/**

* @fileoverview Shared types for ESLint Core.

*/

//------------------------------------------------------------------------------

// Imports

//------------------------------------------------------------------------------

import type { JSONSchema4 } from "json-schema";

//------------------------------------------------------------------------------

// Helper Types

//------------------------------------------------------------------------------

/**

* Represents an error inside of a file.

*/

export interface FileError {

message: string;

line: number;

column: number;

endLine?: number;

endColumn?: number;

}

/**

* Represents a problem found in a file.

*/

export interface FileProblem {

ruleId: string | null;

message: string;

loc: SourceLocation;

}

//------------------------------------------------------------------------------

// ASTs

//------------------------------------------------------------------------------

/**

* Represents the start and end coordinates of a node inside the source.

*/

export interface SourceLocation {

start: Position;

end: Position;

}

/**

* Represents the start and end coordinates of a node inside the source with an offset.

*/

export interface SourceLocationWithOffset {

start: PositionWithOffset;

end: PositionWithOffset;

}

/**

* Represents a location coordinate inside the source. ESLint-style formats

* have just `line` and `column` while others may have `offset` as well.

*/

export interface Position {

line: number;

column: number;

}

/**

* Represents a location coordinate inside the source with an offset.

*/

export interface PositionWithOffset extends Position {

offset: number;

}

/**

* Represents a range of characters in the source.

*/

export type SourceRange = [number, number];

//------------------------------------------------------------------------------

// Rules

//------------------------------------------------------------------------------

/**

* What the rule is responsible for finding:

* - `problem` means the rule has noticed a potential error.

* - `suggestion` means the rule suggests an alternate or better approach.

* - `layout` means the rule is looking at spacing, indentation, etc.

*/

export type RuleType = "problem" | "suggestion" | "layout";

/**

* The type of fix the rule can provide:

* - `code` means the rule can fix syntax.

* - `whitespace` means the rule can fix spacing and indentation.

*/

export type RuleFixType = "code" | "whitespace";

/* eslint-disable @typescript-eslint/no-explicit-any -- Necessary to allow subclasses to work correctly */

/**

* An object containing visitor information for a rule. Each method is either the

* name of a node type or a selector, or is a method that will be called at specific

* times during the traversal.

*/

export type RuleVisitor = Record<

string,

((...args: any[]) => void) | undefined

>;

/* eslint-enable @typescript-eslint/no-explicit-any -- Necessary to allow subclasses to work correctly */

/**

* Rule meta information used for documentation.

*/

export interface RulesMetaDocs {

/**

* A short description of the rule.

*/

description?: string | undefined;

/**

* The URL to the documentation for the rule.

*/

url?: string | undefined;

/**

* Indicates if the rule is generally recommended for all users.

*

* Note - this will always be a boolean for core rules, but may be used in any way by plugins.

*/

recommended?: unknown;

/**

* Indicates if the rule is frozen (no longer accepting feature requests).

*/

frozen?: boolean | undefined;

/**

* The dialects of the languages that the rule is intended to lint.

* @example

* ["JavaScript", "TypeScript"]

*/

dialects?: string[] | undefined;

}

/**

* Meta information about a rule.

*/

export interface RulesMeta<

MessageIds extends string = string,

RuleOptions = unknown[],

ExtRuleDocs = unknown,

