Enhance DocblockExtractor and DocblockNormalizer; add support for template tags and improve normalization of PHPStan-specific annotations

Author: rcalicdan

src/Contract/DocblockExtractor.php

@@ -175,6 +175,12 @@ public static function extractTemplates(PhpDocNode $node): array
             }
         }
 
+        foreach ($node->getTags() as $tagNode) {
+            if ($tagNode->value instanceof TemplateTagValueNode && ! isset($templates[$tagNode->value->name])) {
+                $templates[$tagNode->value->name] = $tagNode->value;
+            }
+        }
+
         return $templates;
     }
 
@@ -212,6 +218,19 @@ public static function extractTemplateVariances(PhpDocNode $node): array
             }
         }
 
+        foreach ($node->getTags() as $tagNode) {
+            if ($tagNode->value instanceof TemplateTagValueNode && ! isset($variances[$tagNode->value->name])) {
+                $lowerTag = strtolower($tagNode->name);
+                if (str_contains($lowerTag, 'covariant')) {
+                    $variances[$tagNode->value->name] = 'covariant';
+                } elseif (str_contains($lowerTag, 'contravariant')) {
+                    $variances[$tagNode->value->name] = 'contravariant';
+                } else {
+                    $variances[$tagNode->value->name] = 'invariant';
+                }
+            }
+        }
+
         return $variances;
     }
 
@@ -223,29 +242,14 @@ public static function extractTemplateVariances(PhpDocNode $node): array
     public static function getInheritedTags(PhpDocNode $node): array
     {
         $tags = [];
-        $tagNames = [
-            '@extends',
-            '@template-extends',
-            '@phpstan-extends',
-            '@psalm-extends',
-            '@implements',
-            '@template-implements',
-            '@phpstan-implements',
-            '@psalm-implements',
-            '@use',
-            '@template-use',
-            '@phpstan-use',
-        ];
 
-        foreach ($tagNames as $name) {
-            foreach ($node->getTagsByName($name) as $tagNode) {
-                if (
-                    $tagNode->value instanceof \PHPStan\PhpDocParser\Ast\PhpDoc\ExtendsTagValueNode ||
-                    $tagNode->value instanceof \PHPStan\PhpDocParser\Ast\PhpDoc\ImplementsTagValueNode ||
-                    $tagNode->value instanceof \PHPStan\PhpDocParser\Ast\PhpDoc\UsesTagValueNode
-                ) {
-                    $tags[] = $tagNode->value;
-                }
+        foreach ($node->getTags() as $tagNode) {
+            if (
+                $tagNode->value instanceof \PHPStan\PhpDocParser\Ast\PhpDoc\ExtendsTagValueNode ||
+                $tagNode->value instanceof \PHPStan\PhpDocParser\Ast\PhpDoc\ImplementsTagValueNode ||
+                $tagNode->value instanceof \PHPStan\PhpDocParser\Ast\PhpDoc\UsesTagValueNode
+            ) {
+                $tags[] = $tagNode->value;
             }
         }
 
@@ -424,4 +428,4 @@ public static function extractMagicMethodContract(string $doc, string $methodNam
 
         return null;
     }
-}
+}

src/Internal/DocblockNormalizer.php

@@ -29,6 +29,9 @@ final class DocblockNormalizer
     public static function normalize(string $doc): string
     {
         $doc = preg_replace('/(@(?:phpstan|psalm)-type\s+[a-zA-Z0-9_\x80-\xff]+)\s*=\s*/', '$1 ', $doc) ?? $doc;
+        $doc = preg_replace('/@(template-(?:covariant|contravariant))/', '@phpstan-$1', $doc) ?? $doc;
+        $doc = preg_replace('/@(template-extends|template-implements|template-use)/', '@phpstan-$1', $doc) ?? $doc;
+        $doc = preg_replace('/@use(\s+[\\\\a-zA-Z0-9_\x80-\xff]+<)/', '@phpstan-use$1', $doc) ?? $doc;
         $doc = preg_replace('/(callable|Closure)\s*\(([^)]*)\)(?!\s*:)/', '$1($2): mixed', $doc) ?? $doc;
         $doc = preg_replace('/(\\\\?[a-zA-Z_\x80-\xff][\\\\a-zA-Z0-9_\x80-\xff]*::[a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*)\s*(\??:)/', '"$1"$2', $doc) ?? $doc;
 
@@ -52,4 +55,4 @@ function (array $matches): string {
             $doc
         ) ?? $doc;
     }
-}
+}