Fix some issues around merge key/anchor handling

pkg/yqlib/doc/operators/anchor-and-alias-operators.md

@@ -92,7 +92,39 @@ yq '.[4] | explode(.)' sample.yml
 will output
 ```yaml
 r: 10
+y: 2
 x: 1
+```
+
+## Override with local key
+like https://yaml.org/type/merge.html, but with x: 1 before the merge key. This is legacy behavior, see --yaml-fix-merge-anchor-to-spec
+
+Given a sample.yml file of:
+```yaml
+- &CENTER
+  x: 1
+  y: 2
+- &LEFT
+  x: 0
+  y: 2
+- &BIG
+  r: 10
+- &SMALL
+  r: 1
+- x: 1
+  !!merge <<:
+    - *BIG
+    - *LEFT
+    - *SMALL
+```
+then
+```bash
+yq '.[4] | explode(.)' sample.yml
+```
+will output
+```yaml
+x: 0
+r: 10
 y: 2
 ```
 
@@ -293,8 +325,8 @@ bar:
 foobarList:
   b: bar_b
   thing: foo_thing
-  c: foobarList_c
   a: foo_a
+  c: foobarList_c
 foobar:
   c: foo_c
   a: foo_a

pkg/yqlib/doc/operators/traverse-read.md

@@ -304,6 +304,8 @@ foo_a
 ```
 
 ## Traversing merge anchors with override
+This is legacy behavior, see --yaml-fix-merge-anchor-to-spec
+
 Given a sample.yml file of:
 ```yaml
 foo: &foo
@@ -399,7 +401,7 @@ foobar_thing
 ```
 
 ## Traversing merge anchor lists
-Note that the later merge anchors override previous
+Note that the later merge anchors override previous, but this is legacy behavior, see --yaml-fix-merge-anchor-to-spec
 
 Given a sample.yml file of:
 ```yaml
@@ -432,6 +434,8 @@ bar_thing
 ```
 
 ## Splatting merge anchor lists
+With legacy override behavior, see --yaml-fix-merge-anchor-to-spec
+
 Given a sample.yml file of:
 ```yaml
 foo: &foo

pkg/yqlib/operator_anchors_aliases.go

