paperlint 10.4.0 → 10.4.1

package/src/adapters/latex/captions.ts

@@ -0,0 +1,56 @@
+/** The captions of a document: the text a reader sees under a figure or a table. */
+import { isDefined } from "remeda";
+import { isDefinition, isUnrendered } from "./hidden.ts";
+import {
+  collapse,
+  isNode,
+  mandatory,
+  textOf,
+  visited,
+  type Macro,
+  type Node,
+} from "./nodes.ts";
+import type { ParsedTex } from "./parse.ts";
+
+const isCaption = (n: Node): n is Macro =>
+  n.type === "macro" && n.content === "caption";
+
+/** Math a reader sees as symbols: it counts as one word, and says nothing else. */
+const MATH_NODES: ReadonlySet<Node["type"]> = new Set<Node["type"]>([
+  "inlinemath",
+  "displaymath",
+  "mathenv",
+]);
+const MATH_WORD = "math";
+
+/** The escapes of a character LaTeX sets for itself: `\%` is a percent sign the reader sees. */
+const ESCAPED: ReadonlySet<string> = new Set(["%", "&", "#", "$", "_"]);
+
+/** What a reader sees of a caption's nodes: its words, its escapes, and one word for each formula. */
+const captionText = (nodes: readonly Node[]): string =>
+  nodes
+    .map((n) => {
+      if (MATH_NODES.has(n.type)) return MATH_WORD;
+      if (n.type === "macro" && ESCAPED.has(n.content)) return n.content;
+      return n.type === "group" ? captionText(n.content) : textOf([n]);
+    })
+    .join("");
+
+/**
+ * The text of every `\caption` in document order: its last mandatory argument, whatever optional
+ * argument (`\caption[Short]{…}`), star or whitespace comes before it. What a reader never sees is
+ * pruned (`isUnrendered`: comments, code), and so is a macro definition's body, where the caption
+ * is written but not set. A caption with no word in it is left out.
+ */
+export function captionsOf(t: ParsedTex): readonly string[] {
+  return visited(
+    t.root,
+    (v, parent) => isUnrendered(v, parent) || isDefinition(v),
+  )
+    .filter(isNode)
+    .filter(isCaption)
+    .map((m) => mandatory(m).at(-1))
+    .filter(isDefined)
+    .map((a) => collapse(captionText(a.content)).trim())
+    .filter((text) => text !== "");
+}

package/src/adapters/latex/index.ts

@@ -50,6 +50,7 @@ export {
   textOf,
 } from "./nodes.ts";
 export { documentBodyOf, includesOf } from "./includes.ts";
+export { captionsOf } from "./captions.ts";
 export { headingsOf } from "./headings.ts";
 export { outlineOf } from "./outline.ts";
 export { parseLatex, type ParsedTex } from "./parse.ts";

package/src/adapters/latex/parse.ts

@@ -92,6 +92,12 @@ const DECLARATION_SIGNATURES = Object.fromEntries([
   ...signed(["linespread", "geometry", "newgeometry"], "m"),
 ]);
 
+/**
+ * `\caption` takes a star, an optional short caption and the text (`\caption*[Short]{Text}`). unified-latex
+ * signs it `o m`, so a starred caption came back with its star as the text and the text as a group beside it.
+ */
+const CAPTION_SIGNATURES = Object.fromEntries(signed(["caption"], "s o m"));
+
 /**
  * Macros that define other macros or environments. A heading in a body is no section where it is
  * written, so the outline skips these; the rendered text reads a body as written, since nothing here
@@ -133,6 +139,7 @@ const parser = once(() =>
       ...LINK_SIGNATURES,
       ...DECLARATION_SIGNATURES,
       ...DEF_SIGNATURES,
+      ...CAPTION_SIGNATURES,
     },
   }),
 );

package/src/adapters/node/list-entries.io.ts

@@ -7,7 +7,8 @@ import type { DirEntry, ListEntries } from "../../ports/list-entries.ts";
 /** What a directory entry is, its link never followed. */
 const kindOf = (d: Readonly<Dirent>): DirEntry["kind"] => {
   if (d.isSymbolicLink()) return "symlink";
-  return d.isDirectory() ? "dir" : "file";
+  if (d.isDirectory()) return "dir";
+  return d.isFile() ? "file" : "other";
 };
 
 export const nodeListEntries: ListEntries = (

package/src/adapters/node/list-entries.test.ts

@@ -2,6 +2,7 @@
  * `nodeListEntries`: a directory's entries with their kinds, a symbolic link reported as one and never
  * followed; none for a missing directory or a file; other errors thrown.
  */
+import { spawnSync } from "node:child_process";
 import { mkdirSync, symlinkSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { describe, expect, it } from "vitest";
@@ -29,6 +30,23 @@ describe("nodeListEntries", () => {
     ]);
   });
 
