maxLength: add support for k8s declarative validation markers and configurability

Author: itzPranshul

pkg/analysis/maxlength/analyzer.go

@@ -32,35 +32,84 @@ const (
 	name = "maxlength"
 )
 
-// Analyzer is the analyzer for the maxlength package.
+func init() {
+	markershelper.DefaultRegistry().Register(
+		markers.K8sMaxLengthMarker,
+		markers.K8sMaxBytesMarker,
+		markers.K8sMaxItemsMarker,
+		markers.K8sMaxPropertiesMarker,
+		markers.K8sEnumMarker,
+		markers.K8sFormatMarker,
+	)
+}
+
+// Analyzer is the analyzer for the maxlength package with the default (kubebuilder-preferred) configuration.
 // It checks that strings and arrays have maximum lengths and maximum items respectively.
-var Analyzer = &analysis.Analyzer{
-	Name:     name,
-	Doc:      "Checks that all strings formatted fields are marked with a maximum length, and that arrays are marked with max items.",
-	Run:      run,
-	Requires: []*analysis.Analyzer{inspector.Analyzer},
+var Analyzer = newAnalyzer(nil)
+
+type analyzer struct {
+	preferredMaxLengthMarker     string
+	preferredMaxItemsMarker      string
+	preferredMaxPropertiesMarker string
+}
+
+// newAnalyzer creates a new analysis.Analyzer for the given MaxLengthConfig.
+// If cfg is nil, the default configuration is used (kubebuilder markers preferred).
+func newAnalyzer(cfg *MaxLengthConfig) *analysis.Analyzer {
+	if cfg == nil {
+		cfg = &MaxLengthConfig{}
+	}
+
+	defaultConfig(cfg)
+
+	a := &analyzer{
+		preferredMaxLengthMarker:     cfg.PreferredMaxLengthMarker,
+		preferredMaxItemsMarker:      cfg.PreferredMaxItemsMarker,
+		preferredMaxPropertiesMarker: cfg.PreferredMaxPropertiesMarker,
+	}
+
+	return &analysis.Analyzer{
+		Name:     name,
+		Doc:      "Checks that all string fields are marked with a maximum length, arrays are marked with max items, and maps are marked with max properties.",
+		Run:      a.run,
+		Requires: []*analysis.Analyzer{inspector.Analyzer},
+	}
 }
 
-func run(pass *analysis.Pass) (any, error) {
+func defaultConfig(cfg *MaxLengthConfig) {
+	if cfg.PreferredMaxLengthMarker == "" {
+		cfg.PreferredMaxLengthMarker = markers.KubebuilderMaxLengthMarker
+	}
+
+	if cfg.PreferredMaxItemsMarker == "" {
+		cfg.PreferredMaxItemsMarker = markers.KubebuilderMaxItemsMarker
+	}
+
+	if cfg.PreferredMaxPropertiesMarker == "" {
+		cfg.PreferredMaxPropertiesMarker = markers.KubebuilderMaxPropertiesMarker
+	}
+}
+
+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, _ extractjsontags.FieldTagInfo, markersAccess markershelper.Markers, qualifiedFieldName string) {
-		checkField(pass, field, markersAccess, qualifiedFieldName)
+		a.checkField(pass, field, markersAccess, qualifiedFieldName)
 	})
 
 	return nil, nil //nolint:nilnil
 }
 
