paperlint 2.0.0

package/src/engine.harness.mjs

@@ -0,0 +1,252 @@
+/**
+ * `engine.ts` — which TeX Live `paperlint build` compiles with.
+ *
+ * Tables, in order:
+ *   1. `resolveEngine` over `EngineFacts` — one row per branch of the order;
+ *   2. the fact readers: `missingPackages` over kpsewhich output, `missingTools`, `whichOnPath`,
+ *      `probeTree` through a fake runner.
+ * All pure or port-driven: no TeX needed. The real-TeX half is `test/e2e/build.mjs`.
+ */
+import assert from "node:assert/strict";
+import {
+  chmodSync,
+  mkdirSync,
+  mkdtempSync,
+  realpathSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const {
+  resolveEngine,
+  missingPackages,
+  missingTools,
+  whichOnPath,
+  isExecutable,
+  probeTree,
+  supportedPlatform,
+} = await import(join(HERE, "engine.ts"));
+
+let n = 0;
+const check = (label, cond, detail = "") => {
+  assert.ok(cond, `${label}${detail ? ` — ${detail}` : ""}`);
+  n++;
+};
+
+// ── 1. resolveEngine ────────────────────────────────────────────────────────────────────
+const tree = (label, missing = []) => ({ label, bin: `/${label}`, missing });
+const COMPLETE_CACHE = tree("cache");
+const PARTIAL_CACHE = tree("cache", ["kastrup"]);
+const COMPLETE_SYS = tree("sys");
+const PARTIAL_SYS = tree("sys", ["cm-super", "libertine"]);
+const REQUIRED = ["acmart", "cm-super", "kastrup", "libertine"];
+const facts = (o) => ({
+  supported: true,
+  cache: null,
+  system: null,
+  interactive: false,
+  required: REQUIRED,
+  ...o,
+});
+const ROWS = [
+  // Guards: the order — rpp's own verified cache first, so a build does not depend on whatever TeX
+  // Live the machine happens to carry.
+  [
+    "a complete cache wins, even over a complete system TeX",
+    facts({ cache: COMPLETE_CACHE, system: COMPLETE_SYS }),
+    { kind: "use-cache", tree: COMPLETE_CACHE },
+  ],
+  [
+    "a partial cache yields to a complete system TeX",
+    facts({ cache: PARTIAL_CACHE, system: COMPLETE_SYS }),
+    { kind: "use-system", tree: COMPLETE_SYS },
+  ],
+  [
+    "no cache, a complete system TeX is used",
+    facts({ system: COMPLETE_SYS }),
+    { kind: "use-system", tree: COMPLETE_SYS },
+  ],
+  // Guards: the whole point of #26 — a TeX Live without libertine would build an acmart paper
+  // GREEN, in Computer Modern.
+  [
+    "🔴 a system TeX that LACKS a declared package is NOT used — not even non-interactively",
+    facts({ system: PARTIAL_SYS }),
+    { kind: "refuse", reason: "not-installed", missing: REQUIRED },
+  ],
+  [
+    "nothing qualifies, a terminal: ask, for everything",
+    facts({ interactive: true, system: PARTIAL_SYS }),
+    { kind: "ask", missing: REQUIRED },
+  ],
+  // Guards: installing only what the cache lacks — a partial cache must not be offered a full
+  // reinstall.
+  [
+    "nothing qualifies, a terminal, a partial cache: ask for the cache's gaps only",
+    facts({ interactive: true, cache: PARTIAL_CACHE }),
+    { kind: "ask", missing: ["kastrup"] },
+  ],
+  [
+    "nothing qualifies, no terminal: refuse (never a silent install)",
+    facts({}),
+    { kind: "refuse", reason: "not-installed", missing: REQUIRED },
+  ],
+  [
+    "unsupported platform, nothing qualifies: refuse as unsupported, even on a terminal",
+    facts({ supported: false, interactive: true }),
+    { kind: "refuse", reason: "unsupported", missing: REQUIRED },
+  ],
+  [
+    "unsupported platform, a complete system TeX: used",
+    facts({ supported: false, system: COMPLETE_SYS }),
+    { kind: "use-system", tree: COMPLETE_SYS },
+  ],
+];
+for (const [label, f, want] of ROWS) {
+  const got = resolveEngine(f);
+  check(
+    `resolveEngine: ${label}`,
+    JSON.stringify(got) === JSON.stringify(want),
+    JSON.stringify(got),
+  );
+}
+check(
+  "supportedPlatform: linux and darwin, not win32",
+  supportedPlatform("linux") &&
+    supportedPlatform("darwin") &&
+    !supportedPlatform("win32"),
+);
+
+// ── 2. the fact readers ─────────────────────────────────────────────────────────────────
+const PKGS = {
+  acmart: ["acmart.cls"],
+  latex: ["latex.ltx", "article.cls"],
+  libertine: ["libertine.sty"],
+};
+check(
+  "missingPackages: matched by FILE NAME of each printed path, sorted",
+  JSON.stringify(missingPackages(PKGS, "/t/tex/latex/acmart/acmart.cls\n")) ===
+    '["latex","libertine"]',
+);
+// Guards: a package counts as present only when EVERY file that proves it resolves.
+check(
+  "missingPackages: one proof of two missing is enough to count the package missing",
+  missingPackages(
+    { latex: ["latex.ltx", "article.cls"] },
+    "/t/latex.ltx\n",
+  ).includes("latex"),
+);
+check(
+  "missingPackages: all present → none",
+  missingPackages(
+    PKGS,
+    "/a/acmart.cls\n/b/latex.ltx\n/b/article.cls\n/c/libertine.sty\n",
+  ).length === 0,
+);
+check(
+  "missingTools: by executable in the bin directory",
+  JSON.stringify(
+    missingTools(
+      { texcount: ["texcount"], checkcites: ["checkcites"] },
+      "/bin",
+      (p) => p === "/bin/texcount",
+    ),
+  ) === '["checkcites"]',
+);
+check(
+  "whichOnPath: the first directory that has it; empty segments skipped",
+  whichOnPath("pdflatex", ":/a:/b:/c", (p) =>
+    ["/b/pdflatex", "/c/pdflatex"].includes(p),
+  ) === "/b",
+);
+check(
+  "whichOnPath: nowhere → null",
+  whichOnPath("pdflatex", "/a:/b", () => false) === null,
+);
+{
+  const calls = [];
+  const run = (cmd, args) => {
+    calls.push([cmd, args]);
+    return { stdout: "/x/acmart.cls\n", status: 1 };
+  };
+  const missing = probeTree("/tl/bin", PKGS, run);
+  check(
+    "probeTree: runs THAT tree's kpsewhich, once, with every proof file once",
+    calls.length === 1 &&
+      calls[0][0] === "/tl/bin/kpsewhich" &&
+      calls[0][1].length === 4,
+    JSON.stringify(calls),
+  );
+  check(
+    "probeTree: kpsewhich's exit code is not the verdict — the printed paths are",
+    JSON.stringify(missing) === '["latex","libertine"]',
+  );
+}
+// Guards: "could not ask" must never read as "nothing missing" — a broken tree would be used.
+check(
+  "🔴 probeTree: a kpsewhich that cannot start finds NOTHING — never 'all present'",
+  JSON.stringify(
+    probeTree("/none", PKGS, () => ({ error: new Error("ENOENT") })),
+  ) === '["acmart","latex","libertine"]',
+);
+
+// ── 3. "installed" means a regular file that can be run — on a REAL filesystem ─────────────
+// 🔴 `existsSync` says yes to a directory and to a file without the execute bit; both then fail
+// to start, while `paperlint toolchain --check` reported the tree verified. Checked on disk, not
+// through an injected predicate, because the predicate is exactly what was wrong.
+{
+  const bin = realpathSync(mkdtempSync(join(tmpdir(), "rpp-engine-bin-")));
+  try {
+    mkdirSync(join(bin, "texcount"));
+    writeFileSync(join(bin, "checkcites"), "#!/bin/sh\n");
+    chmodSync(join(bin, "checkcites"), 0o644);
+    writeFileSync(join(bin, "pdflatex"), "#!/bin/sh\n");
+    chmodSync(join(bin, "pdflatex"), 0o755);
+    const tools = {
+      texcount: ["texcount"],
+      checkcites: ["checkcites"],
+      pdflatex: ["pdflatex"],
+    };
+    const missing = missingTools(tools, bin);
+    // Guards: the runnable-file check — `existsSync` says yes to a directory, and `paperlint toolchain
+    // --check` once reported a verified tree whose texcount could not start.
+    check(
+      "🔴 missingTools: a DIRECTORY named like the tool is missing",
+      missing.includes("texcount"),
+      JSON.stringify(missing),
+    );
+    // Guards: the POSIX permission half — a file the installer left at 0644 fails to start and must
+    // not read as present.
+    check(
+      "🔴 missingTools: a regular file WITHOUT the execute bit is missing",
+      missing.includes("checkcites"),
+      JSON.stringify(missing),
+    );
+    check(
+      "missingTools: an executable regular file is present",
+      !missing.includes("pdflatex"),
+      JSON.stringify(missing),
+    );
+    check(
+      "whichOnPath: a directory without a runnable pdflatex is passed over",
+      whichOnPath("texcount", bin) === null &&
+        whichOnPath("pdflatex", bin) === bin,
+    );
+    check(
+      "isExecutable: a path that does not exist is not executable",
+      !isExecutable(join(bin, "nope")),
+    );
+    check(
+      "isExecutable on win32: no execute bit to ask — a regular file counts, a directory does not",
+      isExecutable(join(bin, "checkcites"), "win32") &&
+        !isExecutable(join(bin, "texcount"), "win32"),
+    );
+  } finally {
+    rmSync(bin, { recursive: true, force: true });
+  }
+}
+
+console.log(`engine: ${n} checks passed`);

package/src/engine.ts

@@ -0,0 +1,176 @@
+/**
+ * WHICH TeX LIVE `paperlint build` COMPILES WITH — decided from facts, and never a TeX Live that lacks a
+ * package the paper's venue declares.
+ *
+ * 🔴 WHY "HAS pdflatex" IS NOT THE QUESTION. A TeX Live without `libertine.sty` builds an acmart
+ * paper GREEN: the class notices the missing font, falls back to Computer Modern, and the PDF looks
+ * fine in the wrong typeface with another pagination. That is how a submitted paper went out. So a
+ * TeX Live qualifies only when `kpsewhich` finds every file the venue declares (issue #26).
+ *
+ * The order (the Playwright pattern, decided 2026-09-24):
+ *   1. rpp's own cache (`paperlint toolchain` installs it) — when it has everything;
+ *   2. a TeX Live already on PATH — when IT has everything;
+ *   3. neither: on a terminal, ask once and install; without one (CI, an agent), refuse in one line
+ *      that names `npx paperlint toolchain` and the missing packages. Never a silent install without a
+ *      human, never a build on a TeX Live that would typeset the wrong font.
+ *
+ * `resolveEngine` is that order as a PURE function over `EngineFacts`, table-tested. The rest of
+ * this file gathers the facts (probing a tree runs `kpsewhich` through the injected `run`, the port
+ * `build.ts` already uses) and acts on the decision.
+ */
+// eslint-disable-next-line boundaries/dependencies -- legacy I/O, moves behind a port in #76
+import { spawnSync } from "node:child_process";
+// eslint-disable-next-line boundaries/dependencies -- legacy I/O, moves behind a port in #76
+import { accessSync, constants, statSync } from "node:fs";
+import { basename, delimiter, join } from "node:path";
+import type { TexRequirements } from "./tex-requirements.ts";
+
+/** A process runner with `spawnSync`'s shape — the port the harness replaces. */
+export type Runner = typeof spawnSync;
+
+/** One TeX Live and what it lacks for the papers at hand. */
+export interface TreeProbe {
+  /** How to name it to a human: `paperlint cache, TeX Live 2026` / `/usr/bin/pdflatex`. */
+  readonly label: string;
+  /** The directory holding `pdflatex` and `kpsewhich`. */
+  readonly bin: string;
+  /** Declared packages whose proof files `kpsewhich` did not find, sorted. */
+  readonly missing: readonly string[];
+}
+
+export interface EngineFacts {
+  /** install-tl-unx runs here (Linux, macOS). */
+  readonly supported: boolean;
+  /** rpp's cached TeX Live, probed — or null when there is none. */
+  readonly cache: TreeProbe | null;
+  /** The `pdflatex` on PATH, probed — or null when there is none. */
+  readonly system: TreeProbe | null;
+  /** A human can answer a question (a terminal on both ends, CI unset). */
+  readonly interactive: boolean;
+  /** Every package the papers need — what an install into an EMPTY cache would add. */
+  readonly required: readonly string[];
+}
+
+export type EngineDecision =
+  | { readonly kind: "use-cache"; readonly tree: TreeProbe }
+  | { readonly kind: "use-system"; readonly tree: TreeProbe }
+  | { readonly kind: "ask"; readonly missing: readonly string[] }
+  | {
+      readonly kind: "refuse";
+      readonly reason: "unsupported" | "not-installed";
+      readonly missing: readonly string[];
+    };
+
+/**
+ * The decision. `missing` in `ask` and `refuse` is what `paperlint toolchain` would install: the cache's
+ * gaps when a cache exists, every required package when it does not.
+ */
+export function resolveEngine(f: EngineFacts): EngineDecision {
+  if (f.cache && f.cache.missing.length === 0)
+    return { kind: "use-cache", tree: f.cache };
+  if (f.system && f.system.missing.length === 0)
+    return { kind: "use-system", tree: f.system };
+  const missing = f.cache ? f.cache.missing : f.required;
+  if (!f.supported) return { kind: "refuse", reason: "unsupported", missing };
+  if (f.interactive) return { kind: "ask", missing };
+  return { kind: "refuse", reason: "not-installed", missing };
+}
+
+// ── facts ───────────────────────────────────────────────────────────────────────────────
+
+/** install-tl-unx covers Linux and macOS; Windows needs install-tl-windows and is not supported. */
+export const supportedPlatform = (platform: NodeJS.Platform): boolean =>
+  platform === "linux" || platform === "darwin";
+
+/**
+ * The declared packages whose proofs are NOT in `found` (the paths `kpsewhich` printed). kpsewhich
+ * given several names prints one line per name it found and nothing for the rest, so the match is
+ * by the file name of each printed path.
+ */
+export function missingPackages(
+  packages: TexRequirements["packages"],
+  found: string,
+): string[] {
+  const have = new Set(
+    found
+      .split("\n")
+      .map((l) => l.trim())
+      .filter(Boolean)
+      .map((p) => basename(p)),
+  );
+  return Object.entries(packages)
+    .filter(([, proofs]) => proofs.some((f) => !have.has(f)))
+    .map(([name]) => name)
+    .sort();
+}
+
+/**
+ * `path` is a program that can be started: a REGULAR FILE, and on POSIX one this process may
+ * execute. `existsSync` is not the question — it says yes to a directory and to a file without
+ * the execute bit, and `paperlint toolchain --check` then reported a verified tree whose `texcount`
+ * could not run.
+ *
+ * On win32 `X_OK` means nothing (Node documents it as behaving like `F_OK` there): whether a file
+ * runs is decided by its extension, not a permission bit. So on win32 the check is "exists and is
+ * a regular file", which is all the platform can answer.
+ */
+export function isExecutable(
+  path: string,
+  // eslint-disable-next-line no-restricted-globals -- legacy I/O, moves behind a port in #76
+  platform: NodeJS.Platform = process.platform,
+): boolean {
+  try {
+    if (!statSync(path).isFile()) return false;
+    if (platform !== "win32") accessSync(path, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** The declared tools (programs) that have no executable in `bin`. */
+export function missingTools(
+  tools: TexRequirements["tools"],
+  bin: string,
+  exists: (path: string) => boolean = isExecutable,
+): string[] {
+  return Object.entries(tools)
+    .filter(([, bins]) => bins.some((b) => !exists(join(bin, b))))
+    .map(([name]) => name)
+    .sort();
+}
+
+/** Every proof file, once — the arguments of one `kpsewhich` call. */
+const proofFiles = (packages: TexRequirements["packages"]): string[] => [
+  ...new Set(Object.values(packages).flat()),
+];
+
+/**
+ * Ask the `kpsewhich` in `bin` for every proof file. A kpsewhich that cannot be started finds
+ * nothing, so every package counts as missing — "could not ask" must never read as "all present".
+ */
+export function probeTree(
+  bin: string,
+  packages: TexRequirements["packages"],
+  run: Runner = spawnSync,
+): string[] {
+  const files = proofFiles(packages);
+  if (files.length === 0) return [];
+  const r = run(join(bin, "kpsewhich"), files, {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  if (r.error) return Object.keys(packages).sort();
+  return missingPackages(packages, String(r.stdout ?? ""));
+}
+
+/** The first directory on `path` holding a runnable `name` — what a shell would run. */
+export function whichOnPath(
+  name: string,
+  path: string | undefined,
+  exists: (p: string) => boolean = isExecutable,
+): string | null {
+  for (const dir of (path ?? "").split(delimiter))
+    if (dir && exists(join(dir, name))) return dir;
+  return null;
+}

package/src/exit-code.test.ts

@@ -0,0 +1,21 @@
+import assert from "node:assert/strict";
+import { test } from "vitest";
+import { exitCodeFor, type ExitCode, type ShimOutcome } from "./exit-code.ts";
+
+/** Every outcome × both modes: [outcome, without --strict, with --strict]. */
+const TABLE: readonly (readonly [ShimOutcome, ExitCode, ExitCode])[] = [
+  ["written", 0, 0],
+  // Guards: in CI a missing banal is an environment error, not a skip that reads as a pass.
+  ["no-geometry", 0, 1],
+  ["unreadable", 0, 1],
+  ["no-such-path", 1, 1],
+  // Guards: "the artifact is not built" is its own code, told apart from "extraction crashed".
+  ["no-artifact", 3, 3],
+  ["usage", 2, 2],
+];
+
+for (const [outcome, local, strict] of TABLE)
+  test(`exitCodeFor: ${outcome}`, () => {
+    assert.equal(exitCodeFor(outcome, { strict: false }), local);
+    assert.equal(exitCodeFor(outcome, { strict: true }), strict);
+  });

package/src/exit-code.ts

@@ -0,0 +1,38 @@
+/**
+ * The exit-code contract of `skills/render-paper/extract-pdf-facts.mjs`, as a total function. CI
+ * steps branch on these codes, so the mapping lives in one table instead of in five `process.exit`
+ * calls, and `--strict` changes exactly the rows it names.
+ *
+ *   0  facts written — or, without `--strict`, not taken and said so (a local run may lack banal)
+ *   1  no such path; or, with `--strict`, the facts could not be taken (unreadable PDF, no geometry)
+ *   2  usage
+ *   3  the paper declares an artifact that is not built
+ */
+export type ShimOutcome =
+  | "written"
+  /** Measured, but banal gave no geometry (not found, no perl, failed). */
+  | "no-geometry"
+  /** pdf.js could not read the PDF. */
+  | "unreadable"
+  | "no-such-path"
+  | "no-artifact"
+  | "usage";
+
+export interface ShimMode {
+  /** CI: a missing tool is an ENVIRONMENT error, and a skipped step must not look like a passed one. */
+  readonly strict: boolean;
+}
+
+export type ExitCode = 0 | 1 | 2 | 3;
+
+const CODES: { readonly [K in ShimOutcome]: (m: ShimMode) => ExitCode } = {
+  written: () => 0,
+  "no-geometry": (m) => (m.strict ? 1 : 0),
+  unreadable: (m) => (m.strict ? 1 : 0),
+  "no-such-path": () => 1,
+  "no-artifact": () => 3,
+  usage: () => 2,
+};
+
+export const exitCodeFor = (o: ShimOutcome, m: ShimMode): ExitCode =>
+  CODES[o](m);