Add setShouldNotImplyOppositeCase() on SpecifiedTypes to replace FAUX function call workarounds

- Add `shouldNotImplyOppositeCase` flag to `SpecifiedTypes` with `@api`-tagged
  setter and getter methods, propagated through all immutable-copy operations
  (setAlwaysOverwriteTypes, setRootExpr, setNewConditionalExpressionHolders,
  removeExpr, intersectWith, unionWith, normalize)
- Check the flag in `ImpossibleCheckTypeHelper::findSpecifiedType()` to return
  null early, preventing false "always true/false" reports when sureTypes are
  side effects of a check rather than its determining condition
- Replace `FAUX_FUNCTION` rootExpr in `StrContainingTypeSpecifyingExtension`
  with `setShouldNotImplyOppositeCase()`
- Replace `__PHPSTAN_FAUX_CONSTANT` rootExpr in
  `ArrayKeyExistsFunctionTypeSpecifyingExtension` with
  `setShouldNotImplyOppositeCase()`
- Use the flag for equality assertions in `TypeSpecifier::specifyTypesFromAsserts()`
  instead of setting rootExpr to the call expression
- Remove unused imports (Arg, BooleanAnd, NotIdentical, String_, Name,
  Identical, ConstFetch) from the two extension files

Closes phpstan/phpstan#14705

Author: VincentLanglet

src/Analyser/MutatingScope.php

@@ -3496,6 +3496,11 @@ public function filterByTruthyValue(Expr $expr): self
 		}
 
 		$specifiedTypes = $this->typeSpecifier->specifyTypesInCondition($this, $expr, TypeSpecifierContext::createTruthy());
+		if ($specifiedTypes->isEquality() && $this->getType($expr)->isBoolean()->yes()) {
+			$specifiedTypes = $specifiedTypes->unionWith(
+				$this->typeSpecifier->create($expr, new ConstantBooleanType(true), TypeSpecifierContext::createTrue(), $this),
+			);
+		}
 		$scope = $this->applySpecifiedTypes($specifiedTypes);
 		$this->truthyScopes[$exprString] = $scope;
 
@@ -3513,6 +3518,11 @@ public function filterByFalseyValue(Expr $expr): self
 		}
 
 		$specifiedTypes = $this->typeSpecifier->specifyTypesInCondition($this, $expr, TypeSpecifierContext::createFalsey());
+		if ($specifiedTypes->isEquality() && $this->getType($expr)->isBoolean()->yes()) {
+			$specifiedTypes = $specifiedTypes->unionWith(
+				$this->typeSpecifier->create($expr, new ConstantBooleanType(false), TypeSpecifierContext::createTrue(), $this),
+			);
+		}
 		$scope = $this->applySpecifiedTypes($specifiedTypes);
 		$this->falseyScopes[$exprString] = $scope;
 

src/Analyser/SpecifiedTypes.php

@@ -21,6 +21,8 @@ final class SpecifiedTypes
 
 	private bool $overwrite = false;
 
+	private bool $equality = false;
+
 	/** @var array<string, ConditionalExpressionHolder[]> */
 	private array $newConditionalExpressionHolders = [];
 
@@ -93,6 +95,30 @@ public function setAlwaysOverwriteTypes(): self
 		return $self;
 	}
 
+	/**
+	 * Marks these types as coming from an equality check, the same concept as
+	 * the "=Type" equality assertions documented at
+	 * https://phpstan.org/writing-php-code/narrowing-types#equality-assertions
+	 *
+	 * The narrowed types are only applied; they do not determine the check
+	 * outcome, so ImpossibleCheckTypeHelper will not use them to report
+	 * always-true/false for the check expression.
+	 *
+	 * @api
+	 */
+	public function setEquality(): self
+	{
+		$self = clone $this;
+		$self->equality = true;
+
+		return $self;
+	}
+
+	public function isEquality(): bool
+	{
+		return $this->equality;
+	}
+
 	/**
 	 * @api
 	 */
