Add CRD-runtime drift detection test framework

[ChrisJBurns]

Summary

• Silent drift between CRD types and their runtime config counterparts has caused user-facing bugs (e.g. Composite Tools: Fix plumbing for on-error-continue config #3118, Simplify VMCP Configuration #3125) where new fields appeared to work in unit tests but were not wired through the CRD conversion path. The only existing safety nets — code review and end-to-end tests — do not scale.
• Adds a reusable reflection-based field walker and a bidirectional drift detection pattern. The pattern requires every leaf JSON field on either side of a CRD↔runtime boundary to be either explicitly mapped to the other side, or explicitly declared as intentionally unmapped with a justification string. Drift is allowed; unannounced drift is not.
• Applies the pattern to MCPTelemetryConfig ↔ telemetry.Config as the first real-world exercise. The drift test passes against the current codebase.

Type of change

• New feature

Test plan

• Unit tests (task test)
• E2E tests (task test-e2e)
• Linting (task lint-fix)
• Manual testing (describe below)

Tests added (all passing): walker unit tests in cmd/thv-operator/internal/testutil/reflect_test.go; drift tests in cmd/thv-operator/pkg/spectoconfig/telemetry_drift_test.go (TestTelemetryConfigDrift_CRDFieldsCovered, TestTelemetryConfigDrift_RuntimeFieldsCovered, TestTelemetryConfigDrift_MappingTableSanity).

task lint-fix could not be run locally — the installed golangci-lint v2.12.1 is built with go1.25 but the project targets go1.26. go vet and gofmt are clean on the new files. CI will run the project's pinned linter.

API Compatibility

• This PR does not break the v1beta1 API, OR the api-break-allowed label is applied and the migration guidance is described above.

Test-only change. No production code, CRD schemas, or APIs are modified.

Changes

File	Change
cmd/thv-operator/internal/testutil/reflect.go	New FlattenJSONLeafFields helper that returns sorted dot-delimited JSON leaf paths for a struct type. Recurses into nested structs, deref'd pointers, and slice/map element types. Stops at primitives and a small allowlist (time.Duration, metav1.Duration, json.RawMessage, thvjson.Map/Any, vmcpconfig.Duration). Skips metav1.TypeMeta/ObjectMeta/ListMeta and unexported / json:\"-\" fields. Honors ,inline and Go's anonymous-field promotion. Cycle-protected.
cmd/thv-operator/internal/testutil/reflect_test.go	Table-driven walker tests: pointers, slice/array/map elements, embedded structs (with and without ,inline), json:\"-\", missing tags, omitempty, unexported fields, leaf allowlist, sorted output, nil/non-struct input.
cmd/thv-operator/pkg/spectoconfig/telemetry_drift_test.go	Bidirectional drift test for MCPTelemetryConfigSpec ↔ telemetry.Config. Two coverage tests (one per direction) sharing a single telemetryFieldMappings source-of-truth table, plus per-side IgnoredOnCRDOnly / IgnoredOnRuntimeOnly maps with justification strings. A third test asserts mapping-table sanity (no duplicates, no overlap with ignore lists, non-empty justifications).

Does this introduce a user-facing change?

No.

Special notes for reviewers

The pattern is bidirectional by design — it does not mandate parity between CRD and runtime types. Either side may have fields the other lacks; the test simply forces every divergence to be explicitly classified. New entries in IgnoredOnCRDOnly / IgnoredOnRuntimeOnly require a justification string, which makes intentional decoupling visible in code review.

The walker uncovered one CRD leaf that prior manual analysis missed: openTelemetry.caBundleRef.configMapRef.optional, a *bool promoted from corev1.ConfigMapKeySelector via LocalObjectReference. It is now explicitly declared in telemetryIgnoredOnCRDOnly with a justification — exactly the pattern working as intended.

This is the first PR in a series. Follow-ups will (1) introduce a CRD-owned v1beta1.VirtualMCPConfig mirror to decouple VirtualMCPServerSpec.Config from pkg/vmcp/config.Config without changing the user-facing CRD schema, and (2) extend the drift pattern to other converter boundaries (OIDC, external auth strategies, embedded auth server config).

Implementation plan

Approved drift detection plan

PR 1 (this PR): build the reusable reflection walker + bidirectional drift test machinery, exercise it against an already-decoupled boundary (telemetry) to validate the pattern.

PR 2 (next): mirror vmcpconfig.Config top-level fields into v1beta1.VirtualMCPConfig, with nested fields still pointing at runtime types. CRD JSON schema unchanged. Replace vmcp.Spec.Config.DeepCopy() in the converter with explicit field-by-field copy at the top level.

PR 3+: add bidirectional drift tests for VirtualMCPConfig and incrementally mirror nested types (AggregationConfig, OperationalConfig, …), one per PR, with the drift test guiding each mirror.

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 88.05970% with 24 lines in your changes missing coverage. Please review.
✅ Project coverage is 67.92%. Comparing base (e943660) to head (7218959).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
cmd/thv-operator/internal/testutil/drift.go	82.60%	15 Missing and 5 partials ⚠️
cmd/thv-operator/internal/testutil/reflect.go	95.34%	2 Missing and 2 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #5209      +/-   ##
==========================================
+ Coverage   67.87%   67.92%   +0.05%     
==========================================
  Files         610      612       +2     
  Lines       62405    62682     +277     
==========================================
+ Hits        42356    42576     +220     
- Misses      16869    16917      +48     
- Partials     3180     3189       +9     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[jhrozek]

Framework is well-conceived, walker semantics are sound, and the drift pattern is a good safety net for future CRD↔runtime work. Two non-blocking notes inline — approving.

[jerm-dro]

I like this direction. A few suggestions to make this more general purpose and require less boilerplate.

[jerm-dro]

suggestion: can telemetryIgnoredOnRuntimeOnly and telemetryIgnoredOnCRDOnly be specified as annotations/tags on the actual struct itself? That keeps the type's documentation in one spot. Annotations are accessible via the reflect package.

[ChrisJBurns]

Went back and forth with CC and it suggests keeping the maps. An ignore entry is really a cross-type fact ("no peer on the other side"), not an intrinsic property of one field. Putting it on the type also pushes edits into stable v1beta1 API code or into pkg/telemetry, which is shared with the standalone thv vmcp serve CLI and shouldn't carry operator-test metadata. Justification strings with parens, commas, and concatenation flatten awkwardly into tag values too. Since the Mappings table has to stay relational regardless, the savings would only be ~30 lines of strings. Happy to revisit if I'm missing something.

[jerm-dro]

Approving since this is a net-positive but I have one suggestion on how to make this more useful beyond testing.

[jerm-dro]

suggestion: I don't think this should be entirely a testutil.

Ideally, the mapping defined in telemetry_drift_test.go is what is used in the production code conversion. Then, in a test, we assert on the mappings and types that there has been no drift. In other words, the only test part of this code should be:

func TestTelemetryConfigDrift(t *testing.T) {
	t.Parallel()
	testutil.AssertNoDrift[telemetry.Config, v1beta1.MCPTelemetryConfigSpec](t, testutil.DriftSpec{
		Domain:               "telemetry",
        // The following values are defined in the production code,
        // since they are used to drive the conversion.
		Mappings:             telemetryFieldMappings,
		IgnoredOnCRDOnly:     telemetryIgnoredOnCRDOnly,
		IgnoredOnRuntimeOnly: telemetryIgnoredOnRuntimeOnly,
	})
}

WDYT?