paperlint 11.1.3 → 12.0.0

package/docs/configuration.md

@@ -399,7 +399,8 @@ papers/my-paper
   keys or a `.bib` file changed. After that, one **final** pass defines `\finalpass`, which arms
   the reference guards in `paper-guards.tex`: an undefined `\ref` or `\cite` fails the build
   there instead of printing `??`. A document that still changes after five passes fails, naming
-  the file that kept changing. After a green compile the step also writes
+  the file that kept changing. The final pass's log is then read for the warnings that fail the
+  build (below). After a green compile the step also writes
   `_build/sources.json`, the record of what TeX read: every file of the paper directory its passes
   opened (from the `.fls` that `-recorder` makes), whether each came before or after
   `\begin{document}`, the `.bib` files TeX itself wrote, the databases and keys bibtex read, and a
@@ -452,6 +453,34 @@ without a new one:
       paper.pdf removed — a stale PDF must not pass for this build
 ```
 
+**Some warnings fail the build although pdflatex exits 0**, because the PDF it wrote is wrong. They
+are one list, `FAILING_WARNINGS` in [`src/latex-log.ts`](../src/latex-log.ts), and only the log of
+the **final** pass is read — before the rerun every reference is undefined by construction:
+
+| id                        | the log line                                              | why it fails                                                                      |
+| ------------------------- | --------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| `lost-character`          | `Missing character: There is no <char> in font <font>!`   | the font has no glyph for the character, so the PDF lacks it (`10^-13` → `10^13`) |
+| `undefined-references`    | `LaTeX Warning: There were undefined references.`         | the PDF prints `??` for a `\ref`, or `[?]` for a `\cite` without natbib           |
+| `undefined-citations`     | `Package natbib Warning: There were undefined citations.` | the PDF prints `[?]` for a `\cite` (natbib)                                       |
+| `multiply-defined-labels` | `LaTeX Warning: There were multiply-defined labels.`      | a `\ref` may point at the wrong one of two labels                                 |
+
+Every other warning — overfull and underfull boxes, font substitutions, "Rerun to get …" — leaves
+the build as it was. The failure quotes each distinct line once, with how many times the log has it
+(here `\char"FF` in `cmr10`, measured on TeX Live 2026; TeX writes the character as one raw byte,
+which is no UTF-8 character, so it shows as `�`):
+
+```
+  ✗ compile: pdflatex exited 0, but its final log carries a warning that fails the build
+      lost-character — the font has no glyph for this character, so pdflatex left it out of the PDF:
+        Missing character: There is no � in font cmr10! (2 times)
+      full log: papers/my-paper/paper.log
+      paper.pdf removed — a stale PDF must not pass for this build
+```
+
+⚠️ TeX writes the `Missing character` line only while `\tracinglostchars` is above 0. LaTeX sets it
+to 2 (TeX Live 2026); a paper that sets it to 0 hides the line, and this check sees nothing. At 3
+and above TeX makes it an error, and the build fails on pdflatex's exit code instead.
+
 **A paper with no `paper.tex` is a FAILURE, not a skip.** "Nothing to build" and "built" must never
 look alike: the corpus this came from once let a paper reach its venue without a single paper job
 having run on it, because a missing build read as nothing to do.

package/docs/e2e.md

