paperlint 12.1.0 → 13.0.0

package/src/adapters/yaml/index.test.ts

@@ -0,0 +1,16 @@
+/** `parseYaml`: the value, a bare date as a `Date`, or the parser's own message. */
+import { expect, test } from "vitest";
+import { parseYaml } from "./index.ts";
+
+test("parses a mapping, a date without quotes as a Date; refuses what is not YAML with the reason", () => {
+  expect(parseYaml("a: 1\nd: 2026-07-22\n")).toStrictEqual({
+    ok: true,
+    value: { a: 1, d: new Date("2026-07-22T00:00:00.000Z") },
+  });
+  const bad = parseYaml("a: [");
+  expect(bad.ok).toBe(false);
+  expect(bad).toStrictEqual({
+    ok: false,
+    error: "unexpected end of the stream within a flow collection (2:1)",
+  });
+});

package/src/adapters/yaml/index.ts

@@ -0,0 +1,17 @@
+/**
+ * `ParseYaml` over js-yaml: the one YAML reader of `src/`. A date without quotes reads as a `Date`.
+ * A refusal is the parser's first line — the reason and its line:column — without the excerpt it
+ * prints under it, so it fits in a one-line message.
+ */
+import { load } from "js-yaml";
+import { messageOf } from "../../domain/text.ts";
+import { err, ok } from "../../domain/result.ts";
+import type { ParseYaml } from "../../ports/yaml.ts";
+
+export const parseYaml: ParseYaml = (text) => {
+  try {
+    return ok(load(text));
+  } catch (e) {
+    return err(messageOf(e).split("\n", 1).join(""));
+  }
+};

package/src/cli.test.ts

@@ -912,3 +912,46 @@ test("submission show: through the HotCRP adapter to a local portal, the token i
     });
   }
 });
+
+test("versions: migrate moves an old-layout paper on disk into folders per attempt; show then prints its state", async () => {
+  const dir = join(root, "versions-migrate");
+  writeTree(dir, {
+    "package.json": "{}",
+    "papers/p/paperlint.json": JSON.stringify({
+      cycles: [
+        {
+          id: "open-2027",
+          venue: { kind: "preset", extends: "paperlint:acm-sigconf" },
+          opened: "2026-09-09",
+          submission: { id: 7 },
+        },
+      ],
+    }),
+    "papers/p/paper.tex": "A.\nB.\n",
+    "papers/p/PIPELINE-STATUS.md":
+      "---\nstages:\n  - stage: submitted\n    cycle: open-2027\n    date: 2026-10-23\n    pdf: versions/2026-10-23-submitted.pdf\n    bytes: 4\n    source: versions/2026-10-23-submitted.tex\n---\n# Status\n",
+    "papers/p/versions/2026-10-23-submitted.pdf": "%PDF",
+    "papers/p/versions/2026-10-23-submitted.tex": "A.\n",
+  });
+  const m = await cli(["versions", "migrate", "papers/p"], dir);
+  assert.equal(m.code, 0, m.err);
+  assert.ok(existsSync(join(dir, "papers/p/versions/open-2027/submitted.pdf")));
+  assert.ok(
+    !existsSync(join(dir, "papers/p/versions/2026-10-23-submitted.pdf")),
+  );
+  const s = await cli(["versions", "papers/p"], dir);
+  assert.equal(s.code, 0, s.err);
+  assert.equal(
+    s.out,
+    [
+      "  open-2027  submitted  CURRENT (under review at acm-sigconf)  4 B  frozen 2026-10-23",
+      "  paper.tex  draft      target not chosen                      differs from open-2027/submitted.tex: 1 line added, 0 removed",
+    ].join("\n"),
+  );
+  const l = await cli(["versions", "lock", "papers/p"], dir);
+  assert.equal(l.code, 0, l.err);
+  assert.equal(
+    l.out,
+    "versions/lock.json records every frozen file as it stands",
+  );
+});

package/src/cli.ts

