paperlint 3.1.2 → 3.2.0

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(
@@ -109,7 +120,7 @@ try {
 
   // ── 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 +151,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 +163,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 +205,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 +259,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 +276,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 +295,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 +310,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,7 @@ import {
   BIN_FILE,
   PACKAGE_NAME,
 } from "../skills/paper-pipeline/scripts/consumer.mjs";
+import { messageOf } from "./domain/text.ts";
 
 /** The committed, shared settings file — husky's `.husky/` analogue, except git carries it. */
 export const SETTINGS_PATH = join(".claude", "settings.json");
@@ -133,17 +134,23 @@ 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;
+
 export interface Wiring {
   readonly compiled: HooksMap;
   /** Derived from the commands, in order. Never empty — an empty set throws. */
@@ -195,7 +202,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;
@@ -218,7 +229,7 @@ export function readSettings(root: string): SettingsRead {
       return { status: "unparsable", path, reason: "not a JSON object" };
     return { status: "read", path, settings: parsed as Settings, raw };
   } catch (e) {
-    return { status: "unparsable", path, reason: (e as Error).message };
+    return { status: "unparsable", path, reason: messageOf(e) };
   }
 }
 

package/src/init.test.ts

@@ -34,7 +34,7 @@ import {
   reportTexLive,
   reportWorkflow,
 } from "./init.ts";
-import { runNode } from "../test/support.mjs";
+import { runNode } from "../test/support.ts";
 
 const dirs: string[] = [];
 afterEach(() => {
@@ -81,7 +81,9 @@ describe("paperlint init — a declared papers directory", () => {
     expect(code).toBe(0);
     expect(section).toMatch(/✓ papers — declared in paperlint\.json/);
     expect(section).not.toMatch(/candidates|eslint-rules|drafts/);
-    const cfg = JSON.parse(readFileSync(join(root, "paperlint.json"), "utf8"));
+    const cfg: unknown = JSON.parse(
+      readFileSync(join(root, "paperlint.json"), "utf8"),
+    );
     expect(cfg).toEqual({ papersDir: "papers" });
   });
 
@@ -93,7 +95,7 @@ describe("paperlint init — a declared papers directory", () => {
       log: () => {},
       err: () => {},
       interactive: true,
-      ask: async (q) => (asked.push(q), "n"),
+      ask: (q) => Promise.resolve((asked.push(q), "n")),
       hooks: false,
       run: (() => ({ status: 0 })) as never,
       link: () => ({ ok: false, error: "not linked in this test" }),
@@ -165,7 +167,8 @@ const texRun = async (
     log: (s: string) => out.push(s),
     err: () => {},
     interactive,
-    ask: async (q) => (asked.push(q), /TeX Live/.test(q) ? answer : ""),
+    ask: (q) =>
+      Promise.resolve((asked.push(q), /TeX Live/.test(q) ? answer : "")),
     hooks: false,
     run: (() => ({ status: 0 })) as never,
     link: () => ({ ok: false as const, error: "not linked in this test" }),
@@ -301,7 +304,7 @@ describe("paperlint init — how several candidate directories were decided, sai
   it("picked by a human", async () => {
     const r = await initRun(several(), {
       interactive: true,
-      ask: async () => "2",
+      ask: () => Promise.resolve("2"),
     });
     expect(section(r.out)).toEqual([
       "  ✓ writing — you picked it out of 2 candidates",
@@ -319,7 +322,7 @@ describe("paperlint init — how several candidate directories were decided, sai
   it("an answer that picks nothing: the first, and said so", async () => {
     const r = await initRun(several(), {
       interactive: true,
-      ask: async () => "nine",
+      ask: () => Promise.resolve("nine"),
     });
     expect(section(r.out)[0]).toBe(
       "  ✓ drafts — 2 candidates, no answer was given, so the first one was taken",
@@ -433,7 +436,7 @@ describe("paperlint init — TeX Live and hooks failures, whole", () => {
   it("TeX Live: a failed install says to run it again", async () => {
     const t = await offerTexLive(
       { installed: () => false, install: () => 1 },
-      { interactive: true, ask: async () => "yes" },
+      { interactive: true, ask: () => Promise.resolve("yes") },
     );
     expect([t, reportTexLive(t, "")]).toEqual([
       "failed",
@@ -462,8 +465,8 @@ describe("paperlint init — a first paper", () => {
     const made: string[] = [];
     const r = await initRun(tree({}), {
       interactive: true,
-      ask: async () => "",
-      createPaper: async (_root, name) => (made.push(name), 0),
+      ask: () => Promise.resolve(""),
+      createPaper: (_root, name) => Promise.resolve((made.push(name), 0)),
     });
     expect(made).toEqual([]);
     expect(r.out[r.out.indexOf("first paper") + 1]).toBe(

package/src/init.ts

@@ -64,13 +64,15 @@ import {
   nameProblem,
   type PaperFormat,
 } from "./new-paper.ts";
-// The one source for the consumer's config key lives in the .mjs half of the package (the ESLint
-// rules and the skill scripts import it too); its types are in lib/paper-config.d.mts.
+// The one source for the consumer's config key lives in lib/ (the ESLint rules and the skill scripts
+// import it too). It is imported compiled, from dist/, the one path that resolves the same from src/
+// and from dist/ — see CONTRIBUTING.md.
 import {
   CONFIG_FILE,
   DEFAULT_PAPERS_ROOT,
   PAPERS_DIR_FIELD,
-} from "../lib/paper-config.mjs";
+} from "#lib/paper-config";
+import { messageOf } from "./domain/text.ts";
 
 /** How the papers directory was arrived at. Printed, because a guess must not read as a fact. */
 export type PapersHow =
@@ -122,13 +124,21 @@ export function interactivity({
   return { interactive: true, why: "a terminal on both ends" };
 }
 
+/**
+ * Whether a standard stream is a terminal. Node types `isTTY` as `boolean`, but on a stream that
+ * is NOT a terminal (a pipe, a file) the property is absent — `undefined` — so it is read as the
+ * optional it really is.
+ */
+const isTty = (stream: { readonly isTTY?: boolean }): boolean =>
+  stream.isTTY === true;
+
 /** The mode of THIS process — the one place `process` is read for it. */
 export const processInteractivity = (yes: boolean) =>
   interactivity({
     // eslint-disable-next-line no-restricted-globals -- legacy I/O, moves behind a port in #76
-    stdinTTY: Boolean(process.stdin.isTTY),
+    stdinTTY: isTty(process.stdin),
     // eslint-disable-next-line no-restricted-globals -- legacy I/O, moves behind a port in #76
-    stdoutTTY: Boolean(process.stdout.isTTY),
+    stdoutTTY: isTty(process.stdout),
     // eslint-disable-next-line no-restricted-globals -- legacy I/O, moves behind a port in #76
     env: process.env,
     yes,
@@ -222,7 +232,7 @@ export async function declarePapers(
     try {
       settings = JSON.parse(raw) as Record<string, unknown>;
     } catch (e) {
-      return { status: "unparsable", path, reason: (e as Error).message };
+      return { status: "unparsable", path, reason: messageOf(e) };
     }
     const existing = settings[PAPERS_DIR_FIELD];
     if (existing !== undefined)
@@ -289,7 +299,7 @@ export async function offerWorkflow(
     ask?: (q: string) => Promise<string>;
     interactive: boolean;
     /** The running package's version; see `InitOptions.version`. */
-    version?: string;
+    version?: string | undefined;
   },
 ): Promise<WorkflowResult> {
   const path = join(root, WORKFLOW_PATH);
@@ -317,7 +327,7 @@ export function reportWorkflow(
     version,
     papersDir,
     why,
-  }: { version?: string; papersDir: string; why: string },
+  }: { version?: string | undefined; papersDir: string; why: string },
 ): string[] {
   const ref = actionRef(version);
   const out: string[] = [];
@@ -406,7 +416,7 @@ export async function offerHooks(
     hooks: boolean;
     interactive: boolean;
     ask?: (q: string) => Promise<string>;
-    merge?: Merge;
+    merge?: Merge | undefined;
   },
 ): Promise<HooksOutcome> {
   if (!hooks) return { status: "skipped" };
@@ -438,7 +448,7 @@ export async function offerHooks(
     }
     return wireHooks(root, m, shippedWiring());
   } catch (e) {
-    return { status: "failed", reason: (e as Error).message };
+    return { status: "failed", reason: messageOf(e) };
   }
 }
 
@@ -560,7 +570,7 @@ export interface InitOptions {
   /** `false` is `--no-hooks`. */
   hooks?: boolean;
   /** vigiles' merge. Injected only so a test can observe or replace it. */
-  merge?: Merge;
+  merge?: Merge | undefined;
   /** `--paper <name>`: create this paper, even without a terminal. */
   paper?: string | null;
   /** `--format tex|md` for that paper. */
@@ -586,7 +596,7 @@ export interface InitOptions {
    * The version of the running package, read by the CLI from its own `package.json`. The CI
    * workflow is pinned to its release tag (`actionRef`); absent or unreleased, the placeholder.
    */
-  version?: string;
+  version?: string | undefined;
   /**
    * TeX Live for `paperlint build`: whether paperlint's own tree is installed, and how to install
    * it (`paperlint toolchain`). Passed in by the CLI; without them the step only names the command.

package/src/{latex-log.harness.mjs → latex-log.harness.ts}

@@ -5,11 +5,9 @@
  * memory: the two error spellings `-file-line-error` produces, the missing-package form, and a
  * marker that TeX broke at column 79.
  */
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-import { createChecker } from "../lib/check.mjs";
+import { createChecker } from "../lib/check.ts";
+import type { LogMarker } from "./latex-log.ts";
 
-const HERE = dirname(fileURLToPath(import.meta.url));
 const {
   unwrapLog,
   logMarkers,
@@ -18,7 +16,7 @@ const {
   bibtexExcerpt,
   auxBib,
   MAX_PRINT_LINE,
-} = await import(join(HERE, "latex-log.ts"));
+} = await import("./latex-log.ts");
 
 const check = createChecker();
 
@@ -78,13 +76,15 @@ const firstPass = [
 const m = logMarkers(firstPass);
 check(
   "every documented marker is recognised",
-  [
-    "rerun-requested",
-    "labels-changed",
-    "rerunfilecheck",
-    "undefined-references",
-    "undefined-citations",
-  ].every((k) => m.includes(k)),
+  (
+    [
+      "rerun-requested",
+      "labels-changed",
+      "rerunfilecheck",
+      "undefined-references",
+      "undefined-citations",
+    ] satisfies LogMarker[]
+  ).every((k) => m.includes(k)),
 );
 check(
   "a clean log carries no markers",
@@ -96,7 +96,7 @@ check(
 // Guards: matching the documented summary line rather than the word 'undefined'.
 check(
   "a single reference warning is not the end-of-run summary",
-  !logMarkers([firstPass[0]]).includes("undefined-references"),
+  !logMarkers(firstPass.slice(0, 1)).includes("undefined-references"),
 );
 
 // ── error excerpt ───────────────────────────────────────────────────────────────────────
@@ -114,7 +114,7 @@ check(
   "-file-line-error form: the error line, the l.NNN line and the rest of the source line",
   ex[0] === "./paper.tex:4: Undefined control sequence." &&
     ex[1] === "l.4 \\foo" &&
-    ex[2].includes("bar baz"),
+    (ex[2] ?? "").includes("bar baz"),
 );
 // Guards: the end of the excerpt — without it the excerpt runs into TeX's memory statistics and
 // buries the line the author needs.