paperlint 2.0.0

package/src/latex-log.harness.mjs

@@ -0,0 +1,226 @@
+/**
+ * `latex-log.ts` — reading pdflatex logs, bibtex output and `.aux` files, both halves.
+ *
+ * The log excerpts below are copied from real TeX Live 2023 runs (2026-09-24), not typed from
+ * memory: the two error spellings `-file-line-error` produces, the missing-package form, and a
+ * marker that TeX broke at column 79.
+ */
+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 {
+  unwrapLog,
+  logMarkers,
+  errorExcerpt,
+  isErrorLine,
+  bibtexExcerpt,
+  auxBib,
+  MAX_PRINT_LINE,
+} = await import(join(HERE, "latex-log.ts"));
+
+let n = 0;
+const check = (label, cond) => {
+  assert.ok(cond, label);
+  n++;
+};
+
+// ── the 79-column wrap ──────────────────────────────────────────────────────────────────
+// A package warning long enough that "Rerun to get" crosses column 79. A real acmart log shows the
+// same break: "Document Class: acmart 2024/02/04 v2.03 Typesetting articles for the Associatio"
+// is a 79-byte line continued on the next one.
+const warning =
+  "Package natbib Warning: Citation(s) may have changed in the bibliography. Rerun to get citations correct.";
+const at79 = warning.slice(0, MAX_PRINT_LINE);
+const rest = warning.slice(MAX_PRINT_LINE);
+check(
+  "the fixture really is split at 79 (the marker straddles the break)",
+  at79.length === 79 && !at79.includes("Rerun to get") && rest.length > 0,
+);
+const wrappedLog = ["(./paper.aux)", "", at79, rest, ""].join("\n");
+// Guards: rejoining the lines TeX broke — a 'Rerun to get' split across the break is on no line at
+// all, and the loop would stop one pass early.
+check(
+  "🔴 a marker broken at column 79 is rejoined and found",
+  logMarkers(unwrapLog(wrappedLog)).includes("rerun-requested"),
+);
+check(
+  "without the unwrap, the split marker is NOT on any one line — the wrap is real",
+  !wrappedLog.split("\n").some((l) => l.includes("Rerun to get")),
+);
+// LaTeX core's line is 78 bytes; one trailing space makes it a line TeX would NOT have broken but
+// that is 79 bytes anyway — the ambiguous case `unwrapLog` documents.
+const exact79 =
+  "LaTeX Warning: Label(s) may have changed. Rerun to get cross-references right. ";
+check(
+  "a marker line that is exactly 79 bytes by itself is still found after the (harmless) join",
+  exact79.length === 79 &&
+    logMarkers(unwrapLog([exact79, "", "next"].join("\n"))).includes(
+      "labels-changed",
+    ),
+);
+check(
+  "a short line is not joined to the next one",
+  JSON.stringify(unwrapLog("a\nb")) === JSON.stringify(["a", "b"]),
+);
+check(
+  "two consecutive 79-byte lines join with the third",
+  unwrapLog(["x".repeat(79), "y".repeat(79), "z"].join("\n"))[0] ===
+    "x".repeat(79) + "y".repeat(79) + "z",
+);
+
+// ── markers ─────────────────────────────────────────────────────────────────────────────
+const firstPass = [
+  "LaTeX Warning: Reference `sec:intro' on page 1 undefined on input line 4.",
+  "LaTeX Warning: There were undefined references.",
+  "LaTeX Warning: Label(s) may have changed. Rerun to get cross-references right.",
+  "Package rerunfilecheck Warning: File `paper.out' has changed.",
+  "(rerunfilecheck)                Rerun to get outlines right",
+  "Package natbib Warning: There were undefined citations.",
+];
+const m = logMarkers(firstPass);
+check(
+  "every documented marker is recognised",
+  [
+    "rerun-requested",
+    "labels-changed",
+    "rerunfilecheck",
+    "undefined-references",
+    "undefined-citations",
+  ].every((k) => m.includes(k)),
+);
+check(
+  "a clean log carries no markers",
+  logMarkers([
+    "This is pdfTeX",
+    "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[0]]).includes("undefined-references"),
+);
+
+// ── error excerpt ───────────────────────────────────────────────────────────────────────
+const undefinedCs = [
+  "(/usr/share/texlive/texmf-dist/tex/latex/base/size10.clo)",
+  "./paper.tex:4: Undefined control sequence.",
+  "l.4 \\foo",
+  "         bar baz ",
+  "Here is how much of TeX's memory you used:",
+];
+const ex = errorExcerpt(undefinedCs);
+// Guards: the spelling rpp's own flags produce for most errors — with only the `!` form recognised,
+// an undefined control sequence fails with no error line quoted.
+check(
+  "-file-line-error form: the error line, the l.NNN line and the rest of the source line",
+  ex[0] === "./paper.tex:4: Undefined control sequence." &&
+    ex[1] === "l.4 \\foo" &&
+    ex[2].includes("bar baz"),
+);
+// Guards: the end of the excerpt — without it the excerpt runs into TeX's memory statistics and
+// buries the line the author needs.
+check(
+  "the excerpt stops at the context — the memory statistics are not quoted",
+  !ex.some((l) => l.startsWith("Here is how much")),
+);
+const missingPkg = [
+  ")",
+  "",
+  "! LaTeX Error: File `nopepkg.sty' not found.",
+  "",
+  "Type X to quit or <RETURN> to proceed,",
+  "or enter new name. (Default extension: sty)",
+  "",
+  "Enter file name: ",
+  "./paper.tex:3: Emergency stop.",
+  "<read *> ",
+  "         ",
+  "l.3 \\begin",
+  "          {document}^^M ",
+  "Here is how much of TeX's memory you used:",
+];
+const ex2 = errorExcerpt(missingPkg);
+check(
+  "the classic `!` form: the FIRST error is quoted, not the emergency stop after it",
+  ex2[0] === "! LaTeX Error: File `nopepkg.sty' not found.",
+);
+check(
+  "…and the excerpt runs to its l.NNN context, dropping blank lines",
+  ex2.includes("l.3 \\begin") && !ex2.some((l) => l.trim() === ""),
+);
+check(
+  "no error line — an empty excerpt",
+  errorExcerpt(["all fine"]).length === 0,
+);
+check(
+  "a warning that ends in `line 4.` is not an error line",
+  !isErrorLine(
+    "LaTeX Warning: Citation `k' on page 1 undefined on input line 4.",
+  ),
+);
+// Guards: the requirement that the prefix look like a path — without it, the first such line in a
+// package's info output is quoted as 'the error'.
+check(
+  "a path-less `word:12: ` is not an error line either",
+  !isErrorLine("Chapter:12: something"),
+);
+
+// ── bibtex ──────────────────────────────────────────────────────────────────────────────
+const bibOut = [
+  "This is BibTeX, Version 0.99d (TeX Live 2023/Debian)",
+  "The top-level auxiliary file: paper.aux",
+  "The style file: plain.bst",
+  "I couldn't open database file nope.bib",
+  "---line 5 of file paper.aux",
+  " : \\bibdata{nope",
+  "(There were 2 error messages)",
+].join("\n");
+const bx = bibtexExcerpt(bibOut);
+// Guards: filtering bibtex's fixed preamble — a failure would open with 'This is BibTeX, Version
+// 0.99d' and push the real reason down.
+check(
+  "bibtex: the banner is dropped, the explanation kept",
+  bx[0] === "I couldn't open database file nope.bib" &&
+    !bx.some((l) => l.startsWith("This is BibTeX")),
+);
+
+// ── aux ─────────────────────────────────────────────────────────────────────────────────
+const aux = [
+  "\\relax ",
+  "\\citation{knuth84}",
+  "\\citation{b,a}",
+  "\\bibstyle{plain}",
+  "\\bibdata{refs,more}",
+  "\\@input{chap1.aux}",
+  "\\newlabel{sec:intro}{{1}{1}{}{}{}}",
+].join("\n");
+const sub = "\\citation{c}\n\\citation{a}\n";
+const parsed = auxBib(aux, (name) => (name === "chap1.aux" ? sub : null));
+// Guards: citations from \include'd chapters — a \cite added in a chapter would not change the
+// citation set, and bibtex would not rerun for it.
+check(
+  "citations: sorted, unique, including the ones in an \\@input aux",
+  JSON.stringify(parsed.citations) ===
+    JSON.stringify(["a", "b", "c", "knuth84"]),
+);
+check(
+  "databases and style are read",
+  JSON.stringify(parsed.databases) === JSON.stringify(["refs", "more"]) &&
+    parsed.style === "plain",
+);
+check(
+  "an aux with no \\bibdata names no databases",
+  auxBib("\\relax\n\\citation{x}\n").databases.length === 0,
+);
+check(
+  "a self-including aux does not loop forever",
+  auxBib("\\@input{paper.aux}\n\\citation{x}", () => "\\@input{paper.aux}")
+    .citations.length === 1,
+);
+
+console.log(
+  `✓ ${String(n)} assertions passed — latex-log: markers across the 79-column wrap, both error spellings, aux`,
+);

package/src/latex-log.ts

@@ -0,0 +1,234 @@
+/**
+ * Reading what pdflatex and bibtex leave behind — PURE functions, text in, data out.
+ *
+ * `latex-loop.ts` decides what to run next; this module turns the files a pass wrote into the
+ * facts that decision needs. Nothing here touches the disk: the caller reads the file and hands
+ * over its text, so every function below is testable on a string.
+ *
+ * 🔴 WHY LINE MATCHING IS LEGITIMATE HERE. A `.log` has no grammar a parser could give us: it is
+ * the terminal transcript of a TeX run. What it does have is a small set of DOCUMENTED marker
+ * lines that LaTeX and its packages print word for word, and that every build tool (latexmk,
+ * arara, texlab) keys on. Those markers are the interface. The `.aux` is similar: TeX writes one
+ * command per line, and the three we read (`\citation`, `\bibdata`, `\bibstyle`) always start a
+ * line. Neither file is prose-with-structure that a parser would read better.
+ *
+ * 🔴 THE 79-COLUMN WRAP. TeX breaks every line it writes to the log at `max_print_line` (79 in
+ * TeX Live), counting BYTES. A marker that happens to straddle the break — "Rerun to get
+ * cross-references right." is the usual victim, since it closes a long warning — is not on any
+ * one physical line. `unwrapLog` rejoins a line of exactly 79 bytes with the next one. The caller
+ * must therefore read the log as `latin1`, so one character is one byte and `length` counts what
+ * TeX counted.
+ */
+
+/** 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:
+ *   - `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.
+ */
+export type LogMarker =
+  | "rerun-requested"
+  | "labels-changed"
+  | "rerunfilecheck"
+  | "undefined-references"
+  | "undefined-citations";
+
+/** Markers that mean "the output of this pass is not final yet". */
+export const RERUN_MARKERS: readonly 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.
+ *
+ * ⚠️ A line that is 79 bytes long BY ITSELF gets joined too — TeX gives no way to tell the two
+ * apart. The cost is one false join, which can only merge two lines, never split a marker; for
+ * the substring checks below that is harmless.
+ */
+export function unwrapLog(text: string): string[] {
+  const physical = text.split(/\r?\n/);
+  const out: string[] = [];
+  let carry = "";
+  for (const line of physical) {
+    if (line.length === MAX_PRINT_LINE) {
+      carry += line;
+      continue;
+    }
+    out.push(carry + line);
+    carry = "";
+  }
+  if (carry) out.push(carry);
+  return out;
+}
+
+/** Which markers a log carries, in a fixed order, each at most once. */
+export function logMarkers(lines: readonly string[]): LogMarker[] {
+  const found = new Set<LogMarker>();
+  for (const line of lines) {
+    if (line.includes("Rerun to get")) found.add("rerun-requested");
+    if (line.startsWith("LaTeX Warning: Label(s) may have changed"))
+      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));
+}
+
+/**
+ * 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
+ * classic `! LaTeX Error: File `x.sty' not found.` (measured on TeX Live 2023). The path part must
+ * contain a dot or a slash, so an ordinary warning ending in a number and a colon cannot pass.
+ */
+export function isErrorLine(line: string): boolean {
+  if (line.startsWith("!")) return true;
+  const m = /^([^\s:]+):(\d+): /.exec(line);
+  return m !== null && /[./]/.test(m[1] ?? "");
+}
+
+/** The `l.NNN …` line TeX prints to show where in the source it stopped. */
+export const isContextLine = (line: string): boolean => /^l\.\d+/.test(line);
+
+/** At most this many lines are quoted from a log: enough for the error and its context. */
+export const MAX_EXCERPT = 12;
+
+/**
+ * The first error of a pass and the source context after it: the error line, the lines up to
+ * and including `l.NNN`, and the one line after it (TeX splits the source line at the point of
+ * the error, so the rest of it sits on the next line). Blank lines are dropped. Empty when the
+ * log carries no error line — the caller then says so rather than printing nothing.
+ */
+export function errorExcerpt(lines: readonly string[]): string[] {
+  const start = lines.findIndex(isErrorLine);
+  if (start < 0) return [];
+  const out: string[] = [];
+  for (let i = start; i < lines.length && out.length < MAX_EXCERPT; i++) {
+    const line = lines[i] ?? "";
+    if (line.trim() === "") continue;
+    out.push(line);
+    if (isContextLine(line)) {
+      const next = lines[i + 1];
+      if (next !== undefined && next.trim() !== "") out.push(next);
+      break;
+    }
+  }
+  return out;
+}
+
+/** The lines bibtex prints before it has anything to say; never an explanation of a failure. */
+const BIBTEX_PREAMBLE = [
+  "This is BibTeX",
+  "Capacity:",
+  "The top-level auxiliary file:",
+  "The style file:",
+  "Database file #",
+];
+
+/** What bibtex said beyond its banner — the explanation of a failed run. */
+export function bibtexExcerpt(stdout: string): string[] {
+  return stdout
+    .split(/\r?\n/)
+    .filter(
+      (l) => l.trim() !== "" && !BIBTEX_PREAMBLE.some((p) => l.startsWith(p)),
+    )
+    .slice(0, MAX_EXCERPT);
+}
+
+/** What the `.aux` tells bibtex: the cited keys, the databases and the style. */
+export interface AuxBib {
+  /** Sorted, unique. `*` (`\nocite{*}`) is a key like any other. */
+  readonly citations: readonly string[];
+  /** The names in `\bibdata{…}`, as written — without `.bib`. */
+  readonly databases: readonly string[];
+  readonly style: string | null;
+}
+
+/** The argument of `\name{…}` when a line is exactly that command, else null. */
+function argOf(line: string, name: string): string | null {
+  const open = `\\${name}{`;
+  if (!line.startsWith(open) || !line.endsWith("}")) return null;
+  return line.slice(open.length, -1);
+}
+
+const list = (arg: string): string[] =>
+  arg
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+
+/** What one walk over an `.aux` tree has gathered so far. Lines are read IN ORDER: see below. */
+interface AuxAcc {
+  readonly citations: Set<string>;
+  readonly databases: string[];
+  style: string | null;
+}
+
+/** How a walk reaches nested aux files, and which it has already followed (a cycle ends there). */
+interface AuxWalk {
+  readonly readInput: (name: string) => string | null;
+  readonly seen: Set<string>;
+}
+
+/**
+ * Fold one aux line into the walk. Order is load-bearing: a nested aux's databases land where
+ * its `\@input` stands, and its style counts only while no `\bibstyle` has been read yet — a
+ * later one in the parent still overrides it.
+ */
+function readAuxLine(line: string, acc: AuxAcc, walk: AuxWalk): void {
+  for (const k of list(argOf(line, "citation") ?? "")) acc.citations.add(k);
+  acc.databases.push(...list(argOf(line, "bibdata") ?? ""));
+  const st = argOf(line, "bibstyle");
+  if (st !== null) acc.style = st.trim();
+  followInput(argOf(line, "@input"), acc, walk);
+}
+
+/** Merge an `\@input` aux into the walk — once per name, and only when it exists. */
+function followInput(input: string | null, acc: AuxAcc, walk: AuxWalk): void {
+  if (input === null || walk.seen.has(input)) return;
+  walk.seen.add(input);
+  const nested = walk.readInput(input);
+  if (nested === null) return;
+  const sub = auxBib(nested, walk.readInput, walk.seen);
+  for (const k of sub.citations) acc.citations.add(k);
+  acc.databases.push(...sub.databases);
+  acc.style ??= sub.style;
+}
+
+/**
+ * Read `\citation`, `\bibdata` and `\bibstyle` out of an `.aux`, following `\@input{sub.aux}` —
+ * `\include` writes each chapter's citations into its own aux file, and bibtex follows them too.
+ * `readInput` returns the text of a nested aux, or null when it does not exist.
+ */
+export function auxBib(
+  text: string,
+  readInput: (name: string) => string | null = () => null,
+  seen: Set<string> = new Set(),
+): AuxBib {
+  const acc: AuxAcc = { citations: new Set(), databases: [], style: null };
+  for (const raw of text.split(/\r?\n/))
+    readAuxLine(raw.trim(), acc, { readInput, seen });
+  return {
+    citations: [...acc.citations].sort(),
+    databases: acc.databases,
+    style: acc.style,
+  };
+}