paperlint 8.0.0 → 9.0.1

package/src/domain/paper-sources.ts

@@ -0,0 +1,94 @@
+/**
+ * WHAT A DATABASE IS — the values the bibtex reader (`BibReader`, src/ports/bib-reader.ts) returns for
+ * a `.bib`, or for the body of a `filecontents` block: its entries, and the bytes bibtex takes from
+ * them. Which databases a paper reads is TeX's answer, recorded by the build (`_build/sources.json`,
+ * src/domain/sources-record.ts, docs/design/paper-sources.md §1); nothing here decides it.
+ */
+import type { AbsolutePath } from "./paths.ts";
+import type { Span } from "./tex-document.ts";
+
+/** The main file's name — the file TeX is given. */
+export const MAIN_FILE = "paper.tex";
+
+/** A name in a name list (`author`, `editor`), split into its parts as BibTeX defines them. */
+export interface BibName {
+  readonly lastName?: string;
+  readonly firstName?: string;
+  readonly prefix?: string;
+  readonly suffix?: string;
+  /** A name written as one unit (`{World Health Organization}`). */
+  readonly name?: string;
+}
+
+/**
+ * The `@string`s in force: each name as bibtex folds it (upper case) → its value as bibtex takes it,
+ * the `@string`s it used expanded and its LaTeX as written. bibtex reads a paper's databases one after
+ * the other with one table of them, so a `@string` an earlier database defines is in force in a later
+ * one (measured: `\\bibliography{abbreviations,references}` typesets an entry of `references.bib` with
+ * the author and booktitle `abbreviations.bib` defines; in the other order both are undefined).
+ */
+export type BibStrings = Readonly<Record<string, string>>;
+
+/** One entry of a database. */
+export interface BibEntry {
+  /** Lower-cased (`@Article` → `article`). */
+  readonly type: string;
+  readonly key: string;
+  /** From its `@` to its closing brace or parenthesis, in the text of the file that holds it. */
+  readonly span: Span;
+  /** Its fields, LaTeX read into text (`{\"u}` → `ü`, `\url{x}` → a link); a list field joined by ` and `. */
+  readonly fields: Readonly<Record<string, string>>;
+  /** Its name lists (`author`, `editor`, …), each name split into its parts. */
+  readonly names: Readonly<Record<string, readonly BibName[]>>;
+}
+
+/** The bytes of one database, where they sit, and what the reader read from them. */
+export interface BibText {
+  /** The file holding the bytes: the `.bib`, or the `.tex` that holds the block. */
+  readonly path: AbsolutePath;
+  /** That file's whole text; every span here is an offset into it. */
+  readonly text: string;
+  /** The database inside `text`: all of it for a `.bib`, the body for a block. */
+  readonly body: Span;
+  readonly entries: readonly BibEntry[];
+  /** The same entries as bibtex takes them, in order: what two databases are compared by. */
+  readonly written: readonly WrittenEntry[];
+  /** The `@preamble` commands, as written, in order: bibtex writes them into the `.bbl`. */
+  readonly preamble: readonly string[];
+  /** The `@string`s the databases bibtex read before this one left in force: none for one read alone. */
+  readonly inherited: BibStrings;
+  /** The `@string`s in force after it — `inherited` and its own, a later one winning: what the next database starts with. */
+  readonly strings: BibStrings;
+}
+
+/**
+ * An entry as bibtex takes it from the database: the type, the key, and each field's value with the
+ * `@string`s it uses expanded where it uses them (a later redefinition changes nothing) and its LaTeX
+ * as written — `{\"o}` and `ö` are different values here, as they are in the `.bbl` bibtex writes.
+ */
+export interface WrittenEntry {
+  /** Lower-cased, as bibtex reads it. */
+  readonly type: string;
+  readonly key: string;
+  /** Whitespace runs folded to one space, as bibtex folds them. */
+  readonly fields: Readonly<Record<string, string>>;
+}
+
+/**
+ * What bibtex takes from a database, for comparing two: each entry as bibtex reads it, in order, its
+ * fields in name order, and the `@preamble` commands. Nothing else in the bytes reaches the `.bbl`:
+ * not the text between entries (a `filecontents` header among it), not a `@string` no entry uses.
+ */
+const contentOf = (b: BibText): string =>
+  JSON.stringify([
+    b.written.map((e) => [
+      e.type,
+      e.key,
+      Object.entries(e.fields).sort(([x], [y]) => x.localeCompare(y)),
+    ]),
+    b.preamble,
+  ]);
+
+/** Whether two databases hold the same, as TeX's own copy of a block holds the block's. */
+export const sameDatabase = (a: BibText, b: BibText): boolean =>
+  contentOf(a) === contentOf(b);

