Merge pull request #69 from JoelSpeed/optionalfields

Introduce optionalfields linter

Author: k8s-ci-robot

README.md

@@ -279,6 +279,42 @@ lintersConfig:
 
 The `nophase` linter checks that the fields in the API types don't contain a 'Phase', or any field which contains 'Phase' as a substring, e.g MachinePhase.
 
+## OptionalFields
+
+The `optionalfields` linter checks that all fields marked as optional adhere to being pointers and having the `omitempty` value in their `json` tag where appropriate.
+
+If you prefer to avoid pointers where possible, the linter can be configured with the `WhenRequired` preference to determine, based on the serialization and valid values for the field, whether the field should be a pointer or not.
+For example, an optional string with a non-zero minimum length does not need to be a pointer, as the zero value is not valid, and it is safe for the Go marshaller to omit the empty value.
+
+In certain use cases, it can be desirable to not omit optional fields from the serialized form of the object.
+In this case, the `omitempty` policy can be set to `Ignore`, and the linter will ensure that the zero value of the object is an acceptable value for the field.
+
+### Configuration
+
+```yaml
+lintersConfig:
+  optionalFields:
+    pointers:
+      preference: Always | WhenRequired # Whether to always require pointers, or only when required. Defaults to `Always`.
+      policy: SuggestFix | Warn # The policy for pointers in optional fields. Defaults to `SuggestFix`.
+    omitempty:
+        policy: SuggestFix | Warn | Ignore # The policy for omitempty in optional fields. Defaults to `SuggestFix`.
+```
+
+### Fixes
+
+The `optionalfields` linter can automatically fix fields that are marked as optional, that are either not pointers or do not have the `omitempty` value in their `json` tag.
+It will suggest to add the pointer to the field, and update the `json` tag to include the `omitempty` value.
+
+If you prefer not to suggest fixes for pointers in optional fields, you can change the `pointers.policy` to `Warn`.
+
+If you prefer not to suggest fixes for `omitempty` in optional fields, you can change the `omitempty.policy` to `Warn` or `Ignore`.
+
+When the `pointers.preference` is set to `WhenRequired`, the linter will suggest to add the pointer to the field only when the field zero value is a valid value for the field.
+When the field zero value is not a valid value for the field, the linter will suggest to remove the pointer from the field.
+
+When the `pointers.preference` is set to `Always`, the linter will always suggest to add the pointer to the field, regardless of the validity of the zero value of the field.
+
 ## OptionalOrRequired
 
 The `optionalorrequired` linter checks that all fields in the API types are either optional or required, and are marked explicitly as such.

go.mod

@@ -8,6 +8,7 @@ require (
 	github.com/onsi/gomega v1.36.3
 	golang.org/x/tools v0.32.0
 	k8s.io/apimachinery v0.32.3
+	k8s.io/utils v0.0.0-20241104100929-3ea5e8cea738
 )
 
 require (

go.sum

@@ -51,3 +51,5 @@ gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 k8s.io/apimachinery v0.32.3 h1:JmDuDarhDmA/Li7j3aPrwhpNBA94Nvk5zLeOge9HH1U=
 k8s.io/apimachinery v0.32.3/go.mod h1:GpHVgxoKlTxClKcteaeuF1Ul/lDVb74KpZcxcmLDElE=
+k8s.io/utils v0.0.0-20241104100929-3ea5e8cea738 h1:M3sRQVHv7vB20Xc2ybTt7ODCeFj6JSWYFzOFnYeS6Ro=
+k8s.io/utils v0.0.0-20241104100929-3ea5e8cea738/go.mod h1:OLgZIPagt7ERELqWJFomSt595RzquPNLL48iOWgYOg0=

pkg/analysis/helpers/markers/analyzer.go

@@ -385,6 +385,13 @@ func (ms MarkerSet) HasWithExpressions(identifier string, expressions map[string
 	return false
 }
 
+// Get returns the markers associated with the given identifier.
+// If no markers are found, an empty slice is returned.
+// The returned slice may contain multiple markers with the same identifier.
+func (ms MarkerSet) Get(identifier string) []Marker {
+	return ms[identifier]
+}
+
 // UnsortedList returns a list of the markers, in no particular order.
 func (ms MarkerSet) UnsortedList() []Marker {
 	markers := []Marker{}