paperlint 2.1.0 → 3.0.0

package/src/paper-settings.ts

@@ -1,27 +1,26 @@
 /**
- * `<paper>/paperlint.json` — ONE PAPER'S SETTINGS, parsed at the boundary.
+ * `<paper>/paperlint.json` — ONE PAPER'S SETTINGS, parsed at the boundary, merged over the root's.
  *
- * The middle of three levels, each named after the tool (lib/paper-config.mjs):
+ * One file name at two levels, one schema (lib/paper-config.mjs → SETTINGS_KEYS):
  *
- *   package.json → "paperlint"     the project
+ *   paperlint.json                 the project (optional): papersDir, rules, defaults
  *   <paper>/paperlint.json         this paper: { extends, kind, pdf, rules }
  *   a venue preset                 `paperlint:<name>` (shipped) or `./x.jsonc` (src/presets.ts)
  *
- * Every reader — the build, the facts writer, the venue rules, `paperlint lint` — goes through
- * `readPaperSettings`, so there is one answer to "what does this paper declare".
+ * The paper's `extends`, `kind` and `pdf` win over the root's; with no own value, the root's is
+ * the default. Every reader — the build, the facts writer, the venue rules, `paperlint lint` —
+ * goes through `readPaperSettings`, so there is one answer to "what does this paper declare".
  *
  * 🔴 STRICT. An unknown key is an error naming the known ones: `"venu": "aisec"` would otherwise
- * read as "no preset", and every venue check would be silently off.
- *
- * 🔴 THE OLD NAME IS NOT READ. Before 2.1.0 the file was `venue.json`. A fallback would keep it
- * working forever and leave two names for one file; instead a `venue.json` with no `paperlint.json`
- * is an error that names `npx paperlint init`, which moves it (`migrationOf` plans that move).
+ * read as "no preset", and every venue check would be silently off. A project-only key
+ * (`papersDir`, …) in a paper's file is refused too: it would be read nowhere.
  */
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import {
-  LEGACY_PAPER_SETTINGS_FILE,
-  PAPER_SETTINGS_FILE,
-  PAPER_SETTINGS_KEYS,
+  CONFIG_FILE,
+  ROOT_ONLY_KEYS,
+  SETTINGS_KEYS,
+  findProjectRoot,
 } from "../lib/paper-config.mjs";
 import type { AbsolutePath } from "./domain/paths.ts";
 import { err, ok, type Result } from "./domain/result.ts";
@@ -40,16 +39,17 @@ export interface PaperSettings {
   readonly kind: string | null;
   /** The built PDF relative to the paper, when it is not `paper.pdf`. */
   readonly pdf: string | null;
-  /** Rule overrides for this paper alone, NOT yet checked against the shipped rules. */
-  readonly rules: Readonly<Record<string, unknown>> | null;
+  /**
+   * Rule overrides for this paper alone — `{ id: severity }` or ESLint blocks — NOT yet checked
+   * against the shipped rules.
+   */
+  readonly rules: Readonly<Record<string, unknown>> | readonly unknown[] | null;
 }
 
 /** Why a paper's settings cannot be read. */
-export type SettingsProblem =
-  | { readonly kind: "broken"; readonly why: string }
-  | { readonly kind: "legacy" };
+export type SettingsProblem = { readonly kind: "broken"; readonly why: string };
 
-const KNOWN = Object.keys(PAPER_SETTINGS_KEYS);
+const KNOWN = Object.keys(SETTINGS_KEYS);
 const STRING_FIELDS = ["extends", "kind", "pdf"] as const;
 
 const isObject = (v: unknown): v is Readonly<Record<string, unknown>> =>
@@ -68,8 +68,8 @@ function stringField(
     : err(`"${k}" must be a non-empty string, got ${JSON.stringify(v)}`);
 }
 
