paperlint 14.0.0 → 14.2.0

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

@@ -18,6 +18,9 @@ type SchemaNode = ({
     kind: "string";
     required: boolean;
     pattern?: string;
+} | {
+    kind: "text";
+    required: boolean;
 } | {
     kind: "integer";
     required: boolean;
@@ -71,10 +74,67 @@ interface Unit {
     readonly part: number;
     readonly of: number;
 }
+interface TextField {
+    readonly label?: string;
+    readonly text: string;
+    readonly style?: string;
+}
+interface CodeLine {
+    readonly n: number;
+    readonly text: string;
+    readonly mark: boolean;
+}
+/** The content blocks (#380), each optional on any kind. */
+interface Blocks {
+    readonly situation?: {
+        readonly summary: string;
+        readonly question: string;
+    };
+    readonly excerpt?: {
+        readonly file?: string;
+        readonly url?: string;
+        readonly lines: readonly CodeLine[];
+        readonly caption?: string;
+        readonly mark_label?: string;
+    };
+    readonly references?: {
+        readonly summary: string;
+        readonly entries: readonly {
+            readonly label?: string;
+            readonly title: string;
+            readonly fields: readonly TextField[];
+            readonly url?: string;
+            readonly url_label?: string;
+        }[];
+    };
+    readonly more?: {
+        readonly summary: string;
+        readonly items: readonly string[];
+        readonly rest?: string;
+    };
+    readonly table?: {
+        readonly summary: string;
+        readonly note?: string;
+        readonly rows: readonly {
+            readonly label: string;
+            readonly value: string;
+            readonly plain?: string;
+            readonly mark?: {
+                readonly tone: string;
+                readonly text: string;
+            };
+        }[];
+    };
+    readonly repeat?: {
+        readonly group: string;
+        readonly index: number;
+        readonly of: number;
+    };
+}
 /** What a card shows, on an item and on a practice item alike. */
 type Card = {
     readonly [F in (typeof PAGE_FIELDS)[number]]?: string;
-} & {
+} & Blocks & {
     readonly body: string;
     readonly rules?: readonly RuleRef[];
     readonly unit?: Unit;
@@ -86,6 +146,7 @@ type Card = {
 type Item = Card & {
     readonly source_id: string;
     readonly group: string;
+    readonly answerers?: readonly string[];
 };
 type Practice = Card & {
     readonly expected: Readonly<Record<string, string>>;
@@ -99,17 +160,22 @@ interface Config {
     readonly seed: number;
     readonly groups: Readonly<Record<string, string>>;
     readonly labeller_knows?: readonly string[];
+    readonly answerers?: readonly string[];
+    readonly min_seconds?: number;
     readonly familiarity?: boolean;
     readonly familiarity_question?: string;
     readonly questions: readonly Question[];
     readonly practice: readonly Practice[];
     readonly practice_round?: number;
+    readonly labels?: Readonly<Record<string, string>>;
     readonly items: readonly Item[];
 }
 interface KeyEntry {
     readonly source_id: string;
     readonly group: string;
     readonly on_page: boolean;
+    /** Who the item is shown to, when not every answerer of the page. */
+    readonly answerers?: readonly string[];
 }
 /** Rule → the linter's description (and a ruff rule's family), for every rule a card names. */
 type Described = ReadonlyMap<string, RuleText>;
@@ -122,18 +188,6 @@ declare function itemsOnPage(cfg: Config, keyPath: string): {
 };
 /** What a page shows: the questions, the practice and the items, blind, with their neutral ids. */
 declare function payloadOf(cfg: Config, page: ReturnType<typeof itemsOnPage>, described: Described): {
-    title: string;
-    intro: string;
-    groups: {
-        id: string;
-        label: string;
-    }[];
-    familiarity_question: string;
-    familiarity: {
-        value: string;
-        label: string;
-    }[];
-    allowed: JsonObject;
     questions: readonly Question[];
     practice: {
         round: number;
@@ -155,9 +209,11 @@ declare function payloadOf(cfg: Config, page: ReturnType<typeof itemsOnPage>, de
         })[];
     };
     items: ({
+        answerers?: readonly string[];
         rules?: never;
         id: string;
     } | {
+        answerers?: readonly string[];
         rules: {
             description?: string;
             family?: string;
@@ -166,6 +222,23 @@ declare function payloadOf(cfg: Config, page: ReturnType<typeof itemsOnPage>, de
         }[];
         id: string;
     })[];
+    answerers?: readonly string[];
+    min_seconds?: number;
+    title: string;
+    intro: string;
+    labels: {
+        [x: string]: string;
+    };
+    groups: {
+        id: string;
+        label: string;
+    }[];
+    familiarity_question: string;
+    familiarity: {
+        value: string;
+        label: string;
+    }[];
+    allowed: JsonObject;
 };
 export type Payload = ReturnType<typeof payloadOf>;
 /**
@@ -175,18 +248,6 @@ export type Payload = ReturnType<typeof payloadOf>;
  */
 export declare function prepareBuild(configPath: string, outDir: string): {
     payload: {
-        title: string;
-        intro: string;
-        groups: {
-            id: string;
-            label: string;
-        }[];
-        familiarity_question: string;
-        familiarity: {
-            value: string;
-            label: string;
-        }[];
-        allowed: JsonObject;
         questions: readonly Question[];
         practice: {
             round: number;
@@ -208,9 +269,11 @@ export declare function prepareBuild(configPath: string, outDir: string): {
             })[];
         };
         items: ({
+            answerers?: readonly string[];
             rules?: never;
             id: string;
         } | {
+            answerers?: readonly string[];
             rules: {
                 description?: string;
                 family?: string;
@@ -219,6 +282,23 @@ export declare function prepareBuild(configPath: string, outDir: string): {
             }[];
             id: string;
         })[];
+        answerers?: readonly string[];
+        min_seconds?: number;
+        title: string;
+        intro: string;
+        labels: {
+            [x: string]: string;
+        };
+        groups: {
+            id: string;
+            label: string;
+        }[];
+        familiarity_question: string;
+        familiarity: {
+            value: string;
+            label: string;
+        }[];
+        allowed: JsonObject;
     };
     dropped: number;
 };

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

@@ -0,0 +1,10 @@
+/** A preset's result: the config in the generic shape, or why it cannot be made. */
+export type Preset = {
+    readonly ok: true;
+    readonly value: unknown;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/** The config with its preset applied; a config without `preset` comes back as it was. */
+export declare function applyPreset(raw: unknown): Preset;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paperlint",
-  "version": "14.0.0",
+  "version": "14.2.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:6e828827dc6fcfc1 compiled from skills/build-label-page/SKILL.md.spec.ts -->
+<!-- vigiles:sha256:dce0979d7f187ae7 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
 
@@ -105,7 +105,11 @@ 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). `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.
+   and each kind requires its card fields on every item and practice card. Any card may also carry
+   the generic content blocks (a code excerpt with a marked line, references, a list, a table), every
+   word on them from `items.json`, with the question right under the excerpt. `"preset":
+   "linter-config-witness"` is a narrow preset for comparing linter configs; the blocks underneath
+   are generic. 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
@@ -138,6 +142,20 @@ building. In one line each:
    same pass, and add the line "labels → `data/<study>-labels-<date>.json`" to the paper's
    `NOTES.md` for the numbers that use them.
 
+## Two answerers, and a time on screen
+
+Two optional top-level keys of `items.json`, both left out by default:
+
+- `"answerers": ["author", "second"]` — two or more people answer the same published page, each
+  under their own name (picked on the page) and without seeing the other's answers; an item's own
+  `answerers` shows it to that subset only. The store's ids become `<answerer>~<id>`, and the
+  labels file keeps each answerer's answers under `by_answerer`.
+- `"min_seconds": 30` — a card's answer saves only after the card has been on screen that long;
+  the seconds at its first save are stored and exported as `seconds`.
+
+Details and the export's shape: [`references/closed-choice-generator.md`](references/closed-choice-generator.md),
+"Two answerers, and a minimum time on screen".
+
 ## When the page misbehaves
 
 Look at what the store holds (`ArtifactData` `list`) before changing anything: the page may be fine

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

@@ -116,7 +116,11 @@ 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). \`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.
+   and each kind requires its card fields on every item and practice card. Any card may also carry
+   the generic content blocks (a code excerpt with a marked line, references, a list, a table), every
+   word on them from \`items.json\`, with the question right under the excerpt. \`"preset":
+   "linter-config-witness"\` is a narrow preset for comparing linter configs; the blocks underneath
+   are generic. 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
@@ -149,6 +153,20 @@ building. In one line each:
    same pass, and add the line "labels → \`data/<study>-labels-<date>.json\`" to the paper's
    \`NOTES.md\` for the numbers that use them.
 
+## Two answerers, and a time on screen
+
+Two optional top-level keys of \`items.json\`, both left out by default:
+
+- \`"answerers": ["author", "second"]\` — two or more people answer the same published page, each
+  under their own name (picked on the page) and without seeing the other's answers; an item's own
+  \`answerers\` shows it to that subset only. The store's ids become \`<answerer>~<id>\`, and the
+  labels file keeps each answerer's answers under \`by_answerer\`.
+- \`"min_seconds": 30\` — a card's answer saves only after the card has been on screen that long;
+  the seconds at its first save are stored and exported as \`seconds\`.
+
+Details and the export's shape: [\`references/closed-choice-generator.md\`](references/closed-choice-generator.md),
+"Two answerers, and a minimum time on screen".
+
 ## When the page misbehaves
 
 Look at what the store holds (\`ArtifactData\` \`list\`) before changing anything: the page may be fine

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

@@ -21,7 +21,11 @@ with the core's payload. Another page shape would be another template on the sam
 Rules 2 to 5, 7 and the page half of 8 of [`checklist.md`](checklist.md): a filter instead of
 scrolling, complete-item counting, neutral ids in a seeded order, the leak guard (an item field
 outside the allow-list stops the build), save on click with a time, the store-unavailable banner,
-the "How to answer" screen, the practice before the real items, one question per screen. Its look:
+the "How to answer" screen (folded into a toggle once the practice is done), the practice before
+the real items, one question per screen, each card's place (`labels.place`, by default
+"G007 · 7 of 20"), the card just
+answered kept under "Next unanswered" until the next answer (so a mis-tap can be changed), and a
+closing line once every item is complete. Its look:
 one dark palette, one column, answer buttons as full-width rows with space between them, an optional
 icon per answer and never a coloured side stripe, `backticks` and the `code` field shown as code,
 code blocks that show leading and trailing whitespace (a space as ·, a tab as →) and each line's
@@ -76,10 +80,130 @@ length.
   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
   next one; a different seed is refused once a key exists.
-- **`ask_why`** on an option: a prompt. That answer is incomplete, on the page and in the export,
-  until a reason is saved. The reason saves as it is typed (after a pause, and when the page is
-  left), so a labeller who closes the page from inside the box does not leave a drop without its
-  reason; a store echo while typing keeps the box and its focus.
+- **`ask_why`** on an option: a prompt. The page does not write that answer to the store until its
+  reason box holds text: the card says «Not saved yet», and the store keeps what it had. The reason
+  then saves with the answer as it is typed (after a pause, and when the page is left); a store echo
+  while typing keeps the box and its focus. An answer stored without its reason (by an older page,
+  or merged from chat) still counts as incomplete, on the page and in the export.
+
+## Content blocks
+
+Any card may carry these blocks, on any `kind`, and each one is optional. The page knows only the shape of each block. Every label and sentence on it comes from `items.json`, so a code review, a prose check or a configuration study each write their own words. A practice card carries the same blocks as the real cards it rehearses. `scripts/fixtures/blocks-items.json` is a whole page of them: a code review, with no preset.
+
+```jsonc
+{
+  "situation": {
+    "summary": "Reviewer A asked for a change at {line}; reviewer B approved it.",
+    "question": "Does «Every query is parameterised» cover {line}?",
+  },
+  "excerpt": {
+    "file": "app/report.py", // optional; with `url`, the name is a link
+    "url": "https://example.com/app/report.py#L12", // optional
+    "lines": [
+      { "n": 11, "text": "def monthly(month):", "mark": false },
+      {
+        "n": 12,
+        "text": "    rows = db.raw(\"SELECT … m=\" + month)",
+        "mark": true,
+      },
+    ],
+    "caption": "Reviewer A wrote: concatenated SQL.", // optional, under the code
+    "mark_label": "◀ the line in question", // optional; default «◀ this line»
+  },
+  "references": {
+    "summary": "What the guideline says", // the folded block's toggle
+    "entries": [
+      {
+        "label": "Guideline", // optional row label
+        "title": "Security guide `SQL-1`",
+        "fields": [
+          { "text": "Build every query with parameters." },
+          { "label": "Why", "text": "Input becomes part of the query." }, // «Why: …»
+          {
+            "style": "note",
+            "text": "The examples below are the guide's own.",
+          },
+          {
+            "label": "Not like this",
+            "style": "code",
+            "text": "db.raw(\"… id=\" + id)",
+          },
+        ],
+        "url": "https://example.com/guide#sql-1", // optional
+        "url_label": "Security guide", // optional; the link text
+      },
+    ],
+  },
+  "more": {
+    "summary": "3 more lines like this",
+    "items": ["`app/export.py`", "`app/admin.py`"],
+    "rest": "and 1 more", // optional, after the items
+  },
+  "table": {
+    "summary": "What each reviewer wrote",
+    "note": "Reviewer A asked for the change; reviewer B approved.", // optional
+    "rows": [
+      {
+        "label": "A only · Comment",
+        "value": "use parameters", // shown as code
+        "plain": "asks for a parameterised query", // optional
+        "mark": { "tone": "yes", "text": "✓ about this line" }, // optional; tone yes or no
+      },
+    ],
+  },
+  "repeat": { "group": "guide-sql", "index": 1, "of": 2 }, // `group` never reaches the page
+}
+```
+
+- **Order on the card.** The card shows, in this order:
+  1. its place (`labels.place`);
+  2. the body, on a `labels.body` row when that label is set;
+  3. the repeat sentence;
+  4. the older fields (`code`, `unit`, `rules`, `readings`, `file`, `context`);
+  5. the situation's summary;
+  6. the excerpt;
+  7. **the question and its answers**;
+  8. `references`, `more` and `table`, each folded and closed.
+
+  The question therefore sits right under the code it names.
+
+- **`situation`**: `{summary, question}`.
+  - `summary` is one sentence above the excerpt.
+  - `question` replaces the text of the page's first question on this card. Other questions keep their own text.
+  - In either text, `{line}` stands for the excerpt's first marked line. The page writes «line N: », then the line's code as code, without its indent. A code line holding a backtick reads as it is.
+  - `{line}` on a card without an `excerpt` is refused by path.
+- **`excerpt`**: at least one line is marked (`mark: true`). The marked line gets a `▶` in the gutter and `mark_label` after its code, and keeps its background, so it reads as marked even without its colour. A line's `text` may be empty, for a blank line.
+- **`references.entries[].fields`**:
+  - A field without `style` is a paragraph («label: text» when it has a label). A long one shows three lines and a «more».
+  - `style: "code"` is a code block on a `label` row.
+  - `style: "note"` is a quiet line.
+- **`table.rows`**: shown in the order given. Each row shows its `label`, then `value` as code, `plain` under it, and `mark` last.
+- **`repeat`**: shows the sentence `labels.repeat` when `of` is more than 1. `index` must lie between 1 and `of`.
+- **`labels`** sits at page level, and every key in it is optional:
+
+  | key                | what it is                                                      | default                        |
+  | ------------------ | --------------------------------------------------------------- | ------------------------------ |
+  | `place`            | the card's place                                                | `{id} · {n} of {total}`        |
+  | `body`             | a row label for the body                                        | none                           |
+  | `line`             | the label of the `unit` row                                     | `Line`                         |
+  | `line_part`        | the `unit` row's label when the line holds several requirements | `{line} · part {part} of {of}` |
+  | `repeat`           | the repeat sentence                                             | `Card {index} of {of}`         |
+  | `practice_example` | text before each answer's example on a practice button          | empty                          |
+
+- The leak guard reads every string these blocks render, one string at a time.
+
+### Presets: named words for a narrow use
+
+A preset is opt-in. An items file names it with `"preset": "<name>"`. The preset maps its own compact card fields onto the blocks above and supplies `labels`. The file's own `labels` override the preset's. The page and the core know nothing of any preset: each one lives in `scripts/label-page-presets.ts`.
+
+- **`linter-config-witness`** is narrow: two linter configs of one requirement disagree on a line of code. The blocks underneath are generic.
+  - **Input fields on a card:**
+    - `example: {file, url?, lines, message, caught_by}`, which becomes the excerpt, with the caption «The linter says: …».
+    - `rules: [{linter, id, explanation}]`, whose explanation has `source` (`ruff rule`, `eslint docs`, `plugin docs`, `config message` or `none`), plus `what`, `why`, `example_bad`, `example_good` and `url`. These become the references, folded under «What the linter rule does (official docs)».
+    - `more_like_this: {count, files}`, which becomes the list «N more file(s) with the same situation».
+    - `details: {a, b}`: rows of `{key, raw, plain, matches_example}`. They become the table «Settings behind this card», with «A only / B only / A and B» rows.
+  - **Its labels**: «Card {n} of {total}», «Requirement», «Card {index} of {of} for this requirement», and «Example of this answer, about other code: ».
+  - `scripts/fixtures/linter-config-witness-items.json` is a whole page of it.
 
 ## The approval page
 
@@ -122,6 +246,48 @@ author cannot read it is an exclusion made after the draw and goes unrecorded. T
 units whose fate is obvious. Each dropped unit carries its reason in the labels file. The author's words, with the date, then go into
 `author_check` of the plan; a dropped unit is replaced by the next one in the draw.
 
+## Two answerers, and a minimum time on screen
+
+Both keys are optional and top-level. Left out, the page, its store documents and the export are
+exactly as above.
+
+- **`answerers`**: two or more names (letters, digits, `-` and `_`), for a study where two people
+  answer the same published page, each under their own name and without seeing the other's
+  answers. The page first asks "Who is answering?"; the choice is kept in the browser's
+  localStorage when it has one (otherwise it asks again on every visit), and "Switch" beside
+  "Answering as …" asks again. Every document the page writes is named `<answerer>~<id>`
+  (`second~G004`, `second~r1-P2`, `second~python`): `~` is outside the name pattern, so no answerer,
+  item, group or practice id can hold it. The page reads only the current answerer's documents, so
+  their progress, done-state and practice are their own. An item may carry its own `answerers`, a
+  subset of the page's: it is shown only to those. A name an item lists that the page does not, a
+  name twice, or an item's list on a page without one stops the build.
+- **`min_seconds`**: an item's answer saves only after its card has been on screen that long. The
+  cards are a list, so "on screen" is measured by an `IntersectionObserver`: half the card in view,
+  or half the viewport filled by a card taller than that, while the tab is visible. A locked card
+  shows "You can answer in N s" under its disabled buttons. The answer document gains `seconds`:
+  how long the card had been on screen at its first save, kept on every later save. The practice
+  cards are not held.
+
+`key.json` carries `answerers`, each item's own subset (`ids.<id>.answerers`, only where it has one)
+and `min_seconds`. With `answerers`, `export` refuses a document id without `<answerer>~`, an
+answerer the key does not list, and an answer to an item not shown to its answerer, as it refuses
+an unknown item. The labels file keeps each answerer's answers apart:
+
+```text
+{ "answerers": ["author", "second"],
+  "items": [{ "id": "G001", "source_id": "case-1000", "group": "python",
+              "answerers": ["author", "second"],
+              "by_answerer": { "author": { "answers": { "label": "yes" }, "complete": true,
+                                           "seconds": 41, "…": "the fields of an item above" },
+                               "second": { "…": "…" } } }],
+  "by_answerer": { "author": { "groups": {}, "complete_items": 1, "total_items": 1, "…": "…" },
+                   "second": { "…": "…" } } }
+```
+
+An answerer with no document for an item is still listed, with every answer `null`. Each
+answerer's practice is scored into its own file, `<study>-practice-r<round>-<answerer>-<date>.json`.
+`seconds` appears only when the page was built with `min_seconds`.
+
 ## The export
 
 `export` reads the store's three collections (`answers`, `groups`, `practice`) from `dump.json`, in