paperlint 14.1.0 → 14.2.0

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

@@ -146,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>>;
@@ -159,6 +160,8 @@ 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[];
@@ -171,6 +174,8 @@ 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>;
@@ -183,21 +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;
-    labels: {
-        [x: string]: string;
-    };
-    groups: {
-        id: string;
-        label: string;
-    }[];
-    familiarity_question: string;
-    familiarity: {
-        value: string;
-        label: string;
-    }[];
-    allowed: JsonObject;
     questions: readonly Question[];
     practice: {
         round: number;
@@ -219,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;
@@ -230,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>;
 /**
@@ -239,21 +248,6 @@ export type Payload = ReturnType<typeof payloadOf>;
  */
 export declare function prepareBuild(configPath: string, outDir: string): {
     payload: {
-        title: string;
-        intro: string;
-        labels: {
-            [x: string]: string;
-        };
-        groups: {
-            id: string;
-            label: string;
-        }[];
-        familiarity_question: string;
-        familiarity: {
-            value: string;
-            label: string;
-        }[];
-        allowed: JsonObject;
         questions: readonly Question[];
         practice: {
             round: number;
@@ -275,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;
@@ -286,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paperlint",
-  "version": "14.1.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:64e09e4a829be441 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
 
@@ -142,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

@@ -153,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

@@ -246,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

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

@@ -0,0 +1,381 @@
+/**
+ * Two people answer the same page (`answerers`), and a card must be on screen a while before its
+ * answer saves (`min_seconds`): the build's checks, the key, the dump check and the export. The page
+ * itself is label-page-browser.test.ts. Each check both ways: quiet on a good input, refusing a bad one.
+ */
+import assert from "node:assert/strict";
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import * as R from "remeda";
+import { test } from "vitest";
+import { z } from "zod";
+import {
+  DONE_PRACTICE,
+  ITEMS,
+  config,
+  exportAt,
+  labelsFile,
+  run,
+  setup,
+} from "../../../test/label-page-kit.ts";
+
+/** Four items: three shown to both answerers, the fourth to `author` only. */
+const FOUR = [
+  ...ITEMS.slice(0, 3),
+  R.merge(ITEMS[3], { answerers: ["author"] }),
+];
+const TWO = (over: Record<string, unknown> = {}) =>
+  config({ answerers: ["author", "second"], items: FOUR, ...over });
+
+const RawKey = z
+  .object({
+    answerers: z.array(z.string()).optional(),
+    min_seconds: z.number().optional(),
+    ids: z.record(
+      z.string(),
+      z
+        .object({ source_id: z.string(), answerers: z.unknown().optional() })
+        .loose(),
+    ),
+  })
+  .loose();
+const keyOf = (dir: string) =>
+  RawKey.parse(JSON.parse(readFileSync(join(dir, "out", "key.json"), "utf8")));
+const buildAt = (dir: string) =>
+  run(["build", join(dir, "items.json"), join(dir, "out")]);
+/** The neutral id of the item drawn from `case-<n>`. */
+const nidOf = (dir: string, n: number): string => {
+  const hit = R.entries(keyOf(dir).ids).find(
+    ([, v]) => v.source_id === `case-${String(1000 + n)}`,
+  );
+  assert.ok(hit !== undefined);
+  return hit[0];
+};
+const dumpAt = (dir: string, dump: unknown): void => {
+  writeFileSync(join(dir, "dump.json"), JSON.stringify(dump));
+};
+const prefixed = (who: string, docs: Record<string, unknown>) =>
+  R.mapKeys(docs, (k) => `${who}~${k}`);
+
+test("🔴 build refuses answerers that two people could not tell apart, and an item's subset naming someone unknown", () => {
+  const cases: readonly (readonly [string, Record<string, unknown>, string])[] =
+    [
+      [
+        "one",
+        { answerers: ["author"] },
+        "answerers: needs 2 or more entries, has 1",
+      ],
+      [
+        "twice",
+        { answerers: ["author", "second", "author"] },
+        "answerers[2]: 'author' is repeated",
+      ],
+      [
+        "separator",
+        { answerers: ["author", "a~b"] },
+        "answerers[1]: 'a~b' must be letters",
+      ],
+      [
+        "unknown",
+        {
+          answerers: ["author", "second"],
+          items: [{ ...ITEMS[0], answerers: ["third"] }],
+        },
+        "items[0].answerers[0]: 'third' is not in `answerers` (author, second)",
+      ],
+      [
+        "item-twice",
+        {
+          answerers: ["author", "second"],
+          items: [{ ...ITEMS[0], answerers: ["second", "second"] }],
+        },
+        "items[0].answerers[1]: 'second' is repeated",
+      ],
+      [
+        "no-page-list",
+        { items: [{ ...ITEMS[0], answerers: ["author"] }] },
+        "items[0].answerers: the page has no `answerers` — add the page's list, or take this out",
+      ],
+      ["zero", { min_seconds: 0 }, "min_seconds: 0 — must be 1 or more"],
+    ];
+  for (const [name, over, message] of cases) {
+    const r = buildAt(setup(`answerers-refuse-${name}`, config(over)));
+    assert.notEqual(r.status, 0, name);
+    assert.ok(r.out.includes(`REFUSED: ${message}`), `${name}\n${r.out}`);
+  }
+});
+
+test("🔴 the key carries the answerers, each item's own subset and min_seconds; the page gets them", () => {
+  const dir = setup("answerers-key", TWO({ min_seconds: 30 }));
+  const r = buildAt(dir);
+  assert.equal(r.status, 0, r.out);
+  const key = keyOf(dir);
+  assert.deepEqual(key.answerers, ["author", "second"]);
+  assert.equal(key.min_seconds, 30);
+  assert.deepEqual(key.ids[nidOf(dir, 3)]?.answerers, ["author"]);
+  assert.equal(key.ids[nidOf(dir, 0)]?.answerers, undefined);
+  const page = readFileSync(join(dir, "out", "page.html"), "utf8");
+  assert.match(page, /"answerers": \["author", "second"\]/);
+  assert.match(page, /"min_seconds": 30/);
+  assert.match(page, /"answerers": \["author"\]/);
+});
+
+/** What the export writes for one stored document of the page's own: no reason, saved now. */
+const exported = (
+  answers: Record<string, string | null>,
+  more: Record<string, unknown> = {},
+) =>
+  R.merge(
+    {
+      answers,
+      invalid_answers: {},
+      reasons: {},
+      unexplained: [],
+      complete: Object.values(answers).every((v) => v !== null),
+      source: "page",
+      saved_at: null,
+    },
+    more,
+  );
+const YES = { label: "yes", boundary: "clear" };
+const NONE = { label: null, boundary: null };
+const noFamiliarity = { familiarity: null, invalid_familiarity: null };
+
+test("🔴 without answerers or min_seconds, the key, the page data and the export are what they were", () => {
+  const dir = setup("answerers-none", config({ items: ITEMS.slice(0, 2) }));
+  assert.equal(buildAt(dir).status, 0);
+  const rawKey = readFileSync(join(dir, "out", "key.json"), "utf8");
+  assert.doesNotMatch(rawKey, /answerers|min_seconds/);
+  const page = readFileSync(join(dir, "out", "page.html"), "utf8");
+  assert.doesNotMatch(page, /"answerers"|"min_seconds"/);
+  const [a, b] = [nidOf(dir, 0), nidOf(dir, 1)];
+  const saved = "2026-01-02T10:00:00Z";
+  dumpAt(dir, {
+    answers: { [a]: { answers: YES, savedAt: saved, source: "page" } },
+    groups: { rust: { familiarity: "well", source: "page" } },
+    practice: DONE_PRACTICE,
+  });
+  const r = exportAt(dir);
+  assert.equal(r.status, 0, r.out);
+  // The labels list the items in id order.
+  const items = R.sortBy(
+    [
+      [
+        a,
+        exported(YES, {
+          id: a,
+          source_id: "case-1000",
+          group: "rust",
+          saved_at: saved,
+        }),
+      ],
+      [
+        b,
+        exported(NONE, {
+          id: b,
+          source_id: "case-1001",
+          group: "python",
+          source: null,
+        }),
+      ],
+    ] as const,
+    ([id]) => id,
+  ).map(([, item]) => item);
+  assert.deepEqual(JSON.parse(labelsFile(dir)), {
+    study: "demo-gold",
+    exported: "2026-01-02",
+    questions: ["label", "boundary"],
+    items,
+    // Object keys compare in any order: deepEqual reads them as a set.
+    groups: {
+      rust: R.merge(noFamiliarity, {
+        familiarity: "well",
+        source: "page",
+        saved_at: null,
+      }),
+      python: R.merge(noFamiliarity, { source: null, saved_at: null }),
+    },
+    complete_items: 1,
+    invalid_items: 0,
+    invalid_groups: 0,
+    total_items: 2,
+  });
+});
+
+/** The four-item page answered by both: author all but one, second one of three; then exported. */
+function exportTwo() {
+  const dir = setup("answerers-export", TWO({ min_seconds: 30 }));
+  assert.equal(buildAt(dir).status, 0);
+  const [a, d] = [nidOf(dir, 0), nidOf(dir, 3)];
+  const no = { label: "no", boundary: "clear" };
+  dumpAt(dir, {
+    answers: {
+      [`author~${a}`]: { answers: YES, seconds: 41, source: "page" },
+      [`second~${a}`]: { answers: no, seconds: 33, source: "page" },
+      [`author~${d}`]: { answers: YES, seconds: 30, source: "page" },
+    },
+    groups: { "author~rust": { familiarity: "well", source: "page" } },
+    practice: {
+      ...prefixed("author", DONE_PRACTICE),
+      "second~r1-P1": { answers: YES, source: "page" },
+    },
+  });
+  const r = exportAt(dir);
+  assert.equal(r.status, 0, r.out);
+  const file = z
+    .object({
+      answerers: z.array(z.string()),
+      items: z.array(
+        z
+          .object({
+            id: z.string(),
+            by_answerer: z.record(z.string(), z.unknown()),
+          })
+          .loose(),
+      ),
+      by_answerer: z.record(
+        z.string(),
+        z.object({
+          complete_items: z.number(),
+          total_items: z.number(),
+          groups: z.record(z.string(), z.unknown()),
+        }),
+      ),
+    })
+    .loose()
+    .parse(JSON.parse(labelsFile(dir)));
+  return { dir, out: r.out, file, a, d, no };
+}
+
+test("🔴 export keeps each answerer's answers to an item apart, with the seconds on screen", () => {
+  const { file, a, d, no } = exportTwo();
+  assert.deepEqual(file.answerers, ["author", "second"]);
+  assert.deepEqual(
+    file.items.find((i) => i.id === a),
+    {
+      id: a,
+      source_id: "case-1000",
+      group: "rust",
+      answerers: ["author", "second"],
+      by_answerer: {
+        author: exported(YES, { seconds: 41 }),
+        second: exported(no, { seconds: 33 }),
+      },
+    },
+  );
+  assert.deepEqual(
+    Object.keys(file.items.find((i) => i.id === d)?.by_answerer ?? { none: 1 }),
+    ["author"],
+  );
+});
+
+test("🔴 export counts, reports and scores the practice per answerer", () => {
+  const { dir, out, file } = exportTwo();
+  assert.deepEqual(
+    R.mapValues(file.by_answerer, (c) => [
+      c.complete_items,
+      c.total_items,
+      R.keys(c.groups).sort(),
+    ]),
+    {
+      author: [2, 4, ["go", "python", "rust"]],
+      second: [1, 3, ["go", "python", "rust"]],
+    },
+  );
+  assert.match(
+    out,
+    /author: 2 of 4 items complete; second: 1 of 3 items complete/,
+  );
+  assert.match(
+    out,
+    new RegExp(`incomplete second~${nidOf(dir, 1)}: missing label, boundary`),
+  );
+  assert.match(out, /group second~rust: no familiarity answer/);
+  // Each answerer's practice is scored on its own, into its own file.
+  assert.match(out, /practice round 1 \(author\): 3 of 3 matched/);
+  assert.match(
+    out,
+    /practice round 1 \(second\): 1 of 3 matched; missed P2, P3/,
+  );
+  const second = z
+    .object({ answerer: z.string(), matched: z.number() })
+    .loose()
+    .parse(
+      JSON.parse(
+        readFileSync(
+          join(dir, "data", "demo-gold-practice-r1-second-2026-01-02.json"),
+          "utf8",
+        ),
+      ),
+    );
+  assert.deepEqual([second.answerer, second.matched], ["second", 1]);
+});
+
+test("🔴 export refuses a document of no answerer, of an unknown one, or of an item not shown to its answerer", () => {
+  const dir = setup("answerers-refuse-dump", TWO({ min_seconds: 30 }));
+  assert.equal(buildAt(dir).status, 0);
+  const [a, d] = [nidOf(dir, 0), nidOf(dir, 3)];
+  const doc = { answers: { label: "yes" }, source: "page" };
+  const cases: readonly (readonly [string, unknown, string])[] = [
+    [
+      "plain",
+      { answers: { [a]: doc } },
+      `answers/${a}: this page has answerers (author, second), so a document's id is <answerer>~<id>`,
+    ],
+    [
+      "stranger",
+      { answers: { [`third~${a}`]: doc } },
+      `answers/third~${a}: 'third' is not an answerer of this page (author, second)`,
+    ],
+    [
+      "not-shown",
+      { answers: { [`second~${d}`]: doc } },
+      `answers/second~${d}: the key does not know this answer for second`,
+    ],
+    [
+      "group-plain",
+      { groups: { rust: { familiarity: "well", source: "page" } } },
+      "groups/rust: this page has answerers",
+    ],
+    [
+      "practice-unknown",
+      { practice: { "second~r1-P9": { answers: {}, source: "page" } } },
+      "practice/second~r1-P9: the key does not know this practice item",
+    ],
+    [
+      "seconds",
+      {
+        answers: {
+          [`author~${a}`]: R.merge(doc, { seconds: "long" }),
+        },
+      },
+      `answers/author~${a}/seconds: 'long' — must be a whole number of seconds or null`,
+    ],
+  ];
+  for (const [name, dump, message] of cases) {
+    dumpAt(dir, dump);
+    const r = exportAt(dir);
+    assert.notEqual(r.status, 0, name);
+    assert.ok(r.out.includes(`REFUSED: ${message}`), `${name}\n${r.out}`);
+  }
+});
+
+test("🔴 without answerers, a prefixed document id is a document the key does not know", () => {
+  const dir = setup("answerers-none-prefixed", config());
+  assert.equal(buildAt(dir).status, 0);
+  const a = nidOf(dir, 0);
+  dumpAt(dir, {
+    answers: { [`author~${a}`]: { answers: {}, source: "page" } },
+  });
+  const r = exportAt(dir);
+  assert.notEqual(r.status, 0);
+  assert.match(r.out, new RegExp(`answers/author~${a}: the key does not know`));
+  // Nor does a page built without min_seconds store seconds.
+  dumpAt(dir, {
+    answers: { [a]: { answers: {}, seconds: 3, source: "page" } },
+  });
+  assert.match(
+    exportAt(dir).out,
+    new RegExp(`answers/${a}/seconds: not a field of a stored answer`),
+  );
+});