@@ -311,6 +337,9 @@ public function intersectWith(SpecifiedTypes $other): self
 		if ($this->overwrite && $other->overwrite) {
 			$result = $result->setAlwaysOverwriteTypes();
 		}
+		if ($this->equality || $other->equality) {
+			$result->equality = true;
+		}
 
 		return $result->setRootExpr($rootExpr);
 	}
@@ -530,6 +559,9 @@ public function unionWith(SpecifiedTypes $other): self
 		if ($this->overwrite || $other->overwrite) {
 			$result = $result->setAlwaysOverwriteTypes();
 		}
+		if ($this->equality || $other->equality) {
+			$result->equality = true;
+		}
 
 		$conditionalExpressionHolders = $this->newConditionalExpressionHolders;
 		foreach ($other->newConditionalExpressionHolders as $exprString => $holders) {
@@ -568,6 +600,7 @@ public static function unionAll(array $typesList): self
 		$conditionalExpressionHolders = [];
 		$recipes = [];
 		$augments = [];
+		$equality = false;
 
 		foreach ($typesList as $types) {
 			foreach ($types->sureTypes as $exprString => [$exprNode, $type]) {
@@ -588,6 +621,7 @@ public static function unionAll(array $typesList): self
 			}
 
 			$overwrite = $overwrite || $types->overwrite;
+			$equality = $equality || $types->equality;
 			$rootExpr = self::mergeRootExpr($rootExpr, $types->rootExpr);
 
 			foreach ($types->newConditionalExpressionHolders as $exprString => $holders) {
@@ -618,6 +652,7 @@ public static function unionAll(array $typesList): self
 		$result->newConditionalExpressionHolders = $conditionalExpressionHolders;
 		$result->conditionalExpressionHolderRecipes = $recipes;
 		$result->deferredAugments = $augments;
+		$result->equality = $equality;
 
 		return $result->setRootExpr($rootExpr);
 	}

src/Analyser/StmtHandler/ExpressionHandler.php

@@ -23,6 +23,7 @@
 use PHPStan\Node\NoopExpressionNode;
 use PHPStan\Node\PropertyAssignNode;
 use PHPStan\Node\VariableAssignNode;
+use PHPStan\Type\Constant\ConstantBooleanType;
 use PHPStan\Type\NeverType;
 use PHPStan\Type\ObjectType;
 use function array_filter;
@@ -95,11 +96,21 @@ public function processStmt(
 		$scope = $result->getScope();
 		// the expression statement was just processed; read its narrowing from
 		// the result instead of re-resolving it via specifyTypesInCondition().
-		$scope = $scope->applySpecifiedTypes($this->typeSpecifier->specifyTypesInCondition(
+		$specifiedTypes = $this->typeSpecifier->specifyTypesInCondition(
 			$scope,
 			$stmt->expr,
 			TypeSpecifierContext::createNull(),
-		));
+		);
+		$scope = $scope->applySpecifiedTypes($specifiedTypes);
+
+		if ($specifiedTypes->isEquality()) {
+			// Statement counterpart of the equality handling in filterByTruthyValue():
+			// store the call's true result so a duplicate void assertion statement is
+			// reported as always-true. We assign directly because void calls have no
+			// return value to protect, and intersecting true with void would produce never.
+			$scope = $scope->assignExpression($stmt->expr, new ConstantBooleanType(true), new ConstantBooleanType(true));
+		}
+
 		$hasYield = $result->hasYield();
 		$throwPoints = $result->getThrowPoints();
 		$impurePoints = $result->getImpurePoints();

src/Analyser/TypeSpecifier.php

@@ -470,7 +470,10 @@ static function (Type $type, callable $traverse) use ($templateTypeMap, &$contai
 					$assertedType,
 					$assert->isNegated() ? TypeSpecifierContext::createFalse() : TypeSpecifierContext::createTrue(),
 					$scope,
-				)->setRootExpr($containsUnresolvedTemplate || $assert->isEquality() ? $call : null);
+				);
+				if ($containsUnresolvedTemplate || $assert->isEquality()) {
+					$newTypes = $newTypes->setEquality();
+				}
 				$types = $types !== null ? $types->unionWith($newTypes) : $newTypes;
 
 				if (!$context->null() || !$assertedType instanceof ConstantBooleanType) {

src/Rules/Comparison/ImpossibleCheckTypeHelper.php

@@ -322,6 +322,20 @@ private function getSpecifiedType(
 			return null;
 		}
 
+		if ($specifiedTypes->isEquality()) {
+			if ($scope->hasExpressionType($node)->yes()) {
+				$nodeType = $this->treatPhpDocTypesAsCertain ? $scope->getType($node) : $scope->getNativeType($node);
+				if ($nodeType->isTrue()->yes()) {
+					return true;
+				}
+				if ($nodeType->isFalse()->yes()) {
+					return false;
+				}
+			}
+
+			return null;
+		}
+
 		$sureTypes = $specifiedTypes->getSureTypes();
 		$sureNotTypes = $specifiedTypes->getSureNotTypes();
 

src/Type/Php/ArrayKeyExistsFunctionTypeSpecifyingExtension.php

@@ -3,10 +3,7 @@
 namespace PHPStan\Type\Php;
 
 use PhpParser\Node\Expr\ArrayDimFetch;
-use PhpParser\Node\Expr\BinaryOp\Identical;
-use PhpParser\Node\Expr\ConstFetch;
 use PhpParser\Node\Expr\FuncCall;
-use PhpParser\Node\Name;
 use PHPStan\Analyser\Scope;
 use PHPStan\Analyser\SpecifiedTypes;
 use PHPStan\Analyser\TypeSpecifier;
@@ -115,7 +112,7 @@ public function specifyTypes(
 					$arrayType->getIterableValueType(),
 					$context,
 					$scope,
-				))->setRootExpr(new Identical($arrayDimFetch, new ConstFetch(new Name('__PHPSTAN_FAUX_CONSTANT'))));
+				))->setEquality();
 			}
 
 			return new SpecifiedTypes();

