paperlint 3.0.0 → 3.1.0

package/src/paper-files.ts

@@ -24,6 +24,14 @@
  *    per owner and its `files` ANDed with the owner's (ESLint's nested-array form), so a rule can
  *    only land where its plugin is registered.
  *
+ * Both read ONE definition of "the files paperlint lints": `ownedScopes`, each own block's `files`
+ * together with its `ignores`. The globs alone are not that definition. The sibling-card block
+ * claims every markdown file under `siblings/` EXCEPT the index, and a rule whose plugin is
+ * registered for every file (`pdf`) used to keep the consumer block's `files` as they were — so a
+ * venue preset's rules reached `siblings/README.md`, a block with no `language` matched it, and
+ * ESLint parsed the markdown as JavaScript (#101). Now every generated block narrows to scopes,
+ * exceptions included, and a plugin registered everywhere owns exactly what paperlint lints.
+ *
  * ESLint's semantics that this leans on, each measured against ESLint 10 before writing it:
  * - a global-ignore pattern that matches a DIRECTORY hides everything inside it, so directories
  *   must be un-ignored (`!` + a pattern ending in a slash) before owned files can be;
@@ -37,11 +45,21 @@ import type { RuleBlock, RuleEntry } from "./rules-config.ts";
 /** What this module reads of a config block. */
 interface Block {
   readonly files?: readonly unknown[];
+  readonly ignores?: readonly unknown[];
   readonly plugins?: Readonly<
     Record<string, { readonly rules?: Readonly<Record<string, unknown>> }>
   >;
 }
 
+/**
+ * A set of files paperlint lints: an own block's globs and the exceptions that block makes. A file is
+ * in it when it matches one of `files` and none of `ignores`.
+ */
+export interface OwnedScope {
+  readonly files: readonly string[];
+  readonly ignores: readonly string[];
+}
+
 /** A `files` entry: one glob, or several that must ALL match. */
 export type FilesEntry = string | readonly string[];
 
@@ -56,9 +74,42 @@ export interface ScopedBlock {
 const globsOf = (b: Block): string[] =>
   (b.files ?? []).filter((f): f is string => typeof f === "string");
 
+const stringsOf = (xs: readonly unknown[] | undefined): string[] =>
+  (xs ?? []).filter((x): x is string => typeof x === "string");
+
+/**
+ * Scopes with the same exceptions, merged into one: their globs united, once, in order. Keeps a
+ * generated block per distinct set of exceptions rather than one per own block.
+ */
+const merged = (scopes: readonly OwnedScope[]): OwnedScope[] => {
+  const byIgnores = new Map<string, OwnedScope>();
+  for (const s of scopes) {
+    const key = JSON.stringify(s.ignores);
+    const had = byIgnores.get(key);
+    byIgnores.set(key, {
+      files: [...new Set([...(had?.files ?? []), ...s.files])],
+      ignores: s.ignores,
+    });
+  }
+  return [...byIgnores.values()];
+};
+
+/**
+ * THE FILES PAPERLINT LINTS: every own block that names `files`, with its `ignores`. A block without
+ * `files` (a global ignore, or the block registering `pdf` for every file) claims nothing.
+ */
+export function ownedScopes(own: readonly unknown[]): OwnedScope[] {
+  return merged(
+    own
+      .map((raw) => raw as Block)
+      .filter((b) => b.files !== undefined)
+      .map((b) => ({ files: globsOf(b), ignores: stringsOf(b.ignores) })),
+  );
+}
+
 /** Every glob paperlint's own blocks lint, once, in config order. */
 export function ownedPatterns(own: readonly unknown[]): string[] {
-  return [...new Set(own.flatMap((b) => globsOf(b as Block)))];
+  return [...new Set(ownedScopes(own).flatMap((s) => s.files))];
 }
 
 /** ESLint's default ignores, re-applied after directories are un-ignored. */
@@ -84,40 +135,37 @@ const ruleIdsOf = (b: Block): string[] =>
     Object.keys(plugin.rules ?? {}).map((rule) => `${name}/${rule}`),
   );
 
-/** An owner seen so far, widened by one more block's globs; `null` (every file) absorbs all. */
-const widen = (
-  had: readonly string[] | null | undefined,
-  files: readonly string[] | null,
-): readonly string[] | null =>
-  had === null || files === null
-    ? null
-    : [...new Set([...(had ?? []), ...files])];
-
 /**
- * Rule id → the globs of the blocks that register its plugin with that rule. `null`: the plugin
- * is registered for every file (a block without `files`), so the rule resolves anywhere.
+ * Rule id → the scopes of the blocks that register its plugin with that rule. A plugin registered
+ * for every file (a block without `files`) owns every scope — everything paperlint lints, and not
+ * one file more.
  */
 export function ruleOwners(
   own: readonly unknown[],
-): Map<string, readonly string[] | null> {
-  const owners = new Map<string, readonly string[] | null>();
+): Map<string, readonly OwnedScope[]> {
+  const all = ownedScopes(own);
+  const found = new Map<string, OwnedScope[]>();
   for (const raw of own) {
     const b = raw as Block;
-    const files = b.files ? globsOf(b) : null;
-    for (const id of ruleIdsOf(b)) owners.set(id, widen(owners.get(id), files));
+    const scopes =
+      b.files === undefined
+        ? all
+        : [{ files: globsOf(b), ignores: stringsOf(b.ignores) }];
+    for (const id of ruleIdsOf(b))
+      found.set(id, [...(found.get(id) ?? []), ...scopes]);
   }
-  return owners;
+  return new Map([...found].map(([id, scopes]) => [id, merged(scopes)]));
 }
 
 /**
- * One consumer block → one block per owner, each carrying only that owner's rules, its `files`
- * ANDed with the owner's globs. A rule no block of this config registers (the LaTeX block is
- * absent when its parser did not load) gets no block: it has no file to reach in this run, and
- * naming it to ESLint would only crash.
+ * One consumer block → one block per owner scope, each carrying only that owner's rules, its `files`
+ * ANDed with the scope's globs and its `ignores` joined by the scope's exceptions. A rule no block
+ * of this config registers (the LaTeX block is absent when its parser did not load) gets no block:
+ * it has no file to reach in this run, and naming it to ESLint would only crash.
  */
 export function narrowToOwners(
   block: RuleBlock,
-  owners: ReadonlyMap<string, readonly string[] | null>,
+  owners: ReadonlyMap<string, readonly OwnedScope[]>,
 ): ScopedBlock[] {
   const groups = new Map<string, Record<string, RuleEntry>>();
   for (const [id, entry] of Object.entries(block.rules)) {
@@ -126,19 +174,27 @@ export function narrowToOwners(
     const key = JSON.stringify(owner);
     groups.set(key, { ...groups.get(key), [id]: entry });
   }
-  return [...groups].map(([key, rules]) => {
-    const owner = JSON.parse(key) as string[] | null;
-    const files: readonly FilesEntry[] | undefined =
-      owner === null
-        ? block.files
-        : block.files
-          ? block.files.flatMap((f) => owner.map((o) => [f, o]))
-          : owner;
-    return {
-      basePath: block.basePath,
-      ...(files ? { files } : {}),
-      ...(block.ignores ? { ignores: block.ignores } : {}),
-      rules,
-    };
-  });
+  return [...groups].flatMap(([key, rules]) =>
+    (JSON.parse(key) as OwnedScope[]).map((scope) =>
+      within(block, scope, rules),
+    ),
+  );
+}
+
+/** `block`'s rules over the files both it and `scope` claim, minus both sets of exceptions. */
+function within(
+  block: RuleBlock,
+  scope: OwnedScope,
+  rules: Readonly<Record<string, RuleEntry>>,
+): ScopedBlock {
+  const files: readonly FilesEntry[] = block.files
+    ? block.files.flatMap((f) => scope.files.map((o) => [f, o]))
+    : scope.files;
+  const ignores = [...(block.ignores ?? []), ...scope.ignores];
+  return {
+    basePath: block.basePath,
+    files,
+    ...(ignores.length ? { ignores } : {}),
+    rules,
+  };
 }

package/src/paper-settings-commands.test.ts

@@ -42,10 +42,11 @@ function project(files: Record<string, string> = {}): string {
 
 async function lint(
   root: string,
+  args: string[] = [],
 ): Promise<{ code: number; out: string; err: string }> {
   const out: string[] = [];
   const err: string[] = [];
-  const code = await run(["lint", "--json"], {
+  const code = await run(["lint", "--json", ...args], {
     cwd: root,
     log: (s: string) => out.push(s),
     err: (s: string) => err.push(s),
@@ -58,6 +59,43 @@ const rulesIn = (stdout: string, paper: string): string[] =>
     .filter((r) => r.filePath.endsWith(join(paper, "paper.tex")))
     .flatMap((r) => r.messages.map((m) => m.ruleId));
 
+describe("🔴 an optional rule that reaches no paper — judged against the PROJECT, not the run (#103)", () => {
+  const THIRD = {
+    "papers/c/paper.tex":
+      "\\documentclass{article}\n\\begin{document}x\\end{document}\n",
+    "papers/c/PIPELINE-STATUS.md": "---\nstages: []\n---\n",
+  };
+  const rootRules = (files: string[]) => ({
+    "paperlint.json": JSON.stringify({
+      rules: [{ files, rules: { "pdf/last-page-balance": "error" } }],
+    }),
+  });
+
+  it("linting paper c alone passes when the block reaches papers a and b", async () => {
+    const root = project({
+      ...THIRD,
+      ...rootRules(["papers/a/**", "papers/b/**"]),
+    });
+    const r = await lint(root, ["papers/c"]);
+    // Guards: the defect — the guard counted only the paper.tex files this run linted.
+    expect(r.err).not.toMatch(/no linted paper\.tex gets it/);
+    expect(r.code).toBe(0);
+    expect(rulesIn(r.out, "c")).not.toContain("pdf/last-page-balance");
+  });
+
+  it("…and a glob that reaches no paper of the project still fails, from a subset too", async () => {
+    const root = project({ ...THIRD, ...rootRules(["papers/typo/**"]) });
+    for (const args of [["papers/c"], []]) {
+      const r = await lint(root, args);
+      // Guards: the other half — widening the judged set did not turn the guard off.
+      expect(r.err).toMatch(
+        /pdf\/last-page-balance is turned on in "rules", but no paper\.tex/,
+      );
+      expect(r.code).toBe(1);
+    }
+  });
+});
+
 describe("paperlint lint — `rules` in a paper's paperlint.json", () => {
   it("turns an optional rule on for that paper alone", async () => {
     const root = project({
@@ -177,11 +215,9 @@ describe("paperlint lint — the venue preset's rules", () => {
     expect(cfgOf.ok && cfgOf.value).toEqual({
       preset: [
         {
+          // Scoped to the paper by `basePath` alone: which of its files the rule reaches is decided
+          // once, by narrowing to paperlint's owned scopes (#101), not by a copy of their globs.
           basePath: join(root, "papers/a"),
-          files: expect.arrayContaining([
-            "**/paper.tex",
-            "**/PIPELINE-STATUS.md",
-          ]),
           rules: { "pdf/last-page-balance": ["error", { tolerancePt: 120 }] },
         },
       ],

package/src/parse-args.test.ts

@@ -0,0 +1,48 @@
+/**
+ * `--flag=value` and unknown flags — the command line the CI action actually writes.
+ *
+ * action.yml runs `npx paperlint lint $PATHS --max-warnings="$MAXWARN" --json`. The parser knew
+ * only `--max-warnings <n>`, so `--max-warnings=-1` fell through to the list of PATHS: ESLint was
+ * handed a file named `--max-warnings=-1`, found nothing for it, and the run reported "nothing was
+ * linted under papers, --max-warnings=-1". Any flag the parser did not know became a path the same
+ * way, silently.
+ */
+import { describe, expect, it } from "vitest";
+import { parseArgs, run } from "./cli.ts";
+
+describe("parseArgs — `--flag=value` is the same as `--flag value`", () => {
+  it("🔴 the action's own command line: `--max-warnings=-1` is a threshold, not a path", () => {
+    const a = parseArgs(["lint", "papers", "--max-warnings=-1", "--json"]);
+    // Guards: the defect — the flag landed in `paths`.
+    expect(a.paths).toEqual(["papers"]);
+    expect(a.maxWarnings).toBe(-1);
+  });
+
+  it.each([
+    ["--config=o.json", "config", "o.json"],
+    ["--venue=agenticdev", "venue", "agenticdev"],
+    ["--kind=short", "kind", "short"],
+    ["--format=md", "format", "md"],
+    ["--paper=p", "paper", "p"],
+  ] as const)("%s", (flag, key, value) => {
+    const a = parseArgs(["new", "x", flag]);
+    expect(a[key]).toBe(value);
+    expect(a.paths).toEqual(["x"]);
+  });
+
+  it("an empty value after `=` is a missing value, refused like `--config` with none", () => {
+    expect(parseArgs(["lint", "--config="]).missingValue).toBe("--config");
+  });
+});
+
+describe("an unknown flag is refused, not read as a path", () => {
+  it("exits 2 and names the flag", async () => {
+    const err: string[] = [];
+    const code = await run(["lint", "--frobnicate"], {
+      log: () => {},
+      err: (s: string) => err.push(s),
+    });
+    expect(code).toBe(2);
+    expect(err.join("\n")).toMatch(/unknown flag `--frobnicate`/);
+  });
+});

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,8 @@ 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 research question/.test(
+    /are skipped/.test(at("no-scorecard")[0].message) &&
+      /stage, source and research-question checks/.test(
         at("no-scorecard")[0].message,
       ),
   );

package/src/structure.ts

@@ -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/research-question\` read this file, so nothing \`${dirName}\` declares about its stages, sources or research question is checked`;
+    return `the stage, source and research-question checks are skipped for \`${dirName}\``;
   return `declared as required by your \`structure\` configuration`;
 }
 

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

@@ -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. */

package/src/venue-rules.test.ts

@@ -316,6 +316,9 @@ describe("pdf/measured — a paper that names a venue and was not measured says
     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

@@ -430,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
 }