paperlint 2.0.0 → 2.1.0

package/src/hooks-settings.ts

@@ -27,6 +27,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, posix } from "node:path";
 import { fileURLToPath } from "node:url";
 import {
+  BIN_FILE,
   LEGACY_PACKAGE_NAME,
   PACKAGE_NAME,
 } from "../skills/paper-pipeline/scripts/consumer.mjs";
@@ -44,13 +45,7 @@ export const WIRING_FILE = fileURLToPath(
  * and `${CLAUDE_PROJECT_DIR}/` before comparing, so this is the same file as the spelling in
  * `hooks.json`, and nothing machine-specific lands in a committed file.
  */
-export const MANAGED_BY = `node_modules/${PACKAGE_NAME}/bin/rpp.mjs`;
-
-/**
- * The same token as an install under the package's old name wrote it. A command spelled this way
- * is ours from before the rename: `init` removes it and writes the current one, `doctor` names it.
- */
-export const LEGACY_MANAGED_BY = `node_modules/${LEGACY_PACKAGE_NAME}/bin/rpp.mjs`;
+export const MANAGED_BY = `node_modules/${PACKAGE_NAME}/${BIN_FILE}`;
 
 /** The names the package's directory under `node_modules` has had. */
 const PKG_DIRS: readonly string[] = [PACKAGE_NAME, LEGACY_PACKAGE_NAME];
@@ -81,50 +76,91 @@ function bare(token: string): string {
   return unquoted.replace(/^\$\{?CLAUDE_PROJECT_DIR\}?[/\\]/, "");
 }
 
+/** A hook command reduced to what it runs: the hook, and the path token that runs it. */
+interface Run {
+  readonly name: string;
+  readonly ours: boolean;
+  readonly legacy: boolean;
+  readonly path: string;
+}
+
 /**
  * Which paperlint hook a command runs, if any, and whether it is spelled the way `init` writes it.
  *
  * Recognised spellings — each is ONE lexeme of a shell command, which is what a command is:
- *   `node <…>/node_modules/paperlint/bin/rpp.mjs hook <name>`   ours when the path is exactly
- *                                                              MANAGED_BY
- *   the same under `node_modules/research-paper-pipeline/`     `legacy`: ours before the rename
- *   `npx paperlint hook <name>`, `node_modules/.bin/paperlint hook <name>` (or the old bin names)
- *                                                              another spelling
+ *   `node <…>/node_modules/paperlint/bin/paperlint.mjs hook <name>`
+ *                          ours when the path is exactly MANAGED_BY
+ *   `node node_modules/<pkg>/bin/<any other file> hook <name>`, <pkg> this name or the old one
+ *                          `legacy`: the project-relative form `init` writes, pointing at a file
+ *                          this version does not install — what an older `init` left behind
+ *                          (1.x: `research-paper-pipeline/bin/rpp.mjs`; 2.0.0: `paperlint/bin/rpp.mjs`)
+ *   `npx paperlint hook <name>`, `node_modules/.bin/paperlint hook <name>` (or under the old package name),
+ *   an absolute path into the package's `bin/`
+ *                          another spelling
  *   `vigiles … run-program <…>/node_modules/<pkg>/hooks/<name>.hook.mjs`
- *                                                              another spelling
+ *                          another spelling
  * The last is how the one real consumer wired all three by hand before `init` could.
+ *
+ * `legacy` is decided by the SHAPE `init` writes, not by a list of past file names: any file in
+ * our `bin/` other than BIN_FILE is one that no longer ships, so a future rename is covered too.
  */
+function parseRun(command: string): Run | null {
+  const tokens = command.trim().split(/\s+/).map(bare);
+  for (let i = 0; i < tokens.length; i++) {
+    const run = runAt(tokens, i);
+    if (run) return run;
+  }
+  return null;
+}
+
+/** The path segments after `node_modules/<pkg>/`, and whether the token starts there. */
+function insidePackage(parts: readonly string[]): {
+  readonly inside: readonly string[];
+  readonly relative: boolean;
+} {
+  const at = parts.findIndex(
+    (p, j) => p === "node_modules" && PKG_DIRS.includes(parts[j + 1] ?? ""),
+  );
+  return {
+    inside: at === -1 ? [] : parts.slice(at + 2),
+    relative: at === 0,
+  };
+}
+
+/** The run token `i` starts, if it names a paperlint hook. */
+function runAt(tokens: readonly string[], i: number): Run | null {
+  const t = posix.normalize(tokens[i] ?? "");
+  const { inside, relative } = insidePackage(t.split("/"));
+  const inBin = inside[0] === "bin" && inside.length === 2;
+  const name = tokens[i + 2];
+  if (
+    (inBin || PKG_DIRS.includes(basename(t))) &&
+    tokens[i + 1] === "hook" &&
+    name
+  )
+    return {
+      name,
+      ours: t === MANAGED_BY,
+      legacy: inBin && relative && t !== MANAGED_BY,
+      path: t,
+    };
+  if (inside[0] === "hooks" && inside[1]?.endsWith(".hook.mjs"))
+    return {
+      name: basename(inside[1], ".hook.mjs"),
+      ours: false,
+      legacy: false,
+      path: t,
+    };
+  return null;
+}
+
 export function hookRun(command: string): {
   readonly name: string;
   readonly ours: boolean;
   readonly legacy: boolean;
 } | null {
-  const tokens = command.trim().split(/\s+/).map(bare);
-  for (let i = 0; i < tokens.length; i++) {
-    const t = posix.normalize(tokens[i] ?? "");
-    const parts = t.split("/");
-    const at = parts.findIndex(
-      (p, j) => p === "node_modules" && PKG_DIRS.includes(parts[j + 1] ?? ""),
-    );
-    const inside = at === -1 ? [] : parts.slice(at + 2);
-    const isBin =
-      (inside[0] === "bin" && inside[1] === "rpp.mjs") ||
-      ["rpp", ...PKG_DIRS].includes(basename(t));
-    const name = tokens[i + 2];
-    if (isBin && tokens[i + 1] === "hook" && name)
-      return {
-        name,
-        ours: t === MANAGED_BY,
-        legacy: t === LEGACY_MANAGED_BY,
-      };
-    if (inside[0] === "hooks" && inside[1]?.endsWith(".hook.mjs"))
-      return {
-        name: basename(inside[1], ".hook.mjs"),
-        ours: false,
-        legacy: false,
-      };
-  }
-  return null;
+  const run = parseRun(command);
+  return run && { name: run.name, ours: run.ours, legacy: run.legacy };
 }
 
 /** Every command in a settings object, with the event it hangs off. */
@@ -356,16 +392,23 @@ export const FRESH_CLONE_NOTE = `the commands point into node_modules/${PACKAGE_
 /** The instruction for a project that also enables the plugin (it only ever existed under the old name). */
 export const UNINSTALL_PLUGIN = `/plugin uninstall ${LEGACY_PACKAGE_NAME}@${LEGACY_PACKAGE_NAME}`;
 
-/** The doctor lines for hook commands an install under the old package name left behind. */
-function legacyLines(
-  counts: ReadonlyMap<string, { readonly legacy: number }>,
-): string[] {
-  let legacy = 0;
-  for (const c of counts.values()) legacy += c.legacy;
-  return legacy === 0
+/**
+ * The doctor lines for hook commands an older install left behind: each names the file it runs,
+ * which this version does not install, so the hook silently does nothing.
+ */
+function legacyLines(settings: Settings): string[] {
+  const stale = new Map<string, number>();
+  for (const { command } of commandsIn(settings)) {
+    const run = parseRun(command);
+    if (run?.legacy) stale.set(run.path, (stale.get(run.path) ?? 0) + 1);
+  }
+  return stale.size === 0
     ? []
     : [
-        `  ⚠ ${String(legacy)} hook command(s) still point into node_modules/${LEGACY_PACKAGE_NAME}/, the package's old name — they no longer run.`,
+        ...[...stale].map(
+          ([path, n]) =>
+            `  ⚠ ${String(n)} hook command(s) run ${path}, which this version does not install — they no longer run.`,
+        ),
         `      \`npx ${PACKAGE_NAME} init\` replaces them`,
       ];
 }
