paperlint 14.0.0 → 14.2.0

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

@@ -482,3 +482,25 @@ test("🔴 familiarity off: no group asks how well it is known, and a group is d
   assert.doesNotMatch(shown, /how well you know it/);
   assert.match(shown, /Nothing left/, shown);
 });
+
+test("🔴 «All items are complete» waits for every group's familiarity too, as «Next unanswered» does", async () => {
+  const { page, key } = build(setup("all-done-groups", config()));
+  const answers = Object.fromEntries(
+    Object.keys(key.ids).map((id) => [
+      id,
+      { answers: { label: "yes", boundary: "clear" }, source: "page" },
+    ]),
+  );
+  const said = async (groups: Record<string, unknown>) =>
+    /All 12 items are complete/.test(
+      (await openLive(page, { answers, groups, practice: DONE_PRACTICE })).app
+        .textContent,
+    );
+  const rated = Object.fromEntries(
+    ["python", "go", "rust"].map((g) => [
+      g,
+      { familiarity: "well", source: "page" },
+    ]),
+  );
+  assert.deepEqual([await said({}), await said(rated)], [false, true]);
+});

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

@@ -0,0 +1,222 @@
+/**
+ * PRESETS: named, opt-in words for one narrow use of the generic content blocks. An items.json picks
+ * one by name (`"preset": "linter-config-witness"`); the preset turns its own compact card fields into
+ * the generic blocks and supplies the page's `labels`, and the items file's own `labels` override
+ * them. The core and the page know only the blocks: every word below stays in this file.
+ */
+import { z } from "zod";
+// ── linter-config-witness: two linter configs of one requirement disagree on a line of code ──────
+const LINE = z.strictObject({
+    n: z.int(),
+    text: z.string(),
+    mark: z.boolean(),
+});
+const EXAMPLE = z.strictObject({
+    file: z.string().min(1),
+    url: z.url().optional(),
+    lines: z.array(LINE).min(1),
+    message: z.string().min(1),
+    caught_by: z.enum(["a", "b"]),
+});
+const EXPLANATION = z
+    .strictObject({
+    source: z.enum([
+        "ruff rule",
+        "eslint docs",
+        "plugin docs",
+        "config message",
+        "none",
+    ]),
+    what: z.string().min(1).optional(),
+    why: z.string().min(1).optional(),
+    example_bad: z.string().min(1).optional(),
+    example_good: z.string().min(1).optional(),
+    url: z.url().optional(),
+})
+    .refine((x) => x.source === "none" || x.what !== undefined, {
+    message: "`what` is required unless `source` is 'none'",
+    path: ["what"],
+});
+const RULE = z.strictObject({
+    linter: z.string().min(1),
+    id: z.string().min(1),
+    explanation: EXPLANATION,
+});
+const SETTING = z.strictObject({
+    key: z.string().regex(/^(files|ignores|rule|option:\S+)$/u),
+    raw: z.string().min(1),
+    plain: z.string().min(1),
+    matches_example: z.boolean().nullable().optional(),
+});
+const LINTER_CARD = z.looseObject({
+    example: EXAMPLE,
+    rules: z.array(RULE).min(1),
+    more_like_this: z
+        .strictObject({ count: z.int(), files: z.array(z.string()) })
+        .optional(),
+    details: z.strictObject({
+        a: z.array(SETTING).min(1),
+        b: z.array(SETTING).min(1),
+    }),
+});
+const LINTER_LABELS = {
+    place: "Card {n} of {total}",
+    body: "Requirement",
+    line: "Where this requirement comes from (the project's rules file)",
+    line_part: "Where this requirement comes from (the project's rules file)",
+    repeat: "Card {index} of {of} for this requirement",
+    practice_example: "Example of this answer, about other code: ",
+};
+const KEY_LABEL = {
+    files: "Checks files",
+    ignores: "Leaves out",
+    rule: "Rule",
+};
+const DOCS_NOTE = "The flagged/allowed examples are the docs' own, with the docs' own settings, not this project's.";
+/** A rule as its docs explain it, as a reference entry. */
+const ruleEntry = (r) => {
+    const x = r.explanation;
+    return {
+        label: "Rule",
+        title: `${r.linter} \`${r.id}\``,
+        fields: [
+            x.source === "none"
+                ? { style: "note", text: "No official explanation for this rule." }
+                : {
+                    ...(x.source === "config message"
+                        ? { label: "The config's own message" }
+                        : {}),
+                    text: String(x.what),
+                },
+            ...(x.why === undefined ? [] : [{ label: "Why", text: x.why }]),
+            ...(x.example_bad === undefined && x.example_good === undefined
+                ? []
+                : [{ style: "note", text: DOCS_NOTE }]),
+            ...(x.example_bad === undefined
+                ? []
+                : [{ label: "Flagged", style: "code", text: x.example_bad }]),
+            ...(x.example_good === undefined
+                ? []
+                : [{ label: "Allowed", style: "code", text: x.example_good }]),
+        ],
+        ...(x.url === undefined ? {} : { url: x.url, url_label: "Rule docs" }),
+    };
+};
+/** Each glob or option on its own row: differences first (A only, B only), what both share last. */
+const settingRows = (d) => {
+    const same = (r, s) => r.key === s.key && r.raw === s.raw;
+    const onlyIn = (xs, ys) => xs.filter((r) => !ys.some((s) => same(r, s)));
+    const rows = [
+        ...onlyIn(d.a, d.b).map((r) => [r, "A only"]),
+        ...onlyIn(d.b, d.a).map((r) => [r, "B only"]),
+        ...d.a
+            .filter((r) => d.b.some((s) => same(r, s)))
+            .map((r) => [r, "A and B"]),
+    ];
+    return rows.map(([r, side]) => ({
+        label: `${side} · ${KEY_LABEL[r.key] ?? `Option ${r.key.replace(/^option:/u, "")}`}`,
+        value: r.raw,
+        plain: r.plain,
+        ...(r.matches_example === true
+            ? { mark: { tone: "yes", text: "✓ matches this file" } }
+            : r.matches_example === false
+                ? { mark: { tone: "no", text: "✗ does not match this file" } }
+                : {}),
+    }));
+};
+/** The files like this one, as a folded list; none when there are none. */
+const moreList = (more) => more === undefined || more.count === 0
+    ? {}
+    : {
+        more: {
+            summary: `${String(more.count)} more file(s) with the same situation`,
+            items: more.files.map((f) => `\`${f}\``),
+            ...(more.count > more.files.length
+                ? { rest: `and ${String(more.count - more.files.length)} more` }
+                : {}),
+        },
+    };
+/** One card in the generic blocks. */
+function linterCard(card) {
+    const { example: ex, rules, more_like_this: more, details, ...rest } = card;
+    const by = ex.caught_by === "a" ? ["A", "B"] : ["B", "A"];
+    return {
+        ...rest,
+        excerpt: {
+            file: ex.file,
+            ...(ex.url === undefined ? {} : { url: ex.url }),
+            lines: ex.lines,
+            caption: `The linter says: ${ex.message}`,
+        },
+        references: {
+            summary: rules.length > 1
+                ? "What the linter rules do (official docs)"
+                : "What the linter rule does (official docs)",
+            entries: rules.map(ruleEntry),
+        },
+        ...moreList(more),
+        table: {
+            summary: "Settings behind this card",
+            note: `Setting ${String(by[0])} flags the example line; setting ${String(by[1])} passes it.`,
+            rows: settingRows(details),
+        },
+    };
+}
+const CONFIG = z.looseObject({
+    preset: z.string(),
+    labels: z.record(z.string(), z.string()).optional(),
+    practice: z.array(z.unknown()),
+    items: z.array(z.unknown()),
+});
+const PRESETS = {
+    "linter-config-witness": {
+        labels: LINTER_LABELS,
+        card: linterCard,
+        schema: LINTER_CARD,
+    },
+};
+/** Each problem zod found, as the build's refusals read: the path, then what is wrong. */
+const issuesOf = (where, e) => e.issues
+    .map((issue) => `${where}${issue.path
+    .map((p) => typeof p === "number" ? `[${String(p)}]` : `.${String(p)}`)
+    .join("")}: ${issue.message}`)
+    .join("; ");
+/** Every card through the preset, practice first, each refused by its path. */
+const mapCards = (preset, practice, items) => [
+    ...practice.map((c, n) => [`practice[${String(n)}]`, c]),
+    ...items.map((c, n) => [`items[${String(n)}]`, c]),
+].map(([at, c]) => {
+    const r = preset.schema.safeParse(c);
+    return r.success
+        ? { ok: true, value: preset.card(r.data) }
+        : { ok: false, message: issuesOf(at, r.error) };
+});
+/** The config with its preset applied; a config without `preset` comes back as it was. */
+export function applyPreset(raw) {
+    const cfg = CONFIG.safeParse(raw);
+    if (!cfg.success)
+        return { ok: true, value: raw };
+    const { preset: name, labels, practice, items, ...rest } = cfg.data;
+    const preset = PRESETS[name];
+    if (preset === undefined)
+        return {
+            ok: false,
+            message: `preset: '${name}' is not a preset (${Object.keys(PRESETS).join(", ")})`,
+        };
+    const cards = mapCards(preset, practice, items);
+    const bad = cards.find((c) => !c.ok);
+    if (bad !== undefined)
+        return bad;
+    const made = cards
+        .filter((c) => c.ok)
+        .map((c) => c.value);
+    return {
+        ok: true,
+        value: {
+            ...rest,
+            labels: { ...preset.labels, ...labels },
+            practice: made.slice(0, practice.length),
+            items: made.slice(practice.length),
+        },
+    };
+}

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

