@wrongstack/tools 0.309.1 → 0.310.0

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

@@ -21,4 +21,9 @@ export declare function parseSymbols(opts: {
     lang: SymbolLang;
 }): Promise<FileSymbols>;
 export { detectLang } from './languages.js';
+/**
+ * The resolved Python binary (or null when no runtime is available).
+ * Shared with the P3.8 batch parser so both paths run the same interpreter.
+ */
+export declare function resolvePythonBinary(): Promise<string | null>;
 //# sourceMappingURL=py-parser.d.ts.map

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

@@ -75,6 +75,13 @@ export interface SearchResult {
 }
 /** Result of a full reindex. */
 export interface IndexResult {
+    /**
+     * Files actually parsed and committed with one or more symbols this run
+     * (P5.15: exactly `fileOutcomes.parsed`). Skipped (mtime/hash-unchanged),
+     * empty, and failed files are reported separately in `fileOutcomes` —
+     * historically they inflated this number, misreading incremental runs as
+     * doing full work.
+     */
     filesIndexed: number;
     /** Outcome detail for this run. Optional for compatibility with older project daemons. */
     fileOutcomes?: {
@@ -201,6 +208,12 @@ export interface GraphEdge {
 export interface CodeMapGraph {
     nodes: GraphNode[];
     edges: GraphEdge[];
+    /**
+     * True when the project server served a previous generation's cached
+     * answer while a refresh was publishing (stale-read serving). Never set
+     * by the worker/inline path, which refuses reads during a refresh.
+     */
+    stale?: boolean | undefined;
 }
-export declare const SCHEMA_VERSION = 4;
+export declare const SCHEMA_VERSION = 5;
 //# sourceMappingURL=schema.d.ts.map

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

@@ -1,8 +1,8 @@
 import type { DatabaseSync } from 'node:sqlite';
 /**
- * Load `node:sqlite`'s `DatabaseSync` lazily. Keeping this off writer.ts top
+ * Load the active runtime's synchronous SQLite implementation lazily. Keeping this off writer.ts top
  * level lets codebase-index tools register at CLI boot without eagerly loading
- * SQLite. Runtimes without `node:sqlite` fail only when the index is used.
+ * SQLite. Runtimes without `node:sqlite` or `bun:sqlite` fail only when the index is used.
  */
 export declare function loadDatabaseSync(): typeof DatabaseSync;
 export declare function runSqliteWithRetry<T>(fn: () => T): T;

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

@@ -4,8 +4,8 @@
  * 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.
+ * (calls, type references, extends/implements, include paths) landed with
+ * P3.9, where real AST fixtures proved the mapping.
  *
  * Why no tree-sitter queries (the `.scm` query language)?
  *   The universal visitor (`visitor.ts`) walks the tree by node-type rather
@@ -19,7 +19,7 @@
  * 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';
+import type { CallType, SymbolKind, SymbolLang } from '../schema.js';
 /**
  * Declarations worth indexing for a language.
  *
@@ -35,6 +35,10 @@ import type { SymbolKind, SymbolLang } from '../schema.js';
  *                    named children of a declaration node. Set for languages
  *                    where the parent itself is the only indexable unit
  *                    (rare; default false).
+ *   `refRules`     — P3.9: node types that emit cross-references (calls,
+ *                    imports, heritage). Absent for languages whose grammar
+ *                    would turn the rule into noise (Elixir's `call` covers
+ *                    operators; shell has no symbol calls).
  */
 export interface NodeQueries {
     declKinds: Record<string, SymbolKind>;
@@ -42,6 +46,29 @@ export interface NodeQueries {
     nameExtractor?: (node: import('web-tree-sitter').Node) => string | null;
     scopeNodes?: ReadonlySet<string>;
     skipNamedChildren?: boolean;
+    refRules?: Partial<Record<string, RefRule>>;
+}
+/** One ref a refRule wants emitted. `callType` defaults to the rule's. */
+export interface RefEmission {
+    toName: string;
+    callType?: CallType;
+    module?: string;
+}
+/**
+ * How to turn one tree-sitter node into refs.
+ *
+ *   `callType`      — the ref kind this rule emits.
+ *   `field`         — field carrying the callee/target (e.g. `'function'`).
+ *                     Default when no extractor: leaf-name of that field.
+ *   `nameExtractor` — full control (multi-ref nodes like heritage lists,
+ *                     imports whose module must be derived from the node
+ *                     text, Ruby `require` calls). Return `null`/`[]` to
+ *                     emit nothing for this node.
+ */
+export interface RefRule {
+    callType: CallType;
+    field?: string;
+    nameExtractor?: (node: import('web-tree-sitter').Node) => ReadonlyArray<RefEmission> | null;
 }
 /** Resolve the queries for a language, falling back to the default. */
 export declare function getQueries(lang: SymbolLang): NodeQueries;

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

@@ -27,11 +27,12 @@
  *      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 { Symbol as IndexSymbol, Ref, SymbolLang } from '../schema.js';
 import type { NodeQueries } from './queries.js';
 /** Result of walking one parsed file. */
 export interface VisitResult {
     symbols: IndexSymbol[];
+    refs: Ref[];
 }
 /**
  * Walk a parsed tree and emit symbols.

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

@@ -17,6 +17,18 @@
  */
 /** The constant k in the RRF formula — the standard value from the literature. */
 export declare const RRF_K = 60;
+/**
+ * P4.11: opt-in gate for the vector embedding layer. Default OFF.
+ *
+ * The 384-dim char-trigram embedding is lexical similarity — it duplicates
+ * what the FTS5 trigram tokenizer already provides — while costing ~1.5 KB
+ * of BLOB per symbol on every insert and an embedText() pass per symbol even
+ * when the table is unavailable. With the gate off, ranking is BM25/FTS-only
+ * (identical result set; the vector layer only re-ordered FTS candidates).
+ * Set WRONGSTACK_INDEX_VECTORS=1 to restore the hybrid RRF path; a force
+ * reindex repopulates the table for pre-existing symbols.
+ */
+export declare function vectorEmbeddingEnabled(): boolean;
 /** Fixed vector dimensionality. 384 matches the proposal's spec. */
 export declare const VECTOR_DIMENSIONS = 384;
 /**

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

@@ -0,0 +1,58 @@
+/**
+ * P4.14: idle-time WAL maintenance for the detached project-server daemon.
+ *
+ * `wal_autocheckpoint=1000` is PASSIVE and only attempts a checkpoint after a
+ * COMMIT. A daemon whose clients keep issuing searches (long-running WAL
+ * readers) can hold WAL snapshots indefinitely: the autocheckpointer sees
+ * busy=1 every time and the WAL grows without bound until a reader gap or
+ * shutdown. Nothing re-fires once writes stop — a COMMIT is what arms it.
+ *
+ * This scheduler gives the daemon its own maintenance heartbeat:
+ *  - every completed write run arms a sliding idle timer;
+ *  - when it fires (no further writes slid it), it checkpoints the WAL
+ *    (probe-first; never blocks on readers) and periodically runs
+ *    `PRAGMA optimize` so the query planner's statistics stay current.
+ *
+ * All timers are unref'd — they must never keep the daemon alive past its
+ * idle-exit, and firing is harmless at any point because checkpointWal is
+ * best-effort.
+ */
+export interface WalMaintenanceOptions {
+    /** Idle window after a write completion before maintenance fires. */
+    idleMs?: number | undefined;
+    /** Run `optimize()` once every N maintenance fires. Default: 8. */
+    optimizeEvery?: number | undefined;
+    /** Clock for tests. */
+    setTimeoutFn?: typeof setTimeout | undefined;
+    /** Clear for tests. */
+    clearTimeoutFn?: typeof clearTimeout | undefined;
+}
+export interface WalMaintenanceHooks {
+    /** Returns true when a checkpoint completed (WAL reset). */
+    checkpoint: () => boolean;
+    /** Recompute statistics. */
+    optimize: () => void;
+}
+export declare class WalMaintenance {
+    private readonly hooks;
+    private timer;
+    private fireCount;
+    private disposed;
+    private readonly idleMs;
+    private readonly optimizeEvery;
+    private readonly setTimeoutFn;
+    private readonly clearTimeoutFn;
+    constructor(hooks: WalMaintenanceHooks, options?: WalMaintenanceOptions);
+    /**
+     * Arm (or re-arm) the idle timer. Call after every completed write run —
+     * bursty incremental writes keep sliding the window so maintenance runs
+     * once after the burst settles, not per write.
+     */
+    notifyWriteCompleted(): void;
+    private fire;
+    /** True when an idle fire is pending (test visibility). */
+    get armed(): boolean;
+    /** Stop all maintenance. Idempotent; safe to call on every shutdown path. */
+    dispose(): void;
+}
+//# sourceMappingURL=wal-maintenance.d.ts.map

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

@@ -0,0 +1,44 @@
+/**
+ * Leaf contract types shared by `index-service.ts` and `worker-protocol.ts`.
+ *
+ * Lives separately from `index-service.ts` so the worker protocol can import
+ * these types type-only without depending on the implementation side, and
+ * so the runtime side can re-export them for downstream consumers that already
+ * reference them via the old path. Breaks the long-standing type-level SCC
+ * ARCH-CYCLE-TYPE-28 where `index-service.ts` and `worker-protocol.ts` were
+ * mutually importing contract types.
+ *
+ * This module MUST contain no runtime imports.
+ */
+import type { CallSite } from '../schema.js';
+/** Result of an incoming calls query. */
+export interface IncomingCallsResult {
+    calls: CallSite[];
+    symbolFound: boolean;
+    /** True when `file` was scoped but the name is ambiguous (other files define it too). */
+    ambiguous: boolean;
+    /** Total matching call sites before the limit was applied. */
+    totalMatches: number;
+    /**
+     * True when the project server served a previous generation's cached
+     * answer while a refresh was publishing (stale-read serving). Never set by
+     * the worker/inline path, which refuses reads during a refresh instead.
+     */
+    stale?: boolean | undefined;
+}
+/** Result of an outgoing calls query. */
+export interface OutgoingCallsResult {
+    calls: CallSite[];
+    symbolFound: boolean;
+    /** Number of refs whose target could not be resolved (to_id IS NULL). */
+    unresolvedCount: number;
+    /** Total matching call sites before the limit was applied. */
+    totalMatches: number;
+    /**
+     * True when the project server served a previous generation's cached
+     * answer while a refresh was publishing (stale-read serving). Never set by
+     * the worker/inline path, which refuses reads during a refresh instead.
+     */
+    stale?: boolean | undefined;
+}
+//# sourceMappingURL=contracts.d.ts.map

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

@@ -4,8 +4,8 @@
  * Plain structured-cloneable shapes only — no class instances, no functions.
  * Errors cross the boundary as strings and are re-wrapped by the host.
  */
+import type { IncomingCallsResult, OutgoingCallsResult } from './worker-protocol/contracts.js';
 import type { CodeMapGraph, IndexResult, IndexStats, SearchResult } from './schema.js';
-import type { IncomingCallsResult, OutgoingCallsResult } from './index-service.js';
 export interface IndexOpArgs {
     projectRoot: string;
     indexDir?: string | undefined;
@@ -44,6 +44,22 @@ export interface CallRefsOpArgs extends StatsOpArgs {
 export interface SearchOpResult {
     results: SearchResult[];
     total: number;
+    /**
+     * P2.5: present only on zero-hit responses. Minimal summary (files indexed,
+     * last_indexed) so the search tool can distinguish "index exists but nothing
+     * matched" from "no persisted index at all" without a separate stats round
+     * trip over IPC.
+     */
+    indexSummary?: {
+        totalFiles: number;
+        lastIndexed: number | null;
+    } | undefined;
+    /**
+     * True when the project server served a previous generation's cached
+     * answer while a refresh was publishing (stale-read serving). Never set by
+     * the worker/inline path, which refuses reads during a refresh instead.
+     */
+    stale?: boolean | undefined;
 }
 /** Map of op name → { args, result } so host and worker stay in lockstep. */
 export interface OpShapes {