paperlint 7.2.0 → 9.0.0

package/src/sources-record.test.ts

@@ -0,0 +1,308 @@
+/**
+ * The build's record step (`recordSources`): from the passes' `.fls` and the `.aux`, `.blg` and `.bbl`
+ * a run left, the `_build/sources.json` of docs/design/paper-sources.md §1 — on the files of real runs
+ * of the planted papers (test/fixtures/tex-output/README.md), over files held in memory. What TeX
+ * itself answers for the same papers is `test/e2e/tex/paper-sources.e2e.ts`.
+ */
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import {
+  memoryFiles,
+  memoryListDir,
+  type MemoryFiles,
+} from "./adapters/memory/index.ts";
+import { texOutput } from "./adapters/tex-output/index.ts";
+import { sourcesCodec } from "./adapters/sources-record/index.ts";
+import {
+  recordSources,
+  sourcesRecorder,
+  type TexRun,
+} from "./sources-record.ts";
+
+const CAPTURES = join(
+  dirname(dirname(fileURLToPath(import.meta.url))),
+  "test",
+  "fixtures",
+  "tex-output",
+);
+const capture = (paper: string, file: string): string =>
+  readFileSync(join(CAPTURES, paper, file), "utf8");
+
+const DIR = "/work/paper";
+/** The record step's ports over files held in memory. */
+const deps = (files: MemoryFiles) => ({
+  files,
+  texOutput,
+  listDir: memoryListDir(files),
+});
+const sha = (text: string): string =>
+  createHash("sha256").update(text).digest("hex");
+
+/** The run of a planted paper: both captured passes, and what bibtex and TeX left. */
+const run = (paper: string, bibtexExit: number | null): TexRun => ({
+  fls: ["first-pass.fls", "paper.fls"].map((f) => capture(paper, f)),
+  bibtexExit,
+});
+/** The paper directory after that run: the sources given, TeX's and bibtex's files captured. */
+const after = (
+  paper: string,
+  sources: Readonly<Record<string, string>>,
+  captured: readonly string[] = ["paper.aux", "paper.blg", "paper.bbl"],
+) =>
+  memoryFiles({
+    ...Object.fromEntries(
+      Object.entries(sources).map(([rel, text]) => [`${DIR}/${rel}`, text]),
+    ),
+    ...Object.fromEntries(
+      captured.map((f) => [`${DIR}/${f}`, capture(paper, f)]),
+    ),
+  });
+
+const SOURCES = { "paper.tex": "% paper\n", "refs.bib": "@misc{a}\n" };
+
+describe("the record of a build", () => {
+  it("lists what TeX read, what bibtex did and the hash of every file the paper is made of", () => {
+    const files = after("p1", {
+      ...SOURCES,
+      "sections/intro.tex": "Intro.\n",
+    });
+    const out = recordSources(deps(files), DIR, run("p1", 0));
+    expect(out).toEqual({
+      kind: "recorded",
+      path: `${DIR}/_build/sources.json`,
+      record: {
+        schema: 1,
+        inputs: [
+          { path: "paper.tex", role: "body" },
+          { path: "refs.bib", role: "preamble" },
+          { path: "sections/intro.tex", role: "body" },
+        ],
+        written: [],
+        bibdata: ["refs"],
+        bibtex: {
+          ran: true,
+          databases: ["refs.bib"],
+          keys: ["stale2020"],
+          exit: 0,
+          errors: [],
+        },
+        sha256: {
+          "paper.tex": sha("% paper\n"),
+          "refs.bib": sha("@misc{a}\n"),
+          "sections/intro.tex": sha("Intro.\n"),
+        },
+      },
+    });
+  });
+
+  it("writes it to _build/sources.json, and what it wrote parses back to the same record", () => {
+    const files = after("p1", { ...SOURCES, "sections/intro.tex": "x" });
+    const out = recordSources(deps(files), DIR, run("p1", 0));
+    const text = new TextDecoder().decode(
+      files.map.get(`${DIR}/_build/sources.json`),
+    );
+    expect(text.endsWith("}\n")).toBe(true);
+    expect(sourcesCodec.parse(text)).toEqual({
+      ok: true,
+      record: out.kind === "recorded" ? out.record : undefined,
+    });
+  });
+});
+
+describe("what the record leaves out, or marks absent", () => {
+  it("a .bib TeX wrote is listed as written and hashed, so an edit to it after the build makes the record stale", () => {
+    const files = after("v8-jobname", {
+      "paper.tex": "% block\n",
+      "paper.bib": "TeX's own copy\n",
+    });
+    const out = recordSources(deps(files), DIR, run("v8-jobname", 0));
+    expect(out.kind === "recorded" ? out.record : out).toEqual({
+      schema: 1,
+      inputs: [{ path: "paper.tex", role: "body" }],
+      written: ["paper.bib"],
+      bibdata: ["paper"],
+      bibtex: {
+        ran: true,
+        databases: ["paper.bib"],
+        keys: ["jkey"],
+        exit: 0,
+        errors: [],
+      },
+      sha256: {
+        "paper.tex": sha("% block\n"),
+        "paper.bib": sha("TeX's own copy\n"),
+      },
+    });
+  });
+
+  it("a database bibtex names as ./paper.bib is recorded as paper.bib, the name the .fls gave the file TeX wrote", () => {
+    const blg = capture("v8-jobname", "paper.blg").replace(
+      "Database file #1: paper.bib",
+      "Database file #1: ./paper.bib",
+    );
+    const files = after(
+      "v8-jobname",
+      {
+        "paper.tex": "% block\n",
+        "paper.bib": "TeX's own copy\n",
+        "paper.blg": blg,
+      },
+      ["paper.aux", "paper.bbl"],
+    );
+    const out = recordSources(deps(files), DIR, run("v8-jobname", 0));
+    expect(out.kind === "recorded" ? out.record : out).toMatchObject({
+      written: ["paper.bib"],
+      bibtex: { ran: true, databases: ["paper.bib"] },
+      sha256: { "paper.bib": sha("TeX's own copy\n") },
+    });
+  });
+});
+
+describe("how the record spells a file", () => {
+  it("a file TeX logged in the source's spelling is recorded in the disk's, so a file system that ignores case gives the record one that does not", () => {
+    const files = memoryFiles({
+      [`${DIR}/paper.tex`]: "% p\n",
+      [`${DIR}/figures/nexmark.pdf`]: "pdf",
+    });
+    const out = recordSources(deps(files), DIR, {
+      fls: [
+        "PWD /work/paper\nINPUT paper.tex\nINPUT Figures/NEXMark.pdf\nINPUT figures/nexmark.pdf\n",
+      ],
+      bibtexExit: null,
+    });
+    expect(out.kind === "recorded" ? out.record : out).toMatchObject({
+      inputs: [{ path: "paper.tex" }, { path: "figures/nexmark.pdf" }],
+      sha256: { "paper.tex": sha("% p\n"), "figures/nexmark.pdf": sha("pdf") },
+    });
+  });
+});
+
+describe("the recorder the build is handed", () => {
+  it("sourcesRecorder is recordSources with its ports bound", () => {
+    const files = after("p1", { "paper.tex": "% p\n" });
+    const bound = sourcesRecorder(deps(files))(DIR, run("p1", 0));
+    expect(bound).toEqual(recordSources(deps(files), DIR, run("p1", 0)));
+  });
+});
+
+describe("what the record hashes", () => {
+  it("a database bibtex opened that no TeX input names is hashed all the same", () => {
+    const files = after("v17-include-order", {
+      "paper.tex": "% p\n",
+      "bibsetup.tex": "% s\n",
+      "first.bib": "@misc{firstkey}\n",
+      "later.bib": "@misc{laterkey}\n",
+    });
+    const out = recordSources(deps(files), DIR, run("v17-include-order", 2));
+    expect(out.kind === "recorded" ? out.record : out).toMatchObject({
+      bibdata: ["first", "later"],
+      bibtex: { ran: true, databases: ["first.bib"], exit: 2 },
+      sha256: {
+        "paper.tex": sha("% p\n"),
+        "bibsetup.tex": sha("% s\n"),
+        "first.bib": sha("@misc{firstkey}\n"),
+      },
+    });
+  });
+});
+
+describe("what bibtex reported", () => {
+  it("bibtex's errors are recorded as it reported them, with its exit", () => {
+    const files = after("v6-unclosed", {
+      "paper.tex": "% p\n",
+      "refs.bib": "@misc{a",
+    });
+    const out = recordSources(deps(files), DIR, run("v6-unclosed", 2));
+    expect(out.kind === "recorded" ? out.record.bibtex : out).toEqual({
+      ran: true,
+      databases: ["refs.bib"],
+      keys: ["a1", "a4", "a3", "a2unclosed"],
+      exit: 2,
+      errors: [
+        {
+          message: "I was expecting a `,' or a `}'",
+          file: "refs.bib",
+          line: 4,
+        },
+      ],
+    });
+  });
+});
+
+describe("a build with no bibtex, a missing file, no .fls", () => {
+  it("a build that ran no bibtex records none, reads no .blg or .bbl a build before it left, and counts a .bbl TeX read as an input", () => {
+    const files = after(
+      "v3-declared",
+      { "paper.tex": "% p\n", "paper.bbl": "b" },
+      ["paper.aux"],
+    );
+    const out = recordSources(deps(files), DIR, run("v3-declared", null));
+    expect(out.kind === "recorded" ? out.record : out).toEqual({
+      schema: 1,
+      inputs: [
+        { path: "paper.tex", role: "body" },
+        { path: "paper.bbl", role: "body" },
+      ],
+      written: [],
+      bibdata: ["paper"],
+      bibtex: { ran: false },
+      sha256: { "paper.tex": sha("% p\n"), "paper.bbl": sha("b") },
+    });
+  });
+});
+
+describe("a file gone, no .aux, no .fls", () => {
+  it("a file the record lists that is gone when it is made is recorded as absent, so its return is a change", () => {
+    const files = after("p1", {
+      "paper.tex": "% p\n",
+      "sections/intro.tex": "x",
+    });
+    const out = recordSources(deps(files), DIR, run("p1", 0));
+    expect(out.kind === "recorded" ? out.record.sha256 : out).toEqual({
+      "paper.tex": sha("% p\n"),
+      "refs.bib": null,
+      "sections/intro.tex": sha("x"),
+    });
+  });
+
+  it("a paper with no \\bibdata has none, and a missing .aux reads as none", () => {
+    const files = after("v3-declared", { "paper.tex": "% p\n" }, []);
+    const out = recordSources(deps(files), DIR, run("v3-declared", null));
+    expect(out.kind === "recorded" ? out.record.bibdata : out).toEqual([]);
+  });
+
+  it("bibtex that ran and left no .blg or .bbl (it could not start) records what it was given: nothing opened, nothing typeset", () => {
+    const files = after("v3-declared", { "paper.tex": "% p\n" }, ["paper.aux"]);
+    const out = recordSources(deps(files), DIR, run("v3-declared", 127));
+    expect(out.kind === "recorded" ? out.record.bibtex : out).toEqual({
+      ran: true,
+      databases: [],
+      keys: [],
+      exit: 127,
+      errors: [],
+    });
+  });
+
+  it("no .fls, or one that names no file of the paper, records nothing and says why", () => {
+    const files = memoryFiles({ [`${DIR}/paper.tex`]: "x" });
+    expect(
+      recordSources(deps(files), DIR, { fls: [], bibtexExit: null }),
+    ).toEqual({
+      kind: "not-recorded",
+      why: "pdflatex wrote no paper.fls — nothing to record",
+    });
+    expect(
+      recordSources(deps(files), DIR, {
+        fls: ["PWD /work/paper\nINPUT /usr/x.cls\n"],
+        bibtexExit: null,
+      }),
+    ).toEqual({
+      kind: "not-recorded",
+      why: "paper.fls lists no file of the paper directory — nothing to record",
+    });
+    expect(files.map.has(`${DIR}/_build/sources.json`)).toBe(false);
+  });
+});

