fix: enhance annotation parsing to support multiple values per tag

Author: jackd248

src/Rules/DocBlockHeaderFixer.php

@@ -327,7 +327,7 @@ private function findInsertPosition(Tokens $tokens, int $structureIndex): int
     }
 
     /**
-     * @return array<string, string>
+     * @return array<string, string|array<string>>
      */
     private function parseExistingAnnotations(string $docBlockContent): array
     {
@@ -339,15 +339,27 @@ private function parseExistingAnnotations(string $docBlockContent): array
             if (preg_match('/^@(\w+)(?:\s+(.*))?$/', $line, $matches)) {
                 $tag = $matches[1];
                 $value = $matches[2] ?? '';
-                $annotations[$tag] = $value;
+
+                // If this tag already exists, convert to array or append to existing array
+                if (isset($annotations[$tag])) {
+                    // Convert existing single value to array
+                    if (!is_array($annotations[$tag])) {
+                        $annotations[$tag] = [$annotations[$tag]];
+                    }
+                    // Append new value to array
+                    $annotations[$tag][] = $value;
+                } else {
+                    // First occurrence, store as string
+                    $annotations[$tag] = $value;
+                }
             }
         }
 
         return $annotations;
     }
 
     /**
-     * @param array<string, string>               $existing
+     * @param array<string, string|array<string>> $existing
      * @param array<string, string|array<string>> $new
      *
      * @return array<string, string|array<string>>