Refactor struct field selection to Inspector helper

Author: JoelSpeed

pkg/analysis/helpers/inspector/analyzer.go

@@ -0,0 +1,51 @@
+package inspector
+
+import (
+	"errors"
+	"reflect"
+
+	"golang.org/x/tools/go/analysis"
+	"golang.org/x/tools/go/analysis/passes/inspect"
+	astinspector "golang.org/x/tools/go/ast/inspector"
+
+	"github.com/JoelSpeed/kal/pkg/analysis/helpers/extractjsontags"
+	"github.com/JoelSpeed/kal/pkg/analysis/helpers/markers"
+)
+
+const name = "inspector"
+
+var (
+	errCouldNotGetInspector = errors.New("could not get inspector")
+	errCouldNotGetJSONTags  = errors.New("could not get json tags")
+	errCouldNotGetMarkers   = errors.New("could not get markers")
+)
+
+// Analyzer is the analyzer for the inspector package.
+// It provides common functionality for analyzers that need to inspect fields and struct.
+// Abstracting away filtering of fields that the analyzers should and shouldn't be worrying about.
+var Analyzer = &analysis.Analyzer{
+	Name:       name,
+	Doc:        "Provides common functionality for analyzers that need to inspect fields and struct",
+	Run:        run,
+	Requires:   []*analysis.Analyzer{inspect.Analyzer, extractjsontags.Analyzer, markers.Analyzer},
+	ResultType: reflect.TypeOf(newInspector(nil, nil, nil)),
+}
+
+func run(pass *analysis.Pass) (interface{}, error) {
+	astinspector, ok := pass.ResultOf[inspect.Analyzer].(*astinspector.Inspector)
+	if !ok {
+		return nil, errCouldNotGetInspector
+	}
+
+	jsonTags, ok := pass.ResultOf[extractjsontags.Analyzer].(extractjsontags.StructFieldTags)
+	if !ok {
+		return nil, errCouldNotGetJSONTags
+	}
+
+	markersAccess, ok := pass.ResultOf[markers.Analyzer].(markers.Markers)
+	if !ok {
+		return nil, errCouldNotGetMarkers
+	}
+
+	return newInspector(astinspector, jsonTags, markersAccess), nil
+}

pkg/analysis/helpers/inspector/analyzer_test.go

@@ -0,0 +1,52 @@
+package inspector_test
+
+import (
+	"errors"
+	"go/ast"
+	"testing"
+
+	"github.com/JoelSpeed/kal/pkg/analysis/helpers/extractjsontags"
+	"github.com/JoelSpeed/kal/pkg/analysis/helpers/inspector"
+	"github.com/JoelSpeed/kal/pkg/analysis/helpers/markers"
+	"golang.org/x/tools/go/analysis"
+	"golang.org/x/tools/go/analysis/analysistest"
+)
+
+func TestInspector(t *testing.T) {
+	testdata := analysistest.TestData()
+
+	analysistest.Run(t, testdata, testAnalyzer, "a")
+}
+
+var errCouldNotGetInspector = errors.New("could not get inspector")
+
+var testAnalyzer = &analysis.Analyzer{
+	Name:     "test",
+	Doc:      "tests the inspector analyzer",
+	Run:      run,
+	Requires: []*analysis.Analyzer{inspector.Analyzer},
+}
+
+func run(pass *analysis.Pass) (interface{}, error) {
+	inspect, ok := pass.ResultOf[inspector.Analyzer].(inspector.Inspector)
+	if !ok {
+		return nil, errCouldNotGetInspector
+	}
+
+	inspect.InspectFields(func(field *ast.Field, stack []ast.Node, jsonTagInfo extractjsontags.FieldTagInfo, markersAccess markers.Markers) {
+		var fieldName string
+		if len(field.Names) > 0 {
+			fieldName = field.Names[0].Name
+		} else if ident, ok := field.Type.(*ast.Ident); ok {
+			fieldName = ident.Name
+		}
+
+		pass.Reportf(field.Pos(), "field: %v", fieldName)
+
+		if jsonTagInfo.Name != "" {
+			pass.Reportf(field.Pos(), "json tag: %v", jsonTagInfo.Name)
+		}
+	})
+
+	return nil, nil //nolint:nilnil
+}

pkg/analysis/helpers/inspector/doc.go

@@ -0,0 +1,34 @@
+/*
+inspector is a helper package that iterates over fields in structs, calling an inspection function on fields
+that should be considered for analysis.
+
+The inspector extracts common logic of iterating and filtering through struct fields, so that analyzers
+need not re-implement the same filtering over and over.
+
+For example, the inspector filters out struct definitions that are not type declarations, and fields that are ignored.
+
+Example:
+
+	type A struct {
+		// This field is included in the analysis.
+		Field string `json:"field"`
+
+		// This field, and the fields within are ignored due to the json tag.
+		F struct {
+			Field string `json:"field"`
+		} `json:"-"`
+	}
+
+	// Any struct defined within a function is ignored.
+	func Foo() {
+		type Bar struct {
+			Field string
+		}
+	}
+
+	// All fields within interface declarations are ignored.
+	type Bar interface {
+		Name() string
+	}
+*/
+package inspector