package/src/sources-record.ts

@@ -0,0 +1,231 @@
+/**
+ * THE RECORD STEP OF A BUILD — `recordSources` writes `<paper>/_build/sources.json`
+ * (`src/domain/sources-record.ts`, docs/design/paper-sources.md §1) from what TeX and bibtex left in
+ * the paper directory after the build's passes: each pass's `.fls`, the `.aux`, the `.blg` and the
+ * `.bbl`. The files are read through the `Files` port, the `.fls` and the `.blg` through `TexOutput`;
+ * which files the passes read is decided by `filesOfRun` (`src/domain/tex-run.ts`).
+ *
+ * Nothing here reads TeX source. Every file named in the record is one TeX or bibtex opened, and its
+ * bytes are hashed as they are now: what a rule compares later to know whether the paper changed.
+ *
+ * What the `.aux`, `.blg` and `.bbl` hold about the bibliography is read by `latex-log.ts` — the reader
+ * the build loop already uses on them, so one reader answers what bibtex was told and what it read.
+ */
+import { join, posix, resolve } from "node:path";
+import { callerPath } from "./caller-path.ts";
+import {
+  JOBNAME,
+  serializeSourcesRecord,
+  SOURCES_DIR,
+  SOURCES_FILE,
+  SOURCES_SCHEMA,
+  spelledIn,
+  type RecordedBibtex,
+  type RecordedInput,
+  type SourcesRecord,
+} from "./domain/sources-record.ts";
+import { sha256Hex } from "./domain/sha256.ts";
+import { filesOfRun, type RunFiles } from "./domain/tex-run.ts";
+import { auxBib, bibtexRead } from "./latex-log.ts";
+import type { Files } from "./ports/files.ts";
+import type { ListDir } from "./ports/talk-media.ts";
+import type { TexOutput } from "./ports/tex-output.ts";
+
+/** What recording needs: the disk, its directory listings, and the readers of TeX's own files. */
+export interface RecordDeps {
+  readonly files: Files;
+  readonly listDir: ListDir;
+  readonly texOutput: TexOutput;
+}
+
+/** What a build's passes left to read, besides the files on disk. */
+export interface TexRun {
+  /** The text of each pdflatex pass's `.fls`, in the order the passes ran. */
+  readonly fls: readonly string[];
+  /** The exit of the last bibtex run, or null when the build ran none. */
+  readonly bibtexExit: number | null;
+}
+
+export type Recorded =
+  | {
+      readonly kind: "recorded";
+      readonly record: SourcesRecord;
+      /** Where it was written. */
+      readonly path: string;
+    }
+  | { readonly kind: "not-recorded"; readonly why: string };
+
+/** The step as the build holds it: wired by the composition root, handed a paper's directory and its run. */
+export type RecordSources = (paperDir: string, run: TexRun) => Recorded;
+
+/** No recorder wired: the build says so, and lint reports the paper as not built. */
+export const notWiredRecord: RecordSources = () => ({
+  kind: "not-recorded",
+  why: "no recorder was wired into this build",
+});
+
+/** Where a paper's record lives. */
+export const sourcesPath = (paperDir: string): string =>
+  join(paperDir, SOURCES_DIR, SOURCES_FILE);
+
+const distinct = <T>(xs: readonly T[]): readonly T[] => [...new Set(xs)];
+
+/** A path as the record spells it: relative to the paper directory, `./` and doubled slashes gone. */
+const spelled = (p: string): string => posix.normalize(p);
+
+/**
+ * A path of the record spelled as the paper directory's entries spell it. TeX logs the name it opened:
+ * on a file system that ignores case that is the source's spelling, while TeX on one that does not
+ * retries without case and logs the disk's — one paper, two records. A segment no entry matches, or
+ * several do, stays as TeX spelled it.
+ */
+const spelledOnDisk =
+  (listDir: ListDir, paperDir: string) =>
+  (p: string): string =>
+    p
+      .split("/")
+      .reduce(
+        (at, segment) =>
+          posix.join(
+            at,
+            spelledIn(listDir(callerPath(resolve(paperDir, at))), segment) ??
+              segment,
+          ),
+        "",
+      );
+
+/** The files a run read and wrote, each named as the disk names it. */
+const respelled = (files: RunFiles, spell: (p: string) => string): RunFiles => {
+  const inputs = files.inputs.map((i) => ({ ...i, path: spell(i.path) }));
+  return {
+    ...files,
+    inputs: inputs.filter(
+      (i, n) => inputs.findIndex((j) => j.path === i.path) === n,
+    ),
+    written: distinct(files.written.map(spell)),
+  };
+};
+
+/** The bytes of a file of the paper by its path in the record, or null when it is not there. */
+const bytesOf =
+  (deps: RecordDeps, paperDir: string) =>
+  (p: string): Uint8Array | null =>
+    deps.files.readBytes(callerPath(resolve(paperDir, p)));
+
+const textOf =
+  (bytes: (p: string) => Uint8Array | null) =>
+  (p: string): string | null => {
+    const b = bytes(p);
+    return b === null ? null : new TextDecoder().decode(b);
+  };
+
+/** What the build's bibtex did, from the `.blg` and `.bbl` it left — or that it did not run. */
+function bibtexOf(
+  deps: RecordDeps,
+  text: (p: string) => string | null,
+  spell: (p: string) => string,
+  exit: number | null,
+): RecordedBibtex {
+  if (exit === null) return { ran: false };
+  const blg = text(`${JOBNAME}.blg`) ?? "";
+  const bbl = text(`${JOBNAME}.bbl`) ?? "";
+  const read = bibtexRead(blg, bbl);
+  return {
+    ran: true,
+    databases: distinct(read.databases.map((d) => spell(spelled(d)))),
+    keys: read.bibitems,
+    exit,
+    errors: deps.texOutput.blgErrors(blg),
+  };
+}
+
+/**
+ * The digest of every file the paper is made of: each input, and each database bibtex opened — one TeX
+ * wrote too, since the rules read it from disk and an edit to it after the build must read as a change.
+ * Null for one that is not there.
+ */
+function hashesOf(
+  inputs: readonly RecordedInput[],
+  databases: readonly string[],
+  bytes: (p: string) => Uint8Array | null,
+): SourcesRecord["sha256"] {
+  const paths = distinct([...inputs.map((i) => i.path), ...databases]);
+  return Object.fromEntries(
+    paths.map((p) => {
+      const b = bytes(p);
+      return [p, b === null ? null : sha256Hex(b)] as const;
+    }),
+  );
+}
+
+/** Why there is nothing to record, or null when the passes read the paper's files. */
+const nothingToRecord = (
+  run: TexRun,
+  inputs: readonly RecordedInput[],
+): string | null => {
+  if (run.fls.length === 0)
+    return `pdflatex wrote no ${JOBNAME}.fls — nothing to record`;
+  return inputs.length === 0
+    ? `${JOBNAME}.fls lists no file of the paper directory — nothing to record`
+    : null;
+};
+
+/** The record of a run whose passes read `files`: bibtex's part, the `.aux`'s, every digest. */
+function recordOf(
+  deps: RecordDeps,
+  paperDir: string,
+  run: TexRun,
+  files: RunFiles,
+): SourcesRecord {
+  const bytes = bytesOf(deps, paperDir);
+  const text = textOf(bytes);
+  const bibtex = bibtexOf(
+    deps,
+    text,
+    spelledOnDisk(deps.listDir, paperDir),
+    run.bibtexExit,
+  );
+  return {
+    schema: SOURCES_SCHEMA,
+    inputs: files.inputs,
+    written: files.written,
+    bibdata: auxBib(text(`${JOBNAME}.aux`) ?? "", text).databases,
+    bibtex,
+    sha256: hashesOf(files.inputs, bibtex.ran ? bibtex.databases : [], bytes),
+  };
+}
+
+export function recordSources(
+  deps: RecordDeps,
+  paperDir: string,
+  run: TexRun,
+): Recorded {
+  const files = respelled(
+    filesOfRun(run.fls.map(deps.texOutput.fls), {
+      jobname: JOBNAME,
+      generated: run.bibtexExit === null ? [] : [`${JOBNAME}.bbl`],
+    }),
+    spelledOnDisk(deps.listDir, paperDir),
+  );
+  const why = nothingToRecord(run, files.inputs);
+  if (why !== null) return { kind: "not-recorded", why };
+  const record = recordOf(deps, paperDir, run, files);
+  const path = sourcesPath(paperDir);
+  deps.files.writeAtomic(
+    callerPath(path),
+    new TextEncoder().encode(serializeSourcesRecord(record)),
+  );
+  return { kind: "recorded", record, path };
+}
+
+/** `recordSources` over `deps`, as the `RecordSources` the build is handed. */
+export const sourcesRecorder =
+  (deps: RecordDeps): RecordSources =>
+  (paperDir, run) =>
+    recordSources(deps, paperDir, run);
+
+/** The line a build prints for a recording. */
+export const recordingNote = (r: Recorded): string =>
+  r.kind === "recorded"
+    ? `sources: ${String(r.record.inputs.length)} file${r.record.inputs.length === 1 ? "" : "s"} read → ${SOURCES_DIR}/${SOURCES_FILE}`
+    : `sources NOT recorded — ${r.why}; lint will say so`;