> {

/**

* Properties that are used when documenting the rule.

*/

docs?: (RulesMetaDocs & ExtRuleDocs) | undefined;

/**

* The type of rule.

*/

type?: RuleType | undefined;

/**

* The schema for the rule options. Required if the rule has options.

*/

schema?: JSONSchema4 | JSONSchema4[] | false | undefined;

/**

* Any default options to be recursively merged on top of any user-provided options.

*/

defaultOptions?: RuleOptions;

/**

* The messages that the rule can report.

*/

messages?: Record<MessageIds, string>;

/**

* Indicates whether the rule has been deprecated or provides additional metadata about the deprecation. Omit if not deprecated.

*/

deprecated?: boolean | DeprecatedInfo | undefined;

/**

* @deprecated Use deprecated.replacedBy instead.

* The name of the rule(s) this rule was replaced by, if it was deprecated.

*/

replacedBy?: readonly string[] | undefined;

/**

* Indicates if the rule is fixable, and if so, what type of fix it provides.

*/

fixable?: RuleFixType | undefined;

/**

* Indicates if the rule may provide suggestions.

*/

hasSuggestions?: boolean | undefined;

/**

* The language the rule is intended to lint.

* @deprecated Use `languages` instead.

*/

language?: string;

/**

* The dialects of `language` that the rule is intended to lint.

* @deprecated Use `docs.dialects` instead.

*/

dialects?: string[];

/**

* Languages supported by this rule in the format `"plugin/language"`.

* Use `"*"` for any language or `"plugin/*"` for any language from a specific plugin.

* @example

* ["js/js", "markdown/gfm", "json/jsonc", "css/css"]

*/

languages?: string[] | undefined;

}

/**

* Provides additional metadata about a deprecation.

*/

export interface DeprecatedInfo {

/**

* General message presented to the user, e.g. for the key rule why the rule

* is deprecated or for info how to replace the rule.

*/

message?: string;

/**

* URL to more information about this deprecation in general.

*/

url?: string;

/**

* An empty array explicitly states that there is no replacement.

*/

replacedBy?: ReplacedByInfo[];

/**

* The package version since when the rule is deprecated (should use full

* semver without a leading "v").

*/

deprecatedSince?: string;

/**

* The estimated version when the rule is removed (probably the next major

* version). null means the rule is "frozen" (will be available but will not

* be changed).

*/

availableUntil?: string | null;

}

/**

* Provides metadata about a replacement

*/

export interface ReplacedByInfo {

/**

* General message presented to the user, e.g. how to replace the rule

*/

message?: string;

/**

* URL to more information about this replacement in general

*/

url?: string;

/**

* Name should be "eslint" if the replacement is an ESLint core rule. Omit

* the property if the replacement is in the same plugin.

*/

plugin?: ExternalSpecifier;

/**

* Name and documentation of the replacement rule

*/

rule?: ExternalSpecifier;

}

/**

* Specifies the name and url of an external resource. At least one property

* should be set.

*/

export interface ExternalSpecifier {

/**

* Name of the referenced plugin / rule.

*/

name?: string;

/**

* URL pointing to documentation for the plugin / rule.

*/

url?: string;

}

/**

* Generic type for `RuleContext`.

*/

export interface RuleContextTypeOptions {

LangOptions: LanguageOptions;

Code: SourceCode;

RuleOptions: unknown[];

Node: unknown;

MessageIds: string;

}

/**

* Represents the context object that is passed to a rule. This object contains

* information about the current state of the linting process and is the rule's

* view into the outside world.

*/

export interface RuleContext<

Options extends RuleContextTypeOptions = RuleContextTypeOptions,

> {

/**

* The current working directory for the session.

*/

cwd: string;

/**

* The filename of the file being linted.

*/

filename: string;

/**

* The physical filename of the file being linted.

*/

physicalFilename: string;

/**

* The source code object that the rule is running on.

*/

sourceCode: Options["Code"];

/**

* Shared settings for the configuration.

*/

settings: SettingsConfig;

/**

* The language options for the configuration.

*/

languageOptions: Options["LangOptions"];

/**

* The rule ID.

*/

id: string;

/**

* The rule's configured options.

*/

options: Options["RuleOptions"];

/**

* The report function that the rule should use to report problems.

* @param violation The violation to report.

*/

report(

violation: ViolationReport<Options["Node"], Options["MessageIds"]>,

): void;

}

// #region Rule Fixing

/**

* Manager of text edits for a rule fix.

*/

