paperlint 9.0.0 → 10.0.0

package/src/repro-layout-rule.test.ts

@@ -0,0 +1,114 @@
+/**
+ * `repro/allowed-files-only` (`src/repro-layout-rule.ts`) on paper folders held in memory, run the way
+ * ESLint runs it: `create`, then `root`. Both halves: each misplaced entry at the top of `repro/` is
+ * reported once, on the first line of `PIPELINE-STATUS.md`; the layout, a paper with no `repro/`, and
+ * any file but the scorecard are not.
+ */
+import { describe, expect, it } from "vitest";
+import { memoryFiles, memoryListDir } from "./adapters/memory/index.ts";
+import { reproMessage, SCRIPT_CURE } from "./domain/repro-layout.ts";
+import {
+  REPRO_LAYOUT_RULE_LEVELS,
+  reproLayoutRules,
+} from "./repro-layout-rule.ts";
+
+const DIR = "/work/papers/p";
+const SCAFFOLD = {
+  [`${DIR}/PIPELINE-STATUS.md`]: "# status\n",
+  [`${DIR}/paper.tex`]: "\\documentclass{article}\n",
+};
+
+interface Reported {
+  readonly messageId: string;
+  readonly message: string;
+  readonly line: number;
+}
+
+/** The rule over the folder `tree` describes, reached through `file` (default the scorecard). */
+function lint(
+  tree: Readonly<Record<string, string>>,
+  file = `${DIR}/PIPELINE-STATUS.md`,
+): Reported[] {
+  const files = memoryFiles(tree);
+  const rule = reproLayoutRules({ files, listDir: memoryListDir(files) })[
+    "allowed-files-only"
+  ];
+  const out: Reported[] = [];
+  const visitor = rule.create({
+    filename: file,
+    sourceCode: { getLocFromIndex: () => ({ line: 1, column: 0 }) },
+    report: (d) => {
+      const template = rule.meta.messages[d.messageId] ?? "";
+      const message = Object.entries(d.data).reduce(
+        (m, [k, v]) => m.split(`{{${k}}}`).join(String(v)),
+        template,
+      );
+      out.push({ messageId: d.messageId, message, line: d.loc.start.line });
+    },
+  });
+  visitor.root?.();
+  return out;
+}
+
+describe("repro/allowed-files-only — reports", () => {
+  it("a loose script, once, on the first line, with the one text", () => {
+    expect(lint({ ...SCAFFOLD, [`${DIR}/repro/run.py`]: "x" })).toEqual([
+      {
+        messageId: "misplaced",
+        message: reproMessage({
+          path: "repro/run.py",
+          problem: "stray",
+          cure: SCRIPT_CURE,
+        }),
+        line: 1,
+      },
+    ]);
+  });
+
+  it("an undated folder and a study without a README.md, each once, in name order", () => {
+    expect(
+      lint({
+        ...SCAFFOLD,
+        [`${DIR}/repro/spike/x.py`]: "x",
+        [`${DIR}/repro/ablation-2026-10-12/run.py`]: "x",
+      }).map((r) => r.message.split(" ", 1).join("")),
+    ).toEqual(["`repro/ablation-2026-10-12/`", "`repro/spike/`"]);
+  });
+});
+
+describe("repro/allowed-files-only — silent", () => {
+  it("on the layout, whatever tools/, data/ and the studies hold", () => {
+    expect(
+      lint({
+        ...SCAFFOLD,
+        [`${DIR}/repro/README.md`]: "x",
+        [`${DIR}/repro/.gitignore`]: "x",
+        [`${DIR}/repro/tools/paper_numbers.py`]: "x",
+        [`${DIR}/repro/data/numbers.tsv`]: "x",
+        [`${DIR}/repro/data/references-cache.json`]: "{}",
+        [`${DIR}/repro/ablation-2026-10-12/README.md`]: "x",
+        [`${DIR}/repro/ablation-2026-10-12/loose.py`]: "x",
+        [`${DIR}/repro/human-labels-2026-10/README.md`]: "x",
+        [`${DIR}/repro/__pycache__/x.pyc`]: "x",
+      }),
+    ).toEqual([]);
+  });
+
+  it("on a paper with no repro/", () => {
+    expect(lint(SCAFFOLD)).toEqual([]);
+  });
+
+  it("on any file but PIPELINE-STATUS.md", () => {
+    expect(
+      lint({ ...SCAFFOLD, [`${DIR}/repro/run.py`]: "x" }, `${DIR}/paper.tex`),
+    ).toEqual([]);
+  });
+});
+
+describe("repro/allowed-files-only — level", () => {
+  it("is an error from the start", () => {
+    expect(REPRO_LAYOUT_RULE_LEVELS).toEqual({
+      "repro/allowed-files-only": "error",
+    });
+  });
+});

