Merge pull request #64 from AryaHassanli/zapdiff

Introduce ZAPDiff Action and Refactor ZAPDiff CLI

Author: AryaHassanli

cmd/action/action.go

@@ -5,4 +5,5 @@ type Action struct {
 	Disco      Disco      `cmd:"" default:"" help:"GitHub action for Matter spec documents"`
 	ZAP        ZAP        `cmd:"" help:"GitHub action for Matter SDK ZAP XML"`
 	MergeGuard MergeGuard `cmd:"" help:"GitHub action to prevent Provisionality and Parse errors to be merged."`
+	ZAPDiff    ZAPDiff    `cmd:"" help:"GitHub action for ZAP XML diff"`
 }

cmd/action/zapdiff.go

@@ -0,0 +1,65 @@
+package action
+
+import (
+	"log/slog"
+
+	"github.com/project-chip/alchemy/cmd/cli"
+)
+
+type ZAPDiffConfig struct {
+	ComparisonSets []ComparisonSet `yaml:"comparison_sets"`
+}
+
+type ComparisonSet struct {
+	SDKRef                  string `yaml:"sdk_ref"`
+	SDKLabel                string `yaml:"sdk_label"`
+	SpecRef                 string `yaml:"spec_ref"`
+	SpecLabel               string `yaml:"spec_label"`
+	ZapGenerationAttributes string `yaml:"zap_generation_attributes"`
+	AlchemyRef              string `yaml:"alchemy_ref"`
+}
+
+type ZAPDiff struct {
+	BaselineXMLDir   string `name:"baseline-xml" help:"Path to baseline XML file or directory" required:"true"`
+	GeneratedXMLDir  string `name:"generated-xml" help:"Path to generated XML file or directory" required:"true"`
+	GeneratedSDKRoot string `name:"sdk-root" help:"Path to SDK root directory (for ZAP generation)" required:"true"`
+	SDKLabel         string `name:"sdk-label" help:"Label for SDK (used in human-readable reports)" default:"SDK"`
+	SpecLabel        string `name:"spec-label" help:"Label for Spec (used in human-readable reports)" default:"Spec"`
+	GenAttributes    string `name:"gen-attributes" help:"Zap generation attributes"`
+	MismatchLevel    int    `name:"mismatch-level" help:"Mismatch level to report (1-3); 1 is most important" default:"3"`
+	SpecRoot         string `name:"spec-root" help:"Path to Spec root directory" default:"."`
+}
+
+func (z *ZAPDiff) Run(cc *cli.Context) (err error) {
+	slog.Info("Running ZAP generation", "attributes", z.GenAttributes)
+	zapCmd := &cli.ZAP{}
+	zapCmd.Root = z.SpecRoot
+	zapCmd.SdkRoot = z.GeneratedSDKRoot
+	zapCmd.Attribute = []string{z.GenAttributes}
+	zapCmd.FeatureXML = true
+	zapCmd.ConformanceXML = true
+	zapCmd.NoProgress = true
+	err = zapCmd.Run(cc)
+	if err != nil {
+		slog.Error("ZAP generation failed", "error", err)
+		return err
+	}
+
+	slog.Info("Running ZAPDiff", "xml1", z.BaselineXMLDir, "xml2", z.GeneratedXMLDir)
+	diffCmd := &cli.ZAPDiff{}
+	diffCmd.XmlRoot1 = z.BaselineXMLDir
+	diffCmd.XmlRoot2 = z.GeneratedXMLDir
+	diffCmd.Label1 = z.SDKLabel
+	diffCmd.Label2 = z.SpecLabel
+	diffCmd.MismatchLevel = z.MismatchLevel
+	diffCmd.Format = "both"
+
+	err = diffCmd.Run(cc)
+	if err != nil {
+		slog.Error("ZAPDiff failed", "error", err)
+		return err
+	}
+
+	slog.Info("zapdiff Action completed successfully")
+	return nil
+}

cmd/cli/zapdiff.go

