Add libs/structwalk (#2957)

## Changes
- New function to walk over values: structwalk.Walk()
- New function to walk over types: structwalk.WalkType()
- structpath is extended to support AnyKey / AnyIndex.

Author: denik

libs/structdiff/structpath/path.go

@@ -7,16 +7,22 @@ import (
 	"github.com/databricks/cli/libs/structdiff/jsontag"
 )
 
+const (
+	tagStruct           = -1
+	tagMapKey           = -2
+	tagUnresolvedStruct = -3
+	tagAnyKey           = -4
+	tagAnyIndex         = -5
+)
+
 // PathNode represents a node in a path for struct diffing.
 // It can represent struct fields, map keys, or array/slice indices.
 type PathNode struct {
 	prev    *PathNode
 	jsonTag jsontag.JSONTag // For lazy JSON key resolution
 	key     string          // Computed key (JSON key for structs, string key for maps, or Go field name for fallback)
 	// If index >= 0, the node specifies a slice/array index in index.
-	// If index == -1, the node specifies a struct attribute
-	// If index == -2, the node specifies a map key in key
-	// If index == -3, the node specifies an unresolved struct attribute
+	// If index < 0, this describes the type of node (see tagStruct and other consts above)
 	index int
 }
 
@@ -42,21 +48,35 @@ func (p *PathNode) MapKey() (string, bool) {
 	if p == nil {
 		return "", false
 	}
-	if p.index == -2 {
+	if p.index == tagMapKey {
 		return p.key, true
 	}
 	return "", false
 }
 
+func (p *PathNode) AnyKey() bool {
+	if p == nil {
+		return false
+	}
+	return p.index == tagAnyKey
+}
+
+func (p *PathNode) AnyIndex() bool {
+	if p == nil {
+		return false
+	}
+	return p.index == tagAnyIndex
+}
+
 func (p *PathNode) resolveField() {
-	if p.index == -3 {
+	if p.index == tagUnresolvedStruct {
 		// Lazy resolve JSON key for struct fields
 		jsonName := p.jsonTag.Name()
 		if jsonName != "" {
 			p.key = jsonName
 		}
 		// If jsonName is empty, key already contains the Go field name as fallback
-		p.index = -1
+		p.index = tagStruct
 	}
 }
 
@@ -65,14 +85,17 @@ func (p *PathNode) Field() (string, bool) {
 		return "", false
 	}
 	p.resolveField()
-	if p.index == -1 {
+	if p.index == tagStruct {
 		return p.key, true
 	}
 	return "", false
 }
 
 // NewIndex creates a new PathNode for an array/slice index.
 func NewIndex(prev *PathNode, index int) *PathNode {
+	if index < 0 {
+		panic("index msut be non-negative")
+	}
 	return &PathNode{
 		prev:  prev,
 		index: index,
@@ -84,7 +107,7 @@ func NewMapKey(prev *PathNode, key string) *PathNode {
 	return &PathNode{
 		prev:  prev,
 		key:   key,
-		index: -2,
+		index: tagMapKey,
 	}
 }
 
@@ -95,7 +118,21 @@ func NewStructField(prev *PathNode, jsonTag jsontag.JSONTag, fieldName string) *
 		prev:    prev,
 		jsonTag: jsonTag,
 		key:     fieldName,
-		index:   -3, // Unresolved struct attribute
+		index:   tagUnresolvedStruct,
+	}
+}
+
+func NewAnyKey(prev *PathNode) *PathNode {
+	return &PathNode{
+		prev:  prev,
+		index: tagAnyKey,
+	}
+}
+
+func NewAnyIndex(prev *PathNode) *PathNode {
+	return &PathNode{
+		prev:  prev,
+		index: tagAnyIndex,
 	}
 }
 
@@ -109,9 +146,13 @@ func (p *PathNode) String() string {
 		return p.prev.String() + "[" + strconv.Itoa(p.index) + "]"
 	}
 
+	if p.index == tagAnyKey || p.index == tagAnyIndex {
+		return p.prev.String() + "[*]"
+	}
+
 	p.resolveField()
 
-	if p.index == -1 {
+	if p.index == tagStruct {
 		return p.prev.String() + "." + p.key
 	}
 
@@ -128,6 +169,19 @@ func (p *PathNode) DynPath() string {
 		return p.prev.DynPath() + "[" + strconv.Itoa(p.index) + "]"
 	}
 
+	if p.index == tagAnyKey {
+		prev := p.prev.DynPath()
+		if prev == "" {
+			return "*"
+		} else {
+			return prev + ".*"
+		}
+	}
+
+	if p.index == tagAnyIndex {
+		return p.prev.DynPath() + "[*]"
+	}
+
 	p.resolveField()
 
 	prev := p.prev.DynPath()

libs/structdiff/structpath/path_test.go

@@ -9,14 +9,16 @@ import (
 
 func TestPathNode(t *testing.T) {
 	tests := []struct {
-		name    string
-		node    *PathNode
-		String  string
-		DynPath string
-		Index   any
-		MapKey  any
-		Field   any
-		Root    any
+		name     string
+		node     *PathNode
+		String   string
+		DynPath  string
+		Index    any
+		MapKey   any
+		Field    any
+		Root     any
+		AnyKey   bool
+		AnyIndex bool
 	}{
 		// Single node tests
 		{
@@ -66,6 +68,19 @@ func TestPathNode(t *testing.T) {
 			DynPath: "lazy_field",
 			Field:   "lazy_field",
 		},
+		{
+			name:    "any key",
+			node:    NewAnyKey(nil),
+			String:  "[*]",
+			DynPath: "*",
+			AnyKey:  true,
+		},
+		{
+			name:     "any index",
+			node:     NewAnyIndex(nil),
+			String:   "[*]",
+			AnyIndex: true,
+		},
 
 		// Two node tests
 		{
@@ -123,6 +138,20 @@ func TestPathNode(t *testing.T) {
 			DynPath: "Parent.child_name",
 			Field:   "child_name",
 		},
+		{
+			name:    "any key",
+			node:    NewAnyKey(NewStructField(nil, jsontag.JSONTag(""), "Parent")),
+			String:  ".Parent[*]",
+			DynPath: "Parent.*",
+			AnyKey:  true,
+		},
+		{
+			name:     "any index",
+			node:     NewAnyIndex(NewStructField(nil, jsontag.JSONTag(""), "Parent")),
+			String:   ".Parent[*]",
+			DynPath:  "Parent[*]",
+			AnyIndex: true,
+		},
 	}
 
 	for _, tt := range tests {
@@ -172,12 +201,17 @@ func TestPathNode(t *testing.T) {
 				assert.True(t, isMapKey)
 			}
 
+			// IsRoot
 			isRoot := tt.node.IsRoot()
 			if tt.Root == nil {
 				assert.False(t, isRoot)
 			} else {
 				assert.True(t, isRoot)
 			}
+
+			// AnyKey, AnyIndex
+			assert.Equal(t, tt.AnyKey, tt.node.AnyKey())
+			assert.Equal(t, tt.AnyIndex, tt.node.AnyIndex())
 		})
 	}
 }

libs/structwalk/util_test.go

@@ -0,0 +1,73 @@
+package structwalk
+
+type Simple struct {
+	X int
+}
+
+type Types struct {
+	ValidField           string `json:"valid_field"`
+	ValidFieldNoTag      string
+	IgnoredField         string `json:"-"`
+	IgnoredFieldOdd      string `json:"-,omitempty"`
+	EmptyTagField        string `json:""`
+	unexportedField      string `json:"unexported"` //nolint
+	unexportedFieldNoTag string //nolint
+
+	IntField  int
+	BoolField bool `json:bool_field` // nolint (bad syntax)
+	AnyField  any
+
+	ValidFieldPtr           *string `json:"valid_field_ptr"`
+	ValidFieldPtrNoTag      *string
+	IgnoredFieldPtr         *string `json:"-"`
+	IgnoredFieldOddPtr      *string `json:"-,omitempty"` //nolint
+	EmptyTagFieldPtr        *string `json:""`
+	unexportedFieldPtr      *string `json:"unexported"` //nolint
+	unexportedFieldNoTagPtr *string //nolint
+
+	SliceString []string
+	ArrayString [2]string
+
+	Nested    Simple
+	NestedPtr *Simple
+	Slice     []Simple
+	Array     [2]Simple
+	Map       map[string]Simple
+	MapPtr    map[string]*Simple
+	MapIntKey map[int]*Simple
+
+	// Fields with omitempty to test ForceSendFields behaviour
+	OmitStr  string `json:"omit_str,omitempty"`
+	OmitInt  int    `json:"omit_int,omitempty"`
+	OmitBool bool   `json:"omit_bool,omitempty"`
+
+	FuncField func() string `json:"-"`
+	ChanField chan string   `json:"-"`
+
+	// List of field names to be force-sent even if they hold zero values.
+	ForceSendFields []string `json:"-"`
+}
+
+type SelfIndirect struct {
+	X *Self
+}
+
+type Self struct {
+	ValidField string `json:"valid_field"`
+
+	SelfReference *Self
+
+	SelfSlice    []Self
+	SelfSlicePtr []*Self
+
+	SelfArrayPtr [5]*Self
+
+	SelfMap    map[string]Self
+	SelfMapPtr map[string]*Self
+
+	SelfIndirect    SelfIndirect
+	SelfIndirectPtr *SelfIndirect
+
+	// List of field names to be force-sent even if they hold zero values.
+	ForceSendFields []string `json:"-"`
+}