github.com/google/go-cmp v0.6.0: cmp.StructField

# google/go-cmp: Struct Field Inspection and Scoped Filtering with cmp.StructField

## Known Solutions Search
A search for `github.com/google/go-cmp/cmp.StructField` in `pkg:golang/github.com/google/go-cmp@v0.6.0` returned `NO_SAFE_MATCH`.

This sample investigates and verifies the contract of `cmp.StructField` for `pkg:golang/github.com/google/go-cmp@v0.6.0`, demonstrating:
1. Detecting and type-asserting `cmp.StructField` from `cmp.PathStep` during `cmp.FilterPath` traversal.
2. Inspecting field names via `sf.Name()` and selectively ignoring specific fields with `cmp.Ignore()`.
3. Verifying field indices via `sf.Index()` against parent struct field positions.
4. Accessing field reflection types via `sf.Type()`.
5. Verifying path string formatting via `sf.String()` matching `.FieldName`.
6. Reading field reflection value pairs via `sf.Values()`.

## Pinned Release
`github.com/google/go-cmp v0.6.0` declared in `go.mod` and verified in `go.sum`.

## Failure Mode
Structs with dynamic or generated fields (such as timestamps, generated tokens, or metadata) cause `cmp.Equal` and `cmp.Diff` to report differences. Without field-level path filtering using `cmp.StructField`, developers cannot selectively ignore or transform specific struct fields while keeping the rest of the struct comparison intact.

## Observed Behaviour
1. `cmp.StructField` implements `cmp.PathStep` and is added to `cmp.Path` whenever `go-cmp` traverses into a struct field.
2. `sf.Name()` returns the field's identifier as a string.
3. `sf.Index()` returns the zero-based index of the field in the parent struct definition.
4. `sf.Type()` returns the field's `reflect.Type`.
5. `sf.String()` returns the field path step formatted as `.<name>`.
6. `sf.Values()` returns `(reflect.Value, reflect.Value)` representing the compared field values.

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify github.com/google/go-cmp/cmp.StructField in pkg:golang/github.com/google/go-cmp@v0.6.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/github.com/google/go-cmp@v0.6.0
Demonstrate these symbols/APIs:
  - github.com/google/go-cmp/cmp.StructField

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:e55cb76cd514d067d20af132e6d0533e49ec100a66521766c0f11112f478fca5","contract":["cmp.StructField path step identifies struct field access during comparison traversal via p.Last().(cmp.StructField)","cmp.StructField Name reports the field identifier and enables field-specific filtering with cmp.FilterPath and cmp.Ignore","cmp.StructField Index returns the zero-based index of the field matching reflect.Type.Field order in the parent struct","cmp.StructField Type returns the reflect.Type of the accessed struct field","cmp.StructField String formats the field path step with a leading period matching .FieldName","cmp.StructField Values exposes reflect.Value pairs of the compared struct field members"],"goal":"verify github.com/google/go-cmp/cmp.StructField in pkg:golang/github.com/google/go-cmp@v0.6.0","kind":"HOW","packages":["pkg:golang/github.com/google/go-cmp@v0.6.0"],"schemaVersion":1,"symbols":["github.com/google/go-cmp/cmp.StructField"]},"contractCommand":["go","run","./test"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"golang","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"go","schemaVersion":1},"license":"MIT-0","packages":["pkg:golang/github.com/google/go-cmp@v0.6.0"],"schemaVersion":1,"subject":"pkg:golang/github.com/google/go-cmp@v0.6.0","symbols":["github.com/google/go-cmp/cmp.StructField"],"verifierAdapter":"golang@1"}

module example.com/structfieldcmp

go 1.22

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

github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=
github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=

{
  "schemaVersion": 1,
  "goal": "verify github.com/google/go-cmp/cmp.StructField in pkg:golang/github.com/google/go-cmp@v0.6.0",
  "kind": "HOW",
  "packages": [
    "pkg:golang/github.com/google/go-cmp@v0.6.0"
  ],
  "symbols": [
    "github.com/google/go-cmp/cmp.StructField"
  ]
}

package structfieldcmp

