ast-mcp-server 0.17.0 → 0.18.0

package/CHANGELOG.md

@@ -6,7 +6,22 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
-## [0.17.0] — not yet published (2026-11-09)
+## [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
 
@@ -25,6 +40,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 - 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

package/README.md

@@ -96,7 +96,10 @@ 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.
+- `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.
@@ -378,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.17.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.17.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/services/angular-templates.js

@@ -175,10 +175,10 @@ export function memberOwner(node) {
         ? { cls: owner, name: nameNode.getText() }
         : undefined;
 }
-function hasDerivedComponent(context, cls) {
+function hasDerivedComponent(cls, cache) {
     const identity = (node) => `${node.getSourceFile().getFilePath()}:${node.getPos()}`;
     const target = identity(cls);
-    return componentClasses(context).some((candidate) => {
+    return cache.components().some((candidate) => {
         let base = candidate.getBaseClass();
         for (let depth = 0; base && depth < 32; depth += 1) {
             if (identity(base) === target)
@@ -406,6 +406,73 @@ function decodeTemplate(bytes) {
         return undefined;
     }
 }
+/**
+ * Template work that does not depend on the queried symbol, shared by the collections of one
+ * request: the component list, each located template, each read and each parse. It is bound to the
+ * {@link ProjectContext} it was created for, and a collection over another context refuses it. It
+ * never outlives the request, so nothing is invalidated.
+ *
+ * Only whole results are kept. An entry is stored after its step returned, so a step that threw is
+ * run again by the next collection, and a scan that stopped early leaves complete entries for the
+ * templates it reached and none for the rest. Scan budgets are not part of it: every collection
+ * charges its own budget for each template, cached or not.
+ */
+export class TemplateScanCache {
+    context;
+    #components;
+    #located = new Map();
+    /** External templates by path, so a file shared by two components is read once; inline by location. */
+    #reads = new Map();
+    #parsed = new WeakMap();
+    #lines = new Map();
+    constructor(context) {
+        this.context = context;
+    }
+    components() {
+        return (this.#components ??= componentClasses(this.context));
+    }
+    locate(cls) {
+        let located = this.#located.get(cls);
+        if (!located) {
+            located = locateTemplate(cls);
+            this.#located.set(cls, located);
+        }
+        return located;
+    }
+    async read(located) {
+        const key = located.container === "external" ? located.absolutePath : located;
+        let read = this.#reads.get(key);
+        if (!read) {
+            read = await readTemplate(this.context, located);
+            this.#reads.set(key, read);
+        }
+        return read;
+    }
+    /**
+     * The lines of the file that holds a usage, for context lines. An external template that the
+     * scan read is split from that text; any other file (a source file with an inline template) is
+     * read from disk once.
+     */
+    async lines(absolutePath) {
+        let lines = this.#lines.get(absolutePath);
+        if (!lines) {
+            const read = this.#reads.get(absolutePath);
+            const text = read && "text" in read ? read.text : await readFile(absolutePath, "utf8");
+            lines = text.split(/\r?\n/);
+            this.#lines.set(absolutePath, lines);
+        }
+        return lines;
+    }
+    /** The parse of a template returned by {@link read}, errors included. */
+    parse(compiler, read, absolutePath) {
+        let parsed = this.#parsed.get(read);
+        if (!parsed) {
+            parsed = compiler.parseTemplate(read.text, absolutePath, { preserveWhitespaces: true });
+            this.#parsed.set(read, parsed);
+        }
+        return parsed;
+    }
+}
 /** Reads a located template within the per-template size cap. */
 async function readTemplate(context, located) {
     let text;
@@ -467,16 +534,11 @@ function bindingTarget(cls, node, name) {
         return undefined;
     return { selector, inputs: names.inputs, outputs: names.outputs };
 }
-/** Parses a consumer template, or returns undefined when the compiler reports errors. */
-function parseConsumer(compiler, text, absolutePath) {
-    const parsed = compiler.parseTemplate(text, absolutePath, { preserveWhitespaces: true });
-    return parsed.errors?.length ? undefined : parsed.nodes;
-}
 function selectorInspector(compiler, target) {
-    return (text, absolutePath, tick) => {
+    return (text, parse, tick) => {
         if (!mayMatch(compiler, target.selector, text))
             return "skip";
-        const nodes = parseConsumer(compiler, text, absolutePath);
+        const nodes = parse();
         if (!nodes)
             return "template_parse_error";
         const scan = extractConsumerUsages(compiler, nodes, text, target, tick);
@@ -489,10 +551,10 @@ function selectorInspector(compiler, target) {
     };
 }
 function pipeInspector(compiler, name, rc) {
-    return (text, absolutePath, tick) => {
+    return (text, parse, tick) => {
         if (!text.includes(name))
             return "skip";
-        const nodes = parseConsumer(compiler, text, absolutePath);
+        const nodes = parse();
         if (!nodes)
             return "template_parse_error";
         try {
@@ -511,7 +573,7 @@ function pipeInspector(compiler, name, rc) {
  * Scans every component template in the Project with `inspect`. Matching comes first; scope only
  * filters matches. Unreadable templates and unproven scopes are reported.
  */
-async function scanConsumers(context, cls, inspect, rc, limits) {
+async function scanConsumers(context, cls, compiler, inspect, rc, limits, cache) {
     const remaining = { ...SCAN_LIMITS, ...limits };
     const usages = [];
     let failure;
@@ -528,25 +590,30 @@ async function scanConsumers(context, cls, inspect, rc, limits) {
             rc.checkpoint();
     };
     try {
-        for (const consumer of componentClasses(context)) {
+        for (const consumer of cache.components()) {
             rc.checkpoint();
             if (--remaining.templates < 0)
                 throw new WorkExhausted();
-            const located = locateTemplate(consumer);
+            const located = cache.locate(consumer);
             if ("reason" in located) {
                 failure ??= located.reason;
                 continue;
             }
-            const read = await readTemplate(context, located);
+            const read = await cache.read(located);
             if ("reason" in read) {
                 failure ??= read.reason;
                 continue;
             }
+            // The budget is charged for every template, whether or not the cache already held it.
             remaining.bytes -= read.bytes.length;
             if (remaining.bytes < 0)
                 throw new WorkExhausted();
             examined += 1;
-            const scan = inspect(read.text, located.absolutePath, tick);
+            const parse = () => {
+                const parsed = cache.parse(compiler, read, located.absolutePath);
+                return parsed.errors?.length ? undefined : parsed.nodes;
+            };
+            const scan = inspect(read.text, parse, tick);
             if (scan === "skip")
                 continue;
             if (scan === "template_parse_error") {
@@ -583,7 +650,7 @@ function pipeName(cls) {
     return literalString(Node.isPropertyAssignment(property) ? property.getInitializer() : undefined);
 }
 /** `| name` usages of a pipe class in the templates of components that have the class in scope. */
-async function collectPipeUsages(cls, context, rc, limits) {
+async function collectPipeUsages(cls, context, rc, limits, cache) {
     const unfinished = (reason, templates = 0) => ({
         coverage: { status: "unfinished", reason, templates },
         usages: [],
@@ -594,15 +661,23 @@ async function collectPipeUsages(cls, context, rc, limits) {
     const loaded = await loadCompiler(context.tsConfigFilePath);
     if ("reason" in loaded)
         return unfinished(loaded.reason);
-    const scan = await scanConsumers(context, cls, pipeInspector(loaded.compiler, name, rc), rc, limits);
+    const scan = await scanConsumers(context, cls, loaded.compiler, pipeInspector(loaded.compiler, name, rc), rc, limits, cache);
     const coverage = scan.failure
         ? { status: "unfinished", reason: scan.failure, templates: scan.examined }
         : { status: "completed", templates: scan.examined };
     return { coverage, usages: scan.usages };
 }
-/** Collects usages of a component member inside its declaring component's template. */
-export async function collectTemplateUsages(node, context, rc, limits = {}) {
+/**
+ * Collects usages of a component member inside its declaring component's template.
+ *
+ * Pass one `cache` to every collection of a request to share symbol-independent work between
+ * them; the result is the same with or without it. By default each call works alone.
+ */
+export async function collectTemplateUsages(node, context, rc, limits = {}, cache = new TemplateScanCache(context)) {
     rc.checkpoint();
+    if (cache.context !== context) {
+        throw new Error("The template scan cache was created for another ProjectContext.");
+    }
     if (!hasAngularCore(context))
         return NOT_APPLICABLE;
     const fail = (status, reason) => ({
@@ -610,7 +685,7 @@ export async function collectTemplateUsages(node, context, rc, limits = {}) {
         usages: [],
     });
     if (Node.isClassDeclaration(node)) {
-        return isPipeClass(node) ? collectPipeUsages(node, context, rc, limits) : NOT_APPLICABLE;
+        return isPipeClass(node) ? collectPipeUsages(node, context, rc, limits, cache) : NOT_APPLICABLE;
     }
     const owner = memberOwner(node);
     if (!owner)
@@ -620,14 +695,17 @@ export async function collectTemplateUsages(node, context, rc, limits = {}) {
         if (owner.name !== "transform" || componentDecorator(owner.cls)) {
             return fail("unfinished", "cross_component");
         }
-        return { ...(await collectPipeUsages(owner.cls, context, rc, limits)), renameBlocked: true };
+        return {
+            ...(await collectPipeUsages(owner.cls, context, rc, limits, cache)),
+            renameBlocked: true,
+        };
     }
     const isComponent = componentDecorator(owner.cls) !== undefined;
     const selectorPublic = isSelectorPublic(node) || isMetadataPublic(owner.cls, owner.name);
     if (!isComponent && selectorPublic && isDirectiveClass(owner.cls)) {
         return fail("unfinished", "cross_component");
     }
-    const derived = hasDerivedComponent(context, owner.cls);
+    const derived = hasDerivedComponent(owner.cls, cache);
     if (!isComponent && !derived)
         return NOT_APPLICABLE;
     if (derived)
@@ -635,16 +713,14 @@ export async function collectTemplateUsages(node, context, rc, limits = {}) {
     const loaded = await loadCompiler(context.tsConfigFilePath);
     if ("reason" in loaded)
         return fail("unfinished", loaded.reason);
-    const located = locateTemplate(owner.cls);
+    const located = cache.locate(owner.cls);
     if ("reason" in located)
         return fail("unfinished", located.reason);
-    const read = await readTemplate(context, located);
+    const read = await cache.read(located);
     if ("reason" in read)
         return fail("unfinished", read.reason);
     rc.checkpoint();
-    const parsed = loaded.compiler.parseTemplate(read.text, located.absolutePath, {
-        preserveWhitespaces: true,
-    });
+    const parsed = cache.parse(loaded.compiler, read, located.absolutePath);
     if (parsed.errors?.length)
         return fail("unfinished", "template_parse_error");
     let raw;
@@ -669,7 +745,7 @@ export async function collectTemplateUsages(node, context, rc, limits = {}) {
         return unfinished("cross_component");
     if (!loaded.selectors)
         return unfinished("compiler_unsupported");
-    const scan = await scanConsumers(context, owner.cls, selectorInspector(loaded.compiler, target), rc, limits);
+    const scan = await scanConsumers(context, owner.cls, loaded.compiler, selectorInspector(loaded.compiler, target), rc, limits, cache);
     const coverage = scan.failure
         ? { status: "unfinished", reason: scan.failure, templates: scan.examined }
         : { status: "completed", templates: scan.examined };

package/dist/services/context-builder.js

@@ -1,11 +1,12 @@
 import path from "node:path";
+import { TemplateScanCache } from "./angular-templates.js";
 import { buildFileOutline, nodeSourceWithLocation } from "./outline.js";
 import { paginate } from "./pagination.js";
 import { resolveImpactRoot } from "./impact.js";
 import { planCallSpines } from "./call-spines.js";
 import { isCooperativeInterruption, NO_REQUEST_CONTEXT, } from "./request-context.js";
 import { findDeclarationByName, getSourceFileOrThrow, reportSymbolIndexFailure, } from "./project.js";
-import { collectSymbolReferences } from "./references.js";
+import { collectSymbolReferencesWithTemplateVerdict, } from "./references.js";
 import { collectCompilerCallRelationships } from "./relationships.js";
 import { presentExploreClusters } from "./explore-presentation.js";
 import { searchProjectSymbolsPage, searchProjectSymbolsPageWithIndex, sourceFileSymbols, symbolMatchRank, } from "./symbols.js";
@@ -151,6 +152,8 @@ export async function buildExploreContext(context, request, requestContext = NO_
     const unresolved = [];
     const evidence = [];
     let callSpines;
+    // Lives for this request only: the selected symbols share template reads, never a scan budget.
+    const templateCache = new TemplateScanCache(effectiveContext);
     if (request.callSpines) {
         if (!request.filePath || !request.symbolPath || routed.route !== "symbol") {
             throw new Error("Call spines require an exact file_path and symbol_path.");
@@ -197,7 +200,13 @@ export async function buildExploreContext(context, request, requestContext = NO_
         }
         if (expansion.references) {
             try {
-                references = collectSymbolReferences(node, effectiveContext.projectRoot, record.selector, true, request.referenceDetail, 0, request.referenceLimit, requestContext);
+                references = await collectSymbolReferencesWithTemplateVerdict(node, effectiveContext, {
+                    symbolPath: record.selector,
+                    includeDeclaration: true,
+                    detail: request.referenceDetail,
+                    offset: 0,
+                    limit: request.referenceLimit,
+                }, requestContext, templateCache);
             }
             catch (error) {
                 if (isCooperativeInterruption(error))
@@ -231,6 +240,16 @@ export async function buildExploreContext(context, request, requestContext = NO_
                 reason: "reference_limit",
             });
         }
+        // Absent coverage means not applicable; anything short of completed leaves usages unknown.
+        const coverage = item.references?.template_coverage?.status;
+        if (coverage !== undefined && coverage !== "completed" && coverage !== "not_applicable") {
+            omissions.push({
+                subject: item.selector,
+                category: "incomplete",
+                component: "references",
+                reason: "template_coverage_incomplete",
+            });
+        }
     }
     if (callSpines?.authority_state === "untrusted") {
         omissions.push({

package/dist/services/explore-presentation.js

@@ -9,6 +9,7 @@ export const EXPLORE_OMISSION_REASONS = [
     "depth_limit",
     "node_limit",
     "edge_limit",
+    "template_coverage_incomplete",
 ];
 function jsonBytes(value) {
     return Buffer.byteLength(JSON.stringify(value), "utf8");

package/dist/services/references.js

@@ -1,9 +1,8 @@
-import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { Node } from "ts-morph";
-import { collectTemplateUsages, } from "./angular-templates.js";
+import { collectTemplateUsages, TemplateScanCache, } from "./angular-templates.js";
 import { paginate } from "./pagination.js";
-import { NO_REQUEST_CONTEXT } from "./request-context.js";
+import { isCooperativeInterruption, NO_REQUEST_CONTEXT, } from "./request-context.js";
 /**
  * Semantic references of `node` excluding the declaration itself.
  *
@@ -79,15 +78,11 @@ export function collectSymbolReferences(node, projectRoot, symbolPath, includeDe
         next_offset: page.next_offset,
     };
 }
-async function templateLocation(usage, detail, lineCache) {
+async function templateLocation(usage, detail, templateCache) {
     let context;
     if (detail === "context") {
-        let lines = lineCache.get(usage.absolutePath);
-        if (!lines) {
-            lines = readFile(usage.absolutePath, "utf8").then((text) => text.split(/\r?\n/));
-            lineCache.set(usage.absolutePath, lines);
-        }
-        context = ((await lines)[usage.line - 1] ?? "").trim().slice(0, 500);
+        const lines = await templateCache.lines(usage.absolutePath);
+        context = (lines[usage.line - 1] ?? "").trim().slice(0, 500);
     }
     return {
         file: usage.file,
@@ -99,29 +94,28 @@ async function templateLocation(usage, detail, lineCache) {
         ...(context === undefined ? {} : { context }),
     };
 }
-/**
- * Collects TypeScript references and, for Angular component members, template usages.
- * Without Angular evidence the result is identical to {@link collectSymbolReferences}.
- */
-export async function collectSymbolReferencesWithTemplates(node, context, query, requestContext = NO_REQUEST_CONTEXT) {
-    const { projectRoot } = context;
-    const { coverage, usages } = await collectTemplateUsages(node, context, requestContext);
-    if (coverage.status === "not_applicable") {
-        return collectSymbolReferences(node, projectRoot, query.symbolPath, query.includeDeclaration, query.detail, query.offset, query.limit, requestContext);
-    }
-    const ts = collectTsLocations(node, projectRoot, query.symbolPath, query.includeDeclaration, query.detail, requestContext);
-    const lineCache = new Map();
-    const templateItems = [];
+/** Template usages of `node` as reference items, with the coverage verdict that qualifies them. */
+async function collectTemplateHalf(node, context, detail, requestContext, templateCache = new TemplateScanCache(context)) {
+    const { coverage, usages } = await collectTemplateUsages(node, context, requestContext, undefined, templateCache);
+    const items = [];
     for (const usage of usages) {
         requestContext.checkpoint();
-        templateItems.push(await templateLocation(usage, query.detail, lineCache));
+        items.push(await templateLocation(usage, detail, templateCache));
+    }
+    return { coverage, items };
+}
+/** Merges the TypeScript references of `node` with an already collected template half. */
+function mergeWithTemplateHalf(node, projectRoot, query, template, requestContext) {
+    if (template.coverage.status === "not_applicable") {
+        return collectSymbolReferences(node, projectRoot, query.symbolPath, query.includeDeclaration, query.detail, query.offset, query.limit, requestContext);
     }
+    const ts = collectTsLocations(node, projectRoot, query.symbolPath, query.includeDeclaration, query.detail, requestContext);
     const merged = [
         ...ts.locations.map((item) => ({ ...item, origin: "compiler" })),
-        ...templateItems,
+        ...template.items,
     ].sort(compareLocations);
     const affectedFiles = [
-        ...new Set([ts.declaration, ...ts.references, ...templateItems].map((item) => item.file)),
+        ...new Set([ts.declaration, ...ts.references, ...template.items].map((item) => item.file)),
     ].sort();
     const page = paginate(merged, query.offset, query.limit);
     requestContext.checkpoint();
@@ -137,7 +131,38 @@ export async function collectSymbolReferencesWithTemplates(node, context, query,
         total: page.total,
         has_more: page.has_more,
         next_offset: page.next_offset,
-        template_coverage: coverage,
-        template_reference_count: templateItems.length,
+        template_coverage: template.coverage,
+        template_reference_count: template.items.length,
     };
 }
+/**
+ * Collects TypeScript references and, for Angular component members, template usages.
+ * Without Angular evidence the result is identical to {@link collectSymbolReferences}.
+ */
+export async function collectSymbolReferencesWithTemplates(node, context, query, requestContext = NO_REQUEST_CONTEXT) {
+    const template = await collectTemplateHalf(node, context, query.detail, requestContext);
+    return mergeWithTemplateHalf(node, context.projectRoot, query, template, requestContext);
+}
+/**
+ * Same result as {@link collectSymbolReferencesWithTemplates}, but a failing template half is
+ * reported as an `unfinished` / `template_unresolved` verdict next to the TypeScript references
+ * instead of failing the call. TypeScript failures and cooperative interruptions still throw.
+ *
+ * A caller that collects several symbols in one request passes the same `templateCache` to each
+ * call; it shares template reads between them and does not change any result.
+ */
+export async function collectSymbolReferencesWithTemplateVerdict(node, context, query, requestContext = NO_REQUEST_CONTEXT, templateCache) {
+    let template;
+    try {
+        template = await collectTemplateHalf(node, context, query.detail, requestContext, templateCache);
+    }
+    catch (error) {
+        if (isCooperativeInterruption(error))
+            throw error;
+        template = {
+            coverage: { status: "unfinished", reason: "template_unresolved", templates: 0 },
+            items: [],
+        };
+    }
+    return mergeWithTemplateHalf(node, context.projectRoot, query, template, requestContext);
+}

package/dist/tools/explore.js

@@ -8,6 +8,7 @@ import { createRequestContext } from "../services/request-context.js";
 import { FRESHNESS_CAUSES, SNAPSHOT_STATES, TRUNCATION_REASONS, } from "../services/read-contracts.js";
 import { createToolErrorContext, errorResult, structuredResult } from "./result.js";
 import { RelationshipEndpointSchema } from "./relationship-schema.js";
+import { ReferenceOriginSchema, templateEvidenceFields } from "./template-evidence-schema.js";
 const TOOL_NAME = "ast_explore";
 const ExploreDetailSchema = z.enum(["selectors", "summary", "context", "full"]).default("summary");
 const ReferenceDetailSchema = z.enum(["locations", "context"]).default("locations");
@@ -100,6 +101,7 @@ const ExploreReferenceSchema = z.object({
     kind: z.string(),
     is_declaration: z.boolean(),
     context: z.string().optional(),
+    origin: ReferenceOriginSchema.optional(),
 });
 const ExploreEvidenceSchema = z.object({
     selector: z.string(),
@@ -111,6 +113,7 @@ const ExploreEvidenceSchema = z.object({
         declaration_count: z.number().int().min(0),
         reference_count: z.number().int().min(0),
         affected_files: z.array(z.string()),
+        ...templateEvidenceFields,
         references: z.array(ExploreReferenceSchema),
         offset: z.number().int().min(0),
         limit: z.number().int().positive(),

package/dist/tools/find_references.js

@@ -4,6 +4,7 @@ import { findDeclarationByName, getSourceFileOrThrow, withProject } from "../ser
 import { collectSymbolReferencesWithTemplates } from "../services/references.js";
 import { createRequestContext } from "../services/request-context.js";
 import { createToolErrorContext, errorResult, formattedResult, ToolOutputFormatInputSchema, } from "./result.js";
+import { ReferenceOriginSchema, templateEvidenceFields } from "./template-evidence-schema.js";
 const TOOL_NAME = "ast_find_references";
 const ReferenceDetailSchema = z.enum(["locations", "context"]).default("locations");
 const AstFindReferencesInputSchema = z.object({
@@ -26,37 +27,20 @@ const ContextReferenceSchema = z.object({
     context: z.string(),
 });
 const ContextReferenceSchemaWithOrigin = ContextReferenceSchema.extend({
-    origin: z.enum(["compiler", "template_external", "template_inline"]).optional(),
+    origin: ReferenceOriginSchema.optional(),
 });
 const LocationReferenceSchema = ContextReferenceSchemaWithOrigin.omit({ context: true });
-const TemplateCoverageSchema = z.object({
-    status: z.enum(["completed", "unfinished", "unsupported"]),
-    reason: z
-        .enum([
-        "compiler_missing",
-        "compiler_unsupported",
-        "template_unresolved",
-        "template_unsafe",
-        "template_parse_error",
-        "size_exceeded",
-        "work_exhausted",
-        "inherited_member",
-        "cross_component",
-    ])
-        .optional(),
-    templates: z.number().int().min(0).optional(),
-});
 const ReferenceOutputBase = {
     symbol: z.string(),
     include_declaration: z.boolean(),
     declaration_count: z.number().int().min(0),
     reference_count: z.number().int().min(0),
     affected_files: z.array(z.string()),
-    template_coverage: TemplateCoverageSchema.optional(),
-    template_reference_count: z.number().int().min(0).optional(),
+    ...templateEvidenceFields,
     ...PaginationOutputSchema,
 };
-const ReferenceOutputSchemas = {
+/** Exported so a golden test can pin the output JSON schema bytes; not a tool contract. */
+export const ReferenceOutputSchemas = {
     locations: z.object({
         ...ReferenceOutputBase,
         references: z.array(LocationReferenceSchema),

package/dist/tools/template-evidence-schema.js

@@ -0,0 +1,25 @@
+import { z } from "zod";
+/** Output schemas for Angular template evidence, shared by every tool that reports references. */
+export const ReferenceOriginSchema = z.enum(["compiler", "template_external", "template_inline"]);
+export const TemplateCoverageSchema = z.object({
+    status: z.enum(["completed", "unfinished", "unsupported"]),
+    reason: z
+        .enum([
+        "compiler_missing",
+        "compiler_unsupported",
+        "template_unresolved",
+        "template_unsafe",
+        "template_parse_error",
+        "size_exceeded",
+        "work_exhausted",
+        "inherited_member",
+        "cross_component",
+    ])
+        .optional(),
+    templates: z.number().int().min(0).optional(),
+});
+/** Present only when template coverage applies to the symbol. */
+export const templateEvidenceFields = {
+    template_coverage: TemplateCoverageSchema.optional(),
+    template_reference_count: z.number().int().min(0).optional(),
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ast-mcp-server",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Structural code MCP server and batch CLI for compact TypeScript/JavaScript reads and hash-bound AST edits.",
   "keywords": [
     "mcp",
@@ -91,6 +91,7 @@
     "benchmark:corpus": "yarn build && node scripts/benchmark-corpus.mjs",
     "benchmark:batch": "yarn build && node scripts/benchmark-batch.mjs",
     "benchmark:formats": "yarn build && node scripts/benchmark-formats.mjs",
+    "benchmark:explore-templates": "yarn build && node scripts/benchmark-explore-templates.mjs",
     "benchmark:shapes": "yarn build && node scripts/benchmark-result-shapes.mjs",
     "benchmark:agent-workflows": "yarn build && node scripts/benchmark-agent-workflows.mjs",
     "benchmark:index-storage": "yarn build && node scripts/benchmark-index-storage.mjs",
@@ -140,5 +141,5 @@
     "vitest": "^5.0.5",
     "yaml": "^2.9.0"
   },
-  "gitHead": "e49987bd1fd36432aa76ecb27ca8359eedb613ad"
+  "gitHead": "9154dc7bd17f326e04c7b7e4dbfb9fcde9a66cdf"
 }

package/skills/structural-code-editing/SKILL.md

@@ -4,7 +4,7 @@ description: "Trigger: navegar, analizar o editar TypeScript/JavaScript con el c
 license: "ISC"
 metadata:
   author: "yail"
-  version: "4.8.0"
+  version: "4.9.0"
   hermes:
     tags: ["typescript", "javascript", "ast", "refactoring", "mcp"]
     homepage: "https://github.com/yailPeralta/ast-mcp-server"
@@ -49,6 +49,11 @@ In an Angular project (`@angular/core` resolvable from the tsconfig directory),
 
 Read `template_coverage` before inferring absence. Only `completed` proves every template it covers was examined. `unfinished` (for example `compiler_missing`, `compiler_unsupported`, `template_unresolved`, `template_parse_error`, `size_exceeded`, `cross_component`, `work_exhausted`) and `unsupported` (for example an inherited member) never prove that no template usage exists. `not_applicable` means the feature is off and the response is unchanged.
 
+`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`. Read `template_coverage` before trusting explore references, and treat every status other than `completed` as unknown.
+
+- 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.
+
 Consumer templates: for a member bound through the selector (`@Input`, `@Output`, `input()`, `output()`, `model()`, a literal alias, or a literal entry of the `inputs` / `outputs` metadata), the binding keys `[x]`, `x="lit"`, `[(x)]`, `(y)` and `(xChange)` are listed with kinds `TemplateInputBinding` for `[x]`, `TemplateAttribute` for `x="lit"`, `TemplateTwoWayBinding` for `[(x)]` and `TemplateOutputBinding` for `(y)` and `(xChange)` in the templates of components whose resolved scope contains the declaring component (literal standalone `imports`, or NgModule `declarations` plus the `exports` of imported modules). For a `@Pipe` class with a literal `name`, and for its `transform` member, `| name` usages in in-scope templates are listed with kind `TemplatePipeName`. A same selector or pipe name outside that scope is ignored.
 
 For these members, `completed` means template evidence inside the Project only: every component template of the Project (the tsconfig passed as `project_root`) was read and every match resolved. `hostDirectives`, `@Directive` inputs and outputs, and non-literal scopes, aliases, metadata or pipe names stay `unfinished` with `cross_component`. Runtime bindings (`setInput`, router input binding, `createComponent` and other dynamic component APIs) and consumers outside the Project (other tsconfigs, libraries, other applications) are never examined, so `completed` does not cover them.
@@ -59,7 +64,7 @@ Pipes: renaming a `@Pipe` class applies with TypeScript edits only; the `name` l
 
 Limits to state when reporting:
 
-- `ast_explore` is TypeScript-only: its references omit template usages. This is tracked in issue #380. Use `ast_find_references` for template evidence; rename still blocks independently.
+- `ast_get_impact`, `ast_find_test_candidates` and the `ast_explore` call spines stay compiler-only: they never contain a template usage. Rename blocks on its own evidence, independently of these tools.
 - The `diagnostics` field stays TypeScript-only. When a rename edits a template, the plan also carries `template_diagnostics`, a best-effort template type-check delta (`status`, `reason`, `added`, `removed`, `added_errors`) from the project's own `@angular/compiler-cli`; it is absent for non-Angular projects and for renames that edit no template. `completed` is the only status with data; `unavailable` (`compiler_cli_missing`, `compiler_unsupported`, `typescript_incompatible`) and `unfinished` (`work_exhausted`, `deadline`, `check_failed`) mean unknown, so run the project's build or tests before applying. `block_on_template_errors` (default `false`) blocks only a `completed` delta with `added_errors`, and `allow_new_errors` waives it. `template_diagnostics[].file` is relative to the directory of the tsconfig, while `diagnostics[].file` is relative to `project_root`. `@angular/compiler-cli` is not a declared peer and must resolve from the project, otherwise the status is `unavailable/compiler_cli_missing`. Template-editing renames persist as plan schema v3, which is rejected on import after a downgrade.
 - Detection uses the user's own `@angular/compiler`, never a bundled one. It is an optional peer (`>=18.0.0 <23.0.0`) that the project already installs with Angular. If it is missing or out of range, coverage is `unfinished` and rename is blocked. Yarn PnP projects without `node_modules` resolve nothing and report `unfinished`.
 

package/skills/structural-code-editing/references/operations.md

@@ -22,7 +22,9 @@ Preferir `file_path` relativo; un suffix ambiguo debe devolver candidatos. `ast_
 
 ### Angular templates
 
