fix(what-changed): don't flag object->composition wrap as breaking

When an object schema is refactored into a oneOf/anyOf that still contains
that object as one of its branches, every value valid before is still valid,
so the change is not breaking. Two common cases were reported as breaking:

  1. An inline object hoisted into a reusable component and referenced via
     `oneOf: [$ref, {type: null}]`. The node diff never resolved the $ref, so
     the object's properties/required looked removed.
  2. An object widened into `anyOf: [<same object>, <new alternative>]`. The
     top-level node changed from an object to an anyOf, so its properties
     looked removed.

CompareSchemas now detects the wrapping direction (old = plain object,
new = oneOf/anyOf that preserves that object as a branch, following local
$refs) and compares the old object against the preserved branch directly.
Genuine, e.g. property-level, changes are still surfaced; only the spurious
top-level properties/required/type removal is suppressed. Nullability must be
preserved (a null-accepting branch) or the fix does not fire. The reverse
direction (a composition collapsing to a single schema, which can drop
alternatives) is intentionally left breaking.

Adds regression tests for both non-breaking cases plus guards proving
unwrapping, non-preserving replacements, genuine property removal, and
dropped nullability all stay breaking.

Author: libopenapi contributor

what-changed/model/schema.go

@@ -498,6 +498,17 @@ func CompareSchemas(l, r *base.SchemaProxy) *SchemaChanges {
 		comparisonLSchema := schemaComparisonViewForSimpleAllOfObject(l, lSchema)
 		comparisonRSchema := schemaComparisonViewForSimpleAllOfObject(r, rSchema)
 
+		// A plain object refactored into a oneOf/anyOf that still contains that object as a branch
+		// (often behind a local $ref, or an "object OR <alternative>" widening) is not a breaking
+		// change — everything valid before is still valid. Compare the old object against the
+		// preserved branch directly so genuine changes are still detected, and suppress the spurious
+		// top-level properties/required/type removal that the wrapper would otherwise produce.
+		skipPreservedCompositionDiff := false
+		if preservedBranch, ok := preservedCompositionBranchView(l, r); ok {
+			comparisonRSchema = preservedBranch
+			skipPreservedCompositionDiff = true
+		}
+
 		if low.AreEqual(lSchema, rSchema) {
 			// there is no point going on, we know nothing changed!
 			return nil
@@ -512,7 +523,8 @@ func CompareSchemas(l, r *base.SchemaProxy) *SchemaChanges {
 		skipSimpleScalarUnionDiff := schemasUseEquivalentSimpleScalarUnion(l, r)
 
 		// check schema core properties for changes.
-		checkSchemaPropertyChanges(comparisonLSchema, comparisonRSchema, l, r, &changes, sc, skipSimpleScalarUnionDiff)
+		checkSchemaPropertyChanges(comparisonLSchema, comparisonRSchema, l, r, &changes, sc,
+			skipSimpleScalarUnionDiff || skipPreservedCompositionDiff)
 
 		// now for the confusing part, there is also a schema's 'properties' property to parse.
 		// inception, eat your heart out.
@@ -544,6 +556,12 @@ func CompareSchemas(l, r *base.SchemaProxy) *SchemaChanges {
 			lanyOf = nil
 			ranyOf = nil
 		}
+		if skipPreservedCompositionDiff {
+			// The preserved branch is now folded into comparisonRSchema; don't also diff the wrapper
+			// composition itself (it would resurface as an added oneOf/anyOf).
+			roneOf = nil
+			ranyOf = nil
+		}
 
 		props := checkMappedSchemaOfASchema(lProperties, rProperties, &changes)
 		sc.SchemaPropertyChanges = props
@@ -2108,6 +2126,169 @@ func extractScalarTypeName(node *yaml.Node) (string, bool) {
 	return node.Value, true
 }
 
+// preservedCompositionBranchView detects the "wrapping" refactor where an OLD plain object schema is
+// reshaped into a NEW oneOf/anyOf composition that still contains that object as one of its branches
+// (commonly behind a local $ref when a schema is hoisted into a reusable component, or an
+// "object OR <alternative>" widening). Because the original object is still one of the accepted
+// shapes, every previously-valid value remains valid, so nothing was removed — but a naive
+// node-level diff sees the top-level `properties`/`required`/`type` vanish and reports them as
+// breaking removals.
+//
+// When the wrap is detected, the resolved "preserved" branch schema is returned so the caller can
+// compare the OLD object against that branch directly. That keeps genuine, e.g. property-level,
+// changes visible while dropping the spurious top-level removal signals. Only the wrapping direction
+// (l = old, r = new) is handled: the reverse (a composition collapsing to a single schema) can drop
+// alternatives and must remain breaking, so it is intentionally not matched here.
+func preservedCompositionBranchView(l, r *base.SchemaProxy) (*base.Schema, bool) {
+	if l == nil || r == nil || l.IsReference() || r.IsReference() {
+		return nil, false
+	}
+	lSchema := l.Schema()
+	rSchema := r.Schema()
+	if lSchema == nil || rSchema == nil {
+		return nil, false
+	}
+
+	// OLD must be a plain object carrying properties and no composition of its own.
+	if !schemaIsPlainObjectWithProperties(lSchema) {
+		return nil, false
+	}
+
+	// NEW must be a pure oneOf/anyOf wrapper (exactly one of the two, no competing top-level keys).
+	branches, ok := schemaWrappingCompositionBranches(rSchema)
+	if !ok {
+		return nil, false
+	}
+
+	// Find exactly one branch that preserves all of OLD's property names (the object, possibly
+	// evolved), resolving local $refs. Any additional branches are treated as added alternatives.
+	var primary *base.Schema
+	primaryCount := 0
+	compositionAcceptsNull := false
+	for _, branch := range branches {
+		if branch.Value == nil || base.CheckSchemaProxyForCircularRefs(branch.Value) {
+			return nil, false
+		}
+		branchSchema := branch.Value.Schema()
+		if branchSchema == nil {
+			return nil, false
+		}
+		if schemaTypeAcceptsNull(branchSchema) {
+			compositionAcceptsNull = true
+		}
+		if schemaPreservesObjectProperties(lSchema, branchSchema) {
+			primary = branchSchema
+			primaryCount++
+		}
+	}
+	if primaryCount != 1 || primary == nil {
+		return nil, false
+	}
+
+	// Nullability must be preserved: if OLD accepted null, NEW must still accept it (via a null
+	// branch or the preserved branch itself), otherwise dropping null is a real narrowing.
+	if schemaTypeAcceptsNull(lSchema) && !compositionAcceptsNull && !schemaTypeAcceptsNull(primary) {
+		return nil, false
+	}
+
+	return primary, true
+}
+
+// schemaWrappingCompositionBranches returns the branches of a schema that is a pure oneOf/anyOf
+// wrapper (exactly one of oneOf/anyOf, and no top-level properties/allOf/prefixItems/not that would
+// make it more than a wrapper). allOf is intentionally excluded — it is handled by
+// schemaComparisonViewForSimpleAllOfObject.
+func schemaWrappingCompositionBranches(schema *base.Schema) ([]low.ValueReference[*base.SchemaProxy], bool) {
+	if schema == nil {
+		return nil, false
+	}
+	if schemaHasProperties(schema) || len(schema.AllOf.Value) > 0 ||
+		len(schema.PrefixItems.Value) > 0 || schema.Not.Value != nil {
+		return nil, false
+	}
+	oneOf := schema.OneOf.Value
+	anyOf := schema.AnyOf.Value
+	switch {
+	case len(oneOf) > 0 && len(anyOf) == 0:
+		return oneOf, true
+	case len(anyOf) > 0 && len(oneOf) == 0:
+		return anyOf, true
+	default:
+		return nil, false
+	}
+}
+
+// schemaPreservesObjectProperties reports whether branch is an object that keeps every property name
+// declared on l (branch may add or widen properties — those are surfaced by the normal recursive
+// diff — but it must not drop any, which is what distinguishes the preserved object from an
+// unrelated alternative branch).
+func schemaPreservesObjectProperties(l, branch *base.Schema) bool {
+	if !schemaHasProperties(branch) || !schemaTypeIncludesObject(branch) {
+		return false
+	}
+	branchNames := make(map[string]struct{}, branch.Properties.Value.Len())
+	for k := range branch.Properties.Value.FromOldest() {
+		branchNames[k.Value] = struct{}{}
+	}
+	for k := range l.Properties.Value.FromOldest() {
+		if _, ok := branchNames[k.Value]; !ok {
+			return false
+		}
+	}
+	return true
+}
+
+func schemaIsPlainObjectWithProperties(schema *base.Schema) bool {
+	return schemaHasProperties(schema) && schemaTypeIncludesObject(schema) && !schemaHasComposition(schema)
+}
+
+func schemaHasProperties(schema *base.Schema) bool {
+	return schema != nil && schema.Properties.Value != nil && schema.Properties.Value.Len() > 0
+}
+
+func schemaHasComposition(schema *base.Schema) bool {
+	if schema == nil {
+		return false
+	}
+	return len(schema.OneOf.Value) > 0 || len(schema.AnyOf.Value) > 0 || len(schema.AllOf.Value) > 0 ||
+		len(schema.PrefixItems.Value) > 0 || schema.Not.Value != nil
+}
+
+// schemaTypeIncludesObject reports whether the schema's declared type admits objects. A schema with
+// no explicit type but with properties is treated as an object.
+func schemaTypeIncludesObject(schema *base.Schema) bool {
+	if schema == nil {
+		return false
+	}
+	if schema.Type.IsEmpty() {
+		return schemaHasProperties(schema)
+	}
+	if schema.Type.Value.IsB() {
+		for _, t := range schema.Type.Value.B {
+			if t.Value == "object" {
+				return true
+			}
+		}
+		return false
+	}
+	return schema.Type.Value.A == "object"
+}
+
+func schemaTypeAcceptsNull(schema *base.Schema) bool {
+	if schema == nil || schema.Type.IsEmpty() {
+		return false
+	}
+	if schema.Type.Value.IsB() {
+		for _, t := range schema.Type.Value.B {
+			if t.Value == "null" {
+				return true
+			}
+		}
+		return false
+	}
+	return schema.Type.Value.A == "null"
+}
+
 func checkExamples(lSchema *base.Schema, rSchema *base.Schema, changes *[]*Change) {
 	if lSchema == nil && rSchema == nil {
 		return