gitnexus 1.6.2-rc.2 → 1.6.2-rc.20

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

@@ -3,44 +3,76 @@
  *
  * Orchestrates the background embedding process:
  * 1. Query embeddable nodes from LadybugDB
- * 2. Generate text representations
- * 3. Batch embed using transformers.js
- * 4. Update LadybugDB with embeddings
+ * 2. Generate text representations with enriched metadata
+ * 3. Chunk long nodes, batch embed
+ * 4. Update LadybugDB with chunk-aware embeddings
  * 5. Create vector index for semantic search
  */
+import { createHash } from 'crypto';
 import { initEmbedder, embedBatch, embedText, embeddingToArray, isEmbedderReady, } from './embedder.js';
-import { generateBatchEmbeddingTexts } from './text-generator.js';
-import { DEFAULT_EMBEDDING_CONFIG, EMBEDDABLE_LABELS, } from './types.js';
+import { generateEmbeddingText } from './text-generator.js';
+import { chunkNode, characterChunk } from './chunker.js';
+import { extractStructuralNames } from './structural-extractor.js';
+import { DEFAULT_EMBEDDING_CONFIG, EMBEDDABLE_LABELS, isShortLabel, LABELS_WITH_EXPORTED, STRUCTURAL_LABELS, collectBestChunks, } from './types.js';
+import { EMBEDDING_TABLE_NAME, EMBEDDING_INDEX_NAME, CREATE_VECTOR_INDEX_QUERY, STALE_HASH_SENTINEL, } from '../lbug/schema.js';
+import { loadVectorExtension } from '../lbug/lbug-adapter.js';
 const isDev = process.env.NODE_ENV === 'development';
