gitnexus 1.1.8 → 1.2.0

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

@@ -49,111 +49,163 @@ export const initKuzu = async (dbPath) => {
     }
     return { db, conn };
 };
-export const loadGraphToKuzu = async (graph, fileContents, storagePath) => {
+export const loadGraphToKuzu = async (graph, fileContents, storagePath, onProgress) => {
     if (!conn) {
         throw new Error('KuzuDB not initialized. Call initKuzu first.');
     }
+    const log = onProgress || (() => { });
     const csvData = generateAllCSVs(graph, fileContents);
     const csvDir = path.join(storagePath, 'csv');
     await fs.mkdir(csvDir, { recursive: true });
+    log('Generating CSVs...');
     const nodeFiles = [];
     for (const [tableName, csv] of csvData.nodes.entries()) {
-        if (csv.split('\n').length <= 1)
+        const rowCount = csv.split('\n').length - 1;
+        if (rowCount <= 0)
             continue;
         const filePath = path.join(csvDir, `${tableName.toLowerCase()}.csv`);
         await fs.writeFile(filePath, csv, 'utf-8');
-        nodeFiles.push({ table: tableName, path: filePath });
+        nodeFiles.push({ table: tableName, path: filePath, rows: rowCount });
     }
-    const relLines = csvData.relCSV.split('\n').slice(1).filter(line => line.trim());
-    for (const { table, path: filePath } of nodeFiles) {
+    // Write relationship CSV to disk for bulk COPY
+    const relCsvPath = path.join(csvDir, 'relations.csv');
+    const validTables = new Set(NODE_TABLES);
+    const getNodeLabel = (nodeId) => {
+        if (nodeId.startsWith('comm_'))
+            return 'Community';
+        if (nodeId.startsWith('proc_'))
+            return 'Process';
+        return nodeId.split(':')[0];
+    };
+    const relLines = csvData.relCSV.split('\n');
+    const relHeader = relLines[0];
+    const validRelLines = [relHeader];
+    let skippedRels = 0;
+    for (let i = 1; i < relLines.length; i++) {
+        const line = relLines[i];
+        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;
+        }
+        validRelLines.push(line);
+    }
+    await fs.writeFile(relCsvPath, validRelLines.join('\n'), 'utf-8');
+    // Bulk COPY all node CSVs
+    const totalSteps = nodeFiles.length + 1; // +1 for relationships
+    let stepsDone = 0;
+    for (const { table, path: filePath, rows } of nodeFiles) {
+        stepsDone++;
+        log(`Loading nodes ${stepsDone}/${totalSteps}: ${table} (${rows.toLocaleString()} rows)`);
         const normalizedPath = normalizeCopyPath(filePath);
         const copyQuery = getCopyQuery(table, normalizedPath);
-        // Log CSV stats for diagnostics
-        const csvContent = await fs.readFile(filePath, 'utf-8');
-        const csvLines = csvContent.split('\n').length;
-        console.log(`  COPY ${table}: ${csvLines - 1} rows`);
         try {
             await conn.query(copyQuery);
         }
         catch (err) {
-            const errMsg = err instanceof Error ? err.message : String(err);
-            console.warn(`⚠️ COPY failed for ${table} (${csvLines - 1} rows): ${errMsg}`);
-            // Retry with IGNORE_ERRORS=true to skip malformed rows
-            console.log(`  Retrying ${table} with IGNORE_ERRORS=true...`);
             try {
                 const retryQuery = copyQuery.replace('auto_detect=false)', 'auto_detect=false, IGNORE_ERRORS=true)');
                 await conn.query(retryQuery);
-                console.log(`  ✅ ${table} loaded with IGNORE_ERRORS (some rows may have been skipped)`);
             }
             catch (retryErr) {
                 const retryMsg = retryErr instanceof Error ? retryErr.message : String(retryErr);
-                console.error(`❌ COPY failed for ${table} even with IGNORE_ERRORS: ${retryMsg}`);
-                throw retryErr;
+                throw new Error(`COPY failed for ${table}: ${retryMsg.slice(0, 200)}`);
             }
         }
     }
-    console.log('✅ All COPY commands succeeded. Starting relationship insertion...');
-    // Build a set of valid table names for fast lookup
-    const validTables = new Set(NODE_TABLES);
-    const getNodeLabel = (nodeId) => {
-        if (nodeId.startsWith('comm_'))
-            return 'Community';
-        if (nodeId.startsWith('proc_'))
-            return 'Process';
-        return nodeId.split(':')[0];
-    };
-    // All multi-language tables are created with backticks - must always reference them with backticks
-    const escapeLabel = (label) => {
-        return BACKTICK_TABLES.has(label) ? `\`${label}\`` : label;
-    };
-    let insertedRels = 0;
-    let skippedRels = 0;
-    for (const line of relLines) {
-        try {
-            const match = line.match(/"([^"]*)","([^"]*)","([^"]*)",([0-9.]+),"([^"]*)",([0-9-]+)/);
+    // Bulk COPY relationships — split by FROM→TO label pair (KuzuDB requires it)
+    const insertedRels = validRelLines.length - 1;
+    const warnings = [];
+    if (insertedRels > 0) {
+        const relsByPair = new Map();
+        for (let i = 1; i < validRelLines.length; i++) {
+            const line = validRelLines[i];
+            const match = line.match(/"([^"]*)","([^"]*)"/);
             if (!match)
                 continue;
-            const [, fromId, toId, relType, confidenceStr, reason, stepStr] = match;
-            const fromLabel = getNodeLabel(fromId);
-            const toLabel = getNodeLabel(toId);
-            // Skip relationships where either node's label doesn't have a table in KuzuDB
-            // (e.g. Variable, Import, Type nodes that aren't in the schema)
-            // Querying a non-existent table causes a fatal native crash
-            if (!validTables.has(fromLabel) || !validTables.has(toLabel)) {
-                skippedRels++;
-                continue;
+            const fromLabel = getNodeLabel(match[1]);
+            const toLabel = getNodeLabel(match[2]);
+            const pairKey = `${fromLabel}|${toLabel}`;
+            let list = relsByPair.get(pairKey);
+            if (!list) {
+                list = [];
+                relsByPair.set(pairKey, list);
             }
-            const confidence = parseFloat(confidenceStr) || 1.0;
-            const step = parseInt(stepStr) || 0;
-            const insertQuery = `
-        MATCH (a:${escapeLabel(fromLabel)} {id: '${fromId.replace(/'/g, "''")}' }),
-              (b:${escapeLabel(toLabel)} {id: '${toId.replace(/'/g, "''")}' })
-        CREATE (a)-[:${REL_TABLE_NAME} {type: '${relType}', confidence: ${confidence}, reason: '${reason.replace(/'/g, "''")}', step: ${step}}]->(b)
-      `;
-            await conn.query(insertQuery);
-            insertedRels++;
+            list.push(line);
+        }
+        log(`Loading edges: ${insertedRels.toLocaleString()} across ${relsByPair.size} types`);
+        let pairIdx = 0;
+        let failedPairEdges = 0;
+        const failedPairLines = [];
+        for (const [pairKey, lines] of relsByPair) {
+            pairIdx++;
+            const [fromLabel, toLabel] = pairKey.split('|');
+            const pairCsvPath = path.join(csvDir, `rel_${fromLabel}_${toLabel}.csv`);
+            await fs.writeFile(pairCsvPath, relHeader + '\n' + lines.join('\n'), 'utf-8');
+            const normalizedPath = normalizeCopyPath(pairCsvPath);
+            const copyQuery = `COPY ${REL_TABLE_NAME} FROM "${normalizedPath}" (from="${fromLabel}", to="${toLabel}", HEADER=true, ESCAPE='"', DELIM=',', QUOTE='"', PARALLEL=false, auto_detect=false)`;
+            if (pairIdx % 5 === 0 || lines.length > 1000) {
+                log(`Loading edges: ${pairIdx}/${relsByPair.size} types (${fromLabel} -> ${toLabel})`);
+            }
+            try {
+                await conn.query(copyQuery);
+            }
+            catch (err) {
+                try {
+                    const retryQuery = copyQuery.replace('auto_detect=false)', 'auto_detect=false, IGNORE_ERRORS=true)');
+                    await conn.query(retryQuery);
+                }
+                catch (retryErr) {
+                    const retryMsg = retryErr instanceof Error ? retryErr.message : String(retryErr);
+                    warnings.push(`${fromLabel}->${toLabel} (${lines.length} edges): ${retryMsg.slice(0, 80)}`);
+                    failedPairEdges += lines.length;
+                    failedPairLines.push(...lines);
+                }
+            }
+            try {
+                await fs.unlink(pairCsvPath);
+            }
+            catch { }
         }
-        catch {
-            skippedRels++;
+        if (failedPairLines.length > 0) {
+            log(`Inserting ${failedPairEdges} edges individually (missing schema pairs)`);
+            await fallbackRelationshipInserts([relHeader, ...failedPairLines], validTables, getNodeLabel);
         }
     }
-    // Cleanup CSVs
+    // Cleanup all CSVs
+    try {
+        await fs.unlink(relCsvPath);
+    }
+    catch { }
     for (const { path: filePath } of nodeFiles) {
         try {
             await fs.unlink(filePath);
         }
-        catch {
-            // ignore
+        catch { }
+    }
+    try {
+        const remaining = await fs.readdir(csvDir);
+        for (const f of remaining) {
+            try {
+                await fs.unlink(path.join(csvDir, f));
+            }
+            catch { }
         }
     }
-    // Remove empty csv directory
+    catch { }
     try {
         await fs.rmdir(csvDir);
     }
-    catch {
-        // ignore if not empty or other error
-    }
-    return { success: true, insertedRels, skippedRels };
+    catch { }
+    return { success: true, insertedRels, skippedRels, warnings };
 };
 // KuzuDB default ESCAPE is '\' (backslash), but our CSV uses RFC 4180 escaping ("" for literal quotes).
 // Source code content is full of backslashes which confuse the auto-detection.
@@ -170,6 +222,37 @@ const BACKTICK_TABLES = new Set([
 const escapeTableName = (table) => {
     return BACKTICK_TABLES.has(table) ? `\`${table}\`` : table;
 };
+/** Fallback: insert relationships one-by-one if COPY fails */
+const fallbackRelationshipInserts = async (validRelLines, validTables, getNodeLabel) => {
+    if (!conn)
+        return;
+    const escapeLabel = (label) => {
+        return BACKTICK_TABLES.has(label) ? `\`${label}\`` : label;
+    };
+    for (let i = 1; i < validRelLines.length; i++) {
+        const line = validRelLines[i];
+        try {
+            const match = line.match(/"([^"]*)","([^"]*)","([^"]*)",([0-9.]+),"([^"]*)",([0-9-]+)/);
+            if (!match)
+                continue;
+            const [, fromId, toId, relType, confidenceStr, reason, stepStr] = match;
+            const fromLabel = getNodeLabel(fromId);
+            const toLabel = getNodeLabel(toId);
+            if (!validTables.has(fromLabel) || !validTables.has(toLabel))
+                continue;
+            const confidence = parseFloat(confidenceStr) || 1.0;
+            const step = parseInt(stepStr) || 0;
+            await conn.query(`
+        MATCH (a:${escapeLabel(fromLabel)} {id: '${fromId.replace(/'/g, "''")}' }),
+              (b:${escapeLabel(toLabel)} {id: '${toId.replace(/'/g, "''")}' })
+        CREATE (a)-[:${REL_TABLE_NAME} {type: '${relType}', confidence: ${confidence}, reason: '${reason.replace(/'/g, "''")}', step: ${step}}]->(b)
+      `);
+        }
+        catch {
+            // skip
+        }
+    }
+};
 const getCopyQuery = (table, filePath) => {
     const t = escapeTableName(table);
     if (table === 'File') {
@@ -377,6 +460,37 @@ export const getKuzuStats = async () => {
     }
     return { nodes: totalNodes, edges: totalEdges };
 };
+/**
+ * Load cached embeddings from KuzuDB before a rebuild.
+ * Returns all embedding vectors so they can be re-inserted after the graph is reloaded,
+ * avoiding expensive re-embedding of unchanged nodes.
+ */
+export const loadCachedEmbeddings = async () => {
+    if (!conn) {
+        return { embeddingNodeIds: new Set(), embeddings: [] };
+    }
+    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`);
+        const result = Array.isArray(rows) ? rows[0] : rows;
+        for (const row of await result.getAll()) {
+            const nodeId = String(row.nodeId ?? row[0] ?? '');
+            if (!nodeId)
+                continue;
+            embeddingNodeIds.add(nodeId);
+            const embedding = row.embedding ?? row[1];
+            if (embedding) {
+                embeddings.push({
+                    nodeId,
+                    embedding: Array.isArray(embedding) ? embedding.map(Number) : Array.from(embedding).map(Number),
+                });
+            }
+        }
+    }
+    catch { /* embedding table may not exist */ }
+    return { embeddingNodeIds, embeddings };
+};
 export const closeKuzu = async () => {
     if (conn) {
         try {

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

@@ -41,7 +41,7 @@ export declare const ANNOTATION_SCHEMA: string;
 export declare const CONSTRUCTOR_SCHEMA: string;
 export declare const TEMPLATE_SCHEMA: string;
 export declare const MODULE_SCHEMA: string;
-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 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 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 `Constructor`,\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 `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 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 `Struct` TO Community,\n  FROM `Struct` TO `Trait`,\n  FROM `Struct` TO Function,\n  FROM `Struct` TO Method,\n  FROM `Enum` TO Community,\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 `Trait` TO Community,\n  FROM `Impl` TO Community,\n  FROM `Impl` TO `Trait`,\n  FROM `TypeAlias` TO Community,\n  FROM `Const` TO Community,\n  FROM `Static` TO Community,\n  FROM `Property` TO Community,\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 `Impl`,\n  FROM `Constructor` TO `Namespace`,\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  type STRING,\n  confidence DOUBLE,\n  reason STRING,\n  step INT32\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 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 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 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 `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 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 `Struct` TO Community,\n  FROM `Struct` TO `Trait`,\n  FROM `Struct` TO Function,\n  FROM `Struct` TO Method,\n  FROM `Enum` TO Community,\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 `Trait` TO Community,\n  FROM `Impl` TO Community,\n  FROM `Impl` TO `Trait`,\n  FROM `TypeAlias` TO Community,\n  FROM `Const` TO Community,\n  FROM `Static` TO Community,\n  FROM `Property` TO Community,\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 `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  type STRING,\n  confidence DOUBLE,\n  reason STRING,\n  step INT32\n)";
 export declare const EMBEDDING_SCHEMA = "\nCREATE NODE TABLE CodeEmbedding (\n  nodeId STRING,\n  embedding FLOAT[384],\n  PRIMARY KEY (nodeId)\n)";
 /**
  * Create vector index for semantic search

package/dist/core/kuzu/schema.js

@@ -218,6 +218,7 @@ CREATE REL TABLE ${REL_TABLE_NAME} (
   FROM Class TO \`TypeAlias\`,
   FROM Class TO \`Struct\`,
   FROM Class TO \`Enum\`,
+  FROM Class TO \`Annotation\`,
   FROM Class TO \`Constructor\`,
   FROM Method TO Function,
   FROM Method TO Method,
@@ -287,8 +288,10 @@ CREATE REL TABLE ${REL_TABLE_NAME} (
   FROM \`Constructor\` TO \`Template\`,
   FROM \`Constructor\` TO \`TypeAlias\`,
   FROM \`Constructor\` TO \`Enum\`,
+  FROM \`Constructor\` TO \`Annotation\`,
   FROM \`Constructor\` TO \`Impl\`,
   FROM \`Constructor\` TO \`Namespace\`,
+  FROM \`Constructor\` TO \`Module\`,
   FROM \`Template\` TO Community,
   FROM \`Module\` TO Community,
   FROM Function TO Process,

package/dist/core/search/bm25-index.js

@@ -47,25 +47,23 @@ export const searchFTSFromKuzu = async (query, limit = 20, repoId) => {
     let fileResults, functionResults, classResults, methodResults, interfaceResults;
     if (repoId) {
         // Use MCP connection pool via dynamic import
+        // IMPORTANT: KuzuDB uses a single connection per repo — queries must be sequential
+        // to avoid deadlocking. Do NOT use Promise.all here.
         const { executeQuery } = await import('../../mcp/core/kuzu-adapter.js');
         const executor = (cypher) => executeQuery(repoId, cypher);
-        [fileResults, functionResults, classResults, methodResults, interfaceResults] = await Promise.all([
-            queryFTSViaExecutor(executor, 'File', 'file_fts', query, limit),
-            queryFTSViaExecutor(executor, 'Function', 'function_fts', query, limit),
-            queryFTSViaExecutor(executor, 'Class', 'class_fts', query, limit),
-            queryFTSViaExecutor(executor, 'Method', 'method_fts', query, limit),
-            queryFTSViaExecutor(executor, 'Interface', 'interface_fts', query, limit),
-        ]);
+        fileResults = await queryFTSViaExecutor(executor, 'File', 'file_fts', query, limit);
+        functionResults = await queryFTSViaExecutor(executor, 'Function', 'function_fts', query, limit);
+        classResults = await queryFTSViaExecutor(executor, 'Class', 'class_fts', query, limit);
+        methodResults = await queryFTSViaExecutor(executor, 'Method', 'method_fts', query, limit);
+        interfaceResults = await queryFTSViaExecutor(executor, 'Interface', 'interface_fts', query, limit);
     }
     else {
-        // Use core kuzu adapter (CLI / pipeline context)
-        [fileResults, functionResults, classResults, methodResults, interfaceResults] = await Promise.all([
-            queryFTS('File', 'file_fts', query, limit, false).catch(() => []),
-            queryFTS('Function', 'function_fts', query, limit, false).catch(() => []),
-            queryFTS('Class', 'class_fts', query, limit, false).catch(() => []),
-            queryFTS('Method', 'method_fts', query, limit, false).catch(() => []),
-            queryFTS('Interface', 'interface_fts', query, limit, false).catch(() => []),
-        ]);
+        // Use core kuzu adapter (CLI / pipeline context) — also sequential for safety
+        fileResults = await queryFTS('File', 'file_fts', query, limit, false).catch(() => []);
+        functionResults = await queryFTS('Function', 'function_fts', query, limit, false).catch(() => []);
+        classResults = await queryFTS('Class', 'class_fts', query, limit, false).catch(() => []);
+        methodResults = await queryFTS('Method', 'method_fts', query, limit, false).catch(() => []);
+        interfaceResults = await queryFTS('Interface', 'interface_fts', query, limit, false).catch(() => []);
     }
     // Merge results by filePath, summing scores for same file
     const merged = new Map();

package/dist/core/wiki/generator.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Wiki Generator
+ *
+ * Orchestrates the full wiki generation pipeline:
+ *   Phase 0: Validate prerequisites + gather graph structure
+ *   Phase 1: Build module tree (one LLM call)
+ *   Phase 2: Generate module pages (one LLM call per module, bottom-up)
+ *   Phase 3: Generate overview page
+ *
+ * Supports incremental updates via git diff + module-file mapping.
+ */
+import { type LLMConfig } from './llm-client.js';
+export interface WikiOptions {
+    force?: boolean;
+    model?: string;
+    baseUrl?: string;
+    apiKey?: string;
+    maxTokensPerModule?: number;
+}
+export interface WikiMeta {
+    fromCommit: string;
+    generatedAt: string;
+    model: string;
+    moduleFiles: Record<string, string[]>;
+    moduleTree: ModuleTreeNode[];
+}
+export interface ModuleTreeNode {
+    name: string;
+    slug: string;
+    files: string[];
+    children?: ModuleTreeNode[];
+}
+export type ProgressCallback = (phase: string, percent: number, detail?: string) => void;
+export declare class WikiGenerator {
+    private repoPath;
+    private storagePath;
+    private wikiDir;
+    private kuzuPath;
+    private llmConfig;
+    private maxTokensPerModule;
+    private options;
+    private onProgress;
+    private failedModules;
+    constructor(repoPath: string, storagePath: string, kuzuPath: string, llmConfig: LLMConfig, options?: WikiOptions, onProgress?: ProgressCallback);
+    /**
+     * Main entry point. Runs the full pipeline or incremental update.
+     */
+    run(): Promise<{
+        pagesGenerated: number;
+        mode: 'full' | 'incremental' | 'up-to-date';
+        failedModules: string[];
+    }>;
+    private fullGeneration;
+    private buildModuleTree;
+    /**
+     * Parse LLM grouping response. Validates all files are assigned.
+     */
+    private parseGroupingResponse;
+    /**
+     * Fallback grouping by top-level directory when LLM parsing fails.
+     */
+    private fallbackGrouping;
+    /**
+     * Split a large module into sub-modules by subdirectory.
+     */
+    private splitBySubdirectory;
+    /**
+     * Recursively generate pages for a module tree node.
+     * Returns count of pages generated.
+     */
+    private generateModulePage;
+    /**
+     * Generate a leaf module page from source code + graph data.
+     */
+    private generateLeafPage;
+    /**
+     * Generate a parent module page from children's documentation.
+     */
+    private generateParentPage;
+    private generateOverview;
+    private incrementalUpdate;
+    private getCurrentCommit;
+    private getChangedFiles;
+    private readSourceFiles;
+    private truncateSource;
+    private estimateModuleTokens;
+    private readProjectInfo;
+    private extractModuleFiles;
+    private countModules;
+    private findNodeBySlug;
+    private slugify;
+    private fileExists;
+    private loadWikiMeta;
+    private saveWikiMeta;
+    private saveModuleTree;
+}