From 67e7af3fdbdb4648b747dfd669be4decfe24086a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=94=AF=E7=84=B6?= Date: Fri, 16 Jun 2023 13:45:29 +0800 Subject: [PATCH] docs: resubmit custom-rules doc changes (#17294) credits: https://github.com/snitin315 Refs: * https://github.com/eslint/eslint/issues/17225 * https://github.com/eslint/eslint/pull/17108 * https://github.com/eslint/eslint/pull/17106 * https://github.com/eslint/eslint/pull/17111 * https://github.com/eslint/eslint/pull/17107 --- docs/src/extend/code-path-analysis.md | 3 +-- docs/src/extend/custom-rules.md | 20 +++++++++++++------- docs/src/integrate/nodejs-api.md | 4 ++-- 3 files changed, 16 insertions(+), 11 deletions(-) diff --git a/docs/src/extend/code-path-analysis.md b/docs/src/extend/code-path-analysis.md index a2caeff8ea9..7344f8647ad 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.getSourceCode(); - + const sourceCode = context.sourceCode; return sourceCode.getDeclaredVariables(node).some(function(v) { return v.type === "Parameter" && v.name === "cb"; }); diff --git a/docs/src/extend/custom-rules.md b/docs/src/extend/custom-rules.md index 1fe23d97ce1..3ba8845b954 100644 --- a/docs/src/extend/custom-rules.md +++ b/docs/src/extend/custom-rules.md @@ -124,7 +124,11 @@ As the name implies, the `context` object contains information that is relevant 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.) @@ -133,7 +137,7 @@ The `context` object has the following properties: 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()`: 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. +* `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. * 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. @@ -144,10 +148,10 @@ 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()`: 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. +* `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()`: 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)). +* `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)). @@ -506,18 +510,20 @@ When using options, make sure that your rule has some logical defaults in case t ### Accessing the Source Code -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.getSourceCode()` method: +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: ```js module.exports = { create: function(context) { - var sourceCode = context.getSourceCode(); + var sourceCode = context.sourceCode; // ... } }; ``` +**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)). @@ -706,7 +712,7 @@ To help with this, you can use the `sourceCode.markVariableAsUsed()` method. Thi ```js module.exports = { create: function(context) { - var sourceCode = context.getSourceCode(); + var sourceCode = context.sourceCode; return { ReturnStatement(node) { diff --git a/docs/src/integrate/nodejs-api.md b/docs/src/integrate/nodejs-api.md index de035ca731c..853abdc57b8 100644 --- a/docs/src/integrate/nodejs-api.md +++ b/docs/src/integrate/nodejs-api.md @@ -510,7 +510,7 @@ The `Linter` object does the actual evaluation of the JavaScript code. It doesn' The `Linter` is a constructor, and you can create a new instance by passing in the options you want to use. The available options are: -* `cwd` - Path to a directory that should be considered as the current working directory. It is accessible to rules by calling `context.getCwd()` (see [The Context Object](../extend/custom-rules#the-context-object)). If `cwd` is `undefined`, it will be normalized to `process.cwd()` if the global `process` object is defined (for example, in the Node.js runtime) , or `undefined` otherwise. +* `cwd` - Path to a directory that should be considered as the current working directory. It is accessible to rules from `context.cwd` or by calling `context.getCwd()` (see [The Context Object](../extend/custom-rules#the-context-object)). If `cwd` is `undefined`, it will be normalized to `process.cwd()` if the global `process` object is defined (for example, in the Node.js runtime) , or `undefined` otherwise. For example: @@ -520,7 +520,7 @@ const linter1 = new Linter({ cwd: 'path/to/project' }); const linter2 = new Linter(); ``` -In this example, rules run on `linter1` will get `path/to/project` when calling `context.getCwd()`. +In this example, rules run on `linter1` will get `path/to/project` from `context.cwd` or when calling `context.getCwd()`. Those run on `linter2` will get `process.cwd()` if the global `process` object is defined or `undefined` otherwise (e.g. on the browser ). ### Linter#verify