paperlint 2.0.0

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

@@ -0,0 +1,131 @@
+/**
+ * Battery for `paper/typography` — mutations over DIFFERENT properties: the `§` count, the
+ * ratchet and its direction, and what the bare-decimal count is allowed to read.
+ *
+ * 🔴 Why the ratchet needs TWO mutations, not one. It has two halves, and they're opposite:
+ * declared debt must STAY SILENT (otherwise a legacy paper drowns out a new finding and the
+ * rule gets turned off), while growth must SPEAK (otherwise debt turns into a permit). A
+ * mutation removing the first leaves the second green and vice versa — so both are needed, and
+ * they must die on different asserts.
+ *
+ * ⚠️ What the battery does NOT check, and why: the accuracy of the counting regexes
+ * themselves. The harness's own fixtures hold those (an arXiv identifier is not a decimal
+ * fraction, consecutive `Figure`s are not a defect), and a mutation here would prove the
+ * fixture exists, not that the count is correct.
+ *
+ * The bare-decimal count is the exception, because what it gets wrong is not the lexeme but the
+ * INPUT: rpp#44 was a correct regex run over the wrong text. So two cases below change what it
+ * reads — back to the raw source (the SILENT half must die), and with math dropped from the walk
+ * (the CAUGHT half must die, since math is where p-values live).
+ */
+import { fileURLToPath } from "node:url";
+import { dirname, join, resolve } from "node:path";
+import { runMutations } from "../lib/mutation-driver.mjs";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const ROOT = resolve(HERE, "..");
+const RULE = join(HERE, "paper-typography.mjs");
+const HARNESS = join(HERE, "paper-typography.harness.mjs");
+
+process.exit(
+  runMutations({
+    root: ROOT,
+    runner: "node",
+    cases: [
+      {
+        name: "the ratchet stops LETTING declared debt THROUGH",
+        harness: HARNESS,
+        expect: "known debt, unchanged, is silent",
+        disables:
+          "the 'debt stays silent' half — a legacy paper with 246 § characters starts going " +
+          "red on every run, and the rule gets turned off within a day, taking new findings with it",
+        edits: [
+          [
+            RULE,
+            "if (n <= before) continue; // known debt, unchanged or paid down",
+            "if (false) continue;",
+          ],
+        ],
+      },
+      {
+        name: "the ratchet stops CATCHING growth",
+        harness: HARNESS,
+        expect: "growth over known debt is reported",
+        disables:
+          "the second half — the one debt is declared for in the first place: without it a " +
+          "record in the debt file turns into a permanent permit rather than a mark of today's state",
+        // 🔴 NOT an unconditional `continue;`: that kills the rule entirely, and the harness dies
+        // on the very first "fires on §" assert — that is, a finding about the MUTATION, not
+        // about the protection. `before > 0` keeps the rule alive where there is no debt, and
+        // mutes EXACTLY growth over declared debt.
+        edits: [
+          [
+            RULE,
+            "if (n <= before) continue; // known debt, unchanged or paid down",
+            "if (before > 0) continue;",
+          ],
+        ],
+      },
+      {
+        name: "the `§` counter stops seeing the macro form",
+        harness: HARNESS,
+        expect:
+          "the section sign count includes the macro form, not only the glyph",
+        disables:
+          "exactly the case the counter was written for: in LaTeX the section sign is typeset " +
+          "as `\\S\\ref{…}`, not as the glyph, and a check that only counts the glyph reports " +
+          "clean on the very defect it was written to catch",
+        edits: [
+          [
+            RULE,
+            "(body.match(/§/g) || []).length +\n    (body.match(/\\\\S(?=\\s*\\\\ref|~\\\\ref|\\d)/g) || []).length",
+            "(body.match(/§/g) || []).length",
+          ],
+        ],
+      },
+      {
+        name: "bareDecimal reads the RAW source again (the #44 defect)",
+        harness: HARNESS,
+        expect: "LaTeX SILENT: a figure width option",
+        disables:
+          "the reason the count walks the tree: over raw source the regex fires on option values, " +
+          "column specs, comments, listings and tikz coordinates — 22 findings, 0 real, on the " +
+          "corpus that prompted #44",
+        edits: [[RULE, "visibleRuns(context.sourceCode),", "[raw],"]],
+      },
+      {
+        name: "arguments unified-latex did not attach are read as prose again",
+        harness: HARNESS,
+        expect: "LaTeX SILENT: a macro definition body",
+        disables:
+          "the second path to the #44 defect: for `\\def`, an author's macro, `subfigure` or " +
+          "`longtable` the parser returns the arguments as sibling nodes, and a tree walk that " +
+          "trusts the tree reads `{.48\\textwidth}` as prose",
+        edits: [
+          [
+            RULE,
+            '  while (nodes[j]?.type === "group") j++;\n  return j - 1;',
+            "  return i;",
+          ],
+        ],
+      },
+      {
+        name: "the tree walk stops entering math",
+        harness: HARNESS,
+        // The messy fixture's two decimals are both in math, so the first assertion to die is the
+        // plain "fires" one — which is the point: without math there is no bare decimal left.
+        expect: "fires on the bare decimal",
+        disables:
+          "the half the projection could never give: math is blanked there, and math is where " +
+          "`$p < .05$` lives — the exact form the reviewer flagged",
+        edits: [
+          [
+            RULE,
+            'n.type === "mathenv"\n    )\n      texRuns(n.content, true, out);',
+            'n.type === "mathenv"\n    )\n      void 0;',
+          ],
+        ],
+      },
+    ],
+  }),
+);

