fixup! test(@angular/build): add library builder scaling benchmark suite

dherges · Oct 8, 2026 · Oct 10, 2026 · Oct 10, 2026 · Oct 10, 2026 · Oct 12, 2026
commit fe70c22f8f36d44bedc63c9adefa0245fba99e27
diff --git a/scripts/benchmark.mts b/scripts/benchmark.mts
@@ -32,7 +32,7 @@ function checkBuildStatus(logger: Console): boolean {
     if (srcMtime > distMtime) {
       logger.warn(
         'Warning: Source files in packages/angular/build are newer than dist/.\n' +
-        'Run "pnpm build" to ensure your benchmark reflects your latest local edits.\n',
+          'Run "pnpm build" to ensure your benchmark reflects your latest local edits.\n',
       );
     }
   }
@@ -44,64 +44,63 @@ function parseIntList(raw: string | number | undefined): number[] | undefined {
   if (raw === undefined) {
     return undefined;
   }
-  return String(raw).split(',').map((s) => Number(s.trim()));
+  return String(raw)
+    .split(',')
+    .map((s) => Number(s.trim()));
 }
 
 async function runLibraryBuilderSubsystem(options: {
   layout?: string;
-  style?: string;
-  sizes?: string;
-  depths?: string;
+  count?: string;
+  depth?: string;
   iterations?: string | number;
   json?: boolean;
 }): Promise<number> {
   if (options.layout !== undefined && options.layout !== 'flat' && options.layout !== 'deep') {
     // eslint-disable-next-line no-console
-    console.error("Error: --layout must be \"flat\" or \"deep\", got \"" + options.layout + "\".");
+    console.error('Error: --layout must be "flat" or "deep", got "' + options.layout + '".');
 
     return 1;
   }
-  if (
-    options.style !== undefined &&
-    !['inline', 'inline-scss', 'external'].includes(options.style)
-  ) {
+
+  const count = parseIntList(options.count);
+  if (count !== undefined && count.some((n) => !Number.isInteger(n) || n < 1)) {
     // eslint-disable-next-line no-console
     console.error(
-      "Error: --style must be one of \"inline\", \"inline-scss\", \"external\", got \"" + options.style + "\"."
+      'Error: --count must be a comma-separated list of positive integers, got "' +
+        options.count +
+        '".',
     );
 
     return 1;
   }
 
-  const sizes = parseIntList(options.sizes);
-  if (sizes !== undefined && sizes.some((n) => !Number.isInteger(n) || n < 1)) {
-    // eslint-disable-next-line no-console
-    console.error("Error: --sizes must be a comma-separated list of positive integers, got \"" + options.sizes + "\".");
-
-    return 1;
-  }
-
-  const depths = parseIntList(options.depths);
-  if (depths !== undefined && depths.some((n) => !Number.isInteger(n) || n < 1)) {
+  const depth = parseIntList(options.depth);
+  if (depth !== undefined && depth.some((n) => !Number.isInteger(n) || n < 1)) {
     // eslint-disable-next-line no-console
-    console.error("Error: --depths must be a comma-separated list of positive integers, got \"" + options.depths + "\".");
+    console.error(
+      'Error: --depth must be a comma-separated list of positive integers, got "' +
+        options.depth +
+        '".',
+    );
 
     return 1;
   }
 
   const iterations = options.iterations !== undefined ? Number(options.iterations) : undefined;
   if (iterations !== undefined && (!Number.isInteger(iterations) || iterations < 1)) {
     // eslint-disable-next-line no-console
-    console.error("Error: --iterations must be a positive integer, got \"" + options.iterations + "\".");
+    console.error(
+      'Error: --iterations must be a positive integer, got "' + options.iterations + '".',
+    );
 
     return 1;
   }
 
   const cliOptions: LibraryBuilderBenchmarkOptions = {
     layout: options.layout as LibraryBuilderBenchmarkOptions['layout'],
-    style: options.style as LibraryBuilderBenchmarkOptions['style'],
-    sizes,
-    depths,
+    count,
+    depth,
     iterations,
     json: Boolean(options.json),
   };
@@ -127,9 +126,8 @@ export default async function (
     compareBaseline?: string;
     'compare-baseline'?: string;
     layout?: string;
-    style?: string;
-    sizes?: string;
-    depths?: string;
+    count?: string;
+    depth?: string;
     help?: boolean;
     [key: string]: unknown;
   },
@@ -163,10 +161,12 @@ Options (i18n):
 
 Options (library-builder):
   --layout=<flat|deep>       Fixture layout (default: flat)
-  --style=<inline|inline-scss|external>  Component style variant (default: inline)
-  --sizes=<n,n,...>          Entry-point counts to sweep, layout=flat only (default: 10,50,300,1000,2000)
-  --depths=<n,n,...>         Tree depths to sweep, layout=deep only (default: 2,5,8,11)
-  --iterations=<n>           Measured iterations per size (default: 2)
+  --count=<n,n,...>          Entry-point count targets, drives both layouts
+                             (default: 10,20,50,100,200,300,400,500,1000,2000)
+  --depth=<n,n,...>          Explicit tree depths, layout=deep only. Overrides the depths
+                             that would otherwise be derived from --count (the smallest
+                             depth with 2^depth >= each target count).
+  --iterations=<n>           Measured iterations (default: 3)
   --json                     Output raw measurements as JSON
 
   --help                     Show this help message

diff --git a/scripts/benchmarks/library-builder/README.md b/scripts/benchmarks/library-builder/README.md
@@ -1,77 +1,119 @@
-# `@angular/build:library` scaling benchmark
+# Library Builds Scaling Benchmark
 
-This benchmark measures how `@angular/build:library`'s cold build time scales with the number
-of secondary entry points in an Angular Package Format (APF) library, across two structurally
-different layouts (flat siblings vs. a deeply nested tree) and three component style variants
-(inline template, inline template + styles, external template/stylesheet files).
+This benchmark measures build time metrics for Angular libraries.
 
-## Why
+## Context
 
-A comparison against [ng-packagr](https://github.com/ng-packagr/ng-packagr) (a third-party APF
-build tool) found that its build time **per entry point** grows super-linearly once a library
-has more than roughly 300-500 secondary entry points -- doubling the library size past that
-point costs noticeably more than double the build time. This suite exists to check whether
-`@angular/build:library`, a from-scratch build pipeline unrelated to ng-packagr's implementation,
-shows the same growth on equivalent fixtures.
+Angular CLI is in the process of transitioning from `ng-packagr` to Angular CLI's native library builder.
+Both library build systems are registered Architect builders:
+- `@angular/build:ng-packagr`: runs library builds through the legacy `ng-packagr` build pipeline.
+- `@angular/build:library`: runs library builds through Angular CLI's native library builder.
 
-**Finding:** it does not. Across the same sweep (flat layout: 10/50/300/1000/2000 entries; deep
-layout: tree depths 2/5/8/11, i.e. 4/32/256/2048 entries), `@angular/build:library`'s per-entry
-cost keeps falling as the library grows, with no climb at the largest sizes tested. It is also
-1.8-13x faster than ng-packagr at matching sizes, with the gap widening as size increases. See
-the PR description this suite was added alongside for the full writeup and caveats.
+This benchmark suite is designed to quantify performance impacts and ensure scalability.
 
-## Running it
+### Previous Benchmarks
+
+For context, when running a similar benchmark suite directly against `ng-packagr`, it hinted at a "U-curve" in build times,
+where build time per entry point in `ng-packagr` drops until entry point N (with N varying in the range 200..500).
+This shape indicates an initial overhead as a possible explanation for a small number of entry points.
+However, we discovered that `ng-packagr` build time per entry point increases
+as the number of entry points scale past a certain N (in the test runs N=200+).
+
+[Landing Angular CLI's native `@angular/build:library` builder](https://github.com/angular/angular-cli/pull/34106#issuecomment-5744311681),
+indicated very favourable performance metrics for the new library builder that can be explained by number of
+architectural changes in the library build pipeline:
+- Shared Stylesheet Bundling
+- Public API Invalidation via Declaration Hashing
+- Dedicated Worker Pool for Production Builds
+- Single Pass Output Emission
+- Direct Async Pipeline
+
+### Goals
+
+This benchmark suite runs explorative research on the performance of library builds in Angular CLI.
+Interesting results from the previous benchmarks indicate 2 measurable goals:
+
+- Measure the new library builder against itself: How does it scale with the number of entry points?
+- Enable A/B benchmarks of the `@angular/build:ng-packagr` builder against `@angular/build:library` builder: How much do library builds benefit from the transition to the native library builder?
+
+As the previous benchmark runs hint at significant performance improvements in the new library builder,
+this benchmark suite aims to quantify the impact of that transition.
+
+## Benchmark Design
+
+This suite supports two primary layouts to test different filesystem and entry-point scaling scenarios:
+
+- **Flat (`--layout=flat`)**: Generates $N$ secondary entry points as direct siblings, where $N$
+  comes straight from `--count`.
+  - Design: Each entry point is named `comp-i` (e.g., `comp-0001`, `comp-0002`).
+
+- **Deep (`--layout=deep`)**: Generates $2^N$ secondary entry points in a binary tree structure.
+  - Design: Creates a nested directory structure (`sub-a`/`sub-b` at each level).
+  - Depth $N$ is not an independent sweep parameter -- see "Sweep rounds" below.
+
+Each entry point consists of a `public-api.ts` and a component file with an inline template
+containing a bit of per-entry content derived from the entry's id (e.g. `<h2>Component no.
+0042</h2>`), so entries aren't byte-identical copies of each other.
+
+### Sweep rounds
+
+`--count` is the one sweep parameter: a comma-separated list of entry-point count targets. The
+default sweep spans small to large entry-point counts in one round, chosen to resolve the
+U-shaped scaling pattern observed with `ng-packagr` (see above):
+`10, 20, 50, 100, 200, 300, 400, 500, 1000, 2000`.
+
+For `--layout=deep`, there's no "number of entry points" parameter directly -- a binary tree of
+depth $N$ always has exactly $2^N$ leaves/entry points. So `--count`'s targets are translated into
+tree depths: for each target `n`, the smallest `depth` with `2^depth >= n`, de-duplicated (e.g.
+`300`, `400`, and `500` all round up to the same `depth=9`, i.e. 512 entry points). This keeps
+both layouts comparable at roughly the same entry-point scale without exposing depth as a second,
+independently-tunable sweep axis. `--depth` still exists as an **explicit override** for
+`--layout=deep` -- pass it directly to sweep exact tree depths instead of entry-point targets --
+but it is not part of the default sweep design and is ignored for `--layout=flat`.
+
+## Running the Benchmarks
 
 ```sh
-pnpm build   # or: pnpm admin build --local -- the benchmark measures the compiled builder,
-             # not TypeScript source, so it must exist at dist/@angular/build and
-             # dist/@angular-devkit/architect first
-pnpm admin benchmark library-builder
+# Ensure the builder is built first
+pnpm build
+
+# Run the benchmark
+pnpm admin benchmark library-builder [options]
 ```
 
-Options:
+### Options
 
-```
---layout=<flat|deep>       Fixture layout (default: flat)
---style=<inline|inline-scss|external>   Component style variant (default: inline)
---sizes=<n,n,...>          Entry-point counts to sweep, layout=flat only (default: 10,50,300,1000,2000)
---depths=<n,n,...>         Tree depths to sweep, layout=deep only (default: 2,5,8,11)
---iterations=<n>           Measured iterations per size (default: 2)
---json                     Output raw measurements as JSON instead of a human-readable log
-```
+| Option                 | Description                                     | Default                                  |
+| :--------------------- | :----------------------------------------------- | :---------------------------------------- |
+| `--layout=<flat\|deep>` | Fixture layout                                  | `flat`                                    |
+| `--count=<n,n,...>`    | Entry-point count targets, drives both layouts  | `10,20,50,100,200,300,400,500,1000,2000` |
+| `--depth=<n,n,...>`    | **`layout=deep` only.** Explicit tree depths, overriding the depths otherwise derived from `--count` | derived from `--count` |
+| `--iterations=<n>`     | Measured iterations per size                    | `3`                                       |
+| `--json`               | Output raw measurements as JSON                 | N/A                                       |
 
-Example: sweep the external-style variant at a few sizes with 3 iterations each:
+> `--count` and `--depth` are not independent sweep axes for `layout=deep`: `--count` is translated
+> into depths (smallest `depth` with `2^depth >= n` per target, de-duplicated); `--depth` only
+> matters when you want to bypass that translation and name exact tree depths yourself. Passing
+> both for `layout=deep` makes `--depth` win; `--depth` is ignored entirely for `layout=flat`.
+
+### Example
+
+Sweep the flat layout at a single size:
 
 ```sh
-pnpm admin benchmark library-builder --style=external --sizes=100,500,1000 --iterations=3
+pnpm admin benchmark library-builder --layout=flat --count=500
 ```
 
-## How it works
-
-- `fixtures.mts` generates a synthetic library at a given size/layout/style: a primary entry
-  point, N secondary entry points (each a minimal standalone Angular component), and the
-  `angular.json`/`tsconfig.lib.json`/`package.json` scaffolding `@angular/build:library` needs.
-  Secondary entry points are declared as a single flat `exports` map in the root `package.json`
-  (the builder's actual convention), not as separate per-entry config files.
-- `index.mts` times `architect lib:build` (the standalone `@angular-devkit/architect` CLI,
-  invoked directly -- no `ng` CLI needed) once per iteration via `child_process.spawnSync`,
-  discards the generated project afterwards, and reports per-size median build time.
-- Because `@angular/build` and `@angular-devkit/architect` are Bazel-built workspace packages
-  rather than ordinary npm dependencies, a plain `pnpm install` never links them (or their own
-  dependencies) into the repo's root `node_modules` -- nothing in `dist/` is resolvable via a
-  bare `require()`/`import` otherwise. On first run, `index.mts` symlinks `@angular/build` and
-  `@angular-devkit/architect` from `dist/` into the root `node_modules`, then walks their
-  declared `dependencies` and links any of those still missing from the pnpm store. This only
-  touches `node_modules` (already gitignored) and is idempotent -- safe to run repeatedly or
-  alongside other work in the same checkout.
-
-## Methodology notes
-
-- Each reported number is the **median** of the measured iterations, not the mean -- process-spawn
-  wall-clock timings are noisy and right-skewed, and the median is more representative of steady
-  state than an outlier-sensitive mean.
-- Results are specific to the machine they were collected on. Run on one otherwise-idle machine
-  for a self-consistent sweep; absolute numbers will differ across hardware, though the _shape_
-  of the curve (does per-entry cost grow with size, or not) is the more portable finding.
-- This benchmark only covers **cold, one-shot builds**. It does not exercise incremental rebuilds
-  or watch mode.
+## Benchmark Results
+
+_(To be filled in once a sweep has been run and reviewed. Out of scope for this iteration.)_
+
+## Future Work
+
+- Style-flavor matrix: inline / inline-css / inline-scss / external / external-css / external-scss, swept across both layouts.
+- A/B comparison against `ng-packagr` (both are already registered Architect builders — `@angular/build:ng-packagr` and `@angular/build:library` — so this is a same-builder-package comparison, not a separate tool invocation).
+- Dependencies between entry points.
+- Shared stylesheet tokens imported by multiple components.
+- Watch mode.
+- Peak memory (`ru_maxrss`) and CPU time (`ru_utime` + `ru_stime`) metrics per build, in addition to wall-clock build time.
+- Library "taste" variants beyond plain flat/deep, e.g. flat/deep with inter-entry-point dependencies or shared SCSS tokens (currently out of scope, listed above).