ast-mcp-server 0.14.3 → 0.15.1

package/dist/services/operations.js

@@ -4,6 +4,8 @@ import { open, readFile, stat } from "node:fs/promises";
 import path from "node:path";
 import { createTwoFilesPatch } from "diff";
 import { LanguageVariant, Node, ScriptTarget, SyntaxKind, ts } from "ts-morph";
+import { collectTemplateUsages } from "./angular-templates.js";
+import { findNonDeclarationReferences } from "./references.js";
 import { compareObservedDiagnostics, observeDiagnostic, } from "./diagnostics.js";
 import { probePublicationCapability, publishAuthenticated, removeOwnedPublicationEntry, rollbackOwnedCommit, snapshotHeldFile, } from "./authenticated-publication.js";
 import { createFreshProject, findDeclarationByName, getSourceFileOrThrow, invalidateProjectIfIdle, recordProjectMutationHistory, withProjectOperation, } from "./project.js";
@@ -12,6 +14,7 @@ import { NO_REQUEST_CONTEXT } from "./request-context.js";
 import { executableDeclaration } from "./symbols.js";
 import { buildClassScaffold } from "./scaffold.js";
 import { withWorkspaceFileLock } from "./runtime-state.js";
+import { assertSafeOperationFile } from "./safe-file.js";
 import { createWorkspaceSnapshot, hashBytes, hashWorkspaceFiles } from "./workspace.js";
 const DEFAULT_OPERATION_TTL_MS = 15 * 60 * 1000;
 const DEFAULT_MAX_OPERATIONS = 100;
@@ -104,33 +107,6 @@ function encodeUpdatedSource(originalBytes, updatedText) {
     const hasUtf8Bom = originalBytes[0] === 0xef && originalBytes[1] === 0xbb && originalBytes[2] === 0xbf;
     return hasUtf8Bom ? Buffer.concat([Buffer.from([0xef, 0xbb, 0xbf]), encoded]) : encoded;
 }
-function assertSafeOperationFile(projectRoot, absolutePath, displayPath) {
-    const fileStat = lstatSync(absolutePath);
-    if (fileStat.isSymbolicLink()) {
-        throw new Error(`Operation target must not be a symbolic link: ${displayPath}`);
-    }
-    if (!fileStat.isFile()) {
-        throw new Error(`Operation target is not a regular file: ${displayPath}`);
-    }
-    const canonicalPath = realpathSync(absolutePath);
-    const samePath = process.platform === "win32"
-        ? canonicalPath.toLowerCase() === absolutePath.toLowerCase()
-        : canonicalPath === absolutePath;
-    if (!samePath) {
-        throw new Error(`Operation target traverses a symbolic link: ${displayPath}`);
-    }
-    if (process.platform !== "win32" && fileStat.nlink !== 1) {
-        throw new Error(`Operation target must have exactly one hard link: ${displayPath}`);
-    }
-    const uid = process.getuid?.();
-    if (uid !== undefined && fileStat.uid !== uid) {
-        throw new Error(`Operation target is not owned by the current user: ${displayPath}`);
-    }
-    const relative = path.relative(projectRoot, canonicalPath);
-    if (relative === "" || relative === ".." || relative.startsWith(`..${path.sep}`)) {
-        throw new Error(`Operation target escapes the project root: ${displayPath}`);
-    }
-}
 function isCreatedFile(file) {
     return file.originalHash === ABSENT_FILE_HASH;
 }
@@ -178,7 +154,68 @@ function assertSafeCreationState(projectRoot, absolutePath, displayPath) {
         assertSafeNewOperationFile(projectRoot, absolutePath, displayPath);
     }
 }
