misc!: mark tree mapper and arguments mapper as @pure

This change also impacts all callables that can be given to the mapper
builder — they also need to be pure.

Although it reduces the scope of the mappers, it greatly improves their
safety.

src/Mapper/ArgumentsMapper.php

@@ -8,6 +8,8 @@
 interface ArgumentsMapper
 {
     /**
+     * @pure
+     *
      * @param mixed $source
      * @return array<string, mixed>
      *

src/Mapper/TreeMapper.php

@@ -8,6 +8,8 @@
 interface TreeMapper
 {
     /**
+     * @pure
+     *
      * @template T of object
      *
      * @param string|class-string<T> $signature

src/Mapper/TypeArgumentsMapper.php

@@ -26,6 +26,7 @@ public function __construct(TreeMapper $delegate, FunctionDefinitionRepository $
         $this->functionDefinitionRepository = $functionDefinitionRepository;
     }
 
+    /** @pure */
     public function mapArguments(callable $callable, $source): array
     {
         $function = $this->functionDefinitionRepository->for($callable);

src/Mapper/TypeTreeMapper.php

@@ -24,6 +24,7 @@ public function __construct(TypeParser $typeParser, RootNodeBuilder $nodeBuilder
         $this->nodeBuilder = $nodeBuilder;
     }
 
+    /** @pure */
     public function map(string $signature, $source)
     {
         $node = $this->node($signature, $source);

src/MapperBuilder.php

@@ -35,6 +35,9 @@ public function __construct()
      * using the given source. These arguments can then be used to decide which
      * implementation should be used.
      *
+     * The callback *must* be pure, its output must be deterministic.
+     * @see https://en.wikipedia.org/wiki/Pure_function
+     *
      * Example:
      *
      * ```php
@@ -53,6 +56,7 @@ public function __construct()
      * ```
      *
      * @param interface-string $interfaceName
+     * @psalm-param pure-callable $callback
      */
     public function infer(string $interfaceName, callable $callback): self
     {
@@ -81,6 +85,9 @@ public function infer(string $interfaceName, callable $callback): self
      * needs to be handled as well, the name of the class must be given to this
      * method.
      *
+     * A constructor *must* be pure, its output must be deterministic.
+     * @see https://en.wikipedia.org/wiki/Pure_function
+     *
      * ```php
      * final class SomeClass
      * {
@@ -157,6 +164,7 @@ public function infer(string $interfaceName, callable $callback): self
      *     ]);
      * ```
      *
+     * @psalm-param pure-callable|class-string ...$constructors
      * @param callable|class-string ...$constructors
      */
     public function registerConstructor(...$constructors): self
@@ -238,6 +246,7 @@ public function withCache(CacheInterface $cache): self
 
     /**
      * @template T
+     * @psalm-param pure-callable(T): T $callback
      * @param callable(T): T $callback
      */
     public function alter(callable $callback): self
@@ -373,6 +382,9 @@ public function allowPermissiveTypes(): self
      * part of a query should never be allowed. Therefore, only an exhaustive
      * list of carefully chosen exceptions should be filtered.
      *
+     * The filter callback *must* be pure, its output must be deterministic.
+     * @see https://en.wikipedia.org/wiki/Pure_function
+     *
      * ```php
      * final class SomeClass
      * {
@@ -398,6 +410,7 @@ public function allowPermissiveTypes(): self
      *     ]);
      * ```
      *
+     * @psalm-param pure-callable(Throwable): ErrorMessage $filter
      * @param callable(Throwable): ErrorMessage $filter
      */
     public function filterExceptions(callable $filter): self