package/src/domain/sources-record.test.ts

@@ -0,0 +1,71 @@
+/**
+ * The record of a build as a value: the one text it is parsed from, what a rule reads off it, and what
+ * changed since it was made. The files it is about are `src/sources-record.test.ts`'s.
+ */
+import { describe, expect, it } from "vitest";
+import { parseSha256 } from "./sha256.ts";
+import {
+  changesSince,
+  describeChanges,
+  serializeSourcesRecord,
+  type SourcesRecord,
+} from "./sources-record.ts";
+
+const A = "a".repeat(64);
+const B = "b".repeat(64);
+
+const RECORD: SourcesRecord = {
+  schema: 1,
+  inputs: [
+    { path: "paper.tex", role: "body" },
+    { path: "macros.tex", role: "preamble" },
+    { path: "sections/intro.tex", role: "body" },
+  ],
+  written: ["refs.bib"],
+  bibdata: ["refs"],
+  bibtex: {
+    ran: true,
+    databases: ["refs.bib"],
+    keys: ["k1"],
+    exit: 2,
+    errors: [{ message: "bad", file: "refs.bib", line: 4 }],
+  },
+  sha256: { "paper.tex": A, "macros.tex": null },
+};
+
+describe("serializing a record", () => {
+  it("is two-space JSON with a final newline, so a diff of two builds reads", () => {
+    expect(serializeSourcesRecord({ ...RECORD, bibtex: { ran: false } })).toBe(
+      `${JSON.stringify({ ...RECORD, bibtex: { ran: false } }, null, 2)}\n`,
+    );
+  });
+});
+
+describe("what changed since the record", () => {
+  const now = (files: Readonly<Record<string, string>>) => (p: string) =>
+    files[p] === undefined ? null : parseSha256(files[p]);
+
+  it("a record whose files are as hashed has no change, a file absent then and now included", () => {
+    expect(changesSince(RECORD, now({ "paper.tex": A }))).toEqual([]);
+  });
+
+  it("an edited file, a deleted one, and a file that appeared where there was none", () => {
+    expect(changesSince(RECORD, now({ "macros.tex": B }))).toEqual([
+      { path: "paper.tex", change: "deleted" },
+      { path: "macros.tex", change: "added" },
+    ]);
+    expect(changesSince(RECORD, now({ "paper.tex": B }))).toEqual([
+      { path: "paper.tex", change: "edited" },
+    ]);
+  });
+
+  it("names the changes in a line a finding can carry", () => {
+    expect(
+      describeChanges([
+        { path: "paper.tex", change: "edited" },
+        { path: "sections/a.tex", change: "deleted" },
+      ]),
+    ).toBe("paper.tex edited, sections/a.tex deleted");
+    expect(describeChanges([])).toBe("");
+  });
+});

package/src/domain/sources-record.ts

