paperlint 3.0.0 → 3.1.1

package/lib/markdown.mjs

@@ -49,6 +49,9 @@ try {
  */
 export const MD_AVAILABLE = () => md !== null;
 
+/** markdown-it's block tokens for `text`, or null when it did not resolve. A test passes its own. */
+const defaultParse = () => (md === null ? null : (text) => md.parse(text, {}));
+
 /**
  * The frontmatter is BLANKED with spaces, not cut out: the offsets must stay the
  * same, because the checks cut the document by offset. Blanking is necessary — inside
@@ -118,15 +121,17 @@ function lineStarts(text) {
  * under without a blank line would become a level-2 heading per CommonMark. The former
  * regexps knew only ATX, so this preserves the contract rather than narrowing it.
  */
-export function headings(text) {
-  if (md === null) return [];
-  const toks = md.parse(blankFrontmatter(text), {});
+export function headings(text, { parse = defaultParse() } = {}) {
+  if (parse === null) return [];
+  const toks = parse(blankFrontmatter(text));
   const starts = lineStarts(text);
   const out = [];
   for (let i = 0; i < toks.length; i++) {
     const t = toks[i];
     if (t.type !== "heading_open" || !t.map) continue;
     if (!t.markup || !t.markup.startsWith("#")) continue; // setext — see the caveat above
+    // markdown-it follows `heading_open` with its `inline` token and maps blocks to lines of the
+    // parsed text; the fallbacks are for a token stream that does not (another parser version).
     const inline = toks[i + 1];
     out.push({
       depth: Number(t.tag.slice(1)),
@@ -138,64 +143,6 @@ export function headings(text) {
   return out;
 }
 
-/** Offsets of the `---` thematic breaks (in this knowledge base — a prose separator). */
-export function thematicBreaks(text) {
-  if (md === null) return [];
-  const starts = lineStarts(text);
-  return md
-    .parse(blankFrontmatter(text), {})
-    .filter((t) => t.type === "hr" && t.map)
-    .map((t) => starts[t.map[0]] ?? 0);
-}
-
-/**
- * A section's body: from the line AFTER the heading matching `match`, up to the next
- * heading of THE SAME OR A LOWER level. `{ heading, body }` or `null`.
- *
- * `match` — a regex over the heading text OR a predicate over `{depth,text,line,offset}`.
- *
- * Level-or-lower, not "exactly `##`": a `###` subsection inside the section does not
- * end it — that is exactly how the former expressions with the `(?=\n## )` lookahead
- * behaved. A regex cannot know this distinction in principle: it has no notion of level.
- *
- * `depth` — the CEILING on the level of the heading itself. Without it an `### Abstract`
- * quoted in an appendix becomes the abstract — and the abstract is judged with a
- * threshold of ZERO.
- *
- * `stopAtRule` additionally cuts the section off at the first `---`. That is NOT markdown
- * structure but a paper convention, and it is preserved deliberately: the conclusion has
- * a `---` before the appendices, and without that boundary a section with no following
- * `##` would reach to the end of the file.
- *
- * 🔴 A MERGED VERSION. On 2026-08-11 this function appeared SIMULTANEOUSLY in two places:
- * here (for `kb-lint`) and in `paper-lint.mjs` (richer — with the level ceiling, the
- * heading in the result and `stopAtRule`). Both were written within one hour by two
- * parallel passes, neither saw the other. Merged into the rich version: the weak one was
- * a subset, and keeping both would have meant diverging in behaviour at the very next edit.
- */
-export function sectionBody(
-  text,
-  match,
-  { depth = 6, stopAtRule = false } = {},
-) {
-  const test = typeof match === "function" ? match : (h) => match.test(h.text);
-  const hs = headings(text);
-  const i = hs.findIndex((h) => h.depth <= depth && test(h));
-  if (i === -1) return null;
-  const h = hs[i];
-  const next = hs.slice(i + 1).find((n) => n.depth <= h.depth);
-  let end = next ? next.offset : text.length;
-  if (stopAtRule) {
-    const hr = thematicBreaks(text).find((o) => o > h.offset && o < end);
-    if (hr !== undefined) end = hr;
-  }
-  // The body starts on the line AFTER the heading: the heading itself is not part of the
-  // section, just as the former expressions' group did not capture it.
-  const nl = text.indexOf("\n", h.offset);
-  const start = nl === -1 || nl + 1 > end ? end : nl + 1;
-  return { heading: h, body: text.slice(start, end) };
-}
-
 /**
  * Slicing the document into chunks "a heading + everything up to the next heading FROM
  * THE SAME RANGE of levels". → `[{ heading, raw, body }]`.
@@ -302,15 +249,15 @@ export function stripFences(text, { blank = false } = {}) {
  * indistinguishable from "the paper has no sections". A confident zero has already been
  * read as a finding four times in this repo; here it is inexpressible.
  */
-export function requireMarkdown() {
+export function requireMarkdown({ from = import.meta.url } = {}) {
   if (MD_AVAILABLE()) return;
-  // 🔴 THE CURE DEPENDS ON THE DELIVERY CHANNEL, AND NAMING THE WRONG ONE WASTES THE ERROR.
-  // Measured 2026-09-19: `npm pack` strips `package-lock.json` unconditionally, and a plugin copy
-  // gets `npm ci` only when a lockfile is present in the fetched root — so a plugin installed from
-  // npm has NO `node_modules`, with no log entry anywhere. Telling that user to run `npm i at the
-  // repo root` points at a repository they do not have. The channel is readable from this file's
-  // own location, so the message can name it instead of guessing.
-  const fromPluginCache = import.meta.url.includes("/.claude/plugins/");
+  // 🔴 THE CURE DEPENDS ON WHERE THIS COPY RUNS FROM. Measured 2026-09-19: a Claude Code plugin
+  // copy is installed without dependencies (`npm pack` strips `package-lock.json`, and the plugin
+  // cache runs `npm ci` only with a lockfile). The plugin channel was removed in #82, but a copy
+  // installed before then still runs from there, and "npm i at the repo root" would point its user
+  // at a repository they do not have. The location is readable from this file's own URL (`from`,
+  // a parameter only so a test can name a plugin-cache location without copying the file there).
+  const fromPluginCache = from.includes("/.claude/plugins/");
   console.error(
     "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" +

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();