feat: add conflictingmarkers linter to detect mutually exclusive markers

Author: yongruilin

docs/linters.md

@@ -17,6 +17,7 @@
 - [StatusOptional](#statusoptional) - Ensures status fields are marked as optional
 - [StatusSubresource](#statussubresource) - Validates status subresource configuration
 - [UniqueMarkers](#uniquemarkers) - Ensures unique marker definitions
+- [ConflictingMarkers](#conflictingmarkers) - Detects and reports when mutually exclusive markers are used on the same field
 
 ## Conditions
 
@@ -345,3 +346,51 @@ Taking the example configuration from above:
 - Marker definitions of `custom:SomeCustomMarker:fruit=apple,color=red` and `custom:SomeCustomMarker:fruit=orange,color=red` would _not_ violate the uniqueness requirement.
 
 Each entry in `customMarkers` must have a unique `identifier`.
+
+## ConflictingMarkers
+
+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 two or more sets of a conflict definition 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 is configurable and allows users to define sets of conflicting markers.
+Each conflict set must specify:
+- A unique name for the conflict
+- Multiple sets of markers that are mutually exclusive with each other (at least 2 sets)
+- A description explaining why the markers conflict
+
+### Configuration
+
+```yaml
+lintersConfig:
+  conflictingmarkers:
+    conflicts:
+      - name: "optional_vs_required"
+        sets:
+          - ["optional", "+kubebuilder:validation:Optional", "+k8s:validation:optional"]
+          - ["required", "+kubebuilder:validation:Required", "+k8s:validation:required"]
+        description: "A field cannot be both optional and required"
+      - name: "default_vs_required"
+        sets:
+          - ["default", "+kubebuilder:default"]
+          - ["required", "+kubebuilder:validation:Required", "+k8s:validation:required"]
+        description: "A field with a default value cannot be required"
+      - name: "mutually_exclusive_validation"
+        sets:
+          - ["optional", "+kubebuilder:validation:Optional"]
+          - ["required", "+kubebuilder:validation:Required"]
+          - ["default", "+kubebuilder:default"]
+        description: "A field cannot be optional, required, and have a default value"
+      - name: "my_custom_conflict"
+        sets:
+          - ["custom:marker1", "custom:marker2"]
+          - ["custom:marker3", "custom:marker4"]
+        description: "These markers conflict because..."
+```
+
+**Note**: This linter is not enabled by default and must be explicitly enabled in the configuration.
+
+The linter does not provide automatic fixes as it cannot determine which conflicting marker should be removed.

pkg/analysis/conflictingmarkers/analyzer.go

@@ -0,0 +1,137 @@
+/*
+Copyright 2025 The Kubernetes 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.
+*/
+package conflictingmarkers
+
+import (
+	"fmt"
+	"go/ast"
+	"strings"
+
+	"golang.org/x/tools/go/analysis"
+	"k8s.io/apimachinery/pkg/util/sets"
+	kalerrors "sigs.k8s.io/kube-api-linter/pkg/analysis/errors"
+	"sigs.k8s.io/kube-api-linter/pkg/analysis/helpers/extractjsontags"
+	"sigs.k8s.io/kube-api-linter/pkg/analysis/helpers/inspector"
+	"sigs.k8s.io/kube-api-linter/pkg/analysis/helpers/markers"
+	"sigs.k8s.io/kube-api-linter/pkg/analysis/utils"
+)
+
+const name = "conflictingmarkers"
+
+type analyzer struct {
+	conflictSets []ConflictSet
+}
+
+func newAnalyzer(cfg *ConflictingMarkersConfig) *analysis.Analyzer {
+	if cfg == nil {
+		cfg = &ConflictingMarkersConfig{}
+	}
+
+	// Register markers from configuration
+	for _, conflictSet := range cfg.Conflicts {
+		for _, set := range conflictSet.Sets {
+			for _, markerID := range set {
+				markers.DefaultRegistry().Register(markerID)
+			}
+		}
+	}
+
+	a := &analyzer{
+		conflictSets: cfg.Conflicts,
+	}
+
+	// Use configured documentation or fall back to default
+	doc := cfg.Doc
+	if doc == "" {
+		doc = "Check that fields do not have conflicting markers from mutually exclusive sets"
+	}
+
+	return &analysis.Analyzer{
+		Name:     name,
+		Doc:      doc,
+		Run:      a.run,
+		Requires: []*analysis.Analyzer{inspector.Analyzer},
+	}
+}
+
+func (a *analyzer) run(pass *analysis.Pass) (any, error) {
+	inspect, ok := pass.ResultOf[inspector.Analyzer].(inspector.Inspector)
+	if !ok {
+		return nil, kalerrors.ErrCouldNotGetInspector
+	}
+
+	inspect.InspectFields(func(field *ast.Field, stack []ast.Node, _ extractjsontags.FieldTagInfo, markersAccess markers.Markers) {
+		checkField(pass, field, markersAccess, a.conflictSets)
+	})
+
+	return nil, nil //nolint:nilnil
+}
+
+func checkField(pass *analysis.Pass, field *ast.Field, markersAccess markers.Markers, conflictSets []ConflictSet) {
+	if field == nil || len(field.Names) == 0 {
+		return
+	}
+
+	markers := utils.TypeAwareMarkerCollectionForField(pass, markersAccess, field)
+
+	for _, conflictSet := range conflictSets {
+		checkConflict(pass, field, markers, conflictSet)
+	}
+}
+
+func checkConflict(pass *analysis.Pass, field *ast.Field, markers markers.MarkerSet, conflictSet ConflictSet) {
+	// Track which sets have markers present
+	var conflictingMarkers []sets.Set[string]
+
+	// Check each set for markers
+	for _, set := range conflictSet.Sets {
+		foundMarkers := sets.New[string]()
+		for _, markerID := range set {
+			if markers.Has(markerID) {
+				foundMarkers.Insert(markerID)
+			}
+		}
+		// Only add the set if it has at least one marker
+		if foundMarkers.Len() > 0 {
+			conflictingMarkers = append(conflictingMarkers, foundMarkers)
+		}
+	}
+
+	// If two or more sets have markers, report the conflict
+	if len(conflictingMarkers) >= 2 {
+		reportConflict(pass, field, conflictSet, conflictingMarkers)
+	}
+}
+
+func reportConflict(pass *analysis.Pass, field *ast.Field, conflictSet ConflictSet, conflictingMarkers []sets.Set[string]) {
+	// Build a descriptive message showing which sets conflict
+	var setDescriptions []string
+	for _, set := range conflictingMarkers {
+		markersList := sets.List(set)
+		setDescriptions = append(setDescriptions, fmt.Sprintf("%v", markersList))
+	}
+
+	message := fmt.Sprintf("field %s has conflicting markers: %s: {%s}. %s",
+		field.Names[0].Name,
+		conflictSet.Name,
+		strings.Join(setDescriptions, ", "),
+		conflictSet.Description)
+
+	pass.Report(analysis.Diagnostic{
+		Pos:     field.Pos(),
+		Message: message,
+	})
+}

pkg/analysis/conflictingmarkers/config.go

@@ -0,0 +1,42 @@
+/*
+Copyright 2025 The Kubernetes 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.
+*/
+package conflictingmarkers
+
+// ConflictingMarkersConfig contains the configuration for the conflictingmarkers linter.
+type ConflictingMarkersConfig struct {
+	// Doc is the documentation string for the analyzer.
+	// If not provided, a default description will be used.
+	Doc string `json:"doc"`
+	// Conflicts allows users to define sets of conflicting markers.
+	// Each entry defines a conflict between multiple sets of markers.
+	Conflicts []ConflictSet `json:"conflicts"`
+}
+
+// ConflictSet represents a conflict between multiple sets of markers.
+// Markers within each set are mutually exclusive with markers in all other sets.
+// The linter will emit a diagnostic when a field has markers from two or more sets.
+type ConflictSet struct {
+	// Name is a human-readable name for this conflict set.
+	// This name will appear in diagnostic messages to identify the type of conflict.
+	Name string `json:"name"`
+	// Sets contains the sets of markers that are mutually exclusive with each other.
+	// Each set is a slice of marker identifiers.
+	// The linter will emit a diagnostic when a field has markers from two or more sets.
+	Sets [][]string `json:"sets"`
+	// Description provides a description of why these markers conflict.
+	// The linter will include this description in the diagnostic message when a conflict is detected.
+	Description string `json:"description"`
+}

pkg/analysis/conflictingmarkers/doc.go

@@ -0,0 +1,63 @@
+/*
+Copyright 2025 The Kubernetes 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.
+*/
+
+/*
+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.
+
+The linter reports issues when markers from two or more sets of a conflict definition 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 is fully configurable and requires users to define all conflict sets they want to check.
+There are no built-in conflict sets - all conflicts must be explicitly configured.
+
+Each conflict set must specify:
+- A unique name for the conflict
+- Multiple sets of markers that are mutually exclusive with each other (at least 2 sets)
+- A description explaining why the markers conflict
+
+Example configuration:
+```yaml
+lintersConfig:
+
+	conflictingmarkers:
+	  # Optional: Custom documentation for the analyzer
+	  doc: "Custom analyzer description for conflicting markers"
+	  conflicts:
+	    - name: "optional_vs_required"
+	      sets:
+	        - ["optional", "+kubebuilder:validation:Optional", "+k8s:validation:optional"]
+	        - ["required", "+kubebuilder:validation:Required", "+k8s:validation:required"]
+	      description: "A field cannot be both optional and required"
+	    - name: "my_custom_conflict"
+	      sets:
+	        - ["custom:marker1", "custom:marker2"]
+	        - ["custom:marker3", "custom:marker4"]
+	        - ["custom:marker5", "custom:marker6"]
+	      description: "These markers define different storage backends that cannot be used simultaneously"
+
+```
+
+Configuration options:
+- `doc`: Optional custom documentation string for the analyzer. If not provided, a default description will be used.
+- `conflicts`: Required list of conflict set definitions.
+
+Note: This linter is not enabled by default and must be explicitly enabled in the configuration.
+
+The linter does not provide automatic fixes as it cannot determine which conflicting marker should be removed.
+*/
+package conflictingmarkers