ast-mcp-server 0.9.2 → 0.10.0

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.2` 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.2 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.2 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.2` 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.2` 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 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. A separate exact 0.9.2 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:
+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.2",
+  "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": "289e280109c2cbd07e353d3c35cc372545b684b4"
+  "gitHead": "7f97830d82d086e1a7ceafb84a8bc795be57039a"
 }

package/skills/structural-code-editing/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: structural-code-editing
 description: Leer, navegar y editar proyectos TypeScript/JavaScript mediante el resolver real del compilador y operaciones AST preparadas, revisadas y vinculadas por hash.
-version: "4.3.0"
+version: "4.4.0"
 author: "yail"
 license: "ISC"
 metadata:
@@ -46,7 +46,7 @@ El setup falla cerrado ante un registro `ast` conflictivo. No eliminar ni reempl
 
 ## Runtime, soporte y errores
 
-El candidato local 0.9.2 requiere Node.js `>=22.13.0` y se verifica con Node.js exacto 22.13.0 y la línea actual de Node.js 24. La versión publicada v0.8.1 conserva su matriz inmutable 22.5.0/24. La publicación de archivos gestionados por setup requiere además GNU coreutils 9.7 `mv` con `--update=none-fail`, `--exchange`, `--no-copy` y `--no-target-directory`, GNU coreutils `ln -L -T`, y procfs en `/proc/self/fd` con `O_DIRECTORY`/`O_NOFOLLOW`. Otras arquitecturas Linux, sistemas sin esos primitivos, macOS y Windows están sin verificar.
+El candidato local 0.10.0 requiere Node.js `>=22.13.0` y se verifica con Node.js exacto 22.13.0 y la línea actual de Node.js 24. La versión publicada v0.8.1 conserva su matriz inmutable 22.5.0/24. La publicación de archivos gestionados por setup requiere además GNU coreutils 9.7 `mv` con `--update=none-fail`, `--exchange`, `--no-copy` y `--no-target-directory`, GNU coreutils `ln -L -T`, y procfs en `/proc/self/fd` con `O_DIRECTORY`/`O_NOFOLLOW`. Otras arquitecturas Linux, sistemas sin esos primitivos, macOS y Windows están sin verificar.
 
 El transporte soportado es stdio local bajo los permisos filesystem del usuario que invoca el proceso. No asumir autenticación HTTP, sandbox, aislamiento entre tenants ni una frontera segura para clientes remotos o no confiables.
 
@@ -73,7 +73,7 @@ Los errores públicos de las tools MCP usan un vocabulario cerrado dentro de `{
 
 `ast_get_file` es read-only y solo acepta archivos incluidos por el tsconfig activo. Su modo normal devuelve líneas exactas, paginadas y numeradas desde 1, junto con el hash SHA-256 de los bytes actuales. `symbols_only: true` devuelve selectors y signatures sin cuerpos. `snapshot_state: "fresh"` describe sincronización con el snapshot del compilador, no ausencia de diagnostics; consultar `ast_get_diagnostics` por separado.
 
-`ast_explore` es read-only y no prepara ni aplica operaciones. Sus selectors son directamente reutilizables por las tools primitivas y de mutación. La respuesta declara `freshness`, `completeness`, `truncation`, `unresolved` y `budget`; si el límite de bytes impide incluir todo el contexto, el resultado queda marcado como incompleto.
+`ast_explore` es read-only y no prepara ni aplica operaciones. Sus selectors son directamente reutilizables por las tools primitivas y de mutación. La respuesta admite clusters completos dentro de `max_bytes`, nunca corta source, referencias ni paths, y clasifica lo omitido como `budget`, `incomplete` o `untrusted`. Para un `file_path + symbol_path` exacto, `call_spines` puede pedir paths estáticos de invocación compiler-resolved; no representa stacks de runtime ni relabela referencias genéricas. Ausencia de la opción no ejecuta ese recorrido.
 
 ## Modelo de confianza y freshness
 
@@ -86,7 +86,7 @@ No tratar toda salida como evidencia equivalente. Cuando una relación expone me
 
 `fresh` significa que la evidencia coincide con el snapshot sincronizado. `pending`, `rebuilding`, `stale` y `degraded` no deben presentarse como evidencia actual. Las respuestas preservan `causes` (`source_change`, `config_change`, `index_failure`, `watcher_failure`, `compiler_rebuild`) y `checked_at`. `ast_get_impact` rechaza relaciones que no estén fresh; `ast_explore` conserva `completeness`, `unresolved`, `budget` y `truncation` para que una lectura parcial no parezca un negativo.
 
-El resolver interno de candidatos de tests solo acepta impacto fresh y exacto, devuelve evidencia de relación directa o transitiva con IDs bounded y no ejecuta tests. Si la relación es stale, está truncada, es ambigua o solo heurística, no genera candidatos.
+`ast_find_test_candidates` resuelve un símbolo exacto, fuerza impacto entrante y solo acepta evidencia fresh, exacta, resuelta y compiler-authoritative. Devuelve candidatos directos, transitivos o por convención con IDs y paths de relación completos; no ejecuta tests. Evidencia stale, truncada, incompleta, ambigua, heurística o no autoritativa falla cerrada. Solo un recorrido completo puede devolver una página vacía marcada `proven_empty`.
 
 Todos los reads son bounded. Respetar `limit`, `reference_limit`, `max_bytes`, y en impacto `max_depth`, `max_nodes` y `max_edges`; revisar siempre `budget` y `truncation` antes de razonar sobre ausencia. Los límites de batch son independientes y también deben mantenerse explícitos.
 
@@ -115,6 +115,8 @@ Cuando un pipeline conocido requiere varias llamadas MCP dependientes y el clien
 - Definir `emit` para que los resultados intermedios no entren al contexto.
 - Mantener paginación y filtros: batch elimina roundtrips, no vuelve razonable leer un monorepo entero.
 - No generar JavaScript/eval dentro del documento; el contrato es declarativo y limitado.
+- `ast_find_test_candidates` está admitida como lectura: el batch inyecta el `project_root` del pipeline, rechaza conflictos y conserva candidatos completos al paginar. JSON y el TOON final representan el mismo resultado lógico del handler MCP registrado.
+- `ast_explore` también está admitida como lectura mediante el handler MCP registrado. Mantener `max_bytes` y los límites de spines explícitos; los intermediates son JSON y solo el resultado final puede serializarse como TOON.
 
 `ast-tool validate pipeline.json` valida schema, orden de referencias y política sin cargar el proyecto. Límites por defecto: 50 steps, 500 invocaciones, 200 items por foreach, concurrencia 4 (máximo 16), input 1 MiB, 10 MiB por resultado retenido/output y 50 MiB de contexto intermedio acumulado. Los errores del CLI permanecen como JSON en stderr aunque el output exitoso solicitado sea TOON.
 

package/skills/structural-code-editing/releases.json

@@ -2,8 +2,8 @@
   "schema_version": 1,
   "algorithm": "sha256",
   "current": {
-    "version": "4.3.0",
-    "sha256": "bf0814b539cd8638aeed108a4e118fe1f2ab418e2e968a77ad75f2d0dbde93b9"
+    "version": "4.4.0",
+    "sha256": "253b588c56d44c8f5565db3f33ce227d80c7c29aa6604d362844f44b1278385a"
   },
   "predecessors": [
     {
@@ -60,6 +60,11 @@
       "version": "4.3.0",
       "sha256": "a8dc2ba8eecbf3a21d7a86092323a2674b0353f5ec1f2bb36ba7ed0cd2890c20",
       "npm_versions": ["0.9.1"]
+    },
+    {
+      "version": "4.3.0",
+      "sha256": "bf0814b539cd8638aeed108a4e118fe1f2ab418e2e968a77ad75f2d0dbde93b9",
+      "npm_versions": ["0.9.2"]
     }
   ]
 }