Detect markers separated by blank lines from type declarations

- Modified marker analyzer to check the previous comment group
- Added extractOrphanedMarkers helper function
- Added test cases for List types and non-List types with blank lines

Signed-off-by: Sascha Grunert <[email protected]>

Author: saschagrunert

pkg/analysis/helpers/markers/analyzer.go

@@ -45,6 +45,11 @@ import (
 // is "k8s:item(one: "value", two: "value")=...".
 const UnnamedArgument = ""
 
+// maxMarkerSeparationLines is the maximum number of lines that can separate
+// a marker comment group from the godoc comment for it to still be considered
+// associated with the type declaration.
+const maxMarkerSeparationLines = 3
+
 // Markers allows access to markers extracted from the
 // go types.
 type Markers interface {
@@ -154,7 +159,16 @@ func run(pass *analysis.Pass) (any, error) {
 	inspect.Preorder(nodeFilter, func(n ast.Node) {
 		switch typ := n.(type) {
 		case *ast.GenDecl:
-			extractGenDeclMarkers(typ, results)
+			// Find the file this declaration belongs to
+			var file *ast.File
+			for _, f := range pass.Files {
+				if f.Pos() <= typ.Pos() && typ.End() <= f.End() {
+					file = f
+					break
+				}
+			}
+
+			extractGenDeclMarkers(typ, file, pass.Fset, results)
 		case *ast.Field:
 			extractFieldMarkers(typ, results)
 		}
@@ -163,15 +177,20 @@ func run(pass *analysis.Pass) (any, error) {
 	return results, nil
 }
 
-func extractGenDeclMarkers(typ *ast.GenDecl, results *markers) {
+func extractGenDeclMarkers(typ *ast.GenDecl, file *ast.File, fset *token.FileSet, results *markers) {
 	declMarkers := NewMarkerSet()
 
+	// Collect markers from the GenDecl's Doc field (comments directly attached to the declaration)
 	if typ.Doc != nil {
 		for _, comment := range typ.Doc.List {
 			if marker := extractMarker(comment); marker.Identifier != "" {
 				declMarkers.Insert(marker)
 			}
 		}
+
+		// Also collect markers from the comment group immediately before the godoc comment
+		// if separated by a blank line.
+		extractOrphanedMarkers(typ.Doc, file, fset, declMarkers)
 	}
 
 	if len(typ.Specs) == 0 {
@@ -190,6 +209,55 @@ func extractGenDeclMarkers(typ *ast.GenDecl, results *markers) {
 	}
 }
 
+// extractOrphanedMarkers finds markers in the comment group immediately before the godoc comment
+// that are separated by a blank line. Only the immediately preceding comment group is checked,
+// and it must be within maxMarkerSeparationLines lines of the godoc comment.
+//
+// This handles cases where markers are separated from type declarations by blank lines, such as:
+//
+//	// +kubebuilder:object:root=true
+//
+//	// MyType does something
+//	type MyType struct {}
+//
+// The root marker will be detected even though separated by a blank line from the godoc comment.
+func extractOrphanedMarkers(docGroup *ast.CommentGroup, file *ast.File, fset *token.FileSet, declMarkers MarkerSet) {
+	if file == nil || fset == nil {
+		return
+	}
+
+	// Find the index of the godoc comment group in the file's comment list
+	docIndex := -1
+
+	for i, cg := range file.Comments {
+		if cg == docGroup {
+			docIndex = i
+			break
+		}
+	}
+
+	// If there's no previous comment group, we're done
+	if docIndex <= 0 {
+		return
+	}
+
+	prevGroup := file.Comments[docIndex-1]
+	docStartLine := fset.Position(docGroup.Pos()).Line
+	prevEndLine := fset.Position(prevGroup.End()).Line
+
+	// Only consider the previous group if it's within maxMarkerSeparationLines of the godoc comment
+	if docStartLine-prevEndLine > maxMarkerSeparationLines {
+		return
+	}
+
+	// Extract markers from the previous comment group
+	for _, comment := range prevGroup.List {
+		if marker := extractMarker(comment); marker.Identifier != "" {
+			declMarkers.Insert(marker)
+		}
+	}
+}
+
 func extractFieldMarkers(field *ast.Field, results *markers) {
 	if field == nil || field.Doc == nil {
 		return

pkg/analysis/statussubresource/testdata/src/a/a.go

@@ -70,6 +70,20 @@ type ClusterList struct {
 	Items    []Cluster `json:"items"`
 }
 
+// Test marker detection with blank line (second level comment bug - issue #53)
+// +kubebuilder:object:root=true
+
+// ServiceList contains a list of Service.
+type ServiceList struct {
+	TypeMeta `json:",inline"`
+	ListMeta `json:"metadata,omitempty"`
+	Items    []Service `json:"items"`
+}
+
+type Service struct {
+	Name string `json:"name"`
+}
+
 type TypeMeta struct {
 	Kind       string `json:"kind,omitempty"`
 	APIVersion string `json:"apiVersion,omitempty"`
@@ -173,3 +187,21 @@ type ReorderedFieldsList struct {
 type ReorderedItem struct {
 	Name string `json:"name"`
 }
+
+// Test marker detection with blank line for non-List type (second level comment bug - issue #53)
+// This should trigger the linter because it has a status field but no status marker
+// +kubebuilder:object:root=true
+
+// BlankLineTest demonstrates marker detection across blank lines.
+type BlankLineTest struct { // want "root object type \"BlankLineTest\" has a status field but does not have the marker \"kubebuilder:subresource:status\" to enable the status subresource"
+	Spec   BlankLineTestSpec   `json:"spec"`
+	Status BlankLineTestStatus `json:"status"`
+}
+
+type BlankLineTestSpec struct {
+	Name string `json:"name"`
+}
+
+type BlankLineTestStatus struct {
+	Ready bool `json:"ready"`
+}

pkg/analysis/statussubresource/testdata/src/a/a.go.golden

@@ -71,6 +71,20 @@ type ClusterList struct {
 	Items    []Cluster `json:"items"`
 }
 
+// Test marker detection with blank line (second level comment bug - issue #53)
+// +kubebuilder:object:root=true
+
+// ServiceList contains a list of Service.
+type ServiceList struct {
+	TypeMeta `json:",inline"`
+	ListMeta `json:"metadata,omitempty"`
+	Items    []Service `json:"items"`
+}
+
+type Service struct {
+	Name string `json:"name"`
+}
+
 type TypeMeta struct {
 	Kind       string `json:"kind,omitempty"`
 	APIVersion string `json:"apiVersion,omitempty"`
@@ -178,3 +192,22 @@ type ReorderedFieldsList struct {
 type ReorderedItem struct {
 	Name string `json:"name"`
 }
+
+// Test marker detection with blank line for non-List type (second level comment bug - issue #53)
+// This should trigger the linter because it has a status field but no status marker
+// +kubebuilder:object:root=true
+
+// BlankLineTest demonstrates marker detection across blank lines.
+// +kubebuilder:subresource:status
+type BlankLineTest struct { // want "root object type \"BlankLineTest\" has a status field but does not have the marker \"kubebuilder:subresource:status\" to enable the status subresource"
+	Spec   BlankLineTestSpec   `json:"spec"`
+	Status BlankLineTestStatus `json:"status"`
+}
+
+type BlankLineTestSpec struct {
+	Name string `json:"name"`
+}
+
+type BlankLineTestStatus struct {
+	Ready bool `json:"ready"`
+}