@@ -1,11 +1,10 @@
 package cli
 
 import (
-	"encoding/csv"
+	"io"
 	"log/slog"
 	"os"
 	"path/filepath"
-	"sort"
 	"strings"
 
 	"github.com/project-chip/alchemy/zapdiff"
@@ -16,17 +15,19 @@ type ZAPDiff struct {
 	XmlRoot2      string `help:"root of second set of ZAP XMLs" group:"SDK Commands:" required:"true"`
 	Label1        string `default:"ZapXML-1" help:"label for first set of ZAP XMLs" group:"SDK Commands:"`
 	Label2        string `default:"ZapXML-2" help:"label for second set of ZAP XMLs" group:"SDK Commands:"`
-	Out           string `default:"." help:"path to output mismatch.csv file" group:"SDK Commands:"`
+	Out           string `default:"." help:"path to output mismatch files" group:"SDK Commands:"`
+	Format        string `default:"both" help:"output format: csv, html, or both" group:"SDK Commands:"`
 	MismatchLevel int    `default:"3" help:"the minimum mismatch level to report (1-3)" group:"SDK Commands:"`
 }
 
 func (z *ZAPDiff) Run(cc *Context) (err error) {
+
 	var mismatchPrintLevel zapdiff.XmlMismatchLevel
 	if z.MismatchLevel < 1 || z.MismatchLevel > 3 {
 		slog.Warn("invalid mismatch level. must be between 1 and 3.", "level", z.MismatchLevel)
 		mismatchPrintLevel = zapdiff.MismatchLevel3 // Default
 	} else {
-		mismatchPrintLevel = zapdiff.XmlMismatchLevel(z.MismatchLevel - 1) // Convert 1-3 to 0-2
+		mismatchPrintLevel = zapdiff.XmlMismatchLevel(3 - z.MismatchLevel)
 	}
 
 	ff1, err := listXMLFiles(z.XmlRoot1)
@@ -43,16 +44,37 @@ func (z *ZAPDiff) Run(cc *Context) (err error) {
 
 	mm := zapdiff.Pipeline(ff1, ff2, z.Label1, z.Label2)
 
-	csvOutputPath := filepath.Join(z.Out, "mismatches.csv")
-	err = writeMismatchesToCSV(csvOutputPath, mm, mismatchPrintLevel)
-	if err != nil {
-		slog.Error("Failed to write CSV output", "error", err)
+	generateCSV := z.Format == "csv" || z.Format == "both" || z.Format == ""
+	if generateCSV {
+		err = writeMismatchesFile(z.Out, "mismatches.csv", "CSV", func(w io.Writer) error {
+			return zapdiff.WriteMismatchesToCSV(w, mm, mismatchPrintLevel)
+		})
+		if err != nil {
+			return err
+		}
 	}
 
-	return
+	generateHTML := z.Format == "html" || z.Format == "both" || z.Format == ""
+	if generateHTML {
+		err = writeMismatchesFile(z.Out, "mismatches.html", "HTML", func(w io.Writer) error {
+			return zapdiff.WriteMismatchesToHTML(w, mm, mismatchPrintLevel, z.XmlRoot1, z.XmlRoot2)
+		})
+		if err != nil {
+			return err
+		}
+	}
+
+	return nil
 }
 
 func listXMLFiles(p string) (paths []string, err error) {
+	fi, err := os.Stat(p)
+	if err != nil {
+		return nil, err
+	}
+	if !fi.IsDir() {
+		return []string{p}, nil
+	}
 	var entries []os.DirEntry
 	entries, err = os.ReadDir(p)
 	if err != nil {
@@ -68,63 +90,19 @@ func listXMLFiles(p string) (paths []string, err error) {
 	return
 }
 
-func writeMismatchesToCSV(p string, mm []zapdiff.XmlMismatch, l zapdiff.XmlMismatchLevel) (err error) {
-	f, err := os.Create(p)
+func writeMismatchesFile(outDir string, filename string, formatName string, writeFn func(io.Writer) error) error {
+	outputPath := filepath.Join(outDir, filename)
+	f, err := os.Create(outputPath)
 	if err != nil {
-		slog.Error("failed to create file", "path", p, "error", err)
+		slog.Error("failed to create "+formatName+" file", "path", outputPath, "error", err)
 		return err
 	}
 	defer f.Close()
-
-	w := csv.NewWriter(f)
-	defer func() {
-		w.Flush()
-		if err == nil {
-			err = w.Error()
-		}
-	}()
-
-	// Write header
-	header := []string{"Level", "Type", "File", "Element Xpath", "Details"}
-	if err = w.Write(header); err != nil {
-		slog.Error("failed to write CSV header", "error", err)
-		return
-	}
-
-	sort.Slice(mm, func(i, j int) bool {
-		// Level (Descending), Path, Type, ElementID, Details
-		if mm[i].Level() != mm[j].Level() {
-			return mm[i].Level() > mm[j].Level()
-		}
-		if mm[i].Path != mm[j].Path {
-			return mm[i].Path < mm[j].Path
-		}
-		if mm[i].Type != mm[j].Type {
-			return mm[i].Type.String() < mm[j].Type.String()
-		}
-		if mm[i].ElementID != mm[j].ElementID {
-			return mm[i].ElementID < mm[j].ElementID
-		}
-		return mm[i].Details < mm[j].Details
-	})
-
-	// Write mismatches
-	for _, m := range mm {
-		if m.Level() >= l {
-			row := []string{
-				m.Level().String(),
-				m.Type.String(),
-				m.Path,
-				m.ElementID,
-				m.Details,
-			}
-			if err = w.Write(row); err != nil {
-				slog.Error("Warning: failed to write row to CSV", "err", err)
-				return
-			}
-		}
+	err = writeFn(f)
+	if err != nil {
+		slog.Error("Failed to write "+formatName+" output", "error", err)
+	} else {
+		slog.Info("Successfully wrote mismatches to "+formatName, "dir", outputPath)
 	}
-
-	slog.Info("Successfully wrote mismatches to CSV", "dir", p)
-	return
+	return nil
 }

cmd/github.go

@@ -13,6 +13,7 @@ var commands struct {
 	Disco      action.Disco      `cmd:"" name:"disco" default:"" help:"Disco ball Matter spec documents specified by the filename_pattern" group:"Spec Actions:"`
 	ZAP        action.ZAP        `cmd:"" help:"Transmute the Matter spec into ZAP templates, optionally filtered to the files specified by filename_pattern" group:"SDK Actions:"`
 	MergeGuard action.MergeGuard `cmd:"" help:"GitHub action for checking Provisionality and Parse errors."`
+	ZAPDiff    action.ZAPDiff    `cmd:"" name:"zap-diff" help:"GitHub action for ZAP XML diff"`
 
 	Version Version `cmd:"" hidden:"" name:"version" help:"display version number"`
 

zapdiff/check.go

@@ -12,22 +12,22 @@ func checkMismatches(ep elementPair, baseName string, n1, n2 string) (mm []XmlMi
 	mm = make([]XmlMismatch, 0)
 
 	for _, c1 := range ep.e1.ChildElements() {
-		id := getElementID(c1)
+		id := getEntityUniqueIdentifier(c1)
 		e1Children[id] = c1
 	}
 
 	for _, c2 := range ep.e2.ChildElements() {
-		id := getElementID(c2)
+		id := getEntityUniqueIdentifier(c2)
 		e2Children[id] = c2
 	}
 
 	for id, e1 := range e1Children {
 		if _, ok := e2Children[id]; !ok {
 			m := XmlMismatch{
-				Path:      baseName,
-				Type:      getMismatchMissingType(e1),
-				Details:   fmt.Sprintf("Only found in %s", n1),
-				ElementID: id,
+				Path:                   baseName,
+				Type:                   getMismatchMissingType(e1),
+				Details:                fmt.Sprintf("Only found in %s", n1),
+				EntityUniqueIdentifier: id,
 			}
 			mm = append(mm, m)
 		}
@@ -36,10 +36,10 @@ func checkMismatches(ep elementPair, baseName string, n1, n2 string) (mm []XmlMi
 	for id, e2 := range e2Children {
 		if _, ok := e1Children[id]; !ok {
 			m := XmlMismatch{
-				Path:      baseName,
-				Type:      getMismatchMissingType(e2),
-				Details:   fmt.Sprintf("Only found in %s", n2),
-				ElementID: id,
+				Path:                   baseName,
+				Type:                   getMismatchMissingType(e2),
+				Details:                fmt.Sprintf("Only found in %s", n2),
+				EntityUniqueIdentifier: id,
 			}
 			mm = append(mm, m)
 		}
@@ -76,18 +76,18 @@ func checkAttributes(ep elementPair, id string, baseName string, n1, n2 string)
 	for k, v1 := range e1Attrs {
 		if v2, ok := e2Attrs[k]; !ok {
 			m := XmlMismatch{
-				Path:      baseName,
-				Type:      getMismatchMissingAttrType(ep.e1),
-				Details:   fmt.Sprintf("Attribute [%s] only found in %s", k, n1),
-				ElementID: id,
+				Path:                   baseName,
+				Type:                   getMismatchMissingAttrType(ep.e1),
+				Details:                fmt.Sprintf("Attribute [%s] only found in %s", k, n1),
+				EntityUniqueIdentifier: id,
 			}
 			mm = append(mm, m)
 		} else if v1 != v2 {
 			m := XmlMismatch{
-				Path:      baseName,
-				Type:      getMismatchAttrValueType(ep.e1),
-				Details:   fmt.Sprintf("Attribute [%s] has different values: '%s' in %s, '%s' in %s", k, v1, n1, v2, n2),
-				ElementID: id,
+				Path:                   baseName,
+				Type:                   getMismatchAttrValueType(ep.e1),
+				Details:                fmt.Sprintf("Attribute [%s] has different values: '%s' in %s, '%s' in %s", k, v1, n1, v2, n2),
+				EntityUniqueIdentifier: id,
 			}
 			mm = append(mm, m)
 		}
@@ -96,10 +96,10 @@ func checkAttributes(ep elementPair, id string, baseName string, n1, n2 string)
 	for k := range e2Attrs {
 		if _, ok := e1Attrs[k]; !ok {
 			m := XmlMismatch{
-				Path:      baseName,
-				Type:      getMismatchMissingAttrType(ep.e2),
-				Details:   fmt.Sprintf("Attribute [%s] only found in %s", k, n2),
-				ElementID: id,
+				Path:                   baseName,
+				Type:                   getMismatchMissingAttrType(ep.e2),
+				Details:                fmt.Sprintf("Attribute [%s] only found in %s", k, n2),
+				EntityUniqueIdentifier: id,
 			}
 			mm = append(mm, m)
 		}

zapdiff/csv.go

@@ -0,0 +1,62 @@
+package zapdiff
+
+import (
+	"encoding/csv"
+	"io"
+	"log/slog"
+	"sort"
+)
+
+// WriteMismatchesToCSV writes the given mismatches to the writer in CSV format.
+func WriteMismatchesToCSV(w io.Writer, mm []XmlMismatch, l XmlMismatchLevel) (err error) {
+	csvWriter := csv.NewWriter(w)
+	defer func() {
+		csvWriter.Flush()
+		if err == nil {
+			err = csvWriter.Error()
+		}
+	}()
+
+	// Write header
+	header := []string{"Level", "Type", "File", "Element Xpath", "Details"}
+	if err = csvWriter.Write(header); err != nil {
+		slog.Error("failed to write CSV header", "error", err)
+		return
+	}
+
+	sort.Slice(mm, func(i, j int) bool {
+		// Level (Descending), Path, Type, EntityUniqueIdentifier, Details
+		if mm[i].Level() != mm[j].Level() {
+			return mm[i].Level() > mm[j].Level()
+		}
+		if mm[i].Path != mm[j].Path {
+			return mm[i].Path < mm[j].Path
+		}
+		if mm[i].Type != mm[j].Type {
+			return mm[i].Type.String() < mm[j].Type.String()
+		}
+		if mm[i].EntityUniqueIdentifier != mm[j].EntityUniqueIdentifier {
+			return mm[i].EntityUniqueIdentifier < mm[j].EntityUniqueIdentifier
+		}
+		return mm[i].Details < mm[j].Details
+	})
+
+	// Write mismatches
+	for _, m := range mm {
+		if m.Level() >= l {
+			row := []string{
+				m.Level().String(),
+				m.Type.String(),
+				m.Path,
+				m.EntityUniqueIdentifier,
+				m.Details,
+			}
+			if err = csvWriter.Write(row); err != nil {
+				slog.Error("Warning: failed to write row to CSV", "err", err)
+				return
+			}
+		}
+	}
+
+	return
+}