paperlint 13.6.1 → 14.0.0

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

@@ -8,7 +8,7 @@ import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { z } from "zod";
-import { describeRule } from "./rule-descriptions.js";
+import { describeRule, } from "./rule-descriptions.js";
 // ── refusals and output ───────────────────────────────────────────────────────────────────────
 export class Refusal extends Error {
     exitCode;
@@ -88,18 +88,22 @@ const readJson = (path) => {
 // stops the build: a blind page fails by what leaked in, and a field nobody listed is exactly the
 // one nobody thought of. A NEW FIELD IS ADDED HERE ON PURPOSE, after asking "does this tell the
 // 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"];
+// prettier-ignore
+const PAGE_FIELDS = ["group", "title", "body", "code", "context", "file"];
 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`.
+// The source line an item was drawn from, with its requirement marked (`mark`, words of the line)
+// and which part of the line it is. Shown on the card; the line is text the labeller may read.
 const UNIT_FIELD = "unit";
+// Two readings of one requirement, shown as rows A and B (#374).
+const READINGS_FIELD = "readings";
 const ALLOWED_FIELDS = [
     ...PAGE_FIELDS,
     RULES_FIELD,
     UNIT_FIELD,
+    READINGS_FIELD,
     ...PRIVATE_FIELDS,
 ];
 const FAMILIARITY = [
@@ -128,9 +132,14 @@ const RESERVED_NAMES = [
 const NAME_PATTERN = `(?!(?:${RESERVED_NAMES.join("|")})$)[A-Za-z0-9_-]+`;
 const SOURCES = ["page", "chat"];
 const SOURCES_SHOWN = `(${SOURCES.map(quoted).join(", ")})`;
-const string = (required = true, pattern) => pattern === undefined
+const string = (required = true, pattern, why) => pattern === undefined
     ? { kind: "string", required }
-    : { kind: "string", required, pattern };
+    : {
+        kind: "string",
+        required,
+        pattern,
+        ...(why === undefined ? {} : { why }),
+    };
 const integer = (required = true) => ({
     kind: "integer",
     required,
@@ -153,13 +162,56 @@ const mapping = (values, keyPattern, min = 0) => ({
     values,
 });
 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),
+// What an item and a practice item both may carry beyond text: a practice card looks like the real
+// cards it rehearses. Each is optional here; a page's `kind` makes some of them required (KINDS).
+const CARD_FIELDS = {
+    [RULES_FIELD]: array(obj({
+        linter: string(true, "eslint|ruff", "eslint or 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),
+    {
+        id: string(),
+        text: string(),
+        mark: string(),
+        part: integer(),
+        of: integer(),
+    }, true, false),
+    [READINGS_FIELD]: obj({ a: string(), b: string() }, true, false),
+    file: string(false),
+};
+const KINDS = {
+    // keep or drop a drawn requirement: the line it came from, marked, and the rule read for it
+    approval: {
+        [UNIT_FIELD]: "an approval card shows the line its requirement was drawn from, the requirement marked",
+        [RULES_FIELD]: "an approval card shows the rule read for it, with the linter's own description",
+    },
+    // why two readings of one requirement disagree on a file
+    witness: {
+        [RULES_FIELD]: "a witness card shows the rule both readings configure, with the linter's description",
+        [READINGS_FIELD]: "a witness card shows the two readings, one row each",
+        file: "a witness card shows the file the readings disagree on, on its own row",
+    },
+    // gold labels, a blind review: the card is the item, nothing more is required
+    labels: {},
+};
+const KIND_NAMES = Object.keys(KINDS).join(", ");
+/** The card fields of a page of `kind`: those it needs, required and saying why. */
+const cardFields = (kind) => Object.fromEntries(Object.entries(CARD_FIELDS).map(([name, node]) => {
+    const why = KINDS[kind][name];
+    return [
+        name,
+        why === undefined ? node : { ...node, required: true, why },
+    ];
+}));
+const itemSchema = (kind) => obj({
+    source_id: string(),
+    ...Object.fromEntries(PAGE_FIELDS.filter((f) => f !== "file").map((f) => [
+        f,
+        string(f === "group" || f === "body"),
+    ])),
+    ...cardFields(kind),
 }, 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).
@@ -171,11 +223,12 @@ const OPTION_SCHEMA = obj({
     icon: string(false),
     ask_why: string(false),
 });
-const PRACTICE_SCHEMA = obj({
-    ...Object.fromEntries(PAGE_FIELDS.filter((f) => f !== "group").map((f) => [
+const practiceSchema = (kind) => obj({
+    ...Object.fromEntries(PAGE_FIELDS.filter((f) => f !== "group" && f !== "file").map((f) => [
         f,
         string(f === "body"),
     ])),
+    ...cardFields(kind),
     expected: mapping(string(), NAME_PATTERN, 1),
     why: string(),
 });
@@ -186,22 +239,25 @@ const QUESTION_SCHEMA = obj({
     short: string(false),
     options: array(OPTION_SCHEMA, true, 2),
 });
-export const CONFIG_SCHEMA = obj({
+const configSchema = (kind) => obj({
     study: string(true, NAME_PATTERN), // becomes a file name
+    kind: string(true, Object.keys(KINDS).join("|"), `one of ${KIND_NAMES}`),
     title: string(),
     intro: string(false),
     seed: integer(),
     groups: mapping(string(), NAME_PATTERN, 1), // ids become store document ids
     labeller_knows: array(string(true, NAME_PATTERN), false),
-    // false: no "how well do you know {group}" question (an approval page: the author has never seen
-    // these repositories, so its answer means nothing). Left out, every group is asked (rule 5).
+    // true: a "how well do you know {group}" question per group, for a study that filters on it
+    // (rule 5). Left out, none is asked: an approval page's author has never seen the repositories.
     familiarity: boolean(false),
     familiarity_question: string(false),
     questions: array(QUESTION_SCHEMA, true, 1),
-    practice: array(PRACTICE_SCHEMA, true, MIN_PRACTICE),
+    practice: array(practiceSchema(kind), true, MIN_PRACTICE),
     practice_round: integer(false),
-    items: array(ITEM_SCHEMA, true, 1),
+    items: array(itemSchema(kind), true, 1),
 });
+/** The declared schema (`schema` prints it): every field, those a kind requires left optional. */
+export const CONFIG_SCHEMA = configSchema("labels");
 // ── checking a value against the schema ──────────────────────────────────────────────────────
 const at = (path, name) => path ? `${path}.${name}` : name;
 const fullMatch = (pattern, s) => new RegExp(`^(?:${pattern})$`, "u").test(s);
@@ -211,7 +267,7 @@ function checkString(value, node, where) {
         fail(`${where}: must be a non-empty string, got ${repr(value)}`);
     }
     else if (node.pattern !== undefined && !fullMatch(node.pattern, value)) {
-        fail(`${where}: ${repr(value)} must be ${ID_RULE}`);
+        fail(`${where}: ${repr(value)} must be ${node.why ?? ID_RULE}`);
     }
 }
 const checkCount = (n, min, where) => {
@@ -243,7 +299,7 @@ function checkObject(value, node, path, where) {
         if (has(value, name))
             checkValue(value[name] ?? null, sub, at(path, name));
         else if (sub.required)
-            fail(`${at(path, name)}: is required and missing`);
+            fail(`${at(path, name)}: is required and missing${sub.why === undefined ? "" : ` — ${sub.why}`}`);
     }
     const unknown = Object.keys(value).find((name) => !has(node.fields, name));
     if (node.closed && unknown !== undefined) {
@@ -298,7 +354,7 @@ const allowedValues = (questions, asksFamiliarity) => ({
     // Empty when the page asks no familiarity: the export then expects no group document at all.
     familiarity: asksFamiliarity ? FAMILIARITY.map((o) => o.value) : [],
 });
-const asksFamiliarity = (cfg) => cfg.familiarity !== false;
+const asksFamiliarity = (cfg) => cfg.familiarity === true;
 /** Two values that read the same once case and surrounding space are gone. */
 const readsAs = (s) => s.trim().toLowerCase();
 /** The first entry whose reading repeats an earlier one, with the index of that earlier one. */
@@ -363,7 +419,7 @@ function checkPractice(cfg) {
 function checkConfig(cfg) {
     checkGroups(cfg);
     if (!asksFamiliarity(cfg) && cfg.familiarity_question !== undefined) {
-        fail(`familiarity_question: ${repr(cfg.familiarity_question)} is never asked, because \`familiarity\` is false — remove one of the two`);
+        fail(`familiarity_question: ${repr(cfg.familiarity_question)} is never asked, because \`familiarity\` is not true — remove it, or set "familiarity": true`);
     }
     cfg.questions.forEach((q, qn) => {
         checkQuestion(q, qn, cfg.questions.slice(0, qn).map((x) => x.id));
@@ -388,25 +444,36 @@ function checkPart({ item, unit, n }, parts) {
         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)}`);
 }
+/** One unit on its own: its part in range, and its mark the requirement's words in the line. */
+function checkUnit(unit, at) {
+    if (unit === undefined)
+        return;
+    if (unit.part < 1 || unit.part > unit.of)
+        fail(`${at}.unit.part: ${String(unit.part)} is not between 1 and ${String(unit.of)}`);
+    if (!unit.text.includes(unit.mark))
+        fail(`${at}.unit.mark: ${repr(unit.mark)} is not in the line ${repr(unit.text)} — mark the requirement with the line's own words`);
+}
 function checkUnits(cfg) {
-    for (const [line, parts] of linesOf(cfg)) {
+    cardsOf(cfg).forEach(([at, card]) => {
+        checkUnit(card.unit, at);
+    });
+    for (const parts of linesOf(cfg).values()) {
         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`);
     }
 }
+/** Every card of the config, items then practice, by path. */
+const cardsOf = (cfg) => [
+    ...cfg.items.map((i, n) => [`items[${String(n)}]`, i]),
+    ...cfg.practice.map((p, n) => [`practice[${String(n)}]`, p]),
+];
 function checkItemFields(cfg) {
     const sids = [];
     cfg.items.forEach((item, n) => {
@@ -427,6 +494,7 @@ function checkItemFields(cfg) {
 const visibleTexts = (item) => [
     ...PAGE_FIELDS.map((f) => [f, item[f] ?? ""]),
     [UNIT_FIELD, item.unit?.text ?? ""],
+    [READINGS_FIELD, `${item.readings?.a ?? ""} ${item.readings?.b ?? ""}`],
 ];
 const escapeRegExp = (s) => s.replace(/[\\^$.*+?()[\]{}|/]/g, "\\$&");
 /**
@@ -491,28 +559,30 @@ const shownFields = (item) => ({
         : {
             [UNIT_FIELD]: {
                 text: item.unit.text,
+                mark: item.unit.mark,
                 part: item.unit.part,
                 of: item.unit.of,
             },
         }),
+    ...(item.readings === undefined ? {} : { [READINGS_FIELD]: item.readings }),
 });
 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) => {
+    return new Map(cardsOf(cfg).flatMap(([at, card]) => (card.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`)
+            ? fail(`${at}.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
+const rulesShown = (card, described) => card.rules === undefined
     ? {}
     : {
-        [RULES_FIELD]: item.rules.map((r) => ({
+        [RULES_FIELD]: card.rules.map((r) => ({
             linter: r.linter,
             id: r.id,
-            description: String(described.get(ruleKey(r))),
+            ...described.get(ruleKey(r)),
         })),
     };
 /** Only what the labeller can answer goes on the page, and only that gets an id, in id order. */
@@ -528,6 +598,14 @@ function itemsOnPage(cfg, keyPath) {
     return { items: sorted, ids, entries, idOf };
 }
 const practiceRound = (cfg) => cfg.practice_round ?? 1;
+/** The practice as its cards show it, with the answers the page checks against. */
+const practiceShown = (cfg, described) => practiceOf(cfg).map((p) => ({
+    id: p.id,
+    expected: p.expected,
+    why: p.why,
+    ...shownFields(p),
+    ...rulesShown(p, described),
+}));
 /** What a page shows: the questions, the practice and the items, blind, with their neutral ids. */
 function payloadOf(cfg, page, described) {
     const used = Object.keys(cfg.groups).filter((g) => page.items.some((i) => i.group === g));
@@ -541,7 +619,10 @@ function payloadOf(cfg, page, described) {
         familiarity: asksFamiliarity(cfg) ? FAMILIARITY : [],
         allowed: allowedValues(cfg.questions, asksFamiliarity(cfg)),
         questions: cfg.questions,
-        practice: { round: practiceRound(cfg), items: practiceOf(cfg) },
+        practice: {
+            round: practiceRound(cfg),
+            items: practiceShown(cfg, described),
+        },
         items: page.items.map((i) => ({
             id: page.idOf(i),
             ...shownFields(i),
@@ -610,6 +691,8 @@ function keyOf(cfg, page, earlier) {
 export function prepareBuild(configPath, outDir) {
     const cfg = readJson(configPath);
     assertConfig(cfg);
+    // Once its `kind` is known to be one, the fields that kind needs on every card.
+    checkValue(cfg, configSchema(cfg.kind), "");
     checkConfig(cfg);
     checkItemFields(cfg);
     checkUnits(cfg);
@@ -774,7 +857,7 @@ function checkNoFamiliarity(dump, allowed) {
     const groups = isObject(dump["groups"]) ? dump["groups"] : {};
     const [first] = Object.keys(groups).sort(byText);
     if (allowed.familiarity.length === 0 && first !== undefined) {
-        fail(`groups/${first}: familiarity is off for this page (items.json \`familiarity: false\`), so no group document is expected — take it out of the dump`);
+        fail(`groups/${first}: familiarity is off for this page (items.json does not set \`"familiarity": true\`), so no group document is expected — take it out of the dump`);
     }
 }
 /** The key's `allowed` lists, or a refusal naming a key made by an older build. */

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

@@ -9,8 +9,10 @@ import { join } from "node:path";
 import { test } from "vitest";
 import { z } from "zod";
 import {
+  APPROVAL_PRACTICE,
   DONE_PRACTICE,
   Exported,
+  approvalCard,
   ITEMS,
   PRACTICE,
   QUESTIONS,
@@ -62,6 +64,16 @@ interface DocObject {
 const isObject = (v: Doc | undefined): v is DocObject =>
   typeof v === "object" && v !== null && !Array.isArray(v);
 
+/** Every optional field of a card, for an item and a practice item alike. */
+const CARD = {
+  title: "T",
+  code: "c = 1",
+  context: "ctx",
+  file: "`src/a.ts`",
+  rules: [{ linter: "eslint", id: "no-console" }],
+  unit: { id: "L0", text: "One line.", mark: "One", part: 1, of: 1 },
+  readings: { a: "on", b: "off" },
+};
 /** A config with EVERY optional field present, so every schema path has a value to spoil. */
 const FULL: DocObject = (() => {
   const doc = Doc.parse(
@@ -80,18 +92,8 @@ const FULL: DocObject = (() => {
       labeller_knows: ["python", "go", "rust"],
       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",
-              rules: [{ linter: "eslint", id: "no-console" }],
-              unit: { id: "L0", text: "One line.", part: 1, of: 1 },
-            }
-          : i,
-      ),
+      practice: PRACTICE.map((p, n) => (n === 0 ? { ...p, ...CARD } : p)),
+      items: ITEMS.map((i, n) => (n === 0 ? { ...i, ...CARD } : i)),
     }),
   );
   assert.ok(isObject(doc));
@@ -235,9 +237,17 @@ function expectRefused(leaf: Leaf): void {
     assert.doesNotMatch(r.out, /Traceback/, `${what}\n${r.out}`);
   });
   if (!leaf.node.required && !leaf.member) {
+    const absent = spoil(leaf.path, undefined);
+    // familiarity_question asks nothing unless familiarity is on: the two leave together.
     const r = tryBuild(
       `schema-${leaf.path.replace(/\W/g, "_")}-absent`,
-      spoil(leaf.path, undefined),
+      leaf.path === "familiarity"
+        ? Object.fromEntries(
+            Object.entries(absent).filter(
+              ([k]) => k !== "familiarity_question",
+            ),
+          )
+        : absent,
     );
     assert.equal(r.status, 0, `${leaf.path} is optional: ${r.out}`);
   }
@@ -245,6 +255,7 @@ function expectRefused(leaf: Leaf): void {
 
 const DOCUMENTED_FIELDS = [
   "study",
+  "kind",
   "title",
   "intro",
   "seed",
@@ -1257,19 +1268,42 @@ test("🔴 familiarity off with a familiarity_question is a contradiction the bu
   assert.notEqual(r.status, 0);
   assert.match(
     r.out,
-    /REFUSED: familiarity_question: .*`familiarity` is false/,
+    /REFUSED: familiarity_question: .*`familiarity` is not true/,
   );
 });
 
-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"]);
+test('🔴 familiarity left out asks no group, approval page or not; a page asks it only with `"familiarity": true`', () => {
+  // Guards: the default is off for every page (#373), so an approval page built the old way asks nothing.
+  for (const [name, cfg] of [
+    ["fam-default-approval", approval()],
+    ["fam-default-gold", config({ familiarity: undefined })],
+  ] as const) {
+    assert.deepEqual(build(setup(name, cfg)).key.allowed.familiarity, []);
+  }
+  const asks = setup("fam-on", config());
+  assert.deepEqual(build(asks).key.allowed.familiarity, [
+    "well",
+    "somewhat",
+    "not_really",
+  ]);
   writeFileSync(
-    join(dir, "dump.json"),
+    join(asks, "dump.json"),
     JSON.stringify({ answers: {}, groups: {} }),
   );
-  assert.match(exportAt(dir).out, /group python: no familiarity answer/);
+  assert.match(exportAt(asks).out, /group python: no familiarity answer/);
+  const r = run([
+    "build",
+    join(
+      setup(
+        "fam-question-alone",
+        config({ familiarity: undefined, familiarity_question: "How well?" }),
+      ),
+      "items.json",
+    ),
+    join(WORK, "fam-question-alone-out"),
+  ]);
+  assert.equal(r.status, 1, r.out);
+  assert.match(r.out, /REFUSED: familiarity_question: .*is not true/);
 });
 
 /** Items 0 and 3 (both Rust) as the two requirements of one line. */
@@ -1280,7 +1314,13 @@ const withUnit = (
   config({
     items: ITEMS.map((item, n) => {
       const u = parts.find(([at]) => at === n);
-      return u === undefined ? item : { ...item, unit: u[1] };
+      // the first word of the line is marked unless the case says otherwise
+      return u === undefined
+        ? item
+        : {
+            ...item,
+            unit: { mark: String(u[1]["text"]).split(" ")[0], ...u[1] },
+          };
     }),
   });
 
@@ -1291,9 +1331,11 @@ const UNIT_REFUSALS: readonly (readonly [
   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-mark-not-in-line",
+    withUnit([
+      [0, { id: "L1", text: LINE, mark: "JavaScript only", part: 1, of: 2 }],
+    ]),
+    "items[0].unit.mark: 'JavaScript only' is not in the line 'TypeScript only (no JavaScript); top-level await is allowed.' — mark the requirement with the line's own words",
   ],
   [
     "unit-part-twice",
@@ -1332,14 +1374,6 @@ const UNIT_REFUSALS: readonly (readonly [
     ]),
     "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 }]]),
@@ -1347,6 +1381,32 @@ const UNIT_REFUSALS: readonly (readonly [
   ],
 ];
 
+test("🔴 a drawn sample holds one requirement of a line that has two: it builds, the drawn part marked", () => {
+  // Guards: a unit with `of` above the parts present is a drawn part, not a lost one (#373, 5 of 9 cards).
+  const { page } = build(
+    setup(
+      "unit-drawn-part",
+      withUnit([
+        [
+          0,
+          {
+            id: "L1",
+            text: LINE,
+            mark: "top-level await is allowed",
+            part: 2,
+            of: 2,
+          },
+        ],
+      ]),
+    ),
+  );
+  assert.ok(
+    page.includes(
+      `"unit": {"text": "${LINE}", "mark": "top-level await is allowed", "part": 2, "of": 2}`,
+    ),
+  );
+});
+
 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);
@@ -1375,7 +1435,12 @@ test("a line whose every requirement is an item builds, and each item carries it
       items: z.array(
         z.object({
           unit: z
-            .object({ text: z.string(), part: z.number(), of: z.number() })
+            .object({
+              text: z.string(),
+              mark: z.string(),
+              part: z.number(),
+              of: z.number(),
+            })
             .optional(),
         }),
       ),
@@ -1385,8 +1450,8 @@ test("a line whose every requirement is an item builds, and each item carries it
     .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 },
+    { text: LINE, mark: "TypeScript", part: 1, of: 2 },
+    { text: LINE, mark: "TypeScript", part: 2, of: 2 },
   ]);
 });
 
@@ -1403,3 +1468,95 @@ 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");
 });
