codesift-mcp 0.14.0 → 0.15.0

package/dist/tools/symbol-reference-tools.d.ts

@@ -0,0 +1,38 @@
+import type { Reference } from "../types.js";
+/**
+ * What a reference scan actually looked at.
+ *
+ * `find_references` returning `[]` is the input to "nobody uses this, safe to rename or delete".
+ * That inference is only valid if the scan saw everywhere a reference could be. It routinely does
+ * not: generated and vendored paths are skipped by default, files can be unreadable, and per
+ * symbol the collection stops at MAX_REFERENCES. None of that was visible in the result.
+ *
+ * Filled through a caller-supplied sink so the `Record<string, Reference[]>` return shape — which
+ * several call sites slice and re-key — stays untouched.
+ */
+export interface ReferenceScanCoverage {
+    /** `unknown` is the honest default when the scan did not report — never assume `complete`. */
+    status: "complete" | "partial" | "unknown";
+    files_indexed: number;
+    files_scanned: number;
+    /** Generated/vendored paths skipped because no file_pattern was given. */
+    files_skipped_noise?: number;
+    files_unreadable?: number;
+    /** Symbols whose reference list hit MAX_REFERENCES — their counts are floors, not totals. */
+    capped_symbols?: string[];
+    detail?: string;
+}
+export interface ReferenceScanSink {
+    coverage?: ReferenceScanCoverage;
+}
+/**
+ * Batch find references for multiple symbols in one pass.
+ * Reads each file once instead of N times — critical for large repos.
+ */
+export declare function findReferencesBatch(repo: string, symbolNames: string[], filePattern?: string, sink?: ReferenceScanSink): Promise<Record<string, Reference[]>>;
+/**
+ * Find references to a symbol name across indexed files.
+ * Matches whole words only using word-boundary regex.
+ */
+export declare function findReferences(repo: string, symbolName: string, filePattern?: string): Promise<Reference[]>;
+//# sourceMappingURL=symbol-reference-tools.d.ts.map

package/dist/tools/symbol-reference-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"symbol-reference-tools.d.ts","sourceRoot":"","sources":["../../src/tools/symbol-reference-tools.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAU7C;;;;;;;;;;GAUG;AACH,MAAM,WAAW,qBAAqB;IACpC,8FAA8F;IAC9F,MAAM,EAAE,UAAU,GAAG,SAAS,GAAG,SAAS,CAAC;IAC3C,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,0EAA0E;IAC1E,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,6FAA6F;IAC7F,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,qBAAqB,CAAC;CAClC;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EAAE,EACrB,WAAW,CAAC,EAAE,MAAM,EACpB,IAAI,CAAC,EAAE,iBAAiB,GACvB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC,CA6FtC;AAiGD;;;GAGG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,SAAS,EAAE,CAAC,CAyDtB"}

package/dist/tools/symbol-reference-tools.js

