paperlint 7.1.0 → 7.2.0

package/src/adapters/hotcrp/deadlines.io.test.ts

@@ -0,0 +1,86 @@
+/**
+ * `hotcrpDeadlines` over a local server that answers `GET /deadlines` with a recorded page: the
+ * request paperlint sends (the path, no credential) and what comes back through the parser; and a
+ * site that does not answer at all.
+ */
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import {
+  createServer,
+  type IncomingMessage,
+  type Server,
+  type ServerResponse,
+} from "node:http";
+import { afterAll, beforeAll, test } from "vitest";
+import { hotcrpDeadlines } from "./deadlines.io.ts";
+
+const page = readFileSync(
+  new URL("./cassette/deadlines-msr2027.html", import.meta.url),
+  "utf8",
+);
+
+const seen: { url: string; authorization: string | undefined }[] = [];
+const server = createServer((req: IncomingMessage, res: ServerResponse) => {
+  seen.push({ url: req.url ?? "", authorization: req.headers.authorization });
+  if (req.url === "/deadlines") {
+    res.writeHead(200, { "content-type": "text/html" });
+    res.end(page);
+  } else {
+    res.writeHead(404, { "content-type": "text/html" });
+    res.end('<h1 id="h-title">No such conference</h1>');
+  }
+});
+
+const portOf = (s: Server): number => {
+  const a = s.address();
+  assert.ok(a !== null && typeof a === "object", "the server is not listening");
+  return a.port;
+};
+const closeServer = (s: Server): Promise<void> =>
+  new Promise<void>((r) => {
+    s.close(() => {
+      r();
+    });
+  });
+
+let base = "";
+beforeAll(async () => {
+  await new Promise<void>((r) => server.listen(0, "127.0.0.1", r));
+  base = `http://127.0.0.1:${String(portOf(server))}`;
+});
+afterAll(() => closeServer(server));
+
+test("GET <site>/deadlines, no credential; the page parses to the venue's deadlines", async () => {
+  const r = await hotcrpDeadlines({ url: base }).read();
+  assert.deepEqual(seen.at(-1), {
+    url: "/deadlines",
+    authorization: undefined,
+  });
+  assert.ok(r.ok, JSON.stringify(r));
+  assert.equal(r.value.open, true);
+  assert.deepEqual(
+    r.value.deadlines.map((d) => [d.what, d.at]),
+    [
+      ["submission", "2026-10-20T04:00:00Z"],
+      ["resubmission", "2026-10-23T04:00:00Z"],
+    ],
+  );
+});
+
+test("a site that is not a conference: refused with the page's title", async () => {
+  const r = await hotcrpDeadlines({ url: `${base}/nosuch` }).read();
+  assert.ok(!r.ok);
+  assert.equal(r.error.kind, "refused");
+});
+
+test("a site that does not answer is unreachable, with the network's words", async () => {
+  const closed = createServer();
+  await new Promise<void>((r) => closed.listen(0, "127.0.0.1", r));
+  const port = portOf(closed);
+  await closeServer(closed);
+  const r = await hotcrpDeadlines({
+    url: `http://127.0.0.1:${String(port)}`,
+  }).read();
+  assert.ok(!r.ok);
+  assert.equal(r.error.kind, "unreachable");
+});

package/src/adapters/hotcrp/deadlines.io.ts

@@ -0,0 +1,27 @@
+/**
+ * HotCRP's deadlines page over Node's `fetch`: `GET <site>/deadlines`, no token — the page is
+ * public, and a deadline is nobody's secret.
+ */
+import { messageOf } from "../../domain/text.ts";
+import { err } from "../../domain/result.ts";
+import type { VenueDeadlines } from "../../ports/venue-deadlines.ts";
+import { parseDeadlinesPage } from "./deadlines.ts";
+
+const READ_TIMEOUT_MS = 60_000;
+
+/** The deadlines of the HotCRP site at `url` (no trailing slash). */
+export function hotcrpDeadlines(o: { readonly url: string }): VenueDeadlines {
+  return {
+    async read() {
+      try {
+        const r = await fetch(`${o.url}/deadlines`, {
+          headers: { Accept: "text/html" },
+          signal: AbortSignal.timeout(READ_TIMEOUT_MS),
+        });
+        return parseDeadlinesPage(r.status, await r.text());
+      } catch (e) {
+        return err({ kind: "unreachable", detail: messageOf(e) });
+      }
+    },
+  };
+}

