feat(eslint-plugin): Add rule triple-slash-reference

packages/eslint-plugin/README.md

@@ -177,6 +177,7 @@ Then you should add `airbnb` (or `airbnb-base`) to your `extends` section of `.e
 | [`@typescript-eslint/require-array-sort-compare`](./docs/rules/require-array-sort-compare.md)             | Enforce giving `compare` argument to `Array#sort`                                                                                                   |                    |          | :thought_balloon: |
 | [`@typescript-eslint/restrict-plus-operands`](./docs/rules/restrict-plus-operands.md)                     | When adding two variables, operands must both be of type number or of type string                                                                   |                    |          | :thought_balloon: |
 | [`@typescript-eslint/semi`](./docs/rules/semi.md)                                                         | Require or disallow semicolons instead of ASI                                                                                                       |                    | :wrench: |                   |
+| [`@typescript-eslint/triple-slash-reference`](./docs/rules/triple-slash-reference.md)                     | Sets preference level for triple slash directives versus ES6-style import declarations                                                                   |                    |          |                   |
 | [`@typescript-eslint/type-annotation-spacing`](./docs/rules/type-annotation-spacing.md)                   | Require consistent spacing around type annotations                                                                                                  | :heavy_check_mark: | :wrench: |                   |
 | [`@typescript-eslint/unbound-method`](./docs/rules/unbound-method.md)                                     | Enforces unbound methods are called with their expected scope                                                                                       |                    |          | :thought_balloon: |
 | [`@typescript-eslint/unified-signatures`](./docs/rules/unified-signatures.md)                             | Warns for any two overloads that could be unified into one by using a union or an optional/rest parameter                                           |                    |          |                   |

packages/eslint-plugin/docs/rules/triple-slash-reference.md

