ast-mcp-server 0.6.0 → 0.7.0

package/dist/services/test-candidates.js

@@ -0,0 +1,209 @@
+import { assertExactImpactEvidence } from "./impact.js";
+export const DEFAULT_TEST_FILE_PATTERNS = Object.freeze(["**/*.test.*", "**/*.spec.*"]);
+export const DEFAULT_TEST_DIRECTORIES = Object.freeze(["test", "tests", "__tests__"]);
+export const TEST_CANDIDATE_REASONS = Object.freeze([
+    "direct_compiler_reference",
+    "transitive_compiler_reference",
+]);
+export const TEST_CANDIDATE_CONFIDENCES = Object.freeze(["exact", "high"]);
+const MAX_CONVENTION_ITEMS = 32;
+const MAX_CONVENTION_LENGTH = 256;
+function normalizeConventionValues(values, defaults, label) {
+    const selected = values ?? defaults;
+    if (!Array.isArray(selected) || selected.length > MAX_CONVENTION_ITEMS) {
+        throw new Error(`${label} must contain at most ${MAX_CONVENTION_ITEMS} entries.`);
+    }
+    const normalized = selected.map((value) => {
+        if (typeof value !== "string" || value.trim().length === 0) {
+            throw new Error(`${label} entries must be non-empty strings.`);
+        }
+        if (value.length > MAX_CONVENTION_LENGTH) {
+            throw new Error(`${label} entries must not exceed ${MAX_CONVENTION_LENGTH} characters.`);
+        }
+        return value.trim().replaceAll("\\", "/");
+    });
+    return [...new Set(normalized)];
+}
+function assertSafePattern(pattern) {
+    if (pattern.startsWith("/") ||
+        /^[A-Za-z]:\//u.test(pattern) ||
+        pattern.split("/").some((segment) => segment === "..")) {
+        throw new Error("Test file patterns must be project-relative.");
+    }
+}
+function assertSafeDirectory(directory) {
+    if (directory.startsWith("/") ||
+        /^[A-Za-z]:\//u.test(directory) ||
+        directory.split("/").some((segment) => segment === "..")) {
+        throw new Error("Test directories must be project-relative.");
+    }
+}
+function normalizeConventions(conventions = {}) {
+    if (typeof conventions !== "object" || conventions === null) {
+        throw new Error("Test candidate conventions are invalid.");
+    }
+    const patterns = normalizeConventionValues(conventions.test_file_patterns, DEFAULT_TEST_FILE_PATTERNS, "test_file_patterns");
+    const directories = normalizeConventionValues(conventions.test_directories, DEFAULT_TEST_DIRECTORIES, "test_directories");
+    patterns.forEach(assertSafePattern);
+    directories.forEach(assertSafeDirectory);
+    return { patterns, directories };
+}
+function escapeRegexCharacter(character) {
+    return /[\\^$.*+?()[\]{}|]/u.test(character) ? `\\${character}` : character;
+}
+function globToRegExp(pattern) {
+    let source = "^";
+    for (let index = 0; index < pattern.length; index += 1) {
+        const character = pattern[index];
+        if (character === "*" && pattern[index + 1] === "*") {
+            index += 1;
+            if (pattern[index + 1] === "/") {
+                index += 1;
+                source += "(?:[^/]+/)*";
+            }
+            else {
+                source += ".*";
+            }
+            continue;
+        }
+        if (character === "*") {
+            source += "[^/]*";
+            continue;
+        }
+        if (character === "?") {
+            source += "[^/]";
+            continue;
+        }
+        source += escapeRegexCharacter(character);
+    }
+    return new RegExp(`${source}$`, "u");
+}
+function matchesFilePattern(file, pattern) {
+    const matcher = globToRegExp(pattern);
+    const basename = file.slice(file.lastIndexOf("/") + 1);
+    return matcher.test(file) || matcher.test(basename);
+}
+function pathContainsDirectory(file, directory) {
+    const fileSegments = file.split("/");
+    const directorySegments = directory.split("/").filter(Boolean);
+    if (directorySegments.length === 0)
+        return false;
+    return fileSegments.some((_, index) => directorySegments.every((segment, offset) => fileSegments[index + offset] === segment));
+}
+function isProjectRelativeFile(file) {
+    return (file.length > 0 &&
+        !file.startsWith("/") &&
+        !/^[A-Za-z]:[\\/]/u.test(file) &&
+        !file.split("/").some((segment) => segment === ".." || segment.length === 0));
+}
+function isTestFile(file, conventions) {
+    if (!isProjectRelativeFile(file))
+        return false;
+    return (conventions.patterns.some((pattern) => matchesFilePattern(file, pattern)) ||
+        conventions.directories.some((directory) => pathContainsDirectory(file, directory)));
+}
+function endpointKey(endpoint) {
+    return `${endpoint.file}\u0000${endpoint.symbol_path}\u0000${endpoint.selector}`;
+}
+function edgeOrder(left, right) {
+    return (left.relationship_id.localeCompare(right.relationship_id) ||
+        left.source.file.localeCompare(right.source.file) ||
+        left.source.selector.localeCompare(right.source.selector) ||
+        left.target.file.localeCompare(right.target.file) ||
+        left.target.selector.localeCompare(right.target.selector));
+}
+function candidateReason(depth) {
+    return depth === 1 ? "direct_compiler_reference" : "transitive_compiler_reference";
+}
+function candidateConfidence(depth) {
+    return depth === 1 ? "exact" : "high";
+}
+function findPathToRoot(startKeys, rootKey, edges) {
+    const queue = [
+        ...startKeys,
+    ]
+        .sort()
+        .map((key) => ({ key, path: [] }));
+    const visited = new Set(startKeys);
+    const orderedEdges = [...edges].sort(edgeOrder);
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (current.key === rootKey && current.path.length > 0)
+            return current.path;
+        const steps = [];
+        for (const edge of orderedEdges) {
+            const sourceKey = endpointKey(edge.source);
+            const targetKey = endpointKey(edge.target);
+            if (sourceKey === current.key)
+                steps.push({ edge, nextKey: targetKey });
+            if (targetKey === current.key)
+                steps.push({ edge, nextKey: sourceKey });
+        }
+        steps.sort((left, right) => edgeOrder(left.edge, right.edge) || left.nextKey.localeCompare(right.nextKey));
+        for (const step of steps) {
+            if (visited.has(step.nextKey))
+                continue;
+            visited.add(step.nextKey);
+            queue.push({ key: step.nextKey, path: [...current.path, step.edge] });
+        }
+    }
+    return null;
+}
+export function findTestCandidates(impact, conventions = {}) {
+    assertExactImpactEvidence(impact);
+    if (typeof impact.root !== "object" ||
+        impact.root === null ||
+        !Array.isArray(impact.nodes) ||
+        !impact.nodes.every((node) => typeof node === "object" && node !== null)) {
+        throw new Error("Impact nodes are invalid.");
+    }
+    const normalized = normalizeConventions(conventions);
+    const nodesByEndpoint = new Map(impact.nodes.map((node) => [endpointKey(node.endpoint), node]));
+    const rootFile = impact.root.file;
+    const rootKey = endpointKey(impact.root);
+    const candidatesByFile = new Map();
+    for (const node of impact.nodes) {
+        const file = node.endpoint.file;
+        if (file === rootFile || !isTestFile(file, normalized))
+            continue;
+        const candidate = candidatesByFile.get(file);
+        if (candidate) {
+            candidate.depth = Math.min(candidate.depth, node.depth);
+            candidate.endpointKeys.add(endpointKey(node.endpoint));
+        }
+        else {
+            candidatesByFile.set(file, {
+                depth: node.depth,
+                endpointKeys: new Set([endpointKey(node.endpoint)]),
+            });
+        }
+    }
+    for (const edge of impact.edges) {
+        const sourceNode = nodesByEndpoint.get(endpointKey(edge.source));
+        const targetNode = nodesByEndpoint.get(endpointKey(edge.target));
+        if (!sourceNode || !targetNode) {
+            throw new Error("Impact edge does not have matching bounded nodes.");
+        }
+    }
+    return [...candidatesByFile.entries()]
+        .map(([file, candidate]) => {
+        const relationships = findPathToRoot([...candidate.endpointKeys], rootKey, impact.edges);
+        if (!relationships) {
+            throw new Error(`Test candidate "${file}" has no exact impact path to the root.`);
+        }
+        const depth = candidate.depth;
+        return {
+            file,
+            reason: candidateReason(depth),
+            confidence: candidateConfidence(depth),
+            evidence: {
+                depth,
+                direct: depth === 1,
+                compiler_authoritative: true,
+                relationship_ids: relationships.map((edge) => edge.relationship_id),
+                relationships,
+            },
+        };
+    })
+        .sort((left, right) => left.evidence.depth - right.evidence.depth || left.file.localeCompare(right.file));
+}

