ast-mcp-server 0.16.0 → 0.18.0

package/CHANGELOG.md

@@ -6,7 +6,45 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
-## [0.16.0] — not yet published (2026-11-06)
+## [0.18.0] — not yet published (2026-11-10)
+
+### Added
+
+- `ast_explore` reports Angular template evidence in `evidence[].references` whenever it expands references: each item carries `origin` (`compiler`, `template_external`, `template_inline`) and the block adds `template_coverage` and `template_reference_count`, with the verdict `ast_find_references` gives for the same symbol. The fields are additive and absent when coverage is `not_applicable`, so output for non-Angular projects is unchanged (#380).
+- New `ast_explore` omission reason `template_coverage_incomplete` (category `incomplete`, component `references`). Any coverage status other than `completed` raises it once per symbol and sets `evidence_complete: false`; the reason code is in `template_coverage`, and the omission is still counted when `max_bytes` drops the references block. A failure of the template step alone keeps the TypeScript references and reports `unfinished` with `template_unresolved` (#380).
+- `yarn benchmark:explore-templates` measures the added latency on demand. The recorded run adds 1059 ms at p95 for `detail: "full"`, `limit: 20` on 501 components (threshold 2 s), and every request on 2001 components returns a typed result with `work_exhausted`; see `docs/spikes/0380-explore-template-latency.md` (#380).
+
+### Changed
+
+- In `ast_explore`, `reference_limit` now bounds the merged list of TypeScript and template items, with the same ordering as `ast_find_references`. Its input description still says "compiler references", and `reference_count` counts TypeScript items only. Page the remaining items through `ast_find_references` (#380).
+- The `tools/list` digest changed because the `ast_explore` output schema gained the optional fields and the new omission reason. Tool descriptions and input schemas are unchanged. `ast_get_impact`, `ast_find_test_candidates` and the `ast_explore` call spines stay compiler-only (#380).
+- The `structural-code-editing` skill is `4.9.0`: it and the README describe the `ast_explore` template evidence instead of the former TypeScript-only limit. The published npm `0.17.0` bytes (skill `4.8.0`) are recorded as a predecessor (#380).
+- `ast_explore` reads and parses each Angular template at most once per request: the selected symbols share the component list, the template reads and the parses through a cache that lives for that request only. Items, order, per-symbol scan budgets and `template_coverage` verdicts are the same as before, and `ast_find_references` is unaffected. In the recorded run the added p50 for `detail: "full"`, `limit: 20` falls from 1040 ms to 179 ms on 501 components and from 4238 ms to 698 ms on 2001 components, where every symbol still ends with `work_exhausted`; see `docs/spikes/0380-explore-template-latency.md` (#454).
+
+## [0.17.0] — published to `next`, verification failed, not promoted (2026-11-10)
+
+### Added
+
+- `ast_rename_symbol` runs an Angular template type check for renames that edit templates and reports the result as `template_diagnostics` (`status`, `reason`, `added`, `removed`, `added_errors`). The check is on by default and best-effort: it runs ngtsc in a one-shot child process that never writes to the workspace, within a time budget, and `unavailable` or `unfinished` statuses mean unknown, so run the project's build or tests. The field is absent for non-Angular projects and renames that edit no template; the `diagnostics` field stays TypeScript-only (#421).
+- New `ast_rename_symbol` input `block_on_template_errors` (default `false`). It blocks the plan only when a `completed` check adds template errors, and `allow_new_errors` waives it (#421).
+- The check needs `@angular/compiler-cli` to resolve from the project (same version as `@angular/compiler`, TypeScript within its peer range); it is not a declared peer, and without it the status is `unavailable` with `compiler_cli_missing`. `template_diagnostics[].file` is relative to the directory of the tsconfig, while `diagnostics[].file` is relative to `project_root` (#421).
+- Spike results and the design decision are in `docs/spikes/0421-template-type-check.md` and `docs/adr/0017-template-type-check-worker.md` (#421).
+
+### Changed
+
+- Plans from a template-editing rename persist as plan schema v3 (the hash adds `template_diagnostics` and `block_on_template_errors`), even when the status is `unavailable` or `unfinished`. Plans without a check keep schema v2 and the same hash. After a downgrade or revert, schema v3 plans are rejected on import (#421).
+- The `ast_rename_symbol` and `ast_find_references` tool descriptions no longer say template errors are not diagnosed; `ast_find_references` still reports usages only and points to `template_diagnostics` (#421).
+
+### Fixed
+
+- With `@angular/compiler` 18 or 19, template usage scans walked every subtree twice per nesting level, so `ast_find_references` on a `@Pipe` class or a component member reported `unfinished` with `work_exhausted` on deeply nested templates, and `ast_rename_symbol` refused the rename. Each template is now walked once on every supported major (#441).
+- Upgrading the `structural-code-editing` skill over an unmodified install from npm `0.16.0` would have failed with a conflict: its content changed after `0.16.0` (#443) while the skill version stayed `4.7.0`, and the `0.16.0` byte set had no recorded predecessor. The published `0.16.0` bytes are now recorded, and the skill version is `4.8.0` (#447).
+
+### Release status
+
+- npm published these immutable bytes under `next` with provenance and the expected Git commit (`e49987bd1fd36432aa76ecb27ca8359eedb613ad`, integrity `sha512-NmjdENfdfLCSqdMJyazxHfx1XuFHgQeJlAB2XIpHGklqCKkwVw43xKMlXmDfdT7m1XT/b4mokx1MefFdj/AIyw==`, publish run `42753818346`). Public-registry verification (run `42754346795`) then failed for the same reason as `0.14.3`–`0.16.0`: the consumer install resolves `minimatch@10.2.6` through `ts-morph@28.0.0`, flagged by `npm audit` for GHSA-g3hv-75wg-m249 (#361). `0.17.0` supersedes `0.16.0` on `next` and was not promoted to `latest`, tagged in Git, or released on GitHub.
+
+## [0.16.0] — published to `next`, verification failed, not promoted (2026-11-07)
 
 ### Added
 
@@ -26,6 +64,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 - `@Directive` members declared with `@Input`, `@Output`, `input()`, `output()` or `model()` reported no `template_coverage`, and members listed in the `inputs` / `outputs` metadata arrays of a `@Component` or `@Directive` were treated as plain members, so `ast_rename_symbol` planned their rename without blocking. They now report `unfinished` with reason `cross_component` (directives with `templates: 0`; a non-literal metadata array marks every member of the class), and `ast_rename_symbol` refuses them with `INCOMPLETE_EVIDENCE` (#410).
 - Upgrading the `structural-code-editing` skill over an unmodified install from npm `0.11.0`–`0.15.1` failed with a conflict: `0.13.0`–`0.15.1` had no recorded predecessor, and the `0.11.0`–`0.12.0` predecessors did not list `references/operations.md`. Every published byte set is now recorded, and the skill version is `4.7.0` (#425).
 
+### Release status
+
+- npm published these immutable bytes under `next` with provenance and the expected Git commit (`0f5a3f137703fdd673640d00a04087db3b2808af`, integrity `sha512-eyKYMudp0DisVhVJctgwXwZERA2GGsNPP8eU+P/Zh7A9aSf/0mGG9PoGY6qxtBAMW+1FJd+nFLizqo8Go7NLZA==`, publish run `42329276499`). Public-registry verification (run `42331039791`) then failed for the same reason as `0.14.3`–`0.15.1`: the consumer install resolves `minimatch@10.2.6` through `ts-morph@28.0.0`, flagged by `npm audit` for GHSA-g3hv-75wg-m249 (#361). `0.16.0` supersedes `0.15.1` on `next` and was not promoted to `latest`, tagged in Git, or released on GitHub.
+
 ## [0.15.1] — published to `next`, verification failed, not promoted (2026-11-05)
 
 ### Changed

package/README.md

@@ -96,8 +96,15 @@ Template evidence is explicit about what it proves:
 - For these members, `completed` means every component template inside the Project was read and every match resolved. `hostDirectives`, `@Directive` inputs and outputs, and non-literal scopes, aliases, metadata or pipe names stay `unfinished` with reason `cross_component`. Runtime bindings (`setInput`, router input binding, `createComponent`) and consumers outside the Project are never examined.
 - Rename rewrites consumer bindings of a selector-bound member when coverage is `completed`, keeping the binding syntax, values and alias-keyed bindings. It returns `INCOMPLETE_EVIDENCE` when coverage is `unfinished` or `unsupported` (including `hostDirectives`, `@Directive` members and metadata-listed members), and `MUTATION_BLOCKED` for inline templates, a name collision with a template local or another binding of the element, `[(x)]` on a non-`model()` pair, `$any`, or a name in the selector. Inline templates are never rewritten.
 - Renaming a `@Pipe` class applies TypeScript edits only and keeps the `name` literal and every `| name` usage; renaming `transform` returns `INCOMPLETE_EVIDENCE`.
-- `ast_explore` stays TypeScript-only for references; template evidence there is tracked in #380. Use `ast_find_references` for template usages.
-- Diagnostics stay TypeScript-only: template errors are not detected, so run the project's Angular build or tests after a rename. Template type checking of rename plans is tracked in #421.
+- `ast_explore` reports the same template evidence in `evidence[].references` whenever it expands references (`detail: "full"` or `include_references: true`): each item carries `origin`, and the block adds `template_coverage` and `template_reference_count` with the verdict `ast_find_references` gives for the same symbol. None of these keys appear when coverage is `not_applicable`.
+- In `ast_explore`, `reference_limit` bounds the merged list of TypeScript and template items, even though its input description still says "compiler references". `reference_count` counts TypeScript items only, and a list cut by the limit raises the usual `reference_limit` omission. `ast_explore` has no reference offset: page the remaining items through `ast_find_references`.
+- Any `template_coverage.status` other than `completed` adds one `template_coverage_incomplete` omission (category `incomplete`, component `references`) per symbol and sets `evidence_complete: false`. The reason code (for example `compiler_missing`) is in `template_coverage`. `omissions.details` lists the omission only when the detail limit leaves room; `omissions.counts` and `omissions.total` always count it, also when `max_bytes` drops the references block.
+- `ast_get_impact`, `ast_find_test_candidates` and the `ast_explore` call spines stay compiler-only: they never contain a template usage.
+- The `diagnostics` field stays TypeScript-only. When a rename edits a template, the plan also carries `template_diagnostics`: a best-effort Angular template type-check delta (`status`, `reason` when not `completed`, `added`, `removed`, `added_errors`) computed by the project's own `@angular/compiler-cli` in a separate child process that never writes to the workspace. It is absent for non-Angular projects and for renames that edit no template. `status` is `completed`, `unavailable` (`compiler_cli_missing`, `compiler_unsupported`, `typescript_incompatible`) or `unfinished` (`work_exhausted`, `deadline`, `check_failed`); the arrays are empty unless it is `completed`.
+- Treat `unavailable` and `unfinished` as unknown, never as clean: run the project's Angular build or tests before applying. `block_on_template_errors` (default `false`) blocks the plan only when the status is `completed` and `added_errors` is not empty; `allow_new_errors` waives it. Without the input the delta is reported but never blocks.
+- `template_diagnostics[].file` is relative to the directory of the tsconfig, while `diagnostics[].file` is relative to `project_root`; they differ when the tsconfig is not at the project root.
+- `@angular/compiler-cli` is not a declared peer. It must resolve from the project, with the same version as `@angular/compiler` and a TypeScript inside its supported range; otherwise the status is `unavailable` with `compiler_cli_missing`.
+- Any template-editing rename emits `template_diagnostics` and persists as plan schema v3, even when the status is `unavailable` or `unfinished`. Plans without the field stay schema v2. After a downgrade or revert, schema v3 plans are rejected on import. See [ADR 0017](docs/adr/0017-template-type-check-worker.md) and the [spike](docs/spikes/0421-template-type-check.md).
 - Yarn PnP projects without a `node_modules` directory cannot resolve the compiler and report `unfinished`; use `nodeLinker: node-modules` for template coverage.
 
 ## Why this helps
@@ -374,7 +381,7 @@ For a local candidate, pack and install its tarball instead:
 
 ```bash
 yarn pack --out ast-mcp-server-%v.tgz
-dsh plugin --profile web add ./ast-mcp-server-0.16.0.tgz
+dsh plugin --profile web add ./ast-mcp-server-0.18.0.tgz
 ```
 
 The first supported surface is **reads + prepare + preview**. Every apply path is

package/cordis.patch.yml

@@ -3,7 +3,7 @@
 # Mounts the packaged `ast-mcp-server` stdio command through the official
 # `@deepseek-ai/dsh-mcp-client` bridge. Harness does not resolve MCP binaries
 # from PATH, so the entrypoint is resolved relative to the profile directory
-# (`baseUrl`), where `dsh plugin --profile <name> add ./ast-mcp-server-0.16.0.tgz`
+# (`baseUrl`), where `dsh plugin --profile <name> add ./ast-mcp-server-0.18.0.tgz`
 # installs a locally packed package as a dependency.
 #
 # First-slice surface: reads + prepare + preview. Every apply path is denied

package/dist/angular-template-typecheck-entry.js

@@ -0,0 +1,19 @@
+import fs from "node:fs";
+import { fileURLToPath } from "node:url";
+import { runTemplateTypeCheck } from "./services/angular-template-typecheck-core.js";
+import { RequestSchema } from "./services/angular-template-typecheck-protocol.js";
+/** Validates one IPC request and runs the core; it never throws. */
+export async function handleRequest(raw, run = runTemplateTypeCheck) {
+    const parsed = RequestSchema.safeParse(raw);
+    return parsed.success ? run(parsed.data) : { v: 1, ok: false, reason: "check_failed" };
+}
+// One-shot child: serve a single request, reply, exit. A lost parent ends the process too.
+const entry = process.argv[1];
+if (process.send &&
+    entry &&
+    fs.realpathSync(entry) === fs.realpathSync(fileURLToPath(import.meta.url))) {
+    process.once("disconnect", () => process.exit(1));
+    process.once("message", (raw) => {
+        void handleRequest(raw).then((reply) => process.send(reply, () => process.exit(0)));
+    });
+}

package/dist/services/angular-package-resolution.js

@@ -0,0 +1,62 @@
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+export const MIN_COMPILER_MAJOR = 18;
+export const MAX_COMPILER_MAJOR = 22;
+/** Resolves `request` the way the project's own tooling would, or `undefined` when absent. */
+export function resolveFrom(tsConfigFilePath, request) {
+    try {
+        const resolved = createRequire(tsConfigFilePath).resolve(request);
+        return existsSync(resolved) ? resolved : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function isWithin(parent, child) {
+    const relative = path.relative(parent, child);
+    return relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+}
+/** True when `packageDir` sits in a node_modules directory owned by `projectDir` or an ancestor. */
+export function isUnderAncestorNodeModules(packageDir, projectDir) {
+    const segments = packageDir.split(path.sep);
+    return segments.some((segment, index) => segment === "node_modules" &&
+        isWithin(segments.slice(0, index).join(path.sep) || path.sep, projectDir));
+}
+export function isSupportedVersion(version) {
+    const match = /^(\d+)\.(\d+)\.(\d+)(-[0-9A-Za-z.-]+)?(?:\+.*)?$/u.exec(String(version));
+    if (!match)
+        return false;
+    const [major, minor, patch] = [match[1], match[2], match[3]].map(Number);
+    const belowFloor = major === MIN_COMPILER_MAJOR && minor === 0 && patch === 0 && !!match[4];
+    return major >= MIN_COMPILER_MAJOR && major <= MAX_COMPILER_MAJOR && !belowFloor;
+}
+const MAX_COMPARATORS = 4;
+const COMPARATOR = /^(>=|<)(\d+)\.(\d+)(?:\.(\d+))?$/u;
+const PLAIN_VERSION = /^(\d+)\.(\d+)\.(\d+)$/u;
+function compareTriples(left, right) {
+    return left[0] - right[0] || left[1] - right[1] || left[2] - right[2];
+}
+/**
+ * Evaluates a plain `x.y.z` version against a space-joined list of `>=x.y[.z]` and `<x.y[.z]`
+ * comparators, the only grammar the Angular peer ranges need. Anything else (`||`, `^`, `~`,
+ * wildcards, prereleases, other operators) is `unsupported` so callers fail closed.
+ */
+export function rangeVerdict(version, range) {
+    const plain = PLAIN_VERSION.exec(version);
+    const tokens = range.trim().split(/\s+/u);
+    if (!plain || tokens.length === 0 || tokens.length > MAX_COMPARATORS)
+        return "unsupported";
+    const actual = [Number(plain[1]), Number(plain[2]), Number(plain[3])];
+    let satisfied = true;
+    for (const token of tokens) {
+        const match = COMPARATOR.exec(token);
+        if (!match)
+            return "unsupported";
+        const bound = [Number(match[2]), Number(match[3]), Number(match[4] ?? 0)];
+        const order = compareTriples(actual, bound);
+        if (match[1] === ">=" ? order < 0 : order >= 0)
+            satisfied = false;
+    }
+    return satisfied ? "satisfied" : "unsatisfied";
+}

package/dist/services/angular-template-typecheck-core.js

@@ -0,0 +1,139 @@
+import { createRequire } from "node:module";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { MAX_MESSAGE_CHARS, } from "./angular-template-typecheck-protocol.js";
+/** Loads the TypeScript that ngtsc itself resolves, then the pre-validated compiler-cli entry. */
+export async function loadToolchain(cliEntry) {
+    const tsEntry = createRequire(cliEntry).resolve("typescript");
+    const ts = (await import(pathToFileURL(tsEntry).href)).default;
+    const cli = (await import(pathToFileURL(cliEntry).href));
+    return { ts, cli };
+}
+/** True when the public surface this driver needs is present (never touches `private/*`). */
+export function probeCompilerApi(cli) {
+    return (typeof cli.NgtscProgram === "function" &&
+        typeof cli.readConfiguration === "function" &&
+        typeof cli.createCompilerHost === "function" &&
+        typeof cli.NgtscProgram.prototype?.getNgSemanticDiagnostics === "function");
+}
+/** Forces the options that make an emit or a build-info write impossible. */
+export function withNoEmit(options) {
+    return {
+        ...options,
+        noEmit: true,
+        incremental: false,
+        composite: false,
+        tsBuildInfoFile: undefined,
+    };
+}
+/** Scope B: an edited template or a scoped component file, never anything under node_modules. */
+export function isInScope(fileName, scopeFiles) {
+    return scopeFiles.has(fileName) && !fileName.split(/[\\/]/u).includes("node_modules");
+}
+export function toWireDiagnostic(ts, root, diagnostic) {
+    const { file } = diagnostic;
+    const start = diagnostic.start ?? null;
+    const position = file && start !== null ? file.getLineAndCharacterOfPosition(start) : null;
+    return {
+        code: diagnostic.code,
+        category: ts.DiagnosticCategory[diagnostic.category] ?? String(diagnostic.category),
+        file: file ? path.relative(root, file.fileName) : "",
+        line: position ? position.line + 1 : null,
+        column: position ? position.character + 1 : null,
+        message: ts
+            .flattenDiagnosticMessageText(diagnostic.messageText, "\n")
+            .slice(0, MAX_MESSAGE_CHARS),
+        start,
+        length: diagnostic.length ?? null,
+    };
+}
+/**
+ * Host over the disk with an optional in-memory overlay. Unchanged files come from one cache
+ * shared by both runs, so the after run reuses the identical SourceFile objects and only parses
+ * overlay files again.
+ */
+function createCheckHost({ ts, cli }, options, overlay, shared) {
+    const tsHost = ts.createCompilerHost(options, true);
+    const { readFile, fileExists, getSourceFile } = tsHost;
+    const fresh = new Map();
+    tsHost.writeFile = () => {
+        throw new Error("The template type check must not write files.");
+    };
+    tsHost.readFile = (name) => overlay?.get(name) ?? readFile.call(tsHost, name);
+    tsHost.fileExists = (name) => overlay?.has(name) === true || fileExists.call(tsHost, name);
+    tsHost.getSourceFile = (name, languageVersion, ...rest) => {
+        const text = overlay?.get(name);
+        if (text !== undefined) {
+            if (!fresh.has(name))
+                fresh.set(name, ts.createSourceFile(name, text, languageVersion, true));
+            return fresh.get(name);
+        }
+        if (!shared.has(name)) {
+            shared.set(name, getSourceFile.call(tsHost, name, languageVersion, ...rest));
+        }
+        return shared.get(name);
+    };
+    const ngHost = cli.createCompilerHost({ options, tsHost });
+    if (overlay) {
+        // With `oldProgram` reuse ngtsc re-analyzes a component only if it is told which resources changed.
+        const resources = new Set([...overlay.keys()].filter((name) => !/\.[cm]?tsx?$/u.test(name)));
+        ngHost.getModifiedResourceFiles = () => resources;
+    }
+    return ngHost;
+}
+async function checkSide(toolchain, config, request, overlay, shared, oldProgram) {
+    const host = createCheckHost(toolchain, config.options, overlay, shared);
+    const program = new toolchain.cli.NgtscProgram(config.rootNames, config.options, host, oldProgram);
+    await program.loadNgStructureAsync();
+    const compiler = program.compiler;
+    if (typeof compiler?.getComponentsWithTemplateFile !== "function")
+        return "unsupported";
+    const scope = new Set(request.templates);
+    for (const template of request.templates) {
+        for (const component of compiler.getComponentsWithTemplateFile(template)) {
+            scope.add(component.getSourceFile().fileName);
+        }
+    }
+    const root = path.dirname(request.tsconfig);
+    const diagnostics = program
+        .getNgSemanticDiagnostics()
+        .filter((diagnostic) => diagnostic.file && isInScope(diagnostic.file.fileName, scope))
+        .map((diagnostic) => toWireDiagnostic(toolchain.ts, root, diagnostic));
+    return { program, diagnostics };
+}
+const fail = (reason) => ({
+    v: 1,
+    ok: false,
+    reason,
+});
+/** Runs ngtsc on the disk state, then on disk plus overlay, and returns both scoped lists. */
+export async function runTemplateTypeCheck(request, load = loadToolchain) {
+    try {
+        const toolchain = await load(request.cliEntry);
+        if (!probeCompilerApi(toolchain.cli))
+            return fail("compiler_unsupported");
+        const read = toolchain.cli.readConfiguration(request.tsconfig);
+        if (read.errors.length > 0)
+            return fail("check_failed");
+        const config = { options: withNoEmit(read.options), rootNames: read.rootNames };
+        const shared = new Map();
+        const overlay = new Map(request.overlay.map((file) => [file.absolutePath, file.text]));
+        const before = await checkSide(toolchain, config, request, undefined, shared, undefined);
+        if (before === "unsupported")
+            return fail("compiler_unsupported");
+        if (before.diagnostics.length > request.maxDiagnostics)
+            return fail("work_exhausted");
+        const after = await checkSide(toolchain, config, request, overlay, shared, before.program);
+        if (after === "unsupported")
+            return fail("compiler_unsupported");
+        if (after.diagnostics.length > request.maxDiagnostics)
+            return fail("work_exhausted");
+        return { v: 1, ok: true, before: before.diagnostics, after: after.diagnostics };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "";
+        return fail(message.startsWith("The Angular Compiler requires TypeScript")
+            ? "typescript_incompatible"
+            : "check_failed");
+    }
+}

package/dist/services/angular-template-typecheck-protocol.js

@@ -0,0 +1,75 @@
+import path from "node:path";
+import { z } from "zod";
+/** Caps shared by both ends of the one-shot IPC channel (v1). */
+export const MAX_WIRE_DIAGNOSTICS = 5000;
+export const MAX_OVERLAY_BYTES = 32 * 1024 * 1024;
+export const MAX_TEMPLATES = 2000;
+export const MAX_OVERLAY_FILES = 10_000;
+const MAX_PATH_CHARS = 4096;
+export const MAX_MESSAGE_CHARS = 8192;
+const absolutePath = z
+    .string()
+    .max(MAX_PATH_CHARS)
+    .refine((value) => path.isAbsolute(value), "must be an absolute path");
+export const RequestSchema = z
+    .object({
+    v: z.literal(1),
+    tsconfig: absolutePath,
+    cliEntry: absolutePath,
+    templates: z.array(absolutePath).max(MAX_TEMPLATES),
+    overlay: z
+        .array(z.object({ absolutePath, text: z.string() }).strict())
+        .max(MAX_OVERLAY_FILES)
+        .refine((files) => files.reduce((total, file) => total + Buffer.byteLength(file.text, "utf8"), 0) <=
+        MAX_OVERLAY_BYTES, "overlay exceeds the byte cap"),
+    maxDiagnostics: z.number().int().min(1).max(MAX_WIRE_DIAGNOSTICS),
+})
+    .strict();
+const position = z.number().int().nonnegative().nullable();
+export const WireDiagnosticSchema = z
+    .object({
+    code: z.number().int(),
+    category: z.string().max(32),
+    /** Project-relative path. */
+    file: z.string().max(MAX_PATH_CHARS),
+    line: position,
+    column: position,
+    message: z.string().max(MAX_MESSAGE_CHARS),
+    start: position,
+    length: position,
+})
+    .strict();
+/** Only a successful reply carries diagnostics, so a non-completed status can never include any. */
+export const ResponseSchema = z.discriminatedUnion("ok", [
+    z
+        .object({
+        v: z.literal(1),
+        ok: z.literal(true),
+        before: z.array(WireDiagnosticSchema).max(MAX_WIRE_DIAGNOSTICS),
+        after: z.array(WireDiagnosticSchema).max(MAX_WIRE_DIAGNOSTICS),
+    })
+        .strict(),
+    z
+        .object({
+        v: z.literal(1),
+        ok: z.literal(false),
+        reason: z.enum([
+            "compiler_unsupported",
+            "typescript_incompatible",
+            "work_exhausted",
+            "check_failed",
+        ]),
+    })
+        .strict(),
+]);
+/** Separates an over-cap reply (work bound) from a malformed one (check failure). */
+export function parseResponse(value) {
+    if (typeof value === "object" && value !== null) {
+        const { before, after } = value;
+        const oversizedSide = (side) => Array.isArray(side) && side.length > MAX_WIRE_DIAGNOSTICS;
+        if (oversizedSide(before) || oversizedSide(after))
+            return { status: "oversized" };
+    }
+    const parsed = ResponseSchema.safeParse(value);
+    return parsed.success ? { status: "valid", response: parsed.data } : { status: "malformed" };
+}

package/dist/services/angular-template-typecheck.js

@@ -0,0 +1,262 @@
+import { fork } from "node:child_process";
+import { readFileSync, realpathSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { isSupportedVersion, isUnderAncestorNodeModules, isWithin, rangeVerdict, resolveFrom, } from "./angular-package-resolution.js";
+import { MAX_OVERLAY_BYTES, MAX_OVERLAY_FILES, MAX_TEMPLATES, MAX_WIRE_DIAGNOSTICS, parseResponse, } from "./angular-template-typecheck-protocol.js";
+import { compareObservedDiagnostics, } from "./diagnostics.js";
+import { NO_REQUEST_CONTEXT, RequestContextError } from "./request-context.js";
+const UNSUPPORTED = { ok: false, reason: "compiler_unsupported" };
+/** Locates an installed package through the shared guard, or reports why it cannot be trusted. */
+function locatePackage(tsConfigFilePath, name, projectDir) {
+    const manifestPath = resolveFrom(tsConfigFilePath, `${name}/package.json`);
+    if (!manifestPath) {
+        try {
+            createRequire(tsConfigFilePath).resolve(`${name}/package.json`);
+        }
+        catch (error) {
+            if (error.code === "MODULE_NOT_FOUND")
+                return "missing";
+        }
+        return "unsupported";
+    }
+    try {
+        const dir = realpathSync(path.dirname(manifestPath));
+        if (!isUnderAncestorNodeModules(dir, projectDir))
+            return "unsupported";
+        const manifest = JSON.parse(readFileSync(path.join(dir, "package.json"), "utf8"));
+        return manifest?.name === name ? { dir, manifest } : "unsupported";
+    }
+    catch {
+        return "unsupported";
+    }
+}
+function majorOf(version) {
+    return Number(String(version).split(".")[0]);
+}
+/** In-process checks before any spawn; TypeScript is resolved from the compiler-cli, as ngtsc does. */
+export function preflightTemplateTypeCheck(tsConfigFilePath) {
+    let projectDir;
+    try {
+        projectDir = realpathSync(path.dirname(tsConfigFilePath));
+    }
+    catch {
+        return UNSUPPORTED;
+    }
+    const cli = locatePackage(tsConfigFilePath, "@angular/compiler-cli", projectDir);
+    if (cli === "missing")
+        return { ok: false, reason: "compiler_cli_missing" };
+    if (cli === "unsupported")
+        return UNSUPPORTED;
+    const compiler = locatePackage(tsConfigFilePath, "@angular/compiler", projectDir);
+    const core = locatePackage(tsConfigFilePath, "@angular/core", projectDir);
+    if (typeof compiler === "string" || typeof core === "string")
+        return UNSUPPORTED;
+    const version = cli.manifest.version;
+    if (!isSupportedVersion(version) || compiler.manifest.version !== version)
+        return UNSUPPORTED;
+    if (!isSupportedVersion(core.manifest.version) ||
+        majorOf(core.manifest.version) !== majorOf(version)) {
+        return UNSUPPORTED;
+    }
+    const entry = resolveFrom(tsConfigFilePath, "@angular/compiler-cli");
+    let cliEntry;
+    try {
+        cliEntry = entry && realpathSync(entry);
+    }
+    catch {
+        return UNSUPPORTED;
+    }
+    if (!cliEntry || !isWithin(cli.dir, cliEntry))
+        return UNSUPPORTED;
+    const peer = cli.manifest.peerDependencies?.typescript;
+    const typescript = resolveFrom(path.join(cli.dir, "package.json"), "typescript/package.json");
+    if (typeof peer !== "string")
+        return UNSUPPORTED;
+    if (!typescript)
+        return { ok: false, reason: "typescript_incompatible" };
+    let typescriptVersion;
+    try {
+        typescriptVersion = JSON.parse(readFileSync(typescript, "utf8")).version;
+    }
+    catch {
+        return UNSUPPORTED;
+    }
+    const verdict = rangeVerdict(String(typescriptVersion), peer);
+    if (verdict === "unsupported")
+        return UNSUPPORTED;
+    if (verdict === "unsatisfied")
+        return { ok: false, reason: "typescript_incompatible" };
+    return { ok: true, cliDir: cli.dir, cliEntry };
+}
+function emptyDelta(status, reason) {
+    return { status, reason, added: [], removed: [], addedErrors: [] };
+}
+const MAX_CHECK_MS = 30_000;
+const MIN_CHECK_MS = 2_000;
+const RESERVE_MS = 10_000;
+const CHILD_HEAP_MB = 1024;
+const EXIT_SETTLE_MS = 500;
+const OOM_EXIT_CODE = 134;
+const DEFAULT_ENTRY = fileURLToPath(new URL("../angular-template-typecheck-entry.js", import.meta.url));
+const UNBOUNDED_CONTEXT = {
+    signal: NO_REQUEST_CONTEXT.signal,
+    checkpoint: () => NO_REQUEST_CONTEXT.checkpoint(),
+    remainingMs: () => MAX_CHECK_MS + RESERVE_MS,
+};
+/** Time the child may run: capped, and leaving a reserve for the rest of the operation. */
+export function checkBudgetMs(remainingMs) {
+    return Math.min(MAX_CHECK_MS, remainingMs - RESERVE_MS);
+}
+function outcomeOf(code, signal, reply) {
+    if (signal === "SIGABRT" || code === OOM_EXIT_CODE) {
+        return { kind: "reason", reason: "work_exhausted" };
+    }
+    if (code !== 0)
+        return { kind: "reason", reason: "check_failed" };
+    const parsed = parseResponse(reply);
+    if (parsed.status === "valid")
+        return { kind: "reply", response: parsed.response };
+    return {
+        kind: "reason",
+        reason: parsed.status === "oversized" ? "work_exhausted" : "check_failed",
+    };
+}
+/** Runs one child to completion; it is always reaped before this settles. */
+function runChild(request, budgetMs, ctx, deps) {
+    return new Promise((resolve, reject) => {
+        let child;
+        try {
+            child = (deps.spawn ?? fork)(deps.entry ?? DEFAULT_ENTRY, [], {
+                execPath: process.execPath,
+                execArgv: [`--max-old-space-size=${CHILD_HEAP_MB}`],
+                env: {},
+                serialization: "advanced",
+                stdio: ["ignore", "ignore", "ignore", "ipc"],
+            });
+        }
+        catch {
+            return resolve({ kind: "reason", reason: "check_failed" });
+        }
+        let reply;
+        let killedFor;
+        let failed = false;
+        let settled = false;
+        const kill = (why) => {
+            killedFor ??= why;
+            child.kill("SIGKILL");
+        };
+        const settle = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            ctx.signal.removeEventListener("abort", onAbort);
+            if (result instanceof Error)
+                reject(result);
+            else
+                resolve(result);
+        };
+        const onAbort = () => kill("abort");
+        const timer = setTimeout(() => kill("deadline"), budgetMs);
+        ctx.signal.addEventListener("abort", onAbort, { once: true });
+        child.once("message", (message) => {
+            reply = message;
+        });
+        child.once("error", () => {
+            failed = true;
+            // No pid means the spawn itself failed and no exit will follow; otherwise reap first.
+            if (child.pid === undefined)
+                settle({ kind: "reason", reason: "check_failed" });
+            else
+                child.kill("SIGKILL");
+        });
+        child.once("exit", (code, signal) => {
+            const finish = () => {
+                if (killedFor === "abort")
+                    settle(abortError(ctx));
+                else if (killedFor === "deadline")
+                    settle({ kind: "deadline" });
+                else if (failed)
+                    settle({ kind: "reason", reason: "check_failed" });
+                else
+                    settle(outcomeOf(code, signal, reply));
+            };
+            // Pending IPC messages are delivered before the channel reports closed.
+            if (!child.connected)
+                return finish();
+            child.once("disconnect", finish);
+            setTimeout(finish, EXIT_SETTLE_MS).unref();
+        });
+        if (ctx.signal.aborted)
+            return onAbort();
+        child.send(request, () => undefined);
+    });
+}
+function abortError(ctx) {
+    try {
+        ctx.checkpoint();
+    }
+    catch (error) {
+        return error;
+    }
+    return new RequestContextError("REQUEST_CANCELLED");
+}
+function observations(diagnostics) {
+    return diagnostics.map(({ start, length, ...shown }, ordinal) => ({
+        public: {
+            code: shown.code,
+            category: shown.category,
+            file: shown.file,
+            line: shown.line,
+            column: shown.column,
+            message: shown.message,
+        },
+        start,
+        length,
+        ordinal,
+    }));
+}
+function diagnosticsOf(response, changes, ctx) {
+    if (!response.ok) {
+        const reason = response.reason;
+        return emptyDelta(reason === "compiler_unsupported" || reason === "typescript_incompatible"
+            ? "unavailable"
+            : "unfinished", reason);
+    }
+    const delta = compareObservedDiagnostics(observations(response.before), observations(response.after), changes, ctx);
+    return { status: "completed", ...delta };
+}
+/**
+ * Entry point of the template type check: preflight and limits in-process, then one forked child
+ * under a wall-clock budget. A client abort kills the child and rethrows `REQUEST_CANCELLED`.
+ */
+export async function checkTemplateTypes(input, ctx = UNBOUNDED_CONTEXT, deps = {}) {
+    ctx.checkpoint();
+    const preflight = preflightTemplateTypeCheck(input.tsConfigFilePath);
+    if (!preflight.ok)
+        return emptyDelta("unavailable", preflight.reason);
+    const overlayBytes = input.overlay.reduce((total, file) => total + Buffer.byteLength(file.text, "utf8"), 0);
+    if (input.templates.length > MAX_TEMPLATES ||
+        input.overlay.length > MAX_OVERLAY_FILES ||
+        overlayBytes > MAX_OVERLAY_BYTES) {
+        return emptyDelta("unfinished", "work_exhausted");
+    }
+    const budgetMs = checkBudgetMs(ctx.remainingMs());
+    if (budgetMs < MIN_CHECK_MS)
+        return emptyDelta("unfinished", "deadline");
+    const outcome = await runChild({
+        v: 1,
+        tsconfig: input.tsConfigFilePath,
+        cliEntry: preflight.cliEntry,
+        templates: [...input.templates],
+        overlay: input.overlay.map(({ absolutePath, text }) => ({ absolutePath, text })),
+        maxDiagnostics: MAX_WIRE_DIAGNOSTICS,
+    }, budgetMs, ctx, deps);
+    if (outcome.kind === "deadline")
+        return emptyDelta("unfinished", "deadline");
+    if (outcome.kind === "reason")
+        return emptyDelta("unfinished", outcome.reason);
+    return diagnosticsOf(outcome.response, input.changes, ctx);
+}