paperlint 2.0.1 → 3.0.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.harness.mjs

@@ -98,11 +98,11 @@ try {
   const papers = join(work, "papers");
   const r = newPaper(papers, "demo", "tex");
   check(
-    "a fresh folder gets the scorecard and a .tex source, both from the package",
+    "a fresh folder gets the scorecard, a .tex source and paperlint.json, all from the package",
     r.ok &&
       r.fresh &&
       r.files.map((f) => `${f.file}:${f.status}:${f.from}`).join(" ") ===
-        "PIPELINE-STATUS.md:created:package paper.tex:created:package",
+        "PIPELINE-STATUS.md:created:package paper.tex:created:package paperlint.json:created:package",
   );
   const status = read(papers, "demo", STATUS_FILE);
   const fm = front(status);
@@ -122,8 +122,10 @@ try {
   );
   const l = await lint(join(papers, "demo"));
   check(
-    "🔴 `paperlint lint` passes the scaffold clean — the first run is green, not a missing-file error",
-    l.code === 0 && /no findings/.test(l.text),
+    "🔴 `paperlint lint` passes the scaffold — exit 0, not a missing-file error — with the one warning that no venue is chosen yet",
+    l.code === 0 &&
+      /names no venue preset yet/.test(l.text) &&
+      /1 problem \(0 errors, 1 warning\)/.test(l.text),
   );
 
   // The format contract of the skills' checker: four sections, parsed.
@@ -171,9 +173,10 @@ try {
   );
   check(
     "wantedFiles asks for a source only when neither format is there",
-    wantedFiles(join(papers, "old"), "tex").join() === STATUS_FILE &&
+    wantedFiles(join(papers, "old"), "tex").join() ===
+      `${STATUS_FILE},paperlint.json` &&
       wantedFiles(join(papers, "nowhere"), "md").join() ===
-        `${STATUS_FILE},paper.md`,
+        `${STATUS_FILE},paper.md,paperlint.json`,
   );
   writeFileSync(join(papers, "afile"), "x");
   check(

package/src/new-paper.test.ts

@@ -0,0 +1,133 @@
+/**
+ * `paperlint new` writes `<paper>/paperlint.json` — from the package's template, or from the
+ * project's `<papers>/.template/` when it has one — with no venue chosen yet, which lint then names
+ * in one warning instead of staying silent.
+ */
+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 { newPaper, OVERRIDE_DIR } from "./new-paper.ts";
+import { parsePaperSettings } from "./paper-settings.ts";
+import { run } from "./cli.ts";
+
+const dirs: string[] = [];
+afterEach(() => {
+  for (const d of dirs.splice(0)) rmSync(d, { recursive: true, force: true });
+});
+const tmp = () => {
+  const d = realpathSync(mkdtempSync(join(tmpdir(), "paperlint-new-")));
+  dirs.push(d);
+  return d;
+};
+const settingsOf = (dir: string) =>
+  JSON.parse(readFileSync(join(dir, "paperlint.json"), "utf8")) as Record<
+    string,
+    unknown
+  >;
+
+describe("paperlint new — paperlint.json", () => {
+  it("is always written, from the package template: no venue chosen yet, and valid", () => {
+    const papers = join(tmp(), "papers");
+    const r = newPaper(papers, "demo", "tex");
+    expect(r.ok && r.files.find((f) => f.file === "paperlint.json")).toEqual({
+      file: "paperlint.json",
+      status: "created",
+      from: "package",
+    });
+    const s = settingsOf(join(papers, "demo"));
+    expect(s["extends"]).toBeNull();
+    expect(String(s["$comment"])).toMatch(/paperlint:agenticdev/);
+    expect(parsePaperSettings(s)).toEqual({
+      ok: true,
+      value: { extends: null, kind: null, pdf: null, rules: null },
+    });
+  });
+
+  it("comes from the project's <papers>/.template/ when it has one", () => {
+    const papers = join(tmp(), "papers");
+    mkdirSync(join(papers, OVERRIDE_DIR), { recursive: true });
+    writeFileSync(
+      join(papers, OVERRIDE_DIR, "paperlint.json"),
+      '{ "extends": "paperlint:aisec", "kind": "research" }\n',
+    );
+    const r = newPaper(papers, "house", "tex");
+    expect(r.ok && r.files.find((f) => f.file === "paperlint.json")?.from).toBe(
+      "project",
+    );
+    expect(settingsOf(join(papers, "house"))).toEqual({
+      extends: "paperlint:aisec",
+      kind: "research",
+    });
+  });
+
+  it("is never overwritten", () => {
+    const papers = join(tmp(), "papers");
+    mkdirSync(join(papers, "p"), { recursive: true });
+    writeFileSync(
+      join(papers, "p", "paperlint.json"),
+      '{"extends":"paperlint:aisec"}',
+    );
+    const r = newPaper(papers, "p", "tex");
+    expect(
+      r.ok && r.files.find((f) => f.file === "paperlint.json")?.status,
+    ).toBe("kept");
+    expect(settingsOf(join(papers, "p"))).toEqual({
+      extends: "paperlint:aisec",
+    });
+  });
+});
+
+describe("paperlint lint — a paper with no venue preset chosen", () => {
+  async function lintNew(extendsValue: string | null) {
+    const root = tmp();
+    writeFileSync(
+      join(root, "package.json"),
+      JSON.stringify({ name: "c", private: true }),
+    );
+    newPaper(join(root, "papers"), "demo", "tex");
+    if (extendsValue !== null)
+      writeFileSync(
+        join(root, "papers", "demo", "paperlint.json"),
+        JSON.stringify({ extends: extendsValue, kind: "short" }),
+      );
+    const out: string[] = [];
+    const code = await run(["lint", "--json"], {
+      cwd: root,
+      log: (s: string) => out.push(s),
+      err: () => {},
+    });
+    const messages = (
+      JSON.parse(out.join("\n")) as {
+        messages: { ruleId: string; severity: number; message: string }[];
+      }[]
+    ).flatMap((r) => r.messages);
+    return { code, messages };
+  }
+
+  it("gets exactly one warning naming the file to set, and exits 0", async () => {
+    const { code, messages } = await lintNew(null);
+    expect(code).toBe(0);
+    expect(messages).toHaveLength(1);
+    expect(messages[0]?.ruleId).toBe("pdf/measured");
+    expect(messages[0]?.severity).toBe(1);
+    expect(messages[0]?.message).toMatch(/names no venue preset yet/);
+    expect(messages[0]?.message).toMatch(
+      /set "extends" in .*papers\/demo\/paperlint\.json/,
+    );
+  });
+
+  it("a paper with a real extends does not get it", async () => {
+    const { messages } = await lintNew("paperlint:agenticdev");
+    expect(messages.map((m) => m.message).join("\n")).not.toMatch(
+      /names no venue preset yet/,
+    );
+  });
+});

package/src/new-paper.ts

@@ -25,6 +25,7 @@ import {
 /* eslint-enable boundaries/dependencies */
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { CONFIG_FILE } from "../lib/paper-config.mjs";
 
 export type PaperFormat = "tex" | "md";
 export const FORMATS: readonly PaperFormat[] = ["tex", "md"];
@@ -83,10 +84,14 @@ export type NewPaperResult =
   | { readonly ok: false; readonly reason: string };
 
 /**
- * The files a paper folder must end up with: the scorecard, plus a source in `format` — unless
- * it already has a source in EITHER format, in which case that one stands and nothing is added.
+ * The files a paper folder must end up with: the scorecard, a source in `format` — unless it
+ * 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), CONFIG_FILE];
+}
+
+function scorecardAndSource(dir: string, format: PaperFormat): string[] {
   const hasSource = Object.values(SOURCE_FILE).some((f) =>
     existsSync(join(dir, f)),
   );