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,181 @@
+/*
+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"
+
+	"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 {
+		fieldName := a.getFieldName(childField)
+		if fieldName == "" {
+			continue
+		}
+
+		// Check if the field has the required optional markers
+		a.checkFieldForOptionalMarker(pass, childField, fieldName, markersAccess)
+
+		// Check embedded structs recursively
+		a.checkEmbeddedStruct(pass, childField, markersAccess)
+	}
+}
+
+// getFieldName extracts the field name from an AST field
+// TODO: move it to utils package.
+func (a *analyzer) getFieldName(field *ast.Field) string {
+	if len(field.Names) > 0 {
+		return field.Names[0].Name
+	}
+
+	// For embedded fields
+	if ident, ok := field.Type.(*ast.Ident); ok {
+		return ident.Name
+	}
+
+	return ""
+}
+
+// checkFieldForOptionalMarker checks if a field has the required optional markers.
+func (a *analyzer) checkFieldForOptionalMarker(pass *analysis.Pass, field *ast.Field, fieldName string, markersAccess markers.Markers) {
+	fieldMarkers := markersAccess.FieldMarkers(field)
+
+	// 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:     field.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: field.Pos(),
+							// Insert the marker before the field
+							NewText: []byte("// +optional\n"),
+						},
+					},
+				},
+			},
+		})
+	}
+}
+
+// checkEmbeddedStruct checks if a field is an embedded struct and if so,
+// recursively checks its children fields.
+func (a *analyzer) checkEmbeddedStruct(pass *analysis.Pass, field *ast.Field, markersAccess markers.Markers) {
+	// Only embedded fields have no names
+	if len(field.Names) > 0 {
+		return
+	}
+
+	ident, ok := field.Type.(*ast.Ident)
+	if !ok {
+		return
+	}
+
+	typeSpec, ok := ident.Obj.Decl.(*ast.TypeSpec)
+	if !ok {
+		return
+	}
+
+	embeddedStruct, ok := typeSpec.Type.(*ast.StructType)
+	if !ok {
+		return
+	}
+
+	a.checkStatusStruct(pass, embeddedStruct, markersAccess)
+}

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.RunWithSuggestedFixes(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.
+*/
+
+/*
+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.
+*/
+package statusoptional

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
+}