paperlint 10.3.0 → 10.4.0

package/src/study-gate.ts

@@ -0,0 +1,161 @@
+/**
+ * `paperlint studies gate <paper-dir> <id>` — may the study's run start? For a study decided before
+ * its run (the default mode), only once its decision file exists and is committed as it stands: exit 0
+ * with the commit and its date, else exit 1 saying why. A runner calls it first:
+ *
+ *   npx paperlint studies gate papers/my-paper P1-S03 && ./run.sh
+ *
+ * An exploratory study has no gate: it exits 0 and says so. A study that declares no mode, names no
+ * decision file, or whose row names a folder that is not one inside `repro/`, is refused.
+ */
+import { join } from "node:path";
+import { callerPath } from "./caller-path.ts";
+import {
+  modeStudies,
+  onDisk,
+  type ModeStudy,
+  type StudyDeps,
+} from "./study-modes.ts";
+import { REPRO_DIR } from "./domain/repro-layout.ts";
+import { decisionAsOutput, type DecideFirst } from "./domain/study-mode.ts";
+import type { Study } from "./domain/study-registry.ts";
+import type { Committed, GitHistory } from "./ports/git-history.ts";
+import { readableFolders, registryOf } from "./study-registry-rule.ts";
+import {
+  refusal,
+  refused,
+  type StudyRefusal,
+  type StudyRun,
+} from "./study-run.ts";
+
+export interface GateDeps extends StudyDeps {
+  readonly git: GitHistory;
+}
+
+/** The line of a committed state that holds the run back. */
+const shutLine = (
+  id: string,
+  file: string,
+  c: Exclude<Committed, { readonly kind: "committed" }>,
+): string => {
+  switch (c.kind) {
+    case "changed":
+      return `${id}: the decision ${file} has changed since its last commit, ${c.commit}; the run waits for the decision as committed. Commit it, then run this again.`;
+    case "deleted":
+      return `${id}: the decision ${file} is not in HEAD: it was deleted in ${c.commit}; the run waits for a decision that stands. Restore it, commit it, then run this again.`;
+    case "not-committed":
+      return `${id}: the decision ${file} is not committed; the run waits for it. Write the decision there, commit it, then run this again.`;
+    case "unknown":
+      return `${id}: git could not say whether the decision ${file} is committed: ${c.why}.`;
+  }
+};
+
+/** What a decision's committed state means for the run. */
+export const gateLine = (
+  id: string,
+  file: string,
+  c: Committed,
+): { readonly open: boolean; readonly line: string } =>
+  c.kind === "committed"
+    ? {
+        open: true,
+        line: `${id}: the decision ${file} is committed in ${c.commit} (${c.date}); the run may start.`,
+      }
+    : { open: false, line: shutLine(id, file, c) };
+
+/**
+ * Why the decision cannot gate the run though it is named: its own outputs match it, or it is a
+ * directory (git answers for a directory with the last commit of anything under it); null when usable.
+ */
+const unusable = (
+  paper: string,
+  { id, folder }: Pick<Study, "id" | "folder">,
+  mode: DecideFirst,
+  deps: GateDeps,
+): StudyRefusal | null => {
+  const file = mode.decision.file;
+  const glob = decisionAsOutput(folder, mode);
+  if (glob !== null)
+    return refusal(
+      `${id}: its decision ${file} is matched by its output \`${glob}\`; a decision cannot be what its own run produces.`,
+    );
+  const on = onDisk(join(paper, file), deps);
+  return on === "directory" || on === "symbolic link"
+    ? refusal(
+        `${id}: its decision ${file} is a ${on}, not a file; the run cannot be gated on it. Name the decision file in \`mode.decision.file\`.`,
+      )
+    : null;
+};
+
+/** The gate of a decide-first study. */
+const gateDecided = (
+  paper: string,
+  { id, folder }: Study,
+  mode: DecideFirst,
+  deps: GateDeps,
+): StudyRun => {
+  const file = mode.decision.file;
+  const blocked = unusable(paper, { id, folder }, mode, deps);
+  if (blocked !== null) return refused(blocked);
+  const g = gateLine(
+    id,
+    file,
+    deps.git.committed(callerPath(paper), callerPath(join(paper, file))),
+  );
+  return g.open ? { ok: true, lines: [g.line] } : refused(refusal(g.line));
+};
+
+/** The refusal when the row of `id` names a folder that is not one inside `repro/`; null when none does. */
+const escapingRow = (
+  paper: string,
+  shown: string,
+  id: string,
+  deps: GateDeps,
+): StudyRefusal | null => {
+  const r = registryOf(paper, deps);
+  const readable = readableFolders(paper, deps);
+  const row = (r.kind === "read" ? r.registry.studies : []).find(
+    (x) => x.id === id && !readable(x.folder),
+  );
+  return row === undefined
+    ? null
+    : refusal(
+        `${id}: its row names the folder \`${row.folder}\`, which is not one folder inside ${shown}/${REPRO_DIR}/; nothing is read through it. Give the row its own folder's name.`,
+      );
+};
+
+/** The refusal of a study whose plan is still a draft: a mode decides nothing until its plan is ready. */
+const draftRefusal = (id: string, s: ModeStudy): StudyRefusal => {
+  const names = s.empty.map((f) => `\`${f}\``).join(", ");
+  const verb = s.empty.length === 1 ? "is" : "are";
+  return refusal(
+    `${id}: its ${s.plan} is a draft — ${names} ${verb} empty; the run waits for a ready plan. Fill it in, then run this again.`,
+  );
+};
+
+/** `studies gate`: 0 when the run may start, 1 with the reason when not. */
+export function runGate(
+  paper: string,
+  shown: string,
+  id: string,
+  deps: GateDeps,
+): StudyRun {
+  const escaping = escapingRow(paper, shown, id, deps);
+  if (escaping !== null) return refused(escaping);
+  const s = modeStudies(paper, deps).find((m) => m.row.id === id);
+  if (s === undefined)
+    return refused(
+      refusal(
+        `${id} declares no mode in ${shown}: no row of ${shown}/${REPRO_DIR}/studies.json with this id names a plan.json that parses with \`mode\`. Lint the paper (\`npx paperlint lint\`) to see why.`,
+      ),
+    );
+  if (s.empty.length > 0) return refused(draftRefusal(id, s));
+  return s.mode.kind === "decide_before_run"
+    ? gateDecided(paper, s.row, s.mode, deps)
+    : {
+        ok: true,
+        lines: [
+          `${id} is exploratory (${s.mode.reason}): it has no gate, and its results are reported as exploratory.`,
+        ],
+      };
+}

