paperlint 3.1.0 → 3.1.2

package/src/domain/lookup-cache.test.ts

@@ -0,0 +1,178 @@
+import { describe, expect, it } from "vitest";
+import {
+  freshPart,
+  EMPTY_LOOKUP_CACHE,
+  parseLookupCache,
+  serializeLookupCache,
+  type LookupCache,
+} from "./lookup-cache.ts";
+import { err, ok } from "./result.ts";
+
+const HIT = {
+  venue: "ICSE",
+  year: "2024",
+  type: "Conference and Workshop Papers",
+  title: "Good Paper.",
+  authors: ["Ada Lovelace"],
+};
+const CACHE: LookupCache = {
+  citations: new Map([
+    [
+      "crossref:doi:10.1/good",
+      {
+        fetched: "2026-09-27",
+        response: { db: "crossref", transport: "ok", query: "doi" },
+      },
+    ],
+  ]),
+  dblp: new Map([
+    [
+      "0123456789abcdef",
+      { fetched: "2026-09-26", title: "Good Paper", hits: [HIT] },
+    ],
+  ]),
+};
+const doc = (o: object): string => JSON.stringify({ schema: 1, ...o });
+
+describe("serializeLookupCache / parseLookupCache", () => {
+  it("round-trips, keys sorted, one trailing newline", () => {
+    const text = serializeLookupCache(CACHE);
+    expect(text).toBe(
+      `${JSON.stringify(
+        {
+          schema: 1,
+          citations: {
+            "crossref:doi:10.1/good": {
+              fetched: "2026-09-27",
+              response: { db: "crossref", transport: "ok", query: "doi" },
+            },
+          },
+          dblp: {
+            ["0123456789abcdef"]: {
+              fetched: "2026-09-26",
+              title: "Good Paper",
+              hits: [HIT],
+            },
+          },
+        },
+        null,
+        2,
+      )}\n`,
+    );
+    expect(parseLookupCache(text)).toEqual(ok(CACHE));
+  });
+
+  it("the empty cache writes both sections, and reads back as empty", () => {
+    expect(parseLookupCache(serializeLookupCache(EMPTY_LOOKUP_CACHE))).toEqual(
+      ok(EMPTY_LOOKUP_CACHE),
+    );
+  });
+});
+
+// Guards: a committed file that is wrong in any way is refused with a NAMED reason. Read as
+// empty, it would silently turn every build into a full online run — the defect this file fixes.
+const REFUSALS: [string, string][] = [
+  ["[]", "expected an object with `schema`, `citations` and `dblp`"],
+  [doc({ schema: 2 }), "schema 2: this paperlint reads schema 1"],
+  [doc({ citations: {}, dblp: {}, x: 1 }), "unknown field `x`"],
+  [doc({ dblp: {} }), "`citations`: expected an object"],
+  [doc({ citations: {} }), "`dblp`: expected an object"],
+  [doc({ citations: { k: 1 }, dblp: {} }), "`citations.k`: expected an object"],
+  [
+    doc({
+      citations: { k: { fetched: "2026-9-1", response: {} } },
+      dblp: {},
+    }),
+    "`citations.k.fetched`: expected a date, YYYY-MM-DD",
+  ],
+  [
+    doc({
+      citations: {
+        k: { fetched: "2026-09-01", response: { transport: "error" } },
+      },
+      dblp: {},
+    }),
+    '`citations.k.response`: expected a successful response ({"transport": "ok", …})',
+  ],
+  [
+    doc({
+      citations: {
+        k: { fetched: "2026-09-01", response: { transport: "ok" }, y: 1 },
+      },
+      dblp: {},
+    }),
+    "`citations.k`: unknown field `y`",
+  ],
+  [
+    doc({
+      citations: {},
+      dblp: { t: { fetched: "2026-09-01", title: 3, hits: [] } },
+    }),
+    "`dblp.t.title`: expected a string",
+  ],
+  [
+    doc({
+      citations: {},
+      dblp: { t: { fetched: "2026-09-01", title: "T", hits: {} } },
+    }),
+    "`dblp.t.hits`: expected an array",
+  ],
+  [
+    doc({
+      citations: {},
+      dblp: {
+        t: {
+          fetched: "2026-09-01",
+          title: "T",
+          hits: [{ ...HIT, authors: [1] }],
+        },
+      },
+    }),
+    "`dblp.t.hits[0]`: expected {venue, year, type, title: string; authors: string[]}",
+  ],
+  [
+    doc({
+      citations: {},
+      dblp: { t: { fetched: "2026-09-01", title: "T", hits: [3] } },
+    }),
+    "`dblp.t.hits[0]`: expected {venue, year, type, title: string; authors: string[]}",
+  ],
+];
+
+describe("parseLookupCache refusals", () => {
+  it("refuses text that is not JSON, saying so", () => {
+    const r = parseLookupCache("{");
+    // The rest of the message is Node's parser; its wording is not the subject.
+    expect(r.ok ? "" : r.error).toMatch(/^not JSON: /);
+  });
+
+  // Guards: see REFUSALS.
+  it.each(REFUSALS)("refuses %s with a named reason", (text, why) => {
+    expect(parseLookupCache(text)).toEqual(err(why));
+  });
+});
+
+describe("freshPart", () => {
+  const cache = (fetched: string): LookupCache => ({
+    citations: new Map([
+      [
+        "k",
+        {
+          fetched,
+          response: { db: "crossref", transport: "ok", query: "doi" },
+        },
+      ],
+    ]),
+    dblp: new Map(),
+  });
+  // Guards: the age window has two ends. A date in the future (a clock ahead, a typo) has a
+  // negative age; read as fresh, a miss would be trusted until that date plus 30 days.
+  it.each([
+    ["2026-09-27", 1],
+    ["2026-08-28", 1],
+    ["2026-08-27", 0],
+    ["2026-09-28", 0],
+  ])("on 2026-09-27, an answer fetched %s is kept %i time(s)", (fetched, n) => {
+    expect(freshPart(cache(fetched), "2026-09-27").citations.size).toBe(n);
+  });
+});

