Merge pull request #131 from benmosher/docs

separate rule docs

Author: benmosher

README.md

@@ -11,21 +11,33 @@ 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 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))
+* 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`])
+* Ensure imported namespaces contain dereferenced properties as they are dereferenced. ([`namespace`])
+* Report any invalid exports, i.e. re-export of the same name ([`export`])
+
+[`no-unresolved`]: ./docs/rules/no-unresolved.md
+[`named`]: ./docs/rules/named.md
+[`default`]: ./docs/rules/default.md
+[`namespace`]: ./docs/rules/namespace.md
+[`export`]: ./docs/rules/export.md
 
 Helpful warnings:
 
-* Report CommonJS `require` calls. ([`no-require`](#no-require))
-* Report use of exported name as identifier of default export ([`no-named-as-default`](#no-named-as-default))
-* Report repeated import of the same module in multiple places ([`no-duplicates`](#no-duplicates), warning by default)
+* Report use of exported name as identifier of default export ([`no-named-as-default`])
 
-Style rules:
+[`no-named-as-default`]: ./docs/rules/no-named-as-default.md
 
-* Ensure all imports appear before other statements ([`imports-first`](#imports-first))
+Style guide:
+
+* Report CommonJS `require` calls. ([`no-require`])
+* Ensure all imports appear before other statements ([`imports-first`])
+* Report repeated import of the same module in multiple places ([`no-duplicates`])
+
+[`no-require`]: ./docs/rules/no-require.md
+[`imports-first`]: ./docs/rules/imports-first.md
+[`no-duplicates`]: ./docs/rules/no-duplicates.md
 
 ## Installation
 
@@ -63,199 +75,6 @@ rules:
   # etc...
 ```
 
-
-# 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`
-
-If a default import is requested, this rule will report if there is no default
-export in the imported module.
-
-For [ES7], reports if a default is named and exported but is not found in the
-referenced module.
-
-### `namespace`
-
-Enforces names exist at the time they are dereferenced, when imported as a full namespace (i.e. `import * as foo from './foo'; foo.bar();` will report if `bar` is not exported by `./foo`.).
-
-Will report at the import declaration if there are _no_ exported names found.
-
-Also, will report for computed references (i.e. `foo["bar"]()`).
-
-Reports on assignment to a member of an imported namespace.
-
-**Implementation note**: currently, this rule does not check for possible
-redefinition of the namespace in an intermediate scope. Adherence to the ESLint
-`no-shadow` rule for namespaces will prevent this from being a problem.
-
-For [ES7], reports if an exported namespace would be empty (no names exported from the referenced module.)
-
-### `no-require`
-
-Reports `require([string])` function calls. Will not report if >1 argument,
-or single argument is not a literal string.
-
-Intended for temporary use when migrating to pure ES6 modules.
-
-Given:
-```js
-// ./mod.js
-export const foo = 'bar'
-export function bar() { return foo }
-
-// ./common.js
-exports.something = 'whatever'
-```
-
-This would be reported:
-
-```js
-var mod = require('./mod')
-  , common = require('./common')
-  , fs = require('fs')
-  , whateverModule = require('./not-found')
-```
-
-### `no-named-as-default`
-
-Reports use of an exported name as the locally imported name of a default export.
-
-Given:
-```js
-// foo.js
-export default 'foo';
-export const bar = 'baz';
-```
-
-...this would be valid:
-```js
-import foo from './foo.js';
-```
-
-...and this would be reported:
-```js
-// message: Using exported name 'bar' as identifier for default export.
-import bar from './foo.js';
-```
-
-Rationale: using an exported name as the name of the default export is likely...
-
-- *misleading*: others familiar with `foo.js` probably expect the name to be `foo`
-- *a mistake*: only needed to import `bar` and forgot the brackets (the case that is prompting this)
-
-For [ES7], this also prevents exporting the default from a referenced module as a name within than module, for the same reasons:
-
-```js
-// valid:
-export foo from './foo.js'
-
-// message: Using exported name 'bar' as identifier for default export.
-export bar from './foo.js';
-```
-
-### `export`
-
-Reports funny business with exports, such as
-
-```js
-export default class MyClass { /*...*/ } // Multiple default exports.
-
-function makeClass() { return new MyClass(...arguments) }
-
-export default makeClass // Multiple default exports.
-```
-
-or
-```js
-export const foo = function () { /*...*/ } // Multiple exports of name 'foo'.
-
-function bar() { /*...*/ }
-export { bar as foo } // Multiple exports of name 'foo'.
-```
-
-In the case of named/default re-export, all `n` re-exports will be reported,
-as at least `n-1` of them are clearly mistakes, but it is not clear which one
-(if any) is intended. Could be the result of copy/paste, code duplication with
-intent to rename, etc.
-
-
-[ES7]: https://github.com/leebyron/ecmascript-more-export-from
-
-
-### `no-duplicates`
-
-Reports if a resolved path is imported more than once.
-
-Valid:
-```js
-import SomeDefaultClass, * as names from './mod'
-```
-
-...whereas here, both `./mod` imports will be reported:
-
-```js
-import SomeDefaultClass from './mod'
-
-// oops, some other import separated these lines
-import foo from './some-other-mod'
-
-import * as names from './mod'
-```
-
-The motivation is that this is likely a result of two developers importing different
-names from the same module at different times (and potentially largely different
-locations in the file.) This rule brings both (or n-many) to attention.
-
-This rule is only set to a warning, by default.
-
-
-### `imports-first`
-
-By popular demand, this rule reports any imports that come after non-import
-statments:
-
-```js
-import foo from './foo'
-
-// some module-level initializer
-initWith(foo)
-
-import bar from './bar' // <- reported
-```
-
-Providing `absolute-first` as an option will report any absolute imports (i.e.
-packages) that come after any relative imports:
-
-```js
-import foo from 'foo'
-import bar from './bar'
-
-import * as _ from 'lodash' // <- reported
-```
-
-This rule is disabled by default.
-
 # Resolver plugins
 
 With the advent of module bundlers and the current state of modules and module

