codesift-mcp 0.13.1 → 0.15.0

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

@@ -0,0 +1,327 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { detectFrameworks, isFrameworkEntryPoint, } from "../utils/framework-detect.js";
+import { isTestFileStrict as isTestFile } from "../utils/test-file.js";
+import { requireCodeIndex } from "./symbol-tool-internals.js";
+const MAX_DEAD_CODE_RESULTS = 100;
+// Kinds that are typically exported and should have external references
+const EXPORTABLE_KINDS = new Set([
+    "function", "class", "interface", "type", "variable", "constant", "enum",
+    "component", "hook",
+]);
+/**
+ * Collect top-level symbols of exportable kinds, filtered by test/pattern options.
+ */
+function collectExportedSymbols(symbols, options) {
+    return symbols.filter((s) => {
+        if (!EXPORTABLE_KINDS.has(s.kind))
+            return false;
+        if (s.parent)
+            return false;
+        if (!options.includeTests && isTestFile(s.file))
+            return false;
+        if (options.filePattern && !s.file.includes(options.filePattern))
+            return false;
+        if (s.name.length < 3)
+            return false;
+        if (s.kind === "variable" && s.name === "default")
+            return false;
+        return true;
+    });
+}
+// Bumped from 2000 → 5000 (F14: prior cap silently dropped references in
+// medium-large repos, producing false-positive dead-code candidates whose
+// real callers lived in unscanned files). Memory cost: roughly one file
+// content string per entry — at 5K average-sized source files this is on
+// the order of 50–200 MB peak, well within limits for analysis flows.
+const MAX_SCAN_FILES = 5000;
+/**
+ * Resolve a relative import path against a source file's directory. Handles
+ * the standard TS/Node extensions plus barrel-style `index` resolution.
+ * Returns the candidate file path that exists in `allFiles`, or null.
+ *
+ * Intentionally narrow: only resolves `./` and `../` paths. Aliased imports
+ * (tsconfig paths, package-json `imports`) are out of scope here — they show
+ * up textually in scanned content anyway, so they don't drive false positives.
+ */
+function resolveRelativeImport(fromFile, importPath, allFiles) {
+    if (!importPath.startsWith("."))
+        return null;
+    const lastSlash = fromFile.lastIndexOf("/");
+    const fromDir = lastSlash >= 0 ? fromFile.slice(0, lastSlash) : "";
+    const segments = (fromDir + "/" + importPath).split("/");
+    const stack = [];
+    for (const seg of segments) {
+        if (!seg || seg === ".")
+            continue;
+        if (seg === "..")
+            stack.pop();
+        else
+            stack.push(seg);
+    }
+    const base = stack.join("/");
+    if (allFiles.has(base))
+        return base;
+    // TS allows `import './x.js'` to resolve to `x.ts` — strip then re-extend.
+    const stripped = base.replace(/\.(m?js|jsx)$/, "");
+    const candidates = [
+        stripped + ".ts",
+        stripped + ".tsx",
+        stripped + ".mjs",
+        stripped + ".js",
+        stripped + ".jsx",
+        stripped + "/index.ts",
+        stripped + "/index.tsx",
+        stripped + "/index.js",
+        stripped + "/index.jsx",
+    ];
+    for (const c of candidates) {
+        if (allFiles.has(c))
+            return c;
+    }
+    return null;
+}
+/**
+ * Pre-scan content for re-export edges. A symbol re-exported from another
+ * file isn't textually referenced in the barrel — without this pass barrel
+ * patterns like `export * from './foo'` cause every symbol in `./foo` to be
+ * misclassified as dead.
+ *
+ * Returns a set of file paths that are reached via at least one re-export
+ * (named or star). Callers treat any candidate whose defining file lands in
+ * this set as live.
+ */
+function collectReExportedFiles(fileContents, allFiles) {
+    const reExported = new Set();
+    // Matches:  export * from "./x";   export { A, B } from "./x";   export type { T } from "./x";
+    // Anchor dropped (`^\s*` removed) so block-comment-prefixed exports
+    // (`/** doc */ export { Y } from "./x"`) and continuation-line exports
+    // (`...; export * from "./x"`) are detected too.
+    const RE = /\bexport\s+(?:\*|type\s+\*|\{[^}]*\}|type\s+\{[^}]*\})\s+from\s+['"]([^'"]+)['"]/gm;
+    for (const [filePath, content] of fileContents) {
+        RE.lastIndex = 0;
+        let m;
+        while ((m = RE.exec(content)) !== null) {
+            const target = resolveRelativeImport(filePath, m[1], allFiles);
+            if (target)
+                reExported.add(target);
+        }
+    }
+    return reExported;
+}
+/**
+ * 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 async function findDeadCode(repo, options) {
+    const index = await requireCodeIndex(repo);
+    const includeTests = options?.include_tests ?? false;
+    const filePattern = options?.file_pattern;
+    const exportedSymbols = collectExportedSymbols(index.symbols, { includeTests, filePattern });
+    const frameworks = detectFrameworks(index);
+    // Read EVERY indexed file (incl. tests) for reference scanning. The previous
+    // version honored `includeTests` here, which meant a symbol referenced only
+    // from tests was misclassified as dead. Candidate selection still uses
+    // `includeTests` (above) so test-only helpers don't appear in the result list.
+    const fileContents = new Map();
+    let scanTruncated = false;
+    let filesSkippedByCap = 0;
+    let filesUnreadable = 0;
+    for (const file of index.files) {
+        if (fileContents.size >= MAX_SCAN_FILES) {
+            scanTruncated = true;
+            filesSkippedByCap = index.files.length - fileContents.size - filesUnreadable;
+            break;
+        }
+        try {
+            fileContents.set(file.path, await readFile(join(index.root, file.path), "utf-8"));
+        }
+        catch {
+            // Deleted, unreadable, or raced with a write. Counted rather than merely skipped: a
+            // reference living only in a file we could not read is invisible to the scan below, and
+            // the symbol it points at then looks dead.
+            filesUnreadable++;
+        }
+    }
+    // Build set of files that are forwarded via re-exports (barrel chains).
+    // Symbols defined in such files are reachable even without textual mention.
+    const allFilePaths = new Set(fileContents.keys());
+    const reExportedFiles = collectReExportedFiles(fileContents, allFilePaths);
+    // Reference index, built in ONE pass over file contents. Previously this scan
+    // was O(exportedSymbols x files): a `\b<name>\b` regex over every file's full
+    // text for every exported symbol. On a healthy repo (few dead symbols) the
+    // early-exit never fires, so the full product ran — telemetry (2026-07-20)
+    // measured a 1,066,401 ms (~17.8 min) p95 for find_dead_code.
+    //
+    // Tokenising on [^A-Za-z0-9_]+ mirrors the \b\w boundary semantics of the old
+    // regex. Per token we only need "is it mentioned outside its defining file",
+    // so we keep the first file that mentioned it plus a multi-file flag — O(1)
+    // memory per unique token instead of a file set, and O(1) lookup per symbol.
+    const tokenIndex = new Map();
+    for (const [filePath, content] of fileContents) {
+        for (const token of new Set(content.split(/[^A-Za-z0-9_]+/))) {
+            if (!token)
+                continue;
+            const entry = tokenIndex.get(token);
+            if (!entry)
+                tokenIndex.set(token, { first: filePath, multi: false });
+            else if (!entry.multi && entry.first !== filePath)
+                entry.multi = true;
+        }
+    }
+    const candidates = [];
+    for (const sym of exportedSymbols) {
+        if (candidates.length >= MAX_DEAD_CODE_RESULTS)
+            break;
+        if (isFrameworkEntryPoint(sym, frameworks))
+            continue;
+        // Re-export reachability — barrel forwards skip the textual-mention check.
+        if (reExportedFiles.has(sym.file))
+            continue;
+        // Mentioned in any file other than the one defining it => not dead.
+        const seen = tokenIndex.get(sym.name);
+        const hasExternalRef = !!seen && (seen.multi || seen.first !== sym.file);
+        if (!hasExternalRef) {
+            candidates.push({
+                name: sym.name,
+                kind: sym.kind,
+                file: sym.file,
+                start_line: sym.start_line,
+                end_line: sym.end_line,
+                reason: "exported but no references found outside defining file",
+            });
+        }
+    }
+    const scanComplete = !scanTruncated && filesUnreadable === 0;
+    const coverage = {
+        status: scanComplete ? "complete" : "partial",
+        files_indexed: index.files.length,
+        files_read: fileContents.size,
+        ...(filesSkippedByCap > 0 ? { files_skipped_by_cap: filesSkippedByCap } : {}),
+        ...(filesUnreadable > 0 ? { files_unreadable: filesUnreadable } : {}),
+        ...(scanComplete
+            ? {}
+            : {
+                detail: `reference scan read ${fileContents.size} of ${index.files.length} indexed files` +
+                    (filesSkippedByCap > 0 ? ` (${filesSkippedByCap} beyond the ${MAX_SCAN_FILES}-file cap)` : "") +
+                    (filesUnreadable > 0 ? ` (${filesUnreadable} unreadable)` : "") +
+                    " — a symbol referenced only from an unread file is indistinguishable from a dead one," +
+                    " so do NOT delete on this result alone; narrow with file_pattern to get a complete scan",
+            }),
+    };
+    return {
+        candidates,
+        scanned_symbols: exportedSymbols.length,
+        scanned_files: fileContents.size,
+        // Deliberately ONLY about list length now. Scan completeness lives in `coverage`, because
+        // the two have opposite implications: a cut-off list means "there are more", a short scan
+        // means "these may be wrong".
+        ...(candidates.length >= MAX_DEAD_CODE_RESULTS ? { truncated: true } : {}),
+        coverage,
+    };
+}
+// ---------------------------------------------------------------------------
+// Unused import detection
+// ---------------------------------------------------------------------------
+const MAX_UNUSED_IMPORTS = 200;
+/**
+ * Find imports whose imported names are never referenced in the file body.
+ * Supports ES module named imports: import { A, B } from '...'
+ */
+export async function findUnusedImports(repo, options) {
+    const index = await requireCodeIndex(repo);
+    const includeTests = options?.include_tests ?? false;
+    const unused = [];
+    let scannedFiles = 0;
+    for (const file of index.files) {
+        if (unused.length >= MAX_UNUSED_IMPORTS)
+            break;
+        if (!includeTests && isTestFile(file.path))
+            continue;
+        if (options?.file_pattern && !file.path.includes(options.file_pattern))
+            continue;
+        // Only analyze JS/TS/Kotlin files
+        if (!/\.(ts|tsx|js|jsx|mjs|kt|kts)$/.test(file.path))
+            continue;
+        let source;
+        try {
+            source = await readFile(join(index.root, file.path), "utf-8");
+        }
+        catch {
+            continue;
+        }
+        scannedFiles++;
+        const lines = source.split("\n");
+        // Find named import lines: import { A, B, C } from '...'
+        // Also: import A from '...'  and  import * as A from '...'
+        const importRegex = /^import\s+(?:type\s+)?(?:\{([^}]+)\}|(\*\s+as\s+\w+)|(\w+)).*from\s+['"][^'"]+['"]/;
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i].trim();
+            if (!line.startsWith("import "))
+                continue;
+            // Stop scanning imports when we hit non-import code
+            if (i > 0 && !line.startsWith("import") && !line.startsWith("//") && !line.startsWith("/*") && line.length > 0 && !lines[i].trim().startsWith("*") && !lines[i].trim().startsWith("}")) {
+                // Could be multi-line import continuation, keep going
+            }
+            const match = importRegex.exec(line);
+            if (!match)
+                continue;
+            const names = [];
+            if (match[1]) {
+                // Named imports: { A, B as C, type D }
+                for (const part of match[1].split(",")) {
+                    const trimmed = part.trim().replace(/^type\s+/, "");
+                    if (!trimmed)
+                        continue;
+                    // Handle "A as B" — the local name is B
+                    const asMatch = /(\w+)\s+as\s+(\w+)/.exec(trimmed);
+                    names.push(asMatch ? asMatch[2] : trimmed);
+                }
+            }
+            else if (match[2]) {
+                // Namespace import: * as A
+                const nsMatch = /\*\s+as\s+(\w+)/.exec(match[2]);
+                if (nsMatch)
+                    names.push(nsMatch[1]);
+            }
+            else if (match[3]) {
+                // Default import: import A
+                names.push(match[3]);
+            }
+            // Check each imported name against rest of file
+            const bodyAfterImports = lines.slice(i + 1).join("\n");
+            for (const name of names) {
+                if (name.length < 2)
+                    continue;
+                const nameRegex = new RegExp(`\\b${name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`);
+                if (!nameRegex.test(bodyAfterImports)) {
+                    unused.push({
+                        file: file.path,
+                        line: i + 1,
+                        import_text: line,
+                        imported_name: name,
+                    });
+                    if (unused.length >= MAX_UNUSED_IMPORTS)
+                        break;
+                }
+            }
+        }
+    }
+    return {
+        unused,
+        scanned_files: scannedFiles,
+        ...(unused.length >= MAX_UNUSED_IMPORTS ? { truncated: true } : {}),
+    };
+}
+//# sourceMappingURL=symbol-analysis-tools.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"symbol-analysis-tools.js","sourceRoot":"","sources":["../../src/tools/symbol-analysis-tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EACL,gBAAgB,EAChB,qBAAqB,GACtB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,gBAAgB,IAAI,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACvE,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAE9D,MAAM,qBAAqB,GAAG,GAAG,CAAC;AA6ClC,wEAAwE;AACxE,MAAM,gBAAgB,GAAG,IAAI,GAAG,CAAa;IAC3C,UAAU,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM;IACxE,WAAW,EAAE,MAAM;CACpB,CAAC,CAAC;AAEH;;GAEG;AACH,SAAS,sBAAsB,CAC7B,OAAqB,EACrB,OAAoE;IAEpE,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE;QAC1B,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;YAAE,OAAO,KAAK,CAAC;QAChD,IAAI,CAAC,CAAC,MAAM;YAAE,OAAO,KAAK,CAAC;QAC3B,IAAI,CAAC,OAAO,CAAC,YAAY,IAAI,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC;YAAE,OAAO,KAAK,CAAC;QAC9D,IAAI,OAAO,CAAC,WAAW,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,WAAW,CAAC;YAAE,OAAO,KAAK,CAAC;QAC/E,IAAI,CAAC,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC;QACpC,IAAI,CAAC,CAAC,IAAI,KAAK,UAAU,IAAI,CAAC,CAAC,IAAI,KAAK,SAAS;YAAE,OAAO,KAAK,CAAC;QAChE,OAAO,IAAI,CAAC;IACd,CAAC,CAAC,CAAC;AACL,CAAC;AAED,yEAAyE;AACzE,0EAA0E;AAC1E,wEAAwE;AACxE,yEAAyE;AACzE,sEAAsE;AACtE,MAAM,cAAc,GAAG,IAAI,CAAC;AAE5B;;;;;;;;GAQG;AACH,SAAS,qBAAqB,CAC5B,QAAgB,EAChB,UAAkB,EAClB,QAAqB;IAErB,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAC7C,MAAM,SAAS,GAAG,QAAQ,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAC5C,MAAM,OAAO,GAAG,SAAS,IAAI,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACnE,MAAM,QAAQ,GAAG,CAAC,OAAO,GAAG,GAAG,GAAG,UAAU,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACzD,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;QAC3B,IAAI,CAAC,GAAG,IAAI,GAAG,KAAK,GAAG;YAAE,SAAS;QAClC,IAAI,GAAG,KAAK,IAAI;YAAE,KAAK,CAAC,GAAG,EAAE,CAAC;;YACzB,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACvB,CAAC;IACD,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC7B,IAAI,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACpC,2EAA2E;IAC3E,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,eAAe,EAAE,EAAE,CAAC,CAAC;IACnD,MAAM,UAAU,GAAG;QACjB,QAAQ,GAAG,KAAK;QAChB,QAAQ,GAAG,MAAM;QACjB,QAAQ,GAAG,MAAM;QACjB,QAAQ,GAAG,KAAK;QAChB,QAAQ,GAAG,MAAM;QACjB,QAAQ,GAAG,WAAW;QACtB,QAAQ,GAAG,YAAY;QACvB,QAAQ,GAAG,WAAW;QACtB,QAAQ,GAAG,YAAY;KACxB,CAAC;IACF,KAAK,MAAM,CAAC,IAAI,UAAU,EAAE,CAAC;QAC3B,IAAI,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC;YAAE,OAAO,CAAC,CAAC;IAChC,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;GASG;AACH,SAAS,sBAAsB,CAC7B,YAAiC,EACjC,QAAqB;IAErB,MAAM,UAAU,GAAG,IAAI,GAAG,EAAU,CAAC;IACrC,+FAA+F;IAC/F,oEAAoE;IACpE,uEAAuE;IACvE,iDAAiD;IACjD,MAAM,EAAE,GAAG,oFAAoF,CAAC;IAChG,KAAK,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,IAAI,YAAY,EAAE,CAAC;QAC/C,EAAE,CAAC,SAAS,GAAG,CAAC,CAAC;QACjB,IAAI,CAAyB,CAAC;QAC9B,OAAO,CAAC,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;YACvC,MAAM,MAAM,GAAG,qBAAqB,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,CAAE,EAAE,QAAQ,CAAC,CAAC;YAChE,IAAI,MAAM;gBAAE,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACrC,CAAC;IACH,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,IAAY,EACZ,OAGC;IAED,MAAM,KAAK,GAAG,MAAM,gBAAgB,CAAC,IAAI,CAAC,CAAC;IAC3C,MAAM,YAAY,GAAG,OAAO,EAAE,aAAa,IAAI,KAAK,CAAC;IACrD,MAAM,WAAW,GAAG,OAAO,EAAE,YAAY,CAAC;IAE1C,MAAM,eAAe,GAAG,sBAAsB,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,YAAY,EAAE,WAAW,EAAE,CAAC,CAAC;IAC7F,MAAM,UAAU,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAC;IAE3C,6EAA6E;IAC7E,4EAA4E;IAC5E,uEAAuE;IACvE,+EAA+E;IAC/E,MAAM,YAAY,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC/C,IAAI,aAAa,GAAG,KAAK,CAAC;IAC1B,IAAI,iBAAiB,GAAG,CAAC,CAAC;IAC1B,IAAI,eAAe,GAAG,CAAC,CAAC;IACxB,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;QAC/B,IAAI,YAAY,CAAC,IAAI,IAAI,cAAc,EAAE,CAAC;YACxC,aAAa,GAAG,IAAI,CAAC;YACrB,iBAAiB,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,YAAY,CAAC,IAAI,GAAG,eAAe,CAAC;YAC7E,MAAM;QACR,CAAC;QACD,IAAI,CAAC;YACH,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;QACpF,CAAC;QAAC,MAAM,CAAC;YACP,oFAAoF;YACpF,wFAAwF;YACxF,2CAA2C;YAC3C,eAAe,EAAE,CAAC;QACpB,CAAC;IACH,CAAC;IAED,wEAAwE;IACxE,4EAA4E;IAC5E,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,YAAY,CAAC,IAAI,EAAE,CAAC,CAAC;IAClD,MAAM,eAAe,GAAG,sBAAsB,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC;IAE3E,8EAA8E;IAC9E,8EAA8E;IAC9E,2EAA2E;IAC3E,2EAA2E;IAC3E,8DAA8D;IAC9D,EAAE;IACF,8EAA8E;IAC9E,6EAA6E;IAC7E,4EAA4E;IAC5E,6EAA6E;IAC7E,MAAM,UAAU,GAAG,IAAI,GAAG,EAA6C,CAAC;IACxE,KAAK,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,IAAI,YAAY,EAAE,CAAC;QAC/C,KAAK,MAAM,KAAK,IAAI,IAAI,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC,EAAE,CAAC;YAC7D,IAAI,CAAC,KAAK;gBAAE,SAAS;YACrB,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;YACpC,IAAI,CAAC,KAAK;gBAAE,UAAU,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;iBAChE,IAAI,CAAC,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC,KAAK,KAAK,QAAQ;gBAAE,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC;QACxE,CAAC;IACH,CAAC;IAED,MAAM,UAAU,GAAwB,EAAE,CAAC;IAE3C,KAAK,MAAM,GAAG,IAAI,eAAe,EAAE,CAAC;QAClC,IAAI,UAAU,CAAC,MAAM,IAAI,qBAAqB;YAAE,MAAM;QACtD,IAAI,qBAAqB,CAAC,GAAG,EAAE,UAAU,CAAC;YAAE,SAAS;QACrD,2EAA2E;QAC3E,IAAI,eAAe,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,SAAS;QAE5C,oEAAoE;QACpE,MAAM,IAAI,GAAG,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACtC,MAAM,cAAc,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,KAAK,GAAG,CAAC,IAAI,CAAC,CAAC;QAEzE,IAAI,CAAC,cAAc,EAAE,CAAC;YACpB,UAAU,CAAC,IAAI,CAAC;gBACd,IAAI,EAAE,GAAG,CAAC,IAAI;gBACd,IAAI,EAAE,GAAG,CAAC,IAAI;gBACd,IAAI,EAAE,GAAG,CAAC,IAAI;gBACd,UAAU,EAAE,GAAG,CAAC,UAAU;gBAC1B,QAAQ,EAAE,GAAG,CAAC,QAAQ;gBACtB,MAAM,EAAE,wDAAwD;aACjE,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,MAAM,YAAY,GAAG,CAAC,aAAa,IAAI,eAAe,KAAK,CAAC,CAAC;IAC7D,MAAM,QAAQ,GAA+B;QAC3C,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS;QAC7C,aAAa,EAAE,KAAK,CAAC,KAAK,CAAC,MAAM;QACjC,UAAU,EAAE,YAAY,CAAC,IAAI;QAC7B,GAAG,CAAC,iBAAiB,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7E,GAAG,CAAC,eAAe,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,gBAAgB,EAAE,eAAe,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACrE,GAAG,CAAC,YAAY;YACd,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC;gBACE,MAAM,EACJ,uBAAuB,YAAY,CAAC,IAAI,OAAO,KAAK,CAAC,KAAK,CAAC,MAAM,gBAAgB;oBACjF,CAAC,iBAAiB,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,iBAAiB,eAAe,cAAc,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC;oBAC9F,CAAC,eAAe,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,eAAe,cAAc,CAAC,CAAC,CAAC,EAAE,CAAC;oBAC/D,uFAAuF;oBACvF,yFAAyF;aAC5F,CAAC;KACP,CAAC;IAEF,OAAO;QACL,UAAU;QACV,eAAe,EAAE,eAAe,CAAC,MAAM;QACvC,aAAa,EAAE,YAAY,CAAC,IAAI;QAChC,0FAA0F;QAC1F,0FAA0F;QAC1F,8BAA8B;QAC9B,GAAG,CAAC,UAAU,CAAC,MAAM,IAAI,qBAAqB,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1E,QAAQ;KACT,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,0BAA0B;AAC1B,8EAA8E;AAE9E,MAAM,kBAAkB,GAAG,GAAG,CAAC;AAe/B;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,IAAY,EACZ,OAA4D;IAE5D,MAAM,KAAK,GAAG,MAAM,gBAAgB,CAAC,IAAI,CAAC,CAAC;IAC3C,MAAM,YAAY,GAAG,OAAO,EAAE,aAAa,IAAI,KAAK,CAAC;IAErD,MAAM,MAAM,GAAmB,EAAE,CAAC;IAClC,IAAI,YAAY,GAAG,CAAC,CAAC;IAErB,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;QAC/B,IAAI,MAAM,CAAC,MAAM,IAAI,kBAAkB;YAAE,MAAM;QAC/C,IAAI,CAAC,YAAY,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,SAAS;QACrD,IAAI,OAAO,EAAE,YAAY,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,YAAY,CAAC;YAAE,SAAS;QAEjF,kCAAkC;QAClC,IAAI,CAAC,+BAA+B,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,SAAS;QAE/D,IAAI,MAAc,CAAC;QACnB,IAAI,CAAC;YACH,MAAM,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC;QAChE,CAAC;QAAC,MAAM,CAAC;YACP,SAAS;QACX,CAAC;QACD,YAAY,EAAE,CAAC;QAEf,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAEjC,yDAAyD;QACzD,2DAA2D;QAC3D,MAAM,WAAW,GAAG,oFAAoF,CAAC;QAEzG,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACtC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC,IAAI,EAAE,CAAC;YAC9B,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC;gBAAE,SAAS;YAC1C,oDAAoD;YACpD,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC,IAAI,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC,IAAI,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;gBACzL,sDAAsD;YACxD,CAAC;YAED,MAAM,KAAK,GAAG,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACrC,IAAI,CAAC,KAAK;gBAAE,SAAS;YAErB,MAAM,KAAK,GAAa,EAAE,CAAC;YAC3B,IAAI,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;gBACb,uCAAuC;gBACvC,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;oBACvC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;oBACpD,IAAI,CAAC,OAAO;wBAAE,SAAS;oBACvB,wCAAwC;oBACxC,MAAM,OAAO,GAAG,oBAAoB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;oBACnD,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;gBAC9C,CAAC;YACH,CAAC;iBAAM,IAAI,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;gBACpB,2BAA2B;gBAC3B,MAAM,OAAO,GAAG,iBAAiB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;gBACjD,IAAI,OAAO;oBAAE,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAE,CAAC,CAAC;YACvC,CAAC;iBAAM,IAAI,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;gBACpB,2BAA2B;gBAC3B,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;YACvB,CAAC;YAED,gDAAgD;YAChD,MAAM,gBAAgB,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACvD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;gBACzB,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;oBAAE,SAAS;gBAC9B,MAAM,SAAS,GAAG,IAAI,MAAM,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;gBACrF,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,gBAAgB,CAAC,EAAE,CAAC;oBACtC,MAAM,CAAC,IAAI,CAAC;wBACV,IAAI,EAAE,IAAI,CAAC,IAAI;wBACf,IAAI,EAAE,CAAC,GAAG,CAAC;wBACX,WAAW,EAAE,IAAI;wBACjB,aAAa,EAAE,IAAI;qBACpB,CAAC,CAAC;oBACH,IAAI,MAAM,CAAC,MAAM,IAAI,kBAAkB;wBAAE,MAAM;gBACjD,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO;QACL,MAAM;QACN,aAAa,EAAE,YAAY;QAC3B,GAAG,CAAC,MAAM,CAAC,MAAM,IAAI,kBAAkB,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACpE,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,68 @@
+import type { CodeSymbol, Reference, SymbolKind } from "../types.js";
+import { type SymbolIdAmbiguity } from "./symbol-lookup-tools.js";
+/** 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>;
+//# sourceMappingURL=symbol-context-tools.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"symbol-context-tools.d.ts","sourceRoot":"","sources":["../../src/tools/symbol-context-tools.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAErE,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,0BAA0B,CAAC;AAOlC,mGAAmG;AACnG,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,SAAS,EAAE,GAAG,MAAM,CAkB3D;AAED,6FAA6F;AAC7F,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,CAM3D;AAED,6EAA6E;AAC7E,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,MAAM,CAE/D;AAED,4CAA4C;AAC5C,wBAAgB,mBAAmB,CAAC,MAAM,EAAE;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAC;IAAC,QAAQ,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAAC,UAAU,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG,MAAM,CAc1M;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,WAAW,CAAC,EAAE,OAAO,GACpB,OAAO,CACR;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,UAAU,CAAC,EAAE,SAAS,EAAE,CAAC;IAAC,YAAY,EAAE,iBAAiB,CAAA;CAAE,GAAG,IAAI,CACzF,CAkBA;AAaD,MAAM,WAAW,YAAY;IAC3B,+EAA+E;IAC/E,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,gGAAgG;IAChG,sBAAsB,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,iEAAiE;IACjE,UAAU,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACxD,uDAAuD;IACvD,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,qDAAqD;IACrD,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,gEAAgE;IAChE,OAAO,EAAE,MAAM,GAAG,YAAY,GAAG,MAAM,GAAG,IAAI,CAAC;CAChD;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,UAAU,CAAC;IACnB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,UAAU,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC1F,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,sDAAsD;IACtD,aAAa,CAAC,EAAE,YAAY,CAAC;IAC7B;mGAC+F;IAC/F,YAAY,EAAE,iBAAiB,CAAC;CACjC;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAwD/B"}

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

@@ -0,0 +1,232 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { loadConfig } from "../config.js";
+import { searchBM25 } from "../search/bm25.js";
+import { extractHookNames, REACT_STDLIB_HOOKS } from "./react-tools.js";
+import { resolveSearchHit, } from "./symbol-lookup-tools.js";
+import { findReferences } from "./symbol-reference-tools.js";
+import { requireBM25Index, requireCodeIndex, } from "./symbol-tool-internals.js";
+/** Format references as compact string for MCP output. Groups by file to avoid repeating paths. */
+export function formatRefsCompact(refs) {
+    if (refs.length === 0)
+        return "";
+    // Group by file
+    const groups = new Map();
+    for (const r of refs) {
+        let g = groups.get(r.file);
+        if (!g) {
+            g = [];
+            groups.set(r.file, g);
+        }
+        g.push(`  ${r.line}: ${r.context}`);
+    }
+    if (groups.size === refs.length) {
+        // Each file has 1 ref — flat is fine
+        return refs.map((r) => `${r.file}:${r.line}: ${r.context}`).join("\n");
+    }
+    const parts = [];
+    for (const [file, lines] of groups) {
+        parts.push(`${file}\n${lines.join("\n")}`);
+    }
+    return parts.join("\n");
+}
+/** Format a CodeSymbol as compact text: header line + source. ~70% less tokens than JSON. */
+export function formatSymbolCompact(sym) {
+    const loc = `${sym.file}:${sym.start_line}-${sym.end_line}`;
+    const sig = sym.signature ? ` ${sym.signature}` : "";
+    const header = `${loc} ${sym.kind} ${sym.name}${sig}`;
+    if (!sym.source)
+        return header;
+    return `${header}\n${sym.source}`;
+}
+/** Format multiple CodeSymbols as compact text, separated by blank lines. */
+export function formatSymbolsCompact(syms) {
+    return syms.map(formatSymbolCompact).join("\n\n");
+}
+/** Format ContextBundle as compact text. */
+export function formatBundleCompact(bundle) {
+    const parts = [];
+    parts.push(formatSymbolCompact(bundle.symbol));
+    if (bundle.imports.length > 0) {
+        parts.push(`\n--- imports ---\n${bundle.imports.join("\n")}`);
+    }
+    if (bundle.siblings.length > 0) {
+        const sibLines = bundle.siblings.map((s) => `  ${s.kind} ${s.name} :${s.start_line}-${s.end_line}`);
+        parts.push(`\n--- siblings ---\n${sibLines.join("\n")}`);
+    }
+    if (bundle.types_used.length > 0) {
+        parts.push(`\n--- types used ---\n${bundle.types_used.join(", ")}`);
+    }
+    return parts.join("");
+}
+/**
+ * Search for a symbol by query and return it with full source.
+ * Optionally includes references across the codebase.
+ */
+export async function findAndShow(repo, query, includeRefs) {
+    const bm25Index = await requireBM25Index(repo);
+    const config = loadConfig();
+    const results = searchBM25(bm25Index, query, 1, config.bm25FieldWeights);
+    const topResult = results[0];
+    if (!topResult)
+        return null;
+    const resolved = await resolveSearchHit(repo, topResult.symbol);
+    if (!resolved)
+        return null;
+    const { symbol: fullSymbol, ambiguity } = resolved;
+    if (includeRefs) {
+        const references = await findReferences(repo, fullSymbol.name);
+        return { symbol: fullSymbol, references, id_ambiguity: ambiguity };
+    }
+    return { symbol: fullSymbol, id_ambiguity: ambiguity };
+}
+/**
+ * Extract full import lines from file source.
+ */
+function extractImportLines(source) {
+    const lines = source.split("\n");
+    return lines.filter((line) => {
+        const trimmed = line.trim();
+        return trimmed.startsWith("import ") || (trimmed.startsWith("const ") && trimmed.includes("require("));
+    });
+}
+/**
+ * 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 async function getContextBundle(repo, symbolName) {
+    const bm25Index = await requireBM25Index(repo);
+    const config = loadConfig();
+    const results = searchBM25(bm25Index, symbolName, 1, config.bm25FieldWeights);
+    const topResult = results[0];
+    if (!topResult)
+        return null;
+    const index = await requireCodeIndex(repo);
+    // Get full symbol with source
+    const resolved = await resolveSearchHit(repo, topResult.symbol);
+    if (!resolved)
+        return null;
+    const { symbol: fullSymbol, ambiguity } = resolved;
+    // Read the file to extract imports
+    let fileSource;
+    try {
+        fileSource = await readFile(join(index.root, fullSymbol.file), "utf-8");
+    }
+    catch {
+        return {
+            symbol: fullSymbol,
+            imports: [],
+            siblings: [],
+            types_used: [],
+            id_ambiguity: ambiguity,
+        };
+    }
+    const imports = extractImportLines(fileSource);
+    // Get sibling symbols (other symbols in the same file)
+    const siblings = index.symbols
+        .filter((s) => s.file === fullSymbol.file && s.id !== fullSymbol.id)
+        .map((s) => ({
+        name: s.name,
+        kind: s.kind,
+        start_line: s.start_line,
+        end_line: s.end_line,
+    }));
+    // Extract type names used in the symbol's source
+    const typesUsed = extractTypesUsed(fullSymbol.source ?? "", index.symbols);
+    // React-specific enrichment for components
+    const bundle = {
+        symbol: fullSymbol,
+        imports,
+        siblings,
+        types_used: typesUsed,
+        id_ambiguity: ambiguity,
+    };
+    if (fullSymbol.kind === "component") {
+        bundle.react_context = buildReactContext(fullSymbol, index.symbols);
+    }
+    return bundle;
+}
+/**
+ * Build React-specific context for a component symbol:
+ * hooks used, child/parent components via JSX, wrapper pattern.
+ *
+ * Uses REACT_STDLIB_HOOKS imported from react-tools.js as the single source
+ * of truth for stdlib hook detection (CQ14 — no duplication).
+ */
+function buildReactContext(component, allSymbols) {
+    const source = component.source ?? "";
+    // Extract hooks used (uses shared extractHookNames from react-tools.ts — CQ14)
+    const hooks_used = [...extractHookNames(source)].map((name) => ({
+        name,
+        is_stdlib: REACT_STDLIB_HOOKS.has(name),
+    }));
+    // Extract child components from JSX (<PascalCase>)
+    const childSet = new Set();
+    const jsxPattern = /<([A-Z][a-zA-Z0-9_$]*)\b/g;
+    let m;
+    while ((m = jsxPattern.exec(source)) !== null) {
+        const name = m[1];
+        if (name !== component.name)
+            childSet.add(name);
+    }
+    const child_components = [...childSet].sort();
+    // Extract parent components: find other components whose source uses <ThisComponent>
+    const escapedComponentName = component.name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const ownPattern = new RegExp(`<${escapedComponentName}\\b`);
+    const parent_components = allSymbols
+        .filter((s) => s.kind === "component" &&
+        s.id !== component.id &&
+        s.name !== component.name &&
+        s.source &&
+        ownPattern.test(s.source))
+        .map((s) => s.name);
+    // Detect wrapper pattern from source — supports TypeScript generics:
+    // forwardRef<HTMLDivElement, Props>(...), memo<Props>(...) (Item 9)
+    let wrapper = null;
+    if (/\b(?:React\.)?memo\s*(?:<[^>]+>)?\s*\(/.test(source))
+        wrapper = "memo";
+    else if (/\b(?:React\.)?forwardRef\s*(?:<[^>]+>)?\s*\(/.test(source))
+        wrapper = "forwardRef";
+    else if (/\b(?:React\.)?lazy\s*(?:<[^>]+>)?\s*\(/.test(source))
+        wrapper = "lazy";
+    // Extract props type from signature: (props: MyProps) or ({ a, b }: Props)
+    let props_type = null;
+    const sig = component.signature ?? "";
+    // Pattern: (props: TypeName) or (arg: TypeName) or ({ ... }: TypeName)
+    const propsMatch = sig.match(/\(\s*(?:\{[^}]*\}|\w+)\s*:\s*([A-Z]\w*)/);
+    if (propsMatch) {
+        props_type = propsMatch[1];
+    }
+    // Resolve props interface body when type name found in the index (Tier 4 — Item 16).
+    // Look for an interface or type alias with the same name as props_type.
+    let props_interface_source = null;
+    if (props_type) {
+        const declarations = allSymbols.filter((s) => (s.kind === "interface" || s.kind === "type") && s.name === props_type);
+        const decl = declarations.find((s) => s.file === component.file) ?? declarations[0];
+        if (decl?.source) {
+            // Cap to 800 chars to keep bundle compact
+            props_interface_source = decl.source.length > 800
+                ? decl.source.slice(0, 800) + "..."
+                : decl.source;
+        }
+    }
+    return { props_type, props_interface_source, hooks_used, child_components, parent_components, wrapper };
+}
+/**
+ * Extract type/interface names referenced in source by matching against known symbols.
+ */
+function extractTypesUsed(source, allSymbols) {
+    const typeNames = new Set(allSymbols
+        .filter((s) => (s.kind === "interface" || s.kind === "type" || s.kind === "enum") && s.name.length >= 3)
+        .map((s) => s.name));
+    if (typeNames.size === 0)
+        return [];
+    const used = new Set();
+    for (const match of source.matchAll(/[$_\p{ID_Start}][$_\u200C\u200D\p{ID_Continue}]*/gu)) {
+        const name = match[0];
+        if (typeNames.has(name))
+            used.add(name);
+    }
+    return [...used].sort();
+}
+//# sourceMappingURL=symbol-context-tools.js.map