paperlint 2.1.0 → 3.0.0

package/src/references.test.ts

@@ -0,0 +1,209 @@
+/**
+ * The references a build checked, end to end without a network: the `references` build step
+ * records what a (fake) checker answers, and the offline rules judge that record.
+ *
+ *   a pass is recorded, with the hash of the bibliography checked
+ *   one mismatched entry → paper/author-list on THAT entry's line
+ *   the bibliography edited after the build → paper/refs-fresh, and the per-entry rules go quiet
+ *   offline → the step still succeeds (the build is not failed) and paper/refs-checked warns
+ */
+import { describe, expect, it } from "vitest";
+import { ESLint } from "eslint";
+import { join } from "node:path";
+import { memoryFiles } from "./adapters/memory/index.ts";
+import type { AbsolutePath } from "./domain/paths.ts";
+import type {
+  CheckReferences,
+  EntryVerdict,
+} from "./ports/check-references.ts";
+import { referencesStep } from "./build.ts";
+import {
+  bibHash,
+  bibliographyOf,
+  readReferences,
+  referencesPath,
+} from "./references.ts";
+import { referenceRules, REFERENCE_RULE_LEVELS } from "./reference-rules.ts";
+// @ts-expect-error — an ESLint language in .mjs, it has no types
+import { texLanguage } from "../eslint-rules/latex-language.mjs";
+
+const PAPER = "/work/papers/p";
+const TEX = (entries: string) =>
+  [
+    "\\documentclass{acmart}",
+    "\\begin{filecontents*}{refs.bib}",
+    entries,
+    "\\end{filecontents*}",
+    "\\begin{document}",
+    "x",
+    "\\end{document}",
+    "",
+  ].join("\n");
+const ENTRIES =
+  "@inproceedings{schick2023,\n  title = {Toolformer},\n  author = {Schick, Timo},\n  booktitle = {NeurIPS}\n}\n@misc{other,\n  title = {Other},\n  url = {https://x.org}\n}";
+
+const verdict = (
+  key: string,
+  authors: EntryVerdict["authors"] = "match",
+  exists: EntryVerdict["exists"] = "true",
+): EntryVerdict => ({
+  key,
+  exists,
+  authors,
+  ...(authors === "mismatch" ? { why: "missing hambro" } : {}),
+});
+
+const checker =
+  (entries: readonly EntryVerdict[]): CheckReferences =>
+  async () => ({ kind: "checked", entries });
+const offline: CheckReferences = async () => ({
+  kind: "not-checked",
+  why: "the citation services cannot be reached (fetch failed)",
+});
+
+/** Run the build step on a paper held in memory; returns the files and the step's outcome. */
+async function build(tex: string, check: CheckReferences) {
+  const files = memoryFiles({ [`${PAPER}/paper.tex`]: tex });
+  const out = await referencesStep.run({
+    paperDir: PAPER,
+    env: {},
+    run: (() => ({})) as never,
+    readPdf: (() => null) as never,
+    measure: (() => null) as never,
+    files,
+    checkReferences: check,
+  });
+  return { files, out };
+}
+
+/**
+ * The rules as an ESLint plugin. Their context type is the narrow one they read (a custom
+ * language's SourceCode), which ESLint's JS-centred plugin type does not describe.
+ */
+const asPlugin = (rules: object): ESLint.Plugin => ({ rules }) as ESLint.Plugin;
+
+/** Lint `tex` as the paper's paper.tex against what `files` recorded. */
+async function lint(files: ReturnType<typeof memoryFiles>, tex: string) {
+  files.writeAtomic(
+    `${PAPER}/paper.tex` as AbsolutePath,
+    new TextEncoder().encode(tex),
+  );
+  const eslint = new ESLint({
+    cwd: "/work",
+    overrideConfigFile: true,
+    overrideConfig: [
+      {
+        files: ["**/paper.tex"],
+        plugins: {
+          tex: { languages: { latex: texLanguage } },
+          paper: asPlugin(referenceRules({ files })),
+        },
+        language: "tex/latex",
+        rules: REFERENCE_RULE_LEVELS,
+      },
+    ],
+  });
+  const [res] = await eslint.lintText(tex, {
+    filePath: join(PAPER, "paper.tex"),
+  });
+  return res!.messages;
+}
+
+describe("the references build step", () => {
+  it("records a pass, with the hash of the bibliography it checked", async () => {
+    const tex = TEX(ENTRIES);
+    const { files, out } = await build(
+      tex,
+      checker([verdict("schick2023"), verdict("other")]),
+    );
+    expect(out.ok).toBe(true);
+    const doc = readReferences(files, PAPER);
+    expect(doc?.status).toBe("checked");
+    expect(doc?.bib.sha256).toBe(bibHash(bibliographyOf(files, PAPER)!));
+    expect(await lint(files, tex)).toEqual([]);
+  });
+
+  it("🔴 offline: the step succeeds — the build is not failed — and lint warns once", async () => {
+    const tex = TEX(ENTRIES);
+    const { files, out } = await build(tex, offline);
+    expect(out.ok).toBe(true);
+    expect(readReferences(files, PAPER)?.status).toBe("not-checked");
+    const msgs = await lint(files, tex);
+    expect(msgs.map((m) => [m.ruleId, m.severity])).toEqual([
+      ["paper/refs-checked", 1],
+    ]);
+    expect(msgs[0]!.message).toMatch(/cannot be reached/);
+  });
+
+  it("a checker that throws is recorded as not checked, not as a failed build", async () => {
+    const { files, out } = await build(TEX(ENTRIES), async () => {
+      throw new Error("DBLP exploded");
+    });
+    expect(out.ok).toBe(true);
+    expect(readReferences(files, PAPER)?.why).toMatch(/DBLP exploded/);
+  });
+});
+
+describe("the reference rules", () => {
+  it("one mismatched entry → paper/author-list on that entry's own line", async () => {
+    const tex = TEX(ENTRIES);
+    const { files } = await build(
+      tex,
+      checker([verdict("schick2023", "mismatch"), verdict("other")]),
+    );
+    const msgs = await lint(files, tex);
+    expect(msgs.map((m) => m.ruleId)).toEqual(["paper/author-list"]);
+    expect(msgs[0]!.line).toBe(3);
+    expect(msgs[0]!.message).toMatch(/`schick2023`.*missing hambro/);
+  });
+
+  it("an identifier that provably fails → paper/cite-exists on that entry", async () => {
+    const tex = TEX(ENTRIES);
+    const { files } = await build(
+      tex,
+      checker([verdict("schick2023"), verdict("other", "skipped", "false")]),
+    );
+    const msgs = await lint(files, tex);
+    expect(msgs.map((m) => [m.ruleId, m.line])).toEqual([
+      ["paper/cite-exists", 8],
+    ]);
+  });
+
+  it("🔴 the bibliography edited after the build → refs-fresh, and the stale verdicts are not judged", async () => {
+    const { files } = await build(
+      TEX(ENTRIES),
+      checker([verdict("schick2023", "mismatch"), verdict("other")]),
+    );
+    const edited = TEX(
+      ENTRIES.replace("Schick, Timo", "Schick, Timo and Hambro, Eric"),
+    );
+    const msgs = await lint(files, edited);
+    expect(msgs.map((m) => [m.ruleId, m.severity])).toEqual([
+      ["paper/refs-fresh", 2],
+    ]);
+  });
+
+  it("the same bibliography, unchanged → silent", async () => {
+    const tex = TEX(ENTRIES);
+    const { files } = await build(tex, checker([verdict("schick2023")]));
+    expect(await lint(files, tex)).toEqual([]);
+  });
+
+  it("never built → one warning naming the command", async () => {
+    const files = memoryFiles({});
+    const msgs = await lint(files, TEX(ENTRIES));
+    expect(msgs.map((m) => m.ruleId)).toEqual(["paper/refs-checked"]);
+    expect(msgs[0]!.message).toMatch(/npx paperlint build/);
+  });
+
+  it("a paper with no bibliography gets nothing", async () => {
+    const files = memoryFiles({});
+    expect(
+      await lint(
+        files,
+        "\\documentclass{article}\n\\begin{document}x\\end{document}\n",
+      ),
+    ).toEqual([]);
+    expect(referencesPath(PAPER)).toBe(`${PAPER}/_build/references.json`);
+  });
+});

