paperlint 2.0.0

package/src/latex-loop.harness.mjs

@@ -0,0 +1,449 @@
+/**
+ * `latex-loop.ts` — three tables, in order:
+ *   1. `nextStep` over a `State`: one row per question, plus the cap;
+ *   2. `summarize` over histories: one row per field;
+ *   3. the two composed, over the histories the loop really sees — the behaviour the build has.
+ * A defect in `nextStep` fails in table 1, one in `summarize` in table 2, before table 3 runs.
+ *
+ * The decision is pure, so none of this needs TeX. The real-pdflatex half lives in
+ * `test/e2e/build.mjs`.
+ */
+import assert from "node:assert/strict";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const { nextStep, summarize, changedFiles, MAX_PASSES } = await import(
+  join(HERE, "latex-loop.ts")
+);
+
+let n = 0;
+const check = (label, cond) => {
+  assert.ok(cond, label);
+  n++;
+};
+
+// ── builders ────────────────────────────────────────────────────────────────────────────
+const H = (aux, toc = null, out = null, bbl = null) => ({ aux, toc, out, bbl });
+const NO_BIB = { kind: "none" };
+const bib = (citations, bibHash = "b1") => ({
+  kind: "needed",
+  citations,
+  databases: ["refs"],
+  style: "plain",
+  bibHash,
+});
+const latex = (o = {}) => ({
+  step: "latex",
+  final: false,
+  exitCode: 0,
+  before: H("a1"),
+  after: H("a1"),
+  markers: [],
+  bib: NO_BIB,
+  errorLines: [],
+  ...o,
+});
+const bibtex = (o = {}) => ({
+  step: "bibtex",
+  exitCode: 0,
+  before: H("a1"),
+  after: H("a1", null, null, "bbl1"),
+  bib: bib(["k"]),
+  errorLines: [],
+  ...o,
+});
+const kind = (s) =>
+  s.kind === "latex" ? `latex${s.final ? "-final" : ""}` : s.kind;
+
+// ── 1. nextStep over a State ─────────────────────────────────────────────────────────────
+const S = (o = {}) => ({
+  failed: null,
+  bibOutdated: false,
+  unsettled: [],
+  latexPasses: 1,
+  finalDone: false,
+  warnings: [],
+  ...o,
+});
+const exitFail = {
+  step: "bibtex",
+  cause: { kind: "exit", code: 2 },
+  lines: ["I couldn't open database file nope.bib"],
+};
+const STATES = [
+  // Guards: the only moment paper-guards can speak — its error comes on the final pass, so testing
+  // 'final' before 'exit code' would ship the undefined reference green.
+  [
+    "Q1 the last program failed — fail, whatever else holds",
+    S({
+      failed: exitFail,
+      bibOutdated: true,
+      unsettled: ["paper.aux"],
+      finalDone: true,
+    }),
+    "fail",
+  ],
+  ["the final pass ran clean — done", S({ finalDone: true }), "done"],
+  // Guards: running bibtex at all — the first pass writes the \citation list; without this question
+  // the loop reruns pdflatex, never produces a .bbl, and every \cite stays undefined.
+  [
+    "Q2 the bibliography input moved since bibtex ran — bibtex, before any rerun",
+    S({ bibOutdated: true, unsettled: ["paper.aux"] }),
+    "bibtex",
+  ],
+  [
+    "Q3 a tracked file moved or the log asked — another plain pass",
+    S({ unsettled: ["paper.aux"] }),
+    "latex",
+  ],
+  // Guards: the stop on a document that never settles — without it the loop runs forever; with a
+  // silent cap it ships a PDF with stale cross-references.
+  [
+    `Q3 cap: ${MAX_PASSES} passes and still unsettled — fail`,
+    S({ unsettled: ["paper.aux"], latexPasses: MAX_PASSES }),
+    "fail",
+  ],
+  // Guards: the \finalpass run that arms paper-guards.tex — skipping it saves one pdflatex run and
+  // turns every undefined \ref and \cite back into a green build.
+  [
+    "Q4 nothing unsettled — the FINAL pass (even at the cap)",
+    S({ latexPasses: MAX_PASSES }),
+    "latex-final",
+  ],
+];
+for (const [label, state, expected] of STATES) {
+  const got = kind(nextStep(state));
+  check(`${label} (expected ${expected}, got ${got})`, got === expected);
+}
+const q1 = nextStep(S({ failed: exitFail }));
+check(
+  "Q1 passes the failure through: the step, the cause and the lines verbatim",
+  q1.step === "bibtex" && q1.cause.code === 2 && q1.lines === exitFail.lines,
+);
+const q3cap = nextStep(
+  S({ unsettled: ["paper.aux", "labels-changed"], latexPasses: MAX_PASSES }),
+);
+check(
+  "the cap's failure is no-convergence and NAMES what stayed unsettled",
+  q3cap.cause.kind === "no-convergence" &&
+    q3cap.lines[0].includes("paper.aux, labels-changed"),
+);
+check(
+  "done carries the state's warnings",
+  nextStep(S({ finalDone: true, warnings: ["undefined-citations"] }))
+    .warnings[0] === "undefined-citations",
+);
+
+// ── 2. summarize over histories ─────────────────────────────────────────────────────────
+const sum = summarize;
+check(
+  "summarize: nothing ran — paper.aux is unsettled (no pass has written it), nothing else holds",
+  JSON.stringify(sum([])) ===
+    JSON.stringify({
+      failed: null,
+      bibOutdated: false,
+      unsettled: ["paper.aux"],
+      latexPasses: 0,
+      finalDone: false,
+      warnings: [],
+    }),
+);
+// Guards: failing on a failed pass — -halt-on-error stops pdflatex at the first error, and a loop
+// reading the half-written aux as progress would rerun it or call it converged.
+check(
+  "summarize: a non-zero exit is `failed`, naming the step, the code and the log excerpt",
+  (() => {
+    const f = sum([latex({ exitCode: 1, errorLines: ["l.4 \\foo"] })]).failed;
+    return (
+      f?.step === "latex" && f.cause.code === 1 && f.lines[0] === "l.4 \\foo"
+    );
+  })(),
+);
+check(
+  "summarize: a FINAL pass that exited non-zero is failed, not finalDone-and-clean",
+  sum([latex({ final: true, exitCode: 1 })]).failed !== null,
+);
+check(
+  "summarize: bibOutdated when the aux names a bibliography bibtex has not run on",
+  sum([latex({ bib: bib(["k"]) })]).bibOutdated === true,
+);
+check(
+  "summarize: bibOutdated is false once bibtex ran on exactly that input",
+  sum([latex({ bib: bib(["k"]) }), bibtex()]).bibOutdated === false,
+);
+// Guards: the .bib hash as an input — a corrected author or year in refs.bib would keep the old
+// .bbl, and the PDF would print the entry as it was before the fix.
+check(
+  "summarize: the .bib content changed since bibtex ran — bibOutdated",
+  sum([latex({ bib: bib(["k"]) }), bibtex(), latex({ bib: bib(["k"], "b2") })])
+    .bibOutdated === true,
+);
+check(
+  "summarize: no bibliography at all — never bibOutdated",
+  sum([latex()]).bibOutdated === false,
+);
+check(
+  "summarize: unsettled names every tracked file the last pass changed",
+  JSON.stringify(
+    sum([latex({ before: H("a1", "t1"), after: H("a2", "t2") })]).unsettled,
+  ) === JSON.stringify(["paper.aux", "paper.toc"]),
+);
+// Guards: the log's own request for another pass — a package that keeps state outside the tracked
+// files (longtable widths, hyperref outlines) speaks only through this line.
+check(
+  "summarize: marker: Rerun to get — unsettled names the rerun marker even with identical files",
+  JSON.stringify(sum([latex({ markers: ["rerun-requested"] })]).unsettled) ===
+    JSON.stringify(["rerun-requested"]),
+);
+// Guards: 'not settled yet' vs 'this key does not exist' — on stable files an undefined reference
+// never resolves, so rerunning for it burns the cap and reports no-convergence for a typo.
+check(
+  "summarize: undefined references ALONE leave nothing unsettled — on stable files they are a real bad key",
+  sum([latex({ markers: ["undefined-references"] })]).unsettled.length === 0,
+);
+check(
+  "summarize: bibtex that rewrote the .bbl leaves paper.bbl unsettled",
+  JSON.stringify(sum([latex({ bib: bib(["k"]) }), bibtex()]).unsettled) ===
+    JSON.stringify(["paper.bbl"]),
+);
+// Guards: reading bibtex's effect from the .bbl — a byte-identical .bbl changes nothing the next
+// pass would read.
+check(
+  "summarize: bibtex left the .bbl byte-identical — the pass before it answers",
+  sum([latex({ bib: bib(["k"]) }), bibtex({ after: H("a1") })]).unsettled
+    .length === 0,
+);
+check(
+  "summarize: latexPasses counts the non-final pdflatex passes only",
+  sum([latex(), bibtex(), latex(), latex({ final: true })]).latexPasses === 2,
+);
+check(
+  "summarize: finalDone and the undefined-reference warnings of the final log, nothing else",
+  (() => {
+    const s = sum([
+      latex(),
+      latex({
+        final: true,
+        markers: ["undefined-citations", "rerun-requested"],
+      }),
+    ]);
+    return (
+      s.finalDone &&
+      JSON.stringify(s.warnings) === JSON.stringify(["undefined-citations"])
+    );
+  })(),
+);
+
+// ── 3. composed: nextStep(summarize(history)) ───────────────────────────────────────────
+const step = (history) => nextStep(summarize(history));
+
+// ── the histories the loop sees ───────────────────────────────────────────────────────────────────────────
+const TABLE = [
+  ["nothing ran yet — the first step is a plain pass", [], "latex"],
+  [
+    "a pass that created the aux — rerun",
+    [latex({ before: H(null), after: H("a1") })],
+    "latex",
+  ],
+  [
+    "a pass whose tracked files did not change and whose log asks for nothing — converged, so the FINAL pass",
+    [latex({ before: H(null), after: H("a1") }), latex()],
+    "latex-final",
+  ],
+  ["the final pass exited 0 — done", [latex(), latex({ final: true })], "done"],
+  [
+    "a .toc change alone is a rerun",
+    [latex({ before: H("a1", "t1"), after: H("a1", "t2") })],
+    "latex",
+  ],
+  [
+    "a .out change alone is a rerun (hyperref bookmarks)",
+    [latex({ before: H("a1", null, "o1"), after: H("a1", null, "o2") })],
+    "latex",
+  ],
+  [
+    "marker: Rerun to get … — rerun even with identical files",
+    [latex({ markers: ["rerun-requested"] })],
+    "latex",
+  ],
+  [
+    "marker: Label(s) may have changed — rerun",
+    [latex({ markers: ["labels-changed"] })],
+    "latex",
+  ],
+  [
+    "marker: rerunfilecheck — rerun",
+    [latex({ markers: ["rerunfilecheck"] })],
+    "latex",
+  ],
+  [
+    "undefined references ALONE do not request a rerun — on stable files they are a real bad key",
+    [latex({ markers: ["undefined-references"] })],
+    "latex-final",
+  ],
+  [
+    "the aux names a bibliography bibtex has not run on — bibtex",
+    [latex({ before: H(null), after: H("a1"), bib: bib(["k"]) })],
+    "bibtex",
+  ],
+  [
+    "after bibtex changed the .bbl — rerun",
+    [latex({ bib: bib(["k"]) }), bibtex()],
+    "latex",
+  ],
+  [
+    "bibtex ran on exactly this input — not again",
+    [
+      latex({ bib: bib(["k"]) }),
+      bibtex(),
+      latex({
+        before: H("a1", null, null, "bbl1"),
+        after: H("a1", null, null, "bbl1"),
+        bib: bib(["k"]),
+      }),
+    ],
+    "latex-final",
+  ],
+  [
+    "the \\citation set changed since bibtex ran — bibtex again",
+    [latex({ bib: bib(["k"]) }), bibtex(), latex({ bib: bib(["k", "k2"]) })],
+    "bibtex",
+  ],
+  [
+    "the .bib content changed since bibtex ran — bibtex again",
+    [latex({ bib: bib(["k"]) }), bibtex(), latex({ bib: bib(["k"], "b2") })],
+    "bibtex",
+  ],
+  [
+    "bibtex left the .bbl byte-identical — the verdict of the pass before it stands (converged)",
+    [
+      latex({ bib: bib(["k"]) }),
+      bibtex({
+        before: H("a1", null, null, "bbl1"),
+        after: H("a1", null, null, "bbl1"),
+      }),
+    ],
+    "latex-final",
+  ],
+  [
+    "a pdflatex pass exited non-zero — fail",
+    [
+      latex({
+        exitCode: 1,
+        errorLines: ["./paper.tex:4: Undefined control sequence.", "l.4 \\foo"],
+      }),
+    ],
+    "fail",
+  ],
+  [
+    "bibtex exited non-zero — fail",
+    [
+      latex({ bib: bib(["k"]) }),
+      bibtex({
+        exitCode: 2,
+        errorLines: ["I couldn't open database file nope.bib"],
+      }),
+    ],
+    "fail",
+  ],
+  [
+    "the FINAL pass exited non-zero (a paper-guards error) — fail, not done",
+    [latex(), latex({ final: true, exitCode: 1 })],
+    "fail",
+  ],
+];
+
+for (const [label, history, expected] of TABLE) {
+  const got = kind(step(history));
+  check(`${label} (expected ${expected}, got ${got})`, got === expected);
+}
+
+// ── what a fail carries ─────────────────────────────────────────────────────────────────
+const latexFail = step([
+  latex({
+    exitCode: 1,
+    errorLines: ["./paper.tex:4: Undefined control sequence.", "l.4 \\foo"],
+  }),
+]);
+check(
+  "a latex fail names the step, the exit code and the log excerpt verbatim",
+  latexFail.step === "latex" &&
+    latexFail.cause.kind === "exit" &&
+    latexFail.cause.code === 1 &&
+    latexFail.lines[1] === "l.4 \\foo",
+);
+const bibFail = step([
+  latex({ bib: bib(["k"]) }),
+  bibtex({
+    exitCode: 2,
+    errorLines: ["I couldn't open database file nope.bib"],
+  }),
+]);
+check(
+  "a bibtex fail names BIBTEX, not latex",
+  bibFail.kind === "fail" &&
+    bibFail.step === "bibtex" &&
+    bibFail.cause.code === 2,
+);
+
+// ── the cap ─────────────────────────────────────────────────────────────────────────────
+const moving = (i) => latex({ before: H(`a${i}`), after: H(`a${i + 1}`) });
+const underCap = Array.from({ length: MAX_PASSES - 1 }, (_, i) => moving(i));
+check(
+  `the cap is ${MAX_PASSES} and it is not hit early: after ${MAX_PASSES - 1} moving passes, one more`,
+  MAX_PASSES === 5 && kind(step(underCap)) === "latex",
+);
+const atCap = Array.from({ length: MAX_PASSES }, (_, i) => moving(i));
+const capped = step(atCap);
+check(
+  "🔴 after the cap, a still-moving aux is a FAIL — no convergence — not a PDF with stale references",
+  capped.kind === "fail" && capped.cause.kind === "no-convergence",
+);
+check(
+  "the non-convergence failure NAMES the file that kept changing",
+  capped.kind === "fail" && capped.lines[0].includes("paper.aux"),
+);
+const cappedMarker = step(
+  Array.from({ length: MAX_PASSES }, () =>
+    latex({ markers: ["labels-changed"] }),
+  ),
+);
+check(
+  "a log that keeps asking for a rerun hits the same cap, and names the marker",
+  cappedMarker.kind === "fail" &&
+    cappedMarker.lines[0].includes("labels-changed"),
+);
+const convergedAtCap = [...atCap.slice(0, -1), latex()];
+check(
+  "reaching the cap WITH a converged last pass is not a failure — the final pass still runs",
+  kind(step(convergedAtCap)) === "latex-final",
+);
+
+// ── done carries the undefined-reference summaries ─────────────────────────────────────
+const doneWarn = step([
+  latex(),
+  latex({ final: true, markers: ["undefined-citations", "rerun-requested"] }),
+]);
+check(
+  "done reports undefined citations still in the final log, and nothing else",
+  doneWarn.kind === "done" &&
+    doneWarn.warnings.length === 1 &&
+    doneWarn.warnings[0] === "undefined-citations",
+);
+
+// ── helpers ─────────────────────────────────────────────────────────────────────────────
+check(
+  "changedFiles lists exactly the differing tracked files",
+  JSON.stringify(
+    changedFiles(H("a", "t", null, "b"), H("a", "t2", "o", "b")),
+  ) === JSON.stringify(["toc", "out"]),
+);
+check(
+  "a file appearing (null → digest) is a change",
+  changedFiles(H(null), H("a1")).includes("aux"),
+);
+
+console.log(
+  `✓ ${String(n)} assertions passed — latex-loop: nextStep over State, summarize over histories, and the two composed, including the ${MAX_PASSES}-pass cap`,
+);

