feat(eslint-plugin): [strict-boolean-expressions] check array predicate functions' return statements (typescript-eslint#10106)

* initial implementation

* tests

* refactor

* some more tests

* update docs

* update snapshots

* handle implicit or explicit undefined return types

* refactor and update tests

* remove unnecessary union check

* inline check

* cover empty return staetments

* report a function as returning undefined only if no other isssues were found

* update comments

* add test

* remove unnecessary test

* update code to match function's inferred return type rather than each return statement individually

* update tests to match the implementation changes

* adjust suggestion message

* final adjustments

* final adjustments #2

* test additions

* update snapshots

* Update packages/eslint-plugin/docs/rules/strict-boolean-expressions.mdx

Co-authored-by: Kirk Waiblinger <[email protected]>

* initial implementation of deducing the correct signature for non-function-expressions

* comments

* take type constraints into consideration

* only check type constraints on type parameters

* update tests

* update index tests

* update snapshot

* simplify code a bit

* remove overly complex heuristic

* use an existing helper rather than implementing one

* update tests

* Update packages/eslint-plugin/src/rules/strict-boolean-expressions.ts

Co-authored-by: Kirk Waiblinger <[email protected]>

* fix codecov

* cleanup old code, support type constraints

* refactor fixer

* remove unnecessary tests

* revert changes to isParenlessArrowFunction

* oops

---------

Co-authored-by: Kirk Waiblinger <[email protected]>

Author: ronami

packages/eslint-plugin/docs/rules/strict-boolean-expressions.mdx

@@ -22,6 +22,7 @@ The following nodes are considered boolean expressions and their type is checked
   - Right-hand side operand is ignored when it's not a descendant of another boolean expression.
     This is to allow usage of boolean operators for their short-circuiting behavior.
 - Asserted argument of an assertion function (`assert(arg)`).
+- Return type of array predicate functions such as `filter()`, `some()`, etc.
 
 ## Examples
 