import (
	"reflect"

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

// AuditRecord represents a structured domain object with multiple typed fields.
type AuditRecord struct {
	ID        string
	Timestamp int64
	Action    string
	Metadata  string
}

// FieldInspection captures reflection and path metadata from a cmp.StructField step.
type FieldInspection struct {
	Name   string
	Index  int
	Type   reflect.Type
	String string
	VX     any
	VY     any
}

// IgnoreFieldByName returns a cmp.Option that uses cmp.FilterPath and cmp.StructField
// to ignore any struct field matching the specified name.
func IgnoreFieldByName(fieldName string) cmp.Option {
	return cmp.FilterPath(func(p cmp.Path) bool {
		sf, ok := p.Last().(cmp.StructField)
		if !ok {
			return false
		}
		return sf.Name() == fieldName
	}, cmp.Ignore())
}

// IgnoreFieldByIndex returns a cmp.Option that uses cmp.FilterPath and cmp.StructField
// to ignore a struct field at the specified struct index within a target struct type.
func IgnoreFieldByIndex(parentType reflect.Type, targetIndex int) cmp.Option {
	return cmp.FilterPath(func(p cmp.Path) bool {
		sf, ok := p.Last().(cmp.StructField)
		if !ok {
			return false
		}
		if len(p) < 2 {
			return false
		}
		parent := p.Index(-2)
		return parent.Type() == parentType && sf.Index() == targetIndex
	}, cmp.Ignore())
}

// InspectStructFields compares two values and collects all cmp.StructField steps encountered.
func InspectStructFields(x, y any) []FieldInspection {
	var inspections []FieldInspection
	_ = cmp.Equal(x, y, cmp.FilterPath(func(p cmp.Path) bool {
		if sf, ok := p.Last().(cmp.StructField); ok {
			vx, vy := sf.Values()
			var valX, valY any
			if vx.IsValid() && vx.CanInterface() {
				valX = vx.Interface()
			}
			if vy.IsValid() && vy.CanInterface() {
				valY = vy.Interface()
			}
			inspections = append(inspections, FieldInspection{
				Name:   sf.Name(),
				Index:  sf.Index(),
				Type:   sf.Type(),
				String: sf.String(),
				VX:     valX,
				VY:     valY,
			})
		}
		return false
	}, cmp.Ignore()))
	return inspections
}

package main

import (
	"fmt"
	"os"
	"reflect"

	sample "example.com/structfieldcmp"
	"github.com/google/go-cmp/cmp"
)

func main() {
	recA := sample.AuditRecord{
		ID:        "rec-001",
		Timestamp: 1700000000,
		Action:    "CREATE",
		Metadata:  "v1.0",
	}
	recB := sample.AuditRecord{
		ID:        "rec-001",
		Timestamp: 1700000999, // differs
		Action:    "CREATE",
		Metadata:  "v1.0",
	}

	// Assertion 1: cmp.StructField path step identifies struct field access during comparison traversal via p.Last().(cmp.StructField)
	{
		var encounteredStructFields []string
		var nonStructFieldSteps int
		_ = cmp.Equal(recA, recB, cmp.FilterPath(func(p cmp.Path) bool {
			if sf, ok := p.Last().(cmp.StructField); ok {
				encounteredStructFields = append(encounteredStructFields, sf.Name())
			} else {
				nonStructFieldSteps++
			}
			return false
		}, cmp.Ignore()))

		if len(encounteredStructFields) == 0 {
			fmt.Fprintf(os.Stderr, "FAIL: expected to encounter cmp.StructField steps during struct comparison traversal\n")
			os.Exit(1)
		}
		if nonStructFieldSteps == 0 {
			fmt.Fprintf(os.Stderr, "FAIL: expected root step to not be a cmp.StructField\n")
			os.Exit(1)
		}
	}

	// Assertion 2: cmp.StructField Name reports the field identifier and enables field-specific filtering with cmp.FilterPath and cmp.Ignore
	{
		// Without option, recA and recB differ on Timestamp
		if cmp.Equal(recA, recB) {
			fmt.Fprintf(os.Stderr, "FAIL: expected recA and recB to differ without ignore option\n")
			os.Exit(1)
		}

		// Ignoring Timestamp by name using cmp.StructField.Name()
		optIgnoreTimestamp := sample.IgnoreFieldByName("Timestamp")
		if !cmp.Equal(recA, recB, optIgnoreTimestamp) {
			diff := cmp.Diff(recA, recB, optIgnoreTimestamp)
			fmt.Fprintf(os.Stderr, "FAIL: expected recA and recB to be equal when Timestamp is ignored, got diff: %s\n", diff)
			os.Exit(1)
		}

		// When another field differs, ignore option on Timestamp should NOT ignore that other field
		recC := sample.AuditRecord{
			ID:        "rec-999", // differs
			Timestamp: 1700000999,
			Action:    "CREATE",
			Metadata:  "v1.0",
		}
		if cmp.Equal(recA, recC, optIgnoreTimestamp) {
			fmt.Fprintf(os.Stderr, "FAIL: expected recA and recC to not be equal when ID differs\n")
			os.Exit(1)
		}
	}

	// Assertion 3: cmp.StructField Index returns the zero-based index of the field matching reflect.Type.Field order in the parent struct
	{
		inspections := sample.InspectStructFields(recA, recB)
		auditType := reflect.TypeOf(sample.AuditRecord{})
		for _, ins := range inspections {
			structField := auditType.Field(ins.Index)
			if structField.Name != ins.Name {
				fmt.Fprintf(os.Stderr, "FAIL: expected index %d to correspond to field %s, got %s\n", ins.Index, structField.Name, ins.Name)
				os.Exit(1)
			}
		}

		// Also verify filtering by index 1 (Timestamp)
		optIgnoreIndex1 := sample.IgnoreFieldByIndex(auditType, 1)
		if !cmp.Equal(recA, recB, optIgnoreIndex1) {
			fmt.Fprintf(os.Stderr, "FAIL: expected recA and recB to be equal when field at index 1 is ignored\n")
			os.Exit(1)
		}
	}

	// Assertion 4: cmp.StructField Type returns the reflect.Type of the accessed struct field
	{
		inspections := sample.InspectStructFields(recA, recB)
		typeMap := make(map[string]reflect.Type)
		for _, ins := range inspections {
			typeMap[ins.Name] = ins.Type
		}

		if typeMap["ID"] != reflect.TypeOf("") {
			fmt.Fprintf(os.Stderr, "FAIL: expected field ID Type to be string, got: %v\n", typeMap["ID"])
			os.Exit(1)
		}
		if typeMap["Timestamp"] != reflect.TypeOf(int64(0)) {
			fmt.Fprintf(os.Stderr, "FAIL: expected field Timestamp Type to be int64, got: %v\n", typeMap["Timestamp"])
			os.Exit(1)
		}
	}

	// Assertion 5: cmp.StructField String formats the field path step with a leading period matching .FieldName
	{
		inspections := sample.InspectStructFields(recA, recB)
		for _, ins := range inspections {
			expectedString := "." + ins.Name
			if ins.String != expectedString {
				fmt.Fprintf(os.Stderr, "FAIL: expected StructField String to be %q, got %q\n", expectedString, ins.String)
				os.Exit(1)
			}
		}

		// Verify that path evaluation using String() on the StructField step matches .Timestamp
		var timestampStepString string
		_ = cmp.Equal(recA, recB, cmp.FilterPath(func(p cmp.Path) bool {
			if sf, ok := p.Last().(cmp.StructField); ok && sf.Name() == "Timestamp" {
				timestampStepString = sf.String()
			}
			return false
		}, cmp.Ignore()))

		if timestampStepString != ".Timestamp" {
			fmt.Fprintf(os.Stderr, "FAIL: expected Timestamp StructField String to be .Timestamp, got: %q\n", timestampStepString)
			os.Exit(1)
		}
	}

	// Assertion 6: cmp.StructField Values exposes reflect.Value pairs of the compared struct field members
	{
		inspections := sample.InspectStructFields(recA, recB)
		foundTimestamp := false
		for _, ins := range inspections {
			if ins.Name == "Timestamp" {
				foundTimestamp = true
				vx, okX := ins.VX.(int64)
				vy, okY := ins.VY.(int64)
				if !okX || !okY || vx != 1700000000 || vy != 1700000999 {
					fmt.Fprintf(os.Stderr, "FAIL: unexpected Values for Timestamp: vx=%v, vy=%v\n", ins.VX, ins.VY)
					os.Exit(1)
				}
			}
		}
		if !foundTimestamp {
			fmt.Fprintf(os.Stderr, "FAIL: expected to find Timestamp field inspection\n")
			os.Exit(1)
		}
	}

	fmt.Println("PASS: all cmp.StructField contract assertions verified")
}