@herbertgao/pi-extensions 2026.8.6 → 2026.8.7

package/node_modules/pi-lens/dist/clients/dispatch/runners/utils/spawn-outcome.js

@@ -1,22 +1,97 @@
+import { LEDGER_FIELD_MAX } from "../../../ledger-bounds.js";
+/**
+ * The first non-empty line of a tool's output, bounded.
+ *
+ * Replaces six hand-rolled copies that spelled the same idea two ways —
+ * `text.trim().split("\n")[0]` and `(text ?? "").trim().split("\n")[0] ||
+ * fallback` — with differing (or absent) length caps. Two behaviours the
+ * copies got wrong and this does not: a leading blank line no longer yields an
+ * empty "first line", and `\r\n` output no longer keeps its carriage return.
+ *
+ * Returns `""` when the text is empty or all-whitespace, so callers keep using
+ * `firstOutputLine(x) || fallback`.
+ */
+export function firstOutputLine(text, max = LEDGER_FIELD_MAX) {
+    for (const line of String(text ?? "").split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        return trimmed.length > max ? `${trimmed.slice(0, max)}…` : trimmed;
+    }
+    return "";
+}
+/**
+ * Decide whether a tool ran, and if not, why (#1816).
+ *
+ * The defect this closes (the #1736 class): a runner that reads only its
+ * parsed diagnostics reports a CLEAN file whenever the parse yields nothing —
+ * including when the tool exited non-zero on an unknown flag, was killed by a
+ * signal, or never spawned at all. An empty result must distinguish clean from
+ * errored.
+ *
+ * Classification order, most specific first:
+ *   1. `result.error` or a signal — the process never completed. `did-not-run`.
+ *   2. `status === null` with no error — no exit status ever arrived, so no
+ *      analysis can be claimed. `did-not-run`.
+ *   3. `reportMissing` — an artifact tool wrote no report. Nonzero exit means
+ *      `report-missing`; exit 0 means a genuinely clean run that had nothing
+ *      to write.
+ *   4. A nonzero status outside the caller's declared `ran` table.
+ *      `rejected-invocation`.
+ *   5. A nonzero status with nothing to parse. `did-not-run` — a tool that
+ *      analysed the file says SOMETHING, so silence plus failure is evidence
+ *      it never got that far.
+ * Everything else ran.
+ *
+ * Note what is deliberately NOT a non-ran path: a nonzero status WITH output
+ * and no contradicting table. Most linters exit non-zero precisely because
+ * they found something, and their findings are on stdout.
+ */
+export function classifyRunOutcome(input) {
+    const { result, exitCodes, reportMissing } = input;
+    const status = result.status ?? null;
+    const signal = result.signal ?? null;
+    const output = input.output ?? result.stdout;
+    const base = {
+        status,
+        signal,
+        firstOutputLine: firstOutputLine(result.stderr) ||
+            firstOutputLine(result.stdout) ||
+            firstOutputLine(result.error?.message),
+    };
+    if (result.error || signal)
+        return { kind: "did-not-run", ...base };
+    if (status === null)
+        return { kind: "did-not-run", ...base };
+    if (reportMissing) {
+        return status === 0
+            ? { kind: "ran", ...base }
+            : { kind: "report-missing", ...base };
+    }
+    if (status !== 0 && exitCodes && !exitCodes.ran.includes(status)) {
+        return { kind: "rejected-invocation", ...base };
+    }
+    if (status !== 0 && !output?.trim()) {
+        return { kind: "did-not-run", ...base };
+    }
+    return { kind: "ran", ...base };
+}
 /**
  * True when a tool both failed and produced nothing to parse — it never got as
  * far as linting the file. Callers map this to `skipped`, never `succeeded`.
  *
- * Guarding on `result.error` alone covers only half of it: safe-spawn sets
- * `error` for spawn/timeout/signal failures and resolves a NORMAL exit with no
- * `error` at any status (see `SpawnResult.failure` — "nonzero exit statuses are
- * not spawn failures"). An unknown subcommand, a rejected flag, or a config
- * that fails to load exits non-zero with the message on stderr and an empty
- * stdout, so an `error`-only guard falls through, parses "" into zero
- * diagnostics, and reports a clean file that nothing ever checked.
- *
- * Tools that exit non-zero *because* they found something are unaffected: their
- * findings are on stdout, so the output half of the test is false.
+ * Kept as its own export because callers outside the dispatch runners use it
+ * (`dead-code-client.ts`, `knip-client.ts`). It now DELEGATES to
+ * `classifyRunOutcome` rather than restating the rule, but keeps its exact
+ * historical semantics: the `!output.trim()` conjunct stays here so a spawn
+ * error that still produced partial output keeps reaching the parser, which is
+ * what today's callers depend on. `classifyRunOutcome` is the stricter,
+ * outcome-typed reading; migrate callers to it deliberately, not by accident.
  *
  * `output` defaults to stdout. Runners that parse stderr too pass the exact
  * string they are about to hand the parser, so "nothing to parse" means both
  * streams rather than just one.
  */
 export function spawnFailedWithNoOutput(result, output = result.stdout) {
-    return (Boolean(result.error) || result.status !== 0) && !output?.trim();
+    return (classifyRunOutcome({ result, output }).kind !== "ran" && !output?.trim());
 }

