paperlint 2.1.0 → 3.1.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/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(() => {
@@ -83,14 +86,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 +93,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)
@@ -143,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([]);
+  });
+});