paperlint 13.5.0 → 13.6.1

package/skills/build-label-page/scripts/label-page-core.test.ts

@@ -87,6 +87,7 @@ const FULL: DocObject = (() => {
               title: "T",
               code: "c = 1",
               context: "ctx",
+              rules: [{ linter: "eslint", id: "no-console" }],
               unit: { id: "L0", text: "One line.", part: 1, of: 1 },
             }
           : i,
@@ -1175,6 +1176,102 @@ test("🔴 a question dropped between practice rounds: the earlier round's answe
   assert.match(r.out, /practice round 1: 3 of 3 matched/);
 });
 
+test("🔴 an item that names a linter rule: the build takes the rule's description from the linter, and refuses one it cannot describe", () => {
+  const named = (rules: readonly Record<string, string>[]) =>
+    config({
+      items: ITEMS.map((item, n) => (n === 0 ? { ...item, rules } : item)),
+    });
+  const { page } = build(
+    setup("rules-ok", named([{ linter: "eslint", id: "no-console" }])),
+  );
+  assert.ok(
+    page.includes(
+      '"rules": [{"linter": "eslint", "id": "no-console", "description": "Disallow the use of `console`"}]',
+    ),
+    "the page carries the linter's own description",
+  );
+  const dir = setup(
+    "rules-unknown",
+    named([{ linter: "eslint", id: "no-such-rule" }]),
+  );
+  const r = run(["build", join(dir, "items.json"), join(dir, "out")]);
+  assert.equal(r.status, 1, r.out);
+  assert.match(
+    r.out,
+    /REFUSED: items\[0\]\.rules\[0\]: eslint 'no-such-rule' has no description from the linter/,
+  );
+  // ruff answers the same whether it is missing or does not know the code: no description.
+  const ruff = setup(
+    "rules-ruff-unknown",
+    named([{ linter: "ruff", id: "NOPE1" }]),
+  );
+  const r2 = run(["build", join(ruff, "items.json"), join(ruff, "out")]);
+  assert.equal(r2.status, 1, r2.out);
+  assert.match(
+    r2.out,
+    /ruff 'NOPE1' has no description from the linter \(`ruff rule` does not know it/,
+  );
+});
+
+test("🔴 familiarity off: the key asks for none, the export reports no missing familiarity, and a stored one is refused", () => {
+  const dir = setup("familiarity-off", approval({ familiarity: false }));
+  const { key } = build(dir);
+  assert.deepEqual(key.allowed.familiarity, []);
+  const [a] = Object.keys(key.ids);
+  assert.ok(a !== undefined);
+  writeFileSync(
+    join(dir, "dump.json"),
+    JSON.stringify({
+      answers: { [a]: { answers: { keep: "keep" }, source: "page" } },
+      groups: {},
+    }),
+  );
+  const r = exportAt(dir);
+  assert.equal(r.status, 0, r.out);
+  assert.doesNotMatch(r.out, /no familiarity answer|invalid group/);
+  assert.deepEqual(Exported.parse(JSON.parse(labelsFile(dir))).groups, {});
+  writeFileSync(
+    join(dir, "dump.json"),
+    JSON.stringify({
+      answers: {},
+      groups: { python: { familiarity: "well", source: "chat" } },
+    }),
+  );
+  const refused = exportAt(dir);
+  assert.notEqual(refused.status, 0);
+  assert.match(refused.out, /groups\/python: .*familiarity is off/);
+});
+
+test("🔴 familiarity off with a familiarity_question is a contradiction the build refuses", () => {
+  const r = run([
+    "build",
+    join(
+      setup(
+        "familiarity-contradiction",
+        approval({ familiarity: false, familiarity_question: "How well?" }),
+      ),
+      "items.json",
+    ),
+    join(WORK, "contradiction-out"),
+  ]);
+  assert.notEqual(r.status, 0);
+  assert.match(
+    r.out,
+    /REFUSED: familiarity_question: .*`familiarity` is false/,
+  );
+});
+
+test("familiarity left out: every group is still asked (rule 5), and a missing one is reported", () => {
+  const dir = setup("familiarity-default", approval());
+  const { key } = build(dir);
+  assert.deepEqual(key.allowed.familiarity, ["well", "somewhat", "not_really"]);
+  writeFileSync(
+    join(dir, "dump.json"),
+    JSON.stringify({ answers: {}, groups: {} }),
+  );
+  assert.match(exportAt(dir).out, /group python: no familiarity answer/);
+});
+
 /** Items 0 and 3 (both Rust) as the two requirements of one line. */
 const LINE = "TypeScript only (no JavaScript); top-level await is allowed.";
 const withUnit = (
@@ -1306,62 +1403,3 @@ test("🔴 the same line in two places is two lines: four items, two ids, it bui
   const { page } = build(dir);
   assert.ok(!page.includes("a.md:3"), "the line's id is private");
 });
-
-test("🔴 familiarity off: the key asks for none, the export reports no missing familiarity, and a stored one is refused", () => {
-  const dir = setup("familiarity-off", approval({ familiarity: false }));
-  const { key } = build(dir);
-  assert.deepEqual(key.allowed.familiarity, []);
-  const [a] = Object.keys(key.ids);
-  assert.ok(a !== undefined);
-  writeFileSync(
-    join(dir, "dump.json"),
-    JSON.stringify({
-      answers: { [a]: { answers: { keep: "keep" }, source: "page" } },
-      groups: {},
-    }),
-  );
-  const r = exportAt(dir);
-  assert.equal(r.status, 0, r.out);
-  assert.doesNotMatch(r.out, /no familiarity answer|invalid group/);
-  assert.deepEqual(Exported.parse(JSON.parse(labelsFile(dir))).groups, {});
-  writeFileSync(
-    join(dir, "dump.json"),
-    JSON.stringify({
-      answers: {},
-      groups: { python: { familiarity: "well", source: "chat" } },
-    }),
-  );
-  const refused = exportAt(dir);
-  assert.notEqual(refused.status, 0);
-  assert.match(refused.out, /groups\/python: .*familiarity is off/);
-});
-
-test("🔴 familiarity off with a familiarity_question is a contradiction the build refuses", () => {
-  const r = run([
-    "build",
-    join(
-      setup(
-        "familiarity-contradiction",
-        approval({ familiarity: false, familiarity_question: "How well?" }),
-      ),
-      "items.json",
-    ),
-    join(WORK, "contradiction-out"),
-  ]);
-  assert.notEqual(r.status, 0);
-  assert.match(
-    r.out,
-    /REFUSED: familiarity_question: .*`familiarity` is false/,
-  );
-});
-
-test("familiarity left out: every group is still asked (rule 5), and a missing one is reported", () => {
-  const dir = setup("familiarity-default", approval());
-  const { key } = build(dir);
-  assert.deepEqual(key.allowed.familiarity, ["well", "somewhat", "not_really"]);
-  writeFileSync(
-    join(dir, "dump.json"),
-    JSON.stringify({ answers: {}, groups: {} }),
-  );
-  assert.match(exportAt(dir).out, /group python: no familiarity answer/);
-});

package/skills/build-label-page/scripts/label-page-core.ts

@@ -6,8 +6,9 @@
  */
 import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { z } from "zod";
+import { describeRule, type RuleRef } from "./rule-descriptions.ts";
 
 // ── refusals and output ───────────────────────────────────────────────────────────────────────
 export class Refusal extends Error {
@@ -94,11 +95,15 @@ const readJson = (path: string): Json => {
 // labeller what the answer is, or where the item came from?" — never to make a build pass.
 const PAGE_FIELDS = ["group", "title", "body", "code", "context"] as const;
 const PRIVATE_FIELDS = ["source_id"] as const;
+// The linter rules an item names ("read as ruff `TID253`"): the page shows each with the linter's
+// own description, looked up at build time (rule-descriptions.ts), never typed into items.json.
+const RULES_FIELD = "rules";
 // One requirement of a line that holds several: the whole line and which part this item is. Shown on
 // the card beneath the item; the line is text the labeller may read, like `context`.
 const UNIT_FIELD = "unit";
 const ALLOWED_FIELDS: readonly string[] = [
   ...PAGE_FIELDS,
+  RULES_FIELD,
   UNIT_FIELD,
   ...PRIVATE_FIELDS,
 ];
@@ -196,6 +201,11 @@ const ITEM_SCHEMA = obj(
     ...Object.fromEntries(
       PAGE_FIELDS.map((f) => [f, string(f === "group" || f === "body")]),
     ),
+    [RULES_FIELD]: array(
+      obj({ linter: string(true, "eslint|ruff"), id: string() }),
+      false,
+      1,
+    ),
     [UNIT_FIELD]: obj(
       // `id` names one occurrence of the line (two files may hold the same words): never shown.
       { id: string(), text: string(), part: integer(), of: integer() },
@@ -374,6 +384,7 @@ type Item = {
   readonly source_id: string;
   readonly group: string;
   readonly body: string;
+  readonly rules?: readonly RuleRef[];
   readonly unit?: Unit;
 };
 interface Practice {
@@ -725,6 +736,34 @@ const shownFields = (
         },
       }),
 });
+/** Rule → the linter's description, for every rule an item on the page names. */
+type Described = ReadonlyMap<string, string>;
+const ruleKey = (r: RuleRef): string => `${r.linter} ${r.id}`;
+/** Ask the linter for every rule named; refuse, by path, a rule it cannot describe. */
+function describeRules(cfg: Config, fromDir: string): Described {
+  return new Map(
+    cfg.items.flatMap((item, n) =>
+      (item.rules ?? []).map((r, k): readonly [string, string] => {
+        const text = describeRule(r, fromDir);
+        return text === undefined
+          ? fail(
+              `items[${String(n)}].rules[${String(k)}]: ${r.linter} ${repr(r.id)} has no description from the linter (${r.linter === "ruff" ? "`ruff rule` does not know it, or ruff is not on PATH" : "not a rule of the ESLint, or of a plugin, installed where items.json is"}) — check the id`,
+            )
+          : [ruleKey(r), text];
+      }),
+    ),
+  );
+}
+const rulesShown = (item: Item, described: Described) =>
+  item.rules === undefined
+    ? {}
+    : {
+        [RULES_FIELD]: item.rules.map((r) => ({
+          linter: r.linter,
+          id: r.id,
+          description: String(described.get(ruleKey(r))),
+        })),
+      };
 
 /** Only what the labeller can answer goes on the page, and only that gets an id, in id order. */
 function itemsOnPage(cfg: Config, keyPath: string) {
@@ -742,7 +781,11 @@ function itemsOnPage(cfg: Config, keyPath: string) {
 const practiceRound = (cfg: Config): number => cfg.practice_round ?? 1;
 
 /** What a page shows: the questions, the practice and the items, blind, with their neutral ids. */
-function payloadOf(cfg: Config, page: ReturnType<typeof itemsOnPage>) {
+function payloadOf(
+  cfg: Config,
+  page: ReturnType<typeof itemsOnPage>,
+  described: Described,
+) {
   const used = Object.keys(cfg.groups).filter((g) =>
     page.items.some((i) => i.group === g),
   );
@@ -757,7 +800,11 @@ function payloadOf(cfg: Config, page: ReturnType<typeof itemsOnPage>) {
     allowed: allowedValues(cfg.questions, asksFamiliarity(cfg)),
     questions: cfg.questions,
     practice: { round: practiceRound(cfg), items: practiceOf(cfg) },
-    items: page.items.map((i) => ({ id: page.idOf(i), ...shownFields(i) })),
+    items: page.items.map((i) => ({
+      id: page.idOf(i),
+      ...shownFields(i),
+      ...rulesShown(i, described),
+    })),
   };
 }
 export type Payload = ReturnType<typeof payloadOf>;
@@ -837,13 +884,14 @@ export function prepareBuild(configPath: string, outDir: string) {
   checkItemFields(cfg);
   checkUnits(cfg);
   checkNoSourceShown(cfg);
+  const described = describeRules(cfg, dirname(configPath));
   mkdirSync(outDir, { recursive: true });
   const keyPath = join(outDir, "key.json");
   const earlier = roundsOf(keyPath);
   const page = itemsOnPage(cfg, keyPath);
   writeJson(keyPath, keyOf(cfg, page, earlier));
   return {
-    payload: payloadOf(cfg, page),
+    payload: payloadOf(cfg, page, described),
     dropped: cfg.items.length - page.items.length,
   };
 }

package/skills/build-label-page/scripts/label-page-html.test.ts

@@ -412,26 +412,15 @@ test("🔴 without the store the page is read-only, and the real items stay read
   assert.match(shown, /G001/, "a real item is shown read-only");
 });
 
-test("🔴 one requirement of a line: its card shows which part it is and the whole line beneath", async () => {
-  const line = "TypeScript only (no JavaScript); top-level await is allowed.";
+test("🔴 an item that names a rule: its card says which rule and what it does, in the linter's words", async () => {
   const { page } = build(
     setup(
-      "unit-card",
+      "rules-card",
       config({
         items: ITEMS.map((item, n) =>
           n === 0
-            ? {
-                ...item,
-                body: "TypeScript only (no JavaScript)",
-                unit: { id: "L1", text: line, part: 1, of: 2 },
-              }
-            : n === 3
-              ? {
-                  ...item,
-                  body: "top-level await is allowed",
-                  unit: { id: "L1", text: line, part: 2, of: 2 },
-                }
-              : item,
+            ? { ...item, rules: [{ linter: "eslint", id: "no-console" }] }
+            : item,
         ),
       }),
     ),
@@ -439,14 +428,13 @@ test("🔴 one requirement of a line: its card shows which part it is and the wh
   const shown = await showPage(page, {}, {});
   assert.match(
     shown,
-    /From the line \(requirement 1 of 2\):\nTypeScript only \(no JavaScript\); top-level await is allowed\./,
+    /Rule eslint no-console: Disallow the use of \nconsole\n/,
     shown,
   );
-  assert.match(shown, /From the line \(requirement 2 of 2\):/);
   assert.equal(
-    occurrences(shown, "From the line"),
-    2,
-    "only the two parts carry the line",
+    occurrences(shown, "Rule eslint"),
+    1,
+    "only the item that names it",
   );
 });
 
@@ -471,3 +459,41 @@ test("🔴 familiarity off: no group asks how well it is known, and a group is d
   assert.doesNotMatch(shown, /how well you know it/);
   assert.match(shown, /Nothing left/, shown);
 });
+
+test("🔴 one requirement of a line: its card shows which part it is and the whole line beneath", async () => {
+  const line = "TypeScript only (no JavaScript); top-level await is allowed.";
+  const { page } = build(
+    setup(
+      "unit-card",
+      config({
+        items: ITEMS.map((item, n) =>
+          n === 0
+            ? {
+                ...item,
+                body: "TypeScript only (no JavaScript)",
+                unit: { id: "L1", text: line, part: 1, of: 2 },
+              }
+            : n === 3
+              ? {
+                  ...item,
+                  body: "top-level await is allowed",
+                  unit: { id: "L1", text: line, part: 2, of: 2 },
+                }
+              : item,
+        ),
+      }),
+    ),
+  );
+  const shown = await showPage(page, {}, {});
+  assert.match(
+    shown,
+    /From the line \(requirement 1 of 2\):\nTypeScript only \(no JavaScript\); top-level await is allowed\./,
+    shown,
+  );
+  assert.match(shown, /From the line \(requirement 2 of 2\):/);
+  assert.equal(
+    occurrences(shown, "From the line"),
+    2,
+    "only the two parts carry the line",
+  );
+});

package/skills/build-label-page/scripts/label-page.js

@@ -54,7 +54,10 @@
  *     "practice_round": 1,                  optional; raise it after rewording, the practice reopens
  *     "items": [{"source_id": "case-0412-b", "group": "python", "body": "…", "code": "…",
  *                "context": "…",
+ *                "rules": [{"linter": "ruff", "id": "TID253"}],
  *                "unit": {"id": "a.md:12", "text": "the whole line", "part": 1, "of": 2}}]
+ *                                           rules: optional; each shown with the linter's own
+ *                                           description (`ruff rule`, ESLint meta.docs.description)
  *                                           unit: optional; one requirement of a line that holds
  *                                           several. Every part of the line is an item, in one group;
  *                                           id (never shown) tells two places with the same words apart.

package/skills/build-label-page/scripts/label-page.ts

@@ -54,7 +54,10 @@
  *     "practice_round": 1,                  optional; raise it after rewording, the practice reopens
  *     "items": [{"source_id": "case-0412-b", "group": "python", "body": "…", "code": "…",
  *                "context": "…",
+ *                "rules": [{"linter": "ruff", "id": "TID253"}],
  *                "unit": {"id": "a.md:12", "text": "the whole line", "part": 1, "of": 2}}]
+ *                                           rules: optional; each shown with the linter's own
+ *                                           description (`ruff rule`, ESLint meta.docs.description)
  *                                           unit: optional; one requirement of a line that holds
  *                                           several. Every part of the line is an item, in one group;
  *                                           id (never shown) tells two places with the same words apart.

package/skills/build-label-page/scripts/page-template.html

@@ -312,6 +312,10 @@ pre { overflow-x: auto; background: var(--surface); border: 1px solid var(--line
     card.appendChild(rich("p", "body", item.body));
     if (item.code) card.appendChild(codeBlock(item.code));
     if (item.context) card.appendChild(rich("p", "muted", item.context));
+    // A rule the item names, with what it does in the linter's own words (looked up at build time).
+    (item.rules || []).forEach(function (r) {
+      card.appendChild(rich("p", "muted", "Rule " + r.linter + " " + r.id + ": " + r.description));
+    });
     // One requirement of a line that holds several: which one, and the whole line it came from.
     if (item.unit) {
       card.appendChild(el("p", "muted", "From the line (requirement " + item.unit.part + " of " + item.unit.of + "):"));

package/skills/build-label-page/scripts/rule-descriptions.js

@@ -0,0 +1,82 @@
+/**
+ * What a linter rule does, in the linter's own words, for the card of an item that names one
+ * ("read as ruff `TID253`" means nothing to a labeller who has not met the code). Never invented: a
+ * rule the linter cannot describe has no description, and the build refuses it.
+ *
+ * - ruff: `ruff rule <code> --output-format json`, the paragraph under "## What it does".
+ * - ESLint: the rule's `meta.docs.description`, from the ESLint (and the plugin) installed where
+ *   items.json is: a study's own install, found by Node's resolution from that folder upwards.
+ *   A plugin rule is found by ESLint's naming convention (`@scope/rule` → `@scope/eslint-plugin`,
+ *   `@scope/p/rule` → `@scope/eslint-plugin-p`, `p/rule` → `eslint-plugin-p`).
+ */
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { resolve } from "node:path";
+import { z } from "zod";
+export const runProcess = (cmd, args) => {
+    const r = spawnSync(cmd, args, { encoding: "utf8" });
+    return { status: r.status, stdout: r.stdout };
+};
+const RuffRule = z.object({ explanation: z.string() });
+/** The paragraph under "## What it does", its lines joined. */
+function ruffDescription(id, run) {
+    const r = run("ruff", ["rule", id, "--output-format", "json"]);
+    if (r.status !== 0)
+        return undefined;
+    const { explanation } = RuffRule.parse(JSON.parse(r.stdout));
+    const what = /## What it does\n([\s\S]*?)(?:\n\n|$)/.exec(explanation)?.[1];
+    return what?.split("\n").join(" ").trim();
+}
+const RuleModule = z.object({
+    meta: z.object({ docs: z.object({ description: z.string() }) }),
+});
+const Plugin = z.object({ rules: z.record(z.string(), z.unknown()) });
+const Builtins = z.object({
+    builtinRules: z.map(z.string(), z.unknown()),
+});
+/** The package and the rule name a namespaced ESLint rule id points at. */
+function pluginOf(id) {
+    const parts = id.split("/");
+    const name = id.slice(id.lastIndexOf("/") + 1);
+    const [scope, plugin] = parts;
+    if (id.startsWith("@"))
+        return [
+            parts.length === 2
+                ? `${String(scope)}/eslint-plugin`
+                : `${String(scope)}/eslint-plugin-${String(plugin)}`,
+            name,
+        ];
+    return [`eslint-plugin-${String(scope)}`, name];
+}
+// `require` of an ES-module plugin returns its namespace: the plugin object is then its `default`.
+const EsmPlugin = z.object({ default: Plugin });
+const pluginRules = (mod) => {
+    const esm = EsmPlugin.safeParse(mod);
+    return esm.success ? esm.data.default.rules : Plugin.parse(mod).rules;
+};
+const description = (rule) => {
+    const r = RuleModule.safeParse(rule);
+    return r.success ? r.data.meta.docs.description : undefined;
+};
+function eslintDescription(id, fromDir) {
+    // createRequire takes an absolute path only; items.json is often named relative to the study folder.
+    const load = createRequire(resolve(fromDir, "items.json"));
+    try {
+        if (!id.includes("/")) {
+            const core = Builtins.parse(load("eslint/use-at-your-own-risk"));
+            return description(core.builtinRules.get(id));
+        }
+        const [pkg, name] = pluginOf(id);
+        return description(pluginRules(load(pkg))[name]);
+    }
+    catch {
+        // ESLint or the plugin is not installed where items.json is: the linter cannot answer.
+        return undefined;
+    }
+}
+/** The linter's own one-line description of `ref`, or undefined when it has none. */
+export function describeRule(ref, fromDir, run = runProcess) {
+    return ref.linter === "ruff"
+        ? ruffDescription(ref.id, run)
+        : eslintDescription(ref.id, fromDir);
+}

package/skills/build-label-page/scripts/rule-descriptions.test.ts

@@ -0,0 +1,118 @@
+/**
+ * What a rule does, in the linter's own words. ESLint against the copy installed in this repository
+ * (a real catalogue, no network); ruff through a stand-in process holding what `ruff 0.16.9 rule TID253
+ * --output-format json` printed (fixtures/ruff-rule-TID253.json), so no test needs the ruff binary.
+ */
+import assert from "node:assert/strict";
+import {
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  realpathSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join, relative } from "node:path";
+import { test } from "vitest";
+import {
+  describeRule,
+  runProcess,
+  type RunProcess,
+} from "./rule-descriptions.ts";
+
+const REPO = join(import.meta.dirname, "..", "..", "..");
+const TID253 = readFileSync(
+  join(import.meta.dirname, "fixtures", "ruff-rule-TID253.json"),
+  "utf8",
+);
+/** `ruff rule <code>` as the binary answers: the recorded JSON for TID253, exit 2 for anything else. */
+const fakeRuff: RunProcess = (cmd, args) =>
+  cmd === "ruff" && args[1] === "TID253"
+    ? { status: 0, stdout: TID253 }
+    : { status: 2, stdout: "" };
+
+test("🔴 a ruff rule is described by its own 'What it does' paragraph, on one line", () => {
+  assert.equal(
+    describeRule({ linter: "ruff", id: "TID253" }, REPO, fakeRuff),
+    "Checks for module-level imports that should instead be imported lazily (e.g., within a function definition, or an `if TYPE_CHECKING:` block, or some other nested context).",
+  );
+});
+
+test("🔴 an ESLint rule is described by meta.docs.description: a core rule, and a plugin rule resolved by the plugin naming convention", () => {
+  assert.equal(
+    describeRule({ linter: "eslint", id: "no-console" }, REPO, fakeRuff),
+    "Disallow the use of `console`",
+  );
+  assert.equal(
+    describeRule(
+      { linter: "eslint", id: "@typescript-eslint/no-explicit-any" },
+      REPO,
+      fakeRuff,
+    ),
+    "Disallow the `any` type",
+  );
+});
+
+test("a rule the linter does not know, or a plugin that is not installed has no description (never an invented one)", () => {
+  const none = [
+    describeRule({ linter: "ruff", id: "NOPE1" }, REPO, fakeRuff),
+    describeRule({ linter: "eslint", id: "no-such-rule" }, REPO, fakeRuff),
+    describeRule({ linter: "eslint", id: "nope/rule" }, REPO, fakeRuff),
+    describeRule({ linter: "eslint", id: "@nope/x/rule" }, REPO, fakeRuff),
+    // ruff answers, but without a "What it does" section
+    describeRule({ linter: "ruff", id: "TID253" }, REPO, () => ({
+      status: 0,
+      stdout: JSON.stringify({ explanation: "## Why is this bad?\nx" }),
+    })),
+  ];
+  assert.deepEqual(none, [
+    undefined,
+    undefined,
+    undefined,
+    undefined,
+    undefined,
+  ]);
+});
+
+test("the real process runner returns the exit status and what was printed (node stands in for ruff)", () => {
+  assert.deepEqual(
+    runProcess(process.execPath, [
+      "-e",
+      "process.stdout.write('x'); process.exit(3)",
+    ]),
+    { status: 3, stdout: "x" },
+  );
+});
+
+test("🔴 a relative folder (the documented `build items.json label-page`) is resolved before ESLint is looked up", () => {
+  assert.equal(
+    describeRule(
+      { linter: "eslint", id: "no-console" },
+      relative(process.cwd(), REPO) || ".",
+      fakeRuff,
+    ),
+    "Disallow the use of `console`",
+  );
+});
+
+test("🔴 an ES-module plugin whose rules sit under its default export is described too", () => {
+  const dir = realpathSync(mkdtempSync(join(tmpdir(), "esm-plugin-")));
+  const pkg = join(dir, "node_modules", "eslint-plugin-esmonly");
+  mkdirSync(pkg, { recursive: true });
+  writeFileSync(
+    join(pkg, "package.json"),
+    JSON.stringify({
+      name: "eslint-plugin-esmonly",
+      type: "module",
+      main: "index.js",
+    }),
+  );
+  writeFileSync(
+    join(pkg, "index.js"),
+    'export default { rules: { r: { meta: { docs: { description: "Only via default" } } } } };\n',
+  );
+  assert.equal(
+    describeRule({ linter: "eslint", id: "esmonly/r" }, dir, fakeRuff),
+    "Only via default",
+  );
+});