paperlint 3.0.0 → 3.1.1

package/skills/paper-pipeline/scripts/generated-code.harness.mjs

@@ -114,7 +114,7 @@ function fixture({ scripts = {}, allow = null, bundle = {}, at = "repro" }) {
       "explicit",
       "import random\nrandom.seed(7)\nrows = random.sample(all_rows, 30)\n",
     ],
-    // 🔴 THIS FIXTURE WAS VACUOUS IN ITS FIRST FORM and the mutations file caught it. It drew with
+    // 🔴 THIS FIXTURE WAS VACUOUS IN ITS FIRST FORM. It drew with
     // `rnd.sample(...)` off a local `random.Random(...)`, which the DRAWS pattern does not recognise
     // as a draw at all — so the case passed because NOTHING was detected, not because the seed was.
     // Neutering the `--seed` alternation changed no verdict. It now draws with `np.random.choice`,
@@ -243,9 +243,9 @@ function fixture({ scripts = {}, allow = null, bundle = {}, at = "repro" }) {
 // ever fails, one of the two checks should be deleted rather than both kept.
 {
   // Silence asserted through --flags-only rather than through the header's count, so that this case
-  // tests the EXCLUSION and not the count. Sharing the count assertion with case 11 made a mutation
-  // of the header land here instead, which reads as an off-target kill and hides which property
-  // actually failed.
+  // tests the EXCLUSION and not the count. Sharing the count assertion with case 11 meant a defect
+  // in the header would be caught here instead, which reads as an off-target result and hides
+  // which property actually failed.
   const r = run(
     fixture({ bundle: { "leak.py": 'open("/home/example/secret.tsv")\n' } }),
     false,

package/skills/paper-pipeline/scripts/generated-code.mjs

@@ -252,8 +252,9 @@ for (const f of files.sort()) {
 
   // 🔴 `ABS.flags`, not a literal 'g'. The first version passed 'g' alone, which silently DROPPED
   // the case-sensitivity that keeps an Express route `/users/export` from matching `/Users/` —
-  // so the property the harness asserts lived nowhere the harness could reach it. Found by the
-  // mutations file: adding an `i` to ABS changed no verdict, i.e. a mutation that did not mutate.
+  // so the property the harness asserts lived nowhere the harness could reach it. Found by
+  // testing directly: adding an `i` to ABS changed no verdict, i.e. the property was
+  // unreachable.
   const abs = code.match(
     new RegExp(ABS.source + "[^\\s'\"`)\\],]*", ABS.flags + "g"),
   );

package/skills/paper-pipeline/scripts/generated-code.test.mjs

@@ -0,0 +1,62 @@
+/**
+ * generated-code.mjs on the inputs its harness does not build: no argument, a directory that does
+ * not exist, and a repro/ holding a dangling link, dot/dependency directories, trees deeper than
+ * the scan's depth (more than eight, so the list is elided), and an allow row with no reason.
+ */
+import assert from "node:assert/strict";
+import { symlinkSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { test } from "vitest";
+import { runNode, useTempDir, writeTree } from "../../../test/support.mjs";
+
+const SCRIPT = join(
+  dirname(fileURLToPath(import.meta.url)),
+  "generated-code.mjs",
+);
+const root = useTempDir("generated-code-");
+const run = (...args) => runNode(SCRIPT, args);
+
+test("no argument prints the usage; a directory that does not exist scanned nothing, and says so", () => {
+  assert.deepEqual(run(), {
+    status: 0,
+    stdout: "",
+    stderr: "usage: node generated-code.mjs <paper-dir> [--flags-only]\n",
+  });
+  const r = run(join(root, "nowhere"));
+  assert.equal(r.status, 0);
+  assert.match(
+    r.stdout,
+    /NOTHING WAS SCANNED: no repro\/ here or one level below/,
+  );
+});
+
+test("repro/: a dangling link is passed over; skipped trees are named, more than eight elided; a reasonless allow row says so", () => {
+  const deep = Object.fromEntries(
+    Array.from({ length: 10 }, (_, i) => [
+      `repro/exp/d${String(i)}/deeper/x.py`,
+      "print(1)\n",
+    ]),
+  );
+  const dir = writeTree(join(root, "paper"), {
+    ...deep,
+    "repro/.cache/x.py": "",
+    // eslint-disable-next-line port/js-install-path -- a fixture directory the scan must skip, not an install location
+    "repro/node_modules/x.js": "",
+    "repro/__pycache__/x.py": "",
+    // Draws randomness unseeded: a NO_SEED finding, which the reasonless row below waves through.
+    "repro/exp/run.py": "import random\nprint(random.random())\n",
+    "repro/generated-code-grandfathered.txt": "exp/run.py\t*\n",
+  });
+  symlinkSync(join(root, "gone"), join(dir, "repro", "dangling.py"));
+  const out = run(dir).stdout;
+  assert.match(
+    out,
+    /• 3 tree\(s\) not entered — dependency, VCS and build trees[^\n]*\n {7}\.cache, __pycache__, node_modules/,
+  );
+  assert.match(
+    out,
+    /• 10 tree\(s\) not entered — nested deeper than 3 levels[^\n]*\n {7}(?:exp\/d\d\/deeper, ){7}exp\/d\d\/deeper … and 2 more/,
+  );
+  assert.match(out, / {7}exp\/run\.py · NO_SEED {2}→ {2}\(NO REASON GIVEN\)/);
+});

package/skills/paper-pipeline/scripts/ledger.cli.test.mjs

@@ -0,0 +1,302 @@
+/**
+ * ledger.mjs — the `record`/`status` CLI every wired skill ends with, the refusals `record` makes,
+ * the evidence contract on a FINDING, and how rows from the retired vocabulary and rows out of
+ * time order are read. The ledger and the consumer are temp paths, set before import.
+ *
+ * Refusal messages are several lines of explanation; where the wording is not the subject, the
+ * FIRST line (which names the defect) and the exit code are compared.
+ */
+import assert from "node:assert/strict";
+import { cpSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterEach, test } from "vitest";
+import { runNode, useTempDir, writeTree } from "../../../test/support.mjs";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const SCRIPT = join(HERE, "ledger.mjs");
+const root = useTempDir("ledger-cli-");
+const consumer = join(root, "consumer");
+const LEDGER = join(root, "runs.jsonl");
+const paper = join(consumer, "papers", "p");
+writeTree(paper, {
+  "paper.md": "# P\n\ntext\n",
+  "counted.md": "---\nfindings: 2\n---\n",
+  "uncounted.md": "no frontmatter count\n",
+});
+cpSync(
+  join(HERE, "..", "..", "cold-read-diff"),
+  join(consumer, ".claude", "skills", "cold-read-diff"),
+  {
+    recursive: true,
+    verbatimSymlinks: true,
+  },
+);
+const env = { CLAUDE_PROJECT_DIR: consumer, PIPELINE_LEDGER: LEDGER };
+Object.assign(process.env, env);
+const { readLedger, record, status } = await import("./ledger.mjs");
+afterEach(() => rmSync(LEDGER, { force: true }));
+
+const cli = (...args) => runNode(SCRIPT, args, { env });
+const firstLine = (s) => s.trim().split("\n")[0];
+const kinds = () =>
+  readLedger().map((r) => `${r.kind} ${r.findings} ${r.blocking}`);
+
+test("record FINDING with a report that states the same count: one row, printed, exit 0", () => {
+  const r = cli(
+    "record",
+    "cold-read-diff",
+    paper,
+    "FINDING",
+    "2",
+    "counted.md",
+    "--blocking",
+    "--check=sub",
+  );
+  const row = JSON.parse(r.stdout);
+  assert.deepEqual(
+    { status: r.status, stderr: r.stderr, check: row.check, kinds: kinds() },
+    { status: 0, stderr: "", check: "sub", kinds: ["FINDING 2 true"] },
+  );
+});
+
+test("the evidence contract: no path, a path to nothing, a disagreeing count — recorded, then exit 1", () => {
+  const cases = [
+    ["FINDING", "2"],
+    ["FINDING", "2", "missing.md"],
+    ["FINDING", "3", "counted.md"],
+  ].map((args) => {
+    const r = cli("record", "cold-read-diff", paper, ...args);
+    return [r.status, firstLine(r.stderr)];
+  });
+  assert.deepEqual(
+    { cases, kinds: kinds() },
+    {
+      cases: [
+        [1, "🔴 cold-read-diff: recorded 2 finding(s) with NO report path."],
+        [
+          1,
+          '🔴 cold-read-diff: recorded report path "missing.md" — nothing is there.',
+        ],
+        [
+          1,
+          "🔴 cold-read-diff: the ledger says 3 finding(s), counted.md says 2.",
+        ],
+      ],
+      kinds: ["FINDING 2 false", "FINDING 2 false", "FINDING 3 false"],
+    },
+  );
+});
+
+test("a report that states no count is only a nudge: recorded, exit 0", () => {
+  const r = cli(
+    "record",
+    "cold-read-diff",
+    paper,
+    "FINDING",
+    "1",
+    "uncounted.md",
+  );
+  assert.deepEqual(
+    { status: r.status, nudge: firstLine(r.stderr) },
+    {
+      status: 0,
+      nudge:
+        "⚠️  cold-read-diff: uncounted.md does not state its own finding count.",
+    },
+  );
+});
+
+test("refusals before writing: a retired kind, an unknown kind, a free-text reason, a finding of zero", () => {
+  const cases = [
+    ["PASS"],
+    ["probably fine"],
+    ["ABSTAINED", "looked fine"],
+    ["FINDING", "0", "counted.md"],
+    ["ABSTAINED", "no-witness", "a note"],
+  ].map((args) => {
+    const r = cli("record", "cold-read-diff", paper, ...args);
+    return [
+      r.status,
+      r.status === 0 ? JSON.parse(r.stdout).reason : firstLine(r.stderr),
+    ];
+  });
+  assert.deepEqual(
+    { cases, kinds: kinds() },
+    {
+      cases: [
+        [
+          2,
+          '🔴 "PASS" is not a verdict any more — deleted: it stored "nothing was wrong" as a value. Record ABSTAINED `no-witness`, and let the reader derive cleanliness from the absence of findings.',
+        ],
+        [2, '🔴 kind must be one of FINDING|ABSTAINED, got "probably fine"'],
+        [
+          2,
+          '🔴 ABSTAINED needs a reason from started|no-witness|input-missing|blocked|crashed, got "looked fine".',
+        ],
+        [
+          2,
+          "🔴 FINDING with findings=0. A finding of nothing is an abstention:",
+        ],
+        [0, "no-witness"],
+      ],
+      // Only the valid abstention was written.
+      kinds: ["ABSTAINED 0 false"],
+    },
+  );
+});
+
+test("status prints the derived rows; no command prints the usage and exits 2", () => {
+  cli("record", "cold-read-diff", paper, "ABSTAINED", "no-witness");
+  const s = cli("status", paper);
+  const u = cli();
+  assert.deepEqual(
+    {
+      status: s.status,
+      rows: JSON.parse(s.stdout).map((r) => [r.key, r.state, r.runs]),
+      usage: [u.status, firstLine(u.stderr)],
+    },
+    {
+      status: 0,
+      rows: [["cold-read-diff", "FRESH", 1]],
+      usage: [
+        2,
+        "usage: ledger.mjs record <skill> <paperDir> FINDING   <count> <report-path> [--check=<id>] [--blocking]",
+      ],
+    },
+  );
+});
+
+test("status with no paper argument reads the current directory", () => {
+  const r = runNode(SCRIPT, ["status"], { env, cwd: paper });
+  assert.deepEqual([r.status, JSON.parse(r.stdout)], [0, []]);
+});
+
+test("retired rows are read as LEGACY, keep their word, and only FINDINGS/FAIL carry a count", () => {
+  const legacy = (verdict, extra = {}) =>
+    JSON.stringify({
+      ts: "2026-08-01T00:00:00Z",
+      skill: "old-skill",
+      paper: "p",
+      verdict,
+      ...extra,
+    });
+  writeFileSync(
+    LEDGER,
+    [
+      legacy("PASS"),
+      legacy("FINDINGS", { findings: "4" }),
+      legacy("FAIL"),
+      legacy(undefined),
+      "not json at all",
+      "",
+    ].join("\n"),
+  );
+  assert.deepEqual(
+    readLedger().map((r) => [
+      r.kind,
+      r.check,
+      r.legacyVerdict,
+      r.findings,
+      r.blocking,
+    ]),
+    [
+      ["LEGACY", "old-skill", "PASS", 0, false],
+      ["LEGACY", "old-skill", "FINDINGS", 4, false],
+      ["LEGACY", "old-skill", "FAIL", 0, true],
+      ["LEGACY", "old-skill", null, 0, false],
+    ],
+  );
+});
+
+test("the latest run is chosen by timestamp; a stamped row beats unstamped ones; unstamped fall back to file order", () => {
+  const row = (ts, findings) =>
+    JSON.stringify({
+      ...(ts ? { ts } : {}),
+      skill: "cold-read-diff",
+      paper: "p",
+      kind: findings ? "FINDING" : "ABSTAINED",
+      findings,
+      reason: findings ? null : "no-witness",
+      report: findings ? "counted.md" : null,
+    });
+  const latest = (...lines) => {
+    writeFileSync(LEDGER, lines.join("\n") + "\n");
+    return status(paper)[0].findings;
+  };
+  assert.deepEqual(
+    [
+      latest(row("2026-09-02T00:00:00Z", 2), row("2026-09-01T00:00:00Z", 0)),
+      latest(row(null, 0), row("2026-09-01T00:00:00Z", 2), row(null, 0)),
+      latest(row(null, 2), row(null, 0)),
+      latest(row(null, 0), row(null, 2)),
+    ],
+    [2, 2, 0, 2],
+  );
+});
+
+test("record straight from code returns the row it wrote", () => {
+  const row = record({
+    skill: "cold-read-diff",
+    paper,
+    kind: "ABSTAINED",
+    reason: "blocked",
+  });
+  assert.deepEqual(
+    [row.kind, row.reason, row.check, row.paper, readLedger().length],
+    ["ABSTAINED", "blocked", "cold-read-diff", "p", 1],
+  );
+});
+
+test("status over hand-edited and retired rows: a bare FINDING, and a legacy FINDINGS that still counts", () => {
+  writeFileSync(
+    LEDGER,
+    [
+      {
+        ts: "2026-09-01T00:00:00Z",
+        skill: "hand",
+        paper: "p",
+        kind: "FINDING",
+      },
+      {
+        ts: "2026-08-01T00:00:00Z",
+        skill: "old-skill",
+        paper: "p",
+        verdict: "FINDINGS",
+        findings: 4,
+        report: "r.md",
+      },
+      {
+        ts: "2026-08-01T00:00:00Z",
+        skill: "failed-skill",
+        paper: "p",
+        verdict: "FAIL",
+        findings: 1,
+      },
+    ]
+      .map((r) => JSON.stringify(r))
+      .join("\n") + "\n",
+  );
+  assert.deepEqual(
+    status(paper, { gates: ["hand", "old-skill", "failed-skill"] }).map((r) => [
+      r.key,
+      r.findings,
+      r.report,
+      r.legacy,
+      r.everFound,
+    ]),
+    [
+      ["hand", 0, null, null, true],
+      ["old-skill", 4, "r.md", "FINDINGS", true],
+      ["failed-skill", 1, null, "FAIL", true],
+    ],
+  );
+});
+
+test("record FINDING with no count at all is a finding of zero, refused", () => {
+  const r = cli("record", "cold-read-diff", paper, "FINDING");
+  assert.deepEqual(
+    [r.status, firstLine(r.stderr)],
+    [2, "🔴 FINDING with findings=0. A finding of nothing is an abstention:"],
+  );
+});

package/skills/paper-pipeline/scripts/ledger.mjs

@@ -120,7 +120,7 @@ export const LEDGER = ledgerPath(HERE);
 // `.claude/skills/paper-pipeline/scripts/` that resolves to `…/paper-pipeline/skills`, which does
 // not exist. And the failure is SILENT in the worst direction — `skillHash()` over a missing
 // directory is stable, so every recorded verdict reads FRESH forever and staleness detection is
-// dead without a single error. Caught only because `ledger.selftest.mjs` asserts the transition.
+// dead without a single error. Caught only because the ledger self-test (now `ledger.test.mjs`) asserts the transition.
 //
 // 🔴 AND IT BROKE A SECOND TIME, THE SAME WAY, ON 2026-09-12 — which is why it is no longer a
 // walk at all. The skills being hashed are the CONSUMER's: `skillHash()` answers "has the checker

package/skills/paper-pipeline/scripts/{ledger.selftest.mjs → ledger.test.mjs}

@@ -1,54 +1,52 @@
-// ledger.selftest.mjs — plant each failure this thing exists to catch, and watch it catch them.
-//
-// The project's rule, written after five tools reported success while doing nothing:
-// "a checker that has never failed does not count as working". So this file does not check that
-// the ledger runs. It checks that it says NO when it should, and YES when it should — both
-// directions, for every property the design claims.
-//
-//   node .claude/skills/paper-pipeline/scripts/ledger.selftest.mjs
-
+/**
+ * The ledger says NO when it should and YES when it should — both directions, for every property
+ * the design claims (formerly `ledger.selftest.mjs`, which nothing ran).
+ *
+ * Everything lives under one temp directory: the ledger file (PIPELINE_LEDGER) and a consumer root
+ * (CLAUDE_PROJECT_DIR) holding a copy of the one skill whose hash is watched. Both are set BEFORE
+ * `ledger.mjs` is imported, because it resolves them at import time.
+ */
+import assert from "node:assert/strict";
 import {
+  appendFileSync,
+  cpSync,
+  mkdirSync,
   mkdtempSync,
-  writeFileSync,
-  rmSync,
   readFileSync,
-  appendFileSync,
-  existsSync,
   realpathSync,
+  rmSync,
+  writeFileSync,
 } from "node:fs";
-import { consumerSkillsDir } from "./consumer.mjs";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterAll, test } from "vitest";
 
-const tmp = realpathSync(mkdtempSync(join(tmpdir(), "ledger-selftest-")));
+const HERE = dirname(fileURLToPath(import.meta.url));
+const tmp = realpathSync(mkdtempSync(join(tmpdir(), "ledger-test-")));
 const paper = join(tmp, "a-paper");
-
-// 🔴 Point the ledger at a throwaway file BEFORE importing it. The first version wrote to the real
-// ledger and restored it in a `finally`, which leaks fixture rows into permanent history the moment
-// the run dies between the two — and it did, on the day this shipped. Isolation, not cleanup.
+const consumer = join(tmp, "consumer");
+const gate = "cold-read-diff"; // a real skill, so skillHash resolves
+mkdirSync(paper, { recursive: true });
+mkdirSync(join(consumer, ".claude", "skills"), { recursive: true });
+cpSync(
+  join(HERE, "..", "..", gate),
+  join(consumer, ".claude", "skills", gate),
+  {
+    recursive: true,
+    verbatimSymlinks: true,
+  },
+);
 process.env.PIPELINE_LEDGER = join(tmp, "runs.jsonl");
+process.env.CLAUDE_PROJECT_DIR = consumer;
+const { record, status } = await import("./ledger.mjs");
+afterAll(() => rmSync(tmp, { recursive: true, force: true }));
 
-let failures = 0;
-const check = (name, actual, expected) => {
-  const ok = actual === expected;
-  if (!ok) failures++;
-  console.log(
-    `  ${ok ? "ok  " : "FAIL"}  ${name}${ok ? "" : `  — expected ${expected}, got ${actual}`}`,
-  );
-};
-
-try {
-  // `skillHash` was dropped from the destructuring on 2026-08-28 — no check below was reading it.
-  const { record, status } = await import("./ledger.mjs");
-  const mk = (t) => {
-    writeFileSync(join(paper, "paper.md"), t);
-  };
-  const { mkdirSync } = await import("node:fs");
-  mkdirSync(paper, { recursive: true });
-
-  const gate = "cold-read-diff"; // a real skill, so skillHash resolves
-  const st = () => status(paper, { gates: [gate] })[0];
+const check = (name, actual, expected) => assert.equal(actual, expected, name);
+const mk = (t) => writeFileSync(join(paper, "paper.md"), t);
+const st = () => status(paper, { gates: [gate] })[0];
 
+test("the ledger catches every planted error, in order", () => {
   // ── 1. NEVER-RUN is a state, not an absence ──────────────────────────────────────────────
   mk("version one");
   check("a gate nobody has run reads NEVER-RUN", st().state, "NEVER-RUN");
@@ -76,30 +74,11 @@ try {
   ran();
   check("back on the original bytes it is FRESH again", st().state, "FRESH");
 
-  // 🔴 `../skills/…` until 2026-08-15, when this file moved from `.claude/pipeline/` into the
-  // skill it serves. A SIXTH form of hidden reference, after literal paths, `join()` segments,
-  // relative imports, path-shaped regexes and `..`-depth constants: `new URL(rel, import.meta.url)`
-  // is not an import, so neither a path search nor an import resolver sees it. It broke in CI —
-  // ENOENT on `.claude/skills/paper-pipeline/skills/cold-read-diff/SKILL.md`, a path assembled from
-  // the new location and the old relative segment.
-  //
-  // 🔴 AND A SEVENTH FORM, 2026-09-12: the segment was right and the ANCHOR moved. Once the
-  // mechanism ships as a package, `import.meta.url` is inside `node_modules`, so the same two `..`
-  // now name a skill directory of the PACKAGE — which holds no consumer skill. The subject here
-  // was never "a file near me"; it is "the SKILL.md whose bytes `skillHash(gate)` folds into the
-  // key", and that file belongs to the repository under test. So it is resolved the way
-  // `ledger.mjs` resolves `SKILLS`, from the consumer root, and the two cannot drift apart.
-  const skillFile = join(consumerSkillsDir(), gate, "SKILL.md");
-  // Loud, not skipped. This assertion is the only one covering property 2 of the design ("the
-  // checker's own source is part of the key"); skipping it when the file is absent would leave the
-  // selftest printing success while proving one property fewer — the green-over-emptiness this
-  // whole file exists to forbid.
-  if (!existsSync(skillFile))
-    throw new Error(
-      `ledger.selftest: ${skillFile} does not exist.\n` +
-        `This selftest runs against a CONSUMER of the pipeline — a repository that has the ` +
-        `pipeline's skills installed under .claude/skills/ — not against this package on its own.`,
-    );
+  // The SKILL.md whose bytes `skillHash(gate)` folds into the key is the CONSUMER's, resolved from
+  // CLAUDE_PROJECT_DIR — here a temp copy, so the edit below never touches a tracked file. (The
+  // selftest this replaced appended to the real skills/cold-read-diff/SKILL.md and restored it,
+  // i.e. it edited the working tree in place while other tests could be reading it.)
+  const skillFile = join(consumer, ".claude", "skills", gate, "SKILL.md");
   const skillBefore = readFileSync(skillFile);
   try {
     appendFileSync(
@@ -272,15 +251,4 @@ try {
       0,
     );
   }
-} finally {
-  // The ledger lives inside `tmp`, so removing the fixture removes it too. Nothing to restore,
-  // which is the point — there is no window in which real history is at risk.
-  rmSync(tmp, { recursive: true, force: true });
-}
-
-console.log(
-  failures === 0
-    ? "\n  all planted errors were caught\n"
-    : `\n  🔴 ${failures} assertion(s) failed — the ledger is not doing what it claims\n`,
-);
-process.exit(failures === 0 ? 0 : 1);
+});