Add `preferredmarkers` linter #172

saschagrunert · 2025-10-30T08:58:17Z

Add a new linter that allows projects to enforce using preferred markers instead of equivalent but different marker identifiers.

Marker preferences are configurable
Auto-fix support
Maintains marker expressions (e.g., :=value, :key=value) during replacement
When multiple equivalent markers exist on the same field/type, consolidates them into a single preferred marker
Handles markers inherited from type aliases
Sorted processing ensures consistent, reproducible results

The linter is disabled by default and requires explicit configuration to enable.

Fixes #139

k8s-ci-robot · 2025-10-30T08:58:23Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: saschagrunert
Once this PR has been reviewed and has the lgtm label, please assign jpbetz for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Needs approval from an approver in each of these files:

OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

Introduce a new configurable linter that enforces consistent marker usage across codebases by ensuring preferred marker identifiers are used instead of equivalent alternatives. Key Features: - Configurable marker preferences with multiple equivalent identifiers - Auto-fix support with expression preservation - Smart duplicate handling (consolidates multiple equivalents) - Type-aware checking (handles markers inherited from type aliases) - Deterministic output with sorted processing - Comprehensive configuration validation Signed-off-by: Sascha Grunert <sgrunert@redhat.com>

JoelSpeed · 2025-10-30T17:02:08Z

docs/linters.md

+- `+k8s:optional`
+- `+kubebuilder:validation:Optional`


Suggested change

- `+k8s:optional`

- `+kubebuilder:validation:Optional`

- `+optional`

- `+k8s:optional`

- `+kubebuilder:validation:Optional`

JoelSpeed · 2025-10-30T17:03:58Z

docs/linters.md

+    markers:
+      - preferredIdentifier: "custom:preferred"
+        equivalentIdentifiers:
+          - "custom:old:marker"


If I had a value for the marker, how would the value be translated? For example, if we switch from +kubebuilder:validation:MaxLength:=3 to +k8s:maxLength:=3, is that handled?

What about something more complex like XValidation that has multiple arguments?

Reading further on, these are preserved verbatim.

If in the future we wanted to remap, is the current config extensible in any way? Possibly not.

I'm expecting a future where (and this is somewhat OpenShift specific), we want to remap

+openshift:validation:featureGate=ABC --> +k8s:ifEnabled(FeatureGate=ABC)

Perhaps we want to make the equivalentIdentifiers a list of objects so that we can expand with a mapping option later?

JoelSpeed · 2025-10-30T17:12:25Z

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

+	OptionalFieldKubebuilder string `json:"optionalFieldKubebuilder"` // want `field OptionalFieldKubebuilder uses marker "kubebuilder:validation:Optional", should use preferred marker "k8s:optional" instead`
+
+	// Inherited from type alias
+	OptionalFieldKubebuilderTypeAlias OptionalTypeKubebuilder `json:"optionalFieldKubebuilderTypeAlias"` // want `field OptionalFieldKubebuilderTypeAlias uses marker "kubebuilder:validation:Optional", should use preferred marker "k8s:optional" instead`


Given this will be reported at the type level, is it beneficial for it to be reported here again?

JoelSpeed · 2025-10-30T17:18:24Z

pkg/analysis/preferredmarkers/initializer_test.go

