paperlint 8.0.0 → 9.0.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

package/src/paper-record.test.ts

@@ -0,0 +1,173 @@
+/**
+ * `paperRecord(dir)` — the one answer to "what did the last build read, and is that still the paper?",
+ * over files held in memory — and the two things the rules take from a fresh record: the files of a
+ * role, and the databases bibtex opened as the bibtex reader reads them.
+ */
+import { describe, expect, it } from "vitest";
+import { bibReader } from "./adapters/bibtex/index.ts";
+import { memoryFiles } from "./adapters/memory/index.ts";
+import { sourcesCodec } from "./adapters/sources-record/index.ts";
+import type { BibText } from "./domain/paper-sources.ts";
+import { sha256Hex } from "./domain/sha256.ts";
+import {
+  serializeSourcesRecord,
+  type SourcesRecord,
+} from "./domain/sources-record.ts";
+import { paperRecord, recordedFiles } from "./paper-record.ts";
+import { recordedBibliography } from "./recorded-bibliography.ts";
+
+const DIR = "/work/paper";
+const bytes = (s: string) => new TextEncoder().encode(s);
+const digest = (s: string) => sha256Hex(bytes(s));
+
+const TEX = "\\documentclass{article}\n";
+const BIB = "@misc{a, title={A}, author={Doe, Jane}, year={2020}}\n";
+
+const RECORD: SourcesRecord = {
+  schema: 1,
+  inputs: [
+    { path: "paper.tex", role: "body" },
+    { path: "macros.tex", role: "preamble" },
+    { path: "sections/intro.tex", role: "body" },
+  ],
+  written: [],
+  bibdata: ["refs"],
+  bibtex: {
+    ran: true,
+    databases: ["refs.bib"],
+    keys: ["a"],
+    exit: 0,
+    errors: [],
+  },
+  sha256: {
+    "paper.tex": digest(TEX),
+    "macros.tex": digest("m"),
+    "sections/intro.tex": digest("i"),
+    "refs.bib": digest(BIB),
+  },
+};
+
+/** The paper directory after a build wrote `record`: every file as it was hashed. */
+const built = (record: SourcesRecord = RECORD) =>
+  memoryFiles({
+    [`${DIR}/_build/sources.json`]: serializeSourcesRecord(record),
+    [`${DIR}/paper.tex`]: TEX,
+    [`${DIR}/macros.tex`]: "m",
+    [`${DIR}/sections/intro.tex`]: "i",
+    [`${DIR}/refs.bib`]: BIB,
+  });
+
+describe("paperRecord", () => {
+  it("a paper no build has recorded has none", () => {
+    expect(
+      paperRecord(DIR, {
+        files: memoryFiles({ [`${DIR}/paper.tex`]: TEX }),
+        codec: sourcesCodec,
+      }),
+    ).toEqual({ kind: "none", unreadable: null });
+  });
+
+  it("a record that cannot be read has none, and says why", () => {
+    const files = built();
+    files.map.set(`${DIR}/_build/sources.json`, bytes("{"));
+    expect(paperRecord(DIR, { files, codec: sourcesCodec })).toEqual({
+      kind: "none",
+      unreadable: "sources.json is not JSON",
+    });
+    files.map.set(`${DIR}/_build/sources.json`, bytes('{"schema":2}'));
+    expect(paperRecord(DIR, { files, codec: sourcesCodec })).toEqual({
+      kind: "none",
+      unreadable: "sources.json is schema 2, this paperlint reads schema 1",
+    });
+  });
+
+  it("a record whose every file is as hashed is fresh", () => {
+    expect(paperRecord(DIR, { files: built(), codec: sourcesCodec })).toEqual({
+      kind: "fresh",
+      record: RECORD,
+    });
+  });
+
+  it("a file edited since the build makes it stale, and names the file", () => {
+    const files = built();
+    files.map.set(`${DIR}/sections/intro.tex`, bytes("edited"));
+    expect(paperRecord(DIR, { files, codec: sourcesCodec })).toEqual({
+      kind: "stale",
+      changed: [{ path: "sections/intro.tex", change: "edited" }],
+    });
+  });
+
+  it("a file deleted, a database edited: every change is named, in the record's order", () => {
+    const files = built();
+    files.map.delete(`${DIR}/macros.tex`);
+    files.map.set(`${DIR}/refs.bib`, bytes("@misc{b}"));
+    expect(paperRecord(DIR, { files, codec: sourcesCodec })).toEqual({
+      kind: "stale",
+      changed: [
+        { path: "macros.tex", change: "deleted" },
+        { path: "refs.bib", change: "edited" },
+      ],
+    });
+  });
+});
+
+const keysOf = (bib: BibText): readonly string[] =>
+  bib.entries.map((e) => e.key);
+
+const DEPS = { codec: sourcesCodec, bib: bibReader };
+
+describe("what a rule takes from a record", () => {
+  it("the files of a role, as absolute paths, in the order TeX first read them", () => {
+    expect(recordedFiles(DIR, RECORD, "body")).toEqual([
+      `${DIR}/paper.tex`,
+      `${DIR}/sections/intro.tex`,
+    ]);
+    expect(recordedFiles(DIR, RECORD, "preamble")).toEqual([
+      `${DIR}/macros.tex`,
+    ]);
+  });
+
+  it("the databases bibtex opened, read as the bibtex reader reads them, a block's copy marked written, a missing one named", () => {
+    const record: SourcesRecord = {
+      ...RECORD,
+      written: ["gen.bib"],
+      bibtex: {
+        ran: true,
+        databases: ["refs.bib", "gen.bib", "gone.bib", "./refs.bib"],
+        keys: [],
+        exit: 0,
+        errors: [],
+      },
+    };
+    const files = built(record);
+    files.map.set(`${DIR}/gen.bib`, bytes("@misc{g, title={G}}"));
+    const r = recordedBibliography(DIR, { ...DEPS, files });
+    expect(
+      r.kind === "recorded"
+        ? {
+            databases: r.databases.map((d) => [
+              d.name,
+              d.written,
+              keysOf(d.bib),
+            ]),
+            unread: r.unread,
+            path: r.databases[0]?.bib.path,
+          }
+        : r,
+    ).toEqual({
+      databases: [
+        ["refs.bib", false, ["a"]],
+        ["gen.bib", true, ["g"]],
+      ],
+      unread: ["gone.bib"],
+      path: `${DIR}/refs.bib`,
+    });
+  });
+
+  it("a build that ran no bibtex opened no database", () => {
+    const record: SourcesRecord = { ...RECORD, bibtex: { ran: false } };
+    expect(
+      recordedBibliography(DIR, { ...DEPS, files: built(record) }),
+    ).toMatchObject({ kind: "recorded", databases: [], unread: [] });
+  });
+});