paperlint 3.0.0 → 3.1.1

package/src/build.ts

@@ -187,11 +187,16 @@ function argText(arg: LatexArgument | undefined): string {
     .join("");
 }
 
-/** A unified-latex AST, or null when the text does not parse. */
-function parseTex(tex: string): LatexRoot | null {
+/** A unified-latex AST, or null when the text does not parse. `parse` is unified-latex's parser. */
+function parseTex(
+  tex: string,
+  parse: (tex: string) => LatexRoot = (t) => getParser().parse(t),
+): LatexRoot | null {
   try {
-    return getParser().parse(tex);
+    return parse(tex);
   } catch {
+    // The parser recurses per group: ~20 000 nested `{` exhaust the stack (RangeError). Such a
+    // file has no class to report, and must not fail the build at `facts` for it.
     return null;
   }
 }
@@ -200,8 +205,11 @@ function parseTex(tex: string): LatexRoot | null {
  * `\documentclass[opts]{name}`, read by the unified-latex parser the lint rules already use —
  * so a `\documentclass` inside a comment is a comment, not a class.
  */
-export function parseDocumentclass(tex: string): PaperFacts["documentclass"] {
-  return documentclassOf(parseTex(tex));
+export function parseDocumentclass(
+  tex: string,
+  { parse }: { parse?: (tex: string) => LatexRoot } = {},
+): PaperFacts["documentclass"] {
+  return documentclassOf(parseTex(tex, parse));
 }
 
 function documentclassOf(ast: LatexRoot | null): PaperFacts["documentclass"] {
@@ -354,9 +362,8 @@ function latexPass(
   const r = ctx.run("pdflatex", pdflatexArgs(final), opts);
   if (r.error) return null;
   const exitCode = r.status ?? 1;
-  const log = unwrapLog(
-    readOr(join(ctx.paperDir, `${JOB}.log`), "latin1") ?? "",
-  );
+  const written = readOr(join(ctx.paperDir, `${JOB}.log`), "latin1");
+  const log = unwrapLog(written ?? "");
   return {
     step: "latex",
     final,
@@ -365,10 +372,30 @@ function latexPass(
     after: hashes(ctx.paperDir),
     markers: logMarkers(log),
     bib: bibInput(ctx.paperDir),
-    errorLines: exitCode === 0 ? [] : errorExcerpt(log).map(fromLatin1),
+    errorLines:
+      exitCode === 0
+        ? []
+        : written === null
+          ? printed(r)
+          : errorExcerpt(log).map(fromLatin1),
   };
 }
 
+/**
+ * The last lines pdflatex printed, for the run that wrote no log — it died before opening one (a
+ * format it cannot load, a missing TeX Live file). Marked by NO_LOG, which the report keys on.
+ */
+function printed(r: { stdout?: unknown; stderr?: unknown }): string[] {
+  const lines = fromLatin1(
+    `${String(r.stdout ?? "")}\n${String(r.stderr ?? "")}`,
+  )
+    .split("\n")
+    .filter((l) => l.trim());
+  return [NO_LOG, ...lines.slice(-8).map((l) => `  ${l}`)];
+}
+
+const NO_LOG = `pdflatex wrote no ${JOB}.log — the last lines it printed:`;
+
 /** One bibtex run, on the input the `.aux` names BEFORE it runs, or null when it could not start. */
 function bibtexPass(ctx: BuildContext, opts: SpawnOptions): Observation | null {
   const before = hashes(ctx.paperDir);
@@ -395,6 +422,9 @@ export function compile(ctx: BuildContext): {
 } {
   const history: Observation[] = [];
   const opts = spawnOptions(ctx);
+  // Every log this loop reads is one its own pdflatex wrote. A pdflatex that dies before opening
+  // paper.log would otherwise have an earlier build's error quoted as this one's.
+  rmSync(join(ctx.paperDir, `${JOB}.log`), { force: true });
   const runs = { latex: 0, bibtex: 0 };
   for (;;) {
     const step = nextStep(summarize(history));
@@ -450,7 +480,7 @@ export const compileStep: BuildStep = {
           ...(end.lines.length
             ? end.lines
             : ["(no error line found in the log)"]),
-          `full log: ${log}`,
+          ...(end.lines[0] === NO_LOG ? [] : [`full log: ${log}`]),
         ],
       };
     }
@@ -828,10 +858,6 @@ function formatRefusal(r: BuildResult): string {
   return r.staleRemoved ? `${refused}\n      ${PDF_REMOVED}` : refused;
 }
 
-export function formatResults(results: readonly BuildResult[]): string {
-  return results.map(formatResult).join("\n");
-}
-
 /**
  * 🔴 "Nothing to compile" COUNTS AS A REFUSAL on a par with a failed build. Failing to tell these
  * two apart is what once produced a green run over a paper no job had built.

package/src/cli.harness.mjs

@@ -11,8 +11,6 @@
  *      leaked out of the depths of eslint-helpers.
  * Both are pinned down by the assertions below so there is no going back.
  */
-import assert from "node:assert/strict";
-import { recordCheck } from "vigiles";
 import { load as yamlLoad } from "js-yaml";
 import {
   mkdtempSync,
@@ -31,6 +29,7 @@ import { tmpdir } from "node:os";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { PAPERS_DIR_FIELD, findProjectRoot } from "../lib/paper-config.mjs";
+import { createChecker } from "../lib/check.mjs";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const { run, parseArgs, buildConfig, nextSteps, toPaths, runHook } =
@@ -39,14 +38,9 @@ const { init, choosePapers, offerWorkflow, missingPrograms, WORKFLOW_PATH } =
   await import(join(HERE, "init.ts"));
 const { PROGRAMS } = await import(join(HERE, "doctor.ts"));
 
-let n = 0;
 // Counted by vigiles too: `init` now loads `vigiles/claude-code` for its merge, and a harness that
 // loads vigiles without recording a check is reported as having verified nothing.
-const check = (label, cond) => {
-  assert.ok(cond, label);
-  recordCheck(label);
-  n++;
-};
+const check = createChecker();
 
 /** Runs the utility with output captured — quieter and faster than spawning a process. */
 async function cli(args, cwd) {
@@ -73,10 +67,9 @@ async function cli(args, cwd) {
     };
   } catch (e) {
     // 🔴 A LEAKED EXCEPTION IS A PROPERTY THAT MUST BE ASSERTED, NOT CAUGHT BY LETTING THE
-    // HARNESS CRASH. The mutation that removes the catch around ESLint used to bring the
-    // harness down with a stack trace, and the driver — under its own strict rule "killed only
-    // by ITS OWN assertion" — refused to count that as a kill and printed "survived". I.e. the
-    // real defect looked like a weak test.
+    // HARNESS CRASH. Removing the catch around ESLint brings the whole harness down with a
+    // stack trace instead of a clean, named assertion failure — i.e. the real defect would
+    // look like a broken test, not a caught one.
     return {
       code: 99,
       out: `THREW: ${e?.message ?? e}`,
@@ -537,8 +530,8 @@ check(
       // declaration had already been written — i.e. the install both succeeded and looked like
       // a crash.
       // 🔴 THE `.catch` HERE IS LOAD-BEARING, NOT CAUTION. A leaked exception is a PROPERTY that
-      // gets asserted; caught by letting the harness crash it reads to the battery's driver as
-      // "the mutation survived", i.e. the real defect would look like a hole in the test.
+      // gets asserted; without it, the harness crashes instead of failing a named assertion,
+      // i.e. the real defect would look like a hole in the test rather than a caught one.
       const aborted = await offerWorkflow(dir, "writing", {
         interactive: true,
         ask: async () => {
@@ -599,7 +592,7 @@ check(
       });
       // 🔴 JUDGE ONLY init's OWN REPORT, BEFORE doctor's banner. The first version of these
       // three assertions looked at the WHOLE output — and doctor also prints `✗ pdflatex` and
-      // the same install command. The mutation that stripped the remedy OUT of init stayed
+      // the same install command. A version of init with the remedy stripped OUT still stayed
       // green: the assertion found a line printed by a different command and reported coverage
       // that did not exist.
       const own = out.text().split("── paperlint doctor")[0];
@@ -996,7 +989,7 @@ check(
     );
     check(
       "and the finding is printed before the ESLint report, with its consequence",
-      /missing `PIPELINE-STATUS\.md`/.test(r.out) && /is checked/.test(r.out),
+      /missing `PIPELINE-STATUS\.md`/.test(r.out) && /are skipped/.test(r.out),
     );
     check(
       'and it does NOT print "no findings" over something that was found',
@@ -1260,7 +1253,7 @@ check(
 }
 
 console.log(
-  `✓ ${String(n)} assertions passed — paperlint lint, one command instead of hand-rolled config`,
+  `✓ ${String(check.count)} assertions passed — paperlint lint, one command instead of hand-rolled config`,
 );
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -1783,7 +1776,7 @@ console.log(
       "🔴 an optional rule turned on for a glob that reaches no paper.tex FAILS the run — not a green zero",
       silent.code === 1 &&
         silent.out.includes(
-          'pdf/last-page-balance is turned on in "rules", but no linted paper.tex gets it',
+          'pdf/last-page-balance is turned on in "rules", but no paper.tex of the project gets it',
         ),
     );
     settings({
@@ -1799,5 +1792,5 @@ console.log(
 }
 
 console.log(
-  `✓ ${String(n)} assertions in total, including init's hooks and paperlint new`,
+  `✓ ${String(check.count)} assertions in total, including init's hooks and paperlint new`,
 );