paperlint 2.0.0

package/src/adapters/node/workspace.test.ts

@@ -0,0 +1,58 @@
+/**
+ * The `Workspace` contract against a real temp directory: the directory exists inside the scope and
+ * is gone after it, whether the scope returned or threw; `write` puts a file in it, runnable when
+ * asked. What banal stages through it is `src/adapters/banal/invocation.test.ts`.
+ */
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  realpathSync,
+  rmSync,
+  statSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll as after, test } from "vitest";
+import { tmpWorkspace } from "./workspace.io.ts";
+
+const root = realpathSync(mkdtempSync(join(tmpdir(), "rpp-ws-test-")));
+after(() => rmSync(root, { recursive: true, force: true }));
+
+test("the directory exists inside the scope and is gone after it", () => {
+  const ws = tmpWorkspace(root);
+  const dir = ws.within("rpp-banal-", (s) => {
+    assert.ok(existsSync(s.dir));
+    return s.dir;
+  });
+  // Guards: cleanup — a paper's text must not pile up in the temp directory, one copy per build.
+  assert.equal(existsSync(dir), false);
+});
+
+test("the directory is gone after a throw too", () => {
+  let seen = "";
+  assert.throws(() =>
+    tmpWorkspace(root).within("rpp-banal-", (s) => {
+      seen = s.dir;
+      throw new Error("boom");
+    }),
+  );
+  assert.equal(existsSync(seen), false);
+});
+
+test("🔴 write: the file lands in the scope's directory, and `exec` makes it runnable — from a path with a space and a quote", () => {
+  const awkward = join(root, "it's a dir");
+  mkdirSync(awkward);
+  tmpWorkspace(awkward).within("rpp-ws-", (s) => {
+    const plain = s.write("data.txt", "hello", "read");
+    assert.equal(readFileSync(plain, "utf8"), "hello");
+    const script = s.write("run", "#!/bin/sh\necho ran\n", "exec");
+    // Guards: the exec bit — banal runs the staged stub as a program, and a 0644 file is refused.
+    const r = spawnSync(script, [], { encoding: "utf8" });
+    assert.equal(r.stdout, "ran\n");
+    assert.equal(statSync(plain).mode & 0o111, 0);
+  });
+});

package/src/adapters/pdfjs/fill.test.ts

