ast-mcp-server 0.14.3 → 0.15.0

package/CHANGELOG.md

@@ -6,7 +6,30 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
-## [0.14.3] — not yet published (2026-10-28)
+## [0.15.0] — not yet published (2026-11-04)
+
+### Added
+
+- Angular template references (#370). In projects where `@angular/core` resolves, `ast_find_references` reports usages of a component member in its external (`templateUrl`) and inline templates. Items carry `origin` (`compiler`, `template_external`, `template_inline`), and the response adds `template_coverage` and `template_reference_count`; `reference_count` stays TypeScript-only and `total` counts both. Only `template_coverage.status: "completed"` supports an absence claim.
+- `ast_rename_symbol` rewrites external Angular templates in the same reviewed, hash-bound plan, with rollback covering the templates. It returns `INCOMPLETE_EVIDENCE` when coverage is `unfinished` or `unsupported`, and `MUTATION_BLOCKED` for inline-template usages, a new name that collides with a template local, or `$any`. Apply remains sequential, not globally atomic.
+- `@angular/compiler` (`>=20.0.0 <23.0.0`) is an optional peer dependency resolved from the target project; it is never bundled. `yarn test:package` now asserts it is absent from the packed `dependencies` and from a consumer install. Yarn PnP projects without `node_modules` report `unfinished` coverage.
+- Workspace snapshots and the file watcher include Angular template files when Angular is detected; workspaces without `@angular/core` hash identically to before.
+
+### Changed
+
+- Documented limits: `ast_explore` references stay TypeScript-only (template evidence is tracked as a follow-up issue) and diagnostics, including the post-apply delta, stay TypeScript-only, so template-only errors are not detected.
+- The `ast_find_references` and `ast_rename_symbol` descriptions now state the Angular template behavior: `ast_find_references` reports template usages tagged by origin with a `template_coverage` verdict and does not diagnose template errors, and `ast_rename_symbol` also rewrites external templates hash-bound to the workspace snapshot while diagnostics stay TypeScript-only. Input and output schemas are unchanged. The dsh-adapter smoke now declares both descriptions in `test/fixtures/declared-tool-contracts.json` (every other tool must still equal the public 0.13.0 contract), and the tool-inventory, registry-consumer and canary digests were re-baselined (#383).
+
+- The issue #103 `node:test` suites now run once per CI run in a dedicated `fixture` job on pinned Node 24.16.0, in parallel with `quality`, instead of once per `quality` matrix entry; the workflow policy check pins both job chains (#368).
+- The CI `quality` job now runs every committed `node:test` suite from the issue #103 chain: `npm-pack-json`, `acquisition`, `setup`, `test-lock`, `prepared-runner` and `prepared-install-build` join the exact-Node fixture command after the four suites it already ran, and the workflow policy check pins the extended command (#364).
+
+### Fixed
+
+- A `project_root` directory whose `tsconfig.json` is solution-style (`"files": []` or no `files`/`include`, plus a non-empty `references` array, as Angular CLI and other `tsc -b` layouts ship) no longer loads as a silent empty project with `source_count: 0`. Resolution now fails closed with a `PROJECT_NOT_FOUND` error that names the referenced configs and asks for one of them as `project_root`; passing a referenced `tsconfig.*.json` file directly is unchanged, and references are never followed automatically (#389).
+- `ast_find_references` and `ast_rename_symbol` no longer count the declaration identifier as a reference. When a member was used before its declaration in source order, ts-morph returned the declaration identifier among the references, so the declaration appeared twice and `reference_count` was inflated by one. The declaration is now reported once and `reference_count` counts only real references (#390).
+- The dsh-adapter smoke no longer reports a surviving Harness process tree when descendants are still exiting after a clean shutdown on a loaded runner. The lifecycle assertion now polls the owned process tree with a bounded ten-second deadline, and when survivors remain it keeps failing but lists each PID with its command line and parent chain (#363).
+
+## [0.14.3] — published to `next`, verification failed, not promoted (2026-11-01)
 
 ### Security
 
@@ -17,6 +40,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 - `ast_get_impact` with `direction: "incoming"` no longer returns an empty, incomplete result on larger projects. The compiler resolver now finds incoming references through the language service instead of walking every AST node, so its work scales with the number of references rather than the project size, and the project-wide computed-call scan runs on its own budget so it can no longer starve the reference lookup (#353).
 
+### Release status
+
+- npm published these immutable bytes under `next` with provenance and the expected Git commit. Public-registry verification then failed because the consumer install resolves `ts-morph@28.0.0 → @ts-morph/common@0.29.0 → minimatch@10.2.6`, vulnerable to GHSA-g3hv-75wg-m249, and the root `minimatch` resolution does not reach consumers (#361, upstream dsherret/ts-morph#1697); `0.14.3` was never promoted to `latest`, tagged in Git, or released on GitHub.
+
 ## [0.14.2] — published to `latest` and `next`, registry verified (2026-10-28)
 
 ### Security

package/README.md

@@ -79,6 +79,24 @@ Impact has two independent completeness channels:
 
 These fields are additive: existing edge shapes, kind strings, defaults, and public errors remain stable. MCP `ast_get_impact` JSON and TOON represent the same logical coverage/work result; candidate MCP output remains canonical JSON, while read-only batch output may encode that same candidate result as TOON. Property, element, dynamic, computed-key, and external-alternative dispatch remains edge-free and unfinished—this contract does not certify the deferred #219 or #220 classifiers.
 
+### Angular templates
+
+In an Angular project, `ast_find_references` also reports usages of a component member in its template, and `ast_rename_symbol` rewrites external templates as part of the same reviewed plan. This needs the project's own `@angular/compiler`. The server does not bundle it: it is an optional peer dependency (`>=20.0.0 <23.0.0`, majors 20 to 22) that Angular projects already install next to `@angular/core`. Nothing changes for projects without `@angular/core`.
+
+Install or align it in the target project when the response reports `compiler_missing` or `compiler_unsupported`:
+
+```bash
+yarn add --dev @angular/compiler@^21   # or npm install --save-dev @angular/compiler@^21
+```
+
+Template evidence is explicit about what it proves:
+
+- Each item carries `origin` (`compiler`, `template_external`, `template_inline`); the response adds `template_coverage` and `template_reference_count`. Only `template_coverage.status: "completed"` supports a claim that no template usage exists.
+- Rename returns `INCOMPLETE_EVIDENCE` when coverage is `unfinished` or `unsupported`, and `MUTATION_BLOCKED` for inline templates, a new name that collides with a template local, or `$any`. Inline templates are never rewritten.
+- `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.
+- 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
 
 - **Less context:** the agent retrieves the smallest structural unit that answers the question instead of loading the complete file by default.
@@ -333,7 +351,7 @@ hermes mcp add ast --command node --env AST_MCP_APPLY_GUARD=allow --args /absolu
 hermes mcp test ast
 ```
 
-Project-scoped tools accept `project_root`, either the project directory or an explicit `tsconfig.json` path. The server contains no repository-specific paths.
+Project-scoped tools accept `project_root`, either the project directory or an explicit `tsconfig.json` path. A directory whose `tsconfig.json` is solution-style (no `files`/`include`, only `references`, as Angular CLI generates) is rejected with an error naming the referenced configs; pass one of them, such as `tsconfig.app.json`, as `project_root` instead. The server contains no repository-specific paths.
 
 ### DeepSeek Harness (Developer Preview)
 
@@ -353,7 +371,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.14.3.tgz
+dsh plugin --profile web add ./ast-mcp-server-0.15.0.tgz
 ```
 
 The first supported surface is **reads + prepare + preview**. Every apply path is
@@ -374,8 +392,14 @@ the official bridge drops MCP tool annotations
 integrity, packs the candidate, builds the pinned Harness and bridge from source, and proves
 `tools.mode: native`, the 15-tool scoped catalog, complete executable input schemas,
 read/prepare/preview, all three invalid `ast_explore` combinations, apply absence, and rejected direct apply.
-The schema gate freezes the public empty `ast_explore` contract as RED, requires the candidate
-registry/native definitions to match, and hashes all 14 unaffected model schemas. A deterministic
+The schema gate freezes the public empty `ast_explore` contract as RED and requires the candidate
+registry/native definitions to match. For every other tool, the candidate description and input
+schema must equal the public baseline or its committed declaration in
+`test/fixtures/declared-tool-contracts.json`; a declaration that equals the public contract fails
+as stale, and no tool may loosen `additionalProperties`. To change a tool contract, declare the new
+description and semantic input schema in that fixture, change the source, and re-baseline the three
+inventory pins (`test/fixtures/tool-inventory.json`, `scripts/registry-consumer-smoke.mjs`,
+`scripts/canary-local-mcp.mjs`), taking the canary value from its own run. A deterministic
 two-step model then invokes
 `mcp__ast__ast_get_project_status` through a real headless Agent/Session: the public baseline
 must reproduce the empty-result marker, while the corrected candidate must deliver lossless

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.14.3.tgz`
+# (`baseUrl`), where `dsh plugin --profile <name> add ./ast-mcp-server-0.15.0.tgz`
 # installs a locally packed package as a dependency.
 #
 # First-slice surface: reads + prepare + preview. Every apply path is denied

package/dist/services/angular-templates.js

@@ -0,0 +1,509 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { readFile, stat } from "node:fs/promises";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { Node, SyntaxKind } from "ts-morph";
+import { assertSafeOperationFile } from "./safe-file.js";
+const MAX_TEMPLATE_BYTES = 512 * 1024;
+const MAX_TEMPLATE_NODES = 100_000;
+const CHECKPOINT_EVERY_NODES = 1000;
+const MIN_COMPILER_MAJOR = 20;
+const MAX_COMPILER_MAJOR = 22;
+const TWO_WAY_BINDING = 5; // BindingType.TwoWay, stable across supported majors
+const TWO_WAY_EVENT = 2; // ParsedEventType.TwoWay, stable across supported majors
+const NOT_APPLICABLE = { coverage: { status: "not_applicable" }, usages: [] };
+const ASSIGNMENT_OPERATION = /^(?:=|(?:\*\*|&&|\|\||\?\?|<<|>>>|>>|[+\-*/%&|^])=)$/u;
+const compilerCache = new Map();
+function resolveFrom(tsConfigFilePath, request) {
+    try {
+        const resolved = createRequire(tsConfigFilePath).resolve(request);
+        return existsSync(resolved) ? resolved : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+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. */
+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));
+}
+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;
+}
+async function loadCompiler(tsConfigFilePath) {
+    const unsupported = { reason: "compiler_unsupported" };
+    const manifestPath = resolveFrom(tsConfigFilePath, "@angular/compiler/package.json");
+    if (!manifestPath) {
+        try {
+            createRequire(tsConfigFilePath).resolve("@angular/compiler/package.json");
+        }
+        catch (error) {
+            if (error.code === "MODULE_NOT_FOUND") {
+                return { reason: "compiler_missing" };
+            }
+        }
+        return unsupported;
+    }
+    try {
+        const packageDir = realpathSync(path.dirname(manifestPath));
+        if (!isUnderAncestorNodeModules(packageDir, realpathSync(path.dirname(tsConfigFilePath)))) {
+            return unsupported;
+        }
+        const manifest = JSON.parse(readFileSync(path.join(packageDir, "package.json"), "utf8"));
+        const entry = resolveFrom(tsConfigFilePath, "@angular/compiler");
+        const realEntry = entry && realpathSync(entry);
+        if (manifest.name !== "@angular/compiler" || !isSupportedVersion(manifest.version)) {
+            return unsupported;
+        }
+        if (!realEntry || !isWithin(packageDir, realEntry))
+            return unsupported;
+        const key = `${realEntry}@${manifest.version}`;
+        let loading = compilerCache.get(key);
+        if (!loading) {
+            loading = import(pathToFileURL(realEntry).href);
+            compilerCache.set(key, loading);
+        }
+        const compiler = await loading.catch((error) => {
+            compilerCache.delete(key);
+            throw error;
+        });
+        const hasWriteNode = compiler.Binary !== undefined || compiler.PropertyWrite !== undefined;
+        const complete = hasWriteNode &&
+            [
+                compiler.parseTemplate,
+                compiler.tmplAstVisitAll,
+                compiler.TmplAstRecursiveVisitor,
+                compiler.RecursiveAstVisitor,
+                compiler.ImplicitReceiver,
+                compiler.ThisReceiver,
+                compiler.PropertyRead,
+                compiler.Call,
+            ].every((member) => typeof member === "function");
+        return complete ? { compiler } : unsupported;
+    }
+    catch {
+        return unsupported;
+    }
+}
+function hasAngularCore(context) {
+    return resolveFrom(context.tsConfigFilePath, "@angular/core/package.json") !== undefined;
+}
+function isComponentDecorator(decorator) {
+    const callee = decorator.getCallExpression()?.getExpression();
+    if (!callee)
+        return false;
+    return decorator
+        .getSourceFile()
+        .getImportDeclarations()
+        .filter((declaration) => declaration.getModuleSpecifierValue() === "@angular/core")
+        .some((declaration) => {
+        const namespace = declaration.getNamespaceImport();
+        if (Node.isPropertyAccessExpression(callee)) {
+            return (callee.getName() === "Component" &&
+                callee.getExpression().getText() === namespace?.getText());
+        }
+        return declaration
+            .getNamedImports()
+            .some((specifier) => specifier.getName() === "Component" &&
+            (specifier.getAliasNode()?.getText() ?? "Component") === callee.getText());
+    });
+}
+function componentDecorator(cls) {
+    return cls.getDecorators().find(isComponentDecorator);
+}
+/** Finds the template of a component class from literal metadata only. */
+function locateTemplate(cls) {
+    const unresolved = { reason: "template_unresolved" };
+    const metadata = componentDecorator(cls)?.getArguments()[0];
+    if (!Node.isObjectLiteralExpression(metadata) || metadata.getProperty("interpolation")) {
+        return unresolved;
+    }
+    const initializer = (name) => {
+        const property = metadata.getProperty(name);
+        if (!property)
+            return undefined;
+        return Node.isPropertyAssignment(property) ? (property.getInitializer() ?? null) : null;
+    };
+    const literalText = (node) => {
+        const literal = node ?? undefined;
+        return Node.isStringLiteral(literal) || Node.isNoSubstitutionTemplateLiteral(literal)
+            ? literal.getLiteralText()
+            : undefined;
+    };
+    const sourceFile = cls.getSourceFile();
+    const templateUrl = initializer("templateUrl");
+    if (templateUrl !== undefined) {
+        const url = literalText(templateUrl);
+        if (url === undefined)
+            return unresolved;
+        return {
+            container: "external",
+            absolutePath: path.resolve(path.dirname(sourceFile.getFilePath()), url),
+        };
+    }
+    const template = initializer("template");
+    const text = literalText(template);
+    if (!template || text === undefined)
+        return unresolved;
+    const offset = template.getStart() + 1;
+    // Escapes or CRLF make cooked text diverge from source offsets, so spans would be inexact.
+    if (sourceFile.getFullText().slice(offset, template.getEnd() - 1) !== text)
+        return unresolved;
+    return { container: "inline", absolutePath: sourceFile.getFilePath(), text, offset };
+}
+function checkTemplatePath(projectRoot, absolutePath) {
+    if (!isWithin(projectRoot, absolutePath) || absolutePath === projectRoot)
+        return "template_unsafe";
+    try {
+        assertSafeOperationFile(projectRoot, absolutePath, path.relative(projectRoot, absolutePath));
+        return undefined;
+    }
+    catch (error) {
+        return error.code === "ENOENT"
+            ? "template_unresolved"
+            : "template_unsafe";
+    }
+}
+function componentClasses(context) {
+    return context.project
+        .getSourceFiles()
+        .filter((file) => !file.isDeclarationFile() &&
+        !file.isFromExternalLibrary() &&
+        file.getFullText().includes("Component"))
+        .flatMap((file) => file.getDescendantsOfKind(SyntaxKind.ClassDeclaration))
+        .filter((cls) => componentDecorator(cls) !== undefined);
+}
+/** Existing, contained external template files of every component. Sync and compiler-free. */
+export function listTemplateFiles(context) {
+    if (!hasAngularCore(context))
+        return [];
+    const files = new Set();
+    for (const cls of componentClasses(context)) {
+        const located = locateTemplate(cls);
+        if ("container" in located &&
+            located.container === "external" &&
+            checkTemplatePath(context.projectRoot, located.absolutePath) === undefined) {
+            files.add(located.absolutePath);
+        }
+    }
+    return [...files].sort();
+}
+function memberOwner(node) {
+    let owner;
+    if (Node.isParameterDeclaration(node)) {
+        owner = node.isParameterProperty() ? node.getParent()?.getParent() : undefined;
+    }
+    else if (Node.isPropertyDeclaration(node) ||
+        Node.isMethodDeclaration(node) ||
+        Node.isGetAccessorDeclaration(node) ||
+        Node.isSetAccessorDeclaration(node)) {
+        owner = node.isStatic() ? undefined : node.getParent();
+    }
+    const nameNode = node.getNameNode?.();
+    return Node.isClassDeclaration(owner) && Node.isIdentifier(nameNode)
+        ? { cls: owner, name: nameNode.getText() }
+        : undefined;
+}
+function hasDerivedComponent(context, cls) {
+    const identity = (node) => `${node.getSourceFile().getFilePath()}:${node.getPos()}`;
+    const target = identity(cls);
+    return componentClasses(context).some((candidate) => {
+        let base = candidate.getBaseClass();
+        for (let depth = 0; base && depth < 32; depth += 1) {
+            if (identity(base) === target)
+                return true;
+            base = base.getBaseClass();
+        }
+        return false;
+    });
+}
+class WorkExhausted extends Error {
+}
+/** Walks parsed template nodes with a scope stack so template-local names shadow members. */
+function extractUsages(compiler, nodes, memberName, rc) {
+    const usages = new Map();
+    const scopes = [];
+    let visited = 0;
+    const tick = () => {
+        if (++visited > MAX_TEMPLATE_NODES)
+            throw new WorkExhausted();
+        if (visited % CHECKPOINT_EVERY_NODES === 0)
+            rc.checkpoint();
+    };
+    const isLocal = (name) => scopes.some((scope) => scope.has(name));
+    const record = (ast, kind) => {
+        const key = `${ast.nameSpan.start}:${ast.nameSpan.end}`;
+        const merged = usages.get(key)?.kind === "TemplatePropertyWrite" ? "TemplatePropertyWrite" : kind;
+        usages.set(key, {
+            start: ast.nameSpan.start,
+            end: ast.nameSpan.end,
+            kind: merged,
+            localsInScope: [...new Set(scopes.flatMap((scope) => [...scope]))].sort(),
+        });
+    };
+    // Explicit `this.` bypasses template locals; ThisReceiver only extends ImplicitReceiver in some majors.
+    const isMemberReceiver = (receiver) => receiver instanceof compiler.ThisReceiver ||
+        (receiver instanceof compiler.ImplicitReceiver && !isLocal(memberName));
+    const isMember = (ast) => ast instanceof compiler.PropertyRead &&
+        ast.name === memberName &&
+        isMemberReceiver(ast.receiver);
+    class Expressions extends compiler.RecursiveAstVisitor {
+        writeRoot;
+        visit(ast, context) {
+            tick();
+            ast.visit(this, context);
+        }
+        visitPropertyRead(ast, context) {
+            if (isMember(ast))
+                record(ast, ast === this.writeRoot ? "TemplatePropertyWrite" : "TemplatePropertyRead");
+            super.visitPropertyRead(ast, context);
+        }
+        visitCall(ast, context) {
+            if (!isMember(ast.receiver))
+                return super.visitCall(ast, context);
+            record(ast.receiver, "TemplateCall");
+            ast.args.forEach((arg) => this.visit(arg, context));
+        }
+        visitSafeCall(ast, context) {
+            this.visitCall(ast, context);
+        }
+        visitBinary(ast, context) {
+            if (!ASSIGNMENT_OPERATION.test(ast.operation) || !isMember(ast.left)) {
+                return super.visitBinary(ast, context);
+            }
+            record(ast.left, "TemplatePropertyWrite");
+            this.visit(ast.right, context);
+        }
+        visitPropertyWrite(ast, context) {
+            if (ast.name === memberName && isMemberReceiver(ast.receiver)) {
+                record(ast, "TemplatePropertyWrite");
+            }
+            this.visit(ast.receiver, context);
+            this.visit(ast.value, context);
+        }
+        visitArrowFunction(ast, context) {
+            scopes.push(new Set(ast.parameters.map((parameter) => parameter.name)));
+            this.visit(ast.body, context);
+            scopes.pop();
+        }
+    }
+    const expressions = new Expressions();
+    // References belong to the view that declares them and are visible before the declaration.
+    class References extends compiler.TmplAstRecursiveVisitor {
+        names = [];
+        visitReference(reference) {
+            this.names.push(reference.name);
+        }
+        visitTemplate(template) {
+            template.references.forEach((reference) => this.visitReference(reference));
+        }
+        visitIfBlock = () => { };
+        visitForLoopBlock = () => { };
+        visitSwitchBlock = () => { };
+        visitDeferredBlock = () => { };
+    }
+    const referencesOf = (children) => {
+        const collector = new References();
+        compiler.tmplAstVisitAll(collector, children);
+        return collector.names;
+    };
+    class Templates extends compiler.TmplAstRecursiveVisitor {
+        visit(node) {
+            tick();
+            node.visit(this);
+        }
+        view(locals, children, before) {
+            const names = [...locals, ...referencesOf(children)].filter((name) => !!name);
+            scopes.push(new Set(names));
+            before?.();
+            compiler.tmplAstVisitAll(this, children);
+            scopes.pop();
+        }
+        expression(value, writeRoot) {
+            if (!value?.ast)
+                return;
+            expressions.writeRoot = writeRoot && value.ast;
+            expressions.visit(value.ast);
+            expressions.writeRoot = undefined;
+        }
+        visitBoundText(text) {
+            this.expression(text.value);
+        }
+        visitBoundAttribute(attribute) {
+            this.expression(attribute.value, attribute.type === TWO_WAY_BINDING);
+        }
+        visitBoundEvent(event) {
+            if (event.type === TWO_WAY_EVENT)
+                return; // covered by the paired two-way input
+            scopes.push(new Set(["$event"]));
+            this.expression(event.handler);
+            scopes.pop();
+        }
+        visitTemplate(template) {
+            for (const list of [
+                template.templateAttrs,
+                template.inputs,
+                template.outputs,
+                template.directives,
+            ]) {
+                compiler.tmplAstVisitAll(this, list ?? []);
+            }
+            this.view(template.variables.map((variable) => variable.name), template.children);
+        }
+        visitIfBlockBranch(branch) {
+            this.expression(branch.expression);
+            this.view([branch.expressionAlias?.name], branch.children);
+        }
+        visitForLoopBlock(block) {
+            this.expression(block.expression);
+            const locals = [
+                block.item.name,
+                ...block.contextVariables.map((variable) => variable.name),
+            ];
+            this.view(locals, block.children, () => this.expression(block.trackBy));
+            if (block.empty)
+                this.visit(block.empty);
+        }
+        visitForLoopBlockEmpty(block) {
+            this.view([], block.children);
+        }
+        visitSwitchBlock(block) {
+            this.expression(block.expression);
+            const groups = block.groups ?? block.cases.map((c) => ({ cases: [c], children: c.children }));
+            for (const group of groups) {
+                group.cases.forEach((c) => this.expression(c.expression));
+                this.view([], group.children);
+            }
+        }
+        visitDeferredBlock(block) {
+            for (const triggers of [block.triggers, block.prefetchTriggers, block.hydrateTriggers]) {
+                Object.values(triggers ?? {}).forEach((trigger) => this.expression(trigger?.value));
+            }
+            this.view([], block.children);
+            [block.placeholder, block.loading, block.error].forEach((sub) => sub && this.visit(sub));
+        }
+        visitDeferredBlockPlaceholder(block) {
+            this.view([], block.children);
+        }
+        visitDeferredBlockLoading(block) {
+            this.view([], block.children);
+        }
+        visitDeferredBlockError(block) {
+            this.view([], block.children);
+        }
+        visitLetDeclaration(declaration) {
+            this.expression(declaration.value);
+            scopes[scopes.length - 1]?.add(declaration.name);
+        }
+        visitIcu(icu) {
+            [...Object.values(icu.vars ?? {}), ...Object.values(icu.placeholders ?? {})].forEach((text) => this.expression(text.value));
+        }
+    }
+    new Templates().view([], nodes);
+    return [...usages.values()].sort((left, right) => left.start - right.start);
+}
+function lineColumn(text, offset) {
+    const before = text.slice(0, offset);
+    const lineStart = before.lastIndexOf("\n") + 1;
+    return { line: before.split("\n").length, column: offset - lineStart + 1 };
+}
+function decodeTemplate(bytes) {
+    try {
+        const utf16 = (bytes[0] === 0xff && bytes[1] === 0xfe) || (bytes[0] === 0xfe && bytes[1] === 0xff);
+        return utf16 ? undefined : new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Collects usages of a component member inside its declaring component's template. */
+export async function collectTemplateUsages(node, context, rc) {
+    rc.checkpoint();
+    const owner = memberOwner(node);
+    if (!owner || !hasAngularCore(context))
+        return NOT_APPLICABLE;
+    const isComponent = componentDecorator(owner.cls) !== undefined;
+    const derived = hasDerivedComponent(context, owner.cls);
+    if (!isComponent && !derived)
+        return NOT_APPLICABLE;
+    const fail = (status, reason) => ({
+        coverage: { status, reason, templates: 0 },
+        usages: [],
+    });
+    if (derived)
+        return fail("unsupported", "inherited_member");
+    const loaded = await loadCompiler(context.tsConfigFilePath);
+    if ("reason" in loaded)
+        return fail("unfinished", loaded.reason);
+    const located = locateTemplate(owner.cls);
+    if ("reason" in located)
+        return fail("unfinished", located.reason);
+    let text;
+    let offset = 0;
+    let bytes;
+    if (located.container === "inline") {
+        ({ text, offset } = located);
+        bytes = Buffer.from(text, "utf8");
+    }
+    else {
+        const unsafe = checkTemplatePath(context.projectRoot, located.absolutePath);
+        if (unsafe)
+            return fail("unfinished", unsafe);
+        if ((await stat(located.absolutePath)).size > MAX_TEMPLATE_BYTES) {
+            return fail("unfinished", "size_exceeded");
+        }
+        bytes = await readFile(located.absolutePath);
+        const decoded = decodeTemplate(bytes);
+        if (decoded === undefined)
+            return fail("unfinished", "template_parse_error");
+        text = decoded;
+    }
+    // Shared cap: the external path also checks the size before reading, inline checks here.
+    if (bytes.length > MAX_TEMPLATE_BYTES)
+        return fail("unfinished", "size_exceeded");
+    rc.checkpoint();
+    const parsed = loaded.compiler.parseTemplate(text, located.absolutePath, {
+        preserveWhitespaces: true,
+    });
+    if (parsed.errors?.length)
+        return fail("unfinished", "template_parse_error");
+    let raw;
+    try {
+        raw = extractUsages(loaded.compiler, parsed.nodes, owner.name, rc);
+    }
+    catch (error) {
+        if (error instanceof WorkExhausted)
+            return fail("unfinished", "work_exhausted");
+        throw error;
+    }
+    const fileText = located.container === "inline" ? owner.cls.getSourceFile().getFullText() : text;
+    const fileHash = createHash("sha256").update(bytes).digest("hex");
+    const usages = raw.map((usage) => {
+        const start = usage.start + offset;
+        return {
+            absolutePath: located.absolutePath,
+            file: path.relative(context.projectRoot, located.absolutePath),
+            container: located.container,
+            start,
+            end: usage.end + offset,
+            ...lineColumn(fileText, start),
+            kind: usage.kind,
+            localsInScope: usage.localsInScope,
+            fileHash,
+        };
+    });
+    return { coverage: { status: "completed", templates: 1 }, usages };
+}