ast-mcp-server 0.16.0 → 0.18.0

package/dist/services/operations.js

@@ -7,6 +7,8 @@ import { LanguageVariant, Node, ScriptTarget, SyntaxKind, ts } from "ts-morph";
 import { isPipeClass } from "./angular-decorators.js";
 import { planTemplateEdits } from "./angular-template-rename.js";
 import { collectTemplateUsages } from "./angular-templates.js";
+import { checkTemplateTypes } from "./angular-template-typecheck.js";
+import { evaluateBlock } from "./operation-block-policy.js";
 import { findNonDeclarationReferences } from "./references.js";
 import { compareObservedDiagnostics, observeDiagnostic, } from "./diagnostics.js";
 import { probePublicationCapability, publishAuthenticated, removeOwnedPublicationEntry, rollbackOwnedCommit, snapshotHeldFile, } from "./authenticated-publication.js";
@@ -47,6 +49,7 @@ function planHashFor(operation, version = 2) {
         diagnostics: operation.diagnostics,
         allow_new_errors: operation.allow_new_errors,
         blocked: operation.blocked,
+        ...(version === 3 ? templateHashFields(operation) : {}),
         files: operation.files.map((file) => ({
             file: file.file,
             original_hash: file.originalHash,
@@ -55,6 +58,27 @@ function planHashFor(operation, version = 2) {
         })),
     }));
 }