@@ -0,0 +1,58 @@
+# Sets preference level for triple slash directives versus ES6-style import declarations. (triple-slash-reference)
+
+Use of triple-slash reference type directives is discouraged in favor of the newer `import` style. This rule allows you to ban use of `/// <reference path="" />`, `/// <reference types="" />`, or `/// <reference lib="" />` directives.
+
+If you use the `no-triple-slash-reference` rule, consider using this rule instead.
+
+## Rule Details
+
+With `{ "path": "never", "types": "never", "lib": "never" }` options set, the following will all be **incorrect** usage:
+
+```ts
+/// <reference path="foo" />
+/// <reference types="bar" />
+/// <reference lib="baz" />
+```
+
+Examples of **incorrect** code for the `{ "types": "prefer-import" }` option. Note that these are only errors when **both** stlyes are used for the **same** module:
+
+```ts
+/// <reference types="foo" />
+import * as foo from 'foo';
+```
+
+```ts
+/// <reference types="foo" />
+import foo = require('foo');
+```
+
+With `{ "path": "always", "types": "always", "lib": "always" }` options set, the following will all be **correct** usage:
+
+```ts
+/// <reference path="foo" />
+/// <reference types="bar" />
+/// <reference lib="baz" />
+```
+
+Examples of **correct** code for the `{ "types": "prefer-import" }` option:
+
+```ts
+import * as foo from 'foo';
+```
+
+```ts
+import foo = require('foo');
+```
+
+## When To Use It
+
+If you want to ban use of one or all of the triple slash reference directives, or any time you might use triple-slash type reference directives and ES6 import declarations in the same file.
+
+## When Not To Use It
+
+If you want to use all flavors of triple slash reference directives.
+
+## Compatibility
+
+- TSLint: [no-reference](http://palantir.github.io/tslint/rules/no-reference/)
+- TSLint: [no-reference-import](https://palantir.github.io/tslint/rules/no-reference-import/)

packages/eslint-plugin/src/rules/index.ts

@@ -52,6 +52,7 @@ import promiseFunctionAsync from './promise-function-async';
 import requireArraySortCompare from './require-array-sort-compare';
 import restrictPlusOperands from './restrict-plus-operands';
 import semi from './semi';
+import tripleSlashReference from './triple-slash-reference';
 import typeAnnotationSpacing from './type-annotation-spacing';
 import unboundMethod from './unbound-method';
 import unifiedSignatures from './unified-signatures';
@@ -111,6 +112,7 @@ export default {
   'require-array-sort-compare': requireArraySortCompare,
   'restrict-plus-operands': restrictPlusOperands,
   semi: semi,
+  'triple-slash-reference': tripleSlashReference,
   'type-annotation-spacing': typeAnnotationSpacing,
   'unbound-method': unboundMethod,
   'unified-signatures': unifiedSignatures,

packages/eslint-plugin/src/rules/no-triple-slash-reference.ts

@@ -11,7 +11,7 @@ export default util.createRule({
     },
     schema: [],
     messages: {
-      tripleSlashReference: 'Do not use a triple slash reference.',
+      noTripleSlashReference: 'Do not use a triple slash reference.',
     },
   },
   defaultOptions: [],
@@ -30,7 +30,7 @@ export default util.createRule({
           if (referenceRegExp.test(comment.value)) {
             context.report({
               node: comment,
-              messageId: 'tripleSlashReference',
+              messageId: 'noTripleSlashReference',
             });
           }
         });

packages/eslint-plugin/src/rules/triple-slash-reference.ts

@@ -0,0 +1,129 @@
+import * as util from '../util';
+import {
+  Literal,
+  Node,
+  TSExternalModuleReference,
+} from '@typescript-eslint/typescript-estree/dist/ts-estree/ts-estree';
+import { TSESTree } from '@typescript-eslint/typescript-estree';
+
+type Options = [
+  {
+    lib?: 'always' | 'never';
+    path?: 'always' | 'never';
+    types?: 'always' | 'never' | 'prefer-import';
+  }
+];
+type MessageIds = 'tripleSlashReference';
+
+export default util.createRule<Options, MessageIds>({
+  name: 'triple-slash-reference',
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        'Sets preference level for triple slash directives versus ES6-style import declarations',
+      category: 'Best Practices',
+      recommended: false,
+    },
+    messages: {
+      tripleSlashReference:
+        'Do not use a triple slash reference for {{module}}, use `import` style instead.',
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          lib: {
+            enum: ['always', 'never'],
+          },
+          path: {
+            enum: ['always', 'never'],
+          },
+          types: {
+            enum: ['always', 'never', 'prefer-import'],
+          },
+        },
+        additionalProperties: false,
+      },
+    ],
+  },
+  defaultOptions: [
+    {
+      lib: 'always',
+      path: 'never',
+      types: 'prefer-import',
+    },
+  ],
+  create(context, [{ lib, path, types }]) {
+    let programNode: Node;
+    const sourceCode = context.getSourceCode();
+    const references: ({
+      comment: TSESTree.Comment;
+      importName: string;
+    })[] = [];
+
+    function hasMatchingReference(source: Literal) {
+      references.forEach(reference => {
+        if (reference.importName === source.value) {
+          context.report({
+            node: reference.comment,
+            messageId: 'tripleSlashReference',
+            data: {
+              module: reference.importName,
+            },
+          });
+        }
+      });
+    }
+    return {
+      ImportDeclaration(node) {
+        if (programNode) {
+          const source = node.source as Literal;
+          hasMatchingReference(source);
+        }
+      },
+      TSImportEqualsDeclaration(node) {
+        if (programNode) {
+          const source = (node.moduleReference as TSExternalModuleReference)
+            .expression as Literal;
+          hasMatchingReference(source);
+        }
+      },
+      Program(node) {
+        if (lib === 'always' && path === 'always' && types == 'always') {
+          return;
+        }
+        programNode = node;
+        const referenceRegExp = /^\/\s*<reference\s*(types|path|lib)\s*=\s*["|'](.*)["|']/;
+        const commentsBefore = sourceCode.getCommentsBefore(programNode);
+
+        commentsBefore.forEach(comment => {
+          if (comment.type !== 'Line') {
+            return;
+          }
+          const referenceResult = referenceRegExp.exec(comment.value);
+
+          if (referenceResult) {
+            if (
+              (referenceResult[1] === 'types' && types === 'never') ||
+              (referenceResult[1] === 'path' && path === 'never') ||
+              (referenceResult[1] === 'lib' && lib === 'never')
+            ) {
+              context.report({
+                node: comment,
+                messageId: 'tripleSlashReference',
+                data: {
+                  module: referenceResult[2],
+                },
+              });
+              return;
+            }
+            if (referenceResult[1] === 'types' && types === 'prefer-import') {
+              references.push({ comment, importName: referenceResult[2] });
+            }
+          }
+        });
+      },
+    };
+  },
+});