@@ -0,0 +1,111 @@
+/**
+ * `fill.ts` — what is recovered from pdf.js's exports for each text item: whether it is upright, and
+ * the fill it was drawn in (the operator-list walk). Operator lists here are written by hand; the
+ * real-PDF half runs in `pdf-facts.harness.mjs` and `test/e2e/banal.mjs`.
+ */
+import assert from "node:assert/strict";
+import { test } from "vitest";
+import { isDeepStrictEqual } from "node:util";
+import * as L from "./fill.ts";
+import type { OperatorList } from "./fill.ts";
+
+/** One vitest case per assertion, named by its label. */
+const check = (label: string, cond: unknown, detail = "") => {
+  test(label, () => {
+    assert.ok(cond, detail ? `${label} — ${detail}` : label);
+  });
+};
+
+// ── upright ─────────────────────────────────────────────────────────────────────────────
+check("isUpright: the identity scaled", L.isUpright([10, 0, 0, 10, 5, 5]));
+check(
+  "isUpright: mirrored vertically is still upright",
+  L.isUpright([10, 0, 0, -10, 5, 5]),
+);
+check("isUpright: rotated 90° is not", !L.isUpright([0, 10, -10, 0, 5, 5]));
+check("isUpright: skewed is not", !L.isUpright([10, 0, 3, 10, 5, 5]));
+
+// ── the fill walk ───────────────────────────────────────────────────────────────────────
+const OPS = {
+  save: 1,
+  restore: 2,
+  setFillRGBColor: 3,
+  setTextRenderingMode: 4,
+  showText: 5,
+  showSpacedText: 6,
+};
+const glyphs = (s: string) => [[...s].map((unicode) => ({ unicode }))];
+const ops = (...pairs: [number, unknown?][]): OperatorList => ({
+  fnArray: pairs.map((p) => p[0]),
+  argsArray: pairs.map((p) => p[1] ?? null),
+});
+
+check(
+  "hexOf: current pdf.js passes a hex string",
+  L.hexOf(["#E5E5E5"]) === "#e5e5e5",
+);
+check(
+  "hexOf: older pdf.js passes three numbers",
+  L.hexOf([229, 229, 229]) === "#e5e5e5",
+);
+{
+  const list = ops(
+    [OPS.save],
+    [OPS.setFillRGBColor, ["#f5f5f5"]],
+    [OPS.showText, glyphs("Light text")],
+    [OPS.restore],
+    [OPS.showText, glyphs("Dark")],
+    [OPS.setTextRenderingMode, [3]],
+    [OPS.showSpacedText, [[{ unicode: "O" }, -250, { unicode: "CR" }]]],
+    [OPS.setTextRenderingMode, [0]],
+    [OPS.showText, glyphs("After")],
+  );
+  const fills = L.fillsOf(OPS, list, ["Light text", "Dark", "OCR", "After"]);
+  // Guards: save/restore — the colour set inside a group ends with it; the next item is not light.
+  check(
+    "fillsOf: a colour set inside save/restore ends at restore",
+    isDeepStrictEqual(fills.slice(0, 2), [
+      { kind: "rgb", hex: "#f5f5f5" },
+      { kind: "unknown" },
+    ]),
+    JSON.stringify(fills),
+  );
+  // Guards: render mode 3 is invisible, and the mode is state, not a property of one operator.
+  check(
+    "fillsOf: render mode 3 is invisible, and mode 0 ends it",
+    fills[2]?.kind === "invisible" && fills[3]?.kind === "unknown",
+    JSON.stringify(fills),
+  );
+}
+{
+  const list = ops(
+    [OPS.setFillRGBColor, ["#ff0000"]],
+    [OPS.showText, glyphs("Hel")],
+    [OPS.showText, glyphs("lo world")],
+  );
+  check(
+    "fillsOf: an item drawn by two operators, and spaces that items and glyphs split differently",
+    L.fillsOf(OPS, list, ["Hello", "world"]).every(
+      (f) => f.kind === "rgb" && f.hex === "#ff0000",
+    ),
+  );
+}
+{
+  const list = ops(
+    [OPS.setFillRGBColor, ["#eeeeee"]],
+    [OPS.showText, glyphs("first")],
+    [OPS.showText, glyphs("second")],
+  );
+  const fills = L.fillsOf(OPS, list, ["nowhere", "second"]);
+  // Guards: the direction of a miss — an item that cannot be found is drawn as black (kept), and
+  // the walk does not lose its place for the items after it.
+  check(
+    "fillsOf: an unmatched item is `unknown` (kept, never dropped), and the next one still matches",
+    fills[0]?.kind === "unknown" && fills[1]?.kind === "rgb",
+    JSON.stringify(fills),
+  );
+}
+check(
+  "fillsOf: an empty item is `unknown`",
+  L.fillsOf(OPS, ops(), [" "])[0]?.kind === "unknown",
+);

package/src/adapters/pdfjs/fill.ts