-func checkField(pass *analysis.Pass, field *ast.Field, markersAccess markershelper.Markers, qualifiedFieldName string) {
+func (a *analyzer) checkField(pass *analysis.Pass, field *ast.Field, markersAccess markershelper.Markers, qualifiedFieldName string) {
 	prefix := fmt.Sprintf("field %s", qualifiedFieldName)
 
-	checkTypeExpr(pass, field.Type, field, nil, markersAccess, prefix, markers.KubebuilderMaxLengthMarker, needsStringMaxLength)
+	a.checkTypeExpr(pass, field.Type, field, nil, markersAccess, prefix, a.preferredMaxLengthMarker, a.needsStringMaxLength)
 }
 
-func checkIdent(pass *analysis.Pass, ident *ast.Ident, node ast.Node, aliases []*ast.TypeSpec, markersAccess markershelper.Markers, prefix, marker string, needsMaxLength func(markershelper.MarkerSet) bool) {
+func (a *analyzer) checkIdent(pass *analysis.Pass, ident *ast.Ident, node ast.Node, aliases []*ast.TypeSpec, markersAccess markershelper.Markers, prefix, marker string, needsMaxLength func(markershelper.MarkerSet) bool) {
 	if utils.IsBasicType(pass, ident) { // Built-in type
 		checkString(pass, ident, node, aliases, markersAccess, prefix, marker, needsMaxLength)
 
@@ -72,72 +121,103 @@ func checkIdent(pass *analysis.Pass, ident *ast.Ident, node ast.Node, aliases []
 		return
 	}
 
-	checkTypeSpec(pass, tSpec, node, append(aliases, tSpec), markersAccess, fmt.Sprintf("%s type", prefix), marker, needsMaxLength)
+	a.checkTypeSpec(pass, tSpec, node, append(aliases, tSpec), markersAccess, fmt.Sprintf("%s type", prefix), marker, needsMaxLength)
 }
 
 func checkString(pass *analysis.Pass, ident *ast.Ident, node ast.Node, aliases []*ast.TypeSpec, markersAccess markershelper.Markers, prefix, marker string, needsMaxLength func(markershelper.MarkerSet) bool) {
 	if ident.Name != "string" {
 		return
 	}
 
-	markers := getCombinedMarkers(markersAccess, node, aliases)
+	markerSet := getCombinedMarkers(markersAccess, node, aliases)
 
-	if needsMaxLength(markers) {
+	if needsMaxLength(markerSet) {
 		pass.Reportf(node.Pos(), "%s must have a maximum length, add %s marker", prefix, marker)
 	}
 }
 
-func checkTypeSpec(pass *analysis.Pass, tSpec *ast.TypeSpec, node ast.Node, aliases []*ast.TypeSpec, markersAccess markershelper.Markers, prefix, marker string, needsMaxLength func(markershelper.MarkerSet) bool) {
+func (a *analyzer) checkTypeSpec(pass *analysis.Pass, tSpec *ast.TypeSpec, node ast.Node, aliases []*ast.TypeSpec, markersAccess markershelper.Markers, prefix, marker string, needsMaxLength func(markershelper.MarkerSet) bool) {
 	if tSpec.Name == nil {
 		return
 	}
 
 	typeName := tSpec.Name.Name
 	prefix = fmt.Sprintf("%s %s", prefix, typeName)
 
-	checkTypeExpr(pass, tSpec.Type, node, aliases, markersAccess, prefix, marker, needsMaxLength)
+	a.checkTypeExpr(pass, tSpec.Type, node, aliases, markersAccess, prefix, marker, needsMaxLength)
 }
 
-func checkTypeExpr(pass *analysis.Pass, typeExpr ast.Expr, node ast.Node, aliases []*ast.TypeSpec, markersAccess markershelper.Markers, prefix, marker string, needsMaxLength func(markershelper.MarkerSet) bool) {
+func (a *analyzer) checkTypeExpr(pass *analysis.Pass, typeExpr ast.Expr, node ast.Node, aliases []*ast.TypeSpec, markersAccess markershelper.Markers, prefix, marker string, needsMaxLength func(markershelper.MarkerSet) bool) {
 	switch typ := typeExpr.(type) {
 	case *ast.Ident:
-		checkIdent(pass, typ, node, aliases, markersAccess, prefix, marker, needsMaxLength)
+		a.checkIdent(pass, typ, node, aliases, markersAccess, prefix, marker, needsMaxLength)
 	case *ast.StarExpr:
-		checkTypeExpr(pass, typ.X, node, aliases, markersAccess, prefix, marker, needsMaxLength)
+		a.checkTypeExpr(pass, typ.X, node, aliases, markersAccess, prefix, marker, needsMaxLength)
 	case *ast.ArrayType:
-		checkArrayType(pass, typ, node, aliases, markersAccess, prefix)
+		a.checkArrayType(pass, typ, node, aliases, markersAccess, prefix)
+	case *ast.MapType:
+		a.checkMapType(pass, typ, node, aliases, markersAccess, prefix)
 	}
 }
 
-func checkArrayType(pass *analysis.Pass, arrayType *ast.ArrayType, node ast.Node, aliases []*ast.TypeSpec, markersAccess markershelper.Markers, prefix string) {
+func (a *analyzer) checkArrayType(pass *analysis.Pass, arrayType *ast.ArrayType, node ast.Node, aliases []*ast.TypeSpec, markersAccess markershelper.Markers, prefix string) {
 	if arrayType.Elt != nil {
 		if ident, ok := arrayType.Elt.(*ast.Ident); ok {
 			if ident.Name == "byte" {
-				// byte slices are a special case as they are treated as strings.
-				// Pretend the ident is a string so that checkString can process it as expected.
-				i := &ast.Ident{
-					NamePos: ident.NamePos,
-					Name:    "string",
-				}
-				checkString(pass, i, node, aliases, markersAccess, prefix, markers.KubebuilderMaxLengthMarker, needsStringMaxLength)
+				a.checkByteSlice(pass, ident, node, aliases, markersAccess, prefix)
 
 				return
 			}
 
-			checkArrayElementIdent(pass, ident, node, aliases, markersAccess, fmt.Sprintf("%s array element", prefix))
+			a.checkArrayElementIdent(pass, ident, node, aliases, markersAccess, fmt.Sprintf("%s array element", prefix))
 		}
 	}
 
 	markerSet := getCombinedMarkers(markersAccess, node, aliases)
 
-	if !markerSet.Has(markers.KubebuilderMaxItemsMarker) {
-		pass.Reportf(node.Pos(), "%s must have a maximum items, add %s marker", prefix, markers.KubebuilderMaxItemsMarker)
+	if !markerSet.Has(markers.KubebuilderMaxItemsMarker) && !markerSet.Has(markers.K8sMaxItemsMarker) {
+		pass.Reportf(node.Pos(), "%s must have a maximum items, add %s marker", prefix, a.preferredMaxItemsMarker)
+	}
+}
+
+func (a *analyzer) checkByteSlice(pass *analysis.Pass, ident *ast.Ident, node ast.Node, aliases []*ast.TypeSpec, markersAccess markershelper.Markers, prefix string) {
+	// byte slices are a special case as they are treated as strings.
+	// Pretend the ident is a string so that checkString can process it as expected.
+	// In DV, k8s:maxBytes (not k8s:maxLength) is the correct tag for []byte fields,
+	// as it constrains byte count rather than Unicode character count.
+	i := &ast.Ident{
+		NamePos: ident.NamePos,
+		Name:    "string",
+	}
+
+	suggestedMarker := a.preferredMaxLengthMarker
+	if suggestedMarker == markers.K8sMaxLengthMarker {
+		suggestedMarker = markers.K8sMaxBytesMarker
+	}
+
+	checkString(pass, i, node, aliases, markersAccess, prefix, suggestedMarker, a.needsByteSliceMaxLength)
+}
+
+// checkMapType checks that map[string]V fields have a maximum properties marker.
+// Only string-keyed maps are checked, mirroring the constraint that maxProperties
+// validation only applies to map[string]V types.
+func (a *analyzer) checkMapType(pass *analysis.Pass, mapType *ast.MapType, node ast.Node, aliases []*ast.TypeSpec, markersAccess markershelper.Markers, prefix string) {
+	// Map maxProperties validation only supports string-keyed maps.
+	// Skip non-string-keyed maps (e.g. map[int]string) to avoid false positives.
+	if !utils.IsStringType(pass, mapType.Key) {
+		return
+	}
+
+	markerSet := getCombinedMarkers(markersAccess, node, aliases)
+
+	if !markerSet.Has(markers.KubebuilderMaxPropertiesMarker) && !markerSet.Has(markers.K8sMaxPropertiesMarker) {
+		pass.Reportf(node.Pos(), "%s must have a maximum properties, add %s marker", prefix, a.preferredMaxPropertiesMarker)
 	}
 }
 
-func checkArrayElementIdent(pass *analysis.Pass, ident *ast.Ident, node ast.Node, aliases []*ast.TypeSpec, markersAccess markershelper.Markers, prefix string) {
+func (a *analyzer) checkArrayElementIdent(pass *analysis.Pass, ident *ast.Ident, node ast.Node, aliases []*ast.TypeSpec, markersAccess markershelper.Markers, prefix string) {
 	if ident.Obj == nil { // Built-in type
-		checkString(pass, ident, node, aliases, markersAccess, prefix, markers.KubebuilderItemsMaxLengthMarker, needsItemsMaxLength)
+		checkString(pass, ident, node, aliases, markersAccess, prefix, markers.KubebuilderItemsMaxLengthMarker, a.needsItemsMaxLength)
 
 		return
 	}
@@ -149,16 +229,16 @@ func checkArrayElementIdent(pass *analysis.Pass, ident *ast.Ident, node ast.Node
 
 	// If the array element wasn't directly a string, allow a string alias to be used
 	// with either the items style markers or the on alias style markers.
-	checkTypeSpec(pass, tSpec, node, append(aliases, tSpec), markersAccess, fmt.Sprintf("%s type", prefix), markers.KubebuilderMaxLengthMarker, func(ms markershelper.MarkerSet) bool {
-		return needsStringMaxLength(ms) && needsItemsMaxLength(ms)
+	a.checkTypeSpec(pass, tSpec, node, append(aliases, tSpec), markersAccess, fmt.Sprintf("%s type", prefix), markers.KubebuilderMaxLengthMarker, func(ms markershelper.MarkerSet) bool {
+		return a.needsStringMaxLength(ms) && a.needsItemsMaxLength(ms)
 	})
 }
 
 func getCombinedMarkers(markersAccess markershelper.Markers, node ast.Node, aliases []*ast.TypeSpec) markershelper.MarkerSet {
 	base := markershelper.NewMarkerSet(getMarkers(markersAccess, node).UnsortedList()...)
 
-	for _, a := range aliases {
-		base.Insert(getMarkers(markersAccess, a).UnsortedList()...)
+	for _, alias := range aliases {
+		base.Insert(getMarkers(markersAccess, alias).UnsortedList()...)
 	}
 
 	return base
@@ -175,23 +255,48 @@ func getMarkers(markersAccess markershelper.Markers, node ast.Node) markershelpe
 	return nil
 }
 
-// needsMaxLength returns true if the field needs a maximum length.
-// Fields do not need a maximum length if they are already marked with a maximum length,
-// or if they are an enum, or if they are a date, date-time or duration.
-func needsStringMaxLength(markerSet markershelper.MarkerSet) bool {
+// needsStringMaxLength returns true if the field needs a maximum length.
+// Returns false if either a kubebuilder or DV max-length marker is already present,
+// or if the field is an enum, or is formatted as a date, date-time or duration.
+func (a *analyzer) needsStringMaxLength(markerSet markershelper.MarkerSet) bool {
 	switch {
 	case markerSet.Has(markers.KubebuilderMaxLengthMarker),
+		markerSet.Has(markers.K8sMaxLengthMarker),
 		markerSet.Has(markers.KubebuilderEnumMarker),
+		markerSet.Has(markers.K8sEnumMarker),
 		markerSet.HasWithValue(kubebuilderFormatWithValue("date")),
 		markerSet.HasWithValue(kubebuilderFormatWithValue("date-time")),
-		markerSet.HasWithValue(kubebuilderFormatWithValue("duration")):
+		markerSet.HasWithValue(kubebuilderFormatWithValue("duration")),
+		markerSet.HasWithValue(k8sFormatWithValue("date")),
+		markerSet.HasWithValue(k8sFormatWithValue("date-time")),
+		markerSet.HasWithValue(k8sFormatWithValue("duration")):
 		return false
 	}
 
 	return true
 }
 
-func needsItemsMaxLength(markerSet markershelper.MarkerSet) bool {
+// needsByteSliceMaxLength is like needsStringMaxLength but enforces that for DV markers,
+// k8s:maxBytes is used instead of k8s:maxLength (which counts characters).
+func (a *analyzer) needsByteSliceMaxLength(markerSet markershelper.MarkerSet) bool {
+	switch {
+	case markerSet.Has(markers.KubebuilderMaxLengthMarker),
+		markerSet.Has(markers.K8sMaxBytesMarker),
+		markerSet.Has(markers.KubebuilderEnumMarker),
+		markerSet.Has(markers.K8sEnumMarker),
+		markerSet.HasWithValue(kubebuilderFormatWithValue("date")),
+		markerSet.HasWithValue(kubebuilderFormatWithValue("date-time")),
+		markerSet.HasWithValue(kubebuilderFormatWithValue("duration")),
+		markerSet.HasWithValue(k8sFormatWithValue("date")),
+		markerSet.HasWithValue(k8sFormatWithValue("date-time")),
+		markerSet.HasWithValue(k8sFormatWithValue("duration")):
+		return false
+	}
+
+	return true
+}
+
+func (a *analyzer) needsItemsMaxLength(markerSet markershelper.MarkerSet) bool {
 	switch {
 	case markerSet.Has(markers.KubebuilderItemsMaxLengthMarker),
 		markerSet.Has(markers.KubebuilderItemsEnumMarker),
@@ -211,3 +316,7 @@ func kubebuilderFormatWithValue(value string) string {
 func kubebuilderItemsFormatWithValue(value string) string {
 	return fmt.Sprintf("%s:=%s", markers.KubebuilderItemsFormatMarker, value)
 }
+
+func k8sFormatWithValue(value string) string {
+	return fmt.Sprintf("%s=%s", markers.K8sFormatMarker, value)
+}