paperlint 2.0.0

package/src/adapters/banal/invocation.test.ts

@@ -0,0 +1,74 @@
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  realpathSync,
+  rmSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll as after, test } from "vitest";
+import { nodeAdapters } from "../node/index.ts";
+import type { AbsolutePath } from "../../domain/paths.ts";
+import {
+  banalCommand,
+  shQuote,
+  stage,
+  stageBanalInput,
+  type StagedInput,
+} from "./invocation.ts";
+import type { LocatedBanal } from "./locate.ts";
+import { XML_DIALECT } from "./xml.ts";
+
+test("the staging holds BOTH files: the XML and the -v stub answering the dialect rpp writes", () => {
+  const [xml, stub] = stageBanalInput([]).files;
+  assert.equal(xml.name, "paper.xml");
+  assert.match(xml.content, /^<\?xml/);
+  assert.equal(stub.mode, "exec");
+  // Guards: the version the stub answers — below 0.85 banal moves every font size.
+  assert.ok(stub.content.includes(`pdftohtml version ${XML_DIALECT.version}`));
+});
+
+test("banalCommand: perl runs banal on the staged .xml, with $PDFTOHTML quoted", () => {
+  const banal = {
+    path: "/b/banal" as AbsolutePath,
+    provenance: { kind: "cache" },
+  } as LocatedBanal;
+  const staged = { xml: "/s/paper.xml", stub: "/s d/pdftohtml" } as StagedInput;
+  const c = banalCommand(banal, staged, { PATH: "/bin" });
+  assert.deepEqual(
+    [c.file, ...c.args],
+    ["perl", "/b/banal", "-no-time", "-json", "/s/paper.xml"],
+  );
+  // Guards: banal interpolates $PDFTOHTML into /bin/sh unquoted; a space in $TMPDIR must survive.
+  assert.deepEqual(c.env, { PATH: "/bin", PDFTOHTML: "'/s d/pdftohtml'" });
+});
+
+test("shQuote survives a single quote", () => {
+  assert.equal(shQuote("it's"), `'it'"'"'s'`);
+});
+
+const root = realpathSync(mkdtempSync(join(tmpdir(), "rpp-stage-test-")));
+after(() => rmSync(root, { recursive: true, force: true }));
+
+test("🔴 stage: on a real scratch directory the stub answers `-v` through the shell, from a path with a space and a quote", () => {
+  const awkward = join(root, "it's a dir");
+  mkdirSync(awkward);
+  const { workspace } = nodeAdapters({ tmpDir: awkward });
+  workspace.within("rpp-banal-", (s) => {
+    const staged = stage(s, stageBanalInput([]));
+    assert.ok(existsSync(staged.xml));
+    // Guards: banal runs `$PDFTOHTML -v 2>&1 |` through /bin/sh, unquoted.
+    const v = spawnSync("/bin/sh", ["-c", `${shQuote(staged.stub)} -v 2>&1`], {
+      encoding: "utf8",
+    });
+    assert.equal(v.stdout.trim(), "pdftohtml version 24.02.0");
+    const convert = spawnSync(staged.stub, ["-xml", "paper.pdf", "out"], {
+      encoding: "utf8",
+    });
+    assert.equal(convert.status, 1);
+    assert.match(convert.stderr, /only answers -v/);
+  });
+});

package/src/adapters/banal/invocation.ts

