feat: implement option to disable built-in conflicts in conflictingmarkers linter and add corresponding tests

Author: yongruilin

docs/linters.md

@@ -79,6 +79,10 @@ When the `json` tag is present, and matches the first word of the field comment
 The `conflictingmarkers` linter detects and reports when mutually exclusive markers are used on the same field.
 This prevents common configuration errors and unexpected behavior in Kubernetes API types.
 
+The linter reports issues when markers from both sets of a conflict pair are present on the same field.
+It does NOT report issues when multiple markers from the same set are present - only when markers from
+different sets within the same conflict definition are found together.
+
 The linter includes built-in checks for the following conflicts:
 
 1. **Optional vs Required**:
@@ -88,7 +92,7 @@ The linter includes built-in checks for the following conflicts:
 
 2. **Default vs Required**:
    - Set A: `+default`, `+kubebuilder:default`
-   - Set B: `+required`, `+kubebuilder:validation:Required`
+   - Set B: `+required`, `+kubebuilder:validation:Required`, `+k8s:required`
    - A field with a default value cannot be required
 
 ### Configuration
@@ -99,17 +103,60 @@ Each custom conflict set must specify a name, two sets of markers, and a descrip
 ```yaml
 lintersConfig:
   conflictingmarkers:
+    disableBuiltInConflicts: true  # When set to true, only custom conflicts will be checked
     customConflicts:
-      - name: "my_custom_conflict"
-        setA: 
-          - "custom:marker1"
-          - "custom:marker2"
-        setB:
-          - "custom:marker3"
-          - "custom:marker4"
-        description: "These markers conflict because..."
+      - name: "custom_conflict_1"
+        setA: ["custom:marker1", "custom:marker2"]
+        setB: ["custom:marker3", "custom:marker4"]
+        description: "custom:marker1, custom:marker2 conflict with custom:marker3, custom:marker4"
+      - name: "custom_conflict_2"
+        setA: ["custom:marker5", "custom:marker6"]
+        setB: ["custom:marker7", "custom:marker8"]
+        description: "custom:marker5, custom:marker6 conflict with custom:marker7, custom:marker8"
 ```
 
+**Configuration options:**
+- `disableBuiltInConflicts` (bool): When set to true, only custom conflicts will be checked
+- `customConflicts` (array): List of custom conflict definitions
+
+**Example configurations:**
+
+1. Default behavior (built-in + custom conflicts):
+```yaml
+lintersConfig:
+  conflictingmarkers:
+    customConflicts:
+      - name: "custom_conflict_example"
+        setA: ["custom:marker1"]
+        setB: ["custom:marker2"]
+        description: "Custom markers 1 and 2 are mutually exclusive"
+```
+
+2. Custom conflicts only (built-in conflicts disabled):
+```yaml
+lintersConfig:
+  conflictingmarkers:
+    disableBuiltInConflicts: true
+    customConflicts:
+      - name: "custom_conflict_1"
+        setA: ["custom:marker1", "custom:marker2"]
+        setB: ["custom:marker3", "custom:marker4"]
+        description: "custom:marker1, custom:marker2 conflict with custom:marker3, custom:marker4"
+      - name: "custom_conflict_2"
+        setA: ["custom:marker5", "custom:marker6"]
+        setB: ["custom:marker7", "custom:marker8"]
+        description: "custom:marker5, custom:marker6 conflict with custom:marker7, custom:marker8"
+```
+
+3. Built-in conflicts only (no custom conflicts):
+```yaml
+lintersConfig:
+  conflictingmarkers: {}  # Uses default built-in conflicts only
+```
+
+**Limitations:**
+The linter does not provide automatic fixes as it cannot determine which conflicting marker should be removed.
+
 ## DuplicateMarkers
 
 The duplicatemarkers linter checks for exact duplicates of markers for types and fields.

pkg/analysis/conflictingmarkers/analyzer.go

@@ -63,8 +63,18 @@ func newAnalyzer(cfg *ConflictingMarkersConfig) *analysis.Analyzer {
 		}
 	}
 