package/node_modules/pi-lens/dist/clients/dispatch/runners/utils/tool-failure.js

@@ -0,0 +1,72 @@
+/**
+ * One wording for a tool that produced no usable result, and the runner gate
+ * that emits it to the degradation ledger (#1816).
+ */
+import { incrementDegradationCount } from "../../../degradation-ledger.js";
+import { truncateForLedger } from "../../../ledger-bounds.js";
+import { classifyRunOutcome, firstOutputLine, } from "./spawn-outcome.js";
+/**
+ * One wording for "this tool did not produce a usable result" (#1816).
+ *
+ * Before this, five reason builders spelled the same sentence five ways and
+ * twelve sites truncated with their own literal, and NONE of them named the
+ * signal — so a SIGKILLed tool read exactly like a clean exit 0. The wording
+ * here is fixed, the truncation is the ledger's own `LEDGER_FIELD_MAX` policy
+ * applied once at the end, and the signal is always named when present.
+ *
+ * Shape: `tool (k=v, k=v) <what happened> with <what was missing>: <detail>`
+ */
+export function formatToolFailure(input) {
+    const entries = Object.entries(input.fields ?? {}).filter(([, value]) => value !== undefined && value !== "");
+    const identity = entries.length
+        ? `${input.tool} (${entries.map(([key, value]) => `${key}=${value}`).join(", ")})`
+        : input.tool;
+    // A signal is the strongest available explanation, so it displaces the exit
+    // status rather than sitting beside a `null` one.
+    const what = input.signal
+        ? `was killed by ${input.signal}`
+        : input.status === null
+            ? "did not run (spawn failure)"
+            : `exited ${input.status}`;
+    const missing = input.reportMissing ? "no report file" : "no output";
+    const detail = firstOutputLine(input.stderr) || firstOutputLine(input.stdout) || "no stderr";
+    return truncateForLedger(`${identity} ${what} with ${missing}: ${detail}`);
+}
+/**
+ * `formatToolFailure` fed straight from a `classifyRunOutcome` verdict — the
+ * path every migrated runner takes, so the outcome and the wording can never
+ * disagree about the status or the signal.
+ */
+export function formatRunOutcomeFailure(tool, outcome, fields) {
+    return formatToolFailure({
+        tool,
+        status: outcome.status,
+        signal: outcome.signal,
+        stderr: outcome.firstOutputLine,
+        reportMissing: outcome.kind === "report-missing",
+        fields: { outcome: outcome.kind, ...fields },
+    });
+}
+/**
+ * The migrated runners' one call: classify the spawn, and when the tool did
+ * NOT run, record a bounded `runner-empty-result` row and hand back the
+ * `skipped` verdict. Returns `null` when the tool ran, meaning "carry on and
+ * parse".
+ *
+ * `incrementDegradationCount` keeps the record bounded — one latest-reason
+ * entry per (kind, subject) with an exact event tally — so a permanently
+ * broken tool costs one ledger row, not one per dispatched file. `subject` is
+ * the tool id, which is the discriminating identity a reader needs: WHICH tool
+ * is silently contributing nothing.
+ */
+export function skipUnlessToolRan(tool, input, fields) {
+    const outcome = classifyRunOutcome(input);
+    if (outcome.kind === "ran")
+        return null;
+    incrementDegradationCount({
+        kind: "runner-empty-result",
+        subject: tool,
+        reason: formatRunOutcomeFailure(tool, outcome, fields),
+    });
+    return { status: "skipped", diagnostics: [], semantic: "none" };
+}

package/node_modules/pi-lens/dist/clients/dispatch/runners/utils/toolchain-availability.js

