fix(cld): harden YAML merge key parsing for pipeline inputs

Return errors for invalid <<: targets, support sequence merges, and
propagate YamlNodeToAny decode failures through the parse path.

Author: graham-chainlink

.changeset/loud-trams-jog.md

@@ -0,0 +1,5 @@
+---
+"chainlink-deployments-framework": minor
+---
+
+feat(cld): enhance support for YAML anchors for pipeline input files

engine/cld/pipeline/input/resolve.go

@@ -13,7 +13,11 @@ import (
 // ResolveChangesetConfig resolves the configuration for a changeset using either
 // a registered resolver or keeping the original payload.
 func ResolveChangesetConfig(valueNode *yaml.Node, csName string, resolver resolvers.ConfigResolver) (any, error) {
-	changesetMap, ok := YamlNodeToAny(valueNode).(map[string]any)
+	changesetAny, err := yamlNodeToAny(valueNode)
+	if err != nil {
+		return nil, fmt.Errorf("decode changeset data for %s: %w", csName, err)
+	}
+	changesetMap, ok := changesetAny.(map[string]any)
 	if !ok {
 		return nil, fmt.Errorf("decode changeset data for %s: expected mapping node", csName)
 	}

engine/cld/pipeline/input/yaml.go

@@ -156,6 +156,39 @@ func isYAMLMergeKey(node *yaml.Node) bool {
 	return node != nil && node.Kind == yaml.ScalarNode && (node.Value == "<<" || node.Tag == "!!merge")
 }
 
+func mergeMapInto(dst, src map[string]any) {
+	for mk, mv := range src {
+		if _, exists := dst[mk]; !exists {
+			dst[mk] = mv
+		}
+	}
+}
+
+func applyYAMLMerge(out map[string]any, value any) error {
+	switch v := value.(type) {
+	case map[string]any:
+		mergeMapInto(out, v)
+
+		return nil
+	case []any:
+		seqMerged := make(map[string]any)
+		for i, item := range v {
+			mergeMap, ok := item.(map[string]any)
+			if !ok {
+				return fmt.Errorf("YAML merge sequence entry %d must be a mapping, got %T", i, item)
+			}
+			for mk, mv := range mergeMap {
+				seqMerged[mk] = mv
+			}
+		}
+		mergeMapInto(out, seqMerged)
+
+		return nil
+	default:
+		return fmt.Errorf("YAML merge key (<<) value must be a mapping or sequence of mappings, got %T", value)
+	}
+}
+
 // ConvertToJSONSafe recursively converts map[interface{}]interface{} to map[string]any.
 func ConvertToJSONSafe(data any) (any, error) {
 	switch v := data.(type) {
@@ -311,7 +344,11 @@ func ParseYAMLBytes(yamlData []byte) (*DurablePipelineYAML, error) {
 	if err := yaml.Unmarshal(yamlData, &root); err != nil {
 		return nil, fmt.Errorf("failed to parse YAML bytes: %w", err)
 	}
-	rootMap, ok := YamlNodeToAny(&root).(map[string]any)
+	rootAny, err := yamlNodeToAny(&root)
+	if err != nil {
+		return nil, fmt.Errorf("failed to decode YAML: %w", err)
+	}
+	rootMap, ok := rootAny.(map[string]any)
 	if !ok {
 		return nil, errors.New("expected a YAML object at the root")
 	}
@@ -342,81 +379,103 @@ func ParseYAMLBytes(yamlData []byte) (*DurablePipelineYAML, error) {
 }
 
 // YamlNodeToAny converts a yaml.Node to a generic any value.
+// This is the stable exported API; decode errors are ignored and nil is returned.
 func YamlNodeToAny(node *yaml.Node) any {
-	if node == nil {
+	v, err := yamlNodeToAny(node)
+	if err != nil {
 		return nil
 	}
 
+	return v
+}
+
+// yamlNodeToAny converts a yaml.Node to a generic any value.
+func yamlNodeToAny(node *yaml.Node) (any, error) {
+	if node == nil {
+		return nil, nil //nolint:nilnil // YAML null
+	}
+
 	switch node.Kind {
 	case yaml.DocumentNode:
 		if len(node.Content) == 0 {
-			return nil
+			return nil, nil //nolint:nilnil // empty YAML document
 		}
 
-		return YamlNodeToAny(node.Content[0])
+		return yamlNodeToAny(node.Content[0])
 	case yaml.MappingNode:
 		out := make(map[string]any, len(node.Content)/2)
 		for i := 0; i+1 < len(node.Content); i += 2 {
 			key := node.Content[i]
 			value := node.Content[i+1]
 			if isYAMLMergeKey(key) {
-				mergeMap, ok := YamlNodeToAny(value).(map[string]any)
-				if !ok {
-					continue
+				merged, err := yamlNodeToAny(value)
+				if err != nil {
+					return nil, err
 				}
-				for mk, mv := range mergeMap {
-					if _, exists := out[mk]; !exists {
-						out[mk] = mv
-					}
+				if err := applyYAMLMerge(out, merged); err != nil {
+					return nil, err
 				}
 
 				continue
 			}
 
-			keyStr := anyToJSONMapKey(YamlNodeToAny(key))
-			out[keyStr] = YamlNodeToAny(value)
+			keyAny, err := yamlNodeToAny(key)
+			if err != nil {
+				return nil, err
+			}
+			valueAny, err := yamlNodeToAny(value)
+			if err != nil {
+				return nil, err
+			}
+			keyStr := anyToJSONMapKey(keyAny)
+			out[keyStr] = valueAny
 		}
 
-		return out
+		return out, nil
 	case yaml.SequenceNode:
 		out := make([]any, 0, len(node.Content))
 		for _, elem := range node.Content {
-			out = append(out, YamlNodeToAny(elem))
+			elemAny, err := yamlNodeToAny(elem)
+			if err != nil {
+				return nil, err
+			}
+			out = append(out, elemAny)
 		}
 
-		return out
+		return out, nil
 	case yaml.ScalarNode:
 		if node.Style == 0 && decimalInteger.MatchString(node.Value) {
-			return json.Number(node.Value)
+			return json.Number(node.Value), nil
 		}
 
 		switch node.Tag {
 		case "!!int":
 			if decimalInteger.MatchString(node.Value) {
-				return json.Number(node.Value)
+				return json.Number(node.Value), nil
 			}
 			if n, ok := new(big.Int).SetString(strings.ReplaceAll(node.Value, "_", ""), 0); ok {
-				return json.Number(n.String())
+				return json.Number(n.String()), nil
 			}
 
-			return node.Value
+			return node.Value, nil
 		case "!!float":
 			f, err := strconv.ParseFloat(node.Value, 64)
 			if err != nil {
-				return node.Value
+				//nolint:nilerr // Fall back to raw scalar when float parsing fails.
+				return node.Value, nil
 			}
 
-			return f
+			return f, nil
 		case "!!null":
-			return nil
+			return nil, nil //nolint:nilnil // YAML null scalar
 		case "!!bool":
-			return strings.EqualFold(node.Value, "true")
+			return strings.EqualFold(node.Value, "true"), nil
 		default:
-			return node.Value
+			return node.Value, nil
 		}
 	case yaml.AliasNode:
-		return YamlNodeToAny(node.Alias)
+		return yamlNodeToAny(node.Alias)
 	default:
-		return nil
+		return nil, nil //nolint:nilnil // unsupported node kind
 	}
 }

engine/cld/pipeline/input/yaml_test.go

@@ -166,6 +166,11 @@ func TestConvertToJSONSafe(t *testing.T) {
 			in:   42,
 			want: 42,
 		},
+		{
+			name: "map with json number key",
+			in:   map[interface{}]interface{}{json.Number("16015286601757825753"): "chain"},
+			want: map[string]any{"16015286601757825753": "chain"},
+		},
 	}
 
 	for _, tt := range tests {
@@ -182,8 +187,7 @@ func TestConvertToJSONSafe(t *testing.T) {
 func TestYamlNodeToAny_Nil(t *testing.T) {
 	t.Parallel()
 
-	got := YamlNodeToAny(nil)
-	require.Nil(t, got)
+	require.Nil(t, YamlNodeToAny(nil))
 }
 
 func TestYamlNodeToAny_AliasMapKeys(t *testing.T) {
@@ -201,7 +205,9 @@ chains:
 	var root yaml.Node
 	require.NoError(t, yaml.Unmarshal([]byte(yamlContent), &root))
 
-	doc := YamlNodeToAny(&root).(map[string]any)
+	docAny, err := yamlNodeToAny(&root)
+	require.NoError(t, err)
+	doc := docAny.(map[string]any)
 	chains := doc["chains"].(map[string]any)
 
 	require.Equal(t, map[string]any{
@@ -232,7 +238,9 @@ chains:
 	var root yaml.Node
 	require.NoError(t, yaml.Unmarshal([]byte(yamlContent), &root))
 
-	doc := YamlNodeToAny(&root).(map[string]any)
+	docAny, err := yamlNodeToAny(&root)
+	require.NoError(t, err)
+	doc := docAny.(map[string]any)
 	chains := doc["chains"].(map[string]any)
 	chain := chains["16015286601757825753"].(map[string]any)
 
@@ -241,6 +249,149 @@ chains:
 	require.Equal(t, map[string]any{"quorum": json.Number("1")}, chain["proposer"])
 }
 
+func TestYamlNodeToAny_MergeKeyOverrideAfter(t *testing.T) {
+	t.Parallel()
+
+	yamlContent := `
+base: &base_cfg
+  qualifier: Base
+  timelockMinDelay: 0
+chains:
+  "123":
+    <<: *base_cfg
+    qualifier: Override
+`
+	var root yaml.Node
+	require.NoError(t, yaml.Unmarshal([]byte(yamlContent), &root))
+
+	docAny, err := yamlNodeToAny(&root)
+	require.NoError(t, err)
+	chain := docAny.(map[string]any)["chains"].(map[string]any)["123"].(map[string]any)
+
+	require.Equal(t, "Override", chain["qualifier"])
+	require.Equal(t, json.Number("0"), chain["timelockMinDelay"])
+}
+
+func TestYamlNodeToAny_MergeKeyExplicitBeforeMerge(t *testing.T) {
+	t.Parallel()
+
+	yamlContent := `
+base: &base_cfg
+  qualifier: Base
+  timelockMinDelay: 0
+chains:
+  "123":
+    qualifier: Override
+    <<: *base_cfg
+`
+	var root yaml.Node
+	require.NoError(t, yaml.Unmarshal([]byte(yamlContent), &root))
+
+	docAny, err := yamlNodeToAny(&root)
+	require.NoError(t, err)
+	chain := docAny.(map[string]any)["chains"].(map[string]any)["123"].(map[string]any)
+
+	require.Equal(t, "Override", chain["qualifier"])
+	require.Equal(t, json.Number("0"), chain["timelockMinDelay"])
+}
+
+func TestYamlNodeToAny_MergeKeySequence(t *testing.T) {
+	t.Parallel()
+
+	yamlContent := `
+a: &a
+  x: 1
+b: &b
+  y: 2
+m:
+  <<: [*a, *b]
+  z: 3
+`
+	var root yaml.Node
+	require.NoError(t, yaml.Unmarshal([]byte(yamlContent), &root))
+
+	docAny, err := yamlNodeToAny(&root)
+	require.NoError(t, err)
+	m := docAny.(map[string]any)["m"].(map[string]any)
+
+	require.Equal(t, json.Number("1"), m["x"])
+	require.Equal(t, json.Number("2"), m["y"])
+	require.Equal(t, json.Number("3"), m["z"])
+}
+
+func TestYamlNodeToAny_MergeKeySequenceConflict(t *testing.T) {
+	t.Parallel()
+
+	yamlContent := `
+a: &a
+  x: from_a
+  only_a: 1
+b: &b
+  x: from_b
+  only_b: 2
+m:
+  <<: [*a, *b]
+`
+	var root yaml.Node
+	require.NoError(t, yaml.Unmarshal([]byte(yamlContent), &root))
+
+	docAny, err := yamlNodeToAny(&root)
+	require.NoError(t, err)
+	m := docAny.(map[string]any)["m"].(map[string]any)
+
+	require.Equal(t, "from_b", m["x"])
+	require.Equal(t, json.Number("1"), m["only_a"])
+	require.Equal(t, json.Number("2"), m["only_b"])
+}
+
+func TestYamlNodeToAny_InvalidMergeValueSwallowsError(t *testing.T) {
+	t.Parallel()
+
+	yamlContent := `
+m:
+  <<: not_a_map
+  z: 3
+`
+	var root yaml.Node
+	require.NoError(t, yaml.Unmarshal([]byte(yamlContent), &root))
+
+	require.Nil(t, YamlNodeToAny(&root))
+}
+
+func TestYamlNodeToAny_InvalidMergeValue(t *testing.T) {
+	t.Parallel()
+
+	yamlContent := `
+m:
+  <<: not_a_map
+  z: 3
+`
+	var root yaml.Node
+	require.NoError(t, yaml.Unmarshal([]byte(yamlContent), &root))
+
+	_, err := yamlNodeToAny(&root)
+	require.Error(t, err)
+	require.ErrorContains(t, err, "YAML merge key (<<) value must be a mapping or sequence of mappings")
+}
+
+func TestParseYAMLBytes_InvalidMergeValue(t *testing.T) {
+	t.Parallel()
+
+	yamlContent := `environment: testnet
+domain: ccv
+changesets:
+  - cs1:
+      payload:
+        m:
+          <<: not_a_map
+          z: 3
+`
+	_, err := ParseYAMLBytes([]byte(yamlContent))
+	require.Error(t, err)
+	require.ErrorContains(t, err, "failed to decode YAML")
+	require.ErrorContains(t, err, "YAML merge key (<<) value must be a mapping or sequence of mappings")
+}
+
 func TestBuildChangesetInputJSON_AliasChainSelectorKeys(t *testing.T) {
 	t.Parallel()