paperlint 10.2.0 → 10.4.0

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

@@ -0,0 +1,216 @@
+/**
+ * The index's mode columns (`src/domain/index-columns.ts`) and the table that carries them
+ * (`studyIndex`, `indexInSync`, `indexCurrent` in `src/domain/study-registry.ts`): the mode from the
+ * plan, the decision's and the first output's commits from git's history, and the two git columns
+ * left out of what the lint compares.
+ */
+import { describe, expect, it } from "vitest";
+import type { DecideFirstStudy } from "./decide-first.ts";
+import { decisionCell, indexHistory } from "./index-columns.ts";
+import type { DecideFirst } from "./study-mode.ts";
+import {
+  indexCurrent,
+  indexInSync,
+  studyIndex,
+  withIndex,
+  type IndexInput,
+  type PlanState,
+  type Study,
+  type StudyPlan,
+  type StudyRegistry,
+} from "./study-registry.ts";
+
+const D = { commit: "d".repeat(40), date: "2026-10-14T09:12:00+05:00" };
+const A = { commit: "a".repeat(40), date: "2026-10-16T11:00:00+05:00" };
+
+const DECIDED: DecideFirst = {
+  kind: "decide_before_run",
+  outputs: ["RESULTS.md"],
+  decision: { file: "repro/P1-S01-hint/decision.md", note: "exclusions" },
+};
+
+const plan = (mode: StudyPlan["mode"]): PlanState => ({
+  kind: "ready",
+  plan: {
+    question: "q?",
+    population: { source: "s", draw: { kind: "all", method: "census" } },
+    arms: [],
+    primary_outcome: "o",
+    author_check: null,
+    mode,
+  },
+});
+
+const row = (n: number, over: Partial<Study> = {}): Study => ({
+  id: `P1-S0${String(n)}`,
+  folder: `P1-S0${String(n)}-s`,
+  title: `S${String(n)}`,
+  question: "q?",
+  kind: "measurement",
+  status: "running",
+  date: "2026-10-15",
+  in_paper: "no",
+  plan: "plan.json",
+  ...over,
+});
+
+/** Nine studies, one per state a mode cell can be in. */
+const NINE: StudyRegistry = {
+  prefix: "P1",
+  studies: [
+    row(1, { folder: "P1-S01-hint" }),
+    row(2),
+    row(3),
+    row(4),
+    row(5),
+    row(6, { kind: "spike", plan: undefined }),
+    row(7, { plan: "../plan.json" }),
+    row(8),
+    row(9),
+  ],
+};
+/** Their plans and histories. */
+const NINE_AT: IndexInput = {
+  plans: new Map<string, PlanState>([
+    ["P1-S01-hint/plan.json", plan(DECIDED)],
+    ["P1-S02-s/plan.json", plan(DECIDED)],
+    ["P1-S03-s/plan.json", plan({ kind: "exploratory", reason: "a | look" })],
+    ["P1-S04-s/plan.json", plan(DECIDED)],
+    ["P1-S05-s/plan.json", plan(DECIDED)],
+    ["P1-S08-s/plan.json", { kind: "unreadable", why: "not JSON" }],
+    ["P1-S09-s/plan.json", plan(undefined)],
+  ]),
+  history: new Map([
+    [
+      "P1-S01",
+      { kind: "read", decision: D, decisionDeleted: false, firstOutput: A },
+    ],
+    [
+      "P1-S02",
+      {
+        kind: "read",
+        decision: null,
+        decisionDeleted: false,
+        firstOutput: null,
+      },
+    ],
+    ["P1-S04", { kind: "unread", why: "shallow clone" }],
+  ]),
+};
+
+describe("the mode columns of the index", () => {
+  it("say each study's mode and, for one decided before its run, its two commits", () => {
+    // Guards: the sample row a reader and the review skills read — decided before the run, the
+    // decision's first commit and date, the first output's — and every other state its own words.
+    expect(studyIndex(NINE, NINE_AT).split("\n").slice(2)).toEqual([
+      "| P1-S01 | S1    | running | —      | no       | decide_before_run      | dddddddddddd 2026-10-14 | aaaaaaaaaaaa 2026-10-16 | [P1-S01-hint/](P1-S01-hint/) |",
+      "| P1-S02 | S2    | running | —      | no       | decide_before_run      | not committed           | none                    | [P1-S02-s/](P1-S02-s/)       |",
+      "| P1-S03 | S3    | running | —      | no       | exploratory: a \\| look | —                       | —                       | [P1-S03-s/](P1-S03-s/)       |",
+      "| P1-S04 | S4    | running | —      | no       | decide_before_run      | unknown (shallow clone) | unknown (shallow clone) | [P1-S04-s/](P1-S04-s/)       |",
+      "| P1-S05 | S5    | running | —      | no       | decide_before_run      | not read                | not read                | [P1-S05-s/](P1-S05-s/)       |",
+      "| P1-S06 | S6    | running | —      | no       | —                      | —                       | —                       | [P1-S06-s/](P1-S06-s/)       |",
+      "| P1-S07 | S7    | running | —      | no       | —                      | —                       | —                       | [P1-S07-s/](P1-S07-s/)       |",
+      "| P1-S08 | S8    | running | —      | no       | —                      | —                       | —                       | [P1-S08-s/](P1-S08-s/)       |",
+      "| P1-S09 | S9    | running | —      | no       | —                      | —                       | —                       | [P1-S09-s/](P1-S09-s/)       |",
+    ]);
+  });
+
+  it("the lint compares the mode, never the two commits; `studies index` rewrites on either", () => {
+    const r: StudyRegistry = { prefix: "P1", studies: [row(1)] };
+    const plans = new Map([["P1-S01-s/plan.json", plan(DECIDED)]]);
+    const was: IndexInput = { plans, history: new Map() };
+    const readme = withIndex("# index\n", r, was);
+    const committed: IndexInput = {
+      plans,
+      history: new Map([
+        [
+          "P1-S01",
+          {
+            kind: "read",
+            decision: D,
+            decisionDeleted: false,
+            firstOutput: null,
+          },
+        ],
+      ]),
+    };
+    const explored: IndexInput = {
+      plans: new Map([
+        ["P1-S01-s/plan.json", plan({ kind: "exploratory", reason: "r" })],
+      ]),
+      history: new Map(),
+    };
+    // Guards: a squash merge renames the commits, so the lint cannot hold them; the command can.
+    expect([
+      indexInSync(readme, r, committed),
+      indexCurrent(readme, r, committed),
+      indexInSync(readme, r, explored),
+      indexCurrent(readme, r, was),
+      indexCurrent(null, r, was),
+    ]).toEqual([true, false, false, true, false]);
+  });
+});
+
+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(
+    decisionCell({
+      mode: DECIDED,
+      history: {
+        kind: "read",
+        decision: D,
+        decisionDeleted: true,
+        firstOutput: null,
+      },
+    }),
+  ).toBe("dddddddddddd 2026-10-14, deleted since");
+});
+
+describe("indexHistory", () => {
+  const study = (facts: DecideFirstStudy["facts"]): DecideFirstStudy => ({
+    id: "P1-S01",
+    folder: "P1-S01-hint",
+    plan: "plan.json",
+    mode: DECIDED,
+    tree: [],
+    facts,
+  });
+
+  it("is the decision's first commit and the oldest output's, or what kept git from saying", () => {
+    expect([
+      indexHistory(study({ kind: "unknown", why: "not a repository" })),
+      indexHistory(study({ kind: "shallow" })),
+      indexHistory(study({ kind: "not-a-file", what: "directory" })),
+      indexHistory(
+        study({
+          kind: "read",
+          decision: D,
+          decisionDeleted: false,
+          files: [
+            { path: "decision.md", ...D, order: "same" },
+            { path: "RESULTS.md", ...A, order: "after" },
+          ],
+        }),
+      ),
+      indexHistory(
+        study({
+          kind: "read",
+          decision: null,
+          decisionDeleted: false,
+          files: [],
+        }),
+      ),
+    ]).toEqual([
+      { kind: "unread", why: "git could not answer" },
+      { kind: "unread", why: "shallow clone" },
+      { kind: "unread", why: "the decision is a directory" },
+      { kind: "read", decision: D, decisionDeleted: false, firstOutput: A },
+      {
+        kind: "read",
+        decision: null,
+        decisionDeleted: false,
+        firstOutput: null,
+      },
+    ]);
+  });
+});

