paperlint 2.0.0

package/eslint-rules/review-findings-cause.harness.mjs

@@ -0,0 +1,228 @@
+/**
+ * `review/findings-cause` — both halves on real ESLint, plus a case where the old
+ * implementation LIED.
+ *
+ * The rule came over from the consumer (`checkReviewFindingsCause` in `paper-lint.mjs`),
+ * where findings were counted by regexes over the text. The third fixture here is not
+ * decoration: a table inside a ``` fence is an EXAMPLE of the format, not a report, and
+ * the text-based counter recorded it as a finding. In the AST it's a `code` node, and
+ * `tableRow` does not exist inside it. That is, the move removed a whole class of bugs,
+ * and this fixture pins it down.
+ */
+import assert from "node:assert/strict";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { ESLint } from "eslint";
+import markdown from "@eslint/markdown";
+import { recordCheck } from "vigiles";
+import reviewRules from "./review-findings-cause.mjs";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const FIX = join(HERE, "..", "fixtures", "review-findings-cause");
+
+/** Same language as the consumer: the rule judges markdown, not lines of text. */
+const eslint = new ESLint({
+  overrideConfigFile: true,
+  overrideConfig: [
+    {
+      files: ["**/*.md"],
+      plugins: { markdown, review: reviewRules },
+      language: "markdown/gfm",
+      languageOptions: { frontmatter: "yaml" },
+      rules: { "review/findings-cause": "error" },
+    },
+  ],
+});
+
+const on = async (file) =>
+  (await eslint.lintFiles([join(FIX, file)]))[0].messages;
+const cases = [];
+
+// ── 1. FIRES: three findings, no cause analysis.
+{
+  const m = await on("defect.md");
+  assert.equal(
+    m.length,
+    1,
+    `one finding was expected, got ${m.length}: ${JSON.stringify(m)}`,
+  );
+  assert.equal(m[0].ruleId, "review/findings-cause");
+  assert.match(
+    m[0].message,
+    /3 findings/,
+    "the message must name the NUMBER of findings",
+  );
+  assert.match(
+    m[0].message,
+    /PIPELINE/,
+    "and say the tool needs fixing, not the paragraph",
+  );
+  assert.equal(
+    m[0].line,
+    1,
+    "the finding is about the FILE, so the position is the start of the document",
+  );
+  cases.push(
+    "a report with findings and no cause analysis → a finding, the count is named",
+  );
+}
+
+// ── 2. STAYS SILENT on a report with an analysis. Without this half the rule is
+//      indistinguishable from one that always screams.
+{
+  const m = await on("clean.md");
+  assert.deepEqual(
+    m,
+    [],
+    `on a report with "Cause:" the rule must stay silent, got: ${JSON.stringify(m)}`,
+  );
+  cases.push("the same report with a cause analysis → silence");
+}
+
+// ── 3. 🔴 STAYS SILENT on a TABLE INSIDE A FENCE — the case the old text-based version
+//      counted as findings. This is the move's payoff, shown as a test.
+{
+  const m = await on("quiet-in-fence.md");
+  assert.deepEqual(
+    m,
+    [],
+    `a table inside a \`\`\` fence is an EXAMPLE of the format, not a report; the text-based ` +
+      `counter counted it, the AST must not. Got: ${JSON.stringify(m)}`,
+  );
+  cases.push(
+    "a table inside a fence → silence (the text-based version got this wrong)",
+  );
+}
+
+// ── 4. THRESHOLD — a consumer option, not a mechanism constant.
+{
+  const strict = new ESLint({
+    overrideConfigFile: true,
+    overrideConfig: [
+      {
+        files: ["**/*.md"],
+        plugins: { markdown, review: reviewRules },
+        language: "markdown/gfm",
+        languageOptions: { frontmatter: "yaml" },
+        rules: { "review/findings-cause": ["error", { minFindings: 99 }] },
+      },
+    ],
+  });
+  const m = (await strict.lintFiles([join(FIX, "defect.md")]))[0].messages;
+  assert.deepEqual(
+    m,
+    [],
+    "with a threshold above the finding count the rule must stay silent — the threshold is data",
+  );
+  cases.push(
+    "the threshold is passed as an option → with minFindings: 99, silence on the same file",
+  );
+}
+
+// ── 5. 🔴 "RULE FROM A DATE": an old report is known debt, not a finding. Without this
+//      option the rule would have opened at the first consumer with FORTY-NINE findings
+//      (measured: 84 reports, 0 new, 49 old), and a check that opens with a wall gets muted.
+{
+  const dated = new ESLint({
+    overrideConfigFile: true,
+    overrideConfig: [
+      {
+        files: ["**/*.md"],
+        plugins: { markdown, review: reviewRules },
+        language: "markdown/gfm",
+        languageOptions: { frontmatter: "yaml" },
+        rules: {
+          "review/findings-cause": ["error", { sinceCreated: "2026-08-23" }],
+        },
+      },
+    ],
+  });
+  const old = (await dated.lintFiles([join(FIX, "old-debt.md")]))[0].messages;
+  assert.deepEqual(
+    old,
+    [],
+    `a report older than the rule's date — debt, not a finding; got: ${JSON.stringify(old)}`,
+  );
+
+  // AND THE SECOND HALF OF THE OPTION: on a fresh report it must NOT exempt anything, or
+  // "rule from a date" turns into an off switch.
+  const fresh = (await dated.lintFiles([join(FIX, "defect.md")]))[0].messages;
+  assert.equal(
+    fresh.length,
+    1,
+    `a report AFTER the rule's date must be caught; got: ${JSON.stringify(fresh)}`,
+  );
+  cases.push(
+    "a report older than the rule's date → silence; a fresh one of the same shape → a finding",
+  );
+}
+
+recordCheck(cases.length);
+console.log(`review/findings-cause: ${cases.length} cases:`);
+for (const c of cases) console.log(`  ok  ${c}`);
+
+// ── THE MARKER COMES FROM AN OPTION, IT IS NOT HARDCODED ──────────────────────────────────────
+//
+// The default has been English since 2026-09-17. Before that it was the Russian word
+// "Причина:", and there was no way to change it: `causeMarker` was not threaded through the
+// CLI, so an English-speaking user could not satisfy an `error`-level rule at all. Both halves:
+//   a) with a foreign marker in the options, a report using IT passes;
+//   b) the same report without the option — a finding. Otherwise "option accepted" is
+//      indistinguishable from "the rule stays silent".
+//
+// ⚠️ The fixture's shape is load-bearing: findings are counted by NUMBERED table rows (and
+// bold list items), not by any list. The first draft of this block used a plain `- finding
+// one`, the rule never fired, and BOTH halves passed vacuously.
+{
+  const body = [
+    "---",
+    "created: 2026-09-01",
+    "---",
+    "",
+    "| # | what | where |",
+    "|---|---|---|",
+    "| 1 | a | §1 |",
+    "| 2 | b | §2 |",
+    "| 3 | c | §3 |",
+    "",
+    "Причина: the pipeline step that let them through.",
+    "",
+  ].join("\n");
+
+  const lintWith = async (options) => {
+    const e = new ESLint({
+      overrideConfigFile: true,
+      overrideConfig: [
+        {
+          files: ["**/*.md"],
+          plugins: { markdown, review: reviewRules },
+          language: "markdown/gfm",
+          languageOptions: { frontmatter: "yaml" },
+          rules: { "review/findings-cause": ["error", options] },
+        },
+      ],
+    });
+    return (
+      await e.lintText(body, { filePath: join(FIX, "option-probe.md") })
+    )[0].messages;
+  };
+
+  const withOpt = await lintWith({ minFindings: 3, causeMarker: "Причина:" });
+  assert.deepEqual(
+    withOpt,
+    [],
+    `the marker from the options must be accepted, got: ${JSON.stringify(withOpt)}`,
+  );
+
+  const withoutOpt = await lintWith({ minFindings: 3 });
+  assert.equal(
+    withoutOpt.length,
+    1,
+    "without the option the same marker is NOT counted as a cause — otherwise the option decides nothing",
+  );
+  assert.match(
+    withoutOpt[0].message,
+    /Cause:/,
+    "and the finding's text carries the ENGLISH default, not something absent from the file",
+  );
+}

