Enhance wildcard constant pattern validation for enums and update documentation

Author: rcalicdan

docs/supported-types/primitives-and-scalars.md

@@ -74,11 +74,12 @@ To prevent rounding artifacts from causing unexpected type failures, TypePHP eva
 
 ---
 
-## Wildcard Class Constant Patterns (`Class::PREFIX_*`)
+## Wildcard Constant Patterns (`Class::PREFIX_*` & `StatusEnum::*`)
 
-TypePHP supports validating parameters, return types, properties, and `@var` local assignments against wildcard class constant patterns (`Class::PREFIX_*` or `self::PREFIX_*`). 
+TypePHP supports validating parameters, return types, properties, and `@var` local assignments against wildcard constant patterns (`Class::PREFIX_*` or `StatusEnum::*`). 
 
-TypePHP uses Reflection to safely inspect all matching constants—including `public`, `protected`, and `private` class constants—and validates that the incoming value matches one of the declared constant values:
+* **Class Constants (`Class::PREFIX_*`):** TypePHP uses Reflection to safely inspect all matching constants—including `public`, `protected`, and `private` class constants—and validates that the incoming value matches one of the declared constant scalar values.
+* **Enums (`StatusEnum::*` or `StatusEnum::ACT*`):** Matches incoming **Enum case objects** against the wildcard case pattern.
 
 ```php
 class MigrationCollectionLoader
@@ -96,16 +97,36 @@ class MigrationCollectionLoader
     }
 }
 
+enum StatusEnum: string
+{
+    case Active = 'active';
+    case Inactive = 'inactive';
+    case Pending = 'pending';
+}
+
+class EnumProcessor
+{
+    /**
+     * @param StatusEnum::ACT* $status
+     */
+    public static function processActive(StatusEnum $status): StatusEnum
+    {
+        return $status;
+    }
+}
+
 $loader = new MigrationCollectionLoader();
 
-// Valid Calls (Matches public and private VERSION_SELECTION_* constant values)
+// Valid Class Constant Calls (Matches public and private VERSION_SELECTION_* constant values)
 $loader->collectAllForVersion('all');
-$loader->collectAllForVersion('blue-green');
 $loader->collectAllForVersion('internal-mode');
 
-// Invalid Call ('invalid_mode' does not match any VERSION_SELECTION_* constant)
-$loader->collectAllForVersion('invalid_mode');
-// Throws: TypeError: Argument $mode must be a valid constant matching MigrationCollectionLoader::VERSION_SELECTION_*
+// Valid Enum Wildcard Call (Matches StatusEnum::ACT* -> StatusEnum::Active)
+EnumProcessor::processActive(StatusEnum::Active);
+
+// Invalid Enum Wildcard Call (StatusEnum::Pending does not match StatusEnum::ACT*)
+EnumProcessor::processActive(StatusEnum::Pending);
+// Throws: TypeError: Argument $status must be a valid constant matching StatusEnum::ACT*
 ```
 
 ---
@@ -394,4 +415,4 @@ function badHaltExecution(): string
 
 badHaltExecution();
 // Throws: TypeError: badHaltExecution(): Return value must be of type never
-```
+```

src/Validator/ArrayShapeValidator.php

@@ -91,4 +91,4 @@ public function validate(mixed $value, TypeNode $node, string $context, TypeVali
 
         return null;
     }
-}
+}

src/Validator/ConstValidator.php

@@ -121,4 +121,4 @@ private static function resolveWildcardConstantValues(string $className, string
 
         return self::$wildcardConstantCache[$cacheKey] = $values;
     }
-}
+}

tests/Fixtures/Types/EnumWildcard.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypePHP\Tests\Fixtures\Types;
+
+class EnumWildcard
+{
+    /**
+     * @param StatusEnum::* $status
+     */
+    public static function processEnumCase(StatusEnum $status): StatusEnum
+    {
+        return $status;
+    }
+
+    /**
+     * @param StatusEnum::ACT* $status
+     */
+    public static function processPrefixEnumCase(StatusEnum $status): StatusEnum
+    {
+        return $status;
+    }
+}

tests/Fixtures/Types/GlobalTypes.php

@@ -10,4 +10,4 @@
  */
 class GlobalTypes
 {
-}
+}

tests/Fixtures/Types/WildcardConstantFixture.php

@@ -17,4 +17,4 @@ public static function setVersionMode(string $mode): string
     {
         return $mode;
     }
