pi-lens 4.3.0 → 4.4.1

package/dist/clients/source-walker.js

@@ -1,211 +0,0 @@
-/**
- * Shared directory-walk primitives (refs #191, "unify the three divergent
- * source walkers").
- *
- * `source-filter.ts` (`collectSourceFiles`/`collectSourceFilesAsync`),
- * `language-profile.ts` (`collectSourceFilesForWarmup`), and
- * `startup-scan.ts` (`countSourceFilesWithinLimit`/`countSourceFilesWithinLimitAsync`)
- * each re-implement a `readdirSync` + ignore-matcher + exclude-dir walk. The
- * SonarCloud duplication flagged on PR #188's async variants is a symptom of
- * this repeated boilerplate.
- *
- * This module intentionally does NOT own the full traversal loop for any
- * caller. Each walker's loop shape (sync-recursive vs. stack-based, yield
- * cadence, file-classification rules — extensions vs. regex vs. build-artifact
- * detection, hard caps vs. count-and-early-exit) is caller-specific and
- * preserved exactly where it already lived; unifying those would silently
- * change observable behavior (e.g. which files survive a `maxFiles` cap on an
- * over-large tree), which issue #191 explicitly calls out as NOT to do
- * silently.
- *
- * What genuinely was duplicated five times across those files is:
- *   1. The "should I recurse into this directory" decision — ignore-matcher +
- *      exclude-dir-name, plus two checks only `source-filter.ts` needs
- *      (generated-artifact directories, symlink-following).
- *   2. The `readdirSync(..., { withFileTypes: true })` + try/catch-swallow
- *      boilerplate (a missing/unreadable directory is silently skipped).
- * Both are centralized here so there is exactly one place that encodes "what
- * counts as an excluded directory."
- */
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { isExcludedDirName } from "./file-utils.js";
-import { isGeneratedArtifactDirectoryName } from "./generated-artifacts.js";
-import { createDeadline, yieldIfOverBudget } from "./cooperative-budget.js";
-/**
- * Read a directory's entries, returning `[]` for a permission-denied or
- * missing directory instead of throwing. Shared by every walker below — a
- * directory can legitimately disappear or become unreadable mid-walk (race
- * with another process, a broken symlink target, etc.) and every existing
- * caller already treated that as "yields no entries," not a hard failure.
- */
-export function readDirEntriesSafe(dirPath) {
-    try {
-        return fs.readdirSync(dirPath, { withFileTypes: true });
-    }
-    catch {
-        return [];
-    }
-}
-/**
- * Async twin of {@link readDirEntriesSafe} (refs #1137) — the identical
- * "unreadable directory yields no entries" contract, but the read itself
- * happens off the event loop via `fs.promises.readdir`.
- *
- * Why this exists: chunked yielding is NOT sufficient to keep the loop free.
- * `walkTreeStackAsync` already `setImmediate`-yielded every N entries, yet each
- * per-directory read was still `readdirSync` — so on a cloud-backed tree
- * (OneDrive, network drive) one stalled directory read blocked the Node loop,
- * and pi's TUI, for the *entire* stall regardless of yield cadence. That is the
- * exact shape #1170 already fixed in `pipeline.ts`'s autofix snapshot walk
- * ("the walk was already async + chunk-yielding, but each synchronous per-dir
- * read still blocked on a cloud stall"); #1170 deferred the SHARED engine, and
- * this is that same fix applied here — so every async walker gets it at once.
- */
-export async function readDirEntriesSafeAsync(dirPath) {
-    try {
-        return await fs.promises.readdir(dirPath, { withFileTypes: true });
-    }
-    catch {
-        return [];
-    }
-}
-/**
- * The one shared "should this directory be walked into" decision. Every
- * caller's own loop still owns *when* to call this (inline recursion vs. a
- * stack) and what to do with the answer.
- *
- * `onGeneratedDirSkip` (#1107 phase 2) fires exactly once when — and only
- * when — the `isGeneratedArtifactDirectoryName` branch is the reason this
- * directory is pruned, so a caller can count PRUNED DIRECTORIES (one event
- * per directory, regardless of how many files it contains) without
- * enumerating the directory's contents — doing that would defeat the whole
- * point of pruning it. Optional and unused by every caller except
- * `source-filter.ts`'s `classifyEntry`: the other two `shouldRecurseIntoDir`
- * callers (`language-profile.ts`, `startup-scan.ts`) always pass
- * `skipGeneratedArtifactDirs: false`, so this branch — and therefore the
- * callback — never fires for them.
- */
-export function shouldRecurseIntoDir(entry, fullPath, policy, onGeneratedDirSkip) {
-    if (isExcludedDirName(entry.name, policy.extraExcludeDirs ?? [])) {
-        return false;
-    }
-    if (policy.ignoreMatcher.isIgnored(fullPath, true))
-        return false;
-    if (policy.skipGeneratedArtifactDirs === true &&
-        isGeneratedArtifactDirectoryName(entry.name)) {
-        onGeneratedDirSkip?.();
-        return false;
-    }
-    if (policy.followSymlinks !== true && entry.isSymbolicLink())
-        return false;
-    return true;
-}
-/**
- * The one depth-first stack loop, written once as a generator so the sync and
- * async drivers below can't drift: it yields after every visited entry (the
- * async driver's chance to `setImmediate` between steps; the sync driver just
- * drains it), and its return value is true iff the visitor stopped the walk
- * via `"stop"` (vs. exhausting the tree or tripping `shouldStop`). Within each
- * directory, entries are visited left-to-right; entries the visitor marks
- * `"recurse"` are gathered and pushed in reverse after the entry loop, so the
- * pop order descends left-to-right.
- */
-function* walkTreeStackSteps(rootDir, visit, shouldStop) {
-    const stack = [rootDir];
-    while (stack.length > 0) {
-        if (shouldStop?.())
-            return false;
-        const dir = stack.pop();
-        if (dir === undefined)
-            continue;
-        // Directory-read REQUEST (#1137): the generator never reads the
-        // filesystem itself — it yields the directory path and the driver
-        // supplies the entries. That is what lets the sync driver stay
-        // `readdirSync` while the async driver reads via `fs.promises.readdir`
-        // WITHOUT forking the traversal into two implementations that can
-        // drift (the invariant this generator exists to protect).
-        const entries = (yield dir) ?? [];
-        const subDirs = [];
-        for (const entry of entries) {
-            const fullPath = path.join(dir, entry.name);
-            const disposition = visit(entry, fullPath);
-            if (disposition === "stop")
-                return true;
-            if (disposition === "recurse")
-                subDirs.push(fullPath);
-            // Per-entry yield point: `undefined` distinguishes it from a
-            // directory-read request above.
-            yield undefined;
-        }
-        for (let i = subDirs.length - 1; i >= 0; i--)
-            stack.push(subDirs[i]);
-    }
-    return false;
-}
-/**
- * Depth-first, stack-based synchronous driver — drains
- * {@link walkTreeStackSteps} with no pause between steps. Returns true iff the
- * visitor stopped the walk via `"stop"`.
- */
-export function walkTreeStackSync(rootDir, visit, opts = {}) {
-    const steps = walkTreeStackSteps(rootDir, visit, opts.shouldStop);
-    let step = steps.next();
-    while (!step.done) {
-        step = steps.next(step.value === undefined ? undefined : readDirEntriesSafe(step.value));
-    }
-    return step.value;
-}
-/**
- * Async, chunked-yield twin of {@link walkTreeStackSync} — the identical
- * {@link walkTreeStackSteps} traversal, plus a `setImmediate` yield every
- * its monotonic budget so a large tree never holds the event loop in
- * one synchronous burst. Returns true iff the visitor stopped the walk via
- * `"stop"`.
- *
- * #1137: every per-directory read goes through {@link readDirEntriesSafeAsync},
- * so the walk is non-blocking on BOTH axes — CPU (the `setImmediate` cadence)
- * and I/O (the directory read itself). The yield cadence alone never covered
- * the I/O axis: a stalled cloud-backed `readdirSync` held the loop for the full
- * stall no matter how often the walk yielded around it.
- */
-export async function walkTreeStackAsync(rootDir, visit, opts) {
-    await opts.beforeWalk?.();
-    const steps = walkTreeStackSteps(rootDir, visit, opts.shouldStop);
-    const deadline = createDeadline(opts.budgetMs ?? 8);
-    let step = steps.next();
-    while (!step.done) {
-        if (step.value !== undefined) {
-            // Directory-read request — satisfy it off the loop. No
-            step = steps.next(await readDirEntriesSafeAsync(step.value));
-            deadline.reset();
-            continue;
-        }
-        if (deadline.expired())
-            await yieldIfOverBudget(deadline);
-        step = steps.next();
-    }
-    return step.value;
-}
-/**
- * Depth-first synchronous driver that descends into a `"recurse"` directory
- * IMMEDIATELY, before visiting the remaining sibling entries — the recursion
- * shape (and therefore the result-array order) of `source-filter.ts`'s sync
- * collector, which its stack-based async twin deliberately does NOT share.
- * Returns true iff the visitor stopped the walk via `"stop"`; the stop
- * propagates up through every recursion frame so the walk halts at once.
- */
-export function walkTreeRecursiveSync(rootDir, visit) {
-    function scan(currentDir) {
-        for (const entry of readDirEntriesSafe(currentDir)) {
-            const fullPath = path.join(currentDir, entry.name);
-            const disposition = visit(entry, fullPath);
-            if (disposition === "stop")
-                return true;
-            if (disposition === "recurse" && scan(fullPath))
-                return true;
-        }
-        return false;
-    }
-    return scan(rootDir);
-}