package/eslint-rules/review-findings-cause.mjs

@@ -0,0 +1,135 @@
+/**
+ * `review/findings-cause` — a review report with findings and no analysis of the ROOT CAUSE.
+ *
+ * ── WHAT THIS RULE IS ──────────────────────────────────────────────────────────
+ * Pipeline convention: a paper review does not end with a list of findings, it ends
+ * with an answer to "what in the PIPELINE let this through" — a defective skill, a
+ * missing skill, a hook, a rule. Otherwise the paper text gets fixed while the tool
+ * that missed it stays the same, and the next paper arrives with the same defect.
+ *
+ * ── WHY THIS IS A MOVE, NOT A NEW RULE ──────────────────────────────────────────
+ * First unit of step 9 of the extraction: until 2026-09-15 the check lived in the
+ * consumer as `checkReviewFindingsCause` in `.claude/hooks/paper-lint.mjs` — a
+ * directory walk plus three regexes over the text.
+ *
+ * 🔴 AND THE MOVE HERE IS NOT A COPY, IT REMOVES A WHOLE CLASS OF BUGS. The old
+ * version counted findings like this:
+ *
+ *     tableRows  ←  ^\|\s*\d+\s*\|            a line starting with "| <number> |"
+ *     boldItems  ←  ^\s*[-*]\s+\*\*             a list item starting bold
+ *
+ * (the regexes are given WITHOUT trailing slashes and flags on purpose: an
+ * "asterisk-slash" sequence inside a block comment closes it — I tripped on this
+ * twice in one hour, the second time right here.)
+ *
+ * That is, a "table row" was recognized by how it's written, not by its markup: the
+ * same line inside a ``` fence counted as a finding, a leading space in the cell
+ * broke the count, and `*` and `-` had to be listed by hand. In the AST a table row
+ * is a `tableRow` node, and all three misses become inexpressible. This is exactly
+ * the base rule "parse markdown with a PARSER".
+ *
+ * ── WHAT STAYS AS CONSUMER DATA ───────────────────────────────────────────────
+ * The findings threshold is an option. The "rule from a date" (reports older than a
+ * given date are known debt, not a finding) DOES NOT MOVE HERE AT ALL: it's a fact
+ * about one consumer's corpus, and its home is that consumer's config via `ignores`,
+ * not the mechanism. The mechanism goes in the package, the data stays with the consumer.
+ */
+
+/** Numbered cell: the first column of a table row holding a single number. */
+const isNumbered = (row) => {
+  const first = row.children?.[0];
+  const text = (first?.children ?? [])
+    .map((c) => c.value ?? "")
+    .join("")
+    .trim();
+  return /^\d+$/.test(text);
+};
+
+/** Finding item: a list element starting with bold text — the finding's heading. */
+const isBoldItem = (item) => {
+  const para = item.children?.find((c) => c.type === "paragraph");
+  return para?.children?.[0]?.type === "strong";
+};
+
+export default {
+  rules: {
+    "findings-cause": {
+      meta: {
+        type: "suggestion",
+        docs: {
+          description:
+            "a review report with findings names what in the pipeline let them through",
+        },
+        schema: [
+          {
+            type: "object",
+            properties: {
+              minFindings: { type: "integer", minimum: 1 },
+              causeMarker: { type: "string" },
+              sinceCreated: {
+                type: "string",
+                pattern: "^\\d{4}-\\d{2}-\\d{2}$",
+              },
+            },
+            additionalProperties: false,
+          },
+        ],
+        messages: {
+          noCause:
+            "{{count}} findings and not one «{{marker}}» note. First name what in the PIPELINE let them through (a defective skill · a missing skill · a hook · a rule) and fix THAT: the text edit falls out of running the fixed tool, not instead of it.",
+        },
+      },
+      create(context) {
+        const {
+          minFindings = 3,
+          causeMarker = "Cause:",
+          sinceCreated,
+        } = context.options[0] ?? {};
+        let findings = 0;
+        let hasCause = false;
+        let created = "";
+
+        return {
+          // 🔴 "RULE FROM A DATE" — MECHANISM, DATE — DATA. A new check that opens with a
+          // wall of findings on a historical corpus gets muted the same day; so the
+          // consumer needs a way to say "before such-and-such date this is known debt,
+          // not a finding". Measured on the first consumer: 84 reports, 0 new would fire
+          // and 49 old — without this option the rule would have opened with forty-nine
+          // findings. The date is NOT hardcoded: it comes in as an option, read from
+          // `created` in the frontmatter, and a document with no date is treated as OLD
+          // only when the option is set — otherwise a missing frontmatter would become a
+          // way to dodge the rule.
+          yaml(node) {
+            created =
+              /^created:\s*(\d{4}-\d{2}-\d{2})/m.exec(node.value ?? "")?.[1] ??
+              "";
+          },
+          tableRow(node) {
+            if (isNumbered(node)) findings++;
+          },
+          listItem(node) {
+            if (isBoldItem(node)) findings++;
+          },
+          text(node) {
+            if (node.value.includes(causeMarker)) hasCause = true;
+          },
+          "root:exit"(node) {
+            if (hasCause || findings < minFindings) return;
+            if (sinceCreated && (!created || created < sinceCreated)) return;
+            // A finding about the FILE, not a line: what's missing isn't anywhere. So the
+            // position is the start of the document, the only honest place for "this is missing".
+            context.report({
+              loc: {
+                start: { line: 1, column: 0 },
+                end: { line: 1, column: 1 },
+              },
+              messageId: "noCause",
+              data: { count: String(findings), marker: causeMarker },
+              node,
+            });
+          },
+        };
+      },
+    },
+  },
+};

