paperlint 2.0.1 → 3.0.0

package/eslint-rules/paper-typography.test.mjs

@@ -0,0 +1,297 @@
+/**
+ * paper/section-word · paper/leading-zero · paper/figure-ref-style · bib/reachable-entry — each
+ * FIRES on a bad input, stays SILENT on a good one, reports every occurrence at its own place,
+ * and (the first three) fixes to an exact output. Plus the escape hatch: a disable directive in a
+ * `%` comment, including inside the `filecontents` bibliography, silences exactly one finding,
+ * and a directive that silences nothing is itself reported.
+ *
+ * The leading-zero cases are the ones paperlint#44 measured: a regex over the raw source found 22
+ * decimals on a real corpus and none was a defect, so the SILENT list is as load-bearing as the
+ * CAUGHT one.
+ */
+import { describe, expect, it } from "vitest";
+import { ESLint } from "eslint";
+import markdown from "@eslint/markdown";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { texLanguage } from "./latex-language.mjs";
+import typography from "./paper-typography.mjs";
+import bib from "./bib-reachable-entry.mjs";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const FIX = join(HERE, "..", "fixtures", "paper-typography");
+
+const RULES = {
+  "paper/section-word": "warn",
+  "paper/leading-zero": "warn",
+  "paper/figure-ref-style": "warn",
+  "bib/reachable-entry": "warn",
+};
+
+const eslint = (fix = false) =>
+  new ESLint({
+    cwd: FIX,
+    overrideConfigFile: true,
+    fix,
+    overrideConfig: [
+      {
+        files: ["**/*.tex"],
+        plugins: {
+          tex: { languages: { latex: texLanguage } },
+          paper: typography,
+          bib,
+        },
+        language: "tex/latex",
+        linterOptions: { reportUnusedDisableDirectives: "error" },
+        rules: RULES,
+      },
+      {
+        files: ["**/*.md"],
+        plugins: { markdown, paper: typography },
+        language: "markdown/gfm",
+        languageOptions: { frontmatter: "yaml" },
+        rules: {
+          "paper/section-word": "warn",
+          "paper/leading-zero": "warn",
+        },
+      },
+    ],
+  });
+
+/** Lint `text` as `file`; no crash allowed, only findings. */
+async function lint(text, file = "paper.tex", fix = false) {
+  const [res] = await eslint(fix).lintText(text, {
+    filePath: join(FIX, "inline", file),
+  });
+  expect(res.messages.filter((m) => m.fatal)).toEqual([]);
+  return res;
+}
+const ids = (res, id) => res.messages.filter((m) => !id || m.ruleId === id);
+const fixed = async (text, file) =>
+  (await lint(text, file, true)).output ?? text;
+const doc = (body) =>
+  `\\documentclass{acmart}\n\\begin{document}\n${body}\n\\end{document}\n`;
+
+describe("the fixtures: messy fires on each rule, clean is silent", () => {
+  it("messy-paper — every occurrence, at its own line", async () => {
+    const res = await lint(
+      readFileSync(join(FIX, "messy-paper", "paper.tex"), "utf8"),
+    );
+    const count = (id) => ids(res, id).length;
+    expect(count("paper/section-word")).toBe(3);
+    expect(count("paper/leading-zero")).toBe(2);
+    expect(count("paper/figure-ref-style")).toBe(1);
+    expect(count("bib/reachable-entry")).toBe(2);
+    expect(ids(res, "bib/reachable-entry").map((m) => m.line)).toEqual([3, 8]);
+  });
+
+  it("clean-paper — nothing", async () => {
+    const res = await lint(
+      readFileSync(join(FIX, "clean-paper", "paper.tex"), "utf8"),
+    );
+    expect(res.messages).toEqual([]);
+  });
+});
+
+describe("paper/section-word", () => {
+  it("🔴 the MACRO form counts, not only the glyph — and each is fixed exactly", async () => {
+    const src = doc("See §~\\ref{a}, \\S\\ref{b}, \\S~\\ref{c}, \\S 4 and §5.");
+    expect(ids(await lint(src), "paper/section-word")).toHaveLength(5);
+    expect(await fixed(src)).toBe(
+      doc(
+        "See Section~\\ref{a}, Section~\\ref{b}, Section~\\ref{c}, Section 4 and Section 5.",
+      ),
+    );
+  });
+
+  it("a glyph before prose is reported but not rewritten", async () => {
+    const src = doc("As §§ above.");
+    expect(ids(await lint(src), "paper/section-word")).toHaveLength(2);
+    expect(await fixed(src)).toBe(src);
+  });
+
+  it("silent on Section written out, on comments, on the bibliography", async () => {
+    const src =
+      "\\documentclass{acmart}\n\\begin{filecontents*}{refs.bib}\n@misc{k, note = {see §5}, url = {https://x.org}}\n\\end{filecontents*}\n" +
+      "\\begin{document}\nSection~\\ref{a}.\n% §5 in an old draft\n\\end{document}\n";
+    expect(ids(await lint(src), "paper/section-word")).toEqual([]);
+  });
+
+  it("markdown: `§5` → `Section 5`, code untouched", async () => {
+    const src = "See §5 and `§3` here.\n";
+    expect(ids(await lint(src, "paper.md"), "paper/section-word")).toHaveLength(
+      1,
+    );
+    expect(await fixed(src, "paper.md")).toBe("See Section 5 and `§3` here.\n");
+  });
+});
+
+describe("paper/leading-zero", () => {
+  const caught = [
+    ["a p-value in inline math", "We call it significant at $p < .05$."],
+    ["a p-value after other math", "(bugfix $-31\\%$, $p=.002$)"],
+    [
+      "a table cell",
+      "\\begin{tabular}{ll}\ntask & p \\\\\nbugfix & .037 \\\\\n\\end{tabular}",
+    ],
+    ["plain prose", "We use a threshold of .05 throughout."],
+  ];
+  it.each(caught)("CAUGHT, exactly one: %s", async (_, body) => {
+    expect(ids(await lint(doc(body)), "paper/leading-zero")).toHaveLength(1);
+  });
+
+  const silent = [
+    ["a figure width option", "\\includegraphics[width=.48\\columnwidth]{f}"],
+    [
+      "a tabular column spec",
+      "\\begin{tabular}{p{.25\\linewidth}l}\na & b \\\\\n\\end{tabular}",
+    ],
+    ["a comment", "Text.\n% p<.01 in the old draft\nMore text."],
+    ["a listing", "\\begin{lstlisting}\nx = .25\n\\end{lstlisting}"],
+    ["inline listing", "Call \\lstinline{.25} here."],
+    ["a length argument", "A\\hspace{.3em}B\\hspace{.35em}C"],
+    ["a macro definition body", "\\def\\x{.85}"],
+    [
+      "tikz coordinates",
+      "\\begin{tikzpicture}\\draw (.35,.65);\\end{tikzpicture}",
+    ],
+    ["an arXiv id", "See arXiv 2310.05736 for details."],
+    [
+      "an unsigned environment's width",
+      "\\begin{subfigure}[b]{.48\\textwidth}\nPanel.\n\\end{subfigure}",
+    ],
+    [
+      "an unsigned table's column spec",
+      "\\begin{longtable}{p{.25\\linewidth}l}\na & b \\\\\n\\end{longtable}",
+    ],
+    [
+      "an unknown macro's options",
+      "\\adjustbox{width=.48\\linewidth}{x} \\foo[scale=.75]{y}",
+    ],
+  ];
+  it.each(silent)("SILENT: %s", async (_, body) => {
+    expect(ids(await lint(doc(body)), "paper/leading-zero")).toEqual([]);
+  });
+
+  it("the preamble and the inline bibliography are not the reader's text", async () => {
+    const src =
+      "\\documentclass{acmart}\n\\renewcommand{\\arraystretch}{.85}\n" +
+      "\\begin{filecontents*}{refs.bib}\n@misc{k, note = {p = .05}, url = {https://x.org}}\n" +
+      "\\end{filecontents*}\n\\begin{document}\nNothing here.\n\\end{document}\n";
+    expect(ids(await lint(src), "paper/leading-zero")).toEqual([]);
+  });
+
+  it("the fix inserts the zero at the dot — in math, in a table, in prose", async () => {
+    const src = doc(
+      "At $p < .05$ and $d=.21$; cell & .037 \\\\ and .5 or .25.",
+    );
+    expect(await fixed(src)).toBe(
+      doc("At $p < 0.05$ and $d=0.21$; cell & 0.037 \\\\ and .5 or 0.25."),
+    );
+  });
+
+  it("markdown: prose and a table cell are fixed, code is not", async () => {
+    const src =
+      "Significant at p<.05.\n\n| task | p |\n| --- | --- |\n| bugfix | .002 |\n\nRun `.25`.\n";
+    expect(ids(await lint(src, "paper.md"), "paper/leading-zero")).toHaveLength(
+      2,
+    );
+    expect(await fixed(src, "paper.md")).toBe(
+      "Significant at p<0.05.\n\n| task | p |\n| --- | --- |\n| bugfix | 0.002 |\n\nRun `.25`.\n",
+    );
+  });
+});
+
+describe("paper/figure-ref-style", () => {
+  it("the minority form is reported and rewritten to the majority", async () => {
+    const src = doc("Figure~\\ref{a}, Figure~\\ref{b} and Fig.~\\ref{c}.");
+    const found = ids(await lint(src), "paper/figure-ref-style");
+    expect(found).toHaveLength(1);
+    expect(found[0].column).toBe(src.split("\n")[2].indexOf("Fig.") + 1);
+    expect(await fixed(src)).toBe(
+      doc("Figure~\\ref{a}, Figure~\\ref{b} and Figure~\\ref{c}."),
+    );
+  });
+
+  it("the majority can be the short form", async () => {
+    const src = doc("Fig.~\\ref{a}, Fig.~\\ref{b} and Figure~\\ref{c}.");
+    expect(await fixed(src)).toBe(
+      doc("Fig.~\\ref{a}, Fig.~\\ref{b} and Fig.~\\ref{c}."),
+    );
+  });
+
+  it("silent when one form is used throughout", async () => {
+    expect(
+      ids(
+        await lint(doc("Fig.~\\ref{a} and Fig.~\\ref{b}.")),
+        "paper/figure-ref-style",
+      ),
+    ).toEqual([]);
+  });
+});
+
+describe("bib/reachable-entry", () => {
+  const bibDoc = (entries) =>
+    `\\documentclass{acmart}\n\\begin{filecontents*}{refs.bib}\n${entries}\n\\end{filecontents*}\n\\begin{document}\nx\n\\end{document}\n`;
+
+  it("a doi, a url or an arXiv id each make an entry reachable", async () => {
+    const res = await lint(
+      bibDoc(
+        "@article{a, doi = {10.1/x}}\n@misc{b, url = {https://x.org}}\n@misc{c, note = {arXiv:2310.05736}}\n@string{v = {x}}",
+      ),
+    );
+    expect(ids(res, "bib/reachable-entry")).toEqual([]);
+  });
+
+  it("reports on the entry itself, naming its key", async () => {
+    const res = await lint(
+      bibDoc("@misc{ok, url = {https://x.org}}\n@article{lost, title = {x}}"),
+    );
+    const [m] = ids(res, "bib/reachable-entry");
+    expect(m.line).toBe(4);
+    expect(m.column).toBe(1);
+    expect(m.message).toMatch(/`lost`/);
+  });
+});
+
+describe("the escape hatch — a disable directive in a `%` comment", () => {
+  it("🔴 inside the filecontents bibliography, it silences exactly the next entry", async () => {
+    const res = await lint(
+      `\\documentclass{acmart}\n\\begin{filecontents*}{refs.bib}\n` +
+        "% eslint-disable-next-line bib/reachable-entry -- an invited talk, no recording exists\n" +
+        "@misc{talk, title = {x}}\n@misc{lost, title = {y}}\n" +
+        "\\end{filecontents*}\n\\begin{document}\nx\n\\end{document}\n",
+    );
+    const found = ids(res, "bib/reachable-entry");
+    expect(found).toHaveLength(1);
+    expect(found[0].message).toMatch(/`lost`/);
+  });
+
+  it("in the body: next-line, same-line, and a disable/enable region", async () => {
+    const src = doc(
+      [
+        "% eslint-disable-next-line paper/leading-zero -- quoted from the reviewer",
+        "They wrote .05 here.",
+        "And .06 here. % eslint-disable-line paper/leading-zero -- also quoted",
+        "% eslint-disable paper/leading-zero -- a quoted table",
+        "Region .07 and .08.",
+        "% eslint-enable paper/leading-zero",
+        "But .09 counts.",
+      ].join("\n"),
+    );
+    const found = ids(await lint(src), "paper/leading-zero");
+    expect(found.map((m) => m.line)).toEqual([9]);
+  });
+
+  it("a directive that silences nothing is itself reported", async () => {
+    const res = await lint(
+      doc(
+        "% eslint-disable-next-line paper/leading-zero -- stale\nNo decimals here.",
+      ),
+    );
+    expect(
+      res.messages.filter((m) => /Unused eslint-disable/.test(m.message)),
+    ).toHaveLength(1);
+  });
+});

