paperlint 12.0.0 → 13.0.0

package/src/domain/versions.test.ts

@@ -0,0 +1,564 @@
+/** The frozen versions by convention: names, the lock, the layout's findings, each version's state. */
+import { describe, expect, it } from "vitest";
+import { currentCycle, parseCycles, type Cycle } from "./cycle.ts";
+import { err, ok } from "./result.ts";
+import {
+  driftBase,
+  frozenName,
+  judgeVersions,
+  keyParts,
+  derivesFrom,
+  lineage,
+  lineDrift,
+  lockText,
+  parseLock,
+  relock,
+  stateOf,
+  unfrozenSubmissions,
+  versionRows,
+  versionTable,
+  type Entry,
+  type LayoutInput,
+  type Lock,
+} from "./versions.ts";
+
+const SHA = "a".repeat(64);
+const OTHER = "b".repeat(64);
+
+/** Cycles parsed as paperlint.json holds them: `rejected` alpha, then `open` beta with a submission. */
+function cycles(...raw: readonly object[]): readonly Cycle[] {
+  const r = parseCycles(raw);
+  if (!r.ok || r.value === null) throw new Error("bad fixture");
+  return r.value;
+}
+const ALPHA = {
+  id: "alpha-2026",
+  venue: { kind: "preset", extends: "paperlint:aisec" },
+  opened: "2026-06-01",
+  submission: { id: 3 },
+  outcome: {
+    kind: "rejected",
+    date: "2026-09-01",
+    evidence: "reviews/a.md",
+  },
+};
+const BETA = {
+  id: "beta-2027",
+  venue: { kind: "named", name: "Beta 2027", url: "https://beta.example" },
+  opened: "2026-09-09",
+  submission: { id: 7 },
+};
+const TWO = cycles(ALPHA, BETA);
+
+const file = (name: string): Entry => ({ name, kind: "file" });
+const dir = (name: string): Entry => ({ name, kind: "dir" });
+
+const entry = (bytes = 10, sha256 = SHA, frozen = "2026-10-23T16:58:01.000Z") =>
+  ({ kind: "file", bytes, sha256, frozen }) as const;
+
+/** A clean folder: both cycles frozen as submitted, every file locked as it stands. */
+const CLEAN_LOCK: Lock = {
+  "alpha-2026/submitted.pdf": entry(),
+  "alpha-2026/submitted.tex": entry(),
+  "beta-2027/submitted.pdf": entry(),
+  "beta-2027/submitted.tex": entry(),
+};
+const layout = (o: Partial<LayoutInput> = {}): LayoutInput => ({
+  cycles: TWO,
+  root: [dir("alpha-2026"), dir("beta-2027"), file("lock.json")],
+  inFolder: () => [file("submitted.pdf"), file("submitted.tex")],
+  lock: ok(CLEAN_LOCK),
+  factsOf: () => ({ bytes: 10, sha256: SHA }),
+  ...o,
+});
+
+describe("names", () => {
+  it("a stage and pdf or tex is a frozen name; anything else is not", () => {
+    expect(frozenName("camera-ready.tex")).toStrictEqual({
+      stage: "camera-ready",
+      ext: "tex",
+    });
+    expect(frozenName("draft.pdf")).toBeNull();
+    expect(frozenName("submitted.docx")).toBeNull();
+    expect(frozenName("2026-07-22-submitted.pdf")).toBeNull();
+  });
+
+  it("a lock key is <cycle>/<stage>.<ext>", () => {
+    expect(keyParts("beta-2027/arxiv.pdf")).toStrictEqual({
+      cycle: "beta-2027",
+      name: { stage: "arxiv", ext: "pdf" },
+    });
+    expect(keyParts("beta-2027/notes.md")).toBeNull();
+    expect(keyParts("submitted.pdf")).toBeNull();
+    // The cycle part by the rule parseCycles holds an id to: one folder name, nothing else.
+    expect(keyParts("conf/2026/submitted.pdf")).toBeNull();
+    expect(keyParts("../submitted.pdf")).toBeNull();
+    expect(keyParts("Conf-2026/submitted.pdf")).toBeNull();
+  });
+});
+
+const json = (files: object) => ({ lockfileVersion: 1, files });
+/** An entry as the file holds it. */
+const written = { bytes: 10, sha256: SHA, frozen: "2026-07-22" };
+
+describe("the lock", () => {
+  it("parses what paperlint writes, and writes it back the same, keys sorted", () => {
+    const lock: Lock = {
+      "beta-2027/submitted.pdf": entry(5, SHA, "2026-10-23T16:58:01.000Z"),
+      "alpha-2026/submitted.tex": { kind: "lost", frozen: "2026-07-22" },
+      "alpha-2026/arxiv.tex": { kind: "lost", frozen: null },
+    };
+    const text = lockText(lock);
+    expect(parseLock(JSON.parse(text))).toStrictEqual(ok(lock));
+    expect(JSON.parse(text)).toStrictEqual({
+      lockfileVersion: 1,
+      note: "generated by paperlint — do not edit: `paperlint submission update --save` and `paperlint versions lock` write it",
+      files: {
+        "alpha-2026/arxiv.tex": { sourceLost: true },
+        "alpha-2026/submitted.tex": { sourceLost: true, frozen: "2026-07-22" },
+        "beta-2027/submitted.pdf": {
+          bytes: 5,
+          sha256: SHA,
+          frozen: "2026-10-23T16:58:01.000Z",
+        },
+      },
+    });
+    expect(text.endsWith("}\n")).toBe(true);
+  });
+});
+
+describe("the lock, refused", () => {
+  it("refuses what it does not write, naming the entry and the key", () => {
+    expect(parseLock({ files: {} })).toStrictEqual(
+      err('not a lock this paperlint writes ("lockfileVersion": 1)'),
+    );
+    expect(parseLock([])).toStrictEqual(
+      err('not a lock this paperlint writes ("lockfileVersion": 1)'),
+    );
+    expect(parseLock({ lockfileVersion: 1 })).toStrictEqual(
+      err('"files" must be an object'),
+    );
+    const at = '"files"["b/submitted.pdf"]';
+    const cases: readonly (readonly [object, string])[] = [
+      [
+        { "b/x.pdf": {} },
+        '"files"["b/x.pdf"]: a key is <cycle>/<stage>.pdf or .tex',
+      ],
+      [{ "b/submitted.pdf": 1 }, `${at} must be an object`],
+      [
+        { "b/submitted.pdf": { ...written, size: 1 } },
+        `${at}: unknown key "size"`,
+      ],
+      [
+        { "b/submitted.pdf": { sourceLost: true } },
+        `${at}: only a source (.tex) can be recorded as lost`,
+      ],
+      [
+        { "b/submitted.tex": { sourceLost: true, frozen: "yesterday" } },
+        '"files"["b/submitted.tex"]: "frozen" must be a date or an instant',
+      ],
+      [
+        { "b/submitted.pdf": { ...written, bytes: -1 } },
+        `${at}: "bytes" must be a whole number`,
+      ],
+      [
+        { "b/submitted.pdf": { ...written, bytes: "1" } },
+        `${at}: "bytes" must be a whole number`,
+      ],
+      [
+        { "b/submitted.pdf": { ...written, sha256: "AB" } },
+        `${at}: "sha256" must be 64 lowercase hex digits`,
+      ],
+      [
+        { "b/submitted.pdf": { bytes: 1, sha256: SHA } },
+        `${at}: "frozen" must be a date or an instant`,
+      ],
+    ];
+    cases.forEach(([files, why]) => {
+      expect(parseLock(json(files))).toStrictEqual(err(why));
+    });
+    // The first problem stops the read.
+    expect(
+      parseLock(json({ "b/x.pdf": {}, "b/submitted.pdf": 1 })),
+    ).toStrictEqual(
+      err('"files"["b/x.pdf"]: a key is <cycle>/<stage>.pdf or .tex'),
+    );
+  });
+});
+
+describe("versions/layout", () => {
+  it("a folder per cycle, a file per stage, all locked as they stand: silent", () => {
+    expect(judgeVersions(layout())).toStrictEqual([]);
+    // Dot files are the system's (`.gitkeep`, `.DS_Store`), not the paper's.
+    expect(
+      judgeVersions(
+        layout({
+          root: [...layout().root, file(".gitkeep")],
+          inFolder: () => [
+            file("submitted.pdf"),
+            file("submitted.tex"),
+            file(".DS_Store"),
+          ],
+        }),
+      ),
+    ).toStrictEqual([]);
+    // Nothing frozen and no lock: nothing to say.
+    expect(
+      judgeVersions(layout({ root: [], lock: null, inFolder: () => [] })),
+    ).toStrictEqual([]);
+  });
+});
+
+describe("versions/layout, entries outside it", () => {
+  it("an entry outside the convention: a dated file says how to migrate it, the rest where things go", () => {
+    const found = judgeVersions(
+      layout({
+        root: [
+          ...layout().root,
+          file("2026-07-22-submitted.pdf"),
+          file("notes.md"),
+          dir("old"),
+        ],
+        inFolder: (name) =>
+          name === "beta-2027"
+            ? [
+                file("submitted.pdf"),
+                file("submitted.tex"),
+                file("final.pdf"),
+                dir("figs"),
+              ]
+            : [file("submitted.pdf"), file("submitted.tex")],
+      }),
+    );
+    expect(found.map((f) => [f.messageId, f.data])).toStrictEqual([
+      [
+        "stray",
+        {
+          path: "2026-07-22-submitted.pdf",
+          hint: "a frozen version in the layout before folders per attempt: `npx paperlint versions migrate <paper>` moves it into versions/<cycle>/",
+        },
+      ],
+      [
+        "stray",
+        {
+          path: "notes.md",
+          hint: "versions/ holds lock.json and one folder per cycle, each with <stage>.pdf and <stage>.tex (submitted, camera-ready, arxiv) — anything else goes to extra/",
+        },
+      ],
+      ["unknownCycle", { folder: "old", known: "alpha-2026 · beta-2027" }],
+      ["stray", expect.objectContaining({ path: "beta-2027/final.pdf" })],
+      ["stray", expect.objectContaining({ path: "beta-2027/figs" })],
+    ]);
+  });
+
+  it("a folder when the paper declares no cycle names none", () => {
+    expect(
+      judgeVersions(layout({ cycles: [], lock: ok({}) })).map((f) => f.data),
+    ).toStrictEqual([
+      { folder: "alpha-2026", known: "(none)" },
+      { folder: "beta-2027", known: "(none)" },
+    ]);
+  });
+});
+
+describe("versions/layout, the files in a folder", () => {
+  it("a PDF without its source, unless the lock records the source lost", () => {
+    const onlyPdf = () => [file("submitted.pdf")];
+    const lock: Lock = {
+      "alpha-2026/submitted.pdf": entry(),
+      "alpha-2026/submitted.tex": { kind: "lost", frozen: "2026-07-22" },
+      "beta-2027/submitted.pdf": entry(),
+    };
+    expect(
+      judgeVersions(layout({ inFolder: onlyPdf, lock: ok(lock) })),
+    ).toStrictEqual([
+      {
+        messageId: "noSource",
+        data: {
+          pdf: "beta-2027/submitted.pdf",
+          tex: "beta-2027/submitted.tex",
+        },
+      },
+    ]);
+  });
+
+  it("a version sent from a cycle still porting; an arXiv copy or a source is not a send", () => {
+    const porting = cycles({ ...BETA, phase: "porting" });
+    const found = judgeVersions(
+      layout({
+        cycles: porting,
+        root: [dir("beta-2027"), file("lock.json")],
+        inFolder: () => [
+          file("submitted.pdf"),
+          file("submitted.tex"),
+          file("arxiv.pdf"),
+          file("arxiv.tex"),
+        ],
+        lock: ok({
+          "beta-2027/submitted.pdf": entry(),
+          "beta-2027/submitted.tex": entry(),
+          "beta-2027/arxiv.pdf": entry(),
+          "beta-2027/arxiv.tex": entry(),
+        }),
+      }),
+    );
+    expect(found).toStrictEqual([
+      {
+        messageId: "porting",
+        data: { file: "beta-2027/submitted.pdf", id: "beta-2027" },
+      },
+    ]);
+  });
+});
+
+describe("versions/layout, the lock", () => {
+  it("frozen files and no lock, or a lock that does not parse: one finding each", () => {
+    expect(judgeVersions(layout({ lock: null }))).toStrictEqual([
+      { messageId: "noLock", data: {} },
+    ]);
+    expect(judgeVersions(layout({ lock: err("not JSON") }))).toStrictEqual([
+      { messageId: "badLock", data: { why: "not JSON" } },
+    ]);
+  });
+
+  it("each file against its lock entry: missing, recorded lost, other bytes, other digest; an entry with no file", () => {
+    const lock: Lock = {
+      "alpha-2026/submitted.pdf": entry(10, OTHER, "2026-07-22"),
+      "alpha-2026/submitted.tex": { kind: "lost", frozen: null },
+      "beta-2027/submitted.pdf": entry(11),
+      "beta-2027/camera-ready.pdf": entry(),
+    };
+    expect(judgeVersions(layout({ lock: ok(lock) }))).toStrictEqual([
+      {
+        messageId: "changed",
+        data: {
+          file: "alpha-2026/submitted.pdf",
+          want: "10",
+          got: "10",
+          frozen: "2026-07-22",
+        },
+      },
+      { messageId: "notLocked", data: { file: "alpha-2026/submitted.tex" } },
+      {
+        messageId: "changed",
+        data: {
+          file: "beta-2027/submitted.pdf",
+          want: "11",
+          got: "10",
+          frozen: "2026-10-23T16:58:01.000Z",
+        },
+      },
+      { messageId: "notLocked", data: { file: "beta-2027/submitted.tex" } },
+      { messageId: "lockedGone", data: { file: "beta-2027/camera-ready.pdf" } },
+    ]);
+  });
+});
+
+describe("cycle/submitted-frozen", () => {
+  it("a cycle with a submission and no submitted.pdf; one without a submission owes nothing", () => {
+    const has = (k: string) => k === "alpha-2026/submitted.pdf";
+    expect(unfrozenSubmissions(TWO, has)).toStrictEqual([
+      {
+        messageId: "unfrozen",
+        data: {
+          id: "beta-2027",
+          submission: "7",
+          pdf: "beta-2027/submitted.pdf",
+        },
+      },
+    ]);
+    expect(unfrozenSubmissions(TWO, () => true)).toStrictEqual([]);
+    expect(
+      unfrozenSubmissions(cycles({ ...BETA, submission: null }), () => false),
+    ).toStrictEqual([]);
+  });
+});
+
+describe("the draft against a frozen source", () => {
+  it("counts the lines added and removed, as a line diff does", () => {
+    expect(lineDrift("a\nb\nc\n", "a\nB\nc\nd\n")).toStrictEqual({
+      added: 2,
+      removed: 1,
+    });
+    expect(lineDrift("a\n", "a\n")).toStrictEqual({ added: 0, removed: 0 });
+  });
+
+  it("a later version's lineage: the accepted lines it keeps; half kept still derives, less does not", () => {
+    expect(lineage("a\nb\nc\nd\n", "a\nB\nc\nd\ne\n")).toStrictEqual({
+      kept: 3,
+      total: 4,
+    });
+    expect(derivesFrom(lineage("a\nb\nc\nd\n", "a\nb\nX\nY\n"))).toBe(true);
+    expect(derivesFrom(lineage("a\nb\nc\nd\n", "a\nX\nY\nZ\n"))).toBe(false);
+  });
+
+  it("the base: the open cycle's submitted source; once accepted, the newest of its sources; none between venues", () => {
+    const current = (raw: readonly object[]) => {
+      const c = currentCycle(cycles(...raw));
+      if (!c.ok) throw new Error("bad fixture");
+      return c.value;
+    };
+    expect(driftBase(current([ALPHA, BETA]), () => false)?.key).toBe(
+      "beta-2027/submitted.tex",
+    );
+    const accepted = {
+      ...BETA,
+      outcome: { kind: "accepted", date: "2026-12-01", evidence: "m.eml" },
+    };
+    expect(driftBase(current([accepted]), () => false)?.key).toBe(
+      "beta-2027/submitted.tex",
+    );
+    expect(driftBase(current([accepted]), () => true)?.key).toBe(
+      "beta-2027/camera-ready.tex",
+    );
+    expect(driftBase(current([ALPHA]), () => true)).toBeNull();
+    expect(driftBase(current([]), () => true)).toBeNull();
+  });
+});
+
+describe("each version's state", () => {
+  it("follows the cycle's outcome", () => {
+    const [alpha, beta] = TWO;
+    if (alpha === undefined || beta === undefined) throw new Error("fixture");
+    const accepted = cycles({
+      ...BETA,
+      outcome: { kind: "accepted", date: "2026-12-01", evidence: "m.eml" },
+    })[0];
+    if (accepted === undefined) throw new Error("fixture");
+    expect(stateOf(beta, "submitted")).toBe(
+      "CURRENT (under review at Beta 2027)",
+    );
+    expect(stateOf(beta, "camera-ready")).toBe(
+      "camera-ready, cycle still open",
+    );
+    expect(stateOf(alpha, "submitted")).toBe("historical (rejected)");
+    expect(stateOf(accepted, "submitted")).toBe("camera-ready base");
+    expect(stateOf(accepted, "camera-ready")).toBe("final");
+    expect(stateOf(accepted, "arxiv")).toBe("arXiv copy");
+  });
+
+  it("the table: each cycle newest first, then the draft — what is missing said, nothing frozen said", () => {
+    const withGamma = cycles(
+      ALPHA,
+      {
+        ...BETA,
+        outcome: { kind: "withdrawn", date: "2026-09-20", evidence: "w.md" },
+      },
+      {
+        id: "gamma-2027",
+        venue: { kind: "preset", extends: "paperlint:msr" },
+        opened: "2026-10-01",
+      },
+    );
+    const lock: Lock = {
+      "alpha-2026/submitted.pdf": entry(305412, SHA, "2026-07-22"),
+      "alpha-2026/submitted.tex": { kind: "lost", frozen: "2026-07-22" },
+    };
+    const rows = versionRows({
+      cycles: withGamma,
+      has: (k) => k === "alpha-2026/submitted.pdf",
+      lock,
+      draft: { kind: "none" },
+    });
+    expect(versionTable(rows)).toStrictEqual([
+      "  gamma-2027  —          open, nothing sent yet",
+      "  beta-2027   submitted  NOT FROZEN — submission 7 is on the portal",
+      "  alpha-2026  submitted  historical (rejected)                       305412 B  frozen 2026-07-22, source lost",
+      "  paper.tex   draft      target not chosen                           no attempt to compare with",
+    ]);
+  });
+});
+
+describe("each version's state, the draft row", () => {
+  it("the draft row: the same as its base, drifted, or no base frozen", () => {
+    const draft = (d: Parameters<typeof versionRows>[0]["draft"]) =>
+      versionRows({ cycles: [], has: () => false, lock: {}, draft: d }).at(-1)
+        ?.detail;
+    expect(draft({ kind: "same", key: "b/submitted.tex" })).toBe(
+      "same as b/submitted.tex",
+    );
+    expect(
+      draft({
+        kind: "drift",
+        key: "b/submitted.tex",
+        drift: { added: 1, removed: 18 },
+      }),
+    ).toBe("differs from b/submitted.tex: 1 line added, 18 removed");
+    expect(draft({ kind: "no-base", key: "b/submitted.tex" })).toBe(
+      "nothing frozen at b/submitted.tex to compare with",
+    );
+  });
+
+  it("a closed cycle with nothing frozen, a frozen file not locked", () => {
+    const rows = versionRows({
+      cycles: cycles({ ...ALPHA, submission: null }, BETA),
+      has: (k) => k === "beta-2027/submitted.pdf",
+      lock: {},
+      draft: { kind: "none" },
+    });
+    expect(rows.slice(0, 2)).toStrictEqual([
+      {
+        version: "beta-2027",
+        stage: "submitted",
+        state: "CURRENT (under review at Beta 2027)",
+        detail: "not locked",
+      },
+      {
+        version: "alpha-2026",
+        stage: "—",
+        state: "rejected, nothing frozen",
+        detail: "",
+      },
+    ]);
+  });
+});
+
+describe("relock", () => {
+  const facts = (bytes: number, sha256 = SHA) => ({ bytes, sha256 });
+  it("keeps what matches, records what is new or changed, drops what is gone, keeps a lost source", () => {
+    const old: Lock = {
+      "a/submitted.pdf": entry(10),
+      "a/submitted.tex": entry(5, OTHER, "2026-07-22"),
+      "a/arxiv.tex": { kind: "lost", frozen: null },
+      "b/submitted.pdf": entry(),
+    };
+    const r = relock(
+      [
+        { key: "a/submitted.pdf", facts: facts(10) },
+        { key: "a/submitted.tex", facts: facts(6) },
+        { key: "c/submitted.pdf", facts: facts(3) },
+      ],
+      old,
+      "2026-10-27T12:00:00.000Z",
+    );
+    expect(r.lock).toStrictEqual({
+      "a/arxiv.tex": { kind: "lost", frozen: null },
+      "a/submitted.pdf": entry(10),
+      "a/submitted.tex": entry(6, SHA, "2026-10-27T12:00:00.000Z"),
+      "c/submitted.pdf": entry(3, SHA, "2026-10-27T12:00:00.000Z"),
+    });
+    expect(r.lines).toStrictEqual([
+      "re-locked     versions/a/submitted.tex: 5 → 6 bytes — it changed after 2026-07-22",
+      "locked        versions/c/submitted.pdf (3 bytes)",
+      "dropped       versions/b/submitted.pdf: the file is gone",
+    ]);
+  });
+
+  it("a file where the lock recorded a lost source: recorded; same bytes, other digest: recorded anew", () => {
+    const r = relock(
+      [
+        { key: "a/submitted.tex", facts: facts(5) },
+        { key: "a/submitted.pdf", facts: facts(10, OTHER) },
+      ],
+      {
+        "a/submitted.tex": { kind: "lost", frozen: null },
+        "a/submitted.pdf": entry(10),
+      },
+      "2026-10-27T12:00:00.000Z",
+    );
+    expect(r.lines).toStrictEqual([
+      "locked        versions/a/submitted.tex (5 bytes)",
+      "re-locked     versions/a/submitted.pdf: 10 → 10 bytes — it changed after 2026-10-23T16:58:01.000Z",
+    ]);
+  });
+});