From c08f5edd7d497517c5b2fe79d4753a492e6b81ce Mon Sep 17 00:00:00 2001
From: DerManoMann <mano@radebatz.net>
Date: Tue, 30 Jun 2026 13:06:15 +1200
Subject: [PATCH] Use `Analysis::removeAnnotation()` in
 MergeControllerDefaults; deprecate `clearUnusedPaths`

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 src/OpenApiBuilder.php                     |  2 +-
 src/Processors/MergeControllerDefaults.php | 23 +++++++++++++---------
 2 files changed, 15 insertions(+), 10 deletions(-)

diff --git a/src/OpenApiBuilder.php b/src/OpenApiBuilder.php
index df9dcd3..9ad4fcd 100644
--- a/src/OpenApiBuilder.php
+++ b/src/OpenApiBuilder.php
@@ -65,7 +65,7 @@ public function tagsToMatch($tags): OpenApiBuilder
     }
 
     /**
-     * Enable/disable recursive cleanup of unused paths and their nested annotations.
+     * @deprecated will be removed in the next major version
      */
     public function clearUnusedPaths(bool $enabled = true): OpenApiBuilder
     {
diff --git a/src/Processors/MergeControllerDefaults.php b/src/Processors/MergeControllerDefaults.php
index d1ddd9e..a178806 100644
--- a/src/Processors/MergeControllerDefaults.php
+++ b/src/Processors/MergeControllerDefaults.php
@@ -20,7 +20,7 @@ public function __invoke(Analysis $analysis): void
         foreach ($operations as $operation) {
             $chain = $this->resolveControllerChain($operation->_context, $controllerMap, $analysis);
             if ($chain !== []) {
-                $this->applyChain($operation, $chain);
+                $this->applyChain($analysis, $operation, $chain);
             }
         }
 
@@ -95,7 +95,7 @@ protected function resolveControllerChain(?Context $operationContext, array $con
     /**
      * @param OAX\Controller[] $chain
      */
-    protected function applyChain(OA\Operation $operation, array $chain): void
+    protected function applyChain(Analysis $analysis, OA\Operation $operation, array $chain): void
     {
         $mergedPrefix = '';
         $mergedTags = [];
@@ -133,9 +133,9 @@ protected function applyChain(OA\Operation $operation, array $chain): void
 
         $this->applyPrefix($operation, $mergedPrefix);
         $this->applyTags($operation, $mergedTags);
-        $this->applyResponses($operation, $mergedResponses);
-        $this->applyHeaders($operation, $mergedHeaders);
-        $this->applyMiddlewares($operation, $mergedMiddlewares);
+        $this->applyResponses($analysis, $operation, $mergedResponses);
+        $this->applyHeaders($analysis, $operation, $mergedHeaders);
+        $this->applyMiddlewares($analysis, $operation, $mergedMiddlewares);
     }
 
     protected function applyPrefix(OA\Operation $operation, string $mergedPrefix): void
@@ -162,7 +162,7 @@ protected function applyTags(OA\Operation $operation, array $mergedTags): void
     /**
      * @param array<string|int, OA\Response> $mergedResponses
      */
-    protected function applyResponses(OA\Operation $operation, array $mergedResponses): void
+    protected function applyResponses(Analysis $analysis, OA\Operation $operation, array $mergedResponses): void
     {
         if ($mergedResponses !== []) {
             $operation->merge(array_values($mergedResponses), true);
@@ -172,7 +172,7 @@ protected function applyResponses(OA\Operation $operation, array $mergedResponse
     /**
      * @param array<string, OA\Header> $mergedHeaders
      */
-    protected function applyHeaders(OA\Operation $operation, array $mergedHeaders): void
+    protected function applyHeaders(Analysis $analysis, OA\Operation $operation, array $mergedHeaders): void
     {
         if ($mergedHeaders && !Generator::isDefault($operation->responses)) {
             foreach ($operation->responses as $response) {
@@ -211,7 +211,7 @@ protected function collectMiddlewares(mixed $attachables, array $mergedMiddlewar
     /**
      * @param array<string, OAX\Middleware> $mergedMiddlewares
      */
-    protected function applyMiddlewares(OA\Operation $operation, array $mergedMiddlewares): void
+    protected function applyMiddlewares(Analysis $analysis, OA\Operation $operation, array $mergedMiddlewares): void
     {
         if ($mergedMiddlewares === []) {
             return;
@@ -237,7 +237,12 @@ protected function clearMerged(Analysis $analysis, $annotations): void
         $annotations = is_array($annotations) ? $annotations : [$annotations];
 
         foreach ($annotations as $annotation) {
-            $analysis->annotations->offsetUnset($annotation);
+            /* @phpstan-ignore function.alreadyNarrowedType */
+            if (method_exists($analysis, 'removeAnnotation')) {
+                $analysis->removeAnnotation($annotation);
+            } else {
+                $analysis->annotations->offsetUnset($annotation);
+            }
         }
     }
 }