Rework phpDoc inheritance to resolve through reflection instead of re-walking the hierarchy

Author: ondrejmirtes

src/Analyser/MutatingScope.php

@@ -57,6 +57,7 @@
 use PHPStan\Php\PhpVersion;
 use PHPStan\Php\PhpVersionFactory;
 use PHPStan\Php\PhpVersions;
+use PHPStan\PhpDoc\ResolvedPhpDocBlock;
 use PHPStan\Reflection\Assertions;
 use PHPStan\Reflection\AttributeReflection;
 use PHPStan\Reflection\AttributeReflectionFactory;
@@ -2143,6 +2144,7 @@ public function enterClassMethod(
 		array $immediatelyInvokedCallableParameters = [],
 		array $phpDocClosureThisTypeParameters = [],
 		bool $isConstructor = false,
+		?ResolvedPhpDocBlock $resolvedPhpDocBlock = null,
 	): self
 	{
 		if (!$this->isInClass()) {
@@ -2172,6 +2174,7 @@ public function enterClassMethod(
 				$asserts ?? Assertions::createEmpty(),
 				$selfOutType,
 				$phpDocComment,
+				$resolvedPhpDocBlock,
 				array_map(fn (Type $type): Type => $this->transformStaticType(TemplateTypeHelper::toArgument($type)), $parameterOutTypes),
 				$immediatelyInvokedCallableParameters,
 				array_map(fn (Type $type): Type => $this->transformStaticType(TemplateTypeHelper::toArgument($type)), $phpDocClosureThisTypeParameters),
@@ -2195,6 +2198,7 @@ public function enterPropertyHook(
 		?string $deprecatedDescription,
 		bool $isDeprecated,
 		?string $phpDocComment,
+		?ResolvedPhpDocBlock $resolvedPhpDocBlock = null,
 	): self
 	{
 		if (!$this->isInClass()) {
@@ -2259,6 +2263,7 @@ public function enterPropertyHook(
 				Assertions::createEmpty(),
 				null,
 				$phpDocComment,
+				$resolvedPhpDocBlock,
 				[],
 				[],
 				[],

src/Analyser/NodeScopeResolver.php

@@ -5376,7 +5376,7 @@ private function processPropertyHooks(
 			$this->callNodeCallback($nodeCallback, $hook, $scope, $storage);
 			$this->processAttributeGroups($stmt, $hook->attrGroups, $scope, $storage, $nodeCallback);
 
-			[, $phpDocParameterTypes,,,, $phpDocThrowType,,,,,,,, $phpDocComment] = $this->getPhpDocs($scope, $hook);
+			[, $phpDocParameterTypes,,,, $phpDocThrowType,,,,,,,, $phpDocComment,,,,,, $resolvedPhpDoc] = $this->getPhpDocs($scope, $hook);
 
 			foreach ($hook->params as $param) {
 				$this->processParamNode($stmt, $param, $scope, $storage, $nodeCallback);
@@ -5394,6 +5394,7 @@ private function processPropertyHooks(
 				$deprecatedDescription,
 				$isDeprecated,
 				$phpDocComment,
+				$resolvedPhpDoc,
 			);
 			$hookReflection = $hookScope->getFunction();
 			if (!$hookReflection instanceof PhpMethodFromParserNodeReflection) {
@@ -7266,7 +7267,7 @@ private function processNodesForCalledMethod($node, ExpressionResultStorage $sto
 	}
 
 	/**
-	 * @return array{TemplateTypeMap, array<string, Type>, array<string, bool>, array<string, Type>, ?Type, ?Type, ?string, bool, bool, bool, bool|null, bool, bool, string|null, Assertions, ?Type, array<string, Type>, array<(string|int), VarTag>, bool}
+	 * @return array{TemplateTypeMap, array<string, Type>, array<string, bool>, array<string, Type>, ?Type, ?Type, ?string, bool, bool, bool, bool|null, bool, bool, string|null, Assertions, ?Type, array<string, Type>, array<(string|int), VarTag>, bool, ?ResolvedPhpDocBlock}
 	 */
 	public function getPhpDocs(Scope $scope, Node\FunctionLike|Node\Stmt\Property $node): array
 	{
@@ -7309,12 +7310,20 @@ public function getPhpDocs(Scope $scope, Node\FunctionLike|Node\Stmt\Property $n
 
 				return $param->var->name;
 			}, $node->getParams());
+			$currentResolvedPhpDoc = null;
+			if ($docComment !== null) {
+				$currentResolvedPhpDoc = $this->fileTypeMapper->getResolvedPhpDoc(
+					$file,
+					$class,
+					$trait,
+					$node->name->name,
+					$docComment,
+				);
+			}
 			$resolvedPhpDoc = $this->phpDocInheritanceResolver->resolvePhpDocForMethod(
-				$docComment,
-				$file,
 				$scope->getClassReflection(),
-				$trait,
 				$node->name->name,
+				$currentResolvedPhpDoc,
 				$positionalParameterNames,
 			);
 
@@ -7416,16 +7425,17 @@ public function getPhpDocs(Scope $scope, Node\FunctionLike|Node\Stmt\Property $n
 			$isPure = $resolvedPhpDoc->isPure();
 			$isAllowedPrivateMutation = $resolvedPhpDoc->isAllowedPrivateMutation();
 			$acceptsNamedArguments = $resolvedPhpDoc->acceptsNamedArguments();
-			if ($acceptsNamedArguments && $scope->isInClass()) {
-				$acceptsNamedArguments = $scope->getClassReflection()->acceptsNamedArguments();
-			}
 			$isReadOnly = $isReadOnly || $resolvedPhpDoc->isReadOnly();
 			$asserts = Assertions::createFromResolvedPhpDocBlock($resolvedPhpDoc);
 			$selfOutType = $resolvedPhpDoc->getSelfOutTag() !== null ? $resolvedPhpDoc->getSelfOutTag()->getType() : null;
 			$varTags = $resolvedPhpDoc->getVarTags();
 		}
 
-		return [$templateTypeMap, $phpDocParameterTypes, $phpDocImmediatelyInvokedCallableParameters, $phpDocClosureThisTypeParameters, $phpDocReturnType, $phpDocThrowType, $deprecatedDescription, $isDeprecated, $isInternal, $isFinal, $isPure, $acceptsNamedArguments, $isReadOnly, $docComment, $asserts, $selfOutType, $phpDocParameterOutTypes, $varTags, $isAllowedPrivateMutation];
+		if ($acceptsNamedArguments && $scope->isInClass()) {
+			$acceptsNamedArguments = $scope->getClassReflection()->acceptsNamedArguments();
+		}
+
+		return [$templateTypeMap, $phpDocParameterTypes, $phpDocImmediatelyInvokedCallableParameters, $phpDocClosureThisTypeParameters, $phpDocReturnType, $phpDocThrowType, $deprecatedDescription, $isDeprecated, $isInternal, $isFinal, $isPure, $acceptsNamedArguments, $isReadOnly, $docComment, $asserts, $selfOutType, $phpDocParameterOutTypes, $varTags, $isAllowedPrivateMutation, $resolvedPhpDoc];
 	}
 
 	private function transformStaticType(ClassReflection $declaringClass, Type $type): Type

src/PhpDoc/InheritedPhpDocParameterMapping.php

@@ -0,0 +1,67 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\PhpDoc;
+
+use PHPStan\PhpDoc\Tag\AssertTagParameter;
+use PHPStan\Type\ConditionalTypeForParameter;
+use PHPStan\Type\Type;
+use PHPStan\Type\TypeTraverser;
+use function array_key_exists;
+use function substr;
+
+final class InheritedPhpDocParameterMapping
+{
+
+	/**
+	 * @param array<string, string> $parameterNameMapping
+	 */
+	public function __construct(
+		private array $parameterNameMapping,
+	)
+	{
+	}
+
+	/**
+	 * @template T
+	 * @param array<string, T> $array
+	 * @return array<string, T>
+	 */
+	public function transformArrayKeysWithParameterNameMapping(array $array): array
+	{
+		$newArray = [];
+		foreach ($array as $key => $value) {
+			if (!array_key_exists($key, $this->parameterNameMapping)) {
+				continue;
+			}
+			$newArray[$this->parameterNameMapping[$key]] = $value;
+		}
+
+		return $newArray;
+	}
+
+	public function transformConditionalReturnTypeWithParameterNameMapping(Type $type): Type
+	{
+		$nameMapping = $this->parameterNameMapping;
+		return TypeTraverser::map($type, static function (Type $type, callable $traverse) use ($nameMapping): Type {
+			if ($type instanceof ConditionalTypeForParameter) {
+				$parameterName = substr($type->getParameterName(), 1);
+				if (array_key_exists($parameterName, $nameMapping)) {
+					$type = $type->changeParameterName('$' . $nameMapping[$parameterName]);
+				}
+			}
+
+			return $traverse($type);
+		});
+	}
+
+	public function transformAssertTagParameterWithParameterNameMapping(AssertTagParameter $parameter): AssertTagParameter
+	{
+		$parameterName = substr($parameter->getParameterName(), 1);
+		if (array_key_exists($parameterName, $this->parameterNameMapping)) {
+			$parameter = $parameter->changeParameterName('$' . $this->parameterNameMapping[$parameterName]);
+		}
+
+		return $parameter;
+	}
+
+}