ast-mcp-server 0.13.0 → 0.14.0

package/dist/services/test-candidates.js

@@ -1,4 +1,14 @@
-import { assertExactImpactEvidence } from "./impact.js";
+import { assertCompleteExactImpactEvidence } from "./impact.js";
+import { isRelationshipCoverageComplete, } from "./relationships.js";
+export const AFFECTED_TEST_RELATIONSHIP_KINDS = Object.freeze([
+    "reference",
+    "import",
+    "export",
+    "extends",
+    "implements",
+    "call",
+]);
+const AFFECTED_TEST_RELATIONSHIP_KIND_SET = new Set(AFFECTED_TEST_RELATIONSHIP_KINDS);
 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([
@@ -156,8 +166,31 @@ function findPathToRoot(startKeys, rootKey, edges) {
     }
     return null;
 }
+function assertCandidateImpactAuthority(impact) {
+    assertCompleteExactImpactEvidence(impact);
+    if (impact.direction !== "incoming" ||
+        impact.relationship_kinds.length !== AFFECTED_TEST_RELATIONSHIP_KINDS.length ||
+        !impact.relationship_kinds.every((kind, index) => kind === AFFECTED_TEST_RELATIONSHIP_KINDS[index])) {
+        throw new Error("Test candidates require the six-kind incoming impact scope.");
+    }
+    const coveredKinds = new Set(impact.coverage?.map((entry) => entry.kind));
+    if (!Array.isArray(impact.coverage) ||
+        coveredKinds.size !== AFFECTED_TEST_RELATIONSHIP_KINDS.length ||
+        !AFFECTED_TEST_RELATIONSHIP_KINDS.every((kind) => coveredKinds.has(kind)) ||
+        !impact.coverage.every((entry) => entry.direction === "incoming" &&
+            AFFECTED_TEST_RELATIONSHIP_KIND_SET.has(entry.kind) &&
+            (entry.status === "completed" || entry.status === "not_applicable")) ||
+        !isRelationshipCoverageComplete(impact.coverage)) {
+        throw new Error("Test candidates require complete six-kind incoming coverage.");
+    }
+    if (impact.work === undefined ||
+        impact.work.work_limit_reached ||
+        impact.work.work_items > impact.work.max_work_items) {
+        throw new Error("Test candidates require bounded impact work.");
+    }
+}
 export function findTestCandidates(impact, conventions = {}) {
-    assertExactImpactEvidence(impact);
+    assertCandidateImpactAuthority(impact);
     if (typeof impact.root !== "object" ||
         impact.root === null ||
         !Array.isArray(impact.nodes) ||

package/dist/tools/explore.js

@@ -17,7 +17,7 @@ const CallSpinesInputSchema = z.object({
     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
+const ExploreInputObjectSchema = z
     .object({
     project_root: z
         .string()
@@ -65,7 +65,8 @@ const ExploreInputSchema = z
         .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), {
+    .strip();
+const ExploreInputSchema = ExploreInputObjectSchema.refine((input) => Boolean(input.query || input.file_path), {
     message: "Provide query, file_path, or both file_path and symbol_path.",
     path: ["query"],
 })
@@ -204,7 +205,7 @@ export function registerExplore(server) {
     server.registerTool(TOOL_NAME, {
         title: "Explore project context",
         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,
+        inputSchema: ExploreInputObjectSchema,
         outputSchema: ExploreOutputSchema,
         annotations: {
             readOnlyHint: true,
@@ -215,6 +216,7 @@ export function registerExplore(server) {
     }, 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 {
+            ExploreInputSchema.parse({ project_root, query, file_path, symbol_path, call_spines });
             const output = await withProject(project_root, (context, operationContext) => buildExploreContext(context, {
                 query,
                 filePath: file_path,

package/dist/tools/find_test_candidates.js

@@ -4,9 +4,10 @@ import { paginate, PaginationInputSchema, PaginationOutputSchema } from "../serv
 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 { AFFECTED_TEST_RELATIONSHIP_KINDS, findTestCandidates, MAX_TEST_CANDIDATE_CONVENTION_ITEMS, MAX_TEST_CANDIDATE_CONVENTION_LENGTH, TEST_CANDIDATE_CONFIDENCES, TEST_CANDIDATE_REASONS, } from "../services/test-candidates.js";
+import { FreshnessSchema, RelationshipCoverageEntrySchema, RelationshipEdgeSchema, RelationshipEndpointSchema, RelationshipWorkSchema, } from "./relationship-schema.js";
 import { createToolErrorContext, errorResult, structuredResult } from "./result.js";
+export { AFFECTED_TEST_RELATIONSHIP_KINDS } from "../services/test-candidates.js";
 const TOOL_NAME = "ast_find_test_candidates";
 const ConventionSchema = z
     .array(z.string().min(1).max(MAX_TEST_CANDIDATE_CONVENTION_LENGTH))
@@ -40,6 +41,16 @@ const FindTestCandidatesOutputSchema = z.object({
     compiler_authoritative: z.literal(true),
     root: RelationshipEndpointSchema,
     direction: z.literal("incoming"),
+    relationship_kinds: z.tuple([
+        z.literal("reference"),
+        z.literal("import"),
+        z.literal("export"),
+        z.literal("extends"),
+        z.literal("implements"),
+        z.literal("call"),
+    ]),
+    coverage: z.array(RelationshipCoverageEntrySchema),
+    work: RelationshipWorkSchema,
     candidates: z.array(TestCandidateSchema),
     ...PaginationOutputSchema,
     visited_nodes: z.number().int().min(0),
@@ -84,7 +95,14 @@ export function registerFindTestCandidates(server) {
                     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);
+                const impact = traverseCompilerImpact(context.project, context.projectRoot, root, freshness, {
+                    direction: "incoming",
+                    relationship_kinds: AFFECTED_TEST_RELATIONSHIP_KINDS,
+                    max_depth,
+                    max_nodes,
+                    max_edges,
+                    authority: "semantic",
+                }, operationContext);
                 if (impact.incomplete || impact.truncation.truncated) {
                     throw new PublicOperationalError("INCOMPLETE_EVIDENCE", "Evidence is incomplete.");
                 }
@@ -98,6 +116,9 @@ export function registerFindTestCandidates(server) {
                     compiler_authoritative: true,
                     root: impact.root,
                     direction: "incoming",
+                    relationship_kinds: AFFECTED_TEST_RELATIONSHIP_KINDS,
+                    coverage: impact.coverage,
+                    work: impact.work,
                     candidates: page.items,
                     offset: page.offset,
                     limit: page.limit,

package/dist/tools/get_impact.js

@@ -4,7 +4,7 @@ import { TRUNCATION_REASONS } from "../services/read-contracts.js";
 import { withProject } from "../services/project.js";
 import { createRequestContext } from "../services/request-context.js";
 import { RELATIONSHIP_EDGE_KINDS } from "../services/relationships.js";
-import { FreshnessSchema, RelationshipEdgeSchema, RelationshipEndpointSchema, } from "./relationship-schema.js";
+import { FreshnessSchema, RelationshipCoverageEntrySchema, RelationshipEdgeSchema, RelationshipEndpointSchema, RelationshipWorkSchema, } from "./relationship-schema.js";
 import { createToolErrorContext, errorResult, formattedResult, ToolOutputFormatInputSchema, } from "./result.js";
 const TOOL_NAME = "ast_get_impact";
 const AstGetImpactInputSchema = z.object({
@@ -60,6 +60,9 @@ const ImpactOutputSchema = z.object({
     max_depth: z.number().int().min(0),
     max_nodes: z.number().int().positive(),
     max_edges: z.number().int().positive(),
+    coverage: z.array(RelationshipCoverageEntrySchema),
+    work: RelationshipWorkSchema,
+    proven_empty: z.boolean(),
     incomplete: z.boolean(),
     truncation: z.object({
         truncated: z.boolean(),
@@ -73,7 +76,6 @@ export function registerGetImpact(server) {
         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,
@@ -93,7 +95,14 @@ export function registerGetImpact(server) {
                     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);
+                const impact = traverseCompilerImpact(context.project, context.projectRoot, root, freshness, {
+                    direction,
+                    max_depth,
+                    max_nodes,
+                    max_edges,
+                    relationship_kinds,
+                    authority: "semantic",
+                }, operationContext);
                 return {
                     ...impact,
                     freshness,

package/dist/tools/relationship-schema.js

@@ -1,6 +1,6 @@
 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";
+import { RELATIONSHIP_CONFIDENCES, RELATIONSHIP_COVERAGE_STATUSES, 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(),
@@ -18,6 +18,17 @@ export const FreshnessSchema = z.object({
     causes: z.array(z.enum(FRESHNESS_CAUSES)),
     checked_at: z.string().nullable(),
 });
+export const RelationshipCoverageEntrySchema = z.object({
+    kind: z.enum(RELATIONSHIP_EDGE_KINDS),
+    direction: z.enum(["incoming", "outgoing"]),
+    endpoint_class: z.enum(["module", "symbol"]),
+    status: z.enum(RELATIONSHIP_COVERAGE_STATUSES),
+});
+export const RelationshipWorkSchema = z.object({
+    work_items: z.number().int().min(0),
+    max_work_items: z.number().int().positive(),
+    work_limit_reached: z.boolean(),
+});
 export const RelationshipEdgeSchema = z.object({
     relationship_id: z.string(),
     source: RelationshipEndpointSchema,

package/dist/tools/result.js

@@ -2,10 +2,15 @@ import { Buffer } from "node:buffer";
 import { isDeepStrictEqual } from "node:util";
 import { decode, encode } from "@toon-format/toon";
 import { z } from "zod";
+import { COMPILER_WORKER_MAX_RESULT_BYTES, fitsCompilerWorkerResponseResult, } from "../services/compiler-worker-protocol.js";
 import { createProjectIdentity } from "../services/project-status.js";
 import { renderPublicError } from "../services/public-errors.js";
 import { emitToolFailureEvent } from "../services/runtime-logger.js";
 export const MAX_TOON_RESULT_BYTES = 10 * 1024 * 1024;
+// Leave room for the unchanged structured value plus JSON-RPC framing under
+// the supervised worker's 256 KiB line limit.
+export const MAX_TEXT_PROJECTION_BYTES = 112 * 1024;
+export const MAX_PROJECTED_RESULT_BYTES = COMPILER_WORKER_MAX_RESULT_BYTES;
 export const ToolOutputFormatSchema = z.enum(["json", "toon"]).default("json");
 export const ToolOutputFormatInputSchema = {
     output_format: ToolOutputFormatSchema.describe("Result representation. TOON wraps one compact encoded value in structuredContent."),
@@ -24,6 +29,49 @@ export function createToolErrorContext(toolName, projectRoot) {
         return { toolName };
     }
 }
+/**
+ * Add a deterministic model-visible JSON projection without replacing the
+ * canonical structured value. Existing content wins, and oversized values get
+ * an explicit bounded marker when the complete framed result has room for it;
+ * otherwise the unchanged structured-only result remains authoritative.
+ */
+export function projectStructuredContentAsText(result, enabled, maxBytes = MAX_TEXT_PROJECTION_BYTES) {
+    if (!enabled ||
+        result.isError === true ||
+        result.content.length > 0 ||
+        result.structuredContent === undefined) {
+        return result;
+    }
+    let text;
+    try {
+        text =
+            JSON.stringify(result.structuredContent) ??
+                "(structured result is not JSON-serializable for model-visible projection)";
+    }
+    catch {
+        text = "(structured result is not JSON-serializable for model-visible projection)";
+    }
+    const byteLength = Buffer.byteLength(text, "utf8");
+    if (byteLength > maxBytes) {
+        text = `(structured result exceeds the ${maxBytes}-byte model-visible projection limit; canonical structuredContent remains available)`;
+    }
+    let projected = {
+        ...result,
+        content: [{ type: "text", text }],
+    };
+    if (fitsCompilerWorkerResponseResult(projected))
+        return projected;
+    projected = {
+        ...result,
+        content: [
+            {
+                type: "text",
+                text: `(structured result exceeds the ${MAX_PROJECTED_RESULT_BYTES}-byte complete projection limit; canonical structuredContent remains available)`,
+            },
+        ],
+    };
+    return fitsCompilerWorkerResponseResult(projected) ? projected : result;
+}
 export function structuredResult(structuredContent) {
     return { content: [], structuredContent };
 }

package/dist/worker-runtime.js

@@ -15,7 +15,12 @@ export async function runStdioServer(options = {}) {
     const runtimeActivity = options.runtimeActivity ?? new RuntimeActivityTracker();
     runtimeActivity.prepareForStartup();
     const runtimePolicy = options.runtimePolicy ?? readRuntimePolicy();
-    const server = options.server ?? createServer({ runtimeActivity, denyApply: runtimePolicy.denyApply });
+    const server = options.server ??
+        createServer({
+            runtimeActivity,
+            denyApply: runtimePolicy.denyApply,
+            projectStructuredContentAsText: runtimePolicy.projectStructuredContentAsText,
+        });
     const transport = options.transport ?? new StdioServerTransport();
     const send = transport.send.bind(transport);
     transport.send = (message, sendOptions) => runtimeActivity.trackSend(() => send(message, sendOptions));

package/docs/support.md

@@ -16,7 +16,7 @@ This document defines the supported platform, runtime, persistence, and operatio
 
 Published v0.12.0 requires Node.js `>=22.13.0`; its immutable matrix targets exact Node.js 22.13.0 and the governed Node.js 24 major. The earlier v0.8.1 Node.js 22.5.0/24 matrix remains historical evidence for those bytes only. 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.
+The checked-evidence freezer requires GNU coreutils 9.7 `mv` with `--update=none-fail`, `--no-copy`, and `--no-target-directory`. Structural apply and managed setup-file mutation additionally require that same `mv` with `--exchange`, GNU coreutils `ln -L -T`, procfs descriptor paths at `/proc/self/fd`, `O_DIRECTORY`/`O_NOFOLLOW`, and successful owned link/exchange identity probes on each destination parent filesystem before source effects. Missing, denied, or behaviorally incompatible primitives fail closed; there is no rename, copy/delete, or pathname-only fallback. Equivalent semantics have not been verified on other operating systems, architectures, or filesystems.
 
 ## Local stdio trust boundary
 
@@ -30,7 +30,9 @@ The server does not provide:
 - tenant isolation;
 - protection from a malicious process running with the same filesystem authority.
 
-Operation locks coordinate cooperating same-user processes. They do not stop editors, network filesystems, or hostile same-user writers. Report-set freezer coordination likewise assumes cooperating same-UID processes and cannot defend checked evidence against a malicious process with the same filesystem authority. The freezer guarantees no-replace atomic visibility of the checked directory; it does not claim persistence across sudden power loss because parent-directory `fsync` durability is not established.
+Operation locks coordinate cooperating processes using the same configuration identity; they do not authorize writes against editors, overlapping configurations, network filesystems, continuously mutating writers, or hostile same-user processes. Structural replacement authenticates one exchanged pair at a time, and multi-file apply is sequential rather than globally atomic. Reverse rollback restores only exact owned pairs. Creation is no-clobber, but if a later failure follows its first publication, unlink ownership is not inferred: the destination and hidden stage are preserved and the outcome is `AMBIGUOUS_APPLY`. Deterministic promise barriers prove only the named publication and rollback interleavings, not arbitrary-writer atomicity.
+
+Report-set freezer coordination likewise assumes cooperating same-UID processes and cannot defend checked evidence against a malicious process with the same filesystem authority. The freezer guarantees no-replace atomic visibility of the checked directory; it does not claim persistence across sudden power loss because parent-directory `fsync` durability is not established.
 
 ## Optional supervised compiler worker
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ast-mcp-server",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Structural code MCP server and batch CLI for compact TypeScript/JavaScript reads and hash-bound AST edits.",
   "keywords": [
     "mcp",
@@ -34,7 +34,13 @@
   "deepseekHarness": {
     "revision": "cd5ef8148158c3a752a658978873241fdf8e2bbc",
     "tag": "dsh-v0.1.2-alpha.1",
-    "mcpClientVersion": "0.1.2-alpha.1"
+    "mcpClientVersion": "0.1.2-alpha.1",
+    "timeoutBudget": {
+      "queueWaitMs": 30000,
+      "executionDeadlineMs": 120000,
+      "marginMs": 15000,
+      "outerToolCallMs": 180000
+    }
   },
   "main": "dist/index.js",
   "bin": {
@@ -54,8 +60,10 @@
     "node": ">=22.13.0"
   },
   "resolutions": {
-    "hono": "4.12.34",
-    "nanoid": "3.3.18"
+    "fast-uri": "3.1.9",
+    "hono": "4.13.13",
+    "nanoid": "3.3.18",
+    "qs": "6.16.0"
   },
   "scripts": {
     "build": "tsc",
@@ -92,12 +100,12 @@
     "dev": "tsc --watch"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.12.0",
+    "@modelcontextprotocol/sdk": "^1.32.1",
     "@toon-format/toon": "4.1.0",
     "diff": "^9.0.0",
     "jsonc-parser": "^3.3.1",
     "ts-morph": "24.0.0",
-    "zod": "^3.23.8"
+    "zod": "^4.6.7"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
@@ -107,8 +115,8 @@
     "prettier": "^3.9.6",
     "typescript": "^5.6.0",
     "typescript-eslint": "^8.65.0",
-    "vitest": "^4.1.10",
+    "vitest": "^4.1.12",
     "yaml": "^2.9.0"
   },
-  "gitHead": "75302189733f40aba6a36a8379c5b1f65fc3bd84"
+  "gitHead": "f6e64751398f69eb3f0f1abc808f4221f7d2bc52"
 }

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

@@ -29,6 +29,14 @@ Published v0.12.0 requires Node.js `>=22.13.0` and retains immutable release evi
 - Nunca reconstruir postimages desde un diff; después del apply, ejecutar el gate canónico del proyecto.
 - Conservar `correlation_id` en errores públicos sin exponer source, paths absolutos, argumentos, environment, cache, stacks ni credenciales.
 
+## Impacto y candidatos de test
+
+`ast_get_impact` separa dos canales. `coverage` asigna a cada kind/direction/endpoint una de `not_applicable`, `completed`, `unsupported` o `unfinished`; `truncation` y `work` describen límites de recorrido. `incomplete` es true si falla cualquiera. `proven_empty` exige cero edges, cobertura aplicable completa y ningún límite agotado.
+
+La selección default conserva los siete kinds. `contains` aplicable es `unsupported`, por lo que el default puede ser semánticamente incompleto sin truncamiento. Calls directas por identificador, `new` y tagged templates pueden ser exactas; property, element, dynamic, unresolved, multiple o external dispatch no generan edges adivinados y dejan esa dirección `unfinished`. No presentar esto como certificación de #219 o #220.
+
+`ast_find_test_candidates` fija seis kinds incoming (`reference`, `import`, `export`, `extends`, `implements`, `call`) y excluye `contains`. Solo acepta evidencia fresh/exact/resolved/compiler-authoritative, cobertura completa y trabajo/recorrido sin agotar. Si no, devuelve `INCOMPLETE_EVIDENCE`, no una página vacía. Después de admitir, pagina candidatos ordenados sin partir paths ni ocultar `coverage`/`work`. MCP entrega JSON canónico; TOON de batch debe conservar el mismo significado lógico.
+
 ## Diagnostic aggregates
 
 `ast_get_diagnostics` keeps its existing response shape unless `include_aggregates: true` is requested. Enabled summaries cover the complete normalized snapshot, not only the selected raw page, and cap both code and file groups at 20.

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

@@ -6,7 +6,7 @@
     "files": [
       {
         "path": "SKILL.md",
-        "sha256": "df2ebc3f3903cf5abf4eb6612da527cad97a92f29f1a9a475ea6e8b4cf47abfb"
+        "sha256": "33d0c6520c1ed54d42a502251a08baed86153bf9b6c275aed4525b2968f1553b"
       },
       {
         "path": "references/operations.md",