(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 (
 	github.com/onsi/gomega v1.38.0
 	golang.org/x/tools v0.37.0
 	k8s.io/apimachinery v0.32.3
+	k8s.io/gengo/v2 v2.0.0-20250922181213-ec3ebc5fd46b
 	k8s.io/utils v0.0.0-20241104100929-3ea5e8cea738
 	sigs.k8s.io/yaml v1.4.0
 )

go.sum

@@ -993,6 +993,8 @@ honnef.co/go/tools v0.6.1 h1:R094WgE8K4JirYjBaOpz/AvTyUu/3wbmAoskKN/pxTI=
 honnef.co/go/tools v0.6.1/go.mod h1:3puzxxljPCe8RGJX7BIy1plGbxEOZni5mR2aXe3/uk4=
 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=
 mvdan.cc/gofumpt v0.9.1 h1:p5YT2NfFWsYyTieYgwcQ8aKV3xRvFH4uuN/zB2gBbMQ=

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,47 +161,60 @@ 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
 }
 
 // validMarkerStart validates that a marker starts with an alphabetic character
@@ -207,9 +223,9 @@ func extractFieldMarkers(field *ast.Field, results *markers) {
 // while supporting declarative validation tags with parentheses and nested markers.
 var validMarkerStart = regexp.MustCompile(`^[a-zA-Z]([a-zA-Z0-9:\(\)\"\" ,])+=?`)
 
-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, "// +")
@@ -218,7 +234,16 @@ func extractMarker(comment *ast.Comment) Marker {
 	// This excludes markdown tables (e.g., "// +-------") and other non-marker content,
 	// while supporting declarative validation tags that may include parentheses and nested markers.
 	if !validMarkerStart.MatchString(markerContent) {
-		return Marker{}
+		return Marker{}, nil
+	}
+
+	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)
@@ -229,7 +254,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) {
@@ -240,6 +265,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))
 }
@@ -325,9 +396,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