Add meta.docs for each rule (#246)

Eslint does support a documentation section in rule definitions. This section allows IDE plugins to display rule descriptions and directly link to the rule documentation. Details are documentad at: https://eslint.org/docs/developer-guide/working-with-rules#rule-basics

Co-authored-by: Daniel Graf Hoyos <[email protected]>

Author: yassin-kammoun-sonarsource

src/index.ts

@@ -17,50 +17,28 @@
  * along with this program; if not, write to the Free Software Foundation,
  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
  */
+import * as fs from 'fs';
+import * as path from 'path';
 import { TSESLint } from '@typescript-eslint/experimental-utils';
 
-const sonarjsRules: [string, TSESLint.Linter.RuleLevel][] = [
-  ['cognitive-complexity', 'error'],
-  ['elseif-without-else', 'off'],
-  ['generator-without-yield', 'error'],
-  ['max-switch-cases', 'error'],
-  ['no-all-duplicated-branches', 'error'],
-  ['no-collapsible-if', 'error'],
-  ['no-collection-size-mischeck', 'error'],
-  ['no-duplicate-string', 'error'],
-  ['no-duplicated-branches', 'error'],
-  ['no-element-overwrite', 'error'],
-  ['no-empty-collection', 'error'],
-  ['no-extra-arguments', 'error'],
-  ['no-gratuitous-expressions', 'error'],
-  ['no-identical-conditions', 'error'],
-  ['no-identical-functions', 'error'],
-  ['no-identical-expressions', 'error'],
-  ['no-inverted-boolean-check', 'error'],
-  ['no-nested-switch', 'error'],
-  ['no-nested-template-literals', 'error'],
-  ['no-one-iteration-loop', 'error'],
-  ['no-redundant-boolean', 'error'],
-  ['no-redundant-jump', 'error'],
-  ['no-same-line-conditional', 'error'],
-  ['no-small-switch', 'error'],
-  ['no-unused-collection', 'error'],
-  ['no-use-of-empty-return-value', 'error'],
-  ['no-useless-catch', 'error'],
-  ['non-existent-operator', 'error'],
-  ['prefer-immediate-return', 'error'],
-  ['prefer-object-literal', 'error'],
-  ['prefer-single-boolean-return', 'error'],
-  ['prefer-while', 'error'],
-];
+const sonarjsRules: string[] = fs
+  .readdirSync(path.join(__dirname, 'rules'))
+  .map(filename => filename.substr(0, filename.lastIndexOf('.ts')));
 
 const sonarjsRuleModules: { [key: string]: any } = {};
 
 const configs: { recommended: TSESLint.Linter.Config & { plugins: string[] } } = {
   recommended: { plugins: ['sonarjs'], rules: {} },
 };
 
-sonarjsRules.forEach(rule => (sonarjsRuleModules[rule[0]] = require(`./rules/${rule[0]}`)));
-sonarjsRules.forEach(rule => (configs.recommended.rules![`sonarjs/${rule[0]}`] = rule[1]));
+sonarjsRules.forEach(rule => {
+  sonarjsRuleModules[rule] = require(`./rules/${rule}`);
+  const {
+    meta: {
+      docs: { recommended },
+    },
+  } = sonarjsRuleModules[rule];
+  configs.recommended.rules![`sonarjs/${rule}`] = recommended === false ? 'off' : recommended;
+});
 
 export { sonarjsRuleModules as rules, configs };

src/rules/cognitive-complexity.ts

@@ -30,6 +30,7 @@ import {
   issueLocation,
 } from '../utils/locations';
 import { Rule } from '../utils/types';
+import docsUrl from '../utils/docs-url';
 
 const DEFAULT_THRESHOLD = 15;
 
@@ -47,6 +48,12 @@ type Options = [number, 'metric'];
 const rule: Rule.RuleModule<string, Options> = {
   meta: {
     type: 'suggestion',
+    docs: {
+      description: 'Cognitive Complexity of functions should not be too high',
+      category: 'Best Practices',
+      recommended: 'error',
+      url: docsUrl(__filename),
+    },
     schema: [
       { type: 'integer', minimum: 0 },
       {

src/rules/elseif-without-else.ts

@@ -21,10 +21,17 @@
 
 import { TSESTree } from '@typescript-eslint/experimental-utils';
 import { Rule } from '../utils/types';
+import docsUrl from '../utils/docs-url';
 
 const rule: Rule.RuleModule = {
   meta: {
     type: 'suggestion',
+    docs: {
+      description: '"if ... else if" constructs should end with "else" clauses',
+      category: 'Best Practices',
+      recommended: false,
+      url: docsUrl(__filename),
+    },
   },
   create(context: Rule.RuleContext) {
     return {

src/rules/generator-without-yield.ts

@@ -22,12 +22,19 @@
 import { TSESTree } from '@typescript-eslint/experimental-utils';
 import { getMainFunctionTokenLocation } from '../utils/locations';
 import { Rule } from '../utils/types';
+import docsUrl from '../utils/docs-url';
 
 const MESSAGE = 'Add a "yield" statement to this generator.';
 
 const rule: Rule.RuleModule = {
   meta: {
     type: 'problem',
+    docs: {
+      description: 'Generators should "yield" something',
+      category: 'Possible Errors',
+      recommended: 'error',
+      url: docsUrl(__filename),
+    },
   },
   create(context: Rule.RuleContext) {
     const yieldStack: number[] = [];

src/rules/max-switch-cases.ts

@@ -21,6 +21,7 @@
 
 import { TSESTree } from '@typescript-eslint/experimental-utils';
 import { Rule } from '../utils/types';
+import docsUrl from '../utils/docs-url';
 
 const MESSAGE =
   'Reduce the number of non-empty switch cases from {{numSwitchCases}} to at most {{maxSwitchCases}}.';
@@ -33,6 +34,12 @@ type Options = [number];
 const rule: Rule.RuleModule<string, Options> = {
   meta: {
     type: 'suggestion',
+    docs: {
+      description: '"switch" statements should not have too many "case" clauses',
+      category: 'Best Practices',
+      recommended: 'error',
+      url: docsUrl(__filename),
+    },
     schema: [
       {
         type: 'integer',

src/rules/no-all-duplicated-branches.ts

@@ -24,6 +24,7 @@ import { Rule } from '../utils/types';
 import { isIfStatement } from '../utils/nodes';
 import { areEquivalent } from '../utils/equivalence';
 import { collectIfBranches, collectSwitchBranches } from '../utils/conditions';
+import docsUrl from '../utils/docs-url';
 
 const MESSAGE =
   "Remove this conditional structure or edit its code blocks so that they're not all the same.";
@@ -33,6 +34,13 @@ const MESSAGE_CONDITIONAL_EXPRESSION =
 const rule: Rule.RuleModule = {
   meta: {
     type: 'problem',
+    docs: {
+      description:
+        'All branches in a conditional structure should not have exactly the same implementation',
+      category: 'Possible Errors',
+      recommended: 'error',
+      url: docsUrl(__filename),
+    },
   },
   create(context: Rule.RuleContext) {
     return {

src/rules/no-collapsible-if.ts

@@ -23,10 +23,17 @@ import { TSESTree } from '@typescript-eslint/experimental-utils';
 import { Rule } from '../utils/types';
 import { isIfStatement, isBlockStatement } from '../utils/nodes';
 import { report, issueLocation } from '../utils/locations';
+import docsUrl from '../utils/docs-url';
 
 const rule: Rule.RuleModule = {
   meta: {
     type: 'suggestion',
+    docs: {
+      description: 'Collapsible "if" statements should be merged',
+      category: 'Best Practices',
+      recommended: 'error',
+      url: docsUrl(__filename),
+    },
     schema: [
       {
         // internal parameter

src/rules/no-collection-size-mischeck.ts

@@ -22,13 +22,20 @@
 import { TSESTree } from '@typescript-eslint/experimental-utils';
 import { Rule } from '../utils/types';
 import { isRequiredParserServices, RequiredParserServices } from '../utils/parser-services';
+import docsUrl from '../utils/docs-url';
 
 const CollectionLike = ['Array', 'Map', 'Set', 'WeakMap', 'WeakSet'];
 const CollectionSizeLike = ['length', 'size'];
 
 const rule: Rule.RuleModule = {
   meta: {
     type: 'problem',
+    docs: {
+      description: 'Collection sizes and array length comparisons should make sense',
+      category: 'Possible Errors',
+      recommended: 'error',
+      url: docsUrl(__filename),
+    },
   },
   create(context: Rule.RuleContext) {
     const services = context.parserServices;

src/rules/no-duplicate-string.ts

@@ -21,6 +21,7 @@
 
 import { TSESTree } from '@typescript-eslint/experimental-utils';
 import { Rule } from '../utils/types';
+import docsUrl from '../utils/docs-url';
 
 // Number of times a literal must be duplicated to trigger an issue
 const DEFAULT_THRESHOLD = 3;
@@ -39,6 +40,12 @@ type Options = [number];
 const rule: Rule.RuleModule<string, Options> = {
   meta: {
     type: 'suggestion',
+    docs: {
+      description: 'String literals should not be duplicated',
+      category: 'Best Practices',
+      recommended: 'error',
+      url: docsUrl(__filename),
+    },
     schema: [{ type: 'integer', minimum: 2 }],
   },
 

src/rules/no-duplicated-branches.ts

@@ -25,13 +25,21 @@ import { isIfStatement, isBlockStatement } from '../utils/nodes';
 import { areEquivalent } from '../utils/equivalence';
 import { collectIfBranches, takeWithoutBreak, collectSwitchBranches } from '../utils/conditions';
 import { report, issueLocation } from '../utils/locations';
+import docsUrl from '../utils/docs-url';
 
 const MESSAGE =
   "This {{type}}'s code block is the same as the block for the {{type}} on line {{line}}.";
 
 const rule: Rule.RuleModule = {
   meta: {
     type: 'problem',
+    docs: {
+      description:
+        'Two branches in a conditional structure should not have exactly the same implementation',
+      category: 'Possible Errors',
+      recommended: 'error',
+      url: docsUrl(__filename),
+    },
     schema: [
       {
         // internal parameter