package/src/domain/lookup-cache.ts

@@ -0,0 +1,202 @@
+/**
+ * THE LOOKUP CACHE — `<paper>/repro/references-cache.json`: what the citation services ANSWERED,
+ * kept so that a build asks each question at most once every MAX_AGE_DAYS, not once per build (#107).
+ *
+ *   { "schema": 1,
+ *     "citations": { "<resolver>:<identifier>": { "fetched": "YYYY-MM-DD", "response": {…} } },
+ *     "dblp":      { "<title key>":             { "fetched": "YYYY-MM-DD", "title": "…", "hits": […] } } }
+ *
+ * `citations` holds verify-cites' per-resolver responses (Crossref, OpenAlex, Semantic Scholar,
+ * arXiv, doi.org, NVD), under verify-cites' own cache keys. `dblp` holds the hits DBLP returned for
+ * a title, under the references adapter's `dblpTitleKey`. Only successful answers are ever stored: a failed request is not an
+ * answer, so the next build asks again.
+ *
+ * 🔴 RESPONSES, NEVER VERDICTS. The verdicts (`_build/references.json`) are DERIVED from these
+ * responses on every build, by the current version of the checkers. A cached verdict would freeze
+ * whatever the checker believed the day it ran — a bug fixed in the comparison would never reach a
+ * paper whose entries are cached. A cached response is evidence: it cannot be made up, only
+ * refetched. The precedent is `extract-ref-facts.mjs`'s `repro/refs-cache.json` ("the cache is
+ * evidence, not a second declaration").
+ *
+ * 🔴 COMMITTED, so CI and every other clone start warm: a build whose entries are all here makes no
+ * network request at all, not even the reachability probe. It lives in `repro/`, beside the paper,
+ * not in `_build/`, which is build output and gitignored.
+ *
+ * WHAT INVALIDATES AN ENTRY: its key, or its age. Editing a bib entry's DOI, arXiv id or title
+ * changes the keys it is looked up under, so only that entry is asked again. An answer older than
+ * MAX_AGE_DAYS (by `fetched`) is asked again too, so a work a service had not indexed yet is found
+ * once it is. To refresh an answer sooner, delete its entry, or the file.
+ *
+ * Parsed here, once, at the boundary: a file that does not match is refused with a named reason,
+ * never read as empty.
+ */
+import { err, ok, type Result } from "./result.ts";
+
+export const LOOKUP_CACHE_SCHEMA = 1;
+
+type Json = Readonly<Record<string, unknown>>;
+
+/** One resolver's successful answer, as verify-cites shapes it (`{ transport: "ok", … }`). */
+export interface CachedResponse {
+  /** When it was fetched, YYYY-MM-DD. */
+  readonly fetched: string;
+  readonly response: Json;
+}
+
+/** One DBLP hit, as bib-authors' `dblpHits` shapes it. */
+export interface DblpHit {
+  readonly venue: string;
+  readonly year: string;
+  readonly type: string;
+  readonly title: string;
+  readonly authors: readonly string[];
+}
+
+export interface CachedDblp {
+  readonly fetched: string;
+  /** The title as it was asked — for a human reading the file; the key is the adapter's `dblpTitleKey(title)`. */
+  readonly title: string;
+  readonly hits: readonly DblpHit[];
+}
+
+export interface LookupCache {
+  readonly citations: ReadonlyMap<string, CachedResponse>;
+  readonly dblp: ReadonlyMap<string, CachedDblp>;
+}
+
+export const EMPTY_LOOKUP_CACHE: LookupCache = {
+  citations: new Map(),
+  dblp: new Map(),
+};
+
+/**
+ * How long a cached answer is used before it is asked again. A registry, doi.org or DBLP that had
+ * not indexed a work yet answers "no record"; kept forever, that answer would outlive the work's
+ * indexing. The age is judged against `fetched`, so every answer — a hit or a miss — gets the
+ * same rule, and nothing has to decide which answers are "negative".
+ */
+export const MAX_AGE_DAYS = 30;
+
+const dayNumber = (date: string): number =>
+  Date.parse(`${date}T00:00:00Z`) / 86_400_000;
+
+/** The part of `cache` still young enough to answer from on `today` (YYYY-MM-DD). */
+export function freshPart(cache: LookupCache, today: string): LookupCache {
+  // An age below zero is a date in the future (a clock ahead, a typo): not trusted, asked again.
+  const young = ({ fetched }: { fetched: string }): boolean => {
+    const age = dayNumber(today) - dayNumber(fetched);
+    return age >= 0 && age <= MAX_AGE_DAYS;
+  };
+  return {
+    citations: new Map([...cache.citations].filter(([, v]) => young(v))),
+    dblp: new Map([...cache.dblp].filter(([, v]) => young(v))),
+  };
+}
+
+const isObject = (v: unknown): v is Json =>
+  typeof v === "object" && v !== null && !Array.isArray(v);
+const unknownField = (o: Json, known: readonly string[]): string | undefined =>
+  Object.keys(o).find((k) => !known.includes(k));
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+const isDate = (v: unknown): v is string =>
+  typeof v === "string" && DATE.test(v);
+
+/** Parse every value of `section` with `one`, or the first named reason. */
+function sectionOf<T>(
+  name: string,
+  section: unknown,
+  known: readonly string[],
+  one: (o: Json, at: string) => Result<T, string>,
+): Result<Map<string, T>, string> {
+  if (!isObject(section)) return err(`\`${name}\`: expected an object`);
+  const out = new Map<string, T>();
+  for (const [key, v] of Object.entries(section)) {
+    const at = `\`${name}.${key}`;
+    if (!isObject(v)) return err(`${at}\`: expected an object`);
+    const extra = unknownField(v, known);
+    if (extra !== undefined) return err(`${at}\`: unknown field \`${extra}\``);
+    if (!isDate(v["fetched"]))
+      return err(`${at}.fetched\`: expected a date, YYYY-MM-DD`);
+    const r = one(v, at);
+    if (!r.ok) return r;
+    out.set(key, r.value);
+  }
+  return ok(out);
+}
+
+const cachedResponse = (o: Json, at: string): Result<CachedResponse, string> =>
+  isObject(o["response"]) && o["response"]["transport"] === "ok"
+    ? ok({ fetched: o["fetched"] as string, response: o["response"] })
+    : err(
+        `${at}.response\`: expected a successful response ({"transport": "ok", …})`,
+      );
+
+const isHit = (h: unknown): h is DblpHit =>
+  isObject(h) &&
+  ["venue", "year", "type", "title"].every((k) => typeof h[k] === "string") &&
+  Array.isArray(h["authors"]) &&
+  h["authors"].every((a) => typeof a === "string");
+
+function cachedDblp(o: Json, at: string): Result<CachedDblp, string> {
+  const { title, hits } = o;
+  if (typeof title !== "string") return err(`${at}.title\`: expected a string`);
+  if (!Array.isArray(hits)) return err(`${at}.hits\`: expected an array`);
+  const bad = hits.findIndex((h) => !isHit(h));
+  if (bad !== -1)
+    return err(
+      `${at}.hits[${String(bad)}]\`: expected {venue, year, type, title: string; authors: string[]}`,
+    );
+  return ok({
+    fetched: o["fetched"] as string,
+    title,
+    hits: hits as DblpHit[],
+  });
+}
+
+/** The cache in `text`, or why it cannot be read. */
+export function parseLookupCache(text: string): Result<LookupCache, string> {
+  let json: unknown;
+  try {
+    json = JSON.parse(text);
+  } catch (e) {
+    return err(`not JSON: ${(e as Error).message}`);
+  }
+  if (!isObject(json))
+    return err("expected an object with `schema`, `citations` and `dblp`");
+  if (json["schema"] !== LOOKUP_CACHE_SCHEMA)
+    return err(
+      `schema ${String(json["schema"])}: this paperlint reads schema ${String(LOOKUP_CACHE_SCHEMA)}`,
+    );
+  const extra = unknownField(json, ["schema", "citations", "dblp"]);
+  if (extra !== undefined) return err(`unknown field \`${extra}\``);
+  const citations = sectionOf(
+    "citations",
+    json["citations"],
+    ["fetched", "response"],
+    cachedResponse,
+  );
+  if (!citations.ok) return citations;
+  const dblp = sectionOf(
+    "dblp",
+    json["dblp"],
+    ["fetched", "title", "hits"],
+    cachedDblp,
+  );
+  if (!dblp.ok) return dblp;
+  return ok({ citations: citations.value, dblp: dblp.value });
+}
+
+const sorted = <T>(m: ReadonlyMap<string, T>): Record<string, T> =>
+  Object.fromEntries([...m.keys()].sort().map((k) => [k, m.get(k) as T]));
+
+/** The cache as the file holds it: keys sorted, so one new answer is a small diff. */
+export const serializeLookupCache = (c: LookupCache): string =>
+  `${JSON.stringify(
+    {
+      schema: LOOKUP_CACHE_SCHEMA,
+      citations: sorted(c.citations),
+      dblp: sorted(c.dblp),
+    },
+    null,
+    2,
+  )}\n`;

