paperlint 3.1.3 → 3.2.0

package/src/{latex-loop.harness.mjs → latex-loop.harness.ts}

@@ -6,30 +6,43 @@
  * A defect in `nextStep` fails in table 1, one in `summarize` in table 2, before table 3 runs.
  *
  * The decision is pure, so none of this needs TeX. The real-pdflatex half lives in
- * `test/e2e/build.mjs`.
+ * `test/e2e/build.ts`.
  */
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-import { createChecker } from "../lib/check.mjs";
+import { createChecker } from "../lib/check.ts";
+import type {
+  BibInput,
+  Hashes,
+  Observation,
+  State,
+  Step,
+} from "./latex-loop.ts";
 
-const HERE = dirname(fileURLToPath(import.meta.url));
-const { nextStep, summarize, changedFiles, MAX_PASSES } = await import(
-  join(HERE, "latex-loop.ts")
-);
+const { nextStep, summarize, changedFiles, MAX_PASSES } =
+  await import("./latex-loop.ts");
 
 const check = createChecker();
 
 // ── builders ────────────────────────────────────────────────────────────────────────────
-const H = (aux, toc = null, out = null, bbl = null) => ({ aux, toc, out, bbl });
-const NO_BIB = { kind: "none" };
-const bib = (citations, bibHash = "b1") => ({
+type LatexPass = Extract<Observation, { step: "latex" }>;
+type BibtexPass = Extract<Observation, { step: "bibtex" }>;
+const H = (
+  aux: string | null,
+  toc: string | null = null,
+  out: string | null = null,
+  bbl: string | null = null,
+): Hashes => ({ aux, toc, out, bbl });
+const NO_BIB: BibInput = { kind: "none" };
+const bib = (
+  citations: readonly string[],
+  bibHash: string | null = "b1",
+): BibInput => ({
   kind: "needed",
   citations,
   databases: ["refs"],
   style: "plain",
   bibHash,
 });
-const latex = (o = {}) => ({
+const latex = (o: Partial<LatexPass> = {}): LatexPass => ({
   step: "latex",
   final: false,
   exitCode: 0,
@@ -40,7 +53,7 @@ const latex = (o = {}) => ({
   errorLines: [],
   ...o,
 });
-const bibtex = (o = {}) => ({
+const bibtex = (o: Partial<BibtexPass> = {}): BibtexPass => ({
   step: "bibtex",
   exitCode: 0,
   before: H("a1"),
@@ -49,11 +62,11 @@ const bibtex = (o = {}) => ({
   errorLines: [],
   ...o,
 });
-const kind = (s) =>
+const kind = (s: Step) =>
   s.kind === "latex" ? `latex${s.final ? "-final" : ""}` : s.kind;
 
 // ── 1. nextStep over a State ─────────────────────────────────────────────────────────────
-const S = (o = {}) => ({
+const S = (o: Partial<State> = {}): State => ({
   failed: null,
   bibOutdated: false,
   unsettled: [],
@@ -62,12 +75,12 @@ const S = (o = {}) => ({
   warnings: [],
   ...o,
 });
-const exitFail = {
+const exitFail: NonNullable<State["failed"]> = {
   step: "bibtex",
   cause: { kind: "exit", code: 2 },
   lines: ["I couldn't open database file nope.bib"],
 };
-const STATES = [
+const STATES: [string, State, string][] = [
   // Guards: the only moment paper-guards can speak — its error comes on the final pass, so testing
   // 'final' before 'exit code' would ship the undefined reference green.
   [
@@ -96,7 +109,7 @@ const STATES = [
   // Guards: the stop on a document that never settles — without it the loop runs forever; with a
   // silent cap it ships a PDF with stale cross-references.
   [
-    `Q3 cap: ${MAX_PASSES} passes and still unsettled — fail`,
+    `Q3 cap: ${String(MAX_PASSES)} passes and still unsettled — fail`,
     S({ unsettled: ["paper.aux"], latexPasses: MAX_PASSES }),
     "fail",
   ],
@@ -115,20 +128,29 @@ for (const [label, state, expected] of STATES) {
 const q1 = nextStep(S({ failed: exitFail }));
 check(
   "Q1 passes the failure through: the step, the cause and the lines verbatim",
-  q1.step === "bibtex" && q1.cause.code === 2 && q1.lines === exitFail.lines,
+  q1.kind === "fail" &&
+    q1.step === "bibtex" &&
+    q1.cause.kind === "exit" &&
+    q1.cause.code === 2 &&
+    q1.lines === exitFail.lines,
 );
 const q3cap = nextStep(
   S({ unsettled: ["paper.aux", "labels-changed"], latexPasses: MAX_PASSES }),
 );
 check(
   "the cap's failure is no-convergence and NAMES what stayed unsettled",
-  q3cap.cause.kind === "no-convergence" &&
-    q3cap.lines[0].includes("paper.aux, labels-changed"),
+  q3cap.kind === "fail" &&
+    q3cap.cause.kind === "no-convergence" &&
+    (q3cap.lines[0] ?? "").includes("paper.aux, labels-changed"),
 );
 check(
   "done carries the state's warnings",
-  nextStep(S({ finalDone: true, warnings: ["undefined-citations"] }))
-    .warnings[0] === "undefined-citations",
+  (() => {
+    const done = nextStep(
+      S({ finalDone: true, warnings: ["undefined-citations"] }),
+    );
+    return done.kind === "done" && done.warnings[0] === "undefined-citations";
+  })(),
 );
 
 // ── 2. summarize over histories ─────────────────────────────────────────────────────────
@@ -152,7 +174,10 @@ check(
   (() => {
     const f = sum([latex({ exitCode: 1, errorLines: ["l.4 \\foo"] })]).failed;
     return (
-      f?.step === "latex" && f.cause.code === 1 && f.lines[0] === "l.4 \\foo"
+      f?.step === "latex" &&
+      f.cause.kind === "exit" &&
+      f.cause.code === 1 &&
+      f.lines[0] === "l.4 \\foo"
     );
   })(),
 );
@@ -162,22 +187,22 @@ check(
 );
 check(
   "summarize: bibOutdated when the aux names a bibliography bibtex has not run on",
-  sum([latex({ bib: bib(["k"]) })]).bibOutdated === true,
+  sum([latex({ bib: bib(["k"]) })]).bibOutdated,
 );
 check(
   "summarize: bibOutdated is false once bibtex ran on exactly that input",
-  sum([latex({ bib: bib(["k"]) }), bibtex()]).bibOutdated === false,
+  !sum([latex({ bib: bib(["k"]) }), bibtex()]).bibOutdated,
 );
 // Guards: the .bib hash as an input — a corrected author or year in refs.bib would keep the old
 // .bbl, and the PDF would print the entry as it was before the fix.
 check(
   "summarize: the .bib content changed since bibtex ran — bibOutdated",
   sum([latex({ bib: bib(["k"]) }), bibtex(), latex({ bib: bib(["k"], "b2") })])
-    .bibOutdated === true,
+    .bibOutdated,
 );
 check(
   "summarize: no bibliography at all — never bibOutdated",
-  sum([latex()]).bibOutdated === false,
+  !sum([latex()]).bibOutdated,
 );
 check(
   "summarize: unsettled names every tracked file the last pass changed",
@@ -232,10 +257,10 @@ check(
 );
 
 // ── 3. composed: nextStep(summarize(history)) ───────────────────────────────────────────
-const step = (history) => nextStep(summarize(history));
+const step = (history: readonly Observation[]) => nextStep(summarize(history));
 
 // ── the histories the loop sees ───────────────────────────────────────────────────────────────────────────
-const TABLE = [
+const TABLE: [string, Observation[], string][] = [
   ["nothing ran yet — the first step is a plain pass", [], "latex"],
   [
     "a pass that created the aux — rerun",
@@ -364,7 +389,8 @@ const latexFail = step([
 ]);
 check(
   "a latex fail names the step, the exit code and the log excerpt verbatim",
-  latexFail.step === "latex" &&
+  latexFail.kind === "fail" &&
+    latexFail.step === "latex" &&
     latexFail.cause.kind === "exit" &&
     latexFail.cause.code === 1 &&
     latexFail.lines[1] === "l.4 \\foo",
@@ -380,14 +406,16 @@ check(
   "a bibtex fail names BIBTEX, not latex",
   bibFail.kind === "fail" &&
     bibFail.step === "bibtex" &&
+    bibFail.cause.kind === "exit" &&
     bibFail.cause.code === 2,
 );
 
 // ── the cap ─────────────────────────────────────────────────────────────────────────────
-const moving = (i) => latex({ before: H(`a${i}`), after: H(`a${i + 1}`) });
+const moving = (i: number) =>
+  latex({ before: H(`a${String(i)}`), after: H(`a${String(i + 1)}`) });
 const underCap = Array.from({ length: MAX_PASSES - 1 }, (_, i) => moving(i));
 check(
-  `the cap is ${MAX_PASSES} and it is not hit early: after ${MAX_PASSES - 1} moving passes, one more`,
+  `the cap is ${String(MAX_PASSES)} and it is not hit early: after ${String(MAX_PASSES - 1)} moving passes, one more`,
   MAX_PASSES === 5 && kind(step(underCap)) === "latex",
 );
 const atCap = Array.from({ length: MAX_PASSES }, (_, i) => moving(i));
@@ -398,7 +426,7 @@ check(
 );
 check(
   "the non-convergence failure NAMES the file that kept changing",
-  capped.kind === "fail" && capped.lines[0].includes("paper.aux"),
+  capped.kind === "fail" && (capped.lines[0] ?? "").includes("paper.aux"),
 );
 const cappedMarker = step(
   Array.from({ length: MAX_PASSES }, () =>
@@ -408,7 +436,7 @@ const cappedMarker = step(
 check(
   "a log that keeps asking for a rerun hits the same cap, and names the marker",
   cappedMarker.kind === "fail" &&
-    cappedMarker.lines[0].includes("labels-changed"),
+    (cappedMarker.lines[0] ?? "").includes("labels-changed"),
 );
 const convergedAtCap = [...atCap.slice(0, -1), latex()];
 check(
@@ -446,5 +474,5 @@ check(
 );
 
 console.log(
-  `✓ ${String(check.count)} 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 ${String(MAX_PASSES)}-pass cap`,
 );

package/src/latex-loop.ts

@@ -3,7 +3,7 @@
  *
  * PURE. No disk, no process, no clock. The shell in `build.ts` runs a step, records what it saw
  * as an `Observation`, appends it to the history and asks `nextStep(summarize(history))` again.
- * Both halves are table tests (`latex-loop.harness.mjs`), not scenarios that need TeX.
+ * Both halves are table tests (`latex-loop.harness.ts`), not scenarios that need TeX.
  *
  * ── THE LOOP: `summarize` reduces the history to a `State`, and `nextStep` asks four questions ──
  *   1. did the last program fail?                          → fail, with its error lines
@@ -118,7 +118,7 @@ export type Step =
     };
 
 /** Non-final pdflatex passes allowed before the build is declared non-converging. */
-export const MAX_PASSES = 5;
+export const MAX_PASSES: number = 5;
 
 /** The history, reduced to the four questions `nextStep` asks. */
 export type State = {
@@ -152,7 +152,7 @@ const noConvergence = (unsettled: readonly string[]): Step => ({
   step: "latex",
   cause: { kind: "no-convergence", unsettled },
   lines: [
-    `the build does not converge: after ${MAX_PASSES} pdflatex passes, the last one still changed or asked to rerun: ${unsettled.join(", ")}.`,
+    `the build does not converge: after ${String(MAX_PASSES)} pdflatex passes, the last one still changed or asked to rerun: ${unsettled.join(", ")}.`,
     `A document whose aux keeps changing on every pass never settles; stopping here instead of`,
     `shipping a PDF with stale cross-references.`,
   ],

package/src/{link-skills.harness.mjs → link-skills.harness.ts}

@@ -12,7 +12,7 @@
  * The fixture package keeps its skills where the real one does, under `SHIPPED_SKILLS_DIR` from
  * consumer.mjs — the same constant the linker and the install e2e read.
  *
- * Run:    node src/link-skills.harness.mjs
+ * Run:    node src/link-skills.harness.ts
  */
 import {
   existsSync,
@@ -26,17 +26,14 @@ import {
   writeFileSync,
 } from "node:fs";
 import { tmpdir } from "node:os";
-import { dirname, isAbsolute, join } from "node:path";
-import { fileURLToPath } from "node:url";
-import { createChecker } from "../lib/check.mjs";
+import { isAbsolute, join } from "node:path";
+import { createChecker } from "../lib/check.ts";
+import type { LinkReport } from "./link-skills.ts";
 
-const HERE = dirname(fileURLToPath(import.meta.url));
-const { linkSkills, locatePackage, shippedSkills } = await import(
-  join(HERE, "link-skills.ts")
-);
-const { SHIPPED_SKILLS_DIR: SHIPS, PACKAGE_NAME: PKG } = await import(
-  join(HERE, "..", "skills", "paper-pipeline", "scripts", "consumer.mjs")
-);
+const { linkSkills, locatePackage, shippedSkills } =
+  await import("./link-skills.ts");
+const { SHIPPED_SKILLS_DIR: SHIPS, PACKAGE_NAME: PKG } =
+  await import("../skills/paper-pipeline/scripts/consumer.mjs");
 
 const check = createChecker();
 
@@ -46,7 +43,7 @@ const work = realpathSync(
 );
 
 /** A package as a manager would unpack it: manifest, skills, one non-skill. */
-function writePackage(dir) {
+function writePackage(dir: string): void {
   mkdirSync(dir, { recursive: true });
   writeFileSync(
     join(dir, "package.json"),
@@ -63,7 +60,7 @@ function writePackage(dir) {
 }
 
 /** A consumer project with the package installed the npm way or the pnpm way. */
-function consumer(name, manager = "npm") {
+function consumer(name: string, manager = "npm"): string {
   const dir = join(work, name);
   mkdirSync(join(dir, "node_modules"), { recursive: true });
   writeFileSync(
@@ -89,8 +86,11 @@ function consumer(name, manager = "npm") {
   return dir;
 }
 
-const home = (dir) => join(dir, ".claude", "skills");
-const status = (report, name) => report.links.find((l) => l.name === name);
+const home = (dir: string) => join(dir, ".claude", "skills");
+/** The report's links; a refusal has none. */
+const linksOf = (report: LinkReport) => (report.ok ? report.links : []);
+const status = (report: LinkReport, name: string) =>
+  linksOf(report).find((l) => l.name === name);
 
 try {
   // ── I. A FRESH npm CONSUMER: EVERY DECLARED SKILL IS LINKED, AND ONLY SKILLS ───────────
@@ -99,11 +99,11 @@ try {
     const r = linkSkills(dir);
     check(
       "🔴 it links every skill the package ships",
-      r.ok === true && SKILLS.every((s) => status(r, s)?.status === "created"),
+      r.ok && SKILLS.every((s) => status(r, s)?.status === "created"),
     );
     check(
       "and nothing that is not a skill — a directory without SKILL.md is not one",
-      r.links.length === SKILLS.length &&
+      linksOf(r).length === SKILLS.length &&
         !existsSync(join(home(dir), "shared")),
     );
     check(
@@ -195,7 +195,7 @@ try {
     const r = linkSkills(dir);
     check(
       "a project that does not have the package gets an error, not links into somebody's cache",
-      r.ok === false && /does not resolve from/.test(r.error),
+      !r.ok && /does not resolve from/.test(r.error),
     );
     check("and nothing is created", !existsSync(join(dir, ".claude")));
   }
@@ -229,5 +229,5 @@ try {
 }
 
 console.log(
-  `✓ ${check.count} assertions passed — link-skills: the skills are where Claude Code looks`,
+  `✓ ${String(check.count)} assertions passed — link-skills: the skills are where Claude Code looks`,
 );

package/src/link-skills.test.ts

@@ -14,7 +14,7 @@ import {
 } from "node:fs";
 import { join } from "node:path";
 import { test } from "vitest";
-import { useTempDir, writeTree } from "../test/support.mjs";
+import { useTempDir, writeTree } from "../test/support.ts";
 import { linkSkills, locatePackage, type LinkFs } from "./link-skills.ts";
 
 const root = useTempDir("paperlint-link-skills-");
@@ -62,7 +62,7 @@ test("a package without a skills directory, or one holding a dangling link, is n
   symlinkSync(join(root, "gone"), join(dangling, "skills", "b"));
   const r = linkSkills(join(root, "p2"), { locate: at(dangling) });
   assert.equal(r.ok, false);
-  assert.match(!r.ok ? r.error : "", /^1 skill link\(s\) in .* lead nowhere:/);
+  assert.match(r.error, /^1 skill link\(s\) in .* lead nowhere:/);
 });
 
 test("a skills home that cannot be made is named", () => {
@@ -71,7 +71,7 @@ test("a skills home that cannot be made is named", () => {
   });
   const r = linkSkills(project, { locate: at(pkg("home", ["a"])) });
   assert.equal(r.ok, false);
-  assert.match(!r.ok ? r.error : "", /^cannot create .*\.claude\/skills: /);
+  assert.match(r.error, /^cannot create .*\.claude\/skills: /);
 });
 
 test("entries that are someone else's: a plain file, one that cannot be resolved, a link that cannot be made", () => {

package/src/link-skills.ts

@@ -44,6 +44,7 @@ import {
   PACKAGE_NAME,
   SHIPPED_SKILLS_DIR,
 } from "../skills/paper-pipeline/scripts/consumer.mjs";
+import { messageOf, codeOf } from "./domain/text.ts";
 
 export { PACKAGE_NAME };
 /** Where Claude Code looks for project skills, relative to the project root. */
@@ -74,7 +75,7 @@ export function locatePackage(
     manifest = resolveManifest(project);
   } catch (e) {
     return {
-      error: `${(e as NodeJS.ErrnoException).code ?? "error"}: ${(e as Error).message.split("\n")[0]}`,
+      error: `${codeOf(e) ?? "error"}: ${String(messageOf(e).split("\n")[0])}`,
     };
   }
   const dir = realpathSync(dirname(manifest));
@@ -108,7 +109,7 @@ export function shippedSkills(
   try {
     return { skillsDir, names: installedSkills(skillsDir) };
   } catch (e) {
-    return { error: (e as Error).message };
+    return { error: messageOf(e) };
   }
 }
 
@@ -207,7 +208,7 @@ function linkOne(
     return {
       name,
       status: "foreign",
-      reason: `could not create the link: ${(e as Error).message}`,
+      reason: `could not create the link: ${messageOf(e)}`,
     };
   }
 }
@@ -218,7 +219,7 @@ function makeHome(home: string): string | null {
     mkdirSync(home, { recursive: true });
     return null;
   } catch (e) {
-    return `cannot create ${home}: ${(e as Error).message}`;
+    return `cannot create ${home}: ${messageOf(e)}`;
   }
 }
 

package/src/lint-fix.test.ts

@@ -13,6 +13,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
 import { run } from "./cli.ts";
+import { lintReport } from "../test/lint-report.ts";
 
 const dirs: string[] = [];
 afterEach(() => {
@@ -50,8 +51,8 @@ async function lint(root: string, args: string[] = []) {
   return { code, out: out.join("\n"), err: err.join("\n") };
 }
 const ruleIds = (stdout: string): string[] =>
-  (JSON.parse(stdout) as { messages: { ruleId: string }[] }[]).flatMap((r) =>
-    r.messages.map((m) => m.ruleId),
+  lintReport(stdout).flatMap((r) =>
+    r.messages.map((m) => m.ruleId ?? "(fatal)"),
   );
 
 describe("paperlint lint --fix", () => {
@@ -85,10 +86,7 @@ describe("sibling cards: `read:` is required, from the package's own schema", ()
         "papers/a/siblings/jones2024.md": "---\nread: abstract\n---\n# Jones\n",
       },
     );
-    const results = JSON.parse((await lint(root)).out) as {
-      filePath: string;
-      messages: { ruleId: string; severity: number }[];
-    }[];
+    const results = lintReport((await lint(root)).out);
     const of = (name: string) =>
       results.find((r) => r.filePath.endsWith(name))?.messages ?? null;
     expect(of("smith2025.md")?.map((m) => [m.ruleId, m.severity])).toEqual([

package/src/linted-set.test.ts

@@ -19,6 +19,7 @@ import { tmpdir } from "node:os";
 import { join, relative } from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
 import { run } from "./cli.ts";
+import { lintReport } from "../test/lint-report.ts";
 
 const dirs: string[] = [];
 afterEach(() => {
@@ -91,9 +92,8 @@ async function lintedSet(root: string, args: string[]): Promise<string[]> {
     log: (s: string) => out.push(s),
     err: () => {},
   });
-  type Result = { filePath: string; messages: { ruleId: string | null }[] };
   return (
-    (JSON.parse(out.join("\n")) as Result[])
+    lintReport(out.join("\n"))
       // A structure finding reports a MISSING file in the same shape; it was not linted.
       .filter(
         (r) => !r.messages.some((m) => m.ruleId === "structure/required-file"),

package/src/new-paper.harness.mjs

@@ -30,8 +30,8 @@ import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { load } from "js-yaml";
-import { frontmatterBlock } from "../lib/markdown.mjs";
-import { createChecker } from "../lib/check.mjs";
+import { frontmatterBlock } from "../lib/markdown.ts";
+import { createChecker } from "../lib/check.ts";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const ROOT = dirname(HERE);

package/src/new-paper.test.ts

@@ -20,6 +20,8 @@ import { parsePaperSettings } from "./paper-settings.ts";
 import { chooseVenue, run } from "./cli.ts";
 import { shippedPresets } from "./presets.ts";
 import { packageVenuesDir } from "../skills/paper-pipeline/scripts/consumer.mjs";
+import { lintReport } from "../test/lint-report.ts";
+import { z } from "zod";
 
 const dirs: string[] = [];
 afterEach(() => {
@@ -31,10 +33,9 @@ const tmp = () => {
   return d;
 };
 const settingsOf = (dir: string) =>
-  JSON.parse(readFileSync(join(dir, "paperlint.json"), "utf8")) as Record<
-    string,
-    unknown
-  >;
+  z
+    .record(z.string(), z.unknown())
+    .parse(JSON.parse(readFileSync(join(dir, "paperlint.json"), "utf8")));
 
 describe("paperlint new — paperlint.json", () => {
   it("is always written, from the package template: no venue chosen yet, and valid", () => {
@@ -107,11 +108,7 @@ describe("paperlint lint — a paper with no venue preset chosen", () => {
       log: (s: string) => out.push(s),
       err: () => {},
     });
-    const messages = (
-      JSON.parse(out.join("\n")) as {
-        messages: { ruleId: string; severity: number; message: string }[];
-      }[]
-    ).flatMap((r) => r.messages);
+    const messages = lintReport(out.join("\n")).flatMap((r) => r.messages);
     return { code, messages };
   }
 
@@ -266,7 +263,8 @@ describe("chooseVenue — on a terminal", () => {
         paperDir: "/p/papers/demo",
         cwd: "/p",
         interactive: true,
-        ask: async (q: string) => (asked.push(q), answers.shift() ?? ""),
+        ask: (q: string) =>
+          Promise.resolve((asked.push(q), answers.shift() ?? "")),
       },
     };
   };

package/src/new-paper.ts

@@ -25,7 +25,7 @@ import {
 /* eslint-enable boundaries/dependencies */
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { CONFIG_FILE } from "../lib/paper-config.mjs";
+import { CONFIG_FILE } from "#lib/paper-config";
 
 export type PaperFormat = "tex" | "md";
 export const FORMATS: readonly PaperFormat[] = ["tex", "md"];
@@ -50,7 +50,7 @@ export const SOURCE_FILE: Readonly<Record<PaperFormat, string>> = {
 };
 
 export const isFormat = (v: unknown): v is PaperFormat =>
-  FORMATS.includes(v as PaperFormat);
+  FORMATS.some((f) => f === v);
 
 /**
  * Why a name is refused, or null. `[a-z0-9._-]+` is the charset; a LEADING dot is refused on top

package/src/paper-files.test.ts

@@ -27,6 +27,7 @@ import {
   ruleOwners,
   scopeToOwned,
 } from "./paper-files.ts";
+import { lintReport } from "../test/lint-report.ts";
 
 const dirs: string[] = [];
 afterEach(() => {
@@ -67,7 +68,7 @@ async function lint(
 }
 
 const linted = (stdout: string): string[] =>
-  (JSON.parse(stdout) as { filePath: string }[]).map((r) => r.filePath);
+  lintReport(stdout).map((r) => r.filePath);
 
 /** Vendored code under a paper: a syntax error, an unknown rule in a directive, plain CommonJS. */
 const VENDORED = {
@@ -208,10 +209,7 @@ describe("🔴 a generated block never reaches a file paperlint does not lint (#
     async (_, settings) => {
       const root = project({ ...SIBLINGS, ...settings });
       const r = await lint(root);
-      const results = JSON.parse(r.out) as {
-        filePath: string;
-        messages: { ruleId: string | null; message: string }[];
-      }[];
+      const results = lintReport(r.out);
       // Guards: the class — no file reaches ESLint's default JavaScript parser.
       expect(
         results.flatMap((x) => x.messages).filter((m) => m.ruleId === null),

package/src/paper-settings-commands.test.ts

@@ -13,6 +13,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
 import { run, toolchainTex } from "./cli.ts";
+import { lintReport } from "../test/lint-report.ts";
 
 const dirs: string[] = [];
 afterEach(() => {
@@ -55,9 +56,9 @@ async function lint(
 }
 
 const rulesIn = (stdout: string, paper: string): string[] =>
-  (JSON.parse(stdout) as { filePath: string; messages: { ruleId: string }[] }[])
+  lintReport(stdout)
     .filter((r) => r.filePath.endsWith(join(paper, "paper.tex")))
-    .flatMap((r) => r.messages.map((m) => m.ruleId));
+    .flatMap((r) => r.messages.map((m) => m.ruleId ?? "(fatal)"));
 
 describe("🔴 an optional rule that reaches no paper — judged against the PROJECT, not the run (#103)", () => {
   const THIRD = {
@@ -151,7 +152,7 @@ describe("papersDir — optional, `papers` by default", () => {
     const r = await lint(project());
     expect(r.code).toBe(0);
     expect(
-      (JSON.parse(r.out) as { filePath: string }[]).map((f) =>
+      lintReport(r.out).map((f) =>
         f.filePath.slice(f.filePath.indexOf("papers/")),
       ),
     ).toEqual(
@@ -178,7 +179,7 @@ describe("papersDir — optional, `papers` by default", () => {
       "docs/drafts/c/PIPELINE-STATUS.md": "---\nstages: []\n---\n",
     });
     const r = await lint(root);
-    const linted = (JSON.parse(r.out) as { filePath: string }[]).map((f) =>
+    const linted = lintReport(r.out).map((f) =>
       f.filePath.slice(root.length + 1),
     );
     expect(linted).toContain("docs/drafts/c/paper.tex");

package/src/paper-settings.test.ts

@@ -5,7 +5,7 @@
 import { describe, expect, it } from "vitest";
 import { memoryFiles } from "./adapters/memory/index.ts";
 import type { AbsolutePath } from "./domain/paths.ts";
-import { findProjectRoot } from "../lib/paper-config.mjs";
+import { findProjectRoot } from "../lib/paper-config.ts";
 import {
   paperRules,
   parsePaperSettings,
@@ -128,12 +128,12 @@ describe("readPaperSettings — a root paperlint.json that cannot be used", () =
       readPaperSettings(withFiles({ [`${ROOT}/paperlint.json`]: root }), PAPER);
     const notJson = broken("{ nope");
     expect(!notJson.ok && notJson.error.kind).toBe("broken");
+    const why: unknown = expect.stringMatching(
+      /^the root paperlint\.json: .*kind/,
+    );
     expect(broken('{"kind":3}')).toEqual({
       ok: false,
-      error: {
-        kind: "broken",
-        why: expect.stringMatching(/^the root paperlint\.json: .*kind/),
-      },
+      error: { kind: "broken", why },
     });
   });
 });