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.
- package/dist/skills/build-label-page/scripts/label-page-core.d.ts +130 -21
- package/dist/skills/build-label-page/scripts/label-page-presets.d.ts +10 -0
- package/dist/skills/build-label-page/scripts/rule-descriptions.d.ts +6 -1
- package/package.json +1 -1
- package/skills/build-label-page/SKILL.md +9 -4
- package/skills/build-label-page/SKILL.md.spec.ts +8 -3
- package/skills/build-label-page/references/checklist.md +6 -6
- package/skills/build-label-page/references/closed-choice-generator.md +167 -21
- package/skills/build-label-page/scripts/fixtures/blocks-items.json +214 -0
- package/skills/build-label-page/scripts/fixtures/linter-config-witness-items.json +448 -0
- package/skills/build-label-page/scripts/label-page-blocks.test.ts +335 -0
- package/skills/build-label-page/scripts/label-page-browser.test.ts +437 -16
- package/skills/build-label-page/scripts/label-page-core.js +271 -46
- package/skills/build-label-page/scripts/label-page-core.test.ts +246 -37
- package/skills/build-label-page/scripts/label-page-core.ts +442 -113
- package/skills/build-label-page/scripts/label-page-html.test.ts +59 -52
- package/skills/build-label-page/scripts/label-page-presets.js +222 -0
- package/skills/build-label-page/scripts/label-page-presets.test.ts +175 -0
- package/skills/build-label-page/scripts/label-page-presets.ts +257 -0
- package/skills/build-label-page/scripts/label-page.js +19 -8
- package/skills/build-label-page/scripts/label-page.ts +19 -8
- package/skills/build-label-page/scripts/page-template.html +278 -45
- package/skills/build-label-page/scripts/rule-descriptions.js +48 -30
- package/skills/build-label-page/scripts/rule-descriptions.test.ts +58 -12
- 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 {
|
|
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
|
-
|
|
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
|
-
//
|
|
102
|
-
// the
|
|
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
|
-
|
|
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
|
-
: {
|
|
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
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
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
|
-
|
|
210
|
-
|
|
211
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
f
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
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
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
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)
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
};
|
|
390
|
-
|
|
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
|
|
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
|
|
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}`.
|
|
548
|
-
*
|
|
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
|
-
|
|
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
|
-
|
|
599
|
-
|
|
600
|
-
|
|
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 (
|
|
864
|
+
if (token !== undefined && card.excerpt === undefined)
|
|
603
865
|
fail(
|
|
604
|
-
|
|
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
|
|
631
|
-
const
|
|
632
|
-
|
|
633
|
-
|
|
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
|
|
719
|
-
|
|
720
|
-
|
|
721
|
-
|
|
722
|
-
|
|
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
|
|
740
|
-
type Described = ReadonlyMap<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.
|
|
746
|
-
(
|
|
747
|
-
|
|
748
|
-
|
|
749
|
-
|
|
750
|
-
|
|
751
|
-
|
|
752
|
-
|
|
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 = (
|
|
758
|
-
|
|
1062
|
+
const rulesShown = (card: Card, described: Described) =>
|
|
1063
|
+
card.rules === undefined
|
|
759
1064
|
? {}
|
|
760
1065
|
: {
|
|
761
|
-
[RULES_FIELD]:
|
|
1066
|
+
[RULES_FIELD]: card.rules.map((r) => ({
|
|
762
1067
|
linter: r.linter,
|
|
763
1068
|
id: r.id,
|
|
764
|
-
|
|
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: {
|
|
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:
|
|
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
|
}
|