@jafreck/lore 0.1.0

package/dist/indexer/db.js

@@ -0,0 +1,275 @@
+/**
+ * @module indexer/db
+ *
+ * Opens (or creates) a SQLite knowledge-base database and ensures all
+ * required tables exist.  Vector embedding tables (vec0 virtual tables)
+ * are created separately via `createVec0Tables()` once the embedding
+ * dimensions are known.
+ */
+import Database from 'better-sqlite3';
+import { createRequire } from 'node:module';
+const esmRequire = createRequire(import.meta.url);
+// ─── DDL ─────────────────────────────────────────────────────────────────────
+const DDL = `
+-- Indexed source files.
+CREATE TABLE IF NOT EXISTS files (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  path        TEXT    NOT NULL,
+  branch      TEXT    NOT NULL DEFAULT '',
+  language    TEXT    NOT NULL,
+  size_bytes  INTEGER NOT NULL DEFAULT 0,
+  last_hash   TEXT,
+  indexed_at  INTEGER NOT NULL DEFAULT (unixepoch()),
+  UNIQUE(path, branch)
+);
+
+-- Named symbols extracted from source files.
+CREATE TABLE IF NOT EXISTS symbols (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  file_id     INTEGER NOT NULL REFERENCES files(id) ON DELETE CASCADE,
+  name        TEXT    NOT NULL,
+  kind        TEXT    NOT NULL,
+  start_line  INTEGER NOT NULL,
+  end_line    INTEGER NOT NULL,
+  signature   TEXT,
+  doc_comment TEXT
+);
+
+-- File-linked annotations extracted from comments (e.g. TODO/FIXME/NOTE).
+CREATE TABLE IF NOT EXISTS annotations (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  file_id     INTEGER NOT NULL REFERENCES files(id) ON DELETE CASCADE,
+  kind        TEXT    NOT NULL,
+  line        INTEGER NOT NULL,
+  text        TEXT    NOT NULL,
+  symbol_id   INTEGER REFERENCES symbols(id) ON DELETE SET NULL,
+  author      TEXT,
+  created_at  INTEGER
+);
+
+-- Import / use declarations found in source files.
+CREATE TABLE IF NOT EXISTS file_imports (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  file_id     INTEGER NOT NULL REFERENCES files(id) ON DELETE CASCADE,
+  raw_import  TEXT    NOT NULL,
+  resolved_id INTEGER REFERENCES files(id)
+);
+
+-- Test file to source file mappings derived during indexing.
+CREATE TABLE IF NOT EXISTS test_mappings (
+  test_file_id   INTEGER NOT NULL REFERENCES files(id) ON DELETE CASCADE,
+  source_file_id INTEGER NOT NULL REFERENCES files(id) ON DELETE CASCADE,
+  confidence     TEXT    NOT NULL DEFAULT 'heuristic',
+  UNIQUE(test_file_id, source_file_id)
+);
+
+-- Call-site references from one symbol to another.
+CREATE TABLE IF NOT EXISTS symbol_refs (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  caller_id   INTEGER NOT NULL REFERENCES symbols(id) ON DELETE CASCADE,
+  callee_id   INTEGER REFERENCES symbols(id),
+  callee_name TEXT    NOT NULL,
+  call_line   INTEGER NOT NULL
+);
+
+-- External (third-party / stdlib) dependencies inferred from imports.
+CREATE TABLE IF NOT EXISTS external_deps (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  file_id     INTEGER NOT NULL REFERENCES files(id) ON DELETE CASCADE,
+  package     TEXT    NOT NULL,
+  version     TEXT,
+  UNIQUE(file_id, package)
+);
+
+-- Logical modules grouping related files (e.g. Rust crates, Python packages).
+CREATE TABLE IF NOT EXISTS modules (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  name        TEXT    NOT NULL UNIQUE,
+  kind        TEXT    NOT NULL,
+  manifest    TEXT
+);
+
+-- Many-to-many mapping between files and modules.
+CREATE TABLE IF NOT EXISTS file_modules (
+  file_id   INTEGER NOT NULL REFERENCES files(id)   ON DELETE CASCADE,
+  module_id INTEGER NOT NULL REFERENCES modules(id) ON DELETE CASCADE,
+  PRIMARY KEY (file_id, module_id)
+);
+
+-- LLM-generated natural-language summaries for symbols.
+CREATE TABLE IF NOT EXISTS symbol_summaries (
+  symbol_id INTEGER PRIMARY KEY REFERENCES symbols(id) ON DELETE CASCADE,
+  summary   TEXT    NOT NULL,
+  model     TEXT    NOT NULL,
+  created_at INTEGER NOT NULL DEFAULT (unixepoch())
+);
+
+-- Per-symbol complexity metrics.
+CREATE TABLE IF NOT EXISTS symbol_metrics (
+  symbol_id   INTEGER PRIMARY KEY REFERENCES symbols(id) ON DELETE CASCADE,
+  line_count  INTEGER NOT NULL,
+  param_count INTEGER NOT NULL,
+  cyclomatic  INTEGER NOT NULL,
+  max_nesting INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_symbol_metrics_cyclomatic ON symbol_metrics(cyclomatic);
+
+-- Key-value store for knowledge-base metadata (schema version, embedding model, etc.).
+CREATE TABLE IF NOT EXISTS kb_meta (
+  key   TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+
+-- User and system notes scoped by key/scope pair.
+CREATE TABLE IF NOT EXISTS notes (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  key         TEXT    NOT NULL,
+  scope       TEXT    NOT NULL DEFAULT 'global',
+  content     TEXT    NOT NULL,
+  model       TEXT    NOT NULL DEFAULT '',
+  source_hash TEXT,
+  created_at  INTEGER NOT NULL DEFAULT (unixepoch()),
+  updated_at  INTEGER NOT NULL DEFAULT (unixepoch()),
+  UNIQUE(key, scope)
+);
+
+-- Full-text search index over symbol names, signatures, and kinds (BM25 via FTS5).
+CREATE VIRTUAL TABLE IF NOT EXISTS symbols_fts USING fts5(
+  name, signature, kind
+);
+
+-- Git commit metadata.
+CREATE TABLE IF NOT EXISTS commits (
+  sha         TEXT    PRIMARY KEY,
+  author      TEXT    NOT NULL,
+  author_email TEXT   NOT NULL,
+  timestamp   INTEGER NOT NULL,
+  message     TEXT    NOT NULL,
+  parents     TEXT    NOT NULL DEFAULT '[]'
+);
+
+-- Files touched by each commit (with diff stats).
+CREATE TABLE IF NOT EXISTS commit_files (
+  commit_sha  TEXT    NOT NULL REFERENCES commits(sha) ON DELETE CASCADE,
+  file_path   TEXT    NOT NULL,
+  change_type TEXT    NOT NULL,
+  insertions  INTEGER,
+  deletions   INTEGER,
+  PRIMARY KEY (commit_sha, file_path)
+);
+
+CREATE TABLE IF NOT EXISTS commit_refs (
+  commit_sha  TEXT    NOT NULL REFERENCES commits(sha) ON DELETE CASCADE,
+  ref_name    TEXT    NOT NULL,
+  ref_type    TEXT    NOT NULL,
+  PRIMARY KEY (commit_sha, ref_name)
+);
+
+-- Coverage ingestion runs.
+CREATE TABLE IF NOT EXISTS coverage_runs (
+  id            INTEGER PRIMARY KEY AUTOINCREMENT,
+  commit_sha    TEXT    NOT NULL,
+  source_path   TEXT    NOT NULL,
+  format        TEXT    NOT NULL,
+  ingested_at   INTEGER NOT NULL DEFAULT (unixepoch()),
+  source_mtime  INTEGER
+);
+
+-- Per-file coverage aggregates for each ingestion run.
+CREATE TABLE IF NOT EXISTS coverage_files (
+  run_id        INTEGER NOT NULL REFERENCES coverage_runs(id) ON DELETE CASCADE,
+  file_path     TEXT    NOT NULL,
+  lines_found   INTEGER NOT NULL DEFAULT 0,
+  lines_hit     INTEGER NOT NULL DEFAULT 0,
+  PRIMARY KEY (run_id, file_path)
+);
+
+-- Per-line hit counts for each file in an ingestion run.
+CREATE TABLE IF NOT EXISTS coverage_lines (
+  run_id        INTEGER NOT NULL REFERENCES coverage_runs(id) ON DELETE CASCADE,
+  file_path     TEXT    NOT NULL,
+  line_number   INTEGER NOT NULL,
+  hit_count     INTEGER NOT NULL DEFAULT 0,
+  PRIMARY KEY (run_id, file_path, line_number),
+  FOREIGN KEY (run_id, file_path) REFERENCES coverage_files(run_id, file_path) ON DELETE CASCADE
+);
+
+CREATE TABLE IF NOT EXISTS api_routes (
+  id           INTEGER PRIMARY KEY AUTOINCREMENT,
+  file_id      INTEGER NOT NULL REFERENCES files(id) ON DELETE CASCADE,
+  method       TEXT    NOT NULL,
+  path         TEXT    NOT NULL,
+  handler_id   INTEGER REFERENCES symbols(id) ON DELETE SET NULL,
+  handler_name TEXT    NOT NULL,
+  framework    TEXT    NOT NULL,
+  line         INTEGER NOT NULL,
+  middleware   TEXT,
+  UNIQUE(file_id, method, path)
+);
+
+CREATE INDEX IF NOT EXISTS idx_api_routes_method ON api_routes(method);
+CREATE INDEX IF NOT EXISTS idx_api_routes_path ON api_routes(path);
+CREATE INDEX IF NOT EXISTS idx_annotations_kind ON annotations(kind);
+CREATE INDEX IF NOT EXISTS idx_annotations_file_id ON annotations(file_id);
+CREATE INDEX IF NOT EXISTS idx_coverage_runs_ingested_at ON coverage_runs(ingested_at);
+CREATE INDEX IF NOT EXISTS idx_coverage_files_path ON coverage_files(file_path);
+CREATE INDEX IF NOT EXISTS idx_coverage_lines_path_line ON coverage_lines(file_path, line_number);
+`;
+// ─── Public API ───────────────────────────────────────────────────────────────
+/**
+ * Opens (or creates) the SQLite database at `path` and initialises the schema.
+ *
+ * The returned `Database` instance is opened with WAL mode enabled for
+ * better concurrent read performance.
+ */
+export function openDb(path) {
+    const db = new Database(path);
+    // WAL mode: readers don't block writers, writers don't block readers.
+    db.pragma('journal_mode = WAL');
+    db.pragma('foreign_keys = ON');
+    // Create all tables in a single transaction.
+    db.exec(DDL);
+    return db;
+}
+// ─── kb_meta helpers ──────────────────────────────────────────────────────────
+export const KB_META_INDEX_CHECKPOINT = 'index_checkpoint';
+export const KB_META_LAST_HEAD_SHA = 'last_known_head_sha';
+export const KB_META_COVERAGE_LAST_SOURCE_PATH = 'coverage_last_source_path';
+export const KB_META_COVERAGE_LAST_SOURCE_MTIME = 'coverage_last_source_mtime';
+/** Write (or overwrite) a key-value pair in `kb_meta`. */
+export function setKbMeta(db, key, value) {
+    db.prepare('INSERT OR REPLACE INTO kb_meta (key, value) VALUES (?, ?)').run(key, value);
+}
+/** Read a value from `kb_meta`; returns `undefined` if the key is absent. */
+export function getKbMeta(db, key) {
+    const row = db.prepare('SELECT value FROM kb_meta WHERE key = ?').get(key);
+    return row?.value;
+}
+// ─── Vec0 virtual tables ──────────────────────────────────────────────────────
+/**
+ * Loads the sqlite-vec extension and creates the `symbol_embeddings` and
+ * `symbol_semantic_embeddings` vec0 virtual tables with the given dimension.
+ * Also stores `embedding_dims` in `kb_meta` for validation on reopen.
+ *
+ * This function is idempotent: it is safe to call multiple times with the
+ * same `dims` value.
+ *
+ * @param db   An open better-sqlite3 database instance.
+ * @param dims Embedding dimensionality (e.g. 1024 for Qwen3-Embedding-0.6B).
+ */
+export function createVec0Tables(db, dims) {
+    // Load the sqlite-vec native extension.
+    // Use createRequire for ESM compatibility (native addons cannot be loaded via import()).
+    const sqliteVec = esmRequire('sqlite-vec');
+    sqliteVec.load(db);
+    db.exec(`
+    CREATE VIRTUAL TABLE IF NOT EXISTS symbol_embeddings USING vec0(
+      embedding FLOAT[${dims}]
+    );
+    CREATE VIRTUAL TABLE IF NOT EXISTS symbol_semantic_embeddings USING vec0(
+      embedding FLOAT[${dims}]
+    );
+  `);
+    setKbMeta(db, 'embedding_dims', String(dims));
+}
+//# sourceMappingURL=db.js.map

