Add CI test enforcing migrate-label coverage on v1beta1 root types

Guards against the main footgun of the opt-in-label design for
storage-version migration: if a new CRD root type is added to
cmd/thv-operator/api/v1beta1/ without the migrate-marker, the
StorageVersionMigrator controller silently excludes it. The problem
surfaces only when a future release tries to drop a deprecated version
— at which point it is far too late to fix.

The test scans every root type (marker block contains both
+kubebuilder:object:root=true and +kubebuilder:storageversion) and
fails unless the block also contains either the migrate marker or an
explicit +thv:storage-version-migrator:exclude sibling marker.

Part of #4969.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: ChrisJBurns

cmd/thv-operator/controllers/marker_coverage_test.go

@@ -0,0 +1,151 @@
+// SPDX-FileCopyrightText: Copyright 2025 Stacklok, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+package controllers
+
+import (
+	"bufio"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// TestV1beta1TypesMarkerCoverage guards against a subtle failure mode in the
+// opt-in-label design for storage-version migration: if a new CRD root type is
+// added to cmd/thv-operator/api/v1beta1/ without the
+//
+//	+kubebuilder:metadata:labels=toolhive.stacklok.dev/auto-migrate-storage-version=true
+//
+// marker, the StorageVersionMigrator controller silently excludes it from
+// reconciliation. The problem surfaces only when a future release tries to
+// drop a deprecated version — at which point it is far too late.
+//
+// The test scans every root type (marker block contains
+// +kubebuilder:object:root=true AND +kubebuilder:storageversion) and fails if
+// any lacks either the migrate marker or an explicit
+// +thv:storage-version-migrator:exclude sibling marker. List types
+// (+kubebuilder:object:root=true WITHOUT +kubebuilder:storageversion) are
+// intentionally skipped — CRD-level labels are keyed on the root type, not
+// the list type.
+func TestV1beta1TypesMarkerCoverage(t *testing.T) {
+	t.Parallel()
+
+	typesDir := filepath.Join("..", "api", "v1beta1")
+	entries, err := os.ReadDir(typesDir)
+	require.NoError(t, err, "reading %s", typesDir)
+
+	const (
+		rootMarker         = "+kubebuilder:object:root=true"
+		storageMarker      = "+kubebuilder:storageversion"
+		migrateMarker      = "+kubebuilder:metadata:labels=toolhive.stacklok.dev/auto-migrate-storage-version=true"
+		excludeMarker      = "+thv:storage-version-migrator:exclude"
+		groupversionInfoGo = "groupversion_info.go"
+		zzGeneratedPrefix  = "zz_generated"
+		suffixTypesGo      = "_types.go"
+	)
+
+	type rootType struct {
+		file        string
+		typeName    string
+		markerBlock []string
+	}
+
+	var roots []rootType
+
+	for _, e := range entries {
+		if e.IsDir() {
+			continue
+		}
+		name := e.Name()
+		if !strings.HasSuffix(name, suffixTypesGo) {
+			continue
+		}
+		if name == groupversionInfoGo || strings.HasPrefix(name, zzGeneratedPrefix) {
+			continue
+		}
+
+		path := filepath.Join(typesDir, name)
+		f, err := os.Open(path)
+		require.NoError(t, err, "open %s", path)
+
+		scanner := bufio.NewScanner(f)
+		// Raise the max token size — some of the *_types.go files have very
+		// long comment lines (printcolumn JSONPath expressions).
+		scanner.Buffer(make([]byte, 64*1024), 1024*1024)
+
+		var block []string
+		for scanner.Scan() {
+			line := strings.TrimSpace(scanner.Text())
+
+			switch {
+			case strings.HasPrefix(line, "//"):
+				// Accumulate every comment/marker line. kubebuilder convention
+				// often separates markers from the godoc comment with a blank
+				// line, so we keep the block alive across blanks and only
+				// reset on a non-comment, non-blank, non-type line.
+				block = append(block, strings.TrimSpace(strings.TrimPrefix(line, "//")))
+			case strings.HasPrefix(line, "type "):
+				// Only root-level types matter (must contain object:root=true
+				// AND storageversion markers). List types have only object:root=true.
+				if containsMarker(block, rootMarker) && containsMarker(block, storageMarker) {
+					typeName := extractTypeName(line)
+					if typeName != "" {
+						copied := append([]string(nil), block...)
+						roots = append(roots, rootType{file: name, typeName: typeName, markerBlock: copied})
+					}
+				}
+				block = nil
+			case line == "":
+				// Blank line — keep block alive (comment-then-blank-then-type
+				// is idiomatic Go + kubebuilder).
+			default:
+				// Anything else (e.g. struct body, package clause, import) —
+				// drop any in-flight comment block.
+				block = nil
+			}
+		}
+		require.NoError(t, scanner.Err(), "scan %s", path)
+		require.NoError(t, f.Close())
+	}
+
+	require.NotEmpty(t, roots,
+		"no v1beta1 root types found — scanner likely broken; this test is meaningless without coverage")
+
+	for _, r := range roots {
+		hasMigrate := containsMarker(r.markerBlock, migrateMarker)
+		hasExclude := containsMarker(r.markerBlock, excludeMarker)
+		assert.Truef(t, hasMigrate || hasExclude,
+			"v1beta1 root type %s.%s is missing either\n"+
+				"  %s\n"+
+				"(opt in to storage-version migration) or\n"+
+				"  %s\n"+
+				"(explicit opt-out). Every root type must declare one. See\n"+
+				"cmd/thv-operator/controllers/storageversionmigrator_controller.go for context.",
+			r.file, r.typeName, migrateMarker, excludeMarker)
+	}
+}
+
+// containsMarker returns true if any line in block contains the given
+// marker substring.
+func containsMarker(block []string, marker string) bool {
+	for _, l := range block {
+		if strings.Contains(l, marker) {
+			return true
+		}
+	}
+	return false
+}
+
+// extractTypeName returns the identifier in a line of the form `type Foo struct {`.
+// Returns empty string if the line is not a type declaration we care about.
+func extractTypeName(line string) string {
+	fields := strings.Fields(line)
+	if len(fields) < 2 || fields[0] != "type" {
+		return ""
+	}
+	return fields[1]
+}