paperlint 6.2.2 → 6.3.0

package/src/submission.ts

@@ -0,0 +1,311 @@
+/**
+ * `paperlint submission show|update [paper-dir]` — read and change a paper's submission on the
+ * venue's portal, through the portal's API.
+ *
+ * The command is named by the job, not by the portal: WHERE the submission lives is data. The venue
+ * preset declares the portal (`"portal": { "kind": "hotcrp", "url": … }`), the paper's
+ * `paperlint.json` declares which submission is its own (`"submission": { "id": 7 }`), and one
+ * adapter per portal kind does the talking (`src/adapters/hotcrp/`).
+ *
+ *   show     status, id, title, paper type, topics, abstract length, the PDF the portal holds — and
+ *            whether it is the local `paper.pdf`, by sha256
+ *   update   send the PDF (and, if asked, an abstract, or "submitted"). A DRY RUN unless `--save`:
+ *            the portal checks the change and keeps nothing
+ *
+ * 🔴 THE TOKEN IS AN INPUT, AND ONLY AN INPUT. It comes from the environment (the root reads it), is
+ * handed to the adapter, and never appears in anything printed here.
+ */
+import { basename, join, resolve } from "node:path";
+import { absolutePath } from "./domain/paths.ts";
+import { err, ok, type Result } from "./domain/result.ts";
+import { sha256Hex, type Sha256 } from "./domain/sha256.ts";
+import {
+  supportedPortal,
+  wordCount,
+  type PortalFailure,
+  type PortalMessage,
+  type SubmissionView,
+  type SupportedPortal,
+  type UpdateOutcome,
+} from "./domain/submission.ts";
+import type { Files } from "./ports/files.ts";
+import type { SubmissionPortal } from "./ports/submission-portal.ts";
+import { paperPreset, paperPresetProblem, type PresetDeps } from "./presets.ts";
+import { CONFIG_FILE } from "#lib/paper-config";
+
+/** The environment variable each portal kind's token is read from. */
+export const TOKEN_ENV: Readonly<Record<SupportedPortal["kind"], string>> = {
+  hotcrp: "HOTCRP_TOKEN",
+};
+
+/** Where each portal kind lets an author create a token. */
+const TOKEN_HELP: Readonly<Record<SupportedPortal["kind"], string>> = {
+  hotcrp:
+    "create one on the HotCRP site under Account settings → Developer, with the scopes submeta:read and document:read (show) and submeta:write and document:write (update)",
+};
+
+export const SUBCOMMANDS = ["show", "update"] as const;
+export type Subcommand = (typeof SUBCOMMANDS)[number];
+const isSubcommand = (s: string | undefined): s is Subcommand =>
+  SUBCOMMANDS.some((x) => x === s);
+
+/** What one `submission` run was asked, after the command line. */
+export interface SubmissionArgs {
+  readonly sub: string | undefined;
+  readonly paperDir: string;
+  /** Positional arguments past the paper directory: refused. */
+  readonly extra: readonly string[];
+  /** `--pdf <file>`, relative to `cwd`; null: the paper's own PDF. */
+  readonly pdf: string | null;
+  /** `--abstract <file>`, relative to `cwd`; null: leave the abstract as it is. */
+  readonly abstract: string | null;
+  readonly submit: boolean;
+  readonly save: boolean;
+}
+
+export interface SubmissionDeps {
+  readonly files: Files;
+  readonly presets: PresetDeps;
+  readonly cwd: string;
+  /** The value of an environment variable; the root reads the environment. */
+  readonly env: (name: string) => string | undefined;
+  readonly portalFor: (p: SupportedPortal, token: string) => SubmissionPortal;
+  readonly log: (line: string) => void;
+  readonly err: (line: string) => void;
+}
+
+/** A paper's portal, its submission there, and the PDF the paper builds. */
+export interface SubmissionTarget {
+  readonly portal: SupportedPortal;
+  readonly id: number;
+  /** The paper's built PDF, absolute. */
+  readonly pdf: string;
+}
+
+const configOf = (dir: string): string => join(dir, CONFIG_FILE);
+
+/** The paper directory → its portal and submission, or the line naming the file and key to set. */
+export function submissionTarget(
+  paperDir: string,
+  deps: PresetDeps,
+): Result<SubmissionTarget, string> {
+  const p = paperPreset(paperDir, deps);
+  const problem = paperPresetProblem(paperDir, p);
+  if (problem !== null) return err(problem);
+  if (p.kind !== "resolved")
+    return err(
+      `${configOf(paperDir)}: no "extends" — the venue preset it names declares the portal ("portal": { "kind": …, "url": … })`,
+    );
+  const declared = p.preset.portal;
+  if (declared === null)
+    return err(
+      `the venue preset declares no "portal" (read: ${p.preset.chain.join(", ")}) — add "portal": { "kind": "hotcrp", "url": "<the site>" } to the venue's preset, or upload by hand`,
+    );
+  const sub = p.settings.submission;
+  if (sub === null)
+    return err(
+      `${configOf(paperDir)}: no "submission" — add "submission": { "id": <the submission number on ${declared.url}> }`,
+    );
+  const portal = supportedPortal(declared);
+  if (!portal.ok) return portal;
+  const pdf = join(paperDir, p.settings.pdf ?? "paper.pdf");
+  return ok({ portal: portal.value, id: sub.id, pdf });
+}
+
+/** The token from the environment, or the line naming the variable and where to get one. */
+export function tokenFor(
+  portal: SupportedPortal,
+  env: (name: string) => string | undefined,
+): Result<string, string> {
+  const name = TOKEN_ENV[portal.kind];
+  const v = env(name)?.trim();
+  return v
+    ? ok(v)
+    : err(
+        `${name} is not set — the ${portal.kind} API needs a token: ${TOKEN_HELP[portal.kind]}. Then: export ${name}=…`,
+      );
+}
+
+const iso = (seconds: number | null): string =>
+  seconds === null ? "—" : new Date(seconds * 1000).toISOString();
+
+const messageLine = (m: PortalMessage): string =>
+  `  portal says: ${m.field === null ? "" : `${m.field}: `}${m.message}`;
+
+/** A failure in words: HTTP status and the portal's own messages. Never the token. */
+export function failureText(f: PortalFailure): string {
+  switch (f.kind) {
+    case "refused": {
+      const said = f.messages.map((m) => m.message).filter(Boolean);
+      return `the portal refused (HTTP ${String(f.httpStatus)})${said.length ? `: ${said.join("; ")}` : ""}`;
+    }
+    case "unreachable":
+      return `the portal cannot be reached: ${f.detail}`;
+    case "malformed":
+      return `the portal answered HTTP ${String(f.httpStatus)}, but not as its API does: ${f.detail}`;
+  }
+}
+
+/** Whether the portal holds the local build, in one line. */
+function matchLine(view: SubmissionView, local: Sha256 | null): string {
+  if (local === null) return "match         unknown — no local PDF to compare";
+  if (view.pdf === null) return "match         NO — the portal holds no PDF";
+  if (view.pdf.sha256 === null)
+    return `match         unknown — the portal names a ${view.pdf.hash.replace(/-.*$/s, "")} hash, not a sha256`;
+  return view.pdf.sha256 === local
+    ? "match         yes — the portal holds this build"
+    : "match         NO — the portal holds a different PDF than the local one";
+}
+
+const pdfLine = (view: SubmissionView): string =>
+  view.pdf === null
+    ? "portal PDF    none"
+    : `portal PDF    ${view.pdf.hash}, ${view.pdf.size === null ? "?" : String(view.pdf.size)} bytes, uploaded ${iso(view.pdf.uploadedAt)}`;
+
+/** `show`'s report. Pure. */
+export function showLines(
+  t: SubmissionTarget,
+  view: SubmissionView,
+  local: { readonly shown: string; readonly sha256: Sha256 | null },
+): readonly string[] {
+  return [
+    `submission ${String(view.id)} on ${t.portal.url} (${t.portal.kind})`,
+    `status        ${view.status}${view.submittedAt === null ? "" : `, submitted ${iso(view.submittedAt)}`}`,
+    `title         ${view.title ?? "—"}`,
+    `paper type    ${view.paperType ?? "—"}`,
+    `topics        ${view.topics.length ? view.topics.join("; ") : "—"}`,
+    `abstract      ${view.abstract === null ? "—" : `${String(wordCount(view.abstract))} words`}`,
+    pdfLine(view),
+    `local PDF     ${local.shown} ${local.sha256 === null ? "(missing)" : `sha2-${local.sha256}`}`,
+    matchLine(view, local.sha256),
+    ...view.messages.map(messageLine),
+  ];
+}
+
+/** `update`'s report. Pure. */
+export function updateLines(
+  o: UpdateOutcome,
+  local: { readonly shown: string; readonly sha256: Sha256 },
+  save: boolean,
+): readonly string[] {
+  const mode = save
+    ? o.dryRun
+      ? "SAVE WITHHELD by the portal — nothing changed"
+      : "saved"
+    : "dry run — the portal checked the change and kept nothing; --save sends it for real";
+  return [
+    mode,
+    `HTTP          ${String(o.httpStatus)}`,
+    `valid         ${o.valid ? "yes" : "NO"}`,
+    `changes       ${o.changes.length ? o.changes.join(", ") : "—"}`,
+    `local PDF     ${local.shown} sha2-${local.sha256}`,
+    ...o.messages.map(messageLine),
+  ];
+}
+
+const shownPath = (cwd: string, p: string): string =>
+  p.startsWith(`${cwd}/`) ? p.slice(cwd.length + 1) : p;
+
+/** The file's bytes, or null when there is none. */
+const bytesAt = (files: Files, p: string): Uint8Array | null =>
+  files.readBytes(absolutePath(p));
+
+/** `show`: read the submission and compare its PDF with the local one. */
+async function runShow(
+  t: SubmissionTarget,
+  portal: SubmissionPortal,
+  pdfPath: string,
+  deps: SubmissionDeps,
+): Promise<number> {
+  const view = await portal.show(t.id);
+  if (!view.ok) return (deps.err(failureText(view.error)), 1);
+  const bytes = bytesAt(deps.files, pdfPath);
+  const local = {
+    shown: shownPath(deps.cwd, pdfPath),
+    sha256: bytes === null ? null : sha256Hex(bytes),
+  };
+  showLines(t, view.value, local).forEach((l) => {
+    deps.log(l);
+  });
+  return 0;
+}
+
+/** The abstract file's text, or the line saying it is missing; null when none was asked for. */
+function abstractOf(
+  a: SubmissionArgs,
+  deps: SubmissionDeps,
+): Result<string | null, string> {
+  if (a.abstract === null) return ok(null);
+  const p = resolve(deps.cwd, a.abstract);
+  const bytes = bytesAt(deps.files, p);
+  return bytes === null
+    ? err(`--abstract: no file at ${shownPath(deps.cwd, p)}`)
+    : ok(new TextDecoder().decode(bytes).trim());
+}
+
+/** `update`: send the PDF (and the abstract, and "submitted" when asked); a dry run unless saving. */
+async function runUpdate(
+  t: SubmissionTarget,
+  portal: SubmissionPortal,
+  a: SubmissionArgs & { readonly pdfPath: string },
+  deps: SubmissionDeps,
+): Promise<number> {
+  const bytes = bytesAt(deps.files, a.pdfPath);
+  const shown = shownPath(deps.cwd, a.pdfPath);
+  if (bytes === null)
+    return (
+      deps.err(`no PDF at ${shown} — build the paper, or name one with --pdf`),
+      2
+    );
+  const abstract = abstractOf(a, deps);
+  if (!abstract.ok) return (deps.err(abstract.error), 2);
+  const change = {
+    pdf: { name: basename(a.pdfPath), bytes },
+    abstract: abstract.value,
+    submit: a.submit,
+  };
+  const r = await portal.update(t.id, change, { save: a.save });
+  if (!r.ok) return (deps.err(failureText(r.error)), 1);
+  const local = { shown, sha256: sha256Hex(bytes) };
+  updateLines(r.value, local, a.save).forEach((l) => {
+    deps.log(l);
+  });
+  const fine =
+    r.value.valid && r.value.httpStatus >= 200 && r.value.httpStatus < 300;
+  return fine ? 0 : 1;
+}
+
+/** Why the command line cannot be run as asked; null when it can. Pure. */
+export function usageProblem(a: SubmissionArgs): string | null {
+  if (!isSubcommand(a.sub))
+    return `\`submission\` needs a subcommand: ${SUBCOMMANDS.join(" or ")} — got \`${a.sub ?? ""}\``;
+  if (a.extra.length > 0)
+    return `\`submission ${a.sub}\` takes one paper folder — got also \`${a.extra.join(" ")}\``;
+  const updateOnly = [
+    a.abstract === null ? null : "--abstract",
+    a.submit ? "--submit" : null,
+    a.save ? "--save" : null,
+  ].filter((f) => f !== null);
+  return a.sub === "show" && updateOnly.length > 0
+    ? `${updateOnly.join(", ")}: only \`submission update\` changes anything; \`show\` reads`
+    : null;
+}
+
+/** `paperlint submission <show|update> [paper-dir]` — exit 0, 1 (the portal said no), or 2 (usage). */
+export async function runSubmission(
+  a: SubmissionArgs,
+  deps: SubmissionDeps,
+): Promise<number> {
+  const usage = usageProblem(a);
+  if (usage !== null) return (deps.err(usage), 2);
+  const paperDir = resolve(deps.cwd, a.paperDir);
+  const t = submissionTarget(paperDir, deps.presets);
+  if (!t.ok) return (deps.err(t.error), 2);
+  const token = tokenFor(t.value.portal, deps.env);
+  if (!token.ok) return (deps.err(token.error), 2);
+  const portal = deps.portalFor(t.value.portal, token.value);
+  const pdfPath = a.pdf === null ? t.value.pdf : resolve(deps.cwd, a.pdf);
+  return a.sub === "show"
+    ? runShow(t.value, portal, pdfPath, deps)
+    : runUpdate(t.value, portal, { ...a, pdfPath }, deps);
+}