+	var conflictSets []ConflictSet
+
+	// Add built-in conflicts unless disabled
+	if !cfg.DisableBuiltInConflicts {
+		conflictSets = append(conflictSets, defaultConflictSets()...)
+	}
+
+	// Add custom conflicts
+	conflictSets = append(conflictSets, cfg.CustomConflicts...)
+
 	a := &analyzer{
-		conflictSets: append(defaultConflictSets(), cfg.CustomConflicts...),
+		conflictSets: conflictSets,
 	}
 
 	return &analysis.Analyzer{

pkg/analysis/conflictingmarkers/analyzer_test.go

@@ -58,3 +58,28 @@ func TestCustomConfiguration(t *testing.T) {
 
 	analysistest.Run(t, testdata, analyzer, "b")
 }
+
+func TestDisableBuiltInConflicts(t *testing.T) {
+	testdata := analysistest.TestData()
+
+	config := &conflictingmarkers.ConflictingMarkersConfig{
+		DisableBuiltInConflicts: true,
+		CustomConflicts: []conflictingmarkers.ConflictSet{
+			{
+				Name:        "custom_conflict",
+				SetA:        []string{"custom:marker1", "custom:marker2"},
+				SetB:        []string{"custom:marker3", "custom:marker4"},
+				Description: "Custom markers conflict with each other",
+			},
+		},
+	}
+
+	initializer := conflictingmarkers.Initializer()
+
+	analyzer, err := initializer.Init(config)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	analysistest.Run(t, testdata, analyzer, "c")
+}

pkg/analysis/conflictingmarkers/config.go

@@ -20,6 +20,11 @@ type ConflictingMarkersConfig struct {
 	// CustomConflicts allows users to define their own sets of conflicting markers.
 	// Each entry defines a conflict between two sets of markers.
 	CustomConflicts []ConflictSet `json:"customConflicts"`
+
+	// DisableBuiltInConflicts allows users to opt-out of built-in conflict detection.
+	// When set to true, only custom conflicts defined in CustomConflicts will be checked.
+	// Built-in conflicts include optional_vs_required and default_vs_required checks.
+	DisableBuiltInConflicts bool `json:"disableBuiltInConflicts"`
 }
 
 // ConflictSet represents a conflict between two sets of markers.

pkg/analysis/conflictingmarkers/doc.go

@@ -18,40 +18,74 @@ limitations under the License.
 conflictingmarkers is a linter that detects and reports when mutually exclusive markers are used on the same field.
 This prevents common configuration errors and unexpected behavior in Kubernetes API types.
 
+How it works:
 The linter reports issues when markers from both sets of a conflict pair are present on the same field.
 It does NOT report issues when multiple markers from the same set are present - only when markers from
 different sets within the same conflict definition are found together.
 
+Built-in conflicts:
 The linter includes built-in checks for the following conflicts:
 
 1. Optional vs Required:
-  - Set A: optional, +kubebuilder:validation:Optional
-  - Set B: required, +kubebuilder:validation:Required
+  - Set A: +optional, +kubebuilder:validation:Optional, +k8s:optional
+  - Set B: +required, +kubebuilder:validation:Required, +k8s:required
   - A field cannot be both optional and required
-  - Note: Multiple optional markers or multiple required markers are allowed
 
 2. Default vs Required:
-  - Set A: default, +kubebuilder:default
-  - Set B: required, +kubebuilder:validation:Required
+  - Set A: +default, +kubebuilder:default
+  - Set B: +required, +kubebuilder:validation:Required, +k8s:required
   - A field with a default value cannot be required
-  - Note: Multiple default markers or multiple required markers are allowed
 
+Configuration:
 The linter is configurable and allows users to define their own custom sets of conflicting markers.
 Each custom conflict set must specify a name, two sets of markers, and a description of why they conflict.
 
-Example configuration:
+Configuration options:
+- disableBuiltInConflicts (bool): When set to true, only custom conflicts will be checked
+- customConflicts (array): List of custom conflict definitions
+
+Example configurations:
+
+1. Default behavior (built-in + custom conflicts):
+```yaml
+lintersConfig:
+
+	conflictingmarkers:
+	  customConflicts:
+	    - name: "custom_conflict_example"
+	      setA: ["custom:marker1"]
+	      setB: ["custom:marker2"]
+	      description: "Custom markers 1 and 2 are mutually exclusive"
+
+```
+
+2. Custom conflicts only (built-in conflicts disabled):
 ```yaml
 lintersConfig:
 
 	conflictingmarkers:
+	  disableBuiltInConflicts: true
 	  customConflicts:
-	    - name: "my_custom_conflict"
+	    - name: "custom_conflict_1"
 	      setA: ["custom:marker1", "custom:marker2"]
 	      setB: ["custom:marker3", "custom:marker4"]
-	      description: "These markers conflict because..."
+	      description: "custom:marker1, custom:marker2 conflict with custom:marker3, custom:marker4"
+	    - name: "custom_conflict_2"
+	      setA: ["custom:marker5", "custom:marker6"]
+	      setB: ["custom:marker7", "custom:marker8"]
+	      description: "custom:marker5, custom:marker6 conflict with custom:marker7, custom:marker8"
+
+```
+
+3. Built-in conflicts only (no custom conflicts):
+```yaml
+lintersConfig:
+
+	conflictingmarkers: {}  # Uses default built-in conflicts only
 
 ```
 
+Limitations:
 The linter does not provide automatic fixes as it cannot determine which conflicting marker should be removed.
 */
 package conflictingmarkers

pkg/analysis/conflictingmarkers/testdata/src/c/c.go

@@ -0,0 +1,20 @@
+package c
+
+type DisableBuiltInConflictsStruct struct {
+	// This field has built-in conflicts but they should be ignored when DisableBuiltInConflicts is true
+	// +optional
+	// +required
+	BuiltInConflictIgnoredField string `json:"builtInConflictIgnoredField"`
+
+	// This field has custom conflicts that should still be detected
+	// +custom:marker1
+	// +custom:marker3
+	CustomConflictDetectedField string `json:"customConflictDetectedField"` // want "field CustomConflictDetectedField has conflicting markers: custom_conflict: \\[custom:marker1\\] and \\[custom:marker3\\]. Custom markers conflict with each other"
+
+	// This field has both built-in and custom conflicts, but only custom conflicts should be reported
+	// +optional
+	// +required
+	// +custom:marker1
+	// +custom:marker3
+	MixedConflictsField string `json:"mixedConflictsField"` // want "field MixedConflictsField has conflicting markers: custom_conflict: \\[custom:marker1\\] and \\[custom:marker3\\]. Custom markers conflict with each other"
+}

pkg/analysis/conflictingmarkers/testdata/src/c/c.go.golden

@@ -0,0 +1,20 @@
+package c
+
+type DisableBuiltInConflictsStruct struct {
+	// This field has built-in conflicts but they should be ignored when DisableBuiltInConflicts is true
+	// +optional
+	// +required
+	BuiltInConflictIgnoredField string `json:"builtInConflictIgnoredField"`
+
+	// This field has custom conflicts that should still be detected
+	// +custom:marker1
+	// +custom:marker3
+	CustomConflictDetectedField string `json:"customConflictDetectedField"` // want "field CustomConflictDetectedField has conflicting markers: custom_conflict: \\[custom:marker1\\] and \\[custom:marker3\\]. Custom markers conflict with each other"
+
+	// This field has both built-in and custom conflicts, but only custom conflicts should be reported
+	// +optional
+	// +required
+	// +custom:marker1
+	// +custom:marker3
+	MixedConflictsField string `json:"mixedConflictsField"` // want "field MixedConflictsField has conflicting markers: custom_conflict: \\[custom:marker1\\] and \\[custom:marker3\\]. Custom markers conflict with each other"
+}