paperlint 14.0.0 → 14.1.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;
@@ -104,6 +164,7 @@ interface Config {
     readonly questions: readonly Question[];
     readonly practice: readonly Practice[];
     readonly practice_round?: number;
+    readonly labels?: Readonly<Record<string, string>>;
     readonly items: readonly Item[];
 }
 interface KeyEntry {
@@ -124,6 +185,9 @@ declare function itemsOnPage(cfg: Config, keyPath: string): {
 declare function payloadOf(cfg: Config, page: ReturnType<typeof itemsOnPage>, described: Described): {
     title: string;
     intro: string;
+    labels: {
+        [x: string]: string;
+    };
     groups: {
         id: string;
         label: string;
@@ -177,6 +241,9 @@ export declare function prepareBuild(configPath: string, outDir: string): {
     payload: {
         title: string;
         intro: string;
+        labels: {
+            [x: string]: string;
+        };
         groups: {
             id: string;
             label: string;

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.1.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:64e09e4a829be441 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

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

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
 

package/skills/build-label-page/scripts/fixtures/blocks-items.json

@@ -0,0 +1,214 @@
+{
+  "study": "demo-review",
+  "kind": "labels",
+  "title": "Review comments",
+  "intro": "Each card shows one guideline, one changed line and one question about that line.",
+  "seed": 5,
+  "groups": { "all": "Review comments" },
+  "labels": {
+    "place": "Comment {n} of {total}",
+    "body": "Guideline",
+    "repeat": "Comment {index} of {of} on this guideline",
+    "practice_example": "Another case: "
+  },
+  "questions": [
+    {
+      "id": "applies",
+      "text": "Does the guideline cover this line?",
+      "short": "covered?",
+      "options": [
+        {
+          "value": "yes",
+          "label": "Yes",
+          "icon": "✅",
+          "example": "«No string-built SQL» and an f-string query"
+        },
+        {
+          "value": "no",
+          "label": "No",
+          "icon": "🚫",
+          "example": "«No string-built SQL» and a log message"
+        },
+        {
+          "value": "unclear",
+          "label": "Unclear",
+          "icon": "↔️",
+          "example": "«Short functions» and a 40-line function",
+          "ask_why": "What makes it unclear?"
+        }
+      ]
+    }
+  ],
+  "practice": [
+    {
+      "body": "Every query is parameterised",
+      "situation": {
+        "summary": "One reviewer asked for a change at {line}; the other approved it.",
+        "question": "Does «Every query is parameterised» cover {line}?"
+      },
+      "excerpt": {
+        "file": "app/orders.py",
+        "lines": [
+          { "n": 41, "text": "def total(order_id):", "mark": false },
+          {
+            "n": 42,
+            "text": "    sql = f\"SELECT * FROM o WHERE id={order_id}\"",
+            "mark": true
+          }
+        ],
+        "caption": "Reviewer A wrote: build this query with parameters."
+      },
+      "expected": { "applies": "yes" },
+      "why": "The value goes into the query text."
+    },
+    {
+      "body": "Every query is parameterised",
+      "situation": {
+        "summary": "One reviewer flagged {line}; the other did not.",
+        "question": "Does «Every query is parameterised» cover {line}?"
+      },
+      "excerpt": {
+        "file": "app/log.py",
+        "lines": [
+          {
+            "n": 7,
+            "text": "log.info(f\"order {order_id} paid\")",
+            "mark": true
+          }
+        ]
+      },
+      "expected": { "applies": "no" },
+      "why": "A log line is not a query."
+    },
+    {
+      "body": "Functions stay short",
+      "situation": {
+        "summary": "One reviewer asked to split the function; the other did not.",
+        "question": "Does «Functions stay short» cover this function?"
+      },
+      "excerpt": {
+        "file": "app/cart.py",
+        "lines": [
+          { "n": 1, "text": "def checkout(cart):", "mark": true },
+          { "n": 2, "text": "    ...", "mark": false }
+        ],
+        "caption": "The function is 40 lines long."
+      },
+      "expected": { "applies": "unclear" },
+      "why": "«Short» has no number."
+    }
+  ],
+  "items": [
+    {
+      "source_id": "review-sql-1",
+      "group": "all",
+      "body": "Every query is parameterised",
+      "repeat": { "group": "guide-sql", "index": 1, "of": 2 },
+      "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",
+        "url": "https://example.com/shop/blob/0000000/app/report.py#L12",
+        "lines": [
+          { "n": 11, "text": "def monthly(month):", "mark": false },
+          {
+            "n": 12,
+            "text": "    rows = db.raw(\"SELECT * FROM sales WHERE m=\" + month)",
+            "mark": true
+          },
+          { "n": 13, "text": "", "mark": false },
+          { "n": 14, "text": "    return rows", "mark": false }
+        ],
+        "caption": "Reviewer A wrote: concatenated SQL.",
+        "mark_label": "◀ the line in question"
+      },
+      "references": {
+        "summary": "What the guideline says",
+        "entries": [
+          {
+            "label": "Guideline",
+            "title": "Security guide `SQL-1`",
+            "fields": [
+              { "text": "Build every query with parameters, never by joining strings." },
+              {
+                "label": "Why",
+                "text": "A query built from strings lets input become part of the query, and a value a user typed can then change what the query does: read other rows, change data, or drop a table. Parameters keep data and query apart in every driver the shop uses."
+              },
+              { "style": "note", "text": "The examples below are the guide's own." },
+              {
+                "label": "Not like this",
+                "style": "code",
+                "text": "db.raw(\"SELECT * FROM t WHERE id=\" + id)"
+              },
+              {
+                "label": "Like this",
+                "style": "code",
+                "text": "db.raw(\"SELECT * FROM t WHERE id=%s\", [id])"
+              }
+            ],
+            "url": "https://example.com/guide#sql-1",
+            "url_label": "Security guide"
+          }
+        ]
+      },
+      "more": {
+        "summary": "3 more lines like this",
+        "items": ["`app/export.py`", "`app/admin.py`"],
+        "rest": "and 1 more"
+      },
+      "table": {
+        "summary": "What each reviewer wrote",
+        "note": "Reviewer A asked for the change; reviewer B approved.",
+        "rows": [
+          {
+            "label": "A only · Comment",
+            "value": "use parameters",
+            "plain": "asks for a parameterised query",
+            "mark": { "tone": "yes", "text": "✓ about this line" }
+          },
+          {
+            "label": "B only · Approval",
+            "value": "LGTM",
+            "mark": { "tone": "no", "text": "✗ says nothing about this line" }
+          }
+        ]
+      }
+    },
+    {
+      "source_id": "review-sql-2",
+      "group": "all",
+      "body": "Every query is parameterised",
+      "repeat": { "group": "guide-sql", "index": 2, "of": 2 },
+      "situation": {
+        "summary": "Only one reviewer commented on {line}.",
+        "question": "Does «Every query is parameterised» cover {line}?"
+      },
+      "excerpt": {
+        "file": "app/search.py",
+        "lines": [
+          {
+            "n": 30,
+            "text": "    q = `SELECT * FROM items WHERE name LIKE '${term}'`",
+            "mark": true
+          }
+        ]
+      }
+    },
+    {
+      "source_id": "review-short-1",
+      "group": "all",
+      "body": "Functions stay short",
+      "situation": {
+        "summary": "One reviewer asked to split the function, the other did not.",
+        "question": "Does «Functions stay short» cover this function?"
+      },
+      "excerpt": {
+        "lines": [
+          { "n": 1, "text": "def import_orders(path):", "mark": true }
+        ]
+      }
+    }
+  ]
+}