Add rationales to rule documentation

.github/contributing.md

@@ -2,7 +2,9 @@
 
 ## I have an idea for a new rule
 
-Open an issue with your proposal. Make sure you elaborate on what problem it solves and include fail/pass examples. [(Example)](https://github.com/sindresorhus/eslint-plugin-unicorn/issues/166)
+Open an issue with your proposal. Make sure you elaborate on what problem it solves, explain why the rule should exist, and include fail/pass examples. [(Example)](https://github.com/sindresorhus/eslint-plugin-unicorn/issues/166)
+
+Rule documentation must include a succinct rationale that explains why the rule exists, not only what syntax it reports.
 
 <!--
 ## I have an idea for a new rule and I also want to implement it

docs/rules/catch-error-name.md

@@ -15,6 +15,8 @@ Enforces a consistent name for caught errors across:
 - `.catch(…)` Promise handlers
 - `.then(…, rejectionHandler)` Promise handlers
 
+Using one recognizable name makes error handlers easier to scan and avoids renaming the same concept across callback styles.
+
 The desired parameter name is [configurable](#name), but defaults to `error`.
 
 The following names are ignored:

docs/rules/class-reference-in-static-methods.md

@@ -11,6 +11,8 @@
 
 This rule enforces either dynamic static dispatch with `this` and `super`, or direct references with class names.
 
+Choosing one style makes it clear whether a static method is intended to follow subclass dispatch or stay tied to a specific class.
+
 By default, it prefers `this` and `super`.
 
 ## Examples

docs/rules/consistent-class-member-order.md

@@ -8,6 +8,8 @@
 
 <!-- end auto-generated rule header -->
 
+A predictable member order makes classes faster to scan and keeps related static, instance, field, and method members together.
+
 This rule enforces the following class member order:
 
 1. Static fields

docs/rules/consistent-compound-words.md

@@ -11,6 +11,8 @@
 
 Compound words should be treated as one word when applying identifier casing conventions.
 
+Treating the same compound word consistently prevents equivalent concepts from being cased differently across identifiers.
+
 This rule uses a conservative curated list of common compound-word mistakes in code identifiers. It is not a spellchecker or a prose style rule.
 
 ## Examples

docs/rules/consistent-function-style.md

@@ -11,6 +11,8 @@
 
 Enforce function syntax by role.
 
+Choosing syntax by function role keeps declarations consistent and makes callbacks, methods, and standalone functions easier to distinguish.
+
 By default, this rule reports nothing. Configure the roles you want to enforce.
 
 This rule does not autofix. Function declarations, function expressions, arrow functions, and object methods are not always semantic equivalents, so `--fix` would be too risky for a style rule.

docs/rules/consistent-optional-chaining.md

@@ -10,6 +10,8 @@
 
 Enforce consistent optional chaining for same-base member access in logical expressions.
 
+Using optional chaining consistently for the same base makes nullish behavior easier to see and avoids visually similar expressions that handle missing values differently.
+
 This rule intentionally handles only direct member access on both sides of `&&` or `||`. It does not rewrite broad truthiness checks like `foo && foo.bar` to `foo?.bar`, because that can change runtime values.
 
 ## Examples

docs/rules/default-export-style.md

@@ -11,6 +11,8 @@
 
 Enforce whether default-exported functions and classes are declared inline with `export default` or separately. For functions, separate means a `const` arrow function exported by identifier. For classes, separate means a class declaration exported by identifier.
 
+A consistent declaration style makes default exports easier to scan and avoids mixing multiple declaration forms across a codebase.
+
 This rule only checks local default exports. Named exports are intentionally ignored. Use [`consistent-function-style`](./consistent-function-style.md) for named function export syntax.
 
 Anonymous default exports remain the responsibility of [`no-anonymous-default-export`](./no-anonymous-default-export.md).

docs/rules/dom-node-dataset.md

@@ -11,6 +11,8 @@
 
 Use [`.dataset`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/dataset) on DOM elements over `getAttribute(…)`, `.setAttribute(…)`, `.removeAttribute(…)` and `.hasAttribute(…)`.
 
+The `dataset` API maps `data-*` attributes to properties, avoiding repeated attribute-name strings and keeping reads and writes consistent.
+
 ## Examples
 
 ```js

docs/rules/empty-brace-spaces.md

@@ -9,6 +9,8 @@
 <!-- end auto-generated rule header -->
 <!-- Do not manually modify this header. Run: `npm run fix:eslint-docs` -->
 
+Keeping empty braces together makes empty blocks and object literals easier to scan and avoids whitespace that has no meaning.
+
 ## Examples
 
 ```js

docs/rules/explicit-length-check.md

@@ -9,7 +9,7 @@
 <!-- end auto-generated rule header -->
 <!-- Do not manually modify this header. Run: `npm run fix:eslint-docs` -->
 
-This rule is only meant to enforce a specific style and make comparisons more clear.
+Explicit comparisons make empty and non-empty intent clear instead of relying on the truthiness of a numeric property.
 
 This rule is fixable, unless it's [unsafe to fix](#unsafe-to-fix-case).
 

docs/rules/filename-case.md

@@ -9,6 +9,8 @@
 
 Enforces filenames and directory names of linted files to use a certain case style and lowercase file extension. The default is `kebabCase`.
 
+Consistent paths make files predictable to find and import, including on case-sensitive filesystems.
+
 Because this rule only inspects the path, it applies to files of any language, not just JavaScript, as long as they are linted with the matching ESLint language plugin (for example [`@eslint/css`](https://github.com/eslint/css) or [`@eslint/markdown`](https://github.com/eslint/markdown)).
 
 Directory names are checked only when the file is inside the current working directory. Files outside the current working directory only have their filename checked.

docs/rules/id-match.md

@@ -9,6 +9,8 @@
 
 This rule is the same as the built-in ESLint [`id-match`](https://eslint.org/docs/latest/rules/id-match) rule, but with an additional `checkNamedSpecifiers` option.
 
+Enforcing an identifier pattern prevents names from drifting from a project's naming convention while keeping that convention configurable.
+
 ## Replacement for ESLint `id-match`
 
 This rule replaces ESLint's built-in `id-match` rule, which Unicorn presets disable when this rule is enabled.

docs/rules/logical-assignment-operators.md

@@ -11,6 +11,8 @@
 
 This rule is the same as the built-in ESLint [`logical-assignment-operators`](https://eslint.org/docs/latest/rules/logical-assignment-operators) rule, but when `enforceForIfStatements` is enabled, falsy `if` assignments are reported with suggestions for both `||=` and `??=` instead of being autofixed.
 
+Consistently choosing logical-assignment shorthand or an explicit assignment or conditional makes updates easier to scan and avoids mixing the same pattern in different forms.
+
 ## Replacement for ESLint `logical-assignment-operators`
 
 This rule replaces ESLint's built-in `logical-assignment-operators` rule, which Unicorn presets disable when this rule is enabled.

docs/rules/no-exports-in-scripts.md

@@ -9,6 +9,8 @@
 
 Scripts are meant to be executed directly, not imported as modules.
 
+Exports in a script mix module and script boundaries and can mislead readers about how the file is intended to run.
+
 ## Examples
 
 This script fails:

docs/rules/no-incorrect-query-selector.md

@@ -11,6 +11,8 @@
 
 This rule catches common incorrect or inefficient `querySelector()` and `querySelectorAll()` usage.
 
+Using the appropriate query method avoids retrieving a collection when only one element is needed and makes empty and no-match checks explicit.
+
 ## Examples
 
 ```js

docs/rules/no-lonely-if.md

@@ -11,6 +11,8 @@
 
 This rule adds onto the built-in [`no-lonely-if`](https://eslint.org/docs/rules/no-lonely-if) rule, which only disallows `if` statements in `else`, not in `if`. It is recommended to use `unicorn/no-lonely-if` together with the core ESLint `no-lonely-if` rule.
 
+Nested `if` statements add indentation without adding an alternative branch, making control flow harder to scan.
+
 ## Examples
 
 ```js

docs/rules/no-magic-array-flat-depth.md

@@ -9,6 +9,8 @@
 
 When calling [`Array#flat(depth)`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/flat), the depth argument should normally be `1` or `Infinity`, otherwise it should be a meaningful variable name or explained with a comment.
 
+A bare depth number does not explain why that particular nesting depth is required, so naming or commenting it preserves intent for readers.
+
 ## Examples
 
 ```js

docs/rules/no-named-default.md

@@ -11,6 +11,8 @@
 
 Enforces the use of the [`default import`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import) and [`default export`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/export#using_the_default_export) syntax instead of named syntax.
 
+The named form is easy to mistake for a named specifier during refactors; dedicated default syntax makes the binding's intent explicit.
+
 ## Examples
 
 ```js

docs/rules/no-negated-comparison.md

@@ -11,6 +11,8 @@
 
 Prefer using the opposite comparison operator instead of negating the whole comparison.
 
+Writing the opposite operator directly makes the comparison easier to read and reduces mental negation.
+
 By default, the rule intentionally does not rewrite compound logical expressions like `!(a === b && c === d)`. Keeping the grouped negation can be easier to read.
 
 Relational comparisons (`<`, `>`, `<=`, `>=`) with optional chaining are ignored, since the operand can be `undefined` and `!(a?.b >= 2)` is not equivalent to `a?.b < 2`. Equality comparisons are unaffected.

docs/rules/no-negation-in-equality-check.md

@@ -9,7 +9,7 @@
 <!-- end auto-generated rule header -->
 <!-- Do not manually modify this header. Run: `npm run fix:eslint-docs` -->
 
-Using a negated expression in equality check is most likely a mistake.
+A negated expression inside an equality check is easy to misread and often indicates that the negation was applied at the wrong level.
 
 ## Examples
 

docs/rules/no-nested-ternary.md

@@ -11,6 +11,8 @@
 
 Improved version of the [`no-nested-ternary`](https://eslint.org/docs/latest/rules/no-nested-ternary) ESLint rule. This rule allows cases where the nested ternary is only one level and wrapped in parens.
 
+Nested ternaries require readers to track multiple conditions and branches at once, making them harder to read and maintain.
+
 ## Replacement for ESLint `no-nested-ternary`
 
 This rule replaces ESLint's built-in `no-nested-ternary` rule, which Unicorn presets disable when this rule is enabled.

docs/rules/no-null.md

@@ -9,7 +9,7 @@
 <!-- end auto-generated rule header -->
 <!-- Do not manually modify this header. Run: `npm run fix:eslint-docs` -->
 
-Disallow the use of the `null` literal, to encourage using `undefined` instead. You can learn why in <https://github.com/sindresorhus/meta/discussions/7>
+Disallow the use of the `null` literal, to encourage using `undefined` instead. Using one absence value within a codebase reduces ambiguity when APIs exchange missing values. You can learn more in <https://github.com/sindresorhus/meta/discussions/7>
 
 ## Examples
 

docs/rules/no-process-exit.md

@@ -7,7 +7,7 @@
 <!-- end auto-generated rule header -->
 <!-- Do not manually modify this header. Run: `npm run fix:eslint-docs` -->
 
-This rule is an extension to ESLint's [`no-process-exit` rule](https://eslint.org/docs/rules/no-process-exit), that allows `process.exit()` to be called in files that start with a [hashbang](https://en.wikipedia.org/wiki/Shebang_(Unix)) → `#!/usr/bin/env node`. It also allows `process.exit()` to be called in `process.on('<event>', func)` event handlers and in files that imports `worker_threads`.
+This rule is an extension to ESLint's [`no-process-exit` rule](https://eslint.org/docs/rules/no-process-exit). Calling `process.exit()` abruptly terminates the process and can bypass normal error propagation and cleanup, so exits are restricted in ordinary application code while permitted in files that start with a [hashbang](https://en.wikipedia.org/wiki/Shebang_(Unix)) → `#!/usr/bin/env node`, `process.on('<event>', func)` event handlers, and files that statically import or require `worker_threads`.
 
 ## Replacement for ESLint `no-process-exit`
 

docs/rules/no-single-promise-in-promise-methods.md

@@ -11,6 +11,8 @@
 
 Passing a single-element array to `Promise.all()`, `Promise.any()`, or `Promise.race()` is likely a mistake.
 
+Promise combinators are intended for coordinating multiple inputs; wrapping one value adds unnecessary array handling and can hide a missing promise.
+
 ## Examples
 
 ```js

docs/rules/no-static-only-class.md

@@ -11,6 +11,8 @@
 
 A class with only static members could just be an object instead.
 
+Using an object avoids implying that instances or a prototype are meaningful when the class has no instance behavior.
+
 ## Examples
 
 ```js

docs/rules/no-unnecessary-polyfills.md

@@ -6,7 +6,7 @@
 
 <!-- end auto-generated rule header -->
 
-This rule helps to use existing methods instead of using extra polyfills.
+Unneeded polyfills add dependencies and code paths while providing no benefit on targets that already support the method.
 
 ## Examples
 

docs/rules/no-unreadable-iife.md

@@ -11,6 +11,8 @@
 
 [IIFE](https://en.wikipedia.org/wiki/Immediately_invoked_function_expression) with parenthesized arrow function body is considered unreadable.
 
+Parenthesized arrow bodies make an IIFE look like a grouped expression and obscure where the function body begins.
+
 ## Examples
 
 ```js

docs/rules/no-useless-re-export.md

@@ -9,6 +9,8 @@
 
 This rule reports named exports that are already covered by an `export *` from the same module.
 
+Removing redundant re-exports keeps module API declarations smaller and avoids implying a special export when the wildcard already exposes it.
+
 The rule only compares module specifiers as written. It does not resolve paths or inspect the module graph. Named exports are ignored when the file re-exports multiple distinct wildcard module requests, as those exports can resolve conflicting names.
 
 Importing a binding and exporting it locally is the concern of [`prefer-export-from`](./prefer-export-from.md). This rule checks only direct `export … from` declarations.

docs/rules/no-useless-spread.md

@@ -9,6 +9,8 @@
 <!-- end auto-generated rule header -->
 <!-- Do not manually modify this header. Run: `npm run fix:eslint-docs` -->
 
+Removing unnecessary spread avoids redundant copying and conversion, and makes it clear when an array, object, or iterable can be used directly.
+
 - Using spread syntax in the following cases is unnecessary:
 
   - Spread an array literal as elements of an array literal

docs/rules/no-useless-switch-case.md

@@ -11,6 +11,8 @@
 
 An empty case before the last default case is useless.
 
+Removing it avoids suggesting that the case has distinct behavior when execution would immediately enter the default case.
+
 In TypeScript files, empty `case null:` and `case undefined:` before `default:` are allowed so type-aware exhaustiveness checks can require explicit nullish union members while `default:` still handles unexpected values.
 
 ## Examples

docs/rules/prefer-array-flat-map.md

@@ -11,6 +11,8 @@
 
 [`Array#flatMap`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/flatMap) performs [`Array#map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map) and [`Array#flat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/flat) in one step.
 
+It expresses mapping and flattening directly and avoids intermediate arrays created by separate `map()` or `filter()` calls.
+
 It can also add or remove items during mapping by returning an empty array for items that should be skipped. This rule only reports `.filter().flatMap()` when the `.flatMap()` callback can return multiple items. Single-item callbacks are handled by [`unicorn/no-unnecessary-array-flat-map`](./no-unnecessary-array-flat-map.md).
 
 ## Examples

docs/rules/prefer-array-flat.md

@@ -11,6 +11,8 @@
 
 ES2019 introduced a new method [`Array#flat()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/flat) that flattens arrays.
 
+The native method expresses flattening directly and avoids verbose or indirect flattening patterns.
+
 ## Examples
 
 ```js

docs/rules/prefer-array-last-methods.md

@@ -11,6 +11,8 @@
 
 Prefer last-oriented array methods over reversing an array and then calling the forward method.
 
+Last-oriented methods express the traversal direction directly and avoid reversing the array before the operation.
+
 This rule reports `.reverse()` and `.toReversed()` followed by `.find()`, `.findIndex()`, `.indexOf()`, or `.reduce()`.
 
 This rule only provides editor suggestions. The replacement can change observable behavior for mutation, sparse arrays, callback index or array arguments, and index-returning methods.

docs/rules/prefer-array-some.md

@@ -9,6 +9,8 @@
 <!-- end auto-generated rule header -->
 <!-- Do not manually modify this header. Run: `npm run fix:eslint-docs` -->
 
+`Array#some` directly expresses an existence check, making it clearer than inspecting a result or found value.
+
 Prefer using [`Array#some`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/some) over:
 
 - Non-zero length check on the result of [`Array#filter()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/filter).

docs/rules/prefer-class-fields.md

@@ -11,6 +11,8 @@
 
 Enforces declaring property defaults with class fields instead of setting them inside the constructor.
 
+Class fields keep property initialization next to the declaration and avoid boilerplate in constructors.
+
 > To avoid leaving empty constructors after autofixing, use the [`no-useless-constructor` rule](https://eslint.org/docs/latest/rules/no-useless-constructor).
 
 ## Examples

docs/rules/prefer-classlist-toggle.md

@@ -11,6 +11,8 @@
 
 Prefer using [`Element#classList.toggle()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/classList) instead of conditionally calling `classList.add()` and `classList.remove()`.
 
+`toggle()` expresses the boolean intent in one operation and avoids keeping separate add and remove branches in sync.
+
 ## Examples
 
 ```js

docs/rules/prefer-global-this.md

@@ -11,6 +11,8 @@
 
 This rule will enforce the use of `globalThis` over `window`, `self`, and `global`.
 
+`globalThis` is the standard cross-environment reference, so it keeps code portable between browsers, Node.js, and other JavaScript runtimes.
+
 However, there are several exceptions that remain permitted:
 
 1. Certain window-specific APIs, such as `window.innerHeight`

docs/rules/prefer-has-check.md

@@ -11,6 +11,8 @@
 
 Prefer `.has()` over `.get()` when checking whether an item exists.
 
+`.has()` directly checks membership without conflating absence with a stored value.
+
 This rule is conservative. It reports `Map`, `ReadonlyMap`, and `WeakMap` only when TypeScript type information, simple TypeScript annotations, or inline `new Map(...)` or `new WeakMap(...)` constructors prove stored values cannot be confused with a missing value. It also reports explicit `null` comparisons and loose `undefined` comparisons for `URLSearchParams`, `Headers`, and `FormData`.
 
 ## Examples

docs/rules/prefer-import-meta-properties.md

@@ -11,6 +11,8 @@
 
 Starting with Node.js 20.11, [`import.meta.dirname`](https://nodejs.org/api/esm.html#importmetadirname) and [`import.meta.filename`](https://nodejs.org/api/esm.html#importmetafilename) have been introduced in ES modules.
 
+These built-in properties avoid converting `import.meta.url` and calling path helpers, so file-path code is shorter and clearer.
+
 > `import.meta.filename` is the same as the `url.fileURLToPath()` of the `import.meta.url`.\
 > `import.meta.dirname` is the same as the `path.dirname()` of the `import.meta.filename`.
 

docs/rules/prefer-math-abs.md

@@ -11,6 +11,8 @@
 
 This rule enforces the use of `Math.abs()` instead of hand-written absolute value expressions and symmetric range checks.
 
+`Math.abs()` states the intent directly and avoids duplicating the two sides of an absolute-value calculation.
+
 ## Examples
 
 ```js

docs/rules/prefer-modern-math-apis.md

@@ -9,6 +9,8 @@
 <!-- end auto-generated rule header -->
 <!-- Do not manually modify this header. Run: `npm run fix:eslint-docs` -->
 
+Standard `Math` methods express mathematical intent directly and are less error-prone than reimplementing them.
+
 Math additions in ES2015:
 
 - [Math.sign()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/sign)

docs/rules/prefer-negative-index.md

@@ -9,6 +9,8 @@
 <!-- end auto-generated rule header -->
 <!-- Do not manually modify this header. Run: `npm run fix:eslint-docs` -->
 
+Negative indexes express positions from the end directly, avoiding length arithmetic and making the intent easier to read.
+
 Prefer negative index over calculating from `.length` for:
 
 - [`String#slice()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/slice)