@@ -0,0 +1,95 @@
+/**
+ * A banal run, as DATA. What must be on disk before banal starts — the banal input XML and the
+ * `pdftohtml -v` stub, always together — and the command that runs it.
+ *
+ * Why the stub: banal asks `$pdftohtml -v` once, before it reads any input (the XML included), to
+ * pick the zoom and a font-size correction (banal 1.2, lines 1828-1868). With no pdftohtml it stops
+ * (`Error: Failed to run pdftohtml`, measured); told a version below 0.85 it applies a larger
+ * correction and every font size moves. So `$PDFTOHTML` (banal's own override, line 166) points at a
+ * stub that answers `-v` with `XML_DIALECT.version` — the pdftohtml whose XML `xml.ts` writes — and
+ * refuses anything else. `test/e2e/banal.mjs` shows both failures with the real banal.
+ */
+import type { Opaque } from "ts-essentials";
+import type { AbsolutePath } from "../../domain/paths.ts";
+import type { Command } from "../../ports/process.ts";
+import type { Scratch } from "../../ports/workspace.ts";
+import type { LocatedBanal } from "./locate.ts";
+import type { PageLayout } from "../../domain/page-layout.ts";
+import { pdf2xml, XML_DIALECT } from "./xml.ts";
+
+/** banal takes well under a second on a paper; a hang still has to end. */
+export const BANAL_RUN_MS = 120_000;
+
+/** A path quoted for `/bin/sh`. Minted by `shQuote` only. */
+export type ShQuoted = Opaque<string, "ShQuoted">;
+
+/** banal interpolates `$PDFTOHTML` into a shell command unquoted — so the value is quoted here. */
+export const shQuote = (s: string): ShQuoted =>
+  `'${s.replace(/'/g, `'"'"'`)}'` as ShQuoted;
+
+/** The stub standing in for `pdftohtml`: it answers `-v` and refuses to convert anything. */
+export const PDFTOHTML_STUB = [
+  "#!/bin/sh",
+  "# research-paper-pipeline: banal reads the banal input XML rpp writes, never a PDF. banal still",
+  "# asks `pdftohtml -v` which dialect to expect; this answers with the one rpp writes.",
+  'if [ "$1" = "-v" ]; then',
+  `  echo "pdftohtml version ${XML_DIALECT.version}"`,
+  "  exit 0",
+  "fi",
+  'echo "rpp: this pdftohtml only answers -v; banal was given a PDF instead of the banal input XML" >&2',
+  "exit 1",
+  "",
+].join("\n");
+
+export interface StagedFile<N extends string, M extends "read" | "exec"> {
+  readonly name: N;
+  readonly content: string;
+  readonly mode: M;
+}
+
+/** What must exist on disk before banal runs. Both files, always: there is no way to build one alone. */
+export interface BanalStaging {
+  readonly files: readonly [
+    StagedFile<"paper.xml", "read">,
+    StagedFile<"pdftohtml", "exec">,
+  ];
+}
+
+export const stageBanalInput = (
+  pages: readonly PageLayout[],
+): BanalStaging => ({
+  files: [
+    { name: "paper.xml", content: pdf2xml(pages), mode: "read" },
+    { name: "pdftohtml", content: PDFTOHTML_STUB, mode: "exec" },
+  ],
+});
+
+/** The staging written to disk. Minted by `stage` only: both files written, or nothing returned. */
+export type StagedInput = Opaque<
+  { readonly xml: AbsolutePath; readonly stub: AbsolutePath },
+  "StagedInput"
+>;
+
+/** Write a staging into a scratch directory, the stub executable. The only minter of `StagedInput`. */
+export function stage(s: Scratch, staging: BanalStaging): StagedInput {
+  const [xml, stub] = staging.files;
+  return {
+    xml: s.write(xml.name, xml.content, xml.mode),
+    stub: s.write(stub.name, stub.content, stub.mode),
+  } as StagedInput;
+}
+
+/** `perl banal -no-time -json <xml>`, with `$PDFTOHTML` quoted by construction. */
+export function banalCommand(
+  banal: LocatedBanal,
+  staged: StagedInput,
+  baseEnv: Readonly<Record<string, string>>,
+): Command {
+  return {
+    file: "perl",
+    args: [banal.path, "-no-time", "-json", staged.xml],
+    env: { ...baseEnv, PDFTOHTML: shQuote(staged.stub) },
+    timeoutMs: BANAL_RUN_MS,
+    maxOutputBytes: 64 * 1024 * 1024,
+  };
+}

package/src/adapters/banal/locate.test.ts

