Add kustomizeconfig-generator; regenerate kustomizeconfig.yaml from API markers

examples/components/kustomizeconfig/kustomizeconfig.yaml was previously
maintained by hand, per the (now removed) instruction in api-design.md. It
had drifted significantly out of date: cross-references for Domain, Service,
Group, Role, RoleAssignment, ApplicationCredential, User (including
PasswordRef), RouterInterface, ShareNetwork, VolumeType, ServerGroup, and
FloatingIP.FloatingSubnetRef were all missing, along with several
spec.import.filter variants of existing entries.

cmd/kustomizeconfig-generator instead derives the file automatically:
  - it scans api/v1alpha1 for '+orc:kustomize:ref=<Kind>' marker comments
    (added in the previous commit)
  - for every registered ORC Kind, it walks the real struct layout of that
    Kind's Spec via reflection to compute the JSON path of each marked
    field (handling embedded/inlined structs, list traversal, and
    RouterInterface's bespoke non-wrapped Spec)
  - it groups the results by referenced Kind and emits a kustomize
    Component nameReference configuration, with a generated-file header

Wired into 'make generate' as a new 'generate-kustomizeconfig' target,
covered by 'make verify-generated'.

Verified:
  - the regenerated file is a strict superset of the old one (zero entries
    lost, confirmed via a structural diff ignoring the old file's
    inconsistent use of '[]' in one path)
  - a real 'kustomize build' exercise (with namePrefix + this component)
    correctly rewrites one of the newly-discovered references
    (Server.bootVolume.volumeRef -> Volume), and does not rewrite a
    deliberately-wrong path, confirming the generated paths are load-bearing
    and correct rather than accidentally permissive
  - 'make manifests' output (config/crd/bases) is unaffected

Also updates website/docs/development/api-design.md: the file is now
generated, not manually maintained; documents the new marker convention.

Author: mandre

Makefile

@@ -58,7 +58,7 @@ modules:
 	go mod tidy
 
 .PHONY: generate
-generate: generate-resources generate-controller-gen generate-codegen generate-go generate-docs modules manifests
+generate: generate-resources generate-controller-gen generate-kustomizeconfig generate-codegen generate-go generate-docs modules manifests
 
 .PHONY: generate-resources
 generate-resources:
@@ -68,6 +68,10 @@ generate-resources:
 generate-controller-gen: controller-gen ## Generate code containing DeepCopy, DeepCopyInto, and DeepCopyObject method implementations.
 	$(CONTROLLER_GEN) object:headerFile="hack/boilerplate.go.txt" paths="./..."
 
+.PHONY: generate-kustomizeconfig
+generate-kustomizeconfig: generate-resources generate-controller-gen ## Generate examples/components/kustomizeconfig/kustomizeconfig.yaml from +orc:kustomize:ref markers on the API types.
+	go run ./cmd/kustomizeconfig-generator
+
 .PHONY: generate-codegen
 generate-codegen: generate-controller-gen ## codegen requires DeepCopy etc
 	./hack/update-codegen.sh

cmd/kustomizeconfig-generator/main.go

@@ -0,0 +1,326 @@
+/*
+Copyright The ORC Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+	http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+// Command kustomizeconfig-generator generates
+// examples/components/kustomizeconfig/kustomizeconfig.yaml from the ORC API
+// types.
+//
+// It discovers cross-references between ORC objects (and core Secrets) by
+// scanning api/v1alpha1 for fields annotated with an
+// "+orc:kustomize:ref=<Kind>" marker, then walks the actual (reflected)
+// struct layout of every registered ORC Kind's Spec to compute the JSON path
+// of each annotated field. The result is emitted as a kustomize Component
+// "nameReference" configuration, grouped by referenced Kind.
+//
+// The "kustomizeref" golangci-lint rule (tools/orc-api-linter) separately
+// verifies that every KubernetesNameRef field carries the marker in the
+// first place; a missing marker produces no diff here, so `make lint` is
+// what catches that case, not this generator.
+package main
+
+import (
+	"fmt"
+	"go/ast"
+	"go/parser"
+	"go/token"
+	"os"
+	"path/filepath"
+	"reflect"
+	"regexp"
+	"sort"
+	"strings"
+
+	"k8s.io/apimachinery/pkg/runtime"
+	"sigs.k8s.io/yaml"
+
+	orcv1alpha1 "github.com/k-orc/openstack-resource-controller/v2/api/v1alpha1"
+)
+
+const (
+	apiDir     = "api/v1alpha1"
+	outputFile = "examples/components/kustomizeconfig/kustomizeconfig.yaml"
+)
+
+var markerRE = regexp.MustCompile(`^\+orc:kustomize:ref=(\S+)$`)
+
+var orcPkgPath = reflect.TypeOf(orcv1alpha1.KubernetesNameRef("")).PkgPath()
+
+// fieldSpec mirrors kustomize's kustomizeconfig fieldSpec entry.
+type fieldSpec struct {
+	Path string `json:"path"`
+	Kind string `json:"kind"`
+}
+
+// nameReferenceEntry mirrors kustomize's kustomizeconfig nameReference entry.
+type nameReferenceEntry struct {
+	Kind       string      `json:"kind"`
+	FieldSpecs []fieldSpec `json:"fieldSpecs"`
+}
+
+type kustomizeConfig struct {
+	NameReference []nameReferenceEntry `json:"nameReference"`
+}
+
+// markerTable maps struct type name -> field name -> referenced Kind, as
+// declared by "+orc:kustomize:ref=<Kind>" marker comments in the API source.
+type markerTable map[string]map[string]string
+
+func main() {
+	if err := run(); err != nil {
+		fmt.Fprintln(os.Stderr, "kustomizeconfig-generator:", err)
+		os.Exit(1)
+	}
+}
+
+func run() error {
+	markers, err := loadMarkers(apiDir)
+	if err != nil {
+		return fmt.Errorf("loading markers from %s: %w", apiDir, err)
+	}
+
+	scheme := runtime.NewScheme()
+	if err := orcv1alpha1.AddToScheme(scheme); err != nil {
+		return fmt.Errorf("building scheme: %w", err)
+	}
+
+	type hit struct {
+		sourceKind string
+		path       string
+		targetKind string
+	}
+	var hits []hit
+
+	for gvk, t := range scheme.AllKnownTypes() {
+		if gvk.Group != orcv1alpha1.GroupName {
+			continue
+		}
+		if strings.HasSuffix(gvk.Kind, "List") {
+			continue
+		}
+
+		specField, ok := t.FieldByName("Spec")
+		if !ok {
+			continue
+		}
+
+		sourceKind := gvk.Kind
+		w := walker{markers: markers}
+		w.walk(derefStruct(specField.Type), "spec", 0, func(path, targetKind string) {
+			hits = append(hits, hit{sourceKind: sourceKind, path: path, targetKind: targetKind})
+		})
+	}
+
+	if len(hits) == 0 {
+		return fmt.Errorf("no +orc:kustomize:ref markers found; refusing to write an empty kustomizeconfig.yaml")
+	}
+
+	grouped := map[string][]fieldSpec{}
+	for _, h := range hits {
+		grouped[h.targetKind] = append(grouped[h.targetKind], fieldSpec{Path: h.path, Kind: h.sourceKind})
+	}
+
+	var targetKinds []string
+	for k := range grouped {
+		targetKinds = append(targetKinds, k)
+	}
+	sort.Strings(targetKinds)
+
+	cfg := kustomizeConfig{}
+	for _, k := range targetKinds {
+		specs := grouped[k]
+		sort.Slice(specs, func(i, j int) bool {
+			if specs[i].Kind != specs[j].Kind {
+				return specs[i].Kind < specs[j].Kind
+			}
+			return specs[i].Path < specs[j].Path
+		})
+		// Deduplicate identical (kind, path) pairs which can legitimately
+		// arise, e.g. the same field appearing in both a create and an
+		// update variant of a resource spec.
+		deduped := specs[:0]
+		for i, s := range specs {
+			if i > 0 && s == specs[i-1] {
+				continue
+			}
+			deduped = append(deduped, s)
+		}
+		cfg.NameReference = append(cfg.NameReference, nameReferenceEntry{Kind: k, FieldSpecs: deduped})
+	}
+
+	out, err := yaml.Marshal(cfg)
+	if err != nil {
+		return fmt.Errorf("marshalling: %w", err)
+	}
+
+	header := `# Code generated by kustomizeconfig-generator. DO NOT EDIT.
+#
+# This file teaches kustomize how to substitute name references between ORC
+# objects (and core Secrets) when transforming example manifests, e.g. via a
+# nameSuffix or nameReference transformer. It is derived from
+# "+orc:kustomize:ref=<Kind>" markers on the ORC API types.
+#
+# To add a new reference, annotate the field in api/v1alpha1 with
+# "+orc:kustomize:ref=<Kind>" and run ` + "`make generate`" + `.
+# See https://k-orc.cloud/development/api-design/.
+`
+
+	return os.WriteFile(outputFile, append([]byte(header), out...), 0o644)
+}
+
+// derefStruct dereferences pointer types until it reaches the underlying type.
+func derefStruct(t reflect.Type) reflect.Type {
+	for t.Kind() == reflect.Ptr {
+		t = t.Elem()
+	}
+	return t
+}
+
+type walker struct {
+	markers markerTable
+}
+
+// walk recursively descends into struct t, calling record(path, kind) for
+// every field annotated with an "+orc:kustomize:ref=<kind>" marker. path is
+// the JSON path accumulated so far, using "[]" to denote list elements,
+// matching kustomize's fieldSpec path syntax.
+func (w walker) walk(t reflect.Type, path string, depth int, record func(path, kind string)) {
+	if depth > 25 {
+		// Defensive guard; the API has no legitimate structures this deep.
+		return
+	}
+	if t.Kind() != reflect.Struct || t.PkgPath() != orcPkgPath {
+		return
+	}
+
+	structName := t.Name()
+	for i := 0; i < t.NumField(); i++ {
+		f := t.Field(i)
+		if f.PkgPath != "" {
+			// unexported field
+			continue
+		}
+
+		if f.Anonymous {
+			// Embedded/inlined field: recurse without adding a path segment.
+			w.walk(derefStruct(f.Type), path, depth+1, record)
+			continue
+		}
+
+		jsonTag := f.Tag.Get("json")
+		if jsonTag == "" || jsonTag == "-" {
+			continue
+		}
+		name := strings.Split(jsonTag, ",")[0]
+		if name == "" {
+			continue
+		}
+		fieldPath := path + "/" + name
+
+		ft := derefStruct(f.Type)
+		isSlice := ft.Kind() == reflect.Slice
+
+		if kind, ok := w.markers[structName][f.Name]; ok {
+			if isSlice {
+				fieldPath += "[]"
+			}
+			record(fieldPath, kind)
+			continue
+		}
+
+		if isSlice {
+			elem := derefStruct(ft.Elem())
+			if elem.Kind() == reflect.Struct && elem.PkgPath() == orcPkgPath {
+				w.walk(elem, fieldPath+"[]", depth+1, record)
+			}
+			continue
+		}
+
+		if ft.Kind() == reflect.Struct && ft.PkgPath() == orcPkgPath {
+			w.walk(ft, fieldPath, depth+1, record)
+		}
+	}
+}
+
+// loadMarkers scans all Go source files directly under dir for struct field
+// doc comments containing "+orc:kustomize:ref=<Kind>", returning a table
+// keyed by struct type name and Go field name.
+func loadMarkers(dir string) (markerTable, error) {
+	table := markerTable{}
+
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		return nil, err
+	}
+
+	fset := token.NewFileSet()
+	for _, entry := range entries {
+		if entry.IsDir() || !strings.HasSuffix(entry.Name(), ".go") {
+			continue
+		}
+
+		filename := filepath.Join(dir, entry.Name())
+		file, err := parser.ParseFile(fset, filename, nil, parser.ParseComments)
+		if err != nil {
+			return nil, fmt.Errorf("parsing %s: %w", filename, err)
+		}
+
+		for _, decl := range file.Decls {
+			genDecl, ok := decl.(*ast.GenDecl)
+			if !ok || genDecl.Tok != token.TYPE {
+				continue
+			}
+			for _, spec := range genDecl.Specs {
+				typeSpec, ok := spec.(*ast.TypeSpec)
+				if !ok {
+					continue
+				}
+				structType, ok := typeSpec.Type.(*ast.StructType)
+				if !ok {
+					continue
+				}
+				structName := typeSpec.Name.Name
+
+				for _, field := range structType.Fields.List {
+					if field.Doc == nil {
+						continue
+					}
+					kind := extractRefMarker(field.Doc)
+					if kind == "" {
+						continue
+					}
+					for _, fieldName := range field.Names {
+						if table[structName] == nil {
+							table[structName] = map[string]string{}
+						}
+						table[structName][fieldName.Name] = kind
+					}
+				}
+			}
+		}
+	}
+
+	return table, nil
+}
+
+func extractRefMarker(doc *ast.CommentGroup) string {
+	for _, c := range doc.List {
+		text := strings.TrimSpace(strings.TrimPrefix(c.Text, "//"))
+		if m := markerRE.FindStringSubmatch(text); m != nil {
+			return m[1]
+		}
+	}
+	return ""
+}