paperlint 10.3.0 → 10.4.1

package/src/study-gate.test.ts

@@ -0,0 +1,467 @@
+/**
+ * `paperlint studies gate <paper-dir> <id>` (`src/study-gate.ts`) on papers held in memory, git a
+ * stand-in: 0 once the decision is committed as it stands, 1 with the reason otherwise — and 0 for a
+ * study whose run waits on nothing, saying why.
+ */
+import { expect, it } from "vitest";
+import type { StudyMode } from "./domain/study-mode.ts";
+import { planText, registryText } from "./domain/study-registry.ts";
+import {
+  DATE,
+  DECIDED,
+  DIR,
+  ROW,
+  S,
+  SHA,
+  planOf,
+  studies,
+  tree,
+} from "../test/study-tree.ts";
+const DECISION = `${DIR}/repro/P1-S01-outcome/decision.md`;
+const decided = (mode: StudyMode = DECIDED) => tree({}, planOf(mode));
+
+it("open once the decision is committed as it stands: exit 0 with its commit and date", () => {
+  const r = studies(
+    "gate",
+    decided(),
+    {},
+    {
+      git: { [DECISION]: { kind: "committed", commit: SHA, date: DATE } },
+    },
+  );
+  // Guards: the line a runner's log keeps, and the exit code `gate && run` reads.
+  expect([r.code, r.log, r.err]).toEqual([
+    0,
+    [
+      `P1-S01: the decision repro/P1-S01-outcome/decision.md is committed in ${SHA} (${DATE}); the run may start.`,
+    ],
+    [],
+  ]);
+});
+
+it("closed while the decision is uncommitted, changed since its commit, or unknown to git", () => {
+  const gate = (state: Parameters<typeof studies>[3]) =>
+    studies("gate", decided(), {}, state);
+  // Guards: each reason the run must wait is said, exit 1.
+  expect(
+    [
+      gate({}),
+      gate({ git: { [DECISION]: { kind: "changed", commit: SHA } } }),
+      gate({
+        git: { [DECISION]: { kind: "unknown", why: "git is not installed" } },
+      }),
+    ].map((r) => [r.code, r.err]),
+  ).toEqual([
+    [
+      1,
+      [
+        "P1-S01: the decision repro/P1-S01-outcome/decision.md is not committed; the run waits for it. Write the decision there, commit it, then run this again.",
+      ],
+    ],
+    [
+      1,
+      [
+        `P1-S01: the decision repro/P1-S01-outcome/decision.md has changed since its last commit, ${SHA}; the run waits for the decision as committed. Commit it, then run this again.`,
+      ],
+    ],
+    [
+      1,
+      [
+        "P1-S01: git could not say whether the decision repro/P1-S01-outcome/decision.md is committed: git is not installed.",
+      ],
+    ],
+  ]);
+});
+
+it("refuses a plan that names no decision file, or one its own outputs match", () => {
+  // Guards: a gate on nothing, or on a file the run itself produces, is no gate.
+  expect([
+    studies("gate", decided({ ...DECIDED, decision: { file: " ", note: "n" } }))
+      .err,
+    studies("gate", decided({ ...DECIDED, outputs: ["*.md"] })).err,
+  ]).toEqual([
+    [
+      "P1-S01: its plan.json is a draft — `mode.decision.file` is empty; the run waits for a ready plan. Fill it in, then run this again.",
+    ],
+    [
+      "P1-S01: its decision repro/P1-S01-outcome/decision.md is matched by its output `*.md`; a decision cannot be what its own run produces.",
+    ],
+  ]);
+});
+
+it("an exploratory study's run waits on nothing: exit 0, saying so", () => {
+  // Guards: the runner may call gate on every study; the answer names the mode.
+  expect(
+    studies("gate", decided({ kind: "exploratory", reason: "a first look" })),
+  ).toMatchObject({
+    code: 0,
+    log: [
+      "P1-S01 is exploratory (a first look): it has no gate, and its results are reported as exploratory.",
+    ],
+  });
+});
+
+it("refuses a study that declares no mode, and one whose row names a folder outside repro/", () => {
+  // Guards: a measurement with no mode is not gated by default — it is refused until it says how;
+  // and a row naming `../x` is never read through, so no file outside the paper decides the gate.
+  expect(
+    [
+      studies("gate", tree({}, planOf(undefined))),
+      studies(
+        "gate",
+        tree(
+          {
+            [`${DIR}/x/plan.json`]: JSON.stringify(planOf(DECIDED)),
+          },
+          planOf(DECIDED),
+          { ...ROW, folder: "../x" },
+        ),
+      ),
+    ].map((r) => [r.code, r.err]),
+  ).toEqual([
+    [
+      1,
+      [
+        "P1-S01 declares no mode in papers/example: the plan its row names in papers/example/repro/studies.json is missing, does not parse, or has no `mode`. Lint the paper (`npx paperlint lint`) to see why.",
+      ],
+    ],
+    [
+      1,
+      [
+        "P1-S01: its row names the folder `../x`, which is not one folder inside papers/example/repro/; nothing is read through it. Give the row its own folder's name.",
+      ],
+    ],
+  ]);
+});
+
+it("refuses a command line without the study's id, or with an argument too many", () => {
+  // Guards: exit 2 is the command line's, never the paper's state.
+  expect(
+    [
+      studies("gate", decided(), { title: undefined }),
+      studies("gate", decided(), { extra: ["P1-S02"] }),
+    ].map((r) => [r.code, r.err]),
+  ).toEqual([
+    [
+      2,
+      [
+        "studies gate needs the study's id: npx paperlint studies gate <paper-dir> <id>",
+      ],
+    ],
+    [
+      2,
+      [
+        "studies gate takes the paper's folder and one id — `P1-S02` is one argument too many",
+      ],
+    ],
+  ]);
+});
+
+it("a plan it cannot read through declares no mode: no registry, a plan outside its folder, a NUL, not JSON", () => {
+  const noMode = (t: Readonly<Record<string, string>>) =>
+    studies("gate", t).err[0]?.split(":")[0];
+  // Guards: each is refused as declaring no mode — none is read past, none opens the gate.
+  expect([
+    noMode(tree({}, planOf(DECIDED), { ...ROW, plan: "../plan.json" })),
+    noMode(tree({}, planOf(DECIDED), { ...ROW, plan: "a\0b.json" })),
+    noMode({ ...decided(), [`${DIR}/repro/P1-S01-outcome/plan.json`]: "{" }),
+  ]).toEqual(Array(3).fill("P1-S01 declares no mode in papers/example"));
+});
+
+it("refuses when the registry is missing or does not parse, naming the file and the way to see why", () => {
+  const withoutRegistry = Object.fromEntries(
+    Object.entries(decided()).filter(([k]) => !k.endsWith("studies.json")),
+  );
+  const unparseable = {
+    ...decided(),
+    [`${DIR}/repro/studies.json`]: "{ not json",
+  };
+  // Guards: "no row carries this id" would send a person to the registry that is the problem.
+  expect(
+    [withoutRegistry, unparseable].map((t) => {
+      const r = studies("gate", t);
+      return [r.code, r.err];
+    }),
+  ).toEqual([
+    [
+      1,
+      [
+        "P1-S01: the registry papers/example/repro/studies.json is missing, so no row can carry this id. Run `npx paperlint lint` to see why, then run this again.",
+      ],
+    ],
+    [
+      1,
+      [
+        expect.stringMatching(
+          /^P1-S01: the registry papers\/example\/repro\/studies\.json does not parse \(.+\), so no row can carry this id\. Run `npx paperlint lint` to see why, then run this again\.$/u,
+        ),
+      ],
+    ],
+  ]);
+});
+
+it("refuses an id no row of the registry carries, saying so and what to do: exit 1", () => {
+  const r = studies("gate", decided(), { title: "P1-S09" });
+  // Guards: an id that is not in the registry is not a study that "declares no mode".
+  expect([r.code, r.log, r.err]).toEqual([
+    1,
+    [],
+    [
+      "P1-S09: no row of papers/example/repro/studies.json carries this id. Use an id from the registry, or register the study with `npx paperlint studies new`, then run this again.",
+    ],
+  ]);
+});
+
+it("refuses a decision that names a directory, whatever git says of it", () => {
+  const dir = "repro/P1-S01-outcome/decisions";
+  const r = studies(
+    "gate",
+    tree(
+      { [`${DIR}/${dir}/a.md`]: "exclude run 7\n" },
+      planOf({ ...DECIDED, decision: { file: dir, note: "n" } }),
+    ),
+    {},
+    {
+      git: {
+        [`${DIR}/${dir}`]: { kind: "committed", commit: SHA, date: DATE },
+      },
+    },
+  );
+  // Guards: git answers for a directory with the last commit under it — never a decision as committed.
+  expect([r.code, r.err]).toEqual([
+    1,
+    [
+      `P1-S01: its decision ${dir} is a directory, not a file; the run cannot be gated on it. Name the decision file in \`mode.decision.file\`.`,
+    ],
+  ]);
+});
+
+it("closed when the decision was committed and then deleted: it is not in HEAD", () => {
+  const r = studies(
+    "gate",
+    decided(),
+    {},
+    { git: { [DECISION]: { kind: "deleted", commit: SHA } } },
+  );
+  // Guards: a decision deleted in a later commit leaves a clean tree, and still gates nothing.
+  expect([r.code, r.err]).toEqual([
+    1,
+    [
+      `P1-S01: the decision repro/P1-S01-outcome/decision.md is not in HEAD: it was deleted in ${SHA}; the run waits for a decision that stands. Restore it, commit it, then run this again.`,
+    ],
+  ]);
+});
+
+it("refuses a plan that is still a draft: a mode is no decision until its plan is ready", () => {
+  const r = studies(
+    "gate",
+    decided({ ...DECIDED, outputs: [] }),
+    {},
+    { git: { [DECISION]: { kind: "committed", commit: SHA, date: DATE } } },
+  );
+  const blankReason = studies(
+    "gate",
+    decided({ kind: "exploratory", reason: " " }),
+  );
+  const twoEmpty = studies(
+    "gate",
+    decided({
+      ...DECIDED,
+      outputs: [],
+      decision: { ...DECIDED.decision, note: "" },
+    }),
+  );
+  // Guards: a draft names no outputs to keep from the decision, and an exploratory plan with no
+  // reason is no declaration; the gate opens on a ready plan only, whatever its mode.
+  expect([
+    [r.code, r.err],
+    [blankReason.code, blankReason.err],
+    [twoEmpty.code, twoEmpty.err],
+  ]).toEqual([
+    [
+      1,
+      [
+        "P1-S01: its plan.json is a draft — `mode.outputs` is empty; the run waits for a ready plan. Fill it in, then run this again.",
+      ],
+    ],
+    [
+      1,
+      [
+        "P1-S01: its plan.json is a draft — `mode.reason` is empty; the run waits for a ready plan. Fill it in, then run this again.",
+      ],
+    ],
+    [
+      1,
+      [
+        "P1-S01: its plan.json is a draft — `mode.outputs`, `mode.decision.note` are empty; the run waits for a ready plan. Fill it in, then run this again.",
+      ],
+    ],
+  ]);
+});
+
+it("refuses a decision or a study folder that is a symbolic link", () => {
+  const committed = {
+    [DECISION]: { kind: "committed", commit: SHA, date: DATE },
+  } as const;
+  const decisionLink = studies(
+    "gate",
+    { ...decided(), [DECISION]: "exclude run 7\n" },
+    {},
+    { git: committed, links: [DECISION] },
+  );
+  const folderLink = studies(
+    "gate",
+    decided(),
+    {},
+    { git: committed, links: [`${DIR}/repro/P1-S01-outcome`] },
+  );
+  // Guards: git records a link, not the file it points to; a linked folder leads out of `repro/`.
+  expect([
+    [decisionLink.code, decisionLink.err],
+    [folderLink.code, folderLink.err],
+  ]).toEqual([
+    [
+      1,
+      [
+        "P1-S01: its decision repro/P1-S01-outcome/decision.md is a symbolic link, not a file; the run cannot be gated on it. Name the decision file in `mode.decision.file`.",
+      ],
+    ],
+    [
+      1,
+      [
+        "P1-S01: its row names the folder `P1-S01-outcome`, which is a symbolic link; nothing is read through it. Give the row a real folder inside papers/example/repro/.",
+      ],
+    ],
+  ]);
+});
+
+it("never reads a plan through a backslash: `..\\x\\plan.json` is outside the folder on Windows", () => {
+  const plan = "..\\x\\plan.json";
+  const r = studies(
+    "gate",
+    tree(
+      {
+        [`${DIR}/repro/P1-S01-outcome/${plan}`]: JSON.stringify(
+          planOf(DECIDED),
+        ),
+      },
+      planOf(DECIDED),
+      { ...ROW, plan },
+    ),
+    {},
+    { git: { [DECISION]: { kind: "committed", commit: SHA, date: DATE } } },
+  );
+  // Guards: the containment test is the registry rule's own `isInside`, the same on every platform.
+  expect(r.err[0]?.split(":")[0]).toBe(
+    "P1-S01 declares no mode in papers/example",
+  );
+});
+
+it("refuses an id that two rows share, even when the first row is exploratory: exit 1, naming both folders", () => {
+  const second = { ...ROW, folder: "P1-S01-again" };
+  const t = {
+    ...tree(
+      {
+        [`${DIR}/repro/P1-S01-again/plan.json`]: JSON.stringify(
+          planOf(DECIDED),
+        ),
+      },
+      planOf({ kind: "exploratory", reason: "a first look" }),
+    ),
+    [`${DIR}/repro/studies.json`]: registryText({
+      prefix: "P1",
+      studies: [ROW, second],
+    }),
+  };
+  const r = studies("gate", t);
+  // Guards: `gate && run` must not start on the first row's mode while a later row of the same id
+  // decides before its run; lint need not have run first.
+  expect([r.code, r.log, r.err]).toEqual([
+    1,
+    [],
+    [
+      "P1-S01: 2 rows of papers/example/repro/studies.json carry this id (folders `P1-S01-outcome`, `P1-S01-again`); the gate answers for exactly one study. Give each other row the next free id and rename its folder to match, then run this again.",
+    ],
+  ]);
+});
+
+it("refuses a plan that is a symbolic link, or sits under a linked directory, naming the link: exit 1", () => {
+  const exploratory = planOf({ kind: "exploratory", reason: "a first look" });
+  const asLink = studies(
+    "gate",
+    tree({}, exploratory),
+    {},
+    { links: [`${S}/plan.json`] },
+  );
+  const sub = { ...ROW, plan: "sub/plan.json" };
+  const underLink = studies(
+    "gate",
+    tree({ [`${S}/sub/plan.json`]: planText(exploratory) }, exploratory, sub),
+    {},
+    { links: [`${S}/sub`] },
+  );
+  // Guards: a plan read through a link would open the gate on a file git does not store as the
+  // study's; the refusal names the row, the plan, the link and the fix. The files behind the link
+  // are ready exploratory plans, so a read through it would exit 0.
+  expect([asLink, underLink].map((r) => [r.code, r.log, r.err])).toEqual([
+    [
+      1,
+      [],
+      [
+        "P1-S01: the plan its row names, in papers/example/repro/P1-S01-outcome, passes through the symbolic link `plan.json`; nothing is read through a link. Replace the link with the plan file itself, then run this again.",
+      ],
+    ],
+    [
+      1,
+      [],
+      [
+        "P1-S01: the plan its row names, in papers/example/repro/P1-S01-outcome, passes through the symbolic link `sub`; nothing is read through a link. Replace the link with the plan file itself, then run this again.",
+      ],
+    ],
+  ]);
+});
+
+it("refuses a decision under a linked directory, naming the link: git cannot vouch for what lies behind it", () => {
+  const file = "repro/P1-S01-outcome/sub/decision.md";
+  const r = studies(
+    "gate",
+    tree(
+      { [`${DIR}/${file}`]: "exclude run 7\n" },
+      planOf({ ...DECIDED, decision: { file, note: "n" } }),
+    ),
+    {},
+    {
+      git: {
+        [`${DIR}/${file}`]: { kind: "committed", commit: SHA, date: DATE },
+      },
+      links: [`${S}/sub`],
+    },
+  );
+  // Guards: only the last component of the decision path was looked at, so a linked directory above
+  // it passed and git was asked about a path it stores as a link's target.
+  expect([r.code, r.err]).toEqual([
+    1,
+    [
+      `P1-S01: its decision ${file} passes through the symbolic link \`repro/P1-S01-outcome/sub\`; git records the link, not the files behind it, so the run cannot be gated on it. Name a decision file that lies in real directories in \`mode.decision.file\`.`,
+    ],
+  ]);
+});
+
+it("refuses a decision that is a FIFO or another special file: git tracks no such thing", () => {
+  const r = studies(
+    "gate",
+    { ...decided(), [DECISION]: "" },
+    {},
+    {
+      git: { [DECISION]: { kind: "committed", commit: SHA, date: DATE } },
+      others: [DECISION],
+    },
+  );
+  // Guards: a decision the listing called a file passed, and git was asked about it.
+  expect([r.code, r.err]).toEqual([
+    1,
+    [
+      "P1-S01: its decision repro/P1-S01-outcome/decision.md is a special file, not a file; the run cannot be gated on it. Name the decision file in `mode.decision.file`.",
+    ],
+  ]);
+});