package/dist/services/workspace.js

@@ -2,9 +2,8 @@ import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { ts } from "ts-morph";
-export function hashBytes(content) {
-    return createHash("sha256").update(content).digest("hex");
-}
+import { collectFileFingerprints, compareFileFingerprints, hashBytes, } from "./file-fingerprints.js";
+export { hashBytes } from "./file-fingerprints.js";
 export function hashWorkspaceFiles(files) {
     const digest = createHash("sha256");
     for (const [filePath, fileHash] of [...files].sort(([left], [right]) => left.localeCompare(right))) {
@@ -62,19 +61,29 @@ export function createConfigSnapshot(rootConfigPath) {
     }
     return { digest: digest.digest("hex"), files };
 }
-export function createWorkspaceSnapshot(context) {
+export function createWorkspaceSnapshot(context, options = {}) {
     const sourcePaths = context.project
         .getSourceFiles()
         .map((sourceFile) => canonicalPath(sourceFile.getFilePath()));
     const configSnapshot = createConfigSnapshot(context.tsConfigFilePath);
+    const allPaths = [...new Set([...sourcePaths, ...configSnapshot.files])];
+    const fingerprintCollection = collectFileFingerprints(allPaths, options.previousFingerprints, {
+        verifyContentHash: options.verifyContentHash,
+    });
+    const fingerprints = fingerprintCollection.files;
     const sourceFiles = new Map();
     for (const filePath of [...new Set(sourcePaths)].sort()) {
-        const digest = hashBytes(fs.readFileSync(filePath));
-        sourceFiles.set(filePath, digest);
+        const fingerprint = fingerprints.get(filePath);
+        if (fingerprint)
+            sourceFiles.set(filePath, fingerprint.content_hash);
     }
     const files = new Map(sourceFiles);
     for (const filePath of configSnapshot.files) {
-        const digest = hashBytes(fs.readFileSync(filePath));
+        const fingerprint = fingerprints.get(filePath);
+        if (!fingerprint) {
+            throw new Error(`Configuration file disappeared while creating a workspace snapshot: ${filePath}`);
+        }
+        const digest = fingerprint.content_hash;
         const previous = files.get(filePath);
         if (previous && previous !== digest) {
             throw new Error(`Workspace identity collision for ${filePath}.`);
@@ -88,5 +97,7 @@ export function createWorkspaceSnapshot(context) {
         sourceFileCount: sourceFiles.size,
         fileCount: files.size,
         files,
+        fingerprints,
+        fingerprintChanges: compareFileFingerprints(options.previousFingerprints ?? new Map(), fingerprints),
     };
 }

package/dist/tools/apply_operation.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { applyOperation } from "../services/operations.js";
-import { errorResult, structuredResult } from "./result.js";
+import { createRequestContext } from "../services/request-context.js";
+import { createToolErrorContext, errorResult, structuredResult } from "./result.js";
 const AstApplyOperationInputSchema = z.object({
     operation_id: z.string().uuid().describe("Identifier returned by a prepare operation."),
     plan_hash: z.string().length(64).describe("Plan hash returned by the same prepare operation."),
@@ -25,12 +26,15 @@ export function registerApplyOperation(server) {
             idempotentHint: true,
             openWorldHint: false,
         },
-    }, async ({ operation_id, plan_hash }) => {
+    }, async ({ operation_id, plan_hash }, extra) => {
+        const requestContext = createRequestContext(extra.signal);
         try {
-            return structuredResult({ ...(await applyOperation(operation_id, plan_hash)) });
+            return structuredResult({
+                ...(await applyOperation(operation_id, plan_hash, requestContext)),
+            });
         }
         catch (error) {
-            return errorResult(error);
+            return errorResult(error, createToolErrorContext("ast_apply_operation"));
         }
     });
 }

package/dist/tools/explore.js

@@ -2,8 +2,9 @@ import { z } from "zod";
 import { buildExploreContext, EXPLORE_DEFAULT_LIMIT, EXPLORE_DEFAULT_MAX_BYTES, EXPLORE_DEFAULT_REFERENCE_LIMIT, EXPLORE_MAX_BYTES, } from "../services/context-builder.js";
 import { createPaginationInputSchema } from "../services/pagination.js";
 import { withProject } from "../services/project.js";
+import { createRequestContext } from "../services/request-context.js";
 import { FRESHNESS_CAUSES, SNAPSHOT_STATES, TRUNCATION_REASONS, } from "../services/read-contracts.js";
-import { errorResult, structuredResult } from "./result.js";
+import { createToolErrorContext, errorResult, structuredResult } from "./result.js";
 const ExploreDetailSchema = z.enum(["selectors", "summary", "context", "full"]).default("summary");
 const ReferenceDetailSchema = z.enum(["locations", "context"]).default("locations");
 const ExploreInputSchema = z
@@ -139,7 +140,7 @@ const ExploreOutputSchema = z.object({
 export function registerExplore(server) {
     server.registerTool("ast_explore", {
         title: "Explore project context",
-        description: "Composes bounded structural search, exact selectors, source evidence and compiler references without weakening the primitive AST tools.",
+        description: "Composes bounded structural search, exact selectors, source evidence and compiler references without weakening the primitive AST tools. Returns bounded session freshness metadata for fresh, pending, stale, rebuilding or degraded state.",
         inputSchema: ExploreInputSchema,
         outputSchema: ExploreOutputSchema,
         annotations: {
@@ -148,9 +149,10 @@ export function registerExplore(server) {
             idempotentHint: true,
             openWorldHint: false,
         },
-    }, async ({ project_root, query, file_path, symbol_path, kinds, file_filter, detail, include_source, include_references, reference_detail, reference_limit, offset, limit, max_bytes, }) => {
+    }, async ({ project_root, query, file_path, symbol_path, kinds, file_filter, detail, include_source, include_references, reference_detail, reference_limit, offset, limit, max_bytes, }, extra) => {
+        const requestContext = createRequestContext(extra.signal);
         try {
-            const output = await withProject(project_root, (context) => buildExploreContext(context, {
+            const output = await withProject(project_root, (context, operationContext) => buildExploreContext(context, {
                 query,
                 filePath: file_path,
                 symbolPath: symbol_path,
@@ -164,11 +166,11 @@ export function registerExplore(server) {
                 limit,
                 referenceLimit: reference_limit,
                 maxBytes: max_bytes,
-            }));
+            }, operationContext), requestContext);
             return structuredResult(ExploreOutputSchema.parse(output));
         }
         catch (error) {
-            return errorResult(error);
+            return errorResult(error, createToolErrorContext("ast_explore", project_root));
         }
     });
 }

package/dist/tools/find_references.js

@@ -2,7 +2,8 @@ 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 { errorResult, formattedResult, ToolOutputFormatInputSchema } from "./result.js";
+import { createRequestContext } from "../services/request-context.js";
+import { createToolErrorContext, errorResult, formattedResult, ToolOutputFormatInputSchema, } from "./result.js";
 const ReferenceDetailSchema = z.enum(["locations", "context"]).default("locations");
 const AstFindReferencesInputSchema = z.object({
     project_root: z
@@ -53,31 +54,29 @@ export function registerFindReferences(server) {
             idempotentHint: true,
             openWorldHint: false,
         },
-    }, async ({ project_root, file_path, symbol_path, include_declaration, detail, output_format, offset, limit, }) => {
+    }, 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 }) => {
+            const structuredContent = await withProject(project_root, ({ project, projectRoot }, operationContext) => {
                 const sourceFile = getSourceFileOrThrow(project, file_path);
                 const node = findDeclarationByName(sourceFile, symbol_path);
-                const collected = collectSymbolReferences(node, projectRoot, symbol_path, include_declaration, detail, offset, limit);
+                const collected = collectSymbolReferences(node, projectRoot, symbol_path, include_declaration, detail, offset, limit, operationContext);
                 const { references, ...metadata } = collected;
                 return {
                     ...metadata,
                     references: detail === "context"
                         ? references
-                        : references.map(({ file, line, column, kind, is_declaration }) => ({
-                            file,
-                            line,
-                            column,
-                            kind,
-                            is_declaration,
-                        })),
+                        : references.map(({ file, line, column, kind, is_declaration }) => {
+                            operationContext.checkpoint();
+                            return { file, line, column, kind, is_declaration };
+                        }),
                 };
-            });
+            }, requestContext);
             const outputSchema = ReferenceOutputSchemas[detail];
             return formattedResult(outputSchema, structuredContent, output_format);
         }
         catch (error) {
-            return errorResult(error);
+            return errorResult(error, createToolErrorContext("ast_find_references", project_root));
         }
     });
 }

package/dist/tools/get_diagnostics.js

@@ -2,7 +2,8 @@ import { z } from "zod";
 import { normalizeDiagnostic } from "../services/diagnostics.js";
 import { PaginationInputSchema, PaginationOutputSchema, paginate } from "../services/pagination.js";
 import { getSourceFileOrThrow, withProject } from "../services/project.js";
-import { errorResult, formattedResult, ToolOutputFormatInputSchema } from "./result.js";
+import { createRequestContext } from "../services/request-context.js";
+import { createToolErrorContext, errorResult, formattedResult, ToolOutputFormatInputSchema, } from "./result.js";
 const DiagnosticSchema = z.object({
     code: z.number().int(),
     category: z.string(),
@@ -40,31 +41,33 @@ export function registerGetDiagnostics(server) {
             idempotentHint: true,
             openWorldHint: false,
         },
-    }, async ({ project_root, file_path, output_format, offset, limit }) => {
+    }, async ({ project_root, file_path, output_format, offset, limit }, extra) => {
+        const requestContext = createRequestContext(extra.signal);
         try {
-            const structuredContent = await withProject(project_root, ({ project, projectRoot }) => {
+            const structuredContent = await withProject(project_root, ({ project, projectRoot }, operationContext) => {
                 const startedAt = performance.now();
                 const diagnostics = file_path
                     ? getSourceFileOrThrow(project, file_path).getPreEmitDiagnostics()
                     : [...project.getConfigFileParsingDiagnostics(), ...project.getPreEmitDiagnostics()];
                 const normalized = diagnostics
-                    .map((diagnostic) => normalizeDiagnostic(diagnostic, projectRoot))
+                    .map((diagnostic) => normalizeDiagnostic(diagnostic, projectRoot, operationContext))
                     .sort((left, right) => `${left.file ?? ""}:${left.line ?? 0}:${left.column ?? 0}:${left.code}`.localeCompare(`${right.file ?? ""}:${right.line ?? 0}:${right.column ?? 0}:${right.code}`));
                 const page = paginate(normalized, offset, limit);
                 const { items, ...metadata } = page;
                 return {
                     diagnostics: items,
-                    error_count: normalized.filter((diagnostic) => diagnostic.category === "Error").length,
+                    error_count: normalized.filter((diagnostic) => diagnostic.category === "Error")
+                        .length,
                     warning_count: normalized.filter((diagnostic) => diagnostic.category === "Warning")
                         .length,
                     duration_ms: performance.now() - startedAt,
                     ...metadata,
                 };
-            });
+            }, requestContext);
             return formattedResult(AstGetDiagnosticsOutputSchema, structuredContent, output_format);
         }
         catch (error) {
-            return errorResult(error);
+            return errorResult(error, createToolErrorContext("ast_get_diagnostics", project_root));
         }
     });
 }

