paperlint 3.0.0 → 3.1.1

package/src/cli.ts

@@ -56,6 +56,7 @@ import {
 } from "./paper-settings.ts";
 import { referenceRules, REFERENCE_RULE_LEVELS } from "./reference-rules.ts";
 import { onlineReferences } from "./adapters/references/index.ts";
+import type { CheckReferences } from "./ports/check-references.ts";
 import {
   narrowToOwners,
   ownedPatterns,
@@ -64,7 +65,11 @@ import {
 } from "./paper-files.ts";
 import {
   paperPreset,
-  paperPresetProblem,
+  settingsProblemLine,
+  presetProblemText,
+  resolvePreset,
+  shippedPresets,
+  SHIPPED_PREFIX,
   type PaperPreset,
 } from "./presets.ts";
 import type { ToolInstaller } from "./ports/tool-installer.ts";
@@ -76,7 +81,12 @@ import {
   type TexRequirements,
 } from "./tex-requirements.ts";
 import { doctor } from "./doctor.ts";
-import { init, processInteractivity, askOnTerminal } from "./init.ts";
+import {
+  askOnTerminal,
+  askOrDefault,
+  init,
+  processInteractivity,
+} from "./init.ts";
 import {
   DEFAULT_FORMAT,
   FORMATS,
@@ -84,6 +94,7 @@ import {
   newPaper,
   reportNewPaper,
   type PaperFormat,
+  type VenueSetting,
 } from "./new-paper.ts";
 // 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.
@@ -123,12 +134,15 @@ 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 = (): string[] => 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
@@ -156,6 +170,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]
 
@@ -188,7 +211,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
@@ -322,6 +345,64 @@ export const SHIPPED_RULES: ReadonlySet<string> = shippedRuleIds(
   [markdown],
 );
 
+/** A plugin as `rulePlugins` gives it: its rules, and for `tex` the LaTeX language when given. */
+export interface RulePlugin {
+  readonly rules?: Readonly<Record<string, unknown>>;
+  readonly languages?: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * 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?: unknown): Record<string, RulePlugin> {
+  const out: Record<string, { rules: Record<string, unknown> }> = {};
+  for (const block of buildConfig({}, texLanguage ?? { sentinel: "tex" }))
+    for (const [name, plugin] of Object.entries(
+      (block as { plugins?: Record<string, RulePlugin> }).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?: unknown): Linter.Config[] {
+  return [
+    {
+      name: "paperlint/rules-off",
+      plugins: rulePlugins(texLanguage) as Linter.Config["plugins"],
+      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: unknown): boolean => {
   const sev = Array.isArray(entry) ? entry[0] : entry;
@@ -345,12 +426,17 @@ export const OPTIONAL_RULES: ReadonlySet<string> = new Set(
  * 🔴 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: ESLint,
-  lintedFiles: readonly string[],
+  files: readonly string[],
   opts: PaperlintConfig,
 ): Promise<string[]> {
   const turnedOn = new Set(
@@ -361,11 +447,11 @@ export async function silentOptionalRules(
     ),
   );
   const reached = new Set<string>();
-  for (const f of lintedFiles.filter((p) => basename(p) === MAIN)) {
-    const cfg = (await eslint.calculateConfigForFile(f)) as {
-      rules?: Record<string, unknown>;
-    };
-    for (const id of turnedOn) if (isOn(cfg.rules?.[id])) reached.add(id);
+  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)) as
+      { rules?: Record<string, unknown> } | undefined;
+    for (const id of turnedOn) if (isOn(cfg?.rules?.[id])) reached.add(id);
   }
   return [...turnedOn].filter((id) => !reached.has(id));
 }
@@ -387,8 +473,8 @@ export function paperRuleBlocks(
   const out = { preset: [] as RuleBlock[], own: [] as 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 };
+    if (p.kind === "settings-problem")
+      return { ok: false, error: settingsProblemLine(dir, p.problem) };
     const blocks = rulesOfPaper(dir, p);
     if (!blocks.ok) return blocks;
     out.preset.push(...blocks.value.preset);
@@ -404,9 +490,9 @@ export function paperRuleBlocks(
  */
 function rulesOfPaper(
   dir: string,
-  p: PaperPreset,
+  p: Exclude<PaperPreset, { kind: "settings-problem" }>,
 ): Parsed<{ preset: RuleBlock[]; own: RuleBlock[] }> {
-  const settings = "settings" in p ? p.settings : null;
+  const { settings } = p;
   const fromPreset =
     p.kind === "resolved"
       ? parseRuleEntries(
@@ -428,17 +514,17 @@ function rulesOfPaper(
           )
         : ownRules(dir, settings);
   if (!own.ok) return own;
+  // 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: Record<string, RuleEntry>): RuleBlock[] =>
-    Object.keys(rules).length
-      ? [{ basePath: dir, files: PAPER_FILE_PATTERNS, 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: string,
   settings: PaperSettings,
@@ -447,16 +533,13 @@ function ownRules(
   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: string[] = ownedPatterns(
   buildConfig({}, { sentinel: "tex language" }),
@@ -500,6 +583,9 @@ export function parseSettings(
 const lintRoot = (home: string, paths: readonly string[]): string =>
   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: string, p: string): string => relative(cwd, p) || p;
+
 /** The longest shared leading run of path segments. */
 const commonDir = (paths: readonly string[]): string => {
   const [first = [], ...rest] = paths.map((p) => p.split(sep));
@@ -525,29 +611,47 @@ export function parseArgs(argv: readonly string[]): Args {
     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: string, i: number): string | undefined => {
-    const v = rest[i];
+  const valueFor = (flag: string): string | undefined => {
+    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 = (): string | undefined => {
+      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") out.fix = true;
     else if (a === "--all") out.all = true;
@@ -557,32 +661,47 @@ export function parseArgs(argv: readonly string[]): Args {
     else if (a === "--no-hooks") out.noHooks = true;
     else if (a.startsWith("--hooks="))
       out.hooksMode = a.slice("--hooks=".length);
-    else if (a === "--paper") out.paper = valueFor(a, ++i) ?? null;
-    else if (a === "--format") out.format = valueFor(a, ++i) ?? null;
+    else if (a === "--paper") out.paper = take() ?? null;
+    else if (a === "--format") 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;
+    else if (a === "--config" || a === "--options") 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: ReadonlySet<string> = 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(): string | undefined {
+export function ownVersion(
+  readManifest: () => string = () =>
+    readFileSync(new URL("../package.json", import.meta.url), "utf8"),
+): string | undefined {
   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 {
     return undefined;
@@ -636,12 +755,9 @@ export function readConfig(
   //
   // 🔴 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 };
@@ -769,16 +885,143 @@ export async function createPaperAt(
     log,
     err,
     cwd,
-  }: { log: typeof console.log; err: typeof console.error; cwd: string },
+    venue = null,
+  }: {
+    log: typeof console.log;
+    err: typeof console.error;
+    cwd: string;
+    /** What `--venue` chose; null writes the template's `paperlint.json` as it is. */
+    venue?: VenueChoice | null;
+  },
 ): Promise<number> {
-  const result = newPaper(papersRoot, name, format);
-  const here = (p: string): string => relative(cwd, p) || p;
+  const result = newPaper(papersRoot, name, format, { venue });
+  const here = (p: string): string => 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 });
 }
 
+/** A venue `paperlint new` will write, with what the messages need to say about it. */
+export interface VenueChoice extends VenueSetting {
+  /** The preset's word in messages (`agenticdev`, `my-workshop`). */
+  readonly label: string;
+  /** The preset's kinds; empty when it sets no page limit. */
+  readonly kinds: readonly string[];
+}
+
+/**
+ * `--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: { readonly venue: string | null; readonly kind: string | null },
+  {
+    paperDir,
+    cwd,
+    interactive,
+    ask,
+  }: {
+    paperDir: string;
+    cwd: string;
+    interactive: boolean;
+    ask: (q: string) => Promise<string>;
+  },
+): Promise<Parsed<VenueChoice | null>> {
+  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: string): Promise<string> =>
+    (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: string): { ok: false; error: string } => ({
+  ok: false,
+  error,
+});
+
+/** What `--venue` names → the `extends` value, relative to `<paperDir>/paperlint.json`. */
+function venueSpec(
+  venue: string,
+  {
+    shipped,
+    paperDir,
+    cwd,
+  }: { shipped: readonly string[]; paperDir: string; cwd: string },
+): Parsed<string> {
+  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.
@@ -800,7 +1043,7 @@ async function runNew(
   const [name, ...extra] = a.paths;
   if (!name || extra.length > 0) {
     err(
-      `\`new\` takes exactly one paper name: \`paperlint new my-paper [--format tex|md]\``,
+      `\`new\` takes exactly one paper name: \`paperlint new my-paper [--venue <preset>] [--kind <kind>] [--format tex|md]\``,
     );
     return 2;
   }
@@ -814,10 +1057,10 @@ async function runNew(
     }
     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() as PaperFormat;
+    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) return cfg.code;
@@ -831,9 +1074,32 @@ async function runNew(
   }
   if (roots.length > 1)
     log(
-      `several papers directories are declared — using the first: ${relative(cwd, papersRoot) || papersRoot}`,
+      `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 createPaperAt(papersRoot, name, format, { log, err, cwd });
+    return 2;
+  }
+  const venue = hasConfig
+    ? { ok: true as const, 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,
+  });
 }
 
 /**
@@ -849,7 +1115,13 @@ async function runBuild(
     log,
     err,
     cwd,
-  }: { log: typeof console.log; err: typeof console.error; cwd: string },
+    checkReferences,
+  }: {
+    log: typeof console.log;
+    err: typeof console.error;
+    cwd: string;
+    checkReferences: CheckReferences;
+  },
 ): Promise<number> {
   const cfg = readConfig(a, { log, err, cwd });
   if (cfg.code !== undefined) return cfg.code;
@@ -881,7 +1153,7 @@ async function runBuild(
     cwd,
     dryRun: a.dryRun,
     log,
-    checkReferences: onlineReferences,
+    checkReferences,
     engine: () => engineEnv(targets, a, { log, err }),
   });
   if (out.kind === "no-engine") return 1;
@@ -953,7 +1225,12 @@ const SIMPLE: Readonly<
     string,
     (
       a: Args,
-      io: { log: typeof console.log; err: typeof console.error; cwd: string },
+      io: {
+        log: typeof console.log;
+        err: typeof console.error;
+        cwd: string;
+        checkReferences: CheckReferences;
+      },
     ) => number | Promise<number>
   >
 > = {
@@ -982,6 +1259,44 @@ function hostBanalInstaller(): ToolInstaller {
   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: Args,
+  {
+    log,
+    err,
+    cwd,
+  }: { log: typeof console.log; err: typeof console.error; cwd: string },
+  toolchain: typeof runToolchain = runToolchain,
+): { readonly installed: () => boolean; readonly install: () => number } {
+  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: Args, cwd: string): string | null {
+  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: Args,
@@ -1014,26 +1329,9 @@ async function runInit(
     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: string): string | null => {
-      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: string): string | null =>
+      cliPapers({ ...a, config: null }, root),
   });
 }
 
@@ -1043,10 +1341,16 @@ export async function run(
     log = console.log,
     err = console.error,
     cwd = process.cwd(),
+    checkReferences = onlineReferences,
   }: {
     log?: typeof console.log;
     err?: typeof console.error;
     cwd?: string;
+    /**
+     * `build`'s online reference check — the real services by default. The e2e build passes a
+     * fake: no test depends on Crossref, Semantic Scholar or DBLP answering.
+     */
+    checkReferences?: CheckReferences;
   } = {},
 ): Promise<number> {
   const a = parseArgs(argv);
@@ -1061,6 +1365,12 @@ export async function run(
     );
     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;
@@ -1073,11 +1383,7 @@ export async function run(
   // 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,
@@ -1086,7 +1392,7 @@ export async function run(
     });
   }
   const simple = SIMPLE[a.cmd];
-  if (simple) return await simple(a, { log, err, cwd });
+  if (simple) 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\`.`,
@@ -1142,13 +1448,15 @@ export async function run(
     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: unknown = 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({
@@ -1161,7 +1469,7 @@ export async function run(
   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(", ")}`,
+      `${shown(cwd, unowned)} is not a file paperlint lints — it lints ${PAPER_FILE_PATTERNS.join(", ")}`,
     );
     return 2;
   }
@@ -1188,7 +1496,7 @@ export async function run(
   // 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.`,
+      `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;
   }
@@ -1199,6 +1507,11 @@ export async function run(
     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)),
   });
 }
 
@@ -1232,7 +1545,7 @@ const isEmptySet = (e: unknown): boolean => {
   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))
   );
 };
 
@@ -1251,22 +1564,24 @@ async function reportLint(
     err,
     where,
     opts,
+    projectPapers,
   }: {
     a: Args;
     log: typeof console.log;
     err: typeof console.error;
     where: string;
     opts: PaperlintConfig;
+    projectPapers: readonly string[];
   },
 ): Promise<number> {
   const silent = await silentOptionalRules(
     eslint,
-    results.map((r) => r.filePath),
+    [...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 ` +
+      `${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;