paperlint 6.3.0 → 7.1.0

package/src/preset-card-rule.test.ts

@@ -0,0 +1,267 @@
+/**
+ * `preset/card-rules` through real ESLint, on a copy of the shipped presets and the rule pages: the
+ * section a card must hold, the findings for each way a card can be wrong, and what `--fix` writes.
+ */
+import {
+  cpSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { ESLint } from "eslint";
+import markdown from "@eslint/markdown";
+import { describe, expect, it } from "vitest";
+import { nodeFiles } from "./adapters/node/index.ts";
+import { eslintConfig } from "./cli.ts";
+import { presetsDir } from "./package-dirs.ts";
+import {
+  entryParts,
+  presetCardRules,
+  SECTION_END,
+  SECTION_START,
+} from "./preset-card-rule.ts";
+import { useTempDir } from "../test/support.ts";
+
+const REPO = join(presetsDir(), "..");
+const root = useTempDir("paperlint-card-rule-");
+cpSync(presetsDir(), join(root, "presets"), { recursive: true });
+cpSync(join(REPO, "docs", "rules"), join(root, "docs", "rules"), {
+  recursive: true,
+});
+cpSync(join(REPO, "docs", "rules.md"), join(root, "docs", "rules.md"));
+const P = join(root, "presets");
+
+const eslint = (fix = false) =>
+  new ESLint({
+    cwd: root,
+    fix,
+    overrideConfigFile: true,
+    // Through cli.ts's one adapter from paperlint's blocks to ESLint's type (`eslintConfig`).
+    overrideConfig: eslintConfig([
+      {
+        files: ["presets/*.md"],
+        plugins: {
+          markdown,
+          preset: {
+            rules: presetCardRules({
+              files: nodeFiles,
+              venuesDir: P,
+              docsRoot: root,
+            }),
+          },
+        },
+        language: "markdown/gfm",
+        rules: { "preset/card-rules": "error" },
+      },
+    ]),
+  });
+
+/** The findings for one card, as `messageId`-free text: rule id and message. */
+async function findings(card: string): Promise<string[]> {
+  const [r] = await eslint().lintFiles([join(P, card)]);
+  return (r?.messages ?? []).map((m) => `${String(m.ruleId)}: ${m.message}`);
+}
+
+/** The card after `eslint --fix`, written to disk as ESLint would. */
+async function fixed(card: string): Promise<string> {
+  const results = await eslint(true).lintFiles([join(P, card)]);
+  await ESLint.outputFixes(results);
+  return readFileSync(join(P, card), "utf8");
+}
+
+/** The generated section of a card's text, markers included. */
+const sectionOf = (text: string): string =>
+  text.slice(
+    text.indexOf(SECTION_START),
+    text.indexOf(SECTION_END) + SECTION_END.length,
+  );
+
+const STALE =
+  "preset/card-rules: the rules section does not match the preset beside this card — run `npx eslint --fix` on this file to rewrite it from the preset";
+
+describe("the shipped cards", () => {
+  it("every shipped card holds the section its preset resolves to", async () => {
+    const results = await eslint().lintFiles([join(P, "*.md")]);
+    // Guards: a glob that matched nothing lints nothing and reports clean.
+    expect(results.map((r) => r.filePath.slice(P.length + 1)).sort()).toEqual([
+      "acm-sigconf.md",
+      "agenticdev.md",
+      "aidc.md",
+      "aisec.md",
+      "ieee-conference.md",
+      "msr.md",
+      "realm.md",
+      "tex-base.md",
+    ]);
+    expect(results.flatMap((r) => r.messages)).toEqual([]);
+  });
+
+  it("agenticdev: its own rules, linked to their page or to the index, and what it extends", async () => {
+    const text = readFileSync(join(P, "agenticdev.md"), "utf8");
+    writeFileSync(
+      join(P, "agenticdev.md"),
+      text.replace(sectionOf(text), `${SECTION_START}\n${SECTION_END}`),
+    );
+    expect(await findings("agenticdev.md")).toEqual([STALE]);
+    // Guards: --fix writes the resolved preset — the section is the generated output, compared whole.
+    expect(sectionOf(await fixed("agenticdev.md"))).toBe(
+      [
+        SECTION_START,
+        "<!-- prettier-ignore-start -->",
+        "<!-- Generated from agenticdev.jsonc by `npx eslint --fix` (rule preset/card-rules). Edit the preset, not this section. -->",
+        "",
+        "**`paperlint:agenticdev`** — venue preset for AgenticDev · call for papers: <https://conf.researchr.org/home/ase-2026/agenticdev-2026> · extends `paperlint:acm-sigconf`",
+        "",
+        "| rule | severity | options | set in |",
+        "| --- | --- | --- | --- |",
+        '| [`pdf/last-page-balance`](../docs/rules.md) | error | `{"tolerancePt":120}` | this preset |',
+        '| [`tex/heading-case`](../docs/rules/tex/heading-case.md) | error | `{"title":"chicago-headline","headings":"chicago-headline"}` | this preset |',
+        "",
+        "<!-- prettier-ignore-end -->",
+        SECTION_END,
+      ].join("\n"),
+    );
+    expect(await findings("agenticdev.md")).toEqual([]);
+  });
+});
+
+describe("the origin column: set here, or inherited from the file of the chain that set it", () => {
+  it("a venue over agenticdev: its own rule is its own, agenticdev's are inherited", async () => {
+    writeFileSync(
+      join(P, "fixture-venue.jsonc"),
+      JSON.stringify({
+        type: "venue",
+        name: "Fixture",
+        url: "https://example.org/cfp",
+        extends: "paperlint:agenticdev",
+        rules: { "pdf/body-size": "off", "tex/register": ["warn", "a|b"] },
+      }),
+    );
+    writeFileSync(join(P, "fixture-venue.md"), "# Fixture\n");
+    expect(await findings("fixture-venue.md")).toEqual([
+      `preset/card-rules: this card has no generated rules section — run \`npx eslint --fix\` on this file to append one (between ${SECTION_START} and ${SECTION_END})`,
+    ]);
+    const text = await fixed("fixture-venue.md");
+    // Guards: an inherited rule names its parent, an own rule says so; an entry without options
+    // shows a dash, and a `|` in the options is escaped so the table keeps its columns.
+    expect(text.split("\n").filter((l) => l.startsWith("| ["))).toEqual([
+      "| [`pdf/body-size`](../docs/rules/pdf/body-size.md) | off | — | this preset |",
+      '| [`pdf/last-page-balance`](../docs/rules.md) | error | `{"tolerancePt":120}` | inherited from `paperlint:agenticdev` |',
+      '| [`tex/heading-case`](../docs/rules/tex/heading-case.md) | error | `{"title":"chicago-headline","headings":"chicago-headline"}` | inherited from `paperlint:agenticdev` |',
+      '| [`tex/register`](../docs/rules/tex/register.md) | warn | `"a\\|b"` | this preset |',
+    ]);
+    // Appended after one blank line to a card that ended with a newline.
+    expect(text.startsWith(`# Fixture\n\n${SECTION_START}\n`)).toBe(true);
+    expect(await findings("fixture-venue.md")).toEqual([]);
+  });
+
+  it("a card without a final newline gets one before the appended section", async () => {
+    writeFileSync(join(P, "fixture-venue.md"), "# Fixture");
+    expect(
+      (await fixed("fixture-venue.md")).startsWith(
+        `# Fixture\n\n${SECTION_START}\n`,
+      ),
+    ).toBe(true);
+  });
+});
+
+describe("a chain that leaves presets/", () => {
+  it("a rule set by a preset outside presets/ names that file by its path from the card", async () => {
+    mkdirSync(join(root, "shared"), { recursive: true });
+    writeFileSync(
+      join(root, "shared", "fixture-base.jsonc"),
+      JSON.stringify({
+        type: "family",
+        extends: "paperlint:acm-sigconf",
+        rules: { "pdf/body-size": "warn" },
+      }),
+    );
+    writeFileSync(
+      join(P, "fixture-outside.jsonc"),
+      JSON.stringify({
+        type: "venue",
+        name: "Outside",
+        url: "https://example.org/cfp",
+        extends: "../shared/fixture-base.jsonc",
+      }),
+    );
+    writeFileSync(join(P, "fixture-outside.md"), "# Outside\n");
+    // Guards: a file of the chain that is not a shipped preset is not given a `paperlint:` name
+    // that would resolve nowhere; it is the path a reader can open from the card.
+    expect(
+      (await fixed("fixture-outside.md"))
+        .split("\n")
+        .filter((l) => l.startsWith("| [")),
+    ).toEqual([
+      "| [`pdf/body-size`](../docs/rules/pdf/body-size.md) | warn | — | inherited from `../shared/fixture-base.jsonc` |",
+    ]);
+    rmSync(join(P, "fixture-outside.jsonc"));
+    rmSync(join(P, "fixture-outside.md"));
+  });
+});
+
+describe("a family the shipped presets do not extend", () => {
+  it("says so, and that its chain sets no rule", async () => {
+    writeFileSync(
+      join(P, "fixture-family.jsonc"),
+      JSON.stringify({ type: "family", extends: "paperlint:acm-sigconf" }),
+    );
+    writeFileSync(join(P, "fixture-family.md"), "# Family\n");
+    expect(
+      sectionOf(await fixed("fixture-family.md"))
+        .split("\n")
+        .slice(4, 7),
+    ).toEqual([
+      "**`paperlint:fixture-family`** — template family, no venue of its own · extends `paperlint:acm-sigconf` · extended by no shipped preset",
+      "",
+      "No preset of this chain sets a rule: under it, every rule keeps paperlint's default.",
+    ]);
+    rmSync(join(P, "fixture-family.jsonc"));
+    rmSync(join(P, "fixture-family.md"));
+  });
+});
+
+describe("a card that cannot be judged, or whose markers are not a pair", () => {
+  it("one marker without the other is reported, and not fixed", async () => {
+    for (const marker of [SECTION_START, SECTION_END]) {
+      writeFileSync(join(P, "fixture-venue.md"), `# Fixture\n\n${marker}\n`);
+      expect(await findings("fixture-venue.md")).toEqual([
+        `preset/card-rules: the generated rules section needs both markers, ${SECTION_START} and ${SECTION_END}, each on its own line`,
+      ]);
+      expect(await fixed("fixture-venue.md")).toBe(`# Fixture\n\n${marker}\n`);
+    }
+  });
+
+  it("a card with no preset beside it names the file it looked for", async () => {
+    writeFileSync(join(P, "orphan.md"), "# Orphan\n");
+    expect(await findings("orphan.md")).toEqual([
+      `preset/card-rules: a preset card describes the preset beside it, and there is none: ${join(P, "orphan.jsonc")}`,
+    ]);
+    rmSync(join(P, "orphan.md"));
+  });
+
+  it("a card beside a preset that does not resolve says why", async () => {
+    writeFileSync(
+      join(P, "broken.jsonc"),
+      JSON.stringify({ type: "family", extends: "x" }),
+    );
+    writeFileSync(join(P, "broken.md"), "# Broken\n");
+    expect(await findings("broken.md")).toEqual([
+      `preset/card-rules: the preset beside this card does not resolve, so its rules cannot be listed: "extends": "x" — a preset is \`paperlint:<name>\` (shipped) or a path starting with ./ or ../ (your own); npm presets: not yet supported. Did you mean "paperlint:x"?`,
+    ]);
+    rmSync(join(P, "broken.jsonc"));
+    rmSync(join(P, "broken.md"));
+  });
+});
+
+describe("entryParts", () => {
+  it.each<[unknown, { severity: string; options: string }]>([
+    ["error", { severity: "error", options: "" }],
+    [2, { severity: "2", options: "" }],
+    [["warn", { a: 1 }, "b"], { severity: "warn", options: '{"a":1}, "b"' }],
+  ])("%j", (entry, want) => {
+    expect(entryParts(entry)).toEqual(want);
+  });
+});

package/src/preset-card-rule.ts

@@ -0,0 +1,384 @@
+/**
+ * `preset/card-rules` — the rules table in a preset's card, generated from the preset beside it.
+ *
+ * Every shipped preset has a card, `presets/<name>.md` beside `presets/<name>.jsonc`: what the venue
+ * or the template family is, its call for papers, its kinds and limits — prose a person writes. One
+ * part of the card is NOT prose: which rules a paper extending the preset runs with, at which
+ * severity and options, and which file of the chain set each. That part is generated between two
+ * markers and checked on every lint, so it cannot say anything the preset does not:
+ *
+ *   <!-- paperlint:preset-rules -->
+ *   …generated: what the preset is, its call for papers, the resolved rules…
+ *   <!-- /paperlint:preset-rules -->
+ *
+ * A section that differs from what the preset resolves to is reported, and `eslint --fix` writes it.
+ * A card with no markers gets the section appended by `--fix`; a card with one marker and not the
+ * other is reported and left alone, since where the section should end is a person's call.
+ *
+ * ── WHY OUR OWN RULE, AND NOT eslint-doc-generator ───────────────────────────────
+ * eslint-doc-generator documents an ESLint PLUGIN: its rules, and which of the plugin's exported
+ * configs enable each. A preset is not an ESLint config — it is paperlint's own format, merged along
+ * an `extends` chain of files (`src/presets.ts`), and the column that matters here (which file of
+ * the chain set a rule) has no counterpart in a plugin's configs.
+ *
+ * ── WHAT IT READS ────────────────────────────────────────────────────────────────
+ * The card's markdown tree (the two markers are top-level `html` nodes), the preset beside it through
+ * `resolvePreset` — the reader every rule uses — and whether `docs/rules/<rule>.md` exists, to link
+ * a rule to its page or, before it has one, to the index `docs/rules.md`.
+ */
+import { basename, dirname, join, relative } from "node:path";
+import { callerPath } from "./caller-path.ts";
+import type { Files } from "./ports/files.ts";
+import {
+  presetProblemText,
+  resolvePreset,
+  resolveShipped,
+  SHIPPED_PREFIX,
+  type Preset,
+} from "./presets.ts";
+
+/** The first line of the generated section. */
+export const SECTION_START = "<!-- paperlint:preset-rules -->";
+/** The last line of the generated section. */
+export const SECTION_END = "<!-- /paperlint:preset-rules -->";
+
+const PRESET_EXT = ".jsonc";
+const CARD_EXT = ".md";
+
+export interface PresetCardDeps {
+  readonly files: Files;
+  /** The shipped presets and their schema: where `paperlint:<name>` resolves. */
+  readonly venuesDir: string;
+  /** The repository root: the rule pages are `docs/rules/<group>/<rule>.md` under it. */
+  readonly docsRoot: string;
+}
+
+/** A point of a markdown node, as mdast gives it: @eslint/markdown's parser sets the offset on every node. */
+interface Point {
+  readonly line: number;
+  readonly column: number;
+  readonly offset: number;
+}
+
+/** The slice of an mdast node the rule reads. */
+export interface MdNode {
+  readonly type: string;
+  readonly value?: string;
+  readonly position: { readonly start: Point; readonly end: Point };
+}
+
+/** The card's root: its top-level blocks. */
+export interface MdRoot extends MdNode {
+  readonly children: readonly MdNode[];
+}
+
+/** What `--fix` may do: replace a range of the card's text, or insert after one. */
+export interface CardFixer {
+  replaceTextRange(range: readonly [number, number], text: string): unknown;
+  insertTextAfterRange(range: readonly [number, number], text: string): unknown;
+}
+
+/** The slice of ESLint's rule context this rule uses. */
+export interface CardRuleContext {
+  readonly filename: string;
+  readonly sourceCode: { readonly text: string };
+  report(d: {
+    readonly node: MdNode;
+    readonly messageId: string;
+    readonly data?: Readonly<Record<string, string>>;
+    readonly fix?: (fixer: CardFixer) => unknown;
+  }): void;
+}
+
+export interface CardRuleModule {
+  readonly meta: {
+    readonly type: "problem";
+    readonly fixable: "code";
+    readonly docs: { readonly description: string };
+    readonly schema: readonly object[];
+    readonly messages: Readonly<Record<string, string>>;
+  };
+  create(context: CardRuleContext): { readonly root: (node: MdRoot) => void };
+}
+
+/** One row of the table: a rule of the resolved preset. */
+export interface RuleRow {
+  readonly id: string;
+  readonly severity: string;
+  /** The options after the severity, as JSON; empty when the entry has none. */
+  readonly options: string;
+  /** The file of the chain that set the entry. */
+  readonly origin: string;
+}
+
+/** A rule entry (`"error"`, `2`, `["error", { … }]`) → its severity and its options as JSON. Pure. */
+export function entryParts(entry: unknown): {
+  readonly severity: string;
+  readonly options: string;
+} {
+  // One level of `flat`: an array entry gives its elements, a bare severity itself.
+  const [severity, ...options] = [entry].flat();
+  return {
+    severity: String(severity),
+    options: options.map((o) => JSON.stringify(o)).join(", "),
+  };
+}
+
+/** The resolved preset's rules, one row each, by rule id. Pure. */
+export const ruleRows = (preset: Preset): readonly RuleRow[] =>
+  Object.entries(preset.ruleOrigins)
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([id, origin]) => ({ id, ...entryParts(preset.rules[id]), origin }));
+
+/** How a card names a preset file: `paperlint:<name>` when it is shipped, else its path from the card. */
+const specOf = (file: string, card: string, venuesDir: string): string =>
+  dirname(file) === venuesDir
+    ? `${SHIPPED_PREFIX}${basename(file, PRESET_EXT)}`
+    : relative(dirname(card), file);
+
+/** A table cell's text with GFM's column separator escaped. Pure. */
+const cell = (text: string): string => text.split("|").join("\\|");
+
+/** What the card says about where to look for the section's source, and how to rewrite it. */
+const generatedNote = (preset: string): string =>
+  `<!-- Generated from ${preset} by \`npx eslint --fix\` (rule preset/card-rules). Edit the preset, not this section. -->`;
+
+/** The section's first paragraph: what the preset is, its call for papers or its relatives. */
+function identityLine(o: {
+  readonly preset: Preset;
+  readonly own: string;
+  readonly specOf: (file: string) => string;
+  readonly extendedBy: readonly string[];
+}): string {
+  const spec = o.specOf(o.own);
+  const extendsText = o.preset.chain
+    .slice(-2, -1)
+    .map((parent) => ` · extends \`${o.specOf(parent)}\``)
+    .join("");
+  switch (o.preset.identity.type) {
+    case "venue":
+      return `**\`${spec}\`** — venue preset for ${o.preset.identity.name} · call for papers: <${o.preset.identity.url}>${extendsText}`;
+    case "family": {
+      const by = o.extendedBy.length
+        ? o.extendedBy.map((s) => `\`${s}\``).join(", ")
+        : "no shipped preset";
+      return `**\`${spec}\`** — template family, no venue of its own${extendsText} · extended by ${by}`;
+    }
+    case "base":
+      return `**\`${basename(o.own)}\`** — the TeX base set: every paper gets it, whatever it extends, and no preset extends it`;
+  }
+}
+
+/** The table, or the sentence that stands for an empty one. Pure. */
+function rulesTable(
+  rows: readonly RuleRow[],
+  own: string,
+  link: (id: string) => string,
+  originSpec: (file: string) => string,
+): string {
+  if (rows.length === 0)
+    return "No preset of this chain sets a rule: under it, every rule keeps paperlint's default.";
+  return [
+    "| rule | severity | options | set in |",
+    "| --- | --- | --- | --- |",
+    ...rows.map(
+      (r) =>
+        `| [\`${r.id}\`](${link(r.id)}) | ${r.severity} | ${r.options === "" ? "—" : `\`${cell(r.options)}\``} | ${r.origin === own ? "this preset" : `inherited from \`${originSpec(r.origin)}\``} |`,
+    ),
+  ].join("\n");
+}
+
+/** A rule's link from the card: its page under `docs/rules/`, or the index before it has one. */
+const ruleLink =
+  (o: {
+    readonly card: string;
+    readonly docsRoot: string;
+    readonly docExists: (file: string) => boolean;
+  }) =>
+  (id: string): string => {
+    const page = join(o.docsRoot, "docs", "rules", `${id}.md`);
+    return relative(
+      dirname(o.card),
+      o.docExists(page) ? page : join(o.docsRoot, "docs", "rules.md"),
+    );
+  };
+
+/**
+ * The section between the markers for the preset `own`, resolved, as the card `card` shows it —
+ * without the markers. Wrapped in prettier-ignore, so the formatter and this rule never disagree
+ * about the table's spacing. Pure but for `docExists`.
+ */
+export function cardSection(o: {
+  readonly preset: Preset;
+  readonly own: string;
+  readonly card: string;
+  readonly venuesDir: string;
+  readonly docsRoot: string;
+  readonly docExists: (file: string) => boolean;
+  readonly extendedBy: readonly string[];
+}): string {
+  const link = ruleLink(o);
+  const spec = (file: string): string => specOf(file, o.card, o.venuesDir);
+  return [
+    "<!-- prettier-ignore-start -->",
+    generatedNote(basename(o.own)),
+    "",
+    identityLine({
+      preset: o.preset,
+      own: o.own,
+      specOf: spec,
+      extendedBy: o.extendedBy,
+    }),
+    "",
+    rulesTable(ruleRows(o.preset), o.own, link, spec),
+    "",
+    "<!-- prettier-ignore-end -->",
+  ].join("\n");
+}
+
+/** The shipped presets whose chain runs through `file`, by their spec, `file` itself left out. */
+const extendedByOf = (file: string, deps: PresetCardDeps): readonly string[] =>
+  resolveShipped(deps)
+    .flatMap((p) => (p.chain.includes(file) ? p.chain.slice(-1) : []))
+    .filter((leaf) => leaf !== file)
+    .map((leaf) => specOf(leaf, file, deps.venuesDir));
+
+/** The section a card should hold, or the finding that stands in its place. */
+type Expected =
+  | { readonly ok: true; readonly text: string }
+  | {
+      readonly ok: false;
+      readonly messageId: string;
+      readonly data: Readonly<Record<string, string>>;
+    };
+
+/** The expected section for the card at `card`, or the finding that stands in its place. */
+function expectedSection(card: string, deps: PresetCardDeps): Expected {
+  const own = join(dirname(card), `${basename(card, CARD_EXT)}${PRESET_EXT}`);
+  if (!deps.files.isFile(callerPath(own)))
+    return { ok: false, messageId: "noPreset", data: { preset: own } };
+  const r = resolvePreset(`./${basename(own)}`, card, deps);
+  if (!r.ok) {
+    const why = presetProblemText(r.error);
+    return { ok: false, messageId: "presetProblem", data: { why } };
+  }
+  return {
+    ok: true,
+    text: cardSection({
+      preset: r.value,
+      own,
+      card,
+      venuesDir: deps.venuesDir,
+      docsRoot: deps.docsRoot,
+      docExists: (f) => deps.files.isFile(callerPath(f)),
+      extendedBy: extendedByOf(own, deps),
+    }),
+  };
+}
+
+/** The first top-level `html` node of the card that is exactly `marker`, or null. */
+const markerIn = (root: MdRoot, marker: string): MdNode | null =>
+  root.children
+    .filter((n) => n.type === "html")
+    .find((n) => String(n.value).trim() === marker) ?? null;
+
+/** The section to append to a card that has none, after its last line. */
+const appended = (text: string, section: string): string =>
+  `${text.endsWith("\n") ? "" : "\n"}\n${SECTION_START}\n${section}\n${SECTION_END}\n`;
+
+/** One finding, as the rule hands it to ESLint. */
+type CardReport = Parameters<CardRuleContext["report"]>[0];
+
+/** The finding for the section between `start` and `end`: stale, with the fix; null when it is right. */
+function staleSection(
+  between: { readonly start: MdNode; readonly end: MdNode },
+  text: string,
+  section: string,
+): CardReport | null {
+  const from = between.start.position.end.offset;
+  const to = between.end.position.start.offset;
+  const expected = `\n${section}\n`;
+  return text.slice(from, to) === expected
+    ? null
+    : {
+        node: between.start,
+        messageId: "stale",
+        fix: (fixer) => fixer.replaceTextRange([from, to], expected),
+      };
+}
+
+/** The card's section against `section`, the one its preset resolves to: missing, unpaired, stale, or right (null). */
+function sectionFinding(
+  root: MdRoot,
+  text: string,
+  section: string,
+): CardReport | null {
+  const start = markerIn(root, SECTION_START);
+  const end = markerIn(root, SECTION_END);
+  if (start === null)
+    return end === null
+      ? {
+          node: root,
+          messageId: "missing",
+          fix: (fixer) =>
+            fixer.insertTextAfterRange(
+              [text.length, text.length],
+              appended(text, section),
+            ),
+        }
+      : { node: end, messageId: "unpaired" };
+  if (end === null) return { node: start, messageId: "unpaired" };
+  return staleSection({ start, end }, text, section);
+}
+
+/** Judge the card `context.filename`: its preset beside it, then its generated section. */
+function judgeCard(
+  context: CardRuleContext,
+  root: MdRoot,
+  deps: PresetCardDeps,
+): void {
+  const want = expectedSection(context.filename, deps);
+  const finding = want.ok
+    ? sectionFinding(root, context.sourceCode.text, want.text)
+    : { node: root, messageId: want.messageId, data: want.data };
+  if (finding !== null) context.report(finding);
+}
+
+/** The rule, over `deps`. */
+export function presetCardRule(deps: PresetCardDeps): CardRuleModule {
+  return {
+    meta: {
+      type: "problem",
+      fixable: "code",
+      docs: {
+        description:
+          "a preset card's rules table is the one its preset resolves to — generated, never hand-written",
+      },
+      schema: [],
+      messages: {
+        stale:
+          "the rules section does not match the preset beside this card — run `npx eslint --fix` on this file to rewrite it from the preset",
+        missing: `this card has no generated rules section — run \`npx eslint --fix\` on this file to append one (between ${SECTION_START} and ${SECTION_END})`,
+        unpaired: `the generated rules section needs both markers, ${SECTION_START} and ${SECTION_END}, each on its own line`,
+        noPreset:
+          "a preset card describes the preset beside it, and there is none: {{preset}}",
+        presetProblem:
+          "the preset beside this card does not resolve, so its rules cannot be listed: {{why}}",
+      },
+    },
+    create(context) {
+      return {
+        root(node) {
+          judgeCard(context, node, deps);
+        },
+      };
+    },
+  };
+}
+
+/** The plugin's rules: `preset/card-rules` once registered under the name `preset`. */
+export const presetCardRules = (
+  deps: PresetCardDeps,
+): Readonly<Record<string, CardRuleModule>> => ({
+  "card-rules": presetCardRule(deps),
+});