@zuvia-software-solutions/code-mapper 2.3.12 → 2.4.1

package/dist/cli/analyze.d.ts

@@ -2,6 +2,7 @@
 export interface AnalyzeOptions {
     force?: boolean;
     embeddings?: boolean;
+    nlEmbeddings?: boolean;
     tsgo?: boolean;
     verbose?: boolean;
 }

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) {
@@ -370,6 +428,22 @@ export const analyzeCommand = async (inputPath, options) => {
         // Reopen DB after Python is done
         db = openDb(dbPath);
     }
+    // Phase 4b: NL Embeddings (bge-small, CPU, Node.js)
+    if (options?.nlEmbeddings) {
+        recordPhase('nl-embeddings');
+        updateBar(95, 'Generating NL embeddings (bge-small)...');
+        const { buildNlEmbeddings } = await import('../core/embeddings/nl-embedder.js');
+        try {
+            const nlResult = await buildNlEmbeddings(db, (current, total) => {
+                const pct = 95 + Math.round((current / Math.max(total, 1)) * 3);
+                updateBar(pct, `NL embeddings (${current}/${total})`, 'NL embeddings');
+            });
+            updateBar(98, `NL embeddings: ${nlResult.embedded} embedded, ${nlResult.skipped} cached (${(nlResult.durationMs / 1000).toFixed(1)}s)`);
+        }
+        catch (err) {
+            console.error(`\n  Warning: NL embeddings failed: ${err instanceof Error ? err.message : err}`);
+        }
+    }
     // Phase 5: Finalize (98-100%)
     recordPhase('finalize');
     updateBar(98, 'Saving metadata...');

package/dist/cli/index.js

@@ -22,8 +22,8 @@ program
     .command('analyze [path]')
     .description('Index a repository (full analysis)')
     .option('-f, --force', 'Force full re-index even if up to date')
-    .option('--embeddings', 'Enable embedding generation for semantic search (on by default)', true)
-    .option('--no-embeddings', 'Skip embedding generation')
+    .option('--embeddings', 'Enable code embedding generation (Jina/MLX, GPU)', false)
+    .option('--nl-embeddings', 'Enable NL embedding generation (bge-small, CPU, recommended)', false)
     .option('--no-tsgo', 'Skip tsgo LSP for call resolution (faster, less accurate)')
     .option('-v, --verbose', 'Enable verbose ingestion warnings (default: false)')
     .addHelpText('after', '\nEnvironment variables:\n  CODE_MAPPER_NO_GITIGNORE=1  Skip .gitignore parsing (still reads .code-mapperignore)')

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,48 @@ 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;
+/** Count NL embeddings in the index */
+export declare function countNlEmbeddings(db: Database.Database): number;
+/** Search NL embeddings via brute-force cosine similarity */
+export declare function searchNlVector(db: Database.Database, queryVec: number[], limit?: number, maxDistance?: number): Array<{
+    nodeId: string;
+    distance: number;
+    source: string;
+    text: string;
+}>;
 /** 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,126 @@ 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();
+}
+// ---------------------------------------------------------------------------
+// NL Embeddings
+// ---------------------------------------------------------------------------
+/** Count NL embeddings in the index */
+export function countNlEmbeddings(db) {
+    try {
+        const row = db.prepare('SELECT COUNT(*) as cnt FROM nl_embeddings').get();
+        return row?.cnt ?? 0;
+    }
+    catch {
+        return 0;
+    }
+}
+/** Search NL embeddings via brute-force cosine similarity */
+export function searchNlVector(db, queryVec, limit = 10, maxDistance = 0.5) {
+    let rows;
+    try {
+        rows = db.prepare('SELECT nodeId, embedding, source, text FROM nl_embeddings').all();
+    }
+    catch {
+        return [];
+    }
+    const results = [];
+    for (const row of rows) {
+        const vec = new Float32Array(row.embedding.buffer, row.embedding.byteOffset, row.embedding.byteLength / 4);
+        let dot = 0, normA = 0, normB = 0;
+        for (let i = 0; i < queryVec.length && i < vec.length; i++) {
+            dot += queryVec[i] * vec[i];
+            normA += queryVec[i] * queryVec[i];
+            normB += vec[i] * vec[i];
+        }
+        const similarity = dot / (Math.sqrt(normA) * Math.sqrt(normB));
+        const distance = 1 - similarity;
+        if (distance < maxDistance) {
+            results.push({ nodeId: row.nodeId, distance, source: row.source, text: row.text });
+        }
+    }
+    results.sort((a, b) => a.distance - b.distance);
+    return results.slice(0, limit);
+}
+// ---------------------------------------------------------------------------
 // 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,25 @@ export interface EmbeddingRow {
     readonly embedding: Buffer;
     readonly textHash: string | null;
 }
