paperlint 14.0.0 → 14.1.0

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

@@ -9,6 +9,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { z } from "zod";
 import { describeRule, } from "./rule-descriptions.js";
+import { applyPreset } from "./label-page-presets.js";
 // ── refusals and output ───────────────────────────────────────────────────────────────────────
 export class Refusal extends Error {
     exitCode;
@@ -74,6 +75,11 @@ const writeJson = (path, value) => {
     writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`, "utf8");
 };
 const JSON_VALUE = z.json();
+/** The config with its named preset applied (label-page-presets.ts), refused by path. */
+const withPreset = (raw) => {
+    const r = applyPreset(raw);
+    return r.ok ? JSON_VALUE.parse(r.value) : fail(r.message);
+};
 const readJson = (path) => {
     try {
         return JSON_VALUE.parse(JSON.parse(readFileSync(path, "utf8")));
@@ -99,11 +105,22 @@ const RULES_FIELD = "rules";
 const UNIT_FIELD = "unit";
 // Two readings of one requirement, shown as rows A and B (#374).
 const READINGS_FIELD = "readings";
+// Content blocks (#380): generic, on any kind. Every label and sentence a block shows comes from
+// items.json (or a preset, label-page-presets.ts); the page knows only the block's shape.
+const BLOCK_FIELDS = [
+    "situation",
+    "excerpt",
+    "references",
+    "more",
+    "table",
+    "repeat",
+];
 const ALLOWED_FIELDS = [
     ...PAGE_FIELDS,
     RULES_FIELD,
     UNIT_FIELD,
     READINGS_FIELD,
+    ...BLOCK_FIELDS,
     ...PRIVATE_FIELDS,
 ];
 const FAMILIARITY = [
@@ -140,6 +157,8 @@ const string = (required = true, pattern, why) => pattern === undefined
         pattern,
         ...(why === undefined ? {} : { why }),
     };
+/** A string that may be empty: a blank line of code. */
+const text = () => ({ kind: "text", required: true });
 const integer = (required = true) => ({
     kind: "integer",
     required,
@@ -164,6 +183,13 @@ const mapping = (values, keyPattern, min = 0) => ({
 const obj = (fields, closed = true, required = true) => ({ kind: "object", required, closed, fields });
 // What an item and a practice item both may carry beyond text: a practice card looks like the real
 // cards it rehearses. Each is optional here; a page's `kind` makes some of them required (KINDS).
+const LINK = string(false, "https?://\\S+", "an http(s) link");
+const optional = (fields) => obj(fields, true, false);
+const TEXT_FIELD = obj({
+    label: string(false),
+    text: string(),
+    style: string(false, "code|note", "code or note"),
+});
 const CARD_FIELDS = {
     [RULES_FIELD]: array(obj({
         linter: string(true, "eslint|ruff", "eslint or ruff"),
@@ -180,6 +206,43 @@ const CARD_FIELDS = {
     }, true, false),
     [READINGS_FIELD]: obj({ a: string(), b: string() }, true, false),
     file: string(false),
+    situation: optional({ summary: string(), question: string() }),
+    excerpt: optional({
+        file: string(false),
+        url: LINK,
+        lines: array(obj({ n: integer(), text: text(), mark: boolean() }), true, 1),
+        caption: string(false),
+        mark_label: string(false),
+    }),
+    references: optional({
+        summary: string(),
+        entries: array(obj({
+            label: string(false),
+            title: string(),
+            fields: array(TEXT_FIELD, true, 1),
+            url: LINK,
+            url_label: string(false),
+        }), true, 1),
+    }),
+    more: optional({
+        summary: string(),
+        items: array(string(), true, 1),
+        rest: string(false),
+    }),
+    table: optional({
+        summary: string(),
+        note: string(false),
+        rows: array(obj({
+            label: string(),
+            value: string(),
+            plain: string(false),
+            mark: optional({
+                tone: string(true, "yes|no", "yes or no"),
+                text: string(),
+            }),
+        }), true, 1),
+    }),
+    repeat: optional({ group: string(), index: integer(), of: integer() }),
 };
 const KINDS = {
     // keep or drop a drawn requirement: the line it came from, marked, and the rule read for it
@@ -254,6 +317,15 @@ const configSchema = (kind) => obj({
     questions: array(QUESTION_SCHEMA, true, 1),
     practice: array(practiceSchema(kind), true, MIN_PRACTICE),
     practice_round: integer(false),
+    // Page-level words the blocks use (references/closed-choice-generator.md §«Content blocks»).
+    labels: optional({
+        place: string(false),
+        body: string(false),
+        line: string(false),
+        line_part: string(false),
+        repeat: string(false),
+        practice_example: string(false),
+    }),
     items: array(itemSchema(kind), true, 1),
 });
 /** The declared schema (`schema` prints it): every field, those a kind requires left optional. */
@@ -310,6 +382,14 @@ function checkBoolean(value, where) {
     if (typeof value !== "boolean")
         fail(`${where}: must be true or false, got ${repr(value)}`);
 }
+/** A string that may be empty (a blank line of code), or an integer. */
+function checkScalar(value, kind, where) {
+    if (kind === "text" && typeof value !== "string")
+        fail(`${where}: must be a string, got ${repr(value)}`);
+    if (kind === "integer" &&
+        (typeof value !== "number" || !Number.isInteger(value)))
+        fail(`${where}: must be an integer, got ${repr(value)}`);
+}
 /** Refuse the first place `value` departs from `node`; the message starts with the field's path. */
 function checkValue(value, node, path) {
     const where = path || "items.json";
@@ -317,10 +397,9 @@ function checkValue(value, node, path) {
         case "string":
             checkString(value, node, where);
             break;
+        case "text":
         case "integer":
-            if (typeof value !== "number" || !Number.isInteger(value)) {
-                fail(`${where}: must be an integer, got ${repr(value)}`);
-            }
+            checkScalar(value, node.kind, where);
             break;
         case "boolean":
             checkBoolean(value, where);
@@ -469,6 +548,33 @@ function checkUnits(cfg) {
         });
     }
 }
+/**
+ * A situation's sentence or question may name the excerpt's marked line as `{line}`: the page writes
+ * «line N: » and the line's code there, so a question sits next to the code it is about.
+ */
+const LINE_TOKEN = "{line}";
+const SITUATION_TEXTS = ["summary", "question"];
+/** The line `{line}` stands for: the first marked line, its number and its code without the indent. */
+const lineOf = (card) => card.excerpt?.lines
+    .filter((l) => l.mark)
+    .map((l) => ({ n: l.n, text: l.text.trim() }))[0];
+const usesLine = (card) => SITUATION_TEXTS.some((f) => card.situation?.[f].includes(LINE_TOKEN));
+/**
+ * What the block schema cannot say: an excerpt marks a line, `{line}` has a marked line to stand for,
+ * and a repeat sits inside its count.
+ */
+function checkBlocks(cfg) {
+    cardsOf(cfg).forEach(([at, card]) => {
+        if (card.excerpt !== undefined && !card.excerpt.lines.some((l) => l.mark))
+            fail(`${at}.excerpt.lines: no line is marked — mark the line the card is about (\`mark: true\`)`);
+        const token = SITUATION_TEXTS.find((f) => card.situation?.[f].includes(LINE_TOKEN));
+        if (token !== undefined && card.excerpt === undefined)
+            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}\``);
+        const r = card.repeat;
+        if (r !== undefined && (r.index < 1 || r.index > r.of))
+            fail(`${at}.repeat.index: ${String(r.index)} is not between 1 and ${String(r.of)}`);
+    });
+}
 /** Every card of the config, items then practice, by path. */
 const cardsOf = (cfg) => [
     ...cfg.items.map((i, n) => [`items[${String(n)}]`, i]),
@@ -490,12 +596,22 @@ function checkItemFields(cfg) {
             fail(`items[${String(n)}].group: ${repr(item.group)} is not in \`groups\``);
     });
 }
