paperlint 10.4.0 → 10.4.1

package/src/domain/study-registry.ts

@@ -248,8 +248,22 @@ export type ParsedPlan =
     }
   | { readonly kind: "unreadable"; readonly why: string };
 
+/**
+ * What a path inside a study's folder is, found without reading it or following a link: a regular
+ * file, nothing, or a path that passes through a symbolic link (`link`: the first one, relative to
+ * the folder).
+ */
+export type Located =
+  | { readonly kind: "file" }
+  | { readonly kind: "absent" }
+  | { readonly kind: "linked"; readonly link: string };
+
 /** What a study's folder holds of the plan its row names: absent, or what its text parsed to. */
-export type PlanState = { readonly kind: "absent" } | ParsedPlan;
+export type PlanState =
+  | { readonly kind: "absent" }
+  /** The plan's path passes through a symbolic link, `link` (relative to the folder); never read. */
+  | { readonly kind: "linked"; readonly link: string }
+  | ParsedPlan;
 
 /** The decision file `paperlint studies new` names for a study in `folder`, relative to the paper. */
 export const decisionPath = (folder: string): string =>
@@ -303,8 +317,8 @@ export interface StudyInput {
   readonly registry: RegistryState;
   /** `repro/README.md`'s text; null when there is none. */
   readonly readme: string | null;
-  /** Each `<folder>/<result_file>` of the registry that is a file. */
-  readonly existingResults: ReadonlySet<string>;
+  /** What each `<folder>/<result_file>` of the registry is, as `locate` found it; one not listed is absent. */
+  readonly results: ReadonlyMap<string, Located>;
   /** The plan each row names, by `<folder>/<plan>`; one not listed is absent. */
   readonly plans: ReadonlyMap<string, PlanState>;
 }
@@ -351,6 +365,13 @@ export type StudyFinding =
       readonly path: string;
       readonly why: "missing" | "outside";
     }
+  | {
+      readonly problem: "result-file";
+      readonly id: string;
+      readonly path: string;
+      readonly why: "linked";
+      readonly link: string;
+    }
   | {
       readonly problem: "no-successor";
       readonly id: string;
@@ -390,6 +411,13 @@ export type StudyFinding =
       readonly path: string;
       readonly why: "missing" | "outside";
     }
