Add notimestamp linter

Author: Karthik-K-N

docs/linters.md

@@ -10,6 +10,7 @@
 - [NoFloats](#nofloats) - Prevents usage of floating-point types
 - [Nomaps](#nomaps) - Restricts usage of map types
 - [Nophase](#nophase) - Prevents usage of 'Phase' fields
+- [Notimestamp](#Notimestamp) - Prevents usage of `TimeStamp` fields
 - [OptionalFields](#optionalfields) - Validates optional field conventions
 - [OptionalOrRequired](#optionalorrequired) - Ensures fields are explicitly marked as optional or required
 - [RequiredFields](#requiredfields) - Validates required field conventions
@@ -151,6 +152,10 @@ The `nomaps` linter checks the usage of map types.
 
 Maps are discouraged apart from `map[string]string` which is used for labels and annotations in Kubernetes APIs since it's hard to distinguish between structs and maps in spec. Instead of plain map, lists of named subobjects are preferred.
 
+## Notimestamp
+
+The `notimestamp` linter checks that the fields in the API types don't contain a 'Timestamp', or any field which contains 'Timestamp' as a substring, e.g CreateTimestamp.
+
 ### Configuration
 
 ```yaml

pkg/analysis/notimestamp/analyzer.go

@@ -0,0 +1,97 @@
+/*
+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 notimestamp
+
+import (
+	"go/ast"
+	"strings"
+
+	"golang.org/x/tools/go/analysis"
+	"golang.org/x/tools/go/analysis/passes/inspect"
+	"golang.org/x/tools/go/ast/inspector"
+	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/utils"
+)
+
+const name = "notimestamp"
+
+// Analyzer is the analyzer for the notimestamp package.
+// It checks that no struct fields named 'timestamp', or that contain timestamp as a
+// substring are present.
+var Analyzer = &analysis.Analyzer{
+	Name:     name,
+	Doc:      "check that non of the struct field named timestamp or contain timestamp as a substring",
+	Run:      run,
+	Requires: []*analysis.Analyzer{inspect.Analyzer, extractjsontags.Analyzer},
+}
+
+func run(pass *analysis.Pass) (any, error) {
+	inspect, ok := pass.ResultOf[inspect.Analyzer].(*inspector.Inspector)
+	if !ok {
+		return nil, kalerrors.ErrCouldNotGetInspector
+	}
+
+	jsonTags, ok := pass.ResultOf[extractjsontags.Analyzer].(extractjsontags.StructFieldTags)
+	if !ok {
+		return nil, kalerrors.ErrCouldNotGetJSONTags
+	}
+
+	// Filter to fields so that we can iterate over fields in a struct.
+	nodeFilter := []ast.Node{
+		(*ast.Field)(nil),
+	}
+
+	// Preorder visits all the nodes of the AST in depth-first order. It calls
+	// f(n) for each node n before it visits n's children.
+	//
+	// We use the filter defined above, ensuring we only look at struct fields.
+	inspect.Preorder(nodeFilter, func(n ast.Node) {
+		field, ok := n.(*ast.Field)
+		if !ok {
+			return
+		}
+
+		if field == nil || len(field.Names) == 0 {
+			return
+		}
+
+		fieldName := utils.FieldName(field)
+
+		// First check if the struct field name contains 'timestamp'
+		if strings.Contains(strings.ToLower(fieldName), "timestamp") {
+			pass.Reportf(field.Pos(),
+				"field %s: fields with timestamp substring should be avoided",
+				fieldName,
+			)
+
+			return
+		}
+
+		// Then check if the json serialization of the field contains 'timestamp'
+		tagInfo := jsonTags.FieldTags(field)
+
+		if strings.Contains(strings.ToLower(tagInfo.Name), "timestamp") {
+			pass.Reportf(field.Pos(),
+				"field %s: fields with timestamp substring should be avoided",
+				fieldName,
+			)
+		}
+	})
+
+	return nil, nil //nolint:nilnil
+}

pkg/analysis/notimestamp/analyzer_test.go

@@ -0,0 +1,29 @@
+/*
+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 notimestamp_test
+
+import (
+	"sigs.k8s.io/kube-api-linter/pkg/analysis/notimestamp"
+	"testing"
+
+	"golang.org/x/tools/go/analysis/analysistest"
+)
+
+func Test(t *testing.T) {
+	testdata := analysistest.TestData()
+	analysistest.RunWithSuggestedFixes(t, testdata, notimestamp.Analyzer, "a")
+}

pkg/analysis/notimestamp/doc.go

@@ -0,0 +1,24 @@
+/*
+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.
+*/
+
+/*
+notimestamp provides a linter to ensure that structs do not contain a TimeStamp field.
+
+The linter will flag any struct field containing the substring 'timestamp'. This means both
+TimeStamp and FooTimeStamp will be flagged.
+*/
+
+package notimestamp

pkg/analysis/notimestamp/initializer.go

@@ -0,0 +1,46 @@
+/*
+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 notimestamp
+
+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{}
+}
+
+// intializer implements the AnalyzerInitializer interface.
+type initializer struct{}
+
+// Name returns the name of the Analyzer.
+func (initializer) Name() string {
+	return name
+}
+
+// Init returns the intialized Analyzer.
+func (initializer) Init(cfg config.LintersConfig) (*analysis.Analyzer, error) {
+	return Analyzer, nil
+}
+
+// Default determines whether this Analyzer is on by default, or not.
+func (initializer) Default() bool {
+	return true
+}

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

@@ -0,0 +1,22 @@
+package a
+
+import "time"
+
+type NoTimeStampTestStruct struct {
+	// +optional
+	TimeStamp *time.Time `json:"timeStamp,omitempty"` // want "field TimeStamp: fields with timestamp substring should be avoided"
+}
+
+// DoNothing is used to check that the analyser doesn't report on methods.
+func (NoTimeStampTestStruct) DoNothing() {}
+
+type NoSubTimeStampTestStruct struct {
+	// +optional
+	FooTimeStamp *time.Time `json:"fooTimeStamp,omitempty"` // want "field FooTimeStamp: fields with timestamp substring should be avoided"
+
+}
+
+type SerializedTimeStampTestStruct struct {
+	// +optional
+	FooTime *time.Time `json:"fooTime,omitempty"`
+}

pkg/analysis/registry.go

@@ -29,6 +29,7 @@ import (
 	"sigs.k8s.io/kube-api-linter/pkg/analysis/nofloats"
 	"sigs.k8s.io/kube-api-linter/pkg/analysis/nomaps"
 	"sigs.k8s.io/kube-api-linter/pkg/analysis/nophase"
+	"sigs.k8s.io/kube-api-linter/pkg/analysis/notimestamp"
 	"sigs.k8s.io/kube-api-linter/pkg/analysis/optionalfields"
 	"sigs.k8s.io/kube-api-linter/pkg/analysis/optionalorrequired"
 	"sigs.k8s.io/kube-api-linter/pkg/analysis/requiredfields"
@@ -86,6 +87,7 @@ func NewRegistry() Registry {
 			nofloats.Initializer(),
 			nomaps.Initializer(),
 			nophase.Initializer(),
+			notimestamp.Initializer(),
 			optionalfields.Initializer(),
 			optionalorrequired.Initializer(),
 			requiredfields.Initializer(),

pkg/analysis/registry_test.go

@@ -39,6 +39,7 @@ var _ = Describe("Registry", func() {
 				"nofloats",
 				"nomaps",
 				"nophase",
+				"notimestamp",
 				"optionalfields",
 				"optionalorrequired",
 				"requiredfields",
@@ -62,6 +63,7 @@ var _ = Describe("Registry", func() {
 				"nofloats",
 				"nomaps",
 				"nophase",
+				"notimestamp",
 				"optionalfields",
 				"optionalorrequired",
 				"requiredfields",