paperlint 13.6.1 → 14.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (25) hide show
  1. package/dist/skills/build-label-page/scripts/label-page-core.d.ts +130 -21
  2. package/dist/skills/build-label-page/scripts/label-page-presets.d.ts +10 -0
  3. package/dist/skills/build-label-page/scripts/rule-descriptions.d.ts +6 -1
  4. package/package.json +1 -1
  5. package/skills/build-label-page/SKILL.md +9 -4
  6. package/skills/build-label-page/SKILL.md.spec.ts +8 -3
  7. package/skills/build-label-page/references/checklist.md +6 -6
  8. package/skills/build-label-page/references/closed-choice-generator.md +167 -21
  9. package/skills/build-label-page/scripts/fixtures/blocks-items.json +214 -0
  10. package/skills/build-label-page/scripts/fixtures/linter-config-witness-items.json +448 -0
  11. package/skills/build-label-page/scripts/label-page-blocks.test.ts +335 -0
  12. package/skills/build-label-page/scripts/label-page-browser.test.ts +437 -16
  13. package/skills/build-label-page/scripts/label-page-core.js +271 -46
  14. package/skills/build-label-page/scripts/label-page-core.test.ts +246 -37
  15. package/skills/build-label-page/scripts/label-page-core.ts +442 -113
  16. package/skills/build-label-page/scripts/label-page-html.test.ts +59 -52
  17. package/skills/build-label-page/scripts/label-page-presets.js +222 -0
  18. package/skills/build-label-page/scripts/label-page-presets.test.ts +175 -0
  19. package/skills/build-label-page/scripts/label-page-presets.ts +257 -0
  20. package/skills/build-label-page/scripts/label-page.js +19 -8
  21. package/skills/build-label-page/scripts/label-page.ts +19 -8
  22. package/skills/build-label-page/scripts/page-template.html +278 -45
  23. package/skills/build-label-page/scripts/rule-descriptions.js +48 -30
  24. package/skills/build-label-page/scripts/rule-descriptions.test.ts +58 -12
  25. package/skills/build-label-page/scripts/rule-descriptions.ts +56 -33
@@ -8,7 +8,8 @@ import { createHash } from "node:crypto";
8
8
  import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
9
9
  import { dirname, join } from "node:path";
10
10
  import { z } from "zod";
11
- import { describeRule } from "./rule-descriptions.js";
11
+ import { describeRule, } from "./rule-descriptions.js";
12
+ import { applyPreset } from "./label-page-presets.js";
12
13
  // ── refusals and output ───────────────────────────────────────────────────────────────────────
