paperlint 2.0.0 → 2.1.0

package/src/new-paper.ts

@@ -25,6 +25,10 @@ import {
 /* eslint-enable boundaries/dependencies */
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
+import {
+  LEGACY_PAPER_SETTINGS_FILE,
+  PAPER_SETTINGS_FILE,
+} from "../lib/paper-config.mjs";
 
 export type PaperFormat = "tex" | "md";
 export const FORMATS: readonly PaperFormat[] = ["tex", "md"];
@@ -83,16 +87,32 @@ export type NewPaperResult =
   | { readonly ok: false; readonly reason: string };
 
 /**
- * The files a paper folder must end up with: the scorecard, plus a source in `format` — unless
- * it already has a source in EITHER format, in which case that one stands and nothing is added.
+ * The files a paper folder must end up with: the scorecard, a source in `format` — unless it
+ * already has a source in EITHER format, in which case that one stands — and `paperlint.json`.
  */
 export function wantedFiles(dir: string, format: PaperFormat): string[] {
+  return [...scorecardAndSource(dir, format), ...settingsFile(dir)];
+}
+
+function scorecardAndSource(dir: string, format: PaperFormat): string[] {
   const hasSource = Object.values(SOURCE_FILE).some((f) =>
     existsSync(join(dir, f)),
   );
   return hasSource ? [STATUS_FILE] : [STATUS_FILE, SOURCE_FILE[format]];
 }
 
+/**
+ * `paperlint.json`, so that nobody has to know the file exists: its template says what to put in
+ * it, and until a venue preset is named lint says so in one warning. Not beside a pre-2.1.0
+ * `venue.json`: `paperlint init` moves that file, and a second, different one would make the move
+ * refuse.
+ */
+function settingsFile(dir: string): string[] {
+  return existsSync(join(dir, LEGACY_PAPER_SETTINGS_FILE))
+    ? []
+    : [PAPER_SETTINGS_FILE];
+}
+
 // Documented in README.md#starting-a-paper — update it when this changes.
 export function newPaper(
   papersRoot: string,

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

@@ -0,0 +1,311 @@
+/**
+ * `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; `paperlint init` moves a pre-2.1.0
+ * `venue.json` and refuses when both files exist and differ; `paperlint doctor` names a leftover.
+ */
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  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";
+import { migratePaperSettings } from "./init.ts";
+import { doctor } from "./doctor.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,
+      paperlint: { papersDir: "papers" },
+    }),
+    "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 project's own `rules` blocks come after, so they win", async () => {
+    const root = project({
+      "package.json": JSON.stringify({
+        name: "c",
+        private: true,
+        paperlint: {
+          papersDir: "papers",
+          rules: [
+            {
+              files: ["papers/a/**"],
+              rules: { "pdf/last-page-balance": "off" },
+            },
+          ],
+        },
+      }),
+      "papers/a/paperlint.json": JSON.stringify({
+        rules: { "pdf/last-page-balance": "error" },
+      }),
+      "papers/b/paperlint.json": JSON.stringify({
+        rules: { "pdf/last-page-balance": "error" },
+      }),
+    });
+    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("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([
+      {
+        basePath: join(root, "papers/a"),
+        files: expect.arrayContaining([
+          "**/paper.tex",
+          "**/PIPELINE-STATUS.md",
+        ]),
+        rules: { "pdf/last-page-balance": ["error", { tolerancePt: 120 }] },
+      },
+    ]);
+  });
+
+  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")]),
+    );
+    expect(blocks.ok && blocks.value[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);
+  });
+});
+
+describe("paperlint init — moves venue.json to paperlint.json", () => {
+  const legacy = '{ "venue": "aisec", "kind": "research" }\n';
+
+  it('moves it, "venue" becoming "extends": "paperlint:<name>", and says so', () => {
+    const root = project({ "papers/a/venue.json": legacy });
+    const r = migratePaperSettings(join(root, "papers"));
+    expect(r.code).toBe(0);
+    expect(existsSync(join(root, "papers/a/venue.json"))).toBe(false);
+    expect(
+      JSON.parse(readFileSync(join(root, "papers/a/paperlint.json"), "utf8")),
+    ).toEqual({ extends: "paperlint:aisec", kind: "research" });
+    expect(r.lines.join("\n")).toMatch(/a\/venue\.json → a\/paperlint\.json/);
+  });
+
+  it("both, with the same content: the leftover is removed", () => {
+    const root = project({
+      "papers/a/venue.json": legacy,
+      "papers/a/paperlint.json":
+        '{"extends":"paperlint:aisec","kind":"research"}',
+    });
+    expect(migratePaperSettings(join(root, "papers")).code).toBe(0);
+    expect(existsSync(join(root, "papers/a/venue.json"))).toBe(false);
+  });
+
+  it("🔴 both, and they differ: refused, naming both, and nothing is touched", () => {
+    const root = project({
+      "papers/a/venue.json": legacy,
+      "papers/a/paperlint.json": '{"venue":"realm"}',
+    });
+    const r = migratePaperSettings(join(root, "papers"));
+    expect(r.code).toBe(2);
+    expect(r.lines.join("\n")).toMatch(/a\/venue\.json.*a\/paperlint\.json/);
+    expect(readFileSync(join(root, "papers/a/venue.json"), "utf8")).toBe(
+      legacy,
+    );
+    expect(readFileSync(join(root, "papers/a/paperlint.json"), "utf8")).toBe(
+      '{"venue":"realm"}',
+    );
+  });
+
+  it("no venue.json anywhere: nothing to say", () => {
+    const root = project();
+    expect(migratePaperSettings(join(root, "papers"))).toEqual({
+      code: 0,
+      lines: [],
+    });
+  });
+});
+
+describe("paperlint doctor — names a leftover venue.json", () => {
+  it("✗ with the command that moves it, and a failing exit", () => {
+    const root = project({ "papers/a/venue.json": '{"venue":"aisec"}' });
+    const out: string[] = [];
+    const code = doctor({
+      log: (s: string) => out.push(s),
+      cwd: root,
+      projectDir: root,
+      cliPapers: "papers",
+      run: (() => ({ status: 0, stdout: "", stderr: "" })) as never,
+      skillLinks: () => ({ ok: false, error: "not checked in this test" }),
+    });
+    const text = out.join("\n");
+    expect(text).toMatch(/✗ papers\/a\/venue\.json is no longer read/);
+    expect(text).toMatch(/npx paperlint init/);
+    expect(code).not.toBe(0);
+  });
+
+  it("says nothing about it when there is none", () => {
+    const root = project();
+    const out: string[] = [];
+    doctor({
+      log: (s: string) => out.push(s),
+      cwd: root,
+      projectDir: root,
+      cliPapers: "papers",
+      run: (() => ({ status: 0, stdout: "", stderr: "" })) as never,
+      skillLinks: () => ({ ok: false, error: "not checked in this test" }),
+    });
+    expect(out.join("\n")).not.toMatch(/venue\.json/);
+  });
+});

