@wrongstack/tools 0.284.0 → 0.285.0

package/dist/codebase-index/index.d.ts

@@ -1,275 +1,27 @@
-import { I as IndexResult, S as Symbol, F as FileMeta, a as SymbolKind, b as SymbolLang, c as SearchResult, d as IndexStats, R as Ref } from '../background-indexer-BeDBxfSh.js';
-export { C as CircuitOpenError, e as CircuitSnapshot, f as CircuitState, g as FileSymbols, h as IndexCircuitBreaker, i as IndexTimeoutError, j as SCHEMA_VERSION, k as cancelPendingReindexes, l as codebaseIndexStats, m as codebaseIndexTool, n as codebaseSearchTool, o as codebaseStatsTool, p as enqueueReindex, q as getIndexState, r as indexCircuitBreaker, s as isIndexReady, t as isIndexableFile, u as isIndexing, v as onIndexStateChange, w as resetIndexCircuitBreaker, x as runStartupIndex, y as searchCodebaseIndex, z as shutdownCodebaseIndexHost } from '../background-indexer-BeDBxfSh.js';
-import { Context } from '@wrongstack/core';
-
-interface IndexerOptions {
-    projectRoot: string;
-    files?: string[] | undefined;
-    force?: boolean | undefined;
-    langs?: string[] | undefined;
-    ignore?: string[] | undefined;
-    /** Override the index directory (default: the global per-project dir). */
-    indexDir?: string | undefined;
-    /**
-     * Signal that cancels indexing cooperatively. Polled at yield points
-     * (file walk, per-file loop) so a hung filesystem won't lock up the
-     * process. When the tool executor's timeout fires, this signal aborts
-     * and `runIndexer` throws, releasing the mutex and resetting flags.
-     */
-    signal?: AbortSignal | undefined;
-    /**
-     * Per-file progress callback. Injected by the caller instead of imported
-     * from the host's module state so the indexer can run inside a worker
-     * thread (worker posts progress messages; inline host updates its state).
-     */
-    onProgress?: ((current: number, total: number) => void) | undefined;
-}
-/** Run a full or incremental index and return statistics. */
-declare function runIndexer(_ctx: Context, opts: IndexerOptions): Promise<IndexResult>;
-
 /**
- * Resolve the per-project index directory. By default it lives under the
- * global project dir (`~/.wrongstack/projects/<hash>/codebase-index`),
- * matching every other piece of per-project state. Callers may pass an
- * explicit `override` (used by tests and any wiring that already resolved the
- * path) to avoid touching the real home directory.
- */
-declare function resolveIndexDir(projectRoot: string, override?: string): string;
-/**
- * Optional index-directory override carried on the run context's `meta` bag.
- * Production leaves it unset (the index resolves to the global per-project
- * dir); tests and bespoke wiring set `meta.codebaseIndexDir` to redirect it.
- */
-declare function codebaseIndexDirOverride(ctx: {
-    meta?: Record<string, unknown>;
-}): string | undefined;
-declare class IndexStore {
-    private db;
-    /** Absolute path to this project's index directory. */
-    private readonly indexDir;
-    /**
-     * True when the SQLite build provides FTS5 (Node's bundled SQLite does).
-     * When false, ranked search falls back to the LIKE + in-process BM25 path.
-     */
-    private ftsAvailable;
-    /**
-     * Cache of prepared statements keyed by their SQL text. `DatabaseSync`
-     * compiles SQL on every `.prepare()` call; for the fixed-SQL methods
-     * (upsertFile, getFileMeta, deleteFile, insertRefs, …) that runs thousands
-     * of times during a full reindex. `StatementSync` objects are reusable
-     * across calls on the same connection, so we compile each distinct SQL once
-     * and reuse it. Cleared in {@link close} when the connection is torn down.
-     */
-    private readonly stmtCache;
-    /** Prepare-once helper: compile `sql` on first use, reuse thereafter. */
-    private stmt;
-    /**
-     * Execute a SQLite write operation with automatic retry on lock conflicts.
-     *
-     * When another wstack process is holding the write lock the statement first
-     * waits up to `busy_timeout` ms, then throws SQLITE_BUSY.  This wrapper catches
-     * that error and retries (up to MAX_LOCK_RETRIES) with exponential backoff,
-     * giving the competing writer time to finish and release the lock.
-     *
-     * @param fn  The write operation to execute. Can return a value which is
-     *            returned to the caller on success.
-     * @throws   {@link LockError} when all retries are exhausted on a lock conflict
-     *            (non-lock errors always propagate on the first attempt).
-     */
-    runWithRetry<T>(fn: () => T): T;
-    constructor(projectRoot: string, opts?: {
-        indexDir?: string | undefined;
-    });
-    private initSchema;
-    /**
-     * Insert symbols, assigning IDs atomically inside `BEGIN IMMEDIATE` /
-     * `COMMIT`. The ID allocation (`SELECT MAX(id)`) and all `INSERT`s share
-     * the same transaction, preventing UNIQUE constraint violations when two
-     * processes index concurrently (each would see a different `MAX(id)` and
-     * neither can insert with the other's IDs).
-     *
-     * @returns The symbols array with `id` fields populated so the caller can
-     *          use them for refs without re-reading from the DB.
-     */
-    insertSymbols(symbols: Symbol[]): Symbol[];
-    deleteSymbolsForFile(file: string): void;
-    /**
-     * Remove every trace of a file (refs, symbols, FTS rows, file meta). Used
-     * when a source file disappears between index runs — previously this only
-     * dropped the `files` row, leaving its symbols orphaned but still searchable.
-     */
-    deleteFile(file: string): void;
-    upsertFile(meta: FileMeta): void;
-    getFileMeta(file: string): FileMeta | null;
-    getAllFileMetas(): FileMeta[];
-    search(query: string, filter?: {
-        kind?: SymbolKind | undefined;
-        lang?: SymbolLang | undefined;
-        file?: string | undefined;
-        lspKind?: number | undefined;
-    }): SearchResult[];
-    /**
-     * Ranked search — the one-stop query the codebase-search tool and plug-lsp
-     * use. With FTS5 this is a single indexed `MATCH` ranked by SQLite's native
-     * `bm25()` with a built-in `snippet()`; without FTS5 it falls back to the
-     * legacy LIKE scan + in-process BM25 (identical semantics, slower).
-     *
-     * Tokens are matched as prefixes (`"tok"*`), mirroring the old
-     * `LIKE '%tok%'` recall for the common symbol-search shapes ("user" finds
-     * "users", camelCase-split text makes "complex" find "complexOperation").
-     */
-    searchRanked(query: string, filter: {
-        kind?: SymbolKind | undefined;
-        lang?: SymbolLang | undefined;
-        file?: string | undefined;
-        lspKind?: number | undefined;
-    } | undefined, limit: number): {
-        results: SearchResult[];
-        total: number;
-    };
-    /** Legacy ranked path: LIKE candidates + in-process BM25 + JS snippets. */
-    private searchRankedFallback;
-    getAllIndexable(): Array<{
-        id: number;
-        text: string;
-    }>;
-    /**
-     * Largest symbol id currently in the table (0 when empty). New ids must be
-     * allocated from this, NOT from `COUNT(*)`: incremental reindexes delete a
-     * changed file's rows, so the row count drops below the max id and a
-     * count-based id would collide with a surviving row (UNIQUE constraint on
-     * `symbols.id`). Ids may have gaps — that is fine.
-     */
-    getMaxSymbolId(): number;
-    getStats(): IndexStats;
-    setLastIndexed(ts: number): void;
-    clearAll(): void;
-    /**
-     * Insert cross-references for a given source symbol id.
-     * Replaces any existing refs from the same source (idempotent on re-index).
-     */
-    insertRefs(fromId: number, refs: Ref[]): void;
-    /**
-     * Bulk-insert refs for many source symbols in a single transaction.
-     *
-     * Unlike {@link insertRefs} this does NOT delete per source id — the caller
-     * (the indexer) has already cleared stale refs for the file via
-     * {@link deleteRefsForFile}, so the per-source DELETE would be redundant work
-     * repeated once per symbol. One transaction for the whole file instead of one
-     * per symbol turns an O(symbols) transaction count into O(1).
-     *
-     * Each ref's own {@link Ref.fromId} is used; pass an empty array to no-op.
-     */
-    insertRefsBatch(refs: Ref[]): void;
-    /**
-     * Commit a batch of file-level symbol/refs/upserts in a single transaction.
-     *
-     * Used by the indexer to amortize SQLite commit overhead across many files.
-     * Before this, the indexer issued one transaction per file (BEGIN IMMEDIATE
-     * for symbols, plus per-file deletes and an upsertFile call), so a 20-file
-     * parallel batch cost ~5+ transactions × 20 files = 100+ commits. With
-     * this entry point we do exactly one BEGIN/COMMIT per parallel batch.
-     *
-     * Each entry must already be a fully-parsed FileSymbols (symbols + refs).
-     * The caller is responsible for the per-file prefix accounting
-     * (refsByLine → flat list with `fromId` populated). `deleteForFiles` lets
-     * the caller clear stale symbols/refs for any files being re-indexed before
-     * the inserts run (required to keep refs → symbols FK invariants).
-     *
-     * Returns the symbols back with their assigned `id` (same shape as
-     * {@link insertSymbols}) so callers can build final per-file results.
-     */
-    commitBatch(entries: Array<{
-        file: string;
-        lang: SymbolLang;
-        symbols: Symbol[];
-        refs: Ref[];
-        mtimeMs: number;
-        symbolCount: number;
-    }>, options?: {
-        deleteForFiles?: string[] | undefined;
-    }): Symbol[];
-    /**
-     * Delete all refs whose source symbols are in a given file.
-     * Used when re-indexing a file to clear stale refs.
-     */
-    deleteRefsForFile(file: string): void;
-    /**
-     * Resolve `to_name` → `to_id` for all refs that have a name but no id.
-     * Call this after all symbols have been inserted to fill in cross-references.
-     *
-     * Single statement: the `to_name IN (SELECT name FROM symbols)` guard restricts
-     * the UPDATE to refs that will actually resolve, so `.changes` counts only refs
-     * that found a target — matching the previous per-row loop's return value.
-     */
-    resolveRefs(): number;
-    /**
-     * Find all references TO a given symbol (who calls / uses this symbol?).
-     */
-    findRefsTo(symbolId: number): Ref[];
-    /**
-     * Find all references FROM a given symbol (what does this symbol call/use?).
-     */
-    findRefsFrom(symbolId: number): Ref[];
-    private sizeBytes;
-    close(): void;
-}
-
-/**
- * BM25 ranking implementation — no external dependencies.
+ * @wrongstack/tools – Codebase Index
  *
- * Algorithm: Okapi BM25 with standard parameters (k1=1.5, b=0.75).
- */
-interface Bm25Doc {
-    id: number;
-    tokens: string[];
-    raw: string;
-    len: number;
-}
-/** Tokenise a string into lowercase word tokens. */
-declare function tokenise(text: string): string[];
-interface IndexableDoc {
-    id: number;
-    text: string;
-}
-/**
- * Build indexable text for BM25 from a symbol's fields.
- * The name is split into camelCase/SnakeCase words so that queries
- * like "complex" match "complexOperation". The verbatim name is
- * also included for exact-match queries.
- */
-declare function buildIndexableText(name: string, signature: string, docComment: string): string;
-declare function buildBm25Index(docs: IndexableDoc[]): Bm25Index;
-declare class Bm25Index {
-    private documents;
-    private df;
-    private N;
-    private readonly safeAvgLen;
-    constructor(documents: Bm25Doc[], df: Record<string, number>, N: number, avgLen: number);
-    score(query: string, filter?: (id: number) => boolean): Array<{
-        id: number;
-        score: number;
-    }>;
-    getDoc(id: number): Bm25Doc | undefined;
-    extractSnippet(docId: number, queryTokens: string[], radius?: number): string;
-}
-
-/**
- * LSP SymbolKind mapping utilities.
+ * Three tools for building and querying a symbol index:
  *
- * LSP SymbolKind numbers are defined by vscode-languageserver-protocol.
- * This module maps between LSP kind numbers and the internal SymbolKind taxonomy.
- */
-
-/**
- * Maps an LSP kind number to the corresponding internal SymbolKind.
- * Returns null if the LSP kind has no equivalent in the internal taxonomy.
- */
-declare function lspKindToInternalKind(k: number): SymbolKind | null;
-/**
- * Maps an internal SymbolKind to the corresponding LSP kind number.
- * Returns null if the internal kind has no equivalent LSP kind.
+ *   `codebase-index`  — run the indexer (full or incremental)
+ *   `codebase-search` — BM25-ranked symbol search
+ *   `codebase-stats`  — index health and statistics
+ *
+ * Storage: `~/.wrongstack/projects/<hash>/codebase-index/index.db`
+ *          (outside the repo — no gitignore needed)
+ * Parser:  TypeScript Compiler API (ts-morph-free, via `@typescript/typescript6`)
+ * Ranking: Okapi BM25 with k1=1.5, b=0.75
  */
