paperlint 14.5.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({
@@ -369,6 +381,8 @@ const TRANSLATION = obj({
     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),
@@ -395,6 +409,8 @@ const configSchema = (kind) => obj({
     practice: array(practiceSchema(kind), true, MIN_PRACTICE),
     practice_round: integer(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),
@@ -674,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
@@ -841,6 +908,15 @@ function questionIn(q, t, at) {
         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
@@ -855,6 +931,7 @@ function translationsOf(cfg) {
             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)
@@ -863,7 +940,7 @@ function translationsOf(cfg) {
             title: t.title ?? cfg.title,
             intro: t.intro ?? "",
             labels: { ...DEFAULT_LABELS, ...cfg.labels, ...t.labels },
-            ...R.pickBy({ situation_question: t.situation_question }, R.isDefined),
+            ...optionalWords(t),
             questions: cfg.questions.map((q) => questionIn(q, t, at)),
         };
     });
@@ -913,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) } : {}),
         },
@@ -993,6 +1070,15 @@ const DEFAULT_LABELS = {
     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. */
@@ -1002,6 +1088,7 @@ function payloadOf(cfg, page, described, translated) {
         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}?")
@@ -1093,6 +1180,7 @@ 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));

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

@@ -280,7 +280,12 @@ const CARD_FIELDS: Readonly<Record<string, SchemaNode>> = {
   ),
   [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"
@@ -304,8 +309,15 @@ const CARD_FIELDS: Readonly<Record<string, SchemaNode>> = {
     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(),
@@ -473,6 +485,8 @@ const TRANSLATION = obj({
   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(),
@@ -508,6 +522,8 @@ const configSchema = (kind: Kind): SchemaNode =>
     practice: array(practiceSchema(kind), true, MIN_PRACTICE),
     practice_round: integer(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),
@@ -683,6 +699,7 @@ interface Blocks {
   readonly situation?: {
     readonly summary?: string;
     readonly question: string;
+    readonly from?: string;
   };
   readonly excerpt?: {
     readonly file?: string;
@@ -693,8 +710,14 @@ interface Blocks {
     readonly annotation?: string;
     readonly caption?: string;
     readonly mark_label?: string;
+    readonly from?: string;
+    readonly caption_from?: string;
+  };
+  readonly quote?: {
+    readonly text: string;
+    readonly source?: string;
+    readonly from?: string;
   };
-  readonly quote?: { readonly text: string; readonly source?: string };
   readonly terms?: readonly Term[];
   readonly answer_notes?: Readonly<
     Record<string, Readonly<Record<string, string>>>
@@ -764,6 +787,7 @@ interface Config {
   readonly practice: readonly Practice[];
   readonly practice_round?: number;
   readonly labels?: Readonly<Record<string, string>>;
+  readonly sources?: Readonly<Record<string, string>>;
   readonly lang?: string;
   readonly translations?: Readonly<Record<string, Translation>>;
   readonly items: readonly Item[];
@@ -788,6 +812,7 @@ interface Translation {
   readonly intro?: string;
   readonly labels?: Readonly<Record<string, string>>;
   readonly situation_question?: string;
+  readonly sources?: Readonly<Record<string, string>>;
   readonly questions: Readonly<Record<string, QuestionWords>>;
 }
 /** The config is typed by passing CONFIG_SCHEMA: `checkValue` refuses (throws) on any departure. */
@@ -1056,6 +1081,65 @@ function checkBlocks(cfg: Config): void {
       );
   });
 }
+// ── 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: string, card: 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: Config): void {
+  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
@@ -1289,6 +1373,21 @@ function questionIn(q: Question, t: Translation, at: string): Question {
     options,
   };
 }
+/** A translated tag label names an id of the page's `sources`. */
+function checkTranslatedSources(cfg: Config, at: string, t: Translation): void {
+  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: Translation) =>
+  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
@@ -1309,6 +1408,7 @@ function translationsOf(cfg: Config) {
       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)
@@ -1319,7 +1419,7 @@ function translationsOf(cfg: Config) {
       title: t.title ?? cfg.title,
       intro: t.intro ?? "",
       labels: { ...DEFAULT_LABELS, ...cfg.labels, ...t.labels },
-      ...R.pickBy({ situation_question: t.situation_question }, R.isDefined),
+      ...optionalWords(t),
       questions: cfg.questions.map((q) => questionIn(q, t, at)),
     };
   });
@@ -1397,7 +1497,10 @@ const situationShown = (item: Card) =>
     ? {}
     : {
         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) } : {}),
         },
@@ -1498,6 +1601,16 @@ const DEFAULT_LABELS: Readonly<Record<string, string>> = {
   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: Config) =>
