paperlint 2.0.1 → 3.0.0

package/src/paper-settings-commands.test.ts

@@ -0,0 +1,274 @@
+/**
+ * `paperlint.json` through the commands, on a real directory: `paperlint lint` applies a paper's
+ * `rules` to that paper alone and refuses an unknown rule id.
+ */
+import {
+  mkdirSync,
+  mkdtempSync,
+  realpathSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { run, toolchainTex } from "./cli.ts";
+
+const dirs: string[] = [];
+afterEach(() => {
+  for (const d of dirs.splice(0)) rmSync(d, { recursive: true, force: true });
+});
+
+/** A project with two papers, `a` and `b`, each with paper.tex and PIPELINE-STATUS.md. */
+function project(files: Record<string, string> = {}): string {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "paperlint-settings-")));
+  dirs.push(root);
+  const all: Record<string, string> = {
+    "package.json": JSON.stringify({ name: "c", private: true }),
+    "papers/a/paper.tex":
+      "\\documentclass{article}\n\\begin{document}x\\end{document}\n",
+    "papers/a/PIPELINE-STATUS.md": "---\nstages: []\n---\n",
+    "papers/b/paper.tex":
+      "\\documentclass{article}\n\\begin{document}x\\end{document}\n",
+    "papers/b/PIPELINE-STATUS.md": "---\nstages: []\n---\n",
+    ...files,
+  };
+  for (const [p, text] of Object.entries(all)) {
+    mkdirSync(join(root, p, ".."), { recursive: true });
+    writeFileSync(join(root, p), text);
+  }
+  return root;
+}
+
+async function lint(
+  root: string,
+): Promise<{ code: number; out: string; err: string }> {
+  const out: string[] = [];
+  const err: string[] = [];
+  const code = await run(["lint", "--json"], {
+    cwd: root,
+    log: (s: string) => out.push(s),
+    err: (s: string) => err.push(s),
+  });
+  return { code, out: out.join("\n"), err: err.join("\n") };
+}
+
+const rulesIn = (stdout: string, paper: string): string[] =>
+  (JSON.parse(stdout) as { filePath: string; messages: { ruleId: string }[] }[])
+    .filter((r) => r.filePath.endsWith(join(paper, "paper.tex")))
+    .flatMap((r) => r.messages.map((m) => m.ruleId));
+
+describe("paperlint lint — `rules` in a paper's paperlint.json", () => {
+  it("turns an optional rule on for that paper alone", async () => {
+    const root = project({
+      "papers/a/paperlint.json": JSON.stringify({
+        rules: { "pdf/last-page-balance": "error" },
+      }),
+    });
+    const r = await lint(root);
+    // The rule is on for `a` (no facts file: it says so, loudly) and for `b` it does not exist.
+    expect(rulesIn(r.out, "a")).toContain("pdf/last-page-balance");
+    expect(rulesIn(r.out, "b")).not.toContain("pdf/last-page-balance");
+  });
+
+  it("🔴 the paper's own `rules` come after the root paperlint.json's, so they win", async () => {
+    const root = project({
+      "paperlint.json": JSON.stringify({
+        rules: [
+          {
+            files: ["papers/*/**"],
+            rules: { "pdf/last-page-balance": "error" },
+          },
+        ],
+      }),
+      "papers/a/paperlint.json": JSON.stringify({
+        rules: { "pdf/last-page-balance": "off" },
+      }),
+    });
+    const r = await lint(root);
+    expect(rulesIn(r.out, "a")).not.toContain("pdf/last-page-balance");
+    expect(rulesIn(r.out, "b")).toContain("pdf/last-page-balance");
+  });
+
+  it.each([
+    [
+      "an unknown rule id",
+      { rules: { "pdf/no-such-rule": "error" } },
+      /not a rule paperlint ships/,
+    ],
+    ["an unknown key", { venu: "aisec" }, /unknown key "venu"/],
+  ])("refuses %s before linting, naming the file", async (_, settings, why) => {
+    const root = project({
+      "papers/a/paperlint.json": JSON.stringify(settings),
+    });
+    const r = await lint(root);
+    expect(r.code).toBe(2);
+    expect(r.err).toMatch(why);
+    expect(r.err).toMatch(/papers\/a\/paperlint\.json/);
+  });
+});
+
+describe("papersDir — optional, `papers` by default", () => {
+  it("no paperlint.json, papers/x/paper.tex: that paper is linted", async () => {
+    const r = await lint(project());
+    expect(r.code).toBe(0);
+    expect(
+      (JSON.parse(r.out) as { filePath: string }[]).map((f) =>
+        f.filePath.slice(f.filePath.indexOf("papers/")),
+      ),
+    ).toEqual(
+      expect.arrayContaining(["papers/a/paper.tex", "papers/b/paper.tex"]),
+    );
+  });
+
+  it("🔴 no paperlint.json and no papers/: exit 2 and the one clear sentence", async () => {
+    const root = realpathSync(mkdtempSync(join(tmpdir(), "paperlint-empty-")));
+    dirs.push(root);
+    writeFileSync(join(root, "package.json"), "{}");
+    const r = await lint(root);
+    expect(r.code).toBe(2);
+    expect(r.err).toBe(
+      'no papers in papers/ — create one with `npx paperlint new <name>`, or set "papersDir" in paperlint.json if your papers live elsewhere',
+    );
+  });
+
+  it("an explicit papersDir is honored", async () => {
+    const root = project({
+      "paperlint.json": JSON.stringify({ papersDir: "docs/drafts" }),
+      "docs/drafts/c/paper.tex":
+        "\\documentclass{article}\n\\begin{document}x\\end{document}\n",
+      "docs/drafts/c/PIPELINE-STATUS.md": "---\nstages: []\n---\n",
+    });
+    const r = await lint(root);
+    const linted = (JSON.parse(r.out) as { filePath: string }[]).map((f) =>
+      f.filePath.slice(root.length + 1),
+    );
+    expect(linted).toContain("docs/drafts/c/paper.tex");
+    expect(linted.some((f) => f.startsWith("papers/"))).toBe(false);
+  });
+
+  it("run from inside a paper, the root file is still found and papersDir is relative to it", async () => {
+    const root = project({
+      "paperlint.json": JSON.stringify({ papersDir: "papers" }),
+      "papers/a/paperlint.json": JSON.stringify({ kind: "short" }),
+    });
+    const out: string[] = [];
+    const code = await run(["lint", "--json"], {
+      cwd: join(root, "papers/a"),
+      log: (x: string) => out.push(x),
+      err: () => {},
+    });
+    expect(code).toBe(0);
+    expect(out.join("\n")).toMatch(/papers\/b\/paper\.tex/);
+  });
+});
+
+describe("paperlint lint — the venue preset's rules", () => {
+  it("agenticdev's preset turns pdf/last-page-balance on for its paper alone", async () => {
+    const root = project({
+      "papers/a/paperlint.json": JSON.stringify({
+        extends: "paperlint:agenticdev",
+        kind: "short",
+      }),
+    });
+    const cfgOf = await import("./cli.ts").then((m) =>
+      m.paperRuleBlocks([join(root, "papers")]),
+    );
+    expect(cfgOf.ok && cfgOf.value).toEqual({
+      preset: [
+        {
+          basePath: join(root, "papers/a"),
+          files: expect.arrayContaining([
+            "**/paper.tex",
+            "**/PIPELINE-STATUS.md",
+          ]),
+          rules: { "pdf/last-page-balance": ["error", { tolerancePt: 120 }] },
+        },
+      ],
+      own: [],
+    });
+  });
+
+  it("🔴 an unbuilt agenticdev paper: ONE warning (pdf/measured), and no balance error", async () => {
+    const root = project({
+      "papers/a/paperlint.json": JSON.stringify({
+        extends: "paperlint:agenticdev",
+        kind: "short",
+      }),
+    });
+    const r = await lint(root);
+    expect(r.code).toBe(0);
+    expect(rulesIn(r.out, "a")).toEqual(["pdf/measured"]);
+  });
+});
+
+describe("paperlint lint — the paper over its preset, and the project's own presets", () => {
+  it("the paper's own rules win over its preset's", async () => {
+    const root = project({
+      "papers/a/paperlint.json": JSON.stringify({
+        extends: "paperlint:agenticdev",
+        rules: { "pdf/last-page-balance": "off" },
+      }),
+    });
+    const blocks = await import("./cli.ts").then((m) =>
+      m.paperRuleBlocks([join(root, "papers")]),
+    );
+    // The preset's block comes first and the paper's own after it: the later block wins.
+    expect(blocks.ok && blocks.value.preset[0]?.rules).toEqual({
+      "pdf/last-page-balance": ["error", { tolerancePt: 120 }],
+    });
+    expect(blocks.ok && blocks.value.own[0]?.rules).toEqual({
+      "pdf/last-page-balance": "off",
+    });
+  });
+
+  it("a project's own preset, by relative path: its rules apply, an unknown rule id is refused", async () => {
+    const root = project({
+      "venues/usenix-sec.jsonc": JSON.stringify({
+        extends: "paperlint:acm-sigconf",
+        rules: { "pdf/no-such-rule": "error" },
+      }),
+      "papers/a/paperlint.json": JSON.stringify({
+        extends: "../../venues/usenix-sec.jsonc",
+      }),
+    });
+    const r = await lint(root);
+    expect(r.code).toBe(2);
+    expect(r.err).toMatch(/usenix-sec\.jsonc.*not a rule paperlint ships/);
+  });
+
+  it("a typo in extends is a pdf/profile error listing the shipped presets", async () => {
+    const root = project({
+      "papers/a/paperlint.json": JSON.stringify({
+        extends: "paperlint:agenticdve",
+      }),
+    });
+    const r = await lint(root);
+    expect(r.code).toBe(1);
+    expect(r.out).toMatch(/acm-sigconf, agenticdev, aisec, realm/);
+  });
+});
+
+describe("paperlint toolchain — installs what the project's own presets need", () => {
+  it("the shipped union plus a relative preset's tex packages", () => {
+    const root = project({
+      "venues/usenix-sec.jsonc": JSON.stringify({
+        extends: "paperlint:acm-sigconf",
+        tex: { packages: { usenix: ["usenix.sty"] } },
+      }),
+      "papers/a/paperlint.json": JSON.stringify({
+        extends: "../../venues/usenix-sec.jsonc",
+      }),
+    });
+    const tex = toolchainTex(root);
+    expect(tex.packages["usenix"]).toEqual(["usenix.sty"]);
+    expect("acmart" in tex.packages).toBe(true);
+    expect("hyperref" in tex.packages).toBe(true);
+  });
+
+  it("without papers of its own: the shipped union alone", () => {
+    const tex = toolchainTex(project());
+    expect("usenix" in tex.packages).toBe(false);
+    expect("acmart" in tex.packages).toBe(true);
+  });
+});

