Flag *Ref/*Refs fields that don't use KubernetesNameRef type

Fields ending in Ref or Refs should use KubernetesNameRef type to reference
ORC objects. This catches cases where the naming convention is correct but
the type is wrong (e.g., SecurityGroupRefs []OpenStackName should be
[]KubernetesNameRef).

CloudCredentialsRef is excluded as it intentionally uses a different type.

Author: mandre

tools/orc-api-linter/pkg/analysis/noopenstackidref/analyzer.go

@@ -40,6 +40,9 @@ ORC Kubernetes objects, not OpenStack resources directly by UUID.
 Fields ending with 'ID' or 'IDs' (like ProjectID, NetworkIDs) in spec structs should
 instead use KubernetesNameRef type with a 'Ref' or 'Refs' suffix (like ProjectRef, NetworkRefs).
 
+Additionally, fields ending with 'Ref' or 'Refs' must use the KubernetesNameRef type,
+not other types like OpenStackName or string.
+
 See: https://k-orc.cloud/development/api-design/`
 )
 
@@ -48,12 +51,22 @@ See: https://k-orc.cloud/development/api-design/`
 // KubernetesNameRef with a "Ref" or "Refs" suffix to reference ORC objects.
 var openstackIDPattern = regexp.MustCompile(`IDs?$`)
 
+// refPattern matches field names that end with "Ref" or "Refs".
+// These fields should use KubernetesNameRef type.
+var refPattern = regexp.MustCompile(`Refs?$`)
+
 // excludedIDPatterns contains field name patterns that end in "ID" or "IDs" but are
 // not OpenStack resource references.
 var excludedIDPatterns = []string{
 	"SegmentationID", // VLAN segmentation ID, not an OpenStack resource
 }
 
+// excludedRefPatterns contains field name patterns that end in "Ref" or "Refs" but
+// intentionally use a different type than KubernetesNameRef.
+var excludedRefPatterns = []string{
+	"CloudCredentialsRef", // References a credentials secret, not an ORC object
+}
+
 // excludedStructs contains struct names that should not be checked even though
 // they don't have "Status" in their name. These are typically nested types used
 // exclusively within status structs.
@@ -105,6 +118,22 @@ func checkField(pass *analysis.Pass, field *ast.Field, qualifiedFieldName string
 		return
 	}
 
+	// Check if field name ends in Ref/Refs but uses wrong type
+	if refPattern.MatchString(fieldName) {
+		// Check if field name is in the Ref exclusion list
+		if slices.Contains(excludedRefPatterns, fieldName) {
+			return
+		}
+
+		if !isKubernetesNameRefTypeOrSlice(field.Type) {
+			pass.Reportf(field.Pos(),
+				"field %s has Ref suffix but does not use KubernetesNameRef type; "+
+					"see https://k-orc.cloud/development/api-design/",
+				qualifiedFieldName)
+		}
+		return
+	}
+
 	// Check if field name matches OpenStack ID pattern
 	if !openstackIDPattern.MatchString(fieldName) {
 		return
@@ -172,3 +201,16 @@ func isKubernetesNameRefType(expr ast.Expr) bool {
 
 	return false
 }
+
+// isKubernetesNameRefTypeOrSlice checks if the expression is KubernetesNameRef,
+// *KubernetesNameRef, or []KubernetesNameRef. This is used for Ref/Refs fields
+// which may be singular or plural.
+func isKubernetesNameRefTypeOrSlice(expr ast.Expr) bool {
+	// Check for []KubernetesNameRef
+	if arrayType, ok := expr.(*ast.ArrayType); ok {
+		return isKubernetesNameRefType(arrayType.Elt)
+	}
+
+	// Check for KubernetesNameRef or *KubernetesNameRef
+	return isKubernetesNameRefType(expr)
+}

tools/orc-api-linter/pkg/analysis/noopenstackidref/testdata/src/a/a.go

@@ -147,3 +147,41 @@ type PluralIDsStatus struct {
 	// NetworkIDs is allowed in status.
 	NetworkIDs []string `json:"networkIDs,omitempty"`
 }
+
+// ---- Ref/Refs fields with wrong type: should be flagged ----
+
+// OpenStackName simulates the ORC OpenStackName type (wrong type for Refs).
+type OpenStackName string
+
+// WrongTypeRefSpec tests that Ref fields with wrong type are flagged.
+type WrongTypeRefSpec struct {
+	// ProjectRef with *string type is wrong - should use *KubernetesNameRef.
+	ProjectRef *string `json:"projectRef,omitempty"` // want `field WrongTypeRefSpec.ProjectRef has Ref suffix but does not use KubernetesNameRef type`
+
+	// NetworkRef with OpenStackName type is wrong - should use KubernetesNameRef.
+	NetworkRef OpenStackName `json:"networkRef,omitempty"` // want `field WrongTypeRefSpec.NetworkRef has Ref suffix but does not use KubernetesNameRef type`
+
+	// SubnetRef is correct - uses KubernetesNameRef.
+	SubnetRef KubernetesNameRef `json:"subnetRef,omitempty"`
+
+	// RouterRef is correct - uses *KubernetesNameRef.
+	RouterRef *KubernetesNameRef `json:"routerRef,omitempty"`
+}
+
+// WrongTypeRefsSpec tests that plural Refs fields with wrong type are flagged.
+type WrongTypeRefsSpec struct {
+	// SecurityGroupRefs with []OpenStackName type is wrong - should use []KubernetesNameRef.
+	SecurityGroupRefs []OpenStackName `json:"securityGroupRefs,omitempty"` // want `field WrongTypeRefsSpec.SecurityGroupRefs has Ref suffix but does not use KubernetesNameRef type`
+
+	// NetworkRefs with []string type is wrong - should use []KubernetesNameRef.
+	NetworkRefs []string `json:"networkRefs,omitempty"` // want `field WrongTypeRefsSpec.NetworkRefs has Ref suffix but does not use KubernetesNameRef type`
+
+	// SubnetRefs is correct - uses []KubernetesNameRef.
+	SubnetRefs []KubernetesNameRef `json:"subnetRefs,omitempty"`
+}
+
+// WrongTypeRefsStatus tests that Refs in status with wrong type are allowed.
+type WrongTypeRefsStatus struct {
+	// SecurityGroupRefs is allowed in status even with wrong type.
+	SecurityGroupRefs []OpenStackName `json:"securityGroupRefs,omitempty"`
+}