package/dist/clients/spawn-output-cap.js

@@ -1,120 +0,0 @@
-/**
- * The one reading of `SpawnResult.outputTruncated` (#2100), the one output-cap
- * number (#3375), and the bounded accumulator the `data` handlers that never
- * reach `safeSpawnAsync` use instead of `+=` (#3383).
- *
- * Its own module for the same reason `ledger-bounds.ts` is: `spawn-outcome.ts`
- * is on the shared runner path that dozens of test files reach with a bare
- * `vi.mock("safe-spawn.js")`, and importing a VALUE from safe-spawn there makes
- * every one of those mocks have to re-export it. This module has no imports, so
- * nobody has to mock it.
- */
-/**
- * The cap `safeSpawnAsync` applies when a caller passes no `maxOutputBytes`
- * (#3375).
- *
- * Before this existed, an omitted cap meant NO cap: `appendOutput` fell
- * through to `current + text` and grew one JS string until V8 refused the next
- * concatenation with `RangeError: Invalid string length`. That throw is raised
- * inside a stdout/stderr `data` handler, where the awaiting caller's
- * `try`/`catch` cannot reach it, so it left the Pi host as an uncaught
- * exception (field report: Pi 0.86.1, 2026-09-22).
- *
- * 32 MiB is chosen against the tree's own deliberate ceilings, not invented:
- * the most generous explicit cap any caller asks for is 16 MiB
- * (`MAX_GIT_STATUS_OUTPUT_BYTES` in `clients/shared-checkout-guard.ts` and
- * `clients/opaque-mutation-scan.ts`, `MAX_LS_FILES_OUTPUT_BYTES` in
- * `clients/git-tracked-ignore.ts` — a monorepo's whole tracked-file list), and
- * the rest sit at 8 MiB or 64 KiB. Doubling that ceiling means no consumer
- * whose legitimate volume is within the most generous allowance a maintainer
- * has ever justified can be truncated by the DEFAULT, while the retained
- * string stays 16x below V8's max string length (2^29-24 bytes of ASCII), so
- * the concatenation that crashed the host is now unreachable rather than
- * merely less likely. A caller that genuinely needs more passes its own
- * `maxOutputBytes`; it always wins.
- */
-export const DEFAULT_MAX_OUTPUT_BYTES = 32 * 1024 * 1024;
-/**
- * The bound for a stream `data` handler that accumulates a string OUTSIDE
- * `safeSpawnAsync` (#3383).
- *
- * #3375 capped the shared spawn seam, which covered 98 of 110 call sites; the
- * class sweep for it found five accumulators that never reach that seam — a
- * forked analyze worker (`clients/mcp/review.ts`), the unref'd one-shot
- * collector (`clients/child-unref.ts`, which cannot import the seam at all: it
- * is what `safe-spawn.ts` itself depends on) and two installer interpreter
- * probes. Each grew one JS string per chunk with no ceiling, so each could
- * reach the identical ending: V8 refusing the next concatenation with
- * `RangeError: Invalid string length` INSIDE a `data` handler, which is an
- * uncaught exception that terminated the Pi host on 2026-09-22.
- *
- * Retention is HEAD-ONLY and whole-chunk: the first chunk that would cross the
- * bound is dropped entire, not byte-prefixed. `safeSpawnAsync`'s own
- * `appendOutput` keeps a head, a marker and a tail because its callers parse
- * tool output where the tail carries the summary; every caller here wants a
- * prefix (a JSON document, a `ps` table, one path line) and a whole-chunk drop
- * cannot split a multi-byte character.
- *
- * `maxBytes` defaults to {@link DEFAULT_MAX_OUTPUT_BYTES} so every bounded
- * accumulator in the tree answers to ONE reviewed number. NO production caller
- * passes it; it is a parameter so the retention arithmetic can be pinned at a
- * readable size (`createBoundedOutputSink(10)`) instead of only at 32 MiB.
- * There is deliberately no sanitizing of it either: nothing passes a value that
- * would need it, so a `Number.isFinite` arm would be mutation-inert.
- */
-export function createBoundedOutputSink(maxBytes = DEFAULT_MAX_OUTPUT_BYTES) {
-    let text = "";
-    let retained = 0;
-    let truncated = false;
-    let observed = 0;
-    return {
-        append(chunk) {
-            const part = typeof chunk === "string" ? chunk : chunk.toString();
-            const bytes = Buffer.byteLength(part);
-            observed += bytes;
-            if (retained + bytes <= maxBytes) {
-                retained += bytes;
-                text += part;
-                return;
-            }
-            truncated = true;
-        },
-        get text() {
-            return text;
-        },
-        get truncated() {
-            return truncated;
-        },
-        get observedBytes() {
-            return observed;
-        },
-    };
-}
-/**
- * True when `outputTruncated` is the OUTPUT CAP's own verdict about this run,
- * and not a detail of some other ending.
- *
- * A timeout or an abort can carry `outputTruncated` too. Those endings own
- * their own classification, so they are excluded here rather than reported as
- * truncation.
- *
- * Typed structurally so `SpawnResult` and runner-level result shapes that
- * re-spell `failure` can both use it.
- */
-export function truncatedByOutputCap(result) {
-    return (result.outputTruncated === true &&
-        result.failure !== "timeout" &&
-        result.failure !== "aborted");
-}
-/**
- * True when `stopForOutputLimit` started terminating the child.
- *
- * Windows reports that termination as status 1 without a signal or failure,
- * while POSIX commonly reports SIGTERM. This field avoids reconstructing our
- * action from either platform's exit shape.
- */
-export function killedForOutputCap(result) {
-    return (result.killedForOutputCap === true &&
-        result.failure !== "timeout" &&
-        result.failure !== "aborted");
-}

