docs: automate docs with eslint-doc-generator

README.md

@@ -4,80 +4,57 @@ SonarJS rules for ESLint to detect bugs and suspicious patterns in your code.
 
 ## Rules
 
-### Bug Detection :bug:
-
-Rules in this category aim to find places in code which have a high chance of being bugs, i.e. don't work as intended.
-
-* All branches in a conditional structure should not have exactly the same implementation ([`no-all-duplicated-branches`])
-* Collection elements should not be replaced unconditionally ([`no-element-overwrite`])
-* Empty collections should not be accessed or iterated ([`no-empty-collection`])
-* Function calls should not pass extra arguments ([`no-extra-arguments`])
-* Related "if/else if" statements should not have the same condition ([`no-identical-conditions`])
-* Identical expressions should not be used on both sides of a binary operator ([`no-identical-expressions`])
-* Return values from functions without side effects should not be ignored ([`no-ignored-return`]) (*uses-types*)
-* Loops with at most one iteration should be refactored ([`no-one-iteration-loop`])
-* The output of functions that don't return anything should not be used ([`no-use-of-empty-return-value`])
-* Non-existent operators '=+', '=-' and '=!' should not be used ([`non-existent-operator`]) (:wrench: *fixable*)
-
-### Code Smell Detection :pig:
-
-Code Smells, or maintainability issues, are raised for places of code which might be costly to change in the future. These rules also help to keep the high code quality and readability. And finally some rules report issues on different suspicious code patters.
-
-* Cognitive Complexity of functions should not be too high ([`cognitive-complexity`])
-* "if ... else if" constructs should end with "else" clauses ([`elseif-without-else`]) (*disabled*)
-* "switch" statements should not have too many "case" clauses ([`max-switch-cases`])
-* Collapsible "if" statements should be merged ([`no-collapsible-if`])
-* Collection sizes and array length comparisons should make sense ([`no-collection-size-mischeck`]) (:wrench: *fixable*, *uses-types*)
-* String literals should not be duplicated ([`no-duplicate-string`])
-* Two branches in a conditional structure should not have exactly the same implementation ([`no-duplicated-branches`])
-* Boolean expressions should not be gratuitous ([`no-gratuitous-expressions`])
-* Functions should not have identical implementations ([`no-identical-functions`])
-* Boolean checks should not be inverted ([`no-inverted-boolean-check`]) (:wrench: *fixable*, *disabled*)
-* "switch" statements should not be nested ([`no-nested-switch`])
-* Template literals should not be nested ([`no-nested-template-literals`])
-* Boolean literals should not be redundant ([`no-redundant-boolean`])
-* Jump statements should not be redundant ([`no-redundant-jump`]) (:wrench: *fixable*)
-* Conditionals should start on new lines ([`no-same-line-conditional`]) (:wrench: *fixable*)
-* "switch" statements should have at least 3 "case" clauses ([`no-small-switch`])
-* Collection and array contents should be used ([`no-unused-collection`])
-* "catch" clauses should do more than rethrow ([`no-useless-catch`])
-* Local variables should not be declared and then immediately returned or thrown ([`prefer-immediate-return`]) (:wrench: *fixable*)
-* Object literal syntax should be used ([`prefer-object-literal`])
-* Return of boolean expressions should not be wrapped into an "if-then-else" statement ([`prefer-single-boolean-return`]) (:wrench: *fixable*)
-* A "while" loop should be used instead of a "for" loop ([`prefer-while`]) (:wrench: *fixable*)
-
-[`cognitive-complexity`]: ./docs/rules/cognitive-complexity.md
-[`elseif-without-else`]: ./docs/rules/elseif-without-else.md
-[`max-switch-cases`]: ./docs/rules/max-switch-cases.md
-[`no-all-duplicated-branches`]: ./docs/rules/no-all-duplicated-branches.md
-[`no-collapsible-if`]: ./docs/rules/no-collapsible-if.md
-[`no-collection-size-mischeck`]: ./docs/rules/no-collection-size-mischeck.md
-[`no-duplicate-string`]: ./docs/rules/no-duplicate-string.md
-[`no-duplicated-branches`]: ./docs/rules/no-duplicated-branches.md
-[`no-element-overwrite`]: ./docs/rules/no-element-overwrite.md
-[`no-empty-collection`]: ./docs/rules/no-empty-collection.md
-[`no-extra-arguments`]: ./docs/rules/no-extra-arguments.md
-[`no-gratuitous-expressions`]: ./docs/rules/no-gratuitous-expressions.md
-[`no-identical-conditions`]: ./docs/rules/no-identical-conditions.md
-[`no-identical-expressions`]: ./docs/rules/no-identical-expressions.md
-[`no-identical-functions`]: ./docs/rules/no-identical-functions.md
-[`no-ignored-return`]: ./docs/rules/no-ignored-return.md
-[`no-inverted-boolean-check`]: ./docs/rules/no-inverted-boolean-check.md
-[`no-nested-switch`]: ./docs/rules/no-nested-switch.md
-[`no-nested-template-literals`]: ./docs/rules/no-nested-template-literals.md
-[`no-one-iteration-loop`]: ./docs/rules/no-one-iteration-loop.md
-[`no-redundant-boolean`]: ./docs/rules/no-redundant-boolean.md
-[`no-redundant-jump`]: ./docs/rules/no-redundant-jump.md
-[`no-same-line-conditional`]: ./docs/rules/no-same-line-conditional.md
-[`no-small-switch`]: ./docs/rules/no-small-switch.md
-[`no-use-of-empty-return-value`]: ./docs/rules/no-use-of-empty-return-value.md
-[`no-unused-collection`]: ./docs/rules/no-unused-collection.md
-[`no-useless-catch`]: ./docs/rules/no-useless-catch.md
-[`non-existent-operator`]: ./docs/rules/non-existent-operator.md
-[`prefer-immediate-return`]: ./docs/rules/prefer-immediate-return.md
-[`prefer-object-literal`]: ./docs/rules/prefer-object-literal.md
-[`prefer-single-boolean-return`]: ./docs/rules/prefer-single-boolean-return.md
-[`prefer-while`]: ./docs/rules/prefer-while.md
+<!-- begin auto-generated rules list -->
+
+💼 Configurations enabled in.\
+🚫 Configurations disabled in.\
+✅ Set 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).
+
+### problem
+
+| Name                                                                       | Description                                                                             | 💼 | 🚫 | 🔧 | 💡 |
+| :------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------- | :- | :- | :- | :- |
+| [no-all-duplicated-branches](docs/rules/no-all-duplicated-branches.md)     | All branches in a conditional structure should not have exactly the same implementation | ✅  |    |    |    |
+| [no-collection-size-mischeck](docs/rules/no-collection-size-mischeck.md)   | Collection sizes and array length comparisons should make sense                         | ✅  |    |    | 💡 |
+| [no-duplicated-branches](docs/rules/no-duplicated-branches.md)             | Two branches in a conditional structure should not have exactly the same implementation | ✅  |    |    |    |
+| [no-element-overwrite](docs/rules/no-element-overwrite.md)                 | Collection elements should not be replaced unconditionally                              | ✅  |    |    |    |
+| [no-empty-collection](docs/rules/no-empty-collection.md)                   | Empty collections should not be accessed or iterated                                    | ✅  |    |    |    |
+| [no-extra-arguments](docs/rules/no-extra-arguments.md)                     | Function calls should not pass extra arguments                                          | ✅  |    |    |    |
+| [no-identical-conditions](docs/rules/no-identical-conditions.md)           | Related "if/else if" statements should not have the same condition                      | ✅  |    |    |    |
+| [no-identical-expressions](docs/rules/no-identical-expressions.md)         | Identical expressions should not be used on both sides of a binary operator             | ✅  |    |    |    |
+| [no-identical-functions](docs/rules/no-identical-functions.md)             | Functions should not have identical implementations                                     | ✅  |    |    |    |
+| [no-ignored-return](docs/rules/no-ignored-return.md)                       | Return values from functions without side effects should not be ignored                 | ✅  |    |    |    |
+| [no-one-iteration-loop](docs/rules/no-one-iteration-loop.md)               | Loops with at most one iteration should be refactored                                   | ✅  |    |    |    |
+| [no-same-line-conditional](docs/rules/no-same-line-conditional.md)         | Conditionals should start on new lines                                                  | ✅  |    |    | 💡 |
+| [no-unused-collection](docs/rules/no-unused-collection.md)                 | Collection and array contents should be used                                            | ✅  |    |    |    |
+| [no-use-of-empty-return-value](docs/rules/no-use-of-empty-return-value.md) | The output of functions that don't return anything should not be used                   | ✅  |    |    |    |
+| [non-existent-operator](docs/rules/non-existent-operator.md)               | Non-existent operators "=+", "=-" and "=!" should not be used                           | ✅  |    |    | 💡 |
+
+### suggestion
+
+| Name                                                                       | Description                                                                          | 💼 | 🚫 | 🔧 | 💡 |
+| :------------------------------------------------------------------------- | :----------------------------------------------------------------------------------- | :- | :- | :- | :- |
+| [cognitive-complexity](docs/rules/cognitive-complexity.md)                 | Cognitive Complexity of functions should not be too high                             | ✅  |    |    |    |
+| [elseif-without-else](docs/rules/elseif-without-else.md)                   | "if ... else if" constructs should end with "else" clauses                           |    | ✅  |    |    |
+| [max-switch-cases](docs/rules/max-switch-cases.md)                         | "switch" statements should not have too many "case" clauses                          | ✅  |    |    |    |
+| [no-collapsible-if](docs/rules/no-collapsible-if.md)                       | Collapsible "if" statements should be merged                                         | ✅  |    |    |    |
+| [no-duplicate-string](docs/rules/no-duplicate-string.md)                   | String literals should not be duplicated                                             | ✅  |    |    |    |
+| [no-gratuitous-expressions](docs/rules/no-gratuitous-expressions.md)       | Boolean expressions should not be gratuitous                                         | ✅  |    |    |    |
+| [no-inverted-boolean-check](docs/rules/no-inverted-boolean-check.md)       | Boolean checks should not be inverted                                                |    | ✅  | 🔧 | 💡 |
+| [no-nested-switch](docs/rules/no-nested-switch.md)                         | "switch" statements should not be nested                                             | ✅  |    |    |    |
+| [no-nested-template-literals](docs/rules/no-nested-template-literals.md)   | Template literals should not be nested                                               | ✅  |    |    |    |
+| [no-redundant-boolean](docs/rules/no-redundant-boolean.md)                 | Boolean literals should not be redundant                                             | ✅  |    |    |    |
+| [no-redundant-jump](docs/rules/no-redundant-jump.md)                       | Jump statements should not be redundant                                              | ✅  |    |    | 💡 |
+| [no-small-switch](docs/rules/no-small-switch.md)                           | "switch" statements should have at least 3 "case" clauses                            | ✅  |    |    |    |
+| [no-useless-catch](docs/rules/no-useless-catch.md)                         | "catch" clauses should do more than rethrow                                          | ✅  |    |    |    |
+| [prefer-immediate-return](docs/rules/prefer-immediate-return.md)           | Local variables should not be declared and then immediately returned or thrown       | ✅  |    | 🔧 |    |
+| [prefer-object-literal](docs/rules/prefer-object-literal.md)               | Object literal syntax should be used                                                 | ✅  |    |    |    |
+| [prefer-single-boolean-return](docs/rules/prefer-single-boolean-return.md) | Return of boolean expressions should not be wrapped into an "if-then-else" statement | ✅  |    |    | 💡 |
+| [prefer-while](docs/rules/prefer-while.md)                                 | A "while" loop should be used instead of a "for" loop                                | ✅  |    | 🔧 |    |
+
+<!-- end auto-generated rules list -->
 
 ## Prerequisites
 
