fix(@angular/build): support incremental asset updates and output cleanup in library watch mode

Ensure the library builder properly handles created, modified, and deleted assets during watch mode rebuilds, and removes stale bundle and manifest output files when entry points or exports change. Also normalize paths across the library builder pipeline to POSIX format.

Author: alan-agius4

packages/angular/build/src/builders/library/builder.ts

@@ -111,13 +111,10 @@ export async function* executeLibraryBuilder(
     );
 
     // Track all referenced compilation files for watch mode
-    const watchedCompilationFiles = new Set<string>([
-      toPosixPath(tsConfigPath),
-      toPosixPath(packageJsonPath),
-    ]);
+    const watchedCompilationFiles = new Set<string>([tsConfigPath, packageJsonPath]);
 
     for (const entryPoint of normalizedOptions.entryPoints.values()) {
-      watchedCompilationFiles.add(toPosixPath(entryPoint.entryFilePath));
+      watchedCompilationFiles.add(entryPoint.entryFilePath);
     }
 
     if (isWatchMode) {
@@ -130,7 +127,10 @@ export async function* executeLibraryBuilder(
         poll,
         preserveSymlinks,
         signal,
-        watchFiles: watchedCompilationFiles,
+        watchFiles: [
+          ...watchedCompilationFiles,
+          ...normalizedOptions.assets.map((asset) => asset.input),
+        ],
       });
 
       context.addTeardown?.(() => void watcher?.close());
