feat(reflection): resolve short class names in @var docblock annotations - PhpToken implementation

packages/reflection/src/PropertyReflector.php

@@ -5,12 +5,20 @@
 namespace Tempest\Reflection;
 
 use Error;
+use PhpToken;
+use ReflectionClass;
 use ReflectionProperty as PHPReflectionProperty;
 
 final class PropertyReflector implements Reflector
 {
     use HasAttributes;
 
+    /** @var array<string, array<string, string>> */
+    private static array $useStatementCache = [];
+
+    /** @var array<string, string> */
+    private static array $resolvedTypeCache = [];
+
     public function __construct(
         private readonly PHPReflectionProperty $reflectionProperty,
     ) {}
@@ -94,17 +102,207 @@ public function getIterableType(): ?TypeReflector
     {
         $doc = $this->reflectionProperty->getDocComment();
 
-        if (! $doc) {
+        if (! $doc || ! preg_match('/@var\s+(?:(?:array|list)<([\\\\\w]+)>|([\\\\\w]+)\[\])/', $doc, $match)) {
             return null;
         }
 
-        preg_match('/@var ([\\\\\w]+)\[]/', $doc, $match);
+        $rawType = $match[1] !== '' ? $match[1] : $match[2];
+        $typeName = ltrim($rawType, '\\');
+
+        return str_contains($rawType, '\\')
+            ? new TypeReflector($typeName)
+            : new TypeReflector($this->resolveShortClassName($typeName));
+    }
+
+    private function resolveShortClassName(string $shortName): string
+    {
+        $declaringClass = $this->reflectionProperty->getDeclaringClass();
+        $cacheKey = $declaringClass->getName() . '::' . $shortName;
+
+        return self::$resolvedTypeCache[$cacheKey] ??= $this->doResolveShortClassName($shortName, $declaringClass);
+    }
+
+    private function doResolveShortClassName(string $shortName, ReflectionClass $declaringClass): string
+    {
+        $fileName = $declaringClass->getFileName();
+
+        if ($fileName) {
+            self::$useStatementCache[$fileName] ??= $this->parseUseStatements($fileName);
+
+            if (isset(self::$useStatementCache[$fileName][$shortName])) {
+                return self::$useStatementCache[$fileName][$shortName];
+            }
+        }
+
+        $namespace = $declaringClass->getNamespaceName();
+
+        if ($namespace !== '') {
+            $fqcn = $namespace . '\\' . $shortName;
+
+            if (class_exists($fqcn)) {
+                return $fqcn;
+            }
+        }
+
+        return $shortName;
+    }
+
+    /** @return array<string, string> */
+    private function parseUseStatements(string $fileName): array
+    {
+        $content = file_get_contents($fileName);
+
+        if ($content === false) {
+            return [];
+        }
+
+        $tokens = PhpToken::tokenize($content);
+        $useStatements = [];
+        $count = count($tokens);
+
+        for ($i = 0; $i < $count; $i++) {
+            $token = $tokens[$i];
+
+            if ($token->is([T_CLASS, T_INTERFACE, T_TRAIT, T_ENUM])) {
+                break;
+            }
+
+            if (! $token->is(T_USE)) {
+                continue;
+            }
+
+            $i++;
+            $this->skipWhitespaceTokens($tokens, $i, $count);
+
+            if ($tokens[$i]->is([T_FUNCTION, T_CONST])) {
+                continue;
+            }
+
+            $fqcn = $this->parseNamespacedName($tokens, $i, $count);
+            $this->skipWhitespaceTokens($tokens, $i, $count);
+
+            if ($tokens[$i]->text === '{') {
+                $this->parseGroupUse($tokens, $i, $count, $fqcn, $useStatements);
+                continue;
+            }
+
+            $alias = $this->parseAlias($tokens, $i, $count) ?? $this->getShortName($fqcn);
+            $useStatements[$alias] = $fqcn;
+
+            while ($i < $count && $tokens[$i]->text !== ';') {
+                $i++;
+            }
+        }
+
+        return $useStatements;
+    }
 
-        if (! isset($match[1])) {
+    /** @param PhpToken[] $tokens */
+    private function skipWhitespaceTokens(array $tokens, int &$i, int $count): void
+    {
+        while ($i < $count && $tokens[$i]->is([T_WHITESPACE, T_COMMENT])) {
+            $i++;
+        }
+    }
+
+    /** @param PhpToken[] $tokens */
+    private function parseNamespacedName(array $tokens, int &$i, int $count): string
+    {
+        $name = '';
+
+        while ($i < $count) {
+            $token = $tokens[$i];
+
+            if ($token->is([T_STRING, T_NAME_QUALIFIED, T_NAME_FULLY_QUALIFIED, T_NS_SEPARATOR])) {
+                $name .= $token->text;
+                $i++;
+            } elseif ($token->is(T_WHITESPACE)) {
+                $i++;
+            } else {
+                break;
+            }
+        }
+
+        return ltrim($name, '\\');
+    }
+
+    /** @param PhpToken[] $tokens */
+    private function parseAlias(array $tokens, int &$i, int $count): ?string
+    {
+        if (! $tokens[$i]->is(T_AS)) {
             return null;
         }
 
-        return new TypeReflector(ltrim($match[1], '\\'));
+        $i++;
+        $this->skipWhitespaceTokens($tokens, $i, $count);
+
+        if ($tokens[$i]->is(T_STRING)) {
+            return $tokens[$i++]->text;
+        }
+
+        return null;
+    }
+
+    /**
+     * @param PhpToken[] $tokens
+     * @param array<string, string> $useStatements
+     */
+    private function parseGroupUse(array $tokens, int &$i, int $count, string $prefix, array &$useStatements): void
+    {
+        $i++;
+
+        while ($i < $count && $tokens[$i]->text !== '}') {
+            $this->skipWhitespaceTokens($tokens, $i, $count);
+
+            if ($i >= $count) {
+                break;
+            }
+
+            if ($tokens[$i]->is([T_FUNCTION, T_CONST])) {
+                while ($i < $count && $tokens[$i]->text !== ',' && $tokens[$i]->text !== '}') {
+                    $i++;
+                }
+
+                if ($i < $count && $tokens[$i]->text === ',') {
+                    $i++;
+                }
+
+                continue;
+            }
+
+            $name = $this->parseNamespacedName($tokens, $i, $count);
+
+            if ($name === '') {
+                $i++;
+                continue;
+            }
+
+            $this->skipWhitespaceTokens($tokens, $i, $count);
+
+            if ($i >= $count) {
+                break;
+            }
+
+            $alias = $this->parseAlias($tokens, $i, $count) ?? $this->getShortName($name);
+            $useStatements[$alias] = $prefix . '\\' . $name;
+
+            $this->skipWhitespaceTokens($tokens, $i, $count);
+
+            if ($i < $count && $tokens[$i]->text === ',') {
+                $i++;
+            }
+        }
+
+        if ($i < $count) {
+            $i++;
+        }
+    }
+
+    private function getShortName(string $fqcn): string
+    {
+        $pos = strrpos($fqcn, '\\');
+
+        return $pos === false ? $fqcn : substr($fqcn, $pos + 1);
     }
 
     public function isUninitialized(object $object): bool

packages/reflection/tests/Fixtures/IterableTypeResolution/Author.php

@@ -0,0 +1,10 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tempest\Reflection\Tests\Fixtures\IterableTypeResolution;
+
+final class Author
+{
+    public string $name;
+}

packages/reflection/tests/Fixtures/IterableTypeResolution/Book.php

@@ -0,0 +1,10 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tempest\Reflection\Tests\Fixtures\IterableTypeResolution;
+
+final class Book
+{
+    public string $title;
+}

packages/reflection/tests/Fixtures/IterableTypeResolution/Models/AliasedUseStatement.php

@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tempest\Reflection\Tests\Fixtures\IterableTypeResolution\Models;
+
+use Tempest\Reflection\Tests\Fixtures\IterableTypeResolution\Book as MyBook;
+
+final class AliasedUseStatement
+{
+    /** @var MyBook[] */
+    public array $books = [];
+}

packages/reflection/tests/Fixtures/IterableTypeResolution/Models/FullyQualifiedClassName.php

@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tempest\Reflection\Tests\Fixtures\IterableTypeResolution\Models;
+
+final class FullyQualifiedClassName
+{
+    /** @var \Tempest\Reflection\Tests\Fixtures\IterableTypeResolution\Book[] */
+    public array $books = [];
+}

packages/reflection/tests/Fixtures/IterableTypeResolution/Models/GroupUseStatement.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tempest\Reflection\Tests\Fixtures\IterableTypeResolution\Models;
+
+use Tempest\Reflection\Tests\Fixtures\IterableTypeResolution\Author;
+use Tempest\Reflection\Tests\Fixtures\IterableTypeResolution\Book;
+
+final class GroupUseStatement
+{
+    /** @var Book[] */
+    public array $books = [];
+
+    /** @var Author[] */
+    public array $authors = [];
+}

packages/reflection/tests/Fixtures/IterableTypeResolution/Models/RegularUseStatement.php

@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tempest\Reflection\Tests\Fixtures\IterableTypeResolution\Models;
+
+use Tempest\Reflection\Tests\Fixtures\IterableTypeResolution\Book;
+
+final class RegularUseStatement
+{
+    /** @var Book[] */
+    public array $books = [];
+}

packages/reflection/tests/Fixtures/IterableTypeResolution/SameNamespace.php

@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tempest\Reflection\Tests\Fixtures\IterableTypeResolution;
+
+final class SameNamespace
+{
+    /** @var Book[] */
+    public array $books = [];
+}