paperlint 10.4.0 → 10.4.1

package/src/study-gate.ts

@@ -6,21 +6,26 @@
  *   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.
+ * 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 {
-  modeStudies,
-  onDisk,
-  type ModeStudy,
-  type StudyDeps,
-} from "./study-modes.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 type { Study } from "./domain/study-registry.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 { readableFolders, registryOf } from "./study-registry-rule.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,
@@ -68,34 +73,48 @@ export const gateLine = (
  * 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">,
+  { id, folder: studyDir }: Pick<Study, "id" | "folder">,
   mode: DecideFirst,
-  deps: GateDeps,
+  folder: StudyFolder,
 ): StudyRefusal | null => {
   const file = mode.decision.file;
-  const glob = decisionAsOutput(folder, mode);
+  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 = 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;
+  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: string,
-  { id, folder }: Study,
+  { paper, folder, deps }: GateRun,
+  row: Study,
   mode: DecideFirst,
-  deps: GateDeps,
 ): StudyRun => {
+  const { id } = row;
   const file = mode.decision.file;
-  const blocked = unusable(paper, { id, folder }, mode, deps);
+  const blocked = unusable(row, mode, folder);
   if (blocked !== null) return refused(blocked);
   const g = gateLine(
     id,
@@ -105,25 +124,30 @@ const gateDecided = (
   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. */
+/** The refusal when the row names a folder that may not be entered; null when it may. */
 const escapingRow = (
-  paper: string,
   shown: string,
-  id: string,
-  deps: GateDeps,
+  row: Study,
+  folder: StudyFolder,
 ): 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),
+  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}.`,
   );
-  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 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(", ");
@@ -133,29 +157,78 @@ const draftRefusal = (id: string, s: ModeStudy): StudyRefusal => {
   );
 };
 
-/** `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);
+/** 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 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));
+  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(paper, s.row, s.mode, deps)
+    ? gateDecided(run, s.row, s.mode)
     : {
         ok: true,
         lines: [
-          `${id} is exploratory (${s.mode.reason}): it has no gate, and its results are reported as exploratory.`,
+          `${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,
+      );
+  }
 }

package/src/study-index-input.ts

@@ -3,12 +3,17 @@
  * 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 {
+  folderKey,
+  type IndexInput,
+  type RegistryState,
+} from "./domain/study-registry.ts";
 import {
   decideFirstStudies,
   type OrderDeps,
 } from "./outputs-before-decision-rule.ts";
-import { plansOf, readableFolders } from "./study-registry-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 = (
@@ -16,8 +21,11 @@ export const indexInputOf = (
   r: RegistryState,
   deps: OrderDeps,
 ): IndexInput => ({
-  plans: plansOf(paper, r, deps, readableFolders(paper, deps)),
+  plans: plansOf(r, studyFolder(paper, deps), deps.codec),
   history: new Map(
-    decideFirstStudies(paper, deps).map((s) => [s.id, indexHistory(s)]),
+    decideFirstStudies(paper, deps).map((s) => [
+      folderKey(s.folder, s.plan),
+      indexHistory(s),
+    ]),
   ),
 });

package/src/study-modes.ts

@@ -1,69 +1,47 @@
 /**
  * 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`
+ * `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 { 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 { 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 {
-  isInside,
+  studiesOf,
   type PlanTextField,
+  type RegistryState,
   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;
+import type { StudyFolder } from "./ports/study-folder.ts";
 
-const ON_DISK: Readonly<Record<DirEntry["kind"], OnDisk>> = {
-  file: "file",
-  dir: "directory",
-  symlink: "symbolic link",
-};
+/** 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 `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.
+ * 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 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];
+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;
 };
 
-/**
- * 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
@@ -76,45 +54,54 @@ export interface ModeStudy {
   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 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.
+ * 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.
  */
-const modeStudyOf = (
-  paper: string,
+export const readModeStudy = (
   s: Study,
-  deps: Pick<StudyDeps, "files" | "codec">,
-  readable: (folder: string) => boolean,
-): ModeStudy | null => {
+  folder: StudyFolder,
+  codec: StudyRegistryCodec,
+): ModeRead => {
   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 (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 null;
+    return { kind: "none" };
   const empty = parsed.kind === "draft" ? parsed.empty : [];
-  return { row: s, plan, mode: parsed.plan.mode, empty };
+  return {
+    kind: "mode",
+    study: { 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.
+ * 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 = (
-  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];
-  });
-};
+  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

@@ -23,6 +23,7 @@ import {
   type StudyRegistry,
   type IndexInput,
 } from "./domain/study-registry.ts";
+import { planOf } from "../test/study-tree.ts";
 import {
   registryOf,
   STUDY_REGISTRY_RULE_LEVELS,
@@ -366,6 +367,92 @@ describe("repro/study-registered — a study folder that is a symbolic link", ()
   });
 });
 
+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(