package/src/tex-requirements.ts

@@ -34,6 +34,7 @@ import {
   type VenueTalk,
   type VenueTalkJson,
 } from "./domain/talk.ts";
+import type { VenuePortal } from "./domain/submission.ts";
 
 /** CTAN package name → the names that prove it is installed. */
 export type PackageProofs = Readonly<Record<string, readonly string[]>>;
@@ -193,6 +194,8 @@ export interface PresetFile {
   readonly registerAnchors: readonly RegisterAnchor[] | null;
   /** What the venue asks a presenter to send; null when the file has no `talk` block. */
   readonly talk: VenueTalk | null;
+  /** Where the venue takes submissions (`paperlint submission`); null when the file does not say. */
+  readonly portal: VenuePortal | null;
 }
 
 type KindsJson = Readonly<
@@ -237,6 +240,7 @@ interface PresetJson {
     } & Readonly<Record<RegisterMeasureName, number>>)[];
   };
   readonly talk?: VenueTalkJson;
+  readonly portal?: VenuePortal;
 }
 
 /** An optional field as the typed preset holds it: absent is null. */
@@ -342,6 +346,10 @@ export function parsePreset(
     rules: j.rules ?? {},
     registerAnchors: anchorsOf(j.register),
     talk: j.talk === undefined ? null : venueTalkOf(j.talk),
+    portal:
+      j.portal === undefined
+        ? null
+        : { kind: j.portal.kind, url: j.portal.url },
   };
 }
 

