paperlint 14.0.0 → 14.1.0

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

@@ -13,6 +13,7 @@ import {
   type Described as RuleText,
   type RuleRef,
 } from "./rule-descriptions.ts";
+import { applyPreset } from "./label-page-presets.ts";
 
 // ── refusals and output ───────────────────────────────────────────────────────────────────────
 export class Refusal extends Error {
@@ -83,6 +84,11 @@ const writeJson = (path: string, value: unknown): void => {
   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: Json): Json => {
+  const r = applyPreset(raw);
+  return r.ok ? JSON_VALUE.parse(r.value) : fail(r.message);
+};
 const readJson = (path: string): Json => {
   try {
     return JSON_VALUE.parse(JSON.parse(readFileSync(path, "utf8")));
@@ -108,11 +114,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",
+] as const;
 const ALLOWED_FIELDS: readonly string[] = [
   ...PAGE_FIELDS,
   RULES_FIELD,
   UNIT_FIELD,
   READINGS_FIELD,
+  ...BLOCK_FIELDS,
   ...PRIVATE_FIELDS,
 ];
 
@@ -152,6 +169,7 @@ const SOURCES_SHOWN = `(${SOURCES.map(quoted).join(", ")})`;
 // refusal, what a value must be (a pattern) or why a field is required (a page kind needs it).
 type SchemaNode = (
   | { kind: "string"; required: boolean; pattern?: string }
+  | { kind: "text"; required: boolean }
   | { kind: "integer"; required: boolean }
   | { kind: "boolean"; required: boolean }
   | { kind: "array"; required: boolean; min: number; items: SchemaNode }
@@ -179,6 +197,8 @@ const string = (required = true, pattern?: string, why?: string): SchemaNode =>
         pattern,
         ...(why === undefined ? {} : { why }),
       };
+/** A string that may be empty: a blank line of code. */
+const text = (): SchemaNode => ({ kind: "text", required: true });
 const integer = (required = true): SchemaNode => ({
   kind: "integer",
   required,
@@ -212,6 +232,14 @@ const obj = (
 
 // 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: Readonly<Record<string, SchemaNode>>): SchemaNode =>
+  obj(fields, true, false);
+const TEXT_FIELD = obj({
+  label: string(false),
+  text: string(),
+  style: string(false, "code|note", "code or note"),
+});
 const CARD_FIELDS: Readonly<Record<string, SchemaNode>> = {
   [RULES_FIELD]: array(
     obj({
@@ -235,6 +263,51 @@ const CARD_FIELDS: Readonly<Record<string, SchemaNode>> = {
   ),
   [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() }),
 };
 /**
  * THE PAGE KINDS, and the card fields each requires on every item and practice card (#373). A fix to
@@ -331,6 +404,15 @@ const configSchema = (kind: Kind): SchemaNode =>
     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. */
@@ -412,6 +494,20 @@ function checkBoolean(value: Json, where: string): void {
   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: Json,
+  kind: "text" | "integer",
+  where: string,
+): void {
+  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: Json, node: SchemaNode, path: string): void {
   const where = path || "items.json";
@@ -419,10 +515,9 @@ function checkValue(value: Json, node: SchemaNode, path: string): void {
     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);
@@ -459,15 +554,66 @@ interface Unit {
   readonly part: number;
   readonly of: number;
 }
+interface TextField {
+  readonly label?: string;
+  readonly text: string;
+  readonly style?: string;
+}
+interface CodeLine {
+  readonly n: number;
+  readonly text: string;
+  readonly mark: boolean;
+}
+/** The content blocks (#380), each optional on any kind. */
+interface Blocks {
+  readonly situation?: { readonly summary: string; readonly question: string };
+  readonly excerpt?: {
+    readonly file?: string;
+    readonly url?: string;
+    readonly lines: readonly CodeLine[];
+    readonly caption?: string;
+    readonly mark_label?: string;
+  };
+  readonly references?: {
+    readonly summary: string;
+    readonly entries: readonly {
+      readonly label?: string;
+      readonly title: string;
+      readonly fields: readonly TextField[];
+      readonly url?: string;
+      readonly url_label?: string;
+    }[];
+  };
+  readonly more?: {
+    readonly summary: string;
+    readonly items: readonly string[];
+    readonly rest?: string;
+  };
+  readonly table?: {
+    readonly summary: string;
+    readonly note?: string;
+    readonly rows: readonly {
+      readonly label: string;
+      readonly value: string;
+      readonly plain?: string;
+      readonly mark?: { readonly tone: string; readonly text: string };
+    }[];
+  };
+  readonly repeat?: {
+    readonly group: string;
+    readonly index: number;
+    readonly of: number;
+  };
+}
 /** What a card shows, on an item and on a practice item alike. */
 type Card = {
   readonly [F in (typeof PAGE_FIELDS)[number]]?: string;
-} & {
-  readonly body: string;
-  readonly rules?: readonly RuleRef[];
-  readonly unit?: Unit;
-  readonly readings?: { readonly a: string; readonly b: string };
-};
+} & Blocks & {
+    readonly body: string;
+    readonly rules?: readonly RuleRef[];
+    readonly unit?: Unit;
+    readonly readings?: { readonly a: string; readonly b: string };
+  };
 type Item = Card & { readonly source_id: string; readonly group: string };
 type Practice = Card & {
   readonly expected: Readonly<Record<string, string>>;
@@ -486,6 +632,7 @@ interface Config {
   readonly questions: readonly Question[];
   readonly practice: readonly Practice[];
   readonly practice_round?: number;
+  readonly labels?: Readonly<Record<string, string>>;
   readonly items: readonly Item[];
 }
 /** The config is typed by passing CONFIG_SCHEMA: `checkValue` refuses (throws) on any departure. */
@@ -688,6 +835,43 @@ function checkUnits(cfg: Config): void {
     });
   }
 }
+/**
+ * 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"] as const;
+/** The line `{line}` stands for: the first marked line, its number and its code without the indent. */
+const lineOf = (card: Card) =>
+  card.excerpt?.lines
+    .filter((l) => l.mark)
+    .map((l) => ({ n: l.n, text: l.text.trim() }))[0];
+const usesLine = (card: Card): boolean =>
+  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: Config): void {
+  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: Config) => [
   ...cfg.items.map((i, n) => [`items[${String(n)}]`, i] as const),
@@ -715,12 +899,24 @@ function checkItemFields(cfg: Config): void {
       );
   });
 }
-/** Every text of an item the labeller sees, by field: the page fields and the line of a unit. */
-const visibleTexts = (item: Item): readonly (readonly [string, string])[] => [
-  ...PAGE_FIELDS.map((f): readonly [string, string] => [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: unknown): readonly string[] =>
+  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: Item): readonly (readonly [string, string])[] =>
+  Object.entries({
+    ...shownFields(item),
+    [RULES_FIELD]: item.rules ?? [],
+  }).flatMap(([f, v]) => stringsIn(v).map((t) => [f, t] as const));
 const escapeRegExp = (s: string): string =>
   s.replace(/[\\^$.*+?()[\]{}|/]/g, "\\$&");
 /**
@@ -804,13 +1000,18 @@ function assignIds(
 }
 
 // ── a build, short of the page ──────────────────────────────────────────────────────────────────
-/** A unit as the page shows it: the line, its mark and its part, without the line's private id. */
-type ShownUnit = Omit<Unit, "id">;
-const shownFields = (
-  item: Card,
-): Readonly<
-  Record<string, string | ShownUnit | NonNullable<Card["readings"]>>
-> => ({
+/** A card's situation as the page shows it, with the line `{line}` stands for. */
+const situationShown = (item: Card) =>
+  item.situation === undefined
+    ? {}
+    : {
+        situation: {
+          summary: item.situation.summary,
+          question: item.situation.question,
+          ...(usesLine(item) ? { line: lineOf(item) } : {}),
+        },
+      };
+const shownFields = (item: Card): Readonly<Record<string, unknown>> => ({
   ...Object.fromEntries(
     PAGE_FIELDS.flatMap((f) => {
       const v = item[f];
@@ -828,6 +1029,15 @@ const shownFields = (
         },
       }),
   ...(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 } }),
 });
 /** Rule → the linter's description (and a ruff rule's family), for every rule a card names. */
 type Described = ReadonlyMap<string, RuleText>;
@@ -836,14 +1046,16 @@ const ruleKey = (r: RuleRef): string => `${r.linter} ${r.id}`;
 function describeRules(cfg: Config, fromDir: string): Described {
   return new Map(
     cardsOf(cfg).flatMap(([at, card]) =>
-      (card.rules ?? []).map((r, k): readonly [string, RuleText] => {
-        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];
-      }),
+      (card.rules ?? []).flatMap(
+        (r, k): readonly (readonly [string, RuleText])[] => {
+          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]];
+        },
+      ),
     ),
   );
 }
@@ -882,6 +1094,14 @@ const practiceShown = (cfg: Config, described: Described) =>
     ...shownFields(p),
     ...rulesShown(p, described),
   }));
+/** The page's own words where `labels` leaves one out (references/closed-choice-generator.md). */
+const DEFAULT_LABELS: Readonly<Record<string, string>> = {
+  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: Config,
@@ -894,6 +1114,7 @@ function payloadOf(
   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}?")
@@ -983,13 +1204,14 @@ function keyOf(
  * returns what the page shows. A page written by hand can take its blindness and its key from here.
  */
 export function prepareBuild(configPath: string, outDir: string) {
-  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-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),
+        },
+    };
+}