fix(@angular/build): support incremental build file results in watch mode

When the application build is in watch mode, incremental build results will
now be generated. This allows fine-grained updates of the files in the output
directory and supports removal of stale application code files.
Note that stale assets will not currently be removed from the output directory.
More complex asset change analysis will be evaluated for inclusion in the future
to address this asset output behavior.

Author: clydin

packages/angular/build/src/builders/application/build-action.ts

@@ -16,7 +16,14 @@ import { logMessages, withNoProgress, withSpinner } from '../../tools/esbuild/ut
 import { shouldWatchRoot } from '../../utils/environment-options';
 import { NormalizedCachedOptions } from '../../utils/normalize-cache';
 import { NormalizedApplicationBuildOptions, NormalizedOutputOptions } from './options';
-import { ComponentUpdateResult, FullResult, Result, ResultKind, ResultMessage } from './results';
+import {
+  ComponentUpdateResult,
+  FullResult,
+  IncrementalResult,
+  Result,
+  ResultKind,
+  ResultMessage,
+} from './results';
 
 // Watch workspace for package manager changes
 const packageWatchFiles = [
@@ -49,6 +56,7 @@ export async function* runEsBuildBuildAction(
     clearScreen?: boolean;
     colors?: boolean;
     jsonLogs?: boolean;
+    incrementalResults?: boolean;
   },
 ): AsyncIterable<Result> {
   const {
@@ -65,6 +73,7 @@ export async function* runEsBuildBuildAction(
     preserveSymlinks,
     colors,
     jsonLogs,
+    incrementalResults,
   } = options;
 
   const withProgress: typeof withSpinner = progress ? withSpinner : withNoProgress;
@@ -135,7 +144,7 @@ export async function* runEsBuildBuildAction(
   // Output the first build results after setting up the watcher to ensure that any code executed
   // higher in the iterator call stack will trigger the watcher. This is particularly relevant for
   // unit tests which execute the builder and modify the file system programmatically.
-  yield await emitOutputResult(result, outputOptions);
+  yield* emitOutputResults(result, outputOptions);
 
   // Finish if watch mode is not enabled
   if (!watcher) {
@@ -162,9 +171,8 @@ export async function* runEsBuildBuildAction(
       // Clear removed files from current watch files
       changes.removed.forEach((removedPath) => currentWatchFiles.delete(removedPath));
 
-      result = await withProgress('Changes detected. Rebuilding...', () =>
-        action(result.createRebuildState(changes)),
-      );
+      const rebuildState = result.createRebuildState(changes);
+      result = await withProgress('Changes detected. Rebuilding...', () => action(rebuildState));
 
       // Log all diagnostic (error/warning/logs) messages
       await logMessages(logger, result, colors, jsonLogs);
@@ -188,7 +196,11 @@ export async function* runEsBuildBuildAction(
         watcher.remove([...staleWatchFiles]);
       }
 
-      yield await emitOutputResult(result, outputOptions);
+      yield* emitOutputResults(
+        result,
+        outputOptions,
+        incrementalResults ? rebuildState.previousOutputHashes : undefined,
+      );
     }
   } finally {
     // Stop the watcher and cleanup incremental rebuild state
@@ -198,7 +210,7 @@ export async function* runEsBuildBuildAction(
   }
 }
 
-async function emitOutputResult(
+async function* emitOutputResults(
   {
     outputFiles,
     assetFiles,
@@ -210,32 +222,113 @@ async function emitOutputResult(
     templateUpdates,
   }: ExecutionResult,
   outputOptions: NormalizedApplicationBuildOptions['outputOptions'],
-): Promise<Result> {
+  previousOutputHashes?: ReadonlyMap<string, string>,
+): AsyncIterable<Result> {
   if (errors.length > 0) {
-    return {
+    yield {
       kind: ResultKind.Failure,
       errors: errors as ResultMessage[],
       warnings: warnings as ResultMessage[],
       detail: {
         outputOptions,
       },
     };
+
+    // Only one failure result if there are errors
+    return;
   }
 
-  // Template updates only exist if no other changes have occurred
-  if (templateUpdates?.size) {
+  // Template updates only exist if no other JS changes have occurred
+  const hasTemplateUpdates = !!templateUpdates?.size;
+  if (hasTemplateUpdates) {
     const updateResult: ComponentUpdateResult = {
       kind: ResultKind.ComponentUpdate,
-      updates: Array.from(templateUpdates).map(([id, content]) => ({
+      updates: Array.from(templateUpdates, ([id, content]) => ({
         type: 'template',
         id,
         content,
       })),
     };
 
-    return updateResult;
+    yield updateResult;
+  }
+
+  // Use an incremental result if previous output information is available
+  if (previousOutputHashes) {
+    const incrementalResult: IncrementalResult = {
+      kind: ResultKind.Incremental,
+      warnings: warnings as ResultMessage[],
+      added: [],
+      removed: [],
+      modified: [],
+      files: {},
+      detail: {
+        externalMetadata,
+        htmlIndexPath,
+        htmlBaseHref,
+        outputOptions,
+      },
+    };
+
+    // Initially assume all previous output files have been removed
+    const removedOutputFiles = new Set(previousOutputHashes.keys());
+
+    for (const file of outputFiles) {
+      removedOutputFiles.delete(file.path);
+
+      // Temporarily ignore JS files until Angular compiler plugin refactor to allow
+      // bypassing application code bundling for template affecting only changes.
+      // TODO: Remove once refactor is complete.
+      if (hasTemplateUpdates && /\.[cm]?js$/.test(file.path)) {
+        continue;
+      }
+
+      const previousHash = previousOutputHashes.get(file.path);
+      let needFile = false;
+      if (previousHash === undefined) {
+        needFile = true;
+        incrementalResult.added.push(file.path);
+      } else if (previousHash !== file.hash) {
+        needFile = true;
+        incrementalResult.modified.push(file.path);
+      }
+
+      if (needFile) {
+        incrementalResult.files[file.path] = {
+          type: file.type,
+          contents: file.contents,
+          origin: 'memory',
+          hash: file.hash,
+        };
+      }
+    }
+
+    // Include the removed output files
+    incrementalResult.removed.push(
+      ...Array.from(removedOutputFiles, (file) => ({
+        path: file,
+        // FIXME: use actual file type
+        type: BuildOutputFileType.Browser,
+      })),
+    );
+
+    // Always consider asset files as added to ensure new/modified assets are available.
+    // TODO: Consider more comprehensive asset analysis.
+    for (const file of assetFiles) {
+      incrementalResult.added.push(file.destination);
+      incrementalResult.files[file.destination] = {
+        type: BuildOutputFileType.Browser,
+        inputPath: file.source,
+        origin: 'disk',
+      };
+    }
+
+    yield incrementalResult;
+
+    return;
   }
 
+  // Otherwise, use a full result
   const result: FullResult = {
     kind: ResultKind.Full,
     warnings: warnings as ResultMessage[],
@@ -263,5 +356,5 @@ async function emitOutputResult(
     };
   }
 
-  return result;
+  yield result;
 }

packages/angular/build/src/builders/application/index.ts

@@ -25,7 +25,7 @@ import {
   NormalizedOutputOptions,
   normalizeOptions,
 } from './options';
-import { Result, ResultKind } from './results';
+import { Result, ResultFile, ResultKind } from './results';
 import { Schema as ApplicationBuilderOptions } from './schema';
 
 export type { ApplicationBuilderOptions };
@@ -126,6 +126,7 @@ export async function* buildApplicationInternal(
       clearScreen: normalizedOptions.clearScreen,
       colors: normalizedOptions.colors,
       jsonLogs: normalizedOptions.jsonLogs,
+      incrementalResults: normalizedOptions.incrementalResults,
       logger,
       signal,
     },
@@ -157,7 +158,8 @@ export async function* buildApplication(
   extensions?: ApplicationBuilderExtensions,
 ): AsyncIterable<ApplicationBuilderOutput> {
   let initial = true;
-  for await (const result of buildApplicationInternal(options, context, extensions)) {
+  const internalOptions = { ...options, incrementalResults: true };
+  for await (const result of buildApplicationInternal(internalOptions, context, extensions)) {
     const outputOptions = result.detail?.['outputOptions'] as NormalizedOutputOptions | undefined;
 
     if (initial) {
@@ -179,7 +181,10 @@ export async function* buildApplication(
     }
 
     assert(outputOptions, 'Application output options are required for builder usage.');
-    assert(result.kind === ResultKind.Full, 'Application build did not provide a full output.');
+    assert(
+      result.kind === ResultKind.Full || result.kind === ResultKind.Incremental,
+      'Application build did not provide a file result output.',
+    );
 
     // TODO: Restructure output logging to better handle stdout JSON piping
     if (!useJSONBuildLogs) {
@@ -197,26 +202,7 @@ export async function* buildApplication(
         return;
       }
 
-      let typeDirectory: string;
-      switch (file.type) {
-        case BuildOutputFileType.Browser:
-        case BuildOutputFileType.Media:
-          typeDirectory = outputOptions.browser;
-          break;
-        case BuildOutputFileType.ServerApplication:
-        case BuildOutputFileType.ServerRoot:
-          typeDirectory = outputOptions.server;
-          break;
-        case BuildOutputFileType.Root:
-          typeDirectory = '';
-          break;
-        default:
-          throw new Error(
-            `Unhandled write for file "${filePath}" with type "${BuildOutputFileType[file.type]}".`,
-          );
-      }
-      // NOTE: 'base' is a fully resolved path at this point
-      const fullFilePath = path.join(outputOptions.base, typeDirectory, filePath);
+      const fullFilePath = generateFullPath(filePath, file.type, outputOptions);
 
       // Ensure output subdirectories exist
       const fileBasePath = path.dirname(fullFilePath);
@@ -234,8 +220,48 @@ export async function* buildApplication(
       }
     });
 
+    // Delete any removed files if incremental
+    if (result.kind === ResultKind.Incremental && result.removed?.length) {
+      await Promise.all(
+        result.removed.map((file) => {
+          const fullFilePath = generateFullPath(file.path, file.type, outputOptions);
+
+          return fs.rm(fullFilePath, { force: true, maxRetries: 3 });
+        }),
+      );
+    }
+
     yield { success: true };
   }
 }
 
+function generateFullPath(
+  filePath: string,
+  type: BuildOutputFileType,
+  outputOptions: NormalizedOutputOptions,
+) {
+  let typeDirectory: string;
+  switch (type) {
+    case BuildOutputFileType.Browser:
+    case BuildOutputFileType.Media:
+      typeDirectory = outputOptions.browser;
+      break;
+    case BuildOutputFileType.ServerApplication:
+    case BuildOutputFileType.ServerRoot:
+      typeDirectory = outputOptions.server;
+      break;
+    case BuildOutputFileType.Root:
+      typeDirectory = '';
+      break;
+    default:
+      throw new Error(
+        `Unhandled write for file "${filePath}" with type "${BuildOutputFileType[type]}".`,
+      );
+  }
+  // NOTE: 'base' is a fully resolved path at this point
+  const fullFilePath = path.join(outputOptions.base, typeDirectory, filePath);
+
+  return fullFilePath;
+}
+
 export default createBuilder(buildApplication);

packages/angular/build/src/builders/application/options.ts

@@ -107,6 +107,12 @@ interface InternalOptions {
    */
   templateUpdates?: boolean;
 
+  /**
+   * Enables emitting incremental build results when in watch mode. A full build result will only be emitted
+   * for the initial build. This option also requires watch to be enabled to have an effect.
+   */
+  incrementalResults?: boolean;
+
   /**
    * Enables instrumentation to collect code coverage data for specific files.
    *
@@ -475,6 +481,7 @@ export async function normalizeOptions(
     instrumentForCoverage,
     security,
     templateUpdates: !!options.templateUpdates,
+    incrementalResults: !!options.incrementalResults,
   };
 }
 

packages/angular/build/src/builders/application/results.ts

@@ -37,7 +37,7 @@ export interface FullResult extends BaseResult {
 export interface IncrementalResult extends BaseResult {
   kind: ResultKind.Incremental;
   added: string[];
-  removed: string[];
+  removed: { path: string; type: BuildOutputFileType }[];
   modified: string[];
   files: Record<string, ResultFile>;
 }