package/dist/tools/get_file.js

@@ -2,7 +2,9 @@ import { z } from "zod";
 import { DEFAULT_FILE_LINE_LIMIT, MAX_FILE_LINE_LIMIT, readFileSnapshot, } from "../services/file-snapshot.js";
 import { buildFileOutline } from "../services/outline.js";
 import { getSourceFileOrThrow, withProject } from "../services/project.js";
-import { errorResult, structuredResult } from "./result.js";
+import { createRequestContext } from "../services/request-context.js";
+import { FRESHNESS_CAUSES, SNAPSHOT_STATES } from "../services/read-contracts.js";
+import { createToolErrorContext, errorResult, structuredResult } from "./result.js";
 const AstGetFileInputSchema = z.object({
     project_root: z
         .string()
@@ -44,6 +46,11 @@ const FileSnapshotBaseSchema = {
     file: z.string(),
     file_hash: z.string().regex(/^[0-9a-f]{64}$/),
     snapshot_state: z.enum(["fresh", "stale"]),
+    freshness: z.object({
+        state: z.enum(SNAPSHOT_STATES),
+        causes: z.array(z.enum(FRESHNESS_CAUSES)),
+        checked_at: z.string().nullable(),
+    }),
 };
 const AstGetFileOutputSchema = z.object({
     mode: z.enum(["source", "symbols_only"]),
@@ -55,7 +62,7 @@ const AstGetFileOutputSchema = z.object({
 export function registerGetFile(server) {
     server.registerTool("ast_get_file", {
         title: "Get bounded source file",
-        description: "Returns exact bounded source lines for one TypeScript/JavaScript file, or body-free symbols when symbols_only is true. Read-only; freshness is reported separately from compiler diagnostics.",
+        description: "Returns exact bounded source lines for one TypeScript/JavaScript file, or body-free symbols when symbols_only is true. Read-only; file snapshot freshness and project freshness are reported separately from compiler diagnostics.",
         inputSchema: AstGetFileInputSchema,
         outputSchema: AstGetFileOutputSchema,
         annotations: {
@@ -64,17 +71,21 @@ export function registerGetFile(server) {
             idempotentHint: true,
             openWorldHint: false,
         },
-    }, async ({ project_root, file_path, offset, limit, symbols_only }) => {
+    }, async ({ project_root, file_path, offset, limit, symbols_only }, extra) => {
+        const requestContext = createRequestContext(extra.signal);
         try {
-            const structuredContent = await withProject(project_root, async ({ project, projectRoot }) => {
-                const snapshot = await readFileSnapshot(project, projectRoot, file_path, {
-                    offset,
-                    limit,
-                });
+            const structuredContent = await withProject(project_root, async ({ project, projectRoot, status }, operationContext) => {
+                const snapshot = await readFileSnapshot(project, projectRoot, file_path, { offset, limit }, operationContext);
+                const freshness = {
+                    state: status.state,
+                    causes: status.causes,
+                    checked_at: status.lastSuccessfulSyncAt,
+                };
                 if (!symbols_only) {
                     return {
                         mode: "source",
                         ...snapshot,
+                        freshness,
                     };
                 }
                 const sourceFile = getSourceFileOrThrow(project, file_path);
@@ -83,13 +94,14 @@ export function registerGetFile(server) {
                     file: snapshot.file,
                     file_hash: snapshot.file_hash,
                     snapshot_state: snapshot.snapshot_state,
-                    symbols: buildFileOutline(sourceFile).symbols,
+                    freshness,
+                    symbols: buildFileOutline(sourceFile, operationContext).symbols,
                 };
-            });
+            }, requestContext);
             return structuredResult(structuredContent);
         }
         catch (error) {
-            return errorResult(error);
+            return errorResult(error, createToolErrorContext("ast_get_file", project_root));
         }
     });
 }

package/dist/tools/get_impact.js

@@ -0,0 +1,134 @@
+import { z } from "zod";
+import { DEFAULT_IMPACT_MAX_DEPTH, DEFAULT_IMPACT_MAX_EDGES, DEFAULT_IMPACT_MAX_NODES, IMPACT_DIRECTIONS, MAX_IMPACT_DEPTH, MAX_IMPACT_EDGES, MAX_IMPACT_NODES, resolveImpactRoot, traverseCompilerImpact, } from "../services/impact.js";
+import { FRESHNESS_CAUSES, SNAPSHOT_STATES, TRUNCATION_REASONS, } from "../services/read-contracts.js";
+import { withProject } from "../services/project.js";
+import { createRequestContext } from "../services/request-context.js";
+import { RELATIONSHIP_CONFIDENCES, RELATIONSHIP_EDGE_KINDS, RELATIONSHIP_PROVENANCES, RELATIONSHIP_RESOLUTIONS, } from "../services/relationships.js";
+import { createToolErrorContext, errorResult, formattedResult, ToolOutputFormatInputSchema, } from "./result.js";
+const AstGetImpactInputSchema = z.object({
+    project_root: z
+        .string()
+        .describe("Absolute project directory containing tsconfig.json, or the config path."),
+    file_path: z.string().describe("Project-relative file containing the exact impact root."),
+    symbol_path: z.string().describe("Exact symbol path returned by an outline or symbol search."),
+    direction: z
+        .enum(IMPACT_DIRECTIONS)
+        .default("both")
+        .describe("Traversal direction relative to the root symbol."),
+    max_depth: z
+        .number()
+        .int()
+        .min(0)
+        .max(MAX_IMPACT_DEPTH)
+        .default(DEFAULT_IMPACT_MAX_DEPTH)
+        .describe("Maximum relationship depth, including zero for the root only."),
+    max_nodes: z
+        .number()
+        .int()
+        .min(1)
+        .max(MAX_IMPACT_NODES)
+        .default(DEFAULT_IMPACT_MAX_NODES)
+        .describe("Maximum returned impact nodes, including the root."),
+    max_edges: z
+        .number()
+        .int()
+        .min(1)
+        .max(MAX_IMPACT_EDGES)
+        .default(DEFAULT_IMPACT_MAX_EDGES)
+        .describe("Maximum returned relationship edges."),
+    relationship_kinds: z
+        .array(z.enum(RELATIONSHIP_EDGE_KINDS))
+        .optional()
+        .describe("Optional relationship kinds to traverse; defaults to all normalized kinds."),
+    ...ToolOutputFormatInputSchema,
+});
+const SourceRangeSchema = z.object({
+    start_line: z.number().int().positive(),
+    start_column: z.number().int().positive().optional(),
+    end_line: z.number().int().positive().optional(),
+    end_column: z.number().int().positive().optional(),
+});
+const RelationshipEndpointSchema = z.object({
+    file: z.string(),
+    symbol_path: z.string(),
+    selector: z.string(),
+    range: SourceRangeSchema.optional(),
+});
+const FreshnessSchema = z.object({
+    state: z.enum(SNAPSHOT_STATES),
+    causes: z.array(z.enum(FRESHNESS_CAUSES)),
+    checked_at: z.string().nullable(),
+});
+const RelationshipEdgeSchema = z.object({
+    relationship_id: z.string(),
+    source: RelationshipEndpointSchema,
+    target: RelationshipEndpointSchema,
+    kind: z.enum(RELATIONSHIP_EDGE_KINDS),
+    provenance: z.enum(RELATIONSHIP_PROVENANCES),
+    confidence: z.enum(RELATIONSHIP_CONFIDENCES),
+    resolution: z.enum(RELATIONSHIP_RESOLUTIONS),
+    compiler_authoritative: z.boolean(),
+    freshness: FreshnessSchema,
+});
+const ImpactOutputSchema = z.object({
+    root: RelationshipEndpointSchema,
+    direction: z.enum(IMPACT_DIRECTIONS),
+    relationship_kinds: z.array(z.enum(RELATIONSHIP_EDGE_KINDS)),
+    nodes: z.array(z.object({
+        endpoint: RelationshipEndpointSchema,
+        depth: z.number().int().min(0),
+        direct: z.boolean(),
+    })),
+    edges: z.array(RelationshipEdgeSchema),
+    visited_nodes: z.number().int().min(0),
+    visited_edges: z.number().int().min(0),
+    max_depth_reached: z.number().int().min(0),
+    max_depth: z.number().int().min(0),
+    max_nodes: z.number().int().positive(),
+    max_edges: z.number().int().positive(),
+    incomplete: z.boolean(),
+    truncation: z.object({
+        truncated: z.boolean(),
+        reason: z.enum(TRUNCATION_REASONS).nullable(),
+    }),
+    truncation_reasons: z.array(z.enum(TRUNCATION_REASONS)),
+    freshness: FreshnessSchema,
+});
+export function registerGetImpact(server) {
+    server.registerTool("ast_get_impact", {
+        title: "Get bounded compiler-backed impact",
+        description: "Traverses exact compiler-backed relationships around a symbol with explicit direction, depth, node and edge budgets. Returns bounded session freshness metadata and fails closed when exact relationships are not fresh. Read-only evidence only; it never prepares or applies mutations.",
+        inputSchema: AstGetImpactInputSchema,
+        outputSchema: ImpactOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async ({ project_root, file_path, symbol_path, direction, max_depth, max_nodes, max_edges, relationship_kinds, output_format, }, extra) => {
+        const requestContext = createRequestContext(extra.signal);
+        try {
+            const structuredContent = await withProject(project_root, (context, operationContext) => {
+                if (context.status.state !== "fresh") {
+                    throw new Error("Compiler-backed impact evidence is not fresh. Retry the read.");
+                }
+                const freshness = {
+                    state: context.status.state,
+                    causes: context.status.causes,
+                    checked_at: context.status.lastSuccessfulSyncAt,
+                };
+                const root = resolveImpactRoot(context.project, context.projectRoot, { file_path, symbol_path }, operationContext);
+                const impact = traverseCompilerImpact(context.project, context.projectRoot, root, freshness, { direction, max_depth, max_nodes, max_edges, relationship_kinds }, operationContext);
+                return {
+                    ...impact,
+                    freshness,
+                };
+            }, requestContext);
+            return formattedResult(ImpactOutputSchema, structuredContent, output_format);
+        }
+        catch (error) {
+            return errorResult(error, createToolErrorContext("ast_get_impact", project_root));
+        }
+    });
+}