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,12 @@ 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, type RuleRef } from "./rule-descriptions.ts";
11
+ import {
12
+ describeRule,
13
+ type Described as RuleText,
14
+ type RuleRef,
15
+ } from "./rule-descriptions.ts";
16
+ import { applyPreset } from "./label-page-presets.ts";
12
17
 
13
18
  // ── refusals and output ───────────────────────────────────────────────────────────────────────
14
19
  export class Refusal extends Error {
@@ -79,6 +84,11 @@ const writeJson = (path: string, value: unknown): void => {
79
84
  writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`, "utf8");
80
85
  };
81
86
  const JSON_VALUE = z.json();
87
+ /** The config with its named preset applied (label-page-presets.ts), refused by path. */
88
+ const withPreset = (raw: Json): Json => {
89
+ const r = applyPreset(raw);
90
+ return r.ok ? JSON_VALUE.parse(r.value) : fail(r.message);
91
+ };
82
92
  const readJson = (path: string): Json => {
83
93
  try {
84
94
  return JSON_VALUE.parse(JSON.parse(readFileSync(path, "utf8")));
@@ -93,18 +103,33 @@ const readJson = (path: string): Json => {
93
103
  // stops the build: a blind page fails by what leaked in, and a field nobody listed is exactly the
94
104
  // one nobody thought of. A NEW FIELD IS ADDED HERE ON PURPOSE, after asking "does this tell the
95
105
  // labeller what the answer is, or where the item came from?" — never to make a build pass.
96
- const PAGE_FIELDS = ["group", "title", "body", "code", "context"] as const;
106
+ // prettier-ignore
107
+ const PAGE_FIELDS = ["group", "title", "body", "code", "context", "file"] as const;
97
108
  const PRIVATE_FIELDS = ["source_id"] as const;
98
109
  // The linter rules an item names ("read as ruff `TID253`"): the page shows each with the linter's
99
110
  // own description, looked up at build time (rule-descriptions.ts), never typed into items.json.
100
111
  const RULES_FIELD = "rules";
101
- // One requirement of a line that holds several: the whole line and which part this item is. Shown on
102
- // the card beneath the item; the line is text the labeller may read, like `context`.
112
+ // The source line an item was drawn from, with its requirement marked (`mark`, words of the line)
113
+ // and which part of the line it is. Shown on the card; the line is text the labeller may read.
103
114
  const UNIT_FIELD = "unit";
115
+ // Two readings of one requirement, shown as rows A and B (#374).
116
+ const READINGS_FIELD = "readings";
117
+ // Content blocks (#380): generic, on any kind. Every label and sentence a block shows comes from
118
+ // items.json (or a preset, label-page-presets.ts); the page knows only the block's shape.
119
+ const BLOCK_FIELDS = [
120
+ "situation",
121
+ "excerpt",
122
+ "references",
123
+ "more",
124
+ "table",
125
+ "repeat",
126
+ ] as const;
104
127
  const ALLOWED_FIELDS: readonly string[] = [
105
128
  ...PAGE_FIELDS,
106
129
  RULES_FIELD,
107
130
  UNIT_FIELD,
131
+ READINGS_FIELD,
132
+ ...BLOCK_FIELDS,
108
133
  ...PRIVATE_FIELDS,
109
134
  ];
110
135
 
@@ -140,9 +165,11 @@ const SOURCES_SHOWN = `(${SOURCES.map(quoted).join(", ")})`;
140
165
  // the field's path (`questions[0].options[1].label`). A NEW FIELD IS A NEW LINE HERE; the
141
166
  // build-label-page test walks this very table (`schema` prints it) with a wrong type, null and an
142
167
  // empty value for each path, so a field without a line is a test failure, not a review finding.
143
- // The leak guard on items (ALLOWED_FIELDS) stays separate and stays closed.
144
- type SchemaNode =
168
+ // The leak guard on items (ALLOWED_FIELDS) stays separate and stays closed. `why` says, in a
169
+ // refusal, what a value must be (a pattern) or why a field is required (a page kind needs it).
170
+ type SchemaNode = (
145
171
  | { kind: "string"; required: boolean; pattern?: string }
172
+ | { kind: "text"; required: boolean }
146
173
  | { kind: "integer"; required: boolean }
147
174
  | { kind: "boolean"; required: boolean }
148
175
  | { kind: "array"; required: boolean; min: number; items: SchemaNode }
@@ -158,12 +185,20 @@ type SchemaNode =
158
185
  required: boolean;
159
186
  closed: boolean;
160
187
  fields: Readonly<Record<string, SchemaNode>>;
161
- };
188
+ }
189
+ ) & { why?: string };
162
190
 
163
- const string = (required = true, pattern?: string): SchemaNode =>
191
+ const string = (required = true, pattern?: string, why?: string): SchemaNode =>
164
192
  pattern === undefined
165
193
  ? { kind: "string", required }
166
- : { kind: "string", required, pattern };
194
+ : {
195
+ kind: "string",
196
+ required,
197
+ pattern,
198
+ ...(why === undefined ? {} : { why }),
199
+ };
200
+ /** A string that may be empty: a blank line of code. */
201
+ const text = (): SchemaNode => ({ kind: "text", required: true });
167
202
  const integer = (required = true): SchemaNode => ({
168
203
  kind: "integer",
169
204
  required,
@@ -195,26 +230,135 @@ const obj = (
195
230
  required = true,
196
231
  ): SchemaNode => ({ kind: "object", required, closed, fields });
197
232
 
198
- const ITEM_SCHEMA = obj(
199
- {
200
- source_id: string(),
201
- ...Object.fromEntries(
202
- PAGE_FIELDS.map((f) => [f, string(f === "group" || f === "body")]),
203
- ),
204
- [RULES_FIELD]: array(
205
- obj({ linter: string(true, "eslint|ruff"), id: string() }),
206
- false,
233
+ // What an item and a practice item both may carry beyond text: a practice card looks like the real
234
+ // cards it rehearses. Each is optional here; a page's `kind` makes some of them required (KINDS).
235
+ const LINK = string(false, "https?://\\S+", "an http(s) link");
236
+ const optional = (fields: Readonly<Record<string, SchemaNode>>): SchemaNode =>
237
+ obj(fields, true, false);
238
+ const TEXT_FIELD = obj({
239
+ label: string(false),
240
+ text: string(),
241
+ style: string(false, "code|note", "code or note"),
242
+ });
243
+ const CARD_FIELDS: Readonly<Record<string, SchemaNode>> = {
244
+ [RULES_FIELD]: array(
245
+ obj({
246
+ linter: string(true, "eslint|ruff", "eslint or ruff"),
247
+ id: string(),
248
+ }),
249
+ false,
250
+ 1,
251
+ ),
252
+ [UNIT_FIELD]: obj(
253
+ // `id` names one occurrence of the line (two files may hold the same words): never shown.
254
+ {
255
+ id: string(),
256
+ text: string(),
257
+ mark: string(),
258
+ part: integer(),
259
+ of: integer(),
260
+ },
261
+ true,
262
+ false,
263
+ ),
264
+ [READINGS_FIELD]: obj({ a: string(), b: string() }, true, false),
265
+ file: string(false),
266
+ situation: optional({ summary: string(), question: string() }),
267
+ excerpt: optional({
268
+ file: string(false),
269
+ url: LINK,
270
+ lines: array(obj({ n: integer(), text: text(), mark: boolean() }), true, 1),
271
+ caption: string(false),
272
+ mark_label: string(false),
273
+ }),
274
+ references: optional({
275
+ summary: string(),
276
+ entries: array(
277
+ obj({
278
+ label: string(false),
279
+ title: string(),
280
+ fields: array(TEXT_FIELD, true, 1),
281
+ url: LINK,
282
+ url_label: string(false),
283
+ }),
284
+ true,
207
285
  1,
208
286
  ),
209
- [UNIT_FIELD]: obj(
210
- // `id` names one occurrence of the line (two files may hold the same words): never shown.
211
- { id: string(), text: string(), part: integer(), of: integer() },
287
+ }),
288
+ more: optional({
289
+ summary: string(),
290
+ items: array(string(), true, 1),
291
+ rest: string(false),
292
+ }),
293
+ table: optional({
294
+ summary: string(),
295
+ note: string(false),
296
+ rows: array(
297
+ obj({
298
+ label: string(),
299
+ value: string(),
300
+ plain: string(false),
301
+ mark: optional({
302
+ tone: string(true, "yes|no", "yes or no"),
303
+ text: string(),
304
+ }),
305
+ }),
212
306
  true,
213
- false,
307
+ 1,
214
308
  ),
309
+ }),
310
+ repeat: optional({ group: string(), index: integer(), of: integer() }),
311
+ };
312
+ /**
313
+ * THE PAGE KINDS, and the card fields each requires on every item and practice card (#373). A fix to
314
+ * a card is a field; a kind that needs it makes it required, so a page built without it fails the
315
+ * schema with the field named instead of shipping the old card.
316
+ */
317
+ type Kind = "approval" | "witness" | "labels";
318
+ const KINDS: Readonly<Record<Kind, Readonly<Record<string, string>>>> = {
319
+ // keep or drop a drawn requirement: the line it came from, marked, and the rule read for it
320
+ approval: {
321
+ [UNIT_FIELD]:
322
+ "an approval card shows the line its requirement was drawn from, the requirement marked",
323
+ [RULES_FIELD]:
324
+ "an approval card shows the rule read for it, with the linter's own description",
325
+ },
326
+ // why two readings of one requirement disagree on a file
327
+ witness: {
328
+ [RULES_FIELD]:
329
+ "a witness card shows the rule both readings configure, with the linter's description",
330
+ [READINGS_FIELD]: "a witness card shows the two readings, one row each",
331
+ file: "a witness card shows the file the readings disagree on, on its own row",
215
332
  },
216
- false, // an unlisted item field is the leak guard's refusal, with its own message
217
- );
333
+ // gold labels, a blind review: the card is the item, nothing more is required
334
+ labels: {},
335
+ };
336
+ const KIND_NAMES = Object.keys(KINDS).join(", ");
337
+ /** The card fields of a page of `kind`: those it needs, required and saying why. */
338
+ const cardFields = (kind: Kind): Readonly<Record<string, SchemaNode>> =>
339
+ Object.fromEntries(
340
+ Object.entries(CARD_FIELDS).map(([name, node]) => {
341
+ const why = KINDS[kind][name];
342
+ return [
343
+ name,
344
+ why === undefined ? node : { ...node, required: true, why },
345
+ ];
346
+ }),
347
+ );
348
+ const itemSchema = (kind: Kind): SchemaNode =>
349
+ obj(
350
+ {
351
+ source_id: string(),
352
+ ...Object.fromEntries(
353
+ PAGE_FIELDS.filter((f) => f !== "file").map((f) => [
354
+ f,
355
+ string(f === "group" || f === "body"),
356
+ ]),
357
+ ),
358
+ ...cardFields(kind),
359
+ },
360
+ false, // an unlisted item field is the leak guard's refusal, with its own message
361
+ );
218
362
  // `icon` (an emoji) tells the buttons apart at a glance. No coloured side stripe on a button: it
219
363
  // reads as decoration, not meaning (the build-label-page look test refuses one).
220
364
  // `ask_why` (a prompt) makes the answer incomplete until the labeller says why: an approval page's "drop".
@@ -225,16 +369,18 @@ const OPTION_SCHEMA = obj({
225
369
  icon: string(false),
226
370
  ask_why: string(false),
227
371
  });
228
- const PRACTICE_SCHEMA = obj({
229
- ...Object.fromEntries(
230
- PAGE_FIELDS.filter((f) => f !== "group").map((f) => [
231
- f,
232
- string(f === "body"),
233
- ]),
234
- ),
235
- expected: mapping(string(), NAME_PATTERN, 1),
236
- why: string(),
237
- });
372
+ const practiceSchema = (kind: Kind): SchemaNode =>
373
+ obj({
374
+ ...Object.fromEntries(
375
+ PAGE_FIELDS.filter((f) => f !== "group" && f !== "file").map((f) => [
376
+ f,
377
+ string(f === "body"),
378
+ ]),
379
+ ),
380
+ ...cardFields(kind),
381
+ expected: mapping(string(), NAME_PATTERN, 1),
382
+ why: string(),
383
+ });
238
384
  const MIN_PRACTICE = 3;
239
385
  const QUESTION_SCHEMA = obj({
240
386
  id: string(true, NAME_PATTERN),
@@ -242,22 +388,35 @@ const QUESTION_SCHEMA = obj({
242
388
  short: string(false),
243
389
  options: array(OPTION_SCHEMA, true, 2),
244
390
  });
245
- export const CONFIG_SCHEMA = obj({
246
- study: string(true, NAME_PATTERN), // becomes a file name
247
- title: string(),
248
- intro: string(false),
249
- seed: integer(),
250
- groups: mapping(string(), NAME_PATTERN, 1), // ids become store document ids
251
- labeller_knows: array(string(true, NAME_PATTERN), false),
252
- // false: no "how well do you know {group}" question (an approval page: the author has never seen
253
- // these repositories, so its answer means nothing). Left out, every group is asked (rule 5).
254
- familiarity: boolean(false),
255
- familiarity_question: string(false),
256
- questions: array(QUESTION_SCHEMA, true, 1),
257
- practice: array(PRACTICE_SCHEMA, true, MIN_PRACTICE),
258
- practice_round: integer(false),
259
- items: array(ITEM_SCHEMA, true, 1),
260
- });
391
+ const configSchema = (kind: Kind): SchemaNode =>
392
+ obj({
393
+ study: string(true, NAME_PATTERN), // becomes a file name
394
+ kind: string(true, Object.keys(KINDS).join("|"), `one of ${KIND_NAMES}`),
395
+ title: string(),
396
+ intro: string(false),
397
+ seed: integer(),
398
+ groups: mapping(string(), NAME_PATTERN, 1), // ids become store document ids
399
+ labeller_knows: array(string(true, NAME_PATTERN), false),
400
+ // true: a "how well do you know {group}" question per group, for a study that filters on it
401
+ // (rule 5). Left out, none is asked: an approval page's author has never seen the repositories.
402
+ familiarity: boolean(false),
403
+ familiarity_question: string(false),
404
+ questions: array(QUESTION_SCHEMA, true, 1),
405
+ practice: array(practiceSchema(kind), true, MIN_PRACTICE),
406
+ practice_round: integer(false),
407
+ // Page-level words the blocks use (references/closed-choice-generator.md §«Content blocks»).
408
+ labels: optional({
409
+ place: string(false),
410
+ body: string(false),
411
+ line: string(false),
412
+ line_part: string(false),
413
+ repeat: string(false),
414
+ practice_example: string(false),
415
+ }),
416
+ items: array(itemSchema(kind), true, 1),
417
+ });
418
+ /** The declared schema (`schema` prints it): every field, those a kind requires left optional. */
419
+ export const CONFIG_SCHEMA = configSchema("labels");
261
420
 
262
421
  // ── checking a value against the schema ──────────────────────────────────────────────────────
263
422
  const at = (path: string, name: string): string =>
@@ -268,13 +427,13 @@ const ID_RULE = "letters, digits, - and _ only";
268
427
 
269
428
  function checkString(
270
429
  value: Json,
271
- node: { pattern?: string },
430
+ node: { pattern?: string; why?: string },
272
431
  where: string,
273
432
  ): void {
274
433
  if (typeof value !== "string" || !value.trim()) {
275
434
  fail(`${where}: must be a non-empty string, got ${repr(value)}`);
276
435
  } else if (node.pattern !== undefined && !fullMatch(node.pattern, value)) {
277
- fail(`${where}: ${repr(value)} must be ${ID_RULE}`);
436
+ fail(`${where}: ${repr(value)} must be ${node.why ?? ID_RULE}`);
278
437
  }
279
438
  }
280
439
  const checkCount = (n: number, min: number, where: string): void => {
@@ -319,7 +478,10 @@ function checkObject(
319
478
  return fail(`${where}: must be an object, got ${repr(value)}`);
320
479
  for (const [name, sub] of Object.entries(node.fields)) {
321
480
  if (has(value, name)) checkValue(value[name] ?? null, sub, at(path, name));
322
- else if (sub.required) fail(`${at(path, name)}: is required and missing`);
481
+ else if (sub.required)
482
+ fail(
483
+ `${at(path, name)}: is required and missing${sub.why === undefined ? "" : ` — ${sub.why}`}`,
484
+ );
323
485
  }
324
486
  const unknown = Object.keys(value).find((name) => !has(node.fields, name));
325
487
  if (node.closed && unknown !== undefined) {
@@ -332,6 +494,20 @@ function checkBoolean(value: Json, where: string): void {
332
494
  if (typeof value !== "boolean")
333
495
  fail(`${where}: must be true or false, got ${repr(value)}`);
334
496
  }
497
+ /** A string that may be empty (a blank line of code), or an integer. */
498
+ function checkScalar(
499
+ value: Json,
500
+ kind: "text" | "integer",
501
+ where: string,
502
+ ): void {
503
+ if (kind === "text" && typeof value !== "string")
504
+ fail(`${where}: must be a string, got ${repr(value)}`);
505
+ if (
506
+ kind === "integer" &&
507
+ (typeof value !== "number" || !Number.isInteger(value))
508
+ )
509
+ fail(`${where}: must be an integer, got ${repr(value)}`);
510
+ }
335
511
  /** Refuse the first place `value` departs from `node`; the message starts with the field's path. */
336
512
  function checkValue(value: Json, node: SchemaNode, path: string): void {
337
513
  const where = path || "items.json";
@@ -339,10 +515,9 @@ function checkValue(value: Json, node: SchemaNode, path: string): void {
339
515
  case "string":
340
516
  checkString(value, node, where);
341
517
  break;
518
+ case "text":
342
519
  case "integer":
343
- if (typeof value !== "number" || !Number.isInteger(value)) {
344
- fail(`${where}: must be an integer, got ${repr(value)}`);
345
- }
520
+ checkScalar(value, node.kind, where);
346
521
  break;
347
522
  case "boolean":
348
523
  checkBoolean(value, where);
@@ -375,28 +550,78 @@ interface Question {
375
550
  interface Unit {
376
551
  readonly id: string;
377
552
  readonly text: string;
553
+ readonly mark: string;
378
554
  readonly part: number;
379
555
  readonly of: number;
380
556
  }
381
- type Item = {
557
+ interface TextField {
558
+ readonly label?: string;
559
+ readonly text: string;
560
+ readonly style?: string;
561
+ }
562
+ interface CodeLine {
563
+ readonly n: number;
564
+ readonly text: string;
565
+ readonly mark: boolean;
566
+ }
567
+ /** The content blocks (#380), each optional on any kind. */
568
+ interface Blocks {
569
+ readonly situation?: { readonly summary: string; readonly question: string };
570
+ readonly excerpt?: {
571
+ readonly file?: string;
572
+ readonly url?: string;
573
+ readonly lines: readonly CodeLine[];
574
+ readonly caption?: string;
575
+ readonly mark_label?: string;
576
+ };
577
+ readonly references?: {
578
+ readonly summary: string;
579
+ readonly entries: readonly {
580
+ readonly label?: string;
581
+ readonly title: string;
582
+ readonly fields: readonly TextField[];
583
+ readonly url?: string;
584
+ readonly url_label?: string;
585
+ }[];
586
+ };
587
+ readonly more?: {
588
+ readonly summary: string;
589
+ readonly items: readonly string[];
590
+ readonly rest?: string;
591
+ };
592
+ readonly table?: {
593
+ readonly summary: string;
594
+ readonly note?: string;
595
+ readonly rows: readonly {
596
+ readonly label: string;
597
+ readonly value: string;
598
+ readonly plain?: string;
599
+ readonly mark?: { readonly tone: string; readonly text: string };
600
+ }[];
601
+ };
602
+ readonly repeat?: {
603
+ readonly group: string;
604
+ readonly index: number;
605
+ readonly of: number;
606
+ };
607
+ }
608
+ /** What a card shows, on an item and on a practice item alike. */
609
+ type Card = {
382
610
  readonly [F in (typeof PAGE_FIELDS)[number]]?: string;
383
- } & {
384
- readonly source_id: string;
385
- readonly group: string;
386
- readonly body: string;
387
- readonly rules?: readonly RuleRef[];
388
- readonly unit?: Unit;
389
- };
390
- interface Practice {
391
- readonly title?: string;
392
- readonly body: string;
393
- readonly code?: string;
394
- readonly context?: string;
611
+ } & Blocks & {
612
+ readonly body: string;
613
+ readonly rules?: readonly RuleRef[];
614
+ readonly unit?: Unit;
615
+ readonly readings?: { readonly a: string; readonly b: string };
616
+ };
617
+ type Item = Card & { readonly source_id: string; readonly group: string };
618
+ type Practice = Card & {
395
619
  readonly expected: Readonly<Record<string, string>>;
396
620
  readonly why: string;
397
- }
621
+ };
398
622
  interface Config {
399
623
  readonly study: string;
624
+ readonly kind: Kind;
400
625
  readonly title: string;
401
626
  readonly intro?: string;
402
627
  readonly seed: number;
@@ -407,6 +632,7 @@ interface Config {
407
632
  readonly questions: readonly Question[];
408
633
  readonly practice: readonly Practice[];
409
634
  readonly practice_round?: number;
635
+ readonly labels?: Readonly<Record<string, string>>;
410
636
  readonly items: readonly Item[];
411
637
  }
412
638
  /** The config is typed by passing CONFIG_SCHEMA: `checkValue` refuses (throws) on any departure. */
@@ -436,7 +662,7 @@ const allowedValues = (
436
662
  // Empty when the page asks no familiarity: the export then expects no group document at all.
437
663
  familiarity: asksFamiliarity ? FAMILIARITY.map((o) => o.value) : [],
438
664
  });
439
- const asksFamiliarity = (cfg: Config): boolean => cfg.familiarity !== false;
665
+ const asksFamiliarity = (cfg: Config): boolean => cfg.familiarity === true;
440
666
 
441
667
  /** Two values that read the same once case and surrounding space are gone. */
442
668
  const readsAs = (s: string): string => s.trim().toLowerCase();
@@ -522,7 +748,7 @@ function checkConfig(cfg: Config): void {
522
748
  checkGroups(cfg);
523
749
  if (!asksFamiliarity(cfg) && cfg.familiarity_question !== undefined) {
524
750
  fail(
525
- `familiarity_question: ${repr(cfg.familiarity_question)} is never asked, because \`familiarity\` is false — remove one of the two`,
751
+ `familiarity_question: ${repr(cfg.familiarity_question)} is never asked, because \`familiarity\` is not true — remove it, or set "familiarity": true`,
526
752
  );
527
753
  }
