Single-pass expression analysis groundwork - answer type questions from ExpressionResults

build/PHPStan/Build/NoScopeTypeReadInEngineRule.php

@@ -0,0 +1,111 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\Build;
+
+use PhpParser\Node;
+use PhpParser\Node\Expr\MethodCall;
+use PHPStan\Analyser\Scope;
+use PHPStan\Rules\Rule;
+use PHPStan\Rules\RuleErrorBuilder;
+use function array_key_exists;
+use function in_array;
+use function sprintf;
+use function str_starts_with;
+
+/**
+ * The single-pass engine must not price expressions through Scope::getType()
+ * and friends - every walked node's type lives in its ExpressionResult
+ * (threaded via ArgsResult, storage, or gathered statement scopes). A scope
+ * read in engine code either re-walks a node on demand or silently diverges
+ * from the stored result. The allowlist below names the documented seams
+ * (rule-facing bridge asks and ask-ahead-of-walk reads).
+ *
+ * @implements Rule<MethodCall>
+ */
+final class NoScopeTypeReadInEngineRule implements Rule
+{
+
+	private const ENGINE_NAMESPACES = [
+		'PHPStan\\Analyser\\NodeScopeResolver',
+		'PHPStan\\Analyser\\StmtHandler\\',
+		'PHPStan\\Analyser\\ExprHandler\\',
+	];
+
+	private const BANNED_METHODS = ['getType', 'getNativeType', 'getKeepVoidType'];
+
+	/** @var array<string, list<string>> class => methods with documented seam reads */
+	private const ALLOWED_SEAMS = [
+		// rule-facing bridge asks: the scope carries no storage
+		'PHPStan\\Analyser\\ExprHandler\\Helper\\ClosureTypeResolver' => ['readExprType', 'resolveArrowFunctionReturnType'],
+		'PHPStan\\Analyser\\ExprHandler\\Helper\\CountNarrowingHelper' => ['isNormalCountCall'],
+		// immediately invoked closures: the invocation args are walked after the closure
+		'PHPStan\\Analyser\\ExprHandler\\Helper\\ClosureTypeResolver#buildParametersAndAcceptors' => [],
+	];
+
+	public function getNodeType(): string
+	{
+		return MethodCall::class;
+	}
+
+	public function processNode(Node $node, Scope $scope): array
+	{
+		if (!$node->name instanceof Node\Identifier) {
+			return [];
+		}
+		$methodName = $node->name->toString();
+		if (!in_array($methodName, self::BANNED_METHODS, true)) {
+			return [];
+		}
+
+		$namespace = $scope->getClassReflection()?->getName();
+		if ($namespace === null) {
+			return [];
+		}
+		$inEngine = false;
+		foreach (self::ENGINE_NAMESPACES as $prefix) {
+			if ($namespace === $prefix || str_starts_with($namespace, $prefix)) {
+				$inEngine = true;
+				break;
+			}
+		}
+		if (!$inEngine) {
+			return [];
+		}
+
+		$calledOnType = $scope->getType($node->var);
+		if ($calledOnType->getObjectClassNames() === []) {
+			return [];
+		}
+		$isScope = false;
+		foreach ($calledOnType->getObjectClassReflections() as $classReflection) {
+			if ($classReflection->is(Scope::class)) {
+				$isScope = true;
+				break;
+			}
+		}
+		if (!$isScope) {
+			return [];
+		}
+
+		$function = $scope->getFunction();
+		$functionName = $function !== null ? $function->getName() : null;
+		if (
+			array_key_exists($namespace, self::ALLOWED_SEAMS)
+			&& $functionName !== null
+			&& in_array($functionName, self::ALLOWED_SEAMS[$namespace], true)
+		) {
+			return [];
+		}
+		if ($functionName !== null && array_key_exists($namespace . '#' . $functionName, self::ALLOWED_SEAMS)) {
+			return [];
+		}
+
+		return [
+			RuleErrorBuilder::message(sprintf(
+				'Engine code must not price expressions via Scope::%s() - read the expression\'s stored ExpressionResult (ArgsResult, storage, gathered scopes) instead.',
+				$methodName,
+			))->identifier('phpstanBuild.scopeTypeReadInEngine')->build(),
+		];
+	}
+
+}

build/phpstan.neon

@@ -183,6 +183,7 @@ parameters:
 
 rules:
 	- PHPStan\Build\FinalClassRule
