paperlint 2.0.0

package/src/hooks-settings.harness.mjs

@@ -0,0 +1,386 @@
+/**
+ * Both halves for `hooks-settings.ts` — the three hooks written into `.claude/settings.json`.
+ *
+ * The merge under test is vigiles' REAL one (`vigiles/claude-code`), not a stand-in: the claims
+ * that matter — a user's hook in the same matcher survives, a second run is byte-identical — are
+ * claims about that function meeting our wiring, and a fake would only test the fake.
+ *
+ * What each block defends against, in real life:
+ *   - a SECOND copy of a hook wired by hand under another spelling: Claude Code dedupes only
+ *     identical handlers, so the guard would run twice and nothing would say so;
+ *   - a rewrite on every `init`: the settings file is committed, so churn is a diff someone reviews
+ *     for nothing — and a reformat of the user's own file is a change they did not ask for;
+ *   - a doctor that says "wired" over nothing, or offers a remedy `init` then refuses to apply.
+ *
+ * ⚠️ 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,
+  mkdtempSync,
+  readFileSync,
+  realpathSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const {
+  hookRun,
+  shippedWiring,
+  wireHooks,
+  wiredCounts,
+  pluginEnabledHere,
+  doctorHooks,
+  readSettings,
+  MANAGED_BY,
+  LEGACY_MANAGED_BY,
+  SETTINGS_PATH,
+} = await import(join(HERE, "hooks-settings.ts"));
+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);
+};
+
+// ── 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",
+);
+
+// ── the one source: plugin/hooks/hooks.json ─────────────────────────────────────────────
+const wiring = shippedWiring();
+check(
+  "the hook names are DERIVED from hooks.json — three, in its order",
+  wiring.names.join() ===
+    "paper-edit-guard,paper-skills-nudge,paper-status-gates",
+);
+const work = realpathSync(mkdtempSync(join(tmpdir(), "rpp-hooks-")));
+try {
+  const empty = join(work, "empty-hooks.json");
+  writeFileSync(empty, '{"hooks":{}}');
+  let threw = false;
+  try {
+    shippedWiring(empty);
+  } catch {
+    threw = true;
+  }
+  check(
+    "a wiring file naming no hook THROWS — wiring nothing must not read as wired",
+    threw,
+  );
+
+  // ── which spelling runs which hook ─────────────────────────────────────────────────────
+  const ours = `node "\${CLAUDE_PROJECT_DIR}/${MANAGED_BY}" hook paper-edit-guard`;
+  const cases = [
+    [ours, { name: "paper-edit-guard", ours: true, legacy: false }],
+    [
+      `node "$CLAUDE_PROJECT_DIR/${MANAGED_BY}" hook paper-status-gates`,
+      { name: "paper-status-gates", ours: true, legacy: false },
+    ],
+    // Guards: what an install under the old package name wrote is recognised as ours-but-stale.
+    [
+      `node "$CLAUDE_PROJECT_DIR/${LEGACY_MANAGED_BY}" hook paper-edit-guard`,
+      { name: "paper-edit-guard", ours: false, legacy: true },
+    ],
+    [
+      `node "$CLAUDE_PROJECT_DIR/node_modules/vigiles/dist/cli.js" hook-runtime run-program "$CLAUDE_PROJECT_DIR/node_modules/paperlint/hooks/paper-edit-guard.hook.mjs"`,
+      { name: "paper-edit-guard", ours: false, legacy: false },
+    ],
+    [
+      `npx paperlint hook paper-skills-nudge`,
+      { name: "paper-skills-nudge", ours: false, legacy: false },
+    ],
+    [
+      `npx paperlint hook paper-skills-nudge`,
+      { name: "paper-skills-nudge", ours: false, legacy: false },
+    ],
+    [
+      `node /abs/proj/node_modules/paperlint/bin/rpp.mjs hook paper-edit-guard`,
+      { name: "paper-edit-guard", ours: false, legacy: false },
+    ],
+    [`node my-own-lint.mjs`, null],
+    [`node node_modules/paperlint/bin/rpp.mjs lint`, null],
+  ];
+  for (const [cmd, want] of cases)
+    check(
+      `hookRun(${cmd.slice(0, 60)}…) → ${JSON.stringify(want)}`,
+      JSON.stringify(hookRun(cmd)) === JSON.stringify(want),
+    );
+
+  const project = (name, settings) => {
+    const dir = join(work, name);
+    mkdirSync(join(dir, ".claude"), { recursive: true });
+    if (settings !== undefined)
+      writeFileSync(
+        join(dir, SETTINGS_PATH),
+        typeof settings === "string"
+          ? settings
+          : JSON.stringify(settings, null, 2) + "\n",
+      );
+    return dir;
+  };
+  const text = (dir) => readFileSync(join(dir, SETTINGS_PATH), "utf8");
+
+  // ── a fresh project ────────────────────────────────────────────────────────────────────
+  {
+    const dir = join(work, "fresh");
+    mkdirSync(dir);
+    const r = wireHooks(dir, merge, wiring);
+    const s = JSON.parse(text(dir));
+    check(
+      "no settings file → it is created with the three hooks",
+      r.status === "written" &&
+        [...wiredCounts(s, wiring.names).values()].every(
+          (c) => c.ours === 1 && c.other === 0,
+        ),
+    );
+    const before = text(dir);
+    const again = wireHooks(dir, merge, wiring);
+    check(
+      "🔴 a second run changes NOTHING — byte-identical, status `present`",
+      again.status === "present" && text(dir) === before,
+    );
+  }
+
+  // ── an install under the old package name is migrated, the user's own command kept ─────
+  {
+    const legacyWired = JSON.parse(
+      JSON.stringify(merge({}, wiring.compiled, MANAGED_BY)).replaceAll(
+        MANAGED_BY,
+        LEGACY_MANAGED_BY,
+      ),
+    );
+    legacyWired.hooks.PostToolUse[0].hooks.push({
+      type: "command",
+      command: "node my-own-lint.mjs",
+    });
+    const dir = project("legacy", legacyWired);
+    const before = doctorHooks(dir, wiring).join("\n");
+    check(
+      "🔴 doctor names hook commands left under the old package name, and the fix",
+      /still point into node_modules\/research-paper-pipeline\//.test(before) &&
+        /npx paperlint init` replaces them/.test(before),
+    );
+    const r = wireHooks(dir, merge, wiring);
+    const s = JSON.parse(text(dir));
+    const counts = [...wiredCounts(s, wiring.names).values()];
+    check(
+      "🔴 init replaces them: every hook wired once under the new name, none left under the old",
+      r.status === "written" &&
+        r.replaced === wiring.names.length &&
+        counts.every((c) => c.ours === 1 && c.legacy === 0 && c.other === 0) &&
+        !text(dir).includes("research-paper-pipeline"),
+    );
+    check(
+      "and the user's own command in the same matcher survives the migration",
+      text(dir).includes("node my-own-lint.mjs"),
+    );
+  }
+
+  // ── the user's own hooks and keys survive ──────────────────────────────────────────────
+  {
+    const dir = project("user", {
+      permissions: { allow: ["Bash(ls:*)"] },
+      hooks: {
+        PostToolUse: [
+          {
+            matcher: "Edit|Write|MultiEdit",
+            hooks: [{ type: "command", command: "node my-own-lint.mjs" }],
+          },
+        ],
+      },
+    });
+    wireHooks(dir, merge, wiring);
+    const s = JSON.parse(text(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:*)",
+    );
+    check(
+      "and ours are there, once each",
+      [...wiredCounts(s, wiring.names).values()].every((c) => c.ours === 1),
+    );
+  }
+
+  // ── already wired, in someone else's formatting → the file is not touched ──────────────
+  {
+    const wired = merge({}, wiring.compiled, MANAGED_BY);
+    const fourSpaces = JSON.stringify(wired, null, 4);
+    const dir = project("formatted", fourSpaces);
+    const r = wireHooks(dir, merge, wiring);
+    check(
+      "🔴 wired already → nothing is rewritten, not even to our indentation",
+      r.status === "present" && text(dir) === fourSpaces,
+    );
+  }
+
+  // ── another spelling of the same hook → write NOTHING ──────────────────────────────────
+  {
+    const handWired = {
+      hooks: {
+        PreToolUse: [
+          {
+            matcher: "Bash",
+            hooks: [
+              {
+                type: "command",
+                command:
+                  'node "$CLAUDE_PROJECT_DIR/node_modules/vigiles/dist/cli.js" hook-runtime run-program "$CLAUDE_PROJECT_DIR/node_modules/research-paper-pipeline/hooks/paper-edit-guard.hook.mjs"',
+              },
+            ],
+          },
+        ],
+      },
+    };
+    const dir = project("foreign", handWired);
+    const before = text(dir);
+    const r = wireHooks(dir, merge, wiring);
+    check(
+      "🔴 a hook wired by hand under another spelling → `foreign`, and the file is untouched",
+      r.status === "foreign" && text(dir) === before,
+    );
+    check(
+      "the report names the hook and the command it found",
+      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",
+    );
+    // 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");
+    check(
+      "(control) vigiles' merge alone would wire paper-edit-guard TWICE here",
+      c.ours === 1 && c.other === 1,
+    );
+  }
+
+  // ── a file that does not parse is reported, never overwritten ──────────────────────────
+  {
+    const dir = project("broken", "{ not json");
+    const r = wireHooks(dir, merge, wiring);
+    check(
+      "an unparsable settings.json → `unparsable`, bytes untouched",
+      r.status === "unparsable" && text(dir) === "{ not json",
+    );
+    check(
+      "an array is not a settings object either",
+      readSettings(project("array", "[]\n")).status === "unparsable",
+    );
+  }
+
+  // ── the plugin, enabled by the project ─────────────────────────────────────────────────
+  check(
+    "the project's enabledPlugins entry for this package is found",
+    pluginEnabledHere({
+      enabledPlugins: {
+        "research-paper-pipeline@research-paper-pipeline": true,
+        "other@x": true,
+      },
+    }).join() === "research-paper-pipeline@research-paper-pipeline",
+  );
+  check(
+    "a disabled entry does not count",
+    pluginEnabledHere({
+      enabledPlugins: {
+        "research-paper-pipeline@research-paper-pipeline": false,
+      },
+    }).length === 0,
+  );
+
+  // ── doctor's section ───────────────────────────────────────────────────────────────────
+  const doc = (settings) => {
+    const dir = project(`doc-${String(n)}`, settings);
+    return doctorHooks(dir, wiring).join("\n");
+  };
+  const wiredOnce = merge({}, wiring.compiled, MANAGED_BY);
+  check(
+    "wired once each → ✓ wired, with the fresh-clone consequence",
+    /✓ wired — paper-edit-guard, paper-skills-nudge, paper-status-gates, once each/.test(
+      doc(wiredOnce),
+    ) && /cannot run until `npm install`/.test(doc(wiredOnce)),
+  );
+  check(
+    "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({
+    type: "command",
+    command: "npx paperlint hook paper-edit-guard",
+  });
+  const twiceText = doc(twice);
+  check(
+    "🔴 the same hook under two spellings → ⚠ wired TWICE, naming it with its count",
+    /wired TWICE/.test(twiceText) &&
+      /paper-edit-guard ×2/.test(twiceText) &&
+      !/✓ wired/.test(twiceText),
+  );
+  const handPartial = doc({
+    hooks: {
+      PreToolUse: [
+        {
+          matcher: "Bash",
+          hooks: [
+            { type: "command", command: "npx paperlint hook paper-edit-guard" },
+          ],
+        },
+      ],
+    },
+  });
+  check(
+    "🔴 partly wired BY HAND → the remedy is NOT `npx paperlint init`, which would refuse to write",
+    /partly wired — missing: paper-skills-nudge, paper-status-gates/.test(
+      handPartial,
+    ) && /writes nothing then/.test(handPartial),
+  );
+  const pluginText = doc({
+    ...wiredOnce,
+    enabledPlugins: { "research-paper-pipeline@research-paper-pipeline": true },
+  });
+  check(
+    "the project also enabling the plugin → told to uninstall it, with the command",
+    /ALSO enables the plugin/.test(pluginText) &&
+      /\/plugin uninstall research-paper-pipeline@research-paper-pipeline/.test(
+        pluginText,
+      ),
+  );
+  check(
+    "🔴 and it says it cannot see a USER-scope plugin, rather than implying there is none",
+    /USER scope is not visible from here/.test(doc({})),
+  );
+  check(
+    "an unparsable file is named in doctor, not crashed on",
+    /does not parse/.test(
+      doctorHooks(project("doc-broken", "{"), wiring).join("\n"),
+    ),
+  );
+  check(
+    "(the scratch projects exist — nothing above was vacuous)",
+    existsSync(work),
+  );
+} finally {
+  rmSync(work, { recursive: true, force: true });
+}
+
+console.log(
+  `✓ ${String(n)} assertions passed — the hooks land in .claude/settings.json once`,
+);

package/src/hooks-settings.mutations.mjs

@@ -0,0 +1,116 @@
+/**
+ * Battery for `hooks-settings.ts`.
+ *
+ * Every case reintroduces a way the hooks end up wired wrong while every report stays green:
+ * twice (a guard that runs two times says nothing about it), rewritten on every run (a committed
+ * file that churns for nothing), or reported as fine when doctor was asked about the wrong thing.
+ */
+import { fileURLToPath } from "node:url";
+import { dirname, join, resolve } from "node:path";
+import { runMutations } from "../lib/mutation-driver.mjs";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const ROOT = resolve(HERE, "..");
+const SRC = join(HERE, "hooks-settings.ts");
+const HARNESS = join(HERE, "hooks-settings.harness.mjs");
+
+process.exit(
+  runMutations({
+    root: ROOT,
+    runner: "node",
+    cases: [
+      {
+        name: "every spelling of the bin counts as ours",
+        harness: HARNESS,
+        // The spelling truth table is the first owner: `npx paperlint hook …` must read as NOT ours,
+        // and that row is where it goes red.
+        expect: '→ {"name":"paper-edit-guard","ours":false,"legacy":true}',
+        disables:
+          "the duplicate guard for every bin spelling but ours. A hook wired by hand as " +
+          "`npx paperlint hook …` or through an absolute rpp.mjs path reads as ours, init merges its own " +
+          "copy beside it, and the hook runs twice per event",
+        edits: [
+          [SRC, "        ours: t === MANAGED_BY,", "        ours: true,"],
+        ],
+      },
+      {
+        name: "another spelling no longer stops the write",
+        harness: HARNESS,
+        expect: "a hook wired by hand under another spelling",
+        disables:
+          "the refusal itself: the foreign command is found and then written over anyway",
+        edits: [[SRC, "  if (found.length > 0) {", "  if (false) {"]],
+      },
+      {
+        name: "the settings file is rewritten even when nothing changed",
+        harness: HARNESS,
+        // The fresh project's second run is the first place a rewrite shows: `written` twice.
+        expect: "a second run changes NOTHING",
+        disables:
+          "idempotency as the user sees it. Every init would reformat a committed file the user " +
+          "wrote, and the diff would say nothing happened while showing that everything did",
+        edits: [
+          [
+            SRC,
+            "  if (JSON.stringify(next) === JSON.stringify(read.settings))",
+            "  if (false)",
+          ],
+        ],
+      },
+      {
+        name: "the project-dir prefix is not stripped",
+        harness: HARNESS,
+        expect: "hookRun(",
+        disables:
+          "recognising the spelling init itself writes. `${CLAUDE_PROJECT_DIR}/node_modules/…` " +
+          "stops matching, so a second init sees a foreign hook where its own stands",
+        edits: [
+          [
+            SRC,
+            '  return unquoted.replace(/^\\$\\{?CLAUDE_PROJECT_DIR\\}?[/\\\\]/, "");',
+            "  return unquoted;",
+          ],
+        ],
+      },
+      {
+        name: "doctor stops counting duplicates",
+        harness: HARNESS,
+        expect: "the same hook under two spellings",
+        disables:
+          "the only report of a guard that runs twice. Claude Code dedupes only identical " +
+          "handlers, so two spellings both run and nothing else would say so",
+        edits: [
+          [
+            SRC,
+            "  const twice = wiring.names.filter((n) => total(n) > 1);",
+            "  const twice = wiring.names.filter((n) => total(n) > 2);",
+          ],
+        ],
+      },
+      {
+        name: "doctor offers `paperlint init` even where init refuses to write",
+        harness: HARNESS,
+        expect: "partly wired BY HAND",
+        disables:
+          "a remedy that works. The reader runs init, init writes nothing, and doctor says the " +
+          "same thing again — a loop with no exit",
+        edits: [[SRC, "  const remedy = handWired", "  const remedy = false"]],
+      },
+      {
+        name: "a disabled plugin counts as enabled",
+        harness: HARNESS,
+        expect: "a disabled entry does not count",
+        disables:
+          "the plugin warning's precision. A project that already switched the plugin off would " +
+          "be told to uninstall it",
+        edits: [
+          [
+            SRC,
+            '      ([id, on]) => on === true && id.split("@")[0] === LEGACY_PACKAGE_NAME,',
+            '      ([id]) => id.split("@")[0] === LEGACY_PACKAGE_NAME,',
+          ],
+        ],
+      },
+    ],
+  }),
+);