paperlint 13.6.1 → 14.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (25) hide show
  1. package/dist/skills/build-label-page/scripts/label-page-core.d.ts +130 -21
  2. package/dist/skills/build-label-page/scripts/label-page-presets.d.ts +10 -0
  3. package/dist/skills/build-label-page/scripts/rule-descriptions.d.ts +6 -1
  4. package/package.json +1 -1
  5. package/skills/build-label-page/SKILL.md +9 -4
  6. package/skills/build-label-page/SKILL.md.spec.ts +8 -3
  7. package/skills/build-label-page/references/checklist.md +6 -6
  8. package/skills/build-label-page/references/closed-choice-generator.md +167 -21
  9. package/skills/build-label-page/scripts/fixtures/blocks-items.json +214 -0
  10. package/skills/build-label-page/scripts/fixtures/linter-config-witness-items.json +448 -0
  11. package/skills/build-label-page/scripts/label-page-blocks.test.ts +335 -0
  12. package/skills/build-label-page/scripts/label-page-browser.test.ts +437 -16
  13. package/skills/build-label-page/scripts/label-page-core.js +271 -46
  14. package/skills/build-label-page/scripts/label-page-core.test.ts +246 -37
  15. package/skills/build-label-page/scripts/label-page-core.ts +442 -113
  16. package/skills/build-label-page/scripts/label-page-html.test.ts +59 -52
  17. package/skills/build-label-page/scripts/label-page-presets.js +222 -0
  18. package/skills/build-label-page/scripts/label-page-presets.test.ts +175 -0
  19. package/skills/build-label-page/scripts/label-page-presets.ts +257 -0
  20. package/skills/build-label-page/scripts/label-page.js +19 -8
  21. package/skills/build-label-page/scripts/label-page.ts +19 -8
  22. package/skills/build-label-page/scripts/page-template.html +278 -45
  23. package/skills/build-label-page/scripts/rule-descriptions.js +48 -30
  24. package/skills/build-label-page/scripts/rule-descriptions.test.ts +58 -12
  25. package/skills/build-label-page/scripts/rule-descriptions.ts +56 -33
@@ -4,22 +4,36 @@
4
4
  * cannot show: focus, typing, and a page that is left without the box ever losing focus.
5
5
  */
6
6
  import assert from "node:assert/strict";
7
- import { chromium, type Page } from "playwright-core";
8
- import { test } from "vitest";
7
+ import {
8
+ type Browser,
9
+ chromium,
10
+ type Locator,
11
+ type Page,
12
+ } from "playwright-core";
13
+ import { readFileSync } from "node:fs";
14
+ import { join } from "node:path";
15
+ import { afterAll, test } from "vitest";
9
16
  import { z } from "zod";
10
17
  import { chromiumPath } from "../../../test/chromium.ts";
11
18
  import {
12
19
  APPROVAL_PRACTICE,
20
+ PRACTICE,
21
+ QUESTIONS,
13
22
  approval,
14
23
  build,
24
+ config,
15
25
  setup,
16
26
  } from "../../../test/label-page-kit.ts";
17
27
 
18
28
  /** A store that keeps every write and echoes it back as a snapshot after `echoMs`. */
19
- const STORE = (practice: Record<string, unknown>, echoMs: number): string => `
29
+ const STORE = (
30
+ practice: Record<string, unknown>,
31
+ echoMs: number,
32
+ answers: Record<string, unknown> = {},
33
+ ): string => `
20
34
  window.__writes = [];
