paperlint 13.5.0 → 13.6.0

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

@@ -1,3 +1,4 @@
+import { type RuleRef } from "./rule-descriptions.ts";
 export declare class Refusal extends Error {
     readonly exitCode: number;
     constructor(exitCode: number, message: string);
@@ -66,6 +67,7 @@ type Item = {
     readonly source_id: string;
     readonly group: string;
     readonly body: string;
+    readonly rules?: readonly RuleRef[];
     readonly unit?: Unit;
 };
 interface Practice {
@@ -95,6 +97,8 @@ interface KeyEntry {
     readonly group: string;
     readonly on_page: boolean;
 }
+/** Rule → the linter's description, for every rule an item on the page names. */
+type Described = ReadonlyMap<string, string>;
 /** Only what the labeller can answer goes on the page, and only that gets an id, in id order. */
 declare function itemsOnPage(cfg: Config, keyPath: string): {
     items: Item[];
@@ -103,7 +107,7 @@ declare function itemsOnPage(cfg: Config, keyPath: string): {
     idOf: (i: Item) => string;
 };
 /** What a page shows: the questions, the practice and the items, blind, with their neutral ids. */
-declare function payloadOf(cfg: Config, page: ReturnType<typeof itemsOnPage>): {
+declare function payloadOf(cfg: Config, page: ReturnType<typeof itemsOnPage>, described: Described): {
     title: string;
     intro: string;
     groups: {
@@ -123,9 +127,17 @@ declare function payloadOf(cfg: Config, page: ReturnType<typeof itemsOnPage>): {
             readonly id: string;
         })[];
     };
-    items: {
+    items: ({
+        rules?: never;
         id: string;
-    }[];
+    } | {
+        rules: {
+            linter: "eslint" | "ruff";
+            id: string;
+            description: string;
+        }[];
+        id: string;
+    })[];
 };
 export type Payload = ReturnType<typeof payloadOf>;
 /**
@@ -154,9 +166,17 @@ export declare function prepareBuild(configPath: string, outDir: string): {
                 readonly id: string;
             })[];
         };
-        items: {
+        items: ({
+            rules?: never;
             id: string;
-        }[];
+        } | {
+            rules: {
+                linter: "eslint" | "ruff";
+                id: string;
+                description: string;
+            }[];
+            id: string;
+        })[];
     };
     dropped: number;
 };

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

@@ -0,0 +1,12 @@
+export interface RuleRef {
+    readonly linter: "eslint" | "ruff";
+    readonly id: string;
+}
+/** A process run to its end: the exit status and what it printed. */
+export type RunProcess = (cmd: string, args: readonly string[]) => {
+    readonly status: number | null;
+    readonly stdout: string;
+};
+export declare const runProcess: RunProcess;
+/** The linter's own one-line description of `ref`, or undefined when it has none. */
+export declare function describeRule(ref: RuleRef, fromDir: string, run?: RunProcess): string | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paperlint",
-  "version": "13.5.0",
+  "version": "13.6.0",
   "description": "A linter for scientific papers written in LaTeX: catches mistakes before you submit to a conference or journal.",
   "type": "module",
   "license": "MIT",

package/skills/build-label-page/references/closed-choice-generator.md

@@ -37,8 +37,14 @@ length.
 - **`practice_round`**: raise it after rewording a question; the practice reopens and the answers of
   the earlier round are kept but not counted.
 - **`items`**: `source_id` (the study's own, never shown), `group`, `body`, and optionally `title`,
-  `code`, `context`, `unit`. Nothing else: the allow-list is fixed in the generator, and a field outside it
+  `code`, `context`, `rules`, `unit`. Nothing else: the allow-list is fixed in the generator, and a field outside it
   is taken out of the item, not added to the list to make a build pass.
+- **`rules`**: `[{linter, id}]` (`linter` is `eslint` or `ruff`) on an item read as a linter rule.
+  The card shows "Rule ruff TID253: Checks for module-level imports that should instead be imported
+  lazily…", the description taken at build time from the linter itself: `ruff rule <id>`'s "What it
+  does" paragraph, or the ESLint rule's `meta.docs.description` from the ESLint and plugins
+  installed where `items.json` is. The build refuses a rule the linter cannot describe; a
+  description is never typed into `items.json`.
 - **`unit`**: `{id, text, part, of}` on an item that is one requirement of a line holding several
   ("TypeScript only (no JavaScript); top-level await is allowed" is two). Each requirement is its
   own item with its own question, and its card shows "From the line (requirement 1 of 2):" and the

package/skills/build-label-page/scripts/fixtures/ruff-rule-TID253.json

@@ -0,0 +1,23 @@
+{
+  "name": "banned-module-level-imports",
+  "code": "TID253",
+  "linter": "flake8-tidy-imports",
+  "summary": "`{name}` is banned at the module level",
+  "message_formats": [
+    "`{name}` is banned at the module level"
+  ],
+  "fix": "Fix is not available.",
+  "fix_availability": "None",
+  "explanation": "## What it does\nChecks for module-level imports that should instead be imported lazily\n(e.g., within a function definition, or an `if TYPE_CHECKING:` block, or\nsome other nested context).\n\n## Why is this bad?\nSome modules are expensive to import. For example, importing `torch` or\n`tensorflow` can introduce a noticeable delay in the startup time of a\nPython program.\n\nIn such cases, you may want to enforce that the module is imported lazily\nas needed, rather than at the top of the file. This could involve inlining\nthe import into the function that uses it, rather than importing it\nunconditionally, to ensure that the module is only imported when necessary.\n\n## Example\n```python\nimport tensorflow as tf\n\n\ndef show_version():\n    print(tf.__version__)\n```\n\nUse instead:\n```python\ndef show_version():\n    import tensorflow as tf\n\n    print(tf.__version__)\n```\n\n## Options\n- `lint.flake8-tidy-imports.banned-module-level-imports`\n",
+  "preview": false,
+  "status": {
+    "Stable": {
+      "since": "v0.0.285"
+    }
+  },
+  "category": "restriction",
+  "source_location": {
+    "file": "crates/ruff_linter/src/rules/flake8_tidy_imports/rules/banned_module_level_imports.rs",
+    "line": 46
+  }
+}

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

@@ -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 } from "./rule-descriptions.js";
 // ── refusals and output ───────────────────────────────────────────────────────────────────────
 export class Refusal extends Error {
     exitCode;
@@ -89,11 +90,15 @@ const readJson = (path) => {
 // 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"];
 const PRIVATE_FIELDS = ["source_id"];
+// 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 = [
     ...PAGE_FIELDS,
+    RULES_FIELD,
     UNIT_FIELD,
     ...PRIVATE_FIELDS,
 ];
@@ -151,6 +156,7 @@ const obj = (fields, closed = true, required = true) => ({ kind: "object", requi
 const ITEM_SCHEMA = obj({
     source_id: string(),
     ...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() }, true, false),
@@ -490,6 +496,25 @@ const shownFields = (item) => ({
             },
         }),
 });
+const ruleKey = (r) => `${r.linter} ${r.id}`;
+/** Ask the linter for every rule named; refuse, by path, a rule it cannot describe. */
+function describeRules(cfg, fromDir) {
+    return new Map(cfg.items.flatMap((item, n) => (item.rules ?? []).map((r, k) => {
+        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, 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, keyPath) {
     const knows = cfg.labeller_knows;
@@ -504,7 +529,7 @@ function itemsOnPage(cfg, keyPath) {
 }
 const practiceRound = (cfg) => cfg.practice_round ?? 1;
 /** What a page shows: the questions, the practice and the items, blind, with their neutral ids. */
-function payloadOf(cfg, page) {
+function payloadOf(cfg, page, described) {
     const used = Object.keys(cfg.groups).filter((g) => page.items.some((i) => i.group === g));
     return {
         title: cfg.title,
@@ -517,7 +542,11 @@ function payloadOf(cfg, page) {
         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),
+        })),
     };
 }
 /** Every id the key keeps (on the page now, or kept from an earlier build), with its source and group. */
@@ -585,13 +614,14 @@ export function prepareBuild(configPath, outDir) {
     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-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",
+  );
+});

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

@@ -0,0 +1,98 @@
+/**
+ * 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 interface RuleRef {
+  readonly linter: "eslint" | "ruff";
+  readonly id: string;
+}
+/** A process run to its end: the exit status and what it printed. */
+export type RunProcess = (
+  cmd: string,
+  args: readonly string[],
+) => { readonly status: number | null; readonly stdout: string };
+
+export const runProcess: 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: string, run: RunProcess): string | 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 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: 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];
+}
+// `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: 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 r = RuleModule.safeParse(rule);
+  return r.success ? 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"));
+  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: RuleRef,
+  fromDir: string,
+  run: RunProcess = runProcess,
+): string | undefined {
+  return ref.linter === "ruff"
+    ? ruffDescription(ref.id, run)
+    : eslintDescription(ref.id, fromDir);
+}