paperlint 3.0.0 → 3.1.1

package/dist/cli.js

@@ -45,10 +45,10 @@ import { paperRules, stringFields, } from "./paper-settings.js";
 import { referenceRules, REFERENCE_RULE_LEVELS } from "./reference-rules.js";
 import { onlineReferences } from "./adapters/references/index.js";
 import { narrowToOwners, ownedPatterns, ruleOwners, scopeToOwned, } from "./paper-files.js";
-import { paperPreset, paperPresetProblem, } from "./presets.js";
+import { paperPreset, settingsProblemLine, presetProblemText, resolvePreset, shippedPresets, SHIPPED_PREFIX, } from "./presets.js";
 import { mergeRequirements, declaredUnion, requirementsFor, NO_REQUIREMENTS, } from "./tex-requirements.js";
 import { doctor } from "./doctor.js";
-import { init, processInteractivity, askOnTerminal } from "./init.js";
+import { askOnTerminal, askOrDefault, init, processInteractivity, } from "./init.js";
 import { DEFAULT_FORMAT, FORMATS, isFormat, newPaper, reportNewPaper, } from "./new-paper.js";
 // The one source for the consumer's config key lives in the .mjs half of the package (the ESLint
 // rules and the skill scripts import it too); its types are in lib/paper-config.d.mts.
@@ -72,12 +72,14 @@ import reviewFrontmatter from "../eslint-rules/review-frontmatter.mjs";
 import siblingFrontmatter from "../eslint-rules/sibling-frontmatter.mjs";
 // @ts-expect-error — an ESLint rule in .mjs, it has no types
 import pdfRules from "../eslint-rules/pdf-last-page-balance.mjs";