package/src/paper-settings.test.ts

@@ -0,0 +1,249 @@
+/**
+ * `<paper>/paperlint.json` — the per-paper settings file: parsed strictly, merged over the root
+ * `paperlint.json`'s defaults, and `rules` turned into an ESLint block for that paper alone.
+ */
+import { describe, expect, it } from "vitest";
+import { memoryFiles } from "./adapters/memory/index.ts";
+import type { AbsolutePath } from "./domain/paths.ts";
+import { findProjectRoot } from "../lib/paper-config.mjs";
+import {
+  paperRules,
+  parsePaperSettings,
+  readPaperSettings,
+} from "./paper-settings.ts";
+
+const PAPER = "/work/papers/p";
+const SHIPPED = new Set([
+  "pdf/last-page-balance",
+  "pdf/profile",
+  "paper/section-word",
+]);
+
+describe("parsePaperSettings", () => {
+  it("reads extends, kind, pdf and rules; every absent field is null", () => {
+    expect(
+      parsePaperSettings({ extends: "paperlint:aisec", kind: "research" }),
+    ).toEqual({
+      ok: true,
+      value: {
+        extends: "paperlint:aisec",
+        kind: "research",
+        pdf: null,
+        rules: null,
+      },
+    });
+    expect(parsePaperSettings({})).toEqual({
+      ok: true,
+      value: { extends: null, kind: null, pdf: null, rules: null },
+    });
+  });
+
+  it("extends: null is valid and means no venue chosen yet — what `paperlint new` writes", () => {
+    expect(parsePaperSettings({ extends: null })).toEqual({
+      ok: true,
+      value: { extends: null, kind: null, pdf: null, rules: null },
+    });
+  });
+});
+
+describe("parsePaperSettings — optional keys", () => {
+  it("accepts $comment, JSON Schema's comment keyword, and ignores it", () => {
+    expect(
+      parsePaperSettings({ extends: "paperlint:aisec", $comment: "why" }).ok,
+    ).toBe(true);
+  });
+
+  it.each([
+    [
+      "an unknown key (a typo is not silent)",
+      { venu: "aisec" },
+      /unknown key "venu" — known keys: papersDir, structure, rules, extends, kind, pdf/,
+    ],
+    [
+      "a comment key other than `$comment`",
+      { extends: "paperlint:aisec", _: "note" },
+      /unknown key "_"/,
+    ],
+    [
+      "an extends that is not a string",
+      { extends: 3 },
+      /"extends" must be a non-empty string/,
+    ],
+    [
+      "an empty extends",
+      { extends: "" },
+      /"extends" must be a non-empty string/,
+    ],
+    [
+      "rules that are neither an object nor a list of blocks",
+      { rules: "pdf/profile" },
+      /"rules" must be an object/,
+    ],
+    [
+      "🔴 papersDir — a project setting, refused in a paper's file",
+      { papersDir: "papers" },
+      /"papersDir" is a project setting — set it in the root paperlint\.json/,
+    ],
+    ["not an object at all", ["aisec"], /must be a JSON object/],
+  ])("refuses %s", (_, json, why) => {
+    const r = parsePaperSettings(json);
+    expect(r.ok).toBe(false);
+    if (!r.ok) expect(r.error).toMatch(why);
+  });
+});
+
+describe("readPaperSettings", () => {
+  it("no file: null — the paper declares nothing", () => {
+    expect(readPaperSettings(memoryFiles(), PAPER)).toEqual({
+      ok: true,
+      value: null,
+    });
+  });
+
+  it("reads paperlint.json", () => {
+    const files = memoryFiles({
+      [`${PAPER}/paperlint.json`]: '{"extends":"paperlint:aisec"}',
+    });
+    const r = readPaperSettings(files, PAPER);
+    expect(r.ok && r.value?.extends).toBe("paperlint:aisec");
+  });
+
+  it("not JSON: broken, with the parser's reason", () => {
+    const files = memoryFiles({
+      [`${PAPER}/paperlint.json`]: "{ extends: aisec",
+    });
+    const r = readPaperSettings(files, PAPER);
+    expect(r.ok).toBe(false);
+    if (!r.ok) expect(r.error.kind).toBe("broken");
+  });
+});
+
+describe("readPaperSettings — the root paperlint.json's defaults, the paper's file over them", () => {
+  const ROOT = "/work";
+  const withFiles = (f: Record<string, string>) =>
+    memoryFiles({ [`${ROOT}/package.json`]: "{}", ...f });
+  const read = (f: Record<string, string>) => {
+    const r = readPaperSettings(withFiles(f), PAPER);
+    if (!r.ok) throw new Error(r.error.why);
+    return r.value;
+  };
+
+  it("no file at either level: null", () => {
+    expect(read({})).toBeNull();
+  });
+
+  it("root only: its extends and kind are this paper's", () => {
+    expect(
+      read({
+        [`${ROOT}/paperlint.json`]:
+          '{"papersDir":"papers","extends":"paperlint:agenticdev","kind":"short"}',
+      }),
+    ).toEqual({
+      extends: "paperlint:agenticdev",
+      kind: "short",
+      pdf: null,
+      rules: null,
+    });
+  });
+
+  it("paper only: its own values", () => {
+    expect(
+      read({ [`${PAPER}/paperlint.json`]: '{"extends":"paperlint:aisec"}' }),
+    ).toEqual({
+      extends: "paperlint:aisec",
+      kind: null,
+      pdf: null,
+      rules: null,
+    });
+  });
+
+  it("🔴 both: the paper's value wins, an absent one falls back to the root's, and `\"extends\": null` is absent", () => {
+    expect(
+      read({
+        [`${ROOT}/paperlint.json`]:
+          '{"extends":"paperlint:agenticdev","kind":"short","rules":{"pdf/profile":"off"}}',
+        [`${PAPER}/paperlint.json`]:
+          '{"extends":null,"kind":"research","rules":{"pdf/fonts":"off"}}',
+      }),
+    ).toEqual({
+      extends: "paperlint:agenticdev",
+      kind: "research",
+      pdf: null,
+      // The root's rules are the project's blocks (cli.ts), not this paper's.
+      rules: { "pdf/fonts": "off" },
+    });
+  });
+
+  it("papersDir in a paper's file: broken, naming the root file as its place", () => {
+    const r = readPaperSettings(
+      withFiles({ [`${PAPER}/paperlint.json`]: '{"papersDir":"x"}' }),
+      PAPER,
+    );
+    expect(r.ok).toBe(false);
+    if (!r.ok) expect(r.error.why).toMatch(/project setting/);
+  });
+});
+
+describe("findProjectRoot — where the root paperlint.json is looked for", () => {
+  const ROOT = "/work";
+  const withFiles = (f: Record<string, string>) =>
+    memoryFiles({ [`${ROOT}/package.json`]: "{}", ...f });
+
+  it("🔴 from INSIDE a paper, the project root is not the paper: its paperlint.json sits beside paper.tex", () => {
+    const files = withFiles({
+      [`${PAPER}/paper.tex`]: "x",
+      [`${PAPER}/paperlint.json`]: '{"kind":"research"}',
+      [`${ROOT}/paperlint.json`]: '{"extends":"paperlint:aisec"}',
+    });
+    const isFile = (p: string) => files.isFile(p as AbsolutePath);
+    expect(findProjectRoot(PAPER, isFile)).toBe(ROOT);
+    // No root file anywhere: the package.json directory.
+    expect(findProjectRoot(PAPER, (p) => p === `${ROOT}/package.json`)).toBe(
+      ROOT,
+    );
+    // Neither: where the walk started.
+    expect(findProjectRoot(PAPER, () => false)).toBe(PAPER);
+  });
+});
+
+describe("paperRules — `rules` in paperlint.json", () => {
+  const settings = (rules: Record<string, unknown> | null) => ({
+    extends: null,
+    kind: null,
+    pdf: null,
+    rules,
+  });
+
+  it("no rules: none", () => {
+    expect(paperRules(PAPER, settings(null), SHIPPED)).toEqual({
+      ok: true,
+      value: null,
+    });
+  });
+
+  it("known rules, parsed", () => {
+    expect(
+      paperRules(
+        PAPER,
+        settings({ "pdf/last-page-balance": "error" }),
+        SHIPPED,
+      ),
+    ).toEqual({ ok: true, value: { "pdf/last-page-balance": "error" } });
+  });
+
+  it.each([
+    [
+      "an unknown rule id",
+      { "pdf/no-such-rule": "error" },
+      /"pdf\/no-such-rule" is not a rule paperlint ships/,
+    ],
+    ["a bad severity", { "pdf/profile": "loud" }, /is not a severity/],
+  ])("refuses %s, naming the file", (_, rules, why) => {
+    const r = paperRules(PAPER, settings(rules), SHIPPED);
+    expect(r.ok).toBe(false);
+    if (!r.ok) {
+      expect(r.error).toMatch(why);
+      expect(r.error).toMatch(/paperlint\.json/);
+    }
+  });
+});