paperlint 14.4.0 → 14.6.0

package/skills/build-label-page/scripts/fixtures/v7-cards-ru.json

@@ -0,0 +1,23 @@
+{
+  "title": "Запрещают ли слова",
+  "labels": {
+    "place": "Карточка {n} из {total}",
+    "wait": "Сохранить · можно через {s} с на этой карточке",
+    "how_to": "📖 Как отвечать",
+    "for_example": "Например: "
+  },
+  "situation_question": "Эти слова запрещают строку {n}?",
+  "questions": {
+    "forbid": {
+      "text": "Эти слова запрещают отмеченную строку?",
+      "short": "запрещают ли слова?",
+      "options": {
+        "forbid": { "label": "Запрещают", "example": "«No print calls» и строка print(x)" },
+        "allow": { "label": "Разрешают", "example": "«No print calls» и строка log.info(x)" },
+        "unsettled": { "label": "Из слов это не следует", "example": "«Keep functions short» и функция на 30 строк" },
+        "elsewhere": { "label": "Слова про другое", "example": "«Use tabs» и строка с запросом к базе" },
+        "cannot": { "label": "Не берусь оценить (объясните)", "example": "строка на языке, который вы не читаете", "ask_why": "Что мешает?" }
+      }
+    }
+  }
+}

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

@@ -1000,9 +1000,10 @@ async function onV7Page(
     cardOf: (sourceId: string) => Promise<Locator>,
   ) => Promise<void>,
   withTime = false,