-}
+}

tests/TypeChecking/ArraysAndShapes/ArrayAndListTypesTest.php

@@ -121,6 +121,7 @@ function testKeylessImplicitTupleShape(array $tuple): bool
  *
  * @phpstan-type LocalTupleAlias array{list<positive-int>, list<non-empty-string>}
  * @phpstan-type MixedTupleShape array{non-empty-string, code: positive-int, list<int>}
+ *
  * @phpstan-import-type SharedTupleShape from \TypePHP\Tests\Fixtures\Types\GlobalTypes as ImportedTuple
  *
  * @param LocalTupleAlias $payload
@@ -153,7 +154,6 @@ function testReturnKeylessTuple(bool $valid): array
     return [[10, 20], 'bundle'];
 }
 
-
 describe('Class Object Arrays (Dog[])', function () {
     test('accepts array of matching class instances', function () {
         expect(testDogArrayParam([new Dog(), new Dog()]))->toBe(2);
@@ -379,4 +379,4 @@ function testReturnKeylessTuple(bool $valid): array
             ->toThrow(TypeError::class, "Return value['0'][1] must be of type positive-int")
         ;
     });
-});
+});

tests/TypeChecking/ArraysAndShapes/UnionErrorBubblingTest.php

@@ -140,6 +140,7 @@ public function __construct()
 
     test('falls back gracefully to generic union error when no deep branch matches structure', function () {
         expect(fn () => testDeepUnionError('string_instead_of_array'))
-            ->toThrow(TypeError::class, 'must be of type (array{id: int, tags: list<(string | int)>} | null)');
+            ->toThrow(TypeError::class, 'must be of type (array{id: int, tags: list<(string | int)>} | null)')
+        ;
     });
 });

tests/TypeChecking/Generics/GenericTemplateBoundsStressTest.php

@@ -226,6 +226,7 @@ function testInferredOverridesDefault(mixed $input, mixed $valueToReturn): mixed
         expect(testInferredOverridesDefault($dt, $dt))->toBe($dt);
 
         expect(fn () => testInferredOverridesDefault($dt, new stdClass()))
-            ->toThrow(TypeError::class, 'Return value');
+            ->toThrow(TypeError::class, 'Return value')
+        ;
     });
 });

tests/TypeChecking/Scalars/ExtendedScalarTypesTest.php

@@ -2,6 +2,8 @@
 
 declare(strict_types=1);
 
+use TypePHP\Tests\Fixtures\Types\EnumWildcard;
+use TypePHP\Tests\Fixtures\Types\StatusEnum;
 use TypePHP\Tests\Fixtures\Types\WildcardConstantFixture;
 
 /**
@@ -152,7 +154,22 @@ function testLiteralUnionsParam(string $status, int $code): bool
 
     test('throws TypeError on value not matching wildcard constant pattern', function () {
         expect(fn () => WildcardConstantFixture::setVersionMode('invalid_mode'))
-            ->toThrow(TypeError::class, "must be a valid constant matching TypePHP\\Tests\\Fixtures\\Types\\WildcardConstantFixture::VERSION_SELECTION_*")
+            ->toThrow(TypeError::class, 'must be a valid constant matching TypePHP\\Tests\\Fixtures\\Types\\WildcardConstantFixture::VERSION_SELECTION_*')
         ;
     });
-});
+});
+
+describe('Enum Wildcard Pattern Validation (StatusEnum::*)', function () {
+    test('accepts Enum case objects matching wildcard patterns (StatusEnum::* & StatusEnum::ACT*)', function () {
+        expect(EnumWildcard::processEnumCase(StatusEnum::Active))->toBe(StatusEnum::Active);
+        expect(EnumWildcard::processEnumCase(StatusEnum::Pending))->toBe(StatusEnum::Pending);
+
+        expect(EnumWildcard::processPrefixEnumCase(StatusEnum::Active))->toBe(StatusEnum::Active);
+    });
+
+    test('throws TypeError when Enum case object does not match prefix wildcard (e.g. Pending for StatusEnum::ACT*)', function () {
+        expect(fn () => EnumWildcard::processPrefixEnumCase(StatusEnum::Pending))
+            ->toThrow(TypeError::class, 'must be a valid constant matching TypePHP\\Tests\\Fixtures\\Types\\StatusEnum::ACT*')
+        ;
+    });
+});