paperlint 7.1.0 → 7.2.0

package/src/cycle-rules.test.ts

@@ -0,0 +1,278 @@
+/**
+ * `cycle/record` and `cycle/evidence` on a paper folder's settings file: both halves of each — the
+ * finding on a planted defect, silence on a consistent record and on the flat form.
+ */
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { memoryFiles } from "./adapters/memory/index.ts";
+import { presetsDir } from "./package-dirs.ts";
+import { cycleRules } from "./cycle-rules.ts";
+
+const VENUES = presetsDir();
+const DIR = "/work/papers/p";
+/** The shipped presets, so a cycle naming `paperlint:msr` resolves through the memory files. */
+const SHIPPED = Object.fromEntries(
+  readdirSync(VENUES)
+    .filter((f) => f.endsWith(".jsonc"))
+    .map((f) => [join(VENUES, f), readFileSync(join(VENUES, f), "utf8")]),
+);
+
+interface Reported {
+  readonly rule: string;
+  readonly messageId: string;
+  readonly message: string;
+}
+
+const closed = {
+  id: "alpha-2026",
+  venue: { kind: "preset", extends: "paperlint:acm-sigconf" },
+  kind: "short",
+  opened: "2026-07-01",
+  outcome: {
+    kind: "rejected",
+    date: "2026-09-08",
+    desk: true,
+    evidence: "reviews/alpha-decision.md",
+  },
+};
+const open = {
+  id: "beta-2027",
+  venue: { kind: "preset", extends: "paperlint:ieee-conference" },
+  kind: "technical",
+  opened: "2026-09-09",
+  deadlines: [
+    {
+      what: "submission",
+      observed: [
+        {
+          at: "2026-10-20T04:00:00Z",
+          source: "portal",
+          url: "https://beta2027.example.org/deadlines",
+          read: "2026-09-09",
+        },
+      ],
+    },
+  ],
+};
+const CALL = {
+  source: "call",
+  url: "https://2027.msrconf.org/track/msr-2027-technical-papers",
+  read: "2026-10-05",
+};
+/** A cycle at the shipped `paperlint:msr`, whose preset carries the portal's readings. */
+const msr = (deadlines: readonly object[]) => ({
+  id: "msr-2027",
+  venue: { kind: "preset", extends: "paperlint:msr" },
+  kind: "technical",
+  opened: "2026-10-05",
+  deadlines,
+});
+const OVERRIDE = {
+  at: "2026-10-27T04:00:00Z",
+  reason: "the chairs extended the deadline by mail",
+  evidence: "mail/extension.eml",
+};
+
+/** Every cycle rule over the paper folder holding `settings` (a string: the raw file) and `extra` files. */
+function lint(
+  settings: object | string | undefined,
+  extra: Readonly<Record<string, string>> = {},
+  file = "PIPELINE-STATUS.md",
+): Reported[] {
+  const files = memoryFiles({
+    ...(settings === undefined
+      ? {}
+      : {
+          [`${DIR}/paperlint.json`]:
+            typeof settings === "string" ? settings : JSON.stringify(settings),
+        }),
+    ...SHIPPED,
+    ...extra,
+  });
+  const out: Reported[] = [];
+  Object.entries(cycleRules({ files, venuesDir: VENUES })).forEach(
+    ([name, rule]) => {
+      rule
+        .create({
+          filename: `${DIR}/${file}`,
+          sourceCode: { getLocFromIndex: () => ({ line: 1, column: 0 }) },
+          report: (d) => {
+            const template = rule.meta.messages[d.messageId] ?? "";
+            out.push({
+              rule: `cycle/${name}`,
+              messageId: d.messageId,
+              message: Object.entries(d.data).reduce(
+                (m, [k, v]) => m.split(`{{${k}}}`).join(String(v)),
+                template,
+              ),
+            });
+          },
+        })
+        .root?.();
+    },
+  );
+  return out;
+}
+
+const EVIDENCE = { [`${DIR}/reviews/alpha-decision.md`]: "# decision\n" };
+
+describe("cycle/record", () => {
+  it("reports on PIPELINE-STATUS.md only — any other file in the folder gets nothing", () => {
+    expect(lint({ cycles: [open, open] }, {}, "paper.tex")).toEqual([]);
+  });
+
+  it("a consistent record with its evidence on disk: every cycle rule is silent", () => {
+    expect(lint({ cycles: [closed, open] }, EVIDENCE)).toEqual([]);
+  });
+
+  it("the flat form, no settings file, or a file that is not JSON: silent — not this rule's to say", () => {
+    expect(lint({ extends: "paperlint:aidc", kind: "regular" })).toEqual([]);
+    expect(lint(undefined)).toEqual([]);
+    expect(lint("{ not json")).toEqual([]);
+  });
+
+  it("two open cycles: `broken`, naming both and the cure", () => {
+    const [f] = lint({
+      cycles: [{ ...closed, outcome: { kind: "open" } }, open],
+    });
+    expect(f?.messageId).toBe("broken");
+    expect(f?.message).toMatch(
+      /^paperlint\.json: cycles «alpha-2026» and «beta-2027» are both open/,
+    );
+  });
+
+  it("a deadline without its zone: `broken`, naming the entry and the key", () => {
+    const bad = msr([
+      { what: "submission", observed: [{ ...CALL, at: "2026-10-23" }] },
+    ]);
+    const m: unknown = expect.stringMatching(
+      /^paperlint\.json: cycles\[0\]\.deadlines\[0\]\.observed\[0\]: "at" must be an instant with its zone/,
+    );
+    expect(lint({ cycles: [bad] }).map((f) => f.message)).toEqual([m]);
+  });
+});
+
+describe("cycle/record — the deadlines, over the venue preset's readings", () => {
+  it("MSR 2027 as a newcomer records the call: abstract → registration, paper → submission; the preset's portal readings are derived — silent", () => {
+    // The portal's submission (2026-10-20T04:00Z, from the preset) is earlier than the call's
+    // registration (the end of 2026-10-20 AoE): two sources disagreeing, not a typo.
+    const fs = lint({
+      cycles: [
+        msr([
+          {
+            what: "registration",
+            observed: [{ ...CALL, at: "2026-10-20 AoE" }],
+          },
+          { what: "submission", observed: [{ ...CALL, at: "2026-10-23 AoE" }] },
+        ]),
+      ],
+    });
+    expect(fs).toEqual([]);
+  });
+
+  it("the call's own dates out of order: `order`, naming the cycle and the source", () => {
+    const fs = lint({
+      cycles: [
+        msr([
+          {
+            what: "registration",
+            observed: [{ ...CALL, at: "2026-10-25 AoE" }],
+          },
+          { what: "submission", observed: [{ ...CALL, at: "2026-10-23 AoE" }] },
+        ]),
+      ],
+    });
+    expect(fs.map((f) => f.messageId)).toEqual(["order"]);
+    expect(fs[0]?.message).toBe(
+      'paperlint.json, cycle «msr-2027»: the call\'s "registration" (2026-10-26T11:59:59Z) is after its "submission" (2026-10-24T11:59:59Z) — a date typed wrong, or an AoE day miscounted (write a call\'s date as "YYYY-MM-DD AoE" and paperlint converts it)',
+    );
+  });
+});
+
+describe("cycle/record — a portal reading beside the preset's", () => {
+  it("a portal reading of a deadline the venue's preset already carries: `presetCopy`, naming the preset's reading", () => {
+    const fs = lint({
+      cycles: [
+        msr([
+          {
+            what: "submission",
+            observed: [
+              {
+                at: "2026-10-20T04:00:00Z",
+                source: "portal",
+                url: "https://msr2027.hotcrp.com/deadlines",
+                read: "2026-10-01",
+              },
+            ],
+          },
+        ]),
+      ],
+    });
+    expect(fs.map((f) => f.message)).toEqual([
+      "paperlint.json, cycle «msr-2027»: the \"submission\" deadline records a portal reading, and the preset paperlint:msr carries the portal's reading of it (2026-10-20T04:00:00Z, read 2026-10-05) — a second copy drifts when paperlint updates the preset: delete this one (the call's reading and an override stay)",
+    ]);
+  });
+
+  it("a portal reading of a venue whose preset carries none, or a named venue: the paper's to record — silent", () => {
+    expect(lint({ cycles: [open] })).toEqual([]);
+    expect(
+      lint({
+        cycles: [
+          {
+            ...open,
+            venue: {
+              kind: "named",
+              name: "Beta '27",
+              url: "https://beta.example.org",
+            },
+          },
+        ],
+      }),
+    ).toEqual([]);
+  });
+
+  it("a cycle whose preset does not resolve: its readings are judged alone (pdf/profile names the preset)", () => {
+    expect(
+      lint({
+        cycles: [
+          { ...open, venue: { kind: "preset", extends: "paperlint:nosuch" } },
+        ],
+      }),
+    ).toEqual([]);
+  });
+});
+
+describe("cycle/evidence", () => {
+  it("a closed cycle whose evidence file is not in the folder: `missing`, with the path", () => {
+    const fs = lint({ cycles: [closed, open] });
+    expect(fs.map((f) => f.rule)).toEqual(["cycle/evidence"]);
+    expect(fs[0]?.message).toMatch(
+      /^cycle «alpha-2026» is rejected \(2026-09-08\) with evidence `reviews\/alpha-decision\.md`, which is not in the paper folder/,
+    );
+  });
+
+  it("an override whose evidence is not in the folder: `overrideMissing`; on disk: silent", () => {
+    const settings = {
+      cycles: [msr([{ what: "submission", override: OVERRIDE }])],
+    };
+    expect(lint(settings).map((f) => [f.rule, f.message])).toEqual([
+      [
+        "cycle/evidence",
+        'cycle «msr-2027»: the override of the "submission" deadline (2026-10-27T04:00:00Z) rests on `mail/extension.eml`, which is not in the paper folder — save the mail or the page that grants it there, or correct the path',
+      ],
+    ]);
+    expect(
+      lint(settings, { [`${DIR}/mail/extension.eml`]: "From: chairs\n" }),
+    ).toEqual([]);
+  });
+
+  it("an open cycle owes no evidence; a broken record is `cycle/record`'s alone", () => {
+    expect(lint({ cycles: [open] })).toEqual([]);
+    expect(
+      lint({ cycles: [{ ...closed, outcome: { kind: "open" } }, open] }).map(
+        (f) => f.rule,
+      ),
+    ).toEqual(["cycle/record"]);
+  });
+});