export interface RuleTextEditor<EditableSyntaxElement = unknown> {

/**

* Inserts text after the specified node or token.

* @param syntaxElement The node or token to insert after.

* @param text The edit to insert after the node or token.

*/

insertTextAfter(

syntaxElement: EditableSyntaxElement,

text: string,

): RuleTextEdit;

/**

* Inserts text after the specified range.

* @param range The range to insert after.

* @param text The edit to insert after the range.

*/

insertTextAfterRange(range: SourceRange, text: string): RuleTextEdit;

/**

* Inserts text before the specified node or token.

* @param syntaxElement A syntax element with location information to insert before.

* @param text The edit to insert before the node or token.

*/

insertTextBefore(

syntaxElement: EditableSyntaxElement,

text: string,

): RuleTextEdit;

/**

* Inserts text before the specified range.

* @param range The range to insert before.

* @param text The edit to insert before the range.

*/

insertTextBeforeRange(range: SourceRange, text: string): RuleTextEdit;

/**

* Removes the specified node or token.

* @param syntaxElement A syntax element with location information to remove.

* @returns The edit to remove the node or token.

*/

remove(syntaxElement: EditableSyntaxElement): RuleTextEdit;

/**

* Removes the specified range.

* @param range The range to remove.

* @returns The edit to remove the range.

*/

removeRange(range: SourceRange): RuleTextEdit;

/**

* Replaces the specified node or token with the given text.

* @param syntaxElement A syntax element with location information to replace.

* @param text The text to replace the node or token with.

* @returns The edit to replace the node or token.

*/

replaceText(

syntaxElement: EditableSyntaxElement,

text: string,

): RuleTextEdit;

/**

* Replaces the specified range with the given text.

* @param range The range to replace.

* @param text The text to replace the range with.

* @returns The edit to replace the range.

*/

replaceTextRange(range: SourceRange, text: string): RuleTextEdit;

}

/**

* Represents a fix for a rule violation implemented as a text edit.

*/

export interface RuleTextEdit {

/**

* The range to replace.

*/

range: SourceRange;

/**

* The text to insert.

*/

text: string;

}

// #endregion

/**

* Fixes a violation.

* @param fixer The text editor to apply the fix.

* @returns The fix(es) for the violation.

*/

export type RuleFixer = (

fixer: RuleTextEditor,

) => RuleTextEdit | Iterable<RuleTextEdit> | null;

/**

* Data that can be used to fill placeholders in error messages.

*/

export type MessagePlaceholderData = Record<

string,

string | number | boolean | bigint | null | undefined

>;

export interface ViolationReportBase<MessageIds extends string = string> {

/**

* The data to insert into the message.

*/

data?: MessagePlaceholderData | undefined;

/**

* The fix to be applied for the violation.

*/

fix?: RuleFixer | null | undefined;

/**

* An array of suggested fixes for the problem. These fixes may change the

* behavior of the code, so they are not applied automatically.

*/

suggest?: SuggestedEdit<MessageIds>[] | null | undefined;

}

export type ViolationMessage<MessageIds extends string = string> =

| { message: string }

| { messageId: MessageIds };

export type ViolationLocation<Node> =

| { loc: SourceLocation | Position }

| { node: Node };

export type ViolationReport<

Node = unknown,

MessageIds extends string = string,

> = ViolationReportBase<MessageIds> &

ViolationMessage<MessageIds> &

ViolationLocation<Node>;

// #region Suggestions

export interface SuggestedEditBase {

/**

* The data to insert into the message.

*/

data?: MessagePlaceholderData | undefined;

/**

* The fix to be applied for the suggestion.

*/

fix: RuleFixer;

}

export type SuggestionMessage<MessageIds extends string = string> =

| { desc: string }

| { messageId: MessageIds };

/**

* A suggested edit for a rule violation.

*/

export type SuggestedEdit<MessageIds extends string = string> =

SuggestedEditBase & SuggestionMessage<MessageIds>;

/**

* The normalized version of a lint suggestion.

*/

