paperlint 14.3.0 → 14.5.0

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

@@ -451,6 +451,42 @@ const QUESTION_SCHEMA = obj({
   short: string(false),
   options: array(OPTION_SCHEMA, true, 2),
 });
+// Page-level words the blocks use (references/closed-choice-generator.md §«Content blocks»).
+const LABELS = optional({
+  place: string(false),
+  body: string(false),
+  line: string(false),
+  line_part: string(false),
+  repeat: string(false),
+  practice_example: string(false),
+  hidden: string(false),
+  hidden_one: string(false),
+  wait: string(false),
+  how_to: string(false),
+  for_example: string(false),
+});
+// The page's own words in another language (#394): never the quote, code, notes or any card text
+// the labeller judges. Keyed like the page, so a translation names its questions and answers by id.
+const TRANSLATION = obj({
+  title: string(false),
+  intro: string(false),
+  labels: LABELS,
+  // the first question as the cards with a `situation` ask it; `{n}` is the marked line's number
+  situation_question: string(false),
+  questions: mapping(
+    obj({
+      text: string(),
+      short: string(false),
+      options: mapping(
+        obj({ label: string(), example: string(), ask_why: string(false) }),
+        NAME_PATTERN,
+        1,
+      ),
+    }),
+    NAME_PATTERN,
+    1,
+  ),
+});
 const configSchema = (kind: Kind): SchemaNode =>
   obj({
     study: string(true, NAME_PATTERN), // becomes a file name
@@ -471,18 +507,10 @@ 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),
-      hidden: string(false),
-      hidden_one: string(false),
-      wait: string(false),
-    }),
+    labels: LABELS,
+    // the language of the page's own words, and the same words in more languages, with a switch
+    lang: string(false, NAME_PATTERN),
+    translations: mapping(TRANSLATION, NAME_PATTERN, 1, false),
     items: array(itemSchema(kind), true, 1),
   });
 /** The declared schema (`schema` prints it): every field, those a kind requires left optional. */
@@ -736,8 +764,32 @@ interface Config {
   readonly practice: readonly Practice[];
   readonly practice_round?: number;
   readonly labels?: Readonly<Record<string, string>>;
+  readonly lang?: string;
+  readonly translations?: Readonly<Record<string, Translation>>;
   readonly items: readonly Item[];
 }
+interface QuestionWords {
+  readonly text: string;
+  readonly short?: string;
+  readonly options: Readonly<
+    Record<
+      string,
+      {
+        readonly label: string;
+        readonly example: string;
+        readonly ask_why?: string;
+      }
+    >
+  >;
+}
+/** The page's own words in one more language (#394). */
+interface Translation {
+  readonly title?: string;
+  readonly intro?: string;
+  readonly labels?: Readonly<Record<string, string>>;
+  readonly situation_question?: string;
+  readonly questions: Readonly<Record<string, QuestionWords>>;
+}
 /** The config is typed by passing CONFIG_SCHEMA: `checkValue` refuses (throws) on any departure. */
 function assertConfig(value: Json): asserts value is Json & Config {
   checkValue(value, CONFIG_SCHEMA, "");
@@ -1157,6 +1209,129 @@ function checkNoSourceShown(cfg: Config): void {
   }
 }
 
