#384: unambiguous docs + added to recommended config as a warning

import-js · Jul 20, 2016 · 9844c62 · jdalton · Jul 20, 2016 · jdalton
1 parent a91e93a
commit 9844c62
Show file tree

Hide file tree

Showing 3 changed files with 58 additions and 0 deletions.
diff --git a/README.md b/README.md
@@ -27,6 +27,7 @@ This plugin intends to support linting of ES2015+ (ES6+) import/export syntax, a
 
 **Helpful warnings:**
 
+
 * Report any invalid exports, i.e. re-export of the same name ([`export`])
 * Report use of exported name as identifier of default export ([`no-named-as-default`])
 * Report use of exported name as property of default export ([`no-named-as-default-member`])
@@ -43,10 +44,12 @@ This plugin intends to support linting of ES2015+ (ES6+) import/export syntax, a
 
 **Module systems:**
 
+* Report potentially ambiguous parse goal (`script` vs. `module`) ([`unambiguous`])
 * Report CommonJS `require` calls and `module.exports` or `exports.*`. ([`no-commonjs`])
 * Report AMD `require` and `define` calls. ([`no-amd`])
 * No Node.js builtin modules. ([`no-nodejs-modules`])
 
+[`unambiguous`]: ./docs/rules/unambiguous.md
 [`no-commonjs`]: ./docs/rules/no-commonjs.md
 [`no-amd`]: ./docs/rules/no-amd.md
 [`no-nodejs-modules`]: ./docs/rules/no-nodejs-modules.md

diff --git a/config/recommended.js b/config/recommended.js
@@ -15,6 +15,7 @@ module.exports = {
     'import/no-named-as-default': 'warn',
     'import/no-named-as-default-member': 'warn',
     'import/no-duplicates': 'warn',
+    'import/unambiguous': 'warn',
   },
 
   // need all these for parsing dependencies (even if _your_ code doesn't need

diff --git a/docs/rules/unambiguous.md b/docs/rules/unambiguous.md
@@ -0,0 +1,54 @@
+# unambiguous
+
+Warn if a `module` could be mistakely parsed as a `script` by a consumer leveraging
+[Unambiguous JavaScript Grammar] to determine correct parsing goal.
+
+Will respect the [`parserOptions.sourceType`] from ESLint config, i.e. files parsed
+as `script` per that setting will not be reported.
+
+This plugin uses [Unambiguous JavaScript Grammar] internally to decide whether
+dependencies should be parsed as modules and searched for exports matching the
+`import`ed names, so it may be beneficial to keep this rule on even if your application
+will run in an explicit `module`-only environment.
+
+## Rule Details
+
+For files parsed as `module` by ESLint, the following are valid:
+
+```js
+import 'foo'
+function x() { return 42 }
+```
+
+```js
+export function x() { return 42 }
+```
+
+```js
+(function x() { return 42 })()
+export {} // simple way to mark side-effects-only file as 'module' without any imports/exports
+```
+
+...whereas the following file would be reported:
+```js
+(function x() { return 42 })()
+```
+
+## When Not To Use It
+
+If your application environment will always know via [some other means](https://github.com/nodejs/node-eps/issues/13)
+how to parse, regardless of syntax, you may not need this rule.
+
+Remember, though, that this plugin uses this strategy internally, so if you were
+to `import` from a module with no `import`s or `export`s, this plugin would not
+report it as it would not be clear whether it should be considered a `script` or
+a `module`.
+
+## Further Reading
+
+- [Unambiguous JavaScript Grammar]
+- [`parserOptions.sourceType`]
+- [node-eps#13](https://github.com/nodejs/node-eps/issues/13)
+
+[`parserOptions.sourceType`]: http://eslint.org/docs/user-guide/configuring#specifying-parser-options
+[Unambiguous JavaScript Grammar]: https://github.com/bmeck/UnambiguousJavaScriptGrammar