@@ -0,0 +1,52 @@
+import assert from "node:assert/strict";
+import { test } from "vitest";
+import type { AbsolutePath } from "../../domain/paths.ts";
+import { err } from "../../domain/result.ts";
+import { installedBanal, lookupOrder, pickBanal } from "./locate.ts";
+import { BANAL_PIN } from "./pin.ts";
+import { parseBanalSettings } from "./settings.ts";
+
+const dirs = { home: "/h", tmp: "/t", cwd: "/w" };
+const project = "/p" as AbsolutePath;
+const cache = `/h/.cache/rpp/banal/${BANAL_PIN.commit.slice(0, 12)}/banal`;
+const on =
+  (...files: string[]) =>
+  (p: string) =>
+    files.includes(p);
+const pick = (env: Record<string, string>, isFile: (p: string) => boolean) =>
+  pickBanal(lookupOrder(parseBanalSettings(env, dirs), project), isFile);
+const kind = (r: ReturnType<typeof pick>) =>
+  r.ok ? r.value.provenance.kind : r.error.kind;
+
+test("installedBanal: one directory per HotCRP commit", () => {
+  assert.equal(installedBanal(parseBanalSettings({}, dirs)), cache);
+});
+
+test("rpp's own copy when nothing else is named", () => {
+  assert.equal(kind(pick({}, on(cache))), "cache");
+});
+
+test("a project's vendor/banal before rpp's copy", () => {
+  // Guards: a project that vendors banal keeps using its own copy.
+  assert.equal(kind(pick({}, on(cache, "/p/vendor/banal"))), "vendor");
+});
+
+test("$BANAL before both", () => {
+  const r = pick({ BANAL: "/own" }, on("/own", cache, "/p/vendor/banal"));
+  assert.equal(r.ok && r.value.path, "/own");
+});
+
+test("🔴 $BANAL naming a missing file finds NOTHING — no fallback to another banal", () => {
+  // Guards: an explicit choice that is wrong is an error, not a silent fall-back.
+  assert.deepEqual(
+    pick({ BANAL: "/nope" }, on(cache, "/p/vendor/banal")),
+    err({ kind: "explicit-not-found", path: "/nope" }),
+  );
+});
+
+test("nothing anywhere: not installed, naming where rpp's copy would be", () => {
+  assert.deepEqual(
+    pick({}, on()),
+    err({ kind: "not-installed", installed: cache }),
+  );
+});

package/src/adapters/banal/locate.ts

