Add statusoptional linter

This commit introduces a new linter, `statusoptional`, which checks that all first-level children fields within a status struct are marked as optional. It adds functionality to automatically suggest fixes for fields that are missing the appropriate markers.

Author: yongruilin

README.md

@@ -279,6 +279,20 @@ It will suggest to remove the pointer from the field, and update the `json` tag
 If you prefer not to suggest fixes for pointers in required fields, you can change the `pointerPolicy` to `Warn`.
 The linter will then only suggest to remove the `omitempty` value from the `json` tag.
 
+## StatusOptional
+
+The `statusoptional` linter checks that all first-level children fields within a status struct are marked as optional.
+
+This is important because status fields should be optional to allow for partial updates and backward compatibility.
+The linter ensures that all direct child fields of any status struct have either the `// +optional` or 
+`// +kubebuilder:validation:Optional` marker.
+
+### Fixes
+
+The `statusoptional` linter can automatically fix fields in status structs that are not marked as optional.
+
+It will suggest adding the `// +optional` marker to any status field that is missing it.
+
 ## StatusSubresource
 
 The `statussubresource` linter checks that the status subresource is configured correctly for

pkg/analysis/registry.go

@@ -30,6 +30,7 @@ import (
 	"sigs.k8s.io/kube-api-linter/pkg/analysis/nophase"
 	"sigs.k8s.io/kube-api-linter/pkg/analysis/optionalorrequired"
 	"sigs.k8s.io/kube-api-linter/pkg/analysis/requiredfields"
+	"sigs.k8s.io/kube-api-linter/pkg/analysis/statusoptional"
 	"sigs.k8s.io/kube-api-linter/pkg/analysis/statussubresource"
 	"sigs.k8s.io/kube-api-linter/pkg/config"
 
@@ -83,6 +84,7 @@ func NewRegistry() Registry {
 			nophase.Initializer(),
 			optionalorrequired.Initializer(),
 			requiredfields.Initializer(),
+			statusoptional.Initializer(),
 			statussubresource.Initializer(),
 		},
 	}

pkg/analysis/registry_test.go

@@ -40,6 +40,7 @@ var _ = Describe("Registry", func() {
 				"nophase",
 				"optionalorrequired",
 				"requiredfields",
+				"statusoptional",
 			))
 		})
 	})
@@ -59,6 +60,7 @@ var _ = Describe("Registry", func() {
 				"nophase",
 				"optionalorrequired",
 				"requiredfields",
+				"statusoptional",
 				"statussubresource",
 			))
 		})

pkg/analysis/statusoptional/analyzer.go

@@ -0,0 +1,140 @@
+/*
+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 statusoptional
+
+import (
+	"fmt"
+	"go/ast"
+	"go/token"
+
+	"golang.org/x/tools/go/analysis"
+
+	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"
+)
+
+const (
+	name = "statusoptional"
+
+	statusJSONTag = "status"
+
+	// OptionalMarker is the marker that indicates that a field is optional.
+	OptionalMarker = "optional"
+
+	// KubebuilderOptionalMarker is the marker that indicates that a field is optional in kubebuilder.
+	KubebuilderOptionalMarker = "kubebuilder:validation:Optional"
+)
+
+func init() {
+	markers.DefaultRegistry().Register(
+		OptionalMarker,
+		KubebuilderOptionalMarker,
+	)
+}
+
+type analyzer struct{}
+
+// newAnalyzer creates a new analyzer.
+func newAnalyzer() *analysis.Analyzer {
+	a := &analyzer{}
+
+	return &analysis.Analyzer{
+		Name:     name,
+		Doc:      "Checks that all first-level children fields within status struct are marked as optional",
+		Run:      a.run,
+		Requires: []*analysis.Analyzer{inspector.Analyzer},
+	}
+}
+
+func (a *analyzer) run(pass *analysis.Pass) (interface{}, error) {
+	inspect, ok := pass.ResultOf[inspector.Analyzer].(inspector.Inspector)
+	if !ok {
+		return nil, kalerrors.ErrCouldNotGetInspector
+	}
+
+	inspect.InspectFields(func(field *ast.Field, stack []ast.Node, jsonTagInfo extractjsontags.FieldTagInfo, markersAccess markers.Markers) {
+		if jsonTagInfo.Name != statusJSONTag {
+			return
+		}
+
+		ident, ok := field.Type.(*ast.Ident)
+		if !ok {
+			return
+		}
+
+		tSpec, ok := ident.Obj.Decl.(*ast.TypeSpec)
+		if !ok {
+			return
+		}
+
+		statusType, ok := tSpec.Type.(*ast.StructType)
+		if !ok {
+			return
+		}
+
+		a.checkStatusStruct(pass, statusType, markersAccess)
+	})
+
+	return nil, nil //nolint:nilnil
+}
+
+func (a *analyzer) checkStatusStruct(pass *analysis.Pass, statusType *ast.StructType, markersAccess markers.Markers) {
+	if statusType.Fields == nil || statusType.Fields.List == nil {
+		return
+	}
+
+	// Check each child field of the status struct
+	for _, childField := range statusType.Fields.List {
+		var fieldName string
+
+		if len(childField.Names) == 0 {
+			switch t := childField.Type.(type) {
+			case *ast.Ident:
+				fieldName = t.Name
+			default:
+				continue
+			}
+		} else {
+			fieldName = childField.Names[0].Name
+		}
+
+		fieldMarkers := markersAccess.FieldMarkers(childField)
+
+		// Check if the field has either the optional or kubebuilder:validation:Optional marker
+		if !fieldMarkers.Has(OptionalMarker) && !fieldMarkers.Has(KubebuilderOptionalMarker) {
+			// Report the error and suggest a fix to add the optional marker
+			pass.Report(analysis.Diagnostic{
+				Pos:     childField.Pos(),
+				Message: fmt.Sprintf("status field %q must be marked as optional", fieldName),
+				SuggestedFixes: []analysis.SuggestedFix{
+					{
+						Message: "add the optional marker",
+						TextEdits: []analysis.TextEdit{
+							{
+								// Position at the beginning of the line of the field
+								Pos: childField.Pos() - token.Pos(len(fieldName)),
+								// Insert the marker before the field
+								NewText: []byte("// +optional\n\t"),
+							},
+						},
+					},
+				},
+			})
+		}
+	}
+}

pkg/analysis/statusoptional/analyzer_test.go

@@ -0,0 +1,27 @@
+/*
+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 statusoptional
+
+import (
+	"testing"
+
+	"golang.org/x/tools/go/analysis/analysistest"
+)
+
+func Test(t *testing.T) {
+	testdata := analysistest.TestData()
+	analysistest.Run(t, testdata, newAnalyzer(), "a")
+}

pkg/analysis/statusoptional/doc.go

@@ -0,0 +1,32 @@
+/*
+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 statusoptional
+
+/*
+The statusoptional linter ensures that all first-level children fields within a status struct
+are marked as optional.
+
+This is important because status fields should be optional to allow for partial updates
+and backward compatibility.
+
+This linter checks:
+1. For structs with a JSON tag of "status"
+2. All direct child fields of the status struct
+3. Ensures each child field has an optional marker
+
+The linter will report an issue if any field in the status struct is not marked as optional
+and will suggest a fix to add the appropriate optional marker.
+*/

