consistent-boolean-name: Add wrappers option (#3572)

Author: sindresorhus

docs/rules/consistent-boolean-name.md

@@ -15,6 +15,8 @@ Boolean names should start with a prefix that makes the boolean meaning clear.
 
 Names that start with a boolean prefix should also refer to booleans or boolean-returning functions. Unknown values are ignored.
 
+Configured wrapper bindings may use boolean prefixes when a configured property or method provides a boolean-like value. This applies only to variables and parameters that are not reassigned.
+
 Reports for property and method names, and reports for non-boolean values using boolean prefixes, do not provide rename suggestions.
 
 The default prefixes are:
@@ -231,6 +233,44 @@ And this would fail:
 const didUpdate = true;
 ```
 
+### wrappers
+
+Type: `Record<string, string>`\
+Default: `{}`
+
+Map unqualified TypeScript wrapper type names to the property or method that provides a boolean-like value. Same-named types share configuration. Derived types, intersections, and constrained type parameters are supported. Members may provide `boolean`, `Promise<boolean>`, or `PromiseLike<boolean>`; nullable results are accepted. Requires TypeScript type information.
+
+```js
+'unicorn/consistent-boolean-name': [
+	'error',
+	{
+		wrappers: {
+			StorageItem: 'get',
+		},
+	},
+]
+```
+
+With the above configuration, this would pass:
+
+```ts
+interface StorageItem<Base, Return = Base | undefined> {
+	get(): Promise<Return>;
+}
+
+declare const isUnicorn: StorageItem<unknown, boolean>;
+```
+
+But this would still fail because `get()` returns a string:
+
+```ts
+interface StorageItem<Base, Return = Base | undefined> {
+	get(): Promise<Return>;
+}
+
+declare const isUnicorn: StorageItem<unknown, string>;
+```
+
 ### ignore
 
 Type: `Array<string | RegExp>`\

rules/consistent-boolean-name.js

@@ -1,15 +1,14 @@
 import {isRegExp} from 'node:util/types';
 import {findVariable, getPropertyName, getStaticValue} from '@eslint-community/eslint-utils';
 import {renameVariable} from './fix/index.js';
+import {combineBooleanStates, getPromisedTypeBooleanState, getTypeBooleanState} from './utils/get-type-boolean-state.js';
 import resolveVariableName from './utils/resolve-variable-name.js';
+import {getBooleanWrapperVariableState} from './utils/get-boolean-wrapper-variable-state.js';
 import {
 	getAvailableVariableName,
 	getScopes,
 	getVariableIdentifiers,
 	isReactHookName,
-	isNullishType,
-	isTypeParameterType,
-	isUnknownType,
 	lowerFirst,
 	upperFirst,
 } from './utils/index.js';
@@ -145,10 +144,12 @@ const prepareOptions = ({
 	checkProperties = false,
 	prefixes = {},
 	ignore = [],
+	wrappers = {},
 } = {}) => ({
 	checkProperties,
 	prefixes: getEnabledPrefixes({prefixes}),
 	ignore: ignore.map(pattern => isRegExp(pattern) ? pattern : new RegExp(pattern, 'u')),
+	wrappers: new Map(Object.entries(wrappers)),
 });
 
 function isIgnoredName(name, ignore) {
@@ -430,17 +431,6 @@ function isBooleanVueReferenceVariable(variable, context) {
 		&& getExpressionBooleanState(argument, context) === boolean;
 }
 
-function combineBooleanStates(states) {
-	if (
-		states.length === 0
-		|| states.includes(unknown)
-	) {
-		return unknown;
-	}
-
-	return states.every(state => state === boolean) ? boolean : nonBoolean;
-}
-
 function combineVariableBooleanStates(states) {
 	if (states.includes(nonBoolean)) {
 		return nonBoolean;
@@ -449,75 +439,6 @@ function combineVariableBooleanStates(states) {
 	return combineBooleanStates(states);
 }
 
-function getTypeBooleanState(type, checker, visitedTypes = new Set(), functionTypesAreBoolean = true) {
-	if (!type) {
-		return unknown;
-	}
-
-	if (
-		isUnknownType(type)
-		|| type.intrinsicName === 'never'
-	) {
-		return unknown;
-	}
-
-	if (visitedTypes.has(type)) {
-		return unknown;
-	}
-
-	visitedTypes.add(type);
-
-	if (isTypeParameterType(type)) {
-		const constraint = type.getConstraint();
-		const result = constraint ? getTypeBooleanState(constraint, checker, visitedTypes, functionTypesAreBoolean) : unknown;
-		visitedTypes.delete(type);
-		return result;
-	}
-
-	const nonNullableType = checker.getNonNullableType(type);
-	if (nonNullableType !== type) {
-		const result = getTypeBooleanState(nonNullableType, checker, visitedTypes, functionTypesAreBoolean);
-		visitedTypes.delete(type);
-		return result;
-	}
-
-	if (type.isUnion()) {
-		const result = combineBooleanStates(
-			type.types
-				.filter(type => !isNullishType(type))
-				.map(type => getTypeBooleanState(type, checker, visitedTypes, functionTypesAreBoolean)),
-		);
-		visitedTypes.delete(type);
-		return result;
-	}
-
-	const signatures = type.getCallSignatures();
-	if (signatures.length > 0) {
-		const result = functionTypesAreBoolean
-			? combineBooleanStates(signatures.map(signature => getTypeBooleanState(signature.getReturnType(), checker, visitedTypes, false)))
-			: nonBoolean;
-		visitedTypes.delete(type);
-		return result;
-	}
-
-	const constraint = checker.getBaseConstraintOfType(type);
-	if (constraint && constraint !== type) {
-		const result = getTypeBooleanState(constraint, checker, visitedTypes, functionTypesAreBoolean);
-		visitedTypes.delete(type);
-		return result;
-	}
-
-	if (type.getProperties().length === 0) {
-		visitedTypes.delete(type);
-		return unknown;
-	}
-
-	const typeString = checker.typeToString(checker.getWidenedType(checker.getBaseTypeOfLiteralType(type)));
-	visitedTypes.delete(type);
-
-	return typeString === 'boolean' ? boolean : nonBoolean;
-}
-
 function getTypeInformationBooleanState(node, context, functionTypesAreBoolean = true) {
 	const {parserServices} = context.sourceCode;
 	if (!parserServices?.program) {
@@ -718,11 +639,6 @@ function isGlobalPromiseTypeAnnotation(node, scope) {
 	return isGlobalPromiseTypeReference(node, scope);
 }
 
-function getPromisedTypeBooleanState(type, checker) {
-	const promisedType = checker.getPromisedTypeOfPromise(type);
-	return promisedType ? getTypeBooleanState(promisedType, checker, new Set(), false) : unknown;
-}
-
 function getAsyncFunctionTypeInformationBooleanState(node, context) {
 	const {parserServices} = context.sourceCode;
 	if (!parserServices?.program) {
@@ -1283,7 +1199,7 @@ function getAutofix({
 
 /** @param {import('eslint').Rule.RuleContext} context */
 const create = context => {
-	const {checkProperties, prefixes, ignore} = prepareOptions(context.options[0]);
+	const {checkProperties, prefixes, ignore, wrappers} = prepareOptions(context.options[0]);
 
 	if (prefixes.length === 0) {
 		return;
@@ -1300,8 +1216,18 @@ const create = context => {
 		const nameForPrefixCheck = getNameForPrefixCheck(variable, context);
 		const booleanPrefix = getBooleanPrefix(nameForPrefixCheck, prefixes);
 		if (booleanPrefix) {
+			const booleanState = getVariableBooleanState(variable, context);
+			const booleanWrapperState = wrappers.size === 0 || booleanState === boolean
+				? unknown
+				: getBooleanWrapperVariableState({
+					variable,
+					definition: getSupportedVariableDefinition(variable),
+					context,
+					wrappers,
+				});
+			const effectiveBooleanState = booleanWrapperState === unknown ? booleanState : booleanWrapperState;
 			if (
-				getVariableBooleanState(variable, context) === nonBoolean
+				effectiveBooleanState === nonBoolean
 				&& !isBooleanReactReferenceVariable(variable, context)
 				&& !isBooleanVueReferenceVariable(variable, context)
 			) {
@@ -1452,6 +1378,15 @@ const config = {
 							pattern: '^[a-z][a-zA-Z0-9]*$',
 						},
 					},
+					wrappers: {
+						type: 'object',
+						description: 'Wrapper type names and their boolean-like value members.',
+						additionalProperties: {
+							type: 'string',
+							description: 'The property or method that provides the wrapped value.',
+							minLength: 1,
+						},
+					},
 					ignore: {
 						type: 'array',
 						uniqueItems: true,
@@ -1460,7 +1395,7 @@ const config = {
 				},
 			},
 		],
-		defaultOptions: [{ignore: []}],
+		defaultOptions: [{ignore: [], wrappers: {}}],
 		messages,
 		languages: [
 			'js/js',

rules/utils/get-boolean-wrapper-variable-state.js

@@ -0,0 +1,148 @@
+import {combineBooleanStates, getPromisedTypeBooleanState, getTypeBooleanState} from './get-type-boolean-state.js';
+import {getBaseTypes, isTypeParameterType} from './types.js';
+
+const boolean = 'boolean';
+const nonBoolean = 'non-boolean';
+const unknown = 'unknown';
+
+// ObjectFlags.Mapped from TypeScript.
+const mappedTypeFlag = 32;
+
+const isMappedType = type => (type.objectFlags % (mappedTypeFlag * 2)) >= mappedTypeFlag;
+
+function getConfiguredMemberName(type, checker, wrappers, visitedTypes = new Set()) {
+	if (!type) {
+		return;
+	}
+
+	const nonNullableType = checker.getNonNullableType(type);
+	if (nonNullableType !== type) {
+		return getConfiguredMemberName(nonNullableType, checker, wrappers, visitedTypes);
+	}
+
+	if (visitedTypes.has(type)) {
+		return;
+	}
+
+	visitedTypes.add(type);
+
+	const typeNames = [
+		type.symbol?.name,
+		type.aliasSymbol?.name,
+		type.target?.symbol?.name,
+	];
+	const memberName = typeNames
+		.map(typeName => wrappers.get(typeName))
+		.find(Boolean);
+	if (memberName) {
+		return memberName;
+	}
+
+	if (isTypeParameterType(type)) {
+		return getConfiguredMemberName(type.getConstraint(), checker, wrappers, visitedTypes);
+	}
+
+	if (type.isIntersection()) {
+		for (const constituentType of type.types) {
+			const memberName = getConfiguredMemberName(constituentType, checker, wrappers, visitedTypes);
+			if (memberName) {
+				return memberName;
+			}
+		}
+	}
+
+	if (isMappedType(type)) {
+		for (const typeArgument of type.aliasTypeArguments ?? []) {
+			const memberName = getConfiguredMemberName(typeArgument, checker, wrappers, visitedTypes);
+			if (memberName) {
+				return memberName;
+			}
+		}
+	}
+
+	for (const baseType of getBaseTypes(type, checker)) {
+		const memberName = getConfiguredMemberName(baseType, checker, wrappers, visitedTypes);
+		if (memberName) {
+			return memberName;
+		}
+	}
+}
+
+function getBooleanValueState(type, checker) {
+	const nonNullableType = checker.getNonNullableType(type);
+	const typeState = getTypeBooleanState(nonNullableType, checker, new Set(), false);
+	const promisedTypeState = getPromisedTypeBooleanState(nonNullableType, checker);
+
+	if (typeState === boolean || promisedTypeState === boolean) {
+		return boolean;
+	}
+
+	return typeState === nonBoolean || promisedTypeState === nonBoolean ? nonBoolean : unknown;
+}
+
+function getBooleanWrapperMemberState(type, memberName, checker) {
+	const member = checker.getPropertyOfType(type, memberName);
+	if (!member) {
+		return nonBoolean;
+	}
+
+	const memberType = checker.getTypeOfPropertyOfType(type, memberName);
+	if (!memberType) {
+		return nonBoolean;
+	}
+
+	const signatures = memberType.getCallSignatures();
+	return signatures.length > 0
+		? combineBooleanStates(signatures.map(signature => getBooleanValueState(signature.getReturnType(), checker)))
+		: getBooleanValueState(memberType, checker);
+}
+
+function getBooleanWrapperTypeState(type, checker, wrappers) {
+	if (!type) {
+		return unknown;
+	}
+
+	const nonNullableType = checker.getNonNullableType(type);
+	if (nonNullableType !== type) {
+		return getBooleanWrapperTypeState(nonNullableType, checker, wrappers);
+	}
+
+	if (type.isUnion()) {
+		return combineBooleanStates(type.types.map(type => getBooleanWrapperTypeState(type, checker, wrappers)));
+	}
+
+	const memberName = getConfiguredMemberName(type, checker, wrappers);
+	if (!memberName) {
+		return unknown;
+	}
+
+	return getBooleanWrapperMemberState(type, memberName, checker);
+}
+
+function getBooleanWrapperVariableState({variable, definition, context, wrappers}) {
+	if (
+		wrappers.size === 0
+		|| !definition
+		|| !['Variable', 'Parameter'].includes(definition.type)
+		|| variable.references.some(reference => !reference.init && reference.isWrite())
+	) {
+		return unknown;
+	}
+
+	const {parserServices} = context.sourceCode;
+	if (!parserServices?.program) {
+		return unknown;
+	}
+
+	try {
+		return getBooleanWrapperTypeState(
+			parserServices.getTypeAtLocation(definition.name),
+			parserServices.program.getTypeChecker(),
+			wrappers,
+		);
+	} catch {
+		return unknown;
+	}
+}
+
+export {getBooleanWrapperVariableState};