refactor(markerscope): convert config to PascalCase values and named object lists

Signed-off-by: nayuta-ai <nayuta723@gmail.com>

Author: nayuta723

docs/linters.md

@@ -442,25 +442,25 @@ lintersConfig:
     allowDangerousTypes: false # Allow dangerous number types (float32, float64). Defaults to `false`.
     markerRules:
       # Override default rule for a built-in marker
-      "optional":
-        scope: field  # or: type, any
+      - name: "optional"
+        scope: Field  # or: Type, Any
 
       # Add a custom marker with scope constraint only
-      "mycompany:validation:CustomMarker":
-        scope: any
+      - name: "mycompany:validation:CustomMarker"
+        scope: Any
 
       # Add a custom marker with scope and type constraints
-      "mycompany:validation:NumericLimit":
-        scope: any
+      - name: "mycompany:validation:NumericLimit"
+        scope: Any
         strictTypeConstraint: true # Require declaration on type definition for named types
         typeConstraint:
           allowedSchemaTypes:
             - integer
             - number
 
       # Add a custom array items marker with element type constraint
-      "mycompany:validation:items:StringFormat":
-        scope: any
+      - name: "mycompany:validation:items:StringFormat"
+        scope: Any
         typeConstraint:
           allowedSchemaTypes:
             - array