package/src/tex-venue-rules.test.ts

@@ -719,7 +719,7 @@ describe("otherVenues", () => {
     const aidc = resolvePreset("paperlint:aidc", from, deps);
     expect(aidc.ok).toBe(true);
     if (!aidc.ok) return;
-    expect(otherVenues(aidc.value, from, deps).map((o) => o.label)).toEqual([
+    expect(otherVenues(aidc.value, deps).map((o) => o.label)).toEqual([
       "acm-sigconf",
       "agenticdev",
       "aisec",

package/src/tex-venue-rules.ts

@@ -27,8 +27,7 @@
  * `pdf/profile` already say so, once. A preset that names no template: silent — there is nothing to
  * compare, and a template-family preset is where it is named.
  */
-import { basename, dirname, join } from "node:path";
-import { CONFIG_FILE } from "#lib/paper-config";
+import { basename, dirname } from "node:path";
 import {
   collapse,
   documentClassLine,
@@ -46,13 +45,8 @@ import {
   type TextRun,
 } from "./domain/tex-document.ts";
 import type { LatexReader } from "./ports/latex.ts";
-import {
-  paperPreset,
-  resolvePreset,
-  SHIPPED_PREFIX,
-  shippedPresets,
-  type Preset,
-} from "./presets.ts";
+import { paperPreset, shippedVenueNames, type Preset } from "./presets.ts";
+import type { NamedVenue } from "./domain/venue-name.ts";
 import type { PaperSource } from "./domain/paper-source.ts";
 import { readPaper, reportInPaper } from "./tex-paper.ts";
 import type { RequiredSection } from "./tex-requirements.ts";
@@ -255,10 +249,7 @@ export function judgeRequiredSections(
 }
 
 /** Another shipped venue: the word for it, and what it is called in a paper's text. */
-export interface OtherVenue {
-  readonly label: string;
-  readonly aliases: readonly string[];
-}
+export type OtherVenue = NamedVenue;
 
 /** `s` as a pattern that matches it literally. */
 const literal = (s: string): string =>
@@ -440,21 +431,17 @@ export const FORMAT_RULE_LEVELS: Readonly<
 };
 
 /**
- * Every shipped venue but the ones on this paper's own chain, each resolved the way a paper
- * extending it would be. A preset that does not resolve is skipped: `pdf/profile` owns that.
+ * Every shipped venue but the ones on this paper's own chain, from the one source of venue names
+ * (`shippedVenueNames`). A preset all of whose files are on this paper's chain is this venue or one
+ * it extends.
  */
 export function otherVenues(
-  preset: Preset,
-  fromFile: string,
+  preset: Pick<Preset, "chain">,
   deps: VenueRuleDeps,
 ): readonly OtherVenue[] {
-  return shippedPresets(deps.venuesDir).flatMap((name) => {
-    const r = resolvePreset(`${SHIPPED_PREFIX}${name}`, fromFile, deps);
-    // A preset all of whose files are on this paper's chain is this venue or one it extends.
-    return r.ok && !r.value.chain.every((f) => preset.chain.includes(f))
-      ? [{ label: r.value.label, aliases: r.value.aliases }]
-      : [];
-  });
+  return shippedVenueNames(deps)
+    .filter((v) => !v.chain.every((f) => preset.chain.includes(f)))
+    .map(({ label, aliases }) => ({ label, aliases }));
 }
 
 /** What the venue-conformance rules are built with: the preset store, and the LaTeX reader. */
@@ -476,7 +463,7 @@ function readingOf(
   const p = paperPreset(dir, deps);
   if (p.kind !== "resolved") return null;
   const preset = p.preset;
-  const others = () => otherVenues(preset, join(dir, CONFIG_FILE), deps);
+  const others = () => otherVenues(preset, deps);
   const paper = readPaper(filename, src, deps);
   return {
     reading: { src: paper.text, latex: deps.latex, preset, others },

package/src/types.ts

@@ -68,6 +68,19 @@ export interface Args {
   venue: string | null;
   /** `--kind <kind>` for `new`: one of the venue preset's kinds. */
   kind: string | null;
+  /** `--pdf <file>` for `submission`: the PDF to compare or send; null is the paper's own. */
+  pdf: string | null;
+  /** `--abstract <file>` for `submission update`: a plain-text abstract to send. */
+  abstract: string | null;
+  /** `--submit` for `submission update`: mark the submission submitted. */
+  submit: boolean;
+  /** `--save` for `submission update`: really change the submission; without it, a dry run. */
+  save: boolean;
+  /**
+   * `--allow-venue-name` for `new`: create the folder even though its name names a venue. Skips
+   * that one refusal and no other.
+   */
+  allowVenueName: boolean;
   /** `--hooks=<mode>` — parsed only so it can be REFUSED by name rather than read as a path. */
   hooksMode: string | null;
   help?: boolean;