gitnexus 1.6.1 → 1.6.2-rc.10

package/dist/core/lbug/lbug-adapter.js

@@ -1,15 +1,123 @@
 import fs from 'fs/promises';
 import { createReadStream, createWriteStream } from 'fs';
 import { createInterface } from 'readline';
+import { once } from 'events';
+import { finished } from 'stream/promises';
 import path from 'path';
 import lbug from '@ladybugdb/core';
-import { NODE_TABLES, REL_TABLE_NAME, SCHEMA_QUERIES, EMBEDDING_TABLE_NAME, } from './schema.js';
+import { NODE_TABLES, REL_TABLE_NAME, SCHEMA_QUERIES, EMBEDDING_TABLE_NAME, STALE_HASH_SENTINEL, } from './schema.js';
 import { streamAllCSVsToDisk } from './csv-generator.js';
+/**
+ * Split a relationship CSV into per-label-pair files on disk.
+ *
+ * Streams the CSV line-by-line, routing each relationship to a file named
+ * `rel_{fromLabel}_{toLabel}.csv`. Handles backpressure correctly: only one
+ * drain listener per stream at a time, and readline resumes only when ALL
+ * backpressured streams have drained.
+ *
+ * @param csvPath       Path to the combined relationship CSV
+ * @param csvDir        Directory to write per-pair CSV files
+ * @param validTables   Set of valid node table names
+ * @param getNodeLabel  Function to extract the label from a node ID
+ * @param wsFactory     Optional WriteStream factory (defaults to fs.createWriteStream)
+ */
+export const splitRelCsvByLabelPair = async (csvPath, csvDir, validTables, getNodeLabel, wsFactory = (p) => createWriteStream(p, 'utf-8')) => {
+    let relHeader = '';
+    const relsByPairMeta = new Map();
+    const pairWriteStreams = new Map();
+    let skippedRels = 0;
+    let totalValidRels = 0;
+    const inputStream = createReadStream(csvPath, 'utf-8');
+    const rl = createInterface({ input: inputStream, crlfDelay: Infinity });
+    // If any pair WriteStream errors (disk full, EMFILE, etc.) or the input
+    // stream fails, we need to abort the pending `once(ws, 'drain')` await.
+    // An AbortController gives us one signal to cancel all pending waits
+    // without a custom state machine.
+    const abortOnError = new AbortController();
+    let streamError = null;
+    const markStreamError = (err) => {
+        streamError ??= err;
+        abortOnError.abort(err);
+    };
+    try {
+        // `for await (const line of rl)` replaces the old manual
+        // on('line')/pause()/resume()/waitingForDrain state machine: readline's
+        // async iterator naturally serializes line delivery with our awaits, so
+        // at most one ws can be in backpressure at a time and we just await its
+        // 'drain' event.
+        let isFirst = true;
+        for await (const line of rl) {
+            if (streamError)
+                throw streamError;
+            if (isFirst) {
+                relHeader = line;
+                isFirst = false;
+                continue;
+            }
+            if (!line.trim())
+                continue;
+            const match = line.match(/"([^"]*)","([^"]*)"/);
+            if (!match) {
+                skippedRels++;
+                continue;
+            }
+            const fromLabel = getNodeLabel(match[1]);
+            const toLabel = getNodeLabel(match[2]);
+            if (!validTables.has(fromLabel) || !validTables.has(toLabel)) {
+                skippedRels++;
+                continue;
+            }
+            const pairKey = `${fromLabel}|${toLabel}`;
+            let ws = pairWriteStreams.get(pairKey);
+            if (!ws) {
+                const pairCsvPath = path.join(csvDir, `rel_${fromLabel}_${toLabel}.csv`);
+                ws = wsFactory(pairCsvPath);
+                ws.on('error', markStreamError);
+                pairWriteStreams.set(pairKey, ws);
+                relsByPairMeta.set(pairKey, { csvPath: pairCsvPath, rows: 0 });
+                if (!ws.write(relHeader + '\n')) {
+                    await once(ws, 'drain', { signal: abortOnError.signal });
+                }
+            }
+            if (!ws.write(line + '\n')) {
+                await once(ws, 'drain', { signal: abortOnError.signal });
+            }
+            relsByPairMeta.get(pairKey).rows++;
+            totalValidRels++;
+        }
+        if (streamError)
+            throw streamError;
+    }
+    catch (err) {
+        // Tear down everything so no fd is left dangling. If the abort was caused
+        // by a stream error, rethrow that error (more actionable than AbortError).
+        for (const ws of pairWriteStreams.values())
+            ws.destroy();
+        inputStream.destroy();
+        throw streamError ?? err;
+    }
+    finally {
+        // Readline 'close' fires before the underlying fs.ReadStream releases its
+        // fd — on Windows that race caused ENOTEMPTY on the parent dir.
+        // stream/promises.finished is the stdlib "wait until this stream is fully
+        // closed" primitive and handles both success and error paths.
+        await finished(inputStream).catch(() => { });
+    }
+    return { relHeader, relsByPairMeta, pairWriteStreams, skippedRels, totalValidRels };
+};
 let db = null;
 let conn = null;
 let currentDbPath = null;
 let ftsLoaded = false;
 let vectorExtensionLoaded = false;
