paperlint 3.0.0 → 3.1.1

package/src/hooks-settings.ts

@@ -93,8 +93,8 @@ interface Run {
  */
 function parseRun(command: string): Run | null {
   const tokens = command.trim().split(/\s+/).map(bare);
-  for (let i = 0; i < tokens.length; i++) {
-    const run = runAt(tokens, i);
+  for (const [i, token] of tokens.entries()) {
+    const run = runAt(token, tokens.slice(i + 1, i + 3));
     if (run) return run;
   }
   return null;
@@ -108,17 +108,13 @@ function insidePackage(parts: readonly string[]): readonly string[] {
   return at === -1 ? [] : parts.slice(at + 2);
 }
 
-/** The run token `i` starts, if it names a paperlint hook. */
-function runAt(tokens: readonly string[], i: number): Run | null {
-  const t = posix.normalize(tokens[i] ?? "");
+/** The run `token` starts, if it names a paperlint hook; `after` is the two tokens that follow it. */
+function runAt(token: string, after: readonly string[]): Run | null {
+  const t = posix.normalize(token);
   const inside = insidePackage(t.split("/"));
   const inBin = inside[0] === "bin" && inside.length === 2;
-  const name = tokens[i + 2];
-  if (
-    (inBin || basename(t) === PACKAGE_NAME) &&
-    tokens[i + 1] === "hook" &&
-    name
-  )
+  const [verb, name] = after;
+  if ((inBin || basename(t) === PACKAGE_NAME) && verb === "hook" && name)
     return { name, ours: t === MANAGED_BY, path: t };
   if (inside[0] === "hooks" && inside[1]?.endsWith(".hook.mjs"))
     return { name: basename(inside[1], ".hook.mjs"), ours: false, path: t };
@@ -171,22 +167,33 @@ export function shippedWiring(file: string = WIRING_FILE): Wiring {
   return { compiled, names: [...new Set(names)] };
 }
 
-/** How many commands run each shipped hook, split by spelling. */
+/** How many commands run one shipped hook, split by spelling. */
+export interface HookCount {
+  readonly name: string;
+  readonly ours: number;
+  readonly other: number;
+}
+
+/** One count per name in `names`, in that order — a name nothing runs has zeros, never a gap. */
 export function wiredCounts(
   settings: Settings,
   names: readonly string[],
-): Map<string, { ours: number; other: number }> {
-  const counts = new Map(names.map((n) => [n, { ours: 0, other: 0 }]));
-  for (const { command } of commandsIn(settings)) {
+): readonly HookCount[] {
+  const runs = commandsIn(settings).flatMap(({ command }) => {
     const run = hookRun(command);
-    const slot = run ? counts.get(run.name) : undefined;
-    if (run && slot)
-      if (run.ours) slot.ours++;
-      else slot.other++;
-  }
-  return counts;
+    return run ? [run] : [];
+  });
+  const count = (name: string, ours: boolean): number =>
+    runs.filter((r) => r.name === name && r.ours === ours).length;
+  return names.map((name) => ({
+    name,
+    ours: count(name, true),
+    other: count(name, false),
+  }));
 }
 
+const total = (c: HookCount): number => c.ours + c.other;
+
 export type SettingsRead =
   | { readonly status: "absent"; readonly path: string; readonly settings: {} }
   | {
@@ -258,15 +265,16 @@ export function wireHooks(
   const read = readSettings(root);
   if (read.status === "unparsable") return read;
   const { path, settings } = read;
-  const found = commandsIn(settings)
-    .map(({ command }) => ({ command, run: hookRun(command) }))
-    .filter(({ run }) => run && !run.ours && wiring.names.includes(run.name))
-    .map(({ command, run }) => ({ name: run?.name ?? "", command }));
+  const found = commandsIn(settings).flatMap(({ command }) => {
+    const run = hookRun(command);
+    return run && !run.ours && wiring.names.includes(run.name)
+      ? [{ name: run.name, command }]
+      : [];
+  });
   if (found.length > 0) {
-    const counts = wiredCounts(settings, wiring.names);
-    const missing = wiring.names.filter(
-      (n) => (counts.get(n)?.ours ?? 0) + (counts.get(n)?.other ?? 0) === 0,
-    );
+    const missing = wiredCounts(settings, wiring.names)
+      .filter((c) => total(c) === 0)
+      .map((c) => c.name);
     return { status: "foreign", path, names: wiring.names, found, missing };
   }
 
@@ -297,19 +305,17 @@ export function doctorHooks(
     return out;
   }
   const counts = wiredCounts(read.settings, wiring.names);
-  const total = (n: string): number =>
-    (counts.get(n)?.ours ?? 0) + (counts.get(n)?.other ?? 0);
-  const missing = wiring.names.filter((n) => total(n) === 0);
-  const twice = wiring.names.filter((n) => total(n) > 1);
+  const missing = counts.filter((c) => total(c) === 0).map((c) => c.name);
+  const twice = counts.filter((c) => total(c) > 1);
   // `init` refuses to write while any hook is wired under another spelling, so its remedy must
   // not be offered then — the remedy is to pick ONE form.
-  const handWired = wiring.names.some((n) => (counts.get(n)?.other ?? 0) > 0);
+  const handWired = counts.some((c) => c.other > 0);
   const remedy = handWired
     ? `some paperlint hooks are wired by hand under another spelling, and \`npx paperlint init\` writes nothing then — add the missing ones in that same form, or delete the hand-written ones and run \`npx paperlint init\``
     : `\`npx paperlint init\` adds them`;
   if (twice.length > 0) {
     out.push(`  ⚠ wired TWICE — each of these runs more than once per event:`);
-    for (const n of twice) out.push(`      ${n} ×${String(total(n))}`);
+    for (const c of twice) out.push(`      ${c.name} ×${String(total(c))}`);
     out.push(
       `      keep one command per hook; \`npx paperlint init\` writes the ${MANAGED_BY} form`,
     );

package/src/init.test.ts

@@ -1,9 +1,12 @@
 /**
- * `paperlint init` over a project that ALREADY declares its papers directory: the declaration is
- * the answer, and init reports it — not a directory it discovered elsewhere and then did not use.
+ * `paperlint init`: how the papers directory is decided and declared, the refusals over a
+ * `paperlint.json` it cannot use, and each section of its report, asserted whole.
  *
- * Seen migrating a consumer project: init printed "papers directory ✓ eslint-rules/fixtures — 4
- * candidates", then kept the declared papersDir. The line described a decision that was not made.
+ * The first block is the one this file was written for — a project that ALREADY declares its
+ * papers directory: the declaration is the answer, and init reports it, not a directory it
+ * discovered elsewhere and then did not use. Seen migrating a consumer project: init printed
+ * "papers directory ✓ eslint-rules/fixtures — 4 candidates", then kept the declared papersDir.
+ * The line described a decision that was not made.
  */
 import {
   existsSync,
@@ -17,7 +20,21 @@ import {
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
-import { choosePapers, init } from "./init.ts";
+import { FRESH_CLONE_NOTE } from "./hooks-settings.ts";
+import {
+  UNPINNED_REF,
+  WORKFLOW_PATH,
+  choosePapers,
+  declarePapers,
+  init,
+  offerHooks,
+  offerTexLive,
+  reportHooks,
+  reportSkillLinks,
+  reportTexLive,
+  reportWorkflow,
+} from "./init.ts";
+import { runNode } from "../test/support.mjs";
 
 const dirs: string[] = [];
 afterEach(() => {
@@ -204,3 +221,289 @@ describe("paperlint init — TeX Live is offered with its cost, never installed
     expect(r.text).toMatch(/✓ paperlint's TeX Live is installed/);
   });
 });
+
+/** A throwaway project from `{ path: contents }`. */
+function tree(files: Record<string, string>): string {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "paperlint-init-")));
+  dirs.push(root);
+  for (const [p, text] of Object.entries(files)) {
+    mkdirSync(join(root, p, ".."), { recursive: true });
+    writeFileSync(join(root, p), text);
+  }
+  return root;
+}
+
+/** init with everything outside the papers step stubbed out; returns the code and both streams. */
+async function initRun(
+  root: string,
+  opts: Parameters<typeof init>[1] = {},
+): Promise<{ code: number; out: string[]; err: string[] }> {
+  const out: string[] = [];
+  const err: string[] = [];
+  const code = await init(root, {
+    cwd: root,
+    log: (s: string) => out.push(s),
+    err: (s: string) => err.push(s),
+    interactive: false,
+    hooks: false,
+    run: (() => ({ status: 0 })) as never,
+    link: () => ({ ok: false, error: "not linked in this test" }),
+    ...opts,
+  });
+  return { code, out, err };
+}
+
+describe("paperlint init — a paperlint.json it cannot use stops it before anything is written", () => {
+  it("unparsable: exit 2, the reason, and nothing written", async () => {
+    const root = tree({ "paperlint.json": "{ nope" });
+    const r = await initRun(root);
+    expect(r.code).toBe(2);
+    expect(r.err[0]).toMatch(/^ {2}✗ paperlint\.json is not valid JSON: /);
+    expect(r.err.slice(1)).toEqual([
+      "      nothing was written. The hooks read their papers directory from this file and",
+      "      refuse every Bash command while it cannot be parsed — fix the JSON first.",
+    ]);
+    expect(readFileSync(join(root, "paperlint.json"), "utf8")).toBe("{ nope");
+  });
+
+  it("a papersDir that is not a string: exit 2, named", async () => {
+    const root = tree({ "paperlint.json": '{ "papersDir": 7 }' });
+    const r = await initRun(root);
+    expect([r.code, r.err]).toEqual([
+      2,
+      [
+        "  ✗ paperlint.json declares papersDir = 7 — it must be a directory path (a string)",
+      ],
+    ]);
+  });
+
+  it("a file without a trailing newline keeps having none", async () => {
+    const root = tree({
+      "paperlint.json": '{"x":1}',
+      "drafts/a/paper.md": "# a\n",
+    });
+    const decl = await declarePapers(root, () =>
+      choosePapers(root, { interactive: false }),
+    );
+    expect(decl.status).toBe("written");
+    expect(readFileSync(join(root, "paperlint.json"), "utf8")).toBe(
+      '{\n  "x": 1,\n  "papersDir": "drafts"\n}',
+    );
+  });
+});
+
+describe("paperlint init — how several candidate directories were decided, said", () => {
+  const several = () =>
+    tree({ "drafts/a/paper.md": "# a\n", "writing/b/paper.md": "# b\n" });
+  const section = (out: string[]) =>
+    out.slice(out.indexOf("papers directory") + 1, out.indexOf("settings") - 1);
+
+  it("picked by a human", async () => {
+    const r = await initRun(several(), {
+      interactive: true,
+      ask: async () => "2",
+    });
+    expect(section(r.out)).toEqual([
+      "  ✓ writing — you picked it out of 2 candidates",
+    ]);
+  });
+
+  it("no terminal: the first, and the others named", async () => {
+    const r = await initRun(several());
+    expect(section(r.out)).toEqual([
+      "  ✓ drafts — 2 candidates, stdin is not a terminal so nothing was asked",
+      '      the others: writing — set "papersDir" in paperlint.json if this is the wrong one',
+    ]);
+  });
+
+  it("an answer that picks nothing: the first, and said so", async () => {
+    const r = await initRun(several(), {
+      interactive: true,
+      ask: async () => "nine",
+    });
+    expect(section(r.out)[0]).toBe(
+      "  ✓ drafts — 2 candidates, no answer was given, so the first one was taken",
+    );
+  });
+});
+
+const here = (p: string) => `<${p}>`;
+
+describe("paperlint init — the workflow section, whole", () => {
+  it("the workflow: written unpinned, kept, declined, not asked", () => {
+    const ctx = { papersDir: "papers", why: "stdin is not a terminal" };
+    expect(reportWorkflow("written", ctx)).toEqual([
+      `  ✓ wrote ${WORKFLOW_PATH} — pin ${UNPINNED_REF} before pushing it`,
+    ]);
+    expect(reportWorkflow("written", { ...ctx, version: "1.2.3" })).toEqual([
+      `  ✓ wrote ${WORKFLOW_PATH}, pinned to v1.2.3`,
+    ]);
+    expect(reportWorkflow("kept", ctx)).toEqual([
+      `  ✓ ${WORKFLOW_PATH} is already there — kept, nothing overwritten`,
+    ]);
+    const step = [
+      "      to run the same checks in CI, add this step to a workflow:",
+      `        - uses: zernie/paperlint@${UNPINNED_REF}`,
+      "          with:",
+      "            paths: papers",
+    ];
+    expect(reportWorkflow("declined", ctx)).toEqual([
+      "  · declined — nothing written",
+      ...step,
+    ]);
+    expect(reportWorkflow("not-asked", ctx)).toEqual([
+      "  · stdin is not a terminal, so nothing was asked. Default taken: NO file written.",
+      ...step,
+    ]);
+  });
+});
+
+describe("paperlint init — the hooks section, whole", () => {
+  it("the hooks: every outcome", () => {
+    const how = "HOW";
+    const r = (o: Parameters<typeof reportHooks>[0]) =>
+      reportHooks(o, { how, here });
+    expect(r({ status: "skipped" })).toEqual([
+      "  · --no-hooks — nothing written",
+    ]);
+    expect(r({ status: "declined" })).toEqual([
+      "  · declined — nothing written. `npx paperlint init` again wires them later",
+    ]);
+    expect(r({ status: "failed", reason: "no vigiles" })).toEqual([
+      "  ✗ not wired — no vigiles",
+      "      the hooks need vigiles to run at all; reinstall this package, then `npx paperlint init`",
+    ]);
+    expect(r({ status: "unparsable", path: "s.json", reason: "bad" })).toEqual([
+      "  ✗ <s.json> does not parse — nothing written: bad",
+    ]);
+    expect(r({ status: "present", path: "s.json", names: ["a"] })).toEqual([
+      "  ✓ already wired in <s.json> — nothing changed",
+      "      HOW",
+      `      ${FRESH_CLONE_NOTE}`,
+    ]);
+    expect(
+      r({
+        status: "foreign",
+        path: "s.json",
+        names: ["a", "b"],
+        found: [{ name: "a", command: "node x.mjs" }],
+        missing: ["b"],
+      }),
+    ).toEqual([
+      "  ✓ already wired under another spelling in <s.json> — nothing written, so nothing runs twice:",
+      "      a: node x.mjs",
+      "  ⚠ and NOT wired in any form: b — add them in that same form",
+      "      to switch to the form init writes, delete those commands and run `npx paperlint init` again",
+    ]);
+  });
+});
+
+describe("paperlint init — the skills section, whole", () => {
+  it("the skills: nothing linked, and a mix with a skipped entry of unknown reason and a missing one", () => {
+    expect(reportSkillLinks({ ok: false, error: "no package" }, here)).toEqual([
+      "",
+      "skills (Claude Code finds project skills in .claude/skills/, not in node_modules)",
+      "  ⚠ nothing linked — no package",
+      "      install the package into this project (`npm i -D …`), then `npx paperlint init` again",
+    ]);
+    expect(
+      reportSkillLinks(
+        {
+          ok: true,
+          home: "h",
+          example: null,
+          links: [
+            { name: "a", status: "created" },
+            { name: "b", status: "foreign" },
+            { name: "c", status: "missing" },
+          ],
+        },
+        here,
+      ).slice(2),
+    ).toEqual([
+      "  ⚠ 3 shipped: 1 linked now, 0 already linked, 1 skipped, 1 NOT linked",
+      "      left untouched — the name is taken by something paperlint did not make:",
+      "        b — occupied",
+      "      those skills are NOT available in Claude Code until the entry is moved or removed",
+    ]);
+  });
+});
+
+describe("paperlint init — TeX Live and hooks failures, whole", () => {
+  it("TeX Live: a failed install says to run it again", async () => {
+    const t = await offerTexLive(
+      { installed: () => false, install: () => 1 },
+      { interactive: true, ask: async () => "yes" },
+    );
+    expect([t, reportTexLive(t, "")]).toEqual([
+      "failed",
+      [
+        "  ✗ the install failed — see above. Run it again:",
+        "      npx paperlint toolchain   # ~270 MB, ~3 min, once",
+      ],
+    ]);
+  });
+
+  it("hooks: a merge that throws is a failed step, not a crash", async () => {
+    const root = tree({});
+    const outcome = await offerHooks(root, {
+      hooks: true,
+      interactive: false,
+      merge: () => {
+        throw new Error("merge exploded");
+      },
+    });
+    expect(outcome).toEqual({ status: "failed", reason: "merge exploded" });
+  });
+});
+
+describe("paperlint init — a first paper", () => {
+  it("Enter at the name prompt skips it: nothing is created", async () => {
+    const made: string[] = [];
+    const r = await initRun(tree({}), {
+      interactive: true,
+      ask: async () => "",
+      createPaper: async (_root, name) => (made.push(name), 0),
+    });
+    expect(made).toEqual([]);
+    expect(r.out[r.out.indexOf("first paper") + 1]).toBe(
+      "  · none yet. `npx paperlint new <name>` or `--paper <name>` creates one",
+    );
+  });
+});
+
+describe("paperlint init — paths are shown relative to where it was run", () => {
+  it("a path that IS the working directory is shown whole, not as an empty string", async () => {
+    const root = tree({ "papers/a/paper.md": "# a\n" });
+    const home = join(root, ".claude", "skills");
+    mkdirSync(home, { recursive: true });
+    const r = await initRun(root, {
+      cwd: home,
+      link: () => ({
+        ok: true,
+        home,
+        example: "../../node_modules/paperlint/skills/x",
+        links: [{ name: "x", status: "present" }],
+      }),
+    });
+    expect(r.out).toContain(
+      `      ${join(home, "<name>")} → ../../node_modules/paperlint/skills/<name>`,
+    );
+  });
+});
+
+describe("askOnTerminal", () => {
+  it("reads one line from stdin, and the question goes to stdout", () => {
+    const probe = join(tree({}), "probe.mjs");
+    writeFileSync(
+      probe,
+      `const { askOnTerminal } = await import(${JSON.stringify(join(import.meta.dirname, "init.ts"))});\n` +
+        `console.log(JSON.stringify(await askOnTerminal("name? ")));\n`,
+    );
+    expect(runNode(probe, [], { input: "paper-one\n" })).toEqual({
+      status: 0,
+      stdout: 'name? "paper-one"\n',
+      stderr: "",
+    });
+  });
+});

package/src/init.ts

@@ -83,7 +83,7 @@ export type PapersHow =
  * declaration had already been written. So the install both succeeded and looked like a crash.
  * An unanswered question is an answer: take the default and say so.
  */
-async function askOrDefault(
+export async function askOrDefault(
   ask: (q: string) => Promise<string>,
   question: string,
 ): Promise<string | null> {
@@ -372,7 +372,7 @@ export function nextSteps(
 ): string {
   return [
     ``,
-    `next:  npx paperlint new <name>   # start a paper in ${papersDir}/ from the template`,
+    `next:  npx paperlint new <name> --venue <preset>   # start a paper in ${papersDir}/ from the template`,
     ...(toolchain
       ? [
           `       npx paperlint toolchain    # TeX Live for building (${TOOLCHAIN_COST})`,
@@ -857,8 +857,8 @@ export async function init(
     // 🔴 THE NAMES AND THE COUNT HERE, THE CONSEQUENCES — IN THE doctor REPORT BELOW, AND THIS IS
     // NOT ABOUT SAVING LINES. The first version printed here the same "✗ program — what goes silent
     // without it" table that doctor prints twenty lines later. Not only did the reader see it
-    // twice — the harness assert could not tell one from the other and left a mutation that cut the
-    // remedy OUT of init green. One fact is printed by one author.
+    // twice — the harness assert could not tell one from the other and would have let a defect
+    // cut the remedy OUT of init green. One fact is printed by one author.
     log(
       `  ✗ ${String(missing.length)} of ${String(PROGRAMS.length)} missing: ` +
         missing.map((p) => p.bin).join(", "),

package/src/latex-log.harness.mjs

@@ -5,9 +5,9 @@
  * memory: the two error spellings `-file-line-error` produces, the missing-package form, and a
  * marker that TeX broke at column 79.
  */
-import assert from "node:assert/strict";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { createChecker } from "../lib/check.mjs";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const {
@@ -20,11 +20,7 @@ const {
   MAX_PRINT_LINE,
 } = await import(join(HERE, "latex-log.ts"));
 
-let n = 0;
-const check = (label, cond) => {
-  assert.ok(cond, label);
-  n++;
-};
+const check = createChecker();
 
 // ── the 79-column wrap ──────────────────────────────────────────────────────────────────
 // A package warning long enough that "Rerun to get" crosses column 79. A real acmart log shows the
@@ -221,6 +217,35 @@ check(
     .citations.length === 1,
 );
 
+check(
+  "an \\@input aux that is not there (the default reader finds nothing) is skipped",
+  JSON.stringify(auxBib("\\@input{gone.aux}\n\\citation{x}\n").citations) ===
+    JSON.stringify(["x"]),
+);
+check(
+  "a log whose LAST line is exactly 79 bytes keeps it (nothing follows to join it to)",
+  JSON.stringify(unwrapLog(`a\n${"x".repeat(79)}`)) ===
+    JSON.stringify(["a", "x".repeat(79)]),
+);
+check(
+  "an error path must hold a dot or a slash; a bare word before the line number is not one",
+  isErrorLine("paper.tex:4: Undefined control sequence.") &&
+    isErrorLine("chapters/intro:9: x") &&
+    !isErrorLine("paper:4: x") &&
+    !isErrorLine("two words.tex:4: x"),
+);
+{
+  const flood = [
+    "./paper.tex:1: Undefined control sequence.",
+    ...Array.from({ length: 20 }, (_, i) => `noise ${String(i)}`),
+    "l.1 \\foo",
+  ];
+  check(
+    "an excerpt stops at MAX_EXCERPT lines even before the l.NNN line arrives",
+    errorExcerpt(flood).length === 12 && errorExcerpt(flood)[11] === "noise 10",
+  );
+}
+
 console.log(
-  `✓ ${String(n)} assertions passed — latex-log: markers across the 79-column wrap, both error spellings, aux`,
+  `✓ ${String(check.count)} assertions passed — latex-log: markers across the 79-column wrap, both error spellings, aux`,
 );

package/src/latex-log.ts

@@ -39,13 +39,6 @@ export type LogMarker =
   | "undefined-references"
   | "undefined-citations";
 
-/** Markers that mean "the output of this pass is not final yet". */
-export const RERUN_MARKERS: readonly LogMarker[] = [
-  "rerun-requested",
-  "labels-changed",
-  "rerunfilecheck",
-];
-
 /**
  * Rejoin the lines TeX broke at column 79. A line of exactly 79 bytes continues on the next one.
  *
@@ -100,9 +93,8 @@ export function logMarkers(lines: readonly string[]): LogMarker[] {
  * contain a dot or a slash, so an ordinary warning ending in a number and a colon cannot pass.
  */
 export function isErrorLine(line: string): boolean {
-  if (line.startsWith("!")) return true;
-  const m = /^([^\s:]+):(\d+): /.exec(line);
-  return m !== null && /[./]/.test(m[1] ?? "");
+  // `<path>:<line>: `, where the path (no space, no colon) holds at least one dot or slash.
+  return line.startsWith("!") || /^[^\s:]*[./][^\s:]*:\d+: /.test(line);
 }
 
 /** The `l.NNN …` line TeX prints to show where in the source it stopped. */
@@ -121,12 +113,13 @@ export function errorExcerpt(lines: readonly string[]): string[] {
   const start = lines.findIndex(isErrorLine);
   if (start < 0) return [];
   const out: string[] = [];
-  for (let i = start; i < lines.length && out.length < MAX_EXCERPT; i++) {
-    const line = lines[i] ?? "";
+  const rest = lines.slice(start);
+  for (const [i, line] of rest.entries()) {
+    if (out.length >= MAX_EXCERPT) break;
     if (line.trim() === "") continue;
     out.push(line);
     if (isContextLine(line)) {
-      const next = lines[i + 1];
+      const next = rest[i + 1];
       if (next !== undefined && next.trim() !== "") out.push(next);
       break;
     }

package/src/latex-loop.harness.mjs

@@ -8,20 +8,16 @@
  * The decision is pure, so none of this needs TeX. The real-pdflatex half lives in
  * `test/e2e/build.mjs`.
  */
-import assert from "node:assert/strict";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { createChecker } from "../lib/check.mjs";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const { nextStep, summarize, changedFiles, MAX_PASSES } = await import(
   join(HERE, "latex-loop.ts")
 );
 
-let n = 0;
-const check = (label, cond) => {
-  assert.ok(cond, label);
-  n++;
-};
+const check = createChecker();
 
 // ── builders ────────────────────────────────────────────────────────────────────────────
 const H = (aux, toc = null, out = null, bbl = null) => ({ aux, toc, out, bbl });
@@ -444,6 +440,11 @@ check(
   changedFiles(H(null), H("a1")).includes("aux"),
 );
 
+check(
+  "a history of only a bibtex run that left every file as it was: nothing unsettled",
+  JSON.stringify(summarize([bibtex({ after: H("a1") })]).unsettled) === "[]",
+);
+
 console.log(
-  `✓ ${String(n)} assertions passed — latex-loop: nextStep over State, summarize over histories, and the two composed, including the ${MAX_PASSES}-pass cap`,
+  `✓ ${String(check.count)} assertions passed — latex-loop: nextStep over State, summarize over histories, and the two composed, including the ${MAX_PASSES}-pass cap`,
 );

package/src/link-skills.harness.mjs

@@ -13,9 +13,7 @@
  * consumer.mjs — the same constant the linker and the install e2e read.
  *
  * Run:    node src/link-skills.harness.mjs
- * Killed by: src/link-skills.mutations.mjs
  */
-import assert from "node:assert/strict";
 import {
   existsSync,
   mkdirSync,
@@ -30,6 +28,7 @@ import {
 import { tmpdir } from "node:os";
 import { dirname, isAbsolute, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { createChecker } from "../lib/check.mjs";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const { linkSkills, locatePackage, shippedSkills } = await import(
@@ -39,11 +38,7 @@ const { SHIPPED_SKILLS_DIR: SHIPS, PACKAGE_NAME: PKG } = await import(
   join(HERE, "..", "skills", "paper-pipeline", "scripts", "consumer.mjs")
 );
 
-let n = 0;
-const check = (label, cond) => {
-  n++;
-  assert.ok(cond, label);
-};
+const check = createChecker();
 
 const SKILLS = ["alpha", "beta", "gamma"];
 const work = realpathSync(
@@ -234,5 +229,5 @@ try {
 }
 
 console.log(
-  `✓ ${n} assertions passed — link-skills: the skills are where Claude Code looks`,
+  `✓ ${check.count} assertions passed — link-skills: the skills are where Claude Code looks`,
 );