pkg/analysis/statusoptional/initializer.go

@@ -0,0 +1,47 @@
+/*
+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 statusoptional
+
+import (
+	"golang.org/x/tools/go/analysis"
+
+	"sigs.k8s.io/kube-api-linter/pkg/config"
+)
+
+// Initializer returns the AnalyzerInitializer for this
+// Analyzer so that it can be added to the registry.
+func Initializer() initializer {
+	return initializer{}
+}
+
+// initializer implements the AnalyzerInitializer interface.
+type initializer struct{}
+
+// Name returns the name of the Analyzer.
+func (initializer) Name() string {
+	return name
+}
+
+// Init returns the initialized Analyzer.
+func (initializer) Init(cfg config.LintersConfig) (*analysis.Analyzer, error) {
+	// Currently no configuration is needed for this linter
+	return newAnalyzer(), nil
+}
+
+// Default determines whether this Analyzer is on by default, or not.
+func (initializer) Default() bool {
+	return true
+}

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

@@ -0,0 +1,62 @@
+/*
+This file contains test cases for the statusoptional linter.
+*/
+package a
+
+// MyResource is a sample resource with a status field containing not optional fields.
+type MyResource struct {
+	// +optional
+	Spec MyResourceSpec `json:"spec"`
+
+	Status MyResourceStatus `json:"status"`
+}
+
+// MyResourceSpec is a sample spec.
+type MyResourceSpec struct {
+	// +optional
+	Foo string `json:"foo"`
+}
+
+// MyResourceStatus is a sample status with a mix of optional and non-optional fields.
+type MyResourceStatus struct {
+	// This field is not marked as optional and should trigger a warning.
+	Phase string `json:"phase"` // want "status field \"Phase\" must be marked as optional"
+
+	// +optional
+	Conditions []string `json:"conditions"`
+
+	// This field is not marked as optional and should trigger a warning.
+	Message string `json:"message"` // want "status field \"Message\" must be marked as optional"
+
+	// +kubebuilder:validation:Optional
+	Reason string `json:"reason"`
+
+	State // want "status field \"State\" must be marked as optional"
+}
+
+type State struct {
+	Ready bool `json:"ready"`
+}
+
+// CompliantResource is a sample resource with all status fields marked as optional.
+type CompliantResource struct {
+	// +optional
+	Spec MyResourceSpec `json:"spec"`
+
+	Status CompliantStatus `json:"status"`
+}
+
+// CompliantStatus has all fields properly marked as optional.
+type CompliantStatus struct {
+	// +optional
+	Phase string `json:"phase"`
+
+	// +optional
+	Conditions []string `json:"conditions"`
+
+	// +optional
+	Message string `json:"message"`
+
+	// +kubebuilder:validation:Optional
+	Reason string `json:"reason"`
+}