paperlint 10.4.1 → 11.0.0

package/src/adapters/hotcrp/site.ts

@@ -0,0 +1,34 @@
+/**
+ * A HotCRP site before any token, as the `PortalSite` port: the variable its token is read from,
+ * where on the site an author makes one and with which scopes, what `submission new` leaves to the
+ * site, a submission's page — and the API, once there is a token. Every word here is HotCRP's.
+ */
+import type { PortalSite } from "../../ports/submission-portal.ts";
+import { hotcrpPortal } from "./portal.io.ts";
+import {
+  SITE_LESS_VARIABLE,
+  VARIABLE_PATTERN,
+  tokenVariable,
+} from "./token.ts";
+
+/** The HotCRP site at `url` (no trailing slash). */
+export const hotcrpSite = (url: string): PortalSite => ({
+  tokenVariable: tokenVariable(url),
+  siteLessVariable: SITE_LESS_VARIABLE,
+  variablePattern: VARIABLE_PATTERN,
+  credentials: {
+    // HotCRP's own link to it: `hotlink("Profile > Developer", "profile", ["t" => "developer"])`
+    // (src/help/h_developer.php in kohler/hotcrp).
+    page: `${url}/profile?t=developer`,
+    where: "Account settings → Developer → API tokens",
+    scopes:
+      "submeta:read and document:read (show), submeta:write and document:write (update, new) — tick all four to use every subcommand",
+  },
+  siteOnly: [
+    "PC conflicts (HotCRP's API takes them as pc_conflicts; paperlint does not send them)",
+    "topics, and every field the venue adds (paper type, artifact, consent boxes …)",
+  ],
+  submissionPage: (id) =>
+    `${url}/paper/${id === null ? "<its number>" : String(id)}`,
+  connect: (token) => hotcrpPortal({ url, token }),
+});

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

@@ -0,0 +1,69 @@
+/**
+ * A HotCRP site's token variable — one per site, never shared by two: on the hosted service
+ * (`*.hotcrp.com`) the subdomain, anywhere else the whole host and path.
+ */
+import { map, unique } from "remeda";
+import { expect, test } from "vitest";
+import { tokenVariable } from "./index.ts";
+
+test("tokenVariable: on hotcrp.com the subdomain alone names the site", () => {
+  expect(tokenVariable("https://msr2027.hotcrp.com")).toBe(
+    "HOTCRP_TOKEN_MSR2027",
+  );
+  expect(tokenVariable("https://msr2027.hotcrp.com/")).toBe(
+    "HOTCRP_TOKEN_MSR2027",
+  );
+  expect(tokenVariable("https://ase-2027.hotcrp.com")).toBe(
+    "HOTCRP_TOKEN_ASE_2027",
+  );
+  expect(tokenVariable("msr2027.hotcrp.com")).toBe("HOTCRP_TOKEN_MSR2027");
+});
+
+test("tokenVariable: any other host — the whole host and path, upper-cased, non-alphanumerics as `_`", () => {
+  expect(tokenVariable("https://aidc.submit.acsac.org")).toBe(
+    "HOTCRP_TOKEN_AIDC_SUBMIT_ACSAC_ORG",
+  );
+  expect(tokenVariable("https://hotcrp.example.edu/conf2027")).toBe(
+    "HOTCRP_TOKEN_HOTCRP_EXAMPLE_EDU_CONF2027",
+  );
+  expect(tokenVariable("https://hotcrp.example.edu/conf2027/")).toBe(
+    "HOTCRP_TOKEN_HOTCRP_EXAMPLE_EDU_CONF2027",
+  );
+  expect(tokenVariable("hotcrp.example.edu")).toBe(
+    "HOTCRP_TOKEN_HOTCRP_EXAMPLE_EDU",
+  );
+});
+
+test("tokenVariable: two sites never share a variable — same first label, same last path segment", () => {
+  const sites = [
+    "https://conf.hotcrp.com",
+    "https://conf.example.edu",
+    "https://a.example.edu/conf2027",
+    "https://b.example.edu/conf2027",
+    "https://hotcrp.example.edu/conf2027",
+    "https://hotcrp.example.edu/conf2028",
+  ];
+  const names = map(sites, tokenVariable);
+  expect(unique(names)).toStrictEqual(names);
+});
+
+test("tokenVariable: a port other than the scheme's default is part of the site; the default changes nothing", () => {
+  expect(
+    map(
+      [
+        "https://review.example.org:8443/conf",
+        "https://review.example.org:9443/conf",
+        "https://review.example.org:443/conf",
+        "https://review.example.org/conf",
+        "http://127.0.0.1:9",
+      ],
+      tokenVariable,
+    ),
+  ).toStrictEqual([
+    "HOTCRP_TOKEN_REVIEW_EXAMPLE_ORG_8443_CONF",
+    "HOTCRP_TOKEN_REVIEW_EXAMPLE_ORG_9443_CONF",
+    "HOTCRP_TOKEN_REVIEW_EXAMPLE_ORG_CONF",
+    "HOTCRP_TOKEN_REVIEW_EXAMPLE_ORG_CONF",
+    "HOTCRP_TOKEN_127_0_0_1_9",
+  ]);
+});