package/dist/indexer/db.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"db.js","sourceRoot":"","sources":["../../src/indexer/db.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AACtC,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAKlD,gFAAgF;AAEhF,MAAM,GAAG,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4MX,CAAC;AAEF,iFAAiF;AAEjF;;;;;GAKG;AACH,MAAM,UAAU,MAAM,CAAC,IAAY;IACjC,MAAM,EAAE,GAAG,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC;IAE9B,sEAAsE;IACtE,EAAE,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAC;IAChC,EAAE,CAAC,MAAM,CAAC,mBAAmB,CAAC,CAAC;IAE/B,6CAA6C;IAC7C,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAEb,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,iFAAiF;AAEjF,MAAM,CAAC,MAAM,wBAAwB,GAAG,kBAAkB,CAAC;AAC3D,MAAM,CAAC,MAAM,qBAAqB,GAAG,qBAAqB,CAAC;AAC3D,MAAM,CAAC,MAAM,iCAAiC,GAAG,2BAA2B,CAAC;AAC7E,MAAM,CAAC,MAAM,kCAAkC,GAAG,4BAA4B,CAAC;AAE/E,0DAA0D;AAC1D,MAAM,UAAU,SAAS,CAAC,EAAqB,EAAE,GAAW,EAAE,KAAa;IACzE,EAAE,CAAC,OAAO,CAAC,2DAA2D,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;AAC1F,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,SAAS,CAAC,EAAqB,EAAE,GAAW;IAC1D,MAAM,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,yCAAyC,CAAC,CAAC,GAAG,CAAC,GAAG,CAE5D,CAAC;IACd,OAAO,GAAG,EAAE,KAAK,CAAC;AACpB,CAAC;AAED,iFAAiF;AAEjF;;;;;;;;;;GAUG;AACH,MAAM,UAAU,gBAAgB,CAAC,EAAqB,EAAE,IAAY;IAClE,wCAAwC;IACxC,yFAAyF;IACzF,MAAM,SAAS,GAAG,UAAU,CAAC,YAAY,CAA0C,CAAC;IACpF,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEnB,EAAE,CAAC,IAAI,CAAC;;wBAEc,IAAI;;;wBAGJ,IAAI;;GAEzB,CAAC,CAAC;IAEH,SAAS,CAAC,EAAE,EAAE,gBAAgB,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;AAChD,CAAC"}

