paperlint 3.2.0 → 4.1.0

package/src/doctor.test.ts

@@ -44,7 +44,7 @@ test("doctor: a settings file silent on papersDir, an occupied entry, an unreada
   const code = doctor({
     cwd: root,
     log: (s: string) => lines.push(s),
-    run: (() => ({ status: 0 })) as never,
+    run: () => ({ status: 0 }),
     cliPapers: join(root, "papers"),
     skillLinks: () => ({
       ok: true,

package/src/doctor.ts

@@ -37,6 +37,7 @@ import { PAPER_MARKERS } from "./build.ts";
 import { linkSkills, SKILLS_HOME, type LinkReport } from "./link-skills.ts";
 import { doctorHooks } from "./hooks-settings.ts";
 import { messageOf } from "./domain/text.ts";
+import { fieldOf } from "./domain/record.ts";
 
 export interface Program {
   readonly bin: string;
@@ -99,7 +100,17 @@ export const PROGRAMS: readonly Program[] = [
   },
 ];
 
-export const found = (bin: string, run = spawnSync): boolean =>
+/**
+ * Asks the shell whether a program is on PATH. `spawnSync` is one; a fake answers with a status
+ * alone, because a status is all `found` reads.
+ */
+export type ProgramProbe = (
+  file: string,
+  args: readonly string[],
+  options: { readonly shell: true; readonly stdio: "ignore" },
+) => { readonly status: number | null };
+
+export const found = (bin: string, run: ProgramProbe = spawnSync): boolean =>
   run("command", ["-v", bin], { shell: true, stdio: "ignore" }).status === 0;
 
 /** Lists a directory's entries; the disk by default, a test stages an unreadable child. */
@@ -176,9 +187,7 @@ function declarationVerdict(raw: string | null): {
       bad: 1,
     };
   }
-  const declared = (settings as Record<string, unknown> | null)?.[
-    PAPERS_DIR_FIELD
-  ];
+  const declared = fieldOf(settings, PAPERS_DIR_FIELD);
   return {
     lines: [
       declared === undefined
@@ -234,7 +243,7 @@ export interface DoctorOptions {
   cwd?: string;
   /** The project root the hooks are anchored to. Claude Code sets this; it defaults to `cwd`. */
   projectDir?: string;
-  run?: typeof spawnSync;
+  run?: ProgramProbe;
   /** The directory the CLI resolved from its own config, so both sides can be compared. */
   cliPapers?: string | null;
   /** Reads the skill links without writing any. Injected only so a test can fake the install. */

package/src/domain/paths.test.ts

@@ -0,0 +1,15 @@
+import assert from "node:assert/strict";
+import { test } from "vitest";
+import { absolutePath, joinPath } from "./paths.ts";
+
+test("absolutePath keeps an absolute path as it is", () => {
+  assert.equal(absolutePath("/a/b"), "/a/b");
+});
+
+test("absolutePath refuses a relative path instead of letting the process's cwd decide it", () => {
+  assert.throws(() => absolutePath("a/b"), /not an absolute path: a\/b/);
+});
+
+test("joinPath stays under its absolute base", () => {
+  assert.equal(joinPath(absolutePath("/a"), "b", "c"), "/a/b/c");
+});

package/src/domain/paths.ts

@@ -1,5 +1,24 @@
 /** Paths as the domain holds them. */
+import { isAbsolute, join } from "node:path";
 import type { Opaque } from "ts-essentials";
 
-/** An absolute path. Minted at the composition root (`abs`), so nothing inside resolves a cwd. */
+/**
+ * An absolute path. Minted by `absolutePath` (a checked string) or `joinPath` (an absolute base and
+ * segments) only, so nothing holding one has to ask whether it is relative.
+ */
 export type AbsolutePath = Opaque<string, "AbsolutePath">;
+
+// The brand's one owner: the predicate IS the check, so no assertion is needed to mint the type.
+const isAbsolutePath = (p: string): p is AbsolutePath => isAbsolute(p);
+
+/** A path the caller holds as text, checked where it becomes a value. A relative one throws. */
+export function absolutePath(p: string): AbsolutePath {
+  if (!isAbsolutePath(p)) throw new Error(`not an absolute path: ${p}`);
+  return p;
+}
+
+/** `segments` under `base`: absolute because `base` is. */
+export const joinPath = (
+  base: AbsolutePath,
+  ...segments: string[]
+): AbsolutePath => absolutePath(join(base, ...segments));

package/src/domain/ready.ts

@@ -0,0 +1,31 @@
+/** A program `paperlint toolchain` installed or found: present, verified, running. */
+
+// Not exported: a `Ready` carries this property, and the one way to write it is `ready` below.
+const READY = Symbol("Ready");
+
+/**
+ * Present, verified, running. BRANDED: a literal `{ where, fresh, verified }` is not a `Ready`, so
+ * only an installer's adapter — one minting call each (banal's is `ready` in
+ * `adapters/banal/index.ts`) — can make one, and a ready line cannot be printed without it.
+ */
+export interface Ready {
+  /** Where it is: the program's path or its bin directory. */
+  readonly where: string;
+  /** This run installed it. */
+  readonly fresh: boolean;
+  /** What was checked before calling it ready, as a person reads it. */
+  readonly verified: string;
+  readonly [READY]: true;
+}
+
+/** An installer's verdict that its program is ready. Called by an installer adapter, after its checks. */
+export const ready = (r: {
+  readonly where: string;
+  readonly fresh: boolean;
+  readonly verified: string;
+}): Ready => ({
+  where: r.where,
+  fresh: r.fresh,
+  verified: r.verified,
+  [READY]: true,
+});

package/src/domain/record.test.ts

@@ -0,0 +1,20 @@
+import assert from "node:assert/strict";
+import { test } from "vitest";
+import { fieldOf, isRecord, numbersOf } from "./record.ts";
+
+test("isRecord: an object, and not null, an array or a string", () => {
+  assert.deepEqual(
+    [isRecord({}), isRecord(null), isRecord([]), isRecord("x")],
+    [true, false, false, false],
+  );
+});
+
+test("fieldOf reads an own or inherited field of a record, and nothing of anything else", () => {
+  assert.equal(fieldOf({ a: 1 }, "a"), 1);
+  assert.equal(fieldOf(new TypeError("x"), "name"), "TypeError");
+  assert.equal(fieldOf("text", "length"), undefined);
+});
+
+test("numbersOf keeps numbers as they are", () => {
+  assert.deepEqual(numbersOf([1, -0.5, 0]), [1, -0.5, 0]);
+});

package/src/domain/record.ts

@@ -0,0 +1,12 @@
+/** Reading fields off a value typed `unknown` — a parsed JSON file, an object a library hands back. */
+
+/** Any non-null object that is not an array, readable by key. */
+export const isRecord = (v: unknown): v is Readonly<Record<string, unknown>> =>
+  typeof v === "object" && v !== null && !Array.isArray(v);
+
+/** `v[key]` when `v` is a record; undefined for anything else. Inherited fields count, as `.` reads them. */
+export const fieldOf = (v: unknown, key: string): unknown =>
+  isRecord(v) ? v[key] : undefined;
+
+/** A number array a library types as `any[]`, read as the numbers it holds. */
+export const numbersOf = (xs: readonly unknown[]): number[] => xs.map(Number);

package/src/domain/sha256.ts

@@ -9,13 +9,15 @@ import type { Opaque } from "ts-essentials";
 export type Sha256 = Opaque<string, "Sha256">;
 
 const SHA256 = /^[0-9a-f]{64}$/;
+// The brand's one owner: the predicate IS the check, so no assertion is needed to mint the type.
+const isSha256 = (s: string): s is Sha256 => SHA256.test(s);
 
 /** A sha256 written down as text — a pin, an option — checked where it is written, not where it is used. */
 export function parseSha256(s: string): Sha256 {
-  if (!SHA256.test(s))
+  if (!isSha256(s))
     throw new Error(`not a sha256 (64 lowercase hex digits): ${s}`);
-  return s as Sha256;
+  return s;
 }
 
 export const sha256Hex = (bytes: Uint8Array): Sha256 =>
-  createHash("sha256").update(bytes).digest("hex") as Sha256;
+  parseSha256(createHash("sha256").update(bytes).digest("hex"));

package/src/domain/tex-document.test.ts

@@ -0,0 +1,80 @@
+/** The values a LaTeX source is read into: a run's text and the span of a range inside it. */
+import { describe, expect, it } from "vitest";
+import {
+  collapse,
+  documentClassLine,
+  missingOptions,
+  runText,
+  spanIn,
+  venueClass,
+  type TextRun,
+} from "./tex-document.ts";
+
+// "ab" at 10, then " " at 20 (one character standing for a longer whitespace), then "cd" at 30.
+const RUN: TextRun = {
+  segments: [
+    { text: "ab", at: 10 },
+    { text: " ", at: 20 },
+    { text: "cd", at: 30 },
+  ],
+};
+
+describe("a text run", () => {
+  it("its text is its segments' text, in order", () => {
+    expect(runText(RUN)).toBe("ab cd");
+  });
+
+  it("spanIn: from the first character's offset to past the last's, across segments", () => {
+    expect(spanIn(RUN, 0, 2)).toEqual({ start: 10, end: 12 });
+    expect(spanIn(RUN, 1, 4)).toEqual({ start: 11, end: 31 });
+    expect(spanIn(RUN, 3, 5)).toEqual({ start: 30, end: 32 });
+  });
+
+  it("🔴 spanIn: an empty range, or one reaching outside the run, has no span — never {0, 0}", () => {
+    expect(spanIn(RUN, 2, 2)).toBe(null);
+    expect(spanIn(RUN, -1, 2)).toBe(null);
+    expect(spanIn(RUN, 3, 9)).toBe(null);
+    expect(spanIn(RUN, 9, 10)).toBe(null);
+  });
+});
+
+describe("a document class", () => {
+  it("documentClassLine writes it back; with no options, no brackets", () => {
+    expect(
+      documentClassLine({
+        cls: "IEEEtran",
+        options: ["conference", "compsoc"],
+      }),
+    ).toBe("\\documentclass[conference,compsoc]{IEEEtran}");
+    expect(documentClassLine({ cls: "article", options: [] })).toBe(
+      "\\documentclass{article}",
+    );
+  });
+
+  it("missingOptions: every option of the wanted class the paper lacks, in the wanted order", () => {
+    expect(
+      missingOptions(
+        { cls: "x", options: ["b"] },
+        { cls: "x", options: ["a", "b", "c"] },
+      ),
+    ).toEqual(["a", "c"]);
+  });
+
+  it("venueClass: another class is replaced; the same class gains the missing options, or is kept", () => {
+    const want = { cls: "IEEEtran", options: ["conference", "compsoc"] };
+    expect(venueClass({ cls: "article", options: ["11pt"] }, want)).toEqual({
+      kind: "replace",
+      by: want,
+    });
+    expect(
+      venueClass({ cls: "IEEEtran", options: ["review", "conference"] }, want),
+    ).toEqual({ kind: "add", options: ["compsoc"] });
+    expect(
+      venueClass({ cls: "IEEEtran", options: ["compsoc", "conference"] }, want),
+    ).toEqual({ kind: "keep" });
+  });
+
+  it("collapse: every run of whitespace, newlines included, and trims", () => {
+    expect(collapse("  LLM   Usage\n Statement ")).toBe("LLM Usage Statement");
+  });
+});

package/src/domain/tex-document.ts

@@ -0,0 +1,110 @@
+/**
+ * What a paper's LaTeX source says, in the paper's vocabulary — its document class, its sections,
+ * the text a reader sees — as values. No parser here: the LaTeX adapter (`src/adapters/latex/`)
+ * produces these, and the rules and `paperlint new` read them through the `LatexReader` port.
+ */
+
+/** A span of the source: `[start, end)` offsets. */
+export interface Span {
+  readonly start: number;
+  readonly end: number;
+}
+
+/** Where something stands in the source, or that the parser gave it no position. */
+export type Place =
+  { readonly kind: "at"; readonly span: Span } | { readonly kind: "unplaced" };
+
+/** Whitespace collapsed to single spaces and trimmed — how a title or a class name is compared. */
+export const collapse = (s: string): string =>
+  s.split(/\s+/u).filter(Boolean).join(" ");
+
+/** A LaTeX document class and the options it is loaded with, in source order. */
+export interface DocumentClass {
+  readonly cls: string;
+  readonly options: readonly string[];
+}
+
+/** A paper's `\documentclass`: none, one that names no class, or a class with its options. */
+export type ClassLine =
+  | { readonly kind: "missing" }
+  | { readonly kind: "empty"; readonly place: Place }
+  | ({ readonly kind: "class"; readonly place: Place } & DocumentClass);
+
+/** The options of `want` that `got` does not carry — every one, in `want`'s order. */
+export const missingOptions = (
+  got: DocumentClass,
+  want: DocumentClass,
+): readonly string[] => want.options.filter((o) => !got.options.includes(o));
+
+/** What a paper's class line needs to satisfy a venue: nothing, options added, or the venue's line. */
+export type ClassChange =
+  | { readonly kind: "keep" }
+  | { readonly kind: "add"; readonly options: readonly string[] }
+  | { readonly kind: "replace"; readonly by: DocumentClass };
+
+/**
+ * What a paper's class must change to satisfy a venue's `want`: another class is replaced by `want`;
+ * the same class keeps its options and gains the ones it lacks, in `want`'s order. This decides WHAT
+ * changes; writing it into a source is the LaTeX adapter's.
+ */
+export function venueClass(
+  have: DocumentClass,
+  want: DocumentClass,
+): ClassChange {
+  if (have.cls !== want.cls) return { kind: "replace", by: want };
+  const missing = missingOptions(have, want);
+  return missing.length === 0
+    ? { kind: "keep" }
+    : { kind: "add", options: missing };
+}
+
+/** A class as a `\documentclass` line, for a message and for the line `paperlint new` writes. */
+export const documentClassLine = (d: DocumentClass): string =>
+  `\\documentclass${d.options.length > 0 ? `[${d.options.join(",")}]` : ""}{${d.cls}}`;
+
+/** One `\section` or `\section*`, its title's text with whitespace collapsed. */
+export interface Heading {
+  readonly title: string;
+  readonly place: Place;
+}
+
+/** The document's sections in source order, where its back matter begins, and where it ends. */
+export interface Outline {
+  readonly sections: readonly Heading[];
+  /** The first `\appendix` or bibliography, or null: sections from here on are not body. */
+  readonly backMatter: number | null;
+  /** Where `\end{document}` stands, or null when there is no document environment. */
+  readonly end: number | null;
+}
+
+/** Text a reader sees, copied from one place: `text[i]` stands at source offset `at + i`. */
+export interface Segment {
+  readonly text: string;
+  readonly at: number;
+}
+
+/** A run of rendered text: contiguous segments, never empty. */
+export interface TextRun {
+  readonly segments: readonly [Segment, ...Segment[]];
+}
+
+/** The run's text. */
+export const runText = (run: TextRun): string =>
+  run.segments.map((s) => s.text).join("");
+
+/** The source offset of the `i`-th character of the text these segments make, or null outside it. */
+function offsetIn(segments: readonly Segment[], i: number): number | null {
+  const [s, ...rest] = segments;
+  if (s === undefined || i < 0) return null;
+  return i < s.text.length ? s.at + i : offsetIn(rest, i - s.text.length);
+}
+
+/**
+ * The source span of `runText(run).slice(from, to)`: from its first character to past its last.
+ * Null when the range is empty or reaches outside the run — never an invented position.
+ */
+export function spanIn(run: TextRun, from: number, to: number): Span | null {
+  const start = offsetIn(run.segments, from);
+  const last = to > from ? offsetIn(run.segments, to - 1) : null;
+  return start === null || last === null ? null : { start, end: last + 1 };
+}

package/src/engine.harness.mjs

@@ -5,7 +5,7 @@
  *   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.ts`.
+ * All pure or port-driven: no TeX needed. The real-TeX half is `test/e2e/tex/build.e2e.ts`.
  */
 import {
   chmodSync,

package/src/engine.ts

@@ -26,8 +26,36 @@ import { basename, delimiter, join } from "node:path";
 import type { TexRequirements } from "./tex-requirements.ts";
 import { printed } from "./domain/text.ts";
 
-/** A process runner with `spawnSync`'s shape — the port the harness replaces. */
-export type Runner = typeof spawnSync;
+/** The options paperlint hands a process runner: text out, both streams captured. */
+export interface RunOptions {
+  readonly encoding: "utf8" | "latin1";
+  readonly stdio: ["ignore", "pipe", "pipe"];
+  readonly env?: NodeJS.ProcessEnv;
+  readonly cwd?: string;
+  readonly maxBuffer?: number;
+  readonly timeout?: number;
+}
+
+/**
+ * What paperlint reads of a finished process. `spawnSync`'s result has this shape; a fake needs
+ * nothing more. Both streams are optional: they are `undefined` when the spawn itself failed.
+ */
+export interface RunResult {
+  readonly status: number | null;
+  readonly stdout?: string;
+  readonly stderr?: string;
+  readonly error?: Error;
+}
+
+/**
+ * A process runner: `spawnSync`'s text overload, narrowed to what paperlint passes and reads — the
+ * port the harness replaces. `spawnSync` itself is one.
+ */
+export type Runner = (
+  file: string,
+  args: readonly string[],
+  options: RunOptions,
+) => RunResult;
 
 /** One TeX Live and what it lacks for the papers at hand. */
 export interface TreeProbe {

package/src/facts-file.test.ts

@@ -5,12 +5,12 @@
  * 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.ts`'s job; banal as the measurer is `adapters/banal/index.test.ts`, and the
- * real banal is `test/e2e/banal.ts`.
+ * real banal is `test/e2e/tex/banal.e2e.ts`.
  */
 import assert from "node:assert/strict";
 import { readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { packageVenuesDir } from "../skills/paper-pipeline/scripts/consumer.mjs";
+import { presetsDir } from "./package-dirs.ts";
 import { test } from "vitest";
 import { memoryFiles } from "./adapters/memory/index.ts";
 import {
@@ -154,12 +154,9 @@ const good: PdfReader = () =>
   });
 /** The shipped presets at their real paths: `extends` resolves through the same Files port. */
 const SHIPPED_PRESETS = Object.fromEntries(
-  readdirSync(packageVenuesDir())
+  readdirSync(presetsDir())
     .filter((f) => /\.jsonc?$/.test(f))
-    .map((f) => [
-      join(packageVenuesDir(), f),
-      readFileSync(join(packageVenuesDir(), f)),
-    ]),
+    .map((f) => [join(presetsDir(), f), readFileSync(join(presetsDir(), f))]),
 );
 
 /** Options over in-memory files: the PDF and paperlint.json on "disk", a measurer answering `geometry`. */

package/src/facts-file.ts

@@ -45,11 +45,11 @@ import {
 } from "./domain/geometry.ts";
 import { parseSha256, sha256Hex, type Sha256 } from "./domain/sha256.ts";
 import type { MeasureGeometry } from "./ports/measure-geometry.ts";
-import type { AbsolutePath } from "./domain/paths.ts";
+import { callerPath } from "./caller-path.ts";
 import type { Files } from "./ports/files.ts";
 import { err, ok, type Result } from "./domain/result.ts";
 import { paperPreset, paperPresetProblem } from "./presets.ts";
-import { packageVenuesDir } from "../skills/paper-pipeline/scripts/consumer.mjs";
+import { presetsDir } from "./package-dirs.ts";
 import { messageOf } from "./domain/text.ts";
 
 export const FACTS_SCHEMA = 2;
@@ -60,12 +60,6 @@ export const FACTS_FILE = "paper.facts.json";
 export const factsPath = (paperDir: string): string =>
   join(paperDir, FACTS_DIR, FACTS_FILE);
 
-/**
- * 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;
-
 /** What the facts need from a paper's `paperlint.json`: its venue's label, its kind, where its PDF is. */
 export interface VenueDecl {
   /** The venue preset's display label (`agenticdev`), or null when the paper extends none. */
@@ -82,7 +76,7 @@ export interface VenueDecl {
 export function declaredVenue(
   files: Files,
   paperDir: string,
-  venuesDir: string = packageVenuesDir(),
+  venuesDir: string = presetsDir(),
 ): VenueDecl | null {
   const p = paperPreset(paperDir, { files, venuesDir });
   const problem = paperPresetProblem(paperDir, p);
@@ -213,7 +207,7 @@ export async function measurePaper(
 ): 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));
+  const bytes = o.files.readBytes(callerPath(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);
@@ -239,7 +233,7 @@ export function writeFactsFile(
 ): string {
   const out = factsPath(paperDir);
   files.writeAtomic(
-    at(out),
+    callerPath(out),
     new TextEncoder().encode(`${JSON.stringify(facts, null, 2)}\n`),
   );
   return out;
@@ -288,6 +282,34 @@ const MAYBE_NUMBERS = [
 ] as const;
 const NUMBERS = ["body_pages", "ref_pages", "appendix_pages"] as const;
 
+/** The geometry columns as the file holds them once checked. */
+type GeometryColumns = {
+  readonly [K in (typeof MAYBE_NUMBERS)[number]]: number | null;
+} & { readonly [K in (typeof NUMBERS)[number]]: number } & {
+  readonly pages_by_type: Readonly<Record<string, number>>;
+};
+
+const isCounts = (v: unknown): v is Readonly<Record<string, number>> =>
+  isRecord(v) && Object.values(v).every(isNum);
+
+/** Every geometry column has its type: the check the type claims, and nothing else. */
+const hasGeometryColumns = (
+  d: Readonly<Record<string, unknown>>,
+): d is Readonly<Record<string, unknown>> & GeometryColumns =>
+  MAYBE_NUMBERS.every((k) => numOrNull(d[k])) &&
+  NUMBERS.every((k) => isNum(d[k])) &&
+  isCounts(d["pages_by_type"]);
+
+/** Which geometry column is wrong, for a record `hasGeometryColumns` refused. */
+function geometryError(d: Readonly<Record<string, unknown>>): string {
+  const bad =
+    MAYBE_NUMBERS.find((k) => !numOrNull(d[k])) ??
+    NUMBERS.find((k) => !isNum(d[k]));
+  return bad
+    ? `\`${bad}\` is not a number`
+    : "`pages_by_type` is not an object of page counts";
+}
+
 /** The geometry columns when a measurer ran; the shape error otherwise. */
 function geometryOf(
   d: Readonly<Record<string, unknown>>,
@@ -295,24 +317,17 @@ function geometryOf(
   if (d["geometry_source"] === null) return ok(null);
   if (typeof d["geometry_source"] !== "string")
     return err("`geometry_source` is neither a measurer's name nor null");
-  const bad =
-    MAYBE_NUMBERS.find((k) => !numOrNull(d[k])) ??
-    NUMBERS.find((k) => !isNum(d[k]));
-  if (bad) return err(`\`${bad}\` is not a number`);
-  const pagesByType = d["pages_by_type"];
-  if (!isRecord(pagesByType) || !Object.values(pagesByType).every(isNum))
-    return err("`pages_by_type` is not an object of page counts");
-  const n = (k: (typeof MAYBE_NUMBERS)[number]) => d[k] as number | null;
+  if (!hasGeometryColumns(d)) return err(geometryError(d));
   return ok({
-    page_w_in: n("page_w_in"),
-    page_h_in: n("page_h_in"),
-    columns: n("columns"),
-    body_pt: n("body_pt"),
-    ref_pt: n("ref_pt"),
-    body_pages: d["body_pages"] as number,
-    ref_pages: d["ref_pages"] as number,
-    appendix_pages: d["appendix_pages"] as number,
-    pages_by_type: pagesByType as Readonly<Record<string, number>>,
+    page_w_in: d.page_w_in,
+    page_h_in: d.page_h_in,
+    columns: d.columns,
+    body_pt: d.body_pt,
+    ref_pt: d.ref_pt,
+    body_pages: d.body_pages,
+    ref_pages: d.ref_pages,
+    appendix_pages: d.appendix_pages,
+    pages_by_type: d.pages_by_type,
   });
 }
 
@@ -348,7 +363,7 @@ export function parseFactsText(text: string): Result<ReadFacts, FactsProblem> {
   if (!artifact.ok) return err({ kind: "broken", why: artifact.error });
   const rawFonts = d["fonts"];
   const fonts = Array.isArray(rawFonts) ? rawFonts.map(fontOf) : null;
-  if (fonts === null || fonts.some((f) => f === null))
+  if (fonts === null || !fonts.every((f) => f !== null))
     return err({
       kind: "broken",
       why: "`fonts` is not a list of { name, type, embedded, program }",
@@ -357,7 +372,7 @@ export function parseFactsText(text: string): Result<ReadFacts, FactsProblem> {
   if (!geometry.ok) return err({ kind: "broken", why: geometry.error });
   return ok({
     ...artifact.value,
-    fonts: fonts as FontEntry[],
+    fonts,
     geometry: geometry.value,
   });
 }

package/src/hooks-settings.harness.ts

@@ -118,6 +118,23 @@ try {
     threw,
   );
 
+  const malformed = join(work, "malformed-hooks.json");
+  writeFileSync(
+    malformed,
+    '{"hooks":{"PreToolUse":[{"hooks":[{"type":"command"}]}]}}',
+  );
+  let why = "";
+  try {
+    shippedWiring(malformed);
+  } catch (e) {
+    why = e instanceof Error ? e.message : String(e);
+  }
+  check(
+    "a wiring file whose `hooks` is not Claude Code's shape THROWS, naming the shape",
+    why.startsWith(`${malformed}: "hooks" is not a map of event`),
+    why,
+  );
+
   // ── which spelling runs which hook ─────────────────────────────────────────────────────
   const ours = `node "\${CLAUDE_PROJECT_DIR}/${MANAGED_BY}" hook paper-edit-guard`;
   const cases: [string, { name: string; ours: boolean } | null][] = [