feat(eslint-plugin): create ban-ts-comment rule (typescript-eslint#1361)

G-Rath · bradzacher · commit 2a83d138a966 · 2020-01-20T16:56:00.000-08:00
diff --git a/.cspell.json b/.cspell.json
@@ -61,6 +61,7 @@
     "estree",
     "linebreaks",
     "necroing",
+    "nocheck",
     "nullish",
     "parameterised",
     "performant",
diff --git a/packages/eslint-plugin/README.md b/packages/eslint-plugin/README.md
@@ -98,7 +98,7 @@ Pro Tip: For larger codebases you may want to consider splitting our linting int
 | [`@typescript-eslint/adjacent-overload-signatures`](./docs/rules/adjacent-overload-signatures.md)               | Require that member overloads be consecutive                                                                                                        | :heavy_check_mark: |          |                   |
 | [`@typescript-eslint/array-type`](./docs/rules/array-type.md)                                                   | Requires using either `T[]` or `Array<T>` for arrays                                                                                                |                    | :wrench: |                   |
 | [`@typescript-eslint/await-thenable`](./docs/rules/await-thenable.md)                                           | Disallows awaiting a value that is not a Thenable                                                                                                   | :heavy_check_mark: |          | :thought_balloon: |
-| [`@typescript-eslint/ban-ts-ignore`](./docs/rules/ban-ts-ignore.md)                                             | Bans “// @ts-ignore” comments from being used                                                                                                       | :heavy_check_mark: |          |                   |
+| [`@typescript-eslint/ban-ts-comment`](./docs/rules/ban-ts-comment.md)                                           | Bans `// @ts-<directive>` comments from being used                                                                                                  |                    |          |                   |
 | [`@typescript-eslint/ban-types`](./docs/rules/ban-types.md)                                                     | Bans specific types from being used                                                                                                                 | :heavy_check_mark: | :wrench: |                   |
 | [`@typescript-eslint/consistent-type-assertions`](./docs/rules/consistent-type-assertions.md)                   | Enforces consistent usage of type assertions                                                                                                        | :heavy_check_mark: |          |                   |
 | [`@typescript-eslint/consistent-type-definitions`](./docs/rules/consistent-type-definitions.md)                 | Consistent with type definition either `interface` or `type`                                                                                        |                    | :wrench: |                   |
diff --git a/packages/eslint-plugin/docs/rules/ban-ts-comment.md b/packages/eslint-plugin/docs/rules/ban-ts-comment.md
@@ -0,0 +1,65 @@
+# Bans `// @ts-<directive>` comments from being used (`ban-ts-comment`)
+
+TypeScript provides several directive comments that can be used to alter how it processes files.
+Using these to suppress TypeScript Compiler Errors reduces the effectiveness of TypeScript overall.
+
+The directive comments supported by TypeScript are:
+
+```
+// @ts-ignore
+// @ts-nocheck
+// @ts-check
+```
+
+## Rule Details
+
+This rule lets you set which directive comments you want to allow in your codebase.
+By default, only `@ts-check` is allowed, as it enables rather then suppresses errors.
+
+The configuration looks like this:
+
+```
+interface Options {
+  'ts-ignore'?: boolean;
+  'ts-nocheck'?: boolean;
+  'ts-check'?: boolean;
+}
+
+const defaultOptions: Options = {
+  'ts-ignore': true,
+  'ts-nocheck': true,
+  'ts-check': false
+}
+```
+
+A value of `true` for a particular directive means that this rule will report if it finds any usage of said directive.
+
+For example, with the defaults above the following patterns are considered warnings:
+
+```ts
+if (false) {
+  // @ts-ignore: Unreachable code error
+  console.log('hello');
+}
+```
+
+The following patterns are not warnings:
+
+```ts
+if (false) {
+  // Compiler warns about unreachable code error
+  console.log('hello');
+}
+```
+
+## When Not To Use It
+
+If you want to use all of the TypeScript directives.
+
+## Further Reading
+
+- TypeScript [Type Checking JavaScript Files](https://www.typescriptlang.org/docs/handbook/type-checking-javascript-files.html)
+
+## Compatibility
+
+- TSLint: [ban-ts-ignore](https://palantir.github.io/tslint/rules/ban-ts-ignore/)
diff --git a/packages/eslint-plugin/docs/rules/ban-ts-ignore.md b/packages/eslint-plugin/docs/rules/ban-ts-ignore.md
@@ -1,5 +1,7 @@
 # Bans “// @ts-ignore” comments from being used (`ban-ts-ignore`)
 
+This rule has been deprecated in favor of [`ban-ts-comment`](./ban-ts-comment.md)
+
 Suppressing TypeScript Compiler Errors can be hard to discover.
 
 ## Rule Details
diff --git a/packages/eslint-plugin/src/configs/all.json b/packages/eslint-plugin/src/configs/all.json
@@ -4,7 +4,7 @@
     "@typescript-eslint/adjacent-overload-signatures": "error",
     "@typescript-eslint/array-type": "error",
     "@typescript-eslint/await-thenable": "error",
-    "@typescript-eslint/ban-ts-ignore": "error",
+    "@typescript-eslint/ban-ts-comment": "error",
     "@typescript-eslint/ban-types": "error",
     "brace-style": "off",
     "@typescript-eslint/brace-style": "error",
diff --git a/packages/eslint-plugin/src/rules/ban-ts-comment.ts b/packages/eslint-plugin/src/rules/ban-ts-comment.ts
@@ -0,0 +1,82 @@
+import * as util from '../util';
+
+interface Options {
+  'ts-ignore'?: boolean;
+  'ts-nocheck'?: boolean;
+  'ts-check'?: boolean;
+}
+
+const defaultOptions: [Options] = [
+  {
+    'ts-ignore': true,
+    'ts-nocheck': true,
+    'ts-check': false,
+  },
+];
+
+type MessageIds = 'tsDirectiveComment';
+
+export default util.createRule<[Options], MessageIds>({
+  name: 'ban-ts-comment',
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Bans `// @ts-<directive>` comments from being used',
+      category: 'Best Practices',
+      recommended: false,
+    },
+    messages: {
+      tsDirectiveComment:
+        'Do not use "// @ts-{directive}" because it alters compilation errors.',
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          'ts-ignore': {
+            type: 'boolean',
+            default: true,
+          },
+          'ts-nocheck': {
+            type: 'boolean',
+            default: true,
+          },
+          'ts-check': {
+            type: 'boolean',
+            default: false,
+          },
+        },
+        additionalProperties: false,
+      },
+    ],
+  },
+  defaultOptions,
+  create(context, [options]) {
+    const tsCommentRegExp = /^\/*\s*@ts-(ignore|check|nocheck)/;
+    const sourceCode = context.getSourceCode();
+
+    return {
+      Program(): void {
+        const comments = sourceCode.getAllComments();
+
+        comments.forEach(comment => {
+          if (comment.type !== 'Line') {
+            return;
+          }
+
+          const [, directive] = tsCommentRegExp.exec(comment.value) ?? [];
+
+          const fullDirective = `ts-${directive}` as keyof Options;
+
+          if (options[fullDirective]) {
+            context.report({
+              data: { directive },
+              node: comment,
+              messageId: 'tsDirectiveComment',
+            });
+          }
+        });
+      },
+    };
+  },
+});
diff --git a/packages/eslint-plugin/src/rules/ban-ts-ignore.ts b/packages/eslint-plugin/src/rules/ban-ts-ignore.ts
@@ -14,6 +14,8 @@ export default util.createRule({
       tsIgnoreComment:
         'Do not use "// @ts-ignore" comments because they suppress compilation errors.',
     },
+    deprecated: true,
+    replacedBy: ['@typescript-eslint/ban-ts-comment'],
   },
   defaultOptions: [],
   create(context) {
diff --git a/packages/eslint-plugin/src/rules/index.ts b/packages/eslint-plugin/src/rules/index.ts
@@ -2,6 +2,7 @@ import adjacentOverloadSignatures from './adjacent-overload-signatures';
 import arrayType from './array-type';
 import awaitThenable from './await-thenable';
 import banTsIgnore from './ban-ts-ignore';
+import banTsComment from './ban-ts-comment';
 import banTypes from './ban-types';
 import braceStyle from './brace-style';
 import camelcase from './camelcase';
@@ -85,6 +86,7 @@ export default {
   'array-type': arrayType,
   'await-thenable': awaitThenable,
   'ban-ts-ignore': banTsIgnore,
+  'ban-ts-comment': banTsComment,
   'ban-types': banTypes,
   'brace-style': braceStyle,
   camelcase: camelcase,
diff --git a/packages/eslint-plugin/tests/rules/ban-ts-comment.test.ts b/packages/eslint-plugin/tests/rules/ban-ts-comment.test.ts