+/**
+ * Check if an error indicates a missing column or table (schema-level problem)
+ * rather than a transient/connection error. Used for legacy DB fallback logic.
+ */
+const isMissingColumnOrTableError = (msg) => msg.includes('does not exist') ||
+    // Kuzu-specific: "(table|column|property) ... not found" — narrow enough to avoid
+    // matching transient errors like "connection not found" or "key not found".
+    /(table|column|property).*not found/i.test(msg);
 /** Expose the current Database for pool adapter reuse in tests. */
 export const getDatabase = () => db;
 // Global session lock for operations that touch module-level lbug globals.
@@ -215,69 +323,14 @@ export const loadGraphToLbug = async (graph, repoPath, storagePath, onProgress)
         }
     }
     // Bulk COPY relationships — split by FROM→TO label pair (LadybugDB requires it)
-    // Stream-read the relation CSV line by line and write directly to per-pair
-    // temp files on disk. This avoids accumulating potentially millions of CSV
-    // lines in memory which could exceed V8 Map or array limits on large repos.
-    let relHeader = '';
-    const relsByPairMeta = new Map();
-    const pairWriteStreams = new Map();
-    let skippedRels = 0;
-    let totalValidRels = 0;
-    await new Promise((resolve, reject) => {
-        const rl = createInterface({
-            input: createReadStream(csvResult.relCsvPath, 'utf-8'),
-            crlfDelay: Infinity,
-        });
-        let isFirst = true;
-        rl.on('line', (line) => {
-            if (isFirst) {
-                relHeader = line;
-                isFirst = false;
-                return;
-            }
-            if (!line.trim())
-                return;
-            const match = line.match(/"([^"]*)","([^"]*)"/);
-            if (!match) {
-                skippedRels++;
-                return;
-            }
-            const fromLabel = getNodeLabel(match[1]);
-            const toLabel = getNodeLabel(match[2]);
-            if (!validTables.has(fromLabel) || !validTables.has(toLabel)) {
-                skippedRels++;
-                return;
-            }
-            const pairKey = `${fromLabel}|${toLabel}`;
-            let ws = pairWriteStreams.get(pairKey);
-            if (!ws) {
-                const pairCsvPath = path.join(csvDir, `rel_${fromLabel}_${toLabel}.csv`);
-                ws = createWriteStream(pairCsvPath, 'utf-8');
-                ws.write(relHeader + '\n');
-                pairWriteStreams.set(pairKey, ws);
-                relsByPairMeta.set(pairKey, { csvPath: pairCsvPath, rows: 0 });
-            }
-            const ok = ws.write(line + '\n');
-            relsByPairMeta.get(pairKey).rows++;
-            totalValidRels++;
-            // Handle backpressure: pause reading when the write buffer is full,
-            // resume when the stream drains. Prevents unbounded memory growth
-            // on repos with millions of relationships.
-            if (!ok) {
-                rl.pause();
-                ws.once('drain', () => rl.resume());
-            }
-        });
-        rl.on('close', resolve);
-        rl.on('error', (err) => {
-            // Destroy all open write streams to avoid resource leaks
-            for (const ws of pairWriteStreams.values())
-                ws.destroy();
-            reject(err);
-        });
-    });
-    // Close all per-pair write streams before COPY
-    await Promise.all(Array.from(pairWriteStreams.values()).map((ws) => new Promise((resolve, reject) => ws.end((err) => (err ? reject(err) : resolve())))));
+    const { relHeader, relsByPairMeta, pairWriteStreams, skippedRels, totalValidRels } = await splitRelCsvByLabelPair(csvResult.relCsvPath, csvDir, validTables, getNodeLabel);
+    // Close all per-pair write streams before COPY. `stream/promises.finished`
+    // resolves on the stream's 'finish' event and rejects on 'error' — replaces
+    // a hand-rolled promisification with the stdlib primitive.
+    await Promise.all(Array.from(pairWriteStreams.values()).map(async (ws) => {
+        ws.end();
+        await finished(ws);
+    }));
     const insertedRels = totalValidRels;
     const warnings = [];
     if (insertedRels > 0) {
@@ -746,7 +799,24 @@ export const loadCachedEmbeddings = async () => {
     const embeddingNodeIds = new Set();
     const embeddings = [];
     try {
-        const rows = await conn.query(`MATCH (e:${EMBEDDING_TABLE_NAME}) RETURN e.nodeId AS nodeId, e.embedding AS embedding`);
+        // Try to read contentHash alongside the embedding
+        let rows;
+        let hasContentHash = true;
+        try {
+            rows = await conn.query(`MATCH (e:${EMBEDDING_TABLE_NAME}) RETURN e.nodeId AS nodeId, e.embedding AS embedding, e.contentHash AS contentHash`);
+        }
+        catch (err) {
+            // Only fall back for missing-column errors (legacy DBs without contentHash).
+            // Rethrow transient / connection errors so callers see them.
+            const msg = err?.message ?? '';
+            if (isMissingColumnOrTableError(msg)) {
+                hasContentHash = false;
+                rows = await conn.query(`MATCH (e:${EMBEDDING_TABLE_NAME}) RETURN e.nodeId AS nodeId, e.embedding AS embedding`);
+            }
+            else {
+                throw err;
+            }
+        }
         const result = Array.isArray(rows) ? rows[0] : rows;
         for (const row of await result.getAll()) {
             const nodeId = String(row.nodeId ?? row[0] ?? '');
@@ -760,6 +830,7 @@ export const loadCachedEmbeddings = async () => {
                     embedding: Array.isArray(embedding)
                         ? embedding.map(Number)
                         : Array.from(embedding).map(Number),
+                    contentHash: hasContentHash ? (row.contentHash ?? row[2] ?? undefined) : undefined,
                 });
             }
         }
@@ -769,6 +840,59 @@ export const loadCachedEmbeddings = async () => {
     }
     return { embeddingNodeIds, embeddings };
 };
