paperlint 14.4.0 → 14.6.0

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

@@ -105,6 +105,7 @@ interface Blocks {
     readonly situation?: {
         readonly summary?: string;
         readonly question: string;
+        readonly from?: string;
     };
     readonly excerpt?: {
         readonly file?: string;
@@ -115,10 +116,13 @@ interface Blocks {
         readonly annotation?: string;
         readonly caption?: string;
         readonly mark_label?: string;
+        readonly from?: string;
+        readonly caption_from?: string;
     };
     readonly quote?: {
         readonly text: string;
         readonly source?: string;
+        readonly from?: string;
     };
     readonly terms?: readonly Term[];
     readonly answer_notes?: Readonly<Record<string, Readonly<Record<string, string>>>>;
@@ -193,8 +197,50 @@ interface Config {
     readonly practice: readonly Practice[];
     readonly practice_round?: number;
     readonly labels?: Readonly<Record<string, string>>;
+    readonly sources?: Readonly<Record<string, string>>;
+    readonly lang?: string;
+    readonly translations?: Readonly<Record<string, Translation>>;
     readonly items: readonly Item[];
 }
+interface QuestionWords {
+    readonly text: string;
+    readonly short?: string;
+    readonly options: Readonly<Record<string, {
+        readonly label: string;
+        readonly example: string;
+        readonly ask_why?: string;
+    }>>;
+}
+/** The page's own words in one more language (#394). */
+interface Translation {
+    readonly title?: string;
+    readonly intro?: string;
+    readonly labels?: Readonly<Record<string, string>>;
+    readonly situation_question?: string;
+    readonly sources?: Readonly<Record<string, string>>;
+    readonly questions: Readonly<Record<string, QuestionWords>>;
+}
+/** The colours the page has for tags (`.tag.s0` to `.tag.s4` in page-template.html), in `sources` order. */
+export declare const SOURCE_COLOURS = 5;
+/**
+ * Every language of the page with its words whole, the translations checked: each covers every
+ * question and answer of the page and names none it does not have, and gives an intro, a reason
+ * prompt and a situation question exactly where the page shows one. A label it leaves out reads as
+ * in the page's own language.
+ */
+declare function translationsOf(cfg: Config): {
+    [x: string]: {
+        questions: Question[];
+        situation_question?: string;
+        sources?: Readonly<Record<string, string>>;
+        title: string;
+        intro: string;
+        labels: {
+            [x: string]: string;
+        };
+    };
+};
+type Translated = ReturnType<typeof translationsOf>;
 interface KeyEntry {
     readonly source_id: string;
     readonly group: string;
@@ -212,7 +258,61 @@ declare function itemsOnPage(cfg: Config, keyPath: string): {
     idOf: (i: Item) => 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): {
+declare function payloadOf(cfg: Config, page: ReturnType<typeof itemsOnPage>, described: Described, translated: Translated): {
+    questions: readonly Question[];
+    practice: {
+        round: number;
+        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: ({
+        answerers?: readonly string[];
+        rules?: never;
+        id: string;
+    } | {
+        answerers?: readonly string[];
+        rules: {
+            description?: string;
+            family?: string;
+            linter: "eslint" | "ruff";
+            id: string;
+        }[];
+        id: string;
+    })[];
+    lang?: string;
+    answerers?: readonly string[];
+    min_seconds?: number;
+    groups: {
+        id: string;
+        label: string;
+    }[];
+    familiarity_question: string;
+    familiarity: {
+        value: string;
+        label: string;
+    }[];
+    allowed: JsonObject;
+    sources?: never;
+    title: string;
+    intro: string;
+    labels: {
+        [x: string]: string;
+    };
+} | {
     questions: readonly Question[];
     practice: {
         round: number;
@@ -247,13 +347,144 @@ declare function payloadOf(cfg: Config, page: ReturnType<typeof itemsOnPage>, de
         }[];
         id: string;
     })[];
+    lang: string;
+    translations: {
+        [x: string]: {
+            questions: Question[];
+            situation_question?: string;
+            sources?: Readonly<Record<string, string>>;
+            title: string;
+            intro: string;
+            labels: {
+                [x: string]: string;
+            };
+        };
+    };
     answerers?: readonly string[];
     min_seconds?: number;
+    groups: {
+        id: string;
+        label: string;
+    }[];
+    familiarity_question: string;
+    familiarity: {
+        value: string;
+        label: string;
+    }[];
+    allowed: JsonObject;
+    sources?: never;
     title: string;
     intro: string;
     labels: {
         [x: string]: string;
     };
+} | {
+    questions: readonly Question[];
+    practice: {
+        round: number;
+        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: ({
+        answerers?: readonly string[];
+        rules?: never;
+        id: string;
+    } | {
+        answerers?: readonly string[];
+        rules: {
+            description?: string;
+            family?: string;
+            linter: "eslint" | "ruff";
+            id: string;
+        }[];
+        id: string;
+    })[];
+    lang?: string;
+    answerers?: readonly string[];
+    min_seconds?: number;
+    groups: {
+        id: string;
+        label: string;
+    }[];
+    familiarity_question: string;
+    familiarity: {
+        value: string;
+        label: string;
+    }[];
+    allowed: JsonObject;
+    sources: {
+        id: string;
+        label: string;
+    }[];
+    title: string;
+    intro: string;
+    labels: {
+        [x: string]: string;
+    };
+} | {
+    questions: readonly Question[];
+    practice: {
+        round: number;
+        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: ({
+        answerers?: readonly string[];
+        rules?: never;
+        id: string;
+    } | {
+        answerers?: readonly string[];
+        rules: {
+            description?: string;
+            family?: string;
+            linter: "eslint" | "ruff";
+            id: string;
+        }[];
+        id: string;
+    })[];
+    lang: string;
+    translations: {
+        [x: string]: {
+            questions: Question[];
+            situation_question?: string;
+            sources?: Readonly<Record<string, string>>;
+            title: string;
+            intro: string;
+            labels: {
+                [x: string]: string;
+            };
+        };
+    };
+    answerers?: readonly string[];
+    min_seconds?: number;
     groups: {
         id: string;
         label: string;
@@ -264,6 +495,15 @@ declare function payloadOf(cfg: Config, page: ReturnType<typeof itemsOnPage>, de
         label: string;
     }[];
     allowed: JsonObject;
+    sources: {
+        id: string;
+        label: string;
+    }[];
+    title: string;
+    intro: string;
+    labels: {
+        [x: string]: string;
+    };
 };
 export type Payload = ReturnType<typeof payloadOf>;
 /**
@@ -307,13 +547,75 @@ export declare function prepareBuild(configPath: string, outDir: string): {
             }[];
             id: string;
         })[];
+        lang?: string;
         answerers?: readonly string[];
         min_seconds?: number;
+        groups: {
+            id: string;
+            label: string;
+        }[];
+        familiarity_question: string;
+        familiarity: {
+            value: string;
+            label: string;
+        }[];
+        allowed: JsonObject;
+        sources?: never;
         title: string;
         intro: string;
         labels: {
             [x: string]: string;
         };
+    } | {
+        questions: readonly Question[];
+        practice: {
+            round: number;
+            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: ({
+            answerers?: readonly string[];
+            rules?: never;
+            id: string;
+        } | {
+            answerers?: readonly string[];
+            rules: {
+                description?: string;
+                family?: string;
+                linter: "eslint" | "ruff";
+                id: string;
+            }[];
+            id: string;
+        })[];
+        lang: string;
+        translations: {
+            [x: string]: {
+                questions: Question[];
+                situation_question?: string;
+                sources?: Readonly<Record<string, string>>;
+                title: string;
+                intro: string;
+                labels: {
+                    [x: string]: string;
+                };
+            };
+        };
+        answerers?: readonly string[];
+        min_seconds?: number;
         groups: {
             id: string;
             label: string;
@@ -324,6 +626,138 @@ export declare function prepareBuild(configPath: string, outDir: string): {
             label: string;
         }[];
         allowed: JsonObject;
+        sources?: never;
+        title: string;
+        intro: string;
+        labels: {
+            [x: string]: string;
+        };
+    } | {
+        questions: readonly Question[];
+        practice: {
+            round: number;
+            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: ({
+            answerers?: readonly string[];
+            rules?: never;
+            id: string;
+        } | {
+            answerers?: readonly string[];
+            rules: {
+                description?: string;
+                family?: string;
+                linter: "eslint" | "ruff";
+                id: string;
+            }[];
+            id: string;
+        })[];
+        lang?: string;
+        answerers?: readonly string[];
+        min_seconds?: number;
+        groups: {
+            id: string;
+            label: string;
+        }[];
+        familiarity_question: string;
+        familiarity: {
+            value: string;
+            label: string;
+        }[];
+        allowed: JsonObject;
+        sources: {
+            id: string;
+            label: string;
+        }[];
+        title: string;
+        intro: string;
+        labels: {
+            [x: string]: string;
+        };
+    } | {
+        questions: readonly Question[];
+        practice: {
+            round: number;
+            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: ({
+            answerers?: readonly string[];
+            rules?: never;
+            id: string;
+        } | {
+            answerers?: readonly string[];
+            rules: {
+                description?: string;
+                family?: string;
+                linter: "eslint" | "ruff";
+                id: string;
+            }[];
+            id: string;
+        })[];
+        lang: string;
+        translations: {
+            [x: string]: {
+                questions: Question[];
+                situation_question?: string;
+                sources?: Readonly<Record<string, string>>;
+                title: string;
+                intro: string;
+                labels: {
+                    [x: string]: string;
+                };
+            };
+        };
+        answerers?: readonly string[];
+        min_seconds?: number;
+        groups: {
+            id: string;
+            label: string;
+        }[];
+        familiarity_question: string;
+        familiarity: {
+            value: string;
+            label: string;
+        }[];
+        allowed: JsonObject;
+        sources: {
+            id: string;
+            label: string;
+        }[];
+        title: string;
+        intro: string;
+        labels: {
+            [x: string]: string;
+        };
     };
     dropped: number;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paperlint",
-  "version": "14.4.0",
+  "version": "14.6.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:ed201d81c5934675 compiled from skills/build-label-page/SKILL.md.spec.ts -->
+<!-- vigiles:sha256:c5863cfb5f123f19 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
 
@@ -158,6 +158,26 @@ Two optional top-level keys of `items.json`, both left out by default:
 Details and the export's shape: [`references/closed-choice-generator.md`](references/closed-choice-generator.md),
 "Two answerers, and a minimum time on screen".
 
+## A second language
+
+A labeller who reads another language better gets the page's own words in it: `"translations": {"ru":
+{…}}` (and `"lang"`, the page's own, `en` by default) adds a switch under the title. The questions,
+answers, examples, reason prompts, intro and labels change; the quote, the code and every note never
+do, because those words are what is judged. The build refuses a translation that leaves out or
+invents a question or an answer; the ids and `key.json` are the same with or without it.
+[`references/closed-choice-generator.md`](references/closed-choice-generator.md), "A second
+language for the page's own words".
+
+## A source tag above each block
+
+When the labeller must tell where a block's text came from (copied from a repository, written by the
+model under test, restated by an earlier labelling model, counted by the script), the page's
+`"sources": {"repo": "From the repository", …}` names the tags, in colour order (at most five), and
+`from` on a `quote`, a `situation` (its summary) or an `excerpt` (`caption_from` for its caption)
+puts one above that block. The build refuses an unknown id, a dead entry and a tag over a text the card
+lacks. [`references/closed-choice-generator.md`](references/closed-choice-generator.md), "A source tag
+above each block".
+
 ## 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

@@ -169,6 +169,26 @@ Two optional top-level keys of \`items.json\`, both left out by default:
 Details and the export's shape: [\`references/closed-choice-generator.md\`](references/closed-choice-generator.md),
 "Two answerers, and a minimum time on screen".
 
+## A second language
+
+A labeller who reads another language better gets the page's own words in it: \`"translations": {"ru":
+{…}}\` (and \`"lang"\`, the page's own, \`en\` by default) adds a switch under the title. The questions,
+answers, examples, reason prompts, intro and labels change; the quote, the code and every note never
+do, because those words are what is judged. The build refuses a translation that leaves out or
+invents a question or an answer; the ids and \`key.json\` are the same with or without it.
+[\`references/closed-choice-generator.md\`](references/closed-choice-generator.md), "A second
+language for the page's own words".
+
+## A source tag above each block
+
+When the labeller must tell where a block's text came from (copied from a repository, written by the
+model under test, restated by an earlier labelling model, counted by the script), the page's
+\`"sources": {"repo": "From the repository", …}\` names the tags, in colour order (at most five), and
+\`from\` on a \`quote\`, a \`situation\` (its summary) or an \`excerpt\` (\`caption_from\` for its caption)
+puts one above that block. The build refuses an unknown id, a dead entry and a tag over a text the card
+lacks. [\`references/closed-choice-generator.md\`](references/closed-choice-generator.md), "A source tag
+above each block".
+
 ## 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

@@ -229,6 +229,8 @@ Any card may carry these blocks, on any `kind`, and each one is optional. The pa
   | `hidden`           | a `⋮` row for lines left out                                    | `lines {from}–{to}`            |
   | `hidden_one`       | a `⋮` row for one line left out                                 | `line {from}`                  |
   | `wait`             | the bar under the answers while `min_seconds` runs              | `⏳ You can answer in {s} s`   |
+  | `how_to`           | the heading of the first screen's questions and examples        | `📖 How to answer`             |
+  | `for_example`      | text before each example on the first screen                    | `For example: `                |
 
 - The leak guard reads every string these blocks render, one string at a time.
 
@@ -286,6 +288,108 @@ 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.
 
+## A second language for the page's own words
+
+For a labeller who reads another language better (#394). Both keys are optional and top-level; left
+out, the page is exactly as above.
+
+```jsonc
+{
+  "lang": "en", // the language of the page's own words; "en" when left out
+  "translations": {
+    "ru": {
+      "title": "…", // optional: the page's title when left out
+      "intro": "…", // given exactly when the page has an `intro`
+      "labels": {
+        "place": "Карточка {n} из {total}",
+        "how_to": "📖 Как отвечать",
+        "for_example": "Например: ",
+      },
+      "situation_question": "Эти слова запрещают строку {n}?", // given exactly when a card has a `situation`
+      "questions": {
+        "forbid": {
+          "text": "…",
+          "short": "…", // optional: the translated `text` stands in for it
+          "options": {
+            "forbid": { "label": "Запрещают", "example": "…" },
+            "cannot": { "label": "…", "example": "…", "ask_why": "…" },
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+- **What changes with the language:** the title, the intro, the `labels`, every question's text and
+  short form, every answer's label and example, every reason prompt (`ask_why`), and the first question
+  as the cards with a `situation` ask it. The first screen's rows ("How to answer") change too.
+- **What never does:** the quote and its source, the code, the annotation, the term notes, the
+  answer sub-lines (`answer_notes`), a situation's `summary`, and every other card field. Those words
+  are what the labeller judges; a translated quote would be a different item.
+- **`situation_question`** replaces each card's own `situation.question` in that language. `{n}` is
+  the number of the card's first marked line; `{line}` works as in `situation`. Either one on a card
+  without an `excerpt` is refused by path.
+- **Refused, by path:** a translation into the page's own `lang`; a question or an answer it leaves
+  out, or one the page does not have; two answers whose labels read the same; an `intro`, an
+  `ask_why` or a `situation_question` given where the page has none, or missing where it has one.
+- **Left out on purpose:** a label the translation does not give reads as in the page's language.
+  The page's fixed words ("Practice", "Change", "Saved", "Next unanswered", "Who is answering?")
+  and the word «line» that `{line}` writes stay in English.
+- **The switch** sits under the title (`data-test="lang-switch"`), one button per language with its
+  tag ("EN", "RU"). The choice is kept in the browser's localStorage under `label-lang` when it has
+  one.
+- **Ids and key:** the neutral ids, the store's documents, `key.json` and the export are the same,
+  byte for byte, with or without translations.
+
+## A source tag above each block
+
+For a labeller who cannot tell where a block's text came from: some of it copied from a repository,
+some written by a model under test, some by an earlier labelling model, some counted by the study's
+script (#400). A small coloured tag above the block says which. All fields are optional; a page
+without `sources` shows no tag, and its config, store documents and key are unchanged.
+
+```jsonc
+{
+  // id → the tag's label, in colour order (at most 5 ids: the page has five colours)
+  "sources": {
+    "repo": "From the repository",
+    "ours": "Our labelling model's restatement",
+    "model": "Written by the model under test",
+    "count": "Counted by our script",
+  },
+  "items": [
+    {
+      "quote": { "text": "…", "source": "…", "from": "repo" }, // tags the quote and its source line
+      "situation": { "summary": "…", "question": "…", "from": "ours" }, // tags the summary, not the question
+      "excerpt": {
+        "lines": [],
+        "caption": "…",
+        "from": "repo",
+        "caption_from": "count",
+      }, // the box, the caption under it
+    },
+  ],
+  "translations": { "ru": { "sources": { "repo": "Из репозитория" } } },
+}
+```
+
+- **`from`** names an id of `sources`, on `quote`, `situation` and `excerpt`; **`caption_from`**
+  on `excerpt` tags the caption. Practice items take the same fields. The question is the page's own
+  words and gets no tag.
+- **On the page:** a small uppercase pill directly above the block. Its colour is the id's place in
+  `sources` (accent, green, amber, red, grey-blue: tokens the page already has). Each carries
+  `data-test="source-tag"` and `data-test-meta` `{"source": "<id>", "block": "quote" | "situation" |
+"excerpt" | "caption"}`.
+- **Refused, by path:** a `from` or `caption_from` with no `sources` on the page; one naming an id not
+  in `sources`; one over a text the card does not have (a `caption_from` without a `caption`, a
+  situation `from` without a `summary`); a `sources` id no item or practice item names; an empty
+  label; more than 5 ids; a `translations.<lang>.sources` id the page's `sources` lack.
+- **Translations:** `translations.<lang>.sources` gives the tag labels in that language. A label it
+  leaves out reads as in the page's own language.
+- **A tag is not a blind-page field:** it shows the labeller where text came from. Use it only where
+  the study allows the labeller to know; a study that blinds the source must not name one.
+
 ## 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