Introduce @psalm-use to import types

That is a proposal of how we could import types defined in other
classes, so we don't need to repeat the types over and over again.
That could be really interesting for composition of types as well.

/** @psalm-type TPhone = array{phone: string} */
class Phone {
    /** @psalm-return TPhone */
    toArray(): array {}
}

/** @psalm-type TName = array{name: string} */
class Name {
    /** @psalm-return TName */
    toArray(): array {}
}

/**
 * @psalm-use TPhone from Phone
 * @psalm-use TName from Name
 *
 * @psalm-type TUserArray = TPhone&TName
 */
class User {
}

Signed-off-by: Jefersson Nathan <malukenho.dev@gmail.com>

src/Psalm/DocComment.php

@@ -267,7 +267,7 @@ public static function parsePreservingLength(\PhpParser\Comment\Doc $docblock)
                     $special_key,
                     [
                         'return', 'param', 'template', 'var', 'type',
-                        'template-covariant', 'property', 'method',
+                        'template-covariant', 'property', 'method', 'use',
                         'assert', 'assert-if-true', 'assert-if-false', 'suppress',
                         'ignore-nullable-return', 'override-property-visibility',
                         'override-method-visibility', 'seal-properties', 'seal-methods',

src/Psalm/Internal/Analyzer/CommentAnalyzer.php

@@ -3,6 +3,7 @@
 
 use PhpParser;
 use Psalm\Aliases;
+use Psalm\Codebase;
 use Psalm\DocComment;
 use Psalm\Exception\DocblockParseException;
 use Psalm\Exception\IncorrectDocblockException;
@@ -11,8 +12,11 @@
 use Psalm\Internal\Scanner\ClassLikeDocblockComment;
 use Psalm\Internal\Scanner\FunctionDocblockComment;
 use Psalm\Internal\Scanner\VarDocblockComment;
+use Psalm\Internal\Taint\Source;
 use Psalm\Internal\Type\ParseTree;
 use Psalm\Type;
+use function array_map;
+use function array_values;
 use function trim;
 use function substr_count;
 use function strlen;
@@ -22,6 +26,7 @@
 use function count;
 use function reset;
 use function preg_split;
+use function var_dump;
 use const PREG_SPLIT_DELIM_CAPTURE;
 use const PREG_SPLIT_NO_EMPTY;
 use function array_shift;
@@ -241,11 +246,21 @@ public static function arrayToDocblocks(
      */
     public static function getTypeAliasesFromComment(
         PhpParser\Comment\Doc $comment,
+        Codebase $codebase,
         Aliases $aliases,
         array $type_aliases = null
     ) {
         $parsed_docblock = DocComment::parsePreservingLength($comment);
 
+        if (isset($parsed_docblock['specials']['psalm-use'])) {
+
+            // @todo Is it possible to get the Aliases form another class using {@see $codebase}?
+            return [
+                // @todo faking the data
+                'TData' => [['array', 4], ['{', 1], ['name', 4], [':', 1], ['string', 5], ['}', 1]]
+            ];
+        }
+
         if (!isset($parsed_docblock['specials']['psalm-type'])) {
             return [];
         }

src/Psalm/Internal/Visitor/ReflectorVisitor.php

@@ -161,6 +161,7 @@ public function enterNode(PhpParser\Node $node)
                 try {
                     $type_alias_tokens = CommentAnalyzer::getTypeAliasesFromComment(
                         $comment,
+                        $this->codebase,
                         $this->aliases,
                         $this->type_aliases
                     );

tests/AnnotationTest.php

@@ -111,6 +111,54 @@ function getCollection(): Generator
         $this->analyzeFile('somefile.php', new Context());
     }
 
+    /**
+     * @return void
+     */
+    public function testReferenceTypeAliasFromAnotherScopeArray()
+    {
+        $this->expectException(\Psalm\Exception\CodeException::class);
+        $this->expectExceptionMessage(
+            'Argument 1 of Boo\Baz::doIt expects array{name: string}, array{age: int(12)} provided'
+        );
+
+        $this->addFile(
+            'definition.php',
+            '<?php
+                namespace Foo {
+                    /**
+                     * @psalm-type TData = array{name: string}
+                     */
+                    class Bar {}
+                }'
+        );
+
+        $this->addFile(
+            'import.php',
+            '<?php
+                namespace Boo {
+                    class Baz {
+                        /**
+                         * @psalm-use TData from \Foo\Bar
+                         * @psalm-param TData $array
+                         */
+                         public static function doIt(array $array) : void {}
+                    }
+                }'
+        );
+
+        $this->addFile(
+            'client.php',
+            '<?php
+               namespace Bar {
+                    \Boo\Baz::doIt(["age" => 12]);
+               }'
+        );
+
+        $this->analyzeFile('definition.php', new Context());
+        $this->analyzeFile('import.php', new Context());
+        $this->analyzeFile('client.php', new Context());
+    }
+
     /**
      * @return void
      */