@@ -0,0 +1,175 @@
+/**
+ * The `linter-config-witness` preset: a narrow use of the generic blocks (two linter configs of one
+ * requirement disagree on a line of code). Its words reach the page only through a page that names
+ * it, and the items file's own labels override them.
+ */
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { test } from "vitest";
+import { z } from "zod";
+import { build, run, setup, showPage } from "../../../test/label-page-kit.ts";
+
+const Fixture = z
+  .object({
+    practice: z.array(
+      z.object({ expected: z.record(z.string(), z.string()) }).loose(),
+    ),
+    items: z.array(z.record(z.string(), z.unknown())),
+  })
+  .loose();
+const FIXTURE = Fixture.parse(
+  JSON.parse(
+    readFileSync(
+      join(import.meta.dirname, "fixtures", "linter-config-witness-items.json"),
+      "utf8",
+    ),
+  ),
+);
+const preset = (
+  over: Record<string, unknown> = {},
+): Record<string, unknown> => ({ ...FIXTURE, ...over });
+const firstItem = (
+  change: (i: Record<string, unknown>) => Record<string, unknown>,
+) => preset({ items: FIXTURE.items.map((i, n) => (n === 0 ? change(i) : i)) });
+const PRACTICE_DONE = Object.fromEntries(
+  FIXTURE.practice.map((p, n) => [
+    `r1-P${String(n + 1)}`,
+    { answers: p.expected, source: "page" },
+  ]),
+);
+const [FIRST] = FIXTURE.items;
+assert.ok(FIRST !== undefined);
+const firstRule = z
+  .array(z.record(z.string(), z.unknown()))
+  .parse(FIRST["rules"])[0];
+
+const REFUSED: readonly (readonly [string, Record<string, unknown>, string])[] =
+  [
+    [
+      "preset-unknown",
+      preset({ preset: "no-such-preset" }),
+      "preset: 'no-such-preset' is not a preset (linter-config-witness)",
+    ],
+    [
+      "preset-no-explanation",
+      firstItem((i) => ({ ...i, rules: [{ linter: "ruff", id: "T201" }] })),
+      "items[0].rules[0].explanation: Invalid input: expected object, received undefined",
+    ],
+    [
+      "preset-explanation-empty",
+      firstItem((i) => ({
+        ...i,
+        rules: [{ ...firstRule, explanation: { source: "ruff rule" } }],
+      })),
+      "items[0].rules[0].explanation.what: `what` is required unless `source` is 'none'",
+    ],
+  ];
+
+test("🔴 the preset refuses an unknown name and, by path, a card it cannot map", () => {
+  assert.deepEqual(
+    REFUSED.map(([name, cfg]) => {
+      const dir = setup(name, cfg);
+      return run(["build", join(dir, "items.json"), join(dir, "out")]);
+    }),
+    REFUSED.map(([, , message]) => ({
+      status: 1,
+      out: `REFUSED: ${message}\n`,
+    })),
+  );
+});
+
+/** `text` with every given part present, in this order. */
+const inOrder = (text: string, parts: readonly string[]): readonly string[] => {
+  const at = parts.map((p) => text.indexOf(p));
+  return parts.filter(
+    (p, n) => at[n] === -1 || (at[n - 1] ?? -1) > (at[n] ?? 0),
+  );
+};
+
+test("🔴 a page naming the preset shows its words on the generic blocks: the linter's message, the rule's docs folded with the docs-examples note, the files like it, and the settings with their sides", async () => {
+  const { page, key } = build(setup("preset-face", preset()));
+  const shown = await showPage(page, {}, {}, PRACTICE_DONE);
+  const id = Object.entries(key.ids).find(
+    ([, v]) => v.source_id === "req-logging:tests",
+  )?.[0];
+  assert.ok(id !== undefined);
+  const card = shown.slice(
+    shown.indexOf(`\nCard ${String(Number(id.slice(1)))} of 3`),
+  );
+  assert.deepEqual(
+    inOrder(card, [
+      "Requirement",
+      "Never log with",
+      "Card 1 of 2 for this requirement",
+      "One setting checks the scripts/ folder",
+      "scripts/seed_db.py",
+      "◀ this line",
+      "The linter says:",
+      "Should this requirement apply to the scripts/ folder?",
+      "What the linter rule does (official docs)",
+      "Rule",
+      "ruff",
+      "T201",
+      "Why:",
+      "The flagged/allowed examples are the docs' own, with the docs' own settings, not this project's.",
+      "Flagged",
+      "Allowed",
+      "Rule docs",
+      "3 more file(s) with the same situation",
+      "scripts/backfill_prices.py",
+      "and 1 more",
+      "Settings behind this card",
+      "Setting B flags the example line; setting A passes it.",
+      "A only · Leaves out",
+      "except the files under scripts/",
+      "✓ matches this file",
+      "A and B · Rule",
+      "flags every call to",
+    ]),
+    [],
+  );
+  assert.match(shown, /No official explanation for this rule\./);
+  const open = await showPage(page, {}, {}, {});
+  assert.match(shown, /✗ does not match this file/);
+  assert.match(
+    open,
+    /Example of this answer, about other code: \n?«Use/,
+    "a practice button's example says it is about other code",
+  );
+});
+
+test("a card naming two rules folds their docs under one plural heading", async () => {
+  const two = firstItem((i) => ({
+    ...i,
+    rules: [firstRule, { ...firstRule, id: "T203" }],
+  }));
+  const { page } = build(setup("preset-two-rules", two));
+  const shown = await showPage(page, {}, {}, PRACTICE_DONE);
+  assert.deepEqual(
+    [
+      shown.includes("What the linter rules do (official docs)"),
+      shown.includes("T203"),
+    ],
+    [true, true],
+  );
+});
+
+test("🔴 the items file's own labels override the preset's", async () => {
+  const { page } = build(
+    setup(
+      "preset-override",
+      preset({ labels: { body: "Rule text", place: "#{n}" } }),
+    ),
+  );
+  const shown = await showPage(page, {}, {}, PRACTICE_DONE);
+  assert.deepEqual(
+    [
+      shown.includes("Rule text"),
+      shown.includes("\nRequirement\n"),
+      /\n#1\n/.test(shown),
+      shown.includes("Card 1 of 2 for this requirement"),
+    ],
+    [true, false, true, true],
+  );
+});

