From 7b7394792610a64e3be5c8da1b8a394ed0c65cbf Mon Sep 17 00:00:00 2001 From: oxc-bot <176400334+oxc-bot@users.noreply.github.com> Date: Wed, 6 Aug 2025 10:13:20 +0000 Subject: [PATCH] Release 1.10.0 --- .../guide/usage/linter/generated-config.md | 23 ++++ .../guide/usage/linter/generated-rules.md | 10 +- .../usage/linter/rules/eslint/max-params.md | 9 ++ .../usage/linter/rules/eslint/no-bitwise.md | 2 +- .../rules/eslint/no-irregular-whitespace.md | 26 ++-- .../linter/rules/eslint/no-unassigned-vars.md | 69 +++++++++++ .../linter/rules/eslint/no-useless-call.md | 4 +- .../usage/linter/rules/eslint/no-void.md | 6 +- .../rules/eslint/prefer-destructuring.md | 116 ++++++++++++++++++ .../linter/rules/jest/no-alias-methods.md | 2 +- .../linter/rules/jest/no-duplicate-hooks.md | 3 + .../linter/rules/jest/no-jasmine-globals.md | 24 +++- .../linter/rules/jest/no-mocks-import.md | 6 +- .../rules/jest/no-restricted-jest-methods.md | 6 + .../rules/jest/no-restricted-matchers.md | 8 ++ .../linter/rules/jest/no-standalone-expect.md | 7 ++ .../linter/rules/jest/prefer-called-with.md | 8 ++ .../rules/jest/prefer-comparison-matcher.md | 7 ++ .../rules/jest/prefer-equality-matcher.md | 8 ++ .../rules/jest/prefer-expect-resolves.md | 19 +-- .../linter/rules/jest/prefer-hooks-on-top.md | 8 ++ .../linter/rules/jest/prefer-jest-mocked.md | 8 ++ .../jest/prefer-mock-promise-shorthand.md | 8 ++ .../usage/linter/rules/jest/prefer-spy-on.md | 8 ++ .../linter/rules/jest/prefer-strict-equal.md | 7 ++ .../usage/linter/rules/jest/prefer-to-be.md | 18 ++- .../usage/linter/rules/jest/require-hook.md | 9 ++ .../rules/jest/require-to-throw-message.md | 8 ++ .../rules/jest/require-top-level-describe.md | 8 ++ .../usage/linter/rules/jsdoc/check-access.md | 6 +- .../usage/linter/rules/jsx_a11y/alt-text.md | 27 ++-- .../aria-activedescendant-has-tabindex.md | 7 ++ .../jsx_a11y/aria-unsupported-elements.md | 9 +- .../linter/rules/jsx_a11y/iframe-has-title.md | 10 +- .../rules/jsx_a11y/img-redundant-alt.md | 18 ++- .../linter/rules/jsx_a11y/no-autofocus.md | 11 +- .../rules/jsx_a11y/no-distracting-elements.md | 8 +- .../rules/nextjs/no-styled-jsx-in-document.md | 39 ++++++ .../usage/linter/rules/oxc/no-async-await.md | 7 ++ .../usage/linter/rules/oxc/no-barrel-file.md | 8 ++ .../linter/rules/oxc/no-optional-chaining.md | 9 ++ .../rules/oxc/no-rest-spread-properties.md | 8 ++ .../linter/rules/react/rules-of-hooks.md | 58 ++++++++- .../linter/rules/react/self-closing-comp.md | 14 ++- .../typescript/consistent-type-imports.md | 83 +++++++++++++ .../rules/typescript/prefer-function-type.md | 34 ++--- .../rules/unicorn/prefer-math-min-max.md | 12 +- .../guide/usage/linter/rules/version.data.js | 2 +- 48 files changed, 707 insertions(+), 108 deletions(-) create mode 100644 src/docs/guide/usage/linter/rules/eslint/no-unassigned-vars.md create mode 100644 src/docs/guide/usage/linter/rules/eslint/prefer-destructuring.md diff --git a/src/docs/guide/usage/linter/generated-config.md b/src/docs/guide/usage/linter/generated-config.md index 4ac942cee3..ae7048c364 100644 --- a/src/docs/guide/usage/linter/generated-config.md +++ b/src/docs/guide/usage/linter/generated-config.md @@ -275,6 +275,29 @@ See [eslint-plugin-jsx-a11y](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y#configurations)'s configuration for a full reference. +#### settings.jsx-a11y.attributes + +type: `Record` + +default: `{}` + +Map of attribute names to their DOM equivalents. +This is useful for non-React frameworks that use different attribute names. + +Example: + +```json +{ + "settings": { + "jsx-a11y": { + "attributes": { + "for": ["htmlFor", "for"] + } + } + } +} +``` + #### settings.jsx-a11y.components type: `Record` diff --git a/src/docs/guide/usage/linter/generated-rules.md b/src/docs/guide/usage/linter/generated-rules.md index d32b5c4cc6..71cd2f07c7 100644 --- a/src/docs/guide/usage/linter/generated-rules.md +++ b/src/docs/guide/usage/linter/generated-rules.md @@ -2,8 +2,8 @@ The progress of all rule implementations is tracked [here](https://github.com/oxc-project/oxc/issues/481). -- Total number of rules: 526 -- Rules turned on by default: 87 +- Total number of rules: 528 +- Rules turned on by default: 88 **Legend for 'Fixable?' column:** @@ -13,7 +13,7 @@ The progress of all rule implementations is tracked [here](https://github.com/ox - ⚠️💡: a dangerous suggestion is available for this rule - 🚧: an auto-fix or suggestion is possible, but currently not implemented -## Correctness (177): +## Correctness (178): Code that is outright wrong or useless. @@ -55,6 +55,7 @@ Code that is outright wrong or useless. | [no-shadow-restricted-names](/docs/guide/usage/linter/rules/eslint/no-shadow-restricted-names.html) | eslint | ✅ | | | [no-sparse-arrays](/docs/guide/usage/linter/rules/eslint/no-sparse-arrays.html) | eslint | ✅ | | | [no-this-before-super](/docs/guide/usage/linter/rules/eslint/no-this-before-super.html) | eslint | ✅ | | +| [no-unassigned-vars](/docs/guide/usage/linter/rules/eslint/no-unassigned-vars.html) | eslint | ✅ | | | [no-unsafe-finally](/docs/guide/usage/linter/rules/eslint/no-unsafe-finally.html) | eslint | ✅ | | | [no-unsafe-negation](/docs/guide/usage/linter/rules/eslint/no-unsafe-negation.html) | eslint | ✅ | 🛠️ | | [no-unsafe-optional-chaining](/docs/guide/usage/linter/rules/eslint/no-unsafe-optional-chaining.html) | eslint | ✅ | | @@ -418,7 +419,7 @@ Lints which are rather strict or have occasional false positives. | [prefer-type-error](/docs/guide/usage/linter/rules/unicorn/prefer-type-error.html) | unicorn | | 🛠️ | | [require-number-to-fixed-digits-argument](/docs/guide/usage/linter/rules/unicorn/require-number-to-fixed-digits-argument.html) | unicorn | | 🛠️ | -## Style (148): +## Style (149): Code that should be written in a more idiomatic way. @@ -452,6 +453,7 @@ Code that should be written in a more idiomatic way. | [no-template-curly-in-string](/docs/guide/usage/linter/rules/eslint/no-template-curly-in-string.html) | eslint | | ⚠️🛠️️ | | [no-ternary](/docs/guide/usage/linter/rules/eslint/no-ternary.html) | eslint | | | | [operator-assignment](/docs/guide/usage/linter/rules/eslint/operator-assignment.html) | eslint | | ⚠️🛠️️ | +| [prefer-destructuring](/docs/guide/usage/linter/rules/eslint/prefer-destructuring.html) | eslint | | 🚧 | | [prefer-exponentiation-operator](/docs/guide/usage/linter/rules/eslint/prefer-exponentiation-operator.html) | eslint | | | | [prefer-numeric-literals](/docs/guide/usage/linter/rules/eslint/prefer-numeric-literals.html) | eslint | | 🛠️ | | [prefer-object-has-own](/docs/guide/usage/linter/rules/eslint/prefer-object-has-own.html) | eslint | | 🛠️ | diff --git a/src/docs/guide/usage/linter/rules/eslint/max-params.md b/src/docs/guide/usage/linter/rules/eslint/max-params.md index a407540021..f703fdd0da 100644 --- a/src/docs/guide/usage/linter/rules/eslint/max-params.md +++ b/src/docs/guide/usage/linter/rules/eslint/max-params.md @@ -64,6 +64,15 @@ This option is for changing the maximum allowed number of function parameters. For example `{ "max": 4 }` would mean that having a function take four parameters is allowed which overrides the default of three. +### countVoidThis + +`{ "countVoidThis": boolean }` + +This option is for counting the `this` parameter if it is of type `void`. + +For example `{ "countVoidThis": true }` would mean that having a function +take a `this` parameter of type `void` is counted towards the maximum number of parameters. + ## How to use To **enable** this rule in the CLI or using the config file, you can use: diff --git a/src/docs/guide/usage/linter/rules/eslint/no-bitwise.md b/src/docs/guide/usage/linter/rules/eslint/no-bitwise.md index b06630a8e5..2c95f6ea95 100644 --- a/src/docs/guide/usage/linter/rules/eslint/no-bitwise.md +++ b/src/docs/guide/usage/linter/rules/eslint/no-bitwise.md @@ -55,7 +55,7 @@ var x = y > z; `{ type: string[], default: [] }` -The`allow` option permits the given list of bitwise operators to be used +The `allow` option permits the given list of bitwise operators to be used as exceptions to this rule. For example `{ "allow": ["~"] }` would allow the use of the bitwise operator diff --git a/src/docs/guide/usage/linter/rules/eslint/no-irregular-whitespace.md b/src/docs/guide/usage/linter/rules/eslint/no-irregular-whitespace.md index 2b82f07a00..181482070c 100644 --- a/src/docs/guide/usage/linter/rules/eslint/no-irregular-whitespace.md +++ b/src/docs/guide/usage/linter/rules/eslint/no-irregular-whitespace.md @@ -15,30 +15,32 @@ const source = `https://github.com/oxc-project/oxc/blob/${ data }/crates/oxc_lin ### What it does -Disallows the use of irregular whitespaces in the code. +Disallows the use of irregular whitespace characters in the code. -### Why is this bad +### Why is this bad? -The use of irregular whitespaces can hinder code readability and -create inconsistencies, making maintenance and collaboration more challenging. +Irregular whitespace characters are invisible to most editors and can +cause unexpected behavior, making code harder to debug and maintain. +They can also cause issues with code formatting and parsing. ### Examples Examples of **incorrect** code for this rule: ```javascript -function invalidExample() { - return 42; +// Contains irregular whitespace characters (invisible) +function example() { + var foo = "bar"; // irregular whitespace before 'bar' } ``` -Examples of **incorrect** code for this rule: +Examples of **correct** code for this rule: -```javascript -function invalidExample() { - return 42; +````javascript +function example() { + var foo = 'bar'; // regular spaces only } -``` + ## How to use @@ -48,7 +50,7 @@ To **enable** this rule in the CLI or using the config file, you can use: ```bash [CLI] oxlint --deny no-irregular-whitespace -``` +```` ```json [Config (.oxlintrc.json)] { diff --git a/src/docs/guide/usage/linter/rules/eslint/no-unassigned-vars.md b/src/docs/guide/usage/linter/rules/eslint/no-unassigned-vars.md new file mode 100644 index 0000000000..8842adf87b --- /dev/null +++ b/src/docs/guide/usage/linter/rules/eslint/no-unassigned-vars.md @@ -0,0 +1,69 @@ + + + + +# eslint/no-unassigned-vars + +
+ +✅ This rule is turned on by default. + +
+ +### What it does + +Disallow let or var variables that are read but never assigned + +### Why is this bad? + +This rule flags let or var declarations that are never assigned a value but are still read or used in the code. +Since these variables will always be undefined, their usage is likely a programming mistake. + +### Examples + +Examples of **incorrect** code for this rule: + +```js +let status; +if (status === "ready") { + console.log("Ready!"); +} +``` + +Examples of **correct** code for this rule: + +```js +let message = "hello"; +console.log(message); + +let user; +user = getUser(); +console.log(user.name); +``` + +## How to use + +To **enable** this rule in the CLI or using the config file, you can use: + +::: code-group + +```bash [CLI] +oxlint --deny no-unassigned-vars +``` + +```json [Config (.oxlintrc.json)] +{ + "rules": { + "no-unassigned-vars": "error" + } +} +``` + +::: + +## References + +- Rule Source diff --git a/src/docs/guide/usage/linter/rules/eslint/no-useless-call.md b/src/docs/guide/usage/linter/rules/eslint/no-useless-call.md index 9407609201..5d1cb97575 100644 --- a/src/docs/guide/usage/linter/rules/eslint/no-useless-call.md +++ b/src/docs/guide/usage/linter/rules/eslint/no-useless-call.md @@ -26,13 +26,13 @@ So if the code about thisArg is a dynamic expression, this rule cannot judge cor Examples of **incorrect** code for this rule: ```js -// These are same as `foo(1, 2, 3);` +// These are the same as `foo(1, 2, 3);` foo.call(undefined, 1, 2, 3); foo.apply(undefined, [1, 2, 3]); foo.call(null, 1, 2, 3); foo.apply(null, [1, 2, 3]); -// These are same as `obj.foo(1, 2, 3);` +// These are the same as `obj.foo(1, 2, 3);` obj.foo.call(obj, 1, 2, 3); obj.foo.apply(obj, [1, 2, 3]); ``` diff --git a/src/docs/guide/usage/linter/rules/eslint/no-void.md b/src/docs/guide/usage/linter/rules/eslint/no-void.md index 479ee89281..44b244ce76 100644 --- a/src/docs/guide/usage/linter/rules/eslint/no-void.md +++ b/src/docs/guide/usage/linter/rules/eslint/no-void.md @@ -17,10 +17,10 @@ const source = `https://github.com/oxc-project/oxc/blob/${ data }/crates/oxc_lin Disallows the use of the `void` operator. -Why is this bad +### Why is this bad? -The `void` operator is often used to get `undefined`, -but this is unnecessary because `undefined` can be used directly instead. +The `void` operator is often used to get `undefined`, but this is +unnecessary because `undefined` can be used directly instead. ### Examples diff --git a/src/docs/guide/usage/linter/rules/eslint/prefer-destructuring.md b/src/docs/guide/usage/linter/rules/eslint/prefer-destructuring.md new file mode 100644 index 0000000000..73746986c1 --- /dev/null +++ b/src/docs/guide/usage/linter/rules/eslint/prefer-destructuring.md @@ -0,0 +1,116 @@ + + + + +# eslint/prefer-destructuring + +
+ +🚧 An auto-fix is still under development. + +
+ +### What it does + +Require destructuring from arrays and/or objects + +### Why is this bad? + +With JavaScript ES6, a new syntax was added for creating variables from an array index or object property, +called destructuring. This rule enforces usage of destructuring +instead of accessing a property through a member expression. + +### Examples + +Examples of **incorrect** code for this rule: + +```js +// With `array` enabled +const foo = array[0]; +bar.baz = array[0]; +// With `object` enabled +const qux = object.qux; +const quux = object["quux"]; +``` + +Examples of **correct** code for this rule: + +```js +// With `array` enabled +const [foo] = array; +const arr = array[someIndex]; +[bar.baz] = array; + +// With `object` enabled +const { baz } = object; +const obj = object.bar; +``` + +### Options + +This rule takes two arguments, both of which are objects. +The first object parameter determines what types of destructuring the rule applies to. +In the first object, there are two properties, array and object, +that can be used to turn on or off the destructuring requirement for each of those types independently. +By default, both are true. + +```json +{ + "prefer-destructuring": ["error", { "array": true, "object": true }] +} +``` + +Alternatively, you can use separate configurations for different assignment types. +The first argument accepts two other keys instead of array and object. +One key is VariableDeclarator and the other is AssignmentExpression, +which can be used to control the destructuring requirement for each of those types independently + +```json +{ + "prefer-destructuring": [ + "error", + { + "VariableDeclarator": { "array": true, "object": true }, + "AssignmentExpression": { "array": true, "object": true } + } + ] +} +``` + +#### enforceForRenamedProperties + +The rule has a second object argument with a single key, +enforceForRenamedProperties, which determines whether the object destructuring applies to renamed variables. + +```json +{ + "prefer-destructuring": ["error", { "array": true, "object": true }, { "enforceForRenamedProperties": true }] +} +``` + +## How to use + +To **enable** this rule in the CLI or using the config file, you can use: + +::: code-group + +```bash [CLI] +oxlint --deny prefer-destructuring +``` + +```json [Config (.oxlintrc.json)] +{ + "rules": { + "prefer-destructuring": "error" + } +} +``` + +::: + +## References + +- Rule Source diff --git a/src/docs/guide/usage/linter/rules/jest/no-alias-methods.md b/src/docs/guide/usage/linter/rules/jest/no-alias-methods.md index 15cf33ea71..954f55b133 100644 --- a/src/docs/guide/usage/linter/rules/jest/no-alias-methods.md +++ b/src/docs/guide/usage/linter/rules/jest/no-alias-methods.md @@ -20,7 +20,7 @@ This rule ensures that only the canonical name as used in the Jest documentation ### Why is this bad? These aliases are going to be removed in the next major version of Jest - see [jestjs/jest#13164](https://github.com/jestjs/jest/issues/13164) for more. -This rule will makes it easier to search for all occurrences of the method within code, and it ensures consistency among the method names used. +This rule will make it easier to search for all occurrences of the method within code, and it ensures consistency among the method names used. ### Examples diff --git a/src/docs/guide/usage/linter/rules/jest/no-duplicate-hooks.md b/src/docs/guide/usage/linter/rules/jest/no-duplicate-hooks.md index 11062dab65..2b104085ef 100644 --- a/src/docs/guide/usage/linter/rules/jest/no-duplicate-hooks.md +++ b/src/docs/guide/usage/linter/rules/jest/no-duplicate-hooks.md @@ -17,6 +17,9 @@ Disallows duplicate hooks in describe blocks. ### Why is this bad? Having duplicate hooks in a describe block can lead to confusion and unexpected behavior. +When multiple hooks of the same type exist, they all execute in order, which can make it +difficult to understand the test setup flow and may result in redundant or conflicting +operations. This makes tests harder to maintain and debug. ### Examples diff --git a/src/docs/guide/usage/linter/rules/jest/no-jasmine-globals.md b/src/docs/guide/usage/linter/rules/jest/no-jasmine-globals.md index 0d7fa057c4..c81b0890fa 100644 --- a/src/docs/guide/usage/linter/rules/jest/no-jasmine-globals.md +++ b/src/docs/guide/usage/linter/rules/jest/no-jasmine-globals.md @@ -15,7 +15,14 @@ const source = `https://github.com/oxc-project/oxc/blob/${ data }/crates/oxc_lin ### What it does -This rule reports on any usage of Jasmine globals, which is not ported to Jest, and suggests alternatives from Jest's own API. +This rule reports on any usage of Jasmine globals, which is not ported to +Jest, and suggests alternatives from Jest's own API. + +### Why is this bad? + +When migrating from Jasmine to Jest, relying on Jasmine-specific globals +creates compatibility issues and prevents taking advantage of Jest's +improved testing features and better error reporting. ### Examples @@ -31,6 +38,21 @@ test("my test", () => { }); ``` +Examples of **correct** code for this rule: + +```javascript +jest.setTimeout(5000); +test("my test", () => { + // Use test.skip() instead of pending() +}); +test.skip("my test", () => { + // Skipped test +}); +test("my test", () => { + jest.fn(); // Use jest.fn() instead of jasmine.createSpy() +}); +``` + ## How to use To **enable** this rule in the CLI or using the config file, you can use: diff --git a/src/docs/guide/usage/linter/rules/jest/no-mocks-import.md b/src/docs/guide/usage/linter/rules/jest/no-mocks-import.md index 448c0d9f30..53b405800a 100644 --- a/src/docs/guide/usage/linter/rules/jest/no-mocks-import.md +++ b/src/docs/guide/usage/linter/rules/jest/no-mocks-import.md @@ -16,7 +16,11 @@ This rule reports imports from a path containing a **mocks** component. ### Why is this bad? -Manually importing mocks from a `__mocks__` directory can lead to unexpected behavior. +Manually importing mocks from a `__mocks__` directory can lead to unexpected behavior +and breaks Jest's automatic mocking system. Jest is designed to automatically resolve +and use mocks from `__mocks__` directories when `jest.mock()` is called. Directly +importing from these directories bypasses Jest's module resolution system and can cause +inconsistencies between test and production environments. ### Examples diff --git a/src/docs/guide/usage/linter/rules/jest/no-restricted-jest-methods.md b/src/docs/guide/usage/linter/rules/jest/no-restricted-jest-methods.md index b8dbda8347..7cbaec0d76 100644 --- a/src/docs/guide/usage/linter/rules/jest/no-restricted-jest-methods.md +++ b/src/docs/guide/usage/linter/rules/jest/no-restricted-jest-methods.md @@ -14,6 +14,12 @@ const source = `https://github.com/oxc-project/oxc/blob/${ data }/crates/oxc_lin Restrict the use of specific `jest` and `vi` methods. +### Why is this bad? + +Certain Jest methods may be deprecated, discouraged in specific +contexts, or incompatible with your testing environment. Restricting +them helps maintain consistent and reliable test practices. + ### Examples Examples of **incorrect** code for this rule: diff --git a/src/docs/guide/usage/linter/rules/jest/no-restricted-matchers.md b/src/docs/guide/usage/linter/rules/jest/no-restricted-matchers.md index 05ae31c28e..bebb14e218 100644 --- a/src/docs/guide/usage/linter/rules/jest/no-restricted-matchers.md +++ b/src/docs/guide/usage/linter/rules/jest/no-restricted-matchers.md @@ -14,6 +14,14 @@ const source = `https://github.com/oxc-project/oxc/blob/${ data }/crates/oxc_lin Ban specific matchers & modifiers from being used, and can suggest alternatives. +### Why is this bad? + +Some matchers or modifiers might be discouraged in your codebase for various reasons: +they might be deprecated, cause confusion, have performance implications, or there +might be better alternatives available. This rule allows you to enforce consistent +testing patterns by restricting certain Jest matchers and providing guidance on +preferred alternatives. + ### Examples Bans are expressed in the form of a map, with the value being either a string message to be shown, diff --git a/src/docs/guide/usage/linter/rules/jest/no-standalone-expect.md b/src/docs/guide/usage/linter/rules/jest/no-standalone-expect.md index d4f48d6377..0e9119175f 100644 --- a/src/docs/guide/usage/linter/rules/jest/no-standalone-expect.md +++ b/src/docs/guide/usage/linter/rules/jest/no-standalone-expect.md @@ -19,6 +19,13 @@ trigger this rule. Statements like `expect.hasAssertions()` will NOT trigger this rule since these calls will execute if they are not in a test block. +### Why is this bad? + +`expect` statements outside of test blocks will not be executed by the Jest +test runner, which means they won't actually test anything. This can lead to +false confidence in test coverage and may hide bugs that would otherwise be +caught by proper testing. + ### Examples Examples of **incorrect** code for this rule: diff --git a/src/docs/guide/usage/linter/rules/jest/prefer-called-with.md b/src/docs/guide/usage/linter/rules/jest/prefer-called-with.md index 8fdd673904..5c8297b3b9 100644 --- a/src/docs/guide/usage/linter/rules/jest/prefer-called-with.md +++ b/src/docs/guide/usage/linter/rules/jest/prefer-called-with.md @@ -14,6 +14,14 @@ const source = `https://github.com/oxc-project/oxc/blob/${ data }/crates/oxc_lin Suggest using `toBeCalledWith()` or `toHaveBeenCalledWith()` +### Why is this bad? + +When testing function calls, it's often more valuable to assert both +that a function was called AND what arguments it was called with. +Using `toBeCalled()` or `toHaveBeenCalled()` only verifies the function +was invoked, but doesn't validate the arguments, potentially missing +bugs where functions are called with incorrect parameters. + ### Examples Examples of **incorrect** code for this rule: diff --git a/src/docs/guide/usage/linter/rules/jest/prefer-comparison-matcher.md b/src/docs/guide/usage/linter/rules/jest/prefer-comparison-matcher.md index f0de5f7da6..73a64581ff 100644 --- a/src/docs/guide/usage/linter/rules/jest/prefer-comparison-matcher.md +++ b/src/docs/guide/usage/linter/rules/jest/prefer-comparison-matcher.md @@ -23,6 +23,13 @@ following built-in comparison matchers: - `toBeLessThan` - `toBeLessThanOrEqual` +### Why is this bad? + +Using generic matchers like `toBe(true)` with comparison expressions +makes tests less readable and provides less helpful error messages when +they fail. Jest's specific comparison matchers offer clearer intent and +better error output that shows the actual values being compared. + ### Examples Examples of **incorrect** code for this rule: diff --git a/src/docs/guide/usage/linter/rules/jest/prefer-equality-matcher.md b/src/docs/guide/usage/linter/rules/jest/prefer-equality-matcher.md index b87948c721..90ad870d2b 100644 --- a/src/docs/guide/usage/linter/rules/jest/prefer-equality-matcher.md +++ b/src/docs/guide/usage/linter/rules/jest/prefer-equality-matcher.md @@ -15,6 +15,14 @@ const source = `https://github.com/oxc-project/oxc/blob/${ data }/crates/oxc_lin Jest has built-in matchers for expecting equality, which allow for more readable tests and error messages if an expectation fails. +### Why is this bad? + +Testing equality expressions with generic matchers like `toBe(true)` +makes tests harder to read and understand. When tests fail, the error +messages are less helpful because they don't show what the actual values +were. Using specific equality matchers provides clearer test intent and +better debugging information. + ### Examples Examples of **incorrect** code for this rule: diff --git a/src/docs/guide/usage/linter/rules/jest/prefer-expect-resolves.md b/src/docs/guide/usage/linter/rules/jest/prefer-expect-resolves.md index 63b73d5f6a..77cd146a25 100644 --- a/src/docs/guide/usage/linter/rules/jest/prefer-expect-resolves.md +++ b/src/docs/guide/usage/linter/rules/jest/prefer-expect-resolves.md @@ -15,20 +15,25 @@ const source = `https://github.com/oxc-project/oxc/blob/${ data }/crates/oxc_lin ### What it does -When working with promises, there are two primary ways you can test the resolved -value: +Prefer `await expect(...).resolves` over `expect(await ...)` when testing +promises. + +### Why is this bad? + +When working with promises, there are two primary ways you can test the +resolved value: 1. use the `resolve` modifier on `expect` (`await expect(...).resolves.` style) 2. `await` the promise and assert against its result (`expect(await ...).` style) -While the second style is arguably less dependent on `jest`, if the promise -rejects it will be treated as a general error, resulting in less predictable -behaviour and output from `jest`. +While the second style is arguably less dependent on `jest`, if the +promise rejects it will be treated as a general error, resulting in less +predictable behaviour and output from `jest`. -Additionally, favoring the first style ensures consistency with its `rejects` -counterpart, as there is no way of "awaiting" a rejection. +Additionally, favoring the first style ensures consistency with its +`rejects` counterpart, as there is no way of "awaiting" a rejection. ### Examples diff --git a/src/docs/guide/usage/linter/rules/jest/prefer-hooks-on-top.md b/src/docs/guide/usage/linter/rules/jest/prefer-hooks-on-top.md index f4e01ac91b..be962501d4 100644 --- a/src/docs/guide/usage/linter/rules/jest/prefer-hooks-on-top.md +++ b/src/docs/guide/usage/linter/rules/jest/prefer-hooks-on-top.md @@ -16,6 +16,14 @@ While hooks can be setup anywhere in a test file, they are always called in a specific order, which means it can be confusing if they're intermixed with test cases. +### Why is this bad? + +When hooks are mixed with test cases, it becomes harder to understand +the test setup and execution order. This can lead to confusion about +which hooks apply to which tests and when they run. Grouping hooks at +the top of each `describe` block makes the test structure clearer and +more maintainable. + ### Examples Examples of **incorrect** code for this rule: diff --git a/src/docs/guide/usage/linter/rules/jest/prefer-jest-mocked.md b/src/docs/guide/usage/linter/rules/jest/prefer-jest-mocked.md index ad2b2f2099..0b3d0fd2d5 100644 --- a/src/docs/guide/usage/linter/rules/jest/prefer-jest-mocked.md +++ b/src/docs/guide/usage/linter/rules/jest/prefer-jest-mocked.md @@ -26,6 +26,14 @@ Restricted types: - `jest.MockedClass` - `jest.MockedObject` +### Why is this bad? + +Using type assertions like `fn as jest.Mock` is a less safe approach +than using `jest.mocked()`. The `jest.mocked()` helper provides better +type safety by preserving the original function signature while adding +mock capabilities. It also makes the code more readable and explicit +about mocking intentions. + ### Examples Examples of **incorrect** code for this rule: diff --git a/src/docs/guide/usage/linter/rules/jest/prefer-mock-promise-shorthand.md b/src/docs/guide/usage/linter/rules/jest/prefer-mock-promise-shorthand.md index b287d02c0c..4a63e73968 100644 --- a/src/docs/guide/usage/linter/rules/jest/prefer-mock-promise-shorthand.md +++ b/src/docs/guide/usage/linter/rules/jest/prefer-mock-promise-shorthand.md @@ -19,6 +19,14 @@ When working with mocks of functions that return promises, Jest provides some API sugar functions to reduce the amount of boilerplate you have to write. These methods should be preferred when possible. +### Why is this bad? + +Using generic mock functions like `mockImplementation(() => Promise.resolve())` +or `mockReturnValue(Promise.reject())` is more verbose and less readable than +Jest's specialized promise shorthands. The shorthand methods like +`mockResolvedValue()` and `mockRejectedValue()` are more expressive and +make the test intent clearer. + ### Examples Examples of **incorrect** code for this rule: diff --git a/src/docs/guide/usage/linter/rules/jest/prefer-spy-on.md b/src/docs/guide/usage/linter/rules/jest/prefer-spy-on.md index 796866bf0a..ffb9a01caf 100644 --- a/src/docs/guide/usage/linter/rules/jest/prefer-spy-on.md +++ b/src/docs/guide/usage/linter/rules/jest/prefer-spy-on.md @@ -26,6 +26,14 @@ function. The original function can be overwritten with `mockFn.mockImplementation()` or by some of the [other mock functions](https://jestjs.io/docs/en/mock-function-api). +### Why is this bad? + +Directly overwriting properties with mock functions can lead to cleanup issues +and test isolation problems. When you manually assign a mock to a property, +you're responsible for restoring the original implementation, which is easy to +forget and can cause tests to interfere with each other. Using `jest.spyOn()` +provides automatic cleanup capabilities and makes your tests more reliable. + ### Examples Examples of **incorrect** code for this rule: diff --git a/src/docs/guide/usage/linter/rules/jest/prefer-strict-equal.md b/src/docs/guide/usage/linter/rules/jest/prefer-strict-equal.md index 0297c313dc..d438ae865c 100644 --- a/src/docs/guide/usage/linter/rules/jest/prefer-strict-equal.md +++ b/src/docs/guide/usage/linter/rules/jest/prefer-strict-equal.md @@ -17,6 +17,13 @@ const source = `https://github.com/oxc-project/oxc/blob/${ data }/crates/oxc_lin This rule triggers a warning if `toEqual()` is used to assert equality. +### Why is this bad? + +The `toEqual()` matcher performs a deep equality check but ignores +`undefined` values in objects and arrays. This can lead to false +positives where tests pass when they should fail. `toStrictEqual()` +provides more accurate comparison by checking for `undefined` values. + ### Examples Examples of **incorrect** code for this rule: diff --git a/src/docs/guide/usage/linter/rules/jest/prefer-to-be.md b/src/docs/guide/usage/linter/rules/jest/prefer-to-be.md index 10a66da1d4..ecdf5649f0 100644 --- a/src/docs/guide/usage/linter/rules/jest/prefer-to-be.md +++ b/src/docs/guide/usage/linter/rules/jest/prefer-to-be.md @@ -15,13 +15,19 @@ const source = `https://github.com/oxc-project/oxc/blob/${ data }/crates/oxc_lin ### What it does -When asserting against primitive literals such as numbers and strings, the -equality matchers all operate the same, but read slightly differently in code. +Recommends using `toBe` matcher for primitive literals and specific +matchers for `null`, `undefined`, and `NaN`. -This rule recommends using the `toBe` matcher in these situations, as it forms -the most grammatically natural sentence. For `null`, `undefined`, and `NaN` this -rule recommends using their specific `toBe` matchers, as they give better error -messages as well. +### Why is this bad? + +When asserting against primitive literals such as numbers and strings, +the equality matchers all operate the same, but read slightly +differently in code. + +This rule recommends using the `toBe` matcher in these situations, as +it forms the most grammatically natural sentence. For `null`, +`undefined`, and `NaN` this rule recommends using their specific `toBe` +matchers, as they give better error messages as well. ### Examples diff --git a/src/docs/guide/usage/linter/rules/jest/require-hook.md b/src/docs/guide/usage/linter/rules/jest/require-hook.md index 9610363767..aeaf21fc59 100644 --- a/src/docs/guide/usage/linter/rules/jest/require-hook.md +++ b/src/docs/guide/usage/linter/rules/jest/require-hook.md @@ -22,6 +22,15 @@ directly within the body of a `describe`, _except_ for the following: - Types - Calls to the standard Jest globals +### Why is this bad? + +Having setup and teardown code outside of hooks can lead to unpredictable test +behavior. Code that runs at the top level executes when the test file is loaded, +not when tests run, which can cause issues with test isolation and make tests +dependent on execution order. Using proper hooks like `beforeEach`, `beforeAll`, +`afterEach`, and `afterAll` ensures that setup and teardown code runs at the +correct time and maintains test isolation. + ### Examples Examples of **incorrect** code for this rule: diff --git a/src/docs/guide/usage/linter/rules/jest/require-to-throw-message.md b/src/docs/guide/usage/linter/rules/jest/require-to-throw-message.md index 1ddd6243c2..b463022dc5 100644 --- a/src/docs/guide/usage/linter/rules/jest/require-to-throw-message.md +++ b/src/docs/guide/usage/linter/rules/jest/require-to-throw-message.md @@ -14,6 +14,14 @@ const source = `https://github.com/oxc-project/oxc/blob/${ data }/crates/oxc_lin This rule triggers a warning if `toThrow()` or `toThrowError()` is used without an error message. +### Why is this bad? + +Using `toThrow()` or `toThrowError()` without specifying an expected error message +makes tests less specific and harder to debug. When a test only checks that an +error was thrown but not what kind of error, it can pass even when the wrong +error is thrown, potentially hiding bugs. Providing an expected error message +or error type makes tests more precise and helps catch regressions more effectively. + ### Examples Examples of **incorrect** code for this rule: diff --git a/src/docs/guide/usage/linter/rules/jest/require-top-level-describe.md b/src/docs/guide/usage/linter/rules/jest/require-top-level-describe.md index 984aa56698..72fb20bd6e 100644 --- a/src/docs/guide/usage/linter/rules/jest/require-top-level-describe.md +++ b/src/docs/guide/usage/linter/rules/jest/require-top-level-describe.md @@ -12,6 +12,14 @@ const source = `https://github.com/oxc-project/oxc/blob/${ data }/crates/oxc_lin ### What it does +Requires test cases and hooks to be inside a top-level `describe` block. + +### Why is this bad? + +Having tests and hooks organized within `describe` blocks provides better +structure and grouping for test suites. It makes test output more readable +and helps with test organization, especially in larger codebases. + This rule triggers a warning if a test case (`test` and `it`) or a hook (`beforeAll`, `beforeEach`, `afterEach`, `afterAll`) is not located in a top-level `describe` block. diff --git a/src/docs/guide/usage/linter/rules/jsdoc/check-access.md b/src/docs/guide/usage/linter/rules/jsdoc/check-access.md index 53f164488a..aa6464378c 100644 --- a/src/docs/guide/usage/linter/rules/jsdoc/check-access.md +++ b/src/docs/guide/usage/linter/rules/jsdoc/check-access.md @@ -23,7 +23,11 @@ Also reports: ### Why is this bad? -It is important to have a consistent way of specifying access levels. +It is important to have a consistent way of specifying access levels in JSDoc +comments. Using invalid or multiple access level tags creates confusion about +the intended visibility of documented elements and can lead to inconsistencies +in API documentation generation. Mixing different access tags or using invalid +values makes the documentation unclear and potentially misleading. ### Examples diff --git a/src/docs/guide/usage/linter/rules/jsx_a11y/alt-text.md b/src/docs/guide/usage/linter/rules/jsx_a11y/alt-text.md index d9a2b0f9e1..8cc0615c07 100644 --- a/src/docs/guide/usage/linter/rules/jsx_a11y/alt-text.md +++ b/src/docs/guide/usage/linter/rules/jsx_a11y/alt-text.md @@ -15,34 +15,31 @@ const source = `https://github.com/oxc-project/oxc/blob/${ data }/crates/oxc_lin Enforce that all elements that require alternative text have meaningful information to relay back to the end user. -### Why is this necessary? +### Why is this bad? Alternative text is a critical component of accessibility for screen -reader users, enabling them to understand the content and function -of an element. - -### What it checks - -This rule checks for alternative text on the following elements: -``, ``, ``, and ``. - -### How to fix it - -Ensure that the `alt` attribute is present and contains meaningful -text that describes the element's content or purpose. +reader users, enabling them to understand the content and function of +an element. Missing or inadequate alt text makes content inaccessible +to users who rely on assistive technologies. ### Examples Examples of **incorrect** code for this rule: ```jsx -A close-up of a white daisy; + + + + ``` Examples of **correct** code for this rule: ```jsx -; +A close-up of a white daisy + + +Navigation link ``` ## How to use diff --git a/src/docs/guide/usage/linter/rules/jsx_a11y/aria-activedescendant-has-tabindex.md b/src/docs/guide/usage/linter/rules/jsx_a11y/aria-activedescendant-has-tabindex.md index 3f8d969d52..8974a34d00 100644 --- a/src/docs/guide/usage/linter/rules/jsx_a11y/aria-activedescendant-has-tabindex.md +++ b/src/docs/guide/usage/linter/rules/jsx_a11y/aria-activedescendant-has-tabindex.md @@ -14,6 +14,13 @@ const source = `https://github.com/oxc-project/oxc/blob/${ data }/crates/oxc_lin Enforce elements with aria-activedescendant are tabbable. +### Why is this bad? + +Elements with `aria-activedescendant` must be tabbable for users to +navigate to them using keyboard input. Without proper tabindex, screen +reader users cannot access the element through keyboard navigation, +making the functionality inaccessible. + ### Examples Examples of **incorrect** code for this rule: diff --git a/src/docs/guide/usage/linter/rules/jsx_a11y/aria-unsupported-elements.md b/src/docs/guide/usage/linter/rules/jsx_a11y/aria-unsupported-elements.md index efe3aa0a02..9b2cd31d80 100644 --- a/src/docs/guide/usage/linter/rules/jsx_a11y/aria-unsupported-elements.md +++ b/src/docs/guide/usage/linter/rules/jsx_a11y/aria-unsupported-elements.md @@ -15,10 +15,15 @@ const source = `https://github.com/oxc-project/oxc/blob/${ data }/crates/oxc_lin ### What it does +Enforces that reserved DOM elements do not contain ARIA roles, states, +or properties. + +### Why is this bad? + Certain reserved DOM elements do not support ARIA roles, states and properties. This is often because they are not visible, for example -`meta`, `html`, `script`, `style`. This rule enforces that these DOM -elements do not contain the `role` and/or `aria-*` props. +`meta`, `html`, `script`, `style`. Adding ARIA attributes to these +elements is meaningless and can create confusion for screen readers. ### Examples diff --git a/src/docs/guide/usage/linter/rules/jsx_a11y/iframe-has-title.md b/src/docs/guide/usage/linter/rules/jsx_a11y/iframe-has-title.md index fd8231bf10..f9025965b8 100644 --- a/src/docs/guide/usage/linter/rules/jsx_a11y/iframe-has-title.md +++ b/src/docs/guide/usage/linter/rules/jsx_a11y/iframe-has-title.md @@ -16,12 +16,10 @@ Enforce iframe elements have a title attribute. ### Why is this bad? -Screen reader users rely on a iframe title to describe the contents of the iframe. -Navigating through iframe and iframe elements quickly becomes difficult and confusing for users of this technology if the markup does not contain a title attribute. - -### What it checks - -This rule checks for title property on iframe element. +Screen reader users rely on a iframe title to describe the contents of +the iframe. Navigating through iframe and iframe elements quickly +becomes difficult and confusing for users of this technology if the +markup does not contain a title attribute. ### Examples diff --git a/src/docs/guide/usage/linter/rules/jsx_a11y/img-redundant-alt.md b/src/docs/guide/usage/linter/rules/jsx_a11y/img-redundant-alt.md index 0873fc759b..80988222ad 100644 --- a/src/docs/guide/usage/linter/rules/jsx_a11y/img-redundant-alt.md +++ b/src/docs/guide/usage/linter/rules/jsx_a11y/img-redundant-alt.md @@ -12,19 +12,15 @@ const source = `https://github.com/oxc-project/oxc/blob/${ data }/crates/oxc_lin ### What it does -Enforce img alt attribute does not contain the word image, picture, or photo. Screenreaders already announce img elements as an image. -There is no need to use words such as image, photo, and/or picture. +Enforce that `img` alt attributes do not contain redundant words like +"image", "picture", or "photo". -### Why is this necessary? +### Why is this bad? -Alternative text is a critical component of accessibility for screen -reader users, enabling them to understand the content and function -of an element. - -### What it checks - -This rule checks for alternative text on the following elements: -`` and the components which you define in options.components with the exception of components which is hidden from screen reader. +Screen readers already announce `img` elements as an image, so there is +no need to use words such as "image", "photo", or "picture" in the alt +text. This creates redundant information for users of assistive +technologies and makes the alt text less concise and useful. ### Examples diff --git a/src/docs/guide/usage/linter/rules/jsx_a11y/no-autofocus.md b/src/docs/guide/usage/linter/rules/jsx_a11y/no-autofocus.md index fa6c25d94a..608b1293f1 100644 --- a/src/docs/guide/usage/linter/rules/jsx_a11y/no-autofocus.md +++ b/src/docs/guide/usage/linter/rules/jsx_a11y/no-autofocus.md @@ -15,9 +15,14 @@ const source = `https://github.com/oxc-project/oxc/blob/${ data }/crates/oxc_lin ### What it does -Enforce that `autoFocus` prop is not used on elements. Autofocusing -elements can cause usability issues for sighted and non-sighted users, -alike. +Enforce that `autoFocus` prop is not used on elements. + +### Why is this bad? + +Autofocusing elements can cause usability issues for sighted and +non-sighted users alike. It can be disorienting when focus is shifted +without user input and can interfere with assistive technologies. +Users should control when and where focus moves on a page. ### Rule Option diff --git a/src/docs/guide/usage/linter/rules/jsx_a11y/no-distracting-elements.md b/src/docs/guide/usage/linter/rules/jsx_a11y/no-distracting-elements.md index c73dd0df15..d4b639403b 100644 --- a/src/docs/guide/usage/linter/rules/jsx_a11y/no-distracting-elements.md +++ b/src/docs/guide/usage/linter/rules/jsx_a11y/no-distracting-elements.md @@ -14,16 +14,12 @@ const source = `https://github.com/oxc-project/oxc/blob/${ data }/crates/oxc_lin Enforces that no distracting elements are used. -### Why is this necessary? +### Why is this bad? Elements that can be visually distracting can cause accessibility issues with visually impaired users. Such elements are most likely deprecated, and should be avoided. By default, `` and `` elements -are visually distracting. - -### What it checks - -This rule checks for marquee and blink element. +are visually distracting and can trigger vestibular disorders. ### Examples diff --git a/src/docs/guide/usage/linter/rules/nextjs/no-styled-jsx-in-document.md b/src/docs/guide/usage/linter/rules/nextjs/no-styled-jsx-in-document.md index 78bc10bee4..205b55344e 100644 --- a/src/docs/guide/usage/linter/rules/nextjs/no-styled-jsx-in-document.md +++ b/src/docs/guide/usage/linter/rules/nextjs/no-styled-jsx-in-document.md @@ -23,11 +23,50 @@ Custom CSS like styled-jsx is not allowed in a [Custom Document](https://nextjs. Examples of **incorrect** code for this rule: ```javascript +// pages/_document.js +import Document, { Head, Html, Main, NextScript } from "next/document"; + +class MyDocument extends Document { + render() { + return ( + + + +
+ + + + + ); + } +} ``` Examples of **correct** code for this rule: ```javascript +// pages/_document.js +import Document, { Head, Html, Main, NextScript } from "next/document"; + +class MyDocument extends Document { + render() { + return ( + + + +
+ + + + ); + } +} ``` ## How to use diff --git a/src/docs/guide/usage/linter/rules/oxc/no-async-await.md b/src/docs/guide/usage/linter/rules/oxc/no-async-await.md index dd9ffa6a99..5835599872 100644 --- a/src/docs/guide/usage/linter/rules/oxc/no-async-await.md +++ b/src/docs/guide/usage/linter/rules/oxc/no-async-await.md @@ -14,6 +14,13 @@ const source = `https://github.com/oxc-project/oxc/blob/${ data }/crates/oxc_lin Disallows the use of async/await. +### Why is this bad? + +This rule is useful for environments that don't support async/await syntax +or when you want to enforce the use of promises or other asynchronous +patterns instead. It can also be used to maintain consistency in codebases +that use alternative async patterns. + ### Examples Examples of **incorrect** code for this rule: diff --git a/src/docs/guide/usage/linter/rules/oxc/no-barrel-file.md b/src/docs/guide/usage/linter/rules/oxc/no-barrel-file.md index 6bdd0bf9ee..258d84e279 100644 --- a/src/docs/guide/usage/linter/rules/oxc/no-barrel-file.md +++ b/src/docs/guide/usage/linter/rules/oxc/no-barrel-file.md @@ -17,6 +17,14 @@ and the total number of modules exceed a threshold. The default threshold is 100; +### Why is this bad? + +Barrel files that re-export many modules can significantly slow down +applications and bundlers. When a barrel file exports a large number of +modules, importing from it forces the runtime or bundler to process all +the exported modules, even if only a few are actually used. This leads +to slower startup times and larger bundle sizes. + References: - diff --git a/src/docs/guide/usage/linter/rules/oxc/no-optional-chaining.md b/src/docs/guide/usage/linter/rules/oxc/no-optional-chaining.md index fc6b9e7c5d..3706e86f30 100644 --- a/src/docs/guide/usage/linter/rules/oxc/no-optional-chaining.md +++ b/src/docs/guide/usage/linter/rules/oxc/no-optional-chaining.md @@ -14,6 +14,15 @@ const source = `https://github.com/oxc-project/oxc/blob/${ data }/crates/oxc_lin Disallow [optional chaining](https://github.com/tc39/proposal-optional-chaining). +### Why is this bad? + +Optional chaining is a relatively new JavaScript feature that may not be +supported in older environments. In some cases, transpiling optional +chaining can result in verbose helper code that impacts bundle size or +performance. This rule is useful when you need to maintain compatibility +with older JavaScript targets or want to avoid the overhead of transpiled +optional chaining. + ### Examples Examples of **incorrect** code for this rule: diff --git a/src/docs/guide/usage/linter/rules/oxc/no-rest-spread-properties.md b/src/docs/guide/usage/linter/rules/oxc/no-rest-spread-properties.md index a96b916f2d..8eb6b8c139 100644 --- a/src/docs/guide/usage/linter/rules/oxc/no-rest-spread-properties.md +++ b/src/docs/guide/usage/linter/rules/oxc/no-rest-spread-properties.md @@ -14,6 +14,14 @@ const source = `https://github.com/oxc-project/oxc/blob/${ data }/crates/oxc_lin Disallow [Object Rest/Spread Properties](https://github.com/tc39/proposal-object-rest-spread#readme). +### Why is this bad? + +Object rest/spread properties are a relatively new JavaScript feature that may +not be supported in all target environments. If you need to support older +browsers or JavaScript engines that don't support these features, using them +can cause runtime errors. This rule helps maintain compatibility with older +environments by preventing the use of these modern syntax features. + ### Examples Examples of **incorrect** code for this rule: diff --git a/src/docs/guide/usage/linter/rules/react/rules-of-hooks.md b/src/docs/guide/usage/linter/rules/react/rules-of-hooks.md index aad67d9ae8..5e1ddb6cd9 100644 --- a/src/docs/guide/usage/linter/rules/react/rules-of-hooks.md +++ b/src/docs/guide/usage/linter/rules/react/rules-of-hooks.md @@ -12,9 +12,63 @@ const source = `https://github.com/oxc-project/oxc/blob/${ data }/crates/oxc_lin ### What it does -This enforces the Rules of Hooks +Enforces the Rules of Hooks, ensuring that React Hooks are only called +in valid contexts and in the correct order. - +### Why is this bad? + +React Hooks must follow specific rules to ensure they work correctly: + +1. Only call Hooks at the top level (never inside loops, conditions, + or nested functions) +2. Only call Hooks from React function components or custom Hooks +3. Hooks must be called in the same order every time a component renders + +Breaking these rules can lead to bugs where state gets corrupted or +component behavior becomes unpredictable. + +### Examples + +Examples of **incorrect** code for this rule: + +```javascript +// Don't call Hooks inside loops, conditions, or nested functions +function BadComponent() { + if (condition) { + const [state, setState] = useState(); // ❌ Hook in condition + } + + for (let i = 0; i < 10; i++) { + useEffect(() => {}); // ❌ Hook in loop + } +} + +// Don't call Hooks from regular JavaScript functions +function regularFunction() { + const [state, setState] = useState(); // ❌ Hook in regular function +} +``` + +Examples of **correct** code for this rule: + +```javascript +// ✅ Call Hooks at the top level of a React component +function GoodComponent() { + const [state, setState] = useState(); + + useEffect(() => { + // Effect logic here + }); + + return
{state}
; +} + +// ✅ Call Hooks from custom Hooks +function useCustomHook() { + const [state, setState] = useState(); + return state; +} +``` ## How to use diff --git a/src/docs/guide/usage/linter/rules/react/self-closing-comp.md b/src/docs/guide/usage/linter/rules/react/self-closing-comp.md index 8fc39fa99a..7bf17e5565 100644 --- a/src/docs/guide/usage/linter/rules/react/self-closing-comp.md +++ b/src/docs/guide/usage/linter/rules/react/self-closing-comp.md @@ -15,11 +15,17 @@ const source = `https://github.com/oxc-project/oxc/blob/${ data }/crates/oxc_lin ### What it does -Detects components without children which can be self-closed to avoid unnecessary extra -closing tags. +Detects components without children which can be self-closed to avoid +unnecessary extra closing tags. -A self closing component which contains whitespace is allowed except when it also contains -a newline. +### Why is this bad? + +Components without children don't need explicit closing tags. Using +self-closing syntax makes code more concise and reduces visual clutter. +It also follows common React and JSX conventions for empty elements. + +A self-closing component which contains whitespace is allowed except +when it also contains a newline. ### Examples diff --git a/src/docs/guide/usage/linter/rules/typescript/consistent-type-imports.md b/src/docs/guide/usage/linter/rules/typescript/consistent-type-imports.md index 1caed5529a..84afc6f36a 100644 --- a/src/docs/guide/usage/linter/rules/typescript/consistent-type-imports.md +++ b/src/docs/guide/usage/linter/rules/typescript/consistent-type-imports.md @@ -38,6 +38,89 @@ Examples of **correct** code for this rule: import type { Foo } from "Foo"; ``` +### Options + +```json +{ + "typescript/consistent-type-imports": [ + "error", + { + "prefer": "type-imports", + "fixStyle": "separate-type-imports", + "disallowTypeAnnotations": true + } + ] +} +``` + +- `prefer`: Control whether to enforce type imports or value imports + - `"type-imports"` (default): Will enforce that you always use `import type Foo from '...'` except referenced by metadata of decorators + - `"no-type-imports"`: Will enforce that you always use `import Foo from '...'` + +- `fixStyle`: Determines how type imports are added when auto-fixing + - `"separate-type-imports"` (default): Will add the type keyword after the import keyword `import type { A } from '...'` + - `"inline-type-imports"`: Will inline the type keyword `import { type A } from '...'` (only available in TypeScript 4.5+) + +- `disallowTypeAnnotations`: Disallow using `import()` in type annotations + - `true` (default): Disallows using `import()` in type annotations like `type T = import('foo')` + - `false`: Allows `import()` type annotations + +#### Examples with `"prefer": "type-imports"` (default) + +Examples of **incorrect** code: + +```ts +import { Foo } from "foo"; +let foo: Foo; +``` + +Examples of **correct** code: + +```ts +import type { Foo } from "foo"; +let foo: Foo; +``` + +#### Examples with `"prefer": "no-type-imports"` + +Examples of **incorrect** code: + +```ts +import type { Foo } from "foo"; +let foo: Foo; +``` + +Examples of **correct** code: + +```ts +import { Foo } from "foo"; +let foo: Foo; +``` + +#### Examples with `"fixStyle": "inline-type-imports"` + +When fixing type imports, this option will use inline `type` modifiers: + +```ts +// Before fixing +import { A, B } from "foo"; +type T = A; +const b = B; + +// After fixing +import { type A, B } from "foo"; +type T = A; +const b = B; +``` + +#### Examples with `"disallowTypeAnnotations": false` + +When set to `false`, allows `import()` type annotations: + +```ts +type T = import("foo").Bar; +``` + ## How to use To **enable** this rule in the CLI or using the config file, you can use: diff --git a/src/docs/guide/usage/linter/rules/typescript/prefer-function-type.md b/src/docs/guide/usage/linter/rules/typescript/prefer-function-type.md index d3c2cd8b90..0dc7d83783 100644 --- a/src/docs/guide/usage/linter/rules/typescript/prefer-function-type.md +++ b/src/docs/guide/usage/linter/rules/typescript/prefer-function-type.md @@ -16,19 +16,23 @@ const source = `https://github.com/oxc-project/oxc/blob/${ data }/crates/oxc_lin ### What it does Enforce using function types instead of interfaces with call signatures. + +### Why is this bad? + TypeScript allows for two common ways to declare a type for a function: - Function type: `() => string` - Object type with a signature: `{ (): string }` -The function type form is generally preferred when possible for being more succinct. - -This rule suggests using a function type instead of an interface or object type literal with a single call signature. +The function type form is generally preferred when possible for being +more succinct and readable. Interfaces with only call signatures add +unnecessary verbosity without providing additional functionality. ### Examples -```ts -// error +Examples of **incorrect** code for this rule: + +```typescript interface Example { (): string; } @@ -40,33 +44,31 @@ function foo(example: { (): number }): number { interface ReturnsSelf { (arg: string): this; } +``` + +Examples of **correct** code for this rule: -// success +```typescript type Example = () => string; function foo(example: () => number): number { - return bar(); + return example(); } -// returns the function itself, not the `this` argument. +// Returns the function itself, not the `this` argument type ReturnsSelf = (arg: string) => ReturnsSelf; +// Multiple properties are allowed function foo(bar: { (): string; baz: number }): string { return bar(); } -interface Foo { - bar: string; -} -interface Bar extends Foo { - (): void; -} - -// multiple call signatures (overloads) is allowed: +// Multiple call signatures (overloads) are allowed interface Overloaded { (data: string): number; (id: number): string; } + // this is equivalent to Overloaded interface. type Intersection = ((data: string) => number) & ((id: number) => string); ``` diff --git a/src/docs/guide/usage/linter/rules/unicorn/prefer-math-min-max.md b/src/docs/guide/usage/linter/rules/unicorn/prefer-math-min-max.md index 98a5b3ac2e..e0e12e5737 100644 --- a/src/docs/guide/usage/linter/rules/unicorn/prefer-math-min-max.md +++ b/src/docs/guide/usage/linter/rules/unicorn/prefer-math-min-max.md @@ -15,9 +15,15 @@ const source = `https://github.com/oxc-project/oxc/blob/${ data }/crates/oxc_lin ### What it does -Prefers use of [`Math.min()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/min) -and [`Math.max()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/max) instead of -ternary expressions when performing simple comparisons for more concise, easier to understand, and less prone to errors. +Prefers use of `Math.min()` and `Math.max()` instead of ternary +expressions when performing simple comparisons. + +### Why is this bad? + +Using `Math.min()` and `Math.max()` for simple comparisons is more +concise, easier to understand, and less prone to errors than ternary +expressions. They clearly express the intent to find the minimum or +maximum value. ### Examples diff --git a/src/docs/guide/usage/linter/rules/version.data.js b/src/docs/guide/usage/linter/rules/version.data.js index 5e04021edd..34ee7e0e32 100644 --- a/src/docs/guide/usage/linter/rules/version.data.js +++ b/src/docs/guide/usage/linter/rules/version.data.js @@ -1,5 +1,5 @@ export default { load() { - return "a696227142fa90e5e895c173ad4b7cb1207d4d92"; + return "5f74a0b16069469fcb284b69fc13223edd0b4316"; }, };