@@ -0,0 +1,84 @@
+/**
+ * Where a banal may be, in order; which one is there; and which rule found it. The order:
+ * `$BANAL` (an explicit choice — if it names nothing, there is NO fallback), `<project>/vendor/banal`
+ * (a project that vendors its own copy), then the one `paperlint toolchain` installed.
+ */
+import { join } from "node:path";
+import type { Opaque } from "ts-essentials";
+import type { AbsolutePath } from "../../domain/paths.ts";
+import { err, ok, type Result } from "../../domain/result.ts";
+import { BANAL_PIN } from "./pin.ts";
+import type { BanalSettings } from "./settings.ts";
+
+export type Provenance =
+  | { readonly kind: "env" }
+  | { readonly kind: "vendor" }
+  | { readonly kind: "cache" };
+
+export interface BanalCandidate {
+  readonly path: AbsolutePath;
+  readonly provenance: Provenance;
+}
+
+/** A candidate the `Files` port confirmed is a file. Minted by `pickBanal` only. */
+export type LocatedBanal = Opaque<BanalCandidate, "LocatedBanal">;
+
+/**
+ * `paperlint toolchain`'s banal after its bytes hashed to the pin AND it measured the probe page. Minted by
+ * `ensureBanal` / `checkBanal` only (`./index.ts`): a "ready" line cannot be printed without one.
+ */
+export type PinnedBanal = Opaque<BanalCandidate, "PinnedBanal">;
+
+/** Why there is no banal to run. */
+export type BanalMissing =
+  /** `$BANAL` names a file that is not there. An explicit choice: no fallback to another banal. */
+  | { readonly kind: "explicit-not-found"; readonly path: string }
+  /** Nothing named, nothing vendored, and `paperlint toolchain` has not installed it (here). */
+  | { readonly kind: "not-installed"; readonly installed: string };
+
+/** Where to look. An explicit `$BANAL` is the whole search; otherwise vendor, then the cache. */
+export type LookupOrder =
+  | { readonly kind: "explicit"; readonly path: AbsolutePath }
+  | {
+      readonly kind: "search";
+      readonly vendor: AbsolutePath;
+      readonly cache: AbsolutePath;
+    };
+
+/** Where `paperlint toolchain` puts the pinned banal: one directory per HotCRP commit. */
+export const installedBanal = (s: BanalSettings): AbsolutePath =>
+  join(s.cacheDir, BANAL_PIN.commit.slice(0, 12), "banal") as AbsolutePath;
+
+export function lookupOrder(
+  s: BanalSettings,
+  projectRoot: AbsolutePath,
+): LookupOrder {
+  if (s.explicit) return { kind: "explicit", path: s.explicit };
+  return {
+    kind: "search",
+    vendor: join(projectRoot, "vendor", "banal") as AbsolutePath,
+    cache: installedBanal(s),
+  };
+}
+
+const located = (path: AbsolutePath, kind: Provenance["kind"]) =>
+  ok({ path, provenance: { kind } } as LocatedBanal);
+
+export function pickBanal(
+  order: LookupOrder,
+  isFile: (p: AbsolutePath) => boolean,
+): Result<LocatedBanal, BanalMissing> {
+  if (order.kind === "explicit")
+    return isFile(order.path)
+      ? located(order.path, "env")
+      : err({ kind: "explicit-not-found", path: order.path });
+  if (isFile(order.vendor)) return located(order.vendor, "vendor");
+  if (isFile(order.cache)) return located(order.cache, "cache");
+  return err({ kind: "not-installed", installed: order.cache });
+}
+
+/** Which rule found it, as a person reads it. */
+export const provenanceLabel = (p: Provenance): string =>
+  ({ env: "$BANAL", vendor: "vendor/banal", cache: "paperlint toolchain" })[
+    p.kind
+  ];

package/src/adapters/banal/output.test.ts

