paperlint 6.2.2 → 6.3.0

package/src/domain/submission.ts

@@ -0,0 +1,141 @@
+/**
+ * THE SUBMISSION ON A CONFERENCE PORTAL — what `paperlint submission` reads and changes.
+ *
+ * Two declarations, each in the file that owns the fact:
+ *
+ *   venue preset `portal`        where the venue takes submissions: `{ "kind": "hotcrp", "url": … }`
+ *   paper `submission`           which submission on that portal is this paper's: `{ "id": 7 }`
+ *
+ * The values here are the portal's answers in paperlint's words, not in any one portal's: an adapter
+ * per portal kind maps its API onto them (`src/adapters/hotcrp/`).
+ */
+import { err, ok, type Result } from "./result.ts";
+import { isRecord } from "./record.ts";
+import type { Sha256 } from "./sha256.ts";
+
+/** The portal kinds an adapter exists for. Any other kind is refused by name. */
+export type PortalKind = "hotcrp";
+export const PORTAL_KINDS: readonly PortalKind[] = ["hotcrp"];
+
+/** A venue preset's `portal`, as the preset declares it: the kind is checked where it is used. */
+export interface VenuePortal {
+  readonly kind: string;
+  /** The portal site's base URL, without a trailing slash. */
+  readonly url: string;
+}
+
+/** A portal whose kind has an adapter. */
+export interface SupportedPortal {
+  readonly kind: PortalKind;
+  readonly url: string;
+}
+
+const isPortalKind = (k: string): k is PortalKind =>
+  PORTAL_KINDS.some((x) => x === k);
+
+/** The declared portal → one paperlint can talk to, or the refusal naming the kind. Pure. */
+export function supportedPortal(
+  p: VenuePortal,
+): Result<SupportedPortal, string> {
+  return isPortalKind(p.kind)
+    ? ok({ kind: p.kind, url: p.url.replace(/\/+$/, "") })
+    : err(`portal kind "${p.kind}" is not supported; upload by hand`);
+}
+
+/** A paper's `submission`: which submission on the venue's portal is this paper's. */
+export interface PaperSubmission {
+  readonly id: number;
+}
+
+/** A paper's `submission` key → the value, null when absent, or one line saying what is wrong. Pure. */
+export function parsePaperSubmission(
+  v: unknown,
+): Result<PaperSubmission | null, string> {
+  if (v === undefined) return ok(null);
+  const bad = err(
+    `"submission" must be { "id": <the submission number on the venue's portal> }`,
+  );
+  if (!isRecord(v)) return bad;
+  const unknown = Object.keys(v).find((k) => k !== "id");
+  if (unknown !== undefined)
+    return err(`"submission" has an unknown key "${unknown}" — known: id`);
+  const id = v["id"];
+  return typeof id === "number" && Number.isInteger(id) && id > 0
+    ? ok({ id })
+    : bad;
+}
+
+/** The PDF the portal holds for a submission. */
+export interface PortalDocument {
+  /** The sha256 of the stored bytes; null when the portal names another hash or none. */
+  readonly sha256: Sha256 | null;
+  /** The hash as the portal spells it. */
+  readonly hash: string;
+  readonly size: number | null;
+  readonly mimetype: string | null;
+  /** Unix seconds; null when the portal does not say. */
+  readonly uploadedAt: number | null;
+}
+
+/** One submission, as the portal shows it to its author. */
+export interface SubmissionView {
+  readonly id: number;
+  readonly status: string;
+  readonly title: string | null;
+  readonly paperType: string | null;
+  readonly topics: readonly string[];
+  readonly abstract: string | null;
+  /** The PDF the portal holds; null when none is uploaded. */
+  readonly pdf: PortalDocument | null;
+  /** Unix seconds; null when not submitted or not said. */
+  readonly submittedAt: number | null;
+  readonly modifiedAt: number | null;
+  /** What the portal said beside the answer. */
+  readonly messages: readonly PortalMessage[];
+}
+
+/** A change to send. Every absent part is left as the portal has it. */
+export interface SubmissionChange {
+  readonly pdf: { readonly name: string; readonly bytes: Uint8Array } | null;
+  readonly abstract: string | null;
+  /** Mark the submission submitted (ready for review). */
+  readonly submit: boolean;
+}
+
+/** One message from the portal: its text, and the field it is about when it names one. */
+export interface PortalMessage {
+  readonly message: string;
+  readonly field: string | null;
+  /** The portal's severity number, when it gives one. */
+  readonly status: number | null;
+}
+
+/** What the portal answered to a change. */
+export interface UpdateOutcome {
+  readonly httpStatus: number;
+  /** The change is valid; for a saved change, it was also committed. */
+  readonly valid: boolean;
+  /** The fields the change touched. */
+  readonly changes: readonly string[];
+  readonly messages: readonly PortalMessage[];
+  /** The portal reports that nothing was saved. */
+  readonly dryRun: boolean;
+}
+
+/** Why the portal gave no usable answer. */
+export type PortalFailure =
+  | {
+      readonly kind: "refused";
+      readonly httpStatus: number;
+      readonly messages: readonly PortalMessage[];
+    }
+  | { readonly kind: "unreachable"; readonly detail: string }
+  | {
+      readonly kind: "malformed";
+      readonly httpStatus: number;
+      readonly detail: string;
+    };
+
+/** Words in a text, as a reader counts them: runs of non-space. Pure. */
+export const wordCount = (s: string): number =>
+  s.split(/\s+/).filter((w) => w !== "").length;