13
14
  export class Refusal extends Error {
14
15
  exitCode;
@@ -74,6 +75,11 @@ const writeJson = (path, value) => {
74
75
  writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`, "utf8");
75
76
  };
76
77
  const JSON_VALUE = z.json();
78
+ /** The config with its named preset applied (label-page-presets.ts), refused by path. */
79
+ const withPreset = (raw) => {
80
+ const r = applyPreset(raw);
81
+ return r.ok ? JSON_VALUE.parse(r.value) : fail(r.message);
82
+ };
77
83
  const readJson = (path) => {
78
84
  try {
79
85
  return JSON_VALUE.parse(JSON.parse(readFileSync(path, "utf8")));
@@ -88,18 +94,33 @@ const readJson = (path) => {
88
94
  // stops the build: a blind page fails by what leaked in, and a field nobody listed is exactly the
89
95
  // one nobody thought of. A NEW FIELD IS ADDED HERE ON PURPOSE, after asking "does this tell the
90
96
  // labeller what the answer is, or where the item came from?" — never to make a build pass.
91
- const PAGE_FIELDS = ["group", "title", "body", "code", "context"];
97
+ // prettier-ignore
98
+ const PAGE_FIELDS = ["group", "title", "body", "code", "context", "file"];
92
99
  const PRIVATE_FIELDS = ["source_id"];
93
100
  // The linter rules an item names ("read as ruff `TID253`"): the page shows each with the linter's
94
101
  // own description, looked up at build time (rule-descriptions.ts), never typed into items.json.
95
102
  const RULES_FIELD = "rules";
96
- // One requirement of a line that holds several: the whole line and which part this item is. Shown on
97
- // the card beneath the item; the line is text the labeller may read, like `context`.
103
+ // The source line an item was drawn from, with its requirement marked (`mark`, words of the line)
104
+ // and which part of the line it is. Shown on the card; the line is text the labeller may read.
98
105
  const UNIT_FIELD = "unit";
106
+ // Two readings of one requirement, shown as rows A and B (#374).
107
+ const READINGS_FIELD = "readings";
108
+ // Content blocks (#380): generic, on any kind. Every label and sentence a block shows comes from
109
+ // items.json (or a preset, label-page-presets.ts); the page knows only the block's shape.
110
+ const BLOCK_FIELDS = [
111
+ "situation",
112
+ "excerpt",
113
+ "references",
114
+ "more",
115
+ "table",
116
+ "repeat",
117
+ ];
99
118
  const ALLOWED_FIELDS = [
100
119
  ...PAGE_FIELDS,
101
120
  RULES_FIELD,
102
121
  UNIT_FIELD,
122
+ READINGS_FIELD,
123
+ ...BLOCK_FIELDS,
103
124
  ...PRIVATE_FIELDS,
104
125
  ];
105
126
  const FAMILIARITY = [
@@ -128,9 +149,16 @@ const RESERVED_NAMES = [
128
149
  const NAME_PATTERN = `(?!(?:${RESERVED_NAMES.join("|")})$)[A-Za-z0-9_-]+`;
129
150
  const SOURCES = ["page", "chat"];
130
151
  const SOURCES_SHOWN = `(${SOURCES.map(quoted).join(", ")})`;
131
- const string = (required = true, pattern) => pattern === undefined
152
+ const string = (required = true, pattern, why) => pattern === undefined
132
153
  ? { kind: "string", required }
133
- : { kind: "string", required, pattern };
154
+ : {
155
+ kind: "string",
156
+ required,
157
+ pattern,
158
+ ...(why === undefined ? {} : { why }),
159
+ };
160
+ /** A string that may be empty: a blank line of code. */
161
+ const text = () => ({ kind: "text", required: true });
134
162
  const integer = (required = true) => ({
135
163
  kind: "integer",
136
164
  required,
@@ -153,13 +181,100 @@ const mapping = (values, keyPattern, min = 0) => ({
153
181
  values,
154
182
  });
155
183
  const obj = (fields, closed = true, required = true) => ({ kind: "object", required, closed, fields });
156
- const ITEM_SCHEMA = obj({
157
- source_id: string(),
158
- ...Object.fromEntries(PAGE_FIELDS.map((f) => [f, string(f === "group" || f === "body")])),
159
- [RULES_FIELD]: array(obj({ linter: string(true, "eslint|ruff"), id: string() }), false, 1),
184
+ // What an item and a practice item both may carry beyond text: a practice card looks like the real
185
+ // cards it rehearses. Each is optional here; a page's `kind` makes some of them required (KINDS).
186
+ const LINK = string(false, "https?://\\S+", "an http(s) link");
187
+ const optional = (fields) => obj(fields, true, false);
188
+ const TEXT_FIELD = obj({
189
+ label: string(false),
190
+ text: string(),
191
+ style: string(false, "code|note", "code or note"),
192
+ });
193
+ const CARD_FIELDS = {
194
+ [RULES_FIELD]: array(obj({
195
+ linter: string(true, "eslint|ruff", "eslint or ruff"),
196
+ id: string(),
197
+ }), false, 1),
160
198
  [UNIT_FIELD]: obj(
161
199
  // `id` names one occurrence of the line (two files may hold the same words): never shown.
162
- { id: string(), text: string(), part: integer(), of: integer() }, true, false),
200
+ {
201
+ id: string(),
202
+ text: string(),
203
+ mark: string(),
204
+ part: integer(),
205
+ of: integer(),
206
+ }, true, false),
207
+ [READINGS_FIELD]: obj({ a: string(), b: string() }, true, false),
208
+ file: string(false),
209
+ situation: optional({ summary: string(), question: string() }),
210
+ excerpt: optional({
211
+ file: string(false),
212
+ url: LINK,
213
+ lines: array(obj({ n: integer(), text: text(), mark: boolean() }), true, 1),
214
+ caption: string(false),
215
+ mark_label: string(false),
216
+ }),
217
+ references: optional({
218
+ summary: string(),
219
+ entries: array(obj({
220
+ label: string(false),
221
+ title: string(),
222
+ fields: array(TEXT_FIELD, true, 1),
223
+ url: LINK,
224
+ url_label: string(false),
225
+ }), true, 1),
226
+ }),
227
+ more: optional({
228
+ summary: string(),
229
+ items: array(string(), true, 1),
230
+ rest: string(false),
231
+ }),
232
+ table: optional({
233
+ summary: string(),
234
+ note: string(false),
235
+ rows: array(obj({
236
+ label: string(),
237
+ value: string(),
238
+ plain: string(false),
239
+ mark: optional({
240
+ tone: string(true, "yes|no", "yes or no"),
241
+ text: string(),
242
+ }),
243
+ }), true, 1),
244
+ }),
245
+ repeat: optional({ group: string(), index: integer(), of: integer() }),
246
+ };
247
+ const KINDS = {
248
+ // keep or drop a drawn requirement: the line it came from, marked, and the rule read for it
249
+ approval: {
250
+ [UNIT_FIELD]: "an approval card shows the line its requirement was drawn from, the requirement marked",
251
+ [RULES_FIELD]: "an approval card shows the rule read for it, with the linter's own description",
252
+ },
253
+ // why two readings of one requirement disagree on a file
254
+ witness: {
255
+ [RULES_FIELD]: "a witness card shows the rule both readings configure, with the linter's description",
256
+ [READINGS_FIELD]: "a witness card shows the two readings, one row each",
257
+ file: "a witness card shows the file the readings disagree on, on its own row",
258
+ },
259
+ // gold labels, a blind review: the card is the item, nothing more is required
260
+ labels: {},
261
+ };
262
+ const KIND_NAMES = Object.keys(KINDS).join(", ");
263
+ /** The card fields of a page of `kind`: those it needs, required and saying why. */
264
+ const cardFields = (kind) => Object.fromEntries(Object.entries(CARD_FIELDS).map(([name, node]) => {
265
+ const why = KINDS[kind][name];
266
+ return [
267
+ name,
268
+ why === undefined ? node : { ...node, required: true, why },
269
+ ];
270
+ }));
271
+ const itemSchema = (kind) => obj({
272
+ source_id: string(),
273
+ ...Object.fromEntries(PAGE_FIELDS.filter((f) => f !== "file").map((f) => [
274
+ f,
275
+ string(f === "group" || f === "body"),
276
+ ])),
277
+ ...cardFields(kind),
163
278
  }, false);
164
279
  // `icon` (an emoji) tells the buttons apart at a glance. No coloured side stripe on a button: it
165
280
  // reads as decoration, not meaning (the build-label-page look test refuses one).
@@ -171,11 +286,12 @@ const OPTION_SCHEMA = obj({
171
286
  icon: string(false),
172
287
  ask_why: string(false),
173
288
  });
174
- const PRACTICE_SCHEMA = obj({
175
- ...Object.fromEntries(PAGE_FIELDS.filter((f) => f !== "group").map((f) => [
289
+ const practiceSchema = (kind) => obj({
290
+ ...Object.fromEntries(PAGE_FIELDS.filter((f) => f !== "group" && f !== "file").map((f) => [
176
291
  f,
177
292
  string(f === "body"),
178
293
  ])),
294
+ ...cardFields(kind),
179
295
  expected: mapping(string(), NAME_PATTERN, 1),
180
296
  why: string(),
181
297
  });
@@ -186,22 +302,34 @@ const QUESTION_SCHEMA = obj({
186
302
  short: string(false),
187
303
  options: array(OPTION_SCHEMA, true, 2),
188
304
  });
189
- export const CONFIG_SCHEMA = obj({
305
+ const configSchema = (kind) => obj({
190
306
  study: string(true, NAME_PATTERN), // becomes a file name
307
+ kind: string(true, Object.keys(KINDS).join("|"), `one of ${KIND_NAMES}`),
191
308
  title: string(),
192
309
  intro: string(false),
193
310
  seed: integer(),
194
311
  groups: mapping(string(), NAME_PATTERN, 1), // ids become store document ids
195
312
  labeller_knows: array(string(true, NAME_PATTERN), false),
196
- // false: no "how well do you know {group}" question (an approval page: the author has never seen
197
- // these repositories, so its answer means nothing). Left out, every group is asked (rule 5).
313
+ // true: a "how well do you know {group}" question per group, for a study that filters on it
314
+ // (rule 5). Left out, none is asked: an approval page's author has never seen the repositories.
198
315
  familiarity: boolean(false),
199
316
  familiarity_question: string(false),
200
317
  questions: array(QUESTION_SCHEMA, true, 1),
201
- practice: array(PRACTICE_SCHEMA, true, MIN_PRACTICE),
318
+ practice: array(practiceSchema(kind), true, MIN_PRACTICE),
202
319
  practice_round: integer(false),
203
- items: array(ITEM_SCHEMA, true, 1),
320
+ // Page-level words the blocks use (references/closed-choice-generator.md §«Content blocks»).
321
+ labels: optional({
322
+ place: string(false),
323
+ body: string(false),
324
+ line: string(false),
325
+ line_part: string(false),
326
+ repeat: string(false),
327
+ practice_example: string(false),
328
+ }),
329
+ items: array(itemSchema(kind), true, 1),
204
330
  });
331
+ /** The declared schema (`schema` prints it): every field, those a kind requires left optional. */
332
+ export const CONFIG_SCHEMA = configSchema("labels");
205
333
  // ── checking a value against the schema ──────────────────────────────────────────────────────
206
334
  const at = (path, name) => path ? `${path}.${name}` : name;
207
335
  const fullMatch = (pattern, s) => new RegExp(`^(?:${pattern})$`, "u").test(s);
@@ -211,7 +339,7 @@ function checkString(value, node, where) {
211
339
  fail(`${where}: must be a non-empty string, got ${repr(value)}`);
212
340
  }
213
341
  else if (node.pattern !== undefined && !fullMatch(node.pattern, value)) {
214
- fail(`${where}: ${repr(value)} must be ${ID_RULE}`);
342
+ fail(`${where}: ${repr(value)} must be ${node.why ?? ID_RULE}`);
215
343
  }
216
344
  }
217
345
  const checkCount = (n, min, where) => {
@@ -243,7 +371,7 @@ function checkObject(value, node, path, where) {
243
371
  if (has(value, name))
244
372
  checkValue(value[name] ?? null, sub, at(path, name));
245
373
  else if (sub.required)
246
- fail(`${at(path, name)}: is required and missing`);
374
+ fail(`${at(path, name)}: is required and missing${sub.why === undefined ? "" : ` — ${sub.why}`}`);
247
375
  }
248
376
  const unknown = Object.keys(value).find((name) => !has(node.fields, name));
249
377
  if (node.closed && unknown !== undefined) {
@@ -254,6 +382,14 @@ function checkBoolean(value, where) {
254
382
  if (typeof value !== "boolean")
255
383
  fail(`${where}: must be true or false, got ${repr(value)}`);
256
384
  }
385
+ /** A string that may be empty (a blank line of code), or an integer. */
386
+ function checkScalar(value, kind, where) {
387
+ if (kind === "text" && typeof value !== "string")
388
+ fail(`${where}: must be a string, got ${repr(value)}`);
389
+ if (kind === "integer" &&
390
+ (typeof value !== "number" || !Number.isInteger(value)))
391
+ fail(`${where}: must be an integer, got ${repr(value)}`);
392
+ }
257
393
  /** Refuse the first place `value` departs from `node`; the message starts with the field's path. */
258
394
  function checkValue(value, node, path) {
259
395
  const where = path || "items.json";
@@ -261,10 +397,9 @@ function checkValue(value, node, path) {
261
397
  case "string":
262
398
  checkString(value, node, where);
263
399
  break;
400
+ case "text":
264
401
  case "integer":
265
- if (typeof value !== "number" || !Number.isInteger(value)) {
266
- fail(`${where}: must be an integer, got ${repr(value)}`);
267
- }
402
+ checkScalar(value, node.kind, where);
268
403
  break;
269
404
  case "boolean":
270
405
  checkBoolean(value, where);
@@ -298,7 +433,7 @@ const allowedValues = (questions, asksFamiliarity) => ({
298
433
  // Empty when the page asks no familiarity: the export then expects no group document at all.
299
434
  familiarity: asksFamiliarity ? FAMILIARITY.map((o) => o.value) : [],
300
435
  });
301
- const asksFamiliarity = (cfg) => cfg.familiarity !== false;
436
+ const asksFamiliarity = (cfg) => cfg.familiarity === true;
302
437
  /** Two values that read the same once case and surrounding space are gone. */
303
438
  const readsAs = (s) => s.trim().toLowerCase();
304
439
  /** The first entry whose reading repeats an earlier one, with the index of that earlier one. */
@@ -363,7 +498,7 @@ function checkPractice(cfg) {
363
498
  function checkConfig(cfg) {
364
499
  checkGroups(cfg);
365
500
  if (!asksFamiliarity(cfg) && cfg.familiarity_question !== undefined) {
366
- fail(`familiarity_question: ${repr(cfg.familiarity_question)} is never asked, because \`familiarity\` is false — remove one of the two`);
501
+ fail(`familiarity_question: ${repr(cfg.familiarity_question)} is never asked, because \`familiarity\` is not true — remove it, or set "familiarity": true`);
367
502
  }
