@zuvia-software-solutions/code-mapper 2.4.0 → 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

@@ -428,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

@@ -138,6 +138,15 @@ export declare function searchFileWords(db: Database.Database, query: string, li
 }>;
 /** 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

@@ -594,6 +594,46 @@ 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,14 @@ 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;
@@ -118,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\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";
+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,

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 {};

package/dist/core/embeddings/nl-embedder.js

@@ -0,0 +1,262 @@
+// code-mapper/src/core/embeddings/nl-embedder.ts
+/**
+ * @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.
+ */
+// NL embedder — no schema imports needed
+const MODEL_ID = 'Xenova/bge-small-en-v1.5';
+// Lazy-loaded pipeline
+let extractor = null;
+let loadPromise = null;
+/** Initialize the NL embedding model (lazy, idempotent) */
+export async function initNlEmbedder() {
+    if (extractor)
+        return;
+    if (loadPromise)
+        return loadPromise;
+    loadPromise = (async () => {
+        const { pipeline } = await import('@huggingface/transformers');
+        extractor = await pipeline('feature-extraction', MODEL_ID, { quantized: true });
+    })();
+    return loadPromise;
+}
+/** Check if the NL embedder is ready */
+export function isNlEmbedderReady() {
+    return extractor !== null;
+}
+/** Embed a single text, returns Float32Array */
+export async function nlEmbed(text) {
+    if (!extractor)
+        await initNlEmbedder();
+    const result = await extractor(text, { pooling: 'cls', normalize: true });
+    return Array.from(result.data);
+}
+/** Embed a batch of texts */
+export async function nlEmbedBatch(texts) {
+    if (!extractor)
+        await initNlEmbedder();
+    const results = [];
+    for (const text of texts) {
+        const result = await extractor(text, { pooling: 'cls', normalize: true });
+        results.push(Array.from(result.data));
+    }
+    return results;
+}
+/** Extract all JSDoc/block comment text (up to 10 lines) */
+function extractFullComment(content) {
+    if (!content)
+        return '';
+    const lines = content.split('\n');
+    const commentLines = [];
+    let inBlock = false;
+    for (const l of lines) {
+        const t = l.trim();
+        if (t.startsWith('/**') || t.startsWith('/*')) {
+            inBlock = true;
+            const inner = t.replace(/^\/\*\*?/, '').replace(/\*\/$/, '').trim();
+            if (inner && !inner.startsWith('@'))
+                commentLines.push(inner);
+            if (t.includes('*/'))
+                inBlock = false;
+            continue;
+        }
+        if (inBlock) {
+            if (t.includes('*/')) {
+                inBlock = false;
+                continue;
+            }
+            const inner = t.replace(/^\*\s?/, '').trim();
+            if (inner && !inner.startsWith('@'))
+                commentLines.push(inner);
+            if (commentLines.length >= 10)
+                break;
+            continue;
+        }
+        if (t.startsWith('//')) {
+            const inner = t.slice(2).trim();
+            if (inner)
+                commentLines.push(inner);
+            if (commentLines.length >= 10)
+                break;
+            continue;
+        }
+        if (t.startsWith('#') && !t.startsWith('#!')) {
+            const inner = t.slice(1).trim();
+            if (inner)
+                commentLines.push(inner);
+            if (commentLines.length >= 10)
+                break;
+            continue;
+        }
+        if (commentLines.length > 0)
+            break; // comment ended
+    }
+    return commentLines.join(' ');
+}
+/** Expand camelCase/PascalCase/snake_case to space-separated words */
+function expandIdentifier(name) {
+    return name
+        .replace(/([a-z])([A-Z])/g, '$1 $2')
+        .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+        .replace(/[_\-]/g, ' ')
+        .toLowerCase();
+}
+/** Extract enum/const array values as NL text */
+function extractEnumValues(content) {
+    // Match: ['value1', 'value2', ...] as const
+    const match = content.match(/\[([^\]]+)\]\s*as\s*const/);
+    if (match?.[1]) {
+        const values = match[1].replace(/['"]/g, '').split(',').map(v => v.trim()).filter(Boolean);
+        if (values.length > 0)
+            return values.join(', ');
+    }
+    // Match: enum { Value1, Value2 }
+    const enumMatch = content.match(/enum\s+\w+\s*\{([^}]+)\}/);
+    if (enumMatch?.[1]) {
+        const values = enumMatch[1].split(',').map(v => v.trim().split('=')[0].trim()).filter(Boolean);
+        if (values.length > 0)
+            return values.map(v => expandIdentifier(v)).join(', ');
+    }
+    return '';
+}
+/** Extract parameter names from function signature */
+function extractParamNames(content) {
+    const match = content.match(/\(([^)]*)\)/);
+    if (!match?.[1])
+        return '';
+    return match[1].split(',')
+        .map(p => p.trim().split(':')[0].split('=')[0].trim())
+        .filter(p => p && p !== '')
+        .map(p => expandIdentifier(p))
+        .join(', ');
+}
+/** Build NL documents from a node */
+export function extractNlTexts(node) {
+    const docs = [];
+    const name = node.name;
+    const expandedName = expandIdentifier(name);
+    const dir = node.filePath.split('/').slice(-3, -1).join('/');
+    // 1. Comment-based NL text (primary)
+    const comment = extractFullComment(node.content);
+    if (comment) {
+        docs.push({
+            nodeId: node.id,
+            source: 'comment',
+            text: `${expandedName}: ${comment}. File: ${dir}`,
+        });
+    }
+    // 2. Name + params + return type (always available)
+    const params = extractParamNames(node.content);
+    const parts = [expandedName];
+    if (params)
+        parts.push(`Parameters: ${params}`);
+    if (dir)
+        parts.push(`in ${dir}`);
+    if (!comment) {
+        // Only add name-based doc if no comment (avoid duplication)
+        docs.push({
+            nodeId: node.id,
+            source: 'name',
+            text: parts.join('. '),
+        });
+    }
+    // 3. Enum/const values
+    if (node.label === 'Enum' || node.label === 'Const' || node.label === 'TypeAlias') {
+        const values = extractEnumValues(node.content);
+        if (values) {
+            docs.push({
+                nodeId: node.id,
+                source: 'enum',
+                text: `${expandedName}: ${values}`,
+            });
+        }
+    }
+    return docs;
+}
+// ---------------------------------------------------------------------------
+// Full NL embedding pipeline
+// ---------------------------------------------------------------------------
+/** Hash text for skip detection */
+import { createHash } from 'crypto';
+function md5(text) {
+    return createHash('md5').update(text).digest('hex');
+}
+/**
+ * Build NL embeddings for all eligible nodes in the database.
+ * Reads nodes, extracts NL text, embeds with bge-small, writes to nl_embeddings.
+ */
+export async function buildNlEmbeddings(db, onProgress) {
+    const t0 = Date.now();
+    await initNlEmbedder();
+    // Query all nodes (not just EMBEDDABLE_LABELS — we want enums, consts, types too)
+    const labels = ['Function', 'Class', 'Method', 'Interface', 'Const', 'Enum', 'TypeAlias', 'Namespace', 'Module', 'Struct'];
+    const placeholders = labels.map(() => '?').join(',');
+    const rows = db.prepare(`SELECT id, name, label, filePath, content, startLine, description FROM nodes WHERE label IN (${placeholders})`).all(...labels);
+    // Skip test files
+    const testPatterns = ['/test/', '/tests/', '/spec/', '/fixtures/', '/__tests__/', '/__mocks__/', '.test.', '.spec.', '_test.', '_spec.'];
+    const filteredRows = rows.filter(r => !testPatterns.some(p => r.filePath.includes(p)));
+    // Extract NL documents
+    const allDocs = [];
+    for (const row of filteredRows) {
+        const docs = extractNlTexts(row);
+        for (const doc of docs)
+            allDocs.push(doc);
+    }
+    if (allDocs.length === 0) {
+        return { embedded: 0, skipped: 0, durationMs: Date.now() - t0 };
+    }
+    // Check existing hashes for skip detection
+    const existingHashes = new Map();
+    try {
+        const hashRows = db.prepare('SELECT nodeId, textHash FROM nl_embeddings WHERE textHash IS NOT NULL').all();
+        for (const r of hashRows)
+            existingHashes.set(r.nodeId + ':' + r.textHash, '1');
+    }
+    catch { /* table might not exist yet */ }
+    // Filter to docs that need embedding
+    const toEmbed = [];
+    let skipped = 0;
+    for (const doc of allDocs) {
+        const hash = md5(doc.text);
+        if (existingHashes.has(doc.nodeId + ':' + hash)) {
+            skipped++;
+            continue;
+        }
+        toEmbed.push({ ...doc, hash });
+    }
+    if (toEmbed.length === 0) {
+        return { embedded: 0, skipped, durationMs: Date.now() - t0 };
+    }
+    // Clear existing NL embeddings and rebuild
+    db.prepare('DELETE FROM nl_embeddings').run();
+    // Embed in batches and write to DB
+    const BATCH = 100;
+    const insertStmt = db.prepare('INSERT INTO nl_embeddings (nodeId, embedding, textHash, source, text) VALUES (?, ?, ?, ?, ?)');
+    let embedded = 0;
+    db.exec('BEGIN');
+    try {
+        for (let i = 0; i < toEmbed.length; i += BATCH) {
+            const batch = toEmbed.slice(i, i + BATCH);
+            const vecs = await nlEmbedBatch(batch.map(d => d.text));
+            for (let j = 0; j < batch.length; j++) {
+                const doc = batch[j];
+                const vec = vecs[j];
+                const blob = Buffer.from(new Float32Array(vec).buffer);
+                insertStmt.run(doc.nodeId, blob, doc.hash, doc.source, doc.text);
+                embedded++;
+            }
+            onProgress?.(Math.min(i + BATCH, toEmbed.length), toEmbed.length);
+        }
+        db.exec('COMMIT');
+    }
+    catch (err) {
+        db.exec('ROLLBACK');
+        throw err;
+    }
+    return { embedded, skipped, durationMs: Date.now() - t0 };
+}

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