@@ -0,0 +1,253 @@
+import { execFile, execFileSync } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { findReferencesLsp } from "../lsp/lsp-tools.js";
+import { matchFilePattern } from "../utils/glob.js";
+import { isNoisePath, MAX_CONTEXT_LENGTH, MAX_REFERENCES, requireCodeIndex, wordBoundaryPattern, } from "./symbol-tool-internals.js";
+/**
+ * Batch find references for multiple symbols in one pass.
+ * Reads each file once instead of N times — critical for large repos.
+ */
+export async function findReferencesBatch(repo, symbolNames, filePattern, sink) {
+    const index = await requireCodeIndex(repo);
+    const uniqueNames = [...new Set(symbolNames)];
+    const patterns = uniqueNames.map((name) => ({
+        name,
+        regex: wordBoundaryPattern(name),
+    }));
+    const result = {};
+    for (const name of uniqueNames)
+        result[name] = [];
+    let filesScanned = 0;
+    let filesSkippedNoise = 0;
+    let filesUnreadable = 0;
+    let timedOut = false;
+    const searchStart = Date.now();
+    for (const fileEntry of index.files) {
+        if (Date.now() - searchStart > SEARCH_TIMEOUT_MS) {
+            timedOut = true;
+            break;
+        }
+        if (filePattern && !matchFilePattern(fileEntry.path, filePattern))
+            continue;
+        if (!filePattern && isNoisePath(fileEntry.path)) {
+            // Sensible default — but it means "no references" really means "none outside generated
+            // and vendored code", and the caller could not tell that scoping had happened.
+            filesSkippedNoise++;
+            continue;
+        }
+        let content;
+        try {
+            content = await readFile(join(index.root, fileEntry.path), "utf-8");
+            filesScanned++;
+        }
+        catch {
+            // A reference living only in a file we could not read is invisible here, and the symbol
+            // then looks unused.
+            filesUnreadable++;
+            continue;
+        }
+        const lines = content.split("\n");
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            if (line === undefined)
+                continue;
+            for (const { name, regex } of patterns) {
+                const refs = result[name];
+                if (refs.length >= MAX_REFERENCES)
+                    continue;
+                const match = regex.exec(line);
+                if (match) {
+                    const rawContext = line.trimEnd();
+                    refs.push({
+                        file: fileEntry.path,
+                        line: i + 1,
+                        col: match.index + 1,
+                        context: rawContext.length > MAX_CONTEXT_LENGTH
+                            ? rawContext.slice(0, MAX_CONTEXT_LENGTH) + "..."
+                            : rawContext,
+                    });
+                }
+            }
+        }
+    }
+    if (sink) {
+        const capped = uniqueNames.filter((n) => (result[n]?.length ?? 0) >= MAX_REFERENCES);
+        const complete = !timedOut && filesSkippedNoise === 0 && filesUnreadable === 0 && capped.length === 0;
+        const reasons = [];
+        if (filesSkippedNoise > 0) {
+            reasons.push(`${filesSkippedNoise} generated/vendored files skipped (pass file_pattern to include them)`);
+        }
+        if (filesUnreadable > 0)
+            reasons.push(`${filesUnreadable} files could not be read`);
+        if (timedOut)
+            reasons.push(`scan exceeded ${SEARCH_TIMEOUT_MS}ms`);
+        if (capped.length > 0)
+            reasons.push(`${capped.length} symbol(s) hit the ${MAX_REFERENCES}-reference cap`);
+        sink.coverage = {
+            status: complete ? "complete" : "partial",
+            files_indexed: index.files.length,
+            files_scanned: filesScanned,
+            ...(filesSkippedNoise > 0 ? { files_skipped_noise: filesSkippedNoise } : {}),
+            ...(filesUnreadable > 0 ? { files_unreadable: filesUnreadable } : {}),
+            ...(capped.length > 0 ? { capped_symbols: capped } : {}),
+            ...(complete
+                ? {}
+                : {
+                    detail: `${reasons.join("; ")} — an empty or short result is about what was scanned, ` +
+                        `not proof the symbol is unused`,
+                }),
+        };
+    }
+    return result;
+}
+const SEARCH_TIMEOUT_MS = 30_000;
+/** Directories to exclude from ripgrep reference search */
+const RG_EXCLUDE_DIRS = [
+    "node_modules", ".git", ".next", "dist", ".codesift", "coverage",
+    ".playwright-mcp", "__pycache__", "__snapshots__",
+];
+/** Detect whether `rg` (ripgrep) is available. Cached at module level. */
+let rgAvailable = null;
+function hasRipgrep() {
+    if (rgAvailable !== null)
+        return rgAvailable;
+    try {
+        execFileSync("rg", ["--version"], { stdio: "pipe", timeout: 2000 });
+        rgAvailable = true;
+    }
+    catch {
+        rgAvailable = false;
+    }
+    return rgAvailable;
+}
+const execFileAsync = promisify(execFile);
+/**
+ * Find references using ripgrep with word-boundary matching.
+ * Returns compact `file:line: context` string when results ≤ threshold.
+ */
+async function findReferencesWithRipgrep(root, symbolName, maxResults, filePattern) {
+    const args = [
+        "-n", "--no-heading", "-F",
+        "--max-columns", String(MAX_CONTEXT_LENGTH),
+        "--max-columns-preview",
+        "--max-count", String(Math.min(maxResults * 2, 5000)),
+    ];
+    if (filePattern) {
+        args.push("--glob", filePattern);
+    }
+    else {
+        for (const dir of RG_EXCLUDE_DIRS)
+            args.push("--glob", `!${dir}`);
+        for (const ext of [".snap", ".lock", ".map", ".svg", ".png", ".jpg", ".ico", ".woff", ".woff2", ".md", ".json", ".yaml", ".yml", ".toml", ".css", ".scss", ".html"]) {
+            args.push("--glob", `!*${ext}`);
+        }
+        // Default to code files only (matches what agent would grep for)
+        args.push("--type-add", "code:*.{ts,tsx,js,jsx,py,go,rs,java,kt,kts,rb,php,vue,svelte}");
+        args.push("--type", "code");
+    }
+    args.push("--", symbolName, root);
+    let stdout;
+    try {
+        const result = await execFileAsync("rg", args, {
+            encoding: "utf-8",
+            maxBuffer: 20 * 1024 * 1024,
+            timeout: SEARCH_TIMEOUT_MS,
+        });
+        stdout = result.stdout;
+    }
+    catch (err) {
+        if (err && typeof err === "object" && "code" in err && err.code === 1)
+            return [];
+        return null;
+    }
+    const rootPrefix = root.endsWith("/") ? root : root + "/";
+    const lines = stdout.split("\n").filter(Boolean);
+    const refs = [];
+    const identifierPattern = wordBoundaryPattern(symbolName);
+    for (const rawLine of lines) {
+        if (refs.length >= maxResults)
+            break;
+        const match = rawLine.match(/^(.+?):(\d+):(.*)/);
+        if (!match || !match[1] || !match[2] || match[3] === undefined)
+            continue;
+        const absPath = match[1];
+        const relPath = absPath.startsWith(rootPrefix) ? absPath.slice(rootPrefix.length) : absPath;
+        if (!filePattern && isNoisePath(relPath))
+            continue;
+        // `rg -w` is incorrect for valid identifiers such as `$store` and `#handler`. The literal
+        // search keeps metacharacters safe; this Unicode-aware filter supplies language boundaries.
+        if (!identifierPattern.test(match[3]))
+            continue;
+        refs.push({
+            file: relPath,
+            line: parseInt(match[2], 10),
+            context: match[3].length > MAX_CONTEXT_LENGTH ? match[3].slice(0, MAX_CONTEXT_LENGTH) + "..." : match[3],
+        });
+    }
+    return refs;
+}
+/**
+ * Find references to a symbol name across indexed files.
+ * Matches whole words only using word-boundary regex.
+ */
+export async function findReferences(repo, symbolName, filePattern) {
+    // Try LSP first (type-safe, no false positives)
+    if (!filePattern) {
+        const lspRefs = await findReferencesLsp(repo, symbolName);
+        if (lspRefs !== null)
+            return lspRefs;
+    }
+    // Use ripgrep when available (10x+ faster than Node.js file walk)
+    if (!filePattern && hasRipgrep()) {
+        const index = await requireCodeIndex(repo);
+        const result = await findReferencesWithRipgrep(index.root, symbolName, MAX_REFERENCES, filePattern);
+        if (result !== null)
+            return result;
+        // Any rg failure other than its explicit no-match exit falls through to the index-backed scan.
+    }
+    // Node.js fallback
+    const index = await requireCodeIndex(repo);
+    const pattern = wordBoundaryPattern(symbolName);
+    const searchStart = Date.now();
+    const refs = [];
+    for (const fileEntry of index.files) {
+        if (refs.length >= MAX_REFERENCES)
+            break;
+        if (Date.now() - searchStart > SEARCH_TIMEOUT_MS)
+            break;
+        if (filePattern && !matchFilePattern(fileEntry.path, filePattern))
+            continue;
+        if (!filePattern && isNoisePath(fileEntry.path))
+            continue;
+        let content;
+        try {
+            content = await readFile(join(index.root, fileEntry.path), "utf-8");
+        }
+        catch {
+            continue;
+        }
+        const lines = content.split("\n");
+        for (let i = 0; i < lines.length; i++) {
+            if (refs.length >= MAX_REFERENCES)
+                break;
+            const line = lines[i];
+            if (line === undefined)
+                continue;
+            const match = pattern.exec(line);
+            if (match) {
+                const rawContext = line.trimEnd();
+                refs.push({
+                    file: fileEntry.path,
+                    line: i + 1,
+                    context: rawContext.length > MAX_CONTEXT_LENGTH
+                        ? rawContext.slice(0, MAX_CONTEXT_LENGTH) + "..."
+                        : rawContext,
+                });
+            }
+        }
+    }
+    return refs;
+}
+//# sourceMappingURL=symbol-reference-tools.js.map