+	- PHPStan\Build\NoScopeTypeReadInEngineRule
 	- PHPStan\Build\AttributeNamedArgumentsRule
 	- PHPStan\Build\NamedArgumentsRule
 	- PHPStan\Build\OverrideAttributeThirdPartyMethodRule

phpstan-baseline.neon

@@ -24,6 +24,12 @@ parameters:
 			count: 3
 			path: src/Analyser/ExprHandler/AssignHandler.php
 
+		-
+			rawMessage: Casting to string something that's already string.
+			identifier: cast.useless
+			count: 3
+			path: src/Analyser/ExprHandler/Helper/ConditionalExpressionHolderHelper.php
+
 		-
 			rawMessage: 'Doing instanceof PHPStan\Type\Constant\ConstantStringType is error-prone and deprecated. Use Type::getConstantStrings() instead.'
 			identifier: phpstanApi.instanceofType
@@ -36,40 +42,22 @@ parameters:
 			count: 2
 			path: src/Analyser/ExprHandler/BinaryOpHandler.php
 
-		-
-			rawMessage: 'Doing instanceof PHPStan\Type\Constant\ConstantBooleanType is error-prone and deprecated. Use Type::isTrue() or Type::isFalse() instead.'
-			identifier: phpstanApi.instanceofType
-			count: 1
-			path: src/Analyser/ExprHandler/BooleanNotHandler.php
-
-		-
-			rawMessage: 'Doing instanceof PHPStan\Type\ConstantScalarType is error-prone and deprecated. Use Type::isConstantScalarValue() or Type::getConstantScalarTypes() or Type::getConstantScalarValues() instead.'
-			identifier: phpstanApi.instanceofType
-			count: 2
-			path: src/Analyser/ExprHandler/Helper/EqualityTypeSpecifyingHelper.php
-
-		-
-			rawMessage: 'Doing instanceof PHPStan\Type\Constant\ConstantBooleanType is error-prone and deprecated. Use Type::isTrue() or Type::isFalse() instead.'
-			identifier: phpstanApi.instanceofType
-			count: 3
-			path: src/Analyser/ExprHandler/Helper/EqualityTypeSpecifyingHelper.php
-
 		-
 			rawMessage: 'Doing instanceof PHPStan\Type\Constant\ConstantStringType is error-prone and deprecated. Use Type::getConstantStrings() instead.'
 			identifier: phpstanApi.instanceofType
 			count: 2
-			path: src/Analyser/ExprHandler/IssetHandler.php
+			path: src/Analyser/ExprHandler/Helper/DefaultNarrowingHelper.php
 
 		-
 			rawMessage: 'Only numeric types are allowed in pre-increment, float|int|string|null given.'
 			identifier: preInc.nonNumeric
 			count: 1
-			path: src/Analyser/ExprHandler/PreIncHandler.php
+			path: src/Analyser/ExprHandler/Helper/IncDecTypeHelper.php
 
 		-
 			rawMessage: Casting to string something that's already string.
 			identifier: cast.useless
-			count: 1
+			count: 4
 			path: src/Analyser/MutatingScope.php
 
 		-
@@ -90,6 +78,12 @@ parameters:
 			count: 1
 			path: src/Analyser/MutatingScope.php
 
+		-
+			rawMessage: 'Parameter #2 $node of method PHPStan\BetterReflection\SourceLocator\Ast\Strategy\NodeToReflection::__invoke() expects PhpParser\Node\Expr\ArrowFunction|PhpParser\Node\Expr\Closure|PhpParser\Node\Expr\FuncCall|PhpParser\Node\Stmt\Class_|PhpParser\Node\Stmt\Const_|PhpParser\Node\Stmt\Enum_|PhpParser\Node\Stmt\Function_|PhpParser\Node\Stmt\Interface_|PhpParser\Node\Stmt\Trait_, PhpParser\Node\Stmt\ClassLike given.'
+			identifier: argument.type
+			count: 1
+			path: src/Analyser/StmtHandler/ClassLikeHandler.php
+
 		-
 			rawMessage: 'Doing instanceof PHPStan\Type\Constant\ConstantBooleanType is error-prone and deprecated. Use Type::isTrue() or Type::isFalse() instead.'
 			identifier: phpstanApi.instanceofType
@@ -108,24 +102,6 @@ parameters:
 			count: 1
 			path: src/Analyser/RuleErrorTransformer.php
 
