fix: remove consumed annotations from analysis registry

Add Analysis::removeAnnotation() and use it in all processors that
consume/merge annotations. MergeJsonContent and MergeXmlContent now
properly remove the original JsonContent/XmlContent from the analysis
after transforming them into MediaType + Schema, preventing orphan
annotations from appearing in validation.

Replaces all direct $analysis->annotations->offsetUnset() calls with
the new method for consistency.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: DerManoMann

src/Analysis.php

@@ -97,6 +97,11 @@ public function addAnnotation(OA\AbstractAnnotation $annotation, Context $contex
         }
     }
 
+    public function removeAnnotation(OA\AbstractAnnotation $annotation): void
+    {
+        $this->annotations->offsetUnset($annotation);
+    }
+
     /**
      * @param list<OA\AbstractAnnotation> $annotations
      */

src/Processors/AugmentRefs.php

@@ -88,7 +88,7 @@ protected function removeDuplicateRefs(Analysis $analysis): void
                     if (!Generator::isDefault($allOfSchema->ref)) {
                         if (in_array($allOfSchema->ref, $refs)) {
                             $dupes[] = $allOfSchema->ref;
-                            $analysis->annotations->offsetUnset($allOfSchema);
+                            $analysis->removeAnnotation($allOfSchema);
                             unset($schema->allOf[$ii]);
                             continue;
                         }

src/Processors/AugmentTags.php

@@ -104,7 +104,7 @@ private function removeUnusedTags(array $usedTagNames, array $declaredTags, Anal
         foreach ($declaredTags as $tag) {
             if (!in_array($tag->name, $tagsToKeep)) {
                 if (false !== $index = array_search($tag, $analysis->openapi->tags, true)) {
-                    $analysis->annotations->offsetUnset($tag);
+                    $analysis->removeAnnotation($tag);
                     unset($analysis->openapi->tags[$index]);
                     $analysis->openapi->tags = array_values($analysis->openapi->tags);
                 }

src/Processors/BuildPaths.php

@@ -26,7 +26,7 @@ public function __invoke(Analysis $analysis): void
                     $annotation->_context->logger->warning($annotation->identity() . ' is missing required property "path" in ' . $annotation->_context);
                 } elseif (isset($paths[$annotation->path])) {
                     $paths[$annotation->path]->mergeProperties($annotation);
-                    $analysis->annotations->offsetUnset($annotation);
+                    $analysis->removeAnnotation($annotation);
                 } else {
                     $paths[$annotation->path] = $annotation;
                 }

src/Processors/MergeIntoOpenApi.php

@@ -98,7 +98,7 @@ public function __invoke(Analysis $analysis): void
                         }
                     }
 
-                    $analysis->annotations->offsetUnset($components);
+                    $analysis->removeAnnotation($components);
                 }
 
                 $merge = array_filter($merge, static fn (OA\AbstractAnnotation $annotation): bool => !$annotation instanceof OA\Components);

src/Processors/MergeJsonContent.php

@@ -53,6 +53,7 @@ public function __invoke(Analysis $analysis): void
             if ($index !== false) {
                 array_splice($parent->_unmerged, $index, 1);
             }
+            $analysis->removeAnnotation($jsonContent);
         }
     }
 }

src/Processors/MergeXmlContent.php

@@ -50,6 +50,7 @@ public function __invoke(Analysis $analysis): void
             if ($index !== false) {
                 array_splice($parent->_unmerged, $index, 1);
             }
+            $analysis->removeAnnotation($xmlContent);
         }
     }
 }