package/src/repro-layout-rule.ts

@@ -0,0 +1,121 @@
+/**
+ * `repro/allowed-files-only` — the top of a paper's `repro/` holds an index, the shared `tools/` and
+ * `data/`, and one dated folder per study, each with a `README.md`.
+ *
+ * What may stand there, and why, is `src/domain/repro-layout.ts` and docs/rules/repro/allowed-files-only.md.
+ * This file lists the folder and reports.
+ *
+ * ── WHY A RULE OF ITS OWN, NOT MORE OF `paper/allowed-files-only` ─────────────────────
+ * Each entry is judged by exactly one rule: `paper/allowed-files-only` judges the paper folder's root,
+ * where `repro/` is allowed, and this rule judges what is inside `repro/`. Neither reports an entry
+ * the other does, so a stray entry gets one message. A rule of its own also has its own page and its
+ * own switch: a paper whose `repro/` predates the layout can turn this one off and keep its root
+ * judged.
+ *
+ * ── WHICH FILE IT REPORTS ON ─────────────────────────────────────────────────────
+ * `PIPELINE-STATUS.md`, first line, like `paper/allowed-files-only`: every paper has it, and `repro/` may
+ * have no file ESLint lints at all.
+ */
+import { basename, dirname, join } from "node:path";
+import { callerPath } from "./caller-path.ts";
+import {
+  README,
+  REPRO_DIR,
+  judgeRepro,
+  reproMessage,
+  type ReproEntry,
+} from "./domain/repro-layout.ts";
+import type {
+  FolderRuleContext,
+  FolderRuleModule,
+} from "./folder-venue-rule.ts";
+import type { FolderLayoutDeps } from "./folder-layout-rule.ts";
+import type { Files } from "./ports/files.ts";
+import type { LayoutEntry } from "./domain/paper-layout.ts";
+import { rulePageUrl } from "./venue-rules.ts";
+
+const STATUS_FILE = "PIPELINE-STATUS.md";
+
+/** `entries` of `<dir>/repro/`, each folder with whether it holds a README.md. */
+const withReadme = (
+  dir: string,
+  entries: readonly LayoutEntry[],
+  files: Files,
+): readonly ReproEntry[] =>
+  entries.map((e) => ({
+    ...e,
+    hasReadme:
+      e.kind === "dir" &&
+      files.isFile(callerPath(join(dir, REPRO_DIR, e.name, README))),
+  }));
+
+/**
+ * The text of each finding among `entries` at the top of the paper folder `dir`'s `repro/` — THE one
+ * function behind both the rule and the `paper-folder-layout` hook, so the two cannot disagree.
+ */
+export const reproTexts = (
+  dir: string,
+  entries: readonly LayoutEntry[],
+  files: Files,
+): readonly string[] =>
+  judgeRepro(withReadme(dir, entries, files)).map(reproMessage);
+
+/** The entries at the top of `<dir>/repro/`, each a file or a folder; none without a `repro/`. */
+export const reproEntriesOf = (
+  dir: string,
+  deps: FolderLayoutDeps,
+): readonly LayoutEntry[] =>
+  [...deps.listDir(callerPath(join(dir, REPRO_DIR)))].sort().map((name) => ({
+    name,
+    kind: deps.files.isFile(callerPath(join(dir, REPRO_DIR, name)))
+      ? "file"
+      : "dir",
+  }));
+
+const META: FolderRuleModule["meta"] = {
+  type: "suggestion",
+  docs: {
+    description:
+      "the top of a paper's repro/ holds README.md, .gitignore, tools/, data/ and one <slug>-YYYY-MM-DD folder per study, each with a README.md",
+    url: rulePageUrl("repro/allowed-files-only"),
+  },
+  schema: [],
+  messages: {
+    // The whole text is `reproMessage` (src/domain/repro-layout.ts), the one the hook sends too.
+    misplaced: "{{text}}",
+  },
+};
+
+/** The rule, reading the folder through `deps`. */
+export function reproLayoutRules(
+  deps: FolderLayoutDeps,
+): Readonly<Record<"allowed-files-only", FolderRuleModule>> {
+  return {
+    "allowed-files-only": {
+      meta: META,
+      create(context: FolderRuleContext) {
+        if (basename(context.filename) !== STATUS_FILE) return {};
+        return {
+          root() {
+            const dir = dirname(context.filename);
+            const at = context.sourceCode.getLocFromIndex(0);
+            reproTexts(dir, reproEntriesOf(dir, deps), deps.files).forEach(
+              (text) => {
+                context.report({
+                  loc: { start: at, end: at },
+                  messageId: "misplaced",
+                  data: { text },
+                });
+              },
+            );
+          },
+        };
+      },
+    },
+  };
+}
+
+/** The level it is on at in paperlint's own config, for every paper's `PIPELINE-STATUS.md`. */
+export const REPRO_LAYOUT_RULE_LEVELS: Readonly<
+  Record<"repro/allowed-files-only", "error">
+> = { "repro/allowed-files-only": "error" };

