refactor: split cmd/gosqlx/cmd/ god package — extract lsp, action, optimize into sub-packages

Extract the most independent subcommands (lsp, action, optimize) from the
13.7K LOC cmd/gosqlx/cmd/ god package into dedicated sub-packages under
cmd/gosqlx/internal/:

- cmd/gosqlx/internal/lspcmd/ — LSP server command (zero deps on cmd pkg)
- cmd/gosqlx/internal/actioncmd/ — GitHub Actions CI command (self-contained)
- cmd/gosqlx/internal/optimizecmd/ — SQL optimization command
- cmd/gosqlx/internal/cmdutil/ — shared utilities (stdin, input detection, flags)

Each sub-package exports a NewCmd() constructor returning *cobra.Command.
Root command registers them via rootCmd.AddCommand().

Remaining commands (validate, format, analyze, parse, lint, config, watch)
stay in cmd/gosqlx/cmd/ for now due to heavy cross-dependencies between
their types (ValidatorOptions, CLIFormatterOptions, etc.). These can be
split in follow-up PRs once shared types are extracted to cmdutil.

No behavior changes — pure structural refactor.

Author: Ajit Pratap Singh

cmd/gosqlx/cmd/root.go

@@ -2,6 +2,10 @@ package cmd
 
 import (
 	"github.com/spf13/cobra"
+
+	"github.com/ajitpratap0/GoSQLX/cmd/gosqlx/internal/actioncmd"
+	"github.com/ajitpratap0/GoSQLX/cmd/gosqlx/internal/lspcmd"
+	"github.com/ajitpratap0/GoSQLX/cmd/gosqlx/internal/optimizecmd"
 )
 
 // Version is the current version of gosqlx CLI.
@@ -159,4 +163,9 @@ func init() {
 	rootCmd.PersistentFlags().BoolVarP(&verbose, "verbose", "v", false, "enable verbose output")
 	rootCmd.PersistentFlags().StringVarP(&outputFile, "output", "o", "", "output file (default: stdout)")
 	rootCmd.PersistentFlags().StringVarP(&format, "format", "f", "auto", "output format: json, yaml, table, tree, auto")
+
+	// Register subcommands from internal packages
+	rootCmd.AddCommand(lspcmd.NewCmd())
+	rootCmd.AddCommand(actioncmd.NewCmd())
+	rootCmd.AddCommand(optimizecmd.NewCmd(&outputFile, &format))
 }

cmd/gosqlx/cmd/action.go cmd/gosqlx/internal/actioncmd/action.gocmd/gosqlx/cmd/action.go renamed to cmd/gosqlx/internal/actioncmd/action.go