package/src/sources-rules.test.ts

@@ -0,0 +1,152 @@
+/**
+ * `paper/sources-fresh` (`src/sources-rules.ts`) on papers held in memory, the way ESLint runs the rule:
+ * `create`, then `root:exit`. Both halves: a paper with no record, an unreadable one, or one the
+ * paper has changed since is reported once, at the top of `paper.tex`, saying what to run; a paper
+ * whose record is current is not, and neither is any file but `paper.tex`.
+ */
+import { describe, expect, it } from "vitest";
+import { memoryFiles } from "./adapters/memory/index.ts";
+import { sourcesCodec } from "./adapters/sources-record/index.ts";
+import { sha256Hex } from "./domain/sha256.ts";
+import {
+  serializeSourcesRecord,
+  type SourcesRecord,
+} from "./domain/sources-record.ts";
+import { SOURCES_RULE_LEVELS, sourcesRules } from "./sources-rules.ts";
+import { builtFixture } from "../test/recorded-fixture.ts";
+
+const DIR = "/work/papers/p";
+const bytes = (s: string) => new TextEncoder().encode(s);
+
+const RECORD: SourcesRecord = {
+  schema: 1,
+  inputs: [
+    { path: "paper.tex", role: "body" },
+    { path: "sections/a.tex", role: "body" },
+  ],
+  written: [],
+  bibdata: [],
+  bibtex: { ran: false },
+  sha256: {
+    "paper.tex": sha256Hex(bytes("main")),
+    "sections/a.tex": sha256Hex(bytes("a")),
+  },
+};
+const FRESH = {
+  [`${DIR}/paper.tex`]: "main",
+  [`${DIR}/sections/a.tex`]: "a",
+  [`${DIR}/_build/sources.json`]: serializeSourcesRecord(RECORD),
+};
+
+interface Reported {
+  readonly messageId: string;
+  readonly message: string;
+  readonly line: number;
+}
+
+/** The rule over one file of the paper directory, the way ESLint runs it. */
+function lint(
+  tree: Record<string, string>,
+  file = "paper.tex",
+): readonly Reported[] {
+  const rule = sourcesRules({
+    files: memoryFiles(tree),
+    codec: sourcesCodec,
+  })["sources-fresh"];
+  const out: Reported[] = [];
+  const visitor = rule.create({
+    filename: `${DIR}/${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(v),
+        template,
+      );
+      out.push({ messageId: d.messageId, message, line: d.loc.start.line });
+    },
+  });
+  visitor["root:exit"]?.();
+  return out;
+}
+
+describe("paper/sources-fresh — reports", () => {
+  it("a paper no build has recorded is reported 'not built', and what that leaves unlinted", () => {
+    expect(
+      lint({ [`${DIR}/paper.tex`]: "main" }).map((r) => [
+        r.messageId,
+        r.message,
+        r.line,
+      ]),
+    ).toEqual([
+      [
+        "notBuilt",
+        "the paper has not been built — run `npx paperlint build`, which records the files TeX reads. Until it has, the files `paper.tex` includes are not linted, and the rules that read the bibliography say nothing",
+        1,
+      ],
+    ]);
+  });
+
+  it("a record this paperlint cannot read is reported, with why", () => {
+    expect(
+      lint({
+        ...FRESH,
+        [`${DIR}/_build/sources.json`]: '{"schema":2}',
+      }).map((r) => [r.messageId, r.message]),
+    ).toEqual([
+      [
+        "unreadable",
+        "the last build's record cannot be used (sources.json is schema 2, this paperlint reads schema 1) — run `npx paperlint build`; until then the files `paper.tex` includes are not linted, and the rules that read the bibliography say nothing",
+      ],
+    ]);
+  });
+
+  it("a paper changed since the build is reported, naming what changed", () => {
+    expect(
+      lint({ ...FRESH, [`${DIR}/sections/a.tex`]: "edited" }).map((r) => [
+        r.messageId,
+        r.message,
+      ]),
+    ).toEqual([
+      [
+        "stale",
+        "the paper changed since the last build (sections/a.tex edited) — run `npx paperlint build`; until then the files `paper.tex` includes are not linted, and the rules that read the bibliography say nothing",
+      ],
+    ]);
+  });
+});
+
+describe("paper/sources-fresh — a .tex TeX wrote from a filecontents block", () => {
+  it("🔴 is a file of the paper: current as the build left it, stale once it is gone or edited", () => {
+    // v29-generated-input: the block in paper.tex wrote body.tex, and the body \input's it.
+    const built = builtFixture("v29-generated-input", DIR);
+    const cleaned = Object.fromEntries(
+      Object.entries(built).filter(([p]) => p !== `${DIR}/body.tex`),
+    );
+    expect([
+      lint(built),
+      lint(cleaned).map((r) => r.message),
+      lint({ ...built, [`${DIR}/body.tex`]: "edited\n" }).map(
+        (r) => r.messageId,
+      ),
+    ]).toEqual([
+      [],
+      [expect.stringContaining("(body.tex deleted)")],
+      ["stale"],
+    ]);
+  });
+});
+
+describe("paper/sources-fresh — silent", () => {
+  it("a paper whose record is current is not reported", () => {
+    expect(lint(FRESH)).toEqual([]);
+  });
+
+  it("only paper.tex is judged: a record that is missing is not reported on another file", () => {
+    expect(lint({ [`${DIR}/other.tex`]: "x" }, "other.tex")).toEqual([]);
+  });
+
+  it("the rule is on, as a warning: lint often runs where nothing is built", () => {
+    expect(SOURCES_RULE_LEVELS).toEqual({ "paper/sources-fresh": "warn" });
+  });
+});