+/** The shipped venue presets, read from the package's venues directory — the one list. */
+const SHIPPED_VENUES = () => shippedPresets(packageVenuesDir());
 const USAGE = `paperlint — machine-checkable gates for a paper kept in git
 
   npx paperlint init [dir]            set the project up: detect the papers directory, declare it
                                       in package.json, link the skills, wire the hooks into
                                       .claude/settings.json, offer the CI step, report what is missing
-  npx paperlint new <name> [--format tex|md]
+  npx paperlint new <name> [--venue <preset>] [--kind <kind>] [--format tex|md]
                                       create <papers>/<name>/ from the template; never overwrites,
                                       on an existing folder adds only the missing files, then lints it
   npx paperlint lint [paths…]         run every rule over your papers
@@ -105,6 +107,15 @@ init:
   --paper <name>      create this paper too (without a human, the only way init creates one)
   --format tex|md     the new paper's source format; default tex
 
+new:
+  --venue <preset>    the venue preset, written as "extends" into the paper's paperlint.json:
+                      a shipped one (${SHIPPED_VENUES().join(", ")}), or a path to your
+                      own preset starting with ./ or ../, relative to where you run the command.
+                      On a terminal without --venue, new asks; "none" leaves it unset
+  --kind <kind>       the paper's kind at that venue (its page limit), e.g. short — one of the
+                      preset's kinds; needs --venue
+  --format tex|md     the paper's source format; default tex
+
 lint:
   npx paperlint lint [paths…] [--fix] [--config <file.json>] [--json]
 
@@ -137,7 +148,7 @@ settings — paperlint.json, at two levels, one schema. Both are optional.
 
     { "extends": "paperlint:aisec", "kind": "research", "rules": { "pdf/last-page-balance": "error" } }
 
-  "extends" names a venue preset: paperlint:<name> (shipped: acm-sigconf, agenticdev, aisec, realm)
+  "extends" names a venue preset: paperlint:<name> (shipped: ${SHIPPED_VENUES().join(", ")})
   or ./path.jsonc, relative to the paperlint.json. npm presets are not supported yet.
 
   "rules" is { "<rule>": "<severity>" } for every paper file in scope, or ESLint flat-config
@@ -260,6 +271,54 @@ export function buildConfig(opts = {}, texLanguage) {
  * config rather than listed again. `@eslint/markdown` is a dependency's plugin, not paperlint's.
  */
 export const SHIPPED_RULES = shippedRuleIds(buildConfig({}, { sentinel: "tex language" }), [markdown]);
+/**
+ * Every plugin paperlint's config registers, ONE object per name, read off that config. In it one
+ * name is bound to different objects in different blocks (`paper` beside `PIPELINE-STATUS.md` is
+ * not `paper` beside `paper.tex`); here their rules are merged, so a config that lints any paper
+ * file knows every rule id. `@eslint/markdown` is a dependency's plugin and is left out. The LaTeX
+ * language rides on `tex` when `texLanguage` is given, and that is how a consumer registers it: a
+ * second `tex` plugin of its own is refused by ESLint ("Cannot redefine plugin "tex"", measured
+ * with and without the language here). Without it, `tex` carries rules only — for a config that
+ * lints markdown papers alone.
+ */
+export function rulePlugins(texLanguage) {
+    const out = {};
+    for (const block of buildConfig({}, texLanguage ?? { sentinel: "tex" }))
+        for (const [name, plugin] of Object.entries(block.plugins ?? {}))
+            if (plugin !== markdown)
+                out[name] = { rules: { ...out[name]?.rules, ...plugin.rules } };
+    if (out["tex"] && texLanguage !== undefined)
+        return {
+            ...out,
+            tex: { ...out["tex"], languages: { latex: texLanguage } },
+        };
+    return out;
+}
+/**
+ * A flat-config fragment for a consumer's OWN ESLint run over paper files (#104): every rule
+ * paperlint ships, registered and turned off. Without it a `% eslint-disable-next-line
+ * paper/leading-zero -- why` — the documented escape hatch — fails that run with "Definition for
+ * rule 'paper/leading-zero' was not found". Off, because `paperlint lint` is where they run.
+ *
+ * The second block is not optional, and it is measured: a directive naming a rule that is off
+ * suppresses nothing, so ESLint reports it as an unused directive (a warning by default, an error
+ * under `reportUnusedDisableDirectives: "error"`). On the files paperlint lints that report is
+ * switched off in THIS run — `paperlint lint` still reports a directive that silences nothing.
+ */
+export function rulesOff(texLanguage) {
+    return [
+        {
+            name: "paperlint/rules-off",
+            plugins: rulePlugins(texLanguage),
+            rules: Object.fromEntries([...SHIPPED_RULES].map((id) => [id, "off"])),
+        },
+        {
+            name: "paperlint/rules-off/directives",
+            files: PAPER_FILE_PATTERNS,
+            linterOptions: { reportUnusedDisableDirectives: "off" },
+        },
+    ];
+}
 /** Whether a rule entry (`"error"`, `2`, `["warn", {…}]`) turns the rule on. */
 const isOn = (entry) => {
     const sev = Array.isArray(entry) ? entry[0] : entry;
@@ -274,18 +333,24 @@ export const OPTIONAL_RULES = new Set([...SHIPPED_RULES].filter((id) => !buildCo
  * 🔴 AN OPTIONAL RULE THAT IS ON AND REACHES NO PAPER IS A GREEN ZERO. A `files` glob that matches
  * nothing — a typo, a path relative to the wrong directory — leaves the rule never invoked, and a
  * rule that never runs reports exactly like a rule that passed. So for every optional rule the
- * consumer turned on, some linted `paper.tex` must actually have it enabled; the ones none has are
+ * consumer turned on, some `paper.tex` must actually have it enabled; the ones none has are
  * returned, for the caller to refuse.
+ *
+ * `files` is every `paper.tex` the guard may count: the ones this run linted AND every paper of the
+ * project. Judged against the run alone, `paperlint lint papers/c` failed on a block written for
+ * papers a and b (#103) — a block that reaches a paper outside this run is not dead. A glob that
+ * reaches no paper of the project at all still fails, from a subset as from the whole.
  */
-export async function silentOptionalRules(eslint, lintedFiles, opts) {
+export async function silentOptionalRules(eslint, files, opts) {
     const turnedOn = new Set((opts.rules ?? []).flatMap((b) => Object.entries(b.rules)
         .filter(([id, e]) => OPTIONAL_RULES.has(id) && isOn(e))
         .map(([id]) => id)));
     const reached = new Set();
-    for (const f of lintedFiles.filter((p) => basename(p) === MAIN)) {
+    for (const f of new Set(files.filter((p) => basename(p) === MAIN))) {
+        // Undefined for a file outside ESLint's cwd or scope: it reaches nothing.
         const cfg = (await eslint.calculateConfigForFile(f));
         for (const id of turnedOn)
-            if (isOn(cfg.rules?.[id]))
+            if (isOn(cfg?.rules?.[id]))
                 reached.add(id);
     }
     return [...turnedOn].filter((id) => !reached.has(id));
@@ -303,8 +368,8 @@ export function paperRuleBlocks(paths) {
     const out = { preset: [], own: [] };
     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 };
+        if (p.kind === "settings-problem")
+            return { ok: false, error: settingsProblemLine(dir, p.problem) };
         const blocks = rulesOfPaper(dir, p);
         if (!blocks.ok)
             return blocks;
@@ -319,7 +384,7 @@ export function paperRuleBlocks(paths) {
  * contributes nothing here; `pdf/profile` reports it on the paper.
  */
 function rulesOfPaper(dir, p) {
-    const settings = "settings" in p ? p.settings : null;
+    const { settings } = p;
     const fromPreset = p.kind === "resolved"
         ? parseRuleEntries(p.preset.rules, `the venue preset ${p.preset.chain.join(" → ")} → "rules"`, SHIPPED_RULES)
         : { ok: true, value: {} };
@@ -332,30 +397,27 @@ function rulesOfPaper(dir, p) {
             : ownRules(dir, settings);
     if (!own.ok)
         return own;
-    const scoped = (rules) => Object.keys(rules).length
-        ? [{ basePath: dir, files: PAPER_FILE_PATTERNS, rules }]
-        : [];
+    // No `files`: `narrowToOwners` scopes the block to what paperlint lints under `dir`, exceptions
+    // included. A copy of the globs here is how the siblings index got parsed as JavaScript (#101).
+    const scoped = (rules) => Object.keys(rules).length ? [{ basePath: dir, rules }] : [];
     return {
         ok: true,
         value: { preset: scoped(fromPreset.value), own: [...own.value] },
     };
 }
-/** A paper's `{ id: severity }` rules, as one block over the paper's files. */
+/** A paper's `{ id: severity }` rules, as one block over the paper's files (narrowed later, #101). */
 function ownRules(dir, settings) {
     const own = paperRules(dir, settings, SHIPPED_RULES);
     if (!own.ok)
         return own;
     return {
         ok: true,
-        value: own.value
-            ? [{ basePath: dir, files: PAPER_FILE_PATTERNS, rules: own.value }]
-            : [],
+        value: own.value ? [{ basePath: dir, rules: own.value }] : [],
     };
 }
 /**
- * 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.
+ * The globs paperlint lints, for the refusal message only. Which files a block reaches is decided by
+ * `narrowToOwners` from `ownedScopes` (src/paper-files.ts), where each glob keeps its exceptions.
  */
 const PAPER_FILE_PATTERNS = ownedPatterns(buildConfig({}, { sentinel: "tex language" }));
 /**
@@ -390,6 +452,8 @@ export function parseSettings(json, where, baseDir) {
  * papers inside the config's directory, that is the config's directory itself.
  */
 const lintRoot = (home, paths) => commonDir([home, ...paths]);
+/** A path as the reader typed it: relative to where the command runs, or whole when it IS there. */
+const shown = (cwd, p) => relative(cwd, p) || p;
 /** The longest shared leading run of path segments. */
 const commonDir = (paths) => {
     const [first = [], ...rest] = paths.map((p) => p.split(sep));
@@ -412,30 +476,47 @@ export function parseArgs(argv) {
         noHooks: false,
         paper: null,
         format: null,
+        venue: null,
+        kind: null,
         hooksMode: null,
         // -1 = warnings NEVER fail the run. In this set most findings are advisory by design, and a
         // gate that fails on advice gets muted entirely.
         maxWarnings: -1,
     };
+    // Consumed from the front: a value flag takes the next argument by shifting it off.
     const rest = [...argv];
-    if (rest[0] && !rest[0].startsWith("-"))
-        out.cmd = rest.shift() ?? null;
+    const first = rest[0];
+    if (first && !first.startsWith("-")) {
+        out.cmd = first;
+        rest.shift();
+    }
     // 🔴 A FLAG WHOSE VALUE WAS TAKEN AWAY IS A REFUSAL, NOT A DEFAULT. The compiler found this
-    // during the move to TypeScript: `rest[++i]` past the last argument gives `undefined`, and
+    // during the move to TypeScript: the value past the last argument is `undefined`, and
     // `paperlint lint --config` (the value forgotten, or eaten by a substitution in CI) silently turned
     // into "no config given" — that is, it went to auto-discovery and linted against SOMEONE ELSE'S
     // file, saying nothing. The failure is one-sided and toward silence, so it is cured by
     // behaviour, not by a type cast.
-    const valueFor = (flag, i) => {
-        const v = rest[i];
+    const valueFor = (flag) => {
+        const v = rest.shift();
         if (v === undefined)
             out.missingValue = flag;
         return v;
     };
-    for (let i = 0; i < rest.length; i++) {
-        const a = rest[i];
-        if (a === undefined)
-            continue;
+    for (let arg = rest.shift(); arg !== undefined; arg = rest.shift()) {
+        // `--flag=value` is `--flag value` for every flag that takes a value: the CI action writes
+        // `--max-warnings="$N"`, and that form used to fall through to the list of paths.
+        const eq = arg.indexOf("=");
+        const inline = arg.startsWith("--") && eq > 0 && VALUE_FLAGS.has(arg.slice(0, eq))
+            ? arg.slice(eq + 1)
+            : undefined;
+        const a = inline === undefined ? arg : arg.slice(0, eq);
+        const take = () => {
+            if (inline === undefined)
+                return valueFor(a);
+            if (inline === "")
+                out.missingValue = a;
+            return inline === "" ? undefined : inline;
+        };
         if (a === "--json")
             out.json = true;
         else if (a === "--fix")
@@ -453,34 +534,51 @@ export function parseArgs(argv) {
         else if (a.startsWith("--hooks="))
             out.hooksMode = a.slice("--hooks=".length);
         else if (a === "--paper")
-            out.paper = valueFor(a, ++i) ?? null;
+            out.paper = take() ?? null;
         else if (a === "--format")
-            out.format = valueFor(a, ++i) ?? null;
+            out.format = take() ?? null;
+        else if (a === "--venue")
+            out.venue = take() ?? null;
+        else if (a === "--kind")
+            out.kind = take() ?? null;
         // `--options` was the first spelling and is kept working. It named the wrong thing — every
         // other tool in the stack calls this file its config — but a flag in someone's CI is not
         // ours to break.
         else if (a === "--config" || a === "--options")
-            out.config = valueFor(a, ++i) ?? null;
+            out.config = take() ?? null;
         else if (a === "--max-warnings") {
-            const v = valueFor(a, ++i);
+            const v = take();
             if (v !== undefined)
                 out.maxWarnings = Number(v);
         }
         else if (a === "--help" || a === "-h")
             out.help = true;
+        // An unknown flag is refused by name. Read as a path, it silently lints something else.
+        else if (a.startsWith("-") && a !== "-")
+            out.unknownFlag ??= a;
         else
             out.paths.push(a);
     }
     return out;
 }
+/** The flags that take a value, in either spelling: `--flag value` or `--flag=value`. */
+const VALUE_FLAGS = new Set([
+    "--paper",
+    "--format",
+    "--venue",
+    "--kind",
+    "--config",
+    "--options",
+    "--max-warnings",
+]);
 /**
  * This package's own version, from the `package.json` beside `src/` and `dist/` alike. `init` pins
  * the CI action to its release tag; an unreadable manifest yields `undefined`, and init then keeps
  * the placeholder instead of guessing.
  */
-function ownVersion() {
+export function ownVersion(readManifest = () => readFileSync(new URL("../package.json", import.meta.url), "utf8")) {
     try {
-        const v = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"))?.version;
+        const v = JSON.parse(readManifest())?.version;
         return typeof v === "string" ? v : undefined;
     }
     catch {
@@ -524,8 +622,9 @@ export function readConfig(a, { log = console.log, err = console.error, cwd = pr
     //
     // 🔴 IN `--json` MODE — TO stderr. Machine output must be ONE parsable document: a line before
     // the array breaks any `| jq`, and it breaks it for the consumer, not for us.
-    (a.json ? err : log)(`config: ${relative(cwd, configPath) || CONFIG_FILE}`);
-    const settings = parseSettings(parsed, relative(cwd, configPath) || CONFIG_FILE, root);
+    const shownPath = shown(cwd, configPath);
+    (a.json ? err : log)(`config: ${shownPath}`);
+    const settings = parseSettings(parsed, shownPath, root);
     if (!settings.ok) {
         err(settings.error);
         return { code: 2 };
@@ -617,16 +716,90 @@ resolve = (spec) => createRequire(import.meta.url).resolve(spec), } = {}) {
  * become two implementations. The lint runs on THAT folder, so the first thing printed after the
  * file list is its verdict rather than the old "missing PIPELINE-STATUS.md".
  */
-export async function createPaperAt(papersRoot, name, format, { log, err, cwd, }) {
-    const result = newPaper(papersRoot, name, format);
-    const here = (p) => relative(cwd, p) || p;
+export async function createPaperAt(papersRoot, name, format, { log, err, cwd, venue = null, }) {
+    const result = newPaper(papersRoot, name, format, { venue });
+    const here = (p) => shown(cwd, p);
     for (const line of reportNewPaper(result, here))
         log(line);
     if (!result.ok)
         return 2;
+    const config = here(join(result.dir, CONFIG_FILE));
+    if (venue === null)
+        log(`  venue: none yet — set "extends" in ${config}, or next time: paperlint new <name> --venue <preset> (${SHIPPED_VENUES().join(", ")})`);
+    else if (venue.kind === null && venue.kinds.length > 0)
+        log(`  kind: not set — \`${venue.label}\` sets a page limit per kind (${venue.kinds.join(", ")}); add "kind" to ${config}. Until then lint reports pdf/profile`);
     log(``);
     return run(["lint", result.dir], { log, err, cwd });
 }