-`ast_find_references` adds template usages (`origin: "template_external" | "template_inline"`, `template_coverage`, `template_reference_count`) only when `@angular/core` resolves; otherwise the response is unchanged. Treat `template_coverage.status` other than `completed` as not proving absence. Selector-bound members (`@Input`, `@Output`, `input()`, `output()`, `model()`, literal aliases, literal `inputs` / `outputs` metadata) also list their bindings in consumer templates (kinds `TemplateInputBinding` for `[x]`, `TemplateAttribute` for `x="lit"`, `TemplateTwoWayBinding` for `[(x)]` and `TemplateOutputBinding` for `(y)` and `(xChange)`), and `@Pipe` classes and their `transform` list `| name` usages (kind `TemplatePipeName`), for components whose resolved standalone or NgModule scope contains the declaring class. For them, `completed` covers templates inside the Project only. `hostDirectives`, `@Directive` inputs and outputs, and non-literal scopes, aliases or names stay `unfinished` with `cross_component`; runtime bindings (`setInput`, router input binding, `createComponent`) and consumers outside the Project are never examined. `ast_explore` is TypeScript-only for references (tracked in issue #380).
+`ast_find_references` adds template usages (`origin: "template_external" | "template_inline"`, `template_coverage`, `template_reference_count`) only when `@angular/core` resolves; otherwise the response is unchanged. Treat `template_coverage.status` other than `completed` as not proving absence. Selector-bound members (`@Input`, `@Output`, `input()`, `output()`, `model()`, literal aliases, literal `inputs` / `outputs` metadata) also list their bindings in consumer templates (kinds `TemplateInputBinding` for `[x]`, `TemplateAttribute` for `x="lit"`, `TemplateTwoWayBinding` for `[(x)]` and `TemplateOutputBinding` for `(y)` and `(xChange)`), and `@Pipe` classes and their `transform` list `| name` usages (kind `TemplatePipeName`), for components whose resolved standalone or NgModule scope contains the declaring class. For them, `completed` covers templates inside the Project only. `hostDirectives`, `@Directive` inputs and outputs, and non-literal scopes, aliases or names stay `unfinished` with `cross_component`; runtime bindings (`setInput`, router input binding, `createComponent`) and consumers outside the Project are never examined.
+
+`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`. Read `template_coverage` before trusting explore references. 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 template type-check delta (`status`, `reason`, `added`, `removed`, `added_errors`) from the project's own `@angular/compiler-cli`; it is absent for non-Angular projects and for renames that edit no template. `completed` is the only status with data; `unavailable` (`compiler_cli_missing`, `compiler_unsupported`, `typescript_incompatible`) and `unfinished` (`work_exhausted`, `deadline`, `check_failed`) mean unknown, so run the project's build or tests before applying. `block_on_template_errors` (default `false`) blocks only a `completed` delta with `added_errors`, and `allow_new_errors` waives it. `template_diagnostics[].file` is relative to the directory of the tsconfig, while `diagnostics[].file` is relative to `project_root`. `@angular/compiler-cli` is not a declared peer and must resolve from the project, otherwise the status is `unavailable/compiler_cli_missing`. Template-editing renames persist as plan schema v3, which is rejected on import after a downgrade.
 

package/skills/structural-code-editing/releases.json

@@ -2,15 +2,15 @@
   "schema_version": 2,
   "algorithm": "sha256",
   "current": {
-    "version": "4.8.0",
+    "version": "4.9.0",
     "files": [
       {
         "path": "SKILL.md",
-        "sha256": "15e5d25553a3ebce86365ff7b43ed61e7df11dd6ad658e83ec6e43cd84118762"
+        "sha256": "451670dcaa0bbfc11273fe9bd507de61865dbaac80e1d586306bcd30962d90d4"
       },
       {
         "path": "references/operations.md",
-        "sha256": "dd633a24e9aabeb1d9e9d1f93e261906e7b30eb721fadfb3d317d6acc60db2ca"
+        "sha256": "363ccb2332a42c68f21073a568a96d3000eff98954eaebff3d92e65d87c4f14c"
       }
     ]
   },
@@ -205,6 +205,20 @@
         }
       ],
       "npm_versions": ["0.16.0"]
+    },
+    {
+      "version": "4.8.0",
+      "files": [
+        {
+          "path": "SKILL.md",
+          "sha256": "15e5d25553a3ebce86365ff7b43ed61e7df11dd6ad658e83ec6e43cd84118762"
+        },
+        {
+          "path": "references/operations.md",
+          "sha256": "dd633a24e9aabeb1d9e9d1f93e261906e7b30eb721fadfb3d317d6acc60db2ca"
+        }
+      ],
+      "npm_versions": ["0.17.0"]
     }
   ]
 }