@vizalice/codegraph 1.5.0

package/dist/mcp/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/mcp/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAYtC,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;GAKG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,EAAE,CAA0B;IACpC,OAAO,CAAC,WAAW,CAAc;IAIjC,OAAO,CAAC,WAAW,CAAuB;IAE1C,OAAO,CAAC,WAAW,CAA8B;IACjD,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,IAAI,CAA6B;IACzC,OAAO,CAAC,MAAM,CAAS;IAGvB,OAAO,CAAC,SAAS,CAA0B;gBAE/B,IAAI,GAAE,gBAAqB;IAKvC;;;;;OAKG;IACH,OAAO,CAAC,cAAc;IAkBtB;;;;;OAKG;IACH,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAK7C,0EAA0E;IAC1E,cAAc,IAAI,MAAM,GAAG,IAAI;IAI/B,yEAAyE;IACzE,cAAc,IAAI,WAAW;IAI7B,uDAAuD;IACvD,mBAAmB,IAAI,OAAO;IAI9B;;;;;;;;OAQG;IACG,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAmB1D;;;;OAIG;IACH,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAuB7C;;;OAGG;IACH,IAAI,IAAI,IAAI;YAiBE,YAAY;IAuB1B;;;;;;OAMG;IACH,OAAO,CAAC,aAAa;IAuDrB;;;;;;;;;OASG;IACH,OAAO,CAAC,WAAW;CAiBpB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAM5E"}

package/dist/mcp/engine.js

