refactor(@angular/build): eliminate circular dependencies in bundler context

clydin · clydin · commit 19b65263739f · 2026-05-04T15:07:32.000-04:00
Relocate foundational bundler file types and creation utilities to a new, standalone module to resolve multiple recursive dependencies centered around the utilities implementation. By decoupling the core output file definitions from the heavier build contexts, the overall module graph is streamlined, ensuring cleaner isolation and enabling the removal of several longstanding circular paths from the package golden file.
diff --git a/goldens/circular-deps/packages.json b/goldens/circular-deps/packages.json
@@ -1,30 +1 @@
-[
-  [
-    "packages/angular/build/src/tools/esbuild/angular/component-stylesheets.ts",
-    "packages/angular/build/src/tools/esbuild/bundler-context.ts",
-    "packages/angular/build/src/tools/esbuild/utils.ts",
-    "packages/angular/build/src/tools/esbuild/bundler-execution-result.ts"
-  ],
-  [
-    "packages/angular/build/src/tools/esbuild/bundler-context.ts",
-    "packages/angular/build/src/tools/esbuild/utils.ts"
-  ],
-  [
-    "packages/angular/build/src/tools/esbuild/bundler-context.ts",
-    "packages/angular/build/src/tools/esbuild/utils.ts",
-    "packages/angular/build/src/tools/esbuild/bundler-execution-result.ts"
-  ],
-  [
-    "packages/angular/build/src/tools/esbuild/bundler-context.ts",
-    "packages/angular/build/src/tools/esbuild/utils.ts",
-    "packages/angular/build/src/utils/server-rendering/manifest.ts"
-  ],
-  [
-    "packages/angular/build/src/tools/esbuild/bundler-execution-result.ts",
-    "packages/angular/build/src/tools/esbuild/utils.ts"
-  ],
-  [
-    "packages/angular/build/src/tools/esbuild/utils.ts",
-    "packages/angular/build/src/utils/server-rendering/manifest.ts"
-  ]
-]
+[]
diff --git a/packages/angular/build/src/builders/application/build-action.ts b/packages/angular/build/src/builders/application/build-action.ts
@@ -9,7 +9,7 @@
 import { BuilderContext } from '@angular-devkit/architect';
 import { existsSync } from 'node:fs';
 import path from 'node:path';
-import { BuildOutputFile, BuildOutputFileType } from '../../tools/esbuild/bundler-context';
+import { BuildOutputFile, BuildOutputFileType } from '../../tools/esbuild/bundler-files';
 import { ExecutionResult, RebuildState } from '../../tools/esbuild/bundler-execution-result';
 import { shutdownSassWorkerPool } from '../../tools/esbuild/stylesheets/sass-language';
 import { logMessages, withNoProgress, withSpinner } from '../../tools/esbuild/utils';
diff --git a/packages/angular/build/src/builders/application/chunk-optimizer.ts b/packages/angular/build/src/builders/application/chunk-optimizer.ts
@@ -21,12 +21,14 @@ import type { Message, Metafile } from 'esbuild';
 import assert from 'node:assert';
 import { type Plugin, rollup } from 'rollup';
 import {
-  BuildOutputFile,
-  BuildOutputFileType,
   BundleContextResult,
-  InitialFileRecord,
 } from '../../tools/esbuild/bundler-context';
-import { createOutputFile } from '../../tools/esbuild/utils';
+import {
+  type BuildOutputFile,
+  BuildOutputFileType,
+  createOutputFile,
+  type InitialFileRecord,
+} from '../../tools/esbuild/bundler-files';
 import { useRolldownChunks } from '../../utils/environment-options';
 import { assertIsError } from '../../utils/error';
 import { toPosixPath } from '../../utils/path';