+// ── a second language for the page's own words (#394) ─────────────────────────────────────────
+/** The language of the page's own words when items.json does not name it. */
+const BASE_LANG = "en";
+/** In a translated `situation_question`, the number of the card's marked line. */
+const NUMBER_TOKEN = "{n}";
+/** A translated text is given exactly when the page shows the text it translates. */
+function checkPresence(
+  where: string,
+  shown: string | undefined,
+  given: string | undefined,
+): void {
+  if (shown !== undefined && given === undefined)
+    fail(`${where}: is required and missing — ${shown}`);
+  if (shown === undefined && given !== undefined)
+    fail(`${where}: is never shown — the page has no text it translates`);
+}
+/** The cards' first question, translated: given exactly when a card has a `situation`. */
+function checkSituationWords(cfg: Config, at: string, t: Translation): void {
+  const cards = cardsOf(cfg).filter(([, c]) => c.situation !== undefined);
+  const first = cards[0];
+  checkPresence(
+    `${at}.situation_question`,
+    first &&
+      `${first[0]}.situation asks the first question in the card's own words`,
+    t.situation_question,
+  );
+  const q = t.situation_question ?? "";
+  const bare = cards.find(([, c]) => lineOf(c) === undefined);
+  if (
+    bare !== undefined &&
+    [NUMBER_TOKEN, LINE_TOKEN].some((token) => q.includes(token))
+  )
+    fail(
+      `${at}.situation_question: names the marked line, and ${bare[0]} has no \`excerpt\` — add it, or write the question without \`${NUMBER_TOKEN}\` and \`${LINE_TOKEN}\``,
+    );
+}
+/** One answer in the translation's words; refused when the translation leaves it out. */
+const optionIn = (o: Option, words: QuestionWords, where: string): Option => {
+  const w =
+    words.options[o.value] ??
+    fail(
+      `${where}.options.${o.value}: is required and missing — every answer is translated`,
+    );
+  checkPresence(
+    `${where}.options.${o.value}.ask_why`,
+    o.ask_why && "this answer asks why",
+    w.ask_why,
+  );
+  return {
+    ...R.omit(o, ["ask_why"]),
+    label: w.label,
+    example: w.example,
+    ...R.pickBy({ ask_why: w.ask_why }, R.isDefined),
+  };
+};
+/** One question in the translation's words: every answer of it, no answer it does not have. */
+function questionIn(q: Question, t: Translation, at: string): Question {
+  const where = `${at}.questions.${q.id}`;
+  const words =
+    t.questions[q.id] ??
+    fail(
+      `${where}: is required and missing — every question of the page is translated`,
+    );
+  const values = q.options.map((o) => o.value);
+  const stray = Object.keys(words.options).find((v) => !values.includes(v));
+  if (stray !== undefined)
+    fail(`${where}.options.${stray}: not one of ${values.join(", ")}`);
+  const options = q.options.map((o) => optionIn(o, words, where));
+  const twice = firstRepeat(options.map((o) => o.label));
+  if (twice !== undefined)
+    fail(
+      `${where}.options.${String(values[twice.at])}.label: ${repr(options[twice.at]?.label)} reads the same as options.${String(values[twice.earlier])}.label — each button needs its own label`,
+    );
+  return {
+    id: q.id,
+    text: words.text,
+    ...R.pickBy({ short: words.short }, R.isDefined),
+    options,
+  };
+}
+/**
+ * Every language of the page with its words whole, the translations checked: each covers every
+ * question and answer of the page and names none it does not have, and gives an intro, a reason
+ * prompt and a situation question exactly where the page shows one. A label it leaves out reads as
+ * in the page's own language.
+ */
+function translationsOf(cfg: Config) {
+  const base = cfg.lang ?? BASE_LANG;
+  return R.mapValues(cfg.translations ?? {}, (t, lang) => {
+    const at = `translations.${lang}`;
+    if (lang === base)
+      fail(
+        `${at}: is the page's own language (\`lang\` is ${repr(base)}) — translate into another one`,
+      );
+    checkPresence(
+      `${at}.intro`,
+      cfg.intro && "the page has an `intro`",
+      t.intro,
+    );
+    checkSituationWords(cfg, at, t);
+    const ids = cfg.questions.map((q) => q.id);
+    const stray = Object.keys(t.questions).find((id) => !ids.includes(id));
+    if (stray !== undefined)
+      fail(
+        `${at}.questions.${stray}: not a question of this page (${ids.join(", ")})`,
+      );
+    return {
+      title: t.title ?? cfg.title,
+      intro: t.intro ?? "",
+      labels: { ...DEFAULT_LABELS, ...cfg.labels, ...t.labels },
+      ...R.pickBy({ situation_question: t.situation_question }, R.isDefined),
+      questions: cfg.questions.map((q) => questionIn(q, t, at)),
+    };
+  });
+}
+type Translated = ReturnType<typeof translationsOf>;
+/** The languages: the page's own when items.json names it, and with translations always (English when unnamed).
+ *  A page that names neither is as it was. */
+const languagesOf = (cfg: Config, translated: Translated) =>
+  cfg.translations === undefined
+    ? R.pickBy({ lang: cfg.lang }, R.isDefined)
+    : { lang: cfg.lang ?? BASE_LANG, translations: translated };
+
 // ── ids: neutral, in an order fixed by the seed, kept across rebuilds ─────────────────────────
 interface KeyEntry {
   readonly source_id: string;
@@ -1320,6 +1495,8 @@ const DEFAULT_LABELS: Readonly<Record<string, string>> = {
   hidden: "lines {from}\u2013{to}",
   hidden_one: "line {from}",
   wait: "\u23f3 You can answer in {s} s",
+  how_to: "📖 How to answer",
+  for_example: "For example: ",
 };
 /** The answerers and the dwell, only when items.json sets them: a page without them is as it was. */
 const twoKeys = (cfg: Config) =>
@@ -1332,6 +1509,7 @@ function payloadOf(
   cfg: Config,
   page: ReturnType<typeof itemsOnPage>,
   described: Described,
+  translated: Translated,
 ) {
   const used = Object.keys(cfg.groups).filter((g) =>
     page.items.some((i) => i.group === g),
@@ -1347,6 +1525,7 @@ function payloadOf(
     familiarity: asksFamiliarity(cfg) ? FAMILIARITY : [],
     allowed: allowedValues(cfg.questions, asksFamiliarity(cfg)),
     ...twoKeys(cfg),
+    ...languagesOf(cfg, translated),
     questions: cfg.questions,
     practice: {
       round: practiceRound(cfg),
@@ -1445,6 +1624,7 @@ export function prepareBuild(configPath: string, outDir: string) {
   checkBlocks(cfg);
   checkCardText(cfg);
   checkNoSourceShown(cfg);
+  const translated = translationsOf(cfg);
   const described = describeRules(cfg, dirname(configPath));
   mkdirSync(outDir, { recursive: true });
   const keyPath = join(outDir, "key.json");
@@ -1452,7 +1632,7 @@ export function prepareBuild(configPath: string, outDir: string) {
   const page = itemsOnPage(cfg, keyPath);
   writeJson(keyPath, keyOf(cfg, page, earlier));
   return {
-    payload: payloadOf(cfg, page, described),
+    payload: payloadOf(cfg, page, described, translated),
     dropped: cfg.items.length - page.items.length,
   };
 }

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

@@ -504,3 +504,32 @@ test("🔴 «All items are complete» waits for every group's familiarity too, a
   );
   assert.deepEqual([await said({}), await said(rated)], [false, true]);
 });
+
+test("🔴 the status line names nothing missing: empty while a card is unanswered, «Saved <time>» once part of it is saved, and its values keep what is missing", async () => {
+  const { page, key } = build(setup("status-missing", config()));
+  const [a, b] = Object.keys(key.ids);
+  assert.ok(a !== undefined && b !== undefined);
+  const savedAt = "2026-01-02T10:00:00Z";
+  const { app } = await openLive(page, {
+    answers: { [a]: { answers: { label: "yes" }, savedAt, source: "page" } },
+    groups: {},
+    practice: DONE_PRACTICE,
+  });
+  const statusOf = (id: string) => {
+    const card = app
+      .getByTestId("item")
+      .find((n) => z.object({ id: z.string() }).parse(n.meta()).id === id);
+    const line = card?.getByTestId("status")[0];
+    return [line?.meta(), line?.textContent];
+  };
+  assert.deepEqual(
+    [statusOf(a), statusOf(b)],
+    [
+      [
+        { state: "missing", missing: ["boundary"] },
+        `Saved ${new Date(savedAt).toLocaleTimeString()}`,
+      ],
+      [{ state: "missing", missing: ["label", "boundary"] }, ""],
+    ],
+  );
+});

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

@@ -0,0 +1,371 @@
+/**
+ * A second language for the page's own words (#394): what `translations` must cover, what the page
+ * is handed, and that the ids and the key do not depend on it.
+ */
+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 {
+  ITEMS,
+  QUESTIONS,
+  build,
+  config,
+  run,
+  setup,
+} from "../../../test/label-page-kit.ts";
+
+/** The questions of the kit's page in Russian: every question and every answer, by id and value. */
+const RU = {
+  title: "Разметьте",
+  labels: { how_to: "📖 Как отвечать", for_example: "Например: " },
+  questions: {
+    label: {
+      text: "Это верно?",
+      short: "верно?",
+      options: {
+        yes: { label: "Да", example: "Сортировка вернула 1, 2, 3." },
+        no: { label: "Нет", example: "Сортировка вернула 3, 1, 2." },
+      },
+    },
+    boundary: {
+      text: "Ясный случай или пограничный?",
+      options: {
+        clear: { label: "Ясный", example: "Пустой список." },
+        boundary: { label: "Пограничный", example: "Два равных ключа." },
+      },
+    },
+  },
+};
+const withRu = (over: Record<string, unknown> = {}) =>
+  config({ translations: { ru: RU }, ...over });
+
+/** The page's data: the JSON the template is filled with. */
+const dataOf = (page: string): unknown =>
+  JSON.parse(
+    String(
+      page
+        .split('<script type="application/json" id="data">')[1]
+        ?.split("</script>")[0],
+    ).replaceAll("<\\/", "</"),
+  );
+const Data = z
+  .object({ lang: z.string(), translations: z.record(z.string(), z.unknown()) })
+  .loose();
+
+/** What the page is handed for Russian: the kit's labels with RU's over them, and every question. */
+function expectedRu() {
+  const [label, boundary] = QUESTIONS;
+  assert.ok(label !== undefined && boundary !== undefined);
+  const inRu = (qid: "label" | "boundary", value: string) =>
+    qid === "label"
+      ? RU.questions.label.options[value === "yes" ? "yes" : "no"]
+      : RU.questions.boundary.options[value === "clear" ? "clear" : "boundary"];
+  return {
+    title: RU.title,
+    intro: "",
+    labels: {
+      place: "{id} · {n} of {total}",
+      line: "Line",
+      line_part: "{line} · part {part} of {of}",
+      repeat: "Card {index} of {of}",
+      practice_example: "",
+      hidden: "lines {from}–{to}",
+      hidden_one: "line {from}",
+      wait: "⏳ You can answer in {s} s",
+      ...RU.labels,
+    },
+    questions: [
+      {
+        id: "label",
+        text: "Это верно?",
+        short: "верно?",
+        options: label.options.map((o) => ({
+          value: o.value,
+          ...inRu("label", o.value),
+        })),
+      },
+      {
+        id: "boundary",
+        text: "Ясный случай или пограничный?",
+        options: boundary.options.map((o) => ({
+          value: o.value,
+          ...inRu("boundary", o.value),
+        })),
+      },
+    ],
+  };
+}
+/** The keys a built page's data has, of `names`. */
+const dataKeys = (page: string, names: readonly string[]) =>
+  names.filter((k) =>
+    Object.hasOwn(z.object({}).loose().parse(dataOf(page)), k),
+  );
+
+test("🔴 a translation hands the page each language's words whole, and leaves the key byte for byte as without it", () => {
+  const plain = setup("lang-plain", config());
+  const translated = setup("lang-ru", withRu());
+  const { page } = build(translated);
+  const keyOf = (dir: string) =>
+    readFileSync(join(dir, "out", "key.json"), "utf8");
+  const data = Data.parse(dataOf(page));
+  assert.deepEqual(
+    [
+      data.lang,
+      data.translations,
+      dataKeys(build(plain).page, ["lang", "translations"]),
+    ],
+    // Guards: a page without translations carries neither key, so it is as it was.
+    ["en", { ru: expectedRu() }, []],
+  );
+  assert.equal(keyOf(translated), keyOf(plain));
+});
+
+test("🔴 a page that names its language without translations keeps it, and still carries no translations", () => {
+  const page = build(setup("lang-only", config({ lang: "de" }))).page;
+  assert.deepEqual(
+    [
+      z.object({ lang: z.string() }).loose().parse(dataOf(page)).lang,
+      dataKeys(page, ["lang", "translations"]),
+    ],
+    ["de", ["lang"]],
+  );
+});
+
+/** RU with an intro, a reason prompt on «no» and a card question naming the marked line. */
+const RU_FULL = {
+  ...RU,
+  intro: "Отвечайте как знаете.",
+  situation_question: "Строка {n} верна?",
+  questions: {
+    ...RU.questions,
+    label: {
+      ...RU.questions.label,
+      options: {
+        ...RU.questions.label.options,
+        no: { ...RU.questions.label.options.no, ask_why: "Почему?" },
+      },
+    },
+  },
+};
+/** A German page with an intro, a reason prompt and a card that asks in its own words, and RU_FULL. */
+function fullConfig() {
+  const [label, boundary] = QUESTIONS;
+  assert.ok(label !== undefined && boundary !== undefined);
+  const [first, ...rest] = ITEMS;
+  return config({
+    lang: "de",
+    intro: "Answer as you know.",
+    questions: [
+      {
+        ...label,
+        options: [
+          label.options[0],
+          { ...label.options[1], ask_why: "Why not?" },
+        ],
+      },
+      boundary,
+    ],
+    translations: { ru: RU_FULL },
+    items: [
+      {
+        ...first,
+        situation: { question: "Is line 3 correct?" },
+        excerpt: { lines: [{ n: 3, text: "x = 1", mark: true }] },
+      },
+      ...rest,
+    ],
+  });
+}
+const FullData = z
+  .object({
+    lang: z.string(),
+    translations: z.object({
+      ru: z
+        .object({
+          intro: z.string(),
+          situation_question: z.string(),
+          questions: z.array(z.unknown()),
+        })
+        .loose(),
+    }),
+  })
+  .loose();
+
+test("🔴 the page's own language may be named, and an intro, a reason prompt and a card's own question are translated with it", () => {
+  const data = FullData.parse(
+    dataOf(build(setup("lang-full", fullConfig())).page),
+  );
+  const ru = data.translations.ru;
+  assert.deepEqual(
+    [data.lang, ru.intro, ru.situation_question, ru.questions[0]],
+    [
+      "de",
+      RU_FULL.intro,
+      RU_FULL.situation_question,
+      {
+        id: "label",
+        text: "Это верно?",
+        short: "верно?",
+        options: [
+          { value: "yes", ...RU.questions.label.options.yes },
+          { value: "no", ...RU_FULL.questions.label.options.no },
+        ],
+      },
+    ],
+  );
+});
+
+/** The kit's page with its Russian words changed by `ru`, and more of the config by `over`. */
+const refusedWith = (
+  ru: Record<string, unknown>,
+  over: Record<string, unknown> = {},
+) => withRu({ translations: { ru: { ...RU, ...ru } }, ...over });
+const ruQuestion = (
+  qid: "label" | "boundary",
+  change: Record<string, unknown>,
+) => ({
+  questions: { ...RU.questions, [qid]: { ...RU.questions[qid], ...change } },
+});
+const ruOptions = (options: Record<string, unknown>) =>
+  ruQuestion("label", { options });
+const situated = (excerpt: boolean) => ({
+  items: ITEMS.map((i, n) =>
+    n === 0
+      ? {
+          ...i,
+          situation: { question: "Is it correct?" },
+          ...(excerpt
+            ? { excerpt: { lines: [{ n: 3, text: "x", mark: true }] } }
+            : {}),
+        }
+      : i,
+  ),
+});
+
+/** A page whose first question asks why on «no». */
+function asksWhy() {
+  const [label] = QUESTIONS;
+  assert.ok(label !== undefined);
+  return [
+    {
+      ...label,
+      options: [label.options[0], { ...label.options[1], ask_why: "Why?" }],
+    },
+    QUESTIONS[1],
+  ];
+}
+/** Configs only the translation checks refuse, each with its refusal. */
+const REFUSALS: readonly (readonly [
+  string,
+  Record<string, unknown>,
+  string,
+])[] = [
+  [
+    "own",
+    withRu({ translations: { en: RU } }),
+    "translations.en: is the page's own language (`lang` is 'en') — translate into another one",
+  ],
+  [
+    "no-question",
+    refusedWith({ questions: { label: RU.questions.label } }),
+    "translations.ru.questions.boundary: is required and missing — every question of the page is translated",
+  ],
+  [
+    "stray-question",
+    refusedWith({
+      questions: { ...RU.questions, ghost: RU.questions.label },
+    }),
+    "translations.ru.questions.ghost: not a question of this page (label, boundary)",
+  ],
+  [
+    "no-answer",
+    refusedWith(ruOptions({ yes: RU.questions.label.options.yes })),
+    "translations.ru.questions.label.options.no: is required and missing — every answer is translated",
+  ],
+  [
+    "stray-answer",
+    refusedWith(
+      ruOptions({
+        ...RU.questions.label.options,
+        maybe: { label: "Может", example: "e" },
+      }),
+    ),
+    "translations.ru.questions.label.options.maybe: not one of yes, no",
+  ],
+  [
+    "same-label",
+    refusedWith(
+      ruOptions({
+        ...RU.questions.label.options,
+        no: { label: " да ", example: "e" },
+      }),
+    ),
+    "translations.ru.questions.label.options.no.label: ' да ' reads the same as options.yes.label — each button needs its own label",
+  ],
+  [
+    "no-why",
+    withRu({ questions: asksWhy() }),
+    "translations.ru.questions.label.options.no.ask_why: is required and missing — this answer asks why",
+  ],
+  [
+    "stray-why",
+    refusedWith(
+      ruOptions({
+        ...RU.questions.label.options,
+        no: { ...RU.questions.label.options.no, ask_why: "Почему?" },
+      }),
+    ),
+    "translations.ru.questions.label.options.no.ask_why: is never shown — the page has no text it translates",
+  ],
+  [
+    "no-intro",
+    withRu({ intro: "Answer." }),
+    "translations.ru.intro: is required and missing — the page has an `intro`",
+  ],
+  [
+    "stray-intro",
+    refusedWith({ intro: "Отвечайте." }),
+    "translations.ru.intro: is never shown — the page has no text it translates",
+  ],
+  [
+    "no-situation",
+    withRu(situated(true)),
+    "translations.ru.situation_question: is required and missing — items[0].situation asks the first question in the card's own words",
+  ],
+  [
+    "stray-situation",
+    refusedWith({ situation_question: "Верно?" }),
+    "translations.ru.situation_question: is never shown — the page has no text it translates",
+  ],
+  [
+    "line-without-code",
+    refusedWith({ situation_question: "Строка {n} верна?" }, situated(false)),
+    "translations.ru.situation_question: names the marked line, and items[0] has no `excerpt` — add it, or write the question without `{n}` and `{line}`",
+  ],
+];
+/** Build `cfg` in a folder of its own; the exit status and what it printed. */
+const tryBuild = (name: string, cfg: Record<string, unknown>) => {
+  const dir = setup(name, cfg);
+  return run(["build", join(dir, "items.json"), join(dir, "out")]);
+};
+
+test("🔴 a translation that leaves out or invents a question, an answer, an intro, a reason prompt or a card's question stops the build, by path", () => {
+  const cases = REFUSALS;
+  assert.deepEqual(
+    cases.map(([name, cfg]) =>
+      tryBuild(`lang-refused-${name}`, cfg).out.trim(),
+    ),
+    cases.map(([, , why]) => `REFUSED: ${why}`),
+  );
+  // Guards: the same card question with its marked line in the code, and one without `{n}` on a
+  // card without code, both build.
+  assert.deepEqual(
+    [
+      refusedWith({ situation_question: "Строка {n} верна?" }, situated(true)),
+      refusedWith({ situation_question: "Верно?" }, situated(false)),
+    ].map((cfg, n) => tryBuild(`lang-situated-${String(n)}`, cfg).status),
+    [0, 0],
+  );
+});