@@ -26,6 +26,8 @@ export function createToolchainAvailability(config) {
     let sweepSawTransient = false;
     let sweepTransientCause = "probe-timeout";
     let sweepHostStallMs = 0;
+    /** What the last classified candidate returned, for the decision record. */
+    let sweepEvidence;
     let ensureInFlight = null;
     async function findPath() {
         if (toolPath)
@@ -35,6 +37,7 @@ export function createToolchainAvailability(config) {
         sweepSawTransient = sweep.sawTransient;
         sweepTransientCause = sweep.transientCause;
         sweepHostStallMs = sweep.hostStallMs;
+        sweepEvidence = sweep.evidence;
         if (sweep.foundPath)
             toolPath = sweep.foundPath;
         return sweep.foundPath;
@@ -54,6 +57,8 @@ export function createToolchainAvailability(config) {
                 latched: true,
                 hostStallMs: sweepHostStallMs,
                 budgetMs: config.budgetMs,
+                classifiedBy: "probe",
+                ...(sweepEvidence !== undefined && { evidence: sweepEvidence }),
             });
             return true;
         }
@@ -72,6 +77,10 @@ export function createToolchainAvailability(config) {
             hostStallMs: sweepHostStallMs,
             ...(retryAfterMs > 0 && { retryAfterMs }),
             budgetMs: config.budgetMs,
+            // Derived from the sweep's own candidate probes, and carrying what the
+            // last of them returned (#1500).
+            classifiedBy: "probe",
+            ...(sweepEvidence !== undefined && { evidence: sweepEvidence }),
         });
         return false;
     }

package/node_modules/pi-lens/dist/clients/dispatch/runners/vale.js

@@ -3,6 +3,7 @@ import * as path from "node:path";
 import { safeSpawnAsync } from "../../safe-spawn.js";
 import { PRIORITY } from "../priorities.js";
 import { createAvailabilityChecker, resolveToolCommandWithInstallFallback, } from "./utils/runner-helpers.js";