package/eslint-rules/papers.harness.mjs

@@ -47,9 +47,8 @@ const repoWith = (...dirs) => {
   for (const d of dirs) mkdirSync(join(base, d), { recursive: true });
   return base;
 };
-const declaring = (papers) => ({
-  paperlint: { [PAPERS_DIR_FIELD]: papers },
-});
+/** The root `paperlint.json`, parsed, declaring `papers`. */
+const declaring = (papers) => ({ [PAPERS_DIR_FIELD]: papers });
 
 // ═════════════════════════════════════════════════════════════════════════════
 // I. THE DEFAULT AND THE DECLARATION
@@ -57,10 +56,9 @@ const declaring = (papers) => ({
 {
   const repo = repoWith(DEFAULT_PAPERS_ROOT);
   for (const [label, pkg] of [
-    ["no package.json content at all", undefined],
-    ["an empty package.json", {}],
-    ["a package.json with an unrelated key", { name: "x", dependencies: {} }],
-    ["our key present but empty", { paperlint: {} }],
+    ["no paperlint.json at all", undefined],
+    ["an empty paperlint.json", {}],
+    ["a paperlint.json with only other keys", { kind: "short", rules: {} }],
   ])
     assert.equal(
       papersRoot(pkg, repo),
@@ -97,8 +95,8 @@ for (const declared of ["papers", "docs/papers", "writing/drafts", "a/b/c/d"]) {
       e.message.includes('"writing/drafts"') &&
       // names WHERE it looked,
       e.message.includes(repo) &&
-      // tells the reader it came from package.json rather than from a default,
-      /declared in package\.json/.test(e.message) &&
+      // tells the reader it came from paperlint.json rather than from a default,
+      /declared in paperlint\.json/.test(e.message) &&
       // and says WHY this is fatal instead of ignorable.
       /indistinguishable/.test(e.message),
     "a declared-but-missing root must throw, and the message must name the value, the place " +
@@ -113,9 +111,7 @@ for (const declared of ["papers", "docs/papers", "writing/drafts", "a/b/c/d"]) {
     (e) =>
       /does not exist/.test(e.message) &&
       /Nothing was declared/.test(e.message) &&
-      e.message.includes(
-        `"paperlint": { "${PAPERS_DIR_FIELD}": "path/to/papers" }`,
-      ),
+      e.message.includes(`{ "${PAPERS_DIR_FIELD}": "path/to/papers" }`),
     "a missing root reached by DEFAULTING must say so and show the declaration to add",
   );
 }

package/eslint-rules/papers.mjs

@@ -10,25 +10,21 @@
  * that forbids imports), the PROSE of a skill (read by a model, not resolved by code), and
  * LaTeX (`TEXINPUTS`, kpathsea).
  *
- * ── THE DECISION (2026-09-11) ───────────────────────────────────────────────
- * ONE declaration, in the consumer's `package.json`, with a default:
+ * ── THE DECISION ────────────────────────────────────────────────────────────
+ * ONE declaration, in the project's root `paperlint.json`, with a default:
  *
- *     "paperlint": { "papersDir": "docs/papers" }
+ *     { "papersDir": "docs/papers" }
  *
- * (The field was called `papers` until 2026-09-24; the old name is now refused.)
- * No key → `papers`. Every carrier then reads that one value with its OWN standard mechanism:
+ * No file, or no key → `papers`. Every carrier then reads that one value with its OWN standard
+ * mechanism:
  *
- *   ESLint  →  `import pkg from "./package.json" with { type: "json" }` + this module
- *   hook    →  `needs: [provide("pkg", "cat package.json")]`, JSON.parse inside `decide`
+ *   ESLint  →  `settingsOf(root)` (lib/paper-config.mjs) + this module
+ *   hook    →  `needs: [provide("config", …)]` cats the file, JSON.parse inside `decide`
  *   prose   →  the skill names a COMMAND, not a path:
- *              `node -p "require('./package.json')['paperlint']?.papersDir ?? 'papers'"`
+ *              `node -p "(() => { try { return require('./paperlint.json').papersDir } catch {} })() ?? 'papers'"`
  *   LaTeX   →  `TEXINPUTS` built FROM THE SCRIPT (`$(dirname "$0")/../tex//:`), so the
  *              consumer declares nothing at all for this carrier
  *
- * `package.json` is the right home rather than a new dotfile for one measured reason: it is
- * the file Node already opens to resolve this package, so it cannot be absent, cannot be
- * gitignored, and needs no discovery rules of its own.
- *
  * ── WHAT WAS MEASURED AND KILLED, so it is not proposed again ───────────────
  * (full measurements: consumer repo, `idei/paper-pipeline-extraction/`, 2026-09-11)
  *
@@ -85,16 +81,14 @@ import {
   CONFIG_KEY,
   DEFAULT_PAPERS_ROOT,
   PAPERS_DIR_FIELD,
-  declaredSettings,
-  renamedFieldMessage,
-  settingsOf,
+  CONFIG_FILE,
 } from "../lib/paper-config.mjs";
 export { DEFAULT_PAPERS_ROOT };
 
 /**
  * The declared papers root, verified to be on disk.
  *
- * @param pkg      the consumer's parsed `package.json`
+ * @param settings the project's root `paperlint.json`, parsed (`settingsOf(root)`), or undefined
  * @param baseDir  the directory the root is relative to. PASS `import.meta.dirname` FROM THE
  *                 CONFIG rather than relying on the default: `process.cwd()` is wherever the
  *                 editor, the hook runtime or the CI step happened to start, and in a git
@@ -104,12 +98,8 @@ export { DEFAULT_PAPERS_ROOT };
  *          globs, which ESLint interprets relative to the config, and an absolute path there
  *          would change their meaning.
  */
-export function papersRoot(pkg, baseDir = process.cwd()) {
-  const found = declaredSettings(pkg);
-  if (found.conflict !== null) throw new TypeError(found.conflict);
-  const renamed = renamedFieldMessage(found.settings);
-  if (renamed) throw new TypeError(renamed);
-  const declared = settingsOf(pkg)?.[PAPERS_DIR_FIELD];
+export function papersRoot(settings, baseDir = process.cwd()) {
+  const declared = settings?.[PAPERS_DIR_FIELD];
   // 🔴 `declared === undefined`, NOT `declared ?? DEFAULT`. The two differ on exactly one
   // input — `"papersDir": null` — and the difference is the whole point: `??` reads an explicit
   // `null` as "nothing was declared" and silently uses the default, which is a typed keystroke
@@ -126,9 +116,9 @@ export function papersRoot(pkg, baseDir = process.cwd()) {
       `${CONFIG_KEY}: the papers root "${root}" does not exist under ${baseDir}.\n` +
         (declared === undefined
           ? `Nothing was declared, so the default "${DEFAULT_PAPERS_ROOT}" was used. Declare the ` +
-            `real location in package.json:\n` +
-            `  "${CONFIG_KEY}": { "${PAPERS_DIR_FIELD}": "path/to/papers" }`
-          : `It is declared in package.json as "${declared}". Fix it there, or create the ` +
+            `real location in ${CONFIG_FILE}:\n` +
+            `  { "${PAPERS_DIR_FIELD}": "path/to/papers" }`
+          : `It is declared in ${CONFIG_FILE} as "${declared}". Fix it there, or create the ` +
             `directory.`) +
         `\nThis is thrown rather than ignored on purpose: a papers root that matches nothing ` +
         `makes every rule lint zero files, and a run with zero findings is indistinguishable ` +
@@ -154,8 +144,8 @@ export function paperFiles(root) {
     tex: [`${root}/*/paper.tex`],
     /** The per-paper stage ledger. */
     status: [`${root}/*/PIPELINE-STATUS.md`],
-    /** The venue data card. */
-    venue: [`${root}/*/venue.json`],
+    /** The per-paper settings file, `paperlint.json`. */
+    venue: [`${root}/*/${CONFIG_FILE}`],
     /** Facts extracted from the built PDF. */
     pdfFacts: [`${root}/*/_build/paper.facts.json`],
     /** Facts extracted from the bibliography. */

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

@@ -6,10 +6,9 @@
  * 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:
+ * the papers whose venue asks, in that paper's paperlint.json:
  *
- *   "paperlint": { "rules": [ { "files": ["papers/my-paper/**"],
- *     "rules": { "pdf/last-page-balance": ["error", { "tolerancePt": 120 }] } } ] }
+ *   { "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.)
@@ -29,12 +28,14 @@
  *
  * 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
+ * is missing: no facts file (unless the paper extends a venue preset — then `pdf/measured` says it),
+ * 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";
+import { CONFIG_FILE } from "../lib/paper-config.mjs";
 
 /** The difference, in points, that two columns may end apart. See the harness for why 120. */
 export const DEFAULT_TOLERANCE_PT = 120;
@@ -133,11 +134,28 @@ function reportLine(file) {
   }
 }
 
+/**
+ * Whether the paper extends a venue preset. Then the venue rules run on it too, and `pdf/measured`
+ * already says — once, as a warning — that a paper with no facts was not checked; this rule
+ * repeating it as an error would fail a lint-only CI for every paper of a venue whose preset turns
+ * this rule on.
+ */
+function extendsPreset(paperDir) {
+  try {
+    const s = JSON.parse(readFileSync(join(paperDir, CONFIG_FILE), "utf8"));
+    return typeof s?.extends === "string" && s.extends !== "";
+  } catch {
+    return false;
+  }
+}
+
 /** 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 } };
+    return extendsPreset(paperDir)
+      ? null
+      : { 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);

package/eslint-rules/review-frontmatter.mjs

@@ -0,0 +1,118 @@
+/**
+ * `review/frontmatter` — a review report's frontmatter is a RECORD, validated by a JSON Schema.
+ *
+ * ── WHAT IT CHECKS ───────────────────────────────────────────────────────────────
+ * A review under `reviews/` declares what it found in its YAML frontmatter:
+ *
+ *   findings:
+ *     - id: 1
+ *       status: open            # open | fixed | wontfix
+ *       cause: missing-skill    # skill-defect | missing-skill | hook | rule — required when open
+ *
+ * The pipeline convention behind it: a review does not end with a list of findings, it ends with
+ * what in the PIPELINE let each one through. Otherwise the text gets fixed while the tool that
+ * missed it stays the same. The schema is `review-frontmatter.schema.json` beside this file, and
+ * "an open finding names its cause" is its `if`/`then`, not code here.
+ *
+ * The same mechanism, with a schema of its own, is `sibling/frontmatter`
+ * (`sibling-frontmatter.mjs`): `frontmatterRule` below is the one implementation.
+ *
+ * ── WHY THIS REPLACED TWO RULES IN 3.0.0 ────────────────────────────────────────────
+ * `review/findings-cause` GUESSED the findings from the prose: it counted numbered table rows and
+ * list items starting in bold, looked for a magic word (`causeMarker`, "Cause:") anywhere in the
+ * text, spoke only above a threshold (`minFindings`), and skipped reports older than a date
+ * (`sinceCreated`) — a date ratchet its own header said belonged in `ignores`. Every one of
+ * those was a convention in prose standing in for a field nobody had declared.
+ * `doc/fields` was a hand-rolled schema language in the config (`{ field: { values: [...] } }`),
+ * and its one real use was the `read:` field of sibling cards — which this package's own
+ * `analyze-sibling-paper` skill writes, so the package now ships that schema too. The record is
+ * data, the schema is JSON Schema, the validator is ajv.
+ *
+ * A review with no `findings` key is not a findings record and is not checked for findings — so
+ * there is no date to compare: old reports simply have no records. A file with no frontmatter is
+ * validated as `{}`, so a field a schema requires is still reported on it: a missing header must
+ * not be a way around the check.
+ *
+ * YAML is read with js-yaml's CORE schema, which leaves `2026-09-20` a string. The default schema
+ * turns it into a Date, and a schema asking for `"type": "string"` would then reject a date the
+ * author wrote correctly.
+ */
+import Ajv from "ajv";
+import { CORE_SCHEMA, load } from "js-yaml";
+import { readFileSync } from "node:fs";
+
+/** One ajv error as a line a person can act on. `if` errors only repeat their `then`. */
+function describe(e) {
+  const where = e.dataPath
+    ? `\`${e.dataPath.replace(/^\./, "")}\``
+    : "the frontmatter";
+  if (e.keyword === "enum")
+    return `${where} must be one of: ${e.params.allowedValues.join(", ")}`;
+  if (e.keyword === "additionalProperties")
+    return `${where} has an unknown field \`${e.params.additionalProperty}\``;
+  return `${where} ${e.message}`;
+}
+
+const errorsOf = (validate, data) =>
+  validate(data)
+    ? []
+    : (validate.errors ?? []).filter((e) => e.keyword !== "if").map(describe);
+
+/**
+ * A rule that validates a markdown file's YAML frontmatter against the JSON Schema in `schemaUrl`
+ * (a file shipped beside the rule). A file with no frontmatter is validated as `{}`.
+ */
+export function frontmatterRule(schemaUrl, description) {
+  const validate = new Ajv({ allErrors: true }).compile(
+    JSON.parse(readFileSync(schemaUrl, "utf8")),
+  );
+  return {
+    meta: {
+      type: "problem",
+      docs: { description },
+      schema: [],
+      messages: {
+        malformed:
+          "the frontmatter does not parse as YAML ({{why}}) — there is no record to read",
+        invalid: "{{problem}}",
+      },
+    },
+    create(context) {
+      let frontmatter = null;
+      let data = {};
+      return {
+        yaml(node) {
+          frontmatter = node;
+          try {
+            data = load(node.value ?? "", { schema: CORE_SCHEMA }) ?? {};
+          } catch (e) {
+            data = null;
+            context.report({
+              node,
+              messageId: "malformed",
+              data: { why: e.reason ?? e.message ?? "unparseable" },
+            });
+          }
+        },
+        "root:exit"(root) {
+          if (data === null) return;
+          for (const problem of errorsOf(validate, data))
+            context.report({
+              node: frontmatter ?? root,
+              messageId: "invalid",
+              data: { problem },
+            });
+        },
+      };
+    },
+  };
+}
+
+export default {
+  rules: {
+    frontmatter: frontmatterRule(
+      new URL("./review-frontmatter.schema.json", import.meta.url),
+      "a review's frontmatter is a record: its findings, each with a status and, when open, the pipeline cause — validated by JSON Schema",
+    ),
+  },
+};

package/eslint-rules/review-frontmatter.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "urn:paperlint:review-frontmatter",
+  "title": "paperlint review frontmatter",
+  "description": "The YAML frontmatter of a review report under reviews/. A review with no `findings` key is not a findings record and is not checked for findings. A project adds its own required fields with the `reviewSchema` setting; its schema is applied together with this one.",
+  "type": "object",
+  "properties": {
+    "findings": {
+      "description": "What the review found, one record per finding.",
+      "type": "array",
+      "items": { "$ref": "#/definitions/finding" }
+    }
+  },
+  "definitions": {
+    "finding": {
+      "type": "object",
+      "required": ["id", "status"],
+      "properties": {
+        "id": {
+          "description": "How the review body refers to this finding.",
+          "type": ["integer", "string"]
+        },
+        "status": { "enum": ["open", "fixed", "wontfix"] },
+        "cause": {
+          "description": "What in the PIPELINE let this through: a defective skill, a missing skill, a hook, or a rule. Fix that, and the text edit falls out of running the fixed tool.",
+          "enum": ["skill-defect", "missing-skill", "hook", "rule"]
+        },
+        "title": { "type": "string" },
+        "note": { "type": "string" }
+      },
+      "additionalProperties": false,
+      "if": { "properties": { "status": { "const": "open" } } },
+      "then": { "required": ["cause"] }
+    }
+  }
+}