github.com/google/go-cmp v0.7.0: Compare embedded structs containing unexported fields using cmpopts.IgnoreUnexported without runtime panics

# google/go-cmp: Embedded Struct Unexported Fields and Promoted Field Filtering

## Known Solutions Search
A search for `github.com/google/go-cmp` identified an existing sample (`sha256:55ce200247ad6334adf868c2f9ec32f994a94b2ff4d0fc6ac211f4b03de32d9c`) demonstrating basic `cmp.Diff` usage, unexported struct panics, and `cmpopts.IgnoreFields` on top-level structs. This sample addresses the separate trap of embedded (composed) struct unexported field handling and promoted field filtering.

## Failure Mode
The wrong invocation fails loudly: `cmp.Diff` and `cmp.Equal` panic at runtime with `cannot handle unexported field at {Outer}.Embedded.field: consider using cmpopts.EquateComparable or cmpopts.IgnoreUnexported` when only the outer struct is passed to `cmpopts.IgnoreUnexported`, and `cmpopts.IgnoreFields` panics at configuration time with `field: does not exist` when passed a promoted field name.

## Behaviour Details
1. `cmpopts.IgnoreUnexported(types...)` checks struct types during tree traversal by exact type match. Passing an outer struct does not cover embedded struct types; each embedded struct type with unexported fields must be explicitly passed to `cmpopts.IgnoreUnexported`.
2. `cmpopts.IgnoreFields(structType, fields...)` requires fields to be directly declared on the specified struct type. Promoted fields cannot be referenced by their unqualified name on the outer struct. Callers must either pass the field name on the embedded struct type (`cmpopts.IgnoreFields(Embedded{}, "field")`) or use dotted path navigation (`cmpopts.IgnoreFields(Outer{}, "Embedded.field")`).

package gocmp

import (
	"fmt"

	"github.com/google/go-cmp/cmp"
	"github.com/google/go-cmp/cmp/cmpopts"
)

// AuditHeader is an embedded struct containing an unexported token field.
type AuditHeader struct {
	Timestamp int64
	token     string
}

// NewAuditHeader creates an AuditHeader instance.
func NewAuditHeader(ts int64, token string) AuditHeader {
	return AuditHeader{Timestamp: ts, token: token}
}

// Envelope embeds AuditHeader and declares its own unexported signature field.
type Envelope struct {
	AuditHeader
	Payload   string
	signature []byte
}

// NewEnvelope creates an Envelope instance.
func NewEnvelope(ts int64, token, payload, signature string) Envelope {
	return Envelope{
		AuditHeader: AuditHeader{Timestamp: ts, token: token},
		Payload:     payload,
		signature:   []byte(signature),
	}
}

// DiffOuterOnly attempts to ignore only Envelope, which panics because AuditHeader's
// unexported token is not ignored during reflection traversal.
func DiffOuterOnly(a, b Envelope) (diff string, panicMsg string) {
	defer func() {
		if r := recover(); r != nil {
			panicMsg = fmt.Sprint(r)
		}
	}()
	diff = cmp.Diff(a, b, cmpopts.IgnoreUnexported(Envelope{}))
	return diff, panicMsg
}

// TryIgnorePromotedField attempts to ignore "token" on Envelope directly,
// which panics because "token" is not a declared field of Envelope.
func TryIgnorePromotedField() (opt cmp.Option, panicMsg string) {
	defer func() {
		if r := recover(); r != nil {
			panicMsg = fmt.Sprint(r)
		}
	}()
	opt = cmpopts.IgnoreFields(Envelope{}, "token")
	return opt, panicMsg
}

// DiffComplete correctly ignores unexported fields across both the outer
// struct Envelope and the embedded struct AuditHeader.
func DiffComplete(a, b Envelope) string {
	return cmp.Diff(a, b, cmpopts.IgnoreUnexported(Envelope{}, AuditHeader{}))
}

// EqualComplete checks equality while ignoring unexported fields across both types.
func EqualComplete(a, b Envelope) bool {
	return cmp.Equal(a, b, cmpopts.IgnoreUnexported(Envelope{}, AuditHeader{}))
}

