paperlint 10.3.0 → 10.4.1

package/src/study-index-input.ts

@@ -0,0 +1,31 @@
+/**
+ * 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 {
+  folderKey,
+  type IndexInput,
+  type RegistryState,
+} from "./domain/study-registry.ts";
+import {
+  decideFirstStudies,
+  type OrderDeps,
+} from "./outputs-before-decision-rule.ts";
+import { studyFolder } from "./study-folder.ts";
+import { plansOf } 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(r, studyFolder(paper, deps), deps.codec),
+  history: new Map(
+    decideFirstStudies(paper, deps).map((s) => [
+      folderKey(s.folder, s.plan),
+      indexHistory(s),
+    ]),
+  ),
+});

package/src/study-modes.ts

@@ -0,0 +1,107 @@
+/**
+ * Reading a paper's studies with their modes: each registered study whose `plan.json` parses with a
+ * `mode`, and how a decision's path stands. 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 { posix } from "node:path";
+import { filter, map, pipe } from "remeda";
+import type { NotAFile } from "./domain/decide-first.ts";
+import type { StudyMode } from "./domain/study-mode.ts";
+import {
+  studiesOf,
+  type PlanTextField,
+  type RegistryState,
+  type Study,
+} from "./domain/study-registry.ts";
+import type { StudyRegistryCodec } from "./ports/study-registry-codec.ts";
+import type { StudyFolder } from "./ports/study-folder.ts";
+
+/** Whether a decision path is one git can vouch for: a file or nothing yet; else why not. */
+export type DecisionEntry =
+  | { readonly kind: "ok" }
+  | { readonly kind: "not-a-file"; readonly what: NotAFile }
+  | { readonly kind: "linked"; readonly link: string };
+
+/**
+ * What the decision file `file` (relative to the paper) is, read through `folder` without following
+ * a link: a decision must be a regular file in real directories — git answers for a directory with
+ * the commits of anything under it, for a link with the link and not the file it points to, and for a
+ * path through a linked directory with what lies behind the link.
+ */
+export const decisionEntry = (
+  folder: StudyFolder,
+  file: string,
+): DecisionEntry => {
+  const at = folder.entryAt(file);
+  if (at.kind === "dir") return { kind: "not-a-file", what: "directory" };
+  if (at.kind === "other") return { kind: "not-a-file", what: "special file" };
+  if (at.kind !== "linked") return { kind: "ok" };
+  return at.link === posix.normalize(file)
+    ? { kind: "not-a-file", what: "symbolic link" }
+    : at;
+};
+
+/**
+ * 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[];
+}
+
+/** What reading the plan of one row gave: its mode study, nothing, or a link on the way to it. */
+export type ModeRead =
+  | { readonly kind: "mode"; readonly study: ModeStudy }
+  | { readonly kind: "none" }
+  | { readonly kind: "linked"; readonly link: string };
+
+/**
+ * The plan of the row `s`, read through `folder` (`src/study-folder.ts`, which follows no link and
+ * enters no folder that is not one inside `repro/`): its mode study when the plan parsed with a
+ * mode; a link on the way to it; else nothing.
+ */
+export const readModeStudy = (
+  s: Study,
+  folder: StudyFolder,
+  codec: StudyRegistryCodec,
+): ModeRead => {
+  const plan = s.plan;
+  if (plan === undefined) return { kind: "none" };
+  const read = folder.read(s.folder, plan);
+  if (read.kind === "linked") return read;
+  if (read.kind === "absent") return { kind: "none" };
+  const parsed = codec.parsePlan(read.text, s.kind);
+  if (parsed.kind === "unreadable" || parsed.plan.mode === undefined)
+    return { kind: "none" };
+  const empty = parsed.kind === "draft" ? parsed.empty : [];
+  return {
+    kind: "mode",
+    study: { row: s, plan, mode: parsed.plan.mode, empty },
+  };
+};
+
+/**
+ * Every study of the registry `r` whose plan declares a mode, in registry order. A plan that does
+ * not parse, or is reached through a link, is `repro/study-registered`'s to report; here it declares
+ * nothing.
+ */
+export const modeStudies = (
+  r: RegistryState,
+  folder: StudyFolder,
+  codec: StudyRegistryCodec,
+): readonly ModeStudy[] =>
+  pipe(
+    studiesOf(r),
+    map((s) => readModeStudy(s, folder, codec)),
+    filter(isMode),
+    map((m) => m.study),
+  );
+
+/** A plan read that declared a mode. */
+const isMode = (m: ModeRead): m is Extract<ModeRead, { kind: "mode" }> =>
+  m.kind === "mode";

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,8 +19,11 @@ import {
   studyMessage,
   withIndex,
   type Study,
+  type StudyPlan,
   type StudyRegistry,
+  type IndexInput,
 } from "./domain/study-registry.ts";
