fix(@angular/build): scope cache directory by project and builder name

Accept optional `projectName` and `builderName` parameters in
`normalizeCacheOptions` to consistently scope `path` and `localPath`
per project and builder across the application, dev-server, library,
ng-packagr, and unit-test builders.

Author: alan-agius4

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

@@ -182,8 +182,12 @@ export async function normalizeOptions(
   const { projectRoot, projectSourceRoot } = getProjectRootPaths(workspaceRoot, projectMetadata);
 
   // Gather persistent caching option and provide a project specific cache location
-  const cacheOptions = normalizeCacheOptions(projectMetadata, workspaceRoot);
-  cacheOptions.path = path.join(cacheOptions.path, projectName);
+  const cacheOptions = normalizeCacheOptions(
+    projectMetadata,
+    workspaceRoot,
+    projectName,
+    context.builder.builderName,
+  );
 
   const i18nOptions: I18nOptions & {
     duplicateTranslationBehavior?: I18NTranslation;

packages/angular/build/src/builders/dev-server/options.ts

@@ -39,7 +39,12 @@ export async function normalizeOptions(
   const projectMetadata = await context.getProjectMetadata(projectName);
   const projectRoot = path.join(workspaceRoot, (projectMetadata.root as string | undefined) ?? '');
 
-  const cacheOptions = normalizeCacheOptions(projectMetadata, workspaceRoot);
+  const cacheOptions = normalizeCacheOptions(
+    projectMetadata,
+    workspaceRoot,
+    projectName,
+    context.builder.builderName,
+  );
 
   // Target specifier defaults to the current project's build target using a development configuration
   const buildTargetSpecifier = options.buildTarget ?? `::development`;

packages/angular/build/src/builders/dev-server/vite/server.ts

@@ -167,7 +167,6 @@ export async function setupServer(
     externalMetadata.explicitBrowser.length === 0 && ssrMode === ServerSsrMode.NoSsr;
   const cacheDir = join(
     serverOptions.cacheOptions.localPath ?? serverOptions.cacheOptions.path,
-    serverOptions.buildTarget.project,
     'vite',
   );
 

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

@@ -112,7 +112,12 @@ export async function normalizeLibraryOptions(
     projectSourceRoot,
   );
 
-  const cacheOptions = normalizeCacheOptions(projectMetadata, workspaceRoot);
+  const cacheOptions = normalizeCacheOptions(
+    projectMetadata,
+    workspaceRoot,
+    projectName,
+    context.builder.builderName,
+  );
 
   const styleIncludePaths = (stylePreprocessorOptions?.includePaths ?? []).map((p: string) =>
     path.resolve(workspaceRoot, p),

packages/angular/build/src/builders/ng-packagr/builder.ts

@@ -66,12 +66,14 @@ export async function* execute(
   const { enabled: cacheEnabled, path: cacheDirectory } = normalizeCacheOptions(
     metadata,
     context.workspaceRoot,
+    projectName,
+    context.builder.builderName,
   );
 
   const ngPackagrOptions: NgPackagrOptions = {
     cacheEnabled,
     poll: options.poll,
-    cacheDirectory: join(cacheDirectory, 'ng-packagr'),
+    cacheDirectory: cacheDirectory,
   };
 
   try {

packages/angular/build/src/builders/unit-test/builder.ts

@@ -340,7 +340,7 @@ export async function* execute(
     } satisfies ApplicationBuilderInternalOptions;
 
     const dumpDirectory = normalizedOptions.dumpVirtualFiles
-      ? path.join(normalizedOptions.cacheOptions.path, 'unit-test', 'output-files')
+      ? path.join(normalizedOptions.cacheOptions.path, 'output-files')
       : undefined;
 
     yield* runBuildAndTest(

packages/angular/build/src/builders/unit-test/options.ts

@@ -64,8 +64,12 @@ export async function normalizeOptions(
   const { projectRoot, projectSourceRoot } = getProjectRootPaths(workspaceRoot, projectMetadata);
 
   // Gather persistent caching option and provide a project specific cache location
-  const cacheOptions = normalizeCacheOptions(projectMetadata, workspaceRoot);
-  cacheOptions.path = path.join(cacheOptions.path, projectName);
+  const cacheOptions = normalizeCacheOptions(
+    projectMetadata,
+    workspaceRoot,
+    projectName,
+    context.builder.builderName,
+  );
 
   const {
     runner,

packages/angular/build/src/utils/normalize-cache.ts

@@ -97,9 +97,24 @@ function getCacheBasePath(workspaceRoot: string, cachePathSetting: string): stri
   return resolve(workspaceRoot, cachePathSetting);
 }
 
+/**
+ * Normalizes the persistent disk cache configuration for a project or workspace.
+ *
+ * Resolves whether disk caching is enabled based on the CLI cache metadata, current runtime
+ * environment (local vs. CI, or WebContainers), and computes the versioned cache directory paths
+ * (resolving shared Git worktree paths when applicable).
+ *
+ * @param projectMetadata The project or workspace metadata object containing optional `cli.cache` settings.
+ * @param workspaceRoot The absolute path to the workspace root directory.
+ * @param projectName Optional name of the project used to scope the resolved cache path.
+ * @param builderName Optional name of the builder or tool used to further scope the resolved cache path.
+ * @returns The normalized disk cache options including enabled state and resolved directory paths.
+ */
 export function normalizeCacheOptions(
   projectMetadata: unknown,
   workspaceRoot: string,
+  projectName = '',
+  builderName = '',
 ): NormalizedCachedOptions {
   const cacheMetadata = hasCacheMetadata(projectMetadata) ? projectMetadata.cli.cache : {};
 
@@ -125,12 +140,13 @@ export function normalizeCacheOptions(
 
   const cacheBasePath = getCacheBasePath(workspaceRoot, path);
   const localCacheBasePath = isAbsolute(path) ? path : resolve(workspaceRoot, path);
+  const normalizedBuilderName = builderName.replaceAll(':', '-');
 
   return {
     enabled: cacheEnabled,
     basePath: cacheBasePath,
-    path: join(cacheBasePath, VERSION),
+    path: join(cacheBasePath, VERSION, projectName, normalizedBuilderName),
     localBasePath: localCacheBasePath,
-    localPath: join(localCacheBasePath, VERSION),
+    localPath: join(localCacheBasePath, VERSION, projectName, normalizedBuilderName),
   };
 }

packages/angular/build/src/utils/normalize-cache_spec.ts

@@ -197,4 +197,96 @@ describe('normalizeCacheOptions', () => {
     expect(options.localBasePath).toBe(resolve(workspaceRoot, '.angular/cache'));
     expect(options.localPath).toBe(resolve(workspaceRoot, '.angular/cache', '0.0.0-PLACEHOLDER'));
   });
+
+  it('should scope path and localPath to projectName when provided', async () => {
+    const workspaceRoot = join(tempDir, 'project');
+    await mkdir(join(workspaceRoot, '.git'), { recursive: true });
+
+    const options = normalizeCacheOptions({}, workspaceRoot, 'my-app');
+
+    expect(options.basePath).toBe(resolve(workspaceRoot, '.angular/cache'));
+    expect(options.path).toBe(resolve(workspaceRoot, '.angular/cache/0.0.0-PLACEHOLDER/my-app'));
+    expect(options.localBasePath).toBe(resolve(workspaceRoot, '.angular/cache'));
+    expect(options.localPath).toBe(
+      resolve(workspaceRoot, '.angular/cache/0.0.0-PLACEHOLDER/my-app'),
+    );
+  });
+
+  it('should scope path and localPath to projectName in a git worktree', async () => {
+    const mainRepoRoot = join(tempDir, 'main-repo');
+    const mainGitDir = join(mainRepoRoot, '.git');
+    const worktreeRoot = join(tempDir, 'worktree');
+
+    await mkdir(mainGitDir, { recursive: true });
+
+    const worktreeMetadataDir = join(mainGitDir, 'worktrees/wt-1');
+    await mkdir(worktreeMetadataDir, { recursive: true });
+    await mkdir(worktreeRoot, { recursive: true });
+    await writeFile(join(worktreeRoot, '.git'), `gitdir: ${worktreeMetadataDir}`);
+    await writeFile(join(worktreeMetadataDir, 'commondir'), '../..');
+
+    const options = normalizeCacheOptions({}, worktreeRoot, 'my-lib');
+
+    expect(options.basePath).toBe(resolve(mainRepoRoot, '.angular/cache'));
+    expect(options.path).toBe(resolve(mainRepoRoot, '.angular/cache/0.0.0-PLACEHOLDER/my-lib'));
+    expect(options.localBasePath).toBe(resolve(worktreeRoot, '.angular/cache'));
+    expect(options.localPath).toBe(
+      resolve(worktreeRoot, '.angular/cache/0.0.0-PLACEHOLDER/my-lib'),
+    );
+  });
+
+  it('should scope path and localPath to projectName and builderName when provided', async () => {
+    const workspaceRoot = join(tempDir, 'project');
+    await mkdir(join(workspaceRoot, '.git'), { recursive: true });
+
+    const options = normalizeCacheOptions({}, workspaceRoot, 'my-app', 'vite');
+
+    expect(options.basePath).toBe(resolve(workspaceRoot, '.angular/cache'));
+    expect(options.path).toBe(
+      resolve(workspaceRoot, '.angular/cache/0.0.0-PLACEHOLDER/my-app/vite'),
+    );
+    expect(options.localBasePath).toBe(resolve(workspaceRoot, '.angular/cache'));
+    expect(options.localPath).toBe(
+      resolve(workspaceRoot, '.angular/cache/0.0.0-PLACEHOLDER/my-app/vite'),
+    );
+  });
+
+  it('should scope path and localPath to projectName and builderName in a git worktree', async () => {
+    const mainRepoRoot = join(tempDir, 'main-repo');
+    const mainGitDir = join(mainRepoRoot, '.git');
+    const worktreeRoot = join(tempDir, 'worktree');
+
+    await mkdir(mainGitDir, { recursive: true });
+
+    const worktreeMetadataDir = join(mainGitDir, 'worktrees/wt-1');
+    await mkdir(worktreeMetadataDir, { recursive: true });
+    await mkdir(worktreeRoot, { recursive: true });
+    await writeFile(join(worktreeRoot, '.git'), `gitdir: ${worktreeMetadataDir}`);
+    await writeFile(join(worktreeMetadataDir, 'commondir'), '../..');
+
+    const options = normalizeCacheOptions({}, worktreeRoot, 'my-app', 'vite');
+
+    expect(options.basePath).toBe(resolve(mainRepoRoot, '.angular/cache'));
+    expect(options.path).toBe(
+      resolve(mainRepoRoot, '.angular/cache/0.0.0-PLACEHOLDER/my-app/vite'),
+    );
+    expect(options.localBasePath).toBe(resolve(worktreeRoot, '.angular/cache'));
+    expect(options.localPath).toBe(
+      resolve(worktreeRoot, '.angular/cache/0.0.0-PLACEHOLDER/my-app/vite'),
+    );
+  });
+
+  it('should normalize builderName to avoid invalid path characters', async () => {
+    const workspaceRoot = join(tempDir, 'project');
+    await mkdir(join(workspaceRoot, '.git'), { recursive: true });
+
+    const options = normalizeCacheOptions({}, workspaceRoot, 'my-app', '@angular/build:unit-test');
+
+    expect(options.path).toBe(
+      resolve(workspaceRoot, '.angular/cache/0.0.0-PLACEHOLDER/my-app/@angular/build-unit-test'),
+    );
+    expect(options.localPath).toBe(
+      resolve(workspaceRoot, '.angular/cache/0.0.0-PLACEHOLDER/my-app/@angular/build-unit-test'),
+    );
+  });
 });