From b2a5ec7dc3780ddc3e3c733c7099fc6cc82ee5a6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=94=AF=E7=84=B6?= Date: Thu, 15 Jun 2023 15:34:49 +0800 Subject: [PATCH] docs: resubmit custom-rules doc changes 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 | 39 ++++++++++++++++----------- docs/src/integrate/nodejs-api.md | 4 +-- 3 files changed, 27 insertions(+), 19 deletions(-) diff --git a/docs/src/extend/code-path-analysis.md b/docs/src/extend/code-path-analysis.md index a2caeff8ea92..7344f8647adf 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 1fe23d97ce14..35b04fdbf8e4 100644 --- a/docs/src/extend/custom-rules.md +++ b/docs/src/extend/custom-rules.md @@ -4,7 +4,7 @@ eleventyNavigation: key: custom rules parent: create plugins title: Custom Rules - order: 2 + order: 1 --- @@ -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)). @@ -608,12 +614,17 @@ You can also access comments through many of `sourceCode`'s methods using the `i 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`. 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. +There are two formats for a rule's exported `schema`: + +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. + +In both cases, these should exclude the [severity](../use/configure/rules#rule-severities), as ESLint automatically validates this first. -However, to simplify schema creation, rules may also export an array of schemas for each optional positional argument. ESLint automatically validates 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. +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`: ```js -// "yoda": [2, "never", { "exceptRange": true }] +// "yoda": ["error", "never", { "exceptRange": true }] module.exports = { meta: { schema: [ @@ -634,12 +645,10 @@ module.exports = { }; ``` -In the preceding example, the error level is assumed to be the first argument. It is followed by the first optional argument, a string that may be either `"always"` or `"never"`. The final optional argument is an object, which may have a boolean property named `exceptRange`. - -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). - **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()`. @@ -706,7 +715,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 de035ca731c6..853abdc57b8d 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