eslint/lib/shared/types.js

   1 /**
   2  * @fileoverview Define common types for input completion.
   3  * @author Toru Nagashima <https://github.com/mysticatea>
   4  */
   5 "use strict";
   6
   7 /** @type {any} */
   8 module.exports = {};
   9
  10 /** @typedef {boolean | "off" | "readable" | "readonly" | "writable" | "writeable"} GlobalConf */
  11 /** @typedef {0 | 1 | 2 | "off" | "warn" | "error"} SeverityConf */
  12 /** @typedef {SeverityConf | [SeverityConf, ...any[]]} RuleConf */
  13
  14 /**
  15  * @typedef {Object} EcmaFeatures
  16  * @property {boolean} [globalReturn] Enabling `return` statements at the top-level.
  17  * @property {boolean} [jsx] Enabling JSX syntax.
  18  * @property {boolean} [impliedStrict] Enabling strict mode always.
  19  */
  20
  21 /**
  22  * @typedef {Object} ParserOptions
  23  * @property {EcmaFeatures} [ecmaFeatures] The optional features.
  24  * @property {3|5|6|7|8|9|10|11|12|13|14|2015|2016|2017|2018|2019|2020|2021|2022|2023} [ecmaVersion] The ECMAScript version (or revision number).
  25  * @property {"script"|"module"} [sourceType] The source code type.
  26  * @property {boolean} [allowReserved] Allowing the use of reserved words as identifiers in ES3.
  27  */
  28
  29 /**
  30  * @typedef {Object} LanguageOptions
  31  * @property {number|"latest"} [ecmaVersion] The ECMAScript version (or revision number).
  32  * @property {Record<string, GlobalConf>} [globals] The global variable settings.
  33  * @property {"script"|"module"|"commonjs"} [sourceType] The source code type.
  34  * @property {string|Object} [parser] The parser to use.
  35  * @property {Object} [parserOptions] The parser options to use.
  36  */
  37
  38 /**
  39  * @typedef {Object} ConfigData
  40  * @property {Record<string, boolean>} [env] The environment settings.
  41  * @property {string | string[]} [extends] The path to other config files or the package name of shareable configs.
  42  * @property {Record<string, GlobalConf>} [globals] The global variable settings.
  43  * @property {string | string[]} [ignorePatterns] The glob patterns that ignore to lint.
  44  * @property {boolean} [noInlineConfig] The flag that disables directive comments.
  45  * @property {OverrideConfigData[]} [overrides] The override settings per kind of files.
  46  * @property {string} [parser] The path to a parser or the package name of a parser.
  47  * @property {ParserOptions} [parserOptions] The parser options.
  48  * @property {string[]} [plugins] The plugin specifiers.
  49  * @property {string} [processor] The processor specifier.
  50  * @property {boolean} [reportUnusedDisableDirectives] The flag to report unused `eslint-disable` comments.
  51  * @property {boolean} [root] The root flag.
  52  * @property {Record<string, RuleConf>} [rules] The rule settings.
  53  * @property {Object} [settings] The shared settings.
  54  */
  55
  56 /**
  57  * @typedef {Object} OverrideConfigData
  58  * @property {Record<string, boolean>} [env] The environment settings.
  59  * @property {string | string[]} [excludedFiles] The glob patterns for excluded files.
  60  * @property {string | string[]} [extends] The path to other config files or the package name of shareable configs.
  61  * @property {string | string[]} files The glob patterns for target files.
  62  * @property {Record<string, GlobalConf>} [globals] The global variable settings.
  63  * @property {boolean} [noInlineConfig] The flag that disables directive comments.
  64  * @property {OverrideConfigData[]} [overrides] The override settings per kind of files.
  65  * @property {string} [parser] The path to a parser or the package name of a parser.
  66  * @property {ParserOptions} [parserOptions] The parser options.
  67  * @property {string[]} [plugins] The plugin specifiers.
  68  * @property {string} [processor] The processor specifier.
  69  * @property {boolean} [reportUnusedDisableDirectives] The flag to report unused `eslint-disable` comments.
  70  * @property {Record<string, RuleConf>} [rules] The rule settings.
  71  * @property {Object} [settings] The shared settings.
  72  */
  73
  74 /**
  75  * @typedef {Object} ParseResult
  76  * @property {Object} ast The AST.
  77  * @property {ScopeManager} [scopeManager] The scope manager of the AST.
  78  * @property {Record<string, any>} [services] The services that the parser provides.
  79  * @property {Record<string, string[]>} [visitorKeys] The visitor keys of the AST.
  80  */
  81
  82 /**
  83  * @typedef {Object} Parser
  84  * @property {(text:string, options:ParserOptions) => Object} parse The definition of global variables.
  85  * @property {(text:string, options:ParserOptions) => ParseResult} [parseForESLint] The parser options that will be enabled under this environment.
  86  */
  87
  88 /**
  89  * @typedef {Object} Environment
  90  * @property {Record<string, GlobalConf>} [globals] The definition of global variables.
  91  * @property {ParserOptions} [parserOptions] The parser options that will be enabled under this environment.
  92  */
  93
  94 /**
  95  * @typedef {Object} LintMessage
  96  * @property {number|undefined} column The 1-based column number.
  97  * @property {number} [endColumn] The 1-based column number of the end location.
  98  * @property {number} [endLine] The 1-based line number of the end location.
  99  * @property {boolean} fatal If `true` then this is a fatal error.
 100  * @property {{range:[number,number], text:string}} [fix] Information for autofix.
 101  * @property {number|undefined} line The 1-based line number.
 102  * @property {string} message The error message.
 103  * @property {string|null} ruleId The ID of the rule which makes this message.
 104  * @property {0|1|2} severity The severity of this message.
 105  * @property {Array<{desc?: string, messageId?: string, fix: {range: [number, number], text: string}}>} [suggestions] Information for suggestions.
 106  */
 107
 108 /**
 109  * @typedef {Object} SuppressedLintMessage
 110  * @property {number|undefined} column The 1-based column number.
 111  * @property {number} [endColumn] The 1-based column number of the end location.
 112  * @property {number} [endLine] The 1-based line number of the end location.
 113  * @property {boolean} fatal If `true` then this is a fatal error.
 114  * @property {{range:[number,number], text:string}} [fix] Information for autofix.
 115  * @property {number|undefined} line The 1-based line number.
 116  * @property {string} message The error message.
 117  * @property {string|null} ruleId The ID of the rule which makes this message.
 118  * @property {0|1|2} severity The severity of this message.
 119  * @property {Array<{kind: string, justification: string}>} suppressions The suppression info.
 120  * @property {Array<{desc?: string, messageId?: string, fix: {range: [number, number], text: string}}>} [suggestions] Information for suggestions.
 121  */
 122
 123 /**
 124  * @typedef {Object} SuggestionResult
 125  * @property {string} desc A short description.
 126  * @property {string} [messageId] Id referencing a message for the description.
 127  * @property {{ text: string, range: number[] }} fix fix result info
 128  */
 129
 130 /**
 131  * @typedef {Object} Processor
 132  * @property {(text:string, filename:string) => Array<string | { text:string, filename:string }>} [preprocess] The function to extract code blocks.
 133  * @property {(messagesList:LintMessage[][], filename:string) => LintMessage[]} [postprocess] The function to merge messages.
 134  * @property {boolean} [supportsAutofix] If `true` then it means the processor supports autofix.
 135  */
 136
 137 /**
 138  * @typedef {Object} RuleMetaDocs
 139  * @property {string} description The description of the rule.
 140  * @property {boolean} recommended If `true` then the rule is included in `eslint:recommended` preset.
 141  * @property {string} url The URL of the rule documentation.
 142  */
 143
 144 /**
 145  * @typedef {Object} RuleMeta
 146  * @property {boolean} [deprecated] If `true` then the rule has been deprecated.
 147  * @property {RuleMetaDocs} docs The document information of the rule.
 148  * @property {"code"|"whitespace"} [fixable] The autofix type.
 149  * @property {boolean} [hasSuggestions] If `true` then the rule provides suggestions.
 150  * @property {Record<string,string>} [messages] The messages the rule reports.
 151  * @property {string[]} [replacedBy] The IDs of the alternative rules.
 152  * @property {Array|Object} schema The option schema of the rule.
 153  * @property {"problem"|"suggestion"|"layout"} type The rule type.
 154  */
 155
 156 /**
 157  * @typedef {Object} Rule
 158  * @property {Function} create The factory of the rule.
 159  * @property {RuleMeta} meta The meta data of the rule.
 160  */
 161
 162 /**
 163  * @typedef {Object} Plugin
 164  * @property {Record<string, ConfigData>} [configs] The definition of plugin configs.
 165  * @property {Record<string, Environment>} [environments] The definition of plugin environments.
 166  * @property {Record<string, Processor>} [processors] The definition of plugin processors.
 167  * @property {Record<string, Function | Rule>} [rules] The definition of plugin rules.
 168  */
 169
 170 /**
 171  * Information of deprecated rules.
 172  * @typedef {Object} DeprecatedRuleInfo
 173  * @property {string} ruleId The rule ID.
 174  * @property {string[]} replacedBy The rule IDs that replace this deprecated rule.
 175  */
 176
 177 /**
 178  * A linting result.
 179  * @typedef {Object} LintResult
 180  * @property {string} filePath The path to the file that was linted.
 181  * @property {LintMessage[]} messages All of the messages for the result.
 182  * @property {SuppressedLintMessage[]} suppressedMessages All of the suppressed messages for the result.
 183  * @property {number} errorCount Number of errors for the result.
 184  * @property {number} fatalErrorCount Number of fatal errors for the result.
 185  * @property {number} warningCount Number of warnings for the result.
 186  * @property {number} fixableErrorCount Number of fixable errors for the result.
 187  * @property {number} fixableWarningCount Number of fixable warnings for the result.
 188  * @property {string} [source] The source code of the file that was linted.
 189  * @property {string} [output] The source code of the file that was linted, with as many fixes applied as possible.
 190  * @property {DeprecatedRuleInfo[]} usedDeprecatedRules The list of used deprecated rules.
 191  */
 192
 193 /**
 194  * A formatter function.
 195  * @callback FormatterFunction
 196  * @param {LintResult[]} results The list of linting results.
 197  * @param {{cwd: string, rulesMeta: Record<string, RuleMeta>}} [context] A context object.
 198  * @returns {string | Promise<string>} Formatted text.
 199  */