@@ -121,15 +98,16 @@ npm install eslint-plugin-sonarjs -g         # or install globally
   }
 }
 ```
+
 * To enable all rules of this plugin, use `@typescript-eslint/parser` as a parser for ESLint ([like we do](https://github.com/SonarSource/eslint-plugin-sonarjs/blob/6e06d59a233e07b28fbbd6398e08b9b0c63b18f9/.eslintrc.js#L4)) and set the [parserOptions.project](https://github.com/typescript-eslint/typescript-eslint/tree/master/packages/parser#parseroptionsproject) option. Thanks to it, type information is available, which is beneficial or even essential for some rules.
 
 ## Available Configurations
 
-This plugin provides only `recommended` configuration. Almost all rules are activated in this profile with a few exceptions (check `disabled` tag in the rules list). `recommended` configuration activates rules with `error` severity. 
+This plugin provides only `recommended` configuration. Almost all rules are activated in this profile with a few exceptions (check `disabled` tag in the rules list). `recommended` configuration activates rules with `error` severity.
 
 ## ESLint and Sonar
 
-This plugin exposes to ESLint users a subset of JS/TS rules from Sonar-* products (aka [SonarJS](https://github.com/SonarSource/SonarJS)). We extracted the rules which are not available in ESLint core or other ESLint plugins to be beneficial for ESLint community. 
+This plugin exposes to ESLint users a subset of JS/TS rules from Sonar-* products (aka [SonarJS](https://github.com/SonarSource/SonarJS)). We extracted the rules which are not available in ESLint core or other ESLint plugins to be beneficial for ESLint community.
 
 If you are a [SonarQube](https://www.sonarqube.org) or [SonarCloud](https://sonarcloud.io) user, to lint your code locally, we suggest to use [SonarLint](https://www.sonarlint.org) IDE extension (available for VSCode, JetBrains IDEs and Eclipse). You can connect SonarLint to your SonarQube/SonarCloud project to synchronize rules configuration, issue statuses, etc.
 

docs/CONTRIBUTING.md

@@ -12,26 +12,26 @@ Report bugs and suggest improvements. If something doesn't work well for you or
 * Create a test file `<rule name>.test.ts` in `test/rules`.
 * Add the rule to `src/index.ts`.
 * In folder `docs/rules` create a rule documentation file `<rule name>.md`
-* In `README.md` add a reference to this documentation file.
+* Run `npm run update:eslint-docs` to update the `README.md` rules list and the rule doc header
 * Run [Ruling](#ruling) test.
 
 ## Testing
 
 To run unit tests:
 
-```
+```sh
 npm run test
 ```
 
 To run unit tests in watch mode:
 
