Apply fixed Coderabbitai review.

Author: terabytesoftw

src/Reflector.php

@@ -14,9 +14,13 @@
 use ReflectionUnionType;
 
 use function array_map;
+use function array_shift;
 use function class_exists;
 use function count;
+use function enum_exists;
+use function interface_exists;
 use function is_object;
+use function trait_exists;
 
 /**
  * Provides lightweight reflection utilities for classes and properties.
@@ -38,7 +42,7 @@ final class Reflector
     /**
      * Maximum number of cached reflection classes.
      */
-    private const MAX_REFLECTION_CLASS_CACHE_SIZE = 1024;
+    private const MAX_REFLECTION_CLASS_CACHE_SIZE = 512;
 
     /**
      * Stores reflection instances keyed by class name.
@@ -234,7 +238,7 @@ public static function propertyAttributeInstances(
      *     SomeClass::class,
      *     'someProperty',
      *     SomeAttribute::class,
-     *  ReflectionAttribute::IS_INSTANCEOF,
+     *     ReflectionAttribute::IS_INSTANCEOF,
      * );
      * ```
      *
@@ -278,7 +282,7 @@ public static function propertyTypeNames(object|string $class, string $property)
         if ($type instanceof ReflectionNamedType) {
             $typeName = $type->getName();
 
-            if ($type->allowsNull() && $typeName !== 'null') {
+            if ($type->allowsNull() && $typeName !== 'null' && $typeName !== 'mixed') {
                 return [$typeName, 'null'];
             }
 
@@ -331,7 +335,12 @@ private static function reflectionClass(object|string $class): ReflectionClass
     {
         $className = is_object($class) ? $class::class : $class;
 
-        if (!class_exists($className)) {
+        if (
+            !class_exists($className)
+            && !interface_exists($className)
+            && !trait_exists($className)
+            && !enum_exists($className)
+        ) {
             throw new InvalidArgumentException(
                 Message::REFLECTOR_TARGET_INVALID->getMessage($className),
             );
@@ -345,7 +354,7 @@ private static function reflectionClass(object|string $class): ReflectionClass
 
         if (!$reflectionClass->isAnonymous()) {
             if (count(self::$reflectionClassCache) >= self::MAX_REFLECTION_CLASS_CACHE_SIZE) {
-                self::$reflectionClassCache = [];
+                array_shift(self::$reflectionClassCache);
             }
 
             self::$reflectionClassCache[$className] = $reflectionClass;

tests/ReflectorTest.php

@@ -8,6 +8,7 @@
 use PHPForge\Helper\Exception\Message;
 use PHPForge\Helper\Reflector;
 use PHPForge\Helper\Tests\Support\Attribute\{Label, Marker};
+use PHPForge\Helper\Tests\Support\Contract\{LeftContract, Status, UsesTimestamp};
 use PHPForge\Helper\Tests\Support\Model\ReflectionFixture;
 use PHPUnit\Framework\TestCase;
 use ReflectionClass;
@@ -18,13 +19,14 @@
  * Unit tests for the {@see Reflector} helper.
  *
  * Test coverage.
- * - Caches reflection class instances for repeated lookups and resets the cache when its size limit is reached.
+ * - Caches reflection class instances for repeated lookups and evicts the oldest entry at cache-size limit.
  * - Detects whether a property exists on the reflection target.
  * - Extracts class and property attributes, including filtered lookups.
  * - Resolves first matching property attribute instances or returns `null` when no match exists.
- * - Resolves property type names for untyped, named, nullable, union, and intersection declarations.
+ * - Resolves property type names for mixed, untyped, named, nullable, union, and intersection declarations.
  * - Returns reflection properties and throws {@see InvalidArgumentException} for missing properties.
- * - Returns short class names for named and anonymous classes and throws.
+ * - Returns short names for class, enum, interface, trait, and anonymous targets and throws
+ *   {@see InvalidArgumentException} for invalid targets.
  *
  * @copyright Copyright (C) 2026 Terabytesoftw.
  * @license https://opensource.org/license/bsd-3-clause BSD 3-Clause License.
@@ -211,7 +213,10 @@ public function testPropertyAttributeInstancesReturnsInstantiatedAttributes(): v
         }
 
         self::assertSame(
-            ['primary', 'secondary'],
+            [
+                'primary',
+                'secondary',
+            ],
             $instanceValues,
             'Should preserve declaration order for instantiated repeatable attributes.',
         );
@@ -320,7 +325,16 @@ public function testPropertyTypeNamesReturnsExpectedNamesForUnionProperty(): voi
         );
     }
 
-    public function testReflectionClassCacheIsResetWhenCacheSizeLimitIsReached(): void
+    public function testPropertyTypeNamesReturnsMixedWithoutExplicitNull(): void
+    {
+        self::assertSame(
+            ['mixed'],
+            Reflector::propertyTypeNames(ReflectionFixture::class, 'payload'),
+            "Should return only 'mixed' without appending an explicit null type.",
+        );
+    }
+
+    public function testReflectionClassCacheEvictsOldestEntryWhenCacheSizeLimitIsReached(): void
     {
         $reflectorClass = new ReflectionClass(Reflector::class);
 
@@ -343,14 +357,19 @@ public function testReflectionClassCacheIsResetWhenCacheSizeLimitIsReached(): vo
         $cacheAfterInsert = $cacheProperty->getValue();
 
         self::assertCount(
-            1,
+            $cacheLimit,
+            $cacheAfterInsert,
+            'Should keep cache size at the configured limit after inserting a new class.',
+        );
+        self::assertArrayNotHasKey(
+            'cached-0',
             $cacheAfterInsert,
-            'Should reset cache and keep only the latest reflected class after limit is reached.',
+            'Should evict the oldest cached entry when cache size limit is reached.',
         );
         self::assertArrayHasKey(
             ReflectionFixture::class,
             $cacheAfterInsert,
-            'Should keep the class being reflected after cache reset.',
+            'Should cache the newly reflected class after evicting the oldest entry.',
         );
     }
 
@@ -406,6 +425,24 @@ public function testShortNameReturnsEmptyStringForAnonymousClass(): void
         );
     }
 
+    public function testShortNameReturnsShortNameForEnumTarget(): void
+    {
+        self::assertSame(
+            'Status',
+            Reflector::shortName(Status::class),
+            'Should return the short name for enum targets.',
+        );
+    }
+
+    public function testShortNameReturnsShortNameForInterfaceTarget(): void
+    {
+        self::assertSame(
+            'LeftContract',
+            Reflector::shortName(LeftContract::class),
+            'Should return the short name for interface targets.',
+        );
+    }
+
     public function testShortNameReturnsShortNameForNamedClass(): void
     {
         self::assertSame(
@@ -415,6 +452,15 @@ public function testShortNameReturnsShortNameForNamedClass(): void
         );
     }
 
+    public function testShortNameReturnsShortNameForTraitTarget(): void
+    {
+        self::assertSame(
+            'UsesTimestamp',
+            Reflector::shortName(UsesTimestamp::class),
+            'Should return the short name for trait targets.',
+        );
+    }
+
     public function testThrowsInvalidArgumentExceptionForInvalidReflectionTarget(): void
     {
         $this->expectException(InvalidArgumentException::class);

tests/Support/Attribute/Label.php

@@ -6,6 +6,12 @@
 
 use Attribute;
 
+/**
+ * Stub repeatable attribute used for reflection attribute tests.
+ *
+ * @copyright Copyright (C) 2026 Terabytesoftw.
+ * @license https://opensource.org/license/bsd-3-clause BSD 3-Clause License.
+ */
 #[Attribute(Attribute::TARGET_CLASS | Attribute::TARGET_PROPERTY | Attribute::IS_REPEATABLE)]
 final class Label
 {

tests/Support/Attribute/Marker.php

@@ -6,5 +6,11 @@
 
 use Attribute;
 
+/**
+ * Stub marker attribute used for filtered reflection attribute tests.
+ *
+ * @copyright Copyright (C) 2026 Terabytesoftw.
+ * @license https://opensource.org/license/bsd-3-clause BSD 3-Clause License.
+ */
 #[Attribute(Attribute::TARGET_PROPERTY)]
 final class Marker {}

tests/Support/Contract/BothContract.php

@@ -4,4 +4,10 @@
 
 namespace PHPForge\Helper\Tests\Support\Contract;
 
+/**
+ * Stub implementation satisfying both intersection contracts for tests.
+ *
+ * @copyright Copyright (C) 2026 Terabytesoftw.
+ * @license https://opensource.org/license/bsd-3-clause BSD 3-Clause License.
+ */
 final class BothContract implements LeftContract, RightContract {}

tests/Support/Contract/LeftContract.php

@@ -4,4 +4,10 @@
 
 namespace PHPForge\Helper\Tests\Support\Contract;
 
+/**
+ * Stub contract used for intersection-type reflection tests.
+ *
+ * @copyright Copyright (C) 2026 Terabytesoftw.
+ * @license https://opensource.org/license/bsd-3-clause BSD 3-Clause License.
+ */
 interface LeftContract {}

tests/Support/Contract/RightContract.php

@@ -4,4 +4,10 @@
 
 namespace PHPForge\Helper\Tests\Support\Contract;
 
+/**
+ * Stub contract used for intersection-type reflection tests.
+ *
+ * @copyright Copyright (C) 2026 Terabytesoftw.
+ * @license https://opensource.org/license/bsd-3-clause BSD 3-Clause License.
+ */
 interface RightContract {}

tests/Support/Contract/Status.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PHPForge\Helper\Tests\Support\Contract;
+
+/**
+ * Stub enum used to validate enum reflection targets in tests.
+ *
+ * @copyright Copyright (C) 2026 Terabytesoftw.
+ * @license https://opensource.org/license/bsd-3-clause BSD 3-Clause License.
+ */
+enum Status
+{
+    case ACTIVE;
+}

tests/Support/Contract/UsesTimestamp.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PHPForge\Helper\Tests\Support\Contract;
+
+/**
+ * Stub trait used to validate trait reflection targets in tests.
+ *
+ * @copyright Copyright (C) 2026 Terabytesoftw.
+ * @license https://opensource.org/license/bsd-3-clause BSD 3-Clause License.
+ */
+trait UsesTimestamp
+{
+    public int $timestamp = 0;
+}

tests/Support/Model/ReflectionFixture.php

@@ -10,22 +10,37 @@
 use PHPForge\Helper\Tests\Support\Contract\LeftContract;
 use PHPForge\Helper\Tests\Support\Contract\RightContract;
 
+/**
+ * Stub model exposing varied property metadata for reflection helper tests.
+ *
+ * @copyright Copyright (C) 2026 Terabytesoftw.
+ * @license https://opensource.org/license/bsd-3-clause BSD 3-Clause License.
+ */
 #[Label('model')]
 final class ReflectionFixture
 {
     public int $id = 1;
+
     public LeftContract&RightContract $intersection;
+
     #[Label('primary')]
     #[Label('secondary')]
     #[Marker]
     public string $name = '';
+
     public string|null $nullable = null;
+
+    public mixed $payload = null;
+
     public static string $static = 'static';
+
     public int|string $union = 1;
+
     /**
      * @var mixed
      */
     public $untyped;
+
     private string $hidden = 'hidden';
 
     public function __construct()