purecontext-mcp 1.0.1

package/dist/semantic/hnsw-index.js

@@ -0,0 +1,364 @@
+/**
+ * Pure TypeScript HNSW (Hierarchical Navigable Small World) index.
+ *
+ * Implements approximate nearest-neighbor search with O(log n) average-case
+ * complexity via a layered proximity graph.
+ *
+ * Reference: Malkov & Yashunin, 2018
+ * "Efficient and robust approximate nearest neighbor search using
+ *  Hierarchical Navigable Small World graphs"
+ *
+ * Design notes:
+ * - No native addon or WASM dependency — works everywhere Node.js runs.
+ * - Cosine distance metric (L2-normalized input vectors recommended).
+ * - String IDs mapped to integer labels internally for graph adjacency lists.
+ * - Serializes to JSON for persistence (readable, portable).
+ */
+import { readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { dirname } from 'path';
+import { PureContextError } from '../core/errors.js';
+import { logger } from '../core/logger.js';
+function heapPush(heap, entry) {
+    heap.push(entry);
+    let i = heap.length - 1;
+    while (i > 0) {
+        const parent = (i - 1) >> 1;
+        if (heap[parent].dist <= heap[i].dist)
+            break;
+        [heap[parent], heap[i]] = [heap[i], heap[parent]];
+        i = parent;
+    }
+}
+function heapPop(heap) {
+    const top = heap[0];
+    const last = heap.pop();
+    if (heap.length > 0) {
+        heap[0] = last;
+        let i = 0;
+        for (;;) {
+            const l = 2 * i + 1;
+            const r = 2 * i + 2;
+            let smallest = i;
+            if (l < heap.length && heap[l].dist < heap[smallest].dist)
+                smallest = l;
+            if (r < heap.length && heap[r].dist < heap[smallest].dist)
+                smallest = r;
+            if (smallest === i)
+                break;
+            [heap[i], heap[smallest]] = [heap[smallest], heap[i]];
+            i = smallest;
+        }
+    }
+    return top;
+}
+/** Max-heap: largest distance at top — used for the W (working set). */
+function maxHeapPush(heap, entry) {
+    heap.push(entry);
+    let i = heap.length - 1;
+    while (i > 0) {
+        const parent = (i - 1) >> 1;
+        if (heap[parent].dist >= heap[i].dist)
+            break;
+        [heap[parent], heap[i]] = [heap[i], heap[parent]];
+        i = parent;
+    }
+}
+function maxHeapPop(heap) {
+    const top = heap[0];
+    const last = heap.pop();
+    if (heap.length > 0) {
+        heap[0] = last;
+        let i = 0;
+        for (;;) {
+            const l = 2 * i + 1;
+            const r = 2 * i + 2;
+            let largest = i;
+            if (l < heap.length && heap[l].dist > heap[largest].dist)
+                largest = l;
+            if (r < heap.length && heap[r].dist > heap[largest].dist)
+                largest = r;
+            if (largest === i)
+                break;
+            [heap[i], heap[largest]] = [heap[largest], heap[i]];
+            i = largest;
+        }
+    }
+    return top;
+}
+// ─── HNSWIndex ────────────────────────────────────────────────────────────────
+/**
+ * HNSW approximate nearest-neighbor index.
+ *
+ * Usage:
+ * ```typescript
+ * const index = new HNSWIndex(1024, 100_000);
+ * index.add(['id1', 'id2'], [vec1, vec2]);
+ * const results = index.search(queryVec, 10);
+ * index.save('/path/to/hnsw.idx');
+ * ```
+ */
+export class HNSWIndex {
+    dimension;
+    _maxElements;
+    M;
+    /** Max connections at layer 0: 2×M per the paper. */
+    Mmax0;
+    efConstruction;
+    efSearch;
+    nodes = [];
+    idToLabel = new Map();
+    deletedLabels = new Set();
+    entryPoint = null;
+    maxLayer = -1;
+    /** Reciprocal of ln(M) — used for random level generation. */
+    mL;
+    constructor(dimension, _maxElements, M = 16, efConstruction = 200, efSearch = 100) {
+        this.dimension = dimension;
+        this._maxElements = _maxElements;
+        this.M = M;
+        this.Mmax0 = 2 * M;
+        this.efConstruction = efConstruction;
+        this.efSearch = efSearch;
+        this.mL = 1 / Math.log(M);
+    }
+    // ─── Distance ──────────────────────────────────────────────────────────────
+    /**
+     * Cosine distance = 1 - cosine_similarity.
+     * For L2-normalized vectors, this equals the inner product distance.
+     * Range: [0, 2]. Identical vectors → 0. Opposite vectors → 2.
+     */
+    dist(a, b) {
+        let dot = 0;
+        const len = a.length;
+        // Unrolled by 4 for minor speed gain
+        let i = 0;
+        for (; i + 3 < len; i += 4) {
+            dot += a[i] * b[i] + a[i + 1] * b[i + 1] + a[i + 2] * b[i + 2] + a[i + 3] * b[i + 3];
+        }
+        for (; i < len; i++)
+            dot += a[i] * b[i];
+        return 1 - dot;
+    }
+    // ─── Level generation ──────────────────────────────────────────────────────
+    /** Geometric distribution — same formula as the original HNSW paper. */
+    randomLevel() {
+        return Math.floor(-Math.log(Math.random() + Number.EPSILON) * this.mL);
+    }
+    // ─── Core search at a single layer ────────────────────────────────────────
+    /**
+     * Search layer `level` starting from `entryLabel`.
+     * Returns up to `ef` nearest labels, sorted nearest-first.
+     */
+    searchLayer(query, entryLabel, ef, level) {
+        const visited = new Set([entryLabel]);
+        const entryDist = this.dist(query, this.nodes[entryLabel].vector);
+        // C: candidate min-heap (closest at top)
+        const C = [];
+        heapPush(C, { label: entryLabel, dist: entryDist });
+        // W: result max-heap — keeps ef nearest found so far (farthest at top for easy pruning)
+        const W = [];
+        maxHeapPush(W, { label: entryLabel, dist: entryDist });
+        while (C.length > 0) {
+            const c = heapPop(C);
+            // If closest candidate is farther than the farthest in W, we're done
+            if (W.length >= ef && c.dist > W[0].dist)
+                break;
+            const neighbors = this.nodes[c.label].neighbors[level] ?? [];
+            for (const n of neighbors) {
+                if (visited.has(n))
+                    continue;
+                visited.add(n);
+                const nDist = this.dist(query, this.nodes[n].vector);
+                const farthestInW = W[0]?.dist ?? Infinity;
+                if (W.length < ef || nDist < farthestInW) {
+                    heapPush(C, { label: n, dist: nDist });
+                    maxHeapPush(W, { label: n, dist: nDist });
+                    if (W.length > ef) {
+                        maxHeapPop(W);
+                    }
+                }
+            }
+        }
+        // Sort W nearest-first and return labels
+        return W
+            .sort((a, b) => a.dist - b.dist)
+            .map((e) => e.label);
+    }
+    // ─── Neighbor selection ────────────────────────────────────────────────────
+    /**
+     * Select M neighbors from sorted candidates (nearest-first).
+     * Simple heuristic: take the M closest.
+     */
+    selectNeighbors(candidates, M) {
+        return candidates.slice(0, M);
+    }
+    // ─── Insertion ─────────────────────────────────────────────────────────────
+    insertOne(id, vector) {
+        if (this.idToLabel.has(id)) {
+            logger.debug('HNSWIndex: skipping already-indexed id', { id });
+            return;
+        }
+        const label = this.nodes.length;
+        const level = this.randomLevel();
+        const node = {
+            id,
+            vector,
+            neighbors: Array.from({ length: level + 1 }, () => []),
+        };
+        this.nodes.push(node);
+        this.idToLabel.set(id, label);
+        if (this.entryPoint === null) {
+            this.entryPoint = label;
+            this.maxLayer = level;
+            return;
+        }
+        let ep = this.entryPoint;
+        // Phase 1: greedy traversal from top layer to level+1 (ef=1)
+        for (let lc = this.maxLayer; lc > level; lc--) {
+            const results = this.searchLayer(vector, ep, 1, lc);
+            ep = results[0] ?? ep;
+        }
+        // Phase 2: search and connect from min(level, maxLayer) down to 0
+        for (let lc = Math.min(level, this.maxLayer); lc >= 0; lc--) {
+            const candidates = this.searchLayer(vector, ep, this.efConstruction, lc);
+            const Mmax = lc === 0 ? this.Mmax0 : this.M;
+            const newNeighbors = this.selectNeighbors(candidates, Mmax).filter((n) => n !== label);
+            node.neighbors[lc] = newNeighbors;
+            // Bidirectional connection + prune if needed
+            for (const n of newNeighbors) {
+                if (!this.nodes[n].neighbors[lc])
+                    this.nodes[n].neighbors[lc] = [];
+                this.nodes[n].neighbors[lc].push(label);
+                if (this.nodes[n].neighbors[lc].length > Mmax) {
+                    // Prune: keep Mmax closest to n
+                    const nVec = this.nodes[n].vector;
+                    this.nodes[n].neighbors[lc] = this.nodes[n].neighbors[lc]
+                        .map((nb) => ({ nb, d: this.dist(nVec, this.nodes[nb].vector) }))
+                        .sort((a, b) => a.d - b.d)
+                        .slice(0, Mmax)
+                        .map((x) => x.nb);
+                }
+            }
+            ep = candidates[0] ?? ep;
+        }
+        if (level > this.maxLayer) {
+            this.maxLayer = level;
+            this.entryPoint = label;
+        }
+    }
+    // ─── Public API ────────────────────────────────────────────────────────────
+    /**
+     * Insert vectors into the index.
+     * `ids` and `vectors` must be the same length.
+     */
+    add(ids, vectors) {
+        if (ids.length !== vectors.length) {
+            throw new PureContextError(`HNSWIndex.add: ids.length (${ids.length}) !== vectors.length (${vectors.length})`);
+        }
+        for (let i = 0; i < ids.length; i++) {
+            this.insertOne(ids[i], vectors[i]);
+        }
+        logger.debug('HNSWIndex: added vectors', { count: ids.length, total: this.size() });
+    }
+    /**
+     * Search for the `k` nearest neighbors of `query`.
+     * Returns results sorted by ascending distance (nearest first).
+     * Deleted vectors are excluded from results.
+     */
+    search(query, k) {
+        if (this.entryPoint === null || this.nodes.length === 0)
+            return [];
+        if (k <= 0)
+            return [];
+        let ep = this.entryPoint;
+        // Greedy descent to layer 1
+        for (let lc = this.maxLayer; lc > 0; lc--) {
+            const results = this.searchLayer(query, ep, 1, lc);
+            ep = results[0] ?? ep;
+        }
+        // Search at layer 0
+        const ef = Math.max(k, this.efSearch);
+        const candidates = this.searchLayer(query, ep, ef, 0);
+        const out = [];
+        for (const label of candidates) {
+            if (this.deletedLabels.has(label))
+                continue;
+            out.push({ id: this.nodes[label].id, distance: this.dist(query, this.nodes[label].vector) });
+            if (out.length >= k)
+                break;
+        }
+        return out;
+    }
+    /**
+     * Mark vectors as deleted. Deleted vectors are excluded from search results.
+     * Actual storage is reclaimed on `rebuild()`.
+     */
+    remove(ids) {
+        for (const id of ids) {
+            const label = this.idToLabel.get(id);
+            if (label !== undefined) {
+                this.deletedLabels.add(label);
+                logger.debug('HNSWIndex: marked deleted', { id, label });
+            }
+        }
+    }
+    /** Number of live (non-deleted) vectors in the index. */
+    size() {
+        return this.nodes.length - this.deletedLabels.size;
+    }
+    /**
+     * Persist the index to disk as JSON.
+     * Path: typically `~/.purecontext/indexes/{repoId}/hnsw.idx`
+     */
+    save(path) {
+        mkdirSync(dirname(path), { recursive: true });
+        const data = {
+            version: 1,
+            dimension: this.dimension,
+            M: this.M,
+            Mmax0: this.Mmax0,
+            efConstruction: this.efConstruction,
+            efSearch: this.efSearch,
+            entryPoint: this.entryPoint,
+            maxLayer: this.maxLayer,
+            deletedLabels: [...this.deletedLabels],
+            nodes: this.nodes.map((n) => ({
+                id: n.id,
+                vector: Array.from(n.vector),
+                neighbors: n.neighbors,
+            })),
+        };
+        writeFileSync(path, JSON.stringify(data), 'utf8');
+        logger.debug('HNSWIndex: saved to disk', { path, nodes: this.nodes.length });
+    }
+    /**
+     * Load a previously saved index from disk.
+     * Replaces all current state.
+     */
+    load(path) {
+        const raw = readFileSync(path, 'utf8');
+        const data = JSON.parse(raw);
+        if (data.version !== 1) {
+            throw new PureContextError(`HNSWIndex: unsupported index version ${data.version}`);
+        }
+        if (data.dimension !== this.dimension) {
+            throw new PureContextError(`HNSWIndex: dimension mismatch — index has ${data.dimension}, this instance expects ${this.dimension}`);
+        }
+        this.entryPoint = data.entryPoint;
+        this.maxLayer = data.maxLayer;
+        this.deletedLabels.clear();
+        for (const l of data.deletedLabels)
+            this.deletedLabels.add(l);
+        this.nodes = data.nodes.map((n) => ({
+            id: n.id,
+            vector: new Float32Array(n.vector),
+            neighbors: n.neighbors,
+        }));
+        this.idToLabel.clear();
+        for (let label = 0; label < this.nodes.length; label++) {
+            this.idToLabel.set(this.nodes[label].id, label);
+        }
+        logger.debug('HNSWIndex: loaded from disk', { path, nodes: this.nodes.length });
+    }
+}
+//# sourceMappingURL=hnsw-index.js.map

package/dist/semantic/hnsw-index.js.map

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

package/dist/semantic/hybrid-search.d.ts

@@ -0,0 +1,46 @@
+/**
+ * HybridSearcher — combines FTS5 keyword search with HNSW semantic search
+ * using Reciprocal Rank Fusion (RRF).
+ *
+ * Algorithm:
+ *   1. Run FTS5 → get top-N keyword-ranked symbols
+ *   2. Run semantic (HNSW) → get top-N vector-ranked symbols
+ *   3. Merge via RRF: score = kw_weight * 1/(k+kwRank) + sem_weight * 1/(k+semRank)
+ *   4. Sort descending by combined score; return top maxResults
+ *
+ * When no semantic index exists (VectorStore.size === 0), the searcher falls
+ * back to keyword-only mode silently.
+ */
+import type Database from 'better-sqlite3';
+import type { SymbolRecord } from '../core/types.js';
+import type { VectorStore } from './vector-store.js';
+export interface SearchOptions {
+    /** Maximum results to return (default: 10). */
+    maxResults?: number;
+    /** Weight given to keyword rank in RRF (default: 0.5). */
+    keywordWeight?: number;
+    /** Weight given to semantic rank in RRF (default: 0.5). */
+    semanticWeight?: number;
+    /** Minimum combined RRF score to include in results (default: 0). */
+    threshold?: number;
+    /** Filter by symbol kind. */
+    kind?: string;
+    /** Filter by file path prefix. */
+    filePattern?: string;
+    /** Use query expansion to improve recall (default: true). */
+    expandQuery?: boolean;
+}
+export interface HybridSearchResult {
+    symbol: SymbolRecord;
+    keywordScore: number;
+    semanticScore: number;
+    combinedScore: number;
+}
+export declare class HybridSearcher {
+    private readonly repoId;
+    private readonly vectorStore;
+    private readonly db;
+    constructor(repoId: string, vectorStore: VectorStore, db: Database.Database);
+    search(query: string, options?: SearchOptions): Promise<HybridSearchResult[]>;
+}
+//# sourceMappingURL=hybrid-search.d.ts.map

package/dist/semantic/hybrid-search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hybrid-search.d.ts","sourceRoot":"","sources":["../../src/semantic/hybrid-search.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAE3C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAErD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAKrD,MAAM,WAAW,aAAa;IAC5B,+CAA+C;IAC/C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0DAA0D;IAC1D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,2DAA2D;IAC3D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6BAA6B;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kCAAkC;IAClC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6DAA6D;IAC7D,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,YAAY,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;CACvB;AASD,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;IAC1C,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAoB;gBAE3B,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,EAAE,EAAE,QAAQ,CAAC,QAAQ;IAQrE,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC;CAmHxF"}

package/dist/semantic/hybrid-search.js

@@ -0,0 +1,164 @@
+/**
+ * HybridSearcher — combines FTS5 keyword search with HNSW semantic search
+ * using Reciprocal Rank Fusion (RRF).
+ *
+ * Algorithm:
+ *   1. Run FTS5 → get top-N keyword-ranked symbols
+ *   2. Run semantic (HNSW) → get top-N vector-ranked symbols
+ *   3. Merge via RRF: score = kw_weight * 1/(k+kwRank) + sem_weight * 1/(k+semRank)
+ *   4. Sort descending by combined score; return top maxResults
+ *
+ * When no semantic index exists (VectorStore.size === 0), the searcher falls
+ * back to keyword-only mode silently.
+ */
+import { ftsSearchSymbols } from '../core/db/symbol-store.js';
+import { logger } from '../core/logger.js';
+import { expandQuery } from './query-expansion.js';
+// ─── RRF constant ─────────────────────────────────────────────────────────────
+/** Standard RRF k constant — smoothes rank differences. */
+const RRF_K = 60;
+// ─── HybridSearcher ───────────────────────────────────────────────────────────
+export class HybridSearcher {
+    repoId;
+    vectorStore;
+    db;
+    constructor(repoId, vectorStore, db) {
+        this.repoId = repoId;
+        this.vectorStore = vectorStore;
+        this.db = db;
+    }
+    // ─── Public API ────────────────────────────────────────────────────────────
+    async search(query, options = {}) {
+        const { maxResults = 10, keywordWeight = 0.5, semanticWeight = 0.5, threshold = 0, kind, filePattern, expandQuery: doExpand = true, } = options;
+        const hasSemanticIndex = this.vectorStore.size > 0;
+        // Determine effective mode
+        const useKeyword = keywordWeight > 0;
+        const useSemantic = semanticWeight > 0 && hasSemanticIndex;
+        const candidateCount = Math.max(maxResults * 4, 40); // over-fetch for merging
+        // ── Step 1: FTS keyword search ────────────────────────────────────────────
+        const keywordResults = [];
+        if (useKeyword) {
+            const ftsQuery = buildFtsQuery(query);
+            try {
+                const rows = ftsSearchSymbols(this.db, this.repoId, ftsQuery, { limit: candidateCount });
+                keywordResults.push(...rows);
+            }
+            catch {
+                // FTS query can fail on special characters — fall back to empty
+                logger.debug('HybridSearcher: FTS query failed, continuing without keyword results', { query });
+            }
+        }
+        // ── Step 2: Semantic vector search ────────────────────────────────────────
+        const semanticIdsByRank = [];
+        if (useSemantic) {
+            const queries = doExpand ? expandQuery(query) : [query];
+            // Collect semantic hits across all query variations; de-dup by ID, preserve first rank
+            const seenSemantic = new Set();
+            for (const q of queries) {
+                const hits = await this.vectorStore.searchSimilar(q, candidateCount);
+                for (const hit of hits) {
+                    if (!seenSemantic.has(hit.id)) {
+                        seenSemantic.add(hit.id);
+                        semanticIdsByRank.push(hit.id);
+                    }
+                }
+                if (semanticIdsByRank.length >= candidateCount)
+                    break;
+            }
+        }
+        // ── Step 3: Build ranked maps ─────────────────────────────────────────────
+        const kwRankOf = new Map(); // symbolId → 1-based rank
+        for (let i = 0; i < keywordResults.length; i++) {
+            kwRankOf.set(keywordResults[i].id, i + 1);
+        }
+        const semRankOf = new Map(); // symbolId → 1-based rank
+        for (let i = 0; i < semanticIdsByRank.length; i++) {
+            semRankOf.set(semanticIdsByRank[i], i + 1);
+        }
+        // ── Step 4: Collect all candidate symbol IDs ──────────────────────────────
+        const allIds = new Set([
+            ...keywordResults.map((s) => s.id),
+            ...semanticIdsByRank,
+        ]);
+        // ── Step 5: Build symbol map (keyword results already fetched; semantic IDs
+        //            need lookup from DB for symbols not in keyword results) ────────
+        const symbolById = new Map();
+        for (const sym of keywordResults) {
+            symbolById.set(sym.id, sym);
+        }
+        // Fetch semantic-only symbols from DB in one query
+        const missingIds = [...allIds].filter((id) => !symbolById.has(id));
+        if (missingIds.length > 0) {
+            const fetched = fetchSymbolsByIds(this.db, this.repoId, missingIds);
+            for (const sym of fetched) {
+                symbolById.set(sym.id, sym);
+            }
+        }
+        // ── Step 6: RRF scoring ───────────────────────────────────────────────────
+        const scored = [];
+        for (const id of allIds) {
+            const symbol = symbolById.get(id);
+            if (!symbol)
+                continue;
+            // Apply filters
+            if (kind && symbol.kind !== kind)
+                continue;
+            if (filePattern && !symbol.filePath.includes(filePattern))
+                continue;
+            const kwRank = kwRankOf.get(id);
+            const semRank = semRankOf.get(id);
+            const keywordScore = kwRank !== undefined && useKeyword
+                ? keywordWeight * (1 / (RRF_K + kwRank))
+                : 0;
+            const semanticScore = semRank !== undefined && useSemantic
+                ? semanticWeight * (1 / (RRF_K + semRank))
+                : 0;
+            const combinedScore = keywordScore + semanticScore;
+            if (combinedScore < threshold)
+                continue;
+            scored.push({ symbol, keywordScore, semanticScore, combinedScore });
+        }
+        // ── Step 7: Sort and return ───────────────────────────────────────────────
+        scored.sort((a, b) => b.combinedScore - a.combinedScore);
+        return scored.slice(0, maxResults);
+    }
+}
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+/**
+ * Convert a plain search query to a safe FTS5 query string.
+ * Wraps terms in quotes to handle special characters; falls back to
+ * prefix matching for single words.
+ */
+function buildFtsQuery(query) {
+    const words = query.trim().split(/\s+/).filter(Boolean);
+    if (words.length === 0)
+        return '""';
+    // Use prefix matching on each token: `auth*`
+    return words.map((w) => `"${w.replace(/"/g, '""')}"*`).join(' ');
+}
+/**
+ * Bulk-fetch SymbolRecords by ID for a given repo.
+ * Uses a single SQL query with placeholders.
+ */
+function fetchSymbolsByIds(db, repoId, ids) {
+    if (ids.length === 0)
+        return [];
+    const placeholders = ids.map(() => '?').join(',');
+    const rows = db
+        .prepare(`SELECT * FROM symbols WHERE repo_id = ? AND id IN (${placeholders})`)
+        .all(repoId, ...ids);
+    return rows.map((r) => ({
+        id: r.id,
+        name: r.name,
+        kind: r.kind,
+        filePath: r.file_path,
+        startByte: r.start_byte,
+        endByte: r.end_byte,
+        signature: r.signature,
+        summary: r.summary,
+        frameworkMeta: r.framework_meta
+            ? JSON.parse(r.framework_meta)
+            : undefined,
+    }));
+}
+//# sourceMappingURL=hybrid-search.js.map

package/dist/semantic/hybrid-search.js.map

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

package/dist/semantic/query-expansion.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Query expansion — generates lightweight variations of a search query to
+ * improve recall without requiring API calls.
+ *
+ * Techniques:
+ *   - Abbreviation expansion: "auth" → ["authentication", "authorization"]
+ *   - Camel/snake splitting: "getUserById" → ["get", "user", "by", "id"]
+ *   - Common synonym expansion for programming terms
+ */
+/**
+ * Generate query variations for better semantic search coverage.
+ *
+ * The returned array always includes the original query as the first element.
+ * Duplicates are removed. The result is limited to 8 variations to keep
+ * embedding costs bounded.
+ *
+ * @example
+ * expandQuery('auth')
+ * // → ['auth', 'authentication', 'authorization', 'authenticate', 'authorize']
+ *
+ * expandQuery('getUserById')
+ * // → ['getUserById', 'get user by id', 'getuser', 'by', 'id']
+ */
+export declare function expandQuery(query: string): string[];
+//# sourceMappingURL=query-expansion.d.ts.map

package/dist/semantic/query-expansion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-expansion.d.ts","sourceRoot":"","sources":["../../src/semantic/query-expansion.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAkGH;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CA2CnD"}