+/**
+ * `--venue` / `--kind` → the `extends` and `kind` to write into `<paperDir>/paperlint.json`, or why
+ * not. Parsed here, at the boundary, and resolved through the same `resolvePreset` lint uses — so a
+ * venue `new` accepts is a venue lint resolves. On a terminal with no `--venue` it asks, with
+ * "none" as the default; without a terminal it chooses nothing (null), as before.
+ *
+ * A path is relative to where the command runs, because that is where it was typed; it is written
+ * relative to the paper's `paperlint.json`, because that is what `extends` is relative to. Written
+ * as typed, `./venues/x.jsonc` would name `<paper>/venues/x.jsonc`.
+ */
+export async function chooseVenue(flags, { paperDir, cwd, interactive, ask, }) {
+    const shipped = SHIPPED_VENUES();
+    if (flags.kind !== null && flags.venue === null)
+        return bad(`--kind needs --venue: a kind is a page limit of one venue preset — \`paperlint new <name> --venue <preset> --kind ${flags.kind}\``);
+    const asked = async (q) => (await askOrDefault(ask, q))?.trim() ?? "";
+    const venue = flags.venue ??
+        (interactive
+            ? await asked(`venue: ${[...shipped, "none"].join(" / ")} [none] `)
+            : "");
+    if (venue === "" || (flags.venue === null && venue === "none"))
+        return { ok: true, value: null };
+    const spec = venueSpec(venue, { shipped, paperDir, cwd });
+    if (!spec.ok)
+        return spec;
+    const r = resolvePreset(spec.value, join(paperDir, CONFIG_FILE), PRESET_DEPS);
+    if (!r.ok)
+        return bad(`--venue ${venue}: ${presetProblemText(r.error)}`);
+    const kinds = [...r.value.format.kinds.keys()];
+    const label = r.value.label;
+    if (flags.kind !== null) {
+        if (kinds.length === 0)
+            return bad(`--kind ${flags.kind}: \`${label}\` has no kinds — it sets no page limit, so there is no kind to choose`);
+        if (!kinds.includes(flags.kind))
+            return bad(`--kind ${flags.kind}: \`${label}\` has no kind \`${flags.kind}\`; its kinds: ${kinds.join(", ")}`);
+    }
+    const kind = flags.kind ??
+        (interactive && kinds.length > 0
+            ? await asked(`kind: ${[...kinds, "later"].join(" / ")} [later] `)
+            : null);
+    return {
+        ok: true,
+        value: {
+            extends: spec.value,
+            kind: kind !== null && kinds.includes(kind) ? kind : null,
+            label,
+            kinds,
+        },
+    };
+}
+const bad = (error) => ({
+    ok: false,
+    error,
+});
+/** What `--venue` names → the `extends` value, relative to `<paperDir>/paperlint.json`. */
+function venueSpec(venue, { shipped, paperDir, cwd, }) {
+    if (venue.startsWith("./") || venue.startsWith("../")) {
+        const file = resolve(cwd, venue);
+        if (!existsSync(file))
+            return bad(`--venue ${venue}: no such file (${file}) — a path is relative to where you run the command`);
+        const rel = relative(paperDir, file).split(sep).join("/");
+        return { ok: true, value: rel.startsWith("../") ? rel : `./${rel}` };
+    }
+    const name = venue.startsWith(SHIPPED_PREFIX)
+        ? venue.slice(SHIPPED_PREFIX.length)
+        : venue;
+    if (!shipped.includes(name))
+        return bad(`--venue ${venue}: no such venue preset. Shipped: ${shipped.join(", ")} — or a path to your own preset, starting with ./ or ../`);
+    return { ok: true, value: `${SHIPPED_PREFIX}${name}` };
+}
 /**
  * `paperlint new <name>` — the papers directory comes from the same declaration every other command
  * reads; there is no second way to name it. See `new-paper.ts` for what it writes and why.
@@ -634,7 +807,7 @@ export async function createPaperAt(papersRoot, name, format, { log, err, cwd, }
 async function runNew(a, { log, err, cwd, ask = askOnTerminal, }) {
     const [name, ...extra] = a.paths;
     if (!name || extra.length > 0) {
-        err(`\`new\` takes exactly one paper name: \`paperlint new my-paper [--format tex|md]\``);
+        err(`\`new\` takes exactly one paper name: \`paperlint new my-paper [--venue <preset>] [--kind <kind>] [--format tex|md]\``);
         return 2;
     }
     let format = DEFAULT_FORMAT;
@@ -646,9 +819,9 @@ async function runNew(a, { log, err, cwd, ask = askOnTerminal, }) {
         format = a.format;
     }
     else if (processInteractivity(a.yes).interactive) {
-        const f = await ask(`format: tex / md [${DEFAULT_FORMAT}] `).catch(() => "");
-        if (isFormat(f.trim()))
-            format = f.trim();
+        const f = (await askOrDefault(ask, `format: tex / md [${DEFAULT_FORMAT}] `))?.trim();
+        if (isFormat(f))
+            format = f;
     }
     const cfg = readConfig({ ...a, json: false }, { log: () => { }, err, cwd });
     if (cfg.code !== undefined)
@@ -660,8 +833,30 @@ async function runNew(a, { log, err, cwd, ask = askOnTerminal, }) {
         return 2;
     }
     if (roots.length > 1)
-        log(`several papers directories are declared — using the first: ${relative(cwd, papersRoot) || papersRoot}`);
-    return createPaperAt(papersRoot, name, format, { log, err, cwd });
+        log(`several papers directories are declared — using the first: ${shown(cwd, papersRoot)}`);
+    const paperDir = join(papersRoot, name);
+    // An existing paperlint.json is never overwritten, so a venue for it is refused, not dropped.
+    const hasConfig = existsSync(join(paperDir, CONFIG_FILE));
+    if (hasConfig && (a.venue !== null || a.kind !== null)) {
+        err(`${relative(cwd, join(paperDir, CONFIG_FILE))} already exists and is never overwritten — set "extends" and "kind" in it by hand`);
+        return 2;
+    }
+    const venue = hasConfig
+        ? { ok: true, value: null }
+        : await chooseVenue(a, {
+            paperDir,
+            cwd,
+            interactive: processInteractivity(a.yes).interactive,
+            ask,
+        });
+    if (!venue.ok)
+        return (err(venue.error), 2);
+    return createPaperAt(papersRoot, name, format, {
+        log,
+        err,
+        cwd,
+        venue: venue.value,
+    });
 }
 /**
  * 🔴 THE TARGET IS NAMED, "EVERYTHING" IS AN OPTION. That is how it is for everyone whose build is
@@ -670,7 +865,7 @@ async function runNew(a, { log, err, cwd, ask = askOnTerminal, }) {
  * everything" on a corpus of five papers is twenty pdflatex runs instead of one, and almost never
  * what was wanted.
  */