+  cfg: Record<string, unknown> = V7_CONFIG,
 ): Promise<void> {
   const { page: html, key } = build(
-    setup(name, withTime ? V7_CONFIG : R.omit(V7_CONFIG, ["min_seconds"])),
+    setup(name, withTime ? cfg : R.omit(cfg, ["min_seconds"])),
   );
   const done = ["forbid", "allow", "elsewhere"];
   const page = await (
@@ -1418,3 +1419,345 @@ test(
   },
   BROWSER_TEST_MS,
 );
+
+// ── a second language for the page's own words (#394) ──────────────────────────────────────────
+const RU_FIXTURE = join(import.meta.dirname, "fixtures", "v7-cards-ru.json");
+const Words = z.object({
+  labels: z.object({ for_example: z.string() }).loose(),
+  questions: z.array(
+    z.object({
+      id: z.string(),
+      text: z.string(),
+      options: z.array(
+        z.object({
+          value: z.string(),
+          label: z.string(),
+          example: z.string(),
+          icon: z.string(),
+        }),
+      ),
+    }),
+  ),
+});
+const RU_RAW = z.json().parse(JSON.parse(readFileSync(RU_FIXTURE, "utf8")));
+const RU_WORDS = z
+  .object({
+    situation_question: z.string(),
+    labels: z.object({ for_example: z.string() }).loose(),
+    questions: z.record(
+      z.string(),
+      z.object({
+        text: z.string(),
+        options: z.record(
+          z.string(),
+          z.object({ label: z.string(), example: z.string() }),
+        ),
+      }),
+    ),
+  })
+  .parse(RU_RAW);
+/** The fixture's page words in one language: the base's, or the Russian translation laid over them. */
+function wordsIn(lang: "en" | "ru") {
+  const base = Words.parse({
+    labels: { for_example: "For example: " },
+    questions: z.object({ questions: z.unknown() }).loose().parse(V7_CONFIG)
+      .questions,
+  });
+  if (lang === "en") return base;
+  return {
+    labels: RU_WORDS.labels,
+    questions: base.questions.map((q) => ({
+      ...q,
+      text: RU_WORDS.questions[q.id]?.text ?? "",
+      options: q.options.map((o) => ({
+        ...o,
+        ...RU_WORDS.questions[q.id]?.options[o.value],
+      })),
+    })),
+  };
+}
+/** What the docstring card and the how-to rows say in `lang`, as the fixture states it. */
+function expectedIn(lang: "en" | "ru") {
+  const card = fixtureCard("card-docstring");
+  const { situation, quote } = z
+    .object({
+      situation: z.object({ question: z.string() }),
+      quote: z.object({ text: z.string() }),
+    })
+    .loose()
+    .parse(card);
+  const w = wordsIn(lang);
+  const [q] = w.questions;
+  assert.ok(q !== undefined);
+  const notes = card.answer_notes.forbid;
+  return {
+    switch: { lang, langs: ["en", "ru"] },
+    quote: unticked(quote.text),
+    question:
+      lang === "en"
+        ? situation.question
+        : RU_WORDS.situation_question.replace(
+            "{n}",
+            String(card.excerpt.lines.find((l) => l.mark)?.n),
+          ),
+    answers: q.options.map((o) => [
+      { question: q.id, value: o.value },
+      `${o.icon}${o.label}${unticked(notes[o.value] ?? "")}`,
+    ]),
+    howTo: [
+      q.text,
+      ...q.options.map(
+        (o) => `${o.icon} ${o.label}${w.labels.for_example}${o.example}`,
+      ),
+    ],
+  };
+}
+/** The same, read from the page. */
+async function shownIn(page: Page, card: Locator) {
+  const texts = async (scope: Page | Locator, kind: string) =>
+    scope.getByTestId(kind).allTextContents();
+  return {
+    switch: await metaOf(page.getByTestId("lang-switch")),
+    quote: (await texts(card, "quote")).join(""),
+    question: (await texts(card, "question")).join(""),
+    answers: await Promise.all(
+      (await allByKind(card, "answer")).map(async (a) => [
+        a.meta,
+        await a.loc.textContent(),
+      ]),
+    ),
+    howTo: [
+      ...(await texts(page, "how-to-question")),
+      ...(await texts(page, "how-to-answer")),
+    ],
+  };
+}
+test(
+  "🔴 the language switch swaps the page's own words both ways, keeps the quote and the code as built, and is remembered over a reload",
+  async () => {
+    const cfg = {
+      ...R.omit(V7_CONFIG, ["min_seconds"]),
+      translations: { ru: RU_RAW },
+    };
+    const { page: html, key } = build(setup("browser-v7-lang", cfg));
+    const at = "http://label.test/";
+    const page = await (
+      await sharedBrowser()
+    ).newPage({ viewport: { width: 400, height: 800 } });
+    try {
+      // A real origin, so the page has a localStorage; every other request is refused, none leaves.
+      await page.route("**/*", (r) =>
+        r.request().url() === at
+          ? r.fulfill({ contentType: "text/html; charset=utf-8", body: html })
+          : r.abort(),
+      );
+      await page.addInitScript(
+        STORE(
+          Object.fromEntries(
+            ["forbid", "allow", "elsewhere"].map((v, n) => [
+              `r1-P${String(n + 1)}`,
+              { answers: { forbid: v }, source: "page" },
+            ]),
+          ),
+          20,
+        ),
+      );
+      await page.goto(at, { waitUntil: "domcontentloaded" });
+      const id = Object.entries(key.ids).find(
+        ([, v]) => v.source_id === "card-docstring",
+      )?.[0];
+      const card = async () => {
+        await page.getByTestId("item").first().waitFor();
+        const found = (await allByKind(page, "item")).find(
+          (c) => Id.parse(c.meta).id === id,
+        );
+        assert.ok(found !== undefined, "the card is drawn");
+        return found.loc;
+      };
+      const option = async (lang: string) =>
+        (await allByKind(page, "lang-option")).find(
+          (o) => z.object({ lang: z.string() }).parse(o.meta).lang === lang,
+        )?.loc;
+      assert.deepEqual(await shownIn(page, await card()), expectedIn("en"));
+      await (await option("ru"))?.click();
+      assert.deepEqual(await shownIn(page, await card()), expectedIn("ru"));
+      await page.reload({ waitUntil: "domcontentloaded" });
+      assert.deepEqual(await shownIn(page, await card()), expectedIn("ru"));
+      await (await option("en"))?.click();
+      assert.deepEqual(await shownIn(page, await card()), expectedIn("en"));
+    } finally {
+      await page.context().close();
+    }
+  },
+  BROWSER_TEST_MS,
+);
+
+test(
+  "🔴 a page without translations names its own language on the document: the one it declares, else English",
+  async () => {
+    const htmlLang = async (cfg: Record<string, unknown>, dir: string) => {
+      const { page: html } = build(setup(dir, cfg));
+      const at = "http://label.test/";
+      const page = await (
+        await sharedBrowser()
+      ).newPage({ viewport: { width: 400, height: 800 } });
+      try {
+        await page.route("**/*", (r) =>
+          r.request().url() === at
+            ? r.fulfill({ contentType: "text/html; charset=utf-8", body: html })
+            : r.abort(),
+        );
+        await page.addInitScript(
+          STORE(
+            Object.fromEntries(
+              ["forbid", "allow", "elsewhere"].map((v, n) => [
+                `r1-P${String(n + 1)}`,
+                { answers: { forbid: v }, source: "page" },
+              ]),
+            ),
+            20,
+          ),
+        );
+        await page.goto(at, { waitUntil: "domcontentloaded" });
+        await page.getByTestId("item").first().waitFor();
+        return await page.evaluate(() => document.documentElement.lang);
+      } finally {
+        await page.context().close();
+      }
+    };
+    const plain = R.omit(V7_CONFIG, ["min_seconds"]);
+    assert.deepEqual(
+      [
+        await htmlLang(plain, "browser-v7-lang-none"),
+        await htmlLang({ ...plain, lang: "de" }, "browser-v7-lang-de"),
+      ],
+      ["en", "de"],
+    );
+  },
+  BROWSER_TEST_MS,
+);
+
+const TAG_LABELS = {
+  repo: "From the repository",
+  ours: "Our restatement",
+  model: "Written by the model under test",
+  count: "Counted by our script",
+};
+const TAG_LABELS_RU = {
+  repo: "Из репозитория",
+  ours: "Пересказ нашей модели",
+  model: "Написано проверяемой моделью",
+  count: "Посчитано нашим скриптом",
+};
+const Raw = z.record(z.string(), z.unknown());
+/** A card's block as the fixture has it, with more fields. */
+const withIn = (
+  card: Record<string, unknown>,
+  block: string,
+  more: object,
+) => ({
+  ...card,
+  [block]: { ...Raw.parse(card[block]), ...more },
+});
+/** The v7 fixture with tags: the docstring card has all four kinds, the call card a quote tag only, the depth card none. */
+const TAGGED_CONFIG = {
+  ...V7_CONFIG,
+  sources: TAG_LABELS,
+  translations: { ru: { ...Raw.parse(RU_RAW), sources: TAG_LABELS_RU } },
+  items: V7_CONFIG.items.map((raw, n) => {
+    const card = Raw.parse(raw);
+    return n === 0
+      ? withIn(
+          withIn(withIn(card, "quote", { from: "repo" }), "situation", {
+            from: "ours",
+            summary: "A reviewer objected to this line.",
+          }),
+          "excerpt",
+          {
+            from: "model",
+            caption: "Counted over the file.",
+            caption_from: "count",
+          },
+        )
+      : n === 1
+        ? withIn(card, "quote", { from: "ours" })
+        : card;
+  }),
+};
+const SourceTag = z.object({ source: z.string(), block: z.string() });
+/** Each source tag of a card: its values and its text. */
+const tagsOn = async (card: Locator) =>
+  Promise.all(
+    (await allByKind(card, "source-tag")).map(async (t) => ({
+      ...SourceTag.parse(t.meta),
+      text: await t.loc.textContent(),
+    })),
+  );
+/** How far a tag's bottom edge is above the top of the block it tags (negative: not above). */
+const gapAbove = async (tag: Locator, block: Locator) => {
+  const [t, b] = [await tag.boundingBox(), await block.boundingBox()];
+  assert.ok(t !== null && b !== null);
+  return b.y - (t.y + t.height);
+};
+
+test(
+  "🔴 each tagged block gets a tag with its source id right above it, the label follows the language, and an untagged card has none",
+  async () => {
+    await onV7Page(
+      "browser-v7-source-tags",
+      async (page, cardOf) => {
+        const docstring = await cardOf("card-docstring");
+        assert.deepEqual(await tagsOn(docstring), [
+          { source: "repo", block: "quote", text: TAG_LABELS.repo },
+          { source: "ours", block: "situation", text: TAG_LABELS.ours },
+          { source: "model", block: "excerpt", text: TAG_LABELS.model },
+          { source: "count", block: "caption", text: TAG_LABELS.count },
+        ]);
+        assert.deepEqual(await tagsOn(await cardOf("card-call")), [
+          { source: "ours", block: "quote", text: TAG_LABELS.ours },
+        ]);
+        // Guards: a card whose blocks name no source has no tag at all.
+        assert.deepEqual(await tagsOn(await cardOf("card-depth")), []);
+        const tags = docstring.getByTestId("source-tag");
+        const gaps = [
+          await gapAbove(tags.nth(0), docstring.getByTestId("quote")),
+          await gapAbove(tags.nth(2), docstring.getByTestId("excerpt-path")),
+        ];
+        // Guards: the tag sits above its block, close to it, never beside or below.
+        assert.ok(
+          gaps.every((g) => g >= 0 && g < 16),
+          JSON.stringify(gaps),
+        );
+        const switchTo = async (lang: string) =>
+          (await allByKind(page, "lang-option"))
+            .find(
+              (o) => z.object({ lang: z.string() }).parse(o.meta).lang === lang,
+            )
+            ?.loc.click();
+        await switchTo("ru");
+        assert.deepEqual(
+          (await tagsOn(await cardOf("card-docstring"))).map((t) => t.text),
+          [
+            TAG_LABELS_RU.repo,
+            TAG_LABELS_RU.ours,
+            TAG_LABELS_RU.model,
+            TAG_LABELS_RU.count,
+          ],
+        );
+      },
+      false,
+      TAGGED_CONFIG,
+    );
+  },
+  BROWSER_TEST_MS,
+);
+
+test(
+  "a page without sources draws no source tag",
+  async () => {
+    await onV7Page("browser-v7-no-source-tags", async (page) => {
+      assert.equal(await page.getByTestId("source-tag").count(), 0);
+    });
+  },
+  BROWSER_TEST_MS,
+);