package/src/rule-cases.test.ts

@@ -39,6 +39,14 @@ const paper = (
   ...extra,
 });
 
+/** `study/declare-sample` is off by default; a paper turns it on in its `paperlint.json`. */
+const DECLARE_SAMPLE_ON: Readonly<Record<string, string>> = {
+  [`${P}/paperlint.json`]: JSON.stringify({
+    extends: null,
+    rules: { "study/declare-sample": "error" },
+  }),
+};
+
 // ── the venues: presets of the tree's own, never the shipped ones ──────────────────────────────
 //
 // A case judges a RULE, so every number it is sized against is written here, beside the facts and
@@ -693,6 +701,78 @@ const CASES: Readonly<Record<string, RuleCases>> = {
       ...onBlindConf("papers/blindconf-2026"),
     },
   },
+  // A plan beside the paper: the root holds only paperlint's own files and folders.
+  "paper/allowed-files-only": {
+    reports: {
+      tree: paper(tex("x"), { [`${P}/PLAN.md`]: "# plan\n" }),
+      file: `${P}/PIPELINE-STATUS.md`,
+      severity: 2,
+      line: 1,
+    },
+    // The same material where the layout puts it.
+    silent: paper(tex("x"), {
+      [`${P}/research/plan.md`]: "# plan\n",
+      [`${P}/extra/PLAN.md`]: "# plan\n",
+    }),
+  },
+  // A loose script at the top of repro/: it belongs in repro/tools/.
+  "repro/allowed-files-only": {
+    reports: {
+      tree: paper(tex("x"), { [`${P}/repro/run.py`]: "print(1)\n" }),
+      file: `${P}/PIPELINE-STATUS.md`,
+      severity: 2,
+      line: 1,
+    },
+    // The same script where the layout puts it, and a dated study with its README.md.
+    silent: paper(tex("x"), {
+      [`${P}/repro/README.md`]: "# repro\n",
+      [`${P}/repro/tools/run.py`]: "print(1)\n",
+      [`${P}/repro/ablation-2026-10-12/README.md`]: "# ablation\n",
+    }),
+  },
+  // A study's prereg.json that declares none of population, strata, screens, coverage, author_check.
+  // Off by default: the paper turns it on, as both trees do.
+  "study/declare-sample": {
+    reports: {
+      tree: paper(tex("x"), {
+        ...DECLARE_SAMPLE_ON,
+        [`${P}/repro/README.md`]: "# repro\n",
+        [`${P}/repro/draw-2026-10-12/README.md`]: "# draw\n",
+        [`${P}/repro/draw-2026-10-12/prereg.json`]: JSON.stringify({
+          hypotheses: ["H1"],
+        }),
+      }),
+      file: `${P}/PIPELINE-STATUS.md`,
+      severity: 2,
+      line: 1,
+    },
+    // The same study, declaring them.
+    silent: paper(tex("x"), {
+      ...DECLARE_SAMPLE_ON,
+      [`${P}/repro/README.md`]: "# repro\n",
+      [`${P}/repro/draw-2026-10-12/README.md`]: "# draw\n",
+      [`${P}/repro/draw-2026-10-12/prereg.json`]: JSON.stringify({
+        hypotheses: ["H1"],
+        population: {
+          about: "rules in instruction files",
+          source: "a census, 2026-07-28",
+          size: 4210,
+        },
+        strata: { by: "rule type", values: ["crisp", "vague"] },
+        screens: [
+          { name: "fits one excerpt", removed: { crisp: 10, vague: 300 } },
+        ],
+        coverage: { share: 0.3, unreachable: ["vague"] },
+        author_check: {
+          who: "first author",
+          when: "2026-10-12",
+          units_seen: 12,
+          units_drawn: 12,
+          verdict: "representative",
+        },
+      }),
+    }),
+  },
   // EMNLP, a shipped venue's name (REALM's conference), in a BlindConf paper's text.
   "tex/venue-leftover": {
     reports: {
@@ -944,6 +1024,24 @@ describe("every registered rule has cases, and every case names a registered rul
   });
 });
 
