paperlint 10.3.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);
+  },
+});