paperlint 2.0.1 → 3.0.0

package/src/paper-settings.ts

@@ -0,0 +1,208 @@
+/**
+ * `<paper>/paperlint.json` — ONE PAPER'S SETTINGS, parsed at the boundary, merged over the root's.
+ *
+ * One file name at two levels, one schema (lib/paper-config.mjs → SETTINGS_KEYS):
+ *
+ *   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)
+ *
+ * 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. A project-only key
+ * (`papersDir`, …) in a paper's file is refused too: it would be read nowhere.
+ */
+import { dirname, join } from "node:path";
+import {
+  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";
+import type { Files } from "./ports/files.ts";
+import {
+  parseRuleEntries,
+  type Parsed,
+  type RuleEntry,
+} from "./rules-config.ts";
+
+/** What one paper declares. Every absent field is null. */
+export interface PaperSettings {
+  /** The venue preset the paper is judged against: `paperlint:<name>` or a relative path. */
+  readonly extends: string | null;
+  /** The kind of paper (`short`, `research`, …), whose page limit applies. */
+  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 — `{ 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 };
+
+const KNOWN = Object.keys(SETTINGS_KEYS);
+const STRING_FIELDS = ["extends", "kind", "pdf"] as const;
+
+const isObject = (v: unknown): v is Readonly<Record<string, unknown>> =>
+  typeof v === "object" && v !== null && !Array.isArray(v);
+
+/** A string field: absent is null, anything but a non-empty string is the error. */
+function stringField(
+  d: Readonly<Record<string, unknown>>,
+  k: (typeof STRING_FIELDS)[number],
+): Result<string | null, string> {
+  const v = d[k];
+  // `"extends": null` is what `paperlint new` writes: no venue chosen yet.
+  if (v === undefined || (k === "extends" && v === null)) return ok(null);
+  return typeof v === "string" && v !== ""
+    ? ok(v)
+    : err(`"${k}" must be a non-empty string, got ${JSON.stringify(v)}`);
+}
+
+/** `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> = {};
+  for (const k of STRING_FIELDS) {
+    const f = stringField(d, k);
+    if (!f.ok) return f;
+    out[k] = f.value;
+  }
+  return ok({
+    extends: out["extends"] ?? null,
+    kind: out["kind"] ?? null,
+    pdf: out["pdf"] ?? null,
+  });
+}
+
+/** The parsed JSON of `paperlint.json` → the settings, or one line saying what is wrong. Pure. */
+export function parsePaperSettings(
+  json: unknown,
+): Result<PaperSettings, string> {
+  if (!isObject(json)) return err("must be a JSON object");
+  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) && !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,
+  });
+}
+
+const at = (p: string): AbsolutePath => p as AbsolutePath;
+
+/** A JSON file through `files`: undefined when absent, the problem when it does not parse. */
+function readJson(
+  files: Files,
+  path: string,
+): Result<unknown, SettingsProblem> {
+  const bytes = files.readBytes(at(path));
+  if (bytes === null) return ok(undefined);
+  try {
+    return ok(JSON.parse(new TextDecoder().decode(bytes)));
+  } catch (e) {
+    return err({ kind: "broken", why: `not JSON (${(e as Error).message})` });
+  }
+}
+
+/**
+ * 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.
+ */
+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}` });
+}
+
+/**
+ * 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));
+}
+
+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. 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 || 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.test.ts

@@ -0,0 +1,236 @@
+/**
+ * Venue presets: what `"extends"` in a paper's `paperlint.json` resolves to. Two spec forms —
+ * `paperlint:<name>` (shipped) and a relative path (the project's own) — a chain of at most four
+ * presets, merged block by block, and a display label derived from the spec.
+ *
+ * The shipped presets are read from the package's venues directory, so a shipped file that stops
+ * resolving shows here.
+ */
+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 { packageVenuesDir } from "../skills/paper-pipeline/scripts/consumer.mjs";
+import {
+  MAX_PRESET_DEPTH,
+  labelOf,
+  presetProblemText,
+  resolvePreset,
+} from "./presets.ts";
+
+const VENUES = packageVenuesDir();
+const shipped = Object.fromEntries(
+  readdirSync(VENUES)
+    .filter((f) => f.endsWith(".jsonc") || f.endsWith(".json"))
+    .map((f) => [join(VENUES, f), readFileSync(join(VENUES, f))]),
+);
+const PAPER_FILE = "/work/papers/p/paperlint.json";
+const deps = (extra: Record<string, string> = {}) => ({
+  files: memoryFiles({ ...shipped, ...extra }),
+  venuesDir: VENUES,
+});
+const resolve = (spec: string, extra: Record<string, string> = {}) =>
+  resolvePreset(spec, PAPER_FILE, deps(extra));
+
+describe("shipped presets", () => {
+  it("paperlint:agenticdev → agenticdev over acm-sigconf: the family's format, the venue's kinds", () => {
+    const r = resolve("paperlint:agenticdev");
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+    expect(r.value.chain.map((f) => f.split("/").pop())).toEqual([
+      "acm-sigconf.jsonc",
+      "agenticdev.jsonc",
+    ]);
+    expect(r.value.format.columns).toBe(2);
+    expect(r.value.format.fontsText).toBe("LinLibertine");
+    expect([...r.value.format.kinds.keys()]).toEqual(["short", "full", "demo"]);
+    expect(r.value.template).toBe("acmart");
+    expect("acmart" in r.value.tex.packages).toBe(true);
+    expect(r.value.label).toBe("agenticdev");
+  });
+
+  it("a paper may extend a family directly: format and fonts, and no kinds", () => {
+    const r = resolve("paperlint:acm-sigconf");
+    expect(r.ok && r.value.format.kinds.size).toBe(0);
+    expect(r.ok && r.value.format.pageWidthIn).toBe(8.5);
+  });
+
+  it("realm (ACL) stands alone: A4, no parent", () => {
+    const r = resolve("paperlint:realm");
+    expect(r.ok && r.value.chain.length).toBe(1);
+    expect(r.ok && r.value.format.pageWidthIn).toBe(8.27);
+  });
+
+  it("agenticdev turns pdf/last-page-balance on — its producer asks for balanced columns", () => {
+    const r = resolve("paperlint:agenticdev");
+    expect(r.ok && r.value.rules["pdf/last-page-balance"]).toEqual([
+      "error",
+      { tolerancePt: 120 },
+    ]);
+  });
+});
+
+describe("a project's own preset, by relative path", () => {
+  const usenix = JSON.stringify({
+    extends: "paperlint:acm-sigconf",
+    name: "USENIX Security",
+    format: {
+      columns: 1,
+      kinds: { full: { body_pages_max: 13, ref_pages_max: 0 } },
+    },
+    tex: { packages: { usenix: ["usenix.sty"] } },
+    rules: { "pdf/body-size": "off" },
+  });
+
+  it("./ is relative to the file that says it; merged per block, child wins", () => {
+    const r = resolve("../../venues/usenix-sec.jsonc", {
+      "/work/venues/usenix-sec.jsonc": usenix,
+    });
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+    // format: per key, child wins; the rest comes from the family
+    expect(r.value.format.columns).toBe(1);
+    expect(r.value.format.pageWidthIn).toBe(8.5);
+    // tex: union, never subtract
+    expect("usenix" in r.value.tex.packages).toBe(true);
+    expect("acmart" in r.value.tex.packages).toBe(true);
+    // rules: per id
+    expect(r.value.rules["pdf/body-size"]).toBe("off");
+    // label: the preset's `name` wins over the file name
+    expect(r.value.label).toBe("USENIX Security");
+  });
+
+  it("without `name`, the label is the file name without its extension", () => {
+    const r = resolve("./venues/usenix-sec.jsonc", {
+      "/work/papers/p/venues/usenix-sec.jsonc": JSON.stringify({
+        extends: "paperlint:acm-sigconf",
+      }),
+    });
+    expect(r.ok && r.value.label).toBe("usenix-sec");
+  });
+
+  it("a child kind replaces that kind wholesale; other kinds are kept", () => {
+    const r = resolve("./mine.jsonc", {
+      "/work/papers/p/mine.jsonc": JSON.stringify({
+        extends: "paperlint:agenticdev",
+        format: { kinds: { short: { body_pages_max: 6 } } },
+      }),
+    });
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+    expect(r.value.format.kinds.get("short")).toEqual({
+      bodyPagesMax: 6,
+      refPagesMax: null,
+    });
+    expect(r.value.format.kinds.get("full")?.bodyPagesMax).toBe(10);
+  });
+
+  it("rules: the leaf wins over its parent, per rule id", () => {
+    const r = resolve("./mine.jsonc", {
+      "/work/papers/p/mine.jsonc": JSON.stringify({
+        extends: "paperlint:agenticdev",
+        rules: { "pdf/last-page-balance": "off" },
+      }),
+    });
+    expect(r.ok && r.value.rules["pdf/last-page-balance"]).toBe("off");
+  });
+});
+
+describe("what does not resolve, and says why", () => {
+  it.each([
+    [
+      "an npm package name",
+      "@acme/venues",
+      "unsupported",
+      /npm presets: not yet supported/,
+    ],
+    ["a bare name", "agenticdev", "unsupported", /paperlint:agenticdev/],
+    [
+      "a shipped name with a typo",
+      "paperlint:agenticdve",
+      "not-found",
+      /acm-sigconf, agenticdev, aisec, realm/,
+    ],
+    ["the base TeX set", "paperlint:tex-base", "not-found", /agenticdev/],
+    [
+      "a relative file that is not there",
+      "./nope.jsonc",
+      "not-found",
+      /nope\.jsonc/,
+    ],
+  ])("%s", (_, spec, kind, text) => {
+    const r = resolve(spec);
+    expect(r.ok).toBe(false);
+    if (r.ok) return;
+    expect(r.error.kind).toBe(kind);
+    expect(presetProblemText(r.error)).toMatch(text);
+  });
+});
+
+describe("chains that do not resolve", () => {
+  it("a cycle is refused, naming the chain", () => {
+    const r = resolve("./a.jsonc", {
+      "/work/papers/p/a.jsonc": JSON.stringify({ extends: "./b.jsonc" }),
+      "/work/papers/p/b.jsonc": JSON.stringify({ extends: "./a.jsonc" }),
+    });
+    expect(r.ok).toBe(false);
+    if (r.ok) return;
+    expect(r.error.kind).toBe("cycle");
+    expect(presetProblemText(r.error)).toMatch(
+      /a\.jsonc → .*b\.jsonc → .*a\.jsonc/,
+    );
+  });
+
+  it(`a chain longer than ${String(MAX_PRESET_DEPTH)} is refused, printing it`, () => {
+    const files: Record<string, string> = {};
+    for (let i = 1; i <= 5; i++)
+      files[`/work/papers/p/p${String(i)}.jsonc`] = JSON.stringify({
+        extends: i < 5 ? `./p${String(i + 1)}.jsonc` : "paperlint:acm-sigconf",
+      });
+    const r = resolve("./p1.jsonc", files);
+    expect(r.ok).toBe(false);
+    if (r.ok) return;
+    expect(r.error.kind).toBe("too-deep");
+    expect(presetProblemText(r.error)).toMatch(/p1\.jsonc → .*p4\.jsonc/);
+  });
+
+  it("a chain of exactly the limit resolves", () => {
+    const r = resolve("./p1.jsonc", {
+      "/work/papers/p/p1.jsonc": JSON.stringify({ extends: "./p2.jsonc" }),
+      "/work/papers/p/p2.jsonc": JSON.stringify({
+        extends: "paperlint:agenticdev",
+      }),
+    });
+    expect(r.ok && r.value.chain.length).toBe(MAX_PRESET_DEPTH);
+  });
+
+  it("a preset that fails the schema is named with its file", () => {
+    const r = resolve("./bad.jsonc", {
+      "/work/papers/p/bad.jsonc": JSON.stringify({
+        extends: "paperlint:acm-sigconf",
+        colums: 2,
+      }),
+    });
+    expect(r.ok).toBe(false);
+    if (r.ok) return;
+    expect(r.error.kind).toBe("broken");
+    expect(presetProblemText(r.error)).toMatch(/bad\.jsonc/);
+  });
+
+  it("a preset with no `extends` must carry `tex` (it is a root)", () => {
+    const r = resolve("./root.jsonc", {
+      "/work/papers/p/root.jsonc": JSON.stringify({ format: { columns: 1 } }),
+    });
+    expect(r.ok).toBe(false);
+  });
+});
+
+describe("labelOf — display only, never used to resolve", () => {
+  it.each([
+    ["paperlint:agenticdev", "agenticdev"],
+    ["./venues/usenix-sec.jsonc", "usenix-sec"],
+    ["../shared/acl.json", "acl"],
+  ])("%s → %s", (spec, label) => {
+    expect(labelOf(spec)).toBe(label);
+  });
+});