paperlint 2.0.0

package/eslint-rules/papers.mutations.mjs

@@ -0,0 +1,186 @@
+/**
+ * Mutation battery for `eslint-rules/papers.mjs`.
+ * Run: `node eslint-rules/papers.mutations.mjs` (not `vigiles test` — this is not a harness).
+ *
+ * 🔴 EVERY MUTATION CARRIES A "THE PATCH LANDED" ASSERTION: the file is re-read FROM DISK, the
+ * mutant must be in it, and after the rollback the contents must return byte for byte. In this
+ * project a green mutation has repeatedly meant not "the defence holds" but "the patch never
+ * landed" / "the test is looking somewhere else".
+ *
+ * WHAT A GREEN HARNESS UNDER A MUTATION MEANS: a finding about the TEST, not a conclusion
+ * about the defence. Rank the causes in this order — the test greps PROSE ABOUT a value
+ * instead of the value · the test looks in the wrong place · the test is the wrong test · the
+ * patch did not land · the set is too narrow · the run was already red BEFORE the mutation.
+ * The last one is closed by the baseline run below.
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+
+const RULES = "eslint-rules/papers.mjs";
+const HARNESS = "eslint-rules/papers.harness.mjs";
+
+// Coverage mode — see `scripts/run-mutations.mjs` guard 2 and the block in
+// `lib/mutation-driver.mjs`. Says what this battery can kill, without touching a file.
+if (process.env.MUTATIONS_REPORT_COVERAGE) {
+  console.log(`MUTATION-COVERS\t${HARNESS}`);
+  process.exit(0);
+}
+
+const PRISTINE = readFileSync(RULES, "utf8");
+
+const M = [
+  [
+    "existsSync/the central refusal",
+    "stop checking that the root is on disk — a wrong root stops being an error and becomes a " +
+      "run that lints zero files and exits 0, which reads exactly like a clean pass",
+    "  if (!existsSync(resolve(baseDir, root)))",
+    "  if (false)",
+  ],
+  [
+    "baseDir/ignored in favour of cwd",
+    "resolve against `process.cwd()` instead of the given base — passes every run started from " +
+      "the repository root and fails in a worktree or from an editor started elsewhere",
+    "  if (!existsSync(resolve(baseDir, root)))",
+    "  if (!existsSync(resolve(process.cwd(), root)))",
+  ],
+  [
+    "default/absence",
+    "drop the default — a consumer that declares nothing gets `undefined` instead of `papers`",
+    "  const root = declared === undefined ? DEFAULT_PAPERS_ROOT : declared;",
+    "  const root = declared;",
+  ],
+  [
+    "declared === undefined/null read as absence",
+    'go back to `??` — an explicit `"papersDir": null` is read as «nothing was declared» and ' +
+      "silently falls back to the default, i.e. a typed keystroke treated as an absence",
+    "  const root = declared === undefined ? DEFAULT_PAPERS_ROOT : declared;",
+    "  const root = declared ?? DEFAULT_PAPERS_ROOT;",
+  ],
+  [
+    "type guard/empty string",
+    "accept any string, including the empty one — every glob becomes `/*/paper.tex`, rooted at " +
+      "the filesystem, matching nothing, silently",
+    '  if (typeof root !== "string" || root.length === 0)',
+    '  if (typeof root !== "string")',
+  ],
+  [
+    "return shape/absolute path",
+    "return the RESOLVED root — ESLint interprets `files:` globs relative to the config, so an " +
+      "absolute path there is a different pattern, and the breakage shows up as silence",
+    "  return root;\n}",
+    "  return resolve(baseDir, root);\n}",
+  ],
+  [
+    "message/which value was declared",
+    "drop the declared value from the error — the reader is told something is missing but not " +
+      "which of several candidate paths the tool was looking at",
+    'the papers root "${root}" does not exist under ${baseDir}.',
+    "the papers root does not exist.",
+  ],
+  [
+    "message/default vs declared",
+    "collapse the two failures into one message — «you declared the wrong thing» and «you " +
+      "declared nothing and the default does not fit» have different fixes",
+    "        (declared === undefined",
+    "        (false",
+  ],
+  [
+    "paperFiles/one glob set stops interpolating the root",
+    "hard-code the `tex` set — the block keeps matching whatever layout the author had in mind",
+    "    tex: [`${root}/*/paper.tex`],",
+    "    tex: [`docs/papers/*/paper.tex`],",
+  ],
+  [
+    "paperFiles/a set disappears",
+    "drop `status` — a consumer's block named it, so that block now lints nothing at all",
+    "    status: [`${root}/*/PIPELINE-STATUS.md`],",
+    "",
+  ],
+];
+
+const runHarness = () => {
+  try {
+    execFileSync("npx", ["vigiles", "test", HARNESS], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    return { failed: false, out: "" };
+  } catch (e) {
+    return { failed: true, out: (e.stdout ?? "") + (e.stderr ?? "") };
+  }
+};
+
+// 🔴 A BASELINE RUN BEFORE ANY MUTATION. A red harness makes EVERY mutation look "killed", and
+// the battery would print a confident green verdict about a defence that is not there.
+{
+  const base = runHarness();
+  if (base.failed) {
+    console.log(
+      "❌ THE HARNESS IS RED BEFORE ANY MUTATION — the battery cannot tell a killed mutation " +
+        "from that:\n" +
+        base.out.slice(-1500),
+    );
+    process.exit(1);
+  }
+}
+
+let ok = 0;
+let bad = 0;
+const rows = [];
+for (const [label, what, from, to] of M) {
+  const hits = PRISTINE.split(from).length - 1;
+  if (hits !== 1) {
+    console.log(
+      `❌ ${label}: TARGET ${hits === 0 ? "NOT FOUND" : `NOT UNIQUE (${hits})`} — ${from.slice(0, 70)}`,
+    );
+    bad++;
+    continue;
+  }
+  writeFileSync(RULES, PRISTINE.replace(from, to));
+  const on = readFileSync(RULES, "utf8");
+  if (!on.includes(to) || on.includes(from)) {
+    console.log(
+      `❌ ${label}: THE MUTATION DID NOT LAND (checked by re-reading the file)`,
+    );
+    bad++;
+    writeFileSync(RULES, PRISTINE);
+    continue;
+  }
+  const { failed, out } = runHarness();
+  writeFileSync(RULES, PRISTINE);
+  if (readFileSync(RULES, "utf8") !== PRISTINE) {
+    console.log(`❌ ${label}: THE ROLLBACK FAILED`);
+    bad++;
+    continue;
+  }
+  // The verdict carries the HARNESS LINE and the assertion text: "killed" without saying by
+  // what is half an answer. The battery must show that each mutation died on ITS OWN assertion.
+  const at = (out.match(/papers\.harness\.mjs:(\d+)/) ?? [])[1];
+  const msg =
+    (out.match(/AssertionError[^:]*: ([^\n]+)/) ?? [])[1] ??
+    // Not every mutation dies on an assertion: removing the `try/catch` crashes the linter
+    // itself, and then "what it died on" is a thrown error. Without this branch the column
+    // would come out EMPTY — "killed by something unknown", which is the half-answer this
+    // battery forbids.
+    (out.match(/((?:Error|ENOENT)[^\n]*)/) ?? [])[1] ??
+    (out.match(
+      /([^\n]*(?:must|the wrong|drifted|was lost|did not fire)[^\n]*)/,
+    ) ?? [])[1] ??
+    "";
+  const where = (at ? `harness:${at} · ` : "") + msg;
+  if (failed) {
+    ok++;
+    rows.push([label, what, where.trim().slice(0, 130)]);
+  } else {
+    console.log(
+      `🔴 ${label}: THE HARNESS IS GREEN UNDER THE MUTATION — a finding about the TEST, not a conclusion about the defence`,
+    );
+    bad++;
+  }
+}
+console.log("\n| property | mutation | what the harness died on |");
+console.log("|---|---|---|");
+for (const [a, b, c] of rows)
+  console.log(`| \`${a}\` | ${b} | ${c.replace(/\|/g, "\\|")} |`);
+console.log(`\n${ok} mutation(s) killed, ${bad} problem(s)`);
+process.exit(bad ? 1 : 0);

package/eslint-rules/pdf-last-page-balance.harness.mjs

@@ -0,0 +1,206 @@
+/**
+ * Colocated test for `eslint-rules/pdf-last-page-balance.mjs` (`pdf/last-page-balance`).
+ * Run: `npx vigiles test eslint-rules/pdf-last-page-balance.harness.mjs`
+ *
+ * The rule is driven the way a consumer drives it: through rpp's own `buildConfig`, with the
+ * rule turned on by a `rules` block in the settings — not through a config invented here. Each
+ * paper is a temporary directory holding `paper.tex`, `paper.pdf` and the facts `paperlint build`
+ * would write beside them.
+ *
+ * Both halves: it FIRES on an unbalanced page and on every input it cannot judge (no facts, a
+ * foreign schema, facts about another PDF), and it is QUIET on a balanced page, a stub, a review
+ * build, a file that is not paper.tex — and when nobody turned it on.
+ */
+import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
+import {
+  mkdirSync,
+  mkdtempSync,
+  realpathSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { ESLint } from "eslint";
+import { texLanguage } from "./latex-language.mjs";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const { parseFacts, judgeColumns, DEFAULT_TOLERANCE_PT } = await import(
+  join(HERE, "pdf-last-page-balance.mjs")
+);
+const { buildConfig } = await import(join(HERE, "..", "src", "cli.ts"));
+
+let n = 0;
+const check = (label, cond, detail = "") => {
+  assert.ok(cond, detail ? `${label} — ${detail}` : label);
+  n++;
+};
+
+const TEX =
+  "% a paper\n\\documentclass[sigconf]{acmart}\n\\begin{document}x\\end{document}\n";
+const PDF = "%PDF-1.5 pretend";
+const sha = (s) => createHash("sha256").update(s).digest("hex");
+const facts = (lastPage, over = {}) => ({
+  schema: 2,
+  pdf: "paper.pdf",
+  pdf_sha256: sha(PDF),
+  last_page: lastPage,
+  ...over,
+});
+const MEASURED = (l, r) => ({ kind: "measured", columns_pt: [l, r] });
+
+const root = realpathSync(mkdtempSync(join(tmpdir(), "rpp-balance-rule-")));
+/** A paper directory with paper.tex, paper.pdf and, unless `null`, `_build/paper.facts.json`. */
+const paper = (name, f, { pdf = PDF } = {}) => {
+  const dir = join(root, "papers", name);
+  mkdirSync(join(dir, "_build"), { recursive: true });
+  writeFileSync(join(dir, "paper.tex"), TEX);
+  writeFileSync(join(dir, "NOTES.md"), "# notes\n");
+  if (pdf !== null) writeFileSync(join(dir, "paper.pdf"), pdf);
+  if (f !== null)
+    writeFileSync(
+      join(dir, "_build", "paper.facts.json"),
+      typeof f === "string" ? f : JSON.stringify(f),
+    );
+  return dir;
+};
+
+/** Lint files with rpp's config, the rule turned on for `papers/**` (unless `rules` says otherwise). */
+async function lint(
+  files,
+  rules = [
+    {
+      basePath: root,
+      files: ["papers/**"],
+      rules: { "pdf/last-page-balance": "error" },
+    },
+  ],
+) {
+  const eslint = new ESLint({
+    cwd: root,
+    overrideConfigFile: true,
+    overrideConfig: buildConfig({ rules }, texLanguage),
+  });
+  const results = await eslint.lintFiles(files);
+  return results.flatMap((r) =>
+    r.messages.map((m) => ({ file: r.filePath, ...m })),
+  );
+}
+const only = (msgs) => msgs.filter((m) => m.ruleId === "pdf/last-page-balance");
+
+try {
+  // ── pure: parsing the facts and judging the columns ──────────────────────────────────
+  check(
+    "parseFacts: a schema-1 file is refused by name",
+    parseFacts(JSON.stringify({ schema: 1 })).messageId === "schema",
+  );
+  check(
+    "parseFacts: not JSON is `factsBroken`, not a crash",
+    parseFacts("{").messageId === "factsBroken",
+  );
+  check(
+    "parseFacts: a measured page without two finite heights is `factsBroken`",
+    parseFacts(JSON.stringify(facts({ kind: "measured", columns_pt: [1] })))
+      .messageId === "factsBroken",
+  );
+  check(
+    "judgeColumns: at the tolerance it is balanced; one point more is not",
+    judgeColumns({ kind: "measured", left: 220, right: 100 }, 120) === null &&
+      judgeColumns({ kind: "measured", left: 221, right: 100 }, 120)
+        ?.messageId === "unbalanced",
+  );
+  check("the default tolerance is 120 pt", DEFAULT_TOLERANCE_PT === 120);
+
+  // ── fires ───────────────────────────────────────────────────────────────────────────
+  const unb = paper("unbalanced", facts(MEASURED(621.5, 264.8)));
+  const u = only(await lint([join(unb, "paper.tex")]));
+  check(
+    "🔴 an unbalanced last page is a finding, with both heights and the difference",
+    u.length === 1 &&
+      u[0].severity === 2 &&
+      /621\.5 and 264\.8 pt, 356\.7 pt apart \(tolerance 120 pt\)/.test(
+        u[0].message,
+      ),
+    JSON.stringify(u),
+  );
+  check(
+    "…at the \\documentclass line, where the class option that fixes it goes",
+    u[0]?.line === 2,
+    String(u[0]?.line),
+  );
+  check(
+    "…and the message says how to fix it by hand: pbalance, flushend, \\balance in the first column",
+    /pbalance/.test(u[0]?.message) &&
+      /flushend/.test(u[0]?.message) &&
+      /FIRST column of the last page/.test(u[0]?.message),
+  );
+  const loose = only(
+    await lint(
+      [join(unb, "paper.tex")],
+      [
+        {
+          basePath: root,
+          files: ["papers/**"],
+          rules: { "pdf/last-page-balance": ["warn", { tolerancePt: 400 }] },
+        },
+      ],
+    ),
+  );
+  check(
+    "the tolerance is the consumer's: 400 pt lets 356.7 pass",
+    loose.length === 0,
+    JSON.stringify(loose),
+  );
+
+  const noFacts = paper("no-facts", null);
+  check(
+    "🔴 on, but no facts file: a finding telling the author to build — not silence",
+    only(await lint([join(noFacts, "paper.tex")]))[0]?.messageId === "noFacts",
+  );
+  const stale = paper("stale", facts(MEASURED(400, 400)), {
+    pdf: "%PDF-1.5 rebuilt since",
+  });
+  check(
+    "🔴 facts about a different PDF than the one on disk are refused as stale",
+    only(await lint([join(stale, "paper.tex")]))[0]?.messageId === "stale",
+  );
+  const gone = paper("gone", facts(MEASURED(400, 400)), { pdf: null });
+  check(
+    "facts whose PDF is gone (a failed build removes it) are refused",
+    only(await lint([join(gone, "paper.tex")]))[0]?.messageId === "pdfMissing",
+  );
+  const old = paper("old-schema", facts(MEASURED(400, 400), { schema: 1 }));
+  check(
+    "schema-1 facts are refused, not read with new meanings",
+    only(await lint([join(old, "paper.tex")]))[0]?.messageId === "schema",
+  );
+
+  // ── quiet ───────────────────────────────────────────────────────────────────────────
+  const bal = paper("balanced", facts(MEASURED(464.2, 461.5)));
+  const stub = paper("stub", facts({ kind: "stub", words: 12 }));
+  const review = paper("review", facts({ kind: "review", line_numbers: 60 }));
+  const quiet = only(
+    await lint([bal, stub, review].map((d) => join(d, "paper.tex"))),
+  );
+  check(
+    "quiet on a balanced page, a stub last page and a review build",
+    quiet.length === 0,
+    JSON.stringify(quiet),
+  );
+  check(
+    "quiet on a file that is not paper.tex, even inside the glob",
+    only(await lint([join(unb, "NOTES.md")])).length === 0,
+  );
+  check(
+    "🔴 OFF BY DEFAULT: with no `rules` block, an unbalanced paper gets no finding",
+    only(await lint([join(unb, "paper.tex")], [])).length === 0,
+  );
+} finally {
+  rmSync(root, { recursive: true, force: true });
+}
+
+console.log(
+  `✓ ${String(n)} assertions passed — pdf/last-page-balance: fires on unbalanced and unjudgeable, quiet on balanced/stub/review/off`,
+);

package/eslint-rules/pdf-last-page-balance.mjs

@@ -0,0 +1,208 @@
+/**
+ * pdf/last-page-balance — the two columns of a paper's last page end at about the same height.
+ *
+ * OPTIONAL, OFF BY DEFAULT. Balance is a requirement of SOME venues, not of papers: some ACM
+ * production vendors return a camera-ready for it (Conference Publishing Consulting, which produces
+ * ICSE/ASE/SIGSOFT/SIGPLAN proceedings; Sheridan for ACM SIG conferences such as CCS), IEEEtran
+ * advises it for camera-ready work, and ACL, USENIX, AAAI and ICML say nothing. No standard format
+ * checker (HotCRP's banal, aclpubcheck, IEEE PDF eXpress) tests it. So a consumer turns it on for
+ * the papers whose venue asks, in package.json:
+ *
+ *   "paperlint": { "rules": [ { "files": ["papers/my-paper/**"],
+ *     "rules": { "pdf/last-page-balance": ["error", { "tolerancePt": 120 }] } } ] }
+ *
+ * (That is a line comment's worth of JSON in a block comment only because it has no asterisk
+ * followed by a slash; see rule 8 of CLAUDE.md before editing it.)
+ *
+ * ── WHAT IT READS: THE FACTS THE BUILD WROTE, NOT THE PDF ───────────────────────
+ * `paperlint build` measures the PDF with pdf.js and writes `<paper>/_build/paper.facts.json`. This rule
+ * runs on `paper.tex` — the one file every LaTeX paper has, and the one ESLint already parses — and
+ * judges that paper's facts file beside it. It never opens the PDF to measure it: it hashes it, to
+ * refuse facts about a different build than the one on disk.
+ *
+ * ── IT DOES NOT FIX, AND SAYS HOW TO ────────────────────────────────────────────
+ * paperlint used to search for a `\balance` position itself and fail the build when none worked. Every
+ * mechanism is documented as unreliable by its own authors (acmart: `balance` "may lead to
+ * problems", `pbalance` is "experimental"; pbalance: "this package is a hack"), and for ACM TAPS
+ * venues ACM recompiles the source, so an edit to a generated `.bbl` may never reach the proceedings.
+ * The message names the manual fixes the vendor itself lists, in its order.
+ *
+ * Silent, by design, where there is nothing to judge: a stub last page (a few lines) and a review
+ * build (numbered lines in the margins make both columns measure full height). Loud where the input
+ * is missing: no facts file, a foreign schema, facts about a PDF that is not on disk or changed
+ * since — a rule that is on and reads nothing must not look like a rule that passed.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { basename, dirname, isAbsolute, join } from "node:path";
+
+/** The difference, in points, that two columns may end apart. See the harness for why 120. */
+export const DEFAULT_TOLERANCE_PT = 120;
+/** The schema of `paper.facts.json` this rule reads (`src/facts-file.ts`, FACTS_SCHEMA). */
+export const FACTS_SCHEMA = 2;
+export const FACTS_REL = join("_build", "paper.facts.json");
+
+const isHeight = (x) => typeof x === "number" && Number.isFinite(x);
+
+/** The `last_page` field, parsed. */
+function lastPageOf(v) {
+  if (v?.kind === "stub" || v?.kind === "review") return { kind: v.kind };
+  const c = v?.columns_pt;
+  if (
+    v?.kind === "measured" &&
+    Array.isArray(c) &&
+    c.length === 2 &&
+    c.every(isHeight)
+  )
+    return { kind: "measured", left: c[0], right: c[1] };
+  return null;
+}
+
+/**
+ * The facts file's text → what this rule needs, or the reason it cannot be judged. Pure.
+ *
+ * @returns {{ ok: true, pdf: string, sha: string, last: object } | { ok: false, messageId: string, data: object }}
+ */
+export function parseFacts(text) {
+  let d;
+  try {
+    d = JSON.parse(text);
+  } catch (e) {
+    return { ok: false, messageId: "factsBroken", data: { why: e.message } };
+  }
+  if (d?.schema !== FACTS_SCHEMA)
+    return {
+      ok: false,
+      messageId: "schema",
+      data: { got: JSON.stringify(d?.schema ?? null) },
+    };
+  const last = lastPageOf(d.last_page);
+  if (
+    typeof d.pdf !== "string" ||
+    !/^[0-9a-f]{64}$/.test(d.pdf_sha256 ?? "") ||
+    !last
+  )
+    return {
+      ok: false,
+      messageId: "factsBroken",
+      data: {
+        why: "no `pdf`, `pdf_sha256` or `last_page` in the expected shape",
+      },
+    };
+  return { ok: true, pdf: d.pdf, sha: d.pdf_sha256, last };
+}
+
+/** Whether the facts describe the PDF on disk: null when they do, else the reason. */
+function staleness(paperDir, facts) {
+  const pdf = isAbsolute(facts.pdf) ? facts.pdf : join(paperDir, facts.pdf);
+  let got;
+  try {
+    got = createHash("sha256").update(readFileSync(pdf)).digest("hex");
+  } catch {
+    return { messageId: "pdfMissing", data: { pdf: facts.pdf } };
+  }
+  return got === facts.sha
+    ? null
+    : { messageId: "stale", data: { pdf: facts.pdf } };
+}
+
+/** The finding for a measured page, or null when it is balanced. Pure. */
+export function judgeColumns(last, tolerancePt) {
+  if (last.kind !== "measured") return null;
+  const diff = Math.abs(last.left - last.right);
+  if (diff <= tolerancePt) return null;
+  return {
+    messageId: "unbalanced",
+    data: {
+      left: last.left.toFixed(1),
+      right: last.right.toFixed(1),
+      diff: diff.toFixed(1),
+      tol: String(tolerancePt),
+    },
+  };
+}
+
+/** Where a finding goes: the `\documentclass` line, where the class options that fix it live. */
+function reportLine(file) {
+  try {
+    const lines = readFileSync(file, "utf8").split("\n");
+    const i = lines.findIndex((l) => /^\s*\\documentclass\b/.test(l));
+    return i >= 0 ? i + 1 : 1;
+  } catch {
+    return 1;
+  }
+}
+
+/** Everything the rule decides for one paper, as a finding or null. */
+function verdict(paperDir, tolerancePt) {
+  const factsFile = join(paperDir, FACTS_REL);
+  if (!existsSync(factsFile))
+    return { messageId: "noFacts", data: { file: FACTS_REL } };
+  const facts = parseFacts(readFileSync(factsFile, "utf8"));
+  if (!facts.ok) return { messageId: facts.messageId, data: facts.data };
+  return staleness(paperDir, facts) ?? judgeColumns(facts.last, tolerancePt);
+}
+
+const rule = {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "the last page's two columns end at about the same height (optional; for venues that require it)",
+    },
+    schema: [
+      {
+        type: "object",
+        properties: {
+          tolerancePt: { type: "number", exclusiveMinimum: 0 },
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      unbalanced:
+        "the last page is unbalanced: its columns end at {{left}} and {{right}} pt, {{diff}} pt " +
+        "apart (tolerance {{tol}} pt). Some ACM production vendors send such a camera-ready back. " +
+        "Conference Publishing Consulting's advice, in its order: \"For the ACMART style, use " +
+        "option 'balance' or, if this does not work, option 'pbalance'\" — acmart already has " +
+        "`balance` on by default, and it calls \\balance from the second column, where it does " +
+        "nothing when the last page is all bibliography, so try `pbalance`; then " +
+        "`\\usepackage{flushend}`; then `\\balance` (balance.sty) placed in what would be the " +
+        "FIRST column of the last page — in the bibliography, before the \\bibitem that starts " +
+        "that column. Rebuild (`paperlint build`) and lint again.",
+      noFacts:
+        "pdf/last-page-balance is on for this paper, but {{file}} does not exist beside it. The rule " +
+        "judges the facts `paperlint build` writes after a successful compile — build the paper first.",
+      factsBroken:
+        "{{why}} in _build/paper.facts.json — rebuild the paper (`paperlint build`) to rewrite it",
+      schema:
+        "_build/paper.facts.json has schema {{got}}; this rule reads schema 2 — rebuild the paper " +
+        "(`paperlint build`) to rewrite it",
+      pdfMissing:
+        "_build/paper.facts.json describes {{pdf}}, which is not on disk (a failed build removes " +
+        "it) — rebuild the paper",
+      stale:
+        "_build/paper.facts.json describes a DIFFERENT {{pdf}} than the one on disk (its SHA-256 " +
+        "differs), so judging it would judge an earlier build — rebuild the paper",
+    },
+  },
+  create(context) {
+    // Judged once per paper, on its paper.tex: the paper directory is the file's directory.
+    if (basename(context.filename) !== "paper.tex") return {};
+    const tolerancePt = context.options[0]?.tolerancePt ?? DEFAULT_TOLERANCE_PT;
+    return {
+      root() {
+        const v = verdict(dirname(context.filename), tolerancePt);
+        if (!v) return;
+        const line = reportLine(context.filename);
+        context.report({
+          loc: { start: { line, column: 1 }, end: { line, column: 2 } },
+          messageId: v.messageId,
+          data: v.data,
+        });
+      },
+    };
+  },
+};
+
+export default { rules: { "last-page-balance": rule } };