package/eslint-rules/review-findings-cause.mutations.mjs

@@ -0,0 +1,72 @@
+/**
+ * Battery for `review/findings-cause`. Three mutations, three different asserts: the rule
+ * must FIRE, must STAY SILENT when there's a cause analysis, and the threshold must come
+ * in as an option.
+ */
+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 RULE = join(HERE, "review-findings-cause.mjs");
+const HARNESS = join(HERE, "review-findings-cause.harness.mjs");
+
+process.exit(
+  runMutations({
+    root: ROOT,
+    runner: "node",
+    cases: [
+      {
+        name: "the rule stops reporting",
+        harness: HARNESS,
+        expect: "one finding was expected",
+        disables:
+          "the verdict itself — a report without a cause analysis passes silently",
+        edits: [
+          [
+            RULE,
+            "if (hasCause || findings < minFindings) return;",
+            "if (true) return;",
+          ],
+        ],
+      },
+      {
+        name: 'the "Cause:" marker stops being noticed',
+        harness: HARNESS,
+        expect: "the rule must stay silent",
+        disables:
+          "the exemption — a report WITH a cause analysis starts going red",
+        edits: [
+          [
+            RULE,
+            "if (node.value.includes(causeMarker)) hasCause = true;",
+            "void node;",
+          ],
+        ],
+      },
+      {
+        name: '"rule from a date" stops exempting',
+        harness: HARNESS,
+        expect: "debt, not a finding",
+        disables:
+          "exemption of the historical corpus — the rule opens with a wall of findings",
+        edits: [
+          [
+            RULE,
+            "if (sinceCreated && (!created || created < sinceCreated)) return;",
+            "if (false) return;",
+          ],
+        ],
+      },
+      {
+        name: "the threshold stops being an option",
+        harness: HARNESS,
+        expect: "the threshold is data",
+        disables:
+          "passing the threshold in from outside — the mechanism claims the data for itself",
+        edits: [[RULE, "context.options[0] ?? {}", "{}"]],
+      },
+    ],
+  }),
+);

