@amsterdamdatalabs/enact-docs-search 0.1.0

package/dist/storage/document-store.js

@@ -0,0 +1,134 @@
+/**
+ * Adapted from obsidian-qmd (MIT): https://github.com/thirteen37/obsidian-qmd
+ * Source: src/storage/DocumentStore.ts — the original had no Obsidian
+ * dependency at all (pure MiniSearch wrapper). Adjustments: added
+ * `startLine` to the indexed schema for path:line output, added a `scope`
+ * pre-filter to `search()`, and dropped the Obsidian-flavoured
+ * `pluginBasePath` option that was already unused upstream.
+ *
+ * DocumentStore provides full-text search using MiniSearch.
+ * Implements proper BM25 ranking with inverted index.
+ */
+import MiniSearch from "minisearch";
+import { scopeOfPath } from "../types.js";
+import { extractQueryTerms, buildSnippet } from "../search/snippet.js";
+const MINISEARCH_OPTIONS = {
+    fields: ["content"],
+    storeFields: ["filePath", "chunkIndex", "mtimeMs", "startLine", "headingBreadcrumb"],
+    searchOptions: {
+        boost: { content: 1 },
+        fuzzy: 0.2,
+        prefix: true,
+    },
+};
+export class DocumentStore {
+    documents = new Map();
+    searchIndex = null;
+    ready = false;
+    async initialize(existingData) {
+        this.documents = new Map();
+        const isValidData = existingData && existingData.index !== undefined && Array.isArray(existingData.documents);
+        if (isValidData) {
+            this.searchIndex = MiniSearch.loadJSON(JSON.stringify(existingData.index), {
+                fields: [...MINISEARCH_OPTIONS.fields],
+                storeFields: [...MINISEARCH_OPTIONS.storeFields],
+            });
+            for (const doc of existingData.documents) {
+                this.documents.set(doc.id, doc);
+            }
+        }
+        else {
+            this.searchIndex = new MiniSearch({
+                fields: [...MINISEARCH_OPTIONS.fields],
+                storeFields: [...MINISEARCH_OPTIONS.storeFields],
+                searchOptions: { ...MINISEARCH_OPTIONS.searchOptions },
+            });
+        }
+        this.ready = true;
+    }
+    isReady() {
+        return this.ready && this.searchIndex !== null;
+    }
+    async indexDocuments(docs) {
+        if (!this.searchIndex)
+            throw new Error("Document store not initialized");
+        for (const doc of docs) {
+            if (this.documents.has(doc.id)) {
+                const existing = this.documents.get(doc.id);
+                this.searchIndex.remove(existing);
+            }
+        }
+        this.searchIndex.addAll(docs);
+        for (const doc of docs) {
+            this.documents.set(doc.id, doc);
+        }
+    }
+    async getDocument(id) {
+        return this.documents.get(id) ?? null;
+    }
+    async deleteByFilePath(filePath) {
+        if (!this.searchIndex)
+            throw new Error("Document store not initialized");
+        const toDelete = [];
+        for (const doc of this.documents.values()) {
+            if (doc.filePath === filePath) {
+                toDelete.push(doc);
+            }
+        }
+        for (const doc of toDelete) {
+            this.searchIndex.remove(doc);
+            this.documents.delete(doc.id);
+        }
+    }
+    /** Search for documents using MiniSearch with BM25 scoring. */
+    async search(query, options = {}) {
+        if (!this.searchIndex)
+            throw new Error("Document store not initialized");
+        const trimmedQuery = query.trim();
+        if (!trimmedQuery)
+            return [];
+        const limit = options.limit ?? 20;
+        const scope = options.scope ?? "all";
+        const miniSearchResults = this.searchIndex.search(trimmedQuery, {
+            filter: (result) => scope === "all" || scopeOfPath(result.filePath) === scope,
+        });
+        const results = [];
+        for (const result of miniSearchResults.slice(0, limit)) {
+            const doc = this.documents.get(result.id);
+            if (!doc)
+                continue;
+            const terms = extractQueryTerms(trimmedQuery);
+            const snippet = await buildSnippet({ filePath: doc.filePath, content: doc.content, startLine: doc.startLine }, terms, options.highlight ?? "plain", options.repoRoot);
+            results.push({
+                id: doc.id,
+                filePath: doc.filePath,
+                chunkIndex: doc.chunkIndex,
+                startLine: doc.startLine,
+                score: result.score,
+                snippet,
+                headingBreadcrumb: doc.headingBreadcrumb,
+                content: doc.content,
+            });
+        }
+        return results;
+    }
+    async getDocumentCount() {
+        return this.documents.size;
+    }
+    async getAllFilePaths() {
+        const filePaths = new Set();
+        for (const doc of this.documents.values()) {
+            filePaths.add(doc.filePath);
+        }
+        return Array.from(filePaths);
+    }
+    export() {
+        if (!this.searchIndex)
+            throw new Error("Document store not initialized");
+        return {
+            documents: Array.from(this.documents.values()),
+            index: this.searchIndex.toJSON(),
+        };
+    }
+}
+//# sourceMappingURL=document-store.js.map