+import { planOf } from "../test/study-tree.ts";
 import {
   registryOf,
   STUDY_REGISTRY_RULE_LEVELS,
@@ -24,6 +31,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 +55,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 +83,7 @@ function lint(
   const rule = studyRegistryRules({
     files,
     listDir: memoryListDir(files),
+    entries: memoryListEntries(files),
     codec: studyRegistryCodec,
   })[name];
   const out: Reported[] = [];
@@ -222,9 +233,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 +311,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 +325,187 @@ 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 plan or a result file reached through a link inside a study folder", () => {
+  const r = P1(
+    study({
+      kind: "spike",
+      status: "done",
+      result: "41 of 60",
+      result_file: "out/r.txt",
+      plan: "sub/plan.json",
+    }),
+  );
+  const S = `${DIR}/repro/P1-S01-baseline`;
+  const found = (links: readonly string[]) => {
+    const files = memoryFiles({
+      ...registered(r),
+      [`${S}/sub/plan.json`]: planText(planOf(undefined)),
+      [`${S}/out/r.txt`]: "41 of 60\n",
+    });
+    return studyFindings(DIR, {
+      files,
+      listDir: memoryListDir(files),
+      entries: (dir) =>
+        memoryListEntries(files)(dir).map((e) =>
+          links.includes(`${dir}/${e.name}`)
+            ? { ...e, kind: "symlink" as const }
+            : e,
+        ),
+      codec: studyRegistryCodec,
+    });
+  };
+
+  it("silent while no link is on the way; each link is reported with its name, and the file behind it is not read", () => {
+    const linked = found([`${S}/sub`, `${S}/out`]).map((f) =>
+      f.problem === "bad-plan" || f.problem === "result-file"
+        ? studyMessage(f).split("\n")[0]
+        : f.problem,
+    );
+    // Guards: both files exist and parse, so only the link can make a finding. The text names the
+    // file, the link and the fix.
+    expect([found([]).map((f) => f.problem), linked]).toEqual([
+      [],
+      [
+        "`repro/studies.json`: the `result_file` of `P1-S01`, `out/r.txt`, passes through the symbolic link `out` in its folder; nothing is read through a link. What to do: name a regular file inside the study's folder, or replace the link with the file itself.",
+        "`repro/studies.json`: the `plan` of `P1-S01`, `sub/plan.json`, passes through the symbolic link `sub` in its folder; nothing is read through a link. What to do: replace the link with the plan file itself.",
+      ],
+    ]);
+  });
+});
+
+describe("repro/study-registered — a result file or a plan that is a FIFO", () => {
+  it("is not a file in its folder: reported as missing, never opened", () => {
+    const r = P1(
+      study({
+        status: "done",
+        result: "41 of 60",
+        result_file: "r.txt",
+        plan: "plan.json",
+      }),
+    );
+    const S = `${DIR}/repro/P1-S01-baseline`;
+    const files = memoryFiles({
+      ...registered(r),
+      [`${S}/plan.json`]: "{}",
+      [`${S}/r.txt`]: "41 of 60\n",
+    });
+    const found = studyFindings(DIR, {
+      files,
+      listDir: memoryListDir(files),
+      entries: (dir) =>
+        memoryListEntries(files)(dir).map((e) =>
+          [`${S}/plan.json`, `${S}/r.txt`].includes(`${dir}/${e.name}`)
+            ? { ...e, kind: "other" as const }
+            : e,
+        ),
+      codec: studyRegistryCodec,
+    });
+    // Guards: `existingResults` used `Files.isFile`; the listing said "file" for a FIFO and the result passed.
+    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 +514,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 +553,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 +595,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 +621,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 +663,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"], []]);
+  });
+});