+  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: Config) =>
   R.pickBy(
@@ -1518,6 +1631,7 @@ function payloadOf(
     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}?")
@@ -1623,6 +1737,7 @@ export function prepareBuild(configPath: string, outDir: string) {
   checkUnits(cfg);
   checkBlocks(cfg);
   checkCardText(cfg);
+  checkSources(cfg);
   checkNoSourceShown(cfg);
   const translated = translationsOf(cfg);
   const described = describeRules(cfg, dirname(configPath));

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

@@ -0,0 +1,231 @@
+/**
+ * Source tags (#400): the page-level `sources`, the `from` and `caption_from` fields that name one,
+ * what the build refuses by path, and what the page is handed.
+ */
+import assert from "node:assert/strict";
+import { join } from "node:path";
+import { test } from "vitest";
+import { z } from "zod";
+import {
+  ITEMS,
+  PRACTICE,
+  build,
+  config,
+  run,
+  setup,
+} from "../../../test/label-page-kit.ts";
+
+const SOURCES = { repo: "From the repository", ours: "Our restatement" };
+const EXCERPT = { lines: [{ n: 3, text: "x = 1", mark: true }] };
+const [FIRST, SECOND, ...REST] = ITEMS;
+assert.ok(FIRST !== undefined && SECOND !== undefined);
+
+/** A page whose first two cards carry a quote, a situation and an excerpt, each tagged by `tags`. */
+function tagged(
+  tags: {
+    readonly quote?: string;
+    readonly situation?: string;
+    readonly excerpt?: string;
+    readonly caption?: string;
+  },
+  over: Record<string, unknown> = {},
+) {
+  return config({
+    sources: SOURCES,
+    items: [
+      {
+        ...FIRST,
+        quote: { text: "Use tabs", ...pick("from", tags.quote) },
+        situation: {
+          summary: "A reviewer objected.",
+          question: "Is line 3 right?",
+          ...pick("from", tags.situation),
+        },
+        excerpt: {
+          ...EXCERPT,
+          caption: "The reviewer wrote: no.",
+          ...pick("from", tags.excerpt),
+          ...pick("caption_from", tags.caption),
+        },
+      },
+      SECOND,
+      ...REST,
+    ],
+    ...over,
+  });
+}
+const pick = (key: string, value: string | undefined) =>
+  value === undefined ? {} : { [key]: value };
+const ALL = {
+  quote: "repo",
+  situation: "ours",
+  excerpt: "repo",
+  caption: "ours",
+};
+
+const Data = z
+  .object({
+    sources: z
+      .array(z.object({ id: z.string(), label: z.string() }))
+      .optional(),
+    items: z.array(z.record(z.string(), z.unknown())),
+  })
+  .loose();
+const dataOf = (page: string) =>
+  Data.parse(
+    JSON.parse(
+      String(
+        page
+          .split('<script type="application/json" id="data">')[1]
+          ?.split("</script>")[0],
+      ).replaceAll("<\\/", "</"),
+    ),
+  );
+
+test("🔴 sources and the four tags reach the page whole, in colour order; a page without sources carries none of it", () => {
+  const data = dataOf(build(setup("src-happy", tagged(ALL))).page);
+  assert.deepEqual(
+    [
+      data.sources,
+      ...["quote", "situation", "excerpt"].map(
+        (k) =>
+          z
+            .object({ from: z.string() })
+            .loose()
+            .parse(data.items.find((i) => k in i)?.[k]).from,
+      ),
+      z
+        .object({ caption_from: z.string() })
+        .loose()
+        .parse(data.items.find((i) => "excerpt" in i)?.["excerpt"])
+        .caption_from,
+    ],
+    [
+      [
+        { id: "repo", label: SOURCES.repo },
+        { id: "ours", label: SOURCES.ours },
+      ],
+      "repo",
+      "ours",
+      "repo",
+      "ours",
+    ],
+  );
+  const plain = build(setup("src-none", config())).page;
+  // Guards: no sources, no key on the page, so it is as it was.
+  assert.equal(Object.hasOwn(dataOf(plain), "sources"), false);
+  assert.equal(plain.includes('"from"'), false);
+});
+
+const PRACTICE_TAGGED = config({
+  sources: { repo: "From the repository" },
+  practice: [
+    {
+      body: "p",
+      quote: { text: "q", from: "repo" },
+      expected: { label: "yes", boundary: "clear" },
+      why: "w",
+    },
+    ...PRACTICE.slice(1),
+  ],
+});
+
+/** Pages the build refuses, each with its whole refusal. */
+const REFUSED: readonly (readonly [string, Record<string, unknown>, string])[] =
+  [
+    [
+      "src-no-sources",
+      config({
+        items: [
+          { ...FIRST, quote: { text: "t", from: "repo" } },
+          SECOND,
+          ...REST,
+        ],
+      }),
+      "items[0].quote.from: names the source 'repo', and the page has no `sources` — add them, or take the tag out",
+    ],
+    [
+      "src-unknown-id",
+      tagged({ quote: "repo", situation: "nope" }),
+      "items[0].situation.from: 'nope' is not in `sources` (repo, ours)",
+    ],
+    [
+      "src-unknown-caption",
+      tagged({ quote: "repo", caption: "nope" }),
+      "items[0].excerpt.caption_from: 'nope' is not in `sources` (repo, ours)",
+    ],
+    [
+      "src-dead-entry",
+      tagged({ quote: "repo" }, { sources: { ...SOURCES, spare: "Spare" } }),
+      "sources.ours: no item or practice item names it — a tag nothing carries is a dead entry",
+    ],
+    [
+      "src-empty-label",
+      tagged(
+        { quote: "repo", situation: "ours" },
+        { sources: { repo: "", ours: "O" } },
+      ),
+      "sources.repo: must be a non-empty string, got ''",
+    ],
+    [
+      "src-too-many",
+      tagged(
+        { quote: "a" },
+        { sources: Object.fromEntries("abcdef".split("").map((c) => [c, c])) },
+      ),
+      "sources: 6 ids, and the page has 5 colours for tags — merge ids, or drop one",
+    ],
+    [
+      "src-no-caption",
+      config({
+        sources: SOURCES,
+        items: [
+          { ...FIRST, excerpt: { ...EXCERPT, caption_from: "repo" } },
+          { ...SECOND, quote: { text: "t", from: "ours" } },
+          ...REST,
+        ],
+      }),
+      "items[0].excerpt.caption_from: tags a text the card does not have — add it, or take the tag out",
+    ],
+    [
+      "src-no-summary",
+      config({
+        sources: SOURCES,
+        items: [
+          {
+            ...FIRST,
+            situation: { question: "Is line 3 right?", from: "repo" },
+            excerpt: EXCERPT,
+          },
+          { ...SECOND, quote: { text: "t", from: "ours" } },
+          ...REST,
+        ],
+      }),
+      "items[0].situation.from: tags a text the card does not have — add it, or take the tag out",
+    ],
+  ];
+
+test("🔴 the build refuses a tag with no sources, an id not in sources, a dead entry, an empty label, more ids than colours, and a tag over a text the card lacks", () => {
+  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`,
+    })),
+  );
+});
+
+test("a practice item may carry a tag, and it counts as using the source", () => {
+  const { page } = build(
+    setup("src-practice", {
+      ...PRACTICE_TAGGED,
+      items: [{ ...FIRST }, ...ITEMS.slice(1)],
+    }),
+  );
+  assert.deepEqual(dataOf(page).sources, [
+    { id: "repo", label: "From the repository" },
+  ]);
+});

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

@@ -369,3 +369,53 @@ test("🔴 a translation that leaves out or invents a question, an answer, an in
     [0, 0],
   );
 });
+
+/** A page with two tagged cards, and Russian labels for its tags. */
+const taggedPage = (ru: Record<string, unknown>) =>
+  config({
+    sources: { repo: "From the repository", ours: "Our restatement" },
+    items: ITEMS.map((i, n) =>
+      n < 2 ? { ...i, quote: { text: "t", from: n ? "ours" : "repo" } } : i,
+    ),
+    translations: { ru: { ...RU, ...ru } },
+  });
+
+test("🔴 translations.<lang>.sources hands the page the tag labels in that language, and one left out stays the page's own", () => {
+  const ru = { sources: { repo: "Из репозитория" } };
+  const data = z
+    .object({
+      translations: z.object({
+        ru: z.object({ sources: z.record(z.string(), z.string()) }).loose(),
+      }),
+    })
+    .loose()
+    .parse(dataOf(build(setup("lang-sources", taggedPage(ru))).page));
+  assert.deepEqual(data.translations.ru.sources, ru.sources);
+});
+
+test("🔴 a translated tag label for an id the page's sources do not have is refused, with or without sources on the page", () => {
+  const stray = { sources: { zzz: "Чужой" } };
+  const refused = (name: string, cfg: Record<string, unknown>) => {
+    const dir = setup(name, cfg);
+    return run(["build", join(dir, "items.json"), join(dir, "out")]);
+  };
+  assert.deepEqual(
+    [
+      refused("lang-sources-stray", taggedPage(stray)),
+      refused(
+        "lang-sources-none",
+        withRu({ translations: { ru: { ...RU, ...stray } } }),
+      ),
+    ],
+    [
+      {
+        status: 1,
+        out: "REFUSED: translations.ru.sources.zzz: not one of the page's `sources` (repo, ours)\n",
+      },
+      {
+        status: 1,
+        out: "REFUSED: translations.ru.sources.zzz: not one of the page's `sources` (none)\n",
+      },
+    ],
+  );
+});