package/src/domain/index-columns.ts

@@ -0,0 +1,105 @@
+/**
+ * THE MODE COLUMNS OF THE INDEX — three columns of `repro/README.md`'s study index beyond the row:
+ * the study's mode, as its plan declares it, and for a study decided before its run the commit that
+ * first recorded its decision and the commit that first recorded an output (docs/design/study-modes.md).
+ *
+ * The mode comes from the plan, which is in the tree, so `repro/study-registered` compares it. The
+ * two commits come from git's history as `paperlint studies index` read it when it ran: a squash merge
+ * or a rebase gives the same files new commits, and a shallow CI clone has none to read, so the lint
+ * never compares those two columns. `repro/outputs-before-decision` judges the order itself. Pure.
+ */
+import {
+  outputCommits,
+  type CommitAt,
+  type DecideFirstStudy,
+} from "./decide-first.ts";
+import type { StudyMode } from "./study-mode.ts";
+
+/** What git's history says of a decide-first study's decision and outputs. */
+export type IndexHistory =
+  /** No order could be read: why, in a few words (`shallow clone`). */
+  | { readonly kind: "unread"; readonly why: string }
+  | {
+      readonly kind: "read";
+      /** The decision file's first commit; null: never committed. */
+      readonly decision: CommitAt | null;
+      /** The decision was committed, then deleted: it is not in HEAD. */
+      readonly decisionDeleted: boolean;
+      /** The first commit of the oldest output; null: no output was ever committed. */
+      readonly firstOutput: CommitAt | null;
+    };
+
+/** What the index shows of a study beyond its row. */
+export interface IndexFacts {
+  /** The mode its plan declares; null when its plan declares none, or there is no plan to read. */
+  readonly mode: StudyMode | null;
+  /** For a decide-first study, its history; null when it was not asked (the lint does not ask). */
+  readonly history: IndexHistory | null;
+}
+
+/** The cell of a column that does not apply to a study. */
+export const NOT_APPLICABLE = "—";
+
+/** A commit as a cell: its first twelve characters, and its date. */
+const commitCell = (c: CommitAt): string =>
+  `${c.commit.slice(0, 12)} ${c.date.slice(0, 10)}`;
+
+/** The mode cell: `decide_before_run`, `exploratory: <reason>`, or `—`. */
+export const modeCell = (f: IndexFacts): string => {
+  if (f.mode === null) return NOT_APPLICABLE;
+  return f.mode.kind === "exploratory"
+    ? `exploratory: ${f.mode.reason}`
+    : f.mode.kind;
+};
+
+/** A history cell of a decide-first study: the text `pick` makes of it, `absent` when it makes none. */
+const historyCell =
+  (
+    pick: (h: IndexHistory & { readonly kind: "read" }) => string | null,
+    absent: string,
+  ) =>
+  (f: IndexFacts): string => {
+    if (f.mode?.kind !== "decide_before_run") return NOT_APPLICABLE;
+    if (f.history === null) return "not read";
+    if (f.history.kind === "unread") return `unknown (${f.history.why})`;
+    return pick(f.history) ?? absent;
+  };
+
+/** The decision cell: its first commit and date (`, deleted since` when it is not in HEAD), or `not committed`. */
+export const decisionCell = historyCell(
+  (h) =>
+    h.decision === null
+      ? null
+      : `${commitCell(h.decision)}${h.decisionDeleted ? ", deleted since" : ""}`,
+  "not committed",
+);
+
+/** The first-output cell: the commit and date of the first output, or `none`. */
+export const firstOutputCell = historyCell(
+  (h) => (h.firstOutput === null ? null : commitCell(h.firstOutput)),
+  "none",
+);
+
+/** The history the index shows of a decide-first study, from the facts git gave. */
+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 "unknown":
+      return { kind: "unread", why: "git could not answer" };
+    case "shallow":
+      return { kind: "unread", why: "shallow clone" };
+    case "read": {
+      const [first] = outputCommits(s, s.facts.files);
+      return {
+        kind: "read",
+        decision: s.facts.decision,
+        decisionDeleted: s.facts.decisionDeleted,
+        firstOutput:
+          first === undefined
+            ? null
+            : { commit: first.commit, date: first.date },
+      };
+    }
+  }
+};