package/eslint-rules/temp-root-realpath.harness.mjs

@@ -0,0 +1,176 @@
+/**
+ * `local/temp-root-realpath` — both halves on real ESLint, plus the corpus itself.
+ *
+ * 🔴 WHY THIS HARNESS EXISTS AT ALL, rather than stopping at the twenty-four fixes. The
+ * defect (issue #9) ONLY REPRODUCES ON macOS: there `/var` is a symlink to `/private/var`,
+ * and one directory gets two spellings. On Linux `realpathSync` is the identity, so no
+ * behavioral test can tell a fixed root apart from a broken one: removing the wrapper leaves
+ * the run GREEN. The only check that can even go red on Linux is structural: ask the AST
+ * whether the root is resolved at the point it's created. That is exactly why it is written
+ * as a linter rule and not an assert inside someone's harness.
+ *
+ * ⚠️ And a boundary, so the harness isn't mistaken for more: it asserts that the IDIOM is in
+ * place, not that macOS is now green. The latter is only checked on macOS, and CI here is one
+ * `ubuntu-latest` — recorded as a known limit, not papered over.
+ *
+ * Fixtures are strings through `lintText`, not files on disk: a defect file under `fixtures/`
+ * would fall under the config's own `**\/*.mjs` block and would make `npx eslint .` red on a
+ * healthy checkout. This is the same reason the `.tex` fixtures sit on `warn`.
+ */
+import assert from "node:assert/strict";
+import { ESLint } from "eslint";
+import { recordCheck } from "vigiles";
+import localRules from "./temp-root-realpath.mjs";
+
+const eslint = new ESLint({
+  overrideConfigFile: true,
+  overrideConfig: [
+    {
+      files: ["**/*.mjs"],
+      languageOptions: { ecmaVersion: 2024, sourceType: "module" },
+      plugins: { local: localRules },
+      rules: { "local/temp-root-realpath": "error" },
+    },
+  ],
+});
+
+/** @returns {Promise<import("eslint").Linter.LintMessage[]>} */
+const on = async (code) =>
+  (await eslint.lintText(code, { filePath: "probe.mjs" }))[0].messages;
+
+const HEAD =
+  'import { mkdtempSync, realpathSync } from "node:fs";\n' +
+  'import { tmpdir } from "node:os";\nimport { join } from "node:path";\n';
+
+const cases = [];
+
+// ── 1. FIRES: a root from `tmpdir()` with no resolve — exactly the shape from issue #9.
+{
+  const m = await on(
+    `${HEAD}const TMP = mkdtempSync(join(tmpdir(), "probe-"));\n`,
+  );
+  assert.equal(
+    m.length,
+    1,
+    `one finding was expected, got ${m.length}: ${JSON.stringify(m)}`,
+  );
+  assert.equal(m[0].ruleId, "local/temp-root-realpath");
+  assert.match(
+    m[0].message,
+    /realpathSync\(mkdtempSync/,
+    "the message must carry the FIX, not just the diagnosis",
+  );
+  assert.match(
+    m[0].message,
+    /private\/var/,
+    "and name the cause — why one directory gets two names",
+  );
+  cases.push(
+    "mkdtempSync(join(tmpdir(), …)) with no resolve → a finding, the fix is in the message",
+  );
+}
+
+// ── 2. STAYS SILENT on the fixed form. Without this half the rule is indistinguishable
+//      from one that screams at every `mkdtempSync`.
+{
+  const m = await on(
+    `${HEAD}const TMP = realpathSync(mkdtempSync(join(tmpdir(), "probe-")));\n`,
+  );
+  assert.deepEqual(
+    m,
+    [],
+    `the rule must stay silent on a resolved root, got: ${JSON.stringify(m)}`,
+  );
+  cases.push("realpathSync(mkdtempSync(join(tmpdir(), …))) → silence");
+}
+
+// ── 3. 🔴 STAYS SILENT ON A NESTED ROOT, and this is load-bearing, not a concession. The
+//      corpus has five of these (`mkdtempSync(join(TMP, "repo-"))`); they inherit their
+//      spelling from `TMP`, which is caught at ITS OWN spot. A rule that screamed here too
+//      would demand a double resolve — and for an `error`-level rule a false positive is
+//      worse than a miss: it gets turned off.
+{
+  const m = await on(
+    `${HEAD}const TMP = realpathSync(mkdtempSync(join(tmpdir(), "probe-")));\n` +
+      `const sub = mkdtempSync(join(TMP, "repo-"));\nvoid sub;\n`,
+  );
+  assert.deepEqual(
+    m,
+    [],
+    `a nested root inherits its spelling from the parent; got: ${JSON.stringify(m)}`,
+  );
+  cases.push(
+    "a nested mkdtempSync(join(TMP, …)) → silence (the parent is already resolved)",
+  );
+}
+
+// ── 4. A COMMENT AND A STRING ARE NOT A CALL. This is exactly why the rule parses the AST: a
+//      text-based guard looking for "mkdtempSync(join(tmpdir()" would find this very file and
+//      would have to exclude itself — the class of check string-based checks are banned for here.
+{
+  const m = await on(
+    `${HEAD}// mkdtempSync(join(tmpdir(), "in-a-comment-"))\n` +
+      `const doc = 'mkdtempSync(join(tmpdir(), "in-a-string-"))';\nvoid doc;\n`,
+  );
+  assert.deepEqual(
+    m,
+    [],
+    `text ABOUT a call is not a call; got: ${JSON.stringify(m)}`,
+  );
+  cases.push("the same sequence in a comment and a string → silence");
+}
+
+// ── 5. `fs.mkdtempSync` / `os.tmpdir()` through a namespace — the same thing under a
+//      different spelling.
+{
+  const ns =
+    'import * as fs from "node:fs";\nimport * as os from "node:os";\nimport { join } from "node:path";\n';
+  const bad = await on(
+    `${ns}const TMP = fs.mkdtempSync(join(os.tmpdir(), "probe-"));\n`,
+  );
+  assert.equal(
+    bad.length,
+    1,
+    `the namespaced spelling must be caught; got: ${JSON.stringify(bad)}`,
+  );
+  const good = await on(
+    `${ns}const TMP = fs.realpathSync(fs.mkdtempSync(join(os.tmpdir(), "probe-")));\n`,
+  );
+  assert.deepEqual(
+    good,
+    [],
+    `and it must be exempted too; got: ${JSON.stringify(good)}`,
+  );
+  cases.push(
+    "fs.mkdtempSync(join(os.tmpdir(), …)) is caught, fs.realpathSync(…) exempts it",
+  );
+}
+
+// ── 6. 🔴 THE CORPUS ITSELF IS CLEAN. The "silent" half on a made-up string says nothing
+//      about the repository: the rule could also be silent because it was never handed a
+//      single file (the recorded class — `scripts/rules-see-files.mjs`). So this check runs
+//      THE RULE OVER THE REAL TREE and requires many files, zero findings.
+{
+  const corpus = new ESLint({ cwd: new URL("..", import.meta.url).pathname });
+  const results = await corpus.lintFiles(["."]);
+  const hits = results.flatMap((r) =>
+    r.messages
+      .filter((msg) => msg.ruleId === "local/temp-root-realpath")
+      .map((msg) => `${r.filePath}:${msg.line}`),
+  );
+  assert.deepEqual(
+    hits,
+    [],
+    `the corpus must be clean of unresolved roots:\n${hits.join("\n")}`,
+  );
+  const linted = results.filter((r) => r.filePath.endsWith(".mjs")).length;
+  assert.ok(
+    linted > 50,
+    `the rule was only handed ${linted} .mjs files — zero findings on an empty input is NOT cleanliness`,
+  );
+  cases.push(`corpus: ${linted} .mjs files, zero unresolved roots`);
+}
+
+recordCheck(cases.length);
+console.log(`local/temp-root-realpath: ${cases.length} cases:`);
+for (const c of cases) console.log(`  ok  ${c}`);