chore(openapi): address PR feedback - extract helper functions and add circular reachability test

Author: TristanSpeakEasy

openapi/clean.go

@@ -313,6 +313,31 @@ func trackSecuritySchemeReference(ref *ReferencedSecurityScheme, tracker map[str
 	return nil
 }
 
+// trackOperationTags tracks operation tag names into the tracker
+func trackOperationTags(op *Operation, tracker *referencedComponentTracker) error {
+	if op == nil || tracker == nil {
+		return nil
+	}
+	for _, tag := range op.GetTags() {
+		if tracker.tags == nil {
+			tracker.tags = make(map[string]bool)
+		}
+		tracker.tags[tag] = true
+	}
+	return nil
+}
+
+// trackSecurityRequirementNames tracks security scheme names referenced by a security requirement
+func trackSecurityRequirementNames(req *SecurityRequirement, tracker map[string]bool) error {
+	if req == nil || tracker == nil {
+		return nil
+	}
+	for schemeName := range req.All() {
+		tracker[schemeName] = true
+	}
+	return nil
+}
+
 // extractComponentName extracts the component name from a reference string
 func extractComponentName(refStr, componentType string) string {
 	prefix := "#/components/" + componentType + "/"
@@ -575,25 +600,11 @@ func walkAndTrackWithFilter(ctx context.Context, doc *OpenAPI, tracker *referenc
 			},
 			// Track operation tags (only under allowed locations)
 			Operation: func(op *Operation) error {
-				if op == nil {
-					return nil
-				}
-				for _, tag := range op.GetTags() {
-					if tracker.tags == nil {
-						tracker.tags = make(map[string]bool)
-					}
-					tracker.tags[tag] = true
-				}
-				return nil
+				return trackOperationTags(op, tracker)
 			},
 			// Track security requirements (special case for security schemes)
 			Security: func(req *SecurityRequirement) error {
-				if req != nil {
-					for schemeName := range req.All() {
-						tracker.securitySchemes[schemeName] = true
-					}
-				}
-				return nil
+				return trackSecurityRequirementNames(req, tracker.securitySchemes)
 			},
 		})
 		if err != nil {

openapi/clean_paths_reachability_test.go

@@ -218,3 +218,67 @@ paths: {}
 
 	assert.Equal(t, expected, actual, "All components should be removed when only self/component-only references exist")
 }
+
+func TestClean_Reachability_CircularSchemas_Success(t *testing.T) {
+	t.Parallel()
+	ctx := t.Context()
+
+	const yml = `
+openapi: 3.1.0
+info:
+  title: Test API
+  version: 1.0.0
+paths:
+  /keep:
+    get:
+      responses:
+        "200":
+          description: ok
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Cycle1"
+components:
+  schemas:
+    Cycle1:
+      $ref: "#/components/schemas/Cycle2"
+    Cycle2:
+      $ref: "#/components/schemas/Cycle1"
+`
+
+	doc, validationErrs, err := openapi.Unmarshal(ctx, strings.NewReader(yml))
+	require.NoError(t, err, "unmarshal should succeed")
+	require.Empty(t, validationErrs, "input should be valid")
+
+	err = openapi.Clean(ctx, doc)
+	require.NoError(t, err, "clean should succeed")
+
+	var buf bytes.Buffer
+	err = openapi.Marshal(ctx, doc, &buf)
+	require.NoError(t, err, "marshal should succeed")
+	actual := buf.String()
+
+	const expected = `openapi: 3.1.0
+info:
+  title: Test API
+  version: 1.0.0
+paths:
+  /keep:
+    get:
+      responses:
+        "200":
+          description: ok
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Cycle1"
+components:
+  schemas:
+    Cycle1:
+      $ref: "#/components/schemas/Cycle2"
+    Cycle2:
+      $ref: "#/components/schemas/Cycle1"
+`
+
+	assert.Equal(t, expected, actual, "Clean should keep circularly referenced components reachable from paths without hanging")
+}