Narrow comparisons on a variable through its recorded defining call

When a variable is assigned the result of a pure information-carrying
call over a plain variable argument (count(), sizeof(), gettype(),
get_class(), get_debug_type()), the scope now records that provenance:
comparing the variable against a single-valued constant additionally
runs the call's own comparison narrowing, so

    $numParts = count($colParts);
    if ($numParts === 3) { ... }

reconstructs $colParts's shape exactly like the direct
`if (count($colParts) === 3)` form - through if/elseif, match arms and
switch cases alike, in both type flavours and both branch directions.

The provenance map is threaded through MutatingScope like the other
expression tables: merges keep only entries recording the identical
call on both sides, and invalidating any expression the entry mentions
(the target, or the call's argument - by printed-key containment)
drops it. Recording is a cheap name check at assignment; lookup is one
isset() per constant comparison on a variable.

None of the touched files is turbo-shadowed.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CGhnJQpUWRRpg6H5LuWJkA

Author: ondrejmirtes

src/Analyser/DirectInternalScopeFactory.php

@@ -68,6 +68,7 @@ public function create(
 		bool $nativeTypesPromoted = false,
 		?TemplateArgumentFrame $templateArgumentFrame = null,
 		?TemplateArgumentConstraints $templateArgumentConstraints = null,
+		array $resultProvenance = [],
 	): MutatingScope
 	{
 		$className = MutatingScope::class;
@@ -109,6 +110,7 @@ public function create(
 			$nativeTypesPromoted,
 			$templateArgumentFrame,
 			$templateArgumentConstraints,
+			$resultProvenance,
 		);
 	}
 

src/Analyser/ExprHandler/AssignHandler.php

@@ -113,6 +113,15 @@ final class AssignHandler implements ExprHandler
 
 	private const DERIVED_CONDITIONAL_EXPRESSIONS_LIMIT = 16;
 
+	/**
+	 * Pure information-carrying functions whose call result keeps provenance
+	 * when assigned to a variable: comparing the variable later narrows
+	 * through the call's own comparison machinery, exactly like comparing the
+	 * call directly (`$type = gettype($x); if ($type === 'string')` narrows
+	 * $x the way `if (gettype($x) === 'string')` does).
+	 */
+	private const RESULT_PROVENANCE_FUNCTIONS = ['count', 'sizeof', 'gettype', 'get_class', 'get_debug_type'];
+
 	public function __construct(
 		private TemplateArgumentObserver $templateArgumentObserver,
 		private VarAnnotationProcessor $varAnnotationProcessor,
@@ -1280,6 +1289,11 @@ public function applyWrite(
 					$scope = $scope->addConditionalExpressions((string) $exprString, $holders);
 				}
 
+				$provenanceCall = $this->resolveResultProvenanceCall($assignedExpr, $var->name);
+				if ($provenanceCall !== null) {
+					$scope = $scope->recordResultProvenance('$' . $var->name, $provenanceCall);
+				}
+
 				if ($assignedExpr instanceof Expr\Array_) {
 					$scope = $this->processArrayByRefItems($nodeScopeResolver, $scope, $storage, $var->name, $assignedExpr, new Variable($var->name));
 				}
@@ -1901,6 +1915,46 @@ private function unwrapAssign(Expr $expr): Expr
 		return $expr;
 	}
 
+	/**
+	 * The assigned expression, when it is a whitelisted pure call over a plain
+	 * variable whose result the target variable now provably holds - the shape
+	 * whose provenance the scope records. The single-variable-argument
+	 * requirement keeps invalidation exact: a write to the argument (or the
+	 * target) drops the record by key containment alone.
+	 */
+	private function resolveResultProvenanceCall(Expr $assignedExpr, string $targetVariableName): ?FuncCall
+	{
+		if (
+			!$assignedExpr instanceof FuncCall
+			|| !$assignedExpr->name instanceof Name
+			|| $assignedExpr->isFirstClassCallable()
+			|| !in_array($assignedExpr->name->toLowerString(), self::RESULT_PROVENANCE_FUNCTIONS, true)
+		) {
+			return null;
+		}
+
+		$args = $assignedExpr->getArgs();
+		if (count($args) !== 1 || $args[0]->unpack || $args[0]->name !== null) {
+			return null;
+		}
+
+		$argValue = $args[0]->value;
+		if (
+			!$argValue instanceof Variable
+			|| !is_string($argValue->name)
+			// the call read the target's pre-assignment value - after the
+			// assignment the record would describe the variable through itself
+			|| $argValue->name === $targetVariableName
+			// closure binds rebind $this without touching provenance
+			|| $argValue->name === 'this'
+			|| in_array($argValue->name, Scope::SUPERGLOBAL_VARIABLES, true)
+		) {
+			return null;
+		}
+
+		return $assignedExpr;
+	}
+
 	/**
 	 * @param array<string, ConditionalExpressionHolder[]> $conditionalExpressions
 	 * @param ImpurePoint[] $rhsImpurePoints

src/Analyser/ExprHandler/Helper/IdenticalNarrowingHelper.php

@@ -46,6 +46,7 @@
 use PHPStan\Type\UnionType;
 use function count;
 use function in_array;
+use function is_string;
 
 /**
  * New-world narrowing for `===` (and, via a negated context, `!==`): composed
@@ -239,6 +240,20 @@ private function specifyAgainstScalarLiteral(
 			return null;
 		}
 
+		// a provenance-recorded subject variable narrows through its defining
+		// call's families, exactly like the direct call comparison - the
+		// variable itself still pins to the constant alongside
+		$provenanceTypes = $this->specifyThroughResultProvenance($subject, $constantExpr, $constantType, $context, $evaluationScope);
+		if ($provenanceTypes !== null) {
+			return $provenanceTypes->unionWith($this->defaultNarrowingHelper->createSubjectTypes(
+				$evaluationScope,
+				$subject,
+				$subjectResult,
+				$constantType,
+				$context,
+			));
+		}
+
 		// $a::class === Foo::class narrows $a to a final Foo when true;
 		// other contexts and plain-string sides only pin the fetch
 		if (
@@ -816,6 +831,40 @@ private function specifyEqualAgainstConstantSide(
 		return false;
 	}
 
+	/**
+	 * When the subject variable is provenance-recorded as holding the result
+	 * of a pure call (`$v = count($x)`), the comparison against the constant
+	 * also runs the call's own family narrowing - `$v == 3` narrows $x like
+	 * `count($x) == 3` would. The recorded call comes from an earlier
+	 * statement and has no stored results in this walk, so the families read
+	 * the argument's current type from the evaluation scope's tracked state.
+	 */
+	private function specifyThroughResultProvenance(
+		Expr $subject,
+		Expr $constantExpr,
+		Type $constantType,
+		TypeSpecifierContext $context,
+		MutatingScope $evaluationScope,
+	): ?SpecifiedTypes
+	{
+		$unwrappedSubject = $subject instanceof AlwaysRememberedExpr ? $subject->getExpr() : $subject;
+		if (!$unwrappedSubject instanceof Expr\Variable || !is_string($unwrappedSubject->name)) {
+			return null;
+		}
+
+		$call = $evaluationScope->getResultProvenanceCall('$' . $unwrappedSubject->name);
+		if ($call === null) {
+			return null;
+		}
+
+		$familyTypes = $this->specifyFuncCallFamilies($call, null, $call, $constantExpr, $constantType, $context, $evaluationScope, null, true);
+		if (!$familyTypes instanceof SpecifiedTypes) {
+			return null;
+		}
+
+		return $familyTypes;
+	}
+
 	/**
 	 * The function-family compositions, shared by the literal and the
 	 * TYPE-based constant sides: a family answer, null to fall back to the
@@ -826,13 +875,14 @@ private function specifyEqualAgainstConstantSide(
 	 */
 	private function specifyFuncCallFamilies(
 		Expr $subject,
-		ExpressionResult $subjectResult,
+		?ExpressionResult $subjectResult,
 		Expr\FuncCall $call,
 		Expr $constantExpr,
 		Type $constantType,
 		TypeSpecifierContext $context,
 		MutatingScope $evaluationScope,
 		?ExpressionResult $argResult,
+		bool $argTypesFromScopeState = false,
 	): SpecifiedTypes|false|null
 	{
 		if (!($call->name instanceof Name) || $call->isFirstClassCallable() || !isset($call->getArgs()[0])) {
@@ -845,6 +895,10 @@ private function specifyFuncCallFamilies(
 			$call->name->toLowerString() === 'preg_match'
 		) {
 			if ($context->true() && (new ConstantIntegerType(1))->isSuperTypeOf($constantType)->yes()) {
+				if ($subjectResult === null) {
+					return null;
+				}
+
 				return $subjectResult->getSpecifiedTypesForScope($evaluationScope, $context);
 			}
 
@@ -859,10 +913,11 @@ private function specifyFuncCallFamilies(
 				$constantStrings = $constantType->getConstantStrings();
 				if (count($constantStrings) === 1 && $constantStrings[0]->getValue() === '') {
 					$argExpr = $call->getArgs()[0]->value;
-					if ($argResult === null) {
+					$argType = $this->resolveFamilyArgType($call, $argResult, $argTypesFromScopeState, $evaluationScope);
+					if ($argType === null) {
 						return null;
 					}
-					if ($argResult->getTypeOnScope($evaluationScope, $evaluationScope->nativeTypesPromoted)->isString()->yes()) {
+					if ($argType->isString()->yes()) {
 						return $this->defaultNarrowingHelper->createForSubject(
 							$argExpr,
 							new IntersectionType([new StringType(), new AccessoryNonEmptyStringType()]),
@@ -882,10 +937,10 @@ private function specifyFuncCallFamilies(
 				$constantStrings = $constantType->getConstantStrings();
 				if (count($constantStrings) === 1 && $constantStrings[0]->getValue() !== '') {
 					$argExpr = $call->getArgs()[0]->value;
-					if ($argResult === null) {
+					$argType = $this->resolveFamilyArgType($call, $argResult, $argTypesFromScopeState, $evaluationScope);
+					if ($argType === null) {
 						return null;
 					}
-					$argType = $argResult->getTypeOnScope($evaluationScope, $evaluationScope->nativeTypesPromoted);
 					$objectType = new ObjectType($constantStrings[0]->getValue());
 					$classStringType = new GenericClassStringType($objectType);
 
@@ -916,10 +971,10 @@ private function specifyFuncCallFamilies(
 		) {
 			if ($context->truthy() && $constantType->isNonEmptyString()->yes()) {
 				$argExpr = $call->getArgs()[0]->value;
-				if ($argResult === null) {
+				$argType = $this->resolveFamilyArgType($call, $argResult, $argTypesFromScopeState, $evaluationScope);
+				if ($argType === null) {
 					return null;
 				}
-				$argType = $argResult->getTypeOnScope($evaluationScope, $evaluationScope->nativeTypesPromoted);
 
 				if ($argType->isString()->yes()) {
 					$types = new SpecifiedTypes();
@@ -961,10 +1016,10 @@ private function specifyFuncCallFamilies(
 				return $this->defaultNarrowingHelper->createForSubject($argExpr, new NeverType(), $context, $evaluationScope);
 			}
 
-			if ($argResult === null) {
+			$argType = $this->resolveFamilyArgType($call, $argResult, $argTypesFromScopeState, $evaluationScope);
+			if ($argType === null) {
 				return null;
 			}
-			$argType = $argResult->getTypeOnScope($evaluationScope, $evaluationScope->nativeTypesPromoted);
 
 			if ((new ConstantIntegerType(0))->isSuperTypeOf($constantType)->yes()) {
 				$newArgType = $context->truthy() && !$argType->isArray()->yes()
@@ -1022,10 +1077,11 @@ private function specifyFuncCallFamilies(
 			}
 
 			if ($context->truthy() && IntegerRangeType::fromInterval(1, null)->isSuperTypeOf($constantType)->yes()) {
-				if ($argResult === null) {
+				$argType = $this->resolveFamilyArgType($call, $argResult, $argTypesFromScopeState, $evaluationScope);
+				if ($argType === null) {
 					return null;
 				}
-				if ($argResult->getTypeOnScope($evaluationScope, $evaluationScope->nativeTypesPromoted)->isString()->yes()) {
+				if ($argType->isString()->yes()) {
 					$accessory = IntegerRangeType::fromInterval(2, null)->isSuperTypeOf($constantType)->yes()
 						? new AccessoryNonFalsyStringType()
 						: new AccessoryNonEmptyStringType();
@@ -1102,6 +1158,25 @@ private function specifyFuncCallFamilies(
 		return false;
 	}
 
+	/**
+	 * The first argument's current type for the family compositions: from the
+	 * captured operand result or - for a provenance-recorded call from an
+	 * earlier statement, which has no captured results in this comparison -
+	 * from the evaluation scope's tracked state. Null means unknown and the
+	 * family falls back to the old-world path.
+	 */
+	private function resolveFamilyArgType(Expr\FuncCall $call, ?ExpressionResult $argResult, bool $argTypesFromScopeState, MutatingScope $evaluationScope): ?Type
+	{
+		if ($argTypesFromScopeState) {
+			return $evaluationScope->getStateType($call->getArgs()[0]->value);
+		}
+		if ($argResult === null) {
+			return null;
+		}
+
+		return $argResult->getTypeOnScope($evaluationScope, $evaluationScope->nativeTypesPromoted);
+	}
+
 	/**
 	 * The first argument's stored result of a (possibly remembered) call
 	 * operand, captured by the seams at create time - the composed function

src/Analyser/InternalScopeFactory.php

@@ -21,6 +21,7 @@ interface InternalScopeFactory
 	 * @param array<string, bool> $currentlyAssignedExpressions
 	 * @param array<string, true> $currentlyAllowedUndefinedExpressions
 	 * @param list<array{FunctionReflection|MethodReflection|null, ParameterReflection|null}> $inFunctionCallsStack
+	 * @param array<string, ResultProvenance> $resultProvenance
 	 */
 	public function create(
 		ScopeContext $context,
@@ -41,6 +42,7 @@ public function create(
 		bool $nativeTypesPromoted = false,
 		?TemplateArgumentFrame $templateArgumentFrame = null,
 		?TemplateArgumentConstraints $templateArgumentConstraints = null,
+		array $resultProvenance = [],
 	): MutatingScope;
 
 	public function toNodeCallbackScopeFactory(): self;

src/Analyser/LazyInternalScopeFactory.php

@@ -89,6 +89,7 @@ public function create(
 		bool $nativeTypesPromoted = false,
 		?TemplateArgumentFrame $templateArgumentFrame = null,
 		?TemplateArgumentConstraints $templateArgumentConstraints = null,
+		array $resultProvenance = [],
 	): MutatingScope
 	{
 		$className = MutatingScope::class;
@@ -142,6 +143,7 @@ public function create(
 			$nativeTypesPromoted,
 			$templateArgumentFrame,
 			$templateArgumentConstraints,
+			$resultProvenance,
 		);
 	}