package/src/adapters/hotcrp/deadlines.test.ts

@@ -0,0 +1,170 @@
+/**
+ * The deadlines page parser on the pages five live HotCRP sites answered on 2026-10-05
+ * (`cassette/deadlines-*.html`, recorded whole), and on a site that does not exist. Each expected
+ * value was read off the page's text by hand before the parser existed.
+ */
+import { readFileSync } from "node:fs";
+import { describe, expect, it } from "vitest";
+import { parseDeadlinesPage, whatOf } from "./index.ts";
+
+type Site = "msr2027" | "aidc26" | "sosp26" | "icse2027" | "fse2027" | "nosuch";
+const page = (site: Site): string =>
+  readFileSync(
+    new URL(`./cassette/deadlines-${site}.html`, import.meta.url),
+    "utf8",
+  );
+
+const read = (site: Site, status = 200) => {
+  const r = parseDeadlinesPage(status, page(site));
+  if (!r.ok) throw new Error(JSON.stringify(r.error));
+  return r.value;
+};
+
+describe("parseDeadlinesPage", () => {
+  it("a conference with a resubmission deadline: the list carries it, the status object does not", () => {
+    expect(read("msr2027")).toEqual({
+      now: 1791194488.329003,
+      open: true,
+      blind: true,
+      deadlines: [
+        {
+          what: "submission",
+          label: "Submission deadline",
+          at: "2026-10-20T04:00:00Z",
+        },
+        {
+          what: "resubmission",
+          label: "Resubmission deadline",
+          at: "2026-10-23T04:00:00Z",
+        },
+      ],
+    });
+  });
+
+  it("a workshop past its submission deadline, with a final-version deadline only the status object names", () => {
+    expect(read("aidc26")).toEqual({
+      now: 1791194489.473936,
+      open: true,
+      blind: true,
+      deadlines: [
+        {
+          what: "submission",
+          label: "Submission deadline",
+          at: "2026-10-03T11:59:59Z",
+        },
+        {
+          what: "camera-ready",
+          label: "camera-ready",
+          at: "2026-10-31T11:59:59Z",
+        },
+      ],
+    });
+  });
+});
+
+describe("parseDeadlinesPage — every kind at once", () => {
+  it("registration, submission, a late resubmission and a final version: sorted by time", () => {
+    expect(read("sosp26").deadlines).toEqual([
+      {
+        what: "registration",
+        label: "Registration deadline",
+        at: "2026-03-27T11:59:59Z",
+      },
+      {
+        what: "submission",
+        label: "Submission deadline",
+        at: "2026-04-02T11:59:59Z",
+      },
+      {
+        what: "resubmission",
+        label: "Resubmission deadline",
+        at: "2026-08-14T23:59:59Z",
+      },
+      {
+        what: "camera-ready",
+        label: "camera-ready",
+        at: "2026-08-29T11:59:59Z",
+      },
+    ]);
+  });
+});
+
+describe("parseDeadlinesPage — a closed round, AoE, and pages that are not deadlines", () => {
+  it("a round that is not open: `open` is false and the dates still read", () => {
+    const r = read("icse2027");
+    expect(r.open).toBe(false);
+    expect(r.deadlines.map((d) => [d.what, d.at])).toEqual([
+      ["registration", "2026-06-24T11:59:59Z"],
+      ["submission", "2026-07-09T11:59:00Z"],
+    ]);
+  });
+});
+
+describe("parseDeadlinesPage — AoE and non-pages", () => {
+  it("the AoE a page prints is already an instant in UTC: «Oct 3, 11:59 PM AoE» is Oct 4, 11:59 UTC", () => {
+    expect(read("fse2027").deadlines).toEqual([
+      {
+        what: "submission",
+        label: "Submission deadline",
+        at: "2026-10-04T11:59:00Z",
+      },
+    ]);
+  });
+
+  it("a status object with no submission round: closed, blindness unknown, no deadlines", () => {
+    expect(
+      parseDeadlinesPage(200, 'hotcrp.init_deadlines({"now": 1})'),
+    ).toEqual({
+      ok: true,
+      value: { now: 1, open: false, blind: null, deadlines: [] },
+    });
+  });
+
+  it("a refusal without a page title carries no message", () => {
+    expect(parseDeadlinesPage(503, "<html>down</html>")).toEqual({
+      ok: false,
+      error: { kind: "refused", httpStatus: 503, messages: [] },
+    });
+  });
+
+  it("a site that does not exist: refused with the page's title", () => {
+    expect(parseDeadlinesPage(404, page("nosuch"))).toEqual({
+      ok: false,
+      error: {
+        kind: "refused",
+        httpStatus: 404,
+        messages: [
+          { message: "No such conference", field: null, status: null },
+        ],
+      },
+    });
+  });
+
+  it("a 200 page that is not a deadlines page, and a status object of another shape: malformed", () => {
+    const detail: unknown = expect.stringContaining(
+      "no `hotcrp.init_deadlines(…)` call",
+    );
+    expect(parseDeadlinesPage(200, "<html><body>hello</body></html>")).toEqual({
+      ok: false,
+      error: {
+        kind: "malformed",
+        httpStatus: 200,
+        detail,
+      },
+    });
+    const r = parseDeadlinesPage(200, 'hotcrp.init_deadlines({"sub":1})');
+    expect(r.ok ? "parsed" : r.error.kind).toBe("malformed");
+    const notJson = parseDeadlinesPage(200, "hotcrp.init_deadlines({now: 1})");
+    expect(notJson.ok ? "parsed" : notJson.error.kind).toBe("malformed");
+  });
+});
+
+describe("whatOf", () => {
+  it("names the deadlines paperlint knows by their HotCRP labels, with or without a round name", () => {
+    expect(whatOf("Submission deadline")).toBe("submission");
+    expect(whatOf("Resubmission deadline")).toBe("resubmission");
+    expect(whatOf("Short papers registration deadline")).toBe("registration");
+    expect(whatOf("Final version deadline")).toBe("camera-ready");
+    expect(whatOf("Response deadline")).toBeNull();
+  });
+});

