Merge pull request #106 from everettraven/linter/fieldnaming

linter: add `namingconventions` linter

Author: k8s-ci-robot

docs/linters.md

@@ -8,6 +8,7 @@
 - [Integers](#integers) - Validates usage of supported integer types
 - [JSONTags](#jsontags) - Ensures proper JSON tag formatting
 - [MaxLength](#maxlength) - Checks for maximum length constraints on strings and arrays
+- [NamingConventions](#namingconventions) - Ensures field names adhere to user-defined naming conventions
 - [NoBools](#nobools) - Prevents usage of boolean types
 - [NoDurations](#nodurations) - Prevents usage of duration types
 - [NoFloats](#nofloats) - Prevents usage of floating-point types
@@ -302,6 +303,86 @@ or `+kubebuilder:validation:items:MaxLenth` if the array is an element of the bu
 Adding maximum lengths to strings and arrays not only ensures that the API is not abused (used to store overly large data, reduces DDOS etc.),
 but also allows CEL validation cost estimations to be kept within reasonable bounds.
 
+## NamingConventions
+
+The `namingconventions` linter ensures that field names adhere to a set of defined naming conventions.
+
+By default, `namingconventions` is not enabled.
+
+When enabled, it must be configured with at least one naming convention.
+
+### Configuration
+
+Naming conventions must have:
+- A unique human-readable name.
+- A human-readable message to be included in violation errors.
+- A regular expression that will match text within the field name that violates the convention.
+- A defined "operation". Allowed operations are `Inform`, `Drop`, `DropField`, and `Replace`.
+
+The `Inform` operation will simply inform when a field name violates the naming convention.
+The `Drop` operation will suggest a fix that drops violating text from the field name.
+The `DropField` operation will suggest a fix that removes the field in it's entirety.
+The `Replace` operation will suggest a fix that replaces the violating text in the field name with a defined replacement value.
+
+High-level configuration overview:
+```yaml
+linterConfig:
+  namingconventions:
+    conventions: 
+      - name: {human readable string} # must be unique
+        violationMatcher: {regular expression}
+        operation: Inform | Drop | DropField | Replace
+        replace: { replacement string } # required when operation is 'Replace', forbidden otherwise
+        message: {human readable string}
+```
+
+Some example configurations:
+
+**Scenario:** Inform that any variations of the word 'fruit' in field names is not allowed
+```yaml
+linterConfig:
+  namingconventions:
+    conventions: 
+      - name: nofruit
+        violationMatcher: (?i)fruit
+        operation: Inform
+        message: fields should not contain any variation of the word 'fruit' in their names
+```
+
+**Scenario:** Drop any variations of the word 'fruit' in field names
+```yaml
+linterConfig:
+  namingconventions:
+    conventions: 
+      - name: nofruit
+        violationMatcher: (?i)fruit
+        operation: Drop
+        message: fields should not contain any variation of the word 'fruit' in their names
+```
+
+**Scenario:** Do not allow fields with any variations of the word 'fruit' in their name
+```yaml
+linterConfig:
+  namingconventions:
+    conventions: 
+      - name: nofruit
+        violationMatcher: (?i)fruit
+        operation: DropField
+        message: fields should not contain any variation of the word 'fruit' in their names
+```
+
+**Scenario:** Replace any variations of the word 'color' with 'colour' in field names
+```yaml
+linterConfig:
+  namingconventions:
+    conventions:
+      - name: BritishEnglishColour 
+        violationMatcher: (?i)color
+        operation: Replace
+        replace: colour
+        message: prefer 'colour' over 'color' when referring to colours in field names
+```
+
 ## NoBools
 
 The `nobools` linter checks that fields in the API types do not contain a `bool` type.

pkg/analysis/namingconventions/analyzer.go

@@ -0,0 +1,213 @@
+/*
+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 namingconventions
+
+import (
+	"fmt"
+	"go/ast"
+	"go/token"
+	"regexp"
+	"strings"
+
+	"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"
+	"sigs.k8s.io/kube-api-linter/pkg/analysis/utils"
+)
+
+const name = "namingconventions"
+
+type analyzer struct {
+	conventions []Convention
+}
+
+// newAnalyzer creates a new analysis.Analyzer for the namingconventions
+// linter based on the provided config.
+func newAnalyzer(cfg *Config) *analysis.Analyzer {
+	a := &analyzer{
+		conventions: cfg.Conventions,
+	}
+
+	analyzer := &analysis.Analyzer{
+		Name:     name,
+		Doc:      "Enforces naming conventions on fields",
+		Run:      a.run,
+		Requires: []*analysis.Analyzer{inspector.Analyzer, extractjsontags.Analyzer},
+	}
+
+	return analyzer
+}
+
+func (a *analyzer) run(pass *analysis.Pass) (any, error) {
+	inspect, ok := pass.ResultOf[inspector.Analyzer].(inspector.Inspector)
+	if !ok {
+		return nil, kalerrors.ErrCouldNotGetInspector
+	}
+
+	inspect.InspectFields(func(field *ast.Field, stack []ast.Node, jsonTags extractjsontags.FieldTagInfo, markersAccess markers.Markers) {
+		checkField(pass, field, jsonTags, a.conventions...)
+	})
+
+	return nil, nil //nolint:nilnil
+}
+
+func checkField(pass *analysis.Pass, field *ast.Field, tagInfo extractjsontags.FieldTagInfo, conventions ...Convention) {
+	if field == nil || len(field.Names) == 0 {
+		return
+	}
+
+	fieldName := utils.FieldName(field)
+
+	for _, convention := range conventions {
+		// regexp.MustCompile will panic if the regular expression doesn't compile.
+		// This should be reasonable as any regular expressions in naming conventions
+		// will have already been validated to compile during the configuration validation stage.
+		matcher := regexp.MustCompile(convention.ViolationMatcher)
+
+		if !matcher.MatchString(fieldName) && !matcher.MatchString(tagInfo.Name) {
+			continue
+		}
+
+		switch convention.Operation {
+		case OperationInform:
+			reportConventionWithSuggestedFixes(pass, field, convention)
+
+		case OperationDropField:
+			reportDropField(pass, field, convention)
+
+		case OperationDrop:
+			reportDrop(pass, field, tagInfo, convention, matcher)
+
+		case OperationReplacement:
+			reportReplace(pass, field, tagInfo, convention, matcher)
+		}
+	}
+}
+
+func reportConventionWithSuggestedFixes(pass *analysis.Pass, field *ast.Field, convention Convention, suggestedFixes ...analysis.SuggestedFix) {
+	pass.Report(analysis.Diagnostic{
+		Pos:            field.Pos(),
+		Message:        fmt.Sprintf("naming convention %q: field %s: %s", convention.Name, utils.FieldName(field), convention.Message),
+		SuggestedFixes: suggestedFixes,
+	})
+}
+
+func reportDropField(pass *analysis.Pass, field *ast.Field, convention Convention) {
+	suggestedFixes := []analysis.SuggestedFix{
+		{
+			Message: "remove the field",
+			TextEdits: []analysis.TextEdit{
+				{
+					Pos:     field.Pos(),
+					NewText: []byte(""),
+					End:     field.End(),
+				},
+			},
+		},
+	}
+
+	reportConventionWithSuggestedFixes(pass, field, convention, suggestedFixes...)
+}
+
+func reportDrop(pass *analysis.Pass, field *ast.Field, tagInfo extractjsontags.FieldTagInfo, convention Convention, matcher *regexp.Regexp) {
+	suggestedFixes := suggestedFixesForReplacement(field, tagInfo, matcher, "")
+	reportConventionWithSuggestedFixes(pass, field, convention, suggestedFixes...)
+}
+
+func reportReplace(pass *analysis.Pass, field *ast.Field, tagInfo extractjsontags.FieldTagInfo, convention Convention, matcher *regexp.Regexp) {
+	suggestedFixes := suggestedFixesForReplacement(field, tagInfo, matcher, convention.Replacement)
+	reportConventionWithSuggestedFixes(pass, field, convention, suggestedFixes...)
+}
+
+func suggestedFixesForReplacement(field *ast.Field, tagInfo extractjsontags.FieldTagInfo, matcher *regexp.Regexp, replacementStr string) []analysis.SuggestedFix {
+	suggestedFixes := []analysis.SuggestedFix{}
+
+	suggestedFixes = append(suggestedFixes, suggestFixesForGoFieldName(field, matcher, replacementStr)...)
+	suggestedFixes = append(suggestedFixes, suggestFixesForSerializedFieldName(tagInfo, matcher, replacementStr)...)
+
+	return suggestedFixes
+}
+
+func suggestFixesForSerializedFieldName(tagInfo extractjsontags.FieldTagInfo, matcher *regexp.Regexp, replacementStr string) []analysis.SuggestedFix {
+	replacement := matcher.ReplaceAllString(tagInfo.Name, replacementStr)
+
+	// If dropping the offending text from the field name would result in an empty
+	// field name, just issue the failure with no suggested fix.
+	if len(replacement) == 0 {
+		return nil
+	}
+
+	// This should prevent panics from slice access when the replacement
+	// string ends up being a length of 1 and still result in a technically
+	// correct JSON tag name value.
+	tagNameReplacement := strings.ToLower(replacement)
+	if len(replacement) > 1 {
+		tagNameReplacement = fmt.Sprintf("%s%s", strings.ToLower(replacement[:1]), replacement[1:])
+	}
+
+	tagReplacement := strings.ReplaceAll(tagInfo.RawValue, tagInfo.Name, tagNameReplacement)
+
+	tagReplacementMessage := fmt.Sprintf("replace offending text in serialized field name with %q", replacementStr)
+
+	if len(replacementStr) == 0 {
+		tagReplacementMessage = "remove offending text from serialized field name"
+	}
+
+	return []analysis.SuggestedFix{
+		{
+			Message: tagReplacementMessage,
+			TextEdits: []analysis.TextEdit{
+				{
+					Pos:     tagInfo.Pos,
+					NewText: []byte(tagReplacement),
+					End:     tagInfo.End,
+				},
+			},
+		},
+	}
+}
+
+func suggestFixesForGoFieldName(field *ast.Field, matcher *regexp.Regexp, replacementStr string) []analysis.SuggestedFix {
+	fieldName := utils.FieldName(field)
+	replacement := matcher.ReplaceAllString(fieldName, replacementStr)
+
+	// If dropping the offending text from the field name would result in an empty
+	// field name, just issue the failure with no suggested fix.
+	if len(replacement) == 0 {
+		return nil
+	}
+
+	replacementMessage := fmt.Sprintf("replace offending text in Go type with %q", replacementStr)
+
+	if len(replacementStr) == 0 {
+		replacementMessage = "remove offending text from Go type field"
+	}
+
+	return []analysis.SuggestedFix{
+		{
+			Message: replacementMessage,
+			TextEdits: []analysis.TextEdit{
+				{
+					Pos:     field.Pos(),
+					NewText: []byte(replacement),
+					End:     field.Pos() + token.Pos(len(fieldName)),
+				},
+			},
+		},
+	}
+}

pkg/analysis/namingconventions/analyzer_test.go

@@ -0,0 +1,64 @@
+/*
+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 namingconventions_test
+
+import (
+	"testing"
+
+	"golang.org/x/tools/go/analysis/analysistest"
+	"sigs.k8s.io/kube-api-linter/pkg/analysis/namingconventions"
+)
+
+func Test(t *testing.T) {
+	testdata := analysistest.TestData()
+
+	cfg := &namingconventions.Config{
+		Conventions: []namingconventions.Convention{
+			{
+				Name:             "nofruit",
+				ViolationMatcher: "(?i)fruit",
+				Operation:        namingconventions.OperationDrop,
+				Message:          "no fields should contain any variations of the word 'fruit' in their name.",
+			},
+			{
+				Name:             "preferbehaviour",
+				ViolationMatcher: "(?i)behavior",
+				Operation:        namingconventions.OperationReplacement,
+				Message:          "prefer the use of the word 'behaviour' instead of 'behavior'.",
+				Replacement:      "Behaviour",
+			},
+			{
+				Name:             "nounsupported",
+				ViolationMatcher: "(?i)unsupported",
+				Operation:        namingconventions.OperationDropField,
+				Message:          "no fields allowing for unsupported behaviors allowed",
+			},
+			{
+				Name:             "notest",
+				ViolationMatcher: "(?i)test",
+				Operation:        namingconventions.OperationInform,
+				Message:          "no temporary test fields",
+			},
+		},
+	}
+
+	analyzer, err := namingconventions.Initializer().Init(cfg)
+	if err != nil {
+		t.Fatalf("initializing namingconventions linter: %v", err)
+	}
+
+	analysistest.RunWithSuggestedFixes(t, testdata, analyzer, "a")
+}