paperlint 2.0.1 → 3.0.0

package/src/paper-files.test.ts

@@ -0,0 +1,290 @@
+/**
+ * WHICH FILES `paperlint lint` LINTS — only the ones its own blocks claim, and a rule named in
+ * `rules` reaches only the files it was written for.
+ *
+ * The defect this closes (found migrating a consumer project with vendored JS under a paper's
+ * `repro/` folder): paperlint handed whole directories to ESLint, and ESLint's built-in defaults
+ * then linted every `.js`/`.mjs`/`.cjs` under the papers directory. 1,877 vendored files produced
+ * 74 errors — parse errors and "Definition for rule … was not found" — none of them on a paper
+ * file, and the run failed. Nothing in the settings could turn that off.
+ */
+import { ESLint, type Linter } from "eslint";
+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 { buildConfig, run } from "./cli.ts";
+import {
+  narrowToOwners,
+  ownedPatterns,
+  ruleOwners,
+  scopeToOwned,
+} from "./paper-files.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";
+
+/** A project with one paper `a` (paper.tex + PIPELINE-STATUS.md), plus `files`. */
+function project(files: Record<string, string> = {}): string {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "paperlint-scope-")));
+  dirs.push(root);
+  const all: Record<string, string> = {
+    "package.json": JSON.stringify({ name: "c", private: true }),
+    "papers/a/paper.tex": TEX,
+    "papers/a/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,
+  args: string[] = [],
+): Promise<{ code: number; out: string; err: string }> {
+  const out: string[] = [];
+  const err: string[] = [];
+  const code = await run(["lint", "--json", ...args], {
+    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 linted = (stdout: string): string[] =>
+  (JSON.parse(stdout) as { filePath: string }[]).map((r) => r.filePath);
+
+/** Vendored code under a paper: a syntax error, an unknown rule in a directive, plain CommonJS. */
+const VENDORED = {
+  "papers/a/repro/x.js": "return 1;\n",
+  "papers/a/repro/y.mjs":
+    "// eslint-disable-next-line import/no-nodejs-modules\nimport fs from 'node:fs';\n",
+  "papers/a/repro/lib/z.cjs": "module.exports = 1;\n",
+};
+
+describe("paperlint lint — lints only the files paperlint owns", () => {
+  it("🔴 vendored JS under a paper is never linted, and the run stays green", async () => {
+    const r = await lint(project(VENDORED));
+    expect(r.err).not.toMatch(/Parsing error|was not found/);
+    const files = linted(r.out);
+    expect(files.filter((f) => /\.[cm]?js$/.test(f))).toEqual([]);
+    expect(r.code).toBe(0);
+  });
+
+  it("…while the paper's own files ARE linted (the other half)", async () => {
+    const root = project({
+      ...VENDORED,
+      "papers/a/reviews/r1.md": "# review\n",
+    });
+    const files = linted((await lint(root)).out);
+    for (const f of [
+      "papers/a/paper.tex",
+      "papers/a/PIPELINE-STATUS.md",
+      "papers/a/reviews/r1.md",
+    ])
+      expect(files).toContain(join(root, f));
+  });
+
+  it("a papers directory holding only vendored JS lints NOTHING — and says so", async () => {
+    const root = project({
+      "papers/a/paper.tex": "",
+      ...VENDORED,
+    });
+    rmSync(join(root, "papers/a/paper.tex"));
+    rmSync(join(root, "papers/a/PIPELINE-STATUS.md"));
+    // From the config: the directory holds no paper, which is said before ESLint runs.
+    const fromConfig = await lint(root);
+    expect(fromConfig.code).toBe(2);
+    expect(fromConfig.err).toMatch(/^no papers in papers\//);
+    // Named on the command line: ESLint gets it, lints nothing, and the run says so.
+    const named = await lint(root, ["papers"]);
+    expect(named.code).toBe(1);
+    expect(named.err).toMatch(/nothing was linted/);
+  });
+
+  it("a file named on the command line that paperlint does not lint is refused by name", async () => {
+    const root = project(VENDORED);
+    const r = await lint(root, ["papers/a/repro/x.js"]);
+    expect(r.code).toBe(2);
+    expect(r.err).toMatch(
+      /papers\/a\/repro\/x\.js is not a file paperlint lints/,
+    );
+    expect(r.err).toMatch(/PIPELINE-STATUS\.md/);
+  });
+
+  it("a paper file named on the command line is still linted", async () => {
+    const root = project(VENDORED);
+    const r = await lint(root, ["papers/a/paper.tex"]);
+    expect(linted(r.out)).toEqual([join(root, "papers/a/paper.tex")]);
+  });
+});
+
+describe("`rules` blocks reach only the files each rule is written for", () => {
+  it.each(["paper/source", "paper/section-word", "review/frontmatter"])(
+    "🔴 %s over papers/** runs, instead of crashing inside ESLint",
+    async (id) => {
+      const root = project({
+        "paperlint.json": JSON.stringify({
+          rules: [{ files: ["papers/**"], rules: { [id]: "warn" } }],
+        }),
+      });
+      const r = await lint(root);
+      expect(r.err).not.toMatch(/Could not find/);
+      expect(r.code).toBe(0);
+    },
+  );
+
+  it("the same, from a paper's own paperlint.json", async () => {
+    const root = project({
+      "papers/a/paperlint.json": JSON.stringify({
+        rules: { "paper/source": "warn", "paper/section-word": "off" },
+      }),
+    });
+    const r = await lint(root);
+    expect(r.err).not.toMatch(/Could not find/);
+    expect(r.code).toBe(0);
+  });
+});
+
+describe("`rules` blocks — where the rule lands", () => {
+  it("on its own files and on no other", async () => {
+    const root = project();
+    const eslint = new ESLint({
+      cwd: root,
+      overrideConfigFile: true,
+      overrideConfig: buildConfig(
+        {
+          rules: [
+            {
+              basePath: root,
+              files: ["papers/**"],
+              rules: { "paper/source": "warn", "paper/section-word": "off" },
+            },
+          ],
+        },
+        null,
+      ) as Linter.Config[],
+    });
+    const on = async (file: string) =>
+      (
+        (await eslint.calculateConfigForFile(join(root, file))) as {
+          rules: Record<string, unknown>;
+        }
+      ).rules;
+    const status = await on("papers/a/PIPELINE-STATUS.md");
+    expect(status["paper/source"]).toEqual([1]);
+    expect(status["paper/section-word"]).toBeUndefined();
+    const draft = await on("papers/a/paper.md");
+    expect(draft["paper/section-word"]).toEqual([0]);
+    expect(draft["paper/source"]).toBeUndefined();
+  });
+});
+
+describe("paper-files — the pieces", () => {
+  const own = [
+    { plugins: { g: { rules: { any: {} } } } },
+    { files: ["**/a.md"], plugins: { p: { rules: { one: {} } } } },
+    { files: ["**/b.md", "**/c.md"], plugins: { p: { rules: { two: {} } } } },
+    { files: ["**/c.md"], plugins: { p: { rules: { two: {} } } } },
+  ];
+
+  it("owned patterns are every own block's files, once", () => {
+    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", () => {
+    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"]);
+  });
+});
+
+describe("paper-files — narrowing a block", () => {
+  const own = [
+    { plugins: { g: { rules: { any: {} } } } },
+    { files: ["**/a.md"], plugins: { p: { rules: { one: {} } } } },
+    { files: ["**/b.md", "**/c.md"], plugins: { p: { rules: { two: {} } } } },
+  ];
+
+  it("a block is split per owner, its files ANDed with the owner's", () => {
+    const blocks = narrowToOwners(
+      {
+        basePath: "/x",
+        files: ["papers/**"],
+        ignores: ["papers/old/**"],
+        rules: { "p/one": "warn", "p/two": "error", "g/any": "off" },
+      },
+      ruleOwners(own),
+    );
+    expect(blocks).toEqual([
+      {
+        basePath: "/x",
+        files: [["papers/**", "**/a.md"]],
+        ignores: ["papers/old/**"],
+        rules: { "p/one": "warn" },
+      },
+      {
+        basePath: "/x",
+        files: [
+          ["papers/**", "**/b.md"],
+          ["papers/**", "**/c.md"],
+        ],
+        ignores: ["papers/old/**"],
+        rules: { "p/two": "error" },
+      },
+      {
+        basePath: "/x",
+        files: ["papers/**"],
+        ignores: ["papers/old/**"],
+        rules: { "g/any": "off" },
+      },
+    ]);
+  });
+
+  it("without `files`, the owner's patterns are the block's files", () => {
+    expect(
+      narrowToOwners(
+        { basePath: "/x", rules: { "p/one": "warn" } },
+        ruleOwners(own),
+      ),
+    ).toEqual([
+      { basePath: "/x", files: ["**/a.md"], rules: { "p/one": "warn" } },
+    ]);
+  });
+
+  it("a rule registered nowhere in this config reaches nothing — no block, no crash", () => {
+    expect(
+      narrowToOwners(
+        { basePath: "/x", rules: { "tex/x": "warn" } },
+        ruleOwners(own),
+      ),
+    ).toEqual([]);
+  });
+});
+
+describe("paper-files — the scope", () => {
+  it("ignores everything, then un-ignores directories and owned files, then re-ignores ESLint's defaults", () => {
+    expect(scopeToOwned(["**/a.md"]).ignores).toEqual([
+      "**/*",
+      "!**/*/",
+      "!**/a.md",
+      "**/node_modules/",
+      "**/.git/",
+    ]);
+  });
+});

package/src/paper-files.ts

@@ -0,0 +1,144 @@
+/**
+ * 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.
+ *
+ * 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 plugins?: Readonly<
+    Record<string, { readonly rules?: Readonly<Record<string, unknown>> }>
+  >;
+}
+
+/** 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");
+
+/** Every glob paperlint's own blocks lint, once, in config order. */
+export function ownedPatterns(own: readonly unknown[]): string[] {
+  return [...new Set(own.flatMap((b) => globsOf(b as Block)))];
+}
+
+/** 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}`),
+  );
+
+/** An owner seen so far, widened by one more block's globs; `null` (every file) absorbs all. */
+const widen = (
+  had: readonly string[] | null | undefined,
+  files: readonly string[] | null,
+): readonly string[] | null =>
+  had === null || files === null
+    ? null
+    : [...new Set([...(had ?? []), ...files])];
+
+/**
+ * Rule id → the globs of the blocks that register its plugin with that rule. `null`: the plugin
+ * is registered for every file (a block without `files`), so the rule resolves anywhere.
+ */
+export function ruleOwners(
+  own: readonly unknown[],
+): Map<string, readonly string[] | null> {
+  const owners = new Map<string, readonly string[] | null>();
+  for (const raw of own) {
+    const b = raw as Block;
+    const files = b.files ? globsOf(b) : null;
+    for (const id of ruleIdsOf(b)) owners.set(id, widen(owners.get(id), files));
+  }
+  return owners;
+}
+
+/**
+ * One consumer block → one block per owner, each carrying only that owner's rules, its `files`
+ * ANDed with the owner's globs. 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 string[] | null>,
+): 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].map(([key, rules]) => {
+    const owner = JSON.parse(key) as string[] | null;
+    const files: readonly FilesEntry[] | undefined =
+      owner === null
+        ? block.files
+        : block.files
+          ? block.files.flatMap((f) => owner.map((o) => [f, o]))
+          : owner;
+    return {
+      basePath: block.basePath,
+      ...(files ? { files } : {}),
+      ...(block.ignores ? { ignores: block.ignores } : {}),
+      rules,
+    };
+  });
+}