@wrongstack/tools 0.302.2 → 0.305.0

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

@@ -38,6 +38,13 @@ export interface FileMeta {
     mtimeMs: number;
     symbolCount: number;
     lastIndexed: number;
+    /**
+     * xxHash64 of the file's UTF-8 bytes (Phase 2). `undefined` for callers
+     * that don't compute it; the writer stores an empty string in that case.
+     * The indexer compares this against the current file's hash to skip
+     * re-parsing when content is byte-identical despite an mtime change.
+     */
+    contentHash?: string | undefined;
 }
 /** Statistics about the index. */
 export interface IndexStats {
@@ -69,6 +76,17 @@ export interface SearchResult {
 /** Result of a full reindex. */
 export interface IndexResult {
     filesIndexed: number;
+    /** Outcome detail for this run. Optional for compatibility with older project daemons. */
+    fileOutcomes?: {
+        /** Files parsed and committed with one or more symbols. */
+        parsed: number;
+        /** Files reused from trusted metadata or an unchanged content hash. */
+        skipped: number;
+        /** Files successfully represented in the index with zero symbols. */
+        empty: number;
+        /** Files that could not be read, parsed, or committed. */
+        failed: number;
+    } | undefined;
     symbolsIndexed: number;
     langStats: Record<SymbolLang, number>;
     durationMs: number;

package/dist/codebase-index/tree-sitter/queries.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Per-language tree-sitter node-mapping queries.
+ *
+ * The Day 2-3 skeleton defines the *declaration-kind* surface for each
+ * language: which tree-sitter node types map to which `SymbolKind`, and how
+ * to extract the symbol's name from that node. Ref/import/heritage emission
+ * (calls, type references, extends/implements, include paths) lands on Day 4
+ * alongside the C-family tests, where real AST fixtures prove the mapping.
+ *
+ * Why no tree-sitter queries (the `.scm` query language)?
+ *   The universal visitor (`visitor.ts`) walks the tree by node-type rather
+ *   than running a `.scm` query. A query-based approach would be faster at
+ *   very large scale but adds a second AST traversal pattern and a separate
+ *   grammar file per language. Direct traversal keeps the code shape aligned
+ *   with `ts-parser.ts` and `py-parser.ts` — one recursion, one witness list.
+ *
+ * Each language only needs to fill in the few fields that differ from the
+ * default (see {@link DEFAULT_QUERIES}). The block form in `LANG_QUERIES`
+ * documents the full set of fields exhaustively so the next reader can see
+ * at a glance what a language can override.
+ */
+import type { SymbolKind, SymbolLang } from '../schema.js';
+/**
+ * Declarations worth indexing for a language.
+ *
+ *   `declKinds`    — map of `tree-sitter node.type` → `SymbolKind`.
+ *   `nameField`    — node field name that carries the identifier; defaults
+ *                    to `'name'`. Some grammars expose a `declarator` field
+ *                    that wraps a `pointer_declarator` or `function_declarator`.
+ *   `nameExtractor` — optional escape hatch for languages (e.g. Elixir)
+ *                    whose declaration shape doesn't have a clean `name` field.
+ *   `scopeNodes`   — node types that push a new scope onto the visitor's
+ *                    stack. Class/struct/namespace/interface/impl/module.
+ *   `skipNamedChildren` — when true, the visitor does not recurse into
+ *                    named children of a declaration node. Set for languages
+ *                    where the parent itself is the only indexable unit
+ *                    (rare; default false).
+ */
+export interface NodeQueries {
+    declKinds: Record<string, SymbolKind>;
+    nameField?: Partial<Record<string, string>>;
+    nameExtractor?: (node: import('web-tree-sitter').Node) => string | null;
+    scopeNodes?: ReadonlySet<string>;
+    skipNamedChildren?: boolean;
+}
+/** Resolve the queries for a language, falling back to the default. */
+export declare function getQueries(lang: SymbolLang): NodeQueries;
+//# sourceMappingURL=queries.d.ts.map

package/dist/codebase-index/tree-sitter/util.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Shared helpers for the tree-sitter extractor.
+ *
+ * Newline-offset binary search is the same pattern `generic-parser.ts` and
+ * `import-extractor.ts` use: precompute the offset of every `\n` once per
+ * file, then resolve match→line in O(log n) instead of O(n). Tree-sitter
+ * gives us `{ row, column }` directly, but we need the same conversion for
+ * identifiers that we extract from arbitrary child nodes whose byte offset
+ * we have to translate into 1-based line + 0-based col ourselves.
+ */
+/** 1-based {line, col} for a byte offset, using binary search over newline offsets. */
+export declare function lineColAt(offsets: readonly number[], index: number): {
+    line: number;
+    col: number;
+};
+/**
+ * Precompute newline offsets once per file. The cost is a single O(n) scan
+ * of the buffer; subsequent lookups (typically dozens to hundreds per file)
+ * are O(log n) instead of O(n).
+ */
+export declare function newlineOffsets(content: string): number[];
+/**
+ * Cap the source the visitor walks, mirroring `GENERIC_MAX_FILE_CHARS` in
+ * `generic-parser.ts`. Files larger than this get sliced; the rest is dropped
+ * from the index. Mirrors the safety net that the regex extractor already
+ * applies — without it, a multi-MB blob can blow the AST heap.
+ */
+export declare const TREE_SITTER_MAX_FILE_CHARS: number;
+/** Soft cap on symbols per file (matches `GENERIC_MAX_SYMBOLS_DEFAULT`). */
+export declare const TREE_SITTER_MAX_SYMBOLS = 500;
+//# sourceMappingURL=util.d.ts.map

package/dist/codebase-index/tree-sitter/visitor.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Universal Tree-Sitter AST visitor.
+ *
+ * Walks a parsed syntax tree, applying the per-language {@link NodeQueries}
+ * table, and produces an indexed symbol list. Ref emission (calls, type
+ * references, imports, heritage) is intentionally out of scope here — it
+ * ships on Day 4 alongside the C-family tests, where per-language fixtures
+ * can verify each `callType` mapping.
+ *
+ * The visitor is O(n) over named children: each node is visited at most
+ * once, and the scope stack is push/pop in O(1). The cost on a 50k-file
+ * monorepo is dominated by `Parser.parse(content)` itself, which tree-sitter
+ * implements as a single-pass GLR parse in WASM.
+ *
+ * Two design rules that shaped this module:
+ *
+ *   1. **Recursive scope tracking, not parent-chain walks.** `ts-parser.ts`
+ *      pushed scope parts onto an array and trimmed on return; we mirror
+ *      that. The cost is O(depth) push/pop instead of O(depth × symbols)
+ *      parent walks — for a 200-symbol file at depth 5, that's 1000 fewer
+ *      `parent` lookups.
+ *
+ *   2. **Identifier extraction has two shapes.** Most languages give you a
+ *      `name` field on the declaration node; a handful (C declarators,
+ *      Elixir calls) don't. The visitor tries `queries.nameExtractor` first,
+ *      then falls back to `queries.nameField[type] ?? 'name'`, then gives
+ *      up — emitting no symbol for that node rather than fabricating one.
+ */
+import type { Tree } from 'web-tree-sitter';
+import type { Symbol as IndexSymbol, SymbolLang } from '../schema.js';
+import type { NodeQueries } from './queries.js';
+/** Result of walking one parsed file. */
+export interface VisitResult {
+    symbols: IndexSymbol[];
+}
+/**
+ * Walk a parsed tree and emit symbols.
+ *
+ *   `tree`     — the parsed syntax tree.
+ *   `content`  — original source text. Used to derive `signature` (the
+ *                declaration node's slice of the source) and `docComment`.
+ *   `file`     — absolute path, threaded into every emitted symbol.
+ *   `lang`     — the language the tree was parsed under.
+ *   `queries`  — per-language node-mapping table.
+ */
+export declare function visitTree(tree: Tree, content: string, file: string, lang: SymbolLang, queries: NodeQueries): VisitResult;
+//# sourceMappingURL=visitor.d.ts.map

package/dist/codebase-index/tree-sitter-parser.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Tree-Sitter WASM Universal AST Extractor (Phase 1).
+ *
+ * Replaces regex heuristics in `generic-parser.ts` for languages with a
+ * pre-compiled tree-sitter grammar: C, C++, Java, C#, PHP, Ruby, Swift,
+ * Kotlin, Elixir, Shell (bash), plus Go/Python/Rust as opt-in WASM paths
+ * (default behavior still uses the existing first-class parsers).
+ *
+ * The runtime contract matches {@link parseGeneric}: callers receive a
+ * {@link FileSymbols} record. Symbol ids are always 0 — the caller assigns
+ * them during bulk insertion. Refs carry `fromId: 0` and are deduplicated
+ * downstream by `parser-dispatch.ts#withRelations`.
+ *
+ * Design notes:
+ *   - Grammar WASM files live alongside the runtime in `wasm/<lang>/`.
+ *     Vendoring them in-tree makes builds deterministic; no fetch-on-first-run.
+ *   - The {@link web-tree-sitter} runtime is initialized once per process.
+ *     `Language.load(wasmPath)` resolves on the first parse of each language
+ *     and is memoized — every subsequent parse reuses the same Language object.
+ *   - On any failure (grammar file missing, runtime not installed, parse error
+ *     with no recoverable symbols) this module returns an empty `symbols[]`
+ *     rather than throwing — matching the existing parsers' "never drops a
+ *     file from the index" contract.
+ */
+import type { FileSymbols, SymbolLang } from './schema.js';
+/** True when this lang has a tree-sitter grammar available right now. */
+export declare function isTreeSitterSupported(lang: SymbolLang): boolean;
+/** Visible for tests: the absolute path to a vendored grammar WASM. */
+export declare function getGrammarWasmPath(lang: SymbolLang): string | undefined;
+/**
+ * Async entry point mirroring {@link parseGeneric}. Used by
+ * `parser-dispatch.ts` via dynamic import. Returns an empty `symbols[]`
+ * on any failure rather than throwing — the dispatch layer falls back to
+ * `generic-parser` for regex coverage when this returns zero symbols.
+ *
+ * Symbol emission is *not* implemented in this file yet — this Day-1
+ * scaffold only proves grammar loading and parsing work end-to-end.
+ * Day 2-3 introduces the universal visitor (`tree-sitter/visitor.ts`)
+ * and per-language query tables (`tree-sitter/queries.ts`).
+ */
+export declare function parseSymbols(opts: {
+    file: string;
+    content: string;
+    lang: SymbolLang;
+}): Promise<FileSymbols>;
+/**
+ * Internal helper used by AST-shape inspectors and tests. Loads and caches
+ * the tree-sitter `Language` for a given {@link SymbolLang} without parsing.
+ * Not part of the public parser API — the indexer should always go through
+ * {@link parseSymbols}.
+ */
+export declare function loadTreeSitterLanguage(lang: SymbolLang): Promise<import('web-tree-sitter').Language>;
+/** Test-only helper: parse and return the root node type. Throws on failure. */
+export declare function __smokeRootType(opts: {
+    content: string;
+    lang: SymbolLang;
+}): Promise<string>;
+//# sourceMappingURL=tree-sitter-parser.d.ts.map

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

@@ -0,0 +1,62 @@
+/**
+ * Phase 3: Hybrid Search Engine — vector embedding layer + RRF fusion.
+ *
+ * This module provides:
+ *  - **Symbol embeddings**: a lightweight character n-gram TF-IDF representation
+ *    of each symbol's text (name + signature + doc comment), producing a fixed
+ *    384-dimensional float32 vector. No native deps (no ONNX runtime). Designed
+ *    to be swapped for a real transformer embedding model in a future phase
+ *    without changing the storage or fusion interface.
+ *  - **Cosine similarity**: ranks symbols by vector proximity to a query vector.
+ *  - **Reciprocal Rank Fusion (RRF)**: merges the ranked lists from BM25/FTS5
+ *    trigram search and vector search into a single result set.
+ *
+ * The RRF formula (k=60, following the original Cormack et al. 2009 paper):
+ *   RRF_Score(d) = 1/(k + Rank_BM25(d)) + 1/(k + Rank_Vector(d))
+ * where a missing rank from either source is treated as infinity (contributes 0).
+ */
+/** The constant k in the RRF formula — the standard value from the literature. */
+export declare const RRF_K = 60;
+/** Fixed vector dimensionality. 384 matches the proposal's spec. */
+export declare const VECTOR_DIMENSIONS = 384;
+/**
+ * Compute a fixed-dimensional embedding of a text string using character
+ * n-gram hashing (the "hashing trick").
+ *
+ * Each n-gram is hashed to a bucket in [0, VECTOR_DIMENSIONS). The bucket's
+ * float32 value is incremented by the n-gram's term frequency. After all
+ * n-grams are counted, the vector is L2-normalized so cosine similarity
+ * reduces to a dot product.
+ *
+ * This is NOT a semantic embedding — it captures **lexical similarity**
+ * (shared substrings). A real embedding model would be dropped in here
+ * without changing the storage or fusion interface.
+ */
+export declare function embedText(text: string): Float32Array;
+/** Cosine similarity between two L2-normalized vectors (reduces to dot product). */
+export declare function cosineSimilarity(a: Float32Array, b: Float32Array): number;
+/** Serialize a Float32Array to a Buffer for SQLite BLOB storage. */
+export declare function encodeVector(vec: Float32Array): Buffer;
+/** Deserialize a BLOB from SQLite back to a Float32Array. */
+export declare function decodeVector(buf: Buffer | Uint8Array): Float32Array;
+/**
+ * Rank map: symbolId → rank (0-based). Lower rank = more relevant.
+ * Built from a search result list (already sorted by relevance).
+ */
+export type RankMap = Map<number, number>;
+/** Build a RankMap from a sorted result list. */
+export declare function buildRankMap(sortedIds: number[]): RankMap;
+/**
+ * Reciprocal Rank Fusion — merge two ranked lists into a single fused ranking.
+ *
+ * Each symbol's RRF score is the sum of 1/(k + rank) from each source.
+ * Symbols only in one list still contribute 1/(k + rank) from that source.
+ * Symbols in neither list are absent from the output.
+ *
+ * @param bm25Ranks - rank map from BM25/FTS5 trigram search
+ * @param vectorRanks - rank map from vector similarity search
+ * @param k - the RRF constant (default 60, per Cormack et al.)
+ * @returns sorted [symbolId, rrfScore] pairs, descending by score
+ */
+export declare function reciprocalRankFusion(bm25Ranks: RankMap, vectorRanks: RankMap, k?: number): Array<[number, number]>;
+//# sourceMappingURL=vector-search.d.ts.map

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

@@ -38,6 +38,8 @@ export interface CallRefsOpArgs extends StatsOpArgs {
     symbol: string;
     file?: string | undefined;
     limit?: number | undefined;
+    /** When true, follow the call graph transitively (callers-of-callers / callees-of-callees) via recursive CTE. */
+    transitive?: boolean | undefined;
 }
 export interface SearchOpResult {
     results: SearchResult[];