feat(markerscope): add default config and enhance documentation

Signed-off-by: nayuta-ai <nayuta723@gmail.com>

Author: nayuta723

pkg/analysis/markerscope/analyzer.go

@@ -60,6 +60,9 @@ func newAnalyzer(cfg *MarkerScopeConfig) *analysis.Analyzer {
 		cfg = &MarkerScopeConfig{}
 	}
 
+	// Apply default configuration
+	defaultConfig(cfg)
+
 	// Convert override and custom marker lists to maps
 	overrideRules := markerRulesListToMap(cfg.OverrideMarkers)
 	customRules := markerRulesListToMap(cfg.CustomMarkers)
@@ -87,14 +90,15 @@ func newAnalyzer(cfg *MarkerScopeConfig) *analysis.Analyzer {
 		markershelper.DefaultRegistry().Register(marker)
 	}
 
-	// Set default policy if not specified
-	if a.policy == "" {
-		a.policy = MarkerScopePolicyWarn
-	}
-
 	return &analysis.Analyzer{
-		Name:             name,
-		Doc:              "Validates that markers are applied in the correct scope.",
+		Name: name,
+		Doc: `Validates that markers are applied in the correct scope and to compatible data types.
+		This analyzer performs two levels of validation:
+		1. Scope validation - ensures markers are placed on the correct location (field vs type)
+		2. Type constraint validation - ensures markers are applied to compatible data types
+		The analyzer includes 100+ built-in kubebuilder marker rules. You can override built-in marker
+		rules using overrideMarkers configuration, or add custom markers using customMarkers configuration.
+		`,
 		Run:              a.run,
 		Requires:         []*analysis.Analyzer{inspect.Analyzer, markershelper.Analyzer},
 		RunDespiteErrors: true,
@@ -112,6 +116,16 @@ func markerRulesListToMap(rules []MarkerScopeRule) map[string]MarkerScopeRule {
 	return result
 }
 
+// defaultConfig applies default values to the configuration.
+func defaultConfig(cfg *MarkerScopeConfig) {
+	// Set default policy if not specified
+	if cfg.Policy == "" {
+		cfg.Policy = MarkerScopePolicyWarn
+	}
+	// allowDangerousTypes defaults to false (zero value)
+	// overrideMarkers and customMarkers default to empty (zero value)
+}
+
 func (a *analyzer) run(pass *analysis.Pass) (any, error) {
 	inspect, ok := pass.ResultOf[inspect.Analyzer].(*inspector.Inspector)
 	if !ok {

pkg/analysis/markerscope/analyzer_test.go

@@ -13,88 +13,108 @@ 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 markerscope
+package markerscope_test
 
 import (
 	"testing"
 
 	"golang.org/x/tools/go/analysis/analysistest"
+	"sigs.k8s.io/kube-api-linter/pkg/analysis/markerscope"
 )
 
-func TestAnalyzerWarnOnly(t *testing.T) {
+func TestAnalyzerWithDefaultConfig(t *testing.T) {
 	testdata := analysistest.TestData()
-	cfg := &MarkerScopeConfig{
-		Policy: MarkerScopePolicyWarn,
+	// Test with nil config - should use all defaults:
+	// - Policy: Warn
+	// - AllowDangerousTypes: false
+	// - OverrideMarkers: empty (use built-in defaults)
+	// - CustomMarkers: empty
+	analyzer, err := markerscope.Initializer().Init(&markerscope.MarkerScopeConfig{})
+	if err != nil {
+		t.Fatal(err)
 	}
-	analyzer := newAnalyzer(cfg)
 	analysistest.Run(t, testdata, analyzer, "a")
 }
 
 func TestAnalyzerSuggestFixes(t *testing.T) {
 	testdata := analysistest.TestData()
-	cfg := &MarkerScopeConfig{
-		Policy: MarkerScopePolicySuggestFix,
+	cfg := &markerscope.MarkerScopeConfig{
+		Policy: markerscope.MarkerScopePolicySuggestFix,
+	}
+	analyzer, err := markerscope.Initializer().Init(cfg)
+	if err != nil {
+		t.Fatal(err)
 	}
-	analyzer := newAnalyzer(cfg)
 	analysistest.RunWithSuggestedFixes(t, testdata, analyzer, "a")
 }
 
 func TestAnalyzerWithCustomAndOverrideMarkers(t *testing.T) {
 	testdata := analysistest.TestData()
-	cfg := &MarkerScopeConfig{
-		Policy: MarkerScopePolicyWarn,
-		OverrideMarkers: []MarkerScopeRule{
+	cfg := &markerscope.MarkerScopeConfig{
+		Policy: markerscope.MarkerScopePolicyWarn,
+		OverrideMarkers: []markerscope.MarkerScopeRule{
 			// Override built-in "optional" to allow on types (default is FieldScope only)
 			{
 				Identifier: "optional",
-				Scope:      AnyScope,
+				Scope:      markerscope.AnyScope,
 			},
 			// Override built-in "required" to allow on types (default is FieldScope only)
 			{
 				Identifier: "required",
-				Scope:      AnyScope,
+				Scope:      markerscope.AnyScope,
 			},
 		},
-		CustomMarkers: []MarkerScopeRule{
+		CustomMarkers: []markerscope.MarkerScopeRule{
 			// Custom field-only marker
 			{
 				Identifier: "custom:field-only",
-				Scope:      FieldScope,
+				Scope:      markerscope.FieldScope,
 			},
 			// Custom type-only marker
 			{
 				Identifier: "custom:type-only",
-				Scope:      TypeScope,
+				Scope:      markerscope.TypeScope,
 			},
 			// Custom marker with string type constraint
 			{
 				Identifier: "custom:string-only",
-				Scope:      FieldScope,
-				TypeConstraint: &TypeConstraint{
-					AllowedSchemaTypes: []SchemaType{SchemaTypeString},
+				Scope:      markerscope.FieldScope,
+				TypeConstraint: &markerscope.TypeConstraint{
+					AllowedSchemaTypes: []markerscope.SchemaType{
+						markerscope.SchemaTypeString,
+					},
 				},
 			},
 			// Custom marker with integer type constraint
 			{
 				Identifier: "custom:integer-only",
-				Scope:      FieldScope,
-				TypeConstraint: &TypeConstraint{
-					AllowedSchemaTypes: []SchemaType{SchemaTypeInteger},
+				Scope:      markerscope.FieldScope,
+				TypeConstraint: &markerscope.TypeConstraint{
+					AllowedSchemaTypes: []markerscope.SchemaType{
+						markerscope.SchemaTypeInteger,
+					},
 				},
 			},
 			// Custom marker with array of strings constraint
 			{
 				Identifier: "custom:string-array",
-				Scope:      FieldScope,
-				TypeConstraint: &TypeConstraint{
-					AllowedSchemaTypes: []SchemaType{SchemaTypeArray},
-					ElementConstraint: &TypeConstraint{
-						AllowedSchemaTypes: []SchemaType{SchemaTypeString},
+				Scope:      markerscope.FieldScope,
+				TypeConstraint: &markerscope.TypeConstraint{
+					AllowedSchemaTypes: []markerscope.SchemaType{
+						markerscope.SchemaTypeArray,
+					},
+					ElementConstraint: &markerscope.TypeConstraint{
+						AllowedSchemaTypes: []markerscope.SchemaType{
+							markerscope.SchemaTypeString,
+						},
 					},
 				},
 			},
 		},
 	}
-	analyzer := newAnalyzer(cfg)
+	analyzer, err := markerscope.Initializer().Init(cfg)
+	if err != nil {
+		t.Fatal(err)
+	}
 	analysistest.Run(t, testdata, analyzer, "b")
 }

pkg/analysis/markerscope/doc.go

@@ -14,13 +14,33 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-// Package markerscope provides a linter that validates markers are applied in the correct scope.
+// Package markerscope provides a linter that validates markers are applied in the correct scope
+// and to compatible data types.
+//
+// # Scope Validation
 //
 // Some markers are only valid when applied to specific Go constructs:
-// - Field-only markers: optional, required, nullable
-// - Type/Struct-only markers: MinProperties, MaxProperties, kubebuilder:object:root, kubebuilder:subresource:status
-// - Field or Type markers: default, MinLength, MaxLength, etc.
+//   - Field-only markers: optional, required, nullable
+//   - Type/Struct-only markers: MinProperties, MaxProperties, kubebuilder:object:root, kubebuilder:subresource:status
+//   - Field or Type markers: default, MinLength, MaxLength, etc.
+//
+// # Type Constraint Validation
+//
+// Markers are also validated for type correctness to ensure they are applied to compatible data types:
+//   - Numeric markers (Minimum, Maximum, MultipleOf) must be applied to integer or number types
+//   - String markers (Pattern, MinLength, MaxLength) must be applied to string types
+//   - Array markers (MinItems, MaxItems, UniqueItems) must be applied to array types
+//   - Object markers (MinProperties, MaxProperties) must be applied to object types (struct/map)
+//
+// For example, applying kubebuilder:validation:Maximum to a string field will be flagged as an error
+// since Maximum is only valid for numeric types.
+//
+// # Array Element Type Constraints
+//
+// For array types, element-level constraints can be specified using items: prefix markers
+// (e.g., items:Minimum, items:Pattern). These validate the array element types rather than
+// the array itself.
 //
-// This linter ensures markers are applied in their appropriate contexts to prevent
-// configuration errors and improve API consistency.
+// This linter ensures markers are applied in their appropriate contexts and to compatible types
+// to prevent configuration errors and improve API consistency.
 package markerscope

pkg/analysis/markerscope/initializer.go

@@ -34,7 +34,7 @@ func Initializer() initializer.AnalyzerInitializer {
 	return initializer.NewConfigurableInitializer(
 		name,
 		initAnalyzer,
-		false, // Not enabled by default
+		true,
 		validateConfig,
 	)
 }