Address issue #140

Reports are rendered deterministically now.

Author: daveshanley

cmd/flag_surface_test.go

@@ -30,9 +30,10 @@ func TestCanonicalCommandLocalFlags(t *testing.T) {
 	}, flagNames(GetSummaryCommand()))
 
 	assert.Equal(t, map[string]bool{
-		"no-color":   true,
-		"roger-mode": true,
-		"tektronix":  true,
+		"no-color":     true,
+		"roger-mode":   true,
+		"reproducible": true,
+		"tektronix":    true,
 	}, flagNames(GetReportCommand()))
 
 	assert.Equal(t, map[string]bool{

cmd/flatten_report.go

@@ -4,6 +4,8 @@
 package cmd
 
 import (
+	"cmp"
+	"sort"
 	"strconv"
 	"strings"
 	"time"
@@ -44,6 +46,7 @@ func flattenReport(report *model.Report, parameterNames map[string]string) *mode
 
 		changes = append(changes, &hashedChange)
 	}
+	sortFlatReportChanges(changes)
 	flatReport.Changes = changes
 
 	// Copy the Commit information from the report to the flatReport and then delete the changes
@@ -120,3 +123,130 @@ func rawPathIfChanged(rawPath, semanticPath string) string {
 	}
 	return rawPath
 }
+
+func sortFlatReportChanges(changes []*model.HashedChange) {
+	sort.SliceStable(changes, func(i, j int) bool {
+		return compareHashedChanges(changes[i], changes[j]) < 0
+	})
+}
+
+func compareHashedChanges(left, right *model.HashedChange) int {
+	if diff := cmp.Compare(changePath(left), changePath(right)); diff != 0 {
+		return diff
+	}
+	if diff := cmp.Compare(changeRawPath(left), changeRawPath(right)); diff != 0 {
+		return diff
+	}
+	if diff := cmp.Compare(changeType(left), changeType(right)); diff != 0 {
+		return diff
+	}
+	if diff := cmp.Compare(changeProperty(left), changeProperty(right)); diff != 0 {
+		return diff
+	}
+	if diff := cmp.Compare(changeKind(left), changeKind(right)); diff != 0 {
+		return diff
+	}
+	if diff := cmp.Compare(changeBreaking(left), changeBreaking(right)); diff != 0 {
+		return diff
+	}
+	if diff := cmp.Compare(changeOriginal(left), changeOriginal(right)); diff != 0 {
+		return diff
+	}
+	if diff := cmp.Compare(changeNew(left), changeNew(right)); diff != 0 {
+		return diff
+	}
+	if diff := cmp.Compare(changeOriginalEncoded(left), changeOriginalEncoded(right)); diff != 0 {
+		return diff
+	}
+	if diff := cmp.Compare(changeNewEncoded(left), changeNewEncoded(right)); diff != 0 {
+		return diff
+	}
+	if diff := cmp.Compare(changeReference(left), changeReference(right)); diff != 0 {
+		return diff
+	}
+	return cmp.Compare(changeHash(left), changeHash(right))
+}
+
+func changePath(change *model.HashedChange) string {
+	if change == nil || change.Change == nil {
+		return ""
+	}
+	return change.Path
+}
+
+func changeRawPath(change *model.HashedChange) string {
+	if change == nil {
+		return ""
+	}
+	return change.RawPath
+}
+
+func changeType(change *model.HashedChange) string {
+	if change == nil || change.Change == nil {
+		return ""
+	}
+	return change.Type
+}
+
+func changeProperty(change *model.HashedChange) string {
+	if change == nil || change.Change == nil {
+		return ""
+	}
+	return change.Property
+}
+
+func changeKind(change *model.HashedChange) int {
+	if change == nil || change.Change == nil {
+		return 0
+	}
+	return change.ChangeType
+}
+
+func changeBreaking(change *model.HashedChange) int {
+	if change == nil || change.Change == nil || !change.Breaking {
+		return 0
+	}
+	return 1
+}
+
+func changeOriginal(change *model.HashedChange) string {
+	if change == nil || change.Change == nil {
+		return ""
+	}
+	return change.Original
+}
+
+func changeNew(change *model.HashedChange) string {
+	if change == nil || change.Change == nil {
+		return ""
+	}
+	return change.New
+}
+
+func changeOriginalEncoded(change *model.HashedChange) string {
+	if change == nil || change.Change == nil {
+		return ""
+	}
+	return change.OriginalEncoded
+}
+
+func changeNewEncoded(change *model.HashedChange) string {
+	if change == nil || change.Change == nil {
+		return ""
+	}
+	return change.NewEncoded
+}
+
+func changeReference(change *model.HashedChange) string {
+	if change == nil || change.Change == nil {
+		return ""
+	}
+	return change.Reference
+}
+
+func changeHash(change *model.HashedChange) string {
+	if change == nil {
+		return ""
+	}
+	return change.ChangeHash
+}

cmd/flatten_report_test.go

@@ -7,6 +7,7 @@ import (
 	"testing"
 
 	wcModel "github.com/pb33f/libopenapi/what-changed/model"
+	openapiModel "github.com/pb33f/openapi-changes/model"
 	"github.com/stretchr/testify/assert"
 )
 
@@ -176,3 +177,46 @@ func TestRawPathIfChanged_SamePaths(t *testing.T) {
 func TestRawPathIfChanged_DifferentPaths(t *testing.T) {
 	assert.Equal(t, "$.parameters[0]", rawPathIfChanged("$.parameters[0]", "$.parameters['petId']"))
 }
+
+func TestFlattenReport_SortsChangesDeterministically(t *testing.T) {
+	report := &openapiModel.Report{
+		Commit: &openapiModel.Commit{
+			Changes: &wcModel.DocumentChanges{
+				PropertyChanges: wcModel.NewPropertyChanges([]*wcModel.Change{
+					{
+						Context:    &wcModel.ChangeContext{},
+						ChangeType: wcModel.PropertyAdded,
+						Path:       "$.paths['/pets'].post",
+						Property:   "summary",
+						Type:       "operation",
+						New:        "create a pet",
+					},
+					{
+						Context:    &wcModel.ChangeContext{},
+						ChangeType: wcModel.Modified,
+						Path:       "$.info",
+						Property:   "title",
+						Type:       "info",
+						Original:   "zeta",
+						New:        "alpha",
+					},
+					{
+						Context:    &wcModel.ChangeContext{},
+						ChangeType: wcModel.PropertyRemoved,
+						Path:       "$.paths['/pets'].get",
+						Property:   "description",
+						Type:       "operation",
+						Original:   "list pets",
+					},
+				}),
+			},
+		},
+	}
+
+	flat := FlattenReport(report)
+
+	assert.Len(t, flat.Changes, 3)
+	assert.Equal(t, "$.info", flat.Changes[0].Path)
+	assert.Equal(t, "$.paths['/pets'].get", flat.Changes[1].Path)
+	assert.Equal(t, "$.paths['/pets'].post", flat.Changes[2].Path)
+}

cmd/report.go

@@ -146,6 +146,10 @@ func GetReportCommand() *cobra.Command {
 			if err != nil {
 				return err
 			}
+			reproducible, err := cmd.Flags().GetBool("reproducible")
+			if err != nil {
+				return err
+			}
 
 			if len(args) == 0 {
 				maybePrintBanner(cmd, opts.palette)
@@ -174,15 +178,18 @@ func GetReportCommand() *cobra.Command {
 				if reportErr != nil {
 					return reportErr
 				}
+				if reproducible {
+					makeReportOutputReproducible(flat)
+				}
 				return printReportJSON(flat)
 			}
 
 			if !isHTTPURL(args[0]) {
 				if _, _, ok := parseGitRef(args[0]); ok {
-					return printReportJSONOrNoChanges(args, opts, breakingConfig)
+					return printReportJSONOrNoChanges(args, opts, breakingConfig, reproducible)
 				}
 				if _, _, ok := parseGitRef(args[1]); ok {
-					return printReportJSONOrNoChanges(args, opts, breakingConfig)
+					return printReportJSONOrNoChanges(args, opts, breakingConfig, reproducible)
 				}
 				f, statErr := os.Stat(args[0])
 				if statErr == nil && f.IsDir() {
@@ -194,18 +201,22 @@ func GetReportCommand() *cobra.Command {
 						printNoChangesJSON()
 						return nil
 					}
+					if reproducible {
+						makeReportOutputReproducible(flat)
+					}
 					return printReportJSON(flat)
 				}
 			}
 
-			return printReportJSONOrNoChanges(args, opts, breakingConfig)
+			return printReportJSONOrNoChanges(args, opts, breakingConfig, reproducible)
 		},
 	}
 	addTerminalThemeFlags(cmd)
+	cmd.Flags().Bool("reproducible", false, "Omit generated timestamps so report JSON is stable across runs")
 	return cmd
 }
 
-func printReportJSONOrNoChanges(args []string, opts summaryOpts, breakingConfig *whatChangedModel.BreakingRulesConfig) error {
+func printReportJSONOrNoChanges(args []string, opts summaryOpts, breakingConfig *whatChangedModel.BreakingRulesConfig, reproducible bool) error {
 	flat, reportErr := runLeftRightReport(args[0], args[1], opts, breakingConfig)
 	if reportErr != nil {
 		return reportErr
@@ -214,5 +225,37 @@ func printReportJSONOrNoChanges(args []string, opts summaryOpts, breakingConfig
 		printNoChangesJSON()
 		return nil
 	}
+	if reproducible {
+		makeReportOutputReproducible(flat)
+	}
 	return printReportJSON(flat)
 }
+
+func makeReportOutputReproducible(report any) {
+	switch typed := report.(type) {
+	case *model.FlatReport:
+		if typed != nil {
+			makeFlatReportReproducible(typed)
+		}
+	case *model.FlatHistoricalReport:
+		if typed == nil {
+			return
+		}
+		typed.DateGenerated = ""
+		for _, item := range typed.Reports {
+			makeFlatReportReproducible(item)
+		}
+	}
+}
+
+func makeFlatReportReproducible(report *model.FlatReport) {
+	if report == nil {
+		return
+	}
+	report.DateGenerated = ""
+	for _, change := range report.Changes {
+		if change != nil {
+			change.RawPath = ""
+		}
+	}
+}

cmd/report_test.go

@@ -165,6 +165,31 @@ func TestRunLeftRightReport_OmitsCommitDetailsInJSON(t *testing.T) {
 	assert.NotContains(t, string(encoded), "commitDetails")
 }
 
+func TestReportCommand_ReproducibleOutputIsStableAcrossRuns(t *testing.T) {
+	args := []string{
+		"--no-logo",
+		"--no-color",
+		"--reproducible",
+		"../sample-specs/petstorev3-original.json",
+		"../sample-specs/petstorev3.json",
+	}
+
+	runOnce := func() string {
+		cmd := testRootCmd(GetReportCommand(), args...)
+		return captureStdout(t, func() {
+			require.NoError(t, cmd.Execute())
+		})
+	}
+
+	first := runOnce()
+	second := runOnce()
+
+	assert.Equal(t, first, second)
+	assert.NotContains(t, first, `"dateGenerated"`)
+	assert.NotContains(t, first, `"commitDetails"`)
+	assert.NotContains(t, first, `"rawPath"`)
+}
+
 func TestRunLeftRightReport_GitRefExplodedSpecIncludesSiblingChanges(t *testing.T) {
 	repoDir, _ := createExplodedGitSpecRepo(t)
 	chdirForTest(t, repoDir)

model/report.go

@@ -87,6 +87,6 @@ type FlatHistoricalReport struct {
 	GitRepoPath   string        `json:"gitRepoPath"`
 	GitFilePath   string        `json:"gitFilePath"`
 	Filename      string        `json:"filename"`
-	DateGenerated string        `json:"dateGenerated"`
+	DateGenerated string        `json:"dateGenerated,omitempty"`
 	Reports       []*FlatReport `json:"reports" `
 }