paperlint 10.2.0 → 10.4.0

package/src/studies-index-modes.test.ts

@@ -0,0 +1,129 @@
+/**
+ * `paperlint studies index` and `studies new` (`src/studies.ts`) writing the index's mode columns from
+ * the plans and git's history (a stand-in), and refusing a registry whose row names a folder outside
+ * `repro/` before reading or writing through it.
+ */
+import { expect, it } from "vitest";
+import {
+  DECIDED,
+  DIR,
+  ROW,
+  planOf,
+  studies,
+  tree,
+} from "../test/study-tree.ts";
+
+const D = { commit: "d".repeat(40), date: "2026-10-14T09:12:00+05:00" };
+const A = { commit: "a".repeat(40), date: "2026-10-16T11:00:00+05:00" };
+const README = `${DIR}/repro/README.md`;
+
+/** The row of P1-S01 in the README `studies index` wrote, its cells trimmed. */
+const rowOf = (after: Readonly<Record<string, string>>): string[] =>
+  (after[README] ?? "")
+    .split("\n")
+    .filter((l) => l.startsWith("| P1-S01"))
+    .flatMap((l) => l.split("|").map((c) => c.trim()))
+    .filter((c) => c !== "");
+
+it("writes the decision's first commit and the first output's, read from git", () => {
+  const r = studies(
+    "index",
+    tree({ [`${DIR}/repro/P1-S01-outcome/RESULTS.md`]: "41 of 60\n" }),
+    { title: undefined },
+    {
+      order: {
+        kind: "read",
+        decision: D,
+        decisionDeleted: false,
+        files: [
+          { path: "decision.md", ...D, order: "same" },
+          { path: "RESULTS.md", ...A, order: "after" },
+        ],
+      },
+    },
+  );
+  // Guards: the cells the review skills read the Methods sentence's facts from.
+  expect([r.code, r.log, rowOf(r.after)]).toEqual([
+    0,
+    ["wrote the index of 1 study in papers/example/repro/README.md"],
+    [
+      "P1-S01",
+      "Outcome",
+      "running",
+      "—",
+      "no",
+      "decide_before_run",
+      "dddddddddddd 2026-10-14",
+      "aaaaaaaaaaaa 2026-10-16",
+      "[P1-S01-outcome/](P1-S01-outcome/)",
+    ],
+  ]);
+});
+
+it("rewrites the index when only git's columns moved, and leaves it when nothing did", () => {
+  const before = studies("index", tree(), { title: undefined }).after;
+  const order = {
+    kind: "read",
+    decision: D,
+    decisionDeleted: false,
+    files: [],
+  } as const;
+  const moved = studies("index", before, { title: undefined }, { order });
+  const again = studies("index", moved.after, { title: undefined }, { order });
+  // Guards: the lint ignores those two columns, so the command is what keeps them current.
+  expect([rowOf(before)[6], moved.log, again.log]).toEqual([
+    "unknown (git could not answer)",
+    ["wrote the index of 1 study in papers/example/repro/README.md"],
+    ["the index in papers/example/repro/README.md is in sync with 1 study"],
+  ]);
+});
+
+it("an exploratory study's mode carries its reason, and no commit", () => {
+  const r = studies(
+    "index",
+    tree({}, planOf({ kind: "exploratory", reason: "a first look" })),
+    { title: undefined },
+  );
+  expect(rowOf(r.after).slice(5, 8)).toEqual([
+    "exploratory: a first look",
+    "—",
+    "—",
+  ]);
+});
+
+it("refuses a registry whose row names a folder outside repro/, for index and for new", () => {
+  const escaping = tree(
+    { [`${DIR}/x/plan.json`]: JSON.stringify(planOf(DECIDED)) },
+    planOf(DECIDED),
+    { ...ROW, folder: "../x" },
+  );
+  const line =
+    "P1-S01 in papers/example/repro/studies.json names the folder `../x`, which is not one folder inside repro/: nothing is read or written through it. Give the row its own folder's name, then run this again.";
+  const index = studies("index", escaping, { title: undefined });
+  const added = studies("new", escaping, { title: "Second" });
+  // Guards: nothing is written — no README, no new folder — when a row could lead outside the paper.
+  expect([
+    [index.code, index.err, README in index.after],
+    [added.code, added.err, Object.keys(added.after).length],
+  ]).toEqual([
+    [1, [line], false],
+    [1, [line], Object.keys(escaping).length],
+  ]);
+});
+
+it("refuses a registry whose study folder is a symbolic link, for index", () => {
+  const r = studies(
+    "index",
+    tree(),
+    { title: undefined },
+    { links: [`${DIR}/repro/P1-S01-outcome`] },
+  );
+  // Guards: a linked folder leads the reads out of `repro/`, like a row naming `../x`.
+  expect([r.code, r.err, README in r.after]).toEqual([
+    1,
+    [
+      "P1-S01 in papers/example/repro/studies.json names the folder `P1-S01-outcome`, which is not one folder inside repro/: nothing is read or written through it. Give the row its own folder's name, then run this again.",
+    ],
+    false,
+  ]);
+});

