@zuvia-software-solutions/code-mapper 1.4.0 → 2.0.1

package/dist/core/graph/graph.d.ts

@@ -1,4 +1,4 @@
 /** @file graph.ts @description Factory for creating in-memory knowledge graphs backed by Maps for O(1) lookups */
-import { KnowledgeGraph } from './types.js';
+import { type KnowledgeGraph } from './types.js';
 /** Create a new empty KnowledgeGraph instance */
 export declare const createKnowledgeGraph: () => KnowledgeGraph;

package/dist/core/graph/graph.js

@@ -1,5 +1,6 @@
 // code-mapper/src/core/graph/graph.ts
 /** @file graph.ts @description Factory for creating in-memory knowledge graphs backed by Maps for O(1) lookups */
+import {} from './types.js';
 /** Create a new empty KnowledgeGraph instance */
 export const createKnowledgeGraph = () => {
     const nodeMap = new Map();

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

@@ -1,6 +1,7 @@
 /** @file types.ts @description Core type definitions for the knowledge graph: nodes, relationships, and the graph interface */
-export type NodeLabel = 'Project' | 'Package' | 'Module' | 'Folder' | 'File' | 'Class' | 'Function' | 'Method' | 'Variable' | 'Interface' | 'Enum' | 'Decorator' | 'Import' | 'Type' | 'CodeElement' | 'Community' | 'Process' | 'Struct' | 'Macro' | 'Typedef' | 'Union' | 'Namespace' | 'Trait' | 'Impl' | 'TypeAlias' | 'Const' | 'Static' | 'Property' | 'Record' | 'Delegate' | 'Annotation' | 'Constructor' | 'Template';
+import { type NodeLabel, type EdgeType, type NodeId, type EdgeId } from '../db/schema.js';
 import { SupportedLanguages } from '../../config/supported-languages.js';
+export { type NodeLabel, type EdgeType, type NodeId, type EdgeId } from '../db/schema.js';
 export type NodeProperties = {
     name: string;
     filePath: string;
@@ -26,17 +27,18 @@ export type NodeProperties = {
     parameterCount?: number;
     returnType?: string;
 };
-export type RelationshipType = 'CONTAINS' | 'CALLS' | 'INHERITS' | 'OVERRIDES' | 'IMPORTS' | 'USES' | 'DEFINES' | 'DECORATES' | 'IMPLEMENTS' | 'EXTENDS' | 'HAS_METHOD' | 'MEMBER_OF' | 'STEP_IN_PROCESS' | 'DEPENDS_ON' | 'PROVIDES';
+/** @deprecated Use EdgeType directly — this alias exists only for migration convenience */
+export type RelationshipType = EdgeType;
 export interface GraphNode {
-    id: string;
+    id: NodeId;
     label: NodeLabel;
     properties: NodeProperties;
 }
 export interface GraphRelationship {
-    id: string;
-    sourceId: string;
-    targetId: string;
-    type: RelationshipType;
+    id: EdgeId;
+    sourceId: NodeId;
+    targetId: NodeId;
+    type: EdgeType;
     /** Confidence score 0-1 (1.0 = certain, lower = uncertain) */
     confidence: number;
     /** Resolution reason: 'import-resolved', 'same-file', 'fuzzy-global', or empty for non-CALLS */
@@ -59,11 +61,11 @@ export interface KnowledgeGraph {
     forEachNode: (fn: (node: GraphNode) => void) => void;
     forEachRelationship: (fn: (rel: GraphRelationship) => void) => void;
     /** Lookup a single node by id — O(1) */
-    getNode: (id: string) => GraphNode | undefined;
+    getNode: (id: NodeId) => GraphNode | undefined;
     nodeCount: number;
     relationshipCount: number;
     addNode: (node: GraphNode) => void;
     addRelationship: (relationship: GraphRelationship) => void;
-    removeNode: (nodeId: string) => boolean;
+    removeNode: (nodeId: NodeId) => boolean;
     removeNodesByFile: (filePath: string) => number;
 }

package/dist/core/graph/types.js

@@ -1,3 +1,6 @@
 // code-mapper/src/core/graph/types.ts
 /** @file types.ts @description Core type definitions for the knowledge graph: nodes, relationships, and the graph interface */
-export {};
+import {} from '../db/schema.js';
+import { SupportedLanguages } from '../../config/supported-languages.js';
+// Re-export canonical types so existing consumers can keep importing from here
+export {} from '../db/schema.js';

package/dist/core/incremental/refresh.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @file Standalone incremental refresh — parses dirty files with tree-sitter
+ * and writes directly to the SQLite database via the adapter.
+ *
+ * Extracted from LocalBackend.inProcessRefresh so both the MCP server
+ * and the CLI can call it without duplicating logic.
+ *
+ * Phases:
+ *   1. Delete old nodes for dirty files
+ *   2. Parse modified/created files with tree-sitter
+ *   3. Insert File nodes + symbol nodes + DEFINES edges
+ *   4. Resolve call edges using tsgo LSP (TS/JS files only)
+ *   5. Repair cross-file edges (callers from unchanged files → changed symbols)
+ */
+import type Database from 'better-sqlite3';
+import { type DirtyFileEntry, type RefreshResult } from './types.js';
+/**
+ * Parse dirty files with tree-sitter and write nodes/edges to the database.
+ *
+ * Phase 1: Delete old nodes for all dirty files
+ * Phase 2: Parse modified/created files with tree-sitter
+ * Phase 3: Insert File nodes + symbol nodes + DEFINES edges
+ * Phase 4: Resolve call edges using tsgo LSP (TS/JS only, optional)
+ * Phase 5: Repair cross-file edges from unchanged files (tsgo, optional)
+ *
+ * @param db - Open better-sqlite3 database instance
+ * @param repoPath - Absolute path to the repository root
+ * @param dirtyFiles - Files that changed (modified, created, or deleted)
+ * @returns Statistics about what was processed
+ */
+export declare function refreshFiles(db: Database.Database, repoPath: string, dirtyFiles: readonly DirtyFileEntry[]): Promise<RefreshResult>;
+/**
+ * Update embeddings for dirty files so semantic search stays in sync.
+ *
+ * Runs ONLY when the repo previously had embeddings (hasEmbeddings = true).
+ * Steps:
+ *   1. Delete stale embeddings for all dirty file paths
+ *   2. Query new embeddable nodes for modified/created files
+ *   3. Enrich with graph context (callers, callees, module) — same as full analyze
+ *   4. Generate text, batch embed, insert via SQLite adapter
+ *
+ * @param db - Open better-sqlite3 database instance
+ * @param dirtyFiles - Files that changed (modified, created, or deleted)
+ * @param hasEmbeddings - Whether the repo previously had embeddings (skip if false)
+ */
+export declare function refreshEmbeddings(db: Database.Database, dirtyFiles: readonly DirtyFileEntry[], hasEmbeddings?: boolean): Promise<void>;

package/dist/core/incremental/refresh.js

@@ -0,0 +1,503 @@
+// code-mapper/src/core/incremental/refresh.ts
+/**
+ * @file Standalone incremental refresh — parses dirty files with tree-sitter
+ * and writes directly to the SQLite database via the adapter.
+ *
+ * Extracted from LocalBackend.inProcessRefresh so both the MCP server
+ * and the CLI can call it without duplicating logic.
+ *
+ * Phases:
+ *   1. Delete old nodes for dirty files
+ *   2. Parse modified/created files with tree-sitter
+ *   3. Insert File nodes + symbol nodes + DEFINES edges
+ *   4. Resolve call edges using tsgo LSP (TS/JS files only)
+ *   5. Repair cross-file edges (callers from unchanged files → changed symbols)
+ */
+import path from 'path';
+import fsSync from 'fs';
+import Parser from 'tree-sitter';
+import { LANGUAGE_QUERIES } from '../ingestion/tree-sitter-queries.js';
+import { getLanguageFromFilename, getDefinitionNodeFromCaptures } from '../ingestion/utils.js';
+import { loadParser, loadLanguage, isLanguageAvailable } from '../tree-sitter/parser-loader.js';
+import { getTreeSitterBufferSize, TREE_SITTER_MAX_BUFFER } from '../ingestion/constants.js';
+import { generateId } from '../../lib/utils.js';
+import { deleteNodesByFile, insertNode, insertEdge, findNodeAtLine, findNodesByFile, deleteEmbeddingsByFile, insertEmbeddingsBatch, countEmbeddings } from '../db/adapter.js';
+import { assertNodeLabel, toNodeId, toEdgeId } from '../db/schema.js';
+import {} from './types.js';
+import { getTsgoService } from '../semantic/tsgo-service.js';
+import { EMBEDDABLE_LABELS } from '../embeddings/types.js';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** File extensions that tsgo can resolve */
+const TS_JS_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mts', '.cts', '.mjs', '.cjs']);
+function isTypeScriptOrJavaScript(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    return TS_JS_EXTENSIONS.has(ext);
+}
+/**
+ * Find the innermost symbol node enclosing a given 0-based line in a file.
+ * Excludes structural nodes (File, Folder, Community, Process).
+ */
+function findEnclosingNode(db, filePath, line) {
+    return findNodeAtLine(db, filePath, line, 'File');
+}
+/**
+ * Find a node whose definition starts at a given 0-based line in a file.
+ * Falls back to the enclosing node if no exact match.
+ */
+function findNodeByFileAndLine(db, filePath, line) {
+    // Try exact startLine match first (exclude structural labels)
+    const exact = db.prepare(`SELECT * FROM nodes
+     WHERE filePath = ? AND startLine = ?
+       AND label NOT IN ('File', 'Folder', 'Community', 'Process')
+     LIMIT 1`
+    // Safe: schema and NodeRow defined together in schema.ts
+    ).get(filePath, line);
+    if (exact)
+        return exact;
+    // Fall back to enclosing node
+    return findEnclosingNode(db, filePath, line);
+}
+/**
+ * Parse dirty files with tree-sitter and write nodes/edges to the database.
+ *
+ * Phase 1: Delete old nodes for all dirty files
+ * Phase 2: Parse modified/created files with tree-sitter
+ * Phase 3: Insert File nodes + symbol nodes + DEFINES edges
+ * Phase 4: Resolve call edges using tsgo LSP (TS/JS only, optional)
+ * Phase 5: Repair cross-file edges from unchanged files (tsgo, optional)
+ *
+ * @param db - Open better-sqlite3 database instance
+ * @param repoPath - Absolute path to the repository root
+ * @param dirtyFiles - Files that changed (modified, created, or deleted)
+ * @returns Statistics about what was processed
+ */
+export async function refreshFiles(db, repoPath, dirtyFiles) {
+    const t0 = Date.now();
+    let nodesDeleted = 0;
+    let nodesInserted = 0;
+    let edgesInserted = 0;
+    let filesSkipped = 0;
+    // Phase 1: Delete old nodes for all dirty files
+    for (const entry of dirtyFiles) {
+        const deleted = deleteNodesByFile(db, entry.relativePath);
+        nodesDeleted += deleted;
+    }
+    // Phase 2: Parse modified/created files with tree-sitter
+    const parser = await loadParser();
+    const filesToProcess = dirtyFiles.filter(f => f.changeKind === 'modified' || f.changeKind === 'created');
+    const allDefinitions = [];
+    const callSites = [];
+    const insertedFilePaths = new Set();
+    for (const entry of filesToProcess) {
+        const relPath = entry.relativePath;
+        const absPath = path.resolve(repoPath, relPath);
+        const language = getLanguageFromFilename(relPath);
+        if (!language || !isLanguageAvailable(language)) {
+            filesSkipped++;
+            continue;
+        }
+        let content;
+        try {
+            content = fsSync.readFileSync(absPath, 'utf-8');
+        }
+        catch {
+            filesSkipped++;
+            continue;
+        }
+        if (content.length > TREE_SITTER_MAX_BUFFER) {
+            filesSkipped++;
+            continue;
+        }
+        try {
+            await loadLanguage(language, relPath);
+        }
+        catch {
+            filesSkipped++;
+            continue;
+        }
+        let tree;
+        try {
+            tree = parser.parse(content, undefined, { bufferSize: getTreeSitterBufferSize(content.length) });
+        }
+        catch {
+            filesSkipped++;
+            continue;
+        }
+        const queryString = LANGUAGE_QUERIES[language];
+        if (!queryString) {
+            filesSkipped++;
+            continue;
+        }
+        let matches;
+        try {
+            const tsLang = parser.getLanguage();
+            const query = new Parser.Query(tsLang, queryString);
+            matches = query.matches(tree.rootNode);
+        }
+        catch {
+            filesSkipped++;
+            continue;
+        }
+        insertedFilePaths.add(relPath);
+        for (const match of matches) {
+            const captureMap = {};
+            for (const c of match.captures)
+                captureMap[c.name] = c.node;
+            if (captureMap['import'] || captureMap['import.source'])
+                continue;
+            if (captureMap['heritage'] || captureMap['heritage.impl'])
+                continue;
+            if (captureMap['call'] || captureMap['call.name']) {
+                const callNameNode = captureMap['call.name'];
+                if (callNameNode) {
+                    callSites.push({
+                        filePath: relPath, absPath,
+                        name: callNameNode.text,
+                        line: callNameNode.startPosition.row,
+                        character: callNameNode.startPosition.column,
+                    });
+                }
+                continue;
+            }
+            const nameNode = captureMap['name'];
+            if (!nameNode && !captureMap['definition.constructor'])
+                continue;
+            const nodeName = nameNode ? nameNode.text : 'init';
+            let nodeLabel = 'CodeElement';
+            if (captureMap['definition.function'])
+                nodeLabel = 'Function';
+            else if (captureMap['definition.class'])
+                nodeLabel = 'Class';
+            else if (captureMap['definition.interface'])
+                nodeLabel = 'Interface';
+            else if (captureMap['definition.method'])
+                nodeLabel = 'Method';
+            else if (captureMap['definition.struct'])
+                nodeLabel = 'Struct';
+            else if (captureMap['definition.enum'])
+                nodeLabel = 'Enum';
+            else if (captureMap['definition.namespace'])
+                nodeLabel = 'Namespace';
+            else if (captureMap['definition.module'])
+                nodeLabel = 'Module';
+            else if (captureMap['definition.trait'])
+                nodeLabel = 'Trait';
+            else if (captureMap['definition.impl'])
+                nodeLabel = 'Impl';
+            else if (captureMap['definition.type'])
+                nodeLabel = 'TypeAlias';
+            else if (captureMap['definition.const'])
+                nodeLabel = 'Const';
+            else if (captureMap['definition.static'])
+                nodeLabel = 'Static';
+            else if (captureMap['definition.typedef'])
+                nodeLabel = 'Typedef';
+            else if (captureMap['definition.macro'])
+                nodeLabel = 'Macro';
+            else if (captureMap['definition.union'])
+                nodeLabel = 'Union';
+            else if (captureMap['definition.property'])
+                nodeLabel = 'Property';
+            else if (captureMap['definition.record'])
+                nodeLabel = 'Record';
+            else if (captureMap['definition.delegate'])
+                nodeLabel = 'Delegate';
+            else if (captureMap['definition.annotation'])
+                nodeLabel = 'Annotation';
+            else if (captureMap['definition.constructor'])
+                nodeLabel = 'Constructor';
+            else if (captureMap['definition.template'])
+                nodeLabel = 'Template';
+            const defNode = getDefinitionNodeFromCaptures(captureMap);
+            const startLine = defNode ? defNode.startPosition.row : (nameNode ? nameNode.startPosition.row : 0);
+            const endLine = defNode ? defNode.endPosition.row : startLine;
+            const nodeContent = defNode ? (defNode.text || '').slice(0, 50_000) : '';
+            allDefinitions.push({
+                nodeId: generateId(nodeLabel, `${relPath}:${nodeName}`),
+                name: nodeName, label: nodeLabel, filePath: relPath,
+                startLine, endLine, content: nodeContent,
+            });
+        }
+    }
+    // Phase 3: Insert File nodes + symbol nodes + DEFINES edges
+    for (const filePath of insertedFilePaths) {
+        const fileId = generateId('File', filePath);
+        insertNode(db, {
+            id: toNodeId(fileId), label: 'File',
+            name: path.basename(filePath), filePath, content: '',
+        });
+        nodesInserted++;
+    }
+    for (const def of allDefinitions) {
+        assertNodeLabel(def.label);
+        insertNode(db, {
+            id: toNodeId(def.nodeId), label: def.label,
+            name: def.name, filePath: def.filePath,
+            startLine: def.startLine, endLine: def.endLine,
+            content: def.content, description: '',
+        });
+        nodesInserted++;
+        const fileId = generateId('File', def.filePath);
+        insertEdge(db, {
+            id: toEdgeId(`${fileId}_DEFINES_${def.nodeId}`),
+            sourceId: toNodeId(fileId), targetId: toNodeId(def.nodeId),
+            type: 'DEFINES', confidence: 1.0, reason: '',
+        });
+        edgesInserted++;
+    }
+    // Phase 4 + 5: Resolve call edges and cross-file edges using tsgo LSP
+    // (TS/JS files only — tsgo is optional, skip if unavailable)
+    console.error(`Code Mapper: refresh tsgo init with repoPath=${repoPath}`);
+    const tsgoService = getTsgoService(repoPath);
+    let tsgoReady = false;
+    try {
+        tsgoReady = await tsgoService.start();
+        console.error(`Code Mapper: refresh tsgo ready=${tsgoReady}`);
+    }
+    catch (err) {
+        console.error(`Code Mapper: refresh tsgo failed: ${err instanceof Error ? err.message : err}`);
+    }
+    // Phase 4: Resolve call edges from dirty files
+    // Always runs — tsgo provides 0.99 confidence, heuristic fallback provides 0.5-0.95
+    if (callSites.length > 0) {
+        db.exec('BEGIN');
+        try {
+            const { findNodesByName } = await import('../db/adapter.js');
+            // Notify tsgo about changed files if available
+            if (tsgoReady) {
+                for (const entry of filesToProcess) {
+                    const absPath = path.resolve(repoPath, entry.relativePath);
+                    if (isTypeScriptOrJavaScript(entry.relativePath)) {
+                        await tsgoService.notifyFileChanged(absPath);
+                    }
+                }
+            }
+            console.error(`Code Mapper: refresh Phase 4 — ${callSites.length} call sites to resolve`);
+            for (const callSite of callSites) {
+                const sourceNode = findEnclosingNode(db, callSite.filePath, callSite.line);
+                if (!sourceNode)
+                    continue;
+                let targetNode;
+                let confidence = 0.5;
+                let reason = 'global';
+                // Try tsgo first for TS/JS files
+                if (tsgoReady && isTypeScriptOrJavaScript(callSite.filePath)) {
+                    try {
+                        const def = await tsgoService.resolveDefinition(callSite.absPath, callSite.line, callSite.character);
+                        if (def) {
+                            targetNode = findNodeByFileAndLine(db, def.filePath, def.line);
+                            if (targetNode) {
+                                confidence = 0.99;
+                                reason = 'tsgo-lsp';
+                            }
+                        }
+                    }
+                    catch { }
+                }
+                // Heuristic fallback: name-based lookup in DB
+                if (!targetNode) {
+                    const candidates = findNodesByName(db, callSite.name, undefined, 5);
+                    const sameFile = candidates.find(c => c.filePath === callSite.filePath);
+                    if (sameFile) {
+                        targetNode = sameFile;
+                        confidence = 0.95;
+                        reason = 'same-file';
+                    }
+                    else if (candidates.length === 1) {
+                        targetNode = candidates[0];
+                        confidence = 0.9;
+                        reason = 'import-resolved';
+                    }
+                    else if (candidates.length > 0) {
+                        targetNode = candidates[0];
+                        confidence = 0.5;
+                        reason = 'global';
+                    }
+                }
+                if (!targetNode)
+                    continue;
+                if (sourceNode.id === targetNode.id)
+                    continue;
+                const edgeId = toEdgeId(`${sourceNode.id}_CALLS_${targetNode.id}`);
+                insertEdge(db, {
+                    id: edgeId,
+                    sourceId: sourceNode.id,
+                    targetId: targetNode.id,
+                    type: 'CALLS',
+                    confidence,
+                    reason,
+                    callLine: callSite.line,
+                });
+                edgesInserted++;
+            }
+            db.exec('COMMIT');
+        }
+        catch (err) {
+            db.exec('ROLLBACK');
+            console.error(`Code Mapper: Phase 4 call resolution failed: ${err instanceof Error ? err.message : err}`);
+        }
+    }
+    // Phase 5: Repair cross-file edges (tsgo only — needs findReferences)
+    if (tsgoReady) {
+        const dirtyFilePaths = new Set(dirtyFiles.map(f => f.relativePath));
+        db.exec('BEGIN');
+        try {
+            // Phase 5: Repair cross-file edges
+            // For each newly inserted definition, find references from UNCHANGED files
+            // and create CALLS edges so the graph stays consistent.
+            for (const def of allDefinitions) {
+                if (!isTypeScriptOrJavaScript(def.filePath))
+                    continue;
+                const absPath = path.resolve(repoPath, def.filePath);
+                const refs = await tsgoService.findReferences(absPath, def.startLine, 0);
+                for (const ref of refs) {
+                    // Skip refs from dirty files — already handled in Phase 4
+                    if (dirtyFilePaths.has(ref.filePath))
+                        continue;
+                    // Skip refs from non-TS/JS files
+                    if (!isTypeScriptOrJavaScript(ref.filePath))
+                        continue;
+                    // This reference is from an UNCHANGED file → create/update the CALLS edge
+                    const sourceNode = findEnclosingNode(db, ref.filePath, ref.line);
+                    if (!sourceNode)
+                        continue;
+                    const targetId = toNodeId(def.nodeId);
+                    // Skip self-edges
+                    if (sourceNode.id === targetId)
+                        continue;
+                    const edgeId = toEdgeId(`${sourceNode.id}_CALLS_${targetId}`);
+                    insertEdge(db, {
+                        id: edgeId,
+                        sourceId: sourceNode.id,
+                        targetId,
+                        type: 'CALLS',
+                        confidence: 0.99,
+                        reason: 'tsgo-cross-file',
+                        callLine: ref.line,
+                    });
+                    edgesInserted++;
+                }
+            }
+            db.exec('COMMIT');
+        }
+        catch (err) {
+            db.exec('ROLLBACK');
+            // Log but don't fail the entire refresh — Phases 1-3 already committed
+            console.error(`Code Mapper: tsgo call resolution failed: ${err instanceof Error ? err.message : err}`);
+        }
+    }
+    // FTS5 auto-updates via triggers — no manual rebuild needed
+    return {
+        filesProcessed: filesToProcess.length, filesSkipped,
+        nodesDeleted, nodesInserted, edgesInserted,
+        durationMs: Date.now() - t0,
+        tsgoEnabled: tsgoReady,
+    };
+}
+// ---------------------------------------------------------------------------
+// Incremental embedding refresh
+// ---------------------------------------------------------------------------
+/**
+ * Update embeddings for dirty files so semantic search stays in sync.
+ *
+ * Runs ONLY when the repo previously had embeddings (hasEmbeddings = true).
+ * Steps:
+ *   1. Delete stale embeddings for all dirty file paths
+ *   2. Query new embeddable nodes for modified/created files
+ *   3. Enrich with graph context (callers, callees, module) — same as full analyze
+ *   4. Generate text, batch embed, insert via SQLite adapter
+ *
+ * @param db - Open better-sqlite3 database instance
+ * @param dirtyFiles - Files that changed (modified, created, or deleted)
+ * @param hasEmbeddings - Whether the repo previously had embeddings (skip if false)
+ */
+export async function refreshEmbeddings(db, dirtyFiles, hasEmbeddings) {
+    // If hasEmbeddings is not explicitly provided, check the DB
+    const embeddingsExist = hasEmbeddings ?? countEmbeddings(db) > 0;
+    if (!embeddingsExist) {
+        console.error('Code Mapper: Skipping embeddings (none in index — run analyze --embeddings to enable)');
+        return;
+    }
+    if (dirtyFiles.length === 0)
+        return;
+    try {
+        // Step 1: Delete stale embeddings for all dirty file paths
+        for (const entry of dirtyFiles) {
+            deleteEmbeddingsByFile(db, entry.relativePath);
+        }
+        // Step 2: Query new embeddable nodes for modified/created files
+        const embeddableSet = new Set(EMBEDDABLE_LABELS);
+        const modifiedPaths = dirtyFiles
+            .filter(f => f.changeKind === 'modified' || f.changeKind === 'created')
+            .map(f => f.relativePath);
+        if (modifiedPaths.length === 0)
+            return;
+        const newNodes = [];
+        for (const relPath of modifiedPaths) {
+            const nodes = findNodesByFile(db, relPath);
+            for (const node of nodes) {
+                if (embeddableSet.has(node.label)) {
+                    newNodes.push({
+                        id: node.id,
+                        name: node.name,
+                        label: node.label,
+                        filePath: node.filePath,
+                        content: node.content,
+                        ...(node.startLine != null ? { startLine: node.startLine } : {}),
+                        ...(node.endLine != null ? { endLine: node.endLine } : {}),
+                    });
+                }
+            }
+        }
+        if (newNodes.length === 0)
+            return;
+        // Step 3: Enrich with graph context — same as the full analyze pipeline
+        // Lazy import to avoid circular dependency at module load time
+        const { fetchGraphContext, enrichTextWithGraphContext } = await import('../embeddings/embedding-pipeline.js');
+        const { generateEmbeddingText } = await import('../embeddings/text-generator.js');
+        const { initEmbedder, embedBatch, embeddingToArray } = await import('../embeddings/embedder.js');
+        const graphContext = fetchGraphContext(db, newNodes);
+        // Step 4: Generate enriched text + hash for skip detection
+        const { createHash } = await import('crypto');
+        const { getEmbeddingHashes } = await import('../db/adapter.js');
+        const existingHashes = getEmbeddingHashes(db);
+        const toEmbed = [];
+        for (const node of newNodes) {
+            let text = generateEmbeddingText(node);
+            const ctx = graphContext.get(node.id);
+            if (ctx) {
+                text = enrichTextWithGraphContext(text, ctx);
+            }
+            const hash = createHash('md5').update(text).digest('hex');
+            // Skip if hash unchanged (content + graph context identical)
+            if (existingHashes.get(node.id) === hash)
+                continue;
+            toEmbed.push({ node, text, hash });
+        }
+        if (toEmbed.length === 0) {
+            console.error(`Code Mapper: All ${newNodes.length} node(s) unchanged (hash skip)`);
+            return;
+        }
+        console.error(`Code Mapper: Embedding ${toEmbed.length}/${newNodes.length} node(s) (${newNodes.length - toEmbed.length} unchanged)`);
+        // Step 5: Ensure embedder is ready
+        await initEmbedder();
+        // Step 6: Batch embed only changed nodes
+        const embeddings = await embedBatch(toEmbed.map(e => e.text));
+        // Step 7: Insert with hashes
+        const items = [];
+        for (let i = 0; i < toEmbed.length; i++) {
+            const entry = toEmbed[i];
+            const emb = embeddings[i];
+            if (entry?.node && emb) {
+                items.push({ nodeId: toNodeId(entry.node.id), embedding: embeddingToArray(emb), textHash: entry.hash });
+            }
+        }
+        insertEmbeddingsBatch(db, items);
+        console.error(`Code Mapper: Embedded ${items.length} node(s) incrementally`);
+    }
+    catch (err) {
+        console.error(`Code Mapper: Incremental embedding failed: ${err instanceof Error ? err.message : err}`);
+    }
+}

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

@@ -13,7 +13,7 @@ type Brand<T, B extends string> = T & {
 export type AbsoluteFilePath = Brand<string, 'AbsoluteFilePath'>;
 /** Path relative to repo root (forward-slash normalized, matches graph filePath) */
 export type RelativeFilePath = Brand<string, 'RelativeFilePath'>;
-/** Absolute path to the LadybugDB database directory */
+/** Absolute path to the SQLite database file */
 export type DbPath = Brand<string, 'DbPath'>;
 /** Absolute path to the repository root */
 export type RepoRoot = Brand<string, 'RepoRoot'>;
@@ -55,6 +55,7 @@ export interface RefreshResult {
     readonly nodesInserted: number;
     readonly edgesInserted: number;
     readonly durationMs: number;
+    readonly tsgoEnabled: boolean;
 }
 /** Messages from child to parent */
 export type ChildToParentMessage = {