ast-mcp-server 0.16.0 → 0.18.0

package/dist/services/angular-templates.js

@@ -1,5 +1,5 @@
 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";
@@ -8,45 +8,17 @@ 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");
@@ -203,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)
@@ -323,9 +295,12 @@ function extractUsages(compiler, nodes, query, rc, onNode = () => { }) {
         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);
@@ -431,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;
@@ -492,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);
@@ -514,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 {
@@ -536,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;
@@ -553,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") {
@@ -608,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: [],
@@ -619,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) => ({
@@ -635,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)
@@ -645,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)
@@ -660,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;
@@ -694,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/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 = {}) {