paperlint 3.0.0 → 3.1.0

package/src/linted-set.test.ts

@@ -0,0 +1,118 @@
+/**
+ * THE LINTED SET IS EXACTLY THE OWNED FILES — checked on the whole result, not one route in.
+ *
+ * Each test in `paper-files.test.ts` closes one way a stray file got into `paperlint lint`: vendored
+ * JavaScript under a paper (#99), a rule source that reached the siblings index (#101). This one
+ * does not care about the route. A paper with every kind of neighbour a real one has, settings from
+ * every level that generates blocks (a venue preset with `rules`, the root `rules`), and one
+ * assertion: the files ESLint returned are exactly the four paperlint owns — set equality, so a
+ * route nobody has thought of yet shows up as an extra member.
+ */
+import {
+  mkdirSync,
+  mkdtempSync,
+  realpathSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join, relative } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { run } from "./cli.ts";
+
+const dirs: string[] = [];
+afterEach(() => {
+  for (const d of dirs.splice(0)) rmSync(d, { recursive: true, force: true });
+});
+
+const TEX = "\\documentclass{article}\n\\begin{document}x\\end{document}\n";
+const JS = "export const x = 1;\n";
+
+/** The files paperlint owns in the fixture paper. */
+const OWNED = [
+  "papers/a/paper.tex",
+  "papers/a/PIPELINE-STATUS.md",
+  "papers/a/reviews/r1.md",
+  "papers/a/siblings/smith2025.md",
+];
+
+/** Everything else a real paper folder and project carry. None of it may be linted. */
+const NEIGHBOURS = {
+  "papers/a/siblings/README.md": "# Siblings\n\n- [Smith](smith2025.md)\n",
+  "papers/a/README.md": "# Paper a\n",
+  "papers/a/notes/idea.md": "# An idea\n",
+  "papers/a/repro/x.js": "return 1;\n",
+  "papers/a/repro/lib/y.mjs": JS,
+  "papers/a/repro/z.cjs": "module.exports = 1;\n",
+  "papers/a/repro/t.ts": "const t: number = 1;\n",
+  "script.js": JS,
+  "node_modules/pkg/index.js": JS,
+};
+
+function project(): string {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "paperlint-set-")));
+  dirs.push(root);
+  const all: Record<string, string> = {
+    "package.json": JSON.stringify({ name: "c", private: true }),
+    // A root `rules` block over every file of the project: the widest glob a consumer can write.
+    "paperlint.json": JSON.stringify({
+      rules: [
+        {
+          files: ["**/*.md", "**/*.tex", "**/*.js"],
+          rules: {
+            "pdf/last-page-balance": "warn",
+            "paper/section-word": "warn",
+          },
+        },
+      ],
+    }),
+    // A venue preset that carries `rules` of its own.
+    "papers/a/paperlint.json": JSON.stringify({
+      extends: "paperlint:agenticdev",
+    }),
+    "papers/a/paper.tex": TEX,
+    "papers/a/PIPELINE-STATUS.md": "---\nstages: []\n---\n",
+    "papers/a/reviews/r1.md": "# review\n",
+    "papers/a/siblings/smith2025.md": "---\nread: full\n---\n# Smith 2025\n",
+    ...NEIGHBOURS,
+  };
+  for (const [p, text] of Object.entries(all)) {
+    mkdirSync(join(root, p, ".."), { recursive: true });
+    writeFileSync(join(root, p), text);
+  }
+  return root;
+}
+
+/** `paperlint lint --json <args>` → the files it linted, relative to the project, sorted. */
+async function lintedSet(root: string, args: string[]): Promise<string[]> {
+  const out: string[] = [];
+  await run(["lint", "--json", ...args], {
+    cwd: root,
+    log: (s: string) => out.push(s),
+    err: () => {},
+  });
+  type Result = { filePath: string; messages: { ruleId: string | null }[] };
+  return (
+    (JSON.parse(out.join("\n")) as Result[])
+      // A structure finding reports a MISSING file in the same shape; it was not linted.
+      .filter(
+        (r) => !r.messages.some((m) => m.ruleId === "structure/required-file"),
+      )
+      .map((r) => relative(root, r.filePath))
+      .sort()
+  );
+}
+
+describe("🔴 paperlint lint — the linted set is EXACTLY the owned files", () => {
+  it.each([
+    ["the papers directory from the config", []],
+    ["the paper named on the command line", ["papers/a"]],
+    // The widest scope: ESLint is handed the project root, so it enumerates `script.js` and
+    // `node_modules/` too, and only the scope keeps them out.
+    ["the whole project named on the command line", ["."]],
+  ])("%s", async (_, args) => {
+    // Guards: every route in at once — vendored JS/TS, a root script, node_modules, a README next
+    // to the paper, the siblings index, notes. An extra member names the file that got through.
+    expect(await lintedSet(project(), args)).toEqual([...OWNED].sort());
+  });
+});