+  // A FIFO needs `mkfifo`, which Windows does not have; the reason is said, not hidden.
+  it.skipIf(process.platform === "win32")(
+    "names a FIFO as neither a file nor a directory: other",
+    () => {
+      const d = join(root, "fifo");
+      mkdirSync(d, { recursive: true });
+      const made = spawnSync("mkfifo", [join(d, "pipe")]);
+      expect(made.status).toBe(0);
+      writeFileSync(join(d, "a.md"), "");
+      // Guards: it was reported as a file, so a reader would open it and block.
+      expect(sorted(d)).toEqual([
+        { name: "a.md", kind: "file" },
+        { name: "pipe", kind: "other" },
+      ]);
+    },
+  );
+
   it("is empty for a directory that does not exist, and for a file", () => {
     writeFileSync(join(root, "f"), "");
     expect([

package/src/domain/decide-first.test.ts

@@ -180,6 +180,23 @@ it("a decision that names a directory is reported, and no history is judged", ()
   ]);
 });
 
+it("a decision behind a linked directory is reported with the link, and no history is judged", () => {
+  // Guards: git records a path through a link as what lies behind the link.
+  expect(
+    judgeOrder({
+      ...STUDY,
+      facts: { kind: "linked", link: "repro/P1-S01-x/sub" },
+    }),
+  ).toEqual([
+    {
+      problem: "decision-linked",
+      id: "P1-S01",
+      file: "repro/P1-S01-x/decision.md",
+      link: "repro/P1-S01-x/sub",
+    },
+  ]);
+});
+
 const PAGE =
   "\nRule repro/outputs-before-decision: https://github.com/zernie/paperlint/blob/main/docs/rules/repro/outputs-before-decision.md";
 
@@ -192,6 +209,12 @@ const ALL: readonly OrderFinding[] = [
     glob: "**/*.md",
   },
   { problem: "decision-deleted", id: "P1-S01", file: "repro/d.md" },
+  {
+    problem: "decision-not-file",
+    id: "P1-S01",
+    file: "repro/p",
+    what: "special file",
+  },
   {
     problem: "decision-not-file",
     id: "P1-S01",
@@ -204,6 +227,12 @@ const ALL: readonly OrderFinding[] = [
     file: "repro/l.md",
     what: "symbolic link",
   },
+  {
+    problem: "decision-linked",
+    id: "P1-S01",
+    file: "repro/sub/d.md",
+    link: "repro/sub",
+  },
   { problem: "no-history", id: "P1-S01", why: "git is not installed" },
   { problem: "shallow", id: "P1-S01" },
   {
@@ -240,10 +269,14 @@ it("each finding's message: what is wrong, what to do, the rule's page", () => {
       PAGE,
     "The decision of `P1-S01`, `repro/d.md`, was committed and then deleted: it is not in HEAD, so the study has no decision its outputs could follow. What to do: restore the decision file as it was decided and commit it — never write a new one after the outputs; if the decision no longer holds, declare the study `exploratory` with the reason." +
       PAGE,
+    "The decision of `P1-S01`, `repro/p`, is a special file, not a file: git tracks only regular files, so no order can be read from it. What to do: name the decision file itself in `mode.decision.file`." +
+      PAGE,
     "The decision of `P1-S01`, `repro/d`, is a directory, not a file: git answers for a directory with the commits of anything under it, so no order can be read from it. What to do: name the decision file itself in `mode.decision.file`." +
       PAGE,
     "The decision of `P1-S01`, `repro/l.md`, is a symbolic link, not a file: git records the link, not the file it points to, so no order can be read from it. What to do: name the decision file itself in `mode.decision.file`." +
       PAGE,
+    "The decision of `P1-S01`, `repro/sub/d.md`, passes through the symbolic link `repro/sub`: git records the link, not the files behind it, so no order can be read from it. What to do: name a decision file that lies in real directories in `mode.decision.file`." +
+      PAGE,
     "`P1-S01` is decided before its run, and git's history is the proof of that order, but git could not answer: git is not installed. What to do: lint the paper inside its git repository, with git installed." +
       PAGE,
     "`P1-S01` is decided before its run, and this clone is shallow: every file's first commit is the clone's first, so the order of decision and outputs cannot be read. What to do: fetch the whole history (`git fetch --unshallow`; in GitHub Actions, `actions/checkout` with `fetch-depth: 0`)." +

package/src/domain/decide-first.ts

@@ -23,7 +23,7 @@ import {
 } from "./study-mode.ts";
 
 /** What a decision path names on disk when it is no file git can vouch for. */
-export type NotAFile = "directory" | "symbolic link";
+export type NotAFile = "directory" | "symbolic link" | "special file";
 
 /** A commit, and its committer date (ISO 8601 with its offset). */
 export interface CommitAt {
@@ -54,6 +54,8 @@ export interface FirstCommit extends CommitAt {
  */
 export type OrderFacts =
   | { readonly kind: "not-a-file"; readonly what: NotAFile }
+  /** The decision's path passes through a symbolic link above the file (`link`: the first, relative to the paper). */
+  | { readonly kind: "linked"; readonly link: string }
   | { readonly kind: "unknown"; readonly why: string }
   /** A shallow clone: every file's first commit is the clone's first, so no order can be read. */
   | { readonly kind: "shallow" }
@@ -97,6 +99,12 @@ export type OrderFinding =
       readonly file: string;
       readonly what: NotAFile;
     }
+  | {
+      readonly problem: "decision-linked";
+      readonly id: string;
+      readonly file: string;
+      readonly link: string;
+    }
   | {
       readonly problem: "no-history";
       readonly id: string;
@@ -188,6 +196,10 @@ const historyFindings = (s: DecideFirstStudy): readonly OrderFinding[] => {
       return [
         { problem: "decision-not-file", id: s.id, file, what: s.facts.what },
       ];
+    case "linked":
+      return [
+        { problem: "decision-linked", id: s.id, file, link: s.facts.link },
+      ];
     case "unknown":
       return [{ problem: "no-history", id: s.id, why: s.facts.why }];
     case "shallow":
@@ -212,6 +224,7 @@ const NOT_A_FILE: Readonly<Record<NotAFile, string>> = {
   directory:
     "git answers for a directory with the commits of anything under it",
   "symbolic link": "git records the link, not the file it points to",
+  "special file": "git tracks only regular files",
 };
 
 const short = (c: CommitAt): string => `${c.commit.slice(0, 12)} (${c.date})`;
@@ -225,6 +238,8 @@ const HEADS: {
     `The decision of \`${f.id}\`, \`${f.file}\`, was committed and then deleted: it is not in HEAD, so the study has no decision its outputs could follow. What to do: restore the decision file as it was decided and commit it — never write a new one after the outputs; if the decision no longer holds, declare the study \`exploratory\` with the reason.`,
   "decision-not-file": (f) =>
     `The decision of \`${f.id}\`, \`${f.file}\`, is a ${f.what}, not a file: ${NOT_A_FILE[f.what]}, so no order can be read from it. What to do: name the decision file itself in \`mode.decision.file\`.`,
+  "decision-linked": (f) =>
+    `The decision of \`${f.id}\`, \`${f.file}\`, passes through the symbolic link \`${f.link}\`: git records the link, not the files behind it, so no order can be read from it. What to do: name a decision file that lies in real directories in \`mode.decision.file\`.`,
   "no-history": (f) =>
     `\`${f.id}\` is decided before its run, and git's history is the proof of that order, but git could not answer: ${f.why}. What to do: lint the paper inside its git repository, with git installed.`,
   shallow: (f) =>

package/src/domain/index-columns.test.ts

@@ -82,11 +82,11 @@ const NINE_AT: IndexInput = {
   ]),
   history: new Map([
     [
-      "P1-S01",
+      "P1-S01-hint/plan.json",
       { kind: "read", decision: D, decisionDeleted: false, firstOutput: A },
     ],
     [
-      "P1-S02",
+      "P1-S02-s/plan.json",
       {
         kind: "read",
         decision: null,
@@ -94,7 +94,7 @@ const NINE_AT: IndexInput = {
         firstOutput: null,
       },
     ],
-    ["P1-S04", { kind: "unread", why: "shallow clone" }],
+    ["P1-S04-s/plan.json", { kind: "unread", why: "shallow clone" }],
   ]),
 };
 
@@ -124,7 +124,7 @@ describe("the mode columns of the index", () => {
       plans,
       history: new Map([
         [
-          "P1-S01",
+          "P1-S01-s/plan.json",
           {
             kind: "read",
             decision: D,
@@ -151,6 +151,49 @@ describe("the mode columns of the index", () => {
   });
 });
 
+it("two rows of one id each show their own history, keyed by folder and plan", () => {
+  const r: StudyRegistry = {
+    prefix: "P1",
+    studies: [row(1, { folder: "P1-S01-a" }), row(1, { folder: "P1-S01-b" })],
+  };
+  const at: IndexInput = {
+    plans: new Map([
+      ["P1-S01-a/plan.json", plan(DECIDED)],
+      ["P1-S01-b/plan.json", plan(DECIDED)],
+    ]),
+    history: new Map([
+      [
+        "P1-S01-a/plan.json",
+        { kind: "read", decision: D, decisionDeleted: false, firstOutput: A },
+      ],
+      [
+        "P1-S01-b/plan.json",
+        {
+          kind: "read",
+          decision: null,
+          decisionDeleted: false,
+          firstOutput: null,
+        },
+      ],
+    ]),
+  };
+  // Guards: keyed by id, the second row's history was shown on both rows (the later one wins).
+  expect(
+    studyIndex(r, at)
+      .split("\n")
+      .slice(2)
+      .map((l) =>
+        l
+          .split("|")
+          .slice(6, 9)
+          .map((c) => c.trim()),
+      ),
+  ).toEqual([
+    ["decide_before_run", "dddddddddddd 2026-10-14", "aaaaaaaaaaaa 2026-10-16"],
+    ["decide_before_run", "not committed", "none"],
+  ]);
+});
+
 it("a decision committed and since deleted shows its commit, and that it is gone", () => {
   // Guards: the Methods sentence must not cite a decision that no longer stands.
   expect(
@@ -181,6 +224,7 @@ describe("indexHistory", () => {
       indexHistory(study({ kind: "unknown", why: "not a repository" })),
       indexHistory(study({ kind: "shallow" })),
       indexHistory(study({ kind: "not-a-file", what: "directory" })),
+      indexHistory(study({ kind: "linked", link: "repro/sub" })),
       indexHistory(
         study({
           kind: "read",
@@ -204,6 +248,7 @@ describe("indexHistory", () => {
       { kind: "unread", why: "git could not answer" },
       { kind: "unread", why: "shallow clone" },
       { kind: "unread", why: "the decision is a directory" },
+      { kind: "unread", why: "the decision is behind a symbolic link" },
       { kind: "read", decision: D, decisionDeleted: false, firstOutput: A },
       {
         kind: "read",

package/src/domain/index-columns.ts

@@ -85,6 +85,8 @@ export const indexHistory = (s: DecideFirstStudy): IndexHistory => {
   switch (s.facts.kind) {
     case "not-a-file":
       return { kind: "unread", why: `the decision is a ${s.facts.what}` };
+    case "linked":
+      return { kind: "unread", why: "the decision is behind a symbolic link" };
     case "unknown":
       return { kind: "unread", why: "git could not answer" };
     case "shallow":

package/src/domain/study-measurements.test.ts

@@ -22,6 +22,7 @@ import {
   type StudyPlan,
   type StudyRegistry,
   type IndexInput,
+  folderKey,
 } from "./study-registry.ts";
 
 /** No plan and no history: the index with every mode column `—`. */
@@ -110,10 +111,10 @@ const input = (
   folders: r.studies.map((s) => s.folder),
   registry: { kind: "read", registry: r },
   readme: withIndex("# Reproduction index\n", r, NO_FACTS),
-  existingResults: new Set(),
+  results: new Map(),
   plans: new Map(
     r.studies.flatMap((s) =>
-      s.plan === undefined ? [] : [[`${s.folder}/${s.plan}`, read(PLAN)]],
+      s.plan === undefined ? [] : [[folderKey(s.folder, s.plan), read(PLAN)]],
     ),
   ),
   ...over,
@@ -385,7 +386,10 @@ describe("plans — the parser decides ready or draft", () => {
     });
     const plans = new Map([[`P1-S01-census/${PLAN_FILE}`, read(PLAN)]]);
     expect(
-      findings(r, { plans, existingResults: new Set(["P1-S01-census/r.tsv"]) }),
+      findings(r, {
+        plans,
+        results: new Map([["P1-S01-census/r.tsv", { kind: "file" as const }]]),
+      }),
     ).toEqual([]);
   });
 

package/src/domain/study-registry.test.ts

@@ -19,6 +19,7 @@ import {
   studyIndex,
   studyMessage,
   studyReadme,
+  studyById,
   studySlug,
   withIndex,
   type RegistryState,
@@ -61,7 +62,7 @@ const input = (
   folders: r.studies.map((s) => s.folder),
   registry: read(r),
   readme: withIndex("# Reproduction index\n", r, NO_FACTS),
-  existingResults: new Set(),
+  results: new Map(),
   plans: new Map(),
   ...over,
 });
@@ -88,7 +89,9 @@ describe("judgeStudies — silent", () => {
     expect(
       judgeStudies(
         input(r, {
-          existingResults: new Set(["P1-S02-ablation/out/results.tsv"]),
+          results: new Map([
+            ["P1-S02-ablation/out/results.tsv", { kind: "file" as const }],
+          ]),
         }),
       ),
     ).toEqual([]);
@@ -100,7 +103,7 @@ describe("judgeStudies — silent", () => {
         folders: [],
         registry: { kind: "absent" },
         readme: null,
-        existingResults: new Set(),
+        results: new Map(),
         plans: new Map(),
       }),
     ).toEqual([]);
@@ -129,7 +132,7 @@ describe("judgeStudies — the registry itself", () => {
         folders: ["a-2026-10-01", "b-2026-10-02"],
         registry: { kind: "absent" },
         readme: null,
-        existingResults: new Set(),
+        results: new Map(),
         plans: new Map(),
       }),
     ).toEqual([
@@ -143,7 +146,7 @@ describe("judgeStudies — the registry itself", () => {
         folders: ["a-2026-10-01"],
         registry: { kind: "unreadable", why: "prefix: required" },
         readme: null,
-        existingResults: new Set(),
+        results: new Map(),
         plans: new Map(),
       }),
     ).toEqual([{ problem: "unreadable", why: "prefix: required" }]);
@@ -259,7 +262,11 @@ describe("judgeStudies — status", () => {
     const r = reg(study({ status: "running", result_file: "r.tsv" }));
     expect(
       judgeStudies(
-        input(r, { existingResults: new Set(["P1-S01-baseline/r.tsv"]) }),
+        input(r, {
+          results: new Map([
+            ["P1-S01-baseline/r.tsv", { kind: "file" as const }],
+          ]),
+        }),
       ),
     ).toEqual([]);
   });
@@ -671,3 +678,24 @@ describe("studyReadme", () => {
     );
   });
 });
+
+describe("studyById — the one way to address a study by its id", () => {
+  const a = study({ id: "P1-S01", folder: "P1-S01-a" });
+  const b = study({ id: "P1-S01", folder: "P1-S01-b" });
+  const c = study({ id: "P1-S02", folder: "P1-S02-c" });
+
+  it("exactly one row: that row; no row: none; two or more: all of them, in registry order", () => {
+    // Guards: a caller can take a row only from `one`, never "the first" of an ambiguous id.
+    expect([
+      studyById([a, c], "P1-S01"),
+      studyById([a, c], "P1-S09"),
+      studyById([], "P1-S01"),
+      studyById([a, c, b], "P1-S01"),
+    ]).toEqual([
+      { kind: "one", row: a },
+      { kind: "none" },
+      { kind: "none" },
+      { kind: "ambiguous", rows: [a, b] },
+    ]);
+  });
+});