test(compiler): add a public API guard for the public compiler options (#35885)

This commit adds a public API test which guards against unintentional
changes to the accepted keys in `angularCompilerOptions`.

PR Close #35885

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

@@ -7,7 +7,9 @@
  */
 
 import * as ts from 'typescript';
-import {BazelAndG3Options, I18nOptions, LegacyNgcOptions, NgcCompatibilityOptions, StrictTemplateOptions} from './public_options';
+
+import {BazelAndG3Options, I18nOptions, LegacyNgcOptions, MiscOptions, NgcCompatibilityOptions, StrictTemplateOptions} from './public_options';
+
 
 /**
  * Non-public options which are useful during testing of the compiler.
@@ -33,32 +35,6 @@ export interface TestOnlyOptions {
    * @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.
    *
@@ -69,4 +45,13 @@ export interface NgCompilerOptions extends ts.CompilerOptions, LegacyNgcOptions,
    * This is currently not exposed to users as the trace format is still unstable.
    */
   tracePerformance?: string;
-}
+}
+
+/**
+ * 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, MiscOptions {}

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

@@ -11,6 +11,8 @@
  * compiler for backwards compatibility.
  *
  * These are expected to be removed at some point in the future.
+ *
+ * @publicApi
  */
 export interface LegacyNgcOptions {
   /** generate all possible generated files  */
@@ -82,6 +84,8 @@ export interface LegacyNgcOptions {
  * existing View Engine applications.
  *
  * These are expected to be removed at some point in the future.
+ *
+ * @publicApi
  */
 export interface NgcCompatibilityOptions {
   /**
@@ -116,6 +120,8 @@ export interface NgcCompatibilityOptions {
 
 /**
  * Options related to template type-checking and its strictness.
+ *
+ * @publicApi
  */
 export interface StrictTemplateOptions {
   /**
@@ -239,6 +245,8 @@ export interface StrictTemplateOptions {
 /**
  * Options which control behavior useful for "monorepo" build cases using Bazel (such as the
  * internal Google monorepo, g3).
+ *
+ * @publicApi
  */
 export interface BazelAndG3Options {
   /**
@@ -280,6 +288,8 @@ export interface BazelAndG3Options {
 
 /**
  * Options related to i18n compilation support.
+ *
+ * @publicApi
  */
 export interface I18nOptions {
   /**
@@ -304,3 +314,21 @@ export interface I18nOptions {
    */
   i18nUseExternalIds?: boolean;
 }
+
+/**
+ * Miscellaneous options that don't fall into any other category
+ *
+ * @publicApi
+ */
+export interface MiscOptions {
+  /**
+   * 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;
+
+  /**
+   * Disable TypeScript Version Check.
+   */
+  disableTypeScriptVersionCheck?: boolean;
+}

tools/public_api_guard/BUILD.bazel

@@ -66,7 +66,8 @@ ts_api_guardian_test(
     golden = "angular/tools/public_api_guard/global_utils.d.ts",
 )
 
-# explicit target because the d.ts file is nested in the core and not part of typical public d.ts api
+# explicit target because the d.ts file is nested in the compiler and not part of typical public
+# d.ts api
 ts_api_guardian_test(
     name = "error_code_api",
     actual = "angular/packages/compiler-cli/src/ngtsc/diagnostics/src/error_code.d.ts",
@@ -76,3 +77,15 @@ ts_api_guardian_test(
     ],
     golden = "angular/tools/public_api_guard/error_code.d.ts",
 )
+
+# explicit target because the d.ts file is nested in the compiler and not part of typical public
+# d.ts api
+ts_api_guardian_test(
+    name = "compiler_options_api",
+    actual = "angular/packages/compiler-cli/src/ngtsc/core/api/src/public_options.d.ts",
+    data = [
+        ":compiler_options.d.ts",
+        "//packages/compiler-cli/src/ngtsc/core:api",
+    ],
+    golden = "angular/tools/public_api_guard/compiler_options.d.ts",
+)

tools/public_api_guard/compiler_options.d.ts

@@ -0,0 +1,43 @@
+export interface BazelAndG3Options {
+    annotateForClosureCompiler?: boolean;
+    generateDeepReexports?: boolean;
+}
+
+export interface I18nOptions {
+    enableI18nLegacyMessageIdFormat?: boolean;
+    i18nInLocale?: string;
+    i18nUseExternalIds?: boolean;
+}
+
+export interface LegacyNgcOptions {
+    allowEmptyCodegenFiles?: boolean;
+    flatModuleId?: string;
+    flatModuleOutFile?: string;
+    fullTemplateTypeCheck?: boolean;
+    preserveWhitespaces?: boolean;
+    strictInjectionParameters?: boolean;
+}
+
+export interface MiscOptions {
+    compileNonExportedClasses?: boolean;
+    disableTypeScriptVersionCheck?: boolean;
+}
+
+export interface NgcCompatibilityOptions {
+    enableIvy?: boolean | 'ngtsc';
+    generateNgFactoryShims?: boolean;
+    generateNgSummaryShims?: boolean;
+}
+
+export interface StrictTemplateOptions {
+    strictAttributeTypes?: boolean;
+    strictContextGenerics?: boolean;
+    strictDomEventTypes?: boolean;
+    strictDomLocalRefTypes?: boolean;
+    strictInputTypes?: boolean;
+    strictLiteralTypes?: boolean;
+    strictNullInputTypes?: boolean;
+    strictOutputEventTypes?: boolean;
+    strictSafeNavigationTypes?: boolean;
+    strictTemplates?: boolean;
+}