paperlint 10.4.0 → 10.4.1

package/src/study-folder.test.ts

@@ -0,0 +1,237 @@
+/**
+ * The one reader of what lies inside a study's folder (`src/study-folder.ts`), over a disk held in
+ * memory whose listing marks chosen paths as symbolic links: a file is read, a missing path is absent,
+ * and a path that passes through a link — at the file or at any directory above it — is `linked`,
+ * naming the link, with nothing read.
+ */
+import { expect, it } from "vitest";
+import { memoryFiles, memoryListEntries } from "./adapters/memory/index.ts";
+import { folderRefusalText, studyFolder } from "./study-folder.ts";
+
+const PAPER = "/work/papers/example";
+const FOLDER = `${PAPER}/repro/P1-S01-outcome`;
+const TREE = {
+  [`${FOLDER}/plan.json`]: "{}",
+  [`${FOLDER}/sub/plan.json`]: "{ }",
+  [`${FOLDER}/sub/deeper/out.tsv`]: "x\n",
+  [`${FOLDER}/other/note.md`]: "n\n",
+  [`${PAPER}/repro/P1-S01-linked/plan.json`]: "{}",
+};
+
+/** The reader over `TREE`, `links` and `others` being absolute paths the listing reports as links and as neither file nor directory (a FIFO); plus every path the disk was asked for. */
+const reader = (links: readonly string[], others: readonly string[] = []) => {
+  const files = memoryFiles(TREE);
+  const asked: string[] = [];
+  return {
+    asked,
+    sf: studyFolder(PAPER, {
+      files: {
+        ...files,
+        readBytes: (p) => {
+          asked.push(p);
+          return files.readBytes(p);
+        },
+        isFile: (p) => {
+          asked.push(p);
+          return files.isFile(p);
+        },
+      },
+      entries: (dir) =>
+        memoryListEntries(files)(dir).map((e) => {
+          if (links.includes(`${dir}/${e.name}`))
+            return { ...e, kind: "symlink" as const };
+          return others.includes(`${dir}/${e.name}`)
+            ? { ...e, kind: "other" as const }
+            : e;
+        }),
+    }),
+  };
+};
+
+it("reads a file inside the folder; a path that is nothing, a directory, or under a file is absent", () => {
+  const { sf } = reader([]);
+  // Guards: the plain cases, so that `linked` below is the link's doing and not a broken reader.
+  expect([
+    sf.read("P1-S01-outcome", "plan.json"),
+    sf.read("P1-S01-outcome", "./sub/plan.json"),
+    sf.read("P1-S01-outcome", "nope.json"),
+    sf.read("P1-S01-outcome", "sub"),
+    sf.read("P1-S01-outcome", "plan.json/x"),
+    sf.read("P1-S01-outcome", "sub/missing/plan.json"),
+  ]).toEqual([
+    { kind: "text", text: "{}" },
+    { kind: "text", text: "{ }" },
+    { kind: "absent" },
+    { kind: "absent" },
+    { kind: "absent" },
+    { kind: "absent" },
+  ]);
+});
+
+it("a link at the file, or at any directory above it, is `linked` and names the link; nothing is read", () => {
+  const { sf, asked } = reader([
+    `${FOLDER}/plan.json`,
+    `${FOLDER}/sub`,
+    `${FOLDER}/other/note.md`,
+  ]);
+  // Guards: the file behind a link is never asked for, wherever on the path the link stands; the
+  // link is named relative to the folder, as far down as the walk got.
+  expect([
+    sf.read("P1-S01-outcome", "plan.json"),
+    sf.read("P1-S01-outcome", "sub/plan.json"),
+    sf.read("P1-S01-outcome", "sub/deeper/out.tsv"),
+    sf.read("P1-S01-outcome", "other/note.md"),
+  ]).toEqual([
+    { kind: "linked", link: "plan.json" },
+    { kind: "linked", link: "sub" },
+    { kind: "linked", link: "sub" },
+    { kind: "linked", link: "other/note.md" },
+  ]);
+  expect(asked).toEqual([]);
+});
+
+it("`locate` says what is there without reading it", () => {
+  const { sf, asked } = reader([`${FOLDER}/sub`]);
+  // Guards: the answer for a result file's existence needs no read of its bytes.
+  expect([
+    sf.locate("P1-S01-outcome", "plan.json"),
+    sf.locate("P1-S01-outcome", "sub/deeper/out.tsv"),
+    sf.locate("P1-S01-outcome", "nope"),
+  ]).toEqual([
+    { kind: "file" },
+    { kind: "linked", link: "sub" },
+    { kind: "absent" },
+  ]);
+  expect(asked).toEqual([]);
+});
+
+it("reads nothing outside the folder: a NUL, a path up and out, a folder name that is not one folder, a folder that is a link", () => {
+  const { sf, asked } = reader([`${PAPER}/repro/P1-S01-outcome`]);
+  const open = reader([]).sf;
+  // Guards: the reader itself holds the containment the callers rely on — the folder that is a link
+  // reads as absent (not `linked`), as the registry rule's page says.
+  expect([
+    open.read("P1-S01-outcome", "a\0b"),
+    open.read("P1-S01-outcome", "../x/plan.json"),
+    open.read("../x", "plan.json"),
+    open.read("a/b", "plan.json"),
+    sf.read("P1-S01-outcome", "plan.json"),
+  ]).toEqual(Array(5).fill({ kind: "absent" }));
+  expect(asked).toEqual([]);
+});
+
+it("a file that vanishes between the walk and the read is absent", () => {
+  const files = memoryFiles(TREE);
+  const sf = studyFolder(PAPER, {
+    files: { ...files, isFile: () => false },
+    entries: memoryListEntries(files),
+  });
+  // Guards: the reader never throws on a race; it says there is nothing.
+  expect(sf.read("P1-S01-outcome", "plan.json")).toEqual({ kind: "absent" });
+});
+
+it("a link is named as far down as the walk got, even when its name repeats above it", () => {
+  const files = memoryFiles({ [`${FOLDER}/a/a/x.txt`]: "x\n" });
+  const sf = studyFolder(PAPER, {
+    files,
+    entries: (dir) =>
+      memoryListEntries(files)(dir).map((e) =>
+        `${dir}/${e.name}` === `${FOLDER}/a/a`
+          ? { ...e, kind: "symlink" as const }
+          : e,
+      ),
+  });
+  // Guards: the second `a` is the link, not the first.
+  expect(sf.read("P1-S01-outcome", "a/a/x.txt")).toEqual({
+    kind: "linked",
+    link: "a/a",
+  });
+});
+
+it("a row's folder may be entered unless it is no one folder inside repro/ or is a link", () => {
+  const { sf } = reader([`${PAPER}/repro/P1-S01-linked`]);
+  // Guards: the one place the folder check lives; each refusal is its own reason.
+  expect([
+    sf.refusal("P1-S01-outcome"),
+    sf.refusal("../x"),
+    sf.refusal("a/b"),
+    sf.refusal("P1-S01-linked"),
+  ]).toEqual([null, "not-a-folder", "not-a-folder", "symbolic-link"]);
+  expect([
+    folderRefusalText("not-a-folder", "p"),
+    folderRefusalText("symbolic-link", "p"),
+  ]).toEqual([
+    {
+      reason: "is not one folder inside p/repro/",
+      fix: "Give the row its own folder's name",
+    },
+    {
+      reason: "is a symbolic link",
+      fix: "Give the row a real folder inside p/repro/",
+    },
+  ]);
+});
+
+it("a path in the paper is a file, a directory, nothing, or a link on the way — the first one, from the paper's root", () => {
+  const { sf, asked } = reader([`${FOLDER}/sub`, `${FOLDER}/plan.json`]);
+  const at = (p: string) => sf.entryAt(p);
+  // Guards: the decision file is judged by every component of its path, not by its last one.
+  expect([
+    at("repro/P1-S01-outcome/other/note.md"),
+    at("repro/P1-S01-outcome/other"),
+    at("repro/P1-S01-outcome/nope.md"),
+    at("repro/P1-S01-outcome/sub/plan.json"),
+    at("repro/P1-S01-outcome/plan.json"),
+    at("../outside.md"),
+    at("a\0b"),
+  ]).toEqual([
+    { kind: "file" },
+    { kind: "dir" },
+    { kind: "absent" },
+    { kind: "linked", link: "repro/P1-S01-outcome/sub" },
+    { kind: "linked", link: "repro/P1-S01-outcome/plan.json" },
+    { kind: "absent" },
+    { kind: "absent" },
+  ]);
+  expect(asked).toEqual([]);
+});
+
+it("lists every file under a study's folder, relative and /-separated; a link is one entry, never descended into", () => {
+  const { sf, asked } = reader([`${FOLDER}/sub`, `${FOLDER}/other/note.md`]);
+  // Guards: the outputs of a study are listed by the same reader that reads its plan — a linked
+  // directory is a file as git stores it, and what lies behind it is not the study's.
+  expect(sf.list("P1-S01-outcome")).toEqual([
+    "plan.json",
+    "sub",
+    "other/note.md",
+  ]);
+  expect(asked).toEqual([]);
+});
+
+it("lists nothing of a folder that may not be entered or is not there", () => {
+  const { sf } = reader([`${PAPER}/repro/P1-S01-linked`]);
+  // Guards: a linked study folder brings no foreign file into the study, nor does a name outside repro/.
+  expect([
+    sf.list("P1-S01-linked"),
+    sf.list("../x"),
+    sf.list("P1-S09-missing"),
+  ]).toEqual([[], [], []]);
+});
+
+it("something that is not a regular file — a FIFO, a socket — is absent as a plan or a result, other as a path, and still listed by name", () => {
+  const { sf, asked } = reader([], [`${FOLDER}/plan.json`]);
+  // Guards: the listing used to call every such entry a file, so the reader would open it (a FIFO
+  // blocks) and report it present.
+  expect([
+    sf.locate("P1-S01-outcome", "plan.json"),
+    sf.read("P1-S01-outcome", "plan.json"),
+    sf.entryAt("repro/P1-S01-outcome/plan.json"),
+    sf.list("P1-S01-outcome"),
+  ]).toEqual([
+    { kind: "absent" },
+    { kind: "absent" },
+    { kind: "other" },
+    ["plan.json", "sub/plan.json", "sub/deeper/out.tsv", "other/note.md"],
+  ]);
+  expect(asked).toEqual([]);
+});