+/** A NL embedding row as stored in the `nl_embeddings` table */
+export interface NlEmbeddingRow {
+    readonly nodeId: NodeId;
+    readonly embedding: Buffer;
+    readonly textHash: string | null;
+    readonly source: string;
+    readonly text: string;
+}
+/** 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 +126,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-- NL Embeddings: natural language description vectors (bge-small, 384-dim)\nCREATE TABLE IF NOT EXISTS nl_embeddings (\n  nodeId TEXT NOT NULL,\n  embedding BLOB NOT NULL,\n  textHash TEXT,\n  source TEXT NOT NULL DEFAULT 'comment',\n  text TEXT NOT NULL DEFAULT ''\n);\n\nCREATE INDEX IF NOT EXISTS idx_nl_emb_nodeId ON nl_embeddings(nodeId);\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

@@ -114,6 +114,17 @@ CREATE TABLE IF NOT EXISTS embeddings (
   textHash TEXT
 );
 
+-- NL Embeddings: natural language description vectors (bge-small, 384-dim)
+CREATE TABLE IF NOT EXISTS nl_embeddings (
+  nodeId TEXT NOT NULL,
+  embedding BLOB NOT NULL,
+  textHash TEXT,
+  source TEXT NOT NULL DEFAULT 'comment',
+  text TEXT NOT NULL DEFAULT ''
+);
+
+CREATE INDEX IF NOT EXISTS idx_nl_emb_nodeId ON nl_embeddings(nodeId);
+
 -- FTS5 virtual table (auto-updated via triggers)
 CREATE VIRTUAL TABLE IF NOT EXISTS nodes_fts USING fts5(
   name,
@@ -135,4 +146,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/nl-embedder.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @file Natural language embedder using bge-small-en-v1.5.
+ *
+ * Runs entirely in Node.js via @huggingface/transformers — no Python, no GPU.
+ * Embeds human-readable descriptions extracted from code (JSDoc comments,
+ * enum values, type patterns, file headers) for conceptual search.
+ *
+ * 33M params, q8 quantized, 384-dim embeddings, ~6ms/text on CPU.
+ */
+import type Database from 'better-sqlite3';
+/** Initialize the NL embedding model (lazy, idempotent) */
+export declare function initNlEmbedder(): Promise<void>;
+/** Check if the NL embedder is ready */
+export declare function isNlEmbedderReady(): boolean;
+/** Embed a single text, returns Float32Array */
+export declare function nlEmbed(text: string): Promise<number[]>;
+/** Embed a batch of texts */
+export declare function nlEmbedBatch(texts: string[]): Promise<number[][]>;
+interface NodeForNl {
+    id: string;
+    name: string;
+    label: string;
+    filePath: string;
+    content: string;
+    startLine: number | null;
+    description: string;
+}
+interface NlDocument {
+    nodeId: string;
+    source: string;
+    text: string;
+}
+/** Build NL documents from a node */
+export declare function extractNlTexts(node: NodeForNl): NlDocument[];
+/**
+ * Build NL embeddings for all eligible nodes in the database.
+ * Reads nodes, extracts NL text, embeds with bge-small, writes to nl_embeddings.
+ */
+export declare function buildNlEmbeddings(db: Database.Database, onProgress?: (current: number, total: number) => void): Promise<{
+    embedded: number;
+    skipped: number;
+    durationMs: number;
+}>;
+export {};