paperlint 2.0.0 → 2.1.0

package/src/paper-settings.ts

@@ -0,0 +1,206 @@
+/**
+ * `<paper>/paperlint.json` — ONE PAPER'S SETTINGS, parsed at the boundary.
+ *
+ * The middle of three levels, each named after the tool (lib/paper-config.mjs):
+ *
+ *   package.json → "paperlint"     the project
+ *   <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".
+ *
+ * 🔴 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).
+ */
+import { join } from "node:path";
+import {
+  LEGACY_PAPER_SETTINGS_FILE,
+  PAPER_SETTINGS_FILE,
+  PAPER_SETTINGS_KEYS,
+} 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, NOT yet checked against the shipped rules. */
+  readonly rules: Readonly<Record<string, unknown>> | null;
+}
+
+/** Why a paper's settings cannot be read. */
+export type SettingsProblem =
+  | { readonly kind: "broken"; readonly why: string }
+  | { readonly kind: "legacy" };
+
+const KNOWN = Object.keys(PAPER_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. */
+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 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`);
+  return ok({
+    ...fields.value,
+    rules: rules ?? null,
+  });
+}
+
+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(
+  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;
+  try {
+    json = 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.
+ */
+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;
+}
+
+const jsonOf = (b: Uint8Array): unknown => {
+  try {
+    return JSON.parse(new TextDecoder().decode(b));
+  } catch {
+    return undefined;
+  }
+};
+
+/** 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" };
+}
+
+// ── 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.
+ */
+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);
+}

package/src/pdf-facts.harness.mjs

@@ -116,7 +116,7 @@ const named = (facts, name) =>
     JSON.stringify(r),
   );
 }
-const tmp = realpathSync(mkdtempSync(join(tmpdir(), "rpp-pdf-facts-")));
+const tmp = realpathSync(mkdtempSync(join(tmpdir(), "paperlint-pdf-facts-")));
 try {
   const notPdf = join(tmp, "paper.pdf");
   writeFileSync(notPdf, "%PDF-stale\n");

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);
+  });
+});