-```
+```sh
 npm run test -- --watch
 ```
 
 And finally to run unit tests with coverage:
 
-```
+```sh
 npm run test -- --coverage
 ```
 

docs/rules/cognitive-complexity.md

@@ -1,5 +1,9 @@
 # cognitive-complexity
 
+💼 This rule is enabled in the ✅ `recommended` config.
+
+<!-- end auto-generated rule header -->
+
 Cognitive Complexity is a measure of how hard the control flow of a function is to understand. Functions with high Cognitive Complexity will be difficult to maintain.
 
 ## See

docs/rules/elseif-without-else.md

@@ -1,5 +1,9 @@
 # elseif-without-else
 
+🚫 This rule is _disabled_ in the ✅ `recommended` config.
+
+<!-- end auto-generated rule header -->
+
 This rule applies whenever an `if` statement is followed by one or more `else if` statements; the final `else if` should be followed by an `else` statement.
 
 The requirement for a final `else` statement is defensive programming.

docs/rules/max-switch-cases.md

@@ -1,4 +1,8 @@
-## max-switch-cases
+# max-switch-cases
+
+💼 This rule is enabled in the ✅ `recommended` config.
+
+<!-- end auto-generated rule header -->
 
 When `switch` statements have large sets of `case` clauses, it is usually an attempt to map two sets of data. A real map structure would be more readable and maintainable, and should be used instead.
 

