paperlint 3.2.0 → 4.0.0

package/src/hooks-settings.ts

@@ -31,6 +31,7 @@ import {
   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");
@@ -151,6 +152,25 @@ const prop = (v: unknown): Readonly<Record<string, unknown>> | undefined =>
     ? 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. */
@@ -162,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");
@@ -225,9 +249,9 @@ 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: messageOf(e) };
   }

package/src/init.test.ts

@@ -70,7 +70,7 @@ describe("paperlint init — a declared papers directory", () => {
       err: (s: string) => out.push(s),
       interactive: false,
       hooks: false,
-      run: (() => ({ status: 0 })) as never,
+      run: () => ({ status: 0 }),
       link: () => ({ ok: false, error: "not linked in this test" }),
     });
     const text = out.join("\n");
@@ -97,7 +97,7 @@ describe("paperlint init — a declared papers directory", () => {
       interactive: true,
       ask: (q) => Promise.resolve((asked.push(q), "n")),
       hooks: false,
-      run: (() => ({ status: 0 })) as never,
+      run: () => ({ status: 0 }),
       link: () => ({ ok: false, error: "not linked in this test" }),
     });
     expect(asked.filter((q) => /papers roots/.test(q))).toEqual([]);
@@ -116,7 +116,7 @@ describe("paperlint init — writes paperlint.json only when something differs f
     err: () => {},
     interactive: false,
     hooks: false,
-    run: (() => ({ status: 0 })) as never,
+    run: () => ({ status: 0 }),
     link: () => ({ ok: false as const, error: "not linked in this test" }),
   };
   const fresh = (files: Record<string, string>): string => {
@@ -170,7 +170,7 @@ const texRun = async (
     ask: (q) =>
       Promise.resolve((asked.push(q), /TeX Live/.test(q) ? answer : "")),
     hooks: false,
-    run: (() => ({ status: 0 })) as never,
+    run: () => ({ status: 0 }),
     link: () => ({ ok: false as const, error: "not linked in this test" }),
     tex,
   });
@@ -249,7 +249,7 @@ async function initRun(
     err: (s: string) => err.push(s),
     interactive: false,
     hooks: false,
-    run: (() => ({ status: 0 })) as never,
+    run: () => ({ status: 0 }),
     link: () => ({ ok: false, error: "not linked in this test" }),
     ...opts,
   });
@@ -280,6 +280,26 @@ describe("paperlint init — a paperlint.json it cannot use stops it before anyt
     ]);
   });
 
