paperlint 3.1.3 → 4.0.0

package/fixtures/pdf-facts/README.md

@@ -1,6 +1,6 @@
 # PDF fixtures for the pdf.js reader
 
-Real PDFs that `src/pdf-facts.harness.mjs` and `skills/render-paper/extract-pdf-facts.harness.mjs`
+Real PDFs that `src/pdf-facts.harness.ts` and `skills/render-paper/extract-pdf-facts.harness.ts`
 read. They were measured with poppler and with pdf.js on 2026-09-24 (issue #61); the harnesses pin
 poppler's numbers, so a pass means agreement with the tool pdf.js replaced.
 
@@ -13,7 +13,7 @@ poppler's numbers, so a pass means agreement with the tool pdf.js replaced.
 | `encrypted.pdf`    | `t3-all.pdf` saved with an AES-256 user password (PyMuPDF)          | pdf.js refuses it with `PasswordException`; the reader reports `encrypted`                                                        |
 | `hidden-text.pdf`  | `hidden-text.tex`, pdflatex                                         | two-column body text beside near-white, rotated and render-mode-3 text; page 2 holds only hidden text, so banal calls it blank    |
 
-`test/e2e/banal.mjs` also reads these files, with the real banal: it pins what banal 1.2 printed for
+`test/e2e/banal.ts` also reads these files, with the real banal: it pins what banal 1.2 printed for
 each one on poppler's `pdftohtml` 24.02.0 (2026-09-25), so a pass there means paperlint's pdf.js-written
 XML measures the same as poppler's. `hidden-text.pdf` exists for that test: each kind of hidden text
 changes banal's answer if it is counted.

package/fixtures/real-markdown-paper/{baseline.mjs → baseline.ts}

@@ -1,18 +1,31 @@
 /**
  * ONE reader of `baseline.json`, shared by the two runs that compare against it: the harness
- * beside this file (the repository's own `bin/paperlint.mjs`) and `test/e2e/install.mjs` (the binary
+ * beside this file (the repository's own `bin/paperlint.mjs`) and `test/e2e/install.ts` (the binary
  * a consumer actually got). Two copies of "growth fails, a drop never does" would drift the first
  * time one of them is tightened, and the two runs would then disagree about the same article.
  */
 import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { z } from "zod";
+
+/** Findings per rule id. */
+export type Counts = Record<string, number>;
+
+const Baseline = z.object({ findings: z.record(z.string(), z.number()) });
+const LintOutput = z.array(
+  z.object({
+    messages: z.array(z.object({ ruleId: z.string().nullable() })).nullish(),
+  }),
+);
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 
 /** The recorded counts, `{ruleId: n}`. */
-export function recordedFindings() {
-  return JSON.parse(readFileSync(join(HERE, "baseline.json"), "utf8")).findings;
+export function recordedFindings(): Counts {
+  return Baseline.parse(
+    JSON.parse(readFileSync(join(HERE, "baseline.json"), "utf8")),
+  ).findings;
 }
 
 /**
@@ -20,11 +33,13 @@ export function recordedFindings() {
  * 🔴 Output that does not parse THROWS. An empty set read as "clean" is how this repository's
  * checks have gone hollow before.
  */
-export function countByRule(stdout) {
-  const out = {};
-  for (const file of JSON.parse(stdout))
-    for (const m of file.messages ?? [])
-      out[m.ruleId] = (out[m.ruleId] ?? 0) + 1;
+export function countByRule(stdout: string): Counts {
+  const out: Counts = {};
+  for (const file of LintOutput.parse(JSON.parse(stdout)))
+    for (const m of file.messages ?? []) {
+      const rule = String(m.ruleId);
+      out[rule] = (out[rule] ?? 0) + 1;
+    }
   return out;
 }
 
@@ -37,12 +52,18 @@ export function countByRule(stdout) {
  * A partial drop is neither: it is what a fix looks like (paperlint#44 is expected to take typography
  * to zero, and then the recording is updated in the same change).
  */
-export function compareToBaseline(found, recorded = recordedFindings()) {
+export function compareToBaseline(
+  found: Readonly<Counts>,
+  recorded: Readonly<Counts> = recordedFindings(),
+): {
+  grew: { rule: string; now: number; recorded: number }[];
+  vanished: string[];
+} {
   const grew = Object.entries(found)
     .filter(([rule, n]) => n > (recorded[rule] ?? 0))
     .map(([rule, n]) => ({ rule, now: n, recorded: recorded[rule] ?? 0 }));
   const vanished = Object.keys(recorded).filter(
-    (r) => recorded[r] > 0 && !(r in found),
+    (r) => (recorded[r] ?? 0) > 0 && !(r in found),
   );
   return { grew, vanished };
 }

package/hooks/{hooks.harness.mjs → hooks.harness.ts}

@@ -1,5 +1,5 @@
 /**
- * hooks.harness.mjs — the three shipped hooks, each asserted in BOTH halves.
+ * hooks.harness.ts — the three shipped hooks, each asserted in BOTH halves.
  *
  * 🔴 WHY "BOTH HALVES" IS THE ORGANISING RULE HERE AND NOT A STYLE. Two of these three are
  * ADVISORY: silence is their success state. So "it printed nothing" and "it is dead" look
@@ -20,9 +20,9 @@
  * `checkHookImports`, over the shipped files directly. That is STRICTER than compiling a twin
  * `.ts` source would be: a twin can drift from its build, and there is no twin here to drift.
  *
- * Run: `npx vigiles test hooks/hooks.harness.mjs`
+ * Run: `npx vigiles test hooks/hooks.harness.ts`
  */
-import { runHook } from "vigiles";
+import { runHook, type HookInput, type HookRunResult } from "vigiles";
 import { checkHookImports } from "vigiles/hook";
 import {
   mkdtempSync,
@@ -37,8 +37,9 @@ import {
 import { tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { PAPERS_DIR_FIELD } from "../lib/paper-config.mjs";
-import { createChecker } from "../lib/check.mjs";
+import { z } from "zod";
+import { PAPERS_DIR_FIELD } from "../lib/paper-config.ts";
+import { createChecker } from "../lib/check.ts";
 
 const HOOKS = dirname(fileURLToPath(import.meta.url));
 const ROOT = resolve(HOOKS, "..");
@@ -64,7 +65,13 @@ const check = createChecker();
  * installed rather than adjacent. The `node_modules/<pkg>` entry is a symlink to this very
  * checkout, which is what `npm install` of a local package does anyway.
  */
-const consumer = (block, { papers = "docs/papers", paper = "alpha" } = {}) => {
+const consumer = (
+  block: unknown,
+  {
+    papers = "docs/papers",
+    paper = "alpha",
+  }: { papers?: string | null; paper?: string } = {},
+) => {
   const dir = realpathSync(mkdtempSync(join(tmpdir(), "paperlint-hooks-")));
   const nm = join(dir, "node_modules");
   mkdirSync(nm, { recursive: true });
@@ -84,24 +91,28 @@ const consumer = (block, { papers = "docs/papers", paper = "alpha" } = {}) => {
 };
 
 /** `run-program <hook>` exactly as a consumer's settings block invokes it. */
-const program = (name) =>
+const program = (name: string) =>
   `node ${JSON.stringify(CLI)} hook-runtime run-program ${JSON.stringify(join(HOOKS, name + ".hook.mjs"))}`;
 
-const onBash = (command) => ({
+const onBash = (command: string): HookInput => ({
   hook_event_name: "PreToolUse",
   tool_name: "Bash",
   tool_input: { command },
 });
-const onEdit = (file_path) => ({
+const onEdit = (file_path: string): HookInput => ({
   hook_event_name: "PostToolUse",
   tool_name: "Edit",
   tool_input: { file_path },
   tool_response: {},
 });
-const STOP = { hook_event_name: "Stop", tool_name: "", tool_input: {} };
+const STOP: HookInput = {
+  hook_event_name: "Stop",
+  tool_name: "",
+  tool_input: {},
+};
 
 /** Run a hook AS a consumer: cwd and `CLAUDE_PROJECT_DIR` both point at the fixture repo. */
-const at = (dir, name, input) =>
+const at = (dir: string, name: string, input: HookInput): HookRunResult =>
   runHook(program(name), input, { cwd: dir, env: { CLAUDE_PROJECT_DIR: dir } });
 
 /**
@@ -116,23 +127,29 @@ const at = (dir, name, input) =>
  * live case: a session `cd`s into a subtree, and vigiles runs every provider «via execSync in
  * the hook's cwd».
  */
-const adrift = (dir, name, input) =>
+const adrift = (dir: string, name: string, input: HookInput): HookRunResult =>
   runHook(program(name), input, {
     cwd: realpathSync(mkdtempSync(join(tmpdir(), "drift-"))),
     env: { CLAUDE_PROJECT_DIR: dir },
   });
 
 /** An injected notice, as the model would receive it — not the returned reaction. */
-const injected = (r) => {
+const Injected = z.object({
+  hookSpecificOutput: z.object({ additionalContext: z.string().nullish() }),
+});
+const injected = (r: HookRunResult): string => {
   try {
-    return JSON.parse(r.stdout).hookSpecificOutput.additionalContext ?? "";
+    return (
+      Injected.parse(JSON.parse(r.stdout)).hookSpecificOutput
+        .additionalContext ?? ""
+    );
   } catch {
     return "";
   }
 };
 
-const tmps = [];
-const fixture = (...args) => {
+const tmps: string[] = [];
+const fixture = (...args: Parameters<typeof consumer>) => {
   const d = consumer(...args);
   tmps.push(d);
   return d;
@@ -191,10 +208,10 @@ try {
     const dir = fixture({ [PAPERS_DIR_FIELD]: "docs/papers" });
     const P = "docs/papers/alpha/paper.md";
     const T = "docs/papers/alpha/paper.tex";
-    const deny = (label, cmd) => {
+    const deny = (label: string, cmd: string) => {
       const r = at(dir, "paper-edit-guard", onBash(cmd));
       check(
-        `guard BLOCKS ${label} (rc=${r.exitCode})`,
+        `guard BLOCKS ${label} (rc=${String(r.exitCode)})`,
         r.exitCode === 2 && r.blocked,
       );
       check(
@@ -202,10 +219,10 @@ try {
         /Use Edit or Write/.test(r.stderr),
       );
     };
-    const allow = (label, cmd) => {
+    const allow = (label: string, cmd: string) => {
       const r = at(dir, "paper-edit-guard", onBash(cmd));
       check(
-        `guard ALLOWS ${label} (rc=${r.exitCode}, ${r.stderr.length}b err)`,
+        `guard ALLOWS ${label} (rc=${String(r.exitCode)}, ${String(r.stderr.length)}b err)`,
         r.exitCode === 0 && !r.blocked,
       );
     };
@@ -292,7 +309,7 @@ try {
     check("drift · guard still blocks a paper write", write.exitCode === 2);
     const idle = adrift(dir, "paper-edit-guard", onBash("echo hi"));
     check(
-      `drift · guard does NOT deny an unrelated command (rc=${idle.exitCode})`,
+      `drift · guard does NOT deny an unrelated command (rc=${String(idle.exitCode)})`,
       idle.exitCode === 0,
     );
     const guarded = adrift(
@@ -318,7 +335,7 @@ try {
       onEdit(`${dir}/writing/drafts/alpha/PIPELINE-STATUS.md`),
     );
     check(
-      `drift · the status-gates hook still runs (rc=${gates.exitCode})`,
+      `drift · the status-gates hook still runs (rc=${String(gates.exitCode)})`,
       gates.exitCode === 0,
     );
   }
@@ -381,7 +398,7 @@ try {
       const dir = fixture({ [PAPERS_DIR_FIELD]: null });
       const r = at(dir, "paper-edit-guard", harmless);
       check(
-        `carrier: "${PAPERS_DIR_FIELD}": null REFUSES (rc=${r.exitCode})`,
+        `carrier: "${PAPERS_DIR_FIELD}": null REFUSES (rc=${String(r.exitCode)})`,
         r.exitCode === 2,
       );
       check(
@@ -394,7 +411,7 @@ try {
       const dir = fixture({ [PAPERS_DIR_FIELD]: "" });
       const r = at(dir, "paper-edit-guard", harmless);
       check(
-        `carrier: "${PAPERS_DIR_FIELD}": "" REFUSES (rc=${r.exitCode})`,
+        `carrier: "${PAPERS_DIR_FIELD}": "" REFUSES (rc=${String(r.exitCode)})`,
         r.exitCode === 2,
       );
       check(
@@ -414,7 +431,7 @@ try {
       );
       const r = at(dir, "paper-edit-guard", harmless);
       check(
-        `carrier: an unparseable paperlint.json REFUSES (rc=${r.exitCode})`,
+        `carrier: an unparseable paperlint.json REFUSES (rc=${String(r.exitCode)})`,
         r.exitCode === 2,
       );
       check(
@@ -442,11 +459,11 @@ try {
   // ═══════════════════════════════════════════════════════════════════════════
   {
     const dir = fixture({ [PAPERS_DIR_FIELD]: "docs/papers" });
-    const lands = (label, p) => {
+    const lands = (label: string, p: string) => {
       const r = at(dir, "paper-skills-nudge", onEdit(p));
       const ctx = injected(r);
       check(
-        `nudge LANDS on ${label} (${r.stdout.length}b stdout)`,
+        `nudge LANDS on ${label} (${String(r.stdout.length)}b stdout)`,
         ctx.length > 0,
       );
       check(
@@ -455,10 +472,10 @@ try {
       );
       check(`nudge on ${label} exits 0`, r.exitCode === 0);
     };
-    const silent = (label, p) => {
+    const silent = (label: string, p: string) => {
       const r = at(dir, "paper-skills-nudge", onEdit(p));
       check(
-        `nudge SILENT on ${label} (${r.stdout.length}b stdout, ${r.stderr.length}b stderr)`,
+        `nudge SILENT on ${label} (${String(r.stdout.length)}b stdout, ${String(r.stderr.length)}b stderr)`,
         r.stdout.length === 0 && r.stderr.length === 0 && r.exitCode === 0,
       );
     };
@@ -505,15 +522,15 @@ try {
   // ═══════════════════════════════════════════════════════════════════════════
   {
     const dir = fixture({ [PAPERS_DIR_FIELD]: "docs/papers" });
-    const fires = (label, p) => {
+    const fires = (label: string, p: string) => {
       const r = at(dir, "paper-status-gates", onEdit(p));
       check(
-        `gates FIRES on ${label} (${r.stderr.length}b stderr)`,
+        `gates FIRES on ${label} (${String(r.stderr.length)}b stderr)`,
         /fixture verdict line/.test(r.stderr),
       );
       check(`gates on ${label} exits 0`, r.exitCode === 0);
     };
-    const silent = (label, p) => {
+    const silent = (label: string, p: string) => {
       const r = at(dir, "paper-status-gates", onEdit(p));
       check(
         `gates SILENT on ${label}`,
@@ -593,7 +610,7 @@ try {
   // ═══════════════════════════════════════════════════════════════════════════
   {
     const dir = fixture({ [PAPERS_DIR_FIELD]: "docs/papers" });
-    const sh = (args) =>
+    const sh = (args: string) =>
       runHook(
         `bash ${JSON.stringify(join(HOOKS, "paper-status-gates.sh"))} ${args}`,
         STOP,
@@ -643,7 +660,7 @@ try {
     );
   }
 
-  console.log(`hooks.harness: ${check.count} assertions passed`);
+  console.log(`hooks.harness: ${String(check.count)} assertions passed`);
 } finally {
   for (const d of tmps) rmSync(d, { recursive: true, force: true });
 }

package/hooks/paper-edit-guard.hook.mjs

@@ -38,7 +38,7 @@
  * install reverting it.
  *
  * The capability surface is therefore asserted HERE, on the artifact that actually executes:
- * `hooks.harness.mjs` runs `checkHookImports` over every shipped `.hook.mjs`. That is a stricter
+ * `hooks.harness.ts` runs `checkHookImports` over every shipped `.hook.mjs`. That is a stricter
  * check than compiling a twin `.ts` source would be, because a twin can drift from its build and
  * this cannot — there is only one file.
  *

package/hooks/{paper-edit-guard.test.mjs → paper-edit-guard.test.ts}

@@ -7,12 +7,8 @@
  */
 import assert from "node:assert/strict";
 import { test } from "vitest";
-import {
-  hookConsumer,
-  onBash,
-  runShippedHook,
-} from "../test/hook-consumer.mjs";
-import { useTempDir } from "../test/support.mjs";
+import { hookConsumer, onBash, runShippedHook } from "../test/hook-consumer.ts";
+import { useTempDir } from "../test/support.ts";
 
 const dir = hookConsumer(useTempDir("paper-edit-guard-"), {
   "papers/alpha/PIPELINE-STATUS.md": "# S\n",
@@ -22,7 +18,7 @@ const GT = String.fromCharCode(62);
 const P = "papers/alpha/paper.md";
 
 /** The guard's exit code for one Bash command: 2 denies, 0 lets it through. */
-const guard = (command) =>
+const guard = (command: string): number =>
   runShippedHook("paper-edit-guard", onBash(command), dir).exitCode;
 
 test("a `>` inside quotes, after an escaped quote, or escaped itself is not a redirection", () => {

package/hooks/paper-skills-nudge.hook.mjs

@@ -28,7 +28,7 @@
  * load at all, and a consumer-side thin spec that imports this logic is refused by
  * `vigiles compile` and can therefore never be re-stamped. The full reasoning, with both
  * measurements, is in that file's header; the capability surface of this one is asserted by
- * `hooks.harness.mjs` running `checkHookImports` over the shipped artifact.
+ * `hooks.harness.ts` running `checkHookImports` over the shipped artifact.
  */
 import {
   experimental_defineReact,

package/hooks/{paper-skills-nudge.test.mjs → paper-skills-nudge.test.ts}

@@ -5,12 +5,8 @@
 import assert from "node:assert/strict";
 import { join } from "node:path";
 import { test } from "vitest";
-import {
-  hookConsumer,
-  onEdit,
-  runShippedHook,
-} from "../test/hook-consumer.mjs";
-import { useTempDir } from "../test/support.mjs";
+import { hookConsumer, onEdit, runShippedHook } from "../test/hook-consumer.ts";
+import { useTempDir } from "../test/support.ts";
 
 const root = useTempDir("paper-skills-nudge-");
 

package/hooks/paper-status-gates.sh

@@ -2,7 +2,7 @@
 # paper-status-gates.sh — NOT A HOOK. This is a TOOL invoked by `paper-status-gates.hook.mjs`,
 # which owns the event routing and decides WHICH paper (if any) an edit concerned.
 #
-#   --surface <paper-dir>   print the readiness verdict + run the pipeline checker
+#   --surface <paper-dir>   print the readiness verdict and the unrun gates
 #
 # 🔴 WHAT LEFT THIS FILE AND WHY IT MATTERS. It used to read its payload with
 # `INPUT="${CLAUDE_TOOL_INPUT:-}"` plus a `timeout 1 cat` fallback and then grep that blob for a
@@ -28,22 +28,21 @@ case "$pdir_name" in
 esac
 
 # ── WHERE THE CONSUMER'S THINGS ARE — READ, NOT ASSUMED ─────────────────────
-# Both paths come from the one declaration every other carrier of this package reads, the
-# project's root paperlint.json (optional — absent means every default):
+# The papers path comes from the one declaration every other carrier of this package reads, the
+# project's root paperlint.json (optional — absent means the default):
 #
-#   { "papersDir": "docs/papers", "scripts": "tools/pipeline" }
+#   { "papersDir": "docs/papers" }
 #
 # ⚠️ `node -p` RATHER THAN grep/sed ON THE FILE. A JSON value is not a line of text: it can
 # be quoted, escaped, or spread across lines, and a pattern that gets it right today gets it
 # wrong on the first reformat — silently, by producing a root that matches nothing. Node is
-# already a hard dependency of the checker this script runs, so there is no new requirement.
+# already a hard dependency of the hook that runs this script, so there is no new requirement.
 ROOT_DIR="${CLAUDE_PROJECT_DIR:-.}"
 read_key() { # $1 = key, $2 = default
   node -p "((c) => c['$1'] ?? '$2')((() => { try { return require('$ROOT_DIR/paperlint.json') } catch { return {} } })())" \
     2>/dev/null || echo "$2"
 }
 papers_root="$(read_key papersDir papers)"
-scripts_root="$(read_key scripts .claude/skills/paper-pipeline/scripts)"
 
 # 🔴 AN UNUSABLE ROOT EXITS, IT DOES NOT BUILD A PATH FROM IT. `node -p` prints `undefined` for a
 # key whose value is literally `null` (`?? ` only catches null/undefined AFTER the object lookup,
@@ -69,18 +68,9 @@ else
   echo "   whether this paper is submittable, which is the one question it exists to answer." >&2
 fi
 
-CHECK="$ROOT_DIR/$scripts_root/pipeline-check.mjs"
-if [ -f "$CHECK" ]; then
-  # The real checker: stale continuous passes, gates missing their declared inputs, a study that
-  # ran before the claim was stated, submit-access inside the moderation window, a verdict that is
-  # only a percentage, unrun gates. Advisory, always exit 0.
-  node "$CHECK" "$ROOT_DIR/$pdir" >&2 || true
-else
-  # Fallback for a checkout without the skill tree — the old crude surface.
-  gates=$(grep -E '☐' "$STATUS" 2>/dev/null | grep -iE 'study-accepted|pc-panel|harden|verify.?citations' || true)
-  if [ -n "$gates" ]; then
-    echo "⚠️ UNRUN GATES in $pdir/PIPELINE-STATUS.md (☐ — run them, don't 'anti-churn'-skip):" >&2
-    echo "$gates" | sed -E 's/\|.*//; s/^\| */   /' >&2
-  fi
+gates=$(grep -E '☐' "$STATUS" 2>/dev/null | grep -iE 'study-accepted|pc-panel|harden|verify.?citations' || true)
+if [ -n "$gates" ]; then
+  echo "⚠️ UNRUN GATES in $pdir/PIPELINE-STATUS.md (☐ — run them, don't 'anti-churn'-skip):" >&2
+  echo "$gates" | sed -E 's/\|.*//; s/^\| */   /' >&2
 fi
 exit 0

package/hooks/{paper-status-gates.test.mjs → paper-status-gates.test.ts}

@@ -5,12 +5,8 @@
 import assert from "node:assert/strict";
 import { join } from "node:path";
 import { test } from "vitest";
-import {
-  hookConsumer,
-  onEdit,
-  runShippedHook,
-} from "../test/hook-consumer.mjs";
-import { useTempDir } from "../test/support.mjs";
+import { hookConsumer, onEdit, runShippedHook } from "../test/hook-consumer.ts";
+import { useTempDir } from "../test/support.ts";
 
 const root = useTempDir("paper-status-gates-");
 const STATUS = "**Readiness verdict:** ✅ fixture verdict line\n";

package/lib/agent-cli-version.harness.mjs

@@ -8,7 +8,7 @@
  */
 import assert from "node:assert/strict";
 import { recordCheck } from "vigiles";
-import { observeAgentCli, CHARACTERIZED_CLI } from "./agent-cli-version.mjs";
+import { observeAgentCli, CHARACTERIZED_CLI } from "./agent-cli-version.ts";
 
 /** A spawner that records how it was called, so the CALL SHAPE is assertable, not just the result. */
 const spawner = (result) => {

package/lib/{agent-cli-version.mjs → agent-cli-version.ts}

@@ -39,28 +39,42 @@ export const CHARACTERIZED_CLI = "2.1.227";
 /** What `claude --version` prints: `2.1.273 (Claude Code)`. */
 const VERSION_IN = /\b(\d+\.\d+\.\d+)\b/;
 
-/**
- * @typedef {object} CliObservation
- * @property {boolean} present  the binary answered `--version` with status 0
- * @property {string}  raw      the full line it printed, trimmed
- * @property {string}  version  the dotted version parsed out of it
- * @property {string}  characterized  the version the assertions were written against
- * @property {boolean} drifted  observed and characterized differ
- * @property {string}  note     one line naming BOTH numbers, for the report and for failures
- */
+/** What one `--version` probe of the agent CLI observed. */
+export interface CliObservation {
+  /** The binary answered `--version` with status 0. */
+  present: boolean;
+  /** The full line it printed, trimmed. */
+  raw: string;
+  /** The dotted version parsed out of it. */
+  version: string;
+  /** The version the assertions were written against. */
+  characterized: string;
+  /** Observed and characterized differ. */
+  drifted: boolean;
+  /** One line naming BOTH numbers, for the report and for failures. */
+  note: string;
+}
+
+/** The one process call the probe makes — injected, so every case is stageable. */
+export type SpawnVersion = (
+  program: string,
+  args: readonly string[],
+  options: { encoding: "utf8" },
+) => {
+  readonly status: number | null;
+  readonly stdout?: string | null;
+  readonly stderr?: string | null;
+};
 
-/**
- * @param {object} deps
- * @param {Function} deps.spawnSync  injected, so every case below is stageable
- * @param {string}  [deps.program]
- * @param {string}  [deps.characterized]
- * @returns {CliObservation}
- */
 export function observeAgentCli({
   spawnSync,
   program = "claude",
   characterized = CHARACTERIZED_CLI,
-}) {
+}: {
+  spawnSync: SpawnVersion;
+  program?: string;
+  characterized?: string;
+}): CliObservation {
   // 🔴 `encoding: "utf8"` IS THE FIX. With `stdio: "ignore"` — the shape this replaces — the
   // child's output goes nowhere and `probe.stdout` comes back null, so everything downstream
   // would be describing a string that was never read.
@@ -85,7 +99,7 @@ export function observeAgentCli({
   if (version === "")
     throw new Error(
       `\`${program} --version\` exited 0 but printed no version on stdout (got ${JSON.stringify(raw)}` +
-        `${probe.stderr ? `, stderr ${JSON.stringify(String(probe.stderr).trim().slice(0, 200))}` : ""}). ` +
+        `${probe.stderr ? `, stderr ${JSON.stringify(probe.stderr.trim().slice(0, 200))}` : ""}). ` +
         `A presence probe is not an observation: this is the \`stdio: "ignore"\` shape that issue #7 ` +
         `is about, and a version nobody read must not be reported as one.`,
     );

package/lib/check.test.ts

@@ -1,6 +1,6 @@
 import assert from "node:assert/strict";
 import { test } from "vitest";
-import { createChecker, failureMessage, renderDetail } from "./check.mjs";
+import { createChecker, failureMessage, renderDetail } from "./check.ts";
 
 test("renderDetail: a string verbatim, nothing for empty, a value inspected, a thunk called", () => {
   assert.deepEqual(
@@ -32,7 +32,7 @@ test("createChecker: counts every call, stays silent on a pass", () => {
   const printed: string[] = [];
   const check = createChecker({ log: (s) => printed.push(s) });
   check("a", true);
-  check("b", 1 === 1, "unused detail");
+  check("b", true, "unused detail");
   assert.deepEqual({ count: check.count, printed }, { count: 2, printed: [] });
 });
 
@@ -40,10 +40,15 @@ test("createChecker: a failure throws AND prints the label with its detail, and
   const printed: string[] = [];
   const check = createChecker({ log: (s) => printed.push(s) });
   // Guards: the detail reaches the reader — the drift this helper replaced dropped it.
-  assert.throws(() => check("the label", false, { got: 3 }), {
-    name: "AssertionError",
-    message: "the label — { got: 3 }",
-  });
+  assert.throws(
+    () => {
+      check("the label", false, { got: 3 });
+    },
+    {
+      name: "AssertionError",
+      message: "the label — { got: 3 }",
+    },
+  );
   assert.deepEqual(
     { count: check.count, printed },
     { count: 1, printed: ["✗ the label — { got: 3 }"] },
@@ -57,11 +62,11 @@ test("createChecker: a detail thunk is only evaluated on failure", () => {
     calls++;
     return "x";
   });
-  assert.throws(() =>
+  assert.throws(() => {
     check("fail", false, () => {
       calls++;
       return "x";
-    }),
-  );
+    });
+  });
   assert.equal(calls, 1);
 });