paperlint 3.0.0 → 3.1.1

package/src/new-paper.ts

@@ -98,12 +98,85 @@ function scorecardAndSource(dir: string, format: PaperFormat): string[] {
   return hasSource ? [STATUS_FILE] : [STATUS_FILE, SOURCE_FILE[format]];
 }
 
-// Documented in README.md#starting-a-paper — update it when this changes.
+/** The venue `paperlint new --venue` chose: what goes into the new paper's `paperlint.json`. */
+export interface VenueSetting {
+  /** `paperlint:<name>`, or a path relative to the paper's `paperlint.json`. */
+  readonly extends: string;
+  readonly kind: string | null;
+}
+
+/**
+ * The template's `paperlint.json` with the chosen venue written in. The template's `$comment`
+ * explains how to choose one, so it goes once one is chosen. A template that is not plain JSON (a
+ * project's own, with comments) cannot be edited safely and is refused by name.
+ */
+function withVenue(
+  text: string,
+  src: string,
+  venue: VenueSetting,
+): { ok: true; text: string } | { ok: false; reason: string } {
+  let obj: Record<string, unknown>;
+  try {
+    obj = JSON.parse(text) as Record<string, unknown>;
+  } catch {
+    return {
+      ok: false,
+      reason: `--venue cannot be written into ${src}: it is not plain JSON — set "extends" by hand`,
+    };
+  }
+  const out: Record<string, unknown> = { ...obj, extends: venue.extends };
+  delete out["$comment"];
+  if (venue.kind !== null) out["kind"] = venue.kind;
+  return { ok: true, text: `${JSON.stringify(out, null, 2)}\n` };
+}
+
+/** A file `newPaper` will write: its text, and which template it came from. */
+interface Planned {
+  readonly file: string;
+  readonly text: string;
+  readonly from: "project" | "package";
+}
+
+/** One file's text from its template — the project's override first, the package's second. */
+function fromTemplate(
+  file: string,
+  {
+    papersRoot,
+    packageTemplates,
+    name,
+    venue,
+  }: {
+    papersRoot: string;
+    packageTemplates: string;
+    name: string;
+    venue: VenueSetting | null;
+  },
+): { ok: true; value: Planned } | { ok: false; reason: string } {
+  const project = join(papersRoot, OVERRIDE_DIR, file);
+  const [src, from] = existsSync(project)
+    ? [project, "project" as const]
+    : [join(packageTemplates, file), "package" as const];
+  // A missing package template is a broken install, not a reason to write an empty file.
+  if (!existsSync(src))
+    return { ok: false, reason: `no template for ${file}: ${src} is missing` };
+  const text = readFileSync(src, "utf8").split("{{name}}").join(name);
+  if (file !== CONFIG_FILE || venue === null)
+    return { ok: true, value: { file, text, from } };
+  const edited = withVenue(text, src, venue);
+  return edited.ok
+    ? { ok: true, value: { file, text: edited.text, from } }
+    : edited;
+}
+
+// Documented in README.md#getting-started — update it when this changes.
 export function newPaper(
   papersRoot: string,
   name: string,
   format: PaperFormat,
-  { packageTemplates = PACKAGE_TEMPLATES }: { packageTemplates?: string } = {},
+  {
+    packageTemplates = PACKAGE_TEMPLATES,
+    venue = null,
+  }: { packageTemplates?: string; venue?: VenueSetting | null } = {},
 ): NewPaperResult {
   const problem = nameProblem(name);
   if (problem) return { ok: false, reason: problem };
@@ -113,26 +186,20 @@ export function newPaper(
     return { ok: false, reason: `${dir} exists and is not a directory` };
 
   const files: FileOutcome[] = [];
-  const toWrite: { file: string; text: string; from: "project" | "package" }[] =
-    [];
+  const toWrite: Planned[] = [];
   for (const file of wantedFiles(dir, format)) {
     if (existsSync(join(dir, file))) {
       files.push({ file, status: "kept" });
       continue;
     }
-    const project = join(papersRoot, OVERRIDE_DIR, file);
-    const fromPackage = join(packageTemplates, file);
-    const [src, from] = existsSync(project)
-      ? [project, "project" as const]
-      : [fromPackage, "package" as const];
-    // A missing package template is a broken install, not a reason to write an empty file.
-    if (!existsSync(src))
-      return {
-        ok: false,
-        reason: `no template for ${file}: ${src} is missing`,
-      };
-    const text = readFileSync(src, "utf8").split("{{name}}").join(name);
-    toWrite.push({ file, text, from });
+    const planned = fromTemplate(file, {
+      papersRoot,
+      packageTemplates,
+      name,
+      venue,
+    });
+    if (!planned.ok) return planned;
+    toWrite.push(planned.value);
   }
   // Read every template before writing any file, so a missing one leaves no half-made folder.
   mkdirSync(dir, { recursive: true });

package/src/paper-files.test.ts

@@ -23,6 +23,7 @@ import { buildConfig, run } from "./cli.ts";
 import {
   narrowToOwners,
   ownedPatterns,
+  ownedScopes,
   ruleOwners,
   scopeToOwned,
 } from "./paper-files.ts";
@@ -160,6 +161,73 @@ describe("`rules` blocks reach only the files each rule is written for", () => {
   });
 });
 
