paperlint 13.6.0 → 14.0.0

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

@@ -35,12 +35,14 @@
  *
  *   {
  *     "study": "demo-gold",                 file-name stem
+ *     "kind": "labels",                     approval | witness | labels: which card fields are required
  *     "title": "Label these",               2-4 words; the page title
  *     "intro": "One or two sentences.",     optional
  *     "seed": 7,                            fixes the order; change it and every id changes
  *     "groups": {"python": "Python"},
  *     "labeller_knows": ["python"],         optional: items of other groups are not put on the page
- *     "familiarity": false,                 optional: no "how well do you know" question (approval page)
+ *     "familiarity": true,                  optional: a "how well do you know" question per group;
+ *                                           left out, none is asked (an approval page)
  *     "familiarity_question": "How well do you know {group}?",          optional
  *     "questions": [{"id": "label", "text": "Is this correct?", "short": "correct?",
  *                    "options": [{"value": "yes", "label": "Yes", "example": "one real case",
@@ -50,17 +52,20 @@
  *                                           ask_why: optional; the answer is incomplete until a
  *                                           reason is given. In any shown text, backticks render
  *                                           as code.
- *     "practice": [{"body": "…", "expected": {"label": "yes"}, "why": "one line"}, …],   3 or more
+ *     "practice": [{"body": "…", "expected": {"label": "yes"}, "why": "one line"}, …],   3 or more;
+ *                                           a practice card may carry rules, unit, readings, file
  *     "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}}]
+ *                "unit": {"id": "a.md:12", "text": "the whole line", "mark": "whole", "part": 1, "of": 2},
+ *                "readings": {"a": "…", "b": "…"}, "file": "`src/a.ts`: B flags it"}]
  *                                           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.
+ *                                           unit: optional; the line an item is drawn from, the
+ *                                           requirement marked in it; id (never shown) tells two
+ *                                           places with the same words apart. kind approval requires
+ *                                           unit and rules; kind witness rules, readings and file.
  *   }
  *
  * TypeScript, compiled beside itself to `label-page.js` by `npm run build`: a consumer runs the skill

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

@@ -35,12 +35,14 @@
  *
  *   {
  *     "study": "demo-gold",                 file-name stem
+ *     "kind": "labels",                     approval | witness | labels: which card fields are required
  *     "title": "Label these",               2-4 words; the page title
  *     "intro": "One or two sentences.",     optional
  *     "seed": 7,                            fixes the order; change it and every id changes
  *     "groups": {"python": "Python"},
  *     "labeller_knows": ["python"],         optional: items of other groups are not put on the page
- *     "familiarity": false,                 optional: no "how well do you know" question (approval page)
+ *     "familiarity": true,                  optional: a "how well do you know" question per group;
+ *                                           left out, none is asked (an approval page)
  *     "familiarity_question": "How well do you know {group}?",          optional
  *     "questions": [{"id": "label", "text": "Is this correct?", "short": "correct?",
  *                    "options": [{"value": "yes", "label": "Yes", "example": "one real case",
@@ -50,17 +52,20 @@
  *                                           ask_why: optional; the answer is incomplete until a
  *                                           reason is given. In any shown text, backticks render
  *                                           as code.
- *     "practice": [{"body": "…", "expected": {"label": "yes"}, "why": "one line"}, …],   3 or more
+ *     "practice": [{"body": "…", "expected": {"label": "yes"}, "why": "one line"}, …],   3 or more;
+ *                                           a practice card may carry rules, unit, readings, file
  *     "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}}]
+ *                "unit": {"id": "a.md:12", "text": "the whole line", "mark": "whole", "part": 1, "of": 2},
+ *                "readings": {"a": "…", "b": "…"}, "file": "`src/a.ts`: B flags it"}]
  *                                           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.
+ *                                           unit: optional; the line an item is drawn from, the
+ *                                           requirement marked in it; id (never shown) tells two
+ *                                           places with the same words apart. kind approval requires
+ *                                           unit and rules; kind witness rules, readings and file.
  *   }
  *
  * TypeScript, compiled beside itself to `label-page.js` by `npm run build`: a consumer runs the skill

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

@@ -19,7 +19,7 @@
 html, body { margin: 0; background: var(--bg); color: var(--text); font-family: var(--sans);
   font-size: 16px; line-height: 1.6; }
 main { max-width: 760px; margin: 0 auto; padding: 24px 16px 64px; display: flex; flex-direction: column;
-  gap: var(--gap-section); }
+  gap: var(--gap-section); overflow-wrap: anywhere; }
 main > * + section, main > section + * { border-top: 1px solid var(--line); padding-top: var(--gap-section); }
 header.top { display: flex; flex-direction: column; gap: 8px; }
 h1 { font-size: 1.5rem; line-height: 1.3; margin: 0; color: var(--strong); font-weight: 700; }
@@ -28,8 +28,15 @@ p { margin: 0; max-width: var(--measure); }
 .muted { color: var(--muted); }
 .id { font-family: var(--mono); color: var(--muted); }
 section { display: flex; flex-direction: column; gap: var(--gap-item); }
-.item { display: flex; flex-direction: column; gap: 12px; padding-top: var(--gap-item);
+.item { display: flex; flex-direction: column; gap: 20px; padding-top: var(--gap-item);
   border-top: 1px solid var(--line); }
+/* The evidence of a card: one labelled row per field, the label a short word above its content. The two
+   readings sit in the same place on every card: A on a solid accent rule, B on a dashed one. */
+.row { display: flex; flex-direction: column; gap: 4px; }
+.lbl { color: var(--muted); font-size: 0.8rem; letter-spacing: 0.08em; text-transform: uppercase; }
+.reading { border-left: 3px solid var(--accent); padding-left: 12px; }
+.reading.b { border-left: 3px dashed var(--text); }
+mark { background: transparent; color: var(--mark); font-weight: 500; }
 .item:first-of-type { border-top: 0; padding-top: 0; }
 .ask { background: var(--surface); border: 1px solid var(--line); border-radius: 12px; padding: 16px;
   display: flex; flex-direction: column; gap: 12px; }
@@ -308,19 +315,7 @@ pre { overflow-x: auto; background: var(--surface); border: 1px solid var(--line
     var done = itemDone(item.id);
     var card = el("article", "item");
     card.appendChild(el("div", "id", item.id));
-    if (item.title) card.appendChild(rich("h3", "", item.title));
-    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 + "):"));
-      card.appendChild(rich("p", "quote", item.unit.text));
-    }
+    evidence(card, item);
     var a = answersOf(item.id);
     askOne(card, a, state.editing[item.id], function (q, v) {
       delete state.editing[item.id];
@@ -351,6 +346,40 @@ pre { overflow-x: auto; background: var(--surface); border: 1px solid var(--line
     card.appendChild(statusLine(item.id, missingFor(item.id), saved));
     return card;
   }
+  // A labelled row: a short word, then what it labels.
+  function row(label, content, cls) {
+    var r = el("div", "row" + (cls ? " " + cls : ""));
+    r.appendChild(el("span", "lbl", label));
+    r.appendChild(content);
+    return r;
+  }
+  // The source line with the requirement marked in it, in the line's own words.
+  function markedLine(u) {
+    var p = el("p", "quote"), at = u.text.indexOf(u.mark);
+    p.appendChild(rich("span", "", u.text.slice(0, at)));
+    p.appendChild(rich("mark", "", u.mark));
+    p.appendChild(rich("span", "", u.text.slice(at + u.mark.length)));
+    return p;
+  }
+  // What a card shows above its question, one labelled row per field (an item and a practice item alike).
+  function evidence(card, item) {
+    if (item.title) card.appendChild(rich("h3", "", item.title));
+    card.appendChild(rich("p", "body", item.body));
+    if (item.code) card.appendChild(codeBlock(item.code));
+    if (item.unit) card.appendChild(row(item.unit.of > 1 ? "Line · part " + item.unit.part + " of " + item.unit.of : "Line",
+      markedLine(item.unit)));
+    // 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(row("Rule", rich("p", "", r.linter + " `" + r.id + "`" + (r.family ? " (" + r.family + ")" : "") +
+        ": " + r.description)));
+    });
+    if (item.readings) {
+      card.appendChild(row("Reading A", rich("p", "", item.readings.a), "reading a"));
+      card.appendChild(row("Reading B", rich("p", "", item.readings.b), "reading b"));
+    }
+    if (item.file) card.appendChild(row("File", rich("p", "", item.file)));
+    if (item.context) card.appendChild(rich("p", "muted", item.context));
+  }
   function labelOf(q, v) {
     var o = q.options.filter(function (x) { return x.value === v; })[0];
     return o ? o.label : v;
@@ -397,10 +426,7 @@ pre { overflow-x: auto; background: var(--surface); border: 1px solid var(--line
   function practiceCard(p, off) {
     var card = el("article", "item");
     card.appendChild(el("div", "id", "Practice " + p.id));
-    if (p.title) card.appendChild(rich("h3", "", p.title));
-    card.appendChild(rich("p", "body", p.body));
-    if (p.code) card.appendChild(codeBlock(p.code));
-    if (p.context) card.appendChild(rich("p", "muted", p.context));
+    evidence(card, p);
     var a = practiceAnswers(p.id);
     askOne(card, a, undefined, function (q, v) { answerPractice(p.id, q.id, v); }, null, off, true);
     if (practiceAnswered(p)) {

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

@@ -3,11 +3,13 @@
  * ("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".
+ * - ruff: `ruff rule <code> --output-format json`, the paragraph under "## What it does", and the
+ *   family it names (`linter`: flake8-print for T201).
  * - 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`).
+ *   `@scope/p/rule` → `@scope/eslint-plugin-p`, `p/rule` → `eslint-plugin-p`); the rule's own name
+ *   may hold a slash (`n/no-unsupported-features/node-builtins`).
  */
 import { spawnSync } from "node:child_process";
 import { createRequire } from "node:module";
@@ -17,15 +19,17 @@ 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. */
+const RuffRule = z.object({ explanation: z.string(), linter: z.string() });
+/** The paragraph under "## What it does", its lines joined, and the rule's family. */
 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 { explanation, linter } = 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();
+    return what === undefined
+        ? undefined
+        : { description: what.split("\n").join(" ").trim(), family: linter };
 }
 const RuleModule = z.object({
     meta: z.object({ docs: z.object({ description: z.string() }) }),
@@ -34,19 +38,22 @@ 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];
+/**
+ * The packages and rule names a namespaced ESLint rule id may point at, likeliest first. The rule's
+ * own name may hold a slash, so `@scope/a/b` is `a/b` of `@scope/eslint-plugin` or `b` of
+ * `@scope/eslint-plugin-a`; an unscoped id's plugin is everything before its first slash.
+ */
+function pluginsOf(id) {
+    const [first = "", second = "", ...rest] = id.split("/");
+    const after = (n) => id.split("/").slice(n).join("/");
+    return id.startsWith("@")
+        ? [
+            ...(rest.length
+                ? [[`${first}/eslint-plugin-${second}`, after(2)]]
+                : []),
+            [`${first}/eslint-plugin`, after(1)],
+        ]
+        : [[`eslint-plugin-${first}`, after(1)]];
 }
 // `require` of an ES-module plugin returns its namespace: the plugin object is then its `default`.
 const EsmPlugin = z.object({ default: Plugin });
@@ -56,23 +63,34 @@ const pluginRules = (mod) => {
 };
 const description = (rule) => {
     const r = RuleModule.safeParse(rule);
-    return r.success ? r.data.meta.docs.description : undefined;
+    return r.success ? { description: 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"));
+/** `load(pkg)`, or undefined when it is not installed where items.json is. */
+const tryLoad = (load, pkg) => {
     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]);
+        return load(pkg);
     }
     catch {
-        // ESLint or the plugin is not installed where items.json is: the linter cannot answer.
         return 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"));
+    if (!id.includes("/")) {
+        const core = tryLoad(load, "eslint/use-at-your-own-risk");
+        return core === undefined
+            ? undefined
+            : description(Builtins.parse(core).builtinRules.get(id));
+    }
+    return pluginsOf(id)
+        .map(([pkg, name]) => {
+        const mod = tryLoad(load, pkg);
+        return mod === undefined
+            ? undefined
+            : description(pluginRules(mod)[name]);
+    })
+        .find((d) => d !== undefined);
 }
 /** The linter's own one-line description of `ref`, or undefined when it has none. */
 export function describeRule(ref, fromDir, run = runProcess) {

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

@@ -31,38 +31,83 @@ const fakeRuff: RunProcess = (cmd, args) =>
     ? { 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(
+test("🔴 a ruff rule is described by its own 'What it does' paragraph, on one line, with the family ruff names", () => {
+  // Guards: the family (`linter` in ruff's JSON) is kept, not dropped (flake8-tidy-imports for TID253).
+  assert.deepEqual(
     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).",
+    {
+      description:
+        "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).",
+      family: "flake8-tidy-imports",
+    },
   );
 });
 
 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(
+  assert.deepEqual(
     describeRule({ linter: "eslint", id: "no-console" }, REPO, fakeRuff),
-    "Disallow the use of `console`",
+    { description: "Disallow the use of `console`" },
   );
-  assert.equal(
+  assert.deepEqual(
     describeRule(
       { linter: "eslint", id: "@typescript-eslint/no-explicit-any" },
       REPO,
       fakeRuff,
     ),
-    "Disallow the `any` type",
+    { description: "Disallow the `any` type" },
   );
 });
 
+test("🔴 a plugin rule whose own name holds a slash is found under its whole name", () => {
+  // Guards: `n/no-unsupported-features/node-builtins` is not cut to `node-builtins`.
+  assert.deepEqual(
+    describeRule(
+      { linter: "eslint", id: "n/no-unsupported-features/node-builtins" },
+      REPO,
+      fakeRuff,
+    ),
+    {
+      description:
+        "disallow unsupported Node.js built-in APIs on the specified version",
+    },
+  );
+});
+
+/** A folder whose own ESLint fails to load (the machine may have another ESLint on NODE_PATH). */
+function brokenEslint(): string {
+  const dir = realpathSync(mkdtempSync(join(tmpdir(), "no-eslint-")));
+  const pkg = join(dir, "node_modules", "eslint");
+  mkdirSync(pkg, { recursive: true });
+  writeFileSync(
+    join(pkg, "package.json"),
+    JSON.stringify({
+      name: "eslint",
+      exports: { "./use-at-your-own-risk": "./index.js" },
+    }),
+  );
+  writeFileSync(join(pkg, "index.js"), 'throw new Error("broken");\n');
+  return dir;
+}
+
 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),
+    // an ESLint that cannot be loaded where items.json is
+    describeRule(
+      { linter: "eslint", id: "no-console" },
+      brokenEslint(),
+      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" }),
+      stdout: JSON.stringify({
+        explanation: "## Why is this bad?\nx",
+        linter: "flake8-tidy-imports",
+      }),
     })),
   ];
   assert.deepEqual(none, [
@@ -71,6 +116,7 @@ test("a rule the linter does not know, or a plugin that is not installed has no
     undefined,
     undefined,
     undefined,
+    undefined,
   ]);
 });
 
@@ -85,13 +131,13 @@ test("the real process runner returns the exit status and what was printed (node
 });
 
 test("🔴 a relative folder (the documented `build items.json label-page`) is resolved before ESLint is looked up", () => {
-  assert.equal(
+  assert.deepEqual(
     describeRule(
       { linter: "eslint", id: "no-console" },
       relative(process.cwd(), REPO) || ".",
       fakeRuff,
     ),
-    "Disallow the use of `console`",
+    { description: "Disallow the use of `console`" },
   );
 });
 
@@ -111,8 +157,8 @@ test("🔴 an ES-module plugin whose rules sit under its default export is descr
     join(pkg, "index.js"),
     'export default { rules: { r: { meta: { docs: { description: "Only via default" } } } } };\n',
   );
-  assert.equal(
+  assert.deepEqual(
     describeRule({ linter: "eslint", id: "esmonly/r" }, dir, fakeRuff),
-    "Only via default",
+    { description: "Only via default" },
   );
 });

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

@@ -3,11 +3,13 @@
  * ("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".
+ * - ruff: `ruff rule <code> --output-format json`, the paragraph under "## What it does", and the
+ *   family it names (`linter`: flake8-print for T201).
  * - 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`).
+ *   `@scope/p/rule` → `@scope/eslint-plugin-p`, `p/rule` → `eslint-plugin-p`); the rule's own name
+ *   may hold a slash (`n/no-unsupported-features/node-builtins`).
  */
 import { spawnSync } from "node:child_process";
 import { createRequire } from "node:module";
@@ -18,6 +20,11 @@ export interface RuleRef {
   readonly linter: "eslint" | "ruff";
   readonly id: string;
 }
+/** What the linter says a rule does; a ruff rule also names the family it comes from. */
+export interface Described {
+  readonly description: string;
+  readonly family?: string;
+}
 /** A process run to its end: the exit status and what it printed. */
 export type RunProcess = (
   cmd: string,
@@ -29,14 +36,16 @@ export const runProcess: RunProcess = (cmd, args) => {
   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: string, run: RunProcess): string | undefined {
+const RuffRule = z.object({ explanation: z.string(), linter: z.string() });
+/** The paragraph under "## What it does", its lines joined, and the rule's family. */
+function ruffDescription(id: string, run: RunProcess): Described | undefined {
   const r = run("ruff", ["rule", id, "--output-format", "json"]);
   if (r.status !== 0) return undefined;
-  const { explanation } = RuffRule.parse(JSON.parse(r.stdout));
+  const { explanation, linter } = 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();
+  return what === undefined
+    ? undefined
+    : { description: what.split("\n").join(" ").trim(), family: linter };
 }
 
 const RuleModule = z.object({
@@ -46,19 +55,22 @@ 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: string): readonly [string, string] {
-  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];
+/**
+ * The packages and rule names a namespaced ESLint rule id may point at, likeliest first. The rule's
+ * own name may hold a slash, so `@scope/a/b` is `a/b` of `@scope/eslint-plugin` or `b` of
+ * `@scope/eslint-plugin-a`; an unscoped id's plugin is everything before its first slash.
+ */
+function pluginsOf(id: string): readonly (readonly [string, string])[] {
+  const [first = "", second = "", ...rest] = id.split("/");
+  const after = (n: number): string => id.split("/").slice(n).join("/");
+  return id.startsWith("@")
+    ? [
+        ...(rest.length
+          ? [[`${first}/eslint-plugin-${second}`, after(2)] as const]
+          : []),
+        [`${first}/eslint-plugin`, after(1)] as const,
+      ]
+    : [[`eslint-plugin-${first}`, after(1)] as const];
 }
 // `require` of an ES-module plugin returns its namespace: the plugin object is then its `default`.
 const EsmPlugin = z.object({ default: Plugin });
@@ -66,24 +78,35 @@ const pluginRules = (mod: unknown): Readonly<Record<string, unknown>> => {
   const esm = EsmPlugin.safeParse(mod);
   return esm.success ? esm.data.default.rules : Plugin.parse(mod).rules;
 };
-const description = (rule: unknown): string | undefined => {
+const description = (rule: unknown): Described | undefined => {
   const r = RuleModule.safeParse(rule);
-  return r.success ? r.data.meta.docs.description : undefined;
+  return r.success ? { description: r.data.meta.docs.description } : undefined;
 };
-function eslintDescription(id: string, fromDir: string): string | undefined {
-  // createRequire takes an absolute path only; items.json is often named relative to the study folder.
-  const load = createRequire(resolve(fromDir, "items.json"));
+/** `load(pkg)`, or undefined when it is not installed where items.json is. */
+const tryLoad = (load: NodeJS.Require, pkg: string): unknown => {
   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]);
+    return load(pkg);
   } catch {
-    // ESLint or the plugin is not installed where items.json is: the linter cannot answer.
     return undefined;
   }
+};
+function eslintDescription(id: string, fromDir: string): Described | undefined {
+  // createRequire takes an absolute path only; items.json is often named relative to the study folder.
+  const load = createRequire(resolve(fromDir, "items.json"));
+  if (!id.includes("/")) {
+    const core = tryLoad(load, "eslint/use-at-your-own-risk");
+    return core === undefined
+      ? undefined
+      : description(Builtins.parse(core).builtinRules.get(id));
+  }
+  return pluginsOf(id)
+    .map(([pkg, name]) => {
+      const mod = tryLoad(load, pkg);
+      return mod === undefined
+        ? undefined
+        : description(pluginRules(mod)[name]);
+    })
+    .find((d) => d !== undefined);
 }
 
 /** The linter's own one-line description of `ref`, or undefined when it has none. */
@@ -91,7 +114,7 @@ export function describeRule(
   ref: RuleRef,
   fromDir: string,
   run: RunProcess = runProcess,
-): string | undefined {
+): Described | undefined {
   return ref.linter === "ruff"
     ? ruffDescription(ref.id, run)
     : eslintDescription(ref.id, fromDir);