paperlint 13.5.0 → 13.6.1

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.1",
   "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/assess-novelty/scripts/check_novelty.py

@@ -10,7 +10,9 @@ The verdict is computed from the cells, never stored, over neighbours read in fu
   result · ⚪ a piece nobody has excluded yet could still complete a neighbour (an unread cell, or an
   abstract-only read).
 Errors: a 'yes' cell without a quote or with a quote not in the text · a 'no' cell on an abstract-only
-neighbour · a missing search source · a priority sentence in paper.tex (first / none of the studies /
+neighbour · a missing search source · a 🟢 claim that some source has no search covering (a `searched`
+entry covers the claims its "claims" names, or, without "claims", the claims "added" on or before its date:
+novelty_search.py) · a priority sentence in paper.tex (first / none of the studies /
 to our knowledge / ...) not mapped to a 🟢 claim · CLAIMS.md disagreeing with the computed verdict ·
 a 🟢 claim without a refutation file · a claim without a known type or an objection_answer · a saved text
 with more than 30 % glued lines (two page columns merged by `pdftotext -layout`).
@@ -32,11 +34,12 @@ from quote_match import found, letters, norm  # noqa: E402
 from novelty_coverage import coverage_errors  # noqa: E402
 import novelty_candidates  # noqa: E402
 import novelty_cells  # noqa: E402
+import novelty_search  # noqa: E402
+from novelty_search import SOURCES  # noqa: E402
 
 # Boldness of a ledger status; ⚪ is not on the scale (unchecked is neither more nor less cautious).
 BOLDNESS = {"🟢": 2, "🟡": 1, "🔴": 0}
 FILE_NAME = re.compile(r"[\w./-]+\.(?:md|txt|json|tex|tsv|csv|py|ts|mjs)\b")
-SOURCES = ("venue-pc", "prev-edition", "arxiv-recent")
 TYPES = {"new-object", "transfer", "installed-base", "instrument", "refutation", "replication"}
 # The result itself: what is examined and what number comes out. A neighbour with both already reported the
 # result, so the claim's delta over it is setting (population, comparator, instrument): 🟡 at best, never 🟢,
@@ -158,6 +161,7 @@ def main():
 
     have = {s.get("source") for s in data.get("searched", []) if (s.get("how") or "").strip()}
     errors += [f"searched: no '{s}' search recorded (source + how)" for s in SOURCES if s not in have]
+    errors += novelty_search.entry_errors(data.get("searched", []))
 
     neighbours = data.get("neighbours", [])
     texts = {}
@@ -228,6 +232,7 @@ def main():
                 errors.append(f"{cid}: 🟢 without a refutation pass (refutation.file)")
             elif not os.path.isfile(os.path.join(paper, ref["file"])):
                 errors.append(f"{cid}: refutation file {ref['file']} does not exist")
+        errors += novelty_search.claim_errors(c, data.get("searched", []), v)
         print(f"{cid}  {v}  {why}")
         print(table(c, neighbours))
 

package/skills/assess-novelty/scripts/check_novelty_search.test.ts

@@ -0,0 +1,279 @@
+/**
+ * check_novelty.py, the search behind a 🟢: for each of the three sources (venue-pc, prev-edition, arxiv-recent) a
+ * free verdict needs a `searched` entry that covers THAT claim. Execution tier: the novelty fixture on disk, no
+ * model, no network. Run: npx vitest run skills/assess-novelty/scripts/check_novelty_search.test.ts
+ *
+ * Why (paperlint#367): three planned claims added to a table on 2026-11-04, whose searches were dated 2026-10-27
+ * and 2026-11-03, came out 🟢 against 30 neighbours collected for other claims; four works the consumer's own
+ * ledger names for one of them were not neighbours at all. `searched` was one list for the whole table, and the
+ * checker asked only for a refutation file.
+ *
+ * An entry covers a claim when its "claims" names it; an entry without "claims" (a table-wide search, as every
+ * table had before) covers a claim whose "added" date is on or before the entry's date.
+ * Each case copies the fixture and makes ONE change; every failing class has a clean twin that passes.
+ */
+import {
+  cpSync,
+  mkdtempSync,
+  readFileSync,
+  realpathSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { spawnSync } from "node:child_process";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import assert from "node:assert/strict";
+import { test } from "vitest";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const FIXTURE = join(here, "fixtures", "novelty");
+const CHECKER = join(here, "check_novelty.py");
+const SOURCES = ["venue-pc", "prev-edition", "arxiv-recent"];
+
+// Copy the fixture, let `change` edit the novelty table, run the checker: the exit code, the printed verdict
+// lines and every ERROR line, so a case can compare the whole list of errors.
+const run = (change: (json: any) => void) => {
+  const dir = realpathSync(mkdtempSync(join(tmpdir(), "novelty-search-")));
+  try {
+    cpSync(FIXTURE, dir, { recursive: true });
+    const path = join(dir, "siblings", "novelty.json");
+    const json = JSON.parse(readFileSync(path, "utf8"));
+    change(json);
+    writeFileSync(path, JSON.stringify(json, null, 2));
+    const r = spawnSync("python3", ["-I", CHECKER, dir], { encoding: "utf8" });
+    const errors = r.stderr
+      .split("\n")
+      .filter((l) => l.startsWith("ERROR "))
+      .map((l) => l.slice("ERROR ".length));
+    return { code: r.status, out: r.stdout, errors };
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+};
+const claim = (j: any, id: string) => j.claims.find((c: any) => c.id === id);
+const entry = (source: string, date: string, claims?: string[]) => ({
+  source,
+  how: `${source}: the search, as run`,
+  date,
+  ...(claims ? { claims } : {}),
+});
+// The searches as every table had them before: one list, no "claims"; the issue's two dates.
+const legacy = (j: any) => {
+  j.searched = [
+    entry("venue-pc", "2026-10-27"),
+    entry("prev-edition", "2026-10-27"),
+    entry("arxiv-recent", "2026-11-03"),
+  ];
+};
+// A design-stage claim added after the last search, with P5-1's cells (🟢) and a refutation file.
+const addC8 = (j: any, added?: string) => {
+  const c8 = { ...structuredClone(claim(j, "P5-1")), id: "C8", planned: true };
+  delete c8.ledger;
+  delete c8.added;
+  j.claims.push(added ? { ...c8, added } : c8);
+};
+const missingC8 = (sources: string, hint: string) =>
+  `C8: 🟢 but no search covers it in ${sources}: search for C8 there and record it with "claims": ["C8"]${hint}`;
+const AFTER = (added: string) =>
+  ` (a search without "claims" covers only the claims added on or before its date; C8 was added ${added})`;
+const NO_ADDED =
+  ' (or set "added" to the day C8 entered the table: a search without "claims" covers only the claims added on or before its date)';
+
+test("check_novelty_search: a claim added after the table's searches", () => {
+  // fires: the issue's case — a claim added 2026-11-04, searches of 2026-10-27 and 2026-11-03, no "claims"
+  {
+    const r = run((j) => {
+      legacy(j);
+      for (const c of j.claims) c.added = "2026-10-08";
+      addC8(j, "2026-11-04");
+    });
+    // Guards: C8 computes 🟢 (the table prints it), yet the run fails, naming C8, all three sources and the fix.
+    assert.match(r.out, /C8\s+🟢/);
+    assert.deepEqual(
+      { code: r.code, errors: r.errors },
+      {
+        code: 1,
+        errors: [missingC8(SOURCES.join(", "), AFTER("2026-11-04"))],
+      },
+    );
+  }
+  // fires: the same claim with no "added" at all — the error names both fixes
+  {
+    const r = run((j) => {
+      legacy(j);
+      for (const c of j.claims) c.added = "2026-10-08";
+      addC8(j);
+    });
+    // Guards: a claim with no date is not assumed to predate the searches.
+    assert.deepEqual(
+      { code: r.code, errors: r.errors },
+      { code: 1, errors: [missingC8(SOURCES.join(", "), NO_ADDED)] },
+    );
+  }
+  // silent: the delta search recorded for C8 in each source
+  {
+    const r = run((j) => {
+      legacy(j);
+      for (const c of j.claims) c.added = "2026-10-08";
+      addC8(j, "2026-11-04");
+      j.searched.push(...SOURCES.map((s) => entry(s, "2026-11-04", ["C8"])));
+    });
+    // Guards: the per-claim search is what lets a 🟢 through.
+    assert.deepEqual(
+      { code: r.code, errors: r.errors },
+      { code: 0, errors: [] },
+    );
+  }
+}, 120_000);
+
+test("check_novelty_search: one source short, and searches without claims", () => {
+  // fires: the delta search ran in two sources only (the third entry says nothing of how) — the error names it
+  {
+    const r = run((j) => {
+      legacy(j);
+      for (const c of j.claims) c.added = "2026-10-08";
+      addC8(j, "2026-11-04");
+      j.searched.push(entry("venue-pc", "2026-11-04", ["C8"]));
+      j.searched.push(entry("prev-edition", "2026-11-04", ["C8"]));
+      j.searched.push({
+        ...entry("arxiv-recent", "2026-11-04", ["C8"]),
+        how: " ",
+      });
+    });
+    // Guards: coverage is counted per source, not "some search names C8"; an entry without a "how" is no search.
+    assert.deepEqual(
+      { code: r.code, errors: r.errors },
+      { code: 1, errors: [missingC8("arxiv-recent", AFTER("2026-11-04"))] },
+    );
+  }
+  // silent: a search without "claims" dated on or after the claim's added date covers it (same day counts)
+  {
+    const r = run((j) => {
+      legacy(j);
+      for (const c of j.claims) c.added = "2026-10-08";
+      addC8(j, "2026-10-27");
+      j.searched.push(entry("arxiv-recent", "2026-10-27"));
+    });
+    // Guards: a table-wide search still counts for every claim the table had on its date.
+    assert.deepEqual(
+      { code: r.code, errors: r.errors },
+      { code: 0, errors: [] },
+    );
+  }
+  // fires: a search that names other claims does not cover C8, whatever its date
+  {
+    const r = run((j) => {
+      addC8(j, "2026-10-01");
+      // the fixture's searches name R1 and P5-1, dated 2026-10-08, after C8's added date
+    });
+    // Guards: an entry with "claims" covers only the claims it names; no hint, since no entry lacks "claims".
+    assert.deepEqual(
+      { code: r.code, errors: r.errors },
+      { code: 1, errors: [missingC8(SOURCES.join(", "), "")] },
+    );
+  }
+}, 120_000);
+
+test("check_novelty_search: migrating a table, and claims that are not free", () => {
+  // fires: an old table as it was (no "claims", no "added") whose 🟢 claim must now say when it entered
+  {
+    const r = run((j) => {
+      for (const s of j.searched) delete s.claims;
+    });
+    // Guards: the migration is named in the error itself; R1 is 🔴 and needs no search to stay 🔴.
+    assert.deepEqual(
+      { code: r.code, errors: r.errors },
+      {
+        code: 1,
+        errors: [
+          `P5-1: 🟢 but no search covers it in ${SOURCES.join(", ")}: search for P5-1 there and record it with "claims": ["P5-1"] (or set "added" to the day P5-1 entered the table: a search without "claims" covers only the claims added on or before its date)`,
+        ],
+      },
+    );
+  }
+  // silent: the same table migrated by dating its claims
+  {
+    const r = run((j) => {
+      for (const s of j.searched) delete s.claims;
+      for (const c of j.claims) c.added = "2026-10-08";
+    });
+    // Guards: "added" on or before the searches' date is the whole migration for a table searched once.
+    assert.deepEqual(
+      { code: r.code, errors: r.errors },
+      { code: 0, errors: [] },
+    );
+  }
+  // silent: a 🔴 claim that no search covers
+  {
+    const r = run((j) => {
+      for (const s of j.searched) s.claims = ["P5-1"];
+    });
+    // Guards: only a 🟢 rests on the search having covered the claim.
+    assert.deepEqual(
+      { code: r.code, errors: r.errors },
+      { code: 0, errors: [] },
+    );
+  }
+}, 120_000);
+
+test("check_novelty_search: an explicit null scope is malformed, not a table-wide search", () => {
+  const r = run((j) => {
+    for (const e of j.searched) e.claims = null;
+    for (const c of j.claims) c.added = "2026-10-08";
+  });
+  // Guards: "claims": null is not the same as no "claims". A null scope in every source must not authorize 🟢 for
+  // every claim added before the searches (Codex review on #370); it is named and covers nothing.
+  assert.equal(r.code, 1);
+  assert.deepEqual(
+    r.errors.filter((e) => e.startsWith("searched[")),
+    nullScopeErrors(3),
+  );
+  assert.ok(
+    r.errors.some((e) =>
+      e.startsWith(
+        "P5-1: 🟢 but no search covers it in venue-pc, prev-edition, arxiv-recent",
+      ),
+    ),
+    r.errors.join("\n"),
+  );
+}, 120_000);
+const nullScopeErrors = (n: number) =>
+  Array.from(
+    { length: n },
+    (_, i) =>
+      `searched[${i}]: "claims" must be a non-empty list of claim ids, got None`,
+  );
+
+test("check_novelty_search: malformed claims, added and dates", () => {
+  const r = run((j) => {
+    j.searched[0].claims = ["R1", "P5-1", "C9"];
+    j.searched[1].claims = [];
+    j.searched[2].claims = "P5-1";
+    claim(j, "R1").added = "4 Nov 2026";
+    j.searched.push({
+      source: "venue-pc",
+      how: "a later sweep",
+      date: "2026-13-01",
+    });
+    j.searched.push({ source: "venue-pc", how: "a sweep with no date" });
+  });
+  // Guards: each malformed field is named with its fix, and a malformed entry covers nothing (P5-1 is short of
+  // prev-edition and arxiv-recent, whose only entries are malformed). C9, no claim of the table, is no error: the
+  // entry records what was searched that day, and a claim dropped later does not make the record wrong.
+  assert.deepEqual(
+    { code: r.code, errors: r.errors },
+    {
+      code: 1,
+      errors: [
+        'searched[1]: "claims" must be a non-empty list of claim ids, got []',
+        "searched[2]: \"claims\" must be a non-empty list of claim ids, got 'P5-1'",
+        "searched[3]: date '2026-13-01' is not YYYY-MM-DD; a search without \"claims\" covers the claims added on or before its date",
+        'searched[4]: date None is not YYYY-MM-DD; a search without "claims" covers the claims added on or before its date',
+        "R1: \"added\" '4 Nov 2026' is not a date (YYYY-MM-DD)",
+        'P5-1: 🟢 but no search covers it in prev-edition, arxiv-recent: search for P5-1 there and record it with "claims": ["P5-1"]',
+      ],
+    },
+  );
+}, 120_000);

package/skills/assess-novelty/scripts/fixtures/novelty/siblings/novelty.json

@@ -1,9 +1,12 @@
 {
   "paper": "paper.tex",
   "searched": [
-    {"source": "venue-pc", "how": "venue PC list, DBLP 2024-2026 of each member", "date": "2026-10-08"},
-    {"source": "prev-edition", "how": "previous edition accepted papers, titles and abstracts", "date": "2026-10-08"},
-    {"source": "arxiv-recent", "how": "arXiv cs.SE since 2026-01: AGENTS.md, rules files", "date": "2026-10-08"}
+    {"source": "venue-pc", "how": "venue PC list, DBLP 2024-2026 of each member", "date": "2026-10-08",
+     "claims": ["R1", "P5-1"]},
+    {"source": "prev-edition", "how": "previous edition accepted papers, titles and abstracts", "date": "2026-10-08",
+     "claims": ["R1", "P5-1"]},
+    {"source": "arxiv-recent", "how": "arXiv cs.SE since 2026-01: AGENTS.md, rules files", "date": "2026-10-08",
+     "claims": ["R1", "P5-1"]}
   ],
   "neighbours": [
     {"id": "doe26", "cite": "doe2026rules", "source": "arxiv-recent", "read": "full",

package/skills/assess-novelty/scripts/novelty_search.py

@@ -0,0 +1,87 @@
+"""Which searches covered which claim: a 🟢 needs, in each of the three sources, a search that covered THAT claim.
+
+A `searched` entry is {"source", "how", "date", "claims"?}. With "claims" (a non-empty list of claim ids) it covers
+exactly the claims it names. Without it, it is a search of the whole table as it stood on its date: it covers the
+claims whose "added" (YYYY-MM-DD, the day the claim entered the table) is on or before that date, and no claim
+without "added". Why: a claim added a week after the last search inherited that search as if it had covered it, and
+came out 🟢 against neighbours collected for other claims (paperlint#367). An entry counts only with a "how".
+
+Migrating a table written before this: give each claim the day it entered the table as "added" (the searches
+without "claims" dated on or after it then count for it), or name the claims in each entry's "claims".
+"""
+import datetime
+import re
+
+SOURCES = ("venue-pc", "prev-edition", "arxiv-recent")
+DAY = re.compile(r"\d{4}-\d{2}-\d{2}")
+SCOPE = 'a search without "claims" covers only the claims added on or before its date'
+
+
+def day(value):
+    """The date a YYYY-MM-DD string names, or None."""
+    if not isinstance(value, str) or not DAY.fullmatch(value):
+        return None
+    try:
+        return datetime.date.fromisoformat(value)
+    except ValueError:
+        return None
+
+
+TABLE_WIDE = object()  # an entry without "claims"; an explicit "claims": null is malformed, not this
+
+
+def named(entry):
+    """The claim ids an entry names, or TABLE_WIDE for an entry without "claims" (a search of the whole table)."""
+    return entry["claims"] if "claims" in entry else TABLE_WIDE
+
+
+def well_formed(entry):
+    ids = named(entry)
+    return ids is TABLE_WIDE or (isinstance(ids, list) and bool(ids) and all(isinstance(i, str) for i in ids))
+
+
+def covers(entry, claim):
+    """Did this search cover this claim? A malformed entry covers nothing."""
+    if not (entry.get("how") or "").strip() or not well_formed(entry):
+        return False
+    ids = named(entry)
+    if ids is not TABLE_WIDE:
+        return claim.get("id") in ids
+    searched_on, added = day(entry.get("date")), day(claim.get("added"))
+    return searched_on is not None and added is not None and added <= searched_on
+
+
+def entry_errors(searched):
+    """A malformed "claims", and an entry without "claims" whose date is not a date: either covers nothing.
+
+    An id in "claims" that is no longer a claim is not an error: the entry records what was searched that day, and
+    a claim dropped from the table later does not make the record wrong (a misspelt id leaves its claim uncovered,
+    which claim_errors names).
+    """
+    def one(i, e):
+        ids = named(e)
+        if ids is TABLE_WIDE:
+            return ([] if day(e.get("date")) else
+                    [f"searched[{i}]: date {e.get('date')!r} is not YYYY-MM-DD; a search without \"claims\" covers"
+                     " the claims added on or before its date"])
+        return [] if well_formed(e) else [f'searched[{i}]: "claims" must be a non-empty list of claim ids, got {ids!r}']
+    return [err for i, e in enumerate(searched) for err in one(i, e)]
+
+
+def claim_errors(claim, searched, verdict):
+    """A malformed "added"; and, for a 🟢, the sources with no search that covered the claim, with the fix."""
+    cid = claim.get("id")
+    bad_added = (["%s: \"added\" %r is not a date (YYYY-MM-DD)" % (cid, claim["added"])]
+                 if "added" in claim and day(claim["added"]) is None else [])
+    if verdict != "🟢":
+        return bad_added
+    missing = [s for s in SOURCES if not any(e.get("source") == s and covers(e, claim) for e in searched)]
+    if not missing:
+        return bad_added
+    table_wide = any(e.get("source") in missing and named(e) is TABLE_WIDE and (e.get("how") or "").strip()
+                     for e in searched)
+    hint = ("" if not table_wide else
+            f' (or set "added" to the day {cid} entered the table: {SCOPE})' if day(claim.get("added")) is None else
+            f" ({SCOPE}; {cid} was added {claim['added']})")
+    return bad_added + [f"{cid}: 🟢 but no search covers it in {', '.join(missing)}: search for {cid} there and"
+                        f' record it with "claims": ["{cid}"]{hint}']

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,
     };
 }