paperlint 2.0.0

package/src/facts-file.test.ts

@@ -0,0 +1,240 @@
+/**
+ * `facts-file.ts` — the one writer of `_build/paper.facts.json`.
+ *
+ * The document is assembled from hand-made measurements (pure), and `measurePaper` runs on
+ * in-memory files with a FAKE pdf.js reader and a FAKE measurer, so each outcome — read failed, not
+ * measured, measured — is chosen rather than hoped for. Reading real PDFs is
+ * `pdf-facts.harness.mjs`'s job; banal as the measurer is `adapters/banal/index.test.ts`, and the
+ * real banal is `test/e2e/banal.mjs`.
+ */
+import assert from "node:assert/strict";
+import { test } from "vitest";
+import { memoryFiles } from "./adapters/memory/index.ts";
+import {
+  declaredVenue,
+  factsDocument,
+  factsPath,
+  measurePaper,
+  writeFactsFile,
+  type MeasureOptions,
+} from "./facts-file.ts";
+import { whyNoGeometry, type Geometry } from "./domain/geometry.ts";
+import { sha256Hex } from "./domain/sha256.ts";
+import type { Fonts, PageText } from "./pdf-geometry.ts";
+import type { PdfReader } from "./pdf-facts.ts";
+
+/** A last page of `left` and `right` words in two columns, plus `extra`. */
+const lastPage = (
+  left: number,
+  right: number,
+  extra: PageText["words"] = [],
+): PageText => {
+  const col = (x: number, n: number) =>
+    Array.from({ length: n }, (_, i) => ({
+      x0: x,
+      y0: 60 + i * 10,
+      x1: x + 20,
+      y1: 70 + i * 10,
+      text: "w",
+    }));
+  return {
+    widthPt: 612,
+    heightPt: 792,
+    words: [...col(54, left), ...col(320, right), ...extra],
+  };
+};
+const FONTS: Fonts = {
+  kind: "drawn",
+  list: [
+    { kind: "embedded", name: "LinLibertineT", program: "Type1C" },
+    { kind: "type3", name: "Type3" },
+    { kind: "not-embedded", name: "Times-Roman", program: "Type1" },
+  ],
+};
+const NONE: Geometry = {
+  kind: "unmeasured",
+  why: ["perl is not installed"],
+  tried: null,
+};
+/** A measurement, in the domain's names, by a measurer called `banal`. */
+const MEASURED: Geometry = {
+  kind: "measured",
+  by: { tool: "banal", path: "/b", how: "$BANAL" },
+  geometry: {
+    pageWidthIn: 8.5,
+    pageHeightIn: 11,
+    columns: 2,
+    bodyPt: 9,
+    refPt: 7,
+    bodyPages: 3,
+    refPages: 1,
+    appendixPages: 1,
+    pagesByType: { body: 3, bib: 1, appendix: 1 },
+  },
+};
+const doc = (last: PageText, geometry: Geometry = NONE) =>
+  factsDocument({
+    pdf: "paper.pdf",
+    sha: "a".repeat(64),
+    venue: "agenticdev",
+    kind: "short",
+    read: { pages: 4, fonts: FONTS, last, layout: [] },
+    geometry,
+  });
+
+// ── the document ────────────────────────────────────────────────────────────────────────
+test("schema 2; a measured last page gives both heights, in both fields", () => {
+  const d = doc(lastPage(60, 30));
+  assert.equal(d.schema, 2);
+  assert.deepEqual(d.last_page, { kind: "measured", columns_pt: [600, 300] });
+  assert.deepEqual(d.last_page_cols_pt, [600, 300]);
+  assert.equal(d.npages, 4);
+  assert.equal(d.fonts_source, "pdfjs-drawn");
+});
+
+test("fonts keep poppler's spelling; Type 3 is embedded; no usable program is not", () => {
+  const d = doc(lastPage(60, 30));
+  assert.deepEqual(d.fonts[1], {
+    name: "Type3",
+    type: "Type 3",
+    embedded: true,
+    program: "Type3",
+  });
+  // Guards: a font with no usable program is `embedded: false`.
+  assert.equal(d.fonts[2]?.embedded, false);
+});
+
+test("🔴 a review build: last_page says review, and last_page_cols_pt is null", () => {
+  const numbers = Array.from({ length: 60 }, (_, i) => ({
+    x0: 20,
+    y0: 60 + i * 10,
+    x1: 30,
+    y1: 70 + i * 10,
+    text: String(i + 1),
+  }));
+  const d = doc(lastPage(60, 10, numbers));
+  // Guards: no fudged heights on a review build.
+  assert.deepEqual(d.last_page, { kind: "review", line_numbers: 60 });
+  assert.equal(d.last_page_cols_pt, null);
+  const stub = doc(lastPage(3, 0));
+  assert.deepEqual(stub.last_page, { kind: "stub", words: 3 });
+});
+
+test("🔴 geometry_source and the nine columns come from ONE branch", () => {
+  const none = doc(lastPage(60, 30));
+  assert.equal(none.geometry_source, null);
+  assert.equal(none.page_w_in, null);
+  assert.equal(none.body_pages, null);
+  const measured = doc(lastPage(60, 30), MEASURED);
+  // Guards: the file names the measurer that measured, from the provenance only an adapter builds.
+  assert.equal(measured.geometry_source, "banal");
+  assert.deepEqual(
+    [
+      measured.body_pages,
+      measured.ref_pages,
+      measured.page_w_in,
+      measured.ref_pt,
+    ],
+    [3, 1, 8.5, 7],
+  );
+});
+
+// ── measuring and writing ───────────────────────────────────────────────────────────────
+const PAPER = "/r/papers/p";
+const PDF = `${PAPER}/paper.pdf`;
+const PDF_BYTES = "%PDF-pretend";
+const good: PdfReader = async () => ({
+  ok: true,
+  facts: { pages: 2, fonts: FONTS, last: lastPage(60, 60), layout: [] },
+});
+/** Options over in-memory files: the PDF and venue.json on "disk", a measurer answering `geometry`. */
+function setup(geometry: Geometry = NONE) {
+  const files = memoryFiles({
+    [PDF]: PDF_BYTES,
+    [`${PAPER}/venue.json`]: JSON.stringify({
+      venue: "agenticdev",
+      kind: "short",
+    }),
+  });
+  const measured: unknown[] = [];
+  const o: MeasureOptions = {
+    readPdf: good,
+    files,
+    measure: {
+      measure(pages) {
+        measured.push(pages);
+        return geometry;
+      },
+    },
+  };
+  return { files, measured, o };
+}
+
+test("measure: venue and kind from venue.json, pdf relative to the paper, the file's sha256", async () => {
+  const { o } = setup();
+  const m = await measurePaper(PAPER, PDF, o);
+  assert.ok(m.ok);
+  assert.equal(m.value.facts.pdf, "paper.pdf");
+  assert.equal(
+    m.value.facts.pdf_sha256,
+    sha256Hex(new TextEncoder().encode(PDF_BYTES)),
+  );
+  assert.deepEqual(
+    [m.value.facts.venue, m.value.facts.kind],
+    ["agenticdev", "short"],
+  );
+  const over = await measurePaper(PAPER, PDF, { ...o, venue: "aisec" });
+  assert.equal(over.ok && over.value.facts.venue, "aisec");
+});
+
+test("measure, not measured: the facts are there with null geometry, and the measurer's reason is kept", async () => {
+  const { o, measured } = setup(NONE);
+  const m = await measurePaper(PAPER, PDF, o);
+  assert.ok(m.ok);
+  assert.equal(m.value.facts.geometry_source, null);
+  const g = m.value.geometry;
+  assert.equal(
+    g.kind === "unmeasured" ? whyNoGeometry(g) : "",
+    "perl is not installed",
+  );
+  // Guards: the measurer is handed the pages pdf.js read — the one read feeds both halves.
+  assert.deepEqual(measured, [[]]);
+});
+
+test("measure, measured: the geometry is in the file under its measurer's name", async () => {
+  const { o } = setup(MEASURED);
+  const m = await measurePaper(PAPER, PDF, o);
+  assert.ok(m.ok);
+  assert.equal(m.value.facts.geometry_source, "banal");
+  assert.deepEqual(
+    [m.value.facts.columns, m.value.facts.body_pages, m.value.facts.page_w_in],
+    [2, 3, 8.5],
+  );
+});
+
+test("a failed read is the one error line, and nothing is written", async () => {
+  const { o, files } = setup();
+  const before = files.map.size;
+  const m = await measurePaper(PAPER, PDF, {
+    ...o,
+    readPdf: async () => ({ ok: false, reason: "unreadable", detail: "boom" }),
+  });
+  assert.match(!m.ok ? m.error : "", /pdf\.js \(unreadable\): boom/);
+  assert.equal(files.map.size, before);
+});
+
+test("writeFactsFile: <paper>/_build/paper.facts.json holds exactly the document", async () => {
+  const { o, files } = setup();
+  const m = await measurePaper(PAPER, PDF, o);
+  assert.ok(m.ok);
+  const out = writeFactsFile(files, PAPER, m.value.facts);
+  assert.equal(out, factsPath(PAPER));
+  const text = new TextDecoder().decode(files.map.get(out));
+  assert.deepEqual(JSON.parse(text), m.value.facts);
+});
+
+test("declaredVenue: none without venue.json, none when it names no venue", () => {
+  assert.equal(declaredVenue(memoryFiles(), PAPER), null);
+  const files = memoryFiles({ [`${PAPER}/venue.json`]: '{"kind":"x"}' });
+  assert.equal(declaredVenue(files, PAPER), null);
+});

