Improve type resolver docs

Author: SerafimArts

src/TypeResolver.php

@@ -5,6 +5,7 @@
 namespace TypeLang\Parser;
 
 use TypeLang\Parser\Traverser\TypeMapVisitor;
+use TypeLang\Parser\TypeResolver\PhpUseStatementsReader;
 use TypeLang\Parser\TypeResolver\PhpUseStatementsTransformer;
 use TypeLang\Type\TypeNode;
 
@@ -41,7 +42,6 @@ public function __construct(
      * echo $ast->name->toString();
      * ```
      *
-     * @api
      * @param non-empty-string $name
      */
     public function withTypeImport(string $name): self
@@ -73,7 +73,6 @@ public function withTypeImport(string $name): self
      * echo $ast->name->toString();
      * ```
      *
-     * @api
      * @param non-empty-string $name
      * @param non-empty-string $alias
      */
@@ -82,6 +81,93 @@ public function withTypeImportAs(string $name, string $alias): self
         return new self([...$this->imports, $alias => $name]);
     }
 
+    /**
+     * Registers every `use` import declared in the source file of the given
+     * class, so that type names are resolved exactly as they would be inside
+     * that class.
+     *
+     * For a class whose file declares:
+     * ```
+     * namespace App;
+     *
+     * use TypeLang\Parser\Node;
+     * use TypeLang\Parser\Exception as Error;
+     *
+     * final class Example {}
+     * ```
+     *
+     * You can reuse its imports like this:
+     * ```
+     * $ast = new TypeParser()
+     *     ->parse(<<<'PHP'
+     *         Error\SemanticException
+     *         PHP);
+     *
+     * $ast = new TypeResolver()
+     *     ->withTypeImportsOf(new \ReflectionClass(App\Example::class))
+     *     ->resolve($ast);
+     *
+     * // Expected Output:
+     * // > TypeLang\Parser\Exception\SemanticException
+     * echo $ast->name->toString();
+     * ```
+     *
+     * @param \ReflectionClass<object> $class
+     */
+    public function withTypeImportsFromClass(\ReflectionClass $class): self
+    {
+        $statements = new PhpUseStatementsReader()
+            ->getClassUseStatements($class);
+
+        return new self([...$this->imports, ...$statements]);
+    }
+
+    /**
+     * Registers every `use` import available in the source file of the given
+     * function or method, so that type names are resolved exactly as they
+     * would be inside that function's body.
+     *
+     * For a function whose file declares:
+     * ```
+     * namespace App;
+     *
+     * use TypeLang\Parser\Node;
+     * use TypeLang\Parser\Exception as Error;
+     *
+     * function example(): void {}
+     * ```
+     *
+     * You can reuse its imports like this:
+     * ```
+     * $ast = new TypeParser()
+     *     ->parse(<<<'PHP'
+     *         Error\SemanticException
+     *         PHP);
+     *
+     * $ast = new TypeResolver()
+     *     ->withTypeImportsFromFunction(new \ReflectionFunction('App\example'))
+     *     ->resolve($ast);
+     *
+     * // Expected Output:
+     * // > TypeLang\Parser\Exception\SemanticException
+     * echo $ast->name->toString();
+     * ```
+     */
+    public function withTypeImportsFromFunction(\ReflectionFunctionAbstract $function): self
+    {
+        if ($function instanceof \ReflectionMethod) {
+            // For methods, we find the class and search by it. This will
+            // allow us to traverse fewer PHP tokens (optimize), since the
+            // class declaration is "higher".
+            return $this->withTypeImportsFromClass($function->getDeclaringClass());
+        }
+
+        $statements = new PhpUseStatementsReader()
+            ->getFunctionUseStatements($function);
+
+        return new self([...$this->imports, ...$statements]);
+    }
+
     private function createTraverser(): TraverserInterface
     {
         $transformer = new PhpUseStatementsTransformer($this->imports);
@@ -112,8 +198,6 @@ private function createTraverser(): TraverserInterface
      * // >     TypeLang\Parser\Exception\SemanticException
      * // > }
      * ```
-     *
-     * @api
      */
     public function resolve(TypeNode $type): TypeNode
     {