@@ -0,0 +1,136 @@
+/**
+ * WHAT THE LAST BUILD READ — `<paper>/_build/sources.json`, written by `paperlint build` from TeX's
+ * own files (docs/design/paper-sources.md §1) and read, offline, by the rules that need to know which
+ * files make up a paper and which bibliography it uses. Nothing else answers either question: no
+ * code of paperlint reads TeX source to decide them.
+ *
+ *   { "schema": 1,
+ *     "inputs":  [ { "path": "paper.tex", "role": "body" }, … ],  the files of the paper directory TeX
+ *                                                                 read, in first-read order
+ *     "written": [ "refs.bib" ],                                  the `.bib` and `.tex` files TeX wrote (filecontents)
+ *     "bibdata": [ "refs" ],                                      what `\bibdata` told bibtex to read
+ *     "bibtex":  { "ran": true, "databases": [ "refs.bib" ],      the files bibtex opened, the keys it
+ *                  "keys": [ … ], "exit": 0, "errors": [] },      typeset, how it ended
+ *     "sha256":  { "paper.tex": "…", … } }                        every input and every database bibtex
+ *                                                                 opened, by path and bytes
+ *
+ * 🔴 A role is the file's, and the main file is the body. A file is `preamble` when TeX read it only
+ * before `\begin{document}` — before it opened `paper.aux` for writing (measured) — and `body` when
+ * any read of it came after. The main file, the first one read, is `body` whatever its place in that
+ * order: it holds `\begin{document}` itself.
+ *
+ * The text of the file is checked once, where it enters: `SourcesCodec` (`src/ports/sources-codec.ts`),
+ * whose adapter holds the zod schema of this shape. The domain holds the value.
+ *
+ * 🔴 STALENESS is the record's own question: `changesSince` compares the bytes now with `sha256`, one
+ * key per file, so a rule can tell that the paper changed after the build without running TeX. A `.bib`
+ * TeX wrote is hashed too: the rules read it from disk, so an edit to it after the build is a change.
+ */
+import type { Sha256 } from "./sha256.ts";
+
+export const SOURCES_SCHEMA = 1;
+export const SOURCES_DIR = "_build";
+export const SOURCES_FILE = "sources.json";
+
+/** The job name every file a build writes carries (`paper.aux`, `paper.fls`): the build names its job so. */
+export const JOBNAME = "paper";
+
+/** Before or after `\begin{document}`. */
+export type InputRole = "preamble" | "body";
+
+/** One file of the paper directory that TeX read. `path` is relative to it, with forward slashes. */
+export interface RecordedInput {
+  readonly path: string;
+  readonly role: InputRole;
+}
+
+/** One error bibtex reported, as its `.blg` says it. */
+export interface BibtexError {
+  readonly message: string;
+  /** The file it was reading (`refs.bib`, `paper.aux`). */
+  readonly file: string;
+  /** Null when bibtex named no line. */
+  readonly line: number | null;
+}
+
+/** What the build's bibtex did — or that the build ran none (the paper names no database). */
+export type RecordedBibtex =
+  | { readonly ran: false }
+  | {
+      readonly ran: true;
+      /** The database files it opened, as it names them (`refs.bib`, `bibs/x.bib`). */
+      readonly databases: readonly string[];
+      /** The keys it typeset: every `\bibitem` of the `.bbl`. */
+      readonly keys: readonly string[];
+      readonly exit: number;
+      readonly errors: readonly BibtexError[];
+    };
+
+export interface SourcesRecord {
+  readonly schema: typeof SOURCES_SCHEMA;
+  readonly inputs: readonly RecordedInput[];
+  readonly written: readonly string[];
+  readonly bibdata: readonly string[];
+  readonly bibtex: RecordedBibtex;
+  /** Path → digest of its bytes; null for a file that was not there when the record was made. */
+  readonly sha256: Readonly<Record<string, string | null>>;
+}
+
+export type ParsedRecord =
+  | { readonly ok: true; readonly record: SourcesRecord }
+  | { readonly ok: false; readonly why: string };
+
+/** The record as the file holds it: two-space JSON and a final newline, so a diff of two builds reads. */
+export const serializeSourcesRecord = (r: SourcesRecord): string =>
+  `${JSON.stringify(r, null, 2)}\n`;
+
+// ── staleness ───────────────────────────────────────────────────────────────────────────
+
+export type ChangeKind = "edited" | "deleted" | "added";
+
+/** One file whose bytes are not those the build hashed. */
+export interface Change {
+  readonly path: string;
+  readonly change: ChangeKind;
+}
+
+/**
+ * The files whose bytes now differ from the record's: edited, deleted, or present where the record saw
+ * none. `now` answers for one path with the digest of its bytes, or null when there is no such file.
+ * Empty when the record is current.
+ */
+export function changesSince(
+  r: SourcesRecord,
+  now: (path: string) => Sha256 | null,
+): readonly Change[] {
+  return Object.entries(r.sha256).flatMap(
+    ([path, recorded]): readonly Change[] => {
+      const current = now(path);
+      if (current === recorded) return [];
+      if (current === null) return [{ path, change: "deleted" }];
+      return [{ path, change: recorded === null ? "added" : "edited" }];
+    },
+  );
+}
+
+/** `paper.tex edited, sections/a.tex deleted` — what a finding names. */
+export const describeChanges = (cs: readonly Change[]): string =>
+  cs.map((c) => `${c.path} ${c.change}`).join(", ");
+
+/**
+ * The name among `names` that `name` stands for: `name` itself, else the one name equal to it ignoring
+ * case — null when there is none, or several. TeX opens a file by the name the source gives it; on a
+ * file system that ignores case that is the source's spelling, on one that does not TeX retries
+ * without case, and the record holds the disk's spelling either way. A name and the record's spelling
+ * of it are matched by this, once, wherever one is looked up in the other.
+ */
+export function spelledIn(
+  names: readonly string[],
+  name: string,
+): string | null {
+  if (names.includes(name)) return name;
+  const [only, ...more] = names.filter(
+    (n) => n.toLowerCase() === name.toLowerCase(),
+  );
+  return only !== undefined && more.length === 0 ? only : null;
+}

