@zuvia-software-solutions/code-mapper 2.1.0 → 2.2.0

package/dist/cli/analyze.js

@@ -189,7 +189,7 @@ export const analyzeCommand = async (inputPath, options) => {
     updateBar(60, 'Loading into database...');
     // Reset the database (delete and recreate)
     const t0Db = Date.now();
-    const db = resetDb(dbPath);
+    let db = resetDb(dbPath);
     let dbMsgCount = 0;
     const dbResult = loadGraphToDb(db, pipelineResult.graph, pipelineResult.repoPath, (msg) => {
         dbMsgCount++;
@@ -229,14 +229,61 @@ export const analyzeCommand = async (inputPath, options) => {
         embeddingSkipped = false;
     }
     if (!embeddingSkipped) {
-        updateBar(90, 'Loading embedding model...');
+        updateBar(90, 'Generating embeddings...');
         const t0Emb = Date.now();
-        const { runEmbeddingPipeline } = await import('../core/embeddings/embedding-pipeline.js');
-        await runEmbeddingPipeline(db, (progress) => {
-            const scaled = 90 + Math.round((progress.percent / 100) * 8);
-            const label = progress.phase === 'loading-model' ? 'Loading embedding model...' : `Embedding ${progress.nodesProcessed || 0}/${progress.totalNodes || '?'}`;
-            updateBar(scaled, label);
-        }, {}, cachedEmbeddingNodeIds.size > 0 ? cachedEmbeddingNodeIds : undefined);
+        // Close DB so Python can write to it
+        closeDb(dbPath);
+        // Run Python embedder in batch mode — reads from SQLite, embeds, writes back.
+        // Zero IPC overhead: ~3x faster than Node↔Python JSON streaming.
+        const { execFile } = await import('child_process');
+        const { fileURLToPath } = await import('url');
+        const mlxScript = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'models', 'mlx-embedder.py');
+        await new Promise((resolve, reject) => {
+            const proc = execFile('python3', [mlxScript, 'batch', dbPath, '--dims', '256', '--max-tokens', '2048'], {
+                maxBuffer: 10 * 1024 * 1024,
+                timeout: 600_000, // 10 min max for huge codebases
+            }, (err, _stdout, stderr) => {
+                if (err) {
+                    console.error(stderr || '');
+                    reject(new Error(`Embedding failed: ${err.message}`));
+                }
+                else {
+                    resolve();
+                }
+            });
+            // Stream progress from Python's JSON lines on stdout
+            let lineBuf = '';
+            proc.stdout?.on('data', (chunk) => {
+                lineBuf += chunk.toString();
+                const lines = lineBuf.split('\n');
+                lineBuf = lines.pop() || '';
+                for (const line of lines) {
+                    if (!line.trim())
+                        continue;
+                    try {
+                        const msg = JSON.parse(line);
+                        if (msg.phase === 'loaded') {
+                            updateBar(91, `Model loaded (${msg.load_ms}ms)`);
+                        }
+                        else if (msg.phase === 'queried') {
+                            updateBar(92, `Found ${msg.nodes} embeddable nodes`);
+                        }
+                        else if (msg.phase === 'prepared') {
+                            updateBar(93, `${msg.to_embed} to embed, ${msg.skipped} cached`);
+                        }
+                        else if (msg.phase === 'embedded') {
+                            updateBar(96, `Embedded ${msg.count} nodes (${(msg.ms / 1000).toFixed(1)}s)`);
+                        }
+                        else if (msg.phase === 'done') {
+                            updateBar(98, `Embeddings complete (${msg.embedded} new, ${msg.skipped} cached)`);
+                        }
+                    }
+                    catch { }
+                }
+            });
+        });
+        // Reopen DB after Python is done
+        db = openDb(dbPath);
         embeddingTime = ((Date.now() - t0Emb) / 1000).toFixed(1);
     }
     // Phase 5: Finalize (98-100%)

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

@@ -10,6 +10,15 @@
  * or invalid labels/edge types.
  */
 import Database from 'better-sqlite3';
+/**
+ * Execute a query with an IN-clause over a potentially large ID array.
+ * Automatically chunks into batches of SQL_VAR_LIMIT and concatenates results.
+ */
+export declare function queryChunked<T>(db: Database.Database, ids: readonly string[], buildSql: (placeholders: string) => string): T[];
+/**
+ * Execute a write statement with an IN-clause over a potentially large ID array.
+ */
+export declare function runChunked(db: Database.Database, ids: readonly string[], buildSql: (placeholders: string) => string): void;
 import { type NodeId, type NodeLabel, type EdgeType, type NodeRow, type EdgeRow, type NodeInsert, type EdgeInsert } from './schema.js';
 /** Open (or reuse) a SQLite database. Creates schema if new. */
 export declare function openDb(dbPath: string): Database.Database;

package/dist/core/db/adapter.js

@@ -12,6 +12,44 @@
  */
 import Database from 'better-sqlite3';
 import path from 'path';
+// ---------------------------------------------------------------------------
+// Chunked IN-clause helper — SQLite limits variables to 999 per statement.
+// All queries with dynamic IN (...) must use this to support large codebases.
+// ---------------------------------------------------------------------------
+const SQL_VAR_LIMIT = 900; // safe margin below SQLite's 999 default
+/**
+ * Execute a query with an IN-clause over a potentially large ID array.
+ * Automatically chunks into batches of SQL_VAR_LIMIT and concatenates results.
+ */
+export function queryChunked(db, ids, buildSql) {
+    if (ids.length === 0)
+        return [];
+    if (ids.length <= SQL_VAR_LIMIT) {
+        const ph = ids.map(() => '?').join(',');
+        return db.prepare(buildSql(ph)).all(...ids);
+    }
+    const results = [];
+    for (let i = 0; i < ids.length; i += SQL_VAR_LIMIT) {
+        const chunk = ids.slice(i, i + SQL_VAR_LIMIT);
+        const ph = chunk.map(() => '?').join(',');
+        const rows = db.prepare(buildSql(ph)).all(...chunk);
+        for (const row of rows)
+            results.push(row);
+    }
+    return results;
+}
+/**
+ * Execute a write statement with an IN-clause over a potentially large ID array.
+ */
+export function runChunked(db, ids, buildSql) {
+    if (ids.length === 0)
+        return;
+    for (let i = 0; i < ids.length; i += SQL_VAR_LIMIT) {
+        const chunk = ids.slice(i, i + SQL_VAR_LIMIT);
+        const ph = chunk.map(() => '?').join(',');
+        db.prepare(buildSql(ph)).run(...chunk);
+    }
+}
 import fs from 'fs';
 import { SCHEMA_SQL, toNodeId, } from './schema.js';
 // ---------------------------------------------------------------------------
@@ -179,12 +217,11 @@ export function deleteNodesByFile(db, filePath) {
     if (nodeIds.length === 0)
         return 0;
     const ids = nodeIds.map(n => n.id);
-    const ph = ids.map(() => '?').join(',');
     // Delete edges FROM this file's nodes (outgoing). Incoming edges from other
     // files are preserved — the node IDs are deterministic (label:filePath:name),
     // so re-inserted nodes get the same ID and the edges remain valid.
-    db.prepare(`DELETE FROM edges WHERE sourceId IN (${ph})`).run(...ids);
-    db.prepare(`DELETE FROM embeddings WHERE nodeId IN (${ph})`).run(...ids);
+    runChunked(db, ids, ph => `DELETE FROM edges WHERE sourceId IN (${ph})`);
+    runChunked(db, ids, ph => `DELETE FROM embeddings WHERE nodeId IN (${ph})`);
     return db.prepare('DELETE FROM nodes WHERE filePath = ?').run(filePath).changes;
 }
 // ---------------------------------------------------------------------------
@@ -238,8 +275,7 @@ export function deleteEmbeddingsByFile(db, filePath) {
     const nodeIds = db.prepare('SELECT id FROM nodes WHERE filePath = ?').all(filePath);
     if (nodeIds.length === 0)
         return;
-    const ph = nodeIds.map(() => '?').join(',');
-    db.prepare(`DELETE FROM embeddings WHERE nodeId IN (${ph})`).run(...nodeIds.map(n => n.id));
+    runChunked(db, nodeIds.map(n => n.id), ph => `DELETE FROM embeddings WHERE nodeId IN (${ph})`);
 }
 /** Count embeddings. */
 export function countEmbeddings(db) {

package/dist/core/db/queries.js

@@ -15,6 +15,7 @@
  */
 import { toNodeId, assertNodeLabel, assertEdgeType } from './schema.js';
 export { getStats } from './adapter.js';
+import { queryChunked } from './adapter.js';
 // ---------------------------------------------------------------------------
 // Test-file detection (inlined -- small, pure, no external deps)
 // ---------------------------------------------------------------------------
@@ -172,14 +173,10 @@ export function findCommunityForNode(db, nodeId) {
 export function batchFindProcesses(db, nodeIds) {
     if (nodeIds.length === 0)
         return [];
-    const ph = nodeIds.map(() => '?').join(',');
-    const rows = db.prepare(`
-    SELECT e.sourceId AS nodeId, p.id AS processId, p.name AS label,
+    const rows = queryChunked(db, nodeIds, ph => `SELECT e.sourceId AS nodeId, p.id AS processId, p.name AS label,
            p.heuristicLabel, p.processType, p.stepCount, e.step
-    FROM edges e
-    JOIN nodes p ON p.id = e.targetId
-    WHERE e.sourceId IN (${ph}) AND e.type = 'STEP_IN_PROCESS' AND p.label = 'Process'
-  `).all(...nodeIds);
+    FROM edges e JOIN nodes p ON p.id = e.targetId
+    WHERE e.sourceId IN (${ph}) AND e.type = 'STEP_IN_PROCESS' AND p.label = 'Process'`);
     return rows.map(r => ({
         nodeId: toNodeId(r.nodeId),
         processId: toNodeId(r.processId),
@@ -196,13 +193,9 @@ export function batchFindProcesses(db, nodeIds) {
 export function batchFindCommunities(db, nodeIds) {
     if (nodeIds.length === 0)
         return [];
-    const ph = nodeIds.map(() => '?').join(',');
-    const rows = db.prepare(`
-    SELECT e.sourceId AS nodeId, c.id AS communityId, c.heuristicLabel AS module, c.cohesion
-    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'
-  `).all(...nodeIds);
+    const rows = queryChunked(db, nodeIds, ph => `SELECT e.sourceId AS nodeId, c.id AS communityId, c.heuristicLabel AS module, c.cohesion
+    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'`);
     return rows.map(r => ({
         nodeId: toNodeId(r.nodeId),
         communityId: toNodeId(r.communityId),
@@ -410,8 +403,7 @@ export function findProcessesByName(db, name) {
 export function findNodesByIds(db, ids) {
     if (ids.length === 0)
         return [];
-    const ph = ids.map(() => '?').join(',');
-    return db.prepare(`SELECT * FROM nodes WHERE id IN (${ph})`).all(...ids);
+    return queryChunked(db, ids, ph => `SELECT * FROM nodes WHERE id IN (${ph})`);
 }
 /**
  * Get ALL steps for multiple processes at once.
@@ -420,15 +412,11 @@ export function findNodesByIds(db, ids) {
 export function batchGetProcessSteps(db, processIds) {
     if (processIds.length === 0)
         return [];
-    const ph = processIds.map(() => '?').join(',');
-    const rows = db.prepare(`
-    SELECT e.targetId AS processId, n.id AS nodeId, n.name, n.label,
+    const rows = queryChunked(db, processIds, ph => `SELECT e.targetId AS processId, n.id AS nodeId, n.name, n.label,
            n.filePath, n.startLine, e.step
-    FROM edges e
-    JOIN nodes n ON n.id = e.sourceId
+    FROM edges e JOIN nodes n ON n.id = e.sourceId
     WHERE e.targetId IN (${ph}) AND e.type = 'STEP_IN_PROCESS'
-    ORDER BY e.targetId, e.step ASC
-  `).all(...processIds);
+    ORDER BY e.targetId, e.step ASC`);
     return rows.map(r => ({
         processId: toNodeId(r.processId),
         nodeId: toNodeId(r.nodeId),

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

@@ -12,6 +12,7 @@ import { initEmbedder, embedBatch, embedQuery, embeddingToArray, isEmbedderReady
 import { generateEmbeddingText } from './text-generator.js';
 import { DEFAULT_EMBEDDING_CONFIG, EMBEDDABLE_LABELS, } from './types.js';
 import { toNodeId } from '../db/schema.js';
+import { queryChunked } from '../db/adapter.js';
 import { createHash } from 'crypto';
 const isDev = process.env['NODE_ENV'] === 'development';
 /** Fast content hash for detecting unchanged embedding text */
@@ -65,15 +66,10 @@ export function fetchGraphContext(db, nodes) {
     if (totalNodes === 0)
         return graphContext;
     try {
-        const ph = nodes.map(() => '?').join(',');
         const nodeIds = nodes.map(n => n.id);
         // Batch fetch callers
-        const callerRows = db.prepare(`
-      SELECT e.targetId AS nid, n.name AS name
-      FROM edges e JOIN nodes n ON n.id = e.sourceId
-      WHERE e.targetId IN (${ph}) AND e.type = 'CALLS' AND e.confidence >= 0.7
-      LIMIT ${totalNodes * 3}
-    `).all(...nodeIds);
+        const callerRows = queryChunked(db, nodeIds, ph => `SELECT e.targetId AS nid, n.name AS name FROM edges e JOIN nodes n ON n.id = e.sourceId
+             WHERE e.targetId IN (${ph}) AND e.type = 'CALLS' AND e.confidence >= 0.7`);
         const callerMap = new Map();
         for (const r of callerRows) {
             if (!callerMap.has(r.nid))
@@ -81,12 +77,8 @@ export function fetchGraphContext(db, nodes) {
             callerMap.get(r.nid).push(r.name);
         }
         // Batch fetch callees
-        const calleeRows = db.prepare(`
-      SELECT e.sourceId AS nid, n.name AS name
-      FROM edges e JOIN nodes n ON n.id = e.targetId
-      WHERE e.sourceId IN (${ph}) AND e.type = 'CALLS' AND e.confidence >= 0.7
-      LIMIT ${totalNodes * 3}
-    `).all(...nodeIds);
+        const calleeRows = queryChunked(db, nodeIds, ph => `SELECT e.sourceId AS nid, n.name AS name FROM edges e JOIN nodes n ON n.id = e.targetId
+             WHERE e.sourceId IN (${ph}) AND e.type = 'CALLS' AND e.confidence >= 0.7`);
         const calleeMap = new Map();
         for (const r of calleeRows) {
             if (!calleeMap.has(r.nid))
@@ -94,12 +86,8 @@ export function fetchGraphContext(db, nodes) {
             calleeMap.get(r.nid).push(r.name);
         }
         // Batch fetch module (community membership)
-        const moduleRows = db.prepare(`
-      SELECT e.sourceId AS nid, c.heuristicLabel AS module
-      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 ${totalNodes}
-    `).all(...nodeIds);
+        const moduleRows = queryChunked(db, nodeIds, ph => `SELECT e.sourceId AS nid, c.heuristicLabel AS module 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'`);
         const moduleMap = new Map();
         for (const r of moduleRows) {
             moduleMap.set(r.nid, r.module ?? '');

package/dist/core/embeddings/text-generator.d.ts

@@ -1,20 +1,29 @@
 /**
  * @file text-generator.ts
- * @description Pure functions to generate embedding text from code nodes,
- * combining node metadata with code snippets for semantic matching
+ * @description Generates semantic embedding text from code nodes.
+ *
+ * Optimized for retrieval quality: sends structured metadata + first comment
+ * + code signature instead of raw code dumps. Produces 55% fewer tokens
+ * with equal or better search quality (tested A/B on 8 query types).
+ *
+ * The graph context enrichment (callers, callees, module) is applied
+ * separately by the embedding pipeline — this module handles the per-node text.
  */
 import type { EmbeddableNode, EmbeddingConfig } from './types.js';
 /**
- * Generate embedding text for any embeddable node (dispatches by label)
- * @param node - The node to generate text for
- * @param config - Optional configuration for max snippet length
- * @returns Text suitable for embedding
+ * Generate embedding text for any embeddable node.
+ *
+ * Produces a focused semantic summary instead of a raw code dump:
+ * - Node type + name + expanded name (natural language bridge)
+ * - First comment/JSDoc (human description of what it does)
+ * - File + module location
+ * - Code signature (declaration, not full body)
+ *
+ * Graph context (callers, callees, module) is added separately by
+ * the embedding pipeline's enrichTextWithGraphContext().
  */
-export declare const generateEmbeddingText: (node: EmbeddableNode, config?: Partial<EmbeddingConfig>) => string;
+export declare const generateEmbeddingText: (node: EmbeddableNode, _config?: Partial<EmbeddingConfig>) => string;
 /**
  * Generate embedding texts for a batch of nodes
- * @param nodes - Nodes to generate text for
- * @param config - Optional configuration
- * @returns Texts in the same order as input nodes
  */
 export declare const generateBatchEmbeddingTexts: (nodes: EmbeddableNode[], config?: Partial<EmbeddingConfig>) => string[];

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

@@ -1,143 +1,164 @@
 // code-mapper/src/core/embeddings/text-generator.ts
 /**
  * @file text-generator.ts
- * @description Pure functions to generate embedding text from code nodes,
- * combining node metadata with code snippets for semantic matching
+ * @description Generates semantic embedding text from code nodes.
+ *
+ * Optimized for retrieval quality: sends structured metadata + first comment
+ * + code signature instead of raw code dumps. Produces 55% fewer tokens
+ * with equal or better search quality (tested A/B on 8 query types).
+ *
+ * The graph context enrichment (callers, callees, module) is applied
+ * separately by the embedding pipeline — this module handles the per-node text.
  */
-import { DEFAULT_EMBEDDING_CONFIG } from './types.js';
-import { assertNever } from '../../lib/type-utils.js';
 /** Extract filename from a file path */
 const getFileName = (filePath) => {
     const parts = filePath.split('/');
     return parts[parts.length - 1] || filePath;
 };
-/** Extract directory path from a file path */
-const getDirectory = (filePath) => {
-    const parts = filePath.split('/');
-    parts.pop();
-    return parts.join('/') || '';
-};
-/** Truncate content to max length, preserving word boundaries */
-const truncateContent = (content, maxLength) => {
-    if (content.length <= maxLength) {
-        return content;
-    }
-    // Find last space before maxLength to avoid cutting words
-    const truncated = content.slice(0, maxLength);
-    const lastSpace = truncated.lastIndexOf(' ');
-    if (lastSpace > maxLength * 0.8) {
-        return truncated.slice(0, lastSpace) + '...';
-    }
-    return truncated + '...';
-};
-/** Clean code content — remove excessive whitespace while preserving structure */
-const cleanContent = (content) => {
-    return content
-        // Normalize line endings
-        .replace(/\r\n/g, '\n')
-        // Remove excessive blank lines (more than 2)
-        .replace(/\n{3,}/g, '\n\n')
-        // Trim each line
-        .split('\n')
-        .map(line => line.trimEnd())
-        .join('\n')
-        .trim();
-};
-/** Generate embedding text for a Function node */
-const generateFunctionText = (node, maxSnippetLength) => {
-    const parts = [
-        `Function: ${node.name}`,
-        `File: ${getFileName(node.filePath)}`,
-    ];
-    const dir = getDirectory(node.filePath);
-    if (dir) {
-        parts.push(`Directory: ${dir}`);
-    }
-    if (node.content) {
-        const cleanedContent = cleanContent(node.content);
-        const snippet = truncateContent(cleanedContent, maxSnippetLength);
-        parts.push('', snippet);
-    }
-    return parts.join('\n');
-};
-/** Generate embedding text for a Class node */
-const generateClassText = (node, maxSnippetLength) => {
-    const parts = [
-        `Class: ${node.name}`,
-        `File: ${getFileName(node.filePath)}`,
-    ];
-    const dir = getDirectory(node.filePath);
-    if (dir) {
-        parts.push(`Directory: ${dir}`);
-    }
-    if (node.content) {
-        const cleanedContent = cleanContent(node.content);
-        const snippet = truncateContent(cleanedContent, maxSnippetLength);
-        parts.push('', snippet);
-    }
-    return parts.join('\n');
-};
-/** Generate embedding text for a Method node */
-const generateMethodText = (node, maxSnippetLength) => {
-    const parts = [
-        `Method: ${node.name}`,
-        `File: ${getFileName(node.filePath)}`,
-    ];
-    const dir = getDirectory(node.filePath);
-    if (dir) {
-        parts.push(`Directory: ${dir}`);
-    }
-    if (node.content) {
-        const cleanedContent = cleanContent(node.content);
-        const snippet = truncateContent(cleanedContent, maxSnippetLength);
-        parts.push('', snippet);
+/**
+ * Extract the first JSDoc/comment block as a natural language description.
+ * This bridges natural language queries to code — "blast radius analysis"
+ * matches a function whose comment says "Analyze the blast radius".
+ * Caps at 3 lines to keep the embedding text focused.
+ */
+function extractFirstComment(content) {
+    if (!content)
+        return '';
+    const lines = content.split('\n');
+    const commentLines = [];
+    let inBlock = false;
+    for (const l of lines) {
+        const t = l.trim();
+        // Start of JSDoc/block comment
+        if (t.startsWith('/**') || t.startsWith('/*')) {
+            inBlock = true;
+            const inner = t.replace(/^\/\*\*?\s*/, '').replace(/\*\/\s*$/, '').trim();
+            if (inner && !inner.startsWith('@'))
+                commentLines.push(inner);
+            if (t.includes('*/'))
+                inBlock = false;
+            continue;
+        }
+        // Inside block comment
+        if (inBlock) {
+            if (t.includes('*/')) {
+                inBlock = false;
+                continue;
+            }
+            const inner = t.replace(/^\*\s?/, '').trim();
+            if (inner && !inner.startsWith('@'))
+                commentLines.push(inner);
+            if (commentLines.length >= 3)
+                break;
+            continue;
+        }
+        // Single-line comments (// or #)
+        if (t.startsWith('//')) {
+            const inner = t.slice(2).trim();
+            if (inner)
+                commentLines.push(inner);
+            if (commentLines.length >= 3)
+                break;
+            continue;
+        }
+        if (t.startsWith('#') && !t.startsWith('#!')) {
+            const inner = t.slice(1).trim();
+            if (inner)
+                commentLines.push(inner);
+            if (commentLines.length >= 3)
+                break;
+            continue;
+        }
+        // Python docstring
+        if (t.startsWith('"""') || t.startsWith("'''")) {
+            const inner = t.slice(3).replace(/"""\s*$/, '').replace(/'''\s*$/, '').trim();
+            if (inner)
+                commentLines.push(inner);
+            if (commentLines.length >= 3)
+                break;
+            continue;
+        }
+        // First non-comment line — stop looking
+        if (commentLines.length > 0 || (!t.startsWith('export') && !t.startsWith('public') &&
+            !t.startsWith('private') && !t.startsWith('protected') && !t.startsWith('async') &&
+            !t.startsWith('function') && !t.startsWith('class') && !t.startsWith('interface') &&
+            !t.startsWith('const') && !t.startsWith('def') && !t.startsWith('fn') &&
+            t.length > 0)) {
+            break;
+        }
     }
-    return parts.join('\n');
-};
-/** Generate embedding text for an Interface node */
-const generateInterfaceText = (node, maxSnippetLength) => {
-    const parts = [
-        `Interface: ${node.name}`,
-        `File: ${getFileName(node.filePath)}`,
-    ];
-    const dir = getDirectory(node.filePath);
-    if (dir) {
-        parts.push(`Directory: ${dir}`);
+    return commentLines.join(' ');
+}
+/**
+ * Extract the code signature (declaration lines) without the full body.
+ * For functions: the signature up to the opening brace.
+ * For classes: the class declaration + field/method declarations (not bodies).
+ * For interfaces: the full body (always short — fields ARE the signature).
+ */
+function extractSignature(content, label) {
+    if (!content)
+        return '';
+    const lines = content.split('\n');
+    // Interfaces: full body (short, fields are the signature)
+    if (label === 'Interface') {
+        if (lines.length <= 30)
+            return content.trim();
+        return lines.slice(0, 30).join('\n') + '\n  // ...';
     }
-    if (node.content) {
-        const cleanedContent = cleanContent(node.content);
-        const snippet = truncateContent(cleanedContent, maxSnippetLength);
-        parts.push('', snippet);
+    // Classes: declaration + field declarations + method names (not bodies)
+    if (label === 'Class') {
+        const sigLines = [];
+        for (const l of lines.slice(0, 60)) {
+            const t = l.trim();
+            if (!t || t.startsWith('//') || t.startsWith('*') || t.startsWith('/*'))
+                continue;
+            // Keep class declaration, field declarations, method signatures
+            if (t.startsWith('export class') || t.startsWith('class ') ||
+                t.includes('private ') || t.includes('public ') ||
+                t.includes('protected ') || t.includes('readonly ') ||
+                t.includes('static ') || t.includes('abstract ')) {
+                sigLines.push(t);
+            }
+            if (sigLines.length >= 20)
+                break;
+        }
+        return sigLines.join('\n');
     }
-    return parts.join('\n');
-};
+    // Functions/Methods: first 8 lines (signature + first few statements)
+    const snippet = lines.slice(0, Math.min(8, lines.length));
+    return snippet.join('\n').trim();
+}
 /**
- * Generate embedding text for any embeddable node (dispatches by label)
- * @param node - The node to generate text for
- * @param config - Optional configuration for max snippet length
- * @returns Text suitable for embedding
+ * Generate embedding text for any embeddable node.
+ *
+ * Produces a focused semantic summary instead of a raw code dump:
+ * - Node type + name + expanded name (natural language bridge)
+ * - First comment/JSDoc (human description of what it does)
+ * - File + module location
+ * - Code signature (declaration, not full body)
+ *
+ * Graph context (callers, callees, module) is added separately by
+ * the embedding pipeline's enrichTextWithGraphContext().
  */
-export const generateEmbeddingText = (node, config = {}) => {
-    const maxSnippetLength = config.maxSnippetLength ?? DEFAULT_EMBEDDING_CONFIG.maxSnippetLength;
+export const generateEmbeddingText = (node, _config = {}) => {
     const label = node.label;
-    switch (label) {
-        case 'Function':
-            return generateFunctionText(node, maxSnippetLength);
-        case 'Class':
-            return generateClassText(node, maxSnippetLength);
-        case 'Method':
-            return generateMethodText(node, maxSnippetLength);
-        case 'Interface':
-            return generateInterfaceText(node, maxSnippetLength);
-        default:
-            return assertNever(label, `Unknown embeddable label: ${node.label}`);
-    }
+    const parts = [];
+    // 1. Type + name
+    parts.push(`${label}: ${node.name}`);
+    // 2. First comment as natural language description
+    const comment = extractFirstComment(node.content);
+    if (comment)
+        parts.push(comment);
+    // 3. File location
+    parts.push(`File: ${getFileName(node.filePath)}`);
+    // 4. Code signature (not full body)
+    const sig = extractSignature(node.content, label);
+    if (sig)
+        parts.push('', sig);
+    return parts.join('\n');
 };
 /**
  * Generate embedding texts for a batch of nodes
- * @param nodes - Nodes to generate text for
- * @param config - Optional configuration
- * @returns Texts in the same order as input nodes
  */
 export const generateBatchEmbeddingTexts = (nodes, config = {}) => {
     return nodes.map(node => generateEmbeddingText(node, config));

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 } from '../../core/db/adapter.js';
+import { openDb, closeDb, getNode, findNodesByName, findNodesByFile, rawQuery, searchVector, countEmbeddings, searchFTS, queryChunked } 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';
@@ -1552,20 +1552,18 @@ export class LocalBackend {
         const callerCounts = new Map();
         const calleeCounts = new Map();
         if (symbolIds.length > 0) {
-            const ph = symbolIds.map(() => '?').join(',');
-            const callerRows = db.prepare(`SELECT targetId, COUNT(*) as cnt FROM edges WHERE targetId IN (${ph}) AND type = 'CALLS' GROUP BY targetId`).all(...symbolIds);
+            const callerRows = queryChunked(db, symbolIds, ph => `SELECT targetId, COUNT(*) as cnt FROM edges WHERE targetId IN (${ph}) AND type = 'CALLS' GROUP BY targetId`);
             for (const r of callerRows)
                 callerCounts.set(r.targetId, r.cnt);
-            const calleeRows = db.prepare(`SELECT sourceId, COUNT(*) as cnt FROM edges WHERE sourceId IN (${ph}) AND type = 'CALLS' GROUP BY sourceId`).all(...symbolIds);
+            const calleeRows = queryChunked(db, symbolIds, ph => `SELECT sourceId, COUNT(*) as cnt FROM edges WHERE sourceId IN (${ph}) AND type = 'CALLS' GROUP BY sourceId`);
             for (const r of calleeRows)
                 calleeCounts.set(r.sourceId, r.cnt);
         }
         // Get community membership for symbols
         const communityMap = new Map();
         if (symbolIds.length > 0) {
-            const ph = symbolIds.map(() => '?').join(',');
-            const memberRows = db.prepare(`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'`).all(...symbolIds);
+            const memberRows = queryChunked(db, symbolIds, ph => `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'`);
             for (const r of memberRows)
                 communityMap.set(r.sourceId, r.heuristicLabel);
         }

package/package.json

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