diff --git a/packages/angular/build/src/builders/application/execute-build.ts b/packages/angular/build/src/builders/application/execute-build.ts
@@ -11,10 +11,10 @@ import { createAngularCompilation } from '../../tools/angular/compilation';
 import { SourceFileCache } from '../../tools/esbuild/angular/source-file-cache';
 import { generateBudgetStats } from '../../tools/esbuild/budget-stats';
 import {
-  BuildOutputFileType,
   BundleContextResult,
   BundlerContext,
 } from '../../tools/esbuild/bundler-context';
+import { BuildOutputFileType } from '../../tools/esbuild/bundler-files';
 import { ExecutionResult, RebuildState } from '../../tools/esbuild/bundler-execution-result';
 import { checkCommonJSModules } from '../../tools/esbuild/commonjs-checker';
 import { extractLicenses } from '../../tools/esbuild/license-extractor';
diff --git a/packages/angular/build/src/builders/application/execute-post-bundle.ts b/packages/angular/build/src/builders/application/execute-post-bundle.ts
@@ -9,16 +9,16 @@
 import type { Metafile } from 'esbuild';
 import assert from 'node:assert';
 import {
-  BuildOutputFile,
+  type BuildOutputFile,
   BuildOutputFileType,
-  InitialFileRecord,
-} from '../../tools/esbuild/bundler-context';
+  createOutputFile,
+  type InitialFileRecord,
+} from '../../tools/esbuild/bundler-files';
 import {
-  BuildOutputAsset,
-  PrerenderedRoutesRecord,
+  type BuildOutputAsset,
+  type PrerenderedRoutesRecord,
 } from '../../tools/esbuild/bundler-execution-result';
 import { generateIndexHtml } from '../../tools/esbuild/index-html-generator';
