@jafreck/lore 0.2.5 → 0.3.0

package/dist/indexer/resolution-method.js

@@ -0,0 +1,53 @@
+/**
+ * @module indexer/resolution-method
+ *
+ * Authoritative taxonomy for the `resolution_method` column stored on
+ * `symbol_refs`, `type_refs`, and `symbol_relationships`.
+ *
+ * Consumers should import from here rather than using string literals so that
+ * writers (call-graph.ts) and readers (graph.ts) stay in sync.
+ */
+/**
+ * Resolution confidence tiers, ordered from highest to lowest confidence.
+ *
+ * - `lsp_definition` — the LSP server returned a precise definition location
+ *   that was mapped to the narrowest enclosing indexed symbol.
+ * - `name_same_file` — no LSP data was available; the callee/type name matched
+ *   exactly one symbol *in the same file* as the reference.
+ * - `name_unique` — no LSP data was available; the callee/type name matched
+ *   exactly one symbol *in the entire index*.
+ * - `external_definition` — the LSP server returned a definition location whose
+ *   path is not in the indexed file set (e.g. node_modules, stdlib).
+ * - `ambiguous_definition` — the LSP server returned a definition location that
+ *   maps to multiple equally-narrow candidate symbols. Manual disambiguation is
+ *   needed.
+ * - `unresolved` — no resolution strategy succeeded. The reference remains a
+ *   dangling name.
+ */
+export const RESOLUTION_METHODS = [
+    'lsp_definition',
+    'name_same_file',
+    'name_unique',
+    'external_definition',
+    'ambiguous_definition',
+    'unresolved',
+];
+/**
+ * Set of resolution methods that indicate a successfully resolved target.
+ * Useful for filtering edges to only include high-confidence results.
+ */
+export const RESOLVED_METHODS = new Set([
+    'lsp_definition',
+    'name_same_file',
+    'name_unique',
+]);
+/**
+ * Set of resolution methods where the target_id is expected to be NULL.
+ * These represent references that could not be mapped to an indexed symbol.
+ */
+export const UNRESOLVED_METHODS = new Set([
+    'external_definition',
+    'ambiguous_definition',
+    'unresolved',
+]);
+//# sourceMappingURL=resolution-method.js.map

package/dist/indexer/resolution-method.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolution-method.js","sourceRoot":"","sources":["../../src/indexer/resolution-method.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,gBAAgB;IAChB,gBAAgB;IAChB,aAAa;IACb,qBAAqB;IACrB,sBAAsB;IACtB,YAAY;CACJ,CAAC;AAKX;;;GAGG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAkC,IAAI,GAAG,CAAC;IACrE,gBAAgB;IAChB,gBAAgB;IAChB,aAAa;CACd,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAkC,IAAI,GAAG,CAAC;IACvE,qBAAqB;IACrB,sBAAsB;IACtB,YAAY;CACb,CAAC,CAAC"}

package/dist/indexer/stages/dependency-api.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @module indexer/stages/dependency-api
+ *
+ * Pipeline stage: index declaration-surface symbols from direct dependencies
+ * (.d.ts files for npm, etc.). Populates `external_symbols`.
+ */
+import type { PipelineContext, PipelineStage } from '../pipeline.js';
+/**
+ * Index exported declarations from direct npm dependencies (.d.ts files).
+ * Stores results in `external_symbols`.
+ */
+export declare class DependencyApiStage implements PipelineStage {
+    readonly name = "dependency-api";
+    private pool;
+    execute(context: PipelineContext, _mode: 'build' | 'update'): Promise<void>;
+    dispose(): Promise<void>;
+}
+//# sourceMappingURL=dependency-api.d.ts.map