package/src/study-gate.ts

@@ -0,0 +1,234 @@
+/**
+ * `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, whose row names a folder that is not one inside `repro/`, or whose id two rows
+ * share, is refused.
+ */
+import { join } from "node:path";
+import { callerPath } from "./caller-path.ts";
+import { decisionEntry, readModeStudy, type ModeStudy } from "./study-modes.ts";
+import { REPRO_DIR } from "./domain/repro-layout.ts";
+import { decisionAsOutput, type DecideFirst } from "./domain/study-mode.ts";
+import {
+  STUDIES_FILE,
+  studiesOf,
+  type RegistryState,
+  studyById,
+  type Study,
+} from "./domain/study-registry.ts";
+import type { Committed, GitHistory } from "./ports/git-history.ts";
+import type { StudyFolder } from "./ports/study-folder.ts";
+import { folderRefusalText, studyFolder } from "./study-folder.ts";
+import type { StudyDeps } from "./ports/study-deps.ts";
+import { 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 = (
+  { id, folder: studyDir }: Pick<Study, "id" | "folder">,
+  mode: DecideFirst,
+  folder: StudyFolder,
+): StudyRefusal | null => {
+  const file = mode.decision.file;
+  const glob = decisionAsOutput(studyDir, 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 = decisionEntry(folder, file);
+  switch (on.kind) {
+    case "not-a-file":
+      return refusal(
+        `${id}: its decision ${file} is a ${on.what}, not a file; the run cannot be gated on it. Name the decision file in \`mode.decision.file\`.`,
+      );
+    case "linked":
+      return refusal(
+        `${id}: its decision ${file} passes through the symbolic link \`${on.link}\`; git records the link, not the files behind it, so the run cannot be gated on it. Name a decision file that lies in real directories in \`mode.decision.file\`.`,
+      );
+    case "ok":
+      return null;
+  }
+};
+
+/** What one gate run reads with: the paper's folder, how it is shown, the study folders' reader, git. */
+interface GateRun {
+  readonly paper: string;
+  readonly shown: string;
+  readonly folder: StudyFolder;
+  readonly deps: GateDeps;
+}
+
+/** The gate of a decide-first study. */
+const gateDecided = (
+  { paper, folder, deps }: GateRun,
+  row: Study,
+  mode: DecideFirst,
+): StudyRun => {
+  const { id } = row;
+  const file = mode.decision.file;
+  const blocked = unusable(row, mode, folder);
+  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 names a folder that may not be entered; null when it may. */
+const escapingRow = (
+  shown: string,
+  row: Study,
+  folder: StudyFolder,
+): StudyRefusal | null => {
+  const why = folder.refusal(row.folder);
+  if (why === null) return null;
+  const { reason, fix } = folderRefusalText(why, shown);
+  return refusal(
+    `${row.id}: its row names the folder \`${row.folder}\`, which ${reason}; nothing is read through it. ${fix}.`,
+  );
+};
+
+/** The refusal of an id that two or more rows carry: the gate answers for exactly one study. */
+const ambiguousRefusal = (
+  shown: string,
+  id: string,
+  rows: readonly Study[],
+): StudyRefusal =>
+  refusal(
+    `${id}: ${String(rows.length)} rows of ${shown}/${REPRO_DIR}/${STUDIES_FILE} carry this id (folders ${rows.map((x) => `\`${x.folder}\``).join(", ")}); the gate answers for exactly one study. Give each other row the next free id and rename its folder to match, then run this again.`,
+  );
+
+/** 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.`,
+  );
+};
+
+/** The gate of the one row `row`. */
+const gateRow = (run: GateRun, row: Study): StudyRun => {
+  const { shown, folder, deps } = run;
+  const escaping = escapingRow(shown, row, folder);
+  if (escaping !== null) return refused(escaping);
+  const read = readModeStudy(row, folder, deps.codec);
+  if (read.kind === "linked")
+    return refused(linkedPlanRefusal(shown, row, read.link));
+  if (read.kind === "none") return refused(noModeRefusal(shown, row.id));
+  const s = read.study;
+  if (s.empty.length > 0) return refused(draftRefusal(row.id, s));
+  return s.mode.kind === "decide_before_run"
+    ? gateDecided(run, s.row, s.mode)
+    : {
+        ok: true,
+        lines: [
+          `${row.id} is exploratory (${s.mode.reason}): it has no gate, and its results are reported as exploratory.`,
+        ],
+      };
+};
+
+/** The refusal of a plan whose path passes through a symbolic link. */
+const linkedPlanRefusal = (
+  shown: string,
+  row: Study,
+  link: string,
+): StudyRefusal =>
+  refusal(
+    `${row.id}: the plan its row names, in ${shown}/${REPRO_DIR}/${row.folder}, passes through the symbolic link \`${link}\`; nothing is read through a link. Replace the link with the plan file itself, then run this again.`,
+  );
+
+/** The refusal of an id no row declares a mode for. */
+const noModeRefusal = (shown: string, id: string): StudyRefusal =>
+  refusal(
+    `${id} declares no mode in ${shown}: the plan its row names in ${shown}/${REPRO_DIR}/${STUDIES_FILE} is missing, does not parse, or has no \`mode\`. Lint the paper (\`npx paperlint lint\`) to see why.`,
+  );
+
+/** The refusal of an id that no row of the registry carries. */
+const unknownIdRefusal = (shown: string, id: string): StudyRefusal =>
+  refusal(
+    `${id}: no row of ${shown}/${REPRO_DIR}/${STUDIES_FILE} carries this id. Use an id from the registry, or register the study with \`npx paperlint studies new\`, then run this again.`,
+  );
+
+/** The refusal of a registry that is not there or does not parse: no row can carry the id. */
+const registryRefusal = (
+  shown: string,
+  id: string,
+  r: Exclude<RegistryState, { readonly kind: "read" }>,
+): StudyRefusal =>
+  refusal(
+    `${id}: the registry ${shown}/${REPRO_DIR}/${STUDIES_FILE} ${r.kind === "absent" ? "is missing" : `does not parse (${r.why})`}, so no row can carry this id. Run \`npx paperlint lint\` to see why, 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 r = registryOf(paper, deps);
+  if (r.kind !== "read") return refused(registryRefusal(shown, id, r));
+  const found = studyById(studiesOf(r), id);
+  switch (found.kind) {
+    case "none":
+      return refused(unknownIdRefusal(shown, id));
+    case "ambiguous":
+      return refused(ambiguousRefusal(shown, id, found.rows));
+    case "one":
+      return gateRow(
+        { paper, shown, folder: studyFolder(paper, deps), deps },
+        found.row,
+      );
+  }
+}