+  | {
+      readonly problem: "bad-plan";
+      readonly id: string;
+      readonly path: string;
+      readonly why: "linked";
+      readonly link: string;
+    }
   | {
       readonly problem: "bad-plan";
       readonly id: string;
@@ -479,24 +507,66 @@ export const isInside = (path: string): boolean => {
 export const isFolderName = (folder: string): boolean =>
   folder !== "." && folder !== ".." && /^[^/\\\0]+$/u.test(folder);
 
+/**
+ * The rows of a registry that carry an id: exactly one, none, or several. The one way to address a
+ * study by its id — a caller that wants "the study P1-S01" gets a row only when there is exactly one,
+ * so no command can act on the first of two rows by accident. A registry may still hold two rows of
+ * one id (`repro/study-registered` reports it); this says so instead of choosing.
+ */
+export type StudyLookup =
+  | { readonly kind: "one"; readonly row: Study }
+  | { readonly kind: "none" }
+  | { readonly kind: "ambiguous"; readonly rows: readonly Study[] };
+
+/** The rows of a registry that was read; none when there is no registry, or it does not parse. */
+export const studiesOf = (state: RegistryState): readonly Study[] =>
+  state.kind === "read" ? state.registry.studies : [];
+
+/** The rows of `studies` whose id is `id`, as a `StudyLookup`. */
+export const studyById = (
+  studies: readonly Study[],
+  id: string,
+): StudyLookup => {
+  const [first, ...rest] = studies.filter((s) => s.id === id);
+  if (first === undefined) return { kind: "none" };
+  return rest.length === 0
+    ? { kind: "one", row: first }
+    : { kind: "ambiguous", rows: [first, ...rest] };
+};
+
+/**
+ * The key a path inside a study's folder is held under: `<folder>/<path>`. A plan (`StudyInput.plans`,
+ * `IndexInput.plans`), the history of its study (`IndexInput.history`) and a result file
+ * (`StudyInput.results`) are all found by it.
+ */
+export const folderKey = (folder: string, path: string): string =>
+  `${folder}/${path}`;
+
 /**
  * The `<folder>/<plan>` of each row whose plan lies inside its folder: the files the judge needs read
  * (`StudyInput.plans`). A plan outside its folder is reported without being read.
  */
 export const planKeys = (r: StudyRegistry): readonly string[] =>
-  planRefs(r).map((p) => p.key);
+  planRefs(r).map((p) => folderKey(p.folder, p.plan));
 
-/** Each plan `planKeys` names, with the kind of the study whose row names it: what its parser needs. */
-export const planRefs = (
-  r: StudyRegistry,
-): readonly {
-  readonly key: string;
+/** A plan a row names: where it is read from, and the kind of the study — what its parser needs. */
+export interface PlanRef {
   readonly folder: string;
+  readonly plan: string;
   readonly kind: StudyKind;
-}[] =>
+}
+
+/** Each plan `planKeys` names. */
+export const planRefs = (r: StudyRegistry): readonly PlanRef[] =>
   r.studies.flatMap((s) =>
     s.plan !== undefined && isInside(s.plan) && isFolderName(s.folder)
-      ? [{ key: `${s.folder}/${s.plan}`, folder: s.folder, kind: s.kind }]
+      ? [
+          {
+            folder: s.folder,
+            plan: s.plan,
+            kind: s.kind,
+          },
+        ]
       : [],
   );
 
@@ -522,7 +592,7 @@ const badId: RowCheck = ({ r, s }) =>
 
 /** Reported once, on the first row that holds the id. */
 const duplicateId: RowCheck = (row) =>
-  row.r.studies.filter((o) => o.id === row.s.id).length > 1 &&
+  studyById(row.r.studies, row.s.id).kind === "ambiguous" &&
   isFirst(row, (o) => o.id)
     ? { problem: "duplicate-id", id: row.s.id }
     : null;
@@ -572,9 +642,23 @@ const resultFile: RowCheck = ({ s, input }) => {
   if (path === undefined) return null;
   if (!isInside(path))
     return { problem: "result-file", id: s.id, path, why: "outside" };
-  return input.existingResults.has(`${s.folder}/${path}`)
-    ? null
-    : { problem: "result-file", id: s.id, path, why: "missing" };
+  const found = input.results.get(folderKey(s.folder, path)) ?? {
+    kind: "absent",
+  };
+  switch (found.kind) {
+    case "file":
+      return null;
+    case "linked":
+      return {
+        problem: "result-file",
+        id: s.id,
+        path,
+        why: "linked",
+        link: found.link,
+      };
+    case "absent":
+      return { problem: "result-file", id: s.id, path, why: "missing" };
+  }
 };
 
 const noSuccessor: RowCheck = ({ r, s }) => {
@@ -593,13 +677,15 @@ const unknownMeasurement: RowCheck = ({ r, s }) =>
     ? null
     : { problem: "unknown-measurement", id: s.id, measurement: s.measurement };
 
-/** The state of the plan the row names (absent when outside its folder); null when it names none. */
-const planOf = ({ s, input }: Row): PlanState | null => {
-  if (s.plan === undefined) return null;
-  return isInside(s.plan)
-    ? (input.plans.get(`${s.folder}/${s.plan}`) ?? { kind: "absent" })
+/** The state of the plan `plan` of the row `s` (absent when outside its folder): the one place a plan is looked up. */
+const planStateOf = (input: StudyInput, s: Study, plan: string): PlanState =>
+  isInside(plan)
+    ? (input.plans.get(folderKey(s.folder, plan)) ?? { kind: "absent" })
     : { kind: "absent" };
-};
+
+/** The state of the plan the row names; null when it names none. */
+const planOf = ({ s, input }: Row): PlanState | null =>
+  s.plan === undefined ? null : planStateOf(input, s, s.plan);
 
 const hasRun = (s: Study): boolean => RAN_STATUSES.includes(s.status);
 
@@ -613,6 +699,8 @@ const planFinding = (
   switch (state.kind) {
     case "absent":
       return { ...at, why: "missing" };
+    case "linked":
+      return { ...at, why: "linked", link: state.link };
     case "unreadable":
       return { ...at, why: "unreadable", reasons: state.why };
     case "draft":
@@ -630,11 +718,7 @@ const badPlan: RowCheck = ({ s, input }) => {
   if (path === undefined) return null;
   if (!isInside(path))
     return { problem: "bad-plan", id: s.id, path, why: "outside" };
-  return planFinding(
-    s,
-    path,
-    input.plans.get(`${s.folder}/${path}`) ?? { kind: "absent" },
-  );
+  return planFinding(s, path, planStateOf(input, s, path));
 };
 
 /** A plan under its old name: read, and named for renaming. */
@@ -801,8 +885,8 @@ const cell = (s: string): string =>
 
 /**
  * What the index is generated from beyond the registry: the plans by `<folder>/<plan>` (as
- * `StudyInput.plans`), and the history of each decide-first study by id. A study with no history
- * listed shows `not read` — the lint, which never compares those columns, asks none.
+ * `StudyInput.plans`), and the history of each decide-first study by the same key. A study with no
+ * history listed shows `not read` — the lint, which never compares those columns, asks none.
  */
 export interface IndexInput {
   readonly plans: ReadonlyMap<string, PlanState>;
@@ -816,10 +900,11 @@ const declaredMode = (
 ): StudyMode | null => {
   const state =
     s.plan !== undefined && isInside(s.plan)
-      ? plans.get(`${s.folder}/${s.plan}`)
+      ? plans.get(folderKey(s.folder, s.plan))
       : undefined;
   return state === undefined ||
     state.kind === "absent" ||
+    state.kind === "linked" ||
     state.kind === "unreadable"
     ? null
     : (state.plan.mode ?? null);
@@ -828,7 +913,10 @@ const declaredMode = (
 /** What the index shows of `s` beyond its row. */
 const factsOf = (s: Study, at: IndexInput): IndexFacts => ({
   mode: declaredMode(s, at.plans),
-  history: at.history.get(s.id) ?? null,
+  history:
+    (s.plan === undefined
+      ? undefined
+      : at.history.get(folderKey(s.folder, s.plan))) ?? null,
 });
 
 /**
@@ -1039,7 +1127,9 @@ const HEADS: { readonly [P in Problem]: (f: FindingOf[P]) => string } = {
   "no-result": (f) =>
     `${REGISTRY}: ${tick(f.id)} is \`done\` without ${f.missing.map(tick).join(" and ")}. What to do: write the one-line result and the file it is read from (\`result\`, \`result_file\`), or set the status it really has.`,
   "result-file": (f) =>
-    `${REGISTRY}: the \`result_file\` of ${tick(f.id)}, ${tick(f.path)}, ${f.why === "missing" ? "is not a file in its folder" : "is outside its folder"}. What to do: name a file that exists, relative to the study's folder.`,
+    f.why === "linked"
+      ? `${REGISTRY}: the \`result_file\` of ${tick(f.id)}, ${tick(f.path)}, passes through the symbolic link ${tick(f.link)} 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.`
+      : `${REGISTRY}: the \`result_file\` of ${tick(f.id)}, ${tick(f.path)}, ${f.why === "missing" ? "is not a file in its folder" : "is outside its folder"}. What to do: name a file that exists, relative to the study's folder.`,
   "no-successor": (f) =>
     `${REGISTRY}: ${tick(f.id)} is \`superseded\` ${f.superseded_by === null ? "without `superseded_by`" : `by ${tick(f.superseded_by)}, which is no study in the registry`}. What to do: name the id of the study that replaced it.`,
   "stale-index": (f) => `${STALE_HEAD[f.why]} ${RUN_INDEX}`,
@@ -1059,6 +1149,8 @@ const HEADS: { readonly [P in Problem]: (f: FindingOf[P]) => string } = {
     switch (f.why) {
       case "missing":
         return `${REGISTRY}: ${of} is not a file in its folder. What to do: write the plan there (its fields are on the rule's page), or correct the row's \`plan\`.`;
+      case "linked":
+        return `${REGISTRY}: ${of} passes through the symbolic link ${tick(f.link)} in its folder; nothing is read through a link. What to do: replace the link with the plan file itself.`;
       case "outside":
         return `${REGISTRY}: ${of} is outside its folder. What to do: keep the plan in the study's folder, as \`${PLAN_FILE}\`, and name it relative to the folder.`;
       case "unreadable":

package/src/outputs-before-decision-rule.test.ts

@@ -10,7 +10,6 @@ import { expect, it } from "vitest";
 import { gitHistory } from "./adapters/git/index.ts";
 import {
   nodeFiles,
-  nodeListDir,
   nodeListEntries,
   spawnProcess,
 } from "./adapters/node/index.ts";
@@ -42,7 +41,6 @@ const T = (h: number): string =>
 const lint = (repo: string, file = "p/PIPELINE-STATUS.md"): string[] => {
   const rule = outputsBeforeDecisionRules({
     files: nodeFiles,
-    listDir: nodeListDir,
     entries: nodeListEntries,
     codec: studyRegistryCodec,
     git: gitHistory(spawnProcess(), { PATH: String(process.env.PATH) }),
@@ -204,3 +202,50 @@ it("never reads through a study folder that is a symbolic link", () => {
   // Guards: the outputs behind the link are not this paper's study; nothing is read through it.
   expect(lint(repo)).toEqual([]);
 });
+
+it("a plan that is a symbolic link declares no mode: the order of its study is not judged", () => {
+  const repo = join(root, "plan-link");
+  initRepo(repo);
+  mkdirSync(join(repo, "p/elsewhere"), { recursive: true });
+  writeFileSync(join(repo, "p/elsewhere/plan.json"), planText(planOf(DECIDED)));
+  mkdirSync(join(repo, S), { recursive: true });
+  symlinkSync("../../elsewhere/plan.json", join(repo, S, "plan.json"));
+  commit(
+    repo,
+    {
+      ...Object.fromEntries(
+        Object.entries(PAPER).filter(([k]) => k !== `${S}/plan.json`),
+      ),
+      [`${S}/RESULTS.md`]: "41 of 60\n",
+    },
+    T(9),
+  );
+  commit(repo, { [`${S}/decision.md`]: "exclude run 7\n" }, T(10));
+  // Guards: read through the link, the plan is a decide-first one and its output precedes its
+  // decision (`output-before-decision`); a link is read through by nothing, so the study declares no mode.
+  expect(lint(repo)).toEqual([]);
+});
+
+it("loud on a decision under a linked directory: git records the link, not the files behind it", () => {
+  const repo = join(root, "decision-dir-link");
+  initRepo(repo);
+  mkdirSync(join(repo, "p/elsewhere"), { recursive: true });
+  writeFileSync(join(repo, "p/elsewhere/decision.md"), "exclude run 7\n");
+  const file = "repro/P1-S01-outcome/sub/decision.md";
+  commit(
+    repo,
+    {
+      ...PAPER,
+      [`${S}/plan.json`]: planText(
+        planOf({ ...DECIDED, decision: { file, note: "n" } }),
+      ),
+    },
+    T(9),
+  );
+  symlinkSync("../../elsewhere", join(repo, S, "sub"));
+  commit(repo, {}, T(10));
+  commit(repo, { [`${S}/RESULTS.md`]: "41 of 60\n" }, T(11));
+  // Guards: the decision file exists, and is committed as a path through a link; the order proof
+  // would be read from the link's history. The study is reported instead.
+  expect(lint(repo)).toEqual(["decision-linked"]);
+});

package/src/outputs-before-decision-rule.ts

@@ -14,13 +14,9 @@
  * Reported on `PIPELINE-STATUS.md`, first line, like the other `repro/` rules.
  */
 import { basename, dirname, join } from "node:path";
+import { filter, map, pipe } from "remeda";
 import { callerPath } from "./caller-path.ts";
-import {
-  filesUnder,
-  modeStudies,
-  onDisk,
-  type StudyDeps,
-} from "./study-modes.ts";
+import { decisionEntry, modeStudies, type ModeStudy } from "./study-modes.ts";
 import {
   judgeOrder,
   orderMessage,
@@ -28,11 +24,15 @@ import {
   type OrderFinding,
 } from "./domain/decide-first.ts";
 import { REPRO_DIR } from "./domain/repro-layout.ts";
+import type { DecideFirst } from "./domain/study-mode.ts";
 import type {
   FolderRuleContext,
   FolderRuleModule,
 } from "./folder-venue-rule.ts";
 import type { GitOrder } from "./ports/git-history.ts";
+import type { StudyDeps } from "./ports/study-deps.ts";
+import { studyFolder } from "./study-folder.ts";
+import { registryOf } from "./study-registry-rule.ts";
 import { rulePageUrl } from "./venue-rules.ts";
 
 const STATUS_FILE = "PIPELINE-STATUS.md";
@@ -46,32 +46,41 @@ export interface OrderDeps extends StudyDeps {
 export const decideFirstStudies = (
   paper: string,
   deps: OrderDeps,
-): readonly DecideFirstStudy[] =>
-  modeStudies(paper, deps).flatMap(({ row, plan, mode, empty }) => {
-    // Only a ready plan decides: a draft may name no outputs, or an empty decision file.
-    if (mode.kind !== "decide_before_run" || empty.length > 0) return [];
-    const folder = join(paper, REPRO_DIR, row.folder);
-    const decision = join(paper, mode.decision.file);
-    const on = onDisk(decision, deps);
-    return [
-      {
+): readonly DecideFirstStudy[] => {
+  const reader = studyFolder(paper, deps);
+  return pipe(
+    modeStudies(registryOf(paper, deps), reader, deps.codec),
+    filter(isDecidedAndReady),
+    map(({ row, plan, mode }): DecideFirstStudy => {
+      const folder = join(paper, REPRO_DIR, row.folder);
+      const decision = join(paper, mode.decision.file);
+      const on = decisionEntry(reader, mode.decision.file);
+      return {
         id: row.id,
         folder: row.folder,
         plan,
         mode,
-        tree: filesUnder(folder, deps),
+        tree: reader.list(row.folder),
         facts:
-          on === "directory" || on === "symbolic link"
-            ? { kind: "not-a-file", what: on }
-            : deps.git.order(callerPath(folder), callerPath(decision)),
-      },
-    ];
-  });
+          on.kind === "ok"
+            ? deps.git.order(callerPath(folder), callerPath(decision))
+            : on,
+      };
+    }),
+  );
+};
+
+/** Only a ready plan decides: a draft may name no outputs, or an empty decision file. */
+const isDecidedAndReady = (
+  s: ModeStudy,
+): s is ModeStudy & { readonly mode: DecideFirst } =>
+  s.mode.kind === "decide_before_run" && s.empty.length === 0;
 
 const PROBLEMS: readonly OrderFinding["problem"][] = [
   "decision-is-output",
   "decision-deleted",
   "decision-not-file",
+  "decision-linked",
   "no-history",
   "shallow",
   "undecided-output",

package/src/ports/list-entries.ts

@@ -1,17 +1,20 @@
 /**
  * A directory's entries with what each one is, read without following a symbolic link — so a walk
  * that descends only into `dir` entries can neither loop on a link to an ancestor nor wander into a
- * tree outside through one. The walker of a study's folder (`src/study-modes.ts`) reads with it.
+ * tree outside through one. The reader of a study's folder
+ * (`src/study-folder.ts`), outputs listing included (`StudyFolder.list`), reads with it.
  */
 import type { AbsolutePath } from "../domain/paths.ts";
 
 /**
- * One entry of a directory: a directory, a symbolic link (not followed), or a file — anything else on
- * disk (a socket, a FIFO) reads as a file: a name, never descended into.
+ * One entry of a directory: a regular file, a directory, a symbolic link (not followed), or `other` —
+ * anything that is none of those (a FIFO, a socket, a device). An `other` entry is a name and nothing
+ * more: it is never read (opening a FIFO blocks) and never descended into, and an outputs listing
+ * still names it.
  */
 export interface DirEntry {
   readonly name: string;
-  readonly kind: "file" | "dir" | "symlink";
+  readonly kind: "file" | "dir" | "symlink" | "other";
 }
 
 /** The entries of `dir`; none when it does not exist or is not a directory. */

package/src/ports/study-deps.ts

@@ -0,0 +1,14 @@
+/**
+ * What the readers of a paper's studies are handed: the disk, the entries of a directory with what
+ * each is (no symbolic link followed), and the parsers of the registry and its plans. The study folder's
+ * reader (`src/study-folder.ts`), the gate and the order rule are built from it.
+ */
+import type { Files } from "./files.ts";
+import type { ListEntries } from "./list-entries.ts";
+import type { StudyRegistryCodec } from "./study-registry-codec.ts";
+
+export interface StudyDeps {
+  readonly files: Files;
+  readonly entries: ListEntries;
+  readonly codec: StudyRegistryCodec;
+}

package/src/ports/study-folder.ts

@@ -0,0 +1,38 @@
+/**
+ * The reads a paper's study folders allow, shaped by what the study readers need: a row's folder is
+ * entered or refused, a path inside it is located or read, the files under it are listed, and the
+ * decision file's path is walked — none of it by following a symbolic link. The reader of every plan,
+ * result file, output listing and decision (`src/study-folder.ts`) is this port's one implementation.
+ */
+import type { Located } from "../domain/study-registry.ts";
+
+/** What reading a path inside a study's folder gave. */
+export type FolderRead =
+  | { readonly kind: "text"; readonly text: string }
+  | { readonly kind: "absent" }
+  | { readonly kind: "linked"; readonly link: string };
+
+/** What a path in the paper is: `Located`, a directory, or something that is no regular file (a FIFO, a socket). */
+export type PathEntry =
+  Located | { readonly kind: "dir" } | { readonly kind: "other" };
+
+/** Why a row's folder may not be entered: it is no one folder inside `repro/`, or it is a link. */
+export type FolderRefusal = "not-a-folder" | "symbolic-link";
+
+/** The reads a paper's study folders allow. */
+export interface StudyFolder {
+  /** Why `folder` may not be entered; null when it may. */
+  readonly refusal: (folder: string) => FolderRefusal | null;
+  /** What `path` in `folder` is; nothing is read. */
+  readonly locate: (folder: string, path: string) => Located;
+  /** The text of the file at `path` in `folder`. */
+  readonly read: (folder: string, path: string) => FolderRead;
+  /**
+   * Every file under `folder`, relative to it and `/`-separated: a symbolic link is listed as a file
+   * (git stores it as one) and never descended into; a FIFO or a socket is listed by name too (it is
+   * never read). None for a folder that may not be entered.
+   */
+  readonly list: (folder: string) => readonly string[];
+  /** What `path`, relative to the paper, is: a decision file is held to be a regular file. */
+  readonly entryAt: (path: string) => PathEntry;
+}

package/src/presets.ts

@@ -406,8 +406,7 @@ export type ShippedVenue = Pick<
 >;
 
 /**
- * A resolved preset as a name knows it: its label, its aliases, its chain. Pure. (Not Remeda's
- * `pick`: the app layer may not import it — `boundaries/dependencies`, `APP_EXTERNALS`.)
+ * A resolved preset as a name knows it: its label, its aliases, its chain. Pure.
  */
 export const venueOf = ({
   label,

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

@@ -98,7 +98,7 @@ it("refuses a registry whose row names a folder outside repro/, for index and fo
     { ...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.";
+    "P1-S01 in papers/example/repro/studies.json names the folder `../x`, which is not one folder inside papers/example/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.
@@ -122,7 +122,7 @@ it("refuses a registry whose study folder is a symbolic link, for index", () =>
   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.",
+      "P1-S01 in papers/example/repro/studies.json names the folder `P1-S01-outcome`, which is a symbolic link: nothing is read or written through it. Give the row a real folder inside papers/example/repro/, then run this again.",
     ],
     false,
   ]);

package/src/studies.ts

@@ -16,6 +16,7 @@
  * registry is refused with the file to write rather than given a guessed one.
  */
 import { join, relative, resolve } from "node:path";
+import { find, map, pipe } from "remeda";
 import { callerPath } from "./caller-path.ts";
 import type { AbsolutePath } from "./domain/paths.ts";
 import { README, REPRO_DIR } from "./domain/repro-layout.ts";
@@ -37,10 +38,12 @@ import {
   type StudyRegistry,
 } from "./domain/study-registry.ts";
 import type { Files } from "./ports/files.ts";
+import type { FolderRefusal } from "./ports/study-folder.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 { readableFolders, registryOf } from "./study-registry-rule.ts";
+import { registryOf } from "./study-registry-rule.ts";
+import { folderRefusalText, studyFolder } from "./study-folder.ts";
 import { runGate } from "./study-gate.ts";
 import { indexInputOf } from "./study-index-input.ts";
 import type { GitHistory, GitOrder } from "./ports/git-history.ts";
@@ -106,20 +109,26 @@ function registryIn(p: Paper, deps: StudiesDeps): StudyRegistry | Refusal {
   }
 }
 
-/** The refusal when a row names a folder that is not one inside `repro/`; null when none does. */
+/** The refusal when a row names a folder that may not be entered; 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 folder = studyFolder(p.dir, deps);
+  const found = pipe(
+    r.studies,
+    map((row) => ({ row, why: folder.refusal(row.folder) })),
+    find(
+      (x): x is typeof x & { readonly why: FolderRefusal } => x.why !== null,
+    ),
+  );
+  if (found === undefined) return null;
+  const { reason, fix } = folderRefusalText(found.why, p.shown);
+  return refuse(
+    1,
+    `${found.row.id} in ${p.shown}/${REPRO_DIR}/${STUDIES_FILE} names the folder \`${found.row.folder}\`, which ${reason}: nothing is read or written through it. ${fix}, then run this again.`,
+  );
 }
 
 const isRefusal = (v: unknown): v is Refusal =>