refactor(compiler): split core/api.ts into multiple files (#35885)

This commit splits the ngtsc `core` package's api entrypoint, which
previously was a single `api.ts` file, into an api/ directory with multiple
files. This is done to isolate the parts of the API definitions pertaining
to the public-facing `angularCompilerOptions` field in tsconfig.json into a
single file, which will enable a public API guard test to be added in a
future commit.

PR Close #35885

packages/compiler-cli/src/ngtsc/core/BUILD.bazel

@@ -39,7 +39,7 @@ ts_library(
 
 ts_library(
     name = "api",
-    srcs = ["api.ts"],
+    srcs = glob(["api/**/*.ts"]),
     deps = [
         "@npm//typescript",
     ],

packages/compiler-cli/src/ngtsc/core/api/index.ts

@@ -0,0 +1,11 @@
+/**
+ * @license
+ * Copyright Google Inc. All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+export * from './src/interfaces';
+export * from './src/options';
+export * from './src/public_options';

packages/compiler-cli/src/ngtsc/core/api/src/interfaces.ts

@@ -0,0 +1,65 @@
+/**
+ * @license
+ * Copyright Google Inc. All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+import * as ts from 'typescript';
+
+/**
+ * A host backed by a build system which has a unified view of the module namespace.
+ *
+ * Such a build system supports the `fileNameToModuleName` method provided by certain build system
+ * integrations (such as the integration with Bazel). See the docs on `fileNameToModuleName` for
+ * more details.
+ */
+export interface UnifiedModulesHost {
+  /**
+   * Converts a file path to a module name that can be used as an `import ...`.
+   *
+   * For example, such a host might determine that `/absolute/path/to/monorepo/lib/importedFile.ts`
+   * should be imported using a module specifier of `monorepo/lib/importedFile`.
+   */
+  fileNameToModuleName(importedFilePath: string, containingFilePath: string): string;
+}
+
+/**
+ * A host which additionally tracks and produces "resources" (HTML templates, CSS
+ * files, etc).
+ */
+export interface ResourceHost {
+  /**
+   * Converts a file path for a resource that is used in a source file or another resource
+   * into a filepath.
+   */
+  resourceNameToFileName(resourceName: string, containingFilePath: string): string|null;
+
+  /**
+   * Load a referenced resource either statically or asynchronously. If the host returns a
+   * `Promise<string>` it is assumed the user of the corresponding `Program` will call
+   * `loadNgStructureAsync()`. Returning  `Promise<string>` outside `loadNgStructureAsync()` will
+   * cause a diagnostics diagnostic error or an exception to be thrown.
+   */
+  readResource(fileName: string): Promise<string>|string;
+
+  /**
+   * Get the absolute paths to the changed files that triggered the current compilation
+   * or `undefined` if this is not an incremental build.
+   */
+  getModifiedResourceFiles?(): Set<string>|undefined;
+}
+
+/**
+ * A `ts.CompilerHost` interface which supports some number of optional methods in addition to the
+ * core interface.
+ */
+export interface ExtendedTsCompilerHost extends ts.CompilerHost, Partial<ResourceHost>,
+    Partial<UnifiedModulesHost> {}
+
+export interface LazyRoute {
+  route: string;
+  module: {name: string, filePath: string};
+  referencedModule: {name: string, filePath: string};
+}

packages/compiler-cli/src/ngtsc/core/api/src/options.ts

@@ -0,0 +1,72 @@
+/**
+ * @license
+ * Copyright Google Inc. All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+import * as ts from 'typescript';
+import {BazelAndG3Options, I18nOptions, LegacyNgcOptions, NgcCompatibilityOptions, StrictTemplateOptions} from './public_options';
+
+/**
+ * Non-public options which are useful during testing of the compiler.
+ */
+export interface TestOnlyOptions {
+  /**
+   * Whether to use the CompilerHost's fileNameToModuleName utility (if available) to generate
+   * import module specifiers. This is false by default, and exists to support running ngtsc
+   * within Google. This option is internal and is used by the ng_module.bzl rule to switch
+   * behavior between Bazel and Blaze.
+   *
+   * @internal
+   */
+  _useHostForImportGeneration?: boolean;
+
+  /**
+   * Turn on template type-checking in the Ivy compiler.
+   *
+   * This is an internal flag being used to roll out template type-checking in ngtsc. Turning it on
+   * by default before it's ready might break other users attempting to test the new compiler's
+   * behavior.
+   *
+   * @internal
+   */
+  ivyTemplateTypeCheck?: boolean;
+}
+
+/**
+ * A merged interface of all of the various Angular compiler options, as well as the standard
+ * `ts.CompilerOptions`.
+ *
+ * Also includes a few miscellaneous options.
+ */
+export interface NgCompilerOptions extends ts.CompilerOptions, LegacyNgcOptions, BazelAndG3Options,
+    NgcCompatibilityOptions, StrictTemplateOptions, TestOnlyOptions, I18nOptions {
+  /**
+   * Whether the compiler should avoid generating code for classes that haven't been exported.
+   * This is only active when building with `enableIvy: true`. Defaults to `true`.
+   */
+  compileNonExportedClasses?: boolean;
+
+  /**
+   * Whether to remove blank text nodes from compiled templates. It is `false` by default starting
+   * from Angular 6.
+   */
+  preserveWhitespaces?: boolean;
+
+  /**
+   * Disable TypeScript Version Check.
+   */
+  disableTypeScriptVersionCheck?: boolean;
+
+  /** An option to enable ngtsc's internal performance tracing.
+   *
+   * This should be a path to a JSON file where trace information will be written. An optional 'ts:'
+   * prefix will cause the trace to be written via the TS host instead of directly to the filesystem
+   * (not all hosts support this mode of operation).
+   *
+   * This is currently not exposed to users as the trace format is still unstable.
+   */
+  tracePerformance?: string;
+}

packages/compiler-cli/src/ngtsc/core/api/src/public_options.ts

@@ -6,58 +6,6 @@
  * found in the LICENSE file at https://angular.io/license
  */
 
-import * as ts from 'typescript';
-
-/**
- * A host backed by a build system which has a unified view of the module namespace.
- *
- * Such a build system supports the `fileNameToModuleName` method provided by certain build system
- * integrations (such as the integration with Bazel). See the docs on `fileNameToModuleName` for
- * more details.
- */
-export interface UnifiedModulesHost {
-  /**
-   * Converts a file path to a module name that can be used as an `import ...`.
-   *
-   * For example, such a host might determine that `/absolute/path/to/monorepo/lib/importedFile.ts`
-   * should be imported using a module specifier of `monorepo/lib/importedFile`.
-   */
-  fileNameToModuleName(importedFilePath: string, containingFilePath: string): string;
-}
-
-/**
- * A host which additionally tracks and produces "resources" (HTML templates, CSS
- * files, etc).
- */
-export interface ResourceHost {
-  /**
-   * Converts a file path for a resource that is used in a source file or another resource
-   * into a filepath.
-   */
-  resourceNameToFileName(resourceName: string, containingFilePath: string): string|null;
-
-  /**
-   * Load a referenced resource either statically or asynchronously. If the host returns a
-   * `Promise<string>` it is assumed the user of the corresponding `Program` will call
-   * `loadNgStructureAsync()`. Returning  `Promise<string>` outside `loadNgStructureAsync()` will
-   * cause a diagnostics diagnostic error or an exception to be thrown.
-   */
-  readResource(fileName: string): Promise<string>|string;
-
-  /**
-   * Get the absolute paths to the changed files that triggered the current compilation
-   * or `undefined` if this is not an incremental build.
-   */
-  getModifiedResourceFiles?(): Set<string>|undefined;
-}
-
-/**
- * A `ts.CompilerHost` interface which supports some number of optional methods in addition to the
- * core interface.
- */
-export interface ExtendedTsCompilerHost extends ts.CompilerHost, Partial<ResourceHost>,
-    Partial<UnifiedModulesHost> {}
-
 /**
  * Options supported by the legacy View Engine compiler, which are still consumed by the Angular Ivy
  * compiler for backwards compatibility.
@@ -356,71 +304,3 @@ export interface I18nOptions {
    */
   i18nUseExternalIds?: boolean;
 }
-
-/**
- * Non-public options which are useful during testing of the compiler.
- */
-export interface TestOnlyOptions {
-  /**
-   * Whether to use the CompilerHost's fileNameToModuleName utility (if available) to generate
-   * import module specifiers. This is false by default, and exists to support running ngtsc
-   * within Google. This option is internal and is used by the ng_module.bzl rule to switch
-   * behavior between Bazel and Blaze.
-   *
-   * @internal
-   */
-  _useHostForImportGeneration?: boolean;
-
-  /**
-   * Turn on template type-checking in the Ivy compiler.
-   *
-   * This is an internal flag being used to roll out template type-checking in ngtsc. Turning it on
-   * by default before it's ready might break other users attempting to test the new compiler's
-   * behavior.
-   *
-   * @internal
-   */
-  ivyTemplateTypeCheck?: boolean;
-}
-
-/**
- * A merged interface of all of the various Angular compiler options, as well as the standard
- * `ts.CompilerOptions`.
- *
- * Also includes a few miscellaneous options.
- */
-export interface NgCompilerOptions extends ts.CompilerOptions, LegacyNgcOptions, BazelAndG3Options,
-    NgcCompatibilityOptions, StrictTemplateOptions, TestOnlyOptions, I18nOptions {
-  /**
-   * Whether the compiler should avoid generating code for classes that haven't been exported.
-   * This is only active when building with `enableIvy: true`. Defaults to `true`.
-   */
-  compileNonExportedClasses?: boolean;
-
-  /**
-   * Whether to remove blank text nodes from compiled templates. It is `false` by default starting
-   * from Angular 6.
-   */
-  preserveWhitespaces?: boolean;
-
-  /**
-   * Disable TypeScript Version Check.
-   */
-  disableTypeScriptVersionCheck?: boolean;
-
-  /** An option to enable ngtsc's internal performance tracing.
-   *
-   * This should be a path to a JSON file where trace information will be written. An optional 'ts:'
-   * prefix will cause the trace to be written via the TS host instead of directly to the filesystem
-   * (not all hosts support this mode of operation).
-   *
-   * This is currently not exposed to users as the trace format is still unstable.
-   */
-  tracePerformance?: string;
-}
-
-export interface LazyRoute {
-  route: string;
-  module: {name: string, filePath: string};
-  referencedModule: {name: string, filePath: string};
-}