feat: add structured output mode for helm-diff (#899)

* feat: add structured output mode for helm-diff

* fix lint errors

* fix: log panic msg and add tests for error paths

* refactor: improve error handling in structured entry creation and update tests

Author: madhunzv

README.md

@@ -115,7 +115,7 @@ Flags:
       --no-color                                 remove colors from the output. If both --no-color and --color are unspecified, coloring enabled only when the stdout is a term and TERM is not "dumb"
       --no-hooks                                 disable diffing of hooks
       --normalize-manifests                      normalize manifests before running diff to exclude style differences from the output
-      --output string                            Possible values: diff, simple, template, dyff. When set to "template", use the env var HELM_DIFF_TPL to specify the template. (default "diff")
+      --output string                            Possible values: diff, simple, template, json, structured, dyff. When set to "template", use the env var HELM_DIFF_TPL to specify the template. (default "diff")
       --post-renderer string                     the path to an executable to be used for post rendering. If it exists in $PATH, the binary will be used, otherwise it will try to look for the executable at the given path
       --post-renderer-args stringArray           an argument to the post-renderer (can specify multiple)
       --repo string                              specify the chart repository url to locate the requested chart
@@ -145,6 +145,33 @@ Additional help topcis:
 Use "diff [command] --help" for more information about a command.
 ```
 
+### Structured JSON output
+
+Set `--output structured` (or `HELM_DIFF_OUTPUT=structured`) to emit machine-readable JSON. Each entry reports the Kubernetes object metadata, resource existence, and per-field changes using JSON Pointer paths:
+
+```shell
+helm diff upgrade prod api ./charts/api --output structured
+```
+
+```json
+[
+  {
+    "apiVersion": "apps/v1",
+    "kind": "Deployment",
+    "namespace": "prod",
+    "name": "api",
+    "changeType": "MODIFY",
+    "resourceStatus": {"oldExists": true, "newExists": true},
+    "changes": [
+      {"path": "spec", "field": "replicas", "change": "replace", "oldValue": 2, "newValue": 3},
+      {"path": "spec.template.spec.containers[0]", "field": "image", "change": "replace", "oldValue": "api:v1", "newValue": "api:v2"}
+    ]
+  }
+]
+```
+
+When a kind is suppressed via `--suppress`, `changesSuppressed` is set to `true` and field details are omitted. Nested metadata such as labels show the container path (`metadata.labels`) and expose the label key through the `field` property (for example `app.kubernetes.io/version`).
+
 ## Commands:
 
 ### upgrade:
@@ -211,7 +238,7 @@ Flags:
       --kubeconfig string                        This flag is ignored, to allow passing of this top level flag to helm
       --no-hooks                                 disable diffing of hooks
       --normalize-manifests                      normalize manifests before running diff to exclude style differences from the output
-      --output string                            Possible values: diff, simple, template, dyff. When set to "template", use the env var HELM_DIFF_TPL to specify the template. (default "diff")
+      --output string                            Possible values: diff, simple, template, json, structured, dyff. When set to "template", use the env var HELM_DIFF_TPL to specify the template. (default "diff")
       --post-renderer string                     the path to an executable to be used for post rendering. If it exists in $PATH, the binary will be used, otherwise it will try to look for the executable at the given path
       --post-renderer-args stringArray           an argument to the post-renderer (can specify multiple)
       --repo string                              specify the chart repository url to locate the requested chart
@@ -266,7 +293,7 @@ Flags:
   -h, --help                                     help for release
       --include-tests                            enable the diffing of the helm test hooks
       --normalize-manifests                      normalize manifests before running diff to exclude style differences from the output
-      --output string                            Possible values: diff, simple, template, dyff. When set to "template", use the env var HELM_DIFF_TPL to specify the template. (default "diff")
+      --output string                            Possible values: diff, simple, template, json, structured, dyff. When set to "template", use the env var HELM_DIFF_TPL to specify the template. (default "diff")
       --show-secrets                             do not redact secret values in the output
       --strip-trailing-cr                        strip trailing carriage return on input
       --suppress stringArray                     allows suppression of the kinds listed in the diff output (can specify multiple, like '--suppress Deployment --suppress Service')
@@ -308,7 +335,7 @@ Flags:
   -h, --help                                     help for revision
       --include-tests                            enable the diffing of the helm test hooks
       --normalize-manifests                      normalize manifests before running diff to exclude style differences from the output
-      --output string                            Possible values: diff, simple, template, dyff. When set to "template", use the env var HELM_DIFF_TPL to specify the template. (default "diff")
+      --output string                            Possible values: diff, simple, template, json, structured, dyff. When set to "template", use the env var HELM_DIFF_TPL to specify the template. (default "diff")
       --show-secrets                             do not redact secret values in the output
       --show-secrets-decoded                     decode secret values in the output
       --strip-trailing-cr                        strip trailing carriage return on input
@@ -344,7 +371,7 @@ Flags:
   -h, --help                                     help for rollback
       --include-tests                            enable the diffing of the helm test hooks
       --normalize-manifests                      normalize manifests before running diff to exclude style differences from the output
-      --output string                            Possible values: diff, simple, template, dyff. When set to "template", use the env var HELM_DIFF_TPL to specify the template. (default "diff")
+      --output string                            Possible values: diff, simple, template, json, structured, dyff. When set to "template", use the env var HELM_DIFF_TPL to specify the template. (default "diff")
       --show-secrets                             do not redact secret values in the output
       --show-secrets-decoded                     decode secret values in the output
       --strip-trailing-cr                        strip trailing carriage return on input

cmd/options.go

@@ -13,7 +13,7 @@ func AddDiffOptions(f *pflag.FlagSet, o *diff.Options) {
 	f.BoolVar(&o.ShowSecretsDecoded, "show-secrets-decoded", false, "decode secret values in the output")
 	f.StringArrayVar(&o.SuppressedKinds, "suppress", []string{}, "allows suppression of the kinds listed in the diff output (can specify multiple, like '--suppress Deployment --suppress Service')")
 	f.IntVarP(&o.OutputContext, "context", "C", -1, "output NUM lines of context around changes")
-	f.StringVar(&o.OutputFormat, "output", "diff", "Possible values: diff, simple, template, dyff. When set to \"template\", use the env var HELM_DIFF_TPL to specify the template.")
+	f.StringVar(&o.OutputFormat, "output", "diff", "Possible values: diff, simple, template, json, structured, dyff. When set to \"template\", use the env var HELM_DIFF_TPL to specify the template.")
 	f.BoolVar(&o.StripTrailingCR, "strip-trailing-cr", false, "strip trailing carriage return on input")
 	f.Float32VarP(&o.FindRenames, "find-renames", "D", 0, "Enable rename detection if set to any value greater than 0. If specified, the value denotes the maximum fraction of changed content as lines added + removed compared to total lines in a diff for considering it a rename. Only objects of the same Kind are attempted to be matched")
 	f.StringArrayVar(&o.SuppressedOutputLineRegex, "suppress-output-line-regex", []string{}, "a regex to suppress diff output lines that match")

diff/diff.go

@@ -5,6 +5,7 @@ import (
 	"fmt"
 	"io"
 	"math"
+	"os"
 	"regexp"
 	"sort"
 	"strings"
@@ -31,6 +32,11 @@ type Options struct {
 	SuppressedOutputLineRegex []string
 }
 
+// StructuredOutput returns true when the structured JSON output is requested.
+func (o *Options) StructuredOutput() bool {
+	return o != nil && o.OutputFormat == "structured"
+}
+
 type OwnershipDiff struct {
 	OldRelease string
 	NewRelease string
@@ -65,7 +71,7 @@ func generateReport(oldIndex, newIndex map[string]*manifest.MappingResult, newOw
 
 	for name, diff := range newOwnedReleases {
 		diff := diffStrings(diff.OldRelease, diff.NewRelease, true)
-		report.addEntry(name, options.SuppressedKinds, "", 0, diff, "OWNERSHIP")
+		report.addEntry(name, options.SuppressedKinds, "", 0, diff, "OWNERSHIP", nil)
 	}
 
 	for _, key := range sortedKeys(oldIndex) {
@@ -159,7 +165,7 @@ func doSuppress(report Report, suppressedOutputLineRegex []string) (Report, erro
 			entry.ChangeType = "MODIFY_SUPPRESSED"
 		}
 
-		filteredReport.addEntry(entry.Key, entry.SuppressedKinds, entry.Kind, entry.Context, diffRecords, entry.ChangeType)
+		filteredReport.addEntry(entry.Key, entry.SuppressedKinds, entry.Kind, entry.Context, diffRecords, entry.ChangeType, entry.Structured)
 	}
 
 	return filteredReport, nil
@@ -235,20 +241,56 @@ func doDiff(report *Report, key string, oldContent *manifest.MappingResult, newC
 		redactSecrets(oldContent, newContent)
 	}
 
-	if oldContent == nil {
-		emptyMapping := &manifest.MappingResult{}
-		diffs := diffMappingResults(emptyMapping, newContent, options.StripTrailingCR)
-		report.addEntry(key, options.SuppressedKinds, newContent.Kind, options.OutputContext, diffs, "ADD")
-	} else if newContent == nil {
-		emptyMapping := &manifest.MappingResult{}
-		diffs := diffMappingResults(oldContent, emptyMapping, options.StripTrailingCR)
-		report.addEntry(key, options.SuppressedKinds, oldContent.Kind, options.OutputContext, diffs, "REMOVE")
-	} else {
-		diffs := diffMappingResults(oldContent, newContent, options.StripTrailingCR)
-		if actualChanges(diffs) > 0 {
-			report.addEntry(key, options.SuppressedKinds, oldContent.Kind, options.OutputContext, diffs, "MODIFY")
+	var changeType string
+	var subjectKind string
+	var diffs []difflib.DiffRecord
+	switch {
+	case oldContent == nil:
+		changeType = "ADD"
+		if newContent != nil {
+			subjectKind = newContent.Kind
+		}
+		if !options.StructuredOutput() && newContent != nil {
+			emptyMapping := &manifest.MappingResult{}
+			diffs = diffMappingResults(emptyMapping, newContent, options.StripTrailingCR)
+		}
+	case newContent == nil:
+		changeType = "REMOVE"
+		if oldContent != nil {
+			subjectKind = oldContent.Kind
+		}
+		if !options.StructuredOutput() && oldContent != nil {
+			emptyMapping := &manifest.MappingResult{}
+			diffs = diffMappingResults(oldContent, emptyMapping, options.StripTrailingCR)
+		}
+	default:
+		changeType = "MODIFY"
+		subjectKind = oldContent.Kind
+		if !options.StructuredOutput() {
+			diffs = diffMappingResults(oldContent, newContent, options.StripTrailingCR)
+			if actualChanges(diffs) == 0 {
+				return
+			}
+		}
+	}
+
+	var structured *StructuredEntry
+	if options.StructuredOutput() {
+		entry, err := buildStructuredEntry(key, changeType, subjectKind, options.SuppressedKinds, oldContent, newContent)
+		if err != nil {
+			// Log warning and omit field-level changes for this entry
+			// printStructuredReport() will still output a basic entry with name and changeType
+			fmt.Fprintf(os.Stderr, "Warning: failed to build structured entry for %s (kind: %s, changeType: %s): %v\n",
+				key, subjectKind, changeType, err)
+		} else {
+			if changeType == "MODIFY" && !entry.ChangesSuppressed && len(entry.Changes) == 0 {
+				return
+			}
+			structured = entry
 		}
 	}
+
+	report.addEntry(key, options.SuppressedKinds, subjectKind, options.OutputContext, diffs, changeType, structured)
 }
 
 func preHandleSecrets(old, new *manifest.MappingResult) (v1.Secret, v1.Secret, error, error) {