package/src/latex-loop.ts

@@ -0,0 +1,211 @@
+/**
+ * THE DECISION of the LaTeX build loop: given what the runs so far observed, what runs next.
+ *
+ * PURE. No disk, no process, no clock. The shell in `build.ts` runs a step, records what it saw
+ * as an `Observation`, appends it to the history and asks `nextStep(summarize(history))` again.
+ * Both halves are table tests (`latex-loop.harness.mjs`), not scenarios that need TeX.
+ *
+ * ── THE LOOP: `summarize` reduces the history to a `State`, and `nextStep` asks four questions ──
+ *   1. did the last program fail?                          → fail, with its error lines
+ *   2. did the citations, a .bib or the style change since
+ *      bibtex last ran?                                    → bibtex
+ *   3. did the last pass change a tracked file, or did the
+ *      log ask for a rerun?                                → latex (fail after MAX_PASSES)
+ *   4. otherwise                                           → one FINAL latex pass, then done
+ *
+ * 🔴 WHY A FINAL PASS AFTER CONVERGENCE. `paper-guards.tex`, shipped by this package, turns an
+ * undefined `\ref` or `\cite` into a BUILD FAILURE — but only on a pass that defines
+ * `\finalpass`, because on the first pass every reference is undefined by construction. Measured
+ * on 2026-08-26 with the unconditional form: pass 1 fails, the `.aux` is never written, pass 2
+ * fails the same way and no PDF ever appears. So the guards need to know which pass is the last,
+ * and only the loop knows it. The price is one extra pdflatex run per build, paid for turning
+ * "?? in the PDF" into a red build.
+ *
+ * 🔴 WHY A CAP. A document can keep changing its own aux on every pass — the textbook case is a
+ * page reference whose own wording moves its target to the other page, and back — and the aux never
+ * settles. Without a cap the loop runs forever; with a silent cap it stops and ships an
+ * unconverged PDF with wrong cross-references. It stops, and it FAILS, naming the file that kept
+ * changing.
+ *
+ * ⚠️ `filecontents` with `[overwrite]` is NOT such a case, though this comment said so until
+ * 2026-09-24. The environment body is verbatim, so every pass writes the same bytes, and the loop
+ * compares CONTENT digests, not modification times. Measured with `paperlint build` on TeX Live 2026: a
+ * real acmart paper embedding its `refs.bib` that way converged in 3 pdflatex passes, and an
+ * `article` with an overwritten `\input` file carrying `\label`/`\ref`, a `\tableofcontents` and
+ * an overwritten `.bib` converged in 4.
+ */
+
+/** Files a pdflatex pass writes and the next pass reads. A change means the output is stale. */
+export type Tracked = "aux" | "toc" | "out" | "bbl";
+export const TRACKED: readonly Tracked[] = ["aux", "toc", "out", "bbl"];
+
+/** Content digests of the tracked files; `null` = the file does not exist. */
+export type Hashes = { readonly [K in Tracked]: string | null };
+
+/** Log markers, as `latex-log.ts` reads them. Re-declared as a type so this module has no imports. */
+export type LogMarker =
+  | "rerun-requested"
+  | "labels-changed"
+  | "rerunfilecheck"
+  | "undefined-references"
+  | "undefined-citations";
+
+const RERUN: readonly LogMarker[] = [
+  "rerun-requested",
+  "labels-changed",
+  "rerunfilecheck",
+];
+
+/**
+ * What bibtex would be run on. `none` — the aux names no `\bibdata`, so there is nothing for
+ * bibtex to do. Two `needed` states are the same input exactly when every field is equal: the
+ * citation set moved, a database was added, or a `.bib` file's content changed ⇒ bibtex again.
+ */
+export type BibInput =
+  | { readonly kind: "none" }
+  | {
+      readonly kind: "needed";
+      /** Sorted, unique cited keys. */
+      readonly citations: readonly string[];
+      readonly databases: readonly string[];
+      readonly style: string | null;
+      /** A digest over the content of every database file that exists; null when none was found. */
+      readonly bibHash: string | null;
+    };
+
+export type Observation =
+  | {
+      readonly step: "latex";
+      /** Whether this pass defined `\finalpass`. */
+      readonly final: boolean;
+      readonly exitCode: number;
+      readonly before: Hashes;
+      readonly after: Hashes;
+      readonly markers: readonly LogMarker[];
+      /** The bibliography input as the aux stood after this pass. */
+      readonly bib: BibInput;
+      /** The first error and its source context, from the log. Empty on success. */
+      readonly errorLines: readonly string[];
+    }
+  | {
+      readonly step: "bibtex";
+      readonly exitCode: number;
+      readonly before: Hashes;
+      readonly after: Hashes;
+      /** The input bibtex was run on. */
+      readonly bib: BibInput;
+      readonly errorLines: readonly string[];
+    };
+
+export type FailCause =
+  | { readonly kind: "exit"; readonly code: number }
+  | { readonly kind: "no-convergence"; readonly unsettled: readonly string[] };
+
+export type Step =
+  | { readonly kind: "latex"; readonly final: boolean }
+  | { readonly kind: "bibtex" }
+  | {
+      readonly kind: "done";
+      /** Undefined-reference summaries still in the final log — a converged doc with a bad key. */
+      readonly warnings: readonly LogMarker[];
+    }
+  | {
+      readonly kind: "fail";
+      readonly step: "latex" | "bibtex";
+      readonly cause: FailCause;
+      /** What to show the human: the log excerpt, or the non-convergence explanation. */
+      readonly lines: readonly string[];
+    };
+
+/** Non-final pdflatex passes allowed before the build is declared non-converging. */
+export const MAX_PASSES = 5;
+
+/** The history, reduced to the four questions `nextStep` asks. */
+export type State = {
+  readonly failed: {
+    readonly step: "latex" | "bibtex";
+    readonly cause: FailCause;
+    readonly lines: readonly string[];
+  } | null;
+  /** Citations, databases, style or `.bib` content changed since bibtex last ran. */
+  readonly bibOutdated: boolean;
+  /** Tracked files the last pass changed (`paper.aux`), or the rerun markers its log printed. */
+  readonly unsettled: readonly string[];
+  /** Non-final pdflatex passes so far. */
+  readonly latexPasses: number;
+  readonly finalDone: boolean;
+  /** Undefined-reference summaries in the log of the final pass. */
+  readonly warnings: readonly LogMarker[];
+};
+
+export function nextStep(s: State): Step {
+  if (s.failed) return { kind: "fail", ...s.failed };
+  if (s.finalDone) return { kind: "done", warnings: s.warnings };
+  if (s.bibOutdated) return { kind: "bibtex" };
+  if (s.unsettled.length === 0) return { kind: "latex", final: true };
+  if (s.latexPasses < MAX_PASSES) return { kind: "latex", final: false };
+  return noConvergence(s.unsettled);
+}
+
+const noConvergence = (unsettled: readonly string[]): Step => ({
+  kind: "fail",
+  step: "latex",
+  cause: { kind: "no-convergence", unsettled },
+  lines: [
+    `the build does not converge: after ${MAX_PASSES} pdflatex passes, the last one still changed or asked to rerun: ${unsettled.join(", ")}.`,
+    `A document whose aux keeps changing on every pass never settles; stopping here instead of`,
+    `shipping a PDF with stale cross-references.`,
+  ],
+});
+
+/** The tracked files whose digest differs between two snapshots. */
+export function changedFiles(before: Hashes, after: Hashes): Tracked[] {
+  return TRACKED.filter((f) => before[f] !== after[f]);
+}
+
+const sameBib = (a: BibInput, b: BibInput): boolean =>
+  JSON.stringify(a) === JSON.stringify(b);
+
+/**
+ * What the last run left unsettled. Walking back: a run that changed a tracked file answers with
+ * those files; a latex pass that changed none answers with the rerun markers in its log. A bibtex
+ * run that left the `.bbl` byte-identical changes nothing, so the pass before it answers.
+ */
+function unsettledBy(history: readonly Observation[]): string[] {
+  if (history.length === 0) return ["paper.aux"]; // no pass has written it yet
+  for (const o of history.toReversed()) {
+    const files = changedFiles(o.before, o.after);
+    if (files.length > 0) return files.map((f) => `paper.${f}`);
+    if (o.step === "latex") return o.markers.filter((m) => RERUN.includes(m));
+  }
+  return [];
+}
+
+export function summarize(history: readonly Observation[]): State {
+  const last = history.at(-1);
+  const latexRuns = history.filter((o) => o.step === "latex");
+  const lastLatex = latexRuns.at(-1);
+  const lastBibtex = history.filter((o) => o.step === "bibtex").at(-1);
+  return {
+    failed:
+      last && last.exitCode !== 0
+        ? {
+            step: last.step,
+            cause: { kind: "exit", code: last.exitCode },
+            lines: last.errorLines,
+          }
+        : null,
+    bibOutdated:
+      lastLatex?.bib.kind === "needed" &&
+      !(lastBibtex && sameBib(lastBibtex.bib, lastLatex.bib)),
+    unsettled: unsettledBy(history),
+    latexPasses: latexRuns.filter((o) => !o.final).length,
+    finalDone: last?.step === "latex" && last.final,
+    warnings:
+      last?.step === "latex"
+        ? last.markers.filter(
+            (m) => m === "undefined-references" || m === "undefined-citations",
+          )
+        : [],
+  };
+}