368
503
  cfg.questions.forEach((q, qn) => {
369
504
  checkQuestion(q, qn, cfg.questions.slice(0, qn).map((x) => x.id));
@@ -388,25 +523,63 @@ function checkPart({ item, unit, n }, parts) {
388
523
  fail(`${at}.unit.text: ${repr(unit.text)}, but items[${String(first.n)}] of line ${repr(unit.id)} says ${repr(first.unit.text)}`);
389
524
  if (unit.of !== first.unit.of)
390
525
  fail(`${at}.unit.of: ${String(unit.of)}, but items[${String(first.n)}].unit.of says ${String(first.unit.of)} for the same line`);
391
- if (unit.part < 1 || unit.part > unit.of)
392
- fail(`${at}.unit.part: ${String(unit.part)} is not between 1 and ${String(unit.of)}`);
393
526
  const earlier = parts.find((p) => p.n < n && p.unit.part === unit.part);
394
527
  if (earlier !== undefined)
395
528
  fail(`${at}.unit.part: ${String(unit.part)} repeats items[${String(earlier.n)}].unit.part`);
396
529
  if (item.group !== first.item.group)
397
530
  fail(`${at}.group: ${repr(item.group)}, but items[${String(first.n)}] of the same line is in ${repr(first.item.group)}`);
398
531
  }
532
+ /** One unit on its own: its part in range, and its mark the requirement's words in the line. */
533
+ function checkUnit(unit, at) {
534
+ if (unit === undefined)
535
+ return;
536
+ if (unit.part < 1 || unit.part > unit.of)
537
+ fail(`${at}.unit.part: ${String(unit.part)} is not between 1 and ${String(unit.of)}`);
538
+ if (!unit.text.includes(unit.mark))
539
+ fail(`${at}.unit.mark: ${repr(unit.mark)} is not in the line ${repr(unit.text)} — mark the requirement with the line's own words`);
540
+ }
399
541
  function checkUnits(cfg) {
400
- for (const [line, parts] of linesOf(cfg)) {
542
+ cardsOf(cfg).forEach(([at, card]) => {
543
+ checkUnit(card.unit, at);
544
+ });
545
+ for (const parts of linesOf(cfg).values()) {
401
546
  parts.forEach((p) => {
402
547
  checkPart(p, parts);
403
548
  });
404
- const [first] = parts;
405
- const missing = Array.from({ length: first.unit.of }, (_, k) => k + 1).find((k) => !parts.some((p) => p.unit.part === k));
406
- if (missing !== undefined)
407
- fail(`items[${String(first.n)}].unit: part ${String(missing)} of ${String(first.unit.of)} of line ${repr(line)} is not among the items`);
408
549
  }
409
550
  }
551
+ /**
552
+ * A situation's sentence or question may name the excerpt's marked line as `{line}`: the page writes
553
+ * «line N: » and the line's code there, so a question sits next to the code it is about.
554
+ */
555
+ const LINE_TOKEN = "{line}";
556
+ const SITUATION_TEXTS = ["summary", "question"];
557
+ /** The line `{line}` stands for: the first marked line, its number and its code without the indent. */
558
+ const lineOf = (card) => card.excerpt?.lines
559
+ .filter((l) => l.mark)
560
+ .map((l) => ({ n: l.n, text: l.text.trim() }))[0];
561
+ const usesLine = (card) => SITUATION_TEXTS.some((f) => card.situation?.[f].includes(LINE_TOKEN));
562
+ /**
563
+ * What the block schema cannot say: an excerpt marks a line, `{line}` has a marked line to stand for,
564
+ * and a repeat sits inside its count.
565
+ */
566
+ function checkBlocks(cfg) {
567
+ cardsOf(cfg).forEach(([at, card]) => {
568
+ if (card.excerpt !== undefined && !card.excerpt.lines.some((l) => l.mark))
569
+ fail(`${at}.excerpt.lines: no line is marked — mark the line the card is about (\`mark: true\`)`);
570
+ const token = SITUATION_TEXTS.find((f) => card.situation?.[f].includes(LINE_TOKEN));
571
+ if (token !== undefined && card.excerpt === undefined)
572
+ fail(`${at}.situation.${token}: \`${LINE_TOKEN}\` names the excerpt's marked line, and the card has no \`excerpt\` — add it, or write the ${token} without \`${LINE_TOKEN}\``);
573
+ const r = card.repeat;
574
+ if (r !== undefined && (r.index < 1 || r.index > r.of))
575
+ fail(`${at}.repeat.index: ${String(r.index)} is not between 1 and ${String(r.of)}`);
576
+ });
577
+ }
578
+ /** Every card of the config, items then practice, by path. */
579
+ const cardsOf = (cfg) => [
580
+ ...cfg.items.map((i, n) => [`items[${String(n)}]`, i]),
581
+ ...cfg.practice.map((p, n) => [`practice[${String(n)}]`, p]),
582
+ ];
410
583
  function checkItemFields(cfg) {
411
584
  const sids = [];
412
585
  cfg.items.forEach((item, n) => {
@@ -423,11 +596,22 @@ function checkItemFields(cfg) {
423
596
  fail(`items[${String(n)}].group: ${repr(item.group)} is not in \`groups\``);
424
597
  });
425
598
  }
426
- /** Every text of an item the labeller sees, by field: the page fields and the line of a unit. */
427
- const visibleTexts = (item) => [
428
- ...PAGE_FIELDS.map((f) => [f, item[f] ?? ""]),
429
- [UNIT_FIELD, item.unit?.text ?? ""],
430
- ];
599
+ /** Every string inside a value: each is tested on its own, as the page renders it, never a serialisation. */
600
+ const stringsIn = (v) => typeof v === "string"
601
+ ? [v]
602
+ : Array.isArray(v)
603
+ ? v.flatMap(stringsIn)
604
+ : typeof v === "object" && v !== null
605
+ ? Object.values(v).flatMap(stringsIn)
606
+ : [];
607
+ /**
608
+ * Every text of an item the labeller sees, by field: each string the page shows (the fields as
609
+ * `shownFields` passes them, so a repeat without its group), and every rule it names.
610
+ */
611
+ const visibleTexts = (item) => Object.entries({
612
+ ...shownFields(item),
613
+ [RULES_FIELD]: item.rules ?? [],
614
+ }).flatMap(([f, v]) => stringsIn(v).map((t) => [f, t]));
431
615
  const escapeRegExp = (s) => s.replace(/[\\^$.*+?()[\]{}|/]/g, "\\$&");
432
616
  /**
433
617
  * A source id typed into a visible field gives the source away as well as a field would. Short ids
@@ -481,6 +665,17 @@ function assignIds(items, seed, keyPath) {
481
665
  ]);
482
666
  return { ids, entries };
483
667
  }
668
+ // ── a build, short of the page ──────────────────────────────────────────────────────────────────
669
+ /** A card's situation as the page shows it, with the line `{line}` stands for. */
670
+ const situationShown = (item) => item.situation === undefined
671
+ ? {}
672
+ : {
673
+ situation: {
674
+ summary: item.situation.summary,
675
+ question: item.situation.question,
676
+ ...(usesLine(item) ? { line: lineOf(item) } : {}),
677
+ },
678
+ };
484
679
  const shownFields = (item) => ({
485
680
  ...Object.fromEntries(PAGE_FIELDS.flatMap((f) => {
486
681
  const v = item[f];
@@ -491,28 +686,35 @@ const shownFields = (item) => ({
491
686
  : {
492
687
  [UNIT_FIELD]: {
493
688
  text: item.unit.text,
689
+ mark: item.unit.mark,
494
690
  part: item.unit.part,
495
691
  of: item.unit.of,
496
692
  },
497
693
  }),
694
+ ...(item.readings === undefined ? {} : { [READINGS_FIELD]: item.readings }),
695
+ ...Object.fromEntries(BLOCK_FIELDS.filter((f) => f !== "repeat" && f !== "situation").flatMap((f) => (item[f] === undefined ? [] : [[f, item[f]]]))),
696
+ ...situationShown(item),
697
+ ...(item.repeat === undefined
698
+ ? {}
699
+ : { repeat: { index: item.repeat.index, of: item.repeat.of } }),
498
700
  });
499
701
  const ruleKey = (r) => `${r.linter} ${r.id}`;
500
702
  /** Ask the linter for every rule named; refuse, by path, a rule it cannot describe. */
501
703
  function describeRules(cfg, fromDir) {
502
- return new Map(cfg.items.flatMap((item, n) => (item.rules ?? []).map((r, k) => {
704
+ return new Map(cardsOf(cfg).flatMap(([at, card]) => (card.rules ?? []).flatMap((r, k) => {
503
705
  const text = describeRule(r, fromDir);
504
706
  return text === undefined
505
- ? 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`)
506
- : [ruleKey(r), text];
707
+ ? 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`)
708
+ : [[ruleKey(r), text]];
507
709
  })));
508
710
  }
509
- const rulesShown = (item, described) => item.rules === undefined
711
+ const rulesShown = (card, described) => card.rules === undefined
510
712
  ? {}
511
713
  : {
512
- [RULES_FIELD]: item.rules.map((r) => ({
714
+ [RULES_FIELD]: card.rules.map((r) => ({
513
715
  linter: r.linter,
514
716
  id: r.id,
515
- description: String(described.get(ruleKey(r))),
717
+ ...described.get(ruleKey(r)),
516
718
  })),
517
719
  };
518
720
  /** Only what the labeller can answer goes on the page, and only that gets an id, in id order. */
@@ -528,12 +730,29 @@ function itemsOnPage(cfg, keyPath) {
528
730
  return { items: sorted, ids, entries, idOf };
529
731
  }
530
732
  const practiceRound = (cfg) => cfg.practice_round ?? 1;
733
+ /** The practice as its cards show it, with the answers the page checks against. */
734
+ const practiceShown = (cfg, described) => practiceOf(cfg).map((p) => ({
735
+ id: p.id,
736
+ expected: p.expected,
737
+ why: p.why,
738
+ ...shownFields(p),
739
+ ...rulesShown(p, described),
740
+ }));
741
+ /** The page's own words where `labels` leaves one out (references/closed-choice-generator.md). */
742
+ const DEFAULT_LABELS = {
743
+ place: "{id} · {n} of {total}",
744
+ line: "Line",
745
+ line_part: "{line} · part {part} of {of}",
746
+ repeat: "Card {index} of {of}",
747
+ practice_example: "",
748
+ };
531
749
  /** What a page shows: the questions, the practice and the items, blind, with their neutral ids. */
532
750
  function payloadOf(cfg, page, described) {
533
751
  const used = Object.keys(cfg.groups).filter((g) => page.items.some((i) => i.group === g));
534
752
  return {
535
753
  title: cfg.title,
536
754
  intro: cfg.intro ?? "",
755
+ labels: { ...DEFAULT_LABELS, ...cfg.labels },
537
756
  groups: used.map((g) => ({ id: g, label: String(cfg.groups[g]) })),
538
757
  familiarity_question: asksFamiliarity(cfg)
539
758
  ? (cfg.familiarity_question ?? "How well do you know {group}?")
@@ -541,7 +760,10 @@ function payloadOf(cfg, page, described) {
541
760
  familiarity: asksFamiliarity(cfg) ? FAMILIARITY : [],
542
761
  allowed: allowedValues(cfg.questions, asksFamiliarity(cfg)),
543
762
  questions: cfg.questions,
544
- practice: { round: practiceRound(cfg), items: practiceOf(cfg) },
763
+ practice: {
764
+ round: practiceRound(cfg),
765
+ items: practiceShown(cfg, described),
766
+ },
545
767
  items: page.items.map((i) => ({
546
768
  id: page.idOf(i),
547
769
  ...shownFields(i),
@@ -608,11 +830,14 @@ function keyOf(cfg, page, earlier) {
608
830
  * returns what the page shows. A page written by hand can take its blindness and its key from here.
609
831
  */
610
832
  export function prepareBuild(configPath, outDir) {
611
- const cfg = readJson(configPath);
833
+ const cfg = withPreset(readJson(configPath));
612
834
  assertConfig(cfg);
835
+ // Once its `kind` is known to be one, the fields that kind needs on every card.
836
+ checkValue(cfg, configSchema(cfg.kind), "");
613
837
  checkConfig(cfg);
614
838
  checkItemFields(cfg);
615
839
  checkUnits(cfg);
840
+ checkBlocks(cfg);
616
841
  checkNoSourceShown(cfg);
617
842
  const described = describeRules(cfg, dirname(configPath));
618
843
  mkdirSync(outDir, { recursive: true });
@@ -774,7 +999,7 @@ function checkNoFamiliarity(dump, allowed) {
774
999
  const groups = isObject(dump["groups"]) ? dump["groups"] : {};
775
1000
  const [first] = Object.keys(groups).sort(byText);
776
1001
  if (allowed.familiarity.length === 0 && first !== undefined) {
777
- 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`);
1002
+ 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`);
778
1003
  }
779
1004
  }
780
1005
  /** The key's `allowed` lists, or a refusal naming a key made by an older build. */