ast-mcp-server 0.5.1 → 0.7.0

package/dist/services/file-fingerprints.js

@@ -0,0 +1,104 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+function isMissingFileError(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        (error.code === "ENOENT" || error.code === "ENOTDIR"));
+}
+function resolveCandidatePath(filePath) {
+    try {
+        return fs.realpathSync(filePath);
+    }
+    catch (error) {
+        if (!isMissingFileError(error))
+            throw error;
+        return path.resolve(filePath);
+    }
+}
+function assertRegularFile(filePath) {
+    const stats = fs.statSync(filePath, { bigint: true });
+    if (!stats.isFile()) {
+        throw new Error(`Cannot fingerprint non-file path: ${filePath}`);
+    }
+    return stats;
+}
+function metadataMatches(previous, current) {
+    return (previous.size_bytes === current.size_bytes &&
+        previous.mtime_ns === current.mtime_ns &&
+        previous.device === current.device &&
+        previous.inode === current.inode);
+}
+export function hashBytes(content) {
+    return createHash("sha256").update(content).digest("hex");
+}
+export function captureFileFingerprint(filePath, previous, options = {}) {
+    const canonicalPath = fs.realpathSync(filePath);
+    const stats = assertRegularFile(canonicalPath);
+    const metadata = {
+        size_bytes: Number(stats.size),
+        mtime_ns: stats.mtimeNs.toString(),
+        device: stats.dev.toString(),
+        inode: stats.ino.toString(),
+    };
+    if (!Number.isSafeInteger(metadata.size_bytes)) {
+        throw new Error(`File size is outside the safe integer range: ${canonicalPath}`);
+    }
+    if (previous && metadataMatches(previous, metadata) && !options.verifyContentHash) {
+        return {
+            ...previous,
+            file_path: canonicalPath,
+        };
+    }
+    return {
+        file_path: canonicalPath,
+        ...metadata,
+        content_hash: hashBytes(fs.readFileSync(canonicalPath)),
+    };
+}
+export function collectFileFingerprints(filePaths, previous = new Map(), options = {}) {
+    const files = new Map();
+    const missing = new Set();
+    for (const filePath of new Set(filePaths)) {
+        const candidatePath = resolveCandidatePath(filePath);
+        try {
+            const previousFingerprint = previous.get(candidatePath);
+            const fingerprint = captureFileFingerprint(candidatePath, previousFingerprint, options);
+            files.set(fingerprint.file_path, fingerprint);
+        }
+        catch (error) {
+            if (!isMissingFileError(error))
+                throw error;
+            missing.add(candidatePath);
+        }
+    }
+    return {
+        files,
+        missing: [...missing].sort(),
+    };
+}
+export function compareFileFingerprints(previous, current) {
+    const added = [];
+    const changed = [];
+    const deleted = [];
+    const unchanged = [];
+    const paths = [...new Set([...previous.keys(), ...current.keys()])].sort();
+    for (const filePath of paths) {
+        const before = previous.get(filePath);
+        const after = current.get(filePath);
+        if (!before && after) {
+            added.push(filePath);
+        }
+        else if (before && !after) {
+            deleted.push(filePath);
+        }
+        else if (before && after && before.content_hash !== after.content_hash) {
+            changed.push(filePath);
+        }
+        else {
+            unchanged.push(filePath);
+        }
+    }
+    return { added, changed, deleted, unchanged };
+}

package/dist/services/file-snapshot.js

