exadev-eslint-config 2.19.4 → 2.20.0

package/README.md

@@ -57,6 +57,7 @@ export default defineConfig(
 - `exadev/prefer-readonly-array-param`
 - `exadev/prefer-readonly-object-param`
 - `exadev/prefer-numeric-sort-compare`
+- `exadev/prefer-options-object-param`
 - `exadev/no-pointless-reassignment`
 - `exadev/test-file-kind`
 
@@ -84,6 +85,8 @@ export default defineConfig(
 - **[`no-magic-numbers`](https://typescript-eslint.io/rules/no-magic-numbers/)** — tuned to exempt array indexes, enum members, readonly class properties, default parameter values, numeric literal types (e.g. `type Indent = 2 | 4`), and the handful of universally-idiomatic bare numbers (`-1`, `0`, `1`, `2`).
 - **[`max-lines`](https://eslint.org/docs/latest/rules/max-lines)** set to `{ max: 800, skipBlankLines: true, skipComments: true }`.
   - *Why:* counting only real code means a file isn't pushed over the limit by whitespace or its own WHY-explanation comments.
+- **[`max-params`](https://eslint.org/docs/latest/rules/max-params)** set to `{ max: 4 }`, one above the rule's own default of `3`. Needs no type information — registered in both `plugin.configs.recommended` and the default (type-checked) export, like `exadev/prefer-readonly-array-param` above.
+  - *Why:* a deliberately loose backstop against a genuinely excessive number of REQUIRED parameters, distinct from `exadev/prefer-options-object-param` above, which already offers a real fix for the more common shape (a run of 2+ trailing OPTIONAL parameters) this rule structurally cannot see until the total count crosses its own threshold.
 - **[`no-warning-comments`](https://eslint.org/docs/latest/rules/no-warning-comments)** — bans any comment containing `Stryker disable`.
   - *Why:* that's Stryker's own mutation-testing suppression directive, invisible to `noInlineConfig` above since it isn't an eslint-disable comment.
 
@@ -281,6 +284,7 @@ Bundled into `exadevConfig()`'s default output the same way React/Next.js auto-d
 | `no-enum-number-widening` | | **A bare `number` is accepted anywhere a numeric enum is expected**, without checking it is actually one of the enum's members — only a numeric *literal* gets range-checked by `tsc`. No autofix: the only provably safe fix is a genuine runtime membership check against the enum's own values, which is a behavioural choice a mechanical fix cannot responsibly make. Requires type information — only in the default (type-checked) export, not `plugin.configs.recommended`. |
 | `no-enum-reverse-lookup-widening` | suggestion | **A numeric enum's reverse lookup can silently type as `string` for an out-of-range index.** Indexing a numeric enum's reverse mapping (`Direction[n]`) with a bare (non-literal) `number`, or with a different enum's member, types as plain `string` for any index, including one outside the enum's actual members, where it genuinely returns `undefined` at runtime — `tsc` does not range-check even a numeric literal index here. When the indexed expression is the init of a variable with an explicit `: string` annotation, a suggestion widens it to `: string \| undefined`, forcing later uses as a bare `string` to surface as real compile errors; every other syntactic position gets a plain report with no fix, and no case gets a full `--fix` autofix. Requires type information — only in the default (type-checked) export, not `plugin.configs.recommended`. |
 | `prefer-numeric-sort-compare` | suggestion | **`.sort()` on a number array sorts lexicographically by default.** A deliberately narrow addition alongside [`@typescript-eslint/require-array-sort-compare`](https://typescript-eslint.io/rules/require-array-sort-compare/) (which already flags any bare `.sort()`/`.toSorted()` except on a plain string array, with no fix): when the array's element type is definitively `number`, a suggestion offers an ascending compare function (`(a, b) => a - b`), since the default comparator sorts lexicographically (`[1, 2, 10].sort()` becomes `[1, 10, 2]`). Not a full autofix — descending order is a real, if less common, alternative intent. Requires type information — only in the default (type-checked) export, not `plugin.configs.recommended`, since it needs the checker to confirm the array's element type. |
+| `prefer-options-object-param` | suggestion | **A run of 2+ trailing optional parameters (`?`-marked or default-valued) should be bundled into one destructured `options` parameter.** Without this, a caller needing only the last optional parameter must still pass `undefined` for every optional parameter before it (the motivating case: a 10-parameter constructor with 8 trailing optional ones). The threshold is configurable (`{ minTrailingOptional }`, default `2`). A suggestion (not a full autofix) rewrites the parameter list and inserts a `const { ... } = options ?? {};` destructure as the body's first statement; call sites are never rewritten, since the signature edit alone turns every stale positional call site into a real compile error. Still reported, but with no suggestion offered, whenever collapsing the run would not be safe/mechanical: a parameter property in the run, a parameter with no simple resolvable name and explicit type of its own (including a destructured parameter, or one typed only through a separately-declared function-type alias), a decorated parameter, a rest parameter anywhere in the full parameter list, no `BlockStatement` body at all (an arrow's expression body, or any declaration-only signature — including an ambient `.d.ts` function, an interface method/construct signature, or an abstract/ambient class method), a `@param` JSDoc tag naming a parameter in the run, or a parameter/function-scope-local variable already named `options`. Complements `max-params` (see "Individual rule tuning" above), which catches the different shape (excessive REQUIRED parameters) this rule is deliberately blind to. Requires no type information, but is registered only in the default (type-checked) export — alongside `prefer-readonly-object-param` and `prefer-numeric-sort-compare` above, for a consistent "every rewrite-suggestion `prefer-*` rule lives here" story, not because it needs the checker for anything. |
 | `package-json-key-order` | ✓ | **Requires `package.json`'s keys to match `syncpack format`'s order.** See [Optional package.json key ordering](#optional-packagejson-key-ordering) — opt-in via `exadevConfig({ packageJsonKeyOrder: true })`, not part of `recommended`/`barrel`. A JSON-language rule (`@eslint/json`'s `json/json`), not a TSESLint one — needs no type information and doesn't apply to any `.ts`/`.js` file. |
 | `test-file-kind` | | **A test file's name must declare its own test kind.** A filename suffix immediately before `.test`/`.spec` (e.g. `foo.unit.test.ts`), one of a configurable `{ kinds }` set (default: `unit`, `integration`, `e2e`). A naming-discipline rule, not a content classifier — it checks only the filename, never what the file actually tests. Self-scoped to real test/spec files (`context.filename`), so it never misfires when applied unscoped and never relies on a consumer's own `files` config. Requires no type information. |
 

package/dist/index.cjs

@@ -295,7 +295,7 @@ function buildNextjsConfig(options = {}) {
 }
 //#endregion
 //#region package.json
-var version = "2.19.4";
+var version = "2.20.0";
 //#endregion
 //#region src/react.ts
 const JSX_FILE_PATTERNS = ["**/*.jsx", "**/*.tsx"];
@@ -653,7 +653,7 @@ const MUTATING_INSERT_METHODS$1 = /* @__PURE__ */ new Set([
 	"fill",
 	"copyWithin"
 ]);
-const createRule$7 = _typescript_eslint_utils.ESLintUtils.RuleCreator((name) => `https://github.com/ExaDev/eslint-config/blob/main/src/rules/${name}.ts`);
+const createRule$8 = _typescript_eslint_utils.ESLintUtils.RuleCreator((name) => `https://github.com/ExaDev/eslint-config/blob/main/src/rules/${name}.ts`);
 function isArrayIsArrayCall(node) {
 	return node.type === _typescript_eslint_utils.AST_NODE_TYPES.CallExpression && node.callee.type === _typescript_eslint_utils.AST_NODE_TYPES.MemberExpression && !node.callee.computed && node.callee.object.type === _typescript_eslint_utils.AST_NODE_TYPES.Identifier && node.callee.object.name === "Array" && node.callee.property.type === _typescript_eslint_utils.AST_NODE_TYPES.Identifier && node.callee.property.name === "isArray";
 }
@@ -665,7 +665,7 @@ function definitelyExits$2(statement) {
 	}
 	return false;
 }
-const noArrayIsArrayMutation = createRule$7({
+const noArrayIsArrayMutation = createRule$8({
 	name: "no-array-isarray-mutation",
 	meta: {
 		type: "problem",
@@ -822,6 +822,11 @@ function lastTokenOrThrow(sourceCode, node) {
 	if (token === null) throw new Error("Unreachable: getLastToken returned null for a node expected to always have at least one token.");
 	return token;
 }
+function firstTokenOrThrow(sourceCode, node) {
+	const token = sourceCode.getFirstToken(node);
+	if (token === null) throw new Error("Unreachable: getFirstToken returned null for a node expected to always have at least one token.");
+	return token;
+}
 //#endregion
 //#region src/rules/no-enum-number-widening.ts
 const noEnumNumberWidening = _typescript_eslint_utils.ESLintUtils.RuleCreator((name) => `https://github.com/ExaDev/eslint-config/blob/main/src/rules/${name}.ts`)({
@@ -944,7 +949,7 @@ const noIndexFiles = {
 };
 //#endregion
 //#region src/rules/no-map-instanceof-mutation.ts
-const createRule$6 = _typescript_eslint_utils.ESLintUtils.RuleCreator((name) => `https://github.com/ExaDev/eslint-config/blob/main/src/rules/${name}.ts`);
+const createRule$7 = _typescript_eslint_utils.ESLintUtils.RuleCreator((name) => `https://github.com/ExaDev/eslint-config/blob/main/src/rules/${name}.ts`);
 const MUTATING_MAP_METHODS = /* @__PURE__ */ new Set([
 	"set",
 	"delete",
@@ -961,7 +966,7 @@ function definitelyExits$1(statement) {
 	}
 	return false;
 }
-const noMapInstanceofMutation = createRule$6({
+const noMapInstanceofMutation = createRule$7({
 	name: "no-map-instanceof-mutation",
 	meta: {
 		type: "problem",
@@ -1042,7 +1047,7 @@ const MUTATING_INSERT_METHODS = /* @__PURE__ */ new Set([
 	"fill",
 	"copyWithin"
 ]);
-const createRule$5 = _typescript_eslint_utils.ESLintUtils.RuleCreator((name) => `https://github.com/ExaDev/eslint-config/blob/main/src/rules/${name}.ts`);
+const createRule$6 = _typescript_eslint_utils.ESLintUtils.RuleCreator((name) => `https://github.com/ExaDev/eslint-config/blob/main/src/rules/${name}.ts`);
 function buildReadonlyArrayFix(annotated, fixer) {
 	if (annotated.type === _typescript_eslint_utils.AST_NODE_TYPES.TSArrayType) return fixer.insertTextBefore(annotated, "readonly ");
 	if (annotated.type !== _typescript_eslint_utils.AST_NODE_TYPES.TSTypeReference) throw new Error(`Unreachable: expected a TSArrayType or TSTypeReference, got ${annotated.type} instead.`);
@@ -1055,7 +1060,7 @@ function isUnionArrayType(typeAnnotation) {
 		if (firstParam?.type === _typescript_eslint_utils.AST_NODE_TYPES.TSUnionType) return firstParam;
 	}
 }
-const noMutableUnionArrayParam = createRule$5({
+const noMutableUnionArrayParam = createRule$6({
 	name: "no-mutable-union-array-param",
 	meta: {
 		type: "problem",
@@ -1108,7 +1113,7 @@ const noNonBarrelIndex = {
 };
 //#endregion
 //#region src/rules/no-non-barrel-reexport.ts
-function removeListMember(fixer, sourceCode, declaration, members, target) {
+function removeListMember({ fixer, sourceCode }, declaration, members, target) {
 	if (members.length === 1) return fixer.remove(declaration);
 	const targetIndex = members.indexOf(target);
 	const isLast = targetIndex === members.length - 1;
@@ -1156,8 +1161,14 @@ const noNonBarrelReexport = {
 						messageId: "splitStatementReexport",
 						data: { name },
 						fix(fixer) {
-							const fixes = [removeListMember(fixer, sourceCode, declaration, declaration.specifiers, specifier)];
-							if (specifier.local.type === "Identifier" && importIsOnlyUsedByThisExport(sourceCode, trackedImport, specifier.local)) fixes.push(removeListMember(fixer, sourceCode, trackedImport.declaration, trackedImport.declaration.specifiers, trackedImport.specifier));
+							const fixes = [removeListMember({
+								fixer,
+								sourceCode
+							}, declaration, declaration.specifiers, specifier)];
+							if (specifier.local.type === "Identifier" && importIsOnlyUsedByThisExport(sourceCode, trackedImport, specifier.local)) fixes.push(removeListMember({
+								fixer,
+								sourceCode
+							}, trackedImport.declaration, trackedImport.declaration.specifiers, trackedImport.specifier));
 							return fixes;
 						}
 					});
@@ -1169,7 +1180,10 @@ const noNonBarrelReexport = {
 						data: { name },
 						fix(fixer) {
 							const fixes = [fixer.remove(declaration)];
-							if (importIsOnlyUsedByThisExport(sourceCode, trackedImport, identifierNode)) fixes.push(removeListMember(fixer, sourceCode, trackedImport.declaration, trackedImport.declaration.specifiers, trackedImport.specifier));
+							if (importIsOnlyUsedByThisExport(sourceCode, trackedImport, identifierNode)) fixes.push(removeListMember({
+								fixer,
+								sourceCode
+							}, trackedImport.declaration, trackedImport.declaration.specifiers, trackedImport.specifier));
 							return fixes;
 						}
 					});
@@ -1180,14 +1194,14 @@ const noNonBarrelReexport = {
 };
 //#endregion
 //#region src/rules/no-object-assign.ts
-const createRule$4 = _typescript_eslint_utils.ESLintUtils.RuleCreator((name) => `https://github.com/ExaDev/eslint-config/blob/main/src/rules/${name}.ts`);
+const createRule$5 = _typescript_eslint_utils.ESLintUtils.RuleCreator((name) => `https://github.com/ExaDev/eslint-config/blob/main/src/rules/${name}.ts`);
 function resolveFrom$1(scope, name) {
 	for (let current = scope; current; current = current.upper) {
 		const found = current.set.get(name);
 		if (found) return found;
 	}
 }
-const noObjectAssign = createRule$4({
+const noObjectAssign = createRule$5({
 	name: "no-object-assign",
 	meta: {
 		type: "problem",
@@ -1333,7 +1347,7 @@ const MUTATING_SET_METHODS = /* @__PURE__ */ new Set([
 	"delete",
 	"clear"
 ]);
-const createRule$3 = _typescript_eslint_utils.ESLintUtils.RuleCreator((name) => `https://github.com/ExaDev/eslint-config/blob/main/src/rules/${name}.ts`);
+const createRule$4 = _typescript_eslint_utils.ESLintUtils.RuleCreator((name) => `https://github.com/ExaDev/eslint-config/blob/main/src/rules/${name}.ts`);
 function isSetInstanceofExpression(node) {
 	return node.type === _typescript_eslint_utils.AST_NODE_TYPES.BinaryExpression && node.operator === "instanceof" && node.right.type === _typescript_eslint_utils.AST_NODE_TYPES.Identifier && node.right.name === "Set";
 }
@@ -1345,7 +1359,7 @@ function definitelyExits(statement) {
 	}
 	return false;
 }
-const noSetInstanceofMutation = createRule$3({
+const noSetInstanceofMutation = createRule$4({
 	name: "no-set-instanceof-mutation",
 	meta: {
 		type: "problem",
@@ -1639,13 +1653,13 @@ const packageJsonKeyOrder = {
 };
 //#endregion
 //#region src/rules/prefer-numeric-sort-compare.ts
-const createRule$2 = _typescript_eslint_utils.ESLintUtils.RuleCreator((name) => `https://github.com/ExaDev/eslint-config/blob/main/src/rules/${name}.ts`);
+const createRule$3 = _typescript_eslint_utils.ESLintUtils.RuleCreator((name) => `https://github.com/ExaDev/eslint-config/blob/main/src/rules/${name}.ts`);
 const SORT_METHOD_NAMES = /* @__PURE__ */ new Set(["sort", "toSorted"]);
 function isDefinitelyNumberType(type) {
 	if (type.isUnion()) return type.types.every((constituent) => isDefinitelyNumberType(constituent));
 	return (type.flags & typescript.TypeFlags.NumberLike) !== 0;
 }
-const preferNumericSortCompare = createRule$2({
+const preferNumericSortCompare = createRule$3({
 	name: "prefer-numeric-sort-compare",
 	meta: {
 		type: "suggestion",
@@ -1687,6 +1701,170 @@ const preferNumericSortCompare = createRule$2({
 	}
 });
 //#endregion
+//#region src/rules/prefer-options-object-param.ts
+const createRule$2 = _typescript_eslint_utils.ESLintUtils.RuleCreator((name) => `https://github.com/ExaDev/eslint-config/blob/main/src/rules/${name}.ts`);
+const FUNCTION_LIKE_SELECTOR$2 = [
+	"ArrowFunctionExpression",
+	"FunctionDeclaration",
+	"FunctionExpression",
+	"TSCallSignatureDeclaration",
+	"TSConstructSignatureDeclaration",
+	"TSDeclareFunction",
+	"TSEmptyBodyFunctionExpression",
+	"TSFunctionType",
+	"TSMethodSignature"
+].join(", ");
+function isOptionalParam(param) {
+	if (param.type === _typescript_eslint_utils.AST_NODE_TYPES.TSParameterProperty) return isOptionalParam(param.parameter);
+	if (param.type === _typescript_eslint_utils.AST_NODE_TYPES.AssignmentPattern) return true;
+	if (param.type === _typescript_eslint_utils.AST_NODE_TYPES.Identifier) return param.optional;
+	return false;
+}
+function getTrailingOptionalRun(params) {
+	const hasTrailingRest = params.length > 0 && params[params.length - 1]?.type === _typescript_eslint_utils.AST_NODE_TYPES.RestElement;
+	const run = [];
+	for (let i = params.length - (hasTrailingRest ? 2 : 1); i >= 0; i--) {
+		const param = params[i];
+		if (param === void 0 || !isOptionalParam(param)) break;
+		run.unshift(param);
+	}
+	return run;
+}
+function resolveFixableParam(param) {
+	if (param.type === _typescript_eslint_utils.AST_NODE_TYPES.TSParameterProperty) return void 0;
+	const identifierNode = param.type === _typescript_eslint_utils.AST_NODE_TYPES.AssignmentPattern ? param.left.type === _typescript_eslint_utils.AST_NODE_TYPES.Identifier ? param.left : void 0 : param.type === _typescript_eslint_utils.AST_NODE_TYPES.Identifier ? param : void 0;
+	if (identifierNode === void 0) return void 0;
+	const typeNode = identifierNode.typeAnnotation?.typeAnnotation;
+	if (typeNode === void 0) return void 0;
+	if (identifierNode.decorators.length > 0) return void 0;
+	return {
+		identifierNode,
+		typeNode,
+		defaultExpression: param.type === _typescript_eslint_utils.AST_NODE_TYPES.AssignmentPattern ? param.right : void 0
+	};
+}
+function isDefined(value) {
+	return value !== void 0;
+}
+function firstAndLastOrThrow(items) {
+	const first = items[0];
+	const last = items.at(-1);
+	if (first === void 0 || last === void 0) throw new Error("Unreachable: expected at least one element (the caller already confirmed a minimum run length).");
+	return [first, last];
+}
+function describeFunctionKind(node) {
+	if (node.type === _typescript_eslint_utils.AST_NODE_TYPES.TSConstructSignatureDeclaration) return "constructor";
+	if (node.type === _typescript_eslint_utils.AST_NODE_TYPES.TSMethodSignature) return "method";
+	const { parent } = node;
+	if (parent.type === _typescript_eslint_utils.AST_NODE_TYPES.MethodDefinition || parent.type === _typescript_eslint_utils.AST_NODE_TYPES.TSAbstractMethodDefinition) return parent.kind === "constructor" ? "constructor" : "method";
+	if (parent.type === _typescript_eslint_utils.AST_NODE_TYPES.Property && parent.method) return "method";
+	return "function";
+}
+function getBlockBody(node) {
+	return "body" in node && node.body?.type === _typescript_eslint_utils.AST_NODE_TYPES.BlockStatement ? node.body : void 0;
+}
+const LIFTABLE_JSDOC_PARENTS = /* @__PURE__ */ new Set([
+	_typescript_eslint_utils.AST_NODE_TYPES.VariableDeclarator,
+	_typescript_eslint_utils.AST_NODE_TYPES.VariableDeclaration,
+	_typescript_eslint_utils.AST_NODE_TYPES.MethodDefinition,
+	_typescript_eslint_utils.AST_NODE_TYPES.TSAbstractMethodDefinition,
+	_typescript_eslint_utils.AST_NODE_TYPES.PropertyDefinition,
+	_typescript_eslint_utils.AST_NODE_TYPES.ExportNamedDeclaration,
+	_typescript_eslint_utils.AST_NODE_TYPES.ExportDefaultDeclaration
+]);
+function getLeadingJSDocComment(sourceCode, node) {
+	let current = node;
+	for (;;) {
+		const jsdocComment = sourceCode.getCommentsBefore(current).findLast((comment) => comment.type === _typescript_eslint_utils.AST_TOKEN_TYPES.Block && comment.value.startsWith("*"));
+		if (jsdocComment) return jsdocComment;
+		const { parent } = current;
+		if (parent === void 0 || !LIFTABLE_JSDOC_PARENTS.has(parent.type)) return void 0;
+		current = parent;
+	}
+}
+function jsDocMentionsParam(commentValue, name) {
+	const escapedName = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+	return new RegExp(`@param\\s+(?:\\{[^}]*\\}\\s+)?\\[?${escapedName}\\b`).test(commentValue);
+}
+function hasOptionsNameCollision(scope, exemptIdentifiers) {
+	return scope.variables.some((variable) => variable.name === "options" && !variable.identifiers.every((identifier) => exemptIdentifiers.has(identifier)));
+}
+const preferOptionsObjectParam = createRule$2({
+	name: "prefer-options-object-param",
+	meta: {
+		type: "suggestion",
+		hasSuggestions: true,
+		docs: { description: "Suggest bundling a run of 2+ trailing optional parameters into a single destructured 'options' parameter — without this, a caller needing only the last optional parameter must still pass 'undefined' for every optional parameter before it." },
+		schema: [{
+			type: "object",
+			properties: { minTrailingOptional: {
+				type: "integer",
+				minimum: 2
+			} },
+			additionalProperties: false
+		}],
+		messages: {
+			tooManyTrailingOptional: "This {{ kind }} has {{ count }} trailing optional parameters ({{ names }}) — a caller needing only the last one must still pass 'undefined' for every parameter before it. Bundle the trailing optional run into a single destructured 'options' parameter instead.",
+			wrapInOptionsObject: "Bundle the trailing optional parameters into a single 'options' parameter."
+		},
+		defaultOptions: [{ minTrailingOptional: 2 }]
+	},
+	create(context, [{ minTrailingOptional }]) {
+		const { sourceCode } = context;
+		function checkParams(node) {
+			const run = getTrailingOptionalRun(node.params);
+			if (run.length < minTrailingOptional) return;
+			const resolved = run.map(resolveFixableParam);
+			const names = run.map((param, index) => resolved[index]?.identifierNode.name ?? sourceCode.getText(param)).join(", ");
+			const data = {
+				kind: describeFunctionKind(node),
+				count: run.length,
+				names
+			};
+			const resolvedParams = resolved.filter(isDefined);
+			const allResolvable = resolvedParams.length === run.length;
+			const hasRestParam = node.params.some((param) => param.type === _typescript_eslint_utils.AST_NODE_TYPES.RestElement);
+			const body = getBlockBody(node);
+			let isFixable = allResolvable && !hasRestParam && body !== void 0;
+			if (isFixable) {
+				const jsdocComment = getLeadingJSDocComment(sourceCode, node);
+				const jsDocBail = jsdocComment !== void 0 && resolvedParams.some((info) => jsDocMentionsParam(jsdocComment.value, info.identifierNode.name));
+				const exemptIdentifiers = new Set(resolvedParams.map((info) => info.identifierNode));
+				const optionsCollision = hasOptionsNameCollision(sourceCode.getScope(node), exemptIdentifiers);
+				isFixable = !jsDocBail && !optionsCollision;
+			}
+			if (!isFixable || body === void 0) {
+				context.report({
+					node,
+					messageId: "tooManyTrailingOptional",
+					data
+				});
+				return;
+			}
+			context.report({
+				node,
+				messageId: "tooManyTrailingOptional",
+				data,
+				suggest: [{
+					messageId: "wrapInOptionsObject",
+					fix(fixer) {
+						const properties = resolvedParams.map((info) => `${info.identifierNode.name}?: ${sourceCode.getText(info.typeNode)}`);
+						const destructureEntries = resolvedParams.map((info) => info.defaultExpression === void 0 ? info.identifierNode.name : `${info.identifierNode.name} = ${sourceCode.getText(info.defaultExpression)}`);
+						const optionsParamText = `options?: { ${properties.join("; ")} }`;
+						const destructureText = `const { ${destructureEntries.join(", ")} } = options ?? {};`;
+						const [firstParam, lastParam] = firstAndLastOrThrow(run);
+						const openBrace = firstTokenOrThrow(sourceCode, body);
+						return [fixer.replaceTextRange([firstParam.range[0], lastParam.range[1]], optionsParamText), fixer.insertTextAfter(openBrace, `\n  ${destructureText}`)];
+					}
+				}]
+			});
+		}
+		return { [FUNCTION_LIKE_SELECTOR$2](node) {
+			checkParams(node);
+		} };
+	}
+});
+//#endregion
 //#region src/rules/prefer-readonly-array-param.ts
 const createRule$1 = _typescript_eslint_utils.ESLintUtils.RuleCreator((name) => `https://github.com/ExaDev/eslint-config/blob/main/src/rules/${name}.ts`);
 function getFixableArrayOrTupleType(typeNode) {
@@ -1904,6 +2082,7 @@ const plugin = {
 		"no-side-effects-in-index": noSideEffectsInIndex,
 		"package-json-key-order": packageJsonKeyOrder,
 		"prefer-numeric-sort-compare": preferNumericSortCompare,
+		"prefer-options-object-param": preferOptionsObjectParam,
 		"prefer-readonly-array-param": preferReadonlyArrayParam,
 		"prefer-readonly-object-param": preferReadonlyObjectParam,
 		"test-file-kind": {
@@ -1966,7 +2145,8 @@ const plugin = {
 					"exadev/no-object-assign": "error",
 					"exadev/no-pointless-reassignment": "error",
 					"exadev/prefer-readonly-array-param": "error",
-					"exadev/test-file-kind": "error"
+					"exadev/test-file-kind": "error",
+					"max-params": ["error", { max: 4 }]
 				}
 			};
 		},
@@ -2078,6 +2258,7 @@ const recommendedTypeChecked = [
 			"exadev/no-pointless-reassignment": "error",
 			"exadev/no-set-instanceof-mutation": "error",
 			"exadev/prefer-numeric-sort-compare": "error",
+			"exadev/prefer-options-object-param": "error",
 			"exadev/prefer-readonly-array-param": "error",
 			"exadev/prefer-readonly-object-param": "error",
 			"exadev/test-file-kind": "error",
@@ -2115,6 +2296,7 @@ const recommendedTypeChecked = [
 				skipBlankLines: true,
 				skipComments: true
 			}],
+			"max-params": ["error", { max: 4 }],
 			"no-warning-comments": ["error", {
 				terms: ["stryker disable"],
 				location: "anywhere"

package/dist/index.js

@@ -4,7 +4,7 @@ import jsdoc from "eslint-plugin-jsdoc";
 import tsdoc from "eslint-plugin-tsdoc";
 import jsonCanonical from "eslint-plugin-json-canonical";
 import { createRequire } from "node:module";
-import { AST_NODE_TYPES, ESLintUtils, TSESLint } from "@typescript-eslint/utils";
+import { AST_NODE_TYPES, AST_TOKEN_TYPES, ESLintUtils, TSESLint } from "@typescript-eslint/utils";
 import * as ts from "typescript";
 import { isPropertyReadonlyInType, isTypeReference } from "ts-api-utils";
 import js from "@eslint/js";
@@ -261,7 +261,7 @@ function buildNextjsConfig(options = {}) {
 }
 //#endregion
 //#region package.json
-var version = "2.19.4";
+var version = "2.20.0";
 //#endregion
 //#region src/react.ts
 const JSX_FILE_PATTERNS = ["**/*.jsx", "**/*.tsx"];
@@ -619,7 +619,7 @@ const MUTATING_INSERT_METHODS$1 = /* @__PURE__ */ new Set([
 	"fill",
 	"copyWithin"
 ]);
-const createRule$7 = ESLintUtils.RuleCreator((name) => `https://github.com/ExaDev/eslint-config/blob/main/src/rules/${name}.ts`);
+const createRule$8 = ESLintUtils.RuleCreator((name) => `https://github.com/ExaDev/eslint-config/blob/main/src/rules/${name}.ts`);
 function isArrayIsArrayCall(node) {
 	return node.type === AST_NODE_TYPES.CallExpression && node.callee.type === AST_NODE_TYPES.MemberExpression && !node.callee.computed && node.callee.object.type === AST_NODE_TYPES.Identifier && node.callee.object.name === "Array" && node.callee.property.type === AST_NODE_TYPES.Identifier && node.callee.property.name === "isArray";
 }
@@ -631,7 +631,7 @@ function definitelyExits$2(statement) {
 	}
 	return false;
 }
-const noArrayIsArrayMutation = createRule$7({
+const noArrayIsArrayMutation = createRule$8({
 	name: "no-array-isarray-mutation",
 	meta: {
 		type: "problem",
@@ -788,6 +788,11 @@ function lastTokenOrThrow(sourceCode, node) {
 	if (token === null) throw new Error("Unreachable: getLastToken returned null for a node expected to always have at least one token.");
 	return token;
 }
+function firstTokenOrThrow(sourceCode, node) {
+	const token = sourceCode.getFirstToken(node);
+	if (token === null) throw new Error("Unreachable: getFirstToken returned null for a node expected to always have at least one token.");
+	return token;
+}
 //#endregion
 //#region src/rules/no-enum-number-widening.ts
 const noEnumNumberWidening = ESLintUtils.RuleCreator((name) => `https://github.com/ExaDev/eslint-config/blob/main/src/rules/${name}.ts`)({
@@ -910,7 +915,7 @@ const noIndexFiles = {
 };
 //#endregion
 //#region src/rules/no-map-instanceof-mutation.ts
-const createRule$6 = ESLintUtils.RuleCreator((name) => `https://github.com/ExaDev/eslint-config/blob/main/src/rules/${name}.ts`);
+const createRule$7 = ESLintUtils.RuleCreator((name) => `https://github.com/ExaDev/eslint-config/blob/main/src/rules/${name}.ts`);
 const MUTATING_MAP_METHODS = /* @__PURE__ */ new Set([
 	"set",
 	"delete",
@@ -927,7 +932,7 @@ function definitelyExits$1(statement) {
 	}
 	return false;
 }
-const noMapInstanceofMutation = createRule$6({
+const noMapInstanceofMutation = createRule$7({
 	name: "no-map-instanceof-mutation",
 	meta: {
 		type: "problem",
@@ -1008,7 +1013,7 @@ const MUTATING_INSERT_METHODS = /* @__PURE__ */ new Set([
 	"fill",
 	"copyWithin"
 ]);
-const createRule$5 = ESLintUtils.RuleCreator((name) => `https://github.com/ExaDev/eslint-config/blob/main/src/rules/${name}.ts`);
+const createRule$6 = ESLintUtils.RuleCreator((name) => `https://github.com/ExaDev/eslint-config/blob/main/src/rules/${name}.ts`);
 function buildReadonlyArrayFix(annotated, fixer) {
 	if (annotated.type === AST_NODE_TYPES.TSArrayType) return fixer.insertTextBefore(annotated, "readonly ");
 	if (annotated.type !== AST_NODE_TYPES.TSTypeReference) throw new Error(`Unreachable: expected a TSArrayType or TSTypeReference, got ${annotated.type} instead.`);
@@ -1021,7 +1026,7 @@ function isUnionArrayType(typeAnnotation) {
 		if (firstParam?.type === AST_NODE_TYPES.TSUnionType) return firstParam;
 	}
 }
-const noMutableUnionArrayParam = createRule$5({
+const noMutableUnionArrayParam = createRule$6({
 	name: "no-mutable-union-array-param",
 	meta: {
 		type: "problem",
@@ -1074,7 +1079,7 @@ const noNonBarrelIndex = {
 };
 //#endregion
 //#region src/rules/no-non-barrel-reexport.ts
-function removeListMember(fixer, sourceCode, declaration, members, target) {
+function removeListMember({ fixer, sourceCode }, declaration, members, target) {
 	if (members.length === 1) return fixer.remove(declaration);
 	const targetIndex = members.indexOf(target);
 	const isLast = targetIndex === members.length - 1;
@@ -1122,8 +1127,14 @@ const noNonBarrelReexport = {
 						messageId: "splitStatementReexport",
 						data: { name },
 						fix(fixer) {
-							const fixes = [removeListMember(fixer, sourceCode, declaration, declaration.specifiers, specifier)];
-							if (specifier.local.type === "Identifier" && importIsOnlyUsedByThisExport(sourceCode, trackedImport, specifier.local)) fixes.push(removeListMember(fixer, sourceCode, trackedImport.declaration, trackedImport.declaration.specifiers, trackedImport.specifier));
+							const fixes = [removeListMember({
+								fixer,
+								sourceCode
+							}, declaration, declaration.specifiers, specifier)];
+							if (specifier.local.type === "Identifier" && importIsOnlyUsedByThisExport(sourceCode, trackedImport, specifier.local)) fixes.push(removeListMember({
+								fixer,
+								sourceCode
+							}, trackedImport.declaration, trackedImport.declaration.specifiers, trackedImport.specifier));
 							return fixes;
 						}
 					});
@@ -1135,7 +1146,10 @@ const noNonBarrelReexport = {
 						data: { name },
 						fix(fixer) {
 							const fixes = [fixer.remove(declaration)];
-							if (importIsOnlyUsedByThisExport(sourceCode, trackedImport, identifierNode)) fixes.push(removeListMember(fixer, sourceCode, trackedImport.declaration, trackedImport.declaration.specifiers, trackedImport.specifier));
+							if (importIsOnlyUsedByThisExport(sourceCode, trackedImport, identifierNode)) fixes.push(removeListMember({
+								fixer,
+								sourceCode
+							}, trackedImport.declaration, trackedImport.declaration.specifiers, trackedImport.specifier));
 							return fixes;
 						}
 					});
@@ -1146,14 +1160,14 @@ const noNonBarrelReexport = {
 };
 //#endregion
 //#region src/rules/no-object-assign.ts
-const createRule$4 = ESLintUtils.RuleCreator((name) => `https://github.com/ExaDev/eslint-config/blob/main/src/rules/${name}.ts`);
+const createRule$5 = ESLintUtils.RuleCreator((name) => `https://github.com/ExaDev/eslint-config/blob/main/src/rules/${name}.ts`);
 function resolveFrom$1(scope, name) {
 	for (let current = scope; current; current = current.upper) {
 		const found = current.set.get(name);
 		if (found) return found;
 	}
 }
-const noObjectAssign = createRule$4({
+const noObjectAssign = createRule$5({
 	name: "no-object-assign",
 	meta: {
 		type: "problem",
@@ -1299,7 +1313,7 @@ const MUTATING_SET_METHODS = /* @__PURE__ */ new Set([
 	"delete",
 	"clear"
 ]);
-const createRule$3 = ESLintUtils.RuleCreator((name) => `https://github.com/ExaDev/eslint-config/blob/main/src/rules/${name}.ts`);
+const createRule$4 = ESLintUtils.RuleCreator((name) => `https://github.com/ExaDev/eslint-config/blob/main/src/rules/${name}.ts`);
 function isSetInstanceofExpression(node) {
 	return node.type === AST_NODE_TYPES.BinaryExpression && node.operator === "instanceof" && node.right.type === AST_NODE_TYPES.Identifier && node.right.name === "Set";
 }
@@ -1311,7 +1325,7 @@ function definitelyExits(statement) {
 	}
 	return false;
 }
-const noSetInstanceofMutation = createRule$3({
+const noSetInstanceofMutation = createRule$4({
 	name: "no-set-instanceof-mutation",
 	meta: {
 		type: "problem",
@@ -1605,13 +1619,13 @@ const packageJsonKeyOrder = {
 };
 //#endregion
 //#region src/rules/prefer-numeric-sort-compare.ts
-const createRule$2 = ESLintUtils.RuleCreator((name) => `https://github.com/ExaDev/eslint-config/blob/main/src/rules/${name}.ts`);
+const createRule$3 = ESLintUtils.RuleCreator((name) => `https://github.com/ExaDev/eslint-config/blob/main/src/rules/${name}.ts`);
 const SORT_METHOD_NAMES = /* @__PURE__ */ new Set(["sort", "toSorted"]);
 function isDefinitelyNumberType(type) {
 	if (type.isUnion()) return type.types.every((constituent) => isDefinitelyNumberType(constituent));
 	return (type.flags & ts.TypeFlags.NumberLike) !== 0;
 }
-const preferNumericSortCompare = createRule$2({
+const preferNumericSortCompare = createRule$3({
 	name: "prefer-numeric-sort-compare",
 	meta: {
 		type: "suggestion",
@@ -1653,6 +1667,170 @@ const preferNumericSortCompare = createRule$2({
 	}
 });
 //#endregion
+//#region src/rules/prefer-options-object-param.ts
+const createRule$2 = ESLintUtils.RuleCreator((name) => `https://github.com/ExaDev/eslint-config/blob/main/src/rules/${name}.ts`);
+const FUNCTION_LIKE_SELECTOR$2 = [
+	"ArrowFunctionExpression",
+	"FunctionDeclaration",
+	"FunctionExpression",
+	"TSCallSignatureDeclaration",
+	"TSConstructSignatureDeclaration",
+	"TSDeclareFunction",
+	"TSEmptyBodyFunctionExpression",
+	"TSFunctionType",
+	"TSMethodSignature"
+].join(", ");
+function isOptionalParam(param) {
+	if (param.type === AST_NODE_TYPES.TSParameterProperty) return isOptionalParam(param.parameter);
+	if (param.type === AST_NODE_TYPES.AssignmentPattern) return true;
+	if (param.type === AST_NODE_TYPES.Identifier) return param.optional;
+	return false;
+}
+function getTrailingOptionalRun(params) {
+	const hasTrailingRest = params.length > 0 && params[params.length - 1]?.type === AST_NODE_TYPES.RestElement;
+	const run = [];
+	for (let i = params.length - (hasTrailingRest ? 2 : 1); i >= 0; i--) {
+		const param = params[i];
+		if (param === void 0 || !isOptionalParam(param)) break;
+		run.unshift(param);
+	}
+	return run;
+}
+function resolveFixableParam(param) {
+	if (param.type === AST_NODE_TYPES.TSParameterProperty) return void 0;
+	const identifierNode = param.type === AST_NODE_TYPES.AssignmentPattern ? param.left.type === AST_NODE_TYPES.Identifier ? param.left : void 0 : param.type === AST_NODE_TYPES.Identifier ? param : void 0;
+	if (identifierNode === void 0) return void 0;
+	const typeNode = identifierNode.typeAnnotation?.typeAnnotation;
+	if (typeNode === void 0) return void 0;
+	if (identifierNode.decorators.length > 0) return void 0;
+	return {
+		identifierNode,
+		typeNode,
+		defaultExpression: param.type === AST_NODE_TYPES.AssignmentPattern ? param.right : void 0
+	};
+}
+function isDefined(value) {
+	return value !== void 0;
+}
+function firstAndLastOrThrow(items) {
+	const first = items[0];
+	const last = items.at(-1);
+	if (first === void 0 || last === void 0) throw new Error("Unreachable: expected at least one element (the caller already confirmed a minimum run length).");
+	return [first, last];
+}
+function describeFunctionKind(node) {
+	if (node.type === AST_NODE_TYPES.TSConstructSignatureDeclaration) return "constructor";
+	if (node.type === AST_NODE_TYPES.TSMethodSignature) return "method";
+	const { parent } = node;
+	if (parent.type === AST_NODE_TYPES.MethodDefinition || parent.type === AST_NODE_TYPES.TSAbstractMethodDefinition) return parent.kind === "constructor" ? "constructor" : "method";
+	if (parent.type === AST_NODE_TYPES.Property && parent.method) return "method";
+	return "function";
+}
+function getBlockBody(node) {
+	return "body" in node && node.body?.type === AST_NODE_TYPES.BlockStatement ? node.body : void 0;
+}
+const LIFTABLE_JSDOC_PARENTS = /* @__PURE__ */ new Set([
+	AST_NODE_TYPES.VariableDeclarator,
+	AST_NODE_TYPES.VariableDeclaration,
+	AST_NODE_TYPES.MethodDefinition,
+	AST_NODE_TYPES.TSAbstractMethodDefinition,
+	AST_NODE_TYPES.PropertyDefinition,
+	AST_NODE_TYPES.ExportNamedDeclaration,
+	AST_NODE_TYPES.ExportDefaultDeclaration
+]);
+function getLeadingJSDocComment(sourceCode, node) {
+	let current = node;
+	for (;;) {
+		const jsdocComment = sourceCode.getCommentsBefore(current).findLast((comment) => comment.type === AST_TOKEN_TYPES.Block && comment.value.startsWith("*"));
+		if (jsdocComment) return jsdocComment;
+		const { parent } = current;
+		if (parent === void 0 || !LIFTABLE_JSDOC_PARENTS.has(parent.type)) return void 0;
+		current = parent;
+	}
+}
+function jsDocMentionsParam(commentValue, name) {
+	const escapedName = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+	return new RegExp(`@param\\s+(?:\\{[^}]*\\}\\s+)?\\[?${escapedName}\\b`).test(commentValue);
+}
+function hasOptionsNameCollision(scope, exemptIdentifiers) {
+	return scope.variables.some((variable) => variable.name === "options" && !variable.identifiers.every((identifier) => exemptIdentifiers.has(identifier)));
+}
+const preferOptionsObjectParam = createRule$2({
+	name: "prefer-options-object-param",
+	meta: {
+		type: "suggestion",
+		hasSuggestions: true,
+		docs: { description: "Suggest bundling a run of 2+ trailing optional parameters into a single destructured 'options' parameter — without this, a caller needing only the last optional parameter must still pass 'undefined' for every optional parameter before it." },
+		schema: [{
+			type: "object",
+			properties: { minTrailingOptional: {
+				type: "integer",
+				minimum: 2
+			} },
+			additionalProperties: false
+		}],
+		messages: {
+			tooManyTrailingOptional: "This {{ kind }} has {{ count }} trailing optional parameters ({{ names }}) — a caller needing only the last one must still pass 'undefined' for every parameter before it. Bundle the trailing optional run into a single destructured 'options' parameter instead.",
+			wrapInOptionsObject: "Bundle the trailing optional parameters into a single 'options' parameter."
+		},
+		defaultOptions: [{ minTrailingOptional: 2 }]
+	},
+	create(context, [{ minTrailingOptional }]) {
+		const { sourceCode } = context;
+		function checkParams(node) {
+			const run = getTrailingOptionalRun(node.params);
+			if (run.length < minTrailingOptional) return;
+			const resolved = run.map(resolveFixableParam);
+			const names = run.map((param, index) => resolved[index]?.identifierNode.name ?? sourceCode.getText(param)).join(", ");
+			const data = {
+				kind: describeFunctionKind(node),
+				count: run.length,
+				names
+			};
+			const resolvedParams = resolved.filter(isDefined);
+			const allResolvable = resolvedParams.length === run.length;
+			const hasRestParam = node.params.some((param) => param.type === AST_NODE_TYPES.RestElement);
+			const body = getBlockBody(node);
+			let isFixable = allResolvable && !hasRestParam && body !== void 0;
+			if (isFixable) {
+				const jsdocComment = getLeadingJSDocComment(sourceCode, node);
+				const jsDocBail = jsdocComment !== void 0 && resolvedParams.some((info) => jsDocMentionsParam(jsdocComment.value, info.identifierNode.name));
+				const exemptIdentifiers = new Set(resolvedParams.map((info) => info.identifierNode));
+				const optionsCollision = hasOptionsNameCollision(sourceCode.getScope(node), exemptIdentifiers);
+				isFixable = !jsDocBail && !optionsCollision;
+			}
+			if (!isFixable || body === void 0) {
+				context.report({
+					node,
+					messageId: "tooManyTrailingOptional",
+					data
+				});
+				return;
+			}
+			context.report({
+				node,
+				messageId: "tooManyTrailingOptional",
+				data,
+				suggest: [{
+					messageId: "wrapInOptionsObject",
+					fix(fixer) {
+						const properties = resolvedParams.map((info) => `${info.identifierNode.name}?: ${sourceCode.getText(info.typeNode)}`);
+						const destructureEntries = resolvedParams.map((info) => info.defaultExpression === void 0 ? info.identifierNode.name : `${info.identifierNode.name} = ${sourceCode.getText(info.defaultExpression)}`);
+						const optionsParamText = `options?: { ${properties.join("; ")} }`;
+						const destructureText = `const { ${destructureEntries.join(", ")} } = options ?? {};`;
+						const [firstParam, lastParam] = firstAndLastOrThrow(run);
+						const openBrace = firstTokenOrThrow(sourceCode, body);
+						return [fixer.replaceTextRange([firstParam.range[0], lastParam.range[1]], optionsParamText), fixer.insertTextAfter(openBrace, `\n  ${destructureText}`)];
+					}
+				}]
+			});
+		}
+		return { [FUNCTION_LIKE_SELECTOR$2](node) {
+			checkParams(node);
+		} };
+	}
+});
+//#endregion
 //#region src/rules/prefer-readonly-array-param.ts
 const createRule$1 = ESLintUtils.RuleCreator((name) => `https://github.com/ExaDev/eslint-config/blob/main/src/rules/${name}.ts`);
 function getFixableArrayOrTupleType(typeNode) {
@@ -1870,6 +2048,7 @@ const plugin = {
 		"no-side-effects-in-index": noSideEffectsInIndex,
 		"package-json-key-order": packageJsonKeyOrder,
 		"prefer-numeric-sort-compare": preferNumericSortCompare,
+		"prefer-options-object-param": preferOptionsObjectParam,
 		"prefer-readonly-array-param": preferReadonlyArrayParam,
 		"prefer-readonly-object-param": preferReadonlyObjectParam,
 		"test-file-kind": {
@@ -1932,7 +2111,8 @@ const plugin = {
 					"exadev/no-object-assign": "error",
 					"exadev/no-pointless-reassignment": "error",
 					"exadev/prefer-readonly-array-param": "error",
-					"exadev/test-file-kind": "error"
+					"exadev/test-file-kind": "error",
+					"max-params": ["error", { max: 4 }]
 				}
 			};
 		},
@@ -2044,6 +2224,7 @@ const recommendedTypeChecked = [
 			"exadev/no-pointless-reassignment": "error",
 			"exadev/no-set-instanceof-mutation": "error",
 			"exadev/prefer-numeric-sort-compare": "error",
+			"exadev/prefer-options-object-param": "error",
 			"exadev/prefer-readonly-array-param": "error",
 			"exadev/prefer-readonly-object-param": "error",
 			"exadev/test-file-kind": "error",
@@ -2081,6 +2262,7 @@ const recommendedTypeChecked = [
 				skipBlankLines: true,
 				skipComments: true
 			}],
+			"max-params": ["error", { max: 4 }],
 			"no-warning-comments": ["error", {
 				terms: ["stryker disable"],
 				location: "anywhere"

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "exadev-eslint-config",
   "description": "Shared custom ESLint rules and plugin for ExaDev projects",
-  "version": "2.19.4",
+  "version": "2.20.0",
   "dependencies": {
     "@eslint/js": "^10.0.1",
     "@typescript-eslint/utils": "8.67.0",