paperlint 10.1.1 → 10.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (72) hide show
  1. package/README.md +2 -0
  2. package/dist/adapters/study-registry/index.d.ts +357 -0
  3. package/dist/adapters/study-registry/index.d.ts.map +1 -0
  4. package/dist/adapters/study-registry/index.js +221 -0
  5. package/dist/adapters/study-registry/index.js.map +1 -0
  6. package/dist/cli.d.ts.map +1 -1
  7. package/dist/cli.js +42 -2
  8. package/dist/cli.js.map +1 -1
  9. package/dist/domain/repro-layout.d.ts +12 -4
  10. package/dist/domain/repro-layout.d.ts.map +1 -1
  11. package/dist/domain/repro-layout.js +49 -18
  12. package/dist/domain/repro-layout.js.map +1 -1
  13. package/dist/domain/scaffold-layout.d.ts +4 -3
  14. package/dist/domain/scaffold-layout.d.ts.map +1 -1
  15. package/dist/domain/scaffold-layout.js +7 -4
  16. package/dist/domain/scaffold-layout.js.map +1 -1
  17. package/dist/domain/study-registry.d.ts +372 -0
  18. package/dist/domain/study-registry.d.ts.map +1 -0
  19. package/dist/domain/study-registry.js +593 -0
  20. package/dist/domain/study-registry.js.map +1 -0
  21. package/dist/ports/study-registry-codec.d.ts +15 -0
  22. package/dist/ports/study-registry-codec.d.ts.map +1 -0
  23. package/dist/ports/study-registry-codec.js +2 -0
  24. package/dist/ports/study-registry-codec.js.map +1 -0
  25. package/dist/repro-layout-rule.d.ts.map +1 -1
  26. package/dist/repro-layout-rule.js +4 -3
  27. package/dist/repro-layout-rule.js.map +1 -1
  28. package/dist/studies.d.ts +27 -0
  29. package/dist/studies.d.ts.map +1 -0
  30. package/dist/studies.js +163 -0
  31. package/dist/studies.js.map +1 -0
  32. package/dist/study-registry-rule.d.ts +24 -0
  33. package/dist/study-registry-rule.d.ts.map +1 -0
  34. package/dist/study-registry-rule.js +145 -0
  35. package/dist/study-registry-rule.js.map +1 -0
  36. package/docs/design/study-registry.md +246 -0
  37. package/docs/layout.md +51 -46
  38. package/docs/rules/paper/allowed-files-only.md +3 -2
  39. package/docs/rules/repro/allowed-files-only.md +40 -30
  40. package/docs/rules/repro/study-plan-name.md +70 -0
  41. package/docs/rules/repro/study-registered.md +320 -0
  42. package/docs/rules/study/declare-sample.md +1 -1
  43. package/docs/rules.md +53 -51
  44. package/package.json +1 -1
  45. package/skills/build-benchmark/SKILL.md +39 -8
  46. package/skills/build-benchmark/SKILL.md.spec.ts +38 -7
  47. package/skills/build-label-page/SKILL.md +14 -9
  48. package/skills/build-label-page/SKILL.md.spec.ts +13 -8
  49. package/skills/paper-pipeline/references/artifact-checklist.md +2 -1
  50. package/skills/paper-pipeline/references/pipeline-status-template.md +5 -3
  51. package/skills/run-agent-grid/SKILL.md +13 -1
  52. package/skills/run-agent-grid/SKILL.md.spec.ts +12 -0
  53. package/src/adapters/study-registry/index.test.ts +484 -0
  54. package/src/adapters/study-registry/index.ts +328 -0
  55. package/src/cli.ts +53 -2
  56. package/src/domain/paper-layout.test.ts +1 -1
  57. package/src/domain/repro-layout.test.ts +18 -9
  58. package/src/domain/repro-layout.ts +58 -18
  59. package/src/domain/scaffold-layout.ts +7 -4
  60. package/src/domain/study-measurements.test.ts +629 -0
  61. package/src/domain/study-registry.test.ts +666 -0
  62. package/src/domain/study-registry.ts +1044 -0
  63. package/src/folder-layout-hook.test.ts +10 -0
  64. package/src/new-paper.test.ts +29 -2
  65. package/src/ports/study-registry-codec.ts +15 -0
  66. package/src/repro-layout-rule.ts +4 -3
  67. package/src/rule-cases.test.ts +68 -0
  68. package/src/studies-cli.test.ts +113 -0
  69. package/src/studies.test.ts +359 -0
  70. package/src/studies.ts +268 -0
  71. package/src/study-registry-rule.test.ts +456 -0
  72. package/src/study-registry-rule.ts +239 -0