@@ -0,0 +1,103 @@
+import { TextDecoder } from "node:util";
+import { lstat, readFile, realpath } from "node:fs/promises";
+import path from "node:path";
+import { getSourceFileOrThrow } from "./project.js";
+import { NO_REQUEST_CONTEXT } from "./request-context.js";
+import { hashBytes } from "./workspace.js";
+export const DEFAULT_FILE_LINE_LIMIT = 200;
+export const MAX_FILE_LINE_LIMIT = 500;
+function assertBoundedRange({ offset, limit }) {
+    if (!Number.isInteger(offset) || offset < 0) {
+        throw new Error("File offset must be a non-negative integer.");
+    }
+    if (!Number.isInteger(limit) || limit < 1 || limit > MAX_FILE_LINE_LIMIT) {
+        throw new Error(`File limit must be an integer between 1 and ${MAX_FILE_LINE_LIMIT}.`);
+    }
+}
+function rejectTraversalPath(filePath) {
+    const normalized = filePath.replaceAll("\\", "/");
+    const segments = normalized.split("/");
+    const isWindowsAbsolute = /^[A-Za-z]:\//.test(normalized) || normalized.startsWith("//");
+    if (segments.includes("..")) {
+        throw new Error("File path traversal is not allowed.");
+    }
+    if (isWindowsAbsolute && !path.isAbsolute(filePath)) {
+        throw new Error("Windows absolute paths are not valid on this host.");
+    }
+}
+function isContained(root, candidate) {
+    const relative = path.relative(root, candidate);
+    return (relative.length > 0 &&
+        relative !== ".." &&
+        !relative.startsWith(`..${path.sep}`) &&
+        !path.isAbsolute(relative));
+}
+function projectRelative(root, filePath) {
+    return path.relative(root, filePath).split(path.sep).join("/");
+}
+function decodeUtf8(bytes, filePath) {
+    try {
+        return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+    }
+    catch {
+        throw new Error(`Source file "${filePath}" is not valid UTF-8.`);
+    }
+}
+function splitLines(source) {
+    if (source.length === 0)
+        return [];
+    const lines = source.split(/\r\n|\n|\r/);
+    if (source.endsWith("\n") || source.endsWith("\r"))
+        lines.pop();
+    return lines;
+}
+function compilerSnapshotHashes(sourceText) {
+    const sourceBytes = Buffer.from(sourceText, "utf8");
+    const hashes = [hashBytes(sourceBytes)];
+    if (sourceText.charCodeAt(0) !== 0xfeff) {
+        hashes.push(hashBytes(Buffer.concat([Buffer.from([0xef, 0xbb, 0xbf]), sourceBytes])));
+    }
+    return hashes;
+}
+export async function readFileSnapshot(project, projectRoot, filePath, options, requestContext = NO_REQUEST_CONTEXT) {
+    requestContext.checkpoint();
+    assertBoundedRange(options);
+    rejectTraversalPath(filePath);
+    const sourceFile = getSourceFileOrThrow(project, filePath);
+    requestContext.checkpoint();
+    const canonicalRoot = await realpath(projectRoot);
+    const sourcePath = sourceFile.getFilePath();
+    const canonicalFile = await realpath(sourcePath);
+    requestContext.checkpoint();
+    if (!isContained(canonicalRoot, canonicalFile)) {
+        throw new Error("Source file resolves outside the configured project root.");
+    }
+    const stat = await lstat(canonicalFile);
+    requestContext.checkpoint();
+    if (!stat.isFile()) {
+        throw new Error("Source file is not a regular file.");
+    }
+    const bytes = await readFile(canonicalFile);
+    requestContext.checkpoint();
+    const source = decodeUtf8(bytes, projectRelative(canonicalRoot, canonicalFile));
+    const fileHash = hashBytes(bytes);
+    const compilerHashes = compilerSnapshotHashes(sourceFile.getFullText());
+    const snapshotState = compilerHashes.includes(fileHash) ? "fresh" : "stale";
+    const allLines = splitLines(source);
+    const selectedLines = allLines.slice(options.offset, options.offset + options.limit);
+    requestContext.checkpoint();
+    return {
+        file: projectRelative(canonicalRoot, canonicalFile),
+        range: {
+            offset: options.offset,
+            limit: options.limit,
+            total_lines: allLines.length,
+        },
+        lines: selectedLines.map((text, index) => ({
+            line: options.offset + index + 1,
+            text,
+        })),
+        file_hash: fileHash,
+        snapshot_state: snapshotState,
+    };
+}

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);
+}