export interface LintSuggestion {

/** A short description. */

desc: string;

/** Fix result info. */

fix: RuleTextEdit;

/** Id referencing a message for the description. */

messageId?: string | undefined;

}

/**

* The normalized version of a lint violation message.

*/

export interface LintMessage {

/** The 1-based column number. */

column: number;

/** The 1-based line number. */

line: number;

/** The 1-based column number of the end location. */

endColumn?: number | undefined;

/** The 1-based line number of the end location. */

endLine?: number | undefined;

/** The ID of the rule which makes this message. */

ruleId: string | null;

/** The reported message. */

message: string;

/** The ID of the message in the rule's meta. */

messageId?: string | undefined;

/** If `true` then this is a fatal error. */

fatal?: true | undefined;

/** The severity of this message. */

severity: Exclude<SeverityLevel, 0>;

/** Information for autofix. */

fix?: RuleTextEdit | undefined;

/** Information for suggestions. */

suggestions?: LintSuggestion[] | undefined;

}

// #endregion

/**

* Generic options for the `RuleDefinition` type.

*/

export interface RuleDefinitionTypeOptions {

LangOptions: LanguageOptions;

Code: SourceCode;

RuleOptions: unknown[];

Visitor: RuleVisitor;

Node: unknown;

MessageIds: string;

ExtRuleDocs: unknown;

}

/**

* The definition of an ESLint rule.

*/

export interface RuleDefinition<

Options extends RuleDefinitionTypeOptions = RuleDefinitionTypeOptions,

> {

/**

* The meta information for the rule.

*/

meta?: RulesMeta<

Options["MessageIds"],

Options["RuleOptions"],

Options["ExtRuleDocs"]

>;

/**

* Creates the visitor that ESLint uses to apply the rule during traversal.

* @param context The rule context.

* @returns The rule visitor.

*/

create(

context: RuleContext<{

LangOptions: Options["LangOptions"];

Code: Options["Code"];

RuleOptions: Options["RuleOptions"];

Node: Options["Node"];

MessageIds: Options["MessageIds"];

}>,

): Options["Visitor"];

}

/**

* Defaults for non-language-related `RuleDefinition` options.

* @deprecated Use the same type from `@eslint/plugin-kit` instead.

*/

export interface CustomRuleTypeDefinitions {

RuleOptions: unknown[];

MessageIds: string;

ExtRuleDocs: Record<string, unknown>;

}

/**

* A helper type to define language specific specializations of the `RuleDefinition` type.

* @deprecated Use the same type from `@eslint/plugin-kit` instead.

*

* @example

* ```ts

* type YourRuleDefinition<

* Options extends Partial<CustomRuleTypeDefinitions> = {},

* > = CustomRuleDefinitionType<

* {

* LangOptions: YourLanguageOptions;

* Code: YourSourceCode;

* Visitor: YourRuleVisitor;

* Node: YourNode;

* },

* Options

* >;

* ```

*/

export type CustomRuleDefinitionType<

LanguageSpecificOptions extends Omit<

RuleDefinitionTypeOptions,

keyof CustomRuleTypeDefinitions

>,

Options extends Partial<CustomRuleTypeDefinitions>,

> = RuleDefinition<

// Language specific type options (non-configurable)

LanguageSpecificOptions &

Required<

// Rule specific type options (custom)

Options &

// Rule specific type options (defaults)

Omit<CustomRuleTypeDefinitions, keyof Options>

>

>;

//------------------------------------------------------------------------------

// Config

//------------------------------------------------------------------------------

// #region Severities

/**

* The human readable severity level used in a configuration.

*/

export type SeverityName = "off" | "warn" | "error";

/**

* The numeric severity level for a rule.

*

* - `0` means off.

* - `1` means warn.

* - `2` means error.

*/

export type SeverityLevel = 0 | 1 | 2;

/**

* The severity of a rule in a configuration.

*/

export type Severity = SeverityName | SeverityLevel;

