Added ChangeIsReferenced interface

allows us to know if a change came from a referenced object.

Author: daveshanley

what-changed/model/change_types.go

@@ -45,6 +45,11 @@ type ChangeContext struct {
 	NewColumn        *int   `json:"newColumn,omitempty" yaml:"newColumn,omitempty"`
 }
 
+type ChangeIsReferenced interface {
+	GetChangeReference() string
+	SetChangeReference(ref string)
+}
+
 // HasChanged determines if the line and column numbers of the original and new values have changed.
 //
 // It's worth noting that there is no guarantee to the positions of anything in either left or right, so
@@ -98,6 +103,9 @@ type Change struct {
 
 	// Path represents the path to the object that was changed (not used in the current implementation).
 	Path string `json:"path,omitempty"`
+
+	// Reference is populated when the change is related to a $ref change.
+	Reference string `json:"reference,omitempty"`
 }
 
 // MarshalJSON is a custom JSON marshaller for the Change object.
@@ -145,9 +153,18 @@ func (c *Change) MarshalJSON() ([]byte, error) {
 // PropertyChanges holds a slice of Change pointers
 type PropertyChanges struct {
 	RenderPropertiesOnly bool      `json:"-" yaml:"-"`
+	ChangeReference      string    `json:"changeReference,omitempty""`
 	Changes              []*Change `json:"changes,omitempty" yaml:"changes,omitempty"`
 }
 
+func (p *PropertyChanges) SetChangeReference(ref string) {
+	p.ChangeReference = ref
+}
+
+func (p *PropertyChanges) GetChangeReference() string {
+	return p.ChangeReference
+}
+
 // TotalChanges returns the total number of property changes made.
 func (p *PropertyChanges) TotalChanges() int {
 	if p == nil {

what-changed/model/comparison_functions.go

@@ -5,11 +5,12 @@ package model
 
 import (
 	"fmt"
-	"github.com/pb33f/libopenapi/datamodel/low/base"
 	"reflect"
 	"strings"
 	"sync"
 
+	"github.com/pb33f/libopenapi/datamodel/low/base"
+
 	"github.com/pb33f/libopenapi/orderedmap"
 	"github.com/pb33f/libopenapi/utils"
 
@@ -24,6 +25,16 @@ const (
 
 var changeMutex sync.Mutex
 
+// SetReferenceIfExists checks if a low-level value has a reference and sets it on the change object
+// if the change object implements the ChangeIsReferenced interface.
+func SetReferenceIfExists[T any](value *low.ValueReference[T], changeObj any) {
+	if value != nil && value.IsReference() {
+		if refChange, ok := changeObj.(ChangeIsReferenced); ok {
+			refChange.SetChangeReference(value.GetReference())
+		}
+	}
+}
+
 func checkLocation(ctx *ChangeContext, hs base.HasIndex) bool {
 	if !reflect.ValueOf(hs).IsNil() {
 		idx := hs.GetIndex()
@@ -341,6 +352,9 @@ func CheckMapForChangesWithComp[T any, R any](expLeft, expRight *orderedmap.Map[
 			// https://github.com/pb33f/libopenapi/issues/61
 			if !reflect.ValueOf(&ch).Elem().IsZero() {
 				expChanges[k] = ch
+				var cr any = ch
+				pVal := p[k]
+				SetReferenceIfExists(&pVal, cr)
 			}
 			chLock.Unlock()
 		}

what-changed/model/comparison_functions_test.go

@@ -275,3 +275,155 @@ func Test_checkLocation_sameIdx(t *testing.T) {
 	assert.False(t, checkLocation(&ChangeContext{DocumentLocation: ""}, testHasIndex))
 
 }
+
+// TestSetReferenceIfExists tests the SetReferenceIfExists function
+func TestSetReferenceIfExists(t *testing.T) {
+	tests := []struct {
+		name           string
+		setupValue     func() *low.ValueReference[string]
+		setupChangeObj func() any
+		expectRef      string
+	}{
+		{
+			name: "sets reference when value has reference and object implements interface",
+			setupValue: func() *low.ValueReference[string] {
+				val := low.ValueReference[string]{
+					Value: "test",
+				}
+				val.SetReference("#/components/headers/TestHeader", nil)
+				return &val
+			},
+			setupChangeObj: func() any {
+				return &PropertyChanges{}
+			},
+			expectRef: "#/components/headers/TestHeader",
+		},
+		{
+			name: "does not set reference when value has no reference",
+			setupValue: func() *low.ValueReference[string] {
+				val := low.ValueReference[string]{
+					Value: "test",
+				}
+				return &val
+			},
+			setupChangeObj: func() any {
+				return &PropertyChanges{}
+			},
+			expectRef: "",
+		},
+		{
+			name:       "handles nil value without panic",
+			setupValue: func() *low.ValueReference[string] { return nil },
+			setupChangeObj: func() any {
+				return &PropertyChanges{}
+			},
+			expectRef: "",
+		},
+		{
+			name: "handles non-ChangeIsReferenced object without panic",
+			setupValue: func() *low.ValueReference[string] {
+				val := low.ValueReference[string]{
+					Value: "test",
+				}
+				val.SetReference("#/components/headers/TestHeader", nil)
+				return &val
+			},
+			setupChangeObj: func() any {
+				// Return something that doesn't implement ChangeIsReferenced
+				return &struct{}{}
+			},
+			expectRef: "",
+		},
+		{
+			name: "sets reference for remote reference",
+			setupValue: func() *low.ValueReference[string] {
+				val := low.ValueReference[string]{
+					Value: "test",
+				}
+				val.SetReference("./schemas.yaml#/components/schemas/TestSchema", nil)
+				return &val
+			},
+			setupChangeObj: func() any {
+				return &PropertyChanges{}
+			},
+			expectRef: "./schemas.yaml#/components/schemas/TestSchema",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			value := tt.setupValue()
+			changeObj := tt.setupChangeObj()
+
+			// Call the function
+			SetReferenceIfExists(value, changeObj)
+
+			// Check the result if it implements ChangeIsReferenced
+			if refObj, ok := changeObj.(ChangeIsReferenced); ok {
+				assert.Equal(t, tt.expectRef, refObj.GetChangeReference())
+			}
+		})
+	}
+}
+
+// TestSetReferenceIfExists_Integration tests the integration with actual comparison scenarios
+func TestSetReferenceIfExists_Integration(t *testing.T) {
+	// Create a referenced value
+	valueNode := &yaml.Node{
+		Kind:  yaml.ScalarNode,
+		Value: "test-value",
+	}
+
+	refValue := low.ValueReference[string]{
+		Value:     "test-value",
+		ValueNode: valueNode,
+	}
+	refValue.SetReference("#/components/parameters/TestParam", nil)
+
+	// Test with HeaderChanges (which embeds PropertyChanges)
+	t.Run("HeaderChanges with reference", func(t *testing.T) {
+		headerChanges := &HeaderChanges{
+			PropertyChanges: &PropertyChanges{},
+		}
+
+		SetReferenceIfExists(&refValue, headerChanges)
+		assert.Equal(t, "#/components/parameters/TestParam", headerChanges.GetChangeReference())
+	})
+
+	// Test with SchemaChanges
+	t.Run("SchemaChanges with reference", func(t *testing.T) {
+		schemaChanges := &SchemaChanges{
+			PropertyChanges: &PropertyChanges{},
+		}
+
+		SetReferenceIfExists(&refValue, schemaChanges)
+		assert.Equal(t, "#/components/parameters/TestParam", schemaChanges.GetChangeReference())
+	})
+
+	// Test that it preserves existing references
+	t.Run("preserves existing reference", func(t *testing.T) {
+		changes := &PropertyChanges{
+			ChangeReference: "#/existing/reference",
+		}
+
+		// Create a value without reference
+		nonRefValue := low.ValueReference[string]{
+			Value: "test",
+		}
+
+		SetReferenceIfExists(&nonRefValue, changes)
+		// Should still have the existing reference
+		assert.Equal(t, "#/existing/reference", changes.GetChangeReference())
+	})
+
+	// Test overwriting reference
+	t.Run("overwrites reference when new reference exists", func(t *testing.T) {
+		changes := &PropertyChanges{
+			ChangeReference: "#/old/reference",
+		}
+
+		SetReferenceIfExists(&refValue, changes)
+		// Should have the new reference
+		assert.Equal(t, "#/components/parameters/TestParam", changes.GetChangeReference())
+	})
+}