@codragraph/cli 1.6.2

package/dist/core/run-analyze.js

@@ -0,0 +1,315 @@
+/**
+ * Shared Analysis Orchestrator
+ *
+ * Extracts the core analysis pipeline from the CLI analyze command into a
+ * reusable function that can be called from both the CLI and a server-side
+ * worker process.
+ *
+ * IMPORTANT: This module must NEVER call process.exit(). The caller (CLI
+ * wrapper or server worker) is responsible for process lifecycle.
+ */
+import path from 'path';
+import fs from 'fs/promises';
+import { runPipelineFromRepo } from './ingestion/pipeline.js';
+import { initLbug, loadGraphToLbug, getLbugStats, executeQuery, executeWithReusedStatement, closeLbug, loadCachedEmbeddings, } from './lbug/lbug-adapter.js';
+import { getStoragePaths, saveMeta, loadMeta, addToGitignore, registerRepo, cleanupOldKuzuFiles, } from '../storage/repo-manager.js';
+import { getCurrentCommit, getRemoteUrl, hasGitDir, getInferredRepoName } from '../storage/git.js';
+import { recordAnalysisSnapshot } from './graphstore/index.js';
+import { generateAIContextFiles } from '../cli/ai-context.js';
+import { EMBEDDING_TABLE_NAME } from './lbug/schema.js';
+import { STALE_HASH_SENTINEL } from './lbug/schema.js';
+/** Threshold: auto-skip embeddings for repos with more nodes than this */
+const EMBEDDING_NODE_LIMIT = 50_000;
+export const PHASE_LABELS = {
+    extracting: 'Scanning files',
+    structure: 'Building structure',
+    parsing: 'Parsing code',
+    imports: 'Resolving imports',
+    calls: 'Tracing calls',
+    heritage: 'Extracting inheritance',
+    communities: 'Detecting communities',
+    processes: 'Detecting processes',
+    complete: 'Pipeline complete',
+    lbug: 'Loading into LadybugDB',
+    fts: 'Creating search indexes',
+    embeddings: 'Generating embeddings',
+    done: 'Done',
+};
+// ---------------------------------------------------------------------------
+// Main orchestrator
+// ---------------------------------------------------------------------------
+/**
+ * Run the full CodraGraph analysis pipeline.
+ *
+ * This is the shared core extracted from the CLI `analyze` command. It
+ * handles: pipeline execution, LadybugDB loading, FTS indexing, embedding
+ * generation, metadata persistence, and AI context file generation.
+ *
+ * The function communicates progress and log messages exclusively through
+ * the {@link AnalyzeCallbacks} interface — it never writes to stdout/stderr
+ * directly and never calls `process.exit()`.
+ */
+export async function runFullAnalysis(repoPath, options, callbacks) {
+    const log = (msg) => callbacks.onLog?.(msg);
+    const progress = (phase, percent, message) => callbacks.onProgress(phase, percent, message);
+    const { storagePath, lbugPath } = getStoragePaths(repoPath);
+    // Clean up stale KuzuDB files from before the LadybugDB migration.
+    const kuzuResult = await cleanupOldKuzuFiles(storagePath);
+    if (kuzuResult.found && kuzuResult.needsReindex) {
+        log('Migrating from KuzuDB to LadybugDB — rebuilding index...');
+    }
+    const repoHasGit = hasGitDir(repoPath);
+    const currentCommit = repoHasGit ? getCurrentCommit(repoPath) : '';
+    const existingMeta = await loadMeta(storagePath);
+    // ── Early-return: already up to date ──────────────────────────────
+    if (existingMeta && !options.force && existingMeta.lastCommit === currentCommit) {
+        // Non-git folders have currentCommit = '' — always rebuild since we can't detect changes
+        if (currentCommit !== '') {
+            return {
+                repoName: options.registryName ?? getInferredRepoName(repoPath) ?? path.basename(repoPath),
+                repoPath,
+                stats: existingMeta.stats ?? {},
+                alreadyUpToDate: true,
+            };
+        }
+    }
+    // ── Cache embeddings from existing index before rebuild ────────────
+    let cachedEmbeddingNodeIds = new Set();
+    let cachedEmbeddings = [];
+    if (options.embeddings && existingMeta && !options.force) {
+        try {
+            progress('embeddings', 0, 'Caching embeddings...');
+            await initLbug(lbugPath);
+            const cached = await loadCachedEmbeddings();
+            cachedEmbeddingNodeIds = cached.embeddingNodeIds;
+            cachedEmbeddings = cached.embeddings;
+            await closeLbug();
+        }
+        catch {
+            try {
+                await closeLbug();
+            }
+            catch {
+                /* swallow */
+            }
+        }
+    }
+    // ── Phase 1: Full Pipeline (0–60%) ────────────────────────────────
+    const pipelineResult = await runPipelineFromRepo(repoPath, (p) => {
+        const phaseLabel = PHASE_LABELS[p.phase] || p.phase;
+        const scaled = Math.round(p.percent * 0.6);
+        progress(p.phase, scaled, phaseLabel);
+    });
+    // ── Phase 2: LadybugDB (60–85%) ──────────────────────────────────
+    progress('lbug', 60, 'Loading into LadybugDB...');
+    await closeLbug();
+    const lbugFiles = [lbugPath, `${lbugPath}.wal`, `${lbugPath}.lock`];
+    for (const f of lbugFiles) {
+        try {
+            await fs.rm(f, { recursive: true, force: true });
+        }
+        catch {
+            /* swallow */
+        }
+    }
+    await initLbug(lbugPath);
+    try {
+        // All work after initLbug is wrapped in try/finally to ensure closeLbug()
+        // is called even if an error occurs — the module-level singleton DB handle
+        // must be released to avoid blocking subsequent invocations.
+        let lbugMsgCount = 0;
+        await loadGraphToLbug(pipelineResult.graph, pipelineResult.repoPath, storagePath, (msg) => {
+            lbugMsgCount++;
+            const pct = Math.min(84, 60 + Math.round((lbugMsgCount / (lbugMsgCount + 10)) * 24));
+            progress('lbug', pct, msg);
+        });
+        // ── Phase 2.5: Versioned-graph snapshot (best-effort) ────────────
+        // Phase 4 hook: snapshot the freshly-loaded graph into the
+        // content-addressed `.codragraph/graphstore/`. Failures here do NOT
+        // break analyze — the user keeps a working LadybugDB index either
+        // way, they just don't get a versioning record for this run.
+        let graphstoreCurrentBranch;
+        let graphstoreHeadCommit;
+        try {
+            const snapshotResult = await recordAnalysisSnapshot({
+                storagePath,
+                indexedRepoCommit: currentCommit || undefined,
+                onSkipTable: (tableName, err) => {
+                    log(`graphstore: skipped table "${tableName}": ${err instanceof Error ? err.message : String(err)}`);
+                },
+            });
+            if (snapshotResult) {
+                graphstoreCurrentBranch = snapshotResult.branch;
+                graphstoreHeadCommit = snapshotResult.commitId;
+                log(`graphstore: snapshot ${snapshotResult.snapshotId.slice(0, 19)}…  ` +
+                    `commit ${snapshotResult.commitId.slice(0, 19)}…  ` +
+                    `branch ${snapshotResult.branch}`);
+            }
+        }
+        catch (err) {
+            log(`graphstore: snapshot failed (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
+        }
+        // ── Phase 3: FTS (85–90%) ─────────────────────────────────────────
+        // FTS indexes are created lazily on first `query`/`context` call instead
+        // of eagerly here. On small repos / CI runners the LadybugDB
+        // CREATE_FTS_INDEX cost is ~440 ms × 5 (≈2 s) regardless of table size,
+        // which dominated `analyze` runtime and pushed Windows CI past its
+        // 30 s test budget. Lazy creation is implemented in
+        // `core/search/bm25-index.ts` via `ensureFTSIndex`.
+        // ── Phase 3.5: Re-insert cached embeddings ────────────────────────
+        if (cachedEmbeddings.length > 0) {
+            const cachedDims = cachedEmbeddings[0].embedding.length;
+            const { EMBEDDING_DIMS } = await import('./lbug/schema.js');
+            if (cachedDims !== EMBEDDING_DIMS) {
+                // Dimensions changed (e.g. switched embedding model) — discard cache and re-embed all
+                log(`Embedding dimensions changed (${cachedDims}d -> ${EMBEDDING_DIMS}d), discarding cache`);
+                cachedEmbeddings = [];
+                cachedEmbeddingNodeIds = new Set();
+            }
+            else {
+                progress('embeddings', 88, `Restoring ${cachedEmbeddings.length} cached embeddings...`);
+                const { batchInsertEmbeddings: batchInsert } = await import('./embeddings/embedding-pipeline.js');
+                const EMBED_BATCH = 200;
+                for (let i = 0; i < cachedEmbeddings.length; i += EMBED_BATCH) {
+                    const batch = cachedEmbeddings.slice(i, i + EMBED_BATCH);
+                    try {
+                        await batchInsert(executeWithReusedStatement, batch);
+                    }
+                    catch {
+                        /* some may fail if node was removed, that's fine */
+                    }
+                }
+            }
+        }
+        // ── Phase 4: Embeddings (90–98%) ──────────────────────────────────
+        const stats = await getLbugStats();
+        let embeddingSkipped = true;
+        if (options.embeddings) {
+            if (stats.nodes <= EMBEDDING_NODE_LIMIT) {
+                embeddingSkipped = false;
+            }
+        }
+        if (!embeddingSkipped) {
+            const { isHttpMode } = await import('./embeddings/http-client.js');
+            const httpMode = isHttpMode();
+            progress('embeddings', 90, httpMode ? 'Connecting to embedding endpoint...' : 'Loading embedding model...');
+            const { runEmbeddingPipeline } = await import('./embeddings/embedding-pipeline.js');
+            // Build a Map<nodeId, contentHash> from cached embeddings for incremental mode
+            let existingEmbeddings;
+            if (cachedEmbeddingNodeIds.size > 0) {
+                existingEmbeddings = new Map();
+                for (const e of cachedEmbeddings) {
+                    existingEmbeddings.set(e.nodeId, e.contentHash ?? STALE_HASH_SENTINEL);
+                }
+            }
+            const { readServerMapping } = await import('./embeddings/server-mapping.js');
+            const projectName = path.basename(repoPath);
+            const serverName = await readServerMapping(projectName);
+            await runEmbeddingPipeline(executeQuery, executeWithReusedStatement, (p) => {
+                const scaled = 90 + Math.round((p.percent / 100) * 8);
+                const label = p.phase === 'loading-model'
+                    ? httpMode
+                        ? 'Connecting to embedding endpoint...'
+                        : 'Loading embedding model...'
+                    : `Embedding ${p.nodesProcessed || 0}/${p.totalNodes || '?'}`;
+                progress('embeddings', scaled, label);
+            }, {}, cachedEmbeddingNodeIds.size > 0 ? cachedEmbeddingNodeIds : undefined, { repoName: projectName, serverName }, existingEmbeddings);
+        }
+        // ── Phase 5: Finalize (98–100%) ───────────────────────────────────
+        progress('done', 98, 'Saving metadata...');
+        // Count embeddings in the index (cached + newly generated)
+        let embeddingCount = 0;
+        try {
+            const embResult = await executeQuery(`MATCH (e:${EMBEDDING_TABLE_NAME}) RETURN count(e) AS cnt`);
+            embeddingCount = embResult?.[0]?.cnt ?? 0;
+        }
+        catch {
+            /* table may not exist if embeddings never ran */
+        }
+        const meta = {
+            repoPath,
+            lastCommit: currentCommit,
+            indexedAt: new Date().toISOString(),
+            // Captured here (not at registration) so it travels with the
+            // on-disk meta.json — sibling-clone fingerprinting works for
+            // out-of-tree consumers (group-status, future tooling) without
+            // a second git shellout. `undefined` when the repo has no
+            // origin remote, which is fine: paths-only repos behave as
+            // before.
+            remoteUrl: hasGitDir(repoPath) ? getRemoteUrl(repoPath) : undefined,
+            // Phase 4: written when the best-effort graphstore snapshot
+            // succeeded; absent otherwise so older meta consumers that don't
+            // know about these fields keep working.
+            currentBranch: graphstoreCurrentBranch,
+            headCommit: graphstoreHeadCommit,
+            stats: {
+                files: pipelineResult.totalFileCount,
+                nodes: stats.nodes,
+                edges: stats.edges,
+                communities: pipelineResult.communityResult?.stats.totalCommunities,
+                processes: pipelineResult.processResult?.stats.totalProcesses,
+                embeddings: embeddingCount,
+            },
+        };
+        await saveMeta(storagePath, meta);
+        // Forward the --name alias and the registry-collision bypass bit.
+        // `allowDuplicateName` is its own concern — independent from the
+        // pipeline `force` above. The CLI maps it from
+        // `--allow-duplicate-name` only; `--force` and `--skills` both
+        // trigger pipeline re-run but never bypass the registry guard.
+        // The returned name is the one actually written to the registry
+        // (after applying the precedence chain in registerRepo) — reuse it
+        // so AGENTS.md / skill files reference the same name MCP clients
+        // will look up (#979).
+        const projectName = await registerRepo(repoPath, meta, {
+            name: options.registryName,
+            allowDuplicateName: options.allowDuplicateName,
+        });
+        // Only attempt to update .gitignore when a .git directory is present.
+        if (hasGitDir(repoPath)) {
+            await addToGitignore(repoPath);
+        }
+        // ── Generate AI context files (best-effort) ───────────────────────
+        let aggregatedClusterCount = 0;
+        if (pipelineResult.communityResult?.communities) {
+            const groups = new Map();
+            for (const c of pipelineResult.communityResult.communities) {
+                const label = c.heuristicLabel || c.label || 'Unknown';
+                groups.set(label, (groups.get(label) || 0) + c.symbolCount);
+            }
+            aggregatedClusterCount = Array.from(groups.values()).filter((count) => count >= 5).length;
+        }
+        try {
+            await generateAIContextFiles(repoPath, storagePath, projectName, {
+                files: pipelineResult.totalFileCount,
+                nodes: stats.nodes,
+                edges: stats.edges,
+                communities: pipelineResult.communityResult?.stats.totalCommunities,
+                clusters: aggregatedClusterCount,
+                processes: pipelineResult.processResult?.stats.totalProcesses,
+            }, undefined, { skipAgentsMd: options.skipAgentsMd, noStats: options.noStats });
+        }
+        catch {
+            // Best-effort — don't fail the entire analysis for context file issues
+        }
+        // ── Close LadybugDB ──────────────────────────────────────────────
+        await closeLbug();
+        progress('done', 100, 'Done');
+        return {
+            repoName: projectName,
+            repoPath,
+            stats: meta.stats,
+            pipelineResult,
+        };
+    }
+    catch (err) {
+        // Ensure LadybugDB is closed even on error
+        try {
+            await closeLbug();
+        }
+        catch {
+            /* swallow */
+        }
+        throw err;
+    }
+}

package/dist/core/search/bm25-index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Full-Text Search via LadybugDB FTS
+ *
+ * Uses LadybugDB's built-in full-text search indexes for keyword-based search.
+ * Always reads from the database (no cached state to drift).
+ *
+ * FTS indexes are created lazily on first query (via `ensureFTSIndex`) — see
+ * `lbug-adapter.ts` for the rationale. This keeps `analyze` fast (the
+ * ~440 ms × 5 LadybugDB CREATE_FTS_INDEX cost dominates pipeline time on
+ * small repos / CI runners) at the cost of paying that overhead on the
+ * first `query`/`context` call in a session.
+ */
+export interface BM25SearchResult {
+    filePath: string;
+    score: number;
+    rank: number;
+    nodeIds?: string[];
+}
+/**
+ * Drop all ensured-FTS cache entries for a given repoId.
+ *
+ * Called from the pool-close listener so that a pool teardown / recreation
+ * forces the next `searchFTSFromLbug` call to re-issue `CREATE_FTS_INDEX`
+ * against the fresh connection rather than trust stale ensure-state from a
+ * previous pool lifetime.
+ *
+ * Exported for tests; the listener wiring is internal.
+ */
+export declare function invalidateEnsuredFTSForRepo(repoId: string): void;
+/**
+ * Search using LadybugDB's built-in FTS (always fresh, reads from disk)
+ *
+ * Queries multiple node tables (File, Function, Class, Method) in parallel
+ * and merges results by filePath, summing scores for the same file.
+ *
+ * @param query - Search query string
+ * @param limit - Maximum results
+ * @param repoId - If provided, queries will be routed via the MCP connection pool
+ * @returns Ranked search results from FTS indexes
+ */
+export declare const searchFTSFromLbug: (query: string, limit?: number, repoId?: string) => Promise<BM25SearchResult[]>;

package/dist/core/search/bm25-index.js

@@ -0,0 +1,209 @@
+/**
+ * Full-Text Search via LadybugDB FTS
+ *
+ * Uses LadybugDB's built-in full-text search indexes for keyword-based search.
+ * Always reads from the database (no cached state to drift).
+ *
+ * FTS indexes are created lazily on first query (via `ensureFTSIndex`) — see
+ * `lbug-adapter.ts` for the rationale. This keeps `analyze` fast (the
+ * ~440 ms × 5 LadybugDB CREATE_FTS_INDEX cost dominates pipeline time on
+ * small repos / CI runners) at the cost of paying that overhead on the
+ * first `query`/`context` call in a session.
+ */
+import { queryFTS, ensureFTSIndex } from '../lbug/lbug-adapter.js';
+/**
+ * FTS schema served by `searchFTSFromLbug`. Centralised so that both the
+ * CLI/pipeline path and the MCP pool path use identical (table, index,
+ * properties) tuples and the lazy-create logic stays in one place.
+ */
+const FTS_INDEXES = [
+    { table: 'File', indexName: 'file_fts', properties: ['name', 'content'] },
+    { table: 'Function', indexName: 'function_fts', properties: ['name', 'content'] },
+    { table: 'Class', indexName: 'class_fts', properties: ['name', 'content'] },
+    { table: 'Method', indexName: 'method_fts', properties: ['name', 'content'] },
+    { table: 'Interface', indexName: 'interface_fts', properties: ['name', 'content'] },
+];
+/**
+ * Per-process cache for the MCP pool path: tracks which `(repoId, table)`
+ * pairs have been ensured. The CLI/pipeline path gets its own cache inside
+ * `lbug-adapter.ts` keyed by table/index, scoped to the singleton connection.
+ *
+ * IMPORTANT: an entry is added ONLY when the index was confirmed to exist
+ * (CREATE_FTS_INDEX succeeded, or failed with `'already exists'`). Other
+ * failures (transient lock errors, missing extension, etc.) leave the key
+ * unset so the next query retries instead of silently caching the failure.
+ *
+ * Entries for a given repoId are invalidated when its pool is closed —
+ * see the `addPoolCloseListener` registration in `searchFTSFromLbug`.
+ */
+const ensuredPoolFTS = new Set();
+/**
+ * Drop all ensured-FTS cache entries for a given repoId.
+ *
+ * Called from the pool-close listener so that a pool teardown / recreation
+ * forces the next `searchFTSFromLbug` call to re-issue `CREATE_FTS_INDEX`
+ * against the fresh connection rather than trust stale ensure-state from a
+ * previous pool lifetime.
+ *
+ * Exported for tests; the listener wiring is internal.
+ */
+export function invalidateEnsuredFTSForRepo(repoId) {
+    const prefix = `${repoId}:`;
+    for (const key of ensuredPoolFTS) {
+        if (key.startsWith(prefix))
+            ensuredPoolFTS.delete(key);
+    }
+}
+/**
+ * Tracks whether we've already wired the pool-close listener for this
+ * process. The pool adapter is dynamically imported, so registration
+ * happens lazily on the first MCP-pool-backed FTS query.
+ */
+let poolCloseListenerRegistered = false;
+function registerPoolCloseListenerOnce(addPoolCloseListener) {
+    if (poolCloseListenerRegistered)
+        return;
+    poolCloseListenerRegistered = true;
+    addPoolCloseListener((repoId) => invalidateEnsuredFTSForRepo(repoId));
+}
+async function ensureFTSIndexViaExecutor(executor, repoId, table, indexName, properties) {
+    const key = `${repoId}:${table}:${indexName}`;
+    if (ensuredPoolFTS.has(key))
+        return;
+    const propList = properties.map((p) => `'${p}'`).join(', ');
+    try {
+        await executor(`CALL CREATE_FTS_INDEX('${table}', '${indexName}', [${propList}], stemmer := 'porter')`);
+        // Index was created successfully — safe to cache.
+        ensuredPoolFTS.add(key);
+    }
+    catch (e) {
+        // 'already exists' is the happy path (index persists on disk between
+        // process invocations) — cache it. Anything else is treated as a
+        // transient failure: surface a one-time warning and leave the key
+        // unset so the NEXT query retries rather than silently using a
+        // cached failure (which previously disabled BM25 for the whole
+        // process for that repo).
+        const msg = String(e?.message ?? '');
+        if (msg.includes('already exists')) {
+            ensuredPoolFTS.add(key);
+        }
+        else {
+            console.warn(`[codragraph] FTS index ensure failed for repo "${repoId}" table "${table}" ` +
+                `(index "${indexName}"): ${msg || e}. Will retry on next query.`);
+        }
+    }
+}
+/**
+ * Execute a single FTS query via a custom executor (for MCP connection pool).
+ * Returns the same shape as core queryFTS (from LadybugDB adapter).
+ */
+async function queryFTSViaExecutor(executor, tableName, indexName, query, limit) {
+    // Escape single quotes and backslashes to prevent Cypher injection
+    const escapedQuery = query.replace(/\\/g, '\\\\').replace(/'/g, "''");
+    const cypher = `
+    CALL QUERY_FTS_INDEX('${tableName}', '${indexName}', '${escapedQuery}', conjunctive := false)
+    RETURN node, score
+    ORDER BY score DESC
+    LIMIT ${limit}
+  `;
+    try {
+        const rows = await executor(cypher);
+        return rows.map((row) => {
+            const node = row.node || row[0] || {};
+            const score = row.score ?? row[1] ?? 0;
+            return {
+                filePath: node.filePath || '',
+                score: typeof score === 'number' ? score : parseFloat(score) || 0,
+                nodeId: node.nodeId || node.id || '',
+            };
+        });
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Search using LadybugDB's built-in FTS (always fresh, reads from disk)
+ *
+ * Queries multiple node tables (File, Function, Class, Method) in parallel
+ * and merges results by filePath, summing scores for the same file.
+ *
+ * @param query - Search query string
+ * @param limit - Maximum results
+ * @param repoId - If provided, queries will be routed via the MCP connection pool
+ * @returns Ranked search results from FTS indexes
+ */
+export const searchFTSFromLbug = async (query, limit = 20, repoId) => {
+    let fileResults, functionResults, classResults, methodResults, interfaceResults;
+    if (repoId) {
+        // Use MCP connection pool via dynamic import
+        // IMPORTANT: FTS queries run sequentially to avoid connection contention.
+        // The MCP pool supports multiple connections, but FTS is best run serially.
+        const poolMod = await import('../lbug/pool-adapter.js');
+        const { executeQuery, addPoolCloseListener } = poolMod;
+        // Register the pool-close listener lazily on first use so a teardown of
+        // the pool entry (LRU eviction, idle timeout, explicit close) drops the
+        // matching `ensuredPoolFTS` entries. Without this, stale ensure-state
+        // can outlive the pool that produced it.
+        registerPoolCloseListenerOnce(addPoolCloseListener);
+        const executor = (cypher) => executeQuery(repoId, cypher);
+        // Lazy-create FTS indexes on first query for this repo (analyze no longer
+        // creates them up-front, so we ensure them here). Cached per-process.
+        for (const { table, indexName, properties } of FTS_INDEXES) {
+            await ensureFTSIndexViaExecutor(executor, repoId, table, indexName, properties);
+        }
+        fileResults = await queryFTSViaExecutor(executor, 'File', 'file_fts', query, limit);
+        functionResults = await queryFTSViaExecutor(executor, 'Function', 'function_fts', query, limit);
+        classResults = await queryFTSViaExecutor(executor, 'Class', 'class_fts', query, limit);
+        methodResults = await queryFTSViaExecutor(executor, 'Method', 'method_fts', query, limit);
+        interfaceResults = await queryFTSViaExecutor(executor, 'Interface', 'interface_fts', query, limit);
+    }
+    else {
+        // Use core lbug adapter (CLI / pipeline context) — also sequential for safety.
+        // Lazy-create FTS indexes on first query (analyze no longer does it).
+        for (const { table, indexName, properties } of FTS_INDEXES) {
+            await ensureFTSIndex(table, indexName, [...properties]).catch(() => { });
+        }
+        fileResults = await queryFTS('File', 'file_fts', query, limit, false).catch(() => []);
+        functionResults = await queryFTS('Function', 'function_fts', query, limit, false).catch(() => []);
+        classResults = await queryFTS('Class', 'class_fts', query, limit, false).catch(() => []);
+        methodResults = await queryFTS('Method', 'method_fts', query, limit, false).catch(() => []);
+        interfaceResults = await queryFTS('Interface', 'interface_fts', query, limit, false).catch(() => []);
+    }
+    // Collect all node scores per filePath to track which nodes actually matched
+    const fileNodeScores = new Map();
+    const addResults = (results) => {
+        for (const r of results) {
+            if (!fileNodeScores.has(r.filePath))
+                fileNodeScores.set(r.filePath, []);
+            fileNodeScores.get(r.filePath).push({ score: r.score, nodeId: r.nodeId });
+        }
+    };
+    addResults(fileResults);
+    addResults(functionResults);
+    addResults(classResults);
+    addResults(methodResults);
+    addResults(interfaceResults);
+    // Sum the top-3 highest-scoring nodes per file and collect their nodeIds.
+    // Summing all nodes naively inflates scores for files with many mediocre
+    // matches (e.g. test files) over files with a single highly-relevant symbol.
+    const merged = new Map();
+    for (const [filePath, entries] of fileNodeScores) {
+        const top3 = [...entries].sort((a, b) => b.score - a.score).slice(0, 3);
+        merged.set(filePath, {
+            filePath,
+            score: top3.reduce((acc, e) => acc + e.score, 0),
+            nodeIds: top3.map((e) => e.nodeId).filter((id) => id),
+        });
+    }
+    // Sort by score descending and add rank
+    const sorted = Array.from(merged.values())
+        .sort((a, b) => b.score - a.score)
+        .slice(0, limit);
+    return sorted.map((r, index) => ({
+        filePath: r.filePath,
+        score: r.score,
+        rank: index + 1,
+        nodeIds: r.nodeIds,
+    }));
+};

package/dist/core/search/hybrid-search.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Hybrid Search with Reciprocal Rank Fusion (RRF)
+ *
+ * Combines BM25 (keyword) and semantic (embedding) search results.
+ * Uses RRF to merge rankings without needing score normalization.
+ *
+ * This is the same approach used by Elasticsearch, Pinecone, and other
+ * production search systems.
+ */
+import { type BM25SearchResult } from './bm25-index.js';
+import type { SemanticSearchResult } from '../embeddings/types.js';
+export interface HybridSearchResult {
+    filePath: string;
+    score: number;
+    rank: number;
+    sources: ('bm25' | 'semantic')[];
+    nodeId?: string;
+    name?: string;
+    label?: string;
+    startLine?: number;
+    endLine?: number;
+    bm25Score?: number;
+    semanticScore?: number;
+}
+/**
+ * Perform hybrid search combining BM25 and semantic results
+ *
+ * @param bm25Results - Results from BM25 keyword search
+ * @param semanticResults - Results from semantic/embedding search
+ * @param limit - Maximum results to return
+ * @returns Merged and re-ranked results
+ */
+export declare const mergeWithRRF: (bm25Results: BM25SearchResult[], semanticResults: SemanticSearchResult[], limit?: number) => HybridSearchResult[];
+/**
+ * Check if hybrid search is available
+ * LadybugDB FTS is always available once the database is initialized.
+ * Semantic search is optional - hybrid works with just FTS if embeddings aren't ready.
+ */
+export declare const isHybridSearchReady: () => boolean;
+/**
+ * Format hybrid results for LLM consumption
+ */
+export declare const formatHybridResults: (results: HybridSearchResult[]) => string;
+/**
+ * Execute BM25 + semantic search and merge with RRF.
+ * Uses LadybugDB FTS for always-fresh BM25 results (no cached data).
+ * The semanticSearch function is injected to keep this module environment-agnostic.
+ */
+export declare const hybridSearch: (query: string, limit: number, executeQuery: (cypher: string) => Promise<any[]>, semanticSearch: (executeQuery: (cypher: string) => Promise<any[]>, query: string, k?: number) => Promise<SemanticSearchResult[]>) => Promise<HybridSearchResult[]>;