paperlint 3.0.0 → 3.1.0

package/src/cli.ts

@@ -65,6 +65,10 @@ import {
 import {
   paperPreset,
   paperPresetProblem,
+  presetProblemText,
+  resolvePreset,
+  shippedPresets,
+  SHIPPED_PREFIX,
   type PaperPreset,
 } from "./presets.ts";
 import type { ToolInstaller } from "./ports/tool-installer.ts";
@@ -84,6 +88,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 +128,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 +164,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 +205,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 +339,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 +420,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 +441,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));
 }
@@ -428,17 +508,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 +527,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" }),
@@ -525,6 +602,8 @@ 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.
@@ -546,8 +625,21 @@ export function parseArgs(argv: readonly string[]): Args {
   };
 
   for (let i = 0; i < rest.length; i++) {
-    const a = rest[i];
-    if (a === undefined) continue;
+    const arg = rest[i];
+    if (arg === undefined) continue;
+    // `--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, ++i);
+      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,22 +649,36 @@ 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
@@ -769,16 +875,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 result = newPaper(papersRoot, name, format, { venue });
   const here = (p: string): string => relative(cwd, p) || 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 ask(q).catch(() => "")).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 +1033,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;
   }
@@ -833,7 +1066,30 @@ async function runNew(
     log(
       `several papers directories are declared — using the first: ${relative(cwd, papersRoot) || papersRoot}`,
     );
-  return createPaperAt(papersRoot, name, format, { log, err, cwd });
+  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 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,
+  });
 }
 
 /**
@@ -1061,6 +1317,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;
@@ -1199,6 +1461,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)),
   });
 }
 
@@ -1251,22 +1518,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;

package/src/engine.harness.mjs

@@ -28,6 +28,7 @@ const {
   whichOnPath,
   isExecutable,
   probeTree,
+  missingDependencies,
   supportedPlatform,
 } = await import(join(HERE, "engine.ts"));
 
@@ -251,4 +252,53 @@ check(
   }
 }
 
+// ── missingDependencies: what an install that "continued anyway" left out ──────────────────
+// Real stdout of `tlmgr check depends` on a tree whose install-tl lost unicode-data to a mirror
+// (2026-09-26): the pdflatex format could not be built, yet every venue .sty was present.
+// Byte for byte: tlmgr opens every section header with a FORM FEED, then a space.
+const BROKEN_DEPENDS =
+  "\f DEPENDS WITHOUT PACKAGES:\n" +
+  "unicode-data in: collection-basic latex-bin luahbtex luatex\n" +
+  "\f PACKAGES NOT IN ANY COLLECTION: acmart booktabs caption\n";
+{
+  const calls = [];
+  const run = (cmd, args) => {
+    calls.push([cmd, args]);
+    return {
+      stdout: BROKEN_DEPENDS,
+      stderr: "tlmgr: An error has occurred.",
+      status: 2,
+    };
+  };
+  const missing = missingDependencies("/tl/bin", run);
+  check(
+    "missingDependencies: asks THAT tree's tlmgr `check depends`",
+    calls.length === 1 &&
+      calls[0][0] === "/tl/bin/tlmgr" &&
+      JSON.stringify(calls[0][1]) === '["check","depends"]',
+    JSON.stringify(calls),
+  );
+  // Guards: a package the tree's own database requires but never installed is a gap.
+  check(
+    "🔴 missingDependencies: names the dependency the install dropped",
+    JSON.stringify(missing) === '["unicode-data"]',
+    JSON.stringify(missing),
+  );
+}
+check(
+  "missingDependencies: packages outside any collection are not gaps",
+  JSON.stringify(
+    missingDependencies("/tl/bin", () => ({
+      stdout: "\f PACKAGES NOT IN ANY COLLECTION: acmart booktabs\n",
+      status: 2,
+    })),
+  ) === "[]",
+);
+check(
+  "missingDependencies: a clean tree has none",
+  JSON.stringify(
+    missingDependencies("/tl/bin", () => ({ stdout: "", status: 0 })),
+  ) === "[]",
+);
+
 console.log(`engine: ${n} checks passed`);

package/src/engine.ts

@@ -164,6 +164,41 @@ export function probeTree(
   return missingPackages(packages, String(r.stdout ?? ""));
 }
 
+/**
+ * Packages the tree's OWN database lists as dependencies but never installed, by its `tlmgr check
+ * depends`. 🔴 The venue's `.sty` files are not enough evidence of a working tree: install-tl that
+ * cannot download a package prints "continuing anyway", and a missing `unicode-data` leaves every
+ * `.sty` in place while the pdflatex format cannot be built — pdflatex then dies before writing a
+ * log. Only paperlint's cache trees are asked: their tlmgr writes to a directory we own. A tlmgr
+ * that cannot start returns nothing here; the tree is then judged by `probeTree` alone.
+ */
+export function missingDependencies(
+  bin: string,
+  run: Runner = spawnSync,
+): string[] {
+  const r = run(join(bin, "tlmgr"), ["check", "depends"], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  if (r.error) return [];
+  const lines = String(r.stdout ?? "").split("\n");
+  const start = lines.findIndex(
+    (l) => l.trim() === "DEPENDS WITHOUT PACKAGES:",
+  );
+  if (start < 0) return [];
+  // The section runs until tlmgr's next header. Headers open with a form feed and a space, entries
+  // with the package name, so a header is any line with leading whitespace.
+  const section = lines.slice(start + 1);
+  const end = section.findIndex((l) => l !== l.trimStart() || !l.trim());
+  return [
+    ...new Set(
+      (end < 0 ? section : section.slice(0, end)).map((l) =>
+        l.split(" in: ")[0]!.trim(),
+      ),
+    ),
+  ].sort();
+}
+
 /** The first directory on `path` holding a runnable `name` — what a shell would run. */
 export function whichOnPath(
   name: string,

package/src/init.ts

@@ -372,7 +372,7 @@ export function nextSteps(
 ): string {
   return [
     ``,
-    `next:  npx paperlint new <name>   # start a paper in ${papersDir}/ from the template`,
+    `next:  npx paperlint new <name> --venue <preset>   # start a paper in ${papersDir}/ from the template`,
     ...(toolchain
       ? [
           `       npx paperlint toolchain    # TeX Live for building (${TOOLCHAIN_COST})`,