docs/rules/default.md

@@ -0,0 +1,69 @@
+# default
+
+If a default import is requested, this rule will report if there is no default
+export in the imported module.
+
+For [ES7], reports if a default is named and exported but is not found in the
+referenced module.
+
+Note: for modules, the plugin will find exported names (including defaults)
+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 default function () { return 42 }
+
+// ./bar.js
+export function bar() { return null }
+
+// ./baz.js
+module.exports = function () { /* ... */ }
+
+// node_modules/some-module/index.js
+exports.sharedFunction = function shared() { /* ... */ }
+```
+
+The following is considered valid:
+
+```js
+import foo from './foo'
+
+// assuming 'node_modules' are ignored (true by default)
+import someModule from 'some-module'
+```
+
+...and the following cases are reported:
+
+```js
+import bar from './bar' // no default export found in ./bar
+import baz from './baz' // no default export found in ./baz
+```
+
+
+## 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.
+
+This rule currently does not interpret `module.exports = ...` as a `default` export,
+either, so such a situation will be reported in the importing module.
+
+## Further Reading
+
+- Lee Byron's [ES7] export proposal
+- [`import/ignore`] setting
+- [`jsnext:main`] (Rollup)
+
+
+[ES7]: https://github.com/leebyron/ecmascript-more-export-from
+[`import/ignore`]: ../../README.md#importignore
+[`jsnext:main`]: https://github.com/rollup/rollup/wiki/jsnext:main

docs/rules/export.md

@@ -0,0 +1,32 @@
+# export
+
+Reports funny business with exports, like repeated exports of names or defaults.
+
+## Rule Details
+
+```js
+export default class MyClass { /*...*/ } // Multiple default exports.
+
+function makeClass() { return new MyClass(...arguments) }
+
+export default makeClass // Multiple default exports.
+```
+
+or
+```js
+export const foo = function () { /*...*/ } // Multiple exports of name 'foo'.
+
+function bar() { /*...*/ }
+export { bar as foo } // Multiple exports of name 'foo'.
+```
+
+In the case of named/default re-export, all `n` re-exports will be reported,
+as at least `n-1` of them are clearly mistakes, but it is not clear which one
+(if any) is intended. Could be the result of copy/paste, code duplication with
+intent to rename, etc.
+
+## Further Reading
+
+- Lee Byron's [ES7] export proposal
+
+[ES7]: https://github.com/leebyron/ecmascript-more-export-from

docs/rules/imports-first.md

@@ -0,0 +1,32 @@
+# imports-first
+
+By popular demand, this rule reports any imports that come after non-import
+statments.
+
+## Rule Details
+
+```js
+import foo from './foo'
+
+// some module-level initializer
+initWith(foo)
+
+import bar from './bar' // <- reported
+```
+
+Providing `absolute-first` as an option will report any absolute imports (i.e.
+packages) that come after any relative imports:
+
+```js
+import foo from 'foo'
+import bar from './bar'
+
+import * as _ from 'lodash' // <- reported
+```
+
+TODO: add explanation of imported name hoisting
+
+## When Not To Use It
+
+If you don't mind imports being sprinkled throughout, you may not want to
+enable this rule.