package/src/domain/tex-run.test.ts

@@ -0,0 +1,228 @@
+/**
+ * Which files of the paper directory a build's TeX passes read, and which `.bib` files they wrote —
+ * decided from the `.fls` lines of each pass. The inputs are `.fls` files captured whole from real
+ * runs of the planted papers (test/fixtures/tex-output/README.md); the few shapes no planted paper
+ * has are written out, and say so.
+ */
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { texOutput } from "../adapters/tex-output/index.ts";
+import { filesOfRun } from "./tex-run.ts";
+
+const CAPTURES = join(
+  dirname(dirname(dirname(fileURLToPath(import.meta.url)))),
+  "test",
+  "fixtures",
+  "tex-output",
+);
+/** A planted paper's passes, as `.fls` text → lines, in the order they ran. */
+const passes = (paper: string) =>
+  ["first-pass.fls", "paper.fls"].map((f) =>
+    texOutput.fls(readFileSync(join(CAPTURES, paper, f), "utf8")),
+  );
+const BIBTEX_RAN = { jobname: "paper", generated: ["paper.bbl"] };
+
+describe("the files a build's TeX read", () => {
+  it("a paper of one file: the main file, a body", () => {
+    expect(filesOfRun(passes("v3-declared"), BIBTEX_RAN)).toEqual({
+      inputs: [{ path: "paper.tex", role: "body" }],
+      written: [],
+    });
+  });
+
+  it("an include read after \\begin{document} is body, a database TeX read before it is preamble — in first-read order", () => {
+    expect(filesOfRun(passes("p1"), BIBTEX_RAN)).toEqual({
+      inputs: [
+        { path: "paper.tex", role: "body" },
+        { path: "refs.bib", role: "preamble" },
+        { path: "sections/intro.tex", role: "body" },
+      ],
+      written: [],
+    });
+  });
+
+  it("a file read before \\begin{document} and never after is preamble", () => {
+    expect(filesOfRun(passes("v16-included-block"), BIBTEX_RAN)).toEqual({
+      inputs: [
+        { path: "paper.tex", role: "body" },
+        { path: "bibblock.tex", role: "preamble" },
+        { path: "refs.bib", role: "preamble" },
+      ],
+      written: [],
+    });
+  });
+});
+
+describe("the .bib files TeX wrote", () => {
+  it("a .bib TeX wrote (filecontents) is written, and is no input: its bytes are the block's", () => {
+    expect(filesOfRun(passes("v8-jobname"), BIBTEX_RAN)).toEqual({
+      inputs: [{ path: "paper.tex", role: "body" }],
+      written: ["paper.bib"],
+    });
+  });
+
+  it("🔴 a block writes its file on the first pass only (the later passes find it there and read it): the last pass alone would list it as an input and not as written", () => {
+    const [first, last] = passes("plain-block");
+    expect(last?.lines.filter((l) => l.path.endsWith(".bib"))).toEqual([
+      { op: "INPUT", path: "./refs.bib" },
+      { op: "INPUT", path: "refs.bib" },
+    ]);
+    expect(filesOfRun(passes("plain-block"), BIBTEX_RAN)).toEqual({
+      inputs: [{ path: "paper.tex", role: "body" }],
+      written: ["refs.bib"],
+    });
+    expect(first?.lines.filter((l) => l.path.endsWith(".bib"))).toEqual([
+      { op: "OUTPUT", path: "refs.bib" },
+    ]);
+  });
+});
+
+describe("a .tex TeX wrote and then read — the paper's text, generated", () => {
+  it("🔴 a block that writes a .tex the body \\input's: the file is written AND an input, a body file — its text is in the PDF", () => {
+    // v29-generated-input: pass 1 writes body.tex and reads it after \begin{document}; the later
+    // passes find it there, read it in the preamble (the block's check) and again in the body.
+    const [first, last] = passes("v29-generated-input");
+    expect(first?.lines.filter((l) => l.path.endsWith("body.tex"))[0]).toEqual({
+      op: "OUTPUT",
+      path: "body.tex",
+    });
+    expect(
+      last?.lines.some((l) => l.op === "OUTPUT" && l.path === "body.tex"),
+    ).toBe(false);
+    expect(filesOfRun(passes("v29-generated-input"), BIBTEX_RAN)).toEqual({
+      inputs: [
+        { path: "paper.tex", role: "body" },
+        { path: "body.tex", role: "body" },
+      ],
+      written: ["body.tex"],
+    });
+  });
+
+  it("with [overwrite] the last pass writes it again before reading it: still an input", () => {
+    const fls = texOutput.fls(
+      [
+        "PWD /work/paper",
+        "INPUT paper.tex",
+        "INPUT ./body.tex",
+        "OUTPUT body.tex",
+        "OUTPUT paper.aux",
+        "INPUT ./body.tex",
+      ].join("\n"),
+    );
+    expect(filesOfRun([fls], BIBTEX_RAN)).toEqual({
+      inputs: [
+        { path: "paper.tex", role: "body" },
+        { path: "body.tex", role: "body" },
+      ],
+      written: ["body.tex"],
+    });
+  });
+});
+
+describe("what is not the paper's: its TeX tree, a sibling directory, what TeX writes", () => {
+  it("the .bbl bibtex wrote is no input of the paper; with no bibtex run it is a file TeX read, and so is one", () => {
+    const last = passes("v3-declared");
+    expect(
+      filesOfRun(last, { jobname: "paper", generated: [] }).inputs,
+    ).toEqual([
+      { path: "paper.tex", role: "body" },
+      { path: "paper.bbl", role: "body" },
+    ]);
+  });
+
+  it("files the paper's TeX tree supplies are not the paper's: only the paper directory's files are listed", () => {
+    const fls = texOutput.fls(
+      [
+        "PWD /work/paper",
+        "INPUT /usr/share/texlive/texmf-dist/tex/latex/base/article.cls",
+        "INPUT paper.tex",
+        "INPUT /work/paper/inside.tex",
+        "INPUT ../shared/outside.tex",
+        "INPUT /elsewhere/other.tex",
+        "OUTPUT paper.aux",
+      ].join("\n"),
+    );
+    expect(
+      filesOfRun([fls], { jobname: "paper", generated: [] }).inputs,
+    ).toEqual([
+      { path: "paper.tex", role: "body" },
+      { path: "inside.tex", role: "preamble" },
+    ]);
+  });
+});
+
+describe("an .fls with no directory, and a name that merely starts with dots", () => {
+  it("an .fls that names no directory lists the files named relative to it and no absolute path", () => {
+    const fls = texOutput.fls(
+      "INPUT /usr/share/texlive/article.cls\nINPUT paper.tex\nINPUT ..x.tex\n",
+    );
+    expect(
+      filesOfRun([fls], { jobname: "paper", generated: [] }).inputs,
+    ).toEqual([
+      { path: "paper.tex", role: "body" },
+      { path: "..x.tex", role: "preamble" },
+    ]);
+  });
+});
+
+describe("roles on the edges: both places, no body, no passes", () => {
+  it("a file read in the preamble and again in the body is body: its first read alone would drop it from the prose", () => {
+    const fls = texOutput.fls(
+      [
+        "PWD /work/paper",
+        "INPUT paper.tex",
+        "INPUT ./macros.tex",
+        "OUTPUT paper.aux",
+        "INPUT ./macros.tex",
+        "INPUT ./intro.tex",
+      ].join("\n"),
+    );
+    expect(
+      filesOfRun([fls], { jobname: "paper", generated: [] }).inputs,
+    ).toEqual([
+      { path: "paper.tex", role: "body" },
+      { path: "macros.tex", role: "body" },
+      { path: "intro.tex", role: "body" },
+    ]);
+  });
+
+  it("a run that stopped before opening the .aux has no body: everything but the main file is preamble", () => {
+    const fls = texOutput.fls(
+      "PWD /work/paper\nINPUT paper.tex\nINPUT ./a.tex\nINPUT ./b.tex\n",
+    );
+    expect(
+      filesOfRun([fls], { jobname: "paper", generated: [] }).inputs,
+    ).toEqual([
+      { path: "paper.tex", role: "body" },
+      { path: "a.tex", role: "preamble" },
+      { path: "b.tex", role: "preamble" },
+    ]);
+  });
+
+  it("a file TeX wrote on any pass is not an input, even one it also reads on a later pass (.toc, .out)", () => {
+    const first = texOutput.fls(
+      "PWD /w\nINPUT paper.tex\nOUTPUT paper.aux\nOUTPUT paper.toc\n",
+    );
+    const second = texOutput.fls(
+      "PWD /w\nINPUT paper.tex\nINPUT ./paper.toc\nOUTPUT paper.aux\n",
+    );
+    expect(
+      filesOfRun([first, second], { jobname: "paper", generated: [] }).inputs,
+    ).toEqual([{ path: "paper.tex", role: "body" }]);
+  });
+
+  it("no passes, or passes that opened nothing of the paper, list nothing", () => {
+    expect(filesOfRun([], { jobname: "paper", generated: [] })).toEqual({
+      inputs: [],
+      written: [],
+    });
+    expect(
+      filesOfRun([texOutput.fls("PWD /w\nINPUT /usr/x.cls\n")], {
+        jobname: "paper",
+        generated: [],
+      }),
+    ).toEqual({ inputs: [], written: [] });
+  });
+});