+/**
+ * Fetch existing embedding hashes from CodeEmbedding table for incremental embedding.
+ * Returns a Map<nodeId, contentHash> suitable for passing to `runEmbeddingPipeline`.
+ * Handles legacy DBs without the `contentHash` column (all rows treated as stale with empty hash).
+ * Returns undefined if the CodeEmbedding table does not exist.
+ *
+ * @param execQuery - Cypher query executor (typically pool-adapter's `executeQuery`)
+ */
+export const fetchExistingEmbeddingHashes = async (execQuery) => {
+    try {
+        const rows = await execQuery(`MATCH (e:${EMBEDDING_TABLE_NAME}) RETURN e.nodeId AS nodeId, e.contentHash AS contentHash`);
+        if (!rows || rows.length === 0)
+            return undefined;
+        const map = new Map();
+        for (const r of rows) {
+            const nodeId = r.nodeId ?? r[0];
+            const hash = r.contentHash ?? r[1] ?? STALE_HASH_SENTINEL;
+            if (nodeId) {
+                // Empty/null contentHash means legacy row — treat as stale so it gets re-embedded
+                map.set(nodeId, hash || STALE_HASH_SENTINEL);
+            }
+        }
+        return map;
+    }
+    catch (err) {
+        const msg = err?.message ?? '';
+        if (isMissingColumnOrTableError(msg)) {
+            // Column or table missing — try fallback without contentHash
+            try {
+                const rows = await execQuery(`MATCH (e:${EMBEDDING_TABLE_NAME}) RETURN e.nodeId AS nodeId`);
+                if (!rows || rows.length === 0)
+                    return undefined;
+                const map = new Map();
+                for (const r of rows) {
+                    const nodeId = r.nodeId ?? r[0];
+                    if (nodeId)
+                        map.set(nodeId, STALE_HASH_SENTINEL); // no contentHash — treat as stale
+                }
+                console.log(`[embed] ${map.size} nodes in legacy DB (no contentHash) — all treated as stale`);
+                return map;
+            }
+            catch (fallbackErr) {
+                const fallbackMsg = fallbackErr?.message ?? '';
+                if (isMissingColumnOrTableError(fallbackMsg)) {
+                    console.log(`[embed] CodeEmbedding table not yet present — full embedding run (${fallbackMsg})`);
+                    return undefined;
+                }
+                throw fallbackErr;
+            }
+        }
+        throw err;
+    }
+};
 export const closeLbug = async () => {
     if (conn) {
         try {

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

@@ -43,6 +43,13 @@ export declare const TOOL_SCHEMA = "\nCREATE NODE TABLE Tool (\n  id STRING,\n
 export declare const SECTION_SCHEMA = "\nCREATE NODE TABLE Section (\n  id STRING,\n  name STRING,\n  filePath STRING,\n  startLine INT64,\n  endLine INT64,\n  level INT64,\n  content STRING,\n  description STRING,\n  PRIMARY KEY (id)\n)";
 export declare const RELATION_SCHEMA = "\nCREATE REL TABLE CodeRelation (\n  FROM File TO File,\n  FROM File TO Folder,\n  FROM File TO Function,\n  FROM File TO Class,\n  FROM File TO Interface,\n  FROM File TO Method,\n  FROM File TO CodeElement,\n  FROM File TO `Struct`,\n  FROM File TO `Enum`,\n  FROM File TO `Macro`,\n  FROM File TO `Typedef`,\n  FROM File TO `Union`,\n  FROM File TO `Namespace`,\n  FROM File TO `Trait`,\n  FROM File TO `Impl`,\n  FROM File TO `TypeAlias`,\n  FROM File TO `Const`,\n  FROM File TO `Static`,\n  FROM File TO `Property`,\n  FROM File TO `Record`,\n  FROM File TO `Delegate`,\n  FROM File TO `Annotation`,\n  FROM File TO `Constructor`,\n  FROM File TO `Template`,\n  FROM File TO `Module`,\n  FROM File TO Section,\n  FROM Folder TO Folder,\n  FROM Folder TO File,\n  FROM Function TO Function,\n  FROM Function TO Method,\n  FROM Function TO Class,\n  FROM Function TO Community,\n  FROM Function TO `Macro`,\n  FROM Function TO `Struct`,\n  FROM Function TO `Template`,\n  FROM Function TO `Enum`,\n  FROM Function TO `Namespace`,\n  FROM Function TO `TypeAlias`,\n  FROM Function TO `Module`,\n  FROM Function TO `Impl`,\n  FROM Function TO Interface,\n  FROM Function TO `Constructor`,\n  FROM Function TO `Const`,\n  FROM Function TO `Typedef`,\n  FROM Function TO `Union`,\n  FROM Function TO `Property`,\n  FROM Function TO CodeElement,\n  FROM Class TO Method,\n  FROM Class TO Function,\n  FROM Class TO Class,\n  FROM Class TO Interface,\n  FROM Class TO Community,\n  FROM Class TO `Template`,\n  FROM Class TO `TypeAlias`,\n  FROM Class TO `Struct`,\n  FROM Class TO `Enum`,\n  FROM Class TO `Annotation`,\n  FROM Class TO `Constructor`,\n  FROM Class TO `Trait`,\n  FROM Class TO `Macro`,\n  FROM Class TO `Impl`,\n  FROM Class TO `Union`,\n  FROM Class TO `Namespace`,\n  FROM Class TO `Typedef`,\n  FROM Class TO `Property`,\n  FROM Method TO Function,\n  FROM Method TO Method,\n  FROM Method TO Class,\n  FROM Method TO Community,\n  FROM Method TO `Template`,\n  FROM Method TO `Struct`,\n  FROM Method TO `TypeAlias`,\n  FROM Method TO `Enum`,\n  FROM Method TO `Macro`,\n  FROM Method TO `Namespace`,\n  FROM Method TO `Module`,\n  FROM Method TO `Impl`,\n  FROM Method TO Interface,\n  FROM Method TO `Constructor`,\n  FROM Method TO `Property`,\n  FROM Method TO CodeElement,\n  FROM `Template` TO `Template`,\n  FROM `Template` TO Function,\n  FROM `Template` TO Method,\n  FROM `Template` TO Class,\n  FROM `Template` TO `Struct`,\n  FROM `Template` TO `TypeAlias`,\n  FROM `Template` TO `Enum`,\n  FROM `Template` TO `Macro`,\n  FROM `Template` TO Interface,\n  FROM `Template` TO `Constructor`,\n  FROM `Module` TO `Module`,\n  FROM Section TO Section,\n  FROM Section TO File,\n  FROM File TO Route,\n  FROM Function TO Route,\n  FROM Method TO Route,\n  FROM File TO Tool,\n  FROM Function TO Tool,\n  FROM Method TO Tool,\n  FROM CodeElement TO Community,\n  FROM Interface TO Community,\n  FROM Interface TO Function,\n  FROM Interface TO Method,\n  FROM Interface TO Class,\n  FROM Interface TO Interface,\n  FROM Interface TO `TypeAlias`,\n  FROM Interface TO `Struct`,\n  FROM Interface TO `Constructor`,\n  FROM Interface TO `Property`,\n  FROM `Struct` TO Community,\n  FROM `Struct` TO `Trait`,\n  FROM `Struct` TO `Struct`,\n  FROM `Struct` TO Class,\n  FROM `Struct` TO `Enum`,\n  FROM `Struct` TO Function,\n  FROM `Struct` TO Method,\n  FROM `Struct` TO Interface,\n  FROM `Struct` TO `Constructor`,\n  FROM `Struct` TO `Property`,\n  FROM `Enum` TO `Enum`,\n  FROM `Enum` TO Community,\n  FROM `Enum` TO Class,\n  FROM `Enum` TO Interface,\n  FROM `Macro` TO Community,\n  FROM `Macro` TO Function,\n  FROM `Macro` TO Method,\n  FROM `Module` TO Function,\n  FROM `Module` TO Method,\n  FROM `Typedef` TO Community,\n  FROM `Union` TO Community,\n  FROM `Namespace` TO Community,\n  FROM `Namespace` TO `Struct`,\n  FROM `Trait` TO Method,\n  FROM `Trait` TO `Constructor`,\n  FROM `Trait` TO `Property`,\n  FROM `Trait` TO Community,\n  FROM `Impl` TO Method,\n  FROM `Impl` TO `Constructor`,\n  FROM `Impl` TO `Property`,\n  FROM `Impl` TO Community,\n  FROM `Impl` TO `Trait`,\n  FROM `Impl` TO `Struct`,\n  FROM `Impl` TO `Impl`,\n  FROM `TypeAlias` TO Community,\n  FROM `TypeAlias` TO `Trait`,\n  FROM `TypeAlias` TO Class,\n  FROM `Const` TO Community,\n  FROM `Static` TO Community,\n  FROM `Property` TO Community,\n  FROM `Record` TO Method,\n  FROM `Record` TO `Constructor`,\n  FROM `Record` TO `Property`,\n  FROM `Record` TO Community,\n  FROM `Delegate` TO Community,\n  FROM `Annotation` TO Community,\n  FROM `Constructor` TO Community,\n  FROM `Constructor` TO Interface,\n  FROM `Constructor` TO Class,\n  FROM `Constructor` TO Method,\n  FROM `Constructor` TO Function,\n  FROM `Constructor` TO `Constructor`,\n  FROM `Constructor` TO `Struct`,\n  FROM `Constructor` TO `Macro`,\n  FROM `Constructor` TO `Template`,\n  FROM `Constructor` TO `TypeAlias`,\n  FROM `Constructor` TO `Enum`,\n  FROM `Constructor` TO `Annotation`,\n  FROM `Constructor` TO `Impl`,\n  FROM `Constructor` TO `Namespace`,\n  FROM `Constructor` TO `Module`,\n  FROM `Constructor` TO `Property`,\n  FROM `Constructor` TO `Typedef`,\n  FROM `Template` TO Community,\n  FROM `Module` TO Community,\n  FROM Function TO Process,\n  FROM Method TO Process,\n  FROM Class TO Process,\n  FROM Interface TO Process,\n  FROM `Struct` TO Process,\n  FROM `Constructor` TO Process,\n  FROM `Module` TO Process,\n  FROM `Macro` TO Process,\n  FROM `Impl` TO Process,\n  FROM `Typedef` TO Process,\n  FROM `TypeAlias` TO Process,\n  FROM `Enum` TO Process,\n  FROM `Union` TO Process,\n  FROM `Namespace` TO Process,\n  FROM `Trait` TO Process,\n  FROM `Const` TO Process,\n  FROM `Static` TO Process,\n  FROM `Property` TO Process,\n  FROM `Record` TO Process,\n  FROM `Delegate` TO Process,\n  FROM `Annotation` TO Process,\n  FROM `Template` TO Process,\n  FROM CodeElement TO Process,\n  FROM Route TO Process,\n  FROM Tool TO Process,\n  type STRING,\n  confidence DOUBLE,\n  reason STRING,\n  step INT32\n)";
 export declare const EMBEDDING_DIMS: number;
+/** HNSW vector index name for the CodeEmbedding table. */
+export declare const EMBEDDING_INDEX_NAME = "code_embedding_idx";
+/**
+ * Sentinel value for "no content hash available" — used in legacy DBs and null rows.
+ * Nodes with this hash are always treated as stale and re-embedded.
+ */
+export declare const STALE_HASH_SENTINEL = "";
 export declare const EMBEDDING_SCHEMA: string;
 /**
  * Create vector index for semantic search

package/dist/core/lbug/schema.js

@@ -410,10 +410,18 @@ if (Number.isNaN(_rawDims) || _rawDims <= 0) {
     throw new Error(`GITNEXUS_EMBEDDING_DIMS must be a positive integer, got "${process.env.GITNEXUS_EMBEDDING_DIMS}"`);
 }
 export const EMBEDDING_DIMS = _rawDims;
+/** HNSW vector index name for the CodeEmbedding table. */
+export const EMBEDDING_INDEX_NAME = 'code_embedding_idx';
+/**
+ * Sentinel value for "no content hash available" — used in legacy DBs and null rows.
+ * Nodes with this hash are always treated as stale and re-embedded.
+ */
+export const STALE_HASH_SENTINEL = '';
 export const EMBEDDING_SCHEMA = `
 CREATE NODE TABLE ${EMBEDDING_TABLE_NAME} (
   nodeId STRING,
   embedding FLOAT[${EMBEDDING_DIMS}],
+  contentHash STRING,
   PRIMARY KEY (nodeId)
 )`;
 /**
@@ -421,7 +429,7 @@ CREATE NODE TABLE ${EMBEDDING_TABLE_NAME} (
  * Uses HNSW (Hierarchical Navigable Small World) algorithm with cosine similarity
  */
 export const CREATE_VECTOR_INDEX_QUERY = `
-CALL CREATE_VECTOR_INDEX('${EMBEDDING_TABLE_NAME}', 'code_embedding_idx', 'embedding', metric := 'cosine')
+CALL CREATE_VECTOR_INDEX('${EMBEDDING_TABLE_NAME}', '${EMBEDDING_INDEX_NAME}', 'embedding', metric := 'cosine')
 `;
 // ============================================================================
 // ALL SCHEMA QUERIES IN ORDER

package/dist/core/run-analyze.js

@@ -15,6 +15,8 @@ import { initLbug, loadGraphToLbug, getLbugStats, executeQuery, executeWithReuse
 import { getStoragePaths, saveMeta, loadMeta, addToGitignore, registerRepo, cleanupOldKuzuFiles, } from '../storage/repo-manager.js';
 import { getCurrentCommit, hasGitDir } from '../storage/git.js';
 import { generateAIContextFiles } from '../cli/ai-context.js';
+import { EMBEDDING_TABLE_NAME } from './lbug/schema.js';
+import { STALE_HASH_SENTINEL } from './lbug/schema.js';
 /** Threshold: auto-skip embeddings for repos with more nodes than this */
 const EMBEDDING_NODE_LIMIT = 50_000;
 export const PHASE_LABELS = {
@@ -147,9 +149,13 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
                 const EMBED_BATCH = 200;
                 for (let i = 0; i < cachedEmbeddings.length; i += EMBED_BATCH) {
                     const batch = cachedEmbeddings.slice(i, i + EMBED_BATCH);
-                    const paramsList = batch.map((e) => ({ nodeId: e.nodeId, embedding: e.embedding }));
+                    const paramsList = batch.map((e) => ({
+                        nodeId: e.nodeId,
+                        embedding: e.embedding,
+                        contentHash: e.contentHash ?? STALE_HASH_SENTINEL,
+                    }));
                     try {
-                        await executeWithReusedStatement(`CREATE (e:CodeEmbedding {nodeId: $nodeId, embedding: $embedding})`, paramsList);
+                        await executeWithReusedStatement(`MERGE (e:${EMBEDDING_TABLE_NAME} {nodeId: $nodeId}) SET e.embedding = $embedding, e.contentHash = $contentHash`, paramsList);
                     }
                     catch {
                         /* some may fail if node was removed, that's fine */
@@ -170,6 +176,14 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
             const httpMode = isHttpMode();
             progress('embeddings', 90, httpMode ? 'Connecting to embedding endpoint...' : 'Loading embedding model...');
             const { runEmbeddingPipeline } = await import('./embeddings/embedding-pipeline.js');
+            // Build a Map<nodeId, contentHash> from cached embeddings for incremental mode
+            let existingEmbeddings;
+            if (cachedEmbeddingNodeIds.size > 0) {
+                existingEmbeddings = new Map();
+                for (const e of cachedEmbeddings) {
+                    existingEmbeddings.set(e.nodeId, e.contentHash ?? STALE_HASH_SENTINEL);
+                }
+            }
             await runEmbeddingPipeline(executeQuery, executeWithReusedStatement, (p) => {
                 const scaled = 90 + Math.round((p.percent / 100) * 8);
                 const label = p.phase === 'loading-model'
@@ -178,14 +192,14 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
                         : 'Loading embedding model...'
                     : `Embedding ${p.nodesProcessed || 0}/${p.totalNodes || '?'}`;
                 progress('embeddings', scaled, label);
-            }, {}, cachedEmbeddingNodeIds.size > 0 ? cachedEmbeddingNodeIds : undefined);
+            }, {}, existingEmbeddings);
         }
         // ── Phase 5: Finalize (98–100%) ───────────────────────────────────
         progress('done', 98, 'Saving metadata...');
         // Count embeddings in the index (cached + newly generated)
         let embeddingCount = 0;
         try {
-            const embResult = await executeQuery(`MATCH (e:CodeEmbedding) RETURN count(e) AS cnt`);
+            const embResult = await executeQuery(`MATCH (e:${EMBEDDING_TABLE_NAME}) RETURN count(e) AS cnt`);
             embeddingCount = embResult?.[0]?.cnt ?? 0;
         }
         catch {

package/dist/mcp/core/embedder.js

@@ -30,6 +30,11 @@ export const initEmbedder = async () => {
     initPromise = (async () => {
         try {
             env.allowLocalModels = false;
+            // Default cache to user-writable location. transformers.js defaults to
+            // ./node_modules/.cache inside its own install dir, which is unwritable
+            // when gitnexus is installed globally (e.g. /usr/lib/node_modules/).
+            // Respect HF_HOME if set, otherwise fall back to ~/.cache/huggingface.
+            env.cacheDir = process.env.HF_HOME ?? `${process.env.HOME}/.cache/huggingface`;
             console.error('GitNexus: Loading embedding model (first search may take a moment)...');
             // Try GPU first (DirectML on Windows, CUDA on Linux), fall back to CPU
             const isWindows = process.platform === 'win32';

package/dist/server/api.js

@@ -1277,6 +1277,13 @@ export const createServer = async (port, host = '127.0.0.1') => {
                     const lbugPath = path.join(entry.storagePath, 'lbug');
                     await withLbugDb(lbugPath, async () => {
                         const { runEmbeddingPipeline } = await import('../core/embeddings/embedding-pipeline.js');
+                        // Fetch existing content hashes for incremental embedding.
+                        // Delegated to lbug-adapter which owns the DB query logic and legacy-fallback handling.
+                        const { fetchExistingEmbeddingHashes } = await import('../core/lbug/lbug-adapter.js');
+                        const existingEmbeddings = await fetchExistingEmbeddingHashes(executeQuery);
+                        if (existingEmbeddings && existingEmbeddings.size > 0) {
+                            console.log(`[embed] ${existingEmbeddings.size} nodes already embedded — incremental run with content-hash comparison`);
+                        }
                         await runEmbeddingPipeline(executeQuery, executeWithReusedStatement, (p) => {
                             embedJobManager.updateJob(job.id, {
                                 progress: {
@@ -1293,7 +1300,8 @@ export const createServer = async (port, host = '127.0.0.1') => {
                                                     : `${p.phase} (${p.percent}%)`,
                                 },
                             });
-                        });
+                        }, {}, // config: use defaults
+                        existingEmbeddings);
                     });
                     clearTimeout(embedTimeout);
                     releaseRepoLock(repoLockPath);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.1",
+  "version": "1.6.2-rc.10",
   "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",
@@ -46,7 +46,7 @@
     "test:integration": "vitest run test/integration",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
-    "postinstall": "node scripts/patch-tree-sitter-swift.cjs",
+    "postinstall": "node scripts/patch-tree-sitter-swift.cjs && node scripts/build-tree-sitter-proto.cjs",
     "prepare": "node scripts/build.js",
     "prepack": "node scripts/build.js"
   },
@@ -71,7 +71,7 @@
     "pandemonium": "^2.4.0",
     "tree-sitter": "^0.21.1",
     "tree-sitter-c": "0.23.2",
-    "tree-sitter-c-sharp": "^0.23.1",
+    "tree-sitter-c-sharp": "0.23.1",
     "tree-sitter-cpp": "^0.23.4",
     "tree-sitter-go": "^0.23.0",
     "tree-sitter-java": "^0.23.5",
@@ -84,7 +84,9 @@
     "uuid": "^13.0.0"
   },
   "optionalDependencies": {
-    "tree-sitter-dart": "https://github.com/UserNobody14/tree-sitter-dart/archive/80e23c07b64494f7e21090bb3450223ef0b192f4.tar.gz",
+    "node-addon-api": "^8.0.0",
+    "node-gyp-build": "^4.8.0",
+    "tree-sitter-dart": "git+https://github.com/UserNobody14/tree-sitter-dart.git#80e23c07b64494f7e21090bb3450223ef0b192f4",
     "tree-sitter-kotlin": "^0.3.8",
     "tree-sitter-proto": "file:./vendor/tree-sitter-proto",
     "tree-sitter-swift": "^0.6.0"

package/scripts/build-tree-sitter-proto.cjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+/**
+ * Build tree-sitter-proto native binding.
+ *
+ * Why this script exists:
+ *   tree-sitter-proto is vendored under gitnexus/vendor/tree-sitter-proto/
+ *   and declared as a `file:` optionalDependency. Previously, the vendored
+ *   package had its own `dependencies` and `install` script, which caused
+ *   npm to create `vendor/tree-sitter-proto/node_modules/` and
+ *   `vendor/tree-sitter-proto/build/` during install. Those directories
+ *   blocked `rmdir` on global-install upgrade, producing:
+ *
+ *     ENOTEMPTY: directory not empty, rmdir
+ *       '.../gitnexus/vendor/tree-sitter-proto/node_modules/node-addon-api'
+ *
+ *   (See https://github.com/abhigyanpatwari/GitNexus/issues/836.)
+ *
+ *   We stripped `dependencies` and the `install` script from the vendored
+ *   package.json, hoisted `node-addon-api` and `node-gyp-build` into
+ *   gitnexus's own optionalDependencies, and moved native compilation here.
+ *
+ * What this does:
+ *   Runs `npx node-gyp rebuild` inside `node_modules/tree-sitter-proto/`
+ *   (which npm creates as a copy of vendor/tree-sitter-proto/ when
+ *   resolving the file: dep). Build output lands in
+ *   `node_modules/tree-sitter-proto/build/Release/tree_sitter_proto_binding.node`
+ *   — under npm-managed territory, safe on upgrade.
+ *
+ *   Mirrors scripts/patch-tree-sitter-swift.cjs. Best-effort: if any
+ *   precondition fails (optional dep absent, no toolchain, --ignore-scripts),
+ *   warn and exit 0 so gitnexus install still succeeds.
+ */
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const protoDir = path.join(__dirname, '..', 'node_modules', 'tree-sitter-proto');
+const bindingGyp = path.join(protoDir, 'binding.gyp');
+const bindingNode = path.join(protoDir, 'build', 'Release', 'tree_sitter_proto_binding.node');
+
+try {
+  if (!fs.existsSync(bindingGyp)) {
+    // tree-sitter-proto is an optionalDependency; absent when install
+    // skipped optional deps or the file: dep was not resolved.
+    process.exit(0);
+  }
+
+  // Skip if the native binding already exists (idempotent re-run).
+  if (fs.existsSync(bindingNode)) {
+    process.exit(0);
+  }
+
+  // Pre-flight: the hoisted build deps must be resolvable.
+  try {
+    require.resolve('node-addon-api');
+    require.resolve('node-gyp-build');
+  } catch (resolveErr) {
+    console.warn(
+      '[tree-sitter-proto] Skipping build: hoisted build deps not resolvable (%s).',
+      resolveErr.message,
+    );
+    console.warn(
+      '[tree-sitter-proto] Proto parsing will be unavailable. Install without --no-optional and with scripts enabled to build.',
+    );
+    process.exit(0);
+  }
+
+  console.log('[tree-sitter-proto] Building native binding...');
+  execSync('npx node-gyp rebuild', {
+    cwd: protoDir,
+    stdio: 'pipe',
+    timeout: 180000,
+  });
+  console.log('[tree-sitter-proto] Native binding built successfully');
+} catch (err) {
+  console.warn('[tree-sitter-proto] Could not build native binding:', err.message);
+  console.warn(
+    '[tree-sitter-proto] Proto (.proto) parsing will be unavailable. Non-proto gitnexus functionality is unaffected.',
+  );
+  // Exit 0: optionalDependency failures must not fail the gitnexus install.
+  process.exit(0);
+}

package/vendor/node_modules/node-addon-api/node_addon_api.Makefile

@@ -0,0 +1,6 @@
+# This file is generated by gyp; do not edit.
+
+export builddir_name ?= ./build/../../node_modules/node-addon-api/.
+.PHONY: all
+all:
+	$(MAKE) -C ../../tree-sitter-proto/build node_addon_api_except