paperlint 8.0.0 → 9.0.1

package/src/heading-case.test.ts

@@ -12,6 +12,7 @@ import { run } from "./cli.ts";
 import { headingCaseRule } from "./heading-case.ts";
 import { latexReader } from "./adapters/latex/index.ts";
 import { useTempDir, writeTree } from "../test/support.ts";
+import { recordedTree } from "../test/recorded-fixture.ts";
 
 const Results = z.array(
   z.looseObject({
@@ -369,10 +370,15 @@ describe("tex/heading-case refuses, when ESLint loads it, a configuration that a
 });
 
 describe("tex/heading-case in the files a paper includes", () => {
-  const tree = paper(
-    doc("\\section{Introduction}\n\\input{sections/results}"),
-    PRESET,
-    { "papers/p/sections/results.tex": "\\section{Results and discussion}\n" },
+  const tree = recordedTree(
+    paper(doc("\\section{Introduction}\n\\input{sections/results}"), PRESET, {
+      "papers/p/sections/results.tex": "\\section{Results and discussion}\n",
+    }),
+    "papers/p",
+    [
+      { path: "paper.tex", role: "body" },
+      { path: "sections/results.tex", role: "body" },
+    ],
   );
 
   it("reports a heading at its own file and line, and --fix edits that file", async () => {
@@ -391,12 +397,20 @@ describe("tex/heading-case in the files a paper includes", () => {
   });
 
   it("🔴 reads a \\title kept in a file the body includes, where it stands", async () => {
-    const withTitle = paper(
-      `${ACM}\n\\begin{document}\n\\input{front}\n\\maketitle\n\\end{document}\n`,
-      PRESET,
-      {
-        "papers/p/front.tex": "% the front matter\n\\title{Measuring things}\n",
-      },
+    const withTitle = recordedTree(
+      paper(
+        `${ACM}\n\\begin{document}\n\\input{front}\n\\maketitle\n\\end{document}\n`,
+        PRESET,
+        {
+          "papers/p/front.tex":
+            "% the front matter\n\\title{Measuring things}\n",
+        },
+      ),
+      "papers/p",
+      [
+        { path: "paper.tex", role: "body" },
+        { path: "front.tex", role: "body" },
+      ],
     );
     const { found } = await lint(withTitle);
     expect(found).toEqual([

package/src/latex-log.ts

@@ -146,6 +146,26 @@ export function bibtexExcerpt(stdout: string): string[] {
     .slice(0, MAX_EXCERPT);
 }
 
+/** What a bibtex run read: the databases its `.blg` names, the entries its `.bbl` holds. */
+export interface BibtexRead {
+  readonly databases: readonly string[];
+  readonly bibitems: readonly string[];
+}
+
+/** `\bibitem{key}`, `\bibitem[label]{key}` — a label may hold one level of braces (natbib's `[{A}(2020)]`). */
+const BIBITEM = /\\bibitem\s*(?:\[(?:[^[\]{}]|\{[^{}]*\})*\])?\s*\{([^}]+)\}/g;
+
+/**
+ * What a bibtex run read, from the files it left: `Database file #n: name` in its `.blg` (the name
+ * as the `.aux` gave it, relative to where bibtex ran), and every key its `.bbl` typesets.
+ */
+export const bibtexRead = (blg: string, bbl: string): BibtexRead => ({
+  databases: [...blg.matchAll(/^Database file #\d+: (.+)$/gm)].flatMap((m) =>
+    m.slice(1, 2),
+  ),
+  bibitems: [...bbl.matchAll(BIBITEM)].flatMap((m) => m.slice(1, 2)),
+});
+
 /** What the `.aux` tells bibtex: the cited keys, the databases and the style. */
 export interface AuxBib {
   /** Sorted, unique. `*` (`\nocite{*}`) is a key like any other. */

package/src/latex-loop.harness.ts

@@ -51,6 +51,7 @@ const latex = (o: Partial<LatexPass> = {}): LatexPass => ({
   markers: [],
   bib: NO_BIB,
   errorLines: [],
+  fls: null,
   ...o,
 });
 const bibtex = (o: Partial<BibtexPass> = {}): BibtexPass => ({

package/src/latex-loop.ts

@@ -86,6 +86,8 @@ export type Observation =
       readonly bib: BibInput;
       /** The first error and its source context, from the log. Empty on success. */
       readonly errorLines: readonly string[];
+      /** What `-recorder` wrote after this pass (`paper.fls`), or null when pdflatex wrote none. */
+      readonly fls: string | null;
     }
   | {
       readonly step: "bibtex";

package/src/linted-set.test.ts

@@ -20,6 +20,7 @@ import { join, relative } from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
 import { run } from "./cli.ts";
 import { lintReport } from "../test/lint-report.ts";
+import { recordedTree } from "../test/recorded-fixture.ts";
 
 const dirs: string[] = [];
 afterEach(() => {
@@ -87,7 +88,14 @@ function project(): string {
     "papers/a/sections/intro.tex": "Intro.\n",
     ...NEIGHBOURS,
   };
-  for (const [p, text] of Object.entries(all)) {
+  // As a build left it: TeX read paper.tex, the macro file in the preamble and the section in the body
+  // (`paper-guards` is paperlint's own input, outside the paper's directory, so the record has none).
+  const built = recordedTree(all, "papers/a", [
+    { path: "paper.tex", role: "body" },
+    { path: "macros.tex", role: "preamble" },
+    { path: "sections/intro.tex", role: "body" },
+  ]);
+  for (const [p, text] of Object.entries(built)) {
     mkdirSync(join(root, p, ".."), { recursive: true });
     writeFileSync(join(root, p), text);
   }

package/src/new-paper.harness.mjs

@@ -112,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.

package/src/new-paper.test.ts

@@ -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);
   });
 });

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-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] } } },
+      },
+    ]);
+  });
 });

package/src/paper-includes.ts

@@ -2,10 +2,12 @@
  * THE FILES OF A PAPER'S BODY, handed to ESLint — so the rules over ESLint's LaTeX text read a paper
  * whose body is in `sections/*.tex`, and report each finding at its own file and line (#144).
  *
- * The set is what TeX reads, resolved by the reader the parse-tree rules use (`bodyFiles`,
- * src/tex-paper.ts): `paper.tex` and every file an include in its document body brings in, found in
- * the paper's directory. Not a glob over every `.tex`: a frozen version under `versions/`, a macro
- * file the preamble includes and a scratch file nothing includes are not the paper.
+ * The set is what TeX read, as the last build recorded it (`_build/sources.json`, `paperRecord` in
+ * src/paper-record.ts): `paper.tex` and the `.tex` files of the paper directory TeX read after
+ * `\\begin{document}`. Nothing here reads TeX source or looks for an include on disk. Not a glob over
+ * every `.tex`: a frozen version under `versions/`, a macro file the preamble includes and a scratch
+ * file nothing includes are not the paper. A paper with no record, or one it has changed since, is
+ * `paper.tex` alone — `paper/sources-fresh` (src/sources-rules.ts) says the rest went unlinted.
  *
  * Two blocks per paper, both relative to the paper's directory (`basePath`):
  *
@@ -16,21 +18,32 @@
  *    for the rules whose verdict is the paper's (eslint-rules/paper-context.ts).
  *
  * ── ONLY `.tex` FILES ARE HANDED TO ESLint (#153) ────────────────────────────────
- * An include may resolve to a file of another extension: `\input{paper.bbl}` in a paper that ships
- * bibtex's output instead of a `.bib`, a plot exported as `.pgf`. Handed to ESLint, such a file got
- * no language — the fragment block claims `.tex` only — and the JavaScript parser stopped at its
- * first `%`. It is not given the LaTeX language either: the fragment rules judge and `--fix` the
- * prose an author writes in that file, and a file of another extension is in practice a tool's
- * output, whose words are someone else's (the titles of cited works) and whose fix the next run of
- * the tool overwrites. TeX still reads it, and so does `readPaper`: the rules over the whole paper
- * see it spliced into `paper.tex`, where TeX typesets it.
+ * TeX may read a body file of another extension: `\\input{paper.bbl}` in a paper that ships bibtex's
+ * output instead of a `.bib`, a plot exported as `.pgf`. Handed to ESLint, such a file got no
+ * language — the fragment block claims `.tex` only — and the JavaScript parser stopped at its first
+ * `%`. It is not given the LaTeX language either: the fragment rules judge and `--fix` the prose an
+ * author writes in that file, and a file of another extension is in practice a tool's output, whose
+ * words are someone else's (the titles of cited works) and whose fix the next run of the tool
+ * overwrites. TeX still reads it, and so does `readPaper`: the rules over the whole paper see it
+ * spliced into `paper.tex`, where TeX typesets it.
+ *
+ * ── NOR IS A `.tex` TeX WROTE ────────────────────────────────────────────────────
+ * A `filecontents` block may write a `.tex` the body `\\input`s (the record lists it as an input and
+ * as written, src/domain/tex-run.ts). Its words are the block's, which the author edits in the file
+ * holding the block; a fix made in the written copy is overwritten by an `[overwrite]` block on the next
+ * build, and splits the copy from the block without one. So it is read the way TeX reads it — spliced by
+ * `readPaper`, for the rules over the whole paper — and is not handed to ESLint as a file of its own.
  */
 import { extname, join, relative } from "node:path";
 import { PAPERLINT_SETTINGS } from "#eslint-rules/paper-context";
 import { callerPath } from "./caller-path.ts";
 import type { AbsolutePath } from "./domain/paths.ts";
+import {
+  paperRecord,
+  recordedFiles,
+  type RecordReadDeps,
+} from "./paper-record.ts";
 import type { ConfigBlock } from "./rules-config.ts";
-import { bodyFiles, type PaperDeps, type Unread } from "./tex-paper.ts";
 
 /** The files the fragment block (`buildConfig`) claims: the only body files ESLint is handed. */
 export const FRAGMENT_FILES: readonly string[] = ["**/*.tex"];
@@ -38,27 +51,31 @@ export const FRAGMENT_FILES: readonly string[] = ["**/*.tex"];
 /** Whether a body file is one the fragment block claims — the extension its glob names. */
 const isFragment = (file: string): boolean => extname(file) === ".tex";
 
-/** One paper's main file and body files, and the includes that resolved nowhere. */
+/** One paper's main file and the body files of its last build. */
 export interface PaperBody {
   readonly dir: string;
   readonly main: AbsolutePath;
-  /** The body files ESLint lints, each as a fragment: the `.tex` ones. */
+  /** The body files ESLint lints, each as a fragment: the `.tex` ones TeX did not write. None without a fresh record. */
   readonly files: readonly AbsolutePath[];
-  readonly missing: readonly Unread[];
 }
 
 /** The body of each paper directory in `dirs` that has a `paper.tex`. */
 export function paperBodies(
   dirs: readonly string[],
-  deps: PaperDeps,
+  deps: RecordReadDeps,
 ): readonly PaperBody[] {
   return dirs.flatMap((dir) => {
     const main = callerPath(join(dir, "paper.tex"));
-    const bytes = deps.files.readBytes(main);
-    if (bytes === null) return [];
-    const body = bodyFiles(main, new TextDecoder().decode(bytes), deps);
-    const files = body.files.filter(isFragment);
-    return [{ dir, main, files, missing: body.missing }];
+    if (!deps.files.isFile(main)) return [];
+    const record = paperRecord(dir, deps);
+    if (record.kind !== "fresh") return [{ dir, main, files: [] }];
+    const written = new Set(
+      record.record.written.map((w) => callerPath(join(dir, w))),
+    );
+    const files = recordedFiles(dir, record.record, "body").filter(
+      (f) => f !== main && isFragment(f) && !written.has(f),
+    );
+    return [{ dir, main, files }];
   });
 }
 
@@ -80,16 +97,3 @@ export const includeBlocks = (
       },
     ];
   });
-
-/** One line per include that resolved nowhere: which text lint did not read, and why. */
-export const unreadLines = (
-  bodies: readonly PaperBody[],
-  shown: (path: string) => string,
-): readonly string[] =>
-  bodies.flatMap((b) =>
-    b.missing.map(
-      (m) =>
-        `${shown(b.main)}: lint did not read \`${m.target}\` (included by ${m.file}): ` +
-        "no such file in the paper's directory or paperlint's inputs",
-    ),
-  );

package/src/paper-prose.test.ts

@@ -1,7 +1,9 @@
 import { expect, it } from "vitest";
 import { latexReader } from "./adapters/latex/index.ts";
 import { memoryFiles } from "./adapters/memory/index.ts";
+import { sourcesCodec } from "./adapters/sources-record/index.ts";
 import { paperProse } from "./paper-prose.ts";
+import { builtFixture, builtPaper } from "../test/recorded-fixture.ts";
 
 const SRC = [
   "\\documentclass{article}",
@@ -20,12 +22,23 @@ const SRC = [
 ].join("\n");
 
 it("the body's prose, a blank line between passages, includes spliced; the preamble, comments, the inline .bib and the title stay out", () => {
-  const files = memoryFiles({
-    "/p/paper.tex": SRC,
-    "/p/body.tex": "\\subsection{Method}\nends here.",
-  });
+  // The build recorded TeX reading both files; the preamble holds no include.
+  const files = memoryFiles(
+    builtPaper(
+      "/p",
+      { "paper.tex": SRC, "body.tex": "\\subsection{Method}\nends here." },
+      [
+        { path: "paper.tex", role: "body" },
+        { path: "body.tex", role: "body" },
+      ],
+    ),
+  );
   expect(
-    paperProse("/p/paper.tex", SRC, { files, latex: latexReader }),
+    paperProse("/p/paper.tex", SRC, {
+      files,
+      latex: latexReader,
+      codec: sourcesCodec,
+    }),
   ).toEqual({
     // A citation stands as `[1]`, where it is set; a heading — here an included one — ends a passage.
     body: "We measure it [1].\n\nA second paragraph\n\nends here.",
@@ -44,6 +57,22 @@ it("a citation stands as `[1]` and a cross-reference as `1`, so the sentence sti
     paperProse("/p/paper.tex", src, {
       files: memoryFiles({ "/p/paper.tex": src }),
       latex: latexReader,
+      codec: sourcesCodec,
     }).body,
   ).toBe("It holds [1]. It is shown (Section 1).");
 });
+
+it("🔴 a .tex a filecontents block wrote and the body \\input's is prose once: spliced where TeX read it, the block's body no prose", () => {
+  // v29-generated-input: TeX recorded body.tex — written by the block, read after \begin{document}.
+  const files = builtFixture("v29-generated-input", "/p");
+  const src = files["/p/paper.tex"] ?? "";
+  const { body } = paperProse("/p/paper.tex", src, {
+    files: memoryFiles(files),
+    latex: latexReader,
+    codec: sourcesCodec,
+  });
+  expect(
+    body.match(/This sentence is typeset from a file a block wrote\./g),
+  ).toHaveLength(1);
+  expect(body).toMatch(/^Before the generated file\. This sentence/);
+});

package/src/paper-prose.ts

@@ -17,7 +17,7 @@
 import { bodySentences } from "./domain/register.ts";
 import { CITATION, MATH, REFERENCE } from "./domain/sentences.ts";
 import { runText } from "./domain/tex-document.ts";
-import { readPaper, type PaperDeps } from "./tex-paper.ts";
+import { readPaper, type ProseDeps } from "./tex-paper.ts";
 
 /** A sentence's text with each mark as a reader would see it set, and math left out. */
 const rendered = (raw: string): string =>
@@ -43,7 +43,7 @@ export interface PaperProse {
 export function paperProse(
   filename: string,
   src: string,
-  deps: PaperDeps,
+  deps: ProseDeps,
 ): PaperProse {
   const { text, segments } = readPaper(filename, src, deps);
   const passages = deps.latex