package/dist/indexer/embedder.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @module indexer/embedder
+ *
+ * Provides an `EmbeddingProvider` abstraction for generating dense vector
+ * embeddings from text. The primary implementation (`SentenceTransformersProvider`)
+ * delegates to a Python subprocess that runs a sentence-transformers model,
+ * communicating over stdin/stdout using newline-delimited JSON (NDJSON).
+ *
+ * The model's embedding dimensionality is auto-detected at startup — the
+ * Python script writes a `{"dims": N}` line before entering the request loop.
+ */
+export interface EmbeddingProvider {
+    /** Embed a batch of texts; returns one float vector per input. */
+    embed(texts: string[]): Promise<number[][]>;
+    /** Human-readable model identifier. */
+    readonly modelName: string;
+    /**
+     * Dimensionality of the returned vectors.
+     * Only valid after `init()` resolves (throws before that).
+     */
+    readonly dims: number;
+    /**
+     * Spawn the Python subprocess, load the model, and detect dim size.
+     * Must be called (and awaited) before the first `embed()` call.
+     */
+    init(): Promise<void>;
+    /** Release the underlying process / resources. */
+    dispose(): Promise<void>;
+}
+/**
+ * Communicates with a Python subprocess via stdin/stdout NDJSON to produce
+ * embeddings using a sentence-transformers compatible model.
+ *
+ * Call `init()` first to spawn the process and detect the model's embedding
+ * dimensionality.  The subprocess is kept alive for the lifetime of the
+ * provider for efficiency.
+ */
+export declare class SentenceTransformersProvider implements EmbeddingProvider {
+    readonly modelName: string;
+    private _dims;
+    private proc;
+    private rl;
+    private readonly pendingRequests;
+    private readonly pythonBin;
+    /** Whether the first stdout line (dims handshake) has been consumed. */
+    private initialized;
+    constructor(modelName: string, pythonBin?: string);
+    /** Embedding dimensionality — available only after `init()`. */
+    get dims(): number;
+    /**
+     * Spawn the Python subprocess, load the model, and read the `{"dims": N}`
+     * handshake line.  This may take a while on first run (model download).
+     */
+    init(): Promise<void>;
+    embed(texts: string[]): Promise<number[][]>;
+    dispose(): Promise<void>;
+    /** Spawn the Python subprocess and wire up the readline interface. */
+    private spawnProcess;
+}
+/** Default embedding model used when no model is explicitly specified. */
+export declare const DEFAULT_EMBEDDING_MODEL = "Qwen/Qwen3-Embedding-4B";
+/**
+ * Creates a `SentenceTransformersProvider` pre-configured for the specified
+ * Qwen3-Embedding model size.
+ *
+ * @param size      Model size variant: `'0.6B'`, `'4B'`, or `'8B'`.
+ * @param pythonBin Path to the Python executable (default: `'python3'`).
+ */
+export declare function Qwen3EmbeddingProvider(size: '0.6B' | '4B' | '8B', pythonBin?: string): SentenceTransformersProvider;
+//# sourceMappingURL=embedder.d.ts.map

