feat: Implement validation for OpenAPI composition structures and add integration tests

Author: developerkunal

internal/transform/flatten.go

@@ -77,6 +77,12 @@ func processFlatteningInFile(path string, opts FlattenOptions, result *FlattenRe
 
 // processDocumentFlattening processes flattening in a document
 func processDocumentFlattening(doc, root *yaml.Node, path string, opts FlattenOptions, result *FlattenResult) (bool, error) {
+	// Validate composition structures before processing
+	if validationErrors := ValidateAndReportCompositions(root, path); validationErrors != "" {
+		// Log validation warnings but continue processing
+		fmt.Printf("⚠️  Validation warnings for %s:\n%s", path, validationErrors)
+	}
+
 	// Track component references before flattening to identify unused ones later
 	componentsBefore := extractComponentRefs(root)
 
@@ -381,7 +387,11 @@ func flattenSchemaNode(node *yaml.Node, schemaName, path string, result *Flatten
 
 		switch key {
 		case "oneOf", "anyOf", "allOf":
-			if refValue := getSingleRefFromArray(value); refValue != "" {
+			if isEmptyComposition(value) {
+				// Handle empty composition by removing it entirely
+				handleEmptyComposition(node, i, schemaName, key, path, result)
+				changed = true
+			} else if refValue := getSingleRefFromArray(value); refValue != "" {
 				// Replace the oneOf/anyOf/allOf with direct $ref
 				node.Content[i] = &yaml.Node{Kind: yaml.ScalarNode, Value: "$ref"}
 				node.Content[i+1] = &yaml.Node{Kind: yaml.ScalarNode, Value: refValue}
@@ -393,6 +403,54 @@ func flattenSchemaNode(node *yaml.Node, schemaName, path string, result *Flatten
 				}
 				result.FlattenedRefs[path] = append(result.FlattenedRefs[path], flattenedPath)
 				changed = true
+			} else if singleSchema := getSingleSchemaFromArray(value); singleSchema != nil {
+				// Replace the oneOf/anyOf/allOf with the single inline schema
+				flattenCompositionWithInlineSchema(node, i, singleSchema, schemaName, key, path, result)
+				changed = true
+			}
+		case "properties":
+			// Special handling for properties - process each property individually
+			if value.Kind == yaml.MappingNode {
+				propertiesToRemove := []int{}
+
+				for j := 0; j < len(value.Content); j += 2 {
+					propName := value.Content[j].Value
+					propNode := value.Content[j+1]
+
+					if propNode.Kind == yaml.MappingNode {
+						propSchemaName := fmt.Sprintf("%s.properties.%s", schemaName, propName)
+						if flattenSchemaNode(propNode, propSchemaName, path, result) {
+							changed = true
+						}
+
+						// Check if property became empty after flattening
+						if len(propNode.Content) == 0 {
+							propertiesToRemove = append(propertiesToRemove, j)
+						}
+					}
+				}
+
+				// Remove empty properties (in reverse order to maintain indices)
+				for i := len(propertiesToRemove) - 1; i >= 0; i-- {
+					propIndex := propertiesToRemove[i]
+
+					// Remove property key-value pair
+					newContent := make([]*yaml.Node, 0, len(value.Content)-2)
+
+					// Copy content before the property
+					for k := 0; k < propIndex; k++ {
+						newContent = append(newContent, value.Content[k])
+					}
+
+					// Copy content after the property (skip the key-value pair)
+					for k := propIndex + 2; k < len(value.Content); k++ {
+						newContent = append(newContent, value.Content[k])
+					}
+
+					// Replace the properties node's content
+					value.Content = newContent
+					changed = true
+				}
 			}
 		default:
 			switch value.Kind {
@@ -517,3 +575,98 @@ func getSingleRefFromArray(arrayNode *yaml.Node) string {
 
 	return refValue
 }
+
+// getSingleSchemaFromArray checks if an array contains only one schema (not $ref) and returns it
+func getSingleSchemaFromArray(arrayNode *yaml.Node) *yaml.Node {
+	if arrayNode == nil || arrayNode.Kind != yaml.SequenceNode {
+		return nil
+	}
+
+	// Check if array has exactly one element
+	if len(arrayNode.Content) != 1 {
+		return nil
+	}
+
+	element := arrayNode.Content[0]
+	if element.Kind != yaml.MappingNode {
+		return nil
+	}
+
+	// Check if the element is an inline schema (not a $ref)
+	for i := 0; i < len(element.Content); i += 2 {
+		key := element.Content[i].Value
+		if key == "$ref" {
+			// This is a $ref, not an inline schema
+			return nil
+		}
+	}
+
+	// It's an inline schema
+	return element
+}
+
+// flattenCompositionWithInlineSchema replaces oneOf/anyOf/allOf with the single inline schema
+func flattenCompositionWithInlineSchema(parentNode *yaml.Node, keyIndex int, singleSchema *yaml.Node, schemaName, compositionType, path string, result *FlattenResult) {
+	// Remove the composition key and replace with the inline schema's properties
+	// We need to merge the single schema's content into the parent node
+
+	// First, remove the composition key-value pair
+	newContent := make([]*yaml.Node, 0, len(parentNode.Content)-2+len(singleSchema.Content))
+
+	// Copy content before the composition
+	for i := 0; i < keyIndex; i++ {
+		newContent = append(newContent, parentNode.Content[i])
+	}
+
+	// Add the single schema's content (all its key-value pairs)
+	newContent = append(newContent, singleSchema.Content...)
+
+	// Copy content after the composition
+	for i := keyIndex + 2; i < len(parentNode.Content); i++ {
+		newContent = append(newContent, parentNode.Content[i])
+	}
+
+	// Replace the parent node's content
+	parentNode.Content = newContent
+
+	// Record the flattening
+	flattenedPath := fmt.Sprintf("%s.%s -> inline schema", schemaName, compositionType)
+	if result.FlattenedRefs[path] == nil {
+		result.FlattenedRefs[path] = []string{}
+	}
+	result.FlattenedRefs[path] = append(result.FlattenedRefs[path], flattenedPath)
+}
+
+// isEmptyComposition checks if a composition array is empty
+func isEmptyComposition(arrayNode *yaml.Node) bool {
+	if arrayNode == nil || arrayNode.Kind != yaml.SequenceNode {
+		return false
+	}
+	return len(arrayNode.Content) == 0
+}
+
+// handleEmptyComposition removes empty composition from schema
+func handleEmptyComposition(parentNode *yaml.Node, keyIndex int, schemaName, compositionType, path string, result *FlattenResult) {
+	// Remove the empty composition key-value pair
+	newContent := make([]*yaml.Node, 0, len(parentNode.Content)-2)
+
+	// Copy content before the composition
+	for i := 0; i < keyIndex; i++ {
+		newContent = append(newContent, parentNode.Content[i])
+	}
+
+	// Copy content after the composition (skip the key-value pair)
+	for i := keyIndex + 2; i < len(parentNode.Content); i++ {
+		newContent = append(newContent, parentNode.Content[i])
+	}
+
+	// Replace the parent node's content
+	parentNode.Content = newContent
+
+	// Record the removal
+	flattenedPath := fmt.Sprintf("%s.%s -> removed (empty)", schemaName, compositionType)
+	if result.FlattenedRefs[path] == nil {
+		result.FlattenedRefs[path] = []string{}
+	}
+	result.FlattenedRefs[path] = append(result.FlattenedRefs[path], flattenedPath)
+}