paperlint 3.0.0 → 3.1.1

package/src/doctor.harness.mjs

@@ -9,9 +9,7 @@
  * this file can tell the two apart.
  *
  * Run:    npx vigiles test src/doctor.harness.mjs
- * Killed by: src/doctor.mutations.mjs
  */
-import assert from "node:assert/strict";
 import { PAPERS_DIR_FIELD } from "../lib/paper-config.mjs";
 import {
   mkdtempSync,
@@ -23,6 +21,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 { doctor, detectPapers, PROGRAMS, found } = await import(
@@ -32,11 +31,7 @@ const { papersRoot } = await import(
   join(HERE, "..", "hooks", "paper-edit-guard.hook.mjs")
 );
 
-let n = 0;
-const check = (label, cond) => {
-  n++;
-  assert.ok(cond, label);
-};
+const check = createChecker();
 
 /** A consumer on disk: a papers directory, and maybe a declaration in the root paperlint.json. */
 function consumer({ papersDir, declared, makeDir = true }) {
@@ -333,5 +328,5 @@ const runDoctor = (
 }
 
 console.log(
-  `✓ ${n} assertions passed — paperlint doctor: an install can vouch for itself`,
+  `✓ ${check.count} assertions passed — paperlint doctor: an install can vouch for itself`,
 );

package/src/doctor.test.ts

@@ -0,0 +1,64 @@
+/**
+ * `doctor.ts` — the edges the harness does not stage: an unreadable directory during paper
+ * discovery, a settings file that names no papers directory, an occupied skill entry with no
+ * reason, and a hooks section that cannot be read at all.
+ */
+import assert from "node:assert/strict";
+import {
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  realpathSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "vitest";
+import { detectPapers, doctor } from "./doctor.ts";
+
+const project = (): string =>
+  realpathSync(mkdtempSync(join(tmpdir(), "doctor-")));
+
+test("detectPapers: a directory that does not exist has no papers", () => {
+  assert.deepEqual(detectPapers(join(project(), "gone")), []);
+});
+
+test("detectPapers: a child that cannot be listed is skipped, its siblings are still found", () => {
+  const root = project();
+  mkdirSync(join(root, "locked"));
+  mkdirSync(join(root, "papers", "p1"), { recursive: true });
+  writeFileSync(join(root, "papers", "p1", "paper.tex"), "");
+  const readdir = (dir: string) => {
+    if (dir === join(root, "locked")) throw new Error("EACCES");
+    return readdirSync(dir, { withFileTypes: true });
+  };
+  assert.deepEqual(detectPapers(root, 2, readdir), ["papers"]);
+});
+
+test("doctor: a settings file silent on papersDir, an occupied entry, an unreadable hooks file", () => {
+  const root = project();
+  writeFileSync(join(root, "paperlint.json"), "{}\n");
+  // `.claude/settings.json` as a DIRECTORY: it exists, and reading it throws EISDIR.
+  mkdirSync(join(root, ".claude", "settings.json"), { recursive: true });
+  const lines: string[] = [];
+  const code = doctor({
+    cwd: root,
+    log: (s: string) => lines.push(s),
+    run: (() => ({ status: 0 })) as never,
+    cliPapers: join(root, "papers"),
+    skillLinks: () => ({
+      ok: true,
+      home: join(root, ".claude", "skills"),
+      example: null,
+      links: [{ name: "paper-pipeline", status: "foreign" }],
+    }),
+  });
+  const out = lines.join("\n");
+  assert.match(
+    out,
+    /✓ paperlint\.json names no papersDir — the default "papers"/,
+  );
+  assert.match(out, /paper-pipeline — occupied, not the shipped skill/);
+  assert.match(out, /\nhooks\n {2}⚠ not checked — EISDIR/);
+  assert.equal(typeof code, "number");
+});

package/src/doctor.ts

@@ -21,7 +21,7 @@
  * Prior art for the shape: `brew doctor`, `flutter doctor`, `npm doctor`, `expo-doctor`.
  */
 // eslint-disable-next-line boundaries/dependencies -- legacy I/O, moves behind a port in #76
-import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { type Dirent, existsSync, readFileSync, readdirSync } from "node:fs";
 import { join, relative, resolve } from "node:path";
 // eslint-disable-next-line boundaries/dependencies -- legacy I/O, moves behind a port in #76
 import { spawnSync } from "node:child_process";
@@ -101,14 +101,22 @@ export const PROGRAMS: readonly Program[] = [
 export const found = (bin: string, run = 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. */
+type ReadDir = (dir: string) => Dirent[];
+const readDir: ReadDir = (dir) => readdirSync(dir, { withFileTypes: true });
+
 /** Directories that look like papers, used to REPLACE a guessed default with a measurement. */
-export function detectPapers(cwd: string, depth = 2): string[] {
+export function detectPapers(
+  cwd: string,
+  depth = 2,
+  readdir: ReadDir = readDir,
+): string[] {
   const hits: string[] = [];
   const skip = new Set(["node_modules", ".git", "dist", "_build", ".claude"]);
   const walk = (dir: string, left: number): void => {
     let entries;
     try {
-      entries = readdirSync(dir, { withFileTypes: true });
+      entries = readdir(dir);
     } catch {
       return;
     }
@@ -119,7 +127,7 @@ export function detectPapers(cwd: string, depth = 2): string[] {
       // A directory whose CHILDREN look like papers is the papers root — not the paper itself.
       let children;
       try {
-        children = readdirSync(here, { withFileTypes: true });
+        children = readdir(here);
       } catch {
         continue;
       }

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 {
@@ -28,14 +28,11 @@ const {
   whichOnPath,
   isExecutable,
   probeTree,
+  missingDependencies,
   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 });
@@ -251,4 +248,77 @@ check(
   }
 }
 
-console.log(`engine: ${n} checks passed`);
+// ── missingDependencies: what an install that "continued anyway" left out ──────────────────
+// Real stdout of `tlmgr check depends` on a tree whose install-tl lost unicode-data to a mirror
+// (2026-09-26): the pdflatex format could not be built, yet every venue .sty was present.
+// Byte for byte: tlmgr opens every section header with a FORM FEED, then a space.
+const BROKEN_DEPENDS =
+  "\f DEPENDS WITHOUT PACKAGES:\n" +
+  "unicode-data in: collection-basic latex-bin luahbtex luatex\n" +
+  "\f PACKAGES NOT IN ANY COLLECTION: acmart booktabs caption\n";
+{
+  const calls = [];
+  const run = (cmd, args) => {
+    calls.push([cmd, args]);
+    return {
+      stdout: BROKEN_DEPENDS,
+      stderr: "tlmgr: An error has occurred.",
+      status: 2,
+    };
+  };
+  const missing = missingDependencies("/tl/bin", run);
+  check(
+    "missingDependencies: asks THAT tree's tlmgr `check depends`",
+    calls.length === 1 &&
+      calls[0][0] === "/tl/bin/tlmgr" &&
+      JSON.stringify(calls[0][1]) === '["check","depends"]',
+    JSON.stringify(calls),
+  );
+  // Guards: a package the tree's own database requires but never installed is a gap.
+  check(
+    "🔴 missingDependencies: names the dependency the install dropped",
+    JSON.stringify(missing) === '["unicode-data"]',
+    JSON.stringify(missing),
+  );
+}
+check(
+  "missingDependencies: packages outside any collection are not gaps",
+  JSON.stringify(
+    missingDependencies("/tl/bin", () => ({
+      stdout: "\f PACKAGES NOT IN ANY COLLECTION: acmart booktabs\n",
+      status: 2,
+    })),
+  ) === "[]",
+);
+check(
+  "missingDependencies: a clean tree has none",
+  JSON.stringify(
+    missingDependencies("/tl/bin", () => ({ stdout: "", status: 0 })),
+  ) === "[]",
+);
+
+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/engine.ts

@@ -164,6 +164,41 @@ export function probeTree(
   return missingPackages(packages, String(r.stdout ?? ""));
 }
 
+/**
+ * Packages the tree's OWN database lists as dependencies but never installed, by its `tlmgr check
+ * depends`. 🔴 The venue's `.sty` files are not enough evidence of a working tree: install-tl that
+ * cannot download a package prints "continuing anyway", and a missing `unicode-data` leaves every
+ * `.sty` in place while the pdflatex format cannot be built — pdflatex then dies before writing a
+ * log. Only paperlint's cache trees are asked: their tlmgr writes to a directory we own. A tlmgr
+ * that cannot start returns nothing here; the tree is then judged by `probeTree` alone.
+ */
+export function missingDependencies(
+  bin: string,
+  run: Runner = spawnSync,
+): string[] {
+  const r = run(join(bin, "tlmgr"), ["check", "depends"], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  if (r.error) return [];
+  const lines = String(r.stdout ?? "").split("\n");
+  const start = lines.findIndex(
+    (l) => l.trim() === "DEPENDS WITHOUT PACKAGES:",
+  );
+  if (start < 0) return [];
+  // The section runs until tlmgr's next header. Headers open with a form feed and a space, entries
+  // with the package name, so a header is any line with leading whitespace.
+  const section = lines.slice(start + 1);
+  const end = section.findIndex((l) => l !== l.trimStart() || !l.trim());
+  return [
+    ...new Set(
+      (end < 0 ? section : section.slice(0, end)).map((l) =>
+        l.split(" in: ")[0]!.trim(),
+      ),
+    ),
+  ].sort();
+}
+
 /** The first directory on `path` holding a runnable `name` — what a shell would run. */
 export function whichOnPath(
   name: string,

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