+/** The version 3 additions, in a fixed key order so equal deltas always hash equal. */
+function templateHashFields(operation) {
+    const delta = operation.template_diagnostics;
+    if (delta === undefined || operation.block_on_template_errors === undefined) {
+        throw new Error("A version 3 plan requires template_diagnostics and block_on_template_errors.");
+    }
+    return {
+        template_diagnostics: {
+            status: delta.status,
+            ...(delta.status === "completed" ? {} : { reason: delta.reason }),
+            added: delta.added,
+            removed: delta.removed,
+            addedErrors: delta.addedErrors,
+        },
+        block_on_template_errors: operation.block_on_template_errors,
+    };
+}
+/** Plans without a template check keep hashing as version 2; only a check upgrades them. */
+function planVersionOf(operation) {
+    return operation.template_diagnostics === undefined ? 2 : 3;
+}
 function pruneOperations() {
     const now = operationNow();
     for (const [id, operation] of operations) {
@@ -216,8 +240,22 @@ async function planAuxiliaryFiles(edits, projectRoot, snapshotFiles, requestCont
     }
     return planned;
 }
+/** Maps the planned files to the check input; paths are relative to the tsconfig directory. */
+function templateCheckInput(tsConfigFilePath, files, auxiliaryFiles) {
+    const base = path.dirname(tsConfigFilePath);
+    return {
+        tsConfigFilePath,
+        templates: auxiliaryFiles.map((file) => file.absolutePath),
+        overlay: files.map((file) => ({ absolutePath: file.absolutePath, text: file.updatedText })),
+        changes: files.map((file) => ({
+            file: path.relative(base, file.absolutePath),
+            beforeText: isCreatedFile(file) ? null : file.originalText,
+            afterText: file.updatedText,
+        })),
+    };
+}
 /** Internal seam shared by the prepare functions; exported so tests can drive `mutate` directly. */
-export async function createPlan(projectRootInput, kind, allowNewErrors, mutate, requestContext) {
+export async function createPlan(projectRootInput, kind, allowNewErrors, mutate, requestContext, planOptions = {}) {
     requestContext.checkpoint();
     let retainedOperationId;
     return withProjectOperation(projectRootInput, async (operationContext) => {
@@ -316,13 +354,25 @@ export async function createPlan(projectRootInput, kind, allowNewErrors, mutate,
             postWorkspaceFiles.set(file.absolutePath, file.updatedHash);
         }
         const postWorkspaceHash = hashWorkspaceFiles(postWorkspaceFiles);
+        // Only a rename that edits templates is checked; the check runs inside the project lock and
+        // before the digest check below, which proves the child's disk reads saw an unchanged tree.
+        const templateDiagnostics = kind === "rename_symbol" && auxiliaryFiles.length > 0
+            ? await checkTemplateTypes(templateCheckInput(context.tsConfigFilePath, files, auxiliaryFiles), operationContext)
+            : undefined;
+        operationContext.checkpoint();
         const workspaceAfter = createWorkspaceSnapshot(createFreshProject(context.tsConfigFilePath));
         operationContext.checkpoint();
         if (workspaceAfter.digest !== workspaceBefore.digest) {
             throw new Error("Workspace changed while the operation was being prepared. Retry preparation.");
         }
         const fullPreview = files.map((file) => file.diff).join("\n");
-        const blocked = !allowNewErrors && diagnosticDelta.addedErrors.length > 0;
+        const blockOnTemplateErrors = planOptions.blockOnTemplateErrors ?? false;
+        const verdict = evaluateBlock({
+            allowNewErrors,
+            typescriptErrors: diagnosticDelta.addedErrors.length,
+            template: templateDiagnostics,
+            blockOnTemplateErrors,
+        });
         const now = operationNow();
         const operationId = randomUUID();
         const recordWithoutHash = {
@@ -344,17 +394,21 @@ export async function createPlan(projectRootInput, kind, allowNewErrors, mutate,
             workspace_file_count: workspaceBefore.fileCount,
             diagnostics: diagnosticDelta,
             allow_new_errors: allowNewErrors,
-            blocked,
-            block_reason: blocked
-                ? `${diagnosticDelta.addedErrors.length} new TypeScript error(s) would be introduced. Prepare again with allow_new_errors=true only after explicit review.`
-                : null,
+            blocked: verdict.blocked,
+            block_reason: verdict.reason,
             preview: fullPreview.length <= MAX_INLINE_PREVIEW_CHARS ? fullPreview : null,
             preview_truncated: fullPreview.length > MAX_INLINE_PREVIEW_CHARS,
+            ...(templateDiagnostics === undefined
+                ? {}
+                : {
+                    template_diagnostics: templateDiagnostics,
+                    block_on_template_errors: blockOnTemplateErrors,
+                }),
             files,
         };
         const record = {
             ...recordWithoutHash,
-            plan_hash: planHashFor(recordWithoutHash),
+            plan_hash: planHashFor(recordWithoutHash, planVersionOf(recordWithoutHash)),
         };
         operationContext.checkpoint();
         operations.set(operationId, record);
@@ -388,6 +442,12 @@ function publicOperation(record) {
         block_reason: record.block_reason,
         preview: record.preview,
         preview_truncated: record.preview_truncated,
+        ...(record.template_diagnostics === undefined
+            ? {}
+            : {
+                template_diagnostics: record.template_diagnostics,
+                block_on_template_errors: record.block_on_template_errors,
+            }),
     };
 }
 const TEMPLATE_ANY_CAST = "$any";
@@ -448,7 +508,7 @@ export async function prepareRename(args, requestContext = NO_REQUEST_CONTEXT) {
                 expectedHash: usage.fileHash,
             })),
         };
-    }, requestContext);
+    }, requestContext, { blockOnTemplateErrors: args.blockOnTemplateErrors });
 }
 export async function prepareReplaceBody(args, requestContext = NO_REQUEST_CONTEXT) {
     return createPlan(args.projectRoot, "replace_symbol_body", args.allowNewErrors ?? false, async ({ project }) => {
@@ -982,7 +1042,7 @@ export function exportOperationRecord(operationId) {
         })),
     };
 }
