@lzehrung/codegraph 2.1.1 → 2.2.0

package/dist/mcp/handlers.js

@@ -0,0 +1,657 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { buildCodegraphArtifactWithSession } from "../agent/artifact.js";
+import { explainCodegraphTargetWithSession } from "../agent/explain.js";
+import { getCodegraphFileViewWithSession } from "../agent/fileView.js";
+import { exploreCodegraphWithSession } from "../agent/explore.js";
+import { orientCodegraphWithSession } from "../agent/orient.js";
+import { getCodegraphPacketWithSession } from "../agent/packet.js";
+import { searchCodegraphWithSession } from "../agent/search.js";
+import { workspaceSymbolsWithSession } from "../agent/workspaceSymbols.js";
+import { findImplementationsWithSession, findSubtypesWithSession, findSupertypesWithSession, } from "../agent/typeHierarchy.js";
+import { findCalleesWithSession, findCallersWithSession } from "../agent/callHierarchy.js";
+import { previewRenameWithSession } from "../agent/renamePreview.js";
+import { buildRefactorPlanWithSession } from "../agent/refactorPlan.js";
+import { parseAgentSymbolHandle } from "../agent/handles.js";
+import { requireSemanticSymbol, resolveSemanticSymbol } from "../agent/semanticSymbols.js";
+import { getDependencies, getReverseDependencies, getShortestPath } from "../graphs/queries.js";
+import { findReferences, goToDefinition } from "../indexer/navigation.js";
+import { parseQualifiedSymbolPath } from "../indexer/symbols.js";
+import { analyzeImpactFromDiff } from "../impact/index.js";
+import { DEFAULT_BOUNDED_IMPACT_BUDGETS } from "../impact/budgets.js";
+import { buildReviewReport } from "../review.js";
+import { boundReviewReportForTransport } from "../review/types.js";
+import { SQLITE_ARTIFACT_FILE_SIGNATURES_METADATA_KEY, queryGraphSqliteRaw } from "../sqlite.js";
+import { boundList, countOmitted } from "../presentation/bounds.js";
+import { isPlainRecord } from "../util/guards.js";
+import { toProjectDisplayPath } from "../util/paths.js";
+import { assertNoPrebuiltSessionWithBuildOptions, createAgentSession, listAgentSessionFiles, } from "../agent/session.js";
+import { mapLimit } from "../util/concurrency.js";
+import { assertRealPathCandidateWithinRoot, resolveProjectFile } from "../util/confinedFile.js";
+import { SymbolKind } from "../indexer/types.js";
+import { DEFAULT_WORKSPACE_SYMBOL_LIMIT, MAX_WORKSPACE_SYMBOL_LIMIT } from "../indexer/workspace-symbols.js";
+import { assertMcpSqliteQueryResourceBounded, DEFAULT_SQLITE_BYTE_LIMIT, normalizeSqliteRowLimit, } from "./sqliteGuard.js";
+import { DEFAULT_CALL_HIERARCHY_LIMIT, MAX_CALL_HIERARCHY_LIMIT, DEFAULT_MCP_COLLECTION_LIMIT, DEFAULT_TYPE_HIERARCHY_LIMIT, MAX_TYPE_HIERARCHY_LIMIT, MAX_MCP_COLLECTION_LIMIT, } from "./tools.js";
+import {} from "../runtimeIdentity.js";
+import { assertWritableDirectoryRealPathWithinRoot, resolveArtifactSqlitePathCandidate } from "./security.js";
+const MAX_MCP_FRESHNESS_CHANGED_FILES = 25;
+const MAX_MCP_FRESHNESS_RETRIES = 3;
+const SQLITE_ARTIFACT_STAT_CONCURRENCY = 64;
+function assertMcpSessionOptions(options) {
+    assertNoPrebuiltSessionWithBuildOptions(options, "MCP server options");
+}
+function createCodegraphMcpSession(options, root) {
+    assertMcpSessionOptions(options);
+    return (options.session ??
+        createAgentSession({
+            root,
+            ...(options.buildOptions ? { buildOptions: options.buildOptions } : {}),
+            freshness: { policy: "auto" },
+        }));
+}
+function startCodegraphMcpWarmup(session, warmup) {
+    if (warmup === "base") {
+        return session.loadProject({ symbolGraph: "skip" });
+    }
+    if (warmup === "symbols") {
+        return session.loadProject();
+    }
+    return undefined;
+}
+export async function createWarmedCodegraphMcpResources(options) {
+    const root = path.resolve(options.root);
+    const session = createCodegraphMcpSession(options, root);
+    await startCodegraphMcpWarmup(session, options.warmup);
+    const { warmup, host, port, onHttpListen, ...handlerOptions } = options;
+    void warmup;
+    void host;
+    void port;
+    void onHttpListen;
+    return {
+        handlers: createCodegraphMcpHandlersForSession({ ...handlerOptions, root }, session),
+        session,
+    };
+}
+export function createCodegraphMcpHandlers(options) {
+    const root = path.resolve(options.root);
+    const session = createCodegraphMcpSession(options, root);
+    return createCodegraphMcpHandlersForSession(options, session);
+}
+function createCodegraphMcpHandlersForSession(options, session) {
+    const root = path.resolve(options.root);
+    const readOnly = options.readOnly ?? true;
+    const realRoot = fs.realpath(root);
+    const configuredSqlitePath = options.artifactPath
+        ? resolveArtifactSqlitePathCandidate(root, options.artifactPath)
+        : undefined;
+    const configuredSqliteOutDir = configuredSqlitePath ? path.dirname(configuredSqlitePath) : undefined;
+    const configuredSqliteCanRefresh = options.artifactPath ? !/\.(sqlite|db)$/i.test(options.artifactPath) : false;
+    let sqlitePath = configuredSqlitePath;
+    let sqliteOutDir = configuredSqliteOutDir;
+    let sqliteCanRefresh = configuredSqliteCanRefresh;
+    let refreshPromise;
+    let refreshEpoch = 0;
+    let artifactWritePromise;
+    const withArtifactWriteLock = async (operation) => {
+        const previous = artifactWritePromise;
+        const complete = Promise.withResolvers();
+        artifactWritePromise = complete.promise;
+        try {
+            if (previous)
+                await previous.catch(() => undefined);
+            return await operation();
+        }
+        finally {
+            complete.resolve();
+            if (artifactWritePromise === complete.promise)
+                artifactWritePromise = undefined;
+        }
+    };
+    const relative = (file) => toProjectDisplayPath(root, file);
+    const boundedLimit = (limit, fallback, max) => {
+        if (typeof limit !== "number" || !Number.isFinite(limit))
+            return fallback;
+        return Math.min(max, Math.max(0, Math.floor(limit)));
+    };
+    const staleFreshness = (files, reason) => {
+        const changedFiles = [...files].sort();
+        const boundedChangedFiles = changedFiles.slice(0, MAX_MCP_FRESHNESS_CHANGED_FILES);
+        return {
+            state: "stale",
+            changedFiles: boundedChangedFiles,
+            changedFileCount: changedFiles.length,
+            omittedChangedFileCount: countOmitted(changedFiles.length, boundedChangedFiles.length),
+            reason,
+        };
+    };
+    const checkMcpFreshness = async () => {
+        if (session.checkFreshness)
+            return await session.checkFreshness();
+        return { state: "fresh" };
+    };
+    const withFreshness = async (run) => {
+        for (let attempt = 0; attempt < MAX_MCP_FRESHNESS_RETRIES; attempt += 1) {
+            if (refreshPromise)
+                await refreshPromise;
+            const epoch = refreshEpoch;
+            const freshness = await checkMcpFreshness();
+            const result = await run();
+            if (epoch === refreshEpoch && !refreshPromise)
+                return { ...result, freshness };
+        }
+        throw new Error("Workspace refresh changed repeatedly while serving the request; retry after refresh completes.");
+    };
+    const formatSqliteFreshnessError = (freshness) => {
+        if (freshness.state === "fresh")
+            return "SQLite artifact freshness check unexpectedly failed.";
+        const reason = freshness.state === "stale" ? freshness.reason : "workspace changed after artifact build";
+        const changed = freshness.changedFiles.length ? ` Changed files: ${freshness.changedFiles.join(", ")}.` : "";
+        const omitted = freshness.state === "stale" && freshness.omittedChangedFileCount
+            ? ` Omitted changed files: ${freshness.omittedChangedFileCount}.`
+            : "";
+        let action = "run artifact_build";
+        if (readOnly) {
+            action = "rebuild the artifact with write access enabled";
+        }
+        if (freshness.state === "stale") {
+            action = `run refresh_index, then ${action}`;
+        }
+        return `SQLite artifact is stale; ${action} before query_sqlite. ${reason}.${changed}${omitted}`;
+    };
+    const canRefreshSqliteArtifact = () => {
+        if (!sqlitePath || !sqliteOutDir || readOnly || !sqliteCanRefresh)
+            return false;
+        return path.basename(sqlitePath) === "codegraph.sqlite";
+    };
+    const rebuildSqliteArtifactForQuery = async () => await withArtifactWriteLock(async () => {
+        if (!sqliteOutDir)
+            throw new Error("SQLite artifact output directory is unavailable.");
+        const outDir = await assertWritableDirectoryRealPathWithinRoot(await realRoot, root, sqliteOutDir, "Artifact output directory");
+        const result = await buildCodegraphArtifactWithSession(session, {
+            root,
+            outDir,
+            filterOutDir: outDir,
+            sqlite: true,
+            force: true,
+        });
+        const sqliteArtifact = result.artifacts.sqlite;
+        if (!sqliteArtifact)
+            throw new Error("SQLite artifact refresh did not produce a SQLite file.");
+        sqlitePath = path.join(result.outDir, sqliteArtifact);
+        sqliteOutDir = result.outDir;
+    });
+    const refreshSqliteArtifactForQuery = async (freshness, refreshOptions) => {
+        if (freshness.state === "fresh")
+            return freshness;
+        if (freshness.state === "stale" && !refreshOptions?.allowStaleRebuild) {
+            throw new Error(formatSqliteFreshnessError(freshness));
+        }
+        if (!canRefreshSqliteArtifact())
+            throw new Error(formatSqliteFreshnessError(freshness));
+        await rebuildSqliteArtifactForQuery();
+        return { state: "refreshed", changedFiles: freshness.changedFiles };
+    };
+    const readSqliteArtifactSignatures = async (realSqlitePath) => {
+        const result = await queryGraphSqliteRaw(realSqlitePath, "SELECT value FROM graph_metadata WHERE key = ?;", [SQLITE_ARTIFACT_FILE_SIGNATURES_METADATA_KEY], { maxRows: 1 });
+        const rawValue = result.rows[0]?.[0];
+        if (typeof rawValue !== "string")
+            return null;
+        let parsed;
+        try {
+            parsed = JSON.parse(rawValue);
+        }
+        catch {
+            return null;
+        }
+        if (!Array.isArray(parsed))
+            return null;
+        const signatures = [];
+        for (const value of parsed) {
+            if (!isPlainRecord(value))
+                continue;
+            if (typeof value.path !== "string")
+                continue;
+            if (typeof value.size !== "number" || typeof value.mtimeMs !== "number")
+                continue;
+            signatures.push({ path: value.path, size: value.size, mtimeMs: value.mtimeMs });
+        }
+        return signatures;
+    };
+    const isFileInsideDirectory = (file, directory) => {
+        const relativeFile = path.relative(directory, file);
+        if (!relativeFile)
+            return true;
+        return !relativeFile.startsWith("..") && !path.isAbsolute(relativeFile);
+    };
+    const collectCurrentSqliteArtifactSignatures = async () => {
+        const outputDirectories = [];
+        if (sqliteOutDir) {
+            outputDirectories.push(sqliteOutDir);
+            const lexicalOutDir = path.resolve(root, path.relative(await realRoot, sqliteOutDir));
+            outputDirectories.push(lexicalOutDir);
+        }
+        let discoveredFiles;
+        if (session.discoverFiles) {
+            discoveredFiles = await session.discoverFiles();
+        }
+        else if (options.session) {
+            throw new Error("MCP session does not expose live file discovery for SQLite freshness.");
+        }
+        else {
+            discoveredFiles = await listAgentSessionFiles({
+                root,
+                ...(options.buildOptions ? { buildOptions: options.buildOptions } : {}),
+            });
+        }
+        const currentFiles = discoveredFiles.filter((file) => !outputDirectories.some((directory) => isFileInsideDirectory(file, directory)));
+        const signatures = new Map();
+        await mapLimit(currentFiles, SQLITE_ARTIFACT_STAT_CONCURRENCY, async (file) => {
+            try {
+                const stat = await fs.stat(file);
+                if (!stat.isFile())
+                    return;
+                signatures.set(relative(file), { path: file, size: stat.size, mtimeMs: stat.mtimeMs });
+            }
+            catch (error) {
+                if (error instanceof Error && "code" in error && (error.code === "ENOENT" || error.code === "ENOTDIR")) {
+                    return;
+                }
+                throw error;
+            }
+        });
+        return signatures;
+    };
+    const checkSqliteArtifactFreshness = async (realSqlitePath) => {
+        const storedSignatures = await readSqliteArtifactSignatures(realSqlitePath);
+        if (!storedSignatures)
+            return staleFreshness([], "SQLite artifact has no freshness baseline");
+        const storedByFile = new Map();
+        for (const signature of storedSignatures) {
+            storedByFile.set(relative(signature.path), signature);
+        }
+        const currentByFile = await collectCurrentSqliteArtifactSignatures();
+        const changedFiles = [];
+        for (const [file, currentSignature] of currentByFile.entries()) {
+            const storedSignature = storedByFile.get(file);
+            if (!storedSignature) {
+                changedFiles.push(file);
+                continue;
+            }
+            if (storedSignature.size !== currentSignature.size || storedSignature.mtimeMs !== currentSignature.mtimeMs) {
+                changedFiles.push(file);
+            }
+        }
+        for (const file of storedByFile.keys()) {
+            if (currentByFile.has(file))
+                continue;
+            changedFiles.push(file);
+        }
+        if (!changedFiles.length)
+            return { state: "fresh" };
+        return staleFreshness(changedFiles, "SQLite artifact is older than files on disk");
+    };
+    const collectMcpDependencyEntries = async (request, collectEntries) => {
+        const snapshot = await session.loadProject({ symbolGraph: "skip" });
+        const limit = boundedLimit(request.limit, DEFAULT_MCP_COLLECTION_LIMIT, MAX_MCP_COLLECTION_LIMIT);
+        const queryOptions = {
+            ...(request.depth !== undefined ? { depth: request.depth } : {}),
+            // Probe one entry past the display limit so `truncated` is exact
+            // rather than a `results.length === limit` heuristic (which cannot
+            // tell "exactly limit reachable files" apart from "more exist"),
+            // without re-walking the whole reachable graph for an exact total -
+            // see finding #44.
+            limit: limit + 1,
+        };
+        const resolvedSymbol = resolveSemanticSymbol(snapshot, request.file);
+        let targetFile;
+        if (resolvedSymbol) {
+            targetFile = resolvedSymbol.def.file;
+        }
+        else if (parseAgentSymbolHandle(request.file) || parseQualifiedSymbolPath(request.file)) {
+            targetFile = requireSemanticSymbol(snapshot, request.file).def.file;
+        }
+        else {
+            targetFile = await resolveProjectFile(await realRoot, root, request.file);
+        }
+        const collected = collectEntries(snapshot.fileGraph, targetFile, queryOptions);
+        const { items, omitted } = boundList(collected, limit);
+        const entries = items.map((dependency) => ({
+            file: relative(dependency.file),
+            depth: dependency.depth,
+        }));
+        return {
+            entries,
+            limit,
+            totalSeen: collected.length,
+            truncated: Boolean(omitted),
+            omitted,
+        };
+    };
+    const calls = async (request) => {
+        const findCalls = request.direction === "callers" ? findCallersWithSession : findCalleesWithSession;
+        return await findCalls(session, {
+            root,
+            handle: request.handle,
+            ...(request.depth !== undefined ? { depth: request.depth } : {}),
+            limit: boundedLimit(request.limit, DEFAULT_CALL_HIERARCHY_LIMIT, MAX_CALL_HIERARCHY_LIMIT),
+            ...(request.includeHeuristic !== undefined ? { includeHeuristic: request.includeHeuristic } : {}),
+        });
+    };
+    const typeHierarchy = async (request) => {
+        const findTypes = request.direction === "supertypes" ? findSupertypesWithSession : findSubtypesWithSession;
+        return await findTypes(session, {
+            root,
+            handle: request.handle,
+            ...(request.depth !== undefined ? { depth: request.depth } : {}),
+            limit: boundedLimit(request.limit, DEFAULT_TYPE_HIERARCHY_LIMIT, MAX_TYPE_HIERARCHY_LIMIT),
+        });
+    };
+    const boundedReferencesFromResult = (result, limit) => {
+        if (result.status !== "ok") {
+            return { references: [], limit, totalSeen: 0, truncated: false, omitted: 0 };
+        }
+        const { items, omitted } = boundList(result.references, limit);
+        const references = items.map((reference) => ({ file: relative(reference.file), range: reference.range }));
+        return {
+            references,
+            limit,
+            totalSeen: result.references.length,
+            truncated: Boolean(omitted),
+            omitted,
+        };
+    };
+    const fileDeps = async (request) => await withFreshness(async () => {
+        const { entries, ...meta } = await collectMcpDependencyEntries(request, request.direction === "deps" ? getDependencies : getReverseDependencies);
+        return request.direction === "deps"
+            ? { dependencies: entries, ...meta }
+            : { reverseDependencies: entries, ...meta };
+    });
+    const searchHandlers = {
+        search: async (request) => await withFreshness(async () => await searchCodegraphWithSession(session, {
+            root,
+            query: request.query,
+            ...(request.mode !== undefined ? { mode: request.mode } : {}),
+            ...(request.from !== undefined ? { from: request.from } : {}),
+            ...(request.depth !== undefined ? { depth: request.depth } : {}),
+            ...(request.limit !== undefined ? { limit: request.limit } : {}),
+        })),
+        workspace_symbols: async (request) => await workspaceSymbolsWithSession(session, {
+            root,
+            query: request.query,
+            ...(request.kinds !== undefined ? { kinds: request.kinds } : {}),
+            ...(request.exportedOnly !== undefined ? { exportedOnly: request.exportedOnly } : {}),
+            ...(request.includeImports !== undefined ? { includeImports: request.includeImports } : {}),
+            ...(request.fileGlob !== undefined ? { fileGlob: request.fileGlob } : {}),
+            limit: boundedLimit(request.limit, DEFAULT_WORKSPACE_SYMBOL_LIMIT, MAX_WORKSPACE_SYMBOL_LIMIT),
+        }),
+        rename_preview: async (request) => await previewRenameWithSession(session, {
+            root,
+            handle: request.handle,
+            newName: request.newName,
+            ...(request.includeComments !== undefined ? { includeComments: request.includeComments } : {}),
+            ...(request.includeStrings !== undefined ? { includeStrings: request.includeStrings } : {}),
+            ...(request.includeFilenames !== undefined ? { includeFilenames: request.includeFilenames } : {}),
+            ...(request.maxEdits !== undefined ? { maxEdits: request.maxEdits } : {}),
+        }),
+        refactor_plan: async (request) => await buildRefactorPlanWithSession(session, {
+            root,
+            handle: request.handle,
+            ...(request.renameTo !== undefined ? { renameTo: request.renameTo } : {}),
+            ...(request.maxReferences !== undefined ? { maxReferences: request.maxReferences } : {}),
+            ...(request.maxCallers !== undefined ? { maxCallers: request.maxCallers } : {}),
+            ...(request.maxHierarchy !== undefined ? { maxHierarchy: request.maxHierarchy } : {}),
+            ...(request.includeSource !== undefined ? { includeSource: request.includeSource } : {}),
+        }),
+        calls,
+        type_hierarchy: typeHierarchy,
+        file_deps: fileDeps,
+        callers: async (request) => await calls({ direction: "callers", ...request }),
+        callees: async (request) => await calls({ direction: "callees", ...request }),
+        supertypes: async (request) => await typeHierarchy({ direction: "supertypes", ...request }),
+        subtypes: async (request) => await typeHierarchy({ direction: "subtypes", ...request }),
+        implementations: async (request) => await findImplementationsWithSession(session, {
+            root,
+            handle: request.handle,
+            limit: boundedLimit(request.limit, DEFAULT_TYPE_HIERARCHY_LIMIT, MAX_TYPE_HIERARCHY_LIMIT),
+        }),
+    };
+    const navigationHandlers = {
+        explore: async (request) => await withFreshness(async () => await exploreCodegraphWithSession(session, {
+            root,
+            query: request.query,
+            ...(request.limit !== undefined ? { limit: request.limit } : {}),
+            ...(request.maxPackets !== undefined ? { maxPackets: request.maxPackets } : {}),
+            ...(request.maxPaths !== undefined ? { maxPaths: request.maxPaths } : {}),
+            ...(request.includeSource !== undefined ? { includeSource: request.includeSource } : {}),
+        })),
+        orient: async (request) => await withFreshness(async () => await orientCodegraphWithSession(session, {
+            root,
+            ...(request.includeRoots !== undefined ? { includeRoots: request.includeRoots } : {}),
+            ...(request.budget !== undefined ? { budget: request.budget } : {}),
+        })),
+        packet_get: async (request) => await withFreshness(async () => await getCodegraphPacketWithSession(session, {
+            root,
+            target: request.target,
+            ...(request.maxSymbols !== undefined ? { maxSymbols: request.maxSymbols } : {}),
+            ...(request.maxSnippets !== undefined ? { maxSnippets: request.maxSnippets } : {}),
+            ...(request.maxDuplicates !== undefined ? { maxDuplicates: request.maxDuplicates } : {}),
+        })),
+        get_file: async (request) => await getCodegraphFileViewWithSession(session, {
+            root,
+            file: request.file,
+            ...(request.offset !== undefined ? { offset: request.offset } : {}),
+            ...(request.limit !== undefined ? { limit: request.limit } : {}),
+            ...(request.maxBytes !== undefined ? { maxBytes: request.maxBytes } : {}),
+            ...(request.includeGraphContext !== undefined ? { includeGraphContext: request.includeGraphContext } : {}),
+            ...(request.allowSensitive !== undefined ? { allowSensitive: request.allowSensitive } : {}),
+            ...(options.buildOptions ? { buildOptions: options.buildOptions } : {}),
+        }),
+        get_symbol: async (request) => await withFreshness(async () => {
+            const explanation = await explainCodegraphTargetWithSession(session, { root, target: request.handle });
+            return explanation.target;
+        }),
+        goto: async (request) => await withFreshness(async () => {
+            const snapshot = await session.loadProject({ symbolGraph: "skip" });
+            if ("handle" in request) {
+                const resolved = requireSemanticSymbol(snapshot, request.handle);
+                return { status: "ok", definition: resolved.def };
+            }
+            return await goToDefinition(snapshot.index, {
+                file: await resolveProjectFile(await realRoot, root, request.file),
+                line: request.line,
+                column: request.column,
+            });
+        }),
+        refs: async (request) => await withFreshness(async () => {
+            const handle = "handle" in request ? request.handle : undefined;
+            const file = "file" in request ? request.file : undefined;
+            const line = "line" in request ? request.line : undefined;
+            const column = "column" in request ? request.column : undefined;
+            const hasAnyPosition = file !== undefined || line !== undefined || column !== undefined;
+            const hasCompletePosition = file !== undefined && line !== undefined && column !== undefined;
+            if (handle !== undefined && hasAnyPosition) {
+                throw new Error("refs requires either handle or file, line, and column.");
+            }
+            if (handle === undefined && !hasCompletePosition) {
+                throw new Error("refs requires either handle or file, line, and column.");
+            }
+            const limit = boundedLimit(request.limit, DEFAULT_MCP_COLLECTION_LIMIT, MAX_MCP_COLLECTION_LIMIT);
+            if (handle !== undefined) {
+                if (parseQualifiedSymbolPath(handle)) {
+                    const snapshot = await session.loadProject({ symbolGraph: "skip" });
+                    const resolved = requireSemanticSymbol(snapshot, handle);
+                    // Probe one reference past the display limit so `truncated` is exact - see
+                    // `collectMcpDependencyEntries` for the rationale (finding #44).
+                    const result = await findReferences(snapshot.index, { def: resolved.def }, { maxReferences: limit + 1 });
+                    return boundedReferencesFromResult(result, limit);
+                }
+                const explanation = await explainCodegraphTargetWithSession(session, {
+                    root,
+                    target: handle,
+                    maxReferences: limit,
+                });
+                return {
+                    references: explanation.references,
+                    limit: explanation.limits.references,
+                    totalSeen: explanation.references.length + explanation.omittedCounts.references,
+                    truncated: explanation.omittedCounts.references > 0,
+                    omitted: explanation.omittedCounts.references,
+                };
+            }
+            if (file === undefined || line === undefined || column === undefined) {
+                throw new Error("refs requires either handle or file, line, and column.");
+            }
+            const snapshot = await session.loadProject({ symbolGraph: "skip" });
+            const result = await findReferences(snapshot.index, {
+                file: await resolveProjectFile(await realRoot, root, file),
+                line,
+                column,
+            }, { maxReferences: limit + 1 });
+            return boundedReferencesFromResult(result, limit);
+        }),
+        deps: async (request) => await withFreshness(async () => {
+            const { entries, ...meta } = await collectMcpDependencyEntries(request, getDependencies);
+            return { dependencies: entries, ...meta };
+        }),
+        rdeps: async (request) => await withFreshness(async () => {
+            const { entries, ...meta } = await collectMcpDependencyEntries(request, getReverseDependencies);
+            return { reverseDependencies: entries, ...meta };
+        }),
+        path: async (request) => await withFreshness(async () => {
+            const snapshot = await session.loadProject({ symbolGraph: "skip" });
+            const result = getShortestPath(snapshot.fileGraph, await resolveProjectFile(await realRoot, root, request.from), await resolveProjectFile(await realRoot, root, request.to));
+            return {
+                path: result ? result.map(relative) : null,
+            };
+        }),
+    };
+    const reviewHandlers = {
+        impact: async (request) => await withFreshness(async () => {
+            const snapshot = await session.loadProject({ symbolGraph: "skip" });
+            return (await analyzeImpactFromDiff(root, snapshot.index, {
+                ...options.buildOptions,
+                provider: "git",
+                base: request.base,
+                head: request.head,
+                cwd: root,
+                compact: true,
+                depth: 2,
+                maxRefs: 200,
+                ...DEFAULT_BOUNDED_IMPACT_BUDGETS,
+            }));
+        }),
+        review: async (request) => await withFreshness(async () => {
+            const report = await buildReviewReport(root, {
+                ...options.buildOptions,
+                gitBase: request.base,
+                gitHead: request.head,
+                ...(request.reviewDepth !== undefined ? { reviewDepth: request.reviewDepth } : {}),
+            }, {
+                ...(session.loadProject
+                    ? {
+                        loadIndex: async () => (await session.loadProject({ symbolGraph: "skip" })).index,
+                    }
+                    : {}),
+                ...(session.loadDuplicateAnalysis ? { loadDuplicateAnalysis: session.loadDuplicateAnalysis } : {}),
+            });
+            // MCP is a bounded transport (finding #45); library callers that need the
+            // complete, unbounded report should call `buildReviewReport` directly.
+            return boundReviewReportForTransport(report);
+        }),
+    };
+    const artifactHandlers = {
+        query_sqlite: async (request, executionOptions) => {
+            if (!sqlitePath) {
+                throw new Error("No SQLite artifact is available. Run artifact_build first or pass artifactPath.");
+            }
+            assertMcpSqliteQueryResourceBounded(request.query);
+            // The artifact's own baseline decides whether the query can be served; session freshness
+            // only decides whether an automatic rebuild is safe. A fresh artifact is served even when
+            // the in-memory session snapshot is stale, and an unsafe session refresh burst blocks the
+            // automatic rebuild instead of silently rebuilding from stale in-memory state.
+            let realSqlitePath = await assertRealPathCandidateWithinRoot(await realRoot, sqlitePath, "SQLite artifact");
+            let artifactFreshness = await checkSqliteArtifactFreshness(realSqlitePath);
+            if (artifactFreshness.state !== "fresh") {
+                const sessionFreshness = await checkMcpFreshness();
+                if (sessionFreshness.state === "stale") {
+                    throw new Error(formatSqliteFreshnessError(sessionFreshness));
+                }
+                artifactFreshness = await refreshSqliteArtifactForQuery(artifactFreshness, { allowStaleRebuild: true });
+                realSqlitePath = await assertRealPathCandidateWithinRoot(await realRoot, sqlitePath, "SQLite artifact");
+            }
+            const result = await queryGraphSqliteRaw(realSqlitePath, request.query, request.params ?? [], {
+                maxRows: normalizeSqliteRowLimit(request.limit),
+                maxBytes: DEFAULT_SQLITE_BYTE_LIMIT,
+                ...(executionOptions?.signal ? { signal: executionOptions.signal } : {}),
+            });
+            return { ...result, truncated: Boolean(result.truncated), freshness: artifactFreshness };
+        },
+        refresh_index: async (request) => await withArtifactWriteLock(async () => {
+            const warmup = request.warmup ?? "off";
+            const previousRefresh = refreshPromise;
+            const refresh = (async () => {
+                if (previousRefresh)
+                    await previousRefresh.catch(() => undefined);
+                ++refreshEpoch;
+                session.invalidate();
+                sqlitePath = configuredSqlitePath;
+                sqliteOutDir = configuredSqliteOutDir;
+                sqliteCanRefresh = configuredSqliteCanRefresh;
+                await startCodegraphMcpWarmup(session, warmup);
+            })();
+            refreshPromise = refresh;
+            try {
+                await refresh;
+            }
+            finally {
+                if (refreshPromise === refresh)
+                    refreshPromise = undefined;
+            }
+            return { refreshed: true, warmup };
+        }),
+        artifact_build: async (request) => await withArtifactWriteLock(async () => {
+            if (readOnly) {
+                throw new Error("artifact_build is disabled in read-only MCP mode.");
+            }
+            const freshness = await checkMcpFreshness();
+            if (freshness.state === "stale") {
+                const changed = freshness.changedFiles.length ? ` Changed files: ${freshness.changedFiles.join(", ")}.` : "";
+                const omitted = freshness.omittedChangedFileCount
+                    ? ` Omitted changed files: ${freshness.omittedChangedFileCount}.`
+                    : "";
+                throw new Error(`Cannot build artifacts from a stale MCP index; run refresh_index first. ${freshness.reason}.${changed}${omitted}`);
+            }
+            const outDir = request.outDir !== undefined
+                ? await assertWritableDirectoryRealPathWithinRoot(await realRoot, root, request.outDir, "Artifact output directory")
+                : undefined;
+            const result = await buildCodegraphArtifactWithSession(session, {
+                root,
+                ...(outDir !== undefined ? { outDir } : {}),
+                ...(request.outDir !== undefined ? { filterOutDir: request.outDir } : {}),
+                ...(request.sqlite !== undefined ? { sqlite: request.sqlite } : {}),
+                ...(request.graphJson !== undefined ? { graphJson: request.graphJson } : {}),
+                ...(request.report !== undefined ? { report: request.report } : {}),
+                ...(request.questions !== undefined ? { questions: request.questions } : {}),
+                ...(request.force !== undefined ? { force: request.force } : {}),
+            });
+            const sqliteArtifact = result.artifacts.sqlite;
+            if (sqliteArtifact) {
+                sqlitePath = path.join(result.outDir, sqliteArtifact);
+                sqliteOutDir = result.outDir;
+                sqliteCanRefresh = true;
+            }
+            return { ...result, freshness };
+        }),
+        dispose: () => {
+            if (!options.session)
+                session.invalidate();
+        },
+    };
+    return {
+        ...searchHandlers,
+        ...navigationHandlers,
+        ...reviewHandlers,
+        ...artifactHandlers,
+    };
+}
+//# sourceMappingURL=handlers.js.map