@jafreck/lore 0.2.4 → 0.3.0

package/dist/indexer/stages/dependency-api.js

@@ -0,0 +1,174 @@
+/**
+ * @module indexer/stages/dependency-api
+ *
+ * Pipeline stage: index declaration-surface symbols from direct dependencies
+ * (.d.ts files for npm, etc.). Populates `external_symbols`.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { ParserPool } from '../parser.js';
+import { LspEnrichmentCoordinator } from '../lsp/enrichment.js';
+import { isPublicDeclarationSurfaceSymbol, } from '../extractors/types.js';
+import { TypeScriptExtractor } from '../extractors/typescript.js';
+// ─── Stage ────────────────────────────────────────────────────────────────────
+/**
+ * Index exported declarations from direct npm dependencies (.d.ts files).
+ * Stores results in `external_symbols`.
+ */
+export class DependencyApiStage {
+    name = 'dependency-api';
+    pool = null;
+    async execute(context, _mode) {
+        const { db, walkerConfig, lsp } = context;
+        // Always clear external symbols — when indexDependencies is false, this
+        // ensures stale data from a previous deps-enabled build is removed.
+        db.prepare('DELETE FROM external_symbols').run();
+        if (!context.indexDependencies)
+            return;
+        this.pool = new ParserPool();
+        const directDependencies = loadDirectDependencies(walkerConfig.rootDir);
+        if (directDependencies.size === 0)
+            return;
+        const extractor = new TypeScriptExtractor();
+        // Optional LSP coordinator for enriching external symbols.
+        let lspCoordinator = null;
+        if (lsp?.enabled) {
+            lspCoordinator = new LspEnrichmentCoordinator(lsp, walkerConfig.rootDir);
+            await lspCoordinator.start(new Set(['typescript']));
+        }
+        try {
+            const insertExternalSymbol = db.prepare(`INSERT OR IGNORE INTO external_symbols
+           (
+             package_name,
+             package_version,
+             source_ref,
+             symbol_name,
+             symbol_kind,
+             signature,
+             doc_comment,
+             resolved_type_signature,
+             resolved_return_type,
+             definition_uri,
+             definition_path
+           )
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+            for (const [packageName, declaredVersion] of directDependencies) {
+                const packageDir = path.join(walkerConfig.rootDir, 'node_modules', packageName);
+                if (!fs.existsSync(packageDir) || !fs.statSync(packageDir).isDirectory())
+                    continue;
+                const packageVersion = readInstalledPackageVersion(packageDir) ?? declaredVersion ?? null;
+                const declarationFiles = collectDeclarationFiles(packageDir);
+                for (const declarationFile of declarationFiles) {
+                    const source = fs.readFileSync(declarationFile, 'utf8');
+                    const tree = this.pool.parse('typescript', source);
+                    if (!tree)
+                        continue;
+                    const result = extractor.extract(tree, source, declarationFile);
+                    const declarationSymbols = result.symbols.filter((symbol) => shouldIndexDependencySymbol(symbol));
+                    const enrichmentRows = lspCoordinator
+                        ? await lspCoordinator.enrich({
+                            filePath: declarationFile,
+                            language: 'typescript',
+                            source,
+                            targets: declarationSymbols.map((symbol) => ({
+                                line: symbol.startLine,
+                                character: symbol.startCharacter ?? 0,
+                            })),
+                        })
+                        : declarationSymbols.map(() => null);
+                    for (let i = 0; i < declarationSymbols.length; i++) {
+                        const symbol = declarationSymbols[i];
+                        if (!symbol)
+                            continue;
+                        const metadata = enrichmentRows[i];
+                        insertExternalSymbol.run(packageName, packageVersion, declarationFile, symbol.name, symbol.kind, symbol.signature, symbol.docComment ?? null, metadata?.resolvedTypeSignature ?? null, metadata?.resolvedReturnType ?? null, metadata?.definitionUri ?? null, metadata?.definitionPath ?? null);
+                    }
+                }
+            }
+        }
+        finally {
+            if (lspCoordinator) {
+                await lspCoordinator.dispose();
+            }
+        }
+    }
+    async dispose() {
+        this.pool = null;
+    }
+}
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+function loadDirectDependencies(rootDir) {
+    const packageJsonPath = path.join(rootDir, 'package.json');
+    if (!fs.existsSync(packageJsonPath))
+        return new Map();
+    const raw = fs.readFileSync(packageJsonPath, 'utf8');
+    const pkg = JSON.parse(raw);
+    const deps = new Map();
+    for (const section of [pkg.dependencies, pkg.devDependencies, pkg.peerDependencies]) {
+        if (!section)
+            continue;
+        for (const [name, version] of Object.entries(section)) {
+            if (!deps.has(name))
+                deps.set(name, version);
+        }
+    }
+    return deps;
+}
+function readInstalledPackageVersion(packageDir) {
+    const packageJsonPath = path.join(packageDir, 'package.json');
+    if (!fs.existsSync(packageJsonPath))
+        return undefined;
+    const raw = fs.readFileSync(packageJsonPath, 'utf8');
+    const pkg = JSON.parse(raw);
+    return pkg.version;
+}
+function collectDeclarationFiles(packageDir) {
+    const declarations = [];
+    const stack = [packageDir];
+    while (stack.length > 0) {
+        const currentDir = stack.pop();
+        if (!currentDir)
+            continue;
+        const entries = fs.readdirSync(currentDir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.name === 'node_modules')
+                continue;
+            const fullPath = path.join(currentDir, entry.name);
+            if (entry.isDirectory()) {
+                stack.push(fullPath);
+                continue;
+            }
+            if (entry.isFile() && fullPath.endsWith('.d.ts')) {
+                declarations.push(fullPath);
+            }
+        }
+    }
+    return declarations;
+}
+function shouldIndexDependencySymbol(symbol) {
+    if (!isPublicDeclarationSurfaceSymbol(symbol))
+        return false;
+    if (symbol.declarationSurface)
+        return true;
+    return !hasImplementationBody(symbol);
+}
+function hasImplementationBody(symbol) {
+    const node = symbol.astNode;
+    if (!node)
+        return false;
+    if (node.type === 'arrow_function' ||
+        node.type === 'function_expression' ||
+        node.type === 'generator_function') {
+        return true;
+    }
+    if (node.type === 'class_declaration' ||
+        node.type === 'interface_declaration' ||
+        node.type === 'type_alias_declaration') {
+        return false;
+    }
+    const bodyNode = node.childForFieldName('body');
+    if (!bodyNode)
+        return false;
+    return bodyNode.namedChildCount > 0 || bodyNode.text.trim() !== '';
+}
+//# sourceMappingURL=dependency-api.js.map

package/dist/indexer/stages/dependency-api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dependency-api.js","sourceRoot":"","sources":["../../../src/indexer/stages/dependency-api.ts"],"names":[],"mappings":"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"}

package/dist/indexer/stages/docs-index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @module indexer/stages/docs-index
+ *
+ * Pipeline stage: walk documentation files, chunk by headings, insert into
+ * the database, and optionally seed notes from documentation content.
+ */
+import type { PipelineContext, PipelineStage } from '../pipeline.js';
+import type { Database } from '../db.js';
+import type { DocumentationFile } from '../docs.js';
+/**
+ * Walk documentation files, chunk by headings, and persist to the database.
+ * Optionally seeds notes from documentation content.
+ */
+export declare class DocsIndexStage implements PipelineStage {
+    readonly name = "docs-index";
+    execute(context: PipelineContext, mode: 'build' | 'update'): Promise<void>;
+}
+export declare function processDocumentationFile(db: Database.Database, doc: DocumentationFile, branch: string): void;
+export declare function upsertSeededDocumentationNote(db: Database.Database, doc: DocumentationFile, branch: string): void;
+//# sourceMappingURL=docs-index.d.ts.map

package/dist/indexer/stages/docs-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-index.d.ts","sourceRoot":"","sources":["../../../src/indexer/stages/docs-index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACrE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEzC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAiBpD;;;GAGG;AACH,qBAAa,cAAe,YAAW,aAAa;IAClD,QAAQ,CAAC,IAAI,gBAAgB;IAEvB,OAAO,CAAC,OAAO,EAAE,eAAe,EAAE,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;CAsCjF;AAID,wBAAgB,wBAAwB,CACtC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,GAAG,EAAE,iBAAiB,EACtB,MAAM,EAAE,MAAM,GACb,IAAI,CAsEN;AAED,wBAAgB,6BAA6B,CAC3C,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,GAAG,EAAE,iBAAiB,EACtB,MAAM,EAAE,MAAM,GACb,IAAI,CAsBN"}

package/dist/indexer/stages/docs-index.js

@@ -0,0 +1,144 @@
+/**
+ * @module indexer/stages/docs-index
+ *
+ * Pipeline stage: walk documentation files, chunk by headings, insert into
+ * the database, and optionally seed notes from documentation content.
+ */
+import { walkDocumentationFiles } from '../walker.js';
+import { inferSeededDocNoteKey, buildDocNoteScope } from '../docs.js';
+// ─── Stage ────────────────────────────────────────────────────────────────────
+/**
+ * Walk documentation files, chunk by headings, and persist to the database.
+ * Optionally seeds notes from documentation content.
+ */
+export class DocsIndexStage {
+    name = 'docs-index';
+    async execute(context, mode) {
+        const docs = await walkDocumentationFiles(context.walkerConfig);
+        context.log.indexing('docs walk complete', { docCount: docs.length });
+        const { db, branch } = context;
+        if (mode === 'build') {
+            db.transaction(() => {
+                const seenDocPaths = new Set();
+                for (const doc of docs) {
+                    seenDocPaths.add(doc.path);
+                    processDocumentationFile(db, doc, branch);
+                    if (context.docsAutoNotes) {
+                        upsertSeededDocumentationNote(db, doc, branch);
+                    }
+                }
+                removeStaleDocumentation(db, branch, seenDocPaths);
+            })();
+        }
+        else {
+            // Update mode: only process docs that are in the changed-file list
+            const changedFiles = context.changedFiles ?? [];
+            const changedSet = new Set(changedFiles);
+            const docsByPath = new Map(docs.map(doc => [doc.path, doc]));
+            db.transaction(() => {
+                for (const filePath of changedFiles) {
+                    const changedDoc = docsByPath.get(filePath);
+                    if (changedDoc) {
+                        processDocumentationFile(db, changedDoc, branch);
+                        if (context.docsAutoNotes)
+                            upsertSeededDocumentationNote(db, changedDoc, branch);
+                        context.changedDocPaths.push(filePath);
+                    }
+                    else {
+                        deleteDocumentationByPath(db, filePath, branch);
+                    }
+                }
+            })();
+        }
+    }
+}
+// ─── Documentation file processing ───────────────────────────────────────────
+export function processDocumentationFile(db, doc, branch) {
+    const existing = db.prepare('SELECT id, content_hash FROM docs WHERE path = ? AND branch = ?').get(doc.path, branch);
+    if (existing?.content_hash === doc.hash) {
+        return;
+    }
+    let docId;
+    if (existing) {
+        db.prepare(`UPDATE docs
+       SET kind = ?, title = ?, content = ?, content_hash = ?, indexed_at = unixepoch()
+       WHERE id = ?`).run(doc.kind, doc.title, doc.content, doc.hash, existing.id);
+        docId = existing.id;
+    }
+    else {
+        const info = db.prepare(`INSERT INTO docs (path, branch, kind, title, content, content_hash)
+       VALUES (?, ?, ?, ?, ?, ?)`).run(doc.path, branch, doc.kind, doc.title, doc.content, doc.hash);
+        docId = Number(info.lastInsertRowid);
+    }
+    const existingSections = db.prepare('SELECT id, section_index FROM doc_sections WHERE doc_id = ?').all(docId);
+    const insertSection = db.prepare(`INSERT INTO doc_sections (
+       doc_id, section_index, title, depth, heading_path, line_start, line_end, content, content_hash
+     ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+     ON CONFLICT(doc_id, section_index) DO UPDATE SET
+       title = excluded.title,
+       depth = excluded.depth,
+       heading_path = excluded.heading_path,
+       line_start = excluded.line_start,
+       line_end = excluded.line_end,
+       content = excluded.content,
+       content_hash = excluded.content_hash`);
+    const activeSectionIndexes = new Set();
+    for (const chunk of doc.chunks) {
+        activeSectionIndexes.add(chunk.sectionIndex);
+        insertSection.run(docId, chunk.sectionIndex, chunk.title, chunk.depth, JSON.stringify(chunk.headingPath), chunk.lineStart, chunk.lineEnd, chunk.content, chunk.hash);
+    }
+    const staleSectionIds = existingSections
+        .filter(section => !activeSectionIndexes.has(section.section_index))
+        .map(section => section.id);
+    deleteDocSectionEmbeddings(db, staleSectionIds);
+    if (staleSectionIds.length > 0) {
+        db.prepare(`DELETE FROM doc_sections
+       WHERE id IN (${staleSectionIds.map(() => '?').join(', ')})`).run(...staleSectionIds);
+    }
+}
+export function upsertSeededDocumentationNote(db, doc, branch) {
+    const key = inferSeededDocNoteKey(doc);
+    if (!key)
+        return;
+    const scope = buildDocNoteScope(doc.path, branch);
+    const existing = db.prepare('SELECT content, source_hash FROM notes WHERE key = ? AND scope = ?').get(key, scope);
+    if (existing?.content === doc.content && existing.source_hash === doc.hash) {
+        return;
+    }
+    db.prepare(`INSERT INTO notes (key, scope, content, model, source_hash, created_at, updated_at)
+     VALUES (?, ?, ?, ?, ?, unixepoch(), unixepoch())
+     ON CONFLICT(key, scope) DO UPDATE SET
+       content = excluded.content,
+       model = excluded.model,
+       source_hash = excluded.source_hash,
+       updated_at = unixepoch()`).run(key, scope, doc.content, 'system:auto-doc-seed', doc.hash);
+}
+function deleteDocumentationByPath(db, docPath, branch) {
+    const row = db.prepare('SELECT id FROM docs WHERE path = ? AND branch = ?')
+        .get(docPath, branch);
+    if (!row)
+        return;
+    deleteDocumentationById(db, row.id);
+}
+function removeStaleDocumentation(db, branch, retainedPaths) {
+    const docs = db.prepare('SELECT id, path FROM docs WHERE branch = ?').all(branch);
+    for (const doc of docs) {
+        if (!retainedPaths.has(doc.path)) {
+            deleteDocumentationById(db, doc.id);
+        }
+    }
+}
+function deleteDocumentationById(db, docId) {
+    const sectionIds = db.prepare('SELECT id FROM doc_sections WHERE doc_id = ?').all(docId);
+    deleteDocSectionEmbeddings(db, sectionIds.map(row => row.id));
+    db.prepare('DELETE FROM docs WHERE id = ?').run(docId);
+}
+function deleteDocSectionEmbeddings(db, sectionIds) {
+    if (sectionIds.length === 0)
+        return;
+    const hasEmbeddingsTable = db.prepare("SELECT 1 AS present FROM sqlite_master WHERE type IN ('table', 'virtual table') AND name = 'doc_section_embeddings'").get();
+    if (!hasEmbeddingsTable)
+        return;
+    db.prepare(`DELETE FROM doc_section_embeddings WHERE rowid IN (${sectionIds.map(() => '?').join(', ')})`).run(...sectionIds);
+}
+//# sourceMappingURL=docs-index.js.map

package/dist/indexer/stages/docs-index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-index.js","sourceRoot":"","sources":["../../../src/indexer/stages/docs-index.ts"],"names":[],"mappings":"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"}

package/dist/indexer/stages/embedding.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @module indexer/stages/embedding
+ *
+ * Pipeline stage: embed symbol signatures, documentation sections, and
+ * commit messages into vec0 virtual tables for semantic search.
+ */
+import type { PipelineContext, PipelineStage } from '../pipeline.js';
+/**
+ * Embed symbol signatures, documentation sections, and commit messages.
+ *
+ * Skips entirely when no `EmbeddingProvider` is configured in the context.
+ */
+export declare class EmbeddingStage implements PipelineStage {
+    readonly name = "embedding";
+    execute(context: PipelineContext, mode: 'build' | 'update'): Promise<void>;
+}
+//# sourceMappingURL=embedding.d.ts.map

package/dist/indexer/stages/embedding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedding.d.ts","sourceRoot":"","sources":["../../../src/indexer/stages/embedding.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AASrE;;;;GAIG;AACH,qBAAa,cAAe,YAAW,aAAa;IAClD,QAAQ,CAAC,IAAI,eAAe;IAEtB,OAAO,CAAC,OAAO,EAAE,eAAe,EAAE,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;CA6BjF"}

package/dist/indexer/stages/embedding.js

@@ -0,0 +1,217 @@
+/**
+ * @module indexer/stages/embedding
+ *
+ * Pipeline stage: embed symbol signatures, documentation sections, and
+ * commit messages into vec0 virtual tables for semantic search.
+ */
+import { setLoreMeta, createVec0Tables } from '../db.js';
+import { buildStructuralEmbeddingText } from '../embedder.js';
+/** Number of items to embed per batch. */
+const EMBED_BATCH_SIZE = 64;
+/**
+ * Embed symbol signatures, documentation sections, and commit messages.
+ *
+ * Skips entirely when no `EmbeddingProvider` is configured in the context.
+ */
+export class EmbeddingStage {
+    name = 'embedding';
+    async execute(context, mode) {
+        if (!context.embedder)
+            return;
+        const { db, embedder } = context;
+        context.log.indexing('embedding started', { model: embedder.modelName });
+        await embedder.init();
+        if (mode === 'update') {
+            // Clean up orphaned symbol embeddings for symbols that were deleted/replaced.
+            deleteSymbolEmbeddings(db, context.staleSymbolIds);
+            // Resolve scoped file/doc IDs for incremental embedding.
+            const changedFileIds = resolveFileIds(db, context.changedSourcePaths, context.branch);
+            const changedDocIds = resolveDocIds(db, context.changedDocPaths, context.branch);
+            await embedStructural(db, embedder, changedFileIds);
+            await embedDocumentation(db, embedder, changedDocIds);
+        }
+        else {
+            await embedStructural(db, embedder);
+            await embedDocumentation(db, embedder);
+        }
+        if (context.history) {
+            await embedCommitMessages(db, embedder);
+        }
+        context.log.indexing('embedding complete');
+    }
+}
+// ─── Structural symbol embeddings ─────────────────────────────────────────────
+async function embedStructural(db, embedder, fileIds) {
+    setLoreMeta(db, 'embedding_model', embedder.modelName);
+    setLoreMeta(db, 'embedding_dims', String(embedder.dims));
+    createVec0Tables(db, embedder.dims);
+    const baseQuery = `SELECT id, name, signature, resolved_type_signature, resolved_return_type
+     FROM symbols
+     WHERE (signature IS NOT NULL
+        OR resolved_type_signature IS NOT NULL
+        OR resolved_return_type IS NOT NULL)`;
+    let symbols;
+    if (fileIds && fileIds.length > 0) {
+        symbols = db
+            .prepare(`${baseQuery} AND file_id IN (${fileIds.map(() => '?').join(', ')})`)
+            .all(...fileIds);
+    }
+    else {
+        symbols = db.prepare(baseQuery).all();
+    }
+    const insertEmbed = db.prepare('INSERT OR REPLACE INTO symbol_embeddings(rowid, embedding) VALUES (CAST(? AS INTEGER), json(?))');
+    // P4: Pipeline — start embedding the next batch while writing the current one.
+    let pendingEmbed = null;
+    let pendingBatch = [];
+    for (let i = 0; i < symbols.length; i += EMBED_BATCH_SIZE) {
+        const batch = symbols.slice(i, i + EMBED_BATCH_SIZE);
+        const texts = batch.map((symbol) => buildStructuralEmbeddingText({
+            name: symbol.name,
+            signature: symbol.signature,
+            resolvedTypeSignature: symbol.resolved_type_signature,
+            resolvedReturnType: symbol.resolved_return_type,
+        }));
+        if (pendingEmbed) {
+            const embeddings = await pendingEmbed;
+            db.transaction(() => {
+                for (let j = 0; j < pendingBatch.length; j++) {
+                    const sym = pendingBatch[j];
+                    if (sym)
+                        insertEmbed.run(sym.id, JSON.stringify(embeddings[j]));
+                }
+            })();
+        }
+        pendingEmbed = embedder.embed(texts);
+        pendingBatch = batch;
+    }
+    if (pendingEmbed) {
+        const embeddings = await pendingEmbed;
+        db.transaction(() => {
+            for (let j = 0; j < pendingBatch.length; j++) {
+                const sym = pendingBatch[j];
+                if (sym)
+                    insertEmbed.run(sym.id, JSON.stringify(embeddings[j]));
+            }
+        })();
+    }
+}
+// ─── Documentation section embeddings ─────────────────────────────────────────
+async function embedDocumentation(db, embedder, docIds) {
+    db.exec(`
+    CREATE VIRTUAL TABLE IF NOT EXISTS doc_section_embeddings USING vec0(
+      embedding FLOAT[${embedder.dims}]
+    );
+  `);
+    let sections;
+    if (docIds && docIds.length > 0) {
+        sections = db.prepare(`SELECT id, title, content
+       FROM doc_sections
+       WHERE doc_id IN (${docIds.map(() => '?').join(', ')})
+       ORDER BY id`).all(...docIds);
+    }
+    else {
+        sections = db.prepare(`SELECT id, title, content
+       FROM doc_sections
+       ORDER BY id`).all();
+    }
+    if (sections.length === 0)
+        return;
+    const insertEmbed = db.prepare('INSERT OR REPLACE INTO doc_section_embeddings(rowid, embedding) VALUES (CAST(? AS INTEGER), json(?))');
+    // P4: Pipeline — start embedding the next batch while writing the current one.
+    let pendingEmbed = null;
+    let pendingBatch = [];
+    for (let i = 0; i < sections.length; i += EMBED_BATCH_SIZE) {
+        const batch = sections.slice(i, i + EMBED_BATCH_SIZE);
+        const texts = batch.map(section => section.content || section.title);
+        if (pendingEmbed) {
+            const embeddings = await pendingEmbed;
+            db.transaction(() => {
+                for (let j = 0; j < pendingBatch.length; j++) {
+                    const section = pendingBatch[j];
+                    if (section)
+                        insertEmbed.run(section.id, JSON.stringify(embeddings[j]));
+                }
+            })();
+        }
+        pendingEmbed = embedder.embed(texts);
+        pendingBatch = batch;
+    }
+    if (pendingEmbed) {
+        const embeddings = await pendingEmbed;
+        db.transaction(() => {
+            for (let j = 0; j < pendingBatch.length; j++) {
+                const section = pendingBatch[j];
+                if (section)
+                    insertEmbed.run(section.id, JSON.stringify(embeddings[j]));
+            }
+        })();
+    }
+}
+// ─── Commit message embeddings ────────────────────────────────────────────────
+async function embedCommitMessages(db, embedder) {
+    const commits = db.prepare(`SELECT c.rowid, c.message
+     FROM commits c
+     LEFT JOIN commit_embeddings ce ON ce.rowid = c.rowid
+     WHERE length(trim(c.message)) > 0
+       AND ce.rowid IS NULL
+     ORDER BY c.rowid`).all();
+    if (commits.length === 0)
+        return;
+    const insertEmbed = db.prepare('INSERT OR REPLACE INTO commit_embeddings(rowid, embedding) VALUES (CAST(? AS INTEGER), json(?))');
+    // P4: Pipeline — start embedding the next batch while writing the current one.
+    let pendingEmbed = null;
+    let pendingBatch = [];
+    for (let i = 0; i < commits.length; i += EMBED_BATCH_SIZE) {
+        const batch = commits.slice(i, i + EMBED_BATCH_SIZE);
+        if (pendingEmbed) {
+            const embeddings = await pendingEmbed;
+            db.transaction(() => {
+                for (let j = 0; j < pendingBatch.length; j++) {
+                    const commit = pendingBatch[j];
+                    if (commit)
+                        insertEmbed.run(commit.rowid, JSON.stringify(embeddings[j]));
+                }
+            })();
+        }
+        pendingEmbed = embedder.embed(batch.map((commit) => commit.message));
+        pendingBatch = batch;
+    }
+    if (pendingEmbed) {
+        const embeddings = await pendingEmbed;
+        db.transaction(() => {
+            for (let j = 0; j < pendingBatch.length; j++) {
+                const commit = pendingBatch[j];
+                if (commit)
+                    insertEmbed.run(commit.rowid, JSON.stringify(embeddings[j]));
+            }
+        })();
+    }
+}
+// ─── Update-mode helpers ──────────────────────────────────────────────────────
+function deleteSymbolEmbeddings(db, symbolIds) {
+    if (symbolIds.length === 0)
+        return;
+    const hasTable = db.prepare("SELECT 1 AS present FROM sqlite_master WHERE type IN ('table', 'virtual table') AND name = 'symbol_embeddings'").get();
+    if (!hasTable)
+        return;
+    db.prepare(`DELETE FROM symbol_embeddings WHERE rowid IN (${symbolIds.map(() => '?').join(', ')})`).run(...symbolIds);
+}
+function resolveFileIds(db, paths, branch) {
+    const ids = [];
+    for (const p of paths) {
+        const row = db.prepare('SELECT id FROM files WHERE path = ? AND branch = ?').get(p, branch);
+        if (row)
+            ids.push(row.id);
+    }
+    return ids;
+}
+function resolveDocIds(db, paths, branch) {
+    const ids = [];
+    for (const p of paths) {
+        const row = db.prepare('SELECT id FROM docs WHERE path = ? AND branch = ?').get(p, branch);
+        if (row)
+            ids.push(row.id);
+    }
+    return ids;
+}
+//# sourceMappingURL=embedding.js.map

package/dist/indexer/stages/embedding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedding.js","sourceRoot":"","sources":["../../../src/indexer/stages/embedding.ts"],"names":[],"mappings":"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"}

package/dist/indexer/stages/import-resolution.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @module indexer/stages/import-resolution
+ *
+ * Pipeline stage: resolve raw import strings to file IDs (internal) or
+ * external package names. Populates `file_imports.resolved_id` and
+ * `external_deps` rows.
+ */
+import type { PipelineContext, PipelineStage } from '../pipeline.js';
+/**
+ * Resolves raw imports in `file_imports` to internal file IDs (`resolved_id`)
+ * or external package names (`external_deps`).
+ */
+export declare class ImportResolutionStage implements PipelineStage {
+    readonly name = "import-resolution";
+    execute(context: PipelineContext, _mode: 'build' | 'update'): Promise<void>;
+}
+//# sourceMappingURL=import-resolution.d.ts.map

package/dist/indexer/stages/import-resolution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"import-resolution.d.ts","sourceRoot":"","sources":["../../../src/indexer/stages/import-resolution.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAKrE;;;GAGG;AACH,qBAAa,qBAAsB,YAAW,aAAa;IACzD,QAAQ,CAAC,IAAI,uBAAuB;IAE9B,OAAO,CAAC,OAAO,EAAE,eAAe,EAAE,KAAK,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;CAsDlF"}