From 4c666a0022ae07947ee7d53840d4c82469a272d9 Mon Sep 17 00:00:00 2001 From: Bryan Mishkin <698306+bmish@users.noreply.github.com> Date: Sun, 9 Oct 2022 15:53:56 -0400 Subject: [PATCH] docs: add eslint-doc-generator --- README.md | 72 ++++----- build/generate-readme-table.js | 61 -------- docs/rules/consistent-output.md | 6 +- docs/rules/fixer-return.md | 6 +- docs/rules/meta-property-ordering.md | 6 +- docs/rules/no-deprecated-context-methods.md | 8 +- docs/rules/no-deprecated-report-api.md | 8 +- docs/rules/no-identical-tests.md | 8 +- docs/rules/no-missing-message-ids.md | 6 +- docs/rules/no-missing-placeholders.md | 6 +- docs/rules/no-only-tests.md | 8 +- docs/rules/no-unused-message-ids.md | 6 +- docs/rules/no-unused-placeholders.md | 6 +- docs/rules/no-useless-token-range.md | 8 +- docs/rules/prefer-message-ids.md | 6 +- docs/rules/prefer-object-rule.md | 8 +- docs/rules/prefer-output-null.md | 8 +- docs/rules/prefer-placeholders.md | 4 +- docs/rules/prefer-replace-text.md | 4 +- docs/rules/report-message-format.md | 4 +- docs/rules/require-meta-docs-description.md | 4 +- docs/rules/require-meta-docs-url.md | 6 +- docs/rules/require-meta-fixable.md | 6 +- docs/rules/require-meta-has-suggestions.md | 8 +- docs/rules/require-meta-schema.md | 8 +- docs/rules/require-meta-type.md | 6 +- docs/rules/test-case-property-ordering.md | 6 +- docs/rules/test-case-shorthand-strings.md | 6 +- package.json | 8 +- tests/build/generate-readme-table.js | 20 --- tests/lib/rule-setup.js | 162 -------------------- 31 files changed, 151 insertions(+), 338 deletions(-) delete mode 100644 build/generate-readme-table.js delete mode 100644 tests/build/generate-readme-table.js diff --git a/README.md b/README.md index 9826fc44..d1443462 100644 --- a/README.md +++ b/README.md @@ -54,46 +54,48 @@ Here's an example ESLint configuration that: ## Rules -* ✔️ if the rule belongs to the `recommended` configuration -* 🛠 if some problems reported by the rule are automatically fixable by the `--fix` [command line](https://eslint.org/docs/user-guide/command-line-interface#fixing-problems) option -* 💡 if some problems reported by the rule are manually fixable by editor [suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions) - - -Name | ✔️ | 🛠 | 💡 | Description ------ | ----- | ----- | ----- | ----- -[consistent-output](https://github.com/eslint-community/eslint-plugin-eslint-plugin/blob/master/docs/rules/consistent-output.md) | ✔️ | | | enforce consistent use of `output` assertions in rule tests -[fixer-return](https://github.com/eslint-community/eslint-plugin-eslint-plugin/blob/master/docs/rules/fixer-return.md) | ✔️ | | | require fixer functions to return a fix -[meta-property-ordering](https://github.com/eslint-community/eslint-plugin-eslint-plugin/blob/master/docs/rules/meta-property-ordering.md) | | 🛠 | | enforce the order of meta properties -[no-deprecated-context-methods](https://github.com/eslint-community/eslint-plugin-eslint-plugin/blob/master/docs/rules/no-deprecated-context-methods.md) | ✔️ | 🛠 | | disallow usage of deprecated methods on rule context objects -[no-deprecated-report-api](https://github.com/eslint-community/eslint-plugin-eslint-plugin/blob/master/docs/rules/no-deprecated-report-api.md) | ✔️ | 🛠 | | disallow the version of `context.report()` with multiple arguments -[no-identical-tests](https://github.com/eslint-community/eslint-plugin-eslint-plugin/blob/master/docs/rules/no-identical-tests.md) | ✔️ | 🛠 | | disallow identical tests -[no-missing-message-ids](https://github.com/eslint-community/eslint-plugin-eslint-plugin/blob/master/docs/rules/no-missing-message-ids.md) | ✔️ | | | disallow `messageId`s that are missing from `meta.messages` -[no-missing-placeholders](https://github.com/eslint-community/eslint-plugin-eslint-plugin/blob/master/docs/rules/no-missing-placeholders.md) | ✔️ | | | disallow missing placeholders in rule report messages -[no-only-tests](https://github.com/eslint-community/eslint-plugin-eslint-plugin/blob/master/docs/rules/no-only-tests.md) | ✔️ | | 💡 | disallow the test case property `only` -[no-unused-message-ids](https://github.com/eslint-community/eslint-plugin-eslint-plugin/blob/master/docs/rules/no-unused-message-ids.md) | ✔️ | | | disallow unused `messageId`s in `meta.messages` -[no-unused-placeholders](https://github.com/eslint-community/eslint-plugin-eslint-plugin/blob/master/docs/rules/no-unused-placeholders.md) | ✔️ | | | disallow unused placeholders in rule report messages -[no-useless-token-range](https://github.com/eslint-community/eslint-plugin-eslint-plugin/blob/master/docs/rules/no-useless-token-range.md) | ✔️ | 🛠 | | disallow unnecessary calls to `sourceCode.getFirstToken()` and `sourceCode.getLastToken()` -[prefer-message-ids](https://github.com/eslint-community/eslint-plugin-eslint-plugin/blob/master/docs/rules/prefer-message-ids.md) | ✔️ | | | require using `messageId` instead of `message` to report rule violations -[prefer-object-rule](https://github.com/eslint-community/eslint-plugin-eslint-plugin/blob/master/docs/rules/prefer-object-rule.md) | ✔️ | 🛠 | | disallow function-style rules -[prefer-output-null](https://github.com/eslint-community/eslint-plugin-eslint-plugin/blob/master/docs/rules/prefer-output-null.md) | ✔️ | 🛠 | | disallow invalid RuleTester test cases where the `output` matches the `code` -[prefer-placeholders](https://github.com/eslint-community/eslint-plugin-eslint-plugin/blob/master/docs/rules/prefer-placeholders.md) | | | | require using placeholders for dynamic report messages -[prefer-replace-text](https://github.com/eslint-community/eslint-plugin-eslint-plugin/blob/master/docs/rules/prefer-replace-text.md) | | | | require using `replaceText()` instead of `replaceTextRange()` -[report-message-format](https://github.com/eslint-community/eslint-plugin-eslint-plugin/blob/master/docs/rules/report-message-format.md) | | | | enforce a consistent format for rule report messages -[require-meta-docs-description](https://github.com/eslint-community/eslint-plugin-eslint-plugin/blob/master/docs/rules/require-meta-docs-description.md) | | | | require rules to implement a `meta.docs.description` property with the correct format -[require-meta-docs-url](https://github.com/eslint-community/eslint-plugin-eslint-plugin/blob/master/docs/rules/require-meta-docs-url.md) | | 🛠 | | require rules to implement a `meta.docs.url` property -[require-meta-fixable](https://github.com/eslint-community/eslint-plugin-eslint-plugin/blob/master/docs/rules/require-meta-fixable.md) | ✔️ | | | require rules to implement a `meta.fixable` property -[require-meta-has-suggestions](https://github.com/eslint-community/eslint-plugin-eslint-plugin/blob/master/docs/rules/require-meta-has-suggestions.md) | ✔️ | 🛠 | | require suggestable rules to implement a `meta.hasSuggestions` property -[require-meta-schema](https://github.com/eslint-community/eslint-plugin-eslint-plugin/blob/master/docs/rules/require-meta-schema.md) | ✔️ | | 💡 | require rules to implement a `meta.schema` property -[require-meta-type](https://github.com/eslint-community/eslint-plugin-eslint-plugin/blob/master/docs/rules/require-meta-type.md) | ✔️ | | | require rules to implement a `meta.type` property -[test-case-property-ordering](https://github.com/eslint-community/eslint-plugin-eslint-plugin/blob/master/docs/rules/test-case-property-ordering.md) | | 🛠 | | require the properties of a test case to be placed in a consistent order -[test-case-shorthand-strings](https://github.com/eslint-community/eslint-plugin-eslint-plugin/blob/master/docs/rules/test-case-shorthand-strings.md) | | 🛠 | | enforce consistent usage of shorthand strings for test cases with no options - + + +✅ Enabled in the `recommended` configuration.\ +🔧 Automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/user-guide/command-line-interface#--fix).\ +💡 Manually fixable by [editor suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions). + +| Name | Description | ✅ | 🔧 | 💡 | +| :--------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------- | :-- | :-- | :-- | +| [consistent-output](docs/rules/consistent-output.md) | enforce consistent use of `output` assertions in rule tests | ✅ | | | +| [fixer-return](docs/rules/fixer-return.md) | require fixer functions to return a fix | ✅ | | | +| [meta-property-ordering](docs/rules/meta-property-ordering.md) | enforce the order of meta properties | | 🔧 | | +| [no-deprecated-context-methods](docs/rules/no-deprecated-context-methods.md) | disallow usage of deprecated methods on rule context objects | ✅ | 🔧 | | +| [no-deprecated-report-api](docs/rules/no-deprecated-report-api.md) | disallow the version of `context.report()` with multiple arguments | ✅ | 🔧 | | +| [no-identical-tests](docs/rules/no-identical-tests.md) | disallow identical tests | ✅ | 🔧 | | +| [no-missing-message-ids](docs/rules/no-missing-message-ids.md) | disallow `messageId`s that are missing from `meta.messages` | ✅ | | | +| [no-missing-placeholders](docs/rules/no-missing-placeholders.md) | disallow missing placeholders in rule report messages | ✅ | | | +| [no-only-tests](docs/rules/no-only-tests.md) | disallow the test case property `only` | ✅ | | 💡 | +| [no-unused-message-ids](docs/rules/no-unused-message-ids.md) | disallow unused `messageId`s in `meta.messages` | ✅ | | | +| [no-unused-placeholders](docs/rules/no-unused-placeholders.md) | disallow unused placeholders in rule report messages | ✅ | | | +| [no-useless-token-range](docs/rules/no-useless-token-range.md) | disallow unnecessary calls to `sourceCode.getFirstToken()` and `sourceCode.getLastToken()` | ✅ | 🔧 | | +| [prefer-message-ids](docs/rules/prefer-message-ids.md) | require using `messageId` instead of `message` to report rule violations | ✅ | | | +| [prefer-object-rule](docs/rules/prefer-object-rule.md) | disallow function-style rules | ✅ | 🔧 | | +| [prefer-output-null](docs/rules/prefer-output-null.md) | disallow invalid RuleTester test cases where the `output` matches the `code` | ✅ | 🔧 | | +| [prefer-placeholders](docs/rules/prefer-placeholders.md) | require using placeholders for dynamic report messages | | | | +| [prefer-replace-text](docs/rules/prefer-replace-text.md) | require using `replaceText()` instead of `replaceTextRange()` | | | | +| [report-message-format](docs/rules/report-message-format.md) | enforce a consistent format for rule report messages | | | | +| [require-meta-docs-description](docs/rules/require-meta-docs-description.md) | require rules to implement a `meta.docs.description` property with the correct format | | | | +| [require-meta-docs-url](docs/rules/require-meta-docs-url.md) | require rules to implement a `meta.docs.url` property | | 🔧 | | +| [require-meta-fixable](docs/rules/require-meta-fixable.md) | require rules to implement a `meta.fixable` property | ✅ | | | +| [require-meta-has-suggestions](docs/rules/require-meta-has-suggestions.md) | require suggestable rules to implement a `meta.hasSuggestions` property | ✅ | 🔧 | | +| [require-meta-schema](docs/rules/require-meta-schema.md) | require rules to implement a `meta.schema` property | ✅ | | 💡 | +| [require-meta-type](docs/rules/require-meta-type.md) | require rules to implement a `meta.type` property | ✅ | | | +| [test-case-property-ordering](docs/rules/test-case-property-ordering.md) | require the properties of a test case to be placed in a consistent order | | 🔧 | | +| [test-case-shorthand-strings](docs/rules/test-case-shorthand-strings.md) | enforce consistent usage of shorthand strings for test cases with no options | | 🔧 | | + + ## Presets | | Name | Description | |:--|:-----|:------------| -| ✔️ | `recommended` | enables all recommended rules in this plugin | +| ✅ | `recommended` | enables all recommended rules in this plugin | | | `rules-recommended` | enables all recommended rules that are aimed at linting ESLint rule files | | | `tests-recommended` | enables all recommended rules that are aimed at linting ESLint test files | | | `all` | enables all rules in this plugin | diff --git a/build/generate-readme-table.js b/build/generate-readme-table.js deleted file mode 100644 index e4e126e5..00000000 --- a/build/generate-readme-table.js +++ /dev/null @@ -1,61 +0,0 @@ -'use strict'; - -const fs = require('node:fs'); -const path = require('node:path'); -const rules = require('..').rules; - -const README_LOCATION = path.resolve(__dirname, '..', 'README.md'); -const BEGIN_TABLE_MARKER = '\n'; -const END_TABLE_MARKER = '\n'; - -const expectedTableLines = Object.keys(rules) - .sort() - .reduce( - (lines, ruleId) => { - const rule = rules[ruleId]; - - lines.push( - [ - `[${ruleId}](https://github.com/eslint-community/eslint-plugin-eslint-plugin/blob/master/docs/rules/${ruleId}.md)`, - rule.meta.docs.recommended ? '✔️' : '', - rule.meta.fixable ? '🛠' : '', - rule.meta.hasSuggestions ? '💡' : '', - rule.meta.docs.description, - ].join(' | ') - ); - - return lines; - }, - [ - 'Name | ✔️ | 🛠 | 💡 | Description', - '----- | ----- | ----- | ----- | -----', - ] - ) - .join('\n'); - -const readmeContents = fs.readFileSync(README_LOCATION, 'utf8'); - -if (!readmeContents.includes(BEGIN_TABLE_MARKER)) { - throw new Error( - `Could not find '${BEGIN_TABLE_MARKER}' marker in README.md.` - ); -} - -if (!readmeContents.includes(END_TABLE_MARKER)) { - throw new Error(`Could not find '${END_TABLE_MARKER}' marker in README.md.`); -} - -const linesStartIndex = - readmeContents.indexOf(BEGIN_TABLE_MARKER) + BEGIN_TABLE_MARKER.length; -const linesEndIndex = readmeContents.indexOf(END_TABLE_MARKER); - -const updatedReadmeContents = - readmeContents.slice(0, linesStartIndex) + - expectedTableLines + - readmeContents.slice(linesEndIndex); - -if (module.parent) { - module.exports = updatedReadmeContents; -} else { - fs.writeFileSync(README_LOCATION, updatedReadmeContents); -} diff --git a/docs/rules/consistent-output.md b/docs/rules/consistent-output.md index 38fb7123..e05e441e 100644 --- a/docs/rules/consistent-output.md +++ b/docs/rules/consistent-output.md @@ -1,6 +1,8 @@ -# Enforce consistent use of `output` assertions in rule tests (consistent-output) +# Enforce consistent use of `output` assertions in rule tests (`eslint-plugin/consistent-output`) -✔️ The `"extends": "plugin:eslint-plugin/recommended"` property in a configuration file enables this rule. +✅ This rule is enabled in the `recommended` config. + + When writing tests for fixable rules, the `output` property on each test case can be used to assert what autofixed code is produced, or to assert that no autofix is produced using `output: null`. diff --git a/docs/rules/fixer-return.md b/docs/rules/fixer-return.md index 4add8729..8d268527 100644 --- a/docs/rules/fixer-return.md +++ b/docs/rules/fixer-return.md @@ -1,6 +1,8 @@ -# Require fixer functions to return a fix (fixer-return) +# Require fixer functions to return a fix (`eslint-plugin/fixer-return`) -✔️ The `"extends": "plugin:eslint-plugin/recommended"` property in a configuration file enables this rule. +✅ This rule is enabled in the `recommended` config. + + In a [fixable](https://eslint.org/docs/developer-guide/working-with-rules#applying-fixes) rule, a fixer function is useless if it never returns anything. diff --git a/docs/rules/meta-property-ordering.md b/docs/rules/meta-property-ordering.md index 4493c243..60b6a47b 100644 --- a/docs/rules/meta-property-ordering.md +++ b/docs/rules/meta-property-ordering.md @@ -1,6 +1,8 @@ -# Enforce the order of meta properties (meta-property-ordering) +# Enforce the order of meta properties (`eslint-plugin/meta-property-ordering`) -⚒️ The `--fix` option on the [command line](https://eslint.org/docs/user-guide/command-line-interface#--fix) can automatically fix some of the problems reported by this rule. +🔧 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix). + + This rule enforces that meta properties of a rule are placed in a consistent order. diff --git a/docs/rules/no-deprecated-context-methods.md b/docs/rules/no-deprecated-context-methods.md index e2bccfa2..259a96e8 100644 --- a/docs/rules/no-deprecated-context-methods.md +++ b/docs/rules/no-deprecated-context-methods.md @@ -1,8 +1,10 @@ -# Disallow usage of deprecated methods on rule context objects (no-deprecated-context-methods) +# Disallow usage of deprecated methods on rule context objects (`eslint-plugin/no-deprecated-context-methods`) -✔️ The `"extends": "plugin:eslint-plugin/recommended"` property in a configuration file enables this rule. +✅ This rule is enabled in the `recommended` config. -⚒️ The `--fix` option on the [command line](https://eslint.org/docs/user-guide/command-line-interface#--fix) can automatically fix some of the problems reported by this rule. +🔧 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix). + + This rule disallows the use of deprecated methods on rule `context` objects. diff --git a/docs/rules/no-deprecated-report-api.md b/docs/rules/no-deprecated-report-api.md index 92f06dff..942a9d7e 100644 --- a/docs/rules/no-deprecated-report-api.md +++ b/docs/rules/no-deprecated-report-api.md @@ -1,8 +1,10 @@ -# Disallow the version of `context.report()` with multiple arguments (no-deprecated-report-api) +# Disallow the version of `context.report()` with multiple arguments (`eslint-plugin/no-deprecated-report-api`) -✔️ The `"extends": "plugin:eslint-plugin/recommended"` property in a configuration file enables this rule. +✅ This rule is enabled in the `recommended` config. -⚒️ The `--fix` option on the [command line](https://eslint.org/docs/user-guide/command-line-interface#--fix) can automatically fix some of the problems reported by this rule. +🔧 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix). + + ESLint has two APIs that rules can use to report problems. diff --git a/docs/rules/no-identical-tests.md b/docs/rules/no-identical-tests.md index 1663e1c9..9780b332 100644 --- a/docs/rules/no-identical-tests.md +++ b/docs/rules/no-identical-tests.md @@ -1,8 +1,10 @@ -# Disallow identical tests (no-identical-tests) +# Disallow identical tests (`eslint-plugin/no-identical-tests`) -✔️ The `"extends": "plugin:eslint-plugin/recommended"` property in a configuration file enables this rule. +✅ This rule is enabled in the `recommended` config. -⚒️ The `--fix` option on the [command line](https://eslint.org/docs/user-guide/command-line-interface#--fix) can automatically fix some of the problems reported by this rule. +🔧 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix). + + Duplicate test cases can cause confusion, can be hard to detect manually in a long file, and serve no purpose. diff --git a/docs/rules/no-missing-message-ids.md b/docs/rules/no-missing-message-ids.md index 268c42b1..3f2ca11f 100644 --- a/docs/rules/no-missing-message-ids.md +++ b/docs/rules/no-missing-message-ids.md @@ -1,6 +1,8 @@ -# Disallow `messageId`s that are missing from `meta.messages` (no-missing-message-ids) +# Disallow `messageId`s that are missing from `meta.messages` (`eslint-plugin/no-missing-message-ids`) -✔️ The `"extends": "plugin:eslint-plugin/recommended"` property in a configuration file enables this rule. +✅ This rule is enabled in the `recommended` config. + + When using `meta.messages` and `messageId` to report rule violations, it's possible to mistakenly use a `messageId` that doesn't exist in `meta.messages`. diff --git a/docs/rules/no-missing-placeholders.md b/docs/rules/no-missing-placeholders.md index df32525e..04376b6c 100644 --- a/docs/rules/no-missing-placeholders.md +++ b/docs/rules/no-missing-placeholders.md @@ -1,6 +1,8 @@ -# Disallow missing placeholders in rule report messages (no-missing-placeholders) +# Disallow missing placeholders in rule report messages (`eslint-plugin/no-missing-placeholders`) -✔️ The `"extends": "plugin:eslint-plugin/recommended"` property in a configuration file enables this rule. +✅ This rule is enabled in the `recommended` config. + + Report messages in rules can have placeholders surrounded by curly brackets. diff --git a/docs/rules/no-only-tests.md b/docs/rules/no-only-tests.md index e03be4af..424d0e79 100644 --- a/docs/rules/no-only-tests.md +++ b/docs/rules/no-only-tests.md @@ -1,8 +1,10 @@ -# Disallow the test case property `only` (no-only-tests) +# Disallow the test case property `only` (`eslint-plugin/no-only-tests`) -✔️ The `"extends": "plugin:eslint-plugin/recommended"` property in a configuration file enables this rule. +✅ This rule is enabled in the `recommended` config. -💡 Some problems reported by this rule are manually fixable by editor [suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions). +💡 This rule is manually fixable by [editor suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions). + + The [`only` property](https://eslint.org/docs/developer-guide/unit-tests#running-individual-tests) can be used as of [ESLint 7.29](https://eslint.org/blog/2021/06/eslint-v7.29.0-released#highlights) for running individual rule test cases with less-noisy debugging. This feature should be only used in development, as it prevents all the tests from running. Mistakenly checking-in a test case with this property can cause CI tests to incorrectly pass. diff --git a/docs/rules/no-unused-message-ids.md b/docs/rules/no-unused-message-ids.md index 942d33d7..01cdde08 100644 --- a/docs/rules/no-unused-message-ids.md +++ b/docs/rules/no-unused-message-ids.md @@ -1,6 +1,8 @@ -# Disallow unused `messageId`s in `meta.messages` (no-unused-message-ids) +# Disallow unused `messageId`s in `meta.messages` (`eslint-plugin/no-unused-message-ids`) -✔️ The `"extends": "plugin:eslint-plugin/recommended"` property in a configuration file enables this rule. +✅ This rule is enabled in the `recommended` config. + + When using `meta.messages` and `messageId` to report rule violations, it's possible to mistakenly leave a message in `meta.messages` that is never used. diff --git a/docs/rules/no-unused-placeholders.md b/docs/rules/no-unused-placeholders.md index aa4fa5fe..7bff88fd 100644 --- a/docs/rules/no-unused-placeholders.md +++ b/docs/rules/no-unused-placeholders.md @@ -1,6 +1,8 @@ -# Disallow unused placeholders in rule report messages (no-unused-placeholders) +# Disallow unused placeholders in rule report messages (`eslint-plugin/no-unused-placeholders`) -✔️ The `"extends": "plugin:eslint-plugin/recommended"` property in a configuration file enables this rule. +✅ This rule is enabled in the `recommended` config. + + This rule aims to disallow unused placeholders in rule report messages. diff --git a/docs/rules/no-useless-token-range.md b/docs/rules/no-useless-token-range.md index 3593adca..bff2542c 100644 --- a/docs/rules/no-useless-token-range.md +++ b/docs/rules/no-useless-token-range.md @@ -1,8 +1,10 @@ -# Disallow unnecessary calls to `sourceCode.getFirstToken()` and `sourceCode.getLastToken()` (no-useless-token-range) +# Disallow unnecessary calls to `sourceCode.getFirstToken()` and `sourceCode.getLastToken()` (`eslint-plugin/no-useless-token-range`) -✔️ The `"extends": "plugin:eslint-plugin/recommended"` property in a configuration file enables this rule. +✅ This rule is enabled in the `recommended` config. -⚒️ The `--fix` option on the [command line](https://eslint.org/docs/user-guide/command-line-interface#--fix) can automatically fix some of the problems reported by this rule. +🔧 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix). + + AST nodes always start and end with tokens. As a result, the start index of the first token in a node is the same as the start index of the node itself, and the end index of the last token in a node is the same as the end index of the node itself. Using code like `sourceCode.getFirstToken(node).range[0]` unnecessarily hurts the performance of your rule, and makes your code less readable. diff --git a/docs/rules/prefer-message-ids.md b/docs/rules/prefer-message-ids.md index 4f1696ce..068e845f 100644 --- a/docs/rules/prefer-message-ids.md +++ b/docs/rules/prefer-message-ids.md @@ -1,6 +1,8 @@ -# Require using `messageId` instead of `message` to report rule violations (prefer-message-ids) +# Require using `messageId` instead of `message` to report rule violations (`eslint-plugin/prefer-message-ids`) -✔️ The `"extends": "plugin:eslint-plugin/recommended"` property in a configuration file enables this rule. +✅ This rule is enabled in the `recommended` config. + + When reporting a rule violation, it's preferred to provide the violation message with the `messageId` property instead of the `message` property. Message IDs provide the following benefits: diff --git a/docs/rules/prefer-object-rule.md b/docs/rules/prefer-object-rule.md index 2582d619..11cbe6df 100644 --- a/docs/rules/prefer-object-rule.md +++ b/docs/rules/prefer-object-rule.md @@ -1,8 +1,10 @@ -# Disallow function-style rules (prefer-object-rule) +# Disallow function-style rules (`eslint-plugin/prefer-object-rule`) -✔️ The `"extends": "plugin:eslint-plugin/recommended"` property in a configuration file enables this rule. +✅ This rule is enabled in the `recommended` config. -⚒️ The `--fix` option on the [command line](https://eslint.org/docs/user-guide/command-line-interface#--fix) can automatically fix some of the problems reported by this rule. +🔧 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix). + + Prior to ESLint v9, ESLint supported both [function-style](https://eslint.org/docs/developer-guide/working-with-rules-deprecated) and [object-style](https://eslint.org/docs/developer-guide/working-with-rules) rules. However, function-style rules have been deprecated since 2016, and do not support newer features like autofixing and suggestions. diff --git a/docs/rules/prefer-output-null.md b/docs/rules/prefer-output-null.md index e5e0a5de..43130ec3 100644 --- a/docs/rules/prefer-output-null.md +++ b/docs/rules/prefer-output-null.md @@ -1,8 +1,10 @@ -# Disallow invalid RuleTester test cases where the `output` matches the `code` (prefer-output-null) +# Disallow invalid RuleTester test cases where the `output` matches the `code` (`eslint-plugin/prefer-output-null`) -✔️ The `"extends": "plugin:eslint-plugin/recommended"` property in a configuration file enables this rule. +✅ This rule is enabled in the `recommended` config. -⚒️ The `--fix` option on the [command line](https://eslint.org/docs/user-guide/command-line-interface#--fix) can automatically fix some of the problems reported by this rule. +🔧 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix). + + Instead of repeating the test case `code`, using `output: null` is more concise and makes it easier to distinguish whether a test case provides an autofix. diff --git a/docs/rules/prefer-placeholders.md b/docs/rules/prefer-placeholders.md index 3f855f33..fea5c345 100644 --- a/docs/rules/prefer-placeholders.md +++ b/docs/rules/prefer-placeholders.md @@ -1,4 +1,6 @@ -# Require using placeholders for dynamic report messages (prefer-placeholders) +# Require using placeholders for dynamic report messages (`eslint-plugin/prefer-placeholders`) + + Report messages in rules can have placeholders surrounded by curly brackets. diff --git a/docs/rules/prefer-replace-text.md b/docs/rules/prefer-replace-text.md index df5ed146..8ae84763 100644 --- a/docs/rules/prefer-replace-text.md +++ b/docs/rules/prefer-replace-text.md @@ -1,4 +1,6 @@ -# Require using `replaceText()` instead of `replaceTextRange()` (prefer-replace-text) +# Require using `replaceText()` instead of `replaceTextRange()` (`eslint-plugin/prefer-replace-text`) + + ## Rule Details diff --git a/docs/rules/report-message-format.md b/docs/rules/report-message-format.md index 4190fb98..82f1abab 100644 --- a/docs/rules/report-message-format.md +++ b/docs/rules/report-message-format.md @@ -1,4 +1,6 @@ -# Enforce a consistent format for rule report messages (report-message-format) +# Enforce a consistent format for rule report messages (`eslint-plugin/report-message-format`) + + It is sometimes desirable to maintain consistent formatting for all report messages. For example, you might want to mandate that all report messages begin with a capital letter and end with a period. diff --git a/docs/rules/require-meta-docs-description.md b/docs/rules/require-meta-docs-description.md index dce7facc..398fc5bd 100644 --- a/docs/rules/require-meta-docs-description.md +++ b/docs/rules/require-meta-docs-description.md @@ -1,4 +1,6 @@ -# Require rules to implement a `meta.docs.description` property with the correct format (require-meta-docs-description) +# Require rules to implement a `meta.docs.description` property with the correct format (`eslint-plugin/require-meta-docs-description`) + + Defining a clear and consistent description for each rule helps developers understand what they're used for. diff --git a/docs/rules/require-meta-docs-url.md b/docs/rules/require-meta-docs-url.md index c3c4e47f..90176887 100644 --- a/docs/rules/require-meta-docs-url.md +++ b/docs/rules/require-meta-docs-url.md @@ -1,6 +1,8 @@ -# Require rules to implement a `meta.docs.url` property (require-meta-docs-url) +# Require rules to implement a `meta.docs.url` property (`eslint-plugin/require-meta-docs-url`) -⚒️ The `--fix` option on the [command line](https://eslint.org/docs/user-guide/command-line-interface#--fix) can automatically fix some of the problems reported by this rule. +🔧 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix). + + A rule can store the URL to its documentation page in `meta.docs.url`. This enables integration tools / IDEs / editors to conveniently provide the link to developers so that they can better understand the rule. diff --git a/docs/rules/require-meta-fixable.md b/docs/rules/require-meta-fixable.md index 37ce7cb7..b2edb0f0 100644 --- a/docs/rules/require-meta-fixable.md +++ b/docs/rules/require-meta-fixable.md @@ -1,6 +1,8 @@ -# Require rules to implement a `meta.fixable` property (require-meta-fixable) +# Require rules to implement a `meta.fixable` property (`eslint-plugin/require-meta-fixable`) -✔️ The `"extends": "plugin:eslint-plugin/recommended"` property in a configuration file enables this rule. +✅ This rule is enabled in the `recommended` config. + + ESLint requires fixable rules to specify a valid `meta.fixable` property (with value `code` or `whitespace`). diff --git a/docs/rules/require-meta-has-suggestions.md b/docs/rules/require-meta-has-suggestions.md index 3677db37..2f0fc5fc 100644 --- a/docs/rules/require-meta-has-suggestions.md +++ b/docs/rules/require-meta-has-suggestions.md @@ -1,8 +1,10 @@ -# Require suggestable rules to implement a `meta.hasSuggestions` property (require-meta-has-suggestions) +# Require suggestable rules to implement a `meta.hasSuggestions` property (`eslint-plugin/require-meta-has-suggestions`) -✔️ The `"extends": "plugin:eslint-plugin/recommended"` property in a configuration file enables this rule. +✅ This rule is enabled in the `recommended` config. -⚒️ The `--fix` option on the [command line](https://eslint.org/docs/user-guide/command-line-interface#--fix) can automatically fix some of the problems reported by this rule. +🔧 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix). + + A suggestable ESLint rule should specify the `meta.hasSuggestions` property with a value of `true`. This makes it easier for both humans and tooling to tell whether a rule provides suggestions. [As of ESLint 8](https://eslint.org/blog/2021/06/whats-coming-in-eslint-8.0.0#rules-with-suggestions-now-require-the-metahassuggestions-property), an exception will be thrown if a suggestable rule is missing this property. diff --git a/docs/rules/require-meta-schema.md b/docs/rules/require-meta-schema.md index c10e2d5e..9b6a5799 100644 --- a/docs/rules/require-meta-schema.md +++ b/docs/rules/require-meta-schema.md @@ -1,8 +1,10 @@ -# Require rules to implement a `meta.schema` property (require-meta-schema) +# Require rules to implement a `meta.schema` property (`eslint-plugin/require-meta-schema`) -✔️ The `"extends": "plugin:eslint-plugin/recommended"` property in a configuration file enables this rule. +✅ This rule is enabled in the `recommended` config. -💡 Some problems reported by this rule are manually fixable by editor [suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions). +💡 This rule is manually fixable by [editor suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions). + + Defining a schema for each rule allows eslint to validate that configuration options are passed correctly. Even when there are no options for a rule, a schema can still be defined as an empty array to validate that no data is mistakenly passed to the rule. diff --git a/docs/rules/require-meta-type.md b/docs/rules/require-meta-type.md index e72e1a60..2b9c9fb1 100644 --- a/docs/rules/require-meta-type.md +++ b/docs/rules/require-meta-type.md @@ -1,6 +1,8 @@ -# Require rules to implement a `meta.type` property (require-meta-type) +# Require rules to implement a `meta.type` property (`eslint-plugin/require-meta-type`) -✔️ The `"extends": "plugin:eslint-plugin/recommended"` property in a configuration file enables this rule. +✅ This rule is enabled in the `recommended` config. + + ESLint v5.9.0 introduces a new `--fix-type` option for the command line interface. This option allows users to filter the type of fixes applied when using `--fix`. diff --git a/docs/rules/test-case-property-ordering.md b/docs/rules/test-case-property-ordering.md index f6838cd7..826bd311 100644 --- a/docs/rules/test-case-property-ordering.md +++ b/docs/rules/test-case-property-ordering.md @@ -1,6 +1,8 @@ -# Require the properties of a test case to be placed in a consistent order (test-case-property-ordering) +# Require the properties of a test case to be placed in a consistent order (`eslint-plugin/test-case-property-ordering`) -⚒️ The `--fix` option on the [command line](https://eslint.org/docs/user-guide/command-line-interface#--fix) can automatically fix some of the problems reported by this rule. +🔧 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix). + + This rule enforces that the properties of RuleTester test cases are arranged in a consistent order. diff --git a/docs/rules/test-case-shorthand-strings.md b/docs/rules/test-case-shorthand-strings.md index ae1bbe35..3514fb70 100644 --- a/docs/rules/test-case-shorthand-strings.md +++ b/docs/rules/test-case-shorthand-strings.md @@ -1,6 +1,8 @@ -# Enforce consistent usage of shorthand strings for test cases with no options (test-case-shorthand-strings) +# Enforce consistent usage of shorthand strings for test cases with no options (`eslint-plugin/test-case-shorthand-strings`) -⚒️ The `--fix` option on the [command line](https://eslint.org/docs/user-guide/command-line-interface#--fix) can automatically fix some of the problems reported by this rule. +🔧 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix). + + When writing valid test cases for rules with `RuleTester`, one can optionally include a string as a test case instead of an object, if the the test case does not use any options. diff --git a/package.json b/package.json index 6459e7d3..db7b6175 100644 --- a/package.json +++ b/package.json @@ -10,13 +10,14 @@ }, "license": "MIT", "scripts": { - "generate-readme-table": "node build/generate-readme-table.js", "lint": "npm-run-all --continue-on-error --aggregate-output --parallel lint:*", - "lint:docs": "markdownlint '**/*.md'", + "lint:docs": "markdownlint \"**/*.md\"", + "lint:eslint-docs": "npm-run-all \"update:eslint-docs --check\"", "lint:js": "eslint --cache .", "lint:package-json": "npmPkgJsonLint .", "release": "release-it", - "test": "nyc --all --check-coverage --include lib mocha tests --recursive" + "test": "nyc --all --check-coverage --include lib mocha tests --recursive", + "update:eslint-docs": "eslint-doc-generator --rule-doc-section-include \"Rule Detail\" --ignore-config all --ignore-config rules --ignore-config rules-recommended --ignore-config tests --ignore-config tests-recommended" }, "files": [ "lib/" @@ -54,6 +55,7 @@ "eslint": "^8.23.0", "eslint-config-not-an-aardvark": "^2.1.0", "eslint-config-prettier": "^8.5.0", + "eslint-doc-generator": "^0.10.0", "eslint-plugin-eslint-comments": "^3.2.0", "eslint-plugin-eslint-plugin": "file:./", "eslint-plugin-markdown": "^3.0.0", diff --git a/tests/build/generate-readme-table.js b/tests/build/generate-readme-table.js deleted file mode 100644 index 5211921a..00000000 --- a/tests/build/generate-readme-table.js +++ /dev/null @@ -1,20 +0,0 @@ -'use strict'; - -const fs = require('node:fs'); -const path = require('node:path'); -const assert = require('chai').assert; - -describe('table in README.md', () => { - it('is up-to-date', () => { - const actualReadme = fs.readFileSync( - path.resolve(__dirname, '..', '..', 'README.md'), - 'utf8' - ); - const expectedReadme = require('../../build/generate-readme-table'); - - assert( - actualReadme === expectedReadme, - 'The table in README.md is out of date. Please use `npm run generate-readme-table` to update it.' - ); - }); -}); diff --git a/tests/lib/rule-setup.js b/tests/lib/rule-setup.js index 8a08c67d..1e8a4e68 100644 --- a/tests/lib/rule-setup.js +++ b/tests/lib/rule-setup.js @@ -6,51 +6,6 @@ const assert = require('chai').assert; const plugin = require('../..'); const RULE_NAMES = Object.keys(plugin.rules); -const RULE_NAMES_RECOMMENDED = new Set( - Object.keys(plugin.configs.recommended.rules) -); - -const MESSAGES = { - fixable: - '⚒️ The `--fix` option on the [command line](https://eslint.org/docs/user-guide/command-line-interface#--fix) can automatically fix some of the problems reported by this rule.', - configRecommended: - '✔️ The `"extends": "plugin:eslint-plugin/recommended"` property in a configuration file enables this rule.', - hasSuggestions: - '💡 Some problems reported by this rule are manually fixable by editor [suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions).', -}; - -/** - * @param {string} string - to operate on - * @returns the string with a capitalized first letter - */ -function capitalizeFirstLetter(string) { - return string.charAt(0).toUpperCase() + string.slice(1); -} - -/** - * Get list of named options from a JSON schema (used for rule schemas). - * @param {Object|Array} jsonSchema - the JSON schema to check - * @returns {String[]} list of named options - */ -function getAllNamedOptions(jsonSchema) { - if (!jsonSchema) { - return []; - } - - if (Array.isArray(jsonSchema)) { - return jsonSchema.flatMap((item) => getAllNamedOptions(item)); - } - - if (jsonSchema.items) { - return getAllNamedOptions(jsonSchema.items); - } - - if (jsonSchema.properties) { - return Object.keys(jsonSchema.properties); - } - - return []; -} describe('rule setup is correct', () => { it('should have a list of exported rules and rules directory that match', () => { @@ -120,121 +75,4 @@ describe('rule setup is correct', () => { .map((file) => file.replace('.md', '')) ); }); - - describe('rule documentation files', () => { - for (const ruleName of RULE_NAMES) { - const rule = plugin.rules[ruleName]; - const filePath = path.join( - __dirname, - '..', - '..', - 'docs', - 'rules', - `${ruleName}.md` - ); - const fileContents = readFileSync(filePath, 'utf8'); - const lines = fileContents.split('\n'); - - describe(ruleName, () => { - it('should have the right contents (title, notices, etc)', () => { - // Title - assert.strictEqual( - lines[0], - `# ${capitalizeFirstLetter( - rule.meta.docs.description - )} (${ruleName})`, - 'first line has rule description and name' - ); - assert.strictEqual(lines[1], '', 'second line is blank'); - - // Rule Details - assert.ok( - fileContents.includes('## Rule Details'), - 'includes "## Rule Details" header' - ); - - // Examples - assert.ok( - fileContents.includes( - 'Examples of **incorrect** code for this rule' - ), - 'includes incorrect examples' - ); - assert.ok( - fileContents.includes('Examples of **correct** code for this rule'), - 'includes correct examples' - ); - - // Decide which notices should be shown at the top of the doc. - const expectedNotices = []; - const unexpectedNotices = []; - if (RULE_NAMES_RECOMMENDED.has('eslint-plugin/' + ruleName)) { - expectedNotices.push('configRecommended'); - } else { - unexpectedNotices.push('configRecommended'); - } - if (rule.meta.fixable) { - expectedNotices.push('fixable'); - } else { - unexpectedNotices.push('fixable'); - } - if (rule.meta.hasSuggestions) { - expectedNotices.push('hasSuggestions'); - } else { - unexpectedNotices.push('hasSuggestions'); - } - - // Ensure that expected notices are present in the correct order. - let currentLineNumber = 1; - for (const expectedNotice of expectedNotices) { - assert.strictEqual(lines[currentLineNumber], ''); - assert.strictEqual( - lines[currentLineNumber + 1], - MESSAGES[expectedNotice] - ); - currentLineNumber += 2; - } - - // Ensure that unexpected notices are not present. - for (const unexpectedNotice of unexpectedNotices) { - assert.ok( - !fileContents.includes(MESSAGES[unexpectedNotice]), - 'does not include notice: ' + MESSAGES[unexpectedNotice] - ); - } - - // Check if the rule has configuration options. - if ( - (Array.isArray(rule.meta.schema) && rule.meta.schema.length > 0) || - (typeof rule.meta.schema === 'object' && - Object.keys(rule.meta.schema).length > 0) - ) { - // Should have a configuration section header: - assert.ok( - fileContents.includes('## Options'), - 'Should have an "## Options" section' - ); - - // Ensure all configuration options are mentioned. - for (const namedOption of getAllNamedOptions(rule.meta.schema)) { - assert.ok( - fileContents.includes(namedOption), - 'Should mention the `' + namedOption + '` option' - ); - } - } else { - // Should NOT have any options/config section headers: - assert.notOk( - fileContents.includes('# Options'), - 'Should not have an "Options" section' - ); - assert.notOk( - fileContents.includes('# Config'), - 'Should not have a "Config" section' - ); - } - }); - }); - } - }); });