refactor(markerscope): separate overrideMarkers and customMarkers with validation

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

Author: nayuta723

docs/linters.md

@@ -433,33 +433,52 @@ The linter includes built-in rules for all standard kubebuilder markers and k8s
 
 ### Configuration
 
-You can customize marker rules or add support for custom markers:
+You can customize marker rules or add support for custom markers.
+
+**Scope values:**
+- `Field`: Marker can only be applied to struct fields
+- `Type`: Marker can only be applied to type definitions
+- `Any`: Marker can be applied to either fields or type definitions
+
+**Type constraints:**
+
+The `typeConstraint` field allows you to restrict which Go types a marker can be applied to. This ensures that markers are only used with compatible data types (e.g., numeric markers like `Minimum` are only applied to integer/number types).
+
+**Type constraint fields:**
+- `allowedSchemaTypes`: List of allowed OpenAPI schema types (`integer`, `number`, `string`, `boolean`, `array`, `object`)
+- `elementConstraint`: Nested constraint for array element types (only valid when `allowedSchemaTypes` includes `array`)
+- `strictTypeConstraint`: When `true`, markers with `AnyScope` and type constraints applied to fields using named types must be declared on the type definition instead of the field. Defaults to `false`.
+
+**Configuration example:**
 
 ```yaml
 lintersConfig:
   markerscope:
     policy: Warn | SuggestFix # The policy for marker scope violations. Defaults to `Warn`.
     allowDangerousTypes: false # Allow dangerous number types (float32, float64). Defaults to `false`.
-    markerRules:
-      # Override default rule for a built-in marker
-      - name: "optional"
+
+    # Override default rules for built-in markers
+    overrideMarkers:
+      - identifier: "optional"
         scope: Field  # or: Type, Any
 
-      # Add a custom marker with scope constraint only
-      - name: "mycompany:validation:CustomMarker"
+    # Add rules for custom markers
+    customMarkers:
+      # Custom marker with scope constraint only
+      - identifier: "mycompany:validation:CustomMarker"
         scope: Any
 
-      # Add a custom marker with scope and type constraints
-      - name: "mycompany:validation:NumericLimit"
+      # Custom marker with scope and type constraints
+      - identifier: "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
-      - name: "mycompany:validation:items:StringFormat"
+      # Custom array items marker with element type constraint
+      - identifier: "mycompany:validation:items:StringFormat"
         scope: Any
         typeConstraint:
           allowedSchemaTypes:
@@ -469,18 +488,10 @@ lintersConfig:
               - string
 ```
 
-**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
-
-**Type constraint fields:**
-- `allowedSchemaTypes`: List of allowed OpenAPI schema types (`integer`, `number`, `string`, `boolean`, `array`, `object`)
-- `elementConstraint`: Nested constraint for array element types (only valid when `allowedSchemaTypes` includes `array`)
-- `strictTypeConstraint`: When `true`, markers with `AnyScope` and type constraints applied to fields using named types must be declared on the type definition instead of the field. Defaults to `false`.
-
-If a marker is not in `markerRules` and not in the default rules, no validation is performed for that marker.
-If a marker is in both `markerRules` and the default rules, your configuration takes precedence.
+**Configuration notes:**
+- Use `overrideMarkers` to customize the behavior of built-in kubebuilder/controller-runtime markers
+- Use `customMarkers` to add validation for your own custom markers
+- If a marker is not in either list and not in the default rules, no validation is performed for that marker
 
 ### Fixes
 

pkg/analysis/markerscope/analyzer.go

@@ -60,11 +60,22 @@ func newAnalyzer(cfg *MarkerScopeConfig) *analysis.Analyzer {
 		cfg = &MarkerScopeConfig{}
 	}
 
