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,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
|
-
|
|
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
|
-
//
|
|
97
|
-
// the
|
|
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
|
-
: {
|
|
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
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
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
|
-
{
|
|
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
|
|
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
|
-
|
|
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
|
-
//
|
|
197
|
-
//
|
|
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(
|
|
318
|
+
practice: array(practiceSchema(kind), true, MIN_PRACTICE),
|
|
202
319
|
practice_round: integer(false),
|
|
203
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
|
427
|
-
const
|
|
428
|
-
|
|
429
|
-
|
|
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.
|
|
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(
|
|
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 = (
|
|
711
|
+
const rulesShown = (card, described) => card.rules === undefined
|
|
510
712
|
? {}
|
|
511
713
|
: {
|
|
512
|
-
[RULES_FIELD]:
|
|
714
|
+
[RULES_FIELD]: card.rules.map((r) => ({
|
|
513
715
|
linter: r.linter,
|
|
514
716
|
id: r.id,
|
|
515
|
-
|
|
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: {
|
|
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:
|
|
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. */
|