@@ -145,9 +145,19 @@ describe("paper-folder-layout hook — allows", () => {
145
145
  expect(reason(`${DIR}/reviews/2026-10-12-x.md`)).toBeNull();
146
146
  expect(reason(`${DIR}/extra/anything.bin`)).toBeNull();
147
147
  expect(reason(`${DIR}/repro/README.md`)).toBeNull();
148
+ expect(reason(`${DIR}/repro/studies.json`)).toBeNull();
148
149
  expect(reason(`${DIR}/repro/tools/paper_numbers.py`)).toBeNull();
149
150
  expect(reason(`${DIR}/repro/data/numbers.tsv`)).toBeNull();
150
151
  });
152
+ });
153
+
154
+ describe("paper-folder-layout hook — a new study folder", () => {
155
+ it("a registered study folder started with its README.md; the first file otherwise is refused", () => {
156
+ expect(reason(`${DIR}/repro/P1-S01-ablation/README.md`)).toBeNull();
157
+ expect(reason(`${DIR}/repro/P1-S01-ablation/run.py`)).toMatch(
158
+ /^`repro\/P1-S01-ablation\/` is a study folder without a README\.md/,
159
+ );
160
+ });
151
161
 
152
162
  it("a new study folder started with its README.md, then any file in it", () => {
153
163
  expect(reason(`${DIR}/repro/ablation-2026-10-12/README.md`)).toBeNull();
@@ -32,11 +32,17 @@ import { judgeLayout } from "./domain/paper-layout.ts";
32
32
  import {
33
33
  GITKEEP,
34
34
  NOT_SCAFFOLDED,
35
+ REPRO_INDEX_STUB,
35
36
  SCAFFOLD_DIRS,
36
37
  SCAFFOLD_FILES,
37
38
  } from "./domain/scaffold-layout.ts";
38
39
  import { ROOT_DIRS } from "./domain/paper-layout.ts";
39
40
  import { judgeRepro, REPRO_DIR } from "./domain/repro-layout.ts";
41
+ import {
42
+ registryText,
43
+ withIndex,
44
+ type StudyRegistry,
45
+ } from "./domain/study-registry.ts";
40
46
  import { statSync } from "node:fs";
41
47
 
42
48
  const dirs: string[] = [];
@@ -765,10 +771,29 @@ async function lintScaffold(added: Record<string, string> = {}) {
765
771
  };
766
772
  }
767
773
 
774
+ /** One registered study, as `paperlint studies new` writes it. */
775
+ const SOME_STUDY: StudyRegistry = {
776
+ prefix: "P1",
777
+ studies: [
778
+ {
779
+ id: "P1-S01",
780
+ folder: "P1-S01-some-study",
781
+ title: "Some study",
782
+ question: "",
783
+ kind: "measurement",
784
+ status: "designing",
785
+ date: "2026-10-13",
786
+ in_paper: "no",
787
+ },
788
+ ],
789
+ };
790
+
768
791
  describe("paperlint lint — a scaffolded paper has no layout finding", () => {
769
792
  const LAYOUT_RULES = [
770
793
  "paper/allowed-files-only",
771
794
  "repro/allowed-files-only",
795
+ "repro/study-registered",
796
+ "repro/study-plan-name",
772
797
  "review/frontmatter",
773
798
  "sibling/frontmatter",
774
799
  "paper/stages",
@@ -787,8 +812,10 @@ describe("paperlint lint — a scaffolded paper has no layout finding", () => {
787
812
  "siblings/.gitkeep": "",
788
813
  "talk/.gitkeep": "",
789
814
  "sections/.gitkeep": "",
790
- "repro/some-study-2026-10-13/README.md": "# s\n",
791
- "repro/some-study-2026-10-13/.gitkeep": "",
815
+ "repro/studies.json": registryText(SOME_STUDY),
816
+ "repro/README.md": withIndex(REPRO_INDEX_STUB, SOME_STUDY),
817
+ "repro/P1-S01-some-study/README.md": "# s\n",
818
+ "repro/P1-S01-some-study/.gitkeep": "",
792
819
  });
793
820
  expect(ids.filter((id) => LAYOUT_RULES.includes(id ?? ""))).toEqual([]);
794
821
  });
@@ -0,0 +1,15 @@
1
+ /**
2
+ * How a `repro/studies.json`, and a study's `plan.json`, become values: its text parsed once, where it enters, against the schema
3
+ * of `StudyRegistry` (`src/domain/study-registry.ts`). The one implementation is
4
+ * `src/adapters/study-registry/` (zod); `src/cli.ts` wires it.
5
+ */
6
+ import type { ParsedPlan, ParsedRegistry } from "../domain/study-registry.ts";
7
+
8
+ export interface StudyRegistryCodec {
9
+ /** A `studies.json`'s text: the registry, or the one reason it is not one of this schema. */
10
+ readonly parse: (text: string) => ParsedRegistry;
11
+ /** A study's `plan.json` text, strict: ready, a draft naming its empty texts, or why it is no plan. */
12
+ readonly parsePlan: (text: string) => ParsedPlan;
13
+ /** A plan still named `prereg.json`, loose: the same three outcomes. */
14
+ readonly parseLegacyPlan: (text: string) => ParsedPlan;
15
+ }
@@ -1,6 +1,7 @@
1
1
  /**
2
- * `repro/allowed-files-only` — the top of a paper's `repro/` holds an index, the shared `tools/` and
3
- * `data/`, and one dated folder per study, each with a `README.md`.
2
+ * `repro/allowed-files-only` — the top of a paper's `repro/` holds an index, the study registry, the
3
+ * shared `tools/` and `data/`, and one folder per study, each with a `README.md`. Whether each study
4
+ * folder has its row in the registry is `repro/study-registered`'s (src/study-registry-rule.ts).
4
5
  *
5
6
  * What may stand there, and why, is `src/domain/repro-layout.ts` and docs/rules/repro/allowed-files-only.md.
6
7
  * This file lists the folder and reports.
@@ -76,7 +77,7 @@ const META: FolderRuleModule["meta"] = {
76
77
  type: "suggestion",
77
78
  docs: {
78
79
  description:
79
- "the top of a paper's repro/ holds README.md, .gitignore, tools/, data/ and one <slug>-YYYY-MM-DD folder per study, each with a README.md",
80
+ "the top of a paper's repro/ holds README.md, studies.json, .gitignore, tools/, data/ and one <id>-<slug> (or <slug>-YYYY-MM-DD) folder per study, each with a README.md",
80
81
  url: rulePageUrl("repro/allowed-files-only"),
81
82
  },
82
83
  schema: [],
@@ -17,6 +17,13 @@ import { describe, expect, it } from "vitest";
17
17
  import { z } from "zod";
18
18
  import { run, rulePlugins } from "./cli.ts";
19
19
  import { sha256Hex } from "./domain/sha256.ts";
20
+ import {
21
+ planTemplate,
22
+ planText,
23
+ registryText,
24
+ withIndex,
25
+ type StudyRegistry,
26
+ } from "./domain/study-registry.ts";
20
27
  import { recordText } from "../test/recorded-fixture.ts";
21
28
  import { useTempDir, venuePreset, writeTree } from "../test/support.ts";
22
29
 
@@ -39,6 +46,42 @@ const paper = (
39
46
  ...extra,
40
47
  });
41
48
 
49
+ /** A registered study: `repro/studies.json` with its row, the study's folder, and the index in sync. */
50
+ const REGISTRY: StudyRegistry = {
51
+ prefix: "P1",
52
+ studies: [
53
+ {
54
+ id: "P1-S01",
55
+ folder: "P1-S01-ablation",
56
+ title: "Ablation",
57
+ question: "Which step does the work?",
58
+ kind: "measurement",
59
+ status: "designing",
60
+ date: "2026-10-15",
61
+ in_paper: "no",
62
+ },
63
+ ],
64
+ };
65
+ const REGISTERED_STUDY: Readonly<Record<string, string>> = {
66
+ [`${P}/repro/studies.json`]: registryText(REGISTRY),
67
+ [`${P}/repro/README.md`]: withIndex("# repro\n", REGISTRY),
68
+ [`${P}/repro/P1-S01-ablation/README.md`]: "# ablation\n",
69
+ };
70
+
71
+ /** The registered study with its plan named `name`, the plan's text beside its README. */
72
+ const STUDY_WITH_PLAN = (name: string): Readonly<Record<string, string>> => {
73
+ const r: StudyRegistry = {
74
+ ...REGISTRY,
75
+ studies: REGISTRY.studies.map((s) => ({ ...s, plan: name })),
76
+ };
77
+ return {
78
+ [`${P}/repro/studies.json`]: registryText(r),
79
+ [`${P}/repro/README.md`]: withIndex("# repro\n", r),
80
+ [`${P}/repro/P1-S01-ablation/README.md`]: "# ablation\n",
81
+ [`${P}/repro/P1-S01-ablation/${name}`]: planText(planTemplate()),
82
+ };
83
+ };
84
+
42
85
  /** `study/declare-sample` is off by default; a paper turns it on in its `paperlint.json`. */
43
86
  const DECLARE_SAMPLE_ON: Readonly<Record<string, string>> = {
44
87
  [`${P}/paperlint.json`]: JSON.stringify({
@@ -730,6 +773,31 @@ const CASES: Readonly<Record<string, RuleCases>> = {
730
773
  [`${P}/repro/ablation-2026-10-12/README.md`]: "# ablation\n",
731
774
  }),
732
775
  },
776
+ // A study folder with no row in repro/studies.json.
777
+ "repro/study-registered": {
778
+ reports: {
779
+ tree: paper(tex("x"), {
780
+ ...REGISTERED_STUDY,
781
+ [`${P}/repro/spike-2026-10-12/README.md`]: "# spike\n",
782
+ }),
783
+ file: `${P}/PIPELINE-STATUS.md`,
784
+ severity: 2,
785
+ line: 1,
786
+ },
787
+ // Every folder registered, and the index the registry generates.
788
+ silent: paper(tex("x"), REGISTERED_STUDY),
789
+ },
790
+ // A study's plan still named prereg.json: read as its plan, and a warning to rename it.
791
+ "repro/study-plan-name": {
792
+ reports: {
793
+ tree: paper(tex("x"), STUDY_WITH_PLAN("prereg.json")),
794
+ file: `${P}/PIPELINE-STATUS.md`,
795
+ severity: 1,
796
+ line: 1,
797
+ },
798
+ // The same plan as plan.json.
799
+ silent: paper(tex("x"), STUDY_WITH_PLAN("plan.json")),
800
+ },
733
801
  // A study's prereg.json that declares none of population, strata, screens, coverage, author_check.
734
802
  // Off by default: the paper turns it on, as both trees do.
735
803
  "study/declare-sample": {
@@ -0,0 +1,113 @@
1
+ /**
2
+ * `paperlint studies new|index` through the CLI's own `run`, on a real paper folder in a temp
3
+ * directory: the wiring (`src/cli.ts`), the disk, today's date — and the promise both commands make,
4
+ * that what they write is what `repro/study-registered` accepts. Both halves: a registry left stale
5
+ * by hand is reported by the same lint, and `studies index` makes it clean again.
6
+ */
7
+ import { readFileSync } from "node:fs";
8
+ import { join } from "node:path";
9
+ import { describe, expect, it } from "vitest";
10
+ import { studyRegistryCodec } from "./adapters/study-registry/index.ts";
11
+ import { run } from "./cli.ts";
12
+ import { lintReport } from "../test/lint-report.ts";
13
+ import { useTempDir, writeTree } from "../test/support.ts";
14
+
15
+ const root = useTempDir("studies-cli-");
16
+
17
+ /** `paperlint <args>` from the project root: the exit code and both streams. */
18
+ async function cli(cwd: string, args: readonly string[]) {
19
+ const log: string[] = [];
20
+ const err: string[] = [];
21
+ const code = await run(args, {
22
+ cwd,
23
+ log: (s: string) => log.push(s),
24
+ err: (s: string) => err.push(s),
25
+ });
26
+ return { code, log, err };
27
+ }
28
+
29
+ /** The `repro/study-registered` findings of `paperlint lint` over the project. */
30
+ async function registryFindings(cwd: string): Promise<readonly string[]> {
31
+ const { log } = await cli(cwd, ["lint", "--json"]);
32
+ return lintReport(log.join("\n")).flatMap((r) =>
33
+ r.messages
34
+ .filter((m) => m.ruleId === "repro/study-registered")
35
+ .map((m) => m.message),
36
+ );
37
+ }
38
+
39
+ /** A local `YYYY-MM-DD`, as the CLI reads the clock. */
40
+ const localDate = (d: Date): string =>
41
+ `${String(d.getFullYear())}-${String(d.getMonth() + 1).padStart(2, "0")}-${String(d.getDate()).padStart(2, "0")}`;
42
+
43
+ const dir = join(root, "project");
44
+ writeTree(dir, {
45
+ "package.json": "{}",
46
+ "papers/example/PIPELINE-STATUS.md": "---\nstages: []\n---\n# status\n",
47
+ "papers/example/paper.tex":
48
+ "\\documentclass{article}\n\\begin{document}\nx\n\\end{document}\n",
49
+ "papers/example/repro/README.md": "# Reproduction index\n",
50
+ "papers/example/repro/studies.json": '{ "prefix": "P1", "studies": [] }\n',
51
+ });
52
+ const repro = join(dir, "papers/example/repro");
53
+
54
+ describe("paperlint studies new — through the CLI", () => {
55
+ it("new registers a study dated today, and the lint finds nothing to report", async () => {
56
+ const before = localDate(new Date());
57
+ const out = await cli(dir, [
58
+ "studies",
59
+ "new",
60
+ "papers/example",
61
+ "Baseline pass rate",
62
+ "--kind",
63
+ "spike",
64
+ ]);
65
+ const after = localDate(new Date());
66
+ expect([out.code, out.err]).toEqual([0, []]);
67
+ expect(out.log[0]).toBe(
68
+ "created papers/example/repro/P1-S01-baseline-pass-rate/README.md",
69
+ );
70
+ const parsed = studyRegistryCodec.parse(
71
+ readFileSync(join(repro, "studies.json"), "utf8"),
72
+ );
73
+ const studies = parsed.ok ? parsed.registry.studies : [];
74
+ expect(studies.map((s) => [s.id, s.kind])).toEqual([["P1-S01", "spike"]]);
75
+ expect([before, after]).toContain(studies[0]?.date);
76
+ expect(await registryFindings(dir)).toEqual([]);
77
+ });
78
+ });
79
+
80
+ describe("paperlint studies index — through the CLI", () => {
81
+ it("a row edited by hand leaves the index stale; studies index makes it clean again", async () => {
82
+ const file = join(repro, "studies.json");
83
+ writeTree(repro, {
84
+ "studies.json": readFileSync(file, "utf8").replace(
85
+ '"designing"',
86
+ '"dropped"',
87
+ ),
88
+ });
89
+ expect(await registryFindings(dir)).toEqual([
90
+ expect.stringMatching(/^The index in `repro\/README\.md`/u),
91
+ ]);
92
+ const out = await cli(dir, ["studies", "index", "papers/example"]);
93
+ expect([out.code, out.log, out.err]).toEqual([
94
+ 0,
95
+ ["wrote the index of 1 study in papers/example/repro/README.md"],
96
+ [],
97
+ ]);
98
+ expect(readFileSync(join(repro, "README.md"), "utf8")).toContain(
99
+ "| P1-S01 | Baseline pass rate | dropped |",
100
+ );
101
+ expect(await registryFindings(dir)).toEqual([]);
102
+ });
103
+
104
+ it("a refusal exits non-zero and says why", async () => {
105
+ const out = await cli(dir, ["studies", "new", "papers/example"]);
106
+ expect([out.code, out.err]).toEqual([
107
+ 2,
108
+ [
109
+ 'studies new needs the study\'s title: npx paperlint studies new <paper-dir> "<title>" [--kind <kind>]',
110
+ ],
111
+ ]);
112
+ });
113
+ });
@@ -0,0 +1,359 @@
1
+ /**
2
+ * `paperlint studies new|index <paper-dir>` (`src/studies.ts`) on paper folders held in memory. Both
3
+ * halves: each command writes exactly the files it promises, and a run that cannot do what it was
4
+ * asked writes nothing and says why, with the exit code (2 for the command line, 1 for the paper's
5
+ * state).
6
+ */
7
+ import { describe, expect, it } from "vitest";
8
+ import { memoryFiles, memoryListDir } from "./adapters/memory/index.ts";
9
+ import { studyRegistryCodec } from "./adapters/study-registry/index.ts";
10
+ import {
11
+ indexBlock,
12
+ planTemplate,
13
+ planText,
14
+ registryText,
15
+ studyReadme,
16
+ withIndex,
17
+ type Study,
18
+ type StudyRegistry,
19
+ } from "./domain/study-registry.ts";
20
+ import { runStudies, type StudiesArgs } from "./studies.ts";
21
+
22
+ const CWD = "/work";
23
+ const DIR = "/work/papers/example";
24
+ const REPRO = `${DIR}/repro`;
25
+
26
+ const study = (over: Partial<Study> = {}): Study => ({
27
+ id: "P1-S01",
28
+ folder: "P1-S01-baseline",
29
+ title: "Baseline",
30
+ question: "q?",
31
+ kind: "measurement",
32
+ status: "done",
33
+ date: "2026-10-01",
34
+ result: "41 of 60",
35
+ result_file: "r.tsv",
36
+ in_paper: "yes",
37
+ role: "counted",
38
+ ...over,
39
+ });
40
+
41
+ const P1 = (...studies: Study[]): StudyRegistry => ({ prefix: "P1", studies });
42
+
43
+ const paper = (
44
+ extra: Readonly<Record<string, string>> = {},
45
+ ): Record<string, string> => ({
46
+ [`${DIR}/PIPELINE-STATUS.md`]: "# status\n",
47
+ ...extra,
48
+ });
49
+
50
+ /** `studies` over `tree`, from `/work`: the exit code, what it printed, and the files after. */
51
+ function studies(
52
+ a: Partial<StudiesArgs>,
53
+ tree: Readonly<Record<string, string>>,
54
+ cwd = CWD,
55
+ ) {
56
+ const files = memoryFiles(tree);
57
+ const log: string[] = [];
58
+ const err: string[] = [];
59
+ const code = runStudies(
60
+ {
61
+ sub: "new",
62
+ paperDir: "papers/example",
63
+ title: undefined,
64
+ extra: [],
65
+ kind: null,
66
+ ...a,
67
+ },
68
+ {
69
+ files,
70
+ listDir: memoryListDir(files),
71
+ codec: studyRegistryCodec,
72
+ cwd,
73
+ today: "2026-10-15",
74
+ log: (l) => log.push(l),
75
+ err: (l) => err.push(l),
76
+ },
77
+ );
78
+ const after = Object.fromEntries(
79
+ [...files.map].map(([k, v]) => [k, new TextDecoder().decode(v)]),
80
+ );
81
+ return { code, log, err, after };
82
+ }
83
+
84
+ /** A paper with one registered study and a README without the index yet. */
85
+ const before = paper({
86
+ [`${REPRO}/studies.json`]: registryText(P1(study())),
87
+ [`${REPRO}/README.md`]: "# Reproduction index\n\nIntro.\n",
88
+ [`${REPRO}/P1-S01-baseline/README.md`]: "# s\n",
89
+ });
90
+
91
+ describe("studies new", () => {
92
+ it("creates the folder's README.md, appends the row, regenerates the index", () => {
93
+ const { code, log, err, after } = studies(
94
+ { title: "Ablation of the guard", kind: "spike" },
95
+ before,
96
+ );
97
+ const added: Study = {
98
+ id: "P1-S02",
99
+ folder: "P1-S02-ablation-of-the-guard",
100
+ title: "Ablation of the guard",
101
+ question: "",
102
+ kind: "spike",
103
+ status: "designing",
104
+ date: "2026-10-15",
105
+ in_paper: "no",
106
+ plan: "plan.json",
107
+ };
108
+ const r = P1(study(), added);
109
+ expect({ code, err }).toEqual({ code: 0, err: [] });
110
+ expect(after).toEqual({
111
+ ...before,
112
+ [`${REPRO}/P1-S02-ablation-of-the-guard/README.md`]: studyReadme(added),
113
+ [`${REPRO}/P1-S02-ablation-of-the-guard/plan.json`]:
114
+ planText(planTemplate()),
115
+ [`${REPRO}/studies.json`]: registryText(r),
116
+ [`${REPRO}/README.md`]: `# Reproduction index\n\nIntro.\n\n${indexBlock(r)}\n`,
117
+ });
118
+ expect(log).toEqual([
119
+ "created papers/example/repro/P1-S02-ablation-of-the-guard/README.md",
120
+ "created papers/example/repro/P1-S02-ablation-of-the-guard/plan.json, the study's plan: its fields are there to fill in before the first run",
121
+ "added P1-S02 to papers/example/repro/studies.json: kind spike, status designing, 2026-10-15",
122
+ "wrote the index of 2 studies in papers/example/repro/README.md",
123
+ "Next: write the study's one-sentence question in its row (`question`) and in its README.md. When it ends, set `status`, `result`, `result_file` and `in_paper` in its row, then run `npx paperlint studies index papers/example`.",
124
+ ]);
125
+ });
126
+
127
+ it("is a measurement when no kind is named, and keeps a row's extra fields", () => {
128
+ const { code, after } = studies({ title: "Second run" }, before);
129
+ expect(code).toBe(0);
130
+ const r = studyRegistryCodec.parse(after[`${REPRO}/studies.json`] ?? "");
131
+ expect(
132
+ (r.ok ? r.registry.studies : []).map((s) => [s.id, s.kind, s["role"]]),
133
+ ).toEqual([
134
+ ["P1-S01", "measurement", "counted"],
135
+ ["P1-S02", "measurement", undefined],
136
+ ]);
137
+ });
138
+
139
+ it("writes repro/README.md when there is none", () => {
140
+ const tree = Object.fromEntries(
141
+ Object.entries(before).filter(([k]) => k !== `${REPRO}/README.md`),
142
+ );
143
+ const { code, after } = studies({ title: "Second run" }, tree);
144
+ expect(code).toBe(0);
145
+ expect(after[`${REPRO}/README.md`]).toMatch(
146
+ /^# Reproduction index\n\n<!-- studies:begin/u,
147
+ );
148
+ });
149
+ });
150
+
151
+ describe("studies new — refuses, writing nothing", () => {
152
+ it.each([
153
+ [
154
+ "no title",
155
+ { title: undefined },
156
+ 2,
157
+ 'studies new needs the study\'s title: npx paperlint studies new <paper-dir> "<title>" [--kind <kind>]',
158
+ ],
159
+ [
160
+ "an unknown kind",
161
+ { title: "x", kind: "benchmark" },
162
+ 2,
163
+ "--kind benchmark is not a kind of study: one of measurement, spike, tooling, data, artifact, salvage",
164
+ ],
165
+ [
166
+ "a title over eight words",
167
+ { title: "one two three four five six seven eight nine" },
168
+ 2,
169
+ "the title has 9 words; a title is a plain name of at most 8 — the detail goes in the row's `question`",
170
+ ],
171
+ [
172
+ "an argument past the title",
173
+ { title: "x", extra: ["y"] },
174
+ 2,
175
+ "studies new takes the paper's folder and one title — `y` is one argument too many (quote a title of several words)",
176
+ ],
177
+ ] as const)("%s", (_why, a, code, line) => {
178
+ const out = studies(a, before);
179
+ expect([out.code, out.err, out.after]).toEqual([code, [line], before]);
180
+ });
181
+ });
182
+
183
+ describe("studies new — refuses by the paper's state, writing nothing", () => {
184
+ it("a folder that already exists", () => {
185
+ const tree = { ...before, [`${REPRO}/P1-S02-second-run/notes.md`]: "x" };
186
+ const out = studies({ title: "Second run" }, tree);
187
+ expect([out.code, out.err, out.after]).toEqual([
188
+ 1,
189
+ [
190
+ "papers/example/repro/P1-S02-second-run/ already exists; it is never overwritten. Register it by hand, or remove it and run this again.",
191
+ ],
192
+ tree,
193
+ ]);
194
+ });
195
+
196
+ it("a paper with no studies.json: names the file, and does not guess the prefix", () => {
197
+ const tree = paper();
198
+ const out = studies({ title: "x" }, tree);
199
+ expect([out.code, out.err, out.after]).toEqual([
200
+ 1,
201
+ [
202
+ 'papers/example/repro/studies.json does not exist. Its prefix is the paper\'s own choice — a capital letter, then capitals or digits, one per paper (P1) — so write the file, then run this again:\n\n{ "prefix": "P1", "studies": [] }',
203
+ ],
204
+ tree,
205
+ ]);
206
+ });
207
+
208
+ it("a studies.json that is not a registry", () => {
209
+ const tree = paper({ [`${REPRO}/studies.json`]: "{" });
210
+ const out = studies({ title: "x" }, tree);
211
+ expect([out.code, out.err]).toEqual([
212
+ 1,
213
+ ["papers/example/repro/studies.json is not a study registry: not JSON"],
214
+ ]);
215
+ });
216
+ });
217
+
218
+ describe("studies index", () => {
219
+ const r = P1(study());
220
+
221
+ it("regenerates the block in place", () => {
222
+ const tree = paper({
223
+ [`${REPRO}/studies.json`]: registryText(r),
224
+ [`${REPRO}/README.md`]: `# I\n\n${indexBlock(P1())}\n\nTail.\n`,
225
+ });
226
+ const { code, log, err, after } = studies(
227
+ { sub: "index", paperDir: "papers/example" },
228
+ tree,
229
+ );
230
+ expect({ code, log, err }).toEqual({
231
+ code: 0,
232
+ log: ["wrote the index of 1 study in papers/example/repro/README.md"],
233
+ err: [],
234
+ });
235
+ expect(after).toEqual({
236
+ ...tree,
237
+ [`${REPRO}/README.md`]: `# I\n\n${indexBlock(r)}\n\nTail.\n`,
238
+ });
239
+ });
240
+
241
+ it("says so and writes nothing when the index is in sync", () => {
242
+ const tree = paper({
243
+ [`${REPRO}/studies.json`]: registryText(r),
244
+ [`${REPRO}/README.md`]: withIndex("# I\n", r),
245
+ });
246
+ const out = studies({ sub: "index" }, tree);
247
+ expect([out.code, out.log, out.after]).toEqual([
248
+ 0,
249
+ ["the index in papers/example/repro/README.md is in sync with 1 study"],
250
+ tree,
251
+ ]);
252
+ });
253
+
254
+ it("refuses a title, which only `new` takes", () => {
255
+ const tree = paper({ [`${REPRO}/studies.json`]: registryText(r) });
256
+ const out = studies({ sub: "index", title: "x" }, tree);
257
+ expect([out.code, out.err]).toEqual([
258
+ 2,
259
+ [
260
+ "studies index takes only the paper's folder — `x` is one argument too many",
261
+ ],
262
+ ]);
263
+ });
264
+ });
265
+
266
+ describe("studies index — a table a formatter padded", () => {
267
+ it("leaves an index in sync as it is, whatever its padding", () => {
268
+ const r = P1(study({ title: "測定 A" }));
269
+ const generated = withIndex("# I\n", r);
270
+ const padded = generated.replace("測定 A", "測定 A ");
271
+ expect(padded).not.toBe(generated);
272
+ const tree = paper({
273
+ [`${REPRO}/studies.json`]: registryText(r),
274
+ [`${REPRO}/README.md`]: padded,
275
+ });
276
+ const out = studies({ sub: "index" }, tree);
277
+ expect([out.code, out.log, out.after]).toEqual([
278
+ 0,
279
+ ["the index in papers/example/repro/README.md is in sync with 1 study"],
280
+ tree,
281
+ ]);
282
+ });
283
+ });
284
+
285
+ describe("studies — a directory where repro/README.md goes", () => {
286
+ const tree = paper({
287
+ [`${REPRO}/studies.json`]: registryText(P1(study())),
288
+ [`${REPRO}/README.md/notes.txt`]: "x",
289
+ });
290
+ const refusal =
291
+ "papers/example/repro/README.md is not a file, so the index cannot be written there. Move it, then run this again.";
292
+
293
+ it.each([
294
+ ["index", {}],
295
+ ["new", { title: "Second run" }],
296
+ ] as const)("studies %s refuses and writes nothing", (sub, extra) => {
297
+ const out = studies({ sub, ...extra }, tree);
298
+ expect([out.code, out.err, out.after]).toEqual([1, [refusal], tree]);
299
+ });
300
+ });
301
+
302
+ describe("studies index — refuses by the paper's state", () => {
303
+ it("a paper with no studies.json, and writes nothing", () => {
304
+ const tree = paper();
305
+ const out = studies({ sub: "index" }, tree);
306
+ expect([out.code, out.err[0]?.split(".", 1)[0], out.after]).toEqual([
307
+ 1,
308
+ "papers/example/repro/studies",
309
+ tree,
310
+ ]);
311
+ });
312
+ });
313
+
314
+ describe("studies — run from inside the paper folder", () => {
315
+ it("names the folder `.`", () => {
316
+ const tree = paper({
317
+ [`${REPRO}/studies.json`]: registryText(P1()),
318
+ [`${REPRO}/README.md`]: withIndex("# I\n", P1()),
319
+ });
320
+ const out = studies({ sub: "index", paperDir: "." }, tree, DIR);
321
+ expect([out.code, out.log]).toEqual([
322
+ 0,
323
+ ["the index in ./repro/README.md is in sync with 0 studies"],
324
+ ]);
325
+ });
326
+ });
327
+
328
+ describe("studies — the command line", () => {
329
+ it.each([
330
+ [
331
+ "no subcommand",
332
+ { sub: undefined },
333
+ 'studies needs a subcommand: new or index — npx paperlint studies new <paper-dir> "<title>" [--kind <kind>] · npx paperlint studies index <paper-dir>',
334
+ ],
335
+ [
336
+ "an unknown subcommand",
337
+ { sub: "add" },
338
+ 'unknown subcommand `studies add`: new or index — npx paperlint studies new <paper-dir> "<title>" [--kind <kind>] · npx paperlint studies index <paper-dir>',
339
+ ],
340
+ [
341
+ "new with no paper folder",
342
+ { sub: "new", paperDir: undefined },
343
+ 'studies new needs the paper\'s folder: npx paperlint studies new <paper-dir> "<title>" [--kind <kind>]',
344
+ ],
345
+ [
346
+ "no paper folder",
347
+ { sub: "index", paperDir: undefined },
348
+ "studies index needs the paper's folder: npx paperlint studies index <paper-dir>",
349
+ ],
350
+ [
351
+ "a folder that is no paper",
352
+ { sub: "index", paperDir: "papers" },
353
+ "papers is not a paper folder: it has no PIPELINE-STATUS.md",
354
+ ],
355
+ ] as const)("refuses %s with 2", (_why, a, line) => {
356
+ const out = studies(a, paper());
357
+ expect([out.code, out.err, out.log]).toEqual([2, [line], []]);
358
+ });
359
+ });