paperlint 9.0.0 → 10.0.0

package/src/cli.ts

@@ -138,7 +138,12 @@ import {
   init,
   processInteractivity,
 } from "./init.ts";
-import { newPaper, reportNewPaper, type VenueSetting } from "./new-paper.ts";
+import {
+  newPaper,
+  reportNewPaper,
+  STATUS_FILE,
+  type VenueSetting,
+} from "./new-paper.ts";
 // The one source for the consumer's config key lives in lib/ (the ESLint rules and the skill scripts
 // import it too). It is imported compiled, from dist/, the one path that resolves the same from src/
 // and from dist/ — see CONTRIBUTING.md.
@@ -164,12 +169,22 @@ export { init };
 export { nextSteps } from "./init.ts";
 
 import paperStages from "#eslint-rules/paper-stages";
+import preregCoverage from "#eslint-rules/prereg-coverage";
 import cycleStage from "#eslint-rules/cycle-stage";
 import { CYCLE_RULE_LEVELS, cycleRules } from "./cycle-rules.ts";
 import {
   FOLDER_VENUE_RULE_LEVELS,
   folderVenueRules,
 } from "./folder-venue-rule.ts";
+import {
+  FOLDER_LAYOUT_RULE_LEVELS,
+  folderLayoutRules,
+} from "./folder-layout-rule.ts";
+import { folderLayoutHook } from "./folder-layout-hook.ts";
+import {
+  REPRO_LAYOUT_RULE_LEVELS,
+  reproLayoutRules,
+} from "./repro-layout-rule.ts";
 import typography from "#eslint-rules/paper-typography";
 import texBuild from "#eslint-rules/tex-build";
 import reviewFrontmatter from "#eslint-rules/review-frontmatter";
@@ -177,6 +192,7 @@ import siblingFrontmatter from "#eslint-rules/sibling-frontmatter";
 import pdfRules from "#eslint-rules/pdf-last-page-balance";
 import { messageOf } from "./domain/text.ts";
 import { isRecord } from "./domain/record.ts";
+import { ESCAPE_HATCH } from "./domain/paper-layout.ts";
 
 /** The shipped venue presets, read from the package's venues directory — the one list. */
 const SHIPPED_VENUES = (): string[] => shippedPresets(presetsDir());
@@ -348,6 +364,9 @@ const FRAGMENT_RULES = {
   "heading-case": REGISTER_AND_CASE_RULES["heading-case"],
 };
 
+/** What the two layout rules read with: the disk and its directory listings. */
+const LAYOUT_RULE_DEPS = { files: nodeFiles, listDir: nodeListDir };
+
 /** What the talk rules read with: the disk, the shipped presets, and the three media readers. */
 const TALK_RULE_DEPS = {
   files: nodeFiles,
@@ -380,7 +399,9 @@ export function buildConfig(
     // its files carry every marker a paper does. Flat config does NOT ignore dot-directories by
     // default (only `node_modules/` and `.git/`), so without this block `paperlint lint` would lint the
     // template as a paper — and a richer template with placeholder stages would fail the run.
-    { ignores: ["**/.template/"] },
+    // The same for a paper's `extra/`: the layout promises it is never judged, and an archived
+    // snapshot there carries a paper's markers too, so its folder read as a paper root with strays.
+    { ignores: ["**/.template/", `**/${ESCAPE_HATCH}/`] },
     // The `pdf` plugin is registered for EVERY file. A consumer's block (`rules`, appended below)
     // may name its rules for a glob that also matches markdown files; with the plugin defined only
     // beside `paper.tex`, ESLint would refuse those files with "could not find plugin". Every rule
@@ -409,8 +430,12 @@ export function buildConfig(
           rules: {
             ...paperStages.rules,
             ...folderVenueRules({ files: nodeFiles, venuesDir: presetsDir() }),
+            ...folderLayoutRules(LAYOUT_RULE_DEPS),
           },
         },
+        repro: { rules: reproLayoutRules(LAYOUT_RULE_DEPS) },
+        // Registered, on for no paper: `"study/declare-sample": "error"` in paperlint.json turns it on.
+        study: { rules: preregCoverage.rules },
         cycle: { rules: CYCLE_STATUS_RULES },
       },
       ...md,
@@ -418,6 +443,8 @@ export function buildConfig(
         "paper/stages": "error",
         "paper/source": "error",
         ...FOLDER_VENUE_RULE_LEVELS,
+        ...FOLDER_LAYOUT_RULE_LEVELS,
+        ...REPRO_LAYOUT_RULE_LEVELS,
         ...CYCLE_RULE_LEVELS,
       },
     },