-async function runBuild(a, { log, err, cwd, }) {
+async function runBuild(a, { log, err, cwd, checkReferences, }) {
     const cfg = readConfig(a, { log, err, cwd });
     if (cfg.code !== undefined)
         return cfg.code;
@@ -698,7 +893,7 @@ async function runBuild(a, { log, err, cwd, }) {
         cwd,
         dryRun: a.dryRun,
         log,
-        checkReferences: onlineReferences,
+        checkReferences,
         engine: () => engineEnv(targets, a, { log, err }),
     });
     if (out.kind === "no-engine")
@@ -782,6 +977,33 @@ function hostBanalInstaller() {
     });
     return banalInstaller({ ...ports, download }, s);
 }
+/**
+ * init's TeX Live step: whether paperlint's own tree is installed, and how to install it —
+ * `runToolchain` over what this project's papers need. `toolchain` is the seam a test replaces:
+ * the real one downloads ~270 MB.
+ */
+export function initTexLive(a, { log, err, cwd, }, toolchain = runToolchain) {
+    return {
+        installed: () => cachedTree(cacheRoot(process.env)) !== null,
+        install: () => toolchain({
+            check: false,
+            log,
+            err,
+            banal: hostBanalInstaller(),
+            tex: toolchainTex(resolve(cwd, a.paths[0] ?? ".")),
+        }),
+    };
+}
+/**
+ * The first papers directory the CLI would lint from `cwd`, or null when the config does not read
+ * or names none — what `doctor` (and `init`, through it) compares the hooks' directory against.
+ */
+function cliPapers(a, cwd) {
+    const read = readConfig(a, { log: () => { }, err: () => { }, cwd });
+    return read.code === undefined
+        ? (toPaths(papersDirOf(read.opts))[0] ?? null)
+        : null;
+}
 /** `paperlint init`: its flags checked here, the install itself in `init.ts`. */
 async function runInit(a, { log, err, cwd, }) {
     // Deferred, not implemented: named and refused, rather than read as the directory argument.
@@ -804,25 +1026,11 @@ async function runInit(a, { log, err, cwd, }) {
         paper: a.paper,
         format: isFormat(a.format) ? a.format : null,
         createPaper: (papersRoot, name, format) => createPaperAt(papersRoot, name, format, { log, err, cwd }),
-        tex: {
-            installed: () => cachedTree(cacheRoot(process.env)) !== null,
-            install: () => runToolchain({
-                check: false,
-                log,
-                err,
-                banal: hostBanalInstaller(),
-                tex: toolchainTex(resolve(cwd, a.paths[0] ?? ".")),
-            }),
-        },
-        resolveCliPapers: (root) => {
-            const read = readConfig({ ...a, config: null }, { log: () => { }, err: () => { }, cwd: root });
-            return read.code === undefined
-                ? (toPaths(papersDirOf(read.opts))[0] ?? null)
-                : null;
-        },
+        tex: initTexLive(a, { log, err, cwd }),
+        resolveCliPapers: (root) => cliPapers({ ...a, config: null }, root),
     });
 }