@@ -0,0 +1,350 @@
+"use strict";
+/**
+ * MCP shared engine — the heavyweight, *shared* state for an MCP server:
+ * the project's {@link CodeGraph} instance, file watcher, and the
+ * {@link ToolHandler} cache for cross-project queries.
+ *
+ * One engine, many sessions:
+ * - direct mode (single stdio session) instantiates one engine + one session;
+ * - daemon mode instantiates one engine and a new session per socket
+ *   connection. Every session reads from the same SQLite WAL and the same
+ *   inotify watch set — that's the entire point of issue #411.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MCPEngine = void 0;
+exports.parseDebounceEnv = parseDebounceEnv;
+const os = __importStar(require("os"));
+const directory_1 = require("../directory");
+const sync_1 = require("../sync");
+const tools_1 = require("./tools");
+const query_pool_1 = require("./query-pool");
+// Lazy-load the heavy CodeGraph chain (sqlite + query/graph/context layers) OFF
+// the MCP startup path. It's only needed once a tool actually opens a project —
+// not to answer initialize/tools-list — so deferring it lets `serve --mcp` (and
+// the daemon it spawns) bind + register tools in ~Node-startup time instead of
+// ~800ms, closing the "No such tool available" cold-start race that made headless
+// agents flounder. require() is sync + cached on the CommonJS build.
+const loadCodeGraph = () => require('../index').default;
+/**
+ * Shared MCP engine. Thread-safe in the sense that multiple sessions can
+ * call its methods concurrently — internally it serializes initialization
+ * through a single promise so multiple sessions racing each other on first
+ * connect never double-open the SQLite file.
+ */
+class MCPEngine {
+    cg = null;
+    toolHandler;
+    // Project root we resolved to. Null until `ensureInitialized` succeeds
+    // (or null forever if no .codegraph/ ever turned up — that's a valid
+    // state for the engine, since cross-project queries still work).
+    projectPath = null;
+    // Set on first `ensureInitialized` so subsequent sessions don't redo work.
+    initPromise = null;
+    watcherStarted = false;
+    opts;
+    closed = false;
+    // Off-loop read-tool pool (daemon mode only). Created lazily once the default
+    // project is open — workers each hold their own WAL read connection.
+    queryPool = null;
+    constructor(opts = {}) {
+        this.opts = { watch: opts.watch ?? true, queryPool: opts.queryPool ?? false };
+        this.toolHandler = new tools_1.ToolHandler(null);
+    }
+    /**
+     * Start the worker-thread query pool once a default project is open (daemon
+     * mode only; honors `CODEGRAPH_QUERY_POOL_SIZE`). Idempotent and best-effort:
+     * if workers can't spawn on this platform the ToolHandler keeps serving reads
+     * in-process, so the pool can only help, never break, tool calls.
+     */
+    maybeStartPool(root) {
+        if (!this.opts.queryPool || this.queryPool || this.closed)
+            return;
+        const size = (0, query_pool_1.resolvePoolSize)(process.env.CODEGRAPH_QUERY_POOL_SIZE, os.cpus().length);
+        if (size <= 0) {
+            process.stderr.write('[CodeGraph MCP] Query pool disabled (CODEGRAPH_QUERY_POOL_SIZE=0); serving reads in-process.\n');
+            return;
+        }
+        try {
+            this.queryPool = new query_pool_1.QueryPool({ root, size });
+            this.toolHandler.setQueryPool(this.queryPool);
+            process.stderr.write(`[CodeGraph MCP] Query pool: up to ${size} worker thread(s) for concurrent reads.\n`);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`[CodeGraph MCP] Query pool unavailable (${msg}); serving reads in-process.\n`);
+            this.queryPool = null;
+        }
+    }
+    /**
+     * Convenience for {@link MCPServer} compatibility: pre-seed an explicit
+     * project path (from the `--path` CLI flag) without yet opening it. This
+     * keeps the synchronous constructor cheap; the actual open happens on the
+     * first `ensureInitialized` call.
+     */
+    setProjectPathHint(projectPath) {
+        this.projectPath = projectPath;
+        this.toolHandler.setDefaultProjectHint(projectPath);
+    }
+    /** Project root that the engine resolved on first init (null if none). */
+    getProjectPath() {
+        return this.projectPath;
+    }
+    /** Shared ToolHandler — sessions delegate tool dispatch through this. */
+    getToolHandler() {
+        return this.toolHandler;
+    }
+    /** Whether the default project's CodeGraph is open. */
+    hasDefaultCodeGraph() {
+        return this.toolHandler.hasDefaultCodeGraph();
+    }
+    /**
+     * Walk up from `searchFrom` to find the nearest `.codegraph/` and open it.
+     * Idempotent: concurrent callers share one in-flight init; subsequent
+     * callers after success are no-ops.
+     *
+     * The original `MCPServer.tryInitializeDefault` carried the same retry-on-
+     * subsequent-tool-call semantics; we preserve them by NOT throwing when the
+     * search misses (just leaves `cg` null so the next call can retry).
+     */
+    async ensureInitialized(searchFrom) {
+        if (this.closed)
+            return;
+        if (this.toolHandler.hasDefaultCodeGraph())
+            return;
+        if (this.initPromise) {
+            try {
+                await this.initPromise;
+            }
+            catch { /* let caller retry */ }
+            return;
+        }
+        this.initPromise = this.doInitialize(searchFrom).finally(() => {
+            this.initPromise = null;
+        });
+        try {
+            await this.initPromise;
+        }
+        catch {
+            // Init errors are logged inside `doInitialize`; falling through here
+            // matches MCPServer's previous "retry on next tool call" behavior.
+        }
+    }
+    /**
+     * Synchronous last-resort init used by the per-session retry loop when the
+     * background `ensureInitialized` already finished (or failed) and we need
+     * to pick up a project that appeared *after* the engine started.
+     */
+    retryInitializeSync(searchFrom) {
+        if (this.closed)
+            return;
+        if (this.toolHandler.hasDefaultCodeGraph())
+            return;
+        this.toolHandler.setDefaultProjectHint(searchFrom);
+        const resolvedRoot = (0, directory_1.findNearestCodeGraphRoot)(searchFrom);
+        if (!resolvedRoot)
+            return;
+        try {
+            // Close any previously failed instance to avoid leaking resources.
+            if (this.cg) {
+                try {
+                    this.cg.close();
+                }
+                catch { /* ignore */ }
+                this.cg = null;
+            }
+            this.cg = loadCodeGraph().openSync(resolvedRoot);
+            this.projectPath = resolvedRoot;
+            this.toolHandler.setDefaultCodeGraph(this.cg);
+            this.startWatching();
+            this.catchUpSync();
+            this.maybeStartPool(resolvedRoot);
+        }
+        catch {
+            // Still failing — caller will try again on the next tool call.
+        }
+    }
+    /**
+     * Close everything. Used on graceful daemon shutdown (SIGTERM/idle timeout)
+     * and on direct-mode stop. Idempotent.
+     */
+    stop() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        // Detach + terminate the worker pool first so no tool call routes to a
+        // worker mid-teardown; outstanding pool calls resolve with graceful guidance.
+        this.toolHandler.setQueryPool(null);
+        if (this.queryPool) {
+            void this.queryPool.destroy();
+            this.queryPool = null;
+        }
+        this.toolHandler.closeAll();
+        if (this.cg) {
+            try {
+                this.cg.close();
+            }
+            catch { /* ignore */ }
+            this.cg = null;
+        }
+    }
+    async doInitialize(searchFrom) {
+        this.toolHandler.setDefaultProjectHint(searchFrom);
+        const resolvedRoot = (0, directory_1.findNearestCodeGraphRoot)(searchFrom);
+        if (!resolvedRoot) {
+            // No .codegraph/ above searchFrom. Sessions may still discover one later via roots/list
+            this.projectPath = searchFrom;
+            return;
+        }
+        this.projectPath = resolvedRoot;
+        try {
+            this.cg = await loadCodeGraph().open(resolvedRoot);
+            this.toolHandler.setDefaultCodeGraph(this.cg);
+            this.startWatching();
+            this.catchUpSync();
+            this.maybeStartPool(resolvedRoot);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`[CodeGraph MCP] Failed to open project at ${resolvedRoot}: ${msg}\n`);
+        }
+    }
+    /**
+     * Start file watching on the active CodeGraph instance. Idempotent — the
+     * watcher is per-engine, not per-session, which is why the daemon path
+     * collapses N inotify sets to one. The wording of the disabled-reason log
+     * exactly matches the prior in-tree implementation so log-driven dashboards
+     * keep working.
+     */
+    startWatching() {
+        if (!this.cg || this.watcherStarted || !this.opts.watch)
+            return;
+        const disabledReason = (0, sync_1.watchDisabledReason)(this.projectPath ?? process.cwd());
+        if (disabledReason) {
+            process.stderr.write(`[CodeGraph MCP] File watcher disabled — ${disabledReason}. ` +
+                `The graph will not auto-update; run \`codegraph sync\` (or install the git sync hooks via \`codegraph init\`) to refresh.\n`);
+            this.watcherStarted = true;
+            return;
+        }
+        // Optional override for the debounce window via env var (issue #403).
+        // Useful for workspaces with bursty writes (formatter-on-save chains,
+        // large generated outputs) where the 2s default fires too often. Clamped
+        // to [100ms, 60s]; out-of-range / non-numeric values fall back to the
+        // FileWatcher default. We log the active value so it's discoverable.
+        const debounceMs = parseDebounceEnv(process.env.CODEGRAPH_WATCH_DEBOUNCE_MS);
+        if (debounceMs !== undefined) {
+            process.stderr.write(`[CodeGraph MCP] File watcher debounce: ${debounceMs}ms (CODEGRAPH_WATCH_DEBOUNCE_MS)\n`);
+        }
+        const started = this.cg.watch({
+            debounceMs,
+            onSyncComplete: (result) => {
+                if (result.filesChanged > 0) {
+                    process.stderr.write(`[CodeGraph MCP] Auto-synced ${result.filesChanged} file(s) in ${result.durationMs}ms\n`);
+                }
+            },
+            onSyncError: (err) => {
+                process.stderr.write(`[CodeGraph MCP] Auto-sync error: ${err.message}\n`);
+            },
+            onDegraded: (reason) => {
+                // Live watching gave up permanently (watch-resource exhaustion or a
+                // write lock held past the retry budget). Say so loudly and ONCE — the
+                // graph will no longer auto-update, so a long-running MCP session must
+                // not keep assuming it's fresh. The reason already names the remedy
+                // (`codegraph sync` / git sync hooks).
+                process.stderr.write(`[CodeGraph MCP] File watcher degraded — ${reason}\n`);
+            },
+        });
+        this.watcherStarted = true;
+        if (started) {
+            process.stderr.write('[CodeGraph MCP] File watcher active — graph will auto-sync on changes\n');
+        }
+        else {
+            process.stderr.write('[CodeGraph MCP] File watcher unavailable on this platform — run `codegraph sync` to refresh the graph after changes.\n');
+        }
+    }
+    /**
+     * Reconcile the index with the current filesystem once, right after open —
+     * catches edits, adds, deletes, and `git pull`/`checkout` changes made while
+     * no watcher was running. Runs in the background, but the returned promise
+     * is pushed into the ToolHandler as a one-shot gate so the *first* tool
+     * call awaits completion before serving (without this, a tool call that
+     * races past sync returns rows for files that no longer exist on disk —
+     * and the per-file staleness banner can't help because `getPendingFiles()`
+     * is populated by the watcher, not by catch-up).
+     */
+    catchUpSync() {
+        const cg = this.cg;
+        if (!cg)
+            return;
+        const p = cg
+            .sync()
+            .then((result) => {
+            const changed = result.filesAdded + result.filesModified + result.filesRemoved;
+            if (changed > 0) {
+                process.stderr.write(`[CodeGraph MCP] Caught up ${changed} file(s) changed since last run\n`);
+            }
+        })
+            .catch((err) => {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`[CodeGraph MCP] Catch-up sync failed: ${msg}\n`);
+        });
+        this.toolHandler.setCatchUpGate(p);
+    }
+}
+exports.MCPEngine = MCPEngine;
+/**
+ * Parse and clamp the CODEGRAPH_WATCH_DEBOUNCE_MS env override.
+ *
+ * Issue #403: workspaces with bursty writes (formatter-on-save, multi-file
+ * refactors) sometimes want a longer quiet window before sync. Returns
+ * `undefined` for unset / empty / non-numeric / out-of-range values so the
+ * FileWatcher default (2000ms) takes over — never throws.
+ *
+ * Clamp range: 100ms (faster would mean a sync per keystroke) to 60s (longer
+ * and the watcher feels broken). Out-of-range values are treated as "ignore
+ * this misconfiguration" rather than capped, since silently capping a 0 or
+ * a typoed value would mask a real config bug.
+ */
+function parseDebounceEnv(raw) {
+    if (!raw || !raw.trim())
+        return undefined;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || !Number.isInteger(n))
+        return undefined;
+    if (n < 100 || n > 60000)
+        return undefined;
+    return n;
+}
+//# sourceMappingURL=engine.js.map

