paperlint 3.2.0 → 4.0.0

package/src/cli.ts

@@ -30,6 +30,7 @@ import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { join, dirname, resolve, relative, basename, sep } from "node:path";
 import markdown from "@eslint/markdown";
+import { z } from "zod";
 // Types come from consumer.d.mts beside it.
 import {
   isMain,
@@ -112,6 +113,7 @@ import {
   shippedRuleIds,
   unknownKeys,
   type Parsed,
+  type ConfigBlock,
   type RuleBlock,
   type RuleEntry,
 } from "./rules-config.ts";
@@ -127,6 +129,7 @@ import reviewFrontmatter from "#eslint-rules/review-frontmatter";
 import siblingFrontmatter from "#eslint-rules/sibling-frontmatter";
 import pdfRules from "#eslint-rules/pdf-last-page-balance";
 import { messageOf } from "./domain/text.ts";
+import { isRecord } from "./domain/record.ts";
 
 /** The shipped venue presets, read from the package's venues directory — the one list. */
 const SHIPPED_VENUES = (): string[] => shippedPresets(packageVenuesDir());
@@ -220,7 +223,7 @@ settings — paperlint.json, at two levels, one schema. Both are optional.
 export function buildConfig(
   opts: PaperlintConfig = {},
   texLanguage: unknown,
-): unknown[] {
+): ConfigBlock[] {
   const paperRules = { ...researchQuestion.rules, ...typography.rules };
   // The reference rules judge `_build/references.json`, and only on `paper.tex`.
   const texPaperRules = {
@@ -238,7 +241,7 @@ export function buildConfig(
     languageOptions: { frontmatter: "yaml" },
   };
 
-  const cfg: unknown[] = [
+  const cfg: ConfigBlock[] = [
     // 🔴 THE PROJECT'S PAPER TEMPLATE IS NOT A PAPER. `paperlint new` reads `<papers>/.template/`, and
     // its files carry every marker a paper does. Flat config does NOT ignore dot-directories by
     // default (only `node_modules/` and `.git/`), so without this block `paperlint lint` would lint the
@@ -329,6 +332,21 @@ export function buildConfig(
   return cfg;
 }
 
+/**
+ * paperlint's blocks as ESLint's config type — the one place the two meet. ESLint types a plugin's
+ * rule as one that runs on ANY language; paperlint's run on the language they were written for, so
+ * no static proof that a block fits exists (`ConfigBlock`, rules-config.ts). ESLint checks every block
+ * when it loads the config and throws on one it cannot use; what is left to check here is that each
+ * is an object.
+ */
+const isEslintBlock = (b: unknown): b is Linter.Config =>
+  typeof b === "object" && b !== null;
+
+export function eslintConfig(blocks: readonly ConfigBlock[]): Linter.Config[] {
+  const loose: readonly unknown[] = blocks;
+  return loose.filter(isEslintBlock);
+}
+
 /**
  * The rule ids a consumer may name in `rules`: every rule paperlint's own config defines, read off that
  * config rather than listed again. `@eslint/markdown` is a dependency's plugin, not paperlint's.
@@ -357,9 +375,7 @@ export interface RulePlugin {
 export function rulePlugins(texLanguage?: unknown): Record<string, RulePlugin> {
   const out: Record<string, { rules: Record<string, unknown> }> = {};
   for (const block of buildConfig({}, texLanguage ?? { sentinel: "tex" }))
-    for (const [name, plugin] of Object.entries(
-      (block as { plugins?: Record<string, RulePlugin> }).plugins ?? {},
-    ))
+    for (const [name, plugin] of Object.entries(block.plugins ?? {}))
       if (plugin !== markdown)
         out[name] = { rules: { ...out[name]?.rules, ...plugin.rules } };
   if (out["tex"] && texLanguage !== undefined)
@@ -382,12 +398,10 @@ export function rulePlugins(texLanguage?: unknown): Record<string, RulePlugin> {
  * switched off in THIS run — `paperlint lint` still reports a directive that silences nothing.
  */
 export function rulesOff(texLanguage?: unknown): Linter.Config[] {
-  return [
+  return eslintConfig([
     {
       name: "paperlint/rules-off",
-      plugins: rulePlugins(texLanguage) as NonNullable<
-        Linter.Config["plugins"]
-      >,
+      plugins: rulePlugins(texLanguage),
       rules: Object.fromEntries([...SHIPPED_RULES].map((id) => [id, "off"])),
     },
     {
@@ -395,7 +409,7 @@ export function rulesOff(texLanguage?: unknown): Linter.Config[] {
       files: PAPER_FILE_PATTERNS,
       linterOptions: { reportUnusedDisableDirectives: "off" },
     },
-  ];
+  ]);
 }
 
 /** Whether a rule entry (`"error"`, `2`, `["warn", {…}]`) turns the rule on. */
@@ -412,7 +426,7 @@ export const OPTIONAL_RULES: ReadonlySet<string> = new Set(
   [...SHIPPED_RULES].filter(
     (id) =>
       !buildConfig({}, { sentinel: "tex language" }).some((b) =>
-        isOn((b as { rules?: Record<string, unknown> }).rules?.[id]),
+        isOn(b.rules?.[id]),
       ),
   ),
 );
@@ -429,8 +443,13 @@ export const OPTIONAL_RULES: ReadonlySet<string> = new Set(
  * papers a and b (#103) — a block that reaches a paper outside this run is not dead. A glob that
  * reaches no paper of the project at all still fails, from a subset as from the whole.
  */
+/** What `calculateConfigForFile` answers, read for its rules: undefined for a file outside ESLint's cwd or scope. */
+const ComputedConfig = z
+  .object({ rules: z.record(z.string(), z.unknown()).optional() })
+  .optional();
+
 export async function silentOptionalRules(
-  eslint: ESLint,
+  eslint: Pick<ESLint, "calculateConfigForFile">,
   files: readonly string[],
   opts: PaperlintConfig,
 ): Promise<string[]> {
@@ -444,8 +463,7 @@ export async function silentOptionalRules(
   const reached = new Set<string>();
   for (const f of new Set(files.filter((p) => basename(p) === MAIN))) {
     // Undefined for a file outside ESLint's cwd or scope: it reaches nothing.
-    const cfg = (await eslint.calculateConfigForFile(f)) as
-      { rules?: Record<string, unknown> } | undefined;
+    const cfg = ComputedConfig.parse(await eslint.calculateConfigForFile(f));
     for (const id of turnedOn) if (isOn(cfg?.rules?.[id])) reached.add(id);
   }
   return [...turnedOn].filter((id) => !reached.has(id));
@@ -543,6 +561,20 @@ const PAPER_FILE_PATTERNS: string[] = ownedPatterns(
   buildConfig({}, { sentinel: "tex language" }),
 );
 
+/** `structure` as `checkStructure` reads it: off, or lists of file names over the defaults. */
+const Names = z.array(z.string()).exactOptional();
+const Structure = z
+  .union([
+    z.literal(false),
+    z.object({
+      markers: Names,
+      require: Names,
+      requireOneOf: z.array(z.array(z.string())).exactOptional(),
+      ignore: Names,
+    }),
+  ])
+  .optional();
+
 /**
  * The root `paperlint.json` after the boundary: an unknown key is refused by name, the paper
  * defaults (`extends`, `kind`, `pdf`) are checked the way a paper's own are, and `rules` becomes
@@ -553,10 +585,9 @@ export function parseSettings(
   where: string,
   baseDir: string,
 ): Parsed<PaperlintConfig> {
-  if (typeof json !== "object" || json === null || Array.isArray(json))
+  if (!isRecord(json))
     return { ok: false, error: `${where}: must be a JSON object` };
-  const raw = json as Record<string, unknown>;
-  const opts = raw as PaperlintConfig;
+  const raw = json;
   const unknown = unknownKeys(raw);
   if (unknown.length > 0)
     return {
@@ -567,9 +598,22 @@ export function parseSettings(
     };
   const defaults = stringFields(raw);
   if (!defaults.ok) return { ok: false, error: `${where}: ${defaults.error}` };
+  const structure = Structure.safeParse(raw["structure"]);
+  if (!structure.success)
+    return {
+      ok: false,
+      error: `${where}: "structure" must be false, or an object whose markers, require and ignore are lists of file names and requireOneOf a list of such lists`,
+    };
   const rules = parseRuleBlocks(raw["rules"], where, SHIPPED_RULES, baseDir);
   if (!rules.ok) return rules;
-  return { ok: true, value: { ...opts, rules: rules.value } };
+  return {
+    ok: true,
+    value: {
+      papersDir: raw[PAPERS_DIR_FIELD],
+      structure: structure.data,
+      rules: rules.value,
+    },
+  };
 }
 
 /**
@@ -770,7 +814,7 @@ export function readConfig(
 
 /** The papers directory field of the settings, read by its one declared name; the default when absent. */
 export function papersDirOf(opts: PaperlintConfig): unknown {
-  const declared = (opts as Record<string, unknown>)[PAPERS_DIR_FIELD];
+  const declared = opts.papersDir;
   return declared === undefined ? DEFAULT_PAPERS_ROOT : declared;
 }
 
@@ -839,7 +883,12 @@ export function runHook(
       createRequire(import.meta.url).resolve(spec),
   }: {
     err?: typeof console.error;
-    run?: typeof spawnSync;
+    /** Runs the hook with the terminal's streams: `spawnSync` is one, and only its status is read. */
+    run?: (
+      file: string,
+      args: readonly string[],
+      options: { readonly stdio: "inherit" },
+    ) => { readonly status: number | null };
     resolve?: (spec: string) => string;
   } = {},
 ): number {
@@ -1466,7 +1515,7 @@ export async function run(
   const eslint = new ESLint({
     cwd: lintRoot(root, paths),
     overrideConfigFile: true,
-    overrideConfig: buildConfig(withPapers, texLanguage) as Linter.Config[],
+    overrideConfig: eslintConfig(buildConfig(withPapers, texLanguage)),
     fix: a.fix,
   });
 
@@ -1543,12 +1592,20 @@ async function firstUnownedFile(
  * is outside paperlint's scope (`all-matched-files-ignored` — a papers directory holding only
  * vendored scripts). Both mean "nothing was linted", which the caller reports itself.
  */
+/** What a thrown ESLint error says about itself; anything else thrown says nothing. */
+const EslintFailure = z
+  .object({
+    messageTemplate: z.string().optional(),
+    message: z.string().optional(),
+  })
+  .catch({});
+
 const isEmptySet = (e: unknown): boolean => {
-  const fail = e as { messageTemplate?: string; message?: string } | null;
+  const fail = EslintFailure.parse(e);
   return (
-    fail?.messageTemplate === "file-not-found" ||
-    fail?.messageTemplate === "all-matched-files-ignored" ||
-    /No files matching/i.test(String(fail?.message))
+    fail.messageTemplate === "file-not-found" ||
+    fail.messageTemplate === "all-matched-files-ignored" ||
+    /No files matching/i.test(String(fail.message))
   );
 };
 

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/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.ts

@@ -45,7 +45,7 @@ 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";
@@ -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. */
@@ -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][] = [