Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Cleanup docs, add markdownlint, tweak eslint-doc-generator options #64

Merged
merged 1 commit into from
Nov 10, 2022
Merged

Cleanup docs, add markdownlint, tweak eslint-doc-generator options #64

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
9 changes: 9 additions & 0 deletions .markdownlint.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
{
"line-length": false,
"no-inline-html": {
"allowed_elements": ["details"]
},
"ul-style": {
"style": "dash"
}
}
3 changes: 3 additions & 0 deletions .markdownlintignore
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
CHANGELOG.md
LICENSE
node_modules
66 changes: 33 additions & 33 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,43 +57,41 @@ npm install --save-dev eslint eslint-plugin-n

<!-- begin auto-generated rules list -->

💼 Configurations enabled in.\
✅ Set in the `recommended` configuration.\
☑️ Set in the `recommended-module` configuration.\
✔️ Set in the `recommended-script` configuration.\
💼 [Configurations](https://github.com/eslint-community/eslint-plugin-n#-configs) enabled in.\
✅ Set in the `recommended` [configuration](https://github.com/eslint-community/eslint-plugin-n#-configs).\
🔧 Automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/user-guide/command-line-interface#--fix).\
❌ Deprecated.

### Best Practices

| Name | Description | 💼 | 🔧 | ❌ |
| :--------------------------------------------------- | :----------------------- | :------ | :- | :- |
| [no-deprecated-api](docs/rules/no-deprecated-api.md) | disallow deprecated APIs | ✅ ☑️ ✔️ | | |
| Name | Description | 💼 | 🔧 | ❌ |
| :--------------------------------------------------- | :----------------------- | :- | :- | :- |
| [no-deprecated-api](docs/rules/no-deprecated-api.md) | disallow deprecated APIs | ✅ | | |

### Possible Errors

| Name                                  | Description | 💼 | 🔧 | ❌ |
| :------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------- | :------ | :- | :- |
| [handle-callback-err](docs/rules/handle-callback-err.md) | require error handling in callbacks | | | |
| [no-callback-literal](docs/rules/no-callback-literal.md) | enforce Node.js-style error-first callback pattern is followed | | | |
| [no-exports-assign](docs/rules/no-exports-assign.md) | disallow the assignment to `exports` | ✅ ☑️ ✔️ | | |
| [no-extraneous-import](docs/rules/no-extraneous-import.md) | disallow `import` declarations which import extraneous modules | ✅ ☑️ ✔️ | | |
| [no-extraneous-require](docs/rules/no-extraneous-require.md) | disallow `require()` expressions which import extraneous modules | ✅ ☑️ ✔️ | | |
| [no-hide-core-modules](docs/rules/no-hide-core-modules.md) | disallow third-party modules which are hiding core modules | | | ❌ |
| [no-missing-import](docs/rules/no-missing-import.md) | disallow `import` declarations which import non-existence modules | ✅ ☑️ ✔️ | | |
| [no-missing-require](docs/rules/no-missing-require.md) | disallow `require()` expressions which import non-existence modules | ✅ ☑️ ✔️ | | |
| [no-new-require](docs/rules/no-new-require.md) | disallow `new` operators with calls to `require` | | | |
| [no-path-concat](docs/rules/no-path-concat.md) | disallow string concatenation with `__dirname` and `__filename` | | | |
| [no-process-exit](docs/rules/no-process-exit.md) | disallow the use of `process.exit()` | ✅ ☑️ ✔️ | | |
| [no-unpublished-bin](docs/rules/no-unpublished-bin.md) | disallow `bin` files that npm ignores | ✅ ☑️ ✔️ | | |
| [no-unpublished-import](docs/rules/no-unpublished-import.md) | disallow `import` declarations which import private modules | ✅ ☑️ ✔️ | | |
| [no-unpublished-require](docs/rules/no-unpublished-require.md) | disallow `require()` expressions which import private modules | ✅ ☑️ ✔️ | | |
| [no-unsupported-features](docs/rules/no-unsupported-features.md) | disallow unsupported ECMAScript features on the specified version | | | ❌ |
| [no-unsupported-features/es-builtins](docs/rules/no-unsupported-features/es-builtins.md) | disallow unsupported ECMAScript built-ins on the specified version | ✅ ☑️ ✔️ | | |
| [no-unsupported-features/es-syntax](docs/rules/no-unsupported-features/es-syntax.md) | disallow unsupported ECMAScript syntax on the specified version | ✅ ☑️ ✔️ | | |
| [no-unsupported-features/node-builtins](docs/rules/no-unsupported-features/node-builtins.md) | disallow unsupported Node.js built-in APIs on the specified version | ✅ ☑️ ✔️ | | |
| [process-exit-as-throw](docs/rules/process-exit-as-throw.md) | require that `process.exit()` expressions use the same code path as `throw` | ✅ ☑️ ✔️ | | |
| [shebang](docs/rules/shebang.md) | require correct usage of shebang | ✅ ☑️ ✔️ | 🔧 | |
| Name                                  | Description | 💼 | 🔧 | ❌ |
| :------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------- | :- | :- | :- |
| [handle-callback-err](docs/rules/handle-callback-err.md) | require error handling in callbacks | | | |
| [no-callback-literal](docs/rules/no-callback-literal.md) | enforce Node.js-style error-first callback pattern is followed | | | |
| [no-exports-assign](docs/rules/no-exports-assign.md) | disallow the assignment to `exports` | ✅ | | |
| [no-extraneous-import](docs/rules/no-extraneous-import.md) | disallow `import` declarations which import extraneous modules | ✅ | | |
| [no-extraneous-require](docs/rules/no-extraneous-require.md) | disallow `require()` expressions which import extraneous modules | ✅ | | |
| [no-hide-core-modules](docs/rules/no-hide-core-modules.md) | disallow third-party modules which are hiding core modules | | | ❌ |
| [no-missing-import](docs/rules/no-missing-import.md) | disallow `import` declarations which import non-existence modules | ✅ | | |
| [no-missing-require](docs/rules/no-missing-require.md) | disallow `require()` expressions which import non-existence modules | ✅ | | |
| [no-new-require](docs/rules/no-new-require.md) | disallow `new` operators with calls to `require` | | | |
| [no-path-concat](docs/rules/no-path-concat.md) | disallow string concatenation with `__dirname` and `__filename` | | | |
| [no-process-exit](docs/rules/no-process-exit.md) | disallow the use of `process.exit()` | ✅ | | |
| [no-unpublished-bin](docs/rules/no-unpublished-bin.md) | disallow `bin` files that npm ignores | ✅ | | |
| [no-unpublished-import](docs/rules/no-unpublished-import.md) | disallow `import` declarations which import private modules | ✅ | | |
| [no-unpublished-require](docs/rules/no-unpublished-require.md) | disallow `require()` expressions which import private modules | ✅ | | |
| [no-unsupported-features](docs/rules/no-unsupported-features.md) | disallow unsupported ECMAScript features on the specified version | | | ❌ |
| [no-unsupported-features/es-builtins](docs/rules/no-unsupported-features/es-builtins.md) | disallow unsupported ECMAScript built-ins on the specified version | ✅ | | |
| [no-unsupported-features/es-syntax](docs/rules/no-unsupported-features/es-syntax.md) | disallow unsupported ECMAScript syntax on the specified version | ✅ | | |
| [no-unsupported-features/node-builtins](docs/rules/no-unsupported-features/node-builtins.md) | disallow unsupported Node.js built-in APIs on the specified version | ✅ | | |
| [process-exit-as-throw](docs/rules/process-exit-as-throw.md) | require that `process.exit()` expressions use the same code path as `throw` | ✅ | | |
| [shebang](docs/rules/shebang.md) | require correct usage of shebang | ✅ | 🔧 | |

### Stylistic Issues

Expand Down Expand Up @@ -124,11 +122,13 @@ npm install --save-dev eslint eslint-plugin-n

This plugin provides three configs:

- `plugin:n/recommended` considers both CommonJS and ES Modules. If [`"type":"module"` field](https://medium.com/@nodejs/announcing-a-new-experimental-modules-1be8d2d6c2ff#b023) existed in package.json then it considers files as ES Modules. Otherwise it considers files as CommonJS. In addition, it considers `*.mjs` files as ES Modules and `*.cjs` files as CommonJS.
- `plugin:n/recommended-module` considers all files as ES Modules.
- `plugin:n/recommended-script` considers all files as CommonJS.
| Name | Description |
| :-- | :-- |
| `plugin:n/recommended` | Considers both CommonJS and ES Modules. If [`"type":"module"` field](https://medium.com/@nodejs/announcing-a-new-experimental-modules-1be8d2d6c2ff#b023) existed in package.json then it considers files as ES Modules. Otherwise it considers files as CommonJS. In addition, it considers `*.mjs` files as ES Modules and `*.cjs` files as CommonJS. |
| `plugin:n/recommended-module` | Considers all files as ES Modules. |
| `plugin:n/recommended-script` | Considers all files as CommonJS. |

Those preset config:
These preset configs:

- enable [no-process-exit](http://eslint.org/docs/rules/no-process-exit) rule because [the official document](https://nodejs.org/api/process.html#process_process_exit_code) does not recommend a use of `process.exit()`.
- enable plugin rules which are given ✅ in the above table.
Expand Down
4 changes: 2 additions & 2 deletions docs/rules/callback-return.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -102,8 +102,8 @@ function bar(err, send) {

Because it is difficult to understand the meaning of a program through static analysis, this rule has limitations:

* *false negatives* when this rule reports correct code, but the program calls the callback more than one time (which is incorrect behavior)
* *false positives* when this rule reports incorrect code, but the program calls the callback only one time (which is correct behavior)
- *false negatives* when this rule reports correct code, but the program calls the callback more than one time (which is incorrect behavior)
- *false positives* when this rule reports incorrect code, but the program calls the callback only one time (which is correct behavior)

#### Passing the callback by reference

Expand Down
12 changes: 6 additions & 6 deletions docs/rules/exports-style.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ In this case, `exports.bar` will be lost since only the instance of `module.expo

This rule enforces the export style.

If you use `module.exports`, this rule disallows `exports`.<br>
If you use `module.exports`, this rule disallows `exports`.\
If you use `exports`, this rule disallows `module.exports`.

You can select it by an option.
Expand All @@ -48,7 +48,7 @@ This rule has a string option.

#### module.exports

Examples of :-1: **incorrect** code for the `"module.exports"` option:
Examples of 👎 **incorrect** code for the `"module.exports"` option:

```js
/*eslint n/exports-style: ["error", "module.exports"]*/
Expand All @@ -57,7 +57,7 @@ exports.foo = 1
exports.bar = 2
```

Examples of :+1: **correct** code for the `"module.exports"` option:
Examples of 👍 **correct** code for the `"module.exports"` option:

```js
/*eslint n/exports-style: ["error", "module.exports"]*/
Expand All @@ -72,7 +72,7 @@ module.exports.baz = 3

#### exports

Examples of :-1: **incorrect** code for the `"exports"` option:
Examples of 👎 **incorrect** code for the `"exports"` option:

```js
/*eslint n/exports-style: ["error", "exports"]*/
Expand All @@ -85,7 +85,7 @@ module.exports = {
module.exports.baz = 3
```

Examples of :+1: **correct** code for the `"exports"` option:
Examples of 👍 **correct** code for the `"exports"` option:

```js
/*eslint n/exports-style: ["error", "exports"]*/
Expand All @@ -96,7 +96,7 @@ exports.bar = 2

#### allowBatchAssign

Examples of :+1: **correct** code for the `"exports"` and `{"allowBatchAssign": true}` option:
Examples of 👍 **correct** code for the `"exports"` and `{"allowBatchAssign": true}` option:

```js
/*eslint n/exports-style: ["error", "exports", {"allowBatchAssign": true}]*/
Expand Down
10 changes: 5 additions & 5 deletions docs/rules/file-extension-in-import.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,15 +41,15 @@ This rule has a string option and an object option.

#### always

Examples of :-1: **incorrect** code for the `"always"` option:
Examples of 👎 **incorrect** code for the `"always"` option:

```js
/*eslint n/file-extension-in-import: ["error", "always"]*/

import foo from "./path/to/a/file"
```

Examples of :+1: **correct** code for the `"always"` option:
Examples of 👍 **correct** code for the `"always"` option:

```js
/*eslint n/file-extension-in-import: ["error", "always"]*/
Expand All @@ -60,15 +60,15 @@ import foo from "./path/to/a/file.js"

#### never

Examples of :-1: **incorrect** code for the `"never"` option:
Examples of 👎 **incorrect** code for the `"never"` option:

```js
/*eslint n/file-extension-in-import: ["error", "never"]*/

import foo from "./path/to/a/file.js"
```

Examples of :+1: **correct** code for the `"never"` option:
Examples of 👍 **correct** code for the `"never"` option:

```js
/*eslint n/file-extension-in-import: ["error", "never"]*/
Expand All @@ -79,7 +79,7 @@ import foo from "./path/to/a/file"

#### .xxx

Examples of :+1: **correct** code for the `["always", { ".js": "never" }]` option:
Examples of 👍 **correct** code for the `["always", { ".js": "never" }]` option:

```js
/*eslint n/file-extension-in-import: ["error", "always", { ".js": "never" }]*/
Expand Down
6 changes: 3 additions & 3 deletions docs/rules/handle-callback-err.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,9 +68,9 @@ so you need a more flexible configuration to ensure that the rule reports all un

If the configured name of the error variable begins with a `^` it is considered to be a regexp pattern.

* If the option is `"^(err|error|anySpecificError)$"`, the rule reports unhandled errors where the parameter name can be `err`, `error` or `anySpecificError`.
* If the option is `"^.+Error$"`, the rule reports unhandled errors where the parameter name ends with `Error` (for example, `connectionError` or `validationError` will match).
* If the option is `"^.*(e|E)rr"`, the rule reports unhandled errors where the parameter name matches any string that contains `err` or `Err` (for example, `err`, `error`, `anyError`, `some_err` will match).
- If the option is `"^(err|error|anySpecificError)$"`, the rule reports unhandled errors where the parameter name can be `err`, `error` or `anySpecificError`.
- If the option is `"^.+Error$"`, the rule reports unhandled errors where the parameter name ends with `Error` (for example, `connectionError` or `validationError` will match).
- If the option is `"^.*(e|E)rr"`, the rule reports unhandled errors where the parameter name matches any string that contains `err` or `Err` (for example, `err`, `error`, `anyError`, `some_err` will match).

## 🔎 Implementation

Expand Down
4 changes: 2 additions & 2 deletions docs/rules/no-callback-literal.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ When invoking a callback function which uses the Node.js error-first callback pa

When a function is named `cb` or `callback`, then it must be invoked with a first argument that is `undefined`, `null`, an `Error` class, or a subclass or `Error`.

Examples of :-1: **incorrect** code for this rule:
Examples of 👎 **incorrect** code for this rule:

```js
/*eslint n/no-callback-literal: "error" */
Expand All @@ -18,7 +18,7 @@ cb({ a: 1 });
callback(0);
```

Examples of :+1: **correct** code for this rule:
Examples of 👍 **correct** code for this rule:

```js
/*eslint n/no-callback-literal: "error" */
Expand Down
8 changes: 4 additions & 4 deletions docs/rules/no-deprecated-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Disallow deprecated APIs (`n/no-deprecated-api`)

💼 This rule is enabled in the following configs: ✅ `recommended`, ☑️ `recommended-module`, ✔️ `recommended-script`.
💼 This rule is enabled in the ✅ `recommended` [config](https://github.com/eslint-community/eslint-plugin-n#-configs).

<!-- end auto-generated rule header -->

Expand All @@ -9,7 +9,7 @@ The community is going to remove those API from Node in future, so we should not

## 📖 Rule Details

Examples of :-1: **incorrect** code for this rule:
Examples of 👎 **incorrect** code for this rule:

```js
/*eslint n/no-deprecated-api: "error" */
Expand Down Expand Up @@ -272,7 +272,7 @@ This option can include the following values:
- `util._extend`
- `vm.runInDebugContext`

Examples of :+1: **correct** code for the `{"ignoreModuleItems": ["new buffer.Buffer()"]}`:
Examples of 👍 **correct** code for the `{"ignoreModuleItems": ["new buffer.Buffer()"]}`:

```js
/*eslint n/no-deprecated-api: [error, {ignoreModuleItems: ["new buffer.Buffer()"]}] */
Expand Down Expand Up @@ -304,7 +304,7 @@ This option can include the following values:
- `process.binding`
- `process.env.NODE_REPL_HISTORY_FILE`

Examples of :+1: **correct** code for the `{"ignoreGlobalItems": ["new Buffer()"]}`:
Examples of 👍 **correct** code for the `{"ignoreGlobalItems": ["new Buffer()"]}`:

```js
/*eslint n/no-deprecated-api: [error, {ignoreGlobalItems: ["new Buffer()"]}] */
Expand Down
2 changes: 1 addition & 1 deletion docs/rules/no-exports-assign.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Disallow the assignment to `exports` (`n/no-exports-assign`)

💼 This rule is enabled in the following configs: ✅ `recommended`, ☑️ `recommended-module`, ✔️ `recommended-script`.
💼 This rule is enabled in the ✅ `recommended` [config](https://github.com/eslint-community/eslint-plugin-n#-configs).

<!-- end auto-generated rule header -->

Expand Down
2 changes: 1 addition & 1 deletion docs/rules/no-extraneous-import.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Disallow `import` declarations which import extraneous modules (`n/no-extraneous-import`)

💼 This rule is enabled in the following configs: ✅ `recommended`, ☑️ `recommended-module`, ✔️ `recommended-script`.
💼 This rule is enabled in the ✅ `recommended` [config](https://github.com/eslint-community/eslint-plugin-n#-configs).

<!-- end auto-generated rule header -->

Expand Down
2 changes: 1 addition & 1 deletion docs/rules/no-extraneous-require.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Disallow `require()` expressions which import extraneous modules (`n/no-extraneous-require`)

💼 This rule is enabled in the following configs: ✅ `recommended`, ☑️ `recommended-module`, ✔️ `recommended-script`.
💼 This rule is enabled in the ✅ `recommended` [config](https://github.com/eslint-community/eslint-plugin-n#-configs).

<!-- end auto-generated rule header -->

Expand Down