paperlint 10.2.0 → 10.4.0

package/src/domain/study-mode.ts

@@ -0,0 +1,78 @@
+/**
+ * A STUDY'S MODE — how its outcomes are kept from the decisions about its inputs. A measurement study
+ * declares exactly one (docs/design/study-modes.md):
+ *
+ *   decide_before_run   the default: the author's decisions on the inputs (exclusions, veto, the
+ *                       sample's approval) are committed BEFORE any output exists. No key, no extra
+ *                       tool: git's history is the proof of order, and
+ *                       `repro/outputs-before-decision` re-checks it on every lint.
+ *   exploratory         no gate: the study is exploratory and is reported as such, with its reason.
+ *
+ * "None" and "two at once" cannot be written: the plan holds one `mode`, a union on its `kind`, and a
+ * measurement study's plan is not ready without it (the parser, `src/adapters/study-registry/`).
+ *
+ * Paths: `outputs` are globs relative to the study's folder (the study's results live there); the
+ * decision's `file` is relative to the PAPER's folder, so a decision may live beside the study or
+ * anywhere in the paper (`research/decisions.md`). Pure.
+ */
+import { posix } from "node:path";
+import { REPRO_DIR } from "./repro-layout.ts";
+import type { StudyKind } from "./study-registry.ts";
+
+/** A decision recorded in a file: where, and what it decides. */
+export interface Decision {
+  /** Relative to the paper's folder. */
+  readonly file: string;
+  readonly note: string;
+}
+
+/** Decide first: the decision on the inputs is committed before any output exists. */
+export interface DecideFirst {
+  readonly kind: "decide_before_run";
+  /** Globs relative to the study's folder: the files the run produces. */
+  readonly outputs: readonly string[];
+  readonly decision: Decision;
+}
+
+/** Exploratory: no gate, and reported as exploratory. */
+export interface Exploratory {
+  readonly kind: "exploratory";
+  readonly reason: string;
+}
+
+export type StudyMode = DecideFirst | Exploratory;
+
+/**
+ * The kinds of study whose plan must declare a mode: the ones that measure. A spike, a tool, a data
+ * set, an artifact or a salvage may omit it.
+ */
+export const MODE_REQUIRED: readonly StudyKind[] = ["measurement"];
+
+/** Whether a study of `kind` must declare its mode. */
+export const needsMode = (kind: StudyKind): boolean =>
+  MODE_REQUIRED.includes(kind);
+
+/** `paperPath` relative to the study folder `folder`, when it lies inside it; else null. */
+export const inStudy = (folder: string, paperPath: string): string | null => {
+  const prefix = `${REPRO_DIR}/${folder}/`;
+  const n = posix.normalize(paperPath);
+  return n.startsWith(prefix) ? n.slice(prefix.length) : null;
+};
+
+/** Whether the file at `path` (relative to the study's folder) is one of `outputs`. */
+export const isOutput = (outputs: readonly string[], path: string): boolean =>
+  outputs.some((g) => posix.matchesGlob(path, g));
+
+/**
+ * The output glob that matches the study's own decision file, when the file lies in the study's
+ * folder: the decision would be "produced" by the run it gates.
+ */
+export const decisionAsOutput = (
+  folder: string,
+  m: DecideFirst,
+): string | null => {
+  const rel = inStudy(folder, m.decision.file);
+  return rel === null
+    ? null
+    : (m.outputs.find((g) => posix.matchesGlob(rel, g)) ?? null);
+};

package/src/domain/study-registry.test.ts

@@ -25,8 +25,12 @@ import {
   type Study,
   type StudyInput,
   type StudyRegistry,
+  type IndexInput,
 } from "./study-registry.ts";
 
+/** No plan and no history: the index with every mode column `—`. */
+const NO_FACTS: IndexInput = { plans: new Map(), history: new Map() };
+
 const study = (over: Partial<Study> = {}): Study => ({
   id: "P1-S01",
   folder: "P1-S01-baseline",
@@ -56,8 +60,9 @@ const input = (
 ): StudyInput => ({
   folders: r.studies.map((s) => s.folder),
   registry: read(r),
-  readme: withIndex("# Reproduction index\n", r),
+  readme: withIndex("# Reproduction index\n", r, NO_FACTS),
   existingResults: new Set(),
+  plans: new Map(),
   ...over,
 });
 
@@ -96,6 +101,7 @@ describe("judgeStudies — silent", () => {
         registry: { kind: "absent" },
         readme: null,
         existingResults: new Set(),
+        plans: new Map(),
       }),
     ).toEqual([]);
   });