-export async function run(argv, { log = console.log, err = console.error, cwd = process.cwd(), } = {}) {
+export async function run(argv, { log = console.log, err = console.error, cwd = process.cwd(), checkReferences = onlineReferences, } = {}) {
     const a = parseArgs(argv);
     // The refusal must come FIRST: behind a flag without a value there is usually a typo, or a
     // substitution in CI that collapsed into nothing, and any continuation works on something other
@@ -833,6 +1041,10 @@ export async function run(argv, { log = console.log, err = console.error, cwd =
             `not what the command line said.`);
         return 2;
     }
+    if (a.unknownFlag !== undefined) {
+        err(`unknown flag \`${a.unknownFlag}\` — \`paperlint --help\` lists every flag`);
+        return 2;
+    }
     if (a.help || !a.cmd) {
         log(USAGE);
         return a.help ? 0 : 2;
@@ -846,10 +1058,7 @@ export async function run(argv, { log = console.log, err = console.error, cwd =
     // broken is precisely its job. So a failed read becomes "the CLI would lint nothing", which is
     // what it prints, rather than an early exit that tells the reader nothing about the hooks.
     if (a.cmd === "doctor") {
-        const read = readConfig(a, { log: () => { }, err: () => { }, cwd });
-        const papers = read.code === undefined
-            ? (toPaths(papersDirOf(read.opts))[0] ?? null)
-            : null;
+        const papers = cliPapers(a, cwd);
         return doctor({
             log,
             cwd,
@@ -859,7 +1068,7 @@ export async function run(argv, { log = console.log, err = console.error, cwd =
     }
     const simple = SIMPLE[a.cmd];
     if (simple)
-        return await simple(a, { log, err, cwd });
+        return await simple(a, { log, err, cwd, checkReferences });
     if (a.cmd === "check")
         err(`\`check\` is now \`lint\` — running it anyway. Update the call to \`paperlint lint\`.`);
     if (a.cmd !== "lint" && a.cmd !== "check") {
@@ -908,14 +1117,16 @@ export async function run(argv, { log = console.log, err = console.error, cwd =
         ...opts,
         rules: [...papers.value.preset, ...(opts.rules ?? []), ...papers.value.own],
     };
+    // Loaded lazily because only `lint` needs it. If the module cannot be loaded (a broken install:
+    // the file missing from the package), lint still runs over the markdown papers rather than
+    // failing outright — the LaTeX rules simply have no language to run in.
     let texLanguage = null;
     try {
-        // @ts-expect-error — the module is .mjs and has no types; a missing LaTeX parser is a normal
-        // case here, it is caught by the catch below.
+        // @ts-expect-error — the module is .mjs and has no types
         ({ texLanguage } = await import("../eslint-rules/latex-language.mjs"));
     }
     catch {
-        /* without a LaTeX parser we work over markdown */
+        texLanguage = null;
     }
     const eslint = new ESLint({
         cwd: lintRoot(root, paths),
@@ -925,7 +1136,7 @@ export async function run(argv, { log = console.log, err = console.error, cwd =
     });
     const unowned = await firstUnownedFile(eslint, paths);
     if (unowned !== null) {
-        err(`${relative(cwd, unowned) || unowned} is not a file paperlint lints — it lints ${PAPER_FILE_PATTERNS.join(", ")}`);
+        err(`${shown(cwd, unowned)} is not a file paperlint lints — it lints ${PAPER_FILE_PATTERNS.join(", ")}`);
         return 2;
     }
     // 🔴 ESLint THROWS on an empty set (`NoFilesFoundError`) — the guard below simply never got
@@ -951,7 +1162,7 @@ export async function run(argv, { log = console.log, err = console.error, cwd =
     // indistinguishable from "not a single rule got a single file". A rule whose glob did not match
     // is not invoked — and, not being invoked, it physically cannot report that.
     if (results.length === 0) {
-        err(`nothing was linted under ${paths.map((x) => relative(cwd, x) || x).join(", ")} — no PIPELINE-STATUS.md, paper.md/tex or reviews/ found there. A clean report over zero files is not a clean report.`);
+        err(`nothing was linted under ${paths.map((x) => shown(cwd, x)).join(", ")} — no PIPELINE-STATUS.md, paper.md/tex or reviews/ found there. A clean report over zero files is not a clean report.`);
         return 1;
     }
     return await reportLint(eslint, results, structure, {
@@ -960,6 +1171,11 @@ export async function run(argv, { log = console.log, err = console.error, cwd =
         err,
         where: relative(cwd, root) || ".",
         opts: withPapers,
+        // Every paper of the project, not only the ones on the command line (#103).
+        projectPapers: papersRoots(cfg)
+            .flatMap((r) => papersIn(r))
+            .map((d) => join(d, MAIN))
+            .filter((f) => existsSync(f)),
     });
 }
 /**
@@ -985,7 +1201,7 @@ const isEmptySet = (e) => {
     const fail = e;
     return (fail?.messageTemplate === "file-not-found" ||
         fail?.messageTemplate === "all-matched-files-ignored" ||
-        /No files matching/i.test(fail?.message ?? ""));
+        /No files matching/i.test(String(fail?.message)));
 };
 /**
  * The end of `paperlint lint`: refuse an optional rule that reached no paper, print the findings, and
@@ -993,10 +1209,10 @@ const isEmptySet = (e) => {
  */
 async function reportLint(eslint, 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any -- #49: replace with a real type
-results, structure, { a, log, err, where, opts, }) {
-    const silent = await silentOptionalRules(eslint, results.map((r) => r.filePath), opts);
+results, structure, { a, log, err, where, opts, projectPapers, }) {
+    const silent = await silentOptionalRules(eslint, [...results.map((r) => r.filePath), ...projectPapers], opts);
     if (silent.length > 0) {
-        err(`${silent.join(", ")} is turned on in "rules", but no linted paper.tex gets it — check the block's ` +
+        err(`${silent.join(", ")} is turned on in "rules", but no paper.tex of the project gets it — check the block's ` +
             `"files" (relative to ${where}). A rule that never runs reports exactly like a rule that passed.`);
         return 1;
     }