package/dist/storage/document-store.js.map

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

package/dist/storage/persistence.d.ts

@@ -0,0 +1,55 @@
+import type { ExportedDocumentStore } from "./document-store.js";
+import type { SidecarData } from "./vector-store.js";
+import type { Scope } from "../types.js";
+export interface ManifestEntry {
+    /** mtime (epoch ms) at the time this file was last indexed */
+    mtimeMs: number;
+}
+export interface Manifest {
+    /** Schema/model version — bump to force a full rebuild on incompatible change */
+    version: number;
+    /** Embedding model id, so a model change forces re-embedding */
+    embeddingModel: string;
+    /** repo-relative file path -> last-indexed mtime */
+    files: Record<string, ManifestEntry>;
+    /** Informational audit trail: scopes passed to a successful `index` run.
+     *  Not used for freshness logic — see checkFreshness()'s doc comment. */
+    indexedScopes: string[];
+    /** epoch ms of the last successful index run */
+    lastIndexedAt: number;
+}
+export declare const MANIFEST_VERSION = 1;
+export declare const EMBEDDING_MODEL_ID = "Xenova/all-MiniLM-L6-v2";
+/** Deterministic, collision-resistant per-repo cache directory. */
+export declare function repoCacheDir(repoPath: string): string;
+export declare function paths(cacheDir: string): {
+    manifest: string;
+    documentStore: string;
+    vectorIndex: string;
+    vectorSidecar: string;
+};
+export declare function ensureCacheDir(cacheDir: string): Promise<void>;
+export declare function readManifest(cacheDir: string): Promise<Manifest | null>;
+export declare function writeManifest(cacheDir: string, manifest: Manifest): Promise<void>;
+export declare function emptyManifest(): Manifest;
+export declare function readDocumentStoreExport(cacheDir: string): Promise<ExportedDocumentStore | null>;
+export declare function writeDocumentStoreExport(cacheDir: string, data: ExportedDocumentStore): Promise<void>;
+export declare function readVectorSidecar(cacheDir: string): Promise<SidecarData | null>;
+export declare function writeVectorSidecar(cacheDir: string, data: SidecarData): Promise<void>;
+export declare function vectorIndexExists(cacheDir: string): Promise<boolean>;
+export interface FreshnessReport {
+    /** Repo-relative paths that are new, changed, or removed since the last index for this scope. */
+    staleCount: number;
+    /** True if this scope has never been indexed at all. */
+    neverIndexed: boolean;
+}
+/**
+ * Compare the current on-disk files (already filtered to a scope by the
+ * caller) against the manifest, without mutating anything. Used by `query`
+ * to refresh a stale or nonexistent index before searching (I-08).
+ */
+export declare function checkFreshness(manifest: Manifest | null, scope: Scope, currentFiles: {
+    path: string;
+    mtimeMs: number;
+}[]): FreshnessReport;
+//# sourceMappingURL=persistence.d.ts.map