+import { skipUnlessToolRan } from "./utils/tool-failure.js";
 const vale = createAvailabilityChecker("vale", ".exe");
 /**
  * Check for a .vale.ini config file in cwd or parent dirs.
@@ -89,6 +90,14 @@ const valeRunner = {
             return { status: "skipped", diagnostics: [], semantic: "none" };
         // Vale exits 0 even on findings, non-zero only on errors
         const result = await safeSpawnAsync(cmd, ["--output", "JSON", ctx.filePath], { cwd, timeout: 15000 });
+        // #1816: this runner read `result.status` zero times, so a Vale that
+        // rejected its config exited nonzero with an empty stdout, parsed to
+        // zero alerts, and reported clean prose. No exit-code table: Vale's
+        // nonzero codes vary with --minAlertLevel, so the conservative
+        // nothing-to-parse rule is the only safe discriminator here.
+        const skipped = skipUnlessToolRan("vale", { result });
+        if (skipped)
+            return skipped;
         const raw = result.stdout || "";
         const diagnostics = parseValeOutput(raw, ctx.filePath);
         if (diagnostics.length === 0) {

package/node_modules/pi-lens/dist/clients/dispatch/runners/yamllint.js

@@ -2,6 +2,7 @@ import { safeSpawnAsync } from "../../safe-spawn.js";
 import { getLinterPolicyForCwd, hasYamllintConfig } from "../../tool-policy.js";
 import { PRIORITY } from "../priorities.js";
 import { createAvailabilityChecker, resolveToolCommandWithInstallFallback, } from "./utils/runner-helpers.js";
+import { skipUnlessToolRan } from "./utils/tool-failure.js";
 const yamllint = createAvailabilityChecker("yamllint", ".exe");
 export { hasYamllintConfig };
 function parseYamllintParsable(raw, filePath) {
@@ -55,7 +56,23 @@ const yamllintRunner = {
         const result = await safeSpawnAsync(cmd, ["-f", "parsable", ctx.filePath], {
             timeout: 15000,
         });
-        const diagnostics = parseYamllintParsable(`${result.stdout ?? ""}${result.stderr ?? ""}`, ctx.filePath);
+        // #1816: this runner read `result.status` zero times, so a yamllint
+        // that rejected its config reported a clean YAML file.
+        //
+        // No exit-code table: yamllint returns 2 both for "warnings only" and
+        // for an argparse usage error, so declaring 2 a rejection would discard
+        // real warnings. The discriminator is the STREAM instead. `-f parsable`
+        // writes findings to stdout and nothing else; stderr carries usage text
+        // and tracebacks. So the gate judges "nothing to parse" on stdout alone,
+        // while the parser still reads both streams.
+        const raw = `${result.stdout ?? ""}${result.stderr ?? ""}`;
+        const skipped = skipUnlessToolRan("yamllint", {
+            result,
+            output: result.stdout,
+        });
+        if (skipped)
+            return skipped;
+        const diagnostics = parseYamllintParsable(raw, ctx.filePath);
         if (diagnostics.length === 0) {
             return { status: "succeeded", diagnostics: [], semantic: "none" };
         }

package/node_modules/pi-lens/dist/clients/dispatch/runners/zig-check.js

@@ -24,7 +24,9 @@ function parseZigOutput(raw, filePath) {
             line: Number.parseInt(lineStr, 10) || 1,
             column: Number.parseInt(colStr, 10) || 1,
             severity,
-            semantic: severity === "error" ? "blocking" : "warning",
+            // `zig build-exe <file>` does not load build.zig module/import context.
+            // Its findings are useful evidence, but cannot prove a project blocker.
+            semantic: "warning",
             tool: "zig",
             rule: `zig-${level}`,
             fixable: false,
@@ -82,7 +84,7 @@ const zigCheckRunner = {
         return {
             status: hasErrors ? "failed" : "succeeded",
             diagnostics,
-            semantic: hasErrors ? "blocking" : "warning",
+            semantic: "warning",
         };
     },
 };

package/node_modules/pi-lens/dist/clients/event-loop-monitor.js

@@ -143,15 +143,38 @@ export function resetEventLoopMonitor() {
     windowStartCpuMs = cpuTotalMs();
 }
 /**
- * Decide whether a freeze is worth persisting to `latency.log`. Pure so the
- * threshold logic is testable without the (vitest-flaky) native histogram.
- * Logs only a *new* worst block (`maxMs > lastLoggedMs + deltaMs`) above a
- * floor (`minMs`), so a turn that froze worse than ever before is recorded
- * once — not the same growing max every turn.
+ * Decide whether THIS block beats the session's running high-water. Pure so
+ * the threshold logic is testable without the (vitest-flaky) native
+ * histogram. Requires `maxMs > lastLoggedMs + deltaMs` above a floor
+ * (`minMs`) so noise near the current max doesn't keep re-triggering the
+ * high-water bookkeeping.
+ *
+ * NOTE (#1723): this is no longer the logging gate — see
+ * `shouldLogLoopBlock` for that. This function now answers a narrower
+ * question ("is this a new session worst?", used for the `worstSoFar`
+ * metadata flag and for deciding whether to advance the high-water), because
+ * gating the LOG on it hid every sub-maximum block after a session's first
+ * large one, which made loop_block-vs-pull-timeout correlation undecidable.
  */
 export function shouldLogWorstBlock(maxMs, lastLoggedMs, minMs = 60, deltaMs = 25) {
     return maxMs >= minMs && maxMs > lastLoggedMs + deltaMs;
 }