package/dist/indexer/embedder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedder.d.ts","sourceRoot":"","sources":["../../src/indexer/embedder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAOH,MAAM,WAAW,iBAAiB;IAChC,kEAAkE;IAClE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAC5C,uCAAuC;IACvC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,kDAAkD;IAClD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAoCD;;;;;;;GAOG;AACH,qBAAa,4BAA6B,YAAW,iBAAiB;IACpE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,OAAO,CAAC,KAAK,CAAuB;IAEpC,OAAO,CAAC,IAAI,CAA6B;IACzC,OAAO,CAAC,EAAE,CAAmC;IAC7C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAwB;IACxD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,wEAAwE;IACxE,OAAO,CAAC,WAAW,CAAS;gBAEhB,SAAS,EAAE,MAAM,EAAE,SAAS,SAAY;IAKpD,gEAAgE;IAChE,IAAI,IAAI,IAAI,MAAM,CAKjB;IAED;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAgCrB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;IAW3C,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAa9B,sEAAsE;IACtE,OAAO,CAAC,YAAY;CAuCrB;AAID,0EAA0E;AAC1E,eAAO,MAAM,uBAAuB,4BAA4B,CAAC;AAEjE;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,EAC1B,SAAS,SAAY,GACpB,4BAA4B,CAG9B"}