@@ -400,7 +443,7 @@ export function doctorHooks(
     out.push(`  ⚠ wired TWICE — each of these runs more than once per event:`);
     for (const n of twice) out.push(`      ${n} ×${String(total(n))}`);
     out.push(
-      `      keep one command per hook; \`npx paperlint init\` writes the rpp.mjs form`,
+      `      keep one command per hook; \`npx paperlint init\` writes the ${MANAGED_BY} form`,
     );
   }
   if (missing.length === wiring.names.length)
@@ -418,7 +461,7 @@ export function doctorHooks(
       `  ✓ wired — ${wiring.names.join(", ")}, once each`,
       `      ${FRESH_CLONE_NOTE}`,
     );
-  out.push(...legacyLines(counts));
+  out.push(...legacyLines(read.settings));
   const plugin = pluginEnabledHere(read.settings);
   if (plugin.length > 0) {
     out.push(

package/src/init.ts

@@ -2,7 +2,7 @@
  * `paperlint init` — the whole install, in the terminal it was typed in.
  *
  * 🔴 WHAT THIS COMMAND USED TO DO, AND WHY THAT WAS A DEFECT RATHER THAN A SHORTFALL. It wrote
- * `rpp.json` with a GUESSED `"papers": "papers"` and never touched `package.json`. The three hooks
+ * a separate config file with a GUESSED `"papers": "papers"` and never touched `package.json`. The three hooks
  * read the papers directory out of `package.json` and nothing else, so a consumer who followed the
  * documented install got a `paper-edit-guard` watching a directory that did not exist — and a guard
  * watching nothing is byte-identical, from outside, to a guard that is working (issue #33).
@@ -15,7 +15,7 @@
  *                      carry a paper marker. Several hits is the only case a human is asked about.
  *   declaration        WRITTEN into `package.json`, merged, never overwriting a value that is
  *                      already there. Prior art: husky's `init` edits the consumer's package.json
- *                      to add `prepare`. `rpp.json` is no longer created at all.
+ *                      to add `prepare`. No second config file is created.
  *   skills             LINKED — one relative symlink per shipped skill into `.claude/skills/`, the
  *                      only place Claude Code looks for project skills (`link-skills.ts`). An
  *                      entry of the same name that paperlint did not make is reported, never replaced.
@@ -35,8 +35,14 @@
  * an answer nobody gave. So the non-interactive path takes the stated default and SAYS which
  * default it took and why nothing was asked, rather than pretending it asked.
  */
-// eslint-disable-next-line boundaries/dependencies -- legacy I/O, moves behind a port in #76
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  unlinkSync,
+  writeFileSync,
+  // eslint-disable-next-line boundaries/dependencies -- legacy I/O, moves behind a port in #76
+} from "node:fs";
 // eslint-disable-next-line boundaries/dependencies -- legacy I/O, moves behind a port in #76
 import { spawnSync } from "node:child_process";
 import { dirname, join, relative, resolve } from "node:path";
@@ -66,10 +72,13 @@ import {
   CONFIG_KEY,
   DEFAULT_PAPERS_ROOT,
   LEGACY_CONFIG_KEY,
+  LEGACY_PAPER_SETTINGS_FILE,
   PAPERS_DIR_FIELD,
+  PAPER_SETTINGS_FILE,
   declaredSettings,
   renamedFieldMessage,
 } from "../lib/paper-config.mjs";
+import { migrationOf } from "./paper-settings.ts";
 
 /** How the papers directory was arrived at. Printed, because a guess must not read as a fact. */
 export type PapersHow =
@@ -204,8 +213,8 @@ export type DeclarationResult =
  *
  * 🔴 A HOOK CANNOT IMPORT CODE AND CANNOT WALK UP A TREE LOOKING FOR A CONFIG. It can read a path
  * it is able to spell, and the only path it can always spell is the project's own `package.json`.
- * That asymmetry is the whole reason the declaration moved here rather than the readers moving to
- * `rpp.json`: many readers against one (`docs/install.md`, "One declaration").
+ * That asymmetry is the whole reason the declaration lives here rather than in a file of its own:
+ * many readers against one (`docs/install.md`, "One declaration").
  *
  * ⚠️ Merged, not rewritten, and never over a value the consumer set — an `init` that silently
  * replaces a setting is worse than an `init` that does nothing, because the consumer keeps
@@ -259,35 +268,6 @@ function renameKey(
   );
 }
 
-export type RppJsonResult = "absent" | "kept" | "filled" | "unparsable";
-
-/**
- * `rpp.json` is no longer CREATED — but a consumer who already has one keeps it working, and it
- * gets the same `papers` value rather than being left to disagree with `package.json` in silence.
- * Two declarations that disagree is the defect `paperlint doctor` was written to catch; writing the
- * second one on purpose would be handing it new work.
- */
-export function syncRppJson(root: string, papers: string): RppJsonResult {
-  const path = join(root, "rpp.json");
-  if (!existsSync(path)) return "absent";
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- #49: replace with a real type
-  let cfg: Record<string, any>;
-  const raw = readFileSync(path, "utf8");
-  try {
-    cfg = JSON.parse(raw);
-  } catch {
-    return "unparsable";
-  }
-  if (cfg?.[PAPERS_DIR_FIELD] !== undefined) return "kept";
-  cfg[PAPERS_DIR_FIELD] = papers;
-  writeFileSync(
-    path,
-    JSON.stringify(cfg, null, 2) + (raw.endsWith("\n") ? "\n" : ""),
-    "utf8",
-  );
-  return "filled";
-}
-
 export const WORKFLOW_PATH = join(".github", "workflows", "papers.yml");
 
 /** Where the action is pinned when no release tag is known — obviously a placeholder. */
@@ -310,7 +290,7 @@ export function workflowYaml(papers: string, ref: string | null): string {
     `    runs-on: ubuntu-latest`,
     `    steps:`,
     `      - uses: actions/checkout@v4`,
-    `      - uses: zernie/research-paper-pipeline@${ref ?? UNPINNED_REF}`,
+    `      - uses: zernie/paperlint@${ref ?? UNPINNED_REF}`,
     `        with:`,
     `          paths: ${papers}`,
     ``,
@@ -380,7 +360,7 @@ export function reportWorkflow(
   if (wf !== "written" && wf !== "kept")
     out.push(
       `      to run the same checks in CI, add this step to a workflow:`,
-      `        - uses: zernie/research-paper-pipeline@${ref ?? UNPINNED_REF}`,
+      `        - uses: zernie/paperlint@${ref ?? UNPINNED_REF}`,
       `          with:`,
       `            paths: ${papersDir}`,
     );
@@ -638,6 +618,73 @@ export interface InitOptions {
 }
 
 /** Reads one line from a real terminal. Kept out of `init` so the command stays testable. */
+/**
+ * Move every paper's pre-2.1.0 `venue.json` to `paperlint.json`, the way the old package.json key
+ * is moved, and in the same step `"venue": "aisec"` becomes `"extends": "paperlint:aisec"`: written
+ * as `paperlint.json` when it is alone, removed when `paperlint.json` already says the same, and
+ * REFUSED — both files left as they are — when they differ, since there is no way to know which
+ * one the author means. `code` is 2 when anything was refused.
+ */
+export function migratePaperSettings(papersAbs: string): {
+  readonly code: number;
+  readonly lines: readonly string[];
+} {
+  const lines: string[] = [];
+  let code = 0;
+  for (const dir of papersIn(papersAbs, [
+    ...PAPER_MARKERS,
+    LEGACY_PAPER_SETTINGS_FILE,
+  ])) {
+    const r = migrateOne(dir, (p) => relative(papersAbs, p));
+    if (r === null) continue;
+    lines.push(r.line);
+    if (r.refused) code = 2;
+  }
+  return {
+    code,
+    lines: lines.length ? ["", "paper settings", ...lines] : [],
+  };
+}
+
+/** One paper's move: done, and the line that says so — or null when there is nothing to move. */
+function migrateOne(
+  dir: string,
+  shown: (p: string) => string,
+): { readonly line: string; readonly refused: boolean } | null {
+  const [from, to] = [LEGACY_PAPER_SETTINGS_FILE, PAPER_SETTINGS_FILE].map(
+    (f) => join(dir, f),
+  ) as [string, string];
+  const read = (p: string) => (existsSync(p) ? readFileSync(p) : null);
+  const plan = migrationOf(read(from), read(to));
+  switch (plan.kind) {
+    case "none":
+      return null;
+    case "move":
+      writeFileSync(to, plan.text);
+      unlinkSync(from);
+      return {
+        line: `  ✓ ${shown(from)} → ${shown(to)} ("venue" is now "extends": "paperlint:<name>"; renamed in paperlint 2.1.0)`,
+        refused: false,
+      };
+    case "drop-legacy":
+      unlinkSync(from);
+      return {
+        line: `  ✓ ${shown(from)} removed — ${shown(to)} already says the same`,
+        refused: false,
+      };
+    case "conflict":
+      return {
+        line: `  ✗ ${shown(from)} and ${shown(to)} both exist and differ — nothing was moved. Keep ${PAPER_SETTINGS_FILE}, copy what you need from ${LEGACY_PAPER_SETTINGS_FILE} into it (its "venue": "x" is "extends": "paperlint:x"), delete ${LEGACY_PAPER_SETTINGS_FILE}, then run init again`,
+        refused: true,
+      };
+    case "broken":
+      return {
+        line: `  ✗ ${shown(from)} was not moved: ${plan.why}`,
+        refused: true,
+      };
+  }
+}
+
 export async function askOnTerminal(question: string): Promise<string> {
   // eslint-disable-next-line boundaries/dependencies -- legacy I/O, moves behind a port in #76
   const { createInterface } = await import("node:readline/promises");
@@ -772,23 +819,12 @@ export async function init(
     `      one declaration — the hooks, the rules and the CLI all read this one key`,
   );
   // Every step below uses the DECLARED directory. A kept declaration outranks what init
-  // measured or guessed: otherwise the first paper, the workflow and rpp.json would land in the
+  // measured or guessed: otherwise the first paper and the workflow would land in the
   // guessed directory while lint and the hooks keep reading the declared one.
   const papersDir =
     decl.status === "kept" ? (decl.papers as string) : choice.papers;
-  const rpp = syncRppJson(root, papersDir);
-  if (rpp === "filled")
-    log(
-      `  ⚠ rpp.json was already here — gave it the same ${PAPERS_DIR_FIELD} value; it is deprecated`,
-    );
-  else if (rpp === "kept")
-    log(
-      `  ⚠ rpp.json was already here and already declares ${PAPERS_DIR_FIELD} — left untouched; it is deprecated`,
-    );
-  else if (rpp === "unparsable")
-    log(
-      `  ⚠ rpp.json is here and does not parse — left untouched; it is deprecated, delete it`,
-    );
+  const moved = migratePaperSettings(resolve(root, papersDir));
+  for (const line of moved.lines) (moved.code ? err : log)(line);
 
   // ── 3. the skills, linked where Claude Code looks for them ─────────────────────────────
   for (const line of reportSkillLinks(link(root), here)) log(line);
@@ -896,5 +932,5 @@ export async function init(
       `doctor exits ${String(code)} — the install is NOT finished. The lines marked ✗ above say what is\n` +
         `left; re-run \`npx paperlint doctor\` once you have done them.`,
     );
-  return paperCode !== 0 ? paperCode : code;
+  return paperCode || moved.code || code;
 }

package/src/latex-log.harness.mjs

@@ -112,7 +112,7 @@ const undefinedCs = [
   "Here is how much of TeX's memory you used:",
 ];
 const ex = errorExcerpt(undefinedCs);
-// Guards: the spelling rpp's own flags produce for most errors — with only the `!` form recognised,
+// Guards: the spelling paperlint's own flags produce for most errors — with only the `!` form recognised,
 // an undefined control sequence fails with no error line quoted.
 check(
   "-file-line-error form: the error line, the l.NNN line and the rest of the source line",

package/src/link-skills.harness.mjs

@@ -50,7 +50,9 @@ const check = (label, cond) => {
 };
 
 const SKILLS = ["alpha", "beta", "gamma"];
-const work = realpathSync(mkdtempSync(join(tmpdir(), "rpp-link-skills-")));
+const work = realpathSync(
+  mkdtempSync(join(tmpdir(), "paperlint-link-skills-")),
+);
 
 /** A package as a manager would unpack it: manifest, skills, one non-skill. */
 function writePackage(dir) {

package/src/link-skills.mutations.mjs

@@ -27,7 +27,7 @@ process.exit(
     runner: "node",
     cases: [
       {
-        // The definition lives in the port since rpp#62 (`installedSkills` in consumer.mjs), so
+        // The definition lives in the port since paperlint#62 (`installedSkills` in consumer.mjs), so
         // the defect is planted THERE and must still die in THIS harness — the evidence that the
         // linker reads it through the shared function rather than through a copy of its own.
         name: "any directory counts as a skill",

package/src/link-skills.ts

@@ -66,7 +66,7 @@ export function locatePackage(project: string): Located {
   let manifest: string;
   try {
     const req = createRequire(
-      pathToFileURL(join(project, "__rpp_locate__.js")).href,
+      pathToFileURL(join(project, "__paperlint_locate__.js")).href,
     );
     manifest = req.resolve(`${PACKAGE_NAME}/package.json`);
   } catch (e) {
@@ -100,7 +100,7 @@ export function shippedSkills(
   // clean run.
   if (!existsSync(skillsDir))
     return { error: `the package's skills directory is missing: ${skillsDir}` };
-  // The same function every reader of an installed skills directory calls (rpp#62): the writer
+  // The same function every reader of an installed skills directory calls (paperlint#62): the writer
   // and the readers of this fact share one definition of "a skill is here", links included.
   try {
     return { skillsDir, names: installedSkills(skillsDir) };

package/src/new-paper.harness.mjs

@@ -52,7 +52,7 @@ const check = (label, cond) => {
   assert.ok(cond, label);
 };
 
-const work = realpathSync(mkdtempSync(join(tmpdir(), "rpp-new-")));
+const work = realpathSync(mkdtempSync(join(tmpdir(), "paperlint-new-")));
 const read = (...p) => readFileSync(join(...p), "utf8");
 const front = (text) => load(frontmatterBlock(text) ?? "") ?? {};
 
@@ -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,145 @@
+/**
+ * `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",
+    });
+  });
+
+  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", () => {
+  async function lintNew(extendsValue: string | null) {
+    const root = tmp();
+    writeFileSync(
+      join(root, "package.json"),
+      JSON.stringify({
+        name: "c",
+        private: true,
+        paperlint: { papersDir: "papers" },
+      }),
+    );
+    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/,
+    );
+  });
+});