paperlint 3.1.0 → 3.1.2

package/src/tex-requirements.harness.mjs

@@ -7,7 +7,6 @@
  *   2. the schema REJECTS what it must — each bad profile names the offending path;
  *   3. what a paper gets: its venue plus the base set, or the base set with the reason said.
  */
-import assert from "node:assert/strict";
 import {
   copyFileSync,
   mkdtempSync,
@@ -19,6 +18,7 @@ import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import ts from "typescript";
+import { createChecker } from "../lib/check.mjs";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const VENUES = join(
@@ -31,11 +31,7 @@ const VENUES = join(
 );
 const R = await import(join(HERE, "tex-requirements.ts"));
 
-let n = 0;
-const check = (label, cond, detail = "") => {
-  assert.ok(cond, `${label}${detail ? ` — ${detail}` : ""}`);
-  n++;
-};
+const check = createChecker();
 const throws = (fn) => {
   try {
     fn();
@@ -229,4 +225,35 @@ rmSync(tmp, { recursive: true, force: true });
   );
 }
 
-console.log(`tex-requirements: ${n} checks passed`);
+// ── 5. the parser's tolerances: an optional block left out, and Ajv's optional fields ───
+{
+  const bare = R.parsePreset(
+    '{ "extends": "paperlint:aisec" }',
+    "bare.jsonc",
+    VENUES,
+  );
+  check(
+    "a preset that only extends another: no tex block, `rules` an empty object",
+    JSON.stringify([bare.extends, bare.tex, bare.rules]) ===
+      '["paperlint:aisec",null,{}]',
+    bare,
+  );
+  // Guards: `packages` is read without a fallback because the schema refuses a tex block
+  // without it — this is the refusal the type relies on.
+  check(
+    "a tex block without `packages` is refused by the schema, before anything reads it",
+    /tex\.jsonc: \.tex should have required property 'packages'/.test(
+      throws(() => R.parsePreset('{ "tex": {} }', "tex.jsonc", VENUES)),
+    ),
+    throws(() => R.parsePreset('{ "tex": {} }', "tex.jsonc", VENUES)),
+  );
+  check(
+    "violations: Ajv's null `errors` is no violation; a message Ajv left out is an empty one",
+    R.violations("f.jsonc", { errors: null }).length === 0 &&
+      R.violations("f.jsonc", {
+        errors: [{ dataPath: "", message: undefined }],
+      })[0] === "f.jsonc: (top level) ",
+  );
+}
+
+console.log(`tex-requirements: ${check.count} checks passed`);

package/src/tex-requirements.ts

@@ -72,8 +72,14 @@ function validatorFor(dir: string): Validate {
   return v;
 }
 
-/** Every violation as `<file>: <path> <message>` — one line each, so all of them are fixed at once. */
-function violations(file: string, v: Validate): string[] {
+/**
+ * Every violation as `<file>: <path> <message>` — one line each, so all of them are fixed at once.
+ * Ajv types `errors` as possibly null and a message as optional; both are tolerated, not assumed.
+ */
+export function violations(
+  file: string,
+  v: Pick<Validate, "errors">,
+): string[] {
   return (v.errors ?? []).map(
     (e) => `${file}: ${e.dataPath || "(top level)"} ${e.message ?? ""}`,
   );
@@ -158,7 +164,9 @@ interface PresetJson {
   readonly extends?: string;
   readonly name?: string;
   readonly template?: string;
-  readonly tex?: Partial<TexRequirements>;
+  /** The schema requires `packages` in a `tex` block; `tools` is optional. */
+  readonly tex?: Pick<TexRequirements, "packages"> &
+    Partial<Pick<TexRequirements, "tools">>;
   readonly format?: FormatJson;
   readonly rules?: Readonly<Record<string, unknown>>;
 }
@@ -221,9 +229,7 @@ export function parsePreset(
     extends: orNull(j.extends),
     name: orNull(j.name),
     template: orNull(j.template),
-    tex: j.tex
-      ? { packages: j.tex.packages ?? {}, tools: j.tex.tools ?? {} }
-      : null,
+    tex: j.tex ? { packages: j.tex.packages, tools: j.tex.tools ?? {} } : null,
     format: formatOf(j.format),
     rules: j.rules ?? {},
   };

package/src/toolchain.harness.mjs

@@ -16,7 +16,6 @@
  *   4. banal, the command's second half: a stand-in banal served from `file://`, never HotCRP —
  *      the installer's own tests are `banal.harness.mjs`; here only the wiring into the command.
  */
-import assert from "node:assert/strict";
 import { spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import {
@@ -33,6 +32,7 @@ import {
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import { createChecker } from "../lib/check.mjs";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const FIXTURE = join(HERE, "..", "fixtures", "toolchain-mirror");
@@ -43,11 +43,7 @@ const B = await import(join(HERE, "adapters", "banal", "index.ts"));
 const N = await import(join(HERE, "adapters", "node", "index.ts"));
 const C = await import(join(HERE, "adapters", "curl", "index.ts"));
 
-let n = 0;
-const check = (label, cond, detail = "") => {
-  assert.ok(cond, `${label}${detail ? ` — ${detail}` : ""}`);
-  n++;
-};
+const check = createChecker();
 
 // ── 1. pure pieces ──────────────────────────────────────────────────────────────────────
 check(
@@ -692,4 +688,4 @@ check(
 }
 
 rmSync(work, { recursive: true, force: true });
-console.log(`toolchain: ${n} checks passed`);
+console.log(`toolchain: ${check.count} checks passed`);

package/src/toolchain.test.ts

@@ -0,0 +1,280 @@
+/**
+ * toolchain.ts edges the harness (a fixture mirror) does not reach, with a scripted runner: curl
+ * that fails with and without output, a mirror serving something that is not a tarball, an archive
+ * without install-tl or without its release file, install-tl that cannot start, tlmgr with nothing
+ * to install; and the pure readers on inputs their happy paths never see.
+ */
+import assert from "node:assert/strict";
+import { chmodSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { join } from "node:path";
+import { test } from "vitest";
+import { useTempDir, writeTree } from "../test/support.mjs";
+import {
+  cachedTrees,
+  CACHE_ENV,
+  describeGaps,
+  downloadInstaller,
+  ensureTexLive,
+  installBase,
+  installPackages,
+  releaseGap,
+  runToolchain,
+  tlYear,
+  UNSUPPORTED,
+  type ToolchainIO,
+} from "./toolchain.ts";
+
+const root = useTempDir("paperlint-toolchain-test-");
+type Answer = {
+  status: number | null;
+  stdout?: string;
+  stderr?: string;
+  error?: Error;
+};
+/** A runner answering by program name (the last path segment); `onRun` may write files first. */
+function io(
+  answers: Record<string, (args: string[]) => Answer>,
+): ToolchainIO & { lines: string[] } {
+  const lines: string[] = [];
+  return {
+    lines,
+    log: (l) => lines.push(l),
+    env: {},
+    run: ((cmd: string, args: string[]) => {
+      const name = cmd.split("/").pop() ?? cmd;
+      const answer = answers[`${name} ${args[0] ?? ""}`] ?? answers[name];
+      if (!answer) throw new Error(`unexpected ${name} ${args.join(" ")}`);
+      return answer(args);
+    }) as never,
+  };
+}
+const ok = (stdout = ""): Answer => ({ status: 0, stdout, stderr: "" });
+
+test("pure readers: a release file with no year, a `local:` line with no year, a gap with no proof file", () => {
+  assert.equal(tlYear(""), null);
+  assert.equal(releaseGap("local: soon\nrepository: 2026"), null);
+  assert.equal(
+    describeGaps(
+      { packages: ["acmart"], tools: [], dependencies: [] },
+      { packages: {}, tools: {} },
+    ),
+    "acmart ()",
+  );
+});
+
+test("the cache: a year whose bin directory holds no runnable pdflatex is not a tree", () => {
+  const cache = join(root, "cache");
+  mkdirSync(join(cache, "2025", "bin", "x86_64-linux"), { recursive: true });
+  writeFileSync(join(cache, "2025", "bin", "x86_64-linux", "pdflatex"), "");
+  mkdirSync(join(cache, "2026", "bin", "x86_64-linux"), { recursive: true });
+  const exe = join(cache, "2026", "bin", "x86_64-linux", "pdflatex");
+  writeFileSync(exe, "#!/bin/sh\n");
+  chmodSync(exe, 0o755);
+  assert.deepEqual(
+    cachedTrees(cache).map((t) => t.year),
+    ["2026"],
+  );
+});
+
+test("download: curl failing with its own line, with only an error, with only a code; then a non-tarball", () => {
+  const t = io({
+    curl: (args) => {
+      const url = args[args.length - 1] ?? "";
+      if (url.startsWith("m1"))
+        return { status: 22, stdout: "", stderr: "curl: (22) 404\n" };
+      if (url.startsWith("m2"))
+        return { status: null, error: new Error("spawn curl ENOENT") };
+      if (url.startsWith("m3")) return { status: 7 };
+      return ok();
+    },
+    "tar tzf": () => ({ status: 2 }),
+  });
+  assert.equal(
+    downloadInstaller(t, ["m1", "m2", "m3", "m4"], join(root, "x.tgz")),
+    null,
+  );
+  assert.deepEqual(t.lines, [
+    "  ⚠ m1/install-tl-unx.tar.gz: curl: (22) 404",
+    "  ⚠ m2/install-tl-unx.tar.gz: spawn curl ENOENT",
+    "  ⚠ m3/install-tl-unx.tar.gz: curl exited 7",
+    "  ⚠ m4/install-tl-unx.tar.gz returned something that is not a .tar.gz — trying the next mirror",
+  ]);
+});
+
+/** A runner whose download succeeds and whose `tar xzf` lays out `files` in the work directory. */
+const unpacking = (
+  files: Record<string, string> | null,
+  more: Record<string, (args: string[]) => Answer> = {},
+) =>
+  io({
+    curl: () => ok(),
+    "tar tzf": () => ok(),
+    "tar xzf": (args) => {
+      if (files === null) return { status: 2 };
+      writeTree(args[args.length - 1] ?? "", files);
+      return ok();
+    },
+    ...more,
+  });
+
+test("install: an archive that does not unpack, holds no install-tl, or no release file", () => {
+  const bad = [
+    unpacking(null),
+    unpacking({ "other/x": "" }),
+    unpacking({ "install-tl-20260101/install-tl": "" }),
+  ].map((t) => installBase(t, join(root, "tl"), ["m"]));
+  for (const r of bad)
+    assert.deepEqual(r, {
+      ok: false,
+      lines: [
+        "the archive from m does not hold an install-tl with a release-texlive.txt",
+      ],
+    });
+});
+
+test("install: install-tl that cannot start names the error and its last lines", () => {
+  const t = unpacking(
+    {
+      "install-tl-20260101/install-tl": "",
+      "install-tl-20260101/release-texlive.txt":
+        "TeX Live (https://tug.org/texlive) version 2026\n",
+    },
+    {
+      "install-tl": () => ({ status: null, error: new Error("spawn EACCES") }),
+    },
+  );
+  assert.deepEqual(installBase(t, join(root, "tl2"), ["m"]), {
+    ok: false,
+    lines: ["install-tl failed (spawn EACCES) — its last lines:"],
+  });
+});
+
+test("tlmgr: nothing missing, nothing installed", () => {
+  const t = io({ kpsewhich: () => ok(), tlmgr: () => ok() });
+  const tree = { dir: "/t/2026", year: "2026", bin: "/t/2026/bin/x" };
+  assert.deepEqual(
+    installPackages(t, tree, { packages: {}, tools: {} }, ["m"]),
+    {
+      ok: true,
+      value: { gaps: { packages: [], tools: [], dependencies: [] }, tail: [] },
+    },
+  );
+});
+
+test("tlmgr: a run that prints nothing still leaves the gap to verify", () => {
+  let kpse = 0;
+  const t = io({
+    kpsewhich: () => ok(kpse++ ? "/t/acmart.cls\n" : ""),
+    "tlmgr check": () => ok(),
+    "tlmgr --repository": () => ({ status: 0 }),
+  });
+  const tree = { dir: "/t/2026", year: "2026", bin: "/t/2026/bin/x" };
+  const r = installPackages(
+    t,
+    tree,
+    { packages: { acmart: ["acmart.cls"] }, tools: {} },
+    ["m"],
+  );
+  assert.deepEqual(r, {
+    ok: true,
+    value: { gaps: { packages: [], tools: [], dependencies: [] }, tail: [] },
+  });
+});
+
+/** A cache holding one tree for `year` with a runnable pdflatex; returns the cache root. */
+function cacheWith(name: string, year: string): string {
+  const cache = join(root, name);
+  const exe = join(cache, year, "bin", "x86_64-linux", "pdflatex");
+  mkdirSync(dirname(exe), { recursive: true });
+  writeFileSync(exe, "#!/bin/sh\n");
+  chmodSync(exe, 0o755);
+  return cache;
+}
+const ACMART = { packages: { acmart: ["acmart.cls"] }, tools: {} };
+function ensure(
+  cache: string,
+  answers: Record<string, (args: string[]) => Answer>,
+) {
+  const t = io(answers);
+  const errs: string[] = [];
+  const r = ensureTexLive(ACMART, {
+    run: t.run,
+    log: t.log,
+    err: (l) => errs.push(l),
+    env: { [CACHE_ENV]: cache },
+    home: root,
+    now: () => 0,
+  });
+  return { r, errs };
+}
+
+test("ensure: tlmgr leaves the package missing — the verdict quotes tlmgr's last lines", () => {
+  const cache = cacheWith("lacks", "2026");
+  const { r, errs } = ensure(cache, {
+    kpsewhich: () => ok(),
+    "tlmgr check": () => ok(),
+    "tlmgr --repository": () =>
+      ok("tlmgr: package acmart installed, but nothing changed\n"),
+  });
+  assert.deepEqual(
+    [r, errs.slice(-2)],
+    [
+      { ok: false },
+      [
+        "    tlmgr's last lines:",
+        "    tlmgr: package acmart installed, but nothing changed",
+      ],
+    ],
+  );
+});
+
+test("ensure: tlmgr refuses across releases, the new tree is installed, and tlmgr still refuses", () => {
+  const cache = cacheWith("newer", "2025");
+  const refusal = ok(
+    "tlmgr: Local TeX Live (2025) is older than remote repository (2026).\n",
+  );
+  const { r, errs } = ensure(cache, {
+    kpsewhich: () => ok(),
+    "tlmgr check": () => ok(),
+    "tlmgr --repository": () => refusal,
+    curl: () => ok(),
+    "tar tzf": () => ok(),
+    "tar xzf": (args) => {
+      writeTree(args[args.length - 1] ?? "", {
+        "install-tl-20260101/install-tl": "",
+        "install-tl-20260101/release-texlive.txt":
+          "TeX Live (https://tug.org/texlive) version 2026\n",
+      });
+      return ok();
+    },
+    "install-tl": () => {
+      const exe = join(cache, "2026", "bin", "x86_64-linux", "pdflatex");
+      mkdirSync(dirname(exe), { recursive: true });
+      writeFileSync(exe, "#!/bin/sh\n");
+      chmodSync(exe, 0o755);
+      return ok();
+    },
+  });
+  assert.deepEqual(
+    [r, errs],
+    [
+      { ok: false },
+      [
+        `✗ paperlint toolchain: tlmgr still refuses: the repository is TeX Live 2026 and the new tree in ${join(cache, "2026")} is 2025`,
+      ],
+    ],
+  );
+});
+
+test("runToolchain with only its installer: the console is the default output", () => {
+  const seen: unknown[] = [];
+  const saved = console.error;
+  console.error = (...a: unknown[]) => void seen.push(a.join(" "));
+  try {
+    assert.equal(runToolchain({ platform: "win32", banal: {} as never }), 1);
+  } finally {
+    console.error = saved;
+  }
+  assert.deepEqual(seen, [`✗ paperlint toolchain: ${UNSUPPORTED}`]);
+});

package/src/toolchain.ts

@@ -162,8 +162,8 @@ export function mirrorsFrom(env: NodeJS.ProcessEnv): readonly string[] {
 
 /** `release-texlive.txt`'s first line: "TeX Live (https://tug.org/texlive) version 2026". */
 export function tlYear(release: string): string | null {
-  const first = release.split("\n", 1)[0] ?? "";
-  return /\bversion (\d{4})\b/.exec(first)?.[1] ?? null;
+  // `^[^\n]*`: the first line only — a year on a later line is not the release.
+  return /^[^\n]*\bversion (\d{4})\b/.exec(release)?.[1] ?? null;
 }
 
 /** The install-tl profile: scheme-basic, no docs or sources, every tree variable inside `dir`. */
@@ -359,7 +359,9 @@ function unpack(io: ToolchainIO, archive: string, work: string): string | null {
   return dir ? join(work, dir) : null;
 }
 
-export type Step<T> = { ok: true; value: T } | { ok: false; lines: string[] };
+/** A failed step always says why: its first line is the headline, the rest detail. */
+export type Step<T> =
+  { ok: true; value: T } | { ok: false; lines: [string, ...string[]] };
 
 /** Download, unpack and run install-tl: a fresh scheme-basic tree in `<root>/<year>`. */
 export function installBase(
@@ -458,7 +460,7 @@ function runInstallTl(
  */
 export type AddStep =
   | { readonly ok: true; readonly value: { gaps: Gaps; tail: string[] } }
-  | { readonly ok: false; readonly lines: string[] }
+  | { readonly ok: false; readonly lines: [string, ...string[]] }
   | { readonly ok: false; readonly newer: ReleaseGap };
 
 export function installPackages(
@@ -654,10 +656,9 @@ export const binLine = (tree: CachedTree): string => `  bin: ${tree.bin}`;
 
 function fail(
   err: (line: string) => void,
-  lines: readonly string[],
+  [head, ...rest]: readonly [string, ...string[]],
 ): InstallResult {
-  const [head, ...rest] = lines;
-  err(`✗ paperlint toolchain: ${head ?? "failed"}`);
+  err(`✗ paperlint toolchain: ${head}`);
   for (const l of rest) err(`    ${l}`);
   return { ok: false };
 }

package/src/venue-rules.test.ts

@@ -113,6 +113,7 @@ function lint(
   p: Paper,
   filename = `${PAPER}/paper.tex`,
   options: Json = {},
+  cwd?: string,
 ): Finding[] {
   const files = memoryFiles(paperFiles(p));
   const rules = venueRules({ files, venuesDir: VENUES });
@@ -123,6 +124,7 @@ function lint(
   ][]) {
     const visitor = rule.create({
       filename,
+      ...(cwd === undefined ? {} : { cwd }),
       sourceCode: { text: TEX },
       options:
         name === "geometry" && Object.keys(options).length ? [options] : [],
@@ -555,3 +557,61 @@ describe("paperlint's own config turns the venue rules on for every paper.tex",
     expect(OPTIONAL_RULES.has("pdf/last-page-balance")).toBe(true);
   });
 });
+
+describe("a project's own preset, and the facts' other spellings", () => {
+  // A standalone preset (no `extends`, so it carries a `tex` block) that sets a body size with no
+  // tolerance, a reference range, two columns — and no page size and no font families.
+  const HOUSE = {
+    [`${PAPER}/house.jsonc`]: JSON.stringify({
+      tex: { packages: { acmart: ["acmart.cls"] } },
+      format: { columns: 2, body_pt: 9, ref_pt_min: 7, ref_pt_max: 8 },
+    }),
+  };
+  const house = (patch: (f: Json) => void = () => {}) =>
+    lint({
+      venue: { extends: "./house.jsonc" },
+      facts: withFacts(patch),
+      extra: HOUSE,
+    });
+
+  it("no page size in the preset: nothing to compare, whatever the PDF measures", () => {
+    expect(ids(house((f) => ((f.page_w_in = 5), (f.page_h_in = 5))))).toEqual(
+      [],
+    );
+  });
+
+  it("a body size with no tolerance is not judged; a reference range with none is judged exactly", () => {
+    expect(ids(house((f) => (f.body_pt = 12)))).toEqual([]);
+    // 6.9 pt passes agenticdev (its body_pt_tol widens the range) and fails here, where nothing does.
+    expect(ids(house((f) => (f.ref_pt = 6.9)))).toEqual(["pdf/limits:refPt"]);
+  });
+
+  it("facts naming the PDF by an absolute path are checked against that file", () => {
+    expect(
+      lint({
+        venue: DECL,
+        facts: withFacts((f) => (f.pdf = `${PAPER}/paper.pdf`)),
+      }),
+    ).toEqual([]);
+  });
+
+  it("a PDF with no fonts at all: each missing family says so", () => {
+    const fs = lint({ venue: DECL, facts: withFacts((f) => (f.fonts = [])) });
+    expect(ids(fs)).toEqual(["pdf/fonts:noFamily", "pdf/fonts:noFamily"]);
+    expect(fs[0]?.message).toMatch(/\(no fonts\)/);
+  });
+
+  it("file names in messages are relative to ESLint's cwd — and never empty", () => {
+    const at = (cwd: string) =>
+      lint(
+        { venue: { kind: "short" }, facts: null, pdf: null },
+        undefined,
+        {},
+        cwd,
+      )[0]?.message;
+    expect(at("/work")).toMatch(/set "extends" in papers\/p\/paperlint\.json/);
+    expect(at(`${PAPER}/paperlint.json`)).toMatch(
+      /set "extends" in \/work\/papers\/p\/paperlint\.json/,
+    );
+  });
+});

package/src/venue-rules.ts

@@ -253,17 +253,19 @@ function judgePages(g: FlatGeometry, resolved: Resolved): Finding[] {
     [kind.limits.bodyPagesMax, g.body_pages, "body pages"],
     [kind.limits.refPagesMax, g.ref_pages, "reference pages"],
   ];
-  return pages
-    .filter(([max, got]) => max !== null && got > max)
-    .map(([max, got, what]) =>
-      finding("pages", {
-        what,
-        got,
-        max: max ?? 0,
-        venue: resolved.venue,
-        kind: kind.name,
-      }),
-    );
+  return pages.flatMap(([max, got, what]) =>
+    max !== null && got > max
+      ? [
+          finding("pages", {
+            what,
+            got,
+            max,
+            venue: resolved.venue,
+            kind: kind.name,
+          }),
+        ]
+      : [],
+  );
 }
 
 function judgeRefPt(g: FlatGeometry, resolved: Resolved): Finding[] {