package/src/study-index-input.ts

@@ -0,0 +1,23 @@
+/**
+ * What `paperlint studies index` and `studies new` generate the index from beyond the registry: each
+ * row's plan, and each decide-first study's history as git gives it now (src/domain/index-columns.ts).
+ */
+import { indexHistory } from "./domain/index-columns.ts";
+import type { IndexInput, RegistryState } from "./domain/study-registry.ts";
+import {
+  decideFirstStudies,
+  type OrderDeps,
+} from "./outputs-before-decision-rule.ts";
+import { plansOf, readableFolders } from "./study-registry-rule.ts";
+
+/** The plans and the histories of the paper folder `paper`, whose registry is `r`. */
+export const indexInputOf = (
+  paper: string,
+  r: RegistryState,
+  deps: OrderDeps,
+): IndexInput => ({
+  plans: plansOf(paper, r, deps, readableFolders(paper, deps)),
+  history: new Map(
+    decideFirstStudies(paper, deps).map((s) => [s.id, indexHistory(s)]),
+  ),
+});

package/src/study-modes.ts

@@ -0,0 +1,120 @@
+/**
+ * Reading a paper's studies with their modes: each registered study whose `plan.json` parses with a
+ * `mode`, and the files under a study's folder. What `repro/outputs-before-decision`, `studies gate`
+ * and the index's mode columns read with (docs/design/study-modes.md). A row whose folder is not one
+ * folder inside `repro/` is never read through.
+ */
+import { basename, dirname, join } from "node:path";
+import { callerPath } from "./caller-path.ts";
+import { REPRO_DIR } from "./domain/repro-layout.ts";
+import type { StudyMode } from "./domain/study-mode.ts";
+import type { NotAFile } from "./domain/decide-first.ts";
+import {
+  isInside,
+  type PlanTextField,
+  type Study,
+} from "./domain/study-registry.ts";
+import type { Files } from "./ports/files.ts";
+import type { StudyRegistryCodec } from "./ports/study-registry-codec.ts";
+import type { DirEntry, ListEntries } from "./ports/list-entries.ts";
+import type { ListDir } from "./ports/talk-media.ts";
+import { readableFolders, registryOf, textAt } from "./study-registry-rule.ts";
+
+/** What reading a paper's studies needs: the disk, its listings with and without kinds, and the parsers. */
+export interface StudyDeps {
+  readonly files: Files;
+  readonly listDir: ListDir;
+  readonly entries: ListEntries;
+  readonly codec: StudyRegistryCodec;
+}
+
+/** What a decision path names on disk: a file, nothing, or something git cannot vouch for. */
+export type OnDisk = "file" | "absent" | NotAFile;
+
+const ON_DISK: Readonly<Record<DirEntry["kind"], OnDisk>> = {
+  file: "file",
+  dir: "directory",
+  symlink: "symbolic link",
+};
+
+/**
+ * What `p` is on disk, read from its directory's entries without following a link: a decision must
+ * be a regular file — git answers for a directory with the commits of anything under it, and for a
+ * link with the link, not the file it points to.
+ */
+export const onDisk = (p: string, deps: Pick<StudyDeps, "entries">): OnDisk => {
+  const e = deps
+    .entries(callerPath(dirname(p)))
+    .find((x) => x.name === basename(p));
+  return e === undefined ? "absent" : ON_DISK[e.kind];
+};
+
+/**
+ * Every file under `dir`, relative to it, `/`-separated; none when it is not a directory. A symbolic
+ * link is listed as a file — git stores it as one — and never followed: a link to the folder itself
+ * would recurse forever, and one to a tree outside would bring its files into the study.
+ */
+export const filesUnder = (
+  dir: string,
+  deps: Pick<StudyDeps, "entries">,
+  prefix = "",
+): readonly string[] =>
+  deps.entries(callerPath(dir)).flatMap(({ name, kind }) => {
+    const rel = prefix === "" ? name : `${prefix}/${name}`;
+    return kind === "dir" ? filesUnder(join(dir, name), deps, rel) : [rel];
+  });
+
+/**
+ * A study whose plan parsed with a mode: its row, the plan's path in its folder, the mode, and the
+ * plan's empty texts — none when it is ready. Only a ready plan's mode decides anything: a draft may
+ * name no outputs, or an empty decision file.
+ */
+export interface ModeStudy {
+  readonly row: Study;
+  readonly plan: string;
+  readonly mode: StudyMode;
+  readonly empty: readonly PlanTextField[];
+}
+
+/**
+ * The study `s`'s plan, when it is a plan inside a folder every reader may read through
+ * (`readableFolders`), by the registry rule's own containment test (`isInside`), that parsed with a
+ * mode; else null.
+ */
+const modeStudyOf = (
+  paper: string,
+  s: Study,
+  deps: Pick<StudyDeps, "files" | "codec">,
+  readable: (folder: string) => boolean,
+): ModeStudy | null => {
+  const plan = s.plan;
+  const text =
+    plan === undefined ||
+    !readable(s.folder) ||
+    !isInside(plan) ||
+    plan.includes("\0")
+      ? null
+      : textAt(deps.files, join(paper, REPRO_DIR, s.folder, plan));
+  if (plan === undefined || text === null) return null;
+  const parsed = deps.codec.parsePlan(text, s.kind);
+  if (parsed.kind === "unreadable" || parsed.plan.mode === undefined)
+    return null;
+  const empty = parsed.kind === "draft" ? parsed.empty : [];
+  return { row: s, plan, mode: parsed.plan.mode, empty };
+};
+
+/**
+ * Every study of the paper folder `paper` whose plan declares a mode, in registry order. A plan that
+ * does not parse is `repro/study-registered`'s to report; here it declares nothing.
+ */
+export const modeStudies = (
+  paper: string,
+  deps: Pick<StudyDeps, "files" | "codec" | "entries">,
+): readonly ModeStudy[] => {
+  const r = registryOf(paper, deps);
+  const readable = readableFolders(paper, deps);
+  return (r.kind === "read" ? r.registry.studies : []).flatMap((s) => {
+    const m = modeStudyOf(paper, s, deps, readable);
+    return m === null ? [] : [m];
+  });
+};

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