package/src/domain/venue-name.test.ts

@@ -0,0 +1,115 @@
+import { describe, expect, it } from "vitest";
+import { cpSync, mkdtempSync, realpathSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { nodeFiles } from "../adapters/node/index.ts";
+import { presetsDir } from "../package-dirs.ts";
+import { shippedVenueNames } from "../presets.ts";
+import {
+  nameTokens,
+  venuesNamedBy,
+  withoutVenues,
+  type NamedVenue,
+} from "./venue-name.ts";
+
+describe("nameTokens — a name as the words it is made of", () => {
+  it.each<[string, readonly string[]]>([
+    ["aisec-2026", ["aisec", "2026"]],
+    ["my_paper.v2", ["my", "paper", "v", "2"]],
+    ["ACM CCS", ["acm", "ccs"]],
+    ["acm-sigconf", ["acm", "sigconf"]],
+    // Letters and digits glued together are two words: `aisec2026` names AISec as much as `aisec-2026`.
+    ["aisec2026", ["aisec", "2026"]],
+    ["--x--", ["x"]],
+    ["", []],
+  ])("%s", (name, want) => {
+    expect(nameTokens(name)).toEqual(want);
+  });
+});
+
+/**
+ * The venues are the SHIPPED presets, read through the one source of venue names
+ * (`shippedVenueNames`) — never a list of names written here. A case below depends on what a preset
+ * says (`aidc`'s alias ACSAC, `aisec`'s ACM CCS); a preset edit that changes it shows here.
+ */
+const VENUES: readonly NamedVenue[] = shippedVenueNames({
+  files: nodeFiles,
+  venuesDir: presetsDir(),
+});
+
+describe("venuesNamedBy — which venues a folder name names", () => {
+  it.each<[string, string, readonly { venue: string; name: string }[]]>([
+    ["the label", "aisec-2026", [{ venue: "aisec", name: "aisec" }]],
+    ["an alias", "acsac-2026", [{ venue: "aidc", name: "ACSAC" }]],
+    [
+      "a two-word alias, as two tokens in a row",
+      "acm-ccs-agents",
+      [{ venue: "aisec", name: "ACM CCS" }],
+    ],
+    ["the two words of an alias apart are not it", "acm-agents-ccs", []],
+    ["glued to a year", "realm2026", [{ venue: "realm", name: "realm" }]],
+    [
+      "two venues, each once, in the order they are listed",
+      "realm-aisec-aisec",
+      [
+        { venue: "aisec", name: "aisec" },
+        { venue: "realm", name: "realm" },
+      ],
+    ],
+    // Whole tokens only: a venue's name inside another word is that other word.
+    ["inside a word: overrealm", "overrealm-study", []],
+    ["inside a word: realms", "realms-of-agents", []],
+    ["inside a word: aisecure", "aisecure", []],
+    ["no venue at all", "agent-rule-drift", []],
+  ])("%s: %s", (_, folder, want) => {
+    expect(venuesNamedBy(folder, VENUES)).toEqual(want);
+  });
+
+  it("a name that is also the paper's own is not reported, whichever venue declares it", () => {
+    // A paper at a venue whose own chain also says "ACM CCS" (two workshops of one conference).
+    expect(venuesNamedBy("ccs-acm-ccs", VENUES, ["ACM CCS"])).toEqual([]);
+    expect(venuesNamedBy("aisec-2026", VENUES, ["aisec"])).toEqual([]);
+  });
+
+  it("own names compare by their words, not their spelling", () => {
+    expect(venuesNamedBy("acsac-2026", VENUES, ["ACSAC"])).toEqual([]);
+    expect(venuesNamedBy("acm-ccs-x", VENUES, ["acm-ccs"])).toEqual([]);
+  });
+
+  it("a preset whose alias has no words names nothing by it", () => {
+    // A fixture preset in a copy of the presets directory: alias "—" has no letter or digit, and a
+    // name of no words must not stand everywhere.
+    const dir = realpathSync(
+      mkdtempSync(join(tmpdir(), "paperlint-venue-name-")),
+    );
+    cpSync(presetsDir(), dir, { recursive: true });
+    writeFileSync(
+      join(dir, "dash.jsonc"),
+      JSON.stringify({ extends: "paperlint:acm-sigconf", aliases: ["—"] }),
+    );
+    const venues = shippedVenueNames({ files: nodeFiles, venuesDir: dir });
+    expect(venues.find((v) => v.label === "dash")?.aliases).toContain("—");
+    expect(venuesNamedBy("agent-rule-drift", venues)).toEqual([]);
+    expect(venuesNamedBy("dash-2026", venues)).toEqual([
+      { venue: "dash", name: "dash" },
+    ]);
+  });
+});
+
+describe("withoutVenues — the name with its venues taken out, when that is a name for the work", () => {
+  it.each<[string, string | null]>([
+    ["aisec-agent-drift", "agent-drift"],
+    ["agent_drift.aisec", "agent-drift"],
+    ["acm-ccs-agents", "agents"],
+    ["realm-rules-aisec-2026", "rules-2026"],
+    ["--aisec--agents", "agents"],
+    // Only numbers left: `2026` names no work.
+    ["aisec-2026", null],
+    ["aisec", null],
+    // A venue glued to other words in one part is not cleanly taken out.
+    ["aisec2026-agents", null],
+    ["agent-rule-drift", "agent-rule-drift"],
+  ])("%s → %s", (name, want) => {
+    expect(withoutVenues(name, VENUES)).toBe(want);
+  });
+});

package/src/domain/venue-name.ts

@@ -0,0 +1,129 @@
+/**
+ * WHICH VENUE A NAME NAMES — a paper folder's name read as words, against what each venue is
+ * called (a preset's label and its `aliases`).
+ *
+ * A name is compared by its WORDS, never by substring: `overrealm` and `realms` do not name REALM,
+ * `aisec-2026` and `aisec2026` name AISec. A word is a run of letters or a run of digits; anything
+ * else separates words, and case is ignored. A venue name of several words (`ACM CCS`) names the
+ * venue only when those words stand in a row.
+ *
+ * Read by `paper/folder-venue-leftover` (a folder naming a venue other than the one the paper
+ * extends) and by `paperlint new`, which refuses a new folder naming any venue at all.
+ */
+
+/** A venue as names know it: the word for it in messages, and the other names it goes by. */
+export interface NamedVenue {
+  readonly label: string;
+  readonly aliases: readonly string[];
+}
+
+/** A venue a name names, and which of its names it used, as the venue spells it. */
+export interface NamedIn {
+  readonly venue: string;
+  readonly name: string;
+}
+
+/** A name's words, lowercased: runs of letters and runs of digits; everything else separates. */
+export const nameTokens = (name: string): readonly string[] =>
+  name.toLowerCase().match(/\p{L}+|\p{N}+/gu) ?? [];
+
+/** Where `words` stand in a row in `tokens`: the index of each first word. None for empty `words`. */
+const placesIn = (
+  tokens: readonly string[],
+  words: readonly string[],
+): readonly number[] =>
+  words.length === 0
+    ? []
+    : tokens.flatMap((_, i) =>
+        words.every((w, j) => tokens[i + j] === w) ? [i] : [],
+      );
+
+/** A name's words as one key, to compare two spellings of a name. */
+const keyOf = (name: string): string => nameTokens(name).join(" ");
+
+/** Every name of every venue that is not one of `own`, with its words. */
+const candidates = (
+  venues: readonly NamedVenue[],
+  own: readonly string[],
+): readonly (NamedIn & { readonly words: readonly string[] })[] => {
+  const ownKeys = new Set(own.map(keyOf));
+  return venues.flatMap((v) =>
+    [v.label, ...v.aliases]
+      .filter((n) => !ownKeys.has(keyOf(n)))
+      .map((name) => ({ venue: v.label, name, words: nameTokens(name) })),
+  );
+};
+
+/**
+ * Each venue `name` names by one of its names (the label first, then its aliases), once per venue,
+ * in the order `venues` lists them. A name that is also one of `own` — the paper's own venue's,
+ * compared by words — is never counted: two workshops of one conference share its name.
+ */
+export function venuesNamedBy(
+  name: string,
+  venues: readonly NamedVenue[],
+  own: readonly string[] = [],
+): readonly NamedIn[] {
+  const tokens = nameTokens(name);
+  const hits = candidates(venues, own).filter(
+    (c) => placesIn(tokens, c.words).length > 0,
+  );
+  return hits
+    .filter((c, i) => hits.findIndex((d) => d.venue === c.venue) === i)
+    .map(({ venue, name: n }) => ({ venue, name: n }));
+}
+
+/** A part of a name between separators, with the indices of its words in the whole name's words. */
+interface Part {
+  readonly text: string;
+  readonly at: readonly number[];
+}
+
+/** A name's hyphen-, underscore- or dot-separated parts, each with where its words stand. */
+const partsOf = (name: string): readonly Part[] =>
+  name
+    .split(/[^\p{L}\p{N}]+/u)
+    .filter((text) => text.length > 0)
+    .reduce<{ readonly next: number; readonly out: readonly Part[] }>(
+      (acc, text) => {
+        const n = nameTokens(text).length;
+        const at = Array.from({ length: n }, (_, j) => acc.next + j);
+        return { next: acc.next + n, out: [...acc.out, { text, at }] };
+      },
+      { next: 0, out: [] },
+    ).out;
+
+/** The indices of the words of `name` that belong to a venue's name. */
+const venueWordsIn = (
+  name: string,
+  venues: readonly NamedVenue[],
+): ReadonlySet<number> => {
+  const tokens = nameTokens(name);
+  return new Set(
+    candidates(venues, []).flatMap((c) =>
+      placesIn(tokens, c.words).flatMap((at) => c.words.map((_, j) => at + j)),
+    ),
+  );
+};
+
+/**
+ * `name` with every venue name taken out, as a name for the work — or null when that is not clean:
+ * a venue's words glued to other words in one hyphen-, underscore- or dot-separated part
+ * (`aisec2026`), or nothing but numbers left (`aisec-2026` → `2026` names no work). The parts left
+ * are joined by `-`.
+ */
+export function withoutVenues(
+  name: string,
+  venues: readonly NamedVenue[],
+): string | null {
+  const venueWord = venueWordsIn(name, venues);
+  const inVenue = (p: Part): number =>
+    p.at.filter((i) => venueWord.has(i)).length;
+  const parts = partsOf(name);
+  if (parts.some((p) => inVenue(p) > 0 && inVenue(p) < p.at.length))
+    return null;
+  const left = parts.filter((p) => inVenue(p) === 0);
+  return left.some((p) => /\p{L}/u.test(p.text))
+    ? left.map((p) => p.text).join("-")
+    : null;
+}

package/src/folder-venue-rule.test.ts

@@ -0,0 +1,182 @@
+/**
+ * `paper/folder-venue-leftover` (`src/folder-venue-rule.ts`) on papers held in memory beside the
+ * SHIPPED presets, so the venue names come from the registry a user gets. Both halves: a folder
+ * named after another venue than the paper's `extends` is reported once, on the scorecard's first
+ * line; a folder named after the paper's own venue, or after no venue, is not.
+ */
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { memoryFiles } from "./adapters/memory/index.ts";
+import { presetsDir } from "./package-dirs.ts";
+import {
+  FOLDER_VENUE_RULE_LEVELS,
+  folderVenueRules,
+} from "./folder-venue-rule.ts";
+
+const VENUES = presetsDir();
+const PAPERS = "/work/papers";
+const shipped = Object.fromEntries(
+  readdirSync(VENUES)
+    .filter((f) => f.endsWith(".jsonc") || f.endsWith(".json"))
+    .map((f) => [join(VENUES, f), readFileSync(join(VENUES, f))]),
+);
+
+interface Reported {
+  readonly messageId: string;
+  readonly message: string;
+  readonly line: number;
+}
+
+/**
+ * The rule over one paper folder's file, the way ESLint runs it: `create`, then `root`. `settings`
+ * is the paper's paperlint.json (absent: no file); `extra` more files, by absolute path.
+ */
+function lint(
+  folder: string,
+  settings: object | undefined,
+  {
+    file = "PIPELINE-STATUS.md",
+    extra = {},
+  }: { file?: string; extra?: Record<string, string> } = {},
+): Reported[] {
+  const dir = `${PAPERS}/${folder}`;
+  const files = memoryFiles({
+    ...shipped,
+    ...(settings === undefined
+      ? {}
+      : { [`${dir}/paperlint.json`]: JSON.stringify(settings) }),
+    ...extra,
+  });
+  const rule = folderVenueRules({ files, venuesDir: VENUES })[
+    "folder-venue-leftover"
+  ];
+  const out: Reported[] = [];
+  const visitor = rule.create({
+    filename: `${dir}/${file}`,
+    sourceCode: { getLocFromIndex: () => ({ line: 1, column: 0 }) },
+    report: (d) => {
+      const template = rule.meta.messages[d.messageId] ?? "";
+      const message = Object.entries(d.data).reduce(
+        (m, [k, v]) => m.split(`{{${k}}}`).join(String(v)),
+        template,
+      );
+      out.push({ messageId: d.messageId, message, line: d.loc.start.line });
+    },
+  });
+  visitor.root?.();
+  return out;
+}
+
+const AIDC = { extends: "paperlint:aidc", kind: "regular" };
+
+describe("paper/folder-venue-leftover — the folder names another venue", () => {
+  it("a folder named after the venue the paper left is reported, naming both and the cure", () => {
+    expect(lint("aisec-2026", AIDC)).toEqual([
+      {
+        messageId: "leftover",
+        line: 1,
+        message:
+          "the folder name «aisec-2026» names the venue aisec, and this paper extends aidc — the name went stale when the venue changed, and venues change on every resubmission. Name the folder after the work (what the paper shows), not the venue",
+      },
+    ]);
+  });
+
+  it("a venue named by an alias says which alias", () => {
+    expect(
+      lint("acm-ccs-agents", AIDC).map(
+        (r) => /names the venue (.*?), and/u.exec(r.message)?.[1],
+      ),
+    ).toEqual(["aisec («ACM CCS»)"]);
+  });
+
+  it("two other venues are two findings", () => {
+    expect(
+      lint("realm-then-aisec", AIDC).map(
+        (r) => /names the venue (\w+)/u.exec(r.message)?.[1],
+      ),
+    ).toEqual(["aisec", "realm"]);
+  });
+
+  it("a project's own preset is judged like a shipped one: its label and aliases are its own", () => {
+    const extra = {
+      [`${PAPERS}/aidc-redux/venue.jsonc`]: JSON.stringify({
+        extends: "paperlint:aisec",
+        name: "AISec 2027",
+      }),
+    };
+    // Its chain is AISec's, so aisec is its own; aidc is another venue.
+    expect(
+      lint(
+        "aidc-redux",
+        { extends: "./venue.jsonc", kind: "short" },
+        { extra },
+      ),
+    ).toHaveLength(1);
+    expect(
+      lint(
+        "aisec-redux",
+        { extends: "./venue.jsonc", kind: "short" },
+        {
+          extra: {
+            [`${PAPERS}/aisec-redux/venue.jsonc`]: JSON.stringify({
+              extends: "paperlint:aisec",
+            }),
+          },
+        },
+      ),
+    ).toEqual([]);
+  });
+});
+
+describe("paper/folder-venue-leftover — silent", () => {
+  it.each<[string, string, object | undefined]>([
+    [
+      "the folder names the paper's own venue",
+      "agenticdev-2026",
+      { extends: "paperlint:agenticdev", kind: "short" },
+    ],
+    ["by its alias", "acsac-2026", AIDC],
+    ["the folder names no venue", "agent-rule-drift", AIDC],
+    // Whole words only: REALM is not inside these.
+    ["a venue's name inside another word", "overrealm-realms", AIDC],
+    ["no paperlint.json: no venue to compare with", "aisec-2026", undefined],
+    ["no extends yet", "aisec-2026", { extends: null }],
+    [
+      "an extends that does not resolve — pdf/profile says so",
+      "aisec-2026",
+      { extends: "paperlint:nope" },
+    ],
+  ])("%s", (_, folder, settings) => {
+    expect(lint(folder, settings)).toEqual([]);
+  });
+
+  it("a paperlint.json that does not parse — pdf/profile says so", () => {
+    expect(
+      lint("aisec-2026", undefined, {
+        extra: { [`${PAPERS}/aisec-2026/paperlint.json`]: "{ not json" },
+      }),
+    ).toEqual([]);
+  });
+
+  it("judged once per paper, on PIPELINE-STATUS.md only", () => {
+    expect(lint("aisec-2026", AIDC, { file: "paper.md" })).toEqual([]);
+  });
+
+  it("a paper on a bare template family declares no venue: a venue in its folder may be its own", () => {
+    // The accepted ACSAC papers in fixtures/accepted-papers/ are exactly this: `…-acsac24` folders
+    // extending ieee-conference, while `aidc` names ACSAC, its parent conference, as an alias.
+    expect(
+      lint("secure-acsac24", { extends: "paperlint:ieee-conference" }),
+    ).toEqual([]);
+    expect(lint("aisec-2026", { extends: "paperlint:acm-sigconf" })).toEqual(
+      [],
+    );
+  });
+});
+
+it("the level: a warning — a rename is the author's call", () => {
+  expect(FOLDER_VENUE_RULE_LEVELS).toEqual({
+    "paper/folder-venue-leftover": "warn",
+  });
+});