package/dist/tools/symbol-reference-tools.js.map

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

package/dist/tools/symbol-tool-internals.d.ts

@@ -0,0 +1,9 @@
+import type { BM25Index } from "../search/bm25.js";
+import type { CodeIndex } from "../types.js";
+export declare const MAX_REFERENCES = 100;
+export declare const MAX_CONTEXT_LENGTH = 200;
+export declare function isNoisePath(filePath: string): boolean;
+export declare function requireCodeIndex(repo: string): Promise<CodeIndex>;
+export declare function requireBM25Index(repo: string): Promise<BM25Index>;
+export declare function wordBoundaryPattern(name: string): RegExp;
+//# sourceMappingURL=symbol-tool-internals.d.ts.map

package/dist/tools/symbol-tool-internals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"symbol-tool-internals.d.ts","sourceRoot":"","sources":["../../src/tools/symbol-tool-internals.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAG7C,eAAO,MAAM,cAAc,MAAM,CAAC;AAClC,eAAO,MAAM,kBAAkB,MAAM,CAAC;AAsBtC,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAIrD;AAED,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAMvE;AAED,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAMvE;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGxD"}

package/dist/tools/symbol-tool-internals.js

@@ -0,0 +1,47 @@
+import { getBM25Index, getCodeIndex } from "./index-tools.js";
+export const MAX_REFERENCES = 100;
+export const MAX_CONTEXT_LENGTH = 200;
+const NOISE_PATH_PREFIXES = [
+    ".next/",
+    "dist/",
+    "build/",
+    "coverage/",
+    "node_modules/",
+    "__snapshots__/",
+];
+const NOISE_EXTENSIONS = new Set([
+    ".snap",
+    ".lock",
+    ".map",
+    ".svg",
+    ".png",
+    ".jpg",
+    ".ico",
+    ".woff",
+    ".woff2",
+]);
+export function isNoisePath(filePath) {
+    if (NOISE_PATH_PREFIXES.some((prefix) => filePath.startsWith(prefix)))
+        return true;
+    const dot = filePath.lastIndexOf(".");
+    return dot >= 0 && NOISE_EXTENSIONS.has(filePath.slice(dot));
+}
+export async function requireCodeIndex(repo) {
+    const index = await getCodeIndex(repo);
+    if (!index) {
+        throw new Error(`Repository "${repo}" not found. Index it first with index_folder.`);
+    }
+    return index;
+}
+export async function requireBM25Index(repo) {
+    const index = await getBM25Index(repo);
+    if (!index) {
+        throw new Error(`Repository "${repo}" not found. Index it first with index_folder.`);
+    }
+    return index;
+}
+export function wordBoundaryPattern(name) {
+    const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return new RegExp(`(?<![$_\\p{ID_Continue}])${escaped}(?![$_\\u200C\\u200D\\p{ID_Continue}])`, "u");
+}
+//# sourceMappingURL=symbol-tool-internals.js.map