@@ -0,0 +1,140 @@
+/**
+ * `output.ts` — every way a banal run can end, as a table of `ProcessExit` → `Result`, and the
+ * measurement → geometry projection. Pure: no perl, no disk. The real banal is `test/e2e/banal.mjs`.
+ */
+import assert from "node:assert/strict";
+import { test } from "vitest";
+import type { ProcessExit } from "../../ports/process.ts";
+import { err } from "../../domain/result.ts";
+import type { BanalFailure } from "./failure.ts";
+import {
+  geometryOf,
+  parseBanalOutput,
+  type BanalMeasurement,
+} from "./output.ts";
+
+const exited = (
+  over: Partial<{ status: number; stdout: string; stderr: string }>,
+): ProcessExit => ({
+  kind: "exited",
+  status: 0,
+  stdout: "",
+  stderr: "",
+  ...over,
+});
+
+/** The failure a row expects, or the `kind` only when its detail is a zod message. */
+const ROWS: readonly (readonly [
+  string,
+  ProcessExit,
+  BanalFailure | BanalFailure["kind"],
+])[] = [
+  [
+    // Guards: perl missing is its own diagnosis, not "banal failed: ENOENT".
+    "perl not found",
+    { kind: "not-found", file: "perl" },
+    { kind: "perl-missing" },
+  ],
+  [
+    "spawn failed",
+    { kind: "spawn-failed", message: "EACCES" },
+    { kind: "spawn-failed", message: "EACCES" },
+  ],
+  [
+    "timed out",
+    { kind: "timed-out", afterMs: 50, stdout: "", stderr: "" },
+    { kind: "timed-out", afterMs: 50 },
+  ],
+  [
+    "killed by a signal",
+    { kind: "signalled", signal: "SIGKILL", stdout: "", stderr: "\n oom \n" },
+    { kind: "signalled", signal: "SIGKILL", stderrHead: "oom" },
+  ],
+  [
+    "a nonzero exit names the exit and banal's first line",
+    exited({ status: 1, stderr: "\nx.xml: Error: bad\nmore" }),
+    { kind: "process-failed", status: 1, stderrHead: "x.xml: Error: bad" },
+  ],
+  [
+    "output that is not JSON",
+    exited({ stdout: "Usage: banal" }),
+    { kind: "no-json", head: "Usage: banal" },
+  ],
+  [
+    // Guards: banal's own failure object exits 0 — it must not read as zero pages.
+    'banal\'s `"error": true` with exit 0',
+    exited({ stdout: '{"error": true, "pages": []}', stderr: "cannot read" }),
+    { kind: "banal-error", stderrHead: "cannot read" },
+  ],
+  [
+    "JSON that is not an object",
+    exited({ stdout: "[1, 2]" }),
+    "unexpected-shape",
+  ],
+  [
+    "an object with no `pages`",
+    exited({ stdout: '{"columns": 2}' }),
+    "unexpected-shape",
+  ],
+];
+
+for (const [label, exit, want] of ROWS) {
+  test(`parseBanalOutput: ${label}`, () => {
+    const got = parseBanalOutput(exit);
+    if (typeof want === "string")
+      assert.equal(!got.ok && got.error.kind, want, JSON.stringify(got));
+    else assert.deepEqual(got, err(want));
+  });
+}
+
+test("parseBanalOutput: a measurement is parsed, unknown fields kept", () => {
+  const got = parseBanalOutput(
+    exited({ stdout: '{"columns": 2, "pages": [{}], "extra": 1}' }),
+  );
+  assert.ok(got.ok);
+  assert.equal(got.value.columns, 2);
+  assert.equal(got.value.pages.length, 1);
+});
+
+const M = (over: Partial<BanalMeasurement>): BanalMeasurement => ({
+  pages: [],
+  ...over,
+});
+
+test("geometryOf: a page without a type IS a body page", () => {
+  // Guards: banal omits `type` on body pages; counting type === "body" gave zero for every paper.
+  const g = geometryOf(
+    M({
+      pages: [
+        {},
+        {},
+        {},
+        { type: "bib", reffontsize: 8.5 },
+        { type: "appendix" },
+      ],
+    }),
+  );
+  assert.deepEqual(
+    [g.bodyPages, g.refPages, g.appendixPages, g.refPt],
+    [3, 1, 1, 8.5],
+  );
+  assert.deepEqual(g.pagesByType, { body: 3, bib: 1, appendix: 1 });
+});
+
+test("geometryOf: papersize is [height, width] in points → inches", () => {
+  const g = geometryOf(
+    M({ papersize: [792, 612], columns: 2, bodyfontsize: 10 }),
+  );
+  assert.deepEqual(
+    [g.pageWidthIn, g.pageHeightIn, g.columns, g.bodyPt],
+    [8.5, 11, 2, 10],
+  );
+});
+
+test("geometryOf: an empty measurement is nulls and zeros, not a crash", () => {
+  const g = geometryOf(M({ bodyfontsize: null }));
+  assert.deepEqual(
+    [g.pageWidthIn, g.columns, g.bodyPt, g.refPt, g.bodyPages],
+    [null, null, null, null, 0],
+  );
+});

package/src/adapters/banal/output.ts