@@ -58,6 +58,8 @@ import {
   nodeAdapters,
   nodeFiles,
   nodeListDir,
+  nodeCopyFile,
+  nodeMoveFile,
 } from "./adapters/node/index.ts";
 import { probeVideo } from "./adapters/mp4box/index.ts";
 import { imageSize } from "./adapters/png/index.ts";
@@ -173,8 +175,16 @@ export { nextSteps } from "./init.ts";
 
 import paperStages from "#eslint-rules/paper-stages";
 import preregCoverage from "#eslint-rules/prereg-coverage";
-import cycleStage from "#eslint-rules/cycle-stage";
 import { CYCLE_RULE_LEVELS, cycleRules } from "./cycle-rules.ts";
+import { runVersions } from "./versions-command.ts";
+import { parseYaml } from "./adapters/yaml/index.ts";
+import {
+  DRAFT_RULE_LEVELS,
+  draftRules,
+  submittedFrozenRules,
+  VERSION_STATUS_RULE_LEVELS,
+  versionLayoutRules,
+} from "./version-rules.ts";
 import {
   FOLDER_VENUE_RULE_LEVELS,
   folderVenueRules,
@@ -260,6 +270,14 @@ const USAGE = `paperlint — machine-checkable gates for a paper kept in git
   npx paperlint submission topics [paper]
                                       the topics the venue's portal offers, against the ones its
                                       preset records; exit 1 when they differ
+  npx paperlint versions [show|lock|migrate] [paper]
+                                      the paper's frozen versions, one folder per attempt:
+                                      versions/<cycle>/<stage>.{pdf,tex}. show (the default): each
+                                      version and its state — under review, historical, camera-ready
+                                      base, final — and how far paper.tex has moved. lock: record the
+                                      files in versions/lock.json (submission --save does it for what
+                                      it sends). migrate: move the stages: list's dated files into
+                                      their cycles' folders, write the lock, drop the list
   npx paperlint studies new <paper-dir> "<title>" [--kind <kind>]
                                       register a study: the next id in repro/studies.json, the folder
                                       repro/<id>-<slug>/ with its README.md and plan.json (a template),
@@ -402,7 +420,7 @@ const REGISTER_AND_CASE_RULES = {
 
 /**
  * The paper's attempts (`cycles` in paperlint.json), judged on `PIPELINE-STATUS.md`: the record itself
- * and its evidence (src/cycle-rules.ts), and the stages that name a cycle (eslint-rules/cycle-stage.ts).
+ * and its evidence (src/cycle-rules.ts), and that each version sent was frozen (src/version-rules.ts).
  * The `cycle` plugin's other rule, `port-done`, reads `paper.tex` (src/tex-venue-rules.ts).
  */
 /** The markdown language with YAML frontmatter: what every markdown block of the config lints as. */
@@ -411,9 +429,27 @@ const MARKDOWN_WITH_FRONTMATTER = {
   languageOptions: { frontmatter: "yaml" },
 };
 
+/** The instant a freeze or a lock records, ISO 8601 (versions/lock.json). */
+const isoNow = (): string => new Date().toISOString();
+
 const CYCLE_STATUS_RULES = {
   ...cycleRules({ files: nodeFiles, venuesDir: presetsDir() }),
-  ...cycleStage.rules,
+  ...submittedFrozenRules({ files: nodeFiles, listDir: nodeListDir }),
+};
+
+/** The `cycle` plugin's rules on `paper.tex`: the port declared done, the draft against its frozen source. */
+const CYCLE_PAPER_RULES = {
+  ...cyclePortRules(TEX_RULE_DEPS),
+  ...draftRules(TEX_RULE_DEPS),
+};
+const CYCLE_PAPER_RULE_LEVELS = {
+  ...CYCLE_PORT_RULE_LEVELS,
+  ...DRAFT_RULE_LEVELS,
+};
+/** The levels of the `cycle` and `versions` rules on `PIPELINE-STATUS.md`. */
+const STATUS_CYCLE_RULE_LEVELS = {
+  ...CYCLE_RULE_LEVELS,
+  ...VERSION_STATUS_RULE_LEVELS,
 };
 
 /** The rules of the files `paper.tex` includes, each read on its own as a fragment (#144). */
@@ -539,6 +575,7 @@ export function buildConfig(
         // Registered, on for no paper: `"study/declare-sample": "error"` in paperlint.json turns it on.
         study: { rules: preregCoverage.rules },
         cycle: { rules: CYCLE_STATUS_RULES },
+        versions: { rules: versionLayoutRules(LAYOUT_RULE_DEPS) },
       },
       ...md,
       rules: {
@@ -547,7 +584,7 @@ export function buildConfig(
         ...FOLDER_VENUE_RULE_LEVELS,
         ...FOLDER_LAYOUT_RULE_LEVELS,
         ...REPRO_RULE_LEVELS,
-        ...CYCLE_RULE_LEVELS,
+        ...STATUS_CYCLE_RULE_LEVELS,
       },
     },
     {
@@ -594,7 +631,7 @@ export function buildConfig(
             ...pageLimitRules({ files: nodeFiles, venuesDir: presetsDir() }),
           },
         },
-        cycle: { rules: cyclePortRules(TEX_RULE_DEPS) },
+        cycle: { rules: CYCLE_PAPER_RULES },
       },
       language: "tex/latex",
       rules: {
@@ -618,7 +655,7 @@ export function buildConfig(
         ...TEX_VENUE_RULE_LEVELS,
         ...FORMAT_RULE_LEVELS,
         ...PAGE_LIMIT_RULE_LEVELS,
-        ...CYCLE_PORT_RULE_LEVELS,
+        ...CYCLE_PAPER_RULE_LEVELS,
         // Silent for a paper that declares no `talk` (src/talk-rules.ts), but talk/undeclared.
         ...TALK_RULE_LEVELS,
       },
@@ -1803,6 +1840,20 @@ const SIMPLE: Readonly<
         err,
       },
     ),
+  versions: (a, { log, err, cwd }) =>
+    runVersions(a.paths, {
+      files: nodeFiles,
+      listDir: nodeListDir,
+      move: nodeMoveFile,
+      copy: nodeCopyFile,
+      yaml: parseYaml,
+      latex: latexReader,
+      codec: sourcesCodec,
+      now: isoNow,
+      cwd,
+      log,
+      err,
+    }),
   submission: (a, { log, err, cwd }) =>
     runSubmission(
       {
@@ -1823,6 +1874,7 @@ const SIMPLE: Readonly<
         latex: latexReader,
         codec: sourcesCodec,
         lintText,
+        now: isoNow,
         log,
         err,
       },

package/src/cycle-rules.ts

@@ -62,7 +62,7 @@ const STATUS_FILE = "PIPELINE-STATUS.md";
 export type CycleRuleName = "record" | "evidence";
 
 /** The `cycles` value of the paper's settings file; undefined when there is no file, no JSON, or no key. */
-function cyclesValue(dir: string, deps: VenueRuleDeps): unknown {
+function cyclesValue(dir: string, deps: Pick<VenueRuleDeps, "files">): unknown {
   const bytes = deps.files.readBytes(callerPath(join(dir, CONFIG_FILE)));
   if (bytes === null) return undefined;
   try {
@@ -75,7 +75,7 @@ function cyclesValue(dir: string, deps: VenueRuleDeps): unknown {
 /** The paper's cycles, parsed and consistent, or the one line that says what is wrong. */
 export function readCycles(
   dir: string,
-  deps: VenueRuleDeps,
+  deps: Pick<VenueRuleDeps, "files">,
 ): Result<Cycles | null, string> {
   const list = parseCycles(cyclesValue(dir, deps));
   if (!list.ok) return list;
@@ -266,11 +266,10 @@ export function cycleRules(
   return { record: rule("record", deps), evidence: rule("evidence", deps) };
 }
 
-/** The level each `cycle/*` rule on PIPELINE-STATUS.md is on at in paperlint's own config — `stage` too (eslint-rules/cycle-stage.ts). */
+/** The level each `cycle/*` rule of this file is on at in paperlint's own config. */
 export const CYCLE_RULE_LEVELS: Readonly<
-  Record<`cycle/${CycleRuleName | "stage"}`, "error">
+  Record<`cycle/${CycleRuleName}`, "error">
 > = {
   "cycle/record": "error",
   "cycle/evidence": "error",
-  "cycle/stage": "error",
 };

package/src/domain/cycle.test.ts

@@ -7,6 +7,7 @@ import { present } from "../../test/support.ts";
 import {
   currentCycle,
   currentDeadlines,
+  cycleId,
   cycleProblemText,
   effectiveBlind,
   parseCycles,
@@ -321,6 +322,25 @@ describe("parseCycles refuses a value of the wrong shape, naming the entry and t
       [{ ...OPEN, kind: 5 }],
       /"kind" must be a string or null/,
     ],
+    [
+      "an id with a slash: it names a folder under versions/, one path segment",
+      [{ ...OPEN, id: "conf/2026" }],
+      /^cycles\[0\]: "id" «conf\/2026» is not one folder name — an id is lowercase letters, digits and hyphens, starting with a letter or a digit \(conf-2026\): it names the attempt's folder, versions\/<id>\/$/,
+    ],
+    [
+      "an id that climbs out of versions/",
+      [{ ...OPEN, id: ".." }],
+      /^cycles\[0\]: "id" «\.\.» is not one folder name/,
+    ],
+    [
+      "an id with a capital, a backslash or a dot",
+      [
+        { ...OPEN, id: "Conf-2026" },
+        { ...OPEN, id: "a\\b" },
+        { ...OPEN, id: "." },
+      ],
+      /^cycles\[0\]: "id" «Conf-2026» is not one folder name/,
+    ],
     [
       "two broken cycles: the first is named, the second never read",
       [{}, {}],
@@ -329,6 +349,13 @@ describe("parseCycles refuses a value of the wrong shape, naming the entry and t
   ])("refuses %s", refuses);
 });
 