-/** `extends`, `kind` and `pdf`, each null when absent. */
-function stringFields(
+/** `extends`, `kind` and `pdf`, each null when absent. The root file's defaults parse the same way. */
+export function stringFields(
   d: Readonly<Record<string, unknown>>,
 ): Result<Pick<PaperSettings, (typeof STRING_FIELDS)[number]>, string> {
   const out: Record<string, string | null> = {};
@@ -93,11 +93,18 @@ export function parsePaperSettings(
   const unknown = Object.keys(json).filter((k) => !KNOWN.includes(k));
   if (unknown.length > 0)
     return err(`unknown key "${unknown[0]}" — known keys: ${KNOWN.join(", ")}`);
+  const project = Object.keys(json).filter((k) => ROOT_ONLY_KEYS.includes(k));
+  if (project.length > 0)
+    return err(
+      `"${project[0]}" is a project setting — set it in the root ${CONFIG_FILE}, not in a paper's`,
+    );
   const fields = stringFields(json);
   if (!fields.ok) return fields;
   const rules = json["rules"];
-  if (rules !== undefined && !isObject(rules))
-    return err(`"rules" must be an object of rule id → severity`);
+  if (rules !== undefined && !isObject(rules) && !Array.isArray(rules))
+    return err(
+      `"rules" must be an object of rule id → severity, or a list of ESLint blocks`,
+    );
   return ok({
     ...fields.value,
     rules: rules ?? null,
@@ -106,101 +113,96 @@ export function parsePaperSettings(
 
 const at = (p: string): AbsolutePath => p as AbsolutePath;
 
-/**
- * A paper's settings: null when it has no `paperlint.json`; the problem when the file does not parse
- * or only the pre-2.1.0 `venue.json` is there. Reads through `files` only; never throws.
- */
-export function readPaperSettings(
+/** A JSON file through `files`: undefined when absent, the problem when it does not parse. */
+function readJson(
   files: Files,
-  paperDir: string,
-): Result<PaperSettings | null, SettingsProblem> {
-  const bytes = files.readBytes(at(join(paperDir, PAPER_SETTINGS_FILE)));
-  if (bytes === null)
-    return files.readBytes(at(join(paperDir, LEGACY_PAPER_SETTINGS_FILE))) ===
-      null
-      ? ok(null)
-      : err({ kind: "legacy" });
-  let json: unknown;
+  path: string,
+): Result<unknown, SettingsProblem> {
+  const bytes = files.readBytes(at(path));
+  if (bytes === null) return ok(undefined);
   try {
-    json = JSON.parse(new TextDecoder().decode(bytes));
+    return ok(JSON.parse(new TextDecoder().decode(bytes)));
   } catch (e) {
     return err({ kind: "broken", why: `not JSON (${(e as Error).message})` });
   }
-  const parsed = parsePaperSettings(json);
-  return parsed.ok ? parsed : err({ kind: "broken", why: parsed.error });
 }
 
-// ── the move from venue.json ────────────────────────────────────────────────────────────
-
-/** What `paperlint init` does with one paper's files. */
-export type Migration =
-  /** No `venue.json`: nothing to do. */
-  | { readonly kind: "none" }
-  /** Only `venue.json`: write `text` as `paperlint.json`, delete `venue.json`. */
-  | { readonly kind: "move"; readonly text: string }
-  /** Both, and `paperlint.json` already says the same: the old one is a leftover, delete it. */
-  | { readonly kind: "drop-legacy" }
-  /** Both, and they differ: refuse — there is no way to know which one the author means. */
-  | { readonly kind: "conflict" }
-  /** `venue.json` is not a JSON object: refuse, naming why. */
-  | { readonly kind: "broken"; readonly why: string };
-
 /**
- * A `venue.json` object → the `paperlint.json` object that says the same, in one move:
- * `"venue": "aisec"` becomes `"extends": "paperlint:aisec"` (the only presets that existed were the
- * shipped ones), and the `"_"` some files used as a comment becomes `"$comment"`. Every other key
- * is carried as it is — an unknown one is then refused by name, as in any `paperlint.json`. Pure.
+ * The root file's defaults for every paper — `extends`, `kind`, `pdf` — found by walking up from
+ * the paper's parent. None when there is no root file, or it is not an object; a root file that
+ * is wrong in another way is reported by `paperlint lint`, which parses it strictly.
  */
-export function fromLegacy(
-  legacy: Readonly<Record<string, unknown>>,
-): Record<string, unknown> {
-  const out: Record<string, unknown> = {};
-  for (const [k, v] of Object.entries(legacy)) {
-    if (k === "venue" && typeof v === "string")
-      out["extends"] = `paperlint:${v}`;
-    else if (k === "_") out["$comment"] = v;
-    else out[k] = v;
-  }
-  return out;
+function rootDefaults(
+  files: Files,
+  paperDir: string,
+): Result<Defaults | null, SettingsProblem> {
+  const root = findProjectRoot(dirname(paperDir), (p) => files.isFile(at(p)));
+  const json = readJson(files, join(root, CONFIG_FILE));
+  if (!json.ok) return json;
+  if (!isObject(json.value)) return ok(null);
+  const fields = stringFields(json.value);
+  return fields.ok
+    ? fields
+    : err({ kind: "broken", why: `the root ${CONFIG_FILE}: ${fields.error}` });
 }
 
-const jsonOf = (b: Uint8Array): unknown => {
-  try {
-    return JSON.parse(new TextDecoder().decode(b));
-  } catch {
-    return undefined;
-  }
-};
+/**
+ * A paper's settings, its own `paperlint.json` merged over the root's defaults: null when neither
+ * says anything; the problem when a file does not parse. Reads through `files` only; never throws.
+ */
+export function readPaperSettings(
+  files: Files,
+  paperDir: string,
+): Result<PaperSettings | null, SettingsProblem> {
+  const own = readJson(files, join(paperDir, CONFIG_FILE));
+  if (!own.ok) return own;
+  const parsed =
+    own.value === undefined ? ok(null) : parsePaperSettings(own.value);
+  if (!parsed.ok) return err({ kind: "broken", why: parsed.error });
+  const defaults = rootDefaults(files, paperDir);
+  if (!defaults.ok) return defaults;
+  return ok(merge(defaults.value, parsed.value));
+}
 
-/** The move, planned from the two files' bytes (null = absent). Pure. */
-export function migrationOf(
-  legacy: Uint8Array | null,
-  current: Uint8Array | null,
-): Migration {
-  if (legacy === null) return { kind: "none" };
-  const old = jsonOf(legacy);
-  if (!isObject(old)) return { kind: "broken", why: "it is not a JSON object" };
-  const next = fromLegacy(old);
-  if (current === null)
-    return { kind: "move", text: `${JSON.stringify(next, null, 2)}\n` };
-  return JSON.stringify(jsonOf(current)) === JSON.stringify(next)
-    ? { kind: "drop-legacy" }
-    : { kind: "conflict" };
+type Defaults = Pick<PaperSettings, "extends" | "kind" | "pdf">;
+const NO_DEFAULTS: Defaults = { extends: null, kind: null, pdf: null };
+
+/** The paper's own values win; each absent one falls back to the root's. */
+function merge(
+  root: Defaults | null,
+  paper: PaperSettings | null,
+): PaperSettings | null {
+  const r = root ?? NO_DEFAULTS;
+  const p = paper ?? { ...NO_DEFAULTS, rules: null };
+  const merged: PaperSettings = {
+    extends: p.extends ?? r.extends,
+    kind: p.kind ?? r.kind,
+    pdf: p.pdf ?? r.pdf,
+    rules: p.rules,
+  };
+  return paper === null && Object.values(merged).every((v) => v === null)
+    ? null
+    : merged;
 }
 
 // ── the paper's rule overrides ──────────────────────────────────────────────────────────
 
 /**
  * `rules` → the parsed entries (rule id → severity or `[severity, options]`), or the error naming
- * the file. Null when the paper sets none. The block they go into is built where the config is
- * (`paperRuleBlocks` in cli.ts), which also knows which files a paper's rules may reach.
+ * the file. Null when the paper sets none. Blocks (the list form) are parsed by the caller, which
+ * knows the file globs they are relative to (`paperRuleBlocks` in cli.ts).
  */
 export function paperRules(
   paperDir: string,
   settings: PaperSettings,
   shipped: ReadonlySet<string>,
 ): Parsed<Record<string, RuleEntry> | null> {
-  if (settings.rules === null) return { ok: true, value: null };
-  const where = `${join(paperDir, PAPER_SETTINGS_FILE)} → "rules"`;
-  return parseRuleEntries(settings.rules, where, shipped);
+  if (settings.rules === null || Array.isArray(settings.rules))
+    return { ok: true, value: null };
+  const where = `${join(paperDir, CONFIG_FILE)} → "rules"`;
+  return parseRuleEntries(
+    settings.rules as Readonly<Record<string, unknown>>,
+    where,
+    shipped,
+  );
 }

package/src/ports/check-references.ts

@@ -0,0 +1,28 @@
+/**
+ * Checking a paper's references online — shaped by what the build records, not by what DBLP or
+ * Crossref answer. The adapter (`adapters/references/`) runs the package's two checkers; a test
+ * passes a function.
+ */
+
+/** What one bibliography entry came to. */
+export interface EntryVerdict {
+  readonly key: string;
+  /**
+   * Does the cited work exist, and does its title match? `false` only on a positive disproof (an
+   * identifier that resolves to nothing or to another work); a work that simply was not found is
+   * `unresolvable`, never `false`.
+   */
+  readonly exists: "true" | "false" | "unresolvable";
+  /** Are the authors those of the version cited (not the preprint's)? */
+  readonly authors: "match" | "mismatch" | "skipped" | "unchecked";
+  /** Why, in one line, when either is not a plain pass. */
+  readonly why?: string;
+}
+
+export type ReferencesCheck =
+  | { readonly kind: "checked"; readonly entries: readonly EntryVerdict[] }
+  /** Nothing could be asked — no network, every service down. Never a pass. */
+  | { readonly kind: "not-checked"; readonly why: string };
+
+/** The bibliography's text (BibTeX) → the verdicts. Never throws: a failure is `not-checked`. */
+export type CheckReferences = (bib: string) => Promise<ReferencesCheck>;

package/src/presets.ts

@@ -47,11 +47,7 @@ import {
   type PaperSettings,
   type SettingsProblem,
 } from "./paper-settings.ts";
-import {
-  LEGACY_PAPER_SETTINGS_FILE,
-  LEGACY_PAPER_SETTINGS_MESSAGE,
-  PAPER_SETTINGS_FILE,
-} from "../lib/paper-config.mjs";
+import { CONFIG_FILE } from "../lib/paper-config.mjs";
 
 /** The prefix of a shipped preset's spec. */
 export const SHIPPED_PREFIX = "paperlint:";
@@ -268,7 +264,7 @@ export type PaperPreset =
       readonly settings: PaperSettings;
       readonly preset: Preset;
     }
-  /** `paperlint.json` does not parse, or only a pre-2.1.0 `venue.json` is there. */
+  /** `paperlint.json` does not parse. */
   | { readonly kind: "settings-problem"; readonly problem: SettingsProblem }
   /** `extends` does not resolve. */
   | {
@@ -283,11 +279,7 @@ export function paperPreset(paperDir: string, deps: PresetDeps): PaperPreset {
   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, PAPER_SETTINGS_FILE),
-    deps,
-  );
+  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 };
@@ -299,9 +291,7 @@ export function paperPresetProblem(
   p: PaperPreset,
 ): string | null {
   if (p.kind === "preset-problem")
-    return `${join(paperDir, PAPER_SETTINGS_FILE)}: ${presetProblemText(p.problem)}`;
+    return `${join(paperDir, CONFIG_FILE)}: ${presetProblemText(p.problem)}`;
   if (p.kind !== "settings-problem") return null;
-  return p.problem.kind === "legacy"
-    ? `${join(paperDir, LEGACY_PAPER_SETTINGS_FILE)}: ${LEGACY_PAPER_SETTINGS_MESSAGE}`
-    : `${join(paperDir, PAPER_SETTINGS_FILE)}: ${p.problem.why}`;
+  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;