package/src/new-paper.harness.mjs

@@ -191,6 +191,8 @@ try {
     "---\n---\n# House scorecard for {{name}}\n",
   );
   const own = newPaper(papers, "house", "md");
+  // Guards: the override slot — `fromTemplate` in new-paper.ts reads `<papers>/.template/<file>`
+  // before the package's copy. Replace that lookup with the package's alone and this goes red.
   check(
     "🔴 <papers>/.template/ is preferred for the file it holds, the package fills the rest",
     own.ok &&

package/src/new-paper.mutations.mjs

@@ -51,20 +51,6 @@ process.exit(
           ],
         ],
       },
-      {
-        name: "the project's template is ignored",
-        harness: HARNESS,
-        expect: "is preferred for the file it holds",
-        disables:
-          "the override slot. A project with its own richer scorecard gets the package's every time",
-        edits: [
-          [
-            SRC,
-            "    const [src, from] = existsSync(project)",
-            "    const [src, from] = false",
-          ],
-        ],
-      },
       {
         name: "a leading dot is accepted",
         harness: HARNESS,

package/src/new-paper.test.ts

@@ -14,9 +14,12 @@ import {
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
+import { existsSync } from "node:fs";
 import { newPaper, OVERRIDE_DIR } from "./new-paper.ts";
 import { parsePaperSettings } from "./paper-settings.ts";
-import { run } from "./cli.ts";
+import { chooseVenue, run } from "./cli.ts";
+import { shippedPresets } from "./presets.ts";
+import { packageVenuesDir } from "../skills/paper-pipeline/scripts/consumer.mjs";
 
 const dirs: string[] = [];
 afterEach(() => {
@@ -131,3 +134,171 @@ describe("paperlint lint — a paper with no venue preset chosen", () => {
     );
   });
 });
+
+/** `paperlint new <args>` in a fresh project (not a terminal: vitest's stdin is not a TTY). */
+async function newIn(args: string[], files: Record<string, string> = {}) {
+  const root = tmp();
+  const all = {
+    "package.json": JSON.stringify({ name: "c", private: true }),
+    ...files,
+  };
+  for (const [p, text] of Object.entries(all)) {
+    mkdirSync(join(root, p, ".."), { recursive: true });
+    writeFileSync(join(root, p), text);
+  }
+  const out: string[] = [];
+  const err: string[] = [];
+  const code = await run(["new", "demo", ...args], {
+    cwd: root,
+    log: (s: string) => out.push(s),
+    err: (s: string) => err.push(s),
+  });
+  const dir = join(root, "papers", "demo");
+  return {
+    code,
+    out: out.join("\n"),
+    err: err.join("\n"),
+    dir,
+    settings: () => settingsOf(dir),
+  };
+}
+
+describe("paperlint new --venue / --kind", () => {
+  const PRESET = `{
+  "extends": "paperlint:acm-sigconf",
+  "format": { "kinds": { "short": { "body_pages_max": 4 } } },
+}
+`;
+
+  it("a shipped venue and its kind → extends and kind in paperlint.json, lint resolves it", async () => {
+    const r = await newIn(["--venue", "agenticdev", "--kind", "short"]);
+    expect(r.settings()).toEqual({
+      extends: "paperlint:agenticdev",
+      kind: "short",
+    });
+    expect(r.out).not.toMatch(/pdf\/profile/);
+    expect(r.code).toBe(0);
+  });
+
+  it("🔴 a path is relative to where you run it, and written relative to the paper's file", async () => {
+    const r = await newIn(
+      ["--venue", "./venues/my-workshop.jsonc", "--kind", "short"],
+      {
+        "venues/my-workshop.jsonc": PRESET,
+      },
+    );
+    // Guards: written as typed, `./venues/…` would name papers/demo/venues/…, which does not exist.
+    expect(r.settings()).toEqual({
+      extends: "../../venues/my-workshop.jsonc",
+      kind: "short",
+    });
+    expect(r.out).not.toMatch(/pdf\/profile/);
+    expect(r.code).toBe(0);
+  });
+
+  it("an unknown venue exits 2, lists the shipped presets, and creates nothing", async () => {
+    const r = await newIn(["--venue", "icse"]);
+    expect(r.code).toBe(2);
+    // Guards: the list is read from the shipped presets, the same list lint prints.
+    expect(r.err).toContain(shippedPresets(packageVenuesDir()).join(", "));
+    expect(r.err).toMatch(/--venue icse: no such venue preset/);
+    expect(existsSync(r.dir)).toBe(false);
+  });
+});
+
+describe("paperlint new --venue / --kind — refusals and defaults", () => {
+  it.each([
+    [
+      "a kind the preset lacks",
+      ["--venue", "agenticdev", "--kind", "long"],
+      /`agenticdev` has no kind `long`; its kinds: short, full, demo/,
+    ],
+    ["a kind without a venue", ["--kind", "short"], /--kind needs --venue/],
+    [
+      "a kind for a preset with no kinds",
+      ["--venue", "acm-sigconf", "--kind", "short"],
+      /`acm-sigconf` has no kinds/,
+    ],
+    [
+      "a path that does not exist",
+      ["--venue", "./venues/nope.jsonc"],
+      /no such file .* relative to where you run the command/,
+    ],
+  ])("%s → exit 2, nothing created", async (_, args, message) => {
+    const r = await newIn(args);
+    expect(r.err).toMatch(message);
+    expect(r.code).toBe(2);
+    expect(existsSync(r.dir)).toBe(false);
+  });
+
+  it("a venue with kinds and no --kind: written, and new says what lint will report", async () => {
+    const r = await newIn(["--venue", "agenticdev"]);
+    expect(r.settings()).toEqual({ extends: "paperlint:agenticdev" });
+    expect(r.out).toMatch(
+      /kind: not set — `agenticdev` sets a page limit per kind/,
+    );
+    expect(r.out).toMatch(/pdf\/profile/);
+  });
+
+  it("without a terminal and no --venue: as before, and the hint names --venue", async () => {
+    const r = await newIn([]);
+    expect(r.settings()["extends"]).toBeNull();
+    expect(r.out).toMatch(/venue: none yet .*--venue <preset>/);
+    expect(r.code).toBe(0);
+  });
+
+  it("an existing paperlint.json is never overwritten: --venue is refused", async () => {
+    const r = await newIn(["--venue", "aisec"], {
+      "papers/demo/paperlint.json": '{ "extends": null }\n',
+    });
+    expect(r.code).toBe(2);
+    expect(r.err).toMatch(/already exists and is never overwritten/);
+    expect(r.settings()).toEqual({ extends: null });
+  });
+});
+
+describe("chooseVenue — on a terminal", () => {
+  const at = (answers: string[]) => {
+    const asked: string[] = [];
+    return {
+      asked,
+      opts: {
+        paperDir: "/p/papers/demo",
+        cwd: "/p",
+        interactive: true,
+        ask: async (q: string) => (asked.push(q), answers.shift() ?? ""),
+      },
+    };
+  };
+
+  it("asks the venue from the shipped list, then its kind", async () => {
+    const t = at(["agenticdev", "full"]);
+    const r = await chooseVenue({ venue: null, kind: null }, t.opts);
+    expect(r).toMatchObject({
+      ok: true,
+      value: { extends: "paperlint:agenticdev", kind: "full" },
+    });
+    expect(t.asked[0]).toContain(
+      [...shippedPresets(packageVenuesDir()), "none"].join(" / "),
+    );
+    expect(t.asked[1]).toMatch(/kind: short \/ full \/ demo \/ later/);
+  });
+
+  it("the default answer is none: no venue written", async () => {
+    const t = at([""]);
+    expect(await chooseVenue({ venue: null, kind: null }, t.opts)).toEqual({
+      ok: true,
+      value: null,
+    });
+  });
+
+  it("without a terminal nothing is asked", async () => {
+    const t = at(["agenticdev"]);
+    const r = await chooseVenue(
+      { venue: null, kind: null },
+      { ...t.opts, interactive: false },
+    );
+    expect(r).toEqual({ ok: true, value: null });
+    expect(t.asked).toEqual([]);
+  });
+});

package/src/new-paper.ts

@@ -98,12 +98,85 @@ function scorecardAndSource(dir: string, format: PaperFormat): string[] {
   return hasSource ? [STATUS_FILE] : [STATUS_FILE, SOURCE_FILE[format]];
 }
 
-// Documented in README.md#starting-a-paper — update it when this changes.
+/** The venue `paperlint new --venue` chose: what goes into the new paper's `paperlint.json`. */
+export interface VenueSetting {
+  /** `paperlint:<name>`, or a path relative to the paper's `paperlint.json`. */
+  readonly extends: string;
+  readonly kind: string | null;
+}
+
+/**
+ * The template's `paperlint.json` with the chosen venue written in. The template's `$comment`
+ * explains how to choose one, so it goes once one is chosen. A template that is not plain JSON (a
+ * project's own, with comments) cannot be edited safely and is refused by name.
+ */
+function withVenue(
+  text: string,
+  src: string,
+  venue: VenueSetting,
+): { ok: true; text: string } | { ok: false; reason: string } {
+  let obj: Record<string, unknown>;
+  try {
+    obj = JSON.parse(text) as Record<string, unknown>;
+  } catch {
+    return {
+      ok: false,
+      reason: `--venue cannot be written into ${src}: it is not plain JSON — set "extends" by hand`,
+    };
+  }
+  const out: Record<string, unknown> = { ...obj, extends: venue.extends };
+  delete out["$comment"];
+  if (venue.kind !== null) out["kind"] = venue.kind;
+  return { ok: true, text: `${JSON.stringify(out, null, 2)}\n` };
+}
+
+/** A file `newPaper` will write: its text, and which template it came from. */
+interface Planned {
+  readonly file: string;
+  readonly text: string;
+  readonly from: "project" | "package";
+}
+
+/** One file's text from its template — the project's override first, the package's second. */
+function fromTemplate(
+  file: string,
+  {
+    papersRoot,
+    packageTemplates,
+    name,
+    venue,
+  }: {
+    papersRoot: string;
+    packageTemplates: string;
+    name: string;
+    venue: VenueSetting | null;
+  },
+): { ok: true; value: Planned } | { ok: false; reason: string } {
+  const project = join(papersRoot, OVERRIDE_DIR, file);
+  const [src, from] = existsSync(project)
+    ? [project, "project" as const]
+    : [join(packageTemplates, file), "package" as const];
+  // A missing package template is a broken install, not a reason to write an empty file.
+  if (!existsSync(src))
+    return { ok: false, reason: `no template for ${file}: ${src} is missing` };
+  const text = readFileSync(src, "utf8").split("{{name}}").join(name);
+  if (file !== CONFIG_FILE || venue === null)
+    return { ok: true, value: { file, text, from } };
+  const edited = withVenue(text, src, venue);
+  return edited.ok
+    ? { ok: true, value: { file, text: edited.text, from } }
+    : edited;
+}
+
+// Documented in README.md#getting-started — update it when this changes.
 export function newPaper(
   papersRoot: string,
   name: string,
   format: PaperFormat,
-  { packageTemplates = PACKAGE_TEMPLATES }: { packageTemplates?: string } = {},
+  {
+    packageTemplates = PACKAGE_TEMPLATES,
+    venue = null,
+  }: { packageTemplates?: string; venue?: VenueSetting | null } = {},
 ): NewPaperResult {
   const problem = nameProblem(name);
   if (problem) return { ok: false, reason: problem };
@@ -113,26 +186,20 @@ export function newPaper(
     return { ok: false, reason: `${dir} exists and is not a directory` };
 
   const files: FileOutcome[] = [];
-  const toWrite: { file: string; text: string; from: "project" | "package" }[] =
-    [];
+  const toWrite: Planned[] = [];
   for (const file of wantedFiles(dir, format)) {
     if (existsSync(join(dir, file))) {
       files.push({ file, status: "kept" });
       continue;
     }
-    const project = join(papersRoot, OVERRIDE_DIR, file);
-    const fromPackage = join(packageTemplates, file);
-    const [src, from] = existsSync(project)
-      ? [project, "project" as const]
-      : [fromPackage, "package" as const];
-    // A missing package template is a broken install, not a reason to write an empty file.
-    if (!existsSync(src))
-      return {
-        ok: false,
-        reason: `no template for ${file}: ${src} is missing`,
-      };
-    const text = readFileSync(src, "utf8").split("{{name}}").join(name);
-    toWrite.push({ file, text, from });
+    const planned = fromTemplate(file, {
+      papersRoot,
+      packageTemplates,
+      name,
+      venue,
+    });
+    if (!planned.ok) return planned;
+    toWrite.push(planned.value);
   }
   // Read every template before writing any file, so a missing one leaves no half-made folder.
   mkdirSync(dir, { recursive: true });

package/src/paper-files.test.ts

@@ -23,6 +23,7 @@ import { buildConfig, run } from "./cli.ts";
 import {
   narrowToOwners,
   ownedPatterns,
+  ownedScopes,
   ruleOwners,
   scopeToOwned,
 } from "./paper-files.ts";
@@ -160,6 +161,73 @@ describe("`rules` blocks reach only the files each rule is written for", () => {
   });
 });
 
+describe("🔴 a generated block never reaches a file paperlint does not lint (#101)", () => {
+  // A venue preset with `rules` (agenticdev turns on pdf/last-page-balance) became a block over
+  // every paper file. `pdf` is registered for every file, so the block was not narrowed, and the
+  // siblings index — which the sibling-card block excludes — matched a block with no language:
+  // ESLint parsed it as JavaScript ("Parsing error: Assigning to rvalue").
+  const SIBLINGS = {
+    "papers/a/siblings/README.md": "# Siblings\n\n- [x](smith2025.md)\n",
+    "papers/a/siblings/smith2025.md": "---\nread: full\n---\n# Smith 2025\n",
+  };
+
+  it.each([
+    [
+      "a venue preset's rules",
+      {
+        "papers/a/paperlint.json": JSON.stringify({
+          extends: "paperlint:agenticdev",
+        }),
+      },
+    ],
+    [
+      // `papers/**` alone would not show it: ESLint does not lint a file on a pattern ending in
+      // `/**`, it only applies such a block to files something else claims.
+      "a root block over every markdown file",
+      {
+        "paperlint.json": JSON.stringify({
+          rules: [
+            {
+              files: ["papers/**/*.md", "papers/**/*.tex"],
+              rules: { "pdf/last-page-balance": "warn" },
+            },
+          ],
+        }),
+      },
+    ],
+    [
+      "a paper's own { id: severity }",
+      {
+        "papers/a/paperlint.json": JSON.stringify({
+          rules: { "pdf/last-page-balance": "warn" },
+        }),
+      },
+    ],
+  ])(
+    "%s: the siblings index is not parsed, the cards still are",
+    async (_, settings) => {
+      const root = project({ ...SIBLINGS, ...settings });
+      const r = await lint(root);
+      const results = JSON.parse(r.out) as {
+        filePath: string;
+        messages: { ruleId: string | null; message: string }[];
+      }[];
+      // Guards: the class — no file reaches ESLint's default JavaScript parser.
+      expect(
+        results.flatMap((x) => x.messages).filter((m) => m.ruleId === null),
+      ).toEqual([]);
+      expect(linted(r.out)).not.toContain(
+        join(root, "papers/a/siblings/README.md"),
+      );
+      // Guards: the other half — narrowing did not drop the files the block is for.
+      expect(linted(r.out)).toContain(
+        join(root, "papers/a/siblings/smith2025.md"),
+      );
+      expect(linted(r.out)).toContain(join(root, "papers/a/paper.tex"));
+    },
+  );
+});
+
 describe("`rules` blocks — where the rule lands", () => {
   it("on its own files and on no other", async () => {
     const root = project();
@@ -206,11 +274,48 @@ describe("paper-files — the pieces", () => {
     expect(ownedPatterns(own)).toEqual(["**/a.md", "**/b.md", "**/c.md"]);
   });
 
-  it("a rule's owner is where its plugin is registered; a global plugin owns every file", () => {
+  it("a rule's owner is where its plugin is registered; a global plugin owns every OWNED file", () => {
     const owners = ruleOwners(own);
-    expect(owners.get("g/any")).toBeNull();
-    expect(owners.get("p/one")).toEqual(["**/a.md"]);
-    expect(owners.get("p/two")).toEqual(["**/b.md", "**/c.md"]);
+    expect(owners.get("g/any")).toEqual([
+      { files: ["**/a.md", "**/b.md", "**/c.md"], ignores: [] },
+    ]);
+    expect(owners.get("p/one")).toEqual([{ files: ["**/a.md"], ignores: [] }]);
+    expect(owners.get("p/two")).toEqual([
+      { files: ["**/b.md", "**/c.md"], ignores: [] },
+    ]);
+  });
+
+  it("🔴 a scope keeps its block's exceptions, and a global plugin inherits them (#101)", () => {
+    const withIndex = [
+      ...own,
+      {
+        files: ["**/s/*.md"],
+        ignores: ["**/s/README.md"],
+        plugins: { s: { rules: { card: {} } } },
+      },
+    ];
+    expect(ownedScopes(withIndex)).toEqual([
+      { files: ["**/a.md", "**/b.md", "**/c.md"], ignores: [] },
+      { files: ["**/s/*.md"], ignores: ["**/s/README.md"] },
+    ]);
+    // Guards: the defect — the plugin registered for every file used to keep any glob, and so
+    // reached the index the card block excludes.
+    expect(ruleOwners(withIndex).get("g/any")).toEqual(ownedScopes(withIndex));
+    expect(
+      narrowToOwners(
+        {
+          basePath: "/x",
+          files: ["papers/**/*.md"],
+          rules: { "g/any": "warn" },
+        },
+        ruleOwners(withIndex),
+      ).at(-1),
+    ).toEqual({
+      basePath: "/x",
+      files: [["papers/**/*.md", "**/s/*.md"]],
+      ignores: ["**/s/README.md"],
+      rules: { "g/any": "warn" },
+    });
   });
 });
 
@@ -249,7 +354,7 @@ describe("paper-files — narrowing a block", () => {
       },
       {
         basePath: "/x",
-        files: ["papers/**"],
+        files: ["**/a.md", "**/b.md", "**/c.md"].map((o) => ["papers/**", o]),
         ignores: ["papers/old/**"],
         rules: { "g/any": "off" },
       },