ast-mcp-server 0.6.0 → 0.7.0

package/dist/services/impact.js

@@ -0,0 +1,334 @@
+import path from "node:path";
+import { createTruncationMetadata, createSourceLocation, } from "./read-contracts.js";
+import { getSourceFileOrThrow } from "./project.js";
+import { findLocatedDeclaration } from "./symbols.js";
+import { NO_REQUEST_CONTEXT } from "./request-context.js";
+import { createCompilerRelationshipResolver, RELATIONSHIP_EDGE_KINDS, } from "./relationships.js";
+export const IMPACT_DIRECTIONS = Object.freeze(["incoming", "outgoing", "both"]);
+export const DEFAULT_IMPACT_MAX_DEPTH = 3;
+export const DEFAULT_IMPACT_MAX_NODES = 100;
+export const DEFAULT_IMPACT_MAX_EDGES = 200;
+export const MAX_IMPACT_DEPTH = 32;
+export const MAX_IMPACT_NODES = 1_000;
+export const MAX_IMPACT_EDGES = 5_000;
+export function isExactImpactEdge(edge) {
+    return (typeof edge === "object" &&
+        edge !== null &&
+        edge.provenance === "compiler" &&
+        edge.confidence === "exact" &&
+        edge.resolution === "resolved" &&
+        edge.compiler_authoritative === true &&
+        typeof edge.freshness === "object" &&
+        edge.freshness !== null &&
+        edge.freshness.state === "fresh" &&
+        Array.isArray(edge.freshness.causes) &&
+        edge.freshness.causes.length === 0);
+}
+export function assertExactImpactEvidence(impact) {
+    if (typeof impact !== "object" || impact === null || !Array.isArray(impact.edges)) {
+        throw new Error("Impact evidence is invalid.");
+    }
+    if (impact.incomplete) {
+        throw new Error("Test candidates require complete impact evidence.");
+    }
+    if (!impact.edges.every(isExactImpactEdge)) {
+        throw new Error("Test candidates require fresh exact compiler impact evidence.");
+    }
+}
+const IMPACT_PROBE_WORK_ITEMS = 1_024;
+const IMPACT_RELATIONSHIP_WORK_ITEMS = 100_000;
+function assertIntegerInRange(value, minimum, maximum, name) {
+    if (!Number.isInteger(value) || value < minimum || value > maximum) {
+        throw new Error(`${name} must be an integer from ${minimum} to ${maximum}.`);
+    }
+    return value;
+}
+function assertDirection(value) {
+    if (!IMPACT_DIRECTIONS.includes(value)) {
+        throw new Error("Impact direction is invalid.");
+    }
+    return value;
+}
+function normalizeRelationshipKinds(kinds) {
+    if (kinds === undefined)
+        return [...RELATIONSHIP_EDGE_KINDS];
+    if (!Array.isArray(kinds))
+        throw new Error("Impact relationship_kinds must be an array.");
+    const unique = new Set();
+    for (const kind of kinds) {
+        if (!RELATIONSHIP_EDGE_KINDS.includes(kind)) {
+            throw new Error("Impact relationship kind is invalid.");
+        }
+        unique.add(kind);
+    }
+    return [...unique].sort((left, right) => RELATIONSHIP_EDGE_KINDS.indexOf(left) - RELATIONSHIP_EDGE_KINDS.indexOf(right));
+}
+function normalizeOptions(options = {}) {
+    if (typeof options !== "object" || options === null) {
+        throw new Error("Impact traversal options are invalid.");
+    }
+    return {
+        direction: assertDirection(options.direction ?? "both"),
+        max_depth: assertIntegerInRange(options.max_depth ?? DEFAULT_IMPACT_MAX_DEPTH, 0, MAX_IMPACT_DEPTH, "Impact max_depth"),
+        max_nodes: assertIntegerInRange(options.max_nodes ?? DEFAULT_IMPACT_MAX_NODES, 1, MAX_IMPACT_NODES, "Impact max_nodes"),
+        max_edges: assertIntegerInRange(options.max_edges ?? DEFAULT_IMPACT_MAX_EDGES, 1, MAX_IMPACT_EDGES, "Impact max_edges"),
+        relationship_kinds: normalizeRelationshipKinds(options.relationship_kinds),
+    };
+}
+function projectRelativeFile(projectRoot, filePath) {
+    return path.relative(projectRoot, filePath).split(path.sep).join("/");
+}
+function nodeRange(node) {
+    const sourceFile = node.getSourceFile();
+    const start = sourceFile.getLineAndColumnAtPos(node.getStart());
+    const end = sourceFile.getLineAndColumnAtPos(Math.max(node.getStart(), node.getEnd() - 1));
+    return {
+        start_line: start.line,
+        start_column: start.column,
+        end_line: end.line,
+        end_column: end.column,
+    };
+}
+export function resolveImpactRoot(project, projectRoot, request, requestContext = NO_REQUEST_CONTEXT) {
+    requestContext.checkpoint();
+    if (typeof request !== "object" ||
+        request === null ||
+        typeof request.file_path !== "string" ||
+        typeof request.symbol_path !== "string") {
+        throw new Error("Impact root is invalid.");
+    }
+    const sourceFile = getSourceFileOrThrow(project, request.file_path);
+    const located = findLocatedDeclaration(sourceFile, request.symbol_path, () => requestContext.checkpoint());
+    const node = located.node;
+    const location = createSourceLocation(projectRelativeFile(projectRoot, sourceFile.getFilePath()), nodeRange(node));
+    const { file, ...range } = location;
+    return Object.freeze({
+        file,
+        symbol_path: located.symbolPath,
+        selector: `${located.symbolPath}@${located.line}`,
+        range,
+    });
+}
+function endpointKey(endpoint) {
+    return `${endpoint.file}\u0000${endpoint.symbol_path}\u0000${endpoint.selector}`;
+}
+function edgeOrder(left, right) {
+    return (left.kind.localeCompare(right.kind) ||
+        left.source.file.localeCompare(right.source.file) ||
+        left.source.selector.localeCompare(right.source.selector) ||
+        left.target.file.localeCompare(right.target.file) ||
+        left.target.selector.localeCompare(right.target.selector) ||
+        left.relationship_id.localeCompare(right.relationship_id));
+}
+function neighborOrder(left, right) {
+    return (left.endpoint.file.localeCompare(right.endpoint.file) ||
+        left.endpoint.selector.localeCompare(right.endpoint.selector) ||
+        left.endpoint.symbol_path.localeCompare(right.endpoint.symbol_path) ||
+        edgeOrder(left.edge, right.edge));
+}
+function collectNeighbors(current, edges, options, requestContext) {
+    const currentKey = endpointKey(current);
+    const kinds = new Set(options.relationship_kinds);
+    const neighbors = new Map();
+    const orderedEdges = [...edges].sort(edgeOrder);
+    for (const edge of orderedEdges) {
+        requestContext.checkpoint();
+        if (!kinds.has(edge.kind))
+            continue;
+        const matchesSource = endpointKey(edge.source) === currentKey;
+        const matchesTarget = endpointKey(edge.target) === currentKey;
+        if ((options.direction === "outgoing" || options.direction === "both") && matchesSource) {
+            neighbors.set(`${edge.relationship_id}\u0000${endpointKey(edge.target)}`, {
+                edge,
+                endpoint: edge.target,
+            });
+        }
+        if ((options.direction === "incoming" || options.direction === "both") && matchesTarget) {
+            neighbors.set(`${edge.relationship_id}\u0000${endpointKey(edge.source)}`, {
+                edge,
+                endpoint: edge.source,
+            });
+        }
+    }
+    return [...neighbors.values()].sort(neighborOrder);
+}
+function traverseWithNeighborProvider(root, neighborsFor, options = {}, requestContext = NO_REQUEST_CONTEXT) {
+    requestContext.checkpoint();
+    if (typeof root !== "object" || root === null) {
+        throw new Error("Impact traversal input is invalid.");
+    }
+    const normalized = normalizeOptions(options);
+    const nodes = new Map([
+        [endpointKey(root), { endpoint: root, depth: 0, direct: false }],
+    ]);
+    const selectedEdges = new Map();
+    const queue = [{ key: endpointKey(root), endpoint: root, depth: 0 }];
+    const truncationReasons = new Set();
+    let maxDepthReached = 0;
+    const classifyObservedNeighbor = (current, neighbor, edgeBlocked) => {
+        const nextKey = endpointKey(neighbor.endpoint);
+        const isKnownNode = nodes.has(nextKey);
+        if (edgeBlocked)
+            truncationReasons.add("edge_limit");
+        if (!isKnownNode && current.depth + 1 > normalized.max_depth) {
+            truncationReasons.add("depth_limit");
+        }
+        if (!isKnownNode && nodes.size >= normalized.max_nodes) {
+            truncationReasons.add("record_limit");
+        }
+    };
+    while (queue.length > 0) {
+        requestContext.checkpoint();
+        const current = queue.shift();
+        const remainingEdges = normalized.max_edges - selectedEdges.size;
+        if (remainingEdges <= 0) {
+            const probe = neighborsFor(current.endpoint, normalized, requestContext, 1, true, undefined, new Set(selectedEdges.keys()), IMPACT_PROBE_WORK_ITEMS);
+            for (const neighbor of probe.neighbors) {
+                classifyObservedNeighbor(current, neighbor, true);
+            }
+            if (probe.incomplete && !probe.workLimitReached)
+                truncationReasons.add("edge_limit");
+            continue;
+        }
+        const restrictionReason = current.depth >= normalized.max_depth
+            ? "depth_limit"
+            : nodes.size >= normalized.max_nodes
+                ? "record_limit"
+                : undefined;
+        const allowedNeighborKeys = restrictionReason ? new Set(nodes.keys()) : undefined;
+        const batch = neighborsFor(current.endpoint, normalized, requestContext, remainingEdges, false, allowedNeighborKeys, new Set(selectedEdges.keys()));
+        if (batch.excludedNeighbors && restrictionReason)
+            truncationReasons.add(restrictionReason);
+        if (batch.workLimitReached)
+            truncationReasons.add("record_limit");
+        let skippedNewNode = false;
+        for (const neighbor of batch.neighbors) {
+            requestContext.checkpoint();
+            const nextKey = endpointKey(neighbor.endpoint);
+            const nextDepth = current.depth + 1;
+            const isKnownNode = nodes.has(nextKey);
+            if (nextDepth > normalized.max_depth && !isKnownNode) {
+                truncationReasons.add("depth_limit");
+                continue;
+            }
+            if (!isKnownNode && nodes.size >= normalized.max_nodes) {
+                truncationReasons.add("record_limit");
+                skippedNewNode = true;
+                continue;
+            }
+            if (!selectedEdges.has(neighbor.edge.relationship_id)) {
+                if (selectedEdges.size >= normalized.max_edges) {
+                    truncationReasons.add("edge_limit");
+                    continue;
+                }
+                selectedEdges.set(neighbor.edge.relationship_id, neighbor.edge);
+            }
+            if (isKnownNode)
+                continue;
+            nodes.set(nextKey, {
+                endpoint: neighbor.endpoint,
+                depth: nextDepth,
+                direct: nextDepth === 1,
+            });
+            queue.push({ key: nextKey, endpoint: neighbor.endpoint, depth: nextDepth });
+            maxDepthReached = Math.max(maxDepthReached, nextDepth);
+        }
+        if (restrictionReason) {
+            if (batch.incomplete && !batch.workLimitReached)
+                truncationReasons.add("edge_limit");
+            const probe = neighborsFor(current.endpoint, normalized, requestContext, 1, true, undefined, new Set(selectedEdges.keys()), IMPACT_PROBE_WORK_ITEMS);
+            for (const neighbor of probe.neighbors) {
+                classifyObservedNeighbor(current, neighbor, selectedEdges.size >= normalized.max_edges);
+            }
+            continue;
+        }
+        if ((skippedNewNode || nodes.size >= normalized.max_nodes) &&
+            selectedEdges.size < normalized.max_edges) {
+            const knownBatch = neighborsFor(current.endpoint, normalized, requestContext, normalized.max_edges - selectedEdges.size, false, new Set(nodes.keys()), new Set(selectedEdges.keys()));
+            if (knownBatch.excludedNeighbors)
+                truncationReasons.add("record_limit");
+            if (knownBatch.workLimitReached)
+                truncationReasons.add("record_limit");
+            for (const neighbor of knownBatch.neighbors) {
+                requestContext.checkpoint();
+                if (selectedEdges.size >= normalized.max_edges) {
+                    truncationReasons.add("edge_limit");
+                    break;
+                }
+                selectedEdges.set(neighbor.edge.relationship_id, neighbor.edge);
+            }
+            if (knownBatch.incomplete && !knownBatch.workLimitReached) {
+                truncationReasons.add("edge_limit");
+            }
+        }
+        else if (batch.incomplete && !batch.workLimitReached) {
+            truncationReasons.add("edge_limit");
+            const overflowProbe = neighborsFor(current.endpoint, normalized, requestContext, 1, true, undefined, new Set(selectedEdges.keys()), IMPACT_PROBE_WORK_ITEMS);
+            for (const neighbor of overflowProbe.neighbors) {
+                classifyObservedNeighbor(current, neighbor, true);
+            }
+        }
+    }
+    const orderedReasons = ["depth_limit", "record_limit", "edge_limit"].filter((reason) => truncationReasons.has(reason));
+    const truncated = orderedReasons.length > 0;
+    requestContext.checkpoint();
+    return {
+        root,
+        direction: normalized.direction,
+        relationship_kinds: normalized.relationship_kinds,
+        nodes: [...nodes.values()].sort((left, right) => left.depth - right.depth ||
+            left.endpoint.file.localeCompare(right.endpoint.file) ||
+            left.endpoint.selector.localeCompare(right.endpoint.selector) ||
+            left.endpoint.symbol_path.localeCompare(right.endpoint.symbol_path)),
+        edges: [...selectedEdges.values()].sort(edgeOrder),
+        visited_nodes: nodes.size,
+        visited_edges: selectedEdges.size,
+        max_depth_reached: maxDepthReached,
+        max_depth: normalized.max_depth,
+        max_nodes: normalized.max_nodes,
+        max_edges: normalized.max_edges,
+        incomplete: truncated,
+        truncation: createTruncationMetadata(truncated, truncated ? orderedReasons[0] : null),
+        truncation_reasons: orderedReasons,
+    };
+}
+export function traverseImpact(root, edges, options = {}, requestContext = NO_REQUEST_CONTEXT) {
+    if (!Array.isArray(edges))
+        throw new Error("Impact traversal input is invalid.");
+    return traverseWithNeighborProvider(root, (current, normalized, _context, maxEdges, _stopAfterFirst, allowedNeighborKeys, excludedRelationshipIds) => {
+        const allNeighbors = collectNeighbors(current, edges, normalized, requestContext).filter((neighbor) => !excludedRelationshipIds?.has(neighbor.edge.relationship_id));
+        const neighbors = allowedNeighborKeys
+            ? allNeighbors.filter((neighbor) => allowedNeighborKeys.has(endpointKey(neighbor.endpoint)))
+            : allNeighbors;
+        return {
+            neighbors: neighbors.slice(0, maxEdges),
+            incomplete: neighbors.length > maxEdges,
+            excludedNeighbors: allowedNeighborKeys
+                ? allNeighbors.some((neighbor) => !allowedNeighborKeys.has(endpointKey(neighbor.endpoint)))
+                : false,
+            workLimitReached: false,
+        };
+    }, options, requestContext);
+}
+export function traverseCompilerImpact(project, projectRoot, root, freshness, options = {}, requestContext = NO_REQUEST_CONTEXT) {
+    const resolver = createCompilerRelationshipResolver(project, projectRoot, freshness, requestContext);
+    return traverseWithNeighborProvider(root, (current, normalized, _context, maxEdges, stopAfterFirst, allowedNeighborKeys, excludedRelationshipIds, maxWorkItems) => {
+        const resolution = resolver.edgesFor(current, {
+            direction: normalized.direction,
+            relationship_kinds: normalized.relationship_kinds,
+            max_edges: maxEdges,
+            max_work_items: maxWorkItems ?? IMPACT_RELATIONSHIP_WORK_ITEMS,
+            allowed_neighbor_keys: allowedNeighborKeys ? [...allowedNeighborKeys] : undefined,
+            excluded_relationship_ids: excludedRelationshipIds
+                ? [...excludedRelationshipIds]
+                : undefined,
+            stop_after_first: stopAfterFirst,
+        });
+        return {
+            neighbors: collectNeighbors(current, resolution.edges, normalized, requestContext),
+            incomplete: resolution.incomplete,
+            excludedNeighbors: resolution.excluded_neighbors,
+            workLimitReached: resolution.work_limit_reached,
+        };
+    }, options, requestContext);
+}