@@ -98,6 +98,7 @@ A new venue fixture is a new folder: its paper, its `paperlint.json`, its `expec
 | `broken`             | a failing build names pdflatex and its exit code, quotes the error line and its `l.NNN` context, and deletes the stale `paper.pdf` planted before the run                                                                                                                                                                                                                                                                                                                                              |
 | `no-source`          | a paper with no `paper.tex` is named separately, and the run as a whole is a failure                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | `empty`              | a document with no pages: pdflatex exits 0 and writes no PDF, and that is a failure, not a green `paper.pdf`                                                                                                                                                                                                                                                                                                                                                                                           |
+| `lost-character`     | pdflatex exits 0 and writes a PDF without a character its font cannot draw (`\char"FF` in cmr10); the build fails, quotes the `Missing character` line from the log and leaves no `paper.pdf`                                                                                                                                                                                                                                                                                                          |
 | `aidc`               | a real `[conference,compsoc]{IEEEtran}` paper builds on paperlint's TeX Live in NimbusRomNo9L, `tex/template`, `tex/required-section` and the `pdf/*` rules find nothing, and `tex/venue-leftover` warns once, on its planted line. It declares `identity` and names nobody, so `anonymity/identity` is silent on a real build, and `format/page-limit` finds the IEEEtran «References» heading                                                                                                        |
 | `anon-*`             | six AIDC papers, each planting the declared (invented) name on ONE path, and `anonymity/identity` reports exactly one finding naming where: `author` the author block · `ack` an acknowledgments paragraph · `bib` a self-citation, printed by `IEEEtran.bst` as «A. Example» · `pdfauthor` `\hypersetup{pdfauthor=…}`, on no page · `href` a link whose target is the author's account while its text is not (the anonymous mirror beside it is not reported) · `macro` the name behind `\newcommand` |
 | `msr`                | a real `[10pt,conference]{IEEEtran}` paper whose ten pages of main text include an appendix before the references, then two pages of only references: `format/page-limit`, `tex/template` and `anonymity/identity` find nothing. banal's count of the same PDF (body 9, references 3) would have failed it                                                                                                                                                                                             |

package/fixtures/build-e2e/lost-character/PIPELINE-STATUS.md

@@ -0,0 +1,3 @@
+# Fixture
+
+Stage: draft

package/fixtures/build-e2e/lost-character/expect.json

@@ -0,0 +1,15 @@
+{
+  "$comment": "pdflatex exits 0 and writes a PDF without a character the font has no glyph for; the build fails on the log line (FAILING_WARNINGS in src/latex-log.ts).",
+  "build": {
+    "outcome": "failed"
+  },
+  "says": [
+    "✗ compile: pdflatex exited 0, but its final log carries a warning that fails the build",
+    "lost-character — the font has no glyph for this character, so pdflatex left it out of the PDF:",
+    "Missing character: There is no",
+    "in font cmr10!"
+  ],
+  "saysNot": [
+    "✓"
+  ]
+}

package/fixtures/build-e2e/lost-character/paper.tex

@@ -0,0 +1,8 @@
+% A paper whose font has no glyph for one character. pdflatex prints "Missing character: There is no
+% ... in font cmr10!" to the log (LaTeX sets \tracinglostchars=2), exits 0 and writes a PDF without
+% it -- the way an abstract once printed 7 x 10^13 for 7 x 10^-13. `paperlint build` must fail, quote
+% the log line, and leave no paper.pdf.
+\documentclass{article}
+\begin{document}
+A rate of $7\times 10^{13}$ and a character cmr10 cannot draw: \char"FF.
+\end{document}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paperlint",
-  "version": "11.1.3",
+  "version": "12.0.0",
   "description": "A linter for scientific papers written in LaTeX: catches mistakes before you submit to a conference or journal.",
   "type": "module",
   "license": "MIT",

package/src/build.test.ts

@@ -265,12 +265,55 @@ test("compile: a document whose .aux never settles did not converge", async () =
   assert.match(line, /^ {2}✗ compile: pdflatex did not converge\n/);
 });
 
