paperlint 6.2.3 → 6.3.0

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

@@ -0,0 +1,503 @@
+/**
+ * The HotCRP adapter against a local HTTP server on 127.0.0.1 — no real portal, no network. The
+ * server records each request whole (method, path, query, headers, body), so the tests assert what
+ * HotCRP would receive, and answers with what HotCRP documents.
+ */
+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 { fieldOf } from "../../domain/record.ts";
+import { sha256Hex } from "../../domain/sha256.ts";
+import type { SubmissionChange } from "../../domain/submission.ts";
+import {
+  CONTENT_FIELD,
+  changeObject,
+  hotcrpPortal,
+  parseShow,
+  parseUpdate,
+  sha256OfHash,
+} from "./index.ts";
+
+interface Seen {
+  readonly method: string;
+  readonly url: URL;
+  readonly headers: IncomingMessage["headers"];
+  readonly body: Buffer;
+}
+
+interface Reply {
+  readonly status: number;
+  readonly body: string;
+  readonly type?: string;
+}
+
+const seen: Seen[] = [];
+let reply: Reply = { status: 200, body: "{}" };
+let base = "";
+
+const server = createServer((req: IncomingMessage, res: ServerResponse) => {
+  const chunks: Buffer[] = [];
+  req.on("data", (c: Buffer) => chunks.push(c));
+  req.on("end", () => {
+    const s: Seen = {
+      method: req.method ?? "",
+      url: new URL(req.url ?? "/", "http://127.0.0.1"),
+      headers: req.headers,
+      body: Buffer.concat(chunks),
+    };
+    seen.push(s);
+    const answer = ignoredDocument(s) ?? reply;
+    res.writeHead(
+      answer.status,
+      answer.type === ""
+        ? {}
+        : { "content-type": answer.type ?? "application/json" },
+    );
+    res.end(answer.body);
+  });
+});
+
+/** The port a listening server was given. */
+/**
+ * What HotCRP answers when `submission.content_file` names no uploaded file — as its source does
+ * (kohler/hotcrp, read 2026-10-03): `DocumentLocator::on_document_import` looks the name up with
+ * `Qrequest::file()`, which holds `$_FILES` as PHP built it, and PHP renames a dot or a space in a
+ * form field's name to `_` there. A part without a filename is a plain field, not a file. When the
+ * lookup misses, `DocumentImporter` reports "Ignored attempt to upload document without any
+ * content" and the change is not valid — measured on a real HotCRP with the field `paper.pdf`.
+ */
+/** A recorded HotCRP answer (`cassette/README.md`), as the text it was sent as. */
+function cassette(
+  name: "get-paper" | "get-noauth" | "post-dot" | "post-ok",
+): string {
+  return readFileSync(
+    new URL(`./cassette/${name}.json`, import.meta.url),
+    "utf8",
+  );
+}
+const parsed = (name: Parameters<typeof cassette>[0]): unknown =>
+  JSON.parse(cassette(name));
+
+function ignoredDocument(s: Seen): Reply | null {
+  if (!String(s.headers["content-type"]).startsWith("multipart/form-data"))
+    return null;
+  const parts = partsOf(s);
+  const json: unknown = JSON.parse(
+    parts.get("json")?.body.toString("utf8") ?? "{}",
+  );
+  const named = fieldOf(fieldOf(json, "submission"), "content_file");
+  const files = [...parts]
+    .filter(([, p]) => /filename="/.test(p.headers))
+    .map(([name]) => name.replace(/[. ]/g, "_"));
+  if (typeof named !== "string" || files.includes(named)) return null;
+  return { status: 200, body: cassette("post-dot") };
+}
+
+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();
+    });
+  });
+
+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));
+
+const TOKEN = "hct_test_token";
+const answer = (status: number, body: unknown): void => {
+  seen.length = 0;
+  reply = { status, body: JSON.stringify(body) };
+};
+const portal = () => hotcrpPortal({ url: base, token: TOKEN });
+const last = (): Seen => {
+  const s = seen.at(-1);
+  assert.ok(s, "the server saw no request");
+  return s;
+};
+
+const PDF = new TextEncoder().encode("%PDF-1.5 fake bytes");
+const HEX = sha256Hex(PDF);
+const CASSETTE_HEX =
+  "b3e602c135f2455f64aecfdc2e1e7f81dad20c5d69f0981e965b1a0131d47163";
+
+interface Part {
+  readonly headers: string;
+  readonly body: Buffer;
+}
+
+/**
+ * The multipart body split into its parts by the boundary its content type names — the way a
+ * server reads it, small enough to read here rather than trust a library's parser.
+ */
+function partsOf(s: Seen): ReadonlyMap<string, Part> {
+  const boundary = /boundary=(.+)$/.exec(s.headers["content-type"] ?? "")?.[1];
+  assert.ok(boundary, "not a multipart body");
+  const text = s.body.toString("latin1");
+  const parts = text.split(`--${boundary}`).slice(1, -1);
+  return new Map(
+    parts.map((raw) => {
+      const [headers = "", ...rest] = raw.slice(2, -2).split("\r\n\r\n");
+      const name = /name="([^"]*)"/.exec(headers)?.[1] ?? "";
+      return [
+        name,
+        { headers, body: Buffer.from(rest.join("\r\n\r\n"), "latin1") },
+      ];
+    }),
+  );
+}
+
+test("show: GET /api/paper?p=<id>&word_limit=hard with the bearer token, parsed whole", async () => {
+  seen.length = 0;
+  reply = { status: 200, body: cassette("get-paper") };
+  const r = await portal().show(7);
+  const s = last();
+  assert.equal(s.method, "GET");
+  assert.equal(s.url.pathname, "/api/paper");
+  assert.deepEqual(Object.fromEntries(s.url.searchParams), {
+    p: "7",
+    word_limit: "hard",
+  });
+  assert.equal(s.headers.authorization, `bearer ${TOKEN}`);
+  assert.deepEqual(r, {
+    ok: true,
+    value: {
+      id: 7,
+      status: "submitted",
+      title: "An Example Paper Title",
+      paperType: "Example paper type",
+      topics: ["Example topic one", "Example topic two"],
+      abstract: "An example abstract of exactly ten words for the test.",
+      pdf: {
+        sha256: CASSETTE_HEX,
+        hash: `sha2-${CASSETTE_HEX}`,
+        size: 17,
+        mimetype: "application/pdf",
+        uploadedAt: 1_790_000_000,
+      },
+      submittedAt: 1_790_000_100,
+      modifiedAt: 1_790_000_100,
+      messages: [],
+    },
+  });
+});
+
+test("show: a submission without a PDF, fields absent, a paper type that is not a string", async () => {
+  answer(200, {
+    ok: true,
+    paper: {
+      pid: 7,
+      status: "draft",
+      paper_type: 2,
+      submission: { hash: "sha2-short" },
+    },
+    message_list: [{ message: "note", field: "title", status: 1 }, {}],
+  });
+  assert.deepEqual(await portal().show(7), {
+    ok: true,
+    value: {
+      id: 7,
+      status: "draft",
+      title: null,
+      paperType: "2",
+      topics: [],
+      abstract: null,
+      pdf: {
+        sha256: null,
+        hash: "sha2-short",
+        size: null,
+        mimetype: null,
+        uploadedAt: null,
+      },
+      submittedAt: null,
+      modifiedAt: null,
+      messages: [{ message: "note", field: "title", status: 1 }],
+    },
+  });
+});
+
+test("show: a null paper type and a null submission read as none", async () => {
+  answer(200, {
+    ok: true,
+    paper: { pid: 7, status: "draft", paper_type: null, submission: null },
+  });
+  const r = await portal().show(7);
+  assert.deepEqual(r.ok && [r.value.paperType, r.value.pdf], [null, null]);
+});
+
+test("🔴 show: 401 surfaces HotCRP's own message, and the token is in no part of it", async () => {
+  seen.length = 0;
+  reply = { status: 401, body: cassette("get-noauth") };
+  const r = await portal().show(7);
+  assert.deepEqual(r, {
+    ok: false,
+    error: {
+      kind: "refused",
+      httpStatus: 401,
+      messages: [{ message: "Missing credentials", field: null, status: 2 }],
+    },
+  });
+  // Guards: the token never travels into what the caller prints.
+  assert.doesNotMatch(JSON.stringify(r), new RegExp(TOKEN));
+});
+
+const CHANGE: SubmissionChange = {
+  pdf: { name: "paper.pdf", bytes: PDF },
+  abstract: "new abstract",
+  submit: true,
+};
+
+test("update: a dry run by default — dry_run=1, the json field, the PDF under its content_file name", async () => {
+  seen.length = 0;
+  reply = { status: 200, body: cassette("post-ok") };
+  const r = await portal().update(7, CHANGE, { save: false });
+  const s = last();
+  assert.equal(s.method, "POST");
+  assert.equal(s.url.pathname, "/api/paper");
+  assert.deepEqual(Object.fromEntries(s.url.searchParams), {
+    p: "7",
+    dry_run: "1",
+  });
+  assert.equal(s.headers.authorization, `bearer ${TOKEN}`);
+  const parts = partsOf(s);
+  assert.deepEqual([...parts.keys()], ["json", CONTENT_FIELD]);
+  assert.deepEqual(JSON.parse(parts.get("json")?.body.toString("utf8") ?? ""), {
+    object: "paper",
+    pid: 7,
+    submission: { content_file: CONTENT_FIELD },
+    abstract: "new abstract",
+    status: "submitted",
+  });
+  const file = parts.get(CONTENT_FIELD);
+  assert.match(file?.headers ?? "", /filename="paper\.pdf"/);
+  assert.match(file?.headers ?? "", /Content-Type: application\/pdf/i);
+  assert.deepEqual(new Uint8Array(file?.body ?? []), PDF);
+  assert.deepEqual(r, {
+    ok: true,
+    value: {
+      httpStatus: 200,
+      valid: true,
+      changes: ["submission"],
+      messages: [],
+      dryRun: true,
+    },
+  });
+});
+
+test("🔴 the mock is HotCRP here: a file part named with a dot is not found under that name", async () => {
+  // Guards: the rule the dry-run test relies on FIRES — the form a real HotCRP refused.
+  answer(200, { ok: true, valid: true, change_list: ["submission"] });
+  const form = new FormData();
+  form.append(
+    "json",
+    JSON.stringify({
+      object: "paper",
+      pid: 7,
+      submission: { content_file: "paper.pdf" },
+    }),
+  );
+  form.append(
+    "paper.pdf",
+    new Blob([PDF], { type: "application/pdf" }),
+    "paper.pdf",
+  );
+  const r = await fetch(`${base}/api/paper?p=7&dry_run=1`, {
+    method: "POST",
+    body: form,
+  });
+  const body: unknown = await r.json();
+  assert.equal(fieldOf(body, "valid"), false);
+});
+
+test("the PDF's field name survives PHP's renaming of form fields: no dot, space or bracket", () => {
+  assert.doesNotMatch(CONTENT_FIELD, /[. [\]]/);
+});
+
+test("update with save: no dry_run parameter at all", async () => {
+  answer(200, { ok: true, valid: true, pid: 7 });
+  const r = await portal().update(7, CHANGE, { save: true });
+  assert.deepEqual(Object.fromEntries(last().url.searchParams), { p: "7" });
+  assert.deepEqual(r, {
+    ok: true,
+    value: {
+      httpStatus: 200,
+      valid: true,
+      changes: [],
+      messages: [],
+      dryRun: false,
+    },
+  });
+});
+
+test("update: valid:false is an outcome with HotCRP's messages, at any HTTP status", async () => {
+  answer(400, {
+    ok: false,
+    valid: false,
+    change_list: ["submission"],
+    message_list: [{ field: "submission", message: "Bad PDF", status: 2 }],
+  });
+  assert.deepEqual(await portal().update(7, CHANGE, { save: false }), {
+    ok: true,
+    value: {
+      httpStatus: 400,
+      valid: false,
+      changes: ["submission"],
+      messages: [{ message: "Bad PDF", field: "submission", status: 2 }],
+      dryRun: false,
+    },
+  });
+});
+
+test("update: 403 without a verdict is a refusal with the messages", async () => {
+  answer(403, {
+    ok: false,
+    message_list: [{ message: "Token scope does not allow this" }],
+  });
+  assert.deepEqual(await portal().update(7, CHANGE, { save: false }), {
+    ok: false,
+    error: {
+      kind: "refused",
+      httpStatus: 403,
+      messages: [
+        {
+          message: "Token scope does not allow this",
+          field: null,
+          status: null,
+        },
+      ],
+    },
+  });
+});
+
+test("an answer that is not JSON, or JSON that is no answer, is malformed — not a pass", async () => {
+  seen.length = 0;
+  reply = { status: 200, body: "<html>login</html>", type: "text/html" };
+  assert.deepEqual(await portal().show(7), {
+    ok: false,
+    error: {
+      kind: "malformed",
+      httpStatus: 200,
+      detail: "the answer is not JSON (text/html)",
+    },
+  });
+  answer(200, { ok: true });
+  assert.deepEqual(await portal().show(7), {
+    ok: false,
+    error: {
+      kind: "malformed",
+      httpStatus: 200,
+      detail: "the answer has no submission in `paper`",
+    },
+  });
+  answer(200, { ok: true });
+  assert.deepEqual(await portal().update(7, CHANGE, { save: false }), {
+    ok: false,
+    error: {
+      kind: "malformed",
+      httpStatus: 200,
+      detail: "the answer has no `valid`",
+    },
+  });
+  seen.length = 0;
+  reply = { status: 502, body: "bad gateway", type: "" };
+  assert.deepEqual(await portal().show(7), {
+    ok: false,
+    error: {
+      kind: "malformed",
+      httpStatus: 502,
+      detail: "the answer is not JSON (no content type)",
+    },
+  });
+  answer(500, "oops");
+  const r = await portal().show(7);
+  assert.deepEqual(r, {
+    ok: false,
+    error: { kind: "refused", httpStatus: 500, messages: [] },
+  });
+});
+
+test("a portal 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 down = hotcrpPortal({
+    url: `http://127.0.0.1:${String(port)}`,
+    token: TOKEN,
+  });
+  for (const r of [
+    await down.show(7),
+    await down.update(7, CHANGE, { save: false }),
+  ]) {
+    assert.equal(!r.ok && r.error.kind, "unreachable");
+    assert.ok(!r.ok && r.error.kind === "unreachable" && r.error.detail !== "");
+  }
+});
+
+test("changeObject: only what changes is sent", () => {
+  assert.deepEqual(
+    changeObject(7, { pdf: null, abstract: null, submit: false }),
+    { object: "paper", pid: 7 },
+  );
+});
+
+test("sha256OfHash: sha2-<hex> is a sha256; any other hash is not claimed to be one", () => {
+  assert.equal(sha256OfHash(`sha2-${HEX}`), HEX);
+  assert.equal(sha256OfHash("da39a3ee5e6b4b0d3255bfef95601890afd80709"), null);
+  assert.equal(sha256OfHash(`sha2-${HEX.toUpperCase()}`), null);
+});
+
+test("🔴 every recorded HotCRP answer parses through the real schemas, into what it means", () => {
+  // Guards: a schema that rejects a real answer — the class a hand-written body cannot show.
+  assert.equal(parseShow(200, parsed("get-paper")).ok, true);
+  const refused = {
+    ok: false,
+    error: {
+      kind: "refused",
+      httpStatus: 401,
+      messages: [{ message: "Missing credentials", field: null, status: 2 }],
+    },
+  };
+  assert.deepEqual(parseShow(401, parsed("get-noauth")), refused);
+  // The body's own `status_code` decides when the transport says 2xx.
+  assert.deepEqual(parseShow(200, parsed("get-noauth")), refused);
+  assert.deepEqual(parseUpdate(200, parsed("post-dot")), {
+    ok: true,
+    value: {
+      httpStatus: 200,
+      valid: false,
+      changes: [],
+      messages: [
+        {
+          message: "Ignored attempt to upload document without any content",
+          field: "submission",
+          status: 2,
+        },
+      ],
+      dryRun: true,
+    },
+  });
+  assert.deepEqual(parseUpdate(200, parsed("post-ok")), {
+    ok: true,
+    value: {
+      httpStatus: 200,
+      valid: true,
+      changes: ["submission"],
+      messages: [],
+      dryRun: true,
+    },
+  });
+});