528
754
  cfg.questions.forEach((q, qn) => {
@@ -544,8 +770,9 @@ const practiceOf = (
544
770
  // ── the items: the leak guard, and the references to the config ───────────────────────────────
545
771
  /**
546
772
  * A line with several requirements is split upstream into one item per requirement, each carrying
547
- * `unit: {text, part, of}`. Every part of a line must be an item, once, in one group (so
548
- * `labeller_knows` keeps or drops the whole line): a lost part is a requirement nobody judged.
773
+ * `unit: {text, mark, part, of}`. A drawn sample may hold one part of a line and not the others; the
774
+ * parts it holds agree on the line, are not repeated, and sit in one group (so `labeller_knows`
775
+ * keeps or drops them together).
549
776
  */
550
777
  interface Part {
551
778
  readonly item: Item;
@@ -576,10 +803,6 @@ function checkPart({ item, unit, n }: Part, parts: Parts): void {
576
803
  fail(
577
804
  `${at}.unit.of: ${String(unit.of)}, but items[${String(first.n)}].unit.of says ${String(first.unit.of)} for the same line`,
578
805
  );
579
- if (unit.part < 1 || unit.part > unit.of)
580
- fail(
581
- `${at}.unit.part: ${String(unit.part)} is not between 1 and ${String(unit.of)}`,
582
- );
583
806
  const earlier = parts.find((p) => p.n < n && p.unit.part === unit.part);
584
807
  if (earlier !== undefined)
585
808
  fail(
@@ -590,21 +813,70 @@ function checkPart({ item, unit, n }: Part, parts: Parts): void {
590
813
  `${at}.group: ${repr(item.group)}, but items[${String(first.n)}] of the same line is in ${repr(first.item.group)}`,
591
814
  );
592
815
  }
816
+ /** One unit on its own: its part in range, and its mark the requirement's words in the line. */
817
+ function checkUnit(unit: Unit | undefined, at: string): void {
818
+ if (unit === undefined) return;
819
+ if (unit.part < 1 || unit.part > unit.of)
820
+ fail(
821
+ `${at}.unit.part: ${String(unit.part)} is not between 1 and ${String(unit.of)}`,
822
+ );
823
+ if (!unit.text.includes(unit.mark))
824
+ fail(
825
+ `${at}.unit.mark: ${repr(unit.mark)} is not in the line ${repr(unit.text)} — mark the requirement with the line's own words`,
826
+ );
827
+ }
593
828
  function checkUnits(cfg: Config): void {
594
- for (const [line, parts] of linesOf(cfg)) {
829
+ cardsOf(cfg).forEach(([at, card]) => {
830
+ checkUnit(card.unit, at);
831
+ });
832
+ for (const parts of linesOf(cfg).values()) {
595
833
  parts.forEach((p) => {
596
834
  checkPart(p, parts);
597
835
  });
598
- const [first] = parts;
599
- const missing = Array.from({ length: first.unit.of }, (_, k) => k + 1).find(
600
- (k) => !parts.some((p) => p.unit.part === k),
836
+ }
837
+ }
838
+ /**
839
+ * A situation's sentence or question may name the excerpt's marked line as `{line}`: the page writes
840
+ * «line N: » and the line's code there, so a question sits next to the code it is about.
841
+ */
842
+ const LINE_TOKEN = "{line}";
843
+ const SITUATION_TEXTS = ["summary", "question"] as const;
844
+ /** The line `{line}` stands for: the first marked line, its number and its code without the indent. */
845
+ const lineOf = (card: Card) =>
846
+ card.excerpt?.lines
847
+ .filter((l) => l.mark)
848
+ .map((l) => ({ n: l.n, text: l.text.trim() }))[0];
849
+ const usesLine = (card: Card): boolean =>
850
+ SITUATION_TEXTS.some((f) => card.situation?.[f].includes(LINE_TOKEN));
851
+ /**
852
+ * What the block schema cannot say: an excerpt marks a line, `{line}` has a marked line to stand for,
853
+ * and a repeat sits inside its count.
854
+ */
855
+ function checkBlocks(cfg: Config): void {
856
+ cardsOf(cfg).forEach(([at, card]) => {
857
+ if (card.excerpt !== undefined && !card.excerpt.lines.some((l) => l.mark))
858
+ fail(
859
+ `${at}.excerpt.lines: no line is marked — mark the line the card is about (\`mark: true\`)`,
860
+ );
861
+ const token = SITUATION_TEXTS.find((f) =>
862
+ card.situation?.[f].includes(LINE_TOKEN),
601
863
  );
602
- if (missing !== undefined)
864
+ if (token !== undefined && card.excerpt === undefined)
603
865
  fail(
604
- `items[${String(first.n)}].unit: part ${String(missing)} of ${String(first.unit.of)} of line ${repr(line)} is not among the items`,
866
+ `${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}\``,
605
867
  );
606
- }
868
+ const r = card.repeat;
869
+ if (r !== undefined && (r.index < 1 || r.index > r.of))
870
+ fail(
871
+ `${at}.repeat.index: ${String(r.index)} is not between 1 and ${String(r.of)}`,
872
+ );
873
+ });
607
874
  }
875
+ /** Every card of the config, items then practice, by path. */
876
+ const cardsOf = (cfg: Config) => [
877
+ ...cfg.items.map((i, n) => [`items[${String(n)}]`, i] as const),
878
+ ...cfg.practice.map((p, n) => [`practice[${String(n)}]`, p] as const),
879
+ ];
608
880
  function checkItemFields(cfg: Config): void {
609
881
  const sids: string[] = [];
610
882
  cfg.items.forEach((item, n) => {
@@ -627,11 +899,24 @@ function checkItemFields(cfg: Config): void {
627
899
  );
628
900
  });
629
901
  }
630
- /** Every text of an item the labeller sees, by field: the page fields and the line of a unit. */
631
- const visibleTexts = (item: Item): readonly (readonly [string, string])[] => [
632
- ...PAGE_FIELDS.map((f): readonly [string, string] => [f, item[f] ?? ""]),
633
- [UNIT_FIELD, item.unit?.text ?? ""],
634
- ];
902
+ /** Every string inside a value: each is tested on its own, as the page renders it, never a serialisation. */
903
+ const stringsIn = (v: unknown): readonly string[] =>
904
+ typeof v === "string"
905
+ ? [v]
906
+ : Array.isArray(v)
907
+ ? v.flatMap(stringsIn)
908
+ : typeof v === "object" && v !== null
909
+ ? Object.values(v).flatMap(stringsIn)
910
+ : [];
911
+ /**
912
+ * Every text of an item the labeller sees, by field: each string the page shows (the fields as
913
+ * `shownFields` passes them, so a repeat without its group), and every rule it names.
914
+ */
915
+ const visibleTexts = (item: Item): readonly (readonly [string, string])[] =>
916
+ Object.entries({
917
+ ...shownFields(item),
918
+ [RULES_FIELD]: item.rules ?? [],
919
+ }).flatMap(([f, v]) => stringsIn(v).map((t) => [f, t] as const));
635
920
  const escapeRegExp = (s: string): string =>
636
921
  s.replace(/[\\^$.*+?()[\]{}|/]/g, "\\$&");
637
922
  /**
@@ -715,11 +1000,18 @@ function assignIds(
715
1000
  }
716
1001
 
717
1002
  // ── a build, short of the page ──────────────────────────────────────────────────────────────────
718
- /** A unit as the page shows it: the part and the line, without the line's private id. */
719
- type ShownUnit = Omit<Unit, "id">;
720
- const shownFields = (
721
- item: Item,
722
- ): Readonly<Record<string, string | ShownUnit>> => ({
1003
+ /** A card's situation as the page shows it, with the line `{line}` stands for. */
1004
+ const situationShown = (item: Card) =>
1005
+ item.situation === undefined
1006
+ ? {}
1007
+ : {
1008
+ situation: {
1009
+ summary: item.situation.summary,
1010
+ question: item.situation.question,
1011
+ ...(usesLine(item) ? { line: lineOf(item) } : {}),
1012
+ },
1013
+ };
1014
+ const shownFields = (item: Card): Readonly<Record<string, unknown>> => ({
723
1015
  ...Object.fromEntries(
724
1016
  PAGE_FIELDS.flatMap((f) => {
725
1017
  const v = item[f];
@@ -731,37 +1023,50 @@ const shownFields = (
731
1023
  : {
732
1024
  [UNIT_FIELD]: {
733
1025
  text: item.unit.text,
1026
+ mark: item.unit.mark,
734
1027
  part: item.unit.part,
735
1028
  of: item.unit.of,
736
1029
  },
737
1030
  }),
1031
+ ...(item.readings === undefined ? {} : { [READINGS_FIELD]: item.readings }),
1032
+ ...Object.fromEntries(
1033
+ BLOCK_FIELDS.filter((f) => f !== "repeat" && f !== "situation").flatMap(
1034
+ (f) => (item[f] === undefined ? [] : [[f, item[f]]]),
1035
+ ),
1036
+ ),
1037
+ ...situationShown(item),
1038
+ ...(item.repeat === undefined
1039
+ ? {}
1040
+ : { repeat: { index: item.repeat.index, of: item.repeat.of } }),
738
1041
  });
739
- /** Rule → the linter's description, for every rule an item on the page names. */
740
- type Described = ReadonlyMap<string, string>;
1042
+ /** Rule → the linter's description (and a ruff rule's family), for every rule a card names. */
1043
+ type Described = ReadonlyMap<string, RuleText>;
741
1044
  const ruleKey = (r: RuleRef): string => `${r.linter} ${r.id}`;
742
1045
  /** Ask the linter for every rule named; refuse, by path, a rule it cannot describe. */
743
1046
  function describeRules(cfg: Config, fromDir: string): Described {
744
1047
  return new Map(
745
- cfg.items.flatMap((item, n) =>
746
- (item.rules ?? []).map((r, k): readonly [string, string] => {
747
- const text = describeRule(r, fromDir);
748
- return text === undefined
749
- ? fail(
750
- `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`,
751
- )
752
- : [ruleKey(r), text];
753
- }),
1048
+ cardsOf(cfg).flatMap(([at, card]) =>
1049
+ (card.rules ?? []).flatMap(
1050
+ (r, k): readonly (readonly [string, RuleText])[] => {
1051
+ const text = describeRule(r, fromDir);
1052
+ return text === undefined
1053
+ ? fail(
1054
+ `${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`,
1055
+ )
1056
+ : [[ruleKey(r), text]];
1057
+ },
1058
+ ),
754
1059
  ),
755
1060
  );
756
1061
  }
757
- const rulesShown = (item: Item, described: Described) =>
758
- item.rules === undefined
1062
+ const rulesShown = (card: Card, described: Described) =>
1063
+ card.rules === undefined
759
1064
  ? {}
760
1065
  : {
761
- [RULES_FIELD]: item.rules.map((r) => ({
1066
+ [RULES_FIELD]: card.rules.map((r) => ({
762
1067
  linter: r.linter,
763
1068
  id: r.id,
764
- description: String(described.get(ruleKey(r))),
1069
+ ...described.get(ruleKey(r)),
765
1070
  })),
766
1071
  };
767
1072
 
@@ -780,6 +1085,23 @@ function itemsOnPage(cfg: Config, keyPath: string) {
780
1085
  }
781
1086
  const practiceRound = (cfg: Config): number => cfg.practice_round ?? 1;
782
1087
 
1088
+ /** The practice as its cards show it, with the answers the page checks against. */
1089
+ const practiceShown = (cfg: Config, described: Described) =>
1090
+ practiceOf(cfg).map((p) => ({
1091
+ id: p.id,
1092
+ expected: p.expected,
1093
+ why: p.why,
1094
+ ...shownFields(p),
1095
+ ...rulesShown(p, described),
1096
+ }));
1097
+ /** The page's own words where `labels` leaves one out (references/closed-choice-generator.md). */
1098
+ const DEFAULT_LABELS: Readonly<Record<string, string>> = {
1099
+ place: "{id} · {n} of {total}",
1100
+ line: "Line",
1101
+ line_part: "{line} · part {part} of {of}",
1102
+ repeat: "Card {index} of {of}",
1103
+ practice_example: "",
1104
+ };
783
1105
  /** What a page shows: the questions, the practice and the items, blind, with their neutral ids. */
784
1106
  function payloadOf(
785
1107
  cfg: Config,
@@ -792,6 +1114,7 @@ function payloadOf(
792
1114
  return {
793
1115
  title: cfg.title,
794
1116
  intro: cfg.intro ?? "",
1117
+ labels: { ...DEFAULT_LABELS, ...cfg.labels },
795
1118
  groups: used.map((g) => ({ id: g, label: String(cfg.groups[g]) })),
796
1119
  familiarity_question: asksFamiliarity(cfg)
797
1120
  ? (cfg.familiarity_question ?? "How well do you know {group}?")
@@ -799,7 +1122,10 @@ function payloadOf(
799
1122
  familiarity: asksFamiliarity(cfg) ? FAMILIARITY : [],
800
1123
  allowed: allowedValues(cfg.questions, asksFamiliarity(cfg)),
801
1124
  questions: cfg.questions,
802
- practice: { round: practiceRound(cfg), items: practiceOf(cfg) },
1125
+ practice: {
1126
+ round: practiceRound(cfg),
1127
+ items: practiceShown(cfg, described),
1128
+ },
803
1129
  items: page.items.map((i) => ({
804
1130
  id: page.idOf(i),
805
1131
  ...shownFields(i),
@@ -878,11 +1204,14 @@ function keyOf(
878
1204
  * returns what the page shows. A page written by hand can take its blindness and its key from here.
879
1205
  */
880
1206
  export function prepareBuild(configPath: string, outDir: string) {
881
- const cfg = readJson(configPath);
1207
+ const cfg = withPreset(readJson(configPath));
882
1208
  assertConfig(cfg);
1209
+ // Once its `kind` is known to be one, the fields that kind needs on every card.
1210
+ checkValue(cfg, configSchema(cfg.kind), "");
883
1211
  checkConfig(cfg);
884
1212
  checkItemFields(cfg);
885
1213
  checkUnits(cfg);
1214
+ checkBlocks(cfg);
886
1215
  checkNoSourceShown(cfg);
887
1216
  const described = describeRules(cfg, dirname(configPath));
888
1217
  mkdirSync(outDir, { recursive: true });
@@ -1119,7 +1448,7 @@ function checkNoFamiliarity(dump: JsonObject, allowed: Allowed): void {
1119
1448
  const [first] = Object.keys(groups).sort(byText);
1120
1449
  if (allowed.familiarity.length === 0 && first !== undefined) {
1121
1450
  fail(
1122
- `groups/${first}: familiarity is off for this page (items.json \`familiarity: false\`), so no group document is expected — take it out of the dump`,
1451
+ `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`,
1123
1452
  );
1124
1453
  }
1125
1454
  }