package/src/domain/result.test.ts

@@ -10,6 +10,10 @@ test("map and andThen run on ok and pass an error through untouched", () => {
     map(ok(2), (n) => n + 1),
     ok(3),
   );
+  assert.deepEqual(
+    map(half(3), () => assert.fail("mapped after an error")),
+    err("3 is odd"),
+  );
   assert.deepEqual(andThen(ok(8), half), ok(4));
   // Guards: an error short-circuits — the function after it is not called.
   assert.deepEqual(

package/src/domain/result.ts

@@ -22,8 +22,3 @@ export const match = <T, E, R>(
   r: Result<T, E>,
   on: { readonly ok: (t: T) => R; readonly err: (e: E) => R },
 ): R => (r.ok ? on.ok(r.value) : on.err(r.error));
-
-/** The `default` of an exhaustive `switch`: a new variant is a compile error, not a silent fall-through. */
-export function assertNever(x: never): never {
-  throw new Error(`unhandled variant: ${JSON.stringify(x)}`);
-}

package/src/engine.harness.mjs

@@ -7,7 +7,6 @@
  *      `probeTree` through a fake runner.
  * All pure or port-driven: no TeX needed. The real-TeX half is `test/e2e/build.mjs`.
  */
-import assert from "node:assert/strict";
 import {
   chmodSync,
   mkdirSync,
@@ -19,6 +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";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const {
@@ -32,11 +32,7 @@ const {
   supportedPlatform,
 } = await import(join(HERE, "engine.ts"));
 
-let n = 0;
-const check = (label, cond, detail = "") => {
-  assert.ok(cond, `${label}${detail ? ` — ${detail}` : ""}`);
-  n++;
-};
+const check = createChecker();
 
 // ── 1. resolveEngine ────────────────────────────────────────────────────────────────────
 const tree = (label, missing = []) => ({ label, bin: `/${label}`, missing });
@@ -301,4 +297,28 @@ check(
   ) === "[]",
 );
 
-console.log(`engine: ${n} checks passed`);
+check(
+  "missingDependencies: a tlmgr that cannot start reports nothing (the tree is judged by probeTree alone)",
+  JSON.stringify(
+    missingDependencies("/tl/bin", () => ({ error: new Error("ENOENT") })),
+  ) === "[]",
+);
+check(
+  "missingDependencies: a section that runs to the end of the output, with no header after it",
+  JSON.stringify(
+    missingDependencies("/tl/bin", () => ({
+      stdout:
+        "\f DEPENDS WITHOUT PACKAGES:\nunicode-data in: latex-bin\nhyphen-base in: x",
+      status: 2,
+    })),
+  ) === '["hyphen-base","unicode-data"]',
+);
+check(
+  "a runner that returns no stdout at all: tlmgr lists nothing, kpsewhich finds nothing",
+  JSON.stringify(missingDependencies("/tl/bin", () => ({ status: 0 }))) ===
+    "[]" &&
+    JSON.stringify(probeTree("/tl/bin", PKGS, () => ({ status: 0 }))) ===
+      JSON.stringify(Object.keys(PKGS).sort()),
+);
+
+console.log(`engine: ${check.count} checks passed`);

package/src/facts-file.test.ts

@@ -18,6 +18,7 @@ import {
   factsDocument,
   factsPath,
   measurePaper,
+  parseFactsText,
   writeFactsFile,
   type MeasureOptions,
 } from "./facts-file.ts";
@@ -278,3 +279,112 @@ test("declaredVenue: a paperlint.json with an unknown key is refused, naming the
   });
   assert.throws(() => declaredVenue(files, PAPER), /unknown key "venu"/);
 });