package/dist/indexer/stages/dependency-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dependency-api.d.ts","sourceRoot":"","sources":["../../../src/indexer/stages/dependency-api.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAcrE;;;GAGG;AACH,qBAAa,kBAAmB,YAAW,aAAa;IACtD,QAAQ,CAAC,IAAI,oBAAoB;IAEjC,OAAO,CAAC,IAAI,CAA2B;IAEjC,OAAO,CAAC,OAAO,EAAE,eAAe,EAAE,KAAK,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IA+F3E,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAG/B"}

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":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAGlC,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,EAIL,gCAAgC,GACjC,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAElE,iFAAiF;AAEjF;;;GAGG;AACH,MAAM,OAAO,kBAAkB;IACpB,IAAI,GAAG,gBAAgB,CAAC;IAEzB,IAAI,GAAsB,IAAI,CAAC;IAEvC,KAAK,CAAC,OAAO,CAAC,OAAwB,EAAE,KAAyB;QAC/D,MAAM,EAAE,EAAE,EAAE,YAAY,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC;QAE1C,wEAAwE;QACxE,oEAAoE;QACpE,EAAE,CAAC,OAAO,CAAC,8BAA8B,CAAC,CAAC,GAAG,EAAE,CAAC;QAEjD,IAAI,CAAC,OAAO,CAAC,iBAAiB;YAAE,OAAO;QAEvC,IAAI,CAAC,IAAI,GAAG,IAAI,UAAU,EAAE,CAAC;QAE7B,MAAM,kBAAkB,GAAG,sBAAsB,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;QACxE,IAAI,kBAAkB,CAAC,IAAI,KAAK,CAAC;YAAE,OAAO;QAE1C,MAAM,SAAS,GAAG,IAAI,mBAAmB,EAAE,CAAC;QAE5C,2DAA2D;QAC3D,IAAI,cAAc,GAAoC,IAAI,CAAC;QAC3D,IAAI,GAAG,EAAE,OAAO,EAAE,CAAC;YACjB,cAAc,GAAG,IAAI,wBAAwB,CAAC,GAAG,EAAE,YAAY,CAAC,OAAO,CAAC,CAAC;YACzE,MAAM,cAAc,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;QACtD,CAAC;QAED,IAAI,CAAC;YACH,MAAM,oBAAoB,GAAG,EAAE,CAAC,OAAO,CACrC;;;;;;;;;;;;;;kDAc0C,CAC3C,CAAC;YAEF,KAAK,MAAM,CAAC,WAAW,EAAE,eAAe,CAAC,IAAI,kBAAkB,EAAE,CAAC;gBAChE,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,OAAO,EAAE,cAAc,EAAE,WAAW,CAAC,CAAC;gBAChF,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,WAAW,EAAE;oBAAE,SAAS;gBAEnF,MAAM,cAAc,GAAG,2BAA2B,CAAC,UAAU,CAAC,IAAI,eAAe,IAAI,IAAI,CAAC;gBAC1F,MAAM,gBAAgB,GAAG,uBAAuB,CAAC,UAAU,CAAC,CAAC;gBAE7D,KAAK,MAAM,eAAe,IAAI,gBAAgB,EAAE,CAAC;oBAC/C,MAAM,MAAM,GAAG,EAAE,CAAC,YAAY,CAAC,eAAe,EAAE,MAAM,CAAC,CAAC;oBACxD,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;oBACnD,IAAI,CAAC,IAAI;wBAAE,SAAS;oBAEpB,MAAM,MAAM,GAAqB,SAAS,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,eAAe,CAAC,CAAC;oBAClF,MAAM,kBAAkB,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,2BAA2B,CAAC,MAAM,CAAC,CAAC,CAAC;oBAClG,MAAM,cAAc,GAAG,cAAc;wBACnC,CAAC,CAAC,MAAM,cAAc,CAAC,MAAM,CAAC;4BAC5B,QAAQ,EAAE,eAAe;4BACzB,QAAQ,EAAE,YAAY;4BACtB,MAAM;4BACN,OAAO,EAAE,kBAAkB,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;gCAC3C,IAAI,EAAE,MAAM,CAAC,SAAS;gCACtB,SAAS,EAAE,MAAM,CAAC,cAAc,IAAI,CAAC;6BACtC,CAAC,CAAC;yBACJ,CAAC;wBACF,CAAC,CAAC,kBAAkB,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;oBAEvC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,kBAAkB,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;wBACnD,MAAM,MAAM,GAAG,kBAAkB,CAAC,CAAC,CAAC,CAAC;wBACrC,IAAI,CAAC,MAAM;4BAAE,SAAS;wBACtB,MAAM,QAAQ,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC;wBACnC,oBAAoB,CAAC,GAAG,CACtB,WAAW,EACX,cAAc,EACd,eAAe,EACf,MAAM,CAAC,IAAI,EACX,MAAM,CAAC,IAAI,EACX,MAAM,CAAC,SAAS,EAChB,MAAM,CAAC,UAAU,IAAI,IAAI,EACzB,QAAQ,EAAE,qBAAqB,IAAI,IAAI,EACvC,QAAQ,EAAE,kBAAkB,IAAI,IAAI,EACpC,QAAQ,EAAE,aAAa,IAAI,IAAI,EAC/B,QAAQ,EAAE,cAAc,IAAI,IAAI,CACjC,CAAC;oBACJ,CAAC;gBACH,CAAC;YACH,CAAC;QACH,CAAC;gBAAS,CAAC;YACT,IAAI,cAAc,EAAE,CAAC;gBACnB,MAAM,cAAc,CAAC,OAAO,EAAE,CAAC;YACjC,CAAC;QACH,CAAC;IACH,CAAC;IAED,KAAK,CAAC,OAAO;QACX,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAED,iFAAiF;AAEjF,SAAS,sBAAsB,CAAC,OAAe;IAC7C,MAAM,eAAe,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC;IAC3D,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,eAAe,CAAC;QAAE,OAAO,IAAI,GAAG,EAAE,CAAC;IAEtD,MAAM,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,eAAe,EAAE,MAAM,CAAC,CAAC;IACrD,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAIzB,CAAC;IACF,MAAM,IAAI,GAAG,IAAI,GAAG,EAA8B,CAAC;IACnD,KAAK,MAAM,OAAO,IAAI,CAAC,GAAG,CAAC,YAAY,EAAE,GAAG,CAAC,eAAe,EAAE,GAAG,CAAC,gBAAgB,CAAC,EAAE,CAAC;QACpF,IAAI,CAAC,OAAO;YAAE,SAAS;QACvB,KAAK,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;YACtD,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC;gBAAE,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,2BAA2B,CAAC,UAAkB;IACrD,MAAM,eAAe,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,cAAc,CAAC,CAAC;IAC9D,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,eAAe,CAAC;QAAE,OAAO,SAAS,CAAC;IAEtD,MAAM,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,eAAe,EAAE,MAAM,CAAC,CAAC;IACrD,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAyB,CAAC;IACpD,OAAO,GAAG,CAAC,OAAO,CAAC;AACrB,CAAC;AAED,SAAS,uBAAuB,CAAC,UAAkB;IACjD,MAAM,YAAY,GAAa,EAAE,CAAC;IAClC,MAAM,KAAK,GAAa,CAAC,UAAU,CAAC,CAAC;IAErC,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,UAAU,GAAG,KAAK,CAAC,GAAG,EAAE,CAAC;QAC/B,IAAI,CAAC,UAAU;YAAE,SAAS;QAE1B,MAAM,OAAO,GAAG,EAAE,CAAC,WAAW,CAAC,UAAU,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;QACpE,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC5B,IAAI,KAAK,CAAC,IAAI,KAAK,cAAc;gBAAE,SAAS;YAE5C,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;YACnD,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;gBACxB,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;gBACrB,SAAS;YACX,CAAC;YAED,IAAI,KAAK,CAAC,MAAM,EAAE,IAAI,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;gBACjD,YAAY,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YAC9B,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,YAAY,CAAC;AACtB,CAAC;AAED,SAAS,2BAA2B,CAAC,MAAiB;IACpD,IAAI,CAAC,gCAAgC,CAAC,MAAM,CAAC;QAAE,OAAO,KAAK,CAAC;IAC5D,IAAI,MAAM,CAAC,kBAAkB;QAAE,OAAO,IAAI,CAAC;IAC3C,OAAO,CAAC,qBAAqB,CAAC,MAAM,CAAC,CAAC;AACxC,CAAC;AAED,SAAS,qBAAqB,CAAC,MAAiB;IAC9C,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC;IAC5B,IAAI,CAAC,IAAI;QAAE,OAAO,KAAK,CAAC;IAExB,IACE,IAAI,CAAC,IAAI,KAAK,gBAAgB;QAC9B,IAAI,CAAC,IAAI,KAAK,qBAAqB;QACnC,IAAI,CAAC,IAAI,KAAK,oBAAoB,EAClC,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IACE,IAAI,CAAC,IAAI,KAAK,mBAAmB;QACjC,IAAI,CAAC,IAAI,KAAK,uBAAuB;QACrC,IAAI,CAAC,IAAI,KAAK,wBAAwB,EACtC,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,QAAQ,GAAG,IAAI,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC;IAChD,IAAI,CAAC,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5B,OAAO,QAAQ,CAAC,eAAe,GAAG,CAAC,IAAI,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC;AACrE,CAAC"}

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"}