package/src/adapters/hotcrp/token.ts

@@ -0,0 +1,51 @@
+/**
+ * WHICH ENVIRONMENT VARIABLE HOLDS A HOTCRP SITE'S API TOKEN — HotCRP's fact, so HotCRP's adapter.
+ * Pure.
+ *
+ * A HotCRP token works on the site it was made on and nowhere else (measured 2026-10-19: a token
+ * made on one HotCRP site gets `401 Unauthorized` from `msr2027.hotcrp.com`'s `/api/whoami`). So the
+ * variable is named after the site, and no two sites share one — `HOTCRP_TOKEN_<subdomain>` on the
+ * hosted service, `HOTCRP_TOKEN_<host and path>` anywhere else — and an author with live submissions
+ * at two venues sets two variables (#236). The site-less `HOTCRP_TOKEN` is no longer read; the policy that refuses it
+ * by name is the domain's (`src/domain/portal-token.ts`).
+ */
+import { hostOf } from "../../domain/portal-token.ts";
+
+/** The site-less variable, read until #236: named when it is still set, never used. */
+export const SITE_LESS_VARIABLE = "HOTCRP_TOKEN";
+
+/** The shape of a site's variable, as a message names it. */
+export const VARIABLE_PATTERN = `${SITE_LESS_VARIABLE}_<LABEL>`;
+
+/** The hosted service, where each conference is a subdomain of its own. */
+const HOSTED = ".hotcrp.com";
+
+/**
+ * What names a site, and no other: on the hosted service the subdomain alone
+ * (`msr2027.hotcrp.com` → `msr2027`); anywhere else the whole host, with a port other than the
+ * scheme's default, and path (`hotcrp.example.edu/conf2027`, `review.example.org:8443/conf`),
+ * because one install may serve several conferences under paths or ports, and two hosts may share a
+ * first label.
+ */
+function siteLabel(url: string): string {
+  const host = hostOf(url);
+  if (host.endsWith(HOSTED)) return host.slice(0, -HOSTED.length);
+  const path = URL.canParse(url) ? new URL(url).pathname : "";
+  return `${host}${path}`;
+}
+
+/**
+ * The variable a HotCRP site's token is read from: `HOTCRP_TOKEN_` and the site's label upper-cased,
+ * every run of characters but letters and digits made one `_`, none at either end.
+ * `https://msr2027.hotcrp.com` → `HOTCRP_TOKEN_MSR2027`; `https://aidc.submit.acsac.org` →
+ * `HOTCRP_TOKEN_AIDC_SUBMIT_ACSAC_ORG`; `https://hotcrp.example.edu/conf2027` →
+ * `HOTCRP_TOKEN_HOTCRP_EXAMPLE_EDU_CONF2027`.
+ */
+export function tokenVariable(url: string): string {
+  const label = siteLabel(url);
+  const name = label
+    .toUpperCase()
+    .replace(/[^A-Z0-9]+/g, "_")
+    .replace(/^_+|_+$/g, "");
+  return `${SITE_LESS_VARIABLE}_${name}`;
+}

package/src/adapters/latex/abstract.test.ts