package/dist/indexer/embedder.js

@@ -0,0 +1,186 @@
+/**
+ * @module indexer/embedder
+ *
+ * Provides an `EmbeddingProvider` abstraction for generating dense vector
+ * embeddings from text. The primary implementation (`SentenceTransformersProvider`)
+ * delegates to a Python subprocess that runs a sentence-transformers model,
+ * communicating over stdin/stdout using newline-delimited JSON (NDJSON).
+ *
+ * The model's embedding dimensionality is auto-detected at startup — the
+ * Python script writes a `{"dims": N}` line before entering the request loop.
+ */
+import { spawn } from 'node:child_process';
+import * as readline from 'node:readline';
+// ─── Python bootstrap script ──────────────────────────────────────────────────
+/**
+ * Inline Python script that:
+ *   1. Loads the model.
+ *   2. Prints `{"dims": <N>}` on the first stdout line.
+ *   3. Enters an NDJSON request loop (stdin → stdout).
+ *
+ * Model name is received as sys.argv[1].
+ */
+const BOOTSTRAP_SCRIPT = `
+import sys, json
+from sentence_transformers import SentenceTransformer
+model = SentenceTransformer(sys.argv[1], trust_remote_code=True)
+dims = model.get_sentence_embedding_dimension()
+sys.stdout.write(json.dumps({"dims": dims}) + "\\n")
+sys.stdout.flush()
+for line in sys.stdin:
+    line = line.strip()
+    if not line:
+        continue
+    req = json.loads(line)
+    vecs = model.encode(req.get('texts', []), normalize_embeddings=True).tolist()
+    sys.stdout.write(json.dumps({'embeddings': vecs}) + '\\n')
+    sys.stdout.flush()
+`.trimStart();
+/**
+ * Communicates with a Python subprocess via stdin/stdout NDJSON to produce
+ * embeddings using a sentence-transformers compatible model.
+ *
+ * Call `init()` first to spawn the process and detect the model's embedding
+ * dimensionality.  The subprocess is kept alive for the lifetime of the
+ * provider for efficiency.
+ */
+export class SentenceTransformersProvider {
+    modelName;
+    _dims = null;
+    proc = null;
+    rl = null;
+    pendingRequests = [];
+    pythonBin;
+    /** Whether the first stdout line (dims handshake) has been consumed. */
+    initialized = false;
+    constructor(modelName, pythonBin = 'python3') {
+        this.modelName = modelName;
+        this.pythonBin = pythonBin;
+    }
+    /** Embedding dimensionality — available only after `init()`. */
+    get dims() {
+        if (this._dims === null) {
+            throw new Error('EmbeddingProvider not initialised — call init() first');
+        }
+        return this._dims;
+    }
+    /**
+     * Spawn the Python subprocess, load the model, and read the `{"dims": N}`
+     * handshake line.  This may take a while on first run (model download).
+     */
+    async init() {
+        if (this.initialized)
+            return;
+        this.spawnProcess();
+        // The very first line from the subprocess is the dims handshake.
+        return new Promise((resolve, reject) => {
+            const onLine = (line) => {
+                try {
+                    const msg = JSON.parse(line);
+                    if (typeof msg.dims === 'number') {
+                        this._dims = msg.dims;
+                        this.initialized = true;
+                        resolve();
+                    }
+                    else {
+                        reject(new Error(`Unexpected handshake from embedding subprocess: ${line}`));
+                    }
+                }
+                catch (err) {
+                    reject(new Error(`Failed to parse embedding handshake: ${line}`));
+                }
+            };
+            // Read exactly one line for the handshake, then re-wire for embed requests.
+            this.rl.once('line', onLine);
+            // If the process dies before the handshake, reject.
+            this.proc.once('exit', (code) => {
+                if (!this.initialized) {
+                    reject(new Error(`Embedding subprocess exited with code ${code} before handshake`));
+                }
+            });
+        });
+    }
+    async embed(texts) {
+        if (texts.length === 0)
+            return [];
+        if (!this.initialized) {
+            throw new Error('EmbeddingProvider not initialised — call init() first');
+        }
+        return new Promise((resolve, reject) => {
+            this.pendingRequests.push({ resolve, reject });
+            this.proc.stdin.write(JSON.stringify({ texts }) + '\n');
+        });
+    }
+    async dispose() {
+        if (!this.proc)
+            return;
+        const proc = this.proc;
+        this.proc = null;
+        this.rl?.close();
+        this.rl = null;
+        proc.stdin?.end();
+        await new Promise(resolve => {
+            const timeout = setTimeout(() => { proc.kill(); resolve(); }, 5_000);
+            proc.once('close', () => { clearTimeout(timeout); resolve(); });
+        });
+    }
+    /** Spawn the Python subprocess and wire up the readline interface. */
+    spawnProcess() {
+        if (this.proc)
+            return;
+        this.proc = spawn(this.pythonBin, ['-c', BOOTSTRAP_SCRIPT, this.modelName], {
+            stdio: ['pipe', 'pipe', 'inherit'],
+        });
+        this.rl = readline.createInterface({ input: this.proc.stdout });
+        // After init(), all subsequent lines are embed responses.
+        this.rl.on('line', (line) => {
+            // Skip lines until init handshake is done (handled by init's once listener).
+            if (!this.initialized)
+                return;
+            const pending = this.pendingRequests.shift();
+            if (!pending)
+                return;
+            try {
+                const { embeddings } = JSON.parse(line);
+                pending.resolve(embeddings);
+            }
+            catch (err) {
+                pending.reject(err);
+            }
+        });
+        this.proc.on('error', (err) => {
+            const reqs = this.pendingRequests.splice(0);
+            this.proc = null;
+            this.rl = null;
+            for (const r of reqs)
+                r.reject(err);
+        });
+        this.proc.on('exit', (code) => {
+            if (code !== 0 && this.pendingRequests.length > 0) {
+                const err = new Error(`Embedding subprocess exited with code ${code}`);
+                const reqs = this.pendingRequests.splice(0);
+                for (const r of reqs)
+                    r.reject(err);
+            }
+            if (this.proc) {
+                this.proc = null;
+                this.rl = null;
+            }
+        });
+    }
+}
+// ─── Qwen3 factory ────────────────────────────────────────────────────────────
+/** Default embedding model used when no model is explicitly specified. */
+export const DEFAULT_EMBEDDING_MODEL = 'Qwen/Qwen3-Embedding-4B';
+/**
+ * Creates a `SentenceTransformersProvider` pre-configured for the specified
+ * Qwen3-Embedding model size.
+ *
+ * @param size      Model size variant: `'0.6B'`, `'4B'`, or `'8B'`.
+ * @param pythonBin Path to the Python executable (default: `'python3'`).
+ */
+export function Qwen3EmbeddingProvider(size, pythonBin = 'python3') {
+    const modelName = `Qwen/Qwen3-Embedding-${size}`;
+    return new SentenceTransformersProvider(modelName, pythonBin);
+}
+//# sourceMappingURL=embedder.js.map