docs/rules/no-all-duplicated-branches.md

@@ -1,5 +1,9 @@
 # no-all-duplicated-branches
 
+💼 This rule is enabled in the ✅ `recommended` config.
+
+<!-- end auto-generated rule header -->
+
 Having all branches in a `switch` or `if` chain with the same implementation is an error.
 Either a copy-paste error was made and something different should be executed,
 or there shouldn't be a `switch`/`if` chain at all. Note that this rule does not apply to

docs/rules/no-collapsible-if.md

@@ -1,5 +1,9 @@
 # no-collapsible-if
 
+💼 This rule is enabled in the ✅ `recommended` config.
+
+<!-- end auto-generated rule header -->
+
 Merging collapsible if statements increases the code's readability.
 
 ## Noncompliant Code Example

docs/rules/no-collection-size-mischeck.md

@@ -1,6 +1,10 @@
 # no-collection-size-mischeck
 
-:wrench: *fixable*
+💼 This rule is enabled in the ✅ `recommended` config.
+
+💡 This rule is manually fixable by [editor suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions).
+
+<!-- end auto-generated rule header -->
 
 The size of a collection and the length of an array are always greater than or equal to zero. So testing that a size or length is greater than or equal to zero doesn't make sense, since the result is always `true`. Similarly testing that it is less than zero will always return `false`. Perhaps the intent was to check the non-emptiness of the collection or array instead.
 