package/src/studies.test.ts

@@ -5,18 +5,28 @@
  * state).
  */
 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 {
   indexBlock,
+  planTemplate,
+  planText,
   registryText,
   studyReadme,
   withIndex,
   type Study,
   type StudyRegistry,
+  type IndexInput,
 } from "./domain/study-registry.ts";
 import { runStudies, type StudiesArgs } from "./studies.ts";
 
+/** No plan and no history: the index with every mode column `—`. */
+const NO_FACTS: IndexInput = { plans: new Map(), history: new Map() };
+
 const CWD = "/work";
 const DIR = "/work/papers/example";
 const REPRO = `${DIR}/repro`;
@@ -66,9 +76,24 @@ function studies(
     {
       files,
       listDir: memoryListDir(files),
+      entries: memoryListEntries(files),
       codec: studyRegistryCodec,
       cwd,
       today: "2026-10-15",
+      git: {
+        committed: () => {
+          throw new Error(
+            "new and index never ask whether a file is committed",
+          );
+        },
+        // A history with no decision and no output committed yet.
+        order: () => ({
+          kind: "read",
+          decision: null,
+          decisionDeleted: false,
+          files: [],
+        }),
+      },
       log: (l) => log.push(l),
       err: (l) => err.push(l),
     },
@@ -101,17 +126,22 @@ describe("studies new", () => {
       status: "designing",
       date: "2026-10-15",
       in_paper: "no",
+      plan: "plan.json",
     };
     const r = P1(study(), added);
     expect({ code, err }).toEqual({ code: 0, err: [] });
     expect(after).toEqual({
       ...before,
       [`${REPRO}/P1-S02-ablation-of-the-guard/README.md`]: studyReadme(added),
+      [`${REPRO}/P1-S02-ablation-of-the-guard/plan.json`]: planText(
+        planTemplate("spike", "x"),
+      ),
       [`${REPRO}/studies.json`]: registryText(r),
-      [`${REPRO}/README.md`]: `# Reproduction index\n\nIntro.\n\n${indexBlock(r)}\n`,
+      [`${REPRO}/README.md`]: `# Reproduction index\n\nIntro.\n\n${indexBlock(r, NO_FACTS)}\n`,
     });
     expect(log).toEqual([
       "created papers/example/repro/P1-S02-ablation-of-the-guard/README.md",
+      "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",
       "added P1-S02 to papers/example/repro/studies.json: kind spike, status designing, 2026-10-15",
       "wrote the index of 2 studies in papers/example/repro/README.md",
       "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`.",
@@ -215,7 +245,7 @@ describe("studies index", () => {
   it("regenerates the block in place", () => {
     const tree = paper({
       [`${REPRO}/studies.json`]: registryText(r),
-      [`${REPRO}/README.md`]: `# I\n\n${indexBlock(P1())}\n\nTail.\n`,
+      [`${REPRO}/README.md`]: `# I\n\n${indexBlock(P1(), NO_FACTS)}\n\nTail.\n`,
     });
     const { code, log, err, after } = studies(
       { sub: "index", paperDir: "papers/example" },
@@ -228,14 +258,14 @@ describe("studies index", () => {
     });
     expect(after).toEqual({
       ...tree,
-      [`${REPRO}/README.md`]: `# I\n\n${indexBlock(r)}\n\nTail.\n`,
+      [`${REPRO}/README.md`]: `# I\n\n${indexBlock(r, NO_FACTS)}\n\nTail.\n`,
     });
   });
 
   it("says so and writes nothing when the index is in sync", () => {
     const tree = paper({
       [`${REPRO}/studies.json`]: registryText(r),
-      [`${REPRO}/README.md`]: withIndex("# I\n", r),
+      [`${REPRO}/README.md`]: withIndex("# I\n", r, NO_FACTS),
     });
     const out = studies({ sub: "index" }, tree);
     expect([out.code, out.log, out.after]).toEqual([
@@ -260,7 +290,7 @@ describe("studies index", () => {
 describe("studies index — a table a formatter padded", () => {
   it("leaves an index in sync as it is, whatever its padding", () => {
     const r = P1(study({ title: "測定 A" }));
-    const generated = withIndex("# I\n", r);
+    const generated = withIndex("# I\n", r, NO_FACTS);
     const padded = generated.replace("測定 A", "測定 A  ");
     expect(padded).not.toBe(generated);
     const tree = paper({
@@ -309,7 +339,7 @@ describe("studies — run from inside the paper folder", () => {
   it("names the folder `.`", () => {
     const tree = paper({
       [`${REPRO}/studies.json`]: registryText(P1()),
-      [`${REPRO}/README.md`]: withIndex("# I\n", P1()),
+      [`${REPRO}/README.md`]: withIndex("# I\n", P1(), NO_FACTS),
     });
     const out = studies({ sub: "index", paperDir: "." }, tree, DIR);
     expect([out.code, out.log]).toEqual([
@@ -324,12 +354,12 @@ describe("studies — the command line", () => {
     [
       "no subcommand",
       { sub: undefined },
-      'studies needs a subcommand: new or index — npx paperlint studies new <paper-dir> "<title>" [--kind <kind>] · npx paperlint studies index <paper-dir>',
+      'studies needs a subcommand: new, index or gate — npx paperlint studies new <paper-dir> "<title>" [--kind <kind>] · npx paperlint studies index <paper-dir> · npx paperlint studies gate <paper-dir> <id>',
     ],
     [
       "an unknown subcommand",
       { sub: "add" },
-      'unknown subcommand `studies add`: new or index — npx paperlint studies new <paper-dir> "<title>" [--kind <kind>] · npx paperlint studies index <paper-dir>',
+      'unknown subcommand `studies add`: new, index or gate — npx paperlint studies new <paper-dir> "<title>" [--kind <kind>] · npx paperlint studies index <paper-dir> · npx paperlint studies gate <paper-dir> <id>',
     ],
     [
       "new with no paper folder",

package/src/studies.ts

@@ -1,10 +1,13 @@
 /**
  * `paperlint studies new|index <paper-dir>` — the two commands that write a paper's study registry,
- * `repro/studies.json`, and its index in `repro/README.md` (docs/design/study-registry.md).
+ * `repro/studies.json`, and its index in `repro/README.md` (docs/design/study-registry.md) — and
+ * `studies gate <paper-dir> <id>` (src/study-gate.ts), over the studies' modes
+ * (docs/design/study-modes.md).
  *
  *   new <paper-dir> "<title>" [--kind <kind>]
- *            the next id; `repro/<id>-<slug>/README.md` with the id and title in its frontmatter; the
- *            row, `status: designing`, today's date; the index regenerated
+ *            the next id; `repro/<id>-<slug>/README.md` with the id and title in its frontmatter, and
+ *            `plan.json`, the plan's template; the row, `status: designing`, today's date, its `plan`;
+ *            the index regenerated
  *   index <paper-dir>
  *            the index block of `repro/README.md`, regenerated from the registry
  *
@@ -18,11 +21,14 @@ import type { AbsolutePath } from "./domain/paths.ts";
 import { README, REPRO_DIR } from "./domain/repro-layout.ts";
 import {
   DEFAULT_KIND,
+  PLAN_FILE,
   STUDIES_FILE,
   STUDY_KINDS,
   addStudy,
-  indexInSync,
+  indexCurrent,
   isStudyKind,
+  planTemplate,
+  planText,
   registryText,
   studyReadme,
   withIndex,
@@ -32,8 +38,12 @@ import {
 } from "./domain/study-registry.ts";
 import type { Files } from "./ports/files.ts";
 import type { StudyRegistryCodec } from "./ports/study-registry-codec.ts";
+import type { ListEntries } from "./ports/list-entries.ts";
 import type { ListDir } from "./ports/talk-media.ts";
-import { registryOf } from "./study-registry-rule.ts";
+import { readableFolders, registryOf } from "./study-registry-rule.ts";
+import { runGate } from "./study-gate.ts";
+import { indexInputOf } from "./study-index-input.ts";
+import type { GitHistory, GitOrder } from "./ports/git-history.ts";
 
 /** What one `studies` run was asked, after the command line. */
 export interface StudiesArgs {
@@ -48,8 +58,10 @@ export interface StudiesArgs {
 }
 
 export interface StudiesDeps {
+  readonly git: GitHistory & GitOrder;
   readonly files: Files;
   readonly listDir: ListDir;
+  readonly entries: ListEntries;
   readonly codec: StudyRegistryCodec;
   readonly cwd: string;
   /** Today, `YYYY-MM-DD`: the root reads the clock. */
@@ -61,7 +73,8 @@ export interface StudiesDeps {
 const NEW_USAGE =
   'npx paperlint studies new <paper-dir> "<title>" [--kind <kind>]';
 const INDEX_USAGE = "npx paperlint studies index <paper-dir>";
-const SUBS = `new or index — ${NEW_USAGE} · ${INDEX_USAGE}`;
+const GATE_USAGE = "npx paperlint studies gate <paper-dir> <id>";
+const SUBS = `new, index or gate — ${[NEW_USAGE, INDEX_USAGE, GATE_USAGE].join(" · ")}`;
 
 const STATUS_FILE = "PIPELINE-STATUS.md";
 
@@ -89,10 +102,26 @@ function registryIn(p: Paper, deps: StudiesDeps): StudyRegistry | Refusal {
     case "unreadable":
       return refuse(1, `${file} is not a study registry: ${r.why}`);
     case "read":
-      return r.registry;
+      return escaping(p, r.registry, deps) ?? r.registry;
   }
 }
 
+/** The refusal when a row names a folder that is not one inside `repro/`; null when none does. */
+function escaping(
+  p: Paper,
+  r: StudyRegistry,
+  deps: StudiesDeps,
+): Refusal | null {
+  const readable = readableFolders(p.dir, deps);
+  const s = r.studies.find((row) => !readable(row.folder));
+  return s === undefined
+    ? null
+    : refuse(
+        1,
+        `${s.id} in ${p.shown}/${REPRO_DIR}/${STUDIES_FILE} names the folder \`${s.folder}\`, which is not one folder inside ${REPRO_DIR}/: nothing is read or written through it. Give the row its own folder's name, then run this again.`,
+      );
+}
+
 const isRefusal = (v: unknown): v is Refusal =>
   typeof v === "object" && v !== null && "code" in v && "line" in v;
 
@@ -111,12 +140,13 @@ const studiesCount = (r: StudyRegistry): string =>
  * Write the index of `r` into the README; whether it wrote. A block already in sync is left as it
  * is, so the padding a formatter gave the table is never undone.
  */
-function writeIndex(dir: string, r: StudyRegistry, files: Files): boolean {
-  const before = readmeOf(dir, files);
-  if (indexInSync(before, r)) return false;
-  files.writeAtomic(
+function writeIndex(dir: string, r: StudyRegistry, deps: StudiesDeps): boolean {
+  const before = readmeOf(dir, deps.files);
+  const at = indexInputOf(dir, { kind: "read", registry: r }, deps);
+  if (indexCurrent(before, r, at)) return false;
+  deps.files.writeAtomic(
     callerPath(join(dir, REPRO_DIR, README)),
-    text(withIndex(before, r)),
+    text(withIndex(before, r, at)),
   );
   return true;
 }
@@ -151,7 +181,7 @@ function runIndex(
   if (blocked !== null) return blocked;
   const readme = `${p.shown}/${REPRO_DIR}/${README}`;
   return [
-    writeIndex(p.dir, r, deps.files)
+    writeIndex(p.dir, r, deps)
       ? `wrote the index of ${studiesCount(r)} in ${readme}`
       : `the index in ${readme} is in sync with ${studiesCount(r)}`,
   ];
@@ -178,21 +208,27 @@ function newArgs(
       );
 }
 
-/** Write a new study's README.md, the registry, and the index; the lines that say so. */
+/** Write a new study's README.md and plan.json, the registry, and the index; the lines that say so. */
 function writeStudy(
   p: Paper,
   added: { readonly registry: StudyRegistry; readonly study: Study },
-  files: Files,
+  deps: StudiesDeps,
 ): readonly string[] {
   const { study, registry } = added;
+  const { files } = deps;
   const at = (...names: readonly string[]): AbsolutePath =>
     callerPath(join(p.dir, REPRO_DIR, ...names));
   files.writeAtomic(at(study.folder, README), text(studyReadme(study)));
+  files.writeAtomic(
+    at(study.folder, PLAN_FILE),
+    text(planText(planTemplate(study.kind, study.folder))),
+  );
   files.writeAtomic(at(STUDIES_FILE), text(registryText(registry)));
-  writeIndex(p.dir, registry, files);
+  writeIndex(p.dir, registry, deps);
   const repro = `${p.shown}/${REPRO_DIR}`;
   return [
     `created ${repro}/${study.folder}/${README}`,
+    `created ${repro}/${study.folder}/${PLAN_FILE}, the study's plan: its fields are there to fill in before the first run`,
     `added ${study.id} to ${repro}/${STUDIES_FILE}: kind ${study.kind}, status ${study.status}, ${study.date}`,
     `wrote the index of ${studiesCount(registry)} in ${repro}/${README}`,
     `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 ${p.shown}\`.`,
@@ -219,35 +255,69 @@ function runNew(
         1,
         `${p.shown}/${REPRO_DIR}/${folder}/ already exists; it is never overwritten. Register it by hand, or remove it and run this again.`,
       )
-    : writeStudy(p, added, deps.files);
+    : writeStudy(p, added, deps);
 }
 
 /** The paper folder the command line names, or the refusal. */
-function paperOf(a: StudiesArgs, deps: StudiesDeps): Refusal | Paper {
+function paperOf(a: StudiesArgs, deps: StudiesDeps): Refusal | Chosen {
   if (a.sub === undefined)
     return refuse(2, `studies needs a subcommand: ${SUBS}`);
-  if (a.sub !== "new" && a.sub !== "index")
+  const sub = COMMANDS.get(a.sub);
+  if (sub === undefined)
     return refuse(2, `unknown subcommand \`studies ${a.sub}\`: ${SUBS}`);
   if (a.paperDir === undefined)
-    return refuse(
-      2,
-      `studies ${a.sub} needs the paper's folder: ${a.sub === "new" ? NEW_USAGE : INDEX_USAGE}`,
-    );
+    return refuse(2, `studies ${a.sub} needs the paper's folder: ${sub.usage}`);
   const dir = resolve(deps.cwd, a.paperDir);
   const shown = relative(deps.cwd, dir) || ".";
   return deps.files.isFile(callerPath(join(dir, STATUS_FILE)))
-    ? { dir, shown }
+    ? { dir, shown, run: sub.run }
     : refuse(2, `${shown} is not a paper folder: it has no ${STATUS_FILE}`);
 }
 
+/** `gate`: the study's id, one argument, then the gate. */
+const gateRun = (
+  p: Paper,
+  a: StudiesArgs,
+  deps: StudiesDeps,
+): Refusal | readonly string[] => {
+  if (a.title === undefined)
+    return refuse(2, `studies gate needs the study's id: ${GATE_USAGE}`);
+  const [surplus] = a.extra;
+  if (surplus !== undefined)
+    return refuse(
+      2,
+      `studies gate takes the paper's folder and one id — \`${surplus}\` is one argument too many`,
+    );
+  const out = runGate(p.dir, p.shown, a.title, deps);
+  return out.ok ? out.lines : out.refusal;
+};
+
+/** A run of a subcommand over a paper folder. */
+type Run = (
+  p: Paper,
+  a: StudiesArgs,
+  d: StudiesDeps,
+) => Refusal | readonly string[];
+
+/** The paper folder, and the run the subcommand chose. */
+interface Chosen extends Paper {
+  readonly run: Run;
+}
+
+/** Each subcommand: its usage line and its run. */
+const COMMANDS: ReadonlyMap<
+  string,
+  { readonly usage: string; readonly run: Run }
+> = new Map([
+  ["new", { usage: NEW_USAGE, run: runNew }],
+  ["index", { usage: INDEX_USAGE, run: runIndex }],
+  ["gate", { usage: GATE_USAGE, run: gateRun }],
+]);
+
 /** The run: 0 done, 1 refused by the paper's state, 2 refused by the command line. */
 export function runStudies(a: StudiesArgs, deps: StudiesDeps): number {
   const p = paperOf(a, deps);
-  const out = isRefusal(p)
-    ? p
-    : a.sub === "new"
-      ? runNew(p, a, deps)
-      : runIndex(p, a, deps);
+  const out = isRefusal(p) ? p : p.run(p, a, deps);
   if (isRefusal(out)) {
     deps.err(out.line);
     return out.code;