paperlint 3.0.0 → 3.1.1

package/src/build-engine.test.ts

@@ -0,0 +1,137 @@
+/**
+ * build-engine.ts arms the harness does not reach: a system pdflatex that lacks packages (said
+ * before asking), an install that fails, an install that leaves packages missing, a cache used from
+ * an environment with no PATH, and the refusal line for a decision that is neither refuse nor ask.
+ */
+import assert from "node:assert/strict";
+import { chmodSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { test } from "vitest";
+import { useTempDir } from "../test/support.mjs";
+import { prepareEngine, refusal } from "./build-engine.ts";
+
+const work = useTempDir("paperlint-build-engine-test-");
+const TEX = { packages: { acmart: ["acmart.cls"] }, tools: {} };
+/** A runnable pdflatex in `dir`. */
+const texAt = (dir: string): string => {
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, "pdflatex"), "");
+  chmodSync(join(dir, "pdflatex"), 0o755);
+  return dir;
+};
+/** kpsewhich answers per bin directory. */
+const fakeRun = (found: Record<string, string>) =>
+  ((cmd: string) => ({
+    stdout: found[dirname(cmd)] ?? "",
+    status: 0,
+  })) as never;
+
+async function go(o: Parameters<typeof prepareEngine>[0]) {
+  const out: string[] = [];
+  const err: string[] = [];
+  const r = await prepareEngine({
+    log: (l) => out.push(l),
+    err: (l) => err.push(l),
+    platform: "linux",
+    interactive: true,
+    ask: async () => "y",
+    ...o,
+  });
+  return { r, out, err };
+}
+
+test("a system pdflatex lacking packages is named before asking; a failed install stops the run", async () => {
+  const sys = texAt(join(work, "sys", "bin"));
+  const x = await go({
+    tex: TEX,
+    env: { PAPERLINT_TEXLIVE_DIR: join(work, "empty-cache"), PATH: sys },
+    run: fakeRun({}),
+    install: () => ({ ok: false }),
+  });
+  assert.deepEqual(
+    [x.r, x.out],
+    [
+      { ok: false, code: 1 },
+      [`${join(sys, "pdflatex")} is not used: it lacks acmart`],
+    ],
+  );
+});
+
+test("an install that verifies but still lacks a package is refused, naming it", async () => {
+  const cache = join(work, "cache-lacking");
+  const x = await go({
+    tex: TEX,
+    env: { PAPERLINT_TEXLIVE_DIR: cache, PATH: join(work, "nothing") },
+    run: fakeRun({}),
+    install: () => {
+      texAt(join(cache, "2026", "bin", "x86_64-linux"));
+      return { ok: true, tree: { dir: "", year: "2026", bin: "" } };
+    },
+  });
+  assert.deepEqual(x.r, { ok: false, code: 1 });
+  assert.match(x.err.join("\n"), /missing: 1 package\(s\): acmart/);
+});
+
+test("an install that leaves no tree at all is refused with nothing named missing", async () => {
+  const x = await go({
+    tex: TEX,
+    env: {
+      PAPERLINT_TEXLIVE_DIR: join(work, "cache-none"),
+      PATH: join(work, "nothing"),
+    },
+    run: fakeRun({}),
+    install: () => ({ ok: true, tree: { dir: "", year: "2026", bin: "" } }),
+  });
+  assert.deepEqual(x.r, { ok: false, code: 1 });
+  assert.match(x.err.join("\n"), /missing: 0 package\(s\): \)/);
+});
+
+test("a complete cache is used from an environment with no PATH at all", async () => {
+  const bin = texAt(join(work, "cache-ok", "2026", "bin", "x86_64-linux"));
+  const x = await go({
+    tex: TEX,
+    env: { PAPERLINT_TEXLIVE_DIR: join(work, "cache-ok") },
+    run: fakeRun({ [bin]: "/t/acmart.cls\n" }),
+  });
+  assert.deepEqual(x.r, {
+    ok: true,
+    env: { PAPERLINT_TEXLIVE_DIR: join(work, "cache-ok"), PATH: `${bin}:` },
+  });
+});
+
+test("the refusal line for a decision to use a tree names nothing missing", () => {
+  assert.equal(
+    refusal({ kind: "use-cache" } as never, { system: null } as never),
+    "✗ paperlint build: no TeX Live with every package these papers need — run `npx paperlint toolchain` (missing: 0 package(s): )",
+  );
+});
+
+test("without an ask or an install given: Enter is yes, and the default install runs (here: every mirror fails)", async () => {
+  const cache = join(work, "cache-default");
+  const calls: string[] = [];
+  const out: string[] = [];
+  const err: string[] = [];
+  const r = await prepareEngine({
+    tex: TEX,
+    log: (l) => out.push(l),
+    err: (l) => err.push(l),
+    platform: "linux",
+    interactive: true,
+    env: {
+      PAPERLINT_TEXLIVE_DIR: cache,
+      PAPERLINT_CTAN_MIRROR: "https://mirror.invalid/tlnet",
+      PATH: join(work, "nothing"),
+    },
+    run: ((cmd: string) => {
+      calls.push(cmd.split("/").pop() ?? cmd);
+      return {
+        status: 22,
+        stdout: "",
+        stderr: "curl: (6) could not resolve\n",
+      };
+    }) as never,
+  });
+  assert.deepEqual(r, { ok: false, code: 1 });
+  assert.ok(calls.includes("curl"), calls.join(","));
+  assert.match(err.join("\n"), /no CTAN mirror returned install-tl/);
+});