+describe("🔴 a generated block never reaches a file paperlint does not lint (#101)", () => {
+  // A venue preset with `rules` (agenticdev turns on pdf/last-page-balance) became a block over
+  // every paper file. `pdf` is registered for every file, so the block was not narrowed, and the
+  // siblings index — which the sibling-card block excludes — matched a block with no language:
+  // ESLint parsed it as JavaScript ("Parsing error: Assigning to rvalue").
+  const SIBLINGS = {
+    "papers/a/siblings/README.md": "# Siblings\n\n- [x](smith2025.md)\n",
+    "papers/a/siblings/smith2025.md": "---\nread: full\n---\n# Smith 2025\n",
+  };
+
+  it.each([
+    [
+      "a venue preset's rules",
+      {
+        "papers/a/paperlint.json": JSON.stringify({
+          extends: "paperlint:agenticdev",
+        }),
+      },
+    ],
+    [
+      // `papers/**` alone would not show it: ESLint does not lint a file on a pattern ending in
+      // `/**`, it only applies such a block to files something else claims.
+      "a root block over every markdown file",
+      {
+        "paperlint.json": JSON.stringify({
+          rules: [
+            {
+              files: ["papers/**/*.md", "papers/**/*.tex"],
+              rules: { "pdf/last-page-balance": "warn" },
+            },
+          ],
+        }),
+      },
+    ],
+    [
+      "a paper's own { id: severity }",
+      {
+        "papers/a/paperlint.json": JSON.stringify({
+          rules: { "pdf/last-page-balance": "warn" },
+        }),
+      },
+    ],
+  ])(
+    "%s: the siblings index is not parsed, the cards still are",
+    async (_, settings) => {
+      const root = project({ ...SIBLINGS, ...settings });
+      const r = await lint(root);
+      const results = JSON.parse(r.out) as {
+        filePath: string;
+        messages: { ruleId: string | null; message: string }[];
+      }[];
+      // Guards: the class — no file reaches ESLint's default JavaScript parser.
+      expect(
+        results.flatMap((x) => x.messages).filter((m) => m.ruleId === null),
+      ).toEqual([]);
+      expect(linted(r.out)).not.toContain(
+        join(root, "papers/a/siblings/README.md"),
+      );
+      // Guards: the other half — narrowing did not drop the files the block is for.
+      expect(linted(r.out)).toContain(
+        join(root, "papers/a/siblings/smith2025.md"),
+      );
+      expect(linted(r.out)).toContain(join(root, "papers/a/paper.tex"));
+    },
+  );
+});
+
 describe("`rules` blocks — where the rule lands", () => {
   it("on its own files and on no other", async () => {
     const root = project();
@@ -206,11 +274,60 @@ describe("paper-files — the pieces", () => {
     expect(ownedPatterns(own)).toEqual(["**/a.md", "**/b.md", "**/c.md"]);
   });
 
-  it("a rule's owner is where its plugin is registered; a global plugin owns every file", () => {
+  it("a rule's owner is where its plugin is registered; a global plugin owns every OWNED file", () => {
     const owners = ruleOwners(own);
-    expect(owners.get("g/any")).toBeNull();
-    expect(owners.get("p/one")).toEqual(["**/a.md"]);
-    expect(owners.get("p/two")).toEqual(["**/b.md", "**/c.md"]);
+    expect(owners.get("g/any")).toEqual([
+      { files: ["**/a.md", "**/b.md", "**/c.md"], ignores: [] },
+    ]);
+    expect(owners.get("p/one")).toEqual([{ files: ["**/a.md"], ignores: [] }]);
+    expect(owners.get("p/two")).toEqual([
+      { files: ["**/b.md", "**/c.md"], ignores: [] },
+    ]);
+  });
+
+  it("🔴 a scope keeps its block's exceptions, and a global plugin inherits them (#101)", () => {
+    const withIndex = [
+      ...own,
+      {
+        files: ["**/s/*.md"],
+        ignores: ["**/s/README.md"],
+        plugins: { s: { rules: { card: {} } } },
+      },
+    ];
+    expect(ownedScopes(withIndex)).toEqual([
+      { files: ["**/a.md", "**/b.md", "**/c.md"], ignores: [] },
+      { files: ["**/s/*.md"], ignores: ["**/s/README.md"] },
+    ]);
+    // Guards: the defect — the plugin registered for every file used to keep any glob, and so
+    // reached the index the card block excludes.
+    expect(ruleOwners(withIndex).get("g/any")).toEqual(ownedScopes(withIndex));
+    expect(
+      narrowToOwners(
+        {
+          basePath: "/x",
+          files: ["papers/**/*.md"],
+          rules: { "g/any": "warn" },
+        },
+        ruleOwners(withIndex),
+      ).at(-1),
+    ).toEqual({
+      basePath: "/x",
+      files: [["papers/**/*.md", "**/s/*.md"]],
+      ignores: ["**/s/README.md"],
+      rules: { "g/any": "warn" },
+    });
+  });
+});
+
+describe("paper-files — blocks that carry no rules", () => {
+  it("a plugin with only a language registers no rule; a block with no files owns no pattern of its own", () => {
+    const own = [
+      { plugins: { tex: { languages: {} } } },
+      { ignores: ["**/x.md"], plugins: { tex: { languages: {} } } },
+      { files: ["**/a.md"], plugins: { p: { rules: { one: {} } } } },
+    ];
+    expect([...ruleOwners(own).keys()]).toEqual(["p/one"]);
+    expect(ownedPatterns(own)).toEqual(["**/a.md"]);
   });
 });
 
@@ -249,7 +366,7 @@ describe("paper-files — narrowing a block", () => {
       },
       {
         basePath: "/x",
-        files: ["papers/**"],
+        files: ["**/a.md", "**/b.md", "**/c.md"].map((o) => ["papers/**", o]),
         ignores: ["papers/old/**"],
         rules: { "g/any": "off" },
       },

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[];
 
@@ -53,12 +71,49 @@ export interface ScopedBlock {
   readonly rules: Readonly<Record<string, RuleEntry>>;
 }
 
-const globsOf = (b: Block): string[] =>
-  (b.files ?? []).filter((f): f is string => typeof f === "string");
+/** A block's `files`, the string globs only. */
+const globsOf = (files: readonly unknown[]): string[] =>
+  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)
+      .flatMap((b) =>
+        b.files === undefined
+          ? []
+          : [{ files: globsOf(b.files), 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 +139,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.files), 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 +178,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/paper-settings.test.ts

@@ -118,6 +118,26 @@ describe("readPaperSettings", () => {
   });
 });
 
+describe("readPaperSettings — a root paperlint.json that cannot be used", () => {
+  const ROOT = "/work";
+  const withFiles = (f: Record<string, string>) =>
+    memoryFiles({ [`${ROOT}/package.json`]: "{}", ...f });
+
+  it("a root file that does not parse, or names a field of the wrong type, is the paper's problem too", () => {
+    const broken = (root: string) =>
+      readPaperSettings(withFiles({ [`${ROOT}/paperlint.json`]: root }), PAPER);
+    const notJson = broken("{ nope");
+    expect(!notJson.ok && notJson.error.kind).toBe("broken");
+    expect(broken('{"kind":3}')).toEqual({
+      ok: false,
+      error: {
+        kind: "broken",
+        why: expect.stringMatching(/^the root paperlint\.json: .*kind/),
+      },
+    });
+  });
+});
+
 describe("readPaperSettings — the root paperlint.json's defaults, the paper's file over them", () => {
   const ROOT = "/work";
   const withFiles = (f: Record<string, string>) =>

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/pdf-facts.harness.mjs

@@ -11,17 +11,14 @@ import { writeFileSync, mkdtempSync, realpathSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { createChecker } from "../lib/check.mjs";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const FIX = resolve(HERE, "..", "fixtures", "pdf-facts");
 const { readPdf } = await import(join(HERE, "pdf-facts.ts"));
 const { classifyLastPage } = await import(join(HERE, "pdf-geometry.ts"));
 
-let n = 0;
-const check = (label, cond, detail = "") => {
-  assert.ok(cond, detail ? `${label} — ${detail}` : label);
-  n++;
-};
+const check = createChecker();
 
 const read = async (name) => {
   const r = await readPdf(join(FIX, name));
@@ -184,5 +181,5 @@ try {
 }
 
 console.log(
-  `✓ ${String(n)} assertions passed — pdf-facts: pdf.js on real PDFs agrees with poppler, and says what it cannot read`,
+  `✓ ${String(check.count)} assertions passed — pdf-facts: pdf.js on real PDFs agrees with poppler, and says what it cannot read`,
 );