paperlint 6.2.3 → 7.0.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/talk-rules.test.ts

@@ -23,7 +23,7 @@ import {
   talkRules,
   type TalkRuleName,
 } from "./talk-rules.ts";
-import { useTempDir, writeTree } from "../test/support.ts";
+import { useTempDir, venuePreset, writeTree } from "../test/support.ts";
 
 const ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
 const media = (name: string): Uint8Array =>
@@ -62,8 +62,11 @@ function run(
   const dir = useTempDir("paperlint-talk-rules-");
   const venue =
     o.venue === null
-      ? { extends: "paperlint:acm-sigconf" }
-      : { extends: "paperlint:agenticdev", talk: { ...VENUE, ...o.venue } };
+      ? { type: "family", extends: "paperlint:acm-sigconf" }
+      : venuePreset("venue", {
+          extends: "paperlint:agenticdev",
+          talk: { ...VENUE, ...o.venue },
+        });
   writeTree(dir, {
     "package.json": "{}",
     "p/paper.tex": "x",

package/src/tex-requirements.harness.ts

@@ -130,32 +130,40 @@ copyFileSync(join(VENUES, R.SCHEMA_FILE), join(tmp, R.SCHEMA_FILE));
 const bad = (text: string) =>
   throws(() => R.parseProfile(text, "bad.jsonc", tmp));
 const BAD: [string, string, string][] = [
-  ["no `tex` block at all", `{ "template": "acmart" }`, "tex"],
+  [
+    "no `tex` block at all",
+    `{ "type": "family", "template": "acmart" }`,
+    "tex",
+  ],
   // Guards: typo detection — `templat` would be accepted and the field silently unread.
   [
     "an unknown top-level key (a typo)",
-    `{ "tex": { "packages": { "a": ["a.sty"] } }, "templat": "x" }`,
+    `{ "type": "family", "tex": { "packages": { "a": ["a.sty"] } }, "templat": "x" }`,
     "additional properties",
   ],
   [
     "a package with NO proof file",
-    `{ "tex": { "packages": { "acmart": [] } } }`,
+    `{ "type": "family", "tex": { "packages": { "acmart": [] } } }`,
     ".tex.packages['acmart']",
   ],
   [
     "a package name tlmgr would not know (upper case)",
-    `{ "tex": { "packages": { "Acmart": ["acmart.cls"] } } }`,
+    `{ "type": "family", "tex": { "packages": { "Acmart": ["acmart.cls"] } } }`,
     "property name",
   ],
   [
     "a proof that is a path, not a file name",
-    `{ "tex": { "packages": { "a": ["tex/a.sty"] } } }`,
+    `{ "type": "family", "tex": { "packages": { "a": ["tex/a.sty"] } } }`,
     "pattern",
   ],
-  ["an empty packages map", `{ "tex": { "packages": {} } }`, "fewer than 1"],
+  [
+    "an empty packages map",
+    `{ "type": "family", "tex": { "packages": {} } }`,
+    "fewer than 1",
+  ],
   [
     "an unknown key inside tex",
-    `{ "tex": { "packages": { "a": ["a.sty"] }, "pkgs": {} } }`,
+    `{ "type": "family", "tex": { "packages": { "a": ["a.sty"] }, "pkgs": {} } }`,
     "additional properties",
   ],
 ];
@@ -174,7 +182,9 @@ check(
 );
 check(
   "comments and trailing commas ARE JSONC",
-  bad(`// quote\n{ "tex": { "packages": { "a": ["a.sty"], }, }, }`) === "",
+  bad(
+    `// quote\n{ "type": "family", "tex": { "packages": { "a": ["a.sty"], }, }, }`,
+  ) === "",
 );
 rmSync(tmp, { recursive: true, force: true });
 
@@ -239,7 +249,7 @@ rmSync(tmp, { recursive: true, force: true });
 // ── 5. the parser's tolerances: an optional block left out, and Ajv's optional fields ───
 {
   const bare = R.parsePreset(
-    '{ "extends": "paperlint:aisec" }',
+    '{ "type": "venue", "name": "X", "url": "https://x.org/", "extends": "paperlint:aisec" }',
     "bare.jsonc",
     VENUES,
   );
@@ -254,9 +264,13 @@ rmSync(tmp, { recursive: true, force: true });
   check(
     "a tex block without `packages` is refused by the schema, before anything reads it",
     /tex\.jsonc: \.tex should have required property 'packages'/.test(
-      throws(() => R.parsePreset('{ "tex": {} }', "tex.jsonc", VENUES)),
+      throws(() =>
+        R.parsePreset('{ "type": "family", "tex": {} }', "tex.jsonc", VENUES),
+      ),
+    ),
+    throws(() =>
+      R.parsePreset('{ "type": "family", "tex": {} }', "tex.jsonc", VENUES),
     ),
-    throws(() => R.parsePreset('{ "tex": {} }', "tex.jsonc", VENUES)),
   );
   check(
     "violations: Ajv's null `errors` is no violation; a message Ajv left out is an empty one",

package/src/tex-requirements.test.ts

@@ -1,6 +1,11 @@
 import assert from "node:assert/strict";
 import { test } from "vitest";
-import { loadTypescript } from "./tex-requirements.ts";
+import {
+  identityHint,
+  identityHints,
+  loadTypescript,
+  parsePreset,
+} from "./tex-requirements.ts";
 
 test("loadTypescript refuses a module without the two functions a profile is read with", () => {
   assert.throws(
@@ -19,3 +24,124 @@ test("loadTypescript hands back what `require` loaded when it has them", () => {
     ts,
   );
 });
+
+// ── what a preset is: the identity its `type` declares ─────────────────────────────────────
+
+/** What `parsePreset` throws for `preset`, as text; "" when it parses. */
+function refusalOf(name: string, preset: object): string {
+  try {
+    parsePreset(JSON.stringify(preset), name);
+    return "";
+  } catch (e) {
+    return e instanceof Error ? e.message : String(e);
+  }
+}
+
+test("a venue without the link to its call for papers is refused at load, saying what to add", () => {
+  // Guards: the wrong state the identity exists to make unrepresentable — a venue nobody can check.
+  assert.equal(
+    refusalOf("v.jsonc", {
+      type: "venue",
+      name: "X",
+      extends: "paperlint:acm-sigconf",
+    }),
+    [
+      "v.jsonc does not match venue-profile.schema.json:",
+      '  a venue preset names its venue and links its call for papers: "name": "<the venue, as its call spells it>", "url": "https://<the call for papers>"',
+      "  v.jsonc: (top level) should have required property 'url'",
+      '  v.jsonc: (top level) should match "then" schema',
+    ].join("\n"),
+  );
+});
+
+test("a template family with a venue's name and url is refused, naming each key", () => {
+  assert.equal(
+    refusalOf("f.jsonc", {
+      type: "family",
+      name: "ACM",
+      url: "https://acm.org/",
+      extends: "paperlint:acm-sigconf",
+    }),
+    [
+      "f.jsonc does not match venue-profile.schema.json:",
+      '  a template family names no venue: drop "name" — "name" and "url" belong to the venue presets that extend it',
+      '  a template family names no venue: drop "url" — "name" and "url" belong to the venue presets that extend it',
+      "  f.jsonc: .name boolean schema is false",
+      "  f.jsonc: .url boolean schema is false",
+      '  f.jsonc: (top level) should match "then" schema',
+    ].join("\n"),
+  );
+});
+
+test("a preset that does not say what it is is refused, with the three answers", () => {
+  assert.equal(
+    refusalOf("n.jsonc", { extends: "paperlint:acm-sigconf" }),
+    [
+      "n.jsonc does not match venue-profile.schema.json:",
+      '  say what this preset is: "type": "venue" (one venue\'s call for papers), "family" (a publisher\'s template that venues extend) or "base" (the TeX base set)',
+      "  n.jsonc: (top level) should have required property 'type'",
+    ].join("\n"),
+  );
+});
+
+test("the TeX base set holds its packages and nothing else", () => {
+  assert.equal(
+    refusalOf("b.jsonc", {
+      type: "base",
+      tex: { packages: { a: ["a.sty"] } },
+      format: { columns: 2 },
+    }),
+    [
+      "b.jsonc does not match venue-profile.schema.json:",
+      '  the TeX base set holds "type" and "tex" only — a venue\'s or a family\'s settings go in its own preset',
+      "  b.jsonc: (top level) should NOT have more than 2 properties",
+      '  b.jsonc: (top level) should match "then" schema',
+    ].join("\n"),
+  );
+});
+
+test("a venue is parsed into its identity; a family and the base set carry none of a venue's fields", () => {
+  const read = (p: object) =>
+    parsePreset(JSON.stringify(p), "p.jsonc").identity;
+  assert.deepEqual(
+    [
+      read({
+        type: "venue",
+        name: "X",
+        url: "https://x.org/cfp",
+        extends: "paperlint:acm-sigconf",
+      }),
+      read({ type: "family", extends: "paperlint:acm-sigconf" }),
+      read({ type: "base", tex: { packages: { a: ["a.sty"] } } }),
+    ],
+    [
+      { type: "venue", name: "X", url: "https://x.org/cfp" },
+      { type: "family" },
+      { type: "base" },
+    ],
+  );
+});
+
+test("identityHint has nothing to add to a violation that is not about the identity", () => {
+  assert.equal(
+    identityHint({
+      keyword: "additionalProperties",
+      dataPath: "",
+      params: { additionalProperty: "colums" },
+    }),
+    null,
+  );
+});
+
+test("identityHints: Ajv's null errors give none; a hint two violations share is given once", () => {
+  assert.deepEqual(identityHints({ errors: null }), []);
+  const missing = {
+    keyword: "required",
+    dataPath: "",
+    schemaPath: "#/required",
+    params: { missingProperty: "type" },
+  };
+  const hints = identityHints({ errors: [missing, missing] });
+  assert.equal(hints.length, 1);
+  assert.deepEqual(hints, [identityHint(missing)]);
+});