gitnexus 1.4.7 → 1.4.8

package/dist/core/ingestion/workers/parse-worker.d.ts

@@ -1,6 +1,7 @@
 import { SupportedLanguages } from '../../../config/supported-languages.js';
 import { type MixedChainStep } from '../utils.js';
 import type { ConstructorBinding } from '../type-env.js';
+import type { NamedBinding } from '../import-resolution.js';
 import type { NodeLabel } from '../../graph/types.js';
 interface ParsedNode {
     id: string;
@@ -16,6 +17,7 @@ interface ParsedNode {
         astFrameworkReason?: string;
         description?: string;
         parameterCount?: number;
+        requiredParameterCount?: number;
         returnType?: string;
     };
 }
@@ -33,6 +35,8 @@ interface ParsedSymbol {
     nodeId: string;
     type: NodeLabel;
     parameterCount?: number;
+    requiredParameterCount?: number;
+    parameterTypes?: string[];
     returnType?: string;
     declaredType?: string;
     ownerId?: string;
@@ -42,10 +46,7 @@ export interface ExtractedImport {
     rawImportPath: string;
     language: SupportedLanguages;
     /** Named bindings from the import (e.g., import {User as U} → [{local:'U', exported:'User'}]) */
-    namedBindings?: {
-        local: string;
-        exported: string;
-    }[];
+    namedBindings?: NamedBinding[];
 }
 export interface ExtractedCall {
     filePath: string;
@@ -102,6 +103,12 @@ export interface FileConstructorBindings {
     filePath: string;
     bindings: ConstructorBinding[];
 }
+/** File-scope type bindings from TypeEnv fixpoint — used for cross-file ExportedTypeMap. */
+export interface FileTypeEnvBindings {
+    filePath: string;
+    /** [varName, typeName] pairs from file scope (scope = '') */
+    bindings: [string, string][];
+}
 export interface ParseWorkerResult {
     nodes: ParsedNode[];
     relationships: ParsedRelationship[];
@@ -112,6 +119,8 @@ export interface ParseWorkerResult {
     heritage: ExtractedHeritage[];
     routes: ExtractedRoute[];
     constructorBindings: FileConstructorBindings[];
+    /** File-scope type bindings from TypeEnv fixpoint for exported symbol collection. */
+    typeEnvBindings: FileTypeEnvBindings[];
     skippedLanguages: Record<string, number>;
     fileCount: number;
 }

package/dist/core/ingestion/workers/parse-worker.js

@@ -28,14 +28,13 @@ try {
     Kotlin = _require('tree-sitter-kotlin');
 }
 catch { }
-import { getLanguageFromFilename, FUNCTION_NODE_TYPES, extractFunctionName, isBuiltInOrNoise, getDefinitionNodeFromCaptures, findEnclosingClassId, extractMethodSignature, countCallArguments, inferCallForm, extractReceiverName, extractReceiverNode, extractMixedChain, } from '../utils.js';
+import { getLanguageFromFilename, FUNCTION_NODE_TYPES, extractFunctionName, isBuiltInOrNoise, getDefinitionNodeFromCaptures, findEnclosingClassId, getLabelFromCaptures, extractMethodSignature, countCallArguments, inferCallForm, extractReceiverName, extractReceiverNode, extractMixedChain, } from '../utils.js';
 import { buildTypeEnv } from '../type-env.js';
 import { isNodeExported } from '../export-detection.js';
 import { detectFrameworkFromAST } from '../framework-detection.js';
 import { typeConfigs } from '../type-extractors/index.js';
 import { generateId } from '../../../lib/utils.js';
-import { extractNamedBindings } from '../named-binding-extraction.js';
-import { appendKotlinWildcard } from '../resolvers/index.js';
+import { namedBindingExtractors, preprocessImportPath } from '../import-resolution.js';
 import { callRouters } from '../call-routing.js';
 import { extractPropertyDeclaredType } from '../type-extractors/shared.js';
 // ============================================================================
@@ -97,61 +96,7 @@ const findEnclosingFunctionId = (node, filePath) => {
     }
     return null;
 };
-// ============================================================================
-// Label detection from capture map
-// ============================================================================
-const getLabelFromCaptures = (captureMap) => {
-    // Skip imports (handled separately) and calls
-    if (captureMap['import'] || captureMap['call'])
-        return null;
-    if (!captureMap['name'])
-        return null;
-    if (captureMap['definition.function'])
-        return 'Function';
-    if (captureMap['definition.class'])
-        return 'Class';
-    if (captureMap['definition.interface'])
-        return 'Interface';
-    if (captureMap['definition.method'])
-        return 'Method';
-    if (captureMap['definition.struct'])
-        return 'Struct';
-    if (captureMap['definition.enum'])
-        return 'Enum';
-    if (captureMap['definition.namespace'])
-        return 'Namespace';
-    if (captureMap['definition.module'])
-        return 'Module';
-    if (captureMap['definition.trait'])
-        return 'Trait';
-    if (captureMap['definition.impl'])
-        return 'Impl';
-    if (captureMap['definition.type'])
-        return 'TypeAlias';
-    if (captureMap['definition.const'])
-        return 'Const';
-    if (captureMap['definition.static'])
-        return 'Static';
-    if (captureMap['definition.typedef'])
-        return 'Typedef';
-    if (captureMap['definition.macro'])
-        return 'Macro';
-    if (captureMap['definition.union'])
-        return 'Union';
-    if (captureMap['definition.property'])
-        return 'Property';
-    if (captureMap['definition.record'])
-        return 'Record';
-    if (captureMap['definition.delegate'])
-        return 'Delegate';
-    if (captureMap['definition.annotation'])
-        return 'Annotation';
-    if (captureMap['definition.constructor'])
-        return 'Constructor';
-    if (captureMap['definition.template'])
-        return 'Template';
-    return 'CodeElement';
-};
+// Label detection moved to shared getLabelFromCaptures in utils.ts
 // DEFINITION_CAPTURE_KEYS and getDefinitionNodeFromCaptures imported from ../utils.js
 // ============================================================================
 // Process a batch of files
@@ -167,6 +112,7 @@ const processBatch = (files, onProgress) => {
         heritage: [],
         routes: [],
         constructorBindings: [],
+        typeEnvBindings: [],
         skippedLanguages: {},
         fileCount: 0,
     };
@@ -727,13 +673,6 @@ const processFileGroup = (files, language, queryString, result, onFileProcessed)
         }
         result.fileCount++;
         onFileProcessed?.();
-        // Build per-file type environment + constructor bindings in a single AST walk.
-        // Constructor bindings are verified against the SymbolTable in processCallsFromExtracted.
-        const typeEnv = buildTypeEnv(tree, language);
-        const callRouter = callRouters[language];
-        if (typeEnv.constructorBindings.length > 0) {
-            result.constructorBindings.push({ filePath: file.path, bindings: [...typeEnv.constructorBindings] });
-        }
         let matches;
         try {
             matches = query.matches(tree.rootNode);
@@ -742,6 +681,51 @@ const processFileGroup = (files, language, queryString, result, onFileProcessed)
             console.warn(`Query execution failed for ${file.path}: ${err instanceof Error ? err.message : String(err)}`);
             continue;
         }
+        // Pre-pass: extract heritage from query matches to build parentMap for buildTypeEnv.
+        // Heritage edges (EXTENDS/IMPLEMENTS) are created by heritage-processor which runs
+        // in PARALLEL with call-processor, so the graph edges don't exist when buildTypeEnv
+        // runs. This pre-pass makes parent class information available for type resolution.
+        const fileParentMap = new Map();
+        for (const match of matches) {
+            const captureMap = {};
+            for (const c of match.captures) {
+                captureMap[c.name] = c.node;
+            }
+            if (captureMap['heritage.class'] && captureMap['heritage.extends']) {
+                const className = captureMap['heritage.class'].text;
+                const parentName = captureMap['heritage.extends'].text;
+                // Skip Go named fields (only anonymous fields are struct embedding)
+                const extendsNode = captureMap['heritage.extends'];
+                const fieldDecl = extendsNode.parent;
+                if (fieldDecl?.type === 'field_declaration' && fieldDecl.childForFieldName('name'))
+                    continue;
+                let parents = fileParentMap.get(className);
+                if (!parents) {
+                    parents = [];
+                    fileParentMap.set(className, parents);
+                }
+                if (!parents.includes(parentName))
+                    parents.push(parentName);
+            }
+        }
+        // Build per-file type environment + constructor bindings in a single AST walk.
+        // Constructor bindings are verified against the SymbolTable in processCallsFromExtracted.
+        const parentMap = fileParentMap;
+        const typeEnv = buildTypeEnv(tree, language, { parentMap });
+        const callRouter = callRouters[language];
+        if (typeEnv.constructorBindings.length > 0) {
+            result.constructorBindings.push({ filePath: file.path, bindings: [...typeEnv.constructorBindings] });
+        }
+        // Extract file-scope bindings for ExportedTypeMap (closes worker/sequential quality gap).
+        // Sequential path uses collectExportedBindings(typeEnv) directly; worker path serializes
+        // these bindings so the main thread can merge them into ExportedTypeMap.
+        const fileScope = typeEnv.env.get('');
+        if (fileScope && fileScope.size > 0) {
+            const bindings = [];
+            for (const [name, type] of fileScope)
+                bindings.push([name, type]);
+            result.typeEnvBindings.push({ filePath: file.path, bindings });
+        }
         for (const match of matches) {
             const captureMap = {};
             for (const c of match.captures) {
@@ -749,10 +733,11 @@ const processFileGroup = (files, language, queryString, result, onFileProcessed)
             }
             // Extract import paths before skipping
             if (captureMap['import'] && captureMap['import.source']) {
-                const rawImportPath = language === SupportedLanguages.Kotlin
-                    ? appendKotlinWildcard(captureMap['import.source'].text.replace(/['"<>]/g, ''), captureMap['import'])
-                    : captureMap['import.source'].text.replace(/['"<>]/g, '');
-                const namedBindings = extractNamedBindings(captureMap['import'], language);
+                const rawImportPath = preprocessImportPath(captureMap['import.source'].text, captureMap['import'], language);
+                if (!rawImportPath)
+                    continue;
+                const extractor = namedBindingExtractors[language];
+                const namedBindings = extractor ? extractor(captureMap['import']) : undefined;
                 result.imports.push({
                     filePath: file.path,
                     rawImportPath,
@@ -941,24 +926,9 @@ const processFileGroup = (files, language, queryString, result, onFileProcessed)
                     continue;
                 }
             }
-            const nodeLabel = getLabelFromCaptures(captureMap);
+            const nodeLabel = getLabelFromCaptures(captureMap, language);
             if (!nodeLabel)
                 continue;
-            // C/C++: @definition.function is broad and also matches inline class methods (inside
-            // a class/struct body). Those are already captured by @definition.method, so skip
-            // the duplicate Function entry to prevent double-indexing in globalIndex.
-            if ((language === SupportedLanguages.CPlusPlus || language === SupportedLanguages.C) &&
-                nodeLabel === 'Function') {
-                let ancestor = captureMap['definition.function']?.parent;
-                while (ancestor) {
-                    if (ancestor.type === 'class_specifier' || ancestor.type === 'struct_specifier') {
-                        break; // inside a class body — duplicate of @definition.method
-                    }
-                    ancestor = ancestor.parent;
-                }
-                if (ancestor)
-                    continue; // found a class/struct ancestor → skip
-            }
             const nameNode = captureMap['name'];
             // Synthesize name for constructors without explicit @name capture (e.g. Swift init)
             if (!nameNode && nodeLabel !== 'Constructor')
@@ -980,11 +950,15 @@ const processFileGroup = (files, language, queryString, result, onFileProcessed)
                 ? detectFrameworkFromAST(language, (definitionNode.text || '').slice(0, 300))
                 : null;
             let parameterCount;
+            let requiredParameterCount;
+            let parameterTypes;
             let returnType;
             let declaredType;
             if (nodeLabel === 'Function' || nodeLabel === 'Method' || nodeLabel === 'Constructor') {
                 const sig = extractMethodSignature(definitionNode);
                 parameterCount = sig.parameterCount;
+                requiredParameterCount = sig.requiredParameterCount;
+                parameterTypes = sig.parameterTypes;
                 returnType = sig.returnType;
                 // Language-specific return type fallback (e.g. Ruby YARD @return [Type])
                 // Also upgrades uninformative AST types like PHP `array` with PHPDoc `@return User[]`
@@ -1018,6 +992,8 @@ const processFileGroup = (files, language, queryString, result, onFileProcessed)
                     } : {}),
                     ...(description !== undefined ? { description } : {}),
                     ...(parameterCount !== undefined ? { parameterCount } : {}),
+                    ...(requiredParameterCount !== undefined ? { requiredParameterCount } : {}),
+                    ...(parameterTypes !== undefined ? { parameterTypes } : {}),
                     ...(returnType !== undefined ? { returnType } : {}),
                 },
             });
@@ -1031,6 +1007,8 @@ const processFileGroup = (files, language, queryString, result, onFileProcessed)
                 nodeId,
                 type: nodeLabel,
                 ...(parameterCount !== undefined ? { parameterCount } : {}),
+                ...(requiredParameterCount !== undefined ? { requiredParameterCount } : {}),
+                ...(parameterTypes !== undefined ? { parameterTypes } : {}),
                 ...(returnType !== undefined ? { returnType } : {}),
                 ...(declaredType !== undefined ? { declaredType } : {}),
                 ...(enclosingClassId ? { ownerId: enclosingClassId } : {}),
@@ -1071,7 +1049,7 @@ const processFileGroup = (files, language, queryString, result, onFileProcessed)
 /** Accumulated result across sub-batches */
 let accumulated = {
     nodes: [], relationships: [], symbols: [],
-    imports: [], calls: [], assignments: [], heritage: [], routes: [], constructorBindings: [], skippedLanguages: {}, fileCount: 0,
+    imports: [], calls: [], assignments: [], heritage: [], routes: [], constructorBindings: [], typeEnvBindings: [], skippedLanguages: {}, fileCount: 0,
 };
 let cumulativeProcessed = 0;
 const mergeResult = (target, src) => {
@@ -1084,6 +1062,7 @@ const mergeResult = (target, src) => {
     target.heritage.push(...src.heritage);
     target.routes.push(...src.routes);
     target.constructorBindings.push(...src.constructorBindings);
+    target.typeEnvBindings.push(...src.typeEnvBindings);
     for (const [lang, count] of Object.entries(src.skippedLanguages)) {
         target.skippedLanguages[lang] = (target.skippedLanguages[lang] || 0) + count;
     }
@@ -1106,7 +1085,7 @@ parentPort.on('message', (msg) => {
         if (msg && msg.type === 'flush') {
             parentPort.postMessage({ type: 'result', data: accumulated });
             // Reset for potential reuse
-            accumulated = { nodes: [], relationships: [], symbols: [], imports: [], calls: [], assignments: [], heritage: [], routes: [], constructorBindings: [], skippedLanguages: {}, fileCount: 0 };
+            accumulated = { nodes: [], relationships: [], symbols: [], imports: [], calls: [], assignments: [], heritage: [], routes: [], constructorBindings: [], typeEnvBindings: [], skippedLanguages: {}, fileCount: 0 };
             cumulativeProcessed = 0;
             return;
         }

package/dist/core/lbug/csv-generator.js

@@ -208,6 +208,8 @@ export const streamAllCSVsToDisk = async (graph, repoPath, csvDir) => {
     const codeElemWriter = new BufferedCSVWriter(path.join(csvDir, 'codeelement.csv'), codeElementHeader);
     const communityWriter = new BufferedCSVWriter(path.join(csvDir, 'community.csv'), 'id,label,heuristicLabel,keywords,description,enrichedBy,cohesion,symbolCount');
     const processWriter = new BufferedCSVWriter(path.join(csvDir, 'process.csv'), 'id,label,heuristicLabel,processType,stepCount,communities,entryPointId,terminalId');
+    // Section nodes have an extra 'level' column
+    const sectionWriter = new BufferedCSVWriter(path.join(csvDir, 'section.csv'), 'id,name,filePath,startLine,endLine,level,content,description');
     // Multi-language node types share the same CSV shape (no isExported column)
     const multiLangHeader = 'id,name,filePath,startLine,endLine,content,description';
     const MULTI_LANG_TYPES = ['Struct', 'Enum', 'Macro', 'Typedef', 'Union', 'Namespace', 'Trait', 'Impl',
@@ -292,6 +294,20 @@ export const streamAllCSVsToDisk = async (graph, repoPath, csvDir) => {
                 ].join(','));
                 break;
             }
+            case 'Section': {
+                const content = await extractContent(node, contentCache);
+                await sectionWriter.addRow([
+                    escapeCSVField(node.id),
+                    escapeCSVField(node.properties.name || ''),
+                    escapeCSVField(node.properties.filePath || ''),
+                    escapeCSVNumber(node.properties.startLine, -1),
+                    escapeCSVNumber(node.properties.endLine, -1),
+                    escapeCSVNumber(node.properties.level, 1),
+                    escapeCSVField(content),
+                    escapeCSVField(node.properties.description || ''),
+                ].join(','));
+                break;
+            }
             default: {
                 // Code element nodes (Function, Class, Interface, CodeElement)
                 const writer = codeWriterMap[node.label];
@@ -329,7 +345,7 @@ export const streamAllCSVsToDisk = async (graph, repoPath, csvDir) => {
         }
     }
     // Finish all node writers
-    const allWriters = [fileWriter, folderWriter, functionWriter, classWriter, interfaceWriter, methodWriter, codeElemWriter, communityWriter, processWriter, ...multiLangWriters.values()];
+    const allWriters = [fileWriter, folderWriter, functionWriter, classWriter, interfaceWriter, methodWriter, codeElemWriter, communityWriter, processWriter, sectionWriter, ...multiLangWriters.values()];
     await Promise.all(allWriters.map(w => w.finish()));
     // --- Stream relationship CSV ---
     const relCsvPath = path.join(csvDir, 'relations.csv');
@@ -353,6 +369,7 @@ export const streamAllCSVsToDisk = async (graph, repoPath, csvDir) => {
         ['Interface', interfaceWriter], ['Method', methodWriter],
         ['CodeElement', codeElemWriter],
         ['Community', communityWriter], ['Process', processWriter],
+        ['Section', sectionWriter],
         ...Array.from(multiLangWriters.entries()).map(([name, w]) => [name, w]),
     ];
     for (const [name, writer] of tableMap) {

package/dist/core/lbug/lbug-adapter.d.ts

@@ -2,6 +2,12 @@ import lbug from '@ladybugdb/core';
 import { KnowledgeGraph } from '../graph/types.js';
 /** Expose the current Database for pool adapter reuse in tests. */
 export declare const getDatabase: () => lbug.Database | null;
+/**
+ * Return true when the error message indicates that another process holds
+ * an exclusive lock on the LadybugDB file (e.g. `gitnexus analyze` or
+ * `gitnexus serve` running at the same time).
+ */
+export declare const isDbBusyError: (err: unknown) => boolean;
 export declare const initLbug: (dbPath: string) => Promise<{
     db: lbug.Database;
     conn: lbug.Connection;
@@ -9,6 +15,10 @@ export declare const initLbug: (dbPath: string) => Promise<{
 /**
  * Execute multiple queries against one repo DB atomically.
  * While the callback runs, no other request can switch the active DB.
+ *
+ * Automatically retries up to DB_LOCK_RETRY_ATTEMPTS times when the
+ * database is busy (e.g. `gitnexus analyze` holds the write lock).
+ * Each retry waits DB_LOCK_RETRY_DELAY_MS * attempt milliseconds.
  */
 export declare const withLbugDb: <T>(dbPath: string, operation: () => Promise<T>) => Promise<T>;
 export type LbugProgressCallback = (message: string) => void;

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

@@ -14,6 +14,22 @@ export const getDatabase = () => db;
 // Global session lock for operations that touch module-level lbug globals.
 // This guarantees no DB switch can happen while an operation is running.
 let sessionLock = Promise.resolve();
+/** Number of times to retry on a BUSY / lock-held error before giving up. */
+const DB_LOCK_RETRY_ATTEMPTS = 3;
+/** Base back-off in ms between BUSY retries (multiplied by attempt number). */
+const DB_LOCK_RETRY_DELAY_MS = 500;
+/**
+ * Return true when the error message indicates that another process holds
+ * an exclusive lock on the LadybugDB file (e.g. `gitnexus analyze` or
+ * `gitnexus serve` running at the same time).
+ */
+export const isDbBusyError = (err) => {
+    const msg = (err instanceof Error ? err.message : String(err)).toLowerCase();
+    return (msg.includes('busy')
+        || msg.includes('lock')
+        || msg.includes('already in use')
+        || msg.includes('could not set lock'));
+};
 const runWithSessionLock = async (operation) => {
     const previous = sessionLock;
     let release = null;
@@ -35,12 +51,50 @@ export const initLbug = async (dbPath) => {
 /**
  * Execute multiple queries against one repo DB atomically.
  * While the callback runs, no other request can switch the active DB.
+ *
+ * Automatically retries up to DB_LOCK_RETRY_ATTEMPTS times when the
+ * database is busy (e.g. `gitnexus analyze` holds the write lock).
+ * Each retry waits DB_LOCK_RETRY_DELAY_MS * attempt milliseconds.
  */
 export const withLbugDb = async (dbPath, operation) => {
-    return runWithSessionLock(async () => {
-        await ensureLbugInitialized(dbPath);
-        return operation();
-    });
+    let lastError;
+    for (let attempt = 1; attempt <= DB_LOCK_RETRY_ATTEMPTS; attempt++) {
+        try {
+            return await runWithSessionLock(async () => {
+                await ensureLbugInitialized(dbPath);
+                return operation();
+            });
+        }
+        catch (err) {
+            lastError = err;
+            if (!isDbBusyError(err) || attempt === DB_LOCK_RETRY_ATTEMPTS) {
+                throw err;
+            }
+            // Close stale connection inside the session lock to prevent race conditions
+            // with concurrent operations that might acquire the lock between cleanup steps
+            await runWithSessionLock(async () => {
+                try {
+                    if (conn)
+                        await conn.close();
+                }
+                catch { /* best-effort */ }
+                try {
+                    if (db)
+                        await db.close();
+                }
+                catch { /* best-effort */ }
+                conn = null;
+                db = null;
+                currentDbPath = null;
+                ftsLoaded = false;
+            });
+            // Sleep outside the lock — no need to block others while waiting
+            await new Promise(resolve => setTimeout(resolve, DB_LOCK_RETRY_DELAY_MS * attempt));
+        }
+    }
+    // This line is unreachable — the loop either returns or throws inside,
+    // but TypeScript needs an explicit throw to satisfy the return type.
+    throw lastError;
 };
 const ensureLbugInitialized = async (dbPath) => {
     if (conn && currentDbPath === dbPath) {
@@ -323,6 +377,9 @@ const getCopyQuery = (table, filePath) => {
     if (table === 'Process') {
         return `COPY ${t}(id, label, heuristicLabel, processType, stepCount, communities, entryPointId, terminalId) FROM "${filePath}" ${COPY_CSV_OPTS}`;
     }
+    if (table === 'Section') {
+        return `COPY ${t}(id, name, filePath, startLine, endLine, level, content, description) FROM "${filePath}" ${COPY_CSV_OPTS}`;
+    }
     if (table === 'Method') {
         return `COPY ${t}(id, name, filePath, startLine, endLine, isExported, content, description, parameterCount, returnType) FROM "${filePath}" ${COPY_CSV_OPTS}`;
     }
@@ -363,6 +420,10 @@ export const insertNodeToLbug = async (label, properties, dbPath) => {
         else if (label === 'Folder') {
             query = `CREATE (n:Folder {id: ${escapeValue(properties.id)}, name: ${escapeValue(properties.name)}, filePath: ${escapeValue(properties.filePath)}})`;
         }
+        else if (label === 'Section') {
+            const descPart = properties.description ? `, description: ${escapeValue(properties.description)}` : '';
+            query = `CREATE (n:Section {id: ${escapeValue(properties.id)}, name: ${escapeValue(properties.name)}, filePath: ${escapeValue(properties.filePath)}, startLine: ${properties.startLine || 0}, endLine: ${properties.endLine || 0}, level: ${properties.level || 1}, content: ${escapeValue(properties.content || '')}${descPart}})`;
+        }
         else if (TABLES_WITH_EXPORTED.has(label)) {
             const descPart = properties.description ? `, description: ${escapeValue(properties.description)}` : '';
             query = `CREATE (n:${t} {id: ${escapeValue(properties.id)}, name: ${escapeValue(properties.name)}, filePath: ${escapeValue(properties.filePath)}, startLine: ${properties.startLine || 0}, endLine: ${properties.endLine || 0}, isExported: ${!!properties.isExported}, content: ${escapeValue(properties.content || '')}${descPart}})`;
@@ -438,6 +499,10 @@ export const batchInsertNodesToLbug = async (nodes, dbPath) => {
                 else if (label === 'Folder') {
                     query = `MERGE (n:Folder {id: ${escapeValue(properties.id)}}) SET n.name = ${escapeValue(properties.name)}, n.filePath = ${escapeValue(properties.filePath)}`;
                 }
+                else if (label === 'Section') {
+                    const descPart = properties.description ? `, n.description = ${escapeValue(properties.description)}` : '';
+                    query = `MERGE (n:Section {id: ${escapeValue(properties.id)}}) SET n.name = ${escapeValue(properties.name)}, n.filePath = ${escapeValue(properties.filePath)}, n.startLine = ${properties.startLine || 0}, n.endLine = ${properties.endLine || 0}, n.level = ${properties.level || 1}, n.content = ${escapeValue(properties.content || '')}${descPart}`;
+                }
                 else if (TABLES_WITH_EXPORTED.has(label)) {
                     const descPart = properties.description ? `, n.description = ${escapeValue(properties.description)}` : '';
                     query = `MERGE (n:${t} {id: ${escapeValue(properties.id)}}) SET n.name = ${escapeValue(properties.name)}, n.filePath = ${escapeValue(properties.filePath)}, n.startLine = ${properties.startLine || 0}, n.endLine = ${properties.endLine || 0}, n.isExported = ${!!properties.isExported}, n.content = ${escapeValue(properties.content || '')}${descPart}`;

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

@@ -8,7 +8,7 @@
  * This allows LLMs to write natural Cypher queries like:
  *   MATCH (f:Function)-[r:CodeRelation {type: 'CALLS'}]->(g:Function) RETURN f, g
  */
-export declare const NODE_TABLES: readonly ["File", "Folder", "Function", "Class", "Interface", "Method", "CodeElement", "Community", "Process", "Struct", "Enum", "Macro", "Typedef", "Union", "Namespace", "Trait", "Impl", "TypeAlias", "Const", "Static", "Property", "Record", "Delegate", "Annotation", "Constructor", "Template", "Module"];
+export declare const NODE_TABLES: readonly ["File", "Folder", "Function", "Class", "Interface", "Method", "CodeElement", "Community", "Process", "Section", "Struct", "Enum", "Macro", "Typedef", "Union", "Namespace", "Trait", "Impl", "TypeAlias", "Const", "Static", "Property", "Record", "Delegate", "Annotation", "Constructor", "Template", "Module"];
 export type NodeTableName = typeof NODE_TABLES[number];
 export declare const REL_TABLE_NAME = "CodeRelation";
 export declare const REL_TYPES: readonly ["CONTAINS", "DEFINES", "IMPORTS", "CALLS", "EXTENDS", "IMPLEMENTS", "HAS_METHOD", "HAS_PROPERTY", "ACCESSES", "OVERRIDES", "MEMBER_OF", "STEP_IN_PROCESS"];
@@ -41,8 +41,10 @@ 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 Function TO `Const`,\n  FROM Function TO `Typedef`,\n  FROM Function TO `Union`,\n  FROM Function TO `Property`,\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 `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 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  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)";
+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 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 `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 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  type STRING,\n  confidence DOUBLE,\n  reason STRING,\n  step INT32\n)";
+export declare const EMBEDDING_DIMS: number;
+export declare const EMBEDDING_SCHEMA: string;
 /**
  * Create vector index for semantic search
  * Uses HNSW (Hierarchical Navigable Small World) algorithm with cosine similarity

package/dist/core/lbug/schema.js

@@ -12,7 +12,7 @@
 // NODE TABLE NAMES
 // ============================================================================
 export const NODE_TABLES = [
-    'File', 'Folder', 'Function', 'Class', 'Interface', 'Method', 'CodeElement', 'Community', 'Process',
+    'File', 'Folder', 'Function', 'Class', 'Interface', 'Method', 'CodeElement', 'Community', 'Process', 'Section',
     // Multi-language support
     'Struct', 'Enum', 'Macro', 'Typedef', 'Union', 'Namespace', 'Trait', 'Impl',
     'TypeAlias', 'Const', 'Static', 'Property', 'Record', 'Delegate', 'Annotation', 'Constructor', 'Template', 'Module'
@@ -171,6 +171,19 @@ export const ANNOTATION_SCHEMA = CODE_ELEMENT_BASE('Annotation');
 export const CONSTRUCTOR_SCHEMA = CODE_ELEMENT_BASE('Constructor');
 export const TEMPLATE_SCHEMA = CODE_ELEMENT_BASE('Template');
 export const MODULE_SCHEMA = CODE_ELEMENT_BASE('Module');
+// Markdown heading sections
+export const SECTION_SCHEMA = `
+CREATE NODE TABLE Section (
+  id STRING,
+  name STRING,
+  filePath STRING,
+  startLine INT64,
+  endLine INT64,
+  level INT64,
+  content STRING,
+  description STRING,
+  PRIMARY KEY (id)
+)`;
 // ============================================================================
 // RELATION TABLE SCHEMA
 // Single table with 'type' property - connects all node tables
@@ -202,6 +215,7 @@ CREATE REL TABLE ${REL_TABLE_NAME} (
   FROM File TO \`Constructor\`,
   FROM File TO \`Template\`,
   FROM File TO \`Module\`,
+  FROM File TO Section,
   FROM Folder TO Folder,
   FROM Folder TO File,
   FROM Function TO Function,
@@ -266,6 +280,8 @@ CREATE REL TABLE ${REL_TABLE_NAME} (
   FROM \`Template\` TO Interface,
   FROM \`Template\` TO \`Constructor\`,
   FROM \`Module\` TO \`Module\`,
+  FROM Section TO Section,
+  FROM Section TO File,
   FROM CodeElement TO Community,
   FROM Interface TO Community,
   FROM Interface TO Function,
@@ -373,10 +389,16 @@ CREATE REL TABLE ${REL_TABLE_NAME} (
 // EMBEDDING TABLE SCHEMA
 // Separate table for vector storage to avoid copy-on-write overhead
 // ============================================================================
+/** Embedding vector dimensions. Default 384 (snowflake-arctic-embed-xs). */
+const _rawDims = parseInt(process.env.GITNEXUS_EMBEDDING_DIMS ?? '384', 10);
+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;
 export const EMBEDDING_SCHEMA = `
 CREATE NODE TABLE ${EMBEDDING_TABLE_NAME} (
   nodeId STRING,
-  embedding FLOAT[384],
+  embedding FLOAT[${EMBEDDING_DIMS}],
   PRIMARY KEY (nodeId)
 )`;
 /**
@@ -419,6 +441,8 @@ export const NODE_SCHEMA_QUERIES = [
     CONSTRUCTOR_SCHEMA,
     TEMPLATE_SCHEMA,
     MODULE_SCHEMA,
+    // Markdown support
+    SECTION_SCHEMA,
 ];
 export const REL_SCHEMA_QUERIES = [
     RELATION_SCHEMA,