paperlint 3.0.0 → 3.1.1

package/src/link-skills.test.ts

@@ -0,0 +1,105 @@
+/**
+ * link-skills.ts edges the harness does not reach: a resolver error without a code, a package that
+ * resolved outside every `node_modules` up the tree, a skills directory that is missing or holds a
+ * dangling link, a skills home that cannot be made, an entry that is a plain file, and — through
+ * the injected fs — an entry that cannot be resolved and a link that cannot be created.
+ */
+import assert from "node:assert/strict";
+import {
+  lstatSync,
+  mkdirSync,
+  readlinkSync,
+  realpathSync,
+  symlinkSync,
+} from "node:fs";
+import { join } from "node:path";
+import { test } from "vitest";
+import { useTempDir, writeTree } from "../test/support.mjs";
+import { linkSkills, locatePackage, type LinkFs } from "./link-skills.ts";
+
+const root = useTempDir("paperlint-link-skills-");
+const realFs: LinkFs = { lstatSync, realpathSync, readlinkSync, symlinkSync };
+
+/** A package directory shipping skills `names` under `skills/`. */
+function pkg(name: string, names: string[]): string {
+  const dir = join(root, name, "pkg");
+  mkdirSync(join(dir, "skills"), { recursive: true });
+  writeTree(
+    dir,
+    Object.fromEntries(names.map((n) => [`skills/${n}/SKILL.md`, "# s\n"])),
+  );
+  return dir;
+}
+const at = (dir: string) => () => ({ dir, spelled: dir });
+
+test("locatePackage: a resolver error without a code; a package found outside every node_modules", () => {
+  assert.deepEqual(
+    locatePackage(root, {
+      resolveManifest: () => {
+        throw new Error("odd\nsecond line");
+      },
+    }),
+    { error: "error: odd" },
+  );
+  const elsewhere = pkg("elsewhere", []);
+  assert.deepEqual(
+    locatePackage(root, {
+      resolveManifest: () => join(elsewhere, "package.json"),
+    }),
+    { dir: elsewhere, spelled: elsewhere },
+  );
+});
+
+test("a package without a skills directory, or one holding a dangling link, is not linked", () => {
+  const bare = join(root, "bare");
+  mkdirSync(bare, { recursive: true });
+  const missing = linkSkills(join(root, "p1"), { locate: at(bare) });
+  assert.deepEqual(missing, {
+    ok: false,
+    error: `the package's skills directory is missing: ${join(bare, "skills")}`,
+  });
+  const dangling = pkg("dangling", ["a"]);
+  symlinkSync(join(root, "gone"), join(dangling, "skills", "b"));
+  const r = linkSkills(join(root, "p2"), { locate: at(dangling) });
+  assert.equal(r.ok, false);
+  assert.match(!r.ok ? r.error : "", /^1 skill link\(s\) in .* lead nowhere:/);
+});
+
+test("a skills home that cannot be made is named", () => {
+  const project = writeTree(join(root, "p3"), {
+    ".claude": "a file, not a directory",
+  });
+  const r = linkSkills(project, { locate: at(pkg("home", ["a"])) });
+  assert.equal(r.ok, false);
+  assert.match(!r.ok ? r.error : "", /^cannot create .*\.claude\/skills: /);
+});
+
+test("entries that are someone else's: a plain file, one that cannot be resolved, a link that cannot be made", () => {
+  const shipped = pkg("entries", ["file", "unresolved", "refused"]);
+  const project = writeTree(join(root, "p4"), { ".claude/skills/file": "x" });
+  mkdirSync(join(project, ".claude", "skills", "unresolved"));
+  const fs: LinkFs = {
+    ...realFs,
+    realpathSync: (p) => {
+      if (p.endsWith("unresolved")) throw new Error("ELOOP");
+      return realpathSync(p);
+    },
+    symlinkSync: () => {
+      throw new Error("EEXIST: raced");
+    },
+  };
+  const r = linkSkills(project, { locate: at(shipped), fs });
+  assert.deepEqual(r.ok ? r.links : [], [
+    { name: "file", status: "foreign", reason: "a file" },
+    {
+      name: "refused",
+      status: "foreign",
+      reason: "could not create the link: EEXIST: raced",
+    },
+    {
+      name: "unresolved",
+      status: "foreign",
+      reason: "an entry that cannot be resolved",
+    },
+  ]);
+});