@@ -470,9 +470,9 @@ lintersConfig:
 ```
 
 **Scope values:**
-- `field`: FieldScope - marker can only be on fields
-- `type`: TypeScope - marker can only be on types
-- `any`: AnyScope - marker can be on fields or types
+- `Field`: FieldScope - marker can only be on fields
+- `Type`: TypeScope - marker can only be on types
+- `Any`: AnyScope - marker can be on fields or types
 
 **Type constraint fields:**
 - `allowedSchemaTypes`: List of allowed OpenAPI schema types (`integer`, `number`, `string`, `boolean`, `array`, `object`)

pkg/analysis/markerscope/analyzer.go

@@ -60,8 +60,11 @@ func newAnalyzer(cfg *MarkerScopeConfig) *analysis.Analyzer {
 		cfg = &MarkerScopeConfig{}
 	}
 
+	// Convert list of marker rules to map
+	customRules := markerRulesListToMap(cfg.MarkerRules)
+
 	a := &analyzer{
-		markerRules:         mergeMarkerRules(DefaultMarkerRules(), cfg.MarkerRules),
+		markerRules:         mergeMarkerRules(DefaultMarkerRules(), customRules),
 		policy:              cfg.Policy,
 		allowDangerousTypes: cfg.AllowDangerousTypes,
 	}
@@ -87,6 +90,17 @@ func newAnalyzer(cfg *MarkerScopeConfig) *analysis.Analyzer {
 	}
 }
 
+// markerRulesListToMap converts a list of marker rules to a map keyed by marker name.
+func markerRulesListToMap(rules []MarkerScopeRule) map[string]MarkerScopeRule {
+	result := make(map[string]MarkerScopeRule, len(rules))
+	for _, rule := range rules {
+		if rule.Name != "" {
+			result[rule.Name] = rule
+		}
+	}
+	return result
+}
+
 // mergeMarkerRules merges custom marker rules with default marker rules.
 // Custom rules take precedence over default rules for the same marker.
 func mergeMarkerRules(defaults, custom map[string]MarkerScopeRule) map[string]MarkerScopeRule {

pkg/analysis/markerscope/analyzer_test.go

@@ -43,31 +43,36 @@ func TestAnalyzerWithCustomMarkers(t *testing.T) {
 	testdata := analysistest.TestData()
 	cfg := &MarkerScopeConfig{
 		Policy: MarkerScopePolicyWarn,
-		MarkerRules: map[string]MarkerScopeRule{
+		MarkerRules: []MarkerScopeRule{
 			// Custom field-only marker
-			"custom:field-only": {
+			{
+				Name:  "custom:field-only",
 				Scope: FieldScope,
 			},
 			// Custom type-only marker
-			"custom:type-only": {
+			{
+				Name:  "custom:type-only",
 				Scope: TypeScope,
 			},
 			// Custom marker with string type constraint
-			"custom:string-only": {
+			{
+				Name:  "custom:string-only",
 				Scope: FieldScope,
 				TypeConstraint: &TypeConstraint{
 					AllowedSchemaTypes: []SchemaType{SchemaTypeString},
 				},
 			},
 			// Custom marker with integer type constraint
-			"custom:integer-only": {
+			{
+				Name:  "custom:integer-only",
 				Scope: FieldScope,
 				TypeConstraint: &TypeConstraint{
 					AllowedSchemaTypes: []SchemaType{SchemaTypeInteger},
 				},
 			},
 			// Custom marker with array of strings constraint
-			"custom:string-array": {
+			{
+				Name:  "custom:string-array",
 				Scope: FieldScope,
 				TypeConstraint: &TypeConstraint{
 					AllowedSchemaTypes: []SchemaType{SchemaTypeArray},

pkg/analysis/markerscope/config.go

@@ -21,36 +21,24 @@ import (
 	"sigs.k8s.io/kube-api-linter/pkg/markers"
 )
 
-// ScopeConstraint defines where a marker is allowed to be placed using bit flags.
-type ScopeConstraint uint8
+// ScopeConstraint defines where a marker is allowed to be placed.
+type ScopeConstraint string
 
 const (
 	// FieldScope indicates the marker can be placed on fields.
-	FieldScope ScopeConstraint = 1 << iota
+	FieldScope ScopeConstraint = "Field"
 	// TypeScope indicates the marker can be placed on type definitions.
-	TypeScope
-
+	TypeScope ScopeConstraint = "Type"
 	// AnyScope indicates the marker can be placed on either fields or types.
-	AnyScope = FieldScope | TypeScope
+	AnyScope ScopeConstraint = "Any"
 )
 
-// String returns a human-readable representation of the scope constraint.
-func (s ScopeConstraint) String() string {
-	switch s {
-	case FieldScope:
-		return "field"
-	case TypeScope:
-		return "type"
-	case AnyScope:
-		return "any"
-	default:
-		return "unknown"
-	}
-}
-
 // Allows checks if the given scope is allowed by this constraint.
 func (s ScopeConstraint) Allows(scope ScopeConstraint) bool {
-	return s&scope != 0
+	if s == AnyScope {
+		return true
+	}
+	return s == scope
 }
 
 // TypeConstraint defines what types a marker can be applied to.
@@ -69,6 +57,10 @@ type TypeConstraint struct {
 
 // MarkerScopeRule defines comprehensive scope validation rules for a marker.
 type MarkerScopeRule struct {
+	// Name is the marker identifier (e.g., "optional", "kubebuilder:validation:Minimum").
+	// This field is only used when MarkerScopeRule is part of a list configuration.
+	Name string `json:"name,omitempty"`
+
 	// Scope specifies where the marker can be placed (field vs type).
 	Scope ScopeConstraint
 
@@ -89,29 +81,29 @@ type MarkerScopePolicy string
 
 const (
 	// MarkerScopePolicyWarn only reports warnings without suggesting fixes.
-	MarkerScopePolicyWarn MarkerScopePolicy = "warn"
+	MarkerScopePolicyWarn MarkerScopePolicy = "Warn"
 
 	// MarkerScopePolicySuggestFix reports warnings and suggests automatic fixes.
-	MarkerScopePolicySuggestFix MarkerScopePolicy = "suggest_fix"
+	MarkerScopePolicySuggestFix MarkerScopePolicy = "SuggestFix"
 )
 
 // MarkerScopeConfig contains configuration for marker scope validation.
 type MarkerScopeConfig struct {
-	// MarkerRules maps marker names to their scope rules with scope and type constraints.
-	// This map can be used to:
+	// MarkerRules is a list of marker rules with scope and type constraints.
+	// This list can be used to:
 	//   - Override default rules for built-in markers (from DefaultMarkerRules)
 	//   - Add rules for custom markers not included in DefaultMarkerRules
 	//
-	// If a marker is not in this map AND not in DefaultMarkerRules(), no scope validation is performed.
-	// If a marker is in both this map and DefaultMarkerRules(), this map takes precedence.
+	// If a marker is not in this list AND not in DefaultMarkerRules(), no scope validation is performed.
+	// If a marker is in both this list and DefaultMarkerRules(), this list takes precedence.
 	//
 	// Example: Adding a custom marker
 	//   markerRules:
-	//     "mycompany:validation:CustomMarker":
+	//     - name: "mycompany:validation:CustomMarker"
 	//       scope: any
 	//       typeConstraint:
 	//         allowedSchemaTypes: ["string"]
-	MarkerRules map[string]MarkerScopeRule `json:"markerRules,omitempty"`
+	MarkerRules []MarkerScopeRule `json:"markerRules,omitempty"`
 
 	// AllowDangerousTypes specifies if dangerous types are allowed.
 	// If true, dangerous types are allowed.

pkg/analysis/markerscope/errors.go

@@ -21,10 +21,18 @@ import (
 )
 
 var (
-	errScopeNonZero     = errors.New("scope must be non-zero")
-	errInvalidScopeBits = errors.New("invalid scope bits")
+	errScopeRequired = errors.New("scope is required")
 )
 
+// InvalidScopeConstraintError represents an error when a scope constraint is invalid.
+type InvalidScopeConstraintError struct {
+	Scope string
+}
+
+func (e *InvalidScopeConstraintError) Error() string {
+	return fmt.Sprintf("invalid scope: %q (must be one of: Field, Type, Any)", e.Scope)
+}
+
 // InvalidSchemaTypeError represents an error when a schema type is invalid.
 type InvalidSchemaTypeError struct {
 	SchemaType string

pkg/analysis/markerscope/initializer.go

@@ -58,9 +58,17 @@ func validateConfig(cfg *MarkerScopeConfig, fldPath *field.Path) field.ErrorList
 	}
 
 	// Validate marker rules
-	for marker, rule := range cfg.MarkerRules {
+	for i, rule := range cfg.MarkerRules {
+		markerRulePath := fldPath.Child("markerRules").Index(i)
+
+		// Validate that name is not empty
+		if rule.Name == "" {
+			fieldErrors = append(fieldErrors, field.Required(markerRulePath.Child("name"), "marker name is required"))
+			continue
+		}
+
 		if err := validateMarkerRule(rule); err != nil {
-			fieldErrors = append(fieldErrors, field.Invalid(fldPath.Child("markerRules", marker), rule, err.Error()))
+			fieldErrors = append(fieldErrors, field.Invalid(markerRulePath, rule, err.Error()))
 		}
 	}
 
@@ -69,14 +77,16 @@ func validateConfig(cfg *MarkerScopeConfig, fldPath *field.Path) field.ErrorList
 
 func validateMarkerRule(rule MarkerScopeRule) error {
 	// Validate scope constraint
-	if rule.Scope == 0 {
-		return errScopeNonZero
+	if rule.Scope == "" {
+		return errScopeRequired
 	}
 
-	// Validate that scope is a valid combination of FieldScope and/or TypeScope
-	validScopes := FieldScope | TypeScope
-	if rule.Scope&^validScopes != 0 {
-		return errInvalidScopeBits
+	// Validate that scope is a valid value
+	switch rule.Scope {
+	case FieldScope, TypeScope, AnyScope:
+		// Valid scope
+	default:
+		return &InvalidScopeConstraintError{Scope: string(rule.Scope)}
 	}
 
 	// Validate type constraint if present