From c123b6c957c3395b8413448132f14692db1824b1 Mon Sep 17 00:00:00 2001 From: Bryan Mishkin <698306+bmish@users.noreply.github.com> Date: Sat, 29 Oct 2022 11:57:27 -0400 Subject: [PATCH] docs: automate docs with eslint-doc-generator --- .eslintrc | 1 + CONTRIBUTING.md | 18 +- README.md | 187 ++++++++---------- docs/rules/consistent-type-specifier-style.md | 4 + docs/rules/default.md | 4 + docs/rules/dynamic-import-chunkname.md | 2 + docs/rules/export.md | 4 + docs/rules/exports-last.md | 2 + docs/rules/extensions.md | 7 +- docs/rules/first.md | 4 + docs/rules/group-exports.md | 2 + docs/rules/imports-first.md | 6 + docs/rules/max-dependencies.md | 2 + docs/rules/named.md | 4 + docs/rules/namespace.md | 4 + docs/rules/newline-after-import.md | 4 + docs/rules/no-absolute-path.md | 6 +- docs/rules/no-amd.md | 2 + docs/rules/no-anonymous-default-export.md | 2 + docs/rules/no-commonjs.md | 2 + docs/rules/no-cycle.md | 2 + docs/rules/no-default-export.md | 4 +- docs/rules/no-deprecated.md | 4 +- docs/rules/no-duplicates.md | 6 + docs/rules/no-dynamic-require.md | 6 +- docs/rules/no-empty-named-blocks.md | 4 + docs/rules/no-extraneous-dependencies.md | 4 +- docs/rules/no-import-module-exports.md | 4 + docs/rules/no-internal-modules.md | 2 + docs/rules/no-mutable-exports.md | 2 + docs/rules/no-named-as-default-member.md | 4 + docs/rules/no-named-as-default.md | 4 + docs/rules/no-named-default.md | 2 + docs/rules/no-named-export.md | 4 +- docs/rules/no-namespace.md | 4 + docs/rules/no-nodejs-modules.md | 4 +- docs/rules/no-relative-packages.md | 4 + docs/rules/no-relative-parent-imports.md | 2 + docs/rules/no-restricted-paths.md | 4 +- docs/rules/no-self-import.md | 4 +- docs/rules/no-unassigned-import.md | 4 +- docs/rules/no-unresolved.md | 4 + docs/rules/no-unused-modules.md | 2 + docs/rules/no-useless-path-segments.md | 4 + docs/rules/no-webpack-loader-syntax.md | 2 + docs/rules/order.md | 6 +- docs/rules/prefer-default-export.md | 2 + docs/rules/unambiguous.md | 2 + package.json | 7 +- src/rules/consistent-type-specifier-style.js | 3 +- src/rules/default.js | 2 + src/rules/dynamic-import-chunkname.js | 2 + src/rules/export.js | 2 + src/rules/exports-last.js | 2 + src/rules/extensions.js | 2 + src/rules/first.js | 2 + src/rules/group-exports.js | 2 + src/rules/imports-first.js | 2 + src/rules/max-dependencies.js | 2 + src/rules/named.js | 2 + src/rules/namespace.js | 2 + src/rules/newline-after-import.js | 2 + src/rules/no-absolute-path.js | 2 + src/rules/no-amd.js | 2 + src/rules/no-anonymous-default-export.js | 2 + src/rules/no-commonjs.js | 2 + src/rules/no-cycle.js | 6 +- src/rules/no-default-export.js | 2 + src/rules/no-deprecated.js | 2 + src/rules/no-duplicates.js | 2 + src/rules/no-dynamic-require.js | 2 + src/rules/no-empty-named-blocks.js | 2 + src/rules/no-extraneous-dependencies.js | 2 + src/rules/no-import-module-exports.js | 4 +- src/rules/no-internal-modules.js | 2 + src/rules/no-mutable-exports.js | 2 + src/rules/no-named-as-default-member.js | 2 + src/rules/no-named-as-default.js | 2 + src/rules/no-named-default.js | 2 + src/rules/no-named-export.js | 6 +- src/rules/no-namespace.js | 2 + src/rules/no-nodejs-modules.js | 2 + src/rules/no-relative-packages.js | 2 + src/rules/no-relative-parent-imports.js | 2 + src/rules/no-restricted-paths.js | 2 + src/rules/no-self-import.js | 3 +- src/rules/no-unassigned-import.js | 2 + src/rules/no-unresolved.js | 2 + src/rules/no-unused-modules.js | 10 +- src/rules/no-useless-path-segments.js | 2 + src/rules/no-webpack-loader-syntax.js | 2 + src/rules/order.js | 2 + src/rules/prefer-default-export.js | 2 + src/rules/unambiguous.js | 2 + 94 files changed, 343 insertions(+), 141 deletions(-) diff --git a/.eslintrc b/.eslintrc index 2cbfd59cea..a90ba1d4be 100644 --- a/.eslintrc +++ b/.eslintrc @@ -71,6 +71,7 @@ "eslint-plugin/no-deprecated-report-api": "off", "eslint-plugin/prefer-replace-text": "error", "eslint-plugin/report-message-format": "error", + "eslint-plugin/require-meta-docs-description": ["error", { "pattern": "^(Enforce|Ensure|Prefer|Forbid).+\\.$" }], "eslint-plugin/require-meta-schema": "error", "eslint-plugin/require-meta-type": "error", diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0606b4a63b..eba44f51ac 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,10 +5,12 @@ Thanks for your interest in helping out! Here are a **few** _weird_ tricks to ~~ ## TL;DR: Checklist When opening an [issue](#issues): + - [ ] search open/closed issues - [ ] discuss bug/enhancement in new or old issue [PR](#prs) time: + - [ ] write tests - [ ] implement feature/fix bug - [ ] update docs @@ -18,13 +20,13 @@ Remember, you don't need to do it all yourself; any of these are helpful! 😎 ## Issues -### Search open + closed issues for similar cases. +### Search open + closed issues for similar cases You may find an open issue that closely matches what you are thinking. You may also find a closed issue with discussion that either solves your problem or explains why we are unlikely to solve it in the near future. If you find a matching issue that is open, and marked `accepted` and/or `help wanted`, you might want to [open a PR](#prs). -### Open an issue. +### Open an issue Let's discuss your issue. Could be as simple as unclear documentation or a wonky config file. If you're suggesting a feature, it might exist and need better documentation, or it might be in process. Even given those, some discussion might be warranted to ensure the enhancement is clear. @@ -48,21 +50,19 @@ Here are some things to keep in mind when working on a PR: If a PR is open, but unfortunately the author is, for any reason, not available to apply code review fixes or rebase the source branch, then please **do not open a new PR**. Instead, paste a link to your own branch in the PR, and the maintainers can pull in your changes and update the existing PR in-place. -#### Tests +### Tests A PR that is just failing test cases for an existing issue is very helpful, as this can take as much time (if not more) as it takes to implement a new feature or fix a bug. If you only have enough time to write tests, fantastic! Submit away. This is a great jumping-off point for a core contributor or even another PR to continue what you've started. -#### Docs - -For enhancements to rules, please update the docs in `docs/rules` matching the rule filename from `src/rules`. +### Docs -Also, take a quick look at the rule summary in [README.md] in case it could use tweaking, or add a line if you've implemented a new rule. +For enhancements to rules, please update the docs in `docs/rules` matching the rule filename from `src/rules` or the rule description in `meta.docs.description`. Running `npm run update:eslint-docs` will update the [README.md] and rule doc header. Bugfixes may not warrant docs changes, though it's worth skimming the existing docs to see if there are any relevant caveats that need to be removed. -#### Changelog +### Changelog Please add a quick blurb to the [**Unreleased**](./CHANGELOG.md#unreleased) section of the change log. Give yourself some credit, and please link back to the PR for future reference. This is especially helpful for resolver changes, as the resolvers are less frequently modified and published. @@ -72,4 +72,4 @@ Note also that the change log can't magically link back to Github entities (i.e. Please familiarize yourself with the [Code of Conduct](https://github.com/import-js/.github/blob/main/CODE_OF_CONDUCT.md). -[README.md]: ./README.md \ No newline at end of file +[README.md]: ./README.md diff --git a/README.md b/README.md index 0e550f8f8e..78344f35e3 100644 --- a/README.md +++ b/README.md @@ -13,111 +13,85 @@ This plugin intends to support linting of ES2015+ (ES6+) import/export syntax, a ## Rules -### Static analysis - -* 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`]) -* Restrict which files can be imported in a given folder ([`no-restricted-paths`]) -* Forbid import of modules using absolute paths ([`no-absolute-path`]) -* Forbid `require()` calls with expressions ([`no-dynamic-require`]) -* Prevent importing the submodules of other modules ([`no-internal-modules`]) -* Forbid webpack loader syntax in imports ([`no-webpack-loader-syntax`]) -* Forbid a module from importing itself ([`no-self-import`]) -* Forbid a module from importing a module with a dependency path back to itself ([`no-cycle`]) -* Prevent unnecessary path segments in import and require statements ([`no-useless-path-segments`]) -* Forbid importing modules from parent directories ([`no-relative-parent-imports`]) -* Prevent importing packages through relative paths ([`no-relative-packages`]) - -[`no-unresolved`]: ./docs/rules/no-unresolved.md -[`named`]: ./docs/rules/named.md -[`default`]: ./docs/rules/default.md -[`namespace`]: ./docs/rules/namespace.md -[`no-restricted-paths`]: ./docs/rules/no-restricted-paths.md -[`no-absolute-path`]: ./docs/rules/no-absolute-path.md -[`no-dynamic-require`]: ./docs/rules/no-dynamic-require.md -[`no-internal-modules`]: ./docs/rules/no-internal-modules.md -[`no-webpack-loader-syntax`]: ./docs/rules/no-webpack-loader-syntax.md -[`no-self-import`]: ./docs/rules/no-self-import.md -[`no-cycle`]: ./docs/rules/no-cycle.md -[`no-useless-path-segments`]: ./docs/rules/no-useless-path-segments.md -[`no-relative-parent-imports`]: ./docs/rules/no-relative-parent-imports.md -[`no-relative-packages`]: ./docs/rules/no-relative-packages.md + + +💼 Configurations enabled in.\ +⚠️ Configurations set to warn in.\ +🚫 Configurations disabled in.\ +❗ Set in the `errors` configuration.\ +☑️ Set in the `recommended` configuration.\ +⌨️ Set in the `typescript` configuration.\ +🚸 Set in the `warnings` configuration.\ +🔧 Automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/user-guide/command-line-interface#--fix).\ +💡 Manually fixable by [editor suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions).\ +❌ Deprecated. ### 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`]) -* Report imported names marked with `@deprecated` documentation tag ([`no-deprecated`]) -* Forbid the use of extraneous packages ([`no-extraneous-dependencies`]) -* Forbid the use of mutable exports with `var` or `let`. ([`no-mutable-exports`]) -* Report modules without exports, or exports without matching import in another module ([`no-unused-modules`]) -* Prevent empty named import blocks ([`no-empty-named-blocks`]) - -[`export`]: ./docs/rules/export.md -[`no-named-as-default`]: ./docs/rules/no-named-as-default.md -[`no-named-as-default-member`]: ./docs/rules/no-named-as-default-member.md -[`no-deprecated`]: ./docs/rules/no-deprecated.md -[`no-extraneous-dependencies`]: ./docs/rules/no-extraneous-dependencies.md -[`no-mutable-exports`]: ./docs/rules/no-mutable-exports.md -[`no-unused-modules`]: ./docs/rules/no-unused-modules.md -[`no-empty-named-blocks`]: ./docs/rules/no-empty-named-blocks.md +| Name                       | Description | 💼 | ⚠️ | 🚫 | 🔧 | 💡 | ❌ | +| :--------------------------------------------------------------------- | :------------------------------------------------------------------------------------ | :--- | :---- | :- | :- | :- | :- | +| [export](docs/rules/export.md) | Forbid any invalid exports, i.e. re-export of the same name. | ❗ ☑️ | | | | | | +| [no-deprecated](docs/rules/no-deprecated.md) | Forbid imported names marked with `@deprecated` documentation tag. | | | | | | | +| [no-empty-named-blocks](docs/rules/no-empty-named-blocks.md) | Forbid empty named import blocks. | | | | 🔧 | 💡 | | +| [no-extraneous-dependencies](docs/rules/no-extraneous-dependencies.md) | Forbid the use of extraneous packages. | | | | | | | +| [no-mutable-exports](docs/rules/no-mutable-exports.md) | Forbid the use of mutable exports with `var` or `let`. | | | | | | | +| [no-named-as-default](docs/rules/no-named-as-default.md) | Forbid use of exported name as identifier of default export. | | ☑️ 🚸 | | | | | +| [no-named-as-default-member](docs/rules/no-named-as-default-member.md) | Forbid use of exported name as property of default export. | | ☑️ 🚸 | | | | | +| [no-unused-modules](docs/rules/no-unused-modules.md) | Forbid modules without exports, or exports without matching import in another module. | | | | | | | ### 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`]) -* Forbid imports with CommonJS exports ([`no-import-module-exports`]) +| Name                     | Description | 💼 | ⚠️ | 🚫 | 🔧 | 💡 | ❌ | +| :----------------------------------------------------------------- | :------------------------------------------------------------------- | :- | :- | :- | :- | :- | :- | +| [no-amd](docs/rules/no-amd.md) | Forbid AMD `require` and `define` calls. | | | | | | | +| [no-commonjs](docs/rules/no-commonjs.md) | Forbid CommonJS `require` calls and `module.exports` or `exports.*`. | | | | | | | +| [no-import-module-exports](docs/rules/no-import-module-exports.md) | Forbid import statements with CommonJS module.exports. | | | | 🔧 | | | +| [no-nodejs-modules](docs/rules/no-nodejs-modules.md) | Forbid Node.js builtin modules. | | | | | | | +| [unambiguous](docs/rules/unambiguous.md) | Forbid potentially ambiguous parse goal (`script` vs. `module`). | | | | | | | -[`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 -[`no-import-module-exports`]: ./docs/rules/no-import-module-exports.md +### Static analysis +| Name                       | Description | 💼 | ⚠️ | 🚫 | 🔧 | 💡 | ❌ | +| :--------------------------------------------------------------------- | :----------------------------------------------------------------------------------- | :--- | :- | :- | :- | :- | :- | +| [default](docs/rules/default.md) | Ensure a default export is present, given a default import. | ❗ ☑️ | | | | | | +| [named](docs/rules/named.md) | Ensure named imports correspond to a named export in the remote file. | ❗ ☑️ | | ⌨️ | | | | +| [namespace](docs/rules/namespace.md) | Ensure imported namespaces contain dereferenced properties as they are dereferenced. | ❗ ☑️ | | | | | | +| [no-absolute-path](docs/rules/no-absolute-path.md) | Forbid import of modules using absolute paths. | | | | | | | +| [no-cycle](docs/rules/no-cycle.md) | Forbid a module from importing a module with a dependency path back to itself. | | | | | | | +| [no-dynamic-require](docs/rules/no-dynamic-require.md) | Forbid `require()` calls with expressions. | | | | | | | +| [no-internal-modules](docs/rules/no-internal-modules.md) | Forbid importing the submodules of other modules. | | | | | | | +| [no-relative-packages](docs/rules/no-relative-packages.md) | Forbid importing packages through relative paths. | | | | 🔧 | | | +| [no-relative-parent-imports](docs/rules/no-relative-parent-imports.md) | Forbid importing modules from parent directories. | | | | | | | +| [no-restricted-paths](docs/rules/no-restricted-paths.md) | Enforce which files can be imported in a given folder. | | | | | | | +| [no-self-import](docs/rules/no-self-import.md) | Forbid a module from importing itself. | | | | | | | +| [no-unresolved](docs/rules/no-unresolved.md) | Ensure imports point to a file/module that can be resolved. | ❗ ☑️ | | | | | | +| [no-useless-path-segments](docs/rules/no-useless-path-segments.md) | Forbid unnecessary path segments in import and require statements. | | | | 🔧 | | | +| [no-webpack-loader-syntax](docs/rules/no-webpack-loader-syntax.md) | Forbid webpack loader syntax in imports. | | | | | | | ### Style guide -* Ensure all imports appear before other statements ([`first`]) -* Ensure all exports appear after other statements ([`exports-last`]) -* Report repeated import of the same module in multiple places ([`no-duplicates`]) -* Forbid namespace (a.k.a. "wildcard" `*`) imports ([`no-namespace`]) -* Ensure consistent use of file extension within the import path ([`extensions`]) -* Enforce a convention in module import order ([`order`]) -* Enforce a newline after import statements ([`newline-after-import`]) -* Prefer a default export if module exports a single name ([`prefer-default-export`]) -* Limit the maximum number of dependencies a module can have ([`max-dependencies`]) -* Forbid unassigned imports ([`no-unassigned-import`]) -* Forbid named default exports ([`no-named-default`]) -* Forbid default exports ([`no-default-export`]) -* Forbid named exports ([`no-named-export`]) -* Forbid anonymous values as default exports ([`no-anonymous-default-export`]) -* Prefer named exports to be grouped together in a single export declaration ([`group-exports`]) -* Enforce a leading comment with the webpackChunkName for dynamic imports ([`dynamic-import-chunkname`]) -* Enforce or ban the use of inline type-only markers for named imports ([`consistent-type-specifier-style`]) - -[`first`]: ./docs/rules/first.md -[`exports-last`]: ./docs/rules/exports-last.md -[`no-duplicates`]: ./docs/rules/no-duplicates.md -[`no-namespace`]: ./docs/rules/no-namespace.md -[`extensions`]: ./docs/rules/extensions.md -[`order`]: ./docs/rules/order.md -[`newline-after-import`]: ./docs/rules/newline-after-import.md -[`prefer-default-export`]: ./docs/rules/prefer-default-export.md -[`max-dependencies`]: ./docs/rules/max-dependencies.md -[`no-unassigned-import`]: ./docs/rules/no-unassigned-import.md -[`no-named-default`]: ./docs/rules/no-named-default.md -[`no-anonymous-default-export`]: ./docs/rules/no-anonymous-default-export.md -[`group-exports`]: ./docs/rules/group-exports.md -[`no-default-export`]: ./docs/rules/no-default-export.md -[`no-named-export`]: ./docs/rules/no-named-export.md -[`dynamic-import-chunkname`]: ./docs/rules/dynamic-import-chunkname.md -[`consistent-type-specifier-style`]: ./docs/rules/consistent-type-specifier-style.md +| Name                            | Description | 💼 | ⚠️ | 🚫 | 🔧 | 💡 | ❌ | +| :------------------------------------------------------------------------------- | :------------------------------------------------------------------------- | :- | :---- | :- | :- | :- | :- | +| [consistent-type-specifier-style](docs/rules/consistent-type-specifier-style.md) | Enforce or ban the use of inline type-only markers for named imports. | | | | 🔧 | | | +| [dynamic-import-chunkname](docs/rules/dynamic-import-chunkname.md) | Enforce a leading comment with the webpackChunkName for dynamic imports. | | | | | | | +| [exports-last](docs/rules/exports-last.md) | Ensure all exports appear after other statements. | | | | | | | +| [extensions](docs/rules/extensions.md) | Ensure consistent use of file extension within the import path. | | | | | | | +| [first](docs/rules/first.md) | Ensure all imports appear before other statements. | | | | 🔧 | | | +| [group-exports](docs/rules/group-exports.md) | Prefer named exports to be grouped together in a single export declaration | | | | | | | +| [imports-first](docs/rules/imports-first.md) | Replaced by `import/first`. | | | | 🔧 | | ❌ | +| [max-dependencies](docs/rules/max-dependencies.md) | Enforce the maximum number of dependencies a module can have. | | | | | | | +| [newline-after-import](docs/rules/newline-after-import.md) | Enforce a newline after import statements. | | | | 🔧 | | | +| [no-anonymous-default-export](docs/rules/no-anonymous-default-export.md) | Forbid anonymous values as default exports. | | | | | | | +| [no-default-export](docs/rules/no-default-export.md) | Forbid default exports. | | | | | | | +| [no-duplicates](docs/rules/no-duplicates.md) | Forbid repeated import of the same module in multiple places. | | ☑️ 🚸 | | 🔧 | | | +| [no-named-default](docs/rules/no-named-default.md) | Forbid named default exports. | | | | | | | +| [no-named-export](docs/rules/no-named-export.md) | Forbid named exports. | | | | | | | +| [no-namespace](docs/rules/no-namespace.md) | Forbid namespace (a.k.a. "wildcard" `*`) imports. | | | | 🔧 | | | +| [no-unassigned-import](docs/rules/no-unassigned-import.md) | Forbid unassigned imports | | | | | | | +| [order](docs/rules/order.md) | Enforce a convention in module import order. | | | | 🔧 | | | +| [prefer-default-export](docs/rules/prefer-default-export.md) | Prefer a default export if module exports a single name. | | | | | | | + + ## `eslint-plugin-import` for enterprise @@ -209,6 +183,7 @@ settings: # uses 'eslint-import-resolver-foo': import/resolver: foo ``` + ```js // .eslintrc.js module.exports = { @@ -227,6 +202,7 @@ module.exports = { settings: import/resolver: 'my-awesome-npm-module' ``` + ```js // .eslintrc.js module.exports = { @@ -254,8 +230,6 @@ module.exports = { Relative paths will be resolved relative to the source's nearest `package.json` or the process's current working directory if no `package.json` is found. - - If you are interesting in writing a resolver, see the [spec](./resolvers/README.md) for more details. [`resolve`]: https://www.npmjs.com/package/resolve @@ -264,11 +238,11 @@ If you are interesting in writing a resolver, see the [spec](./resolvers/README. [Node]: https://www.npmjs.com/package/eslint-import-resolver-node [webpack]: https://www.npmjs.com/package/eslint-import-resolver-webpack -# Settings +## Settings You may set the following settings in your `.eslintrc`: -#### `import/extensions` +### `import/extensions` A list of file extensions that will be parsed as modules and inspected for `export`s. @@ -309,7 +283,7 @@ factor into the `no-unresolved` rule. Also, the following `import/ignore` patterns will overrule this list. -#### `import/ignore` +### `import/ignore` A list of regex strings that, if matched by a path, will not report the matching module if no `export`s are found. @@ -325,7 +299,7 @@ settings: - \.(scss|less|css)$ # can't parse unprocessed CSS modules, either ``` -#### `import/core-modules` +### `import/core-modules` An array of additional modules to consider as "core" modules--modules that should be considered resolved but have no path on the filesystem. Your resolver may @@ -352,7 +326,7 @@ that specifies this for you. Contribution of more such shared configs for other platforms are welcome! -#### `import/external-module-folders` +### `import/external-module-folders` An array of folders. Resolved modules only from those folders will be considered as "external". By default - `["node_modules"]`. Makes sense if you have configured your path or webpack to handle your internal paths differently and want to consider modules from some folders, for example `bower_components` or `jspm_modules`, as "external". @@ -370,7 +344,7 @@ Each item in this array is either a folder's name, its subpath, or its absolute Please note that incomplete names are not allowed here so `components` won't match `bower_components` and `packages/ui` won't match `packages/ui-utils` (but will match `packages/ui/utils`). -#### `import/parsers` +### `import/parsers` A map from parsers to file extension arrays. If a file extension is matched, the dependency parser will require and use the map key as the parser instead of the @@ -397,12 +371,11 @@ depending on how far down the rabbit hole goes. Submit an issue if you find stra behavior beyond here, but steel your heart against the likely outcome of closing with `wontfix`. - -#### `import/resolver` +### `import/resolver` See [resolvers](#resolvers). -#### `import/cache` +### `import/cache` Settings for cache behavior. Memoization is used at various levels to avoid the copious amount of `fs.statSync`/module parse calls required to correctly report errors. @@ -431,7 +404,7 @@ settings: [`eslint_d`]: https://www.npmjs.com/package/eslint_d [`eslint-loader`]: https://www.npmjs.com/package/eslint-loader -#### `import/internal-regex` +### `import/internal-regex` A regex for packages should be treated as internal. Useful when you are utilizing a monorepo setup or developing a set of packages that depend on each other. @@ -445,7 +418,6 @@ settings: import/internal-regex: ^@scope/ ``` - ## SublimeLinter-eslint SublimeLinter-eslint introduced a change to support `.eslintignore` files @@ -510,6 +482,7 @@ I also found that I needed to set `rc_search_limit` to `null`, which removes the hierarchy search limit when looking up the directory tree for `.sublimelinterrc`: In Package Settings / SublimeLinter / User Settings: + ```json { "user": { diff --git a/docs/rules/consistent-type-specifier-style.md b/docs/rules/consistent-type-specifier-style.md index 4314e33867..54c09049ef 100644 --- a/docs/rules/consistent-type-specifier-style.md +++ b/docs/rules/consistent-type-specifier-style.md @@ -1,5 +1,9 @@ # import/consistent-type-specifier-style +🔧 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix). + + + In both Flow and TypeScript you can mark an import as a type-only import by adding a "kind" marker to the import. Both languages support two positions for marker. **At the top-level** which marks all names in the import as type-only and applies to named, default, and namespace (for TypeScript) specifiers: diff --git a/docs/rules/default.md b/docs/rules/default.md index f69934468a..ffbbdc166a 100644 --- a/docs/rules/default.md +++ b/docs/rules/default.md @@ -1,5 +1,9 @@ # import/default +💼 This rule is enabled in the following configs: ❗ `errors`, ☑️ `recommended`. + + + If a default import is requested, this rule will report if there is no default export in the imported module. diff --git a/docs/rules/dynamic-import-chunkname.md b/docs/rules/dynamic-import-chunkname.md index 6b43074f19..472a366485 100644 --- a/docs/rules/dynamic-import-chunkname.md +++ b/docs/rules/dynamic-import-chunkname.md @@ -1,5 +1,7 @@ # import/dynamic-import-chunkname + + This rule reports any dynamic imports without a webpackChunkName specified in a leading block comment in the proper format. This rule enforces naming of webpack chunks in dynamic imports. When you don't explicitly name chunks, webpack will autogenerate chunk names that are not consistent across builds, which prevents long-term browser caching. diff --git a/docs/rules/export.md b/docs/rules/export.md index e99882be85..115d2d8b29 100644 --- a/docs/rules/export.md +++ b/docs/rules/export.md @@ -1,5 +1,9 @@ # import/export +💼 This rule is enabled in the following configs: ❗ `errors`, ☑️ `recommended`. + + + Reports funny business with exports, like repeated exports of names or defaults. ## Rule Details diff --git a/docs/rules/exports-last.md b/docs/rules/exports-last.md index 291daee484..6b3e4bac40 100644 --- a/docs/rules/exports-last.md +++ b/docs/rules/exports-last.md @@ -1,5 +1,7 @@ # import/exports-last + + This rule enforces that all exports are declared at the bottom of the file. This rule will report any export declarations that comes before any non-export statements. diff --git a/docs/rules/extensions.md b/docs/rules/extensions.md index 575895c5a0..9e78b8c70f 100644 --- a/docs/rules/extensions.md +++ b/docs/rules/extensions.md @@ -1,4 +1,6 @@ -# import/extensions - Ensure consistent use of file extension within the import path +# import/extensions + + Some file resolve algorithms allow you to omit the file extension within the import source path. For example the `node` resolver can resolve `./foo/bar` to the absolute path `/User/someone/foo/bar.js` because the `.js` extension is resolved automatically by default. Depending on the resolver you can configure more extensions to get resolved automatically. @@ -37,6 +39,7 @@ By providing both a string and an object, the string will set the default settin For example, `["error", "never", { "svg": "always" }]` would require that all extensions are omitted, except for "svg". `ignorePackages` can be set as a separate boolean option like this: + ``` "import/extensions": [ , @@ -49,10 +52,10 @@ For example, `["error", "never", { "svg": "always" }]` would require that all ex } ] ``` + In that case, if you still want to specify extensions, you can do so inside the **pattern** property. Default value of `ignorePackages` is `false`. - ### Exception When disallowing the use of certain extensions this rule makes an exception and allows the use of extension when the file would not be resolvable without extension. diff --git a/docs/rules/first.md b/docs/rules/first.md index c71ab7d8ab..21904e2fa1 100644 --- a/docs/rules/first.md +++ b/docs/rules/first.md @@ -1,5 +1,9 @@ # import/first +🔧 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix). + + + This rule reports any imports that come after non-import statements. diff --git a/docs/rules/group-exports.md b/docs/rules/group-exports.md index e6b9887b24..c5a23cd218 100644 --- a/docs/rules/group-exports.md +++ b/docs/rules/group-exports.md @@ -1,5 +1,7 @@ # import/group-exports + + Reports when named exports are not grouped together in a single `export` declaration or when multiple assignments to CommonJS `module.exports` or `exports` object are present in a single file. **Rationale:** An `export` declaration or `module.exports` assignment can appear anywhere in the code. By requiring a single export declaration all your exports will remain at one place, making it easier to see what exports a module provides. diff --git a/docs/rules/imports-first.md b/docs/rules/imports-first.md index 4b90f04ea8..278e4c4725 100644 --- a/docs/rules/imports-first.md +++ b/docs/rules/imports-first.md @@ -1,3 +1,9 @@ # import/imports-first +❌ This rule is deprecated. + +🔧 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix). + + + This rule was **deprecated** in eslint-plugin-import v2.0.0. Please use the corresponding rule [`first`](https://github.com/import-js/eslint-plugin-import/blob/HEAD/docs/rules/first.md). diff --git a/docs/rules/max-dependencies.md b/docs/rules/max-dependencies.md index 3bead8273d..1da74f6818 100644 --- a/docs/rules/max-dependencies.md +++ b/docs/rules/max-dependencies.md @@ -1,5 +1,7 @@ # import/max-dependencies + + Forbid modules to have too many dependencies (`import` or `require` statements). This is a useful rule because a module with too many dependencies is a code smell, and usually indicates the module is doing too much and/or should be broken up into smaller modules. diff --git a/docs/rules/named.md b/docs/rules/named.md index 0f697cc254..6d376defac 100644 --- a/docs/rules/named.md +++ b/docs/rules/named.md @@ -1,5 +1,9 @@ # import/named +💼🚫 This rule is enabled in the following configs: ❗ `errors`, ☑️ `recommended`. This rule is _disabled_ in the ⌨️ `typescript` config. + + + 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. diff --git a/docs/rules/namespace.md b/docs/rules/namespace.md index 4bbbd378e9..5ac25b750d 100644 --- a/docs/rules/namespace.md +++ b/docs/rules/namespace.md @@ -1,5 +1,9 @@ # import/namespace +💼 This rule is enabled in the following configs: ❗ `errors`, ☑️ `recommended`. + + + 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. diff --git a/docs/rules/newline-after-import.md b/docs/rules/newline-after-import.md index ab454e4bdc..ed0a5b678f 100644 --- a/docs/rules/newline-after-import.md +++ b/docs/rules/newline-after-import.md @@ -1,5 +1,9 @@ # import/newline-after-import +🔧 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix). + + + Enforces having one or more empty lines after the last top-level import statement or require call. +(fixable) The `--fix` option on the [command line] automatically fixes problems reported by this rule. diff --git a/docs/rules/no-absolute-path.md b/docs/rules/no-absolute-path.md index 305e8e6050..3d85b9eba7 100644 --- a/docs/rules/no-absolute-path.md +++ b/docs/rules/no-absolute-path.md @@ -1,7 +1,11 @@ -# import/no-absolute-path: Forbid import of modules using absolute paths +# import/no-absolute-path + + Node.js allows the import of modules using an absolute path such as `/home/xyz/file.js`. That is a bad practice as it ties the code using it to your computer, and therefore makes it unusable in packages distributed on `npm` for instance. +This rule forbids the import of modules using absolute paths. + ## Rule Details ### Fail diff --git a/docs/rules/no-amd.md b/docs/rules/no-amd.md index f7146c1347..155c19b3ca 100644 --- a/docs/rules/no-amd.md +++ b/docs/rules/no-amd.md @@ -1,5 +1,7 @@ # import/no-amd + + Reports `require([array], ...)` and `define([array], ...)` function calls at the module scope. Will not report if !=2 arguments, or first argument is not a literal array. diff --git a/docs/rules/no-anonymous-default-export.md b/docs/rules/no-anonymous-default-export.md index 3edac63135..d3c88f94e0 100644 --- a/docs/rules/no-anonymous-default-export.md +++ b/docs/rules/no-anonymous-default-export.md @@ -1,5 +1,7 @@ # import/no-anonymous-default-export + + Reports if a module's default export is unnamed. This includes several types of unnamed data types; literals, object expressions, arrays, anonymous functions, arrow functions, and anonymous class declarations. Ensuring that default exports are named helps improve the grepability of the codebase by encouraging the re-use of the same identifier for the module's default export at its declaration site and at its import sites. diff --git a/docs/rules/no-commonjs.md b/docs/rules/no-commonjs.md index 7be4bb3993..09a6b44010 100644 --- a/docs/rules/no-commonjs.md +++ b/docs/rules/no-commonjs.md @@ -1,5 +1,7 @@ # import/no-commonjs + + Reports `require([string])` function calls. Will not report if >1 argument, or single argument is not a literal string. diff --git a/docs/rules/no-cycle.md b/docs/rules/no-cycle.md index 70b2ceb9b8..1593842df8 100644 --- a/docs/rules/no-cycle.md +++ b/docs/rules/no-cycle.md @@ -1,5 +1,7 @@ # import/no-cycle + + Ensures that there is no resolvable path back to this module via its dependencies. This includes cycles of depth 1 (imported module imports me) to `"∞"` (or `Infinity`), if the diff --git a/docs/rules/no-default-export.md b/docs/rules/no-default-export.md index 4f1a300a26..586d5e7451 100644 --- a/docs/rules/no-default-export.md +++ b/docs/rules/no-default-export.md @@ -1,4 +1,6 @@ -# `import/no-default-export` +# import/no-default-export + + Prohibit default exports. Mostly an inverse of [`prefer-default-export`]. diff --git a/docs/rules/no-deprecated.md b/docs/rules/no-deprecated.md index c948b51781..641fc1a8f4 100644 --- a/docs/rules/no-deprecated.md +++ b/docs/rules/no-deprecated.md @@ -1,4 +1,6 @@ -# `import/no-deprecated` +# import/no-deprecated + + Reports use of a deprecated name, as indicated by a JSDoc block with a `@deprecated` tag or TomDoc `Deprecated: ` comment. diff --git a/docs/rules/no-duplicates.md b/docs/rules/no-duplicates.md index 5252db1b79..3ca8d1af26 100644 --- a/docs/rules/no-duplicates.md +++ b/docs/rules/no-duplicates.md @@ -1,5 +1,11 @@ # import/no-duplicates +⚠️ This rule _warns_ in the following configs: ☑️ `recommended`, 🚸 `warnings`. + +🔧 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix). + + + Reports if a resolved path is imported more than once. +(fixable) The `--fix` option on the [command line] automatically fixes some problems reported by this rule. diff --git a/docs/rules/no-dynamic-require.md b/docs/rules/no-dynamic-require.md index 0f7bb6d371..292055fcdc 100644 --- a/docs/rules/no-dynamic-require.md +++ b/docs/rules/no-dynamic-require.md @@ -1,8 +1,10 @@ -# import/no-dynamic-require: Forbid `require()` calls with expressions +# import/no-dynamic-require + + The `require` method from CommonJS is used to import modules from different files. Unlike the ES6 `import` syntax, it can be given expressions that will be resolved at runtime. While this is sometimes necessary and useful, in most cases it isn't. Using expressions (for instance, concatenating a path and variable) as the argument makes it harder for tools to do static code analysis, or to find where in the codebase a module is used. -This rule checks every call to `require()` that uses expressions for the module name argument. +This rule forbids every call to `require()` that uses expressions for the module name argument. ## Rule Details diff --git a/docs/rules/no-empty-named-blocks.md b/docs/rules/no-empty-named-blocks.md index 229d927478..7bf4d695cf 100644 --- a/docs/rules/no-empty-named-blocks.md +++ b/docs/rules/no-empty-named-blocks.md @@ -1,5 +1,9 @@ # import/no-empty-named-blocks +🔧💡 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) and manually fixable by [editor suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions). + + + Reports the use of empty named import blocks. ## Rule Details diff --git a/docs/rules/no-extraneous-dependencies.md b/docs/rules/no-extraneous-dependencies.md index 70c08809cf..68cd4b154f 100644 --- a/docs/rules/no-extraneous-dependencies.md +++ b/docs/rules/no-extraneous-dependencies.md @@ -1,4 +1,6 @@ -# import/no-extraneous-dependencies: Forbid the use of extraneous packages +# import/no-extraneous-dependencies + + Forbid the import of external modules that are not declared in the `package.json`'s `dependencies`, `devDependencies`, `optionalDependencies`, `peerDependencies`, or `bundledDependencies`. The closest parent `package.json` will be used. If no `package.json` is found, the rule will not lint anything. This behavior can be changed with the rule option `packageDir`. Normally ignores imports of modules marked internal, but this can be changed with the rule option `includeInternal`. Type imports can be verified by specifying `includeTypes`. diff --git a/docs/rules/no-import-module-exports.md b/docs/rules/no-import-module-exports.md index d658deb566..08aacfcc34 100644 --- a/docs/rules/no-import-module-exports.md +++ b/docs/rules/no-import-module-exports.md @@ -1,5 +1,9 @@ # import/no-import-module-exports +🔧 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix). + + + Reports the use of import declarations with CommonJS exports in any module except for the [main module](https://docs.npmjs.com/files/package.json#main). diff --git a/docs/rules/no-internal-modules.md b/docs/rules/no-internal-modules.md index d957e26f36..47f7490da6 100644 --- a/docs/rules/no-internal-modules.md +++ b/docs/rules/no-internal-modules.md @@ -1,5 +1,7 @@ # import/no-internal-modules + + Use this rule to prevent importing the submodules of other modules. ## Rule Details diff --git a/docs/rules/no-mutable-exports.md b/docs/rules/no-mutable-exports.md index f4cc7843ad..f0a6251c19 100644 --- a/docs/rules/no-mutable-exports.md +++ b/docs/rules/no-mutable-exports.md @@ -1,5 +1,7 @@ # import/no-mutable-exports + + Forbids the use of mutable exports with `var` or `let`. ## Rule Details diff --git a/docs/rules/no-named-as-default-member.md b/docs/rules/no-named-as-default-member.md index da6ae3f1d4..5e0f5069e9 100644 --- a/docs/rules/no-named-as-default-member.md +++ b/docs/rules/no-named-as-default-member.md @@ -1,5 +1,9 @@ # import/no-named-as-default-member +⚠️ This rule _warns_ in the following configs: ☑️ `recommended`, 🚸 `warnings`. + + + Reports use of an exported name as a property on the default export. Rationale: Accessing a property that has a name that is shared by an exported diff --git a/docs/rules/no-named-as-default.md b/docs/rules/no-named-as-default.md index 0421413833..b3715e6c44 100644 --- a/docs/rules/no-named-as-default.md +++ b/docs/rules/no-named-as-default.md @@ -1,5 +1,9 @@ # import/no-named-as-default +⚠️ This rule _warns_ in the following configs: ☑️ `recommended`, 🚸 `warnings`. + + + Reports use of an exported name as the locally imported name of a default export. Rationale: using an exported name as the name of the default export is likely... diff --git a/docs/rules/no-named-default.md b/docs/rules/no-named-default.md index bb8b13bca4..2f3d54b807 100644 --- a/docs/rules/no-named-default.md +++ b/docs/rules/no-named-default.md @@ -1,5 +1,7 @@ # import/no-named-default + + Reports use of a default export as a locally named import. Rationale: the syntax exists to import default exports expressively, let's use it. diff --git a/docs/rules/no-named-export.md b/docs/rules/no-named-export.md index 0ff881e349..13ea63ad73 100644 --- a/docs/rules/no-named-export.md +++ b/docs/rules/no-named-export.md @@ -1,4 +1,6 @@ -# `import/no-named-export` +# import/no-named-export + + Prohibit named exports. Mostly an inverse of [`no-default-export`]. diff --git a/docs/rules/no-namespace.md b/docs/rules/no-namespace.md index 854f65d6f9..5545bce229 100644 --- a/docs/rules/no-namespace.md +++ b/docs/rules/no-namespace.md @@ -1,5 +1,9 @@ # import/no-namespace +🔧 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix). + + + Enforce a convention of not using namespace (a.k.a. "wildcard" `*`) imports. +(fixable) The `--fix` option on the [command line] automatically fixes problems reported by this rule, provided that the namespace object is only used for direct member access, e.g. `namespace.a`. diff --git a/docs/rules/no-nodejs-modules.md b/docs/rules/no-nodejs-modules.md index 225adab222..624c27e059 100644 --- a/docs/rules/no-nodejs-modules.md +++ b/docs/rules/no-nodejs-modules.md @@ -1,4 +1,6 @@ -# import/no-nodejs-modules: No Node.js builtin modules +# import/no-nodejs-modules + + Forbid the use of Node.js builtin modules. Can be useful for client-side web projects that do not have access to those modules. diff --git a/docs/rules/no-relative-packages.md b/docs/rules/no-relative-packages.md index a989c12a23..4919de94e5 100644 --- a/docs/rules/no-relative-packages.md +++ b/docs/rules/no-relative-packages.md @@ -1,5 +1,9 @@ # import/no-relative-packages +🔧 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix). + + + Use this rule to prevent importing packages through relative paths. It's useful in Yarn/Lerna workspaces, were it's possible to import a sibling diff --git a/docs/rules/no-relative-parent-imports.md b/docs/rules/no-relative-parent-imports.md index 7d6e883cff..e5684eb1cf 100644 --- a/docs/rules/no-relative-parent-imports.md +++ b/docs/rules/no-relative-parent-imports.md @@ -1,5 +1,7 @@ # import/no-relative-parent-imports + + Use this rule to prevent imports to folders in relative parent paths. This rule is useful for enforcing tree-like folder structures instead of complex graph-like folder structures. While this restriction might be a departure from Node's default resolution style, it can lead large, complex codebases to be easier to maintain. If you've ever had debates over "where to put files" this rule is for you. diff --git a/docs/rules/no-restricted-paths.md b/docs/rules/no-restricted-paths.md index d22a8b3ea3..344c33bb67 100644 --- a/docs/rules/no-restricted-paths.md +++ b/docs/rules/no-restricted-paths.md @@ -1,4 +1,6 @@ -# import/no-restricted-paths: Restrict which files can be imported in a given folder +# import/no-restricted-paths + + Some projects contain files which are not always meant to be executed in the same environment. For example consider a web application that contains specific code for the server and some specific code for the browser/client. In this case you don’t want to import server-only files in your client code. diff --git a/docs/rules/no-self-import.md b/docs/rules/no-self-import.md index bde063f5d3..8d8491c508 100644 --- a/docs/rules/no-self-import.md +++ b/docs/rules/no-self-import.md @@ -1,4 +1,6 @@ -# Forbid a module from importing itself (`import/no-self-import`) +# import/no-self-import + + Forbid a module from importing itself. This can sometimes happen during refactoring. diff --git a/docs/rules/no-unassigned-import.md b/docs/rules/no-unassigned-import.md index fb3065c48f..6f763e9737 100644 --- a/docs/rules/no-unassigned-import.md +++ b/docs/rules/no-unassigned-import.md @@ -1,4 +1,6 @@ -# import/no-unassigned-import: Forbid unassigned imports +# import/no-unassigned-import + + With both CommonJS' `require` and the ES6 modules' `import` syntax, it is possible to import a module but not to use its result. This can be done explicitly by not assigning the module to as variable. Doing so can mean either of the following things: - The module is imported but not used diff --git a/docs/rules/no-unresolved.md b/docs/rules/no-unresolved.md index 08522deb4c..13f7928877 100644 --- a/docs/rules/no-unresolved.md +++ b/docs/rules/no-unresolved.md @@ -1,5 +1,9 @@ # import/no-unresolved +💼 This rule is enabled in the following configs: ❗ `errors`, ☑️ `recommended`. + + + Ensures an imported module can be resolved to a module on the local filesystem, as defined by standard Node `require.resolve` behavior. diff --git a/docs/rules/no-unused-modules.md b/docs/rules/no-unused-modules.md index 0bd805612b..5cd24bef41 100644 --- a/docs/rules/no-unused-modules.md +++ b/docs/rules/no-unused-modules.md @@ -1,5 +1,7 @@ # import/no-unused-modules + + Reports: - modules without any exports - individual exports not being statically `import`ed or `require`ed from other modules in the same project diff --git a/docs/rules/no-useless-path-segments.md b/docs/rules/no-useless-path-segments.md index 5f01dcb4a2..c8dc67727a 100644 --- a/docs/rules/no-useless-path-segments.md +++ b/docs/rules/no-useless-path-segments.md @@ -1,5 +1,9 @@ # import/no-useless-path-segments +🔧 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix). + + + Use this rule to prevent unnecessary path segments in import and require statements. ## Rule Details diff --git a/docs/rules/no-webpack-loader-syntax.md b/docs/rules/no-webpack-loader-syntax.md index 271c76ca82..e1b7a4bd9d 100644 --- a/docs/rules/no-webpack-loader-syntax.md +++ b/docs/rules/no-webpack-loader-syntax.md @@ -1,5 +1,7 @@ # import/no-webpack-loader-syntax + + Forbid Webpack loader syntax in imports. [Webpack](https://webpack.js.org) allows specifying the [loaders](https://webpack.js.org/concepts/loaders/) to use in the import source string using a special syntax like this: diff --git a/docs/rules/order.md b/docs/rules/order.md index dbda8b2d77..e3deacaf24 100644 --- a/docs/rules/order.md +++ b/docs/rules/order.md @@ -1,4 +1,8 @@ -# import/order: Enforce a convention in module import order +# import/order + +🔧 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix). + + Enforce a convention in the order of `require()` / `import` statements. +(fixable) The `--fix` option on the [command line] automatically fixes problems reported by this rule. diff --git a/docs/rules/prefer-default-export.md b/docs/rules/prefer-default-export.md index 4dabb695a2..38ec166e69 100644 --- a/docs/rules/prefer-default-export.md +++ b/docs/rules/prefer-default-export.md @@ -1,5 +1,7 @@ # import/prefer-default-export + + When there is only a single export from a module, prefer using default export over named export. ## Rule Details diff --git a/docs/rules/unambiguous.md b/docs/rules/unambiguous.md index 5be7d3df22..da77a7453f 100644 --- a/docs/rules/unambiguous.md +++ b/docs/rules/unambiguous.md @@ -1,5 +1,7 @@ # import/unambiguous + + Warn if a `module` could be mistakenly parsed as a `script` by a consumer leveraging [Unambiguous JavaScript Grammar] to determine correct parsing goal. diff --git a/package.json b/package.json index c3ffef586e..c48fade822 100644 --- a/package.json +++ b/package.json @@ -24,14 +24,16 @@ "copy-metafiles": "node --require babel-register ./scripts/copyMetafiles", "watch": "npm run tests-only -- -- --watch", "pretest": "linklocal", - "posttest": "eslint .", + "posttest": "eslint . && npm run update:eslint-docs -- --check", "mocha": "cross-env BABEL_ENV=test nyc mocha", "tests-only": "npm run mocha tests/src", "test": "npm run tests-only", "test-compiled": "npm run prepublish && BABEL_ENV=testCompiled mocha --compilers js:babel-register tests/src", "test-all": "node --require babel-register ./scripts/testAll", "prepublishOnly": "safe-publish-latest && npm run build", - "prepublish": "not-in-publish || npm run prepublishOnly" + "prepublish": "not-in-publish || npm run prepublishOnly", + "preupdate:eslint-docs": "npm run build", + "update:eslint-docs": "eslint-doc-generator --rule-doc-title-format prefix-name --rule-doc-section-options false --split-by meta.docs.category --ignore-config stage-0 --config-emoji recommended,☑️" }, "repository": { "type": "git", @@ -71,6 +73,7 @@ "cross-env": "^4.0.0", "escope": "^3.6.0", "eslint": "^2 || ^3 || ^4 || ^5 || ^6 || ^7.2.0 || ^8", + "eslint-doc-generator": "^0.19.0", "eslint-import-resolver-node": "file:./resolvers/node", "eslint-import-resolver-typescript": "^1.0.2 || ^1.1.1", "eslint-import-resolver-webpack": "file:./resolvers/webpack", diff --git a/src/rules/consistent-type-specifier-style.js b/src/rules/consistent-type-specifier-style.js index 73e0ba92f2..869eea91ff 100644 --- a/src/rules/consistent-type-specifier-style.js +++ b/src/rules/consistent-type-specifier-style.js @@ -40,7 +40,8 @@ module.exports = { meta: { type: 'suggestion', docs: { - description: 'Enforce or ban the use of inline type-only markers for named imports', + category: 'Style guide', + description: 'Enforce or ban the use of inline type-only markers for named imports.', url: docsUrl('consistent-type-specifier-style'), }, fixable: 'code', diff --git a/src/rules/default.js b/src/rules/default.js index 6b917ccae3..6ca918ef66 100644 --- a/src/rules/default.js +++ b/src/rules/default.js @@ -5,6 +5,8 @@ module.exports = { meta: { type: 'problem', docs: { + category: 'Static analysis', + description: 'Ensure a default export is present, given a default import.', url: docsUrl('default'), }, schema: [], diff --git a/src/rules/dynamic-import-chunkname.js b/src/rules/dynamic-import-chunkname.js index 2c59d35e59..87a8523dad 100644 --- a/src/rules/dynamic-import-chunkname.js +++ b/src/rules/dynamic-import-chunkname.js @@ -5,6 +5,8 @@ module.exports = { meta: { type: 'suggestion', docs: { + category: 'Style guide', + description: 'Enforce a leading comment with the webpackChunkName for dynamic imports.', url: docsUrl('dynamic-import-chunkname'), }, schema: [{ diff --git a/src/rules/export.js b/src/rules/export.js index 5d430360a2..da0df1ee75 100644 --- a/src/rules/export.js +++ b/src/rules/export.js @@ -115,6 +115,8 @@ module.exports = { meta: { type: 'problem', docs: { + category: 'Helpful warnings', + description: 'Forbid any invalid exports, i.e. re-export of the same name.', url: docsUrl('export'), }, schema: [], diff --git a/src/rules/exports-last.js b/src/rules/exports-last.js index e89aa7eefe..ed77758d20 100644 --- a/src/rules/exports-last.js +++ b/src/rules/exports-last.js @@ -10,6 +10,8 @@ module.exports = { meta: { type: 'suggestion', docs: { + category: 'Style guide', + description: 'Ensure all exports appear after other statements.', url: docsUrl('exports-last'), }, schema: [], diff --git a/src/rules/extensions.js b/src/rules/extensions.js index 9dad56f863..7d026c787f 100644 --- a/src/rules/extensions.js +++ b/src/rules/extensions.js @@ -63,6 +63,8 @@ module.exports = { meta: { type: 'suggestion', docs: { + category: 'Style guide', + description: 'Ensure consistent use of file extension within the import path.', url: docsUrl('extensions'), }, diff --git a/src/rules/first.js b/src/rules/first.js index 285a377f27..ebead6cf27 100644 --- a/src/rules/first.js +++ b/src/rules/first.js @@ -10,6 +10,8 @@ module.exports = { meta: { type: 'suggestion', docs: { + category: 'Style guide', + description: 'Ensure all imports appear before other statements.', url: docsUrl('first'), }, fixable: 'code', diff --git a/src/rules/group-exports.js b/src/rules/group-exports.js index e9fc432977..63af9d9141 100644 --- a/src/rules/group-exports.js +++ b/src/rules/group-exports.js @@ -5,6 +5,8 @@ import flat from 'array.prototype.flat'; const meta = { type: 'suggestion', docs: { + category: 'Style guide', + description: 'Prefer named exports to be grouped together in a single export declaration', url: docsUrl('group-exports'), }, }; diff --git a/src/rules/imports-first.js b/src/rules/imports-first.js index ba8af48f00..07bb4633de 100644 --- a/src/rules/imports-first.js +++ b/src/rules/imports-first.js @@ -5,6 +5,8 @@ const first = require('./first'); const newMeta = Object.assign({}, first.meta, { deprecated: true, docs: { + category: 'Style guide', + description: 'Replaced by `import/first`.', url: docsUrl('imports-first', '7b25c1cb95ee18acc1531002fd343e1e6031f9ed'), }, }); diff --git a/src/rules/max-dependencies.js b/src/rules/max-dependencies.js index f9bdd12e51..95f34176f5 100644 --- a/src/rules/max-dependencies.js +++ b/src/rules/max-dependencies.js @@ -17,6 +17,8 @@ module.exports = { meta: { type: 'suggestion', docs: { + category: 'Style guide', + description: 'Enforce the maximum number of dependencies a module can have.', url: docsUrl('max-dependencies'), }, diff --git a/src/rules/named.js b/src/rules/named.js index ad1b5e1728..050f835056 100644 --- a/src/rules/named.js +++ b/src/rules/named.js @@ -6,6 +6,8 @@ module.exports = { meta: { type: 'problem', docs: { + category: 'Static analysis', + description: 'Ensure named imports correspond to a named export in the remote file.', url: docsUrl('named'), }, schema: [ diff --git a/src/rules/namespace.js b/src/rules/namespace.js index 405c415cea..3b6019da8d 100644 --- a/src/rules/namespace.js +++ b/src/rules/namespace.js @@ -45,6 +45,8 @@ module.exports = { meta: { type: 'problem', docs: { + category: 'Static analysis', + description: 'Ensure imported namespaces contain dereferenced properties as they are dereferenced.', url: docsUrl('namespace'), }, diff --git a/src/rules/newline-after-import.js b/src/rules/newline-after-import.js index 3f285345f9..36678bfc4e 100644 --- a/src/rules/newline-after-import.js +++ b/src/rules/newline-after-import.js @@ -56,6 +56,8 @@ module.exports = { meta: { type: 'layout', docs: { + category: 'Style guide', + description: 'Enforce a newline after import statements.', url: docsUrl('newline-after-import'), }, fixable: 'whitespace', diff --git a/src/rules/no-absolute-path.js b/src/rules/no-absolute-path.js index fe0a1b6d31..171419d844 100644 --- a/src/rules/no-absolute-path.js +++ b/src/rules/no-absolute-path.js @@ -6,6 +6,8 @@ module.exports = { meta: { type: 'suggestion', docs: { + category: 'Static analysis', + description: 'Forbid import of modules using absolute paths.', url: docsUrl('no-absolute-path'), }, schema: [ makeOptionsSchema() ], diff --git a/src/rules/no-amd.js b/src/rules/no-amd.js index 187273589c..90359cd5fd 100644 --- a/src/rules/no-amd.js +++ b/src/rules/no-amd.js @@ -13,6 +13,8 @@ module.exports = { meta: { type: 'suggestion', docs: { + category: 'Module systems', + description: 'Forbid AMD `require` and `define` calls.', url: docsUrl('no-amd'), }, schema: [], diff --git a/src/rules/no-anonymous-default-export.js b/src/rules/no-anonymous-default-export.js index 106f43b091..d9edcc2b36 100644 --- a/src/rules/no-anonymous-default-export.js +++ b/src/rules/no-anonymous-default-export.js @@ -79,6 +79,8 @@ module.exports = { meta: { type: 'suggestion', docs: { + category: 'Style guide', + description: 'Forbid anonymous values as default exports.', url: docsUrl('no-anonymous-default-export'), }, diff --git a/src/rules/no-commonjs.js b/src/rules/no-commonjs.js index 9e157f46db..7a35fc8a08 100644 --- a/src/rules/no-commonjs.js +++ b/src/rules/no-commonjs.js @@ -69,6 +69,8 @@ module.exports = { meta: { type: 'suggestion', docs: { + category: 'Module systems', + description: 'Forbid CommonJS `require` calls and `module.exports` or `exports.*`.', url: docsUrl('no-commonjs'), }, diff --git a/src/rules/no-cycle.js b/src/rules/no-cycle.js index e261ac40b7..63765c863c 100644 --- a/src/rules/no-cycle.js +++ b/src/rules/no-cycle.js @@ -14,7 +14,11 @@ const traversed = new Set(); module.exports = { meta: { type: 'suggestion', - docs: { url: docsUrl('no-cycle') }, + docs: { + category: 'Static analysis', + description: 'Forbid a module from importing a module with a dependency path back to itself.', + url: docsUrl('no-cycle'), + }, schema: [makeOptionsSchema({ maxDepth: { oneOf: [ diff --git a/src/rules/no-default-export.js b/src/rules/no-default-export.js index ed1aaf8db6..5fc8c40e4c 100644 --- a/src/rules/no-default-export.js +++ b/src/rules/no-default-export.js @@ -4,6 +4,8 @@ module.exports = { meta: { type: 'suggestion', docs: { + category: 'Style guide', + description: 'Forbid default exports.', url: docsUrl('no-default-export'), }, schema: [], diff --git a/src/rules/no-deprecated.js b/src/rules/no-deprecated.js index 4913d389b5..7a35a8e673 100644 --- a/src/rules/no-deprecated.js +++ b/src/rules/no-deprecated.js @@ -16,6 +16,8 @@ module.exports = { meta: { type: 'suggestion', docs: { + category: 'Helpful warnings', + description: 'Forbid imported names marked with `@deprecated` documentation tag.', url: docsUrl('no-deprecated'), }, schema: [], diff --git a/src/rules/no-duplicates.js b/src/rules/no-duplicates.js index efd9583fbc..4aec2d1e77 100644 --- a/src/rules/no-duplicates.js +++ b/src/rules/no-duplicates.js @@ -245,6 +245,8 @@ module.exports = { meta: { type: 'problem', docs: { + category: 'Style guide', + description: 'Forbid repeated import of the same module in multiple places.', url: docsUrl('no-duplicates'), }, fixable: 'code', diff --git a/src/rules/no-dynamic-require.js b/src/rules/no-dynamic-require.js index 27e9a957a7..f334adec67 100644 --- a/src/rules/no-dynamic-require.js +++ b/src/rules/no-dynamic-require.js @@ -25,6 +25,8 @@ module.exports = { meta: { type: 'suggestion', docs: { + category: 'Static analysis', + description: 'Forbid `require()` calls with expressions.', url: docsUrl('no-dynamic-require'), }, schema: [ diff --git a/src/rules/no-empty-named-blocks.js b/src/rules/no-empty-named-blocks.js index 65a8515cf0..114736f168 100644 --- a/src/rules/no-empty-named-blocks.js +++ b/src/rules/no-empty-named-blocks.js @@ -19,6 +19,8 @@ module.exports = { meta: { type: 'suggestion', docs: { + category: 'Helpful warnings', + description: 'Forbid empty named import blocks.', url: docsUrl('no-empty-named-blocks'), }, fixable: 'code', diff --git a/src/rules/no-extraneous-dependencies.js b/src/rules/no-extraneous-dependencies.js index 65c396e672..d6437c2fd1 100644 --- a/src/rules/no-extraneous-dependencies.js +++ b/src/rules/no-extraneous-dependencies.js @@ -254,6 +254,8 @@ module.exports = { meta: { type: 'problem', docs: { + category: 'Helpful warnings', + description: 'Forbid the use of extraneous packages.', url: docsUrl('no-extraneous-dependencies'), }, diff --git a/src/rules/no-import-module-exports.js b/src/rules/no-import-module-exports.js index 4af1e7b453..d40bae88ce 100644 --- a/src/rules/no-import-module-exports.js +++ b/src/rules/no-import-module-exports.js @@ -23,8 +23,8 @@ module.exports = { meta: { type: 'problem', docs: { - description: 'Disallow import statements with module.exports', - category: 'Best Practices', + category: 'Module systems', + description: 'Forbid import statements with CommonJS module.exports.', recommended: true, }, fixable: 'code', diff --git a/src/rules/no-internal-modules.js b/src/rules/no-internal-modules.js index a33f23b475..9d44f5859a 100644 --- a/src/rules/no-internal-modules.js +++ b/src/rules/no-internal-modules.js @@ -9,6 +9,8 @@ module.exports = { meta: { type: 'suggestion', docs: { + category: 'Static analysis', + description: 'Forbid importing the submodules of other modules.', url: docsUrl('no-internal-modules'), }, diff --git a/src/rules/no-mutable-exports.js b/src/rules/no-mutable-exports.js index c506c997cc..75a321b62a 100644 --- a/src/rules/no-mutable-exports.js +++ b/src/rules/no-mutable-exports.js @@ -4,6 +4,8 @@ module.exports = { meta: { type: 'suggestion', docs: { + category: 'Helpful warnings', + description: 'Forbid the use of mutable exports with `var` or `let`.', url: docsUrl('no-mutable-exports'), }, schema: [], diff --git a/src/rules/no-named-as-default-member.js b/src/rules/no-named-as-default-member.js index ef2000e229..0fb0927249 100644 --- a/src/rules/no-named-as-default-member.js +++ b/src/rules/no-named-as-default-member.js @@ -16,6 +16,8 @@ module.exports = { meta: { type: 'suggestion', docs: { + category: 'Helpful warnings', + description: 'Forbid use of exported name as property of default export.', url: docsUrl('no-named-as-default-member'), }, schema: [], diff --git a/src/rules/no-named-as-default.js b/src/rules/no-named-as-default.js index 7c1ef0e04c..c3a35ff64a 100644 --- a/src/rules/no-named-as-default.js +++ b/src/rules/no-named-as-default.js @@ -6,6 +6,8 @@ module.exports = { meta: { type: 'problem', docs: { + category: 'Helpful warnings', + description: 'Forbid use of exported name as identifier of default export.', url: docsUrl('no-named-as-default'), }, schema: [], diff --git a/src/rules/no-named-default.js b/src/rules/no-named-default.js index 6a5c1db703..8745ce3890 100644 --- a/src/rules/no-named-default.js +++ b/src/rules/no-named-default.js @@ -4,6 +4,8 @@ module.exports = { meta: { type: 'suggestion', docs: { + category: 'Style guide', + description: 'Forbid named default exports.', url: docsUrl('no-named-default'), }, schema: [], diff --git a/src/rules/no-named-export.js b/src/rules/no-named-export.js index 6c92ad9cae..b0722f3596 100644 --- a/src/rules/no-named-export.js +++ b/src/rules/no-named-export.js @@ -3,7 +3,11 @@ import docsUrl from '../docsUrl'; module.exports = { meta: { type: 'suggestion', - docs: { url: docsUrl('no-named-export') }, + docs: { + category: 'Style guide', + description: 'Forbid named exports.', + url: docsUrl('no-named-export'), + }, schema: [], }, diff --git a/src/rules/no-namespace.js b/src/rules/no-namespace.js index c615dfff52..4382007a59 100644 --- a/src/rules/no-namespace.js +++ b/src/rules/no-namespace.js @@ -15,6 +15,8 @@ module.exports = { meta: { type: 'suggestion', docs: { + category: 'Style guide', + description: 'Forbid namespace (a.k.a. "wildcard" `*`) imports.', url: docsUrl('no-namespace'), }, fixable: 'code', diff --git a/src/rules/no-nodejs-modules.js b/src/rules/no-nodejs-modules.js index 1e3207d208..a87bff796f 100644 --- a/src/rules/no-nodejs-modules.js +++ b/src/rules/no-nodejs-modules.js @@ -12,6 +12,8 @@ module.exports = { meta: { type: 'suggestion', docs: { + category: 'Module systems', + description: 'Forbid Node.js builtin modules.', url: docsUrl('no-nodejs-modules'), }, schema: [ diff --git a/src/rules/no-relative-packages.js b/src/rules/no-relative-packages.js index 7bf1ce5cea..6b0a627670 100644 --- a/src/rules/no-relative-packages.js +++ b/src/rules/no-relative-packages.js @@ -57,6 +57,8 @@ module.exports = { meta: { type: 'suggestion', docs: { + category: 'Static analysis', + description: 'Forbid importing packages through relative paths.', url: docsUrl('no-relative-packages'), }, fixable: 'code', diff --git a/src/rules/no-relative-parent-imports.js b/src/rules/no-relative-parent-imports.js index 8e3696275b..fd8dcb302f 100644 --- a/src/rules/no-relative-parent-imports.js +++ b/src/rules/no-relative-parent-imports.js @@ -9,6 +9,8 @@ module.exports = { meta: { type: 'suggestion', docs: { + category: 'Static analysis', + description: 'Forbid importing modules from parent directories.', url: docsUrl('no-relative-parent-imports'), }, schema: [makeOptionsSchema()], diff --git a/src/rules/no-restricted-paths.js b/src/rules/no-restricted-paths.js index 9b17975b5c..b8a461fa2d 100644 --- a/src/rules/no-restricted-paths.js +++ b/src/rules/no-restricted-paths.js @@ -16,6 +16,8 @@ module.exports = { meta: { type: 'problem', docs: { + category: 'Static analysis', + description: 'Enforce which files can be imported in a given folder.', url: docsUrl('no-restricted-paths'), }, diff --git a/src/rules/no-self-import.js b/src/rules/no-self-import.js index a5f464b242..0ba0f66694 100644 --- a/src/rules/no-self-import.js +++ b/src/rules/no-self-import.js @@ -23,7 +23,8 @@ module.exports = { meta: { type: 'problem', docs: { - description: 'Forbid a module from importing itself', + category: 'Static analysis', + description: 'Forbid a module from importing itself.', recommended: true, url: docsUrl('no-self-import'), }, diff --git a/src/rules/no-unassigned-import.js b/src/rules/no-unassigned-import.js index 37be903e0b..b790141927 100644 --- a/src/rules/no-unassigned-import.js +++ b/src/rules/no-unassigned-import.js @@ -56,6 +56,8 @@ module.exports = { meta: { type: 'suggestion', docs: { + category: 'Style guide', + description: 'Forbid unassigned imports', url: docsUrl('no-unassigned-import'), }, schema: [ diff --git a/src/rules/no-unresolved.js b/src/rules/no-unresolved.js index dafc7cb13f..8216cdf1f2 100644 --- a/src/rules/no-unresolved.js +++ b/src/rules/no-unresolved.js @@ -12,6 +12,8 @@ module.exports = { meta: { type: 'problem', docs: { + category: 'Static analysis', + description: 'Ensure imports point to a file/module that can be resolved.', url: docsUrl('no-unresolved'), }, diff --git a/src/rules/no-unused-modules.js b/src/rules/no-unused-modules.js index 5feb319036..8f8b4b634c 100644 --- a/src/rules/no-unused-modules.js +++ b/src/rules/no-unused-modules.js @@ -38,14 +38,14 @@ try { }; } catch (e) { const { listFilesToProcess: originalListFilesToProcess } = require('eslint/lib/util/glob-util'); - + listFilesToProcess = function (src, extensions) { const patterns = src.reduce((carry, pattern) => { return carry.concat(extensions.map((extension) => { return /\*\*|\*\./.test(pattern) ? pattern : `${pattern}/**/*${extension}`; })); }, src.slice()); - + return originalListFilesToProcess(patterns); }; } @@ -408,7 +408,11 @@ const fileIsInPkg = file => { module.exports = { meta: { type: 'suggestion', - docs: { url: docsUrl('no-unused-modules') }, + docs: { + category: 'Helpful warnings', + description: 'Forbid modules without exports, or exports without matching import in another module.', + url: docsUrl('no-unused-modules'), + }, schema: [{ properties: { src: { diff --git a/src/rules/no-useless-path-segments.js b/src/rules/no-useless-path-segments.js index c0156d09f8..a328be2465 100644 --- a/src/rules/no-useless-path-segments.js +++ b/src/rules/no-useless-path-segments.js @@ -40,6 +40,8 @@ module.exports = { meta: { type: 'suggestion', docs: { + category: 'Static analysis', + description: 'Forbid unnecessary path segments in import and require statements.', url: docsUrl('no-useless-path-segments'), }, diff --git a/src/rules/no-webpack-loader-syntax.js b/src/rules/no-webpack-loader-syntax.js index e517207bac..faedeb4373 100644 --- a/src/rules/no-webpack-loader-syntax.js +++ b/src/rules/no-webpack-loader-syntax.js @@ -13,6 +13,8 @@ module.exports = { meta: { type: 'problem', docs: { + category: 'Static analysis', + description: 'Forbid webpack loader syntax in imports.', url: docsUrl('no-webpack-loader-syntax'), }, schema: [], diff --git a/src/rules/order.js b/src/rules/order.js index e8d023dfe6..dc9da64f22 100644 --- a/src/rules/order.js +++ b/src/rules/order.js @@ -589,6 +589,8 @@ module.exports = { meta: { type: 'suggestion', docs: { + category: 'Style guide', + description: 'Enforce a convention in module import order.', url: docsUrl('order'), }, diff --git a/src/rules/prefer-default-export.js b/src/rules/prefer-default-export.js index 230efad12f..d1b134cfc1 100644 --- a/src/rules/prefer-default-export.js +++ b/src/rules/prefer-default-export.js @@ -6,6 +6,8 @@ module.exports = { meta: { type: 'suggestion', docs: { + category: 'Style guide', + description: 'Prefer a default export if module exports a single name.', url: docsUrl('prefer-default-export'), }, schema: [], diff --git a/src/rules/unambiguous.js b/src/rules/unambiguous.js index 576b3379ee..91152ea2af 100644 --- a/src/rules/unambiguous.js +++ b/src/rules/unambiguous.js @@ -10,6 +10,8 @@ module.exports = { meta: { type: 'suggestion', docs: { + category: 'Module systems', + description: 'Forbid potentially ambiguous parse goal (`script` vs. `module`).', url: docsUrl('unambiguous'), }, schema: [],