From c482c01eedd4395dbfd4e8a7354f352426a5a491 Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Tue, 3 Sep 2024 12:15:23 -0400 Subject: [PATCH 1/8] docs: inject option descriptions into rule docs when possible --- .../docs/rules/consistent-type-assertions.mdx | 4 +- .../docs/rules/consistent-type-exports.mdx | 1 - .../docs/rules/consistent-type-imports.mdx | 7 +- .../eslint-plugin/docs/rules/dot-notation.mdx | 4 - .../rules/explicit-member-accessibility.mdx | 3 +- .../eslint-plugin/docs/rules/max-params.mdx | 2 - .../docs/rules/method-signature-style.mdx | 2 - .../docs/rules/no-base-to-string.mdx | 6 +- .../docs/rules/no-empty-interface.mdx | 2 +- .../docs/rules/no-empty-object-type.mdx | 5 +- .../docs/rules/no-explicit-any.mdx | 2 - .../docs/rules/no-extraneous-class.mdx | 8 -- .../docs/rules/no-floating-promises.mdx | 8 +- .../docs/rules/no-inferrable-types.mdx | 4 - .../docs/rules/no-invalid-void-type.mdx | 5 +- .../rules/no-meaningless-void-operator.mdx | 2 - .../docs/rules/no-misused-promises.mdx | 2 - .../eslint-plugin/docs/rules/no-redeclare.mdx | 2 +- .../docs/rules/no-require-imports.mdx | 2 +- .../docs/rules/no-restricted-imports.mdx | 3 +- .../docs/rules/no-restricted-types.mdx | 2 - .../eslint-plugin/docs/rules/no-shadow.mdx | 4 +- .../docs/rules/no-type-alias.mdx | 16 --- .../docs/rules/no-use-before-define.mdx | 6 -- .../docs/rules/parameter-properties.mdx | 4 +- .../docs/rules/prefer-literal-enum-member.mdx | 2 - .../docs/rules/prefer-nullish-coalescing.mdx | 10 -- .../docs/rules/prefer-optional-chain.mdx | 14 --- .../rules/prefer-readonly-parameter-types.mdx | 4 - .../docs/rules/prefer-readonly.mdx | 2 - .../docs/rules/promise-function-async.mdx | 13 --- .../rules/restrict-template-expressions.mdx | 14 --- .../docs/rules/sort-type-constituents.mdx | 6 -- .../docs/rules/strict-boolean-expressions.mdx | 18 +--- .../rules/switch-exhaustiveness-check.mdx | 4 +- packages/eslint-plugin/docs/rules/typedef.mdx | 16 --- .../rules/explicit-member-accessibility.ts | 8 +- .../src/rules/no-invalid-void-type.ts | 4 +- .../src/rules/no-misused-promises.ts | 4 + .../src/rules/no-restricted-imports.ts | 2 +- .../src/rules/no-restricted-types.ts | 2 + .../src/rules/sort-type-constituents.ts | 7 +- .../src/rules/strict-boolean-expressions.ts | 12 ++- packages/website/package.json | 1 + .../generated-rule-docs/RuleDocsPage.ts | 23 ++-- .../generated-rule-docs/createRuleDocsPage.ts | 4 +- .../plugins/generated-rule-docs/index.ts | 4 +- .../insertions/insertBaseRuleReferences.ts | 32 +----- .../insertions/insertFormattingNotice.ts | 100 ------------------ .../insertions/insertNewRuleReferences.ts | 86 ++++----------- .../insertions/insertResources.ts | 61 +---------- .../insertions/insertRuleDescription.ts | 41 ++----- .../insertions/insertRuleOptions.ts | 93 ++++++++++++++++ .../insertions/insertWhenNotToUseIt.ts | 48 +-------- packages/website/plugins/utils/rules.ts | 19 ++-- yarn.lock | 3 +- 56 files changed, 227 insertions(+), 536 deletions(-) delete mode 100644 packages/website/plugins/generated-rule-docs/insertions/insertFormattingNotice.ts create mode 100644 packages/website/plugins/generated-rule-docs/insertions/insertRuleOptions.ts diff --git a/packages/eslint-plugin/docs/rules/consistent-type-assertions.mdx b/packages/eslint-plugin/docs/rules/consistent-type-assertions.mdx index cf437b9ed714..adaf279f7bd8 100644 --- a/packages/eslint-plugin/docs/rules/consistent-type-assertions.mdx +++ b/packages/eslint-plugin/docs/rules/consistent-type-assertions.mdx @@ -30,7 +30,7 @@ Examples of them include `let x = "hello" as const;` and `let x = "hello" ### `assertionStyle` -The expected assertion style to enforce. Valid values for `assertionStyle` are: +Valid values for `assertionStyle` are: - `as` will enforce that you always use `... as foo`. - `angle-bracket` will enforce that you always use `...` @@ -42,8 +42,6 @@ Some codebases like to go for an extra level of type safety, and ban assertions ### `objectLiteralTypeAssertions` -Whether to always prefer type declarations for object literals used as variable initializers, rather than type assertions. - For example, this would prefer `const x: T = { ... };` to `const x = { ... } as T;` (or similar with angle brackets). The type assertion in the latter case is either unnecessary or will probably hide an error. diff --git a/packages/eslint-plugin/docs/rules/consistent-type-exports.mdx b/packages/eslint-plugin/docs/rules/consistent-type-exports.mdx index 7c2ed45dcda9..05a89198d53d 100644 --- a/packages/eslint-plugin/docs/rules/consistent-type-exports.mdx +++ b/packages/eslint-plugin/docs/rules/consistent-type-exports.mdx @@ -54,7 +54,6 @@ export type { ButtonProps }; ### `fixMixedExportsWithInlineTypeSpecifier` -Whether the rule will autofix "mixed" export cases using TS inline type specifiers. If you are using a TypeScript version less than 4.5, then you will not be able to use this option. For example the following code: diff --git a/packages/eslint-plugin/docs/rules/consistent-type-imports.mdx b/packages/eslint-plugin/docs/rules/consistent-type-imports.mdx index cacc53d50a2c..71c80fa8e9f0 100644 --- a/packages/eslint-plugin/docs/rules/consistent-type-imports.mdx +++ b/packages/eslint-plugin/docs/rules/consistent-type-imports.mdx @@ -18,7 +18,7 @@ This allows transpilers to drop imports without knowing the types of the depende ### `prefer` -The expected import kind for type-only imports. Valid values for `prefer` are: +Valid values for `prefer` are: - `type-imports` will enforce that you always use `import type Foo from '...'` except referenced by metadata of decorators. It is the default. - `no-type-imports` will enforce that you always use `import Foo from '...'`. @@ -43,7 +43,7 @@ const x: Bar = 1; ### `fixStyle` -The expected type modifier to be added when an import is detected as used only in the type position. Valid values for `fixStyle` are: +Valid values for `fixStyle` are: - `separate-type-imports` will add the type keyword after the import keyword `import type { A } from '...'`. It is the default. - `inline-type-imports` will inline the type keyword `import { type A } from '...'` and is only available in TypeScript 4.5 and onwards. See [documentation here](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-5.html#type-modifiers-on-import-names 'TypeScript 4.5 documentation on type modifiers and import names'). @@ -83,9 +83,6 @@ const x: Bar = 1; ### `disallowTypeAnnotations` -Whether to disallow type imports in type annotations (`import()`). -Default is `true`. - Examples of **incorrect** code with `{disallowTypeAnnotations: true}`: ```ts option='{ "disallowTypeAnnotations": true }' showPlaygroundButton diff --git a/packages/eslint-plugin/docs/rules/dot-notation.mdx b/packages/eslint-plugin/docs/rules/dot-notation.mdx index cf44c44028b8..1b6819448799 100644 --- a/packages/eslint-plugin/docs/rules/dot-notation.mdx +++ b/packages/eslint-plugin/docs/rules/dot-notation.mdx @@ -38,7 +38,6 @@ If the TypeScript compiler option `noPropertyAccessFromIndexSignature` is set to ### `allowPrivateClassPropertyAccess` -Whether to allow accessing class members marked as `private` with array notation. This can be useful because TypeScript will report a type error on dot notation but not array notation. Example of a correct code when `allowPrivateClassPropertyAccess` is set to `true`: @@ -54,7 +53,6 @@ x['priv_prop'] = 123; ### `allowProtectedClassPropertyAccess` -Whether to allow accessing class members marked as `protected` with array notation. This can be useful because TypeScript will report a type error on dot notation but not array notation. Example of a correct code when `allowProtectedClassPropertyAccess` is set to `true`: @@ -70,8 +68,6 @@ x['protected_prop'] = 123; ### `allowIndexSignaturePropertyAccess` -Whether to allow accessing properties matching an index signature with array notation. - Example of correct code when `allowIndexSignaturePropertyAccess` is set to `true`: ```ts option='{ "allowIndexSignaturePropertyAccess": true }' showPlaygroundButton diff --git a/packages/eslint-plugin/docs/rules/explicit-member-accessibility.mdx b/packages/eslint-plugin/docs/rules/explicit-member-accessibility.mdx index 60f4f6c2a810..d69da91bcfa0 100644 --- a/packages/eslint-plugin/docs/rules/explicit-member-accessibility.mdx +++ b/packages/eslint-plugin/docs/rules/explicit-member-accessibility.mdx @@ -317,8 +317,7 @@ class Animal { ### `ignoredMethodNames` -Specific method names that may be ignored. -Note that this option does not care for the context, and will ignore every method with these names, which could lead to it missing some cases. You should use this sparingly. +Note that this option does not care about context, and will ignore every method with these names, which could lead to it missing some cases. You should use this sparingly. e.g. `[ { ignoredMethodNames: ['specificMethod', 'whateverMethod'] } ]` ```ts option='{ "ignoredMethodNames": ["specificMethod", "whateverMethod"] }' showPlaygroundButton diff --git a/packages/eslint-plugin/docs/rules/max-params.mdx b/packages/eslint-plugin/docs/rules/max-params.mdx index 1797dffaec73..75f01b121d19 100644 --- a/packages/eslint-plugin/docs/rules/max-params.mdx +++ b/packages/eslint-plugin/docs/rules/max-params.mdx @@ -29,8 +29,6 @@ const defaultOptions: Options = { ### `countVoidThis` -Whether to count a `this` declaration when the type is `void`. - Example of a code when `countVoidThis` is set to `false` and `max` is `1`: diff --git a/packages/eslint-plugin/docs/rules/method-signature-style.mdx b/packages/eslint-plugin/docs/rules/method-signature-style.mdx index 0536bff803a5..cea7b26819bd 100644 --- a/packages/eslint-plugin/docs/rules/method-signature-style.mdx +++ b/packages/eslint-plugin/docs/rules/method-signature-style.mdx @@ -39,8 +39,6 @@ This rule accepts one string option: - `"property"`: Enforce using property signature for functions. Use this to enforce maximum correctness together with TypeScript's strict mode. - `"method"`: Enforce using method signature for functions. Use this if you aren't using TypeScript's strict mode and prefer this style. -The default is `"property"`. - ### `property` Examples of code with `property` option. diff --git a/packages/eslint-plugin/docs/rules/no-base-to-string.mdx b/packages/eslint-plugin/docs/rules/no-base-to-string.mdx index 97767da415b8..0aa989c3972b 100644 --- a/packages/eslint-plugin/docs/rules/no-base-to-string.mdx +++ b/packages/eslint-plugin/docs/rules/no-base-to-string.mdx @@ -66,9 +66,8 @@ const literalWithToString = { ### `ignoredTypeNames` -Stringified regular expressions of type names to ignore. -This is useful for types missing `toString()` (but actually has `toString()`). -There are some types missing `toString()` in old version TypeScript, like `RegExp`, `URL`, `URLSearchParams` etc. +This is useful for types whose declarations missing `toString()`, but are known to actually have `toString()`. +There are some types missing `toString()` in TypeScript, like `RegExp`, `URL`, `URLSearchParams` etc. The following patterns are considered correct with the default options `{ ignoredTypeNames: ["RegExp"] }`: @@ -93,3 +92,4 @@ If you don't mind a risk of `"[object Object]"` or incorrect type coercions in y ## Further Reading - [`Object.prototype.toString()` MDN documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/toString) +- [Microsoft/TypeScript Add missing toString declarations for base types that have them](https://github.com/microsoft/TypeScript/issues/38347) diff --git a/packages/eslint-plugin/docs/rules/no-empty-interface.mdx b/packages/eslint-plugin/docs/rules/no-empty-interface.mdx index 733d8b39ebe6..5a9100006f68 100644 --- a/packages/eslint-plugin/docs/rules/no-empty-interface.mdx +++ b/packages/eslint-plugin/docs/rules/no-empty-interface.mdx @@ -62,7 +62,7 @@ interface Baz extends Foo, Bar {} ### `allowSingleExtends` -`allowSingleExtends: true` will silence warnings about extending a single interface without adding additional members +`allowSingleExtends: true` will silence warnings about extending a single interface without adding additional members. ## When Not To Use It diff --git a/packages/eslint-plugin/docs/rules/no-empty-object-type.mdx b/packages/eslint-plugin/docs/rules/no-empty-object-type.mdx index 8bf941a66615..ebd083d9e650 100644 --- a/packages/eslint-plugin/docs/rules/no-empty-object-type.mdx +++ b/packages/eslint-plugin/docs/rules/no-empty-object-type.mdx @@ -83,7 +83,7 @@ By default, this rule flags both interfaces and object types. ### `allowInterfaces` -Whether to allow empty interfaces, as one of: +Allowed values are: - `'always'`: to always allow interfaces with no fields - `'never'` _(default)_: to never allow interfaces with no fields @@ -101,14 +101,13 @@ interface Derived extends Base {} ### `allowObjectTypes` -Whether to allow empty object type literals, as one of: +Allowed values are: - `'always'`: to always allow object type literals with no fields - `'never'` _(default)_: to never allow object type literals with no fields ### `allowWithName` -A stringified regular expression to allow interfaces and object type aliases with the configured name. This can be useful if your existing code style includes a pattern of declaring empty types with `{}` instead of `object`. Examples of code for this rule with `{ allowWithName: 'Props$' }`: diff --git a/packages/eslint-plugin/docs/rules/no-explicit-any.mdx b/packages/eslint-plugin/docs/rules/no-explicit-any.mdx index 52f7108d165b..3420e295a6b5 100644 --- a/packages/eslint-plugin/docs/rules/no-explicit-any.mdx +++ b/packages/eslint-plugin/docs/rules/no-explicit-any.mdx @@ -114,8 +114,6 @@ Enabling `{ "fixToUnknown": true }` gives the rule an auto-fixer to replace `: a ### `ignoreRestArgs` -A boolean to specify if arrays from the rest operator are considered okay. `false` by default. - The examples below are **incorrect** when `{ignoreRestArgs: false}`, but **correct** when `{ignoreRestArgs: true}`. ```ts option='{ "ignoreRestArgs": false }' showPlaygroundButton diff --git a/packages/eslint-plugin/docs/rules/no-extraneous-class.mdx b/packages/eslint-plugin/docs/rules/no-extraneous-class.mdx index 0966be0978c1..e2c2042ae790 100644 --- a/packages/eslint-plugin/docs/rules/no-extraneous-class.mdx +++ b/packages/eslint-plugin/docs/rules/no-extraneous-class.mdx @@ -221,8 +221,6 @@ The rule's options each add an exemption for a specific type of class. ### `allowConstructorOnly` -`allowConstructorOnly` adds an exemption for classes that have only a constructor and no fields. - @@ -246,8 +244,6 @@ class NoFields { ### `allowEmpty` -The `allowEmpty` option adds an exemption for classes that are entirely empty. - @@ -271,8 +267,6 @@ class NoFields {} ### `allowStaticOnly` -The `allowStaticOnly` option adds an exemption for classes that only contain static members. - :::caution We strongly recommend against the `allowStaticOnly` exemption. It works against this rule's primary purpose of discouraging classes used only for static members. @@ -299,8 +293,6 @@ class NotEmptyClass { ### `allowWithDecorator` -The `allowWithDecorator` option adds an exemption for classes decorated with a `@` decorator. - diff --git a/packages/eslint-plugin/docs/rules/no-floating-promises.mdx b/packages/eslint-plugin/docs/rules/no-floating-promises.mdx index 18a84c2e0240..6f324ad2ab2e 100644 --- a/packages/eslint-plugin/docs/rules/no-floating-promises.mdx +++ b/packages/eslint-plugin/docs/rules/no-floating-promises.mdx @@ -131,8 +131,7 @@ await createMyThenable(); ### `ignoreVoid` -This option, which is `true` by default, allows you to stop the rule reporting promises consumed with void operator. -This can be a good way to explicitly mark a promise as intentionally not awaited. +Placing the `void` operator in front of a Promise can be a convenient way to explicitly mark that Promise as intentionally not awaited. Examples of **correct** code for this rule with `{ ignoreVoid: true }`: @@ -149,8 +148,6 @@ With this option set to `true`, and if you are using `no-void`, you should turn ### `ignoreIIFE` -This allows you to skip checking of async IIFEs (Immediately Invoked Function Expressions). - Examples of **correct** code for this rule with `{ ignoreIIFE: true }`: {/* prettier-ignore */} @@ -166,7 +163,7 @@ await (async function () { ### `allowForKnownSafePromises` -Specific types to be marked as "safe" to be floating. For example, you may need to do this in the case of libraries whose APIs return Promises whose rejections are safely handled by the library. +For example, you may need to do this in the case of libraries whose APIs return Promises whose rejections are safely handled by the library. This option takes the shared [`TypeOrValueSpecifier` format](/packages/type-utils/type-or-value-specifier). @@ -218,7 +215,6 @@ returnsSafePromise(); ### `allowForKnownSafeCalls` -Specific functions to be marked as "safe" to be called to create floating Promises. For example, you may need to do this in the case of libraries whose APIs may be called without handling the resultant Promises. This option takes the shared [`TypeOrValueSpecifier` format](/packages/type-utils/type-or-value-specifier). diff --git a/packages/eslint-plugin/docs/rules/no-inferrable-types.mdx b/packages/eslint-plugin/docs/rules/no-inferrable-types.mdx index 0cf7caa4d767..ff21a3538a35 100644 --- a/packages/eslint-plugin/docs/rules/no-inferrable-types.mdx +++ b/packages/eslint-plugin/docs/rules/no-inferrable-types.mdx @@ -80,8 +80,6 @@ function fn(a = 5, b = true) {} ### `ignoreParameters` -Whether to ignore function parameters. - When set to true, the following pattern is considered valid: ```ts option='{ "ignoreParameters": true }' showPlaygroundButton @@ -92,8 +90,6 @@ function foo(a: number = 5, b: boolean = true) { ### `ignoreProperties` -Whether to ignore class properties. - When set to true, the following pattern is considered valid: ```ts option='{ "ignoreProperties": true }' showPlaygroundButton diff --git a/packages/eslint-plugin/docs/rules/no-invalid-void-type.mdx b/packages/eslint-plugin/docs/rules/no-invalid-void-type.mdx index 1e6a1507a3fa..ea0160b9a1c4 100644 --- a/packages/eslint-plugin/docs/rules/no-invalid-void-type.mdx +++ b/packages/eslint-plugin/docs/rules/no-invalid-void-type.mdx @@ -62,9 +62,7 @@ type stillVoid = void | never; ### `allowInGenericTypeArguments` -Whether `void` can be used as a valid value for generic type parameters. - -Alternatively, you can provide an array of strings which whitelist which types may accept `void` as a generic type parameter. +Alternatively, you can provide an array of strings which allowlist which types may accept `void` as a generic type parameter. Any types considered valid by this option will be considered valid as part of a union type with `void`. @@ -98,7 +96,6 @@ type AllowedVoidUnion = void | Ex.Mx.Tx; ### `allowAsThisParameter` -Whether a `this` parameter of a function may be `void`. This pattern can be useful to explicitly label function types that do not use a `this` argument. [See the TypeScript docs for more information](https://www.typescriptlang.org/docs/handbook/functions.html#this-parameters-in-callbacks). This option is `false` by default. diff --git a/packages/eslint-plugin/docs/rules/no-meaningless-void-operator.mdx b/packages/eslint-plugin/docs/rules/no-meaningless-void-operator.mdx index 518da46b3328..5e0e97e7b858 100644 --- a/packages/eslint-plugin/docs/rules/no-meaningless-void-operator.mdx +++ b/packages/eslint-plugin/docs/rules/no-meaningless-void-operator.mdx @@ -54,8 +54,6 @@ void bar(1); // discarding a number ### `checkNever` -Whether to suggest removing `void` when the argument has type `never`. - ## When Not To Use It If you don't mind extra `void`s in your project, you can avoid this rule. diff --git a/packages/eslint-plugin/docs/rules/no-misused-promises.mdx b/packages/eslint-plugin/docs/rules/no-misused-promises.mdx index bc8ae0f33b6e..4ac2c491cde0 100644 --- a/packages/eslint-plugin/docs/rules/no-misused-promises.mdx +++ b/packages/eslint-plugin/docs/rules/no-misused-promises.mdx @@ -101,8 +101,6 @@ Disables checking an asynchronous function used as a variable whose return type ### `checksSpreads` -Whether to warn when `...` spreading a `Promise`. - If you don't want to check object spreads, you can add this configuration: ```json diff --git a/packages/eslint-plugin/docs/rules/no-redeclare.mdx b/packages/eslint-plugin/docs/rules/no-redeclare.mdx index cf0171d484e8..50e04101b3cd 100644 --- a/packages/eslint-plugin/docs/rules/no-redeclare.mdx +++ b/packages/eslint-plugin/docs/rules/no-redeclare.mdx @@ -33,7 +33,7 @@ const defaultOptions: Options = { ### `ignoreDeclarationMerge` -Whether to ignore declaration merges between the following sets: +The following sets will be ignored when this option is enabled: - interface + interface - namespace + namespace diff --git a/packages/eslint-plugin/docs/rules/no-require-imports.mdx b/packages/eslint-plugin/docs/rules/no-require-imports.mdx index 4512c2693d95..1754f4f72daa 100644 --- a/packages/eslint-plugin/docs/rules/no-require-imports.mdx +++ b/packages/eslint-plugin/docs/rules/no-require-imports.mdx @@ -61,7 +61,7 @@ console.log(require('../package.json').version); ### `allowAsImport` -When set to `true`, the `import x = require(...)` declaration won't be reported. +When set to `true`, `import ... = require(...)` declarations won't be reported. This is useful if you use certain module options that require strict CommonJS interop semantics. With `{allowAsImport: true}`: diff --git a/packages/eslint-plugin/docs/rules/no-restricted-imports.mdx b/packages/eslint-plugin/docs/rules/no-restricted-imports.mdx index 621bf351e833..b7005c8bff63 100644 --- a/packages/eslint-plugin/docs/rules/no-restricted-imports.mdx +++ b/packages/eslint-plugin/docs/rules/no-restricted-imports.mdx @@ -17,7 +17,8 @@ This rule adds the following options: ### `allowTypeImports` -(default: `false`) +Whether to allow type-only imports for a path. +Default: `false`. You can specify this option for a specific path or pattern as follows: diff --git a/packages/eslint-plugin/docs/rules/no-restricted-types.mdx b/packages/eslint-plugin/docs/rules/no-restricted-types.mdx index 20732174929e..0577bcd4aa18 100644 --- a/packages/eslint-plugin/docs/rules/no-restricted-types.mdx +++ b/packages/eslint-plugin/docs/rules/no-restricted-types.mdx @@ -19,8 +19,6 @@ Note that it does not ban the corresponding runtime objects from being used. ### `types` -An object whose keys are the types you want to ban, and the values are error messages. - The type can either be a type name literal (`OldType`) or a a type name with generic parameter instantiation(s) (`OldType`). The values can be: diff --git a/packages/eslint-plugin/docs/rules/no-shadow.mdx b/packages/eslint-plugin/docs/rules/no-shadow.mdx index 40651e2fbe99..24f4fda374f6 100644 --- a/packages/eslint-plugin/docs/rules/no-shadow.mdx +++ b/packages/eslint-plugin/docs/rules/no-shadow.mdx @@ -31,7 +31,7 @@ const defaultOptions: Options = { ### `ignoreTypeValueShadow` -Whether to ignore types named the same as a variable. This is generally safe because you cannot use variables in type locations without a `typeof` operator, so there's little risk of confusion. +This is generally safe because you cannot use variables in type locations without a `typeof` operator, so there's little risk of confusion. Examples of **correct** code with `{ ignoreTypeValueShadow: true }`: @@ -55,8 +55,6 @@ _Shadowing_ specifically refers to two identical identifiers that are in differe ### `ignoreFunctionTypeParameterNameValueShadow` -Whether to ignore function parameters named the same as a variable. - Each of a function type's arguments creates a value variable within the scope of the function type. This is done so that you can reference the type later using the `typeof` operator: ```ts diff --git a/packages/eslint-plugin/docs/rules/no-type-alias.mdx b/packages/eslint-plugin/docs/rules/no-type-alias.mdx index 11068fbab2f6..2a88770af624 100644 --- a/packages/eslint-plugin/docs/rules/no-type-alias.mdx +++ b/packages/eslint-plugin/docs/rules/no-type-alias.mdx @@ -114,8 +114,6 @@ and simplified types (primitives, tuples, unions, intersections, etc). ### `allowAliases` -This applies to primitive types and reference types. - The setting accepts the following values: - `"always"` or `"never"` to active or deactivate the feature. @@ -268,8 +266,6 @@ type Foo = Bar & Baz; ### `allowCallbacks` -This applies to function types. - The setting accepts the following values: - `"always"` or `"never"` to active or deactivate the feature. @@ -290,8 +286,6 @@ type Foo = (name: string, age: number) => string & Person; ### `allowConditionalTypes` -This applies to conditional types. - Examples of **correct** code for the `{ "allowConditionalTypes": "always" }` option: ```ts option='{ "allowConditionalTypes": "always" }' showPlaygroundButton @@ -300,8 +294,6 @@ type Foo = T extends number ? number : null; ### `allowConstructors` -This applies to constructor types. - The setting accepts the following values: - `"always"` or `"never"` to active or deactivate the feature. @@ -314,8 +306,6 @@ type Foo = new () => void; ### `allowLiterals` -This applies to literal types (`type Foo = { ... }`). - The setting accepts the following options: - `"always"` or `"never"` to active or deactivate the feature. @@ -421,8 +411,6 @@ type Foo = { name: string } & { age: number }; ### `allowMappedTypes` -This applies to literal types. - The setting accepts the following values: - `"always"` or `"never"` to active or deactivate the feature. @@ -524,8 +512,6 @@ type Foo = { [P in keyof T]?: T[P] } & { [P in keyof U]?: U[P] }; ### `allowTupleTypes` -This applies to tuple types (`type Foo = [number]`). - The setting accepts the following options: - `"always"` or `"never"` to active or deactivate the feature. @@ -599,8 +585,6 @@ type Foo = [string] | [number]; ### `allowGenerics` -This applies to generic types, including TypeScript provided global utility types (`type Foo = Record`). - The setting accepts the following options: - `"always"` or `"never"` to active or deactivate the feature. diff --git a/packages/eslint-plugin/docs/rules/no-use-before-define.mdx b/packages/eslint-plugin/docs/rules/no-use-before-define.mdx index 29bf8b75a0a7..a0b107444fe2 100644 --- a/packages/eslint-plugin/docs/rules/no-use-before-define.mdx +++ b/packages/eslint-plugin/docs/rules/no-use-before-define.mdx @@ -33,8 +33,6 @@ const defaultOptions: Options = { ### `enums` -Whether to check references to enums before the enum declaration. - If this is `true`, this rule warns every reference to a enum before the enum declaration. If this is `false`, this rule will ignore references to enums, when the reference is in a child scope. @@ -69,8 +67,6 @@ enum Foo { ### `typedefs` -Whether to check references to types before the type declaration. - If this is `true`, this rule warns every reference to a type before the type declaration. If this is `false`, this rule will ignore references to types. @@ -83,8 +79,6 @@ type StringOrNumber = string | number; ### `ignoreTypeReferences` -Whether to ignore type references, such as in type annotations and assertions. - If this is `true`, this rule ignores all type references. If this is `false`, this will check all type references. diff --git a/packages/eslint-plugin/docs/rules/parameter-properties.mdx b/packages/eslint-plugin/docs/rules/parameter-properties.mdx index b9915dd65e68..bdebfc5ec271 100644 --- a/packages/eslint-plugin/docs/rules/parameter-properties.mdx +++ b/packages/eslint-plugin/docs/rules/parameter-properties.mdx @@ -50,8 +50,8 @@ For example, to ignore `public` properties: ### `prefer` -By default, the rule prefers class property (`"class-property"`). -You can switch it to instead preferring parameter property with (`"parameter-property"`). +By default, the rule prefers class properties. +You can switch it to instead preferring parameter properties with (`"parameter-property"`). In `"parameter-property"` mode, the rule will issue a report when: diff --git a/packages/eslint-plugin/docs/rules/prefer-literal-enum-member.mdx b/packages/eslint-plugin/docs/rules/prefer-literal-enum-member.mdx index 5f9e4ac03736..3b8faeabf561 100644 --- a/packages/eslint-plugin/docs/rules/prefer-literal-enum-member.mdx +++ b/packages/eslint-plugin/docs/rules/prefer-literal-enum-member.mdx @@ -67,8 +67,6 @@ enum Valid { ### `allowBitwiseExpressions` -Whether to allow using bitwise expressions in enum initializers (default: `false`). - Examples of code for the `{ "allowBitwiseExpressions": true }` option: diff --git a/packages/eslint-plugin/docs/rules/prefer-nullish-coalescing.mdx b/packages/eslint-plugin/docs/rules/prefer-nullish-coalescing.mdx index f36acad8e05f..449f26bf4760 100644 --- a/packages/eslint-plugin/docs/rules/prefer-nullish-coalescing.mdx +++ b/packages/eslint-plugin/docs/rules/prefer-nullish-coalescing.mdx @@ -25,8 +25,6 @@ This rule will not work as expected if [`strictNullChecks`](https://www.typescri ### `ignoreTernaryTests` -Whether to ignore any ternary expressions that could be simplified by using the nullish coalescing operator. This is set to `false` by default. - Incorrect code for `ignoreTernaryTests: false`, and correct code for `ignoreTernaryTests: true`: ```ts option='{ "ignoreTernaryTests": false }' showPlaygroundButton @@ -65,8 +63,6 @@ foo ?? 'a string'; ### `ignoreConditionalTests` -Whether to ignore cases that are located within a conditional test. This is set to `true` by default. - Generally expressions within conditional tests intentionally use the falsy fallthrough behavior of the logical or operator, meaning that fixing the operator to the nullish coalesce operator could cause bugs. If you're looking to enforce stricter conditional tests, you should consider using the `strict-boolean-expressions` rule. @@ -107,8 +103,6 @@ a ?? b ? true : false; ### `ignoreMixedLogicalExpressions` -Whether to ignore any logical or expressions that are part of a mixed logical expression (with `&&`). This is set to `false` by default. - Generally expressions within mixed logical expressions intentionally use the falsy fallthrough behavior of the logical or operator, meaning that fixing the operator to the nullish coalesce operator could cause bugs. If you're looking to enforce stricter conditional tests, you should consider using the `strict-boolean-expressions` rule. @@ -147,8 +141,6 @@ a ?? (b && c && d); ### `ignorePrimitives` -Whether to ignore all (`true`) or some (an object with properties) primitive types. - If you would like to ignore expressions containing operands of certain primitive types that can be falsy then you may pass an object containing a boolean value for each primitive: - `string: true`, ignores `null` or `undefined` unions with `string` (default: false). @@ -174,8 +166,6 @@ Also, if you would like to ignore all primitives types, you can set `ignorePrimi ### `allowRuleToRunWithoutStrictNullChecksIKnowWhatIAmDoing` -Unless this is set to `true`, the rule will error on every file whose `tsconfig.json` does _not_ have the `strictNullChecks` compiler option (or `strict`) set to `true`. - Without `strictNullChecks`, TypeScript essentially erases `undefined` and `null` from the types. This means when this rule inspects the types from a variable, **it will not be able to tell that the variable might be `null` or `undefined`**, which essentially makes this rule useless. You should be using `strictNullChecks` to ensure complete type-safety in your codebase. diff --git a/packages/eslint-plugin/docs/rules/prefer-optional-chain.mdx b/packages/eslint-plugin/docs/rules/prefer-optional-chain.mdx index ee7aa6abf42f..29e835ff9306 100644 --- a/packages/eslint-plugin/docs/rules/prefer-optional-chain.mdx +++ b/packages/eslint-plugin/docs/rules/prefer-optional-chain.mdx @@ -89,8 +89,6 @@ When this option is `false` unsafe cases will have suggestion fixers provided in ### `checkAny` -When this option is `true` the rule will check operands that are typed as `any` when inspecting "loose boolean" operands. - @@ -115,8 +113,6 @@ thing && thing.toString(); ### `checkUnknown` -When this option is `true` the rule will check operands that are typed as `unknown` when inspecting "loose boolean" operands. - @@ -141,8 +137,6 @@ thing && thing.toString(); ### `checkString` -When this option is `true` the rule will check operands that are typed as `string` when inspecting "loose boolean" operands. - @@ -167,8 +161,6 @@ thing && thing.toString(); ### `checkNumber` -When this option is `true` the rule will check operands that are typed as `number` when inspecting "loose boolean" operands. - @@ -193,8 +185,6 @@ thing && thing.toString(); ### `checkBoolean` -When this option is `true` the rule will check operands that are typed as `boolean` when inspecting "loose boolean" operands. - :::note This rule intentionally ignores the following case: @@ -233,8 +223,6 @@ thing && thing.toString(); ### `checkBigInt` -When this option is `true` the rule will check operands that are typed as `bigint` when inspecting "loose boolean" operands. - @@ -259,8 +247,6 @@ thing && thing.toString(); ### `requireNullish` -When this option is `true` the rule will skip operands that are not typed with `null` and/or `undefined` when inspecting "loose boolean" operands. - diff --git a/packages/eslint-plugin/docs/rules/prefer-readonly-parameter-types.mdx b/packages/eslint-plugin/docs/rules/prefer-readonly-parameter-types.mdx index f89d653bd63e..30e189502345 100644 --- a/packages/eslint-plugin/docs/rules/prefer-readonly-parameter-types.mdx +++ b/packages/eslint-plugin/docs/rules/prefer-readonly-parameter-types.mdx @@ -140,7 +140,6 @@ interface Foo { ### `allow` -An array of type specifiers to ignore. Some complex types cannot easily be made readonly, for example the `HTMLElement` type or the `JQueryStatic` type from `@types/jquery`. This option allows you to globally disable reporting of such types. This option takes the shared [`TypeOrValueSpecifier` format](/packages/type-utils/type-or-value-specifier). @@ -251,7 +250,6 @@ function fn(arg: Foo) {} ### `checkParameterProperties` -Whether to check class parameter properties. Because parameter properties create properties on the class, it may be undesirable to force them to be readonly. Examples of code for this rule with `{checkParameterProperties: true}`: @@ -290,7 +288,6 @@ class Foo { ### `ignoreInferredTypes` -Whether to ignore parameters which don't explicitly specify a type. This may be desirable in cases where an external dependency specifies a callback with mutable parameters, and manually annotating the callback's parameters is undesirable. Examples of code for this rule with `{ignoreInferredTypes: true}`: @@ -348,7 +345,6 @@ export const acceptsCallback: AcceptsCallback; ### `treatMethodsAsReadonly` -Whether to treat all mutable methods as though they are readonly. This may be desirable when you are never reassigning methods. Examples of code for this rule with `{treatMethodsAsReadonly: false}`: diff --git a/packages/eslint-plugin/docs/rules/prefer-readonly.mdx b/packages/eslint-plugin/docs/rules/prefer-readonly.mdx index a3fe49e0336c..d341d98d34c2 100644 --- a/packages/eslint-plugin/docs/rules/prefer-readonly.mdx +++ b/packages/eslint-plugin/docs/rules/prefer-readonly.mdx @@ -70,8 +70,6 @@ class Container { ### `onlyInlineLambdas` -You may pass `"onlyInlineLambdas": true` as a rule option within an object to restrict checking only to members immediately assigned a lambda value. - ```jsonc { "@typescript-eslint/prefer-readonly": [ diff --git a/packages/eslint-plugin/docs/rules/promise-function-async.mdx b/packages/eslint-plugin/docs/rules/promise-function-async.mdx index aabe921925d3..aa95ebc93028 100644 --- a/packages/eslint-plugin/docs/rules/promise-function-async.mdx +++ b/packages/eslint-plugin/docs/rules/promise-function-async.mdx @@ -68,7 +68,6 @@ async function functionReturnsUnionWithPromiseImplicitly(p: boolean) { ### `allowAny` -Whether to ignore functions that return `any` or `unknown`. If you want additional safety, consider turning this option off, as it makes the rule less able to catch incorrect Promise behaviors. Examples of code with `{ "allowAny": false }`: @@ -120,24 +119,12 @@ const returnsBluebird = async () => new Bluebird(() => {}); ### `checkArrowFunctions` -Whether to check arrow functions. -`true` by default, but can be set to `false` to ignore them. - ### `checkFunctionDeclarations` -Whether to check standalone function declarations. -`true` by default, but can be set to `false` to ignore them. - ### `checkFunctionExpressions` -Whether to check inline function expressions. -`true` by default, but can be set to `false` to ignore them. - ### `checkMethodDeclarations` -Whether to check methods on classes and object literals. -`true` by default, but can be set to `false` to ignore them. - ## When Not To Use It This rule can be difficult to enable on projects that use APIs which require functions to always be `async`. diff --git a/packages/eslint-plugin/docs/rules/restrict-template-expressions.mdx b/packages/eslint-plugin/docs/rules/restrict-template-expressions.mdx index 2d6b03041224..d55a7baa041d 100644 --- a/packages/eslint-plugin/docs/rules/restrict-template-expressions.mdx +++ b/packages/eslint-plugin/docs/rules/restrict-template-expressions.mdx @@ -55,8 +55,6 @@ const msg3 = `stringWithKindProp = ${stringWithKindProp}`; ### `allowNumber` -Whether to allow `number` typed values in template expressions. - Examples of additional **correct** code for this rule with `{ allowNumber: true }`: ```ts option='{ "allowNumber": true }' showPlaygroundButton @@ -73,8 +71,6 @@ Consider using [`.toFixed()`](https://developer.mozilla.org/en-US/docs/Web/JavaS ### `allowBoolean` -Whether to allow Boolean typed values in template expressions. - Examples of additional **correct** code for this rule with `{ allowBoolean: true }`: ```ts option='{ "allowBoolean": true }' showPlaygroundButton @@ -85,8 +81,6 @@ const msg2 = `arg = ${arg || 'not truthy'}`; ### `allowAny` -Whether to `any` typed values in template expressions. - Examples of additional **correct** code for this rule with `{ allowAny: true }`: ```ts option='{ "allowAny": true }' showPlaygroundButton @@ -97,8 +91,6 @@ const msg2 = `arg = ${user.name || 'the user with no name'}`; ### `allowNullish` -Whether to allow `null` or `undefined` typed values in template expressions. - Examples of additional **correct** code for this rule with `{ allowNullish: true }`: ```ts option='{ "allowNullish": true }' showPlaygroundButton @@ -108,8 +100,6 @@ const msg1 = `arg = ${arg}`; ### `allowRegExp` -Whether to allow `RegExp` typed values in template expressions. - Examples of additional **correct** code for this rule with `{ allowRegExp: true }`: ```ts option='{ "allowRegExp": true }' showPlaygroundButton @@ -124,8 +114,6 @@ const msg1 = `arg = ${arg}`; ### `allowNever` -Whether to `never` typed values in template expressions. - Examples of additional **correct** code for this rule with `{ allowNever: true }`: ```ts option='{ "allowNever": true }' showPlaygroundButton @@ -135,8 +123,6 @@ const msg1 = typeof arg === 'string' ? arg : `arg = ${arg}`; ### `allowArray` -Whether to `Array` typed values in template expressions. - Examples of additional **correct** code for this rule with `{ allowArray: true }`: ```ts option='{ "allowArray": true }' showPlaygroundButton diff --git a/packages/eslint-plugin/docs/rules/sort-type-constituents.mdx b/packages/eslint-plugin/docs/rules/sort-type-constituents.mdx index 9ce8157deffb..9beb63bae2c1 100644 --- a/packages/eslint-plugin/docs/rules/sort-type-constituents.mdx +++ b/packages/eslint-plugin/docs/rules/sort-type-constituents.mdx @@ -96,8 +96,6 @@ type T4 = ### `caseSensitive` -Whether to sort using case sensitive string comparisons. - Examples of code with `{ "caseSensitive": true }`: @@ -119,8 +117,6 @@ type T = 'DeleteForever' | 'DeletedAt'; ### `checkIntersections` -Whether to check intersection types (`&`). - Examples of code with `{ "checkIntersections": true }` (the default): @@ -142,8 +138,6 @@ type ExampleIntersection = A & B; ### `checkUnions` -Whether to check union types (`|`). - Examples of code with `{ "checkUnions": true }` (the default): diff --git a/packages/eslint-plugin/docs/rules/strict-boolean-expressions.mdx b/packages/eslint-plugin/docs/rules/strict-boolean-expressions.mdx index 8c5b27e0c10f..7b1388c937d0 100644 --- a/packages/eslint-plugin/docs/rules/strict-boolean-expressions.mdx +++ b/packages/eslint-plugin/docs/rules/strict-boolean-expressions.mdx @@ -95,57 +95,47 @@ const foo = (arg: any) => (Boolean(arg) ? 1 : 0); ### `allowString` -Allows `string` in a boolean context. -This is safe because strings have only one falsy value (`""`). +This can be safe because strings have only one falsy value (`""`). Set this to `false` if you prefer the explicit `str != ""` or `str.length > 0` style. ### `allowNumber` -Allows `number` in a boolean context. -This is safe because numbers have only two falsy values (`0` and `NaN`). +This can be safe because numbers have only two falsy values (`0` and `NaN`). Set this to `false` if you prefer the explicit `num != 0` and `!Number.isNaN(num)` style. ### `allowNullableObject` -Allows `object | function | symbol | null | undefined` in a boolean context. -This is safe because objects, functions and symbols don't have falsy values. +This can be safe because objects, functions, and symbols don't have falsy values. Set this to `false` if you prefer the explicit `obj != null` style. ### `allowNullableBoolean` -Allows `boolean | null | undefined` in a boolean context. This is unsafe because nullable booleans can be either `false` or nullish. Set this to `false` if you want to enforce explicit `bool ?? false` or `bool ?? true` style. Set this to `true` if you don't mind implicitly treating false the same as a nullish value. ### `allowNullableString` -Allows `string | null | undefined` in a boolean context. This is unsafe because nullable strings can be either an empty string or nullish. Set this to `true` if you don't mind implicitly treating an empty string the same as a nullish value. ### `allowNullableNumber` -Allows `number | null | undefined` in a boolean context. This is unsafe because nullable numbers can be either a falsy number or nullish. Set this to `true` if you don't mind implicitly treating zero or NaN the same as a nullish value. ### `allowNullableEnum` -Allows `enum | null | undefined` in a boolean context. This is unsafe because nullable enums can be either a falsy number or nullish. Set this to `true` if you don't mind implicitly treating an enum whose value is zero the same as a nullish value. ### `allowAny` -Allows `any` in a boolean context. -This is unsafe for obvious reasons. +This is unsafe for because `any` allows any values and disables many type checking checks. Set this to `true` at your own risk. ### `allowRuleToRunWithoutStrictNullChecksIKnowWhatIAmDoing` -If this is set to `false`, then the rule will error on every file whose `tsconfig.json` does _not_ have the `strictNullChecks` compiler option (or `strict`) set to `true`. - Without `strictNullChecks`, TypeScript essentially erases `undefined` and `null` from the types. This means when this rule inspects the types from a variable, **it will not be able to tell that the variable might be `null` or `undefined`**, which essentially makes this rule a lot less useful. You should be using `strictNullChecks` to ensure complete type-safety in your codebase. diff --git a/packages/eslint-plugin/docs/rules/switch-exhaustiveness-check.mdx b/packages/eslint-plugin/docs/rules/switch-exhaustiveness-check.mdx index f629d8ee53ac..e220f748a1a1 100644 --- a/packages/eslint-plugin/docs/rules/switch-exhaustiveness-check.mdx +++ b/packages/eslint-plugin/docs/rules/switch-exhaustiveness-check.mdx @@ -18,7 +18,7 @@ This rule reports when a `switch` statement over a value typed as a union of lit ### `allowDefaultCaseForExhaustiveSwitch` -Defaults to true. If set to false, this rule will also report when a `switch` statement has a case for everything in a union and _also_ contains a `default` case. Thus, by setting this option to false, the rule becomes stricter. +If set to false, this rule will also report when a `switch` statement has a case for everything in a union and _also_ contains a `default` case. Thus, by setting this option to false, the rule becomes stricter. When a `switch` statement over a union type is exhaustive, a final `default` case would be a form of dead code. Additionally, if a new value is added to the union type, a `default` would prevent the `switch-exhaustiveness-check` rule from reporting on the new case not being handled in the `switch` statement. @@ -34,7 +34,7 @@ If your project has many intentionally redundant `default` cases, you may want t ### `requireDefaultForNonUnion` -Defaults to false. If set to true, this rule will also report when a `switch` statement switches over a non-union type (like a `number` or `string`, for example) and that `switch` statement does not have a `default` case. Thus, by setting this option to true, the rule becomes stricter. +If set to true, this rule will also report when a `switch` statement switches over a non-union type (like a `number` or `string`, for example) and that `switch` statement does not have a `default` case. Thus, by setting this option to true, the rule becomes stricter. This is generally desirable so that `number` and `string` switches will be subject to the same exhaustive checks that your other switches are. diff --git a/packages/eslint-plugin/docs/rules/typedef.mdx b/packages/eslint-plugin/docs/rules/typedef.mdx index 46fa0134c90f..40e5e54b2726 100644 --- a/packages/eslint-plugin/docs/rules/typedef.mdx +++ b/packages/eslint-plugin/docs/rules/typedef.mdx @@ -62,8 +62,6 @@ For example, with the following configuration: ### `arrayDestructuring` -Whether to enforce type annotations on variables declared using array destructuring. - Examples of code with `{ "arrayDestructuring": true }`: @@ -91,8 +89,6 @@ for (const [key, val] of new Map([['key', 1]])) { ### `arrowParameter` -Whether to enforce type annotations for parameters of arrow functions. - Examples of code with `{ "arrowParameter": true }`: @@ -126,8 +122,6 @@ const mapper = { ### `memberVariableDeclaration` -Whether to enforce type annotations on member variables of classes. - Examples of code with `{ "memberVariableDeclaration": true }`: @@ -155,8 +149,6 @@ class ContainsText { ### `objectDestructuring` -Whether to enforce type annotations on variables declared using object destructuring. - Examples of code with `{ "objectDestructuring": true }`: @@ -183,8 +175,6 @@ for (const { key, val } of [{ key: 'key', val: 1 }]) { ### `parameter` -Whether to enforce type annotations for parameters of functions and methods. - Examples of code with `{ "parameter": true }`: @@ -250,8 +240,6 @@ class Logger { ### `propertyDeclaration` -Whether to enforce type annotations for properties of interfaces and types. - Examples of code with `{ "propertyDeclaration": true }`: @@ -279,8 +267,6 @@ type Members = { ### `variableDeclaration` -Whether to enforce type annotations for variable declarations, excluding array and object destructuring. - Examples of code with `{ "variableDeclaration": true }`: @@ -306,8 +292,6 @@ let delayedText: string; ### `variableDeclarationIgnoreFunction` -Whether to ignore variable declarations for non-arrow and arrow functions. - Examples of code with `{ "variableDeclaration": true, "variableDeclarationIgnoreFunction": true }`: diff --git a/packages/eslint-plugin/src/rules/explicit-member-accessibility.ts b/packages/eslint-plugin/src/rules/explicit-member-accessibility.ts index 2661949b57d7..a4f3c80c14ae 100644 --- a/packages/eslint-plugin/src/rules/explicit-member-accessibility.ts +++ b/packages/eslint-plugin/src/rules/explicit-member-accessibility.ts @@ -79,8 +79,14 @@ export default createRule({ }, type: 'object', properties: { - accessibility: { $ref: '#/items/0/$defs/accessibilityLevel' }, + accessibility: { + $ref: '#/items/0/$defs/accessibilityLevel', + description: + 'Which of accessibility modifier is required to exist or not exist.', + }, overrides: { + description: + 'Changes to required accessibility modifiers for specific kinds of class members.', type: 'object', properties: { accessors: { $ref: '#/items/0/$defs/accessibilityLevel' }, diff --git a/packages/eslint-plugin/src/rules/no-invalid-void-type.ts b/packages/eslint-plugin/src/rules/no-invalid-void-type.ts index 81faa510faf9..a66ddb030383 100644 --- a/packages/eslint-plugin/src/rules/no-invalid-void-type.ts +++ b/packages/eslint-plugin/src/rules/no-invalid-void-type.ts @@ -88,7 +88,7 @@ export default createRule<[Options], MessageIds>({ /** * @brief check if the given void keyword is used as a valid generic type * - * reports if the type parametrized by void is not in the whitelist, or + * reports if the type parametrized by void is not in the allowlist, or * allowInGenericTypeArguments is false. * no-op if the given void keyword is not used as generic type */ @@ -103,7 +103,7 @@ export default createRule<[Options], MessageIds>({ return; } - // check whitelist + // check allowlist if (Array.isArray(allowInGenericTypeArguments)) { const fullyQualifiedName = context.sourceCode .getText(node.parent.parent.typeName) diff --git a/packages/eslint-plugin/src/rules/no-misused-promises.ts b/packages/eslint-plugin/src/rules/no-misused-promises.ts index 6c0a94bf8087..523048bfca7f 100644 --- a/packages/eslint-plugin/src/rules/no-misused-promises.ts +++ b/packages/eslint-plugin/src/rules/no-misused-promises.ts @@ -99,9 +99,13 @@ export default createRule({ additionalProperties: false, properties: { checksConditionals: { + description: + 'Whether to warn when a Promise is provided to conditional statements.', type: 'boolean', }, checksVoidReturn: { + description: + 'Whether to warn when a Promise is returned from a function typed as returning `void`.', oneOf: [ { type: 'boolean' }, { diff --git a/packages/eslint-plugin/src/rules/no-restricted-imports.ts b/packages/eslint-plugin/src/rules/no-restricted-imports.ts index f61baa7ed396..daeb31e051c7 100644 --- a/packages/eslint-plugin/src/rules/no-restricted-imports.ts +++ b/packages/eslint-plugin/src/rules/no-restricted-imports.ts @@ -81,7 +81,7 @@ const baseSchema = baseRule.meta.schema as { const allowTypeImportsOptionSchema: JSONSchema4ObjectSchema['properties'] = { allowTypeImports: { type: 'boolean', - description: 'Disallow value imports, but allow type-only imports.', + description: 'Whether to allow type-only imports for a path.', }, }; diff --git a/packages/eslint-plugin/src/rules/no-restricted-types.ts b/packages/eslint-plugin/src/rules/no-restricted-types.ts index c13f2838d85d..b02242dcf9d1 100644 --- a/packages/eslint-plugin/src/rules/no-restricted-types.ts +++ b/packages/eslint-plugin/src/rules/no-restricted-types.ts @@ -121,6 +121,8 @@ export default createRule({ type: 'object', properties: { types: { + description: + 'An object whose keys are the types you want to ban, and the values are error messages.', type: 'object', additionalProperties: { $ref: '#/items/0/$defs/banConfig', diff --git a/packages/eslint-plugin/src/rules/sort-type-constituents.ts b/packages/eslint-plugin/src/rules/sort-type-constituents.ts index de87dc2aa962..e21cbc55097c 100644 --- a/packages/eslint-plugin/src/rules/sort-type-constituents.ts +++ b/packages/eslint-plugin/src/rules/sort-type-constituents.ts @@ -140,15 +140,16 @@ export default createRule({ additionalProperties: false, properties: { checkIntersections: { - description: 'Whether to check intersection types.', + description: 'Whether to check intersection types (`&`).', type: 'boolean', }, checkUnions: { - description: 'Whether to check union types.', + description: 'Whether to check union types (`|`).', type: 'boolean', }, caseSensitive: { - description: 'Whether to sort using case sensitive sorting.', + description: + 'Whether to sort using case sensitive string comparisons.', type: 'boolean', }, groupOrder: { diff --git a/packages/eslint-plugin/src/rules/strict-boolean-expressions.ts b/packages/eslint-plugin/src/rules/strict-boolean-expressions.ts index 7bd708ac6f9c..400a6882e1e5 100644 --- a/packages/eslint-plugin/src/rules/strict-boolean-expressions.ts +++ b/packages/eslint-plugin/src/rules/strict-boolean-expressions.ts @@ -77,27 +77,27 @@ export default createRule({ }, allowNullableObject: { description: - 'Whether to allow nullable `object`s in a boolean context.', + 'Whether to allow nullable `object`, `symbol`, and functions in a boolean context.', type: 'boolean', }, allowNullableBoolean: { description: - 'Whether to allow nullable `boolean`s in a boolean context.', + 'Whether to allow nullable `boolean` in a boolean context.', type: 'boolean', }, allowNullableString: { description: - 'Whether to allow nullable `string`s in a boolean context.', + 'Whether to allow nullable `string` in a boolean context.', type: 'boolean', }, allowNullableNumber: { description: - 'Whether to allow nullable `number`s in a boolean context.', + 'Whether to allow nullable `number` in a boolean context.', type: 'boolean', }, allowNullableEnum: { description: - 'Whether to allow nullable `enum`s in a boolean context.', + 'Whether to allow nullable `enum` in a boolean context.', type: 'boolean', }, allowAny: { @@ -105,6 +105,8 @@ export default createRule({ type: 'boolean', }, allowRuleToRunWithoutStrictNullChecksIKnowWhatIAmDoing: { + description: + 'Unless this is set to `true`, the rule will error on every file whose `tsconfig.json` does _not_ have the `strictNullChecks` compiler option (or `strict`) set to `true`.', type: 'boolean', }, }, diff --git a/packages/website/package.json b/packages/website/package.json index ee01833b0077..a9fc31f238f8 100644 --- a/packages/website/package.json +++ b/packages/website/package.json @@ -60,6 +60,7 @@ "cross-fetch": "*", "history": "^4.9.0", "make-dir": "*", + "mdast-util-from-markdown": "^2.0.1", "mdast-util-mdx": "^3.0.0", "monaco-editor": "~0.50.0", "raw-loader": "^4.0.2", diff --git a/packages/website/plugins/generated-rule-docs/RuleDocsPage.ts b/packages/website/plugins/generated-rule-docs/RuleDocsPage.ts index e540c014b133..29ca8a6e66c4 100644 --- a/packages/website/plugins/generated-rule-docs/RuleDocsPage.ts +++ b/packages/website/plugins/generated-rule-docs/RuleDocsPage.ts @@ -1,8 +1,9 @@ import type { ESLintPluginRuleModule } from '@typescript-eslint/eslint-plugin/use-at-your-own-risk/rules'; +import { fromMarkdown } from 'mdast-util-from-markdown'; import type * as unist from 'unist'; import type { VFileWithStem } from '../utils/rules'; -import { findH2Index } from '../utils/rules'; +import { findHeadingIndex } from '../utils/rules'; export interface RequiredHeadingIndices { howToUse: number; @@ -57,17 +58,27 @@ export class RuleDocsPage { spliceChildren( start: number, deleteCount: number, - ...items: unist.Node[] + ...items: (string | unist.Node)[] ): void { - this.#children.splice(start, deleteCount, ...items); + this.#children.splice( + start, + deleteCount, + ...items.map(item => + typeof item === 'string' ? fromMarkdown(item) : item, + ), + ); this.#headingIndices = this.#recreateHeadingIndices(); } #recreateHeadingIndices(): RequiredHeadingIndices { return { - howToUse: findH2Index(this.#children, requiredHeadingNames[0]), - options: findH2Index(this.#children, requiredHeadingNames[1]), - whenNotToUseIt: findH2Index(this.#children, requiredHeadingNames[2]), + howToUse: findHeadingIndex(this.#children, 2, requiredHeadingNames[0]), + options: findHeadingIndex(this.#children, 2, requiredHeadingNames[1]), + whenNotToUseIt: findHeadingIndex( + this.#children, + 2, + requiredHeadingNames[2], + ), }; } } diff --git a/packages/website/plugins/generated-rule-docs/createRuleDocsPage.ts b/packages/website/plugins/generated-rule-docs/createRuleDocsPage.ts index 939e50e81704..aef53121a1fe 100644 --- a/packages/website/plugins/generated-rule-docs/createRuleDocsPage.ts +++ b/packages/website/plugins/generated-rule-docs/createRuleDocsPage.ts @@ -3,7 +3,7 @@ import type * as mdast from 'mdast'; import type * as unist from 'unist'; import type { VFileWithStem } from '../utils/rules'; -import { findH2Index } from '../utils/rules'; +import { findHeadingIndex } from '../utils/rules'; import type { HeadingName } from './RuleDocsPage'; import { requiredHeadingNames, RuleDocsPage } from './RuleDocsPage'; @@ -13,7 +13,7 @@ export function createRuleDocsPage( rule: Readonly, ): RuleDocsPage { const headingIndices = requiredHeadingNames.map(headingName => - findH2Index(children, headingName), + findHeadingIndex(children, 2, headingName), ); function insertIfMissing( diff --git a/packages/website/plugins/generated-rule-docs/index.ts b/packages/website/plugins/generated-rule-docs/index.ts index f29c0371748b..69735f844e89 100644 --- a/packages/website/plugins/generated-rule-docs/index.ts +++ b/packages/website/plugins/generated-rule-docs/index.ts @@ -6,8 +6,8 @@ import { isESLintPluginRuleModule, isVFileWithStem } from '../utils/rules'; import { addESLintHashToCodeBlocksMeta } from './addESLintHashToCodeBlocksMeta'; import { createRuleDocsPage } from './createRuleDocsPage'; import { insertBaseRuleReferences } from './insertions/insertBaseRuleReferences'; -import { insertFormattingNotice } from './insertions/insertFormattingNotice'; import { insertNewRuleReferences } from './insertions/insertNewRuleReferences'; +import { insertRuleOptions } from './insertions/insertRuleOptions'; import { insertResources } from './insertions/insertResources'; import { insertRuleDescription } from './insertions/insertRuleDescription'; import { insertWhenNotToUseIt } from './insertions/insertWhenNotToUseIt'; @@ -28,7 +28,6 @@ export const generatedRuleDocs: Plugin = () => { removeSourceCodeNotice(page); insertRuleDescription(page); - insertFormattingNotice(page); const eslintrc = rule.meta.docs.extendsBaseRule ? insertBaseRuleReferences(page) @@ -36,6 +35,7 @@ export const generatedRuleDocs: Plugin = () => { insertWhenNotToUseIt(page); insertResources(page); + insertRuleOptions(page); addESLintHashToCodeBlocksMeta(page, eslintrc); }; }; diff --git a/packages/website/plugins/generated-rule-docs/insertions/insertBaseRuleReferences.ts b/packages/website/plugins/generated-rule-docs/insertions/insertBaseRuleReferences.ts index f88a17a85bc6..b5c1f5604f7e 100644 --- a/packages/website/plugins/generated-rule-docs/insertions/insertBaseRuleReferences.ts +++ b/packages/website/plugins/generated-rule-docs/insertions/insertBaseRuleReferences.ts @@ -10,33 +10,11 @@ export function insertBaseRuleReferences(page: RuleDocsPage): string { ? page.rule.meta.docs.extendsBaseRule : page.file.stem; - page.spliceChildren(page.headingIndices.options + 1, 0, { - children: [ - { - value: 'See ', - type: 'text', - }, - { - children: [ - { - type: 'inlineCode', - value: `eslint/${extendsBaseRuleName}`, - }, - { - type: 'text', - value: ' options', - }, - ], - type: 'link', - url: `https://eslint.org/docs/rules/${extendsBaseRuleName}#options`, - }, - { - type: 'text', - value: '.', - }, - ], - type: 'paragraph', - } as mdast.Paragraph); + page.spliceChildren( + page.headingIndices.options + 1, + 0, + `See [\`eslint/${extendsBaseRuleName}\`'s options](https://eslint.org/docs/rules/${extendsBaseRuleName}#options).`, + ); const eslintrc = getEslintrcString( extendsBaseRuleName, diff --git a/packages/website/plugins/generated-rule-docs/insertions/insertFormattingNotice.ts b/packages/website/plugins/generated-rule-docs/insertions/insertFormattingNotice.ts deleted file mode 100644 index a4ff96e120e8..000000000000 --- a/packages/website/plugins/generated-rule-docs/insertions/insertFormattingNotice.ts +++ /dev/null @@ -1,100 +0,0 @@ -import type { MdxJsxFlowElement } from 'mdast-util-mdx'; - -import type { RuleDocsPage } from '../RuleDocsPage'; - -export function insertFormattingNotice(page: RuleDocsPage): void { - const replacement = page.rule.meta.replacedBy?.find(e => - e.startsWith('@stylistic/'), - ); - if (!replacement) { - return; - } - - const url = - replacement && - `https://eslint.style/rules/${replacement.replace('@stylistic/', '')}`; - - page.spliceChildren(0, 0, { - children: [ - { - type: 'paragraph', - children: [ - { - type: 'text', - value: 'Formatting rules now live in ', - }, - { - type: 'link', - title: null, - url: 'https://eslint.style', - children: [ - { - type: 'text', - value: 'eslint-stylistic', - }, - ], - }, - { - type: 'text', - value: '. ', - }, - ...(url - ? [ - { - type: 'link', - title: null, - url, - children: [ - { - type: 'text', - value: replacement, - }, - ], - }, - { - type: 'text', - value: ' is the replacement for this rule. ', - }, - ] - : []), - { - type: 'break', - }, - { - type: 'text', - value: 'See ', - }, - { - type: 'link', - title: null, - url: '/blog/deprecating-formatting-rules', - children: [ - { - type: 'text', - value: 'Deprecating Formatting Rules', - }, - ], - }, - { - type: 'text', - value: ' for more information.', - }, - ], - }, - ], - attributes: [ - { - type: 'mdxJsxAttribute', - name: 'title', - value: 'Deprecated', - }, - { - type: 'mdxJsxAttribute', - name: 'type', - value: 'danger', - }, - ], - name: 'Admonition', - type: 'mdxJsxFlowElement', - } as MdxJsxFlowElement); -} diff --git a/packages/website/plugins/generated-rule-docs/insertions/insertNewRuleReferences.ts b/packages/website/plugins/generated-rule-docs/insertions/insertNewRuleReferences.ts index 5b601124ef35..08cca0d8e0d3 100644 --- a/packages/website/plugins/generated-rule-docs/insertions/insertNewRuleReferences.ts +++ b/packages/website/plugins/generated-rule-docs/insertions/insertNewRuleReferences.ts @@ -1,6 +1,7 @@ import { EOL } from 'node:os'; import * as path from 'node:path'; +import type { ESLintPluginDocs } from '@typescript-eslint/eslint-plugin/use-at-your-own-risk/rules'; import { compile } from '@typescript-eslint/rule-schema-to-typescript-types'; import type * as mdast from 'mdast'; import type { MdxJsxFlowElement } from 'mdast-util-mdx'; @@ -62,12 +63,9 @@ export async function insertNewRuleReferences( page.spliceChildren( firstH2Index, 0, - { - lang: 'js', - type: 'code', - meta: 'title=".eslintrc.cjs"', - value: `module.exports = ${eslintrc};`, - } as mdast.Code, + `\`\`\`js title=".eslintrc.cjs" +module.exports = ${eslintrc}; +\`\`\``, { attributes: [ { @@ -97,46 +95,18 @@ export async function insertNewRuleReferences( : Object.keys(page.rule.meta.schema).length === 0; if (hasNoConfig) { - page.spliceChildren(page.headingIndices.options + 1, 0, { - children: [ - { - type: 'text', - value: 'This rule is not configurable.', - }, - ], - type: 'paragraph', - } as mdast.Paragraph); + page.spliceChildren( + page.headingIndices.options + 1, + 0, + 'This rule is not configurable.', + ); } else if (!COMPLICATED_RULE_OPTIONS.has(page.file.stem)) { page.spliceChildren( page.headingIndices.options + 1, 0, - { - children: - typeof page.rule.meta.docs.recommended === 'object' - ? [ - { - type: 'text', - value: - 'This rule accepts the following options, and has more strict settings in the ', - } as mdast.Text, - ...linkToConfigs( - page.rule.meta.docs.requiresTypeChecking - ? ['strict', 'strict-type-checked'] - : ['strict'], - ), - { - type: 'text', - value: ` config${page.rule.meta.docs.requiresTypeChecking ? 's' : ''}.`, - } as mdast.Text, - ] - : [ - { - type: 'text', - value: 'This rule accepts the following options:', - } as mdast.Text, - ], - type: 'paragraph', - } as mdast.Paragraph, + typeof page.rule.meta.docs.recommended === 'object' + ? linkToConfigsForObject(page.rule.meta.docs) + : 'This rule accepts the following options:', { lang: 'ts', type: 'code', @@ -156,30 +126,14 @@ export async function insertNewRuleReferences( return eslintrc; } -function linkToConfigs(configs: string[]): mdast.Node[] { - const links = configs.map( - (config): mdast.Link => ({ - children: [ - { - type: 'inlineCode', - value: config, - } as mdast.InlineCode, - ], - type: 'link', - url: `/users/configs#${config}`, - }), - ); - - return links.length === 1 - ? links - : [ - links[0], - { - type: 'text', - value: ' and ', - } as mdast.Text, - links[1], - ]; +function linkToConfigsForObject(docs: ESLintPluginDocs): string { + return [ + 'This rule accepts the following options, and has more strict settings in the', + (docs.requiresTypeChecking ? ['strict', 'strict-type-checked'] : ['strict']) + .map(config => `[${config}](/users/configs#${config})`) + .join(' and '), + `config${docs.requiresTypeChecking ? 's' : ''}.`, + ].join(' '); } function getRuleDefaultOptions(page: RuleDocsPage): string { diff --git a/packages/website/plugins/generated-rule-docs/insertions/insertResources.ts b/packages/website/plugins/generated-rule-docs/insertions/insertResources.ts index 50efedf8a71c..e6b6eb88f096 100644 --- a/packages/website/plugins/generated-rule-docs/insertions/insertResources.ts +++ b/packages/website/plugins/generated-rule-docs/insertions/insertResources.ts @@ -1,4 +1,3 @@ -import type * as mdast from 'mdast'; import type { MdxJsxFlowElement } from 'mdast-util-mdx'; import { getUrlForRuleTest, sourceUrlPrefix } from '../../utils/rules'; @@ -9,61 +8,11 @@ export function insertResources(page: RuleDocsPage): void { page.spliceChildren( page.children.length, 0, - { - children: [ - { - type: 'text', - value: 'Resources', - }, - ], - depth: 2, - type: 'heading', - } as mdast.Heading, - { - children: [ - { - children: [ - { - children: [ - { - type: 'link', - url: `${sourceUrlPrefix}src/rules/${page.file.stem}.ts`, - children: [ - { - type: 'text', - value: 'Rule source', - }, - ], - }, - ], - type: 'paragraph', - }, - ], - type: 'listItem', - }, - { - children: [ - { - children: [ - { - type: 'link', - url: getUrlForRuleTest(page.file.stem), - children: [ - { - type: 'text', - value: 'Test source', - }, - ], - }, - ], - type: 'paragraph', - }, - ], - type: 'listItem', - }, - ], - type: 'list', - } as mdast.List, + `## Resources + +- [Rule source](${sourceUrlPrefix}src/rules/${page.file.stem}.ts) +- [Test source](${getUrlForRuleTest(page.file.stem)}) + `, ); // Also add a notice about coming from ESLint core for extension rules diff --git a/packages/website/plugins/generated-rule-docs/insertions/insertRuleDescription.ts b/packages/website/plugins/generated-rule-docs/insertions/insertRuleDescription.ts index 86d0be107d30..832c35b60264 100644 --- a/packages/website/plugins/generated-rule-docs/insertions/insertRuleDescription.ts +++ b/packages/website/plugins/generated-rule-docs/insertions/insertRuleDescription.ts @@ -1,36 +1,17 @@ -import type * as mdast from 'mdast'; import type { MdxJsxFlowElement } from 'mdast-util-mdx'; import type { RuleDocsPage } from '../RuleDocsPage'; export function insertRuleDescription(page: RuleDocsPage): void { - page.spliceChildren( - 0, - 0, - { - children: [ - { - children: page.rule.meta.docs.description - .split(/`(.+?)`/) - .map((value, index, array) => ({ - type: index % 2 === 0 ? 'text' : 'inlineCode', - value: index === array.length - 1 ? `${value}.` : value, - })), - type: 'paragraph', - }, - ], - type: 'blockquote', - } as mdast.Blockquote, - { - attributes: [ - { - type: 'mdxJsxAttribute', - name: 'name', - value: page.file.stem, - }, - ], - name: 'RuleAttributes', - type: 'mdxJsxFlowElement', - } as MdxJsxFlowElement, - ); + page.spliceChildren(0, 0, `> ${page.rule.meta.docs.description}.`, { + attributes: [ + { + type: 'mdxJsxAttribute', + name: 'name', + value: page.file.stem, + }, + ], + name: 'RuleAttributes', + type: 'mdxJsxFlowElement', + } as MdxJsxFlowElement); } diff --git a/packages/website/plugins/generated-rule-docs/insertions/insertRuleOptions.ts b/packages/website/plugins/generated-rule-docs/insertions/insertRuleOptions.ts new file mode 100644 index 000000000000..d94cc8a2e56c --- /dev/null +++ b/packages/website/plugins/generated-rule-docs/insertions/insertRuleOptions.ts @@ -0,0 +1,93 @@ +import type { JSONSchema4 } from '@typescript-eslint/utils/json-schema'; + +import { findHeadingIndex } from '../../utils/rules'; +import type { RuleDocsPage } from '../RuleDocsPage'; + +const knownSkippedRules = new Set([ + 'array-type', + 'ban-ts-comment', + 'member-ordering', +]); + +const emptyOptionDefaults = new Map([ + ['boolean', false], + ['array', []], +]); + +export function insertRuleOptions(page: RuleDocsPage): void { + if ( + knownSkippedRules.has(page.file.stem) || + !Array.isArray(page.rule.meta.schema) + ) { + return; + } + + const optionProperties = getOptionProperties( + (page.rule.meta.schema as JSONSchema4[]).at(0), + ); + + if (!optionProperties) { + return; + } + + const defaultOptions = (page.rule.defaultOptions[0] ?? {}) as Record< + string, + unknown + >; + + for (const [optionName, option] of Object.entries(optionProperties)) { + if (!option.description) { + if (!page.rule.meta.docs.extendsBaseRule) { + throw new Error(`Missing description for option ${optionName}.`); + } + return; + } + + const existingHeadingIndex = findHeadingIndex( + page.children, + 3, + node => node.type === 'inlineCode' && node.value === optionName, + ); + if (existingHeadingIndex === -1) { + if (!page.rule.meta.docs.extendsBaseRule) { + throw new Error(`Couldn't find h3 for option ${optionName}.`); + } + continue; + } + + const defaultValue = + defaultOptions[optionName] ?? emptyOptionDefaults.get(option.type); + + page.spliceChildren( + existingHeadingIndex + 1, + 0, + defaultValue !== undefined + ? `${option.description} Default: \`${JSON.stringify(defaultValue)}\`.` + : option.description, + ); + } +} + +function getOptionProperties( + options: JSONSchema4 | undefined, +): Record | undefined { + if (!options) { + return undefined; + } + + if (options.type === 'object') { + return options.properties; + } + + if (options.oneOf) { + return options.oneOf.reduce>( + (previous, next) => ({ + ...previous, + ...getOptionProperties(next), + }), + {}, + ); + } + + return undefined; +} diff --git a/packages/website/plugins/generated-rule-docs/insertions/insertWhenNotToUseIt.ts b/packages/website/plugins/generated-rule-docs/insertions/insertWhenNotToUseIt.ts index 7365438bde60..97f03abe2061 100644 --- a/packages/website/plugins/generated-rule-docs/insertions/insertWhenNotToUseIt.ts +++ b/packages/website/plugins/generated-rule-docs/insertions/insertWhenNotToUseIt.ts @@ -1,5 +1,3 @@ -import type * as mdast from 'mdast'; - import { nodeIsHeading } from '../../utils/nodes'; import type { RuleDocsPage } from '../RuleDocsPage'; @@ -23,48 +21,8 @@ export function insertWhenNotToUseIt(page: RuleDocsPage): void { page.spliceChildren( nextHeadingIndex === -1 ? page.children.length : nextHeadingIndex - 1, 0, - { - children: [ - ...(hasExistingText ? [{ type: 'thematicBreak' }] : []), - { - type: 'text', - value: - 'Type checked lint rules are more powerful than traditional lint rules, but also require configuring ', - }, - { - type: 'link', - title: null, - url: `/getting-started/typed-linting`, - children: [ - { - type: 'text', - value: 'type checked linting', - }, - ], - }, - { - type: 'text', - value: '. See ', - }, - { - type: 'link', - title: null, - url: `/troubleshooting/typed-linting/performance`, - children: [ - { - type: 'text', - value: - 'Troubleshooting > Linting with Type Information > Performance', - }, - ], - }, - { - type: 'text', - value: - ' if you experience performance degredations after enabling type checked rules.', - }, - ], - type: 'paragraph', - } as mdast.Paragraph, + ...(hasExistingText ? ['---'] : []), + 'Type checked lint rules are more powerful than traditional lint rules, but also require configuring [type checked linting](/getting-started/typed-linting).', + 'See [Troubleshooting > Linting with Type Information > Performance](/troubleshooting/typed-linting/performance) if you experience performance degredations after enabling type checked rules.', ); } diff --git a/packages/website/plugins/utils/rules.ts b/packages/website/plugins/utils/rules.ts index 02130f2e28db..508616497146 100644 --- a/packages/website/plugins/utils/rules.ts +++ b/packages/website/plugins/utils/rules.ts @@ -4,6 +4,7 @@ import * as path from 'node:path'; import type { ESLintPluginRuleModule } from '@typescript-eslint/eslint-plugin/use-at-your-own-risk/rules'; import type { RuleModule } from '@typescript-eslint/utils/ts-eslint'; import * as lz from 'lz-string'; +import type * as mdast from 'mdast'; import type * as unist from 'unist'; import type { VFile } from 'vfile'; @@ -68,16 +69,22 @@ export function isVFileWithStem(file: VFile): file is VFileWithStem { return !!file.stem; } -export function findH2Index( - children: unist.Node[], - headingName: string, +export function findHeadingIndex( + children: readonly unist.Node[], + depth: 2 | 3, + contents: string | ((node: mdast.PhrasingContent) => boolean), ): number { + const childMatch = + typeof contents === 'string' + ? (node: mdast.PhrasingContent): boolean => + node.type === 'text' && node.value === contents + : contents; + return children.findIndex( node => nodeIsHeading(node) && - node.depth === 2 && + node.depth === depth && node.children.length === 1 && - node.children[0].type === 'text' && - node.children[0].value === headingName, + childMatch(node.children[0]), ); } diff --git a/yarn.lock b/yarn.lock index 58d81d900b9a..afb86e2bf1cc 100644 --- a/yarn.lock +++ b/yarn.lock @@ -14011,7 +14011,7 @@ __metadata: languageName: node linkType: hard -"mdast-util-from-markdown@npm:^2.0.0": +"mdast-util-from-markdown@npm:^2.0.0, mdast-util-from-markdown@npm:^2.0.1": version: 2.0.1 resolution: "mdast-util-from-markdown@npm:2.0.1" dependencies: @@ -20203,6 +20203,7 @@ __metadata: konamimojisplosion: ^0.5.2 lz-string: ^1.5.0 make-dir: "*" + mdast-util-from-markdown: ^2.0.1 mdast-util-mdx: ^3.0.0 monaco-editor: ~0.50.0 prettier: ^3.2.5 From 3588e07562e384960cfe646068a5858031c37abe Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Fri, 20 Sep 2024 10:04:17 -0400 Subject: [PATCH 2/8] A few more missing descriptions --- .../docs/rules/prefer-destructuring.mdx | 2 -- .../src/rules/class-literal-property-style.ts | 1 + .../rules/consistent-generic-constructors.ts | 1 + .../rules/consistent-indexed-object-style.ts | 1 + .../src/rules/consistent-type-definitions.ts | 1 + .../src/rules/no-invalid-void-type.ts | 8 ++++++- .../src/rules/no-misused-promises.ts | 8 ++++++- .../src/rules/no-use-before-define.ts | 5 ++++- .../src/rules/prefer-destructuring.ts | 4 ++++ .../src/rules/prefer-nullish-coalescing.ts | 22 +++++++++++++++---- 10 files changed, 44 insertions(+), 9 deletions(-) diff --git a/packages/eslint-plugin/docs/rules/prefer-destructuring.mdx b/packages/eslint-plugin/docs/rules/prefer-destructuring.mdx index 411e376b7243..80a4711aeffa 100644 --- a/packages/eslint-plugin/docs/rules/prefer-destructuring.mdx +++ b/packages/eslint-plugin/docs/rules/prefer-destructuring.mdx @@ -80,8 +80,6 @@ const defaultOptions: Options = [ ### `enforceForDeclarationWithTypeAnnotation` -When set to `true`, type annotated variable declarations are enforced to use destructuring assignment. - Examples with `{ enforceForDeclarationWithTypeAnnotation: true }`: diff --git a/packages/eslint-plugin/src/rules/class-literal-property-style.ts b/packages/eslint-plugin/src/rules/class-literal-property-style.ts index 28d4a5cc78ba..58c158eecea0 100644 --- a/packages/eslint-plugin/src/rules/class-literal-property-style.ts +++ b/packages/eslint-plugin/src/rules/class-literal-property-style.ts @@ -72,6 +72,7 @@ export default createRule({ }, schema: [ { + description: 'Which literal class member syntax to prefer.', type: 'string', enum: ['fields', 'getters'], }, diff --git a/packages/eslint-plugin/src/rules/consistent-generic-constructors.ts b/packages/eslint-plugin/src/rules/consistent-generic-constructors.ts index c4a110c7aa86..6cd2c14b26fc 100644 --- a/packages/eslint-plugin/src/rules/consistent-generic-constructors.ts +++ b/packages/eslint-plugin/src/rules/consistent-generic-constructors.ts @@ -24,6 +24,7 @@ export default createRule({ fixable: 'code', schema: [ { + description: 'Which constructor call syntax to prefer.', type: 'string', enum: ['type-annotation', 'constructor'], }, diff --git a/packages/eslint-plugin/src/rules/consistent-indexed-object-style.ts b/packages/eslint-plugin/src/rules/consistent-indexed-object-style.ts index f0f91cc32b8e..dc515af5b045 100644 --- a/packages/eslint-plugin/src/rules/consistent-indexed-object-style.ts +++ b/packages/eslint-plugin/src/rules/consistent-indexed-object-style.ts @@ -21,6 +21,7 @@ export default createRule({ fixable: 'code', schema: [ { + description: 'Which indexed object syntax to prefer.', type: 'string', enum: ['record', 'index-signature'], }, diff --git a/packages/eslint-plugin/src/rules/consistent-type-definitions.ts b/packages/eslint-plugin/src/rules/consistent-type-definitions.ts index 45b156fdf0ee..8614c9f9c143 100644 --- a/packages/eslint-plugin/src/rules/consistent-type-definitions.ts +++ b/packages/eslint-plugin/src/rules/consistent-type-definitions.ts @@ -18,6 +18,7 @@ export default createRule({ }, schema: [ { + description: 'Which type definition syntax to prefer.', type: 'string', enum: ['interface', 'type'], }, diff --git a/packages/eslint-plugin/src/rules/no-invalid-void-type.ts b/packages/eslint-plugin/src/rules/no-invalid-void-type.ts index a66ddb030383..2b18d42ee8e0 100644 --- a/packages/eslint-plugin/src/rules/no-invalid-void-type.ts +++ b/packages/eslint-plugin/src/rules/no-invalid-void-type.ts @@ -45,8 +45,14 @@ export default createRule<[Options], MessageIds>({ description: 'Whether `void` can be used as a valid value for generic type parameters.', oneOf: [ - { type: 'boolean' }, { + description: + 'Whether `void` can be used as a valid value for all generic type parameters.', + type: 'boolean', + }, + { + description: + 'Allowlist of types that may accept `void` as a generic type parameter.', type: 'array', items: { type: 'string' }, minItems: 1, diff --git a/packages/eslint-plugin/src/rules/no-misused-promises.ts b/packages/eslint-plugin/src/rules/no-misused-promises.ts index 6961df37d168..d834b2b324f5 100644 --- a/packages/eslint-plugin/src/rules/no-misused-promises.ts +++ b/packages/eslint-plugin/src/rules/no-misused-promises.ts @@ -110,9 +110,15 @@ export default createRule({ description: 'Whether to warn when a Promise is returned from a function typed as returning `void`.', oneOf: [ - { type: 'boolean' }, + { + description: + 'Whether to disable checking all asynchronous functions.', + type: 'boolean', + }, { additionalProperties: false, + description: + 'Which forms of functions may have checking disabled.', properties: { arguments: { description: diff --git a/packages/eslint-plugin/src/rules/no-use-before-define.ts b/packages/eslint-plugin/src/rules/no-use-before-define.ts index 4c6cc0041971..03fe4c8c4b8b 100644 --- a/packages/eslint-plugin/src/rules/no-use-before-define.ts +++ b/packages/eslint-plugin/src/rules/no-use-before-define.ts @@ -262,7 +262,10 @@ export default createRule({ 'Whether to ignore type references, such as in type annotations and assertions.', type: 'boolean', }, - allowNamedExports: { type: 'boolean' }, + allowNamedExports: { + description: 'Whether to ignore named exports.', + type: 'boolean', + }, }, additionalProperties: false, }, diff --git a/packages/eslint-plugin/src/rules/prefer-destructuring.ts b/packages/eslint-plugin/src/rules/prefer-destructuring.ts index 60e53dbb61e6..0fcdd2403329 100644 --- a/packages/eslint-plugin/src/rules/prefer-destructuring.ts +++ b/packages/eslint-plugin/src/rules/prefer-destructuring.ts @@ -52,9 +52,13 @@ const schema: readonly JSONSchema4[] = [ type: 'object', properties: { enforceForRenamedProperties: { + description: + 'Whether to enforce destructuring that use a different variable name than the property name.', type: 'boolean', }, enforceForDeclarationWithTypeAnnotation: { + description: + 'Whether to enforce destructuring on variable declarations with type annotations.', type: 'boolean', }, }, diff --git a/packages/eslint-plugin/src/rules/prefer-nullish-coalescing.ts b/packages/eslint-plugin/src/rules/prefer-nullish-coalescing.ts index 05de88296a4f..f5b3fd39f32d 100644 --- a/packages/eslint-plugin/src/rules/prefer-nullish-coalescing.ts +++ b/packages/eslint-plugin/src/rules/prefer-nullish-coalescing.ts @@ -84,15 +84,29 @@ export default createRule({ 'Whether to ignore all (`true`) or some (an object with properties) primitive types.', oneOf: [ { + description: 'Which primitives types may be ignored.', type: 'object', properties: { - bigint: { type: 'boolean' }, - boolean: { type: 'boolean' }, - number: { type: 'boolean' }, - string: { type: 'boolean' }, + bigint: { + description: 'Ignore bigint primitive types.', + type: 'boolean', + }, + boolean: { + description: 'Ignore boolean primitive types.', + type: 'boolean', + }, + number: { + description: 'Ignore number primitive types.', + type: 'boolean', + }, + string: { + description: 'Ignore string primitive types.', + type: 'boolean', + }, }, }, { + description: 'Ignore all primitive types.', type: 'boolean', enum: [true], }, From d93bc268ff6574df631bef769f81aa71b61172ba Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Fri, 20 Sep 2024 10:05:36 -0400 Subject: [PATCH 3/8] chore: lint --- packages/website/plugins/generated-rule-docs/index.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/website/plugins/generated-rule-docs/index.ts b/packages/website/plugins/generated-rule-docs/index.ts index 69735f844e89..088c53e1b534 100644 --- a/packages/website/plugins/generated-rule-docs/index.ts +++ b/packages/website/plugins/generated-rule-docs/index.ts @@ -7,9 +7,9 @@ import { addESLintHashToCodeBlocksMeta } from './addESLintHashToCodeBlocksMeta'; import { createRuleDocsPage } from './createRuleDocsPage'; import { insertBaseRuleReferences } from './insertions/insertBaseRuleReferences'; import { insertNewRuleReferences } from './insertions/insertNewRuleReferences'; -import { insertRuleOptions } from './insertions/insertRuleOptions'; import { insertResources } from './insertions/insertResources'; import { insertRuleDescription } from './insertions/insertRuleDescription'; +import { insertRuleOptions } from './insertions/insertRuleOptions'; import { insertWhenNotToUseIt } from './insertions/insertWhenNotToUseIt'; import { removeSourceCodeNotice } from './removeSourceCodeNotice'; From a76371b8fb0cd6930f8ab4788ccb5af9457bad27 Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Fri, 20 Sep 2024 10:32:55 -0400 Subject: [PATCH 4/8] Update test snapshots and SBE --- .../src/rules/explicit-member-accessibility.ts | 2 +- .../src/rules/strict-boolean-expressions.ts | 16 ++++++++-------- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/packages/eslint-plugin/src/rules/explicit-member-accessibility.ts b/packages/eslint-plugin/src/rules/explicit-member-accessibility.ts index a4f3c80c14ae..c2f738bd85b3 100644 --- a/packages/eslint-plugin/src/rules/explicit-member-accessibility.ts +++ b/packages/eslint-plugin/src/rules/explicit-member-accessibility.ts @@ -82,7 +82,7 @@ export default createRule({ accessibility: { $ref: '#/items/0/$defs/accessibilityLevel', description: - 'Which of accessibility modifier is required to exist or not exist.', + 'Which accessibility modifier is required to exist or not exist.', }, overrides: { description: diff --git a/packages/eslint-plugin/src/rules/strict-boolean-expressions.ts b/packages/eslint-plugin/src/rules/strict-boolean-expressions.ts index 400a6882e1e5..a13c44c39177 100644 --- a/packages/eslint-plugin/src/rules/strict-boolean-expressions.ts +++ b/packages/eslint-plugin/src/rules/strict-boolean-expressions.ts @@ -68,40 +68,40 @@ export default createRule({ type: 'object', properties: { allowString: { - description: 'Whether to allow `string` in a boolean context.', + description: 'Whether to allow `string`s in a boolean context.', type: 'boolean', }, allowNumber: { - description: 'Whether to allow `number` in a boolean context.', + description: 'Whether to allow `number`s in a boolean context.', type: 'boolean', }, allowNullableObject: { description: - 'Whether to allow nullable `object`, `symbol`, and functions in a boolean context.', + 'Whether to allow nullable `object`s, `symbol`s, and functions in a boolean context.', type: 'boolean', }, allowNullableBoolean: { description: - 'Whether to allow nullable `boolean` in a boolean context.', + 'Whether to allow nullable `boolean`s in a boolean context.', type: 'boolean', }, allowNullableString: { description: - 'Whether to allow nullable `string` in a boolean context.', + 'Whether to allow nullable `string`s in a boolean context.', type: 'boolean', }, allowNullableNumber: { description: - 'Whether to allow nullable `number` in a boolean context.', + 'Whether to allow nullable `number`s in a boolean context.', type: 'boolean', }, allowNullableEnum: { description: - 'Whether to allow nullable `enum` in a boolean context.', + 'Whether to allow nullable `enum`s in a boolean context.', type: 'boolean', }, allowAny: { - description: 'Whether to allow `any` in a boolean context.', + description: 'Whether to allow `any`s in a boolean context.', type: 'boolean', }, allowRuleToRunWithoutStrictNullChecksIKnowWhatIAmDoing: { From 91556db455a0559283c3682c43d5c4c24e331140 Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Fri, 20 Sep 2024 10:34:07 -0400 Subject: [PATCH 5/8] Actually update snapshots --- .../class-literal-property-style.shot | 8 ++++++- .../consistent-generic-constructors.shot | 8 ++++++- .../consistent-indexed-object-style.shot | 8 ++++++- .../consistent-type-definitions.shot | 8 ++++++- .../explicit-member-accessibility.shot | 6 ++++- .../no-invalid-void-type.shot | 13 +++++++---- .../schema-snapshots/no-misused-promises.shot | 16 ++++++++++--- .../no-restricted-imports.shot | 12 +++++----- .../schema-snapshots/no-restricted-types.shot | 2 ++ .../no-use-before-define.shot | 2 ++ .../prefer-destructuring.shot | 4 ++++ .../prefer-nullish-coalescing.shot | 23 +++++++++++++++---- .../sort-type-constituents.shot | 12 +++++----- .../strict-boolean-expressions.shot | 18 ++++++++------- 14 files changed, 103 insertions(+), 37 deletions(-) diff --git a/packages/eslint-plugin/tests/schema-snapshots/class-literal-property-style.shot b/packages/eslint-plugin/tests/schema-snapshots/class-literal-property-style.shot index ab5b34c1d89c..0a601ac8f34d 100644 --- a/packages/eslint-plugin/tests/schema-snapshots/class-literal-property-style.shot +++ b/packages/eslint-plugin/tests/schema-snapshots/class-literal-property-style.shot @@ -6,6 +6,7 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos [ { + "description": "Which literal class member syntax to prefer.", "enum": ["fields", "getters"], "type": "string" } @@ -14,6 +15,11 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos # TYPES: -type Options = ['fields' | 'getters']; +type Options = [ + /** Which literal class member syntax to prefer. */ + | 'getters' + /** Which literal class member syntax to prefer. */ + | 'fields', +]; " `; diff --git a/packages/eslint-plugin/tests/schema-snapshots/consistent-generic-constructors.shot b/packages/eslint-plugin/tests/schema-snapshots/consistent-generic-constructors.shot index 339f564088a9..7f40a340e498 100644 --- a/packages/eslint-plugin/tests/schema-snapshots/consistent-generic-constructors.shot +++ b/packages/eslint-plugin/tests/schema-snapshots/consistent-generic-constructors.shot @@ -6,6 +6,7 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos [ { + "description": "Which constructor call syntax to prefer.", "enum": ["constructor", "type-annotation"], "type": "string" } @@ -14,6 +15,11 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos # TYPES: -type Options = ['constructor' | 'type-annotation']; +type Options = [ + /** Which constructor call syntax to prefer. */ + | 'type-annotation' + /** Which constructor call syntax to prefer. */ + | 'constructor', +]; " `; diff --git a/packages/eslint-plugin/tests/schema-snapshots/consistent-indexed-object-style.shot b/packages/eslint-plugin/tests/schema-snapshots/consistent-indexed-object-style.shot index d498aa9d3571..e6aac3062fc5 100644 --- a/packages/eslint-plugin/tests/schema-snapshots/consistent-indexed-object-style.shot +++ b/packages/eslint-plugin/tests/schema-snapshots/consistent-indexed-object-style.shot @@ -6,6 +6,7 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos [ { + "description": "Which indexed object syntax to prefer.", "enum": ["index-signature", "record"], "type": "string" } @@ -14,6 +15,11 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos # TYPES: -type Options = ['index-signature' | 'record']; +type Options = [ + /** Which indexed object syntax to prefer. */ + | 'record' + /** Which indexed object syntax to prefer. */ + | 'index-signature', +]; " `; diff --git a/packages/eslint-plugin/tests/schema-snapshots/consistent-type-definitions.shot b/packages/eslint-plugin/tests/schema-snapshots/consistent-type-definitions.shot index 0a7217423843..a47225168222 100644 --- a/packages/eslint-plugin/tests/schema-snapshots/consistent-type-definitions.shot +++ b/packages/eslint-plugin/tests/schema-snapshots/consistent-type-definitions.shot @@ -6,6 +6,7 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos [ { + "description": "Which type definition syntax to prefer.", "enum": ["interface", "type"], "type": "string" } @@ -14,6 +15,11 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos # TYPES: -type Options = ['interface' | 'type']; +type Options = [ + /** Which type definition syntax to prefer. */ + | 'type' + /** Which type definition syntax to prefer. */ + | 'interface', +]; " `; diff --git a/packages/eslint-plugin/tests/schema-snapshots/explicit-member-accessibility.shot b/packages/eslint-plugin/tests/schema-snapshots/explicit-member-accessibility.shot index 38813f579a5e..0606e4d377b1 100644 --- a/packages/eslint-plugin/tests/schema-snapshots/explicit-member-accessibility.shot +++ b/packages/eslint-plugin/tests/schema-snapshots/explicit-member-accessibility.shot @@ -30,7 +30,8 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos "additionalProperties": false, "properties": { "accessibility": { - "$ref": "#/items/0/$defs/accessibilityLevel" + "$ref": "#/items/0/$defs/accessibilityLevel", + "description": "Which accessibility modifier is required to exist or not exist." }, "ignoredMethodNames": { "description": "Specific method names that may be ignored.", @@ -41,6 +42,7 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos }, "overrides": { "additionalProperties": false, + "description": "Changes to required accessibility modifiers for specific kinds of class members.", "properties": { "accessors": { "$ref": "#/items/0/$defs/accessibilityLevel" @@ -78,9 +80,11 @@ type AccessibilityLevel = type Options = [ { + /** Which accessibility modifier is required to exist or not exist. */ accessibility?: AccessibilityLevel; /** Specific method names that may be ignored. */ ignoredMethodNames?: string[]; + /** Changes to required accessibility modifiers for specific kinds of class members. */ overrides?: { accessors?: AccessibilityLevel; constructors?: AccessibilityLevel; diff --git a/packages/eslint-plugin/tests/schema-snapshots/no-invalid-void-type.shot b/packages/eslint-plugin/tests/schema-snapshots/no-invalid-void-type.shot index a02fca83275d..c6610bd2980c 100644 --- a/packages/eslint-plugin/tests/schema-snapshots/no-invalid-void-type.shot +++ b/packages/eslint-plugin/tests/schema-snapshots/no-invalid-void-type.shot @@ -16,9 +16,11 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos "description": "Whether \`void\` can be used as a valid value for generic type parameters.", "oneOf": [ { + "description": "Whether \`void\` can be used as a valid value for all generic type parameters.", "type": "boolean" }, { + "description": "Allowlist of types that may accept \`void\` as a generic type parameter.", "items": { "type": "string" }, @@ -40,10 +42,13 @@ type Options = [ /** Whether a \`this\` parameter of a function may be \`void\`. */ allowAsThisParameter?: boolean; /** Whether \`void\` can be used as a valid value for generic type parameters. */ - allowInGenericTypeArguments?: - | [string, ...string[]] - /** Whether \`void\` can be used as a valid value for generic type parameters. */ - | boolean; + allowInGenericTypeArguments?: /** + * Whether \`void\` can be used as a valid value for generic type parameters. + * Whether \`void\` can be used as a valid value for all generic type parameters. + */ + | boolean + /** Allowlist of types that may accept \`void\` as a generic type parameter. */ + | [string, ...string[]]; }, ]; " diff --git a/packages/eslint-plugin/tests/schema-snapshots/no-misused-promises.shot b/packages/eslint-plugin/tests/schema-snapshots/no-misused-promises.shot index e0d897012c0a..4ce87848cced 100644 --- a/packages/eslint-plugin/tests/schema-snapshots/no-misused-promises.shot +++ b/packages/eslint-plugin/tests/schema-snapshots/no-misused-promises.shot @@ -9,6 +9,7 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos "additionalProperties": false, "properties": { "checksConditionals": { + "description": "Whether to warn when a Promise is provided to conditional statements.", "type": "boolean" }, "checksSpreads": { @@ -16,12 +17,15 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos "type": "boolean" }, "checksVoidReturn": { + "description": "Whether to warn when a Promise is returned from a function typed as returning \`void\`.", "oneOf": [ { + "description": "Whether to disable checking all asynchronous functions.", "type": "boolean" }, { "additionalProperties": false, + "description": "Which forms of functions may have checking disabled.", "properties": { "arguments": { "description": "Disables checking an asynchronous function passed as argument where the parameter type expects a function that returns \`void\`.", @@ -62,10 +66,17 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos type Options = [ { + /** Whether to warn when a Promise is provided to conditional statements. */ checksConditionals?: boolean; /** Whether to warn when \`...\` spreading a \`Promise\`. */ checksSpreads?: boolean; - checksVoidReturn?: + /** Whether to warn when a Promise is returned from a function typed as returning \`void\`. */ + checksVoidReturn?: /** + * Whether to warn when a Promise is returned from a function typed as returning \`void\`. + * Whether to disable checking all asynchronous functions. + */ + | boolean + /** Which forms of functions may have checking disabled. */ | { /** Disables checking an asynchronous function passed as argument where the parameter type expects a function that returns \`void\`. */ arguments?: boolean; @@ -79,8 +90,7 @@ type Options = [ returns?: boolean; /** Disables checking an asynchronous function used as a variable whose return type is a function that returns \`void\`. */ variables?: boolean; - } - | boolean; + }; }, ]; " diff --git a/packages/eslint-plugin/tests/schema-snapshots/no-restricted-imports.shot b/packages/eslint-plugin/tests/schema-snapshots/no-restricted-imports.shot index 55bec533996f..7c4fb5932293 100644 --- a/packages/eslint-plugin/tests/schema-snapshots/no-restricted-imports.shot +++ b/packages/eslint-plugin/tests/schema-snapshots/no-restricted-imports.shot @@ -22,7 +22,7 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos "type": "array" }, "allowTypeImports": { - "description": "Disallow value imports, but allow type-only imports.", + "description": "Whether to allow type-only imports for a path.", "type": "boolean" }, "importNames": { @@ -69,7 +69,7 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos "type": "array" }, "allowTypeImports": { - "description": "Disallow value imports, but allow type-only imports.", + "description": "Whether to allow type-only imports for a path.", "type": "boolean" }, "importNames": { @@ -119,7 +119,7 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos "uniqueItems": true }, "allowTypeImports": { - "description": "Disallow value imports, but allow type-only imports.", + "description": "Whether to allow type-only imports for a path.", "type": "boolean" }, "caseSensitive": { @@ -173,7 +173,7 @@ type Options = | ( | { allowImportNames?: string[]; - /** Disallow value imports, but allow type-only imports. */ + /** Whether to allow type-only imports for a path. */ allowTypeImports?: boolean; importNames?: string[]; message?: string; @@ -187,7 +187,7 @@ type Options = paths?: ( | { allowImportNames?: string[]; - /** Disallow value imports, but allow type-only imports. */ + /** Whether to allow type-only imports for a path. */ allowTypeImports?: boolean; importNames?: string[]; message?: string; @@ -199,7 +199,7 @@ type Options = | { allowImportNamePattern?: string; allowImportNames?: [string, ...string[]]; - /** Disallow value imports, but allow type-only imports. */ + /** Whether to allow type-only imports for a path. */ allowTypeImports?: boolean; caseSensitive?: boolean; group: [string, ...string[]]; diff --git a/packages/eslint-plugin/tests/schema-snapshots/no-restricted-types.shot b/packages/eslint-plugin/tests/schema-snapshots/no-restricted-types.shot index 845262dabe82..8dddf55f996b 100644 --- a/packages/eslint-plugin/tests/schema-snapshots/no-restricted-types.shot +++ b/packages/eslint-plugin/tests/schema-snapshots/no-restricted-types.shot @@ -49,6 +49,7 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos "additionalProperties": { "$ref": "#/items/0/$defs/banConfig" }, + "description": "An object whose keys are the types you want to ban, and the values are error messages.", "type": "object" } }, @@ -76,6 +77,7 @@ type BanConfig = type Options = [ { + /** An object whose keys are the types you want to ban, and the values are error messages. */ types?: { [k: string]: BanConfig; }; diff --git a/packages/eslint-plugin/tests/schema-snapshots/no-use-before-define.shot b/packages/eslint-plugin/tests/schema-snapshots/no-use-before-define.shot index a094b1776731..192552d4fd41 100644 --- a/packages/eslint-plugin/tests/schema-snapshots/no-use-before-define.shot +++ b/packages/eslint-plugin/tests/schema-snapshots/no-use-before-define.shot @@ -15,6 +15,7 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos "additionalProperties": false, "properties": { "allowNamedExports": { + "description": "Whether to ignore named exports.", "type": "boolean" }, "classes": { @@ -54,6 +55,7 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos type Options = [ | 'nofunc' | { + /** Whether to ignore named exports. */ allowNamedExports?: boolean; /** Whether to ignore references to class declarations. */ classes?: boolean; diff --git a/packages/eslint-plugin/tests/schema-snapshots/prefer-destructuring.shot b/packages/eslint-plugin/tests/schema-snapshots/prefer-destructuring.shot index ca0e2597bf59..1769b32c5ce9 100644 --- a/packages/eslint-plugin/tests/schema-snapshots/prefer-destructuring.shot +++ b/packages/eslint-plugin/tests/schema-snapshots/prefer-destructuring.shot @@ -54,9 +54,11 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos { "properties": { "enforceForDeclarationWithTypeAnnotation": { + "description": "Whether to enforce destructuring on variable declarations with type annotations.", "type": "boolean" }, "enforceForRenamedProperties": { + "description": "Whether to enforce destructuring that use a different variable name than the property name.", "type": "boolean" } }, @@ -85,7 +87,9 @@ type Options = [ } ), { + /** Whether to enforce destructuring on variable declarations with type annotations. */ enforceForDeclarationWithTypeAnnotation?: boolean; + /** Whether to enforce destructuring that use a different variable name than the property name. */ enforceForRenamedProperties?: boolean; [k: string]: unknown; }, diff --git a/packages/eslint-plugin/tests/schema-snapshots/prefer-nullish-coalescing.shot b/packages/eslint-plugin/tests/schema-snapshots/prefer-nullish-coalescing.shot index 7afce381e977..58a4820086c3 100644 --- a/packages/eslint-plugin/tests/schema-snapshots/prefer-nullish-coalescing.shot +++ b/packages/eslint-plugin/tests/schema-snapshots/prefer-nullish-coalescing.shot @@ -24,23 +24,29 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos "description": "Whether to ignore all (\`true\`) or some (an object with properties) primitive types.", "oneOf": [ { + "description": "Which primitives types may be ignored.", "properties": { "bigint": { + "description": "Ignore bigint primitive types.", "type": "boolean" }, "boolean": { + "description": "Ignore boolean primitive types.", "type": "boolean" }, "number": { + "description": "Ignore number primitive types.", "type": "boolean" }, "string": { + "description": "Ignore string primitive types.", "type": "boolean" } }, "type": "object" }, { + "description": "Ignore all primitive types.", "enum": [true], "type": "boolean" } @@ -67,16 +73,23 @@ type Options = [ /** Whether to ignore any logical or expressions that are part of a mixed logical expression (with \`&&\`). */ ignoreMixedLogicalExpressions?: boolean; /** Whether to ignore all (\`true\`) or some (an object with properties) primitive types. */ - ignorePrimitives?: - | true - /** Whether to ignore all (\`true\`) or some (an object with properties) primitive types. */ - | { + ignorePrimitives?: /** + * Whether to ignore all (\`true\`) or some (an object with properties) primitive types. + * Which primitives types may be ignored. + */ + | { + /** Ignore bigint primitive types. */ bigint?: boolean; + /** Ignore boolean primitive types. */ boolean?: boolean; + /** Ignore number primitive types. */ number?: boolean; + /** Ignore string primitive types. */ string?: boolean; [k: string]: unknown; - }; + } + /** Ignore all primitive types. */ + | true; /** Whether to ignore any ternary expressions that could be simplified by using the nullish coalescing operator. */ ignoreTernaryTests?: boolean; }, diff --git a/packages/eslint-plugin/tests/schema-snapshots/sort-type-constituents.shot b/packages/eslint-plugin/tests/schema-snapshots/sort-type-constituents.shot index 2b5fe0203a1a..32232ad1ab67 100644 --- a/packages/eslint-plugin/tests/schema-snapshots/sort-type-constituents.shot +++ b/packages/eslint-plugin/tests/schema-snapshots/sort-type-constituents.shot @@ -9,15 +9,15 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos "additionalProperties": false, "properties": { "caseSensitive": { - "description": "Whether to sort using case sensitive sorting.", + "description": "Whether to sort using case sensitive string comparisons.", "type": "boolean" }, "checkIntersections": { - "description": "Whether to check intersection types.", + "description": "Whether to check intersection types (\`&\`).", "type": "boolean" }, "checkUnions": { - "description": "Whether to check union types.", + "description": "Whether to check union types (\`|\`).", "type": "boolean" }, "groupOrder": { @@ -51,11 +51,11 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos type Options = [ { - /** Whether to sort using case sensitive sorting. */ + /** Whether to sort using case sensitive string comparisons. */ caseSensitive?: boolean; - /** Whether to check intersection types. */ + /** Whether to check intersection types (\`&\`). */ checkIntersections?: boolean; - /** Whether to check union types. */ + /** Whether to check union types (\`|\`). */ checkUnions?: boolean; /** Ordering of the groups. */ groupOrder?: ( diff --git a/packages/eslint-plugin/tests/schema-snapshots/strict-boolean-expressions.shot b/packages/eslint-plugin/tests/schema-snapshots/strict-boolean-expressions.shot index 5c52af177f3d..77591c6228fc 100644 --- a/packages/eslint-plugin/tests/schema-snapshots/strict-boolean-expressions.shot +++ b/packages/eslint-plugin/tests/schema-snapshots/strict-boolean-expressions.shot @@ -9,7 +9,7 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos "additionalProperties": false, "properties": { "allowAny": { - "description": "Whether to allow \`any\` in a boolean context.", + "description": "Whether to allow \`any\`s in a boolean context.", "type": "boolean" }, "allowNullableBoolean": { @@ -25,7 +25,7 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos "type": "boolean" }, "allowNullableObject": { - "description": "Whether to allow nullable \`object\`s in a boolean context.", + "description": "Whether to allow nullable \`object\`s, \`symbol\`s, and functions in a boolean context.", "type": "boolean" }, "allowNullableString": { @@ -33,14 +33,15 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos "type": "boolean" }, "allowNumber": { - "description": "Whether to allow \`number\` in a boolean context.", + "description": "Whether to allow \`number\`s in a boolean context.", "type": "boolean" }, "allowRuleToRunWithoutStrictNullChecksIKnowWhatIAmDoing": { + "description": "Unless this is set to \`true\`, the rule will error on every file whose \`tsconfig.json\` does _not_ have the \`strictNullChecks\` compiler option (or \`strict\`) set to \`true\`.", "type": "boolean" }, "allowString": { - "description": "Whether to allow \`string\` in a boolean context.", + "description": "Whether to allow \`string\`s in a boolean context.", "type": "boolean" } }, @@ -53,7 +54,7 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos type Options = [ { - /** Whether to allow \`any\` in a boolean context. */ + /** Whether to allow \`any\`s in a boolean context. */ allowAny?: boolean; /** Whether to allow nullable \`boolean\`s in a boolean context. */ allowNullableBoolean?: boolean; @@ -61,14 +62,15 @@ type Options = [ allowNullableEnum?: boolean; /** Whether to allow nullable \`number\`s in a boolean context. */ allowNullableNumber?: boolean; - /** Whether to allow nullable \`object\`s in a boolean context. */ + /** Whether to allow nullable \`object\`s, \`symbol\`s, and functions in a boolean context. */ allowNullableObject?: boolean; /** Whether to allow nullable \`string\`s in a boolean context. */ allowNullableString?: boolean; - /** Whether to allow \`number\` in a boolean context. */ + /** Whether to allow \`number\`s in a boolean context. */ allowNumber?: boolean; + /** Unless this is set to \`true\`, the rule will error on every file whose \`tsconfig.json\` does _not_ have the \`strictNullChecks\` compiler option (or \`strict\`) set to \`true\`. */ allowRuleToRunWithoutStrictNullChecksIKnowWhatIAmDoing?: boolean; - /** Whether to allow \`string\` in a boolean context. */ + /** Whether to allow \`string\`s in a boolean context. */ allowString?: boolean; }, ]; From ec5b8fa4f3129d26265c502562701e089ad89b95 Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Fri, 11 Oct 2024 11:29:57 -0400 Subject: [PATCH 6/8] Standardize correct/incorrect tabs --- .../rules/explicit-module-boundary-types.mdx | 24 +++++---- .../docs/rules/prefer-optional-chain.mdx | 49 +++++++++++-------- 2 files changed, 43 insertions(+), 30 deletions(-) diff --git a/packages/eslint-plugin/docs/rules/explicit-module-boundary-types.mdx b/packages/eslint-plugin/docs/rules/explicit-module-boundary-types.mdx index 4d0ad5865ecd..7837dd9d0fed 100644 --- a/packages/eslint-plugin/docs/rules/explicit-module-boundary-types.mdx +++ b/packages/eslint-plugin/docs/rules/explicit-module-boundary-types.mdx @@ -101,15 +101,17 @@ If you are working on a codebase within which you lint non-TypeScript code (i.e. When this option is `true`, the rule ignores arguments that are explicitly typed as any. +Examples of code for this rule with `{ allowArgumentsExplicitlyTypedAsAny: false }`: + - + ```ts option='{ "allowArgumentsExplicitlyTypedAsAny": false }' export const func = (value: any): number => value + 1; ``` - + ```ts option='{ "allowArgumentsExplicitlyTypedAsAny": true }' export const func = (value: any): number => value + 1; @@ -122,10 +124,10 @@ export const func = (value: any): number => value + 1; {/* insert option description */} -When this option is `true`, the rule ignores return type annotations on body-less arrow functions that return an `as const` type assertion. +Examples of code for this rule with `{ allowDirectConstAssertionInArrowFunctions: false }`: - + ```ts option='{ "allowDirectConstAssertionInArrowFunctions": false }' export const func = (value: number) => ({ type: 'X', value }); @@ -136,7 +138,7 @@ export const bar = () => 1; ``` - + ```ts option='{ "allowDirectConstAssertionInArrowFunctions": true }' export const func = (value: number) => ({ type: 'X', value }) as const; @@ -173,8 +175,10 @@ You may pass function/method names you would like this rule to ignore, like so: When this option is `true`, the rule ignores return type annotations on function, which is immediately returning another function expression. +Examples of code for this rule with `{ allowHigherOrderFunctions: false }`: + - + ```ts option='{ "allowHigherOrderFunctions": false }' export const arrowFn = () => () => {}; @@ -189,7 +193,7 @@ export function foo(outer: string) { ``` - + ```ts option='{ "allowHigherOrderFunctions": true }' export const arrowFn = () => (): void => {}; @@ -212,8 +216,10 @@ export function foo(outer: string) { When this option is `true`, the rule ignores type annotations on the variable of a function expression. +Examples of code for this rule with `{ allowTypedFunctionExpressions: false }`: + - + ```ts option='{ "allowTypedFunctionExpressions": false }' export let arrowFn = () => 'test'; @@ -230,7 +236,7 @@ export const foo = bar => {}; ``` - + ```ts option='{ "allowTypedFunctionExpressions": true }' type FuncType = () => string; diff --git a/packages/eslint-plugin/docs/rules/prefer-optional-chain.mdx b/packages/eslint-plugin/docs/rules/prefer-optional-chain.mdx index 396ce65fa9df..f1627d853cab 100644 --- a/packages/eslint-plugin/docs/rules/prefer-optional-chain.mdx +++ b/packages/eslint-plugin/docs/rules/prefer-optional-chain.mdx @@ -93,9 +93,10 @@ When this option is `false` unsafe cases will have suggestion fixers provided in {/* insert option description */} - +Examples of code for this rule with `{ checkAny: false }`: - + + ```ts option='{ "checkAny": true }' declare const thing: any; @@ -104,7 +105,7 @@ thing && thing.toString(); ``` - + ```ts option='{ "checkAny": false }' declare const thing: any; @@ -119,9 +120,10 @@ thing && thing.toString(); {/* insert option description */} - +Examples of code for this rule with `{ checkUnknown: false }`: - + + ```ts option='{ "checkUnknown": true }' declare const thing: unknown; @@ -130,7 +132,7 @@ thing && thing.toString(); ``` - + ```ts option='{ "checkUnknown": false }' declare const thing: unknown; @@ -145,9 +147,10 @@ thing && thing.toString(); {/* insert option description */} - +Examples of code for this rule with `{ checkString: false }`: - + + ```ts option='{ "checkString": true }' declare const thing: string; @@ -156,7 +159,7 @@ thing && thing.toString(); ``` - + ```ts option='{ "checkString": false }' declare const thing: string; @@ -171,9 +174,10 @@ thing && thing.toString(); {/* insert option description */} - +Examples of code for this rule with `{ checkNumber: false }`: - + + ```ts option='{ "checkNumber": true }' declare const thing: number; @@ -182,7 +186,7 @@ thing && thing.toString(); ``` - + ```ts option='{ "checkNumber": false }' declare const thing: number; @@ -211,9 +215,10 @@ The boolean expression narrows out the non-nullish falsy cases - so converting t ::: - +Examples of code for this rule with `{ checkBoolean: false }`: - + + ```ts option='{ "checkBoolean": true }' declare const thing: true; @@ -222,7 +227,7 @@ thing && thing.toString(); ``` - + ```ts option='{ "checkBoolean": false }' declare const thing: true; @@ -237,9 +242,10 @@ thing && thing.toString(); {/* insert option description */} - +Examples of code for this rule with `{ checkBigInt: false }`: - + + ```ts option='{ "checkBigInt": true }' declare const thing: bigint; @@ -248,7 +254,7 @@ thing && thing.toString(); ``` - + ```ts option='{ "checkBigInt": false }' declare const thing: bigint; @@ -263,9 +269,10 @@ thing && thing.toString(); {/* insert option description */} - +Examples of code for this rule with `{ requireNullish: false }`: - + + ```ts option='{ "requireNullish": true }' declare const thing1: string | null; @@ -273,7 +280,7 @@ thing1 && thing1.toString(); ``` - + ```ts option='{ "requireNullish": true }' declare const thing1: string | null; From c0ed7e32d3e36807fa4f2ce6a71edad481f5c0b8 Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Fri, 11 Oct 2024 11:33:20 -0400 Subject: [PATCH 7/8] Touch up some more unnecessary text --- .../docs/rules/explicit-module-boundary-types.mdx | 6 ------ packages/eslint-plugin/docs/rules/no-floating-promises.mdx | 2 +- 2 files changed, 1 insertion(+), 7 deletions(-) diff --git a/packages/eslint-plugin/docs/rules/explicit-module-boundary-types.mdx b/packages/eslint-plugin/docs/rules/explicit-module-boundary-types.mdx index 7837dd9d0fed..fadbfa296975 100644 --- a/packages/eslint-plugin/docs/rules/explicit-module-boundary-types.mdx +++ b/packages/eslint-plugin/docs/rules/explicit-module-boundary-types.mdx @@ -99,8 +99,6 @@ If you are working on a codebase within which you lint non-TypeScript code (i.e. {/* insert option description */} -When this option is `true`, the rule ignores arguments that are explicitly typed as any. - Examples of code for this rule with `{ allowArgumentsExplicitlyTypedAsAny: false }`: @@ -173,8 +171,6 @@ You may pass function/method names you would like this rule to ignore, like so: {/* insert option description */} -When this option is `true`, the rule ignores return type annotations on function, which is immediately returning another function expression. - Examples of code for this rule with `{ allowHigherOrderFunctions: false }`: @@ -214,8 +210,6 @@ export function foo(outer: string) { {/* insert option description */} -When this option is `true`, the rule ignores type annotations on the variable of a function expression. - Examples of code for this rule with `{ allowTypedFunctionExpressions: false }`: diff --git a/packages/eslint-plugin/docs/rules/no-floating-promises.mdx b/packages/eslint-plugin/docs/rules/no-floating-promises.mdx index 17f2a06b230b..12bf7465b537 100644 --- a/packages/eslint-plugin/docs/rules/no-floating-promises.mdx +++ b/packages/eslint-plugin/docs/rules/no-floating-promises.mdx @@ -155,7 +155,7 @@ void returnsPromise(); void Promise.reject('value'); ``` -When this option is set to `true`, and if you are using `no-void`, you should turn on the [`allowAsStatement`](https://eslint.org/docs/rules/no-void#allowasstatement) option. +When this option is set to `true`, if you are using `no-void`, you should turn on the [`allowAsStatement`](https://eslint.org/docs/rules/no-void#allowasstatement) option. ### `ignoreIIFE` From 693d24c98d47cefe3733fad1d63d085318995226 Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Fri, 11 Oct 2024 11:37:43 -0400 Subject: [PATCH 8/8] update test snapshots --- .../schema-snapshots/class-methods-use-this.shot | 14 +++++++------- .../schema-snapshots/no-restricted-types.shot | 16 ++++++++-------- 2 files changed, 15 insertions(+), 15 deletions(-) diff --git a/packages/eslint-plugin/tests/schema-snapshots/class-methods-use-this.shot b/packages/eslint-plugin/tests/schema-snapshots/class-methods-use-this.shot index ccecd0a0f6a9..fd93a8fc8c4f 100644 --- a/packages/eslint-plugin/tests/schema-snapshots/class-methods-use-this.shot +++ b/packages/eslint-plugin/tests/schema-snapshots/class-methods-use-this.shot @@ -10,18 +10,18 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos "properties": { "enforceForClassFields": { "default": true, - "description": "Enforces that functions used as instance field initializers utilize \`this\`", + "description": "Enforces that functions used as instance field initializers utilize \`this\`.", "type": "boolean" }, "exceptMethods": { - "description": "Allows specified method names to be ignored with this rule", + "description": "Allows specified method names to be ignored with this rule.", "items": { "type": "string" }, "type": "array" }, "ignoreClassesThatImplementAnInterface": { - "description": "Ignore classes that specifically implement some interface", + "description": "Makes the rule ignore class members that are defined within a class that \`implements\` a type", "oneOf": [ { "description": "Ignore all classes that implement an interface", @@ -48,13 +48,13 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos type Options = [ { - /** Enforces that functions used as instance field initializers utilize \`this\` */ + /** Enforces that functions used as instance field initializers utilize \`this\`. */ enforceForClassFields?: boolean; - /** Allows specified method names to be ignored with this rule */ + /** Allows specified method names to be ignored with this rule. */ exceptMethods?: string[]; - /** Ignore classes that specifically implement some interface */ + /** Makes the rule ignore class members that are defined within a class that \`implements\` a type */ ignoreClassesThatImplementAnInterface?: /** - * Ignore classes that specifically implement some interface + * Makes the rule ignore class members that are defined within a class that \`implements\` a type * Ignore all classes that implement an interface */ | boolean diff --git a/packages/eslint-plugin/tests/schema-snapshots/no-restricted-types.shot b/packages/eslint-plugin/tests/schema-snapshots/no-restricted-types.shot index 8dddf55f996b..bd7867ed79e8 100644 --- a/packages/eslint-plugin/tests/schema-snapshots/no-restricted-types.shot +++ b/packages/eslint-plugin/tests/schema-snapshots/no-restricted-types.shot @@ -10,24 +10,24 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos "banConfig": { "oneOf": [ { - "description": "Bans the type with the default message", + "description": "Bans the type with the default message.", "enum": [true], "type": "boolean" }, { - "description": "Bans the type with a custom message", + "description": "Bans the type with a custom message.", "type": "string" }, { "additionalProperties": false, - "description": "Bans a type", + "description": "Bans a type.", "properties": { "fixWith": { "description": "Type to autofix replace with. Note that autofixers can be applied automatically - so you need to be careful with this option.", "type": "string" }, "message": { - "description": "Custom error message", + "description": "Custom error message.", "type": "string" }, "suggest": { @@ -61,18 +61,18 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos # TYPES: type BanConfig = - /** Bans a type */ + /** Bans a type. */ | { /** Type to autofix replace with. Note that autofixers can be applied automatically - so you need to be careful with this option. */ fixWith?: string; - /** Custom error message */ + /** Custom error message. */ message?: string; /** Types to suggest replacing with. */ suggest?: string[]; } - /** Bans the type with a custom message */ + /** Bans the type with a custom message. */ | string - /** Bans the type with the default message */ + /** Bans the type with the default message. */ | true; type Options = [