Add constants and const mask support

Author: SerafimArts

src/Exception/Runtime/InvalidIterableKeyException.php

@@ -8,14 +8,14 @@
 use TypeLang\Mapper\Context\RuntimeContext;
 
 /**
- * @template TValue of iterable = iterable<mixed, mixed>
+ * @template TValue of mixed = mixed
  *
  * @template-extends IterableKeyException<TValue>
  */
 class InvalidIterableKeyException extends IterableKeyException
 {
     /**
-     * @template TArgValue of iterable
+     * @template TArgValue of mixed
      *
      * @param int<0, max> $index
      * @param TArgValue $value
@@ -25,11 +25,11 @@ class InvalidIterableKeyException extends IterableKeyException
     public static function createFromPath(
         int $index,
         mixed $key,
-        iterable $value,
+        mixed $value,
         PathInterface $path,
         ?\Throwable $previous = null,
     ): self {
-        $template = 'The key {{key}} on index {{index}} in {{value}} is invalid';
+        $template = 'The key {{key}} in {{value}} is invalid';
 
         /** @var self<TArgValue> */
         return new self(

src/Exception/Runtime/IterableException.php

@@ -7,19 +7,15 @@
 use TypeLang\Mapper\Context\Path\PathInterface;
 
 /**
- * @template TValue of iterable = iterable<mixed, mixed>
+ * @template TValue of mixed = mixed
  *
  * @template-extends ValueException<TValue>
  */
 abstract class IterableException extends ValueException implements
     NotInterceptableExceptionInterface
 {
-    /**
-     * @param TValue $value unlike {@see ValueException::$value}, this exception
-     *        value can only be {@see iterable}
-     */
     public function __construct(
-        iterable $value,
+        mixed $value,
         PathInterface $path,
         string $template,
         int $code = 0,

src/Exception/Runtime/IterableKeyException.php

@@ -7,7 +7,7 @@
 use TypeLang\Mapper\Context\Path\PathInterface;
 
 /**
- * @template TValue of iterable = iterable<mixed, mixed>
+ * @template TValue of mixed = mixed
  *
  * @template-extends IterableException<TValue>
  */
@@ -30,7 +30,7 @@ public function __construct(
          * be compatible with PHP array keys ({@see int} or {@see string}).
          */
         public readonly mixed $key,
-        iterable $value,
+        mixed $value,
         PathInterface $path,
         string $template,
         int $code = 0,

src/Mapping/Reference/ReferencesResolver.php

@@ -54,6 +54,10 @@ private function resolveFromCurrentNamespace(TypeStatement $statement, \Reflecti
         return $this->typeResolver->resolve(
             type: $statement,
             transform: static function (Name $name) use ($class): ?Name {
+                if ($name->isFullQualified() || $name->isBuiltin()) {
+                    return $name;
+                }
+
                 $namespace = $class->getNamespaceName();
 
                 // Replace "namespace\ClassName" sequences to current
@@ -72,19 +76,13 @@ private function resolveFromCurrentNamespace(TypeStatement $statement, \Reflecti
                     }
                 }
 
-                if ($namespace !== '' && self::entryExists($namespace . '\\' . $name->toString())) {
-                    return (new Name($namespace))
-                        ->withAdded($name);
+                if ($namespace === '') {
+                    return null;
                 }
 
-                return null;
+                return (new Name($namespace))
+                    ->withAdded($name);
             },
         );
     }
-
-    private static function entryExists(string $fqn): bool
-    {
-        return \class_exists($fqn)
-            || \interface_exists($fqn, false);
-    }
 }

src/Platform/StandardPlatform.php

@@ -42,10 +42,32 @@ public function getTypes(): iterable
         // Adds support for the "string" type
         yield $string = new Builder\SimpleTypeBuilder('string', Type\StringType::class);
         yield new Builder\TypeAliasBuilder(\Stringable::class, $string);
+        yield new Builder\TypeAliasBuilder('non-empty-string', $string, Reason::Temporary);
+        yield new Builder\TypeAliasBuilder('lowercase-string', $string, Reason::Temporary);
+        yield new Builder\TypeAliasBuilder('non-empty-lowercase-string', $string, Reason::Temporary);
+        yield new Builder\TypeAliasBuilder('uppercase-string', $string, Reason::Temporary);
+        yield new Builder\TypeAliasBuilder('non-empty-uppercase-string', $string, Reason::Temporary);
+        yield new Builder\TypeAliasBuilder('numeric-string', $string, Reason::Temporary);
+        yield new Builder\TypeAliasBuilder('literal-string', $string, Reason::Temporary);
+        yield new Builder\TypeAliasBuilder('non-empty-literal-string', $string, Reason::Temporary);
+        yield new Builder\TypeAliasBuilder('class-string', $string, Reason::Temporary);
+        yield new Builder\TypeAliasBuilder('interface-string', $string, Reason::Temporary);
+        yield new Builder\TypeAliasBuilder('trait-string', $string, Reason::Temporary);
+        yield new Builder\TypeAliasBuilder('enum-string', $string, Reason::Temporary);
+        yield new Builder\TypeAliasBuilder('callable-string', $string, Reason::Temporary);
+        yield new Builder\TypeAliasBuilder('truthy-string', $string, Reason::Temporary);
+        yield new Builder\TypeAliasBuilder('non-falsy-string', $string, Reason::Temporary);
 
         // Adds support for the "int" type
         yield $int = new Builder\IntRangeTypeBuilder('int');
         yield new Builder\TypeAliasBuilder('integer', $int, Reason::NonCanonical);
+        yield new Builder\TypeAliasBuilder('positive-int', $int, Reason::Temporary);
+        yield new Builder\TypeAliasBuilder('non-positive-int', $int, Reason::Temporary);
+        yield new Builder\TypeAliasBuilder('negative-int', $int, Reason::Temporary);
+        yield new Builder\TypeAliasBuilder('non-negative-int', $int, Reason::Temporary);
+        yield new Builder\TypeAliasBuilder('non-zero-int', $int, Reason::Temporary);
+        yield new Builder\TypeAliasBuilder('number', $int, Reason::Temporary);
+        yield new Builder\TypeAliasBuilder('numeric', $int, Reason::Temporary);
 
         // Adds support for the "float" type
         yield $float = new Builder\SimpleTypeBuilder('float', Type\FloatType::class);
@@ -70,19 +92,11 @@ public function getTypes(): iterable
         // Adds support for the "?T" statement
         yield new Builder\NullableTypeBuilder();
 
-        // Adds support for the "null" literal and/or named type statement
+        // Adds support for the literal types
         yield new Builder\NullTypeBuilder();
-
-        // Adds support for the "true" and "false" literals
         yield new Builder\BoolLiteralTypeBuilder();
-
-        // Adds support for the integer literal types
         yield new Builder\IntLiteralTypeBuilder();
-
-        // Adds support for the float literal types
         yield new Builder\FloatLiteralTypeBuilder();
-
-        // Adds support for the string literal types
         yield new Builder\StringLiteralTypeBuilder();
 
         // Adds support for the "T[]" statement
@@ -91,33 +105,12 @@ public function getTypes(): iterable
         // Adds support for the "T|U" union types
         yield new Builder\UnionTypeBuilder();
 
-        // Temporary aliases
-        yield new Builder\TypeAliasBuilder('non-empty-string', $string, Reason::Temporary);
-        yield new Builder\TypeAliasBuilder('lowercase-string', $string, Reason::Temporary);
-        yield new Builder\TypeAliasBuilder('non-empty-lowercase-string', $string, Reason::Temporary);
-        yield new Builder\TypeAliasBuilder('uppercase-string', $string, Reason::Temporary);
-        yield new Builder\TypeAliasBuilder('non-empty-uppercase-string', $string, Reason::Temporary);
-        yield new Builder\TypeAliasBuilder('numeric-string', $string, Reason::Temporary);
-        yield new Builder\TypeAliasBuilder('literal-string', $string, Reason::Temporary);
-        yield new Builder\TypeAliasBuilder('non-empty-literal-string', $string, Reason::Temporary);
-        yield new Builder\TypeAliasBuilder('class-string', $string, Reason::Temporary);
-        yield new Builder\TypeAliasBuilder('interface-string', $string, Reason::Temporary);
-        yield new Builder\TypeAliasBuilder('trait-string', $string, Reason::Temporary);
-        yield new Builder\TypeAliasBuilder('enum-string', $string, Reason::Temporary);
-        yield new Builder\TypeAliasBuilder('callable-string', $string, Reason::Temporary);
-        yield new Builder\TypeAliasBuilder('truthy-string', $string, Reason::Temporary);
-        yield new Builder\TypeAliasBuilder('non-falsy-string', $string, Reason::Temporary);
-
-        yield new Builder\TypeAliasBuilder('positive-int', $int, Reason::Temporary);
-        yield new Builder\TypeAliasBuilder('non-positive-int', $int, Reason::Temporary);
-        yield new Builder\TypeAliasBuilder('negative-int', $int, Reason::Temporary);
-        yield new Builder\TypeAliasBuilder('non-negative-int', $int, Reason::Temporary);
-        yield new Builder\TypeAliasBuilder('non-zero-int', $int, Reason::Temporary);
-
-        yield new Builder\TypeAliasBuilder('number', $int, Reason::Temporary);
-        yield new Builder\TypeAliasBuilder('numeric', $int, Reason::Temporary);
+        // Adds support for constants (and masks)
+        yield new Builder\ConstMaskTypeBuilder();
+        yield new Builder\ClassConstTypeBuilder();
+        yield new Builder\ClassConstMaskTypeBuilder();
 
-        // Other
+        // Other (asymmetric)
         yield $object = new Builder\ObjectTypeBuilder('object');
         yield new Builder\TypeAliasBuilder(\stdClass::class, $object);
         yield new Builder\UnitEnumTypeBuilder();

src/Type/Builder/ClassConstMaskTypeBuilder.php

@@ -0,0 +1,88 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypeLang\Mapper\Type\Builder;
+
+use TypeLang\Mapper\Context\BuildingContext;
+use TypeLang\Mapper\Exception\Definition\InternalTypeException;
+use TypeLang\Mapper\Type\Builder\ConstMaskTypeBuilder\ConstFinder;
+use TypeLang\Mapper\Type\Builder\ConstMaskTypeBuilder\ConstFinderMode;
+use TypeLang\Mapper\Type\Builder\ConstMaskTypeBuilder\ConstGroupCreator;
+use TypeLang\Mapper\Type\UnionConstType;
+use TypeLang\Parser\Node\Name;
+use TypeLang\Parser\Node\Stmt\ClassConstMaskNode;
+use TypeLang\Parser\Node\Stmt\ClassConstNode;
+use TypeLang\Parser\Node\Stmt\TypeStatement;
+
+/**
+ * @template-implements TypeBuilderInterface<ClassConstMaskNode, UnionConstType<mixed, mixed>>
+ */
+final class ClassConstMaskTypeBuilder implements TypeBuilderInterface
+{
+    private readonly ConstFinder $finder;
+    private readonly ConstGroupCreator $groups;
+
+    public function __construct()
+    {
+        $this->finder = new ConstFinder();
+        $this->groups = new ConstGroupCreator();
+    }
+
+    public function isSupported(TypeStatement $stmt): bool
+    {
+        return $stmt instanceof ClassConstMaskNode
+            && !$stmt instanceof ClassConstNode;
+    }
+
+    public function build(TypeStatement $stmt, BuildingContext $context): UnionConstType
+    {
+        /** @phpstan-ignore-next-line : Additional DbC assertion */
+        assert($stmt instanceof ClassConstMaskNode);
+
+        return new UnionConstType(
+            groups: $this->groups->create(
+                values: $this->getConstants($stmt),
+                context: $context,
+            ),
+        );
+    }
+
+    /**
+     * @return list<mixed>
+     */
+    private function getConstants(ClassConstMaskNode $stmt): array
+    {
+        $constants = $this->getAllConstants($stmt);
+
+        if ($stmt->constant === null) {
+            return \array_values($constants);
+        }
+
+        return $this->finder->find(
+            constants: $constants,
+            mask: new Name($stmt->constant),
+            mode: ConstFinderMode::Prefix,
+        );
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    private function getAllConstants(ClassConstMaskNode $stmt): array
+    {
+        /** @var class-string $class */
+        $class = $stmt->class->toString();
+
+        try {
+            return (new \ReflectionClass($class))
+                ->getConstants();
+        } catch (\ReflectionException $e) {
+            throw InternalTypeException::becauseInternalTypeErrorOccurs(
+                type: $stmt,
+                message: 'The type of a class constant {{type}} cannot be determined',
+                previous: $e,
+            );
+        }
+    }
+}

src/Type/Builder/ClassConstTypeBuilder.php

@@ -0,0 +1,48 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypeLang\Mapper\Type\Builder;
+
+use TypeLang\Mapper\Context\BuildingContext;
+use TypeLang\Mapper\Exception\Definition\InternalTypeException;
+use TypeLang\Mapper\Type\ClassConstType;
+use TypeLang\Parser\Node\Stmt\ClassConstNode;
+use TypeLang\Parser\Node\Stmt\TypeStatement;
+
+/**
+ * @template-implements TypeBuilderInterface<ClassConstNode, ClassConstType>
+ */
+final class ClassConstTypeBuilder implements TypeBuilderInterface
+{
+    public function isSupported(TypeStatement $stmt): bool
+    {
+        return $stmt instanceof ClassConstNode;
+    }
+
+    public function build(TypeStatement $stmt, BuildingContext $context): ClassConstType
+    {
+        /** @phpstan-ignore-next-line : Additional DbC assertion */
+        assert($stmt instanceof ClassConstNode);
+
+        /** @var class-string $class */
+        $class = $stmt->class->toString();
+        /** @phpstan-ignore-next-line : Constant name is always present */
+        $constant = $stmt->constant->toString();
+
+        try {
+            $reflection = new \ReflectionClassConstant($class, $constant);
+        } catch (\Throwable $e) {
+            throw InternalTypeException::becauseInternalTypeErrorOccurs(
+                type: $stmt,
+                message: 'The type of a class constant {{type}} cannot be determined',
+                previous: $e,
+            );
+        }
+
+        return new ClassConstType(
+            value: $reflection->getValue(),
+            type: $context->getTypeByValue($reflection->getValue()),
+        );
+    }
+}

src/Type/Builder/ConstMaskTypeBuilder.php

@@ -0,0 +1,58 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypeLang\Mapper\Type\Builder;
+
+use TypeLang\Mapper\Context\BuildingContext;
+use TypeLang\Mapper\Type\Builder\ConstMaskTypeBuilder\ConstFinder;
+use TypeLang\Mapper\Type\Builder\ConstMaskTypeBuilder\ConstFinderMode;
+use TypeLang\Mapper\Type\Builder\ConstMaskTypeBuilder\ConstGroupCreator;
+use TypeLang\Mapper\Type\UnionConstType;
+use TypeLang\Parser\Node\Stmt\ConstMaskNode;
+use TypeLang\Parser\Node\Stmt\TypeStatement;
+
+/**
+ * @template-implements TypeBuilderInterface<ConstMaskNode, UnionConstType<mixed, mixed>>
+ */
+final class ConstMaskTypeBuilder implements TypeBuilderInterface
+{
+    private readonly ConstFinder $finder;
+    private readonly ConstGroupCreator $groups;
+
+    public function __construct()
+    {
+        $this->finder = new ConstFinder();
+        $this->groups = new ConstGroupCreator();
+    }
+
+    public function isSupported(TypeStatement $stmt): bool
+    {
+        return $stmt instanceof ConstMaskNode;
+    }
+
+    public function build(TypeStatement $stmt, BuildingContext $context): UnionConstType
+    {
+        /** @phpstan-ignore-next-line : Additional DbC assertion */
+        assert($stmt instanceof ConstMaskNode);
+
+        return new UnionConstType(
+            groups: $this->groups->create(
+                values: $this->getConstants($stmt),
+                context: $context,
+            ),
+        );
+    }
+
+    /**
+     * @return list<mixed>
+     */
+    private function getConstants(ConstMaskNode $stmt): array
+    {
+        return $this->finder->find(
+            constants: \get_defined_constants(),
+            mask: $stmt->name,
+            mode: ConstFinderMode::Prefix,
+        );
+    }
+}