@@ -0,0 +1,141 @@
+/**
+ * banal's output, PARSED — one schema, one type, read by both consumers (the facts file and the
+ * install probe). What banal prints was measured on the pinned banal 1.2 (2026-09-25): an object
+ * with `papersize` ([height, width] in points), `columns`, `bodyfontsize` — null on an empty
+ * document — and `pages`, one entry per page, where a page's `type` is OMITTED when it is "body".
+ */
+import { z } from "zod";
+import type { PageGeometry } from "../../domain/geometry.ts";
+import { firstLine } from "../../domain/text.ts";
+import type { ProcessExit } from "../../ports/process.ts";
+import { andThen, err, ok, type Result } from "../../domain/result.ts";
+import type { BanalFailure } from "./failure.ts";
+
+const page = z.looseObject({
+  type: z.string().optional(),
+  reffontsize: z.number().nullable().optional(),
+});
+
+/** banal's own failure object: exit 0 and `{"error": true, …}`. It has no measurement in it. */
+const banalError = z.looseObject({ error: z.literal(true) });
+
+export const measurementSchema = z.looseObject({
+  papersize: z.tuple([z.number(), z.number()]).optional(),
+  columns: z.number().nullable().optional(),
+  bodyfontsize: z.number().nullable().optional(),
+  /** Required: banal emits it on every run, an empty document included (measured). */
+  pages: z.array(page),
+});
+
+/** A measurement banal printed. banal's `{"error": true}` object cannot be one: it is refused first. */
+export type BanalMeasurement = z.infer<typeof measurementSchema>;
+
+interface Streams {
+  readonly stdout: string;
+  readonly stderr: string;
+}
+
+/** The process-level outcome, before stdout is read: banal's streams, or why there are none. */
+function streamsOf(r: ProcessExit): Result<Streams, BanalFailure> {
+  switch (r.kind) {
+    case "not-found":
+      return err({ kind: "perl-missing" });
+    case "spawn-failed":
+      return err({ kind: "spawn-failed", message: r.message });
+    case "timed-out":
+      return err({ kind: "timed-out", afterMs: r.afterMs });
+    case "signalled":
+      return err({
+        kind: "signalled",
+        signal: r.signal,
+        stderrHead: firstLine(r.stderr),
+      });
+    case "exited":
+      return r.status === 0
+        ? ok(r)
+        : err({
+            kind: "process-failed",
+            status: r.status,
+            stderrHead: firstLine(r.stderr),
+          });
+  }
+}
+
+function jsonOf(stdout: string): Result<unknown, null> {
+  try {
+    return ok(JSON.parse(stdout));
+  } catch {
+    return err(null);
+  }
+}
+
+/** What banal printed, as a measurement — or which failure it is. */
+function measurementOf(o: Streams): Result<BanalMeasurement, BanalFailure> {
+  const json = jsonOf(o.stdout);
+  if (!json.ok)
+    return err({
+      kind: "no-json",
+      head: firstLine(o.stdout) || firstLine(o.stderr),
+    });
+  if (banalError.safeParse(json.value).success)
+    return err({ kind: "banal-error", stderrHead: firstLine(o.stderr) });
+  const m = measurementSchema.safeParse(json.value);
+  return m.success
+    ? ok(m.data)
+    : err({
+        kind: "unexpected-shape",
+        issues: m.error.issues.map(
+          (i) => `${i.path.join(".") || "(root)"}: ${i.message}`,
+        ),
+      });
+}
+
+/** A banal run as a measurement, or which failure it was. Total over `ProcessExit`. */
+export const parseBanalOutput = (
+  r: ProcessExit,
+): Result<BanalMeasurement, BanalFailure> =>
+  andThen(streamsOf(r), measurementOf);
+
+const inches = (pt: number | undefined): number | null =>
+  pt === undefined ? null : Number((pt / 72).toFixed(3));
+
+type Page = BanalMeasurement["pages"][number];
+
+/**
+ * 🔴 banal OMITS a page's `type` when it is "body" (its line 1022: `push … if $page->{type} ne
+ * "body"`), so counting pages whose type equals "body" gives ZERO for every paper in the world —
+ * that is how the first page-limit gate was written, and it could not fire once. A page without a
+ * type IS a body page.
+ */
+const typeOf = (p: Page): string => p.type ?? "body";
+
+/** Pages per type, body pages included under "body". */
+function countByType(pages: readonly Page[]): Record<string, number> {
+  const byType: Record<string, number> = {};
+  for (const p of pages) byType[typeOf(p)] = (byType[typeOf(p)] ?? 0) + 1;
+  return byType;
+}
+
+/** The reference font size: the first bibliography page that has one. */
+const refFontSize = (pages: readonly Page[]): number | null =>
+  pages.find((p) => p.type === "bib" && p.reffontsize != null)?.reffontsize ??
+  null;
+
+/** The measurement → the domain's page geometry. */
+export function geometryOf(m: BanalMeasurement): PageGeometry {
+  const byType = countByType(m.pages);
+  const refPages = byType["bib"] ?? 0;
+  const appendixPages = byType["appendix"] ?? 0;
+  return {
+    // banal gives papersize as [height, width] in points — checked against live output 2026-08-26.
+    pageWidthIn: inches(m.papersize?.[1]),
+    pageHeightIn: inches(m.papersize?.[0]),
+    columns: m.columns ?? null,
+    bodyPt: m.bodyfontsize ?? null,
+    refPt: refFontSize(m.pages),
+    bodyPages: m.pages.length - refPages - appendixPages,
+    refPages,
+    appendixPages,
+    pagesByType: byType,
+  };
+}

