ast-mcp-server 0.15.1 → 0.17.0

package/dist/services/angular-templates.js

@@ -1,48 +1,24 @@
 import { createHash } from "node:crypto";
-import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { 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 { angularCoreMajor, componentDecorator, isCoreDecorator, isDirectiveClass, isMetadataPublic, isPipeClass, isSelectorPublic, literalString, bindingNames, metadataBindingNames, } from "./angular-decorators.js";
+import { extractConsumerUsages, mayMatch, } from "./angular-template-bindings.js";
+import { createScopeResolver, MAX_SCOPE_VISITS, ScopeWorkExhausted, } from "./angular-template-scope.js";
+import { isSupportedVersion, isUnderAncestorNodeModules, isWithin, resolveFrom, } from "./angular-package-resolution.js";
 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 = 18;
-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 SCAN_LIMITS = { templates: 2000, bytes: 32 * 1024 * 1024, nodes: 1_000_000 };
 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");
@@ -92,7 +68,12 @@ async function loadCompiler(tsConfigFilePath) {
                 compiler.PropertyRead,
                 compiler.Call,
             ].every((member) => typeof member === "function");
-        return complete ? { compiler } : unsupported;
+        const selectors = [
+            compiler.CssSelector?.parse,
+            compiler.SelectorMatcher,
+            compiler.createCssSelectorFromNode,
+        ].every((member) => typeof member === "function");
+        return complete ? { compiler, selectors } : unsupported;
     }
     catch {
         return unsupported;
@@ -101,29 +82,6 @@ async function loadCompiler(tsConfigFilePath) {
 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" };
@@ -201,7 +159,7 @@ export function listTemplateFiles(context) {
     }
     return [...files].sort();
 }
-function memberOwner(node) {
+export function memberOwner(node) {
     let owner;
     if (Node.isParameterDeclaration(node)) {
         owner = node.isParameterProperty() ? node.getParent()?.getParent() : undefined;
@@ -232,8 +190,12 @@ function hasDerivedComponent(context, cls) {
 }
 class WorkExhausted extends Error {
 }
+/** A pipe name span that does not slice to the name: the usage cannot be edited exactly. */
+class SpanDrift extends Error {
+}
 /** Walks parsed template nodes with a scope stack so template-local names shadow members. */
-function extractUsages(compiler, nodes, memberName, rc) {
+function extractUsages(compiler, nodes, query, rc, onNode = () => { }) {
+    const memberName = "member" in query ? query.member : undefined;
     const usages = new Map();
     const scopes = [];
     let visited = 0;
@@ -242,6 +204,7 @@ function extractUsages(compiler, nodes, memberName, rc) {
             throw new WorkExhausted();
         if (visited % CHECKPOINT_EVERY_NODES === 0)
             rc.checkpoint();
+        onNode();
     };
     const isLocal = (name) => scopes.some((scope) => scope.has(name));
     const record = (ast, kind) => {
@@ -251,13 +214,15 @@ function extractUsages(compiler, nodes, memberName, rc) {
             start: ast.nameSpan.start,
             end: ast.nameSpan.end,
             kind: merged,
+            role: "own",
             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 &&
+    const isMember = (ast) => memberName !== undefined &&
+        ast instanceof compiler.PropertyRead &&
         ast.name === memberName &&
         isMemberReceiver(ast.receiver);
     class Expressions extends compiler.RecursiveAstVisitor {
@@ -287,6 +252,15 @@ function extractUsages(compiler, nodes, memberName, rc) {
             record(ast.left, "TemplatePropertyWrite");
             this.visit(ast.right, context);
         }
+        visitPipe(ast, context) {
+            if ("pipe" in query && ast.name === query.pipe) {
+                if (query.text.slice(ast.nameSpan.start, ast.nameSpan.end) !== query.pipe) {
+                    throw new SpanDrift();
+                }
+                record(ast, "TemplatePipeName");
+            }
+            super.visitPipe(ast, context);
+        }
         visitPropertyWrite(ast, context) {
             if (ast.name === memberName && isMemberReceiver(ast.receiver)) {
                 record(ast, "TemplatePropertyWrite");
@@ -321,9 +295,12 @@ function extractUsages(compiler, nodes, memberName, rc) {
         return collector.names;
     };
     class Templates extends compiler.TmplAstRecursiveVisitor {
+        // v18/v19 `tmplAstVisitAll` runs `visitor.visit(node) || node.visit(visitor)`; returning
+        // true marks the node handled so each subtree is walked once instead of twice per level.
         visit(node) {
             tick();
             node.visit(this);
+            return true;
         }
         view(locals, children, before) {
             const names = [...locals, ...referencesOf(children)].filter((name) => !!name);
@@ -429,81 +406,274 @@ function decodeTemplate(bytes) {
         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);
+/** Reads a located template within the per-template size cap. */
+async function readTemplate(context, located) {
     let text;
-    let offset = 0;
     let bytes;
     if (located.container === "inline") {
-        ({ text, offset } = located);
+        text = located.text;
         bytes = Buffer.from(text, "utf8");
     }
     else {
         const unsafe = checkTemplatePath(context.projectRoot, located.absolutePath);
         if (unsafe)
-            return fail("unfinished", unsafe);
+            return { reason: unsafe };
         if ((await stat(located.absolutePath)).size > MAX_TEMPLATE_BYTES) {
-            return fail("unfinished", "size_exceeded");
+            return { reason: "size_exceeded" };
         }
         bytes = await readFile(located.absolutePath);
         const decoded = decodeTemplate(bytes);
         if (decoded === undefined)
-            return fail("unfinished", "template_parse_error");
+            return { reason: "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");
+        return { reason: "size_exceeded" };
+    return { text, bytes, offset: located.container === "inline" ? located.offset : 0 };
+}
+function toUsages(context, cls, located, read, raw) {
+    const fileText = located.container === "inline" ? cls.getSourceFile().getFullText() : read.text;
+    const fileHash = createHash("sha256").update(read.bytes).digest("hex");
+    return raw.map((usage) => {
+        const start = usage.start + read.offset;
+        return {
+            ...usage,
+            absolutePath: located.absolutePath,
+            file: path.relative(context.projectRoot, located.absolutePath),
+            container: located.container,
+            start,
+            end: usage.end + read.offset,
+            ...lineColumn(fileText, start),
+            fileHash,
+        };
+    });
+}
+/** Selector and public binding names, or undefined when bindings cannot be named from the member. */
+function bindingTarget(cls, node, name) {
+    const metadata = componentDecorator(cls)?.getArguments()[0];
+    if (!Node.isObjectLiteralExpression(metadata) || metadata.getProperty("hostDirectives")) {
+        return undefined;
+    }
+    const property = metadata.getProperty("selector");
+    const selector = literalString(Node.isPropertyAssignment(property) ? property.getInitializer() : undefined);
+    const names = isMetadataPublic(cls, name)
+        ? // A member both decorated and listed in metadata has ambiguous binding names.
+            isSelectorPublic(node)
+                ? undefined
+                : metadataBindingNames(cls, name)
+        : bindingNames(node, name);
+    if (!selector || !names)
+        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) => {
+        if (!mayMatch(compiler, target.selector, text))
+            return "skip";
+        const nodes = parseConsumer(compiler, text, absolutePath);
+        if (!nodes)
+            return "template_parse_error";
+        const scan = extractConsumerUsages(compiler, nodes, text, target, tick);
+        const usages = scan.usages.map((usage) => ({
+            ...usage,
+            localsInScope: [],
+            role: "consumer",
+        }));
+        return { matched: scan.matched, opaque: scan.opaque, usages };
+    };
+}
+function pipeInspector(compiler, name, rc) {
+    return (text, absolutePath, tick) => {
+        if (!text.includes(name))
+            return "skip";
+        const nodes = parseConsumer(compiler, text, absolutePath);
+        if (!nodes)
+            return "template_parse_error";
+        try {
+            const raw = extractUsages(compiler, nodes, { pipe: name, text }, rc, tick);
+            const usages = raw.map((usage) => ({ ...usage, role: "consumer" }));
+            return { matched: usages.length > 0, opaque: false, usages };
+        }
+        catch (error) {
+            if (error instanceof SpanDrift)
+                return { matched: true, opaque: true, usages: [] };
+            throw error;
+        }
+    };
+}
+/**
+ * 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) {
+    const remaining = { ...SCAN_LIMITS, ...limits };
+    const usages = [];
+    let failure;
+    let examined = 0;
+    const resolve = createScopeResolver(cls, {
+        coreMajor: angularCoreMajor(context),
+        budget: { scopeVisits: MAX_SCOPE_VISITS },
+        rc,
+    });
+    const tick = () => {
+        if (--remaining.nodes < 0)
+            throw new WorkExhausted();
+        if (remaining.nodes % CHECKPOINT_EVERY_NODES === 0)
+            rc.checkpoint();
+    };
+    try {
+        for (const consumer of componentClasses(context)) {
+            rc.checkpoint();
+            if (--remaining.templates < 0)
+                throw new WorkExhausted();
+            const located = locateTemplate(consumer);
+            if ("reason" in located) {
+                failure ??= located.reason;
+                continue;
+            }
+            const read = await readTemplate(context, located);
+            if ("reason" in read) {
+                failure ??= read.reason;
+                continue;
+            }
+            remaining.bytes -= read.bytes.length;
+            if (remaining.bytes < 0)
+                throw new WorkExhausted();
+            examined += 1;
+            const scan = inspect(read.text, located.absolutePath, tick);
+            if (scan === "skip")
+                continue;
+            if (scan === "template_parse_error") {
+                failure ??= scan;
+                continue;
+            }
+            if (scan.opaque)
+                failure ??= "cross_component";
+            if (!scan.matched)
+                continue;
+            const verdict = resolve(consumer);
+            if (verdict === "opaque")
+                failure ??= "cross_component";
+            if (verdict === "includes") {
+                usages.push(...toUsages(context, consumer, located, read, scan.usages));
+            }
+        }
+    }
+    catch (error) {
+        if (error instanceof WorkExhausted || error instanceof ScopeWorkExhausted) {
+            return { usages: [], failure: "work_exhausted", examined };
+        }
+        throw error;
+    }
+    return { usages, failure, examined };
+}
+/** The literal `name` of a `@Pipe({ name })` class, or undefined when it is not a plain literal. */
+function pipeName(cls) {
+    const decorator = cls.getDecorators().find((candidate) => isCoreDecorator(candidate, "Pipe"));
+    const metadata = decorator?.getArguments()[0];
+    if (!Node.isObjectLiteralExpression(metadata))
+        return undefined;
+    const property = metadata.getProperty("name");
+    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) {
+    const unfinished = (reason, templates = 0) => ({
+        coverage: { status: "unfinished", reason, templates },
+        usages: [],
+    });
+    const name = pipeName(cls);
+    if (name === undefined)
+        return unfinished("cross_component");
+    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 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 = {}) {
     rc.checkpoint();
-    const parsed = loaded.compiler.parseTemplate(text, located.absolutePath, {
+    if (!hasAngularCore(context))
+        return NOT_APPLICABLE;
+    const fail = (status, reason) => ({
+        coverage: { status, reason, templates: 0 },
+        usages: [],
+    });
+    if (Node.isClassDeclaration(node)) {
+        return isPipeClass(node) ? collectPipeUsages(node, context, rc, limits) : NOT_APPLICABLE;
+    }
+    const owner = memberOwner(node);
+    if (!owner)
+        return NOT_APPLICABLE;
+    if (isPipeClass(owner.cls)) {
+        // Only `transform` is the pipe contract: it reports the pipe's usages but a rename stays refused.
+        if (owner.name !== "transform" || componentDecorator(owner.cls)) {
+            return fail("unfinished", "cross_component");
+        }
+        return { ...(await collectPipeUsages(owner.cls, context, rc, limits)), 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);
+    if (!isComponent && !derived)
+        return NOT_APPLICABLE;
+    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);
+    const read = await readTemplate(context, located);
+    if ("reason" in read)
+        return fail("unfinished", read.reason);
+    rc.checkpoint();
+    const parsed = loaded.compiler.parseTemplate(read.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);
+        raw = extractUsages(loaded.compiler, parsed.nodes, { member: 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,
-        };
+    const usages = toUsages(context, owner.cls, located, read, raw);
+    if (!selectorPublic)
+        return { coverage: { status: "completed", templates: 1 }, usages };
+    // Selector-public members are also bound in consuming templates: scan every component template.
+    const target = bindingTarget(owner.cls, node, owner.name);
+    const unfinished = (reason, templates = 1) => ({
+        coverage: { status: "unfinished", reason, templates },
+        usages,
     });
-    return { coverage: { status: "completed", templates: 1 }, usages };
+    if (!target)
+        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 coverage = scan.failure
+        ? { status: "unfinished", reason: scan.failure, templates: scan.examined }
+        : { status: "completed", templates: scan.examined };
+    // Names listed in `inputs` / `outputs` metadata are strings that a TypeScript rename cannot follow.
+    const renameBlocked = isMetadataPublic(owner.cls, owner.name);
+    return { coverage, usages: [...usages, ...scan.usages], renameBlocked };
 }

package/dist/services/h03-timeout-fixture.js

@@ -38,7 +38,7 @@ export class H05LifecycleFixtureController {
         const generationSignal = this.#generationAbort.signal, signal = AbortSignal.any([context.signal, generationSignal]);
         const checkpoint = () => { if (!this.accepts(identity) || generationSignal.aborted)
             throw new H03TimeoutFixtureError(); context.checkpoint(); };
-        const hooked = Object.freeze({ get sequence() { return context.sequence; }, get phase() { return context.phase; }, signal, checkpoint, markExecuting: () => context.markExecuting(), enterCompletionCritical: () => { checkpoint(); context.enterCompletionCritical(); } });
+        const hooked = Object.freeze({ get sequence() { return context.sequence; }, get phase() { return context.phase; }, signal, checkpoint, markExecuting: () => context.markExecuting(), remainingMs: () => context.remainingMs(), enterCompletionCritical: () => { checkpoint(); context.enterCompletionCritical(); } });
         this.#active += 1;
         this.#emit({ ...eventIdentity, phase: "started" });
         try {
@@ -201,6 +201,7 @@ export class H03TimeoutFixtureController {
             signal,
             checkpoint,
             markExecuting: () => context.markExecuting(),
+            remainingMs: () => context.remainingMs(),
             enterCompletionCritical: () => {
                 checkpoint();
                 context.enterCompletionCritical();

package/dist/services/operation-block-policy.js

@@ -0,0 +1,19 @@
+const REVIEW_HINT = "Prepare again with allow_new_errors=true only after explicit review.";
+/**
+ * A plan is blocked by new TypeScript errors, and, only when opted in, by new template errors of
+ * a `completed` check. A check that did not complete never blocks. `allow_new_errors` waives both.
+ */
+export function evaluateBlock(input) {
+    const templateErrors = input.blockOnTemplateErrors && input.template?.status === "completed"
+        ? input.template.addedErrors.length
+        : 0;
+    const reasons = [
+        ...(input.typescriptErrors > 0
+            ? [`${input.typescriptErrors} new TypeScript error(s) would be introduced.`]
+            : []),
+        ...(templateErrors > 0 ? [`${templateErrors} new template error(s) would be introduced.`] : []),
+    ];
+    if (input.allowNewErrors || reasons.length === 0)
+        return { blocked: false, reason: null };
+    return { blocked: true, reason: `${reasons.join(" ")} ${REVIEW_HINT}` };
+}

package/dist/services/operation-plan-file.js

@@ -6,6 +6,8 @@ import { z } from "zod";
 import { applyOperation, configureOperationApply, exportOperationRecord, importOperationRecord, } from "./operations.js";
 import { ensurePrivateDirectory, resolveRuntimeStateDirectory, } from "./runtime-state.js";
 export const PLAN_SCHEMA_VERSION = 2;
+/** Plans that carry a template type-check delta persist as this version. */
+export const TEMPLATE_PLAN_SCHEMA_VERSION = 3;
 export const MAX_PLAN_BYTES = 50 * 1024 * 1024;
 const HashSchema = z.string().regex(/^[a-f0-9]{64}$/);
 const IsoDateSchema = z.string().datetime({ offset: true });
@@ -38,8 +40,27 @@ const PersistedFileSchema = AffectedFileSchema.extend({
     updated_bytes_base64: z.string(),
     mode: z.number().int().nonnegative(),
 }).strict();
-const PersistedOperationSchema = z
-    .object({
+const TemplateReasonSchema = z.enum([
+    "compiler_cli_missing",
+    "compiler_unsupported",
+    "typescript_incompatible",
+    "work_exhausted",
+    "deadline",
+    "check_failed",
+]);
+const TemplateDiagnosticsSchema = z.discriminatedUnion("status", [
+    DiagnosticDeltaSchema.extend({ status: z.literal("completed") }).strict(),
+    z
+        .object({
+        status: z.enum(["unavailable", "unfinished"]),
+        reason: TemplateReasonSchema,
+        added: z.array(DiagnosticSchema).max(0),
+        removed: z.array(DiagnosticSchema).max(0),
+        addedErrors: z.array(DiagnosticSchema).max(0),
+    })
+        .strict(),
+]);
+const PersistedOperationShape = {
     operation_id: z.string().uuid(),
     plan_hash: HashSchema,
     kind: z.enum(["rename_symbol", "replace_symbol_body", "scaffold_class"]),
@@ -60,14 +81,24 @@ const PersistedOperationSchema = z
     preview_truncated: z.boolean(),
     applied_at: IsoDateSchema.optional(),
     files: z.array(PersistedFileSchema).min(1),
+};
+const PersistedOperationSchema = z.object(PersistedOperationShape).strict();
+const PersistedOperationV3Schema = z
+    .object({
+    ...PersistedOperationShape,
+    template_diagnostics: TemplateDiagnosticsSchema,
+    block_on_template_errors: z.boolean(),
 })
     .strict();
 const PlanEnvelopeSchema = z.discriminatedUnion("schema_version", [
     z.object({ schema_version: z.literal(1), operation: PersistedOperationSchema }).strict(),
     z.object({ schema_version: z.literal(2), operation: PersistedOperationSchema }).strict(),
+    z.object({ schema_version: z.literal(3), operation: PersistedOperationV3Schema }).strict(),
 ]);
 function planEnvelope(version, operation) {
-    return version === 1 ? { schema_version: 1, operation } : { schema_version: 2, operation };
+    if (version === 1)
+        return { schema_version: 1, operation };
+    return version === 2 ? { schema_version: 2, operation } : { schema_version: 3, operation };
 }
 function stateDirectory(options) {
     return resolveRuntimeStateDirectory(options);
@@ -148,7 +179,10 @@ async function readPlanEnvelope(planFileInput) {
 export async function persistOperationPlan(operationId, options = {}) {
     const plansDirectory = path.join(stateDirectory(options), "plans");
     const planFile = path.join(plansDirectory, `${operationId}.astplan`);
-    await atomicWritePlan(planFile, planEnvelope(PLAN_SCHEMA_VERSION, exportOperationRecord(operationId)));
+    const record = exportOperationRecord(operationId);
+    await atomicWritePlan(planFile, planEnvelope(record.template_diagnostics === undefined
+        ? PLAN_SCHEMA_VERSION
+        : TEMPLATE_PLAN_SCHEMA_VERSION, record));
     return planFile;
 }
 export async function applyPersistedOperation(planFileInput, planHash, options = {}) {