src/Type/Php/PregMatchTypeSpecifyingExtension.php

@@ -106,7 +106,7 @@ public function specifyTypes(FunctionReflection $functionReflection, FuncCall $n
 			$matchedType,
 			$context,
 			$scope,
-		)->setRootExpr($node);
+		)->setEquality();
 		if ($overwrite) {
 			$types = $types->setAlwaysOverwriteTypes();
 		}

src/Type/Php/StrContainingTypeSpecifyingExtension.php

@@ -2,12 +2,7 @@
 
 namespace PHPStan\Type\Php;
 
-use PhpParser\Node\Arg;
-use PhpParser\Node\Expr\BinaryOp\BooleanAnd;
-use PhpParser\Node\Expr\BinaryOp\NotIdentical;
 use PhpParser\Node\Expr\FuncCall;
-use PhpParser\Node\Name;
-use PhpParser\Node\Scalar\String_;
 use PHPStan\Analyser\Scope;
 use PHPStan\Analyser\SpecifiedTypes;
 use PHPStan\Analyser\TypeSpecifier;
@@ -100,15 +95,7 @@ public function specifyTypes(FunctionReflection $functionReflection, FuncCall $n
 					new IntersectionType($accessories),
 					$context,
 					$scope,
-				)->setRootExpr(new BooleanAnd(
-					new NotIdentical(
-						$args[$needleArg]->value,
-						new String_(''),
-					),
-					new FuncCall(new Name('FAUX_FUNCTION'), [
-						new Arg($args[$needleArg]->value),
-					]),
-				));
+				)->setEquality();
 
 				if (in_array($lowerFunctionName, self::SUBSTRING_PROVING_FUNCTIONS, true)) {
 					$specifiedTypes = $specifiedTypes