package/dist/clients/spawn-timeout-cooldown.js

@@ -1,110 +0,0 @@
-/**
- * Session-scoped cooldown for commands whose spawn TIMED OUT (#1995).
- *
- * Live evidence: one wedged `markdownlint-cli2.cmd` on Windows charged its
- * failure budget three times for a single edit — availability verification
- * (30s, SIGTERM), autofix `--fix` (30s), and the lint runner (15s) each paid
- * separately, because a positive probe/cache verdict said nothing about the
- * command's ability to COMPLETE. Total post-edit cost: 52-60 seconds.
- *
- * This seam is the shared negative evidence:
- * - `noteSpawnTimeout` records that a resolved command timed out, in which
- *   phase, and what wrapper kind it had; every record emits one bounded
- *   latency row so the session stays auditable.
- * - `isInSpawnTimeoutCooldown` is consulted by every invocation path for that
- *   command — verification, autofix, and lint — so ONE wedged executable
- *   consumes at most ONE bounded failure budget per edit (invariant 1) and a
- *   timeout/skipped result is never re-reported as clean (invariant 4).
- *
- * Durability contract: SESSION. A hot loop of edits must not retry (a wedged
- * `.cmd` shim does not heal between edits), but a new session may — the
- * executable or its environment may have changed. Reset is registered in the
- * session-state registry (`spawn-timeout-cooldown:latches`) and wired into
- * `handleSessionStart`.
- */
-import path from "node:path";
-import { logLatency } from "./latency-logger.js";
-import { normalizeLoggedPath } from "./path-utils.js";
-const COOLDOWN_STATE_KEY = Symbol.for("pi-lens:spawn-timeout-cooldown");
-const _global = globalThis;
-if (!_global[COOLDOWN_STATE_KEY]) {
-    _global[COOLDOWN_STATE_KEY] = { timedOutByCommand: new Map() };
-}
-const timedOutByCommand = _global[COOLDOWN_STATE_KEY].timedOutByCommand;
-/** Wrapper kind for the telemetry record: how the command will be launched. */
-function wrapperKindOf(command) {
-    const ext = path.extname(command);
-    return ext ? ext.slice(1) : "bare";
-}
-/**
- * Cooldown key: the command's basename minus extension, lowercased.
- *
- * Deliberately NOT the full resolved path: the three lanes resolve the same
- * physical binary through different helpers (PATH-resolved absolute,
- * `<cwd>/node_modules/.bin/...`, bare name), and cross-lane sharing is the
- * entire point (#1995 - otherwise each lane pays its own first budget).
- */
-function cooldownKey(command) {
-    return path
-        .basename(command)
-        .replace(/\.[^.]+$/, "")
-        .toLowerCase();
-}
-export function noteSpawnTimeout(input) {
-    const key = cooldownKey(input.command);
-    timedOutByCommand.set(key, {
-        tool: input.tool,
-        command: input.command,
-        phase: input.phase,
-        atMs: Date.now(),
-    });
-    // #2229 review round 1, F3, reverted in round 3 (R2-F2): normalizing
-    // `filePath` here is fine (it is `logLatency`'s emit-seam field, a
-    // display value with no reader). `metadata.command` is NOT a display
-    // value — `safe-spawn-timeout-teardown.test.ts` reads it back to match
-    // the cooldown row against the RAW command, and `cooldownKey` above
-    // deliberately keys on basename because the same binary arrives in
-    // multiple spellings across call sites. Normalizing it changed a
-    // correlation key's contents, which is a behavior change other code
-    // reads, not just a display fix — narrower than what F3 asked for.
-    // `filePath` and `metadata.command` can legitimately show two spellings
-    // of the same command in one record; if that turns out to matter, the
-    // fix belongs in a follow-up that stops `filePath` from carrying
-    // commands at all, not in widening this field's normalization.
-    logLatency({
-        type: "phase",
-        toolName: input.tool,
-        phase: "spawn_timeout_cooldown",
-        filePath: normalizeLoggedPath(input.command),
-        durationMs: input.durationMs ?? 0,
-        status: "cooldown_armed",
-        metadata: {
-            command: input.command,
-            wrapperKind: wrapperKindOf(input.command),
-            timeoutPhase: input.phase,
-            ...(input.durationMs !== undefined && {
-                timeoutBudgetMs: input.durationMs,
-            }),
-            ...(input.teardown && {
-                teardownMs: input.teardown.ms,
-                teardownOutcome: input.teardown.outcome,
-            }),
-        },
-    });
-}
-/**
- * True while `command` is cooling down after a spawn timeout. Every
- * invocation path for this command should skip WITHOUT spawning and report
- * an honest "not checked" outcome (skipped / 0-fixes), never clean.
- */
-export function isInSpawnTimeoutCooldown(command) {
-    return timedOutByCommand.has(cooldownKey(command));
-}
-/**
- * Session-start re-arm seam (registered in the session-state registry):
- * a new session may retry a command the previous session cooled down -
- * the executable or its environment may have changed.
- */
-export function resetSpawnTimeoutCooldowns() {
-    timedOutByCommand.clear();
-}

package/dist/clients/stale-marker.js

@@ -1,17 +0,0 @@
-/**
- * #1622 / #1419 precedent: what a demoted finding shows where its cached line
- * number used to be. The finding survives, the untrustworthy coordinate does
- * not. Shared base marker so every freshness gate (dependency-drift blockers,
- * cached-scanner staleness, #1641's past-EOF gate) renders the same "this
- * coordinate is no longer trustworthy" vocabulary — a caller with a more
- * specific reason appends its own suffix rather than inventing a parallel
- * marker string.
- *
- * #1631 review V2: lives in its own leaf module rather than `runtime-turn.ts`
- * (the turn orchestrator) so a low-level store like `widget-state.ts` can use
- * the marker without importing a high-level orchestration module — `madge
- * --circular` went from 0 to 45 cycles when `widget-state.ts` imported this
- * constant from `runtime-turn.ts`, and this repo ships that circular-import
- * check as a product feature.
- */
-export const STALE_LINE_MARKER = "[stale — re-run to confirm]";