docs/rules/no-duplicate-string.md

@@ -1,4 +1,8 @@
 # no-duplicate-string
+
+💼 This rule is enabled in the ✅ `recommended` config.
+
+<!-- end auto-generated rule header -->
 Duplicated string literals make the process of refactoring error-prone, since you must be sure to update all occurrences.
 On the other hand, constants can be referenced from many places, but only need to be updated in a single place.
 

docs/rules/no-duplicated-branches.md

@@ -1,5 +1,9 @@
 # no-duplicated-branches
 
+💼 This rule is enabled in the ✅ `recommended` config.
+
+<!-- end auto-generated rule header -->
+
 Having two `case`s in a `switch` statement or two branches in an `if` chain with the same implementation is at best
 duplicate code, and at worst a coding error. If the same logic is truly needed for both instances, then in an `if`
 chain they should be combined, or for a `switch`, one should fall through to the other.

docs/rules/no-element-overwrite.md

@@ -1,5 +1,9 @@
 # no-element-overwrite
 
+💼 This rule is enabled in the ✅ `recommended` config.
+
+<!-- end auto-generated rule header -->
+
 It is highly suspicious when a value is saved for a key or index and then unconditionally overwritten. Such replacements are likely in error.
 
 ## Noncompliant Code Example

docs/rules/no-empty-collection.md

@@ -1,5 +1,9 @@
 # no-empty-collection
 
+💼 This rule is enabled in the ✅ `recommended` config.
+
+<!-- end auto-generated rule header -->
+
 When a collection is empty it makes no sense to access or iterate it. Doing so anyway is surely an error; either population was accidentally omitted or the developer doesn’t understand the situation.
 
 ## Noncompliant Code Example

docs/rules/no-extra-arguments.md

@@ -1,5 +1,9 @@
 # no-extra-arguments
 
+💼 This rule is enabled in the ✅ `recommended` config.
+
+<!-- end auto-generated rule header -->
+
 You can easily call a JavaScript function with more arguments than the function needs, but the extra arguments will be just ignored by function execution.
 
 ## Noncompliant Code Example