Merge pull request #220 from itzPranshul/main-customMessages

Add support for custom messages in preferredmarkers linter

Author: k8s-ci-robot

pkg/analysis/preferredmarkers/analyzer.go

@@ -34,20 +34,29 @@ const name = "preferredmarkers"
 type analyzer struct {
 	// equivalentToPreferred maps equivalent marker identifiers to their preferred identifiers
 	equivalentToPreferred map[string]string
+
+	// preferredToMessage maps preferred marker identifiers to their custom message
+	preferredToMessage map[string]string
 }
 
 // newAnalyzer creates a new analysis.Analyzer for the preferredmarkers
 // linter based on the provided Config.
 func newAnalyzer(cfg *Config) *analysis.Analyzer {
 	a := &analyzer{
 		equivalentToPreferred: make(map[string]string),
+		preferredToMessage:    make(map[string]string),
 	}
 
 	// Build the mapping from equivalent identifiers to preferred identifiers
 	for _, marker := range cfg.Markers {
 		for _, equivalent := range marker.EquivalentIdentifiers {
 			a.equivalentToPreferred[equivalent.Identifier] = marker.PreferredIdentifier
 		}
+
+		msg := marker.Message
+		if msg != "" {
+			a.preferredToMessage[marker.PreferredIdentifier] = msg
+		}
 	}
 
 	analyzer := &analysis.Analyzer{
@@ -75,11 +84,11 @@ func (a *analyzer) run(pass *analysis.Pass) (any, error) {
 	}
 
 	inspect.InspectFields(func(field *ast.Field, _ extractjsontags.FieldTagInfo, markersAccess markers.Markers, qualifiedFieldName string) {
-		checkField(pass, field, markersAccess, a.equivalentToPreferred, qualifiedFieldName)
+		checkField(pass, field, markersAccess, a.equivalentToPreferred, a.preferredToMessage, qualifiedFieldName)
 	})
 
 	inspect.InspectTypeSpec(func(typeSpec *ast.TypeSpec, markersAccess markers.Markers) {
-		checkType(pass, typeSpec, markersAccess, a.equivalentToPreferred)
+		checkType(pass, typeSpec, markersAccess, a.equivalentToPreferred, a.preferredToMessage)
 	})
 
 	return nil, nil //nolint:nilnil
@@ -88,26 +97,26 @@ func (a *analyzer) run(pass *analysis.Pass) (any, error) {
 // checkField validates a single struct field for marker usage.
 // Only checks markers directly on the field, not inherited from type aliases,
 // since inherited markers are already reported at the type level.
-func checkField(pass *analysis.Pass, field *ast.Field, markersAccess markers.Markers, equivalentToPreferred map[string]string, qualifiedFieldName string) {
+func checkField(pass *analysis.Pass, field *ast.Field, markersAccess markers.Markers, equivalentToPreferred, preferredToMessage map[string]string, qualifiedFieldName string) {
 	if field == nil || len(field.Names) == 0 {
 		return
 	}
 
 	markerSet := markersAccess.FieldMarkers(field)
 	check(markerSet, equivalentToPreferred, func(marks []markers.Marker, preferredIdentifier string, preferredExists bool) {
-		reportMarkers(pass, marks, preferredIdentifier, qualifiedFieldName, field.Pos(), "field", preferredExists)
+		reportMarkers(pass, marks, preferredIdentifier, preferredToMessage[preferredIdentifier], qualifiedFieldName, field.Pos(), "field", preferredExists)
 	})
 }
 
 // checkType validates a single type definition for marker usage.
-func checkType(pass *analysis.Pass, typeSpec *ast.TypeSpec, markersAccess markers.Markers, equivalentToPreferred map[string]string) {
+func checkType(pass *analysis.Pass, typeSpec *ast.TypeSpec, markersAccess markers.Markers, equivalentToPreferred, preferredToMessage map[string]string) {
 	if typeSpec == nil {
 		return
 	}
 
 	markerSet := markersAccess.TypeMarkers(typeSpec)
 	check(markerSet, equivalentToPreferred, func(marks []markers.Marker, preferredIdentifier string, preferredExists bool) {
-		reportMarkers(pass, marks, preferredIdentifier, typeSpec.Name.Name, typeSpec.Pos(), "type", preferredExists)
+		reportMarkers(pass, marks, preferredIdentifier, preferredToMessage[preferredIdentifier], typeSpec.Name.Name, typeSpec.Pos(), "type", preferredExists)
 	})
 }
 
@@ -193,7 +202,7 @@ func buildTextEdits(marks []markers.Marker, preferredIdentifier string, preferre
 // reportMarkers generates a diagnostic report for markers that should be
 // replaced. This function handles the common logic for both field and type
 // reporting.
-func reportMarkers(pass *analysis.Pass, marks []markers.Marker, preferredIdentifier, elementName string, pos token.Pos, elementType string, preferredExists bool) {
+func reportMarkers(pass *analysis.Pass, marks []markers.Marker, preferredIdentifier, customMessage, elementName string, pos token.Pos, elementType string, preferredExists bool) {
 	if len(marks) == 0 {
 		return
 	}
@@ -206,6 +215,10 @@ func reportMarkers(pass *analysis.Pass, marks []markers.Marker, preferredIdentif
 	message := fmt.Sprintf("%s %s uses %s %s, should use preferred marker %q instead",
 		elementType, elementName, markerWord, formatMarkerList(marks), preferredIdentifier)
 
+	if customMessage != "" {
+		message += fmt.Sprintf(": %s", customMessage)
+	}
+
 	fixMessage := "remove equivalent markers"
 	if !preferredExists {
 		fixMessage = fmt.Sprintf("replace with %q", preferredIdentifier)

pkg/analysis/preferredmarkers/analyzer_test.go

@@ -48,3 +48,18 @@ func TestWithConfiguration(t *testing.T) {
 		},
 	}), "a/...")
 }
+
+func TestWithCustomMessage(t *testing.T) {
+	testdata := analysistest.TestData()
+	analysistest.RunWithSuggestedFixes(t, testdata, newAnalyzer(&Config{
+		Markers: []Marker{
+			{
+				PreferredIdentifier: "k8s:optional",
+				EquivalentIdentifiers: []EquivalentIdentifier{
+					{Identifier: "kubebuilder:validation:Optional"},
+				},
+				Message: "custom message for k8s:optional",
+			},
+		},
+	}), "b/...")
+}

pkg/analysis/preferredmarkers/config.go

@@ -39,6 +39,10 @@ type Marker struct {
 	// preferred identifier.
 	// Must have at least one entry.
 	EquivalentIdentifiers []EquivalentIdentifier `json:"equivalentIdentifiers"`
+
+	// message is an explanation of why the preferred identifier should be used.
+	// If not provided, a default message will be used.
+	Message string `json:"message,omitempty"`
 }
 
 // EquivalentIdentifier represents a marker identifier that should be

pkg/analysis/preferredmarkers/doc.go

@@ -43,6 +43,7 @@ limitations under the License.
 *       - preferredIdentifier: "k8s:optional"
 *         equivalentIdentifiers:
 *           - "kubebuilder:validation:Optional"
+*         message: "Use k8s:optional to ensure consistency with upstream Kubernetes types."
 * ```
 *
 * **Scenario:** Enforce using a custom marker instead of multiple equivalent markers

pkg/analysis/preferredmarkers/testdata/src/b/b.go

@@ -0,0 +1,6 @@
+package b
+
+type CustomMessage struct {
+	// +kubebuilder:validation:Optional
+	Field string // want "field CustomMessage.Field uses marker \"kubebuilder:validation:Optional\", should use preferred marker \"k8s:optional\" instead: custom message for k8s:optional"
+}

pkg/analysis/preferredmarkers/testdata/src/b/b.go.golden

@@ -0,0 +1,6 @@
+package b
+
+type CustomMessage struct {
+	// +k8s:optional
+	Field string // want "field CustomMessage.Field uses marker \"kubebuilder:validation:Optional\", should use preferred marker \"k8s:optional\" instead: custom message for k8s:optional"
+}