paperlint 3.0.0 → 3.1.0

package/eslint-rules/paper-typography.mjs

@@ -50,6 +50,14 @@
  * inserts the zero there. The arXiv lookbehind stays: in `2310.05736` the dot follows a digit.
  * A text macro outside the known set (`\hl{.05}`) is read as a parameter and NOT reported — a
  * miss costs less than a finding on markup.
+ *
+ * 🔴 A NUMBER AFTER `¶` OR `§` IS A DESIGNATOR, NOT A DECIMAL (#102). An auditing standard is cited
+ * by paragraph as `¶¶.42`, and `--fix` rewrote it to `¶¶0.42` — a fix that changed a reference.
+ * So a lexeme right after the sign (`¶`, `§`, `\P`, `\S`, spaces or `~` between) is silent. The
+ * same sentence then goes on `and .44`: a paragraph number continuing the list, or a decimal —
+ * the text does not say which. In a paragraph that already cites `¶.nn` this way, a bare decimal
+ * is REPORTED WITHOUT A FIX and the zero is offered as a suggestion: an autofix must never be the
+ * one to decide what a number means. A real `.05` in any other paragraph is fixed as before.
  */
 import { getParser } from "@unified-latex/unified-latex-util-parse";
 
@@ -312,16 +320,43 @@ function sectionWord(context) {
 // (2310.05736) out: there the dot follows a digit.
 const BARE_DECIMAL = /(?<![\d.\w])\.\d{2,}\b/g;
 
+// A paragraph or section sign — the glyph, or `\P`/`\S` not followed by a letter — and what may
+// sit between it and the number. Both read the SOURCE, because in LaTeX `\P\P.42` reaches the
+// visible runs as `.42` alone: the macros end the run.
+const DESIGNATOR_BEFORE = /(?:[¶§]|\\[PS](?![A-Za-z]))[ \t~]*$/;
+const DESIGNATED = /(?:[¶§]|\\[PS](?![A-Za-z]))[ \t~]*\.\d/;
+
+/** The source of the paragraph holding `i`, up to `i`: from the last blank line before it. */
+const paragraphBefore = (src, i) => {
+  const head = src.slice(0, i);
+  const blank = [...head.matchAll(/\n[ \t]*\n/g)].at(-1);
+  return head.slice(blank ? blank.index + blank[0].length : 0);
+};
+
 function leadingZero(context) {
-  for (const r of visibleRuns(context.sourceCode))
+  const sc = context.sourceCode;
+  const src = isTex(sc) ? sc.raw : sc.text;
+  for (const r of visibleRuns(sc))
     for (const m of r.text.matchAll(BARE_DECIMAL)) {
       const dot = r.offs[m.index];
       if (dot === null || dot === undefined) continue;
-      at(context, dot, dot + 1, {
-        messageId: "bare",
-        data: { n: m[0] },
-        fix: (f) => f.insertTextBeforeRange([dot, dot], "0"),
-      });
+      const before = paragraphBefore(src, dot);
+      if (DESIGNATOR_BEFORE.test(before)) continue;
+      const zero = (f) => f.insertTextBeforeRange([dot, dot], "0");
+      at(
+        context,
+        dot,
+        dot + 1,
+        DESIGNATED.test(before)
+          ? {
+              messageId: "ambiguous",
+              data: { n: m[0] },
+              suggest: [
+                { messageId: "insertZero", data: { n: m[0] }, fix: zero },
+              ],
+            }
+          : { messageId: "bare", data: { n: m[0] }, fix: zero },
+      );
     }
 }
 
@@ -349,13 +384,14 @@ function figureRefStyle(context) {
   }
 }
 
-const rule = (description, messages, check) => ({
+const rule = (description, messages, check, meta = {}) => ({
   meta: {
     type: "suggestion",
     fixable: "code",
     docs: { description },
     schema: [],
     messages,
+    ...meta,
   },
   create: (context) => ({ "root:exit": () => check(context) }),
 });
@@ -373,8 +409,12 @@ export default {
       "a decimal below 1 written without its leading zero (IEEE / ISO 80000-1); fixable",
       {
         bare: "`{{n}}` has no leading zero — write `0{{n}}` (IEEE / ISO 80000-1); `paperlint lint --fix` inserts it",
+        ambiguous:
+          "`{{n}}` in a paragraph that cites `¶`/`§` numbers: a decimal without its leading zero, or another paragraph number? Not fixed automatically — write `0{{n}}` for a decimal, or put the sign before a paragraph number",
+        insertZero: "It is a decimal: write `0{{n}}`",
       },
       leadingZero,
+      { hasSuggestions: true },
     ),
     "figure-ref-style": rule(
       "`Fig.~\\ref` and `Figure~\\ref` mixed in one document; fixable to the majority form",

package/eslint-rules/paper-typography.test.mjs

@@ -203,6 +203,46 @@ describe("paper/leading-zero", () => {
   });
 });
 
+describe("paper/leading-zero — a number after ¶ or § is not a decimal (#102)", () => {
+  // From a consumer's bibliography: `--fix` rewrote the paragraph number `¶¶.42` to `¶¶0.42`.
+  const CITE =
+    "PCAOB. \\emph{Audit of Financial Statements}, ¶¶.42 (design\neffectiveness) and .44 (operating effectiveness).";
+
+  it.each([
+    ["¶¶.42", "Standard 5, ¶¶.42 applies."],
+    ["¶ .42", "Standard 5, ¶ .42 applies."],
+    ["\\P\\P.42", "Standard 5, \\P\\P.42 applies."],
+    ["§.12", "Rule 10b-5, §.12 applies."],
+  ])("SILENT: %s is a designator", async (_, body) => {
+    // Guards: the defect — the lexeme after a paragraph/section sign was read as a decimal.
+    expect(ids(await lint(doc(body)), "paper/leading-zero")).toEqual([]);
+    expect(await fixed(doc(body))).toBe(doc(body));
+  });
+
+  it("🔴 the list continuation `and .44` is reported WITHOUT a fix, with the zero as a suggestion", async () => {
+    const res = await lint(doc(CITE));
+    const found = ids(res, "paper/leading-zero");
+    expect(found.map((m) => [m.line, m.message.slice(0, 5)])).toEqual([
+      [4, "`.44`"],
+    ]);
+    expect(found[0].fix).toBeUndefined();
+    expect(found[0].suggestions).toHaveLength(1);
+    // Guards: --fix changes nothing in an ambiguous paragraph — neither number.
+    expect(await fixed(doc(CITE))).toBe(doc(CITE));
+  });
+
+  it("…while a real decimal still fixes, in markdown too, even beside a cited paragraph", async () => {
+    const body = `${CITE}\n\nWe use a threshold of .05 throughout.`;
+    expect(await fixed(doc(body))).toBe(
+      doc(`${CITE}\n\nWe use a threshold of 0.05 throughout.`),
+    );
+    const md = "See ¶¶.42 and .44.\n\nSignificant at p<.05.\n";
+    expect(await fixed(md, "paper.md")).toBe(
+      "See ¶¶.42 and .44.\n\nSignificant at p<0.05.\n",
+    );
+  });
+});
+
 describe("paper/figure-ref-style", () => {
   it("the minority form is reported and rewritten to the majority", async () => {
     const src = doc("Figure~\\ref{a}, Figure~\\ref{b} and Fig.~\\ref{c}.");

package/eslint-rules/review-frontmatter.schema.json

@@ -2,7 +2,7 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "urn:paperlint:review-frontmatter",
   "title": "paperlint review frontmatter",
-  "description": "The YAML frontmatter of a review report under reviews/. A review with no `findings` key is not a findings record and is not checked for findings. A project adds its own required fields with the `reviewSchema` setting; its schema is applied together with this one.",
+  "description": "The YAML frontmatter of a review report under reviews/. A review with no `findings` key is not a findings record and is not checked for findings.",
   "type": "object",
   "properties": {
     "findings": {

package/fixtures/toolchain-mirror/catalog.txt

@@ -3,3 +3,4 @@ acmart acmart.cls
 libertine libertine.sty
 texcount bin:texcount
 liar other.sty
+unicode-data GraphemeBreakProperty.txt

package/fixtures/toolchain-mirror/install-tl

@@ -17,11 +17,14 @@ if [ -n "${FAKE_INSTALL_TL_FAIL:-}" ]; then
   exit 1
 fi
 mkdir -p "$dir/bin/x86_64-linux"
-for t in pdflatex kpsewhich tlmgr; do
+for t in pdflatex kpsewhich tlmgr fmtutil-sys; do
   cp "$here/stub-$t" "$dir/bin/x86_64-linux/$t"
   chmod +x "$dir/bin/x86_64-linux/$t"
 done
 : > "$dir/files.txt"
 # The real install-tl leaves release-texlive.txt at TEXDIR; stub-tlmgr reads the tree's year there.
 cp "$here/release-texlive.txt" "$dir/release-texlive.txt"
+# The real install-tl, when a mirror fails to serve a package, prints "continuing anyway" and
+# exits as if nothing happened. FAKE_INSTALL_TL_DROP names the package it lost.
+if [ -n "${FAKE_INSTALL_TL_DROP:-}" ]; then echo "$FAKE_INSTALL_TL_DROP" > "$dir/missing-deps.txt"; fi
 echo "fake install-tl: scheme-basic into $dir"

package/fixtures/toolchain-mirror/stub-fmtutil-sys

@@ -0,0 +1,4 @@
+#!/bin/sh
+# Stands in for fmtutil-sys: records its arguments in fmtutil.log at the tree root.
+bin=$(cd "$(dirname "$0")" && pwd)
+echo "$*" >> "$bin/../../fmtutil.log"

package/fixtures/toolchain-mirror/stub-tlmgr

@@ -9,6 +9,15 @@ while [ $# -gt 0 ]; do
   case "$1" in
     --repository) repo=$2; shift 2 ;;
     install) shift; break ;;
+    # `check depends` in tlmgr's own layout: every name in missing-deps.txt (what the stub
+    # install-tl was told to drop) is a dependency without a package. Not logged: it installs nothing.
+    check)
+      if [ -s "$tree/missing-deps.txt" ]; then
+        echo " DEPENDS WITHOUT PACKAGES:"
+        sed 's/$/ in: collection-basic latex-bin/' "$tree/missing-deps.txt"
+        exit 2
+      fi
+      exit 0 ;;
     *) shift ;;
   esac
 done
@@ -34,6 +43,12 @@ for p in "$@"; do
     status=1
     continue
   fi
+  # Installing a dropped dependency repairs the tree.
+  # Portable on purpose: macOS sed -i takes a backup suffix, GNU sed does not.
+  if [ -f "$tree/missing-deps.txt" ]; then
+    grep -vx "$p" "$tree/missing-deps.txt" > "$tree/missing-deps.tmp" || true
+    mv "$tree/missing-deps.tmp" "$tree/missing-deps.txt"
+  fi
   for item in ${line#* }; do
     case "$item" in
       bin:*) : > "$bin/${item#bin:}"; chmod +x "$bin/${item#bin:}" ;;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paperlint",
-  "version": "3.0.0",
+  "version": "3.1.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/scripts/mutation-batteries.frozen.json

@@ -99,7 +99,7 @@
       "cases": 6
     },
     "src/new-paper.mutations.mjs": {
-      "cases": 4
+      "cases": 3
     },
     "src/structure.mutations.mjs": {
       "cases": 4

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

@@ -74,6 +74,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 +89,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 +399,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,

package/src/build.ts

@@ -354,9 +354,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 +364,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 +414,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 +472,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}`]),
         ],
       };
     }

package/src/cli.harness.mjs

@@ -996,7 +996,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',
@@ -1783,7 +1783,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({