package/dist/indexer/embedder.js.map

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

package/dist/indexer/ensure-python-deps.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @module indexer/ensure-python-deps
+ *
+ * Validates that the Python environment has the packages required for
+ * embedding generation (`sentence-transformers`, `torch`).  If missing,
+ * attempts an automatic `pip install` before the first embedding run.
+ *
+ * This is only used when `kbIndex.embeddings.enabled` is `true` in the
+ * migration config.
+ */
+/**
+ * Checks whether each of `REQUIRED_PACKAGES` is importable by the given Python
+ * binary.  For any missing package, runs `pip install sentence-transformers`
+ * (which pulls in `torch` as a transitive dependency).
+ *
+ * Throws if the Python binary is not found or if `pip install` fails.
+ *
+ * @param pythonBin  Path to the Python 3 interpreter (default: `'python3'`).
+ * @param timeout    Maximum milliseconds to wait for the install (default: 5 min).
+ */
+export declare function ensurePythonDeps(pythonBin?: string, timeout?: number): Promise<void>;
+//# sourceMappingURL=ensure-python-deps.d.ts.map

package/dist/indexer/ensure-python-deps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ensure-python-deps.d.ts","sourceRoot":"","sources":["../../src/indexer/ensure-python-deps.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAUH;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CACpC,SAAS,SAAY,EACrB,OAAO,SAAa,GACnB,OAAO,CAAC,IAAI,CAAC,CAyBf"}

