paperlint 3.2.0 → 4.1.0

package/src/build-engine.ts

@@ -62,10 +62,12 @@ type Resolved = Required<Omit<EngineOptions, "install">> & {
 };
 
 /** The options a caller actually set — `undefined` must still get its default, so no plain spread. */
-const defined = <T extends object>(o: T): Partial<T> =>
-  Object.fromEntries(
-    Object.entries(o).filter(([, v]) => v !== undefined),
-  ) as Partial<T>;
+function defined<T extends object>(o: T): Partial<T> {
+  const out: Partial<T> = {};
+  // `for…in` hands out `o`'s keys typed as its keys; an options literal has no inherited ones.
+  for (const k in o) if (o[k] !== undefined) out[k] = o[k];
+  return out;
+}
 
 function withDefaults(o: EngineOptions): Resolved {
   const r = {
@@ -133,7 +135,10 @@ const names = (missing: readonly string[]): string =>
   `${String(missing.length)} package(s): ${missing.join(", ")}`;
 
 /** The one line a run without a human gets. It names the command and what is missing. */
-export function refusal(d: EngineDecision, facts: EngineFacts): string {
+export function refusal(
+  d: EngineDecision,
+  facts: Pick<EngineFacts, "system">,
+): string {
   const missing = d.kind === "refuse" || d.kind === "ask" ? d.missing : [];
   const sys =
     facts.system && facts.system.missing.length

package/src/build.harness.mjs

@@ -4,7 +4,7 @@
  * The process runner is replaced by a fake that writes what pdflatex and bibtex would write, so
  * these assertions check the SHELL's decisions: what is run, with which environment, in which
  * order, and what is left on disk. Whether a real pdflatex produces a real PDF is the other half,
- * `test/e2e/build.ts`.
+ * `test/e2e/tex/build.e2e.ts`.
  *
  * 🔴 THE TWO THINGS PINNED DOWN HERE THAT A RETURNED OBJECT CANNOT SHOW: a paper-supplied
  * `build.sh` is never executed (checked by the trace it would leave on disk and by the list of
@@ -40,9 +40,7 @@ const {
   STEPS,
   IGNORED_SCRIPTS,
 } = await import(join(HERE, "build.ts"));
-const { packageVenuesDir } = await import(
-  join(HERE, "..", "skills", "paper-pipeline", "scripts", "consumer.mjs")
-);
+const { texInputsDir } = await import(join(HERE, "package-dirs.ts"));
 
 const check = createChecker();
 
@@ -137,12 +135,12 @@ const fakeRead = async (pdf) => {
 const CLEAN_TEX = "\\documentclass{article}\\begin{document}x\\end{document}";
 
 try {
-  // ── inputs: paperlint's own venues directory, no configuration ───────────────────────────────
+  // ── inputs: paperlint's own TeX inputs directory, no configuration ────────────────────────────
   // First: the facts below resolve a paper's venue preset in this same directory, so a wrong one
   // must be named HERE, not as a missing venue label two checks later.
-  const venues = packageVenuesDir();
+  const venues = texInputsDir();
   check(
-    "the venues directory is paperlint's own and holds paper-guards.tex",
+    "the TeX inputs directory is paperlint's own and holds paper-guards.tex",
     existsSync(join(venues, "paper-guards.tex")),
   );
   check(

package/src/build.test.ts

@@ -8,7 +8,7 @@ import assert from "node:assert/strict";
 import { existsSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { test } from "vitest";
-import { useTempDir, writeTree } from "../test/support.ts";
+import { present, useTempDir, writeTree } from "../test/support.ts";
 import {
   bibInput,
   buildPaper,
@@ -64,16 +64,16 @@ function bibtexRun(f: Fake, cwd: string) {
 }
 function fakeRun(f: Fake): NonNullable<BuildOptions["run"]> {
   let pass = 0;
-  return ((bin: string, _args: string[], opts: { cwd: string }) => {
+  return (bin, _args, opts) => {
     if (bin === f.missing)
       return {
         error: Object.assign(new Error("spawn ENOENT"), { code: "ENOENT" }),
         status: null,
       };
-    return bin === "pdflatex"
-      ? latexPass(f, opts.cwd, ++pass)
-      : bibtexRun(f, opts.cwd);
-  }) as never;
+    // The build always runs a pass in the paper's directory.
+    const cwd = present(opts.cwd, "the pass's cwd");
+    return bin === "pdflatex" ? latexPass(f, cwd, ++pass) : bibtexRun(f, cwd);
+  };
 }
 
 const NO_GEOMETRY: Geometry = {
@@ -146,11 +146,10 @@ test("documentclass: an empty name is no class; a macro inside the name contribu
   // `\documentclass` came back bare has no name to read, and is no class.
   assert.equal(
     parseDocumentclass("\\documentclass", {
-      parse: () =>
-        ({
-          type: "root",
-          content: [{ type: "macro", content: "documentclass" }],
-        }) as never,
+      parse: () => ({
+        type: "root",
+        content: [{ type: "macro", content: "documentclass" }],
+      }),
     }),
     null,
   );

package/src/build.ts

@@ -34,7 +34,7 @@
  * The decision of the LaTeX loop is `latex-loop.ts`, reading the log is `latex-log.ts`; both are
  * pure. This file is the shell: it runs processes through the injected `run` (the existing port —
  * `spawnSync` by default) and reads the files a pass left behind. Where paperlint's own files live is
- * answered by `consumer.mjs`, the one module allowed to know it (rule 10).
+ * answered by `package-dirs.ts`, the one module allowed to know it (rule 10).
  */
 // eslint-disable-next-line boundaries/dependencies -- legacy I/O, moves behind a port in #76
 import { existsSync, readdirSync, readFileSync, rmSync } from "node:fs";
@@ -44,7 +44,7 @@ import { createHash } from "node:crypto";
 import { delimiter, join, relative } from "node:path";
 // eslint-disable-next-line boundaries/dependencies -- legacy layer, moves behind a port in #76
 import { getParser } from "@unified-latex/unified-latex-util-parse";
-import { packageVenuesDir } from "../skills/paper-pipeline/scripts/consumer.mjs";
+import { texInputsDir } from "./package-dirs.ts";
 import { CONFIG_FILE } from "#lib/paper-config";
 import {
   declaredVenue,
@@ -61,7 +61,8 @@ import { banalMeasurer, parseBanalSettings } from "./adapters/banal/index.ts";
 // eslint-disable-next-line boundaries/dependencies -- legacy layer, moves behind a port in #76
 import { hostDirs, nodeAdapters, nodeFiles } from "./adapters/node/index.ts";
 import { whyNoGeometry } from "./domain/geometry.ts";
-import type { AbsolutePath } from "./domain/paths.ts";
+import { callerPath } from "./caller-path.ts";
+import type { Runner } from "./engine.ts";
 import type { Files } from "./ports/files.ts";
 import type { MeasureGeometry } from "./ports/measure-geometry.ts";
 import type { CheckReferences } from "./ports/check-references.ts";
@@ -76,7 +77,6 @@ import {
 import {
   nextStep,
   summarize,
-  TRACKED,
   type BibInput,
   type Hashes,
   type Observation,
@@ -128,7 +128,7 @@ export interface PaperFacts {
 }
 
 /** A process runner with `spawnSync`'s shape — the port the harness replaces. */
-export type Runner = typeof spawnSync;
+export type { Runner };
 
 /** What a step's `run` receives. `env` is the environment accumulated by the steps before it. */
 export interface BuildContext {
@@ -268,11 +268,11 @@ export const inputsStep: BuildStep = {
   required: false,
   applies: () => ({
     yes: true,
-    why: `TEXINPUTS += ${packageVenuesDir()}`,
+    why: `TEXINPUTS += ${texInputsDir()}`,
   }),
   run: (ctx) => ({
     ok: true,
-    env: withTexInputs(ctx.env, [packageVenuesDir()]),
+    env: withTexInputs(ctx.env, [texInputsDir()]),
   }),
 };
 
@@ -286,9 +286,8 @@ function hashes(paperDir: string): Hashes {
     const p = join(paperDir, `${JOB}.${ext}`);
     return existsSync(p) ? sha(readFileSync(p)) : null;
   };
-  const out: Record<string, string | null> = {};
-  for (const t of TRACKED) out[t] = h(t);
-  return out as Hashes;
+  // A literal of the mapped type: a new tracked extension without a hash here is a compile error.
+  return { aux: h("aux"), toc: h("toc"), out: h("out"), bbl: h("bbl") };
 }
 
 const readOr = (path: string, enc: BufferEncoding): string | null =>
@@ -387,8 +386,8 @@ function latexPass(
 
 /** The two streams of a finished run, as they really arrive (see `printed`). */
 interface Streams {
-  readonly stdout: string | undefined;
-  readonly stderr: string | undefined;
+  readonly stdout?: string | undefined;
+  readonly stderr?: string | undefined;
 }
 
 /**
@@ -694,7 +693,7 @@ function defaultMeasurer(
   return banalMeasurer(
     nodeAdapters({ tmpDir: dirs.tmp }),
     parseBanalSettings(b.env, dirs),
-    b.projectRoot as AbsolutePath,
+    callerPath(b.projectRoot),
   );
 }
 

package/src/caller-path.ts

@@ -0,0 +1,13 @@
+/**
+ * A path as a caller gave it, made absolute where it enters a `Files` call.
+ *
+ * The app's use cases take paper directories and files as strings, and some callers pass them as
+ * typed on a command line (`skills/render-paper/extract-pdf-facts.mjs <paper.pdf>`). A relative one
+ * has always meant the process's cwd — `node:fs` resolved it there. Resolving it HERE, the same way,
+ * makes the `AbsolutePath` brand a checked fact rather than an assertion: the value handed to the port
+ * is absolute, and nothing downstream has to wonder.
+ */
+import { resolve } from "node:path";
+import { absolutePath, type AbsolutePath } from "./domain/paths.ts";
+
+export const callerPath = (p: string): AbsolutePath => absolutePath(resolve(p));

package/src/cli.harness.mjs

@@ -1148,7 +1148,7 @@ check(
 //     pnpm: node_modules/vigiles/dist/cli.js  DOES NOT
 // The old wiring addressed the runtime from the project root and did not resolve under pnpm,
 // and `|| exit 2` on PreToolUse(Bash) turned that into a block on ANY command. The end-to-end
-// half (both installs, real processes) lives in `test/e2e/install.ts`; here — the verdicts.
+// half (both installs, real processes) lives in `test/e2e/install/install.e2e.ts`; here — the verdicts.
 {
   const calls = [];
   const fake = (code) => (bin, args, opts) => {
@@ -1711,8 +1711,6 @@ console.log(
         typo.out.includes('paperlint.json: unknown key "typographyDept"'),
     );
     settings({
-      ledger: "x.jsonl",
-      citeChecks: "c",
       timezone: "UTC",
       contactEmail: "a@b.c",
       triggerCases: "t.mjs",

package/src/cli.test.ts

@@ -10,6 +10,7 @@ import { existsSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { test } from "vitest";
 import { runNode, useTempDir, writeTree } from "../test/support.ts";
+import type { runToolchain } from "./toolchain.ts";
 import {
   chooseVenue,
   initTexLive,
@@ -22,6 +23,7 @@ import {
   silentOptionalRules,
   toolchainTex,
 } from "./cli.ts";
+import { texInputsDir } from "./package-dirs.ts";
 
 const root = useTempDir("cli-test-");
 
@@ -57,6 +59,18 @@ test("parseArgs: the boolean flags of build and toolchain, and a value flag with
   );
 });
 
+test("🔴 parseSettings refuses a mistyped `structure` instead of letting `lint` crash on it", () => {
+  // Guards: `markers: 5` used to pass the boundary, and `checkStructure` then threw
+  // "rules.markers.some is not a function" from inside `paperlint lint`.
+  for (const structure of [{ markers: 5 }, "yes", { requireOneOf: ["a"] }]) {
+    const r = parseSettings({ structure }, "paperlint.json", "/r");
+    assert.equal(r.ok, false, JSON.stringify(structure));
+    assert.match(r.error, /^paperlint\.json: "structure" must be false/);
+  }
+  const off = parseSettings({ structure: false }, "paperlint.json", "/r");
+  assert.equal(off.ok && off.value.structure, false);
+});
+
 test("parseSettings refuses a non-object, names one unknown key or several, and a mistyped default", () => {
   const error = (json: unknown) => {
     const r = parseSettings(json, "paperlint.json", "/r");
@@ -146,7 +160,7 @@ test("runHook: a runtime with no cli.js beside it, and a hook killed by a signal
   });
   const killed = runHook("paper-edit-guard", {
     err: (m: string) => messages.push(m),
-    run: (() => ({ status: null, signal: "SIGKILL" })) as never,
+    run: () => ({ status: null, signal: "SIGKILL" }),
   });
   assert.deepEqual(
     { noCli, killed, messages: messages.map((m) => m.split(" from ")[0]) },
@@ -235,14 +249,7 @@ writeTree(noTexDir, {
   "papers/tex/paper.tex":
     "\\documentclass{article}\\begin{document}x\\end{document}\n",
 });
-const venues = join(
-  import.meta.dirname,
-  "..",
-  "skills",
-  "submit-paper",
-  "references",
-  "venues",
-);
+const venues = texInputsDir();
 
 test("build: a markdown-only paper is refused", async () => {
   const md = await withoutTex(noTexDir, () =>
@@ -363,7 +370,8 @@ test("a paper's paperlint.json that does not parse stops the lint with its path"
 });
 
 test("silentOptionalRules: a config with no rules turns nothing on", async () => {
-  assert.deepEqual(await silentOptionalRules({} as never, [], {}), []);
+  const eslint = { calculateConfigForFile: () => Promise.resolve(undefined) };
+  assert.deepEqual(await silentOptionalRules(eslint, [], {}), []);
 });
 
 test("init with no path and --format md sets up the current directory", async () => {
@@ -538,8 +546,8 @@ test("ownVersion: the manifest's version; an unreadable manifest or a non-string
 
 test("init's TeX Live install runs the toolchain over the project's papers, never a check", () => {
   const dir = writeTree(join(root, "init-tex"), { "package.json": "{}" });
-  const calls: unknown[] = [];
-  const fake = ((o: unknown) => (calls.push(o), 0)) as never;
+  const calls: Parameters<typeof runToolchain>[0][] = [];
+  const fake: typeof runToolchain = (o) => (calls.push(o), 0);
   const log = () => {};
   const here = initTexLive(
     parseArgs(["init"]),
@@ -553,10 +561,7 @@ test("init's TeX Live install runs the toolchain over the project's papers, neve
   );
   assert.deepEqual([here.install(), there.install()], [0, 0]);
   assert.deepEqual(
-    calls.map((c) => {
-      const o = c as { check: boolean; tex: unknown; banal: unknown };
-      return [o.check, o.tex, typeof o.banal];
-    }),
+    calls.map((c) => [c.check, c.tex, typeof c.banal]),
     [
       [false, toolchainTex(dir), "object"],
       [false, toolchainTex(join(dir, "sub")), "object"],

package/src/cli.ts

@@ -30,11 +30,10 @@ import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { join, dirname, resolve, relative, basename, sep } from "node:path";
 import markdown from "@eslint/markdown";
+import { z } from "zod";
 // Types come from consumer.d.mts beside it.
-import {
-  isMain,
-  packageVenuesDir,
-} from "../skills/paper-pipeline/scripts/consumer.mjs";
+import { isMain } from "../skills/paper-pipeline/scripts/consumer.mjs";
+import { presetsDir } from "./package-dirs.ts";
 export { isMain };
 import type { Args, PaperlintConfig, ConfigRead } from "./types.ts";
 import {
@@ -47,8 +46,10 @@ import { prepareEngine } from "./build-engine.ts";
 import { cacheRoot, cachedTree, runToolchain } from "./toolchain.ts";
 import { banalInstaller, parseBanalSettings } from "./adapters/banal/index.ts";
 import { curlDownload } from "./adapters/curl/index.ts";
+import { latexReader } from "./adapters/latex/index.ts";
 import { hostDirs, nodeAdapters, nodeFiles } from "./adapters/node/index.ts";
 import { VENUE_RULE_LEVELS, venueRules } from "./venue-rules.ts";
+import { TEX_VENUE_RULE_LEVELS, texVenueRules } from "./tex-venue-rules.ts";
 import {
   paperRules,
   stringFields,
@@ -71,6 +72,7 @@ import {
   shippedPresets,
   SHIPPED_PREFIX,
   type PaperPreset,
+  type PresetTemplate,
 } from "./presets.ts";
 import type { ToolInstaller } from "./ports/tool-installer.ts";
 import {
@@ -112,6 +114,7 @@ import {
   shippedRuleIds,
   unknownKeys,
   type Parsed,
+  type ConfigBlock,
   type RuleBlock,
   type RuleEntry,
 } from "./rules-config.ts";
@@ -127,9 +130,10 @@ import reviewFrontmatter from "#eslint-rules/review-frontmatter";
 import siblingFrontmatter from "#eslint-rules/sibling-frontmatter";
 import pdfRules from "#eslint-rules/pdf-last-page-balance";
 import { messageOf } from "./domain/text.ts";
+import { isRecord } from "./domain/record.ts";
 
 /** The shipped venue presets, read from the package's venues directory — the one list. */
-const SHIPPED_VENUES = (): string[] => shippedPresets(packageVenuesDir());
+const SHIPPED_VENUES = (): string[] => shippedPresets(presetsDir());
 
 const USAGE = `paperlint — machine-checkable gates for a paper kept in git
 
@@ -220,7 +224,7 @@ settings — paperlint.json, at two levels, one schema. Both are optional.
 export function buildConfig(
   opts: PaperlintConfig = {},
   texLanguage: unknown,
-): unknown[] {
+): ConfigBlock[] {
   const paperRules = { ...researchQuestion.rules, ...typography.rules };
   // The reference rules judge `_build/references.json`, and only on `paper.tex`.
   const texPaperRules = {
@@ -238,7 +242,7 @@ export function buildConfig(
     languageOptions: { frontmatter: "yaml" },
   };
 
-  const cfg: unknown[] = [
+  const cfg: ConfigBlock[] = [
     // 🔴 THE PROJECT'S PAPER TEMPLATE IS NOT A PAPER. `paperlint new` reads `<papers>/.template/`, and
     // its files carry every marker a paper does. Flat config does NOT ignore dot-directories by
     // default (only `node_modules/` and `.git/`), so without this block `paperlint lint` would lint the
@@ -254,7 +258,7 @@ export function buildConfig(
         pdf: {
           rules: {
             ...pdfRules.rules,
-            ...venueRules({ files: nodeFiles, venuesDir: packageVenuesDir() }),
+            ...venueRules({ files: nodeFiles, venuesDir: presetsDir() }),
           },
         },
       },
@@ -299,7 +303,17 @@ export function buildConfig(
     cfg.push({
       files: ["**/paper.tex"],
       plugins: {
-        tex: { languages: { latex: texLanguage }, rules: texBuild },
+        tex: {
+          languages: { latex: texLanguage },
+          rules: {
+            ...texBuild,
+            ...texVenueRules({
+              files: nodeFiles,
+              venuesDir: presetsDir(),
+              latex: latexReader,
+            }),
+          },
+        },
         paper: { rules: texPaperRules },
         bib: bibReachable,
       },
@@ -313,6 +327,7 @@ export function buildConfig(
         "tex/acm-frontmatter-override": "error",
         // Silent for a paper whose paperlint.json names no venue (src/venue-rules.ts).
         ...VENUE_RULE_LEVELS,
+        ...TEX_VENUE_RULE_LEVELS,
       },
     });
   // 🔴 ONLY THE FILES THESE BLOCKS CLAIM ARE LINTED (src/paper-files.ts). Without this block ESLint's
@@ -329,6 +344,21 @@ export function buildConfig(
   return cfg;
 }
 
+/**
+ * paperlint's blocks as ESLint's config type — the one place the two meet. ESLint types a plugin's
+ * rule as one that runs on ANY language; paperlint's run on the language they were written for, so
+ * no static proof that a block fits exists (`ConfigBlock`, rules-config.ts). ESLint checks every block
+ * when it loads the config and throws on one it cannot use; what is left to check here is that each
+ * is an object.
+ */
+const isEslintBlock = (b: unknown): b is Linter.Config =>
+  typeof b === "object" && b !== null;
+
+export function eslintConfig(blocks: readonly ConfigBlock[]): Linter.Config[] {
+  const loose: readonly unknown[] = blocks;
+  return loose.filter(isEslintBlock);
+}
+
 /**
  * The rule ids a consumer may name in `rules`: every rule paperlint's own config defines, read off that
  * config rather than listed again. `@eslint/markdown` is a dependency's plugin, not paperlint's.
@@ -357,9 +387,7 @@ export interface RulePlugin {
 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 ?? {},
-    ))
+    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)
@@ -382,12 +410,10 @@ export function rulePlugins(texLanguage?: unknown): Record<string, RulePlugin> {
  * switched off in THIS run — `paperlint lint` still reports a directive that silences nothing.
  */
 export function rulesOff(texLanguage?: unknown): Linter.Config[] {
-  return [
+  return eslintConfig([
     {
       name: "paperlint/rules-off",
-      plugins: rulePlugins(texLanguage) as NonNullable<
-        Linter.Config["plugins"]
-      >,
+      plugins: rulePlugins(texLanguage),
       rules: Object.fromEntries([...SHIPPED_RULES].map((id) => [id, "off"])),
     },
     {
@@ -395,7 +421,7 @@ export function rulesOff(texLanguage?: unknown): Linter.Config[] {
       files: PAPER_FILE_PATTERNS,
       linterOptions: { reportUnusedDisableDirectives: "off" },
     },
-  ];
+  ]);
 }
 
 /** Whether a rule entry (`"error"`, `2`, `["warn", {…}]`) turns the rule on. */
@@ -412,7 +438,7 @@ export const OPTIONAL_RULES: ReadonlySet<string> = new Set(
   [...SHIPPED_RULES].filter(
     (id) =>
       !buildConfig({}, { sentinel: "tex language" }).some((b) =>
-        isOn((b as { rules?: Record<string, unknown> }).rules?.[id]),
+        isOn(b.rules?.[id]),
       ),
   ),
 );
@@ -429,8 +455,13 @@ export const OPTIONAL_RULES: ReadonlySet<string> = new Set(
  * 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.
  */
+/** What `calculateConfigForFile` answers, read for its rules: undefined for a file outside ESLint's cwd or scope. */
+const ComputedConfig = z
+  .object({ rules: z.record(z.string(), z.unknown()).optional() })
+  .optional();
+
 export async function silentOptionalRules(
-  eslint: ESLint,
+  eslint: Pick<ESLint, "calculateConfigForFile">,
   files: readonly string[],
   opts: PaperlintConfig,
 ): Promise<string[]> {
@@ -444,8 +475,7 @@ export async function silentOptionalRules(
   const reached = new Set<string>();
   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;
+    const cfg = ComputedConfig.parse(await eslint.calculateConfigForFile(f));
     for (const id of turnedOn) if (isOn(cfg?.rules?.[id])) reached.add(id);
   }
   return [...turnedOn].filter((id) => !reached.has(id));
@@ -543,6 +573,20 @@ const PAPER_FILE_PATTERNS: string[] = ownedPatterns(
   buildConfig({}, { sentinel: "tex language" }),
 );
 
+/** `structure` as `checkStructure` reads it: off, or lists of file names over the defaults. */
+const Names = z.array(z.string()).exactOptional();
+const Structure = z
+  .union([
+    z.literal(false),
+    z.object({
+      markers: Names,
+      require: Names,
+      requireOneOf: z.array(z.array(z.string())).exactOptional(),
+      ignore: Names,
+    }),
+  ])
+  .optional();
+
 /**
  * The root `paperlint.json` after the boundary: an unknown key is refused by name, the paper
  * defaults (`extends`, `kind`, `pdf`) are checked the way a paper's own are, and `rules` becomes
@@ -553,10 +597,9 @@ export function parseSettings(
   where: string,
   baseDir: string,
 ): Parsed<PaperlintConfig> {
-  if (typeof json !== "object" || json === null || Array.isArray(json))
+  if (!isRecord(json))
     return { ok: false, error: `${where}: must be a JSON object` };
-  const raw = json as Record<string, unknown>;
-  const opts = raw as PaperlintConfig;
+  const raw = json;
   const unknown = unknownKeys(raw);
   if (unknown.length > 0)
     return {
@@ -567,9 +610,22 @@ export function parseSettings(
     };
   const defaults = stringFields(raw);
   if (!defaults.ok) return { ok: false, error: `${where}: ${defaults.error}` };
+  const structure = Structure.safeParse(raw["structure"]);
+  if (!structure.success)
+    return {
+      ok: false,
+      error: `${where}: "structure" must be false, or an object whose markers, require and ignore are lists of file names and requireOneOf a list of such lists`,
+    };
   const rules = parseRuleBlocks(raw["rules"], where, SHIPPED_RULES, baseDir);
   if (!rules.ok) return rules;
-  return { ok: true, value: { ...opts, rules: rules.value } };
+  return {
+    ok: true,
+    value: {
+      papersDir: raw[PAPERS_DIR_FIELD],
+      structure: structure.data,
+      rules: rules.value,
+    },
+  };
 }
 
 /**
@@ -770,7 +826,7 @@ export function readConfig(
 
 /** The papers directory field of the settings, read by its one declared name; the default when absent. */
 export function papersDirOf(opts: PaperlintConfig): unknown {
-  const declared = (opts as Record<string, unknown>)[PAPERS_DIR_FIELD];
+  const declared = opts.papersDir;
   return declared === undefined ? DEFAULT_PAPERS_ROOT : declared;
 }
 
@@ -839,7 +895,12 @@ export function runHook(
       createRequire(import.meta.url).resolve(spec),
   }: {
     err?: typeof console.error;
-    run?: typeof spawnSync;
+    /** Runs the hook with the terminal's streams: `spawnSync` is one, and only its status is read. */
+    run?: (
+      file: string,
+      args: readonly string[],
+      options: { readonly stdio: "inherit" },
+    ) => { readonly status: number | null };
     resolve?: (spec: string) => string;
   } = {},
 ): number {
@@ -988,12 +1049,25 @@ export async function chooseVenue(
     value: {
       extends: spec.value,
       kind: kind !== null && kinds.includes(kind) ? kind : null,
+      setClass: classSetter(r.value.template),
       label,
       kinds,
     },
   };
 }
 
+/**
+ * What `paperlint new` does to the template's paper.tex for a venue: set it in the class the
+ * preset's template names. Null when the preset names no template, or one the reader cannot read
+ * (then `tex/template` says so on the new paper).
+ */
+function classSetter(
+  t: PresetTemplate | null,
+): ((paperTex: string) => string) | null {
+  const cls = t === null ? null : latexReader.template(t.text);
+  return cls === null ? null : (src) => latexReader.withDocumentClass(src, cls);
+}
+
 const bad = (error: string): { ok: false; error: string } => ({
   ok: false,
   error,
@@ -1168,7 +1242,7 @@ async function runBuild(
 }
 
 /** The presets' deps, wired to the disk and the package's own venues directory. */
-const PRESET_DEPS = { files: nodeFiles, venuesDir: packageVenuesDir() };
+const PRESET_DEPS = { files: nodeFiles, venuesDir: presetsDir() };
 
 /**
  * What one paper needs from TeX Live: the base set plus its preset chain's `tex`. A paper whose
@@ -1466,7 +1540,7 @@ export async function run(
   const eslint = new ESLint({
     cwd: lintRoot(root, paths),
     overrideConfigFile: true,
-    overrideConfig: buildConfig(withPapers, texLanguage) as Linter.Config[],
+    overrideConfig: eslintConfig(buildConfig(withPapers, texLanguage)),
     fix: a.fix,
   });
 
@@ -1543,12 +1617,20 @@ async function firstUnownedFile(
  * is outside paperlint's scope (`all-matched-files-ignored` — a papers directory holding only
  * vendored scripts). Both mean "nothing was linted", which the caller reports itself.
  */
+/** What a thrown ESLint error says about itself; anything else thrown says nothing. */
+const EslintFailure = z
+  .object({
+    messageTemplate: z.string().optional(),
+    message: z.string().optional(),
+  })
+  .catch({});
+
 const isEmptySet = (e: unknown): boolean => {
-  const fail = e as { messageTemplate?: string; message?: string } | null;
+  const fail = EslintFailure.parse(e);
   return (
-    fail?.messageTemplate === "file-not-found" ||
-    fail?.messageTemplate === "all-matched-files-ignored" ||
-    /No files matching/i.test(String(fail?.message))
+    fail.messageTemplate === "file-not-found" ||
+    fail.messageTemplate === "all-matched-files-ignored" ||
+    /No files matching/i.test(String(fail.message))
   );
 };