package/src/paper-settings.test.ts

@@ -0,0 +1,220 @@
+/**
+ * `<paper>/paperlint.json` — the per-paper settings file (it was `venue.json` before 2.1.0): parsed
+ * strictly, the old name never read, the move planned from bytes, 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 {
+  migrationOf,
+  paperRules,
+  parsePaperSettings,
+  readPaperSettings,
+} from "./paper-settings.ts";
+
+const PAPER = "/work/papers/p";
+const SHIPPED = new Set([
+  "pdf/last-page-balance",
+  "pdf/profile",
+  "paper/typography",
+]);
+const enc = (s: string) => new TextEncoder().encode(s);
+
+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".*extends, kind, pdf, rules/,
+    ],
+    [
+      "the pre-2.1.0 comment key `_`",
+      { 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 not an object",
+      { rules: ["pdf/profile"] },
+      /"rules" must be an object/,
+    ],
+    ["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("🔴 a venue.json alone is NOT read — it is named, with the command that moves it", () => {
+    const files = memoryFiles({ [`${PAPER}/venue.json`]: '{"venue":"aisec"}' });
+    const r = readPaperSettings(files, PAPER);
+    expect(r).toEqual({ ok: false, error: { kind: "legacy" } });
+  });
+
+  it("paperlint.json wins when both exist — the leftover is doctor's to report", () => {
+    const files = memoryFiles({
+      [`${PAPER}/venue.json`]: '{"venue":"realm"}',
+      [`${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("migrationOf — what `paperlint init` does with a paper's files", () => {
+  const plan = (legacy: string | null, current: string | null) =>
+    migrationOf(
+      legacy === null ? null : enc(legacy),
+      current === null ? null : enc(current),
+    );
+
+  it.each([
+    ["no venue.json", null, null, "none"],
+    [
+      "no venue.json, paperlint.json present",
+      null,
+      '{"extends":"paperlint:a"}',
+      "none",
+    ],
+    ["venue.json only", '{"venue":"a"}', null, "move"],
+    [
+      "both, and paperlint.json already says the same (spacing differs)",
+      '{"venue":"a","kind":"short"}',
+      '{ "extends": "paperlint:a", "kind": "short" }\n',
+      "drop-legacy",
+    ],
+    [
+      "both, different",
+      '{"venue":"a"}',
+      '{"extends":"paperlint:b"}',
+      "conflict",
+    ],
+    ["venue.json that is not JSON", "{", null, "broken"],
+    ["venue.json that is not an object", "[]", null, "broken"],
+  ])("%s → %s", (_, legacy, current, want) => {
+    expect(plan(legacy, current).kind).toBe(want);
+  });
+
+  it('the move rewrites "venue": "x" to "extends": "paperlint:x", and "_" to "$comment"', () => {
+    const r = plan(
+      '{"venue":"aisec","kind":"research","pdf":"b.pdf","_":"note"}',
+      null,
+    );
+    expect(r.kind === "move" && JSON.parse(r.text)).toEqual({
+      extends: "paperlint:aisec",
+      kind: "research",
+      pdf: "b.pdf",
+      $comment: "note",
+    });
+  });
+});
+
+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/);
+    }
+  });
+});