package/src/adapters/hotcrp/response.ts

@@ -0,0 +1,181 @@
+/**
+ * HotCRP's answers, parsed at the boundary into paperlint's submission values. Pure.
+ *
+ * Only the fields the command uses are read; every other key HotCRP sends is dropped here. The field
+ * names are HotCRP's (`devel/openapi.json` and `devel/apidoc/submissions.md` in kohler/hotcrp):
+ * `GET /api/paper` answers `{ ok, paper, message_list? }`, `POST /api/paper` answers
+ * `{ ok, valid, change_list, message_list, dry_run?, pid }`. A document's `hash` is
+ * `sha2-<64 hex>` when HotCRP stored a sha256; timestamps are Unix seconds.
+ */
+import { z } from "zod";
+import { err, ok, type Result } from "../../domain/result.ts";
+import { parseSha256, type Sha256 } from "../../domain/sha256.ts";
+import type {
+  PortalDocument,
+  PortalFailure,
+  PortalMessage,
+  SubmissionView,
+  UpdateOutcome,
+} from "../../domain/submission.ts";
+
+const Message = z.object({
+  message: z.string().optional(),
+  field: z.string().optional(),
+  status: z.number().optional(),
+});
+const Messages = z.array(Message).optional();
+
+const Document = z.object({
+  hash: z.string().optional(),
+  size: z.number().optional(),
+  mimetype: z.string().optional(),
+  timestamp: z.number().optional(),
+});
+
+const Paper = z.object({
+  pid: z.number(),
+  status: z.string(),
+  title: z.string().optional(),
+  abstract: z.string().optional(),
+  paper_type: z.unknown().optional(),
+  topics: z.array(z.string()).optional(),
+  submission: Document.nullable().optional(),
+  submitted_at: z.number().optional(),
+  modified_at: z.number().optional(),
+});
+
+const ShowBody = z.object({
+  ok: z.literal(true),
+  paper: Paper,
+  message_list: Messages,
+});
+
+const UpdateBody = z.object({
+  valid: z.boolean(),
+  change_list: z.array(z.string()).optional(),
+  message_list: Messages,
+  dry_run: z.boolean().optional(),
+});
+
+const Envelope = z.object({ message_list: Messages });
+
+const SHA2 = /^sha2-([0-9a-f]{64})$/;
+
+/** HotCRP's `sha2-<hex>` → the sha256; null for any other hash it may name. */
+export function sha256OfHash(hash: string): Sha256 | null {
+  const hex = SHA2.exec(hash)?.[1];
+  return hex === undefined ? null : parseSha256(hex);
+}
+
+/** HotCRP prefixes a message with its format (`<0>` plain text, `<5>` HTML); the text is the rest. */
+const textOf = (message: string | undefined): string =>
+  (message ?? "").replace(/^<\d+>/, "").trim();
+
+/** The messages that say something: HotCRP also sends entries with no text, which print as blanks. */
+const messagesOf = (
+  list: Readonly<z.infer<typeof Messages>>,
+): readonly PortalMessage[] =>
+  (list ?? [])
+    .map((m) => ({
+      message: textOf(m.message),
+      field: m.field ?? null,
+      status: m.status ?? null,
+    }))
+    .filter((m) => m.message !== "");
+
+const documentOf = (
+  d: Readonly<z.infer<typeof Document>> | null | undefined,
+): PortalDocument | null =>
+  d?.hash === undefined
+    ? null
+    : {
+        sha256: sha256OfHash(d.hash),
+        hash: d.hash,
+        size: d.size ?? null,
+        mimetype: d.mimetype ?? null,
+        uploadedAt: d.timestamp ?? null,
+      };
+
+/** A paper type as text: HotCRP sends the option's name, or a value of another shape. */
+const typeText = (v: unknown): string | null =>
+  v === undefined || v === null
+    ? null
+    : typeof v === "string"
+      ? v
+      : JSON.stringify(v);
+
+function viewOf(b: Readonly<z.infer<typeof ShowBody>>): SubmissionView {
+  const p = b.paper;
+  return {
+    id: p.pid,
+    status: p.status,
+    title: p.title ?? null,
+    paperType: typeText(p.paper_type),
+    topics: p.topics ?? [],
+    abstract: p.abstract ?? null,
+    pdf: documentOf(p.submission),
+    submittedAt: p.submitted_at ?? null,
+    modifiedAt: p.modified_at ?? null,
+    messages: messagesOf(b.message_list),
+  };
+}
+
+const is2xx = (status: number): boolean => status >= 200 && status < 300;
+
+const StatusCode = z.object({ status_code: z.number() });
+
+/**
+ * The status HotCRP meant. Its error envelope repeats the status in the body (`status_code: 401`
+ * beside `ok: false`, recorded in `cassette/get-noauth.json`); when something between us and HotCRP
+ * turns the transport status into a 2xx, the body's code still decides.
+ */
+function statusOf(transport: number, body: unknown): number {
+  const c = StatusCode.safeParse(body);
+  return is2xx(transport) && c.success ? c.data.status_code : transport;
+}
+
+/** A body that is no answer of HotCRP's: the portal's messages when it sent any, else "malformed". */
+function refusal(
+  httpStatus: number,
+  body: unknown,
+  what: string,
+): PortalFailure {
+  const e = Envelope.safeParse(body);
+  const messages = e.success ? messagesOf(e.data.message_list) : [];
+  return messages.length > 0 || !is2xx(httpStatus)
+    ? { kind: "refused", httpStatus, messages }
+    : { kind: "malformed", httpStatus, detail: what };
+}
+
+/** `GET /api/paper` → the submission, or why there is none. */
+export function parseShow(
+  httpStatus: number,
+  body: unknown,
+): Result<SubmissionView, PortalFailure> {
+  const status = statusOf(httpStatus, body);
+  const b = ShowBody.safeParse(body);
+  return b.success && is2xx(status)
+    ? ok(viewOf(b.data))
+    : err(refusal(status, body, "the answer has no submission in `paper`"));
+}
+
+/**
+ * `POST /api/paper` → the outcome, valid or not. A body carrying `valid` is HotCRP's verdict on
+ * the change whatever the HTTP status; the caller decides the exit from both.
+ */
+export function parseUpdate(
+  httpStatus: number,
+  body: unknown,
+): Result<UpdateOutcome, PortalFailure> {
+  const status = statusOf(httpStatus, body);
+  const b = UpdateBody.safeParse(body);
+  if (!b.success)
+    return err(refusal(status, body, "the answer has no `valid`"));
+  return ok({
+    httpStatus: status,
+    valid: b.data.valid,
+    changes: b.data.change_list ?? [],
+    messages: messagesOf(b.data.message_list),
+    dryRun: b.data.dry_run ?? false,
+  });
+}