@@ -0,0 +1,141 @@
+/**
+ * pdf.js's half of the page layout — PURE. pdf.js's text content carries no colour and no
+ * orientation flag, so two facts about each text item are recovered from what pdf.js exports:
+ * whether its transform draws it upright, and which fill its characters were drawn with (walked
+ * from the operator list). `pdf-facts.ts` reads the PDF and calls these; the result is the domain's
+ * `PageLayout` (`domain/page-layout.ts`). Split out of the banal XML writer (#75): this is what
+ * would change if pdf.js did — not banal.
+ */
+import type { Fill } from "../../domain/page-layout.ts";
+
+/** A transform `[a, b, c, d, e, f]` that draws text upright: no rotation and no skew. */
+export function isUpright(m: readonly number[]): boolean {
+  const eps = 1e-6;
+  return Math.abs(m[1] ?? 0) < eps && Math.abs(m[2] ?? 0) < eps;
+}
+
+/** The operator codes the colour walk reads — pdf.js's `OPS`, reduced to what is used. */
+export interface ColourOps {
+  readonly save: number;
+  readonly restore: number;
+  readonly setFillRGBColor: number;
+  readonly setTextRenderingMode: number;
+  readonly showText: number;
+  readonly showSpacedText: number;
+}
+
+/** pdf.js's operator list: parallel arrays of operator codes and their arguments. */
+export interface OperatorList {
+  readonly fnArray: readonly number[];
+  readonly argsArray: readonly unknown[];
+}
+
+/** Text as the walk compares it: normalised, with no whitespace (items and glyphs split spaces differently). */
+const squeeze = (s: string): string => s.normalize("NFKC").replace(/\s+/g, "");
+
+/** `setFillRGBColor`'s argument: a `#rrggbb` string in current pdf.js, three 0-255 numbers in older ones. */
+export function hexOf(args: unknown): string {
+  const a = Array.isArray(args) ? (args as unknown[]) : [];
+  if (typeof a[0] === "string") return a[0].toLowerCase();
+  const byte = (v: unknown): string =>
+    Math.round(typeof v === "number" ? v : 0)
+      .toString(16)
+      .padStart(2, "0");
+  return `#${byte(a[0])}${byte(a[1])}${byte(a[2])}`;
+}
+
+/** The characters a show-text operator draws, from its glyph objects. */
+function glyphText(args: unknown): string {
+  const a = Array.isArray(args) ? (args as unknown[]) : [];
+  const glyphs = Array.isArray(a[0]) ? (a[0] as unknown[]) : [];
+  return glyphs
+    .map((g) =>
+      typeof g === "object" && g !== null && "unicode" in g
+        ? String((g as { unicode: unknown }).unicode ?? "")
+        : "",
+    )
+    .join("");
+}
+
+/** The graphics state the walk tracks. */
+interface State {
+  fill: Fill;
+  mode: number;
+}
+
+/** Apply one state operator; false when `fn` is not one. */
+function applyState(
+  ops: ColourOps,
+  fn: number,
+  args: unknown,
+  s: { cur: State; stack: State[] },
+): boolean {
+  if (fn === ops.save) s.stack.push({ ...s.cur });
+  else if (fn === ops.restore)
+    s.cur = s.stack.pop() ?? { fill: { kind: "unknown" }, mode: 0 };
+  else if (fn === ops.setFillRGBColor)
+    s.cur.fill = { kind: "rgb", hex: hexOf(args) };
+  else if (fn === ops.setTextRenderingMode)
+    s.cur.mode = Number((args as unknown[] | undefined)?.[0] ?? 0);
+  else return false;
+  return true;
+}
+
+/** Every drawn character, in content order, with the fill it was drawn in. */
+export function drawnCharacters(
+  ops: ColourOps,
+  list: OperatorList,
+): { chars: string[]; fills: Fill[] } {
+  const s = { cur: { fill: { kind: "unknown" } as Fill, mode: 0 }, stack: [] };
+  const chars: string[] = [];
+  const fills: Fill[] = [];
+  list.fnArray.forEach((fn, i) => {
+    const args = list.argsArray[i];
+    if (applyState(ops, fn, args, s)) return;
+    if (fn !== ops.showText && fn !== ops.showSpacedText) return;
+    const fill: Fill = s.cur.mode === 3 ? { kind: "invisible" } : s.cur.fill;
+    for (const ch of squeeze(glyphText(args))) {
+      chars.push(ch);
+      fills.push(fill);
+    }
+  });
+  return { chars, fills };
+}
+
+/** How far ahead the walk looks for an item it cannot find where it expects it. */
+export const LOOKAHEAD = 4000;
+
+/** The position at or after `from` where `want` starts in `chars`, or -1 within the look-ahead. */
+function findRun(
+  chars: readonly string[],
+  want: readonly string[],
+  from: number,
+): number {
+  const limit = Math.min(chars.length, from + LOOKAHEAD);
+  for (let q = from; q < limit; q++)
+    if (want.every((ch, k) => chars[q + k] === ch)) return q;
+  return -1;
+}
+
+/**
+ * The fill of each text item. pdf.js's text content carries no colour, so the operator list is
+ * walked for the characters each show-text operator draws, and the items — in the same content
+ * order — are matched against them. An item that cannot be matched gets `unknown` (drawn as black):
+ * a missed match can keep light text, never drop dark text.
+ */
+export function fillsOf(
+  ops: ColourOps,
+  list: OperatorList,
+  items: readonly string[],
+): Fill[] {
+  const { chars, fills } = drawnCharacters(ops, list);
+  let at = 0;
+  return items.map((text): Fill => {
+    const want = [...squeeze(text)];
+    if (want.length === 0) return { kind: "unknown" };
+    const q = findRun(chars, want, at);
+    if (q < 0) return { kind: "unknown" };
+    at = q + want.length;
+    return fills[q] ?? { kind: "unknown" };
+  });
+}

