(feat): markers: add support for parsing declarative validation tags

Signed-off-by: Bryce Palmer <[email protected]>

Author: everettraven

go.mod

@@ -9,6 +9,7 @@ require (
 	golang.org/x/tools v0.32.0
 	gopkg.in/yaml.v3 v3.0.1
 	k8s.io/apimachinery v0.32.3
+	k8s.io/gengo/v2 v2.0.0-20250922181213-ec3ebc5fd46b
 	k8s.io/utils v0.0.0-20241104100929-3ea5e8cea738
 )
 

go.sum

@@ -51,5 +51,7 @@ gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 k8s.io/apimachinery v0.32.3 h1:JmDuDarhDmA/Li7j3aPrwhpNBA94Nvk5zLeOge9HH1U=
 k8s.io/apimachinery v0.32.3/go.mod h1:GpHVgxoKlTxClKcteaeuF1Ul/lDVb74KpZcxcmLDElE=
+k8s.io/gengo/v2 v2.0.0-20250922181213-ec3ebc5fd46b h1:gMplByicHV/TJBizHd9aVEsTYoJBnnUAT5MHlTkbjhQ=
+k8s.io/gengo/v2 v2.0.0-20250922181213-ec3ebc5fd46b/go.mod h1:CgujABENc3KuTrcsdpGmrrASjtQsWCT7R99mEV4U/fM=
 k8s.io/utils v0.0.0-20241104100929-3ea5e8cea738 h1:M3sRQVHv7vB20Xc2ybTt7ODCeFj6JSWYFzOFnYeS6Ro=
 k8s.io/utils v0.0.0-20241104100929-3ea5e8cea738/go.mod h1:OLgZIPagt7ERELqWJFomSt595RzquPNLL48iOWgYOg0=

pkg/analysis/helpers/markers/analyzer.go