package/src/cycle-rules.ts

@@ -0,0 +1,273 @@
+/**
+ * THE CYCLE RULES over a paper's settings file — the `cycle` plugin, judged once per paper on its
+ * `PIPELINE-STATUS.md` (every paper folder has one, whatever its source format; `paper/folder-venue-leftover`
+ * reports there for the same reason):
+ *
+ *   cycle/record    error  `cycles` in paperlint.json parses and names one current attempt: no two
+ *                          open cycles, the open one last, ids unique, every deadline an instant
+ *                          with its zone; each source's deadlines in order; no portal reading the
+ *                          venue's preset already carries
+ *   cycle/evidence  error  every closed cycle's `outcome.evidence`, and every deadline override's
+ *                          `evidence`, is a file in the paper folder
+ *
+ * ── WHY ERROR, NOT WARN ───────────────────────────────────────────────────────────
+ * A warning is read once and never again. Each of these names a state that cannot be worked in:
+ * two open cycles is dual submission or a decision nobody recorded; a deadline without its zone is
+ * the mistake the record exists to prevent; a decision or an override whose evidence is not in the
+ * folder is a claim with nothing behind it. Nothing here depends on a clock or the network — the
+ * record is judged against itself, the installed venue preset and the disk, like `paper/stages`.
+ *
+ * ── THE PRESET'S READINGS ARE DERIVED, NOT COPIED ──────────────────────────────────
+ * A cycle whose venue is a preset gets that preset's `deadlines` (the portal's readings, refreshed in
+ * the package); the paper adds the call's readings and its overrides. A paper's own portal reading
+ * of a deadline the preset carries is a second copy of one fact, and it drifts the day the preset is
+ * updated — so it is reported.
+ *
+ * ── WHO SPEAKS WHEN THERE IS NOTHING TO JUDGE ──────────────────────────────────────
+ * No `paperlint.json`, one that is not JSON, or one without `cycles` (the flat form): silent — the
+ * flat form is still valid, and `pdf/profile` says when the whole file is broken. A `cycles` that
+ * does not parse, or names no current attempt (two open cycles), never reaches this rule through
+ * `paperlint lint`: `paperRuleBlocks` (src/cli.ts) refuses the settings file before ESLint runs, one
+ * line naming the file and the problem, exit 2 — the same strictness as an unknown key (measured
+ * 2026-10-05). The `broken` message below is what the rule says when a host runs it without that
+ * refusal; under the CLI only `order` is reachable.
+ */
+import { basename, dirname, join } from "node:path";
+import { callerPath } from "./caller-path.ts";
+import {
+  cycleProblemText,
+  cyclesOf,
+  parseCycles,
+  type Cycle,
+  type Cycles,
+} from "./domain/cycle.ts";
+import { deadlineOrderProblems, type Reading } from "./domain/deadline.ts";
+import { resolvePreset } from "./presets.ts";
+import { fieldOf } from "./domain/record.ts";
+import { err, ok, type Result } from "./domain/result.ts";
+import type {
+  FolderRuleContext,
+  FolderRuleModule,
+} from "./folder-venue-rule.ts";
+import type { Finding, VenueRuleDeps } from "./venue-rules.ts";
+import { rulePageUrl } from "./venue-rules.ts";
+import { CONFIG_FILE } from "#lib/paper-config";
+
+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 {
+  const bytes = deps.files.readBytes(callerPath(join(dir, CONFIG_FILE)));
+  if (bytes === null) return undefined;
+  try {
+    return fieldOf(JSON.parse(new TextDecoder().decode(bytes)), "cycles");
+  } catch {
+    return undefined;
+  }
+}
+
+/** The paper's cycles, parsed and consistent, or the one line that says what is wrong. */
+export function readCycles(
+  dir: string,
+  deps: VenueRuleDeps,
+): Result<Cycles | null, string> {
+  const list = parseCycles(cyclesValue(dir, deps));
+  if (!list.ok) return list;
+  if (list.value === null) return ok(null);
+  const cycles = cyclesOf(list.value);
+  return cycles.ok ? cycles : err(cycleProblemText(cycles.error));
+}
+
+/** A cycle's venue preset — its spec, as the cycle names it — and the readings it carries. */
+export interface PresetOfCycle {
+  readonly spec: string;
+  readonly readings: readonly Reading[];
+}
+
+/** The preset of a cycle; null for a named venue or a preset that does not resolve. */
+export type PresetReadings = (c: Cycle) => PresetOfCycle | null;
+
+/** A paper's portal readings of deadlines its venue's preset already carries. */
+function presetCopies(c: Cycle, preset: PresetOfCycle): readonly Finding[] {
+  return c.deadlines.flatMap((d) => {
+    const theirs = preset.readings.find(
+      (r) => r.what === d.what && r.source === "portal",
+    );
+    const ours = d.observed.some((o) => o.source === "portal");
+    return theirs !== undefined && ours
+      ? [
+          {
+            messageId: "presetCopy",
+            data: {
+              id: c.id,
+              what: d.what,
+              preset: preset.spec,
+              at: theirs.at,
+              read: theirs.read,
+            },
+          },
+        ]
+      : [];
+  });
+}
+
+/** `cycle/record`: the record's own problems. Pure over the read and the presets' readings. */
+export function judgeRecord(
+  read: Result<Cycles | null, string>,
+  presetReadings: PresetReadings,
+): readonly Finding[] {
+  if (!read.ok) return [{ messageId: "broken", data: { why: read.error } }];
+  if (read.value === null) return [];
+  return read.value.list.flatMap((c) => {
+    const preset = presetReadings(c);
+    return [
+      ...deadlineOrderProblems(c.deadlines, preset?.readings ?? []).map(
+        (why) => ({ messageId: "order", data: { id: c.id, why } }),
+      ),
+      ...(preset === null ? [] : presetCopies(c, preset)),
+    ];
+  });
+}
+
+/** The overrides whose evidence is not on disk. */
+const overrideEvidence = (
+  c: Cycle,
+  isFile: (relative: string) => boolean,
+): readonly Finding[] =>
+  c.deadlines.flatMap((d) =>
+    d.override !== null && !isFile(d.override.evidence)
+      ? [
+          {
+            messageId: "overrideMissing",
+            data: {
+              id: c.id,
+              what: d.what,
+              at: d.override.at,
+              evidence: d.override.evidence,
+            },
+          },
+        ]
+      : [],
+  );
+
+/** The closed cycles, and the overrides, whose evidence is not on disk. */
+export function judgeEvidence(
+  cycles: readonly Cycle[],
+  isFile: (relative: string) => boolean,
+): readonly Finding[] {
+  return cycles.flatMap((c) => {
+    const o = c.outcome;
+    return [
+      ...(o.kind !== "open" && !isFile(o.evidence)
+        ? [
+            {
+              messageId: "missing",
+              data: {
+                id: c.id,
+                outcome: o.kind,
+                date: o.date,
+                evidence: o.evidence,
+              },
+            },
+          ]
+        : []),
+      ...overrideEvidence(c, isFile),
+    ];
+  });
+}
+
+const META: Readonly<Record<CycleRuleName, FolderRuleModule["meta"]>> = {
+  record: {
+    type: "suggestion",
+    docs: {
+      description:
+        "the paper's `cycles` record parses and names one current attempt, each source's deadlines in order, no copy of the preset's portal readings",
+      url: rulePageUrl("cycle/record"),
+    },
+    schema: [],
+    messages: {
+      broken: `${CONFIG_FILE}: {{why}}`,
+      order: `${CONFIG_FILE}, cycle «{{id}}»: {{why}} — a date typed wrong, or an AoE day miscounted (write a call's date as "YYYY-MM-DD AoE" and paperlint converts it)`,
+      presetCopy: `${CONFIG_FILE}, cycle «{{id}}»: the "{{what}}" deadline records a portal reading, and the preset {{preset}} carries the portal's reading of it ({{at}}, read {{read}}) — a second copy drifts when paperlint updates the preset: delete this one (the call's reading and an override stay)`,
+    },
+  },
+  evidence: {
+    type: "suggestion",
+    docs: {
+      description:
+        "every closed cycle's decision, and every deadline override, points at a file in the paper folder — the mail, the reviews, the note",
+      url: rulePageUrl("cycle/evidence"),
+    },
+    schema: [],
+    messages: {
+      missing:
+        "cycle «{{id}}» is {{outcome}} ({{date}}) with evidence `{{evidence}}`, which is not in the paper folder — save the decision mail, the reviews or the note that records the decision there, or correct the path",
+      overrideMissing:
+        'cycle «{{id}}»: the override of the "{{what}}" deadline ({{at}}) rests on `{{evidence}}`, which is not in the paper folder — save the mail or the page that grants it there, or correct the path',
+    },
+  },
+};
+
+/** Each cycle's venue preset's readings, resolved from the paper's settings file like `extends`. */
+const presetReadingsOf =
+  (dir: string, deps: VenueRuleDeps): PresetReadings =>
+  (c) => {
+    if (c.venue.kind !== "preset") return null;
+    const spec = c.venue.extends;
+    const p = resolvePreset(spec, join(dir, CONFIG_FILE), deps);
+    return p.ok ? { spec, readings: p.value.deadlines } : null;
+  };
+
+/** The findings of one rule for the paper folder `dir`. */
+function findingsFor(
+  name: CycleRuleName,
+  dir: string,
+  deps: VenueRuleDeps,
+): readonly Finding[] {
+  const read = readCycles(dir, deps);
+  switch (name) {
+    case "record":
+      return judgeRecord(read, presetReadingsOf(dir, deps));
+    case "evidence":
+      return read.ok && read.value !== null
+        ? judgeEvidence(read.value.list, (rel) =>
+            deps.files.isFile(callerPath(join(dir, rel))),
+          )
+        : [];
+  }
+}
+
+function rule(name: CycleRuleName, deps: VenueRuleDeps): FolderRuleModule {
+  return {
+    meta: META[name],
+    create(context: FolderRuleContext) {
+      if (basename(context.filename) !== STATUS_FILE) return {};
+      return {
+        root() {
+          const at = context.sourceCode.getLocFromIndex(0);
+          findingsFor(name, dirname(context.filename), deps).forEach((f) => {
+            context.report({ loc: { start: at, end: at }, ...f });
+          });
+        },
+      };
+    },
+  };
+}
+
+/** The `cycle` plugin's rules over the settings file, for every paper's `PIPELINE-STATUS.md`. */
+export function cycleRules(
+  deps: VenueRuleDeps,
+): Readonly<Record<CycleRuleName, FolderRuleModule>> {
+  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). */
+export const CYCLE_RULE_LEVELS: Readonly<
+  Record<`cycle/${CycleRuleName | "stage"}`, "error">
+> = {
+  "cycle/record": "error",
+  "cycle/evidence": "error",
+  "cycle/stage": "error",
+};