paperlint 2.1.0 → 3.0.0

package/src/link-skills.mutations.mjs

@@ -84,13 +84,13 @@ process.exit(
         edits: [
           [
             SRC,
-            '  unlinkSync,\n} from "node:fs";',
-            '  unlinkSync,\n  rmSync,\n} from "node:fs";',
+            '  symlinkSync,\n} from "node:fs";',
+            '  symlinkSync,\n  rmSync,\n} from "node:fs";',
           ],
           [
             SRC,
-            "  if (!write || !fixable) {",
-            '  if (!write || seen.status === "present") {',
+            '  if (!write || seen.status !== "missing")',
+            '  if (!write || seen.status === "present")',
           ],
           [
             SRC,
@@ -123,7 +123,11 @@ process.exit(
           "the difference between looking and changing. `paperlint doctor` would quietly repair the " +
           "state it is supposed to report, so the report can never show the gap",
         edits: [
-          [SRC, "  if (!write || !fixable) {", "  if (!fixable) {"],
+          [
+            SRC,
+            '  if (!write || seen.status !== "missing")',
+            '  if (seen.status !== "missing")',
+          ],
           [
             SRC,
             "  if (write && shipped.names.length > 0) {",

package/src/link-skills.ts

@@ -34,15 +34,13 @@ import {
   readlinkSync,
   realpathSync,
   symlinkSync,
-  unlinkSync,
 } from "node:fs";
 /* eslint-enable boundaries/dependencies */
 import { createRequire } from "node:module";
-import { dirname, join, relative, resolve, sep } from "node:path";
+import { dirname, join, relative, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import {
   installedSkills,
-  LEGACY_PACKAGE_NAME,
   PACKAGE_NAME,
   SHIPPED_SKILLS_DIR,
 } from "../skills/paper-pipeline/scripts/consumer.mjs";
@@ -109,8 +107,7 @@ export function shippedSkills(
   }
 }
 
-export type LinkStatus =
-  "created" | "replaced" | "present" | "missing" | "foreign";
+export type LinkStatus = "created" | "present" | "missing" | "foreign";
 
 export interface SkillLink {
   readonly name: string;
@@ -129,27 +126,17 @@ export type LinkReport =
     }
   | { readonly ok: false; readonly error: string };
 
-/**
- * What occupies `entry`, judged against the directory it should lead to. A link spelled exactly as
- * an install under the package's old name wrote it (`legacyTarget`) is `stale`: ours, from before
- * the rename, and replaced on the next `init`.
- */
+/** What occupies `entry`, judged against the directory it should lead to. */
 function inspect(
   entry: string,
   want: string,
-  legacyTarget: string,
-): { status: "present" | "missing" | "foreign" | "stale"; reason?: string } {
+): { status: "present" | "missing" | "foreign"; reason?: string } {
   let st;
   try {
     st = lstatSync(entry);
   } catch {
     return { status: "missing" };
   }
-  if (st.isSymbolicLink() && readlinkSync(entry) === legacyTarget)
-    return {
-      status: "stale",
-      reason: `a link into ${LEGACY_PACKAGE_NAME}, the package's old name — \`npx ${PACKAGE_NAME} init\` replaces it`,
-    };
   try {
     if (realpathSync(entry) === want) return { status: "present" };
   } catch {
@@ -168,10 +155,7 @@ function inspect(
   };
 }
 
-/**
- * One skill: inspect its entry and, when writing, create the link — or replace one an install
- * under the package's old name made.
- */
+/** One skill: inspect its entry and, when writing, create the link. */
 function linkOne(
   name: string,
   {
@@ -181,22 +165,14 @@ function linkOne(
     write,
   }: { entry: string; target: string; want: string; write: boolean },
 ): SkillLink {
-  const legacyTarget = target.replace(
-    `node_modules${sep}${PACKAGE_NAME}${sep}`,
-    `node_modules${sep}${LEGACY_PACKAGE_NAME}${sep}`,
-  );
-  const seen = inspect(entry, want, legacyTarget);
-  const fixable = seen.status === "missing" || seen.status === "stale";
-  if (!write || !fixable) {
-    const status = seen.status === "stale" ? "foreign" : seen.status;
+  const seen = inspect(entry, want);
+  if (!write || seen.status !== "missing")
     return seen.reason
-      ? { name, status, reason: seen.reason }
-      : { name, status };
-  }
+      ? { name, status: seen.status, reason: seen.reason }
+      : { name, status: seen.status };
   try {
-    if (seen.status === "stale") unlinkSync(entry);
     symlinkSync(target, entry, "dir");
-    return { name, status: seen.status === "stale" ? "replaced" : "created" };
+    return { name, status: "created" };
   } catch (e) {
     return {
       name,

package/src/lint-fix.test.ts

@@ -0,0 +1,120 @@
+/**
+ * `paperlint lint --fix`, and the settings that replaced the ratchets, through the command.
+ */
+import {
+  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 } from "./cli.ts";
+
+const dirs: string[] = [];
+afterEach(() => {
+  for (const d of dirs.splice(0)) rmSync(d, { recursive: true, force: true });
+});
+
+function project(
+  settings: Record<string, unknown>,
+  files: Record<string, string> = {},
+): string {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "paperlint-fix-")));
+  dirs.push(root);
+  const all: Record<string, string> = {
+    "package.json": JSON.stringify({ name: "c", private: true }),
+    "paperlint.json": JSON.stringify({ papersDir: "papers", ...settings }),
+    "papers/a/PIPELINE-STATUS.md": "---\nstages: []\n---\n",
+    "papers/a/paper.md": "# Intro\n\nSee §5, §6 and §7; p < .05.\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[] = []) {
+  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 ruleIds = (stdout: string): string[] =>
+  (JSON.parse(stdout) as { messages: { ruleId: string }[] }[]).flatMap((r) =>
+    r.messages.map((m) => m.ruleId),
+  );
+
+describe("paperlint lint --fix", () => {
+  it("🔴 three `§` and a bare decimal → --fix → zero findings, and the file says Section", async () => {
+    const root = project({});
+    const before = ruleIds((await lint(root)).out);
+    expect(before.filter((r) => r === "paper/section-word")).toHaveLength(3);
+    expect(before).toContain("paper/leading-zero");
+    const fixed = await lint(root, ["--fix"]);
+    expect(ruleIds(fixed.out)).not.toContain("paper/section-word");
+    expect(ruleIds(fixed.out)).not.toContain("paper/leading-zero");
+    expect(readFileSync(join(root, "papers/a/paper.md"), "utf8")).toBe(
+      "# Intro\n\nSee Section 5, Section 6 and Section 7; p < 0.05.\n",
+    );
+  });
+
+  it("without --fix nothing is written", async () => {
+    const root = project({});
+    await lint(root);
+    expect(readFileSync(join(root, "papers/a/paper.md"), "utf8")).toMatch(/§5/);
+  });
+});
+
+describe("sibling cards: `read:` is required, from the package's own schema", () => {
+  it("a card without it is a warning; with it, silent; the index is not a card", async () => {
+    const root = project(
+      {},
+      {
+        "papers/a/siblings/README.md": "# Siblings\n",
+        "papers/a/siblings/smith2025.md": "# Smith 2025\n",
+        "papers/a/siblings/jones2024.md": "---\nread: abstract\n---\n# Jones\n",
+      },
+    );
+    const results = JSON.parse((await lint(root)).out) as {
+      filePath: string;
+      messages: { ruleId: string; severity: number }[];
+    }[];
+    const of = (name: string) =>
+      results.find((r) => r.filePath.endsWith(name))?.messages ?? null;
+    expect(of("smith2025.md")?.map((m) => [m.ruleId, m.severity])).toEqual([
+      ["sibling/frontmatter", 1],
+    ]);
+    expect(of("jones2024.md")).toEqual([]);
+    expect(of("siblings/README.md")).toBeNull();
+  });
+});
+
+describe("settings: what 3.0.0 removed is an ordinary unknown key or rule", () => {
+  it.each([
+    "typographyDebt",
+    "authorListCommand",
+    "docFields",
+    "causeMarker",
+    "reviewSchema",
+  ])("%s → the generic unknown-key error", async (key) => {
+    const r = await lint(project({ [key]: 1 }));
+    expect(r.code).toBe(2);
+    expect(r.err).toMatch(new RegExp(`unknown key "${key}"`));
+  });
+
+  it("paper/typography → not a rule paperlint ships", async () => {
+    const r = await lint(project({ rules: { "paper/typography": "off" } }));
+    expect(r.code).toBe(2);
+    expect(r.err).toMatch(/"paper\/typography" is not a rule paperlint ships/);
+  });
+});

package/src/new-paper.test.ts

@@ -83,14 +83,6 @@ describe("paperlint new — paperlint.json", () => {
       extends: "paperlint:aisec",
     });
   });
-
-  it("is not added beside a pre-2.1.0 venue.json — `paperlint init` moves that one", () => {
-    const papers = join(tmp(), "papers");
-    mkdirSync(join(papers, "old"), { recursive: true });
-    writeFileSync(join(papers, "old", "venue.json"), '{"venue":"aisec"}');
-    const r = newPaper(papers, "old", "tex");
-    expect(r.ok && r.files.map((f) => f.file)).not.toContain("paperlint.json");
-  });
 });
 
 describe("paperlint lint — a paper with no venue preset chosen", () => {
@@ -98,11 +90,7 @@ describe("paperlint lint — a paper with no venue preset chosen", () => {
     const root = tmp();
     writeFileSync(
       join(root, "package.json"),
-      JSON.stringify({
-        name: "c",
-        private: true,
-        paperlint: { papersDir: "papers" },
-      }),
+      JSON.stringify({ name: "c", private: true }),
     );
     newPaper(join(root, "papers"), "demo", "tex");
     if (extendsValue !== null)

package/src/new-paper.ts

@@ -25,10 +25,7 @@ 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";
+import { CONFIG_FILE } from "../lib/paper-config.mjs";
 
 export type PaperFormat = "tex" | "md";
 export const FORMATS: readonly PaperFormat[] = ["tex", "md"];
@@ -91,7 +88,7 @@ export type NewPaperResult =
  * 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)];
+  return [...scorecardAndSource(dir, format), CONFIG_FILE];
 }
 
 function scorecardAndSource(dir: string, format: PaperFormat): string[] {
@@ -101,18 +98,6 @@ function scorecardAndSource(dir: string, format: PaperFormat): string[] {
   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-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/",
+    ]);
+  });
+});