paperlint 2.0.0 → 2.1.0

package/src/doctor.ts

@@ -37,9 +37,11 @@ import {
 import {
   LEGACY_CONFIG_KEY,
   LEGACY_KEY_MESSAGE,
+  LEGACY_PAPER_SETTINGS_FILE,
+  PAPER_SETTINGS_FILE,
   declaredSettings,
 } from "../lib/paper-config.mjs";
-import { PAPER_MARKERS } from "./build.ts";
+import { PAPER_MARKERS, papersIn } from "./build.ts";
 import { linkSkills, SKILLS_HOME, type LinkReport } from "./link-skills.ts";
 import { doctorHooks } from "./hooks-settings.ts";
 
@@ -233,6 +235,28 @@ function papersVerdict(
   return { lines: out, bad };
 }
 
+/**
+ * A pre-2.1.0 `venue.json` left in a paper: it is no longer read, so that paper's venue checks
+ * silently would not run if nothing named it. `init` moves it.
+ */
+function leftoverSettingsVerdict(
+  root: string,
+  papersDir: string | null,
+): { lines: string[]; bad: number } {
+  if (papersDir === null) return { lines: [], bad: 0 };
+  const lines = papersIn(resolve(root, papersDir), [
+    ...PAPER_MARKERS,
+    LEGACY_PAPER_SETTINGS_FILE,
+  ])
+    .map((dir) => join(dir, LEGACY_PAPER_SETTINGS_FILE))
+    .filter((f) => existsSync(f))
+    .map(
+      (f) =>
+        `  ✗ ${relative(root, f)} is no longer read — paperlint 2.1.0 renamed it ${PAPER_SETTINGS_FILE}, so this paper's venue checks do not run. \`npx paperlint init\` moves it`,
+    );
+  return { lines, bad: lines.length };
+}
+
 export interface DoctorOptions {
   log?: typeof console.log;
   cwd?: string;
@@ -282,8 +306,6 @@ export function doctor({
     out.push(...declaration.lines);
     bad += declaration.bad;
   }
-  if (existsSync(join(root, "rpp.json")))
-    out.push(`  ⚠ rpp.json is present — deprecated; the hooks never read it`);
 
   out.push("", "papers directory");
   const hookRoot = rawPkg ? papersRoot(rawPkg) : null;
@@ -295,8 +317,9 @@ export function doctor({
     `  the hooks will guard ${hookSays ?? "(nothing — the guard refuses and says why on first use)"}`,
   );
   const verdict = papersVerdict(root, cliPapers, hookSays);
-  out.push(...verdict.lines);
-  bad += verdict.bad;
+  const leftover = leftoverSettingsVerdict(root, cliPapers ?? hookSays);
+  out.push(...verdict.lines, ...leftover.lines);
+  bad += verdict.bad + leftover.bad;
 
   // A skill that is not linked is ADVISORY, like a missing program: `paperlint lint`, the hooks and CI
   // work without it, and an entry of the same name that `init` refused to replace is the

package/src/engine.harness.mjs

@@ -53,7 +53,7 @@ const facts = (o) => ({
   ...o,
 });
 const ROWS = [
-  // Guards: the order — rpp's own verified cache first, so a build does not depend on whatever TeX
+  // Guards: the order — paperlint's own verified cache first, so a build does not depend on whatever TeX
   // Live the machine happens to carry.
   [
     "a complete cache wins, even over a complete system TeX",
@@ -198,7 +198,9 @@ check(
 // to start, while `paperlint toolchain --check` reported the tree verified. Checked on disk, not
 // through an injected predicate, because the predicate is exactly what was wrong.
 {
-  const bin = realpathSync(mkdtempSync(join(tmpdir(), "rpp-engine-bin-")));
+  const bin = realpathSync(
+    mkdtempSync(join(tmpdir(), "paperlint-engine-bin-")),
+  );
   try {
     mkdirSync(join(bin, "texcount"));
     writeFileSync(join(bin, "checkcites"), "#!/bin/sh\n");

package/src/engine.ts

@@ -8,7 +8,7 @@
  * TeX Live qualifies only when `kpsewhich` finds every file the venue declares (issue #26).
  *
  * The order (the Playwright pattern, decided 2026-09-24):
- *   1. rpp's own cache (`paperlint toolchain` installs it) — when it has everything;
+ *   1. paperlint's own cache (`paperlint toolchain` installs it) — when it has everything;
  *   2. a TeX Live already on PATH — when IT has everything;
  *   3. neither: on a terminal, ask once and install; without one (CI, an agent), refuse in one line
  *      that names `npx paperlint toolchain` and the missing packages. Never a silent install without a
@@ -41,7 +41,7 @@ export interface TreeProbe {
 export interface EngineFacts {
   /** install-tl-unx runs here (Linux, macOS). */
   readonly supported: boolean;
-  /** rpp's cached TeX Live, probed — or null when there is none. */
+  /** paperlint's cached TeX Live, probed — or null when there is none. */
   readonly cache: TreeProbe | null;
   /** The `pdflatex` on PATH, probed — or null when there is none. */
   readonly system: TreeProbe | null;

package/src/facts-file.test.ts

@@ -8,6 +8,9 @@
  * real banal is `test/e2e/banal.mjs`.
  */
 import assert from "node:assert/strict";
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { packageVenuesDir } from "../skills/paper-pipeline/scripts/consumer.mjs";
 import { test } from "vitest";
 import { memoryFiles } from "./adapters/memory/index.ts";
 import {
@@ -147,12 +150,23 @@ const good: PdfReader = async () => ({
   ok: true,
   facts: { pages: 2, fonts: FONTS, last: lastPage(60, 60), layout: [] },
 });
-/** Options over in-memory files: the PDF and venue.json on "disk", a measurer answering `geometry`. */
+/** The shipped presets at their real paths: `extends` resolves through the same Files port. */
+const SHIPPED_PRESETS = Object.fromEntries(
+  readdirSync(packageVenuesDir())
+    .filter((f) => /\.jsonc?$/.test(f))
+    .map((f) => [
+      join(packageVenuesDir(), f),
+      readFileSync(join(packageVenuesDir(), f)),
+    ]),
+);
+
+/** Options over in-memory files: the PDF and paperlint.json on "disk", a measurer answering `geometry`. */
 function setup(geometry: Geometry = NONE) {
   const files = memoryFiles({
     [PDF]: PDF_BYTES,
-    [`${PAPER}/venue.json`]: JSON.stringify({
-      venue: "agenticdev",
+    ...SHIPPED_PRESETS,
+    [`${PAPER}/paperlint.json`]: JSON.stringify({
+      extends: "paperlint:agenticdev",
       kind: "short",
     }),
   });
@@ -170,7 +184,7 @@ function setup(geometry: Geometry = NONE) {
   return { files, measured, o };
 }
 
-test("measure: venue and kind from venue.json, pdf relative to the paper, the file's sha256", async () => {
+test("measure: venue and kind from paperlint.json, pdf relative to the paper, the file's sha256", async () => {
   const { o } = setup();
   const m = await measurePaper(PAPER, PDF, o);
   assert.ok(m.ok);
@@ -233,8 +247,41 @@ test("writeFactsFile: <paper>/_build/paper.facts.json holds exactly the document
   assert.deepEqual(JSON.parse(text), m.value.facts);
 });
 
-test("declaredVenue: none without venue.json, none when it names no venue", () => {
+test("declaredVenue: none without paperlint.json; no label when it extends no preset", () => {
   assert.equal(declaredVenue(memoryFiles(), PAPER), null);
-  const files = memoryFiles({ [`${PAPER}/venue.json`]: '{"kind":"x"}' });
-  assert.equal(declaredVenue(files, PAPER), null);
+  const files = memoryFiles({
+    [`${PAPER}/paperlint.json`]: '{"kind":"x","pdf":"b/p.pdf"}',
+  });
+  assert.deepEqual(declaredVenue(files, PAPER), {
+    label: null,
+    kind: "x",
+    pdf: "b/p.pdf",
+  });
+});
+
+test("declaredVenue: the label is the preset's, and an extends that resolves nowhere is refused", () => {
+  const ok = memoryFiles({
+    ...SHIPPED_PRESETS,
+    [`${PAPER}/paperlint.json`]: '{"extends":"paperlint:aisec"}',
+  });
+  assert.equal(declaredVenue(ok, PAPER)?.label, "aisec");
+  const typo = memoryFiles({
+    ...SHIPPED_PRESETS,
+    [`${PAPER}/paperlint.json`]: '{"extends":"paperlint:aisek"}',
+  });
+  assert.throws(() => declaredVenue(typo, PAPER), /shipped presets/);
+});
+
+test("declaredVenue: a venue.json alone is refused with the command that moves it, not read", () => {
+  const files = memoryFiles({
+    [`${PAPER}/venue.json`]: '{"venue":"agenticdev"}',
+  });
+  assert.throws(() => declaredVenue(files, PAPER), /npx paperlint init/);
+});
+
+test("declaredVenue: a paperlint.json with an unknown key is refused, naming the key", () => {
+  const files = memoryFiles({
+    [`${PAPER}/paperlint.json`]: '{"venu":"agenticdev"}',
+  });
+  assert.throws(() => declaredVenue(files, PAPER), /unknown key "venu"/);
 });

package/src/facts-file.ts

@@ -40,13 +40,16 @@ import { describeFailure, type PdfFacts, type PdfReader } from "./pdf-facts.ts";
 import {
   flatGeometry,
   type FactsGeometryFields,
+  type FlatGeometry,
   type Geometry,
 } from "./domain/geometry.ts";
-import { sha256Hex } from "./domain/sha256.ts";
+import { parseSha256, sha256Hex, type Sha256 } from "./domain/sha256.ts";
 import type { MeasureGeometry } from "./ports/measure-geometry.ts";
 import type { AbsolutePath } from "./domain/paths.ts";
 import type { Files } from "./ports/files.ts";
 import { err, ok, type Result } from "./domain/result.ts";
+import { paperPreset, paperPresetProblem } from "./presets.ts";
+import { packageVenuesDir } from "../skills/paper-pipeline/scripts/consumer.mjs";
 
 export const FACTS_SCHEMA = 2;
 export const FACTS_DIR = "_build";
@@ -56,41 +59,42 @@ export const FACTS_FILE = "paper.facts.json";
 export const factsPath = (paperDir: string): string =>
   join(paperDir, FACTS_DIR, FACTS_FILE);
 
-/** The `venue.json` a paper declares: where it is submitted, as which kind, and where its PDF is. */
-export interface VenueDecl {
-  readonly venue: string;
-  readonly kind: string | null;
-  readonly pdf: string | null;
-}
-
 /**
  * A path as the caller gave it. The `Files` adapter resolves a relative one against the process's
  * cwd, which is what these callers have always meant; the brand is not a claim this code checked it.
  */
 const at = (p: string): AbsolutePath => p as AbsolutePath;
 
-const str = (v: unknown): string | null => (typeof v === "string" ? v : null);
-
-/** A parsed `venue.json`, or null when it names no venue. */
-export function parseVenueDecl(json: unknown): VenueDecl | null {
-  const d = typeof json === "object" && json !== null ? json : {};
-  const field = (k: string) => str((d as Record<string, unknown>)[k]);
-  const venue = field("venue");
-  return venue ? { venue, kind: field("kind"), pdf: field("pdf") } : null;
+/** What the facts need from a paper's `paperlint.json`: its venue's label, its kind, where its PDF is. */
+export interface VenueDecl {
+  /** The venue preset's display label (`agenticdev`), or null when the paper extends none. */
+  readonly label: string | null;
+  readonly kind: string | null;
+  readonly pdf: string | null;
 }
 
 /**
- * The paper's `venue.json`, or null when there is none or it names no venue. The one reader of
- * that file: the build, the facts writer and the shim all read it here.
+ * What a paper's `paperlint.json` declares, or null when it has none. THROWS with a one-line reason
+ * when the file does not parse, its `extends` does not resolve, or only the pre-2.1.0 `venue.json`
+ * is there: the build reports that as its `facts` failure rather than building against no venue.
  */
 export function declaredVenue(
   files: Files,
   paperDir: string,
+  venuesDir: string = packageVenuesDir(),
 ): VenueDecl | null {
-  const bytes = files.readBytes(at(join(paperDir, "venue.json")));
-  return bytes === null
-    ? null
-    : parseVenueDecl(JSON.parse(new TextDecoder().decode(bytes)));
+  const p = paperPreset(paperDir, { files, venuesDir });
+  const problem = paperPresetProblem(paperDir, p);
+  if (problem !== null) throw new Error(problem);
+  if (p.kind === "resolved")
+    return {
+      label: p.preset.label,
+      kind: p.settings.kind,
+      pdf: p.settings.pdf,
+    };
+  return p.kind === "none" && p.settings
+    ? { label: null, kind: p.settings.kind, pdf: p.settings.pdf }
+    : null;
 }
 
 // ── the document ────────────────────────────────────────────────────────────────────────
@@ -184,7 +188,7 @@ export interface MeasureOptions {
   readonly kind?: string | null;
   /** The page-geometry measurer (banal, as the composition root wired it). */
   readonly measure: MeasureGeometry;
-  /** Where the PDF and `venue.json` are read from. */
+  /** Where the PDF and `paperlint.json` are read from. */
   readonly files: Files;
 }
 
@@ -215,7 +219,7 @@ export async function measurePaper(
   const facts = factsDocument({
     pdf: posix(relative(paperDir, pdf)),
     sha: sha256Hex(bytes),
-    venue: o.venue ?? decl?.venue ?? null,
+    venue: o.venue ?? decl?.label ?? null,
     kind: o.kind ?? decl?.kind ?? null,
     read: r.facts,
     geometry,
@@ -239,3 +243,120 @@ export function writeFactsFile(
   );
   return out;
 }
+
+// ── reading ─────────────────────────────────────────────────────────────────────────────
+
+/** What a rule judges, read back from the facts file and typed once. */
+export interface ReadFacts {
+  /** As the file spells it: relative to the paper directory, or absolute. */
+  readonly pdf: string;
+  readonly sha: Sha256;
+  readonly fonts: readonly FontEntry[];
+  /** The geometry columns, or null when no measurer ran (`geometry_source` is null). */
+  readonly geometry: FlatGeometry | null;
+}
+
+/** Why a facts file cannot be judged. */
+export type FactsProblem =
+  | { readonly kind: "schema"; readonly got: string }
+  | { readonly kind: "broken"; readonly why: string };
+
+const isRecord = (v: unknown): v is Readonly<Record<string, unknown>> =>
+  typeof v === "object" && v !== null && !Array.isArray(v);
+const isNum = (v: unknown): v is number =>
+  typeof v === "number" && Number.isFinite(v);
+const numOrNull = (v: unknown): v is number | null => v === null || isNum(v);
+
+function fontOf(v: unknown): FontEntry | null {
+  if (!isRecord(v)) return null;
+  const { name, type, embedded, program } = v;
+  return typeof name === "string" &&
+    typeof type === "string" &&
+    typeof embedded === "boolean" &&
+    typeof program === "string"
+    ? { name, type, embedded, program }
+    : null;
+}
+
+const MAYBE_NUMBERS = [
+  "page_w_in",
+  "page_h_in",
+  "columns",
+  "body_pt",
+  "ref_pt",
+] as const;
+const NUMBERS = ["body_pages", "ref_pages", "appendix_pages"] as const;
+
+/** The geometry columns when a measurer ran; the shape error otherwise. */
+function geometryOf(
+  d: Readonly<Record<string, unknown>>,
+): Result<FlatGeometry | null, string> {
+  if (d["geometry_source"] === null) return ok(null);
+  if (typeof d["geometry_source"] !== "string")
+    return err("`geometry_source` is neither a measurer's name nor null");
+  const bad =
+    MAYBE_NUMBERS.find((k) => !numOrNull(d[k])) ??
+    NUMBERS.find((k) => !isNum(d[k]));
+  if (bad) return err(`\`${bad}\` is not a number`);
+  const pagesByType = d["pages_by_type"];
+  if (!isRecord(pagesByType) || !Object.values(pagesByType).every(isNum))
+    return err("`pages_by_type` is not an object of page counts");
+  const n = (k: (typeof MAYBE_NUMBERS)[number]) => d[k] as number | null;
+  return ok({
+    page_w_in: n("page_w_in"),
+    page_h_in: n("page_h_in"),
+    columns: n("columns"),
+    body_pt: n("body_pt"),
+    ref_pt: n("ref_pt"),
+    body_pages: d["body_pages"] as number,
+    ref_pages: d["ref_pages"] as number,
+    appendix_pages: d["appendix_pages"] as number,
+    pages_by_type: pagesByType as Readonly<Record<string, number>>,
+  });
+}
+
+/** The PDF the facts describe: its path and its sha256. */
+function artifactOf(
+  d: Readonly<Record<string, unknown>>,
+): Result<{ pdf: string; sha: Sha256 }, string> {
+  const pdf = d["pdf"];
+  if (typeof pdf !== "string" || pdf === "") return err("no `pdf` path");
+  try {
+    return ok({ pdf, sha: parseSha256(String(d["pdf_sha256"])) });
+  } catch {
+    return err("no `pdf_sha256` of 64 hex digits");
+  }
+}
+
+/**
+ * The facts file's text → what a rule judges, or why it cannot be judged. The one reader of the
+ * file in `src/`, beside its one writer: a field renamed here and not there is a compile error in
+ * this module, not a rule that silently reads `undefined`. Pure.
+ */
+export function parseFactsText(text: string): Result<ReadFacts, FactsProblem> {
+  let d: unknown;
+  try {
+    d = JSON.parse(text);
+  } catch (e) {
+    return err({ kind: "broken", why: `not JSON (${(e as Error).message})` });
+  }
+  if (!isRecord(d)) return err({ kind: "broken", why: "not a JSON object" });
+  if (d["schema"] !== FACTS_SCHEMA)
+    return err({ kind: "schema", got: JSON.stringify(d["schema"] ?? null) });
+  const artifact = artifactOf(d);
+  if (!artifact.ok) return err({ kind: "broken", why: artifact.error });
+  const rawFonts = d["fonts"];
+  const fonts = Array.isArray(rawFonts) ? rawFonts.map(fontOf) : null;
+  if (fonts === null || fonts.some((f) => f === null))
+    return err({
+      kind: "broken",
+      why: "`fonts` is not a list of { name, type, embedded, program }",
+    });
+  const geometry = geometryOf(d);
+  if (!geometry.ok) return err({ kind: "broken", why: geometry.error });
+  return ok({
+    ...artifact.value,
+    fonts: fonts as FontEntry[],
+    geometry: geometry.value,
+  });
+}

package/src/hooks-settings.harness.mjs

@@ -40,7 +40,6 @@ const {
   doctorHooks,
   readSettings,
   MANAGED_BY,
-  LEGACY_MANAGED_BY,
   SETTINGS_PATH,
 } = await import(join(HERE, "hooks-settings.ts"));
 const { claudeCodeHookProtocol } = await import("vigiles/claude-code");
@@ -66,7 +65,7 @@ check(
   wiring.names.join() ===
     "paper-edit-guard,paper-skills-nudge,paper-status-gates",
 );
-const work = realpathSync(mkdtempSync(join(tmpdir(), "rpp-hooks-")));
+const work = realpathSync(mkdtempSync(join(tmpdir(), "paperlint-hooks-")));
 try {
   const empty = join(work, "empty-hooks.json");
   writeFileSync(empty, '{"hooks":{}}');
@@ -89,11 +88,16 @@ try {
       `node "$CLAUDE_PROJECT_DIR/${MANAGED_BY}" hook paper-status-gates`,
       { name: "paper-status-gates", ours: true, legacy: false },
     ],
-    // Guards: what an install under the old package name wrote is recognised as ours-but-stale.
+    // Guards: what an older install wrote is recognised as ours-but-stale. Spelled literally, not
+    // built from a constant: these are what 1.x and 2.0.0 actually put in users' settings files.
     [
-      `node "$CLAUDE_PROJECT_DIR/${LEGACY_MANAGED_BY}" hook paper-edit-guard`,
+      `node "$CLAUDE_PROJECT_DIR/node_modules/research-paper-pipeline/bin/rpp.mjs" hook paper-edit-guard`,
       { name: "paper-edit-guard", ours: false, legacy: true },
     ],
+    [
+      `node "\${CLAUDE_PROJECT_DIR}/node_modules/paperlint/bin/rpp.mjs" hook paper-status-gates`,
+      { name: "paper-status-gates", ours: false, legacy: true },
+    ],
     [
       `node "$CLAUDE_PROJECT_DIR/node_modules/vigiles/dist/cli.js" hook-runtime run-program "$CLAUDE_PROJECT_DIR/node_modules/paperlint/hooks/paper-edit-guard.hook.mjs"`,
       { name: "paper-edit-guard", ours: false, legacy: false },
@@ -107,11 +111,11 @@ try {
       { name: "paper-skills-nudge", ours: false, legacy: false },
     ],
     [
-      `node /abs/proj/node_modules/paperlint/bin/rpp.mjs hook paper-edit-guard`,
+      `node /abs/proj/node_modules/paperlint/bin/paperlint.mjs hook paper-edit-guard`,
       { name: "paper-edit-guard", ours: false, legacy: false },
     ],
     [`node my-own-lint.mjs`, null],
-    [`node node_modules/paperlint/bin/rpp.mjs lint`, null],
+    [`node node_modules/paperlint/bin/paperlint.mjs lint`, null],
   ];
   for (const [cmd, want] of cases)
     check(
@@ -154,37 +158,42 @@ try {
     );
   }
 
-  // ── an install under the old package name is migrated, the user's own command kept ─────
-  {
+  // ── what an older install wrote is migrated, the user's own command kept ─────────────────
+  // Two real histories, spelled literally: 1.x wrote the old package directory, 2.0.0 wrote the
+  // new directory with the old entry file name. Neither file exists after an upgrade.
+  for (const [release, stale] of [
+    ["1.x", "node_modules/research-paper-pipeline/bin/rpp.mjs"],
+    ["2.0.0", "node_modules/paperlint/bin/rpp.mjs"],
+  ]) {
     const legacyWired = JSON.parse(
       JSON.stringify(merge({}, wiring.compiled, MANAGED_BY)).replaceAll(
         MANAGED_BY,
-        LEGACY_MANAGED_BY,
+        stale,
       ),
     );
     legacyWired.hooks.PostToolUse[0].hooks.push({
       type: "command",
       command: "node my-own-lint.mjs",
     });
-    const dir = project("legacy", legacyWired);
+    const dir = project(`legacy-${release}`, legacyWired);
     const before = doctorHooks(dir, wiring).join("\n");
     check(
-      "🔴 doctor names hook commands left under the old package name, and the fix",
-      /still point into node_modules\/research-paper-pipeline\//.test(before) &&
+      `🔴 doctor names hook commands ${release} left behind — the missing file, and the fix`,
+      before.includes(`run ${stale}, which this version does not install`) &&
         /npx paperlint init` replaces them/.test(before),
     );
     const r = wireHooks(dir, merge, wiring);
     const s = JSON.parse(text(dir));
     const counts = [...wiredCounts(s, wiring.names).values()];
     check(
-      "🔴 init replaces them: every hook wired once under the new name, none left under the old",
+      `🔴 init replaces what ${release} wrote: every hook wired once, none left at the old path`,
       r.status === "written" &&
         r.replaced === wiring.names.length &&
         counts.every((c) => c.ours === 1 && c.legacy === 0 && c.other === 0) &&
-        !text(dir).includes("research-paper-pipeline"),
+        !text(dir).includes(stale),
     );
     check(
-      "and the user's own command in the same matcher survives the migration",
+      `and the user's own command in the same matcher survives the ${release} migration`,
       text(dir).includes("node my-own-lint.mjs"),
     );
   }

package/src/hooks-settings.mutations.mjs

@@ -27,11 +27,9 @@ process.exit(
         expect: '→ {"name":"paper-edit-guard","ours":false,"legacy":true}',
         disables:
           "the duplicate guard for every bin spelling but ours. A hook wired by hand as " +
-          "`npx paperlint hook …` or through an absolute rpp.mjs path reads as ours, init merges its own " +
+          "`npx paperlint hook …` or through an absolute path to the bin reads as ours, init merges its own " +
           "copy beside it, and the hook runs twice per event",
-        edits: [
-          [SRC, "        ours: t === MANAGED_BY,", "        ours: true,"],
-        ],
+        edits: [[SRC, "      ours: t === MANAGED_BY,", "      ours: true,"]],
       },
       {
         name: "another spelling no longer stops the write",