paperlint 2.0.1 → 3.0.0

package/src/presets.ts

@@ -0,0 +1,297 @@
+/**
+ * VENUE PRESETS — what `"extends"` in a paper's `paperlint.json` resolves to.
+ *
+ * A venue is a preset, the way an ESLint config is a shareable config: a file with the venue's
+ * format (page size, columns, fonts, font sizes, page limits per kind), the TeX packages its
+ * template needs, and the rules it implies. A preset may build on another with its own `extends`:
+ * `agenticdev` extends the family `acm-sigconf`, which holds everything the ACM template decides.
+ *
+ * ── TWO SPEC FORMS, AND ONLY TWO ─────────────────────────────────────────────────
+ *   paperlint:<name>   a preset shipped in the package's venues directory
+ *   ./x.jsonc, ../x    a file of the project's own, relative to the file that names it
+ * Anything else — an npm package name, a bare name — is refused by name. npm presets are not
+ * supported yet; a bare name is almost always a shipped name missing its prefix, and the message says so.
+ *
+ * ── THE CHAIN ─────────────────────────────────────────────────────────────────────
+ * At most `MAX_PRESET_DEPTH` files, root to leaf. A cycle (relative paths can form one) is refused
+ * naming the chain. The chain is merged block by block:
+ *
+ *   tex        union — a child never removes a package its parent needs
+ *   format     per key, the child wins; `kinds` by kind name, a child's kind replaces that kind
+ *   rules      per rule id, the child wins
+ *   template   the child wins; so does `name`
+ *
+ * ── THE LABEL ─────────────────────────────────────────────────────────────────────
+ * Messages, the facts file and the build plan need a word for the venue. It is the most derived
+ * preset's `name` when one sets it, else the spec's file name without its extension
+ * (`paperlint:agenticdev` → `agenticdev`, `./venues/usenix-sec.jsonc` → `usenix-sec`). Display
+ * only: nothing is ever resolved by it.
+ */
+import { basename, dirname, extname, join, resolve } from "node:path";
+import {
+  mergeRequirements,
+  NO_FORMAT,
+  NO_REQUIREMENTS,
+  parsePreset,
+  profileFileOf,
+  venueNames,
+  type PresetFile,
+  type TexRequirements,
+  type VenueFormat,
+} from "./tex-requirements.ts";
+import type { AbsolutePath } from "./domain/paths.ts";
+import { err, ok, type Result } from "./domain/result.ts";
+import type { Files } from "./ports/files.ts";
+import {
+  readPaperSettings,
+  type PaperSettings,
+  type SettingsProblem,
+} from "./paper-settings.ts";
+import { CONFIG_FILE } from "../lib/paper-config.mjs";
+
+/** The prefix of a shipped preset's spec. */
+export const SHIPPED_PREFIX = "paperlint:";
+/** The longest chain of presets, the paper's own target included. */
+export const MAX_PRESET_DEPTH = 4;
+
+export interface PresetDeps {
+  readonly files: Files;
+  /** The package's venues directory: the shipped presets and the schema every preset is checked against. */
+  readonly venuesDir: string;
+}
+
+/** A resolved chain, merged. */
+export interface Preset {
+  /** The word for this venue in messages. */
+  readonly label: string;
+  /** Every file of the chain, root first. */
+  readonly chain: readonly string[];
+  readonly template: string | null;
+  readonly tex: TexRequirements;
+  readonly format: VenueFormat;
+  readonly rules: Readonly<Record<string, unknown>>;
+}
+
+/** Why a spec does not resolve. */
+export type PresetProblem =
+  | { readonly kind: "unsupported"; readonly spec: string }
+  | {
+      readonly kind: "not-found";
+      readonly spec: string;
+      readonly file: string;
+      readonly shipped: readonly string[];
+    }
+  | { readonly kind: "cycle"; readonly chain: readonly string[] }
+  | { readonly kind: "too-deep"; readonly chain: readonly string[] }
+  | { readonly kind: "broken"; readonly file: string; readonly why: string };
+
+/** The display label of a spec: the file name without its extension. Pure. */
+export function labelOf(spec: string): string {
+  const name = spec.startsWith(SHIPPED_PREFIX)
+    ? spec.slice(SHIPPED_PREFIX.length)
+    : basename(spec);
+  return name.slice(0, name.length - extname(name).length) || name;
+}
+
+const isRelative = (spec: string): boolean =>
+  spec.startsWith("./") || spec.startsWith("../");
+
+/** A spec → the file it names, or why it names none. Pure. */
+function fileOf(
+  spec: string,
+  from: string,
+  venuesDir: string,
+): Result<string, PresetProblem> {
+  if (isRelative(spec)) return ok(resolve(dirname(from), spec));
+  if (!spec.startsWith(SHIPPED_PREFIX))
+    return err({ kind: "unsupported", spec });
+  const file = profileFileOf(spec.slice(SHIPPED_PREFIX.length));
+  return file === null
+    ? err({ kind: "not-found", spec, file: spec, shipped: [] })
+    : ok(join(venuesDir, file));
+}
+
+/** One file of the chain: read and parsed, or why not. */
+function readPreset(
+  spec: string,
+  from: string,
+  deps: PresetDeps,
+): Result<{ file: string; preset: PresetFile }, PresetProblem> {
+  const where = fileOf(spec, from, deps.venuesDir);
+  if (!where.ok) return where;
+  const bytes = deps.files.readBytes(where.value as AbsolutePath);
+  if (bytes === null)
+    return err({ kind: "not-found", spec, file: where.value, shipped: [] });
+  try {
+    const text = new TextDecoder().decode(bytes);
+    return ok({
+      file: where.value,
+      preset: parsePreset(text, where.value, deps.venuesDir),
+    });
+  } catch (e) {
+    return err({
+      kind: "broken",
+      file: where.value,
+      why: (e as Error).message.split("\n").join(" "),
+    });
+  }
+}
+
+/** The chain's files, leaf first, each parsed. */
+function chainOf(
+  spec: string,
+  from: string,
+  deps: PresetDeps,
+): Result<{ file: string; preset: PresetFile }[], PresetProblem> {
+  const out: { file: string; preset: PresetFile }[] = [];
+  let next: { spec: string; from: string } | null = { spec, from };
+  while (next !== null) {
+    const r = readPreset(next.spec, next.from, deps);
+    if (!r.ok) return r;
+    const files = out.map((x) => x.file);
+    if (files.includes(r.value.file))
+      return err({ kind: "cycle", chain: [...files, r.value.file] });
+    if (out.length === MAX_PRESET_DEPTH)
+      return err({ kind: "too-deep", chain: [...files, r.value.file] });
+    out.push(r.value);
+    const up: string | null = r.value.preset.extends;
+    next = up === null ? null : { spec: up, from: r.value.file };
+  }
+  return ok(out);
+}
+
+/** A child's format over its parent's: per key the child wins, kinds by name. Pure. */
+export function mergeFormat(
+  parent: VenueFormat,
+  child: VenueFormat,
+): VenueFormat {
+  const keys = Object.keys(NO_FORMAT).filter((k) => k !== "kinds") as Exclude<
+    keyof VenueFormat,
+    "kinds"
+  >[];
+  const scalars = Object.fromEntries(
+    keys.map((k) => [k, child[k] ?? parent[k]]),
+  ) as Omit<VenueFormat, "kinds">;
+  return { ...scalars, kinds: new Map([...parent.kinds, ...child.kinds]) };
+}
+
+/** The chain, root first, merged into one preset. Pure. */
+function merged(
+  spec: string,
+  rootFirst: readonly PresetFile[],
+  files: readonly string[],
+): Preset {
+  const base = {
+    name: null as string | null,
+    template: null as string | null,
+    tex: NO_REQUIREMENTS,
+    format: NO_FORMAT,
+    rules: {} as Readonly<Record<string, unknown>>,
+  };
+  const m = rootFirst.reduce(
+    (acc, p) => ({
+      name: p.name ?? acc.name,
+      template: p.template ?? acc.template,
+      tex: p.tex ? mergeRequirements(acc.tex, p.tex) : acc.tex,
+      format: mergeFormat(acc.format, p.format),
+      rules: { ...acc.rules, ...p.rules },
+    }),
+    base,
+  );
+  return {
+    label: m.name ?? labelOf(spec),
+    chain: files,
+    template: m.template,
+    tex: m.tex,
+    format: m.format,
+    rules: m.rules,
+  };
+}
+
+/**
+ * `spec`, as written in `fromFile` (a paper's `paperlint.json`), → the merged preset, or why it
+ * does not resolve. Reads through `deps.files` only; never throws.
+ */
+export function resolvePreset(
+  spec: string,
+  fromFile: string,
+  deps: PresetDeps,
+): Result<Preset, PresetProblem> {
+  const chain = chainOf(spec, fromFile, deps);
+  if (!chain.ok)
+    return chain.error.kind === "not-found"
+      ? err({ ...chain.error, shipped: shippedPresets(deps.venuesDir) })
+      : chain;
+  const rootFirst = [...chain.value].reverse();
+  return ok(
+    merged(
+      spec,
+      rootFirst.map((x) => x.preset),
+      rootFirst.map((x) => x.file),
+    ),
+  );
+}
+
+/** The shipped presets' names (each is spelled `paperlint:<name>`). */
+export function shippedPresets(venuesDir: string): string[] {
+  return venueNames(venuesDir);
+}
+
+/** One line for a problem, naming what to change. Pure. */
+export function presetProblemText(p: PresetProblem): string {
+  switch (p.kind) {
+    case "unsupported":
+      return `"extends": "${p.spec}" — a preset is \`paperlint:<name>\` (shipped) or a path starting with ./ or ../ (your own); npm presets: not yet supported. Did you mean "${SHIPPED_PREFIX}${p.spec}"?`;
+    case "not-found":
+      return `"extends": "${p.spec}" names no preset (${p.file}); shipped presets (${SHIPPED_PREFIX}<name>): ${p.shipped.join(", ")}`;
+    case "cycle":
+      return `the presets extend each other in a cycle: ${p.chain.join(" → ")}`;
+    case "too-deep":
+      return `the preset chain is longer than ${String(MAX_PRESET_DEPTH)}: ${p.chain.join(" → ")}`;
+    case "broken":
+      return `the preset ${p.file} does not parse: ${p.why}`;
+  }
+}
+
+// ── a paper's preset ────────────────────────────────────────────────────────────────────
+
+/** What one paper declares and the preset it resolves to — one answer for every reader. */
+export type PaperPreset =
+  /** No `paperlint.json`, or one without `extends`: no venue checks, the base TeX set. */
+  | { readonly kind: "none"; readonly settings: PaperSettings | null }
+  | {
+      readonly kind: "resolved";
+      readonly settings: PaperSettings;
+      readonly preset: Preset;
+    }
+  /** `paperlint.json` does not parse. */
+  | { readonly kind: "settings-problem"; readonly problem: SettingsProblem }
+  /** `extends` does not resolve. */
+  | {
+      readonly kind: "preset-problem";
+      readonly settings: PaperSettings;
+      readonly problem: PresetProblem;
+    };
+
+/** A paper directory → its settings and its resolved preset. Reads through `deps.files`; never throws. */
+export function paperPreset(paperDir: string, deps: PresetDeps): PaperPreset {
+  const read = readPaperSettings(deps.files, paperDir);
+  if (!read.ok) return { kind: "settings-problem", problem: read.error };
+  const settings = read.value;
+  if (settings?.extends == null) return { kind: "none", settings };
+  const r = resolvePreset(settings.extends, join(paperDir, CONFIG_FILE), deps);
+  return r.ok
+    ? { kind: "resolved", settings, preset: r.value }
+    : { kind: "preset-problem", settings, problem: r.error };
+}
+
+/** The one-line reason a paper's settings or preset cannot be used, or null when they can. */
+export function paperPresetProblem(
+  paperDir: string,
+  p: PaperPreset,
+): string | null {
+  if (p.kind === "preset-problem")
+    return `${join(paperDir, CONFIG_FILE)}: ${presetProblemText(p.problem)}`;
+  if (p.kind !== "settings-problem") return null;
+  return `${join(paperDir, CONFIG_FILE)}: ${p.problem.why}`;
+}