@@ -1,4 +1,5 @@
-package cmd
+// Package actioncmd implements the gosqlx action subcommand for GitHub Actions CI.
+package actioncmd
 
 import (
 	"fmt"
@@ -26,12 +27,12 @@ var (
 	actionTimeout  int
 )
 
-// actionCmd implements the GitHub Actions entrypoint as a Go subcommand.
-// It finds SQL files, runs lint + validate, and outputs GitHub Actions annotations.
-var actionCmd = &cobra.Command{
-	Use:   "action",
-	Short: "Run GoSQLX checks for GitHub Actions CI",
-	Long: `Run SQL validation and linting with GitHub Actions annotation output.
+// NewCmd returns the action cobra.Command.
+func NewCmd() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "action",
+		Short: "Run GoSQLX checks for GitHub Actions CI",
+		Long: `Run SQL validation and linting with GitHub Actions annotation output.
 
 This command replaces the shell-based entrypoint for the GoSQLX GitHub Action.
 It finds SQL files matching a glob pattern, runs validation and linting on each,
@@ -43,20 +44,18 @@ Environment variables (also settable via flags):
   SEVERITY   - threshold: error, warning, info (default: warning)
   CONFIG     - path to .gosqlx.yml config file
   TIMEOUT    - per-file timeout in seconds (default: 600)`,
-	RunE: runAction,
-}
+		RunE: runAction,
+	}
 
-func init() {
-	actionCmd.Flags().StringVar(&actionFiles, "files", "", "glob pattern for SQL files (env: SQL_FILES)")
-	actionCmd.Flags().StringVar(&actionRules, "rules", "", "comma-separated lint rules (env: RULES)")
-	actionCmd.Flags().StringVar(&actionSeverity, "severity", "", "severity threshold: error, warning, info (env: SEVERITY)")
-	actionCmd.Flags().StringVar(&actionConfig, "config", "", "path to config file (env: CONFIG)")
-	actionCmd.Flags().IntVar(&actionTimeout, "timeout", 0, "per-file timeout in seconds (env: TIMEOUT)")
+	cmd.Flags().StringVar(&actionFiles, "files", "", "glob pattern for SQL files (env: SQL_FILES)")
+	cmd.Flags().StringVar(&actionRules, "rules", "", "comma-separated lint rules (env: RULES)")
+	cmd.Flags().StringVar(&actionSeverity, "severity", "", "severity threshold: error, warning, info (env: SEVERITY)")
+	cmd.Flags().StringVar(&actionConfig, "config", "", "path to config file (env: CONFIG)")
+	cmd.Flags().IntVar(&actionTimeout, "timeout", 0, "per-file timeout in seconds (env: TIMEOUT)")
 
-	rootCmd.AddCommand(actionCmd)
+	return cmd
 }
 
-// envDefault returns the flag value if non-empty, otherwise the env var, otherwise the fallback.
 func envDefault(flagVal, envKey, fallback string) string {
 	if flagVal != "" {
 		return flagVal
@@ -99,7 +98,6 @@ func runAction(_ *cobra.Command, _ []string) error {
 		}
 	}
 
-	// Find SQL files
 	files, err := findSQLFiles(pattern)
 	if err != nil {
 		return fmt.Errorf("finding SQL files: %w", err)
@@ -110,7 +108,6 @@ func runAction(_ *cobra.Command, _ []string) error {
 	}
 	fmt.Printf("Found %d SQL file(s)\n", len(files))
 
-	// Parse rules
 	var ruleList []string
 	if rules != "" {
 		for _, r := range strings.Split(rules, ",") {
@@ -134,7 +131,6 @@ func runAction(_ *cobra.Command, _ []string) error {
 	for _, file := range files {
 		displayFile := strings.TrimPrefix(file, "./")
 
-		// Validate
 		vErr := validateFileWithTimeout(file, timeout)
 		if vErr != nil {
 			validateErrors++
@@ -154,7 +150,6 @@ func runAction(_ *cobra.Command, _ []string) error {
 			totalValid++
 		}
 
-		// Lint
 		violations := lintFile(file, ruleList)
 		for _, v := range violations {
 			level := "notice"
@@ -169,7 +164,6 @@ func runAction(_ *cobra.Command, _ []string) error {
 		}
 	}
 
-	// Summary
 	fmt.Println()
 	fmt.Println("==============================")
 	fmt.Println("  GoSQLX Results Summary")
@@ -181,12 +175,10 @@ func runAction(_ *cobra.Command, _ []string) error {
 	fmt.Printf("  Lint warnings:      %d\n", lintWarnings)
 	fmt.Println("==============================")
 
-	// GitHub step summary
 	if summaryPath := os.Getenv("GITHUB_STEP_SUMMARY"); summaryPath != "" {
 		writeStepSummary(summaryPath, len(files), totalValid, validateErrors, lintErrors, lintWarnings)
 	}
 
-	// Exit code based on severity
 	fail := false
 	switch severity {
 	case "error":
@@ -201,7 +193,6 @@ func runAction(_ *cobra.Command, _ []string) error {
 	return nil
 }
 
-// ghAnnotation prints a GitHub Actions annotation.
 func ghAnnotation(level, file string, line int, msg string) {
 	params := ""
 	if file != "" {
@@ -217,7 +208,6 @@ func ghAnnotation(level, file string, line int, msg string) {
 	}
 }
 
-// extractLineNumber extracts a line number from text matching "line N".
 func extractLineNumber(re *regexp.Regexp, text string) int {
 	m := re.FindStringSubmatch(text)
 	if len(m) >= 2 {
@@ -227,15 +217,14 @@ func extractLineNumber(re *regexp.Regexp, text string) int {
 	return 0
 }
 
-// findSQLFiles locates SQL files matching the given glob pattern.
 func findSQLFiles(pattern string) ([]string, error) {
 	var files []string
 
 	switch {
 	case pattern == "**/*.sql":
 		err := filepath.Walk(".", func(path string, info os.FileInfo, err error) error {
 			if err != nil {
-				return nil // skip errors
+				return nil
 			}
 			if !info.IsDir() && strings.HasSuffix(strings.ToLower(path), ".sql") {
 				files = append(files, path)
@@ -256,7 +245,6 @@ func findSQLFiles(pattern string) ([]string, error) {
 			}
 		}
 	default:
-		// Try filepath.Glob first, fall back to Walk with path matching
 		matched, err := filepath.Glob(pattern)
 		if err == nil && len(matched) > 0 {
 			for _, m := range matched {
@@ -266,7 +254,6 @@ func findSQLFiles(pattern string) ([]string, error) {
 				}
 			}
 		} else {
-			// Walk and match with filepath.Match
 			err = filepath.Walk(".", func(path string, info os.FileInfo, walkErr error) error {
 				if walkErr != nil {
 					return nil
@@ -286,14 +273,12 @@ func findSQLFiles(pattern string) ([]string, error) {
 	return files, nil
 }
 
-// lintViolation represents a single lint finding.
 type lintViolation struct {
 	Line     int
 	Severity string
 	Message  string
 }
 
-// defaultLinter creates a linter with standard rules.
 func defaultLinter() *linter.Linter {
 	return linter.New(
 		whitespace.NewTrailingWhitespaceRule(),
@@ -303,7 +288,6 @@ func defaultLinter() *linter.Linter {
 	)
 }
 
-// lintFile runs the linter on a file and returns violations.
 func lintFile(filePath string, _ []string) []lintViolation {
 	l := defaultLinter()
 	result := l.LintFile(filePath)
@@ -327,7 +311,6 @@ func lintFile(filePath string, _ []string) []lintViolation {
 	return violations
 }
 
-// validateFileWithTimeout validates a SQL file with a timeout.
 func validateFileWithTimeout(filePath string, timeout time.Duration) error {
 	type result struct {
 		err error
@@ -351,7 +334,6 @@ func validateFileWithTimeout(filePath string, timeout time.Duration) error {
 	}
 }
 
-// writeStepSummary appends a markdown summary to the GitHub step summary file.
 func writeStepSummary(path string, total, valid, valErrors, lintErrors, lintWarnings int) {
 	f, err := os.OpenFile(filepath.Clean(path), os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0o600)
 	if err != nil {

cmd/gosqlx/internal/cmdutil/cmd_utils.go

@@ -0,0 +1,39 @@
+package cmdutil
+
+import (
+	"github.com/spf13/cobra"
+	"github.com/spf13/pflag"
+)
+
+// RootFlags holds pointers to the root command's persistent flag values.
+// Sub-packages receive this to access global flags without circular imports.
+type RootFlags struct {
+	Verbose    *bool
+	OutputFile *string
+	Format     *string
+}
+
+// Valid output format constants
+const (
+	OutputFormatText  = "text"
+	OutputFormatJSON  = "json"
+	OutputFormatSARIF = "sarif"
+)
+
+// ValidOutputFormats lists all supported output formats for validation
+var ValidOutputFormats = []string{OutputFormatText, OutputFormatJSON, OutputFormatSARIF}
+
+// TrackChangedFlags returns a map of flag names that were explicitly set on the command line.
+// This includes both local flags and parent persistent flags.
+func TrackChangedFlags(cmd *cobra.Command) map[string]bool {
+	flagsChanged := make(map[string]bool)
+	cmd.Flags().Visit(func(f *pflag.Flag) {
+		flagsChanged[f.Name] = true
+	})
+	if cmd.Parent() != nil && cmd.Parent().PersistentFlags() != nil {
+		cmd.Parent().PersistentFlags().Visit(func(f *pflag.Flag) {
+			flagsChanged[f.Name] = true
+		})
+	}
+	return flagsChanged
+}