Fix static::CONST in PHPDoc resolving as self::CONST

- Added ClassConstantAccessType, a late-resolvable type that defers constant
  resolution until the actual class is known via static type transformation
- Modified TypeNodeResolver::resolveConstTypeNode() to distinguish static from
  self when resolving class constant PHPDoc types
- When static::CONST appears in a PHPDoc (e.g. @return static::FOO_BAR) on a
  non-final class, the constant is now resolved on the actual called-on class
  rather than always using the declaring class
- New regression test in tests/PHPStan/Analyser/nsrt/bug-13828.php

Closes phpstan/phpstan#13828

Author: github-actions[bot]

src/PhpDoc/TypeNodeResolver.php

@@ -58,6 +58,7 @@
 use PHPStan\Type\BenevolentUnionType;
 use PHPStan\Type\BooleanType;
 use PHPStan\Type\CallableType;
+use PHPStan\Type\ClassConstantAccessType;
 use PHPStan\Type\ClassStringType;
 use PHPStan\Type\ClosureType;
 use PHPStan\Type\ConditionalType;
@@ -1188,9 +1189,13 @@ private function resolveConstTypeNode(ConstTypeNode $typeNode, NameScope $nameSc
 				throw new ShouldNotHappenException(); // global constant should get parsed as class name in IdentifierTypeNode
 			}
 
+			$isStaticKeyword = false;
 			if ($nameScope->getClassName() !== null) {
 				switch (strtolower($constExpr->className)) {
 					case 'static':
+						$isStaticKeyword = true;
+						$className = $nameScope->getClassName();
+						break;
 					case 'self':
 						$className = $nameScope->getClassName();
 						break;
@@ -1263,6 +1268,10 @@ private function resolveConstTypeNode(ConstTypeNode $typeNode, NameScope $nameSc
 				return new EnumCaseObjectType($classReflection->getName(), $constantName);
 			}
 
+			if ($isStaticKeyword && !$classReflection->isFinal()) {
+				return new ClassConstantAccessType(new StaticType($classReflection), $constantName);
+			}
+
 			$reflectionConstant = $classReflection->getNativeReflection()->getReflectionConstant($constantName);
 			if ($reflectionConstant === false) {
 				return new ErrorType();

src/Type/ClassConstantAccessType.php

@@ -0,0 +1,94 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\Type;
+
+use PHPStan\PhpDocParser\Ast\ConstExpr\ConstFetchNode;
+use PHPStan\PhpDocParser\Ast\Type\ConstTypeNode;
+use PHPStan\PhpDocParser\Ast\Type\TypeNode;
+use PHPStan\Type\Generic\TemplateTypeVariance;
+use PHPStan\Type\Traits\LateResolvableTypeTrait;
+use PHPStan\Type\Traits\NonGeneralizableTypeTrait;
+
+final class ClassConstantAccessType implements CompoundType, LateResolvableType
+{
+
+	use LateResolvableTypeTrait;
+	use NonGeneralizableTypeTrait;
+
+	public function __construct(
+		private Type $classType,
+		private string $constantName,
+	)
+	{
+	}
+
+	public function getReferencedClasses(): array
+	{
+		return $this->classType->getReferencedClasses();
+	}
+
+	public function getReferencedTemplateTypes(TemplateTypeVariance $positionVariance): array
+	{
+		return $this->classType->getReferencedTemplateTypes($positionVariance);
+	}
+
+	public function equals(Type $type): bool
+	{
+		return $type instanceof self
+			&& $this->classType->equals($type->classType)
+			&& $this->constantName === $type->constantName;
+	}
+
+	public function describe(VerbosityLevel $level): string
+	{
+		return $this->resolve()->describe($level);
+	}
+
+	public function isResolvable(): bool
+	{
+		return !($this->classType instanceof StaticType);
+	}
+
+	protected function getResult(): Type
+	{
+		foreach ($this->classType->getObjectClassReflections() as $classReflection) {
+			if (!$classReflection->hasConstant($this->constantName)) {
+				continue;
+			}
+
+			return $classReflection->getConstant($this->constantName)->getValueType();
+		}
+
+		return new MixedType();
+	}
+
+	public function traverse(callable $cb): Type
+	{
+		$newClassType = $cb($this->classType);
+		if ($newClassType !== $this->classType) {
+			return new self($newClassType, $this->constantName);
+		}
+
+		return $this;
+	}
+
+	public function traverseSimultaneously(Type $right, callable $cb): Type
+	{
+		if (!$right instanceof self) {
+			return $this;
+		}
+
+		$newClassType = $cb($this->classType, $right->classType);
+		if ($newClassType !== $this->classType) {
+			return new self($newClassType, $this->constantName);
+		}
+
+		return $this;
+	}
+
+	public function toPhpDocNode(): TypeNode
+	{
+		return new ConstTypeNode(new ConstFetchNode('static', $this->constantName));
+	}
+
+}

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

@@ -0,0 +1,39 @@
+<?php
+
+declare(strict_types = 1);
+
+namespace Bug13828;
+
+use function PHPStan\Testing\assertType;
+
+abstract class FooBar
+{
+	const FOO_BAR = 'foo';
+
+	/** @return static::FOO_BAR */
+	public function test(): string
+	{
+		return static::FOO_BAR;
+	}
+}
+
+class Foo extends FooBar
+{
+	const FOO_BAR = 'foo';
+}
+
+class Bar extends FooBar
+{
+	const FOO_BAR = 'bar';
+}
+
+class Baz extends FooBar
+{
+	// Does not override FOO_BAR, inherits 'foo'
+}
+
+function () {
+	assertType("'foo'", (new Foo())->test()); // Foo::FOO_BAR = 'foo'
+	assertType("'bar'", (new Bar())->test()); // Bar::FOO_BAR = 'bar'
+	assertType("'foo'", (new Baz())->test()); // Baz inherits FOO_BAR = 'foo'
+};