+describe("study/declare-sample is off by default", () => {
+  it("is silent on an empty prereg.json until the paper turns it on", async () => {
+    const study = {
+      [`${P}/repro/README.md`]: "# repro\n",
+      [`${P}/repro/draw-2026-10-12/README.md`]: "# draw\n",
+      [`${P}/repro/draw-2026-10-12/prereg.json`]: "{}",
+    };
+    const ids = async (tree: Record<string, string>) =>
+      (await lintTree(tree)).map((m) => m.ruleId);
+    expect(await ids(paper(tex("x"), study))).not.toContain(
+      "study/declare-sample",
+    );
+    expect(
+      await ids(paper(tex("x"), { ...study, ...DECLARE_SAMPLE_ON })),
+    ).toContain("study/declare-sample");
+  });
+});
+
 /**
  * A case lints its tree through the whole CLI: a body long enough for a rate to be judged (2 000
  * words and more) takes seconds under coverage, on a machine running every suite at once.

package/src/tex-requirements.ts

@@ -17,7 +17,7 @@
  * of every violation, it is never read as "no packages".
  *
  * Where the profiles live is answered by `presetsDir()` in `package-dirs.ts` — the one module
- * allowed to know where this package's data is installed (rule 10).
+ * allowed to know where this package's data is installed (root CLAUDE.md).
  */
 // eslint-disable-next-line boundaries/dependencies -- legacy I/O, moves behind a port in #76
 import { readFileSync, readdirSync } from "node:fs";

package/src/toolchain.ts

@@ -3,7 +3,7 @@
  * declare, into paperlint's own cache, and banal (the page-geometry script HotCRP runs) at its pinned
  * commit (`adapters/banal/`). `paperlint build` offers the TeX Live install on a terminal.
  *
- * 🔴 WHY paperlint INSTALLS TeX AT ALL (rule 11). "Install TeX Live yourself" was a manual step with a
+ * 🔴 WHY paperlint INSTALLS TeX AT ALL (root CLAUDE.md: installing must be smooth). "Install TeX Live yourself" was a manual step with a
  * trap in it: the distribution packages cost 2.1 GB, and a smaller hand-picked set silently typeset
  * acmart papers in Computer Modern. The engine decision (2026-09-24) is TeX Live's pdflatex,
  * installed the way Playwright installs browsers: one command, a cache directory, idempotent.

package/templates/paper/PIPELINE-STATUS.md

@@ -13,7 +13,41 @@ Updated: <ISO>
 **Readiness verdict:** <one line — submit-ready? if not, the WORST failing gate first. Any failing
 gate caps "ready"; an accept probability alone is not a verdict.>
 
