From 3ef58140550cf8ff34af35fc4d9a1f9a124fe0e6 Mon Sep 17 00:00:00 2001 From: Milos Djermanovic Date: Mon, 5 Jun 2023 22:48:12 +0200 Subject: [PATCH] docs: Revert all changes after the license change (#17227) --- docs/src/extend/code-path-analysis.md | 3 +- docs/src/extend/custom-processors.md | 10 +- docs/src/extend/custom-rules.md | 495 ++++++++---------- docs/src/extend/plugins.md | 30 +- docs/src/integrate/nodejs-api.md | 4 +- docs/src/maintain/manage-issues.md | 20 +- docs/src/rules/callback-return.md | 2 +- docs/src/rules/global-require.md | 2 +- docs/src/rules/handle-callback-err.md | 2 +- docs/src/rules/id-match.md | 4 +- docs/src/rules/no-buffer-constructor.md | 2 +- docs/src/rules/no-div-regex.md | 4 +- docs/src/rules/no-mixed-requires.md | 2 +- docs/src/rules/no-new-require.md | 2 +- docs/src/rules/no-new.md | 2 +- docs/src/rules/no-path-concat.md | 2 +- docs/src/rules/no-process-env.md | 2 +- docs/src/rules/no-process-exit.md | 2 +- docs/src/rules/no-restricted-modules.md | 2 +- docs/src/rules/no-sync.md | 2 +- docs/src/rules/semi.md | 77 +-- .../use/configure/configuration-files-new.md | 36 +- docs/src/use/configure/configuration-files.md | 4 - docs/src/use/configure/language-options.md | 4 +- docs/src/use/formatters/index.md | 2 +- docs/src/use/integrations.md | 21 +- docs/src/use/migrate-to-8.0.0.md | 10 +- docs/src/use/migrating-to-5.0.0.md | 2 +- docs/src/use/migrating-to-7.0.0.md | 2 +- 29 files changed, 306 insertions(+), 446 deletions(-) diff --git a/docs/src/extend/code-path-analysis.md b/docs/src/extend/code-path-analysis.md index 7344f8647ad..6cb7d2ac571 100644 --- a/docs/src/extend/code-path-analysis.md +++ b/docs/src/extend/code-path-analysis.md @@ -259,8 +259,7 @@ Please use a map of information instead. ```js function hasCb(node, context) { if (node.type.indexOf("Function") !== -1) { - const sourceCode = context.sourceCode; - return sourceCode.getDeclaredVariables(node).some(function(v) { + return context.getDeclaredVariables(node).some(function(v) { return v.type === "Parameter" && v.name === "cb"; }); } diff --git a/docs/src/extend/custom-processors.md b/docs/src/extend/custom-processors.md index d112d724688..8f330883b03 100644 --- a/docs/src/extend/custom-processors.md +++ b/docs/src/extend/custom-processors.md @@ -59,19 +59,19 @@ Reported problems have the following location information in each lint message: type LintMessage = { /// The 1-based line number where the message occurs. - line?: number; + line: number; /// The 1-based column number where the message occurs. - column?: number; + column: number; /// The 1-based line number of the end location. - endLine?: number; + endLine: number; /// The 1-based column number of the end location. - endColumn?: number; + endColumn: number; /// If `true`, this is a fatal error. - fatal?: boolean; + fatal: boolean; /// Information for an autofix. fix: Fix; diff --git a/docs/src/extend/custom-rules.md b/docs/src/extend/custom-rules.md index 35b04fdbf8e..0118757c6a4 100644 --- a/docs/src/extend/custom-rules.md +++ b/docs/src/extend/custom-rules.md @@ -34,43 +34,44 @@ module.exports = { }; ``` -## Rule Structure +## Rule Basics -The source file for a rule exports an object with the following properties. Both custom rules and core rules follow this format. +The source file for a rule exports an object with the following properties. -`meta`: (`object`) Contains metadata for the rule: +`meta` (object) contains metadata for the rule: -* `type`: (`string`) Indicates the type of rule, which is one of `"problem"`, `"suggestion"`, or `"layout"`: +* `type` (string) indicates the type of rule, which is one of `"problem"`, `"suggestion"`, or `"layout"`: + * `"problem"` means the rule is identifying code that either will cause an error or may cause a confusing behavior. Developers should consider this a high priority to resolve. + * `"suggestion"` means the rule is identifying something that could be done in a better way but no errors will occur if the code isn't changed. + * `"layout"` means the rule cares primarily about whitespace, semicolons, commas, and parentheses, all the parts of the program that determine how the code looks rather than how it executes. These rules work on parts of the code that aren't specified in the AST. - * `"problem"`: The rule is identifying code that either will cause an error or may cause a confusing behavior. Developers should consider this a high priority to resolve. - * `"suggestion"`: The rule is identifying something that could be done in a better way but no errors will occur if the code isn't changed. - * `"layout"`: The rule cares primarily about whitespace, semicolons, commas, and parentheses, all the parts of the program that determine how the code looks rather than how it executes. These rules work on parts of the code that aren't specified in the AST. +* `docs` (object) is required for core rules of ESLint: -* `docs`: (`object`) Required for core rules and optional for custom rules. Core rules have specific entries inside of `docs` while custom rules can include any properties that you need. The following properties are only relevant when working on core rules. + * `description` (string) provides the short description of the rule in the [rules index](../rules/) + * `recommended` (boolean) is whether the `"extends": "eslint:recommended"` property in a [configuration file](../use/configure/configuration-files#extending-configuration-files) enables the rule + * `url` (string) specifies the URL at which the full documentation can be accessed (enabling code editors to provide a helpful link on highlighted rule violations) - * `description`: (`string`) Provides the short description of the rule in the [rules index](../rules/). - * `recommended`: (`boolean`) Specifies whether the `"extends": "eslint:recommended"` property in a [configuration file](../use/configure/configuration-files#extending-configuration-files) enables the rule. - * `url`: (`string`) Specifies the URL at which the full documentation can be accessed (enabling code editors to provide a helpful link on highlighted rule violations). + In a custom rule or plugin, you can omit `docs` or include any properties that you need in it. -* `fixable`: (`string`) Either `"code"` or `"whitespace"` if the `--fix` option on the [command line](../use/command-line-interface#--fix) automatically fixes problems reported by the rule. +* `fixable` (string) is either `"code"` or `"whitespace"` if the `--fix` option on the [command line](../use/command-line-interface#--fix) automatically fixes problems reported by the rule - **Important:** the `fixable` property is mandatory for fixable rules. If this property isn't specified, ESLint will throw an error whenever the rule attempts to produce a fix. Omit the `fixable` property if the rule is not fixable. + **Important:** the `fixable` property is mandatory for fixable rules. If this property isn't specified, ESLint will throw an error whenever the rule attempts to produce a fix. Omit the `fixable` property if the rule is not fixable. -* `hasSuggestions`: (`boolean`) Specifies whether rules can return suggestions (defaults to `false` if omitted). +* `hasSuggestions` (boolean) specifies whether rules can return suggestions (defaults to `false` if omitted) - **Important:** the `hasSuggestions` property is mandatory for rules that provide suggestions. If this property isn't set to `true`, ESLint will throw an error whenever the rule attempts to produce a suggestion. Omit the `hasSuggestions` property if the rule does not provide suggestions. + **Important:** the `hasSuggestions` property is mandatory for rules that provide suggestions. If this property isn't set to `true`, ESLint will throw an error whenever the rule attempts to produce a suggestion. Omit the `hasSuggestions` property if the rule does not provide suggestions. -* `schema`: (`object | array`) Specifies the [options](#options-schemas) so ESLint can prevent invalid [rule configurations](../use/configure/rules). +* `schema` (array) specifies the [options](#options-schemas) so ESLint can prevent invalid [rule configurations](../use/configure/rules) -* `deprecated`: (`boolean`) Indicates whether the rule has been deprecated. You may omit the `deprecated` property if the rule has not been deprecated. +* `deprecated` (boolean) indicates whether the rule has been deprecated. You may omit the `deprecated` property if the rule has not been deprecated. -* `replacedBy`: (`array`) In the case of a deprecated rule, specify replacement rule(s). +* `replacedBy` (array) in the case of a deprecated rule, specifies replacement rule(s) -`create()`: Returns an object with methods that ESLint calls to "visit" nodes while traversing the abstract syntax tree (AST as defined by [ESTree](https://github.com/estree/estree)) of JavaScript code: +`create` (function) returns an object with methods that ESLint calls to "visit" nodes while traversing the abstract syntax tree (AST as defined by [ESTree](https://github.com/estree/estree)) of JavaScript code: -* If a key is a node type or a [selector](./selectors), ESLint calls that **visitor** function while going **down** the tree. -* If a key is a node type or a [selector](./selectors) plus `:exit`, ESLint calls that **visitor** function while going **up** the tree. -* If a key is an event name, ESLint calls that **handler** function for [code path analysis](code-path-analysis). +* if a key is a node type or a [selector](./selectors), ESLint calls that **visitor** function while going **down** the tree +* if a key is a node type or a [selector](./selectors) plus `:exit`, ESLint calls that **visitor** function while going **up** the tree +* if a key is an event name, ESLint calls that **handler** function for [code path analysis](code-path-analysis) A rule can use the current node and its surrounding tree to report or fix problems. @@ -105,40 +106,20 @@ module.exports = { ## The Context Object -The `context` object is the only argument of the `create` method in a rule. For example: +The `context` object contains additional functionality that is helpful for rules to do their jobs. As the name implies, the `context` object contains information that is relevant to the context of the rule. The `context` object has the following properties: -```js -// customRule.js - -module.exports = { - meta: { ... }, - // `context` object is the argument - create(context) { - // ... - } -}; -``` - -As the name implies, the `context` object contains information that is relevant to the context of the rule. - -The `context` object has the following properties: - -* `id`: (`string`) The rule ID. -* `filename`: (`string`) The filename associated with the source. -* `physicalFilename`: (`string`) When linting a file, it provides the full path of the file on disk without any code block information. When linting text, it provides the value passed to `—stdin-filename` or `` if not specified. -* `cwd`: (`string`) The `cwd` option passed to the [Linter](../integrate/nodejs-api#linter). It is a path to a directory that should be considered the current working directory. -* `options`: (`array`) An array of the [configured options](../use/configure/rules) for this rule. This array does not include the rule severity (see the [dedicated section](#accessing-options-passed-to-a-rule)). -* `sourceCode`: (`object`) A `SourceCode` object that you can use to work with the source that was passed to ESLint (see [Accessing the Source Code](#accessing-the-source-code)). -* `settings`: (`object`) The [shared settings](../use/configure/configuration-files#adding-shared-settings) from the configuration. -* `parserPath`: (`string`) The name of the `parser` from the configuration. -* `parserServices`: (`object`) Contains parser-provided services for rules. The default parser does not provide any services. However, if a rule is intended to be used with a custom parser, it could use `parserServices` to access anything provided by that parser. (For example, a TypeScript parser could provide the ability to get the computed type of a given node.) -* `parserOptions`: The parser options configured for this run (more details [here](../use/configure/language-options#specifying-parser-options)). +* `parserOptions` - the parser options configured for this run (more details [here](../use/configure/language-options#specifying-parser-options)). +* `id` - the rule ID. +* `options` - an array of the [configured options](../use/configure/rules) for this rule. This array does not include the rule severity. For more information, see [here](#contextoptions). +* `settings` - the [shared settings](../use/configure/configuration-files#adding-shared-settings) from configuration. +* `parserPath` - the name of the `parser` from configuration. +* `parserServices` - an object containing parser-provided services for rules. The default parser does not provide any services. However, if a rule is intended to be used with a custom parser, it could use `parserServices` to access anything provided by that parser. (For example, a TypeScript parser could provide the ability to get the computed type of a given node.) Additionally, the `context` object has the following methods: -* `getAncestors()`: (**Deprecated:** Use `SourceCode#getAncestors(node)` instead.) Returns an array of the ancestors of the currently-traversed node, starting at the root of the AST and continuing through the direct parent of the current node. This array does not include the currently-traversed node itself. -* `getCwd()`: (**Deprecated:** Use `context.cwd` instead.) Returns the `cwd` option passed to the [Linter](../integrate/nodejs-api#linter). It is a path to a directory that should be considered the current working directory. -* `getDeclaredVariables(node)`: (**Deprecated:** Use `SourceCode#getDeclaredVariables(node)` instead.) Returns a list of [variables](./scope-manager-interface#variable-interface) declared by the given node. This information can be used to track references to variables. +* `getAncestors()` - returns an array of the ancestors of the currently-traversed node, starting at the root of the AST and continuing through the direct parent of the current node. This array does not include the currently-traversed node itself. +* `getCwd()` - returns the `cwd` passed to [Linter](../integrate/nodejs-api#linter). It is a path to a directory that should be considered as the current working directory. +* `getDeclaredVariables(node)` - returns a list of [variables](./scope-manager-interface#variable-interface) declared by the given node. This information can be used to track references to variables. * If the node is a `VariableDeclaration`, all variables declared in the declaration are returned. * If the node is a `VariableDeclarator`, all variables declared in the declarator are returned. * If the node is a `FunctionDeclaration` or `FunctionExpression`, the variable for the function name is returned, in addition to variables for the function parameters. @@ -148,30 +129,79 @@ Additionally, the `context` object has the following methods: * If the node is an `ImportDeclaration`, variables for all of its specifiers are returned. * If the node is an `ImportSpecifier`, `ImportDefaultSpecifier`, or `ImportNamespaceSpecifier`, the declared variable is returned. * Otherwise, if the node does not declare any variables, an empty array is returned. -* `getFilename()`: (**Deprecated:** Use `context.filename` instead.) Returns the filename associated with the source. -* `getPhysicalFilename()`: (**Deprecated:** Use `context.physicalFilename` instead.) When linting a file, it returns the full path of the file on disk without any code block information. When linting text, it returns the value passed to `—stdin-filename` or `` if not specified. -* `getScope()`: (**Deprecated:** Use `SourceCode#getScope(node)` instead.) Returns the [scope](./scope-manager-interface#scope-interface) of the currently-traversed node. This information can be used to track references to variables. -* `getSourceCode()`: (**Deprecated:** Use `context.sourceCode` instead.) Returns a `SourceCode` object that you can use to work with the source that was passed to ESLint (see [Accessing the Source Code](#accessing-the-source-code)). -* `markVariableAsUsed(name)`: (**Deprecated:** Use `SourceCode#markVariableAsUsed(name, node)` instead.) Marks a variable with the given name in the current scope as used. This affects the [no-unused-vars](../rules/no-unused-vars) rule. Returns `true` if a variable with the given name was found and marked as used, otherwise `false`. -* `report(descriptor)`. Reports a problem in the code (see the [dedicated section](#reporting-problems)). +* `getFilename()` - returns the filename associated with the source. +* `getPhysicalFilename()` - when linting a file, it returns the full path of the file on disk without any code block information. When linting text, it returns the value passed to `—stdin-filename` or `` if not specified. +* `getScope()` - returns the [scope](./scope-manager-interface#scope-interface) of the currently-traversed node. This information can be used to track references to variables. +* `getSourceCode()` - returns a [`SourceCode`](#contextgetsourcecode) object that you can use to work with the source that was passed to ESLint. +* `markVariableAsUsed(name)` - marks a variable with the given name in the current scope as used. This affects the [no-unused-vars](../rules/no-unused-vars) rule. Returns `true` if a variable with the given name was found and marked as used, otherwise `false`. +* `report(descriptor)` - reports a problem in the code (see the [dedicated section](#contextreport)). **Note:** Earlier versions of ESLint supported additional methods on the `context` object. Those methods were removed in the new format and should not be relied upon. -### Reporting Problems +### context.getScope() -The main method you'll use when writing custom rules is `context.report()`, which publishes a warning or error (depending on the configuration being used). This method accepts a single argument, which is an object containing the following properties: +This method returns the scope of the current node. It is a useful method for finding information about the variables in a given scope, and how they are used in other scopes. -* `message`: (`string`) The problem message. -* `node`: (optional `object`) The AST node related to the problem. If present and `loc` is not specified, then the starting location of the node is used as the location of the problem. -* `loc`: (optional `object`) Specifies the location of the problem. If both `loc` and `node` are specified, then the location is used from `loc` instead of `node`. - * `start`: An object of the start location. - * `line`: (`number`) The 1-based line number at which the problem occurred. - * `column`: (`number`) The 0-based column number at which the problem occurred. - * `end`: An object of the end location. - * `line`: (`number`) The 1-based line number at which the problem occurred. - * `column`: (`number`) The 0-based column number at which the problem occurred. -* `data`: (optional `object`) [Placeholder](#using-message-placeholders) data for `message`. -* `fix(fixer)`: (optional `function`) Applies a [fix](#applying-fixes) to resolve the problem. +#### Scope types + +The following table contains a list of AST node types and the scope type that they correspond to. For more information about the scope types, refer to the [`Scope` object documentation](./scope-manager-interface#scope-interface). + +| AST Node Type | Scope Type | +|:--------------------------|:-----------| +| `Program` | `global` | +| `FunctionDeclaration` | `function` | +| `FunctionExpression` | `function` | +| `ArrowFunctionExpression` | `function` | +| `ClassDeclaration` | `class` | +| `ClassExpression` | `class` | +| `BlockStatement` ※1 | `block` | +| `SwitchStatement` ※1 | `switch` | +| `ForStatement` ※2 | `for` | +| `ForInStatement` ※2 | `for` | +| `ForOfStatement` ※2 | `for` | +| `WithStatement` | `with` | +| `CatchClause` | `catch` | +| others | ※3 | + +**※1** Only if the configured parser provided the block-scope feature. The default parser provides the block-scope feature if `parserOptions.ecmaVersion` is not less than `6`.
+**※2** Only if the `for` statement defines the iteration variable as a block-scoped variable (E.g., `for (let i = 0;;) {}`).
+**※3** The scope of the closest ancestor node which has own scope. If the closest ancestor node has multiple scopes then it chooses the innermost scope (E.g., the `Program` node has a `global` scope and a `module` scope if `Program#sourceType` is `"module"`. The innermost scope is the `module` scope.). + +#### Scope Variables + +The `Scope#variables` property contains an array of [`Variable` objects](./scope-manager-interface#variable-interface). These are the variables declared in current scope. You can use these `Variable` objects to track references to a variable throughout the entire module. + +Inside of each `Variable`, the `Variable#references` property contains an array of [`Reference` objects](./scope-manager-interface#reference-interface). The `Reference` array contains all the locations where the variable is referenced in the module's source code. + +Also inside of each `Variable`, the `Variable#defs` property contains an array of [`Definition` objects](./scope-manager-interface#definition-interface). You can use the `Definitions` to find where the variable was defined. + +Global variables have the following additional properties: + +* `Variable#writeable` (`boolean | undefined`) ... If `true`, this global variable can be assigned arbitrary value. If `false`, this global variable is read-only. +* `Variable#eslintExplicitGlobal` (`boolean | undefined`) ... If `true`, this global variable was defined by a `/* globals */` directive comment in the source code file. +* `Variable#eslintExplicitGlobalComments` (`Comment[] | undefined`) ... The array of `/* globals */` directive comments which defined this global variable in the source code file. This property is `undefined` if there are no `/* globals */` directive comments. +* `Variable#eslintImplicitGlobalSetting` (`"readonly" | "writable" | undefined`) ... The configured value in config files. This can be different from `variable.writeable` if there are `/* globals */` directive comments. + +For examples of using `context.getScope()` to track variables, refer to the source code for the following built-in rules: + +* [no-shadow](https://github.com/eslint/eslint/blob/main/lib/rules/no-shadow.js): Calls `context.getScopes()` at the global scope and parses all child scopes to make sure a variable name is not reused at a lower scope. ([no-shadow](../rules/no-shadow) documentation) +* [no-redeclare](https://github.com/eslint/eslint/blob/main/lib/rules/no-redeclare.js): Calls `context.getScope()` at each scope to make sure that a variable is not declared twice at that scope. ([no-redeclare](../rules/no-redeclare) documentation) + +### context.report() + +The main method you'll use is `context.report()`, which publishes a warning or error (depending on the configuration being used). This method accepts a single argument, which is an object containing the following properties: + +* `message` - the problem message. +* `node` - (optional) the AST node related to the problem. If present and `loc` is not specified, then the starting location of the node is used as the location of the problem. +* `loc` - (optional) an object specifying the location of the problem. If both `loc` and `node` are specified, then the location is used from `loc` instead of `node`. + * `start` - An object of the start location. + * `line` - the 1-based line number at which the problem occurred. + * `column` - the 0-based column number at which the problem occurred. + * `end` - An object of the end location. + * `line` - the 1-based line number at which the problem occurred. + * `column` - the 0-based column number at which the problem occurred. +* `data` - (optional) [placeholder](#using-message-placeholders) data for `message`. +* `fix` - (optional) a function that applies a [fix](#applying-fixes) to resolve the problem. Note that at least one of `node` or `loc` is required. @@ -184,9 +214,9 @@ context.report({ }); ``` -The node contains all the information necessary to figure out the line and column number of the offending text as well as the source text representing the node. +The node contains all of the information necessary to figure out the line and column number of the offending text as well the source text representing the node. -#### Using Message Placeholders +### Using message placeholders You can also use placeholders in the message and provide `data`: @@ -204,20 +234,17 @@ context.report({ Note that leading and trailing whitespace is optional in message parameters. -The node contains all the information necessary to figure out the line and column number of the offending text as well as the source text representing the node. +The node contains all of the information necessary to figure out the line and column number of the offending text as well the source text representing the node. -#### `messageId`s +### `messageId`s Instead of typing out messages in both the `context.report()` call and your tests, you can use `messageId`s instead. This allows you to avoid retyping error messages. It also prevents errors reported in different sections of your rule from having out-of-date messages. -Rule file: - ```js {% raw %} -// avoid-name.js - +// in your rule module.exports = { meta: { messages: { @@ -240,28 +267,18 @@ module.exports = { }; } }; -{% endraw %} -``` - -In the file to lint: -```javascript -// someFile.js +// in the file to lint: var foo = 2; // ^ error: Avoid using variables named 'foo' -``` - -In your tests: -```javascript -// avoid-name.test.js - -var rule = require("../../../lib/rules/avoid-name"); +// In your tests: +var rule = require("../../../lib/rules/my-rule"); var RuleTester = require("eslint").RuleTester; var ruleTester = new RuleTester(); -ruleTester.run("avoid-name", rule, { +ruleTester.run("my-rule", rule, { valid: ["bar", "baz"], invalid: [ { @@ -274,9 +291,10 @@ ruleTester.run("avoid-name", rule, { } ] }); +{% endraw %} ``` -#### Applying Fixes +### Applying Fixes If you'd like ESLint to attempt to fix the problem you're reporting, you can do so by specifying the `fix` function when using `context.report()`. The `fix` function receives a single argument, a `fixer` object, that you can use to apply a fix. For example: @@ -284,28 +302,28 @@ If you'd like ESLint to attempt to fix the problem you're reporting, you can do context.report({ node: node, message: "Missing semicolon", - fix(fixer) { + fix: function(fixer) { return fixer.insertTextAfter(node, ";"); } }); ``` -Here, the `fix()` function is used to insert a semicolon after the node. Note that a fix is not immediately applied, and may not be applied at all if there are conflicts with other fixes. After applying fixes, ESLint will run all the enabled rules again on the fixed code, potentially applying more fixes. This process will repeat up to 10 times, or until no more fixable problems are found. Afterward, any remaining problems will be reported as usual. +Here, the `fix()` function is used to insert a semicolon after the node. Note that a fix is not immediately applied, and may not be applied at all if there are conflicts with other fixes. After applying fixes, ESLint will run all of the enabled rules again on the fixed code, potentially applying more fixes. This process will repeat up to 10 times, or until no more fixable problems are found. Afterwards, any remaining problems will be reported as usual. -**Important:** The `meta.fixable` property is mandatory for fixable rules. ESLint will throw an error if a rule that implements `fix` functions does not [export](#rule-structure) the `meta.fixable` property. +**Important:** The `meta.fixable` property is mandatory for fixable rules. ESLint will throw an error if a rule that implements `fix` functions does not [export](#rule-basics) the `meta.fixable` property. The `fixer` object has the following methods: -* `insertTextAfter(nodeOrToken, text)`: Insert text after the given node or token. -* `insertTextAfterRange(range, text)`: Insert text after the given range. -* `insertTextBefore(nodeOrToken, text)`: Insert text before the given node or token. -* `insertTextBeforeRange(range, text)`: Insert text before the given range. -* `remove(nodeOrToken)`: Remove the given node or token. -* `removeRange(range)`: Remove text in the given range. -* `replaceText(nodeOrToken, text)`: Replace the text in the given node or token. -* `replaceTextRange(range, text)`: Replace the text in the given range. +* `insertTextAfter(nodeOrToken, text)` - inserts text after the given node or token +* `insertTextAfterRange(range, text)` - inserts text after the given range +* `insertTextBefore(nodeOrToken, text)` - inserts text before the given node or token +* `insertTextBeforeRange(range, text)` - inserts text before the given range +* `remove(nodeOrToken)` - removes the given node or token +* `removeRange(range)` - removes text in the given range +* `replaceText(nodeOrToken, text)` - replaces the text in the given node or token +* `replaceTextRange(range, text)` - replaces the text in the given range -A `range` is a two-item array containing character indices inside the source code. The first item is the start of the range (inclusive) and the second item is the end of the range (exclusive). Every node and token has a `range` property to identify the source code range they represent. +A range is a two-item array containing character indices inside of the source code. The first item is the start of the range (inclusive) and the second item is the end of the range (exclusive). Every node and token has a `range` property to identify the source code range they represent. The above methods return a `fixing` object. The `fix()` function can return the following values: @@ -363,11 +381,11 @@ There is no way to specify which of the conflicting fixes is applied. For example, if two fixes want to modify characters 0 through 5, only one is applied. -#### Providing Suggestions +### Providing Suggestions In some cases fixes aren't appropriate to be automatically applied, for example, if a fix potentially changes functionality or if there are multiple valid ways to fix a rule depending on the implementation intent (see the best practices for [applying fixes](#applying-fixes) listed above). In these cases, there is an alternative `suggest` option on `context.report()` that allows other tools, such as editors, to expose helpers for users to manually apply a suggestion. -To provide suggestions, use the `suggest` key in the report argument with an array of suggestion objects. The suggestion objects represent individual suggestions that could be applied and require either a `desc` key string that describes what applying the suggestion would do or a `messageId` key (see [below](#suggestion-messageids)), and a `fix` key that is a function defining the suggestion result. This `fix` function follows the same API as regular fixes (described above in [applying fixes](#applying-fixes)). +In order to provide suggestions, use the `suggest` key in the report argument with an array of suggestion objects. The suggestion objects represent individual suggestions that could be applied and require either a `desc` key string that describes what applying the suggestion would do or a `messageId` key (see [below](#suggestion-messageids)), and a `fix` key that is a function defining the suggestion result. This `fix` function follows the same API as regular fixes (described above in [applying fixes](#applying-fixes)). ```js {% raw %} @@ -393,9 +411,9 @@ context.report({ {% endraw %} ``` -**Important:** The `meta.hasSuggestions` property is mandatory for rules that provide suggestions. ESLint will throw an error if a rule attempts to produce a suggestion but does not [export](#rule-structure) this property. +**Important:** The `meta.hasSuggestions` property is mandatory for rules that provide suggestions. ESLint will throw an error if a rule attempts to produce a suggestion but does not [export](#rule-basics) this property. -**Note:** Suggestions are applied as stand-alone changes, without triggering multipass fixes. Each suggestion should focus on a singular change in the code and should not try to conform to user-defined styles. For example, if a suggestion is adding a new statement into the codebase, it should not try to match correct indentation or conform to user preferences on the presence/absence of semicolons. All of those things can be corrected by multipass autofix when the user triggers it. +Note: Suggestions will be applied as a stand-alone change, without triggering multipass fixes. Each suggestion should focus on a singular change in the code and should not try to conform to user defined styles. For example, if a suggestion is adding a new statement into the codebase, it should not try to match correct indentation, or conform to user preferences on presence/absence of semicolons. All of those things can be corrected by multipass autofix when the user triggers it. Best practices for suggestions: @@ -406,7 +424,7 @@ Suggestions are intended to provide fixes. ESLint will automatically remove the #### Suggestion `messageId`s -Instead of using a `desc` key for suggestions a `messageId` can be used instead. This works the same way as `messageId`s for the overall error (see [messageIds](#messageids)). Here is an example of how to use a suggestion `messageId` in a rule: +Instead of using a `desc` key for suggestions a `messageId` can be used instead. This works the same way as `messageId`s for the overall error (see [messageIds](#messageids)). Here is an example of how to use it in a rule: ```js {% raw %} @@ -427,13 +445,13 @@ module.exports = { data: { character }, suggest: [ { - messageId: "removeEscape", // suggestion messageId + messageId: "removeEscape", fix: function(fixer) { return fixer.removeRange(range); } }, { - messageId: "escapeBackslash", // suggestion messageId + messageId: "escapeBackslash", fix: function(fixer) { return fixer.insertTextBeforeRange(range, "\\"); } @@ -445,7 +463,7 @@ module.exports = { {% endraw %} ``` -#### Placeholders in Suggestion Messages +#### Placeholders in suggestion messages You can also use placeholders in the suggestion message. This works the same way as placeholders for the overall error (see [using message placeholders](#using-message-placeholders)). @@ -482,9 +500,9 @@ module.exports = { {% endraw %} ``` -### Accessing Options Passed to a Rule +### context.options -Some rules require options in order to function correctly. These options appear in configuration (`.eslintrc`, command line interface, or comments). For example: +Some rules require options in order to function correctly. These options appear in configuration (`.eslintrc`, command line, or in comments). For example: ```json { @@ -508,123 +526,95 @@ Since `context.options` is just an array, you can use it to determine how many o When using options, make sure that your rule has some logical defaults in case the options are not provided. -### Accessing the Source Code +### context.getSourceCode() -The `SourceCode` object is the main object for getting more information about the source code being linted. You can retrieve the `SourceCode` object at any time by using the `context.sourceCode` property: +The `SourceCode` object is the main object for getting more information about the source code being linted. You can retrieve the `SourceCode` object at any time by using the `getSourceCode()` method: ```js module.exports = { create: function(context) { - var sourceCode = context.sourceCode; + var sourceCode = context.getSourceCode(); // ... } }; ``` -**Deprecated:** The `context.getSourceCode()` method is deprecated; make sure to use `context.sourceCode` property instead. - Once you have an instance of `SourceCode`, you can use the following methods on it to work with the code: -* `getText(node)`: Returns the source code for the given node. Omit `node` to get the whole source (see the [dedicated section](#accessing-the-source-text)). -* `getAllComments()`: Returns an array of all comments in the source (see the [dedicated section](#accessing-comments)). -* `getCommentsBefore(nodeOrToken)`: Returns an array of comment tokens that occur directly before the given node or token (see the [dedicated section](#accessing-comments)). -* `getCommentsAfter(nodeOrToken)`: Returns an array of comment tokens that occur directly after the given node or token (see the [dedicated section](#accessing-comments)). -* `getCommentsInside(node)`: Returns an array of all comment tokens inside a given node (see the [dedicated section](#accessing-comments)). -* `isSpaceBetween(nodeOrToken, nodeOrToken)`: Returns true if there is a whitespace character between the two tokens or, if given a node, the last token of the first node and the first token of the second node. -* `getFirstToken(node, skipOptions)`: Returns the first token representing the given node. -* `getFirstTokens(node, countOptions)`: Returns the first `count` tokens representing the given node. -* `getLastToken(node, skipOptions)`: Returns the last token representing the given node. -* `getLastTokens(node, countOptions)`: Returns the last `count` tokens representing the given node. -* `getTokenAfter(nodeOrToken, skipOptions)`: Returns the first token after the given node or token. -* `getTokensAfter(nodeOrToken, countOptions)`: Returns `count` tokens after the given node or token. -* `getTokenBefore(nodeOrToken, skipOptions)`: Returns the first token before the given node or token. -* `getTokensBefore(nodeOrToken, countOptions)`: Returns `count` tokens before the given node or token. -* `getFirstTokenBetween(nodeOrToken1, nodeOrToken2, skipOptions)`: Returns the first token between two nodes or tokens. -* `getFirstTokensBetween(nodeOrToken1, nodeOrToken2, countOptions)`: Returns the first `count` tokens between two nodes or tokens. -* `getLastTokenBetween(nodeOrToken1, nodeOrToken2, skipOptions)`: Returns the last token between two nodes or tokens. -* `getLastTokensBetween(nodeOrToken1, nodeOrToken2, countOptions)`: Returns the last `count` tokens between two nodes or tokens. -* `getTokens(node)`: Returns all tokens for the given node. -* `getTokensBetween(nodeOrToken1, nodeOrToken2)`: Returns all tokens between two nodes. -* `getTokenByRangeStart(index, rangeOptions)`: Returns the token whose range starts at the given index in the source. -* `getNodeByRangeIndex(index)`: Returns the deepest node in the AST containing the given source index. -* `getLocFromIndex(index)`: Returns an object with `line` and `column` properties, corresponding to the location of the given source index. `line` is 1-based and `column` is 0-based. -* `getIndexFromLoc(loc)`: Returns the index of a given location in the source code, where `loc` is an object with a 1-based `line` key and a 0-based `column` key. -* `commentsExistBetween(nodeOrToken1, nodeOrToken2)`: Returns `true` if comments exist between two nodes. +* `getText(node)` - returns the source code for the given node. Omit `node` to get the whole source. +* `getAllComments()` - returns an array of all comments in the source. +* `getCommentsBefore(nodeOrToken)` - returns an array of comment tokens that occur directly before the given node or token. +* `getCommentsAfter(nodeOrToken)` - returns an array of comment tokens that occur directly after the given node or token. +* `getCommentsInside(node)` - returns an array of all comment tokens inside a given node. +* `isSpaceBetween(nodeOrToken, nodeOrToken)` - returns true if there is a whitespace character between the two tokens or, if given a node, the last token of the first node and the first token of the second node. +* `getFirstToken(node, skipOptions)` - returns the first token representing the given node. +* `getFirstTokens(node, countOptions)` - returns the first `count` tokens representing the given node. +* `getLastToken(node, skipOptions)` - returns the last token representing the given node. +* `getLastTokens(node, countOptions)` - returns the last `count` tokens representing the given node. +* `getTokenAfter(nodeOrToken, skipOptions)` - returns the first token after the given node or token. +* `getTokensAfter(nodeOrToken, countOptions)` - returns `count` tokens after the given node or token. +* `getTokenBefore(nodeOrToken, skipOptions)` - returns the first token before the given node or token. +* `getTokensBefore(nodeOrToken, countOptions)` - returns `count` tokens before the given node or token. +* `getFirstTokenBetween(nodeOrToken1, nodeOrToken2, skipOptions)` - returns the first token between two nodes or tokens. +* `getFirstTokensBetween(nodeOrToken1, nodeOrToken2, countOptions)` - returns the first `count` tokens between two nodes or tokens. +* `getLastTokenBetween(nodeOrToken1, nodeOrToken2, skipOptions)` - returns the last token between two nodes or tokens. +* `getLastTokensBetween(nodeOrToken1, nodeOrToken2, countOptions)` - returns the last `count` tokens between two nodes or tokens. +* `getTokens(node)` - returns all tokens for the given node. +* `getTokensBetween(nodeOrToken1, nodeOrToken2)` - returns all tokens between two nodes. +* `getTokenByRangeStart(index, rangeOptions)` - returns the token whose range starts at the given index in the source. +* `getNodeByRangeIndex(index)` - returns the deepest node in the AST containing the given source index. +* `getLocFromIndex(index)` - returns an object with `line` and `column` properties, corresponding to the location of the given source index. `line` is 1-based and `column` is 0-based. +* `getIndexFromLoc(loc)` - returns the index of a given location in the source code, where `loc` is an object with a 1-based `line` key and a 0-based `column` key. +* `commentsExistBetween(nodeOrToken1, nodeOrToken2)` - returns `true` if comments exist between two nodes. `skipOptions` is an object which has 3 properties; `skip`, `includeComments`, and `filter`. Default is `{skip: 0, includeComments: false, filter: null}`. -* `skip`: (`number`) Positive integer, the number of skipping tokens. If `filter` option is given at the same time, it doesn't count filtered tokens as skipped. -* `includeComments`: (`boolean`) The flag to include comment tokens into the result. -* `filter(token)`: Function which gets a token as the first argument. If the function returns `false` then the result excludes the token. +* `skip` is a positive integer, the number of skipping tokens. If `filter` option is given at the same time, it doesn't count filtered tokens as skipped. +* `includeComments` is a boolean value, the flag to include comment tokens into the result. +* `filter` is a function which gets a token as the first argument, if the function returns `false` then the result excludes the token. `countOptions` is an object which has 3 properties; `count`, `includeComments`, and `filter`. Default is `{count: 0, includeComments: false, filter: null}`. -* `count`: (`number`) Positive integer, the maximum number of returning tokens. -* `includeComments`: (`boolean`) The flag to include comment tokens into the result. -* `filter(token)`: Function which gets a token as the first argument, if the function returns `false` then the result excludes the token. +* `count` is a positive integer, the maximum number of returning tokens. +* `includeComments` is a boolean value, the flag to include comment tokens into the result. +* `filter` is a function which gets a token as the first argument, if the function returns `false` then the result excludes the token. -`rangeOptions` is an object that has 1 property, `includeComments`. Default is `{includeComments: false}`. +`rangeOptions` is an object which has 1 property: `includeComments`. -* `includeComments`: (`boolean`) The flag to include comment tokens into the result. +* `includeComments` is a boolean value, the flag to include comment tokens into the result. There are also some properties you can access: -* `hasBOM`: (`boolean`) The flag to indicate whether the source code has Unicode BOM. -* `text`: (`string`) The full text of the code being linted. Unicode BOM has been stripped from this text. -* `ast`: (`object`) `Program` node of the AST for the code being linted. -* `scopeManager`: [ScopeManager](./scope-manager-interface#scopemanager-interface) object of the code. -* `visitorKeys`: (`object`) Visitor keys to traverse this AST. -* `lines`: (`array`) Array of lines, split according to the specification's definition of line breaks. +* `hasBOM` - the flag to indicate whether or not the source code has Unicode BOM. +* `text` - the full text of the code being linted. Unicode BOM has been stripped from this text. +* `ast` - the `Program` node of the AST for the code being linted. +* `scopeManager` - the [ScopeManager](./scope-manager-interface#scopemanager-interface) object of the code. +* `visitorKeys` - the visitor keys to traverse this AST. +* `lines` - an array of lines, split according to the specification's definition of line breaks. You should use a `SourceCode` object whenever you need to get more information about the code being linted. -#### Accessing the Source Text +#### Deprecated -If your rule needs to get the actual JavaScript source to work with, then use the `sourceCode.getText()` method. This method works as follows: +Please note that the following methods have been deprecated and will be removed in a future version of ESLint: -```js - -// get all source -var source = sourceCode.getText(); - -// get source for just this AST node -var nodeSource = sourceCode.getText(node); - -// get source for AST node plus previous two characters -var nodeSourceWithPrev = sourceCode.getText(node, 2); - -// get source for AST node plus following two characters -var nodeSourceWithFollowing = sourceCode.getText(node, 0, 2); -``` - -In this way, you can look for patterns in the JavaScript text itself when the AST isn't providing the appropriate data (such as the location of commas, semicolons, parentheses, etc.). - -#### Accessing Comments - -While comments are not technically part of the AST, ESLint provides the `sourceCode.getAllComments()`, `sourceCode.getCommentsBefore()`, `sourceCode.getCommentsAfter()`, and `sourceCode.getCommentsInside()` to access them. - -`sourceCode.getCommentsBefore()`, `sourceCode.getCommentsAfter()`, and `sourceCode.getCommentsInside()` are useful for rules that need to check comments in relation to a given node or token. - -Keep in mind that the results of these methods are calculated on demand. - -You can also access comments through many of `sourceCode`'s methods using the `includeComments` option. +* `getComments()` - replaced by `getCommentsBefore()`, `getCommentsAfter()`, and `getCommentsInside()` +* `getTokenOrCommentBefore()` - replaced by `getTokenBefore()` with the `{ includeComments: true }` option +* `getTokenOrCommentAfter()` - replaced by `getTokenAfter()` with the `{ includeComments: true }` option +* `isSpaceBetweenTokens()` - replaced by `isSpaceBetween()` +* `getJSDocComment()` ### Options Schemas -Rules may export a `schema` property, which is a [JSON Schema](https://json-schema.org/) format description of a rule's options which will be used by ESLint to validate configuration options and prevent invalid or unexpected inputs before they are passed to the rule in `context.options`. - -There are two formats for a rule's exported `schema`: +Rules may export a `schema` property, which is a [JSON schema](https://json-schema.org/) format description of a rule's options which will be used by ESLint to validate configuration options and prevent invalid or unexpected inputs before they are passed to the rule in `context.options`. -1. A full JSON Schema object describing all possible options the rule accepts. -2. An array of JSON Schema objects for each optional positional argument. +There are two formats for a rule's exported `schema`. The first is a full JSON Schema object describing all possible options the rule accepts, including the rule's error level as the first argument and any optional arguments thereafter. -In both cases, these should exclude the [severity](../use/configure/rules#rule-severities), as ESLint automatically validates this first. - -For example, the `yoda` rule accepts a primary mode argument of `"always"` or `"never"`, as well as an extra options object with an optional property `exceptRange`: +However, to simplify schema creation, rules may also export an array of schemas for each optional positional argument, and ESLint will automatically validate the required error level first. For example, the `yoda` rule accepts a primary mode argument, as well as an extra options object with named properties. ```js -// "yoda": ["error", "never", { "exceptRange": true }] +// "yoda": [2, "never", { "exceptRange": true }] module.exports = { meta: { schema: [ @@ -645,108 +635,61 @@ module.exports = { }; ``` -**Note:** If your rule schema uses JSON schema [`$ref`](https://json-schema.org/understanding-json-schema/structuring.html#ref) properties, you must use the full JSON Schema object rather than the array of positional property schemas. This is because ESLint transforms the array shorthand into a single schema without updating references that makes them incorrect (they are ignored). - -To learn more about JSON Schema, we recommend looking at some examples on the [JSON Schema website](https://json-schema.org/learn/), or reading the free [Understanding JSON Schema](https://json-schema.org/understanding-json-schema/) ebook. - -### Accessing Shebangs - -[Shebangs (#!)](https://en.wikipedia.org/wiki/Shebang_(Unix)) are represented by the unique tokens of type `"Shebang"`. They are treated as comments and can be accessed by the methods outlined in the [Accessing Comments](#accessing-comments) section, such as `sourceCode.getAllComments()`. - -### Accessing Variable Scopes +In the preceding example, the error level is assumed to be the first argument. It is followed by the first optional argument, a string which may be either `"always"` or `"never"`. The final optional argument is an object, which may have a Boolean property named `exceptRange`. -The `SourceCode#getScope(node)` method returns the scope of the given node. It is a useful method for finding information about the variables in a given scope and how they are used in other scopes. +To learn more about JSON Schema, we recommend looking at some examples in [website](https://json-schema.org/learn/) to start, and also reading [Understanding JSON Schema](https://json-schema.org/understanding-json-schema/) (a free ebook). -**Deprecated:** The `context.getScope()` is deprecated; make sure to use `SourceCode#getScope(node)` instead. +**Note:** Currently you need to use full JSON Schema object rather than array in case your schema has references ($ref), because in case of array format ESLint transforms this array into a single schema without updating references that makes them incorrect (they are ignored). -#### Scope types - -The following table contains a list of AST node types and the scope type that they correspond to. For more information about the scope types, refer to the [`Scope` object documentation](./scope-manager-interface#scope-interface). - -| AST Node Type | Scope Type | -|:--------------------------|:-----------| -| `Program` | `global` | -| `FunctionDeclaration` | `function` | -| `FunctionExpression` | `function` | -| `ArrowFunctionExpression` | `function` | -| `ClassDeclaration` | `class` | -| `ClassExpression` | `class` | -| `BlockStatement` ※1 | `block` | -| `SwitchStatement` ※1 | `switch` | -| `ForStatement` ※2 | `for` | -| `ForInStatement` ※2 | `for` | -| `ForOfStatement` ※2 | `for` | -| `WithStatement` | `with` | -| `CatchClause` | `catch` | -| others | ※3 | +### Getting the Source -**※1** Only if the configured parser provided the block-scope feature. The default parser provides the block-scope feature if `parserOptions.ecmaVersion` is not less than `6`.
-**※2** Only if the `for` statement defines the iteration variable as a block-scoped variable (E.g., `for (let i = 0;;) {}`).
-**※3** The scope of the closest ancestor node which has own scope. If the closest ancestor node has multiple scopes then it chooses the innermost scope (E.g., the `Program` node has a `global` scope and a `module` scope if `Program#sourceType` is `"module"`. The innermost scope is the `module` scope.). +If your rule needs to get the actual JavaScript source to work with, then use the `sourceCode.getText()` method. This method works as follows: -#### Scope Variables +```js -The `Scope#variables` property contains an array of [`Variable` objects](./scope-manager-interface#variable-interface). These are the variables declared in current scope. You can use these `Variable` objects to track references to a variable throughout the entire module. +// get all source +var source = sourceCode.getText(); -Inside of each `Variable`, the `Variable#references` property contains an array of [`Reference` objects](./scope-manager-interface#reference-interface). The `Reference` array contains all the locations where the variable is referenced in the module's source code. +// get source for just this AST node +var nodeSource = sourceCode.getText(node); -Also inside of each `Variable`, the `Variable#defs` property contains an array of [`Definition` objects](./scope-manager-interface#definition-interface). You can use the `Definitions` to find where the variable was defined. +// get source for AST node plus previous two characters +var nodeSourceWithPrev = sourceCode.getText(node, 2); -Global variables have the following additional properties: +// get source for AST node plus following two characters +var nodeSourceWithFollowing = sourceCode.getText(node, 0, 2); +``` -* `Variable#writeable` (`boolean | undefined`) ... If `true`, this global variable can be assigned arbitrary value. If `false`, this global variable is read-only. -* `Variable#eslintExplicitGlobal` (`boolean | undefined`) ... If `true`, this global variable was defined by a `/* globals */` directive comment in the source code file. -* `Variable#eslintExplicitGlobalComments` (`Comment[] | undefined`) ... The array of `/* globals */` directive comments which defined this global variable in the source code file. This property is `undefined` if there are no `/* globals */` directive comments. -* `Variable#eslintImplicitGlobalSetting` (`"readonly" | "writable" | undefined`) ... The configured value in config files. This can be different from `variable.writeable` if there are `/* globals */` directive comments. +In this way, you can look for patterns in the JavaScript text itself when the AST isn't providing the appropriate data (such as location of commas, semicolons, parentheses, etc.). -For examples of using `SourceCode#getScope()` to track variables, refer to the source code for the following built-in rules: +### Accessing Comments -* [no-shadow](https://github.com/eslint/eslint/blob/main/lib/rules/no-shadow.js): Calls `sourceCode.getScope()` at the `Program` node and inspects all child scopes to make sure a variable name is not reused at a lower scope. ([no-shadow](../rules/no-shadow) documentation) -* [no-redeclare](https://github.com/eslint/eslint/blob/main/lib/rules/no-redeclare.js): Calls `sourceCode.getScope()` at each scope to make sure that a variable is not declared twice in the same scope. ([no-redeclare](../rules/no-redeclare) documentation) +While comments are not technically part of the AST, ESLint provides a few ways for rules to access them: -### Marking Variables as Used +#### sourceCode.getAllComments() -**Deprecated:** The `context.markVariableAsUsed()` method is deprecated in favor of `sourceCode.markVariableAsUsed()`. +This method returns an array of all the comments found in the program. This is useful for rules that need to check all comments regardless of location. -Certain ESLint rules, such as [`no-unused-vars`](../rules/no-unused-vars), check to see if a variable has been used. ESLint itself only knows about the standard rules of variable access and so custom ways of accessing variables may not register as "used". +#### sourceCode.getCommentsBefore(), sourceCode.getCommentsAfter(), and sourceCode.getCommentsInside() -To help with this, you can use the `sourceCode.markVariableAsUsed()` method. This method takes two arguments: the name of the variable to mark as used and an option reference node indicating the scope in which you are working. Here's an example: +These methods return an array of comments that appear directly before, directly after, and inside nodes, respectively. They are useful for rules that need to check comments in relation to a given node or token. -```js -module.exports = { - create: function(context) { - var sourceCode = context.sourceCode; +Keep in mind that the results of this method are calculated on demand. - return { - ReturnStatement(node) { +#### Token traversal methods - // look in the scope of the function for myCustomVar and mark as used - sourceCode.markVariableAsUsed("myCustomVar", node); +Finally, comments can be accessed through many of `sourceCode`'s methods using the `includeComments` option. - // or: look in the global scope for myCustomVar and mark as used - sourceCode.markVariableAsUsed("myCustomVar"); - } - } - // ... - } -}; -``` +### Accessing Shebangs -Here, the `myCustomVar` variable is marked as used relative to a `ReturnStatement` node, which means ESLint will start searching from the scope closest to that node. If you omit the second argument, then the top-level scope is used. (For ESM files, the top-level scope is the module scope; for CommonJS files, the top-level scope is the first function scope.) +Shebangs are represented by tokens of type `"Shebang"`. They are treated as comments and can be accessed by the methods outlined above. ### Accessing Code Paths -ESLint analyzes code paths while traversing AST. You can access code path objects with five events related to code paths. For more information, refer to [Code Path Analysis](code-path-analysis). - -### Deprecated `SourceCode` Methods +ESLint analyzes code paths while traversing AST. +You can access that code path objects with five events related to code paths. -Please note that the following `SourceCode` methods have been deprecated and will be removed in a future version of ESLint: - -* `getComments()`: Replaced by `SourceCode#getCommentsBefore()`, `SourceCode#getCommentsAfter()`, and `SourceCode#getCommentsInside()`. -* `getTokenOrCommentBefore()`: Replaced by `SourceCode#getTokenBefore()` with the `{ includeComments: true }` option. -* `getTokenOrCommentAfter()`: Replaced by `SourceCode#getTokenAfter()` with the `{ includeComments: true }` option. -* `isSpaceBetweenTokens()`: Replaced by `SourceCode#isSpaceBetween()` -* `getJSDocComment()` +[details here](code-path-analysis) ## Rule Unit Tests @@ -754,11 +697,11 @@ ESLint provides the [`RuleTester`](../integrate/nodejs-api#ruletester) utility t ## Rule Naming Conventions -While you can give a custom rule any name you'd like, the core rules have naming conventions. It could be clearer to apply these same naming conventions to your custom rule. To learn more, refer to the [Core Rule Naming Conventions](../contribute/core-rules#rule-naming-conventions) documentation. +While you can give a custom rule any name you'd like, the core rules have naming conventions that it could be clearer to apply to your custom rule. To learn more, refer to the [Core Rule Naming Conventions](../contribute/core-rules#rule-naming-conventions) documentation. ## Runtime Rules -The thing that makes ESLint different from other linters is the ability to define custom rules at runtime. This is perfect for rules that are specific to your project or company and wouldn't make sense for ESLint to ship with or be included in a plugin. Just write your rules and include them at runtime. +The thing that makes ESLint different from other linters is the ability to define custom rules at runtime. This is perfect for rules that are specific to your project or company and wouldn't make sense for ESLint to ship with. With runtime rules, you don't have to wait for the next version of ESLint or be disappointed that your rule isn't general enough to apply to the larger JavaScript community, just write your rules and include them at runtime. Runtime rules are written in the same format as all other rules. Create your rule as you would any other and then follow these steps: diff --git a/docs/src/extend/plugins.md b/docs/src/extend/plugins.md index 70bc3ee7c74..f180c034faa 100644 --- a/docs/src/extend/plugins.md +++ b/docs/src/extend/plugins.md @@ -18,34 +18,6 @@ Each plugin is an npm module with a name in the format of `eslint-plugin-). ### Linter#verify diff --git a/docs/src/maintain/manage-issues.md b/docs/src/maintain/manage-issues.md index 803451b4c63..6cfdbc93b19 100644 --- a/docs/src/maintain/manage-issues.md +++ b/docs/src/maintain/manage-issues.md @@ -30,7 +30,7 @@ The first goal when evaluating an issue is to determine which category the issue ## Triaging Process -All of ESLint's issues, across all GitHub repositories, are managed on our [Triage Project](https://github.com/orgs/eslint/projects/3). Please use the Triage project instead of the issues list when reviewing issues to determine what to work on. The Triage project has several columns: +All of ESLint's issues, across all GitHub repositories, are managed on our [Triage Project](https://github.com/orgs/eslint/projects/2). Please use the Triage project instead of the issues list when reviewing issues to determine what to work on. The Triage project has several columns: * **Needs Triage**: Issues that have not yet been reviewed by anyone * **Triaging**: Issues that someone has reviewed but has not been able to fully triage yet @@ -41,7 +41,7 @@ All of ESLint's issues, across all GitHub repositories, are managed on our [Tria * **RFC Opened**: An RFC is opened to address these issues * **Blocked**: The issue can't move forward due to some dependency * **Ready to Implement**: These issues have all the details necessary to start implementation -* **Implementing**: There is an open pull request for each of these issues +* **PR Opened**: There is an open pull request for each of these issues * **Completed**: The issue has been closed (either via pull request merge or by the team manually closing the issue) We make every attempt to automate movement between as many columns as we can, but sometimes moving issues needs to be done manually. @@ -64,7 +64,7 @@ The steps for triaging an issue are: * If the issue is actually a question (rather than something the dev team needs to change), please [convert it to a discussion](https://docs.github.com/en/free-pro-team@latest/discussions/managing-discussions-for-your-community/moderating-discussions#converting-an-issue-to-a-discussion). You can continue the conversation as a discussion. * If the issue is reporting a bug, try to reproduce the issue following the instructions in the issue. If you can reproduce the bug, please add the "repro:yes" label. (The bot will automatically remove the "repro:needed" label.) If you can't reproduce the bug, ask the author for more information about their environment or to clarify reproduction steps. * If the issue is reporting something that works as intended, please add the "works as intended" label and close the issue. - * Please add labels describing the part of ESLint affected: + * For all issues, please add labels describing the part of ESLint affected: * **3rd party plugin**: Related to third-party functionality (plugins, parsers, rules, etc.) * **build**: Related to commands run during a build (testing, linting, release scripts, etc.) * **cli**: Related to command line input or output, or to `CLIEngine` @@ -72,16 +72,6 @@ The steps for triaging an issue are: * **documentation**: Related to content on eslint.org * **infrastructure**: Related to resources needed for builds or deployment (VMs, CI tools, bots, etc.) * **rule**: Related to core rules - * Please assign an initial priority based on the importance of the issue. If you're not sure, use your best judgment. We can always change the priority later. - * **P1**: Urgent and important, we need to address this immediately. - * **P2**: Important but not urgent. Should be handled by a TSC member or reviewer. - * **P3**: Nice to have but not important. Can be handled by any team member. - * **P4**: A good idea that we'd like to have but may take a while for the team to get to it. - * **P5**: A good idea that the core team can't commit to. Will likely need to be done by an outside contributor. - * Please assign an initial impact assessement (make your best guess): - * **Low**: Doesn't affect many users. - * **Medium**: Affects most users or has a noticeable effect on user experience. - * **High**: Affects a lot of users, is a breaking change, or otherwise will be very noticeable to users. * If you can't properly triage the issue, move the issue back to the "Needs Triage" column in the Triage project so someone else can triage it. * If you have triaged the issue, move the issue to the "Ready for Dev Team" column in the Triage project. @@ -130,8 +120,8 @@ Consensus is reached on issues when there are at least three team members who be If consensus cannot be reached on an issue, or an issue's progress has been stalled and it's not clear if the issue should be closed, then you can refer the issue to the TSC for resolution. To do so, add the "tsc agenda" label to the issue and add a comment including the following information: -1. A one-paragraph summary of the discussion to this point. This should begin with "TSC Summary:". -2. The question you would like the TSC to answer. This should begin with "TSC Question:". +1. A one-paragraph summary of the discussion to this point. +2. The question you would like the TSC to answer. The issue will be discussed at the next TSC meeting and the resolution will be posted back to the issue. diff --git a/docs/src/rules/callback-return.md b/docs/src/rules/callback-return.md index 92ec02628f3..d3d621814a3 100644 --- a/docs/src/rules/callback-return.md +++ b/docs/src/rules/callback-return.md @@ -9,7 +9,7 @@ further_reading: --- -This rule was **deprecated** in ESLint v7.0.0. Please use the corresponding rule in [`eslint-plugin-n`](https://github.com/eslint-community/eslint-plugin-n). +This rule was **deprecated** in ESLint v7.0.0. Please use the corresponding rule in [`eslint-plugin-node`](https://github.com/mysticatea/eslint-plugin-node). The callback pattern is at the heart of most I/O and event-driven programming in JavaScript. diff --git a/docs/src/rules/global-require.md b/docs/src/rules/global-require.md index e960468b380..4a2d20a75d7 100644 --- a/docs/src/rules/global-require.md +++ b/docs/src/rules/global-require.md @@ -4,7 +4,7 @@ rule_type: suggestion --- -This rule was **deprecated** in ESLint v7.0.0. Please use the corresponding rule in [`eslint-plugin-n`](https://github.com/eslint-community/eslint-plugin-n). +This rule was **deprecated** in ESLint v7.0.0. Please use the corresponding rule in [`eslint-plugin-node`](https://github.com/mysticatea/eslint-plugin-node). In Node.js, module dependencies are included using the `require()` function, such as: diff --git a/docs/src/rules/handle-callback-err.md b/docs/src/rules/handle-callback-err.md index 3f66ad2031e..fddce708b46 100644 --- a/docs/src/rules/handle-callback-err.md +++ b/docs/src/rules/handle-callback-err.md @@ -7,7 +7,7 @@ further_reading: --- -This rule was **deprecated** in ESLint v7.0.0. Please use the corresponding rule in [`eslint-plugin-n`](https://github.com/eslint-community/eslint-plugin-n). +This rule was **deprecated** in ESLint v7.0.0. Please use the corresponding rule in [`eslint-plugin-node`](https://github.com/mysticatea/eslint-plugin-node). In Node.js, a common pattern for dealing with asynchronous behavior is called the callback pattern. This pattern expects an `Error` object or `null` as the first argument of the callback. diff --git a/docs/src/rules/id-match.md b/docs/src/rules/id-match.md index 08d5ff3ba9c..468078d2d54 100644 --- a/docs/src/rules/id-match.md +++ b/docs/src/rules/id-match.md @@ -91,10 +91,10 @@ This rule has an object option: * `"properties": false` (default) does not check object properties * `"properties": true` requires object literal properties and member expression assignment properties to match the specified regular expression -* `"classFields": false` (default) does not check class field names +* `"classFields": false` (default) does not class field names * `"classFields": true` requires class field names to match the specified regular expression * `"onlyDeclarations": false` (default) requires all variable names to match the specified regular expression -* `"onlyDeclarations": true` requires only `var`, `const`, `let`, `function`, and `class` declarations to match the specified regular expression +* `"onlyDeclarations": true` requires only `var`, `function`, and `class` declarations to match the specified regular expression * `"ignoreDestructuring": false` (default) enforces `id-match` for destructured identifiers * `"ignoreDestructuring": true` does not check destructured identifiers diff --git a/docs/src/rules/no-buffer-constructor.md b/docs/src/rules/no-buffer-constructor.md index 97ea1918d0b..59b9dd8772d 100644 --- a/docs/src/rules/no-buffer-constructor.md +++ b/docs/src/rules/no-buffer-constructor.md @@ -8,7 +8,7 @@ further_reading: --- -This rule was **deprecated** in ESLint v7.0.0. Please use the corresponding rule in [`eslint-plugin-n`](https://github.com/eslint-community/eslint-plugin-n). +This rule was **deprecated** in ESLint v7.0.0. Please use the corresponding rule in [`eslint-plugin-node`](https://github.com/mysticatea/eslint-plugin-node). In Node.js, the behavior of the `Buffer` constructor is different depending on the type of its argument. Passing an argument from user input to `Buffer()` without validating its type can lead to security vulnerabilities such as remote memory disclosure and denial of service. As a result, the `Buffer` constructor has been deprecated and should not be used. Use the producer methods `Buffer.from`, `Buffer.alloc`, and `Buffer.allocUnsafe` instead. diff --git a/docs/src/rules/no-div-regex.md b/docs/src/rules/no-div-regex.md index cb30420e700..ccc7287dcbe 100644 --- a/docs/src/rules/no-div-regex.md +++ b/docs/src/rules/no-div-regex.md @@ -8,7 +8,7 @@ related_rules: -Characters `/=` at the beginning of a regular expression literal can be confused with a division assignment operator. +Require regex literals to escape division operators. ```js function bar() { return /=foo/; } @@ -16,7 +16,7 @@ function bar() { return /=foo/; } ## Rule Details -This rule forbids equal signs (`=`) after the slash (`/`) at the beginning of a regular expression literal, because the characters `/=` can be confused with a division assignment operator. +This is used to disambiguate the division operator to not confuse users. Examples of **incorrect** code for this rule: diff --git a/docs/src/rules/no-mixed-requires.md b/docs/src/rules/no-mixed-requires.md index f747ebd6362..3dcf6384fd4 100644 --- a/docs/src/rules/no-mixed-requires.md +++ b/docs/src/rules/no-mixed-requires.md @@ -4,7 +4,7 @@ rule_type: suggestion --- -This rule was **deprecated** in ESLint v7.0.0. Please use the corresponding rule in [`eslint-plugin-n`](https://github.com/eslint-community/eslint-plugin-n). +This rule was **deprecated** in ESLint v7.0.0. Please use the corresponding rule in [`eslint-plugin-node`](https://github.com/mysticatea/eslint-plugin-node). In the Node.js community it is often customary to separate initializations with calls to `require` modules from other variable declarations, sometimes also grouping them by the type of module. This rule helps you enforce this convention. diff --git a/docs/src/rules/no-new-require.md b/docs/src/rules/no-new-require.md index 494d4881da2..1aa663e6669 100644 --- a/docs/src/rules/no-new-require.md +++ b/docs/src/rules/no-new-require.md @@ -4,7 +4,7 @@ rule_type: suggestion --- -This rule was **deprecated** in ESLint v7.0.0. Please use the corresponding rule in [`eslint-plugin-n`](https://github.com/eslint-community/eslint-plugin-n). +This rule was **deprecated** in ESLint v7.0.0. Please use the corresponding rule in [`eslint-plugin-node`](https://github.com/mysticatea/eslint-plugin-node). The `require` function is used to include modules that exist in separate files, such as: diff --git a/docs/src/rules/no-new.md b/docs/src/rules/no-new.md index c8cea29cb0f..9eeda70095a 100644 --- a/docs/src/rules/no-new.md +++ b/docs/src/rules/no-new.md @@ -43,7 +43,7 @@ Examples of **correct** code for this rule: var thing = new Thing(); -Foo(); +Thing(); ``` ::: diff --git a/docs/src/rules/no-path-concat.md b/docs/src/rules/no-path-concat.md index 1042f317920..840b80c3520 100644 --- a/docs/src/rules/no-path-concat.md +++ b/docs/src/rules/no-path-concat.md @@ -4,7 +4,7 @@ rule_type: suggestion --- -This rule was **deprecated** in ESLint v7.0.0. Please use the corresponding rule in [`eslint-plugin-n`](https://github.com/eslint-community/eslint-plugin-n). +This rule was **deprecated** in ESLint v7.0.0. Please use the corresponding rule in [`eslint-plugin-node`](https://github.com/mysticatea/eslint-plugin-node). In Node.js, the `__dirname` and `__filename` global variables contain the directory path and the file path of the currently executing script file, respectively. Sometimes, developers try to use these variables to create paths to other files, such as: diff --git a/docs/src/rules/no-process-env.md b/docs/src/rules/no-process-env.md index 99cd1f41a0e..2130a89443f 100644 --- a/docs/src/rules/no-process-env.md +++ b/docs/src/rules/no-process-env.md @@ -7,7 +7,7 @@ further_reading: --- -This rule was **deprecated** in ESLint v7.0.0. Please use the corresponding rule in [`eslint-plugin-n`](https://github.com/eslint-community/eslint-plugin-n). +This rule was **deprecated** in ESLint v7.0.0. Please use the corresponding rule in [`eslint-plugin-node`](https://github.com/mysticatea/eslint-plugin-node). The `process.env` object in Node.js is used to store deployment/configuration parameters. Littering it through out a project could lead to maintenance issues as it's another kind of global dependency. As such, it could lead to merge conflicts in a multi-user setup and deployment issues in a multi-server setup. Instead, one of the best practices is to define all those parameters in a single configuration/settings file which could be accessed throughout the project. diff --git a/docs/src/rules/no-process-exit.md b/docs/src/rules/no-process-exit.md index 90e312b2d45..6928a0d4843 100644 --- a/docs/src/rules/no-process-exit.md +++ b/docs/src/rules/no-process-exit.md @@ -4,7 +4,7 @@ rule_type: suggestion --- -This rule was **deprecated** in ESLint v7.0.0. Please use the corresponding rule in [`eslint-plugin-n`](https://github.com/eslint-community/eslint-plugin-n). +This rule was **deprecated** in ESLint v7.0.0. Please use the corresponding rule in [`eslint-plugin-node`](https://github.com/mysticatea/eslint-plugin-node). The `process.exit()` method in Node.js is used to immediately stop the Node.js process and exit. This is a dangerous operation because it can occur in any method at any point in time, potentially stopping a Node.js application completely when an error occurs. For example: diff --git a/docs/src/rules/no-restricted-modules.md b/docs/src/rules/no-restricted-modules.md index eb2ca03ffc8..3ed5bd86117 100644 --- a/docs/src/rules/no-restricted-modules.md +++ b/docs/src/rules/no-restricted-modules.md @@ -4,7 +4,7 @@ rule_type: suggestion --- -This rule was **deprecated** in ESLint v7.0.0. Please use the corresponding rule in [`eslint-plugin-n`](https://github.com/eslint-community/eslint-plugin-n). +This rule was **deprecated** in ESLint v7.0.0. Please use the corresponding rule in [`eslint-plugin-node`](https://github.com/mysticatea/eslint-plugin-node). A module in Node.js is a simple or complex functionality organized in a JavaScript file which can be reused throughout the Node.js application. The keyword `require` is used in Node.js/CommonJS to import modules into an application. This way you can have dynamic loading where the loaded module name isn't predefined /static, or where you conditionally load a module only if it's "truly required". diff --git a/docs/src/rules/no-sync.md b/docs/src/rules/no-sync.md index 254974411e4..33fbec47fc0 100644 --- a/docs/src/rules/no-sync.md +++ b/docs/src/rules/no-sync.md @@ -4,7 +4,7 @@ rule_type: suggestion --- -This rule was **deprecated** in ESLint v7.0.0. Please use the corresponding rule in [`eslint-plugin-n`](https://github.com/eslint-community/eslint-plugin-n). +This rule was **deprecated** in ESLint v7.0.0. Please use the corresponding rule in [`eslint-plugin-node`](https://github.com/mysticatea/eslint-plugin-node). In Node.js, most I/O is done through asynchronous methods. However, there are often synchronous versions of the asynchronous methods. For example, `fs.exists()` and `fs.existsSync()`. In some contexts, using synchronous operations is okay (if, as with ESLint, you are writing a command line utility). However, in other contexts the use of synchronous operations is considered a bad practice that should be avoided. For example, if you are running a high-travel web server on Node.js, you should consider carefully if you want to allow any synchronous operations that could lock up the server. diff --git a/docs/src/rules/semi.md b/docs/src/rules/semi.md index 6fd05501cd1..86c4e5d84fe 100644 --- a/docs/src/rules/semi.md +++ b/docs/src/rules/semi.md @@ -76,18 +76,17 @@ This rule has two options, a string option and an object option. String option: * `"always"` (default) requires semicolons at the end of statements -* `"never"` disallows semicolons at the end of statements (except to disambiguate statements beginning with `[`, `(`, `/`, `+`, or `-`) +* `"never"` disallows semicolons as the end of statements (except to disambiguate statements beginning with `[`, `(`, `/`, `+`, or `-`) Object option (when `"always"`): -* `"omitLastInOneLineBlock": true` disallows the last semicolon in a block in which its braces (and therefore the content of the block) are in the same line -* `"omitLastInOneLineClassBody": true` disallows the last semicolon in a class body in which its braces (and therefore the content of the class body) are in the same line +* `"omitLastInOneLineBlock": true` ignores the last semicolon in a block in which its braces (and therefore the content of the block) are in the same line Object option (when `"never"`): * `"beforeStatementContinuationChars": "any"` (default) ignores semicolons (or lacking semicolon) at the end of statements if the next line starts with `[`, `(`, `/`, `+`, or `-`. * `"beforeStatementContinuationChars": "always"` requires semicolons at the end of statements if the next line starts with `[`, `(`, `/`, `+`, or `-`. -* `"beforeStatementContinuationChars": "never"` disallows semicolons at the end of statements if it doesn't make ASI hazard even if the next line starts with `[`, `(`, `/`, `+`, or `-`. +* `"beforeStatementContinuationChars": "never"` disallows semicolons as the end of statements if it doesn't make ASI hazard even if the next line starts with `[`, `(`, `/`, `+`, or `-`. **Note:** `beforeStatementContinuationChars` does not apply to class fields because class fields are not statements. @@ -133,52 +132,6 @@ class Foo { ::: -#### omitLastInOneLineBlock - -Examples of additional **correct** code for this rule with the `"always", { "omitLastInOneLineBlock": true }` options: - -::: correct - -```js -/*eslint semi: ["error", "always", { "omitLastInOneLineBlock": true}] */ - -if (foo) { bar() } - -if (foo) { bar(); baz() } - -function f() { bar(); baz() } - -class C { - foo() { bar(); baz() } - - static { bar(); baz() } -} -``` - -::: - -#### omitLastInOneLineClassBody - -Examples of additional **correct** code for this rule with the `"always", { "omitLastInOneLineClassBody": true }` options: - -::: correct - -```js -/*eslint semi: ["error", "always", { "omitLastInOneLineClassBody": true}] */ - -export class SomeClass{ - logType(){ - console.log(this.type); - console.log(this.anotherType); - } -} - -export class Variant1 extends SomeClass{type=1} -export class Variant2 extends SomeClass{type=2; anotherType=3} -``` - -::: - ### never Examples of **incorrect** code for this rule with the `"never"` option: @@ -237,6 +190,30 @@ class Foo { ::: +#### omitLastInOneLineBlock + +Examples of additional **correct** code for this rule with the `"always", { "omitLastInOneLineBlock": true }` options: + +::: correct + +```js +/*eslint semi: ["error", "always", { "omitLastInOneLineBlock": true}] */ + +if (foo) { bar() } + +if (foo) { bar(); baz() } + +function f() { bar(); baz() } + +class C { + foo() { bar(); baz() } + + static { bar(); baz() } +} +``` + +::: + #### beforeStatementContinuationChars Examples of additional **incorrect** code for this rule with the `"never", { "beforeStatementContinuationChars": "always" }` options: diff --git a/docs/src/use/configure/configuration-files-new.md b/docs/src/use/configure/configuration-files-new.md index bf854f08eca..a57bbf0f235 100644 --- a/docs/src/use/configure/configuration-files-new.md +++ b/docs/src/use/configure/configuration-files-new.md @@ -9,7 +9,7 @@ eleventyNavigation: --- ::: warning -This config system is feature complete but not enabled by default. To opt-in, place an `eslint.config.js` file in the root of your project or set the `ESLINT_USE_FLAT_CONFIG` environment variable to `true`. To opt-out, even in the presence of an `eslint.config.js` file, set the environment variable to `false`. If you are using the API, you can use the configuration system described on this page by using the `FlatESLint` class, the `FlatRuleTester` class, or by setting `configType: "flat"` in the `Linter` class. +This is an experimental feature. To opt-in, place an `eslint.config.js` file in the root of your project or set the `ESLINT_USE_FLAT_CONFIG` environment variable to `true`. To opt-out, even in the presence of an `eslint.config.js` file, set the environment variable to `false`. If you are using the API, you can use the configuration system described on this page by using the `FlatESLint` class, the `FlatRuleTester` class, or by setting `configType: "flat"` in the `Linter` class. ::: You can put your ESLint project configuration in a configuration file. You can include built-in rules, how you want them enforced, plugins with custom rules, shareable configurations, which files you want rules to apply to, and more. @@ -143,21 +143,7 @@ export default [ ]; ``` -This configuration specifies that all of the files in the `.config` directory should be ignored. This pattern is added after the default patterns, which are `["**/node_modules/", ".git/"]`. - -You can also unignore files and directories that are ignored by the default patterns. For example, this config unignores `node_modules/mylibrary`: - -```js -export default [ - { - ignores: [ - "!node_modules/", // unignore `node_modules/` directory - "node_modules/*", // ignore its content - "!node_modules/mylibrary/" // unignore `node_modules/mylibrary` directory - ] - } -]; -``` +This configuration specifies that all of the files in the `.config` directory should be ignored. This pattern is added after the default patterns, which are `["**/node_modules/**", ".git/**"]`. #### Cascading configuration objects @@ -342,24 +328,6 @@ export default [ For historical reasons, the boolean value `false` and the string value `"readable"` are equivalent to `"readonly"`. Similarly, the boolean value `true` and the string value `"writeable"` are equivalent to `"writable"`. However, the use of older values is deprecated. -##### Predefined global variables - -Apart from the ECMAScript standard built-in globals, which are automatically enabled based on the configured `languageOptions.ecmaVersion`, ESLint doesn't provide predefined sets of global variables. You can use the [`globals`](https://www.npmjs.com/package/globals) package to additionally enable all globals for a specific environment. For example, here is how you can add `console`, amongst other browser globals, into your configuration. - -```js -import globals from "globals"; - -export default [ - { - languageOptions: { - globals: { - ...globals.browser - } - } - } -]; -``` - ### Using plugins in your configuration Plugins are used to share rules, processors, configurations, parsers, and more across ESLint projects. diff --git a/docs/src/use/configure/configuration-files.md b/docs/src/use/configure/configuration-files.md index b2d51e09a3b..f9c7aa341f3 100644 --- a/docs/src/use/configure/configuration-files.md +++ b/docs/src/use/configure/configuration-files.md @@ -8,10 +8,6 @@ eleventyNavigation: --- -::: warning -We are transitioning to a new config system in ESLint v9.0.0. The config system shared on this page is currently the default but will be deprecated in v9.0.0. You can opt-in to the new config system by following the instructions in the [documentation](configuration-files-new). -::: - You can put your ESLint project configuration in a configuration file. You can include built-in rules, how you want them enforced, plugins with custom rules, shareable configurations, which files you want rules to apply to, and more. ## Configuration File Formats diff --git a/docs/src/use/configure/language-options.md b/docs/src/use/configure/language-options.md index 4f8fa148bce..ef21c35d57e 100644 --- a/docs/src/use/configure/language-options.md +++ b/docs/src/use/configure/language-options.md @@ -27,7 +27,7 @@ An environment provides predefined global variables. The available environments * `es2021` - adds all ECMAScript 2021 globals and automatically sets the `ecmaVersion` parser option to 12. * `es2022` - adds all ECMAScript 2022 globals and automatically sets the `ecmaVersion` parser option to 13. * `worker` - web workers global variables. -* `amd` - defines `require()` and `define()` as global variables as per the [amd](https://github.com/amdjs/amdjs-api/blob/master/AMD.md) spec. +* `amd` - defines `require()` and `define()` as global variables as per the [amd](https://github.com/amdjs/amdjs-api/wiki/AMD) spec. * `mocha` - adds all of the Mocha testing global variables. * `jasmine` - adds all of the Jasmine testing global variables for version 1.3 and 2.0. * `jest` - Jest global variables. @@ -187,7 +187,7 @@ For historical reasons, the boolean value `false` and the string value `"readabl ESLint allows you to specify the JavaScript language options you want to support. By default, ESLint expects ECMAScript 5 syntax. You can override that setting to enable support for other ECMAScript versions and JSX using parser options. -Please note that supporting JSX syntax is not the same as supporting React. React applies specific semantics to JSX syntax that ESLint doesn't recognize. We recommend using [eslint-plugin-react](https://github.com/jsx-eslint/eslint-plugin-react) if you are using React. +Please note that supporting JSX syntax is not the same as supporting React. React applies specific semantics to JSX syntax that ESLint doesn't recognize. We recommend using [eslint-plugin-react](https://github.com/yannickcr/eslint-plugin-react) if you are using React. By the same token, supporting ES6 syntax is not the same as supporting new ES6 globals (e.g., new types such as `Set`). For ES6 syntax, use `{ "parserOptions": { "ecmaVersion": 6 } }`; for new ES6 global variables, use `{ "env": { "es6": true } }`. Setting `{ "env": { "es6": true } }` enables ES6 syntax automatically, but `{ "parserOptions": { "ecmaVersion": 6 } }` does not enable ES6 globals automatically. diff --git a/docs/src/use/formatters/index.md b/docs/src/use/formatters/index.md index ec6ce537ed7..b5bb8be723d 100644 --- a/docs/src/use/formatters/index.md +++ b/docs/src/use/formatters/index.md @@ -122,7 +122,7 @@ Alternatively, you can use the [ESLint Node.js API](../../integrate/nodejs-api) Example output: ```text -{"results":[{"filePath":"/var/lib/jenkins/workspace/Releases/eslint Release/eslint/fullOfProblems.js","messages":[{"ruleId":"no-unused-vars","severity":2,"message":"'addOne' is defined but never used.","line":1,"column":10,"nodeType":"Identifier","messageId":"unusedVar","endLine":1,"endColumn":16},{"ruleId":"use-isnan","severity":2,"message":"Use the isNaN function to compare with NaN.","line":2,"column":9,"nodeType":"BinaryExpression","messageId":"comparisonWithNaN","endLine":2,"endColumn":17},{"ruleId":"space-unary-ops","severity":2,"message":"Unexpected space before unary operator '++'.","line":3,"column":16,"nodeType":"UpdateExpression","messageId":"unexpectedBefore","endLine":3,"endColumn":20,"fix":{"range":[57,58],"text":""}},{"ruleId":"semi","severity":1,"message":"Missing semicolon.","line":3,"column":20,"nodeType":"ReturnStatement","messageId":"missingSemi","endLine":4,"endColumn":1,"fix":{"range":[60,60],"text":";"}},{"ruleId":"no-else-return","severity":1,"message":"Unnecessary 'else' after 'return'.","line":4,"column":12,"nodeType":"BlockStatement","messageId":"unexpected","endLine":6,"endColumn":6,"fix":{"range":[0,94],"text":"function addOne(i) {\n if (i != NaN) {\n return i ++\n } \n return\n \n}"}},{"ruleId":"indent","severity":1,"message":"Expected indentation of 8 spaces but found 6.","line":5,"column":1,"nodeType":"Keyword","messageId":"wrongIndentation","endLine":5,"endColumn":7,"fix":{"range":[74,80],"text":" "}},{"ruleId":"consistent-return","severity":2,"message":"Function 'addOne' expected a return value.","line":5,"column":7,"nodeType":"ReturnStatement","messageId":"missingReturnValue","endLine":5,"endColumn":13},{"ruleId":"semi","severity":1,"message":"Missing semicolon.","line":5,"column":13,"nodeType":"ReturnStatement","messageId":"missingSemi","endLine":6,"endColumn":1,"fix":{"range":[86,86],"text":";"}},{"ruleId":"no-extra-semi","severity":2,"message":"Unnecessary semicolon.","line":7,"column":2,"nodeType":"EmptyStatement","messageId":"unexpected","endLine":7,"endColumn":3,"fix":{"range":[93,95],"text":"}"}}],"suppressedMessages":[],"errorCount":5,"fatalErrorCount":0,"warningCount":4,"fixableErrorCount":2,"fixableWarningCount":4,"source":"function addOne(i) {\n if (i != NaN) {\n return i ++\n } else {\n return\n }\n};"}],"metadata":{"rulesMeta":{"no-else-return":{"type":"suggestion","docs":{"description":"Disallow `else` blocks after `return` statements in `if` statements","recommended":false,"url":"https://eslint.org/docs/latest/rules/no-else-return"},"schema":[{"type":"object","properties":{"allowElseIf":{"type":"boolean","default":true}},"additionalProperties":false}],"fixable":"code","messages":{"unexpected":"Unnecessary 'else' after 'return'."}},"indent":{"type":"layout","docs":{"description":"Enforce consistent indentation","recommended":false,"url":"https://eslint.org/docs/latest/rules/indent"},"fixable":"whitespace","schema":[{"oneOf":[{"enum":["tab"]},{"type":"integer","minimum":0}]},{"type":"object","properties":{"SwitchCase":{"type":"integer","minimum":0,"default":0},"VariableDeclarator":{"oneOf":[{"oneOf":[{"type":"integer","minimum":0},{"enum":["first","off"]}]},{"type":"object","properties":{"var":{"oneOf":[{"type":"integer","minimum":0},{"enum":["first","off"]}]},"let":{"oneOf":[{"type":"integer","minimum":0},{"enum":["first","off"]}]},"const":{"oneOf":[{"type":"integer","minimum":0},{"enum":["first","off"]}]}},"additionalProperties":false}]},"outerIIFEBody":{"oneOf":[{"type":"integer","minimum":0},{"enum":["off"]}]},"MemberExpression":{"oneOf":[{"type":"integer","minimum":0},{"enum":["off"]}]},"FunctionDeclaration":{"type":"object","properties":{"parameters":{"oneOf":[{"type":"integer","minimum":0},{"enum":["first","off"]}]},"body":{"type":"integer","minimum":0}},"additionalProperties":false},"FunctionExpression":{"type":"object","properties":{"parameters":{"oneOf":[{"type":"integer","minimum":0},{"enum":["first","off"]}]},"body":{"type":"integer","minimum":0}},"additionalProperties":false},"StaticBlock":{"type":"object","properties":{"body":{"type":"integer","minimum":0}},"additionalProperties":false},"CallExpression":{"type":"object","properties":{"arguments":{"oneOf":[{"type":"integer","minimum":0},{"enum":["first","off"]}]}},"additionalProperties":false},"ArrayExpression":{"oneOf":[{"type":"integer","minimum":0},{"enum":["first","off"]}]},"ObjectExpression":{"oneOf":[{"type":"integer","minimum":0},{"enum":["first","off"]}]},"ImportDeclaration":{"oneOf":[{"type":"integer","minimum":0},{"enum":["first","off"]}]},"flatTernaryExpressions":{"type":"boolean","default":false},"offsetTernaryExpressions":{"type":"boolean","default":false},"ignoredNodes":{"type":"array","items":{"type":"string","not":{"pattern":":exit$"}}},"ignoreComments":{"type":"boolean","default":false}},"additionalProperties":false}],"messages":{"wrongIndentation":"Expected indentation of {{expected}} but found {{actual}}."}},"space-unary-ops":{"type":"layout","docs":{"description":"Enforce consistent spacing before or after unary operators","recommended":false,"url":"https://eslint.org/docs/latest/rules/space-unary-ops"},"fixable":"whitespace","schema":[{"type":"object","properties":{"words":{"type":"boolean","default":true},"nonwords":{"type":"boolean","default":false},"overrides":{"type":"object","additionalProperties":{"type":"boolean"}}},"additionalProperties":false}],"messages":{"unexpectedBefore":"Unexpected space before unary operator '{{operator}}'.","unexpectedAfter":"Unexpected space after unary operator '{{operator}}'.","unexpectedAfterWord":"Unexpected space after unary word operator '{{word}}'.","wordOperator":"Unary word operator '{{word}}' must be followed by whitespace.","operator":"Unary operator '{{operator}}' must be followed by whitespace.","beforeUnaryExpressions":"Space is required before unary expressions '{{token}}'."}},"semi":{"type":"layout","docs":{"description":"Require or disallow semicolons instead of ASI","recommended":false,"url":"https://eslint.org/docs/latest/rules/semi"},"fixable":"code","schema":{"anyOf":[{"type":"array","items":[{"enum":["never"]},{"type":"object","properties":{"beforeStatementContinuationChars":{"enum":["always","any","never"]}},"additionalProperties":false}],"minItems":0,"maxItems":2},{"type":"array","items":[{"enum":["always"]},{"type":"object","properties":{"omitLastInOneLineBlock":{"type":"boolean"},"omitLastInOneLineClassBody":{"type":"boolean"}},"additionalProperties":false}],"minItems":0,"maxItems":2}]},"messages":{"missingSemi":"Missing semicolon.","extraSemi":"Extra semicolon."}},"consistent-return":{"type":"suggestion","docs":{"description":"Require `return` statements to either always or never specify values","recommended":false,"url":"https://eslint.org/docs/latest/rules/consistent-return"},"schema":[{"type":"object","properties":{"treatUndefinedAsUnspecified":{"type":"boolean","default":false}},"additionalProperties":false}],"messages":{"missingReturn":"Expected to return a value at the end of {{name}}.","missingReturnValue":"{{name}} expected a return value.","unexpectedReturnValue":"{{name}} expected no return value."}}}}} +{"results":[{"filePath":"/var/lib/jenkins/workspace/Releases/eslint Release/eslint/fullOfProblems.js","messages":[{"ruleId":"no-unused-vars","severity":2,"message":"'addOne' is defined but never used.","line":1,"column":10,"nodeType":"Identifier","messageId":"unusedVar","endLine":1,"endColumn":16},{"ruleId":"use-isnan","severity":2,"message":"Use the isNaN function to compare with NaN.","line":2,"column":9,"nodeType":"BinaryExpression","messageId":"comparisonWithNaN","endLine":2,"endColumn":17},{"ruleId":"space-unary-ops","severity":2,"message":"Unexpected space before unary operator '++'.","line":3,"column":16,"nodeType":"UpdateExpression","messageId":"unexpectedBefore","endLine":3,"endColumn":20,"fix":{"range":[57,58],"text":""}},{"ruleId":"semi","severity":1,"message":"Missing semicolon.","line":3,"column":20,"nodeType":"ReturnStatement","messageId":"missingSemi","endLine":4,"endColumn":1,"fix":{"range":[60,60],"text":";"}},{"ruleId":"no-else-return","severity":1,"message":"Unnecessary 'else' after 'return'.","line":4,"column":12,"nodeType":"BlockStatement","messageId":"unexpected","endLine":6,"endColumn":6,"fix":{"range":[0,94],"text":"function addOne(i) {\n if (i != NaN) {\n return i ++\n } \n return\n \n}"}},{"ruleId":"indent","severity":1,"message":"Expected indentation of 8 spaces but found 6.","line":5,"column":1,"nodeType":"Keyword","messageId":"wrongIndentation","endLine":5,"endColumn":7,"fix":{"range":[74,80],"text":" "}},{"ruleId":"consistent-return","severity":2,"message":"Function 'addOne' expected a return value.","line":5,"column":7,"nodeType":"ReturnStatement","messageId":"missingReturnValue","endLine":5,"endColumn":13},{"ruleId":"semi","severity":1,"message":"Missing semicolon.","line":5,"column":13,"nodeType":"ReturnStatement","messageId":"missingSemi","endLine":6,"endColumn":1,"fix":{"range":[86,86],"text":";"}},{"ruleId":"no-extra-semi","severity":2,"message":"Unnecessary semicolon.","line":7,"column":2,"nodeType":"EmptyStatement","messageId":"unexpected","endLine":7,"endColumn":3,"fix":{"range":[93,95],"text":"}"}}],"suppressedMessages":[],"errorCount":5,"fatalErrorCount":0,"warningCount":4,"fixableErrorCount":2,"fixableWarningCount":4,"source":"function addOne(i) {\n if (i != NaN) {\n return i ++\n } else {\n return\n }\n};"}],"metadata":{"rulesMeta":{"no-else-return":{"type":"suggestion","docs":{"description":"Disallow `else` blocks after `return` statements in `if` statements","recommended":false,"url":"https://eslint.org/docs/rules/no-else-return"},"schema":[{"type":"object","properties":{"allowElseIf":{"type":"boolean","default":true}},"additionalProperties":false}],"fixable":"code","messages":{"unexpected":"Unnecessary 'else' after 'return'."}},"indent":{"type":"layout","docs":{"description":"Enforce consistent indentation","recommended":false,"url":"https://eslint.org/docs/rules/indent"},"fixable":"whitespace","schema":[{"oneOf":[{"enum":["tab"]},{"type":"integer","minimum":0}]},{"type":"object","properties":{"SwitchCase":{"type":"integer","minimum":0,"default":0},"VariableDeclarator":{"oneOf":[{"oneOf":[{"type":"integer","minimum":0},{"enum":["first","off"]}]},{"type":"object","properties":{"var":{"oneOf":[{"type":"integer","minimum":0},{"enum":["first","off"]}]},"let":{"oneOf":[{"type":"integer","minimum":0},{"enum":["first","off"]}]},"const":{"oneOf":[{"type":"integer","minimum":0},{"enum":["first","off"]}]}},"additionalProperties":false}]},"outerIIFEBody":{"oneOf":[{"type":"integer","minimum":0},{"enum":["off"]}]},"MemberExpression":{"oneOf":[{"type":"integer","minimum":0},{"enum":["off"]}]},"FunctionDeclaration":{"type":"object","properties":{"parameters":{"oneOf":[{"type":"integer","minimum":0},{"enum":["first","off"]}]},"body":{"type":"integer","minimum":0}},"additionalProperties":false},"FunctionExpression":{"type":"object","properties":{"parameters":{"oneOf":[{"type":"integer","minimum":0},{"enum":["first","off"]}]},"body":{"type":"integer","minimum":0}},"additionalProperties":false},"StaticBlock":{"type":"object","properties":{"body":{"type":"integer","minimum":0}},"additionalProperties":false},"CallExpression":{"type":"object","properties":{"arguments":{"oneOf":[{"type":"integer","minimum":0},{"enum":["first","off"]}]}},"additionalProperties":false},"ArrayExpression":{"oneOf":[{"type":"integer","minimum":0},{"enum":["first","off"]}]},"ObjectExpression":{"oneOf":[{"type":"integer","minimum":0},{"enum":["first","off"]}]},"ImportDeclaration":{"oneOf":[{"type":"integer","minimum":0},{"enum":["first","off"]}]},"flatTernaryExpressions":{"type":"boolean","default":false},"offsetTernaryExpressions":{"type":"boolean","default":false},"ignoredNodes":{"type":"array","items":{"type":"string","not":{"pattern":":exit$"}}},"ignoreComments":{"type":"boolean","default":false}},"additionalProperties":false}],"messages":{"wrongIndentation":"Expected indentation of {{expected}} but found {{actual}}."}},"space-unary-ops":{"type":"layout","docs":{"description":"Enforce consistent spacing before or after unary operators","recommended":false,"url":"https://eslint.org/docs/rules/space-unary-ops"},"fixable":"whitespace","schema":[{"type":"object","properties":{"words":{"type":"boolean","default":true},"nonwords":{"type":"boolean","default":false},"overrides":{"type":"object","additionalProperties":{"type":"boolean"}}},"additionalProperties":false}],"messages":{"unexpectedBefore":"Unexpected space before unary operator '{{operator}}'.","unexpectedAfter":"Unexpected space after unary operator '{{operator}}'.","unexpectedAfterWord":"Unexpected space after unary word operator '{{word}}'.","wordOperator":"Unary word operator '{{word}}' must be followed by whitespace.","operator":"Unary operator '{{operator}}' must be followed by whitespace.","beforeUnaryExpressions":"Space is required before unary expressions '{{token}}'."}},"semi":{"type":"layout","docs":{"description":"Require or disallow semicolons instead of ASI","recommended":false,"url":"https://eslint.org/docs/rules/semi"},"fixable":"code","schema":{"anyOf":[{"type":"array","items":[{"enum":["never"]},{"type":"object","properties":{"beforeStatementContinuationChars":{"enum":["always","any","never"]}},"additionalProperties":false}],"minItems":0,"maxItems":2},{"type":"array","items":[{"enum":["always"]},{"type":"object","properties":{"omitLastInOneLineBlock":{"type":"boolean"}},"additionalProperties":false}],"minItems":0,"maxItems":2}]},"messages":{"missingSemi":"Missing semicolon.","extraSemi":"Extra semicolon."}},"consistent-return":{"type":"suggestion","docs":{"description":"Require `return` statements to either always or never specify values","recommended":false,"url":"https://eslint.org/docs/rules/consistent-return"},"schema":[{"type":"object","properties":{"treatUndefinedAsUnspecified":{"type":"boolean","default":false}},"additionalProperties":false}],"messages":{"missingReturn":"Expected to return a value at the end of {{name}}.","missingReturnValue":"{{name}} expected a return value.","unexpectedReturnValue":"{{name}} expected no return value."}}}}} ``` ### json diff --git a/docs/src/use/integrations.md b/docs/src/use/integrations.md index 427377ed7a0..892a5080e35 100644 --- a/docs/src/use/integrations.md +++ b/docs/src/use/integrations.md @@ -15,10 +15,10 @@ If you would like to recommend an integration to be added to this page, [submit ## Editors * Sublime Text 3: - * [SublimeLinter-eslint](https://github.com/SublimeLinter/SublimeLinter-eslint) + * [SublimeLinter-eslint](https://github.com/roadhump/SublimeLinter-eslint) * [Build Next](https://github.com/albertosantini/sublimetext-buildnext) * Vim: - * [ALE](https://github.com/dense-analysis/ale) + * [ALE](https://github.com/w0rp/ale) * [Syntastic](https://github.com/vim-syntastic/syntastic/tree/master/syntax_checkers/javascript) * Emacs: [Flycheck](http://www.flycheck.org/) supports ESLint with the [javascript-eslint](http://www.flycheck.org/en/latest/languages.html#javascript) checker. * Eclipse Orion: ESLint is the [default linter](https://dev.eclipse.org/mhonarc/lists/orion-dev/msg02718.html) @@ -26,6 +26,9 @@ If you would like to recommend an integration to be added to this page, [submit * TextMate 2: * [eslint.tmbundle](https://github.com/ryanfitzer/eslint.tmbundle) * [javascript-eslint.tmbundle](https://github.com/natesilva/javascript-eslint.tmbundle) +* Atom: + * [linter-eslint](https://atom.io/packages/linter-eslint) + * [fast-eslint-8](https://atom.io/packages/fast-eslint-8) * IntelliJ IDEA, WebStorm, PhpStorm, PyCharm, RubyMine, and other JetBrains IDEs: [How to use ESLint](https://www.jetbrains.com/help/webstorm/eslint.html) * Visual Studio: [Linting JavaScript in VS](https://learn.microsoft.com/en-us/visualstudio/javascript/linting-javascript?view=vs-2022) * Visual Studio Code: [ESLint Extension](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) @@ -34,8 +37,16 @@ If you would like to recommend an integration to be added to this page, [submit ## Build tools * Grunt: [grunt-eslint](https://www.npmjs.com/package/grunt-eslint) +* Gulp: [gulp-eslint](https://www.npmjs.com/package/gulp-eslint) +* Mimosa: [mimosa-eslint](https://www.npmjs.com/package/mimosa-eslint) +* Broccoli: [broccoli-eslint](https://www.npmjs.com/package/broccoli-eslint) +* Browserify: [eslintify](https://www.npmjs.com/package/eslintify) * Webpack: [eslint-webpack-plugin](https://www.npmjs.com/package/eslint-webpack-plugin) * Rollup: [@rollup/plugin-eslint](https://www.npmjs.com/package/@rollup/plugin-eslint) +* Ember-cli: [ember-cli-eslint](https://www.npmjs.com/package/ember-cli-eslint) +* Sails.js: [sails-hook-lint](https://www.npmjs.com/package/sails-hook-lint), [sails-eslint](https://www.npmjs.com/package/sails-eslint) +* Start: [@start/plugin-lib-eslint](https://www.npmjs.com/package/@start/plugin-lib-eslint) +* Brunch: [eslint-brunch](https://www.npmjs.com/package/eslint-brunch) ## Command Line Tools @@ -48,7 +59,11 @@ If you would like to recommend an integration to be added to this page, [submit * [Git Precommit Hook](https://coderwall.com/p/zq8jlq/eslint-pre-commit-hook) * [Git pre-commit hook that only lints staged changes](https://gist.github.com/dahjelle/8ddedf0aebd488208a9a7c829f19b9e8) * [overcommit Git hook manager](https://github.com/brigade/overcommit) -* [Mega-Linter](https://megalinter.io/latest/): Linters aggregator for CI, [embedding eslint](https://megalinter.io/latest/descriptors/javascript_eslint/) +* [Mega-Linter](https://nvuillam.github.io/mega-linter): Linters aggregator for CI, [embedding eslint](https://nvuillam.github.io/mega-linter/descriptors/javascript_eslint/) + +## Testing + +* Mocha.js: [mocha-eslint](https://www.npmjs.com/package/mocha-eslint) ## Other Integration Lists diff --git a/docs/src/use/migrate-to-8.0.0.md b/docs/src/use/migrate-to-8.0.0.md index 9fac8cd597a..71d92c52087 100644 --- a/docs/src/use/migrate-to-8.0.0.md +++ b/docs/src/use/migrate-to-8.0.0.md @@ -55,7 +55,7 @@ Node.js 10, 13, 15 all reached end of life either in 2020 or early 2021. ESLint ESLint v8.0.0 has removed the `codeframe` and `table` formatters from the core. These formatters required dependencies that weren't used anywhere else in ESLint, and removing them allows us to reduce the size of ESLint, allowing for faster installation. -**To address:** If you are using the `codeframe` or `table` formatters, you'll need to install the standalone [`eslint-formatter-codeframe`](https://github.com/eslint-community/eslint-formatter-codeframe) or [`eslint-formatter-table`](https://github.com/eslint-community/eslint-formatter-table) packages, respectively, to be able to use them in ESLint v8.0.0. +**To address:** If you are using the `codeframe` or `table` formatters, you'll need to install the standalone [`eslint-formatter-codeframe`](https://github.com/fregante/eslint-formatter-codeframe) or [`eslint-formatter-table`](https://github.com/fregante/eslint-formatter-table) packages, respectively, to be able to use them in ESLint v8.0.0. **Related issue(s):** [#14277](https://github.com/eslint/eslint/issues/14277), [#14316](https://github.com/eslint/eslint/pull/14316) @@ -135,7 +135,7 @@ module.exports = { }; ``` -The [eslint-plugin/require-meta-has-suggestions](https://github.com/eslint-community/eslint-plugin-eslint-plugin/blob/main/docs/rules/require-meta-has-suggestions.md) rule can automatically fix and enforce that your rules are properly specifying `meta.hasSuggestions`. +The [eslint-plugin/require-meta-has-suggestions](https://github.com/not-an-aardvark/eslint-plugin-eslint-plugin/blob/master/docs/rules/require-meta-has-suggestions.md) rule can automatically fix and enforce that your rules are properly specifying `meta.hasSuggestions`. **Related issue(s):** [#14312](https://github.com/eslint/eslint/issues/14312) @@ -164,9 +164,9 @@ module.exports = { }; ``` -The [eslint-plugin/require-meta-fixable](https://github.com/eslint-community/eslint-plugin-eslint-plugin/blob/main/docs/rules/require-meta-fixable.md) rule can automatically fix and enforce that your rules are properly specifying `meta.fixable`. +The [eslint-plugin/require-meta-fixable](https://github.com/not-an-aardvark/eslint-plugin-eslint-plugin/blob/master/docs/rules/require-meta-fixable.md) rule can automatically fix and enforce that your rules are properly specifying `meta.fixable`. -The [eslint-plugin/prefer-object-rule](https://github.com/eslint-community/eslint-plugin-eslint-plugin/blob/main/docs/rules/prefer-object-rule.md) rule can automatically fix and enforce that your rules are written with the object format instead of the deprecated function format. +The [eslint-plugin/prefer-object-rule](https://github.com/not-an-aardvark/eslint-plugin-eslint-plugin/blob/master/docs/rules/prefer-object-rule.md) rule can automatically fix and enforce that your rules are written with the object format instead of the deprecated function format. See the [rule documentation](../extend/custom-rules) for more information on writing rules. @@ -178,7 +178,7 @@ Back in ESLint v4.0.0, we deprecated `SourceCode#getComments()`, but we neglecte The `SourceCode#getComments()` method will be removed in v9.0.0. -**To address:** If your rule uses `SourceCode#getComments()`, please use [`SourceCode#getCommentsBefore()`, `SourceCode#getCommentsAfter()`, or `SourceCode#getCommentsInside()`](../extend/custom-rules#accessing-comments). +**To address:** If your rule uses `SourceCode#getComments()`, please use [`SourceCode#getCommentsBefore()`, `SourceCode#getCommentsAfter()`, or `SourceCode#getCommentsInside()`](../extend/custom-rules#sourcecodegetcommentsbefore-sourcecodegetcommentsafter-and-sourcecodegetcommentsinside). **Related issue(s):** [#14744](https://github.com/eslint/eslint/issues/14744) diff --git a/docs/src/use/migrating-to-5.0.0.md b/docs/src/use/migrating-to-5.0.0.md index 96c54ec5dee..5eb4ec7ad1a 100644 --- a/docs/src/use/migrating-to-5.0.0.md +++ b/docs/src/use/migrating-to-5.0.0.md @@ -221,7 +221,7 @@ Previously, the `context.getScope()` method changed its behavior based on the `p Additionally, `context.getScope()` incorrectly returned the parent scope of the proper scope on `CatchClause` (in ES5), `ForStatement` (in ≧ES2015), `ForInStatement` (in ≧ES2015), `ForOfStatement`, and `WithStatement` nodes. -In ESLint v5, the `context.getScope()` method has the same behavior regardless of `parserOptions.ecmaVersion` and returns the proper scope. See [the documentation](../extend/scope-manager-interface) for more details on which scopes are returned. +In ESLint v5, the `context.getScope()` method has the same behavior regardless of `parserOptions.ecmaVersion` and returns the proper scope. See [the documentation](../extend/custom-rules#contextgetscope) for more details on which scopes are returned. **To address:** If you have written a custom rule that uses the `context.getScope()` method in node handlers, you may need to update it to account for the modified scope information. diff --git a/docs/src/use/migrating-to-7.0.0.md b/docs/src/use/migrating-to-7.0.0.md index 86b81cf832a..898bcad11a3 100644 --- a/docs/src/use/migrating-to-7.0.0.md +++ b/docs/src/use/migrating-to-7.0.0.md @@ -145,7 +145,7 @@ To allow for the colocation of comments that provide context with the directive, ## Node.js/CommonJS rules have been deprecated -The ten Node.js/CommonJS rules in core have been deprecated and moved to the [eslint-plugin-node](https://github.com/mysticatea/eslint-plugin-node) plugin (for ESLint v8.0.0 and later, use the maintained [eslint-plugin-n](https://github.com/eslint-community/eslint-plugin-n) fork instead) . +The ten Node.js/CommonJS rules in core have been deprecated and moved to the [eslint-plugin-node](https://github.com/mysticatea/eslint-plugin-node) plugin. **To address:** As per [our deprecation policy](../use/rule-deprecation), the deprecated rules will remain in core for the foreseeable future and are still available for use. However, we will no longer be updating or fixing any bugs in those rules. To use a supported version of the rules, we recommend using the corresponding rules in the plugin instead.