feat(cli): Add component diff sub-command

Author: dmcilvaney

internal/app/azldev/cmds/component/component.go

@@ -25,6 +25,7 @@ components defined in the project configuration.`,
 	app.AddTopLevelCommand(cmd)
 	addOnAppInit(app, cmd)
 	buildOnAppInit(app, cmd)
+	diffIdentityOnAppInit(app, cmd)
 	diffSourcesOnAppInit(app, cmd)
 	identityOnAppInit(app, cmd)
 	listOnAppInit(app, cmd)

internal/app/azldev/cmds/component/diffidentity.go

@@ -0,0 +1,179 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+package component
+
+import (
+	"encoding/json"
+	"fmt"
+	"sort"
+
+	"github.com/microsoft/azure-linux-dev-tools/internal/app/azldev"
+	"github.com/microsoft/azure-linux-dev-tools/internal/utils/fileutils"
+	"github.com/spf13/cobra"
+)
+
+func diffIdentityOnAppInit(_ *azldev.App, parentCmd *cobra.Command) {
+	parentCmd.AddCommand(NewDiffIdentityCommand())
+}
+
+// diffIdentityArgCount is the number of positional arguments required by the diff-identity command.
+const diffIdentityArgCount = 2
+
+// NewDiffIdentityCommand constructs a [cobra.Command] for "component diff-identity".
+func NewDiffIdentityCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "diff-identity <base.json> <head.json>",
+		Short: "Compare two identity files and report changed components",
+		Long: `Compare two component identity JSON files (produced by 'component identity -a -O json')
+and report which components have changed, been added, or been removed.
+
+CI uses the 'changed' and 'added' lists to determine the build queue.`,
+		Example: `  # Compare base and head identity files
+  azldev component diff-identity base-identity.json head-identity.json
+
+  # JSON output for CI
+  azldev component diff-identity base.json head.json -O json`,
+		Args: cobra.ExactArgs(diffIdentityArgCount),
+		RunE: azldev.RunFuncWithoutRequiredConfigWithExtraArgs(
+			func(env *azldev.Env, args []string) (interface{}, error) {
+				return DiffIdentities(env, args[0], args[1])
+			},
+		),
+	}
+
+	return cmd
+}
+
+// IdentityDiffStatus represents the change status of a component.
+type IdentityDiffStatus string
+
+const (
+	// IdentityDiffChanged indicates the component's fingerprint changed.
+	IdentityDiffChanged IdentityDiffStatus = "changed"
+	// IdentityDiffAdded indicates the component is new in the head.
+	IdentityDiffAdded IdentityDiffStatus = "added"
+	// IdentityDiffRemoved indicates the component was removed in the head.
+	IdentityDiffRemoved IdentityDiffStatus = "removed"
+	// IdentityDiffUnchanged indicates the component's fingerprint is identical.
+	IdentityDiffUnchanged IdentityDiffStatus = "unchanged"
+)
+
+// IdentityDiffResult is the per-component row in table output.
+type IdentityDiffResult struct {
+	Component string             `json:"component" table:",sortkey"`
+	Status    IdentityDiffStatus `json:"status"`
+}
+
+// IdentityDiffReport is the structured output for JSON format.
+type IdentityDiffReport struct {
+	Changed   []string `json:"changed"`
+	Added     []string `json:"added"`
+	Removed   []string `json:"removed"`
+	Unchanged []string `json:"unchanged"`
+}
+
+// DiffIdentities reads two identity JSON files and computes the diff.
+func DiffIdentities(env *azldev.Env, basePath string, headPath string) (interface{}, error) {
+	baseIdentities, err := readIdentityFile(env, basePath)
+	if err != nil {
+		return nil, fmt.Errorf("reading base identity file %#q:\n%w", basePath, err)
+	}
+
+	headIdentities, err := readIdentityFile(env, headPath)
+	if err != nil {
+		return nil, fmt.Errorf("reading head identity file %#q:\n%w", headPath, err)
+	}
+
+	report := ComputeDiff(baseIdentities, headIdentities)
+
+	// Return table-friendly results for table/CSV format, or the report for JSON.
+	if env.DefaultReportFormat() == azldev.ReportFormatJSON {
+		return report, nil
+	}
+
+	return buildTableResults(report), nil
+}
+
+// readIdentityFile reads and parses a component identity JSON file into a map of
+// component name to fingerprint.
+func readIdentityFile(
+	env *azldev.Env, filePath string,
+) (map[string]string, error) {
+	data, err := fileutils.ReadFile(env.FS(), filePath)
+	if err != nil {
+		return nil, fmt.Errorf("reading file:\n%w", err)
+	}
+
+	var entries []ComponentIdentityResult
+
+	err = json.Unmarshal(data, &entries)
+	if err != nil {
+		return nil, fmt.Errorf("parsing JSON:\n%w", err)
+	}
+
+	result := make(map[string]string, len(entries))
+	for _, entry := range entries {
+		result[entry.Component] = entry.Fingerprint
+	}
+
+	return result, nil
+}
+
+// ComputeDiff compares base and head identity maps and produces a diff report.
+func ComputeDiff(base map[string]string, head map[string]string) *IdentityDiffReport {
+	report := &IdentityDiffReport{}
+
+	// Check base components against head.
+	for name, baseFP := range base {
+		headFP, exists := head[name]
+
+		switch {
+		case !exists:
+			report.Removed = append(report.Removed, name)
+		case baseFP != headFP:
+			report.Changed = append(report.Changed, name)
+		default:
+			report.Unchanged = append(report.Unchanged, name)
+		}
+	}
+
+	// Check for new components in head.
+	for name := range head {
+		if _, exists := base[name]; !exists {
+			report.Added = append(report.Added, name)
+		}
+	}
+
+	// Sort all lists for deterministic output.
+	sort.Strings(report.Changed)
+	sort.Strings(report.Added)
+	sort.Strings(report.Removed)
+	sort.Strings(report.Unchanged)
+
+	return report
+}
+
+// buildTableResults converts the diff report into a slice for table output.
+func buildTableResults(report *IdentityDiffReport) []IdentityDiffResult {
+	results := make([]IdentityDiffResult, 0,
+		len(report.Changed)+len(report.Added)+len(report.Removed)+len(report.Unchanged))
+
+	for _, name := range report.Changed {
+		results = append(results, IdentityDiffResult{Component: name, Status: IdentityDiffChanged})
+	}
+
+	for _, name := range report.Added {
+		results = append(results, IdentityDiffResult{Component: name, Status: IdentityDiffAdded})
+	}
+
+	for _, name := range report.Removed {
+		results = append(results, IdentityDiffResult{Component: name, Status: IdentityDiffRemoved})
+	}
+
+	for _, name := range report.Unchanged {
+		results = append(results, IdentityDiffResult{Component: name, Status: IdentityDiffUnchanged})
+	}
+
+	return results
+}

internal/app/azldev/cmds/component/diffidentity_test.go

@@ -0,0 +1,121 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+package component_test
+
+import (
+	"testing"
+
+	"github.com/microsoft/azure-linux-dev-tools/internal/app/azldev/cmds/component"
+	"github.com/stretchr/testify/assert"
+)
+
+func TestComputeDiff(t *testing.T) {
+	t.Run("all categories", func(t *testing.T) {
+		base := map[string]string{
+			"curl":    "sha256:aaa",
+			"wget":    "sha256:bbb",
+			"openssl": "sha256:ccc",
+			"libold":  "sha256:fff",
+		}
+		head := map[string]string{
+			"curl":    "sha256:aaa",
+			"wget":    "sha256:ddd",
+			"libfoo":  "sha256:eee",
+			"openssl": "sha256:ccc",
+		}
+
+		report := component.ComputeDiff(base, head)
+
+		assert.Equal(t, []string{"wget"}, report.Changed)
+		assert.Equal(t, []string{"libfoo"}, report.Added)
+		assert.Equal(t, []string{"libold"}, report.Removed)
+		assert.Equal(t, []string{"curl", "openssl"}, report.Unchanged)
+	})
+
+	t.Run("removed component", func(t *testing.T) {
+		base := map[string]string{
+			"curl":   "sha256:aaa",
+			"libfoo": "sha256:bbb",
+		}
+		head := map[string]string{
+			"curl": "sha256:aaa",
+		}
+
+		report := component.ComputeDiff(base, head)
+
+		assert.Empty(t, report.Changed)
+		assert.Empty(t, report.Added)
+		assert.Equal(t, []string{"libfoo"}, report.Removed)
+		assert.Equal(t, []string{"curl"}, report.Unchanged)
+	})
+
+	t.Run("empty base", func(t *testing.T) {
+		base := map[string]string{}
+		head := map[string]string{
+			"curl": "sha256:aaa",
+			"wget": "sha256:bbb",
+		}
+
+		report := component.ComputeDiff(base, head)
+
+		assert.Empty(t, report.Changed)
+		assert.Equal(t, []string{"curl", "wget"}, report.Added)
+		assert.Empty(t, report.Removed)
+		assert.Empty(t, report.Unchanged)
+	})
+
+	t.Run("empty head", func(t *testing.T) {
+		base := map[string]string{
+			"curl": "sha256:aaa",
+		}
+		head := map[string]string{}
+
+		report := component.ComputeDiff(base, head)
+
+		assert.Empty(t, report.Changed)
+		assert.Empty(t, report.Added)
+		assert.Equal(t, []string{"curl"}, report.Removed)
+		assert.Empty(t, report.Unchanged)
+	})
+
+	t.Run("both empty", func(t *testing.T) {
+		report := component.ComputeDiff(map[string]string{}, map[string]string{})
+
+		assert.Empty(t, report.Changed)
+		assert.Empty(t, report.Added)
+		assert.Empty(t, report.Removed)
+		assert.Empty(t, report.Unchanged)
+	})
+
+	t.Run("identical", func(t *testing.T) {
+		both := map[string]string{
+			"curl":    "sha256:aaa",
+			"openssl": "sha256:bbb",
+		}
+
+		report := component.ComputeDiff(both, both)
+
+		assert.Empty(t, report.Changed)
+		assert.Empty(t, report.Added)
+		assert.Empty(t, report.Removed)
+		assert.Equal(t, []string{"curl", "openssl"}, report.Unchanged)
+	})
+
+	t.Run("sorted output", func(t *testing.T) {
+		base := map[string]string{
+			"zlib":    "sha256:aaa",
+			"curl":    "sha256:bbb",
+			"openssl": "sha256:ccc",
+		}
+		head := map[string]string{
+			"zlib":    "sha256:xxx",
+			"curl":    "sha256:yyy",
+			"openssl": "sha256:ccc",
+		}
+
+		report := component.ComputeDiff(base, head)
+
+		assert.Equal(t, []string{"curl", "zlib"}, report.Changed, "changed list should be sorted")
+	})
+}