package/dist/storage/persistence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence.d.ts","sourceRoot":"","sources":["../../src/storage/persistence.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEzC,MAAM,WAAW,aAAa;IAC5B,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,QAAQ;IACvB,iFAAiF;IACjF,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,cAAc,EAAE,MAAM,CAAC;IACvB,oDAAoD;IACpD,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACrC;6EACyE;IACzE,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,gDAAgD;IAChD,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAClC,eAAO,MAAM,kBAAkB,4BAA4B,CAAC;AAQ5D,mEAAmE;AACnE,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAKrD;AAOD,wBAAgB,KAAK,CAAC,QAAQ,EAAE,MAAM;;;;;EAOrC;AAED,wBAAsB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEpE;AAED,wBAAsB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAS7E;AAED,wBAAsB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAEvF;AAED,wBAAgB,aAAa,IAAI,QAAQ,CAQxC;AAED,wBAAsB,uBAAuB,CAC3C,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC,CAOvC;AAED,wBAAsB,wBAAwB,CAC5C,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,qBAAqB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAEf;AAED,wBAAsB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAOrF;AAED,wBAAsB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAE3F;AAED,wBAAsB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAI1E;AAED,MAAM,WAAW,eAAe;IAC9B,iGAAiG;IACjG,UAAU,EAAE,MAAM,CAAC;IACnB,wDAAwD;IACxD,YAAY,EAAE,OAAO,CAAC;CACvB;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,QAAQ,GAAG,IAAI,EACzB,KAAK,EAAE,KAAK,EACZ,YAAY,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,EAAE,GAChD,eAAe,CA0BjB"}

package/dist/storage/persistence.js