@@ -42,6 +42,8 @@ export declare class LocalBackend {
     private tsgoServices;
     /** Per-repo in-memory embedding cache: nodeId → Float32Array (256-dim) */
     private embeddingCaches;
+    /** Per-repo in-memory NL embedding cache: includes source text for match_reason */
+    private nlEmbeddingCaches;
     /** 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. */
@@ -50,6 +52,10 @@ export declare class LocalBackend {
     private loadEmbeddingCache;
     /** Search embeddings in memory — O(N) dot products, no disk I/O */
     private searchEmbeddingsInMemory;
+    /** Load NL embeddings into memory for fast conceptual search */
+    private loadNlEmbeddingCache;
+    /** Search NL embeddings in memory, returns match_reason text */
+    private searchNlEmbeddingsInMemory;
     /** 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 */
@@ -131,6 +137,11 @@ export declare class LocalBackend {
      * Semantic vector search helper
      */
     private semanticSearch;
+    /**
+     * NL semantic search: embed query with bge-small, search NL descriptions.
+     * Returns match_reason (the NL text that matched) for agent transparency.
+     */
+    private nlSemanticSearch;
     /**
      * 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).

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

@@ -57,6 +57,8 @@ export class LocalBackend {
     tsgoServices = new Map();
     /** Per-repo in-memory embedding cache: nodeId → Float32Array (256-dim) */
     embeddingCaches = new Map();
+    /** Per-repo in-memory NL embedding cache: includes source text for match_reason */
+    nlEmbeddingCaches = 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);
@@ -140,6 +142,70 @@ export class LocalBackend {
         results.sort((a, b) => a.distance - b.distance);
         return results.slice(0, limit);
     }
+    /** Load NL embeddings into memory for fast conceptual search */
+    loadNlEmbeddingCache(repoId) {
+        try {
+            const db = this.getDb(repoId);
+            let rows;
+            try {
+                rows = db.prepare('SELECT nodeId, embedding, text FROM nl_embeddings').all();
+            }
+            catch {
+                return;
+            } // table might not exist
+            if (rows.length === 0) {
+                this.nlEmbeddingCaches.delete(repoId);
+                return;
+            }
+            const dims = rows[0].embedding.byteLength / 4;
+            const nodeIds = [];
+            const texts = [];
+            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);
+                texts.push(row.text);
+                const vec = new Float32Array(row.embedding.buffer, row.embedding.byteOffset, row.embedding.byteLength / 4);
+                matrix.set(vec, i * dims);
+                let norm = 0;
+                for (let d = 0; d < dims; d++)
+                    norm += vec[d] * vec[d];
+                norms[i] = Math.sqrt(norm);
+            }
+            this.nlEmbeddingCaches.set(repoId, { nodeIds, texts, matrix, norms });
+        }
+        catch { /* NL embeddings not available */ }
+    }
+    /** Search NL embeddings in memory, returns match_reason text */
+    searchNlEmbeddingsInMemory(repoId, queryVec, limit = 10, maxDistance = 0.5) {
+        const cache = this.nlEmbeddingCaches.get(repoId);
+        if (!cache || cache.nodeIds.length === 0)
+            return [];
+        const dims = queryVec.length;
+        const results = [];
+        let qNorm = 0;
+        for (let d = 0; d < dims; d++)
+            qNorm += queryVec[d] * queryVec[d];
+        qNorm = Math.sqrt(qNorm);
+        if (qNorm === 0)
+            return [];
+        const cacheDims = cache.matrix.length / cache.nodeIds.length;
+        for (let i = 0; i < cache.nodeIds.length; i++) {
+            const offset = i * cacheDims;
+            let dot = 0;
+            const minDims = Math.min(dims, cacheDims);
+            for (let d = 0; d < minDims; 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, text: cache.texts[i] });
+            }
+        }
+        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 */
@@ -273,11 +339,12 @@ export class LocalBackend {
         for (const [id, handle] of this.repos) {
             this.startWatcher(id, handle);
             this.seedWatcherFromGit(id, handle);
-            // Load embedding cache into memory for fast vector search
+            // Load embedding caches into memory for fast vector search
             if ((handle.stats?.embeddings ?? 0) > 0) {
                 this.loadEmbeddingCache(id);
                 anyEmbeddings = true;
             }
+            this.loadNlEmbeddingCache(id); // NL cache loaded regardless (cheap, may not exist)
         }
         // Pre-warm MLX embedder so first query has zero model-load latency
         if (anyEmbeddings) {
@@ -592,6 +659,9 @@ export class LocalBackend {
                 const end = d.endLine || 0;
                 const isSmall = end > 0 && start > 0 && (end - start) < 10;
                 lines.push(`  ${sig} — ${d.type} @ ${this.shortPath(d.filePath)}:${start || '?'}${mod}`);
+                if (d.match_reason) {
+                    lines.push(`    _"${d.match_reason}"_`);
+                }
                 if (isSmall && d.content) {
                     const src = String(d.content).trim();
                     if (src.length < 500) {
@@ -671,6 +741,9 @@ export class LocalBackend {
                 renderFlows(2);
             }
         }
+        lines.push('');
+        lines.push('---');
+        lines.push('_Note: Results ranked by BM25 keyword + semantic + refs + file-content signals. Natural language queries may miss code using different terminology. If results seem incomplete, try specific identifiers or `grep -rn "keyword" --include="*.ts"` for exhaustive search._');
         return lines.join('\n');
     }
     formatContextAsText(result) {
@@ -776,6 +849,10 @@ export class LocalBackend {
                 lines.push(`  ${p.name} (step ${p.step_index}/${p.step_count})`);
             }
         }
+        // Guidance footer for agents
+        lines.push('');
+        lines.push('---');
+        lines.push('_Note: Callers are from graph edges + refs index. For widely-used symbols, verify completeness with `grep -rn "symbolName(" --include="*.ts"`. Outgoing calls may miss dynamic dispatch or reflection._');
         return lines.join('\n');
     }
     formatImpactAsText(result) {
@@ -822,6 +899,9 @@ export class LocalBackend {
             lines.push('');
             lines.push(`### Modules: ${mods.map((m) => `${m.name} (${m.hits} ${m.impact})`).join(' | ')}`);
         }
+        lines.push('');
+        lines.push('---');
+        lines.push('_Note: d=1 callers include graph edges + refs index. Indirect deps through dynamic dispatch, config, or type-only references may not appear. For critical changes, verify d=1 with `grep -rn "symbolName" --include="*.ts"`._');
         return lines.join('\n');
     }
     formatDetectChangesAsText(result) {
@@ -1002,13 +1082,14 @@ export class LocalBackend {
         // 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, refsResults, fileWordsResults] = await Promise.all([
+        const [bm25Results, semanticResults, nlSemanticResults, refsResults, fileWordsResults] = await Promise.all([
             this.bm25Search(repo, expandedSearchQuery, searchLimit),
             this.semanticSearch(repo, semanticQuery, searchLimit),
+            this.nlSemanticSearch(repo, searchQuery, searchLimit),
             Promise.resolve(this.refsSearch(repo, searchQuery, searchLimit)),
             Promise.resolve(this.fileWordsSearch(repo, searchQuery, searchLimit)),
         ]);
-        // Step 2: Weighted RRF merge (4 signals)
+        // Step 2: Weighted RRF merge (5 signals)
         const bm25ForRRF = bm25Results.map((r, i) => ({
             nodeId: String(r.nodeId ?? ''),
             name: String(r.name ?? ''),
@@ -1038,7 +1119,26 @@ export class LocalBackend {
             ...(r.startLine != null ? { startLine: r.startLine } : {}),
             ...(r.endLine != null ? { endLine: r.endLine } : {}),
         }));
-        let rrfMerged = mergeWithRRF(bm25ForRRF, semanticForRRF, { limit: searchLimit });
+        // NL semantic results get high weight — proven 100% recall on conceptual queries
+        const nlForRRF = nlSemanticResults.map((r) => ({
+            nodeId: String(r.nodeId ?? ''), name: String(r.name ?? ''), label: String(r.type ?? ''),
+            filePath: String(r.filePath ?? ''), distance: Number(r.distance ?? 1),
+            ...(r.startLine != null ? { startLine: r.startLine } : {}),
+            ...(r.endLine != null ? { endLine: r.endLine } : {}),
+        }));
+        // Merge code + NL semantic into one semantic list (best of both worlds)
+        const combinedSemantic = [...semanticForRRF, ...nlForRRF]
+            .sort((a, b) => a.distance - b.distance)
+            .filter((r, i, arr) => arr.findIndex(x => x.nodeId === r.nodeId) === i) // dedupe by nodeId
+            .slice(0, searchLimit);
+        let rrfMerged = mergeWithRRF(bm25ForRRF, combinedSemantic, { limit: searchLimit });
+        // Store NL match reasons for display
+        const nlMatchReasons = new Map();
+        for (const r of nlSemanticResults) {
+            if (r.match_reason && !nlMatchReasons.has(r.nodeId)) {
+                nlMatchReasons.set(r.nodeId, r.match_reason);
+            }
+        }
         // Merge refs + fileWords into the RRF results (lower weight)
         if (refsForRRF.length > 0 || fileWordsForRRF.length > 0) {
             const supplemental = mergeWithRRF(refsForRRF, fileWordsForRRF.map((r) => ({
@@ -1084,13 +1184,22 @@ export class LocalBackend {
             if (!searchDataMap.has(key))
                 searchDataMap.set(key, r);
         }
-        let merged = rrfMerged.map(rrf => ({
-            score: rrf.score,
-            data: searchDataMap.get(rrf.nodeId ?? '') ?? searchDataMap.get(rrf.filePath) ?? {
+        for (const r of nlSemanticResults) {
+            const key = r.nodeId || r.filePath;
+            if (!searchDataMap.has(key))
+                searchDataMap.set(key, r);
+        }
+        let merged = rrfMerged.map(rrf => {
+            const data = searchDataMap.get(rrf.nodeId ?? '') ?? searchDataMap.get(rrf.filePath) ?? {
                 name: rrf.name ?? rrf.filePath.split('/').pop(), type: rrf.label ?? 'File',
                 filePath: rrf.filePath, nodeId: rrf.nodeId,
-            },
-        }));
+            };
+            // Attach NL match reason if available
+            const reason = nlMatchReasons.get(rrf.nodeId ?? '') ?? nlMatchReasons.get(data.nodeId ?? '');
+            if (reason)
+                data.match_reason = reason;
+            return { score: rrf.score, data };
+        });
         // Filter noise: remove test files, config files, docs from results by default
         merged = merged.filter(item => {
             const fp = String(item.data.filePath ?? '').toLowerCase();
@@ -1511,6 +1620,48 @@ export class LocalBackend {
             return [];
         }
     }
+    /**
+     * NL semantic search: embed query with bge-small, search NL descriptions.
+     * Returns match_reason (the NL text that matched) for agent transparency.
+     */
+    async nlSemanticSearch(repo, query, limit) {
+        try {
+            const cache = this.nlEmbeddingCaches.get(repo.id);
+            if (!cache || cache.nodeIds.length === 0)
+                return [];
+            const { nlEmbed } = await import('../../core/embeddings/nl-embedder.js');
+            const queryVec = await nlEmbed(query);
+            const vecResults = this.searchNlEmbeddingsInMemory(repo.id, queryVec, limit, 0.5);
+            if (vecResults.length === 0)
+                return [];
+            // Fetch node metadata
+            const metaDb = this.getDb(repo.id);
+            const seen = new Set();
+            const results = [];
+            for (const r of vecResults) {
+                if (seen.has(r.nodeId))
+                    continue;
+                seen.add(r.nodeId);
+                const node = getNode(metaDb, toNodeId(r.nodeId));
+                if (node) {
+                    results.push({
+                        nodeId: r.nodeId,
+                        name: node.name,
+                        type: node.label,
+                        filePath: node.filePath,
+                        distance: r.distance,
+                        startLine: node.startLine,
+                        endLine: node.endLine,
+                        match_reason: r.text, // The NL text that matched — shown to agents
+                    });
+                }
+            }
+            return results;
+        }
+        catch {
+            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).
@@ -2033,24 +2184,30 @@ export class LocalBackend {
         }
         // Supplement callers from refs table (catches callers the graph missed)
         try {
-            const refCallers = findRefsBySymbol(db, sym.name, 100);
+            const refCallers = findRefsBySymbol(db, sym.name, 200);
             const knownFiles = new Set(incomingRows.map(r => r.filePath));
+            let refsAdded = 0;
             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);
+                    continue; // already have a caller from this file
                 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',
-                    });
-                }
+                if (!enclosing)
+                    continue; // no symbol at this line (e.g. import statement)
+                knownFiles.add(ref.filePath); // mark AFTER finding a valid node
+                incomingRows.push({
+                    relType: 'CALLS', uid: '', name: enclosing.name, filePath: ref.filePath,
+                    kind: enclosing.label, startLine: ref.line, reason: 'refs-index',
+                });
+                refsAdded++;
             }
+            if (process.env['CODE_MAPPER_VERBOSE'])
+                console.error(`Code Mapper: refs supplement for '${sym.name}': ${refsAdded} added from ${refCallers.length} refs`);
+        }
+        catch (err) {
+            console.error(`Code Mapper: refs supplement failed: ${err instanceof Error ? err.message : err}`);
         }
-        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 = [];
@@ -2388,10 +2545,44 @@ export class LocalBackend {
                 logQueryError('rename:read-ref', e);
             }
         }
-        // Step 3: Text search for refs the graph might have missed
-        let astSearchEdits = 0;
+        // Step 3a: Refs table lookup (instant, covers most cases the graph missed)
+        let refsEdits = 0;
         const graphFiles = new Set([sym.filePath, ...allIncoming.map(r => r.filePath)].filter(Boolean));
-        // Simple text search across the repo for the old name (in files not already covered by graph)
+        try {
+            const refsDb = this.getDb(repo.id);
+            const refsForName = findRefsBySymbol(refsDb, oldName, 500);
+            for (const ref of refsForName) {
+                const normalizedFile = ref.filePath.replace(/\\/g, '/');
+                if (graphFiles.has(normalizedFile))
+                    continue;
+                graphFiles.add(normalizedFile); // mark so ripgrep doesn't re-process
+                try {
+                    const content = await fs.readFile(assertSafePath(normalizedFile), 'utf-8');
+                    const lines = content.split('\n');
+                    const regex = new RegExp(`\\b${oldName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`, 'g');
+                    for (let i = 0; i < lines.length; i++) {
+                        const searchLine = lines[i];
+                        if (!searchLine)
+                            continue;
+                        regex.lastIndex = 0;
+                        if (regex.test(searchLine)) {
+                            regex.lastIndex = 0;
+                            addEdit(normalizedFile, i + 1, searchLine.trim(), searchLine.replace(regex, new_name).trim(), 'refs');
+                            refsEdits++;
+                        }
+                    }
+                }
+                catch (e) {
+                    logQueryError('rename:refs-read', e);
+                }
+            }
+        }
+        catch (e) {
+            logQueryError('rename:refs', e);
+        }
+        // Step 3b: Ripgrep text search for anything refs + graph missed
+        let astSearchEdits = 0;
+        // Simple text search across the repo for the old name (in files not already covered)
         try {
             const { execFileSync } = await import('child_process');
             const rgArgs = [
@@ -2456,9 +2647,11 @@ export class LocalBackend {
             files_affected: allChanges.length,
             total_edits: totalEdits,
             graph_edits: graphEdits,
+            refs_edits: refsEdits,
             text_search_edits: astSearchEdits,
             changes: allChanges,
             applied: !dry_run,
+            _note: 'Rename uses graph edges + refs index + ripgrep. Always review changes before applying. String literals, comments, and dynamic references (e.g. obj[methodName]) need manual review.',
         };
     }
     async impact(repo, params) {
@@ -2535,6 +2728,32 @@ export class LocalBackend {
                 }
             }
         }
+        // Supplement d=1 callers from refs table (catches callers the graph missed)
+        if (direction === 'upstream') {
+            try {
+                const targetName = sym.name;
+                const d1FromRefs = findRefsBySymbol(db, targetName, 200);
+                for (const ref of d1FromRefs) {
+                    if (ref.filePath === sym.filePath)
+                        continue;
+                    const refNode = this.findNodeAtPosition(db, ref.filePath, ref.line);
+                    if (refNode && !seenIds.has(refNode.name + ':' + ref.filePath)) {
+                        // Find the actual node ID for this position
+                        const fullNodes = findNodesByFile(db, ref.filePath);
+                        const match = fullNodes.find(n => n.name === refNode.name && n.startLine != null && n.startLine <= ref.line + 1 && (n.endLine ?? 9999) >= ref.line + 1);
+                        if (match && !seenIds.has(match.id) && !startIds.some(s => s === match.id)) {
+                            seenIds.add(match.id);
+                            mergedNodes.push({
+                                id: match.id, name: match.name, label: match.label,
+                                filePath: match.filePath, depth: 1,
+                                relationType: 'CALLS', confidence: 0.8,
+                            });
+                        }
+                    }
+                }
+            }
+            catch { /* refs table may not exist */ }
+        }
         const impacted = mergedNodes;
         const truncated = anyTruncated;
         const grouped = {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zuvia-software-solutions/code-mapper",
-  "version": "2.4.0",
+  "version": "2.4.1",
   "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",