@@ -6,7 +6,11 @@
  * on the first line of `PIPELINE-STATUS.md`, with the domain's text.
  */
 import { describe, expect, it } from "vitest";
-import { memoryFiles, memoryListDir } from "./adapters/memory/index.ts";
+import {
+  memoryFiles,
+  memoryListDir,
+  memoryListEntries,
+} from "./adapters/memory/index.ts";
 import { studyRegistryCodec } from "./adapters/study-registry/index.ts";
 import {
   planTemplate,
@@ -15,7 +19,9 @@ import {
   studyMessage,
   withIndex,
   type Study,
+  type StudyPlan,
   type StudyRegistry,
+  type IndexInput,
 } from "./domain/study-registry.ts";
 import {
   registryOf,
@@ -24,6 +30,9 @@ import {
   studyRegistryRules,
 } from "./study-registry-rule.ts";
 
+/** No plan and no history: the index with every mode column `—`. */
+const NO_FACTS: IndexInput = { plans: new Map(), history: new Map() };
+
 const DIR = "/work/papers/example";
 const SCAFFOLD = {
   [`${DIR}/PIPELINE-STATUS.md`]: "# status\n",
@@ -45,7 +54,7 @@ const study = (over: Partial<Study> = {}): Study => ({
 /** A registered `repro/`: the registry, its index, and a README.md in each row's folder. */
 const registered = (
   r: StudyRegistry,
-  readme: string | null = withIndex("# Reproduction index\n", r),
+  readme: string | null = withIndex("# Reproduction index\n", r, NO_FACTS),
 ): Record<string, string> => ({
   ...SCAFFOLD,
   [`${DIR}/repro/studies.json`]: registryText(r),
@@ -73,6 +82,7 @@ function lint(
   const rule = studyRegistryRules({
     files,
     listDir: memoryListDir(files),
+    entries: memoryListEntries(files),
     codec: studyRegistryCodec,
   })[name];
   const out: Reported[] = [];
@@ -222,9 +232,9 @@ describe("repro/study-registered — reports a row's status and the index", () =
 
   it("a stale index", () => {
     const r = P1(study());
-    expect(messages(registered(r, withIndex("# x\n", P1())))).toEqual([
-      studyMessage({ problem: "stale-index", why: "differs" }),
-    ]);
+    expect(messages(registered(r, withIndex("# x\n", P1(), NO_FACTS)))).toEqual(
+      [studyMessage({ problem: "stale-index", why: "differs" })],
+    );
   });
 });
 
@@ -300,7 +310,7 @@ describe("repro/study-registered — a result_file the disk cannot hold", () =>
     const files = memoryFiles({
       ...SCAFFOLD,
       [`${DIR}/repro/studies.json`]: registryText(r),
-      [`${DIR}/repro/README.md`]: withIndex("# index\n", r),
+      [`${DIR}/repro/README.md`]: withIndex("# index\n", r, NO_FACTS),
       [`${DIR}/repro/P1-S01-baseline/README.md`]: "# s\n",
     });
     const probe = {
@@ -314,14 +324,101 @@ describe("repro/study-registered — a result_file the disk cannot hold", () =>
       studyFindings(DIR, {
         files: probe,
         listDir: memoryListDir(files),
+        entries: memoryListEntries(files),
         codec: studyRegistryCodec,
       }).map((f) => f.problem),
     ).toEqual(["result-file"]);
   });
 });
 
+describe("repro/study-registered — a study folder that is a symbolic link", () => {
+  it("never reads a plan or a result through it", () => {
+    const r = P1(
+      study({
+        status: "done",
+        result: "41 of 60",
+        result_file: "r.txt",
+        plan: "plan.json",
+      }),
+    );
+    const files = memoryFiles({
+      ...registered(r),
+      [`${DIR}/repro/P1-S01-baseline/plan.json`]: "not JSON",
+      [`${DIR}/repro/P1-S01-baseline/r.txt`]: "41 of 60\n",
+    });
+    const found = studyFindings(DIR, {
+      files,
+      listDir: memoryListDir(files),
+      entries: (dir) =>
+        memoryListEntries(files)(dir).map((e) =>
+          e.name === "P1-S01-baseline" ? { ...e, kind: "symlink" as const } : e,
+        ),
+      codec: studyRegistryCodec,
+    });
+    // Guards: the files behind the link are not read — the plan and the result read as missing.
+    expect(
+      found.map((f) =>
+        f.problem === "bad-plan" || f.problem === "result-file"
+          ? `${f.problem}:${f.why}`
+          : f.problem,
+      ),
+    ).toEqual(["result-file:missing", "bad-plan:missing"]);
+  });
+});
+
+describe("repro/study-registered — a row whose folder leads outside repro/", () => {
+  it("is reported by name, and nothing is read through it: its plan and result read as missing", () => {
+    const r = P1(
+      study({
+        folder: "../outside",
+        status: "done",
+        result: "41 of 60",
+        result_file: "r.txt",
+        plan: "plan.json",
+      }),
+    );
+    const files = memoryFiles({
+      ...SCAFFOLD,
+      [`${DIR}/repro/studies.json`]: registryText(r),
+      [`${DIR}/repro/README.md`]: withIndex("# index\n", r, NO_FACTS),
+      [`${DIR}/outside/plan.json`]: "not JSON",
+      [`${DIR}/outside/r.txt`]: "41 of 60\n",
+    });
+    const read: string[] = [];
+    const spy = {
+      ...files,
+      readBytes: (p: Parameters<typeof files.readBytes>[0]) => {
+        read.push(p);
+        return files.readBytes(p);
+      },
+      isFile: (p: Parameters<typeof files.isFile>[0]): boolean => {
+        read.push(p);
+        return files.isFile(p);
+      },
+    };
+    const found = studyFindings(DIR, {
+      files: spy,
+      listDir: memoryListDir(files),
+      entries: memoryListEntries(files),
+      codec: studyRegistryCodec,
+    });
+    // Guards: a row naming `../outside` never has a file outside `repro/` read for it.
+    expect([
+      found.map((f) =>
+        f.problem === "bad-plan" || f.problem === "result-file"
+          ? `${f.problem}:${f.why}`
+          : f.problem,
+      ),
+      read.filter((p) => p.includes("/outside/")),
+    ]).toEqual([
+      ["folder-name", "no-folder", "result-file:missing", "bad-plan:missing"],
+      [],
+    ]);
+  });
+});
+
 /** A plan as a study would hold it once the author has checked its drawn units. */
-const FILLED = planText({
+const FILLED_PLAN: StudyPlan = {
   question: "How many rules can a linter check?",
   population: {
     source: "the crawl of 2026-10-01",
@@ -330,7 +427,28 @@ const FILLED = planText({
   arms: [],
   primary_outcome: "the share of rules a linter can check",
   author_check: { by: "A. Author", date: "2026-10-14", quote: "Go." },
-});
+  mode: {
+    kind: "decide_before_run",
+    outputs: ["results.tsv"],
+    decision: {
+      file: "repro/P1-S01-baseline/decision.md",
+      note: "the sample approved",
+    },
+  },
+};
+const FILLED = planText(FILLED_PLAN);
+
+/** The index of `r` as `studies index` writes it, FILLED_PLAN as its study's plan and `history` read. */
+const FILLED_INDEX = (
+  r: StudyRegistry,
+  history: IndexInput["history"] = new Map(),
+): string =>
+  withIndex("# Reproduction index\n", r, {
+    plans: new Map([
+      ["P1-S01-baseline/plan.json", { kind: "ready", plan: FILLED_PLAN }],
+    ]),
+    history,
+  });
 
 /** A registry with a headline measurement of one running study whose row names `plan`. */
 const HEADLINE = (plan: string): StudyRegistry => ({
@@ -348,10 +466,11 @@ const HEADLINE = (plan: string): StudyRegistry => ({
 });
 
 describe("repro/study-registered — the plan a row names, read from its folder", () => {
-  it("is silent on a plan.json the author checked", () => {
+  it("is silent on a plan.json the author checked, its mode in the index", () => {
+    const r = HEADLINE("plan.json");
     expect(
       lint({
-        ...registered(HEADLINE("plan.json")),
+        ...registered(r, FILLED_INDEX(r)),
         [`${DIR}/repro/P1-S01-baseline/plan.json`]: FILLED,
       }),
     ).toEqual([]);
@@ -389,7 +508,9 @@ describe("repro/study-registered — the plan a row names, read from its folder"
     expect(
       lint({
         ...registered(HEADLINE("plan.json")),
-        [`${DIR}/repro/P1-S01-baseline/plan.json`]: planText(planTemplate()),
+        [`${DIR}/repro/P1-S01-baseline/plan.json`]: planText(
+          planTemplate("spike", "x"),
+        ),
       }).map((r) => [r.messageId, r.line]),
     ).toEqual([
       ["bad-plan", 1],
@@ -413,6 +534,7 @@ describe("repro/study-registered — a plan the disk cannot hold", () => {
       studyFindings(DIR, {
         files: probe,
         listDir: memoryListDir(files),
+        entries: memoryListEntries(files),
         codec: studyRegistryCodec,
       }).map((f) => f.problem),
     ).toEqual(["bad-plan"]);
@@ -454,3 +576,68 @@ describe("repro/study-plan-name — a plan under its old name", () => {
     ]).toEqual([[], []]);
   });
 });
+
+/** A plan whose texts are filled and which declares no mode; checked by the author when `check`. */
+const noMode = (check: boolean): string =>
+  planText({
+    question: "q",
+    population: { source: "s", draw: { kind: "all", method: "census" } },
+    arms: [],
+    primary_outcome: "o",
+    author_check: check
+      ? { by: "A. Author", date: "2026-10-14", quote: "Go." }
+      : null,
+  });
+
+/** The first line of each finding over the headline study with `plan` as its plan.json. */
+const firstLines = (plan: string): readonly string[] =>
+  lint({
+    ...registered(HEADLINE("plan.json")),
+    [`${DIR}/repro/P1-S01-baseline/plan.json`]: plan,
+  }).map((r) => r.message.split("\n")[0] ?? "");
+
+it("repro/study-registered — a measurement's plan that has run without a mode is reported; approved without one, it is no plan", () => {
+  // Guards: decide-first is the default — a measurement that ran with no mode is reported, never silent.
+  expect([firstLines(noMode(false)), firstLines(noMode(true))]).toEqual([
+    [
+      "The plan of `P1-S01`, `plan.json` in its folder, leaves `mode` empty, and the study is `running`: a plan is written before the runs. What to do: fill them in, or set the study back to `designing`.",
+      "`P1-S01` is `running` in the headline measurement `M1`, and its plan has no `author_check`. What to do: show the author the drawn units, then record their answer in the plan's `author_check` — `by`, `date`, and their words in `quote`.",
+    ],
+    [
+      "The plan of `P1-S01`, `plan.json` in its folder, is not a study plan: author_check: is set, and the plan leaves `mode` empty — the author approves a complete plan: fill them, or set author_check to null. What to do: give it the fields on the rule's page — `question`, `population`, `arms`, `primary_outcome`, and for a measurement its `mode`.",
+    ],
+  ]);
+});
+
+describe("repro/study-registered — the index's mode columns", () => {
+  it("reports an index whose mode column is not the plan's, and never compares the two read from git", () => {
+    const r = HEADLINE("plan.json");
+    const at = { commit: "a".repeat(40), date: "2026-10-14T09:00:00+05:00" };
+    const lintWith = (readme: string): string[] =>
+      lint({
+        ...registered(r, readme),
+        [`${DIR}/repro/P1-S01-baseline/plan.json`]: FILLED,
+      }).map((x) => x.messageId);
+    // Guards: the mode is in the tree, so a stale one is reported; the commits are what git said when
+    // `studies index` ran — a squash merge renames them — so whatever they say is in sync.
+    expect([
+      lintWith(withIndex("# Reproduction index\n", r, NO_FACTS)),
+      lintWith(
+        FILLED_INDEX(
+          r,
+          new Map([
+            [
+              "P1-S01",
+              {
+                kind: "read",
+                decision: at,
+                decisionDeleted: false,
+                firstOutput: at,
+              },
+            ],
+          ]),
+        ),
+      ),
+    ]).toEqual([["stale-index"], []]);
+  });
+});