-test("compile: warnings the final log still reports are named in the note", async () => {
-  const { r } = await build(paper(), {
+test("🔴 compile: pdflatex exits 0 but its log says a character was dropped — the build fails, quoting the line, and the PDF goes", async () => {
+  const dir = paper();
+  // The log as pdflatex writes it: raw UTF-8 bytes, which the build reads as latin1 and shows as UTF-8.
+  const { r, line } = await build(dir, {
+    log: [
+      "(./paper.aux)",
+      "Missing character: There is no ⁻ in font cmr10!",
+      "Overfull \\hbox (1.2pt too wide) in paragraph at lines 4--5",
+      "Missing character: There is no ⁻ in font cmr10!",
+      "",
+    ].join("\n"),
+  });
+  assert.equal(r.status, "failed");
+  assert.equal(
+    line,
+    [
+      "  ✗ compile: pdflatex exited 0, but its final log carries a warning that fails the build",
+      "      lost-character — the font has no glyph for this character, so pdflatex left it out of the PDF:",
+      "        Missing character: There is no ⁻ in font cmr10! (2 times)",
+      `      full log: ${join(dir, "paper.log").replace(root, "<root>")}`,
+      "      paper.pdf removed — a stale PDF must not pass for this build",
+    ].join("\n"),
+  );
+  assert.equal(existsSync(join(dir, "paper.pdf")), false);
+});
+
+test("compile: undefined references in the final log fail the build — no longer a note on a green one", async () => {
+  const { r, line } = await build(paper(), {
     log: "LaTeX Warning: There were undefined references.\n",
   });
+  assert.equal(r.status, "failed");
+  assert.match(
+    line,
+    /\n {6}undefined-references — .*:\n {8}LaTeX Warning: There were undefined references\.\n/,
+  );
+});
+
+test("compile: warnings off the failing list — overfull boxes, a font substitution, one undefined reference — leave the build green", async () => {
+  const { r } = await build(paper(), {
+    log: [
+      "Overfull \\hbox (1.2pt too wide) in paragraph at lines 4--5",
+      "LaTeX Font Warning: Font shape `OT1/cmr/bx/sc' undefined",
+      "(Font)              using `OT1/cmr/bx/n' instead on input line 3.",
+      "LaTeX Warning: Reference `sec:x' on page 1 undefined on input line 4.",
+      "",
+    ].join("\n"),
+  });
   assert.equal(r.status, "built");
-  assert.match(r.notes?.[0] ?? "", /— ⚠️ the final log still reports /);
+  assert.doesNotMatch(r.notes?.[0] ?? "", /⚠️/);
 });
 
 test("references: without a reader the step says it was not wired; with one and no checker, the record says not checked", async () => {

package/src/build.ts

@@ -83,6 +83,7 @@ import {
   auxBib,
   bibtexExcerpt,
   errorExcerpt,
+  failingWarnings,
   logMarkers,
   unwrapLog,
 } from "./latex-log.ts";
@@ -90,6 +91,7 @@ import {
   nextStep,
   summarize,
   type BibInput,
+  type FailCause,
   type Hashes,
   type Observation,
   type Step,
@@ -401,6 +403,10 @@ function latexPass(
     markers: logMarkers(log),
     bib: bibInput(ctx.paperDir),
     fls: readOr(join(ctx.paperDir, `${JOB}.fls`), "utf8"),
+    failing: failingWarnings(log).map((h) => ({
+      ...h,
+      quotes: h.quotes.map((q) => ({ ...q, text: fromLatin1(q.text) })),
+    })),
     errorLines:
       exitCode === 0
         ? []
@@ -494,6 +500,18 @@ export function compile(ctx: BuildContext): {
 
 const NO_PDF = `pdflatex exited 0 but wrote no ${JOB}.pdf — does the document have any pages?`;
 
+/** The head of a failed compile: which program, and how it ended. */
+function whereFailed(bin: string, cause: FailCause): string {
+  switch (cause.kind) {
+    case "exit":
+      return `${bin} exited with ${String(cause.code)}`;
+    case "no-convergence":
+      return `${bin} did not converge`;
+    case "log-warnings":
+      return `${bin} exited 0, but its final log carries a warning that fails the build`;
+  }
+}
+
 const plural = (n: number, one: string, many: string): string =>
   `${String(n)} ${n === 1 ? one : many}`;
 
@@ -517,10 +535,7 @@ export const compileStep: BuildStep = {
     const { end, latex, bibtex, run } = compile(ctx);
     if (end.kind === "fail") {
       const bin = end.step === "latex" ? "pdflatex" : "bibtex";
-      const where =
-        end.cause.kind === "exit"
-          ? `${bin} exited with ${String(end.cause.code)}`
-          : `${bin} did not converge`;
+      const where = whereFailed(bin, end.cause);
       const log = join(
         ctx.paperDir,
         `${JOB}.${end.step === "latex" ? "log" : "blg"}`,
@@ -545,12 +560,9 @@ export const compileStep: BuildStep = {
         ok: false,
         lines: [NO_PDF, `full log: ${join(ctx.paperDir, `${JOB}.log`)}`],
       };
-    const warn = end.warnings.length
-      ? ` — ⚠️ the final log still reports ${end.warnings.join(", ")}`
-      : "";
     return {
       ok: true,
-      note: `${plural(latex, "pdflatex pass", "pdflatex passes")}, ${plural(bibtex, "bibtex run", "bibtex runs")}${warn}; ${recordingNote(ctx.recordSources(ctx.paperDir, run))}`,
+      note: `${plural(latex, "pdflatex pass", "pdflatex passes")}, ${plural(bibtex, "bibtex run", "bibtex runs")}; ${recordingNote(ctx.recordSources(ctx.paperDir, run))}`,
     };
   },
 };

package/src/latex-log.harness.ts

@@ -6,7 +6,7 @@
  * marker that TeX broke at column 79.
  */
 import { createChecker } from "../lib/check.ts";
-import type { LogMarker } from "./latex-log.ts";
+import type { FailingWarningId, LogMarker } from "./latex-log.ts";
 
 const {
   unwrapLog,
@@ -16,6 +16,8 @@ const {
   bibtexExcerpt,
   auxBib,
   MAX_PRINT_LINE,
+  FAILING_WARNINGS,
+  failingWarnings,
 } = await import("./latex-log.ts");
 
 const check = createChecker();
@@ -75,16 +77,14 @@ const firstPass = [
 ];
 const m = logMarkers(firstPass);
 check(
-  "every documented marker is recognised",
-  (
-    [
+  "every documented marker is recognised, and the end-of-run summaries are not markers (they fail the build: FAILING_WARNINGS)",
+  JSON.stringify(m) ===
+    JSON.stringify([
       "rerun-requested",
       "labels-changed",
       "rerunfilecheck",
-      "undefined-references",
-      "undefined-citations",
-    ] satisfies LogMarker[]
-  ).every((k) => m.includes(k)),
+    ] satisfies LogMarker[]),
+  m,
 );
 check(
   "a clean log carries no markers",
@@ -93,11 +93,6 @@ check(
     "Output written on paper.pdf (1 page, 1234 bytes).",
   ]).length === 0,
 );
-// Guards: matching the documented summary line rather than the word 'undefined'.
-check(
-  "a single reference warning is not the end-of-run summary",
-  !logMarkers(firstPass.slice(0, 1)).includes("undefined-references"),
-);
 
 // ── error excerpt ───────────────────────────────────────────────────────────────────────
 const undefinedCs = [
@@ -246,6 +241,142 @@ check(
   );
 }
 
+// ── warnings that fail the build ────────────────────────────────────────────────────────
+// Every entry of FAILING_WARNINGS has its two halves here — log lines it must find, and lines it
+// must not — and `satisfies Record<FailingWarningId, …>` makes a table entry without a row here a
+// type error; the first check below makes it a red run as well.
+// The lost-character line is copied from a real TeX Live 2026 run (2026-10-26): `\char"FF` in
+// cmr10 under `\documentclass{article}`, which sets `\tracinglostchars=2`; pdflatex exited 0.
+// The log is read as latin1, so the byte 0xFF is the one character "\xff".
+const LOST = "Missing character: There is no \xff in font cmr10!";
+const FAILING_CASES = {
+  "lost-character": {
+    fires: [
+      LOST,
+      "Missing character: There is no \xe2 in font LinLibertineT-tlf-ot1!",
+    ],
+    quiet: [
+      "Overfull \\hbox (1.2pt too wide) in paragraph at lines 4--5",
+      "LaTeX Font Warning: Font shape `OT1/cmr/bx/sc' undefined",
+      "LaTeX Warning: Label(s) may have changed. Rerun to get cross-references right.",
+      "LaTeX Warning: There were undefined references.",
+      // The words inside an unrelated longer line — an overfull box quoting the text it set.
+      "[]\\OT1/cmr/m/n/10 Missing character: There is no x in font cmr10!",
+    ],
+  },
+  // The three end-of-run summaries, worded as latex.ltx and natbib.sty print them (TeX Live 2026);
+  // LaTeX core has no "undefined citations" summary — an undefined \cite counts as a reference. Guards: matching the
+  // summary, not the word "undefined" — one reference warning per \ref is printed on EVERY pass
+  // before the rerun, and is not the summary.
+  "undefined-references": {
+    fires: ["LaTeX Warning: There were undefined references."],
+    quiet: [
+      "LaTeX Warning: Reference `sec:intro' on page 1 undefined on input line 4.",
+      "Package natbib Warning: There were undefined citations.",
+      "LaTeX Warning: Label(s) may have changed. Rerun to get cross-references right.",
+    ],
+  },
+  "undefined-citations": {
+    fires: ["Package natbib Warning: There were undefined citations."],
+    quiet: [
+      "LaTeX Warning: Citation `knuth84' on page 1 undefined on input line 7.",
+      "Package natbib Warning: Citation `knuth84' on page 1 undefined on input line 7.",
+      "LaTeX Warning: There were undefined references.",
+    ],
+  },
+  "multiply-defined-labels": {
+    fires: ["LaTeX Warning: There were multiply-defined labels."],
+    quiet: [
+      "LaTeX Warning: Label `sec:intro' multiply defined.",
+      "LaTeX Warning: There were undefined references.",
+    ],
+  },
+} satisfies Record<
+  FailingWarningId,
+  { readonly fires: readonly string[]; readonly quiet: readonly string[] }
+>;
+check(
+  "every failing warning in the table has a row of cases, and every row is in the table",
+  JSON.stringify(FAILING_WARNINGS.map((w) => w.id).sort()) ===
+    JSON.stringify(Object.keys(FAILING_CASES).sort()),
+);
+for (const [id, c] of Object.entries(FAILING_CASES)) {
+  for (const line of c.fires)
+    check(
+      `${id}: fires on ${JSON.stringify(line)}`,
+      failingWarnings(["(./paper.aux)", line, ""]).some((h) => h.id === id),
+      () => failingWarnings(["(./paper.aux)", line, ""]),
+    );
+  for (const line of c.quiet)
+    check(
+      `${id}: quiet on ${JSON.stringify(line)}`,
+      !failingWarnings(["(./paper.aux)", line, ""]).some((h) => h.id === id),
+      () => failingWarnings(["(./paper.aux)", line, ""]),
+    );
+}
+check(
+  "a clean log carries no failing warning",
+  failingWarnings([
+    "This is pdfTeX",
+    "Output written on paper.pdf (1 page, 1234 bytes).",
+  ]).length === 0,
+);
+{
+  const log = [
+    LOST,
+    "(./paper.aux)",
+    LOST,
+    "Missing character: There is no \xfe in font cmtt10!",
+    LOST,
+  ];
+  const hits = failingWarnings(log);
+  check(
+    "a lost character quotes each distinct line once, in order, with how many times TeX printed it",
+    JSON.stringify(hits) ===
+      JSON.stringify([
+        {
+          id: "lost-character",
+          reason: FAILING_WARNINGS[0].reason,
+          quotes: [
+            { text: LOST, times: 3 },
+            {
+              text: "Missing character: There is no \xfe in font cmtt10!",
+              times: 1,
+            },
+          ],
+        },
+      ]),
+    hits,
+  );
+}
+{
+  // A long font name pushes the line past column 79: TeX breaks it, and unwrapLog rejoins it.
+  const long =
+    "Missing character: There is no \xff in font LinLibertineT-tlf-ts1-scaled-1000-extended!";
+  const split = [long.slice(0, MAX_PRINT_LINE), long.slice(MAX_PRINT_LINE)];
+  check(
+    "a lost-character line TeX split at column 79 is rejoined and found, quoted whole",
+    split[0]?.length === 79 &&
+      JSON.stringify(
+        failingWarnings(unwrapLog(split.join("\n")))[0]?.quotes,
+      ) === JSON.stringify([{ text: long, times: 1 }]),
+  );
+}
+{
+  // A line of exactly 79 bytes by itself is joined to the next one (unwrapLog's documented false
+  // join): the marker then starts at byte 79 of the joined line, where the physical line began.
+  const before = "x".repeat(MAX_PRINT_LINE);
+  const joined = unwrapLog([before, LOST, ""].join("\n"));
+  check(
+    "a lost-character line glued by a false join to a 79-byte line before it is still found",
+    joined[0] === before + LOST && failingWarnings(joined).length === 1,
+  );
+  check(
+    "the marker words NOT at a physical line start (byte 78) are not read as one",
+    failingWarnings(["y".repeat(MAX_PRINT_LINE - 1) + LOST]).length === 0,
+  );
+}
+
 console.log(
-  `✓ ${String(check.count)} assertions passed — latex-log: markers across the 79-column wrap, both error spellings, aux`,
+  `✓ ${String(check.count)} assertions passed — latex-log: markers across the 79-column wrap, both error spellings, aux, warnings that fail the build`,
 );

package/src/latex-log.ts

@@ -19,25 +19,19 @@
  * must therefore read the log as `latin1`, so one character is one byte and `length` counts what
  * TeX counted.
  */
+import { filter, map, pipe, range, unique } from "remeda";
 
 /** TeX Live's `max_print_line`. A physical log line of exactly this many bytes was broken by TeX. */
 export const MAX_PRINT_LINE = 79;
 
 /**
- * Log lines that ask for another pass, or report on references. Each is a documented message,
- * not a guess about wording:
+ * Log lines that ask for another pass. Each is a documented message, not a guess about wording:
  *   - `rerun-requested`   — any "Rerun to get …" (LaTeX core, natbib, hyperref's outlines, …)
  *   - `labels-changed`    — "LaTeX Warning: Label(s) may have changed."
  *   - `rerunfilecheck`    — "Package rerunfilecheck Warning: File `…' has changed."
- *   - `undefined-references` / `undefined-citations` — the end-of-run summaries. These do NOT
- *     request a rerun by themselves: on a converged document they mean a genuinely undefined key.
+ * The end-of-run summaries about references are not markers: they fail the build (`FAILING_WARNINGS`).
  */
-export type LogMarker =
-  | "rerun-requested"
-  | "labels-changed"
-  | "rerunfilecheck"
-  | "undefined-references"
-  | "undefined-citations";
+export type LogMarker = "rerun-requested" | "labels-changed" | "rerunfilecheck";
 
 /**
  * Rejoin the lines TeX broke at column 79. A line of exactly 79 bytes continues on the next one.
@@ -71,21 +65,116 @@ export function logMarkers(lines: readonly string[]): LogMarker[] {
       found.add("labels-changed");
     if (line.startsWith("Package rerunfilecheck Warning:"))
       found.add("rerunfilecheck");
-    if (line.includes("There were undefined references"))
-      found.add("undefined-references");
-    if (line.includes("There were undefined citations"))
-      found.add("undefined-citations");
   }
   const order: LogMarker[] = [
     "rerun-requested",
     "labels-changed",
     "rerunfilecheck",
-    "undefined-references",
-    "undefined-citations",
   ];
   return order.filter((m) => found.has(m));
 }
 
+/** A log warning that fails the build: what it is called, why it fails, and the lines that carry it. */
+export interface FailingWarning {
+  readonly id: string;
+  /** One line a human reads before the quoted log lines. */
+  readonly reason: string;
+  /** Whether this logical line (after `unwrapLog`) carries it. */
+  readonly matches: (line: string) => boolean;
+}
+
+/**
+ * Does `prefix` start one of the PHYSICAL lines this logical line was joined from? `unwrapLog` joins
+ * only lines of exactly 79 bytes, so every physical line starts at a multiple of 79. That keeps a
+ * marker found after unwrapLog's false join (a 79-byte line by itself, then the marker) and still
+ * ignores the same words in the middle of a line — an overfull box quoting the text it set.
+ */
+const startsPhysicalLine = (line: string, prefix: string): boolean =>
+  range(0, Math.floor(line.length / MAX_PRINT_LINE) + 1).some((k) =>
+    line.startsWith(prefix, k * MAX_PRINT_LINE),
+  );
+
+/**
+ * 🔴 THE WARNINGS THAT FAIL THE BUILD — like an ESLint rule at "error". pdflatex exits 0 on each of
+ * them and writes a PDF that is wrong: a character missing, `??` or `[?]` in the text, a reference
+ * that may point at the wrong place. Only the log of the FINAL pass is judged (`latex-loop.ts`):
+ * before the rerun every reference is undefined by construction.
+ *
+ * WHY THESE FOUR. Each makes the PDF wrong for a reader, and turning all four on was measured on four
+ * real papers (their final logs of 2026-10-26): 0 hits each, so no correct paper turns red. Left out: overfull boxes (cosmetic,
+ * nearly every paper has some, and the pdf/* rules check the margins), font shape substitution
+ * (usually harmless), "Rerun to get" (the loop already reruns). Those never fail a build.
+ *
+ * Adding one is one entry here, plus its row of cases in `latex-log.harness.ts` (the harness does
+ * not type-check without it).
+ *
+ * `lost-character`: TeX prints "Missing character: There is no X in font F!" when
+ * `\tracinglostchars` > 0; LaTeX's format sets it to 2 (TeX Live 2026, `latex.ltx`), and pdflatex
+ * still exits 0. A paper that sets it to 0 silences the line, and this check with it. At 3 or more
+ * TeX makes it an error, and the build fails on the exit code instead.
+ */
+export const FAILING_WARNINGS = [
+  {
+    id: "lost-character",
+    reason:
+      "the font has no glyph for this character, so pdflatex left it out of the PDF",
+    matches: (l: string) =>
+      startsPhysicalLine(l, "Missing character: There is no "),
+  },
+  {
+    id: "undefined-references",
+    reason:
+      "a \\ref — or, without natbib, a \\cite — names what no pass defined, so the PDF prints ?? or [?] in its place",
+    matches: (l: string) => l.includes("There were undefined references"),
+  },
+  {
+    id: "undefined-citations",
+    reason:
+      "a \\cite names a key the bibliography does not hold, so the PDF prints [?] in its place (natbib's summary)",
+    matches: (l: string) => l.includes("There were undefined citations"),
+  },
+  {
+    id: "multiply-defined-labels",
+    reason: "two \\label share a name, so a \\ref may point at the wrong one",
+    matches: (l: string) => l.includes("There were multiply-defined labels"),
+  },
+] as const satisfies readonly FailingWarning[];
+
+export type FailingWarningId = (typeof FAILING_WARNINGS)[number]["id"];
+
+/** One distinct log line, quoted as TeX wrote it, and how many times the log carries it. */
+export interface Quote {
+  readonly text: string;
+  readonly times: number;
+}
+
+/** A failing warning the log carries, with the lines that carry it. */
+export interface FailingHit {
+  readonly id: FailingWarningId;
+  readonly reason: string;
+  readonly quotes: readonly Quote[];
+}
+
+const quotesOf = (matched: readonly string[]): readonly Quote[] =>
+  map(unique(matched), (text) => ({
+    text,
+    times: matched.filter((l) => l === text).length,
+  }));
+
+/** Which of `FAILING_WARNINGS` the log carries, in table order, each line quoted once with a count. */
+export const failingWarnings = (
+  lines: readonly string[],
+): readonly FailingHit[] =>
+  pipe(
+    FAILING_WARNINGS,
+    map((w) => ({
+      id: w.id,
+      reason: w.reason,
+      quotes: quotesOf(lines.filter((l) => w.matches(l))),
+    })),
+    filter((h) => h.quotes.length > 0),
+  );
+
 /**
  * Is this the line a TeX error starts on? Two spellings exist and `-file-line-error` produces
  * both: most errors become `./paper.tex:4: Undefined control sequence.`, while some keep the