codesift-mcp 0.13.1 → 0.15.0

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

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

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

@@ -0,0 +1,77 @@
+import type { CodeSymbol, SymbolKind } from "../types.js";
+/**
+ * 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 resolveSearchHit(repo: string, hit: CodeSymbol): Promise<{
+    symbol: CodeSymbol;
+    ambiguity: SymbolIdAmbiguity;
+} | null>;
+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[]>;
+//# sourceMappingURL=symbol-lookup-tools.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"symbol-lookup-tools.d.ts","sourceRoot":"","sources":["../../src/tools/symbol-lookup-tools.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAI1D;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAOlE;AAED,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAcxB;AAED,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EACnB,KAAK,SAAI,GACR,OAAO,CAAC,KAAK,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,CA4B9F;AAkED;;;;;GAKG;AACH;;;;;;;;GAQG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AAED,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,sBAAsB,CAMpF;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,iBAAiB;IAChC,qGAAqG;IACrG,MAAM,EAAE,QAAQ,GAAG,WAAW,CAAC;IAC/B,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0FAA0F;IAC1F,UAAU,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,UAAU,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC1F;AAED,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,UAAU,GACd,OAAO,CAAC;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,SAAS,EAAE,iBAAiB,CAAA;CAAE,GAAG,IAAI,CAAC,CAkBtE;AAED,wBAAsB,SAAS,CAC7B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE;IAAE,eAAe,CAAC,EAAE,OAAO,CAAA;CAAE,GACtC,OAAO,CAAC;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,OAAO,CAAC,EAAE,UAAU,EAAE,CAAA;CAAE,GAAG,IAAI,CAAC,CA0DhE;AAED;;;GAGG;AACH,wBAAsB,UAAU,CAC9B,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EAAE,GAClB,OAAO,CAAC,UAAU,EAAE,CAAC,CA4FvB"}

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

@@ -0,0 +1,305 @@
+import { open, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { getCodeIndex } from "./index-tools.js";
+import { requireCodeIndex } from "./symbol-tool-internals.js";
+/**
+ * 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 function extractSymbolNameGuess(requestedId) {
+    const parts = requestedId.split(/[:#/.]/).map((p) => p.trim()).filter(Boolean);
+    for (let i = parts.length - 1; i >= 0; i--) {
+        const p = parts[i];
+        if (!/^\d+$/.test(p))
+            return p;
+    }
+    return requestedId.trim();
+}
+export async function resolveSymbolIdExact(repo, requestedId) {
+    const nameGuess = extractSymbolNameGuess(requestedId);
+    if (!nameGuess)
+        return null;
+    const index = await getCodeIndex(repo, { skipFreshness: true });
+    if (!index)
+        return null;
+    let match = null;
+    for (const s of index.symbols) {
+        if (s.name !== nameGuess)
+            continue;
+        if (match)
+            return null; // ambiguous — let the caller show suggestions
+        match = s.id;
+    }
+    return match;
+}
+export async function findSimilarSymbols(repo, requestedId, limit = 3) {
+    const index = await getCodeIndex(repo, { skipFreshness: true });
+    if (!index)
+        return [];
+    const nameGuess = extractSymbolNameGuess(requestedId);
+    if (!nameGuess)
+        return [];
+    const lower = nameGuess.toLowerCase();
+    const exact = [];
+    const prefix = [];
+    const substr = [];
+    for (const s of index.symbols) {
+        const sn = s.name.toLowerCase();
+        if (sn === lower)
+            exact.push(s);
+        else if (sn.startsWith(lower) || lower.startsWith(sn))
+            prefix.push(s);
+        else if (sn.includes(lower) || lower.includes(sn))
+            substr.push(s);
+        if (exact.length >= limit)
+            break;
+    }
+    const ranked = [...exact, ...prefix, ...substr].slice(0, limit);
+    return ranked.map((s) => ({
+        id: s.id,
+        name: s.name,
+        kind: s.kind,
+        file: s.file,
+        start_line: s.start_line,
+    }));
+}
+/**
+ * Strip internal/BM25 fields from CodeSymbol for leaner output.
+ * Removes: repo, tokens, start_col, end_col. Shortens id (strips repo prefix).
+ */
+function stripSymbol(sym) {
+    const { repo: _repo, tokens: _tokens, start_col: _sc, end_col: _ec, start_byte: _sb, end_byte: _eb, id, ...rest } = sym;
+    // Strip "local/reponame:" prefix from id
+    const shortId = id.includes(":") ? id.slice(id.indexOf(":") + 1) : id;
+    return { ...rest, id: shortId };
+}
+function matchesSymbolId(symbol, requestedId) {
+    if (symbol.id === requestedId)
+        return true;
+    const separator = symbol.id.indexOf(":");
+    return separator >= 0 && symbol.id.slice(separator + 1) === requestedId;
+}
+/**
+ * Read a source file and extract lines for a symbol (1-based, inclusive).
+ * Uses byte offsets when available for precise reads without loading full file.
+ * Returns undefined if the file cannot be read.
+ */
+async function extractSource(repoRoot, file, startLine, endLine, startByte, endByte) {
+    const filePath = join(repoRoot, file);
+    // Fast path: use byte offsets to read exact range
+    if (startByte != null && endByte != null && endByte > startByte) {
+        try {
+            const fh = await open(filePath, "r");
+            try {
+                const length = endByte - startByte;
+                const buf = Buffer.alloc(length);
+                let total = 0;
+                while (total < length) {
+                    const { bytesRead } = await fh.read(buf, total, length - total, startByte + total);
+                    if (bytesRead === 0)
+                        break;
+                    total += bytesRead;
+                }
+                if (total === length)
+                    return buf.toString("utf-8");
+            }
+            finally {
+                await fh.close();
+            }
+        }
+        catch {
+            // Fall through to line-based extraction
+        }
+    }
+    // Fallback: line-based extraction
+    try {
+        const content = await readFile(filePath, "utf-8");
+        const lines = content.split("\n");
+        return lines.slice(startLine - 1, endLine).join("\n");
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * 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 class AmbiguousSymbolIdError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "AmbiguousSymbolIdError";
+    }
+}
+export function isAmbiguousSymbolIdError(err) {
+    return (typeof err === "object" &&
+        err !== null &&
+        err.name === "AmbiguousSymbolIdError");
+}
+export async function resolveSearchHit(repo, hit) {
+    try {
+        const full = await getSymbol(repo, hit.id, { include_related: false });
+        return full ? { symbol: full.symbol, ambiguity: { status: "unique" } } : null;
+    }
+    catch (err) {
+        if (!isAmbiguousSymbolIdError(err))
+            throw err;
+        // Falling back is defensible; falling back SILENTLY is not. The caller is being handed one of
+        // several symbols and has no way to tell from the result — which is the same silence the
+        // `lossy_migration` marker was added to remove one layer down.
+        const index = await requireCodeIndex(repo);
+        const candidates = index.symbols
+            .filter((s) => s.id === hit.id)
+            .map((s) => ({ name: s.name, kind: s.kind, file: s.file, start_line: s.start_line }));
+        return {
+            symbol: hit,
+            ambiguity: { status: "ambiguous", shared_by: candidates.length, candidates: candidates.slice(0, 5) },
+        };
+    }
+}
+export async function getSymbol(repo, symbolId, options) {
+    const index = await requireCodeIndex(repo);
+    const includeRelated = options?.include_related ?? true;
+    // `repo:file:name:line` is NOT unique — a minified bundle puts many symbols on line 1, and
+    // PHPDoc synthesis emits a field and a method at the same line (73,165 collisions measured
+    // across 16 indexes). `.find` would hand back whichever happened to load first, with no
+    // signal: the caller then reads source for a symbol it did not ask for. This file already
+    // states the rule for names ("two symbols named `handler` must stay ambiguous — silently
+    // picking one is worse than the miss it replaces"); it was never applied to ids because they
+    // were assumed unique.
+    const matches = index.symbols.filter((s) => matchesSymbolId(s, symbolId));
+    if (matches.length === 0)
+        return null;
+    if (matches.length > 1) {
+        const where = matches
+            .map((s) => `${s.kind} ${s.name} @ ${s.file}:${s.start_line}`)
+            .slice(0, 5)
+            .join("; ");
+        throw new AmbiguousSymbolIdError(`Symbol id "${symbolId}" is ambiguous — ${matches.length} distinct symbols share it: ${where}. ` +
+            `Ids embed only file, name and line, which collide in generated or synthesised code. ` +
+            `Use search_symbols to pick the one you mean.`);
+    }
+    const symbol = matches[0];
+    const source = await extractSource(index.root, symbol.file, symbol.start_line, symbol.end_line, symbol.start_byte, symbol.end_byte);
+    const result = { ...symbol };
+    if (source !== undefined) {
+        result.source = source;
+    }
+    const stripped = stripSymbol(result);
+    if (!includeRelated) {
+        return { symbol: stripped };
+    }
+    // Prefetch children for classes/interfaces
+    const related = [];
+    if (symbol.kind === "class" || symbol.kind === "interface") {
+        const children = index.symbols.filter((s) => s.parent === symbol.id);
+        for (const child of children.slice(0, 20)) {
+            related.push(stripSymbol(child));
+        }
+    }
+    const out = { symbol: stripped };
+    if (related.length > 0)
+        out.related = related;
+    return out;
+}
+/**
+ * Retrieve multiple symbols by ID with fresh source from disk.
+ * Groups reads by file to minimize disk I/O.
+ */
+export async function getSymbols(repo, symbolIds) {
+    const index = await requireCodeIndex(repo);
+    // Build lookup map for requested symbols.
+    //
+    // A colliding id must be refused here for the same reason `getSymbol` refuses it: ids are
+    // `repo:file:name:line` and that is not unique, so `.set()` on a repeated id was last-write-wins
+    // — the caller asked for one symbol and silently received whichever happened to come later in
+    // the array. Leaving the batch path permissive would have meant two entry points in this file
+    // disagreeing about the same input, one throwing and one substituting, which is worse than
+    // either rule applied consistently.
+    const requestedIds = new Set(symbolIds);
+    const symbolMap = new Map();
+    const collisions = new Map();
+    for (const sym of index.symbols) {
+        const separator = sym.id.indexOf(":");
+        const candidates = separator >= 0 ? [sym.id, sym.id.slice(separator + 1)] : [sym.id];
+        for (const requestedId of new Set(candidates)) {
+            if (!requestedIds.has(requestedId))
+                continue;
+            const seen = symbolMap.get(requestedId);
+            if (seen === undefined) {
+                symbolMap.set(requestedId, sym);
+                continue;
+            }
+            const group = collisions.get(requestedId) ?? [seen];
+            group.push(sym);
+            collisions.set(requestedId, group);
+        }
+    }
+    if (collisions.size > 0) {
+        const detail = [...collisions.entries()]
+            .slice(0, 3)
+            .map(([id, group]) => {
+            const where = group
+                .slice(0, 5)
+                .map((s) => `${s.kind} ${s.name} @ ${s.file}:${s.start_line}`)
+                .join("; ");
+            return `"${id}" -> ${group.length} symbols: ${where}`;
+        })
+            .join(" | ");
+        throw new AmbiguousSymbolIdError(`${collisions.size} of the requested ids are ambiguous — ${detail}. ` +
+            `Ids embed only file, name and line, which collide in generated or synthesised code. ` +
+            `Use search_symbols to pick the ones you mean.`);
+    }
+    // Group symbols by file to read each file only once
+    const byFile = new Map();
+    for (const id of symbolIds) {
+        const sym = symbolMap.get(id);
+        if (!sym)
+            continue;
+        let group = byFile.get(sym.file);
+        if (!group) {
+            group = [];
+            byFile.set(sym.file, group);
+        }
+        group.push({ requestedId: id, symbol: sym });
+    }
+    // Read all files in parallel, extract source for all symbols in each file
+    const results = new Map();
+    const fileEntries = [...byFile.entries()];
+    const fileContents = await Promise.all(fileEntries.map(([file]) => readFile(join(index.root, file), "utf-8").catch(() => undefined)));
+    for (let i = 0; i < fileEntries.length; i++) {
+        const [, symbols] = fileEntries[i];
+        const lines = fileContents[i]?.split("\n");
+        for (const { requestedId, symbol: sym } of symbols) {
+            const result = { ...sym };
+            if (lines) {
+                result.source = lines.slice(sym.start_line - 1, sym.end_line).join("\n");
+            }
+            results.set(requestedId, result);
+        }
+    }
+    // Return in the same order as requested, skipping missing IDs
+    const ordered = [];
+    for (const id of symbolIds) {
+        const sym = results.get(id);
+        if (sym)
+            ordered.push(stripSymbol(sym));
+    }
+    return ordered;
+}
+//# sourceMappingURL=symbol-lookup-tools.js.map

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

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

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"}