package/dist/mcp/engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.js","sourceRoot":"","sources":["../../src/mcp/engine.ts"],"names":[],"mappings":"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"}

package/dist/mcp/explore-dedup.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Cross-call source dedup for `codegraph_explore` (CG-18).
+ *
+ * The session record (CG-17) knows what earlier calls already sent. This module
+ * is the algebra that turns that record into a decision for the call being
+ * rendered: of the line ranges this call WOULD emit, which does the agent
+ * already hold, and what is genuinely new.
+ *
+ * Three rules shape everything here, and all three come from the same place —
+ * an insufficient-feeling response is what sends an agent to Read, and one or
+ * two of those early in a session teach it to abandon codegraph entirely
+ * (CLAUDE.md):
+ *
+ *   1. **A pointer, never a bare omission.** Removed source is replaced by a
+ *      back-reference naming the file, the symbols, and the line span, worded so
+ *      it is unmistakable that the source was already delivered IN THIS
+ *      CONVERSATION and is still current. Silence reads as "codegraph didn't
+ *      find it".
+ *   2. **Only prove-it dedup.** A span is withheld only when the file's bytes
+ *      are byte-identical to what was served (a content fingerprint, not an
+ *      mtime and not the index's drift flag). An edit between calls means the
+ *      agent's copy is wrong, so the source is re-emitted in full.
+ *   3. **Cut chunks, not slivers.** Only a covered run of at least
+ *      {@link EXPLORE_DEDUP.MIN_COVERED_LINES} lines is worth replacing. Below
+ *      that the pointer costs more than the source, and shattering a block into
+ *      one-line fragments produces exactly the ragged output that reads as a
+ *      failure. Everything not withheld is emitted — where the algebra is
+ *      unsure, it re-serves.
+ *
+ * Which way to be wrong, restated for this layer: re-serving something the agent
+ * has is a few hundred wasted chars; withholding something it never saw is a
+ * Read. Every threshold below leans to the first.
+ */
+import type { ExploreLineRange, ExploreProjectState } from './explore-session-state';
+export declare const EXPLORE_DEDUP: {
+    /**
+     * Shortest already-served run that may be replaced by a back-reference.
+     *
+     * Sized against what dedup is actually FOR — a later call re-serving a whole
+     * method or file it already sent. A shorter covered run is either a signature
+     * line in a skeleton render or the ±3 lines of context padding around a
+     * cluster, and swapping either for a pointer trades bytes for noise: the
+     * pointer sentence is itself ~140 chars, so under this length dedup would
+     * make the response BIGGER while making it read as full of holes.
+     */
+    readonly MIN_COVERED_LINES: 8;
+    /**
+     * Below this many chars of NEW source, a file's remainder is folded into its
+     * back-reference instead of being fenced on its own.
+     *
+     * The shape this exists for, seen on the CG-17 fixture: a third call whose
+     * only unheld line was the file's trailing blank one, rendered as a code fence
+     * containing `228\t`. A fence holding two lines of nothing reads as a broken
+     * response, and reading as broken is the expensive failure — it is the thing
+     * that sends an agent to Read and keeps it there. So a remainder this small is
+     * dropped rather than shown. It is the one place this module withholds
+     * something the agent has not seen, and it is bounded to ~two lines that sit
+     * directly against source the agent does hold; the file is still named, with
+     * its symbols, so one follow-up explore fetches it whole.
+     */
+    readonly MIN_DELTA_CHARS: 160;
+    /** Line spans named in one pointer before it summarises the rest. */
+    readonly MAX_SPANS_IN_POINTER: 4;
+    /** Symbols named in one pointer before it summarises the rest. */
+    readonly MAX_SYMBOLS_IN_POINTER: 5;
+};
+/**
+ * Kill switch: `CODEGRAPH_EXPLORE_DEDUP=0` renders every call as if the session
+ * had no history. Read per call (not memoized) so a test can toggle it.
+ */
+export declare function exploreDedupEnabled(): boolean;
+/**
+ * Identity of the bytes a call served for one file.
+ *
+ * This — not the index's drift flag — is what gates dedup. `isFileStaleOnDisk`
+ * answers "did the file change since the last INDEX SYNC", which is a different
+ * question with a different answer: two calls inside one drift window served the
+ * same current bytes (dedup is correct), while a file edited and re-synced
+ * between two calls is never "stale" and yet the agent's copy is now wrong
+ * (dedup would be actively harmful). Length is prefixed so a hash prefix
+ * collision cannot alias two files of different size.
+ */
+export declare function fileFingerprint(content: string): string;
+/** Sort + merge overlapping/adjacent spans into the smallest equivalent set. */
+export declare function mergeRanges(ranges: ReadonlyArray<ExploreLineRange>): ExploreLineRange[];
+/** The parts of `range` that `served` covers. */
+export declare function intersectRange(range: ExploreLineRange, served: ReadonlyArray<ExploreLineRange>): ExploreLineRange[];
+/** The parts of `range` that `cut` does NOT cover. */
+export declare function subtractRange(range: ExploreLineRange, cut: ReadonlyArray<ExploreLineRange>): ExploreLineRange[];
+/** What one intended span becomes once the session's history is applied. */
+export interface RangeDedup {
+    /** Spans to render now — everything not proven-already-held. */
+    emit: ExploreLineRange[];
+    /** Spans replaced by a back-reference. */
+    covered: ExploreLineRange[];
+}
+/**
+ * Split one intended span into what to emit and what to point back at.
+ *
+ * Covered runs shorter than {@link EXPLORE_DEDUP.MIN_COVERED_LINES} are left in
+ * the emit set on purpose (rule 3 above) — so a span the agent holds "almost
+ * all of" still comes back whole rather than as a stutter of fragments around
+ * pointers.
+ */
+export declare function dedupeRange(range: ExploreLineRange, served: ReadonlyArray<ExploreLineRange>, minCovered?: number): RangeDedup;
+/**
+ * Every line span this session has already served for one file, but ONLY from
+ * calls that served the SAME BYTES.
+ *
+ * A record with no fingerprint is ignored rather than trusted: it cannot prove
+ * the agent's copy matches the file on disk now, and an unprovable match is
+ * exactly the case where re-serving is right.
+ */
+export declare function servedRangesForFile(prior: ExploreProjectState | null, filePath: string, fingerprint: string): ExploreLineRange[];
+/** `L12`, `L12-40`, capped with a `+N more` tail. */
+export declare function formatSpans(spans: ReadonlyArray<ExploreLineRange>): string;
+/**
+ * The line that replaces withheld source.
+ *
+ * It has one job: make the agent reach into its own context instead of into
+ * Read. So it carries the three things needed to find the source it already has
+ * — path, symbols, line spans — plus the two facts that make using it safe:
+ * that it came from THIS conversation, and that the file has not changed since
+ * (which is checked, not asserted — see {@link fileFingerprint}). It never says
+ * "omitted", and it never steers to Read.
+ */
+export declare function formatBackReference(filePath: string, covered: ReadonlyArray<ExploreLineRange>, symbols: ReadonlyArray<string>, opts: {
+    partial: boolean;
+}): string;
+/** Symbol names whose definitions fall inside the withheld spans. */
+export declare function symbolsInSpans(nodes: ReadonlyArray<{
+    name: string;
+    kind: string;
+    startLine: number;
+    endLine: number;
+}>, spans: ReadonlyArray<ExploreLineRange>): string[];
+//# sourceMappingURL=explore-dedup.d.ts.map

package/dist/mcp/explore-dedup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explore-dedup.d.ts","sourceRoot":"","sources":["../../src/mcp/explore-dedup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAErF,eAAO,MAAM,aAAa;IACxB;;;;;;;;;OASG;;IAEH;;;;;;;;;;;;;OAaG;;IAEH,qEAAqE;;IAErE,kEAAkE;;CAE1D,CAAC;AAIX;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,OAAO,CAI7C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED,gFAAgF;AAChF,wBAAgB,WAAW,CAAC,MAAM,EAAE,aAAa,CAAC,gBAAgB,CAAC,GAAG,gBAAgB,EAAE,CAYvF;AAED,iDAAiD;AACjD,wBAAgB,cAAc,CAC5B,KAAK,EAAE,gBAAgB,EACvB,MAAM,EAAE,aAAa,CAAC,gBAAgB,CAAC,GACtC,gBAAgB,EAAE,CAQpB;AAED,sDAAsD;AACtD,wBAAgB,aAAa,CAC3B,KAAK,EAAE,gBAAgB,EACvB,GAAG,EAAE,aAAa,CAAC,gBAAgB,CAAC,GACnC,gBAAgB,EAAE,CAYpB;AAED,4EAA4E;AAC5E,MAAM,WAAW,UAAU;IACzB,gEAAgE;IAChE,IAAI,EAAE,gBAAgB,EAAE,CAAC;IACzB,0CAA0C;IAC1C,OAAO,EAAE,gBAAgB,EAAE,CAAC;CAC7B;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,gBAAgB,EACvB,MAAM,EAAE,aAAa,CAAC,gBAAgB,CAAC,EACvC,UAAU,GAAE,MAAwC,GACnD,UAAU,CAKZ;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,mBAAmB,GAAG,IAAI,EACjC,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,GAClB,gBAAgB,EAAE,CAWpB;AAED,qDAAqD;AACrD,wBAAgB,WAAW,CAAC,KAAK,EAAE,aAAa,CAAC,gBAAgB,CAAC,GAAG,MAAM,CAM1E;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,aAAa,CAAC,gBAAgB,CAAC,EACxC,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,EAC9B,IAAI,EAAE;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,GACzB,MAAM,CAWR;AAED,qEAAqE;AACrE,wBAAgB,cAAc,CAC5B,KAAK,EAAE,aAAa,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,EACxF,KAAK,EAAE,aAAa,CAAC,gBAAgB,CAAC,GACrC,MAAM,EAAE,CAWV"}