package/eslint-rules/papers.harness.mjs

@@ -0,0 +1,259 @@
+/**
+ * Colocated test for `eslint-rules/papers.mjs`.
+ * Run: `npx vigiles test eslint-rules/papers.harness.mjs`
+ *
+ * FOUR PARTS:
+ *   I.   THE DEFAULT AND THE DECLARATION — the two ways a root is chosen.
+ *   II.  THE REFUSALS — every input this module must NOT quietly accept, each checked for the
+ *        message a person will actually read, not only for the fact that something threw.
+ *   III. PROPERTIES NOBODY SEES, WITHOUT WHICH THE GLOBS SILENTLY CHANGE MEANING:
+ *        the returned root is RELATIVE, and `baseDir` — not `process.cwd()` — decides where it
+ *        is looked for.
+ *   IV.  THE ACCEPTANCE CRITERION OF THE WHOLE EXTRACTION: no consumer-specific path anywhere
+ *        in this package. This is the assertion that makes the package reusable, and it is the
+ *        one that will fail first when someone "just hard-codes it for now".
+ *
+ * 🔴 Assertions live at MODULE TOP LEVEL: `vigiles test` imports the file and treats "it did
+ * not throw" as success; an exported `tests` object is run by nothing.
+ */
+import assert from "node:assert/strict";
+import { PAPERS_DIR_FIELD } from "../lib/paper-config.mjs";
+import {
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+  statSync,
+  realpathSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, isAbsolute, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { DEFAULT_PAPERS_ROOT, paperFiles, papersRoot } from "./papers.mjs";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(HERE, "..");
+
+const TMP = realpathSync(mkdtempSync(join(tmpdir(), "papers-root-")));
+// Registered immediately, not at the end: assertions throw, and cleanup at the bottom of a
+// file never runs in exactly the runs that are red.
+process.on("exit", () => rmSync(TMP, { recursive: true, force: true }));
+
+/** A throwaway repository with the given directories already on disk. */
+const repoWith = (...dirs) => {
+  const base = mkdtempSync(join(TMP, "repo-"));
+  for (const d of dirs) mkdirSync(join(base, d), { recursive: true });
+  return base;
+};
+const declaring = (papers) => ({
+  paperlint: { [PAPERS_DIR_FIELD]: papers },
+});
+
+// ═════════════════════════════════════════════════════════════════════════════
+// I. THE DEFAULT AND THE DECLARATION
+// ═════════════════════════════════════════════════════════════════════════════
+{
+  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: {} }],
+  ])
+    assert.equal(
+      papersRoot(pkg, repo),
+      DEFAULT_PAPERS_ROOT,
+      `${label}: a consumer that declares nothing must get the default "${DEFAULT_PAPERS_ROOT}"`,
+    );
+}
+
+// A declared root wins, including a nested one — the first consumer's is two levels deep, and
+// a helper that only handled a single path segment would work on every fixture and fail there.
+for (const declared of ["papers", "docs/papers", "writing/drafts", "a/b/c/d"]) {
+  const repo = repoWith(declared);
+  assert.equal(
+    papersRoot(declaring(declared), repo),
+    declared,
+    `a declared root must be returned as declared: ${declared}`,
+  );
+}
+
+// ═════════════════════════════════════════════════════════════════════════════
+// II. THE REFUSALS — and the message each one carries
+// ═════════════════════════════════════════════════════════════════════════════
+// 🔴 THE CENTRAL ONE. A root that is not on disk must STOP the config from loading, because
+// the alternative is not "wrong findings" but NO findings — and a run with no findings is
+// byte-identical to a run that checked everything and passed.
+{
+  const repo = repoWith("somewhere-else");
+  assert.throws(
+    () => papersRoot(declaring("writing/drafts"), repo),
+    (e) =>
+      /does not exist/.test(e.message) &&
+      // names WHAT was declared, so the reader does not have to guess which of several
+      // candidate paths the tool was looking at,
+      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) &&
+      // 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 " +
+      "it looked, its source, and why silence was not an option",
+  );
+
+  // The SAME failure reached by defaulting carries a DIFFERENT message, and that difference is
+  // the whole usefulness of it: "you declared the wrong thing" and "you declared nothing and
+  // the default does not fit you" have different fixes, and a shared message would hide which.
+  assert.throws(
+    () => papersRoot({}, repo),
+    (e) =>
+      /does not exist/.test(e.message) &&
+      /Nothing was declared/.test(e.message) &&
+      e.message.includes(
+        `"paperlint": { "${PAPERS_DIR_FIELD}": "path/to/papers" }`,
+      ),
+    "a missing root reached by DEFAULTING must say so and show the declaration to add",
+  );
+}
+
+// Shapes that are present but unusable. Left unchecked, `""` is the worst of them: it makes
+// every glob `"/*/paper.tex"` — rooted at the filesystem, matching nothing, silently.
+for (const bad of ["", null, 0, false, [], {}, 42])
+  assert.throws(
+    () => papersRoot(declaring(bad), TMP),
+    (e) => e instanceof TypeError && /non-empty string/.test(e.message),
+    `a "papers" of ${JSON.stringify(bad)} must be refused as a type error, not coerced`,
+  );
+
+// ═════════════════════════════════════════════════════════════════════════════
+// III. PROPERTIES NOBODY SEES
+// ═════════════════════════════════════════════════════════════════════════════
+// 🔴 THE RETURNED ROOT MUST STAY RELATIVE. ESLint resolves `files:` globs against the config's
+// directory; an absolute path there is a different pattern with different behaviour, and the
+// breakage would show up as "the rule stopped matching", i.e. as silence.
+{
+  const repo = repoWith("writing/drafts");
+  const got = papersRoot(declaring("writing/drafts"), repo);
+  assert.equal(
+    isAbsolute(got),
+    false,
+    "the root must be returned relative, not resolved",
+  );
+  assert.equal(
+    got.includes(repo),
+    false,
+    "the root must not carry the base directory",
+  );
+}
+
+// 🔴 `baseDir` DECIDES, NOT `process.cwd()`. This is the assertion that pins the reason the
+// parameter exists: cwd is wherever the editor, the CI step or the hook runtime happened to
+// start, and in a git worktree it can be an entirely different checkout. A helper that quietly
+// used cwd would pass every test run from the repository root and fail in exactly the setups
+// nobody runs tests in.
+{
+  const real = repoWith("writing/drafts");
+  const empty = repoWith("unrelated");
+  assert.equal(papersRoot(declaring("writing/drafts"), real), "writing/drafts");
+  assert.throws(
+    () => papersRoot(declaring("writing/drafts"), empty),
+    /does not exist/,
+    "baseDir must be what is consulted — the same declaration must fail against a base that " +
+      "does not contain the root",
+  );
+}
+
+// Every glob set is derived from the root, and NONE of them is spelled out independently: a
+// set that forgot to interpolate would keep matching the previous consumer's layout.
+{
+  const sets = paperFiles("R");
+  const names = Object.keys(sets).sort();
+  assert.deepEqual(
+    names,
+    ["all", "md", "pdfFacts", "refFacts", "status", "tex", "venue"],
+    "the glob set changed — a consumer's config enumerates these by name, and a renamed or " +
+      "dropped key is a block that silently lints nothing",
+  );
+  for (const [name, globs] of Object.entries(sets)) {
+    assert.ok(
+      Array.isArray(globs) && globs.length > 0,
+      `${name}: must be a non-empty array`,
+    );
+    for (const g of globs)
+      assert.ok(
+        g.startsWith("R/"),
+        `${name}: glob "${g}" does not start at the given root`,
+      );
+  }
+  // Two roots must produce two disjoint sets — proof the root is interpolated everywhere and
+  // not merely present in the first glob of each list.
+  const other = paperFiles("Q");
+  for (const name of names)
+    assert.deepEqual(
+      sets[name].map((g) => g.replace(/^R\//, "")),
+      other[name].map((g) => g.replace(/^Q\//, "")),
+      `${name}: the two roots did not produce the same shapes — something is hard-coded`,
+    );
+}
+
+// ═════════════════════════════════════════════════════════════════════════════
+// IV. THE ACCEPTANCE CRITERION OF THE EXTRACTION
+// ═════════════════════════════════════════════════════════════════════════════
+// 🔴 NO CONSUMER-SPECIFIC PATH ANYWHERE IN THIS PACKAGE. This is the assertion the whole
+// extraction exists for, and the reason it is here rather than in a plan document: a plan is
+// read once, a test runs every time. The forbidden word is the first consumer's own directory
+// name; it may appear ONLY in this file (as the value under test) and in prose that documents
+// the decision.
+{
+  // ⚠️ THE ONLY LEGITIMATE OCCURRENCE OF THIS WORD IN THE PACKAGE, and it is here out of
+  // necessity: it is the SUBJECT of the assert. The fixtures above deliberately use neutral
+  // paths (`writing/drafts`) — until 2026-09-12 they carried the consumer's real directory name,
+  // and the pre-publication audit found eleven occurrences where the meaning called for one.
+  // ⚠️ THIS LIST HOLDS PATH TOKENS ONLY, AND THE PERSONAL NAMES ARE DELIBERATELY ABSENT.
+  // Extending it to the owner's name was tried on 2026-09-12 and reverted the same hour by the
+  // consumer-side audit that reads this repository before it is published: to GUARD against a
+  // string a checker must SPELL it, so the extension put a private personal name into a public
+  // source file and into a public commit message — a leak created by the leak detector. A
+  // directory name is a layout fact and is safe to spell here; a person is not.
+  //
+  // The personal half therefore lives in the CONSUMER, where those strings already are, and runs
+  // over `node_modules/<this package>` from there. That is rule T3 of the extraction plan, and
+  // this is the measurement that made it non-negotiable rather than merely tidy.
+  const FORBIDDEN = ["migratsiya"];
+  const SELF = fileURLToPath(import.meta.url);
+  const skipDirs = new Set(["node_modules", ".git", "fixtures"]);
+  const offenders = [];
+  const walk = (dir) => {
+    for (const entry of readdirSync(dir)) {
+      if (skipDirs.has(entry)) continue;
+      const p = join(dir, entry);
+      if (statSync(p).isDirectory()) {
+        walk(p);
+        continue;
+      }
+      if (p === SELF) continue;
+      if (!/\.(mjs|js|ts|json|tex|sh)$/.test(entry)) continue;
+      let text;
+      try {
+        text = readFileSync(p, "utf8");
+      } catch {
+        continue;
+      }
+      const hit = FORBIDDEN.find((w) => text.includes(w));
+      if (hit) offenders.push(`${p.slice(ROOT.length + 1)} (${hit})`);
+    }
+  };
+  walk(ROOT);
+  assert.deepEqual(
+    offenders,
+    [],
+    `this package names the first consumer's own directory ("${FORBIDDEN.join(", ")}") in: ` +
+      `${offenders.join(", ")}. A package that hard-codes one consumer's layout has exactly ` +
+      `one possible user, which is the thing the extraction exists to undo. The root belongs ` +
+      `in the consumer's package.json — see eslint-rules/papers.mjs`,
+  );
+}

package/eslint-rules/papers.mjs

@@ -0,0 +1,166 @@
+/**
+ * papers.mjs — WHERE THE CONSUMER'S PAPERS LIVE. One declaration, three readers.
+ *
+ * ── THE PROBLEM THIS SOLVES ─────────────────────────────────────────────────
+ * This package lints papers. It must not know where any particular consumer keeps them: the
+ * first consumer keeps them two levels deep under a directory named in its own language, and
+ * a package that hard-codes that word is a package with exactly one possible user. But the
+ * path cannot simply be "passed in" either, because it is needed by FOUR carriers with four
+ * different mechanics — an ESLint config (JavaScript), a compiled hook (a closed vocabulary
+ * 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:
+ *
+ *     "paperlint": { "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:
+ *
+ *   ESLint  →  `import pkg from "./package.json" with { type: "json" }` + this module
+ *   hook    →  `needs: [provide("pkg", "cat package.json")]`, JSON.parse inside `decide`
+ *   prose   →  the skill names a COMMAND, not a path:
+ *              `node -p "require('./package.json')['paperlint']?.papersDir ?? '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)
+ *
+ *   A SYMLINK (`papers -> <the real directory>`) plus a hard-coded default, no config at all.
+ *     ESLint does NOT descend into a symlinked directory when walking `.`: the run reported
+ *     ZERO files and exit 0 — the green zero this package has a dedicated guard against.
+ *
+ *   AN ENVIRONMENT VARIABLE (`$PAPER_ROOT`).
+ *     A compiled hook cannot read `process.env` — the vocabulary check rejects every import
+ *     except `vigiles/hook`. The only way in is `provide("root", "echo $PAPER_ROOT")`, and
+ *     then THREE different places must set the same value (the agent harness that spawns the
+ *     hook, CI, the editor running ESLint). Unset, it expands to the empty string and every
+ *     prefix test silently passes.
+ *
+ *   A FILENAME MARKER, no root at all (`**\/paper.tex`).
+ *     Measured on the first consumer: `paper.tex` ×4 with one outside the corpus,
+ *     `PIPELINE-STATUS.md` ×6 with two of them test fixtures, `paper.md` ×3 with two outside.
+ *     The guard that would consume this is a `deny` at `error` severity; a denial on writing
+ *     a fixture gets the hook switched off the same day.
+ *
+ *   `context.settings`.
+ *     It delivers data INTO a rule; it does not choose which files a rule sees. `files:` is
+ *     the only mechanism that does. Useful for a plugin's `structureRoot`, useless here.
+ *
+ * ── WHY THIS THROWS INSTEAD OF FALLING BACK ─────────────────────────────────
+ * 🔴 A wrong root does not produce wrong findings — it produces NO findings, and a run with no
+ * findings is byte-identical to a run that examined everything and passed. That is the one
+ * failure mode of this whole design, and it belongs to the ESLint carrier alone: the other
+ * three fail loudly on their own (a hook throws on `join(undefined)`, `ls` exits non-zero,
+ * LaTeX stops with `! Emergency stop.`). So this module refuses to return a root it cannot
+ * see on disk, and the refusal happens while the CONFIG is loading — before any rule runs,
+ * where it cannot be mistaken for a clean lint.
+ *
+ * ⚠️ THAT IS NOT ENOUGH ON ITS OWN, and saying so is the point. `existsSync` proves the
+ * directory exists, not that any rule was handed a file from it: a root that exists but holds
+ * no papers, or a glob shape that stopped matching, still yields the green zero. The second
+ * net is `scripts/rules-see-files.mjs`, which asks ESLint what the effective config of every
+ * linted file is and names any rule that saw none. A consumer using this module without
+ * running that script has one net, not two.
+ *
+ * ⚠️ THE EXAMPLES IN THIS FILE ARE DELIBERATELY GENERIC (`docs/papers`), and that is ENFORCED
+ * rather than a style preference: `papers.harness.mjs` part IV fails if the first consumer's own
+ * directory name appears anywhere in this package outside the test itself. It caught this very
+ * docblock on 2026-09-11, where the example used the real value. An exemption list is what turns
+ * such a check into decoration, so there is exactly one exemption: the file asserting it.
+ */
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+
+// Re-exported, not re-declared. This file is not a hook, so nothing stops it importing the one
+// source; it had its own copy for no reason, and that copy was outside the agreement check that
+// compares the three hooks — it could have drifted in silence.
+import {
+  CONFIG_KEY,
+  DEFAULT_PAPERS_ROOT,
+  PAPERS_DIR_FIELD,
+  declaredSettings,
+  renamedFieldMessage,
+  settingsOf,
+} 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 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
+ *                 worktree it can be a different checkout entirely. The config file sits at
+ *                 the repository root, so its own directory is the stable answer.
+ * @returns the root as DECLARED (relative), not resolved — it goes straight into `files:`
+ *          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];
+  // 🔴 `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
+  // being treated as an absence. Caught by the harness on 2026-09-11, where the first draft of
+  // this line used `??` and let `null` through. Absence means default; anything written down
+  // means it must be usable.
+  const root = declared === undefined ? DEFAULT_PAPERS_ROOT : declared;
+  if (typeof root !== "string" || root.length === 0)
+    throw new TypeError(
+      `${CONFIG_KEY}: "${PAPERS_DIR_FIELD}" must be a non-empty string, got ${JSON.stringify(root)}`,
+    );
+  if (!existsSync(resolve(baseDir, root)))
+    throw new Error(
+      `${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 ` +
+            `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 ` +
+        `from a run that checked everything and passed.`,
+    );
+  return root;
+}
+
+/**
+ * The glob sets a consumer declares its blocks on, derived from one root.
+ *
+ * 🔴 THE SHAPES LIVE HERE, NOT IN THE CONSUMER, and that is the half that keeps a rule from
+ * going blind later. `paper.md` + `draft.md`, `_build/*.facts.json`, `PIPELINE-STATUS.md` are
+ * this pipeline's CONVENTION; if a rule starts reading a new file, the glob for it must arrive
+ * with the rule, in the same package, rather than as a line every consumer has to add by hand
+ * to keep up. A hand-maintained list of paths is the thing that rots, and rots silently.
+ */
+export function paperFiles(root) {
+  return {
+    /** Markdown drafts — the two names a paper's prose is allowed to have. */
+    md: [`${root}/*/paper.md`, `${root}/*/draft.md`],
+    /** The LaTeX source of a paper (not its figures, not its vendored drafts). */
+    tex: [`${root}/*/paper.tex`],
+    /** The per-paper stage ledger. */
+    status: [`${root}/*/PIPELINE-STATUS.md`],
+    /** The venue data card. */
+    venue: [`${root}/*/venue.json`],
+    /** Facts extracted from the built PDF. */
+    pdfFacts: [`${root}/*/_build/paper.facts.json`],
+    /** Facts extracted from the bibliography. */
+    refFacts: [`${root}/*/_build/refs.facts.json`],
+    /** Everything under the root — for blocks that turn other tooling OFF rather than on. */
+    all: [`${root}/**/*.*`],
+  };
+}