@@ -124,6 +130,7 @@ describe("judgeStudies — the registry itself", () => {
         registry: { kind: "absent" },
         readme: null,
         existingResults: new Set(),
+        plans: new Map(),
       }),
     ).toEqual([
       { problem: "no-registry", folders: ["a-2026-10-01", "b-2026-10-02"] },
@@ -137,6 +144,7 @@ describe("judgeStudies — the registry itself", () => {
         registry: { kind: "unreadable", why: "prefix: required" },
         readme: null,
         existingResults: new Set(),
+        plans: new Map(),
       }),
     ).toEqual([{ problem: "unreadable", why: "prefix: required" }]);
   });
@@ -306,16 +314,16 @@ describe("judgeStudies — the index", () => {
 
   it("a table prettier padded by display width, with wide characters, is in sync", async () => {
     const wide = reg(study({ title: "測定 A" }));
-    const readme = await format(withIndex("# index\n", wide), {
+    const readme = await format(withIndex("# index\n", wide, NO_FACTS), {
       parser: "markdown",
     });
-    expect(readme).not.toBe(withIndex("# index\n", wide));
+    expect(readme).not.toBe(withIndex("# index\n", wide, NO_FACTS));
     expect(judgeStudies(input(wide, { readme }))).toEqual([]);
   });
 
   it("a title with a backslash before a pipe stays one cell through prettier", async () => {
     const bs = reg(study({ title: "foo\\|bar" }));
-    const readme = await format(withIndex("# index\n", bs), {
+    const readme = await format(withIndex("# index\n", bs, NO_FACTS), {
       parser: "markdown",
     });
     expect(judgeStudies(input(bs, { readme }))).toEqual([]);
@@ -324,22 +332,25 @@ describe("judgeStudies — the index", () => {
 
   it("a title carrying the end marker's text: in sync, and regenerating changes nothing", () => {
     const m = reg(study({ title: `x ${INDEX_END} y` }));
-    const readme = withIndex("# index\n", m);
+    const readme = withIndex("# index\n", m, NO_FACTS);
     expect(judgeStudies(input(m, { readme }))).toEqual([]);
-    expect(withIndex(readme, m)).toBe(readme);
+    expect(withIndex(readme, m, NO_FACTS)).toBe(readme);
   });
 
   it("prose that mentions the begin marker is kept, and the real block is the one judged", () => {
     const r1 = reg(study());
     const prose = `# index\n\nThe table between \`${INDEX_BEGIN}\` and its end marker is generated.\n`;
-    const readme = withIndex(prose, r1);
+    const readme = withIndex(prose, r1, NO_FACTS);
     expect(judgeStudies(input(r1, { readme }))).toEqual([]);
-    expect(withIndex(readme, r1)).toBe(readme);
+    expect(withIndex(readme, r1, NO_FACTS)).toBe(readme);
     expect(readme.startsWith(prose.trimEnd())).toBe(true);
   });
 
   it("a block that differs from the registry by one character", () => {
-    const readme = withIndex("# index\n", r).replace("designing", "running");
+    const readme = withIndex("# index\n", r, NO_FACTS).replace(
+      "designing",
+      "running",
+    );
     expect(judgeStudies(input(r, { readme }))).toEqual([
       { problem: "stale-index", why: "differs" },
     ]);
@@ -359,12 +370,12 @@ describe("the index", () => {
         in_paper: "yes",
       }),
     );
-    expect(studyIndex(r)).toBe(
+    expect(studyIndex(r, NO_FACTS)).toBe(
       [
-        "| id     | title               | status    | result   | in paper | folder                               |",
-        "| ------ | ------------------- | --------- | -------- | -------- | ------------------------------------ |",
-        "| P1-S01 | Baseline pass rate  | designing | —        | no       | [P1-S01-baseline/](P1-S01-baseline/) |",
-        "| P1-S02 | Pipes \\| and breaks | done      | 41 of 60 | yes      | [P1-S02-a-b/](P1-S02-a-b/)           |",
+        "| id     | title               | status    | result   | in paper | mode | decision | first output | folder                               |",
+        "| ------ | ------------------- | --------- | -------- | -------- | ---- | -------- | ------------ | ------------------------------------ |",
+        "| P1-S01 | Baseline pass rate  | designing | —        | no       | —    | —        | —            | [P1-S01-baseline/](P1-S01-baseline/) |",
+        "| P1-S02 | Pipes \\| and breaks | done      | 41 of 60 | yes      | —    | —        | —            | [P1-S02-a-b/](P1-S02-a-b/)           |",
       ].join("\n"),
     );
   });
@@ -386,30 +397,30 @@ describe("the index", () => {
         }),
       ].slice(0, n),
     );
-    const md = withIndex("# Reproduction index\n\nSome text.\n", r);
+    const md = withIndex("# Reproduction index\n\nSome text.\n", r, NO_FACTS);
     expect(await format(md, { parser: "markdown" })).toBe(md);
   });
 });
 
 describe("the index of an empty registry, and its markers", () => {
   it("of an empty registry is the header alone", () => {
-    expect(studyIndex(reg())).toBe(
+    expect(studyIndex(reg(), NO_FACTS)).toBe(
       [
-        "| id  | title | status | result | in paper | folder |",
-        "| --- | ----- | ------ | ------ | -------- | ------ |",
+        "| id  | title | status | result | in paper | mode | decision | first output | folder |",
+        "| --- | ----- | ------ | ------ | -------- | ---- | -------- | ------------ | ------ |",
       ].join("\n"),
     );
   });
 
   it("sits between the two markers, a blank line on each side", () => {
-    expect(indexBlock(reg())).toBe(
-      `${INDEX_BEGIN}\n\n${studyIndex(reg())}\n\n${INDEX_END}`,
+    expect(indexBlock(reg(), NO_FACTS)).toBe(
+      `${INDEX_BEGIN}\n\n${studyIndex(reg(), NO_FACTS)}\n\n${INDEX_END}`,
     );
   });
 
   it("is read back from a README as the text between the markers, or null", () => {
-    expect(embeddedIndex(`# x\n\n${indexBlock(reg())}\n`)).toBe(
-      `\n\n${studyIndex(reg())}\n\n`,
+    expect(embeddedIndex(`# x\n\n${indexBlock(reg(), NO_FACTS)}\n`)).toBe(
+      `\n\n${studyIndex(reg(), NO_FACTS)}\n\n`,
     );
     expect(embeddedIndex("# x\n")).toBeNull();
     expect(embeddedIndex(`${INDEX_END}\n${INDEX_BEGIN}\n`)).toBeNull();
@@ -420,27 +431,27 @@ describe("withIndex", () => {
   const r = reg(study());
 
   it("replaces the block in place and keeps the rest", () => {
-    const before = `# Index\n\nintro\n\n${indexBlock(reg())}\n\ntail\n`;
-    expect(withIndex(before, r)).toBe(
-      `# Index\n\nintro\n\n${indexBlock(r)}\n\ntail\n`,
+    const before = `# Index\n\nintro\n\n${indexBlock(reg(), NO_FACTS)}\n\ntail\n`;
+    expect(withIndex(before, r, NO_FACTS)).toBe(
+      `# Index\n\nintro\n\n${indexBlock(r, NO_FACTS)}\n\ntail\n`,
     );
   });
 
   it("appends the block to a README without markers", () => {
-    expect(withIndex("# Index\n\nintro", r)).toBe(
-      `# Index\n\nintro\n\n${indexBlock(r)}\n`,
+    expect(withIndex("# Index\n\nintro", r, NO_FACTS)).toBe(
+      `# Index\n\nintro\n\n${indexBlock(r, NO_FACTS)}\n`,
     );
   });
 
   it("writes a README when there is none", () => {
-    expect(withIndex(null, r)).toBe(
-      `# Reproduction index\n\n${indexBlock(r)}\n`,
+    expect(withIndex(null, r, NO_FACTS)).toBe(
+      `# Reproduction index\n\n${indexBlock(r, NO_FACTS)}\n`,
     );
   });
 
   it("is a fixed point: a second run changes nothing", () => {
-    const once = withIndex("# Index\n", r);
-    expect(withIndex(once, r)).toBe(once);
+    const once = withIndex("# Index\n", r, NO_FACTS);
+    expect(withIndex(once, r, NO_FACTS)).toBe(once);
   });
 });
 
@@ -583,7 +594,7 @@ describe("addStudy", () => {
     date: "2026-10-15",
   } as const;
 
-  it("appends the next id, its folder, designing, not in the paper, an empty question", () => {
+  it("appends the next id, its folder, designing, not in the paper, an empty question, its plan", () => {
     const r = reg(study({ id: "P1-S04", folder: "P1-S04-x", foo: 1 }));
     const out = addStudy(r, { ...NEW, title: "  Baseline\n pass   rate " });
     const added: Study = {
@@ -595,6 +606,7 @@ describe("addStudy", () => {
       status: "designing",
       date: "2026-10-15",
       in_paper: "no",
+      plan: "plan.json",
     };
     expect(out).toEqual({
       ok: true,
@@ -645,6 +657,10 @@ describe("studyReadme", () => {
         "Its row in `../studies.json` holds its status. When the study ends, set `status`, `result`,",
         "`result_file` and `in_paper` there, then run `npx paperlint studies index <paper-dir>`.",
         "",
+        "Its plan is `plan.json`: what it measures, the population and the draw, the arms and the primary",
+        "outcome, filled in before the first run; the author's check of the drawn units goes in its",
+        "`author_check`.",
+        "",
         "## Question",
         "",
         "## How to run",