-async function createPlan(projectRootInput, kind, allowNewErrors, mutate, requestContext) {
+function compareFiles(left, right) {
+    return left.file < right.file ? -1 : left.file > right.file ? 1 : 0;
+}
+function applyEditsDescending(text, edits, file) {
+    const ordered = [...edits].sort((left, right) => left.start - right.start);
+    let previousEnd = 0;
+    for (const edit of ordered) {
+        if (!(edit.start >= previousEnd && edit.end >= edit.start && edit.end <= text.length)) {
+            throw new Error(`Auxiliary edits overlap or fall outside the file: ${file}`);
+        }
+        previousEnd = edit.end;
+    }
+    return ordered
+        .reverse()
+        .reduce((updated, edit) => updated.slice(0, edit.start) + edit.newText + updated.slice(edit.end), text);
+}
+/** Plans edits to files outside the compiler program, bound to the workspace snapshot hashes. */
+async function planAuxiliaryFiles(edits, projectRoot, snapshotFiles, requestContext) {
+    const byFile = new Map();
+    for (const edit of edits) {
+        const absolutePath = realpathSync(edit.absolutePath);
+        byFile.set(absolutePath, [...(byFile.get(absolutePath) ?? []), edit]);
+    }
+    const planned = [];
+    for (const [absolutePath, fileEdits] of byFile) {
+        requestContext.checkpoint();
+        const file = path.relative(projectRoot, absolutePath);
+        assertSafeOperationFile(projectRoot, absolutePath, file);
+        const snapshotHash = snapshotFiles.get(absolutePath);
+        if (snapshotHash === undefined) {
+            throw new Error(`Affected file is missing from the workspace snapshot: ${file}`);
+        }
+        const originalBytes = await readFile(absolutePath);
+        requestContext.checkpoint();
+        const bytesHash = hashBytes(originalBytes);
+        if (bytesHash !== snapshotHash || fileEdits.some((edit) => edit.expectedHash !== bytesHash)) {
+            throw new Error(`Workspace changed while the operation was being prepared (${file}). Retry preparation.`);
+        }
+        const originalText = decodeSource(originalBytes, absolutePath);
+        const updatedText = applyEditsDescending(originalText, fileEdits, file);
+        if (updatedText === originalText)
+            continue;
+        const updatedBytes = encodeUpdatedSource(originalBytes, updatedText);
+        planned.push({
+            absolutePath,
+            file,
+            originalHash: bytesHash,
+            updatedHash: hashBytes(updatedBytes),
+            originalText,
+            updatedText,
+            originalBytes,
+            updatedBytes,
+            diff: createTwoFilesPatch(file, file, originalText, updatedText, "before", "after", {
+                context: 3,
+            }),
+            mode: (await stat(absolutePath)).mode,
+        });
+    }
+    return planned;
+}
+/** Internal seam shared by the prepare functions; exported so tests can drive `mutate` directly. */
+export async function createPlan(projectRootInput, kind, allowNewErrors, mutate, requestContext) {
     requestContext.checkpoint();
     let retainedOperationId;
     return withProjectOperation(projectRootInput, async (operationContext) => {
@@ -201,11 +238,12 @@ async function createPlan(projectRootInput, kind, allowNewErrors, mutate, reques
             }
         }
         operationContext.checkpoint();
-        const referenceCount = mutate(context.project, context.projectRoot);
+        const { referenceCount, auxiliaryEdits = [] } = await mutate(context, operationContext);
         operationContext.checkpoint();
         const afterObservations = observeProjectDiagnostics(context.project, context.projectRoot, operationContext);
         const textChanges = collectPlannedTextChanges(context.project, context.projectRoot, originals, operationContext);
-        if (textChanges.length === 0) {
+        const auxiliaryFiles = await planAuxiliaryFiles(auxiliaryEdits, context.projectRoot, workspaceBefore.files, operationContext);
+        if (textChanges.length === 0 && auxiliaryFiles.length === 0) {
             throw new Error("The structural operation produced no file changes.");
         }
         const comparisonWorkspace = createWorkspaceSnapshot(createFreshProject(context.tsConfigFilePath));
@@ -265,6 +303,8 @@ async function createPlan(projectRootInput, kind, allowNewErrors, mutate, reques
                 mode: fileStat.mode,
             });
         }
+        files.push(...auxiliaryFiles);
+        files.sort(compareFiles);
         const postWorkspaceFiles = new Map(workspaceBefore.files);
         for (const file of files) {
             operationContext.checkpoint();
@@ -348,6 +388,22 @@ function publicOperation(record) {
         preview_truncated: record.preview_truncated,
     };
 }
+const TEMPLATE_ANY_CAST = "$any";
+/** Fails closed before any edit when template evidence is incomplete or the new name would be captured. */
+function assertTemplateRenameAllowed(coverageStatus, usages, newName) {
+    if (coverageStatus === "unfinished" || coverageStatus === "unsupported") {
+        throw new PublicOperationalError("INCOMPLETE_EVIDENCE", "Template coverage is incomplete, so the rename cannot be proven safe.");
+    }
+    if (usages.some((usage) => usage.container === "inline")) {
+        throw new PublicOperationalError("MUTATION_BLOCKED", "The member is used in an inline template, which rename does not edit.");
+    }
+    const collides = coverageStatus === "completed" &&
+        (newName === TEMPLATE_ANY_CAST ||
+            usages.some((usage) => usage.localsInScope.includes(newName)));
+    if (collides) {
+        throw new PublicOperationalError("MUTATION_BLOCKED", "The new name would collide with a template-local name or the $any cast.");
+    }
+}
 export async function prepareRename(args, requestContext = NO_REQUEST_CONTEXT) {
     requestContext.checkpoint();
     const scanner = ts.createScanner(ScriptTarget.Latest, false, LanguageVariant.Standard, args.newName);
@@ -355,21 +411,33 @@ export async function prepareRename(args, requestContext = NO_REQUEST_CONTEXT) {
     if (!validIdentifier) {
         throw new Error(`"${args.newName}" is not a valid TypeScript identifier.`);
     }
-    return createPlan(args.projectRoot, "rename_symbol", args.allowNewErrors ?? false, (project) => {
-        const sourceFile = getSourceFileOrThrow(project, args.filePath);
+    return createPlan(args.projectRoot, "rename_symbol", args.allowNewErrors ?? false, async (context, rc) => {
+        const sourceFile = getSourceFileOrThrow(context.project, args.filePath);
         const node = findDeclarationByName(sourceFile, args.symbolPath);
         if (!Node.isRenameable(node)) {
             throw new Error(`Symbol "${args.symbolPath}" (${node.getKindName()}) does not support structural rename.`);
         }
-        const referenceCount = Node.isReferenceFindable(node)
-            ? node.findReferencesAsNodes().length
+        // Template usages must be collected before the rename mutates the program.
+        const { coverage, usages } = await collectTemplateUsages(node, context, rc);
+        assertTemplateRenameAllowed(coverage.status, usages, args.newName);
+        const tsReferenceCount = Node.isReferenceFindable(node)
+            ? findNonDeclarationReferences(node).length
             : 0;
         node.rename(args.newName);
-        return referenceCount;
+        return {
+            referenceCount: tsReferenceCount + usages.length,
+            auxiliaryEdits: usages.map((usage) => ({
+                absolutePath: usage.absolutePath,
+                start: usage.start,
+                end: usage.end,
+                newText: args.newName,
+                expectedHash: usage.fileHash,
+            })),
+        };
     }, requestContext);
 }
 export async function prepareReplaceBody(args, requestContext = NO_REQUEST_CONTEXT) {
-    return createPlan(args.projectRoot, "replace_symbol_body", args.allowNewErrors ?? false, (project) => {
+    return createPlan(args.projectRoot, "replace_symbol_body", args.allowNewErrors ?? false, async ({ project }) => {
         const sourceFile = getSourceFileOrThrow(project, args.filePath);
         const declaration = findDeclarationByName(sourceFile, args.symbolPath);
         const executable = executableDeclaration(declaration);
@@ -380,7 +448,7 @@ export async function prepareReplaceBody(args, requestContext = NO_REQUEST_CONTE
             executable.getBody().replaceWithText("{}");
         }
         executable.setBodyText(args.newBody);
-        return 0;
+        return { referenceCount: 0 };
     }, requestContext);
 }
 export async function prepareScaffoldClass(args, requestContext = NO_REQUEST_CONTEXT) {
@@ -399,7 +467,7 @@ export async function prepareScaffoldClass(args, requestContext = NO_REQUEST_CON
         throw new Error("Scaffold file_path must target a .ts or .tsx implementation file.");
     }
     let metadata;
-    const operation = await createPlan(args.projectRoot, "scaffold_class", args.allowNewErrors ?? false, (project, projectRoot) => {
+    const operation = await createPlan(args.projectRoot, "scaffold_class", args.allowNewErrors ?? false, async ({ project, projectRoot }) => {
         const absolutePath = path.resolve(projectRoot, normalizedFile);
         assertSafeNewOperationFile(projectRoot, absolutePath, normalizedFile);
         const scaffold = buildClassScaffold(project, absolutePath, args.spec);
@@ -407,7 +475,7 @@ export async function prepareScaffoldClass(args, requestContext = NO_REQUEST_CON
             outline: scaffold.outline,
             pendingMethods: scaffold.pendingMethods,
         };
-        return 0;
+        return { referenceCount: 0 };
     }, requestContext);
     if (!metadata)
         throw new Error("Scaffold generation did not produce metadata.");

package/dist/services/project.js

@@ -1,6 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
-import { Project } from "ts-morph";
+import { Project, ts } from "ts-morph";
 // prettier-ignore
 import { bindConfiguredH03Error, captureConfiguredH03Command, captureConfiguredH05Command, runConfiguredH03Fixture, runConfiguredH05Fixture } from "./h03-timeout-fixture.js";
 import { InMemorySymbolIndex, SYMBOL_INDEX_SCHEMA_VERSION, } from "./symbol-index.js";
@@ -9,10 +9,12 @@ import { openSQLiteSymbolIndexStore, quarantineSQLiteSymbolIndexFile, } from "./
 import { findDeclaration, sourceFileIndexSymbols } from "./symbols.js";
 import { createProjectWatcher, selectProjectWatchDirectories, } from "./project-watcher.js";
 import { createConfigSnapshot, createWorkspaceSnapshot } from "./workspace.js";
+import { listTemplateFiles } from "./angular-templates.js";
 import { createInitialProjectStatus, createProjectIdentity, projectOperationQueueToProjection, projectStatusToProjection, transitionProjectStatus, } from "./project-status.js";
 import { ProjectOperationScheduler, ProjectOperationSchedulerError, } from "./project-operation-scheduler.js";
 import { isCooperativeInterruption, NO_REQUEST_CONTEXT, } from "./request-context.js";
 import { readRuntimePolicy } from "./runtime-policy.js";
+import { PublicOperationalError } from "./public-errors.js";
 export class ProjectCapacityError extends Error {
     code = "PROJECT_CAPACITY_EXCEEDED";
     constructor() {
@@ -203,10 +205,43 @@ export function resolveTsConfigPath(projectRoot) {
     }
     const candidate = path.join(abs, "tsconfig.json");
     if (fs.existsSync(candidate)) {
-        return fs.realpathSync(candidate);
+        const resolved = fs.realpathSync(candidate);
+        const references = solutionStyleReferences(resolved);
+        if (references !== null) {
+            throw new PublicOperationalError("PROJECT_NOT_FOUND", `"${resolved}" is a solution-style tsconfig with no source files and ${references.length} project reference${references.length === 1 ? "" : "s"} (${references.join(", ")}). Pass one of the referenced configs as project_root.`);
+        }
+        return resolved;
     }
     throw new Error(`No tsconfig.json found at "${abs}". Pass a project directory containing tsconfig.json or the config file itself.`);
 }
+/**
+ * Detect a solution-style config (`tsc -b` root: no `files`/`include` of its
+ * own, only `references`). Returns the referenced paths as written, or `null`
+ * when the config declares sources or cannot be read; unreadable configs keep
+ * the existing compiler-failure path.
+ */
+function solutionStyleReferences(tsConfigFilePath) {
+    try {
+        const { config, error } = ts.readConfigFile(tsConfigFilePath, ts.sys.readFile);
+        if (error !== undefined || typeof config !== "object" || config === null)
+            return null;
+        const raw = config;
+        if (raw.include !== undefined || !Array.isArray(raw.references))
+            return null;
+        const references = raw.references.flatMap((reference) => typeof reference === "object" &&
+            reference !== null &&
+            typeof reference.path === "string"
+            ? [reference.path]
+            : []);
+        if (references.length === 0)
+            return null;
+        const parsed = ts.parseJsonConfigFileContent(config, ts.sys, path.dirname(tsConfigFilePath));
+        return parsed.fileNames.length === 0 ? references : null;
+    }
+    catch {
+        return null;
+    }
+}
 function buildProjectContext(tsConfigFilePath) {
     const project = new Project({
         tsConfigFilePath,
@@ -330,6 +365,13 @@ function assertProjectRuntimeAdmissionOpen() {
         throw new ProjectOperationSchedulerError("SERVER_SHUTTING_DOWN");
     }
 }
+/** Compiler sources plus external templates, which sit outside the TS program but join the hash. */
+function watchedFilePaths(context) {
+    return [
+        ...context.project.getSourceFiles().map((sourceFile) => sourceFile.getFilePath()),
+        ...listTemplateFiles(context),
+    ];
+}
 function createProjectSession(projectRoot, runtimePolicy, symbolIndexPolicy, requestContext, lastAccessSequence) {
     requestContext.checkpoint();
     const tsConfigFilePath = resolveTsConfigPath(projectRoot);
@@ -338,7 +380,7 @@ function createProjectSession(projectRoot, runtimePolicy, symbolIndexPolicy, req
         ...baseContext,
         symbolIndexObservability: createInitialSymbolIndexRuntimeObservability(symbolIndexPolicy),
     };
-    const watchDirectories = selectProjectWatchDirectories(context.projectRoot, context.project.getSourceFiles().map((sourceFile) => sourceFile.getFilePath()));
+    const watchDirectories = selectProjectWatchDirectories(context.projectRoot, watchedFilePaths(context));
     const owner = {};
     const watcher = createSessionWatcher(() => owner.session, context.projectRoot, watchDirectories);
     const session = {
@@ -430,7 +472,7 @@ async function synchronizeSession(session, requestContext) {
                 project.removeSourceFile(sourceFile);
         }
         requestContext.checkpoint();
-        replaceSessionWatcher(session, selectProjectWatchDirectories(session.context.projectRoot, project.getSourceFiles().map((sourceFile) => sourceFile.getFilePath())));
+        replaceSessionWatcher(session, selectProjectWatchDirectories(session.context.projectRoot, watchedFilePaths(session.context)));
         requestContext.checkpoint();
         const snapshot = createWorkspaceSnapshot(session.context, {
             previousFingerprints: session.fingerprints,

package/dist/services/references.js

@@ -1,8 +1,24 @@
+import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { Node } from "ts-morph";
+import { collectTemplateUsages, } from "./angular-templates.js";
 import { paginate } from "./pagination.js";
 import { NO_REQUEST_CONTEXT } from "./request-context.js";
-export function collectSymbolReferences(node, projectRoot, symbolPath, includeDeclaration, detail, offset, limit, requestContext = NO_REQUEST_CONTEXT) {
+/**
+ * Semantic references of `node` excluding the declaration itself.
+ *
+ * ts-morph only skips the first definition entry per referenced symbol; when a usage
+ * precedes the declaration in source order the declaration identifier is returned again
+ * as an ordinary reference. Drop any node at the declaration's position (the declaration
+ * node or its name identifier) so the declaration is reported exactly once.
+ */
+export function findNonDeclarationReferences(node) {
+    const declarationNodes = Node.hasName(node) ? [node, node.getNameNode()] : [node];
+    const isDeclaration = (reference) => declarationNodes.some((declaration) => declaration.getSourceFile().getFilePath() === reference.getSourceFile().getFilePath() &&
+        declaration.getStart() === reference.getStart());
+    return node.findReferencesAsNodes().filter((reference) => !isDeclaration(reference));
+}
+function collectTsLocations(node, projectRoot, symbolPath, includeDeclaration, detail, requestContext) {
     requestContext.checkpoint();
     if (!Node.isReferenceFindable(node)) {
         throw new Error(`Symbol "${symbolPath}" (${node.getKindName()}) does not support semantic reference search.`);
@@ -30,13 +46,24 @@ export function collectSymbolReferences(node, projectRoot, symbolPath, includeDe
         };
     };
     requestContext.checkpoint();
-    const references = node.findReferencesAsNodes().map((reference) => location(reference, false));
+    const references = findNonDeclarationReferences(node).map((reference) => location(reference, false));
     const declaration = location(node, true);
-    const allLocations = includeDeclaration ? [declaration, ...references] : references;
+    return {
+        declaration,
+        references,
+        locations: includeDeclaration ? [declaration, ...references] : [...references],
+    };
+}
+function compareLocations(left, right) {
+    const key = (item) => `${item.file}:${item.line}:${item.column}:${item.is_declaration ? 0 : 1}`;
+    return key(left).localeCompare(key(right));
+}
+export function collectSymbolReferences(node, projectRoot, symbolPath, includeDeclaration, detail, offset, limit, requestContext = NO_REQUEST_CONTEXT) {
+    const { declaration, references, locations } = collectTsLocations(node, projectRoot, symbolPath, includeDeclaration, detail, requestContext);
     requestContext.checkpoint();
-    allLocations.sort((left, right) => `${left.file}:${left.line}:${left.column}:${left.is_declaration ? 0 : 1}`.localeCompare(`${right.file}:${right.line}:${right.column}:${right.is_declaration ? 0 : 1}`));
+    locations.sort(compareLocations);
     const affectedFiles = [...new Set([declaration, ...references].map((item) => item.file))].sort();
-    const page = paginate(allLocations, offset, limit);
+    const page = paginate(locations, offset, limit);
     requestContext.checkpoint();
     return {
         symbol: symbolPath,
@@ -52,3 +79,65 @@ export function collectSymbolReferences(node, projectRoot, symbolPath, includeDe
         next_offset: page.next_offset,
     };
 }
+async function templateLocation(usage, detail, lineCache) {
+    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);
+    }
+    return {
+        file: usage.file,
+        line: usage.line,
+        column: usage.column,
+        kind: usage.kind,
+        is_declaration: false,
+        origin: usage.container === "inline" ? "template_inline" : "template_external",
+        ...(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 = [];
+    for (const usage of usages) {
+        requestContext.checkpoint();
+        templateItems.push(await templateLocation(usage, query.detail, lineCache));
+    }
+    const merged = [
+        ...ts.locations.map((item) => ({ ...item, origin: "compiler" })),
+        ...templateItems,
+    ].sort(compareLocations);
+    const affectedFiles = [
+        ...new Set([ts.declaration, ...ts.references, ...templateItems].map((item) => item.file)),
+    ].sort();
+    const page = paginate(merged, query.offset, query.limit);
+    requestContext.checkpoint();
+    return {
+        symbol: query.symbolPath,
+        include_declaration: query.includeDeclaration,
+        declaration_count: 1,
+        reference_count: ts.references.length,
+        affected_files: affectedFiles,
+        references: page.items,
+        offset: page.offset,
+        limit: page.limit,
+        total: page.total,
+        has_more: page.has_more,
+        next_offset: page.next_offset,
+        template_coverage: coverage,
+        template_reference_count: templateItems.length,
+    };
+}

package/dist/services/safe-file.js

@@ -0,0 +1,29 @@
+import { lstatSync, realpathSync } from "node:fs";
+import path from "node:path";
+export function assertSafeOperationFile(projectRoot, absolutePath, displayPath) {
+    const fileStat = lstatSync(absolutePath);
+    if (fileStat.isSymbolicLink()) {
+        throw new Error(`Operation target must not be a symbolic link: ${displayPath}`);
+    }
+    if (!fileStat.isFile()) {
+        throw new Error(`Operation target is not a regular file: ${displayPath}`);
+    }
+    const canonicalPath = realpathSync(absolutePath);
+    const samePath = process.platform === "win32"
+        ? canonicalPath.toLowerCase() === absolutePath.toLowerCase()
+        : canonicalPath === absolutePath;
+    if (!samePath) {
+        throw new Error(`Operation target traverses a symbolic link: ${displayPath}`);
+    }
+    if (process.platform !== "win32" && fileStat.nlink !== 1) {
+        throw new Error(`Operation target must have exactly one hard link: ${displayPath}`);
+    }
+    const uid = process.getuid?.();
+    if (uid !== undefined && fileStat.uid !== uid) {
+        throw new Error(`Operation target is not owned by the current user: ${displayPath}`);
+    }
+    const relative = path.relative(projectRoot, canonicalPath);
+    if (relative === "" || relative === ".." || relative.startsWith(`..${path.sep}`)) {
+        throw new Error(`Operation target escapes the project root: ${displayPath}`);
+    }
+}

package/dist/services/workspace.js

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { ts } from "ts-morph";
+import { listTemplateFiles } from "./angular-templates.js";
 import { collectFileFingerprints, compareFileFingerprints, hashBytes, } from "./file-fingerprints.js";
 export { hashBytes } from "./file-fingerprints.js";
 export function hashWorkspaceFiles(files) {
@@ -66,7 +67,9 @@ export function createWorkspaceSnapshot(context, options = {}) {
         .getSourceFiles()
         .map((sourceFile) => canonicalPath(sourceFile.getFilePath()));
     const configSnapshot = createConfigSnapshot(context.tsConfigFilePath);
-    const allPaths = [...new Set([...sourcePaths, ...configSnapshot.files])];
+    // Template files sit outside the TS program; listing them here keeps every snapshot consumer in agreement.
+    const templatePaths = listTemplateFiles(context).map(canonicalPath);
+    const allPaths = [...new Set([...sourcePaths, ...configSnapshot.files, ...templatePaths])];
     const fingerprintCollection = collectFileFingerprints(allPaths, options.previousFingerprints, {
         verifyContentHash: options.verifyContentHash,
     });
@@ -90,6 +93,11 @@ export function createWorkspaceSnapshot(context, options = {}) {
         }
         files.set(filePath, digest);
     }
+    for (const filePath of templatePaths) {
+        const fingerprint = fingerprints.get(filePath);
+        if (fingerprint)
+            files.set(filePath, fingerprint.content_hash);
+    }
     return {
         digest: hashWorkspaceFiles(files),
         sourceDigest: hashWorkspaceFiles(sourceFiles),

package/dist/tools/find_references.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { PaginationInputSchema, PaginationOutputSchema } from "../services/pagination.js";
 import { findDeclarationByName, getSourceFileOrThrow, withProject } from "../services/project.js";
-import { collectSymbolReferences } from "../services/references.js";
+import { collectSymbolReferencesWithTemplates } from "../services/references.js";
 import { createRequestContext } from "../services/request-context.js";
 import { createToolErrorContext, errorResult, formattedResult, ToolOutputFormatInputSchema, } from "./result.js";
 const TOOL_NAME = "ast_find_references";
@@ -25,13 +25,34 @@ const ContextReferenceSchema = z.object({
     is_declaration: z.boolean(),
     context: z.string(),
 });
-const LocationReferenceSchema = ContextReferenceSchema.omit({ context: true });
+const ContextReferenceSchemaWithOrigin = ContextReferenceSchema.extend({
+    origin: z.enum(["compiler", "template_external", "template_inline"]).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",
+    ])
+        .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(),
     ...PaginationOutputSchema,
 };
 const ReferenceOutputSchemas = {
@@ -41,13 +62,13 @@ const ReferenceOutputSchemas = {
     }),
     context: z.object({
         ...ReferenceOutputBase,
-        references: z.array(ContextReferenceSchema),
+        references: z.array(ContextReferenceSchemaWithOrigin),
     }),
 };
 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.",
+        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 tagged by origin with a template_coverage verdict; incomplete coverage does not prove absence, and template errors are not diagnosed.",
         inputSchema: AstFindReferencesInputSchema,
         annotations: {
             readOnlyHint: true,
@@ -58,18 +79,31 @@ export function registerFindReferences(server) {
     }, async ({ project_root, file_path, symbol_path, include_declaration, detail, output_format, offset, limit, }, extra) => {
         const requestContext = createRequestContext(extra.signal);
         try {
-            const structuredContent = await withProject(project_root, ({ project, projectRoot }, operationContext) => {
-                const sourceFile = getSourceFileOrThrow(project, file_path);
+            const structuredContent = await withProject(project_root, async (context, operationContext) => {
+                const sourceFile = getSourceFileOrThrow(context.project, file_path);
                 const node = findDeclarationByName(sourceFile, symbol_path);
-                const collected = collectSymbolReferences(node, projectRoot, symbol_path, include_declaration, detail, offset, limit, operationContext);
+                const collected = await collectSymbolReferencesWithTemplates(node, context, {
+                    symbolPath: symbol_path,
+                    includeDeclaration: include_declaration,
+                    detail,
+                    offset,
+                    limit,
+                }, operationContext);
                 const { references, ...metadata } = collected;
                 return {
                     ...metadata,
                     references: detail === "context"
                         ? references
-                        : references.map(({ file, line, column, kind, is_declaration }) => {
+                        : references.map(({ file, line, column, kind, is_declaration, origin }) => {
                             operationContext.checkpoint();
-                            return { file, line, column, kind, is_declaration };
+                            return {
+                                file,
+                                line,
+                                column,
+                                kind,
+                                is_declaration,
+                                ...(origin === undefined ? {} : { origin }),
+                            };
                         }),
                 };
             }, requestContext);

package/dist/tools/rename_symbol.js

@@ -21,7 +21,7 @@ const AstRenameSymbolInputSchema = z.object({
 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.",
+        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 hash-bound to the workspace snapshot; diagnostics stay TypeScript-only.",
         inputSchema: AstRenameSymbolInputSchema,
         outputSchema: PreparedOperationOutputSchema,
         annotations: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ast-mcp-server",
-  "version": "0.14.3",
+  "version": "0.15.1",
   "description": "Structural code MCP server and batch CLI for compact TypeScript/JavaScript reads and hash-bound AST edits.",
   "keywords": [
     "mcp",
@@ -109,17 +109,31 @@
     "ts-morph": "28.0.0",
     "zod": "^4.6.7"
   },
+  "peerDependencies": {
+    "@angular/compiler": ">=18.0.0 <23.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@angular/compiler": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@types/node": "^26.6.5",
+    "angular-compiler-v18": "npm:@angular/compiler@18.2.14",
+    "angular-compiler-v19": "npm:@angular/compiler@19.2.15",
+    "angular-compiler-v20": "npm:@angular/compiler@20.3.34",
+    "angular-compiler-v21": "npm:@angular/compiler@21.2.25",
+    "angular-compiler-v22": "npm:@angular/compiler@22.2.4",
     "eslint": "^10.8.0",
     "gpt-tokenizer": "4.1.0",
     "prettier": "^3.9.6",
+    "tar": "7.5.22",
     "typescript": "^5.6.0",
     "typescript-eslint": "^8.65.0",
     "vite": "^8.3.4",
     "vitest": "^5.0.5",
     "yaml": "^2.9.0"
   },
-  "gitHead": "da7adf2662572454fdd388b549eb538fbfc5a380"
+  "gitHead": "20548017b7c9266160963a0272ce8757b8f42a77"
 }