paperlint 2.1.0 → 3.1.0

package/src/paper-files.ts

@@ -0,0 +1,200 @@
+/**
+ * THE FILES PAPERLINT OWNS — read off its own config, and made the only thing ESLint may reach.
+ *
+ * paperlint's blocks name the files they lint (`PIPELINE-STATUS.md`, `paper.md`, `paper.tex`,
+ * `reviews/*.md`, …). That list is the whole scope of `paperlint lint`, and this module turns it
+ * into two things ESLint understands:
+ *
+ * 1. **A global ignore of everything else** (`scopeToOwned`). Handing ESLint a directory is not
+ *    enough: its built-in defaults lint every JavaScript file it finds, whatever our config says.
+ *    Measured on a consumer project with vendored code under a paper's `repro/` folder: 1,877
+ *    files, 74 errors ("'return' outside of function", "Definition for rule … was not found"),
+ *    zero of them on a paper file, exit 1 — and nothing in the settings could turn it off. With
+ *    the ignore, a stray script under the papers directory is never enumerated at all, and a file
+ *    named on the command line can be asked about (`ESLint#isPathIgnored`) with ESLint's own
+ *    matcher instead of a hand-written one.
+ *
+ * 2. **Each rule scoped to the files it was written for** (`ruleOwners` + `narrowToOwners`).
+ *    One plugin NAME is bound to different plugin objects in different blocks: `paper` holds
+ *    `stages`/`source`/`author-list` beside `PIPELINE-STATUS.md` and `research-question`/
+ *    `typography` beside `paper.md`/`paper.tex`. So a consumer block that named `paper/source`
+ *    for every file under the papers directory reached `paper.tex`, where `paper` has no `source`
+ *    — and ESLint threw `Could not find "source" in plugin "paper"` from inside `lintFiles`,
+ *    after paperlint's own validation had (correctly) accepted the id. A block is therefore split
+ *    per owner and its `files` ANDed with the owner's (ESLint's nested-array form), so a rule can
+ *    only land where its plugin is registered.
+ *
+ * Both read ONE definition of "the files paperlint lints": `ownedScopes`, each own block's `files`
+ * together with its `ignores`. The globs alone are not that definition. The sibling-card block
+ * claims every markdown file under `siblings/` EXCEPT the index, and a rule whose plugin is
+ * registered for every file (`pdf`) used to keep the consumer block's `files` as they were — so a
+ * venue preset's rules reached `siblings/README.md`, a block with no `language` matched it, and
+ * ESLint parsed the markdown as JavaScript (#101). Now every generated block narrows to scopes,
+ * exceptions included, and a plugin registered everywhere owns exactly what paperlint lints.
+ *
+ * ESLint's semantics that this leans on, each measured against ESLint 10 before writing it:
+ * - a global-ignore pattern that matches a DIRECTORY hides everything inside it, so directories
+ *   must be un-ignored (`!` + a pattern ending in a slash) before owned files can be;
+ * - that un-ignores `node_modules/` and `.git/` too — ESLint's own defaults — so they are
+ *   re-ignored after, or a `paper.md` inside a dependency would be linted;
+ * - later global-ignore patterns win, across blocks, in config order;
+ * - `files: [["a", "b"]]` matches a file only when BOTH patterns match.
+ */
+import type { RuleBlock, RuleEntry } from "./rules-config.ts";
+
+/** What this module reads of a config block. */
+interface Block {
+  readonly files?: readonly unknown[];
+  readonly ignores?: readonly unknown[];
+  readonly plugins?: Readonly<
+    Record<string, { readonly rules?: Readonly<Record<string, unknown>> }>
+  >;
+}
+
+/**
+ * A set of files paperlint lints: an own block's globs and the exceptions that block makes. A file is
+ * in it when it matches one of `files` and none of `ignores`.
+ */
+export interface OwnedScope {
+  readonly files: readonly string[];
+  readonly ignores: readonly string[];
+}
+
+/** A `files` entry: one glob, or several that must ALL match. */
+export type FilesEntry = string | readonly string[];
+
+/** A consumer block after narrowing: its `files` may carry ANDed pairs. */
+export interface ScopedBlock {
+  readonly basePath: string;
+  readonly files?: readonly FilesEntry[];
+  readonly ignores?: readonly string[];
+  readonly rules: Readonly<Record<string, RuleEntry>>;
+}
+
+const globsOf = (b: Block): string[] =>
+  (b.files ?? []).filter((f): f is string => typeof f === "string");
+
+const stringsOf = (xs: readonly unknown[] | undefined): string[] =>
+  (xs ?? []).filter((x): x is string => typeof x === "string");
+
+/**
+ * Scopes with the same exceptions, merged into one: their globs united, once, in order. Keeps a
+ * generated block per distinct set of exceptions rather than one per own block.
+ */
+const merged = (scopes: readonly OwnedScope[]): OwnedScope[] => {
+  const byIgnores = new Map<string, OwnedScope>();
+  for (const s of scopes) {
+    const key = JSON.stringify(s.ignores);
+    const had = byIgnores.get(key);
+    byIgnores.set(key, {
+      files: [...new Set([...(had?.files ?? []), ...s.files])],
+      ignores: s.ignores,
+    });
+  }
+  return [...byIgnores.values()];
+};
+
+/**
+ * THE FILES PAPERLINT LINTS: every own block that names `files`, with its `ignores`. A block without
+ * `files` (a global ignore, or the block registering `pdf` for every file) claims nothing.
+ */
+export function ownedScopes(own: readonly unknown[]): OwnedScope[] {
+  return merged(
+    own
+      .map((raw) => raw as Block)
+      .filter((b) => b.files !== undefined)
+      .map((b) => ({ files: globsOf(b), ignores: stringsOf(b.ignores) })),
+  );
+}
+
+/** Every glob paperlint's own blocks lint, once, in config order. */
+export function ownedPatterns(own: readonly unknown[]): string[] {
+  return [...new Set(ownedScopes(own).flatMap((s) => s.files))];
+}
+
+/** ESLint's default ignores, re-applied after directories are un-ignored. */
+const ESLINT_DEFAULT_IGNORES = ["**/node_modules/", "**/.git/"];
+
+/** A global-ignore block that leaves ESLint nothing to lint but `owned`. */
+export function scopeToOwned(owned: readonly string[]): {
+  readonly ignores: string[];
+} {
+  return {
+    ignores: [
+      "**/*",
+      "!**/*/",
+      ...owned.map((p) => `!${p}`),
+      ...ESLINT_DEFAULT_IGNORES,
+    ],
+  };
+}
+
+/** Every `<plugin>/<rule>` a block registers. */
+const ruleIdsOf = (b: Block): string[] =>
+  Object.entries(b.plugins ?? {}).flatMap(([name, plugin]) =>
+    Object.keys(plugin.rules ?? {}).map((rule) => `${name}/${rule}`),
+  );
+
+/**
+ * Rule id → the scopes of the blocks that register its plugin with that rule. A plugin registered
+ * for every file (a block without `files`) owns every scope — everything paperlint lints, and not
+ * one file more.
+ */
+export function ruleOwners(
+  own: readonly unknown[],
+): Map<string, readonly OwnedScope[]> {
+  const all = ownedScopes(own);
+  const found = new Map<string, OwnedScope[]>();
+  for (const raw of own) {
+    const b = raw as Block;
+    const scopes =
+      b.files === undefined
+        ? all
+        : [{ files: globsOf(b), ignores: stringsOf(b.ignores) }];
+    for (const id of ruleIdsOf(b))
+      found.set(id, [...(found.get(id) ?? []), ...scopes]);
+  }
+  return new Map([...found].map(([id, scopes]) => [id, merged(scopes)]));
+}
+
+/**
+ * One consumer block → one block per owner scope, each carrying only that owner's rules, its `files`
+ * ANDed with the scope's globs and its `ignores` joined by the scope's exceptions. A rule no block
+ * of this config registers (the LaTeX block is absent when its parser did not load) gets no block:
+ * it has no file to reach in this run, and naming it to ESLint would only crash.
+ */
+export function narrowToOwners(
+  block: RuleBlock,
+  owners: ReadonlyMap<string, readonly OwnedScope[]>,
+): ScopedBlock[] {
+  const groups = new Map<string, Record<string, RuleEntry>>();
+  for (const [id, entry] of Object.entries(block.rules)) {
+    const owner = owners.get(id);
+    if (owner === undefined) continue;
+    const key = JSON.stringify(owner);
+    groups.set(key, { ...groups.get(key), [id]: entry });
+  }
+  return [...groups].flatMap(([key, rules]) =>
+    (JSON.parse(key) as OwnedScope[]).map((scope) =>
+      within(block, scope, rules),
+    ),
+  );
+}
+
+/** `block`'s rules over the files both it and `scope` claim, minus both sets of exceptions. */
+function within(
+  block: RuleBlock,
+  scope: OwnedScope,
+  rules: Readonly<Record<string, RuleEntry>>,
+): ScopedBlock {
+  const files: readonly FilesEntry[] = block.files
+    ? block.files.flatMap((f) => scope.files.map((o) => [f, o]))
+    : scope.files;
+  const ignores = [...(block.ignores ?? []), ...scope.ignores];
+  return {
+    basePath: block.basePath,
+    files,
+    ...(ignores.length ? { ignores } : {}),
+    rules,
+  };
+}

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