+describe("cycleId", () => {
+  it("mints an id that is one folder name, and throws on one that is not", () => {
+    expect(cycleId("msr-2027")).toBe("msr-2027");
+    expect(() => cycleId("conf/2026")).toThrow("not a cycle id: conf/2026");
+  });
+});
+
 describe("currentCycle", () => {
   it("no cycles: none; the last cycle open: that cycle; the last cycle closed: parked on it", () => {
     expect(currentCycle([])).toEqual({ ok: true, value: { kind: "none" } });

package/src/domain/cycle.ts

@@ -37,6 +37,7 @@
  *
  * Parsed by hand: the domain imports no schema library (see `src/CLAUDE.md`).
  */
+import type { Opaque } from "ts-essentials";
 import { err, ok, type Result } from "./result.ts";
 import { fieldOf, isRecord } from "./record.ts";
 import {
@@ -81,9 +82,30 @@ export const OUTCOME_KINDS: readonly Outcome["kind"][] = [
 
 export type Phase = "porting" | "prepared";
 
+/**
+ * A cycle's id: the name of the attempt's folder, `versions/<id>/`, and the first part of its keys in
+ * `versions/lock.json`. Minted only by `isCycleId`, so every freeze, migration, lock and layout check
+ * holds an id that is one path segment: no `/` or `\`, never `.` or `..`, never empty. The charset is
+ * kept small on purpose — lowercase letters, digits and hyphens, starting with a letter or a digit —
+ * so the name means the same folder on every filesystem, case-insensitive ones included.
+ */
+export type CycleId = Opaque<string, "CycleId">;
+
+/** The id's one owner: `parseLock` builds its key pattern from this too. */
+export const CYCLE_ID_PATTERN = "[a-z0-9][a-z0-9-]*";
+const CYCLE_ID = new RegExp(`^${CYCLE_ID_PATTERN}$`);
+
+export const isCycleId = (s: string): s is CycleId => CYCLE_ID.test(s);
+
+/** An id the caller holds as text (a test, a literal), checked where it becomes one; a bad one throws. */
+export function cycleId(s: string): CycleId {
+  if (!isCycleId(s)) throw new Error(`not a cycle id: ${s}`);
+  return s;
+}
+
 export interface Cycle {
-  /** What a stage refers to (`stages[].cycle`): unique in the list. */
-  readonly id: string;
+  /** What a stage refers to (`stages[].cycle`), and the attempt's folder: unique in the list. */
+  readonly id: CycleId;
   readonly venue: CycleVenue;
   /** A key of the preset's `format.kinds`; null when the venue has one kind or none is chosen. */
   readonly kind: string | null;
@@ -262,13 +284,23 @@ const kindOf = (v: unknown): Result<string | null, string> =>
       ? ok(v)
       : err('"kind" must be a string or null');
 
+/** A cycle's id, checked as the folder name it becomes. */
+function parseId(id: unknown, at: string): Result<CycleId, string> {
+  if (typeof id !== "string" || id === "")
+    return err(`${at}: "id" must be a non-empty string (what stages refer to)`);
+  return isCycleId(id)
+    ? ok(id)
+    : err(
+        `${at}: "id" «${id}» is not one folder name — an id is lowercase letters, digits and hyphens, starting with a letter or a digit (conf-2026): it names the attempt's folder, versions/<id>/`,
+      );
+}
+
 function parseHead(
   v: Readonly<Record<string, unknown>>,
   at: string,
 ): Result<Head, string> {
-  const id = v["id"];
-  if (typeof id !== "string" || id === "")
-    return err(`${at}: "id" must be a non-empty string (what stages refer to)`);
+  const id = parseId(v["id"], at);
+  if (!id.ok) return id;
   const venue = parseVenue(v["venue"], at);
   if (!venue.ok) return venue;
   const kind = kindOf(v["kind"]);
@@ -282,7 +314,7 @@ function parseHead(
   if (!isPhase(phase))
     return err(`${at}: "phase" must be "porting" or "prepared"`);
   return ok({
-    id,
+    id: id.value,
     venue: venue.value,
     kind: kind.value,
     opened,

package/src/domain/paper-layout.ts

@@ -14,7 +14,7 @@
  *   - what `paperlint new` scaffolds: `PIPELINE-STATUS.md`, `paper.tex`, `paperlint.json`;
  *   - what the build writes: `paper.pdf` and `_build/`, and TeX's own byproducts beside `paper.tex`
  *     (pdflatex runs in the paper folder without `-output-directory`), which are never reported;
- *   - what the rules read: `versions/` (`paper/stages`), `reviews/` (`review/frontmatter`),
+ *   - what the rules read: `versions/` (`versions/layout`, `paper/stages`), `reviews/` (`review/frontmatter`),
  *     `siblings/` (`sibling/frontmatter`), `talk/` (the `talk/` rules' default folder);
  *   - what the skills read or write at the root: `README.md`, `CLAUDE.md`, `CLAIMS.md`, `NOTES.md`,
  *     `SUBMIT-CHECKLIST.md`, `research/`, `repro/`, `figures/`, `submission/`;
@@ -93,7 +93,10 @@ export const ROOT_FILES: readonly string[] = ROOT_FILE_NOTES.map((f) => f.name);
 /** The folders the root may hold, by exact name, each with what it holds. */
 export const ROOT_DIR_NOTES: readonly Noted[] = [
   { name: "_build", note: "the facts `paperlint build` writes" },
-  { name: "versions", note: "each stage's frozen PDF and source" },
+  {
+    name: "versions",
+    note: "each stage's frozen PDF and source — per attempt, versions/<cycle>/, with lock.json",
+  },
   { name: "reviews", note: "dated reviews and pass reports" },
   { name: "siblings", note: "the cards of competing papers" },
   { name: "research", note: "dated research and decision records" },

package/src/domain/paths.test.ts

@@ -1,6 +1,6 @@
 import assert from "node:assert/strict";
 import { test } from "vitest";
-import { absolutePath, joinPath } from "./paths.ts";
+import { absolutePath, asPaperPath, joinPath, paperPath } from "./paths.ts";
 
 test("absolutePath keeps an absolute path as it is", () => {
   assert.equal(absolutePath("/a/b"), "/a/b");
@@ -13,3 +13,30 @@ test("absolutePath refuses a relative path instead of letting the process's cwd
 test("joinPath stays under its absolute base", () => {
   assert.equal(joinPath(absolutePath("/a"), "b", "c"), "/a/b/c");
 });
+
+test("paperPath: one spelling per file of the paper, and nothing outside it", () => {
+  assert.deepEqual(paperPath("./versions/a.tex"), {
+    ok: true,
+    value: "versions/a.tex",
+  });
+  assert.deepEqual(paperPath("versions//b/../a.tex"), {
+    ok: true,
+    value: "versions/a.tex",
+  });
+  for (const bad of ["../x.tex", "versions/../../x", "/abs/x", "", ".", "a\\b"])
+    assert.deepEqual(paperPath(bad), {
+      ok: false,
+      error: `\`${bad}\` is not a path inside the paper folder`,
+    });
+});
+
+test("asPaperPath keeps a composed path, and throws on one that is not one spelling inside the paper", () => {
+  assert.equal(
+    asPaperPath("versions/c/submitted.pdf"),
+    "versions/c/submitted.pdf",
+  );
+  assert.throws(
+    () => asPaperPath("versions/./x"),
+    /not a path inside the paper folder/,
+  );
+});

package/src/domain/paths.ts

@@ -1,6 +1,7 @@
 /** Paths as the domain holds them. */
-import { isAbsolute, join } from "node:path";
+import { isAbsolute, join, posix } from "node:path";
 import type { Opaque } from "ts-essentials";
+import { err, ok, type Result } from "./result.ts";
 
 /**
  * An absolute path. Minted by `absolutePath` (a checked string) or `joinPath` (an absolute base and
@@ -22,3 +23,35 @@ export const joinPath = (
   base: AbsolutePath,
   ...segments: string[]
 ): AbsolutePath => absolutePath(join(base, ...segments));
+
+/**
+ * A file of a paper, by its path relative to the paper folder, in one spelling: posix-normalized, no
+ * leading `./`, never absolute, never out of the folder (`..`), never the folder itself. Two
+ * spellings of one file (`./versions/a.tex`, `versions/a.tex`) are then one value, so comparing,
+ * grouping and checking paths is comparing strings.
+ */
+export type PaperPath = Opaque<string, "PaperPath">;
+
+// The brand's one owner, as for AbsolutePath: the predicate is the check.
+const isPaperPath = (p: string): p is PaperPath =>
+  p !== "." &&
+  p !== ".." &&
+  !p.startsWith("../") &&
+  !isAbsolute(p) &&
+  !p.includes("\\") &&
+  posix.normalize(p) === p;
+
+/** A path as a paper's record spells it, normalized; or why it names no file inside the paper. */
+export function paperPath(raw: string): Result<PaperPath, string> {
+  const p = posix.normalize(raw);
+  return isPaperPath(p)
+    ? ok(p)
+    : err(`\`${raw}\` is not a path inside the paper folder`);
+}
+
+/** A path the code composes from parts it already holds (`versions/<key>`); one that is not throws. */
+export function asPaperPath(p: string): PaperPath {
+  if (!isPaperPath(p))
+    throw new Error(`not a path inside the paper folder: ${p}`);
+  return p;
+}

package/src/domain/scaffold-layout.ts

@@ -16,7 +16,7 @@
  * Git keeps files, not folders: an empty folder is not in the first commit, which is the point of
  * scaffolding. A folder that holds nothing else gets a `.gitkeep`; a folder that holds a real file
  * (`repro/` with its README.md) gets none. `.gitkeep` is the convention, not a paperlint file, and no
- * rule reads it: `paper/stages` looks for `*.pdf` in `versions/`, the review and sibling rules lint
+ * rule reads it: `versions/layout` and `paper/stages` look for `*.pdf` in `versions/`, the review and sibling rules lint
  * `*.md`, `repro/allowed-files-only` judges the top of `repro/` only, and neither `tools/` nor `data/` is
  * listed by any rule.
  *