+				Expect(errs).To(HaveLen(0), "No errors were expected")
+			}
+		},
+			Entry("With a valid preferredmarkers configuration", testCase{


Do we have a case that checks the preferred identifier is not in the list of equivalent identifiers? So we wouldn't create a loop of trying to replace an identifier with itself

JoelSpeed · 2025-10-30T17:20:59Z

pkg/analysis/preferredmarkers/config.go

+// Config is the configuration type
+// for the preferredmarkers linter.
+type Config struct {
+	// Markers is the unique set of preferred markers


We follow the conventions of lowercase first word on the godoc on these config types

Suggested change

// Markers is the unique set of preferred markers

// markers is the unique set of preferred markers

JoelSpeed · 2025-10-30T17:23:32Z

pkg/analysis/preferredmarkers/analyzer.go

+		return
+	}
+
+	markerSet := utils.TypeAwareMarkerCollectionForField(pass, markersAccess, field)


I suspect this is going to cause confusion since we are inspecting the types separately

JoelSpeed · 2025-10-30T17:27:25Z

pkg/analysis/preferredmarkers/analyzer.go

+
+	// Check for unnamed expression (simple case like "+marker:=value")
+	if unnamedValue, ok := expressions[markers.UnnamedExpression]; ok {
+		return ":=" + unnamedValue


I don't think := is universally compatible, just use =.

Kubebuilder supports :=, but to my knowledge, the +k8s markers do not

JoelSpeed · 2025-10-30T17:28:28Z

pkg/analysis/preferredmarkers/analyzer.go

+// preferred identifier while preserving any expressions from the original
+// marker.
+func buildReplacementMarker(marker markers.Marker, preferredIdentifier string) string {
+	return "// +" + preferredIdentifier + formatExpressions(marker.Expressions)


@everettraven can you PTAL at this given your context with the DV parsing, is this likely to break/change?

JoelSpeed · 2025-10-30T17:29:04Z

pkg/analysis/preferredmarkers/testdata/src/a/eof.go

+
+// Type at end of file without trailing newline
+// +kubebuilder:validation:Optional
+type EndOfFileType string // want `type EndOfFileType uses marker "kubebuilder:validation:Optional", should use preferred marker "k8s:optional" instead`


Is this important to test? The change isn't actually at the end of the file, it's on line 4?

How did you come across this issue to want to test EOF?

k8s-ci-robot added the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Oct 30, 2025

saschagrunert marked this pull request as ready for review October 30, 2025 08:58

k8s-ci-robot requested review from everettraven and jpbetz October 30, 2025 08:58

k8s-ci-robot added the cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. label Oct 30, 2025

k8s-ci-robot requested a review from sivchari October 30, 2025 08:58

k8s-ci-robot added the size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. label Oct 30, 2025

saschagrunert force-pushed the add-preferredmarkers-linter branch 6 times, most recently from 8b3ad22 to c13e1ee Compare October 30, 2025 09:43

saschagrunert force-pushed the add-preferredmarkers-linter branch from c13e1ee to c004f0d Compare October 30, 2025 09:44

saschagrunert changed the title ~~WIP: Add preferredmarkers linter~~ Add preferredmarkers linter Oct 30, 2025

k8s-ci-robot removed the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Oct 30, 2025

JoelSpeed reviewed Oct 30, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add `preferredmarkers` linter #172

Add `preferredmarkers` linter #172

Uh oh!

saschagrunert commented Oct 30, 2025 •

edited

Loading

Uh oh!

k8s-ci-robot commented Oct 30, 2025

Uh oh!

JoelSpeed Oct 30, 2025

Uh oh!

JoelSpeed Oct 30, 2025

Uh oh!

JoelSpeed Oct 30, 2025

Uh oh!

JoelSpeed Oct 30, 2025

Uh oh!

JoelSpeed Oct 30, 2025

Uh oh!

JoelSpeed Oct 30, 2025

Uh oh!

JoelSpeed Oct 30, 2025

Uh oh!

JoelSpeed Oct 30, 2025

Uh oh!

JoelSpeed Oct 30, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	// Markers is the unique set of preferred markers
	// markers is the unique set of preferred markers

Add preferredmarkers linter #172

Are you sure you want to change the base?

Add preferredmarkers linter #172

Uh oh!

Conversation

saschagrunert commented Oct 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

k8s-ci-robot commented Oct 30, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Add `preferredmarkers` linter #172

Add `preferredmarkers` linter #172

saschagrunert commented Oct 30, 2025 •

edited

Loading