paperlint 3.0.0 → 3.1.1

package/eslint-rules/review-frontmatter.test.mjs

@@ -5,7 +5,7 @@
 import { describe, expect, it } from "vitest";
 import { ESLint } from "eslint";
 import markdown from "@eslint/markdown";
-import review from "./review-frontmatter.mjs";
+import review, { errorsOf } from "./review-frontmatter.mjs";
 import sibling from "./sibling-frontmatter.mjs";
 
 async function lint(text) {
@@ -81,6 +81,42 @@ describe("review/frontmatter — the findings record", () => {
   });
 });
 
+describe("review/frontmatter — what the parser and the validator may hand back", () => {
+  /** The rule's visitors over a fake context; the reports it makes. */
+  const visit = (value) => {
+    const reports = [];
+    const v = review.rules.frontmatter.create({
+      report: (r) => reports.push(r),
+    });
+    v.yaml({ value });
+    v["root:exit"]({});
+    return reports.map(
+      (r) => r.messageId + (r.data?.why ? `: ${r.data.why}` : ""),
+    );
+  };
+
+  it("an empty frontmatter block is validated as `{}` — silent", async () => {
+    expect(await lint("---\n---\n# Review\n")).toEqual([]);
+    expect(visit(undefined)).toEqual([]);
+  });
+
+  it("a parser failure without a YAML reason is reported by its message, or as unparseable", () => {
+    const throwing = (thrown) => ({
+      toString() {
+        throw thrown;
+      },
+    });
+    expect(visit(throwing(new Error("boom")))).toEqual(["malformed: boom"]);
+    expect(visit(throwing("not an Error"))).toEqual(["malformed: unparseable"]);
+  });
+
+  it("a failed validation with no errors attached names nothing", () => {
+    const validate = () => false;
+    validate.errors = null;
+    expect(errorsOf(validate, {})).toEqual([]);
+  });
+});
+
 describe("sibling/frontmatter — the same mechanism, the package's own sibling-card schema", () => {
   async function card(text) {
     const eslint = new ESLint({

package/eslint-rules/temp-root-realpath.harness.mjs

@@ -146,6 +146,55 @@ const cases = [];
   );
 }
 
+// ── 5b. `realpathSync.native(…)` resolves too — as a bare import and through a namespace. A
+//       `.native(…)` on anything else is NOT a resolve: another object, a computed member, a call
+//       result, a bare `native` function. Each of those still gets its finding.
+{
+  const root = 'mkdtempSync(join(tmpdir(), "probe-"))';
+  const silent = await on(
+    `${HEAD}import * as fs from "node:fs";\n` +
+      `const a = realpathSync.native(${root});\nconst b = fs.realpathSync.native(${root});\n`,
+  );
+  assert.deepEqual(
+    silent,
+    [],
+    `realpathSync.native must exempt the root; got: ${JSON.stringify(silent)}`,
+  );
+  for (const wrap of [
+    "keep",
+    "other.native",
+    "fs[name].native",
+    "pick().native",
+    "native",
+  ]) {
+    const m = await on(`${HEAD}const r = ${wrap}(${root});\n`);
+    assert.equal(
+      m.length,
+      1,
+      `${wrap}(…) does not resolve the path — one finding expected, got ${JSON.stringify(m)}`,
+    );
+  }
+  cases.push(
+    "realpathSync.native / fs.realpathSync.native exempt; keep, other.native, fs[name].native, pick().native, native do not",
+  );
+}
+
+// ── 5c. The walk over the arguments survives the shapes that are not plain nodes: an array hole
+//       (null) and a regex literal's `regex` object (no `type`). Neither is a `tmpdir()` call.
+{
+  const m = await on(
+    `${HEAD}const a = mkdtempSync([, /tmp/g]);\nconst b = mkdtempSync([, /x/, tmpdir()]);\n`,
+  );
+  assert.deepEqual(
+    m.map((x) => x.line),
+    [5],
+    `only the second call names tmpdir(); got: ${JSON.stringify(m)}`,
+  );
+  cases.push(
+    "an array hole and a regex literal in the arguments are walked, not mistaken",
+  );
+}
+
 // ── 6. 🔴 THE CORPUS ITSELF IS CLEAN. The "silent" half on a made-up string says nothing
 //      about the repository: the rule could also be silent because it was never handed a
 //      single file (the recorded class — `scripts/rules-see-files.mjs`). So this check runs

package/eslint-rules/tex-build.mjs

@@ -156,10 +156,10 @@ const futurePromise = {
     return {
       root() {
         // 🔴 ONE GUARD, NOT THREE. The first draft had `if (!file || !existsSync(file))`
-        // BEFORE the read — and a mutation run on 2026-09-07 showed that removing that line is
-        // caught by NOTHING: the `try/catch` around the read covers exactly the same cases (no
-        // path, a `<text>` run through stdin, no permission). Two guards doing one job is a
-        // guard no mutation can kill, i.e. a dead assertion dressed as robustness.
+        // BEFORE the read — removing that line on 2026-09-07 showed it is caught by NOTHING:
+        // the `try/catch` around the read covers exactly the same cases (no path, a `<text>` run
+        // through stdin, no permission). Two guards doing one job is a guard the harness can
+        // never fail on, i.e. a dead assertion dressed as robustness.
         // What is left is the read inside `try`: stay quiet rather than judge content we never
         // saw.
         let text;
@@ -264,7 +264,7 @@ const acmFrontmatterOverride = {
       root() {
         // Same single guard as the sibling rule, and for the same measured reason: a separate
         // `existsSync` before the read is covered by this `catch` in every case it could
-        // fire, i.e. it is an assertion no mutation can kill.
+        // fire, i.e. it is an assertion the harness can never fail on.
         let text;
         try {
           text = readFileSync(context.filename, "utf8");
@@ -289,14 +289,14 @@ const acmFrontmatterOverride = {
           for (const { re, removes } of FRONTMATTER_OVERRIDES) {
             // 🔴 NO `re.lastIndex = 0` HERE, AND THAT IS A MEASUREMENT. These regexes are
             // module-level and `/g`, so they carry `lastIndex` across files, and the obvious
-            // defensive line is to reset it. A mutation run on 2026-09-11 removed that line
-            // and the harness stayed GREEN — because the loop below always drains the regex,
-            // and a `/g` `exec` that returns `null` resets `lastIndex` to 0 by itself. The
-            // reset was a guard no mutation could kill, i.e. the same dead assertion dressed
-            // as robustness that the sibling rule's single-`try` comment describes. What
-            // keeps the property honest instead is an ASSERTION, not a line of code: the
-            // harness lints the same input twice in one process and requires the two runs to
-            // agree. Add a `break` to this loop and that assertion is what will fail.
+            // defensive line is to reset it. Removing that line on 2026-09-11 left the harness
+            // GREEN — because the loop below always drains the regex, and a `/g` `exec` that
+            // returns `null` resets `lastIndex` to 0 by itself. The reset was a guard the
+            // harness could never fail on, i.e. the same dead assertion dressed as robustness
+            // that the sibling rule's single-`try` comment describes. What keeps the property
+            // honest instead is an ASSERTION, not a line of code: the harness lints the same
+            // input twice in one process and requires the two runs to agree. Add a `break` to
+            // this loop and that assertion is what will fail.
             let m;
             while ((m = re.exec(line)) !== null) {
               const column = m.index + 1;

package/eslint.config.mjs

@@ -138,6 +138,9 @@ export const layerBoundaries = (root) => ({
         partialMatch: false,
         capture: ["kind"],
       },
+      // test/support.mjs — shared helpers for tests. Only the `test` category may import it: the
+      // policies below allow tests any element, and allow no other file this one.
+      { type: "test-support", pattern: "test", partialMatch: false },
     ],
     "boundaries/files": [
       // `exclusive`: the root also matches the app pattern below, and is only the root.
@@ -369,8 +372,9 @@ export default [
    * 🔴 THIS BLOCK COVERS THE PACKAGE ITSELF, and before 2026-09-15 it was not here: the config held only
    * one block for `.tex` (I don't quote the glob inside this comment: the sequence
    * "star-slash" would close the comment itself — which is where I tripped), and a file with no block gets simply IGNORED by ESLint 9.
-   * Meaning: 133 own `.mjs` — mutation engine, three hooks, scripts for 24 skills — went unchecked,
-   * with green `npm run lint`. A tool that checks others' papers and not itself.
+   * Meaning: 133 own `.mjs` — a since-removed mutation-testing engine, three hooks, scripts for
+   * 24 skills — went unchecked, with green `npm run lint`. A tool that checks others' papers and
+   * not itself.
    *
    * Measurement on the first run: 15 files with dead imports (`resolve`, `pathToFileURL`) and
    * orphaned constants — remnants of a move from `mine`, where those names were needed. All

package/fixtures/toolchain-mirror/catalog.txt

@@ -3,3 +3,4 @@ acmart acmart.cls
 libertine libertine.sty
 texcount bin:texcount
 liar other.sty
+unicode-data GraphemeBreakProperty.txt

package/fixtures/toolchain-mirror/install-tl

@@ -17,11 +17,14 @@ if [ -n "${FAKE_INSTALL_TL_FAIL:-}" ]; then
   exit 1
 fi
 mkdir -p "$dir/bin/x86_64-linux"
-for t in pdflatex kpsewhich tlmgr; do
+for t in pdflatex kpsewhich tlmgr fmtutil-sys; do
   cp "$here/stub-$t" "$dir/bin/x86_64-linux/$t"
   chmod +x "$dir/bin/x86_64-linux/$t"
 done
 : > "$dir/files.txt"
 # The real install-tl leaves release-texlive.txt at TEXDIR; stub-tlmgr reads the tree's year there.
 cp "$here/release-texlive.txt" "$dir/release-texlive.txt"
+# The real install-tl, when a mirror fails to serve a package, prints "continuing anyway" and
+# exits as if nothing happened. FAKE_INSTALL_TL_DROP names the package it lost.
+if [ -n "${FAKE_INSTALL_TL_DROP:-}" ]; then echo "$FAKE_INSTALL_TL_DROP" > "$dir/missing-deps.txt"; fi
 echo "fake install-tl: scheme-basic into $dir"

package/fixtures/toolchain-mirror/stub-fmtutil-sys

@@ -0,0 +1,4 @@
+#!/bin/sh
+# Stands in for fmtutil-sys: records its arguments in fmtutil.log at the tree root.
+bin=$(cd "$(dirname "$0")" && pwd)
+echo "$*" >> "$bin/../../fmtutil.log"

package/fixtures/toolchain-mirror/stub-tlmgr

@@ -9,6 +9,15 @@ while [ $# -gt 0 ]; do
   case "$1" in
     --repository) repo=$2; shift 2 ;;
     install) shift; break ;;
+    # `check depends` in tlmgr's own layout: every name in missing-deps.txt (what the stub
+    # install-tl was told to drop) is a dependency without a package. Not logged: it installs nothing.
+    check)
+      if [ -s "$tree/missing-deps.txt" ]; then
+        echo " DEPENDS WITHOUT PACKAGES:"
+        sed 's/$/ in: collection-basic latex-bin/' "$tree/missing-deps.txt"
+        exit 2
+      fi
+      exit 0 ;;
     *) shift ;;
   esac
 done
@@ -34,6 +43,12 @@ for p in "$@"; do
     status=1
     continue
   fi
+  # Installing a dropped dependency repairs the tree.
+  # Portable on purpose: macOS sed -i takes a backup suffix, GNU sed does not.
+  if [ -f "$tree/missing-deps.txt" ]; then
+    grep -vx "$p" "$tree/missing-deps.txt" > "$tree/missing-deps.tmp" || true
+    mv "$tree/missing-deps.tmp" "$tree/missing-deps.txt"
+  fi
   for item in ${line#* }; do
     case "$item" in
       bin:*) : > "$bin/${item#bin:}"; chmod +x "$bin/${item#bin:}" ;;

package/hooks/hooks.harness.mjs

@@ -21,9 +21,7 @@
  * `.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`
- * Killed by: `hooks/hooks.mutations.mjs`
  */
-import assert from "node:assert/strict";
 import { runHook } from "vigiles";
 import { checkHookImports } from "vigiles/hook";
 import {
@@ -40,6 +38,7 @@ 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";
 
 const HOOKS = dirname(fileURLToPath(import.meta.url));
 const ROOT = resolve(HOOKS, "..");
@@ -51,11 +50,7 @@ const SHIPPED = readdirSync(HOOKS)
   .filter((f) => f.endsWith(".hook.mjs"))
   .sort();
 
-let n = 0;
-const check = (label, cond) => {
-  assert.ok(cond, label);
-  n++;
-};
+const check = createChecker();
 
 /**
  * A throwaway consumer repository: a root `paperlint.json` holding the given settings (none when
@@ -492,7 +487,7 @@ try {
       // 🔴 AND SILENT ON THE DEFAULT ROOT TOO — this is the half that catches `??`. With
       // `declared ?? DEFAULT` an explicit `null` is read as «nothing was declared», the prefix
       // becomes `papers/`, and the nudge starts firing about a tree the consumer never named.
-      // Without this case that mutation survives, because the assertion above passes either way.
+      // Without this case that defect survives, because the assertion above passes either way.
       const d = at(
         broken,
         "paper-skills-nudge",
@@ -629,8 +624,8 @@ try {
     );
     // 🔴 THE NASTY NAME NEEDS A REAL DIRECTORY BEHIND IT, or the assertion cannot fail. First
     // draft just passed `a;b` and checked for silence — but a name that names nothing is silent
-    // anyway, for want of a status file, so the mutation that DELETES the name check survived
-    // green. The fixture now contains a paper literally called `a;b` with a status file in it:
+    // anyway, for want of a status file, so deleting the name check would leave this harness
+    // green regardless. The fixture now contains a paper literally called `a;b` with a status file in it:
     // with the check, silence; without it, the verdict comes out. Measured 2026-09-12.
     mkdirSync(join(dir, "docs/papers/a;b"), { recursive: true });
     writeFileSync(
@@ -648,7 +643,7 @@ try {
     );
   }
 
-  console.log(`hooks.harness: ${n} assertions passed`);
+  console.log(`hooks.harness: ${check.count} assertions passed`);
 } finally {
   for (const d of tmps) rmSync(d, { recursive: true, force: true });
 }

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

@@ -355,8 +355,8 @@ const MUTATORS = [
  * `runs()` now sees through `env`, `env -C`, `command`, `nice`, `xargs`, `sudo`, `time`, a
  * repeated space and a quoted head — every form tried. So the crutch defended nothing, which is
  * not a judgement but a measurement: removing it left all 78 harness assertions GREEN, and no
- * command form could be found that it alone catches. A line no mutation can kill is a line
- * documenting a defence that does not exist, so it was deleted rather than kept for comfort.
+ * command form could be found that it alone catches. A line the harness can never fail on is a
+ * line documenting a defence that does not exist, so it was deleted rather than kept for comfort.
  *
  * ⚠️ WHAT THIS DOES NOT FIX: rows 3 and 4 above. A wrapper that moves the working directory is
  * still invisible, because `touches`/`namesPaperSource` compare against a repo-root prefix and

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

@@ -0,0 +1,61 @@
+/**
+ * paper-edit-guard's Bash scan on the shapes the hooks harness does not carry: a `>` inside quotes
+ * or escaped (not a redirection), a target spelled with backslashes (read through them), a target
+ * ended by a delimiter, and a mutator that moves a paper source AWAY — a write `writesTo` does not
+ * see, which the `touches` fallback catches. Each case runs the hook the way a consumer's settings
+ * run it: `vigiles hook-runtime run-program`, from a throwaway project.
+ */
+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";
+
+const dir = hookConsumer(useTempDir("paper-edit-guard-"), {
+  "papers/alpha/PIPELINE-STATUS.md": "# S\n",
+});
+/** `>` built rather than typed: a literal one here would be a redirection to the guard's own scan. */
+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) =>
+  runShippedHook("paper-edit-guard", onBash(command), dir).exitCode;
+
+test("a `>` inside quotes, after an escaped quote, or escaped itself is not a redirection", () => {
+  assert.deepEqual(
+    [
+      guard(`echo "a ${GT} ${P}"`),
+      guard(`echo "a \\" ${GT} b"`),
+      guard(`echo a\\${GT} ${P}`),
+    ],
+    [0, 0, 0],
+  );
+});
+
+test("a redirection target is read through backslashes, quoted or not, and ends at a delimiter", () => {
+  assert.deepEqual(
+    [
+      guard(`echo x ${GT} "papers/alpha/pa\\per.md"`),
+      guard(`echo x ${GT} papers/alpha/pa\\per.md`),
+      guard(`echo x ${GT}${P}; true`),
+    ],
+    [2, 2, 2],
+  );
+});
+
+test("moving a paper source away is a write to it: denied", () => {
+  assert.equal(guard(`mv ${P} /tmp/elsewhere.md`), 2);
+});
+
+test("a command cut off right after a backslash still names its target, quoted or not", () => {
+  // The backslash escapes nothing — there is no next character — and the target read so far
+  // is still a paper source.
+  assert.deepEqual(
+    [guard(`echo x ${GT} ${P}\\`), guard(`echo x ${GT} "${P}\\`)],
+    [2, 2],
+  );
+});

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

@@ -71,8 +71,8 @@ const READ_CONFIG = `f="\${CLAUDE_PROJECT_DIR:-.}/${CONFIG_FILE}"; if [ -e "$f"
  * `e.path.under()`, and vigiles normalises the prefix itself (`normalizePrefix` →
  * `trimTrailingSeparators`), so `"docs/papers/"` and `"docs/papers"` are the same prefix to it.
  * A normalise here would be a line no test could kill, which is a line that documents a
- * defence that does not exist. Checked 2026-09-12 by mutation: removing it left the harness
- * green, which is the finding that produced this paragraph.
+ * defence that does not exist. Confirmed 2026-09-12: removing it left the harness green, which
+ * is the finding that produced this paragraph.
  *
  * ⚠️ A NUDGE FALLS SILENT WHERE THE GATE REFUSES, and the asymmetry is the decision, not an
  * inconsistency. `paper-edit-guard` denies on an unreadable declaration because a gate that

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

@@ -0,0 +1,38 @@
+/**
+ * paper-skills-nudge on the two declarations the hooks harness does not carry: none at all (the
+ * default `papers/` root applies) and one that does not parse (silence — a nudge never blocks).
+ */
+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";
+
+const root = useTempDir("paper-skills-nudge-");
+
+test("no paperlint.json: an edit to papers/<p>/paper.md gets the checklist", () => {
+  const dir = hookConsumer(join(root, "default"));
+  const r = runShippedHook(
+    "paper-skills-nudge",
+    onEdit("papers/alpha/paper.md"),
+    dir,
+  );
+  assert.equal(r.exitCode, 0);
+  assert.notEqual(r.stdout, "");
+});
+
+test("a paperlint.json that does not parse: silent, exit 0", () => {
+  const dir = hookConsumer(join(root, "broken"), {
+    "paperlint.json": "{ nope",
+  });
+  const r = runShippedHook(
+    "paper-skills-nudge",
+    onEdit("papers/alpha/paper.md"),
+    dir,
+  );
+  assert.deepEqual([r.exitCode, r.stdout, r.stderr], [0, "", ""]);
+});

package/hooks/paper-status-gates.test.mjs

@@ -0,0 +1,42 @@
+/**
+ * paper-status-gates on the two declarations the hooks harness does not carry: none at all (the
+ * default `papers/` root applies) and one that does not parse (silence — this hook never blocks).
+ */
+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";
+
+const root = useTempDir("paper-status-gates-");
+const STATUS = "**Readiness verdict:** ✅ fixture verdict line\n";
+
+test("no paperlint.json: an edit under papers/ runs the gates for that paper", () => {
+  const dir = hookConsumer(join(root, "default"), {
+    "papers/alpha/PIPELINE-STATUS.md": STATUS,
+  });
+  const r = runShippedHook(
+    "paper-status-gates",
+    onEdit("papers/alpha/paper.md"),
+    dir,
+  );
+  assert.equal(r.exitCode, 0);
+  assert.match(r.stderr, /fixture verdict line/);
+});
+
+test("a paperlint.json that does not parse: silent, exit 0", () => {
+  const dir = hookConsumer(join(root, "broken"), {
+    "paperlint.json": "{ nope",
+    "papers/alpha/PIPELINE-STATUS.md": STATUS,
+  });
+  const r = runShippedHook(
+    "paper-status-gates",
+    onEdit("papers/alpha/paper.md"),
+    dir,
+  );
+  assert.deepEqual([r.exitCode, r.stdout, r.stderr], [0, "", ""]);
+});

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

@@ -107,6 +107,13 @@ const cases = [];
   cases.push(
     'exit 0 + empty stdout (the `stdio: "ignore"` shape) → throws, does not report a blank',
   );
+  // …and what the program DID say, on stderr, is carried into the refusal: it is the only clue.
+  const chatty = spawner({ status: 0, stdout: "", stderr: "  warming up\n" });
+  assert.throws(
+    () => observeAgentCli({ spawnSync: chatty }),
+    /\(got "", stderr "warming up"\)/,
+  );
+  cases.push("…and the stderr it printed instead is quoted in the refusal");
 }
 
 // ── 5. THE CALL SHAPE, asserted directly. Case 4 catches a discarding probe only because the

package/lib/check.d.mts

@@ -0,0 +1,17 @@
+// Types for lib/check.mjs — the shared harness assertion helper (see the module).
+
+/** A failure detail: text, any value (rendered with `util.inspect`), or a thunk producing one. */
+export type Detail = unknown;
+
+export declare function renderDetail(detail: Detail): string;
+export declare function failureMessage(label: string, detail: Detail): string;
+
+export interface Check {
+  (label: string, cond: unknown, detail?: Detail): void;
+  /** How many times this checker has been called. */
+  readonly count: number;
+}
+
+export declare function createChecker(options?: {
+  log?: (line: string) => void;
+}): Check;

package/lib/check.mjs

@@ -0,0 +1,50 @@
+/**
+ * The one assertion helper every `*.harness.mjs` uses.
+ *
+ * Until #52 each harness defined its own `check()`, and the copies had drifted: some printed a
+ * detail on failure and some dropped it, some joined it with " — " and some with a newline, and two
+ * passed the LABEL to vigiles' `recordCheck(n)`, which adds its argument to a number — so the
+ * recorded count became a string. One helper removes the drift instead of documenting it.
+ *
+ * What it guarantees:
+ *   - a failure names the label AND the detail, on stderr and in the thrown assertion — the detail
+ *     is what makes a red run diagnosable without re-running it;
+ *   - `detail` may be a function, so an expensive rendering is paid only on failure;
+ *   - every call is counted (`check.count`) and reported to the vigiles runner (`recordCheck`), so
+ *     a harness's summary line and the runner's check count come from the same place.
+ */
+import assert from "node:assert/strict";
+import { inspect } from "node:util";
+import { recordCheck } from "vigiles";
+
+/** A failure detail as text: strings verbatim, other values through `util.inspect`, a thunk called. */
+export function renderDetail(detail) {
+  const value = typeof detail === "function" ? detail() : detail;
+  if (value === undefined || value === null || value === "") return "";
+  return typeof value === "string" ? value : inspect(value, { depth: 6 });
+}
+
+/** The label, then the detail: on the same line when it is one line, below it when it is many. */
+export function failureMessage(label, detail) {
+  const shown = renderDetail(detail);
+  if (!shown) return label;
+  return shown.includes("\n") ? `${label}\n${shown}` : `${label} — ${shown}`;
+}
+
+/**
+ * A fresh `check(label, cond, detail?)`. `check.count` is how many times it has been called.
+ * `log` is where a failure is printed — stderr unless this module's own test injects one.
+ */
+export function createChecker({ log = console.error } = {}) {
+  let count = 0;
+  const check = (label, cond, detail) => {
+    count++;
+    recordCheck();
+    if (cond) return;
+    const message = failureMessage(label, detail);
+    log(`✗ ${message}`);
+    assert.fail(message);
+  };
+  Object.defineProperty(check, "count", { get: () => count });
+  return check;
+}

package/lib/check.test.ts

@@ -0,0 +1,67 @@
+import assert from "node:assert/strict";
+import { test } from "vitest";
+import { createChecker, failureMessage, renderDetail } from "./check.mjs";
+
+test("renderDetail: a string verbatim, nothing for empty, a value inspected, a thunk called", () => {
+  assert.deepEqual(
+    [
+      renderDetail("as is"),
+      renderDetail(""),
+      renderDetail(undefined),
+      renderDetail(null),
+      renderDetail({ a: [1, 2] }),
+      renderDetail(() => "lazy"),
+      renderDetail(() => undefined),
+    ],
+    ["as is", "", "", "", "{ a: [ 1, 2 ] }", "lazy", ""],
+  );
+});
+
+test("failureMessage: label alone, label — detail, or label on its own line above a multi-line detail", () => {
+  assert.deepEqual(
+    [
+      failureMessage("L", undefined),
+      failureMessage("L", "d"),
+      failureMessage("L", "one\ntwo"),
+    ],
+    ["L", "L — d", "L\none\ntwo"],
+  );
+});
+
+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");
+  assert.deepEqual({ count: check.count, printed }, { count: 2, printed: [] });
+});
+
+test("createChecker: a failure throws AND prints the label with its detail, and is counted", () => {
+  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.deepEqual(
+    { count: check.count, printed },
+    { count: 1, printed: ["✗ the label — { got: 3 }"] },
+  );
+});
+
+test("createChecker: a detail thunk is only evaluated on failure", () => {
+  let calls = 0;
+  const check = createChecker({ log: () => {} });
+  check("pass", true, () => {
+    calls++;
+    return "x";
+  });
+  assert.throws(() =>
+    check("fail", false, () => {
+      calls++;
+      return "x";
+    }),
+  );
+  assert.equal(calls, 1);
+});