[raycicmd] Parse array adjustments config (#463)

Add arrayAdjustment struct and parseArrayAdjustments() to parse the
adjustments field nested under array. Each adjustment has a required
`with` map (dimension→value) and optional `skip` (bool). The
`adjustments` key in the array map is reserved and excluded from
dimension parsing. Duplicate `with` values are rejected.

Topic: parse-adjustments
Signed-off-by: andrew <andrew@anyscale.com>

Signed-off-by: andrew <andrew@anyscale.com>

Author: andrew-anyscale

raycicmd/array_config.go

@@ -18,10 +18,19 @@ type arrayElement struct {
 }
 
 // parseArrayConfig parses the array field from a step.
+// The "adjustments" key, if present, is reserved and not treated as a dimension.
 //
 //	array:
 //	  python: ["3.10", "3.11"]
 //	  cuda: ["12.1.1", "12.8.1"]
+//	  adjustments:
+//	    - with:
+//	        python: "3.10"
+//	        cuda: "12.1.1"
+//	      skip: true
+//	    - with:
+//	        python: "3.12"
+//	        cuda: "12.8.1"
 func parseArrayConfig(v any) (*arrayConfig, error) {
 	m, ok := v.(map[string]any)
 	if !ok {
@@ -35,6 +44,9 @@ func parseArrayConfig(v any) (*arrayConfig, error) {
 		dims: make(map[string][]string, len(m)),
 	}
 	for dim, vals := range m {
+		if dim == "adjustments" {
+			continue // handled separately
+		}
 		valsSlice, ok := vals.([]any)
 		if !ok {
 			return nil, fmt.Errorf("array.%s must be an array, got %T", dim, vals)
@@ -48,6 +60,9 @@ func parseArrayConfig(v any) (*arrayConfig, error) {
 		}
 		cfg.dims[dim] = values
 	}
+	if len(cfg.dims) == 0 {
+		return nil, fmt.Errorf("array must have at least one dimension")
+	}
 	return cfg, nil
 }
 
@@ -63,6 +78,20 @@ func toStringSlice(arr []any) ([]string, error) {
 	return result, nil
 }
 
+func toStringMap(m map[string]any) (map[string]string, error) {
+	result := make(map[string]string, len(m))
+	for k, v := range m {
+		s, ok := v.(string)
+		if !ok {
+			return nil, fmt.Errorf(
+				"value for key %q must be a string, got %T", k, v,
+			)
+		}
+		result[k] = s
+	}
+	return result, nil
+}
+
 func (cfg *arrayConfig) sortedDimensions() []string {
 	dims := make([]string, 0, len(cfg.dims))
 	for dim := range cfg.dims {
@@ -156,3 +185,89 @@ func (elem *arrayElement) substituteString(s string) string {
 func hasArrayPlaceholder(s string) bool {
 	return strings.Contains(s, "{{array.")
 }
+
+// arrayAdjustment represents a single adjustment to the array expansion.
+type arrayAdjustment struct {
+	with map[string]string
+	skip bool
+}
+
+// parseArrayAdjustments parses the adjustments field from a step.
+func parseArrayAdjustments(v any) ([]*arrayAdjustment, error) {
+	arr, ok := v.([]any)
+	if !ok {
+		return nil, fmt.Errorf(
+			"adjustments must be an array, got %T", v,
+		)
+	}
+
+	seen := make(map[string]struct{})
+	var result []*arrayAdjustment
+	for i, item := range arr {
+		m, ok := item.(map[string]any)
+		if !ok {
+			return nil, fmt.Errorf(
+				"adjustments[%d] must be a map, got %T", i, item,
+			)
+		}
+
+		adj, err := parseAdjustment(m)
+		if err != nil {
+			return nil, fmt.Errorf("adjustments[%d]: %w", i, err)
+		}
+
+		key := marshalStringMap(adj.with)
+		if _, dup := seen[key]; dup {
+			return nil, fmt.Errorf(
+				"adjustments[%d]: duplicate \"with\" %v",
+				i, adj.with,
+			)
+		}
+		seen[key] = struct{}{}
+
+		result = append(result, adj)
+	}
+	return result, nil
+}
+
+// marshalStringMap returns a deterministic string for dedup of string maps.
+func marshalStringMap(m map[string]string) string {
+	keys := make([]string, 0, len(m))
+	for k := range m {
+		keys = append(keys, k)
+	}
+	sort.Strings(keys)
+	var parts []string
+	for _, k := range keys {
+		parts = append(parts, k+"="+m[k])
+	}
+	return strings.Join(parts, ",")
+}
+
+func parseAdjustment(m map[string]any) (*arrayAdjustment, error) {
+	withVal, ok := m["with"]
+	if !ok {
+		return nil, fmt.Errorf("missing required \"with\" key")
+	}
+	withMap, ok := withVal.(map[string]any)
+	if !ok {
+		return nil, fmt.Errorf("\"with\" must be a map, got %T", withVal)
+	}
+	if len(withMap) == 0 {
+		return nil, fmt.Errorf("\"with\" cannot be empty")
+	}
+	with, err := toStringMap(withMap)
+	if err != nil {
+		return nil, fmt.Errorf("with: %w", err)
+	}
+
+	skip, _ := m["skip"].(bool)
+
+	for k := range m {
+		if k != "with" && k != "skip" {
+			return nil, fmt.Errorf("unknown key %q", k)
+		}
+	}
+
+	return &arrayAdjustment{with: with, skip: skip}, nil
+}

raycicmd/array_config_test.go

@@ -125,6 +125,111 @@ func TestHasArrayPlaceholder(t *testing.T) {
 	}
 }
 
+func TestParseArrayAdjustments(t *testing.T) {
+	input := []any{
+		map[string]any{
+			"with": map[string]any{"os": "windows", "arch": "arm64"},
+			"skip": true,
+		},
+		map[string]any{
+			"with": map[string]any{"os": "Plan 9", "arch": "arm64"},
+		},
+	}
+
+	adjs, err := parseArrayAdjustments(input)
+	if err != nil {
+		t.Fatalf("parseArrayAdjustments() error = %v", err)
+	}
+	if len(adjs) != 2 {
+		t.Fatalf("len(adjs) = %d, want 2", len(adjs))
+	}
+
+	if !adjs[0].skip {
+		t.Error("adjs[0].skip = false, want true")
+	}
+	if adjs[0].with["os"] != "windows" || adjs[0].with["arch"] != "arm64" {
+		t.Errorf("adjs[0].with = %v, want {os:windows, arch:arm64}", adjs[0].with)
+	}
+
+	if adjs[1].skip {
+		t.Error("adjs[1] should be a pure addition, got skip=true")
+	}
+}
+
+func TestParseArrayAdjustmentsErrors(t *testing.T) {
+	tests := []struct {
+		name    string
+		input   any
+		wantErr string
+	}{
+		{
+			name:    "not an array",
+			input:   "bad",
+			wantErr: "must be an array",
+		},
+		{
+			name:    "element not a map",
+			input:   []any{"bad"},
+			wantErr: "must be a map",
+		},
+		{
+			name:    "missing with",
+			input:   []any{map[string]any{"skip": true}},
+			wantErr: "missing required \"with\"",
+		},
+		{
+			name:    "with not a map",
+			input:   []any{map[string]any{"with": "bad"}},
+			wantErr: "\"with\" must be a map",
+		},
+		{
+			name:    "empty with",
+			input:   []any{map[string]any{"with": map[string]any{}}},
+			wantErr: "\"with\" cannot be empty",
+		},
+		{
+			name: "with value not a string",
+			input: []any{map[string]any{
+				"with": map[string]any{"os": 42},
+			}},
+			wantErr: "must be a string",
+		},
+		{
+			name: "duplicate with",
+			input: []any{
+				map[string]any{
+					"with": map[string]any{"os": "linux"},
+					"skip": true,
+				},
+				map[string]any{
+					"with": map[string]any{"os": "linux"},
+				},
+			},
+			wantErr: "duplicate \"with\"",
+		},
+		{
+			name: "unknown key",
+			input: []any{map[string]any{
+				"with": map[string]any{"os": "linux"},
+				"skp":  true,
+			}},
+			wantErr: "unknown key",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			_, err := parseArrayAdjustments(tt.input)
+			if err == nil {
+				t.Fatal("parseArrayAdjustments() expected error, got nil")
+			}
+			if !strings.Contains(err.Error(), tt.wantErr) {
+				t.Errorf("error = %q, want to contain %q", err.Error(), tt.wantErr)
+			}
+		})
+	}
+}
+
 func TestParseArrayConfigErrors(t *testing.T) {
 	tests := []struct {
 		name    string
@@ -156,6 +261,11 @@ func TestParseArrayConfigErrors(t *testing.T) {
 			input:   map[string]any{"python": []any{}},
 			wantErr: "cannot be empty",
 		},
+		{
+			name:    "only adjustments key",
+			input:   map[string]any{"adjustments": []any{}},
+			wantErr: "at least one dimension",
+		},
 	}
 
 	for _, tt := range tests {