paperlint 14.4.0 → 14.6.0

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

@@ -222,7 +222,12 @@ const CARD_FIELDS = {
     }, true, false),
     [READINGS_FIELD]: obj({ a: string(), b: string() }, true, false),
     file: string(false),
-    situation: optional({ summary: string(false), question: string() }),
+    situation: optional({
+        summary: string(false),
+        question: string(),
+        // the source tag over the summary (#400); the question is the page's own and gets none
+        from: string(false),
+    }),
     excerpt: optional({
         file: string(false),
         // the file's language, after its path: "path · Python"
@@ -242,8 +247,15 @@ const CARD_FIELDS = {
         annotation: string(false),
         caption: string(false),
         mark_label: string(false),
+        // source tags (#400): over the code box, and over the caption under it
+        from: string(false),
+        caption_from: string(false),
+    }),
+    quote: optional({
+        text: string(),
+        source: string(false),
+        from: string(false),
     }),
-    quote: optional({ text: string(), source: string(false) }),
     terms: array(obj({
         term: string(),
         note: array(obj({
@@ -347,6 +359,36 @@ 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),
+    // the labels of the page's `sources`, by id; one left out reads as in the page's own language
+    sources: mapping(string(), NAME_PATTERN, 1, 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) => obj({
     study: string(true, NAME_PATTERN), // becomes a file name
     kind: string(true, Object.keys(KINDS).join("|"), `one of ${KIND_NAMES}`),
@@ -366,18 +408,12 @@ 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),
-        hidden: string(false),
-        hidden_one: string(false),
-        wait: string(false),
-    }),
+    labels: LABELS,
+    // the source tags a card's blocks carry (#400): id → the tag's label, in colour order
+    sources: mapping(string(), NAME_PATTERN, 1, false),
+    // 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. */
@@ -654,6 +690,57 @@ function checkBlocks(cfg) {
             fail(`${at}.repeat.index: ${String(r.index)} is not between 1 and ${String(r.of)}`);
     });
 }
+// ── source tags (#400) ────────────────────────────────────────────────────────────────────────
+/** The colours the page has for tags (`.tag.s0` to `.tag.s4` in page-template.html), in `sources` order. */
+export const SOURCE_COLOURS = 5;
+/** Each tag a card asks for: the path of the field that names it, the id it names, the text it sits over. */
+const tagsOf = (at, card) => [
+    ...(card.quote?.from === undefined
+        ? []
+        : [{ at: `${at}.quote.from`, id: card.quote.from, over: "text" }]),
+    ...(card.situation?.from === undefined
+        ? []
+        : [
+            {
+                at: `${at}.situation.from`,
+                id: card.situation.from,
+                over: card.situation.summary,
+            },
+        ]),
+    ...(card.excerpt?.from === undefined
+        ? []
+        : [{ at: `${at}.excerpt.from`, id: card.excerpt.from, over: "box" }]),
+    ...(card.excerpt?.caption_from === undefined
+        ? []
+        : [
+            {
+                at: `${at}.excerpt.caption_from`,
+                id: card.excerpt.caption_from,
+                over: card.excerpt.caption,
+            },
+        ]),
+];
+/**
+ * What the schema cannot say about source tags: a tag names an id of the page's `sources`, over a
+ * text the card has, the page has colours for its ids, and an id nothing uses is a dead entry.
+ */
+function checkSources(cfg) {
+    const tags = cardsOf(cfg).flatMap(([at, card]) => tagsOf(at, card));
+    const ids = Object.keys(cfg.sources ?? {});
+    if (ids.length > SOURCE_COLOURS)
+        fail(`sources: ${String(ids.length)} ids, and the page has ${String(SOURCE_COLOURS)} colours for tags — merge ids, or drop one`);
+    tags.forEach((t) => {
+        if (cfg.sources === undefined)
+            fail(`${t.at}: names the source ${repr(t.id)}, and the page has no \`sources\` — add them, or take the tag out`);
+        else if (!has(cfg.sources, t.id))
+            fail(`${t.at}: ${repr(t.id)} is not in \`sources\` (${ids.join(", ")})`);
+        if (t.over === undefined)
+            fail(`${t.at}: tags a text the card does not have — add it, or take the tag out`);
+    });
+    const dead = ids.find((id) => !tags.some((t) => t.id === id));
+    if (dead !== undefined)
+        fail(`sources.${dead}: no item or practice item names it — a tag nothing carries is a dead entry`);
+}
 /**
  * The texts a term may open a note from, the words asked about first: the quote, its source, then
  * the excerpt's annotation. The page looks a term up in the same texts, split the same way at
@@ -765,6 +852,104 @@ function checkNoSourceShown(cfg) {
         }
     }
 }
+// ── 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, shown, given) {
+    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, at, t) {
+    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, words, where) => {
+    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, t, at) {
+    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,
+    };
+}
+/** A translated tag label names an id of the page's `sources`. */
+function checkTranslatedSources(cfg, at, t) {
+    const known = Object.keys(cfg.sources ?? {});
+    const stray = Object.keys(t.sources ?? {}).find((id) => !known.includes(id));
+    if (stray !== undefined)
+        fail(`${at}.sources.${stray}: not one of the page's \`sources\` (${known.join(", ") || "none"})`);
+}
+/** The translated words a translation may leave out. */
+const optionalWords = (t) => R.pickBy({ situation_question: t.situation_question, sources: t.sources }, R.isDefined);
+/**
+ * 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) {
+    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);
+        checkTranslatedSources(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 },
+            ...optionalWords(t),
+            questions: cfg.questions.map((q) => questionIn(q, t, at)),
+        };
+    });
+}
+/** 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, translated) => cfg.translations === undefined
+    ? R.pickBy({ lang: cfg.lang }, R.isDefined)
+    : { lang: cfg.lang ?? BASE_LANG, translations: translated };
 /** key.json is this script's own output, written by `build`; its shape is trusted, not re-checked. */
 // eslint-disable-next-line @typescript-eslint/no-unused-vars -- an assertion signature, no body to run
 function assertOwnKey(_value) { }
@@ -805,7 +990,7 @@ const situationShown = (item) => item.situation === undefined
     ? {}
     : {
         situation: {
-            ...R.pickBy({ summary: item.situation.summary }, R.isDefined),
+            ...R.pickBy({ summary: item.situation.summary, from: item.situation.from }, R.isDefined),
             question: item.situation.question,
             ...(usesLine(item) ? { line: lineOf(item) } : {}),
         },
@@ -882,16 +1067,28 @@ const DEFAULT_LABELS = {
     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 tags' ids and labels in colour order, only when items.json has `sources`: a page without them is as it was. */
+const sourcesShown = (cfg) => cfg.sources === undefined
+    ? {}
+    : {
+        sources: Object.entries(cfg.sources).map(([id, label]) => ({
+            id,
+            label,
+        })),
+    };
 /** The answerers and the dwell, only when items.json sets them: a page without them is as it was. */
 const twoKeys = (cfg) => R.pickBy({ answerers: cfg.answerers, min_seconds: cfg.min_seconds }, R.isDefined);
 /** What a page shows: the questions, the practice and the items, blind, with their neutral ids. */
-function payloadOf(cfg, page, described) {
+function payloadOf(cfg, page, described, translated) {
     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 },
+        ...sourcesShown(cfg),
         groups: used.map((g) => ({ id: g, label: String(cfg.groups[g]) })),
         familiarity_question: asksFamiliarity(cfg)
             ? (cfg.familiarity_question ?? "How well do you know {group}?")
@@ -899,6 +1096,7 @@ function payloadOf(cfg, page, described) {
         familiarity: asksFamiliarity(cfg) ? FAMILIARITY : [],
         allowed: allowedValues(cfg.questions, asksFamiliarity(cfg)),
         ...twoKeys(cfg),
+        ...languagesOf(cfg, translated),
         questions: cfg.questions,
         practice: {
             round: practiceRound(cfg),
@@ -982,7 +1180,9 @@ export function prepareBuild(configPath, outDir) {
     checkUnits(cfg);
     checkBlocks(cfg);
     checkCardText(cfg);
+    checkSources(cfg);
     checkNoSourceShown(cfg);
+    const translated = translationsOf(cfg);
     const described = describeRules(cfg, dirname(configPath));
     mkdirSync(outDir, { recursive: true });
     const keyPath = join(outDir, "key.json");
@@ -990,7 +1190,7 @@ export function prepareBuild(configPath, outDir) {
     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-core.test.ts

@@ -139,6 +139,42 @@ const CARD = {
   },
   repeat: { group: "g", index: 1, of: 1 },
 };
+/** The translation of FULL's page, with every optional field present. */
+const RU_FULL = {
+  title: "Т",
+  intro: "Разметьте.",
+  labels: {
+    place: "К",
+    body: "Т",
+    line: "С",
+    line_part: "{line} {part}/{of}",
+    repeat: "П",
+    practice_example: "П",
+    hidden: "С {from}-{to}",
+    hidden_one: "С {from}",
+    wait: "Ж {s}",
+    how_to: "Как",
+    for_example: "Н: ",
+  },
+  situation_question: "В?",
+  questions: {
+    label: {
+      text: "Верно?",
+      short: "верно?",
+      options: {
+        yes: { label: "Да", example: "1, 2, 3" },
+        no: { label: "Нет", example: "3, 1, 2", ask_why: "Что не так?" },
+      },
+    },
+    boundary: {
+      text: "Граница?",
+      options: {
+        clear: { label: "Ясно", example: "[]" },
+        boundary: { label: "Граница", example: "равные ключи" },
+      },
+    },
+  },
+};
 /** A config with EVERY optional field present, so every schema path has a value to spoil. */
 const FULL: DocObject = (() => {
   const doc = Doc.parse(
@@ -169,7 +205,11 @@ const FULL: DocObject = (() => {
         hidden: "H {from}-{to}",
         hidden_one: "H {from}",
         wait: "W {s}",
+        how_to: "How",
+        for_example: "E: ",
       },
+      lang: "en",
+      translations: { ru: RU_FULL },
       practice: PRACTICE.map((p, n) => (n === 0 ? { ...p, ...CARD } : p)),
       items: ITEMS.map((i, n) =>
         n === 0 ? { ...i, ...CARD, answerers: ["author"] } : i,
@@ -304,6 +344,15 @@ function badCases({ node, member }: Leaf): readonly BadCase[] {
   return [...wrongType, ...extra];
 }
 
+/** `doc` without the value at `steps`. */
+function without(
+  doc: DocObject,
+  steps: readonly (string | number)[],
+): DocObject {
+  const out = put(doc, steps, undefined);
+  assert.ok(isObject(out));
+  return out;
+}
 /** `doc` with its first item's own answerers taken out. */
 function withoutItemAnswerers(doc: DocObject): DocObject {
   const out = put(doc, ["items", 0, "answerers"], undefined);
@@ -317,6 +366,25 @@ function withoutItemAnswerers(doc: DocObject): DocObject {
 const RELAX: Partial<Record<string, (doc: DocObject) => DocObject>> = {
   familiarity: (doc) => R.omit(doc, ["familiarity_question"]),
   answerers: withoutItemAnswerers,
+  // A translation gives an intro, a reason prompt and a card question exactly where the page has one.
+  intro: (doc) => without(doc, ["translations", "ru", "intro"]),
+  "translations.ru.intro": (doc) => R.omit(doc, ["intro"]),
+  "questions[0].options[1].ask_why": (doc) =>
+    without(doc, [
+      "translations",
+      "ru",
+      "questions",
+      "label",
+      "options",
+      "no",
+      "ask_why",
+    ]),
+  "translations.ru.situation_question": (doc) =>
+    without(without(doc, ["items", 0, "situation"]), [
+      "practice",
+      0,
+      "situation",
+    ]),
 };
 
 /** Spoil `leaf` each way in `badCases`; every one must stop the build and name the path. */