-	// Convert list of marker rules to map
-	customRules := markerRulesListToMap(cfg.MarkerRules)
+	// Convert override and custom marker lists to maps
+	overrideRules := markerRulesListToMap(cfg.OverrideMarkers)
+	customRules := markerRulesListToMap(cfg.CustomMarkers)
+
+	// Merge rules:
+	// 1. Start with default built-in marker rules
+	// 2. Apply overrides (replaces default rules for built-in markers)
+	// 3. Add custom markers (new markers not in defaults)
+	// Note: Validation ensures overrideMarkers only contains built-in markers
+	// and customMarkers only contains non-built-in markers, so no conflicts.
+	rules := DefaultMarkerRules()
+	maps.Copy(rules, overrideRules) // Override built-in markers
+	maps.Copy(rules, customRules)   // Add custom markers
 
 	a := &analyzer{
-		markerRules:         mergeMarkerRules(DefaultMarkerRules(), customRules),
+		markerRules:         rules,
 		policy:              cfg.Policy,
 		allowDangerousTypes: cfg.AllowDangerousTypes,
 	}
@@ -90,31 +101,17 @@ func newAnalyzer(cfg *MarkerScopeConfig) *analysis.Analyzer {
 	}
 }
 
-// markerRulesListToMap converts a list of marker rules to a map keyed by marker name.
+// markerRulesListToMap converts a list of marker rules to a map keyed by marker identifier.
 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