+  it("🔴 a paperlint.json holding JSON that is not an object is refused, not read as settings", async () => {
+    // Guards: `null` threw a TypeError reading the papers field; `[1]` was spread into a settings
+    // object and the consumer's file rewritten as `{ "0": 1, "papersDir": … }`.
+    for (const json of ["null\n", "[1]\n"]) {
+      const root = tree({
+        "paperlint.json": json,
+        "drafts/a/paper.md": "# a\n",
+      });
+      const decl = await declarePapers(root, () =>
+        choosePapers(root, { interactive: false }),
+      );
+      expect(decl).toEqual({
+        status: "unparsable",
+        path: join(root, "paperlint.json"),
+        reason: "not a JSON object",
+      });
+      expect(readFileSync(join(root, "paperlint.json"), "utf8")).toBe(json);
+    }
+  });
+
   it("a file without a trailing newline keeps having none", async () => {
     const root = tree({
       "paperlint.json": '{"x":1}',

package/src/init.ts

@@ -46,7 +46,13 @@ import {
 // eslint-disable-next-line boundaries/dependencies -- legacy I/O, moves behind a port in #76
 import { spawnSync } from "node:child_process";
 import { dirname, join, relative, resolve } from "node:path";
-import { doctor, detectPapers, found, PROGRAMS } from "./doctor.ts";
+import {
+  doctor,
+  detectPapers,
+  found,
+  PROGRAMS,
+  type ProgramProbe,
+} from "./doctor.ts";
 import { PAPER_MARKERS, papersIn } from "./build.ts";
 import { linkSkills, SKILLS_HOME, type LinkReport } from "./link-skills.ts";
 import { actionRef } from "./action-ref.ts";
@@ -73,6 +79,7 @@ import {
   PAPERS_DIR_FIELD,
 } from "#lib/paper-config";
 import { messageOf } from "./domain/text.ts";
+import { isRecord } from "./domain/record.ts";
 
 /** How the papers directory was arrived at. Printed, because a guess must not read as a fact. */
 export type PapersHow =
@@ -227,13 +234,17 @@ export async function declarePapers(
 ): Promise<DeclarationResult> {
   const path = join(root, CONFIG_FILE);
   const raw = existsSync(path) ? readFileSync(path, "utf8") : null;
-  let settings: Record<string, unknown> = {};
+  let settings: Readonly<Record<string, unknown>> = {};
   if (raw !== null) {
+    let parsed: unknown;
     try {
-      settings = JSON.parse(raw) as Record<string, unknown>;
+      parsed = JSON.parse(raw);
     } catch (e) {
       return { status: "unparsable", path, reason: messageOf(e) };
     }
+    if (!isRecord(parsed))
+      return { status: "unparsable", path, reason: "not a JSON object" };
+    settings = parsed;
     const existing = settings[PAPERS_DIR_FIELD];
     if (existing !== undefined)
       return { status: "kept", path, papers: existing };
@@ -362,7 +373,7 @@ export function reportWorkflow(
  * passing checker produce the same silence.
  */
 export function missingPrograms(
-  run = spawnSync,
+  run: ProgramProbe = spawnSync,
 ): readonly (typeof PROGRAMS)[number][] {
   return PROGRAMS.filter((p) => !found(p.bin, run));
 }
@@ -584,7 +595,7 @@ export interface InitOptions {
     name: string,
     format: PaperFormat,
   ) => Promise<number>;
-  run?: typeof spawnSync;
+  run?: ProgramProbe;
   /**
    * What `paperlint lint` would resolve from the declaration, asked of the CLI's OWN reader. A second
    * implementation here would be a second source of truth — the very defect `doctor` reports.
@@ -749,21 +760,28 @@ export async function init(
   for (const line of papersLines(decl, why)) log(line);
   log(``);
   log(`settings`);
-  if (decl.status === "written")
+  // Every step below uses the DECLARED directory. A kept declaration outranks what init
+  // measured or guessed: otherwise the first paper and the workflow would land in the
+  // guessed directory while lint and the hooks keep reading the declared one.
+  let papersDir: string;
+  if (decl.status === "written") {
+    papersDir = decl.papers;
     log(
       `  ✓ ${here(decl.path)} → { "${PAPERS_DIR_FIELD}": ${JSON.stringify(decl.papers)} }`,
     );
-  else if (decl.status === "default")
+  } else if (decl.status === "default") {
+    papersDir = decl.papers;
     log(
       `  ✓ nothing to write — "${decl.papers}" is the default, so no ${CONFIG_FILE} is needed`,
     );
-  else if (decl.status === "kept") {
+  } else if (decl.status === "kept") {
     if (typeof decl.papers !== "string") {
       err(
         `  ✗ ${here(decl.path)} declares ${PAPERS_DIR_FIELD} = ${JSON.stringify(decl.papers)} — it must be a directory path (a string)`,
       );
       return 2;
     }
+    papersDir = decl.papers;
     log(
       `  ✓ ${here(decl.path)} already declares ${PAPERS_DIR_FIELD} = ${JSON.stringify(decl.papers)} — kept, nothing overwritten`,
     );
@@ -777,10 +795,6 @@ export async function init(
     );
     return 2;
   }
-  // Every step below uses the DECLARED directory. A kept declaration outranks what init
-  // measured or guessed: otherwise the first paper and the workflow would land in the
-  // guessed directory while lint and the hooks keep reading the declared one.
-  const papersDir = decl.papers as string;
 
   // ── 3. the skills, linked where Claude Code looks for them ─────────────────────────────
   for (const line of reportSkillLinks(link(root), here)) log(line);

package/src/new-paper.harness.mjs

@@ -7,9 +7,8 @@
  *     from a missing file into a created one;
  *   - the scorecard carries `researchQuestion` and NO `stages` — a new paper has shipped nothing,
  *     and a placeholder stage would be a red `paper/stages` on the very first run;
- *   - the scorecard PARSES as a scorecard (`pipeline-check.mjs` finds its four sections). The
- *     template used to live in a code fence; moved into a file, it must still be the format the
- *     skills' checker reads;
+ *   - the scorecard carries the `**Readiness verdict:**` line the status hook surfaces on every
+ *     paper edit — without it the hook reports that the paper cannot say whether it is ready;
  *   - it never overwrites, and on an existing folder adds only what is missing;
  *   - the project's `<papers>/.template/` wins over the package, file by file.
  *
@@ -25,7 +24,6 @@ import {
   rmSync,
   writeFileSync,
 } from "node:fs";
-import { spawnSync } from "node:child_process";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -124,26 +122,12 @@ try {
       /1 problem \(0 errors, 1 warning\)/.test(l.text),
   );
 
-  // The format contract of the skills' checker: four sections, parsed.
-  const pc = spawnSync(
-    process.execPath,
-    [
-      join(ROOT, "skills", "paper-pipeline", "scripts", "pipeline-check.mjs"),
-      join(papers, "demo"),
-      "--json",
-      "--today=2026-09-23",
-    ],
-    { cwd: work, encoding: "utf8" },
-  );
-  let parsed = null;
-  try {
-    parsed = JSON.parse(pc.stdout);
-  } catch {
-    parsed = null;
-  }
+  // What the status hook reads on every paper edit: the verdict line.
   check(
-    "the scorecard PARSES for pipeline-check — its four sections are found (it prints JSON, not the format warning)",
-    Array.isArray(parsed) && !/expected the four sections/.test(pc.stderr),
+    "the scorecard carries the `**Readiness verdict:**` line the status hook surfaces",
+    /^\*\*Readiness verdict:\*\*/m.test(
+      readFileSync(join(papers, "demo", STATUS_FILE), "utf8"),
+    ),
   );
 
   // ── never overwrite; on an existing folder only the missing files ─────────────────────

package/src/new-paper.ts

@@ -26,6 +26,7 @@ import {
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { CONFIG_FILE } from "#lib/paper-config";
+import { isRecord } from "./domain/record.ts";
 
 export type PaperFormat = "tex" | "md";
 export const FORMATS: readonly PaperFormat[] = ["tex", "md"];
@@ -115,15 +116,18 @@ function withVenue(
   src: string,
   venue: VenueSetting,
 ): { ok: true; text: string } | { ok: false; reason: string } {
-  let obj: Record<string, unknown>;
+  let obj: unknown;
   try {
-    obj = JSON.parse(text) as Record<string, unknown>;
+    obj = JSON.parse(text);
   } catch {
+    obj = null;
+  }
+  // Not JSON, or JSON that is not an object: there is no field to write "extends" into.
+  if (!isRecord(obj))
     return {
       ok: false,
       reason: `--venue cannot be written into ${src}: it is not plain JSON — set "extends" by hand`,
     };
-  }
   const out: Record<string, unknown> = { ...obj, extends: venue.extends };
   delete out["$comment"];
   if (venue.kind !== null) out["kind"] = venue.kind;

package/src/paper-files.test.ts

@@ -8,7 +8,7 @@
  * 74 errors — parse errors and "Definition for rule … was not found" — none of them on a paper
  * file, and the run failed. Nothing in the settings could turn that off.
  */
-import { ESLint, type Linter } from "eslint";
+import { ESLint } from "eslint";
 import {
   mkdirSync,
   mkdtempSync,
@@ -19,7 +19,7 @@ import {
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
-import { buildConfig, run } from "./cli.ts";
+import { buildConfig, eslintConfig, run } from "./cli.ts";
 import {
   narrowToOwners,
   ownedPatterns,
@@ -28,6 +28,10 @@ import {
   scopeToOwned,
 } from "./paper-files.ts";
 import { lintReport } from "../test/lint-report.ts";
+import { z } from "zod";
+
+/** What `calculateConfigForFile` answers for a file inside the config's scope, read for its rules. */
+const Computed = z.object({ rules: z.record(z.string(), z.unknown()) });
 
 const dirs: string[] = [];
 afterEach(() => {
@@ -232,25 +236,24 @@ describe("`rules` blocks — where the rule lands", () => {
     const eslint = new ESLint({
       cwd: root,
       overrideConfigFile: true,
-      overrideConfig: buildConfig(
-        {
-          rules: [
-            {
-              basePath: root,
-              files: ["papers/**"],
-              rules: { "paper/source": "warn", "paper/section-word": "off" },
-            },
-          ],
-        },
-        null,
-      ) as Linter.Config[],
+      overrideConfig: eslintConfig(
+        buildConfig(
+          {
+            rules: [
+              {
+                basePath: root,
+                files: ["papers/**"],
+                rules: { "paper/source": "warn", "paper/section-word": "off" },
+              },
+            ],
+          },
+          null,
+        ),
+      ),
     });
     const on = async (file: string) =>
-      (
-        (await eslint.calculateConfigForFile(join(root, file))) as {
-          rules: Record<string, unknown>;
-        }
-      ).rules;
+      Computed.parse(await eslint.calculateConfigForFile(join(root, file)))
+        .rules;
     const status = await on("papers/a/PIPELINE-STATUS.md");
     expect(status["paper/source"]).toEqual([1]);
     expect(status["paper/section-word"]).toBeUndefined();

package/src/paper-files.ts

@@ -40,16 +40,7 @@
  * - later global-ignore patterns win, across blocks, in config order;
  * - `files: [["a", "b"]]` matches a file only when BOTH patterns match.
  */
-import type { RuleBlock, RuleEntry } from "./rules-config.ts";
-
-/** What this module reads of a config block. */
-interface Block {
-  readonly files?: readonly unknown[];
-  readonly ignores?: readonly unknown[];
-  readonly plugins?: Readonly<
-    Record<string, { readonly rules?: Readonly<Record<string, unknown>> }>
-  >;
-}
+import type { ConfigBlock, RuleBlock, RuleEntry } from "./rules-config.ts";
 
 /**
  * A set of files paperlint lints: an own block's globs and the exceptions that block makes. A file is
@@ -99,20 +90,18 @@ const merged = (scopes: readonly OwnedScope[]): OwnedScope[] => {
  * THE FILES PAPERLINT LINTS: every own block that names `files`, with its `ignores`. A block without
  * `files` (a global ignore, or the block registering `pdf` for every file) claims nothing.
  */
-export function ownedScopes(own: readonly unknown[]): OwnedScope[] {
+export function ownedScopes(own: readonly ConfigBlock[]): OwnedScope[] {
   return merged(
-    own
-      .map((raw) => raw as Block)
-      .flatMap((b) =>
-        b.files === undefined
-          ? []
-          : [{ files: globsOf(b.files), ignores: stringsOf(b.ignores) }],
-      ),
+    own.flatMap((b) =>
+      b.files === undefined
+        ? []
+        : [{ files: globsOf(b.files), ignores: stringsOf(b.ignores) }],
+    ),
   );
 }
 
 /** Every glob paperlint's own blocks lint, once, in config order. */
-export function ownedPatterns(own: readonly unknown[]): string[] {
+export function ownedPatterns(own: readonly ConfigBlock[]): string[] {
   return [...new Set(ownedScopes(own).flatMap((s) => s.files))];
 }
 
@@ -134,7 +123,7 @@ export function scopeToOwned(owned: readonly string[]): {
 }
 
 /** Every `<plugin>/<rule>` a block registers. */
-const ruleIdsOf = (b: Block): string[] =>
+const ruleIdsOf = (b: ConfigBlock): string[] =>
   Object.entries(b.plugins ?? {}).flatMap(([name, plugin]) =>
     Object.keys(plugin.rules ?? {}).map((rule) => `${name}/${rule}`),
   );
@@ -145,12 +134,11 @@ const ruleIdsOf = (b: Block): string[] =>
  * one file more.
  */
 export function ruleOwners(
-  own: readonly unknown[],
+  own: readonly ConfigBlock[],
 ): Map<string, readonly OwnedScope[]> {
   const all = ownedScopes(own);
   const found = new Map<string, OwnedScope[]>();
-  for (const raw of own) {
-    const b = raw as Block;
+  for (const b of own) {
     const scopes =
       b.files === undefined
         ? all
@@ -171,17 +159,18 @@ export function narrowToOwners(
   block: RuleBlock,
   owners: ReadonlyMap<string, readonly OwnedScope[]>,
 ): ScopedBlock[] {
+  // Keyed by the owner's JSON, so rules with equal owners share one group of blocks.
   const groups = new Map<string, Record<string, RuleEntry>>();
+  const ownerOf = new Map<string, readonly OwnedScope[]>();
   for (const [id, entry] of Object.entries(block.rules)) {
     const owner = owners.get(id);
     if (owner === undefined) continue;
     const key = JSON.stringify(owner);
     groups.set(key, { ...groups.get(key), [id]: entry });
+    ownerOf.set(key, owner);
   }
-  return [...groups].flatMap(([key, rules]) =>
-    (JSON.parse(key) as OwnedScope[]).map((scope) =>
-      within(block, scope, rules),
-    ),
+  return [...ownerOf].flatMap(([key, owner]) =>
+    owner.map((scope) => within(block, scope, { ...groups.get(key) })),
   );
 }
 

package/src/paper-settings.test.ts

@@ -4,7 +4,7 @@
  */
 import { describe, expect, it } from "vitest";
 import { memoryFiles } from "./adapters/memory/index.ts";
-import type { AbsolutePath } from "./domain/paths.ts";
+import { absolutePath } from "./domain/paths.ts";
 import { findProjectRoot } from "../lib/paper-config.ts";
 import {
   paperRules,
@@ -215,7 +215,7 @@ describe("findProjectRoot — where the root paperlint.json is looked for", () =
       [`${PAPER}/paperlint.json`]: '{"kind":"research"}',
       [`${ROOT}/paperlint.json`]: '{"extends":"paperlint:aisec"}',
     });
-    const isFile = (p: string) => files.isFile(p as AbsolutePath);
+    const isFile = (p: string) => files.isFile(absolutePath(p));
     expect(findProjectRoot(PAPER, isFile)).toBe(ROOT);
     // No root file anywhere: the package.json directory.
     expect(findProjectRoot(PAPER, (p) => p === `${ROOT}/package.json`)).toBe(

package/src/paper-settings.ts

@@ -22,7 +22,7 @@ import {
   SETTINGS_KEYS,
   findProjectRoot,
 } from "#lib/paper-config";
-import type { AbsolutePath } from "./domain/paths.ts";
+import { callerPath } from "./caller-path.ts";
 import { err, ok, type Result } from "./domain/result.ts";
 import type { Files } from "./ports/files.ts";
 import {
@@ -114,14 +114,12 @@ export function parsePaperSettings(
   });
 }
 
-const at = (p: string): AbsolutePath => p as AbsolutePath;
-
 /** A JSON file through `files`: undefined when absent, the problem when it does not parse. */
 function readJson(
   files: Files,
   path: string,
 ): Result<unknown, SettingsProblem> {
-  const bytes = files.readBytes(at(path));
+  const bytes = files.readBytes(callerPath(path));
   if (bytes === null) return ok(undefined);
   try {
     return ok(JSON.parse(new TextDecoder().decode(bytes)));
@@ -139,7 +137,9 @@ function rootDefaults(
   files: Files,
   paperDir: string,
 ): Result<Defaults | null, SettingsProblem> {
-  const root = findProjectRoot(dirname(paperDir), (p) => files.isFile(at(p)));
+  const root = findProjectRoot(dirname(paperDir), (p) =>
+    files.isFile(callerPath(p)),
+  );
   const json = readJson(files, join(root, CONFIG_FILE));
   if (!json.ok) return json;
   if (!isObject(json.value)) return ok(null);

package/src/pdf-facts.test.ts

@@ -40,11 +40,11 @@ function page(items: FakeItem[], fonts: Record<string, unknown>) {
     }),
   };
 }
-const doc = (pages: ReturnType<typeof page>[]) =>
-  ({
-    numPages: pages.length,
-    getPage: (i: number) => Promise.resolve(pages[i - 1]),
-  }) as never;
+const doc = (pages: ReturnType<typeof page>[]) => ({
+  numPages: pages.length,
+  getPage: (i: number) =>
+    Promise.resolve(present(pages[i - 1], `page ${String(i)}`)),
+});
 const item = (
   fontName: string,
   transform: number[],
@@ -141,3 +141,14 @@ test("a failure that is not an Error is named `Error` with its text", () => {
     detail: "Error: boom",
   });
 });
+
+test("🔴 a rejection with no value at all is a failure too, not a TypeError out of `readPdf`", () => {
+  // Guards: `readPdf` ends in `.catch(failureOf)`, and reading `.name` off `null` threw from inside it.
+  assert.deepEqual(
+    [failureOf(null), failureOf(undefined)],
+    [
+      { ok: false, reason: "unreadable", detail: "Error: null" },
+      { ok: false, reason: "unreadable", detail: "Error: undefined" },
+    ],
+  );
+});