package/src/references.ts

@@ -0,0 +1,138 @@
+/**
+ * THE REFERENCES A BUILD CHECKED — `<paper>/_build/references.json`, written by `paperlint build`
+ * and read, offline, by the lint rules in `reference-rules.ts`.
+ *
+ * The package ships two online checks: `verify-cites` (the cited work exists and its title
+ * matches) and `bib-authors` (the authors are those of the version cited, not the preprint's).
+ * Until 3.0.0 lint could only ask whether someone had run them — by finding the word
+ * "bib-authors" in a scorecard table, or a command the project configured. Now the build runs
+ * them and records the result as data, beside the facts it already writes about the PDF:
+ *
+ *   { "schema": 1,
+ *     "bib": { "source": "paper.tex", "sha256": "…" },       the bibliography that was checked
+ *     "status": "checked" | "not-checked", "why": "…",       not-checked: nothing could be asked
+ *     "entries": [ { "key", "exists", "authors", "why" } ] }
+ *
+ * A sibling file, not a new field of `paper.facts.json`: those facts are about ONE PDF and are
+ * stale when it changes (`pdf_sha256`); these are about the bibliography and are stale when IT
+ * changes (`bib.sha256`). One staleness key per file, the way `pdf/fresh` already works.
+ *
+ * 🔴 THE STEP NEVER FAILS THE BUILD. A build without network still builds the PDF; the reference
+ * step records `not-checked` and the lint rule says so, as a warning. Recording "not checked" as
+ * a pass would be the counter that counts what it never looked at.
+ */
+import { join } from "node:path";
+import type { AbsolutePath } from "./domain/paths.ts";
+import { sha256Hex } from "./domain/sha256.ts";
+import type { Files } from "./ports/files.ts";
+import type {
+  CheckReferences,
+  EntryVerdict,
+  ReferencesCheck,
+} from "./ports/check-references.ts";
+// @ts-expect-error — an ESLint rule module in .mjs, it has no types
+import { bibRange } from "../eslint-rules/paper-typography.mjs";
+
+export const REFERENCES_SCHEMA = 1;
+export const REFERENCES_FILE = "references.json";
+
+/** Where a paper's reference verdicts live — beside `paper.facts.json`. */
+export const referencesPath = (paperDir: string): string =>
+  join(paperDir, "_build", REFERENCES_FILE);
+
+const at = (p: string): AbsolutePath => p as AbsolutePath;
+const text = (files: Files, p: string): string | null => {
+  const b = files.readBytes(at(p));
+  return b === null ? null : new TextDecoder().decode(b);
+};
+
+/** The bibliography a paper carries: inside `paper.tex` (`filecontents`), else `refs.bib`. */
+export interface Bibliography {
+  readonly source: "paper.tex" | "refs.bib";
+  readonly text: string;
+  /** Where `text` starts in the source file — so a finding can point at an entry. */
+  readonly offset: number;
+}
+
+export function bibliographyOf(
+  files: Files,
+  paperDir: string,
+): Bibliography | null {
+  const tex = text(files, join(paperDir, "paper.tex"));
+  const inline = tex === null ? null : bibRange(tex);
+  if (inline)
+    return { source: "paper.tex", text: inline.body, offset: inline.bodyStart };
+  const bib = text(files, join(paperDir, "refs.bib"));
+  return bib === null ? null : { source: "refs.bib", text: bib, offset: 0 };
+}
+
+export const bibHash = (b: Bibliography): string =>
+  sha256Hex(new TextEncoder().encode(b.text));
+
+/** What `_build/references.json` holds. */
+export interface ReferencesDocument {
+  readonly schema: number;
+  readonly bib: { readonly source: string; readonly sha256: string };
+  readonly status: "checked" | "not-checked";
+  readonly why?: string;
+  readonly entries: readonly EntryVerdict[];
+}
+
+export const documentOf = (
+  bib: Bibliography,
+  check: ReferencesCheck,
+): ReferencesDocument => ({
+  schema: REFERENCES_SCHEMA,
+  bib: { source: bib.source, sha256: bibHash(bib) },
+  ...(check.kind === "checked"
+    ? { status: "checked" as const, entries: check.entries }
+    : { status: "not-checked" as const, why: check.why, entries: [] }),
+});
+
+/** The recorded verdicts, or null when there are none or they do not parse. */
+export function readReferences(
+  files: Files,
+  paperDir: string,
+): ReferencesDocument | null {
+  const raw = text(files, referencesPath(paperDir));
+  if (raw === null) return null;
+  try {
+    const d = JSON.parse(raw) as ReferencesDocument;
+    return d?.schema === REFERENCES_SCHEMA && Array.isArray(d.entries)
+      ? d
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The build step's work: check the bibliography and record the verdicts. Returns the one-line
+ * note the build prints. A checker that throws is recorded as `not-checked` — the step reports,
+ * it never refuses.
+ */
+export async function recordReferences(
+  files: Files,
+  paperDir: string,
+  check: CheckReferences,
+): Promise<string> {
+  const bib = bibliographyOf(files, paperDir);
+  if (bib === null) return "no bibliography — nothing to check";
+  let result: ReferencesCheck;
+  try {
+    result = await check(bib.text);
+  } catch (e) {
+    result = { kind: "not-checked", why: (e as Error).message };
+  }
+  const doc = documentOf(bib, result);
+  files.writeAtomic(
+    at(referencesPath(paperDir)),
+    new TextEncoder().encode(`${JSON.stringify(doc, null, 2)}\n`),
+  );
+  if (doc.status === "not-checked")
+    return `references NOT checked — ${doc.why ?? "no reason given"}; lint will say so`;
+  const bad = doc.entries.filter(
+    (e) => e.exists === "false" || e.authors === "mismatch",
+  ).length;
+  return `references: ${String(doc.entries.length)} checked, ${String(bad)} failing → _build/${REFERENCES_FILE}`;
+}

package/src/rules-config.harness.mjs

@@ -1,6 +1,6 @@
 /**
  * `rules-config.ts` — parsing the `rules` key into ESLint config blocks, and deriving which rules
- * paperlint ships. The end-to-end path (a consumer's package.json → `paperlint lint`) is in `cli.harness.mjs`;
+ * paperlint ships. The end-to-end path (a project's paperlint.json → `paperlint lint`) is in `cli.harness.mjs`;
  * this pins the parser's output shape and each refusal.
  */
 import assert from "node:assert/strict";
@@ -46,23 +46,39 @@ check(
     JSON.stringify(r),
   );
 }
+{
+  const r = parse({ "pdf/last-page-balance": "error" });
+  check(
+    "the object form is ONE block with no `files` — narrowed to each rule's own files later",
+    r.ok &&
+      JSON.stringify(r.value) ===
+        JSON.stringify([
+          {
+            basePath: "/consumer",
+            rules: { "pdf/last-page-balance": "error" },
+          },
+        ]),
+    JSON.stringify(r),
+  );
+}
 check(
   "both severity spellings are accepted",
   parse([{ rules: { "paper/typography": 0, "pdf/last-page-balance": "warn" } }])
     .ok,
 );
 const refusals = [
-  [{ a: 1 }, "S.rules must be a list"],
-  [[42], "S.rules[0] must be an object"],
-  [[{ rules: [] }], "S.rules[0].rules must be an object"],
-  [[{ files: [], rules: {} }], "S.rules[0].files must be a non-empty list"],
+  ["pdf/last-page-balance", 'S → "rules" must be { "<rule>": "<severity>" }'],
+  [{ a: 1 }, '"a" is not a rule paperlint ships'],
+  [[42], "S → rules[0] must be an object"],
+  [[{ rules: [] }], "S → rules[0].rules must be an object"],
+  [[{ files: [], rules: {} }], "S → rules[0].files must be a non-empty list"],
   [
     [{ files: ["x"], ignores: [1], rules: {} }],
-    "S.rules[0].ignores must be a non-empty list",
+    "S → rules[0].ignores must be a non-empty list",
   ],
   [
     [{ languageOptions: {}, rules: {} }],
-    'S.rules[0]: unknown key "languageOptions"',
+    'S → rules[0]: unknown key "languageOptions"',
   ],
   [
     [{ rules: { "markdown/no-html": "error" } }],
@@ -70,7 +86,7 @@ const refusals = [
   ],
   [
     [{ rules: { "paper/typography": ["loud"] } }],
-    'S.rules[0].rules["paper/typography"]: ["loud"] is not a severity',
+    'S → rules[0].rules["paper/typography"]: ["loud"] is not a severity',
   ],
 ];
 for (const [raw, says] of refusals) {

package/src/rules-config.ts

@@ -44,6 +44,7 @@ export type Parsed<T> =
   | { readonly ok: false; readonly error: string };
 
 const SEVERITIES: readonly unknown[] = ["off", "warn", "error", 0, 1, 2];
+
 const BLOCK_KEYS = new Set(["files", "ignores", "rules"]);
 
 const bad = <T>(error: string): Parsed<T> => ({ ok: false, error });
@@ -67,7 +68,7 @@ function parseEntry(v: unknown): RuleEntry | null {
 
 /**
  * A `rules` object — rule id → severity or `[severity, ...options]` — with only the rules paperlint
- * ships. Read from the package.json blocks and from a paper's `paperlint.json`.
+ * ships. Read from every `paperlint.json`, the root's and each paper's.
  *
  * @param where  the key path to name in messages, e.g. `package.json → "paperlint".rules[0].rules`
  */
@@ -108,17 +109,20 @@ const globsOf = (o: Record<string, unknown>) => ({
   ...(o["ignores"] ? { ignores: o["ignores"] as string[] } : {}),
 });
 
+const isRecord = (v: unknown): v is Record<string, unknown> =>
+  typeof v === "object" && v !== null && !Array.isArray(v);
+
 /** One element of the `rules` list. */
 function parseBlock(
   v: unknown,
   at: string,
   ctx: { shipped: ReadonlySet<string>; baseDir: string },
 ): Parsed<RuleBlock> {
-  if (typeof v !== "object" || v === null || Array.isArray(v))
+  if (!isRecord(v))
     return bad(
       `${at} must be an object like { "files": [...], "rules": {...} }`,
     );
-  const o = v as Record<string, unknown>;
+  const o = v;
   const extra = Object.keys(o).filter((k) => !BLOCK_KEYS.has(k));
   if (extra.length)
     return bad(
@@ -135,10 +139,12 @@ function parseBlock(
 }
 
 /**
- * The `rules` key → config blocks, or one error naming the key path.
+ * The `rules` key → config blocks, or one error naming the key path. Two shapes, at every level:
+ * `{ id: severity }` is one block over every paper file under `baseDir`; a list is ESLint blocks
+ * (`files`, `ignores`, `rules`), their globs relative to `baseDir`.
  *
  * @param raw      the value under `rules` (undefined when absent)
- * @param where    how the settings are named in messages, e.g. `package.json → "paperlint"`
+ * @param where    how the settings are named in messages, e.g. `paperlint.json`
  * @param shipped  the rule ids paperlint ships (`shippedRuleIds`)
  * @param baseDir  the directory of the file holding the settings
  */
@@ -149,13 +155,19 @@ export function parseRuleBlocks(
   baseDir: string,
 ): Parsed<readonly RuleBlock[]> {
   if (raw === undefined) return { ok: true, value: [] };
+  if (isRecord(raw)) {
+    const rules = parseRuleEntries(raw, `${where} → "rules"`, shipped);
+    return rules.ok
+      ? { ok: true, value: [{ basePath: baseDir, rules: rules.value }] }
+      : rules;
+  }
   if (!Array.isArray(raw))
     return bad(
-      `${where}.rules must be a list of blocks, like ESLint's flat config: [{ "files": [...], "rules": {...} }]`,
+      `${where} → "rules" must be { "<rule>": "<severity>" }, or a list of blocks like ESLint's flat config: [{ "files": [...], "rules": {...} }]`,
     );
   const out: RuleBlock[] = [];
   for (const [i, v] of raw.entries()) {
-    const b = parseBlock(v, `${where}.rules[${i}]`, { shipped, baseDir });
+    const b = parseBlock(v, `${where} → rules[${i}]`, { shipped, baseDir });
     if (!b.ok) return b;
     out.push(b.value);
   }

package/src/structure.harness.mjs

@@ -72,7 +72,9 @@ 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 authors/.test(at("no-scorecard")[0].message),
+      /stages, sources or research question/.test(
+        at("no-scorecard")[0].message,
+      ),
   );
   check(
     "and the consequence names THIS directory by name",

package/src/structure.ts

@@ -25,7 +25,7 @@
 import { readdirSync, existsSync } from "node:fs";
 import { join, relative, basename, isAbsolute, sep } from "node:path";
 import type { StructureConfig, StructureFinding } from "./types.ts";
-import { PAPER_SETTINGS_FILE } from "../lib/paper-config.mjs";
+import { CONFIG_FILE } from "../lib/paper-config.mjs";
 
 /** The requirements after the consumer's config is laid over the defaults. */
 type Rules = Required<StructureConfig>;
@@ -38,7 +38,7 @@ type Rules = Required<StructureConfig>;
  * byte-compared by the `paper/stages` rule anyway.
  */
 export const STRUCTURE_DEFAULTS = {
-  markers: ["PIPELINE-STATUS.md", "paper.tex", "paper.md", PAPER_SETTINGS_FILE],
+  markers: ["PIPELINE-STATUS.md", "paper.tex", "paper.md", CONFIG_FILE],
   require: ["PIPELINE-STATUS.md"],
   requireOneOf: [["paper.tex", "paper.md"]],
   ignore: [],
@@ -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/author-list\` read this file, so nothing \`${dirName}\` declares about its stages, sources or authors is checked`;
+    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 `declared as required by your \`structure\` configuration`;
 }
 

package/src/tex-requirements.ts

@@ -26,7 +26,7 @@ import { join } from "node:path";
 // eslint-disable-next-line boundaries/dependencies -- legacy layer, moves behind a port in #76
 import Ajv from "ajv";
 import { packageVenuesDir } from "../skills/paper-pipeline/scripts/consumer.mjs";
-import { PAPER_SETTINGS_FILE } from "../lib/paper-config.mjs";
+import { CONFIG_FILE } from "../lib/paper-config.mjs";
 
 /** CTAN package name → the names that prove it is installed. */
 export type PackageProofs = Readonly<Record<string, readonly string[]>>;
@@ -298,7 +298,7 @@ export function requirementsFor(
   const base = readProfile(dir, BASE_PROFILE);
   return preset === null
     ? {
-        source: `the base set (no venue preset in ${PAPER_SETTINGS_FILE})`,
+        source: `the base set (no venue preset in ${CONFIG_FILE})`,
         tex: base,
       }
     : {

package/src/types.ts

@@ -5,29 +5,27 @@ import type { RuleBlock } from "./rules-config.ts";
  * in someone's head: a typo in a config key read as "field not set", not as an error.
  */
 
-/** The consumer's settings — the `paperlint` key of its `package.json`. */
+/**
+ * The project's settings — the root `paperlint.json`, optional. Every key is optional; the key list
+ * (and which keys a paper's own `paperlint.json` may also hold) is `SETTINGS_KEYS` in
+ * lib/paper-config.mjs.
+ */
 export interface PaperlintConfig {
-  /** 🔴 REQUIRED. The paper director(ies), relative to the config file ITSELF. The field name is
+  /** The paper director(ies), relative to the project root. Default `papers`. The field name is
    * `PAPERS_DIR_FIELD` in lib/paper-config.mjs; code reads it through `papersDirOf()` in cli.ts. */
   papersDir?: string | string[];
-  /** The command that prints the author list from .bib — each corpus has its own. */
-  authorListCommand?: string;
-  /** Per-paper typography debt: how many findings already exist; the number may only go down. */
-  typographyDebt?: Record<string, Record<string, number>>;
-  /** Frontmatter fields required for review notes, and the permitted values of each. */
-  docFields?: Record<string, { values: string[] }>;
-  /** Ignore review findings older than this date. */
-  reviewSince?: string;
-  /** How many findings a cold read must produce to count as a cold read. */
-  minFindings?: number;
-  /** The word with which review notes introduce the cause. */
-  causeMarker?: string;
   /** Which files a paper directory must carry; `false` turns the check off entirely. */
   structure?: StructureConfig | false;
-  /** REMOVED — `paperlint build` compiles the paper itself. Still typed so a leftover key can be named. */
-  buildScripts?: unknown;
   /** ESLint config blocks appended after paperlint's own — PARSED by `parseSettings` in cli.ts. */
   rules?: readonly RuleBlock[];
+  /** The default venue preset of every paper that names none (`src/paper-settings.ts`). */
+  extends?: string | null;
+  /** The default kind of paper. */
+  kind?: string;
+  /** The default path of the built PDF, relative to each paper. */
+  pdf?: string;
+  /** A note for humans; ignored. */
+  $comment?: unknown;
 }
 
 export interface StructureConfig {
@@ -47,6 +45,8 @@ export interface Args {
   paths: string[];
   config: string | null;
   json: boolean;
+  /** `--fix`: `lint` writes every fix a rule offers, then reports what is left. */
+  fix: boolean;
   all: boolean;
   dryRun: boolean;
   /** `--check`: `toolchain` reports what is missing and changes nothing. */
@@ -102,5 +102,17 @@ export interface BuildResult {
 
 /** The result of reading the config: either data, or the exit code the caller exits with. */
 export type ConfigRead =
-  | { opts: PaperlintConfig; configPath: string | null; code?: undefined }
-  | { code: number; opts?: undefined; configPath?: undefined };
+  | {
+      opts: PaperlintConfig;
+      /** The root `paperlint.json`, or null when the project has none. */
+      configPath: string | null;
+      /** The project root: `papersDir` and the `rules` globs are relative to it. */
+      root: string;
+      code?: undefined;
+    }
+  | {
+      code: number;
+      opts?: undefined;
+      configPath?: undefined;
+      root?: undefined;
+    };

package/src/venue-rules.test.ts

@@ -173,7 +173,7 @@ describe("a paper that meets its venue", () => {
 });
 
 describe("a paper that names no venue", () => {
-  it("no paperlint.json (a paper from before 2.1.0): every rule is silent, even with no facts and no PDF", () => {
+  it("no paperlint.json: every rule is silent, even with no facts and no PDF", () => {
     expect(lint({ venue: undefined, facts: null, pdf: null })).toEqual([]);
   });
 
@@ -228,16 +228,6 @@ describe("pdf/profile — the declaration must resolve, or nothing is judged", (
     expect(fs[0]?.message).toMatch(text);
   });
 
-  it("🔴 a venue.json left from before 2.1.0 is not read — pdf/profile says to run `paperlint init`", () => {
-    const fs = lint({
-      facts: null,
-      pdf: null,
-      extra: { [`${PAPER}/venue.json`]: JSON.stringify(DECL) },
-    });
-    expect(ids(fs)).toEqual(["pdf/profile:legacySettings"]);
-    expect(fs[0]?.message).toMatch(/npx paperlint init/);
-  });
-
   it("a profile that does not parse is named with the file", () => {
     const fs = lint({
       venue: { extends: "paperlint:mine", kind: "short" },
@@ -302,6 +292,25 @@ describe("pdf/profile — the kind", () => {
   });
 });
 
+describe("pdf/profile — a preset with no kinds", () => {
+  it("🔴 a preset with NO kinds (acm-sigconf) and no `kind`: nothing to pick, no finding", () => {
+    const fs = lint({
+      venue: { extends: "paperlint:acm-sigconf" },
+      facts: withFacts((f) => (f.body_pages = 99)),
+    });
+    expect(ids(fs).filter((id) => id.startsWith("pdf/profile"))).toEqual([]);
+  });
+
+  it("…but a `kind` named against a kindless preset is still an error that says it has none", () => {
+    const fs = lint({
+      venue: { extends: "paperlint:acm-sigconf", kind: "short" },
+    });
+    const profile = fs.filter((f) => f.rule === "pdf/profile");
+    expect(ids(profile)).toEqual(["pdf/profile:kindUnknown"]);
+    expect(profile[0]?.message).toMatch(/its kinds: \(none\)/);
+  });
+});
+
 describe("pdf/measured — a paper that names a venue and was not measured says so (warn)", () => {
   it("no facts file: one finding, from pdf/measured only", () => {
     const fs = lint({ venue: DECL, facts: null, pdf: null });