@@ -61,6 +62,9 @@ while (obj) {
 declare function assert(value: unknown): asserts value;
 let maybeString = Math.random() > 0.5 ? '' : undefined;
 assert(maybeString);
+
+// array predicates' return types are boolean contexts.
+['one', null].filter(x => x);
 ```
 
 </TabItem>

packages/eslint-plugin/src/rules/strict-boolean-expressions.ts

@@ -3,7 +3,7 @@ import type {
   TSESTree,
 } from '@typescript-eslint/utils';
 
-import { AST_NODE_TYPES } from '@typescript-eslint/utils';
+import { AST_NODE_TYPES, ASTUtils } from '@typescript-eslint/utils';
 import * as tsutils from 'ts-api-utils';
 import * as ts from 'typescript';
 
@@ -12,7 +12,10 @@ import {
   getConstrainedTypeAtLocation,
   getParserServices,
   getWrappingFixer,
+  isArrayMethodCallWithPredicate,
+  isParenlessArrowFunction,
   isTypeArrayTypeOrUnionOfArrayTypes,
+  nullThrows,
 } from '../util';
 import { findTruthinessAssertedArgument } from '../util/assertionFunctionUtils';
 
@@ -53,7 +56,10 @@ export type MessageId =
   | 'conditionFixDefaultEmptyString'
   | 'conditionFixDefaultFalse'
   | 'conditionFixDefaultZero'
-  | 'noStrictNullCheck';
+  | 'explicitBooleanReturnType'
+  | 'noStrictNullCheck'
+  | 'predicateCannotBeAsync'
+  | 'predicateReturnsNonBoolean';
 
 export default createRule<Options, MessageId>({
   name: 'strict-boolean-expressions',
@@ -122,8 +128,13 @@ export default createRule<Options, MessageId>({
         'Explicitly treat nullish value the same as false (`value ?? false`)',
       conditionFixDefaultZero:
         'Explicitly treat nullish value the same as 0 (`value ?? 0`)',
+      explicitBooleanReturnType:
+        'Add an explicit `boolean` return type annotation.',
       noStrictNullCheck:
         'This rule requires the `strictNullChecks` compiler option to be turned on to function correctly.',
+      predicateCannotBeAsync:
+        "Predicate function should not be 'async'; expected a boolean return type.",
+      predicateReturnsNonBoolean: 'Predicate function should return a boolean.',
     },
     schema: [
       {
@@ -275,6 +286,104 @@ export default createRule<Options, MessageId>({
       if (assertedArgument != null) {
         traverseNode(assertedArgument, true);
       }
+      if (isArrayMethodCallWithPredicate(context, services, node)) {
+        const predicate = node.arguments.at(0);
+
+        if (predicate) {
+          checkArrayMethodCallPredicate(predicate);
+        }
+      }
+    }
+
+    /**
+     * Dedicated function to check array method predicate calls. Reports predicate
+     * arguments that don't return a boolean value.
+     *
+     * Ignores the `allow*` options and requires a boolean value.
+     */
+    function checkArrayMethodCallPredicate(
+      predicateNode: TSESTree.CallExpressionArgument,
+    ): void {
+      const isFunctionExpression = ASTUtils.isFunction(predicateNode);
+
+      // custom message for accidental `async` function expressions
+      if (isFunctionExpression && predicateNode.async) {
+        return context.report({
+          node: predicateNode,
+          messageId: 'predicateCannotBeAsync',
+        });
+      }
+
+      const returnTypes = services
+        .getTypeAtLocation(predicateNode)
+        .getCallSignatures()
+        .map(signature => {
+          const type = signature.getReturnType();
+
+          if (tsutils.isTypeParameter(type)) {
+            return checker.getBaseConstraintOfType(type) ?? type;
+          }
+
+          return type;
+        });
+
+      if (returnTypes.every(returnType => isBooleanType(returnType))) {
+        return;
+      }
+
+      const canFix = isFunctionExpression && !predicateNode.returnType;
+
+      return context.report({
+        node: predicateNode,
+        messageId: 'predicateReturnsNonBoolean',
+        suggest: canFix
+          ? [
+              {
+                messageId: 'explicitBooleanReturnType',
+                fix: fixer => {
+                  if (
+                    predicateNode.type ===
+                      AST_NODE_TYPES.ArrowFunctionExpression &&
+                    isParenlessArrowFunction(predicateNode, context.sourceCode)
+                  ) {
+                    return [
+                      fixer.insertTextBefore(predicateNode.params[0], '('),
+                      fixer.insertTextAfter(
+                        predicateNode.params[0],
+                        '): boolean',
+                      ),
+                    ];
+                  }
+
+                  if (predicateNode.params.length === 0) {
+                    const closingBracket = nullThrows(
+                      context.sourceCode.getFirstToken(
+                        predicateNode,
+                        token => token.value === ')',
+                      ),
+                      'function expression has to have a closing parenthesis.',
+                    );
+
+                    return fixer.insertTextAfter(closingBracket, ': boolean');
+                  }
+
+                  const lastClosingParenthesis = nullThrows(
+                    context.sourceCode.getTokenAfter(
+                      predicateNode.params[predicateNode.params.length - 1],
+                      token => token.value === ')',
+                    ),
+                    'function expression has to have a closing parenthesis.',
+                  );
+
+                  return fixer.insertTextAfter(
+                    lastClosingParenthesis,
+                    ': boolean',
+                  );
+                },
+              },
+            ]
+          : null,
+      });
     }
 
     /**
@@ -1007,11 +1116,13 @@ function isArrayLengthExpression(
 function isBrandedBoolean(type: ts.Type): boolean {
   return (
     type.isIntersection() &&
-    type.types.some(childType =>
-      tsutils.isTypeFlagSet(
-        childType,
-        ts.TypeFlags.BooleanLiteral | ts.TypeFlags.Boolean,
-      ),
-    )
+    type.types.some(childType => isBooleanType(childType))
+  );
+}
+
+function isBooleanType(expressionType: ts.Type): boolean {
+  return tsutils.isTypeFlagSet(
+    expressionType,
+    ts.TypeFlags.Boolean | ts.TypeFlags.BooleanLiteral,
   );
 }