package/src/adapters/hotcrp/deadlines.ts

@@ -0,0 +1,161 @@
+/**
+ * HotCRP's deadlines page (`<site>/deadlines`), parsed at the boundary into paperlint's
+ * `PortalDeadlines`. Pure.
+ *
+ * ── WHAT THE PAGE IS, measured 2026-10-05 on five live sites (`cassette/deadlines-*.html`) ───────
+ * The page is HTML, public, no account needed; the API endpoint of the same name (`/api/deadlines`)
+ * answers 401 «Missing credentials» without a token. The machine-readable part is the argument of
+ * `hotcrp.init_deadlines({…})` in the page's last script: the author's `status_json()`
+ * (kohler/hotcrp, src/contact.php), of which an anonymous visitor gets
+ *
+ *   now            the server's clock, Unix seconds with a fraction
+ *   sub.open       whether the submission round is open now
+ *   sub.sub        the submission deadline, Unix seconds           (SubmissionRound::$submit)
+ *   sub.reg        the registration deadline, when it is earlier   (SubmissionRound::$register)
+ *   sub.blind      true | "optional" | "until-review"              (Conf::submission_blindness)
+ *   final.done     the final-version (camera-ready) deadline       (final_deadline_for_display)
+ *
+ * The RESUBMISSION deadline (updates allowed until, `SubmissionRound::$resubmit`) is not in that
+ * object; the page lists it only in its `<dl>`, each entry a `<dt>` with the deadline's label and a
+ * `<span data-ts="…">` holding the same Unix seconds (pages/p_deadlines.php, `dl1`). So both are
+ * read: the JSON for what it names, the list for every deadline the page shows, matched by label.
+ */
+import { z } from "zod";
+import {
+  instantOfUnix,
+  type DeadlineWhat,
+  type PortalDeadline,
+  type PortalDeadlines,
+} from "../../domain/deadline.ts";
+import { err, ok, type Result } from "../../domain/result.ts";
+import type { PortalFailure } from "../../domain/submission.ts";
+
+const Blind = z.union([
+  z.boolean(),
+  z.literal("optional"),
+  z.literal("until-review"),
+]);
+const Status = z.looseObject({
+  now: z.number(),
+  sub: z
+    .looseObject({
+      open: z.boolean().optional(),
+      sub: z.number().optional(),
+      reg: z.number().optional(),
+      blind: Blind.optional(),
+    })
+    .optional(),
+  final: z.looseObject({ done: z.number().optional() }).optional(),
+});
+
+/** The script call that carries the status object; the argument is JSON. */
+const INIT = /hotcrp\.init_deadlines\((\{.*?\})\)/s;
+/** One listed deadline: its label in `<strong>`, its time in `data-ts`. */
+const ENTRY = /<dt><strong>([^<]*)<\/strong>:\s*<span[^>]*\bdata-ts="(\d+)"/g;
+/** The page's title, for a page that is no deadlines page (a site that does not exist). */
+const TITLE = /<h1 id="h-title">([^<]*)</;
+
+/** What a listed deadline's label names, in paperlint's words; null for one paperlint does not name. */
+export function whatOf(label: string): DeadlineWhat | null {
+  const l = label.toLowerCase();
+  if (/\bresubmission deadline\b/.test(l)) return "resubmission";
+  if (/\bregistration deadline\b/.test(l)) return "registration";
+  if (/\bsubmission deadline\b/.test(l)) return "submission";
+  if (/\bfinal\b|\bcamera[- ]ready\b/.test(l)) return "camera-ready";
+  return null;
+}
+
+/** The deadlines the status object names, each with the label the page would give it. */
+type StatusJson = Readonly<z.infer<typeof Status>>;
+
+function fromStatus(s: StatusJson): readonly PortalDeadline[] {
+  const named: readonly (readonly [DeadlineWhat, number | undefined])[] = [
+    ["registration", s.sub?.reg],
+    ["submission", s.sub?.sub],
+    ["camera-ready", s.final?.done],
+  ];
+  return named.flatMap(([what, at]) =>
+    at === undefined ? [] : [{ what, label: what, at: instantOfUnix(at) }],
+  );
+}
+
+/** Every deadline the page lists, with its label as the page spells it. */
+function fromList(html: string): readonly PortalDeadline[] {
+  return [...html.matchAll(ENTRY)].map((m) => {
+    // Both groups always participate in a match of ENTRY: there is no fallback to take.
+    const label = String(m[1]).trim();
+    return { what: whatOf(label), label, at: instantOfUnix(Number(m[2])) };
+  });
+}
+
+/** Listed entries first (they carry the page's label); a status entry only when the list lacks its kind. */
+function merged(
+  listed: readonly PortalDeadline[],
+  named: readonly PortalDeadline[],
+): readonly PortalDeadline[] {
+  const extra = named.filter(
+    (n) => !listed.some((l) => l.what === n.what && l.at === n.at),
+  );
+  return [...listed, ...extra].toSorted((a, b) => a.at.localeCompare(b.at));
+}
+
+const refused = (httpStatus: number, html: string): PortalFailure => {
+  const title = TITLE.exec(html)?.[1]?.trim();
+  return {
+    kind: "refused",
+    httpStatus,
+    messages:
+      title === undefined
+        ? []
+        : [{ message: title, field: null, status: null }],
+  };
+};
+
+/** The status object in the page's `init_deadlines` call, or why there is none. */
+function statusOf(
+  httpStatus: number,
+  html: string,
+): Result<StatusJson, PortalFailure> {
+  const m = INIT.exec(html);
+  if (m === null)
+    return err({
+      kind: "malformed",
+      httpStatus,
+      detail:
+        "the page has no `hotcrp.init_deadlines(…)` call — not a HotCRP deadlines page",
+    });
+  const json = ((): unknown => {
+    try {
+      return JSON.parse(String(m[1])); // the group always participates in a match of INIT
+    } catch {
+      return undefined;
+    }
+  })();
+  const parsed = Status.safeParse(json);
+  return parsed.success
+    ? ok(parsed.data)
+    : err({
+        kind: "malformed",
+        httpStatus,
+        detail:
+          "the `init_deadlines` argument is not the status object HotCRP documents",
+      });
+}
+
+/** `GET /deadlines` → the portal's deadlines, or why the page is not them. */
+export function parseDeadlinesPage(
+  httpStatus: number,
+  html: string,
+): Result<PortalDeadlines, PortalFailure> {
+  if (httpStatus < 200 || httpStatus >= 300)
+    return err(refused(httpStatus, html));
+  const status = statusOf(httpStatus, html);
+  if (!status.ok) return status;
+  const s = status.value;
+  return ok({
+    now: s.now,
+    open: s.sub?.open ?? false,
+    blind: s.sub?.blind ?? null,
+    deadlines: merged(fromList(html), fromStatus(s)),
+  });
+}

