paperlint 2.1.0 → 3.0.0

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,
+    };
+  });
+}

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",
@@ -80,26 +71,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 +108,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 +174,19 @@ 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: [
+        {
+          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 () => {
@@ -172,7 +213,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 +272,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/);
-  });
-});

package/src/paper-settings.test.ts

@@ -1,12 +1,12 @@
 /**
- * `<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.
+ * `<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 {
-  migrationOf,
   paperRules,
   parsePaperSettings,
   readPaperSettings,
@@ -16,9 +16,8 @@ const PAPER = "/work/papers/p";
 const SHIPPED = new Set([
   "pdf/last-page-balance",
   "pdf/profile",
-  "paper/typography",
+  "paper/section-word",
 ]);
-const enc = (s: string) => new TextEncoder().encode(s);
 
 describe("parsePaperSettings", () => {
   it("reads extends, kind, pdf and rules; every absent field is null", () => {
@@ -58,10 +57,10 @@ describe("parsePaperSettings — optional keys", () => {
     [
       "an unknown key (a typo is not silent)",
       { venu: "aisec" },
-      /unknown key "venu".*extends, kind, pdf, rules/,
+      /unknown key "venu" — known keys: papersDir, structure, rules, extends, kind, pdf/,
     ],
     [
-      "the pre-2.1.0 comment key `_`",
+      "a comment key other than `$comment`",
       { extends: "paperlint:aisec", _: "note" },
       /unknown key "_"/,
     ],
@@ -76,10 +75,15 @@ describe("parsePaperSettings — optional keys", () => {
       /"extends" must be a non-empty string/,
     ],
     [
-      "rules that are not an object",
-      { rules: ["pdf/profile"] },
+      "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);
@@ -104,21 +108,6 @@ describe("readPaperSettings", () => {
     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",
@@ -129,52 +118,92 @@ describe("readPaperSettings", () => {
   });
 });
 
-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),
-    );
+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.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("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('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({
+  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: "b.pdf",
-      $comment: "note",
+      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", () => {