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

docs: Create a shared settings document #115

Merged
merged 4 commits into from
Sep 25, 2023
Merged

docs: Create a shared settings document #115

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
ffa1a05
docs: Create a shared settings document
scagood Sep 11, 2023
678c62b
docs: add links to shared settings in no-missing-import
scagood Sep 11, 2023
31ac6ca
docs: Reference shared settings for most shared settings
scagood Sep 11, 2023
2f27eb8
docs: Disable "ruleDocSectionOptions" in "eslint-doc-generator"
scagood Sep 21, 2023
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
1 change: 1 addition & 0 deletions .eslint-doc-generatorrc.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ const config = {
["flat/recommended", "☑️"],
["flat/mixed-esm-and-cjs", "🟠"],
],
ruleDocSectionOptions: false,
}

module.exports = config
36 changes: 6 additions & 30 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 @@ -92,39 +92,15 @@ import logo from "./logo.png"

### Shared Settings

The following options can be set by [shared settings](http://eslint.org/docs/user-guide/configuring.html#adding-shared-settings).
Several rules have the same option, but we can set this option at once.
#### tsconfigPath

#### typescriptExtensionMap

Adds the ability to change the extension mapping when converting between typescript and javascript

You can also use the [typescript compiler jsx options](https://www.typescriptlang.org/tsconfig#jsx) to automatically use the correct mapping.
This can be configured in the shared settings [`settings.tsconfigPath`](../shared-settings.md#tsconfigpath).
Please see the shared settings documentation for more information.

If this option is left undefined we:

1. Check your `tsconfig.json` `compilerOptions.jsx`
2. Return the default mapping (jsx = `preserve`)
#### typescriptExtensionMap

```js
// .eslintrc.js
module.exports = {
"settings": {
"node": {
"typescriptExtensionMap": [
[ "", ".js" ],
[ ".ts", ".js" ],
[ ".cts", ".cjs" ],
[ ".mts", ".mjs" ],
[ ".tsx", ".jsx" ],
]
}
},
"rules": {
"n/file-extension-in-import": "error"
}
}
```
This can be configured in the shared settings [`settings.typescriptExtensionMap`](../shared-settings.md#typescriptextensionmap).
Please see the shared settings documentation for more information.

## 🔎 Implementation

Expand Down
51 changes: 6 additions & 45 deletions docs/rules/no-extraneous-import.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,57 +26,18 @@ This rule warns `import` declarations of extraneous modules.

#### allowModules

Some platforms have additional embedded modules.
For example, Electron has `electron` module.

We can specify additional embedded modules with this option.
This option is an array of strings as module names.

```json
{
"rules": {
"n/no-extraneous-import": ["error", {
"allowModules": ["electron"]
}]
}
}
```
This can be configured in the rule options or as a shared setting [`settings.allowModules`](../shared-settings.md#allowmodules).
Please see the shared settings documentation for more information.

#### resolvePaths

Adds additional paths to try for when resolving imports.
If a path is relative, it will be resolved from CWD.

Default is `[]`
This can be configured in the rule options or as a shared setting [`settings.resolvePaths`](../shared-settings.md#resolvepaths).
Please see the shared settings documentation for more information.

#### convertPath

- `exclude`: TODO
- `include`: TODO
- `replace`: TODO
Comment on lines -54 to -56
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@bmish it causes eslint-docs-generator to report an error, when moving the options docs to another page(shared-settings). Is there a way to ignore the error?

I'm glad to help making a PR in eslint-docs-generagor if you want. 😄

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since it looks like the rule options are all mentioned in a shared doc instead, it should be safe for you to use the option --rule-doc-section-options false to disable the check (https://github.com/bmish/eslint-doc-generator#configuration-options).

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The issue is that we mention the root option, and reference it, eg in no-extraneous-import:

We reference convertPath docs/rules/no-extraneous-import.md#convertpath and point to the shared setting docs/shared-settings.md#convertpath

The schema is defined here: lib/rules/no-extraneous-import.js#L27-L31

The issue is that the missing options are child properties of convertPath:

  • convertPath.include
  • convertPath.exclude
  • convertPath.replace
`no-extraneous-import` rule doc should have included rule option: include
`no-extraneous-import` rule doc should have included rule option: exclude
`no-extraneous-import` rule doc should have included rule option: replace

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The existing eslint-doc-generator option --rule-doc-section-options is all-or-nothing in terms of checking for the options section and any named options it can detect. So with your planned design, you may just have to disable the option. Let me know if you have ideas for more granular options to control these checks.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

wonderful job! The option looks useful! 👍

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We can turn off this option for now and use that option when it was supported in eslint-doc-generator.
wdyt?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

mmm, I don't love the option, as you'd need to be more vigilant in PRs.

If that is fine with you, then we can proceed with the option.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't love it, but its disabled here:

2f27eb8 (#115)

Copy link
Member

@bmish bmish Sep 22, 2023 •
edited

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@scagood --rule-doc-section-options-depth (as it customizes the existing --rule-doc-section-options option behavior) sounds like an interesting idea. Would you like to open an issue in eslint-doc-generator to suggest it so we can track this? I'm open to considering it if you feel that it's necessary and ideally that it would be useful to more than just this plugin.

In the meantime, you should proceed without this and just disable --rule-doc-section-options for now.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

to avoid breaking changes:

  • --rule-doc-section-options=true can be treated as depth: Infinity
  • --rule-doc-section-options=false as depth: 0


### Shared Settings

The following options can be set by [shared settings](http://eslint.org/docs/user-guide/configuring.html#adding-shared-settings).
Several rules have the same option, but we can set this option at once.

- `allowModules`
- `resolvePaths`

```js
// .eslintrc.js
module.exports = {
"settings": {
"node": {
"allowModules": ["electron"],
"resolvePaths": [__dirname],
}
},
"rules": {
"n/no-extraneous-import": "error"
}
}
```
This can be configured in the rule options or as a shared setting [`settings.convertPath`](../shared-settings.md#convertpath).
Please see the shared settings documentation for more information.

## 🔎 Implementation

Expand Down
63 changes: 10 additions & 53 deletions docs/rules/no-extraneous-require.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,66 +27,23 @@ This rule warns `require()` of extraneous modules.

#### allowModules

Some platforms have additional embedded modules.
For example, Electron has `electron` module.

We can specify additional embedded modules with this option.
This option is an array of strings as module names.

```json
{
"rules": {
"n/no-extraneous-require": ["error", {
"allowModules": ["electron"]
}]
}
}
```
This can be configured in the rule options or as a shared setting [`settings.allowModules`](../shared-settings.md#allowmodules).
Please see the shared settings documentation for more information.

#### resolvePaths

Adds additional paths to try for when resolving imports.
If a path is relative, it will be resolved from CWD.
This can be configured in the rule options or as a shared setting [`settings.resolvePaths`](../shared-settings.md#resolvepaths).
Please see the shared settings documentation for more information.

Default is `[]`

#### tryExtensions

When an import path does not exist, this rule checks whether or not any of `path.js`, `path.json`, and `path.node` exists.
`tryExtensions` option is the extension list this rule uses at the time.
#### convertPath

Default is `[".js", ".json", ".node"]`.
This can be configured in the rule options or as a shared setting [`settings.convertPath`](../shared-settings.md#convertpath).
Please see the shared settings documentation for more information.

#### convertPath
#### tryExtensions

- `exclude`: TODO
- `include`: TODO
- `replace`: TODO

### Shared Settings

The following options can be set by [shared settings](http://eslint.org/docs/user-guide/configuring.html#adding-shared-settings).
Several rules have the same option, but we can set this option at once.

- `allowModules`
- `resolvePaths`
- `tryExtensions`

```js
// .eslintrc.js
module.exports = {
"settings": {
"node": {
"allowModules": ["electron"],
"resolvePaths": [__dirname],
"tryExtensions": [".js", ".json", ".node"]
}
},
"rules": {
"n/no-extraneous-require": "error"
}
}
```
This can be configured in the rule options or as a shared setting [`settings.tryExtensions`](../shared-settings.md#tryextensions).
Please see the shared settings documentation for more information.

## 🔎 Implementation

Expand Down
82 changes: 9 additions & 73 deletions docs/rules/no-missing-import.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,87 +46,23 @@ import existingModule from "existing-module";

#### allowModules

Some platforms have additional embedded modules.
For example, Electron has `electron` module.

We can specify additional embedded modules with this option.
This option is an array of strings as module names.

```json
{
"rules": {
"n/no-missing-import": ["error", {
"allowModules": ["electron"]
}]
}
}
```
This can be configured in the rule options or as a shared setting [`settings.allowModules`](../shared-settings.md#allowmodules).
Please see the shared settings documentation for more information.

#### resolvePaths

Adds additional paths to try for when resolving imports.
If a path is relative, it will be resolved from CWD.

Default is `[]`

#### typescriptExtensionMap

Adds the ability to change the extension mapping when converting between typescript and javascript

You can also use the [typescript compiler jsx options](https://www.typescriptlang.org/tsconfig#jsx) to automatically use the correct mapping.

If this option is left undefined we:

1. Check the Shared Settings
2. Check your `tsconfig.json` `compilerOptions.jsx`
3. Return the default mapping (jsx = `preserve`)

Default is:

```json
[
[ "", ".js" ],
[ ".ts", ".js" ],
[ ".cts", ".cjs" ],
[ ".mts", ".mjs" ],
[ ".tsx", ".jsx" ],
]
```
This can be configured in the rule options or as a shared setting [`settings.resolvePaths`](../shared-settings.md#resolvepaths).
Please see the shared settings documentation for more information.

#### tsconfigPath

Adds the ability to specify the tsconfig used by the typescriptExtensionMap tool.

### Shared Settings
This can be configured in the rule options or as a shared setting [`settings.tsconfigPath`](../shared-settings.md#tsconfigpath).
Please see the shared settings documentation for more information.

The following options can be set by [shared settings](http://eslint.org/docs/user-guide/configuring.html#adding-shared-settings).
Several rules have the same option, but we can set this option at once.

- `allowModules`
- `resolvePaths`
- `typescriptExtensionMap`
#### typescriptExtensionMap

```js
// .eslintrc.js
module.exports = {
"settings": {
"node": {
"allowModules": ["electron"],
"resolvePaths": [__dirname],
"typescriptExtensionMap": [
[ "", ".js" ],
[ ".ts", ".js" ],
[ ".cts", ".cjs" ],
[ ".mts", ".mjs" ],
[ ".tsx", ".js" ],
]
}
},
"rules": {
"n/no-missing-import": "error"
}
}
```
This can be configured in the rule options or as a shared setting [`settings.typescriptExtensionMap`](../shared-settings.md#typescriptextensionmap).
Please see the shared settings documentation for more information.

## 🔎 Implementation

Expand Down
90 changes: 11 additions & 79 deletions docs/rules/no-missing-require.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,96 +52,28 @@ var foo = require(FOO_NAME);

#### allowModules

Some platforms have additional embedded modules.
For example, Electron has `electron` module.

We can specify additional embedded modules with this option.
This option is an array of strings as module names.

```json
{
"rules": {
"n/no-missing-require": ["error", {
"allowModules": ["electron"]
}]
}
}
```
This can be configured in the rule options or as a shared setting [`settings.allowModules`](../shared-settings.md#allowmodules).
Please see the shared settings documentation for more information.

#### resolvePaths

Adds additional paths to try for when resolving a require.
If a path is relative, it will be resolved from CWD.

Default is `[]`
This can be configured in the rule options or as a shared setting [`settings.resolvePaths`](../shared-settings.md#resolvepaths).
Please see the shared settings documentation for more information.

#### tryExtensions

When an import path does not exist, this rule checks whether or not any of `path.js`, `path.json`, and `path.node` exists.
`tryExtensions` option is the extension list this rule uses at the time.

Default is `[".js", ".json", ".node"]`.

#### typescriptExtensionMap

Adds the ability to change the extension mapping when converting between typescript and javascript

You can also use the [typescript compiler jsx options](https://www.typescriptlang.org/tsconfig#jsx) to automatically use the correct mapping.

If this option is left undefined we:

1. Check the Shared Settings
2. Check your `tsconfig.json` `compilerOptions.jsx`
3. Return the default mapping (jsx = `preserve`)

Default is:

```json
[
[ "", ".js" ],
[ ".ts", ".js" ],
[ ".cts", ".cjs" ],
[ ".mts", ".mjs" ],
[ ".tsx", ".jsx" ],
]
```
This can be configured in the rule options or as a shared setting [`settings.tryExtensions`](../shared-settings.md#tryextensions).
Please see the shared settings documentation for more information.

#### tsconfigPath

Adds the ability to specify the tsconfig used by the typescriptExtensionMap tool.

### Shared Settings
This can be configured in the rule options or as a shared setting [`settings.tsconfigPath`](../shared-settings.md#tsconfigpath).
Please see the shared settings documentation for more information.

The following options can be set by [shared settings](http://eslint.org/docs/user-guide/configuring.html#adding-shared-settings).
Several rules have the same option, but we can set this option at once.

- `allowModules`
- `resolvePaths`
- `tryExtensions`
- `typescriptExtensionMap`
#### typescriptExtensionMap

```js
// .eslintrc.js
module.exports = {
"settings": {
"node": {
"allowModules": ["electron"],
"resolvePaths": [__dirname],
"tryExtensions": [".js", ".json", ".node"],
"typescriptExtensionMap": [
[ "", ".js" ],
[ ".ts", ".js" ],
[ ".cts", ".cjs" ],
[ ".mts", ".mjs" ],
[ ".tsx", ".js" ],
]
}
},
"rules": {
"n/no-missing-require": "error"
}
}
```
This can be configured in the rule options or as a shared setting [`settings.typescriptExtensionMap`](../shared-settings.md#typescriptextensionmap).
Please see the shared settings documentation for more information.

## 🔎 Implementation

Expand Down