refactor(compiler-cli): extract NgCompilerAdapter interface (angular#37118)

`NgCompiler` is the heart of ngtsc and can be used to analyze and compile
Angular programs in a variety of environments. Most of these integrations
rely on `NgProgram` and the creation of an `NgCompilerHost` in order to
create a `ts.Program` with the right shape for `NgCompiler`.

However, certain environments (such as the Angular Language Service) have
their own mechanisms for creating `ts.Program`s that don't make use of a
`ts.CompilerHost`. In such environments, an `NgCompilerHost` does not make
sense.

This commit breaks the dependency of `NgCompiler` on `NgCompilerHost` and
extracts the specific interface of the host on which `NgCompiler` depends
into a new interface, `NgCompilerAdapter`. This interface includes methods
from `ts.CompilerHost`, the `ExtendedTsCompilerHost`, as well as APIs from
`NgCompilerHost`.

A consumer such as the language service can implement this API without
needing to jump through hoops to create an `NgCompilerHost` implementation
that somehow wraps its specific environment.

PR Close angular#37118

Author: alxhub

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

@@ -20,7 +20,7 @@ ts_library(
         "//packages/compiler-cli/src/ngtsc/reflection",
         "//packages/compiler-cli/src/ngtsc/routing",
         "//packages/compiler-cli/src/ngtsc/scope",
-        "//packages/compiler-cli/src/ngtsc/shims",
+        "//packages/compiler-cli/src/ngtsc/shims:api",
         "//packages/compiler-cli/src/ngtsc/transform",
         "//packages/compiler-cli/src/ngtsc/typecheck",
         "//packages/compiler-cli/src/ngtsc/util",

packages/compiler-cli/src/ngtsc/annotations/src/ng_module.ts

@@ -16,7 +16,7 @@ import {PartialEvaluator, ResolvedValue, ResolvedValueArray} from '../../partial
 import {ClassDeclaration, Decorator, ReflectionHost, reflectObjectLiteral, typeNodeToValueExpr} from '../../reflection';
 import {NgModuleRouteAnalyzer} from '../../routing';
 import {LocalModuleScopeRegistry, ScopeData} from '../../scope';
-import {FactoryTracker} from '../../shims';
+import {FactoryTracker} from '../../shims/api';
 import {AnalysisOutput, CompileResult, DecoratorHandler, DetectResult, HandlerPrecedence, ResolveResult} from '../../transform';
 import {getSourceFile} from '../../util/src/typescript';
 

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

@@ -43,6 +43,7 @@ ts_library(
     srcs = glob(["api/**/*.ts"]),
     deps = [
         "//packages/compiler-cli/src/ngtsc/file_system",
+        "//packages/compiler-cli/src/ngtsc/shims:api",
         "@npm//typescript",
     ],
 )

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

@@ -6,6 +6,7 @@
  * found in the LICENSE file at https://angular.io/license
  */
 
+export * from './src/adapter';
 export * from './src/interfaces';
 export * from './src/options';
 export * from './src/public_options';

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

@@ -0,0 +1,99 @@
+/**
+ * @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 {AbsoluteFsPath} from '../../../file_system';
+import {FactoryTracker} from '../../../shims/api';
+
+import {ExtendedTsCompilerHost, UnifiedModulesHost} from './interfaces';
+
+/**
+ * Names of methods from `ExtendedTsCompilerHost` that need to be provided by the
+ * `NgCompilerAdapter`.
+ */
+export type ExtendedCompilerHostMethods =
+    // Used to normalize filenames for the host system. Important for proper case-sensitive file
+    // handling.
+    'getCanonicalFileName'|
+    // An optional method of `ts.CompilerHost` where an implementer can override module resolution.
+    'resolveModuleNames'|
+    // Retrieve the current working directory. Unlike in `ts.ModuleResolutionHost`, this is a
+    // required method.
+    'getCurrentDirectory'|
+    // Additional methods of `ExtendedTsCompilerHost` related to resource files (e.g. HTML
+    // templates). These are optional.
+    'getModifiedResourceFiles'|'readResource'|'resourceNameToFileName';
+
+/**
+ * Adapter for `NgCompiler` that allows it to be used in various circumstances, such as
+ * command-line `ngc`, as a plugin to `ts_library` in Bazel, or from the Language Service.
+ *
+ * `NgCompilerAdapter` is a subset of the `NgCompilerHost` implementation of `ts.CompilerHost`
+ * which is relied upon by `NgCompiler`. A consumer of `NgCompiler` can therefore use the
+ * `NgCompilerHost` or implement `NgCompilerAdapter` itself.
+ */
+export interface NgCompilerAdapter extends
+    // getCurrentDirectory is removed from `ts.ModuleResolutionHost` because it's optional, and
+    // incompatible with the `ts.CompilerHost` version which isn't. The combination of these two
+    // still satisfies `ts.ModuleResolutionHost`.
+        Omit<ts.ModuleResolutionHost, 'getCurrentDirectory'>,
+    Pick<ExtendedTsCompilerHost, 'getCurrentDirectory'|ExtendedCompilerHostMethods> {
+  /**
+   * A path to a single file which represents the entrypoint of an Angular Package Format library,
+   * if the current program is one.
+   *
+   * This is used to emit a flat module index if requested, and can be left `null` if that is not
+   * required.
+   */
+  readonly entryPoint: AbsoluteFsPath|null;
+
+  /**
+   * An array of `ts.Diagnostic`s that occurred during construction of the `ts.Program`.
+   */
+  readonly constructionDiagnostics: ts.Diagnostic[];
+
+  /**
+   * A `Set` of `ts.SourceFile`s which are internal to the program and should not be emitted as JS
+   * files.
+   *
+   * Often these are shim files such as `ngtypecheck` shims used for template type-checking in
+   * command-line ngc.
+   */
+  readonly ignoreForEmit: Set<ts.SourceFile>;
+
+  /**
+   * A tracker for usage of symbols in `.ngfactory` shims.
+   *
+   * This can be left `null` if such shims are not a part of the `ts.Program`.
+   */
+  readonly factoryTracker: FactoryTracker|null;
+
+  /**
+   * A specialized interface provided in some environments (such as Bazel) which overrides how
+   * import specifiers are generated.
+   *
+   * If not required, this can be `null`.
+   */
+  readonly unifiedModulesHost: UnifiedModulesHost|null;
+
+  /**
+   * Resolved list of root directories explicitly set in, or inferred from, the tsconfig.
+   */
+  readonly rootDirs: ReadonlyArray<AbsoluteFsPath>;
+
+  /**
+   * Distinguishes between shim files added by Angular to the compilation process (both those
+   * intended for output, like ngfactory files, as well as internal shims like ngtypecheck files)
+   * and original files in the user's program.
+   *
+   * This is mostly used to limit type-checking operations to only user files. It should return
+   * `true` if a file was written by the user, and `false` if a file was added by the compiler.
+   */
+  isShim(sf: ts.SourceFile): boolean;
+}

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

@@ -22,19 +22,15 @@ import {ModuleWithProvidersScanner} from '../../modulewithproviders';
 import {PartialEvaluator} from '../../partial_evaluator';
 import {NOOP_PERF_RECORDER, PerfRecorder} from '../../perf';
 import {TypeScriptReflectionHost} from '../../reflection';
-import {HostResourceLoader} from '../../resource';
+import {AdapterResourceLoader} from '../../resource';
 import {entryPointKeyFor, NgModuleRouteAnalyzer} from '../../routing';
 import {ComponentScopeReader, LocalModuleScopeRegistry, MetadataDtsModuleScopeResolver} from '../../scope';
 import {generatedFactoryTransform} from '../../shims';
 import {ivySwitchTransform} from '../../switch';
 import {aliasTransformFactory, declarationTransformFactory, DecoratorHandler, DtsTransformRegistry, ivyTransformFactory, TraitCompiler} from '../../transform';
 import {isTemplateDiagnostic, TemplateTypeChecker, TypeCheckContext, TypeCheckingConfig, TypeCheckingProgramStrategy} from '../../typecheck';
 import {getSourceFileOrNull, isDtsPath, resolveModuleName} from '../../util/src/typescript';
-import {LazyRoute, NgCompilerOptions} from '../api';
-
-import {NgCompilerHost} from './host';
-
-
+import {LazyRoute, NgCompilerAdapter, NgCompilerOptions} from '../api';
 
 /**
  * State information about a compilation which is only generated once some data is requested from
@@ -94,18 +90,18 @@ export class NgCompiler {
   private nextProgram: ts.Program;
   private entryPoint: ts.SourceFile|null;
   private moduleResolver: ModuleResolver;
-  private resourceManager: HostResourceLoader;
+  private resourceManager: AdapterResourceLoader;
   private cycleAnalyzer: CycleAnalyzer;
   readonly incrementalDriver: IncrementalDriver;
   readonly ignoreForDiagnostics: Set<ts.SourceFile>;
   readonly ignoreForEmit: Set<ts.SourceFile>;
 
   constructor(
-      private host: NgCompilerHost, private options: NgCompilerOptions,
+      private adapter: NgCompilerAdapter, private options: NgCompilerOptions,
       private tsProgram: ts.Program,
       private typeCheckingProgramStrategy: TypeCheckingProgramStrategy,
       oldProgram: ts.Program|null = null, private perfRecorder: PerfRecorder = NOOP_PERF_RECORDER) {
-    this.constructionDiagnostics.push(...this.host.diagnostics);
+    this.constructionDiagnostics.push(...this.adapter.constructionDiagnostics);
     const incompatibleTypeCheckOptionsDiagnostic = verifyCompatibleTypeCheckOptions(this.options);
     if (incompatibleTypeCheckOptionsDiagnostic !== null) {
       this.constructionDiagnostics.push(incompatibleTypeCheckOptionsDiagnostic);
@@ -115,18 +111,19 @@ export class NgCompiler {
     this.closureCompilerEnabled = !!this.options.annotateForClosureCompiler;
 
     this.entryPoint =
-        host.entryPoint !== null ? getSourceFileOrNull(tsProgram, host.entryPoint) : null;
+        adapter.entryPoint !== null ? getSourceFileOrNull(tsProgram, adapter.entryPoint) : null;
 
     const moduleResolutionCache = ts.createModuleResolutionCache(
-        this.host.getCurrentDirectory(), fileName => this.host.getCanonicalFileName(fileName));
+        this.adapter.getCurrentDirectory(),
+        fileName => this.adapter.getCanonicalFileName(fileName));
     this.moduleResolver =
-        new ModuleResolver(tsProgram, this.options, this.host, moduleResolutionCache);
-    this.resourceManager = new HostResourceLoader(host, this.options);
+        new ModuleResolver(tsProgram, this.options, this.adapter, moduleResolutionCache);
+    this.resourceManager = new AdapterResourceLoader(adapter, this.options);
     this.cycleAnalyzer = new CycleAnalyzer(new ImportGraph(this.moduleResolver));
 
     let modifiedResourceFiles: Set<string>|null = null;
-    if (this.host.getModifiedResourceFiles !== undefined) {
-      modifiedResourceFiles = this.host.getModifiedResourceFiles() || null;
+    if (this.adapter.getModifiedResourceFiles !== undefined) {
+      modifiedResourceFiles = this.adapter.getModifiedResourceFiles() || null;
     }
 
     if (oldProgram === null) {
@@ -146,9 +143,9 @@ export class NgCompiler {
     setIncrementalDriver(tsProgram, this.incrementalDriver);
 
     this.ignoreForDiagnostics =
-        new Set(tsProgram.getSourceFiles().filter(sf => this.host.isShim(sf)));
+        new Set(tsProgram.getSourceFiles().filter(sf => this.adapter.isShim(sf)));
 
-    this.ignoreForEmit = this.host.ignoreForEmit;
+    this.ignoreForEmit = this.adapter.ignoreForEmit;
   }
 
   /**
@@ -279,7 +276,7 @@ export class NgCompiler {
       const containingFile = this.tsProgram.getRootFileNames()[0];
       const [entryPath, moduleName] = entryRoute.split('#');
       const resolvedModule =
-          resolveModuleName(entryPath, containingFile, this.options, this.host, null);
+          resolveModuleName(entryPath, containingFile, this.options, this.adapter, null);
 
       if (resolvedModule) {
         entryRoute = entryPointKeyFor(resolvedModule.resolvedFileName, moduleName);
@@ -326,8 +323,9 @@ export class NgCompiler {
       afterDeclarations.push(aliasTransformFactory(compilation.traitCompiler.exportStatements));
     }
 
-    if (this.host.factoryTracker !== null) {
-      before.push(generatedFactoryTransform(this.host.factoryTracker.sourceInfo, importRewriter));
+    if (this.adapter.factoryTracker !== null) {
+      before.push(
+          generatedFactoryTransform(this.adapter.factoryTracker.sourceInfo, importRewriter));
     }
     before.push(ivySwitchTransform);
 
@@ -499,7 +497,7 @@ export class NgCompiler {
     const typeCheckSpan = this.perfRecorder.start('typeCheckDiagnostics');
     const diagnostics: ts.Diagnostic[] = [];
     for (const sf of this.tsProgram.getSourceFiles()) {
-      if (sf.isDeclarationFile || this.host.isShim(sf)) {
+      if (sf.isDeclarationFile || this.adapter.isShim(sf)) {
         continue;
       }
 
@@ -600,7 +598,7 @@ export class NgCompiler {
     // Construct the ReferenceEmitter.
     let refEmitter: ReferenceEmitter;
     let aliasingHost: AliasingHost|null = null;
-    if (this.host.unifiedModulesHost === null || !this.options._useHostForImportGeneration) {
+    if (this.adapter.unifiedModulesHost === null || !this.options._useHostForImportGeneration) {
       let localImportStrategy: ReferenceEmitStrategy;
 
       // The strategy used for local, in-project imports depends on whether TS has been configured
@@ -613,7 +611,7 @@ export class NgCompiler {
         // rootDirs logic is in effect - use the `LogicalProjectStrategy` for in-project relative
         // imports.
         localImportStrategy = new LogicalProjectStrategy(
-            reflector, new LogicalFileSystem([...this.host.rootDirs], this.host));
+            reflector, new LogicalFileSystem([...this.adapter.rootDirs], this.adapter));
       } else {
         // Plain relative imports are all that's needed.
         localImportStrategy = new RelativePathStrategy(reflector);
@@ -648,9 +646,9 @@ export class NgCompiler {
         // Then use aliased references (this is a workaround to StrictDeps checks).
         new AliasStrategy(),
         // Then use fileNameToModuleName to emit imports.
-        new UnifiedModulesStrategy(reflector, this.host.unifiedModulesHost),
+        new UnifiedModulesStrategy(reflector, this.adapter.unifiedModulesHost),
       ]);
-      aliasingHost = new UnifiedModulesAliasingHost(this.host.unifiedModulesHost);
+      aliasingHost = new UnifiedModulesAliasingHost(this.adapter.unifiedModulesHost);
     }
 
     const evaluator = new PartialEvaluator(reflector, checker, this.incrementalDriver.depGraph);
@@ -693,7 +691,7 @@ export class NgCompiler {
     const handlers: DecoratorHandler<unknown, unknown, unknown>[] = [
       new ComponentDecoratorHandler(
           reflector, evaluator, metaRegistry, metaReader, scopeReader, scopeRegistry, isCore,
-          this.resourceManager, this.host.rootDirs, this.options.preserveWhitespaces || false,
+          this.resourceManager, this.adapter.rootDirs, this.options.preserveWhitespaces || false,
           this.options.i18nUseExternalIds !== false,
           this.options.enableI18nLegacyMessageIdFormat !== false,
           this.options.i18nNormalizeLineEndingsInICUs, this.moduleResolver, this.cycleAnalyzer,
@@ -721,7 +719,7 @@ export class NgCompiler {
           injectableRegistry),
       new NgModuleDecoratorHandler(
           reflector, evaluator, metaReader, metaRegistry, scopeRegistry, referencesRegistry, isCore,
-          routeAnalyzer, refEmitter, this.host.factoryTracker, defaultImportTracker,
+          routeAnalyzer, refEmitter, this.adapter.factoryTracker, defaultImportTracker,
           this.closureCompilerEnabled, injectableRegistry, this.options.i18nInLocale),
     ];
 
@@ -731,7 +729,7 @@ export class NgCompiler {
 
     const templateTypeChecker = new TemplateTypeChecker(
         this.tsProgram, this.typeCheckingProgramStrategy, traitCompiler,
-        this.getTypeCheckingConfig(), refEmitter, reflector, this.host, this.incrementalDriver);
+        this.getTypeCheckingConfig(), refEmitter, reflector, this.adapter, this.incrementalDriver);
 
     return {
       isCore,

packages/compiler-cli/src/ngtsc/core/src/host.ts

@@ -11,12 +11,12 @@ import * as ts from 'typescript';
 import {ErrorCode, ngErrorCode} from '../../diagnostics';
 import {findFlatIndexEntryPoint, FlatIndexGenerator} from '../../entry_point';
 import {AbsoluteFsPath, resolve} from '../../file_system';
-import {FactoryGenerator, FactoryTracker, isShim, ShimAdapter, ShimReferenceTagger, SummaryGenerator} from '../../shims';
-import {PerFileShimGenerator, TopLevelShimGenerator} from '../../shims/api';
+import {FactoryGenerator, isShim, ShimAdapter, ShimReferenceTagger, SummaryGenerator} from '../../shims';
+import {FactoryTracker, PerFileShimGenerator, TopLevelShimGenerator} from '../../shims/api';
 import {TypeCheckShimGenerator} from '../../typecheck';
 import {normalizeSeparators} from '../../util/src/path';
 import {getRootDirs, isDtsPath, isNonDeclarationTsPath} from '../../util/src/typescript';
-import {ExtendedTsCompilerHost, NgCompilerOptions, UnifiedModulesHost} from '../api';
+import {ExtendedTsCompilerHost, NgCompilerAdapter, NgCompilerOptions, UnifiedModulesHost} from '../api';
 
 // A persistent source of bugs in CompilerHost delegation has been the addition by TS of new,
 // optional methods on ts.CompilerHost. Since these methods are optional, it's not a type error that
@@ -89,10 +89,10 @@ export class DelegatingCompilerHost implements
  * `ExtendedTsCompilerHost` methods whenever present.
  */
 export class NgCompilerHost extends DelegatingCompilerHost implements
-    RequiredCompilerHostDelegations, ExtendedTsCompilerHost {
+    RequiredCompilerHostDelegations, ExtendedTsCompilerHost, NgCompilerAdapter {
   readonly factoryTracker: FactoryTracker|null = null;
   readonly entryPoint: AbsoluteFsPath|null = null;
-  readonly diagnostics: ts.Diagnostic[];
+  readonly constructionDiagnostics: ts.Diagnostic[];
 
   readonly inputFiles: ReadonlyArray<string>;
   readonly rootDirs: ReadonlyArray<AbsoluteFsPath>;
@@ -107,7 +107,7 @@ export class NgCompilerHost extends DelegatingCompilerHost implements
 
     this.factoryTracker = factoryTracker;
     this.entryPoint = entryPoint;
-    this.diagnostics = diagnostics;
+    this.constructionDiagnostics = diagnostics;
     this.inputFiles = [...inputFiles, ...shimAdapter.extraInputFiles];
     this.rootDirs = rootDirs;
   }

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

@@ -11,7 +11,7 @@ ts_library(
     deps = [
         "//packages/compiler-cli/src/ngtsc/diagnostics",
         "//packages/compiler-cli/src/ngtsc/file_system",
-        "//packages/compiler-cli/src/ngtsc/shims",
+        "//packages/compiler-cli/src/ngtsc/shims:api",
         "//packages/compiler-cli/src/ngtsc/util",
         "@npm//@types/node",
         "@npm//typescript",

packages/compiler-cli/src/ngtsc/entry_point/src/generator.ts

@@ -11,7 +11,7 @@
 import * as ts from 'typescript';
 
 import {AbsoluteFsPath, dirname, join} from '../../file_system';
-import {TopLevelShimGenerator} from '../../shims';
+import {TopLevelShimGenerator} from '../../shims/api';
 import {relativePathBetween} from '../../util/src/path';
 
 export class FlatIndexGenerator implements TopLevelShimGenerator {

packages/compiler-cli/src/ngtsc/file_system/src/logical.ts

@@ -59,7 +59,9 @@ export class LogicalFileSystem {
    */
   private cache: Map<AbsoluteFsPath, LogicalProjectPath|null> = new Map();
 
-  constructor(rootDirs: AbsoluteFsPath[], private compilerHost: ts.CompilerHost) {
+  constructor(
+      rootDirs: AbsoluteFsPath[],
+      private compilerHost: Pick<ts.CompilerHost, 'getCanonicalFileName'>) {
     // Make a copy and sort it by length in reverse order (longest first). This speeds up lookups,
     // since there's no need to keep going through the array once a match is found.
     this.rootDirs = rootDirs.concat([]).sort((a, b) => b.length - a.length);