docs: added docs for no-reference-import

packages/eslint-plugin/README.md

@@ -155,6 +155,7 @@ Then you should add `airbnb` (or `airbnb-base`) to your `extends` section of `.e
 | [`@typescript-eslint/no-non-null-assertion`](./docs/rules/no-non-null-assertion.md)                       | Disallows non-null assertions using the `!` postfix operator                                                                                        | :heavy_check_mark: |          |                   |
 | [`@typescript-eslint/no-object-literal-type-assertion`](./docs/rules/no-object-literal-type-assertion.md) | Forbids an object literal to appear in a type assertion expression                                                                                  | :heavy_check_mark: |          |                   |
 | [`@typescript-eslint/no-parameter-properties`](./docs/rules/no-parameter-properties.md)                   | Disallow the use of parameter properties in class constructors                                                                                      | :heavy_check_mark: |          |                   |
+| [`@typescript-eslint/no-reference-import`](./docs/rules/no-reference-import.md)                           | Disallow simultaneous use of `/// <reference type="" />` comments and ES6 style imports for the same module                                         |                    |          |                   |
 | [`@typescript-eslint/no-require-imports`](./docs/rules/no-require-imports.md)                             | Disallows invocation of `require()`                                                                                                                 |                    |          |                   |
 | [`@typescript-eslint/no-this-alias`](./docs/rules/no-this-alias.md)                                       | Disallow aliasing `this`                                                                                                                            |                    |          |                   |
 | [`@typescript-eslint/no-triple-slash-reference`](./docs/rules/no-triple-slash-reference.md)               | Disallow `/// <reference path="" />` comments                                                                                                       | :heavy_check_mark: |          |                   |

packages/eslint-plugin/docs/rules/no-reference-import.md

@@ -0,0 +1,37 @@
+# Disallow simultaneous use of `/// <reference type="" />` comments and ES6 style imports for the same module. (no-reference-import)
+
+Use of triple-slash directives is discouraged in favor of the newer `import` style. In cases where both styles might occur, this rule prevents use of triple-slash references for modules which are otherwise imported.
+
+Use `no-triple-slash-reference` instead if you intend to ban triple slash directives entirely.
+
+## Rule Details
+
+Examples of **incorrect** code for this rule:
+
+```ts
+/// <reference types="foo" />
+import * as foo from 'foo';
+```
+
+```ts
+/// <reference types="foo" />
+import foo = require('foo');
+```
+
+Examples of **correct** code for this rule:
+
+```ts
+import * as foo from 'foo';
+```
+
+```ts
+import foo = require('foo');
+```
+
+## When To Use It
+
+Any time you might use triple-slash directives and ES6 import declarations in the same file.
+
+## When Not To Use It
+
+If you intend to ban triple slash directives entirely.

packages/eslint-plugin/src/rules/no-reference-import.ts

@@ -12,9 +12,9 @@ export default util.createRule({
     type: 'suggestion',
     docs: {
       description:
-        'Disallow `/// <reference type="" />` comments when already using an import declaration.',
+        'Disallow simultaneous use of `/// <reference type="" />` comments and ES6 style imports for the same module',
       category: 'Best Practices',
-      recommended: 'error',
+      recommended: false,
     },
     schema: [],
     messages: {

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

@@ -13,13 +13,13 @@ ruleTester.run('no-reference-import', rule, {
     `/// <reference types="foo" />
     var foo = require("foo");`,
     `/// <reference path="foo" />
-    import * from "foo"`,
+    import * as foo from "foo"`,
   ],
   invalid: [
     {
       code: `
 /// <reference types="foo" />
-import * from "foo"
+import * as foo from "foo"
       `,
 
       parser: '@typescript-eslint/parser',