@jafreck/lore 0.2.0 → 0.2.2

package/dist/indexer/index.js

@@ -9,14 +9,18 @@
  */
 import * as fs from 'node:fs';
 import * as crypto from 'node:crypto';
+import * as path from 'node:path';
 import { execFileSync } from 'node:child_process';
-import { openDb, setKbMeta, getKbMeta, createVec0Tables, KB_META_INDEX_CHECKPOINT, KB_META_LAST_HEAD_SHA, KB_META_COVERAGE_LAST_SOURCE_PATH, KB_META_COVERAGE_LAST_SOURCE_MTIME, } from './db.js';
+import { openDb, setLoreMeta, getLoreMeta, createVec0Tables, LORE_META_INDEX_CHECKPOINT, LORE_META_LAST_HEAD_SHA, LORE_META_COVERAGE_LAST_SOURCE_PATH, LORE_META_COVERAGE_LAST_SOURCE_MTIME, } from './db.js';
 import { walkFiles } from './walker.js';
 import { detectLanguageForPath } from './walker.js';
+import { walkDocumentationFiles } from './walker.js';
+import { inferSeededDocNoteKey, buildDocNoteScope } from './docs.js';
 import { ingestGitHistory } from './git-history.js';
 import { ParserPool } from './parser.js';
 import { ImportResolver } from './resolver.js';
 import { buildCallGraph } from './call-graph.js';
+import { isPublicDeclarationSurfaceSymbol, } from './extractors/types.js';
 import { CExtractor } from './extractors/c.js';
 import { RustExtractor } from './extractors/rust.js';
 import { PythonExtractor } from './extractors/python.js';
@@ -41,9 +45,10 @@ import { HaskellExtractor } from './extractors/haskell.js';
 import { JuliaExtractor } from './extractors/julia.js';
 import { ElmExtractor } from './extractors/elm.js';
 import { ObjcExtractor } from './extractors/objc.js';
-import { DEFAULT_EMBEDDING_MODEL } from './embedder.js';
+import { DEFAULT_EMBEDDING_MODEL, buildStructuralEmbeddingText } from './embedder.js';
 import { ingestCoverageReport } from './coverage.js';
 import { refreshTestMappings } from './test-mapper.js';