+
+test("a PDF with no text has an empty font list, not a failed document", () => {
+  const d = factsDocument({
+    pdf: "paper.pdf",
+    sha: "a".repeat(64),
+    venue: null,
+    kind: null,
+    read: {
+      pages: 1,
+      fonts: { kind: "no-text" },
+      last: lastPage(0, 0),
+      layout: [],
+    },
+    geometry: NONE,
+  });
+  assert.deepEqual(d.fonts, []);
+});
+
+test("measure: a PDF gone between pdf.js's read and the hash is an error, not a hash of nothing", async () => {
+  const { o, files } = setup();
+  files.map.delete(PDF);
+  const m = await measurePaper(PAPER, PDF, o);
+  assert.equal(!m.ok && m.error, `${PDF}: gone after pdf.js read it`);
+});
+
+test("measure: no paperlint.json and no override — venue and kind are null", async () => {
+  const { o, files } = setup();
+  files.map.delete(`${PAPER}/paperlint.json`);
+  const m = await measurePaper(PAPER, PDF, o);
+  assert.deepEqual(m.ok && [m.value.facts.venue, m.value.facts.kind], [
+    null,
+    null,
+  ]);
+});
+
+// ── reading the file back: every refusal names what is wrong ────────────────────────────
+const written = (geometry: Geometry = MEASURED) => ({
+  ...doc(lastPage(60, 30), geometry),
+});
+const parse = (d: unknown) => parseFactsText(JSON.stringify(d));
+const why = (d: unknown): string => {
+  const r = parse(d);
+  return !r.ok && r.error.kind === "broken" ? r.error.why : "";
+};
+
+test("parseFactsText: a written document reads back, with and without geometry", () => {
+  const measured = parse(written());
+  assert.ok(measured.ok);
+  assert.equal(measured.value.geometry?.columns, 2);
+  const none = parse(written(NONE));
+  assert.equal(none.ok && none.value.geometry, null);
+});
+
+test("parseFactsText: every malformed shape is refused with its reason", () => {
+  assert.equal(why([1]), "not a JSON object");
+  assert.equal(why({ ...written(), pdf: "" }), "no `pdf` path");
+  assert.equal(why({ ...written(), pdf: 7 }), "no `pdf` path");
+  assert.equal(
+    why({ ...written(), pdf_sha256: "xyz" }),
+    "no `pdf_sha256` of 64 hex digits",
+  );
+  assert.equal(
+    why({ ...written(), fonts: [{ name: "x" }] }),
+    "`fonts` is not a list of { name, type, embedded, program }",
+  );
+  assert.equal(
+    why({ ...written(), fonts: ["Times"] }),
+    "`fonts` is not a list of { name, type, embedded, program }",
+  );
+  assert.equal(
+    why({ ...written(), geometry_source: 3 }),
+    "`geometry_source` is neither a measurer's name nor null",
+  );
+  assert.equal(
+    why({ ...written(), columns: "two" }),
+    "`columns` is not a number",
+  );
+  assert.equal(
+    why({ ...written(), ref_pages: null }),
+    "`ref_pages` is not a number",
+  );
+  assert.equal(
+    why({ ...written(), pages_by_type: { body: "3" } }),
+    "`pages_by_type` is not an object of page counts",
+  );
+  assert.equal(
+    why({ ...written(), pages_by_type: [3] }),
+    "`pages_by_type` is not an object of page counts",
+  );
+  assert.equal(
+    why({ ...written(), fonts: "Times" }),
+    "`fonts` is not a list of { name, type, embedded, program }",
+  );
+  const notJson = parseFactsText("{");
+  assert.match(
+    !notJson.ok && notJson.error.kind === "broken" ? notJson.error.why : "",
+    /^not JSON \(/,
+  );
+});
+
+test("parseFactsText: a missing schema is reported as null, another schema by its value", () => {
+  const missing = parse({ ...written(), schema: undefined });
+  assert.deepEqual(!missing.ok && missing.error, {
+    kind: "schema",
+    got: "null",
+  });
+  const other = parse({ ...written(), schema: 1 });
+  assert.deepEqual(!other.ok && other.error, { kind: "schema", got: "1" });
+});

package/src/hooks-settings.harness.mjs

@@ -15,8 +15,6 @@
  * ⚠️ Assertions at the TOP LEVEL: `vigiles test` imports the file and counts "did not throw"
  * as a pass.
  */
-import assert from "node:assert/strict";
-import { recordCheck } from "vigiles";
 import {
   existsSync,
   mkdirSync,
@@ -29,6 +27,7 @@ import {
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { createChecker } from "../lib/check.mjs";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const {
@@ -44,12 +43,7 @@ const {
 const { claudeCodeHookProtocol } = await import("vigiles/claude-code");
 const merge = (e, c, m) => claudeCodeHookProtocol.mergeRegistrations(e, c, m);
 
-let n = 0;
-const check = (label, cond) => {
-  n++;
-  assert.ok(cond, label);
-  recordCheck(label);
-};
+const check = createChecker();
 
 // ── the contract with vigiles, checked before anything relies on it ──────────────────────
 check(
@@ -64,6 +58,40 @@ check(
   wiring.names.join() ===
     "paper-edit-guard,paper-skills-nudge,paper-status-gates",
 );
+// ── settings written by hand: shapes Claude Code would ignore are skipped, not crashed on ──
+check(
+  "an event that is not a list, an entry with no `hooks` list, a handler with no command → no commands",
+  JSON.stringify(
+    wiredCounts(
+      {
+        hooks: {
+          PreToolUse: "npx paperlint hook paper-edit-guard",
+          PostToolUse: [{ matcher: "Edit" }, null, { hooks: "x" }],
+          Stop: [{ hooks: [{ type: "command" }, null] }],
+        },
+      },
+      wiring.names,
+    ),
+  ) ===
+    JSON.stringify(wiring.names.map((name) => ({ name, ours: 0, other: 0 }))),
+);
+{
+  const file = join(tmpdir(), `paperlint-no-hooks-${String(process.pid)}.json`);
+  writeFileSync(file, "{}\n");
+  let thrown = "";
+  try {
+    shippedWiring(file);
+  } catch (e) {
+    thrown = e.message;
+  }
+  rmSync(file);
+  check(
+    "a wiring file without `hooks` names no hook — and THROWS instead of wiring nothing",
+    thrown === `${file} names no paperlint hook — there is nothing to wire`,
+    thrown,
+  );
+}
+
 const work = realpathSync(mkdtempSync(join(tmpdir(), "paperlint-hooks-")));
 try {
   const empty = join(work, "empty-hooks.json");
@@ -135,7 +163,7 @@ try {
     check(
       "no settings file → it is created with the three hooks",
       r.status === "written" &&
-        [...wiredCounts(s, wiring.names).values()].every(
+        wiredCounts(s, wiring.names).every(
           (c) => c.ours === 1 && c.other === 0,
         ),
     );
@@ -172,7 +200,7 @@ try {
     );
     check(
       "and ours are there, once each",
-      [...wiredCounts(s, wiring.names).values()].every((c) => c.ours === 1),
+      wiredCounts(s, wiring.names).every((c) => c.ours === 1),
     );
   }
 
@@ -224,7 +252,9 @@ try {
     // The control: without the check, vigiles' merge WOULD add a second copy. This is the
     // reason the check exists, measured rather than asserted.
     const merged = merge(handWired, wiring.compiled, MANAGED_BY);
-    const c = wiredCounts(merged, wiring.names).get("paper-edit-guard");
+    const c = wiredCounts(merged, wiring.names).find(
+      (c) => c.name === "paper-edit-guard",
+    );
     check(
       "(control) vigiles' merge alone would wire paper-edit-guard TWICE here",
       c.ours === 1 && c.other === 1,
@@ -247,7 +277,7 @@ try {
 
   // ── doctor's section ───────────────────────────────────────────────────────────────────
   const doc = (settings) => {
-    const dir = project(`doc-${String(n)}`, settings);
+    const dir = project(`doc-${String(check.count)}`, settings);
     return doctorHooks(dir, wiring).join("\n");
   };
   const wiredOnce = merge({}, wiring.compiled, MANAGED_BY);
@@ -306,5 +336,5 @@ try {
 }
 
 console.log(
-  `✓ ${String(n)} assertions passed — the hooks land in .claude/settings.json once`,
+  `✓ ${String(check.count)} assertions passed — the hooks land in .claude/settings.json once`,
 );