paperlint 10.2.0 → 10.4.0

package/src/study-gate.test.ts

@@ -0,0 +1,316 @@
+/**
+ * `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 {
+  DATE,
+  DECIDED,
+  DIR,
+  ROW,
+  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: no row of papers/example/repro/studies.json with this id names a plan.json that parses with `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];
+  const withoutRegistry = Object.fromEntries(
+    Object.entries(decided()).filter(([k]) => !k.endsWith("studies.json")),
+  );
+  // Guards: each is refused as declaring no mode — none is read past, none opens the gate.
+  expect([
+    noMode(withoutRegistry),
+    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(4).fill("P1-S01 declares no mode in papers/example"));
+});
+
+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 not one folder inside papers/example/repro/; nothing is read through it. Give the row its own folder's name.",
+      ],
+    ],
+  ]);
+});
+
+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",
+  );
+});

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];
+  });
+};