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 ruleOptions?: readonly unknown[];
    readonly installedDependencies?: readonly {
        readonly module: string;
        readonly version: string;
    }[];
    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 };