package/src/adapters/banal/pin.ts

@@ -0,0 +1,30 @@
+/**
+ * The banal paperlint runs: HotCRP at one commit, one file, one sha256. The licence boundary is in
+ * `./index.ts`: paperlint downloads and runs banal, it never contains it.
+ */
+import { parseSha256, type Sha256 } from "../../domain/sha256.ts";
+
+/** Where to download banal from, and the bytes to accept. The pin by default; a test passes a local file. */
+export interface BanalSource {
+  readonly url: string;
+  readonly sha256: Sha256;
+}
+
+export interface BanalPin extends BanalSource {
+  readonly version: string;
+  readonly commit: string;
+}
+
+/** Parsed at module load: a typo in the pin fails on import, not at the first download. */
+export const BANAL_PIN: BanalPin = {
+  version: "1.2",
+  commit: "f3e4352133f3184c7c42b0d5e6501124bead18e6",
+  url: "https://raw.githubusercontent.com/kohler/hotcrp/f3e4352133f3184c7c42b0d5e6501124bead18e6/src/banal",
+  sha256: parseSha256(
+    "fd8cc4ae189b9da02460ae442a34f14434e5784210489fb668313ac671006911",
+  ),
+};
+
+/** How a person reads the pin: `banal 1.2 (HotCRP f3e4352)`. */
+export const pinLabel = (pin: BanalPin = BANAL_PIN): string =>
+  `banal ${pin.version} (HotCRP ${pin.commit.slice(0, 7)})`;

package/src/adapters/banal/probe.ts

@@ -0,0 +1,35 @@
+/**
+ * Does a banal RUN — accepted by a measurement, not by the download's exit code. The probe is one
+ * US-letter page of 50 lines of 10 pt text: enough for banal to measure a body font size.
+ */
+import { err, ok, type Result } from "../../domain/result.ts";
+import type { BanalFailure } from "./failure.ts";
+import type { BanalMeasurement } from "./output.ts";
+import type { PageLayout } from "../../domain/page-layout.ts";
+
+/** One text line of 90 characters, 10 pt, at line `i` of a one-column page. */
+const probeLine = (i: number) => ({
+  top: 72 + i * 12,
+  left: 72,
+  width: 468,
+  height: 10,
+  size: 10,
+  font: "Times-Roman",
+  text: "x".repeat(90),
+  upright: true,
+  fill: { kind: "unknown" } as const,
+});
+
+export const PROBE_PAGE: PageLayout = {
+  widthPt: 612,
+  heightPt: 792,
+  boxes: Array.from({ length: 50 }, (_, i) => probeLine(i)),
+};
+
+/** A probe measurement is accepted when banal saw the one page and measured its body size. */
+export const acceptProbe = (
+  m: BanalMeasurement,
+): Result<BanalMeasurement, BanalFailure> =>
+  m.pages.length === 1 && typeof m.bodyfontsize === "number"
+    ? ok(m)
+    : err({ kind: "probe-rejected", got: m });