+		if rule.Identifier != "" {
+			result[rule.Identifier] = 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 {
-	merged := make(map[string]MarkerScopeRule, len(defaults)+len(custom))
-
-	// Copy all default rules
-	maps.Copy(merged, defaults)
-
-	// Override with custom rules
-	maps.Copy(merged, custom)
-
-	return merged
-}
-
 func (a *analyzer) run(pass *analysis.Pass) (any, error) {
 	inspect, ok := pass.ResultOf[inspect.Analyzer].(*inspector.Inspector)
 	if !ok {

pkg/analysis/markerscope/analyzer_test.go

@@ -39,41 +39,53 @@ func TestAnalyzerSuggestFixes(t *testing.T) {
 	analysistest.RunWithSuggestedFixes(t, testdata, analyzer, "a")
 }
 
-func TestAnalyzerWithCustomMarkers(t *testing.T) {
+func TestAnalyzerWithCustomAndOverrideMarkers(t *testing.T) {
 	testdata := analysistest.TestData()
 	cfg := &MarkerScopeConfig{
 		Policy: MarkerScopePolicyWarn,
-		MarkerRules: []MarkerScopeRule{
+		OverrideMarkers: []MarkerScopeRule{
+			// Override built-in "optional" to allow on types (default is FieldScope only)
+			{
+				Identifier: "optional",
+				Scope:      AnyScope,
+			},
+			// Override built-in "required" to allow on types (default is FieldScope only)
+			{
+				Identifier: "required",
+				Scope:      AnyScope,
+			},
+		},
+		CustomMarkers: []MarkerScopeRule{
 			// Custom field-only marker
 			{
-				Name:  "custom:field-only",
-				Scope: FieldScope,
+				Identifier: "custom:field-only",
+				Scope:      FieldScope,
 			},
 			// Custom type-only marker
 			{
-				Name:  "custom:type-only",
-				Scope: TypeScope,
+				Identifier: "custom:type-only",
+				Scope:      TypeScope,
 			},
 			// Custom marker with string type constraint
 			{
-				Name:  "custom:string-only",
-				Scope: FieldScope,
+				Identifier: "custom:string-only",
+				Scope:      FieldScope,
 				TypeConstraint: &TypeConstraint{
 					AllowedSchemaTypes: []SchemaType{SchemaTypeString},
 				},
 			},
 			// Custom marker with integer type constraint
 			{
-				Name:  "custom:integer-only",
-				Scope: FieldScope,
+				Identifier: "custom:integer-only",
+				Scope:      FieldScope,
 				TypeConstraint: &TypeConstraint{
 					AllowedSchemaTypes: []SchemaType{SchemaTypeInteger},
 				},
 			},
 			// Custom marker with array of strings constraint
 			{
-				Name:  "custom:string-array",
-				Scope: FieldScope,
+				Identifier: "custom:string-array",
+				Scope:      FieldScope,
 				TypeConstraint: &TypeConstraint{
 					AllowedSchemaTypes: []SchemaType{SchemaTypeArray},
 					ElementConstraint: &TypeConstraint{

pkg/analysis/markerscope/config.go

@@ -57,9 +57,8 @@ 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"`
+	// Identifier is the marker identifier (e.g., "optional", "kubebuilder:validation:Minimum").
+	Identifier string `json:"identifier,omitempty"`
 
 	// Scope specifies where the marker can be placed (field vs type).
 	Scope ScopeConstraint
@@ -89,21 +88,25 @@ const (
 
 // MarkerScopeConfig contains configuration for marker scope validation.
 type MarkerScopeConfig struct {
-	// 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
+	// OverrideMarkers is a list of marker rules that override default rules for built-in markers.
+	// Use this to customize the behavior of standard kubebuilder/controller-runtime markers.
 	//
-	// 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: Override the built-in "optional" marker
+	//   overrideMarkers:
+	//     - identifier: "optional"
+	//       scope: Field
+	OverrideMarkers []MarkerScopeRule `json:"overrideMarkers,omitempty"`
+
+	// CustomMarkers is a list of marker rules for custom markers not included in the default rules.
+	// Use this to add validation for your own custom markers.
 	//
-	// Example: Adding a custom marker
-	//   markerRules:
-	//     - name: "mycompany:validation:CustomMarker"
-	//       scope: any
+	// Example: Add a custom marker
+	//   customMarkers:
+	//     - identifier: "mycompany:validation:CustomMarker"
+	//       scope: Any
 	//       typeConstraint:
 	//         allowedSchemaTypes: ["string"]
-	MarkerRules []MarkerScopeRule `json:"markerRules,omitempty"`
+	CustomMarkers []MarkerScopeRule `json:"customMarkers,omitempty"`
 
 	// AllowDangerousTypes specifies if dangerous types are allowed.
 	// If true, dangerous types are allowed.

pkg/analysis/markerscope/initializer.go

@@ -57,13 +57,45 @@ func validateConfig(cfg *MarkerScopeConfig, fldPath *field.Path) field.ErrorList
 			fmt.Sprintf("invalid policy, must be one of: %q, %q", MarkerScopePolicyWarn, MarkerScopePolicySuggestFix)))
 	}
 
-	// Validate marker rules
-	for i, rule := range cfg.MarkerRules {
-		markerRulePath := fldPath.Child("markerRules").Index(i)
+	// Get default marker rules for validation
+	defaultRules := DefaultMarkerRules()
 
-		// Validate that name is not empty
-		if rule.Name == "" {
-			fieldErrors = append(fieldErrors, field.Required(markerRulePath.Child("name"), "marker name is required"))
+	// Validate override marker rules
+	for i, rule := range cfg.OverrideMarkers {
+		markerRulePath := fldPath.Child("overrideMarkers").Index(i)
+
+		// Validate that identifier is not empty
+		if rule.Identifier == "" {
+			fieldErrors = append(fieldErrors, field.Required(markerRulePath.Child("identifier"), "marker identifier is required"))
+			continue
+		}
+
+		// Validate that override marker exists in default rules
+		if _, exists := defaultRules[rule.Identifier]; !exists {
+			fieldErrors = append(fieldErrors, field.Invalid(markerRulePath.Child("identifier"), rule.Identifier,
+				"override marker must be a built-in marker; use customMarkers for custom markers"))
+			continue
+		}
+
+		if err := validateMarkerRule(rule); err != nil {
+			fieldErrors = append(fieldErrors, field.Invalid(markerRulePath, rule, err.Error()))
+		}
+	}
+
+	// Validate custom marker rules
+	for i, rule := range cfg.CustomMarkers {
+		markerRulePath := fldPath.Child("customMarkers").Index(i)
+
+		// Validate that identifier is not empty
+		if rule.Identifier == "" {
+			fieldErrors = append(fieldErrors, field.Required(markerRulePath.Child("identifier"), "marker identifier is required"))
+			continue
+		}
+
+		// Validate that custom marker does not exist in default rules
+		if _, exists := defaultRules[rule.Identifier]; exists {
+			fieldErrors = append(fieldErrors, field.Invalid(markerRulePath.Child("identifier"), rule.Identifier,
+				"custom marker cannot be a built-in marker; use overrideMarkers to override built-in markers"))
 			continue
 		}