-		-
-			rawMessage: Casting to string something that's already string.
-			identifier: cast.useless
-			count: 2
-			path: src/Analyser/ScopeOps.php
-
-		-
-			rawMessage: 'Parameter #2 $node of method PHPStan\BetterReflection\SourceLocator\Ast\Strategy\NodeToReflection::__invoke() expects PhpParser\Node\Expr\ArrowFunction|PhpParser\Node\Expr\Closure|PhpParser\Node\Expr\FuncCall|PhpParser\Node\Stmt\Class_|PhpParser\Node\Stmt\Const_|PhpParser\Node\Stmt\Enum_|PhpParser\Node\Stmt\Function_|PhpParser\Node\Stmt\Interface_|PhpParser\Node\Stmt\Trait_, PhpParser\Node\Stmt\ClassLike given.'
-			identifier: argument.type
-			count: 1
-			path: src/Analyser/StmtHandler/ClassLikeHandler.php
-
-		-
-			rawMessage: 'Doing instanceof PHPStan\Type\Constant\ConstantBooleanType is error-prone and deprecated. Use Type::isTrue() or Type::isFalse() instead.'
-			identifier: phpstanApi.instanceofType
-			count: 2
-			path: src/Analyser/TypeSpecifier.php
-
 		-
 			rawMessage: 'Template type TNodeType is declared as covariant, but occurs in contravariant position in parameter node of method PHPStan\Collectors\Collector::processNode().'
 			identifier: generics.variance

src/Analyser/AnalyserResultFinalizer.php

@@ -16,6 +16,7 @@
 use function array_merge;
 use function count;
 use function get_class;
+use function ksort;
 use function sprintf;
 
 #[AutowiredService]
@@ -50,7 +51,12 @@ public function finalize(AnalyserResult $analyserResult, bool $onlyFiles, bool $
 		}
 
 		$nodeType = CollectedDataNode::class;
-		$node = new CollectedDataNode($analyserResult->getCollectedData(), $onlyFiles);
+
+		// parallel analysis merges collected data in worker-completion order -
+		// canonicalize so rules never observe a timing-dependent file order
+		$collectedData = $analyserResult->getCollectedData();
+		ksort($collectedData);
+		$node = new CollectedDataNode($collectedData, $onlyFiles);
 
 		$file = 'N/A';
 		$scope = $this->scopeFactory->create(ScopeContext::create($file));

src/Analyser/ArgsResult.php

@@ -2,26 +2,63 @@
 
 namespace PHPStan\Analyser;
 
+use PhpParser\Node\Expr;
 use PHPStan\Reflection\ParametersAcceptor;
