paperlint 14.5.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,6 +197,7 @@ 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[];
@@ -212,8 +217,11 @@ interface Translation {
     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
@@ -224,6 +232,7 @@ declare function translationsOf(cfg: Config): {
     [x: string]: {
         questions: Question[];
         situation_question?: string;
+        sources?: Readonly<Record<string, string>>;
         title: string;
         intro: string;
         labels: {
@@ -287,11 +296,6 @@ declare function payloadOf(cfg: Config, page: ReturnType<typeof itemsOnPage>, de
     lang?: string;
     answerers?: readonly string[];
     min_seconds?: number;
-    title: string;
-    intro: string;
-    labels: {
-        [x: string]: string;
-    };
     groups: {
         id: string;
         label: string;
@@ -302,6 +306,12 @@ declare function payloadOf(cfg: Config, page: ReturnType<typeof itemsOnPage>, de
         label: string;
     }[];
     allowed: JsonObject;
+    sources?: never;
+    title: string;
+    intro: string;
+    labels: {
+        [x: string]: string;
+    };
 } | {
     questions: readonly Question[];
     practice: {
@@ -342,6 +352,7 @@ declare function payloadOf(cfg: Config, page: ReturnType<typeof itemsOnPage>, de
         [x: string]: {
             questions: Question[];
             situation_question?: string;
+            sources?: Readonly<Record<string, string>>;
             title: string;
             intro: string;
             labels: {
@@ -351,11 +362,60 @@ declare function payloadOf(cfg: Config, page: ReturnType<typeof itemsOnPage>, de
     };
     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;
@@ -366,6 +426,84 @@ 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;
+    };
+} | {
+    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;
+    };
 };
 export type Payload = ReturnType<typeof payloadOf>;
 /**
@@ -412,11 +550,6 @@ export declare function prepareBuild(configPath: string, outDir: string): {
         lang?: string;
         answerers?: readonly string[];
         min_seconds?: number;
-        title: string;
-        intro: string;
-        labels: {
-            [x: string]: string;
-        };
         groups: {
             id: string;
             label: string;
@@ -427,6 +560,12 @@ 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: {
@@ -467,6 +606,7 @@ export declare function prepareBuild(configPath: string, outDir: string): {
             [x: string]: {
                 questions: Question[];
                 situation_question?: string;
+                sources?: Readonly<Record<string, string>>;
                 title: string;
                 intro: string;
                 labels: {
@@ -476,11 +616,60 @@ export declare function prepareBuild(configPath: string, outDir: 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;
@@ -491,6 +680,84 @@ export declare function prepareBuild(configPath: string, outDir: 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.5.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:46ebfc043d459ff0 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
 
@@ -168,6 +168,16 @@ invents a question or an answer; the ids and `key.json` are the same with or wit
 [`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

@@ -179,6 +179,16 @@ invents a question or an answer; the ids and \`key.json\` are the same with or w
 [\`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

@@ -342,6 +342,54 @@ out, the page is exactly as above.
 - **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

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

@@ -1000,9 +1000,10 @@ async function onV7Page(
     cardOf: (sourceId: string) => Promise<Locator>,
   ) => Promise<void>,
   withTime = false,
+  cfg: Record<string, unknown> = V7_CONFIG,
 ): Promise<void> {
   const { page: html, key } = build(
-    setup(name, withTime ? V7_CONFIG : R.omit(V7_CONFIG, ["min_seconds"])),
+    setup(name, withTime ? cfg : R.omit(cfg, ["min_seconds"])),
   );
   const done = ["forbid", "allow", "elsewhere"];
   const page = await (
@@ -1635,3 +1636,128 @@ test(
   },
   BROWSER_TEST_MS,
 );
+
+const TAG_LABELS = {
+  repo: "From the repository",
+  ours: "Our restatement",
+  model: "Written by the model under test",
+  count: "Counted by our script",
+};
+const TAG_LABELS_RU = {
+  repo: "Из репозитория",
+  ours: "Пересказ нашей модели",
+  model: "Написано проверяемой моделью",
+  count: "Посчитано нашим скриптом",
+};
+const Raw = z.record(z.string(), z.unknown());
+/** A card's block as the fixture has it, with more fields. */
+const withIn = (
+  card: Record<string, unknown>,
+  block: string,
+  more: object,
+) => ({
+  ...card,
+  [block]: { ...Raw.parse(card[block]), ...more },
+});
+/** The v7 fixture with tags: the docstring card has all four kinds, the call card a quote tag only, the depth card none. */
+const TAGGED_CONFIG = {
+  ...V7_CONFIG,
+  sources: TAG_LABELS,
+  translations: { ru: { ...Raw.parse(RU_RAW), sources: TAG_LABELS_RU } },
+  items: V7_CONFIG.items.map((raw, n) => {
+    const card = Raw.parse(raw);
+    return n === 0
+      ? withIn(
+          withIn(withIn(card, "quote", { from: "repo" }), "situation", {
+            from: "ours",
+            summary: "A reviewer objected to this line.",
+          }),
+          "excerpt",
+          {
+            from: "model",
+            caption: "Counted over the file.",
+            caption_from: "count",
+          },
+        )
+      : n === 1
+        ? withIn(card, "quote", { from: "ours" })
+        : card;
+  }),
+};
+const SourceTag = z.object({ source: z.string(), block: z.string() });
+/** Each source tag of a card: its values and its text. */
+const tagsOn = async (card: Locator) =>
+  Promise.all(
+    (await allByKind(card, "source-tag")).map(async (t) => ({
+      ...SourceTag.parse(t.meta),
+      text: await t.loc.textContent(),
+    })),
+  );
+/** How far a tag's bottom edge is above the top of the block it tags (negative: not above). */
+const gapAbove = async (tag: Locator, block: Locator) => {
+  const [t, b] = [await tag.boundingBox(), await block.boundingBox()];
+  assert.ok(t !== null && b !== null);
+  return b.y - (t.y + t.height);
+};
+
+test(
+  "🔴 each tagged block gets a tag with its source id right above it, the label follows the language, and an untagged card has none",
+  async () => {
+    await onV7Page(
+      "browser-v7-source-tags",
+      async (page, cardOf) => {
+        const docstring = await cardOf("card-docstring");
+        assert.deepEqual(await tagsOn(docstring), [
+          { source: "repo", block: "quote", text: TAG_LABELS.repo },
+          { source: "ours", block: "situation", text: TAG_LABELS.ours },
+          { source: "model", block: "excerpt", text: TAG_LABELS.model },
+          { source: "count", block: "caption", text: TAG_LABELS.count },
+        ]);
+        assert.deepEqual(await tagsOn(await cardOf("card-call")), [
+          { source: "ours", block: "quote", text: TAG_LABELS.ours },
+        ]);
+        // Guards: a card whose blocks name no source has no tag at all.
+        assert.deepEqual(await tagsOn(await cardOf("card-depth")), []);
+        const tags = docstring.getByTestId("source-tag");
+        const gaps = [
+          await gapAbove(tags.nth(0), docstring.getByTestId("quote")),
+          await gapAbove(tags.nth(2), docstring.getByTestId("excerpt-path")),
+        ];
+        // Guards: the tag sits above its block, close to it, never beside or below.
+        assert.ok(
+          gaps.every((g) => g >= 0 && g < 16),
+          JSON.stringify(gaps),
+        );
+        const switchTo = async (lang: string) =>
+          (await allByKind(page, "lang-option"))
+            .find(
+              (o) => z.object({ lang: z.string() }).parse(o.meta).lang === lang,
+            )
+            ?.loc.click();
+        await switchTo("ru");
+        assert.deepEqual(
+          (await tagsOn(await cardOf("card-docstring"))).map((t) => t.text),
+          [
+            TAG_LABELS_RU.repo,
+            TAG_LABELS_RU.ours,
+            TAG_LABELS_RU.model,
+            TAG_LABELS_RU.count,
+          ],
+        );
+      },
+      false,
+      TAGGED_CONFIG,
+    );
+  },
+  BROWSER_TEST_MS,
+);
+
+test(
+  "a page without sources draws no source tag",
+  async () => {
+    await onV7Page("browser-v7-no-source-tags", async (page) => {
+      assert.equal(await page.getByTestId("source-tag").count(), 0);
+    });
+  },
+  BROWSER_TEST_MS,
+);