@@ -1,13 +1,10 @@
 /**
  * `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.
+ * `rules` to that paper alone and refuses an unknown rule id.
  */
 import {
-  existsSync,
   mkdirSync,
   mkdtempSync,
-  readFileSync,
   realpathSync,
   rmSync,
   writeFileSync,
@@ -16,8 +13,6 @@ 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(() => {
@@ -29,11 +24,7 @@ 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" },
-    }),
+    "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",
@@ -51,10 +42,11 @@ function project(files: Record<string, string> = {}): string {
 
 async function lint(
   root: string,
+  args: string[] = [],
 ): Promise<{ code: number; out: string; err: string }> {
   const out: string[] = [];
   const err: string[] = [];
-  const code = await run(["lint", "--json"], {
+  const code = await run(["lint", "--json", ...args], {
     cwd: root,
     log: (s: string) => out.push(s),
     err: (s: string) => err.push(s),
@@ -67,6 +59,43 @@ const rulesIn = (stdout: string, paper: string): string[] =>
     .filter((r) => r.filePath.endsWith(join(paper, "paper.tex")))
     .flatMap((r) => r.messages.map((m) => m.ruleId));
 
+describe("🔴 an optional rule that reaches no paper — judged against the PROJECT, not the run (#103)", () => {
+  const THIRD = {
+    "papers/c/paper.tex":
+      "\\documentclass{article}\n\\begin{document}x\\end{document}\n",
+    "papers/c/PIPELINE-STATUS.md": "---\nstages: []\n---\n",
+  };
+  const rootRules = (files: string[]) => ({
+    "paperlint.json": JSON.stringify({
+      rules: [{ files, rules: { "pdf/last-page-balance": "error" } }],
+    }),
+  });
+
+  it("linting paper c alone passes when the block reaches papers a and b", async () => {
+    const root = project({
+      ...THIRD,
+      ...rootRules(["papers/a/**", "papers/b/**"]),
+    });
+    const r = await lint(root, ["papers/c"]);
+    // Guards: the defect — the guard counted only the paper.tex files this run linted.
+    expect(r.err).not.toMatch(/no linted paper\.tex gets it/);
+    expect(r.code).toBe(0);
+    expect(rulesIn(r.out, "c")).not.toContain("pdf/last-page-balance");
+  });
+
+  it("…and a glob that reaches no paper of the project still fails, from a subset too", async () => {
+    const root = project({ ...THIRD, ...rootRules(["papers/typo/**"]) });
+    for (const args of [["papers/c"], []]) {
+      const r = await lint(root, args);
+      // Guards: the other half — widening the judged set did not turn the guard off.
+      expect(r.err).toMatch(
+        /pdf\/last-page-balance is turned on in "rules", but no paper\.tex/,
+      );
+      expect(r.code).toBe(1);
+    }
+  });
+});
+
 describe("paperlint lint — `rules` in a paper's paperlint.json", () => {
   it("turns an optional rule on for that paper alone", async () => {
     const root = project({
@@ -80,26 +109,18 @@ describe("paperlint lint — `rules` in a paper's paperlint.json", () => {
     expect(rulesIn(r.out, "b")).not.toContain("pdf/last-page-balance");
   });
 
-  it("the project's own `rules` blocks come after, so they win", async () => {
+  it("🔴 the paper's own `rules` come after the root paperlint.json's, 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" },
-            },
-          ],
-        },
+      "paperlint.json": JSON.stringify({
+        rules: [
+          {
+            files: ["papers/*/**"],
+            rules: { "pdf/last-page-balance": "error" },
+          },
+        ],
       }),
       "papers/a/paperlint.json": JSON.stringify({
-        rules: { "pdf/last-page-balance": "error" },
-      }),
-      "papers/b/paperlint.json": JSON.stringify({
-        rules: { "pdf/last-page-balance": "error" },
+        rules: { "pdf/last-page-balance": "off" },
       }),
     });
     const r = await lint(root);
@@ -125,6 +146,61 @@ describe("paperlint lint — `rules` in a paper's 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({
@@ -136,16 +212,17 @@ describe("paperlint lint — the venue preset's rules", () => {
     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 }] },
-      },
-    ]);
+    expect(cfgOf.ok && cfgOf.value).toEqual({
+      preset: [
+        {
+          // Scoped to the paper by `basePath` alone: which of its files the rule reaches is decided
+          // once, by narrowing to paperlint's owned scopes (#101), not by a copy of their globs.
+          basePath: join(root, "papers/a"),
+          rules: { "pdf/last-page-balance": ["error", { tolerancePt: 120 }] },
+        },
+      ],
+      own: [],
+    });
   });
 
   it("🔴 an unbuilt agenticdev paper: ONE warning (pdf/measured), and no balance error", async () => {
@@ -172,7 +249,11 @@ describe("paperlint lint — the paper over its preset, and the project's own pr
     const blocks = await import("./cli.ts").then((m) =>
       m.paperRuleBlocks([join(root, "papers")]),
     );
-    expect(blocks.ok && blocks.value[0]?.rules).toEqual({
+    // 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",
     });
   });
@@ -227,85 +308,3 @@ describe("paperlint toolchain — installs what the project's own presets need",
     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/);
-  });
-});