feat: implement consistent key ordering for YAML node creation and add related tests

Author: developerkunal

internal/transform/vendor_extensions.go

@@ -5,6 +5,7 @@ import (
 	"io/fs"
 	"path/filepath"
 	"regexp"
+	"sort"
 	"strings"
 
 	"gopkg.in/yaml.v3"
@@ -348,11 +349,31 @@ func addExtensionToOperation(operationNode *yaml.Node, extensionName string, ext
 	return true
 }
 
-// createYAMLNodeFromMap creates a YAML node from a map
+// createYAMLNodeFromMap creates a YAML node from a map with consistent key ordering
 func createYAMLNodeFromMap(data map[string]interface{}) *yaml.Node {
 	node := &yaml.Node{Kind: yaml.MappingNode}
 
-	for key, value := range data {
+	// Sort keys with custom ordering for pagination fields
+	var keys []string
+	for key := range data {
+		keys = append(keys, key)
+	}
+	sort.Slice(keys, func(i, j int) bool {
+		orderI := getPaginationFieldOrder(keys[i])
+		orderJ := getPaginationFieldOrder(keys[j])
+		
+		// If orders are the same, sort alphabetically
+		if orderI == orderJ {
+			return keys[i] < keys[j]
+		}
+		
+		return orderI < orderJ
+	})
+
+	// Add keys and values in sorted order
+	for _, key := range keys {
+		value := data[key]
+		
 		keyNode := &yaml.Node{
 			Kind:  yaml.ScalarNode,
 			Value: key,
@@ -376,6 +397,30 @@ func createYAMLNodeFromMap(data map[string]interface{}) *yaml.Node {
 	return node
 }
 
+// getPaginationFieldOrder returns the priority order for pagination fields
+// Lower numbers appear first in the output
+func getPaginationFieldOrder(key string) int {
+	switch key {
+	case "offset":
+		return 1
+	case "cursor": 
+		return 1 // Same priority as offset - they're mutually exclusive
+	case "page":
+		return 1 // Same priority as offset/cursor - they're mutually exclusive
+	case "results":
+		return 2
+	case "limit":
+		return 3
+	case "next":
+		return 4
+	case "previous":
+		return 5
+	default:
+		// Unknown fields come last, sorted alphabetically by adding 1000 + ASCII value
+		return 1000
+	}
+}
+
 // Helper functions
 
 func extractParameterNames(params *yaml.Node, root *yaml.Node) []string {

internal/transform/vendor_extensions_test.go

@@ -3,6 +3,7 @@ package transform
 import (
 	"os"
 	"path/filepath"
+	"strings"
 	"testing"
 
 	"gopkg.in/yaml.v3"
@@ -797,6 +798,67 @@ func TestCreateYAMLNodeFromMap(t *testing.T) {
 	}
 }
 
+func TestCreateYAMLNodeFromMapOrdering(t *testing.T) {
+	tests := []struct {
+		name     string
+		input    map[string]interface{}
+		expected []string // expected order of keys
+	}{
+		{
+			name: "pagination fields in correct order",
+			input: map[string]interface{}{
+				"results": "$response.data",
+				"offset":  "$request.page",
+				"limit":   "$request.per_page",
+			},
+			expected: []string{"offset", "results", "limit"},
+		},
+		{
+			name: "pagination fields with cursor",
+			input: map[string]interface{}{
+				"cursor":  "$request.cursor",
+				"results": "$response.items",
+				"next":    "$response.next_cursor",
+			},
+			expected: []string{"cursor", "results", "next"},
+		},
+		{
+			name: "mixed known and unknown fields",
+			input: map[string]interface{}{
+				"unknown_field": "value",
+				"results":       "$response.data",
+				"offset":        "$request.page",
+				"custom":        "custom_value",
+			},
+			expected: []string{"offset", "results", "custom", "unknown_field"},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			node := createYAMLNodeFromMap(tt.input)
+
+			// Extract the key order from the YAML node
+			var actualKeys []string
+			for i := 0; i < len(node.Content); i += 2 {
+				actualKeys = append(actualKeys, node.Content[i].Value)
+			}
+
+			// Verify the order matches expected
+			if len(actualKeys) != len(tt.expected) {
+				t.Errorf("Expected %d keys, got %d", len(tt.expected), len(actualKeys))
+				return
+			}
+
+			for i, expectedKey := range tt.expected {
+				if actualKeys[i] != expectedKey {
+					t.Errorf("At position %d: expected key %q, got %q", i, expectedKey, actualKeys[i])
+				}
+			}
+		})
+	}
+}
+
 func TestAddProcessedExtension(t *testing.T) {
 	result := &VendorExtensionResult{
 		AddedExtensions: make(map[string][]string),
@@ -1127,3 +1189,45 @@ info:
 		})
 	}
 }
+
+func TestConsistentPaginationOrdering(t *testing.T) {
+	// Test the exact case mentioned in the user request
+	paginationData := map[string]interface{}{
+		"results": "$response.network_acls",
+		"offset":  "$request.page",
+	}
+
+	// Generate the YAML node multiple times to ensure consistent ordering
+	for i := 0; i < 5; i++ {
+		node := createYAMLNodeFromMap(paginationData)
+
+		// Convert to YAML string to verify output
+		var buffer strings.Builder
+		encoder := yaml.NewEncoder(&buffer)
+		encoder.SetIndent(2)
+		err := encoder.Encode(node)
+		if err != nil {
+			t.Fatalf("Failed to encode YAML: %v", err)
+		}
+		encoder.Close()
+
+		yamlOutput := buffer.String()
+
+		// Verify that "offset" appears before "results" in the output
+		offsetPos := strings.Index(yamlOutput, "offset:")
+		resultsPos := strings.Index(yamlOutput, "results:")
+
+		if offsetPos == -1 || resultsPos == -1 {
+			t.Fatalf("Missing expected fields in YAML output: %s", yamlOutput)
+		}
+
+		if offsetPos >= resultsPos {
+			t.Errorf("Expected 'offset' to appear before 'results' in YAML output, but got:\n%s", yamlOutput)
+		}
+
+		// For the first iteration, log the output for visual verification
+		if i == 0 {
+			t.Logf("Generated YAML output:\n%s", yamlOutput)
+		}
+	}
+}