package/dist/indexer/ensure-python-deps.js

@@ -0,0 +1,47 @@
+/**
+ * @module indexer/ensure-python-deps
+ *
+ * Validates that the Python environment has the packages required for
+ * embedding generation (`sentence-transformers`, `torch`).  If missing,
+ * attempts an automatic `pip install` before the first embedding run.
+ *
+ * This is only used when `kbIndex.embeddings.enabled` is `true` in the
+ * migration config.
+ */
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+/** Python packages required by the sentence-transformers embedding provider. */
+const REQUIRED_PACKAGES = ['sentence_transformers', 'torch'];
+/**
+ * Checks whether each of `REQUIRED_PACKAGES` is importable by the given Python
+ * binary.  For any missing package, runs `pip install sentence-transformers`
+ * (which pulls in `torch` as a transitive dependency).
+ *
+ * Throws if the Python binary is not found or if `pip install` fails.
+ *
+ * @param pythonBin  Path to the Python 3 interpreter (default: `'python3'`).
+ * @param timeout    Maximum milliseconds to wait for the install (default: 5 min).
+ */
+export async function ensurePythonDeps(pythonBin = 'python3', timeout = 5 * 60_000) {
+    // Probe which packages are already available.
+    const missing = [];
+    for (const pkg of REQUIRED_PACKAGES) {
+        try {
+            await execFileAsync(pythonBin, ['-c', `import ${pkg}`], { timeout: 10_000 });
+        }
+        catch {
+            missing.push(pkg);
+        }
+    }
+    if (missing.length === 0)
+        return;
+    // `sentence-transformers` transitively installs torch, so a single pip
+    // install call is sufficient.
+    await execFileAsync(pythonBin, ['-m', 'pip', 'install', '--quiet', 'sentence-transformers'], { timeout });
+    // Verify the install succeeded.
+    for (const pkg of REQUIRED_PACKAGES) {
+        await execFileAsync(pythonBin, ['-c', `import ${pkg}`], { timeout: 10_000 });
+    }
+}
+//# sourceMappingURL=ensure-python-deps.js.map