@@ -16,6 +16,7 @@ limitations under the License.
 package markers
 
 import (
+	"fmt"
 	"go/ast"
 	"go/token"
 	"reflect"
@@ -26,6 +27,8 @@ import (
 	"golang.org/x/tools/go/analysis/passes/inspect"
 	"golang.org/x/tools/go/ast/inspector"
 
+	"k8s.io/gengo/v2/codetags"
+
 	kalerrors "sigs.k8s.io/kube-api-linter/pkg/analysis/errors"
 )
 
@@ -158,55 +161,78 @@ func run(pass *analysis.Pass) (any, error) {
 	return results, nil
 }
 
-func extractGenDeclMarkers(typ *ast.GenDecl, results *markers) {
+func extractGenDeclMarkers(typ *ast.GenDecl, results *markers) error {
 	declMarkers := NewMarkerSet()
 
 	if typ.Doc != nil {
 		for _, comment := range typ.Doc.List {
-			if marker := extractMarker(comment); marker.Identifier != "" {
+			marker, err := extractMarker(comment)
+			if err != nil {
+				return err
+			}
+
+			if marker.Identifier != "" {
 				declMarkers.Insert(marker)
 			}
 		}
 	}
 
 	if len(typ.Specs) == 0 {
-		return
+		return nil
 	}
 
 	tSpec, ok := typ.Specs[0].(*ast.TypeSpec)
 	if !ok {
-		return
+		return nil
 	}
 
 	results.insertTypeMarkers(tSpec, declMarkers)
 
 	if sTyp, ok := tSpec.Type.(*ast.StructType); ok {
 		results.insertStructMarkers(sTyp, declMarkers)
 	}
+
+	return nil
 }
 
-func extractFieldMarkers(field *ast.Field, results *markers) {
+func extractFieldMarkers(field *ast.Field, results *markers) error {
 	if field == nil || field.Doc == nil {
-		return
+		return nil
 	}
 
 	fieldMarkers := NewMarkerSet()
 
 	for _, comment := range field.Doc.List {
-		if marker := extractMarker(comment); marker.Identifier != "" {
+		marker, err := extractMarker(comment)
+		if err != nil {
+			return err
+		}
+
+		if marker.Identifier != "" {
 			fieldMarkers.Insert(marker)
 		}
 	}
 
 	results.insertFieldMarkers(field, fieldMarkers)
+	return nil
 }
 
-func extractMarker(comment *ast.Comment) Marker {
+func extractMarker(comment *ast.Comment) (Marker, error) {
 	if !strings.HasPrefix(comment.Text, "// +") {
-		return Marker{}
+		return Marker{}, nil
 	}
 
 	markerContent := strings.TrimPrefix(comment.Text, "// +")
+
+	if isDeclarativeValidationMarker(markerContent) {
+		marker, err := extractDeclarativeValidationMarker(markerContent, comment)
+		if err != nil {
+			return Marker{}, fmt.Errorf("parsing declarative validation marker %q: %w", markerContent, err)
+		}
+
+		return *marker, nil
+	}
+
 	id, expressions := extractMarkerIDAndExpressions(DefaultRegistry(), markerContent)
 
 	return Marker{
@@ -215,7 +241,7 @@ func extractMarker(comment *ast.Comment) Marker {
 		RawComment:  comment.Text,
 		Pos:         comment.Pos(),
 		End:         comment.End(),
-	}
+	}, nil
 }
 
 func extractMarkerIDAndExpressions(knownMarkers Registry, marker string) (string, map[string]string) {
@@ -226,6 +252,52 @@ func extractMarkerIDAndExpressions(knownMarkers Registry, marker string) (string
 	return extractUnknownMarkerIDAndExpressions(marker)
 }
 
+func isDeclarativeValidationMarker(marker string) bool {
+	return strings.HasPrefix(marker, "k8s:")
+}
+
+func extractDeclarativeValidationMarker(marker string, comment *ast.Comment) (*Marker, error) {
+	tag, err := codetags.Parse(marker)
+	if err != nil {
+		return nil, fmt.Errorf("encountered an error parsing declarative validation marker %q: %v", marker, err)
+	}
+
+	return markerForTag(&tag, comment)
+}
+
+func markerForTag(tag *codetags.Tag, comment *ast.Comment) (*Marker, error) {
+	out := &Marker{
+		Identifier:  tag.Name,
+		Expressions: make(map[string]string),
+		RawComment:  comment.Text,
+		Pos:         comment.Pos(),
+		End:         comment.End(),
+	}
+
+	for _, arg := range tag.Args {
+		out.Expressions[arg.Name] = arg.Value
+	}
+
+	switch tag.ValueType {
+	case codetags.ValueTypeString, codetags.ValueTypeInt, codetags.ValueTypeBool, codetags.ValueTypeRaw:
+		// all resolvable to an exact string value
+		out.Expressions["payload"] = tag.Value
+	case codetags.ValueTypeNone:
+		// nothing
+	case codetags.ValueTypeTag:
+		// TODO: Better position evaluation
+		marker, err := markerForTag(tag.ValueTag, comment)
+		if err != nil {
+			return nil, err
+		}
+		out.Marker = marker
+	default:
+		return nil, fmt.Errorf("unknown tag value type %v", tag.ValueType)
+	}
+
+	return out, nil
+}
+
 func extractKnownMarkerIDAndExpressions(id string, marker string) (string, map[string]string) {
 	return id, extractExpressions(strings.TrimPrefix(marker, id))
 }
@@ -311,9 +383,17 @@ type Marker struct {
 	// Identifier is the value of the marker once the leading comment, '+', and expressions are trimmed.
 	Identifier string
 
-	// Expressions are the set of expressions that have been specified for the marker
+	// Expressions are the set of expressions that have been specified for the marker.
+	// Marker named and unnamed arguments are included in this map. If the marker's payload is
+	// not another marker, the key "payload" will contain the marker payload.
 	Expressions map[string]string
 
+	// Marker is a nested marker. This is present in cases
+	// where we've parsed a declarative validation tag
+	// and it has another declarative validation tag in it's payload.
+	// If this is nil, the payload was _not_ another dv tag.
+	Marker *Marker
+
 	// RawComment is the raw comment line, unfiltered.
 	RawComment string
 

pkg/analysis/helpers/markers/analyzer_test.go

@@ -16,6 +16,9 @@ limitations under the License.
 package markers
 
 import (
+	"errors"
+	"fmt"
+	"go/ast"
 	"testing"
 
 	. "github.com/onsi/gomega"
@@ -146,3 +149,180 @@ func TestExtractMarkerIdAndExpressions(t *testing.T) {
 		})
 	}
 }
+
+func TestExtractMarker(t *testing.T) {
+	type testcase struct {
+		name    string
+		comment *ast.Comment
+		expect  func(Marker) error
+	}
+
+	testcases := []testcase{
+		{
+			name: "simple declarative validation marker",
+			comment: &ast.Comment{
+				Text: "// +k8s:required",
+			},
+			expect: func(m Marker) error {
+				if m.Identifier != "k8s:required" {
+					return fmt.Errorf("identifier %q did not match expected identifier %q", m.Identifier, "k8s:required")
+				}
+
+				return nil
+			},
+		},
+		{
+			name: "declarative validation marker with a value",
+			comment: &ast.Comment{
+				Text: "// +k8s:maxLength=10",
+			},
+			expect: func(m Marker) error {
+				if m.Identifier != "k8s:maxLength" {
+					return fmt.Errorf("identifier %q did not match expected identifier %q", m.Identifier, "k8s:required")
+				}
+
+				payload, ok := m.Expressions["payload"]
+				if !ok {
+					return errors.New("expected a payload but there was none")
+				}
+
+				if payload != "10" {
+					return fmt.Errorf("payload value of %q does not match expected value %q", payload, "10")
+				}
+
+				return nil
+			},
+		},
+		{
+			name:       "declarative validation marker with named argument",
+			comment: &ast.Comment{
+				Text: "// +k8s:unionMember(union: \"union1\")",
+			},
+			expect: func(m Marker) error {
+				if m.Identifier != "k8s:unionMember" {
+					return fmt.Errorf("identifier %q did not match expected identifier %q", m.Identifier, "k8s:unionMember")
+				}
+
+				union, ok := m.Expressions["union"]
+				if !ok {
+					return fmt.Errorf("expected named argument %q to be in expressions but it was missing", "union")
+				}
+
+				if union != "union1" {
+					return fmt.Errorf("union value of %q does not match expected value %q", union, "union1")
+				}
+
+				return nil
+			},
+		},
+		{
+			name:       "declarative validation marker with unnamed argument",
+			comment: &ast.Comment{
+				Text: "// +k8s:doesWork(100)", // not a real DV marker, but AFAIK nothing stops something like this from coming up
+			},
+			expect: func(m Marker) error {
+				if m.Identifier != "k8s:doesWork" {
+					return fmt.Errorf("identifier %q did not match expected identifier %q", m.Identifier, "k8s:doesWork")
+				}
+
+				unnamed, ok := m.Expressions[""]
+				if !ok {
+					return errors.New("expected unnamed argument to be in expressions but it was missing")
+				}
+
+				if unnamed != "100" {
+					return fmt.Errorf("unnamed argument value of %q does not match expected value %q", unnamed, "100")
+				}
+
+				return nil
+			},
+		},
+		{
+			name:       "declarative validation marker with unnamed argument and simple validation tag payload",
+			comment: &ast.Comment{
+				Text: "// +k8s:ifEnabled(\"my-feature\")=+k8s:required",
+			},
+			expect: func(m Marker) error {
+				if m.Identifier != "k8s:ifEnabled" {
+					return fmt.Errorf("identifier %q did not match expected identifier %q", m.Identifier, "k8s:ifEnabled")
+				}
+
+				unnamed, ok := m.Expressions[""]
+				if !ok {
+					return errors.New("expected unnamed argument to be in expressions but it was missing")
+				}
+
+				if unnamed != "my-feature" {
+					return fmt.Errorf("unnamed argument value of %q does not match expected value %q", unnamed, "my-feature")
+				}
+
+				if m.Marker == nil {
+					return errors.New("expected a nested marker but none was found")
+				}
+
+				if m.Marker.Identifier != "k8s:required" {
+					return fmt.Errorf("nested marker identifier %q does not match expected identifier %q", m.Marker.Identifier, "k8s:required")
+				}
+
+				return nil
+			},
+		},
+		{
+			name:       "declarative validation marker with deeper chained validation tags",
+			comment: &ast.Comment{
+				Text: "// +k8s:ifEnabled(\"my-feature\")=+k8s:item(type: \"Approved\")=+k8s:zeroOrOneOfMember",
+			},
+			expect: func(m Marker) error {
+				if m.Identifier != "k8s:ifEnabled" {
+					return fmt.Errorf("identifier %q did not match expected identifier %q", m.Identifier, "k8s:ifEnabled")
+				}
+
+				unnamed, ok := m.Expressions[""]
+				if !ok {
+					return errors.New("expected unnamed argument to be in expressions but it was missing")
+				}
+
+				if unnamed != "my-feature" {
+					return fmt.Errorf("unnamed argument value of %q does not match expected value %q", unnamed, "my-feature")
+				}
+
+				if m.Marker == nil {
+					return errors.New("expected a nested marker but none was found")
+				}
+
+				if m.Marker.Identifier != "k8s:item" {
+					return fmt.Errorf("nested marker identifier %q does not match expected identifier %q", m.Marker.Identifier, "k8s:item")
+				}
+
+				typ, ok := m.Marker.Expressions["type"]
+				if !ok {
+					return errors.New("expected nested marker to have named argument \"type\" but it was missing")
+				}
+
+				if typ != "Approved" {
+					return fmt.Errorf("nested marker named argument \"type\" value of %q does not match expected value %q", typ, "Approved")
+				}
+
+				if m.Marker.Marker == nil {
+					return errors.New("expected nested marker to have a nested marker but none was found")
+				}
+
+				if m.Marker.Marker.Identifier != "k8s:zeroOrOneOfMember" {
+					return fmt.Errorf("nested marker's nested marker identifier %q does not match expected identifier %q", m.Marker.Identifier, "k8s:zeroOrOneOfMember")
+				}
+
+				return nil
+			},
+		},
+	}
+
+	for _, tc := range testcases {
+		t.Run(tc.name, func(t *testing.T) {
+			g := NewWithT(t)
+
+			marker, err := extractMarker(tc.comment)
+			g.Expect(err).NotTo(HaveOccurred())
+			g.Expect(tc.expect(marker)).NotTo(HaveOccurred())
+		})
+	}
+}