package/dist/tools/symbol-tool-internals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"symbol-tool-internals.js","sourceRoot":"","sources":["../../src/tools/symbol-tool-internals.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAE9D,MAAM,CAAC,MAAM,cAAc,GAAG,GAAG,CAAC;AAClC,MAAM,CAAC,MAAM,kBAAkB,GAAG,GAAG,CAAC;AAEtC,MAAM,mBAAmB,GAAG;IAC1B,QAAQ;IACR,OAAO;IACP,QAAQ;IACR,WAAW;IACX,eAAe;IACf,gBAAgB;CACjB,CAAC;AACF,MAAM,gBAAgB,GAAG,IAAI,GAAG,CAAC;IAC/B,OAAO;IACP,OAAO;IACP,MAAM;IACN,MAAM;IACN,MAAM;IACN,MAAM;IACN,MAAM;IACN,OAAO;IACP,QAAQ;CACT,CAAC,CAAC;AAEH,MAAM,UAAU,WAAW,CAAC,QAAgB;IAC1C,IAAI,mBAAmB,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACnF,MAAM,GAAG,GAAG,QAAQ,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IACtC,OAAO,GAAG,IAAI,CAAC,IAAI,gBAAgB,CAAC,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;AAC/D,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,IAAY;IACjD,MAAM,KAAK,GAAG,MAAM,YAAY,CAAC,IAAI,CAAC,CAAC;IACvC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CAAC,eAAe,IAAI,gDAAgD,CAAC,CAAC;IACvF,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,IAAY;IACjD,MAAM,KAAK,GAAG,MAAM,YAAY,CAAC,IAAI,CAAC,CAAC;IACvC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CAAC,eAAe,IAAI,gDAAgD,CAAC,CAAC;IACvF,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC;IAC5D,OAAO,IAAI,MAAM,CAAC,4BAA4B,OAAO,wCAAwC,EAAE,GAAG,CAAC,CAAC;AACtG,CAAC"}