-import { createOutputFile } from '../../tools/esbuild/utils';
 import { maxWorkers } from '../../utils/environment-options';
 import {
   SERVER_APP_MANIFEST_FILENAME,
diff --git a/packages/angular/build/src/builders/application/i18n.ts b/packages/angular/build/src/builders/application/i18n.ts
@@ -9,7 +9,7 @@
 import { BuilderContext } from '@angular-devkit/architect';
 import type { Metafile } from 'esbuild';
 import { join } from 'node:path';
-import { BuildOutputFileType, InitialFileRecord } from '../../tools/esbuild/bundler-context';
+import { BuildOutputFileType, InitialFileRecord } from '../../tools/esbuild/bundler-files';
 import {
   ExecutionResult,
   PrerenderedRoutesRecord,
diff --git a/packages/angular/build/src/builders/application/index.ts b/packages/angular/build/src/builders/application/index.ts
@@ -10,7 +10,7 @@ import { Builder, BuilderContext, BuilderOutput, createBuilder } from '@angular-
 import assert from 'node:assert';
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { BuildOutputFileType } from '../../tools/esbuild/bundler-context';
+import { BuildOutputFileType } from '../../tools/esbuild/bundler-files';
 import { createJsonBuildManifest, emitFilesToDisk } from '../../tools/esbuild/utils';
 import { colors as ansiColors } from '../../utils/color';
 import { deleteOutputDir } from '../../utils/delete-output-dir';
diff --git a/packages/angular/build/src/builders/application/results.ts b/packages/angular/build/src/builders/application/results.ts
@@ -6,7 +6,7 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
-import { BuildOutputFileType } from '../../tools/esbuild/bundler-context';
+import { BuildOutputFileType } from '../../tools/esbuild/bundler-files';
 
 export enum ResultKind {
   Failure,
diff --git a/packages/angular/build/src/builders/dev-server/internal.ts b/packages/angular/build/src/builders/dev-server/internal.ts
@@ -6,7 +6,7 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
-export { type BuildOutputFile, BuildOutputFileType } from '../../tools/esbuild/bundler-context';
+export { type BuildOutputFile, BuildOutputFileType } from '../../tools/esbuild/bundler-files';
 export { createRxjsEsmResolutionPlugin } from '../../tools/esbuild/rxjs-esm-resolution-plugin';
 export { JavaScriptTransformer } from '../../tools/esbuild/javascript-transformer';
 export { getFeatureSupport, isZonelessApp } from '../../tools/esbuild/utils';
diff --git a/packages/angular/build/src/builders/karma/utils.ts b/packages/angular/build/src/builders/karma/utils.ts
@@ -8,7 +8,7 @@
 
 import type { BuilderContext } from '@angular-devkit/architect';
 import { createRequire } from 'node:module';
-import { BuildOutputFileType } from '../../tools/esbuild/bundler-context';
+import { BuildOutputFileType } from '../../tools/esbuild/bundler-files';
 import { getProjectRootPaths } from '../../utils/project-metadata';
 import { findTests, getTestEntrypoints } from './find-tests';
 import type { NormalizedKarmaBuilderOptions } from './options';
diff --git a/packages/angular/build/src/index.ts b/packages/angular/build/src/index.ts
@@ -8,7 +8,7 @@
 
 export { buildApplication, type ApplicationBuilderOptions } from './builders/application';
 export type { ApplicationBuilderExtensions } from './builders/application/options';
-export { type BuildOutputFile, BuildOutputFileType } from './tools/esbuild/bundler-context';
+export { type BuildOutputFile, BuildOutputFileType } from './tools/esbuild/bundler-files';
 export type { BuildOutputAsset } from './tools/esbuild/bundler-execution-result';
 
 export {
diff --git a/packages/angular/build/src/tools/esbuild/angular/component-stylesheets.ts b/packages/angular/build/src/tools/esbuild/angular/component-stylesheets.ts
@@ -9,12 +9,8 @@
 import assert from 'node:assert';
 import { createHash } from 'node:crypto';
 import path from 'node:path';
-import {
-  BuildOutputFile,
-  BuildOutputFileType,
-  BundleContextResult,
-  BundlerContext,
-} from '../bundler-context';
+import { BundleContextResult, BundlerContext } from '../bundler-context';
+import { type BuildOutputFile, BuildOutputFileType } from '../bundler-files';
 import { MemoryCache } from '../cache';
 import {
   BundleStylesheetOptions,
diff --git a/packages/angular/build/src/tools/esbuild/application-code-bundle.ts b/packages/angular/build/src/tools/esbuild/application-code-bundle.ts
@@ -17,6 +17,7 @@ import { toPosixPath } from '../../utils/path';
 import {
   SERVER_APP_ENGINE_MANIFEST_FILENAME,
   SERVER_APP_MANIFEST_FILENAME,
+  SERVER_GENERATED_EXTERNALS,
 } from '../../utils/server-rendering/manifest';
 import { AngularCompilation, NoopCompilation } from '../angular/compilation';
 import { createCompilerPlugin } from './angular/compiler-plugin';
@@ -32,7 +33,7 @@ import { createLoaderImportAttributePlugin } from './loader-import-attribute-plu
 import { createRxjsEsmResolutionPlugin } from './rxjs-esm-resolution-plugin';
 import { createServerBundleMetadata } from './server-bundle-metadata-plugin';
 import { createSourcemapIgnorelistPlugin } from './sourcemap-ignorelist-plugin';
-import { SERVER_GENERATED_EXTERNALS, getFeatureSupport, isZonelessApp } from './utils';
+import { getFeatureSupport, isZonelessApp } from './utils';
 import { createVirtualModulePlugin } from './virtual-module-plugin';
 import { createWasmPlugin } from './wasm-plugin';
 
diff --git a/packages/angular/build/src/tools/esbuild/budget-stats.ts b/packages/angular/build/src/tools/esbuild/budget-stats.ts
@@ -12,7 +12,7 @@ import {
   type BuildOutputFile,
   BuildOutputFileType,
   type InitialFileRecord,
-} from './bundler-context';
+} from './bundler-files';
 import { getChunkNameFromMetafile } from './utils';
 
 /**
diff --git a/packages/angular/build/src/tools/esbuild/bundler-context.ts b/packages/angular/build/src/tools/esbuild/bundler-context.ts
@@ -21,7 +21,13 @@ import assert from 'node:assert';
 import { builtinModules } from 'node:module';
 import { basename, extname, join, relative } from 'node:path';
 import { LoadResultCache, MemoryLoadResultCache } from './load-result-cache';
-import { SERVER_GENERATED_EXTERNALS, convertOutputFile } from './utils';
+import { SERVER_GENERATED_EXTERNALS } from '../../utils/server-rendering/manifest';
+import {
+  type BuildOutputFile,
+  BuildOutputFileType,
+  type InitialFileRecord,
+  convertOutputFile,
+} from './bundler-files';
 
 export type BundleContextResult =
   | { errors: Message[]; warnings: Message[] }
@@ -38,28 +44,6 @@ export type BundleContextResult =
       externalConfiguration?: string[];
     };
 
-export interface InitialFileRecord {
-  entrypoint: boolean;
-  name?: string;
-  type: 'script' | 'style';
-  external?: boolean;
-  serverFile: boolean;
-  depth: number;
-}
-
-export enum BuildOutputFileType {
-  Browser,
-  Media,
-  ServerApplication,
-  ServerRoot,
-  Root,
-}
-
-export interface BuildOutputFile extends OutputFile {
-  type: BuildOutputFileType;
-  readonly size: number;
-  clone: () => BuildOutputFile;
-}
 
 export type BundlerOptionsFactory<T extends BuildOptions = BuildOptions> = (
   loadCache: LoadResultCache | undefined,
diff --git a/packages/angular/build/src/tools/esbuild/bundler-execution-result.ts b/packages/angular/build/src/tools/esbuild/bundler-execution-result.ts
@@ -11,8 +11,8 @@ import { normalize } from 'node:path';
 import type { ChangedFiles } from '../../tools/esbuild/watcher';
 import type { ComponentStylesheetBundler } from './angular/component-stylesheets';
 import type { SourceFileCache } from './angular/source-file-cache';
-import type { BuildOutputFile, BuildOutputFileType, BundlerContext } from './bundler-context';
-import { createOutputFile } from './utils';
+import type { BundlerContext } from './bundler-context';
+import { type BuildOutputFile, BuildOutputFileType, createOutputFile } from './bundler-files';
 
 export interface BuildOutputAsset {
   source: string;
diff --git a/packages/angular/build/src/tools/esbuild/bundler-files.ts b/packages/angular/build/src/tools/esbuild/bundler-files.ts
@@ -0,0 +1,138 @@
+/**
+ * @license
+ * Copyright Google LLC 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.dev/license
+ */
+
+import type { OutputFile } from 'esbuild';
+import { createHash } from 'node:crypto';
+
+export interface InitialFileRecord {
+  entrypoint: boolean;
+  name?: string;
+  type: 'script' | 'style';
+  external?: boolean;
+  serverFile: boolean;
+  depth: number;
+}
+
+export enum BuildOutputFileType {
+  Browser,
+  Media,
+  ServerApplication,
+  ServerRoot,
+  Root,
+}
+
+export interface BuildOutputFile extends OutputFile {
+  type: BuildOutputFileType;
+  readonly size: number;
+  clone: () => BuildOutputFile;
+}
+
+export function createOutputFile(
+  path: string,
+  data: string | Uint8Array,
+  type: BuildOutputFileType,
+): BuildOutputFile {
+  if (typeof data === 'string') {
+    let cachedContents: Uint8Array | null = null;
+    let cachedText: string | null = data;
+    let cachedHash: string | null = null;
+
+    return {
+      path,
+      type,
+      get contents(): Uint8Array {
+        cachedContents ??= new TextEncoder().encode(data);
+
+        return cachedContents;
+      },
+      set contents(value: Uint8Array) {
+        cachedContents = value;
+        cachedText = null;
+      },
+      get text(): string {
+        cachedText ??= new TextDecoder('utf-8').decode(this.contents);
+
+        return cachedText;
+      },
+      get size(): number {
+        return this.contents.byteLength;
+      },
+      get hash(): string {
+        cachedHash ??= createHash('sha256')
+          .update(cachedText ?? this.contents)
+          .digest('hex');
+
+        return cachedHash;
+      },
+      clone(): BuildOutputFile {
+        return createOutputFile(this.path, cachedText ?? this.contents, this.type);
+      },
+    };
+  } else {
+    let cachedContents = data;
+    let cachedText: string | null = null;
+    let cachedHash: string | null = null;
+
+    return {
+      get contents(): Uint8Array {
+        return cachedContents;
+      },
+      set contents(value: Uint8Array) {
+        cachedContents = value;
+        cachedText = null;
+      },
+      path,
+      type,
+      get size(): number {
+        return this.contents.byteLength;
+      },
+      get text(): string {
+        cachedText ??= new TextDecoder('utf-8').decode(this.contents);
+
+        return cachedText;
+      },
+      get hash(): string {
+        cachedHash ??= createHash('sha256').update(this.contents).digest('hex');
+
+        return cachedHash;
+      },
+      clone(): BuildOutputFile {
+        return createOutputFile(this.path, this.contents, this.type);
+      },
+    };
+  }
+}
+
+export function convertOutputFile(file: OutputFile, type: BuildOutputFileType): BuildOutputFile {
+  let { contents: cachedContents } = file;
+  let cachedText: string | null = null;
+
+  return {
+    get contents(): Uint8Array {
+      return cachedContents;
+    },
+    set contents(value: Uint8Array) {
+      cachedContents = value;
+      cachedText = null;
+    },
+    hash: file.hash,
+    path: file.path,
+    type,
+    get size(): number {
+      return this.contents.byteLength;
+    },
+    get text(): string {
+      cachedText ??= new TextDecoder('utf-8').decode(this.contents);
+
+      return cachedText;
+    },
+    clone(): BuildOutputFile {
+      return convertOutputFile(this, this.type);
+    },
+  };
+}
diff --git a/packages/angular/build/src/tools/esbuild/i18n-inliner.ts b/packages/angular/build/src/tools/esbuild/i18n-inliner.ts
@@ -10,9 +10,12 @@ import assert from 'node:assert';
 import { createHash } from 'node:crypto';
 import { extname, join } from 'node:path';
 import { WorkerPool } from '../../utils/worker-pool';
-import { BuildOutputFile, BuildOutputFileType } from './bundler-context';
+import {
+  type BuildOutputFile,
+  BuildOutputFileType,
+  createOutputFile,
+} from './bundler-files';
 import type { LmdbCacheStore } from './lmdb-cache-store';
-import { createOutputFile } from './utils';
 
 /**
  * A keyword used to indicate if a JavaScript file may require inlining of translations.
diff --git a/packages/angular/build/src/tools/esbuild/index-html-generator.ts b/packages/angular/build/src/tools/esbuild/index-html-generator.ts
diff --git a/packages/angular/build/src/tools/esbuild/utils.ts b/packages/angular/build/src/tools/esbuild/utils.ts
diff --git a/packages/angular/build/src/utils/server-rendering/manifest.ts b/packages/angular/build/src/utils/server-rendering/manifest.ts
diff --git a/packages/angular/build/src/utils/server-rendering/prerender.ts b/packages/angular/build/src/utils/server-rendering/prerender.ts
diff --git a/packages/angular/build/src/utils/service-worker.ts b/packages/angular/build/src/utils/service-worker.ts
diff --git a/packages/angular/build/src/utils/test-files.ts b/packages/angular/build/src/utils/test-files.ts