21
35
  (function () {
22
- var docs = { answers: {}, groups: {}, practice: ${JSON.stringify(practice)} };
36
+ var docs = { answers: ${JSON.stringify(answers)}, groups: {}, practice: ${JSON.stringify(practice)} };
23
37
  var subs = {};
24
38
  function snap(n) {
25
39
  (subs[n] || []).forEach(function (cb) {
@@ -66,6 +80,20 @@ async function reasonStored(page: Page, text: string): Promise<void> {
66
80
  assert.equal(await storedReason(page), text);
67
81
  }
68
82
 
83
+ /**
84
+ * One Chromium for the whole file, each test in a context of its own (`newPage` opens one): a launch
85
+ * per test cost about 5 s apiece on the macOS runner, and the file's wall time grew with every test.
86
+ */
87
+ let launched: Browser | undefined;
88
+ const sharedBrowser = async (): Promise<Browser> =>
89
+ (launched ??= await chromium.launch({
90
+ executablePath: chromiumPath(),
91
+ args: ["--no-sandbox"],
92
+ }));
93
+ afterAll(async () => {
94
+ await launched?.close();
95
+ });
96
+
69
97
  /** A browser test launches Chromium and types: far above vitest's 5 s default on a slow runner. */
70
98
  const BROWSER_TEST_MS = 60_000;
71
99
 
@@ -76,12 +104,9 @@ async function onApprovalPage(
76
104
  filter: "all" | "next" = "all",
77
105
  ): Promise<void> {
78
106
  const { page: html } = build(setup(name, approval()));
79
- const browser = await chromium.launch({
80
- executablePath: chromiumPath(),
81
- args: ["--no-sandbox"],
82
- });
107
+ const browser = await sharedBrowser();
108
+ const page = await browser.newPage();
83
109
  try {
84
- const page = await browser.newPage();
85
110
  await page.addInitScript(STORE(PRACTICE_DONE, echoMs));
86
111
  await page.goto("about:blank");
87
112
  await page.setContent(html, { waitUntil: "domcontentloaded" });
@@ -90,7 +115,7 @@ async function onApprovalPage(
90
115
  await page.getByRole("button", { name: /Drop/ }).first().click();
91
116
  await steps(page);
92
117
  } finally {
93
- await browser.close();
118
+ await page.context().close();
94
119
  }
95
120
  }
96
121
 
@@ -159,16 +184,42 @@ test(
159
184
  BROWSER_TEST_MS,
160
185
  );
161
186
 
187
+ test(
188
+ "🔴 an answer that needs a reason is not saved while its reason is empty; another answer replaces it unsaved",
189
+ async () => {
190
+ await onApprovalPage("browser-refuse", 20, async (page) => {
191
+ await page.waitForTimeout(1200); // longer than the reason's pause: nothing may arrive
192
+ assert.deepEqual(await writes(page), []);
193
+ assert.match(
194
+ (await page.locator("article.item").first().textContent()) ?? "",
195
+ /Not saved yet/,
196
+ );
197
+ // Leaving the page with the box empty saves nothing either.
198
+ await page.evaluate(() => {
199
+ window.dispatchEvent(new Event("pagehide"));
200
+ });
201
+ await page.waitForTimeout(100);
202
+ assert.deepEqual(await writes(page), []);
203
+ await page.getByRole("button", { name: /Keep/ }).first().click();
204
+ await page.waitForTimeout(100);
205
+ assert.deepEqual(
206
+ await page.evaluate(
207
+ "window.__writes.map(function (w) { return w.answers; })",
208
+ ),
209
+ [{ keep: "keep" }],
210
+ );
211
+ });
212
+ },
213
+ BROWSER_TEST_MS,
214
+ );
215
+
162
216
  test(
163
217
  "a Keep needs no reason and writes none: the page stays quiet",
164
218
  async () => {
165
219
  const { page: html } = build(setup("browser-keep", approval()));
166
- const browser = await chromium.launch({
167
- executablePath: chromiumPath(),
168
- args: ["--no-sandbox"],
169
- });
220
+ const browser = await sharedBrowser();
221
+ const page = await browser.newPage();
170
222
  try {
171
- const page = await browser.newPage();
172
223
  await page.addInitScript(STORE(PRACTICE_DONE, 20));
173
224
  await page.goto("about:blank");
174
225
  await page.setContent(html, { waitUntil: "domcontentloaded" });
@@ -180,7 +231,377 @@ test(
180
231
  [{}],
181
232
  );
182
233
  } finally {
183
- await browser.close();
234
+ await page.context().close();
235
+ }
236
+ },
237
+ BROWSER_TEST_MS,
238
+ );
239
+
240
+ /** A two-reading card with a long URL and compact JSON: what pushed the page sideways on a phone. */
241
+ const URL_LONG = `https://github.com/a/b/blob/${"0".repeat(40)}/src/a/long/path/to/witness.ts`;
242
+ const WITNESS = {
243
+ source_id: "s1",
244
+ group: "python",
245
+ body: "Warn for unused variables, except those prefixed with `_`",
246
+ unit: {
247
+ id: "L",
248
+ text: "Warn for unused variables",
249
+ mark: "unused",
250
+ part: 1,
251
+ of: 1,
252
+ },
253
+ rules: [{ linter: "eslint", id: "no-console" }],
254
+ readings: {
255
+ a: `[{"argsIgnorePattern":"^_","varsIgnorePattern":"^_","caughtErrors":"all"}]`,
256
+ b: "[]",
257
+ },
258
+ file: URL_LONG,
259
+ context: URL_LONG,
260
+ };
261
+
262
+ /** Where the line, the rule, reading A, reading B and the question sit on a card, top to bottom. */
263
+ const blocksOf = async (card: Locator) =>
264
+ Promise.all(
265
+ [
266
+ ".quote",
267
+ ".row:has(.lbl:text-is('Rule'))",
268
+ ".reading.a",
269
+ ".reading.b",
270
+ ".ask",
271
+ ].map(async (sel) => card.locator(sel).first().boundingBox()),
272
+ );
273
+
274
+ test(
275
+ "🔴 at phone width the card reads by position: line, rule, reading A above reading B, then the question; nothing pushes the page sideways",
276
+ async () => {
277
+ const { page: html } = build(
278
+ setup("browser-layout", approval({ items: [WITNESS] })),
279
+ );
280
+ const page = await (
281
+ await sharedBrowser()
282
+ ).newPage({ viewport: { width: 400, height: 900 } });
283
+ try {
284
+ await page.addInitScript(STORE(PRACTICE_DONE, 20));
285
+ await page.setContent(html, { waitUntil: "domcontentloaded" });
286
+ const card = page.locator("article.item").last();
287
+ const boxes = await blocksOf(card);
288
+ const [line, rule, a, b, ask] = boxes;
289
+ assert.ok(line && rule && a && b && ask, "every block is on the card");
290
+ // Guards: each block below the one before, A and B in one column, a gap before the question.
291
+ assert.deepEqual(
292
+ boxes
293
+ .slice(1)
294
+ .map(
295
+ (x, i) =>
296
+ (x?.y ?? 0) >= (boxes[i]?.y ?? 0) + (boxes[i]?.height ?? 0),
297
+ ),
298
+ [true, true, true, true],
299
+ );
300
+ assert.equal(a.x, b.x);
301
+ assert.ok(ask.y - (b.y + b.height) >= 16, "space before the question");
302
+ assert.deepEqual(
303
+ await card
304
+ .locator(".reading")
305
+ .evaluateAll((els) =>
306
+ els.map((e) => getComputedStyle(e).borderLeftStyle),
307
+ ),
308
+ ["solid", "dashed"],
309
+ );
310
+ // Guards: a long URL or compact JSON wraps; the page itself never scrolls sideways.
311
+ assert.equal(
312
+ await page.evaluate(() => document.documentElement.scrollWidth),
313
+ 400,
314
+ );
315
+ } finally {
316
+ await page.context().close();
317
+ }
318
+ },
319
+ BROWSER_TEST_MS,
320
+ );
321
+
322
+ const WITNESS_FIXTURE = join(
323
+ import.meta.dirname,
324
+ "fixtures",
325
+ "linter-config-witness-items.json",
326
+ );
327
+ /** The generic witness page, every practice card answered as expected, at phone width. */
328
+ async function onWitnessPage(
329
+ name: string,
330
+ steps: (page: Page) => Promise<void>,
331
+ practiceDone = true,
332
+ ): Promise<void> {
333
+ const cfg = z
334
+ .object({
335
+ practice: z.array(
336
+ z.object({ expected: z.record(z.string(), z.string()) }).loose(),
337
+ ),
338
+ })
339
+ .loose()
340
+ .parse(JSON.parse(readFileSync(WITNESS_FIXTURE, "utf8")));
341
+ const done = Object.fromEntries(
342
+ cfg.practice.map((p, n) => [
343
+ `r1-P${String(n + 1)}`,
344
+ { answers: p.expected, source: "page" },
345
+ ]),
346
+ );
347
+ const { page: html } = build(setup(name, cfg));
348
+ const page = await (
349
+ await sharedBrowser()
350
+ ).newPage({ viewport: { width: 400, height: 900 } });
351
+ try {
352
+ await page.addInitScript(STORE(practiceDone ? done : {}, 20));
353
+ await page.goto("about:blank");
354
+ await page.setContent(html, { waitUntil: "domcontentloaded" });
355
+ await steps(page);
356
+ } finally {
357
+ await page.context().close();
358
+ }
359
+ }
360
+
361
+ /** The code, the linter's message, the question, the rule docs' toggle: one read of the laid-out card,
362
+ * so a re-render between reads cannot mix two layouts. */
363
+ const LAYOUT_OF = ["pre.numbered", "p.said", ".ask", "details > summary"];
364
+ const Layout = z.array(z.object({ top: z.number(), bottom: z.number() }));
365
+ const layout = async (card: Locator) =>
366
+ Layout.parse(
367
+ await card.evaluate(
368
+ (e, sels) =>
369
+ sels.map((s) => {
370
+ const r = e.querySelector(s)?.getBoundingClientRect();
371
+ return { top: r?.top ?? NaN, bottom: r?.bottom ?? NaN };
372
+ }),
373
+ LAYOUT_OF,
374
+ ),
375
+ );
376
+
377
+ test(
378
+ "🔴 at phone width a witness card labels the caught line in its numbered code, asks its question right under that code, folds the rule docs and the settings, opens a long text on «more», and nothing pushes the page sideways",
379
+ async () => {
380
+ await onWitnessPage("browser-witness", async (page) => {
381
+ // Measure after the store's practice answers arrived: before them the practice cards sit above.
382
+ await page.locator("summary", { hasText: "How to answer" }).waitFor();
383
+ const card = page.locator("article.item", { hasText: "seed_db.py" });
384
+ // The marked line reads as marked without colour: a gutter marker and a label.
385
+ assert.equal(
386
+ await card.locator("pre.numbered .hit").textContent(),
387
+ '▶18print(f"seeded {len(rows)} rows")◀ this line',
388
+ );
389
+ // Guards: the rule docs, the files like it and the settings are folded.
390
+ assert.deepEqual(
391
+ [
392
+ await card.locator("details").count(),
393
+ await card.locator("details[open]").count(),
394
+ ],
395
+ [3, 0],
396
+ );
397
+ // The question sits right under the code it is about: only the linter's message between them,
398
+ // and the rule's docs start below the answers.
399
+ const docsSummary = card.locator("summary", {
400
+ hasText: "What the linter rule does (official docs)",
401
+ });
402
+ const box = await layout(card);
403
+ const [code, said, ask, docs] = box;
404
+ assert.ok(code && said && ask && docs, JSON.stringify(box));
405
+ assert.ok(
406
+ said.top >= code.bottom && ask.top >= said.bottom,
407
+ JSON.stringify(box),
408
+ );
409
+ assert.ok(ask.top - said.bottom < 40, JSON.stringify(box));
410
+ assert.ok(docs.top >= ask.bottom, JSON.stringify(box));
411
+ await docsSummary.click();
412
+ const why = card.locator(".clamped", { hasText: "Why:" });
413
+ const folded = (await why.boundingBox())?.height ?? 0;
414
+ await card.getByRole("button", { name: "more" }).first().click();
415
+ const opened = await card.locator("p", { hasText: "Why:" }).boundingBox();
416
+ assert.ok(
417
+ opened && opened.height > folded,
418
+ `${String(folded)} → ${String(opened?.height)}`,
419
+ );
420
+ assert.equal(
421
+ await page.evaluate(() => document.documentElement.scrollWidth),
422
+ 400,
423
+ );
424
+ });
425
+ },
426
+ BROWSER_TEST_MS,
427
+ );
428
+
429
+ test(
430
+ "🔴 a witness practice card's answer buttons say their example is about other code",
431
+ async () => {
432
+ await onWitnessPage(
433
+ "browser-witness-buttons",
434
+ async (page) => {
435
+ const practice = page.locator("article.item").first();
436
+ assert.deepEqual(
437
+ [
438
+ await practice.locator(".id").textContent(),
439
+ await practice.locator(".opts button").count(),
440
+ await practice.locator(".opts .ex").count(),
441
+ await practice.locator(".opts .ex").first().textContent(),
442
+ ],
443
+ [
444
+ "Practice P1",
445
+ 4,
446
+ 4,
447
+ "Example of this answer, about other code: «Use ===» and the line a == b: yes, the requirement forbids it",
448
+ ],
449
+ );
450
+ },
451
+ false,
452
+ );
453
+ },
454
+ BROWSER_TEST_MS,
455
+ );
456
+
457
+ test(
458
+ "🔴 under 'Next unanswered' the card just answered stays, with Change, until the next card is answered",
459
+ async () => {
460
+ await onWitnessPage("browser-witness-next", async (page) => {
461
+ await page.getByRole("button", { name: "Next unanswered" }).click();
462
+ const cards = page.locator("article.item");
463
+ assert.equal(await cards.count(), 3);
464
+ await cards.nth(0).getByRole("button", { name: "Yes" }).click();
465
+ await page.waitForTimeout(100);
466
+ assert.equal(await cards.count(), 3, "the answered card is still there");
467
+ assert.equal(
468
+ await cards.nth(0).getByRole("button", { name: "Change" }).count(),
469
+ 1,
470
+ );
471
+ await cards.nth(1).getByRole("button", { name: "Yes" }).click();
472
+ await page.waitForTimeout(100);
473
+ assert.equal(await cards.count(), 2, "the first one has gone");
474
+ });
475
+ },
476
+ BROWSER_TEST_MS,
477
+ );
478
+
479
+ test(
480
+ "🔴 on a page of two questions, an answer still waiting for its reason is in no write, even when the next question is answered",
481
+ async () => {
482
+ const [label, boundary] = QUESTIONS;
483
+ assert.ok(label !== undefined && boundary !== undefined);
484
+ const withWhy = {
485
+ ...label,
486
+ options: label.options.map((o) =>
487
+ o.value === "no" ? { ...o, ask_why: "Why not?" } : o,
488
+ ),
489
+ };
490
+ const { page: html } = build(
491
+ setup("browser-pending-two", config({ questions: [withWhy, boundary] })),
492
+ );
493
+ const done = Object.fromEntries(
494
+ PRACTICE.map((p, n) => [
495
+ `r1-P${String(n + 1)}`,
496
+ { answers: p.expected, source: "page" },
497
+ ]),
498
+ );
499
+ const page = await (await sharedBrowser()).newPage();
500
+ try {
501
+ await page.addInitScript(STORE(done, 20));
502
+ await page.goto("about:blank");
503
+ await page.setContent(html, { waitUntil: "domcontentloaded" });
504
+ const card = page.locator("article.item").filter({ hasText: "G001" });
505
+ await card.getByRole("button", { name: "No", exact: true }).click();
506
+ await card.getByRole("button", { name: "Clear-cut" }).click();
507
+ await page.waitForTimeout(100);
508
+ // Guards: the reasonless «no» never reaches the store; the answer without a reason does.
509
+ assert.deepEqual(
510
+ (await writes(page)).map((w) => w["answers"]),
511
+ [{ boundary: "clear" }],
512
+ );
513
+ await card.locator("textarea").fill("the output is out of order");
514
+ await card.locator("textarea").blur();
515
+ await page.waitForTimeout(100);
516
+ assert.deepEqual((await writes(page)).at(-1), {
517
+ ...(await writes(page)).at(-1),
518
+ answers: { label: "no", boundary: "clear" },
519
+ reasons: { label: "the output is out of order" },
520
+ });
521
+ } finally {
522
+ await page.context().close();
523
+ }
524
+ },
525
+ BROWSER_TEST_MS,
526
+ );
527
+
528
+ test(
529
+ "🔴 a saved answer changed to one still waiting for its reason stays saved when another question is answered",
530
+ async () => {
531
+ const [label, boundary] = QUESTIONS;
532
+ assert.ok(label !== undefined && boundary !== undefined);
533
+ const withWhy = {
534
+ ...label,
535
+ options: label.options.map((o) =>
536
+ o.value === "no" ? { ...o, ask_why: "Why not?" } : o,
537
+ ),
538
+ };
539
+ const { page: html } = build(
540
+ setup(
541
+ "browser-pending-saved",
542
+ config({ questions: [withWhy, boundary] }),
543
+ ),
544
+ );
545
+ const done = Object.fromEntries(
546
+ PRACTICE.map((p, n) => [
547
+ `r1-P${String(n + 1)}`,
548
+ { answers: p.expected, source: "page" },
549
+ ]),
550
+ );
551
+ const page = await (await sharedBrowser()).newPage();
552
+ try {
553
+ await page.addInitScript(
554
+ STORE(done, 20, {
555
+ G001: {
556
+ answers: { label: "yes", boundary: "clear" },
557
+ reasons: {},
558
+ source: "page",
559
+ },
560
+ }),
561
+ );
562
+ await page.goto("about:blank");
563
+ await page.setContent(html, { waitUntil: "domcontentloaded" });
564
+ const card = page.locator("article.item").filter({ hasText: "G001" });
565
+ await card.getByRole("button", { name: "Change" }).first().click();
566
+ await card.getByRole("button", { name: "No", exact: true }).click();
567
+ await card.getByRole("button", { name: "Change" }).last().click();
568
+ await card.getByRole("button", { name: "Boundary" }).click();
569
+ await page.waitForTimeout(100);
570
+ // Guards: the store keeps «yes» until the reason for «no» is typed; the new boundary is saved.
571
+ assert.deepEqual(
572
+ (await writes(page)).map((w) => w["answers"]),
573
+ [{ label: "yes", boundary: "boundary" }],
574
+ );
575
+ } finally {
576
+ await page.context().close();
577
+ }
578
+ },
579
+ BROWSER_TEST_MS,
580
+ );
581
+
582
+ test(
583
+ "🔴 a stored answer to a question the page no longer asks does not stop the next answer from saving",
584
+ async () => {
585
+ const { page: html } = build(setup("browser-stale-question", approval()));
586
+ const page = await (await sharedBrowser()).newPage();
587
+ try {
588
+ await page.addInitScript(
589
+ STORE(PRACTICE_DONE, 20, {
590
+ G001: { answers: { renamed: "x" }, source: "page" },
591
+ }),
592
+ );
593
+ await page.goto("about:blank");
594
+ await page.setContent(html, { waitUntil: "domcontentloaded" });
595
+ const card = page.locator("article.item").filter({ hasText: "G001" });
596
+ await card.getByRole("button", { name: /Keep/ }).click();
597
+ await page.waitForTimeout(100);
598
+ // Guards: the answer is written, and the stored answer it does not know is kept as it was.
599
+ assert.deepEqual(
600
+ (await writes(page)).map((w) => w["answers"]),
601
+ [{ renamed: "x", keep: "keep" }],
602
+ );
603
+ } finally {
604
+ await page.context().close();
184
605
  }
185
606
  },
186
607
  BROWSER_TEST_MS,