package/dist/tools/symbol-tools.d.ts

@@ -1,274 +1,15 @@
-import type { CodeSymbol, Reference, SymbolKind } from "../types.js";
 /**
- * Find symbols with names similar to the requested ID. Used to recover from
- * hallucinated symbol IDs (telemetry shows 24-26% of get_symbol/get_symbols
- * calls return zero results). Extracts a name candidate from the requested
- * ID and returns up to `limit` symbols whose name matches case-insensitively.
- */
-/**
- * Resolve a non-canonical symbol reference to a real symbol ID when it is
- * UNAMBIGUOUS.
- *
- * Symbol IDs are `repo:file:name:line` — they embed the declaration line, so no
- * caller can construct one by hand. Agents therefore pass a bare name
- * ("getOptions") or a half-remembered path, and the lookup returns null; the
- * measured miss rate was 24% of get_symbol calls and 26% of get_symbols. The old
- * behaviour answered with a suggestion list, which is a second round trip for a
- * question we can already answer.
+ * Stable public facade for symbol-oriented tools.
  *
- * Only an EXACT, SINGLE name match resolves. Two symbols named `handler` must
- * stay ambiguous — silently picking one would return the wrong source with no
- * signal, which is worse than the miss it replaces.
- */
-/**
- * Best-effort symbol NAME out of whatever the caller passed.
- *
- * Symbol IDs end in the declaration line (`repo:file:name:LINE`), so naively
- * taking the last segment yields "42" and matches nothing — every suggestion for
- * a well-formed-but-stale id was silently useless. Skip trailing numeric
- * segments, then fall back to the last non-empty one.
- */
-export declare function extractSymbolNameGuess(requestedId: string): string;
-export declare function resolveSymbolIdExact(repo: string, requestedId: string): Promise<string | null>;
-export declare function findSimilarSymbols(repo: string, requestedId: string, limit?: number): Promise<Array<{
-    id: string;
-    name: string;
-    kind: string;
-    file: string;
-    start_line: number;
-}>>;
-/**
- * Retrieve a single symbol by ID with fresh source from disk.
- * When include_related is true (default), auto-prefetches:
- *  - children (for classes/interfaces) — saves follow-up get_symbols call
- *  - symbols in the same file that reference this symbol — saves find_references call
- */
-/**
- * Raised when one id maps to several distinct symbols.
- *
- * A named type rather than a bare `Error` because two callers must tell this apart from a real
- * failure, and matching on message text would break the moment the wording changes. Structural
- * check, not `instanceof`: a duplicated module instance across a worker or bundler boundary makes
- * `instanceof` false for an object that is in every observable way the right error — the same
- * trap `isIndexStorageError` documents in the storage layer.
- */
-export declare class AmbiguousSymbolIdError extends Error {
-    constructor(message: string);
-}
-export declare function isAmbiguousSymbolIdError(err: unknown): err is AmbiguousSymbolIdError;
-/**
- * Resolve a search hit to its full symbol, tolerating an ambiguous id.
- *
- * `getSymbol` throwing on a colliding id is right when a caller supplies one: it named a specific
- * symbol and must not silently receive a different one. Here nobody supplied it — the id was read
- * back off a BM25 hit whose symbol this function already holds. Failing an entire search because
- * its top hit happens to sit in a minified bundle would make the collision a worse answer than the
- * silent substitution it replaced, and it would hit `find_and_show` and `get_context_bundle`, the
- * two tools the H7/H8 hints steer agents toward. Falling back to the hit is not a guess: it is the
- * result the search actually returned.
- */
-export interface SymbolIdAmbiguity {
-    /** Always present. `ambiguous` means the answer is the search's top hit, not a unique resolution. */
-    status: "unique" | "ambiguous";
-    /** Set only when ambiguous: how many distinct symbols share the id. */
-    shared_by?: number;
-    /** Set only when ambiguous: the other candidates, so the caller can pick deliberately. */
-    candidates?: Array<{
-        name: string;
-        kind: SymbolKind;
-        file: string;
-        start_line: number;
-    }>;
-}
-export declare function getSymbol(repo: string, symbolId: string, options?: {
-    include_related?: boolean;
-}): Promise<{
-    symbol: CodeSymbol;
-    related?: CodeSymbol[];
-} | null>;
-/**
- * Retrieve multiple symbols by ID with fresh source from disk.
- * Groups reads by file to minimize disk I/O.
- */
-export declare function getSymbols(repo: string, symbolIds: string[]): Promise<CodeSymbol[]>;
-/**
- * Find references to a symbol name across indexed files.
- * Matches whole words only using word-boundary regex.
- */
-/**
- * Batch find references for multiple symbols in one pass.
- * Reads each file once instead of N times — critical for large repos.
- */
-/**
- * What a reference scan actually looked at.
- *
- * `find_references` returning `[]` is the input to "nobody uses this, safe to rename or delete".
- * That inference is only valid if the scan saw everywhere a reference could be. It routinely does
- * not: generated and vendored paths are skipped by default, files can be unreadable, and per
- * symbol the collection stops at MAX_REFERENCES. None of that was visible in the result.
- *
- * Filled through a caller-supplied sink so the `Record<string, Reference[]>` return shape — which
- * several call sites slice and re-key — stays untouched.
- */
-export interface ReferenceScanCoverage {
-    /** `unknown` is the honest default when the scan did not report — never assume `complete`. */
-    status: "complete" | "partial" | "unknown";
-    files_indexed: number;
-    files_scanned: number;
-    /** Generated/vendored paths skipped because no file_pattern was given. */
-    files_skipped_noise?: number;
-    files_unreadable?: number;
-    /** Symbols whose reference list hit MAX_REFERENCES — their counts are floors, not totals. */
-    capped_symbols?: string[];
-    detail?: string;
-}
-export interface ReferenceScanSink {
-    coverage?: ReferenceScanCoverage;
-}
-export declare function findReferencesBatch(repo: string, symbolNames: string[], filePattern?: string, sink?: ReferenceScanSink): Promise<Record<string, Reference[]>>;
-export declare function findReferences(repo: string, symbolName: string, filePattern?: string): Promise<Reference[]>;
-/** Format references as compact string for MCP output. Groups by file to avoid repeating paths. */
-export declare function formatRefsCompact(refs: Reference[]): string;
-/** Format a CodeSymbol as compact text: header line + source. ~70% less tokens than JSON. */
-export declare function formatSymbolCompact(sym: CodeSymbol): string;
-/** Format multiple CodeSymbols as compact text, separated by blank lines. */
-export declare function formatSymbolsCompact(syms: CodeSymbol[]): string;
-/** Format ContextBundle as compact text. */
-export declare function formatBundleCompact(bundle: {
-    symbol: CodeSymbol;
-    imports: string[];
-    siblings: Array<{
-        name: string;
-        kind: string;
-        start_line: number;
-        end_line: number;
-    }>;
-    types_used: string[];
-}): string;
-/**
- * Search for a symbol by query and return it with full source.
- * Optionally includes references across the codebase.
- */
-export declare function findAndShow(repo: string, query: string, includeRefs?: boolean): Promise<{
-    symbol: CodeSymbol;
-    references?: Reference[];
-    id_ambiguity: SymbolIdAmbiguity;
-} | null>;
-export interface ReactContext {
-    /** Props type name extracted from the component's parameter type annotation */
-    props_type: string | null;
-    /** Source of the props interface/type declaration when found in the index (Tier 4 — Item 16) */
-    props_interface_source: string | null;
-    /** React hooks called inside this component (use*() patterns) */
-    hooks_used: Array<{
-        name: string;
-        is_stdlib: boolean;
-    }>;
-    /** Child components rendered via JSX (<PascalCase>) */
-    child_components: string[];
-    /** Parent components that render this one via JSX */
-    parent_components: string[];
-    /** Detected wrapper pattern (memo, forwardRef, lazy) or null */
-    wrapper: "memo" | "forwardRef" | "lazy" | null;
-}
-export interface ContextBundle {
-    symbol: CodeSymbol;
-    imports: string[];
-    siblings: Array<{
-        name: string;
-        kind: SymbolKind;
-        start_line: number;
-        end_line: number;
-    }>;
-    types_used: string[];
-    /** Only populated when symbol.kind === "component" */
-    react_context?: ReactContext;
-    /** Always present. Says whether `symbol` is a unique resolution or the search's top hit among
-     *  several sharing one id — a distinction the caller cannot otherwise make from the result. */
-    id_ambiguity: SymbolIdAmbiguity;
-}
-/**
- * Get a symbol with its file's imports and sibling symbols in one call.
- * Saves 2-3 round-trips vs get_symbol + search_text(imports) + get_file_outline.
- */
-export declare function getContextBundle(repo: string, symbolName: string): Promise<ContextBundle | null>;
-export interface DeadCodeCandidate {
-    name: string;
-    kind: SymbolKind;
-    file: string;
-    start_line: number;
-    end_line: number;
-    reason: string;
-}
-export interface DeadCodeResult {
-    candidates: DeadCodeCandidate[];
-    scanned_symbols: number;
-    scanned_files: number;
-    /**
-     * The RESULT LIST was cut short — there are more dead-looking symbols than are shown.
-     * The listed candidates are still as trustworthy as `coverage` says; there are just more.
-     */
-    truncated?: boolean;
-    /**
-     * Whether the reference scan actually saw the whole repository.
-     *
-     * This is the field that decides whether a candidate may be deleted. "Dead" here means
-     * "no reference found in the files I read" — if some files were never read, a symbol used
-     * only from those files looks exactly like a genuinely unused one. `truncated` used to carry
-     * this meaning as well as the list-length one; an agent reading a single boolean naturally
-     * takes the harmless reading ("the list is cut off") and acts on the candidates, which is
-     * the wrong call precisely when the scan was short.
-     *
-     * `complete` is the only status under which an empty or short candidate list is evidence
-     * about the code rather than about the scan.
-     */
-    coverage: {
-        status: "complete" | "partial";
-        files_indexed: number;
-        files_read: number;
-        /** Files the scan stopped before reaching (MAX_SCAN_FILES cap). */
-        files_skipped_by_cap?: number;
-        /** Files that were indexed but could not be read now (deleted, permissions, races). */
-        files_unreadable?: number;
-        detail?: string;
-    };
-}
-/**
- * Find potentially dead code: exported symbols with 0 references outside their own file.
- * Scans all indexed files for word-boundary matches of each exported symbol name.
- *
- * F14 fixes (2026-05-05):
- *   - Test files are now ALWAYS scanned for references regardless of
- *     `include_tests`. The flag now gates only candidate selection (whether
- *     test-internal exports can themselves be flagged dead). Symbols used
- *     only in tests are no longer false-positive dead.
- *   - Re-exports via `export * from './x'` and `export { Y } from './x'`
- *     now mark `./x` as live; previously the lack of textual mention in the
- *     barrel made every barrel-forwarded symbol look dead.
- *   - MAX_SCAN_FILES raised 2000 → 5000; truncation now surfaces in the
- *     `truncated` field so callers can react.
- */
-export declare function findDeadCode(repo: string, options?: {
-    file_pattern?: string | undefined;
-    include_tests?: boolean | undefined;
-}): Promise<DeadCodeResult>;
-export interface UnusedImport {
-    file: string;
-    line: number;
-    import_text: string;
-    imported_name: string;
-}
-export interface UnusedImportsResult {
-    unused: UnusedImport[];
-    scanned_files: number;
-    truncated?: boolean;
-}
-/**
- * Find imports whose imported names are never referenced in the file body.
- * Supports ES module named imports: import { A, B } from '...'
+ * Deferred tool loaders and external consumers import this exact module path.
+ * Keep exports explicit so internal split helpers cannot accidentally become public.
  */
-export declare function findUnusedImports(repo: string, options?: {
-    file_pattern?: string;
-    include_tests?: boolean;
-}): Promise<UnusedImportsResult>;
+export { AmbiguousSymbolIdError, extractSymbolNameGuess, findSimilarSymbols, getSymbol, getSymbols, isAmbiguousSymbolIdError, resolveSymbolIdExact, } from "./symbol-lookup-tools.js";
+export type { SymbolIdAmbiguity } from "./symbol-lookup-tools.js";
+export { findReferences, findReferencesBatch, } from "./symbol-reference-tools.js";
+export type { ReferenceScanCoverage, ReferenceScanSink, } from "./symbol-reference-tools.js";
+export { findAndShow, formatBundleCompact, formatRefsCompact, formatSymbolCompact, formatSymbolsCompact, getContextBundle, } from "./symbol-context-tools.js";
+export type { ContextBundle, ReactContext, } from "./symbol-context-tools.js";
+export { findDeadCode, findUnusedImports, } from "./symbol-analysis-tools.js";
+export type { DeadCodeCandidate, DeadCodeResult, UnusedImport, UnusedImportsResult, } from "./symbol-analysis-tools.js";
 //# sourceMappingURL=symbol-tools.d.ts.map