paperlint 2.0.0 → 2.1.0

package/src/cli.ts

@@ -10,13 +10,13 @@
  *
  * Two entry points into the tool, and both are whole now:
  *     npx paperlint lint              ← here
- *     uses: zernie/research-paper-pipeline@<sha>    ← action.yml
+ *     uses: zernie/paperlint@<sha>    ← action.yml
  *
  * ⚠️ THE BOUNDARY THIS UTILITY HAS NO RIGHT TO ERASE: the consumer's data stays with the consumer.
  * The typography debt, the marker of the author-list check run, the field dictionary — all of that
  * is about ONE corpus, and wiring it into the package would repeat the defect that put the path
  * `.claude/skills/verify-citations/...` into a rule's message. So they live in the consumer's
- * `rpp.json`.
+ * `package.json`, under the `paperlint` key.
  *
  * 🔴 WHY THE COMMAND IS CALLED `lint` AND NOT `check`. It does exactly what everyone else calls by
  * that word: reads files, changes nothing, prints findings, exits non-zero. `check` is taken in the
@@ -33,30 +33,34 @@ import { fileURLToPath } from "node:url";
 import { join, dirname, resolve, relative, basename, sep } from "node:path";
 import markdown from "@eslint/markdown";
 // Types come from consumer.d.mts beside it, the same arrangement as lib/paper-config.d.mts.
-import { isMain } from "../skills/paper-pipeline/scripts/consumer.mjs";
+import {
+  isMain,
+  packageVenuesDir,
+} from "../skills/paper-pipeline/scripts/consumer.mjs";
 export { isMain };
-import type { Args, RppConfig, ConfigRead } from "./types.ts";
+import type { Args, PaperlintConfig, ConfigRead } from "./types.ts";
 import {
   checkStructure,
   formatStructure,
   asEslintResults,
 } from "./structure.ts";
-import {
-  buildPapers,
-  papersIn,
-  anyFailed,
-  remedyFor,
-  readFacts,
-  MAIN,
-} from "./build.ts";
+import { buildPapers, papersIn, anyFailed, remedyFor, MAIN } from "./build.ts";
 import { prepareEngine } from "./build-engine.ts";
 import { runToolchain } from "./toolchain.ts";
 import { banalInstaller, parseBanalSettings } from "./adapters/banal/index.ts";
 import { curlDownload } from "./adapters/curl/index.ts";
