paperlint 14.2.0 → 14.3.0

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

@@ -8,8 +8,10 @@ import assert from "node:assert/strict";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { test } from "vitest";
+import * as R from "remeda";
 import { z } from "zod";
 import {
+  type FakeNode,
   build,
   openLive,
   run,
@@ -204,7 +206,7 @@ const inOrder = (text: string, parts: readonly string[]): readonly string[] => {
   );
 };
 
-test("🔴 a card reads top to bottom: its place and body in the page's words, the repeat, the situation, the excerpt with its marked line labelled and its caption, the question and its answers, then the references, the list and the table, each folded", async () => {
+test("🔴 a card reads top to bottom: its place and body in the page's words, the repeat, the situation, the excerpt with its marked line labelled and its caption, the question and its answers, then the references, the list and the table, each in place", async () => {
   const { page: html, key } = build(setup("blocks-face", page()));
   const shown = await showPage(html, {}, {}, PRACTICE_DONE);
   const id = Object.entries(key.ids).find(
@@ -333,3 +335,277 @@ test("🔴 `labels.line_part` names a unit row whose line holds several requirem
     [true, true],
   );
 });
+
+// ── the approved card (#392): quote, terms with notes, answer sub-lines, the annotated excerpt ──
+const V7 = z
+  .object({ items: z.array(z.record(z.string(), z.unknown())) })
+  .loose()
+  .parse(
+    JSON.parse(
+      readFileSync(
+        join(import.meta.dirname, "fixtures", "v7-cards-items.json"),
+        "utf8",
+      ),
+    ),
+  );
+/** The v7 fixture without its time on screen, its first card changed by `change`. */
+const v7 = (
+  change: (
+    i: Record<string, unknown>,
+  ) => Record<string, unknown> = R.identity(),
+): Record<string, unknown> => ({
+  ...R.omit(V7, ["min_seconds"]),
+  items: V7.items.map((i, n) => (n === 0 ? change(i) : i)),
+});
+const V7_DONE = Object.fromEntries(
+  ["forbid", "allow", "elsewhere"].map((v, n) => [
+    `r1-P${String(n + 1)}`,
+    { answers: { forbid: v }, source: "page" },
+  ]),
+);
+const V7_REFUSED: readonly (readonly [
+  string,
+  Record<string, unknown>,
+  string,
+])[] = [
+  [
+    "v7-term-not-shown",
+    v7((i) => ({
+      ...i,
+      terms: [
+        {
+          term: "NumPy",
+          note: [{ quote: "q", url: "https://e.x/", url_label: "u" }],
+        },
+      ],
+    })),
+    "items[0].terms[0].term: 'NumPy' is not in the card's annotation, quote or quote source — a note opens from words the card shows",
+  ],
+  [
+    "v7-term-across-backticks",
+    v7((i) => ({
+      ...i,
+      terms: [
+        {
+          term: "rule D413",
+          note: [{ quote: "q", url: "https://e.x/", url_label: "u" }],
+        },
+      ],
+    })),
+    "items[0].terms[0].term: 'rule D413' is not in the card's annotation, quote or quote source — a note opens from words the card shows",
+  ],
+  [
+    "v7-terms-overlap",
+    v7((i) => ({
+      ...i,
+      terms: [
+        {
+          term: "Ruff",
+          note: [{ quote: "q", url: "https://e.x/", url_label: "u" }],
+        },
+        {
+          term: "Ruff rule",
+          note: [{ quote: "q", url: "https://e.x/", url_label: "u" }],
+        },
+      ],
+    })),
+    "items[0].terms[0].term: 'Ruff' is inside items[0].terms[1].term 'Ruff rule' — the page draws one of two overlapping terms, so the other note never opens",
+  ],
+  [
+    "v7-terms-twice",
+    v7((i) => ({
+      ...i,
+      terms: ["Ruff", "Ruff"].map((term) => ({
+        term,
+        note: [{ quote: "q", url: "https://e.x/", url_label: "u" }],
+      })),
+    })),
+    "items[0].terms[0].term: 'Ruff' is inside items[0].terms[1].term 'Ruff' — the page draws one of two overlapping terms, so the other note never opens",
+  ],
+  [
+    "v7-note-without-words",
+    v7((i) => ({
+      ...i,
+      terms: [
+        {
+          term: "Ruff",
+          note: [{ says: "a linter", url: "https://e.x/", url_label: "u" }],
+        },
+      ],
+    })),
+    "items[0].terms[0].note[0]: has neither `quote` nor `code` — a note shows its source's own words",
+  ],
+  [
+    "v7-note-unknown-question",
+    v7((i) => ({ ...i, answer_notes: { applies: { forbid: "x" } } })),
+    "items[0].answer_notes.applies: not a question of this page (forbid)",
+  ],
+  [
+    "v7-note-unknown-answer",
+    v7((i) => ({ ...i, answer_notes: { forbid: { maybe: "x" } } })),
+    "items[0].answer_notes.forbid.maybe: not one of forbid, allow, unsettled, elsewhere, cannot",
+  ],
+  [
+    "v7-no-words",
+    v7((i) => R.omit(i, ["quote"])),
+    "items[0].body: is required and missing — a card shows its `body`, or its words as a `quote`",
+  ],
+];
+
+test("🔴 the card text refuses a term the card does not show (or that spans a backtick), a note entry without a quote or a snippet, an answer note on an unknown question or answer, and a card with neither body nor quote", () => {
+  assert.deepEqual(
+    V7_REFUSED.map(([name, cfg]) => {
+      const dir = setup(name, cfg);
+      return run(["build", join(dir, "items.json"), join(dir, "out")]);
+    }),
+    V7_REFUSED.map(([, , message]) => ({
+      status: 1,
+      out: `REFUSED: ${message}\n`,
+    })),
+  );
+});
+
+/** The v7 fixture's first card, as the fixture writes it. */
+const V7_CARD = z
+  .object({
+    source_id: z.string(),
+    quote: z.object({ text: z.string(), source: z.string() }),
+    excerpt: z.object({
+      file: z.string(),
+      lang: z.string(),
+      annotation: z.string(),
+      lines: z.array(
+        z.object({
+          n: z.number(),
+          mark: z.boolean(),
+          context: z.boolean().optional(),
+          gutter: z.string().optional(),
+        }),
+      ),
+    }),
+    answer_notes: z.object({ forbid: z.record(z.string(), z.string()) }),
+  })
+  .loose()
+  .parse(V7.items[0]);
+const V7_QUESTION = z
+  .object({
+    questions: z.tuple([
+      z.object({
+        id: z.string(),
+        short: z.string(),
+        options: z.array(z.object({ value: z.string() })),
+      }),
+    ]),
+  })
+  .loose()
+  .parse(V7).questions[0];
+/** A fixture text as the page shows it: its `backticks` are code spans, not characters. */
+const unticked = (text: string): string => text.split("`").join("");
+/** What a node shows, with the fake DOM's line breaks between elements taken out. */
+const shownBy = (n: FakeNode): string => n.textContent.replace(/\n/g, "");
+/** The kinds of the card's parts, in the order they appear. */
+const KINDS = [
+  "excerpt-path",
+  "code-line",
+  "gap",
+  "annotation",
+  "quote",
+  "quote-source",
+  "question",
+  "answer",
+  "answer-sub",
+  "status",
+];
+
+/** What the card shows, read from the page: every part's values, its text, and the order of the parts. */
+function shownFacts(card: FakeNode) {
+  const of = (kind: string) => card.getByTestId(kind);
+  const texts = (kind: string) => of(kind).map(shownBy);
+  return {
+    path: of("excerpt-path").map((n) => n.meta()),
+    lines: of("code-line").map((n) => n.meta()),
+    gaps: of("gap").map((n) => n.meta()),
+    annotation: [of("annotation").map((n) => n.meta()), texts("annotation")],
+    quote: texts("quote"),
+    source: texts("quote-source"),
+    answers: of("answer").map((n) => n.meta()),
+    subs: of("answer-sub").map((n) => [n.meta(), shownBy(n)]),
+    status: [of("status").map((n) => n.meta()), texts("status")],
+    order: card
+      .all()
+      .map((n) => n.getAttribute("data-test") ?? "")
+      .filter((k) => KINDS.includes(k)),
+  };
+}
+/** The same facts, as the fixture states them. */
+function fixtureFacts() {
+  const lines = V7_CARD.excerpt.lines;
+  const notes = V7_CARD.answer_notes.forbid;
+  const noted = V7_QUESTION.options.filter((o) => o.value in notes);
+  return {
+    path: [{ file: V7_CARD.excerpt.file, lang: V7_CARD.excerpt.lang }],
+    lines: lines.map((l) => ({
+      line: l.n,
+      marked: l.mark,
+      gutter: l.gutter ?? "",
+      context: l.context ?? false,
+    })),
+    gaps: R.zip(lines, lines.slice(1))
+      .filter(([a, b]) => b.n > a.n + 1)
+      .map(([a, b]) => ({ from: a.n + 1, to: b.n - 1 })),
+    annotation: [
+      [{ line: lines.find((l) => l.mark)?.n }],
+      [unticked(V7_CARD.excerpt.annotation)],
+    ],
+    quote: [unticked(V7_CARD.quote.text)],
+    source: [unticked(V7_CARD.quote.source)],
+    answers: V7_QUESTION.options.map((o) => ({
+      question: V7_QUESTION.id,
+      value: o.value,
+    })),
+    subs: noted.map((o) => [
+      { question: V7_QUESTION.id, value: o.value },
+      unticked(notes[o.value] ?? ""),
+    ]),
+    status: [
+      [{ state: "missing", missing: [V7_QUESTION.id] }],
+      [`Still needs: ${V7_QUESTION.short}`],
+    ],
+    order: [
+      "excerpt-path",
+      ...lines.flatMap((l, n) => [
+        ...(l.n > (lines[n - 1]?.n ?? l.n) + 1 ? ["gap"] : []),
+        "code-line",
+        ...(l.mark ? ["annotation"] : []),
+      ]),
+      "quote",
+      "quote-source",
+      "question",
+      ...V7_QUESTION.options.flatMap((o) =>
+        o.value in notes ? ["answer", "answer-sub"] : ["answer"],
+      ),
+      "status",
+    ],
+  };
+}
+
+test("🔴 an approved card reads top to bottom: its path, the code with a gap row for what it leaves out, the marked line and the note under it, the quote, its source, the question, each answer with its sub-line, then what it still needs", async () => {
+  const { page: html, key } = build(setup("v7-face", v7()));
+  const { app } = await openLive(html, { practice: V7_DONE });
+  const id = Object.entries(key.ids).find(
+    ([, v]) => v.source_id === V7_CARD.source_id,
+  )?.[0];
+  const card = app
+    .getByTestId("item")
+    .find((n) => z.object({ id: z.string() }).parse(n.meta()).id === id);
+  assert.ok(id !== undefined && card !== undefined, "the card is drawn");
+  assert.deepEqual(shownFacts(card), fixtureFacts());
+  // Guards: the question's id is not what the line prints; no generator word names a section.
+  assert.notEqual(V7_QUESTION.short, `${V7_QUESTION.id}?`);
+  assert.deepEqual(
+    ["◀ this line", "Requirement", "REQUIREMENT", "CODE"].filter((w) =>
+      shownBy(card).includes(w),
+    ),
+    [],
+  );
+});