ast-mcp-server 0.9.1 → 0.10.0

package/dist/services/public-errors.js

@@ -13,6 +13,7 @@ export const PUBLIC_ERROR_CODES = Object.freeze([
     "NOT_FOUND",
     "AMBIGUOUS_TARGET",
     "STALE_WORKSPACE",
+    "INCOMPLETE_EVIDENCE",
     "MUTATION_BLOCKED",
     "CONFLICT",
     "INTERNAL_ERROR",
@@ -35,6 +36,7 @@ const FIXED_PUBLIC_MESSAGES = Object.freeze({
     NOT_FOUND: "The requested target was not found.",
     AMBIGUOUS_TARGET: "The requested target is ambiguous.",
     STALE_WORKSPACE: "The workspace changed. Retry the operation.",
+    INCOMPLETE_EVIDENCE: "The required compiler evidence is incomplete.",
     MUTATION_BLOCKED: "The mutation is blocked.",
     CONFLICT: "The operation conflicts with current state.",
     INTERNAL_ERROR: INTERNAL_ERROR_MESSAGE,
@@ -70,6 +72,10 @@ const LEGACY_MESSAGE_RULES = Object.freeze([
         code: "STALE_WORKSPACE",
         pattern: /^(?:Workspace changed\b|Project (?:configuration|source) changed during synchronization\.)/,
     },
+    {
+        code: "INCOMPLETE_EVIDENCE",
+        pattern: /^Compiler-backed impact evidence is incomplete\.$/,
+    },
     {
         code: "CONFLICT",
         pattern: /^(?:Conflict:|Plan hash mismatch\b|Persisted plan integrity mismatch\b|Operation id collision\b|Applied receipt conflict\b|Postimage recovery conflict\b|Operation target already exists\b|Another AST apply holds\b)/,
@@ -80,7 +86,7 @@ const LEGACY_MESSAGE_RULES = Object.freeze([
     },
     {
         code: "INVALID_INPUT",
-        pattern: /^(?:File path traversal is not allowed\.|Windows absolute paths are not valid on this host\.|Source file resolves outside the configured project root\.|Unsupported (?:UTF-16|non-UTF-8) source encoding\b|Persisted (?:operation|applied operation|prepared operation|project_root|original hash|updated hash|affected_files|diagnostic error delta|blocked status)\b|Scaffold file_path must\b|.{0,1024} is not a valid TypeScript identifier\.|.{0,1024} must (?:be|not)\b|.{0,1024} requires\b|.{0,1024} exceeds \d+ characters\.)/,
+        pattern: /^(?:File path traversal is not allowed\.|Windows absolute paths are not valid on this host\.|Source file resolves outside the configured project root\.|Unsupported (?:UTF-16|non-UTF-8) source encoding\b|Persisted (?:operation|applied operation|prepared operation|project_root|original hash|updated hash|affected_files|diagnostic error delta|blocked status)\b|Scaffold file_path must\b|.{0,1024} is not a valid TypeScript identifier\.|.{0,1024} must (?:be|not|contain)\b|.{0,1024} requires\b|.{0,1024} exceeds \d+ characters\.)/,
     },
 ]);
 export class PublicOperationalError extends Error {

package/dist/services/relationships.js

@@ -1159,6 +1159,110 @@ export function createCompilerRelationshipResolver(project, projectRoot, freshne
         },
     };
 }
+function callLikeExpression(node) {
+    if (Node.isCallExpression(node) || Node.isNewExpression(node))
+        return node.getExpression();
+    if (Node.isTaggedTemplateExpression(node))
+        return node.getTag();
+    return undefined;
+}
+function unwrapInvocationExpression(node) {
+    let current = node;
+    while (Node.isParenthesizedExpression(current) ||
+        Node.isNonNullExpression(current) ||
+        Node.isAsExpression(current) ||
+        Node.isTypeAssertion(current) ||
+        Node.isSatisfiesExpression(current)) {
+        current = current.getExpression();
+    }
+    return current;
+}
+function locatedCallTarget(projectRoot, declaration) {
+    if (Node.isParameterDeclaration(declaration) || Node.isMethodSignature(declaration))
+        return undefined;
+    const sourceFile = declaration.getSourceFile();
+    if (!isProjectScopedFile(projectRoot, sourceFile.getFilePath()))
+        return undefined;
+    const targetNode = Node.isConstructorDeclaration(declaration)
+        ? declaration.getFirstAncestorByKind(SyntaxKind.ClassDeclaration)
+        : declaration;
+    if (!targetNode)
+        return undefined;
+    return (collectSymbols(sourceFile).find((symbol) => symbol.node === targetNode) ??
+        containingSymbol(sourceFile, targetNode));
+}
+export function collectCompilerCallRelationships(project, projectRoot, freshness, options = {}, requestContext = NO_REQUEST_CONTEXT) {
+    const maxEdges = options.max_edges ?? 5_000;
+    const maxWorkItems = options.max_work_items ?? 100_000;
+    if (!Number.isSafeInteger(maxEdges) || maxEdges < 1) {
+        throw new Error("Compiler call max_edges must be a positive safe integer.");
+    }
+    if (!Number.isSafeInteger(maxWorkItems) || maxWorkItems < 1) {
+        throw new Error("Compiler call max_work_items must be a positive safe integer.");
+    }
+    const normalizedFreshness = normalizeFreshness(freshness);
+    const checker = project.getTypeChecker();
+    const edges = new Map();
+    let workItems = 0;
+    let workLimitReached = false;
+    for (const sourceFile of project
+        .getSourceFiles()
+        .sort((left, right) => left.getFilePath().localeCompare(right.getFilePath()))) {
+        sourceFile.forEachDescendant((node, traversal) => {
+            requestContext.checkpoint();
+            if (++workItems > maxWorkItems) {
+                workLimitReached = true;
+                traversal.stop();
+                return;
+            }
+            const expression = callLikeExpression(node);
+            if (!expression)
+                return;
+            const invoked = unwrapInvocationExpression(expression);
+            const caller = containingSymbol(sourceFile, node);
+            if (!caller)
+                return;
+            const signature = checker.getResolvedSignature(node);
+            const implicitConstructSignatures = Node.isNewExpression(node)
+                ? invoked.getType().getConstructSignatures()
+                : [];
+            if (!signature && implicitConstructSignatures.length !== 1)
+                return;
+            const signatureDeclaration = signature?.getDeclaration();
+            const declarations = declarationsForSymbol(invoked.getSymbol());
+            const targets = new Map();
+            for (const declaration of declarations.length > 0
+                ? declarations
+                : signatureDeclaration
+                    ? [signatureDeclaration]
+                    : []) {
+                const target = locatedCallTarget(projectRoot, declaration);
+                if (target)
+                    targets.set(symbolEndpoint(target, projectRoot).selector, target);
+            }
+            if (targets.size !== 1)
+                return;
+            const target = [...targets.values()][0];
+            const edge = createRelationshipEdge({
+                source: symbolEndpoint(caller, projectRoot),
+                target: symbolEndpoint(target, projectRoot),
+                kind: "call",
+                provenance: "compiler",
+                confidence: "exact",
+                resolution: "resolved",
+                freshness: normalizedFreshness,
+            });
+            edges.set(edge.relationship_id, edge);
+        });
+        if (workLimitReached)
+            break;
+    }
+    const ordered = [...edges.values()].sort((left, right) => left.relationship_id.localeCompare(right.relationship_id));
+    return Object.freeze({
+        edges: Object.freeze(ordered.slice(0, maxEdges)),
+        incomplete: workLimitReached || ordered.length > maxEdges,
+    });
+}
 export function collectCompilerRelationships(project, projectRoot, freshness, requestContext = NO_REQUEST_CONTEXT) {
     requestContext.checkpoint();
     const sourceFiles = project

package/dist/services/test-candidates.js

@@ -4,21 +4,22 @@ export const DEFAULT_TEST_DIRECTORIES = Object.freeze(["test", "tests", "__tests
 export const TEST_CANDIDATE_REASONS = Object.freeze([
     "direct_compiler_reference",
     "transitive_compiler_reference",
+    "convention_match",
 ]);
 export const TEST_CANDIDATE_CONFIDENCES = Object.freeze(["exact", "high"]);
-const MAX_CONVENTION_ITEMS = 32;
-const MAX_CONVENTION_LENGTH = 256;
+export const MAX_TEST_CANDIDATE_CONVENTION_ITEMS = 32;
+export const MAX_TEST_CANDIDATE_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.`);
+    if (!Array.isArray(selected) || selected.length > MAX_TEST_CANDIDATE_CONVENTION_ITEMS) {
+        throw new Error(`${label} must contain at most ${MAX_TEST_CANDIDATE_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.`);
+        if (value.length > MAX_TEST_CANDIDATE_CONVENTION_LENGTH) {
+            throw new Error(`${label} entries must not exceed ${MAX_TEST_CANDIDATE_CONVENTION_LENGTH} characters.`);
         }
         return value.trim().replaceAll("\\", "/");
     });
@@ -112,7 +113,13 @@ function edgeOrder(left, right) {
         left.target.file.localeCompare(right.target.file) ||
         left.target.selector.localeCompare(right.target.selector));
 }
-function candidateReason(depth) {
+function candidateReason(file, depth) {
+    if (!isTestFile(file, {
+        patterns: DEFAULT_TEST_FILE_PATTERNS,
+        directories: DEFAULT_TEST_DIRECTORIES,
+    })) {
+        return "convention_match";
+    }
     return depth === 1 ? "direct_compiler_reference" : "transitive_compiler_reference";
 }
 function candidateConfidence(depth) {
@@ -194,7 +201,7 @@ export function findTestCandidates(impact, conventions = {}) {
         const depth = candidate.depth;
         return {
             file,
-            reason: candidateReason(depth),
+            reason: candidateReason(file, depth),
             confidence: candidateConfidence(depth),
             evidence: {
                 depth,

package/dist/tools/explore.js

@@ -1,12 +1,21 @@
 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 { buildExploreContext, EXPLORE_DEFAULT_LIMIT, EXPLORE_DEFAULT_MAX_BYTES, EXPLORE_DEFAULT_OMISSION_DETAIL_LIMIT, EXPLORE_DEFAULT_REFERENCE_LIMIT, EXPLORE_MAX_BYTES, EXPLORE_MAX_OMISSION_DETAIL_LIMIT, } from "../services/context-builder.js";
+import { DEFAULT_IMPACT_MAX_DEPTH, DEFAULT_IMPACT_MAX_EDGES, DEFAULT_IMPACT_MAX_NODES, MAX_IMPACT_DEPTH, MAX_IMPACT_EDGES, MAX_IMPACT_NODES, } from "../services/impact.js";
+import { EXPLORE_OMISSION_REASONS } from "../services/explore-presentation.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 { createToolErrorContext, errorResult, structuredResult } from "./result.js";
+import { RelationshipEndpointSchema } from "./relationship-schema.js";
 const ExploreDetailSchema = z.enum(["selectors", "summary", "context", "full"]).default("summary");
 const ReferenceDetailSchema = z.enum(["locations", "context"]).default("locations");
+const CallSpinesInputSchema = z.object({
+    direction: z.enum(["incoming", "outgoing"]).default("outgoing"),
+    max_depth: z.number().int().min(0).max(MAX_IMPACT_DEPTH).default(DEFAULT_IMPACT_MAX_DEPTH),
+    max_nodes: z.number().int().min(1).max(MAX_IMPACT_NODES).default(DEFAULT_IMPACT_MAX_NODES),
+    max_edges: z.number().int().min(1).max(MAX_IMPACT_EDGES).default(DEFAULT_IMPACT_MAX_EDGES),
+});
 const ExploreInputSchema = z
     .object({
     project_root: z
@@ -46,6 +55,14 @@ const ExploreInputSchema = z
         .max(EXPLORE_MAX_BYTES)
         .default(EXPLORE_DEFAULT_MAX_BYTES)
         .describe("Maximum serialized logical result size in UTF-8 bytes."),
+    call_spines: CallSpinesInputSchema.optional().describe("Optional compiler-authoritative static call paths for an exact file_path and symbol_path."),
+    omission_detail_limit: z
+        .number()
+        .int()
+        .min(0)
+        .max(EXPLORE_MAX_OMISSION_DETAIL_LIMIT)
+        .default(EXPLORE_DEFAULT_OMISSION_DETAIL_LIMIT)
+        .describe("Maximum deterministic omission detail records; exact counts are always retained."),
 })
     .refine((input) => Boolean(input.query || input.file_path), {
     message: "Provide query, file_path, or both file_path and symbol_path.",
@@ -54,6 +71,10 @@ const ExploreInputSchema = z
     .refine((input) => !input.symbol_path || Boolean(input.file_path), {
     message: "symbol_path requires file_path so the exact declaration can be resolved.",
     path: ["symbol_path"],
+})
+    .refine((input) => !input.call_spines || Boolean(input.file_path && input.symbol_path), {
+    message: "call_spines requires exact file_path and symbol_path inputs.",
+    path: ["call_spines"],
 });
 const ExploreSymbolSchema = z.object({
     file: z.string(),
@@ -97,6 +118,35 @@ const ExploreEvidenceSchema = z.object({
     })
         .optional(),
 });
+const ExploreOmissionSchema = z.object({
+    subject: z.string(),
+    category: z.enum(["budget", "incomplete", "untrusted"]),
+    component: z.enum(["signature", "source", "references", "call_spine"]),
+    reason: z.enum(EXPLORE_OMISSION_REASONS),
+});
+const CallSpinesOutputSchema = z.object({
+    root: RelationshipEndpointSchema,
+    direction: z.enum(["incoming", "outgoing"]),
+    paths: z.array(z.object({
+        endpoint: RelationshipEndpointSchema,
+        endpoints: z.array(RelationshipEndpointSchema),
+        relationship_ids: z.array(z.string()),
+    })),
+    visited: z.object({
+        nodes: z.number().int().min(0),
+        edges: z.number().int().min(0),
+        max_depth: z.number().int().min(0),
+    }),
+    budget: z.object({
+        max_depth: z.number().int().min(0),
+        max_nodes: z.number().int().positive(),
+        max_edges: z.number().int().positive(),
+    }),
+    incomplete: z.boolean(),
+    truncation_reasons: z.array(z.enum(["depth_limit", "node_limit", "edge_limit"])),
+    authority_state: z.enum(["authoritative", "incomplete", "untrusted"]),
+    empty_proven: z.boolean(),
+});
 const ExploreOutputSchema = z.object({
     route: z.enum(["query", "file", "symbol"]),
     query: z.string().nullable(),
@@ -110,6 +160,17 @@ const ExploreOutputSchema = z.object({
     total: z.number().int().min(0),
     has_more: z.boolean(),
     next_offset: z.number().int().min(0).nullable(),
+    omissions: z.object({
+        counts: z.array(z.object({
+            category: z.enum(["budget", "incomplete", "untrusted"]),
+            component: z.enum(["signature", "source", "references", "call_spine"]),
+            count: z.number().int().positive(),
+        })),
+        details: z.array(ExploreOmissionSchema),
+        total: z.number().int().min(0),
+        has_more: z.boolean(),
+    }),
+    call_spines: CallSpinesOutputSchema.optional(),
     freshness: z.object({
         state: z.enum(SNAPSHOT_STATES),
         causes: z.array(z.enum(FRESHNESS_CAUSES)),
@@ -119,6 +180,7 @@ const ExploreOutputSchema = z.object({
         complete: z.boolean(),
         symbols_complete: z.boolean(),
         evidence_complete: z.boolean(),
+        spines_complete: z.boolean().optional(),
         unresolved: z.array(z.object({
             selector: z.string(),
             reason: z.enum(["source_unresolved", "references_unresolved"]),
@@ -149,7 +211,7 @@ 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, }, extra) => {
+    }, async ({ project_root, query, file_path, symbol_path, kinds, file_filter, detail, include_source, include_references, reference_detail, reference_limit, offset, limit, max_bytes, call_spines, omission_detail_limit, }, extra) => {
         const requestContext = createRequestContext(extra.signal);
         try {
             const output = await withProject(project_root, (context, operationContext) => buildExploreContext(context, {
@@ -166,6 +228,15 @@ export function registerExplore(server) {
                 limit,
                 referenceLimit: reference_limit,
                 maxBytes: max_bytes,
+                callSpines: call_spines
+                    ? {
+                        direction: call_spines.direction,
+                        maxDepth: call_spines.max_depth,
+                        maxNodes: call_spines.max_nodes,
+                        maxEdges: call_spines.max_edges,
+                    }
+                    : undefined,
+                omissionDetailLimit: omission_detail_limit,
             }, operationContext), requestContext);
             return structuredResult(ExploreOutputSchema.parse(output));
         }

package/dist/tools/find_test_candidates.js

@@ -0,0 +1,124 @@
+import { z } from "zod";
+import { DEFAULT_IMPACT_MAX_DEPTH, DEFAULT_IMPACT_MAX_EDGES, DEFAULT_IMPACT_MAX_NODES, MAX_IMPACT_DEPTH, MAX_IMPACT_EDGES, MAX_IMPACT_NODES, resolveImpactRoot, traverseCompilerImpact, } from "../services/impact.js";
+import { paginate, PaginationInputSchema, PaginationOutputSchema } from "../services/pagination.js";
+import { withProject } from "../services/project.js";
+import { PublicOperationalError } from "../services/public-errors.js";
+import { createRequestContext } from "../services/request-context.js";
+import { findTestCandidates, MAX_TEST_CANDIDATE_CONVENTION_ITEMS, MAX_TEST_CANDIDATE_CONVENTION_LENGTH, TEST_CANDIDATE_CONFIDENCES, TEST_CANDIDATE_REASONS, } from "../services/test-candidates.js";
+import { FreshnessSchema, RelationshipEdgeSchema, RelationshipEndpointSchema, } from "./relationship-schema.js";
+import { createToolErrorContext, errorResult, structuredResult } from "./result.js";
+const ConventionSchema = z
+    .array(z.string().min(1).max(MAX_TEST_CANDIDATE_CONVENTION_LENGTH))
+    .max(MAX_TEST_CANDIDATE_CONVENTION_ITEMS)
+    .optional();
+const AstFindTestCandidatesInputSchema = z.object({
+    project_root: z.string(),
+    file_path: z.string(),
+    symbol_path: z.string(),
+    max_depth: z.number().int().min(0).max(MAX_IMPACT_DEPTH).default(DEFAULT_IMPACT_MAX_DEPTH),
+    max_nodes: z.number().int().min(1).max(MAX_IMPACT_NODES).default(DEFAULT_IMPACT_MAX_NODES),
+    max_edges: z.number().int().min(1).max(MAX_IMPACT_EDGES).default(DEFAULT_IMPACT_MAX_EDGES),
+    test_file_patterns: ConventionSchema,
+    test_directories: ConventionSchema,
+    ...PaginationInputSchema,
+});
+const TestCandidateSchema = z.object({
+    file: z.string(),
+    reason: z.enum(TEST_CANDIDATE_REASONS),
+    confidence: z.enum(TEST_CANDIDATE_CONFIDENCES),
+    evidence: z.object({
+        depth: z.number().int().min(0),
+        direct: z.boolean(),
+        compiler_authoritative: z.literal(true),
+        relationship_ids: z.array(z.string()),
+        relationships: z.array(RelationshipEdgeSchema),
+    }),
+});
+const FindTestCandidatesOutputSchema = z.object({
+    backend: z.literal("typescript_compiler"),
+    compiler_authoritative: z.literal(true),
+    root: RelationshipEndpointSchema,
+    direction: z.literal("incoming"),
+    candidates: z.array(TestCandidateSchema),
+    ...PaginationOutputSchema,
+    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.literal(false),
+    truncation: z.object({
+        truncated: z.literal(false),
+        reason: z.null(),
+    }),
+    freshness: FreshnessSchema,
+    completeness: z.object({
+        complete: z.literal(true),
+        proven_empty: z.boolean(),
+    }),
+});
+export function registerFindTestCandidates(server) {
+    server.registerTool("ast_find_test_candidates", {
+        title: "Find compiler-backed affected test candidates",
+        description: "Finds deterministic affected test candidates from fresh, complete incoming compiler relationships. Returns bounded whole-candidate proofs and never executes tests or prepares mutations.",
+        inputSchema: AstFindTestCandidatesInputSchema,
+        outputSchema: FindTestCandidatesOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async ({ project_root, file_path, symbol_path, max_depth, max_nodes, max_edges, test_file_patterns, test_directories, offset, limit, }, extra) => {
+        const requestContext = createRequestContext(extra.signal);
+        try {
+            const result = await withProject(project_root, (context, operationContext) => {
+                if (context.status.state !== "fresh") {
+                    throw new PublicOperationalError("STALE_WORKSPACE", "Retry the workspace 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: "incoming", max_depth, max_nodes, max_edges }, operationContext);
+                if (impact.incomplete || impact.truncation.truncated) {
+                    throw new PublicOperationalError("INCOMPLETE_EVIDENCE", "Evidence is incomplete.");
+                }
+                const candidates = findTestCandidates(impact, {
+                    test_file_patterns,
+                    test_directories,
+                });
+                const page = paginate(candidates, offset, limit);
+                return {
+                    backend: "typescript_compiler",
+                    compiler_authoritative: true,
+                    root: impact.root,
+                    direction: "incoming",
+                    candidates: page.items,
+                    offset: page.offset,
+                    limit: page.limit,
+                    total: page.total,
+                    has_more: page.has_more,
+                    next_offset: page.next_offset,
+                    visited_nodes: impact.visited_nodes,
+                    visited_edges: impact.visited_edges,
+                    max_depth_reached: impact.max_depth_reached,
+                    max_depth: impact.max_depth,
+                    max_nodes: impact.max_nodes,
+                    max_edges: impact.max_edges,
+                    incomplete: false,
+                    truncation: { truncated: false, reason: null },
+                    freshness,
+                    completeness: { complete: true, proven_empty: candidates.length === 0 },
+                };
+            }, requestContext);
+            return structuredResult(FindTestCandidatesOutputSchema.parse(result));
+        }
+        catch (error) {
+            return errorResult(error, createToolErrorContext("ast_find_test_candidates", project_root));
+        }
+    });
+}

package/dist/tools/get_impact.js

@@ -1,9 +1,10 @@
 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 { 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 { RELATIONSHIP_EDGE_KINDS } from "../services/relationships.js";
+import { FreshnessSchema, RelationshipEdgeSchema, RelationshipEndpointSchema, } from "./relationship-schema.js";
 import { createToolErrorContext, errorResult, formattedResult, ToolOutputFormatInputSchema, } from "./result.js";
 const AstGetImpactInputSchema = z.object({
     project_root: z
@@ -42,34 +43,6 @@ const AstGetImpactInputSchema = z.object({
         .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),

package/dist/tools/relationship-schema.js

@@ -0,0 +1,31 @@
+import { z } from "zod";
+import { FRESHNESS_CAUSES, SNAPSHOT_STATES } from "../services/read-contracts.js";
+import { RELATIONSHIP_CONFIDENCES, RELATIONSHIP_EDGE_KINDS, RELATIONSHIP_PROVENANCES, RELATIONSHIP_RESOLUTIONS, } from "../services/relationships.js";
+export 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(),
+});
+export const RelationshipEndpointSchema = z.object({
+    file: z.string(),
+    symbol_path: z.string(),
+    selector: z.string(),
+    range: SourceRangeSchema.optional(),
+});
+export const FreshnessSchema = z.object({
+    state: z.enum(SNAPSHOT_STATES),
+    causes: z.array(z.enum(FRESHNESS_CAUSES)),
+    checked_at: z.string().nullable(),
+});
+export 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,
+});

package/docs/support.md

@@ -1,20 +1,20 @@
 # Support policy
 
-This document defines the supported platform, runtime, persistence, and operational boundary for published `ast-mcp-server` v0.8.1 and the local `0.9.1` release candidate.
+This document defines the supported platform, runtime, persistence, and operational boundary for published `ast-mcp-server` v0.8.1 and the local `0.10.0` release candidate.
 
 ## Supported release target
 
-| Environment                                                                   | Status      | Contract                                                                                       |
-| ----------------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------- |
-| Linux x64 with required GNU coreutils and procfs, Node.js 22.5.0              | Published   | Immutable v0.8.1 release matrix; not the runtime floor of the current development tree.        |
-| Linux x64 with required GNU coreutils and procfs, exact Node.js 22.13.0       | Supported   | Local 0.9.1 candidate package, persistence, MCP/CLI/package, lifecycle and mutation matrix.    |
-| Linux x64 with required GNU coreutils and procfs, current Node.js 24 line     | Supported   | Published v0.8.1 and local 0.9.1 candidate matrices, each bound to its own package/tree bytes. |
-| Other Linux architectures or systems without the required filesystem features | Unverified  | Not supported until equivalent architecture, mutation, and filesystem-publication gates pass.  |
-| macOS                                                                         | Unverified  | Not supported until equivalent filesystem, process, package, mutation, and canary gates pass.  |
-| Windows                                                                       | Unverified  | Not supported until equivalent filesystem, process, package, mutation, and canary gates pass.  |
-| Remote, untrusted, or multi-tenant service use                                | Unsupported | No network authentication, sandbox, or tenant-isolation boundary is provided.                  |
+| Environment                                                                   | Status      | Contract                                                                                        |
+| ----------------------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------- |
+| Linux x64 with required GNU coreutils and procfs, Node.js 22.5.0              | Published   | Immutable v0.8.1 release matrix; not the runtime floor of the current development tree.         |
+| Linux x64 with required GNU coreutils and procfs, exact Node.js 22.13.0       | Supported   | Local 0.10.0 candidate package, persistence, MCP/CLI/package, lifecycle and mutation matrix.    |
+| Linux x64 with required GNU coreutils and procfs, current Node.js 24 line     | Supported   | Published v0.8.1 and local 0.10.0 candidate matrices, each bound to its own package/tree bytes. |
+| Other Linux architectures or systems without the required filesystem features | Unverified  | Not supported until equivalent architecture, mutation, and filesystem-publication gates pass.   |
+| macOS                                                                         | Unverified  | Not supported until equivalent filesystem, process, package, mutation, and canary gates pass.   |
+| Windows                                                                       | Unverified  | Not supported until equivalent filesystem, process, package, mutation, and canary gates pass.   |
+| Remote, untrusted, or multi-tenant service use                                | Unsupported | No network authentication, sandbox, or tenant-isolation boundary is provided.                   |
 
-The local `0.9.1` candidate requires Node.js `>=22.13.0`; its matrix targets exact Node.js 22.13.0 and the governed Node.js 24 major. Published v0.8.1 retains its immutable `>=22.5.0` metadata and exact Node.js 22.5.0/24 release evidence. A future runtime satisfying an engine range is not automatically a verified release target.
+The local `0.10.0` candidate requires Node.js `>=22.13.0`; its matrix targets exact Node.js 22.13.0 and the governed Node.js 24 major. Published v0.8.1 retains its immutable `>=22.5.0` metadata and exact Node.js 22.5.0/24 release evidence. A future runtime satisfying an engine range is not automatically a verified release target.
 
 The checked-evidence freezer requires GNU coreutils 9.7 `mv` with `--update=none-fail`, `--no-copy`, and `--no-target-directory`. Managed setup-file mutation additionally requires that same `mv` with `--exchange`, GNU coreutils `ln -L -T`, procfs descriptor paths at `/proc/self/fd`, `O_DIRECTORY`, and `O_NOFOLLOW`. It fails closed when any verified Linux primitive is unavailable. Equivalent publication, exchange, descriptor-link, and descriptor-relative mutation semantics have not been verified on other operating systems or architectures.
 
@@ -34,7 +34,7 @@ Operation locks coordinate cooperating same-user processes. They do not stop edi
 
 ## Symbol-index persistence
 
-Published v0.8.1 remains memory-default. In the local `0.9.1` candidate, absence and explicit `enabled` select native SQLite; operators requiring no persistent index state must set `disabled` explicitly:
+Published v0.8.1 remains memory-default. In the local `0.10.0` candidate, absence and explicit `enabled` select native SQLite; operators requiring no persistent index state must set `disabled` explicitly:
 
 ```bash
 AST_SYMBOL_INDEX_PERSISTENCE=disabled \
@@ -64,7 +64,7 @@ Both commands are bounded and path-free. Clear preflights the tree, refuses unsa
 
 ## Production-readiness acceptance
 
-The four retained Linux x64 production-readiness reports cover `ast-mcp-server` and `x-scraper` under Node.js 22.5.0 and Node.js 24 for package version 0.6.0, commit `2d0b21bbb80fae1acfca6a85d5891d87e68b59c1`, and tree `af931d49769fabdf06f623965a6cfe1f9afb8a81`. They are historical integration evidence only: they are not reattributed to v0.8.1, published-next v0.9.0, or the local 0.9.1 candidate. The exact 0.9.0 release matrix remains historical evidence for its immutable published-next bytes. A separate exact 0.9.1 release matrix is the candidate-specific gate for current repository bytes under both supported runtime lines, including managed setup; neither matrix rebinds the older retained reports. MCP-PROD-404 remains normative for admission:
+The four retained Linux x64 production-readiness reports cover `ast-mcp-server` and `x-scraper` under Node.js 22.5.0 and Node.js 24 for package version 0.6.0, commit `2d0b21bbb80fae1acfca6a85d5891d87e68b59c1`, and tree `af931d49769fabdf06f623965a6cfe1f9afb8a81`. They are historical integration evidence only: they are not reattributed to v0.8.1, published-next v0.9.0 or v0.9.1, or the local 0.9.2 candidate. The exact 0.9.0 and 0.9.1 release matrices remain historical evidence for their immutable published-next bytes, and the exact 0.9.2 release matrix remains historical local-candidate evidence for its own bytes. A separate exact 0.10.0 release matrix is the candidate-specific gate for current repository bytes under both supported runtime lines, including managed setup; none of these matrices rebinds the older retained reports. MCP-PROD-404 remains normative for admission:
 
 - zero semantic mismatches across disabled, cold, warm, restart, and rollback reads;
 - byte-identical real-repository status and worktree trees;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ast-mcp-server",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "description": "Structural code MCP server and batch CLI for compact TypeScript/JavaScript reads and hash-bound AST edits.",
   "keywords": [
     "mcp",
@@ -97,5 +97,5 @@
     "typescript-eslint": "^8.65.0",
     "vitest": "^4.1.10"
   },
-  "gitHead": "a8b672cd2d1fb2afe65b9cb4a4f842ee75b3faca"
+  "gitHead": "7f97830d82d086e1a7ceafb84a8bc795be57039a"
 }