@wrongstack/tools 0.309.1 → 0.310.0

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

@@ -10,6 +10,9 @@ export declare function resolveParallelBatch(): number;
  * Pool startup is amortized across the complete index run, not one outer
  * batch. Balanced batches are capped at 40 files, so comparing the per-batch
  * parse count with the 500-file threshold made the worker path unreachable.
+ *
+ * Threshold is env-configurable (audit T-04): `WRONGSTACK_INDEX_WORKER_THRESHOLD`
+ * overrides the default, `0` disables the worker path entirely.
  */
 export declare function shouldUseParserWorkerPool(candidateFileCount: number, parseBatchCount: number): boolean;
 interface IndexerOptions {

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

@@ -0,0 +1,53 @@
+/**
+ * Batch parsers for the external toolchain languages (Go, Python) — P3.8.
+ *
+ * The single-file parsers spawn one `go run` / `python` child process per
+ * file. For a 400-file Go project that is 400 process spawns, each paying
+ * toolchain startup; the spawn gate serializes them, so parse time scales
+ * linearly with spawn cost. This module runs the SAME extraction logic over
+ * a batch: one child process per chunk of files, sources in over stdin as a
+ * JSON array, one JSON envelope out per file.
+ *
+ * Fallback contract: a file the batch could not parse (per-file error in the
+ * envelope, or the chunk itself failing) is simply ABSENT from the returned
+ * map — the caller re-parses those files through the single-file parser,
+ * which owns the per-language fallback semantics (Go: regex extractor;
+ * Python: generic regex only when the runtime is missing). Parity with the
+ * per-file path is therefore by construction, not by reimplementation.
+ */
+import type { FileSymbols, SymbolLang } from './schema.js';
+/** Max files per child process. Bounded so one pathological file cannot
+ *  poison an unbounded chunk and stdin stays a comfortable pipe size. */
+export declare const MAX_BATCH_FILES = 100;
+/** Max cumulative source bytes per child process. */
+export declare const MAX_BATCH_BYTES: number;
+export interface BatchFile {
+    file: string;
+    content: string;
+    lang: SymbolLang;
+}
+/** Split a file list into chunks bounded by both file count and total bytes.
+ *  Generic so callers' extra per-file fields (e.g. source index) survive. */
+export declare function chunkBatchFiles<T extends BatchFile>(files: readonly T[]): T[][];
+/**
+ * Test-only: the cached batch-script paths. The security regression test
+ * observes WHERE the scripts were written without needing a toolchain —
+ * a missing binary still leaves the (already-created) path cached.
+ */
+export declare function __batchScriptPathsForTest(): {
+    go: string | null;
+    py: string | null;
+};
+/**
+ * Parse a chunk of Go files with ONE `go run` invocation.
+ * Returns per-file results; files absent from the map failed and the caller
+ * falls back to the single-file parser.
+ */
+export declare function runGoBatch(files: readonly BatchFile[], goBinary?: string): Promise<Map<string, FileSymbols>>;
+/**
+ * Parse a chunk of Python files with ONE interpreter invocation.
+ * Same contract as {@link runGoBatch}; `pythonBinary` is the cached resolver
+ * from py-parser.ts so both paths agree on which interpreter runs.
+ */
+export declare function runPyBatch(files: readonly BatchFile[], pythonBinary: string): Promise<Map<string, FileSymbols>>;
+//# sourceMappingURL=parser-batch.d.ts.map

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

@@ -5,4 +5,36 @@ import type { FileSymbols, SymbolLang } from './schema.js';
  * SQLite/IPC owner when TS/JS parsing is delegated to parser workers.
  */
 export declare function parseFileContent(file: string, content: string, lang: SymbolLang): Promise<FileSymbols>;
+/**
+ * Parse a mixed-language batch of files (P3.8).
+ *
+ * Go and Python files are grouped and handed to ONE child process per chunk
+ * (`runGoBatch` / `runPyBatch`) instead of one spawn per file; every other
+ * language goes through `parseFileContent` as before. Files the batch
+ * parsers could not produce (per-file error inside the envelope, or the
+ * whole chunk failing) fall back to the single-file parser, which owns the
+ * per-language fallback semantics — so output is identical to the per-file
+ * path in every case, only faster.
+ *
+ * Results are returned in input order (index-aligned), matching what callers
+ * expected from N parallel `parseFileContent` calls.
+ *
+ * Opt out with `WRONGSTACK_TOOLCHAIN_BATCH=0` to restore per-file spawning
+ * everywhere (bisecting a toolchain issue, exotic environments).
+ */
+/**
+ * One file's parse outcome. `result` is null only when the parser THREW —
+ * batch-invalid files still come back with the fallback parser's own
+ * zero-symbol semantics. `error` carries the throw's message so callers can
+ * record something actionable instead of a bare "no result".
+ */
+export interface ParseSlot {
+    result: FileSymbols | null;
+    error?: string | undefined;
+}
+export declare function parseFilesContent(files: ReadonlyArray<{
+    file: string;
+    content: string;
+    lang: SymbolLang;
+}>): Promise<ParseSlot[]>;
 //# sourceMappingURL=parser-dispatch.d.ts.map

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

@@ -26,4 +26,18 @@ export interface ParsedParserOutput {
 }
 /** Decode a parser child process's stdout. Never throws. */
 export declare function parseParserOutput(stdout: string, lang: SymbolLang): ParsedParserOutput;
+/**
+ * Decode a BATCH parser child process's stdout (P3.8): one envelope with a
+ * per-file results array. Per-file entries carry an optional `error` (the
+ * file failed inside the batch; the caller falls back to the single-file
+ * parser). Never throws — a malformed envelope yields [].
+ */
+export interface BatchFileOutput {
+    file: string;
+    /** Set when this file failed inside the batch (e.g. syntax error). */
+    error?: string | undefined;
+    symbols: RawParsedSymbol[];
+    refs: Ref[];
+}
+export declare function parseParserBatchOutput(stdout: string, lang: SymbolLang): BatchFileOutput[];
 //# sourceMappingURL=parser-output.d.ts.map

package/dist/codebase-index/parser-worker-pool.d.ts

@@ -3,19 +3,41 @@
  *
  * Spawns N worker threads (N = CPU cores - 1, clamped to [1, 4]) that share
  * the file-parsing load during startup/full reindex passes. Each worker runs
- * `parser-worker-script.ts`, reads files from disk, parses them via
- * `parseFileContent`, and returns `FileSymbols[]`.
+ * `parser-worker-script.ts`, parses file content supplied by the main thread
+ * via `parseFileContent`, and returns `FileSymbols[]`.
  *
- * The main thread distributes files in round-robin batches, collects results,
+ * The main thread distributes files in round-robin chunks, collects results,
  * and performs all SQLite writes via `commitBatch`. Workers never touch the
  * database — single-writer WAL semantics are preserved.
  *
+ * Failover (P3.7): every response carries the responding worker's
+ * `workerId` (threadId), so busy-tracking is identity-based and a batch
+ * knows exactly which chunk each worker owes. When a worker dies mid-batch,
+ * its orphaned chunk is re-parsed inline on this thread instead of waiting
+ * for a response that never arrive — a partial pool death previously hung
+ * the batch until the outer 60s/240s watchdog. Only when every worker dies
+ * does the batch reject, letting the indexer's existing inline fallback
+ * take over.
+ *
  * The pool is created lazily on first use and terminated on shutdown. Workers
  * are `unref()`'d so they don't keep the process alive.
  */
 import type { FileSymbols, SymbolLang } from './schema.js';
 /** Minimum number of files before the pool is worth spawning. */
 export declare const WORKER_POOL_THRESHOLD = 500;
+/**
+ * Effective pool threshold for this run (audit T-04): the documented
+ * {@link WORKER_POOL_THRESHOLD} default unless `WRONGSTACK_INDEX_WORKER_THRESHOLD`
+ * overrides it. Re-resolved on every call — like `resolveParallelBatch` — so
+ * profile changes (and tests) apply per index run without a process restart.
+ *
+ * - unset / unparsable / negative → the 500 default
+ * - `0` → disables the worker path (per the `WRONGSTACK_*=0` opt-out
+ *   convention, e.g. `WRONGSTACK_TOOLCHAIN_BATCH=0`): no candidate count can
+ *   satisfy `>= 0 && parseBatchCount > 1` gate semantics with an explicit
+ *   disable, so the gate checks the disable first.
+ */
+export declare function resolveWorkerPoolThreshold(): number;
 export declare class ParserWorkerPool {
     private readonly maxWorkers;
     private workers;
@@ -38,7 +60,7 @@ export declare class ParserWorkerPool {
     ensureReady(): Promise<boolean>;
     /**
      * Parse files in parallel across the worker pool. Returns a flat
-     * `FileSymbols[]` in completion order (caller sorts if needed).
+     * `FileSymbols[]` in completion order (caller matches by file path).
      *
      * Content is pre-read by the main thread (for the content-hash check)
      * and passed to workers to avoid a second disk read. Files are
@@ -52,6 +74,37 @@ export declare class ParserWorkerPool {
     /** Shut down all workers. Safe to call multiple times. */
     shutdown(): Promise<void>;
     private handleMessage;
+    /**
+     * Remove a worker from the pool and salvage any chunk it still owed.
+     *
+     * Idempotent by workerId — `error` and `exit` can both fire for one
+     * death, and a worker may die while no batch references it. When the
+     * dead worker owed files to an in-flight batch and other workers remain,
+     * those files are re-parsed inline on this thread (one fewer worker
+     * should cost latency, not correctness). When it was the last worker,
+     * every remaining batch rejects so the indexer's existing inline
+     * fallback takes over the whole batch.
+     */
+    private retireWorker;
+    /**
+     * Salvage path: re-parse an orphaned chunk on this thread. Files that
+     * fail here stay absent from the results — same contract as a per-file
+     * error inside a live worker (see handleMessage).
+     */
+    private reparseInline;
+    /**
+     * Terminal tail of a salvage — runs on every exit path. Kept free of
+     * control flow inside a `finally` (noUnsafeFinally): releases the
+     * pending-marker and resolves the batch if this was its last chunk.
+     */
+    private finishSalvage;
+    /**
+     * Retire by worker object rather than threadId. `threadId` is -1 before
+     * the worker emits `online`, so a death during script load would make a
+     * threadId-keyed lookup silently no-op and leak the entry (with its
+     * pending chunk) — reference identity is correct in every case.
+     */
+    private retireByReference;
     private handleError;
 }
 /**

package/dist/codebase-index/parser-worker-script.d.ts

@@ -13,8 +13,7 @@
  * The worker terminates cleanly when it receives a `{ type: 'shutdown' }`
  * message. If the parent port closes unexpectedly, the worker exits.
  */
-import type { FileSymbols } from './schema.js';
-import type { SymbolLang } from './schema.js';
+import type { FileSymbols, SymbolLang } from './schema.js';
 export interface ParserWorkerRequest {
     type: 'parse';
     id: number;
@@ -29,6 +28,10 @@ export interface ParserWorkerRequest {
 export interface ParserWorkerResponse {
     type: 'result';
     id: number;
+    /** Identity of the responding worker (`threadId`) — lets the pool free
+     *  exactly the worker that answered, and detect which chunk is orphaned
+     *  when a worker dies mid-batch. */
+    workerId: number;
     results: FileSymbols[];
     errors: ReadonlyArray<{
         file: string;