package/src/build-engine.harness.mjs

@@ -0,0 +1,314 @@
+/**
+ * `build-engine.ts` — `paperlint build`'s engine step: facts gathered from a cache on disk and a PATH,
+ * the decision acted on. The TeX Lives here are directories with a `pdflatex` file and a fake
+ * runner standing in for their `kpsewhich`; the question and the install are injected.
+ *
+ * Tables, in order:
+ *   1. the pure texts: the question, the refusal line, what counts as "yes";
+ *   2. prepareEngine: use the cache · use the system · refuse without a human · ask, decline,
+ *      accept and install · dry-run never asks or installs.
+ */
+import assert from "node:assert/strict";
+import {
+  chmodSync,
+  mkdirSync,
+  mkdtempSync,
+  realpathSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, delimiter, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const E = await import(join(HERE, "build-engine.ts"));
+
+let n = 0;
+const check = (label, cond, detail = "") => {
+  assert.ok(cond, `${label}${detail ? ` — ${detail}` : ""}`);
+  n++;
+};
+
+// ── 1. texts ────────────────────────────────────────────────────────────────────────────
+const noCache = {
+  supported: true,
+  cache: null,
+  system: null,
+  interactive: true,
+  required: ["acmart", "libertine"],
+};
+check(
+  "question: no TeX Live at all — size, time, and where it goes",
+  E.question(noCache, "/c") ===
+    "TeX Live is not installed (needed to compile paper.tex, ~230 MB, ~2 min). Install it now into /c? [Y/n] ",
+);
+check(
+  "question: a partial cache — only its gaps are offered",
+  E.question(
+    { ...noCache, cache: { label: "c", bin: "/c/b", missing: ["kastrup"] } },
+    "/c",
+  ) === "TeX Live in /c lacks 1 package(s): kastrup. Install them now? [Y/n] ",
+);
+const refused = E.refusal(
+  { kind: "refuse", reason: "not-installed", missing: ["acmart", "libertine"] },
+  {
+    ...noCache,
+    interactive: false,
+    system: { label: "s", bin: "/usr/bin", missing: ["cm-super"] },
+  },
+);
+// Guards: the one line a CI log shows — without `npx paperlint toolchain` in it, the reader does not know
+// the cure.
+check(
+  "refusal: ONE line naming `npx paperlint toolchain`, the missing packages, and why the system TeX was passed over",
+  !refused.includes("\n") &&
+    refused.includes("run `npx paperlint toolchain`") &&
+    refused.includes("missing: 2 package(s): acmart, libertine") &&
+    refused.includes("/usr/bin/pdflatex lacks: cm-super"),
+  refused,
+);
+check(
+  "refusal on an unsupported platform says so",
+  E.refusal(
+    { kind: "refuse", reason: "unsupported", missing: ["x"] },
+    noCache,
+  ).includes("Windows is not supported"),
+);
+for (const [a, yes] of [
+  // Guards: the default answer — [Y/n] promises that Enter installs.
+  ["", true],
+  ["y", true],
+  ["YES", true],
+  [" y ", true],
+  ["n", false],
+  ["no", false],
+  ["maybe", false],
+  [null, false],
+])
+  check(`isYes(${JSON.stringify(a)}) is ${yes}`, E.isYes(a) === yes);
+
+// ── 2. prepareEngine ────────────────────────────────────────────────────────────────────
+const work = realpathSync(mkdtempSync(join(tmpdir(), "rpp-engine-h-")));
+const TEX = {
+  packages: { acmart: ["acmart.cls"], libertine: ["libertine.sty"] },
+  tools: {},
+};
+const ALL = "/t/acmart.cls\n/t/libertine.sty\n";
+/**
+ * A TeX Live on disk: a bin directory with a RUNNABLE pdflatex file. The execute bit is load-bearing:
+ * a pdflatex that cannot be started is not a TeX Live (`isExecutable` in engine.ts).
+ */
+const texAt = (dir) => {
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, "pdflatex"), "");
+  chmodSync(join(dir, "pdflatex"), 0o755);
+  return dir;
+};
+const cacheBin = texAt(join(work, "cache", "2026", "bin", "x86_64-linux"));
+const sysBin = texAt(join(work, "usr", "bin"));
+const emptyBin = join(work, "nothing");
+mkdirSync(emptyBin);
+
+/** kpsewhich answers per tree: `found[bin]` is what it prints. */
+const fakeRun = (found) => (cmd) => ({
+  stdout: found[dirname(cmd)] ?? "",
+  status: 0,
+});
+const go = async (o) => {
+  const out = [];
+  const err = [];
+  const asked = [];
+  let installs = 0;
+  const r = await E.prepareEngine({
+    tex: TEX,
+    log: (l) => out.push(l),
+    err: (l) => err.push(l),
+    ask: async (q) => {
+      asked.push(q);
+      return o.answer ?? "";
+    },
+    install: () => {
+      installs++;
+      return o.onInstall ? o.onInstall() : { ok: false };
+    },
+    platform: "linux",
+    ...o,
+  });
+  return {
+    r,
+    out: out.join("\n"),
+    err: err.join("\n"),
+    asked,
+    installs: () => installs,
+  };
+};
+const envWith = (cacheRoot, path) => ({
+  RPP_TEXLIVE_DIR: cacheRoot,
+  PATH: path,
+});
+
+{
+  const x = await go({
+    env: envWith(join(work, "cache"), sysBin),
+    run: fakeRun({ [cacheBin]: ALL, [sysBin]: ALL }),
+  });
+  // Guards: the cache being USED — without its bin first on PATH, the build runs whatever pdflatex
+  // the machine has.
+  check(
+    "a complete cache: used, named, and PATH starts with its bin",
+    x.r.ok &&
+      x.out.includes("engine: TeX Live 2026 — paperlint cache") &&
+      x.r.env.PATH.split(delimiter)[0] === cacheBin,
+    `${x.out} ${JSON.stringify(x.r)}`,
+  );
+}
+{
+  // Two TeX Live years in the cache: a 2027 install that stopped after install-tl, and 2026.
+  const years = join(work, "years");
+  const old = texAt(join(years, "2026", "bin", "x86_64-linux"));
+  const cut = texAt(join(years, "2027", "bin", "x86_64-linux"));
+  const x = await go({
+    env: envWith(years, emptyBin),
+    run: fakeRun({ [old]: ALL, [cut]: "" }),
+  });
+  // Guards: the year choice — an interrupted new-year install must not stand in for a complete
+  // older one.
+  check(
+    "🔴 two years, the newer incomplete: the newest COMPLETE one builds",
+    x.r.ok &&
+      x.out.includes("engine: TeX Live 2026 — paperlint cache") &&
+      x.r.env.PATH.split(delimiter)[0] === old,
+    x.out,
+  );
+  const y = await go({
+    env: envWith(years, emptyBin),
+    run: fakeRun({ [old]: ALL, [cut]: ALL }),
+  });
+  check(
+    "two years, both complete: the newer one",
+    y.r.ok && y.r.env.PATH.split(delimiter)[0] === cut,
+    y.out,
+  );
+}
+{
+  const x = await go({
+    env: envWith(join(work, "cache"), sysBin),
+    run: fakeRun({ [cacheBin]: "/t/acmart.cls\n", [sysBin]: ALL }),
+  });
+  check(
+    "a partial cache, a complete system TeX: the system one, PATH untouched",
+    x.r.ok &&
+      x.out.includes(
+        `engine: TeX Live on PATH (${join(sysBin, "pdflatex")})`,
+      ) &&
+      x.r.env.PATH === sysBin,
+    x.out,
+  );
+}
+{
+  const x = await go({
+    env: envWith(join(work, "none"), `${emptyBin}${delimiter}${sysBin}`),
+    run: fakeRun({ [sysBin]: "/t/acmart.cls\n" }),
+    interactive: false,
+  });
+  // Guards: refusing without a terminal — CI and agents would otherwise block on a question nobody
+  // can answer.
+  check(
+    "🔴 no human, nothing qualifies: refused in one line, NOTHING asked, NOTHING installed",
+    !x.r.ok &&
+      x.r.code === 1 &&
+      x.err.includes("npx paperlint toolchain") &&
+      x.err.includes("libertine") &&
+      x.asked.length === 0 &&
+      x.installs() === 0,
+    x.err,
+  );
+}
+{
+  const x = await go({
+    env: envWith(join(work, "none"), emptyBin),
+    run: fakeRun({}),
+    interactive: true,
+    answer: "n",
+  });
+  check(
+    "a terminal, declined: asked ONCE, nothing installed, refusal printed",
+    !x.r.ok &&
+      x.asked.length === 1 &&
+      x.installs() === 0 &&
+      x.err.includes("npx paperlint toolchain"),
+    JSON.stringify(x),
+  );
+}
+{
+  const x = await go({
+    env: envWith(join(work, "none"), emptyBin),
+    run: fakeRun({}),
+    interactive: true,
+    ask: async () => {
+      throw new Error("Aborted with Ctrl+D");
+    },
+  });
+  check(
+    "a question that cannot be answered (Ctrl+D) is a no, not a crash",
+    !x.r.ok && x.installs() === 0,
+  );
+}
+// The accept path needs the fake kpsewhich to answer for a tree that appears DURING the run.
+const x_run = { found: {} };
+{
+  const fresh = join(work, "fresh2");
+  const x = await go({
+    env: envWith(fresh, emptyBin),
+    run: (cmd) => ({ stdout: x_run.found[dirname(cmd)] ?? "", status: 0 }),
+    interactive: true,
+    answer: "",
+    onInstall: () => {
+      const bin = texAt(join(fresh, "2026", "bin", "x86_64-linux"));
+      x_run.found[bin] = ALL;
+      return {
+        ok: true,
+        tree: { dir: dirname(dirname(bin)), year: "2026", bin },
+      };
+    },
+  });
+  check(
+    "a terminal, Enter (default yes): installs once, then builds with the cache",
+    x.r.ok &&
+      x.installs() === 1 &&
+      x.out.includes("engine: TeX Live 2026 — paperlint cache") &&
+      basename(x.r.env.PATH.split(delimiter)[0]) === "x86_64-linux",
+    `${x.out}\n${x.err}`,
+  );
+}
+{
+  const x = await go({
+    env: envWith(join(work, "none"), emptyBin),
+    run: fakeRun({}),
+    interactive: true,
+    answer: "y",
+    onInstall: () => ({ ok: false }),
+  });
+  check("an install that fails stops the build", !x.r.ok && x.installs() === 1);
+}
+{
+  const x = await go({
+    env: envWith(join(work, "none"), emptyBin),
+    run: fakeRun({}),
+    interactive: true,
+    dryRun: true,
+  });
+  // Guards: --dry-run as a plan without side effects.
+  check(
+    "--dry-run: prints what would stop the build, never asks, never installs",
+    x.r.ok &&
+      x.asked.length === 0 &&
+      x.installs() === 0 &&
+      x.out.includes("engine: none — a real run would stop here"),
+    x.out,
+  );
+}
+
+rmSync(work, { recursive: true, force: true });
+console.log(`build-engine: ${n} checks passed`);