@zuvia-software-solutions/code-mapper 2.3.11 → 2.4.0

package/dist/cli/analyze.js

@@ -269,10 +269,68 @@ export const analyzeCommand = async (inputPath, options) => {
     recordPhase('search-text');
     updateBar(84, 'Building search index...');
     populateSearchText(db);
+    // Phase 2.7: Build refs table (identifier occurrence index)
+    recordPhase('refs');
+    updateBar(85, 'Building refs index...');
+    {
+        const { clearRefs, insertRefsBatch, clearFileWords, upsertFileWords } = await import('../core/db/adapter.js');
+        const fsRef = await import('fs/promises');
+        clearRefs(db);
+        clearFileWords(db);
+        // Scan all source files for identifier occurrences
+        const STOP_WORDS = new Set(['the', 'and', 'for', 'from', 'with', 'this', 'that', 'have', 'has', 'not', 'are', 'was', 'were', 'been', 'being', 'will', 'would', 'could', 'should', 'may', 'might', 'can', 'does', 'did', 'let', 'var', 'const', 'new', 'return', 'function', 'class', 'import', 'export', 'default', 'void', 'null', 'undefined', 'true', 'false', 'else', 'case', 'break', 'continue', 'while', 'throw', 'catch', 'try', 'finally', 'async', 'await', 'yield', 'typeof', 'instanceof', 'delete', 'switch', 'interface', 'type', 'enum', 'extends', 'implements', 'static', 'private', 'public', 'protected', 'abstract', 'readonly', 'override', 'declare', 'module', 'namespace', 'require', 'string', 'number', 'boolean', 'object', 'any', 'never', 'unknown', 'symbol']);
+        const SRC_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx', '.py', '.go', '.rs', '.java', '.c', '.h', '.cpp', '.hpp', '.cs', '.rb', '.php', '.kt', '.swift', '.mts', '.mjs', '.cts', '.cjs']);
+        const identRegex = /\b[a-zA-Z_]\w{2,}\b/g;
+        const wordRegex = /\b[a-zA-Z]\w{2,}\b/g;
+        // Get all file paths from the nodes table
+        const fileRows = db.prepare("SELECT DISTINCT filePath FROM nodes WHERE label = 'File'").all();
+        let refsBuilt = 0;
+        for (const { filePath } of fileRows) {
+            const ext = path.extname(filePath).toLowerCase();
+            if (!SRC_EXTENSIONS.has(ext))
+                continue;
+            let content;
+            try {
+                content = await fsRef.readFile(path.resolve(repoPath, filePath), 'utf-8');
+            }
+            catch {
+                continue;
+            }
+            // Build refs (identifier occurrences — skip language keywords)
+            const refs = [];
+            const lines = content.split('\n');
+            for (let lineIdx = 0; lineIdx < lines.length; lineIdx++) {
+                let match;
+                identRegex.lastIndex = 0;
+                while ((match = identRegex.exec(lines[lineIdx])) !== null) {
+                    if (!STOP_WORDS.has(match[0].toLowerCase())) {
+                        refs.push({ symbol: match[0], filePath, line: lineIdx });
+                    }
+                }
+            }
+            if (refs.length > 0)
+                insertRefsBatch(db, refs);
+            // Build file_words (conceptual search)
+            const wordSet = new Set();
+            let wMatch;
+            wordRegex.lastIndex = 0;
+            while ((wMatch = wordRegex.exec(content)) !== null) {
+                const w = wMatch[0].toLowerCase();
+                if (!STOP_WORDS.has(w))
+                    wordSet.add(w);
+            }
+            if (wordSet.size > 0)
+                upsertFileWords(db, filePath, [...wordSet].join(' '));
+            refsBuilt++;
+            if (refsBuilt % 500 === 0) {
+                updateBar(85, `Building refs index... (${refsBuilt}/${fileRows.length})`);
+            }
+        }
+    }
     // Phase 3: FTS (85-90%)
     // FTS5 is auto-created by schema triggers — no manual index creation needed
     recordPhase('fts');
-    updateBar(85, 'Search indexes ready');
+    updateBar(87, 'Search indexes ready');
     // Phase 3.5: Re-insert cached embeddings
     recordPhase('restore-embeddings');
     if (cachedEmbeddings.length > 0) {

package/dist/core/db/adapter.d.ts

@@ -80,11 +80,12 @@ export declare function searchFTS(db: Database.Database, query: string, limit?:
     filePath: string;
     score: number;
 }>;
-/** Get node count, edge count, and embedding count. */
+/** Get node count, edge count, embedding count, and refs count. */
 export declare function getStats(db: Database.Database): {
     nodes: number;
     edges: number;
     embeddings: number;
+    refs: number;
 };
 /** Batch insert nodes in a single transaction. */
 export declare function insertNodesBatch(db: Database.Database, nodes: readonly NodeInsert[]): void;
@@ -104,6 +105,39 @@ export declare function insertEmbeddingsBatch(db: Database.Database, items: read
 }[]): void;
 /** Get all textHashes from the embeddings table for hash-based skip on re-index */
 export declare function getEmbeddingHashes(db: Database.Database): Map<string, string>;
+/** Bulk-insert identifier references */
+export declare function insertRefsBatch(db: Database.Database, refs: ReadonlyArray<{
+    symbol: string;
+    filePath: string;
+    line: number;
+}>): void;
+/** Delete all refs for a given file (used by incremental refresh) */
+export declare function deleteRefsByFile(db: Database.Database, filePath: string): void;
+/** Find all files referencing a symbol name */
+export declare function findRefsBySymbol(db: Database.Database, symbol: string, limit?: number): Array<{
+    filePath: string;
+    line: number;
+}>;
+/** Count total refs in the index */
+export declare function countRefs(db: Database.Database): number;
+/** Delete all refs (used before full rebuild) */
+export declare function clearRefs(db: Database.Database): void;
+/** Insert or replace file-level word index */
+export declare function upsertFileWords(db: Database.Database, filePath: string, words: string): void;
+/** Bulk insert file words in a transaction */
+export declare function insertFileWordsBatch(db: Database.Database, entries: ReadonlyArray<{
+    filePath: string;
+    words: string;
+}>): void;
+/** Delete file words for a given file */
+export declare function deleteFileWordsByFile(db: Database.Database, filePath: string): void;
+/** Search file_words_fts for conceptual matches, returns file paths ranked by relevance */
+export declare function searchFileWords(db: Database.Database, query: string, limit?: number): Array<{
+    filePath: string;
+    score: number;
+}>;
+/** Clear all file words (used before full rebuild) */
+export declare function clearFileWords(db: Database.Database): void;
 /** Escape a string for use in SQL single-quoted literals. */
 export declare function escapeSql(value: string): string;
 /** Execute a raw SQL query and return rows. */

package/dist/core/db/adapter.js

@@ -347,12 +347,13 @@ export function searchFTS(db, query, limit = 20) {
 // ---------------------------------------------------------------------------
 // Stats
 // ---------------------------------------------------------------------------
-/** Get node count, edge count, and embedding count. */
+/** Get node count, edge count, embedding count, and refs count. */
 export function getStats(db) {
     return {
         nodes: countNodes(db),
         edges: countEdges(db),
         embeddings: countEmbeddings(db),
+        refs: countRefs(db),
     };
 }
 // ---------------------------------------------------------------------------
@@ -513,6 +514,86 @@ export function getEmbeddingHashes(db) {
     return map;
 }
 // ---------------------------------------------------------------------------
+// Refs (identifier occurrence index)
+// ---------------------------------------------------------------------------
+/** Bulk-insert identifier references */
+export function insertRefsBatch(db, refs) {
+    if (refs.length === 0)
+        return;
+    const stmt = db.prepare('INSERT INTO refs (symbol, filePath, line) VALUES (?, ?, ?)');
+    const tx = db.transaction(() => {
+        for (const ref of refs) {
+            stmt.run(ref.symbol, ref.filePath, ref.line);
+        }
+    });
+    tx();
+}
+/** Delete all refs for a given file (used by incremental refresh) */
+export function deleteRefsByFile(db, filePath) {
+    db.prepare('DELETE FROM refs WHERE filePath = ?').run(filePath);
+}
+/** Find all files referencing a symbol name */
+export function findRefsBySymbol(db, symbol, limit = 200) {
+    return db.prepare('SELECT DISTINCT filePath, line FROM refs WHERE symbol = ? LIMIT ?').all(symbol, limit);
+}
+/** Count total refs in the index */
+export function countRefs(db) {
+    const row = db.prepare('SELECT COUNT(*) as cnt FROM refs').get();
+    return row?.cnt ?? 0;
+}
+/** Delete all refs (used before full rebuild) */
+export function clearRefs(db) {
+    db.prepare('DELETE FROM refs').run();
+}
+// ---------------------------------------------------------------------------
+// File Words (conceptual search index)
+// ---------------------------------------------------------------------------
+/** Insert or replace file-level word index */
+export function upsertFileWords(db, filePath, words) {
+    db.prepare('INSERT OR REPLACE INTO file_words (filePath, words) VALUES (?, ?)').run(filePath, words);
+}
+/** Bulk insert file words in a transaction */
+export function insertFileWordsBatch(db, entries) {
+    if (entries.length === 0)
+        return;
+    const stmt = db.prepare('INSERT OR REPLACE INTO file_words (filePath, words) VALUES (?, ?)');
+    const tx = db.transaction(() => {
+        for (const entry of entries) {
+            stmt.run(entry.filePath, entry.words);
+        }
+    });
+    tx();
+}
+/** Delete file words for a given file */
+export function deleteFileWordsByFile(db, filePath) {
+    db.prepare('DELETE FROM file_words WHERE filePath = ?').run(filePath);
+}
+/** Search file_words_fts for conceptual matches, returns file paths ranked by relevance */
+export function searchFileWords(db, query, limit = 20) {
+    let safeQuery = query.replace(/"/g, '""').replace(/[*(){}[\]^~\\:]/g, ' ').trim();
+    if (!safeQuery)
+        return [];
+    const words = safeQuery.split(/\s+/).filter(w => w.length > 2);
+    if (words.length === 0)
+        return [];
+    safeQuery = words.join(' OR ');
+    try {
+        return db.prepare(`SELECT fw.filePath, rank as score
+       FROM file_words_fts fts
+       JOIN file_words fw ON fw.rowid = fts.rowid
+       WHERE file_words_fts MATCH ?
+       ORDER BY rank
+       LIMIT ?`).all(safeQuery, limit);
+    }
+    catch {
+        return [];
+    }
+}
+/** Clear all file words (used before full rebuild) */
+export function clearFileWords(db) {
+    db.prepare('DELETE FROM file_words').run();
+}
+// ---------------------------------------------------------------------------
 // Raw SQL escape (for dynamic queries in local-backend.ts)
 // ---------------------------------------------------------------------------
 /** Escape a string for use in SQL single-quoted literals. */

package/dist/core/db/schema.d.ts

@@ -68,6 +68,17 @@ export interface EmbeddingRow {
     readonly embedding: Buffer;
     readonly textHash: string | null;
 }
+/** A reference occurrence as stored in the `refs` table */
+export interface RefsRow {
+    readonly symbol: string;
+    readonly filePath: string;
+    readonly line: number;
+}
+/** A file-level word index row as stored in the `file_words` table */
+export interface FileWordsRow {
+    readonly filePath: string;
+    readonly words: string;
+}
 /** Fields required to insert a node */
 export interface NodeInsert {
     readonly id: NodeId;
@@ -107,4 +118,4 @@ export interface EdgeInsert {
 }
 /** Legacy edge table name constant (kept for compatibility) */
 export declare const REL_TABLE_NAME = "CodeRelation";
-export declare const SCHEMA_SQL = "\n-- Nodes: unified table for all code elements\nCREATE TABLE IF NOT EXISTS nodes (\n  id TEXT PRIMARY KEY,\n  label TEXT NOT NULL,\n  name TEXT NOT NULL DEFAULT '',\n  filePath TEXT NOT NULL DEFAULT '',\n  startLine INTEGER,\n  endLine INTEGER,\n  isExported INTEGER,\n  content TEXT NOT NULL DEFAULT '',\n  description TEXT NOT NULL DEFAULT '',\n  heuristicLabel TEXT,\n  cohesion REAL,\n  symbolCount INTEGER,\n  keywords TEXT,\n  enrichedBy TEXT,\n  processType TEXT,\n  stepCount INTEGER,\n  communities TEXT,\n  entryPointId TEXT,\n  terminalId TEXT,\n  parameterCount INTEGER,\n  returnType TEXT,\n  nameExpanded TEXT DEFAULT '',\n  searchText TEXT DEFAULT ''\n);\n\nCREATE INDEX IF NOT EXISTS idx_nodes_label ON nodes(label);\nCREATE INDEX IF NOT EXISTS idx_nodes_name ON nodes(name);\nCREATE INDEX IF NOT EXISTS idx_nodes_filePath ON nodes(filePath);\nCREATE INDEX IF NOT EXISTS idx_nodes_label_name ON nodes(label, name);\nCREATE INDEX IF NOT EXISTS idx_nodes_filePath_lines ON nodes(filePath, startLine, endLine);\n\n-- Edges: single table for all relationships\nCREATE TABLE IF NOT EXISTS edges (\n  id TEXT PRIMARY KEY,\n  sourceId TEXT NOT NULL,\n  targetId TEXT NOT NULL,\n  type TEXT NOT NULL,\n  confidence REAL NOT NULL DEFAULT 1.0,\n  reason TEXT NOT NULL DEFAULT '',\n  step INTEGER NOT NULL DEFAULT 0,\n  callLine INTEGER\n);\n\nCREATE INDEX IF NOT EXISTS idx_edges_sourceId ON edges(sourceId);\nCREATE INDEX IF NOT EXISTS idx_edges_targetId ON edges(targetId);\nCREATE INDEX IF NOT EXISTS idx_edges_type ON edges(type);\nCREATE INDEX IF NOT EXISTS idx_edges_source_type ON edges(sourceId, type);\nCREATE INDEX IF NOT EXISTS idx_edges_target_type ON edges(targetId, type);\n\n-- Embeddings: vector storage\nCREATE TABLE IF NOT EXISTS embeddings (\n  nodeId TEXT PRIMARY KEY,\n  embedding BLOB NOT NULL,\n  textHash TEXT\n);\n\n-- FTS5 virtual table (auto-updated via triggers)\nCREATE VIRTUAL TABLE IF NOT EXISTS nodes_fts USING fts5(\n  name,\n  nameExpanded,\n  searchText,\n  filePath,\n  content,\n  content='nodes',\n  content_rowid='rowid'\n);\n\nCREATE TRIGGER IF NOT EXISTS nodes_fts_ai AFTER INSERT ON nodes BEGIN\n  INSERT INTO nodes_fts(rowid, name, nameExpanded, searchText, filePath, content) VALUES (new.rowid, new.name, new.nameExpanded, new.searchText, new.filePath, new.content);\nEND;\nCREATE TRIGGER IF NOT EXISTS nodes_fts_ad AFTER DELETE ON nodes BEGIN\n  INSERT INTO nodes_fts(nodes_fts, rowid, name, nameExpanded, searchText, filePath, content) VALUES ('delete', old.rowid, old.name, old.nameExpanded, old.searchText, old.filePath, old.content);\nEND;\nCREATE TRIGGER IF NOT EXISTS nodes_fts_au AFTER UPDATE ON nodes BEGIN\n  INSERT INTO nodes_fts(nodes_fts, rowid, name, nameExpanded, searchText, filePath, content) VALUES ('delete', old.rowid, old.name, old.nameExpanded, old.searchText, old.filePath, old.content);\n  INSERT INTO nodes_fts(nodes_fts, rowid, name, nameExpanded, searchText, filePath, content) VALUES (new.rowid, new.name, new.nameExpanded, new.searchText, new.filePath, new.content);\nEND;\n";
+export declare const SCHEMA_SQL = "\n-- Nodes: unified table for all code elements\nCREATE TABLE IF NOT EXISTS nodes (\n  id TEXT PRIMARY KEY,\n  label TEXT NOT NULL,\n  name TEXT NOT NULL DEFAULT '',\n  filePath TEXT NOT NULL DEFAULT '',\n  startLine INTEGER,\n  endLine INTEGER,\n  isExported INTEGER,\n  content TEXT NOT NULL DEFAULT '',\n  description TEXT NOT NULL DEFAULT '',\n  heuristicLabel TEXT,\n  cohesion REAL,\n  symbolCount INTEGER,\n  keywords TEXT,\n  enrichedBy TEXT,\n  processType TEXT,\n  stepCount INTEGER,\n  communities TEXT,\n  entryPointId TEXT,\n  terminalId TEXT,\n  parameterCount INTEGER,\n  returnType TEXT,\n  nameExpanded TEXT DEFAULT '',\n  searchText TEXT DEFAULT ''\n);\n\nCREATE INDEX IF NOT EXISTS idx_nodes_label ON nodes(label);\nCREATE INDEX IF NOT EXISTS idx_nodes_name ON nodes(name);\nCREATE INDEX IF NOT EXISTS idx_nodes_filePath ON nodes(filePath);\nCREATE INDEX IF NOT EXISTS idx_nodes_label_name ON nodes(label, name);\nCREATE INDEX IF NOT EXISTS idx_nodes_filePath_lines ON nodes(filePath, startLine, endLine);\n\n-- Edges: single table for all relationships\nCREATE TABLE IF NOT EXISTS edges (\n  id TEXT PRIMARY KEY,\n  sourceId TEXT NOT NULL,\n  targetId TEXT NOT NULL,\n  type TEXT NOT NULL,\n  confidence REAL NOT NULL DEFAULT 1.0,\n  reason TEXT NOT NULL DEFAULT '',\n  step INTEGER NOT NULL DEFAULT 0,\n  callLine INTEGER\n);\n\nCREATE INDEX IF NOT EXISTS idx_edges_sourceId ON edges(sourceId);\nCREATE INDEX IF NOT EXISTS idx_edges_targetId ON edges(targetId);\nCREATE INDEX IF NOT EXISTS idx_edges_type ON edges(type);\nCREATE INDEX IF NOT EXISTS idx_edges_source_type ON edges(sourceId, type);\nCREATE INDEX IF NOT EXISTS idx_edges_target_type ON edges(targetId, type);\n\n-- Embeddings: vector storage\nCREATE TABLE IF NOT EXISTS embeddings (\n  nodeId TEXT PRIMARY KEY,\n  embedding BLOB NOT NULL,\n  textHash TEXT\n);\n\n-- FTS5 virtual table (auto-updated via triggers)\nCREATE VIRTUAL TABLE IF NOT EXISTS nodes_fts USING fts5(\n  name,\n  nameExpanded,\n  searchText,\n  filePath,\n  content,\n  content='nodes',\n  content_rowid='rowid'\n);\n\nCREATE TRIGGER IF NOT EXISTS nodes_fts_ai AFTER INSERT ON nodes BEGIN\n  INSERT INTO nodes_fts(rowid, name, nameExpanded, searchText, filePath, content) VALUES (new.rowid, new.name, new.nameExpanded, new.searchText, new.filePath, new.content);\nEND;\nCREATE TRIGGER IF NOT EXISTS nodes_fts_ad AFTER DELETE ON nodes BEGIN\n  INSERT INTO nodes_fts(nodes_fts, rowid, name, nameExpanded, searchText, filePath, content) VALUES ('delete', old.rowid, old.name, old.nameExpanded, old.searchText, old.filePath, old.content);\nEND;\nCREATE TRIGGER IF NOT EXISTS nodes_fts_au AFTER UPDATE ON nodes BEGIN\n  INSERT INTO nodes_fts(nodes_fts, rowid, name, nameExpanded, searchText, filePath, content) VALUES ('delete', old.rowid, old.name, old.nameExpanded, old.searchText, old.filePath, old.content);\n  INSERT INTO nodes_fts(nodes_fts, rowid, name, nameExpanded, searchText, filePath, content) VALUES (new.rowid, new.name, new.nameExpanded, new.searchText, new.filePath, new.content);\nEND;\n\n-- Refs: identifier occurrence index (pre-computed grep)\nCREATE TABLE IF NOT EXISTS refs (\n  symbol TEXT NOT NULL,\n  filePath TEXT NOT NULL,\n  line INTEGER NOT NULL\n);\n\nCREATE INDEX IF NOT EXISTS idx_refs_symbol ON refs(symbol);\nCREATE INDEX IF NOT EXISTS idx_refs_filePath ON refs(filePath);\nCREATE INDEX IF NOT EXISTS idx_refs_symbol_file ON refs(symbol, filePath);\n\n-- File-level word index for conceptual search\nCREATE TABLE IF NOT EXISTS file_words (\n  filePath TEXT PRIMARY KEY,\n  words TEXT NOT NULL DEFAULT ''\n);\n\nCREATE VIRTUAL TABLE IF NOT EXISTS file_words_fts USING fts5(\n  words,\n  content='file_words',\n  content_rowid='rowid'\n);\n\nCREATE TRIGGER IF NOT EXISTS file_words_fts_ai AFTER INSERT ON file_words BEGIN\n  INSERT INTO file_words_fts(rowid, words) VALUES (new.rowid, new.words);\nEND;\nCREATE TRIGGER IF NOT EXISTS file_words_fts_ad AFTER DELETE ON file_words BEGIN\n  INSERT INTO file_words_fts(file_words_fts, rowid, words) VALUES ('delete', old.rowid, old.words);\nEND;\nCREATE TRIGGER IF NOT EXISTS file_words_fts_au AFTER UPDATE ON file_words BEGIN\n  INSERT INTO file_words_fts(file_words_fts, rowid, words) VALUES ('delete', old.rowid, old.words);\n  INSERT INTO file_words_fts(file_words_fts, rowid, words) VALUES (new.rowid, new.words);\nEND;\n";

package/dist/core/db/schema.js

@@ -135,4 +135,38 @@ CREATE TRIGGER IF NOT EXISTS nodes_fts_au AFTER UPDATE ON nodes BEGIN
   INSERT INTO nodes_fts(nodes_fts, rowid, name, nameExpanded, searchText, filePath, content) VALUES ('delete', old.rowid, old.name, old.nameExpanded, old.searchText, old.filePath, old.content);
   INSERT INTO nodes_fts(nodes_fts, rowid, name, nameExpanded, searchText, filePath, content) VALUES (new.rowid, new.name, new.nameExpanded, new.searchText, new.filePath, new.content);
 END;
+
+-- Refs: identifier occurrence index (pre-computed grep)
+CREATE TABLE IF NOT EXISTS refs (
+  symbol TEXT NOT NULL,
+  filePath TEXT NOT NULL,
+  line INTEGER NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_refs_symbol ON refs(symbol);
+CREATE INDEX IF NOT EXISTS idx_refs_filePath ON refs(filePath);
+CREATE INDEX IF NOT EXISTS idx_refs_symbol_file ON refs(symbol, filePath);
+
+-- File-level word index for conceptual search
+CREATE TABLE IF NOT EXISTS file_words (
+  filePath TEXT PRIMARY KEY,
+  words TEXT NOT NULL DEFAULT ''
+);
+
+CREATE VIRTUAL TABLE IF NOT EXISTS file_words_fts USING fts5(
+  words,
+  content='file_words',
+  content_rowid='rowid'
+);
+
+CREATE TRIGGER IF NOT EXISTS file_words_fts_ai AFTER INSERT ON file_words BEGIN
+  INSERT INTO file_words_fts(rowid, words) VALUES (new.rowid, new.words);
+END;
+CREATE TRIGGER IF NOT EXISTS file_words_fts_ad AFTER DELETE ON file_words BEGIN
+  INSERT INTO file_words_fts(file_words_fts, rowid, words) VALUES ('delete', old.rowid, old.words);
+END;
+CREATE TRIGGER IF NOT EXISTS file_words_fts_au AFTER UPDATE ON file_words BEGIN
+  INSERT INTO file_words_fts(file_words_fts, rowid, words) VALUES ('delete', old.rowid, old.words);
+  INSERT INTO file_words_fts(file_words_fts, rowid, words) VALUES (new.rowid, new.words);
+END;
 `;

package/dist/core/embeddings/embedding-pipeline.d.ts

@@ -11,11 +11,13 @@ import { type EmbeddingProgress, type EmbeddingConfig, type SemanticSearchResult
 import type Database from 'better-sqlite3';
 /** Progress callback type */
 export type EmbeddingProgressCallback = (progress: EmbeddingProgress) => void;
-/** Graph context for a node: callers, callees, and community module */
+/** Graph context for a node: callers, callees, community module, imports, and siblings */
 export interface GraphContext {
     callers: string[];
     callees: string[];
     module: string;
+    importNames: string[];
+    siblingNames: string[];
 }
 /**
  * Fetch graph context (callers, callees, community module) for a set of nodes.

package/dist/core/embeddings/embedding-pipeline.js

@@ -92,12 +92,51 @@ export function fetchGraphContext(db, nodes) {
         for (const r of moduleRows) {
             moduleMap.set(r.nid, r.module ?? '');
         }
+        // Batch fetch import names (what this file imports)
+        const chunkSize = 500;
+        const importMap = {};
+        for (let ci = 0; ci < nodeIds.length; ci += chunkSize) {
+            const chunk = nodeIds.slice(ci, ci + chunkSize);
+            const ph = chunk.map(() => '?').join(',');
+            const importRows = db.prepare(`SELECT DISTINCT n.filePath, tn.name
+         FROM nodes n
+         JOIN edges e ON e.sourceId = n.id AND e.type = 'IMPORTS'
+         JOIN nodes tn ON tn.id = e.targetId
+         WHERE n.id IN (${ph})`).all(...chunk);
+            for (const row of importRows) {
+                if (!importMap[row.filePath])
+                    importMap[row.filePath] = [];
+                if (importMap[row.filePath].length < 10)
+                    importMap[row.filePath].push(row.name);
+            }
+        }
+        // Batch fetch sibling symbol names (other symbols in same file)
+        const siblingMap = {};
+        for (let ci = 0; ci < nodeIds.length; ci += chunkSize) {
+            const chunk = nodeIds.slice(ci, ci + chunkSize);
+            const ph = chunk.map(() => '?').join(',');
+            const sibRows = db.prepare(`SELECT n1.id as sourceId, n2.name as sibName
+         FROM nodes n1
+         JOIN nodes n2 ON n2.filePath = n1.filePath AND n2.id != n1.id
+         WHERE n1.id IN (${ph})
+         AND n2.label NOT IN ('File', 'Folder', 'Community', 'Process')
+         LIMIT ${chunk.length * 5}`).all(...chunk);
+            for (const row of sibRows) {
+                if (!siblingMap[row.sourceId])
+                    siblingMap[row.sourceId] = [];
+                if (siblingMap[row.sourceId].length < 5)
+                    siblingMap[row.sourceId].push(row.sibName);
+            }
+        }
         // Assemble
         for (const node of nodes) {
+            const n = node;
             graphContext.set(node.id, {
                 callers: (callerMap.get(node.id) || []).slice(0, 3),
                 callees: (calleeMap.get(node.id) || []).slice(0, 3),
                 module: moduleMap.get(node.id) || '',
+                importNames: n.filePath ? (importMap[n.filePath] || []) : [],
+                siblingNames: siblingMap[node.id] || [],
             });
         }
     }
@@ -115,7 +154,7 @@ export function fetchGraphContext(db, nodes) {
  * @returns Enriched text
  */
 export function enrichTextWithGraphContext(text, ctx) {
-    if (!ctx.module && ctx.callers.length === 0 && ctx.callees.length === 0)
+    if (!ctx.module && ctx.callers.length === 0 && ctx.callees.length === 0 && ctx.importNames.length === 0 && ctx.siblingNames.length === 0)
         return text;
     const lines = text.split('\n');
     // Append Module to the File: line (matches Python batch format)
@@ -125,7 +164,17 @@ export function enrichTextWithGraphContext(text, ctx) {
             lines[fileIdx] += ` | Module: ${ctx.module}`;
         }
     }
-    // Insert callers/callees after the File: line
+    // Insert imports after the File: line
+    if (ctx.importNames.length > 0) {
+        const importLine = `Imports: ${ctx.importNames.join(', ')}`;
+        // Insert after the File line
+        const fileIdx = lines.findIndex(l => l.startsWith('File:'));
+        if (fileIdx >= 0)
+            lines.splice(fileIdx + 1, 0, importLine);
+        else
+            lines.push(importLine);
+    }
+    // Insert callers/callees after the File: line (and imports if present)
     const insertParts = [];
     if (ctx.callers.length > 0)
         insertParts.push(`Called by: ${ctx.callers.join(', ')}`);
@@ -138,6 +187,10 @@ export function enrichTextWithGraphContext(text, ctx) {
             lines.splice(insertAt, 0, insertParts[i] ?? '');
         }
     }
+    // Append siblings at the end
+    if (ctx.siblingNames.length > 0) {
+        lines.push(`Siblings: ${ctx.siblingNames.join(', ')}`);
+    }
     return lines.join('\n');
 }
 /**

package/dist/core/embeddings/text-generator.js

@@ -16,6 +16,13 @@ const getFileName = (filePath) => {
     const parts = filePath.split('/');
     return parts[parts.length - 1] || filePath;
 };
+/** Extract directory context from file path (last 2-3 segments) */
+const getDirectoryContext = (filePath) => {
+    const parts = filePath.split('/');
+    // Remove filename, take last 2 directory segments
+    parts.pop();
+    return parts.slice(-2).join('/');
+};
 /**
  * Extract the first JSDoc/comment block as a natural language description.
  * This bridges natural language queries to code — "blast radius analysis"
@@ -154,8 +161,9 @@ export const generateEmbeddingText = (node, _config = {}) => {
     const comment = extractFirstComment(node.content);
     if (comment)
         parts.push(comment);
-    // 3. File location
-    parts.push(`File: ${getFileName(node.filePath)}`);
+    // 3. File location with directory context
+    const dir = getDirectoryContext(node.filePath);
+    parts.push(`File: ${getFileName(node.filePath)}${dir ? ` in ${dir}` : ''}`);
     // 4. Code signature (not full body)
     const sig = extractSignature(node.content, label);
     if (sig)

package/dist/core/embeddings/types.d.ts

@@ -1,5 +1,5 @@
 /** @file types.ts @description Type definitions for embedding generation and semantic search */
-export declare const EMBEDDABLE_LABELS: readonly ["Function", "Class", "Method", "Interface"];
+export declare const EMBEDDABLE_LABELS: readonly ["Function", "Class", "Method", "Interface", "Const", "Enum", "TypeAlias", "Namespace", "Module", "Struct"];
 export type EmbeddableLabel = typeof EMBEDDABLE_LABELS[number];
 /** Check if a label is embeddable */
 export declare const isEmbeddableLabel: (label: string) => label is EmbeddableLabel;

package/dist/core/embeddings/types.js

@@ -4,10 +4,8 @@
 // File nodes removed — their embeddings were low quality (import headers, license text)
 // and polluted semantic search. BM25 FTS already searches file content effectively.
 export const EMBEDDABLE_LABELS = [
-    'Function',
-    'Class',
-    'Method',
-    'Interface',
+    'Function', 'Class', 'Method', 'Interface',
+    'Const', 'Enum', 'TypeAlias', 'Namespace', 'Module', 'Struct',
 ];
 /** Check if a label is embeddable */
 export const isEmbeddableLabel = (label) => EMBEDDABLE_LABELS.includes(label);

package/dist/core/incremental/refresh.js

@@ -21,7 +21,7 @@ import { getLanguageFromFilename, getDefinitionNodeFromCaptures } from '../inges
 import { loadParser, loadLanguage, isLanguageAvailable } from '../tree-sitter/parser-loader.js';
 import { getTreeSitterBufferSize, TREE_SITTER_MAX_BUFFER } from '../ingestion/constants.js';
 import { generateId } from '../../lib/utils.js';
-import { deleteNodesByFile, insertNode, insertEdge, findNodeAtLine, findNodesByFile, deleteEmbeddingsByFile, insertEmbeddingsBatch, countEmbeddings } from '../db/adapter.js';
+import { deleteNodesByFile, insertNode, insertEdge, findNodeAtLine, findNodesByFile, deleteEmbeddingsByFile, insertEmbeddingsBatch, countEmbeddings, deleteRefsByFile, insertRefsBatch, deleteFileWordsByFile, upsertFileWords } from '../db/adapter.js';
 import { assertNodeLabel, toNodeId, toEdgeId } from '../db/schema.js';
 import {} from './types.js';
 import { getTsgoService } from '../semantic/tsgo-service.js';
@@ -79,10 +79,13 @@ export async function refreshFiles(db, repoPath, dirtyFiles) {
     let nodesInserted = 0;
     let edgesInserted = 0;
     let filesSkipped = 0;
-    // Phase 1: Delete old nodes for all dirty files
+    // Phase 1: Delete old nodes + refs + file_words for all dirty files
     for (const entry of dirtyFiles) {
-        const deleted = deleteNodesByFile(db, entry.relativePath);
+        const relPath = entry.relativePath;
+        const deleted = deleteNodesByFile(db, relPath);
         nodesDeleted += deleted;
+        deleteRefsByFile(db, relPath);
+        deleteFileWordsByFile(db, relPath);
     }
     // Phase 2: Parse modified/created files with tree-sitter
     const parser = await loadParser();
@@ -90,6 +93,7 @@ export async function refreshFiles(db, repoPath, dirtyFiles) {
     const allDefinitions = [];
     const callSites = [];
     const insertedFilePaths = new Set();
+    const fileContents = new Map(); // for file_words rebuild
     for (const entry of filesToProcess) {
         const relPath = entry.relativePath;
         const absPath = path.resolve(repoPath, relPath);
@@ -110,6 +114,7 @@ export async function refreshFiles(db, repoPath, dirtyFiles) {
             filesSkipped++;
             continue;
         }
+        fileContents.set(relPath, content);
         try {
             await loadLanguage(language, relPath);
         }
@@ -247,6 +252,37 @@ export async function refreshFiles(db, repoPath, dirtyFiles) {
         });
         edgesInserted++;
     }
+    // Phase 3b+3c: Rebuild refs + file_words for dirty files
+    const STOP_WORDS = new Set(['the', 'and', 'for', 'from', 'with', 'this', 'that', 'have', 'has', 'not', 'are', 'was', 'were', 'been', 'being', 'will', 'would', 'could', 'should', 'may', 'might', 'can', 'does', 'did', 'let', 'var', 'const', 'new', 'return', 'function', 'class', 'import', 'export', 'default', 'void', 'null', 'undefined', 'true', 'false', 'else', 'case', 'break', 'continue', 'while', 'throw', 'catch', 'try', 'finally', 'async', 'await', 'yield', 'typeof', 'instanceof', 'delete', 'switch', 'interface', 'type', 'enum', 'extends', 'implements', 'static', 'private', 'public', 'protected', 'abstract', 'readonly', 'override', 'declare', 'module', 'namespace', 'require', 'string', 'number', 'boolean', 'object', 'any', 'never', 'unknown', 'symbol']);
+    // Phase 3b: Rebuild refs for dirty files (identifier occurrence index)
+    for (const [relPath, content] of fileContents) {
+        const refs = [];
+        const lines = content.split('\n');
+        const identRegex = /\b[a-zA-Z_]\w{2,}\b/g;
+        for (let lineIdx = 0; lineIdx < lines.length; lineIdx++) {
+            let match;
+            while ((match = identRegex.exec(lines[lineIdx])) !== null) {
+                if (!STOP_WORDS.has(match[0].toLowerCase())) {
+                    refs.push({ symbol: match[0], filePath: relPath, line: lineIdx });
+                }
+            }
+        }
+        if (refs.length > 0)
+            insertRefsBatch(db, refs);
+    }
+    // Phase 3c: Rebuild file_words for dirty files (conceptual search index)
+    for (const [relPath, content] of fileContents) {
+        const wordSet = new Set();
+        const wordRegex = /\b[a-zA-Z]\w{2,}\b/g;
+        let match;
+        while ((match = wordRegex.exec(content)) !== null) {
+            const w = match[0].toLowerCase();
+            if (!STOP_WORDS.has(w))
+                wordSet.add(w);
+        }
+        if (wordSet.size > 0)
+            upsertFileWords(db, relPath, [...wordSet].join(' '));
+    }
     // Phase 4 + 5: Resolve call edges and cross-file edges using tsgo LSP
     // (TS/JS files only — tsgo is optional, skip if unavailable)
     console.error(`Code Mapper: refresh tsgo init with repoPath=${repoPath}`);

package/dist/core/semantic/tsgo-service.js

@@ -294,16 +294,32 @@ export class TsgoService {
         }
     }
     findTsgoBinary() {
-        // Try resolving via the @typescript/native-preview platform package
+        const pkgName = `@typescript/native-preview-${process.platform}-${process.arch}`;
+        // 1. Try resolving from the global install (code-mapper's own node_modules)
         try {
-            const pkgName = `@typescript/native-preview-${process.platform}-${process.arch}`;
             const pkgJsonPath = esmRequire.resolve(`${pkgName}/package.json`);
             const exe = path.join(path.dirname(pkgJsonPath), 'lib', 'tsgo');
             if (fs.existsSync(exe))
                 return exe;
         }
         catch { }
-        // Try which/where
+        // 2. Try resolving from the PROJECT's node_modules (where devDependencies live)
+        try {
+            const projectRequire = createRequire(path.join(this.projectRoot, 'node_modules', '.package-lock.json'));
+            const pkgJsonPath = projectRequire.resolve(`${pkgName}/package.json`);
+            const exe = path.join(path.dirname(pkgJsonPath), 'lib', 'tsgo');
+            if (fs.existsSync(exe))
+                return exe;
+        }
+        catch { }
+        // 3. Try direct path in project's node_modules
+        try {
+            const exe = path.join(this.projectRoot, 'node_modules', pkgName, 'lib', 'tsgo');
+            if (fs.existsSync(exe))
+                return exe;
+        }
+        catch { }
+        // 4. Try which/where (on PATH)
         try {
             const cmd = process.platform === 'win32' ? 'where' : 'which';
             const result = execFileSync(cmd, ['tsgo'], { encoding: 'utf-8', timeout: 3000 }).trim();

package/dist/mcp/local/local-backend.d.ts

@@ -40,10 +40,16 @@ export declare class LocalBackend {
     private refreshLocks;
     /** Per-repo tsgo LSP service instances for live semantic enrichment */
     private tsgoServices;
+    /** Per-repo in-memory embedding cache: nodeId → Float32Array (256-dim) */
+    private embeddingCaches;
     /** Get (or lazily start) a tsgo LSP service for a repo. Returns null if unavailable. */
     private getTsgo;
     /** Get (or lazily open) the SQLite database for a repo. */
     private getDb;
+    /** Load all embeddings into memory for fast vector search */
+    private loadEmbeddingCache;
+    /** Search embeddings in memory — O(N) dot products, no disk I/O */
+    private searchEmbeddingsInMemory;
     /** Hard ceiling — beyond this, incremental is unreliable, warn prominently */
     private static readonly MAX_INCREMENTAL_FILES;
     /** Start file system watcher for a repo to detect source changes */
@@ -125,6 +131,26 @@ export declare class LocalBackend {
      * Semantic vector search helper
      */
     private semanticSearch;
+    /**
+     * Refs-based search: find symbols referenced in files that contain the query identifiers.
+     * Bridges the gap between graph edges (incomplete) and grep (complete for exact names).
+     */
+    private refsSearch;
+    /**
+     * File-words FTS search: find files whose content contains conceptual terms,
+     * then return the best symbol from each file. Bridges NL → code gap.
+     */
+    private fileWordsSearch;
+    /**
+     * Query expansion via embedding nearest neighbors: embed the query,
+     * find 5 closest symbols, extract their names as BM25 expansion terms.
+     */
+    private expandQueryViaNearestNeighbors;
+    /**
+     * Ripgrep fallback: when all search signals return sparse results,
+     * grep the repo for query terms to find any relevant files.
+     */
+    private ripgrepFallback;
     executeSql(repoName: string, query: string): Promise<any>;
     private sqlQuery;
     /** Format raw SQL result rows as a markdown table, with raw fallback */

package/dist/mcp/local/local-backend.js

@@ -6,7 +6,7 @@
 import fs from 'fs/promises';
 import path from 'path';
 import { execFileSync } from 'child_process';
-import { openDb, closeDb, getNode, findNodesByName, findNodesByFile, rawQuery, searchVector, countEmbeddings, searchFTS, queryChunked } from '../../core/db/adapter.js';
+import { openDb, closeDb, getNode, findNodesByName, findNodesByFile, rawQuery, countEmbeddings, searchFTS, queryChunked, findRefsBySymbol, searchFileWords } from '../../core/db/adapter.js';
 import { toNodeId, assertEdgeType } from '../../core/db/schema.js';
 import * as queries from '../../core/db/queries.js';
 import { refreshFiles, refreshEmbeddings } from '../../core/incremental/refresh.js';
@@ -55,6 +55,8 @@ export class LocalBackend {
     refreshLocks = new Map();
     /** Per-repo tsgo LSP service instances for live semantic enrichment */
     tsgoServices = new Map();
+    /** Per-repo in-memory embedding cache: nodeId → Float32Array (256-dim) */
+    embeddingCaches = new Map();
     /** Get (or lazily start) a tsgo LSP service for a repo. Returns null if unavailable. */
     async getTsgo(repo) {
         const existing = this.tsgoServices.get(repo.id);
@@ -80,6 +82,64 @@ export class LocalBackend {
         const dbPath = path.join(handle.storagePath, 'index.db');
         return openDb(dbPath);
     }
+    /** Load all embeddings into memory for fast vector search */
+    loadEmbeddingCache(repoId) {
+        try {
+            const db = this.getDb(repoId);
+            const rows = db.prepare('SELECT nodeId, embedding FROM embeddings').all();
+            if (rows.length === 0) {
+                this.embeddingCaches.delete(repoId);
+                return;
+            }
+            const dims = rows[0].embedding.byteLength / 4;
+            const nodeIds = [];
+            const matrix = new Float32Array(rows.length * dims);
+            const norms = new Float32Array(rows.length);
+            for (let i = 0; i < rows.length; i++) {
+                const row = rows[i];
+                nodeIds.push(row.nodeId);
+                const vec = new Float32Array(row.embedding.buffer, row.embedding.byteOffset, row.embedding.byteLength / 4);
+                matrix.set(vec, i * dims);
+                // Pre-compute norm for fast cosine similarity
+                let norm = 0;
+                for (let d = 0; d < dims; d++)
+                    norm += vec[d] * vec[d];
+                norms[i] = Math.sqrt(norm);
+            }
+            this.embeddingCaches.set(repoId, { nodeIds, matrix, norms });
+        }
+        catch (err) {
+            console.error(`Code Mapper: Failed to load embedding cache: ${err instanceof Error ? err.message : err}`);
+        }
+    }
+    /** Search embeddings in memory — O(N) dot products, no disk I/O */
+    searchEmbeddingsInMemory(repoId, queryVec, limit = 10, maxDistance = 0.5) {
+        const cache = this.embeddingCaches.get(repoId);
+        if (!cache || cache.nodeIds.length === 0)
+            return [];
+        const dims = queryVec.length;
+        const results = [];
+        // Pre-compute query norm
+        let qNorm = 0;
+        for (let d = 0; d < dims; d++)
+            qNorm += queryVec[d] * queryVec[d];
+        qNorm = Math.sqrt(qNorm);
+        if (qNorm === 0)
+            return [];
+        for (let i = 0; i < cache.nodeIds.length; i++) {
+            const offset = i * dims;
+            let dot = 0;
+            for (let d = 0; d < dims; d++)
+                dot += queryVec[d] * cache.matrix[offset + d];
+            const similarity = dot / (qNorm * cache.norms[i]);
+            const distance = 1 - similarity;
+            if (distance < maxDistance) {
+                results.push({ nodeId: cache.nodeIds[i], distance });
+            }
+        }
+        results.sort((a, b) => a.distance - b.distance);
+        return results.slice(0, limit);
+    }
     /** Hard ceiling — beyond this, incremental is unreliable, warn prominently */
     static MAX_INCREMENTAL_FILES = 200;
     /** Start file system watcher for a repo to detect source changes */
@@ -188,6 +248,9 @@ export class LocalBackend {
             const db = this.getDb(repo.id);
             const hasEmb = (repo.stats?.embeddings ?? 0) > 0;
             await refreshEmbeddings(db, dirtyFiles, hasEmb);
+            // Reload embedding cache after refresh
+            if (hasEmb)
+                this.loadEmbeddingCache(repo.id);
         }
         catch (err) {
             watcher.inject(dirtyFiles);
@@ -206,10 +269,21 @@ export class LocalBackend {
     async init() {
         await this.refreshRepos();
         // Start file watchers for incremental refresh
+        let anyEmbeddings = false;
         for (const [id, handle] of this.repos) {
             this.startWatcher(id, handle);
-            // Seed watcher with changes that happened while the server was down
             this.seedWatcherFromGit(id, handle);
+            // Load embedding cache into memory for fast vector search
+            if ((handle.stats?.embeddings ?? 0) > 0) {
+                this.loadEmbeddingCache(id);
+                anyEmbeddings = true;
+            }
+        }
+        // Pre-warm MLX embedder so first query has zero model-load latency
+        if (anyEmbeddings) {
+            import('../../core/embeddings/embedder.js').then(({ initEmbedder }) => {
+                initEmbedder().catch(() => { });
+            }).catch(() => { });
         }
         return this.repos.size > 0;
     }
@@ -918,15 +992,23 @@ export class LocalBackend {
         // Enrich semantic query with task_context/goal for better embeddings
         const semanticQuery = [searchQuery, params.goal, params.task_context]
             .filter(Boolean).join(' — ');
-        // Step 1: Hybrid search (BM25 + semantic in parallel)
-        // BM25 uses raw query (keyword matching); semantic uses enriched query (better embedding)
+        // Step 0: Query expansion via nearest-neighbor embeddings
+        // "double charging" → finds "idempotencyKey" nearby → BM25 now searches for it
+        const { expandQuery } = await import('../../core/search/query-expansion.js');
+        const nnExpansionTerms = await this.expandQueryViaNearestNeighbors(repo, semanticQuery);
+        const expandedSearchQuery = nnExpansionTerms.length > 0
+            ? expandQuery(searchQuery, nnExpansionTerms)
+            : searchQuery;
+        // Step 1: Four-signal search in parallel
+        // BM25 uses expanded query; semantic uses enriched query; refs + file_words use raw query
         const searchLimit = processLimit * maxSymbolsPerProcess;
-        const [bm25Results, semanticResults] = await Promise.all([
-            this.bm25Search(repo, searchQuery, searchLimit),
+        const [bm25Results, semanticResults, refsResults, fileWordsResults] = await Promise.all([
+            this.bm25Search(repo, expandedSearchQuery, searchLimit),
             this.semanticSearch(repo, semanticQuery, searchLimit),
+            Promise.resolve(this.refsSearch(repo, searchQuery, searchLimit)),
+            Promise.resolve(this.fileWordsSearch(repo, searchQuery, searchLimit)),
         ]);
-        // Step 2: Weighted RRF merge (single implementation — no duplication)
-        // BM25 now returns symbol-level results with nodeId, name, type
+        // Step 2: Weighted RRF merge (4 signals)
         const bm25ForRRF = bm25Results.map((r, i) => ({
             nodeId: String(r.nodeId ?? ''),
             name: String(r.name ?? ''),
@@ -943,7 +1025,52 @@ export class LocalBackend {
             ...(r.startLine != null ? { startLine: r.startLine } : {}),
             ...(r.endLine != null ? { endLine: r.endLine } : {}),
         }));
-        const rrfMerged = mergeWithRRF(bm25ForRRF, semanticForRRF, { limit: searchLimit });
+        // Refs and file_words use BM25-compatible format for RRF
+        const refsForRRF = refsResults.map((r, i) => ({
+            nodeId: String(r.nodeId ?? ''), name: String(r.name ?? ''), type: String(r.type ?? 'File'),
+            filePath: String(r.filePath ?? ''), score: 1.0, rank: i + 1,
+            ...(r.startLine != null ? { startLine: r.startLine } : {}),
+            ...(r.endLine != null ? { endLine: r.endLine } : {}),
+        }));
+        const fileWordsForRRF = fileWordsResults.map((r, i) => ({
+            nodeId: String(r.nodeId ?? ''), name: String(r.name ?? ''), type: String(r.type ?? 'File'),
+            filePath: String(r.filePath ?? ''), score: 1.0, rank: i + 1,
+            ...(r.startLine != null ? { startLine: r.startLine } : {}),
+            ...(r.endLine != null ? { endLine: r.endLine } : {}),
+        }));
+        let rrfMerged = mergeWithRRF(bm25ForRRF, semanticForRRF, { limit: searchLimit });
+        // Merge refs + fileWords into the RRF results (lower weight)
+        if (refsForRRF.length > 0 || fileWordsForRRF.length > 0) {
+            const supplemental = mergeWithRRF(refsForRRF, fileWordsForRRF.map((r) => ({
+                nodeId: r.nodeId, name: r.name, label: r.type, filePath: r.filePath, distance: 0.5,
+                ...(r.startLine != null ? { startLine: r.startLine } : {}),
+                ...(r.endLine != null ? { endLine: r.endLine } : {}),
+            })), { limit: searchLimit });
+            // Add supplemental results not already in main merge
+            const mainIds = new Set(rrfMerged.map(r => r.nodeId || r.filePath));
+            for (const s of supplemental) {
+                const key = s.nodeId || s.filePath;
+                if (!mainIds.has(key)) {
+                    rrfMerged.push({ ...s, score: s.score * 0.5 }); // lower weight for supplemental
+                    mainIds.add(key);
+                }
+            }
+            rrfMerged.sort((a, b) => b.score - a.score);
+            rrfMerged = rrfMerged.slice(0, searchLimit);
+        }
+        // Step 2b: Ripgrep fallback when all signals return sparse results
+        if (rrfMerged.length < 3) {
+            const rgResults = this.ripgrepFallback(repo, searchQuery, 10);
+            for (const rg of rgResults) {
+                if (!rrfMerged.some(m => m.filePath === rg.filePath)) {
+                    rrfMerged.push({
+                        filePath: rg.filePath, score: 0.01, rank: rrfMerged.length + 1,
+                        sources: ['bm25'], nodeId: rg.nodeId, name: rg.name, label: rg.type,
+                        startLine: rg.startLine, endLine: rg.endLine,
+                    });
+                }
+            }
+        }
         // Build lookup from original search data (keyed by both nodeId and filePath for cross-referencing)
         const searchDataMap = new Map();
         for (const r of bm25Results) {
@@ -1341,25 +1468,34 @@ export class LocalBackend {
      */
     async semanticSearch(repo, query, limit) {
         try {
-            // Check if embeddings exist before loading the model (avoids heavy model init when embeddings are off)
-            const semDb = this.getDb(repo.id);
-            const embCount = countEmbeddings(semDb);
-            if (embCount === 0)
-                return [];
+            // Use in-memory cache if available (10-100x faster than SQLite scan)
+            const cache = this.embeddingCaches.get(repo.id);
+            if (!cache || cache.nodeIds.length === 0) {
+                // Fallback: check DB directly
+                const checkDb = this.getDb(repo.id);
+                const embCount = countEmbeddings(checkDb);
+                if (embCount === 0)
+                    return [];
+                // Load cache on demand
+                this.loadEmbeddingCache(repo.id);
+                if (!this.embeddingCaches.get(repo.id))
+                    return [];
+            }
             const { DEFAULT_MAX_SEMANTIC_DISTANCE } = await import('../../core/search/types.js');
             const { embedQuery } = await import('../../core/embeddings/embedder.js');
             const queryVec = await embedQuery(query);
-            // Brute-force cosine search via adapter (fast enough for <200K vectors at 256 dims)
-            const vecResults = searchVector(semDb, queryVec, limit, DEFAULT_MAX_SEMANTIC_DISTANCE);
+            // In-memory cosine search — no disk I/O
+            const vecResults = this.searchEmbeddingsInMemory(repo.id, queryVec, limit, DEFAULT_MAX_SEMANTIC_DISTANCE);
             if (vecResults.length === 0)
                 return [];
             // Batch metadata fetch
+            const metaDb = this.getDb(repo.id);
             const vecNodeIds = vecResults.map(r => r.nodeId);
             const distanceMap = new Map();
             for (const r of vecResults) {
                 distanceMap.set(r.nodeId, r.distance);
             }
-            const metaNodes = queries.findNodesByIds(semDb, vecNodeIds);
+            const metaNodes = queries.findNodesByIds(metaDb, vecNodeIds);
             return metaNodes.map(node => ({
                 nodeId: node.id,
                 name: node.name,
@@ -1375,6 +1511,143 @@ export class LocalBackend {
             return [];
         }
     }
+    /**
+     * Refs-based search: find symbols referenced in files that contain the query identifiers.
+     * Bridges the gap between graph edges (incomplete) and grep (complete for exact names).
+     */
+    refsSearch(repo, query, limit) {
+        try {
+            const db = this.getDb(repo.id);
+            // Tokenize query into potential identifier names
+            const tokens = query.match(/\b[a-zA-Z_]\w{2,}\b/g) || [];
+            if (tokens.length === 0)
+                return [];
+            const seen = new Set();
+            const results = [];
+            for (const token of tokens) {
+                const refs = findRefsBySymbol(db, token, 50);
+                for (const ref of refs) {
+                    if (seen.has(ref.filePath))
+                        continue;
+                    seen.add(ref.filePath);
+                    // Find the best symbol in this file
+                    const fileNodes = findNodesByFile(db, ref.filePath);
+                    const bestNode = fileNodes.find(n => n.label !== 'File') || fileNodes[0];
+                    if (bestNode) {
+                        results.push({
+                            nodeId: bestNode.id,
+                            name: bestNode.name,
+                            type: bestNode.label,
+                            filePath: bestNode.filePath,
+                            startLine: bestNode.startLine,
+                            endLine: bestNode.endLine,
+                            refsScore: -results.length, // rank by order found
+                        });
+                    }
+                    if (results.length >= limit)
+                        break;
+                }
+                if (results.length >= limit)
+                    break;
+            }
+            return results;
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * File-words FTS search: find files whose content contains conceptual terms,
+     * then return the best symbol from each file. Bridges NL → code gap.
+     */
+    fileWordsSearch(repo, query, limit) {
+        try {
+            const db = this.getDb(repo.id);
+            const fileResults = searchFileWords(db, query, limit);
+            if (fileResults.length === 0)
+                return [];
+            const results = [];
+            for (const fr of fileResults) {
+                const fileNodes = findNodesByFile(db, fr.filePath);
+                const bestNode = fileNodes.find(n => n.label !== 'File') || fileNodes[0];
+                if (bestNode) {
+                    results.push({
+                        nodeId: bestNode.id,
+                        name: bestNode.name,
+                        type: bestNode.label,
+                        filePath: bestNode.filePath,
+                        startLine: bestNode.startLine,
+                        endLine: bestNode.endLine,
+                        fileWordsScore: fr.score,
+                    });
+                }
+            }
+            return results;
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * Query expansion via embedding nearest neighbors: embed the query,
+     * find 5 closest symbols, extract their names as BM25 expansion terms.
+     */
+    async expandQueryViaNearestNeighbors(repo, query) {
+        try {
+            const cache = this.embeddingCaches.get(repo.id);
+            if (!cache || cache.nodeIds.length === 0)
+                return [];
+            const { embedQuery } = await import('../../core/embeddings/embedder.js');
+            const queryVec = await embedQuery(query);
+            const neighbors = this.searchEmbeddingsInMemory(repo.id, queryVec, 5, 0.7);
+            // Extract symbol names from nodeIds (format: "Label:filePath:name")
+            return neighbors.map(n => {
+                const parts = n.nodeId.split(':');
+                return parts[parts.length - 1] || '';
+            }).filter(Boolean);
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * Ripgrep fallback: when all search signals return sparse results,
+     * grep the repo for query terms to find any relevant files.
+     */
+    ripgrepFallback(repo, query, limit) {
+        try {
+            const words = query.split(/\s+/).filter(w => w.length > 2).slice(0, 3);
+            if (words.length === 0)
+                return [];
+            const pattern = words.join('|');
+            const output = execFileSync('rg', ['-l', '-i', '--max-count', '1', pattern, '.'], {
+                cwd: repo.repoPath, encoding: 'utf-8', timeout: 3000,
+            });
+            const db = this.getDb(repo.id);
+            const results = [];
+            const files = output.trim().split('\n').filter(Boolean).slice(0, limit);
+            for (const f of files) {
+                const relPath = f.replace(/^\.\//, '');
+                const fileNodes = findNodesByFile(db, relPath);
+                const bestNode = fileNodes.find(n => n.label !== 'File') || fileNodes[0];
+                if (bestNode) {
+                    results.push({
+                        nodeId: bestNode.id,
+                        name: bestNode.name,
+                        type: bestNode.label,
+                        filePath: bestNode.filePath,
+                        startLine: bestNode.startLine,
+                        endLine: bestNode.endLine,
+                        matched_by: 'ripgrep',
+                    });
+                }
+            }
+            return results;
+        }
+        catch {
+            return [];
+        }
+    }
     async executeSql(repoName, query) {
         const repo = await this.resolveRepo(repoName);
         return this.sqlQuery(repo, { query });
@@ -1758,6 +2031,26 @@ export class LocalBackend {
                 // tsgo reference lookup failed — non-fatal, graph results still available
             }
         }
+        // Supplement callers from refs table (catches callers the graph missed)
+        try {
+            const refCallers = findRefsBySymbol(db, sym.name, 100);
+            const knownFiles = new Set(incomingRows.map(r => r.filePath));
+            for (const ref of refCallers) {
+                if (ref.filePath === sym.filePath)
+                    continue; // skip self-file
+                if (knownFiles.has(ref.filePath))
+                    continue; // already known
+                knownFiles.add(ref.filePath);
+                const enclosing = this.findNodeAtPosition(db, ref.filePath, ref.line);
+                if (enclosing) {
+                    incomingRows.push({
+                        relType: 'CALLS', uid: '', name: enclosing.name, filePath: ref.filePath,
+                        kind: enclosing.label, startLine: ref.line, reason: 'refs-index',
+                    });
+                }
+            }
+        }
+        catch { /* refs table may not exist yet */ }
         // Outgoing refs — exclude generic method names that produce false positives at low confidence
         const GENERIC_NAMES_EXCLUDE = new Set(['has', 'get', 'set', 'add', 'remove', 'delete', 'close', 'stop', 'clear', 'reset', 'toString', 'valueOf', 'push', 'pop', 'entries', 'keys', 'values']);
         let outgoingRows = [];

package/models/mlx-embedder.py

@@ -228,7 +228,7 @@ def batch_mode(db_path, dims=256, max_tokens=2048):
         db.execute("ALTER TABLE embeddings ADD COLUMN textHash TEXT")
 
     # Query embeddable nodes — skip test/fixture files (BM25 covers them)
-    labels = ('Function', 'Class', 'Method', 'Interface')
+    labels = ('Function', 'Class', 'Method', 'Interface', 'Const', 'Enum', 'TypeAlias', 'Namespace', 'Module', 'Struct')
     placeholders = ','.join('?' * len(labels))
     all_rows = db.execute(
         f"SELECT id, name, label, filePath, content, startLine, endLine, nameExpanded FROM nodes WHERE label IN ({placeholders})",
@@ -272,7 +272,23 @@ def batch_mode(db_path, dims=256, max_tokens=2048):
         for row in db.execute(f"SELECT e.sourceId, c.heuristicLabel FROM edges e JOIN nodes c ON c.id = e.targetId WHERE e.sourceId IN ({ph}) AND e.type = 'MEMBER_OF' AND c.label = 'Community' LIMIT {len(chunk_ids)}", chunk_ids):
             module_map[row[0]] = row[1]
 
-    print(json.dumps({"phase": "context", "with_callers": len(caller_map), "with_module": len(module_map)}), flush=True)
+    # Batch fetch import names per file
+    import_map = {}
+    for ci in range(0, len(node_ids), CHUNK):
+        chunk_ids = node_ids[ci:ci+CHUNK]
+        ph = ','.join('?' * len(chunk_ids))
+        # Get unique file paths for these nodes
+        file_paths = [r[3] for r in rows if r[0] in set(chunk_ids)]
+        unique_files = list(set(file_paths))
+        if unique_files:
+            fph = ','.join('?' * len(unique_files))
+            for row in db.execute(
+                f"SELECT DISTINCT n.filePath, tn.name FROM nodes n JOIN edges e ON e.sourceId = n.id AND e.type = 'IMPORTS' JOIN nodes tn ON tn.id = e.targetId WHERE n.filePath IN ({fph}) LIMIT {len(unique_files)*10}",
+                unique_files
+            ):
+                import_map.setdefault(row[0], []).append(row[1])
+
+    print(json.dumps({"phase": "context", "with_callers": len(caller_map), "with_module": len(module_map), "with_imports": len(import_map)}), flush=True)
 
     # Get existing text hashes for skip detection
     existing_hashes = {}
@@ -367,13 +383,24 @@ def batch_mode(db_path, dims=256, max_tokens=2048):
         if comment:
             parts.append(comment)
 
+        # Directory context
+        dir_parts = filePath.rsplit('/', 2)
+        dir_context = '/'.join(dir_parts[:-1])[-40:] if '/' in filePath else ''
+
         # File + module location
         loc = f"File: {file_name}"
+        if dir_context:
+            loc += f" in {dir_context}"
         module = module_map.get(nid, "")
         if module:
             loc += f" | Module: {module}"
         parts.append(loc)
 
+        # Import context
+        file_imports = import_map.get(filePath, [])[:5]
+        if file_imports:
+            parts.append(f"Imports: {', '.join(file_imports)}")
+
         # Graph context
         callers = caller_map.get(nid, [])[:5]
         callees = callee_map.get(nid, [])[:5]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zuvia-software-solutions/code-mapper",
-  "version": "2.3.11",
+  "version": "2.4.0",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",