packages/eslint-plugin/tests/rules/no-triple-slash-reference.test.ts

@@ -22,7 +22,7 @@ let a
       code: '/// <reference path="Animal" />',
       errors: [
         {
-          messageId: 'tripleSlashReference',
+          messageId: 'noTripleSlashReference',
           line: 1,
           column: 1,
         },
@@ -36,7 +36,7 @@ let a
       parser: '@typescript-eslint/parser',
       errors: [
         {
-          messageId: 'tripleSlashReference',
+          messageId: 'noTripleSlashReference',
           line: 2,
           column: 1,
         },

packages/eslint-plugin/tests/rules/triple-slash-reference.test.ts

@@ -0,0 +1,122 @@
+import rule from '../../src/rules/triple-slash-reference';
+import { RuleTester } from '../RuleTester';
+
+const ruleTester = new RuleTester({
+  parserOptions: {
+    sourceType: 'module',
+  },
+  parser: '@typescript-eslint/parser',
+});
+
+ruleTester.run('triple-slash-reference', rule, {
+  valid: [
+    {
+      code: `
+      /// <reference path="foo" />
+      import * as foo from "foo"
+      `,
+      options: [{ path: 'always' }],
+    },
+    {
+      code: `
+      /// <reference types="foo" />
+      import * as foo from "foo"
+      `,
+      options: [{ types: 'always' }],
+    },
+    {
+      code: `
+      /// <reference lib="foo" />
+      import * as foo from "foo"
+      `,
+      options: [{ lib: 'always' }],
+    },
+    {
+      code: `
+      import * as foo from "foo"
+      `,
+      options: [{ path: 'never' }],
+    },
+    {
+      code: `
+      import * as foo from "foo"
+      `,
+      options: [{ types: 'never' }],
+    },
+    {
+      code: `
+      import * as foo from "foo"
+      `,
+      options: [{ lib: 'never' }],
+    },
+    {
+      code: `
+      import * as foo from "foo"
+      `,
+      options: [{ types: 'prefer-import' }],
+    },
+  ],
+  invalid: [
+    {
+      code: `
+/// <reference types="foo" />
+import * as foo from "foo"
+      `,
+      options: [{ types: 'prefer-import' }],
+      errors: [
+        {
+          messageId: 'tripleSlashReference',
+          line: 2,
+          column: 1,
+        },
+      ],
+    },
+    {
+      code: `
+/// <reference types="foo" />
+import foo = require("foo");
+      `,
+      options: [{ types: 'prefer-import' }],
+      errors: [
+        {
+          messageId: 'tripleSlashReference',
+          line: 2,
+          column: 1,
+        },
+      ],
+    },
+    {
+      code: `/// <reference path="foo" />`,
+      options: [{ path: 'never' }],
+      errors: [
+        {
+          messageId: 'tripleSlashReference',
+          line: 1,
+          column: 1,
+        },
+      ],
+    },
+    {
+      code: `/// <reference types="foo" />`,
+      options: [{ types: 'never' }],
+      errors: [
+        {
+          messageId: 'tripleSlashReference',
+          line: 1,
+          column: 1,
+        },
+      ],
+    },
+    {
+      code: `/// <reference lib="foo" />`,
+      options: [{ lib: 'never' }],
+      errors: [
+        {
+          messageId: 'tripleSlashReference',
+          line: 1,
+          column: 1,
+        },
+      ],
+    },
+  ],
+});