paperlint 13.6.1 → 14.0.0

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

@@ -1,4 +1,4 @@
-import { type RuleRef } from "./rule-descriptions.ts";
+import { type Described as RuleText, type RuleRef } from "./rule-descriptions.ts";
 export declare class Refusal extends Error {
     readonly exitCode: number;
     constructor(exitCode: number, message: string);
@@ -13,8 +13,8 @@ type Json = null | boolean | number | string | readonly Json[] | {
 type JsonObject = {
     readonly [key: string]: Json;
 };
-declare const PAGE_FIELDS: readonly ["group", "title", "body", "code", "context"];
-type SchemaNode = {
+declare const PAGE_FIELDS: readonly ["group", "title", "body", "code", "context", "file"];
+type SchemaNode = ({
     kind: "string";
     required: boolean;
     pattern?: string;
@@ -40,7 +40,16 @@ type SchemaNode = {
     required: boolean;
     closed: boolean;
     fields: Readonly<Record<string, SchemaNode>>;
+}) & {
+    why?: string;
 };
+/**
+ * THE PAGE KINDS, and the card fields each requires on every item and practice card (#373). A fix to
+ * a card is a field; a kind that needs it makes it required, so a page built without it fails the
+ * schema with the field named instead of shipping the old card.
+ */
+type Kind = "approval" | "witness" | "labels";
+/** The declared schema (`schema` prints it): every field, those a kind requires left optional. */
 export declare const CONFIG_SCHEMA: SchemaNode;
 interface Option {
     readonly value: string;
@@ -58,28 +67,33 @@ interface Question {
 interface Unit {
     readonly id: string;
     readonly text: string;
+    readonly mark: string;
     readonly part: number;
     readonly of: number;
 }
-type Item = {
+/** What a card shows, on an item and on a practice item alike. */
+type Card = {
     readonly [F in (typeof PAGE_FIELDS)[number]]?: string;
 } & {
-    readonly source_id: string;
-    readonly group: string;
     readonly body: string;
     readonly rules?: readonly RuleRef[];
     readonly unit?: Unit;
+    readonly readings?: {
+        readonly a: string;
+        readonly b: string;
+    };
 };
-interface Practice {
-    readonly title?: string;
-    readonly body: string;
-    readonly code?: string;
-    readonly context?: string;
+type Item = Card & {
+    readonly source_id: string;
+    readonly group: string;
+};
+type Practice = Card & {
     readonly expected: Readonly<Record<string, string>>;
     readonly why: string;
-}
+};
 interface Config {
     readonly study: string;
+    readonly kind: Kind;
     readonly title: string;
     readonly intro?: string;
     readonly seed: number;
@@ -97,8 +111,8 @@ interface KeyEntry {
     readonly group: string;
     readonly on_page: boolean;
 }
-/** Rule → the linter's description, for every rule an item on the page names. */
-type Described = ReadonlyMap<string, string>;
+/** Rule → the linter's description (and a ruff rule's family), for every rule a card names. */
+type Described = ReadonlyMap<string, RuleText>;
 /** Only what the labeller can answer goes on the page, and only that gets an id, in id order. */
 declare function itemsOnPage(cfg: Config, keyPath: string): {
     items: Item[];
@@ -123,8 +137,21 @@ declare function payloadOf(cfg: Config, page: ReturnType<typeof itemsOnPage>, de
     questions: readonly Question[];
     practice: {
         round: number;
-        items: readonly (Practice & {
-            readonly id: string;
+        items: ({
+            rules?: never;
+            id: string;
+            expected: Readonly<Record<string, string>>;
+            why: string;
+        } | {
+            rules: {
+                description?: string;
+                family?: string;
+                linter: "eslint" | "ruff";
+                id: string;
+            }[];
+            id: string;
+            expected: Readonly<Record<string, string>>;
+            why: string;
         })[];
     };
     items: ({
@@ -132,9 +159,10 @@ declare function payloadOf(cfg: Config, page: ReturnType<typeof itemsOnPage>, de
         id: string;
     } | {
         rules: {
+            description?: string;
+            family?: string;
             linter: "eslint" | "ruff";
             id: string;
-            description: string;
         }[];
         id: string;
     })[];
@@ -162,8 +190,21 @@ export declare function prepareBuild(configPath: string, outDir: string): {
         questions: readonly Question[];
         practice: {
             round: number;
-            items: readonly (Practice & {
-                readonly id: string;
+            items: ({
+                rules?: never;
+                id: string;
+                expected: Readonly<Record<string, string>>;
+                why: string;
+            } | {
+                rules: {
+                    description?: string;
+                    family?: string;
+                    linter: "eslint" | "ruff";
+                    id: string;
+                }[];
+                id: string;
+                expected: Readonly<Record<string, string>>;
+                why: string;
             })[];
         };
         items: ({
@@ -171,9 +212,10 @@ export declare function prepareBuild(configPath: string, outDir: string): {
             id: string;
         } | {
             rules: {
+                description?: string;
+                family?: string;
                 linter: "eslint" | "ruff";
                 id: string;
-                description: string;
             }[];
             id: string;
         })[];

package/dist/skills/build-label-page/scripts/rule-descriptions.d.ts

@@ -2,6 +2,11 @@ export interface RuleRef {
     readonly linter: "eslint" | "ruff";
     readonly id: string;
 }
+/** What the linter says a rule does; a ruff rule also names the family it comes from. */
+export interface Described {
+    readonly description: string;
+    readonly family?: string;
+}
 /** A process run to its end: the exit status and what it printed. */
 export type RunProcess = (cmd: string, args: readonly string[]) => {
     readonly status: number | null;
@@ -9,4 +14,4 @@ export type RunProcess = (cmd: string, args: readonly string[]) => {
 };
 export declare const runProcess: RunProcess;
 /** The linter's own one-line description of `ref`, or undefined when it has none. */
-export declare function describeRule(ref: RuleRef, fromDir: string, run?: RunProcess): string | undefined;
+export declare function describeRule(ref: RuleRef, fromDir: string, run?: RunProcess): Described | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paperlint",
-  "version": "13.6.1",
+  "version": "14.0.0",
   "description": "A linter for scientific papers written in LaTeX: catches mistakes before you submit to a conference or journal.",
   "type": "module",
   "license": "MIT",

package/skills/build-label-page/SKILL.md

@@ -4,7 +4,7 @@ description: Build a phone labelling page published as a claude.ai Artifact with
 allowed-tools: [Read, Write, Edit, Grep, Glob, Bash, Artifact, ArtifactData]
 ---
 
-<!-- vigiles:sha256:bd616b2694831fa1 compiled from skills/build-label-page/SKILL.md.spec.ts -->
+<!-- vigiles:sha256:6e828827dc6fcfc1 compiled from skills/build-label-page/SKILL.md.spec.ts -->
 
 # build-label-page — a page the person labels on a phone, and the labels back in the repo
 
@@ -63,8 +63,8 @@ building. In one line each:
    source labels on the page. The generator refuses to build when an item carries a field outside an
    allow-list; a page written by hand checks its items against the same list.
 5. **Ask only what the labeller can answer.** Only the languages and tools they know; one "how well do
-   you know it" question per group, used later as an analysis filter (off on an approval page,
-   `"familiarity": false`: the author has not seen those repositories); "clear-cut or real boundary"
+   you know it" question per group when the study filters on it (`"familiarity": true`; left
+   out, none is asked, as on an approval page, whose author has not seen those repositories); "clear-cut or real boundary"
    is the labeller's judgement, not the designer's.
 6. **Export into the repository right away**, one JSON per page into the study's `data/` with the
    export date, commit it, and record answers given in chat with `source: "chat"`. If the page fails,
@@ -104,7 +104,8 @@ building. In one line each:
    ```
 
    It writes `label-page/page.html` and `label-page/key.json` (the only link from `G001` to the
-   source id; it never goes on the page). Written by hand, the page meets the requirements above.
+   source id; it never goes on the page). `kind` (`approval`, `witness`, `labels`) is required,
+   and each kind requires its card fields on every item and practice card. Written by hand, the page meets the requirements above.
 4. **Read it as the labeller, then look at it.** Read the page text once as a person who knows
    nothing about the source: if anything on it tells the answer, take it out. Read each question as
    someone who did not design the study: can they tell what each answer means from the question, its

package/skills/build-label-page/SKILL.md.spec.ts

@@ -74,8 +74,8 @@ building. In one line each:
    source labels on the page. The generator refuses to build when an item carries a field outside an
    allow-list; a page written by hand checks its items against the same list.
 5. **Ask only what the labeller can answer.** Only the languages and tools they know; one "how well do
-   you know it" question per group, used later as an analysis filter (off on an approval page,
-   \`"familiarity": false\`: the author has not seen those repositories); "clear-cut or real boundary"
+   you know it" question per group when the study filters on it (\`"familiarity": true\`; left
+   out, none is asked, as on an approval page, whose author has not seen those repositories); "clear-cut or real boundary"
    is the labeller's judgement, not the designer's.
 6. **Export into the repository right away**, one JSON per page into the study's \`data/\` with the
    export date, commit it, and record answers given in chat with \`source: "chat"\`. If the page fails,
@@ -115,7 +115,8 @@ building. In one line each:
    \`\`\`
 
    It writes \`label-page/page.html\` and \`label-page/key.json\` (the only link from \`G001\` to the
-   source id; it never goes on the page). Written by hand, the page meets the requirements above.
+   source id; it never goes on the page). \`kind\` (\`approval\`, \`witness\`, \`labels\`) is required,
+   and each kind requires its card fields on every item and practice card. Written by hand, the page meets the requirements above.
 4. **Read it as the labeller, then look at it.** Read the page text once as a person who knows
    nothing about the source: if anything on it tells the answer, take it out. Read each question as
    someone who did not design the study: can they tell what each answer means from the question, its

package/skills/build-label-page/references/checklist.md

@@ -81,11 +81,11 @@ the text of an allowed field says.
 
 - Restrict the items to the languages and tools the labeller knows (`labeller_knows`). Items of
   other groups are not put on the page and get no id.
-- Add one question per group, "how well do you know this language / tool" (well / somewhat / not
-  really). It is an analysis filter: the study can report the labels with and without the groups
-  the labeller does not know well. An approval page asks none (`"familiarity": false` in
-  `items.json`): its question is about a drawn unit, not about repositories the author has seen,
-  and an answer to "how well do you know the projects of this group" there means nothing.
+- When the study filters on it, ask one question per group, "how well do you know this language /
+  tool" (well / somewhat / not really), with `"familiarity": true` in `items.json`: the study can
+  then report the labels with and without the groups the labeller does not know well. Left out, no
+  page asks it: on an approval page the question is about a drawn unit, not about repositories the
+  author has seen, and "how well do you know the projects of this group" there means nothing.
 - The per-item judgement "clear-cut or a real boundary case" is the labeller's. The study design
   does not decide it in advance and does not pre-fill it.
 
@@ -94,7 +94,7 @@ answer is the only way to find it afterwards. And a boundary case is boundary be
 person hesitates; a designer who tags it in advance has measured the design, not the item.
 
 **Check.** The build prints how many items were left out; the export has a familiarity value for
-every group, or the page was built with `"familiarity": false` and the export has no groups.
+every group, or the page was built without `"familiarity": true` and the export has no groups.
 
 ## 6. Export into the repository right away
 

package/skills/build-label-page/references/closed-choice-generator.md

@@ -33,24 +33,45 @@ length.
   required `example`: a real case of the study, in a line, that takes that answer. `icon` (an
   emoji) is optional. Two labels that read the same, or two equal values, stop the build.
 - **`practice`**: 3 or more real cases whose answer you are sure of, each with `expected` (one answer
-  per question) and a one-line `why`. Never an item that is also on the page to be labelled.
+  per question) and a one-line `why`. Never an item that is also on the page to be labelled. A
+  practice card carries the same fields as the real cards it rehearses (`rules`, `unit`,
+  `readings`, `file`).
 - **`practice_round`**: raise it after rewording a question; the practice reopens and the answers of
   the earlier round are kept but not counted.
 - **`items`**: `source_id` (the study's own, never shown), `group`, `body`, and optionally `title`,
-  `code`, `context`, `rules`, `unit`. Nothing else: the allow-list is fixed in the generator, and a field outside it
-  is taken out of the item, not added to the list to make a build pass.
+  `code`, `context`, `rules`, `unit`, `readings`, `file`. Nothing else: the allow-list is fixed in
+  the generator, and a field outside it is taken out of the item, not added to the list to make a
+  build pass.
+- **`kind`** (required): what the page asks, and so which card fields every item and practice card
+  must carry. A card without one fails the schema, naming the field and why the kind needs it:
+
+  | kind       | the labeller decides                                 | required on every card                             |
+  | ---------- | ---------------------------------------------------- | -------------------------------------------------- |
+  | `approval` | keep or drop a drawn requirement                     | `unit` (the line, the requirement marked), `rules` |
+  | `witness`  | why two readings of a requirement disagree on a file | `rules`, `readings`, `file`                        |
+  | `labels`   | a gold label, a blind review                         | nothing beyond the item                            |
+
+  Nothing reads `context`: it stays free text. A rule, a line or two readings written there show
+  none of what their fields show, so on an `approval` or `witness` page they go in the fields.
+
 - **`rules`**: `[{linter, id}]` (`linter` is `eslint` or `ruff`) on an item read as a linter rule.
-  The card shows "Rule ruff TID253: Checks for module-level imports that should instead be imported
-  lazily…", the description taken at build time from the linter itself: `ruff rule <id>`'s "What it
-  does" paragraph, or the ESLint rule's `meta.docs.description` from the ESLint and plugins
-  installed where `items.json` is. The build refuses a rule the linter cannot describe; a
+  The card's "Rule" row shows "ruff `TID253` (flake8-tidy-imports): Checks for module-level
+  imports that should instead be imported lazily…", taken at build time from the linter itself:
+  `ruff rule <id>`'s "What it does" paragraph and family, or the ESLint rule's
+  `meta.docs.description` from the ESLint and plugins installed where `items.json` is (a plugin
+  rule's own name may hold a slash: `n/no-unsupported-features/node-builtins`). The build refuses a rule the linter cannot describe; a
   description is never typed into `items.json`.
-- **`unit`**: `{id, text, part, of}` on an item that is one requirement of a line holding several
-  ("TypeScript only (no JavaScript); top-level await is allowed" is two). Each requirement is its
-  own item with its own question, and its card shows "From the line (requirement 1 of 2):" and the
-  whole line beneath, so the labeller judges one requirement at a time and sees where it came from.
-  The build refuses a line whose parts do not add up (one missing, repeated, a different `of`, or
-  split across groups), naming the item. `id` names one occurrence of the line (a file and line
+- **`unit`**: `{id, text, mark, part, of}` on an item drawn from a source line: the whole line,
+  the requirement's own words in it (`mark`, shown highlighted), and which requirement of the line
+  it is ("TypeScript only (no JavaScript); top-level await is allowed" is two). The card's "Line"
+  row shows the line with the mark, and "part 1 of 2" when the line holds several. A drawn sample
+  may hold one part of a line and not the others; the build refuses a `mark` that is not in the
+  line, and parts of one line that disagree (another text or `of`, a part repeated, split across
+  groups), naming the item.
+- **`readings`**: `{a, b}` on an item that compares two readings of one requirement: two rows,
+  "Reading A" on a solid accent rule and "Reading B" on a dashed one, in the same place on every
+  card. **`file`**: the witness file (a path, a link, what each reading did with it), on its own
+  "File" row. `id` names one occurrence of the line (a file and line
   number, say) and is never shown: two files holding the same words are two lines, each judged in
   full. Splitting the line is the study's job, before the page.
 - **`seed`**: fixes the order. Rebuilding with the same seed keeps every id, and a new item gets the
@@ -89,9 +110,10 @@ drop, the drop carrying `ask_why`.
 }
 ```
 
-The page sets `"familiarity": false`: the author is judging drawn units, not repositories they
-have seen, so the per-group "how well do you know it" question is left out (and a
-`familiarity_question` beside it is refused).
+The page sets `"kind": "approval"`, so every card carries its `unit` and `rules`, and leaves
+`familiarity` out: the author is judging drawn units, not repositories they have
+seen, so no per-group "how well do you know it" question is asked. Only a page that sets
+`"familiarity": true` asks it (and a `familiarity_question` without it is refused).
 
 The items are the drawn units verbatim, in a language the author reads. Units in other languages
 are taken out before the draw, as a population rule the study's `plan.json` states ("English-language

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

@@ -4,8 +4,13 @@
  * cannot show: focus, typing, and a page that is left without the box ever losing focus.
  */
 import assert from "node:assert/strict";
-import { chromium, type Page } from "playwright-core";
-import { test } from "vitest";
+import {
+  type Browser,
+  chromium,
+  type Locator,
+  type Page,
+} from "playwright-core";
+import { afterAll, test } from "vitest";
 import { z } from "zod";
 import { chromiumPath } from "../../../test/chromium.ts";
 import {
@@ -66,6 +71,20 @@ async function reasonStored(page: Page, text: string): Promise<void> {
   assert.equal(await storedReason(page), text);
 }
 
+/**
+ * One Chromium for the whole file, each test in a context of its own (`newPage` opens one): a launch
+ * per test cost about 5 s apiece on the macOS runner, and the file's wall time grew with every test.
+ */
+let launched: Browser | undefined;
+const sharedBrowser = async (): Promise<Browser> =>
+  (launched ??= await chromium.launch({
+    executablePath: chromiumPath(),
+    args: ["--no-sandbox"],
+  }));
+afterAll(async () => {
+  await launched?.close();
+});
+
 /** A browser test launches Chromium and types: far above vitest's 5 s default on a slow runner. */
 const BROWSER_TEST_MS = 60_000;
 
@@ -76,12 +95,9 @@ async function onApprovalPage(
   filter: "all" | "next" = "all",
 ): Promise<void> {
   const { page: html } = build(setup(name, approval()));
-  const browser = await chromium.launch({
-    executablePath: chromiumPath(),
-    args: ["--no-sandbox"],
-  });
+  const browser = await sharedBrowser();
+  const page = await browser.newPage();
   try {
-    const page = await browser.newPage();
     await page.addInitScript(STORE(PRACTICE_DONE, echoMs));
     await page.goto("about:blank");
     await page.setContent(html, { waitUntil: "domcontentloaded" });
@@ -90,7 +106,7 @@ async function onApprovalPage(
     await page.getByRole("button", { name: /Drop/ }).first().click();
     await steps(page);
   } finally {
-    await browser.close();
+    await page.context().close();
   }
 }
 
@@ -163,12 +179,9 @@ test(
   "a Keep needs no reason and writes none: the page stays quiet",
   async () => {
     const { page: html } = build(setup("browser-keep", approval()));
-    const browser = await chromium.launch({
-      executablePath: chromiumPath(),
-      args: ["--no-sandbox"],
-    });
+    const browser = await sharedBrowser();
+    const page = await browser.newPage();
     try {
-      const page = await browser.newPage();
       await page.addInitScript(STORE(PRACTICE_DONE, 20));
       await page.goto("about:blank");
       await page.setContent(html, { waitUntil: "domcontentloaded" });
@@ -180,7 +193,89 @@ test(
         [{}],
       );
     } finally {
-      await browser.close();
+      await page.context().close();
+    }
+  },
+  BROWSER_TEST_MS,
+);
+
+/** A two-reading card with a long URL and compact JSON: what pushed the page sideways on a phone. */
+const URL_LONG = `https://github.com/a/b/blob/${"0".repeat(40)}/src/a/long/path/to/witness.ts`;
+const WITNESS = {
+  source_id: "s1",
+  group: "python",
+  body: "Warn for unused variables, except those prefixed with `_`",
+  unit: {
+    id: "L",
+    text: "Warn for unused variables",
+    mark: "unused",
+    part: 1,
+    of: 1,
+  },
+  rules: [{ linter: "eslint", id: "no-console" }],
+  readings: {
+    a: `[{"argsIgnorePattern":"^_","varsIgnorePattern":"^_","caughtErrors":"all"}]`,
+    b: "[]",
+  },
+  file: URL_LONG,
+  context: URL_LONG,
+};
+
+/** Where the line, the rule, reading A, reading B and the question sit on a card, top to bottom. */
+const blocksOf = async (card: Locator) =>
+  Promise.all(
+    [
+      ".quote",
+      ".row:has(.lbl:text-is('Rule'))",
+      ".reading.a",
+      ".reading.b",
+      ".ask",
+    ].map(async (sel) => card.locator(sel).first().boundingBox()),
+  );
+
+test(
+  "🔴 at phone width the card reads by position: line, rule, reading A above reading B, then the question; nothing pushes the page sideways",
+  async () => {
+    const { page: html } = build(
+      setup("browser-layout", approval({ items: [WITNESS] })),
+    );
+    const page = await (
+      await sharedBrowser()
+    ).newPage({ viewport: { width: 400, height: 900 } });
+    try {
+      await page.addInitScript(STORE(PRACTICE_DONE, 20));
+      await page.setContent(html, { waitUntil: "domcontentloaded" });
+      const card = page.locator("article.item").last();
+      const boxes = await blocksOf(card);
+      const [line, rule, a, b, ask] = boxes;
+      assert.ok(line && rule && a && b && ask, "every block is on the card");
+      // Guards: each block below the one before, A and B in one column, a gap before the question.
+      assert.deepEqual(
+        boxes
+          .slice(1)
+          .map(
+            (x, i) =>
+              (x?.y ?? 0) >= (boxes[i]?.y ?? 0) + (boxes[i]?.height ?? 0),
+          ),
+        [true, true, true, true],
+      );
+      assert.equal(a.x, b.x);
+      assert.ok(ask.y - (b.y + b.height) >= 16, "space before the question");
+      assert.deepEqual(
+        await card
+          .locator(".reading")
+          .evaluateAll((els) =>
+            els.map((e) => getComputedStyle(e).borderLeftStyle),
+          ),
+        ["solid", "dashed"],
+      );
+      // Guards: a long URL or compact JSON wraps; the page itself never scrolls sideways.
+      assert.equal(
+        await page.evaluate(() => document.documentElement.scrollWidth),
+        400,
+      );
+    } finally {
+      await page.context().close();
     }
   },
   BROWSER_TEST_MS,