@sarj/eslint-plugin 15.26.8 → 15.27.0

package/dist/_docs-XCw_6XV9.d.cts

@@ -0,0 +1,88 @@
+import { ESLintUtils } from '@typescript-eslint/utils';
+
+/**
+ * @fileoverview _docs — typed source-owned rule documentation and executable examples.
+ *
+ */
+
+type RuleCategory = "architecture" | "correctness" | "maintainability" | "performance" | "security" | "style" | "testing";
+type AutofixPolicy = "none" | "safe" | "suggestion";
+type DefaultLevel = "error" | "warning";
+type ExampleOutcome = "match" | "no-match";
+interface ExampleFile {
+    readonly path: string;
+    readonly source: string;
+}
+/** A reviewed example. It remains private unless `public: true` is explicit. */
+interface RuleExample {
+    readonly id: string;
+    readonly scenarioId?: string;
+    readonly title: string;
+    readonly outcome: ExampleOutcome;
+    readonly files: readonly ExampleFile[];
+    readonly focusPath: string;
+    readonly expectedCount: number;
+    readonly public?: boolean;
+    readonly fixedFiles?: readonly ExampleFile[];
+}
+/** Human-authored fields that cannot be derived from the ESLint rule module. */
+interface RuleDocumentation {
+    readonly summary: string;
+    readonly rationale: string;
+    readonly remediation: string;
+    readonly category: RuleCategory;
+    readonly defaultLevel?: DefaultLevel;
+    readonly languages?: readonly "typescript"[];
+    readonly autofix?: AutofixPolicy;
+    readonly aliases?: readonly string[];
+    readonly limitations?: readonly string[];
+    readonly filePatterns?: readonly string[];
+    readonly references?: readonly string[];
+    readonly since?: string;
+    readonly examples?: readonly RuleExample[];
+}
+/** Complete native record exposed to catalog generation without changing ESLint metadata. */
+interface NativeRuleSpec extends Required<Omit<RuleDocumentation, "since">> {
+    readonly engine: "eslint";
+    readonly ruleId: string;
+    readonly code: null;
+    readonly messageIds: readonly string[];
+    readonly optionsSchema: object | null;
+    readonly since: string | null;
+    readonly key: string;
+    readonly publicExamples: readonly RuleExample[];
+}
+/** The explicit allowlist projection consumed by generated public documentation. */
+interface PublicRuleSpec {
+    readonly engine: "eslint";
+    readonly ruleId: string;
+    readonly code: null;
+    readonly summary: string;
+    readonly rationale: string;
+    readonly remediation: string;
+    readonly category: RuleCategory;
+    readonly defaultLevel: DefaultLevel;
+    readonly languages: readonly "typescript"[];
+    readonly autofix: AutofixPolicy;
+    readonly aliases: readonly string[];
+    readonly limitations: readonly string[];
+    readonly filePatterns: readonly string[];
+    readonly references: readonly string[];
+    readonly since: string | null;
+    readonly messageIds: readonly string[];
+    readonly optionsSchema: object | null;
+    readonly examples: readonly RuleExample[];
+}
+declare const eslintCreateRule: <Options extends readonly unknown[], MessageIds extends string>({ meta, name, ...rule }: Readonly<ESLintUtils.RuleWithMetaAndName<Options, MessageIds, unknown>>) => ESLintUtils.RuleModule<MessageIds, Options, unknown, ESLintUtils.RuleListener> & {
+    name: string;
+};
+type DocumentedRule<Options extends readonly unknown[], MessageIds extends string> = ReturnType<typeof eslintCreateRule<Options, MessageIds>> & {
+    /** Non-enumerable so the public ESLint rule shape remains unchanged. */
+    readonly documentation?: NativeRuleSpec;
+};
+/** Serialize only reviewed fields; test-only examples never cross this boundary. */
+declare function publicDocumentation(rules: Readonly<Record<string, {
+    readonly documentation?: NativeRuleSpec;
+}>>): readonly PublicRuleSpec[];
+
+export { type DocumentedRule as D, publicDocumentation as p };