@@ -0,0 +1,132 @@
+/**
+ * persistence.ts — on-disk cache for one target repo's index.
+ *
+ * Written fresh: obsidian-qmd persists into the Obsidian vault via
+ * localforage/IndexedDB, which has no equivalent outside a browser. This
+ * lays the same DocumentStore/VectorStore export shapes out as plain files
+ * under a per-repo cache directory, plus a manifest that tracks each
+ * indexed file's mtime (for incremental re-indexing) and which scopes have
+ * ever been indexed (so a query can refresh an un-indexed scope instead of
+ * silently returning nothing).
+ */
+import { mkdir, readFile, writeFile, stat } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { scopesToRoots } from "../types.js";
+export const MANIFEST_VERSION = 1;
+export const EMBEDDING_MODEL_ID = "Xenova/all-MiniLM-L6-v2";
+function cacheRoot() {
+    const xdg = process.env.XDG_CACHE_HOME;
+    const base = xdg && xdg.trim().length > 0 ? xdg : join(homedir(), ".cache");
+    return join(base, "enact-docs-search");
+}
+/** Deterministic, collision-resistant per-repo cache directory. */
+export function repoCacheDir(repoPath) {
+    const abs = resolve(repoPath);
+    const hash = createHash("sha256").update(abs).digest("hex").slice(0, 16);
+    const base = abs.split("/").filter(Boolean).pop() ?? "repo";
+    return join(cacheRoot(), `${base}-${hash}`);
+}
+const MANIFEST_FILE = "manifest.json";
+const DOCUMENT_STORE_FILE = "document-store.json";
+const VECTOR_INDEX_FILE = "vector-index.bin";
+const VECTOR_SIDECAR_FILE = "vector-sidecar.json";
+export function paths(cacheDir) {
+    return {
+        manifest: join(cacheDir, MANIFEST_FILE),
+        documentStore: join(cacheDir, DOCUMENT_STORE_FILE),
+        vectorIndex: join(cacheDir, VECTOR_INDEX_FILE),
+        vectorSidecar: join(cacheDir, VECTOR_SIDECAR_FILE),
+    };
+}
+export async function ensureCacheDir(cacheDir) {
+    await mkdir(cacheDir, { recursive: true });
+}
+export async function readManifest(cacheDir) {
+    try {
+        const raw = await readFile(paths(cacheDir).manifest, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (parsed.version !== MANIFEST_VERSION)
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeManifest(cacheDir, manifest) {
+    await writeFile(paths(cacheDir).manifest, JSON.stringify(manifest, null, 2), "utf-8");
+}
+export function emptyManifest() {
+    return {
+        version: MANIFEST_VERSION,
+        embeddingModel: EMBEDDING_MODEL_ID,
+        files: {},
+        indexedScopes: [],
+        lastIndexedAt: 0,
+    };
+}
+export async function readDocumentStoreExport(cacheDir) {
+    try {
+        const raw = await readFile(paths(cacheDir).documentStore, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeDocumentStoreExport(cacheDir, data) {
+    await writeFile(paths(cacheDir).documentStore, JSON.stringify(data), "utf-8");
+}
+export async function readVectorSidecar(cacheDir) {
+    try {
+        const raw = await readFile(paths(cacheDir).vectorSidecar, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeVectorSidecar(cacheDir, data) {
+    await writeFile(paths(cacheDir).vectorSidecar, JSON.stringify(data), "utf-8");
+}
+export async function vectorIndexExists(cacheDir) {
+    return stat(paths(cacheDir).vectorIndex)
+        .then(() => true)
+        .catch(() => false);
+}
+/**
+ * Compare the current on-disk files (already filtered to a scope by the
+ * caller) against the manifest, without mutating anything. Used by `query`
+ * to refresh a stale or nonexistent index before searching (I-08).
+ */
+export function checkFreshness(manifest, scope, currentFiles) {
+    // "Never indexed" is judged by overlap with the manifest, not by a scope
+    // label match: indexing with --scope all and then querying --scope docs
+    // (a subset) is a legitimate, fully-covered case. If there are files on
+    // disk in this scope but none of them appear in the manifest at all, no
+    // index run has ever covered this scope.
+    if (!manifest)
+        return { staleCount: 0, neverIndexed: true };
+    if (currentFiles.length > 0 && currentFiles.every((f) => !(f.path in manifest.files))) {
+        return { staleCount: 0, neverIndexed: true };
+    }
+    let staleCount = 0;
+    const seen = new Set();
+    for (const f of currentFiles) {
+        seen.add(f.path);
+        const entry = manifest.files[f.path];
+        if (!entry || entry.mtimeMs !== f.mtimeMs)
+            staleCount++;
+    }
+    // Files present in the manifest for this scope but deleted on disk also count as stale.
+    const roots = scopesToRoots(scope);
+    for (const path of Object.keys(manifest.files)) {
+        const inScope = roots.some((r) => path === r || path.startsWith(r + "/"));
+        if (inScope && !seen.has(path))
+            staleCount++;
+    }
+    return { staleCount, neverIndexed: false };
+}
+//# sourceMappingURL=persistence.js.map

package/dist/storage/persistence.js.map

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

package/dist/storage/vector-store.d.ts

@@ -0,0 +1,63 @@
+import type { Scope } from "../types.js";
+export declare class DependencyError extends Error {
+}
+export interface VectorDocument {
+    id: string;
+    filePath: string;
+    chunkIndex: number;
+    embedding: number[];
+}
+export interface VectorSearchResult {
+    id: string;
+    filePath: string;
+    chunkIndex: number;
+    /** Cosine similarity score (0-1, higher is closer) */
+    score: number;
+}
+export interface VectorStoreOptions {
+    dimensions: number;
+}
+interface VectorMetadata {
+    id: string;
+    filePath: string;
+    chunkIndex: number;
+}
+export declare class VectorStore {
+    private index;
+    private dimensions;
+    private ready;
+    private idToLabel;
+    private labelToId;
+    private metadata;
+    private nextLabel;
+    private deletedLabels;
+    private maxElements;
+    private readonly M;
+    private readonly efConstruction;
+    private readonly efSearch;
+    constructor(options: VectorStoreOptions);
+    /** Initialize a fresh, empty index. */
+    initialize(): Promise<void>;
+    /** Load a previously persisted index plus its label/metadata sidecar. */
+    loadFromDisk(indexPath: string, sidecar: SidecarData): Promise<void>;
+    /** Persist the raw HNSW index plus the sidecar label/metadata mapping. */
+    saveToDisk(indexPath: string): Promise<SidecarData>;
+    isReady(): boolean;
+    private resizeIfNeeded;
+    add(doc: VectorDocument): Promise<void>;
+    delete(id: string): Promise<void>;
+    deleteByFilePath(filePath: string): Promise<void>;
+    /** Search for similar vectors using HNSW, optionally restricted to a scope. */
+    search(query: number[], k: number, scope?: Scope): Promise<VectorSearchResult[]>;
+    getCount(): Promise<number>;
+    has(id: string): Promise<boolean>;
+}
+export interface SidecarData {
+    idToLabel: [string, number][];
+    metadata: [string, VectorMetadata][];
+    nextLabel: number;
+    deletedLabels: number[];
+    dimensions: number;
+}
+export {};
+//# sourceMappingURL=vector-store.d.ts.map

package/dist/storage/vector-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vector-store.d.ts","sourceRoot":"","sources":["../../src/storage/vector-store.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEzC,qBAAa,eAAgB,SAAQ,KAAK;CAAG;AAyB7C,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,UAAU,cAAc;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,qBAAa,WAAW;IACtB,OAAO,CAAC,KAAK,CAAoC;IACjD,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,KAAK,CAAS;IAEtB,OAAO,CAAC,SAAS,CAAkC;IACnD,OAAO,CAAC,SAAS,CAAkC;IACnD,OAAO,CAAC,QAAQ,CAA0C;IAE1D,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,aAAa,CAAgB;IAErC,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAM;IACxB,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAO;IACtC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAM;gBAEnB,OAAO,EAAE,kBAAkB;IAIvC,uCAAuC;IACjC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAejC,yEAAyE;IACnE,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAgB1E,0EAA0E;IACpE,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAYzD,OAAO,IAAI,OAAO;IAIlB,OAAO,CAAC,cAAc;IAShB,GAAG,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAwBvC,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAcjC,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUvD,+EAA+E;IACzE,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,GAAE,KAAa,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC;IA2CvF,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC;IAI3B,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAGxC;AAED,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;IAC9B,QAAQ,EAAE,CAAC,MAAM,EAAE,cAAc,CAAC,EAAE,CAAC;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;CACpB"}

package/dist/storage/vector-store.js

@@ -0,0 +1,172 @@
+import { scopeOfPath } from "../types.js";
+export class DependencyError extends Error {
+}
+async function loadHierarchicalNSW() {
+    try {
+        const mod = (await import("hnswlib-node"));
+        const HierarchicalNSW = mod.HierarchicalNSW ?? mod.default?.HierarchicalNSW;
+        if (!HierarchicalNSW)
+            throw new Error("HierarchicalNSW export is missing");
+        return HierarchicalNSW;
+    }
+    catch (error) {
+        throw new DependencyError("Semantic search requires hnswlib-node, which is not installed (or its " +
+            "native binding failed to build for this platform).\n" +
+            "Run `npm install` in the enact-docs-search directory, then retry.\n" +
+            `Original error: ${error.message}`);
+    }
+}
+export class VectorStore {
+    index = null;
+    dimensions;
+    ready = false;
+    idToLabel = new Map();
+    labelToId = new Map();
+    metadata = new Map();
+    nextLabel = 0;
+    deletedLabels = [];
+    maxElements = 10000;
+    M = 16;
+    efConstruction = 200;
+    efSearch = 50;
+    constructor(options) {
+        this.dimensions = options.dimensions;
+    }
+    /** Initialize a fresh, empty index. */
+    async initialize() {
+        const HierarchicalNSW = await loadHierarchicalNSW();
+        this.index = new HierarchicalNSW("cosine", this.dimensions);
+        this.index.initIndex(this.maxElements, this.M, this.efConstruction, 100);
+        this.index.setEf(this.efSearch);
+        this.idToLabel.clear();
+        this.labelToId.clear();
+        this.metadata.clear();
+        this.nextLabel = 0;
+        this.deletedLabels = [];
+        this.ready = true;
+    }
+    /** Load a previously persisted index plus its label/metadata sidecar. */
+    async loadFromDisk(indexPath, sidecar) {
+        const HierarchicalNSW = await loadHierarchicalNSW();
+        this.index = new HierarchicalNSW("cosine", this.dimensions);
+        await this.index.readIndex(indexPath, true);
+        this.index.setEf(this.efSearch);
+        this.maxElements = this.index.getMaxElements();
+        this.idToLabel = new Map(sidecar.idToLabel);
+        this.labelToId = new Map(sidecar.idToLabel.map(([id, label]) => [label, id]));
+        this.metadata = new Map(sidecar.metadata);
+        this.nextLabel = sidecar.nextLabel;
+        this.deletedLabels = [...sidecar.deletedLabels];
+        this.ready = true;
+    }
+    /** Persist the raw HNSW index plus the sidecar label/metadata mapping. */
+    async saveToDisk(indexPath) {
+        if (!this.index)
+            throw new Error("Vector store not initialized");
+        await this.index.writeIndex(indexPath);
+        return {
+            idToLabel: Array.from(this.idToLabel.entries()),
+            metadata: Array.from(this.metadata.entries()),
+            nextLabel: this.nextLabel,
+            deletedLabels: [...this.deletedLabels],
+            dimensions: this.dimensions,
+        };
+    }
+    isReady() {
+        return this.ready;
+    }
+    resizeIfNeeded() {
+        if (!this.index)
+            return;
+        const currentCount = this.idToLabel.size;
+        if (currentCount >= this.maxElements - 1) {
+            this.maxElements *= 2;
+            this.index.resizeIndex(this.maxElements);
+        }
+    }
+    async add(doc) {
+        if (!this.ready || !this.index)
+            throw new Error("Vector store not initialized");
+        if (this.idToLabel.has(doc.id)) {
+            await this.delete(doc.id);
+        }
+        this.resizeIfNeeded();
+        // Deliberately not reusing labels from `deletedLabels`: hnswlib-node's
+        // addPoint(..., replaceDeleted=true) label-reuse path is unreliable in
+        // this binding (it can throw "Can't use addPoint to update deleted
+        // elements..." even on a freshly-marked-deleted label). Always taking a
+        // fresh label and leaving markDelete's tombstone in place is simpler and
+        // correct; at this corpus size (~1k chunks) the wasted slots are noise.
+        const label = this.nextLabel++;
+        this.index.addPoint(doc.embedding, label, false);
+        this.idToLabel.set(doc.id, label);
+        this.labelToId.set(label, doc.id);
+        this.metadata.set(doc.id, { id: doc.id, filePath: doc.filePath, chunkIndex: doc.chunkIndex });
+    }
+    async delete(id) {
+        if (!this.ready || !this.index)
+            throw new Error("Vector store not initialized");
+        const label = this.idToLabel.get(id);
+        if (label === undefined)
+            return;
+        this.index.markDelete(label);
+        this.deletedLabels.push(label);
+        this.idToLabel.delete(id);
+        this.labelToId.delete(label);
+        this.metadata.delete(id);
+    }
+    async deleteByFilePath(filePath) {
+        if (!this.ready)
+            throw new Error("Vector store not initialized");
+        const toDelete = [];
+        for (const [id, meta] of this.metadata) {
+            if (meta.filePath === filePath)
+                toDelete.push(id);
+        }
+        for (const id of toDelete)
+            await this.delete(id);
+    }
+    /** Search for similar vectors using HNSW, optionally restricted to a scope. */
+    async search(query, k, scope = "all") {
+        if (!this.ready || !this.index)
+            throw new Error("Vector store not initialized");
+        const actualCount = this.idToLabel.size;
+        if (actualCount === 0)
+            return [];
+        const actualK = Math.min(k, actualCount);
+        const filter = scope === "all"
+            ? undefined
+            : (label) => {
+                const id = this.labelToId.get(label);
+                const meta = id ? this.metadata.get(id) : undefined;
+                return !!meta && scopeOfPath(meta.filePath) === scope;
+            };
+        const result = this.index.searchKnn(query, actualK, filter);
+        const results = [];
+        for (let i = 0; i < result.neighbors.length; i++) {
+            const label = result.neighbors[i];
+            const distance = result.distances[i];
+            const id = this.labelToId.get(label);
+            if (!id)
+                continue;
+            const meta = this.metadata.get(id);
+            if (!meta)
+                continue;
+            const similarity = 1 - distance;
+            results.push({
+                id,
+                filePath: meta.filePath,
+                chunkIndex: meta.chunkIndex,
+                score: Math.max(0, Math.min(1, similarity)),
+            });
+        }
+        return results;
+    }
+    async getCount() {
+        return this.idToLabel.size;
+    }
+    async has(id) {
+        return this.idToLabel.has(id);
+    }
+}
+//# sourceMappingURL=vector-store.js.map

package/dist/storage/vector-store.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Shared types for enact-docs-search.
+ */
+/** The three known knowledge trees, plus "all" meaning all of them together. */
+export type Scope = "docs" | "plans" | "specs" | "all";
+/** Root directory name (relative to the target repo) for each concrete scope. */
+export declare const SCOPE_ROOTS: Record<Exclude<Scope, "all">, string>;
+export declare function scopesToRoots(scope: Scope): string[];
+/** Which concrete scope a repo-relative path belongs to, if any. */
+export declare function scopeOfPath(relPath: string): Exclude<Scope, "all"> | null;
+export type SearchMode = "keyword" | "semantic" | "hybrid";
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,gFAAgF;AAChF,MAAM,MAAM,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,GAAG,KAAK,CAAC;AAEvD,iFAAiF;AACjF,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,MAAM,CAI7D,CAAC;AAEF,wBAAgB,aAAa,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,EAAE,CAGpD;AAED,oEAAoE;AACpE,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,IAAI,CAOzE;AAED,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,UAAU,GAAG,QAAQ,CAAC"}

package/dist/types.js

@@ -0,0 +1,24 @@
+/**
+ * Shared types for enact-docs-search.
+ */
+/** Root directory name (relative to the target repo) for each concrete scope. */
+export const SCOPE_ROOTS = {
+    docs: "docs",
+    plans: ".plans",
+    specs: ".specs",
+};
+export function scopesToRoots(scope) {
+    if (scope === "all")
+        return Object.values(SCOPE_ROOTS);
+    return [SCOPE_ROOTS[scope]];
+}
+/** Which concrete scope a repo-relative path belongs to, if any. */
+export function scopeOfPath(relPath) {
+    for (const [scope, root] of Object.entries(SCOPE_ROOTS)) {
+        if (relPath === root || relPath.startsWith(root + "/")) {
+            return scope;
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,iFAAiF;AACjF,MAAM,CAAC,MAAM,WAAW,GAA0C;IAChE,IAAI,EAAE,MAAM;IACZ,KAAK,EAAE,QAAQ;IACf,KAAK,EAAE,QAAQ;CAChB,CAAC;AAEF,MAAM,UAAU,aAAa,CAAC,KAAY;IACxC,IAAI,KAAK,KAAK,KAAK;QAAE,OAAO,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;IACvD,OAAO,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC;AAC9B,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,WAAW,CAAC,OAAe;IACzC,KAAK,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,CAAC;QACxD,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,CAAC,UAAU,CAAC,IAAI,GAAG,GAAG,CAAC,EAAE,CAAC;YACvD,OAAO,KAA8B,CAAC;QACxC,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}