fix: resolve stack overflow with circular schema references

kin-openapi's Validate() crashes with a stack overflow when schemas have
circular $ref references (e.g. discriminator/inheritance patterns). The
crash occurs in the visitJSON codepath which validates default/example
values against schemas without cycle detection.

- slice/split: pass DisableSchemaDefaultsValidation and
  DisableExamplesValidation to Validate() to skip the unsafe visitJSON
  codepath while keeping structural schema validation
- filter: resolve $ref pointers in duplicateOas using ResolveRefsIn so
  that the duplicate is a proper kin-openapi object with populated .Value
  fields
- extension: skip recursing into $ref SchemaRefs in
  updateExtensionsForSchema to avoid infinite recursion on circular refs
- versioning: skip $ref responses in updateResponses to avoid mutating
  shared component responses during per-operation versioning

Author: andmatei

tools/cli/internal/cli/slice/slice.go

@@ -19,6 +19,7 @@ import (
 	"fmt"
 	"log"
 
+	"github.com/getkin/kin-openapi/openapi3"
 	"github.com/mongodb/openapi/tools/cli/internal/cli/flag"
 	"github.com/mongodb/openapi/tools/cli/internal/cli/usage"
 	"github.com/mongodb/openapi/tools/cli/internal/openapi"
@@ -66,8 +67,13 @@ func (o *Opts) Run() error {
 		return err
 	}
 
-	// Validate the sliced spec
-	if err := specInfo.Spec.Validate(loader.Loader.Context); err != nil {
+	// Validate the sliced spec structure (skip defaults/examples validation
+	// to avoid stack overflow with circular schema references in kin-openapi).
+	ctx := openapi3.WithValidationOptions(loader.Loader.Context,
+		openapi3.DisableSchemaDefaultsValidation(),
+		openapi3.DisableExamplesValidation(),
+	)
+	if err := specInfo.Spec.Validate(ctx); err != nil {
 		log.Printf("[WARN] Sliced OpenAPI document has validation warnings: %v", err)
 	}
 

tools/cli/internal/cli/split/split.go

@@ -65,7 +65,13 @@ func (o *Opts) Run() error {
 			return err
 		}
 
-		if err := filteredOAS.Validate(loader.Loader.Context); err != nil {
+		// Validate the spec structure (skip defaults/examples validation
+		// to avoid stack overflow with circular schema references in kin-openapi).
+		ctx := openapi3.WithValidationOptions(loader.Loader.Context,
+			openapi3.DisableSchemaDefaultsValidation(),
+			openapi3.DisableExamplesValidation(),
+		)
+		if err := filteredOAS.Validate(ctx); err != nil {
 			log.Printf("[WARN] OpenAPI document is invalid: %v", err)
 		}
 	}

tools/cli/internal/openapi/filter/extension.go

@@ -156,6 +156,12 @@ func (f *ExtensionFilter) updateExtensionsForSchema(schema *openapi3.SchemaRef)
 	}
 	f.deleteIpaExceptionExtensionIfNeeded(schema.Extensions)
 
+	// If this is a $ref, don't recurse into .Value — the referenced schema
+	// will be visited via updateExtensionsForComponents.
+	if isRef(schema) {
+		return
+	}
+
 	if schema.Value == nil {
 		return
 	}

tools/cli/internal/openapi/filter/filter.go

@@ -155,11 +155,20 @@ func duplicateOas(doc *openapi3.T) (*openapi3.T, error) {
 
 	// Unmarshal the JSON data into a new OpenAPI document
 	duplicateDoc := &openapi3.T{}
-	err = json.Unmarshal(jsonData, duplicateDoc)
-	if err != nil {
+	if err = json.Unmarshal(jsonData, duplicateDoc); err != nil {
 		return nil, fmt.Errorf("failed to unmarshal duplicated OpenAPI specification: %w", err)
 	}
 
+	// Resolve $ref pointers so that SchemaRef.Value (and other ref types) are
+	// populated. Without this, filters that walk schemas would see nil .Value
+	// on every $ref. We use ResolveRefsIn rather than LoadFromData because the
+	// loader's full pipeline normalizes media types and other structures, which
+	// would change the output.
+	loader := openapi3.NewLoader()
+	if err = loader.ResolveRefsIn(duplicateDoc, nil); err != nil {
+		return nil, fmt.Errorf("failed to resolve refs in duplicated OpenAPI specification: %w", err)
+	}
+
 	return duplicateDoc, nil
 }
 

tools/cli/internal/openapi/filter/versioning.go

@@ -134,6 +134,12 @@ func updateResponses(op *openapi3.Operation, config *VersionConfig) error {
 			continue
 		}
 
+		// Skip $ref responses — they point to shared component responses
+		// that should not be mutated by per-operation versioning filters.
+		if response.Ref != "" {
+			continue
+		}
+
 		filteredResponse, err := filterResponse(response, op, config)
 		if err != nil {
 			return err