-export function importOperationRecord(persisted, expectedPlanHash, planVersion = 2) {
+export function importOperationRecord(persisted, expectedPlanHash, planVersion = planVersionOf(persisted)) {
     if (persisted.plan_hash !== expectedPlanHash) {
         throw new Error(`Plan hash mismatch for operation "${persisted.operation_id}". No files were written.`);
     }
@@ -1047,18 +1107,31 @@ export function importOperationRecord(persisted, expectedPlanHash, planVersion =
     if (JSON.stringify(addedErrors) !== JSON.stringify(persisted.diagnostics.addedErrors)) {
         throw new Error("Persisted diagnostic error delta is inconsistent.");
     }
-    const blocked = !persisted.allow_new_errors && addedErrors.length > 0;
-    if (persisted.blocked !== blocked) {
+    const templateDelta = persisted.template_diagnostics;
+    if (templateDelta !== undefined) {
+        const templateErrors = templateDelta.added.filter((diagnostic) => diagnostic.category === "Error");
+        if (JSON.stringify(templateErrors) !== JSON.stringify(templateDelta.addedErrors)) {
+            throw new Error("Persisted template diagnostic error delta is inconsistent.");
+        }
+    }
+    if ((planVersion === 3) !== (templateDelta !== undefined)) {
+        throw new Error("Persisted template diagnostics are inconsistent with the plan version.");
+    }
+    const verdict = evaluateBlock({
+        allowNewErrors: persisted.allow_new_errors,
+        typescriptErrors: addedErrors.length,
+        template: templateDelta,
+        blockOnTemplateErrors: persisted.block_on_template_errors ?? false,
+    });
+    if (persisted.blocked !== verdict.blocked) {
         throw new Error("Persisted blocked status is inconsistent with diagnostics policy.");
     }
     const fullPreview = files.map((file) => file.diff).join("\n");
     const record = {
         ...persisted,
         affected_files: affectedFiles,
-        blocked,
-        block_reason: blocked
-            ? `${addedErrors.length} new TypeScript error(s) would be introduced. Prepare again with allow_new_errors=true only after explicit review.`
-            : null,
+        blocked: verdict.blocked,
+        block_reason: verdict.reason,
         preview: fullPreview.length <= MAX_INLINE_PREVIEW_CHARS ? fullPreview : null,
         preview_truncated: fullPreview.length > MAX_INLINE_PREVIEW_CHARS,
         tsConfigFilePath: context.tsConfigFilePath,

package/dist/services/project-operation-scheduler.js

@@ -354,6 +354,10 @@ export class ProjectOperationScheduler {
             checkpoint: () => {
                 this.#checkpoint(node);
             },
+            remainingMs: () => {
+                const startedAt = node.executionStartedAt ?? this.#readNow();
+                return Math.max(0, this.#operationDeadlineMs - (this.#readNow() - startedAt));
+            },
             markExecuting: () => {
                 this.#checkpoint(node);
                 if (node.phase !== "synchronizing") {

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),
@@ -69,7 +53,7 @@ const ReferenceOutputSchemas = {
 export function registerFindReferences(server) {
     server.registerTool(TOOL_NAME, {
         title: "Find semantic symbol references",
-        description: "Finds type-resolved references and returns bounded project-relative locations, including declaration impact by default. When @angular/compiler resolves, it also reports Angular template usages, including consumer templates, tagged by origin with a template_coverage verdict; completed covers templates inside the Project only, incomplete coverage does not prove absence, and template errors are not diagnosed.",
+        description: "Finds type-resolved references and returns bounded project-relative locations, including declaration impact by default. When @angular/compiler resolves, it also reports Angular template usages, including consumer templates, tagged by origin with a template_coverage verdict; completed covers templates inside the Project only, incomplete coverage does not prove absence. It reports usages only; template type errors are reported by ast_rename_symbol plans in template_diagnostics.",
         inputSchema: AstFindReferencesInputSchema,
         annotations: {
             readOnlyHint: true,

package/dist/tools/operation-schema.js

@@ -34,6 +34,46 @@ export const PreparedOperationOutputSchema = z.object({
     preview: z.string().nullable(),
     preview_truncated: z.boolean(),
 });
+const TemplateDiagnosticsListSchema = z.array(NormalizedDiagnosticSchema);
+const NonCompletedTemplateListSchema = z.array(NormalizedDiagnosticSchema).max(0);
+/** Template type-check delta of a rename; present only when the check ran or tried to. */
+export const TemplateDiagnosticsSchema = z.discriminatedUnion("status", [
+    z
+        .object({
+        status: z.literal("completed"),
+        added: TemplateDiagnosticsListSchema,
+        removed: TemplateDiagnosticsListSchema,
+        added_errors: TemplateDiagnosticsListSchema,
+    })
+        .strict(),
+    z
+        .object({
+        status: z.enum(["unavailable", "unfinished"]),
+        reason: z.enum([
+            "compiler_cli_missing",
+            "compiler_unsupported",
+            "typescript_incompatible",
+            "work_exhausted",
+            "deadline",
+            "check_failed",
+        ]),
+        added: NonCompletedTemplateListSchema,
+        removed: NonCompletedTemplateListSchema,
+        added_errors: NonCompletedTemplateListSchema,
+    })
+        .strict(),
+]);
+/** Only `ast_rename_symbol` can carry template diagnostics, so only its contract changes. */
+export const RenameOperationOutputSchema = PreparedOperationOutputSchema.extend({
+    template_diagnostics: TemplateDiagnosticsSchema.optional(),
+});
+/** The one place that turns the record shape (`addedErrors`) into the wire shape. */
+export function toTemplateDiagnosticsOutput(delta) {
+    const lists = { added: delta.added, removed: delta.removed, added_errors: delta.addedErrors };
+    return delta.status === "completed"
+        ? { status: "completed", ...lists }
+        : { status: delta.status, reason: delta.reason, ...lists };
+}
 export function serializePreparedOperation(operation) {
     if (operation.status !== "prepared") {
         throw new Error(`Operation ${operation.operation_id} is not in prepared state.`);
@@ -60,5 +100,8 @@ export function serializePreparedOperation(operation) {
         block_reason: operation.block_reason,
         preview: operation.preview,
         preview_truncated: operation.preview_truncated,
+        ...(operation.template_diagnostics === undefined
+            ? {}
+            : { template_diagnostics: toTemplateDiagnosticsOutput(operation.template_diagnostics) }),
     };
 }

package/dist/tools/rename_symbol.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { prepareRename } from "../services/operations.js";
 import { createRequestContext } from "../services/request-context.js";
-import { PreparedOperationOutputSchema, serializePreparedOperation } from "./operation-schema.js";
+import { RenameOperationOutputSchema, serializePreparedOperation } from "./operation-schema.js";
 import { createToolErrorContext, errorResult, structuredResult } from "./result.js";
 const TOOL_NAME = "ast_rename_symbol";
 const AstRenameSymbolInputSchema = z.object({
@@ -17,20 +17,24 @@ const AstRenameSymbolInputSchema = z.object({
         .boolean()
         .default(false)
         .describe("Permit a plan with new TypeScript errors after explicit review."),
+    block_on_template_errors: z
+        .boolean()
+        .default(false)
+        .describe("Block the plan when a completed template check adds template errors. allow_new_errors still waives it."),
 });
 export function registerRenameSymbol(server) {
     server.registerTool(TOOL_NAME, {
         title: "Prepare a project-wide structural rename",
-        description: "Prepares an exact hash-bound rename plan without writing. Review the preview and apply its operation_id with ast_apply_operation. The plan also rewrites external Angular templates, including consumer templates when coverage is completed, hash-bound to the workspace snapshot; diagnostics stay TypeScript-only.",
+        description: "Prepares an exact hash-bound rename plan without writing. Review the preview and apply its operation_id with ast_apply_operation. The plan also rewrites external Angular templates, including consumer templates when coverage is completed, hash-bound to the workspace snapshot. The diagnostics field stays TypeScript-only; when templates are edited, template_diagnostics reports the template type-check delta separately with a typed status, and blocks only with block_on_template_errors=true.",
         inputSchema: AstRenameSymbolInputSchema,
-        outputSchema: PreparedOperationOutputSchema,
+        outputSchema: RenameOperationOutputSchema,
         annotations: {
             readOnlyHint: true,
             destructiveHint: false,
             idempotentHint: false,
             openWorldHint: false,
         },
-    }, async ({ project_root, file_path, symbol_path, new_name, dry_run, allow_new_errors }, extra) => {
+    }, async ({ project_root, file_path, symbol_path, new_name, dry_run, allow_new_errors, block_on_template_errors, }, extra) => {
         const requestContext = createRequestContext(extra.signal);
         try {
             if (!dry_run) {
@@ -42,6 +46,7 @@ export function registerRenameSymbol(server) {
                 symbolPath: symbol_path,
                 newName: new_name,
                 allowNewErrors: allow_new_errors,
+                blockOnTemplateErrors: block_on_template_errors,
             }, requestContext);
             return structuredResult(serializePreparedOperation(operation));
         }

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.16.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",
@@ -26,6 +26,9 @@
   },
   "type": "module",
   "packageManager": "yarn@4.15.0",
+  "workspaces": [
+    "test/angular-matrix/*"
+  ],
   "dsh": {
     "bundle": {
       "patch": "./cordis.patch.yml"
@@ -65,12 +68,14 @@
     "hono": "4.13.13",
     "minimatch": "11.0.3",
     "nanoid": "3.3.18",
-    "qs": "6.16.1"
+    "qs": "6.16.1",
+    "@babel/core@npm:7.25.2": "npm:7.29.7",
+    "@babel/core@npm:7.26.9": "npm:7.29.7"
   },
   "scripts": {
     "build": "tsc",
     "typecheck": "tsc --noEmit && tsc -p tsconfig.test.json",
-    "test": "vitest run --exclude test/supervised-worker.integration.test.ts && yarn build && vitest run test/supervised-worker.integration.test.ts --no-file-parallelism",
+    "test": "vitest run --exclude test/supervised-worker.integration.test.ts --exclude test/angular-template-typecheck.integration.test.ts --exclude test/operations-template-typecheck.integration.test.ts && yarn build && vitest run test/supervised-worker.integration.test.ts test/angular-template-typecheck.integration.test.ts test/operations-template-typecheck.integration.test.ts --no-file-parallelism",
     "test:watch": "vitest",
     "test:mcp": "yarn build && node scripts/mcp-smoke.mjs",
     "test:lifecycle": "yarn build && node scripts/mcp-lifecycle-smoke.mjs",
@@ -86,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",
@@ -135,5 +141,5 @@
     "vitest": "^5.0.5",
     "yaml": "^2.9.0"
   },
-  "gitHead": "0f5a3f137703fdd673640d00a04087db3b2808af"
+  "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.7.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,8 +64,8 @@ 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.
-- Diagnostics stay TypeScript-only: `ast_get_diagnostics` and the post-apply delta do not detect template errors, including in rewritten consumer templates. A template-only breakage produces no diagnostic, so run the project's Angular build or tests after a rename. Template type checking of rename plans is tracked in issue #421.
+- `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`.
 
 ## Contributor contract

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

@@ -22,7 +22,11 @@ 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), and diagnostics stay TypeScript-only, so template errors are never detected; template type checking of rename plans is tracked in issue #421.
+`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.
 
 `ast_rename_symbol` edits external templates, including consumer templates of a selector-bound member with `completed` coverage, and returns `INCOMPLETE_EVIDENCE` (coverage `unfinished` or `unsupported`, `hostDirectives`, `@Directive` members, metadata-listed members, non-literal aliases) or `MUTATION_BLOCKED` (inline usage, template-local or binding-name collision, `[(x)]` on a non-`model()` pair, `$any`, name in the selector). Renaming a `@Pipe` class applies TypeScript edits only and keeps the `name` literal and `| name` usages; renaming `transform` returns `INCOMPLETE_EVIDENCE`. The user's `@angular/compiler` is an optional peer, never bundled; Yarn PnP projects without `node_modules` report `unfinished`. See the Angular templates section of `SKILL.md`.