Propagate @phpstan-assert annotations to first-class callables and string callables

- Added Assertions support to ClosureType so first-class callables preserve assertion metadata
- Modified InitializerExprTypeResolver::createFirstClassCallable() to pass assertions from function/method reflection to the created ClosureType
- Added specifyTypesFromCallableCall() in TypeSpecifier to handle variable function calls ($f($v)) by extracting assertions from ClosureType or resolving string callables to their function reflection
- New regression test in tests/PHPStan/Analyser/nsrt/bug-14249.php

Closes phpstan/phpstan#14249

Author: phpstan-bot

src/Analyser/TypeSpecifier.php

@@ -45,6 +45,7 @@
 use PHPStan\Type\Accessory\NonEmptyArrayType;
 use PHPStan\Type\ArrayType;
 use PHPStan\Type\BooleanType;
+use PHPStan\Type\ClosureType;
 use PHPStan\Type\ConditionalTypeForParameter;
 use PHPStan\Type\Constant\ConstantArrayType;
 use PHPStan\Type\Constant\ConstantArrayTypeBuilder;
@@ -570,6 +571,13 @@ public function specifyTypesInCondition(
 				}
 			}
 
+			return $this->handleDefaultTruthyOrFalseyContext($context, $expr, $scope);
+		} elseif ($expr instanceof FuncCall && !($expr->name instanceof Name)) {
+			$specifiedTypes = $this->specifyTypesFromCallableCall($context, $expr, $scope);
+			if ($specifiedTypes !== null) {
+				return $specifiedTypes;
+			}
+
 			return $this->handleDefaultTruthyOrFalseyContext($context, $expr, $scope);
 		} elseif ($expr instanceof MethodCall && $expr->name instanceof Node\Identifier) {
 			$methodCalledOnType = $scope->getType($expr->var);
@@ -1764,6 +1772,75 @@ static function (Type $type, callable $traverse) use ($templateTypeMap, &$contai
 		return $types;
 	}
 
+	private function specifyTypesFromCallableCall(TypeSpecifierContext $context, FuncCall $call, Scope $scope): ?SpecifiedTypes
+	{
+		if (!$call->name instanceof Expr) {
+			return null;
+		}
+
+		$calleeType = $scope->getType($call->name);
+		$args = $call->getArgs();
+
+		$assertions = null;
+		$parametersAcceptor = null;
+
+		// Check for ClosureType with assertions (from first-class callables)
+		if ($calleeType->isCallable()->yes()) {
+			foreach ($calleeType->getCallableParametersAcceptors($scope) as $variant) {
+				if (!$variant instanceof ClosureType) {
+					continue;
+				}
+
+				$variantAssertions = $variant->getAsserts();
+				if ($variantAssertions->getAll() === []) {
+					continue;
+				}
+
+				$assertions = $variantAssertions;
+				$parametersAcceptor = $variant;
+				break;
+			}
+		}
+
+		// Check for constant string callables (e.g. $f = 'is_positive_int'; $f($v))
+		if ($assertions === null) {
+			foreach ($calleeType->getConstantStrings() as $constantString) {
+				if ($constantString->getValue() === '') {
+					continue;
+				}
+				$functionName = new Name($constantString->getValue());
+				if (!$this->reflectionProvider->hasFunction($functionName, $scope)) {
+					continue;
+				}
+
+				$functionReflection = $this->reflectionProvider->getFunction($functionName, $scope);
+				$functionAssertions = $functionReflection->getAsserts();
+				if ($functionAssertions->getAll() === []) {
+					continue;
+				}
+
+				$assertions = $functionAssertions;
+				if (count($args) > 0) {
+					$parametersAcceptor = ParametersAcceptorSelector::selectFromArgs($scope, $args, $functionReflection->getVariants(), $functionReflection->getNamedArgumentsVariants());
+				}
+				break;
+			}
+		}
+
+		if ($assertions === null || $assertions->getAll() === [] || $parametersAcceptor === null) {
+			return null;
+		}
+
+		$asserts = $assertions->mapTypes(static fn (Type $type) => TemplateTypeHelper::resolveTemplateTypes(
+			$type,
+			$parametersAcceptor->getResolvedTemplateTypeMap(),
+			$parametersAcceptor instanceof ExtendedParametersAcceptor ? $parametersAcceptor->getCallSiteVarianceMap() : TemplateTypeVarianceMap::createEmpty(),
+			TemplateTypeVariance::createInvariant(),
+		));
+
+		return $this->specifyTypesFromAsserts($context, $call, $asserts, $parametersAcceptor, $scope);
+	}
+
 	/**
 	 * @return array<string, ConditionalExpressionHolder[]>
 	 */

src/Reflection/InitializerExprTypeResolver.php

@@ -958,6 +958,7 @@ public function createFirstClassCallable(
 			}
 
 			$parameters = $variant->getParameters();
+			$assertions = $function !== null ? $function->getAsserts() : Assertions::createEmpty();
 			$closureTypes[] = new ClosureType(
 				$parameters,
 				$returnType,
@@ -970,6 +971,7 @@ public function createFirstClassCallable(
 				$impurePoints,
 				acceptsNamedArguments: $acceptsNamedArguments,
 				mustUseReturnValue: $mustUseReturnValue,
+				assertions: $assertions,
 			);
 		}
 

src/Type/ClosureType.php

@@ -13,6 +13,7 @@
 use PHPStan\PhpDocParser\Ast\Type\IdentifierTypeNode;
 use PHPStan\PhpDocParser\Ast\Type\TypeNode;
 use PHPStan\PhpDocParser\Printer\Printer;
+use PHPStan\Reflection\Assertions;
 use PHPStan\Reflection\Callables\CallableParametersAcceptor;
 use PHPStan\Reflection\Callables\SimpleImpurePoint;
 use PHPStan\Reflection\Callables\SimpleThrowPoint;
@@ -84,6 +85,8 @@ class ClosureType implements TypeWithClassName, CallableParametersAcceptor
 
 	private TrinaryLogic $mustUseReturnValue;
 
+	private Assertions $assertions;
+
 	/**
 	 * @api
 	 * @param list<ParameterReflection>|null $parameters
@@ -107,6 +110,7 @@ public function __construct(
 		private array $usedVariables = [],
 		?TrinaryLogic $acceptsNamedArguments = null,
 		?TrinaryLogic $mustUseReturnValue = null,
+		?Assertions $assertions = null,
 	)
 	{
 		if ($acceptsNamedArguments === null) {
@@ -126,6 +130,12 @@ public function __construct(
 		$this->resolvedTemplateTypeMap = $resolvedTemplateTypeMap ?? TemplateTypeMap::createEmpty();
 		$this->callSiteVarianceMap = $callSiteVarianceMap ?? TemplateTypeVarianceMap::createEmpty();
 		$this->impurePoints = $impurePoints ?? [new SimpleImpurePoint('functionCall', 'call to an unknown Closure', false)];
+		$this->assertions = $assertions ?? Assertions::createEmpty();
+	}
+
+	public function getAsserts(): Assertions
+	{
+		return $this->assertions;
 	}
 
 	/**
@@ -664,6 +674,7 @@ public function traverse(callable $cb): Type
 			$this->usedVariables,
 			$this->acceptsNamedArguments,
 			$this->mustUseReturnValue,
+			$this->assertions,
 		);
 	}
 
@@ -715,6 +726,7 @@ public function traverseSimultaneously(Type $right, callable $cb): Type
 			$this->usedVariables,
 			$this->acceptsNamedArguments,
 			$this->mustUseReturnValue,
+			$this->assertions,
 		);
 	}
 

tests/PHPStan/Analyser/nsrt/bug-14249.php

@@ -0,0 +1,31 @@
+<?php // lint >= 8.1
+
+declare(strict_types = 1);
+
+namespace Bug14249;
+
+use function PHPStan\Testing\assertType;
+
+/**
+ * @phpstan-assert-if-true positive-int $value
+ */
+function is_positive_int(mixed $value): bool {
+	return is_int($value) && $value > 0;
+}
+
+function f(mixed $v): void {
+	$f1 = is_positive_int(...);
+	$f2 = 'Bug14249\is_positive_int';
+
+	if (is_positive_int($v)) {
+		assertType('int<1, max>', $v);
+	}
+
+	if ($f1($v)) {
+		assertType('int<1, max>', $v);
+	}
+
+	if ($f2($v)) {
+		assertType('int<1, max>', $v);
+	}
+}