package/src/build-engine.ts

@@ -13,6 +13,7 @@ import { homedir } from "node:os";
 import { delimiter, join } from "node:path";
 import {
   resolveEngine,
+  missingDependencies,
   probeTree,
   supportedPlatform,
   whichOnPath,
@@ -103,7 +104,11 @@ export function gatherFacts(o: Resolved): EngineFacts {
     (tree): TreeProbe => ({
       label: `TeX Live ${tree.year} — paperlint cache (${tree.dir})`,
       bin: tree.bin,
-      missing: probeTree(tree.bin, o.tex.packages, o.run),
+      // Only a cache tree is asked for its dependencies: its tlmgr writes where we own.
+      missing: [
+        ...probeTree(tree.bin, o.tex.packages, o.run),
+        ...missingDependencies(tree.bin, o.run),
+      ],
     }),
   );
   const cache = usableTree(probes, (p) => p.missing.length === 0);

package/src/build.harness.mjs

@@ -10,7 +10,6 @@
  * `build.sh` is never executed (checked by the trace it would leave on disk and by the list of
  * processes started), and a failed build removes the stale `paper.pdf` (checked on disk).
  */
-import assert from "node:assert/strict";
 import {
   mkdtempSync,
   mkdirSync,
@@ -23,6 +22,7 @@ import {
 import { tmpdir } from "node:os";
 import { join, dirname, delimiter } from "node:path";
 import { fileURLToPath } from "node:url";
+import { createChecker } from "../lib/check.mjs";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const {
@@ -44,11 +44,7 @@ const { packageVenuesDir } = await import(
   join(HERE, "..", "skills", "paper-pipeline", "scripts", "consumer.mjs")
 );
 
-let n = 0;
-const check = (label, cond) => {
-  assert.ok(cond, label);
-  n++;
-};
+const check = createChecker();
 
 const root = realpathSync(mkdtempSync(join(tmpdir(), "paperlint-build-")));
 // 🔴 banal is looked for under the temp root, never in the developer's cache: with the real
@@ -74,6 +70,10 @@ function fakeTex({
   log = "",
   missing = false,
   noPdf = false,
+  // `noLog`: pdflatex that dies before it opens paper.log (a format it cannot load); what it
+  // printed is `stdout`.
+  noLog = false,
+  stdout = "",
 } = {}) {
   const calls = [];
   const run = (bin, args, opts) => {
@@ -85,11 +85,11 @@ function fakeTex({
       };
     if (bin === "pdflatex") {
       writeFileSync(join(opts.cwd, "paper.aux"), aux);
-      writeFileSync(join(opts.cwd, "paper.log"), log);
+      if (!noLog) writeFileSync(join(opts.cwd, "paper.log"), log);
       // `noPdf`: what real pdflatex does on a document with no pages — "No pages of output.", exit 0.
       if (exitCode === 0 && !noPdf)
         writeFileSync(join(opts.cwd, "paper.pdf"), "%PDF-fake");
-      return { status: exitCode, stdout: "", stderr: "" };
+      return { status: exitCode, stdout, stderr: "" };
     }
     if (bin === "bibtex") {
       writeFileSync(join(opts.cwd, "paper.bbl"), "\\begin{thebibliography}{1}");
@@ -395,6 +395,46 @@ try {
   check("…and says the PDF was removed", /paper\.pdf removed/.test(shown));
   check("a failed pass is not retried", ftex.calls.length === 1);
 
+  // ── pdflatex dies before writing a log ────────────────────────────────────────────────
+  // Seen 2026-09-26: a TeX Live whose pdflatex format was never built. pdflatex exits 1 having
+  // printed the reason, and paper.log is either absent or left over from an earlier build.
+  const nolog = paper("nolog", {
+    "paper.tex": CLEAN_TEX,
+    "paper.log": "./paper.tex:9: OLD ERROR FROM YESTERDAY\nl.9 \\old\n",
+  });
+  const dieTex = fakeTex({
+    exitCode: 1,
+    noLog: true,
+    stdout:
+      "This is pdfTeX, Version 3.141592653-2.6-1.40.28 (TeX Live 2026) (INITEX)\n" +
+      "I can't find the format file `pdflatex.fmt'!\n",
+  });
+  const rn = await buildPaper(nolog, {
+    cwd: root,
+    readPdf: fakeRead,
+    run: dieTex.run,
+    env: ENV,
+    log: quiet,
+  });
+  const shownN = formatResult(rn);
+  // Guards: the reason pdflatex printed reaches the human when there is no log to quote.
+  check(
+    "🔴 no log: the failure shows what pdflatex printed",
+    rn.status === "failed" && shownN.includes("I can't find the format file"),
+    shownN,
+  );
+  // Guards: a log from an earlier build is never quoted as this build's error.
+  check(
+    "🔴 no log: a stale paper.log from an earlier build is not quoted",
+    !shownN.includes("OLD ERROR FROM YESTERDAY"),
+    shownN,
+  );
+  check(
+    "no log: it does not point at a log file that this run did not write",
+    !shownN.includes("full log:") && shownN.includes("wrote no paper.log"),
+    shownN,
+  );
+
   // ── pdflatex not installed ────────────────────────────────────────────────────────────
   const rm = await buildPaper(clean, {
     cwd: root,
@@ -467,8 +507,8 @@ try {
   check("on full success there is no remedy", remedyFor([r]) === "");
 
   // ── 🔴 A STALE PDF NEVER SURVIVES A RUN THAT DID NOT REPLACE IT — every path of buildPapers ──
-  // The order matters for the battery: the up-front removal is killed by the no-engine case, the
-  // existence check by the empty document, and neither case depends on the other defence.
+  // The order matters here: the up-front removal is exercised by the no-engine case below, the
+  // existence check by the empty-document case, and neither depends on the other defence.
   const REMOVED =
     "paper.pdf removed — a stale PDF must not pass for this build";
 
@@ -636,5 +676,5 @@ try {
 }
 
 console.log(
-  `✓ ${String(n)} assertions passed — build: paperlint compiles, build.sh never runs, a red build leaves no PDF`,
+  `✓ ${String(check.count)} assertions passed — build: paperlint compiles, build.sh never runs, a red build leaves no PDF`,
 );

package/src/build.test.ts

@@ -0,0 +1,362 @@
+/**
+ * build.ts edges the harness does not reach: the compile step's wording for every way pdflatex or
+ * bibtex stops, bibtex's input when the `.aux` names a database, the measure note for a review
+ * build, a stub page and a measured geometry, the loop over non-applicable steps, and the verdict
+ * lines. pdflatex and bibtex are a fake runner that writes the files the real ones would.
+ */
+import assert from "node:assert/strict";
+import { existsSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { test } from "vitest";
+import { useTempDir, writeTree } from "../test/support.mjs";
+import {
+  bibInput,
+  buildPaper,
+  buildPapers,
+  compileStep,
+  formatResult,
+  parseDocumentclass,
+  readFacts,
+  type BuildOptions,
+  type PaperFacts,
+} from "./build.ts";
+import type { Geometry } from "./domain/geometry.ts";
+import type { PdfReader } from "./pdf-facts.ts";
+
+const root = useTempDir("paperlint-build-test-");
+const TEX = "\\documentclass{article}\\begin{document}x\\end{document}";
+let n = 0;
+const paper = (files: Record<string, string> = { "paper.tex": TEX }) =>
+  writeTree(join(root, `p${String(n++)}`), files);
+
+interface Fake {
+  /** pdflatex's exit status; `null` is a signal. */
+  latex?: number | null;
+  /** bibtex's exit status, and what it prints. */
+  bibtex?: number | null;
+  bibtexOut?: string;
+  /** Which program cannot be started. */
+  missing?: "pdflatex" | "bibtex";
+  aux?: string;
+  log?: string;
+  /** pdflatex dies before opening paper.log, printing nothing. */
+  noLog?: boolean;
+  /** Each pass writes a different .aux, so the loop never settles. */
+  churn?: boolean;
+}
+/** A pdflatex pass: writes the .aux, the log unless it dies first, and a PDF when it exits 0. */
+function latexPass(f: Fake, cwd: string, pass: number) {
+  const status = "latex" in f ? f.latex : 0;
+  const aux = f.churn ? `\\relax % ${String(pass)}\n` : (f.aux ?? "\\relax\n");
+  writeFileSync(join(cwd, "paper.aux"), aux);
+  if (!f.noLog) writeFileSync(join(cwd, "paper.log"), f.log ?? "");
+  if (status === 0) writeFileSync(join(cwd, "paper.pdf"), "%PDF-fake");
+  return f.noLog ? { status } : { status, stdout: "", stderr: "" };
+}
+/** A bibtex run: writes the .bbl; status and output as the case says. */
+function bibtexRun(f: Fake, cwd: string) {
+  writeFileSync(join(cwd, "paper.bbl"), "\\begin{thebibliography}{1}");
+  if (f.bibtex === undefined)
+    return { status: 0, stdout: "This is BibTeX\n", stderr: "" };
+  return f.bibtexOut === undefined
+    ? { status: f.bibtex }
+    : { status: f.bibtex, stdout: f.bibtexOut };
+}
+function fakeRun(f: Fake): BuildOptions["run"] {
+  let pass = 0;
+  return ((bin: string, _args: string[], opts: { cwd: string }) => {
+    if (bin === f.missing)
+      return {
+        error: Object.assign(new Error("spawn ENOENT"), { code: "ENOENT" }),
+        status: null,
+      };
+    return bin === "pdflatex"
+      ? latexPass(f, opts.cwd, ++pass)
+      : bibtexRun(f, opts.cwd);
+  }) as never;
+}
+
+const NO_GEOMETRY: Geometry = {
+  kind: "unmeasured",
+  why: ["no banal"],
+  tried: null,
+};
+const page = (words: number, numbered = 0) => ({
+  widthPt: 612,
+  heightPt: 792,
+  words: [
+    ...Array.from({ length: numbered }, (_, i) => ({
+      x0: 20,
+      y0: 60 + i * 10,
+      x1: 30,
+      y1: 70 + i * 10,
+      text: String(i + 1),
+    })),
+    ...Array.from({ length: words }, (_, i) => ({
+      x0: i % 2 ? 320 : 54,
+      y0: 60 + (i >> 1) * 10,
+      x1: i % 2 ? 340 : 74,
+      y1: 70 + (i >> 1) * 10,
+      text: "w",
+    })),
+  ],
+});
+const reader =
+  (last = page(80)): PdfReader =>
+  async () => ({
+    ok: true,
+    facts: {
+      pages: 1,
+      fonts: {
+        kind: "drawn",
+        list: [{ kind: "embedded", name: "CMR10", program: "Type1" }],
+      },
+      last,
+      layout: [],
+    },
+  });
+const quiet = () => {};
+/** buildPaper with fakes; the verdict line is what the command would print for it. */
+async function build(dir: string, f: Fake = {}, over: BuildOptions = {}) {
+  const r = await buildPaper(dir, {
+    cwd: root,
+    log: quiet,
+    env: { PAPERLINT_BANAL_DIR: join(root, "no-banal") },
+    run: fakeRun(f),
+    readPdf: reader(),
+    measure: { measure: () => NO_GEOMETRY },
+    ...over,
+  });
+  return { r, line: formatResult(r).replaceAll(root, "<root>") };
+}
+
+test("documentclass: an empty name is no class; a macro inside the name contributes nothing", () => {
+  assert.equal(parseDocumentclass("\\documentclass{}"), null);
+  // Nested deep enough to exhaust the parser's stack: no class, not a crash.
+  assert.equal(
+    parseDocumentclass(`\\documentclass{x}${"{".repeat(20_000)}`),
+    null,
+  );
+  assert.deepEqual(parseDocumentclass("\\documentclass{a\\foo{}b}"), {
+    name: "ab",
+    options: [],
+  });
+  // unified-latex attaches arguments to the macros it has a signature for; a tree where
+  // `\documentclass` came back bare has no name to read, and is no class.
+  assert.equal(
+    parseDocumentclass("\\documentclass", {
+      parse: () =>
+        ({
+          type: "root",
+          content: [{ type: "macro", content: "documentclass" }],
+        }) as never,
+    }),
+    null,
+  );
+});
+
+test("facts of a paper with no paper.tex: no class", () => {
+  assert.deepEqual(readFacts(paper({ "paper.md": "# P\n" })), {
+    main: null,
+    documentclass: null,
+    venue: null,
+    ignoredScripts: [],
+  });
+});
+
+test("compile's plan line names the options, a missing class and the venue", () => {
+  const facts = (over: Partial<PaperFacts>): PaperFacts => ({
+    main: "paper.tex",
+    documentclass: null,
+    venue: null,
+    ignoredScripts: [],
+    ...over,
+  });
+  assert.deepEqual(
+    [
+      compileStep.applies(
+        facts({
+          documentclass: { name: "acmart", options: ["sigconf", "review"] },
+        }),
+      ),
+      compileStep.applies(facts({ venue: "aisec" })),
+    ],
+    [
+      { yes: true, why: "paper.tex (\\documentclass[sigconf,review]{acmart})" },
+      { yes: true, why: "paper.tex (no \\documentclass found, venue aisec)" },
+    ],
+  );
+});
+
+test("bibtex's input: no .aux, nothing named, a database named with and without .bib, one that is missing", () => {
+  assert.deepEqual(bibInput(paper({})), { kind: "none" });
+  const none = paper({ "paper.aux": "\\relax\n" });
+  assert.deepEqual(bibInput(none), { kind: "none" });
+  const named = paper({
+    "paper.aux": "\\citation{k}\n\\bibstyle{plain}\n\\bibdata{a.bib,missing}\n",
+    "a.bib": "@misc{k}\n",
+  });
+  const got = bibInput(named);
+  assert.deepEqual(
+    { ...got, bibHash: got.kind === "needed" && typeof got.bibHash },
+    {
+      kind: "needed",
+      citations: ["k"],
+      databases: ["a.bib", "missing"],
+      style: "plain",
+      bibHash: "string",
+    },
+  );
+  const gone = bibInput(paper({ "paper.aux": "\\bibdata{gone}\n" }));
+  assert.equal(gone.kind === "needed" && gone.bibHash, null);
+});
+
+test("compile: pdflatex killed by a signal, with no log and nothing printed", async () => {
+  const { line } = await build(paper(), { latex: null, noLog: true });
+  assert.equal(
+    line,
+    [
+      "  ✗ compile: pdflatex exited with 1",
+      "      pdflatex wrote no paper.log — the last lines it printed:",
+      "      paper.pdf removed — a stale PDF must not pass for this build",
+    ].join("\n"),
+  );
+});
+
+test("compile: bibtex that cannot start, and bibtex that fails, quote the .blg", async () => {
+  const aux = "\\citation{k}\n\\bibstyle{plain}\n\\bibdata{refs}\n";
+  const files = { "paper.tex": TEX, "refs.bib": "@misc{k}\n" };
+  const cannot = await build(paper(files), { aux, missing: "bibtex" });
+  assert.match(cannot.line, /^ {2}✗ compile: bibtex exited with 127\n/);
+  const dir = paper(files);
+  const failed = await build(dir, {
+    aux,
+    bibtex: 2,
+    bibtexOut:
+      "I couldn't open database file refs.bib\n---line 3 of file paper.aux\n",
+  });
+  assert.match(failed.line, /^ {2}✗ compile: bibtex exited with 2\n/);
+  assert.match(failed.line, /full log: <root>\/p\d+\/paper\.blg/);
+  const signal = await build(paper(files), { aux, bibtex: null });
+  assert.match(
+    signal.line,
+    /bibtex exited with 1\n {6}\(no error line found in the log\)/,
+  );
+});
+
+test("compile: a document whose .aux never settles did not converge", async () => {
+  const { line } = await build(paper(), { churn: true });
+  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(), {
+    log: "LaTeX Warning: There were undefined references.\n",
+  });
+  assert.equal(r.status, "built");
+  assert.match(r.notes?.[0] ?? "", /— ⚠️ the final log still reports /);
+});
+
+test("measure: a review build and a stub last page are named; a measured geometry adds nothing", async () => {
+  const review = await build(paper(), {}, { readPdf: reader(page(20, 60)) });
+  assert.match(
+    review.line,
+    /last page has numbered lines \(a review build\), not measured/,
+  );
+  const stub = await build(paper(), {}, { readPdf: reader(page(3)) });
+  assert.match(stub.line, /last page has 3 words, too few to measure/);
+  const measured = await build(
+    paper(),
+    {},
+    {
+      measure: {
+        measure: () => ({
+          kind: "measured",
+          by: { tool: "banal", path: "/b", how: "$BANAL" },
+          geometry: {
+            pageWidthIn: 8.5,
+            pageHeightIn: 11,
+            columns: 2,
+            bodyPt: 9,
+            refPt: 7,
+            bodyPages: 1,
+            refPages: 0,
+            appendixPages: 0,
+            pagesByType: { body: 1 },
+          },
+        }),
+      },
+    },
+  );
+  assert.doesNotMatch(measured.line, /page geometry not measured/);
+});
+
+test("a step that does not apply is skipped; a run whose steps leave no note prints the bare PDF", async () => {
+  const { line } = await build(
+    paper(),
+    {},
+    {
+      steps: [
+        {
+          name: "never",
+          required: false,
+          applies: () => ({ yes: false, why: "no" }),
+          run: () => {
+            throw new Error("ran");
+          },
+        },
+        {
+          name: "quiet",
+          required: true,
+          applies: () => ({ yes: true, why: "yes" }),
+          run: () => ({ ok: true }),
+        },
+      ],
+    },
+  );
+  assert.equal(line, "  ✓ paper.pdf");
+});
+
+test("paths: a paper that IS the working directory is named by its full path", async () => {
+  const dir = paper();
+  const logged: string[] = [];
+  await buildPaper(dir, {
+    cwd: dir,
+    log: (l) => logged.push(l),
+    dryRun: true,
+    measure: { measure: () => NO_GEOMETRY },
+  });
+  assert.equal(logged[0], dir);
+  const lines: string[] = [];
+  writeFileSync(join(dir, "paper.pdf"), "%PDF-old");
+  const run = await buildPapers([dir], {
+    cwd: dir,
+    log: (l) => lines.push(l),
+    engine: async () => null,
+  });
+  assert.deepEqual(
+    [run, lines],
+    [
+      { kind: "no-engine" },
+      [`${dir}: paper.pdf removed — a stale PDF must not pass for this build`],
+    ],
+  );
+  assert.equal(existsSync(join(dir, "paper.pdf")), false);
+});
+
+test("facts that cannot be read fail the build at `facts`", async () => {
+  const { line } = await build(
+    paper({ "paper.tex": TEX, "paperlint.json": "{ nope" }),
+  );
+  assert.match(line, /^ {2}✗ facts: /);
+});
+
+test("a failed result without its lines still says what failed", () => {
+  assert.equal(
+    formatResult({ dir: "d", status: "failed", plan: [] }),
+    [
+      "  ✗ build: failed",
+      "      paper.pdf removed — a stale PDF must not pass for this build",
+    ].join("\n"),
+  );
+});