package/dist/indexer/ensure-python-deps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ensure-python-deps.js","sourceRoot":"","sources":["../../src/indexer/ensure-python-deps.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,MAAM,aAAa,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;AAE1C,gFAAgF;AAChF,MAAM,iBAAiB,GAAG,CAAC,uBAAuB,EAAE,OAAO,CAAC,CAAC;AAE7D;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,SAAS,GAAG,SAAS,EACrB,OAAO,GAAG,CAAC,GAAG,MAAM;IAEpB,8CAA8C;IAC9C,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,KAAK,MAAM,GAAG,IAAI,iBAAiB,EAAE,CAAC;QACpC,IAAI,CAAC;YACH,MAAM,aAAa,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,UAAU,GAAG,EAAE,CAAC,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;QAC/E,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACpB,CAAC;IACH,CAAC;IAED,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IAEjC,uEAAuE;IACvE,8BAA8B;IAC9B,MAAM,aAAa,CACjB,SAAS,EACT,CAAC,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,uBAAuB,CAAC,EAC5D,EAAE,OAAO,EAAE,CACZ,CAAC;IAEF,gCAAgC;IAChC,KAAK,MAAM,GAAG,IAAI,iBAAiB,EAAE,CAAC;QACpC,MAAM,aAAa,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,UAAU,GAAG,EAAE,CAAC,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;IAC/E,CAAC;AACH,CAAC"}

package/dist/indexer/extractors/bash.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @module indexer/extractors/bash
+ *
+ * Bash/Shell language extractor.  Extracts function definitions and `source`
+ * / `.` commands as imports.
+ */
+import type Parser from 'tree-sitter';
+import { type ExtractionResult, type SymbolExtractor } from './types.js';
+export declare class BashExtractor implements SymbolExtractor {
+    extract(tree: Parser.Tree, _source: string, _filePath: string): ExtractionResult;
+}
+//# sourceMappingURL=bash.d.ts.map

package/dist/indexer/extractors/bash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bash.d.ts","sourceRoot":"","sources":["../../../src/indexer/extractors/bash.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,MAAM,MAAM,aAAa,CAAC;AACtC,OAAO,EACL,KAAK,gBAAgB,EAGrB,KAAK,eAAe,EAIrB,MAAM,YAAY,CAAC;AAIpB,qBAAa,aAAc,YAAW,eAAe;IACnD,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,gBAAgB;CAkBjF"}