paperlint 3.1.3 → 4.0.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/result.test.ts

@@ -3,7 +3,7 @@ import { test } from "vitest";
 import { andThen, err, map, match, ok, type Result } from "./result.ts";
 
 const half = (n: number): Result<number, string> =>
-  n % 2 === 0 ? ok(n / 2) : err(`${n} is odd`);
+  n % 2 === 0 ? ok(n / 2) : err(`${String(n)} is odd`);
 
 test("map and andThen run on ok and pass an error through untouched", () => {
   assert.deepEqual(
@@ -24,7 +24,7 @@ test("map and andThen run on ok and pass an error through untouched", () => {
 
 test("match picks the branch by `ok`", () => {
   const say = (r: Result<number, string>) =>
-    match(r, { ok: (n) => `got ${n}`, err: (e) => `no: ${e}` });
+    match(r, { ok: (n) => `got ${String(n)}`, err: (e) => `no: ${e}` });
   assert.equal(say(half(4)), "got 2");
   assert.equal(say(half(5)), "no: 5 is odd");
 });

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

@@ -0,0 +1,32 @@
+import assert from "node:assert/strict";
+import { test } from "vitest";
+import { codeOf, firstLine, messageOf, printed } from "./text.ts";
+
+test("messageOf: an Error's message, and anything else thrown as its text", () => {
+  assert.equal(messageOf(new Error("boom")), "boom");
+  // `throw "x"` and `throw 3` are legal JavaScript; `(e as Error).message` read them as undefined.
+  assert.equal(messageOf("plain string"), "plain string");
+  assert.equal(messageOf(3), "3");
+});
+
+test("codeOf: a string `code` only", () => {
+  assert.equal(
+    codeOf(Object.assign(new Error("x"), { code: "ENOENT" })),
+    "ENOENT",
+  );
+  assert.equal(codeOf(new Error("no code")), undefined);
+  assert.equal(codeOf({ code: 3 }), undefined);
+  assert.equal(codeOf(null), undefined);
+  assert.equal(codeOf("ENOENT"), undefined);
+});
+
+test("printed: a stream a failed spawn left undefined reads as empty text", () => {
+  assert.equal(printed(undefined), "");
+  assert.equal(printed(null), "");
+  assert.equal(printed("out"), "out");
+});
+
+test("firstLine: the first non-blank line, trimmed", () => {
+  assert.equal(firstLine("\n  \n  first \nsecond"), "first");
+  assert.equal(firstLine(""), "");
+});

package/src/domain/text.ts

@@ -9,3 +9,26 @@ export const firstLine = (s: string): string =>
     .split("\n")
     .map((l) => l.trim())
     .find(Boolean) ?? "";
+
+/**
+ * What a process printed on one stream, as text. Node types `spawnSync(…, { encoding })`'s
+ * `stdout`/`stderr` as `string`, but both are `undefined` when the spawn itself failed (measured:
+ * `spawnSync("no-such-program", [], { encoding: "utf8" }).stdout` is `undefined`). The parameter
+ * takes the stream as it really arrives, so the fallback guards a real case instead of reading
+ * as dead code against a type that lies.
+ */
+export const printed = (stream: string | null | undefined): string =>
+  stream ?? "";
+
+/** What a caught value says: an `Error`'s message, anything else as text (`catch` gets `unknown`). */
+export const messageOf = (e: unknown): string =>
+  e instanceof Error ? e.message : String(e);
+
+/** The `code` a Node error carries (`ENOENT`, `EACCES`, …), when it carries a string one. */
+export const codeOf = (e: unknown): string | undefined =>
+  typeof e === "object" &&
+  e !== null &&
+  "code" in e &&
+  typeof e.code === "string"
+    ? e.code
+    : undefined;

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.mjs`.
+ * All pure or port-driven: no TeX needed. The real-TeX half is `test/e2e/build.ts`.
  */
 import {
   chmodSync,
@@ -18,7 +18,7 @@ import {
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { createChecker } from "../lib/check.mjs";
+import { createChecker } from "../lib/check.ts";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const {

package/src/engine.ts

@@ -24,9 +24,38 @@ import { spawnSync } from "node:child_process";
 import { accessSync, constants, statSync } from "node:fs";
 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 {
@@ -161,7 +190,7 @@ export function probeTree(
     stdio: ["ignore", "pipe", "pipe"],
   });
   if (r.error) return Object.keys(packages).sort();
-  return missingPackages(packages, String(r.stdout ?? ""));
+  return missingPackages(packages, printed(r.stdout));
 }
 
 /**
@@ -181,7 +210,7 @@ export function missingDependencies(
     stdio: ["ignore", "pipe", "pipe"],
   });
   if (r.error) return [];
-  const lines = String(r.stdout ?? "").split("\n");
+  const lines = printed(r.stdout).split("\n");
   const start = lines.findIndex(
     (l) => l.trim() === "DEPENDS WITHOUT PACKAGES:",
   );
@@ -193,7 +222,7 @@ export function missingDependencies(
   return [
     ...new Set(
       (end < 0 ? section : section.slice(0, end)).map((l) =>
-        l.split(" in: ")[0]!.trim(),
+        l.replace(/ in: [\s\S]*/, "").trim(),
       ),
     ),
   ].sort();

package/src/facts-file.test.ts

@@ -4,8 +4,8 @@
  * 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`.
+ * `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`.
  */
 import assert from "node:assert/strict";
 import { readdirSync, readFileSync } from "node:fs";
@@ -147,10 +147,11 @@ test("🔴 geometry_source and the nine columns come from ONE branch", () => {
 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: [] },
-});
+const good: PdfReader = () =>
+  Promise.resolve({
+    ok: true,
+    facts: { pages: 2, fonts: FONTS, last: lastPage(60, 60), layout: [] },
+  });
 /** The shipped presets at their real paths: `extends` resolves through the same Files port. */
 const SHIPPED_PRESETS = Object.fromEntries(
   readdirSync(packageVenuesDir())
@@ -232,7 +233,8 @@ test("a failed read is the one error line, and nothing is written", async () =>
   const before = files.map.size;
   const m = await measurePaper(PAPER, PDF, {
     ...o,
-    readPdf: async () => ({ ok: false, reason: "unreadable", detail: "boom" }),
+    readPdf: () =>
+      Promise.resolve({ ok: false, reason: "unreadable", detail: "boom" }),
   });
   assert.match(!m.ok ? m.error : "", /pdf\.js \(unreadable\): boom/);
   assert.equal(files.map.size, before);

package/src/facts-file.ts

@@ -45,11 +45,12 @@ 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 { messageOf } from "./domain/text.ts";
 
 export const FACTS_SCHEMA = 2;
 export const FACTS_DIR = "_build";
@@ -59,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. */
@@ -212,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);
@@ -238,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;
@@ -287,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>>,
@@ -294,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,
   });
 }
 
@@ -338,7 +354,7 @@ export function parseFactsText(text: string): Result<ReadFacts, FactsProblem> {
   try {
     d = JSON.parse(text);
   } catch (e) {
-    return err({ kind: "broken", why: `not JSON (${(e as Error).message})` });
+    return err({ kind: "broken", why: `not JSON (${messageOf(e)})` });
   }
   if (!isRecord(d)) return err({ kind: "broken", why: "not a JSON object" });
   if (d["schema"] !== FACTS_SCHEMA)
@@ -347,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 }",
@@ -356,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.mjs → hooks-settings.harness.ts}

@@ -25,11 +25,21 @@ import {
   writeFileSync,
 } from "node:fs";
 import { tmpdir } from "node:os";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-import { createChecker } from "../lib/check.mjs";
+import { join } from "node:path";
+import { createChecker } from "../lib/check.ts";
+import { isDeepStrictEqual } from "node:util";
+import { z } from "zod";
+import type { Merge, Settings } from "./hooks-settings.ts";
+
+/** Settings with a PreToolUse entry — the shape the "wired twice" case edits. */
+const PreToolUseSettings = z.looseObject({
+  hooks: z.looseObject({
+    PreToolUse: z.array(
+      z.looseObject({ hooks: z.array(z.looseObject({ command: z.string() })) }),
+    ),
+  }),
+});
 
-const HERE = dirname(fileURLToPath(import.meta.url));
 const {
   hookRun,
   shippedWiring,
@@ -39,16 +49,17 @@ const {
   readSettings,
   MANAGED_BY,
   SETTINGS_PATH,
-} = await import(join(HERE, "hooks-settings.ts"));
+} = await import("./hooks-settings.ts");
 const { claudeCodeHookProtocol } = await import("vigiles/claude-code");
-const merge = (e, c, m) => claudeCodeHookProtocol.mergeRegistrations(e, c, m);
+const merge: Merge = (e, c, m) =>
+  claudeCodeHookProtocol.mergeRegistrations(e, c, m);
 
 const check = createChecker();
 
 // ── the contract with vigiles, checked before anything relies on it ──────────────────────
 check(
   "🔴 vigiles/claude-code exports claudeCodeHookProtocol.mergeRegistrations — the merge init calls",
-  typeof claudeCodeHookProtocol?.mergeRegistrations === "function",
+  typeof claudeCodeHookProtocol.mergeRegistrations === "function",
 );
 
 // ── the one source: plugin/hooks/hooks.json ─────────────────────────────────────────────
@@ -82,7 +93,7 @@ check(
   try {
     shippedWiring(file);
   } catch (e) {
-    thrown = e.message;
+    thrown = e instanceof Error ? e.message : String(e);
   }
   rmSync(file);
   check(
@@ -107,9 +118,26 @@ 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 = [
+  const cases: [string, { name: string; ours: boolean } | null][] = [
     [ours, { name: "paper-edit-guard", ours: true }],
     [
       `node "$CLAUDE_PROJECT_DIR/${MANAGED_BY}" hook paper-status-gates`,
@@ -140,7 +168,7 @@ try {
       JSON.stringify(hookRun(cmd)) === JSON.stringify(want),
     );
 
-  const project = (name, settings) => {
+  const project = (name: string, settings?: Settings | string) => {
     const dir = join(work, name);
     mkdirSync(join(dir, ".claude"), { recursive: true });
     if (settings !== undefined)
@@ -152,14 +180,19 @@ try {
       );
     return dir;
   };
-  const text = (dir) => readFileSync(join(dir, SETTINGS_PATH), "utf8");
+  const text = (dir: string) => readFileSync(join(dir, SETTINGS_PATH), "utf8");
+  const settingsIn = (dir: string): Settings => {
+    const r = readSettings(dir);
+    if (r.status === "unparsable") throw new Error(r.reason);
+    return r.settings;
+  };
 
   // ── a fresh project ────────────────────────────────────────────────────────────────────
   {
     const dir = join(work, "fresh");
     mkdirSync(dir);
     const r = wireHooks(dir, merge, wiring);
-    const s = JSON.parse(text(dir));
+    const s = settingsIn(dir);
     check(
       "no settings file → it is created with the three hooks",
       r.status === "written" &&
@@ -189,14 +222,14 @@ try {
       },
     });
     wireHooks(dir, merge, wiring);
-    const s = JSON.parse(text(dir));
+    const s = settingsIn(dir);
     check(
       "🔴 the user's own hook in the SAME matcher survives",
       JSON.stringify(s).includes("node my-own-lint.mjs"),
     );
     check(
       "and every other key is kept (permissions)",
-      s.permissions?.allow?.[0] === "Bash(ls:*)",
+      isDeepStrictEqual(s["permissions"], { allow: ["Bash(ls:*)"] }),
     );
     check(
       "and ours are there, once each",
@@ -243,11 +276,14 @@ try {
     );
     check(
       "the report names the hook and the command it found",
-      r.found.length === 1 && r.found[0].name === "paper-edit-guard",
+      r.status === "foreign" &&
+        r.found.length === 1 &&
+        r.found[0]?.name === "paper-edit-guard",
     );
     check(
       "and names the hooks that are not wired in ANY form",
-      r.missing.join() === "paper-skills-nudge,paper-status-gates",
+      r.status === "foreign" &&
+        r.missing.join() === "paper-skills-nudge,paper-status-gates",
     );
     // The control: without the check, vigiles' merge WOULD add a second copy. This is the
     // reason the check exists, measured rather than asserted.
@@ -257,7 +293,7 @@ try {
     );
     check(
       "(control) vigiles' merge alone would wire paper-edit-guard TWICE here",
-      c.ours === 1 && c.other === 1,
+      c?.ours === 1 && c.other === 1,
     );
   }
 
@@ -276,7 +312,7 @@ try {
   }
 
   // ── doctor's section ───────────────────────────────────────────────────────────────────
-  const doc = (settings) => {
+  const doc = (settings?: Settings | string) => {
     const dir = project(`doc-${String(check.count)}`, settings);
     return doctorHooks(dir, wiring).join("\n");
   };
@@ -291,8 +327,8 @@ try {
     "nothing wired → ⚠ not wired, with the remedy",
     /⚠ not wired — none of the 3 hooks/.test(doc({})),
   );
-  const twice = JSON.parse(JSON.stringify(wiredOnce));
-  twice.hooks.PreToolUse[0].hooks.push({
+  const twice = PreToolUseSettings.parse(structuredClone(wiredOnce));
+  twice.hooks.PreToolUse[0]?.hooks.push({
     type: "command",
     command: "npx paperlint hook paper-edit-guard",
   });

package/src/hooks-settings.ts

@@ -30,6 +30,8 @@ import {
   BIN_FILE,
   PACKAGE_NAME,
 } from "../skills/paper-pipeline/scripts/consumer.mjs";
+import { messageOf } from "./domain/text.ts";
+import { fieldOf, isRecord } from "./domain/record.ts";
 
 /** The committed, shared settings file — husky's `.husky/` analogue, except git carries it. */
 export const SETTINGS_PATH = join(".claude", "settings.json");
@@ -133,17 +135,42 @@ export function hookRun(command: string): {
 export function commandsIn(
   settings: Settings,
 ): { readonly event: string; readonly command: string }[] {
-  const hooks = settings["hooks"];
-  if (!hooks || typeof hooks !== "object") return [];
   const out: { event: string; command: string }[] = [];
-  for (const [event, entries] of Object.entries(hooks as HooksMap))
-    for (const entry of Array.isArray(entries) ? entries : [])
-      for (const h of Array.isArray(entry?.hooks) ? entry.hooks : [])
-        if (typeof h?.command === "string")
-          out.push({ event, command: h.command });
+  for (const [event, entries] of Object.entries(prop(settings["hooks"]) ?? {}))
+    for (const entry of listOf(entries))
+      for (const h of listOf(prop(entry)?.["hooks"])) {
+        const command = prop(h)?.["command"];
+        if (typeof command === "string") out.push({ event, command });
+      }
   return out;
 }
 
+/** The settings file is the user's: any level may be missing or of the wrong kind. */
+const listOf = (v: unknown): readonly unknown[] => (Array.isArray(v) ? v : []);
+const prop = (v: unknown): Readonly<Record<string, unknown>> | undefined =>
+  typeof v === "object" && v !== null
+    ? Object.fromEntries(Object.entries(v))
+    : undefined;
+
+const isHookCommand = (v: unknown): v is HookCommand =>
+  typeof fieldOf(v, "type") === "string" &&
+  typeof fieldOf(v, "command") === "string";
+
+function isHookEntry(v: unknown): v is HookEntry {
+  const matcher = fieldOf(v, "matcher");
+  const hooks = fieldOf(v, "hooks");
+  return (
+    ["undefined", "string"].includes(typeof matcher) &&
+    Array.isArray(hooks) &&
+    hooks.every(isHookCommand)
+  );
+}
+
+/** A `hooks` map of the shape Claude Code reads: event → entries → commands. */
+const isHooksMap = (v: unknown): v is HooksMap =>
+  isRecord(v) &&
+  Object.values(v).every((es) => Array.isArray(es) && es.every(isHookEntry));
+
 export interface Wiring {
   readonly compiled: HooksMap;
   /** Derived from the commands, in order. Never empty — an empty set throws. */
@@ -155,8 +182,12 @@ export interface Wiring {
  * check that silently wired nothing would report "✓ wired" over an empty set.
  */
 export function shippedWiring(file: string = WIRING_FILE): Wiring {
-  const json = JSON.parse(readFileSync(file, "utf8")) as { hooks?: HooksMap };
-  const compiled = json.hooks ?? {};
+  const json: unknown = JSON.parse(readFileSync(file, "utf8"));
+  const compiled = fieldOf(json, "hooks") ?? {};
+  if (!isHooksMap(compiled))
+    throw new Error(
+      `${file}: "hooks" is not a map of event → [{ matcher?, hooks: [{ type, command }] }]`,
+    );
   const names = commandsIn({ hooks: compiled })
     .map((c) => hookRun(c.command)?.name)
     .filter((n): n is string => typeof n === "string");
@@ -195,7 +226,11 @@ export function wiredCounts(
 const total = (c: HookCount): number => c.ours + c.other;
 
 export type SettingsRead =
-  | { readonly status: "absent"; readonly path: string; readonly settings: {} }
+  | {
+      readonly status: "absent";
+      readonly path: string;
+      readonly settings: Settings;
+    }
   | {
       readonly status: "read";
       readonly path: string;
@@ -214,11 +249,11 @@ export function readSettings(root: string): SettingsRead {
   const raw = readFileSync(path, "utf8");
   try {
     const parsed: unknown = JSON.parse(raw);
-    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+    if (!isRecord(parsed))
       return { status: "unparsable", path, reason: "not a JSON object" };
-    return { status: "read", path, settings: parsed as Settings, raw };
+    return { status: "read", path, settings: parsed, raw };
   } catch (e) {
-    return { status: "unparsable", path, reason: (e as Error).message };
+    return { status: "unparsable", path, reason: messageOf(e) };
   }
 }