paperlint 13.4.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);
@@ -12,6 +13,7 @@ type Json = null | boolean | number | string | readonly Json[] | {
 type JsonObject = {
     readonly [key: string]: Json;
 };
+declare const PAGE_FIELDS: readonly ["group", "title", "body", "code", "context"];
 type SchemaNode = {
     kind: "string";
     required: boolean;
@@ -53,9 +55,20 @@ interface Question {
     readonly short?: string;
     readonly options: readonly Option[];
 }
-type Item = Readonly<Record<string, string>> & {
+interface Unit {
+    readonly id: string;
+    readonly text: string;
+    readonly part: number;
+    readonly of: number;
+}
+type Item = {
+    readonly [F in (typeof PAGE_FIELDS)[number]]?: string;
+} & {
     readonly source_id: string;
     readonly group: string;
+    readonly body: string;
+    readonly rules?: readonly RuleRef[];
+    readonly unit?: Unit;
 };
 interface Practice {
     readonly title?: string;
@@ -84,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[];
@@ -92,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: {
@@ -112,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>;
 /**
@@ -143,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.4.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,22 @@ 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`. 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
+  whole line beneath, so the labeller judges one requirement at a time and sees where it came from.
+  The build refuses a line whose parts do not add up (one missing, repeated, a different `of`, or
+  split across groups), naming the item. `id` names one occurrence of the line (a file and line
+  number, say) and is never shown: two files holding the same words are two lines, each judged in
+  full. Splitting the line is the study's job, before the page.
 - **`seed`**: fixes the order. Rebuilding with the same seed keeps every id, and a new item gets the
   next one; a different seed is refused once a key exists.
 - **`ask_why`** on an option: a prompt. That answer is incomplete, on the page and in the export,

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,7 +90,18 @@ 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"];
-const ALLOWED_FIELDS = [...PAGE_FIELDS, ...PRIVATE_FIELDS];
+// 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,
+];
 const FAMILIARITY = [
     { value: "well", label: "Well" },
     { value: "somewhat", label: "Somewhat" },
@@ -140,10 +152,14 @@ const mapping = (values, keyPattern, min = 0) => ({
     key_pattern: keyPattern,
     values,
 });
-const obj = (fields, closed = true) => ({ kind: "object", required: true, closed, fields });
+const obj = (fields, closed = true, required = true) => ({ kind: "object", required, closed, fields });
 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),
 }, false);
 // `icon` (an emoji) tells the buttons apart at a glance. No coloured side stripe on a button: it
 // reads as decoration, not meaning (the build-label-page look test refuses one).
@@ -356,7 +372,41 @@ function checkConfig(cfg) {
 }
 /** The practice as the page shows it and the key keeps it: neutral ids P1, P2 … in the given order. */
 const practiceOf = (cfg) => cfg.practice.map((item, n) => ({ id: `P${String(n + 1)}`, ...item }));
-// ── the items: the leak guard, and the references to the config ───────────────────────────────
+/** The items of each line, in items.json order; a line's list is never empty. */
+const linesOf = (cfg) => cfg.items.reduce((byLine, item, n) => {
+    if (item.unit === undefined)
+        return byLine;
+    const part = { item, unit: item.unit, n };
+    const seen = byLine.get(item.unit.id);
+    return byLine.set(item.unit.id, seen ? [seen[0], ...seen.slice(1), part] : [part]);
+}, new Map());
+/** One part against the first part of its line: same count, in range, not repeated, same group. */
+function checkPart({ item, unit, n }, parts) {
+    const [first] = parts;
+    const at = `items[${String(n)}]`;
+    if (unit.text !== first.unit.text)
+        fail(`${at}.unit.text: ${repr(unit.text)}, but items[${String(first.n)}] of line ${repr(unit.id)} says ${repr(first.unit.text)}`);
+    if (unit.of !== first.unit.of)
+        fail(`${at}.unit.of: ${String(unit.of)}, but items[${String(first.n)}].unit.of says ${String(first.unit.of)} for the same line`);
+    if (unit.part < 1 || unit.part > unit.of)
+        fail(`${at}.unit.part: ${String(unit.part)} is not between 1 and ${String(unit.of)}`);
+    const earlier = parts.find((p) => p.n < n && p.unit.part === unit.part);
+    if (earlier !== undefined)
+        fail(`${at}.unit.part: ${String(unit.part)} repeats items[${String(earlier.n)}].unit.part`);
+    if (item.group !== first.item.group)
+        fail(`${at}.group: ${repr(item.group)}, but items[${String(first.n)}] of the same line is in ${repr(first.item.group)}`);
+}
+function checkUnits(cfg) {
+    for (const [line, parts] of linesOf(cfg)) {
+        parts.forEach((p) => {
+            checkPart(p, parts);
+        });
+        const [first] = parts;
+        const missing = Array.from({ length: first.unit.of }, (_, k) => k + 1).find((k) => !parts.some((p) => p.unit.part === k));
+        if (missing !== undefined)
+            fail(`items[${String(first.n)}].unit: part ${String(missing)} of ${String(first.unit.of)} of line ${repr(line)} is not among the items`);
+    }
+}
 function checkItemFields(cfg) {
     const sids = [];
     cfg.items.forEach((item, n) => {
@@ -373,6 +423,11 @@ function checkItemFields(cfg) {
             fail(`items[${String(n)}].group: ${repr(item.group)} is not in \`groups\``);
     });
 }
+/** Every text of an item the labeller sees, by field: the page fields and the line of a unit. */
+const visibleTexts = (item) => [
+    ...PAGE_FIELDS.map((f) => [f, item[f] ?? ""]),
+    [UNIT_FIELD, item.unit?.text ?? ""],
+];
 const escapeRegExp = (s) => s.replace(/[\\^$.*+?()[\]{}|/]/g, "\\$&");
 /**
  * A source id typed into a visible field gives the source away as well as a field would. Short ids
@@ -385,7 +440,7 @@ function checkNoSourceShown(cfg) {
     for (const item of cfg.items) {
         for (const sid of long) {
             const word = new RegExp(`(?<![\\p{L}\\p{N}_-])${escapeRegExp(sid)}(?![\\p{L}\\p{N}_-])`, "u");
-            const field = PAGE_FIELDS.find((f) => word.test(item[f] ?? ""));
+            const field = visibleTexts(item).find(([, text]) => word.test(text))?.[0];
             if (field !== undefined) {
                 fail(`the source id ${repr(sid)} appears in the visible \`${field}\` of item ${item.source_id}. Take it out of the text (or use source ids that are not natural words).`);
             }
@@ -426,11 +481,40 @@ function assignIds(items, seed, keyPath) {
     ]);
     return { ids, entries };
 }
-// ── a build, short of the page ──────────────────────────────────────────────────────────────────
-const shownFields = (item) => Object.fromEntries(PAGE_FIELDS.flatMap((f) => {
-    const v = item[f];
-    return v === undefined ? [] : [[f, v]];
-}));
+const shownFields = (item) => ({
+    ...Object.fromEntries(PAGE_FIELDS.flatMap((f) => {
+        const v = item[f];
+        return v === undefined ? [] : [[f, v]];
+    })),
+    ...(item.unit === undefined
+        ? {}
+        : {
+            [UNIT_FIELD]: {
+                text: item.unit.text,
+                part: item.unit.part,
+                of: item.unit.of,
+            },
+        }),
+});
+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;
@@ -445,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,
@@ -458,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. */
@@ -524,14 +612,16 @@ export function prepareBuild(configPath, outDir) {
     assertConfig(cfg);
     checkConfig(cfg);
     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

@@ -81,7 +81,16 @@ const FULL: DocObject = (() => {
       familiarity: true,
       familiarity_question: "How well do you know {group}?",
       items: ITEMS.map((i, n) =>
-        n === 0 ? { ...i, title: "T", code: "c = 1", context: "ctx" } : i,
+        n === 0
+          ? {
+              ...i,
+              title: "T",
+              code: "c = 1",
+              context: "ctx",
+              rules: [{ linter: "eslint", id: "no-console" }],
+              unit: { id: "L0", text: "One line.", part: 1, of: 1 },
+            }
+          : i,
       ),
     }),
   );
@@ -1167,6 +1176,43 @@ 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);
@@ -1225,3 +1271,135 @@ test("familiarity left out: every group is still asked (rule 5), and a missing o
   );
   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 = (
+  parts: readonly (readonly [n: number, unit: Record<string, unknown>])[],
+): Record<string, unknown> =>
+  config({
+    items: ITEMS.map((item, n) => {
+      const u = parts.find(([at]) => at === n);
+      return u === undefined ? item : { ...item, unit: u[1] };
+    }),
+  });
+
+/** A line whose parts do not add up, and the refusal that names it. */
+const UNIT_REFUSALS: readonly (readonly [
+  string,
+  Record<string, unknown>,
+  string,
+])[] = [
+  [
+    "unit-missing-part",
+    withUnit([[0, { id: "L1", text: LINE, part: 1, of: 2 }]]),
+    `items[0].unit: part 2 of 2 of line 'L1' is not among the items`,
+  ],
+  [
+    "unit-part-twice",
+    withUnit([
+      [0, { id: "L1", text: LINE, part: 1, of: 2 }],
+      [3, { id: "L1", text: LINE, part: 1, of: 2 }],
+    ]),
+    "items[3].unit.part: 1 repeats items[0].unit.part",
+  ],
+  [
+    "unit-of-differs",
+    withUnit([
+      [0, { id: "L1", text: LINE, part: 1, of: 2 }],
+      [3, { id: "L1", text: LINE, part: 2, of: 3 }],
+    ]),
+    "items[3].unit.of: 3, but items[0].unit.of says 2 for the same line",
+  ],
+  [
+    "unit-part-range",
+    withUnit([[0, { id: "L1", text: LINE, part: 3, of: 2 }]]),
+    "items[0].unit.part: 3 is not between 1 and 2",
+  ],
+  [
+    "unit-groups-differ",
+    withUnit([
+      [0, { id: "L1", text: LINE, part: 1, of: 2 }],
+      [1, { id: "L1", text: LINE, part: 2, of: 2 }],
+    ]),
+    "items[1].group: 'python', but items[0] of the same line is in 'rust'",
+  ],
+  [
+    "unit-text-differs",
+    withUnit([
+      [0, { id: "L1", text: LINE, part: 1, of: 2 }],
+      [3, { id: "L1", text: "Another line.", part: 2, of: 2 }],
+    ]),
+    "items[3].unit.text: 'Another line.', but items[0] of line 'L1' says",
+  ],
+  [
+    "unit-halves-of-two-occurrences",
+    withUnit([
+      [0, { id: "L1", text: LINE, part: 1, of: 2 }],
+      [3, { id: "L2", text: LINE, part: 2, of: 2 }],
+    ]),
+    "items[0].unit: part 2 of 2 of line 'L1' is not among the items",
+  ],
+  [
+    "unit-leaks-source",
+    withUnit([[0, { id: "L1", text: "as in case-1003", part: 1, of: 1 }]]),
+    "the source id 'case-1003' appears in the visible `unit` of item case-1000",
+  ],
+];
+
+test("🔴 a line with several requirements: build refuses a unit whose parts do not add up, naming the item", () => {
+  for (const [name, cfg, message] of UNIT_REFUSALS) {
+    const dir = setup(name, cfg);
+    const r = run(["build", join(dir, "items.json"), join(dir, "out")]);
+    assert.equal(r.status, 1, `${name}\n${r.out}`);
+    assert.ok(r.out.includes(`REFUSED: ${message}`), `${name}\n${r.out}`);
+  }
+});
+
+test("a line whose every requirement is an item builds, and each item carries its part and the whole line", () => {
+  const dir = setup(
+    "unit-ok",
+    withUnit([
+      [0, { id: "L1", text: LINE, part: 1, of: 2 }],
+      [3, { id: "L1", text: LINE, part: 2, of: 2 }],
+    ]),
+  );
+  const { page } = build(dir);
+  const json =
+    /<script type="application\/json" id="data">([\s\S]*?)<\/script>/.exec(
+      page,
+    )?.[1];
+  assert.ok(json !== undefined);
+  const units = z
+    .object({
+      items: z.array(
+        z.object({
+          unit: z
+            .object({ text: z.string(), part: z.number(), of: z.number() })
+            .optional(),
+        }),
+      ),
+    })
+    .parse(JSON.parse(json.replace(/<\\\//g, "</")))
+    .items.flatMap((i) => (i.unit ? [i.unit] : []))
+    .sort((a, b) => a.part - b.part);
+  // what the page carries: the part and the line, never the line's private id
+  assert.deepEqual(units, [
+    { text: LINE, part: 1, of: 2 },
+    { text: LINE, part: 2, of: 2 },
+  ]);
+});
+
+test("🔴 the same line in two places is two lines: four items, two ids, it builds, and the id stays off the page", () => {
+  const dir = setup(
+    "unit-same-text",
+    withUnit([
+      [0, { id: "a.md:3", text: LINE, part: 1, of: 2 }],
+      [3, { id: "a.md:3", text: LINE, part: 2, of: 2 }],
+      [6, { id: "b.md:9", text: LINE, part: 1, of: 2 }],
+      [9, { id: "b.md:9", text: LINE, part: 2, of: 2 }],
+    ]),
+  );
+  const { page } = build(dir);
+  assert.ok(!page.includes("a.md:3"), "the line's id is private");
+});

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,7 +95,18 @@ 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;
-const ALLOWED_FIELDS: readonly string[] = [...PAGE_FIELDS, ...PRIVATE_FIELDS];
+// 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,
+];
 
 const FAMILIARITY = [
   { value: "well", label: "Well" },
@@ -180,7 +192,8 @@ const mapping = (
 const obj = (
   fields: Readonly<Record<string, SchemaNode>>,
   closed = true,
-): SchemaNode => ({ kind: "object", required: true, closed, fields });
+  required = true,
+): SchemaNode => ({ kind: "object", required, closed, fields });
 
 const ITEM_SCHEMA = obj(
   {
@@ -188,6 +201,17 @@ 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() },
+      true,
+      false,
+    ),
   },
   false, // an unlisted item field is the leak guard's refusal, with its own message
 );
@@ -348,9 +372,20 @@ interface Question {
   readonly short?: string;
   readonly options: readonly Option[];
 }
-type Item = Readonly<Record<string, string>> & {
+interface Unit {
+  readonly id: string;
+  readonly text: string;
+  readonly part: number;
+  readonly of: number;
+}
+type Item = {
+  readonly [F in (typeof PAGE_FIELDS)[number]]?: string;
+} & {
   readonly source_id: string;
   readonly group: string;
+  readonly body: string;
+  readonly rules?: readonly RuleRef[];
+  readonly unit?: Unit;
 };
 interface Practice {
   readonly title?: string;
@@ -507,6 +542,69 @@ const practiceOf = (
   cfg.practice.map((item, n) => ({ id: `P${String(n + 1)}`, ...item }));
 
 // ── the items: the leak guard, and the references to the config ───────────────────────────────
+/**
+ * A line with several requirements is split upstream into one item per requirement, each carrying
+ * `unit: {text, part, of}`. Every part of a line must be an item, once, in one group (so
+ * `labeller_knows` keeps or drops the whole line): a lost part is a requirement nobody judged.
+ */
+interface Part {
+  readonly item: Item;
+  readonly unit: Unit;
+  readonly n: number;
+}
+type Parts = readonly [Part, ...Part[]];
+/** The items of each line, in items.json order; a line's list is never empty. */
+const linesOf = (cfg: Config): ReadonlyMap<string, Parts> =>
+  cfg.items.reduce((byLine, item, n) => {
+    if (item.unit === undefined) return byLine;
+    const part: Part = { item, unit: item.unit, n };
+    const seen = byLine.get(item.unit.id);
+    return byLine.set(
+      item.unit.id,
+      seen ? [seen[0], ...seen.slice(1), part] : [part],
+    );
+  }, new Map<string, Parts>());
+/** One part against the first part of its line: same count, in range, not repeated, same group. */
+function checkPart({ item, unit, n }: Part, parts: Parts): void {
+  const [first] = parts;
+  const at = `items[${String(n)}]`;
+  if (unit.text !== first.unit.text)
+    fail(
+      `${at}.unit.text: ${repr(unit.text)}, but items[${String(first.n)}] of line ${repr(unit.id)} says ${repr(first.unit.text)}`,
+    );
+  if (unit.of !== first.unit.of)
+    fail(
+      `${at}.unit.of: ${String(unit.of)}, but items[${String(first.n)}].unit.of says ${String(first.unit.of)} for the same line`,
+    );
+  if (unit.part < 1 || unit.part > unit.of)
+    fail(
+      `${at}.unit.part: ${String(unit.part)} is not between 1 and ${String(unit.of)}`,
+    );
+  const earlier = parts.find((p) => p.n < n && p.unit.part === unit.part);
+  if (earlier !== undefined)
+    fail(
+      `${at}.unit.part: ${String(unit.part)} repeats items[${String(earlier.n)}].unit.part`,
+    );
+  if (item.group !== first.item.group)
+    fail(
+      `${at}.group: ${repr(item.group)}, but items[${String(first.n)}] of the same line is in ${repr(first.item.group)}`,
+    );
+}
+function checkUnits(cfg: Config): void {
+  for (const [line, parts] of linesOf(cfg)) {
+    parts.forEach((p) => {
+      checkPart(p, parts);
+    });
+    const [first] = parts;
+    const missing = Array.from({ length: first.unit.of }, (_, k) => k + 1).find(
+      (k) => !parts.some((p) => p.unit.part === k),
+    );
+    if (missing !== undefined)
+      fail(
+        `items[${String(first.n)}].unit: part ${String(missing)} of ${String(first.unit.of)} of line ${repr(line)} is not among the items`,
+      );
+  }
+}
 function checkItemFields(cfg: Config): void {
   const sids: string[] = [];
   cfg.items.forEach((item, n) => {
@@ -529,6 +627,11 @@ function checkItemFields(cfg: Config): void {
       );
   });
 }
+/** Every text of an item the labeller sees, by field: the page fields and the line of a unit. */
+const visibleTexts = (item: Item): readonly (readonly [string, string])[] => [
+  ...PAGE_FIELDS.map((f): readonly [string, string] => [f, item[f] ?? ""]),
+  [UNIT_FIELD, item.unit?.text ?? ""],
+];
 const escapeRegExp = (s: string): string =>
   s.replace(/[\\^$.*+?()[\]{}|/]/g, "\\$&");
 /**
@@ -545,7 +648,7 @@ function checkNoSourceShown(cfg: Config): void {
         `(?<![\\p{L}\\p{N}_-])${escapeRegExp(sid)}(?![\\p{L}\\p{N}_-])`,
         "u",
       );
-      const field = PAGE_FIELDS.find((f) => word.test(item[f] ?? ""));
+      const field = visibleTexts(item).find(([, text]) => word.test(text))?.[0];
       if (field !== undefined) {
         fail(
           `the source id ${repr(sid)} appears in the visible \`${field}\` of item ${item.source_id}. Take it out of the text (or use source ids that are not natural words).`,
@@ -612,13 +715,55 @@ function assignIds(
 }
 
 // ── a build, short of the page ──────────────────────────────────────────────────────────────────
-const shownFields = (item: Item): Readonly<Record<string, string>> =>
-  Object.fromEntries(
+/** A unit as the page shows it: the part and the line, without the line's private id. */
+type ShownUnit = Omit<Unit, "id">;
+const shownFields = (
+  item: Item,
+): Readonly<Record<string, string | ShownUnit>> => ({
+  ...Object.fromEntries(
     PAGE_FIELDS.flatMap((f) => {
       const v = item[f];
       return v === undefined ? [] : [[f, v]];
     }),
+  ),
+  ...(item.unit === undefined
+    ? {}
+    : {
+        [UNIT_FIELD]: {
+          text: item.unit.text,
+          part: item.unit.part,
+          of: item.unit.of,
+        },
+      }),
+});
+/** 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) {
@@ -636,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),
   );
@@ -651,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>;
@@ -729,14 +882,16 @@ export function prepareBuild(configPath: string, outDir: string) {
   assertConfig(cfg);
   checkConfig(cfg);
   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,6 +412,32 @@ 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("🔴 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(
+      "rules-card",
+      config({
+        items: ITEMS.map((item, n) =>
+          n === 0
+            ? { ...item, rules: [{ linter: "eslint", id: "no-console" }] }
+            : item,
+        ),
+      }),
+    ),
+  );
+  const shown = await showPage(page, {}, {});
+  assert.match(
+    shown,
+    /Rule eslint no-console: Disallow the use of \nconsole\n/,
+    shown,
+  );
+  assert.equal(
+    occurrences(shown, "Rule eslint"),
+    1,
+    "only the item that names it",
+  );
+});
+
 test("🔴 familiarity off: no group asks how well it is known, and a group is done when its items are", async () => {
   const { page, key } = build(
     setup("familiarity-off-page", approval({ familiarity: false })),
@@ -433,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

@@ -53,7 +53,14 @@
  *     "practice": [{"body": "…", "expected": {"label": "yes"}, "why": "one line"}, …],   3 or more
  *     "practice_round": 1,                  optional; raise it after rewording, the practice reopens
  *     "items": [{"source_id": "case-0412-b", "group": "python", "body": "…", "code": "…",
- *                "context": "…"}]
+ *                "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.
  *   }
  *
  * 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

@@ -53,7 +53,14 @@
  *     "practice": [{"body": "…", "expected": {"label": "yes"}, "why": "one line"}, …],   3 or more
  *     "practice_round": 1,                  optional; raise it after rewording, the practice reopens
  *     "items": [{"source_id": "case-0412-b", "group": "python", "body": "…", "code": "…",
- *                "context": "…"}]
+ *                "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.
  *   }
  *
  * 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

@@ -312,6 +312,15 @@ 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 + "):"));
+      card.appendChild(rich("p", "quote", item.unit.text));
+    }
     var a = answersOf(item.id);
     askOne(card, a, state.editing[item.id], function (q, v) {
       delete state.editing[item.id];

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);
+}