package/src/link-skills.ts

@@ -60,13 +60,18 @@ export type Located =
  *
  * @returns `dir` — the real directory; `spelled` — the same directory as the project names it.
  */
-export function locatePackage(project: string): Located {
+export function locatePackage(
+  project: string,
+  {
+    resolveManifest = (from: string): string =>
+      createRequire(
+        pathToFileURL(join(from, "__paperlint_locate__.js")).href,
+      ).resolve(`${PACKAGE_NAME}/package.json`),
+  }: { resolveManifest?: (project: string) => string } = {},
+): Located {
   let manifest: string;
   try {
-    const req = createRequire(
-      pathToFileURL(join(project, "__paperlint_locate__.js")).href,
-    );
-    manifest = req.resolve(`${PACKAGE_NAME}/package.json`);
+    manifest = resolveManifest(project);
   } catch (e) {
     return {
       error: `${(e as NodeJS.ErrnoException).code ?? "error"}: ${(e as Error).message.split("\n")[0]}`,
@@ -126,10 +131,28 @@ export type LinkReport =
     }
   | { readonly ok: false; readonly error: string };
 
+/** The filesystem calls linking makes — the disk by default; a test stages a race or a refusal. */
+export interface LinkFs {
+  readonly lstatSync: (p: string) => {
+    isSymbolicLink(): boolean;
+    isDirectory(): boolean;
+  };
+  readonly realpathSync: (p: string) => string;
+  readonly readlinkSync: (p: string) => string;
+  readonly symlinkSync: (target: string, path: string, type: "dir") => void;
+}
+const nodeLinkFs: LinkFs = {
+  lstatSync,
+  realpathSync,
+  readlinkSync,
+  symlinkSync,
+};
+
 /** What occupies `entry`, judged against the directory it should lead to. */
 function inspect(
   entry: string,
   want: string,
+  { lstatSync, realpathSync, readlinkSync }: LinkFs,
 ): { status: "present" | "missing" | "foreign"; reason?: string } {
   let st;
   try {
@@ -163,15 +186,22 @@ function linkOne(
     target,
     want,
     write,
-  }: { entry: string; target: string; want: string; write: boolean },
+    fs,
+  }: {
+    entry: string;
+    target: string;
+    want: string;
+    write: boolean;
+    fs: LinkFs;
+  },
 ): SkillLink {
-  const seen = inspect(entry, want);
+  const seen = inspect(entry, want, fs);
   if (!write || seen.status !== "missing")
     return seen.reason
       ? { name, status: seen.status, reason: seen.reason }
       : { name, status: seen.status };
   try {
-    symlinkSync(target, entry, "dir");
+    fs.symlinkSync(target, entry, "dir");
     return { name, status: "created" };
   } catch (e) {
     return {
@@ -182,6 +212,16 @@ function linkOne(
   }
 }
 
+/** Create the skills home; the reason it could not be, or null. */
+function makeHome(home: string): string | null {
+  try {
+    mkdirSync(home, { recursive: true });
+    return null;
+  } catch (e) {
+    return `cannot create ${home}: ${(e as Error).message}`;
+  }
+}
+
 /**
  * Link every shipped skill into `<project>/.claude/skills/`, or — with `write: false` — only
  * report which ones are missing (that is what `paperlint doctor` asks).
@@ -191,7 +231,12 @@ export function linkSkills(
   {
     write = true,
     locate = locatePackage,
-  }: { write?: boolean; locate?: (p: string) => Located } = {},
+    fs = nodeLinkFs,
+  }: {
+    write?: boolean;
+    locate?: (p: string) => Located;
+    fs?: LinkFs;
+  } = {},
 ): LinkReport {
   const pkg = locate(project);
   if ("error" in pkg)
@@ -205,20 +250,28 @@ export function linkSkills(
   const spelledSkills = join(pkg.spelled, relative(pkg.dir, shipped.skillsDir));
 
   const home = join(project, SKILLS_HOME);
-  if (write && shipped.names.length > 0) {
-    try {
-      mkdirSync(home, { recursive: true });
-    } catch (e) {
-      return {
-        ok: false,
-        error: `cannot create ${home}: ${(e as Error).message}`,
-      };
-    }
-  }
+  const made = write && shipped.names.length > 0 ? makeHome(home) : null;
+  if (made !== null) return { ok: false, error: made };
+  return {
+    ok: true,
+    home,
+    ...linkAll(shipped, { spelledSkills, home, write, fs }),
+  };
+}
+
+/** Every shipped skill's link, and the first one's target as the report's example. */
+function linkAll(
+  shipped: { readonly skillsDir: string; readonly names: readonly string[] },
+  {
+    spelledSkills,
+    home,
+    write,
+    fs,
+  }: { spelledSkills: string; home: string; write: boolean; fs: LinkFs },
+): { example: string | null; links: SkillLink[] } {
   // A relative target resolves against the directory that PHYSICALLY holds the link, so it is
   // computed from the real one — `.claude` may itself be a symlink.
   const physicalHome = existsSync(home) ? realpathSync(home) : resolve(home);
-
   let example: string | null = null;
   const links = shipped.names.map((name): SkillLink => {
     const target = relative(physicalHome, join(spelledSkills, name));
@@ -228,7 +281,8 @@ export function linkSkills(
       target,
       want: realpathSync(join(shipped.skillsDir, name)),
       write,
+      fs,
     });
   });
-  return { ok: true, home, example, links };
+  return { example, links };
 }

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

@@ -16,7 +16,6 @@
  * ⚠️ Assertions at the TOP LEVEL: `vigiles test` imports the file and counts "did not throw"
  * as a pass.
  */
-import assert from "node:assert/strict";
 import {
   existsSync,
   mkdirSync,
@@ -32,6 +31,7 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { load } from "js-yaml";
 import { frontmatterBlock } from "../lib/markdown.mjs";
+import { createChecker } from "../lib/check.mjs";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const ROOT = dirname(HERE);
@@ -46,11 +46,7 @@ const {
 } = await import(join(HERE, "new-paper.ts"));
 const { run } = await import(join(HERE, "cli.ts"));
 
-let n = 0;
-const check = (label, cond) => {
-  n++;
-  assert.ok(cond, label);
-};
+const check = createChecker();
 
 const work = realpathSync(mkdtempSync(join(tmpdir(), "paperlint-new-")));
 const read = (...p) => readFileSync(join(...p), "utf8");
@@ -191,6 +187,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 &&
@@ -215,5 +213,5 @@ try {
 }
 
 console.log(
-  `✓ ${String(n)} assertions passed — paperlint new scaffolds what paperlint lint accepts`,
+  `✓ ${String(check.count)} assertions passed — paperlint new scaffolds what paperlint lint accepts`,
 );

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 { newPaper, OVERRIDE_DIR } from "./new-paper.ts";
+import { existsSync } from "node:fs";
+import { newPaper, OVERRIDE_DIR, reportNewPaper } 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(() => {
@@ -131,3 +134,201 @@ 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([]);
+  });
+});
+
+describe("a project's own template", () => {
+  it("🔴 a template paperlint.json with comments refuses --venue by name, and nothing is made", () => {
+    const papers = join(tmp(), "papers");
+    mkdirSync(join(papers, OVERRIDE_DIR), { recursive: true });
+    const src = join(papers, OVERRIDE_DIR, "paperlint.json");
+    writeFileSync(src, '{\n  // our house venue\n  "extends": null\n}\n');
+    const r = newPaper(papers, "p", "tex", {
+      venue: { extends: "paperlint:aisec", kind: null },
+    });
+    expect(r).toEqual({
+      ok: false,
+      reason: `--venue cannot be written into ${src}: it is not plain JSON — set "extends" by hand`,
+    });
+    expect(existsSync(join(papers, "p"))).toBe(false);
+  });
+
+  it("the report names where each created file came from", () => {
+    const papers = join(tmp(), "papers");
+    mkdirSync(join(papers, OVERRIDE_DIR), { recursive: true });
+    writeFileSync(join(papers, OVERRIDE_DIR, "paperlint.json"), "{}\n");
+    const lines = reportNewPaper(newPaper(papers, "p", "tex"), (p) => p);
+    expect(lines).toContain(
+      "      + paperlint.json  (from the project's .template/ template)",
+    );
+    expect(
+      lines.filter((l) => l.endsWith("(from the package template)")).length,
+    ).toBeGreaterThan(0);
+  });
+});