package/src/study-folder.ts

@@ -0,0 +1,176 @@
+/**
+ * The one reader of what lies inside a study's folder, `repro/<folder>/<path>`, and of the decision
+ * file that lies elsewhere in the paper. It never follows a symbolic link: a path is walked one
+ * component at a time by the entries of each directory (`ListEntries`, which does not follow links),
+ * and a path that passes through a link — the file itself, or any directory above it — is `linked`,
+ * naming the link, before a single byte is read. Every reader of a study takes a `StudyFolder` and
+ * not `Files`, so a read that follows a link is not what those readers are handed.
+ *
+ * What goes through it, and who builds it (once per run, from the paper's folder):
+ *   - the plan of a row: `repro/study-registered`, `repro/outputs-before-decision`, `studies gate`
+ *     and the index's mode columns;
+ *   - the result file of a row: `repro/study-registered`;
+ *   - whether a row's folder may be entered at all (`refusal`): `studies gate`, `studies index|new`;
+ *   - the decision file's path (`entryAt`): the gate and the order rule.
+ * The outputs of a study are listed through it too (`list`).
+ * A study folder that is itself a link, or a folder name that is not one folder inside `repro/`, is
+ * never entered: its files read as `absent`.
+ *
+ * A link made between the walk and the read is not caught: paperlint guards against accidents, not
+ * against an author who races their own tooling (docs/design/study-modes.md, the threat model).
+ */
+import { join, posix } from "node:path";
+import { callerPath } from "./caller-path.ts";
+import { REPRO_DIR } from "./domain/repro-layout.ts";
+import {
+  isFolderName,
+  isInside,
+  type Located,
+} from "./domain/study-registry.ts";
+import type { Files } from "./ports/files.ts";
+import type { DirEntry, ListEntries } from "./ports/list-entries.ts";
+import type {
+  FolderRefusal,
+  PathEntry,
+  StudyFolder,
+} from "./ports/study-folder.ts";
+
+/** What a refusal says of the folder a row names: `which <reason>`, and the fix without its full stop. */
+export const folderRefusalText = (
+  why: FolderRefusal,
+  shown: string,
+): { readonly reason: string; readonly fix: string } =>
+  why === "not-a-folder"
+    ? {
+        reason: `is not one folder inside ${shown}/${REPRO_DIR}/`,
+        fix: "Give the row its own folder's name",
+      }
+    : {
+        reason: "is a symbolic link",
+        fix: `Give the row a real folder inside ${shown}/${REPRO_DIR}/`,
+      };
+
+/** What the entry `name` of the directory `dir` is; undefined when there is none. */
+const kindAt = (
+  entries: ListEntries,
+  dir: string,
+  name: string,
+): DirEntry["kind"] | undefined =>
+  entries(callerPath(dir)).find((e) => e.name === name)?.kind;
+
+const ENTRY: Readonly<Record<Exclude<DirEntry["kind"], "symlink">, PathEntry>> =
+  {
+    file: { kind: "file" },
+    dir: { kind: "dir" },
+    other: { kind: "other" },
+  };
+
+/**
+ * What the entry `name` below `dir`/`above` is: every component on the way is looked up in its
+ * directory's entries, and the first that is a symbolic link ends the walk (an entry under a
+ * directory that is not there is not listed, so it can be no link).
+ */
+const walk = (
+  dir: string,
+  above: readonly string[],
+  name: string,
+  entries: ListEntries,
+): PathEntry => {
+  const path = [...above, name];
+  const at = path.findIndex(
+    (c, i) => kindAt(entries, join(dir, ...path.slice(0, i)), c) === "symlink",
+  );
+  if (at >= 0) return { kind: "linked", link: path.slice(0, at + 1).join("/") };
+  const kind = kindAt(entries, join(dir, ...above), name);
+  return kind === undefined || kind === "symlink"
+    ? { kind: "absent" }
+    : ENTRY[kind];
+};
+
+/** `path` as the directories above its last component, and that component. */
+const split = (
+  path: string,
+): {
+  readonly above: readonly string[];
+  readonly name: string;
+} => {
+  const normal = posix.normalize(path);
+  return {
+    above: posix
+      .dirname(normal)
+      .split("/")
+      .filter((c) => c !== "."),
+    name: posix.basename(normal),
+  };
+};
+
+/** What `path` in `folder` is, by the entries of the paper folder `paper`; nothing is read. */
+const locateIn = (
+  paper: string,
+  entries: ListEntries,
+  folder: string,
+  path: string,
+): Located => {
+  // A NUL is no path the disk can hold, and probing one throws; the rest never leaves the folder.
+  if (!isFolderName(folder) || !isInside(path) || path.includes("\0"))
+    return { kind: "absent" };
+  const { above, name } = split(path);
+  // The folder is walked too: one that is a link is never entered, and reads as absent.
+  const found = walk(join(paper, REPRO_DIR), [folder, ...above], name, entries);
+  // A directory or a special file is no file to read: it reads as nothing.
+  if (found.kind === "dir" || found.kind === "other") return { kind: "absent" };
+  if (found.kind !== "linked") return found;
+  return found.link === folder
+    ? { kind: "absent" }
+    : { kind: "linked", link: found.link.slice(folder.length + 1) };
+};
+
+/** Why `folder` may not be entered in the paper folder `paper`; null when it may. */
+const refusalOf = (
+  paper: string,
+  entries: ListEntries,
+  folder: string,
+): FolderRefusal | null => {
+  if (!isFolderName(folder)) return "not-a-folder";
+  return kindAt(entries, join(paper, REPRO_DIR), folder) === "symlink"
+    ? "symbolic-link"
+    : null;
+};
+
+/** Every file under `dir`, relative to it; a link is a file, and is not entered. */
+const filesUnder = (
+  dir: string,
+  entries: ListEntries,
+  prefix = "",
+): readonly string[] =>
+  entries(callerPath(dir)).flatMap(({ name, kind }) => {
+    const rel = prefix === "" ? name : `${prefix}/${name}`;
+    return kind === "dir" ? filesUnder(join(dir, name), entries, rel) : [rel];
+  });
+
+/** The reader of the study folders of the paper folder `paper`. */
+export const studyFolder = (
+  paper: string,
+  deps: { readonly files: Files; readonly entries: ListEntries },
+): StudyFolder => ({
+  refusal: (folder) => refusalOf(paper, deps.entries, folder),
+  locate: (folder, path) => locateIn(paper, deps.entries, folder, path),
+  read: (folder, path) => {
+    const at = locateIn(paper, deps.entries, folder, path);
+    if (at.kind !== "file") return at;
+    const p = callerPath(join(paper, REPRO_DIR, folder, path));
+    const bytes = deps.files.isFile(p) ? deps.files.readBytes(p) : null;
+    return bytes === null
+      ? { kind: "absent" }
+      : { kind: "text", text: new TextDecoder().decode(bytes) };
+  },
+  list: (folder) =>
+    refusalOf(paper, deps.entries, folder) === null
+      ? filesUnder(join(paper, REPRO_DIR, folder), deps.entries)
+      : [],
+  entryAt: (path) => {
+    if (!isInside(path) || path.includes("\0")) return { kind: "absent" };
+    const { above, name } = split(path);
+    return walk(paper, above, name, deps.entries);
+  },
+});

package/src/study-gate.test.ts

@@ -5,11 +5,13 @@
  */
 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,
@@ -120,7 +122,7 @@ it("refuses a study that declares no mode, and one whose row names a folder outs
     [
       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.",
+        "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.",
       ],
     ],
     [
@@ -158,16 +160,56 @@ it("refuses a command line without the study's id, or with an 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"));
+  ]).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", () => {
@@ -287,7 +329,7 @@ it("refuses a decision or a study folder that is a symbolic link", () => {
     [
       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.",
+        "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/.",
       ],
     ],
   ]);
@@ -314,3 +356,112 @@ it("never reads a plan through a backslash: `..\\x\\plan.json` is outside the fo
     "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`.",
+    ],
+  ]);
+});