eslint-doc-generator/dist/lib/types.d.ts

Automatic documentation generator for ESLint plugins and rules.

import type { RuleDocTitleFormat } from './rule-doc-title-format.js';
import type { TSESLint } from '@typescript-eslint/utils';
import type { ConfigFormat } from './config-format.js';
export type RuleModule = TSESLint.RuleModule<string, readonly unknown[]>;
export type Rules = TSESLint.Linter.RulesRecord;
export type RuleSeverity = TSESLint.Linter.RuleLevel;
export type Config = TSESLint.Linter.Config;
export type Plugin = TSESLint.Linter.Plugin;
/**
 * Where a rule comes from (where it's defined).
 */
export declare const RULE_SOURCE: {
    readonly self: "self";
    readonly eslintCore: "eslintCore";
    readonly thirdPartyPlugin: "thirdPartyPlugin";
};
export type RULE_SOURCE = (typeof RULE_SOURCE)[keyof typeof RULE_SOURCE];
export declare const SEVERITY_ERROR: Set<TSESLint.SharedConfig.RuleLevel>;
export declare const SEVERITY_WARN: Set<TSESLint.SharedConfig.RuleLevel>;
export declare const SEVERITY_OFF: Set<TSESLint.SharedConfig.RuleLevel>;
export declare const SEVERITY_TYPE: {
    readonly error: "error";
    readonly warn: "warn";
    readonly off: "off";
};
export type SEVERITY_TYPE = (typeof SEVERITY_TYPE)[keyof typeof SEVERITY_TYPE];
export declare const SEVERITY_TYPE_TO_SET: {
    [key in SEVERITY_TYPE]: Set<TSESLint.Linter.RuleLevel>;
};
export type ConfigsToRules = Record<string, Rules>;
/**
 * List of rules in the form of tuples (rule name and the actual rule).
 */
export type RuleNamesAndRules = readonly (readonly [
    name: string,
    rule: RuleModule
])[];
/**
 * The emoji for each config that has one after option parsing and defaults have been applied.
 */
export type ConfigEmojis = readonly {
    config: string;
    emoji: string;
}[];
/**
 * Rule doc notices.
 */
export declare const NOTICE_TYPE: {
    readonly CONFIGS: "configs";
    readonly DEPRECATED: "deprecated";
    readonly DESCRIPTION: "description";
    readonly FIXABLE: "fixable";
    readonly FIXABLE_AND_HAS_SUGGESTIONS: "fixableAndHasSuggestions";
    readonly HAS_SUGGESTIONS: "hasSuggestions";
    readonly OPTIONS: "options";
    readonly REQUIRES_TYPE_CHECKING: "requiresTypeChecking";
    readonly TYPE: "type";
};
export type NOTICE_TYPE = (typeof NOTICE_TYPE)[keyof typeof NOTICE_TYPE];
/**
 * Rule list columns.
 */
export declare const COLUMN_TYPE: {
    readonly CONFIGS_ERROR: "configsError";
    readonly CONFIGS_OFF: "configsOff";
    readonly CONFIGS_WARN: "configsWarn";
    readonly DEPRECATED: "deprecated";
    readonly DESCRIPTION: "description";
    readonly FIXABLE: "fixable";
    readonly FIXABLE_AND_HAS_SUGGESTIONS: "fixableAndHasSuggestions";
    readonly HAS_SUGGESTIONS: "hasSuggestions";
    readonly NAME: "name";
    readonly OPTIONS: "options";
    readonly REQUIRES_TYPE_CHECKING: "requiresTypeChecking";
    readonly TYPE: "type";
};
export type COLUMN_TYPE = (typeof COLUMN_TYPE)[keyof typeof COLUMN_TYPE];
/**
 * CLI/config file options.
 */
export declare const OPTION_TYPE: {
    readonly CHECK: "check";
    readonly CONFIG_EMOJI: "configEmoji";
    readonly CONFIG_FORMAT: "configFormat";
    readonly IGNORE_CONFIG: "ignoreConfig";
    readonly IGNORE_DEPRECATED_RULES: "ignoreDeprecatedRules";
    readonly INIT_RULE_DOCS: "initRuleDocs";
    readonly PATH_RULE_DOC: "pathRuleDoc";
    readonly PATH_RULE_LIST: "pathRuleList";
    readonly POSTPROCESS: "postprocess";
    readonly RULE_DOC_NOTICES: "ruleDocNotices";
    readonly RULE_DOC_SECTION_EXCLUDE: "ruleDocSectionExclude";
    readonly RULE_DOC_SECTION_INCLUDE: "ruleDocSectionInclude";
    readonly RULE_DOC_SECTION_OPTIONS: "ruleDocSectionOptions";
    readonly RULE_DOC_TITLE_FORMAT: "ruleDocTitleFormat";
    readonly RULE_LIST_COLUMNS: "ruleListColumns";
    readonly RULE_LIST_SPLIT: "ruleListSplit";
    readonly URL_CONFIGS: "urlConfigs";
    readonly URL_RULE_DOC: "urlRuleDoc";
};
export type OPTION_TYPE = (typeof OPTION_TYPE)[keyof typeof OPTION_TYPE];
/**
 * Function for splitting the rule list into multiple sections.
 * Can be provided via a JavaScript-based config file using the `ruleListSplit` option.
 * @param rules - all rules from the plugin
 * @returns an array of sections, each with a title (optional) and list of rules
 */