+import { LspEnrichmentCoordinator } from './lsp/enrichment.js';
 // ─── Extractor registry ───────────────────────────────────────────────────────
 const EXTRACTORS = {
     c: new CExtractor(),
@@ -79,7 +84,7 @@ const EMBED_BATCH_SIZE = 64;
  *
  * @example
  * ```ts
- * const builder = new IndexBuilder('/path/to/kb.db', { rootDir: '/path/to/src' });
+ * const builder = new IndexBuilder('/path/to/lore.db', { rootDir: '/path/to/src' });
  * await builder.build();
  * ```
  */
@@ -90,7 +95,10 @@ export class IndexBuilder {
     resolver;
     embedder;
     history;
+    indexDependencies;
     embeddingModel;
+    docsAutoNotes;
+    lspSettings;
     constructor(dbPath, walkerConfig, embedder, embeddingModelOrOptions) {
         this.dbPath = dbPath;
         this.walkerConfig = walkerConfig;
@@ -108,6 +116,9 @@ export class IndexBuilder {
             this.embedder = null;
         }
         this.history = opts.history ?? false;
+        this.docsAutoNotes = opts.docsAutoNotes ?? true;
+        this.indexDependencies = opts.indexDependencies ?? false;
+        this.lspSettings = opts.lsp ?? null;
     }
     // ─── Public API ──────────────────────────────────────────────────────────
     /**
@@ -118,8 +129,17 @@ export class IndexBuilder {
     async build() {
         const db = openDb(this.dbPath);
         const branch = this.resolveBranch();
+        const lspCoordinator = this.createLspEnrichmentCoordinator();
         try {
+            this.saveDocsAutoNotesSetting(db);
             const files = await walkFiles(this.walkerConfig);
+            const docs = await walkDocumentationFiles(this.walkerConfig);
+            if (lspCoordinator) {
+                const languages = new Set(files.map((file) => file.language));
+                if (this.indexDependencies)
+                    languages.add('typescript');
+                await lspCoordinator.start(languages);
+            }
             const resumeAt = this.loadBuildCheckpoint(db, branch, files.length);
             db.transaction(() => {
                 for (let i = resumeAt; i < files.length; i++) {
@@ -129,22 +149,38 @@ export class IndexBuilder {
                     this.processFile(db, file.path, file.language, branch);
                     this.saveBuildCheckpoint(db, branch, i + 1, files.length);
                 }
+                const seenDocPaths = new Set();
+                for (const doc of docs) {
+                    seenDocPaths.add(doc.path);
+                    this.processDocumentationFile(db, doc, branch);
+                    this.upsertSeededDocumentationNote(db, doc, branch);
+                }
+                this.removeStaleDocumentation(db, branch, seenDocPaths);
             })();
             this.saveBuildCheckpoint(db, branch, files.length, files.length);
             this.resolveImports(db, branch);
+            await this.indexDependencyDeclarations(db, lspCoordinator);
+            await this.enrichProjectSymbolsAndCallRefs(db, branch, files, lspCoordinator);
             refreshTestMappings(db, branch);
             buildCallGraph(db);
             this.saveLastKnownHead(db);
             if (this.embedder) {
                 await this.embedder.init();
                 await this.embedStructural(db);
+                await this.embedDocumentation(db);
             }
             if (this.history) {
                 const historyOptions = typeof this.history === 'object' ? this.history : undefined;
                 await ingestGitHistory(db, this.walkerConfig.rootDir, historyOptions);
+                if (this.embedder) {
+                    await this.embedCommitMessages(db);
+                }
             }
         }
         finally {
+            if (lspCoordinator) {
+                await lspCoordinator.dispose();
+            }
             db.close();
         }
     }
@@ -157,7 +193,25 @@ export class IndexBuilder {
     async update(changedFiles) {
         const db = openDb(this.dbPath);
         const branch = this.resolveBranch();
+        const lspCoordinator = this.createLspEnrichmentCoordinator();
+        const enrichedFiles = [];
         try {
+            this.saveDocsAutoNotesSetting(db);
+            const docs = await walkDocumentationFiles(this.walkerConfig);
+            const docsByPath = new Map(docs.map(doc => [doc.path, doc]));
+            if (lspCoordinator) {
+                const languages = new Set();
+                for (const filePath of changedFiles) {
+                    if (!fs.existsSync(filePath))
+                        continue;
+                    const language = detectLanguageForPath(filePath, this.walkerConfig);
+                    if (language)
+                        languages.add(language);
+                }
+                if (this.indexDependencies)
+                    languages.add('typescript');
+                await lspCoordinator.start(languages);
+            }
             db.transaction(() => {
                 for (const filePath of changedFiles) {
                     // If the file no longer exists, remove it from the DB
@@ -169,23 +223,35 @@ export class IndexBuilder {
                             db.prepare('DELETE FROM symbols_fts WHERE rowid IN (SELECT id FROM symbols WHERE file_id = ?)').run(row.id);
                             db.prepare('DELETE FROM files WHERE id = ?').run(row.id);
                         }
+                        this.deleteDocumentationByPath(db, filePath, branch);
                         continue;
                     }
                     const language = detectLanguageForPath(filePath, this.walkerConfig);
-                    if (!language)
-                        continue;
-                    // Null out resolved_id references pointing to this file before deletion
-                    const existingRow = db.prepare('SELECT id FROM files WHERE path = ? AND branch = ?').get(filePath, branch);
-                    if (existingRow) {
-                        db.prepare('UPDATE file_imports SET resolved_id = NULL WHERE resolved_id = ?').run(existingRow.id);
-                        db.prepare('DELETE FROM symbols_fts WHERE rowid IN (SELECT id FROM symbols WHERE file_id = ?)').run(existingRow.id);
+                    if (language) {
+                        enrichedFiles.push({ path: filePath, language });
+                        // Null out resolved_id references pointing to this file before deletion
+                        const existingRow = db.prepare('SELECT id FROM files WHERE path = ? AND branch = ?').get(filePath, branch);
+                        if (existingRow) {
+                            db.prepare('UPDATE file_imports SET resolved_id = NULL WHERE resolved_id = ?').run(existingRow.id);
+                            db.prepare('DELETE FROM symbols_fts WHERE rowid IN (SELECT id FROM symbols WHERE file_id = ?)').run(existingRow.id);
+                        }
+                        // Delete existing rows for this file (cascade handles symbols/imports)
+                        db.prepare('DELETE FROM files WHERE path = ? AND branch = ?').run(filePath, branch);
+                        this.processFile(db, filePath, language, branch);
+                    }
+                    const changedDoc = docsByPath.get(filePath);
+                    if (changedDoc) {
+                        this.processDocumentationFile(db, changedDoc, branch);
+                        this.upsertSeededDocumentationNote(db, changedDoc, branch);
+                    }
+                    else {
+                        this.deleteDocumentationByPath(db, filePath, branch);
                     }
-                    // Delete existing rows for this file (cascade handles symbols/imports)
-                    db.prepare('DELETE FROM files WHERE path = ? AND branch = ?').run(filePath, branch);
-                    this.processFile(db, filePath, language, branch);
                 }
             })();
             this.resolveImports(db, branch);
+            await this.indexDependencyDeclarations(db, lspCoordinator);
+            await this.enrichProjectSymbolsAndCallRefs(db, branch, enrichedFiles, lspCoordinator);
             refreshTestMappings(db, branch);
             if (this.history) {
                 const historyOptions = typeof this.history === 'object' ? this.history : undefined;
@@ -194,11 +260,18 @@ export class IndexBuilder {
             if (this.embedder) {
                 await this.embedder.init();
                 await this.embedStructural(db);
+                await this.embedDocumentation(db);
+                if (this.history) {
+                    await this.embedCommitMessages(db);
+                }
             }
             buildCallGraph(db);
             this.saveLastKnownHead(db);
         }
         finally {
+            if (lspCoordinator) {
+                await lspCoordinator.dispose();
+            }
             db.close();
         }
     }
@@ -238,8 +311,8 @@ export class IndexBuilder {
                 commitSha: resolvedCommitSha,
                 sourceMtime,
             });
-            setKbMeta(db, KB_META_COVERAGE_LAST_SOURCE_PATH, reportPath);
-            setKbMeta(db, KB_META_COVERAGE_LAST_SOURCE_MTIME, String(sourceMtime));
+            setLoreMeta(db, LORE_META_COVERAGE_LAST_SOURCE_PATH, reportPath);
+            setLoreMeta(db, LORE_META_COVERAGE_LAST_SOURCE_MTIME, String(sourceMtime));
         }
         finally {
             db.close();
@@ -264,8 +337,8 @@ export class IndexBuilder {
         // Upsert the file row
         let fileId;
         if (existing) {
-            db.prepare(`UPDATE files SET language = ?, size_bytes = ?, last_hash = ?, indexed_at = unixepoch()
-         WHERE id = ?`).run(language, sizeBytes, hash, existing.id);
+            db.prepare(`UPDATE files SET language = ?, size_bytes = ?, last_hash = ?, source = ?, indexed_at = unixepoch()
+          WHERE id = ?`).run(language, sizeBytes, hash, source, existing.id);
             fileId = existing.id;
             // Remove stale symbols / imports / external deps (also clean up FTS5 index)
             db.prepare(`DELETE FROM symbols_fts WHERE rowid IN (SELECT id FROM symbols WHERE file_id = ?)`).run(fileId);
@@ -276,9 +349,9 @@ export class IndexBuilder {
         }
         else {
             const info = db
-                .prepare(`INSERT INTO files (path, branch, language, size_bytes, last_hash)
-           VALUES (?, ?, ?, ?, ?)`)
-                .run(filePath, branch, language, sizeBytes, hash);
+                .prepare(`INSERT INTO files (path, branch, language, size_bytes, last_hash, source)
+           VALUES (?, ?, ?, ?, ?, ?)`)
+                .run(filePath, branch, language, sizeBytes, hash, source);
             fileId = Number(info.lastInsertRowid);
         }
         // Parse the source
@@ -299,7 +372,10 @@ export class IndexBuilder {
             const info = insertSymbol.run(fileId, sym.name, sym.kind, sym.startLine, sym.endLine, sym.signature ?? null, sym.docComment ?? null);
             const symId = Number(info.lastInsertRowid);
             symbolIdMap.set(sym.name, symId);
-            insertFts.run(symId, sym.name, sym.signature ?? '', sym.kind);
+            insertFts.run(symId, sym.name, buildStructuralEmbeddingText({
+                name: sym.name,
+                signature: sym.signature ?? null,
+            }), sym.kind);
         }
         const insertRoute = db.prepare(`INSERT INTO api_routes (file_id, method, path, handler_id, handler_name, framework, line, middleware)
        VALUES (?, ?, ?, ?, ?, ?, ?, ?)`);
@@ -321,6 +397,95 @@ export class IndexBuilder {
             }
         }
     }
+    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);
+        this.deleteDocSectionEmbeddings(db, staleSectionIds);
+        if (staleSectionIds.length > 0) {
+            db.prepare(`DELETE FROM doc_sections
+         WHERE id IN (${staleSectionIds.map(() => '?').join(', ')})`).run(...staleSectionIds);
+        }
+    }
+    upsertSeededDocumentationNote(db, doc, branch) {
+        if (!this.docsAutoNotes)
+            return;
+        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);
+    }
+    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)) {
+                this.deleteDocumentationById(db, doc.id);
+            }
+        }
+    }
+    deleteDocumentationByPath(db, docPath, branch) {
+        const row = db.prepare('SELECT id FROM docs WHERE path = ? AND branch = ?').get(docPath, branch);
+        if (!row)
+            return;
+        this.deleteDocumentationById(db, row.id);
+    }
+    deleteDocumentationById(db, docId) {
+        const sectionIds = db.prepare('SELECT id FROM doc_sections WHERE doc_id = ?').all(docId);
+        this.deleteDocSectionEmbeddings(db, sectionIds.map(row => row.id));
+        db.prepare('DELETE FROM docs WHERE id = ?').run(docId);
+    }
+    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);
+    }
     /**
      * Second pass: resolve raw_import strings to file IDs in the
      * `file_imports.resolved_id` column.  Also populates `external_deps` for
@@ -352,6 +517,146 @@ export class IndexBuilder {
             }
         }
     }
+    async indexDependencyDeclarations(db, lspCoordinator) {
+        db.prepare('DELETE FROM external_symbols').run();
+        if (!this.indexDependencies)
+            return;
+        const directDependencies = this.loadDirectDependencies();
+        if (directDependencies.size === 0)
+            return;
+        const extractor = EXTRACTORS.typescript;
+        if (!extractor)
+            return;
+        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(this.walkerConfig.rootDir, 'node_modules', packageName);
+            if (!fs.existsSync(packageDir) || !fs.statSync(packageDir).isDirectory())
+                continue;
+            const packageVersion = this.readInstalledPackageVersion(packageDir) ?? declaredVersion ?? null;
+            const declarationFiles = this.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) => this.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);
+                }
+            }
+        }
+    }
+    createLspEnrichmentCoordinator() {
+        if (!this.lspSettings?.enabled) {
+            return null;
+        }
+        return new LspEnrichmentCoordinator(this.lspSettings, this.walkerConfig.rootDir);
+    }
+    async enrichProjectSymbolsAndCallRefs(db, branch, files, lspCoordinator) {
+        if (!lspCoordinator || files.length === 0)
+            return;
+        const selectSymbols = db.prepare(`SELECT s.id, s.name, s.signature, s.start_line
+       FROM symbols s
+       JOIN files f ON f.id = s.file_id
+       WHERE f.path = ? AND f.branch = ?
+       ORDER BY s.id`);
+        const selectCallRefs = db.prepare(`SELECT sr.id, sr.call_line
+       FROM symbol_refs sr
+       JOIN symbols s ON s.id = sr.caller_id
+       JOIN files f ON f.id = s.file_id
+       WHERE f.path = ? AND f.branch = ?
+       ORDER BY sr.id`);
+        const updateSymbol = db.prepare(`UPDATE symbols
+       SET resolved_type_signature = ?, resolved_return_type = ?, definition_uri = ?, definition_path = ?
+       WHERE id = ?`);
+        const updateSymbolFts = db.prepare('UPDATE symbols_fts SET signature = ? WHERE rowid = ?');
+        const updateCallRef = db.prepare(`UPDATE symbol_refs
+       SET resolved_type_signature = ?, resolved_return_type = ?, definition_uri = ?, definition_path = ?
+       WHERE id = ?`);
+        for (const file of files) {
+            if (!file || !fs.existsSync(file.path))
+                continue;
+            let source;
+            try {
+                source = fs.readFileSync(file.path, 'utf8');
+            }
+            catch {
+                continue;
+            }
+            const symbols = selectSymbols.all(file.path, branch);
+            if (symbols.length > 0) {
+                const symbolMetadata = await lspCoordinator.enrich({
+                    filePath: file.path,
+                    language: file.language,
+                    source,
+                    targets: symbols.map((symbol) => ({ line: symbol.start_line, character: 0 })),
+                });
+                for (let i = 0; i < symbols.length; i++) {
+                    const symbol = symbols[i];
+                    if (!symbol)
+                        continue;
+                    const metadata = symbolMetadata[i];
+                    if (!metadata)
+                        continue;
+                    updateSymbol.run(metadata.resolvedTypeSignature, metadata.resolvedReturnType, metadata.definitionUri, metadata.definitionPath, symbol.id);
+                    updateSymbolFts.run(buildStructuralEmbeddingText({
+                        name: symbol.name,
+                        signature: symbol.signature,
+                        resolvedTypeSignature: metadata.resolvedTypeSignature,
+                        resolvedReturnType: metadata.resolvedReturnType,
+                    }), symbol.id);
+                }
+            }
+            const callRefs = selectCallRefs.all(file.path, branch);
+            if (callRefs.length > 0) {
+                const callRefMetadata = await lspCoordinator.enrich({
+                    filePath: file.path,
+                    language: file.language,
+                    source,
+                    targets: callRefs.map((callRef) => ({ line: callRef.call_line, character: 0 })),
+                });
+                for (let i = 0; i < callRefs.length; i++) {
+                    const callRef = callRefs[i];
+                    if (!callRef)
+                        continue;
+                    const metadata = callRefMetadata[i];
+                    if (!metadata)
+                        continue;
+                    updateCallRef.run(metadata.resolvedTypeSignature, metadata.resolvedReturnType, metadata.definitionUri, metadata.definitionPath, callRef.id);
+                }
+            }
+        }
+    }
     resolveBranch() {
         if (this.walkerConfig.branch)
             return this.walkerConfig.branch;
@@ -360,9 +665,12 @@ export class IndexBuilder {
     saveLastKnownHead(db) {
         const headSha = this.readGitValue(['rev-parse', 'HEAD']);
         if (headSha) {
-            setKbMeta(db, KB_META_LAST_HEAD_SHA, headSha);
+            setLoreMeta(db, LORE_META_LAST_HEAD_SHA, headSha);
         }
     }
+    saveDocsAutoNotesSetting(db) {
+        setLoreMeta(db, 'docs_auto_notes', this.docsAutoNotes ? '1' : '0');
+    }
     readGitValue(args) {
         try {
             const value = execFileSync('git', ['-C', this.walkerConfig.rootDir, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
@@ -372,8 +680,82 @@ export class IndexBuilder {
             return undefined;
         }
     }
+    loadDirectDependencies() {
+        const packageJsonPath = path.join(this.walkerConfig.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;
+    }
+    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;
+    }
+    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;
+    }
+    shouldIndexDependencySymbol(symbol) {
+        if (!isPublicDeclarationSurfaceSymbol(symbol))
+            return false;
+        if (symbol.declarationSurface)
+            return true;
+        return !this.hasImplementationBody(symbol);
+    }
+    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() !== '';
+    }
     loadBuildCheckpoint(db, branch, totalFiles) {
-        const raw = getKbMeta(db, KB_META_INDEX_CHECKPOINT);
+        const raw = getLoreMeta(db, LORE_META_INDEX_CHECKPOINT);
         if (!raw)
             return 0;
         try {
@@ -395,28 +777,37 @@ export class IndexBuilder {
             nextFileIndex,
             updatedAt: Math.floor(Date.now() / 1000),
         };
-        setKbMeta(db, KB_META_INDEX_CHECKPOINT, JSON.stringify(checkpoint));
+        setLoreMeta(db, LORE_META_INDEX_CHECKPOINT, JSON.stringify(checkpoint));
     }
     /**
      * Embed structural symbol signatures in batches and persist results to
      * the `symbol_embeddings` vec0 virtual table.
      *
-     * Also stores the embedding model name and dims in `kb_meta` and
+     * Also stores the embedding model name and dims in `lore_meta` and
      * creates the vec0 tables if they don't exist yet.
      */
     async embedStructural(db) {
         const embedder = this.embedder;
-        setKbMeta(db, 'embedding_model', embedder.modelName);
-        setKbMeta(db, 'embedding_dims', String(embedder.dims));
+        setLoreMeta(db, 'embedding_model', embedder.modelName);
+        setLoreMeta(db, 'embedding_dims', String(embedder.dims));
         createVec0Tables(db, embedder.dims);
-        // Fetch all symbols that have a signature to embed.
+        // Fetch all symbols that have structural text to embed.
         const symbols = db
-            .prepare('SELECT id, name, signature FROM symbols WHERE signature IS NOT NULL')
+            .prepare(`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`)
             .all();
         const insertEmbed = db.prepare('INSERT OR REPLACE INTO symbol_embeddings(rowid, embedding) VALUES (CAST(? AS INTEGER), json(?))');
         for (let i = 0; i < symbols.length; i += EMBED_BATCH_SIZE) {
             const batch = symbols.slice(i, i + EMBED_BATCH_SIZE);
-            const texts = batch.map(s => s.signature || s.name);
+            const texts = batch.map((symbol) => buildStructuralEmbeddingText({
+                name: symbol.name,
+                signature: symbol.signature,
+                resolvedTypeSignature: symbol.resolved_type_signature,
+                resolvedReturnType: symbol.resolved_return_type,
+            }));
             const embeddings = await embedder.embed(texts);
             db.transaction(() => {
                 for (let j = 0; j < batch.length; j++) {
@@ -427,5 +818,54 @@ export class IndexBuilder {
             })();
         }
     }
+    async embedDocumentation(db) {
+        const embedder = this.embedder;
+        db.exec(`
+      CREATE VIRTUAL TABLE IF NOT EXISTS doc_section_embeddings USING vec0(
+        embedding FLOAT[${embedder.dims}]
+      );
+    `);
+        const 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(?))');
+        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);
+            const embeddings = await embedder.embed(texts);
+            db.transaction(() => {
+                for (let j = 0; j < batch.length; j++) {
+                    const section = batch[j];
+                    if (section) {
+                        insertEmbed.run(section.id, JSON.stringify(embeddings[j]));
+                    }
+                }
+            })();
+        }
+    }
+    async embedCommitMessages(db) {
+        const embedder = this.embedder;
+        const commits = db.prepare(`SELECT rowid, message
+       FROM commits
+       WHERE length(trim(message)) > 0
+       ORDER BY rowid`).all();
+        if (commits.length === 0)
+            return;
+        const insertEmbed = db.prepare('INSERT OR REPLACE INTO commit_embeddings(rowid, embedding) VALUES (CAST(? AS INTEGER), json(?))');
+        for (let i = 0; i < commits.length; i += EMBED_BATCH_SIZE) {
+            const batch = commits.slice(i, i + EMBED_BATCH_SIZE);
+            const embeddings = await embedder.embed(batch.map((commit) => commit.message));
+            db.transaction(() => {
+                for (let j = 0; j < batch.length; j++) {
+                    const commit = batch[j];
+                    if (commit) {
+                        insertEmbed.run(commit.rowid, JSON.stringify(embeddings[j]));
+                    }
+                }
+            })();
+        }
+    }
 }
 //# sourceMappingURL=index.js.map