paperlint 3.1.0 → 3.1.1

package/lib/markdown.test.mjs

@@ -0,0 +1,246 @@
+/**
+ * markdown.mjs — the markup readers every script shares, on the shapes their callers rely on:
+ * frontmatter blanked (offsets kept) or cut, headings from the parser (not from a `#` inside a
+ * fence), sections by level, fences, paragraphs and tables. And the one thing a test run never
+ * sees by accident: markdown-it failing to resolve, where every reader must degrade to its
+ * documented empty value and `requireMarkdown` must refuse with exit 2.
+ */
+import assert from "node:assert/strict";
+import { copyFileSync, mkdirSync } 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";
+import {
+  blankFrontmatter,
+  fences,
+  frontmatterBlock,
+  headings,
+  requireMarkdown,
+  paragraphs,
+  splitSections,
+  stripFences,
+  stripFrontmatter,
+  tables,
+} from "./markdown.mjs";
+
+const DOC = [
+  "---", // 0
+  "title: T", // 1
+  "  ## not a heading, inside the frontmatter", // 2
+  "---", // 3
+  "# Title", // 4
+  "", // 5
+  "Intro para.", // 6
+  "", // 7
+  "## One", // 8
+  "Body one.", // 9
+  "", // 10
+  "---", // 11
+  "", // 12
+  "after the rule", // 13
+  "", // 14
+  "```", // 15
+  "## a heading in a fence", // 16
+  "```", // 17
+  "", // 18
+  "    indented code", // 19
+  "", // 20
+  "### One.a", // 21
+  "| a | b |", // 22
+  "|---|:-:|", // 23
+  "| 1 | 2 |", // 24
+  "", // 25
+  "## Two", // 26
+  "last", // 27
+].join("\n");
+
+test("frontmatter: blanked with offsets kept, its body, cut; untouched when there is none", () => {
+  assert.deepEqual(
+    {
+      blank: blankFrontmatter("---\na: 1\n---\nx").split("\n"),
+      body: frontmatterBlock(DOC),
+      none: [
+        frontmatterBlock("x"),
+        blankFrontmatter("x"),
+        stripFrontmatter("x"),
+      ],
+      cut: stripFrontmatter("---\na: 1\n---\n\nx"),
+    },
+    {
+      blank: ["   ", "    ", "   ", "x"],
+      body: "title: T\n  ## not a heading, inside the frontmatter",
+      none: [null, "x", "x"],
+      cut: "\nx",
+    },
+  );
+});
+
+test("headings come from the parser: not from the frontmatter, not from a fence, not setext", () => {
+  const offset = (line) => DOC.split("\n").slice(0, line).join("\n").length + 1;
+  assert.deepEqual(headings(DOC + "\n\nSetext\n======\n"), [
+    { depth: 1, text: "Title", line: 4, offset: offset(4) },
+    { depth: 2, text: "One", line: 8, offset: offset(8) },
+    { depth: 3, text: "One.a", line: 21, offset: offset(21) },
+    { depth: 2, text: "Two", line: 26, offset: offset(26) },
+  ]);
+});
+
+test("an empty ATX heading has empty text", () => {
+  assert.deepEqual(
+    headings("#\n").map((h) => [h.depth, h.text]),
+    [[1, ""]],
+  );
+});
+
+test("splitSections: a preamble always first, then each heading of the level range", () => {
+  assert.deepEqual(
+    splitSections(DOC, { min: 2, max: 2 }).map((s) => [
+      s.heading?.text ?? null,
+      s.body.split("\n")[0],
+    ]),
+    [
+      [null, "---"],
+      ["One", "Body one."],
+      ["Two", "last"],
+    ],
+  );
+  assert.deepEqual(
+    splitSections("## A").map((s) => [s.heading?.text ?? null, s.body]),
+    [
+      [null, ""],
+      ["A", ""],
+    ],
+  );
+});
+
+test("fences and indented code, as content; stripped as lines, or blanked in place", () => {
+  const src = "a\n```\nx\n```\n\n    y\nb";
+  assert.deepEqual(
+    {
+      fences: fences(src),
+      stripped: stripFences(src),
+      blanked: stripFences(src, { blank: true }),
+    },
+    { fences: ["x\n", "y\n"], stripped: "a\n\nb", blanked: "a\n\n\n\n\n\nb" },
+  );
+});
+
+test("paragraphs are line ranges; tables are rows of cells, the alignment row skipped", () => {
+  assert.deepEqual(
+    { paragraphs: paragraphs(DOC), tables: tables(DOC) },
+    {
+      paragraphs: [
+        { line: 6, endLine: 7 },
+        { line: 9, endLine: 10 },
+        { line: 13, endLine: 14 },
+        { line: 27, endLine: 28 },
+      ],
+      tables: [
+        {
+          line: 22,
+          endLine: 25,
+          rows: [
+            ["a", "b"],
+            ["1", "2"],
+          ],
+        },
+      ],
+    },
+  );
+});
+
+const root = useTempDir("markdown-no-parser-");
+writeTree(root, {
+  // Registered with --import: resolving `markdown-it` fails, as it does with no node_modules.
+  "no-markdown-it.mjs":
+    "import { register } from 'node:module';\n" +
+    "register('data:text/javascript,' + encodeURIComponent(\"export async function resolve(s, c, next) { if (s === 'markdown-it') throw Object.assign(new Error('gone'), { code: 'ERR_MODULE_NOT_FOUND' }); return next(s, c); }\"));\n",
+  "probe.mjs":
+    `const m = await import(${JSON.stringify(join(dirname(fileURLToPath(import.meta.url)), "markdown.mjs"))});\n` +
+    "const t = '# H\\n\\n```\\nx\\n```\\n';\n" +
+    "console.log(JSON.stringify([m.MD_AVAILABLE(), m.headings(t), m.fences(t), m.stripFences(t), m.paragraphs(t), m.tables(t)]));\n" +
+    "m.requireMarkdown();\n" +
+    "console.log('not reached');\n",
+  "probe-plugin.mjs":
+    `const m = await import(${JSON.stringify(join(dirname(fileURLToPath(import.meta.url)), "markdown.mjs"))});\n` +
+    'm.requireMarkdown({ from: "file:///home/u/.claude/plugins/cache/paperlint/lib/markdown.mjs" });\n',
+});
+
+test("this file, told it runs from a plugin cache, sends its user to the npm package", () => {
+  const r = runNode(join(root, "probe-plugin.mjs"), [], {
+    nodeArgs: ["--import", join(root, "no-markdown-it.mjs")],
+  });
+  assert.deepEqual(
+    [r.status, r.stderr.split("\n").slice(1, 2)],
+    [
+      2,
+      [
+        "  Running from a PLUGIN copy, which is installed without dependencies. Install the npm",
+      ],
+    ],
+  );
+});
+
+test("with no markdown-it, every reader degrades to its empty value and requireMarkdown exits 2", () => {
+  const r = runNode(join(root, "probe.mjs"), [], {
+    nodeArgs: ["--import", join(root, "no-markdown-it.mjs")],
+  });
+  assert.deepEqual(r, {
+    status: 2,
+    stdout:
+      JSON.stringify([false, [], [], "# H\n\n```\nx\n```\n", [], []]) + "\n",
+    stderr:
+      "markdown-it does not resolve — this script parses markup with a parser and without it would produce a confident zero instead of an error.\n" +
+      "  Cured by `npm i` at the repo root.\n",
+  });
+});
+
+test("splitSections of a document with no heading is the preamble alone; requireMarkdown is silent with a parser", () => {
+  assert.deepEqual(
+    [
+      splitSections("just text").map((s) => [s.heading, s.body]),
+      requireMarkdown(),
+    ],
+    [[[null, "just text"]], undefined],
+  );
+});
+
+test("headings read a token stream that breaks markdown-it's shape as empty text and offset 0", () => {
+  // A heading not followed by its inline token, mapped past the end of the text.
+  const parse = () => [
+    { type: "heading_open", map: [9, 10], markup: "##", tag: "h2" },
+    { type: "paragraph_open" },
+  ];
+  assert.deepEqual(headings("x", { parse }), [
+    { depth: 2, text: "", line: 9, offset: 0 },
+  ]);
+});
+
+test("a copy running from a plugin cache without markdown-it is told to install the npm package", () => {
+  // A plugin copy is installed without dependencies: here, a copy under `.claude/plugins/` with
+  // no node_modules above it, so `markdown-it` does not resolve for real.
+  const lib = join(root, ".claude", "plugins", "paperlint", "lib");
+  mkdirSync(lib, { recursive: true });
+  copyFileSync(
+    join(dirname(fileURLToPath(import.meta.url)), "markdown.mjs"),
+    join(lib, "markdown.mjs"),
+  );
+  writeTree(lib, {
+    "probe.mjs":
+      'const m = await import("./markdown.mjs");\nm.requireMarkdown();\n',
+  });
+  const r = runNode(join(lib, "probe.mjs"), []);
+  assert.deepEqual(
+    [r.status, r.stderr.split("\n").slice(1)],
+    [
+      2,
+      [
+        "  Running from a PLUGIN copy, which is installed without dependencies. Install the npm",
+        "  package in the project as well (`npm i paperlint`) and call it through",
+        "  `npx paperlint`, which resolves from the project's own tree.",
+        "",
+      ],
+    ],
+  );
+});