+
+/** A witness card: an approval card's line and rule, plus the two readings and the file. */
+const witnessCard = <T extends { readonly body: string }>(c: T, n: number) => ({
+  ...approvalCard(c, n),
+  readings: { a: "on", b: "off" },
+  file: "`src/a.ts`: B flags it",
+});
+const witnessPage = (
+  items: readonly Record<string, unknown>[] = ITEMS.map(witnessCard),
+) =>
+  approval({
+    kind: "witness",
+    practice: APPROVAL_PRACTICE.map(witnessCard),
+    items,
+  });
+
+/** Pages that miss their kind or a field it needs, each with its refusal. */
+function kindRefusals(): readonly (readonly [
+  string,
+  Record<string, unknown>,
+  string,
+])[] {
+  const plain = { items: ITEMS, practice: APPROVAL_PRACTICE };
+  const rulesOnly = {
+    items: ITEMS.map((c, n) => ({ ...c, rules: approvalCard(c, n).rules })),
+    practice: APPROVAL_PRACTICE.map((c, n) => ({
+      ...c,
+      rules: approvalCard(c, n).rules,
+    })),
+  };
+  return [
+    // the shape pages were built in until now: no kind, the line and the rule in free text
+    [
+      "kind-missing",
+      approval({ ...plain, kind: undefined }),
+      "kind: is required and missing — one of approval, witness, labels",
+    ],
+    [
+      "kind-unknown",
+      approval({ kind: "audit" }),
+      "kind: 'audit' must be one of approval, witness, labels",
+    ],
+    [
+      "approval-no-rules",
+      approval(plain),
+      "practice[0].rules: is required and missing — an approval card shows the rule read for it, with the linter's own description",
+    ],
+    [
+      "approval-no-unit",
+      approval(rulesOnly),
+      "practice[0].unit: is required and missing — an approval card shows the line its requirement was drawn from, the requirement marked",
+    ],
+    [
+      "witness-no-readings",
+      approval({ kind: "witness" }),
+      "practice[0].readings: is required and missing — a witness card shows the two readings, one row each",
+    ],
+    [
+      "witness-no-file",
+      witnessPage(
+        ITEMS.map((c, n) => ({ ...witnessCard(c, n), file: undefined })),
+      ),
+      "items[0].file: is required and missing — a witness card shows the file the readings disagree on, on its own row",
+    ],
+  ];
+}
+
+test("🔴 a page without its kind, or a card without its kind's fields, fails the schema naming the field", () => {
+  const refused = kindRefusals();
+  // Guards: the whole refusal, the field and why the page's kind needs it.
+  assert.deepEqual(
+    refused.map(([name, cfg]) => {
+      const dir = setup(name, cfg);
+      return run(["build", join(dir, "items.json"), join(dir, "out")]);
+    }),
+    refused.map(([, , message]) => ({
+      status: 1,
+      out: `REFUSED: ${message}\n`,
+    })),
+  );
+});
+
+test("a page of each kind with its fields builds; a practice card shows its rule like a real one", () => {
+  const witness = build(setup("witness-ok", witnessPage()));
+  assert.ok(witness.page.includes('"readings": {"a": "on", "b": "off"}'));
+  assert.ok(
+    build(setup("approval-ok", approval())).page.includes(
+      '"rules": [{"linter": "eslint", "id": "no-console", "description": "Disallow the use of `console`"}]',
+    ),
+  );
+  assert.equal(build(setup("labels-ok", config())).key.seed, 7);
+});