package/src/domain/tex-run.ts

@@ -0,0 +1,139 @@
+/**
+ * WHICH FILES A BUILD'S TeX PASSES READ — decided from the lines of each pass's `.fls` (pdflatex
+ * `-recorder`), not from any TeX source (docs/design/paper-sources.md §1).
+ *
+ *   inputs   the files of the paper directory the LAST pass read, in the order it first read them,
+ *            each a `preamble` or `body` file: before or after TeX opened `<jobname>.aux` for writing,
+ *            which `\begin{document}` does (measured). The main file, read first, is `body`.
+ *   written  the `.bib` and `.tex` files ANY pass wrote — a `filecontents` block's.
+ *
+ * 🔴 WHY THE LAST PASS FOR INPUTS AND EVERY PASS FOR WHAT WAS WRITTEN. A block without `[overwrite]`
+ * writes its file on the first pass only; the later passes find it there and read it (measured on TeX
+ * Live 2026: pass 1 `OUTPUT refs.bib`, passes 2 and 3 `INPUT refs.bib`, no OUTPUT). The last pass alone
+ * would list TeX's own copy of a `.bib` as a file of the paper. And the first pass reads no `.aux`,
+ * `.toc` or `.out` yet, so only a later pass lists what the paper reads and the passes after it write.
+ *
+ * 🔴 A FILE TeX WROTE IS AN INPUT ONLY WHEN IT IS TeX SOURCE OF THE PAPER: a `.tex`. A block that
+ * writes `body.tex` the body `\input`s puts that text in the PDF (measured: pass 1 `OUTPUT body.tex`
+ * then `INPUT ./body.tex` after `\begin{document}`; the later passes read it again), so it is an
+ * input like any other: hashed, spliced where its include stands. Every other file a pass wrote is
+ * TeX's bookkeeping or a database — its `.aux`, `.out` and `.toc`, a block's `.bib` — and is no input.
+ * A file another program wrote from TeX's output (`generated`: the `.bbl`, when bibtex ran) is none
+ * either.
+ */
+import { isAbsolute, posix } from "node:path";
+import type { RecordedInput } from "./sources-record.ts";
+
+/** One line of an `.fls`: TeX opened a file to read it, or to write it. */
+export interface FlsLine {
+  readonly op: "INPUT" | "OUTPUT";
+  /** As TeX named the file: `./a.tex` and `a.tex` for one file, an absolute path for the TeX tree's. */
+  readonly path: string;
+}
+
+/** A pdflatex `-recorder` file: where it ran, and every file it opened, in order. */
+export interface Fls {
+  /** The directory pdflatex ran in, or null when the file names none. */
+  readonly pwd: string | null;
+  readonly lines: readonly FlsLine[];
+}
+
+export interface RunFiles {
+  readonly inputs: readonly RecordedInput[];
+  readonly written: readonly string[];
+}
+
+/**
+ * `path` as TeX named it → relative to the paper directory with forward slashes, or null when the file
+ * is not in it: the TeX tree's, a file of a sibling directory, an absolute path outside `pwd`.
+ */
+function inPaperDir(path: string, pwd: string | null): string | null {
+  const rel = isAbsolute(path)
+    ? pwd === null
+      ? null
+      : posix.relative(pwd, path)
+    : posix.normalize(path);
+  // `..` or `../x`: a file of a sibling directory. (`..x` is a file of this one.)
+  return rel === null || rel.split("/")[0] === ".." ? null : rel;
+}
+
+const distinct = <T>(xs: readonly T[]): readonly T[] => [...new Set(xs)];
+
+/** A file TeX writes that the record names: TeX source of the paper (`.tex`) or a database (`.bib`). */
+const isTexSource = (path: string): boolean => posix.extname(path) === ".tex";
+const isRecordedWrite = (path: string): boolean =>
+  isTexSource(path) || posix.extname(path) === ".bib";
+
+type Opened = FlsLine & { readonly rel: string };
+
+/** The files of the paper directory a pass opened, with the op, in order. */
+const opened = (pass: Fls): readonly Opened[] =>
+  pass.lines.flatMap((l) => {
+    const rel = inPaperDir(l.path, pass.pwd);
+    return rel === null ? [] : [{ ...l, rel }];
+  });
+
+export interface RunOptions {
+  /** The job name: `<jobname>.aux` is the file whose opening marks `\begin{document}`. */
+  readonly jobname: string;
+  /** Files other programs wrote from TeX's own output, relative to the paper directory (`paper.bbl`). */
+  readonly generated: readonly string[];
+}
+
+/** One read of a file of the paper, and whether it came after `\begin{document}`. */
+interface Read {
+  readonly path: string;
+  readonly afterBegin: boolean;
+}
+
+/**
+ * The reads of the last pass: INPUT lines of files nothing wrote, or that a pass wrote as TeX source,
+ * each with its place against the line that opens `<jobname>.aux` — `\begin{document}`. No such line
+ * (the run stopped first): none is after it.
+ */
+function readsOf(
+  last: readonly Opened[],
+  outputs: ReadonlySet<string>,
+  { jobname, generated }: RunOptions,
+): readonly Read[] {
+  const boundary = last.findIndex(
+    (l) => l.op === "OUTPUT" && l.rel === `${jobname}.aux`,
+  );
+  return last.flatMap((l, i) =>
+    l.op === "INPUT" &&
+    (!outputs.has(l.rel) || isTexSource(l.rel)) &&
+    !generated.includes(l.rel)
+      ? [{ path: l.rel, afterBegin: boundary >= 0 && i > boundary }]
+      : [],
+  );
+}
+
+export function filesOfRun(
+  passes: readonly Fls[],
+  options: RunOptions,
+): RunFiles {
+  const everyPass = passes.flatMap(opened);
+  const wrote = (l: Opened): boolean => l.op === "OUTPUT";
+  const outputs = new Set(everyPass.filter(wrote).map((l) => l.rel));
+  const last = passes.at(-1);
+  const reads = readsOf(
+    last === undefined ? [] : opened(last),
+    outputs,
+    options,
+  );
+  // The main file holds `\begin{document}` itself, so it is body wherever TeX opened it.
+  const body = (path: string): boolean =>
+    path === reads[0]?.path ||
+    reads.some((r) => r.path === path && r.afterBegin);
+  return {
+    inputs: distinct(reads.map((r) => r.path)).map((path): RecordedInput => ({
+      path,
+      role: body(path) ? "body" : "preamble",
+    })),
+    written: distinct(
+      everyPass
+        .filter((l) => wrote(l) && isRecordedWrite(l.rel))
+        .map((l) => l.rel),
+    ),
+  };
+}