package/src/reference-rules.ts

@@ -0,0 +1,229 @@
+/**
+ * The reference rules — `paper/author-list`, `paper/cite-exists`, `paper/refs-checked`,
+ * `paper/refs-fresh` — judge `_build/references.json` (`references.ts`), offline. `paperlint build`
+ * does the online work; lint never touches the network.
+ *
+ *   entry whose authors are the preprint's   paper/author-list (error), on the entry
+ *   entry whose identifier provably fails    paper/cite-exists (error), on the entry
+ *   no record, or recorded "not checked"     paper/refs-checked (warn) — like pdf/measured
+ *   bibliography edited after the build      paper/refs-fresh (error) — like pdf/fresh
+ *
+ * While the record is stale, the per-entry rules are silent: they would judge a bibliography
+ * that no longer exists, and refs-fresh already says so once. A paper with no bibliography gets
+ * nothing.
+ *
+ * `paper/author-list` used to live on PIPELINE-STATUS.md and ask whether the scorecard mentioned
+ * a run. It lives here now because its subject is the bibliography, and the record of the run is
+ * the run's own output.
+ */
+import { basename, dirname } from "node:path";
+import type { Files } from "./ports/files.ts";
+import {
+  bibHash,
+  bibliographyOf,
+  readReferences,
+  REFERENCES_FILE,
+  type Bibliography,
+} from "./references.ts";
+
+interface Loc {
+  readonly line: number;
+  readonly column: number;
+}
+interface RuleContext {
+  readonly filename: string;
+  readonly cwd: string;
+  readonly sourceCode: {
+    getLocFromIndex(i: number): Loc;
+  };
+  report(d: {
+    loc: { start: Loc; end: Loc };
+    messageId: string;
+    data?: Record<string, string>;
+  }): void;
+}
+export interface ReferenceRuleModule {
+  readonly meta: {
+    readonly type: "problem" | "suggestion";
+    readonly docs: { readonly description: string };
+    readonly schema: readonly object[];
+    readonly messages: Readonly<Record<string, string>>;
+  };
+  create(context: RuleContext): { "root:exit"?: () => void };
+}
+
+type Name = "author-list" | "cite-exists" | "refs-checked" | "refs-fresh";
+
+/** What one lint run knows about a paper's references. */
+type Assessment =
+  | { readonly kind: "no-bibliography" }
+  | { readonly kind: "unrecorded" }
+  | { readonly kind: "not-checked"; readonly why: string }
+  | { readonly kind: "stale" }
+  | {
+      readonly kind: "ready";
+      readonly bib: Bibliography;
+      readonly failing: readonly {
+        readonly key: string;
+        readonly rule: "author-list" | "cite-exists";
+        readonly why: string;
+      }[];
+    };
+
+function assess(files: Files, paperDir: string): Assessment {
+  const bib = bibliographyOf(files, paperDir);
+  if (bib === null) return { kind: "no-bibliography" };
+  const doc = readReferences(files, paperDir);
+  if (doc === null) return { kind: "unrecorded" };
+  if (doc.bib.sha256 !== bibHash(bib)) return { kind: "stale" };
+  if (doc.status === "not-checked")
+    return { kind: "not-checked", why: doc.why ?? "no reason recorded" };
+  const failing = doc.entries.flatMap((e) => [
+    ...(e.authors === "mismatch"
+      ? [{ key: e.key, rule: "author-list" as const, why: e.why ?? "" }]
+      : []),
+    ...(e.exists === "false"
+      ? [{ key: e.key, rule: "cite-exists" as const, why: e.why ?? "" }]
+      : []),
+  ]);
+  return { kind: "ready", bib, failing };
+}
+
+/** Where entry `key` starts in the source file: its `@type{key,` line, or the file's start. */
+function entryOffset(bib: Bibliography, key: string): number {
+  const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const m = new RegExp(`^@\\w+\\s*\\{\\s*${escaped}\\s*,`, "m").exec(bib.text);
+  return m ? bib.offset + m.index : 0;
+}
+
+const BUILD = "`npx paperlint build`";
+
+const META: Readonly<Record<Name, ReferenceRuleModule["meta"]>> = {
+  "author-list": {
+    type: "problem",
+    docs: {
+      description:
+        "each entry's authors are those of the version it cites, not the preprint's (recorded by paperlint build)",
+    },
+    schema: [],
+    messages: {
+      mismatch:
+        "`{{key}}`: the authors are not those of the version cited — {{why}}. The citation resolves and the id resolves, and the list is the PREPRINT's under a published venue",
+    },
+  },
+  "cite-exists": {
+    type: "problem",
+    docs: {
+      description:
+        "each entry's identifier resolves to the work cited (recorded by paperlint build)",
+    },
+    schema: [],
+    messages: {
+      missing: "`{{key}}` does not resolve to the work cited — {{why}}",
+    },
+  },
+  "refs-checked": {
+    type: "suggestion",
+    docs: {
+      description:
+        "the build checked the references online (existence, title, authors); a warning when it could not",
+    },
+    schema: [],
+    messages: {
+      unrecorded: `the references have not been checked — ${BUILD} checks them online and records the result in _build/${REFERENCES_FILE}`,
+      notChecked: `the last build could not check the references ({{why}}) — run ${BUILD} with network`,
+    },
+  },
+  "refs-fresh": {
+    type: "problem",
+    docs: {
+      description:
+        "the recorded reference verdicts are about the bibliography on disk, not an earlier one",
+    },
+    schema: [],
+    messages: {
+      stale: `the references changed since the last build checked them — run ${BUILD}`,
+    },
+  },
+};
+
+type Report = { at: number; messageId: string; data?: Record<string, string> };
+
+const JUDGES: Readonly<Record<Name, (a: Assessment) => Report[]>> = {
+  "author-list": (a) =>
+    a.kind === "ready"
+      ? a.failing
+          .filter((f) => f.rule === "author-list")
+          .map((f) => ({
+            at: entryOffset(a.bib, f.key),
+            messageId: "mismatch",
+            data: { key: f.key, why: f.why },
+          }))
+      : [],
+  "cite-exists": (a) =>
+    a.kind === "ready"
+      ? a.failing
+          .filter((f) => f.rule === "cite-exists")
+          .map((f) => ({
+            at: entryOffset(a.bib, f.key),
+            messageId: "missing",
+            data: { key: f.key, why: f.why },
+          }))
+      : [],
+  "refs-checked": (a) =>
+    a.kind === "unrecorded"
+      ? [{ at: 0, messageId: "unrecorded" }]
+      : a.kind === "not-checked"
+        ? [{ at: 0, messageId: "notChecked", data: { why: a.why } }]
+        : [],
+  "refs-fresh": (a) =>
+    a.kind === "stale" ? [{ at: 0, messageId: "stale" }] : [],
+};
+
+/** The four rules, reading through `files`. They act on `paper.tex` only. */
+export function referenceRules({
+  files,
+}: {
+  files: Files;
+}): Record<Name, ReferenceRuleModule> {
+  const make = (name: Name): ReferenceRuleModule => ({
+    meta: META[name],
+    create: (context) =>
+      basename(context.filename) !== "paper.tex"
+        ? {}
+        : {
+            "root:exit": () => {
+              const paperDir = dirname(context.filename);
+              const a = assess(files, paperDir);
+              // An external refs.bib: the entry is not in this file, so the finding sits at its
+              // start and names the key.
+              const external =
+                a.kind === "ready" && a.bib.source !== "paper.tex";
+              for (const r of JUDGES[name](a)) {
+                const loc = context.sourceCode.getLocFromIndex(
+                  external ? 0 : r.at,
+                );
+                context.report({
+                  loc: { start: loc, end: loc },
+                  messageId: r.messageId,
+                  ...(r.data ? { data: r.data } : {}),
+                });
+              }
+            },
+          },
+  });
+  return {
+    "author-list": make("author-list"),
+    "cite-exists": make("cite-exists"),
+    "refs-checked": make("refs-checked"),
+    "refs-fresh": make("refs-fresh"),
+  };
+}
+
+/** The level each is on at for every `paper.tex` in paperlint's own config. */
+export const REFERENCE_RULE_LEVELS = {
+  "paper/author-list": "error",
+  "paper/cite-exists": "error",
+  "paper/refs-checked": "warn",
+  "paper/refs-fresh": "error",
+} as const;