paperlint 3.1.0 → 3.1.1

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`,
 );

package/src/hooks-settings.ts

@@ -93,8 +93,8 @@ interface Run {
  */
 function parseRun(command: string): Run | null {
   const tokens = command.trim().split(/\s+/).map(bare);
-  for (let i = 0; i < tokens.length; i++) {
-    const run = runAt(tokens, i);
+  for (const [i, token] of tokens.entries()) {
+    const run = runAt(token, tokens.slice(i + 1, i + 3));
     if (run) return run;
   }
   return null;
@@ -108,17 +108,13 @@ function insidePackage(parts: readonly string[]): readonly string[] {
   return at === -1 ? [] : parts.slice(at + 2);
 }
 
-/** The run token `i` starts, if it names a paperlint hook. */
-function runAt(tokens: readonly string[], i: number): Run | null {
-  const t = posix.normalize(tokens[i] ?? "");
+/** The run `token` starts, if it names a paperlint hook; `after` is the two tokens that follow it. */
+function runAt(token: string, after: readonly string[]): Run | null {
+  const t = posix.normalize(token);
   const inside = insidePackage(t.split("/"));
   const inBin = inside[0] === "bin" && inside.length === 2;
-  const name = tokens[i + 2];
-  if (
-    (inBin || basename(t) === PACKAGE_NAME) &&
-    tokens[i + 1] === "hook" &&
-    name
-  )
+  const [verb, name] = after;
+  if ((inBin || basename(t) === PACKAGE_NAME) && verb === "hook" && name)
     return { name, ours: t === MANAGED_BY, path: t };
   if (inside[0] === "hooks" && inside[1]?.endsWith(".hook.mjs"))
     return { name: basename(inside[1], ".hook.mjs"), ours: false, path: t };
@@ -171,22 +167,33 @@ export function shippedWiring(file: string = WIRING_FILE): Wiring {
   return { compiled, names: [...new Set(names)] };
 }
 
-/** How many commands run each shipped hook, split by spelling. */
+/** How many commands run one shipped hook, split by spelling. */
+export interface HookCount {
+  readonly name: string;
+  readonly ours: number;
+  readonly other: number;
+}
+
+/** One count per name in `names`, in that order — a name nothing runs has zeros, never a gap. */
 export function wiredCounts(
   settings: Settings,
   names: readonly string[],
-): Map<string, { ours: number; other: number }> {
-  const counts = new Map(names.map((n) => [n, { ours: 0, other: 0 }]));
-  for (const { command } of commandsIn(settings)) {
+): readonly HookCount[] {
+  const runs = commandsIn(settings).flatMap(({ command }) => {
     const run = hookRun(command);
-    const slot = run ? counts.get(run.name) : undefined;
-    if (run && slot)
-      if (run.ours) slot.ours++;
-      else slot.other++;
-  }
-  return counts;
+    return run ? [run] : [];
+  });
+  const count = (name: string, ours: boolean): number =>
+    runs.filter((r) => r.name === name && r.ours === ours).length;
+  return names.map((name) => ({
+    name,
+    ours: count(name, true),
+    other: count(name, false),
+  }));
 }
 
+const total = (c: HookCount): number => c.ours + c.other;
+
 export type SettingsRead =
   | { readonly status: "absent"; readonly path: string; readonly settings: {} }
   | {
@@ -258,15 +265,16 @@ export function wireHooks(
   const read = readSettings(root);
   if (read.status === "unparsable") return read;
   const { path, settings } = read;
-  const found = commandsIn(settings)
-    .map(({ command }) => ({ command, run: hookRun(command) }))
-    .filter(({ run }) => run && !run.ours && wiring.names.includes(run.name))
-    .map(({ command, run }) => ({ name: run?.name ?? "", command }));
+  const found = commandsIn(settings).flatMap(({ command }) => {
+    const run = hookRun(command);
+    return run && !run.ours && wiring.names.includes(run.name)
+      ? [{ name: run.name, command }]
+      : [];
+  });
   if (found.length > 0) {
-    const counts = wiredCounts(settings, wiring.names);
-    const missing = wiring.names.filter(
-      (n) => (counts.get(n)?.ours ?? 0) + (counts.get(n)?.other ?? 0) === 0,
-    );
+    const missing = wiredCounts(settings, wiring.names)
+      .filter((c) => total(c) === 0)
+      .map((c) => c.name);
     return { status: "foreign", path, names: wiring.names, found, missing };
   }
 
@@ -297,19 +305,17 @@ export function doctorHooks(
     return out;
   }
   const counts = wiredCounts(read.settings, wiring.names);
-  const total = (n: string): number =>
-    (counts.get(n)?.ours ?? 0) + (counts.get(n)?.other ?? 0);
-  const missing = wiring.names.filter((n) => total(n) === 0);
-  const twice = wiring.names.filter((n) => total(n) > 1);
+  const missing = counts.filter((c) => total(c) === 0).map((c) => c.name);
+  const twice = counts.filter((c) => total(c) > 1);
   // `init` refuses to write while any hook is wired under another spelling, so its remedy must
   // not be offered then — the remedy is to pick ONE form.
-  const handWired = wiring.names.some((n) => (counts.get(n)?.other ?? 0) > 0);
+  const handWired = counts.some((c) => c.other > 0);
   const remedy = handWired
     ? `some paperlint hooks are wired by hand under another spelling, and \`npx paperlint init\` writes nothing then — add the missing ones in that same form, or delete the hand-written ones and run \`npx paperlint init\``
     : `\`npx paperlint init\` adds them`;
   if (twice.length > 0) {
     out.push(`  ⚠ wired TWICE — each of these runs more than once per event:`);
-    for (const n of twice) out.push(`      ${n} ×${String(total(n))}`);
+    for (const c of twice) out.push(`      ${c.name} ×${String(total(c))}`);
     out.push(
       `      keep one command per hook; \`npx paperlint init\` writes the ${MANAGED_BY} form`,
     );