export type RuleListSplitFunction = (rules: RuleNamesAndRules) => readonly {
    title?: string;
    rules: RuleNamesAndRules;
}[];
/**
 * Function for generating the URL to a rule doc.
 * Can be provided via a JavaScript-based config file using the `urlRuleDoc` option.
 * @param name - the name of the rule
 * @param path - the file path to the current page displaying the link, relative to the project root
 * @returns the URL to the rule doc, or `undefined` to fallback to the default logic (relative URL)
 */
export type UrlRuleDocFunction = (name: string, path: string) => string | undefined;
/**
 * Function for generating the path to markdown file for each rule doc.
 * Can be provided via a JavaScript-based config file using the `pathRuleDoc` option.
 * @param name - the name of the rule
 * @returns the path to the rule doc
 */
export type PathRuleDocFunction = (name: string) => string;
/** The type for the config file (e.g. `.eslint-doc-generatorrc.js`) and internal `generate()` function. */
export type GenerateOptions = {
    /**
     * Whether to check for and fail if there is a diff.
     * Any diff will be displayed but no output will be written to files.
     * Typically used during CI.
     * Default: `false`.
     */
    readonly check?: boolean;
    /**
     * List of configs and their associated emojis.
     * Array of `[configName, emoji]`.
     * Default emojis are provided for common configs.
     * To use a text/image/icon badge instead of an emoji, supply the corresponding markdown as the emoji.
     */
    readonly configEmoji?: readonly ([configName: string, emoji: string] | [configName: string])[];
    /** The format to use for config names. Default: `name`. */
    readonly configFormat?: ConfigFormat;
    /** Configs to ignore from being displayed. Often used for an `all` config. */
    readonly ignoreConfig?: readonly string[];
    /** Whether to ignore deprecated rules from being checked, displayed, or updated. Default: `false`. */
    readonly ignoreDeprecatedRules?: boolean;
    /** Whether to create rule doc files if they don't yet exist. Default: `false`. */
    readonly initRuleDocs?: boolean;
    /**
     * Path (or function to generate a path) to to markdown file for each rule doc.
     * For the string version, use `{name}` placeholder for the rule name.
     * Default: `docs/rules/{name}.md`.
     */
    readonly pathRuleDoc?: string | PathRuleDocFunction;
    /** Path to markdown file(s) where the rules table list should live. Default: `README.md`. */
    readonly pathRuleList?: string | readonly string[];
    /**
     * Function to be called with the generated content and file path for each processed file.
     * Useful for applying custom transformations such as formatting with tools like prettier.
     * Only available via a JavaScript-based config file.
     */
    readonly postprocess?: (content: string, pathToFile: string) => string | Promise<string>;
    /**
     * Ordered list of notices to display in rule doc.
     * Non-applicable notices will be hidden.
     * Choices: `configs`, `deprecated`, `description` (off by default), `fixable` (off by default), `fixableAndHasSuggestions`, `hasSuggestions` (off by default), `options` (off by default), `requiresTypeChecking`, `type` (off by default).
     * Default: `['deprecated', 'configs', 'fixableAndHasSuggestions', 'requiresTypeChecking']`.
     */
    readonly ruleDocNotices?: readonly NOTICE_TYPE[];
    /** Disallowed sections in each rule doc. Exit with failure if present. */
    readonly ruleDocSectionExclude?: readonly string[];
    /** Required sections in each rule doc. Exit with failure if missing. */
    readonly ruleDocSectionInclude?: readonly string[];
    /** Whether to require an "Options" or "Config" rule doc section and mention of any named options for rules with options. Default: `true`. */
    readonly ruleDocSectionOptions?: boolean;
    /** The format to use for rule doc titles. Default: `prefix-name`. */
    readonly ruleDocTitleFormat?: RuleDocTitleFormat;
    /**
     * Ordered list of columns to display in rule list.
     * Empty columns will be hidden.
     * Choices: `configsError`, `configsOff`, `configsWarn`, `deprecated`, `description`, `fixable`, `fixableAndHasSuggestions` (off by default), `hasSuggestions`, `name`, `options` (off by default), `requiresTypeChecking`, `type` (off by default).
     * Default: `['name', 'description', 'configsError', 'configsWarn', 'configsOff', 'fixable', 'hasSuggestions', 'requiresTypeChecking', 'deprecated']`.
     */
    readonly ruleListColumns?: readonly COLUMN_TYPE[];
    /**
     * Rule property(s) or function to split the rules list by.
     * A separate list and header will be created for each value.
     * Example: `meta.type`.
     */
    readonly ruleListSplit?: string | readonly string[] | RuleListSplitFunction;
    /** Link to documentation about the ESLint configurations exported by the plugin. */
    readonly urlConfigs?: string;
    /**
     * Link (or function to generate a link) to documentation for each rule.
     * Useful when it differs from the rule doc path on disk (e.g. custom documentation site in use).
     * For the string version, use `{name}` placeholder for the rule name.
     */
    readonly urlRuleDoc?: string | UrlRuleDocFunction;
};