'Dump' command

* Added a 'dump' command to allow dumping internal state/representation for manual inspection & debugging purposes

Dump command currently accepts only a `graph` subcommand and outputs only in `dot` format

* Removed some un-necessary code

* Removed log clutter during tests

* Updated `SymbolGraph.FindByKind` to accept 'rest' kinds

* Fixed a case of panic when encountering certain embedded fields in controllers

Author: yuval-po

cmd/dump.go

@@ -0,0 +1,167 @@
+package cmd
+
+import (
+	"fmt"
+	"os"
+	"strings"
+
+	"github.com/gopher-fleece/gleece/v2/core/pipeline"
+	"github.com/gopher-fleece/gleece/v2/definitions"
+	"github.com/gopher-fleece/gleece/v2/infrastructure/logger"
+	"github.com/spf13/cobra"
+)
+
+type DumpFormat string
+
+const (
+	DumpFormatDot   DumpFormat = "dot"
+	DumpFormatPlain DumpFormat = "plain"
+)
+
+var (
+	gleeceConfigPath string
+	dumpOutput       string
+	dumpFormat       string
+)
+
+// dumpCmd is a command used to dump information such as controllers, models, graph representations etc.
+var dumpCmd = &cobra.Command{
+	Use:   "dump",
+	Short: "Dumps information about a Gleece project",
+	Long: `The dump command returns information on the given Gleece project.
+This information is obtained by running the project through the analysis facilities`,
+}
+
+var graphCmd = &cobra.Command{
+	Use:   "graph",
+	Short: "Dumps the primary symbolic graph to a textual representation",
+	Long: `The 'graph' command can be used to dump a full representation of Gleece primary symbolic graph.
+This graph depict all entities and their relations and is most useful as means to visualize entity relations and dependencies`,
+	PreRunE: func(cmd *cobra.Command, args []string) error {
+		switch dumpFormat {
+		case string(DumpFormatDot), string(DumpFormatPlain), "":
+		default:
+			return fmt.Errorf("invalid --format: '%s' (want dot|plain)", dumpFormat)
+		}
+		return nil
+	},
+	RunE: func(cmd *cobra.Command, args []string) error {
+		err := dumpGraph(cmd)
+		if err != nil {
+			logger.Fatal("Failed to dump graph - %v", err)
+		}
+		return err
+	},
+}
+
+func initDumpCommandHierarchy() {
+	graphCmd.Flags().StringVarP(
+		&dumpFormat,
+		"format",
+		"f",
+		"dot",
+		"-f=dot",
+	)
+
+	dumpCmd.PersistentFlags().StringVarP(
+		&dumpOutput,
+		"output",
+		"o",
+		"",
+		"-o \"/target-directory/dump.dot\"",
+	)
+
+	dumpCmd.PersistentFlags().StringVarP(
+		&gleeceConfigPath,
+		"config",
+		"c",
+		"./gleece.config.json",
+		"-c \"/project-directory/gleece.config.json\"",
+	)
+
+	dumpCmd.AddCommand(graphCmd)
+}
+
+func resetDumpCommand() {
+	gleeceConfigPath = ""
+	dumpOutput = ""
+	dumpFormat = ""
+}
+
+func loadGleeceConfig(cmd *cobra.Command) (*definitions.GleeceConfig, error) {
+	gleeceConfigPath, err := cmd.Flags().GetString("config")
+	if err != nil {
+		logger.Error("Failed to read Gleece config location from CLI - %v", err)
+		return nil, fmt.Errorf("failed to read Gleece config location from CLI - %v", err)
+	}
+
+	trimmedPath := strings.Trim(gleeceConfigPath, "\"")
+	if trimmedPath == "" {
+		trimmedPath = "./gleece.config.json"
+		logger.Info("Gleece config path was no specified. Defaulting to '%s'", trimmedPath)
+	}
+
+	gleeceConfig, err := LoadGleeceConfig(trimmedPath)
+	if err != nil {
+		logger.Error("Failed to load Gleece config from '%s' - %v", trimmedPath, err)
+		return nil, fmt.Errorf("failed to load Gleece config from '%s' - %v", trimmedPath, err)
+	}
+
+	return gleeceConfig, nil
+
+}
+
+func getPipeline(cmd *cobra.Command) (*pipeline.GleecePipeline, error) {
+	gleeceConfig, err := loadGleeceConfig(cmd)
+	if err != nil {
+		return nil, err
+	}
+
+	pipe, err := pipeline.NewGleecePipeline(gleeceConfig)
+	if err != nil {
+		logger.Error("Failed to construct the analysis pipeline - %v", err)
+		return nil, fmt.Errorf("failed to construct the analysis pipeline - %v", err)
+	}
+
+	return &pipe, nil
+}
+
+func dumpGraph(cmd *cobra.Command) error {
+	logger.Info("Dumping graph to '%s' format", dumpFormat)
+	pipe, err := getPipeline(cmd)
+	if err != nil {
+		return err
+	}
+
+	err = pipe.GenerateGraph()
+	if err != nil {
+		logger.Error("Failed to construct a symbol graph for the project - %v", err)
+		return fmt.Errorf("failed to construct a symbol graph for the project - %v", err)
+	}
+
+	var text string
+	switch dumpFormat {
+	case string(DumpFormatDot):
+		text = pipe.Graph().ToDot(nil)
+	case string(DumpFormatPlain):
+		text = pipe.Graph().String()
+	default:
+		logger.Debug("Dump format not specified - defaulting to DOT")
+		text = pipe.Graph().ToDot(nil)
+	}
+
+	if dumpOutput == "" {
+		logger.Debug("Output not specified - using stdout")
+		cmd.Println(string(text))
+		return nil
+	}
+
+	logger.Debug("Writing %d bytes to '%s'", len(text), dumpOutput)
+	if err = os.WriteFile(dumpOutput, []byte(text), 0o644); err != nil {
+		logger.Error("Failed to write to '%s' - %v", dumpOutput, err)
+		return fmt.Errorf("failed to write to '%s' - %v", dumpOutput, err)
+	}
+
+	logger.Info("Graph successfully written to '%s'", dumpOutput)
+	return nil
+}