package/lib/paper-config.harness.mjs

@@ -23,21 +23,16 @@
  * while the value itself is still taken by import.
  *
  * Run:    npx vigiles test lib/paper-config.harness.mjs
- * Killed by: lib/paper-config.mutations.mjs
  */
-import assert from "node:assert/strict";
 import { readFileSync, readdirSync } from "node:fs";
 import { dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import { createChecker } from "./check.mjs";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const ROOT = resolve(HERE, "..");
 
-let n = 0;
-const check = (label, cond) => {
-  n++;
-  assert.ok(cond, label);
-};
+const check = createChecker();
 
 /**
  * Every place that publishes at least one of the two constants. The three hooks duplicate them
@@ -181,7 +176,7 @@ const loaded = await Promise.all(
       if (e.isDirectory()) walk(p);
       else if (
         /\.(mjs|ts)$/.test(e.name) &&
-        !/\.(harness|mutations)\.(mjs|ts)$/.test(e.name)
+        !/\.harness\.(mjs|ts)$/.test(e.name)
       ) {
         if (declares.test(readFileSync(p, "utf8")))
           found.push(relative(ROOT, p));
@@ -264,6 +259,30 @@ const loaded = await Promise.all(
   );
 }
 
+// ── the two readers' fallbacks: no marker anywhere up the tree, and JSON that is not an object ──
+{
+  const { findProjectRoot, settingsOf } = await import(
+    join(HERE, "paper-config.mjs")
+  );
+  check(
+    "findProjectRoot: no paperlint.json and no package.json up to / — the start directory itself",
+    findProjectRoot("/nowhere/deep", () => false) === "/nowhere/deep",
+  );
+  const { mkdtempSync, realpathSync, rmSync, writeFileSync } =
+    await import("node:fs");
+  const { tmpdir } = await import("node:os");
+  const dir = realpathSync(mkdtempSync(join(tmpdir(), "paper-config-")));
+  try {
+    writeFileSync(join(dir, "paperlint.json"), "[]\n");
+    check(
+      "settingsOf: a paperlint.json that is JSON but not an object is no settings",
+      settingsOf(dir) === undefined,
+    );
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
 console.log(
-  `✓ ${n} assertions passed — one source for the consumer's config key`,
+  `✓ ${check.count} assertions passed — one source for the consumer's config key`,
 );

package/lib/paper-config.mjs

@@ -64,11 +64,16 @@ export const PAPER_MARKERS = Object.freeze([
 export function findProjectRoot(startDir, isFile = existsSync) {
   const start = resolve(startDir);
   const isPaper = (d) => PAPER_MARKERS.some((m) => isFile(join(d, m)));
+  // Up from `start` to the first directory `found` accepts; null past the filesystem root. A
+  // loop with an exit condition rather than `for (;;)`: the code after an endless loop is a block
+  // that can never run, and coverage counts it as one that did not.
   const walk = (found) => {
-    for (let d = start; ; d = dirname(d)) {
-      if (found(d)) return d;
+    let d = start;
+    while (!found(d)) {
       if (dirname(d) === d) return null;
+      d = dirname(d);
     }
+    return d;
   };
   return (
     walk((d) => isFile(join(d, CONFIG_FILE)) && !isPaper(d)) ??

package/lib/skill-checks.mjs

@@ -137,8 +137,8 @@ export async function checkSkill(name) {
   // ═══════════════════════════════════════════════════════════════════════════════════════════════
   // 1. GONE, AND THAT IS THE RESULT (2026-08-19). This slot held a strict-YAML assertion whose whole
   // job was to police the gap between how the corpus was READ here (a hand-rolled lenient reader)
-  // and how every other consumer reads it (a real YAML parser). The corpus owner, on being shown the mutation
-  // suite: "sounds like a hack… let's think about how to do it properly". The right fix was not a better
+  // and how every other consumer reads it (a real YAML parser). The corpus owner, on being shown the gap:
+  // "sounds like a hack… let's think about how to do it properly". The right fix was not a better
   // check — it was to stop being lenient: the two remaining unparseable descriptions were quoted and
   // `parseFm` in skill-corpus.mjs now throws on anything a real parser rejects.
   //
@@ -213,7 +213,12 @@ export async function checkSkill(name) {
       ["announce", PIPELINE.announce, "Run me"],
       ["record", PIPELINE.ledger, "Record the verdict"],
     ]) {
-      const hits = cmds.filter((c) => c.script === script);
+      // For the ledger, only a `record` call is the wired call: `ledger.mjs status <dir>` is a
+      // read, files under nothing, and until 2026-09-27 was misreported as "files under status".
+      const hits = cmds.filter(
+        (c) =>
+          c.script === script && (label !== "record" || c.args[0] === "record"),
+      );
       soft(() =>
         assert.ok(
           hits.length > 0,
@@ -231,12 +236,7 @@ export async function checkSkill(name) {
           ),
         );
         // arg[0] for announce is the skill; for ledger.mjs it is the literal `record`, then the skill.
-        const passed =
-          label === "announce"
-            ? h.args[0]
-            : h.args[0] === "record"
-              ? h.args[1]
-              : h.args[0];
+        const passed = label === "announce" ? h.args[0] : h.args[1];
         soft(() =>
           assert.equal(
             passed,
@@ -551,10 +551,7 @@ function danglingLinks(src, dir) {
  * Check the prose skill `name`.
  *
  * @param {string} name — the directory name in `.claude/skills/`
- * @param {{mustSay?: [RegExp,string][], mustNotSay?: [RegExp,string][],
- *          toolsNeeded?: Record<string,string>}} opts
- *   `mustSay` — that whose DISAPPEARANCE is a regression (a rule obtained by measurement).
- *   `mustNotSay` — that whose APPEARANCE is a regression (a refuted claim).
+ * @param {{toolsNeeded?: Record<string,string>}} opts
  *   `toolsNeeded` — {tool: REASON}. Lifts the ban on Bash/Agent/Task for a skill that
  *     needs the tool IN SUBSTANCE. The reason is mandatory and non-empty.
  *
@@ -583,6 +580,14 @@ export async function checkProseSkill(name, opts = {}) {
     }
   };
 
+  // Any other option is refused by name: an option this function no longer reads would be a
+  // check the caller believes runs and that does nothing.
+  const unknown = Object.keys(opts).filter((k) => k !== "toolsNeeded");
+  assert.deepEqual(
+    unknown,
+    [],
+    `${name}: unknown option(s) ${unknown.join(", ")} — checkProseSkill takes only toolsNeeded`,
+  );
   assert.ok(existsSync(md), `${name}: no ${md} — nothing to check`);
   const src = readFileSync(md, "utf8");
 
@@ -650,12 +655,6 @@ export async function checkProseSkill(name, opts = {}) {
         `is a dead instruction: the model reads it, does something adjacent and reports success.`,
     ),
   );
-  // mutation: a planted broken link must be caught
-  assert.equal(
-    danglingLinks(src + "\n[x](./net-takogo-fayla.md)\n", dir).length,
-    dangling.length + 1,
-    `${name}: the link check did not fire on a planted broken link — it is dead`,
-  );
 
   // 3. Whether it is compiled. Editing the markdown by hand desynchronises the sha and gets
   // quietly rolled back by the next `vigiles compile`.
@@ -667,33 +666,6 @@ export async function checkProseSkill(name, opts = {}) {
     ),
   );
 
-  // 4-5. Substantive anchors, each with BOTH halves.
-  for (const [re, why] of opts.mustSay || []) {
-    soft(() => assert.ok(re.test(src), `${name}: "${why}" is gone (${re})`));
-    // Mutation: without the matched fragment the predicate must fail. The replacement is GLOBAL —
-    // `replace` with a non-global regex removes only the first occurrence, and an anchor occurring
-    // twice (for example both in the description and in the body) would "pass" on the mutated text
-    // too. Then this assertion would fail rather than the anchor itself — that is, the message
-    // would point in the wrong direction.
-    const g = new RegExp(
-      re.source,
-      re.flags.includes("g") ? re.flags : re.flags + "g",
-    );
-    assert.equal(
-      re.test(src.replace(g, "")),
-      false,
-      `${name}: the anchor ${re} passes even on text WITHOUT it — the check pins nothing down`,
-    );
-  }
-  for (const [re, why] of opts.mustNotSay || []) {
-    soft(() => assert.ok(!re.test(src), `${name}: "${why}" came back (${re})`));
-    assert.equal(
-      re.test(src + "\n" + why + "\n"),
-      true,
-      `${name}: the ban ${re} does not fire on the planted line "${why}" — the check is dead`,
-    );
-  }
-
   if (deferred.length)
     throw new AggregateError(deferred, `${name}: ${deferred.length} findings`);
   recordCheck();