From 35c5c4784d6b1013236aedc295def54d923660c8 Mon Sep 17 00:00:00 2001 From: Ben Perlmutter Date: Wed, 18 Jan 2023 22:57:40 -0500 Subject: [PATCH 01/10] docs: split rule docs Resolves #16648 --- docs/src/contribute/contribute-core-rule.md | 141 ++++++++++++++++++++ docs/src/extend/custom-rules.md | 118 +--------------- 2 files changed, 144 insertions(+), 115 deletions(-) create mode 100644 docs/src/contribute/contribute-core-rule.md diff --git a/docs/src/contribute/contribute-core-rule.md b/docs/src/contribute/contribute-core-rule.md new file mode 100644 index 00000000000..3f5cc78a095 --- /dev/null +++ b/docs/src/contribute/contribute-core-rule.md @@ -0,0 +1,141 @@ +--- +title: Contribute to Core Rules +eleventyNavigation: + key: contribute core rule + parent: contribute to eslint + title: Contribute to Core Rules + order: 11 +--- + +The ESLint core rules are the rules included in the ESLint package. + +## Rule Writing Documentation + +For full reference information on writing rules, refer to [Custom Rules](../extend/custom-rules). Both custom rules and core rules have the same structure and API. The primary difference between core and custom rules are: + +1. Core rules are included in the `eslint` package. +1. Core rules must adhere to the structure documented on this page. + +## Core Rule Structure + +Each core rule in ESLint has three files named with its identifier (for example, `no-extra-semi`). + +* in the `lib/rules` directory: a source file (for example, `no-extra-semi.js`) +* in the `tests/lib/rules` directory: a test file (for example, `no-extra-semi.js`) +* in the `docs/src/rules` directory: a Markdown documentation file (for example, `no-extra-semi.md`) + +**Important:** If you submit a **core** rule to the ESLint repository, you **must** follow some conventions explained below. + +Here is the basic format of the source file for a rule: + +```js +/** + * @fileoverview Rule to disallow unnecessary semicolons + * @author Nicholas C. Zakas + */ + +"use strict"; + +//------------------------------------------------------------------------------ +// Rule Definition +//------------------------------------------------------------------------------ + +/** @type {import('eslint').Rule.RuleModule} */ +module.exports = { + meta: { + type: "suggestion", + + docs: { + description: "disallow unnecessary semicolons", + recommended: true, + url: "https://eslint.org/docs/rules/no-extra-semi" + }, + fixable: "code", + schema: [] // no options + }, + create: function(context) { + return { + // callback functions + }; + } +}; +``` + +## Rule Unit Tests + +Each bundled rule for ESLint core must have a set of unit tests submitted with it to be accepted. The test file is named the same as the source file but lives in `tests/lib/`. For example, if the rule source file is `lib/rules/foo.js` then the test file should be `tests/lib/rules/foo.js`. + +ESLint provides the [`RuleTester`](../integrate/nodejs-api#ruletester) utility to make it easy to write tests for rules. + +## Performance Testing + +To keep the linting process efficient and unobtrusive, it is useful to verify the performance impact of new rules or modifications to existing rules. + +### Overall Performance + +When developing in the ESLint core repository, the `npm run perf` command gives a high-level overview of ESLint running time with all core rules enabled. + +```bash +$ git checkout main +Switched to branch 'main' + +$ npm run perf +CPU Speed is 2200 with multiplier 7500000 +Performance Run #1: 1394.689313ms +Performance Run #2: 1423.295351ms +Performance Run #3: 1385.09515ms +Performance Run #4: 1382.406982ms +Performance Run #5: 1409.68566ms +Performance budget ok: 1394.689313ms (limit: 3409.090909090909ms) + +$ git checkout my-rule-branch +Switched to branch 'my-rule-branch' + +$ npm run perf +CPU Speed is 2200 with multiplier 7500000 +Performance Run #1: 1443.736547ms +Performance Run #2: 1419.193291ms +Performance Run #3: 1436.018228ms +Performance Run #4: 1473.605485ms +Performance Run #5: 1457.455283ms +Performance budget ok: 1443.736547ms (limit: 3409.090909090909ms) +``` + +### Per-rule Performance + +ESLint has a built-in method to track performance of individual rules. Setting the `TIMING` environment variable will trigger the display, upon linting completion, of the ten longest-running rules, along with their individual running time (rule creation + rule execution) and relative performance impact as a percentage of total rule processing time (rule creation + rule execution). + +```bash +$ TIMING=1 eslint lib +Rule | Time (ms) | Relative +:-----------------------|----------:|--------: +no-multi-spaces | 52.472 | 6.1% +camelcase | 48.684 | 5.7% +no-irregular-whitespace | 43.847 | 5.1% +valid-jsdoc | 40.346 | 4.7% +handle-callback-err | 39.153 | 4.6% +space-infix-ops | 35.444 | 4.1% +no-undefined | 25.693 | 3.0% +no-shadow | 22.759 | 2.7% +no-empty-class | 21.976 | 2.6% +semi | 19.359 | 2.3% +``` + +To test one rule explicitly, combine the `--no-eslintrc`, and `--rule` options: + +```bash +$ TIMING=1 eslint --no-eslintrc --rule "quotes: [2, 'double']" lib +Rule | Time (ms) | Relative +:------|----------:|--------: +quotes | 18.066 | 100.0% +``` + +To see a longer list of results (more than 10), set the environment variable to another value such as `TIMING=50` or `TIMING=all`. + +## Rule Naming Conventions + +The rule naming conventions for ESLint are fairly simple: + +* If your rule is disallowing something, prefix it with `no-` such as `no-eval` for disallowing `eval()` and `no-debugger` for disallowing `debugger`. +* If your rule is enforcing the inclusion of something, use a short name without a special prefix. +* Use dashes between words. diff --git a/docs/src/extend/custom-rules.md b/docs/src/extend/custom-rules.md index 5da0b6722de..0a2c9e32896 100644 --- a/docs/src/extend/custom-rules.md +++ b/docs/src/extend/custom-rules.md @@ -8,50 +8,9 @@ eleventyNavigation: --- -**Note:** This page covers the most recent rule format for ESLint >= 3.0.0. There is also a [deprecated rule format](./custom-rules-deprecated). - -Each rule in ESLint has three files named with its identifier (for example, `no-extra-semi`). - -* in the `lib/rules` directory: a source file (for example, `no-extra-semi.js`) -* in the `tests/lib/rules` directory: a test file (for example, `no-extra-semi.js`) -* in the `docs/src/rules` directory: a Markdown documentation file (for example, `no-extra-semi.md`) - -**Important:** If you submit a **core** rule to the ESLint repository, you **must** follow some conventions explained below. - -Here is the basic format of the source file for a rule: +You can create custom rules to use with ESLint. You might want to create a custom rule if the [core rules](../rules/) do not cover your use case. -```js -/** - * @fileoverview Rule to disallow unnecessary semicolons - * @author Nicholas C. Zakas - */ - -"use strict"; - -//------------------------------------------------------------------------------ -// Rule Definition -//------------------------------------------------------------------------------ - -/** @type {import('eslint').Rule.RuleModule} */ -module.exports = { - meta: { - type: "suggestion", - - docs: { - description: "disallow unnecessary semicolons", - recommended: true, - url: "https://eslint.org/docs/rules/no-extra-semi" - }, - fixable: "code", - schema: [] // no options - }, - create: function(context) { - return { - // callback functions - }; - } -}; -``` +**Note:** This page covers the most recent rule format for ESLint >= 3.0.0. There is also a [deprecated rule format](./custom-rules-deprecated). ## Rule Basics @@ -712,82 +671,11 @@ You can access that code path objects with five events related to code paths. ## Rule Unit Tests -Each bundled rule for ESLint core must have a set of unit tests submitted with it to be accepted. The test file is named the same as the source file but lives in `tests/lib/`. For example, if the rule source file is `lib/rules/foo.js` then the test file should be `tests/lib/rules/foo.js`. - ESLint provides the [`RuleTester`](../integrate/nodejs-api#ruletester) utility to make it easy to write tests for rules. -## Performance Testing - -To keep the linting process efficient and unobtrusive, it is useful to verify the performance impact of new rules or modifications to existing rules. - -### Overall Performance - -When developing in the ESLint core repository, the `npm run perf` command gives a high-level overview of ESLint running time with all core rules enabled. - -```bash -$ git checkout main -Switched to branch 'main' - -$ npm run perf -CPU Speed is 2200 with multiplier 7500000 -Performance Run #1: 1394.689313ms -Performance Run #2: 1423.295351ms -Performance Run #3: 1385.09515ms -Performance Run #4: 1382.406982ms -Performance Run #5: 1409.68566ms -Performance budget ok: 1394.689313ms (limit: 3409.090909090909ms) - -$ git checkout my-rule-branch -Switched to branch 'my-rule-branch' - -$ npm run perf -CPU Speed is 2200 with multiplier 7500000 -Performance Run #1: 1443.736547ms -Performance Run #2: 1419.193291ms -Performance Run #3: 1436.018228ms -Performance Run #4: 1473.605485ms -Performance Run #5: 1457.455283ms -Performance budget ok: 1443.736547ms (limit: 3409.090909090909ms) -``` - -### Per-rule Performance - -ESLint has a built-in method to track performance of individual rules. Setting the `TIMING` environment variable will trigger the display, upon linting completion, of the ten longest-running rules, along with their individual running time (rule creation + rule execution) and relative performance impact as a percentage of total rule processing time (rule creation + rule execution). - -```bash -$ TIMING=1 eslint lib -Rule | Time (ms) | Relative -:-----------------------|----------:|--------: -no-multi-spaces | 52.472 | 6.1% -camelcase | 48.684 | 5.7% -no-irregular-whitespace | 43.847 | 5.1% -valid-jsdoc | 40.346 | 4.7% -handle-callback-err | 39.153 | 4.6% -space-infix-ops | 35.444 | 4.1% -no-undefined | 25.693 | 3.0% -no-shadow | 22.759 | 2.7% -no-empty-class | 21.976 | 2.6% -semi | 19.359 | 2.3% -``` - -To test one rule explicitly, combine the `--no-eslintrc`, and `--rule` options: - -```bash -$ TIMING=1 eslint --no-eslintrc --rule "quotes: [2, 'double']" lib -Rule | Time (ms) | Relative -:------|----------:|--------: -quotes | 18.066 | 100.0% -``` - -To see a longer list of results (more than 10), set the environment variable to another value such as `TIMING=50` or `TIMING=all`. - ## Rule Naming Conventions -The rule naming conventions for ESLint are fairly simple: - -* If your rule is disallowing something, prefix it with `no-` such as `no-eval` for disallowing `eval()` and `no-debugger` for disallowing `debugger`. -* If your rule is enforcing the inclusion of something, use a short name without a special prefix. -* Use dashes between words. +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/contribute-core-rule#rule-naming-conventions) documentation. ## Runtime Rules From adef32fd178bc1d8b3b2e6c79b3871da1d3bc990 Mon Sep 17 00:00:00 2001 From: Ben Perlmutter Date: Sat, 21 Jan 2023 15:13:59 -0500 Subject: [PATCH 02/10] Add todo --- docs/src/extend/custom-rules.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/src/extend/custom-rules.md b/docs/src/extend/custom-rules.md index 0a2c9e32896..08ae65d16c9 100644 --- a/docs/src/extend/custom-rules.md +++ b/docs/src/extend/custom-rules.md @@ -8,6 +8,8 @@ eleventyNavigation: --- +TODO: update the extend/index.md landing page and the contribute/index.md landing page w the new pages + You can create custom rules to use with ESLint. You might want to create a custom rule if the [core rules](../rules/) do not cover your use case. **Note:** This page covers the most recent rule format for ESLint >= 3.0.0. There is also a [deprecated rule format](./custom-rules-deprecated). From 7a6342da7917841732508175ee2cf0d39d4eb1af Mon Sep 17 00:00:00 2001 From: Ben Perlmutter Date: Sat, 21 Jan 2023 15:33:29 -0500 Subject: [PATCH 03/10] add page to IA --- docs/src/contribute/contribute-core-rule.md | 2 +- docs/src/contribute/governance.md | 2 +- docs/src/contribute/index.md | 4 ++++ 3 files changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/src/contribute/contribute-core-rule.md b/docs/src/contribute/contribute-core-rule.md index 3f5cc78a095..f2b6341ac41 100644 --- a/docs/src/contribute/contribute-core-rule.md +++ b/docs/src/contribute/contribute-core-rule.md @@ -4,7 +4,7 @@ eleventyNavigation: key: contribute core rule parent: contribute to eslint title: Contribute to Core Rules - order: 11 + order: 10 --- The ESLint core rules are the rules included in the ESLint package. diff --git a/docs/src/contribute/governance.md b/docs/src/contribute/governance.md index 53e5cda97af..563840a01dc 100644 --- a/docs/src/contribute/governance.md +++ b/docs/src/contribute/governance.md @@ -4,7 +4,7 @@ eleventyNavigation: key: governance parent: contribute to eslint title: Governance - order: 10 + order: 11 --- diff --git a/docs/src/contribute/index.md b/docs/src/contribute/index.md index 9a6c4078763..65ab8b97530 100644 --- a/docs/src/contribute/index.md +++ b/docs/src/contribute/index.md @@ -54,6 +54,10 @@ Have some extra time and want to contribute? This section talks about the proces We're always looking for contributions from the community. This section explains the requirements for pull requests and the process of contributing code. +## [Contribute to Core Rules](contribute-core-rule) + +This section explains how to add to the core rules of ESLint. + ## [Governance](governance) Describes the governance policy for ESLint, including the rights and privileges of individuals inside the project. From d8f34539c38558a58064507d2a2d4923bba90d20 Mon Sep 17 00:00:00 2001 From: Ben Perlmutter Date: Sat, 28 Jan 2023 14:39:40 -0500 Subject: [PATCH 04/10] Copy edits + remove TODO --- docs/src/extend/custom-rules.md | 2 -- docs/src/extend/index.md | 2 +- 2 files changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/src/extend/custom-rules.md b/docs/src/extend/custom-rules.md index 08ae65d16c9..0a2c9e32896 100644 --- a/docs/src/extend/custom-rules.md +++ b/docs/src/extend/custom-rules.md @@ -8,8 +8,6 @@ eleventyNavigation: --- -TODO: update the extend/index.md landing page and the contribute/index.md landing page w the new pages - You can create custom rules to use with ESLint. You might want to create a custom rule if the [core rules](../rules/) do not cover your use case. **Note:** This page covers the most recent rule format for ESLint >= 3.0.0. There is also a [deprecated rule format](./custom-rules-deprecated). diff --git a/docs/src/extend/index.md b/docs/src/extend/index.md index 0ca8c777529..581a9644133 100644 --- a/docs/src/extend/index.md +++ b/docs/src/extend/index.md @@ -23,7 +23,7 @@ You've developed custom rules for ESLint and you want to share them with the com ## [Custom Rules](custom-rules) -This section explains how to create and modify rules to use with ESLint. +This section explains how to create custom rules to use with ESLint. ## [Custom Formatters](custom-formatters) From 839cd685084b3dff95b62f4988efa558a2e88b95 Mon Sep 17 00:00:00 2001 From: Ben Perlmutter <57849986+bpmutter@users.noreply.github.com> Date: Tue, 31 Jan 2023 21:30:04 -0500 Subject: [PATCH 05/10] Update docs/src/contribute/contribute-core-rule.md Co-authored-by: Nitin Kumar --- docs/src/contribute/contribute-core-rule.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/contribute/contribute-core-rule.md b/docs/src/contribute/contribute-core-rule.md index f2b6341ac41..9cc068853bf 100644 --- a/docs/src/contribute/contribute-core-rule.md +++ b/docs/src/contribute/contribute-core-rule.md @@ -103,7 +103,7 @@ Performance budget ok: 1443.736547ms (limit: 3409.090909090909ms) ### Per-rule Performance -ESLint has a built-in method to track performance of individual rules. Setting the `TIMING` environment variable will trigger the display, upon linting completion, of the ten longest-running rules, along with their individual running time (rule creation + rule execution) and relative performance impact as a percentage of total rule processing time (rule creation + rule execution). +ESLint has a built-in method to track the performance of individual rules. Setting the `TIMING` environment variable will trigger the display, upon linting completion, of the ten longest-running rules, along with their individual running time (rule creation + rule execution) and relative performance impact as a percentage of total rule processing time (rule creation + rule execution). ```bash $ TIMING=1 eslint lib From bd63d17040e3da2e75224f3e62f21da4d6e7d195 Mon Sep 17 00:00:00 2001 From: Ben Perlmutter <57849986+bpmutter@users.noreply.github.com> Date: Sun, 5 Feb 2023 13:31:31 -0500 Subject: [PATCH 06/10] Apply suggestions from code review Co-authored-by: Nicholas C. Zakas Co-authored-by: Milos Djermanovic --- docs/src/contribute/contribute-core-rule.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/src/contribute/contribute-core-rule.md b/docs/src/contribute/contribute-core-rule.md index 9cc068853bf..682da9fbb7d 100644 --- a/docs/src/contribute/contribute-core-rule.md +++ b/docs/src/contribute/contribute-core-rule.md @@ -24,7 +24,7 @@ Each core rule in ESLint has three files named with its identifier (for example, * in the `tests/lib/rules` directory: a test file (for example, `no-extra-semi.js`) * in the `docs/src/rules` directory: a Markdown documentation file (for example, `no-extra-semi.md`) -**Important:** If you submit a **core** rule to the ESLint repository, you **must** follow some conventions explained below. +**Important:** If you submit a core rule to the ESLint repository, you **must** follow some conventions explained below. Here is the basic format of the source file for a rule: @@ -40,7 +40,7 @@ Here is the basic format of the source file for a rule: // Rule Definition //------------------------------------------------------------------------------ -/** @type {import('eslint').Rule.RuleModule} */ +/** @type {import('../shared/types').Rule} */ module.exports = { meta: { type: "suggestion", @@ -134,8 +134,8 @@ To see a longer list of results (more than 10), set the environment variable to ## Rule Naming Conventions -The rule naming conventions for ESLint are fairly simple: +The rule naming conventions for ESLint are as follows: -* If your rule is disallowing something, prefix it with `no-` such as `no-eval` for disallowing `eval()` and `no-debugger` for disallowing `debugger`. +* If your rule only disallows something, prefix it with `no-` such as `no-eval` for disallowing `eval()` and `no-debugger` for disallowing `debugger`. * If your rule is enforcing the inclusion of something, use a short name without a special prefix. * Use dashes between words. From 38626f89d8c812ec8335fe56cb61d516d1608e64 Mon Sep 17 00:00:00 2001 From: Ben Perlmutter <57849986+bpmutter@users.noreply.github.com> Date: Sun, 5 Feb 2023 13:34:08 -0500 Subject: [PATCH 07/10] Apply suggestions from code review Co-authored-by: Milos Djermanovic --- docs/src/contribute/contribute-core-rule.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/src/contribute/contribute-core-rule.md b/docs/src/contribute/contribute-core-rule.md index 682da9fbb7d..4a1d4612e25 100644 --- a/docs/src/contribute/contribute-core-rule.md +++ b/docs/src/contribute/contribute-core-rule.md @@ -11,12 +11,12 @@ The ESLint core rules are the rules included in the ESLint package. ## Rule Writing Documentation -For full reference information on writing rules, refer to [Custom Rules](../extend/custom-rules). Both custom rules and core rules have the same structure and API. The primary difference between core and custom rules are: +For full reference information on writing rules, refer to [Custom Rules](../extend/custom-rules). Both custom rules and core rules have the same API. The primary difference between core and custom rules are: 1. Core rules are included in the `eslint` package. -1. Core rules must adhere to the structure documented on this page. +1. Core rules must adhere to the conventions documented on this page. -## Core Rule Structure +## File Structure Each core rule in ESLint has three files named with its identifier (for example, `no-extra-semi`). From e4ed4547fba00d2eee0662878e5eac20d4a9e9b8 Mon Sep 17 00:00:00 2001 From: Ben Perlmutter Date: Sun, 5 Feb 2023 13:43:17 -0500 Subject: [PATCH 08/10] move rule performance testing to custom rules --- ...{contribute-core-rule.md => core-rules.md} | 35 ++----------------- docs/src/contribute/index.md | 2 +- docs/src/extend/custom-rules.md | 33 ++++++++++++++++- 3 files changed, 35 insertions(+), 35 deletions(-) rename docs/src/contribute/{contribute-core-rule.md => core-rules.md} (72%) diff --git a/docs/src/contribute/contribute-core-rule.md b/docs/src/contribute/core-rules.md similarity index 72% rename from docs/src/contribute/contribute-core-rule.md rename to docs/src/contribute/core-rules.md index 4a1d4612e25..f99de9abb17 100644 --- a/docs/src/contribute/contribute-core-rule.md +++ b/docs/src/contribute/core-rules.md @@ -71,7 +71,7 @@ ESLint provides the [`RuleTester`](../integrate/nodejs-api#ruletester) utility t To keep the linting process efficient and unobtrusive, it is useful to verify the performance impact of new rules or modifications to existing rules. -### Overall Performance +To learn how to profile the performance of individual rules, refer to [Profile Rule Performance](../extend/custom-rules#profile-rule-performance) in the custom rules documentation. When developing in the ESLint core repository, the `npm run perf` command gives a high-level overview of ESLint running time with all core rules enabled. @@ -101,41 +101,10 @@ Performance Run #5: 1457.455283ms Performance budget ok: 1443.736547ms (limit: 3409.090909090909ms) ``` -### Per-rule Performance - -ESLint has a built-in method to track the performance of individual rules. Setting the `TIMING` environment variable will trigger the display, upon linting completion, of the ten longest-running rules, along with their individual running time (rule creation + rule execution) and relative performance impact as a percentage of total rule processing time (rule creation + rule execution). - -```bash -$ TIMING=1 eslint lib -Rule | Time (ms) | Relative -:-----------------------|----------:|--------: -no-multi-spaces | 52.472 | 6.1% -camelcase | 48.684 | 5.7% -no-irregular-whitespace | 43.847 | 5.1% -valid-jsdoc | 40.346 | 4.7% -handle-callback-err | 39.153 | 4.6% -space-infix-ops | 35.444 | 4.1% -no-undefined | 25.693 | 3.0% -no-shadow | 22.759 | 2.7% -no-empty-class | 21.976 | 2.6% -semi | 19.359 | 2.3% -``` - -To test one rule explicitly, combine the `--no-eslintrc`, and `--rule` options: - -```bash -$ TIMING=1 eslint --no-eslintrc --rule "quotes: [2, 'double']" lib -Rule | Time (ms) | Relative -:------|----------:|--------: -quotes | 18.066 | 100.0% -``` - -To see a longer list of results (more than 10), set the environment variable to another value such as `TIMING=50` or `TIMING=all`. - ## Rule Naming Conventions The rule naming conventions for ESLint are as follows: +* Use dashes between words. * If your rule only disallows something, prefix it with `no-` such as `no-eval` for disallowing `eval()` and `no-debugger` for disallowing `debugger`. * If your rule is enforcing the inclusion of something, use a short name without a special prefix. -* Use dashes between words. diff --git a/docs/src/contribute/index.md b/docs/src/contribute/index.md index 65ab8b97530..49e617061d9 100644 --- a/docs/src/contribute/index.md +++ b/docs/src/contribute/index.md @@ -54,7 +54,7 @@ Have some extra time and want to contribute? This section talks about the proces We're always looking for contributions from the community. This section explains the requirements for pull requests and the process of contributing code. -## [Contribute to Core Rules](contribute-core-rule) +## [Contribute to Core Rules](core-rules) This section explains how to add to the core rules of ESLint. diff --git a/docs/src/extend/custom-rules.md b/docs/src/extend/custom-rules.md index 0a2c9e32896..e3a92a347b1 100644 --- a/docs/src/extend/custom-rules.md +++ b/docs/src/extend/custom-rules.md @@ -675,7 +675,7 @@ 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 that it could be clearer to apply to your custom rule. To learn more, refer to the [Core Rule Naming Conventions](../contribute/contribute-core-rule#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-rulse#rule-naming-conventions) documentation. ## Runtime Rules @@ -686,3 +686,34 @@ Runtime rules are written in the same format as all other rules. Create your rul 1. Place all of your runtime rules in the same directory (e.g., `eslint_rules`). 2. Create a [configuration file](../use/configure/) and specify your rule ID error level under the `rules` key. Your rule will not run unless it has a value of `"warn"` or `"error"` in the configuration file. 3. Run the [command line interface](../use/command-line-interface) using the `--rulesdir` option to specify the location of your runtime rules. + +## Profile Rule Performance + +ESLint has a built-in method to track the performance of individual rules. Setting the `TIMING` environment variable will trigger the display, upon linting completion, of the ten longest-running rules, along with their individual running time (rule creation + rule execution) and relative performance impact as a percentage of total rule processing time (rule creation + rule execution). + +```bash +$ TIMING=1 eslint lib +Rule | Time (ms) | Relative +:-----------------------|----------:|--------: +no-multi-spaces | 52.472 | 6.1% +camelcase | 48.684 | 5.7% +no-irregular-whitespace | 43.847 | 5.1% +valid-jsdoc | 40.346 | 4.7% +handle-callback-err | 39.153 | 4.6% +space-infix-ops | 35.444 | 4.1% +no-undefined | 25.693 | 3.0% +no-shadow | 22.759 | 2.7% +no-empty-class | 21.976 | 2.6% +semi | 19.359 | 2.3% +``` + +To test one rule explicitly, combine the `--no-eslintrc`, and `--rule` options: + +```bash +$ TIMING=1 eslint --no-eslintrc --rule "quotes: [2, 'double']" lib +Rule | Time (ms) | Relative +:------|----------:|--------: +quotes | 18.066 | 100.0% +``` + +To see a longer list of results (more than 10), set the environment variable to another value such as `TIMING=50` or `TIMING=all`. From 694f46a3a85fc1f776d756a951a5ac94b2d17766 Mon Sep 17 00:00:00 2001 From: Ben Perlmutter <57849986+bpmutter@users.noreply.github.com> Date: Tue, 7 Feb 2023 19:53:38 -0500 Subject: [PATCH 09/10] Apply suggestions from code review Co-authored-by: Nicholas C. Zakas Co-authored-by: Milos Djermanovic --- docs/src/contribute/core-rules.md | 2 +- docs/src/extend/custom-rules.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/src/contribute/core-rules.md b/docs/src/contribute/core-rules.md index f99de9abb17..5610c000e84 100644 --- a/docs/src/contribute/core-rules.md +++ b/docs/src/contribute/core-rules.md @@ -24,7 +24,7 @@ Each core rule in ESLint has three files named with its identifier (for example, * in the `tests/lib/rules` directory: a test file (for example, `no-extra-semi.js`) * in the `docs/src/rules` directory: a Markdown documentation file (for example, `no-extra-semi.md`) -**Important:** If you submit a core rule to the ESLint repository, you **must** follow some conventions explained below. +**Important:** If you submit a core rule to the ESLint repository, you **must** follow the conventions explained below. Here is the basic format of the source file for a rule: diff --git a/docs/src/extend/custom-rules.md b/docs/src/extend/custom-rules.md index e3a92a347b1..4ee59c7c5e4 100644 --- a/docs/src/extend/custom-rules.md +++ b/docs/src/extend/custom-rules.md @@ -675,7 +675,7 @@ 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 that it could be clearer to apply to your custom rule. To learn more, refer to the [Core Rule Naming Conventions](../contribute/core-rulse#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 From 84e8fddcc63567f74728267ea7b648cae2e5d791 Mon Sep 17 00:00:00 2001 From: Ben Perlmutter Date: Tue, 7 Feb 2023 20:04:04 -0500 Subject: [PATCH 10/10] add basic custom rule overview --- docs/src/extend/custom-rules.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/docs/src/extend/custom-rules.md b/docs/src/extend/custom-rules.md index 4ee59c7c5e4..62e5336df49 100644 --- a/docs/src/extend/custom-rules.md +++ b/docs/src/extend/custom-rules.md @@ -12,6 +12,28 @@ You can create custom rules to use with ESLint. You might want to create a custo **Note:** This page covers the most recent rule format for ESLint >= 3.0.0. There is also a [deprecated rule format](./custom-rules-deprecated). +Here's the basic format of a custom rule: + +```js +// customRule.js + +module.exports = { + meta: { + type: "suggestion", + docs: { + description: "Description of the rule", + }, + fixable: "code", + schema: [] // no options + }, + create: function(context) { + return { + // callback functions + }; + } +}; +``` + ## Rule Basics The source file for a rule exports an object with the following properties.