crossplane-diff: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Development Commands

Building and Testing

# Build the binary for your platform
earthly +build

# Run unit and integration tests (fast, ~7s)
# Direct go test - fastest, immediate output
cd cmd/diff
go test ./...

# Via Earthly (ensures consistent environment, caches dependencies)
earthly +go-test

# Run a specific test
go test ./cmd/diff/diffprocessor -run TestCachedFunctionProvider -v

# Run a single test file
go test ./cmd/diff/diffprocessor/diff_processor_test.go -v

# Check test coverage
go test -cover ./cmd/diff/diffprocessor/... -coverprofile=/tmp/coverage.out
go tool cover -func=/tmp/coverage.out

# Pre-PR checks: linting, tests, generation (requires long timeout, can take several minutes)
earthly -P +reviewable

# Fetch Crossplane's CRDs at the crossplane version go.mod pins into cluster/gomod/crds. Required for unit and
# integration tests (run it in a fresh worktree, and again after a crossplane dependency bump). +go-test runs it.
earthly +fetch-crossplane-crds-gomod

# Fetch Crossplane's cluster directory for an image tag into cluster/<tag>. Only e2e uses it, because it must
# match the Crossplane image e2e runs.
earthly +fetch-crossplane-cluster --CROSSPLANE_IMAGE_TAG=main

# Tidy go modules
earthly +generate

Earthly Output Notes:

• By default, Earthly buffers stdout and stderr separately, which can cause interleaved output
• Use 2>&1 to merge streams for chronological output: earthly +go-test 2>&1 | tee output.log

End-to-End Tests

E2E tests run against real kind clusters with Crossplane installed. They can take several minutes to complete.

# Full E2E matrix against multiple Crossplane versions (slow, runs serially)
earthly -P +e2e-matrix

# Single E2E test against specific Crossplane version
earthly +e2e --CROSSPLANE_IMAGE_TAG=main

# Overriding FLAGS replaces the default `-labels=crossplane-version=<tag>` filter, so pass it yourself when
# targeting release-1.20; otherwise main-only (v2) tests run against Crossplane v1 and fail
earthly -P +e2e --CROSSPLANE_IMAGE_TAG=release-1.20 --FLAGS="-labels=crossplane-version=release-1.20 -test.run ^TestDiffExistingClaim$"

# Run specific E2E test with verbose logging
earthly -P +e2e --FLAGS="-v=4 -test.run ^TestCompositionDiff"

# Debug E2E: stop on first failure and preserve kind cluster
earthly -i -P +e2e --FLAGS="-test.failfast -fail-fast -destroy-kind-cluster=false"

# Run E2E tests directly (without Earthly wrapper for easier debugging)
go test -c -o e2e ./test/e2e
./e2e -v=4 -test.v -test.failfast -destroy-kind-cluster=false -test.run ^TestSpecificTest