-/** Every text of an item the labeller sees, by field: the page fields and the line of a unit. */
-const visibleTexts = (item) => [
-    ...PAGE_FIELDS.map((f) => [f, item[f] ?? ""]),
-    [UNIT_FIELD, item.unit?.text ?? ""],
-    [READINGS_FIELD, `${item.readings?.a ?? ""} ${item.readings?.b ?? ""}`],
-];
+/** Every string inside a value: each is tested on its own, as the page renders it, never a serialisation. */
+const stringsIn = (v) => typeof v === "string"
+    ? [v]
+    : Array.isArray(v)
+        ? v.flatMap(stringsIn)
+        : typeof v === "object" && v !== null
+            ? Object.values(v).flatMap(stringsIn)
+            : [];
+/**
+ * Every text of an item the labeller sees, by field: each string the page shows (the fields as
+ * `shownFields` passes them, so a repeat without its group), and every rule it names.
+ */
+const visibleTexts = (item) => Object.entries({
+    ...shownFields(item),
+    [RULES_FIELD]: item.rules ?? [],
+}).flatMap(([f, v]) => stringsIn(v).map((t) => [f, t]));
 const escapeRegExp = (s) => s.replace(/[\\^$.*+?()[\]{}|/]/g, "\\$&");
 /**
  * A source id typed into a visible field gives the source away as well as a field would. Short ids
@@ -549,6 +665,17 @@ function assignIds(items, seed, keyPath) {
     ]);
     return { ids, entries };
 }
+// ── a build, short of the page ──────────────────────────────────────────────────────────────────
+/** A card's situation as the page shows it, with the line `{line}` stands for. */
+const situationShown = (item) => item.situation === undefined
+    ? {}
+    : {
+        situation: {
+            summary: item.situation.summary,
+            question: item.situation.question,
+            ...(usesLine(item) ? { line: lineOf(item) } : {}),
+        },
+    };
 const shownFields = (item) => ({
     ...Object.fromEntries(PAGE_FIELDS.flatMap((f) => {
         const v = item[f];
@@ -565,15 +692,20 @@ const shownFields = (item) => ({
             },
         }),
     ...(item.readings === undefined ? {} : { [READINGS_FIELD]: item.readings }),
+    ...Object.fromEntries(BLOCK_FIELDS.filter((f) => f !== "repeat" && f !== "situation").flatMap((f) => (item[f] === undefined ? [] : [[f, item[f]]]))),
+    ...situationShown(item),
+    ...(item.repeat === undefined
+        ? {}
+        : { repeat: { index: item.repeat.index, of: item.repeat.of } }),
 });
 const ruleKey = (r) => `${r.linter} ${r.id}`;
 /** Ask the linter for every rule named; refuse, by path, a rule it cannot describe. */
 function describeRules(cfg, fromDir) {
-    return new Map(cardsOf(cfg).flatMap(([at, card]) => (card.rules ?? []).map((r, k) => {
+    return new Map(cardsOf(cfg).flatMap(([at, card]) => (card.rules ?? []).flatMap((r, k) => {
         const text = describeRule(r, fromDir);
         return text === undefined
             ? fail(`${at}.rules[${String(k)}]: ${r.linter} ${repr(r.id)} has no description from the linter (${r.linter === "ruff" ? "`ruff rule` does not know it, or ruff is not on PATH" : "not a rule of the ESLint, or of a plugin, installed where items.json is"}) — check the id`)
-            : [ruleKey(r), text];
+            : [[ruleKey(r), text]];
     })));
 }
 const rulesShown = (card, described) => card.rules === undefined
@@ -606,12 +738,21 @@ const practiceShown = (cfg, described) => practiceOf(cfg).map((p) => ({
     ...shownFields(p),
     ...rulesShown(p, described),
 }));
+/** The page's own words where `labels` leaves one out (references/closed-choice-generator.md). */
+const DEFAULT_LABELS = {
+    place: "{id} · {n} of {total}",
+    line: "Line",
+    line_part: "{line} · part {part} of {of}",
+    repeat: "Card {index} of {of}",
+    practice_example: "",
+};
 /** What a page shows: the questions, the practice and the items, blind, with their neutral ids. */
 function payloadOf(cfg, page, described) {
     const used = Object.keys(cfg.groups).filter((g) => page.items.some((i) => i.group === g));
     return {
         title: cfg.title,
         intro: cfg.intro ?? "",
+        labels: { ...DEFAULT_LABELS, ...cfg.labels },
         groups: used.map((g) => ({ id: g, label: String(cfg.groups[g]) })),
         familiarity_question: asksFamiliarity(cfg)
             ? (cfg.familiarity_question ?? "How well do you know {group}?")
@@ -689,13 +830,14 @@ function keyOf(cfg, page, earlier) {
  * returns what the page shows. A page written by hand can take its blindness and its key from here.
  */
 export function prepareBuild(configPath, outDir) {
-    const cfg = readJson(configPath);
+    const cfg = withPreset(readJson(configPath));
     assertConfig(cfg);
     // Once its `kind` is known to be one, the fields that kind needs on every card.
     checkValue(cfg, configSchema(cfg.kind), "");
     checkConfig(cfg);
     checkItemFields(cfg);
     checkUnits(cfg);
+    checkBlocks(cfg);
     checkNoSourceShown(cfg);
     const described = describeRules(cfg, dirname(configPath));
     mkdirSync(outDir, { recursive: true });

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

@@ -29,7 +29,15 @@ import {
 /** A node of the declared config schema, as `example-generator.py schema` prints it. */
 const Node: z.ZodType<SchemaNode> = z.lazy(() =>
   z.object({
-    kind: z.enum(["string", "integer", "boolean", "map", "array", "object"]),
+    kind: z.enum([
+      "string",
+      "text",
+      "integer",
+      "boolean",
+      "map",
+      "array",
+      "object",
+    ]),
     required: z.boolean(),
     pattern: z.string().optional(),
     key_pattern: z.string().optional(),
@@ -42,7 +50,8 @@ const Node: z.ZodType<SchemaNode> = z.lazy(() =>
 );
 
 interface SchemaNode {
-  readonly kind: "string" | "integer" | "boolean" | "map" | "array" | "object";
+  readonly kind:
+    "string" | "text" | "integer" | "boolean" | "map" | "array" | "object";
   readonly required: boolean;
   readonly pattern?: string | undefined;
   readonly key_pattern?: string | undefined;
@@ -73,6 +82,40 @@ const CARD = {
   rules: [{ linter: "eslint", id: "no-console" }],
   unit: { id: "L0", text: "One line.", mark: "One", part: 1, of: 1 },
   readings: { a: "on", b: "off" },
+  situation: { summary: "S", question: "Q?" },
+  excerpt: {
+    file: "src/a.ts",
+    url: "https://example.com/a.ts",
+    lines: [{ n: 1, text: "", mark: true }],
+    caption: "C",
+    mark_label: "M",
+  },
+  references: {
+    summary: "S",
+    entries: [
+      {
+        label: "L",
+        title: "T",
+        fields: [{ label: "F", text: "X", style: "code" }],
+        url: "https://example.com/r",
+        url_label: "U",
+      },
+    ],
+  },
+  more: { summary: "S", items: ["`src/b.ts`"], rest: "R" },
+  table: {
+    summary: "S",
+    note: "N",
+    rows: [
+      {
+        label: "L",
+        value: "V",
+        plain: "P",
+        mark: { tone: "yes", text: "Y" },
+      },
+    ],
+  },
+  repeat: { group: "g", index: 1, of: 1 },
 };
 /** A config with EVERY optional field present, so every schema path has a value to spoil. */
 const FULL: DocObject = (() => {
@@ -92,6 +135,14 @@ const FULL: DocObject = (() => {
       labeller_knows: ["python", "go", "rust"],
       familiarity: true,
       familiarity_question: "How well do you know {group}?",
+      labels: {
+        place: "C",
+        body: "B",
+        line: "L",
+        line_part: "{line} {part}/{of}",
+        repeat: "R",
+        practice_example: "P",
+      },
       practice: PRACTICE.map((p, n) => (n === 0 ? { ...p, ...CARD } : p)),
       items: ITEMS.map((i, n) => (n === 0 ? { ...i, ...CARD } : i)),
     }),
@@ -187,6 +238,7 @@ function spoil(path: string, bad: Doc | undefined): DocObject {
 
 const WRONG_TYPES: Readonly<Record<SchemaNode["kind"], readonly Doc[]>> = {
   string: [null, 1, true, ["x"], {}, "", "   "],
+  text: [null, 1, true, ["x"], {}],
   integer: [null, "7", true, 7.5, []],
   boolean: [null, "false", 0, [], {}],
   map: [null, "x", ["x"], 1],