@@ -227,16 +227,27 @@ async function executeBuild(
     if (watcher) {
       watcher.add(Array.from(watchedCompilationFiles));
 
-      const { assetsToEmit } = actionContext;
-      if (assetsToEmit?.length) {
-        watcher.add(assetsToEmit.map((asset) => asset.source));
+      const { collectedAssets } = actionContext;
+      if (collectedAssets?.filesToEmit.length) {
+        watcher.add(collectedAssets.filesToEmit.map((asset) => asset.source));
       }
     }
   }
 }
 
 /**
  * Runs the watch loop, rebuilding the library as watched files are modified.
+ *
+ * @param watcher The file watcher instance.
+ * @param options The normalized library builder options with POSIX paths.
+ * @param stylesheetBundler The component stylesheet bundler instance.
+ * @param watchedCompilationFiles Set of POSIX file paths tracked for compilation.
+ * @param context The Architect builder context.
+ * @param withProgress Progress wrapper function (`withSpinner` or `withNoProgress`).
+ * @param buildState The state preserved across incremental builds.
+ * @param buildAction The library build action function to execute.
+ * @param hasModifiedWatchedFile Helper to check whether watched compilation files changed.
+ * @param signal Optional abort signal to terminate the watch loop.
  */
 async function* runWatchLoop(
   watcher: BuildWatcher,
@@ -253,7 +264,6 @@ async function* runWatchLoop(
   const { collectAssetsToEmit } = await import('./pipeline/assets');
 
   const { workspaceRoot, packageJsonPath, assets, clearScreen } = options;
-  const posixPackageJsonPath = toPosixPath(packageJsonPath);
 
   for await (const changes of watcher) {
     if (signal?.aborted) {
@@ -293,13 +303,13 @@ async function* runWatchLoop(
 
     // Check if package.json was modified
     let hasPackageJsonChanges = false;
-    if (changedFiles.has(posixPackageJsonPath)) {
+    if (changedFiles.has(packageJsonPath)) {
       try {
         const packageJson = await loadPackageJson(packageJsonPath);
-        options.packageJson = packageJson;
         if (!packageJson.name) {
           throw new Error(`The package.json at '${packageJsonPath}' must contain a 'name'.`);
         }
+        options.packageJson = packageJson;
         options.packageName = packageJson.name;
 
         updateWatchedEntryPoints(
@@ -328,15 +338,21 @@ async function* runWatchLoop(
       !buildState.singleProgramCache ||
       buildState.hasCompilationError ||
       buildState.hasEntryPointsChanges ||
-      hasModifiedWatchedFile(changedFiles, watchedCompilationFiles, posixPackageJsonPath);
+      hasModifiedWatchedFile(changedFiles, watchedCompilationFiles, packageJsonPath);
 
-    const assetsToEmit = await collectAssetsToEmit(
+    const collectedAssets = await collectAssetsToEmit(
       assets,
       workspaceRoot,
       buildState.hasEmittedAssets ? changedFiles : undefined,
+      buildState.emittedAssets,
     );
 
-    if (!hasSourceChanges && !hasPackageJsonChanges && assetsToEmit.length === 0) {
+    if (
+      !hasSourceChanges &&
+      !hasPackageJsonChanges &&
+      collectedAssets.filesToEmit.length === 0 &&
+      collectedAssets.filesToDelete.length === 0
+    ) {
       continue;
     }
 
@@ -350,7 +366,7 @@ async function* runWatchLoop(
         context,
         buildState,
         modifiedFiles: changedFiles,
-        assetsToEmit,
+        collectedAssets,
       },
       withProgress,
       watcher,
@@ -388,7 +404,7 @@ function logMessages(
  * @param logger The Architect logger API.
  * @param startTime High-resolution timestamp recorded when the build iteration started.
  * @param success Whether the build iteration succeeded without errors.
- * @param outputPath Optional output directory path to log on successful builds.
+ * @param outputPath Optional POSIX output directory path to log on successful builds.
  */
 function logBuildResult(
   logger: logging.LoggerApi,

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

@@ -13,6 +13,7 @@ import { normalizeAssetPatterns } from '../../utils';
 import { supportColor } from '../../utils/color';
 import { assertIsError } from '../../utils/error';
 import { normalizeCacheOptions } from '../../utils/normalize-cache';
+import { toPosixPath } from '../../utils/path';
 import {
   generateSearchDirectories,
   getTailwindConfig,
@@ -24,14 +25,25 @@ import { loadPackageJson } from './pipeline/utils';
 import type { Schema as LibraryBuilderOptions } from './schema';
 import type { NormalizedLibraryOptions, PackageJsonData } from './types';
 
+/**
+ * Normalizes raw library builder options into {@link NormalizedLibraryOptions} with all
+ * file and directory paths normalized to POSIX format.
+ *
+ * @param context The Architect builder context.
+ * @param projectName The name of the library project.
+ * @param options The raw library builder schema options.
+ * @returns A promise resolving to the normalized library options.
+ */
 export async function normalizeLibraryOptions(
   context: BuilderContext,
   projectName: string,
   options: LibraryBuilderOptions,
 ): Promise<NormalizedLibraryOptions> {
-  const { workspaceRoot } = context;
+  const workspaceRoot = toPosixPath(context.workspaceRoot);
   const projectMetadata = await context.getProjectMetadata(projectName);
-  const { projectRoot, projectSourceRoot } = getProjectRootPaths(workspaceRoot, projectMetadata);
+  const projectRootPaths = getProjectRootPaths(workspaceRoot, projectMetadata);
+  const projectRoot = toPosixPath(projectRootPaths.projectRoot);
+  const projectSourceRoot = toPosixPath(projectRootPaths.projectSourceRoot);
 
   const {
     tsConfig,
@@ -50,8 +62,8 @@ export async function normalizeLibraryOptions(
     clearScreen,
   } = options;
 
-  const resolvedTsConfigPath = path.resolve(workspaceRoot, tsConfig);
-  const packageJsonPath = path.join(projectRoot, 'package.json');
+  const resolvedTsConfigPath = toPosixPath(path.resolve(workspaceRoot, tsConfig));
+  const packageJsonPath = path.posix.join(projectRoot, 'package.json');
 
   let packageJson: PackageJsonData;
   try {
@@ -99,7 +111,7 @@ export async function normalizeLibraryOptions(
     }
     defaultAssets.push({
       glob: 'README.md',
-      input: path.dirname(entryPoint.entryFilePath),
+      input: path.posix.dirname(entryPoint.entryFilePath),
       output: entryPoint.name,
     });
   }
@@ -109,7 +121,11 @@ export async function normalizeLibraryOptions(
     workspaceRoot,
     projectRoot,
     projectSourceRoot,
-  );
+  ).map((asset) => ({
+    ...asset,
+    input: toPosixPath(path.resolve(workspaceRoot, asset.input)),
+    output: toPosixPath(asset.output),
+  }));
 
   const cacheOptions = normalizeCacheOptions(
     projectMetadata,
@@ -119,7 +135,7 @@ export async function normalizeLibraryOptions(
   );
 
   const styleIncludePaths = (stylePreprocessorOptions?.includePaths ?? []).map((p: string) =>
-    path.resolve(workspaceRoot, p),
+    toPosixPath(path.resolve(workspaceRoot, p)),
   );
 
   const searchDirectories = await generateSearchDirectories([projectRoot, workspaceRoot]);
@@ -133,7 +149,9 @@ export async function normalizeLibraryOptions(
     projectRoot,
     packageName,
     packageJson,
-    outputPath: path.resolve(workspaceRoot, options.outputPath ?? path.join('dist', projectName)),
+    outputPath: toPosixPath(
+      path.resolve(workspaceRoot, options.outputPath ?? path.posix.join('dist', projectName)),
+    ),
     deleteOutputPath,
     packageJsonPath,
     tsConfigPath: resolvedTsConfigPath,

packages/angular/build/src/builders/library/pipeline/assets.ts

@@ -9,69 +9,115 @@
 import { statSync } from 'node:fs';
 import path from 'node:path';
 import picomatch from 'picomatch';
-import { toPosixPath } from '../../../utils/path';
 import { DEFAULT_ASSET_IGNORE, resolveAssets } from '../../../utils/resolve-assets';
 import type { NormalizedLibraryOptions } from '../types';
 import { type DiskOutputFile, createDiskOutputFile } from './utils';
 
 /**
- * Resolves and collects configured library assets to be emitted to disk.
+ * Result of resolving and collecting library assets for a build iteration.
+ */
+export interface CollectedAssets {
+  /** Asset files to emit to disk, with POSIX source and destination paths. */
+  filesToEmit: DiskOutputFile[];
+
+  /** Previously emitted asset files whose source files were deleted and should be removed from output. */
+  filesToDelete: DiskOutputFile[];
+}
+
+interface AssetMatcher {
+  asset: NormalizedLibraryOptions['assets'][number];
+  posixInputPrefix: string;
+  isMatch: picomatch.Matcher;
+}
+
+const assetMatcherCache = new WeakMap<NormalizedLibraryOptions['assets'], AssetMatcher[]>();
+
+/**
+ * Resolves and collects configured library assets to be emitted to or deleted from disk.
  *
- * @param assets The normalized asset patterns.
- * @param workspaceRoot The workspace root directory path.
- * @param modifiedFiles Optional set of modified file paths for incremental copying in watch mode.
- * @returns An array of disk file emission descriptors.
+ * @param assets The normalized asset patterns with POSIX input and output paths.
+ * @param workspaceRoot The workspace root POSIX directory path.
+ * @param modifiedFiles Optional set of modified POSIX file paths for incremental copying in watch mode.
+ * @param emittedAssets Optional map of previously emitted POSIX source file paths to relative POSIX output paths.
+ * @returns The collected asset files to emit and delete.
  */
 export async function collectAssetsToEmit(
   assets: NormalizedLibraryOptions['assets'],
   workspaceRoot: string,
   modifiedFiles?: ReadonlySet<string>,
-): Promise<DiskOutputFile[]> {
+  emittedAssets?: ReadonlyMap<string, string>,
+): Promise<CollectedAssets> {
   if (assets.length === 0 || modifiedFiles?.size === 0) {
-    return [];
+    return { filesToEmit: [], filesToDelete: [] };
   }
 
   if (modifiedFiles) {
-    const matchers = createAssetMatchers(assets, workspaceRoot);
+    const matchers = getAssetMatchers(assets);
     const filesToEmit: DiskOutputFile[] = [];
+    const filesToDelete: DiskOutputFile[] = [];
 
     for (const file of modifiedFiles) {
-      const resolvedFile = path.isAbsolute(file) ? file : path.resolve(workspaceRoot, file);
-      const posixFile = toPosixPath(resolvedFile);
+      let isFile: boolean | undefined;
+
+      const previousOutput = emittedAssets?.get(file);
+      if (previousOutput !== undefined) {
+        isFile = statSync(file, { throwIfNoEntry: false })?.isFile() ?? false;
+        if (!isFile) {
+          filesToDelete.push(createDiskOutputFile(file, previousOutput));
+          continue;
+        }
+      }
 
       for (const { asset, posixInputPrefix, isMatch } of matchers) {
-        if (!posixFile.startsWith(posixInputPrefix)) {
+        if (!file.startsWith(posixInputPrefix)) {
           continue;
         }
 
-        const relative = posixFile.slice(posixInputPrefix.length);
+        const relative = file.slice(posixInputPrefix.length);
         if (!isMatch(relative)) {
           continue;
         }
 
-        if (statSync(resolvedFile, { throwIfNoEntry: false })?.isFile()) {
-          filesToEmit.push(createDiskOutputFile(resolvedFile, path.join(asset.output, relative)));
+        isFile ??= statSync(file, { throwIfNoEntry: false })?.isFile() ?? false;
+        if (isFile) {
+          filesToEmit.push(createDiskOutputFile(file, path.posix.join(asset.output, relative)));
         }
       }
     }
 
-    return filesToEmit;
+    return { filesToEmit, filesToDelete };
   }
 
   const resolvedAssets = await resolveAssets(assets, workspaceRoot);
 
-  return resolvedAssets.map(({ source, destination }) => createDiskOutputFile(source, destination));
+  return {
+    filesToEmit: resolvedAssets.map(({ source, destination }) =>
+      createDiskOutputFile(source, destination),
+    ),
+    filesToDelete: [],
+  };
 }
 
-function createAssetMatchers(assets: NormalizedLibraryOptions['assets'], workspaceRoot: string) {
-  return assets.map((asset) => {
-    const absInput = path.resolve(workspaceRoot, asset.input);
-    const posixInput = toPosixPath(absInput).replace(/\/+$/, '');
-    const isMatch = picomatch(asset.glob, {
-      dot: true,
-      ignore: [...DEFAULT_ASSET_IGNORE, ...(asset.ignore ?? [])],
+/**
+ * Returns cached or newly compiled picomatch matchers and POSIX input prefixes for each asset configuration.
+ *
+ * @param assets The normalized asset patterns with POSIX input and output paths.
+ * @returns An array of asset matcher descriptors.
+ */
+function getAssetMatchers(assets: NormalizedLibraryOptions['assets']): AssetMatcher[] {
+  let matchers = assetMatcherCache.get(assets);
+  if (!matchers) {
+    matchers = assets.map((asset) => {
+      const posixInput = asset.input.replace(/\/+$/, '');
+      const isMatch = picomatch(asset.glob, {
+        dot: true,
+        ignore: [...DEFAULT_ASSET_IGNORE, ...(asset.ignore ?? [])],
+      });
+
+      return { asset, posixInputPrefix: `${posixInput}/`, isMatch };
     });
+    assetMatcherCache.set(assets, matchers);
+  }
 
-    return { asset, posixInputPrefix: `${posixInput}/`, isMatch };
-  });
+  return matchers;
 }