package/dist/_docs-XCw_6XV9.d.ts

@@ -0,0 +1,88 @@
+import { ESLintUtils } from '@typescript-eslint/utils';
+
+/**
+ * @fileoverview _docs — typed source-owned rule documentation and executable examples.
+ *
+ */
+
+type RuleCategory = "architecture" | "correctness" | "maintainability" | "performance" | "security" | "style" | "testing";
+type AutofixPolicy = "none" | "safe" | "suggestion";
+type DefaultLevel = "error" | "warning";
+type ExampleOutcome = "match" | "no-match";
+interface ExampleFile {
+    readonly path: string;
+    readonly source: string;
+}
+/** A reviewed example. It remains private unless `public: true` is explicit. */
+interface RuleExample {
+    readonly id: string;
+    readonly scenarioId?: string;
+    readonly title: string;
+    readonly outcome: ExampleOutcome;
+    readonly files: readonly ExampleFile[];
+    readonly focusPath: string;
+    readonly expectedCount: number;
+    readonly public?: boolean;
+    readonly fixedFiles?: readonly ExampleFile[];
+}
+/** Human-authored fields that cannot be derived from the ESLint rule module. */
+interface RuleDocumentation {
+    readonly summary: string;
+    readonly rationale: string;
+    readonly remediation: string;
+    readonly category: RuleCategory;
+    readonly defaultLevel?: DefaultLevel;
+    readonly languages?: readonly "typescript"[];
+    readonly autofix?: AutofixPolicy;
+    readonly aliases?: readonly string[];
+    readonly limitations?: readonly string[];
+    readonly filePatterns?: readonly string[];
+    readonly references?: readonly string[];
+    readonly since?: string;
+    readonly examples?: readonly RuleExample[];
+}
+/** Complete native record exposed to catalog generation without changing ESLint metadata. */
+interface NativeRuleSpec extends Required<Omit<RuleDocumentation, "since">> {
+    readonly engine: "eslint";
+    readonly ruleId: string;
+    readonly code: null;
+    readonly messageIds: readonly string[];
+    readonly optionsSchema: object | null;
+    readonly since: string | null;
+    readonly key: string;
+    readonly publicExamples: readonly RuleExample[];
+}
+/** The explicit allowlist projection consumed by generated public documentation. */
+interface PublicRuleSpec {
+    readonly engine: "eslint";
+    readonly ruleId: string;
+    readonly code: null;
+    readonly summary: string;
+    readonly rationale: string;
+    readonly remediation: string;
+    readonly category: RuleCategory;
+    readonly defaultLevel: DefaultLevel;
+    readonly languages: readonly "typescript"[];
+    readonly autofix: AutofixPolicy;
+    readonly aliases: readonly string[];
+    readonly limitations: readonly string[];
+    readonly filePatterns: readonly string[];
+    readonly references: readonly string[];
+    readonly since: string | null;
+    readonly messageIds: readonly string[];
+    readonly optionsSchema: object | null;
+    readonly examples: readonly RuleExample[];
+}
+declare const eslintCreateRule: <Options extends readonly unknown[], MessageIds extends string>({ meta, name, ...rule }: Readonly<ESLintUtils.RuleWithMetaAndName<Options, MessageIds, unknown>>) => ESLintUtils.RuleModule<MessageIds, Options, unknown, ESLintUtils.RuleListener> & {
+    name: string;
+};
+type DocumentedRule<Options extends readonly unknown[], MessageIds extends string> = ReturnType<typeof eslintCreateRule<Options, MessageIds>> & {
+    /** Non-enumerable so the public ESLint rule shape remains unchanged. */
+    readonly documentation?: NativeRuleSpec;
+};
+/** Serialize only reviewed fields; test-only examples never cross this boundary. */
+declare function publicDocumentation(rules: Readonly<Record<string, {
+    readonly documentation?: NativeRuleSpec;
+}>>): readonly PublicRuleSpec[];
+
+export { type DocumentedRule as D, publicDocumentation as p };

package/dist/index.cjs