package/src/adapters/hotcrp/index.ts

@@ -9,3 +9,5 @@ export {
   type HotcrpOptions,
 } from "./portal.io.ts";
 export { parseShow, parseUpdate, sha256OfHash } from "./response.ts";
+export { hotcrpDeadlines } from "./deadlines.io.ts";
+export { parseDeadlinesPage, whatOf } from "./deadlines.ts";

package/src/cli.test.ts

@@ -344,6 +344,15 @@ test("no command prints the usage and exits 2; --kind with no value is refused",
   assert.equal(parseArgs(["new", "x", "--kind"]).missingValue, "--kind");
 });
 
+test("--help names the cycles and where a deadline comes from — the only place a newcomer looks first", async () => {
+  const r = await cli(["--help"], root);
+  assert.equal(r.code, 0);
+  assert.match(r.out, /"cycles": \[ \{ "id"/);
+  assert.match(r.out, /A venue preset carries the portal's deadlines/);
+  assert.match(r.out, /"override": \{ "at", "reason", "evidence" \}/);
+  assert.match(r.out, /the earlier reading binds/);
+});
+
 test("src/cli.ts run as the program itself answers like the bin", () => {
   const r = runNode(join(import.meta.dirname, "cli.ts"), ["--help"]);
   assert.equal(r.status, 0);

package/src/cli.ts

@@ -74,6 +74,8 @@ import {
 import {
   FORMAT_RULE_LEVELS,
   formatRules,
+  CYCLE_PORT_RULE_LEVELS,
+  cyclePortRules,
   TEX_VENUE_RULE_LEVELS,
   texVenueRules,
 } from "./tex-venue-rules.ts";
@@ -164,6 +166,8 @@ export { init };
 export { nextSteps } from "./init.ts";
 
 import paperStages from "#eslint-rules/paper-stages";
+import cycleStage from "#eslint-rules/cycle-stage";
+import { CYCLE_RULE_LEVELS, cycleRules } from "./cycle-rules.ts";
 import {
   FOLDER_VENUE_RULE_LEVELS,
   folderVenueRules,
@@ -280,6 +284,24 @@ settings — paperlint.json, at two levels, one schema. Both are optional.
   "extends" names a venue preset: paperlint:<name> (shipped: ${SHIPPED_VENUES().join(", ")})
   or ./path.jsonc, relative to the paperlint.json. npm presets are not supported yet.
 
+  cycles and deadlines — a paper's attempts at venues, oldest first, instead of "extends",
+  "kind" and "submission" (those are then the current attempt's, and refused beside "cycles"):
+
+    { "cycles": [ { "id": "msr-2027", "venue": { "kind": "preset", "extends": "paperlint:msr" },
+                    "kind": "technical", "opened": "2026-10-05",
+                    "deadlines": [ { "what": "submission",
+                                     "observed": [ { "at": "2026-10-23 AoE", "source": "call",
+                                                     "url": "<the call>", "read": "2026-10-05" } ] } ] } ] }
+
+  A venue preset carries the portal's deadlines, read and dated; the package updates them and
+  your dependency update brings them. A paper adds what the call says ("source": "call") and,
+  for a deadline moved by the chairs, "override": { "at", "reason", "evidence" } — evidence a
+  file in the paper folder. The override wins; otherwise the earlier reading binds. "what":
+  registration (the call's abstract), submission (the full paper), resubmission, notification,
+  camera-ready. A venue without a preset: "venue": { "kind": "named", "name", "url" }, every
+  deadline typed from its call. Lint never reads the clock: it checks the record, not the time
+  left. docs/configuration.md#the-papers-cycles
+
   "rules" is { "<rule>": "<severity>" } for every paper file in scope, or ESLint flat-config
   blocks (files, ignores, rules) with globs relative to that file. Order, later wins: paperlint's
   own, the venue preset's, the root file's, the paper's. Optional rules (off unless turned on):
@@ -303,6 +325,22 @@ const REGISTER_AND_CASE_RULES = {
   "heading-case": headingCaseRule(TEX_RULE_DEPS),
 };
 
+/**
+ * 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).
+ * 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. */
+const MARKDOWN_WITH_FRONTMATTER = {
+  language: "markdown/gfm",
+  languageOptions: { frontmatter: "yaml" },
+};
+
+const CYCLE_STATUS_RULES = {
+  ...cycleRules({ files: nodeFiles, venuesDir: presetsDir() }),
+  ...cycleStage.rules,
+};
+
 /** The rules of the files `paper.tex` includes, each read on its own as a fragment (#144). */
 const FRAGMENT_RULES = {
   "future-promise": texBuild["future-promise"],
@@ -333,10 +371,7 @@ export function buildConfig(
     "paper/section-word": "warn",
     "paper/leading-zero": "warn",
   };
-  const md = {
-    language: "markdown/gfm",
-    languageOptions: { frontmatter: "yaml" },
-  };
+  const md = MARKDOWN_WITH_FRONTMATTER;
 
   const cfg: ConfigBlock[] = [
     // 🔴 THE PROJECT'S PAPER TEMPLATE IS NOT A PAPER. `paperlint new` reads `<papers>/.template/`, and
@@ -374,12 +409,14 @@ export function buildConfig(
             ...folderVenueRules({ files: nodeFiles, venuesDir: presetsDir() }),
           },
         },
+        cycle: { rules: CYCLE_STATUS_RULES },
       },
       ...md,
       rules: {
         "paper/stages": "error",
         "paper/source": "error",
         ...FOLDER_VENUE_RULE_LEVELS,
+        ...CYCLE_RULE_LEVELS,
       },
     },
     {
@@ -432,6 +469,7 @@ export function buildConfig(
             ...pageLimitRules({ files: nodeFiles, venuesDir: presetsDir() }),
           },
         },
+        cycle: { rules: cyclePortRules(TEX_RULE_DEPS) },
       },
       language: "tex/latex",
       rules: {
@@ -454,6 +492,7 @@ export function buildConfig(
         ...TEX_VENUE_RULE_LEVELS,
         ...FORMAT_RULE_LEVELS,
         ...PAGE_LIMIT_RULE_LEVELS,
+        ...CYCLE_PORT_RULE_LEVELS,
         // Silent for a paper that declares no `talk` (src/talk-rules.ts), but talk/undeclared.
         ...TALK_RULE_LEVELS,
       },