Merge aad2a2f into ee110ef

README.md

@@ -11,12 +11,15 @@ This plugin intends to support linting of ES2015+ (ES6+) import/export syntax, a
 
 ## Rules
 
-* Ensure imports point to a file/module that can be resolved. ([`no-unresolved`](#no-unresolved))
-* Ensure named imports correspond to a named export in the remote file. ([`named`](#named))
+* Ensure imports point to a file/module that can be resolved. ([`no-unresolved`])
+* Ensure named imports correspond to a named export in the remote file. ([`named`])
 * Ensure a default export is present, given a default import. ([`default`](#default))
 * Ensure imported namespaces contain dereferenced properties as they are dereferenced. ([`namespace`](#namespace))
 * Report any invalid exports, i.e. re-export of the same name ([`export`](#export))
 
+[`no-unresolved`]: ./docs/rules/no-unresolved.md
+[`named`]: ./docs/rules/named.md
+
 Helpful warnings:
 
 * Report CommonJS `require` calls. ([`no-require`](#no-require))
@@ -66,26 +69,6 @@ rules:
 
 # Rule Details
 
-### `no-unresolved`
-
-Ensures an imported module can be resolved to a module on the local filesystem,
-as defined by standard Node `require.resolve` behavior.
-
-See [settings](#settings) for customization options for the resolution (i.e.
-additional filetypes, `NODE_PATH`, etc.)
-
-This rule can also optionally report on unresolved modules in CommonJS `require('./foo')` calls and AMD `require(['./foo'], function (foo){...})` and `define(['./foo'], function (foo){...})`.
-
-To enable this, send `{ commonjs: true/false, amd: true/false }` as a rule option.
-Both are disabled by default.
-
-If you are using Webpack, see the section on [resolver plugins](#resolver-plugins).
-
-### `named`
-
-Verifies that all named imports are part of the set of named exports in the referenced module.
-
-For `export`, verifies that all named exports exist in the referenced module.
 
 ### `default`
 

docs/rules/named.md

@@ -0,0 +1,94 @@
+# named
+
+Verifies that all named imports are part of the set of named exports in the referenced module.
+
+For `export`, verifies that all named exports exist in the referenced module.
+
+Note: for modules, the plugin will find exported names from [`jsnext:main`], if present in `package.json`.
+Redux's npm module includes this key, and thereby is lintable, for example. Otherwise,
+the whole `node_modules` folder is ignored by default ([`import/ignore`]) as most published modules are
+formatted in CommonJS, which [at time of this writing](https://github.com/benmosher/eslint-plugin-import/issues/13)
+is not able to be analyzed for exports.
+
+
+## Rule Details
+
+Given:
+
+```js
+// ./foo.js
+export const foo = "I'm so foo"
+```
+
+The following is considered valid:
+
+```js
+// ./bar.js
+import { foo } from './foo'
+
+// ES7 proposal
+export { foo as bar } from './foo'
+
+// node_modules without jsnext:main are not analyzed by default
+// (import/ignore setting)
+import { SomeNonsenseThatDoesntExist } from 'react'
+```
+
+...and the following are reported:
+
+```js
+// ./baz.js
+import { notFoo } from './foo'
+
+// ES7 proposal
+export { notFoo as defNotBar } from './foo'
+
+// will follow 'jsnext:main', if available
+import { dontCreateStore } from 'redux'
+```
+
+### Settings
+
+[`import/ignore`] can be provided as a setting to ignore certain modules (node_modules,
+CoffeeScript, CSS if using Webpack, etc.).
+
+Given:
+
+```yaml
+# .eslintrc (YAML)
+---
+settings:
+  import/ignore:
+    - node_modules  # included by default, but replaced if explicitly configured
+    - *.coffee$     # can't parse CoffeeScript (unless a custom polyglot parser was configured)
+```
+
+and
+
+```coffeescript
+# ./whatever.coffee
+exports.whatever = (foo) -> console.log foo
+```
+
+then the following is not reported:
+
+```js
+// ./foo.js
+
+// can't be analyzed, and ignored, so not reported
+import { notWhatever } from './whatever'
+```
+
+## When Not To Use It
+
+If you are using CommonJS and/or modifying the exported namespace of any module at
+runtime, you will likely see false positives with this rule.
+
+## Further Reading
+
+- [`import/ignore`] setting
+- [`jsnext:main`] (Rollup)
+
+
+[`jsnext:main`]: https://github.com/rollup/rollup/wiki/jsnext:main
+[`import/ignore`]: ../../README.md#importignore

docs/rules/no-unresolved.md

@@ -0,0 +1,65 @@
+# no-unresolved
+
+Ensures an imported module can be resolved to a module on the local filesystem,
+as defined by standard Node `require.resolve` behavior.
+
+See [settings](../../README.md#settings) for customization options for the resolution (i.e.
+additional filetypes, `NODE_PATH`, etc.)
+
+This rule can also optionally report on unresolved modules in CommonJS `require('./foo')` calls and AMD `require(['./foo'], function (foo){...})` and `define(['./foo'], function (foo){...})`.
+
+To enable this, send `{ commonjs: true/false, amd: true/false }` as a rule option.
+Both are disabled by default.
+
+If you are using Webpack, see the section on [resolver plugins](../../README.md#resolver-plugins).
+
+## Rule Details
+
+### Options
+
+By default, only ES6 imports will be resolved:
+
+```js
+/*eslint import/no-unresolved: 2*/
+import x from './foo' // reports if './foo' cannot be resolved on the filesystem
+```
+
+If `{commonjs: true}` is provided, single-argument `require` calls will be resolved:
+
+```js
+/*eslint import/no-unresolved: [2, { commonjs: true }]*/
+const { default: x } = require('./foo') // reported if './foo' is not found
+
+require(0) // ignored
+require(['x', 'y'], function (x, y) { /*...*/ }) // ignored
+```
+
+Similarly, if `{ amd: true }` is provided, dependency paths for `define` and `require`
+calls will be resolved:
+
+```js
+/*eslint import/no-unresolved: [2, { amd: true }]*/
+define(['./foo'], function (foo) { /*...*/ }) // reported if './foo' is not found
+require(['./foo'], function (foo) { /*...*/ }) // reported if './foo' is not found
+
+const { default: x } = require('./foo') // ignored
+```
+
+Both may be provided, too:
+```js
+/*eslint import/no-unresolved: [2, { commonjs: true, amd: true }]*/
+const { default: x } = require('./foo') // reported if './foo' is not found
+define(['./foo'], function (foo) { /*...*/ }) // reported if './foo' is not found
+require(['./foo'], function (foo) { /*...*/ }) // reported if './foo' is not found
+```
+
+## When Not To Use It
+
+If you're using a module bundler other than Node or Webpack, you may end up with
+a lot of false positive reports of missing dependencies.
+
+## Further Reading
+
+- [Resolver plugins](../../README.md#resolver-plugins)
+- [Node resolver](https://npmjs.com/package/eslint-import-resolver-node) (default)
+- [Webpack resolver](https://npmjs.com/package/eslint-import-resolver-webpack)