@@ -23227,7 +23227,7 @@ var RULES = {
 };
 var meta = {
   name: "@sarj/eslint-plugin",
-  version: "15.26.8"
+  version: "15.27.0"
 };
 var APPLICATION_ONLY_RULES = [];
 var LIBRARY_IMPORT_POLICY = ["error", {

package/dist/index.d.cts

@@ -1,4 +1,6 @@
-import { ESLintUtils } from '@typescript-eslint/utils';
+import { D as DocumentedRule } from './_docs-XCw_6XV9.cjs';
+export { p as publicDocumentation } from './_docs-XCw_6XV9.cjs';
+import '@typescript-eslint/utils';
 
 /** @fileoverview _retired — burned rule names and their migration action. */
 /** Why a name was withdrawn, and in which release. */
@@ -10,91 +12,6 @@ interface RetiredRule {
 }
 declare const RETIRED_RULES: Readonly<Record<string, RetiredRule>>;
 
-/**
- * @fileoverview _docs — typed source-owned rule documentation and executable examples.
- *
- */
-
-type RuleCategory = "architecture" | "correctness" | "maintainability" | "performance" | "security" | "style" | "testing";
-type AutofixPolicy = "none" | "safe" | "suggestion";
-type DefaultLevel = "error" | "warning";
-type ExampleOutcome = "match" | "no-match";
-interface ExampleFile {
-    readonly path: string;
-    readonly source: string;
-}
-/** A reviewed example. It remains private unless `public: true` is explicit. */
-interface RuleExample {
-    readonly id: string;
-    readonly scenarioId?: string;
-    readonly title: string;
-    readonly outcome: ExampleOutcome;
-    readonly files: readonly ExampleFile[];
-    readonly focusPath: string;
-    readonly expectedCount: number;
-    readonly public?: boolean;
-    readonly fixedFiles?: readonly ExampleFile[];
-}
-/** Human-authored fields that cannot be derived from the ESLint rule module. */
-interface RuleDocumentation {
-    readonly summary: string;
-    readonly rationale: string;
-    readonly remediation: string;
-    readonly category: RuleCategory;
-    readonly defaultLevel?: DefaultLevel;
-    readonly languages?: readonly "typescript"[];
-    readonly autofix?: AutofixPolicy;
-    readonly aliases?: readonly string[];
-    readonly limitations?: readonly string[];
-    readonly filePatterns?: readonly string[];
-    readonly references?: readonly string[];
-    readonly since?: string;
-    readonly examples?: readonly RuleExample[];
-}
-/** Complete native record exposed to catalog generation without changing ESLint metadata. */
-interface NativeRuleSpec extends Required<Omit<RuleDocumentation, "since">> {
-    readonly engine: "eslint";
-    readonly ruleId: string;
-    readonly code: null;
-    readonly messageIds: readonly string[];
-    readonly optionsSchema: object | null;
-    readonly since: string | null;
-    readonly key: string;
-    readonly publicExamples: readonly RuleExample[];
-}
-/** The explicit allowlist projection consumed by generated public documentation. */
-interface PublicRuleSpec {
-    readonly engine: "eslint";
-    readonly ruleId: string;
-    readonly code: null;
-    readonly summary: string;
-    readonly rationale: string;
-    readonly remediation: string;
-    readonly category: RuleCategory;
-    readonly defaultLevel: DefaultLevel;
-    readonly languages: readonly "typescript"[];
-    readonly autofix: AutofixPolicy;
-    readonly aliases: readonly string[];
-    readonly limitations: readonly string[];
-    readonly filePatterns: readonly string[];
-    readonly references: readonly string[];
-    readonly since: string | null;
-    readonly messageIds: readonly string[];
-    readonly optionsSchema: object | null;
-    readonly examples: readonly RuleExample[];
-}
-declare const eslintCreateRule: <Options extends readonly unknown[], MessageIds extends string>({ meta, name, ...rule }: Readonly<ESLintUtils.RuleWithMetaAndName<Options, MessageIds, unknown>>) => ESLintUtils.RuleModule<MessageIds, Options, unknown, ESLintUtils.RuleListener> & {
-    name: string;
-};
-type DocumentedRule<Options extends readonly unknown[], MessageIds extends string> = ReturnType<typeof eslintCreateRule<Options, MessageIds>> & {
-    /** Non-enumerable so the public ESLint rule shape remains unchanged. */
-    readonly documentation?: NativeRuleSpec;
-};
-/** Serialize only reviewed fields; test-only examples never cross this boundary. */
-declare function publicDocumentation(rules: Readonly<Record<string, {
-    readonly documentation?: NativeRuleSpec;
-}>>): readonly PublicRuleSpec[];
-
 interface RuleOptions$5 {
     readonly basePath?: string;
 }
@@ -996,7 +913,7 @@ type FlatPreset = {
 declare const PLUGIN: {
     readonly meta: {
         readonly name: "@sarj/eslint-plugin";
-        readonly version: "15.26.8";
+        readonly version: "15.27.0";
     };
     readonly rules: {
         readonly "no-conditional-empty-object-spread": DocumentedRule<[], "avoid">;
@@ -1161,4 +1078,4 @@ declare const PLUGIN: {
     };
 };
 
-export { ADVISORY_RULES, APPLICATION_ONLY_RULES, RECOMMENDED_RULES, RENAMED_RULES, RETIRED_RULES, RULES, type RetiredRule, STRICT_RULES, ADVISORY_RULES as advisoryRules, APPLICATION_ONLY_RULES as applicationOnlyRules, PLUGIN as default, publicDocumentation, RECOMMENDED_RULES as recommendedRules, RENAMED_RULES as renamedRules, RETIRED_RULES as retiredRules, RULES as rules, STRICT_RULES as strictRules };
+export { ADVISORY_RULES, APPLICATION_ONLY_RULES, RECOMMENDED_RULES, RENAMED_RULES, RETIRED_RULES, RULES, type RetiredRule, STRICT_RULES, ADVISORY_RULES as advisoryRules, APPLICATION_ONLY_RULES as applicationOnlyRules, PLUGIN as default, RECOMMENDED_RULES as recommendedRules, RENAMED_RULES as renamedRules, RETIRED_RULES as retiredRules, RULES as rules, STRICT_RULES as strictRules };

package/dist/index.d.ts

@@ -1,4 +1,6 @@
-import { ESLintUtils } from '@typescript-eslint/utils';
+import { D as DocumentedRule } from './_docs-XCw_6XV9.js';
+export { p as publicDocumentation } from './_docs-XCw_6XV9.js';
+import '@typescript-eslint/utils';
 
 /** @fileoverview _retired — burned rule names and their migration action. */
 /** Why a name was withdrawn, and in which release. */
@@ -10,91 +12,6 @@ interface RetiredRule {
 }
 declare const RETIRED_RULES: Readonly<Record<string, RetiredRule>>;
 
-/**
- * @fileoverview _docs — typed source-owned rule documentation and executable examples.
- *
- */
-
-type RuleCategory = "architecture" | "correctness" | "maintainability" | "performance" | "security" | "style" | "testing";
-type AutofixPolicy = "none" | "safe" | "suggestion";
-type DefaultLevel = "error" | "warning";
-type ExampleOutcome = "match" | "no-match";
-interface ExampleFile {
-    readonly path: string;
-    readonly source: string;
-}
-/** A reviewed example. It remains private unless `public: true` is explicit. */
-interface RuleExample {
-    readonly id: string;
-    readonly scenarioId?: string;
-    readonly title: string;
-    readonly outcome: ExampleOutcome;
-    readonly files: readonly ExampleFile[];
-    readonly focusPath: string;
-    readonly expectedCount: number;
-    readonly public?: boolean;
-    readonly fixedFiles?: readonly ExampleFile[];
-}
-/** Human-authored fields that cannot be derived from the ESLint rule module. */
-interface RuleDocumentation {
-    readonly summary: string;
-    readonly rationale: string;
-    readonly remediation: string;
-    readonly category: RuleCategory;
-    readonly defaultLevel?: DefaultLevel;
-    readonly languages?: readonly "typescript"[];
-    readonly autofix?: AutofixPolicy;
-    readonly aliases?: readonly string[];
-    readonly limitations?: readonly string[];
-    readonly filePatterns?: readonly string[];
-    readonly references?: readonly string[];
-    readonly since?: string;
-    readonly examples?: readonly RuleExample[];
-}
-/** Complete native record exposed to catalog generation without changing ESLint metadata. */
-interface NativeRuleSpec extends Required<Omit<RuleDocumentation, "since">> {
-    readonly engine: "eslint";
-    readonly ruleId: string;
-    readonly code: null;
-    readonly messageIds: readonly string[];
-    readonly optionsSchema: object | null;
-    readonly since: string | null;
-    readonly key: string;
-    readonly publicExamples: readonly RuleExample[];
-}
-/** The explicit allowlist projection consumed by generated public documentation. */
-interface PublicRuleSpec {
-    readonly engine: "eslint";
-    readonly ruleId: string;
-    readonly code: null;
-    readonly summary: string;
-    readonly rationale: string;
-    readonly remediation: string;
-    readonly category: RuleCategory;
-    readonly defaultLevel: DefaultLevel;
-    readonly languages: readonly "typescript"[];
-    readonly autofix: AutofixPolicy;
-    readonly aliases: readonly string[];
-    readonly limitations: readonly string[];
-    readonly filePatterns: readonly string[];
-    readonly references: readonly string[];
-    readonly since: string | null;
-    readonly messageIds: readonly string[];
-    readonly optionsSchema: object | null;
-    readonly examples: readonly RuleExample[];
-}
-declare const eslintCreateRule: <Options extends readonly unknown[], MessageIds extends string>({ meta, name, ...rule }: Readonly<ESLintUtils.RuleWithMetaAndName<Options, MessageIds, unknown>>) => ESLintUtils.RuleModule<MessageIds, Options, unknown, ESLintUtils.RuleListener> & {
-    name: string;
-};
-type DocumentedRule<Options extends readonly unknown[], MessageIds extends string> = ReturnType<typeof eslintCreateRule<Options, MessageIds>> & {
-    /** Non-enumerable so the public ESLint rule shape remains unchanged. */
-    readonly documentation?: NativeRuleSpec;
-};
-/** Serialize only reviewed fields; test-only examples never cross this boundary. */
-declare function publicDocumentation(rules: Readonly<Record<string, {
-    readonly documentation?: NativeRuleSpec;
-}>>): readonly PublicRuleSpec[];
-
 interface RuleOptions$5 {
     readonly basePath?: string;
 }
@@ -996,7 +913,7 @@ type FlatPreset = {
 declare const PLUGIN: {
     readonly meta: {
         readonly name: "@sarj/eslint-plugin";
-        readonly version: "15.26.8";
+        readonly version: "15.27.0";
     };
     readonly rules: {
         readonly "no-conditional-empty-object-spread": DocumentedRule<[], "avoid">;
@@ -1161,4 +1078,4 @@ declare const PLUGIN: {
     };
 };
 
-export { ADVISORY_RULES, APPLICATION_ONLY_RULES, RECOMMENDED_RULES, RENAMED_RULES, RETIRED_RULES, RULES, type RetiredRule, STRICT_RULES, ADVISORY_RULES as advisoryRules, APPLICATION_ONLY_RULES as applicationOnlyRules, PLUGIN as default, publicDocumentation, RECOMMENDED_RULES as recommendedRules, RENAMED_RULES as renamedRules, RETIRED_RULES as retiredRules, RULES as rules, STRICT_RULES as strictRules };
+export { ADVISORY_RULES, APPLICATION_ONLY_RULES, RECOMMENDED_RULES, RENAMED_RULES, RETIRED_RULES, RULES, type RetiredRule, STRICT_RULES, ADVISORY_RULES as advisoryRules, APPLICATION_ONLY_RULES as applicationOnlyRules, PLUGIN as default, RECOMMENDED_RULES as recommendedRules, RENAMED_RULES as renamedRules, RETIRED_RULES as retiredRules, RULES as rules, STRICT_RULES as strictRules };

package/dist/index.js

@@ -23248,7 +23248,7 @@ var RULES = {
 };
 var meta = {
   name: "@sarj/eslint-plugin",
-  version: "15.26.8"
+  version: "15.27.0"
 };
 var APPLICATION_ONLY_RULES = [];
 var LIBRARY_IMPORT_POLICY = ["error", {

package/dist/rule-examples.cjs

@@ -0,0 +1,112 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/rule-examples.ts
+var rule_examples_exports = {};
+__export(rule_examples_exports, {
+  verifyRuleExamples: () => verifyRuleExamples
+});
+module.exports = __toCommonJS(rule_examples_exports);
+var import_promises = require("fs/promises");
+var import_node_os = require("os");
+var import_node_path = require("path");
+var parser = __toESM(require("@typescript-eslint/parser"), 1);
+var import_eslint = require("eslint");
+async function verifyRuleExamples(rule) {
+  const spec = rule.documentation;
+  if (spec === void 0 || !spec.publicExamples.some((item) => item.outcome === "match") || !spec.publicExamples.some((item) => item.outcome === "no-match")) {
+    throw new Error("rule requires documented public matching and non-matching examples");
+  }
+  for (const example of spec.examples) {
+    const root = await (0, import_promises.mkdtemp)((0, import_node_path.join)((0, import_node_os.tmpdir)(), "sarj-rule-example-"));
+    try {
+      for (const file of example.files) {
+        const path = fixturePath(root, file.path);
+        await (0, import_promises.mkdir)((0, import_node_path.dirname)(path), { recursive: true });
+        await (0, import_promises.writeFile)(path, file.source);
+      }
+      const tsconfig = (0, import_node_path.join)(root, "tsconfig.json");
+      if (!example.files.some((file) => file.path === "tsconfig.json")) {
+        await (0, import_promises.writeFile)(tsconfig, JSON.stringify({ compilerOptions: {
+          target: "ESNext",
+          module: "ESNext",
+          moduleResolution: "Bundler",
+          strict: true,
+          allowJs: true,
+          jsx: "preserve",
+          noEmit: true
+        }, include: ["**/*"] }));
+      }
+      const ruleId = `@sarj/${spec.ruleId}`;
+      const config = {
+        files: ["**/*.{ts,tsx,js,jsx,mts,cts,mjs,cjs}"],
+        languageOptions: { parser, parserOptions: { project: tsconfig, tsconfigRootDir: root } },
+        plugins: { "@sarj": { rules: { [spec.ruleId]: rule } } },
+        rules: { [ruleId]: ["error", ...rule.defaultOptions ?? []] }
+      };
+      await verifyExample(new import_eslint.Linter({ cwd: root }), config, example, root, ruleId);
+    } finally {
+      await (0, import_promises.rm)(root, { recursive: true, force: true });
+    }
+  }
+  return spec.examples.length;
+}
+function fixturePath(root, path) {
+  const resolved = (0, import_node_path.resolve)(root, path);
+  if (!resolved.startsWith(root + import_node_path.sep)) throw new Error(`unsafe example path: ${path}`);
+  return resolved;
+}
+async function verifyExample(linter, config, example, root, ruleId) {
+  const focus = example.files.find((file) => file.path === example.focusPath);
+  if (focus === void 0) throw new Error(`${example.id}: focus file is missing`);
+  const filename = fixturePath(root, focus.path);
+  const messages = linter.verify(focus.source, config, { filename });
+  if (messages.some((message) => message.fatal || message.ruleId !== ruleId)) {
+    throw new Error(`${example.id}: invalid fixture: ${messages.map((message) => message.message).join("; ")}`);
+  }
+  if (messages.length !== example.expectedCount) {
+    throw new Error(`${example.id}: expected ${example.expectedCount} findings, received ${messages.length}`);
+  }
+  for (const expected of example.fixedFiles ?? []) {
+    const input = example.files.find((file) => file.path === expected.path);
+    if (input === void 0) throw new Error(`${example.id}: fixed file has no original`);
+    const options = { filename: fixturePath(root, input.path) };
+    const fixed = linter.verifyAndFix(input.source, config, options);
+    if (fixed.output !== expected.source) throw new Error(`${example.id}: unexpected fixed source`);
+    await (0, import_promises.writeFile)(options.filename, fixed.output);
+    const repeated = linter.verifyAndFix(fixed.output, config, options);
+    if (repeated.fixed || repeated.output !== fixed.output || repeated.messages.length > 0) {
+      throw new Error(`${example.id}: fix is not clean and idempotent`);
+    }
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  verifyRuleExamples
+});

package/dist/rule-examples.d.cts

@@ -0,0 +1,7 @@
+import { D as DocumentedRule } from './_docs-XCw_6XV9.cjs';
+import '@typescript-eslint/utils';
+
+/** Execute all authored examples, including private regressions, in isolated projects. */
+declare function verifyRuleExamples<Options extends readonly unknown[], MessageIds extends string>(rule: DocumentedRule<Options, MessageIds>): Promise<number>;
+
+export { verifyRuleExamples };

package/dist/rule-examples.d.ts

@@ -0,0 +1,7 @@
+import { D as DocumentedRule } from './_docs-XCw_6XV9.js';
+import '@typescript-eslint/utils';
+
+/** Execute all authored examples, including private regressions, in isolated projects. */
+declare function verifyRuleExamples<Options extends readonly unknown[], MessageIds extends string>(rule: DocumentedRule<Options, MessageIds>): Promise<number>;
+
+export { verifyRuleExamples };

package/dist/rule-examples.js

@@ -0,0 +1,77 @@
+// src/rule-examples.ts
+import { mkdtemp, mkdir, rm, writeFile } from "fs/promises";
+import { tmpdir } from "os";
+import { dirname, join, resolve, sep } from "path";
+import * as parser from "@typescript-eslint/parser";
+import { Linter } from "eslint";
+async function verifyRuleExamples(rule) {
+  const spec = rule.documentation;
+  if (spec === void 0 || !spec.publicExamples.some((item) => item.outcome === "match") || !spec.publicExamples.some((item) => item.outcome === "no-match")) {
+    throw new Error("rule requires documented public matching and non-matching examples");
+  }
+  for (const example of spec.examples) {
+    const root = await mkdtemp(join(tmpdir(), "sarj-rule-example-"));
+    try {
+      for (const file of example.files) {
+        const path = fixturePath(root, file.path);
+        await mkdir(dirname(path), { recursive: true });
+        await writeFile(path, file.source);
+      }
+      const tsconfig = join(root, "tsconfig.json");
+      if (!example.files.some((file) => file.path === "tsconfig.json")) {
+        await writeFile(tsconfig, JSON.stringify({ compilerOptions: {
+          target: "ESNext",
+          module: "ESNext",
+          moduleResolution: "Bundler",
+          strict: true,
+          allowJs: true,
+          jsx: "preserve",
+          noEmit: true
+        }, include: ["**/*"] }));
+      }
+      const ruleId = `@sarj/${spec.ruleId}`;
+      const config = {
+        files: ["**/*.{ts,tsx,js,jsx,mts,cts,mjs,cjs}"],
+        languageOptions: { parser, parserOptions: { project: tsconfig, tsconfigRootDir: root } },
+        plugins: { "@sarj": { rules: { [spec.ruleId]: rule } } },
+        rules: { [ruleId]: ["error", ...rule.defaultOptions ?? []] }
+      };
+      await verifyExample(new Linter({ cwd: root }), config, example, root, ruleId);
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  }
+  return spec.examples.length;
+}
+function fixturePath(root, path) {
+  const resolved = resolve(root, path);
+  if (!resolved.startsWith(root + sep)) throw new Error(`unsafe example path: ${path}`);
+  return resolved;
+}
+async function verifyExample(linter, config, example, root, ruleId) {
+  const focus = example.files.find((file) => file.path === example.focusPath);
+  if (focus === void 0) throw new Error(`${example.id}: focus file is missing`);
+  const filename = fixturePath(root, focus.path);
+  const messages = linter.verify(focus.source, config, { filename });
+  if (messages.some((message) => message.fatal || message.ruleId !== ruleId)) {
+    throw new Error(`${example.id}: invalid fixture: ${messages.map((message) => message.message).join("; ")}`);
+  }
+  if (messages.length !== example.expectedCount) {
+    throw new Error(`${example.id}: expected ${example.expectedCount} findings, received ${messages.length}`);
+  }
+  for (const expected of example.fixedFiles ?? []) {
+    const input = example.files.find((file) => file.path === expected.path);
+    if (input === void 0) throw new Error(`${example.id}: fixed file has no original`);
+    const options = { filename: fixturePath(root, input.path) };
+    const fixed = linter.verifyAndFix(input.source, config, options);
+    if (fixed.output !== expected.source) throw new Error(`${example.id}: unexpected fixed source`);
+    await writeFile(options.filename, fixed.output);
+    const repeated = linter.verifyAndFix(fixed.output, config, options);
+    if (repeated.fixed || repeated.output !== fixed.output || repeated.messages.length > 0) {
+      throw new Error(`${example.id}: fix is not clean and idempotent`);
+    }
+  }
+}
+export {
+  verifyRuleExamples
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sarj/eslint-plugin",
-  "version": "15.26.8",
+  "version": "15.27.0",
   "packageManager": "npm@12.1.0",
   "description": "Custom ESLint rules for hypermodern TypeScript / React / Next.js projects",
   "type": "module",
@@ -34,12 +34,13 @@
   },
   "scripts": {
     "build": "tsup",
-    "dogfood": "npm run build && eslint --config eslint.dogfood.config.mjs src tests eslint.config.mjs eslint.dogfood.config.mjs module-constant-naming-options.mjs tsup.config.ts vitest.config.ts --max-warnings 0 && node -e \"import('./dist/index.js').then(({default:p}) => console.log('dogfood: '+Object.keys(p.rules).length+' TypeScript rules, 0 diagnostics'))\"",
+    "dogfood": "npm run build && npm run dogfood:built",
     "lint": "eslint . --max-warnings 0",
     "prepack": "npm run build && npm run verify-package",
     "test": "vitest run",
     "typecheck": "tsc --noEmit",
-    "verify-package": "node -e \"const fs=require('node:fs'),p=require('./package.json'),walk=x=>typeof x==='string'?[x]:x&&typeof x==='object'?Object.values(x).flatMap(walk):[];for(const file of new Set([p.main,p.module,p.types,...walk(p.exports)].filter(Boolean).map(x=>x.startsWith('./')?x.slice(2):x))){if(!file.startsWith('dist/'))throw new Error('export must live under dist: '+file);const stat=fs.statSync(file);if(!stat.isFile()||stat.size===0)throw new Error('missing or empty export: '+file)}\""
+    "verify-package": "node -e \"const fs=require('node:fs'),p=require('./package.json'),walk=x=>typeof x==='string'?[x]:x&&typeof x==='object'?Object.values(x).flatMap(walk):[];for(const file of new Set([p.main,p.module,p.types,...walk(p.exports)].filter(Boolean).map(x=>x.startsWith('./')?x.slice(2):x))){if(!file.startsWith('dist/'))throw new Error('export must live under dist: '+file);const stat=fs.statSync(file);if(!stat.isFile()||stat.size===0)throw new Error('missing or empty export: '+file)}\"",
+    "dogfood:built": "eslint --config eslint.dogfood.config.mjs src tests eslint.config.mjs eslint.dogfood.config.mjs module-constant-naming-options.mjs tsup.config.ts vitest.config.ts --max-warnings 0 && node -e \"import('./dist/index.js').then(({default:p}) => console.log('dogfood: '+Object.keys(p.rules).length+' TypeScript rules, 0 diagnostics'))\""
   },
   "keywords": [
     "eslint",