paperlint 3.0.0 → 3.1.1

package/lib/skill-checks.test.mjs

@@ -0,0 +1,297 @@
+/**
+ * skill-checks.mjs's two refusing halves, which the per-skill harnesses (all green on the real
+ * corpus) never reach: `checkSkill` on an unknown name and on a pipeline skill with a planted
+ * defect, and `checkProseSkill` — the check for skills WITHOUT the pipeline, which the package
+ * exports for a consumer's own skills and no harness here calls.
+ *
+ * The consumer is a temp root holding a COPY of the shipped skills, so a planted defect edits the
+ * copy, never the tracked files. It is set before import: the corpus resolves it at load time.
+ */
+import assert from "node:assert/strict";
+import { cpSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { test } from "vitest";
+import { useTempDir, writeTree } from "../test/support.mjs";
+
+const SHIPPED = join(dirname(fileURLToPath(import.meta.url)), "..", "skills");
+const consumer = useTempDir("skill-checks-");
+const SKILLS = join(consumer, ".claude", "skills");
+cpSync(SHIPPED, SKILLS, { recursive: true, verbatimSymlinks: true });
+process.env.CLAUDE_PROJECT_DIR = consumer;
+const { checkProseSkill, checkSkill } = await import("./skill-checks.mjs");
+
+/** The message of what `fn` throws — an AggregateError's messages joined, one per line. */
+async function thrown(fn) {
+  try {
+    await fn();
+  } catch (e) {
+    return e instanceof AggregateError
+      ? [e.message, ...e.errors.map((x) => x.message.split("\n")[0])]
+      : e.message.split("\n")[0];
+  }
+  return null;
+}
+
+test("checkSkill passes a real shipped skill and refuses a name that is not a wired skill", async () => {
+  assert.deepEqual(
+    [
+      await checkSkill("cold-read-diff"),
+      await thrown(() => checkSkill("no-such-skill")),
+    ],
+    [
+      1,
+      `"no-such-skill" is not a wired pipeline skill. Known: ${(await import("./skill-corpus.mjs")).SKILLS.join(", ")}`,
+    ],
+  );
+});
+
+test("checkSkill reports EVERY finding of a broken pipeline skill at once", async () => {
+  const md = join(SKILLS, "cold-read-diff", "SKILL.md");
+  const clean = readFileSync(md, "utf8");
+  writeFileSync(
+    md,
+    clean
+      .replace("name: cold-read-diff", "name: renamed")
+      .replace("## Run me", "## Not run"),
+  );
+  try {
+    const first = await thrown(() => checkSkill("cold-read-diff"));
+    assert.equal(
+      first,
+      '2 assertion(s) failed for pipeline skill "cold-read-diff":',
+    );
+  } finally {
+    writeFileSync(md, clean);
+  }
+});
+
+test("a pipeline skill whose record block is gone: ONE finding naming the heading — the ledger checks that read the block skip it", async () => {
+  const md = join(SKILLS, "cold-read-diff", "SKILL.md");
+  const clean = readFileSync(md, "utf8");
+  writeFileSync(md, clean.replaceAll("## Record the verdict", "## Afterwards"));
+  let message = "";
+  try {
+    await checkSkill("cold-read-diff");
+  } catch (e) {
+    message = e.message;
+  } finally {
+    writeFileSync(md, clean);
+  }
+  assert.equal(
+    message,
+    '1 assertion(s) failed for pipeline skill "cold-read-diff":\n\n' +
+      '  [1] cold-read-diff: no "Record the verdict" heading. A run with an announce row and no verdict row is indistinguishable from a skill that started and died.',
+  );
+});
+
+const PROSE = (extra = "") =>
+  [
+    "---",
+    "name: prose",
+    "description: a skill with no pipeline",
+    "allowed-tools: [Read, Write]",
+    "---",
+    "",
+    "<!-- vigiles:sha256:0000000000000000 compiled from SKILL.md.spec.ts -->",
+    "",
+    "Measured rule: always say which file. See [the notes](./notes.md) and [the web](https://x.org).",
+    extra,
+    "",
+  ].join("\n");
+writeTree(SKILLS, { "prose/SKILL.md": PROSE(), "prose/notes.md": "notes\n" });
+
+test("checkProseSkill passes a clean prose skill", async () => {
+  assert.equal(await checkProseSkill("prose"), 1);
+});
+
+test("checkProseSkill refuses an option it does not read, instead of silently skipping it", async () => {
+  assert.deepEqual(
+    await thrown(() =>
+      checkProseSkill("prose", { mustSay: [[/x/, "x"]], toolsNeeded: {} }),
+    ),
+    "prose: unknown option(s) mustSay — checkProseSkill takes only toolsNeeded",
+  );
+});
+
+test("checkProseSkill collects every finding: a banned tool, a dangling link, no compile mark", async () => {
+  writeTree(SKILLS, {
+    "broken/SKILL.md": [
+      "---",
+      "name: broken",
+      "description: d",
+      "allowed-tools: [Read, Bash]",
+      "---",
+      "See [gone](./gone.md). never mind the file.",
+      "",
+    ].join("\n"),
+  });
+  assert.deepEqual(await thrown(() => checkProseSkill("broken")), [
+    "broken: 3 findings",
+    "broken: Bash appeared in the contract. It was dropped deliberately; bringing it back restores a leg of the lethal trifecta (data + network + execution) on a skill that only writes text. If the tool IS needed IN SUBSTANCE — declare it in toolsNeeded WITH A REASON, not silently.",
+    "broken: dangling links → ./gone.md. A skill naming a path that does not exist is a dead instruction: the model reads it, does something adjacent and reports success.",
+    "broken: no compilation mark. That means SKILL.md was edited by hand rather than through .spec.ts — the next `vigiles compile` will overwrite the edit without warning.",
+  ]);
+});
+
+test("checkProseSkill: a tool exemption needs a reason, and an exemption for a tool not in the contract is stale", async () => {
+  writeTree(SKILLS, {
+    "needs-bash/notes.md": "notes\n",
+    "needs-bash/SKILL.md": PROSE()
+      .replace("name: prose", "name: needs-bash")
+      .replace("[Read, Write]", "[Read, Bash]"),
+  });
+  assert.deepEqual(
+    [
+      await thrown(() =>
+        checkProseSkill("needs-bash", { toolsNeeded: { Bash: "short" } }),
+      ),
+      await checkProseSkill("needs-bash", {
+        toolsNeeded: { Bash: "runs the measurement script it documents" },
+      }),
+      await thrown(() =>
+        checkProseSkill("prose", {
+          toolsNeeded: { Agent: "delegates the heavy read to a subagent" },
+        }),
+      ),
+    ],
+    [
+      "needs-bash: toolsNeeded.Bash is declared without an intelligible reason. An exemption must say WHY the tool is needed in substance — otherwise it is a silent disabling of the check.",
+      1,
+      [
+        "prose: 1 findings",
+        "prose: toolsNeeded.Agent is declared, but Agent itself is NOT in the contract. The exemption is stale — remove it, otherwise it describes a different skill.",
+      ],
+    ],
+  );
+});
+
+test("checkProseSkill refuses a skill with no SKILL.md, an empty contract, and one that does not parse", async () => {
+  writeTree(SKILLS, {
+    "empty-tools/notes.md": "notes\n",
+    "bad-yaml/notes.md": "notes\n",
+    "empty-tools/SKILL.md": PROSE()
+      .replace("name: prose", "name: empty-tools")
+      .replace("allowed-tools: [Read, Write]", "allowed-tools: []"),
+    "bad-yaml/SKILL.md": PROSE()
+      .replace("name: prose", "name: bad-yaml")
+      .replace("allowed-tools: [Read, Write]", "allowed-tools: [Read, Write"),
+  });
+  assert.deepEqual(
+    [
+      await thrown(() => checkProseSkill("absent")),
+      await thrown(() => checkProseSkill("empty-tools")),
+      (await thrown(() => checkProseSkill("bad-yaml")))[0],
+    ],
+    [
+      `absent: no ${join(SKILLS, "absent", "SKILL.md")} — nothing to check`,
+      [
+        "empty-tools: 1 findings",
+        "empty-tools: empty allowed-tools — inherits everything",
+      ],
+      "bad-yaml: 2 findings",
+    ],
+  );
+});
+
+/** Rewrite a copied skill's SKILL.md with `edit`, run checkSkill, restore; the failure's first line. */
+async function brokenBy(name, edit) {
+  const md = join(SKILLS, name, "SKILL.md");
+  const clean = readFileSync(md, "utf8");
+  writeFileSync(md, edit(clean));
+  try {
+    await checkSkill(name);
+    return null;
+  } catch (e) {
+    // The header, then the first 90 characters of each numbered finding.
+    const lines = e.message.split("\n");
+    return [
+      lines[0],
+      ...lines
+        .filter((l) => /^  \[\d+\] /.test(l))
+        .map((l) => l.trim().slice(0, 90)),
+    ];
+  } finally {
+    writeFileSync(md, clean);
+  }
+}
+const recordSection = /## Record the verdict[\s\S]*?(?=\n## |\n# |$)/;
+
+test("checkSkill on the defects its own corpus never has: no description, no record block, a record block naming no kind", async () => {
+  assert.deepEqual(
+    [
+      await brokenBy("cold-read-diff", (s) =>
+        s.replace(/^description: .*\n/m, ""),
+      ),
+      await brokenBy("argument-arc", (s) =>
+        s.replace(
+          recordSection,
+          "## Record the verdict\n\nNothing named here.\n",
+        ),
+      ),
+      await brokenBy("draft-paper", (s) =>
+        s.replace(
+          recordSection,
+          "## Record the verdict\n\n**ABSTAINED** — and no reason is named.\n",
+        ),
+      ),
+    ],
+    [
+      [
+        '1 assertion(s) failed for pipeline skill "cold-read-diff":',
+        "[1] cold-read-diff: description is missing or trivially short (0 chars). The description i",
+      ],
+      [
+        '3 assertion(s) failed for pipeline skill "argument-arc":',
+        '[1] argument-arc: the "Record the verdict" block instructs no `node .claude/skills/paper-p',
+        "[2] argument-arc: its record block names [nothing] and not FINDING, and does not admit tha",
+        "[3] argument-arc: its record block names no abstention reason from [started, no-witness, i",
+      ],
+      [
+        '5 assertion(s) failed for pipeline skill "draft-paper":',
+        '[1] draft-paper: the "Record the verdict" block instructs no `node .claude/skills/paper-pi',
+        "[2] draft-paper: its record block names [ABSTAINED] and not FINDING, and does not admit th",
+        "[3] draft-paper: its record block names no abstention reason from [started, no-witness, in",
+        "[4] draft-paper: the honest admission is gone from its record block. It is the one skill i",
+        "[5] ABSTAINED needs a reason from started|no-witness|input-missing|blocked|crashed, got nu",
+      ],
+    ],
+  );
+});
+
+test("a skill may show `ledger.mjs status` — only a `record` call must file under the skill", async () => {
+  assert.equal(
+    await brokenBy("cold-read-diff", (s) =>
+      s.replace(
+        "node .claude/skills/paper-pipeline/scripts/announce.mjs cold-read-diff <paper-dir>",
+        "node .claude/skills/paper-pipeline/scripts/announce.mjs cold-read-diff <paper-dir>\n" +
+          "node .claude/skills/paper-pipeline/scripts/ledger.mjs status <paper-dir>",
+      ),
+    ),
+    null,
+  );
+});
+
+test("a skill whose only ledger call is `status` records nothing, and is told so", async () => {
+  assert.deepEqual(
+    await brokenBy("cold-read-diff", (s) =>
+      s.replaceAll(
+        /ledger\.mjs record cold-read-diff <paper-dir> \w+[^\n]*/g,
+        "ledger.mjs status <paper-dir>",
+      ),
+    ),
+    [
+      '1 assertion(s) failed for pipeline skill "cold-read-diff":',
+      '[1] cold-read-diff: the "Record the verdict" block instructs no `node .claude/skills/paper',
+    ],
+  );
+});
+
+test("the record CALL is the contract, not the heading: a renamed record section still passes", async () => {
+  assert.equal(
+    await brokenBy("camera-ready", (s) =>
+      s.replace("## Record the verdict", "## Something else"),
+    ),
+    null,
+  );
+});

package/lib/skill-corpus.mjs

@@ -86,9 +86,9 @@ export const GATE_SKILLS = new Set(
 // command and is in neither list. That is DELIBERATE (see EXCLUDED), but nothing checked that the
 // deliberateness was still true, and the old comment asserting it was the only thing holding it.
 //
-// The mutation driver's case 12b passed the whole time, because it removes a skill from EXPECTED_GATES
-// while leaving it in the pinned array. A green mutation proving a narrower property than its own
-// error message claims is exactly the vacuity this file was built to hunt, sitting in this file.
+// A defect that removes a skill from EXPECTED_GATES while leaving it in the pinned array passed
+// silently the whole time. A check proving a narrower property than its own error message claims
+// is exactly the vacuity this file was built to hunt, sitting in this file.
 //
 // The old comment's objection to globbing was real and is answered rather than ignored: `.claude/skills/`
 // does hold daily skills (search-krisha, food-log-entry, …) with no pipeline contract, so the filter
@@ -127,14 +127,15 @@ export const EXCLUDED = new Map([
 // defects this file hunts, and a defect that shrinks the checked set is worse than the defect itself:
 // the harness goes green by no longer looking.
 //
-// Both narrower versions were written and both were killed by the mutation driver within minutes:
+// Both narrower versions were written and both failed within minutes, on the same two planted
+// defects:
 //
-//   filter `announce.mjs <own name>`  -> case 13 (typo the announced NAME) dropped harden-paper out
+//   filter `announce.mjs <own name>`  -> a typo in the announced NAME dropped harden-paper out
 //                                        of scope; harness printed "20 pipeline skills", said nothing
-//   filter `announce.mjs` path        -> case 5b (typo the announce PATH) dropped camera-ready the
+//   filter `announce.mjs` path        -> a typo in the announce PATH dropped camera-ready the
 //                                        same way
 //
-// Each time, the mutation that used to turn the harness red went GREEN because the planted defect
+// Each time, the same planted defect that used to turn the harness red went GREEN because it
 // erased its own subject. Scope decided by a property the defect corrupts is not scope.
 //
 // The union cannot be shrunk by a single-point edit: break the wiring and the gate table still holds
@@ -395,9 +396,6 @@ export const load = (name) => {
 // the header of `skill-checks.mjs`). The real, declared carrier of this check is `checkSkill()`,
 // which does it one skill at a time and with a legible message.
 //
-// `ONLY` stays: it is read by the check one line up — the only thing here that survived.
-const ONLY = process.env.PIPELINE_SKILL_ONLY ?? "";
-if (ONLY && !SKILLS.includes(ONLY))
-  throw new Error(
-    `PIPELINE_SKILL_ONLY="${ONLY}" is not a wired pipeline skill. Known: ${SKILLS.join(", ")}`,
-  );
+// `PIPELINE_SKILL_ONLY` used to stay here, validated against SKILLS. Nothing read the variable
+// any more — the validation was all that was left of the feature — so it was removed with it
+// (2026-09-27).

package/lib/skill-corpus.test.mjs

@@ -0,0 +1,54 @@
+/**
+ * skill-corpus.mjs's pure readers on the inputs the shipped corpus never contains: frontmatter
+ * that is not a mapping or not YAML, an `allowed-tools` that is absent, a skill with no record
+ * block and one whose record block ends the file.
+ */
+import assert from "node:assert/strict";
+import { test } from "vitest";
+import { parseFm, recordBlock, toolList } from "./skill-corpus.mjs";
+
+const refusal = (fn) => {
+  try {
+    fn();
+    return null;
+  } catch (e) {
+    return e.message.split(". Almost")[0];
+  }
+};
+
+test("parseFm refuses a list, a bare string and broken YAML, naming where", () => {
+  assert.deepEqual(
+    [
+      refusal(() => parseFm("- a\n- b", "x/SKILL.md")),
+      refusal(() => parseFm("just words")),
+      refusal(() => parseFm("a: b: c")),
+    ],
+    [
+      "x/SKILL.md: frontmatter is not valid YAML — parsed to a list, not a mapping",
+      "frontmatter: frontmatter is not valid YAML — parsed to string, not a mapping",
+      "frontmatter: frontmatter is not valid YAML — bad indentation of a mapping entry (1:5)",
+    ],
+  );
+});
+
+test("toolList of nothing is an empty contract, and a flow list or a comma scalar is split", () => {
+  assert.deepEqual(
+    [
+      toolList(undefined),
+      toolList("[Bash, Read]"),
+      toolList(" Read , Write "),
+      toolList(["Read ", ""]),
+    ],
+    [[], ["Bash", "Read"], ["Read", "Write"], ["Read"]],
+  );
+});
+
+test("recordBlock: none without the heading; to the end of the file when it is the last section", () => {
+  assert.deepEqual(
+    [
+      recordBlock("# S\n\n## Run me\n\nx\n"),
+      recordBlock("# S\n\n## Record the verdict\n\nlast\n"),
+    ],
+    [null, "## Record the verdict\n\nlast\n"],
+  );
+});

package/lib/skill-trigger-cases.harness.mjs

@@ -14,7 +14,6 @@
  * be holding them itself".
  *
  * Run: `npx vigiles test lib/skill-trigger-cases.harness.mjs`
- * Killed by: `lib/skill-trigger-cases.mutations.mjs`
  */
 import assert from "node:assert/strict";
 import { execFileSync } from "node:child_process";
@@ -41,10 +40,10 @@ const soft = (label, fn) => {
  * (top-level await) — a second import in this process would be served from the module cache and
  * would measure the first root again while appearing to measure the second.
  */
-function loadAt(root) {
+function loadAt(root, then = `console.log("OK " + m.CASES.length)`) {
   const script =
     `import("${join(HERE, "skill-trigger-cases.mjs").replaceAll("\\", "/")}")` +
-    `.then((m) => console.log("OK " + m.CASES.length))` +
+    `.then((m) => { ${then}; })` +
     `.catch((e) => { console.log("THROW " + String(e.message).split("\\n")[0]); });`;
   return execFileSync(process.execPath, ["--input-type=module", "-e", script], {
     cwd: root,
@@ -160,12 +159,66 @@ soft("II. a consumer may not redefine a case this package owns", () => {
   );
 });
 
+soft(
+  "II. a declaration that is not a non-empty string THROWS, naming what it got",
+  () => {
+    for (const [declared, shown] of [
+      ["", '""'],
+      [7, "7"],
+    ]) {
+      const out = loadAt(fixture({ triggerCases: declared }, null));
+      assert.equal(
+        out,
+        `THROW paperlint: "triggerCases" must be a non-empty string, got ${shown}`,
+      );
+    }
+  },
+);
+
+soft(
+  "II. a default-location file that does not load THROWS, saying it is the default",
+  () => {
+    for (const broken of [
+      "export const CASES = [\n",
+      'throw "not an Error";\n',
+    ]) {
+      const out = loadAt(fixture(null, broken));
+      assert.match(out, /^THROW .*could not load the consumer's trigger cases/);
+      assert.match(
+        out,
+        /\(the default location; declare another in paperlint\.json/,
+      );
+    }
+  },
+);
+
+soft("II. a cases file whose CASES is not an array THROWS", () => {
+  const out = loadAt(fixture(null, "export const CASES = {};\n"));
+  assert.match(out, /^THROW .* must export an array named CASES$/);
+});
+
+soft(
+  "II. irrelevantFor refuses an unknown skill, and a collider that names one",
+  () => {
+    assert.throws(
+      () => irrelevantFor("no-such-skill"),
+      /^Error: unknown skill: no-such-skill$/,
+    );
+    const ghost = `export const CASES = [{ skill: "local-x", why: "x", prompts: ["a","b","c","d"], collides: ["ghost"] }];\n`;
+    const out = loadAt(
+      fixture(null, ghost),
+      `m.irrelevantFor("local-x"); console.log("OK")`,
+    );
+    assert.equal(out, 'THROW local-x collides with unknown skill "ghost"');
+  },
+);
+
 if (failures.length) {
   console.error(`${failures.length} assertion(s) failed:`);
   for (const f of failures) console.error(`  ✗ ${f}`);
   process.exit(1);
 }
 console.log(
-  `trigger-case carrier: ${CASES.length} package case(s), consumer merge in four states ✓`,
+  `trigger-case carrier: ${CASES.length} package case(s), consumer merge in every state ✓`,
 );
 recordCheck();

package/package.json

@@ -1,16 +1,17 @@
 {
   "name": "paperlint",
-  "version": "3.0.0",
+  "version": "3.1.1",
   "description": "A linter for scientific papers written in LaTeX: catches mistakes before you submit to a conference or journal.",
   "type": "module",
   "license": "MIT",
   "scripts": {
     "build": "tsc",
     "prepare": "tsc",
-    "test": "node scripts/exclusive.mjs vitest run && node scripts/exclusive.mjs vigiles test --min=1",
-    "lint": "node scripts/exclusive.mjs eslint .",
+    "test": "node scripts/test.mjs",
+    "coverage": "NODE_OPTIONS=\"--import=./test/coverage-src.mjs $NODE_OPTIONS\" c8 --check-coverage npm test --",
+    "lint": "eslint .",
     "check": "node scripts/check.mjs",
-    "test:e2e": "node scripts/exclusive.mjs node test/e2e/install.mjs && node scripts/exclusive.mjs node test/e2e/build.mjs",
+    "test:e2e": "node test/e2e/install.mjs && node test/e2e/build.mjs",
     "fmt": "prettier --write .",
     "fmt:check": "prettier --check ."
   },
@@ -33,6 +34,7 @@
     "@semantic-release/commit-analyzer": "13.0.1",
     "@semantic-release/release-notes-generator": "14.1.1",
     "@types/node": "^26.6.1",
+    "c8": "^12.0.0",
     "conventional-changelog-conventionalcommits": "9.3.1",
     "eslint-plugin-boundaries": "^7.2.0",
     "eslint-plugin-n": "^18.3.0",
@@ -75,7 +77,6 @@
     "CLAUDE.md",
     "CONTRIBUTING.md",
     "action.harness.mjs",
-    "action.mutations.mjs",
     "action.yml",
     "bin",
     "dist",

package/scripts/check.harness.mjs

@@ -14,11 +14,11 @@
  * ⚠️ 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 { existsSync, readdirSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { load } from "js-yaml";
+import { createChecker } from "../lib/check.mjs";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const ROOT = dirname(HERE);
@@ -26,11 +26,7 @@ const ROOT = dirname(HERE);
 const { GATES, NOT_COVERED, outcome, SKIP_EXIT, commandOf } =
   await import("./check.mjs");
 
-let n = 0;
-const check = (label, cond) => {
-  n++;
-  assert.ok(cond, label);
-};
+const check = createChecker();
 
 // ── the workflow is the ORACLE, not a copy of it ───────────────────────────────────────────
 // A declared skip is a THIRD outcome. Folding it into "pass" printed "all gates passed" on a
@@ -135,9 +131,7 @@ for (const g of GATES) {
   // every program other than `node` must be installed in node_modules/.bin.
   const argv = commandOf(g);
   const files = argv.filter((a) => /\.m?js$/.test(a));
-  const programs = argv.filter(
-    (a, i) => i === 0 || argv[i - 1] === "scripts/exclusive.mjs",
-  );
+  const programs = [argv[0]];
   // Guards: a gate runs SOMETHING — a script of ours, or an installed program such as `tsc`.
   check(
     `gate «${g.name}» runs files that exist (${files.join(", ")})`,
@@ -172,6 +166,6 @@ check(
 );
 
 console.log(
-  `✓ ${String(n)} assertions passed — npm run check: ${GATES.length} gates, ` +
+  `✓ ${String(check.count)} assertions passed — npm run check: ${GATES.length} gates, ` +
     `${ciJobs.length} CI job(s) all accounted for`,
 );