package/src/facts-file.ts

@@ -0,0 +1,241 @@
+/**
+ * THE ONE WRITER of `<paper>/_build/paper.facts.json` — what a finished PDF measures, as data a lint
+ * rule can judge. It judges nothing itself.
+ *
+ * Two callers, one function: `paperlint build` writes the facts right after a successful compile, and
+ * `skills/render-paper/extract-pdf-facts.mjs` is a thin command-line shim over the same
+ * `measurePaper` + `writeFactsFile` for PDFs paperlint did not build and for CI steps that name that script by path. Two
+ * writers would drift — one would learn a field the other does not — and the rules reading the file
+ * cannot tell which wrote it.
+ *
+ * ── WHERE THE FACTS COME FROM ──────────────────────────────────────────────────
+ * - pdf.js (`pdf-facts.ts`) — page count, the fonts the pages draw text with, the last page. Always.
+ * - a page-geometry measurer, through the `MeasureGeometry` port (`ports/measure-geometry.ts`) —
+ *   today banal (Eddie Kohler's page-geometry tool, the one HotCRP's format checker runs) — paper size,
+ *   columns, body and reference font sizes, page types. It runs on pdftohtml-style XML that paperlint
+ *   writes from the same pdf.js read (`adapters/banal/xml.ts`), so poppler is not needed (`adapters/banal/`).
+ *   OPTIONAL: banal is GPL and paperlint does not ship it — `paperlint toolchain` fetches it. Found ⇒ its fields
+ *   are filled and `geometry_source` says `banal`; not found ⇒ they are null and `geometry_source`
+ *   is null, so a rule can tell "not measured" from "measured as zero". Whether that is a failure is
+ *   the caller's policy: `extract-pdf-facts.mjs --strict` refuses to write such facts.
+ *
+ * ── SCHEMA 2 (2026-09-24) ───────────────────────────────────────────────────────
+ * Every schema-1 field keeps its name. The number changed because three meanings did, and a
+ * consumer that pins the schema must hear about it rather than read new meanings under the old
+ * number: fonts are the ones pages DRAW (pdf.js), not every font in a resource dictionary; Type 3
+ * fonts are all named `Type3`; `embedded` means a usable program is present, so a corrupted one is
+ * false. `pdf` is now relative to the PAPER directory, not to wherever the command ran.
+ *
+ * 🔴 STALENESS. The PDF is not committed, so neither are these facts: they live in `_build/` and
+ * carry `pdf_sha256`. A rule compares it with the PDF on disk and refuses facts about another build.
+ */
+import { join, relative, sep } from "node:path";
+import {
+  classifyLastPage,
+  popplerType,
+  type FontFact,
+  type LastPage,
+} from "./pdf-geometry.ts";
+import { describeFailure, type PdfFacts, type PdfReader } from "./pdf-facts.ts";
+import {
+  flatGeometry,
+  type FactsGeometryFields,
+  type Geometry,
+} from "./domain/geometry.ts";
+import { sha256Hex } from "./domain/sha256.ts";
+import type { MeasureGeometry } from "./ports/measure-geometry.ts";
+import type { AbsolutePath } from "./domain/paths.ts";
+import type { Files } from "./ports/files.ts";
+import { err, ok, type Result } from "./domain/result.ts";
+
+export const FACTS_SCHEMA = 2;
+export const FACTS_DIR = "_build";
+export const FACTS_FILE = "paper.facts.json";
+
+/** Where a paper's facts live. */
+export const factsPath = (paperDir: string): string =>
+  join(paperDir, FACTS_DIR, FACTS_FILE);
+
+/** The `venue.json` a paper declares: where it is submitted, as which kind, and where its PDF is. */
+export interface VenueDecl {
+  readonly venue: string;
+  readonly kind: string | null;
+  readonly pdf: string | null;
+}
+
+/**
+ * A path as the caller gave it. The `Files` adapter resolves a relative one against the process's
+ * cwd, which is what these callers have always meant; the brand is not a claim this code checked it.
+ */
+const at = (p: string): AbsolutePath => p as AbsolutePath;
+
+const str = (v: unknown): string | null => (typeof v === "string" ? v : null);
+
+/** A parsed `venue.json`, or null when it names no venue. */
+export function parseVenueDecl(json: unknown): VenueDecl | null {
+  const d = typeof json === "object" && json !== null ? json : {};
+  const field = (k: string) => str((d as Record<string, unknown>)[k]);
+  const venue = field("venue");
+  return venue ? { venue, kind: field("kind"), pdf: field("pdf") } : null;
+}
+
+/**
+ * The paper's `venue.json`, or null when there is none or it names no venue. The one reader of
+ * that file: the build, the facts writer and the shim all read it here.
+ */
+export function declaredVenue(
+  files: Files,
+  paperDir: string,
+): VenueDecl | null {
+  const bytes = files.readBytes(at(join(paperDir, "venue.json")));
+  return bytes === null
+    ? null
+    : parseVenueDecl(JSON.parse(new TextDecoder().decode(bytes)));
+}
+
+// ── the document ────────────────────────────────────────────────────────────────────────
+
+/** One font as the facts file spells it. `type` keeps poppler's spelling (`Type 3`). */
+export interface FontEntry {
+  readonly name: string;
+  readonly type: string;
+  readonly embedded: boolean;
+  readonly program: string;
+}
+
+export type LastPageEntry =
+  | {
+      readonly kind: "measured";
+      readonly columns_pt: readonly [number, number];
+    }
+  | { readonly kind: "stub"; readonly words: number }
+  | { readonly kind: "review"; readonly line_numbers: number };
+
+/** The facts file's content. */
+export type FactsDocument = {
+  readonly schema: typeof FACTS_SCHEMA;
+  readonly pdf: string;
+  readonly pdf_sha256: string;
+  readonly venue: string | null;
+  readonly kind: string | null;
+  readonly npages: number;
+  readonly fonts_source: "pdfjs-drawn";
+  readonly fonts: readonly FontEntry[];
+  readonly last_page: LastPageEntry;
+  /** Schema 1's field, kept: the two heights, or null when the last page is a stub or a review build. */
+  readonly last_page_cols_pt: readonly [number, number] | null;
+} & FactsGeometryFields;
+
+export function fontEntry(f: FontFact): FontEntry {
+  return {
+    name: f.name,
+    type: popplerType(f),
+    // A Type 3 font's glyphs are procedures inside the PDF: nothing is substituted, so it IS
+    // embedded (poppler says so too). Its defect is being Type 3, which `type` already names.
+    embedded: f.kind !== "not-embedded",
+    program: f.kind === "type3" ? "Type3" : f.program,
+  };
+}
+
+export function lastPageEntry(p: LastPage): LastPageEntry {
+  if (p.kind === "measured")
+    return { kind: "measured", columns_pt: [p.columns[0], p.columns[1]] };
+  if (p.kind === "review")
+    return { kind: "review", line_numbers: p.lineNumbers };
+  return { kind: "stub", words: p.words };
+}
+
+/** Everything the document is assembled from. */
+export interface FactsInput {
+  /** The PDF's path relative to the paper directory, with forward slashes. */
+  readonly pdf: string;
+  readonly sha: string;
+  readonly venue: string | null;
+  readonly kind: string | null;
+  readonly read: PdfFacts;
+  readonly geometry: Geometry;
+}
+
+/** Assemble the document. Pure. */
+export function factsDocument(i: FactsInput): FactsDocument {
+  const last = lastPageEntry(classifyLastPage(i.read.last));
+  return {
+    schema: FACTS_SCHEMA,
+    pdf: i.pdf,
+    pdf_sha256: i.sha,
+    venue: i.venue,
+    kind: i.kind,
+    npages: i.read.pages,
+    fonts_source: "pdfjs-drawn",
+    fonts:
+      i.read.fonts.kind === "drawn" ? i.read.fonts.list.map(fontEntry) : [],
+    last_page: last,
+    last_page_cols_pt: last.kind === "measured" ? last.columns_pt : null,
+    ...flatGeometry(i.geometry),
+  };
+}
+
+// ── measuring and writing ───────────────────────────────────────────────────────────────
+
+/** What `measurePaper` needs besides the paper and its PDF. */
+export interface MeasureOptions {
+  readonly readPdf: PdfReader;
+  readonly venue?: string | null;
+  readonly kind?: string | null;
+  /** The page-geometry measurer (banal, as the composition root wired it). */
+  readonly measure: MeasureGeometry;
+  /** Where the PDF and `venue.json` are read from. */
+  readonly files: Files;
+}
+
+/** The document, and the geometry it was projected from — a caller decides what "no geometry" means. */
+export interface Measured {
+  readonly facts: FactsDocument;
+  readonly geometry: Geometry;
+}
+
+const posix = (p: string): string => p.split(sep).join("/");
+
+/**
+ * Measure `pdf`: pdf.js always, banal when one is found. Writes nothing. The error is one line: the
+ * PDF could not be read. Whether a missing geometry is a failure is the CALLER's policy — the build
+ * writes the facts anyway, the shim's `--strict` refuses them.
+ */
+export async function measurePaper(
+  paperDir: string,
+  pdf: string,
+  o: MeasureOptions,
+): Promise<Result<Measured, string>> {
+  const r = await o.readPdf(pdf);
+  if (!r.ok) return err(describeFailure(r, pdf));
+  const bytes = o.files.readBytes(at(pdf));
+  if (bytes === null) return err(`${pdf}: gone after pdf.js read it`);
+  const geometry = o.measure.measure(r.facts.layout);
+  const decl = declaredVenue(o.files, paperDir);
+  const facts = factsDocument({
+    pdf: posix(relative(paperDir, pdf)),
+    sha: sha256Hex(bytes),
+    venue: o.venue ?? decl?.venue ?? null,
+    kind: o.kind ?? decl?.kind ?? null,
+    read: r.facts,
+    geometry,
+  });
+  return ok({ facts, geometry });
+}
+
+/**
+ * Write `<paperDir>/_build/paper.facts.json`, atomically. A caller that decides not to write leaves
+ * an earlier file as it was — its `pdf_sha256` no longer matches the PDF, so a rule refuses it.
+ */
+export function writeFactsFile(
+  files: Files,
+  paperDir: string,
+  facts: FactsDocument,
+): string {
+  const out = factsPath(paperDir);
+  files.writeAtomic(
+    at(out),
+    new TextEncoder().encode(`${JSON.stringify(facts, null, 2)}\n`),
+  );
+  return out;
+}