Add SelfOut attribute

Author: carlos-granados

composer.json

@@ -25,7 +25,7 @@
     "require": {
         "php": ">=8.0",
         "nikic/php-parser": "^4 || ^5",
-        "php-static-analysis/attributes": "^0.1.12 || dev-main"
+        "php-static-analysis/attributes": "^0.1.13 || dev-main"
     },
     "require-dev": {
         "php-static-analysis/phpstan-extension": "dev-main",

src/AttributeNodeVisitor.php

@@ -22,6 +22,7 @@
 use PhpStaticAnalysis\Attributes\PropertyRead;
 use PhpStaticAnalysis\Attributes\PropertyWrite;
 use PhpStaticAnalysis\Attributes\Returns;
+use PhpStaticAnalysis\Attributes\SelfOut;
 use PhpStaticAnalysis\Attributes\Template;
 use PhpStaticAnalysis\Attributes\TemplateContravariant;
 use PhpStaticAnalysis\Attributes\TemplateCovariant;
@@ -34,7 +35,8 @@ class AttributeNodeVisitor extends NodeVisitorAbstract
 {
     private const ARGS_NONE = 'none';
     private const ARGS_ONE = 'one';
-    private const ARGS_ONE_OPTIONAL = 'one_optional';
+    private const ARGS_ONE_OPTIONAL = 'one optional';
+    private const ARGS_ONE_WITH_PREFIX = 'one with prefix';
     private const ARGS_TWO_WITH_TYPE = 'two with type';
     private const ARGS_MANY_IN_USE = "many in use";
     private const ARGS_MANY_WITH_NAME = "many with name";
@@ -77,6 +79,7 @@ class AttributeNodeVisitor extends NodeVisitorAbstract
             Param::class,
             ParamOut::class,
             Returns::class,
+            SelfOut::class,
             Template::class,
             Type::class,
         ],
@@ -134,6 +137,7 @@ class AttributeNodeVisitor extends NodeVisitorAbstract
         'PropertyRead' => PropertyRead::class,
         'PropertyWrite' => PropertyWrite::class,
         'Returns' => Returns::class,
+        'SelfOut' => SelfOut::class,
         'Template' => Template::class,
         'TemplateContravariant' => TemplateContravariant::class,
         'TemplateCovariant' => TemplateCovariant::class,
@@ -178,6 +182,9 @@ class AttributeNodeVisitor extends NodeVisitorAbstract
         Returns::class => [
             'all' => 'return',
         ],
+        SelfOut::class => [
+            'all' => 'self-out',
+        ],
         Template::class => [
             'all' => 'template',
         ],
@@ -239,6 +246,9 @@ class AttributeNodeVisitor extends NodeVisitorAbstract
         Returns::class => [
             'all' => self::ARGS_ONE,
         ],
+        SelfOut::class => [
+            'all' => self::ARGS_ONE_WITH_PREFIX,
+        ],
         Template::class => [
             'all' => self::ARGS_TWO_WITH_TYPE,
         ],
@@ -318,6 +328,12 @@ public function enterNode(Node $node)
                                     $tagCreated = true;
                                 }
                                 break;
+                            case self::ARGS_ONE_WITH_PREFIX:
+                                if (isset($args[0])) {
+                                    $tagsToAdd[] = $this->createTag($nodeType, $attributeName, $args[0], prefix: $this->toolType);
+                                    $tagCreated = true;
+                                }
+                                break;
                             case self::ARGS_ONE_OPTIONAL:
                                 if (isset($args[0])) {
                                     $tagsToAdd[] = $this->createTag(
@@ -393,7 +409,7 @@ private function createTag(
         } else {
             return '';
         }
-        if ($prefix !== null) {
+        if ($prefix !== null && $prefix !== '') {
             $tagName = $prefix . '-' . $tagName;
         }
         $tag = '@' . $tagName;

tests/SelfOutAttributeNodeVisitorTest.php

@@ -0,0 +1,31 @@
+<?php
+
+namespace test\PhpStaticAnalysis\NodeVisitor;
+
+use PhpParser\Node;
+use PhpParser\Node\Attribute;
+use PhpParser\Node\AttributeGroup;
+use PhpParser\Node\Name\FullyQualified;
+use PhpStaticAnalysis\Attributes\SelfOut;
+
+class SelfOutAttributeNodeVisitorTest extends AttributeNodeVisitorTestBase
+{
+    public function testAddsReturnPHPDoc(): void
+    {
+        $node = new Node\Stmt\ClassMethod('Test');
+        $this->addSelfOutAttributeToNode($node);
+        $this->nodeVisitor->enterNode($node);
+        $docText = $this->getDocText($node);
+        $this->assertEquals("/**\n * @self-out self<T>\n */", $docText);
+    }
+
+    private function addSelfOutAttributeToNode(Node\Stmt\ClassMethod $node): void
+    {
+        $args = [
+            new Node\Arg(new Node\Scalar\String_('self<T>'))
+        ];
+        $attributeName = new FullyQualified(SelfOut::class);
+        $attribute = new Attribute($attributeName, $args);
+        $node->attrGroups = [new AttributeGroup([$attribute])];
+    }
+}