-declare function internalKindToLspKind(k: SymbolKind): number | null;
-
-export { FileMeta, IndexResult, IndexStats, IndexStore, SearchResult, Symbol, SymbolKind, SymbolLang, buildBm25Index, buildIndexableText, codebaseIndexDirOverride, internalKindToLspKind, lspKindToInternalKind, resolveIndexDir, runIndexer, tokenise };
+export { codebaseIndexTool } from './codebase-index-tool.js';
+export { codebaseSearchTool } from './codebase-search-tool.js';
+export { codebaseStatsTool } from './codebase-stats-tool.js';
+export { runIndexer } from './indexer.js';
+export { runStartupIndex, enqueueReindex, isIndexableFile, cancelPendingReindexes, isIndexReady, isIndexing, getIndexState, onIndexStateChange, searchCodebaseIndex, codebaseIndexStats, shutdownCodebaseIndexHost, } from './background-indexer.js';
+export { IndexCircuitBreaker, indexCircuitBreaker, resetIndexCircuitBreaker, CircuitOpenError, IndexTimeoutError, } from './circuit-breaker.js';
+export type { CircuitState, CircuitSnapshot } from './circuit-breaker.js';
+export { IndexStore, resolveIndexDir, codebaseIndexDirOverride } from './writer.js';
+export { tokenise, buildIndexableText, buildBm25Index, } from './bm25.js';
+export { internalKindToLspKind, lspKindToInternalKind, } from './lsp-kind.js';
+export type { Symbol, SymbolKind, SymbolLang, FileSymbols, FileMeta, IndexStats, IndexResult, SearchResult, } from './schema.js';
+export { SCHEMA_VERSION } from './schema.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/codebase-index/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/codebase-index/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAI7D,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EACL,eAAe,EACf,cAAc,EACd,eAAe,EACf,sBAAsB,EACtB,YAAY,EACZ,UAAU,EACV,aAAa,EACb,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,yBAAyB,GAC1B,MAAM,yBAAyB,CAAC;AAIjC,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,wBAAwB,EACxB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAI1E,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AACpF,OAAO,EACL,QAAQ,EACR,kBAAkB,EAClB,cAAc,GACf,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,eAAe,CAAC;AAGvB,YAAY,EACV,MAAM,EACN,UAAU,EACV,UAAU,EACV,WAAW,EACX,QAAQ,EACR,UAAU,EACV,WAAW,EACX,YAAY,GACb,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC"}