@@ -0,0 +1,280 @@
+/**
+ * The abstract as plain text, from `\begin{abstract}…\end{abstract}` in the paper's source: the
+ * author's argument-less macros expanded, TeX's ligatures for dashes and quotes, citations and
+ * comments dropped — and anything else refused by name and place, never guessed.
+ */
+import { map } from "remeda";
+import { describe, expect, it } from "vitest";
+import type * as Ast from "@unified-latex/unified-latex-types";
+import { abstractOfTree } from "./abstract.ts";
+import { latexReader } from "./index.ts";
+
+const doc = (preamble: string, abstract: string): string =>
+  `\\documentclass{article}\n${preamble}\n\\begin{document}\n\\begin{abstract}\n${abstract}\n\\end{abstract}\n\\end{document}\n`;
+
+const text = (preamble: string, abstract: string) =>
+  latexReader.abstractText(doc(preamble, abstract));
+
+describe("abstractText — what TeX prints, as plain text", () => {
+  it("words, spaces and paragraphs collapse to one paragraph", () => {
+    expect(text("", "One  line,\nand\n\nanother.")).toEqual({
+      ok: true,
+      value: "One line, and another.",
+    });
+  });
+
+  it("argument-less macros of the author's own are expanded — \\newcommand, \\renewcommand, \\def — nested too", () => {
+    expect(
+      text(
+        "\\newcommand{\\numX}{83}\\renewcommand\\tool{GateBench}\\def\\pct{\\numX\\%}",
+        "\\tool{} blocked \\numX{} attacks (\\pct) and \\tool\\ held.",
+      ),
+    ).toEqual({
+      ok: true,
+      value: "GateBench blocked 83 attacks (83%) and GateBench held.",
+    });
+  });
+
+  it("TeX's ligatures: -- and --- as dashes, `` '' ` ' as curly quotes, ~ as a space", () => {
+    expect(
+      text("", "pages 1--2---done; ``quoted'' and `single', it's~here."),
+    ).toEqual({
+      ok: true,
+      value: "pages 1–2—done; “quoted” and ‘single’, it’s here.",
+    });
+  });
+
+  it("citations and comments are dropped; formatting commands say what their argument says", () => {
+    expect(
+      text(
+        "",
+        "As shown \\cite{a,b} and \\citep[p.~3]{c}, \\emph{this} \\textbf{is} \\texttt{code}. % a comment\nNext.% glued\nOn.",
+      ),
+    ).toEqual({ ok: true, value: "As shown and, this is code. Next.On." });
+  });
+});
+
+describe("abstractText — what prints nothing, a space, or a fixed word", () => {
+  it("a forced line break is a space; a label, a footnote and \\relax print nothing; the logos print their word", () => {
+    expect(
+      text(
+        "",
+        "One\\\\two\\newline three\\label{x}\\footnote{aside}\\relax{} in \\LaTeX.",
+      ),
+    ).toEqual({ ok: true, value: "One two three in LaTeX." });
+  });
+
+  it("commands that only steer line breaking print nothing; a group in math is only grouping", () => {
+    expect(
+      text(
+        "",
+        "long\\allowbreak/word, no\\nobreak\\ break, hy\\-phen, it\\/ and ${\\sim}12{,}345$ items.",
+      ),
+    ).toEqual({
+      ok: true,
+      value: "long/word, no break, hyphen, it and ∼12,345 items.",
+    });
+  });
+
+  it("escaped characters, \\ldots, and math that is only digits and symbols", () => {
+    expect(
+      text(
+        "",
+        "50\\% \\& more\\ldots{} up to $3\\times$ and $\\le 5$ ($p<0.05$).",
+      ),
+    ).toEqual({
+      ok: true,
+      value: "50% & more… up to 3× and ≤ 5 (p<0.05).",
+    });
+  });
+});
+
+describe("abstractText — refused by name and place, never guessed", () => {
+  it("a macro nobody defined", () => {
+    const r = text("", "We use \\toolname{} here.");
+    expect(r.ok ? r : r.error).toMatchObject({
+      kind: "unreadable",
+      what: "\\toolname, which no \\newcommand, \\renewcommand or \\def in the paper defines",
+    });
+  });
+
+  it("a macro that takes arguments — \\newcommand with [n], \\def with #1", () => {
+    const preambles = ["\\newcommand{\\two}[1]{x#1}", "\\def\\two#1{x#1}"];
+    expect(
+      map(preambles, (preamble) => {
+        const r = text(preamble, "See \\two{a}.");
+        return r.ok
+          ? r
+          : {
+              kind: r.error.kind,
+              what: "what" in r.error ? r.error.what : null,
+            };
+      }),
+    ).toStrictEqual(
+      map(preambles, () => ({
+        kind: "unreadable",
+        what: "\\two, which takes arguments",
+      })),
+    );
+  });
+
+  it("math beyond digits and symbols, and any other construct", () => {
+    const math = text("", "Accuracy $\\alpha_i$ rises.");
+    expect(math.ok ? math : math.error).toMatchObject({
+      kind: "unreadable",
+      what: "the math $\\alpha_i$",
+    });
+    const env = text("", "A list:\\begin{itemize}\\item one\\end{itemize}");
+    expect(env.ok ? env : env.error).toMatchObject({
+      kind: "unreadable",
+      what: "the itemize environment",
+    });
+  });
+});
+
+describe("abstractText — where the refusal stands, and what is not read at all", () => {
+  it("the place is the offset of the construct in the source", () => {
+    const src = doc("", "Fine. \\nope{} here.");
+    const r = latexReader.abstractText(src);
+    const at = !r.ok && r.error.kind === "unreadable" ? r.error.at : -1;
+    expect(src.slice(at, at + "\\nope".length)).toBe("\\nope");
+  });
+
+  it("nothing after \\end{document} is read: neither an abstract nor a definition there", () => {
+    expect([
+      latexReader.abstractText(
+        `${doc("\\newcommand{\\x}{a}", "\\x.")}\\def\\x{b}\n\\begin{abstract}late\\end{abstract}\n`,
+      ),
+      latexReader.abstractText(
+        "\\documentclass{article}\\begin{document}Body.\\end{document}\\begin{abstract}x\\end{abstract}",
+      ),
+    ]).toStrictEqual([
+      { ok: true, value: "a." },
+      { ok: false, error: { kind: "none" } },
+    ]);
+  });
+
+  it("no abstract environment: said so", () => {
+    expect(
+      latexReader.abstractText(
+        "\\documentclass{article}\\begin{document}Body.\\end{document}",
+      ),
+    ).toEqual({ ok: false, error: { kind: "none" } });
+  });
+
+  it("a macro defined in terms of itself is refused, not expanded forever", () => {
+    const r = text("\\def\\loop{\\loop}", "A \\loop.");
+    expect(r.ok ? r : r.error).toMatchObject({
+      kind: "unreadable",
+      what: "\\loop, which expands into itself",
+    });
+  });
+});
+
+describe("abstractText — a macro defined more than once is refused, never resolved", () => {
+  const redefined = (preamble: string, abstract: string) => {
+    const src = doc(preamble, abstract);
+    const r = latexReader.abstractText(src);
+    return r.ok || r.error.kind !== "redefined"
+      ? r
+      : { name: r.error.name, at: r.error.at.map((o) => src.slice(o, o + 12)) };
+  };
+
+  it("\\newcommand then \\providecommand (TeX keeps the first), and a \\def again after the abstract", () => {
+    expect([
+      redefined(
+        "\\newcommand{\\x}{old}\\providecommand{\\x}{fallback}",
+        "\\x.",
+      ),
+      redefined(
+        "\\def\\x{old}",
+        "\\x.\n\\end{abstract}\\def\\x{new}\\begin{abstract}",
+      ),
+    ]).toStrictEqual([
+      { name: "x", at: ["\\newcommand{", "\\providecomm"] },
+      { name: "x", at: ["\\def\\x{old}\n", "\\def\\x{new}\\"] },
+    ]);
+  });
+
+  it("a single definition at or after \\begin{abstract} is refused at that definition, not applied backwards", () => {
+    const src = doc(
+      "",
+      "\\today.\n\\end{abstract}\\def\\today{new}\\begin{abstract}",
+    );
+    const r = latexReader.abstractText(src);
+    expect(
+      r.ok || r.error.kind !== "unreadable"
+        ? r
+        : { what: r.error.what, at: src.slice(r.error.at, r.error.at + 11) },
+    ).toStrictEqual({
+      what: "\\today, which the paper defines only after the abstract begins",
+      at: "\\def\\today{",
+    });
+  });
+
+  it("one definition before the abstract, even in a closed group, is expanded", () => {
+    expect(text("{\\gdef\\x{once}}", "\\x.")).toEqual({
+      ok: true,
+      value: "once.",
+    });
+  });
+});
+
+describe("abstractText — the edges of what the source may hold", () => {
+  it("malformed definitions define nothing; an author's macro reads inside math too", () => {
+    expect(
+      text(
+        "\\newcommand{oops}{x}\\newcommand{}{x}\\newcommand{\\half}\\def{y}{z}\\newcommand{\\n}{83}",
+        "We saw $\\n\\%$ of runs.",
+      ),
+    ).toEqual({ ok: true, value: "We saw 83% of runs." });
+  });
+
+  it.each([
+    ["$a@b$", "the math $a@b$"],
+    ["$x^2$", "the math $x^2$"],
+    ["$1 %c\n2$", "the math $1 %c\n2$"],
+    ["\\begin{equation}x\\end{equation}", "the equation environment"],
+    ["\\[x\\]", "the displaymath"],
+  ])("%s is refused as %s", (body, what) => {
+    const r = text("", `See ${body} here.`);
+    expect(r.ok ? r : r.error).toMatchObject({ kind: "unreadable", what });
+  });
+
+  it("a node the parser gave no position is refused at -1, and \\def without arguments defines nothing", () => {
+    const tree: Ast.Root = {
+      type: "root",
+      content: [
+        { type: "macro", content: "def" },
+        {
+          type: "environment",
+          env: "abstract",
+          content: [
+            { type: "inlinemath", content: [{ type: "string", content: "@" }] },
+          ],
+        },
+      ],
+    };
+    expect(abstractOfTree(tree, "")).toEqual({
+      ok: false,
+      error: { kind: "unreadable", what: "the math ", at: -1 },
+    });
+  });
+
+  it("a formatting command the parser gave no argument prints nothing", () => {
+    const tree: Ast.Root = {
+      type: "root",
+      content: [
+        {
+          type: "environment",
+          env: "abstract",
+          content: [
+            { type: "string", content: "A" },
+            { type: "macro", content: "emph" },
+          ],
+        },
+      ],
+    };
+    expect(abstractOfTree(tree, "")).toEqual({ ok: true, value: "A" });
+  });
+});