@@ -647,7 +674,7 @@ export const OPTIONAL_RULES: ReadonlySet<string> = new Set(
  * 🔴 AN OPTIONAL RULE THAT IS ON AND REACHES NO PAPER IS A GREEN ZERO. A `files` glob that matches
  * nothing — a typo, a path relative to the wrong directory — leaves the rule never invoked, and a
  * rule that never runs reports exactly like a rule that passed. So for every optional rule the
- * consumer turned on, some `paper.tex` must actually have it enabled; the ones none has are
+ * consumer turned on, some paper's `paper.tex` or `PIPELINE-STATUS.md` must actually have it enabled; the ones none has are
  * returned, for the caller to refuse.
  *
  * `files` is every `paper.tex` the guard may count: the ones this run linted AND every paper of the
@@ -673,9 +700,16 @@ export async function silentOptionalRules(
     ),
   );
   const reached = new Set<string>();
-  for (const f of new Set(files.filter((p) => basename(p) === MAIN))) {
+  // A paper's rules reach it through two files: `paper.tex` and the `PIPELINE-STATUS.md` beside it,
+  // where the rules about the paper folder itself run.
+  const probes = [
+    ...new Set(files.filter((p) => basename(p) === MAIN)),
+  ].flatMap((f) => [f, join(dirname(f), STATUS_FILE)]);
+  for (const probe of probes) {
     // Undefined for a file outside ESLint's cwd or scope: it reaches nothing.
-    const cfg = ComputedConfig.parse(await eslint.calculateConfigForFile(f));
+    const cfg = ComputedConfig.parse(
+      await eslint.calculateConfigForFile(probe),
+    );
     // Reached is "some block names the rule for this paper", on OR off: a paper that turns off what
     // its venue preset turned on is the documented way out, and reads the same as a glob that missed
     // only if "off" is counted as "not there" — which refused every such paper.
@@ -1084,6 +1118,35 @@ export function toPaths(papers: unknown): string[] {
   return [];
 }
 
+/** What an in-process hook is handed: the payload, and where its output and complaints go. */
+interface HookIo {
+  readonly err: typeof console.error;
+  readonly stdin: () => string;
+  readonly out: (text: string) => void;
+}
+
+/**
+ * Hooks that run inside this process instead of as a vigiles program, each because it must call the
+ * package's own code (`src/folder-layout-hook.ts` says why for its one). Advisory: whatever goes
+ * wrong, the tool call has already happened, so it says so on stderr and exits 0.
+ */
+const IN_PROCESS_HOOKS: Readonly<Record<string, (io: HookIo) => number>> = {
+  "paper-folder-layout": ({ err, stdin, out }) => {
+    try {
+      const said = folderLayoutHook(JSON.parse(stdin()), {
+        files: nodeFiles,
+        listDir: nodeListDir,
+      });
+      if (said !== null) out(`${JSON.stringify(said)}\n`);
+    } catch (e) {
+      err(
+        `paperlint: the paper-folder-layout hook did not run: ${messageOf(e)}`,
+      );
+    }
+    return 0;
+  },
+};
+
 /**
  * `paperlint hook <name>` — run an editor hook. It exists for ONE thing: so that the wiring does not
  * address the runtime from the project root.
@@ -1125,6 +1188,10 @@ export function runHook(
     // the very file the package itself declares as its `bin`.
     resolve = (spec: string): string =>
       createRequire(import.meta.url).resolve(spec),
+    stdin = (): string => readFileSync(0, "utf8"),
+    out = (text: string): void => {
+      process.stdout.write(text);
+    },
   }: {
     err?: typeof console.error;
     /** Runs the hook with the terminal's streams: `spawnSync` is one, and only its status is read. */
@@ -1134,12 +1201,18 @@ export function runHook(
       options: { readonly stdio: "inherit" },
     ) => { readonly status: number | null };
     resolve?: (spec: string) => string;
+    /** The hook's payload, as Claude Code sends it on stdin. */
+    stdin?: () => string;
+    /** Where an in-process hook's output goes: stdout, which Claude Code reads. */
+    out?: (text: string) => void;
   } = {},
 ): number {
   if (!name) {
     err(`\`hook\` needs a name, e.g. \`paperlint hook paper-edit-guard\``);
     return 2;
   }
+  const inProcess = IN_PROCESS_HOOKS[name];
+  if (inProcess !== undefined) return inProcess({ err, stdin, out });
   const program = fileURLToPath(
     new URL(`../hooks/${name}.hook.mjs`, import.meta.url),
   );

package/src/domain/layout-tree.test.ts

@@ -0,0 +1,32 @@
+/**
+ * `renderTree` (`src/domain/layout-tree.ts`): the drawing every layout message and rule page shows.
+ * Branches drawn as `tree` draws them, nested entries indented under a continuing or a closed branch,
+ * every note in one column.
+ */
+import { describe, expect, it } from "vitest";
+import { leaf, renderTree } from "./layout-tree.ts";
+
+describe("renderTree", () => {
+  it("draws nested entries under open and closed branches, notes in one column", () => {
+    expect(
+      renderTree("root/", [
+        { name: "a/", note: "first", children: [leaf("x", "inner")] },
+        leaf("bb", "middle"),
+        { name: "c/", note: "last", children: [leaf("y", "under last")] },
+      ]),
+    ).toBe(
+      [
+        "root/",
+        "├── a/     ← first",
+        "│   └── x  ← inner",
+        "├── bb     ← middle",
+        "└── c/     ← last",
+        "    └── y  ← under last",
+      ].join("\n"),
+    );
+  });
+
+  it("an empty layout is its root alone", () => {
+    expect(renderTree("root/", [])).toBe("root/");
+  });
+});

package/src/domain/layout-tree.ts

@@ -0,0 +1,47 @@
+/**
+ * A layout drawn as a tree — the one picture of what a paper folder may hold.
+ *
+ * The rules' messages, the hook's refusal and the rules' pages all show the same drawing, rendered by
+ * `renderTree` from the constants that decide what is allowed (`paper-layout.ts`, `repro-layout.ts`).
+ * The pages embed it between markers and a test compares them with this render, so a page cannot
+ * describe a layout the code does not enforce.
+ */
+
+/** One entry of a layout: its name (a folder's ends in a slash), what it is for, what it holds. */
+export interface TreeNode {
+  readonly name: string;
+  readonly note: string;
+  readonly children: readonly TreeNode[];
+}
+
+/** An entry with nothing drawn under it. */
+export const leaf = (name: string, note: string): TreeNode => ({
+  name,
+  note,
+  children: [],
+});
+
+interface Row {
+  readonly left: string;
+  readonly note: string;
+}
+
+/** Each entry's line, depth first, with the branch drawing in front of its name. */
+const rowsOf = (nodes: readonly TreeNode[], indent: string): readonly Row[] =>
+  nodes.flatMap((n, i) => {
+    const last = i === nodes.length - 1;
+    return [
+      { left: `${indent}${last ? "└── " : "├── "}${n.name}`, note: n.note },
+      ...rowsOf(n.children, `${indent}${last ? "    " : "│   "}`),
+    ];
+  });
+
+/** `nodes` under `root`, one line each, every note in one column after `←`. Pure. */
+export function renderTree(root: string, nodes: readonly TreeNode[]): string {
+  const rows = rowsOf(nodes, "");
+  const width = Math.max(0, ...rows.map((r) => r.left.length));
+  return [
+    root,
+    ...rows.map((r) => `${r.left.padEnd(width)}  ← ${r.note}`),
+  ].join("\n");
+}

package/src/domain/lookup-cache.ts

@@ -1,5 +1,5 @@
 /**
- * THE LOOKUP CACHE — `<paper>/repro/references-cache.json`: what the citation services ANSWERED,
+ * THE LOOKUP CACHE — `<paper>/repro/data/references-cache.json`: what the citation services ANSWERED,
  * kept so that a build asks each question at most once every MAX_AGE_DAYS, not once per build (#107).
  *
  *   { "schema": 1,
@@ -15,7 +15,7 @@
  * responses on every build, by the current version of the checkers. A cached verdict would freeze
  * whatever the checker believed the day it ran — a bug fixed in the comparison would never reach a
  * paper whose entries are cached. A cached response is evidence: it cannot be made up, only
- * refetched. The precedent is `extract-ref-facts.mjs`'s `repro/refs-cache.json` ("the cache is
+ * refetched. The precedent is `extract-ref-facts.mjs`'s `repro/data/refs-cache.json` ("the cache is
  * evidence, not a second declaration").
  *
  * 🔴 COMMITTED, so CI and every other clone start warm: a build whose entries are all here makes no

package/src/domain/paper-layout.test.ts

@@ -0,0 +1,264 @@
+/**
+ * The paper folder's layout (`src/domain/paper-layout.ts`), judged on its root entries alone. Both
+ * halves: the scaffold `paperlint new` writes, and a folder holding every allowed entry, are clean; a
+ * stray file or folder at the root is reported once, by name, with where it belongs.
+ */
+import { describe, expect, it } from "vitest";
+import {
+  CURE_BY_KIND,
+  KNOWN_CURES,
+  NOTHING_DECLARED,
+  PAPER_LAYOUT_TREE,
+  ROOT_DIRS,
+  ROOT_FILES,
+  judgeLayout,
+  strayMessage,
+  type LayoutEntry,
+} from "./paper-layout.ts";
+
+const file = (name: string): LayoutEntry => ({ name, kind: "file" });
+const dir = (name: string): LayoutEntry => ({ name, kind: "dir" });
+
+describe("judgeLayout — silent", () => {
+  it("on the scaffold `paperlint new` writes", () => {
+    expect(
+      judgeLayout(
+        [file("PIPELINE-STATUS.md"), file("paper.tex"), file("paperlint.json")],
+        NOTHING_DECLARED,
+      ),
+    ).toEqual([]);
+  });
+});
+
+describe("judgeLayout — silent on the whole allowed set", () => {
+  it("on every allowed file and folder, the TeX inputs and the build's byproducts", () => {
+    const entries = [
+      ...[
+        "PIPELINE-STATUS.md",
+        "paper.tex",
+        "paperlint.json",
+        "README.md",
+        "CLAUDE.md",
+        "CLAIMS.md",
+        "NOTES.md",
+        "SUBMIT-CHECKLIST.md",
+        ".gitignore",
+        "paper.pdf",
+        "numbers.tex",
+        "refs.bib",
+        "acmart.cls",
+        "pbalance.sty",
+        "ACM-Reference-Format.bst",
+        "paper.aux",
+        "paper.log",
+        "paper.bbl",
+        "paper.blg",
+        "paper.out",
+        "paper.fls",
+        "paper.toc",
+        "paper.synctex.gz",
+        ".DS_Store",
+      ].map(file),
+      ...[
+        "_build",
+        "versions",
+        "reviews",
+        "siblings",
+        "research",
+        "repro",
+        "figures",
+        "sections",
+        "talk",
+        "submission",
+        "extra",
+      ].map(dir),
+    ];
+    expect(judgeLayout(entries, NOTHING_DECLARED)).toEqual([]);
+  });
+
+  it("on what the paper's settings name at its root: another PDF, another talk folder, its own preset", () => {
+    expect(
+      judgeLayout([file("main.pdf"), dir("video"), file("venue.jsonc")], {
+        roots: ["main.pdf", "video", "venue.jsonc"],
+      }),
+    ).toEqual([]);
+  });
+});
+
+describe("judgeLayout — reports", () => {
+  it("a known name with its one destination: the plan is a section of the status file", () => {
+    const [plan] = judgeLayout(
+      [file("paper.tex"), file("PLAN.md")],
+      NOTHING_DECLARED,
+    );
+    expect(plan?.name).toBe("PLAN.md");
+    expect(plan?.cure).toMatch(
+      /^a section of PIPELINE-STATUS\.md .*"Plan \/ now"/,
+    );
+  });
+
+  it.each([
+    ["DECISION-LOG.md", "file", /^research\//],
+    ["EMAILS.md", "file", /^submission\//],
+    ["data", "dir", /^repro\//],
+    ["artifact", "dir", /^repro\//],
+    [
+      "archive",
+      "dir",
+      /^versions\/ for frozen PDFs, submission\/ .*, extra\/ for the rest$/,
+    ],
+    [
+      "venue-corpus",
+      "dir",
+      /^<papers-root>\/venues\/<venue>\/, outside the paper folder/,
+    ],
+    ["plans", "dir", /^a section of PIPELINE-STATUS\.md/],
+    ["Plan.md", "file", /^a section of PIPELINE-STATUS\.md/],
+  ] as const)("%s (%s) goes to its destination", (name, kind, cure) => {
+    expect(judgeLayout([{ name, kind }], NOTHING_DECLARED)[0]?.cure).toMatch(
+      cure,
+    );
+  });
+
+  it("an unknown name gets the choice by what it is", () => {
+    expect(judgeLayout([dir("corpus")], NOTHING_DECLARED)).toEqual([
+      { name: "corpus/", kind: "dir", cure: CURE_BY_KIND },
+    ]);
+  });
+
+  it("a known file name used by a folder is not that file: the choice by kind", () => {
+    expect(judgeLayout([dir("PLAN.md")], NOTHING_DECLARED)[0]?.cure).toBe(
+      CURE_BY_KIND,
+    );
+  });
+});
+
+describe("judgeLayout — the build's byproducts", () => {
+  // What pdflatex, bibtex, makeindex, biber, glossaries, beamer and latexmk write next to paper.tex.
+  const byproducts = [
+    "aux",
+    "log",
+    "out",
+    "toc",
+    "lof",
+    "lot",
+    "loa",
+    "lol",
+    "bbl",
+    "blg",
+    "idx",
+    "ind",
+    "ilg",
+    "glo",
+    "gls",
+    "glg",
+    "nlo",
+    "nls",
+    "fls",
+    "fdb_latexmk",
+    "synctex.gz",
+    "run.xml",
+    "bcf",
+    "nav",
+    "snm",
+    "vrb",
+    "xdv",
+    "dvi",
+  ];
+
+  it("a root holding paper.idx, paper.ind, paper.ilg and the rest of the job's outputs reports nothing", () => {
+    expect(
+      judgeLayout(
+        byproducts.map((ext) => file(`paper.${ext}`)),
+        NOTHING_DECLARED,
+      ),
+    ).toEqual([]);
+  });
+
+  it("only under the paper's own job name: draft.idx is reported", () => {
+    expect(
+      judgeLayout([file("draft.idx"), file("paper.idx")], NOTHING_DECLARED).map(
+        (s) => s.name,
+      ),
+    ).toEqual(["draft.idx"]);
+  });
+
+  it("🔴 the .aux that \\include writes beside a root source: chapter.aux with chapter.tex is the build's; alone it is reported", () => {
+    expect(
+      judgeLayout(
+        [file("chapter.tex"), file("chapter.aux"), file("orphan.aux")],
+        NOTHING_DECLARED,
+      ).map((s) => s.name),
+    ).toEqual(["orphan.aux"]);
+  });
+});
+
+describe("judgeLayout — reports by name, exactly", () => {
+  it("a PDF other than the built one, a dotfile, another job's byproduct", () => {
+    expect(
+      judgeLayout(
+        [file("paper-2026-07-18.pdf"), file(".body-limit"), file("draft.aux")],
+        NOTHING_DECLARED,
+      ).map((s) => s.name),
+    ).toEqual(["paper-2026-07-18.pdf", ".body-limit", "draft.aux"]);
+  });
+
+  it("an allowed folder's name used by a file, and an allowed file's name used by a folder", () => {
+    expect(
+      judgeLayout([file("reviews"), dir("README.md")], NOTHING_DECLARED).map(
+        (s) => s.name,
+      ),
+    ).toEqual(["reviews", "README.md/"]);
+  });
+
+  it("names compared exactly: case matters", () => {
+    expect(
+      judgeLayout([dir("Reviews")], NOTHING_DECLARED).map((s) => s.name),
+    ).toEqual(["Reviews/"]);
+  });
+
+  it("each stray entry once, in the order given", () => {
+    expect(
+      judgeLayout(
+        [file("a.md"), file("paper.tex"), dir("data")],
+        NOTHING_DECLARED,
+      ).map((s) => s.name),
+    ).toEqual(["a.md", "data/"]);
+  });
+});
+
+describe("strayMessage — stands alone for a reader with no context", () => {
+  const [plan] = judgeLayout([file("PLAN.md")], NOTHING_DECLARED);
+  const text = plan === undefined ? "" : strayMessage(plan);
+
+  it("names the entry, where it goes, draws the whole layout, and links the rule's page", () => {
+    expect(text.split("\n")).toEqual([
+      `\`PLAN.md\` is at the root of a paper folder (the folder holding PIPELINE-STATUS.md), and that root holds only paperlint's layout. Where it goes: ${KNOWN_CURES[0]?.cure ?? ""}.`,
+      "The layout (extra/ takes anything and is never judged; the build's paper.* byproducts are never reported):",
+      ...PAPER_LAYOUT_TREE.split("\n"),
+      "Rule paper/allowed-files-only: https://github.com/zernie/paperlint/blob/main/docs/rules/paper/allowed-files-only.md",
+    ]);
+  });
+
+  it("the layout it draws holds every allowed root entry, repro/'s own layout inside", () => {
+    const lines = PAPER_LAYOUT_TREE.split("\n");
+    expect(lines[0]).toBe("<paper>/");
+    const drawn = new Set(
+      lines.map((l) =>
+        l
+          .replace(/^[│ ]*[├└]── /u, "")
+          .split(" ", 1)
+          .join(""),
+      ),
+    );
+    expect(
+      [...ROOT_FILES, ...ROOT_DIRS.map((d) => `${d}/`)].filter(
+        (name) => !drawn.has(name),
+      ),
+    ).toEqual([]);
+    expect(lines).toContain(
+      "│   └── <slug>-YYYY-MM-DD/         ← one folder per study or spike (<slug>-YYYY-MM for one that ran over weeks)",
+    );
+    expect(lines.at(-1)).toMatch(/^└── extra\/ +← anything; never judged$/);
+  });
+});