ng build --watch: first edit of each file rebuilds its entire dependent cone — TS shape signatures get overwritten with text version hashes during watch startup #33619

Command

ng build --watch (application builder, @angular/build:application)

Is this a regression?

Partially. The behavior exists at least since @angular-devkit/build-angular:browser-esbuild
17.x + TS 5.4, but the cost per affected file roughly doubled with @angular/build 21 + TS 5.9
(emit + semantic diagnostics of the cone are re-done, where TS 5.4 emitted 1 file and served
diagnostics from cache).

Description

In a large single-project workspace (~7,800 TS files, deep barrel imports), with the build
cache enabled:

• The first edit of a file after starting the watch triggers a near-full recompilation:
  ~1,150 files marked affected by TypeScript, all of them re-emitted through the TS emitter
  and template re-checked — 70–95s — even when the edit is a single appended blank line.
• The second edit of the same file behaves correctly: 1 affected file, 7–10s.
• The first edit of a different file then pays that file's dependent cone once, and so on
  — "first save per dependency cone per watch session is slow".

Root cause (instrumented, TypeScript 5.9.3)

We added probes to BuilderState.create and BuilderState.updateShapeSignature in
typescript.js and logged the signature lifecycle of one file across a session
(hashes abbreviated):

TypeScript's builder has an emit-time shortcut that stores a file's text version hash as
its shape signature instead of computing the d.ts hash
(handleDtsMayChangeOf… → updateShapeSignature(…, /*useFileVersionAsSignature*/ true)).
Every file processed through that path during the watch-startup build is left with a
"poisoned" signature, and its first subsequent edit produces a guaranteed false shape-change,
invalidating its entire dependent cone.

At watch startup the restored program virtually always sees some changed files vs. the
buildinfo snapshot, so the cones of those files get poisoned — in barrel-heavy monorepos this
is effectively most of the program.

Negative control: bare TypeScript does not reproduce this

We drove ts.createEmitAndSemanticDiagnosticsBuilderProgram directly (same call pattern as
AotCompilation: semantic affected-walk with an ignoreSourceFile callback, then
emitNextAffectedFile loop, buildinfo persisted, program restored via ts.readBuilderProgram,
one file touched) against a synthetic 500-dependent barrel project, across TypeScript 5.4.5,
5.5.4, 5.6.3, 5.7.3, 5.8.3, 5.9.3, with variants (inlineSourceMap, shim-style files, custom
transformers passed to emit). Every version/variant collapses correctly: restart-save =
2 affected / 2 emitted, steady saves = 1/1. The poisoning requires the changed-file + emit
interleaving that @angular/build's watch startup produces, which is why we're filing here
(a TypeScript companion issue can follow — the offending shortcut is TS-internal).

Experiment: neutralizing the shortcut fixes it

A 2-line patch to typescript.js — (1) BuilderState.create returns
useFileVersionAsSignature: false unconditionally; (2) updateShapeSignature ignores the
caller's useFileVersionAsSignature override — was tested on the same workspace:

So with true shape signatures, "first save per cone" becomes "first save per session".

Note: TypeScript already has an internal escape hatch — disableUseFileVersionAsSignature
(third parameter of BuilderState.create, used by the language-service path) — but the
incremental-builder API hardcodes it to false, and the emit-time override bypasses it
anyway. There is currently no public knob.

Secondary observation (Angular-side)

With the TS layer fixed, the session's first update still rebuilds one cone: the Angular
compiler regenerates the TTC shims for the changed file's whole import cone on the first
update of a session (~1,147 shim files with new versions → TS must walk them as changed
files), and only regenerates the touched file's shim on later updates. Its
incremental/semantic state is in-memory only, so this cost recurs once per watch session.

Minimal reproduction recipe

Any large workspace with barrel imports shows it; measure with:

NG_BUILD_DEBUG_PERF=1 NG_BUILD_PARALLEL_TS=0 ng build --watch
# wait for initial build, then:
echo "" >> src/app/<some-widely-imported-file>.ts     # 1st edit: near-initial-build time
echo "" >> src/app/<some-widely-imported-file>.ts     # 2nd edit: fast
echo "" >> src/app/<some-other-area-file>.ts          # 1st edit of another cone: slow again

A synthetic generator (N components importing a shared type through a barrel index.ts)
reproduces the same pattern; happy to provide the probe patches for
BuilderState.create/updateShapeSignature used to capture the signature lifecycle.

Environment

• Angular CLI / @angular/build: 21.2.12
• TypeScript: 5.9.3
• Node: v22.19.0
• OS: Linux x64
• Single-project workspace, ~7,800 TS files, incremental + CLI cache enabled,
  sourceMap.scripts: true (TS-emit path)

Related

• ng serve --watch is as slow as ng build on rebuild #24832 (ng serve --watch as slow as ng build on rebuild — same symptom family)
• Watch mode: rebuild takes too long after adding a simple console.log to file (~2 minutes) microsoft/TypeScript#42173 (closed as Design Limitation — same symptom family, no mechanism)

Ask

1. Coordinate with TypeScript to expose/respect disableUseFileVersionAsSignature in the
   incremental builder API (or stop overwriting real shape hashes with version hashes at emit
   time), and adopt it in @angular/build — our measurements show no meaningful cost and a
   10x improvement for first-edit rebuilds in barrel-heavy workspaces.
2. Consider making the first-update TTC shim regeneration incremental (or persistable), so
   the once-per-session cone disappears as well.