+use PHPStan\ShouldNotHappenException;
+use function get_class;
+use function spl_object_id;
+use function sprintf;
 
 /**
  * Result of NodeScopeResolver::processArgs(): the scope/throw/impure state after
  * processing all arguments (wrapped ExpressionResult) plus the ParametersAcceptor
  * resolved from the arg types gathered on the arg-to-arg evolving scope. The
  * resolved acceptor is type-driven (selectFromTypes) so its generics are resolved
- * against the actual argument types - callers wire it into the call's return
- * type. Null when the call had no variants (dynamic callee).
+ * against the actual argument types - callers wire it into the call expression's
+ * stored return type. Null when the call had no variants (dynamic callee).
  */
 final class ArgsResult
 {
 
+	/**
+	 * @param array<int, ExpressionResult> $argResults keyed by spl_object_id of each argument's value expression
+	 */
 	public function __construct(
 		private ExpressionResult $expressionResult,
 		private ?ParametersAcceptor $resolvedParametersAcceptor,
+		private array $argResults = [],
 	)
 	{
 	}
 
+	/**
+	 * The already-processed ExpressionResult of a call argument's value expression,
+	 * so callers read its type via the result instead of re-asking the scope.
+	 */
+	public function getArgResult(Expr $argValue): ?ExpressionResult
+	{
+		return $this->argResults[spl_object_id($argValue)] ?? null;
+	}
+
+	/**
+	 * The stored ExpressionResult of a call argument's value expression; the
+	 * argument must have been processed by processArgs() - engine code reads
+	 * argument types through this instead of re-asking the scope.
+	 */
+	public function requireArgResult(Expr $argValue): ExpressionResult
+	{
+		$result = $this->argResults[spl_object_id($argValue)] ?? null;
+		if ($result === null) {
+			throw new ShouldNotHappenException(sprintf(
+				'No stored ExpressionResult for a %s argument on line %d.',
+				get_class($argValue),
+				$argValue->getStartLine(),
+			));
+		}
+
+		return $result;
+	}
+
 	public function getScope(): MutatingScope
 	{
 		return $this->expressionResult->getScope();

src/Analyser/CalledMethodProcessor.php

@@ -89,7 +89,7 @@ public function processCalledMethod(NodeScopeResolver $nodeScopeResolver, Method
 				$statementResult = $executionEnd->getStatementResult();
 				$endNode = $executionEnd->getNode();
 				if ($endNode instanceof Node\Stmt\Expression) {
-					$exprType = $statementResult->getScope()->getType($endNode->expr);
+					$exprType = $nodeScopeResolver->readTypeOfMaybeStored($endNode->expr, $statementResult->getScope()->toWalkScope());
 					if ($exprType instanceof NeverType && $exprType->isExplicit()) {
 						continue;
 					}

src/Analyser/ConditionalExpressionHolderRecipe.php

@@ -44,7 +44,7 @@ public function evaluate(MutatingScope $scope): array
 		// dropped-self-condition complement below
 		$conditionOriginalTypes = [];
 		foreach ($this->conditionEntries as [$exprString, $expr, $fromSureTypes, $type]) {
-			$scopeType = $scope->getType($expr);
+			$scopeType = $scope->getStateType($expr);
 			$conditionType = $fromSureTypes
 				? TypeCombinator::remove($scopeType, $type)
 				: TypeCombinator::intersect($scopeType, $type);
@@ -81,7 +81,7 @@ public function evaluate(MutatingScope $scope): array
 				continue;
 			}
 
-			$targetType = $pinnedTargetType ?? $scope->getType($expr);
+			$targetType = $pinnedTargetType ?? $scope->getStateType($expr);
 			$holderType = $this->holdersFromSureTypes
 				? TypeCombinator::intersect($targetType, $type)
 				: TypeCombinator::remove($targetType, $type);

src/Analyser/DirectInternalScopeFactory.php

@@ -19,6 +19,8 @@
 final class DirectInternalScopeFactory implements InternalScopeFactory
 {
 
+	private ExpressionResultStorageStack $expressionResultStorageStack;
+
 	/**
 	 * @param int|array{min: int, max: int}|null $configPhpVersion
 	 * @param callable(Node $node, Scope $scope): void|null $nodeCallback
@@ -39,8 +41,10 @@ public function __construct(
 		private $nodeCallback,
 		private ConstantResolver $constantResolver,
 		private bool $createsNodeCallbackScopes = false,
+		?ExpressionResultStorageStack $expressionResultStorageStack = null,
 	)
 	{
+		$this->expressionResultStorageStack = $expressionResultStorageStack ?? new ExpressionResultStorageStack();
 	}
 
 	public function create(
@@ -78,6 +82,7 @@ public function create(
 			$this->propertyReflectionFinder,
 			$this->parser,
 			$this->constantResolver,
+			$this->expressionResultStorageStack,
 			$context,
 			$this->phpVersion,
 			$this->attributeReflectionFactory,
@@ -103,25 +108,15 @@ public function create(
 
 	public function toNodeCallbackScopeFactory(): InternalScopeFactory
 	{
-		return new self(
-			$this->container,
-			$this->reflectionProvider,
-			$this->initializerExprTypeResolver,
-			$this->expressionTypeResolverExtensions,
-			$this->exprPrinter,
-			$this->typeSpecifier,
-			$this->propertyReflectionFinder,
-			$this->parser,
-			$this->phpVersion,
-			$this->attributeReflectionFactory,
-			$this->configPhpVersion,
-			$this->nodeCallback,
-			$this->constantResolver,
-			true,
-		);
+		return $this->withFlavor(true);
 	}
 
 	public function toWalkScopeFactory(): InternalScopeFactory
+	{
+		return $this->withFlavor(false);
+	}
+
+	private function withFlavor(bool $createsNodeCallbackScopes): self
 	{
 		return new self(
 			$this->container,
@@ -137,7 +132,8 @@ public function toWalkScopeFactory(): InternalScopeFactory
 			$this->configPhpVersion,
 			$this->nodeCallback,
 			$this->constantResolver,
-			false,
+			$createsNodeCallbackScopes,
+			$this->expressionResultStorageStack,
 		);
 	}