paperlint 13.6.0 → 14.0.0

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

@@ -9,8 +9,10 @@ import { join } from "node:path";
 import { test } from "vitest";
 import { z } from "zod";
 import {
+  APPROVAL_PRACTICE,
   DONE_PRACTICE,
   Exported,
+  approvalCard,
   ITEMS,
   PRACTICE,
   QUESTIONS,
@@ -62,6 +64,16 @@ interface DocObject {
 const isObject = (v: Doc | undefined): v is DocObject =>
   typeof v === "object" && v !== null && !Array.isArray(v);
 
+/** Every optional field of a card, for an item and a practice item alike. */
+const CARD = {
+  title: "T",
+  code: "c = 1",
+  context: "ctx",
+  file: "`src/a.ts`",
+  rules: [{ linter: "eslint", id: "no-console" }],
+  unit: { id: "L0", text: "One line.", mark: "One", part: 1, of: 1 },
+  readings: { a: "on", b: "off" },
+};
 /** A config with EVERY optional field present, so every schema path has a value to spoil. */
 const FULL: DocObject = (() => {
   const doc = Doc.parse(
@@ -80,18 +92,8 @@ const FULL: DocObject = (() => {
       labeller_knows: ["python", "go", "rust"],
       familiarity: true,
       familiarity_question: "How well do you know {group}?",
-      items: ITEMS.map((i, n) =>
-        n === 0
-          ? {
-              ...i,
-              title: "T",
-              code: "c = 1",
-              context: "ctx",
-              rules: [{ linter: "eslint", id: "no-console" }],
-              unit: { id: "L0", text: "One line.", part: 1, of: 1 },
-            }
-          : i,
-      ),
+      practice: PRACTICE.map((p, n) => (n === 0 ? { ...p, ...CARD } : p)),
+      items: ITEMS.map((i, n) => (n === 0 ? { ...i, ...CARD } : i)),
     }),
   );
   assert.ok(isObject(doc));
@@ -235,9 +237,17 @@ function expectRefused(leaf: Leaf): void {
     assert.doesNotMatch(r.out, /Traceback/, `${what}\n${r.out}`);
   });
   if (!leaf.node.required && !leaf.member) {
+    const absent = spoil(leaf.path, undefined);
+    // familiarity_question asks nothing unless familiarity is on: the two leave together.
     const r = tryBuild(
       `schema-${leaf.path.replace(/\W/g, "_")}-absent`,
-      spoil(leaf.path, undefined),
+      leaf.path === "familiarity"
+        ? Object.fromEntries(
+            Object.entries(absent).filter(
+              ([k]) => k !== "familiarity_question",
+            ),
+          )
+        : absent,
     );
     assert.equal(r.status, 0, `${leaf.path} is optional: ${r.out}`);
   }
@@ -245,6 +255,7 @@ function expectRefused(leaf: Leaf): void {
 
 const DOCUMENTED_FIELDS = [
   "study",
+  "kind",
   "title",
   "intro",
   "seed",
@@ -1257,19 +1268,42 @@ test("🔴 familiarity off with a familiarity_question is a contradiction the bu
   assert.notEqual(r.status, 0);
   assert.match(
     r.out,
-    /REFUSED: familiarity_question: .*`familiarity` is false/,
+    /REFUSED: familiarity_question: .*`familiarity` is not true/,
   );
 });
 
-test("familiarity left out: every group is still asked (rule 5), and a missing one is reported", () => {
-  const dir = setup("familiarity-default", approval());
-  const { key } = build(dir);
-  assert.deepEqual(key.allowed.familiarity, ["well", "somewhat", "not_really"]);
+test('🔴 familiarity left out asks no group, approval page or not; a page asks it only with `"familiarity": true`', () => {
+  // Guards: the default is off for every page (#373), so an approval page built the old way asks nothing.
+  for (const [name, cfg] of [
+    ["fam-default-approval", approval()],
+    ["fam-default-gold", config({ familiarity: undefined })],
+  ] as const) {
+    assert.deepEqual(build(setup(name, cfg)).key.allowed.familiarity, []);
+  }
+  const asks = setup("fam-on", config());
+  assert.deepEqual(build(asks).key.allowed.familiarity, [
+    "well",
+    "somewhat",
+    "not_really",
+  ]);
   writeFileSync(
-    join(dir, "dump.json"),
+    join(asks, "dump.json"),
     JSON.stringify({ answers: {}, groups: {} }),
   );
-  assert.match(exportAt(dir).out, /group python: no familiarity answer/);
+  assert.match(exportAt(asks).out, /group python: no familiarity answer/);
+  const r = run([
+    "build",
+    join(
+      setup(
+        "fam-question-alone",
+        config({ familiarity: undefined, familiarity_question: "How well?" }),
+      ),
+      "items.json",
+    ),
+    join(WORK, "fam-question-alone-out"),
+  ]);
+  assert.equal(r.status, 1, r.out);
+  assert.match(r.out, /REFUSED: familiarity_question: .*is not true/);
 });
 
 /** Items 0 and 3 (both Rust) as the two requirements of one line. */
@@ -1280,7 +1314,13 @@ const withUnit = (
   config({
     items: ITEMS.map((item, n) => {
       const u = parts.find(([at]) => at === n);
-      return u === undefined ? item : { ...item, unit: u[1] };
+      // the first word of the line is marked unless the case says otherwise
+      return u === undefined
+        ? item
+        : {
+            ...item,
+            unit: { mark: String(u[1]["text"]).split(" ")[0], ...u[1] },
+          };
     }),
   });
 
@@ -1291,9 +1331,11 @@ const UNIT_REFUSALS: readonly (readonly [
   string,
 ])[] = [
   [
-    "unit-missing-part",
-    withUnit([[0, { id: "L1", text: LINE, part: 1, of: 2 }]]),
-    `items[0].unit: part 2 of 2 of line 'L1' is not among the items`,
+    "unit-mark-not-in-line",
+    withUnit([
+      [0, { id: "L1", text: LINE, mark: "JavaScript only", part: 1, of: 2 }],
+    ]),
+    "items[0].unit.mark: 'JavaScript only' is not in the line 'TypeScript only (no JavaScript); top-level await is allowed.' — mark the requirement with the line's own words",
   ],
   [
     "unit-part-twice",
@@ -1332,14 +1374,6 @@ const UNIT_REFUSALS: readonly (readonly [
     ]),
     "items[3].unit.text: 'Another line.', but items[0] of line 'L1' says",
   ],
-  [
-    "unit-halves-of-two-occurrences",
-    withUnit([
-      [0, { id: "L1", text: LINE, part: 1, of: 2 }],
-      [3, { id: "L2", text: LINE, part: 2, of: 2 }],
-    ]),
-    "items[0].unit: part 2 of 2 of line 'L1' is not among the items",
-  ],
   [
     "unit-leaks-source",
     withUnit([[0, { id: "L1", text: "as in case-1003", part: 1, of: 1 }]]),
@@ -1347,6 +1381,32 @@ const UNIT_REFUSALS: readonly (readonly [
   ],
 ];
 
+test("🔴 a drawn sample holds one requirement of a line that has two: it builds, the drawn part marked", () => {
+  // Guards: a unit with `of` above the parts present is a drawn part, not a lost one (#373, 5 of 9 cards).
+  const { page } = build(
+    setup(
+      "unit-drawn-part",
+      withUnit([
+        [
+          0,
+          {
+            id: "L1",
+            text: LINE,
+            mark: "top-level await is allowed",
+            part: 2,
+            of: 2,
+          },
+        ],
+      ]),
+    ),
+  );
+  assert.ok(
+    page.includes(
+      `"unit": {"text": "${LINE}", "mark": "top-level await is allowed", "part": 2, "of": 2}`,
+    ),
+  );
+});
+
 test("🔴 a line with several requirements: build refuses a unit whose parts do not add up, naming the item", () => {
   for (const [name, cfg, message] of UNIT_REFUSALS) {
     const dir = setup(name, cfg);
@@ -1375,7 +1435,12 @@ test("a line whose every requirement is an item builds, and each item carries it
       items: z.array(
         z.object({
           unit: z
-            .object({ text: z.string(), part: z.number(), of: z.number() })
+            .object({
+              text: z.string(),
+              mark: z.string(),
+              part: z.number(),
+              of: z.number(),
+            })
             .optional(),
         }),
       ),
@@ -1385,8 +1450,8 @@ test("a line whose every requirement is an item builds, and each item carries it
     .sort((a, b) => a.part - b.part);
   // what the page carries: the part and the line, never the line's private id
   assert.deepEqual(units, [
-    { text: LINE, part: 1, of: 2 },
-    { text: LINE, part: 2, of: 2 },
+    { text: LINE, mark: "TypeScript", part: 1, of: 2 },
+    { text: LINE, mark: "TypeScript", part: 2, of: 2 },
   ]);
 });
 
@@ -1403,3 +1468,95 @@ test("🔴 the same line in two places is two lines: four items, two ids, it bui
   const { page } = build(dir);
   assert.ok(!page.includes("a.md:3"), "the line's id is private");
 });
+
+/** A witness card: an approval card's line and rule, plus the two readings and the file. */
+const witnessCard = <T extends { readonly body: string }>(c: T, n: number) => ({
+  ...approvalCard(c, n),
+  readings: { a: "on", b: "off" },
+  file: "`src/a.ts`: B flags it",
+});
+const witnessPage = (
+  items: readonly Record<string, unknown>[] = ITEMS.map(witnessCard),
+) =>
+  approval({
+    kind: "witness",
+    practice: APPROVAL_PRACTICE.map(witnessCard),
+    items,
+  });
+
+/** Pages that miss their kind or a field it needs, each with its refusal. */
+function kindRefusals(): readonly (readonly [
+  string,
+  Record<string, unknown>,
+  string,
+])[] {
+  const plain = { items: ITEMS, practice: APPROVAL_PRACTICE };
+  const rulesOnly = {
+    items: ITEMS.map((c, n) => ({ ...c, rules: approvalCard(c, n).rules })),
+    practice: APPROVAL_PRACTICE.map((c, n) => ({
+      ...c,
+      rules: approvalCard(c, n).rules,
+    })),
+  };
+  return [
+    // the shape pages were built in until now: no kind, the line and the rule in free text
+    [
+      "kind-missing",
+      approval({ ...plain, kind: undefined }),
+      "kind: is required and missing — one of approval, witness, labels",
+    ],
+    [
+      "kind-unknown",
+      approval({ kind: "audit" }),
+      "kind: 'audit' must be one of approval, witness, labels",
+    ],
+    [
+      "approval-no-rules",
+      approval(plain),
+      "practice[0].rules: is required and missing — an approval card shows the rule read for it, with the linter's own description",
+    ],
+    [
+      "approval-no-unit",
+      approval(rulesOnly),
+      "practice[0].unit: is required and missing — an approval card shows the line its requirement was drawn from, the requirement marked",
+    ],
+    [
+      "witness-no-readings",
+      approval({ kind: "witness" }),
+      "practice[0].readings: is required and missing — a witness card shows the two readings, one row each",
+    ],
+    [
+      "witness-no-file",
+      witnessPage(
+        ITEMS.map((c, n) => ({ ...witnessCard(c, n), file: undefined })),
+      ),
+      "items[0].file: is required and missing — a witness card shows the file the readings disagree on, on its own row",
+    ],
+  ];
+}
+
+test("🔴 a page without its kind, or a card without its kind's fields, fails the schema naming the field", () => {
+  const refused = kindRefusals();
+  // Guards: the whole refusal, the field and why the page's kind needs it.
+  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 page of each kind with its fields builds; a practice card shows its rule like a real one", () => {
+  const witness = build(setup("witness-ok", witnessPage()));
+  assert.ok(witness.page.includes('"readings": {"a": "on", "b": "off"}'));
+  assert.ok(
+    build(setup("approval-ok", approval())).page.includes(
+      '"rules": [{"linter": "eslint", "id": "no-console", "description": "Disallow the use of `console`"}]',
+    ),
+  );
+  assert.equal(build(setup("labels-ok", config())).key.seed, 7);
+});