paperlint 7.2.0 → 9.0.0

package/src/new-paper.harness.mjs

@@ -36,7 +36,6 @@ const ROOT = dirname(HERE);
 const {
   newPaper,
   nameProblem,
-  wantedFiles,
   PACKAGE_TEMPLATES,
   OVERRIDE_DIR,
   STATUS_FILE,
@@ -63,7 +62,7 @@ async function lint(dir) {
 
 try {
   // ── the templates are FILES in the package, one per required file ──────────────────────
-  for (const f of [STATUS_FILE, SOURCE_FILE.tex, SOURCE_FILE.md])
+  for (const f of [STATUS_FILE, SOURCE_FILE])
     check(
       `the package ships templates/paper/${f}`,
       existsSync(join(PACKAGE_TEMPLATES, f)),
@@ -85,13 +84,13 @@ try {
     );
   check(
     "a refused name creates nothing",
-    newPaper(work, "Bad", "tex", { venues: [] }).ok === false &&
+    newPaper(work, "Bad", { venues: [] }).ok === false &&
       !existsSync(join(work, "Bad")),
   );
 
   // ── a fresh LaTeX paper ─────────────────────────────────────────────────────────────
   const papers = join(work, "papers");
-  const r = newPaper(papers, "demo", "tex", { venues: [] });
+  const r = newPaper(papers, "demo", { venues: [] });
   check(
     "a fresh folder gets the scorecard, a .tex source and paperlint.json, all from the package",
     r.ok &&
@@ -113,10 +112,11 @@ try {
   );
   const l = await lint(join(papers, "demo"));
   check(
-    "🔴 `paperlint lint` passes the scaffold — exit 0, not a missing-file error — with the one warning that no venue is chosen yet",
+    "🔴 `paperlint lint` passes the scaffold — exit 0, not a missing-file error — with two warnings: no venue is chosen yet, and the paper is not built",
     l.code === 0 &&
       /names no venue preset yet/.test(l.text) &&
-      /1 problem \(0 errors, 1 warning\)/.test(l.text),
+      /paper\/sources-fresh/.test(l.text) &&
+      /2 problems \(0 errors, 2 warnings\)/.test(l.text),
   );
 
   // What the status hook reads on every paper edit: the verdict line.
@@ -129,36 +129,18 @@ try {
 
   // ── never overwrite; on an existing folder only the missing files ─────────────────────
   writeFileSync(join(papers, "demo", STATUS_FILE), "mine\n");
-  const again = newPaper(papers, "demo", "md", { venues: [] });
+  const again = newPaper(papers, "demo", { venues: [] });
   check(
-    "🔴 a second run overwrites nothing and adds no second source",
+    "🔴 a second run overwrites nothing",
     again.ok &&
       !again.fresh &&
       read(papers, "demo", STATUS_FILE) === "mine\n" &&
-      !existsSync(join(papers, "demo", "paper.md")) &&
       again.files.every((f) => f.status === "kept"),
   );
-  mkdirSync(join(papers, "old"), { recursive: true });
-  writeFileSync(join(papers, "old", "paper.md"), "# Old\n");
-  const migrated = newPaper(papers, "old", "tex", { venues: [] });
-  check(
-    "an old folder with only paper.md gets ONLY the scorecard — that is the migration",
-    migrated.ok &&
-      existsSync(join(papers, "old", STATUS_FILE)) &&
-      !existsSync(join(papers, "old", "paper.tex")) &&
-      read(papers, "old", "paper.md") === "# Old\n",
-  );
-  check(
-    "wantedFiles asks for a source only when neither format is there",
-    wantedFiles(join(papers, "old"), "tex").join() ===
-      `${STATUS_FILE},paperlint.json` &&
-      wantedFiles(join(papers, "nowhere"), "md").join() ===
-        `${STATUS_FILE},paper.md,paperlint.json`,
-  );
   writeFileSync(join(papers, "afile"), "x");
   check(
     "a name taken by a FILE is refused, not written through",
-    newPaper(papers, "afile", "tex", { venues: [] }).ok === false,
+    newPaper(papers, "afile", { venues: [] }).ok === false,
   );
 
   // ── the project's template wins, file by file ─────────────────────────────────────────
@@ -167,7 +149,7 @@ try {
     join(papers, OVERRIDE_DIR, STATUS_FILE),
     "---\n---\n# House scorecard for {{name}}\n",
   );
-  const own = newPaper(papers, "house", "md", { venues: [] });
+  const own = newPaper(papers, "house", { venues: [] });
   // Guards: the override slot — `fromTemplate` in new-paper.ts reads `<papers>/.template/<file>`
   // before the package's copy. Replace that lookup with the package's alone and this goes red.
   check(
@@ -176,11 +158,11 @@ try {
       read(papers, "house", STATUS_FILE) ===
         "---\n---\n# House scorecard for house\n" &&
       own.files.find((f) => f.file === STATUS_FILE)?.from === "project" &&
-      own.files.find((f) => f.file === "paper.md")?.from === "package",
+      own.files.find((f) => f.file === SOURCE_FILE)?.from === "package",
   );
 
   // ── a missing template is a broken install, not an empty file ─────────────────────────
-  const broken = newPaper(join(work, "b"), "x", "tex", {
+  const broken = newPaper(join(work, "b"), "x", {
     venues: [],
     packageTemplates: join(work, "no-such-dir"),
   });

package/src/new-paper.test.ts

@@ -41,7 +41,7 @@ const settingsOf = (dir: string) =>
 describe("paperlint new — paperlint.json", () => {
   it("is always written, from the package template: no venue chosen yet, and valid", () => {
     const papers = join(tmp(), "papers");
-    const r = newPaper(papers, "demo", "tex", { venues: [] });
+    const r = newPaper(papers, "demo", { venues: [] });
     expect(r.ok && r.files.find((f) => f.file === "paperlint.json")).toEqual({
       file: "paperlint.json",
       status: "created",
@@ -72,7 +72,7 @@ describe("paperlint new — paperlint.json", () => {
       join(papers, OVERRIDE_DIR, "paperlint.json"),
       '{ "extends": "paperlint:aisec", "kind": "research" }\n',
     );
-    const r = newPaper(papers, "house", "tex", { venues: [] });
+    const r = newPaper(papers, "house", { venues: [] });
     expect(r.ok && r.files.find((f) => f.file === "paperlint.json")?.from).toBe(
       "project",
     );
@@ -89,7 +89,7 @@ describe("paperlint new — paperlint.json", () => {
       join(papers, "p", "paperlint.json"),
       '{"extends":"paperlint:aisec"}',
     );
-    const r = newPaper(papers, "p", "tex", { venues: [] });
+    const r = newPaper(papers, "p", { venues: [] });
     expect(
       r.ok && r.files.find((f) => f.file === "paperlint.json")?.status,
     ).toBe("kept");
@@ -106,7 +106,7 @@ describe("paperlint lint — a paper with no venue preset chosen", () => {
       join(root, "package.json"),
       JSON.stringify({ name: "c", private: true }),
     );
-    newPaper(join(root, "papers"), "demo", "tex", { venues: [] });
+    newPaper(join(root, "papers"), "demo", { venues: [] });
     if (extendsValue !== null)
       writeFileSync(
         join(root, "papers", "demo", "paperlint.json"),
@@ -122,10 +122,13 @@ describe("paperlint lint — a paper with no venue preset chosen", () => {
     return { code, messages };
   }
 
-  it("gets exactly one warning naming the file to set, and exits 0", async () => {
+  it("gets the warning naming the file to set, besides the one that it is not built, and exits 0", async () => {
     const { code, messages } = await lintNew(null);
     expect(code).toBe(0);
-    expect(messages).toHaveLength(1);
+    expect(messages.map((m) => m.ruleId)).toEqual([
+      "pdf/measured",
+      "paper/sources-fresh",
+    ]);
     expect(messages[0]?.ruleId).toBe("pdf/measured");
     expect(messages[0]?.severity).toBe(1);
     expect(messages[0]?.message).toMatch(/names no venue preset yet/);
@@ -254,10 +257,11 @@ describe("paperlint new --venue msr", () => {
       log: (s: string) => out.push(s),
       err: () => {},
     });
-    // Guards: what remains is the reminder that the PDF is not built yet — a warning, not a finding
-    // about the paper.
-    expect(out.join("\n")).toMatch(/\(0 errors, 1 warning\)/);
+    // Guards: what remains is the reminder that the paper is not built yet — two warnings, not a
+    // finding about the paper: no PDF measured, no record of what TeX read.
+    expect(out.join("\n")).toMatch(/\(0 errors, 2 warnings\)/);
     expect(out.join("\n")).toMatch(/pdf\/measured/);
+    expect(out.join("\n")).toMatch(/paper\/sources-fresh/);
     expect(code).toBe(0);
   });
 });
@@ -488,7 +492,7 @@ describe("a project's own template", () => {
     mkdirSync(join(papers, OVERRIDE_DIR), { recursive: true });
     const src = join(papers, OVERRIDE_DIR, "paperlint.json");
     writeFileSync(src, '{\n  // our house venue\n  "extends": null\n}\n');
-    const r = newPaper(papers, "p", "tex", {
+    const r = newPaper(papers, "p", {
       venues: [],
       venue: { extends: "paperlint:aisec", kind: null },
     });
@@ -504,7 +508,7 @@ describe("a project's own template", () => {
     mkdirSync(join(papers, OVERRIDE_DIR), { recursive: true });
     writeFileSync(join(papers, OVERRIDE_DIR, "paperlint.json"), "{}\n");
     const lines = reportNewPaper(
-      newPaper(papers, "p", "tex", { venues: [] }),
+      newPaper(papers, "p", { venues: [] }),
       (p) => p,
     );
     expect(lines).toContain(

package/src/new-paper.ts

@@ -8,8 +8,7 @@
  * Every rule below is taken from a tool that already solved it (docs/prior-art/paper-folder-scaffolding.md):
  *   - the template is a FILE with a lookup order — the project's `<papers>/.template/<file>` first,
  *     the package's `templates/paper/<file>` second (Hugo's archetypes);
- *   - it NEVER overwrites: on an existing folder it adds only the missing required files, which is
- *     also the migration for an old folder that has only `paper.md` (`cargo init`);
+ *   - it NEVER overwrites: on an existing folder it adds only the missing required files (`cargo init`);
  *   - the name is validated, because it becomes a path and, through the hooks, a shell argument.
  *
  * The only substitution is `{{name}}` → the folder name. Nothing else in a template is touched.
@@ -33,10 +32,6 @@ import {
   type NamedVenue,
 } from "./domain/venue-name.ts";
 
-export type PaperFormat = "tex" | "md";
-export const FORMATS: readonly PaperFormat[] = ["tex", "md"];
-export const DEFAULT_FORMAT: PaperFormat = "tex";
-
 /** The package's default templates. Read from disk, so they ship in the tarball (`files`). */
 export const PACKAGE_TEMPLATES = fileURLToPath(
   new URL("../templates/paper/", import.meta.url),
@@ -50,17 +45,12 @@ export const PACKAGE_TEMPLATES = fileURLToPath(
 export const OVERRIDE_DIR = ".template";
 
 export const STATUS_FILE = "PIPELINE-STATUS.md";
-export const SOURCE_FILE: Readonly<Record<PaperFormat, string>> = {
-  tex: "paper.tex",
-  md: "paper.md",
-};
+/** A paper's source: LaTeX, one file at the paper's root. */
+export const SOURCE_FILE = "paper.tex";
 
 /** The flag that lets `paperlint new` create a folder whose name names a venue. */
 export const ALLOW_VENUE_NAME = "--allow-venue-name";
 
-export const isFormat = (v: unknown): v is PaperFormat =>
-  FORMATS.some((f) => f === v);
-
 /**
  * Why a name is refused, or null. `[a-z0-9._-]+` is the charset; a LEADING dot is refused on top
  * of it, because discovery skips dot-directories — a paper named `.x` would be created and then
@@ -109,20 +99,12 @@ export type NewPaperResult =
     }
   | { readonly ok: false; readonly reason: string };
 
-/**
- * The files a paper folder must end up with: the scorecard, a source in `format` — unless it
- * already has a source in EITHER format, in which case that one stands — and `paperlint.json`.
- */
-export function wantedFiles(dir: string, format: PaperFormat): string[] {
-  return [...scorecardAndSource(dir, format), CONFIG_FILE];
-}
-
-function scorecardAndSource(dir: string, format: PaperFormat): string[] {
-  const hasSource = Object.values(SOURCE_FILE).some((f) =>
-    existsSync(join(dir, f)),
-  );
-  return hasSource ? [STATUS_FILE] : [STATUS_FILE, SOURCE_FILE[format]];
-}
+/** The files a paper folder must end up with: the scorecard, the source and `paperlint.json`. */
+export const WANTED_FILES: readonly string[] = [
+  STATUS_FILE,
+  SOURCE_FILE,
+  CONFIG_FILE,
+];
 
 /** The venue `paperlint new --venue` chose: what goes into the new paper's `paperlint.json`. */
 export interface VenueSetting {
@@ -195,7 +177,7 @@ function fromTemplate(
     return { ok: false, reason: `no template for ${file}: ${src} is missing` };
   const text = readFileSync(src, "utf8").split("{{name}}").join(name);
   const setClass = venue?.setClass ?? null;
-  if (file === SOURCE_FILE.tex && setClass !== null)
+  if (file === SOURCE_FILE && setClass !== null)
     return { ok: true, value: { file, text: setClass(text), from } };
   if (file !== CONFIG_FILE || venue === null)
     return { ok: true, value: { file, text, from } };
@@ -217,7 +199,6 @@ export interface NewPaperOptions {
 export function newPaper(
   papersRoot: string,
   name: string,
-  format: PaperFormat,
   opts: NewPaperOptions,
 ): NewPaperResult {
   const { packageTemplates = PACKAGE_TEMPLATES, venue = null } = opts;
@@ -230,7 +211,7 @@ export function newPaper(
 
   const files: FileOutcome[] = [];
   const toWrite: Planned[] = [];
-  for (const file of wantedFiles(dir, format)) {
+  for (const file of WANTED_FILES) {
     if (existsSync(join(dir, file))) {
       files.push({ file, status: "kept" });
       continue;

package/src/package-dirs.ts

@@ -6,8 +6,9 @@
  *   presets/       the venue presets (`paperlint:<name>`) and their JSON Schema
  *   presets/tex/   the LaTeX inputs `paperlint build` puts on TEXINPUTS
  *
- * `texSearchPath` is where an `\input` is looked for, in order. The build hands it to TeX and the
- * lint rules read includes through it, so the two cannot disagree about which file a paper means.
+ * `texSearchPath` is where an `\input` is looked for, in order. The build hands it to TeX; lint does
+ * not search for an include at all — it reads the files TeX read, from the build's record
+ * (docs/design/paper-sources.md §1).
  */
 import { fileURLToPath } from "node:url";
 

package/src/paper-files.test.ts

@@ -20,6 +20,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
 import { buildConfig, eslintConfig, run } from "./cli.ts";
+import { texLanguage } from "#eslint-rules/latex-language";
 import {
   narrowToOwners,
   ownedPatterns,
@@ -247,7 +248,7 @@ describe("`rules` blocks — where the rule lands", () => {
               },
             ],
           },
-          null,
+          texLanguage,
         ),
       ),
     });
@@ -257,9 +258,9 @@ describe("`rules` blocks — where the rule lands", () => {
     const status = await on("papers/a/PIPELINE-STATUS.md");
     expect(status["paper/source"]).toEqual([1]);
     expect(status["paper/section-word"]).toBeUndefined();
-    const draft = await on("papers/a/paper.md");
-    expect(draft["paper/section-word"]).toEqual([0]);
-    expect(draft["paper/source"]).toBeUndefined();
+    const source = await on("papers/a/paper.tex");
+    expect(source["paper/section-word"]).toEqual([0]);
+    expect(source["paper/source"]).toBeUndefined();
   });
 });
 

package/src/paper-files.ts

@@ -1,8 +1,8 @@
 /**
  * THE FILES PAPERLINT OWNS — read off its own config, and made the only thing ESLint may reach.
  *
- * paperlint's blocks name the files they lint (`PIPELINE-STATUS.md`, `paper.md`, `paper.tex`,
- * `reviews/*.md`, …). That list is the whole scope of `paperlint lint`, and this module turns it
+ * paperlint's blocks name the files they lint (`PIPELINE-STATUS.md`, `paper.tex`, `reviews/*.md`,
+ * …). That list is the whole scope of `paperlint lint`, and this module turns it
  * into two things ESLint understands:
  *
  * 1. **A global ignore of everything else** (`scopeToOwned`). Handing ESLint a directory is not
@@ -17,7 +17,7 @@
  * 2. **Each rule scoped to the files it was written for** (`ruleOwners` + `narrowToOwners`).
  *    One plugin NAME is bound to different plugin objects in different blocks: `paper` holds
  *    `stages`/`source`/`author-list` beside `PIPELINE-STATUS.md` and `typography` beside
- *    `paper.md`/`paper.tex`. So a consumer block that named `paper/source`
+ *    `paper.tex`. So a consumer block that named `paper/source`
  *    for every file under the papers directory reached `paper.tex`, where `paper` has no `source`
  *    — and ESLint threw `Could not find "source" in plugin "paper"` from inside `lintFiles`,
  *    after paperlint's own validation had (correctly) accepted the id. A block is therefore split
@@ -36,7 +36,7 @@
  * - a global-ignore pattern that matches a DIRECTORY hides everything inside it, so directories
  *   must be un-ignored (`!` + a pattern ending in a slash) before owned files can be;
  * - that un-ignores `node_modules/` and `.git/` too — ESLint's own defaults — so they are
- *   re-ignored after, or a `paper.md` inside a dependency would be linted;
+ *   re-ignored after, or a `paper.tex` inside a dependency would be linted;
  * - later global-ignore patterns win, across blocks, in config order;
  * - `files: [["a", "b"]]` matches a file only when BOTH patterns match.
  */

package/src/paper-includes.test.ts

@@ -1,9 +1,11 @@
 /**
  * `paperlint lint` over a paper whose body is in other files: the rules over ESLint's LaTeX text read
- * every file `paper.tex` includes from its document body, report at that file's own path and line,
- * and fix that file. What a rule decides for the whole paper — the majority reference form and
- * whether the build is in review mode — it decides over all of the paper's files, not over the one
- * it is reporting in.
+ * every body file the last build's record lists (`_build/sources.json`: the files TeX read after
+ * `\\begin{document}`), report at that file's own path and line, and fix that file. A paper with no
+ * record, or one it has outgrown, is `paper.tex` alone and `paper/sources-fresh` says the rest went
+ * unlinted. What a rule decides for the whole paper — the majority reference form and whether the
+ * build is in review mode — it decides over all of the paper's files, not over the one it is
+ * reporting in.
  */
 import {
   mkdirSync,
@@ -16,8 +18,13 @@ import {
 import { tmpdir } from "node:os";
 import { join, relative } from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
+import { memoryFiles } from "./adapters/memory/index.ts";
+import { absolutePath } from "./domain/paths.ts";
+import { sourcesCodec } from "./adapters/sources-record/index.ts";
 import { run } from "./cli.ts";
+import { includeBlocks, paperBodies } from "./paper-includes.ts";
 import { lintReport } from "../test/lint-report.ts";
+import { builtFixture, recordedTree } from "../test/recorded-fixture.ts";
 
 const dirs: string[] = [];
 afterEach(() => {
@@ -29,7 +36,21 @@ const doc = (cls: string, preamble: string, body: string): string =>
 
 const INTRO = "See §3 and p < .05.\nAs Fig.~\\ref{f3} shows.\n";
 
-function project(files: Record<string, string>): string {
+/** What TeX read of the paper `project` makes, in the order it read it. */
+const READ = [
+  { path: "paper.tex", role: "body" },
+  { path: "macros.tex", role: "preamble" },
+  { path: "sections/intro.tex", role: "body" },
+] as const;
+
+/**
+ * A project with one paper, `papers/a`, as a build left it: its files, and a record listing `inputs`.
+ * `inputs: null` is a paper nothing has built.
+ */
+function project(
+  files: Record<string, string>,
+  inputs: readonly { path: string; role: "preamble" | "body" }[] | null = READ,
+): string {
   const root = realpathSync(mkdtempSync(join(tmpdir(), "paperlint-inc-")));
   dirs.push(root);
   const all: Record<string, string> = {
@@ -51,7 +72,8 @@ function project(files: Record<string, string>): string {
     ),
     ...files,
   };
-  for (const [p, text] of Object.entries(all)) {
+  const written = inputs === null ? all : recordedTree(all, "papers/a", inputs);
+  for (const [p, text] of Object.entries(written)) {
     mkdirSync(join(root, p, ".."), { recursive: true });
     writeFileSync(join(root, p), text);
   }
@@ -62,7 +84,11 @@ function project(files: Record<string, string>): string {
 async function lint(
   root: string,
   args: string[] = [],
-): Promise<{ byFile: Record<string, string[]>; err: string }> {
+): Promise<{
+  byFile: Record<string, string[]>;
+  said: Record<string, string[]>;
+  err: string;
+}> {
   const out: string[] = [];
   const err: string[] = [];
   await run(["lint", "--json", ...args], {
@@ -70,13 +96,20 @@ async function lint(
     log: (s: string) => out.push(s),
     err: (s: string) => err.push(s),
   });
+  const report = lintReport(out.join("\n"));
   const byFile = Object.fromEntries(
-    lintReport(out.join("\n")).map((r) => [
+    report.map((r) => [
       relative(root, r.filePath),
       r.messages.map((m) => m.ruleId ?? "(fatal)").sort(),
     ]),
   );
-  return { byFile, err: err.join("\n") };
+  const said = Object.fromEntries(
+    report.map((r) => [
+      relative(root, r.filePath),
+      r.messages.map((m) => m.message),
+    ]),
+  );
+  return { byFile, said, err: err.join("\n") };
 }
 
 describe("lint reads the files paper.tex includes from its body", () => {
@@ -104,18 +137,24 @@ describe("lint reads the files paper.tex includes from its body", () => {
 
   it("🔴 an included file that is not `.tex` — a `.bbl` — is not handed to ESLint, which parsed it as JavaScript (#153)", async () => {
     const { byFile, err } = await lint(
-      project({
-        "papers/a/paper.tex": doc(
-          "{article}",
-          "",
-          "Text, as Figure~\\ref{f1} shows.\n\\input{paper.bbl}",
-        ),
-        // What bibtex writes: a comment first, which ESLint's JavaScript parser stops at.
-        "papers/a/paper.bbl":
-          "% Generated by IEEEtran.bst\n\\begin{thebibliography}{1}\n" +
-          "\\bibitem{a} A. Author, ``A result with p < .05,'' 2024.\n" +
-          "\\end{thebibliography}\n",
-      }),
+      project(
+        {
+          "papers/a/paper.tex": doc(
+            "{article}",
+            "",
+            "Text, as Figure~\\ref{f1} shows.\n\\input{paper.bbl}",
+          ),
+          // What bibtex writes: a comment first, which ESLint's JavaScript parser stops at.
+          "papers/a/paper.bbl":
+            "% Generated by IEEEtran.bst\n\\begin{thebibliography}{1}\n" +
+            "\\bibitem{a} A. Author, ``A result with p < .05,'' 2024.\n" +
+            "\\end{thebibliography}\n",
+        },
+        [
+          { path: "paper.tex", role: "body" },
+          { path: "paper.bbl", role: "body" },
+        ],
+      ),
     );
     // Guards: the `.bbl` was the one file of the run with a parse error («Unexpected token %»).
     // It is bibtex's output, not prose the author edits: no fragment rule reports in it, and
@@ -124,7 +163,6 @@ describe("lint reads the files paper.tex includes from its body", () => {
       "papers/a/PIPELINE-STATUS.md": [],
       "papers/a/paper.tex": [],
     });
-    // Read, not missing: no «lint did not read» note names it.
     expect(err).not.toMatch(/paper\.bbl/);
   });
 
@@ -162,26 +200,107 @@ describe("what lint decides for the whole paper, it decides over every file of i
     );
     expect(review.byFile["papers/a/sections/intro.tex"]).toEqual([]);
   });
+});
 
-  it("an include that resolves nowhere is named as a file lint did not read", async () => {
-    const { err } = await lint(
-      project({
-        "papers/a/paper.tex": doc("{article}", "", "\\input{sections/gone}"),
-      }),
-    );
-    expect(err).toMatch(
-      /papers\/a\/paper\.tex: lint did not read `sections\/gone`/,
-    );
+describe("a built paper whose files are clean", () => {
+  it("is reported as the files that were checked — the paper's, and the section TeX read", async () => {
+    const root = project({
+      "papers/a/sections/intro.tex": "Plain words, nothing to flag.\n",
+    });
+    const out: string[] = [];
+    const code = await run(["lint"], {
+      cwd: root,
+      log: (s: string) => out.push(s),
+      err: () => undefined,
+    });
+    expect({ code, out }).toEqual({
+      code: 0,
+      out: ["✓ 3 file(s) checked, no findings"],
+    });
   });
+});
 
-  it("the note is about the papers this run lints, not another paper of the project", async () => {
-    const root = project({
-      "papers/b/PIPELINE-STATUS.md": "---\nstages: []\n---\n",
-      "papers/b/paper.tex": doc("{article}", "", "\\input{gone}"),
+describe("a paper whose record is missing, stale or silent about a file", () => {
+  it("🔴 a paper no build has recorded is paper.tex alone: its includes are not linted, and paper/sources-fresh says so", async () => {
+    const { byFile } = await lint(project({}, null));
+    expect(byFile).toEqual({
+      "papers/a/PIPELINE-STATUS.md": [],
+      "papers/a/paper.tex": ["paper/sources-fresh"],
     });
-    expect((await lint(root, ["papers/a"])).err).not.toMatch(/did not read/);
-    expect((await lint(root)).err).toMatch(
-      /papers\/b\/paper\.tex: lint did not read `gone`/,
+  });
+
+  it("🔴 a paper changed since its build is paper.tex alone, and paper/sources-fresh names the file", async () => {
+    const root = project({});
+    writeFileSync(
+      join(root, "papers/a/sections/intro.tex"),
+      "Edited after the build, p < .05.\n",
+    );
+    const { byFile, said } = await lint(root);
+    expect(Object.keys(byFile)).not.toContain("papers/a/sections/intro.tex");
+    expect(said["papers/a/paper.tex"]).toEqual([
+      expect.stringMatching(/sections\/intro\.tex edited/),
+    ]);
+  });
+});
+
+describe("paperBodies — the body files of the record TeX's own build left", () => {
+  const bodies = (files: Record<string, string>, dir = "/papers/p") =>
+    paperBodies([dir], { files: memoryFiles(files), codec: sourcesCodec });
+
+  it("p1: the one file TeX read after \\begin{document} — not the `.bib`, not the files its text names behind a comment or \\iffalse", () => {
+    expect(bodies(builtFixture("p1", "/papers/p"))).toEqual([
+      {
+        dir: "/papers/p",
+        main: "/papers/p/paper.tex",
+        files: ["/papers/p/sections/intro.tex"],
+      },
+    ]);
+  });
+
+  it("a body file that is a `.tex` listed after paper.tex is handed over; a preamble one is not (v16: a block written from a preamble include)", () => {
+    expect(
+      bodies(builtFixture("v16-included-block", "/papers/p"))[0]?.files,
+    ).toEqual([]);
+    expect(
+      bodies(builtFixture("v17-include-order", "/papers/p"))[0]?.files,
+    ).toEqual(["/papers/p/bibsetup.tex"]);
+  });
+
+  it("🔴 a body .tex TeX wrote from a filecontents block is not handed to ESLint: its text is the block's, and a fix there is overwritten or splits it from the block", () => {
+    const files = builtFixture("v29-generated-input", "/papers/p");
+    expect(files["/papers/p/body.tex"]).toBeDefined();
+    expect(bodies(files)[0]?.files).toEqual([]);
+  });
+
+  it("a directory without paper.tex is no paper", () => {
+    expect(bodies({}, "/papers/none")).toEqual([]);
+  });
+});
+
+describe("includeBlocks — what ESLint is told of each paper", () => {
+  it("un-ignores each body file by name, and hands the paper to every file of it", () => {
+    const main = absolutePath("/papers/p/paper.tex");
+    const intro = absolutePath("/papers/p/sections/intro.tex");
+    expect(includeBlocks([{ dir: "/papers/p", main, files: [intro] }])).toEqual(
+      [
+        { basePath: "/papers/p", ignores: ["!sections/intro.tex"] },
+        {
+          basePath: "/papers/p",
+          files: ["paper.tex", "sections/intro.tex"],
+          settings: { paperlint: { paper: { main, files: [main, intro] } } },
+        },
+      ],
     );
   });
+
+  it("a paper of one file un-ignores nothing", () => {
+    const main = absolutePath("/papers/p/paper.tex");
+    expect(includeBlocks([{ dir: "/papers/p", main, files: [] }])).toEqual([
+      {
+        basePath: "/papers/p",
+        files: ["paper.tex"],
+        settings: { paperlint: { paper: { main, files: [main] } } },
+      },
+    ]);
+  });
 });