+/**
+ * Compute a stable content fingerprint for an embeddable node.
+ * Used to detect when the underlying text has changed so stale vectors
+ * can be replaced (DELETE-then-INSERT, the Kuzu-sanctioned pattern for
+ * vector-indexed rows).
+ */
+export const contentHashForNode = (node, config = {}) => {
+    // Hash must be deterministic across runs, so exclude methodNames/fieldNames
+    // which are populated during the batch loop via AST extraction.
+    // Using only node.content ensures the hash stays stable.
+    const text = generateEmbeddingText({ ...node, methodNames: undefined, fieldNames: undefined }, node.content, config);
+    return createHash('sha1').update(text).digest('hex');
+};
 /**
  * Query all embeddable nodes from LadybugDB
- * Uses table-specific queries (File has different schema than code elements)
+ * Uses table-specific queries for different label types
  */
 const queryEmbeddableNodes = async (executeQuery) => {
     const allNodes = [];
-    // Query each embeddable table with table-specific columns
     for (const label of EMBEDDABLE_LABELS) {
         try {
             let query;
-            if (label === 'File') {
-                // File nodes don't have startLine/endLine
+            if (label === 'Method') {
+                // Method has parameterCount and returnType
                 query = `
-          MATCH (n:File)
-          RETURN n.id AS id, n.name AS name, 'File' AS label, 
-                 n.filePath AS filePath, n.content AS content
+          MATCH (n:Method)
+          RETURN n.id AS id, n.name AS name, 'Method' AS label,
+                 n.filePath AS filePath, n.content AS content,
+                 n.startLine AS startLine, n.endLine AS endLine,
+                 n.isExported AS isExported, n.description AS description,
+                 n.parameterCount AS parameterCount, n.returnType AS returnType
+        `;
+            }
+            else if (LABELS_WITH_EXPORTED.has(label)) {
+                // Function, Class, Interface have isExported and description
+                query = `
+          MATCH (n:\`${label}\`)
+          RETURN n.id AS id, n.name AS name, '${label}' AS label,
+                 n.filePath AS filePath, n.content AS content,
+                 n.startLine AS startLine, n.endLine AS endLine,
+                 n.isExported AS isExported, n.description AS description
         `;
             }
             else {
-                // Code elements have startLine/endLine
+                // Multi-language tables (Struct, Enum, etc.) — have description but no isExported
                 query = `
-          MATCH (n:${label})
-          RETURN n.id AS id, n.name AS name, '${label}' AS label, 
+          MATCH (n:\`${label}\`)
+          RETURN n.id AS id, n.name AS name, '${label}' AS label,
                  n.filePath AS filePath, n.content AS content,
-                 n.startLine AS startLine, n.endLine AS endLine
+                 n.startLine AS startLine, n.endLine AS endLine,
+                 n.description AS description
         `;
             }
             const rows = await executeQuery(query);
             for (const row of rows) {
+                const hasExportedColumn = label === 'Method' || LABELS_WITH_EXPORTED.has(label);
                 allNodes.push({
                     id: row.id ?? row[0],
                     name: row.name ?? row[1],
@@ -49,11 +81,18 @@ const queryEmbeddableNodes = async (executeQuery) => {
                     content: row.content ?? row[4] ?? '',
                     startLine: row.startLine ?? row[5],
                     endLine: row.endLine ?? row[6],
+                    isExported: hasExportedColumn ? (row.isExported ?? row[7]) : undefined,
+                    description: row.description ?? (hasExportedColumn ? row[8] : row[7]),
+                    ...(label === 'Method'
+                        ? {
+                            parameterCount: row.parameterCount ?? row[9],
+                            returnType: row.returnType ?? row[10],
+                        }
+                        : {}),
                 });
             }
         }
         catch (error) {
-            // Table might not exist or be empty, continue
             if (isDev) {
                 console.warn(`Query for ${label} nodes failed:`, error);
             }
@@ -62,42 +101,36 @@ const queryEmbeddableNodes = async (executeQuery) => {
     return allNodes;
 };
 /**
- * Batch INSERT embeddings into separate CodeEmbedding table
- * Using a separate lightweight table avoids copy-on-write overhead
- * that occurs when UPDATEing nodes with large content fields
+ * Batch INSERT chunk-aware embeddings into CodeEmbedding table
  */
-const batchInsertEmbeddings = async (executeWithReusedStatement, updates) => {
-    // MERGE instead of CREATE — idempotent, handles concurrent analyzes and partial prior runs
-    const cypher = `MERGE (e:CodeEmbedding {nodeId: $nodeId}) SET e.embedding = $embedding`;
-    const paramsList = updates.map((u) => ({ nodeId: u.id, embedding: u.embedding }));
+export const batchInsertEmbeddings = async (executeWithReusedStatement, updates) => {
+    const cypher = `CREATE (e:${EMBEDDING_TABLE_NAME} {id: $id, nodeId: $nodeId, chunkIndex: $chunkIndex, startLine: $startLine, endLine: $endLine, embedding: $embedding, contentHash: $contentHash})`;
+    const paramsList = updates.map((u) => ({
+        id: `${u.nodeId}:${u.chunkIndex}`,
+        nodeId: u.nodeId,
+        chunkIndex: u.chunkIndex,
+        startLine: u.startLine,
+        endLine: u.endLine,
+        embedding: u.embedding,
+        contentHash: u.contentHash ?? STALE_HASH_SENTINEL,
+    }));
     await executeWithReusedStatement(cypher, paramsList);
 };
 /**
  * Create the vector index for semantic search
- * Now indexes the separate CodeEmbedding table
+
+ * Now indexes the separate CodeEmbedding table.
+ * Delegates extension loading to lbug-adapter's loadVectorExtension(),
+ * which owns the VECTOR extension lifecycle and state tracking.
+
  */
-let vectorExtensionLoaded = false;
 const createVectorIndex = async (executeQuery) => {
-    // LadybugDB v0.15+ requires explicit VECTOR extension loading (once per session)
-    if (!vectorExtensionLoaded) {
-        try {
-            await executeQuery('INSTALL VECTOR');
-            await executeQuery('LOAD EXTENSION VECTOR');
-            vectorExtensionLoaded = true;
-        }
-        catch {
-            // Extension may already be loaded — CREATE_VECTOR_INDEX will fail clearly if not
-            vectorExtensionLoaded = true;
-        }
-    }
-    const cypher = `
-    CALL CREATE_VECTOR_INDEX('CodeEmbedding', 'code_embedding_idx', 'embedding', metric := 'cosine')
-  `;
+    // Delegate to the adapter which tracks loaded state and handles DB reconnect resets
+    await loadVectorExtension();
     try {
-        await executeQuery(cypher);
+        await executeQuery(CREATE_VECTOR_INDEX_QUERY);
     }
     catch (error) {
-        // Index might already exist
         if (isDev) {
             console.warn('Vector index creation warning:', error);
         }
@@ -111,8 +144,13 @@ const createVectorIndex = async (executeQuery) => {
  * @param onProgress - Callback for progress updates
  * @param config - Optional configuration override
  * @param skipNodeIds - Optional set of node IDs that already have embeddings (incremental mode)
+ * @param context - Optional repo/server context for metadata enrichment
+ * @param existingEmbeddings - Optional map of nodeId → contentHash for incremental mode.
+ *        Nodes whose hash matches are skipped; nodes with a changed hash are DELETE'd
+ *        and re-embedded; nodes not in the map are embedded fresh.
+
  */
-export const runEmbeddingPipeline = async (executeQuery, executeWithReusedStatement, onProgress, config = {}, skipNodeIds) => {
+export const runEmbeddingPipeline = async (executeQuery, executeWithReusedStatement, onProgress, config = {}, skipNodeIds, context, existingEmbeddings) => {
     const finalConfig = { ...DEFAULT_EMBEDDING_CONFIG, ...config };
     try {
         // Phase 1: Load embedding model
@@ -141,12 +179,57 @@ export const runEmbeddingPipeline = async (executeQuery, executeWithReusedStatem
         }
         // Phase 2: Query embeddable nodes
         let nodes = await queryEmbeddableNodes(executeQuery);
-        // Incremental mode: filter out nodes that already have embeddings
-        if (skipNodeIds && skipNodeIds.size > 0) {
+        // Apply context metadata
+        if (context?.repoName) {
+            for (const node of nodes) {
+                node.repoName = context.repoName;
+                node.serverName = context.serverName;
+            }
+        }
+        // Incremental mode: compare content hashes, delete stale rows, skip fresh ones.
+        // Computed hashes for stale nodes are cached so batchInsertEmbeddings can reuse them
+        // (avoids double computation).
+        const computedStaleHashes = new Map();
+        if (existingEmbeddings && existingEmbeddings.size > 0) {
             const beforeCount = nodes.length;
-            nodes = nodes.filter((n) => !skipNodeIds.has(n.id));
+            const staleNodeIds = [];
+            nodes = nodes.filter((n) => {
+                const existingHash = existingEmbeddings.get(n.id);
+                if (existingHash === undefined) {
+                    // New node — needs embedding
+                    return true;
+                }
+                const currentHash = contentHashForNode(n, finalConfig);
+                if (currentHash !== existingHash) {
+                    // Content changed — cache hash for reuse during insert, mark for DELETE + re-embed
+                    computedStaleHashes.set(n.id, currentHash);
+                    staleNodeIds.push(n.id);
+                    return true;
+                }
+                // Hash matches — skip (fresh); no need to cache hash for skipped nodes
+                return false;
+            });
+            // DELETE stale embedding rows so they can be re-inserted
+            // (Kuzu forbids SET on vector-indexed properties; DELETE-then-INSERT is the sanctioned pattern)
+            if (staleNodeIds.length > 0) {
+                if (isDev) {
+                    console.log(`🔄 Deleting ${staleNodeIds.length} stale embedding rows for re-embed`);
+                }
+                try {
+                    await executeWithReusedStatement(`MATCH (e:${EMBEDDING_TABLE_NAME} {nodeId: $nodeId}) DELETE e`, staleNodeIds.map((nodeId) => ({ nodeId })));
+                }
+                catch (err) {
+                    // "does not exist" = rows already gone — safe to proceed.
+                    // All other errors risk vector-index corruption (Kuzu requires DELETE-before-INSERT
+                    // for vector-indexed properties) — propagate so the pipeline aborts cleanly.
+                    const msg = err instanceof Error ? err.message : String(err);
+                    if (!msg.includes('does not exist')) {
+                        throw new Error(`[embed] Failed to delete stale embedding rows — aborting to prevent vector-index corruption: ${msg}`);
+                    }
+                }
+            }
             if (isDev) {
-                console.log(`📦 Incremental embeddings: ${beforeCount} total, ${skipNodeIds.size} cached, ${nodes.length} to embed`);
+                console.log(`📦 Incremental embeddings: ${beforeCount} total, ${existingEmbeddings.size} cached, ${staleNodeIds.length} stale, ${nodes.length} to embed`);
             }
         }
         const totalNodes = nodes.length;
@@ -154,6 +237,10 @@ export const runEmbeddingPipeline = async (executeQuery, executeWithReusedStatem
             console.log(`📊 Found ${totalNodes} embeddable nodes`);
         }
         if (totalNodes === 0) {
+            // Ensure the vector index exists even when no new nodes need embedding.
+            // A prior crash or first-time incremental run may have left CodeEmbedding
+            // rows without ever reaching index creation.
+            await createVectorIndex(executeQuery);
             onProgress({
                 phase: 'ready',
                 percent: 100,
@@ -162,42 +249,99 @@ export const runEmbeddingPipeline = async (executeQuery, executeWithReusedStatem
             });
             return;
         }
-        // Phase 3: Batch embed nodes
+        // Phase 3: Chunk + embed nodes
         const batchSize = finalConfig.batchSize;
-        const totalBatches = Math.ceil(totalNodes / batchSize);
+        const chunkSize = finalConfig.chunkSize;
+        const overlap = finalConfig.overlap;
         let processedNodes = 0;
+        let totalChunks = 0;
         onProgress({
             phase: 'embedding',
             percent: 20,
             nodesProcessed: 0,
             totalNodes,
             currentBatch: 0,
-            totalBatches,
+            totalBatches: Math.ceil(totalNodes / batchSize),
         });
-        for (let batchIndex = 0; batchIndex < totalBatches; batchIndex++) {
-            const start = batchIndex * batchSize;
-            const end = Math.min(start + batchSize, totalNodes);
-            const batch = nodes.slice(start, end);
-            // Generate texts for this batch
-            const texts = generateBatchEmbeddingTexts(batch, finalConfig);
-            // Embed the batch
-            const embeddings = await embedBatch(texts);
-            // Update LadybugDB with embeddings
-            const updates = batch.map((node, i) => ({
-                id: node.id,
-                embedding: embeddingToArray(embeddings[i]),
-            }));
-            await batchInsertEmbeddings(executeWithReusedStatement, updates);
+        // Process in batches of nodes
+        for (let batchIndex = 0; batchIndex < totalNodes; batchIndex += batchSize) {
+            const batch = nodes.slice(batchIndex, batchIndex + batchSize);
+            // Chunk each node and generate text
+            const allTexts = [];
+            const allUpdates = [];
+            for (const node of batch) {
+                const isShort = isShortLabel(node.label);
+                const startLine = node.startLine ?? 0;
+                const endLine = node.endLine ?? 0;
+                // Extract structural names for class-like nodes via AST extractors
+                if (!isShort && STRUCTURAL_LABELS.has(node.label)) {
+                    try {
+                        const names = await extractStructuralNames(node.content, node.filePath);
+                        node.methodNames = names.methodNames;
+                        node.fieldNames = names.fieldNames;
+                    }
+                    catch {
+                        // AST extraction failed — names stay undefined, text-generator handles gracefully
+                    }
+                }
+                // Compute content hash once per node (re-use cached value for stale nodes)
+                const hash = computedStaleHashes.get(node.id) ?? contentHashForNode(node, finalConfig);
+                let chunks;
+                if (isShort) {
+                    chunks = [{ text: node.content, chunkIndex: 0, startLine, endLine }];
+                }
+                else {
+                    try {
+                        chunks = await chunkNode(node.label, node.content, node.filePath, startLine, endLine, chunkSize, overlap);
+                    }
+                    catch (chunkErr) {
+                        if (isDev) {
+                            console.warn(`⚠️ AST chunking failed for ${node.label} "${node.name}" (${node.filePath}), falling back to character-based chunking:`, chunkErr);
+                        }
+                        chunks = characterChunk(node.content, startLine, endLine, chunkSize, overlap);
+                    }
+                }
+                for (const chunk of chunks) {
+                    const text = generateEmbeddingText(node, chunk.text, finalConfig);
+                    allTexts.push(text);
+                    allUpdates.push({
+                        nodeId: node.id,
+                        chunkIndex: chunk.chunkIndex,
+                        startLine: chunk.startLine,
+                        endLine: chunk.endLine,
+                        contentHash: hash,
+                    });
+                }
+            }
+            // Embed chunk texts in sub-batches to control memory
+            const EMBED_SUB_BATCH = 8;
+            for (let si = 0; si < allTexts.length; si += EMBED_SUB_BATCH) {
+                const subTexts = allTexts.slice(si, si + EMBED_SUB_BATCH);
+                const subUpdates = allUpdates.slice(si, si + EMBED_SUB_BATCH);
+                let embeddings;
+                try {
+                    embeddings = await embedBatch(subTexts);
+                }
+                catch (embedErr) {
+                    console.error(`❌ embedBatch failed for ${subTexts.length} texts (first: "${subTexts[0]?.substring(0, 80)}..."):`, embedErr);
+                    throw embedErr;
+                }
+                const dbUpdates = subUpdates.map((u, i) => ({
+                    ...u,
+                    embedding: embeddingToArray(embeddings[i]),
+                }));
+                await batchInsertEmbeddings(executeWithReusedStatement, dbUpdates);
+            }
             processedNodes += batch.length;
-            // Report progress (20-90% for embedding phase)
+            totalChunks += allUpdates.length;
             const embeddingProgress = 20 + (processedNodes / totalNodes) * 70;
             onProgress({
                 phase: 'embedding',
                 percent: Math.round(embeddingProgress),
                 nodesProcessed: processedNodes,
                 totalNodes,
-                currentBatch: batchIndex + 1,
-                totalBatches,
+                currentBatch: Math.floor(batchIndex / batchSize) + 1,
+                totalBatches: Math.ceil(totalNodes / batchSize),
             });
         }
         // Phase 4: Create vector index
@@ -211,7 +355,6 @@ export const runEmbeddingPipeline = async (executeQuery, executeWithReusedStatem
             console.log('📇 Creating vector index...');
         }
         await createVectorIndex(executeQuery);
-        // Complete
         onProgress({
             phase: 'ready',
             percent: 100,
@@ -219,7 +362,7 @@ export const runEmbeddingPipeline = async (executeQuery, executeWithReusedStatem
             totalNodes,
         });
         if (isDev) {
-            console.log('✅ Embedding pipeline complete!');
+            console.log(`✅ Embedding pipeline complete! (${totalChunks} chunks from ${totalNodes} nodes)`);
         }
     }
     catch (error) {
@@ -236,68 +379,57 @@ export const runEmbeddingPipeline = async (executeQuery, executeWithReusedStatem
     }
 };
 /**
- * Perform semantic search using the vector index
- *
- * Uses CodeEmbedding table and queries each node table to get metadata
- *
- * @param executeQuery - Function to execute Cypher queries
- * @param query - Search query text
- * @param k - Number of results to return (default: 10)
- * @param maxDistance - Maximum distance threshold (default: 0.5)
- * @returns Array of search results ordered by relevance
+ * Perform semantic search using the vector index with chunk deduplication
  */
 export const semanticSearch = async (executeQuery, query, k = 10, maxDistance = 0.5) => {
     if (!isEmbedderReady()) {
         throw new Error('Embedding model not initialized. Run embedding pipeline first.');
     }
-    // Embed the query
     const queryEmbedding = await embedText(query);
     const queryVec = embeddingToArray(queryEmbedding);
     const queryVecStr = `[${queryVec.join(',')}]`;
-    // Query the vector index on CodeEmbedding to get nodeIds and distances
-    const vectorQuery = `
-    CALL QUERY_VECTOR_INDEX('CodeEmbedding', 'code_embedding_idx', 
-      CAST(${queryVecStr} AS FLOAT[${queryVec.length}]), ${k})
-    YIELD node AS emb, distance
-    WITH emb, distance
-    WHERE distance < ${maxDistance}
-    RETURN emb.nodeId AS nodeId, distance
-    ORDER BY distance
-  `;
-    const embResults = await executeQuery(vectorQuery);
-    if (embResults.length === 0) {
+    const bestChunks = await collectBestChunks(k, async (fetchLimit) => {
+        const vectorQuery = `
+      CALL QUERY_VECTOR_INDEX('${EMBEDDING_TABLE_NAME}', '${EMBEDDING_INDEX_NAME}',
+        CAST(${queryVecStr} AS FLOAT[${queryVec.length}]), ${fetchLimit})
+      YIELD node AS emb, distance
+      WITH emb, distance
+      WHERE distance < ${maxDistance}
+      RETURN emb.nodeId AS nodeId, emb.chunkIndex AS chunkIndex,
+             emb.startLine AS startLine, emb.endLine AS endLine, distance
+      ORDER BY distance
+    `;
+        const embResults = await executeQuery(vectorQuery);
+        return embResults.map((row) => ({
+            nodeId: row.nodeId ?? row[0],
+            chunkIndex: row.chunkIndex ?? row[1] ?? 0,
+            startLine: row.startLine ?? row[2] ?? 0,
+            endLine: row.endLine ?? row[3] ?? 0,
+            distance: row.distance ?? row[4],
+        }));
+    });
+    if (bestChunks.size === 0) {
         return [];
     }
     // Group results by label for batched metadata queries
     const byLabel = new Map();
-    for (const embRow of embResults) {
-        const nodeId = embRow.nodeId ?? embRow[0];
-        const distance = embRow.distance ?? embRow[1];
+    for (const [nodeId, chunk] of Array.from(bestChunks.entries()).slice(0, k)) {
         const labelEndIdx = nodeId.indexOf(':');
         const label = labelEndIdx > 0 ? nodeId.substring(0, labelEndIdx) : 'Unknown';
         if (!byLabel.has(label))
             byLabel.set(label, []);
-        byLabel.get(label).push({ nodeId, distance });
+        byLabel.get(label).push({ nodeId, ...chunk });
     }
     // Batch-fetch metadata per label
     const results = [];
     for (const [label, items] of byLabel) {
         const idList = items.map((i) => `'${i.nodeId.replace(/'/g, "''")}'`).join(', ');
         try {
-            let nodeQuery;
-            if (label === 'File') {
-                nodeQuery = `
-          MATCH (n:File) WHERE n.id IN [${idList}]
-          RETURN n.id AS id, n.name AS name, n.filePath AS filePath
-        `;
-            }
-            else {
-                nodeQuery = `
-          MATCH (n:${label}) WHERE n.id IN [${idList}]
-          RETURN n.id AS id, n.name AS name, n.filePath AS filePath,
-                 n.startLine AS startLine, n.endLine AS endLine
-        `;
-            }
+            const nodeQuery = `
+        MATCH (n:\`${label}\`) WHERE n.id IN [${idList}]
+        RETURN n.id AS id, n.name AS name, n.filePath AS filePath,
+               n.startLine AS startLine, n.endLine AS endLine
+      `;
             const nodeRows = await executeQuery(nodeQuery);
             const rowMap = new Map();
             for (const row of nodeRows) {
@@ -313,8 +445,8 @@ export const semanticSearch = async (executeQuery, query, k = 10, maxDistance =
                         label,
                         filePath: nodeRow.filePath ?? nodeRow[2] ?? '',
                         distance: item.distance,
-                        startLine: label !== 'File' ? (nodeRow.startLine ?? nodeRow[3]) : undefined,
-                        endLine: label !== 'File' ? (nodeRow.endLine ?? nodeRow[4]) : undefined,
+                        startLine: item.startLine,
+                        endLine: item.endLine,
                     });
                 }
             }
@@ -323,26 +455,13 @@ export const semanticSearch = async (executeQuery, query, k = 10, maxDistance =
             // Table might not exist, skip
         }
     }
-    // Re-sort by distance since batch queries may have mixed order
     results.sort((a, b) => a.distance - b.distance);
     return results;
 };
 /**
  * Semantic search with graph expansion (flattened results)
- *
- * Note: With multi-table schema, graph traversal is simplified.
- * Returns semantic matches with their metadata.
- * For full graph traversal, use execute_vector_cypher tool directly.
- *
- * @param executeQuery - Function to execute Cypher queries
- * @param query - Search query text
- * @param k - Number of initial semantic matches (default: 5)
- * @param _hops - Unused (kept for API compatibility).
- * @returns Semantic matches with metadata
  */
 export const semanticSearchWithContext = async (executeQuery, query, k = 5, _hops = 1) => {
-    // For multi-table schema, just return semantic search results
-    // Graph traversal is complex with separate tables - use execute_vector_cypher instead
     const results = await semanticSearch(executeQuery, query, k, 0.5);
     return results.map((r) => ({
         matchId: r.nodeId,

package/dist/core/embeddings/line-index.d.ts

@@ -0,0 +1,7 @@
+export interface ResolvedLineRange {
+    startLine: number;
+    endLine: number;
+}
+export declare const buildLineIndex: (content: string) => Int32Array;
+export declare const lineFromOffset: (lineOffsets: Int32Array, charOffset: number) => number;
+export declare const resolveChunkLines: (lineOffsets: Int32Array, startOffset: number, endOffset: number, baseStartLine: number) => ResolvedLineRange;

package/dist/core/embeddings/line-index.js

@@ -0,0 +1,42 @@
+export const buildLineIndex = (content) => {
+    const offsets = [0];
+    for (let i = 0; i < content.length; i++) {
+        if (content.charCodeAt(i) === 10)
+            offsets.push(i + 1);
+    }
+    return new Int32Array(offsets);
+};
+const clampOffset = (lineOffsets, charOffset) => {
+    if (lineOffsets.length === 0)
+        return 0;
+    const maxOffset = lineOffsets[lineOffsets.length - 1];
+    if (charOffset < 0)
+        return 0;
+    if (charOffset > maxOffset)
+        return maxOffset;
+    return charOffset;
+};
+export const lineFromOffset = (lineOffsets, charOffset) => {
+    if (lineOffsets.length === 0)
+        return 0;
+    const clamped = clampOffset(lineOffsets, charOffset);
+    let lo = 0;
+    let hi = lineOffsets.length - 1;
+    while (lo < hi) {
+        const mid = (lo + hi + 1) >> 1;
+        if (lineOffsets[mid] <= clamped)
+            lo = mid;
+        else
+            hi = mid - 1;
+    }
+    return lo;
+};
+export const resolveChunkLines = (lineOffsets, startOffset, endOffset, baseStartLine) => {
+    const relativeStartLine = lineFromOffset(lineOffsets, startOffset);
+    const effectiveEndOffset = endOffset > startOffset ? endOffset - 1 : startOffset;
+    const relativeEndLine = lineFromOffset(lineOffsets, effectiveEndOffset);
+    return {
+        startLine: baseStartLine + relativeStartLine,
+        endLine: baseStartLine + relativeEndLine,
+    };
+};

package/dist/core/embeddings/server-mapping.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Server Mapping Configuration
+ *
+ * Reads ~/.gitnexus/server-mapping.json to map repo names to service names.
+ * Used in embedding text to enrich metadata with microservice context.
+ */
+/**
+ * Read the server mapping file and return the serverName for a given repoName.
+ * Returns undefined if no mapping exists.
+ */
+export declare const readServerMapping: (repoName: string) => Promise<string | undefined>;
+/**
+ * Clear the cached mapping (useful for testing or after file changes)
+ */
+export declare const clearServerMappingCache: () => void;

package/dist/core/embeddings/server-mapping.js

@@ -0,0 +1,33 @@
+/**
+ * Server Mapping Configuration
+ *
+ * Reads ~/.gitnexus/server-mapping.json to map repo names to service names.
+ * Used in embedding text to enrich metadata with microservice context.
+ */
+import fs from 'fs/promises';
+import path from 'path';
+import os from 'os';
+const MAPPING_FILE = path.join(os.homedir(), '.gitnexus', 'server-mapping.json');
+let cachedMapping = null;
+/**
+ * Read the server mapping file and return the serverName for a given repoName.
+ * Returns undefined if no mapping exists.
+ */
+export const readServerMapping = async (repoName) => {
+    try {
+        if (!cachedMapping) {
+            const raw = await fs.readFile(MAPPING_FILE, 'utf-8');
+            cachedMapping = JSON.parse(raw);
+        }
+        return cachedMapping[repoName];
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * Clear the cached mapping (useful for testing or after file changes)
+ */
+export const clearServerMappingCache = () => {
+    cachedMapping = null;
+};

package/dist/core/embeddings/structural-extractor.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Structural Extractor Module
+ *
+ * Reuses ingestion pipeline's AST-based MethodExtractor / FieldExtractor
+ * to extract method and field names for embedding text generation.
+ */
+export interface StructuralNames {
+    methodNames: string[];
+    fieldNames: string[];
+}
+/**
+ * Extract method and field names from a class/struct/interface node
+ * using the ingestion pipeline's AST extractors.
+ */
+export declare const extractStructuralNames: (content: string, filePath: string) => Promise<StructuralNames>;