@@ -3,6 +3,7 @@ package yqlib
 import (
 	"container/list"
 	"fmt"
+	"slices"
 )
 
 func assignAliasOperator(d *dataTreeNavigator, context Context, expressionNode *ExpressionNode) (Context, error) {
@@ -147,27 +148,15 @@ func reconstructAliasedMap(node *CandidateNode, context Context) error {
 		keyNode := node.Content[index]
 		valueNode := node.Content[index+1]
 		log.Debugf("traversing %v", keyNode.Value)
-		if keyNode.Value != "<<" {
-			err := overrideEntry(node, keyNode, valueNode, index, context.ChildContext(newContent))
+		if keyNode.Tag != "!!merge" {
+			err := overrideEntry(node, keyNode, valueNode, index, true, context.ChildContext(newContent))
 			if err != nil {
 				return err
 			}
 		} else {
-			if valueNode.Kind == SequenceNode {
-				log.Debugf("an alias merge list!")
-				for index := len(valueNode.Content) - 1; index >= 0; index = index - 1 {
-					aliasNode := valueNode.Content[index]
-					err := applyAlias(node, aliasNode.Alias, index, context.ChildContext(newContent))
-					if err != nil {
-						return err
-					}
-				}
-			} else {
-				log.Debugf("an alias merge!")
-				err := applyAlias(node, valueNode.Alias, index, context.ChildContext(newContent))
-				if err != nil {
-					return err
-				}
+			err := applyMergeAnchor(node, valueNode, index, context.ChildContext(newContent))
+			if err != nil {
+				return err
 			}
 		}
 	}
@@ -208,7 +197,7 @@ func explodeNode(node *CandidateNode, context Context) error {
 		hasAlias := false
 		for index := 0; index < len(node.Content); index = index + 2 {
 			keyNode := node.Content[index]
-			if keyNode.Value == "<<" {
+			if keyNode.Tag == "!!merge" {
 				hasAlias = true
 				break
 			}
@@ -237,42 +226,91 @@ func explodeNode(node *CandidateNode, context Context) error {
 	}
 }
 
-func applyAlias(node *CandidateNode, alias *CandidateNode, aliasIndex int, newContent Context) error {
-	log.Debug("alias is nil ?")
-	if alias == nil {
+func applyMergeAnchor(node *CandidateNode, merge *CandidateNode, mergeIndex int, newContent Context) error {
+	inline := true
+	if merge.Kind == AliasNode {
+		inline = false
+		merge = merge.Alias
+	}
+	switch merge.Kind {
+	case MappingNode:
+		log.Debugf("a merge map!")
+		return applyMergeAnchorMap(node, merge, mergeIndex, inline, newContent)
+	case SequenceNode:
+		log.Debugf("a merge list!")
+		// With FixMergeAnchorToSpec, we rely on overrideEntry to reject duplicates
+		content := slices.All(merge.Content)
+		if !ConfiguredYamlPreferences.FixMergeAnchorToSpec {
+			// Even without FixMergeAnchorToSpec, this already gave preference to earlier keys
+			content = slices.Backward(merge.Content)
+		}
+		for _, childValue := range content {
+			childInline := inline
+			if childValue.Kind == AliasNode {
+				childInline = false
+				childValue = childValue.Alias
+			}
+			if childValue.Kind != MappingNode {
+				return fmt.Errorf(
+					"can only use merge anchors with maps (!!map) or sequences (!!seq) of maps, but got sequence containing %v",
+					childValue.Tag)
+			}
+			err := applyMergeAnchorMap(node, childValue, mergeIndex, childInline, newContent)
+			if err != nil {
+				return err
+			}
+		}
+		return nil
+	default:
+		return fmt.Errorf("can only use merge anchors with maps (!!map) or sequences (!!seq) of maps, but got %v", merge.Tag)
+	}
+}
+
+func applyMergeAnchorMap(node *CandidateNode, mergeMap *CandidateNode, mergeIndex int, explode bool, newContent Context) error {
+	if mergeMap == nil {
+		log.Debug("merge map is nil")
 		return nil
 	}
-	log.Debug("alias: %v", NodeToString(alias))
-	if alias.Kind != MappingNode {
-		return fmt.Errorf("merge anchor only supports maps, got %v instead", alias.Tag)
+	log.Debug("merge map: %v", NodeToString(mergeMap))
+	if mergeMap.Kind != MappingNode {
+		return fmt.Errorf("applyMergeAnchorMap expects !!map, got %v instead", mergeMap.Tag)
 	}
-	for index := 0; index < len(alias.Content); index = index + 2 {
-		keyNode := alias.Content[index]
-		log.Debugf("applying alias key %v", keyNode.Value)
-		valueNode := alias.Content[index+1]
-		err := overrideEntry(node, keyNode, valueNode, aliasIndex, newContent)
+
+	if explode {
+		err := explodeNode(mergeMap, newContent)
+		if err != nil {
+			return err
+		}
+	}
+
+	for index := 0; index < len(mergeMap.Content); index = index + 2 {
+		keyNode := mergeMap.Content[index]
+		log.Debugf("applying merge map key %v", keyNode.Value)
+		valueNode := mergeMap.Content[index+1]
+		err := overrideEntry(node, keyNode, valueNode, mergeIndex, explode, newContent)
 		if err != nil {
 			return err
 		}
 	}
 	return nil
 }
 
-func overrideEntry(node *CandidateNode, key *CandidateNode, value *CandidateNode, startIndex int, newContent Context) error {
-
-	err := explodeNode(value, newContent)
-
-	if err != nil {
-		return err
+func overrideEntry(node *CandidateNode, key *CandidateNode, value *CandidateNode, startIndex int, explode bool, newContent Context) error {
+	if explode {
+		err := explodeNode(value, newContent)
+		if err != nil {
+			return err
+		}
 	}
 
 	for newEl := newContent.MatchingNodes.Front(); newEl != nil; newEl = newEl.Next() {
 		valueEl := newEl.Next() // move forward twice
 		keyNode := newEl.Value.(*CandidateNode)
 		log.Debugf("checking new content %v:%v", keyNode.Value, valueEl.Value.(*CandidateNode).Value)
 		if keyNode.Value == key.Value && keyNode.Alias == nil && key.Alias == nil {
-			log.Debugf("overridign new content")
+			log.Debugf("overriding new content")
 			if !ConfiguredYamlPreferences.FixMergeAnchorToSpec {
+				//TODO This also fires in when an earlier element in a list merge anchor overwrites a later element, which *is* to the spec
 				log.Warning("--yaml-fix-merge-anchor-to-spec is false; causing the merge anchor to override the existing value at %v which isn't to the yaml spec. This flag will default to true in late 2025.", keyNode.GetNicePath())
 				valueEl.Value = value
 			}
@@ -290,9 +328,11 @@ func overrideEntry(node *CandidateNode, key *CandidateNode, value *CandidateNode
 		}
 	}
 
-	err = explodeNode(key, newContent)
-	if err != nil {
-		return err
+	if explode {
+		err := explodeNode(key, newContent)
+		if err != nil {
+			return err
+		}
 	}
 	log.Debugf("adding %v:%v", key.Value, value.Value)
 	newContent.MatchingNodes.PushBack(key)