-import { hostDirs, nodeAdapters } from "./adapters/node/index.ts";
+import { hostDirs, nodeAdapters, nodeFiles } from "./adapters/node/index.ts";
+import { VENUE_RULE_LEVELS, venueRules } from "./venue-rules.ts";
+import { paperRules } from "./paper-settings.ts";
+import {
+  paperPreset,
+  paperPresetProblem,
+  type PaperPreset,
+} from "./presets.ts";
 import type { ToolInstaller } from "./ports/tool-installer.ts";
 import {
   mergeRequirements,
+  declaredUnion,
   requirementsFor,
   NO_REQUIREMENTS,
   type TexRequirements,
@@ -84,9 +88,11 @@ import {
 } from "../lib/paper-config.mjs";
 import {
   parseRuleBlocks,
+  parseRuleEntries,
   shippedRuleIds,
   unknownKeys,
   type Parsed,
+  type RuleBlock,
 } from "./rules-config.ts";
 export { init };
 export { nextSteps } from "./init.ts";
@@ -122,8 +128,8 @@ const USAGE = `paperlint — machine-checkable gates for a paper kept in git
                                       Compiles with paperlint's TeX Live, else one on PATH that has every
                                       package the venue declares; on a terminal it offers to install
                                       one, without a terminal it stops and names \`npx paperlint toolchain\`
-  npx paperlint toolchain [--check]   install TeX Live with every package the venue profiles declare
-                                      into ~/.cache/rpp/texlive (RPP_TEXLIVE_DIR overrides); a second
+  npx paperlint toolchain [--check]   install TeX Live with every package the venue presets declare
+                                      into ~/.cache/paperlint/texlive (PAPERLINT_TEXLIVE_DIR overrides); a second
                                       run does nothing. --check: report what is missing, change nothing
   npx paperlint doctor                say what is actually wired — and what only LOOKS wired
   npx paperlint hook <name>           run an editor hook (.claude/settings.json calls this)
@@ -149,8 +155,8 @@ lint:
                       most findings here are advisory and a gate that fails on advice gets muted
 
 settings — the \`paperlint\` key of your package.json, found by walking up from the
-current directory, the way every other tool in the stack finds its config. \`rpp.json\` is still
-read as a deprecated fallback and the run says so. \`papersDir\` is required; the rest is optional:
+current directory, the way every other tool in the stack finds its config. \`--config\` names
+another file of the same shape. \`papersDir\` is required; the rest is optional:
 
   "paperlint": {
     "papersDir":         "papers",
@@ -164,14 +170,26 @@ read as a deprecated fallback and the run says so. \`papersDir\` is required; th
                  "rules": { "pdf/last-page-balance": "error" } } ]
   }
 
-  "rules" takes ESLint flat-config blocks (files, ignores, rules), appended after rpp's own, with
+  "rules" takes ESLint flat-config blocks (files, ignores, rules), appended after paperlint's own, with
   files relative to the file holding the settings. Optional rules (off unless turned on there):
-  pdf/last-page-balance. An unknown key, anywhere in the settings, is an error.
+  pdf/last-page-balance. The venue rules (pdf/fresh, pdf/profile, pdf/fonts, pdf/geometry,
+  pdf/limits, pdf/body-size, pdf/measured) are on for every paper whose paperlint.json names a venue;
+  set one to "off" there to skip it.
+
+per paper — <paper>/paperlint.json (it was venue.json before 2.1.0; \`npx paperlint init\` moves it):
+
+  { "extends": "paperlint:aisec", "kind": "research", "rules": { "pdf/last-page-balance": "error" } }
+
+  "extends" names a venue preset: paperlint:<name> (shipped: acm-sigconf, agenticdev, aisec, realm)
+  or ./path.jsonc, relative to the paperlint.json. npm presets are not supported yet.
+
+  "rules" there applies to that paper alone, after its preset's rules and before the project's. An unknown key,
+  anywhere in the settings or in a paperlint.json, is an error.
 `;
 
 /** The config the user would otherwise write by hand. The data comes from `opts`, the mechanism is here. */
 export function buildConfig(
-  opts: RppConfig = {},
+  opts: PaperlintConfig = {},
   texLanguage: unknown,
 ): unknown[] {
   const paperRules = { ...researchQuestion.rules, ...typography.rules };
@@ -188,11 +206,21 @@ export function buildConfig(
     // default (only `node_modules/` and `.git/`), so without this block `paperlint lint` would lint the
     // template as a paper — and a richer template with placeholder stages would fail the run.
     { ignores: ["**/.template/"] },
-    // The `pdf` plugin is registered for EVERY file, and its rule is on for none. A consumer's
-    // block (`rules`, appended below) turns it on for a glob that also matches markdown files;
-    // with the plugin defined only beside `paper.tex`, ESLint would refuse those files with
-    // "could not find plugin". The rule itself acts on `paper.tex` only.
-    { plugins: { pdf: pdfRules } },
+    // The `pdf` plugin is registered for EVERY file. A consumer's block (`rules`, appended below)
+    // may name its rules for a glob that also matches markdown files; with the plugin defined only
+    // beside `paper.tex`, ESLint would refuse those files with "could not find plugin". Every rule
+    // in it acts on `paper.tex` only. `last-page-balance` is on for no file (optional); the venue
+    // rules are on for every `paper.tex`, in the block below.
+    {
+      plugins: {
+        pdf: {
+          rules: {
+            ...pdfRules.rules,
+            ...venueRules({ files: nodeFiles, venuesDir: packageVenuesDir() }),
+          },
+        },
+      },
+    },
     {
       files: ["**/PIPELINE-STATUS.md"],
       plugins: { markdown, paper: paperStages },
@@ -263,6 +291,8 @@ export function buildConfig(
         "paper/typography": typographyOpt,
         "tex/future-promise": "warn",
         "tex/acm-frontmatter-override": "error",
+        // Silent for a paper whose paperlint.json names no venue (src/venue-rules.ts).
+        ...VENUE_RULE_LEVELS,
       },
     });
   // The consumer's own blocks, LAST, so a later block wins — ESLint's rule. Parsed by
@@ -272,8 +302,8 @@ export function buildConfig(
 }
 
 /**
- * The rule ids a consumer may name in `rules`: every rule rpp's own config defines, read off that
- * config rather than listed again. `@eslint/markdown` is a dependency's plugin, not rpp's.
+ * The rule ids a consumer may name in `rules`: every rule paperlint's own config defines, read off that
+ * config rather than listed again. `@eslint/markdown` is a dependency's plugin, not paperlint's.
  */
 export const SHIPPED_RULES: ReadonlySet<string> = shippedRuleIds(
   buildConfig({}, { sentinel: "tex language" }),
@@ -288,7 +318,7 @@ const isOn = (entry: unknown): boolean => {
 
 /**
  * Rules paperlint ships and turns on for no file itself — the ones a consumer opts into with `rules`.
- * Derived: every shipped rule that no block of rpp's own config names.
+ * Derived: every shipped rule that no block of paperlint's own config names.
  */
 export const OPTIONAL_RULES: ReadonlySet<string> = new Set(
   [...SHIPPED_RULES].filter(
@@ -309,7 +339,7 @@ export const OPTIONAL_RULES: ReadonlySet<string> = new Set(
 export async function silentOptionalRules(
   eslint: ESLint,
   lintedFiles: readonly string[],
-  opts: RppConfig,
+  opts: PaperlintConfig,
 ): Promise<string[]> {
   const turnedOn = new Set(
     (opts.rules ?? []).flatMap((b) =>
@@ -328,15 +358,75 @@ export async function silentOptionalRules(
   return [...turnedOn].filter((id) => !reached.has(id));
 }
 
+/**
+ * Every linted paper's `rules` from its `paperlint.json`, as ESLint blocks scoped to that paper.
+ * A file that does not parse, or names a rule paperlint does not ship, stops the run with one line
+ * naming the file — the same strictness as the project's own `rules`. A leftover `venue.json` is
+ * not read here; `pdf/profile` and `paperlint doctor` name it.
+ */
+export function paperRuleBlocks(paths: readonly string[]): Parsed<RuleBlock[]> {
+  const papers = [...new Set(paths.flatMap((p) => [p, ...papersIn(p)]))];
+  const out: RuleBlock[] = [];
+  for (const dir of papers) {
+    const p = paperPreset(dir, PRESET_DEPS);
+    if (p.kind === "settings-problem" && p.problem.kind === "broken")
+      return { ok: false, error: paperPresetProblem(dir, p) ?? dir };
+    const block = rulesOfPaper(dir, p);
+    if (!block.ok) return block;
+    if (block.value) out.push(block.value);
+  }
+  return { ok: true, value: out };
+}
+
+/**
+ * One paper's block: its preset chain's `rules`, then its own — later wins per rule id. A preset
+ * that does not resolve contributes nothing here; `pdf/profile` reports it on the paper.
+ */
+function rulesOfPaper(dir: string, p: PaperPreset): Parsed<RuleBlock | null> {
+  const settings = "settings" in p ? p.settings : null;
+  if (settings === null) return { ok: true, value: null };
+  const own = paperRules(dir, settings, SHIPPED_RULES);
+  if (!own.ok) return own;
+  const fromPreset =
+    p.kind === "resolved"
+      ? parseRuleEntries(
+          p.preset.rules,
+          `the venue preset ${p.preset.chain.join(" → ")} → "rules"`,
+          SHIPPED_RULES,
+        )
+      : { ok: true as const, value: {} };
+  if (!fromPreset.ok) return fromPreset;
+  const rules = { ...fromPreset.value, ...(own.value ?? {}) };
+  return {
+    ok: true,
+    value: Object.keys(rules).length
+      ? { basePath: dir, files: PAPER_FILE_PATTERNS, rules }
+      : null,
+  };
+}
+
+/**
+ * The files a paper's block may reach: exactly the ones paperlint's own blocks lint, read off its
+ * config. A wider glob (everything under the paper) would make ESLint lint files no block gives a
+ * language — `paperlint.json` itself would be parsed as JavaScript.
+ */
+const PAPER_FILE_PATTERNS: string[] = [
+  ...new Set(
+    buildConfig({}, { sentinel: "tex language" }).flatMap(
+      (b) => (b as { files?: string[] }).files ?? [],
+    ),
+  ),
+];
+
 /**
  * The settings after the boundary: an unknown key is refused by name, and `rules` becomes parsed
  * config blocks. Nothing after this sees the raw object.
  */
 export function parseSettings(
-  opts: RppConfig,
+  opts: PaperlintConfig,
   where: string,
   baseDir: string,
-): Parsed<RppConfig> {
+): Parsed<PaperlintConfig> {
   const raw = opts as Record<string, unknown>;
   const unknown = unknownKeys(raw);
   if (unknown.length > 0)
@@ -431,7 +521,6 @@ export function parseArgs(argv: readonly string[]): Args {
   return out;
 }
 
-export const CONFIG_NAME = "rpp.json";
 export const PKG_NAME = "package.json";
 
 /**
@@ -450,36 +539,20 @@ function ownVersion(): string | undefined {
   }
 }
 
-/** Where the consumer's settings were found, and in which of the two carriers. */
-export interface Declaration {
-  readonly path: string;
-  readonly kind: "package.json" | "rpp.json";
-}
-
 /**
- * 🔴 THE CLI HAD TO LEARN TO READ `package.json`, AND THAT IS NOT A SIDE ERRAND. `paperlint init` now
- * writes ONE declaration, into the `package.json` key that the three hooks and `eslint-rules`
- * already read. Without this walker the install it produces would not work at all: `paperlint lint`
- * would find no `rpp.json`, report "nothing to lint", and the consumer would be back to
- * declaring the same directory twice — the defect the single declaration removes (issue #33,
+ * 🔴 THE CLI READS `package.json`, THE ONE DECLARATION. `paperlint init` writes the settings under
+ * the `package.json` key that the three hooks and `eslint-rules` already read; the CLI reads the
+ * same file, so the install and the check cannot look at different files (issue #33,
  * `docs/install.md`).
  *
- * `rpp.json` stays readable as a DEPRECATED fallback, and the read says so out loud. Silently
- * dropping a file this command used to write would break working setups on upgrade.
- *
  * The walk goes up to the filesystem root, the way eslint, prettier and tsc find theirs, so a run
- * from inside one paper sees the same settings as a run from the repository root. At each level
- * `package.json` wins over `rpp.json`: it is the carrier every other reader uses, so preferring
- * it is what keeps "one declaration" true rather than merely intended.
+ * from inside one paper sees the same settings as a run from the repository root.
  */
-export function findDeclaration(startDir: string): Declaration | null {
+export function findConfig(startDir: string): string | null {
   let dir = resolve(startDir);
   for (;;) {
     const pkg = join(dir, PKG_NAME);
-    if (existsSync(pkg) && declaresSettings(pkg))
-      return { path: pkg, kind: "package.json" };
-    const rpp = join(dir, CONFIG_NAME);
-    if (existsSync(rpp)) return { path: rpp, kind: "rpp.json" };
+    if (existsSync(pkg) && declaresSettings(pkg)) return pkg;
     const up = dirname(dir);
     if (up === dir) return null;
     dir = up;
@@ -500,11 +573,6 @@ const declaresSettings = (pkgPath: string): boolean => {
   }
 };
 
-/** Kept as the one-line question "which file holds the settings" — callers that only need a path. */
-export function findConfig(startDir: string): string | null {
-  return findDeclaration(startDir)?.path ?? null;
-}
-
 /**
  * Reading the config, ONE reader for all commands. Pulled out of `run()` the moment a second
  * command needed the same config (`build`): two copies of this block would have drifted apart on
@@ -525,24 +593,17 @@ export function readConfig(
   } = {},
 ): ConfigRead {
   // 🔴 THE CONFIG FINDS ITSELF. An explicit `--config` beats the discovered one — it was named out
-  // loud, and a substitution is never silent. For an explicit path the FILE NAME decides the
-  // carrier: the path here is a value, not a text to make guesses about, and `package.json` holds
-  // the settings under a key.
-  const decl: Declaration | null = a.config
-    ? {
-        path: a.config,
-        kind: basename(a.config) === PKG_NAME ? "package.json" : "rpp.json",
-      }
-    : findDeclaration(cwd);
-  const configPath = decl?.path ?? null;
+  // loud, and a substitution is never silent. Either way the file has the shape of a
+  // `package.json`: the settings sit under the key.
+  const configPath = a.config ?? findConfig(cwd);
   if (a.config && !existsSync(a.config)) {
     err(`config file not found: ${a.config}`);
     return { code: 2 };
   }
 
-  let opts: RppConfig = {};
+  let opts: PaperlintConfig = {};
   let legacyKey = false;
-  if (decl && configPath) {
+  if (configPath) {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any -- #49: replace with a real type
     let parsed: any;
     try {
@@ -551,15 +612,13 @@ export function readConfig(
       err(`${configPath} is not valid JSON: ${(e as Error).message}`);
       return { code: 2 };
     }
-    if (decl.kind === "package.json") {
-      const d = declaredSettings(parsed);
-      if (d.conflict !== null) {
-        err(d.conflict);
-        return { code: 2 };
-      }
-      opts = (d.settings ?? {}) as RppConfig;
-      legacyKey = d.legacy;
-    } else opts = parsed;
+    const d = declaredSettings(parsed);
+    if (d.conflict !== null) {
+      err(d.conflict);
+      return { code: 2 };
+    }
+    opts = (d.settings ?? {}) as PaperlintConfig;
+    legacyKey = d.legacy;
     // The discovered config is NAMED out loud. Otherwise a run from someone else's directory picks
     // up someone else's file and does not say so — and a typography-debt mismatch looks like a finding.
     //
@@ -568,30 +627,19 @@ export function readConfig(
     // test but by an attempt to wire our own action to this output; in the harness I first WORKED
     // AROUND this line (stripped the first line before JSON.parse) — that is, the workaround hid
     // the defect exactly where it should have been shouting.
-    (a.json ? err : log)(`config: ${relative(cwd, configPath) || CONFIG_NAME}`);
-    // 🔴 THE DEPRECATED CARRIER IS NAMED OUT LOUD, IT DOES NOT STOP BEING READ. The hooks read ONLY
-    // package.json, so a consumer whose settings stayed in rpp.json lints one directory and guards
-    // another — and both states look equally green.
-    if (decl.kind === "rpp.json")
-      (a.json ? err : log)(
-        `  ⚠ ${CONFIG_NAME} is deprecated — move these keys under "${CONFIG_KEY}" in ${PKG_NAME}; ` +
-          `the hooks read only that file. \`npx paperlint init\` does it for you.`,
-      );
+    (a.json ? err : log)(`config: ${relative(cwd, configPath) || PKG_NAME}`);
     if (legacyKey) (a.json ? err : log)(`  ⚠ ${LEGACY_KEY_MESSAGE}`);
   }
 
   // The old field name is refused before anything else is read from the settings: falling back
   // to it would keep it working forever, and this package has no released users to migrate.
-  const where =
-    decl?.kind === "package.json"
-      ? `${PKG_NAME} → "${legacyKey ? LEGACY_CONFIG_KEY : CONFIG_KEY}"`
-      : (decl?.path ?? CONFIG_NAME);
-  const renamed = decl ? renamedFieldMessage(opts, where) : null;
+  const where = `${configPath ? basename(configPath) : PKG_NAME} → "${legacyKey ? LEGACY_CONFIG_KEY : CONFIG_KEY}"`;
+  const renamed = configPath ? renamedFieldMessage(opts, where) : null;
   if (renamed) {
     err(renamed);
     return { code: 2 };
   }
-  if (decl && configPath) {
+  if (configPath) {
     const parsed = parseSettings(
       opts,
       where,
@@ -607,15 +655,11 @@ export function readConfig(
   // 🔴 THE PAPERS DIRECTORY IS A REQUIRED FIELD. The papers directory is the one thing without which the tool
   // does not know what it works on, and the one thing that cannot be guessed: a default of "." runs
   // the rules over the whole checkout and exits green over a scope nobody chose.
-  if (decl && !hasPapers(opts)) {
+  if (configPath && !hasPapers(opts)) {
     err(
-      decl.kind === "package.json"
-        ? `${decl.path} must declare \`${PAPERS_DIR_FIELD}\` — the directory your papers live in, e.g.\n` +
-            `  { "${CONFIG_KEY}": { "${PAPERS_DIR_FIELD}": "papers" } }\n` +
-            `It is the one thing this tool cannot guess. \`npx paperlint init\` writes it for you.`
-        : `${decl.path} must declare \`${PAPERS_DIR_FIELD}\` — the directory your papers live in, e.g.\n` +
-            `  { "${PAPERS_DIR_FIELD}": "papers" }\n` +
-            `It is the one thing this tool cannot guess.`,
+      `${configPath} must declare \`${PAPERS_DIR_FIELD}\` — the directory your papers live in, e.g.\n` +
+        `  { "${CONFIG_KEY}": { "${PAPERS_DIR_FIELD}": "papers" } }\n` +
+        `It is the one thing this tool cannot guess. \`npx paperlint init\` writes it for you.`,
     );
     return { code: 2 };
   }
@@ -623,7 +667,7 @@ export function readConfig(
 }
 
 /** The papers directory field of the settings, read by its one declared name. */
-export function papersDirOf(opts: RppConfig): unknown {
+export function papersDirOf(opts: PaperlintConfig): unknown {
   return (opts as Record<string, unknown>)[PAPERS_DIR_FIELD];
 }
 
@@ -635,7 +679,7 @@ export function toPaths(papers: unknown): string[] {
   return [];
 }
 
-const hasPapers = (opts: RppConfig): boolean =>
+const hasPapers = (opts: PaperlintConfig): boolean =>
   toPaths(papersDirOf(opts)).length > 0;
 
 /**
@@ -703,7 +747,7 @@ export function runHook(
       throw new Error(`resolved vigiles, but no cli.js beside it: ${runtime}`);
   } catch {
     err(
-      `rpp: the hook runtime (vigiles) is not resolvable from ${fileURLToPath(new URL(".", import.meta.url))}.\n` +
+      `paperlint: the hook runtime (vigiles) is not resolvable from ${fileURLToPath(new URL(".", import.meta.url))}.\n` +
         `The \`${name}\` hook is NOT running. Everything else — \`paperlint lint\`, CI — is unaffected.\n` +
         `Reinstall this package so its dependencies are present.`,
     );
@@ -864,15 +908,40 @@ async function runBuild(
   return anyFailed(out.results) ? 1 : 0;
 }
 
-/** What one paper needs from TeX Live; a venue.json that does not parse is the build's to report. */
+/** The presets' deps, wired to the disk and the package's own venues directory. */
+const PRESET_DEPS = { files: nodeFiles, venuesDir: packageVenuesDir() };
+
+/**
+ * What one paper needs from TeX Live: the base set plus its preset chain's `tex`. A paper whose
+ * settings or preset do not resolve gets the base set; the build reports why at its facts step.
+ */
 function paperRequirements(dir: string): TexRequirements {
-  let venue: string | null = null;
-  try {
-    venue = readFacts(dir).venue;
-  } catch {
-    venue = null;
-  }
-  return requirementsFor(venue).tex;
+  const p = paperPreset(dir, PRESET_DEPS);
+  return requirementsFor(p.kind === "resolved" ? p.preset : null).tex;
+}
+
+/**
+ * What `paperlint toolchain` installs: every shipped preset's packages, plus the resolved chain of
+ * every paper under the project's papers directory — a project's own preset lives outside the
+ * package, so the shipped union alone would not see it.
+ */
+export function toolchainTex(cwd: string): TexRequirements {
+  const cfg = readConfig(parseArgs(["toolchain"]), {
+    log: () => {},
+    err: () => {},
+    cwd,
+  });
+  const roots =
+    cfg.code === undefined
+      ? toPaths(papersDirOf(cfg.opts)).map((rel) =>
+          resolve(dirname(cfg.configPath ?? cwd), rel),
+        )
+      : [];
+  const chains = roots
+    .flatMap((r) => papersIn(r))
+    .map((dir) => paperPreset(dir, PRESET_DEPS))
+    .flatMap((p) => (p.kind === "resolved" ? [p.preset.tex] : []));
+  return declaredUnion(undefined, chains).tex;
 }
 
 /**
@@ -914,8 +983,14 @@ const SIMPLE: Readonly<
   hook: (a, { err }) => runHook(a.paths[0], { err }),
   new: (a, io) => runNew(a, io),
   build: (a, io) => runBuild(a, io),
-  toolchain: (a, { log, err }) =>
-    runToolchain({ check: a.check, log, err, banal: hostBanalInstaller() }),
+  toolchain: (a, { log, err, cwd }) =>
+    runToolchain({
+      check: a.check,
+      log,
+      err,
+      banal: hostBanalInstaller(),
+      tex: toolchainTex(cwd),
+    }),
 };
 
 /** banal's installer, wired from this process's environment: the composition root's work. */
@@ -1048,7 +1123,7 @@ export async function run(
         );
   if (paths.length === 0) {
     err(
-      `nothing to lint: no path was given and no ${CONFIG_NAME} was found.\n` +
+      `nothing to lint: no path was given and no "${CONFIG_KEY}" key was found in a ${PKG_NAME}.\n` +
         `Run \`npx paperlint init\` here, or pass the directory: \`paperlint lint papers\`.`,
     );
     return 2;
@@ -1059,6 +1134,14 @@ export async function run(
   // a directory without `PIPELINE-STATUS.md` simply gets not a single rule and reports clean. The
   // analysis of why a structure plugin for ESLint does not cure this is in `structure.mjs`.
   const structure = checkStructure(paths, opts.structure, { cwd });
+  // Each paper's own `rules` (its paperlint.json) go after paperlint's blocks and BEFORE the
+  // project's, so the project's package.json still has the last word.
+  const papers = paperRuleBlocks(paths);
+  if (!papers.ok) return (err(papers.error), 2);
+  const withPapers = {
+    ...opts,
+    rules: [...papers.value, ...(opts.rules ?? [])],
+  };
 
   let texLanguage: unknown = null;
   try {
@@ -1072,7 +1155,7 @@ export async function run(
   const eslint = new ESLint({
     cwd: lintRoot(configPath ? dirname(resolve(cwd, configPath)) : cwd, paths),
     overrideConfigFile: true,
-    overrideConfig: buildConfig(opts, texLanguage) as Linter.Config[],
+    overrideConfig: buildConfig(withPapers, texLanguage) as Linter.Config[],
   });
 
   // 🔴 ESLint THROWS on an empty set (`NoFilesFoundError`) — the guard below simply never got
@@ -1109,7 +1192,7 @@ export async function run(
     log,
     err,
     where: relative(cwd, dirname(resolve(cwd, configPath ?? "."))) || ".",
-    opts,
+    opts: withPapers,
   });
 }
 
@@ -1133,7 +1216,7 @@ async function reportLint(
     log: typeof console.log;
     err: typeof console.error;
     where: string;
-    opts: RppConfig;
+    opts: PaperlintConfig;
   },
 ): Promise<number> {
   const silent = await silentOptionalRules(
@@ -1180,7 +1263,7 @@ async function reportLint(
 
 // 🔴 `isMain`, NOT A STRING COMPARISON. The first version wrote
 //     if (import.meta.url === `file://${process.argv[1]}`)
-// and the utility, launched via `node_modules/.bin/rpp`, SILENTLY EXITED WITH ZERO: npm puts a
+// and the utility, launched via `node_modules/.bin/paperlint`, SILENTLY EXITED WITH ZERO: npm puts a
 // SYMLINK there, `process.argv[1]` stays the symlink's path while `import.meta.url` is the real
 // path, and the condition is false. That is, the only way a real consumer launches the utility did
 // not work at all — and it looked like a clean run.

package/src/doctor.harness.mjs

@@ -41,9 +41,9 @@ const check = (label, cond) => {
   assert.ok(cond, label);
 };
 
-/** A consumer on disk: a papers directory, declarations in one or both places. */
-function consumer({ papersDir, pkgKey, rppJson, makeDir = true }) {
-  const dir = realpathSync(mkdtempSync(join(tmpdir(), "rpp-doctor-")));
+/** A consumer on disk: a papers directory, and maybe a declaration in package.json. */
+function consumer({ papersDir, pkgKey, makeDir = true }) {
+  const dir = realpathSync(mkdtempSync(join(tmpdir(), "paperlint-doctor-")));
   if (makeDir && papersDir) {
     mkdirSync(join(dir, papersDir, "some-paper"), { recursive: true });
     writeFileSync(
@@ -54,11 +54,6 @@ function consumer({ papersDir, pkgKey, rppJson, makeDir = true }) {
   const pkg = { name: "consumer", version: "1.0.0" };
   if (pkgKey !== undefined) pkg["paperlint"] = { [PAPERS_DIR_FIELD]: pkgKey };
   writeFileSync(join(dir, "package.json"), JSON.stringify(pkg, null, 2));
-  if (rppJson !== undefined)
-    writeFileSync(
-      join(dir, "rpp.json"),
-      JSON.stringify({ [PAPERS_DIR_FIELD]: rppJson }, null, 2),
-    );
   return dir;
 }
 
@@ -113,13 +108,10 @@ const runDoctor = (
 }
 
 // ── II. THE VERY DEFECT: AN INSTALL FOLLOWING THE DOCS ─────────────────────────────────────
-// `paperlint init` writes rpp.json and does not touch package.json; the hook reads package.json.
+// The old `init` wrote its own config file and did not touch package.json; the hook reads package.json.
 // Measured 09-18.
 {
-  const dir = consumer({
-    papersDir: "writing/drafts",
-    rppJson: "writing/drafts",
-  });
+  const dir = consumer({ papersDir: "writing/drafts" });
   const r = runDoctor(dir, { cliPapers: "writing/drafts" });
   check(
     "an install that follows the docs — a FAILURE, not a cheerful report",
@@ -150,7 +142,7 @@ const runDoctor = (
 // It must not fail here (an error-level false positive costs more than a miss), but it must
 // not stay silent either.
 {
-  const dir = consumer({ papersDir: "papers", rppJson: "papers" });
+  const dir = consumer({ papersDir: "papers" });
   const r = runDoctor(dir, { cliPapers: "papers" });
   check("an install that works by coincidence does NOT crash", r.code === 0);
   check(
@@ -220,18 +212,10 @@ const runDoctor = (
 
 // ── III. TWO DECLARATIONS HAVE DRIFTED APART ────────────────────────────────────────────────
 {
-  const dir = consumer({
-    papersDir: "writing/drafts",
-    pkgKey: "papers",
-    rppJson: "writing/drafts",
-  });
+  const dir = consumer({ papersDir: "writing/drafts", pkgKey: "papers" });
   mkdirSync(join(dir, "papers"), { recursive: true });
   const r = runDoctor(dir, { cliPapers: "writing/drafts" });
   check("both declarations exist, but differ — a FAILURE", r.code === 2);
-  check(
-    "the stale rpp.json is called out ⚠",
-    /rpp\.json is present/.test(r.out),
-  );
   rmSync(dir, { recursive: true, force: true });
 }
 
@@ -307,7 +291,7 @@ const runDoctor = (
 
 // ── VII. DETECTING THE PAPERS DIRECTORY ─────────────────────────────────────────────────────
 {
-  const dir = realpathSync(mkdtempSync(join(tmpdir(), "rpp-detect-")));
+  const dir = realpathSync(mkdtempSync(join(tmpdir(), "paperlint-detect-")));
   mkdirSync(join(dir, "writing", "drafts", "p1"), { recursive: true });
   writeFileSync(join(dir, "writing", "drafts", "p1", "paper.tex"), "x");
   mkdirSync(join(dir, "node_modules", "pkg", "papers", "p"), {
@@ -387,7 +371,7 @@ const runDoctor = (
   check("a program that really exists is found", found("node") === true);
   check(
     "a made-up one is not (otherwise the check answers the form, not the subject)",
-    found("rpp-definitely-not-a-real-binary-xyz") === false,
+    found("paperlint-definitely-not-a-real-binary-xyz") === false,
   );
 }