paperlint 2.1.0 → 3.1.0

package/src/rules-config.ts

@@ -44,6 +44,7 @@ export type Parsed<T> =
   | { readonly ok: false; readonly error: string };
 
 const SEVERITIES: readonly unknown[] = ["off", "warn", "error", 0, 1, 2];
+
 const BLOCK_KEYS = new Set(["files", "ignores", "rules"]);
 
 const bad = <T>(error: string): Parsed<T> => ({ ok: false, error });
@@ -67,7 +68,7 @@ function parseEntry(v: unknown): RuleEntry | null {
 
 /**
  * A `rules` object — rule id → severity or `[severity, ...options]` — with only the rules paperlint
- * ships. Read from the package.json blocks and from a paper's `paperlint.json`.
+ * ships. Read from every `paperlint.json`, the root's and each paper's.
  *
  * @param where  the key path to name in messages, e.g. `package.json → "paperlint".rules[0].rules`
  */
@@ -108,17 +109,20 @@ const globsOf = (o: Record<string, unknown>) => ({
   ...(o["ignores"] ? { ignores: o["ignores"] as string[] } : {}),
 });
 
+const isRecord = (v: unknown): v is Record<string, unknown> =>
+  typeof v === "object" && v !== null && !Array.isArray(v);
+
 /** One element of the `rules` list. */
 function parseBlock(
   v: unknown,
   at: string,
   ctx: { shipped: ReadonlySet<string>; baseDir: string },
 ): Parsed<RuleBlock> {
-  if (typeof v !== "object" || v === null || Array.isArray(v))
+  if (!isRecord(v))
     return bad(
       `${at} must be an object like { "files": [...], "rules": {...} }`,
     );
-  const o = v as Record<string, unknown>;
+  const o = v;
   const extra = Object.keys(o).filter((k) => !BLOCK_KEYS.has(k));
   if (extra.length)
     return bad(
@@ -135,10 +139,12 @@ function parseBlock(
 }
 
 /**
- * The `rules` key → config blocks, or one error naming the key path.
+ * The `rules` key → config blocks, or one error naming the key path. Two shapes, at every level:
+ * `{ id: severity }` is one block over every paper file under `baseDir`; a list is ESLint blocks
+ * (`files`, `ignores`, `rules`), their globs relative to `baseDir`.
  *
  * @param raw      the value under `rules` (undefined when absent)
- * @param where    how the settings are named in messages, e.g. `package.json → "paperlint"`
+ * @param where    how the settings are named in messages, e.g. `paperlint.json`
  * @param shipped  the rule ids paperlint ships (`shippedRuleIds`)
  * @param baseDir  the directory of the file holding the settings
  */
@@ -149,13 +155,19 @@ export function parseRuleBlocks(
   baseDir: string,
 ): Parsed<readonly RuleBlock[]> {
   if (raw === undefined) return { ok: true, value: [] };
+  if (isRecord(raw)) {
+    const rules = parseRuleEntries(raw, `${where} → "rules"`, shipped);
+    return rules.ok
+      ? { ok: true, value: [{ basePath: baseDir, rules: rules.value }] }
+      : rules;
+  }
   if (!Array.isArray(raw))
     return bad(
-      `${where}.rules must be a list of blocks, like ESLint's flat config: [{ "files": [...], "rules": {...} }]`,
+      `${where} → "rules" must be { "<rule>": "<severity>" }, or a list of blocks like ESLint's flat config: [{ "files": [...], "rules": {...} }]`,
     );
   const out: RuleBlock[] = [];
   for (const [i, v] of raw.entries()) {
-    const b = parseBlock(v, `${where}.rules[${i}]`, { shipped, baseDir });
+    const b = parseBlock(v, `${where} → rules[${i}]`, { shipped, baseDir });
     if (!b.ok) return b;
     out.push(b.value);
   }

package/src/rules-off.test.ts

@@ -0,0 +1,111 @@
+/**
+ * A consumer that ALSO lints paper files with its own ESLint config (#104).
+ *
+ * 3.0.0 made `% eslint-disable-next-line <rule> -- <why>` the way to keep a deliberate exception.
+ * A project that runs its own `eslint` over the same `paper.tex` — for its own rules, with
+ * paperlint's LaTeX language — did not register paperlint's rule plugins, so that run failed on the
+ * directive: "Definition for rule 'paper/leading-zero' was not found". `rulesOff` is the fragment
+ * such a config spreads in: every rule paperlint ships, registered and turned off.
+ */
+import { ESLint, type Linter } from "eslint";
+import { describe, expect, it } from "vitest";
+// @ts-expect-error — the module is .mjs and has no types.
+import { texLanguage } from "../eslint-rules/latex-language.mjs";
+import { rulePlugins, rulesOff, SHIPPED_RULES } from "./cli.ts";
+
+const PAPER = [
+  "\\documentclass{article}",
+  "\\begin{document}",
+  "% eslint-disable-next-line paper/leading-zero -- quoted from the reviewer",
+  "We use a threshold of .05 throughout.",
+  "% eslint-disable-next-line bib/reachable-entry -- kept for the artifact",
+  "Nothing else.",
+  "\\end{document}",
+  "",
+].join("\n");
+
+/** The consumer's own config: its LaTeX files, with paperlint's language, and its own rules. */
+async function lintAsConsumer(
+  fragment: Linter.Config[],
+): Promise<Linter.LintMessage[]> {
+  const eslint = new ESLint({
+    overrideConfigFile: true,
+    overrideConfig: [
+      ...fragment,
+      {
+        files: ["**/*.tex"],
+        plugins:
+          fragment.length > 0
+            ? {}
+            : { tex: { languages: { latex: texLanguage } } },
+        language: "tex/latex",
+      },
+    ],
+  });
+  const [res] = await eslint.lintText(PAPER, {
+    filePath: "papers/a/paper.tex",
+  });
+  return res!.messages;
+}
+
+describe("rulesOff — paperlint's rules, registered and off, for a consumer's own ESLint run", () => {
+  it("without it, the documented escape hatch breaks the consumer's run (the defect)", async () => {
+    const messages = await lintAsConsumer([]);
+    expect(messages.map((m) => m.message)).toContain(
+      "Definition for rule 'paper/leading-zero' was not found.",
+    );
+  });
+
+  it("🔴 spreading it: no 'Definition … not found', and no paperlint finding runs", async () => {
+    const messages = await lintAsConsumer(rulesOff(texLanguage));
+    // Guards: the defect — every directive names a rule ESLint now knows.
+    expect(messages.map((m) => m.message).join("\n")).not.toMatch(
+      /Definition for rule/,
+    );
+    // Guards: off means off — paperlint's own run judges these files, not the consumer's.
+    expect(messages.filter((m) => m.ruleId?.startsWith("paper/"))).toEqual([]);
+    // Guards: a directive naming an OFF rule suppresses nothing, and ESLint would call it unused
+    // ("Unused eslint-disable directive (no problems were reported from 'paper/leading-zero')").
+    expect(messages).toEqual([]);
+  });
+
+  it("registers every rule paperlint ships, each off, and carries the LaTeX language", () => {
+    const [cfg] = rulesOff(texLanguage);
+    expect(new Set(Object.keys(cfg?.rules ?? {}))).toEqual(SHIPPED_RULES);
+    expect(Object.values(cfg?.rules ?? {}).every((e) => e === "off")).toBe(
+      true,
+    );
+    const plugins = rulePlugins(texLanguage);
+    const defined = new Set<string>();
+    for (const [name, p] of Object.entries(plugins))
+      for (const r of Object.keys(p.rules ?? {})) defined.add(`${name}/${r}`);
+    expect(defined).toEqual(SHIPPED_RULES);
+    expect(plugins["tex"]?.languages?.["latex"]).toBe(texLanguage);
+    // `@eslint/markdown` is a dependency's plugin: the consumer registers its own.
+    expect(plugins["markdown"]).toBeUndefined();
+  });
+
+  it("the unused-directive report is off on paper files only, not on the consumer's code", async () => {
+    const eslint = new ESLint({
+      overrideConfigFile: true,
+      overrideConfig: [
+        ...rulesOff(texLanguage),
+        {
+          files: ["**/*.js"],
+          linterOptions: { reportUnusedDisableDirectives: "warn" },
+        },
+      ],
+    });
+    const [res] = await eslint.lintText(
+      "// eslint-disable-next-line paper/leading-zero -- nothing to silence\nconst x = 1;\n",
+      { filePath: "src/x.js" },
+    );
+    expect(res!.messages.map((m) => m.message)).toEqual([
+      "Unused eslint-disable directive (no problems were reported from 'paper/leading-zero').",
+    ]);
+  });
+
+  it("without a LaTeX language, the `tex` plugin carries rules only", () => {
+    expect(rulePlugins()["tex"]?.languages).toBeUndefined();
+  });
+});

package/src/structure.harness.mjs

@@ -71,8 +71,10 @@ try {
   );
   check(
     "and the message names the CONSEQUENCE, not a restatement of the condition",
-    /is checked/.test(at("no-scorecard")[0].message) &&
-      /stages, sources or authors/.test(at("no-scorecard")[0].message),
+    /are skipped/.test(at("no-scorecard")[0].message) &&
+      /stage, source and research-question checks/.test(
+        at("no-scorecard")[0].message,
+      ),
   );
   check(
     "and the consequence names THIS directory by name",

package/src/structure.ts

@@ -25,7 +25,7 @@
 import { readdirSync, existsSync } from "node:fs";
 import { join, relative, basename, isAbsolute, sep } from "node:path";
 import type { StructureConfig, StructureFinding } from "./types.ts";
-import { PAPER_SETTINGS_FILE } from "../lib/paper-config.mjs";
+import { CONFIG_FILE } from "../lib/paper-config.mjs";
 
 /** The requirements after the consumer's config is laid over the defaults. */
 type Rules = Required<StructureConfig>;
@@ -38,7 +38,7 @@ type Rules = Required<StructureConfig>;
  * byte-compared by the `paper/stages` rule anyway.
  */
 export const STRUCTURE_DEFAULTS = {
-  markers: ["PIPELINE-STATUS.md", "paper.tex", "paper.md", PAPER_SETTINGS_FILE],
+  markers: ["PIPELINE-STATUS.md", "paper.tex", "paper.md", CONFIG_FILE],
   require: ["PIPELINE-STATUS.md"],
   requireOneOf: [["paper.tex", "paper.md"]],
   ignore: [],
@@ -122,7 +122,7 @@ export function checkStructure(
  */
 function whyMissingMatters(file: string, dirName: string): string {
   if (file === "PIPELINE-STATUS.md")
-    return `\`paper/stages\`, \`paper/source\` and \`paper/author-list\` read this file, so nothing \`${dirName}\` declares about its stages, sources or authors is checked`;
+    return `the stage, source and research-question checks are skipped for \`${dirName}\``;
   return `declared as required by your \`structure\` configuration`;
 }
 

package/src/tex-requirements.ts

@@ -26,7 +26,7 @@ import { join } from "node:path";
 // eslint-disable-next-line boundaries/dependencies -- legacy layer, moves behind a port in #76
 import Ajv from "ajv";
 import { packageVenuesDir } from "../skills/paper-pipeline/scripts/consumer.mjs";
-import { PAPER_SETTINGS_FILE } from "../lib/paper-config.mjs";
+import { CONFIG_FILE } from "../lib/paper-config.mjs";
 
 /** CTAN package name → the names that prove it is installed. */
 export type PackageProofs = Readonly<Record<string, readonly string[]>>;
@@ -298,7 +298,7 @@ export function requirementsFor(
   const base = readProfile(dir, BASE_PROFILE);
   return preset === null
     ? {
-        source: `the base set (no venue preset in ${PAPER_SETTINGS_FILE})`,
+        source: `the base set (no venue preset in ${CONFIG_FILE})`,
         tex: base,
       }
     : {

package/src/toolchain.harness.mjs

@@ -163,14 +163,19 @@ for (const f of [
   "stub-pdflatex",
   "stub-kpsewhich",
   "stub-tlmgr",
+  "stub-fmtutil-sys",
   "release-texlive.txt",
 ])
   copyFileSync(join(FIXTURE, f), join(staging, f));
 spawnSync("chmod", [
   "+x",
-  ...["install-tl", "stub-pdflatex", "stub-kpsewhich", "stub-tlmgr"].map((f) =>
-    join(staging, f),
-  ),
+  ...[
+    "install-tl",
+    "stub-pdflatex",
+    "stub-kpsewhich",
+    "stub-tlmgr",
+    "stub-fmtutil-sys",
+  ].map((f) => join(staging, f)),
 ]);
 spawnSync(
   "tar",
@@ -192,6 +197,10 @@ writeFileSync(
 const url = (dir) => pathToFileURL(dir).href;
 const MISSING = url(join(work, "no-such-mirror"));
 
+/** A call that downloads or installs. `tlmgr check depends` only reads, so it is not one. */
+const installs = (c) =>
+  c.cmd === "curl" || (c.cmd.endsWith("tlmgr") && c.args.includes("install"));
+
 /** A `spawnSync` that records every program it was asked to run. */
 const recorder = () => {
   const calls = [];
@@ -364,8 +373,33 @@ const cmd = ({ banal = BANAL, ...over } = {}) => {
   );
   check(
     "second run: downloads nothing and installs nothing",
-    !r.calls.some((c) => c.cmd === "curl" || c.cmd.endsWith("tlmgr")),
-    JSON.stringify(r.calls.map((c) => c.cmd)),
+    !r.calls.some(installs),
+    JSON.stringify(r.calls.map((c) => [c.cmd, ...c.args])),
+  );
+}
+// Guards: a tree with every venue package can still be broken. install-tl that lost a package
+// to a mirror prints "continuing anyway"; seen 2026-09-26 with unicode-data, after which the
+// pdflatex format was never built and every build died before writing a log.
+{
+  const tree = join(root, "2026");
+  writeFileSync(join(tree, "missing-deps.txt"), "unicode-data\n");
+  const check1 = cmd({ check: true });
+  check(
+    "🔴 a dropped base dependency: --check does not call the tree complete",
+    check1.code === 1,
+    `${check1.out}\n${check1.err}`,
+  );
+  const r = cmd();
+  check(
+    "🔴 a dropped base dependency: the run installs it, then builds the missing formats",
+    r.code === 0 &&
+      readFileSync(join(tree, "tlmgr.log"), "utf8").includes("unicode-data") &&
+      readFileSync(join(tree, "fmtutil.log"), "utf8").trim() === "--missing",
+    `${r.out}\n${r.err}`,
+  );
+  check(
+    "a dropped base dependency: the tree is whole afterwards",
+    readFileSync(join(tree, "missing-deps.txt"), "utf8").trim() === "",
   );
 }
 {
@@ -500,6 +534,7 @@ const mirrorFor = (name, year, installerYear = year) => {
     "stub-pdflatex",
     "stub-kpsewhich",
     "stub-tlmgr",
+    "stub-fmtutil-sys",
   ])
     copyFileSync(join(staging, f), join(stage, f));
   writeFileSync(
@@ -544,7 +579,7 @@ check(
       r.out.includes("TeX Live 2026") &&
       r.out.includes("nothing to do") &&
       !existsSync(join(years, "2027")) &&
-      !r.calls.some((c) => c.cmd === "curl" || c.cmd.endsWith("tlmgr")),
+      !r.calls.some(installs),
     `${r.out}\n${JSON.stringify(r.calls.map((c) => c.cmd))}`,
   );
 }

package/src/toolchain.ts

@@ -45,6 +45,7 @@ import { join } from "node:path";
 import {
   isExecutable,
   missingTools,
+  missingDependencies,
   probeTree,
   supportedPlatform,
   type Runner,
@@ -240,14 +241,20 @@ function yearAfter(lines: readonly string[], label: string): string | null {
     : null;
 }
 
-/** What a tree lacks: packages by `kpsewhich`, tools by executable. */
+/**
+ * What a tree lacks: the venue's packages by `kpsewhich`, tools by executable, and packages the
+ * tree's own database depends on but never installed (`tlmgr check depends`).
+ */
 export interface Gaps {
   readonly packages: readonly string[];
   readonly tools: readonly string[];
+  readonly dependencies: readonly string[];
 }
 
 export const noGaps = (g: Gaps): boolean =>
-  g.packages.length === 0 && g.tools.length === 0;
+  g.packages.length === 0 &&
+  g.tools.length === 0 &&
+  g.dependencies.length === 0;
 
 /** `acmart (acmart.cls), texcount (texcount)` — a gap named with the file that proves it. */
 export function describeGaps(g: Gaps, tex: TexRequirements): string {
@@ -258,6 +265,9 @@ export function describeGaps(g: Gaps, tex: TexRequirements): string {
   return [
     ...named(g.packages, tex.packages),
     ...named(g.tools, tex.tools),
+    ...g.dependencies.map(
+      (d) => `${d} (a TeX Live dependency the install left out)`,
+    ),
   ].join(", ");
 }
 
@@ -296,6 +306,7 @@ export function gapsOf(
   return {
     packages: probeTree(tree.bin, tex.packages, run),
     tools: missingTools(tex.tools, tree.bin),
+    dependencies: missingDependencies(tree.bin, run),
   };
 }
 
@@ -460,7 +471,8 @@ export function installPackages(
   let last: string[] = [];
   for (const mirror of mirrors) {
     if (noGaps(gaps)) break;
-    const want = [...gaps.packages, ...gaps.tools];
+    const want = [...gaps.packages, ...gaps.tools, ...gaps.dependencies];
+    const repairsBase = gaps.dependencies.length > 0;
     io.log(`  tlmgr: installing ${want.length} package(s) from ${mirror}…`);
     const r = io.run(
       join(tree.bin, "tlmgr"),
@@ -481,6 +493,10 @@ export function installPackages(
         ],
       };
     last = tail(r);
+    // A dependency of the base was missing, so the formats it feeds were never built (pdflatex dies
+    // before writing a log without them). Build the missing ones now that the package is in.
+    if (repairsBase)
+      io.run(join(tree.bin, "fmtutil-sys"), ["--missing"], quiet(io, TLMGR_MS));
     gaps = gapsOf(tree, tex, io.run);
   }
   return { ok: true, value: { gaps, tail: last } };
@@ -688,9 +704,17 @@ function report(o: Resolved, tree: CachedTree | null): number {
     o.log(binLine(tree));
     return 0;
   }
-  const count = gaps.packages.length + gaps.tools.length;
+  const declared = gaps.packages.length + gaps.tools.length;
+  // A dependency the install left out is not one of the venue's declared packages: counted apart,
+  // so the line never reads "lacks 0 of 51" followed by a name.
+  const what = [
+    ...(declared ? [`${declared} of ${n} declared packages`] : []),
+    ...(gaps.dependencies.length
+      ? [`${gaps.dependencies.length} TeX Live base package(s)`]
+      : []),
+  ].join(" and ");
   o.log(
-    `✗ TeX Live ${tree.year} in ${tree.dir} lacks ${count} of ${n} declared packages: ${describeGaps(gaps, o.tex)}`,
+    `✗ TeX Live ${tree.year} in ${tree.dir} lacks ${what}: ${describeGaps(gaps, o.tex)}`,
   );
   o.log(`  run \`npx paperlint toolchain\` to install them`);
   return 1;

package/src/types.ts

@@ -5,29 +5,27 @@ import type { RuleBlock } from "./rules-config.ts";
  * in someone's head: a typo in a config key read as "field not set", not as an error.
  */
 
-/** The consumer's settings — the `paperlint` key of its `package.json`. */
+/**
+ * The project's settings — the root `paperlint.json`, optional. Every key is optional; the key list
+ * (and which keys a paper's own `paperlint.json` may also hold) is `SETTINGS_KEYS` in
+ * lib/paper-config.mjs.
+ */
 export interface PaperlintConfig {
-  /** 🔴 REQUIRED. The paper director(ies), relative to the config file ITSELF. The field name is
+  /** The paper director(ies), relative to the project root. Default `papers`. The field name is
    * `PAPERS_DIR_FIELD` in lib/paper-config.mjs; code reads it through `papersDirOf()` in cli.ts. */
   papersDir?: string | string[];
-  /** The command that prints the author list from .bib — each corpus has its own. */
-  authorListCommand?: string;
-  /** Per-paper typography debt: how many findings already exist; the number may only go down. */
-  typographyDebt?: Record<string, Record<string, number>>;
-  /** Frontmatter fields required for review notes, and the permitted values of each. */
-  docFields?: Record<string, { values: string[] }>;
-  /** Ignore review findings older than this date. */
-  reviewSince?: string;
-  /** How many findings a cold read must produce to count as a cold read. */
-  minFindings?: number;
-  /** The word with which review notes introduce the cause. */
-  causeMarker?: string;
   /** Which files a paper directory must carry; `false` turns the check off entirely. */
   structure?: StructureConfig | false;
-  /** REMOVED — `paperlint build` compiles the paper itself. Still typed so a leftover key can be named. */
-  buildScripts?: unknown;
   /** ESLint config blocks appended after paperlint's own — PARSED by `parseSettings` in cli.ts. */
   rules?: readonly RuleBlock[];
+  /** The default venue preset of every paper that names none (`src/paper-settings.ts`). */
+  extends?: string | null;
+  /** The default kind of paper. */
+  kind?: string;
+  /** The default path of the built PDF, relative to each paper. */
+  pdf?: string;
+  /** A note for humans; ignored. */
+  $comment?: unknown;
 }
 
 export interface StructureConfig {
@@ -47,6 +45,8 @@ export interface Args {
   paths: string[];
   config: string | null;
   json: boolean;
+  /** `--fix`: `lint` writes every fix a rule offers, then reports what is left. */
+  fix: boolean;
   all: boolean;
   dryRun: boolean;
   /** `--check`: `toolchain` reports what is missing and changes nothing. */
@@ -60,11 +60,17 @@ export interface Args {
   paper: string | null;
   /** `--format tex|md` for `new` and `init --paper`. Validated by the command, not here. */
   format: string | null;
+  /** `--venue <preset>` for `new`: a shipped preset name, or a path to the project's own. */
+  venue: string | null;
+  /** `--kind <kind>` for `new`: one of the venue preset's kinds. */
+  kind: string | null;
   /** `--hooks=<mode>` — parsed only so it can be REFUSED by name rather than read as a path. */
   hooksMode: string | null;
   help?: boolean;
   /** A flag that turned out to have no value. A non-empty field is a REFUSAL, not a default. */
   missingValue?: string;
+  /** The first flag the parser does not know. Refused, never read as a path. */
+  unknownFlag?: string;
 }
 
 /** A finding about the PRESENCE of a file — what an ESLint rule cannot express. */
@@ -102,5 +108,17 @@ export interface BuildResult {
 
 /** The result of reading the config: either data, or the exit code the caller exits with. */
 export type ConfigRead =
-  | { opts: PaperlintConfig; configPath: string | null; code?: undefined }
-  | { code: number; opts?: undefined; configPath?: undefined };
+  | {
+      opts: PaperlintConfig;
+      /** The root `paperlint.json`, or null when the project has none. */
+      configPath: string | null;
+      /** The project root: `papersDir` and the `rules` globs are relative to it. */
+      root: string;
+      code?: undefined;
+    }
+  | {
+      code: number;
+      opts?: undefined;
+      configPath?: undefined;
+      root?: undefined;
+    };

package/src/venue-rules.test.ts

@@ -173,7 +173,7 @@ describe("a paper that meets its venue", () => {
 });
 
 describe("a paper that names no venue", () => {
-  it("no paperlint.json (a paper from before 2.1.0): every rule is silent, even with no facts and no PDF", () => {
+  it("no paperlint.json: every rule is silent, even with no facts and no PDF", () => {
     expect(lint({ venue: undefined, facts: null, pdf: null })).toEqual([]);
   });
 
@@ -228,16 +228,6 @@ describe("pdf/profile — the declaration must resolve, or nothing is judged", (
     expect(fs[0]?.message).toMatch(text);
   });
 
-  it("🔴 a venue.json left from before 2.1.0 is not read — pdf/profile says to run `paperlint init`", () => {
-    const fs = lint({
-      facts: null,
-      pdf: null,
-      extra: { [`${PAPER}/venue.json`]: JSON.stringify(DECL) },
-    });
-    expect(ids(fs)).toEqual(["pdf/profile:legacySettings"]);
-    expect(fs[0]?.message).toMatch(/npx paperlint init/);
-  });
-
   it("a profile that does not parse is named with the file", () => {
     const fs = lint({
       venue: { extends: "paperlint:mine", kind: "short" },
@@ -302,11 +292,33 @@ describe("pdf/profile — the kind", () => {
   });
 });
 
+describe("pdf/profile — a preset with no kinds", () => {
+  it("🔴 a preset with NO kinds (acm-sigconf) and no `kind`: nothing to pick, no finding", () => {
+    const fs = lint({
+      venue: { extends: "paperlint:acm-sigconf" },
+      facts: withFacts((f) => (f.body_pages = 99)),
+    });
+    expect(ids(fs).filter((id) => id.startsWith("pdf/profile"))).toEqual([]);
+  });
+
+  it("…but a `kind` named against a kindless preset is still an error that says it has none", () => {
+    const fs = lint({
+      venue: { extends: "paperlint:acm-sigconf", kind: "short" },
+    });
+    const profile = fs.filter((f) => f.rule === "pdf/profile");
+    expect(ids(profile)).toEqual(["pdf/profile:kindUnknown"]);
+    expect(profile[0]?.message).toMatch(/its kinds: \(none\)/);
+  });
+});
+
 describe("pdf/measured — a paper that names a venue and was not measured says so (warn)", () => {
   it("no facts file: one finding, from pdf/measured only", () => {
     const fs = lint({ venue: DECL, facts: null, pdf: null });
     expect(ids(fs)).toEqual(["pdf/measured:unbuilt"]);
     expect(fs[0]?.message).toMatch(/paperlint build/);
+    // Guards: the message stays one short line — it is the first thing a new user sees.
+    expect(fs[0]?.message).toMatch(/^not built yet, so /);
+    expect(fs[0]?.message.length).toBeLessThan(110);
   });
 
   it("facts without geometry (no banal): pdf/measured names it, the three geometry rules are silent, fonts still judge", () => {

package/src/venue-rules.ts

@@ -24,7 +24,7 @@
  * One rule per reason, and the others are silent — so a paper gets one finding that says what to
  * do, not six that say the same thing:
  *
- *   no paperlint.json       every rule silent — a paper from before 2.1.0 (`paperlint new` writes one)
+ *   no paperlint.json       every rule silent (`paperlint new` writes one)
  *   extends null / absent   pdf/measured (warn) — no venue chosen yet; it names the file to set
  *   preset does not resolve pdf/profile (error) — a typo would otherwise switch every check off
  *   not built / no facts    pdf/measured (warn) — lint often runs before or without a build (the
@@ -48,10 +48,7 @@ import type { FlatGeometry } from "./domain/geometry.ts";
 import type { AbsolutePath } from "./domain/paths.ts";
 import { sha256Hex } from "./domain/sha256.ts";
 import type { Files } from "./ports/files.ts";
-import {
-  LEGACY_PAPER_SETTINGS_MESSAGE,
-  PAPER_SETTINGS_FILE,
-} from "../lib/paper-config.mjs";
+import { CONFIG_FILE } from "../lib/paper-config.mjs";
 
 // ── the verdict's vocabulary ─────────────────────────────────────────────────────────
 
@@ -109,6 +106,11 @@ function kindOf(
   kind: string | null,
 ): Pick<Resolved, "kind" | "kindProblem"> {
   const known = [...format.kinds.keys()].join(", ") || "(none)";
+  // A preset with no kinds (`acm-sigconf`, a family a paper for an unprofiled venue extends
+  // directly) has no page limit to pick, so naming no kind is the only valid declaration. A kind
+  // named against it is still `kindUnknown`, whose "its kinds: (none)" says why.
+  if (kind === null && format.kinds.size === 0)
+    return { kind: null, kindProblem: null };
   if (kind === null)
     return {
       kind: null,
@@ -150,14 +152,11 @@ export function assessPaper(paperDir: string, deps: VenueRuleDeps): Assessment {
   if (p.kind === "none")
     return p.settings === null
       ? { kind: "no-venue" }
-      : { kind: "no-preset", file: join(paperDir, PAPER_SETTINGS_FILE) };
+      : { kind: "no-preset", file: join(paperDir, CONFIG_FILE) };
   if (p.kind === "settings-problem")
     return {
       kind: "unresolved",
-      finding:
-        p.problem.kind === "legacy"
-          ? finding("legacySettings")
-          : finding("settingsBroken", { why: p.problem.why }),
+      finding: finding("settingsBroken", { why: p.problem.why }),
     };
   if (p.kind === "preset-problem")
     return {
@@ -415,11 +414,10 @@ const META: Readonly<Record<VenueRuleName, Meta>> = {
         "the venue preset a paper's paperlint.json extends resolves, and the kind it names exists",
     },
     messages: {
-      settingsBroken: `${PAPER_SETTINGS_FILE} cannot be read: {{why}}`,
-      legacySettings: `this paper's venue checks do not run — ${LEGACY_PAPER_SETTINGS_MESSAGE}`,
+      settingsBroken: `${CONFIG_FILE} cannot be read: {{why}}`,
       preset:
         "{{why}} — so this paper's page limit, fonts and format are not checked. Fix `extends` in its paperlint.json, or turn pdf/profile off for this paper",
-      kindMissing: `${PAPER_SETTINGS_FILE} names no \`kind\`, so the page limit of \`{{venue}}\` is not checked; its kinds: {{known}}`,
+      kindMissing: `${CONFIG_FILE} names no \`kind\`, so the page limit of \`{{venue}}\` is not checked; its kinds: {{known}}`,
       kindUnknown:
         "`{{venue}}` has no kind `{{kind}}`, so the page limit is not checked; its kinds: {{known}}",
     },
@@ -432,7 +430,7 @@ const META: Readonly<Record<VenueRuleName, Meta>> = {
     },
     messages: {
       unbuilt:
-        "this paper names the venue `{{venue}}`, but {{file}} does not exist, so its page limit, fonts and format were NOT checked — run `paperlint build` before `paperlint lint`",
+        "not built yet, so `{{venue}}`'s page limit, fonts and format are not checked — run `paperlint build`",
       noPreset:
         'this paper names no venue preset yet, so its page limit, fonts and format are not checked — set "extends" in {{file}} (e.g. "paperlint:agenticdev"; see docs/rules.md)',
       noGeometry:

package/templates/paper/paperlint.json

@@ -1,4 +1,4 @@
 {
-  "$comment": "Name this paper's venue preset in \"extends\", e.g. \"paperlint:agenticdev\" (shipped: acm-sigconf, agenticdev, aisec, realm — see paperlint's docs/rules.md) or \"./venues/my-venue.jsonc\"; add \"kind\" for its page limit. Until then the page limit, fonts and format are not checked.",
+  "$comment": "Name this paper's venue preset in \"extends\": \"paperlint:<name>\" for a shipped one, e.g. \"paperlint:agenticdev\" (`npx paperlint --help` lists them), or a path to your own preset relative to THIS file, e.g. \"../../venues/my-venue.jsonc\"; add \"kind\" for its page limit. `npx paperlint new <name> --venue <preset>` writes both for a new paper. Until then the page limit, fonts and format are not checked.",
   "extends": null
 }