// #endregion

/**

* Represents the metadata for an object, such as a plugin or processor.

*/

export interface ObjectMetaProperties {

/** @deprecated Use `meta.name` instead. */

name?: string | undefined;

/** @deprecated Use `meta.version` instead. */

version?: string | undefined;

meta?: {

name?: string | undefined;

version?: string | undefined;

};

}

/**

* Represents the configuration options for the core linter.

*/

export interface LinterOptionsConfig {

/**

* Indicates whether or not inline configuration is evaluated.

*/

noInlineConfig?: boolean;

/**

* Indicates what to do when an unused disable directive is found.

*/

reportUnusedDisableDirectives?: boolean | Severity;

/**

* A severity value indicating if and how unused inline configs should be

* tracked and reported.

*/

reportUnusedInlineConfigs?: Severity;

}

/**

* The configuration for a rule.

*/

export type RuleConfig<RuleOptions extends unknown[] = unknown[]> =

| Severity

| [Severity, ...Partial<RuleOptions>];

/* eslint-disable @typescript-eslint/consistent-indexed-object-style -- needed to allow extension */

/**

* A collection of rules and their configurations.

*/

export interface RulesConfig {

[key: string]: RuleConfig;

}

/**

* A collection of settings.

*/

export interface SettingsConfig {

[key: string]: unknown;

}

/* eslint-enable @typescript-eslint/consistent-indexed-object-style -- needed to allow extension */

/**

* The configuration for a set of files.

*/

export interface ConfigObject<Rules extends RulesConfig = RulesConfig> {

/**

* A string to identify the configuration object. Used in error messages and

* inspection tools.

*/

name?: string;

/**

* Path to the directory where the configuration object should apply.

* `files` and `ignores` patterns in the configuration object are

* interpreted as relative to this path.

*/

basePath?: string;

/**

* An array of glob patterns indicating the files that the configuration

* object should apply to. If not specified, the configuration object applies

* to all files

*/

files?: (string | string[])[];

/**

* An array of glob patterns indicating the files that the configuration

* object should not apply to. If not specified, the configuration object

* applies to all files matched by files

*/

ignores?: string[];

/**

* The name of the language used for linting. This is used to determine the

* parser and other language-specific settings.

* @since 9.7.0

*/

language?: string;

/**

* An object containing settings related to how the language is configured for

* linting.

*/

languageOptions?: LanguageOptions;

/**

* An object containing settings related to the linting process

*/

linterOptions?: LinterOptionsConfig;

/**

* Either an object containing preprocess() and postprocess() methods or a

* string indicating the name of a processor inside of a plugin

* (i.e., "pluginName/processorName").

*/

processor?: string | Processor;

/**

* An object containing a name-value mapping of plugin names to plugin objects.

* When files is specified, these plugins are only available to the matching files.

*/

plugins?: Record<string, Plugin>;

/**

* An object containing the configured rules. When files or ignores are specified,

* these rule configurations are only available to the matching files.

*/

rules?: Partial<Rules>;

/**

* An object containing name-value pairs of information that should be

* available to all rules.

*/

settings?: SettingsConfig;

}

//------------------------------------------------------------------------------

// Legacy Config

// https://eslint.org/docs/latest/use/configure/configuration-files#legacy-config

//------------------------------------------------------------------------------

/* eslint-disable @typescript-eslint/consistent-indexed-object-style, @typescript-eslint/no-explicit-any -- needed for backward compatibility */

/** @deprecated Only supported in legacy eslintrc config format. */

export type GlobalAccess =

| boolean

| "off"

| "readable"

| "readonly"

| "writable"

| "writeable";

/** @deprecated Only supported in legacy eslintrc config format. */

export interface GlobalsConfig {

[name: string]: GlobalAccess;

}

/**

* The ECMAScript version of the code being linted.

* @deprecated Only supported in legacy eslintrc config format.

*/

export type EcmaVersion =

| 3

| 5