package gocmp

import (
	"strings"
	"testing"
)

func TestEmbeddedStructUnexportedPanicsAndResolution(t *testing.T) {
	env1 := NewEnvelope(1700000000, "session-secret-a", "user-payload", "sig-1")
	env2 := NewEnvelope(1700000000, "session-secret-b", "user-payload", "sig-2")

	t.Run("IgnoreUnexportedOnOuterOnlyPanicsOnEmbeddedField", func(t *testing.T) {
		_, panicMsg := DiffOuterOnly(env1, env2)
		if panicMsg == "" {
			t.Fatal("expected Diff with only outer IgnoreUnexported to panic on embedded unexported field")
		}
		if !strings.Contains(panicMsg, "AuditHeader.token") {
			t.Fatalf("expected panic message to cite AuditHeader.token, got: %s", panicMsg)
		}
	})

	t.Run("IgnoreFieldsPanicsOnPromotedFieldName", func(t *testing.T) {
		_, panicMsg := TryIgnorePromotedField()
		if panicMsg == "" {
			t.Fatal("expected IgnoreFields with promoted field name to panic")
		}
		if !strings.Contains(panicMsg, "does not exist") {
			t.Fatalf("expected panic message indicating field does not exist, got: %s", panicMsg)
		}
	})

	t.Run("IgnoreUnexportedBothOuterAndEmbeddedSucceeds", func(t *testing.T) {
		if !EqualComplete(env1, env2) {
			t.Fatal("expected envelopes with matching public fields to be equal when both struct types are ignored")
		}
		diff := DiffComplete(env1, env2)
		if diff != "" {
			t.Fatalf("expected empty diff for equal public fields, got: %s", diff)
		}
	})

	t.Run("DetectsDifferencesInPublicFieldsOfEmbeddedAndOuterStructs", func(t *testing.T) {
		envDifferent := NewEnvelope(1700000099, "session-secret-c", "other-payload", "sig-3")
		if EqualComplete(env1, envDifferent) {
			t.Fatal("expected envelopes with different Timestamp and Payload to not be equal")
		}
		diff := DiffComplete(env1, envDifferent)
		if diff == "" {
			t.Fatal("expected non-empty diff for differing public fields")
		}
		if !strings.Contains(diff, "Timestamp") || !strings.Contains(diff, "Payload") {
			t.Fatalf("expected diff to report differences in Timestamp and Payload, got: %s", diff)
		}
	})
}

{"case":{"believed":"Passing an outer struct to cmpopts.IgnoreUnexported automatically ignores unexported fields within embedded structs.","caseId":"case:sha256:d330c7031671a65b997a09ad8aad338c0d385b1f62111522fdff389c0b7d65a1","contract":["assert cmpopts.IgnoreUnexported on an outer struct panics when comparing embedded structs with unexported fields","assert cmpopts.IgnoreFields panics when given a promoted field name from an embedded struct","assert cmpopts.IgnoreUnexported succeeds when every embedded struct type is explicitly passed alongside the outer struct","assert cmp.Diff detects differences in public fields of embedded structs when unexported fields are ignored"],"goal":"Compare embedded structs containing unexported fields using cmpopts.IgnoreUnexported without runtime panics","kind":"HOW","packages":["pkg:golang/github.com/google/go-cmp@0.7.0"],"schemaVersion":1,"symbols":["cmp.Diff","cmp.Equal","cmpopts.IgnoreUnexported","cmpopts.IgnoreFields"]},"contractCommand":["go","test","./..."],"environment":{"arch":"x64","ecosystem":"golang","executionContext":"go","language":"go","os":"linux","packageManager":"gomod","runtime":"go","schemaVersion":1},"license":"MIT-0","packages":["pkg:golang/github.com/google/go-cmp@0.7.0"],"schemaVersion":1,"symbols":["cmp.Diff","cmp.Equal","cmpopts.IgnoreUnexported","cmpopts.IgnoreFields"],"verifierAdapter":"golang@1"}

module example.com/gocmp

go 1.24

require github.com/google/go-cmp v0.7.0

github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=