+/**
+ * Decide whether a block is worth persisting to `latency.log` AT ALL (#1723).
+ * Every block at or above the floor (`minMs`) qualifies — not only a new
+ * session worst — because a session's later blocks can be smaller than an
+ * early spike yet still be exactly the ones that starved an LSP pull
+ * (#1549/#1713) and are otherwise invisible to the correlation.
+ *
+ * Volume is bounded by CALL CADENCE, not by this gate: the `turn_end` caller
+ * invokes this at most once per turn (the histogram window is reset every
+ * turn), so the natural cap is one `loop_block` record per turn — a jittery
+ * session cannot flood the log because there is nowhere for a second sample
+ * to come from within the same turn.
+ */
+export function shouldLogLoopBlock(maxMs, minMs = 60) {
+    return maxMs >= minMs;
+}
 /** Test-only: stop and clear the monitor so cases don't leak into each other. */
 export function _stopEventLoopMonitorForTest() {
     histogram?.disable();

package/node_modules/pi-lens/dist/clients/extension-log.js

@@ -55,6 +55,11 @@ export function createSubsystemLogger(subsystem, defaultLevel = "debug") {
 }
 /** No-op with the `SubsystemLogger` shape, for the verbose-off branch. */
 export function noopSubsystemLogger() {
+    // SAFETY: `SubsystemLogger` is a callable with `error`/`warn`/`debug`
+    // properties. TypeScript cannot type a function literal that gains its
+    // properties on the following lines, so the cast runs ahead of the three
+    // assignments that complete the shape. Every member of the interface is
+    // assigned before `noop` escapes this function.
     const noop = (() => { });
     noop.error = () => { };
     noop.warn = () => { };
@@ -175,6 +180,13 @@ export function runInConsoleCaptureWindow(fn) {
     return storage.run(true, fn);
 }
 function inCaptureWindow(fn) {
+    // SAFETY: the wrapper forwards `this` and every argument to `fn` unchanged
+    // and returns its result unchanged, so it is call-compatible with `T` at
+    // runtime. TypeScript cannot prove that for a generic `T` it did not
+    // construct, because a variadic `(...args: unknown[]) => unknown` is not
+    // assignable to an arbitrary function type. The invariant is the
+    // pass-through itself: change the body to alter arguments or the return
+    // value and this cast stops being true.
     return function (...args) {
         return runInConsoleCaptureWindow(() => fn.apply(this, args));
     };
@@ -313,7 +325,7 @@ export function withConsoleCaptureWindows(api) {
             // A host that returns `this` for chaining would hand back the raw API,
             // so a chained `on(...).on(...)` would register an unwrapped handler.
             // Keep the proxy on the chain.
-            const keepProxy = (result) => result === target ? proxy : result;
+            const keepProxy = (result) => Object.is(result, target) ? proxy : result;
             // Pass-through members are cached too (S3a/S3b: `proxy.getFlag ===
             // proxy.getFlag`), but the cached wrapper re-reads `target[prop]` on
             // EVERY call rather than closing over `method` -- a plain
@@ -379,6 +391,11 @@ export function installConsoleGuard() {
     if (process.env.PI_LENS_CONSOLE_GUARD === "0")
         return false;
     consoleGuardInstalled = true;
+    // SAFETY: re-views `console` as a string-keyed record so the loop below can
+    // read and replace methods by name. `ConsoleMethod` is the union of keys
+    // that exist on `Console`, and each read is guarded by `typeof original ===
+    // "function"` before use, so a host whose console lacks a method is skipped
+    // rather than patched with undefined.
     const target = console;
     for (const method of CONSOLE_METHODS) {
         const original = target[method];
@@ -413,6 +430,10 @@ export function uninstallConsoleGuard() {
     if (!consoleGuardInstalled)
         return false;
     consoleGuardInstalled = false;
+    // SAFETY: same re-view as `installConsoleGuard`. Only keys this module
+    // recorded in `originalConsoleMethods` at install time are written back,
+    // and only when the current value is still the replacement this module
+    // installed, so a method someone else patched afterwards is left alone.
     const target = console;
     for (const [method, original] of originalConsoleMethods) {
         if (target[method] === installedConsoleMethods.get(method)) {

package/node_modules/pi-lens/dist/clients/file-kinds.js

@@ -25,6 +25,7 @@ export const KIND_EXTENSIONS = {
         ".sass",
         ".scss",
     ],
+    cue: [".cue"],
     // From llvm-project/clang/lib/Driver/Types.cpp clang::driver::types::lookupTypeForExtension:
     cxx: [
         // C
@@ -260,8 +261,10 @@ for (const [kind, exts] of Object.entries(KIND_EXTENSIONS)) {
         }
     }
 }
-// Special filenames that indicate a file kind
-const SPECIAL_FILENAMES = [
+// Special filenames that indicate a file kind. Exported so other seams that
+// classify by basename (e.g. lsp/language.ts's language-id resolution) derive
+// from this list instead of hand-keeping their own basename literals (#1594).
+export const SPECIAL_FILENAMES = [
     { pattern: /^CMakeLists\.txt$/i, kind: "cmake" },
     { pattern: /^Makefile$/i, kind: "shell" },
     { pattern: /^Dockerfile(\.\w+)?$/i, kind: "docker" },
@@ -336,6 +339,7 @@ export const CODE_KINDS = new Set([
     "clojure",
     "cmake",
     "csharp",
+    "cue",
     "cxx",
     "dart",
     "docker",
@@ -434,6 +438,7 @@ export function getFileKindLabel(kind) {
         gleam: "Gleam",
         ocaml: "OCaml",
         clojure: "Clojure",
+        cue: "CUE",
         terraform: "Terraform",
         terragrunt: "Terragrunt",
         nix: "Nix",
@@ -504,6 +509,7 @@ export function getLanguageId(kind) {
         gleam: "gleam",
         ocaml: "ocaml",
         clojure: "clojure",
+        cue: "cue",
         terraform: "terraform",
         terragrunt: "terragrunt",
         nix: "nix",