| 6

| 7

| 8

| 9

| 10

| 11

| 12

| 13

| 14

| 15

| 16

| 17

| 2015

| 2016

| 2017

| 2018

| 2019

| 2020

| 2021

| 2022

| 2023

| 2024

| 2025

| 2026

| "latest";

/**

* The type of JavaScript source code.

* @deprecated Only supported in legacy eslintrc config format.

*/

export type JavaScriptSourceType = "script" | "module" | "commonjs";

/**

* Parser options.

* @deprecated Only supported in legacy eslintrc config format.

* @see [Specifying Parser Options](https://eslint.org/docs/latest/use/configure/language-options#specifying-parser-options)

*/

export interface JavaScriptParserOptionsConfig {

/**

* Allow the use of reserved words as identifiers (if `ecmaVersion` is 3).

*

* @default false

*/

allowReserved?: boolean | undefined;

/**

* Accepts any valid ECMAScript version number or `'latest'`:

*

* - A version: es3, es5, es6, es7, es8, es9, es10, es11, es12, es13, es14, ..., or

* - A year: es2015, es2016, es2017, es2018, es2019, es2020, es2021, es2022, es2023, ..., or

* - `'latest'`

*

* When it's a version or a year, the value must be a number - so do not include the `es` prefix.

*

* Specifies the version of ECMAScript syntax you want to use. This is used by the parser to determine how to perform scope analysis, and it affects the default

*

* @default 5

*/

ecmaVersion?: EcmaVersion | undefined;

/**

* The type of JavaScript source code. Possible values are "script" for

* traditional script files, "module" for ECMAScript modules (ESM), and

* "commonjs" for CommonJS files.

*

* @default 'script'

*

* @see https://eslint.org/docs/latest/use/configure/language-options-deprecated#specifying-parser-options

*/

sourceType?: JavaScriptSourceType | undefined;

/**

* An object indicating which additional language features you'd like to use.

*

* @see https://eslint.org/docs/latest/use/configure/language-options-deprecated#specifying-parser-options

*/

ecmaFeatures?:

| {

globalReturn?: boolean | undefined;

impliedStrict?: boolean | undefined;

jsx?: boolean | undefined;

[key: string]: any;

}

| undefined;

[key: string]: any;

}

/** @deprecated Only supported in legacy eslintrc config format. */

export interface EnvironmentConfig {

/** The definition of global variables. */

globals?: GlobalsConfig | undefined;

/** The parser options that will be enabled under this environment. */

parserOptions?: JavaScriptParserOptionsConfig | undefined;

}

/**

* A configuration object that may have a `rules` block.

*/

export interface HasRules<Rules extends RulesConfig = RulesConfig> {

rules?: Partial<Rules> | undefined;

}

/**

* ESLint legacy configuration.

*

* @see [ESLint Legacy Configuration](https://eslint.org/docs/latest/use/configure/)

*/

export interface BaseConfig<

Rules extends RulesConfig = RulesConfig,

OverrideRules extends RulesConfig = Rules,

> extends HasRules<Rules> {

$schema?: string | undefined;

/**

* An environment provides predefined global variables.

*

* @see [Environments](https://eslint.org/docs/latest/use/configure/language-options-deprecated#specifying-environments)

*/

env?: { [name: string]: boolean } | undefined;

/**

* Extending configuration files.

*

* @see [Extends](https://eslint.org/docs/latest/use/configure/configuration-files-deprecated#extending-configuration-files)

*/

extends?: string | string[] | undefined;

/**

* Specifying globals.

*

* @see [Globals](https://eslint.org/docs/latest/use/configure/language-options-deprecated#specifying-globals)

*/

globals?: GlobalsConfig | undefined;

/**

* Disable processing of inline comments.

*

* @see [Disabling Inline Comments](https://eslint.org/docs/latest/use/configure/rules-deprecated#disabling-inline-comments)

*/

noInlineConfig?: boolean | undefined;