package/skills/build-label-page/scripts/label-page-presets.ts

@@ -0,0 +1,257 @@
+/**
+ * PRESETS: named, opt-in words for one narrow use of the generic content blocks. An items.json picks
+ * one by name (`"preset": "linter-config-witness"`); the preset turns its own compact card fields into
+ * the generic blocks and supplies the page's `labels`, and the items file's own `labels` override
+ * them. The core and the page know only the blocks: every word below stays in this file.
+ */
+import { z } from "zod";
+
+/** A preset's result: the config in the generic shape, or why it cannot be made. */
+export type Preset =
+  | { readonly ok: true; readonly value: unknown }
+  | { readonly ok: false; readonly message: string };
+
+// ── linter-config-witness: two linter configs of one requirement disagree on a line of code ──────
+const LINE = z.strictObject({
+  n: z.int(),
+  text: z.string(),
+  mark: z.boolean(),
+});
+const EXAMPLE = z.strictObject({
+  file: z.string().min(1),
+  url: z.url().optional(),
+  lines: z.array(LINE).min(1),
+  message: z.string().min(1),
+  caught_by: z.enum(["a", "b"]),
+});
+const EXPLANATION = z
+  .strictObject({
+    source: z.enum([
+      "ruff rule",
+      "eslint docs",
+      "plugin docs",
+      "config message",
+      "none",
+    ]),
+    what: z.string().min(1).optional(),
+    why: z.string().min(1).optional(),
+    example_bad: z.string().min(1).optional(),
+    example_good: z.string().min(1).optional(),
+    url: z.url().optional(),
+  })
+  .refine((x) => x.source === "none" || x.what !== undefined, {
+    message: "`what` is required unless `source` is 'none'",
+    path: ["what"],
+  });
+const RULE = z.strictObject({
+  linter: z.string().min(1),
+  id: z.string().min(1),
+  explanation: EXPLANATION,
+});
+const SETTING = z.strictObject({
+  key: z.string().regex(/^(files|ignores|rule|option:\S+)$/u),
+  raw: z.string().min(1),
+  plain: z.string().min(1),
+  matches_example: z.boolean().nullable().optional(),
+});
+const LINTER_CARD = z.looseObject({
+  example: EXAMPLE,
+  rules: z.array(RULE).min(1),
+  more_like_this: z
+    .strictObject({ count: z.int(), files: z.array(z.string()) })
+    .optional(),
+  details: z.strictObject({
+    a: z.array(SETTING).min(1),
+    b: z.array(SETTING).min(1),
+  }),
+});
+type LinterCard = z.infer<typeof LINTER_CARD>;
+type Setting = z.infer<typeof SETTING>;
+
+const LINTER_LABELS = {
+  place: "Card {n} of {total}",
+  body: "Requirement",
+  line: "Where this requirement comes from (the project's rules file)",
+  line_part: "Where this requirement comes from (the project's rules file)",
+  repeat: "Card {index} of {of} for this requirement",
+  practice_example: "Example of this answer, about other code: ",
+};
+const KEY_LABEL: Readonly<Record<string, string>> = {
+  files: "Checks files",
+  ignores: "Leaves out",
+  rule: "Rule",
+};
+const DOCS_NOTE =
+  "The flagged/allowed examples are the docs' own, with the docs' own settings, not this project's.";
+
+/** A rule as its docs explain it, as a reference entry. */
+const ruleEntry = (r: LinterCard["rules"][number]) => {
+  const x = r.explanation;
+  return {
+    label: "Rule",
+    title: `${r.linter} \`${r.id}\``,
+    fields: [
+      x.source === "none"
+        ? { style: "note", text: "No official explanation for this rule." }
+        : {
+            ...(x.source === "config message"
+              ? { label: "The config's own message" }
+              : {}),
+            text: String(x.what),
+          },
+      ...(x.why === undefined ? [] : [{ label: "Why", text: x.why }]),
+      ...(x.example_bad === undefined && x.example_good === undefined
+        ? []
+        : [{ style: "note", text: DOCS_NOTE }]),
+      ...(x.example_bad === undefined
+        ? []
+        : [{ label: "Flagged", style: "code", text: x.example_bad }]),
+      ...(x.example_good === undefined
+        ? []
+        : [{ label: "Allowed", style: "code", text: x.example_good }]),
+    ],
+    ...(x.url === undefined ? {} : { url: x.url, url_label: "Rule docs" }),
+  };
+};
+/** Each glob or option on its own row: differences first (A only, B only), what both share last. */
+const settingRows = (d: LinterCard["details"]) => {
+  const same = (r: Setting, s: Setting) => r.key === s.key && r.raw === s.raw;
+  const onlyIn = (xs: readonly Setting[], ys: readonly Setting[]) =>
+    xs.filter((r) => !ys.some((s) => same(r, s)));
+  const rows: readonly (readonly [Setting, string])[] = [
+    ...onlyIn(d.a, d.b).map((r) => [r, "A only"] as const),
+    ...onlyIn(d.b, d.a).map((r) => [r, "B only"] as const),
+    ...d.a
+      .filter((r) => d.b.some((s) => same(r, s)))
+      .map((r) => [r, "A and B"] as const),
+  ];
+  return rows.map(([r, side]) => ({
+    label: `${side} · ${KEY_LABEL[r.key] ?? `Option ${r.key.replace(/^option:/u, "")}`}`,
+    value: r.raw,
+    plain: r.plain,
+    ...(r.matches_example === true
+      ? { mark: { tone: "yes", text: "✓ matches this file" } }
+      : r.matches_example === false
+        ? { mark: { tone: "no", text: "✗ does not match this file" } }
+        : {}),
+  }));
+};
+/** The files like this one, as a folded list; none when there are none. */
+const moreList = (more: LinterCard["more_like_this"]) =>
+  more === undefined || more.count === 0
+    ? {}
+    : {
+        more: {
+          summary: `${String(more.count)} more file(s) with the same situation`,
+          items: more.files.map((f) => `\`${f}\``),
+          ...(more.count > more.files.length
+            ? { rest: `and ${String(more.count - more.files.length)} more` }
+            : {}),
+        },
+      };
+/** One card in the generic blocks. */
+function linterCard(card: LinterCard): Record<string, unknown> {
+  const { example: ex, rules, more_like_this: more, details, ...rest } = card;
+  const by = ex.caught_by === "a" ? ["A", "B"] : ["B", "A"];
+  return {
+    ...rest,
+    excerpt: {
+      file: ex.file,
+      ...(ex.url === undefined ? {} : { url: ex.url }),
+      lines: ex.lines,
+      caption: `The linter says: ${ex.message}`,
+    },
+    references: {
+      summary:
+        rules.length > 1
+          ? "What the linter rules do (official docs)"
+          : "What the linter rule does (official docs)",
+      entries: rules.map(ruleEntry),
+    },
+    ...moreList(more),
+    table: {
+      summary: "Settings behind this card",
+      note: `Setting ${String(by[0])} flags the example line; setting ${String(by[1])} passes it.`,
+      rows: settingRows(details),
+    },
+  };
+}
+
+const CONFIG = z.looseObject({
+  preset: z.string(),
+  labels: z.record(z.string(), z.string()).optional(),
+  practice: z.array(z.unknown()),
+  items: z.array(z.unknown()),
+});
+const PRESETS: Readonly<
+  Record<
+    string,
+    {
+      readonly labels: Readonly<Record<string, string>>;
+      readonly card: (c: LinterCard) => Record<string, unknown>;
+      readonly schema: typeof LINTER_CARD;
+    }
+  >
+> = {
+  "linter-config-witness": {
+    labels: LINTER_LABELS,
+    card: linterCard,
+    schema: LINTER_CARD,
+  },
+};
+
+/** Each problem zod found, as the build's refusals read: the path, then what is wrong. */
+const issuesOf = (where: string, e: z.ZodError): string =>
+  e.issues
+    .map(
+      (issue) =>
+        `${where}${issue.path
+          .map((p) =>
+            typeof p === "number" ? `[${String(p)}]` : `.${String(p)}`,
+          )
+          .join("")}: ${issue.message}`,
+    )
+    .join("; ");
+
+/** Every card through the preset, practice first, each refused by its path. */
+const mapCards = (
+  preset: (typeof PRESETS)[string],
+  practice: readonly unknown[],
+  items: readonly unknown[],
+): readonly Preset[] =>
+  [
+    ...practice.map((c, n) => [`practice[${String(n)}]`, c] as const),
+    ...items.map((c, n) => [`items[${String(n)}]`, c] as const),
+  ].map(([at, c]) => {
+    const r = preset.schema.safeParse(c);
+    return r.success
+      ? { ok: true, value: preset.card(r.data) }
+      : { ok: false, message: issuesOf(at, r.error) };
+  });
+/** The config with its preset applied; a config without `preset` comes back as it was. */
+export function applyPreset(raw: unknown): Preset {
+  const cfg = CONFIG.safeParse(raw);
+  if (!cfg.success) return { ok: true, value: raw };
+  const { preset: name, labels, practice, items, ...rest } = cfg.data;
+  const preset = PRESETS[name];
+  if (preset === undefined)
+    return {
+      ok: false,
+      message: `preset: '${name}' is not a preset (${Object.keys(PRESETS).join(", ")})`,
+    };
+  const cards = mapCards(preset, practice, items);
+  const bad = cards.find((c) => !c.ok);
+  if (bad !== undefined) return bad;
+  const made = cards
+    .filter((c): c is Extract<Preset, { ok: true }> => c.ok)
+    .map((c) => c.value);
+  return {
+    ok: true,
+    value: {
+      ...rest,
+      labels: { ...preset.labels, ...labels },
+      practice: made.slice(0, practice.length),
+      items: made.slice(practice.length),
+    },
+  };
+}