perf(@angular/build): optimize incremental watch rebuilds in angular compilation

Author: alan-agius4

packages/angular/build/src/tools/angular/compilation/aot-compilation.ts

@@ -41,7 +41,7 @@ class AngularCompilationState {
   constructor(
     public readonly angularProgram: ng.NgtscProgram,
     public readonly compilerHost: ng.CompilerHost,
-    public readonly typeScriptProgram: ts.EmitAndSemanticDiagnosticsBuilderProgram,
+    public typeScriptProgram: ts.EmitAndSemanticDiagnosticsBuilderProgram,
     public readonly affectedFiles: ReadonlySet<ts.SourceFile>,
     public readonly templateDiagnosticsOptimization: ng.OptimizeFor,
     public readonly webWorkerTransform: ts.TransformerFactory<ts.SourceFile>,
@@ -61,6 +61,7 @@ export class AotCompilation extends TypeScriptCompilation {
     super();
   }
 
+  // eslint-disable-next-line max-lines-per-function
   async initialize(
     tsconfig: string,
     hostOptions: AngularHostOptions,
@@ -100,8 +101,8 @@ export class AotCompilation extends TypeScriptCompilation {
     if (hostOptions.modifiedFiles) {
       this.invalidateFiles(hostOptions.modifiedFiles);
 
-      for (const modifiedFile of hostOptions.modifiedFiles) {
-        if (this.#state) {
+      if (this.#state && hostOptions.modifiedFiles.size > 0) {
+        for (const modifiedFile of hostOptions.modifiedFiles) {
           // Clear package.json cache if a node modules file was modified
           if (!clearPackageJsonCache && modifiedFile.includes('node_modules')) {
             clearPackageJsonCache = true;
@@ -117,6 +118,14 @@ export class AotCompilation extends TypeScriptCompilation {
             }
           }
         }
+
+        if (compilerOptions.declaration) {
+          populatePreviousDtsSignatures(
+            this.#state.typeScriptProgram,
+            this.#state.compilerHost,
+            hostOptions.modifiedFiles,
+          );
+        }
       }
     }
 
@@ -207,25 +216,35 @@ export class AotCompilation extends TypeScriptCompilation {
     const componentResourcesDependencies = new Map<string, string[]>();
 
     // Get all files referenced in the TypeScript/Angular program including component resources
-    const referencedFiles = typeScriptProgram
-      .getSourceFiles()
-      .filter((sourceFile) => !angularCompiler.ignoreForEmit.has(sourceFile))
-      .flatMap((sourceFile) => {
-        const resourceDependencies = angularCompiler.getResourceDependencies(sourceFile);
-        componentResourcesDependencies.set(sourceFile.fileName, resourceDependencies);
-        // Also invalidate Angular diagnostics for a source file if component resources are modified
-        if (this.#state && hostOptions.modifiedFiles?.size) {
-          for (const resourceDependency of resourceDependencies) {
-            if (hostOptions.modifiedFiles.has(resourceDependency)) {
-              this.#state.diagnosticCache.delete(sourceFile);
-              // Also mark as affected in case changed template affects diagnostics
-              affectedFiles.add(sourceFile);
-            }
+    const referencedFiles: string[] = [];
+    for (const sourceFile of typeScriptProgram.getSourceFiles()) {
+      if (angularCompiler.ignoreForEmit.has(sourceFile)) {
+        continue;
+      }
+      referencedFiles.push(sourceFile.fileName);
+      if (sourceFile.isDeclarationFile) {
+        continue;
+      }
+      const resourceDependencies = angularCompiler.getResourceDependencies(sourceFile);
+      componentResourcesDependencies.set(sourceFile.fileName, resourceDependencies);
+      if (resourceDependencies.length === 0) {
+        continue;
+      }
+      referencedFiles.push(...resourceDependencies);
+      // Also invalidate Angular diagnostics for a source file if component template resources are modified
+      if (this.#state && hostOptions.modifiedFiles?.size) {
+        for (const resourceDependency of resourceDependencies) {
+          if (
+            hostOptions.modifiedFiles.has(resourceDependency) &&
+            !/\.(?:css|scss|sass|less)$/i.test(resourceDependency)
+          ) {
+            this.#state.diagnosticCache.delete(sourceFile);
+            // Also mark as affected in case changed template affects diagnostics
+            affectedFiles.add(sourceFile);
           }
         }
-
-        return [sourceFile.fileName, ...resourceDependencies];
-      });
+      }
+    }
 
     this.#state = new AngularCompilationState(
       angularProgram,
@@ -261,63 +280,82 @@ export class AotCompilation extends TypeScriptCompilation {
     const syntactic = modes & DiagnosticModes.Syntactic;
     const semantic = modes & DiagnosticModes.Semantic;
 
-    // Collect program level diagnostics
-    if (modes & DiagnosticModes.Option) {
-      yield* typeScriptProgram.getConfigFileParsingDiagnostics();
-      yield* angularCompiler.getOptionDiagnostics();
-      yield* typeScriptProgram.getOptionsDiagnostics();
-    }
-    if (syntactic) {
-      yield* typeScriptProgram.getGlobalDiagnostics();
-    }
-
-    // Collect source file specific diagnostics
-    for (const sourceFile of typeScriptProgram.getSourceFiles()) {
-      if (angularCompiler.ignoreForDiagnostics.has(sourceFile)) {
-        continue;
+    try {
+      // Collect program level diagnostics
+      if (modes & DiagnosticModes.Option) {
+        yield* typeScriptProgram.getConfigFileParsingDiagnostics();
+        yield* angularCompiler.getOptionDiagnostics();
+        yield* typeScriptProgram.getOptionsDiagnostics();
       }
-
       if (syntactic) {
-        // TypeScript will use cached diagnostics for files that have not been
-        // changed or affected for this build when using incremental building.
-        yield* profileSync(
-          'NG_DIAGNOSTICS_SYNTACTIC',
-          () => typeScriptProgram.getSyntacticDiagnostics(sourceFile),
-          true,
-        );
+        yield* typeScriptProgram.getGlobalDiagnostics();
       }
 
-      if (!semantic) {
-        continue;
-      }
+      // Collect source file specific diagnostics
+      for (const sourceFile of typeScriptProgram.getSourceFiles()) {
+        if (angularCompiler.ignoreForDiagnostics.has(sourceFile)) {
+          continue;
+        }
 
-      yield* profileSync(
-        'NG_DIAGNOSTICS_SEMANTIC',
-        () => typeScriptProgram.getSemanticDiagnostics(sourceFile),
-        true,
-      );
+        if (syntactic) {
+          // TypeScript will use cached diagnostics for files that have not been
+          // changed or affected for this build when using incremental building.
+          yield* profileSync(
+            'NG_DIAGNOSTICS_SYNTACTIC',
+            () => typeScriptProgram.getSyntacticDiagnostics(sourceFile),
+            true,
+          );
+        }
 
-      // Declaration files cannot have template diagnostics
-      if (sourceFile.isDeclarationFile) {
-        continue;
-      }
+        if (!semantic) {
+          continue;
+        }
 
-      // Only request Angular template diagnostics for affected files to avoid
-      // overhead of template diagnostics for unchanged files.
-      if (affectedFiles.has(sourceFile)) {
-        const angularDiagnostics = profileSync(
-          'NG_DIAGNOSTICS_TEMPLATE',
-          () => angularCompiler.getDiagnosticsForFile(sourceFile, templateDiagnosticsOptimization),
+        yield* profileSync(
+          'NG_DIAGNOSTICS_SEMANTIC',
+          () => typeScriptProgram.getSemanticDiagnostics(sourceFile),
           true,
         );
-        diagnosticCache.set(sourceFile, angularDiagnostics);
-        yield* angularDiagnostics;
-      } else {
-        const angularDiagnostics = diagnosticCache.get(sourceFile);
-        if (angularDiagnostics) {
+
+        // Declaration files cannot have template diagnostics
+        if (sourceFile.isDeclarationFile) {
+          continue;
+        }
+
+        // Only request Angular template diagnostics for affected files to avoid
+        // overhead of template diagnostics for unchanged files.
+        if (affectedFiles.has(sourceFile)) {
+          const angularDiagnostics = profileSync(
+            'NG_DIAGNOSTICS_TEMPLATE',
+            () =>
+              angularCompiler.getDiagnosticsForFile(sourceFile, templateDiagnosticsOptimization),
+            true,
+          );
+          diagnosticCache.set(sourceFile, angularDiagnostics);
           yield* angularDiagnostics;
+        } else {
+          const angularDiagnostics = diagnosticCache.get(sourceFile);
+          if (angularDiagnostics) {
+            yield* angularDiagnostics;
+          }
         }
       }
+    } finally {
+      // Angular's template typechecker lazily creates `.ngtypecheck.ts` shims in a new `ts.Program`
+      // during `getDiagnosticsForFile`. Sync the builder program with `angularCompiler.getCurrentProgram()`
+      // so the next incremental build does not treat all `.ngtypecheck.ts` files as newly added files.
+      commitBuilderProgramState(typeScriptProgram);
+      const currentTsProgram = angularCompiler.getCurrentProgram();
+      if (currentTsProgram !== typeScriptProgram.getProgram()) {
+        ensureSourceFileVersions(currentTsProgram);
+        const updatedBuilder = ts.createEmitAndSemanticDiagnosticsBuilderProgram(
+          currentTsProgram,
+          this.#state.compilerHost,
+          typeScriptProgram,
+        );
+        commitBuilderProgramState(updatedBuilder);
+        this.#state.typeScriptProgram = updatedBuilder;
+      }
     }
   }
 
@@ -522,3 +560,99 @@ function findAffectedFiles(
 
   return affectedFiles;
 }
+
+interface InternalBuilderProgram extends ts.EmitAndSemanticDiagnosticsBuilderProgram {
+  state?: {
+    fileInfos?: Map<string, { version: string; signature: string | undefined }>;
+    changedFilesSet?: Set<string>;
+    oldSignatures?: Map<string, string | false>;
+    hasCalledUpdateShapeSignature?: Set<string>;
+  };
+}
+
+interface InternalTypeScriptWithBuilderState {
+  BuilderState?: {
+    updateShapeSignature?(
+      state: unknown,
+      program: ts.Program,
+      sourceFile: ts.SourceFile,
+      cancellationToken: ts.CancellationToken | undefined,
+      host: ts.CompilerHost,
+      useFileVersionAsSignature: boolean,
+    ): boolean;
+  };
+}
+
+/**
+ * Commits the internal state of a TypeScript `BuilderProgram` by clearing uncommitted
+ * `oldSignatures` and `changedFilesSet` entries.
+ *
+ * Why this is needed:
+ * TypeScript's `BuilderProgram` only clears `state.oldSignatures` and `state.changedFilesSet`
+ * when `getSemanticDiagnostics()` (whole-program, no arguments) is called. Because Angular's
+ * `collectDiagnostics()` queries `getSemanticDiagnostics(sourceFile)` per-file (skipping
+ * internal `ignoreForDiagnostics` shims), TypeScript leaves `oldSignatures` populated with `false`.
+ * When `BuilderState.create` creates the next `BuilderProgram`, any `false` entry in `oldSignatures`
+ * resets that file's `info.signature` back to `undefined`. Clearing `oldSignatures` and `changedFilesSet`
+ * commits the current build's state so subsequent incremental builds preserve `.d.ts` signatures.
+ */
+function commitBuilderProgramState(program: InternalBuilderProgram): void {
+  program.state?.changedFilesSet?.clear();
+  program.state?.oldSignatures?.clear();
+}
+
+/**
+ * Ensures `.d.ts` shape signatures (`info.signature`) are computed on the previous `BuilderProgram`
+ * for modified files before the next `BuilderProgram` is created.
+ *
+ * Why this is needed:
+ * 1. On the initial build (`oldProgram === undefined`), TypeScript's `BuilderState.create` sets
+ *    `state.useFileVersionAsSignature = true`, which initializes `info.signature = sourceFile.version`
+ *    (the SHA-256 hash of the `.ts` source text).
+ * 2. Normally, during `emitNextAffectedFile()`, TypeScript's `getWriteFileCallback` replaces
+ *    `info.signature` with the hash of the emitted `.d.ts` declaration text. However, TypeScript
+ *    explicitly guards this behind `if (!customTransformers)` (in `ts.createBuilderProgram`).
+ *    Because Angular passes `angularCompiler.prepareEmit().transformers` (`customTransformers`) to
+ *    `emitNextAffectedFile()`, TypeScript skips updating `info.signature`, leaving it equal to the
+ *    `.ts` file hash (`sourceFile.version`).
+ * 3. On the first incremental watch rebuild (`oldProgram !== undefined`), `useFileVersionAsSignature`
+ *    becomes `false` and TypeScript calls `BuilderState.updateShapeSignature()` (`computeDtsSignature`)
+ *    for each modified file, comparing the newly computed `.d.ts` hash against the previous build's
+ *    `info.signature` (which is still the `.ts` hash). Because a `.d.ts` hash never matches a `.ts`
+ *    hash, TypeScript falsely concludes that the file's public `.d.ts` shape changed and cascades
+ *    re-analysis and re-emission across all transitive importers in `referencedMap`.
+ * 4. Calling `BuilderState.updateShapeSignature(..., false)` on the previous program when a modified
+ *    file's `signature` is still equal to its `version` replaces the initial `.ts` version hash with
+ *    its true `.d.ts` signature prior to diffing, preventing false-positive `.d.ts` cascades on watch edits.
+ */
+function populatePreviousDtsSignatures(
+  oldProgram: InternalBuilderProgram,
+  oldHost: ts.CompilerHost,
+  modifiedFiles: ReadonlySet<string>,
+): void {
+  const updateShapeSignature = (ts as InternalTypeScriptWithBuilderState).BuilderState
+    ?.updateShapeSignature;
+  const oldState = oldProgram.state;
+  if (!updateShapeSignature || !oldState?.fileInfos) {
+    return;
+  }
+
+  const program = oldProgram.getProgram();
+  for (const modifiedFile of modifiedFiles) {
+    const sf = program.getSourceFile(modifiedFile);
+    if (!sf || sf.isDeclarationFile) {
+      continue;
+    }
+
+    const resolvedPath =
+      (sf as ts.SourceFile & { resolvedPath?: string }).resolvedPath ?? modifiedFile;
+    const fileInfo = oldState.fileInfos.get(resolvedPath);
+    if (!fileInfo || fileInfo.signature !== fileInfo.version) {
+      continue;
+    }
+
+    oldState.hasCalledUpdateShapeSignature?.delete(resolvedPath);
+    updateShapeSignature(oldState, program, sf, undefined, oldHost, false);
+  }
+  oldState.oldSignatures?.clear();
+}

packages/angular/build/src/tools/angular/compilation/typescript-compilation.ts

@@ -24,6 +24,7 @@ export interface TransformedConfiguration {
 
 export abstract class TypeScriptCompilation extends AngularCompilation {
   static #angularCompilerCliModule?: typeof ng;
+  #cachedConfiguration?: TransformedConfiguration;
 
   static async loadCompilerCli(): Promise<typeof ng> {
     TypeScriptCompilation.#angularCompilerCliModule ??= await import('@angular/compiler-cli');
@@ -35,6 +36,12 @@ export abstract class TypeScriptCompilation extends AngularCompilation {
     tsconfig: string,
     compilerOptionOverrides?: CompilerOptionOverrides,
   ): Promise<TransformedConfiguration> {
+    // When `rootFiles` are explicitly provided (e.g., library builder), avoid re-parsing `tsconfig.json`
+    // and walking the project directory tree via `readConfiguration` on every watch rebuild (~200-350ms on large libraries).
+    if (compilerOptionOverrides?.rootFiles?.length && this.#cachedConfiguration) {
+      return this.#cachedConfiguration;
+    }
+
     const { readConfiguration } = await TypeScriptCompilation.loadCompilerCli();
 
     const {
@@ -80,19 +87,30 @@ export abstract class TypeScriptCompilation extends AngularCompilation {
       tsconfig,
     );
 
-    return {
+    const config: TransformedConfiguration = {
       compilerOptions,
       rootNames,
       errors,
       warnings,
     };
+
+    if (compilerOptionOverrides?.rootFiles?.length) {
+      this.#cachedConfiguration = config;
+    }
+
+    return config;
   }
 
   protected readonly sourceFiles = new Map<string, ts.SourceFile>();
 
   protected invalidateFiles(files: Iterable<string>): void {
     for (const file of files) {
-      this.sourceFiles.delete(toPosixPath(file));
+      const posixFile = toPosixPath(file);
+      this.sourceFiles.delete(posixFile);
+      if (posixFile.endsWith('.json')) {
+        // If a tsconfig changes, we need to re-read the configuration.
+        this.#cachedConfiguration = undefined;
+      }
     }
   }