-**Gates at a glance (worst first — mark any failing gate ✗):** readability(persona stalls) <density/verdict> · structure(tighten-paper) <verdict> · claims-honest(claims) <clean?> · defects(panel) <accept-prob/decision> · writing <NN/60> · content(venue bar) <run?/levers>
+**Gates at a glance (worst first — mark any failing gate ✗):** readability(persona stalls) <density/verdict> · structure(tighten-paper) <verdict> · claims-honest(claims) <clean?> · defects(panel) <accept-prob/decision> · writing <NN/60> · content(strong-accept scorecard) <run?/mode>
+
+## Plan / now
+
+The paper's live plan: this file is the paper's one live-state file, so the plan lives here, not in a
+`PLAN.md` beside it (`paper/allowed-files-only` reports one). Rewrite this section as the plan changes; a
+decision's history goes to `research/` as a dated record.
+
+- **Now (<ISO date>):** <what is being worked on, and the next step>
+- **Decisions in force:** <the decision — who made it, ISO date, link to the record>
+- **Schedule:** <ISO date — milestone, in the author's own zone>
+
+## Strong-accept scorecard (M1–M10)
+
+Filled by `study-accepted-papers`: mode C scores every row, mode D checks M2 and M4 again. What each
+mechanism is, and what it is not, is that skill's `references/mechanisms.md`. The verdicts live only
+here; the dated report in `reviews/` keeps the reasoning and points here.
+
+Status: `pass` · `partial` · `fail` · `—` (not scored). A `fail` names an owner and either a plan or
+`accept ceiling: <why>`.
+
+| #   | mechanism                                       | status | evidence (file:line) | owner | plan or accept ceiling |
+| --- | ----------------------------------------------- | ------ | -------------------- | ----- | ---------------------- |
+| M1  | a non-model oracle under the headline           | —      | —                    | —     | —                      |
+| M2  | the claim is aimed at a belief stated on record | —      | —                    | —     | —                      |
+| M3  | the construct is the claim                      | —      | —                    | —     | —                      |
+| M4  | the denominator in the claim sentence, no drift | —      | —                    | —     | —                      |
+| M5  | a negative or "X alone" claim shape             | —      | —                    | —     | —                      |
+| M6  | the generalised-over factor is a column         | —      | —                    | —     | —                      |
+| M7  | the phenomenon measured directly                | —      | —                    | —     | —                      |
+| M8  | a reusable thing the field pays for once        | —      | —                    | —     | —                      |
+| M9  | relevance to every reviewer on the PC           | —      | —                    | —     | —                      |
+| M10 | where the paper's own result loses              | —      | —                    | —     | —                      |
+
+## Stages
 
 ### SETUP
 
@@ -22,18 +56,18 @@ gate caps "ready"; an accept probability alone is not a verdict.>
 | idea       | Validate idea                     | research-ideate       | ☐      | —    | —                                                                                                 | —         |
 | priorwork  | Map competitors                   | map-prior-work        | ☐      | —    | —                                                                                                 | siblings/ |
 | venue      | Pick venue                        | find-venue            | ☐      | —    | —                                                                                                 | —         |
-| venuebar   | Venue bar / levers                | study-accepted-papers | ☐      | —    | —                                                                                                 | —         |
+| venuebar   | What the venue rewards            | study-accepted-papers | ☐      | —    | —                                                                                                 | —         |
 | **access** | 🔴 **Can you physically submit?** | plan-paper-timeline   | ☐      | —    | account · profile ACTIVE since <ISO> · portal reachable · form fields known · artifact host known | —         |
 | schedule   | Schedule + calendar               | plan-paper-timeline   | ☐      | —    | —                                                                                                 | —         |
 | **frame**  | **Claim stated before the runs**  | argument-arc (frame)  | ☐      | —    | one paragraph: what will this paper claim?                                                        | —         |
 
 ### LOOP
 
-| id    | Work             | Skill           | Status | Date | Result | Open |
-| ----- | ---------------- | --------------- | ------ | ---- | ------ | ---- |
-| study | Study + artifact | build-benchmark | ☐      | —    | —      | —    |
-| draft | Draft            | draft-paper     | ☐      | —    | —      | —    |
-| arc   | Argument arc     | argument-arc    | ☐      | —    | —      | —    |
+| id    | Work             | Skill           | Status | Date | Result | Open   |
+| ----- | ---------------- | --------------- | ------ | ---- | ------ | ------ |
+| study | Study + artifact | build-benchmark | ☐      | —    | —      | repro/ |
+| draft | Draft            | draft-paper     | ☐      | —    | —      | —      |
+| arc   | Argument arc     | argument-arc    | ☐      | —    | —      | —      |
 
 ### CONTINUOUS