cmd/generate.go

@@ -10,8 +10,6 @@ import (
 var generateCmd = &cobra.Command{
 	Use:   "generate spec-and-routes --config \"/path/to/gleece.config.json\"",
 	Short: "Generate OpenAPI schema and routing middlewares from a Go project",
-	Run: func(cmd *cobra.Command, args []string) {
-	},
 }
 
 var specCommand = &cobra.Command{

cmd/root.go

@@ -28,7 +28,7 @@ var rootCmd = &cobra.Command{
 	),
 	PersistentPreRun: func(cmd *cobra.Command, args []string) {
 		if !cliArgs.NoBanner {
-			logger.Raw(arguments.GopherAscii)
+			fmt.Fprintln(cmd.OutOrStdout(), arguments.GopherAscii)
 		}
 
 		// This is basically safe as Cobra have already validated or provided default
@@ -47,6 +47,12 @@ var rootCmd = &cobra.Command{
 	},
 }
 
+func Reset() {
+	// There must be a better way to orchestrate this...
+	cliArgs = arguments.CliArguments{}
+	resetDumpCommand()
+}
+
 func Execute() {
 	err := rootCmd.Execute()
 	if err != nil {
@@ -92,6 +98,8 @@ func ExecuteWithArgs(args []string, redirectLogs bool) arguments.ExecuteWithArgs
 
 func init() {
 	initGenerateCommandHierarchy()
+	initDumpCommandHierarchy()
+
 	rootCmd.PersistentFlags().BoolVar(
 		&cliArgs.NoBanner,
 		"no-banner",
@@ -109,4 +117,5 @@ func init() {
 
 	rootCmd.AddCommand(versionCmd)
 	rootCmd.AddCommand(generateCmd)
+	rootCmd.AddCommand(dumpCmd)
 }

common/enumerations.go

@@ -1,5 +1,7 @@
 package common
 
+import "fmt"
+
 type SymKind string
 
 const (
@@ -150,3 +152,44 @@ func ToSpecialType(s string) (SpecialType, bool) {
 		return "", false
 	}
 }
+
+func ToSymbolKind(value string) (SymKind, error) {
+	switch value {
+	case string(SymKindUnknown):
+		return SymKindUnknown, nil
+	case string(SymKindPackage):
+		return SymKindPackage, nil
+	case string(SymKindStruct):
+		return SymKindStruct, nil
+	case string(SymKindController):
+		return SymKindController, nil
+	case string(SymKindInterface):
+		return SymKindInterface, nil
+	case string(SymKindAlias):
+		return SymKindAlias, nil
+	case string(SymKindEnum):
+		return SymKindEnum, nil
+	case string(SymKindEnumValue):
+		return SymKindEnumValue, nil
+	case string(SymKindFunction):
+		return SymKindFunction, nil
+	case string(SymKindReceiver):
+		return SymKindReceiver, nil
+	case string(SymKindField):
+		return SymKindField, nil
+	case string(SymKindParameter):
+		return SymKindParameter, nil
+	case string(SymKindVariable):
+		return SymKindVariable, nil
+	case string(SymKindConstant):
+		return SymKindConstant, nil
+	case string(SymKindReturnType):
+		return SymKindReturnType, nil
+	case string(SymKindBuiltin):
+		return SymKindBuiltin, nil
+	case string(SymKindSpecialBuiltin):
+		return SymKindSpecialBuiltin, nil
+	default:
+		return "", fmt.Errorf("invalid SymKind '%q'", value)
+	}
+}

gast/ast.utils.go

@@ -26,10 +26,13 @@ func IsFuncDeclReceiverForStruct(structName string, funcDecl *ast.FuncDecl) bool
 	case *ast.Ident:
 		return expr.Name == structName
 	case *ast.StarExpr:
-		return expr.X.(*ast.Ident).Name == structName
-	default:
-		return false
+		ident, isIdent := expr.X.(*ast.Ident)
+		if isIdent && ident.Name == structName {
+			return true
+		}
 	}
+
+	return false
 }
 
 // DoesStructEmbedStruct tests the given structToCheck in the *ast.File `sourceFile`

graphs/symboldg/graph.go

@@ -386,12 +386,29 @@ func (g *SymbolGraph) Exists(key graphs.SymbolKey) bool {
 	return g.Get(key) != nil
 }
 
-func (g *SymbolGraph) FindByKind(kind common.SymKind) []*SymbolNode {
-	var results []*SymbolNode
-
-	for _, node := range g.nodes {
-		if node.Kind == kind {
-			results = append(results, node)
+// FindByKinds searches the graph for nodes of the given kinds.
+//
+// Returns an empty slice if no matches were found.
+//
+// Nodes are returned by address and are *not* safe to mutate.
+func (g *SymbolGraph) FindByKind(kinds ...common.SymKind) []*SymbolNode {
+	results := []*SymbolNode{}
+
+	switch len(kinds) {
+	case 0:
+		return results
+	case 1:
+		for _, node := range g.nodes {
+			if node.Kind == kinds[0] {
+				results = append(results, node)
+			}
+		}
+	default:
+		kindsSet := mapset.NewThreadUnsafeSet(kinds...)
+		for _, node := range g.nodes {
+			if kindsSet.ContainsOne(node.Kind) {
+				results = append(results, node)
+			}
 		}
 	}
 

graphs/symboldg/interfaces.go

@@ -31,7 +31,7 @@ type SymbolGraphBuilder interface {
 	Exists(key graphs.SymbolKey) bool
 	Get(key graphs.SymbolKey) *SymbolNode
 	GetEdges(key graphs.SymbolKey, kinds []SymbolEdgeKind) map[string]SymbolEdgeDescriptor
-	FindByKind(kind common.SymKind) []*SymbolNode
+	FindByKind(kind... common.SymKind) []*SymbolNode
 
 	IsPrimitivePresent(primitive common.PrimitiveType) bool
 	IsSpecialPresent(special common.SpecialType) bool

infrastructure/logger/logger.go

@@ -1,6 +1,7 @@
 package logger
 
 import (
+	"flag"
 	"fmt"
 	"log"
 )
@@ -54,7 +55,10 @@ func getPrintPrefix(level LogLevel) string {
 // SetLogLevel Sets the logger's verbosity level
 func SetLogLevel(level LogLevel) {
 	verbosityLevel = level
-	System("Verbosity level set to %s\n", getPrintPrefix(level))
+	// This message is annoying during testing
+	if flag.Lookup("test.v") == nil {
+		System("Verbosity level set to %s\n", getPrintPrefix(level))
+	}
 }
 
 // GetLogLevel returns the logger's current verbosity level
@@ -63,7 +67,7 @@ func GetLogLevel() LogLevel {
 }
 
 // Prints a message, if level is greater to or equal to the currently set verbosity level
-func logger(level LogLevel, format string, v ...interface{}) {
+func logger(level LogLevel, format string, v ...any) {
 	if level >= verbosityLevel {
 		prefix := fmt.Sprintf("[%s]", getPrintPrefix(level))
 		message := fmt.Sprintf("%-8s %s", prefix, format)
@@ -72,34 +76,34 @@ func logger(level LogLevel, format string, v ...interface{}) {
 }
 
 // Prints a debug message
-func Debug(format string, v ...interface{}) {
+func Debug(format string, v ...any) {
 	logger(LogLevelDebug, format, v...)
 }
 
 // Prints an info message
-func Info(format string, v ...interface{}) {
+func Info(format string, v ...any) {
 	logger(LogLevelInfo, format, v...)
 }
 
 // Prints a warning message
-func Warn(format string, v ...interface{}) {
+func Warn(format string, v ...any) {
 	logger(LogLevelWarn, format, v...)
 }
 
 // Prints an error message
-func Error(format string, v ...interface{}) {
+func Error(format string, v ...any) {
 	logger(LogLevelError, format, v...)
 }
 
 // Prints a fatal message
-func Fatal(format string, v ...interface{}) {
+func Fatal(format string, v ...any) {
 	logger(LogLevelFatal, format, v...)
 }
 
-func System(format string, v ...interface{}) {
+func System(format string, v ...any) {
 	message := fmt.Sprintf("[SYSTEM] %s", format)
 	log.Printf(message, v...)
 }
-func Raw(format string, v ...interface{}) {
+func Raw(format string, v ...any) {
 	log.Printf(format, v...)
 }