Merge branch 'main' into enums

Author: krishagarwal278

docs/linters.md

@@ -7,6 +7,7 @@
 - [DefaultOrRequired](#defaultorrequired) - Ensures fields marked as required do not have default values
 - [DuplicateMarkers](#duplicatemarkers) - Checks for exact duplicates of markers
 - [Enums](#enums) - Enforces proper usage of enumerated fields with type aliases and +enum marker
+- [DependentTags](#dependenttags) - Enforces dependencies between markers
 - [ForbiddenMarkers](#forbiddenmarkers) - Checks that no forbidden markers are present on types/fields.
 - [Integers](#integers) - Validates usage of supported integer types
 - [JSONTags](#jsontags) - Ensures proper JSON tag formatting
@@ -93,6 +94,43 @@ If any of the 5 markers in the example above are missing, the linter will sugges
 When `usePatchStrategy` is set to `Ignore`, the linter will not suggest to add the `patchStrategy` and `patchMergeKey` tags to the `Conditions` field markers.
 When `usePatchStrategy` is set to `Forbid`, the linter will suggest to remove the `patchStrategy` and `patchMergeKey` tags from the `Conditions` field markers.
 
+## DependentTags
+
+The `dependenttags` linter enforces dependencies between markers. This prevents API inconsistencies where one marker requires the presence of another.
+
+The linter is configured with a main tag and a list of required dependent tags. If the main tag is present on a field, the linter checks for the presence of the dependent tags based on the `type` field:
+- `All`: Ensures that **all** of the dependent tags are present.
+- `Any`: Ensures that **at least one** of the dependent tags is present.
+
+### Configuration
+
+```yaml
+lintersConfig:
+  dependenttags:
+    rules:
+      - identifier: "k8s:unionMember"
+        type: "All"
+        dependents:
+          - "k8s:optional"
+      - identifier: "listType"
+        type: "All"
+        dependents:
+          - "k8s:listType"
+      - identifier: "example:any"
+        type: "Any"
+        dependents:
+          - "dep1"
+          - "dep2"
+```
+
+### Behavior
+
+This linter only checks for the presence or absence of markers; it does not inspect or enforce specific values within those markers. Therefore:
+
+- **Values:** The linter does not care about the values of the `identifier` or `dependent` markers. It only verifies if the markers themselves are present.
+- **Fixes:** This linter does not provide automatic fixes. It only reports violations.
+- **Same/Different Values:** Whether you want the same or different values between dependent markers is outside the scope of this linter. You would need other validation mechanisms (e.g., CEL validation) to enforce value-based dependencies.
+
 ## CommentStart
 
 The `commentstart` linter checks that all comments in the API types start with the serialized form of the type they are commenting on.

pkg/analysis/dependenttags/analyzer.go

@@ -0,0 +1,123 @@
+/*
+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 dependenttags
+
+import (
+	"fmt"
+	"go/ast"
+	"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"
+)
+
+// analyzer implements the dependenttags linter.
+type analyzer struct {
+	cfg Config
+}
+
+// newAnalyzer creates a new analyzer.
+func newAnalyzer(cfg Config) *analysis.Analyzer {
+	// Register markers from configuration
+	for _, rule := range cfg.Rules {
+		markers.DefaultRegistry().Register(rule.Identifier)
+
+		for _, dep := range rule.Dependents {
+			markers.DefaultRegistry().Register(dep)
+		}
+	}
+
+	a := &analyzer{
+		cfg: cfg,
+	}
+
+	return &analysis.Analyzer{
+		Name:     name,
+		Doc:      "Enforces dependencies between markers.",
+		Run:      a.run,
+		Requires: []*analysis.Analyzer{inspector.Analyzer, markers.Analyzer},
+	}
+}
+
+// run is the main function for the 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, jsonTagInfo extractjsontags.FieldTagInfo, markersAccess markers.Markers, qualifiedFieldName string) {
+		if field.Doc == nil {
+			return
+		}
+
+		fieldMarkers := utils.TypeAwareMarkerCollectionForField(pass, markersAccess, field)
+
+		for _, rule := range a.cfg.Rules {
+			if _, ok := fieldMarkers[rule.Identifier]; ok {
+				switch rule.Type {
+				case DependencyTypeAny:
+					handleAny(pass, field, rule, fieldMarkers, qualifiedFieldName)
+				case DependencyTypeAll:
+					handleAll(pass, field, rule, fieldMarkers, qualifiedFieldName)
+				default:
+					panic(fmt.Sprintf("unknown dependency type %s", rule.Type))
+				}
+			}
+		}
+	})
+
+	return nil, nil //nolint:nilnil
+}
+func handleAll(pass *analysis.Pass, field *ast.Field, rule Rule, fieldMarkers markers.MarkerSet, qualifiedFieldName string) {
+	missing := make([]string, 0, len(rule.Dependents))
+
+	for _, dependent := range rule.Dependents {
+		if _, depOk := fieldMarkers[dependent]; !depOk {
+			missing = append(missing, fmt.Sprintf("+%s", dependent))
+		}
+	}
+
+	if len(missing) > 0 {
+		pass.Reportf(field.Pos(), "field %s with marker +%s is missing required marker(s): %s", qualifiedFieldName, rule.Identifier, strings.Join(missing, ", "))
+	}
+}
+
+func handleAny(pass *analysis.Pass, field *ast.Field, rule Rule, fieldMarkers markers.MarkerSet, qualifiedFieldName string) {
+	found := false
+
+	for _, dependent := range rule.Dependents {
+		if _, depOk := fieldMarkers[dependent]; depOk {
+			found = true
+			break
+		}
+	}
+
+	if !found {
+		dependents := make([]string, len(rule.Dependents))
+		for i, d := range rule.Dependents {
+			dependents[i] = fmt.Sprintf("+%s", d)
+		}
+
+		pass.Reportf(field.Pos(), "field %s with marker +%s requires at least one of the following markers, but none were found: %s", qualifiedFieldName, rule.Identifier, strings.Join(dependents, ", "))
+	}
+}

pkg/analysis/dependenttags/analyzer_test.go

@@ -0,0 +1,59 @@
+/*
+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 dependenttags_test
+
+import (
+	"testing"
+
+	"golang.org/x/tools/go/analysis/analysistest"
+	"sigs.k8s.io/kube-api-linter/pkg/analysis/dependenttags"
+)
+
+func TestAnalyzer(t *testing.T) {
+	testdata := analysistest.TestData()
+	cfg := dependenttags.Config{
+		Rules: []dependenttags.Rule{
+			{
+				Identifier: "k8s:unionMember",
+				Type:       dependenttags.DependencyTypeAll,
+				Dependents: []string{"k8s:optional"},
+			},
+			{
+				Identifier: "listType",
+				Type:       dependenttags.DependencyTypeAll,
+				Dependents: []string{"k8s:listType"},
+			},
+			{
+				Identifier: "example:any",
+				Type:       dependenttags.DependencyTypeAny,
+				Dependents: []string{"dep1", "dep2"},
+			},
+			{
+				Identifier: "listType=map",
+				Type:       dependenttags.DependencyTypeAll,
+				Dependents: []string{"listMapKey"},
+			},
+		},
+	}
+	analyzer, err := dependenttags.Initializer().Init(&cfg)
+
+	if err != nil {
+		t.Fatalf("failed to initialize analyzer: %v", err)
+	}
+
+	analysistest.Run(t, testdata, analyzer, "a")
+}

pkg/analysis/dependenttags/config.go

@@ -0,0 +1,45 @@
+/*
+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 dependenttags
+
+// DependencyType defines the type of dependency rule.
+type DependencyType string
+
+const (
+	// DependencyTypeAll indicates that all dependent markers are required.
+	DependencyTypeAll DependencyType = "All"
+	// DependencyTypeAny indicates that at least one of the dependent markers is required.
+	DependencyTypeAny DependencyType = "Any"
+)
+
+// Config defines the configuration for the dependenttags linter.
+type Config struct {
+	// Rules defines the dependency rules between markers.
+	Rules []Rule `mapstructure:"rules"`
+}
+
+// Rule defines a dependency rule where a main marker requires a set of dependent markers.
+type Rule struct {
+	// Identifier is the marker that requires other markers.
+	Identifier string `mapstructure:"identifier"`
+	// Dependents are the markers that are required by Main.
+	Dependents []string `mapstructure:"dependents"`
+	// Type defines how to interpret the dependents list.
+	// When set to All, every dependent in the list must be present when the identifier is present on a field or type.
+	// When set to Any, at least one of the listed dependents must be present when the identifier is present on a field or type.
+	Type DependencyType `mapstructure:"type,omitempty"`
+}

pkg/analysis/dependenttags/dependenttags_suite_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 dependenttags_test
+
+import (
+	"testing"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+func TestDependentTags(t *testing.T) {
+	RegisterFailHandler(Fail)
+	RunSpecs(t, "DependentTags Suite")
+}

pkg/analysis/dependenttags/doc.go

@@ -0,0 +1,51 @@
+/*
+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 dependenttags enforces dependencies between markers.
+//
+// # Analyzer dependenttags
+//
+// The dependenttags analyzer validates that if a specific marker (identifier) is present on a field,
+// a set of other markers (dependent tags) are also present. This is useful for enforcing API
+// contracts where certain markers imply the presence of others.
+//
+// For example, a field marked with `+k8s:unionMember` must also be marked with `+k8s:optional`.
+//
+// # Configuration
+//
+// The linter is configured with a list of rules. Each rule specifies an identifier marker and a list of
+// dependent markers. The `type` field is required and specifies how to interpret the dependents list:
+// - `All`: all dependent markers are required.
+// - `Any`: at least one of the dependent markers is required.
+//
+// This linter only checks for the presence or absence of markers; it does not inspect or enforce specific values within those markers. It also does not provide automatic fixes.
+//
+//	linters:
+//	  dependenttags:
+//	    rules:
+//	    - identifier: "k8s:unionMember"
+//	      type: "All"
+//	      dependents:
+//	      - "k8s:optional"
+//	    - identifier: "listType"
+//	      type: "All"
+//	      dependents:
+//	      - "k8s:listType"
+//	    - identifier: "example:any"
+//	      type: "Any"
+//	      dependents:
+//	      - "dep1"
+//	      - "dep2"
+package dependenttags