pkg/analysis/helpers/inspector/inspector.go

@@ -0,0 +1,87 @@
+package inspector
+
+import (
+	"go/ast"
+	"go/token"
+
+	"github.com/JoelSpeed/kal/pkg/analysis/helpers/extractjsontags"
+	"github.com/JoelSpeed/kal/pkg/analysis/helpers/markers"
+	astinspector "golang.org/x/tools/go/ast/inspector"
+)
+
+// Inspector is an interface that allows for the inspection of fields in structs.
+type Inspector interface {
+	// InspectFields is a function that iterates over fields in structs.
+	InspectFields(func(field *ast.Field, stack []ast.Node, jsonTagInfo extractjsontags.FieldTagInfo, markersAccess markers.Markers))
+}
+
+// inspector implements the Inspector interface.
+type inspector struct {
+	inspector *astinspector.Inspector
+	jsonTags  extractjsontags.StructFieldTags
+	markers   markers.Markers
+}
+
+// newInspector creates a new inspector.
+func newInspector(astinspector *astinspector.Inspector, jsonTags extractjsontags.StructFieldTags, markers markers.Markers) Inspector {
+	return &inspector{
+		inspector: astinspector,
+		jsonTags:  jsonTags,
+		markers:   markers,
+	}
+}
+
+// InspectFields iterates over fields in structs, ignoring any struct that is not a type declaration, and any field that is ignored and
+// therefore would not be included in the CRD spec.
+// For the remaining fields, it calls the provided inspectField function to apply analysis logic.
+func (i *inspector) InspectFields(inspectField func(field *ast.Field, stack []ast.Node, jsonTagInfo extractjsontags.FieldTagInfo, markersAccess markers.Markers)) {
+	// Filter to fields so that we can iterate over fields in a struct.
+	nodeFilter := []ast.Node{
+		(*ast.Field)(nil),
+	}
+
+	i.inspector.WithStack(nodeFilter, func(n ast.Node, push bool, stack []ast.Node) (proceed bool) {
+		if !push {
+			return false
+		}
+
+		if len(stack) < 3 {
+			return true
+		}
+
+		// The 0th node in the stack is the *ast.File.
+		// The 1st node in the stack is the *ast.GenDecl.
+		decl, ok := stack[1].(*ast.GenDecl)
+		if !ok {
+			// Make sure that we don't inspect structs within a function.
+			return false
+		}
+
+		if decl.Tok != token.TYPE {
+			// Returning false here means we won't inspect non-type declarations (e.g. var, const, import).
+			return false
+		}
+
+		_, ok = stack[len(stack)-3].(*ast.StructType)
+		if !ok {
+			// A field within a struct has a FieldList parent and then a StructType parent.
+			// If we don't have a StructType parent, then we're not in a struct.
+			return false
+		}
+
+		field, ok := n.(*ast.Field)
+		if !ok {
+			return true
+		}
+
+		tagInfo := i.jsonTags.FieldTags(field)
+		if tagInfo.Ignored {
+			// Returning false here means we won't inspect the children of an ignored field.
+			return false
+		}
+
+		inspectField(field, stack, tagInfo, i.markers)
+
+		return true
+	})
+}

pkg/analysis/helpers/inspector/testdata/src/a/a.go

@@ -0,0 +1,59 @@
+package A
+
+var (
+	String string
+)
+
+const (
+	Int int = 0
+)
+
+type A struct {
+	Field string `json:"field"` // want "field: Field" "json tag: field"
+
+	B `json:"b"` // want "field: B" "json tag: b"
+
+	C `json:",inline"` // want "field: C"
+
+	D `json:"-"`
+
+	E struct { // want "field: E" "json tag: e"
+		Field string `json:"field"` // want "field: Field" "json tag: field"
+	} `json:"e"`
+
+	F struct {
+		Field string `json:"field"`
+	} `json:"-"`
+}
+
+func (A) DoNothing() {}
+
+type B struct {
+	Field string `json:"field"` // want "field: Field" "json tag: field"
+}
+
+type (
+	C struct {
+		Field string `json:"field"` // want "field: Field" "json tag: field"
+	}
+
+	D struct {
+		Field string `json:"field"` // want "field: Field" "json tag: field"
+	}
+)
+
+func Foo() {
+	type Bar struct {
+		Field string
+	}
+}
+
+type Bar interface {
+	Name() string
+}
+
+var Var = struct {
+	Field string
+}{
+	Field: "field",
+}