feat(p3): CLI watch registration, pool stats API, JSON function parsing (#458 #459 #460)

Part A (#458): Register watch command in CLI root
- Added cmd/gosqlx/cmd/watch_cmd.go with cobra command wrapping existing FileWatcher
- Supports --mode (validate|format), --debounce, --clear, --watch-verbose flags
- gosqlx watch now appears in --help output

Part B (#460): Pool utilization stats API
- Added pkg/metrics/pool_stats.go: PoolStat struct, RecordNamedPoolGet/Put, GetPoolStats, ResetPoolStats
- Instrumented tokenizer, parser, and AST pools with RecordNamedPoolGet/Put calls
- Added cmd/gosqlx/cmd/stats.go: gosqlx stats command with human-readable table and --json flag
- Added pkg/metrics/pool_stats_test.go with 8 race-safe tests including concurrent safety

Part C (#459): JSON function parsing tests
- Added pkg/sql/parser/json_functions_test.go: 12 tests covering JSON_OBJECT, JSON_BUILD_ARRAY,
  JSON_EXTRACT, JSON_AGG, JSON_BUILD_OBJECT, JSON_VALUE, JSON_CONTAINS, JSON_SET, JSONB_AGG,
  TO_JSON, JSON_ARRAYAGG, JSON_LENGTH, and arrow operators (all PASS)
- Parser already handles JSON functions as generic FunctionCall nodes

Co-authored-by: Ajit Pratap Singh <ajitpratapsingh@Ajits-Mac-mini-2655.local>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: 3 people

cmd/gosqlx/cmd/stats.go

@@ -0,0 +1,74 @@
+// Copyright 2026 GoSQLX Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// 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 cmd
+
+import (
+	"encoding/json"
+	"fmt"
+	"sort"
+
+	"github.com/spf13/cobra"
+
+	"github.com/ajitpratap0/GoSQLX/pkg/metrics"
+)
+
+// statsCmd shows current object pool utilization counters.
+var statsCmd = &cobra.Command{
+	Use:   "stats",
+	Short: "Show pool utilization statistics",
+	Long: `Display current object pool utilization counters.
+
+Shows gets (pool retrievals), puts (pool returns), and active (currently borrowed)
+counts for each named pool: tokenizer, parser, and ast.
+
+Examples:
+  gosqlx stats
+  gosqlx stats --json`,
+	RunE: func(cmd *cobra.Command, args []string) error {
+		jsonOutput, _ := cmd.Flags().GetBool("json")
+		stats := metrics.GetPoolStats()
+
+		if jsonOutput {
+			b, err := json.MarshalIndent(stats, "", "  ")
+			if err != nil {
+				return err
+			}
+			fmt.Fprintln(cmd.OutOrStdout(), string(b))
+			return nil
+		}
+
+		// Human-readable table
+		out := cmd.OutOrStdout()
+		fmt.Fprintf(out, "%-20s %10s %10s %10s\n", "POOL", "GETS", "PUTS", "ACTIVE")
+		fmt.Fprintf(out, "%-20s %10s %10s %10s\n", "----", "----", "----", "------")
+
+		names := make([]string, 0, len(stats))
+		for k := range stats {
+			names = append(names, k)
+		}
+		sort.Strings(names)
+
+		for _, name := range names {
+			s := stats[name]
+			fmt.Fprintf(out, "%-20s %10d %10d %10d\n", name, s.Gets, s.Puts, s.Active())
+		}
+		return nil
+	},
+}
+
+func init() {
+	statsCmd.Flags().Bool("json", false, "Output as JSON")
+	rootCmd.AddCommand(statsCmd)
+}

cmd/gosqlx/cmd/watch_cmd.go

@@ -0,0 +1,74 @@
+// Copyright 2026 GoSQLX Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// 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 cmd
+
+import (
+	"github.com/spf13/cobra"
+)
+
+// watchCmd is the cobra command that registers the watch subcommand.
+// The FileWatcher implementation lives in watch.go.
+var watchCmd = &cobra.Command{
+	Use:   "watch [file|dir...]",
+	Short: "Watch SQL files and re-validate or re-format on change",
+	Long: `Watch SQL files or directories and automatically re-process them when changes are detected.
+
+Supports two modes:
+  • validate (default): Re-run SQL validation on every file change
+  • format: Re-format SQL files in-place on every file change
+
+Examples:
+  gosqlx watch *.sql
+  gosqlx watch --mode format queries/
+  gosqlx watch --debounce 500 schema.sql migrations/`,
+	RunE: func(cmd *cobra.Command, args []string) error {
+		if len(args) == 0 {
+			return cmd.Help()
+		}
+
+		modeStr, _ := cmd.Flags().GetString("mode")
+		debounce, _ := cmd.Flags().GetInt("debounce")
+		clear, _ := cmd.Flags().GetBool("clear")
+		watchVerbose, _ := cmd.Flags().GetBool("watch-verbose")
+
+		mode := WatchModeValidate
+		if modeStr == "format" {
+			mode = WatchModeFormat
+		}
+
+		opts := WatchOptions{
+			Mode:        mode,
+			DebounceMs:  debounce,
+			ClearScreen: clear,
+			Verbose:     watchVerbose,
+			Out:         cmd.OutOrStdout(),
+			Err:         cmd.ErrOrStderr(),
+		}
+
+		fw, err := NewFileWatcher(opts)
+		if err != nil {
+			return err
+		}
+		return fw.Watch(args)
+	},
+}
+
+func init() {
+	watchCmd.Flags().String("mode", "validate", "watch mode: validate or format")
+	watchCmd.Flags().Int("debounce", 300, "debounce delay in milliseconds")
+	watchCmd.Flags().Bool("clear", false, "clear screen before each re-run")
+	watchCmd.Flags().Bool("watch-verbose", false, "verbose output from watcher")
+	rootCmd.AddCommand(watchCmd)
+}

pkg/metrics/pool_stats.go

@@ -0,0 +1,111 @@
+// Copyright 2026 GoSQLX Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// 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 metrics
+
+import (
+	"sync"
+	"sync/atomic"
+)
+
+// PoolStat holds utilization counters for a single named object pool.
+// Gets counts total Get() calls (items retrieved), Puts counts total Put() calls
+// (items returned). Active() returns an estimate of currently borrowed items.
+type PoolStat struct {
+	Gets int64 `json:"gets"` // total Get() calls
+	Puts int64 `json:"puts"` // total Put() calls
+}
+
+// Active returns an estimate of currently borrowed items (Gets - Puts).
+// May be negative during warm-up before items are returned to the pool.
+func (s PoolStat) Active() int64 {
+	return s.Gets - s.Puts
+}
+
+// poolCounter is the internal per-pool atomic counter pair.
+type poolCounter struct {
+	gets int64
+	puts int64
+}
+
+var (
+	poolStatsMu  sync.RWMutex
+	poolCounters = map[string]*poolCounter{}
+)
+
+// standardPoolNames are always pre-populated in GetPoolStats output.
+var standardPoolNames = []string{"tokenizer", "parser", "ast"}
+
+func getOrCreatePoolCounter(name string) *poolCounter {
+	poolStatsMu.RLock()
+	c, ok := poolCounters[name]
+	poolStatsMu.RUnlock()
+	if ok {
+		return c
+	}
+	poolStatsMu.Lock()
+	defer poolStatsMu.Unlock()
+	if c, ok = poolCounters[name]; ok {
+		return c
+	}
+	c = &poolCounter{}
+	poolCounters[name] = c
+	return c
+}
+
+// RecordNamedPoolGet records a Get() call for the named pool and returns the new total.
+// Call this immediately after retrieving an object from a sync.Pool.
+// This is safe for concurrent use and uses atomic operations.
+func RecordNamedPoolGet(name string) int64 {
+	c := getOrCreatePoolCounter(name)
+	return atomic.AddInt64(&c.gets, 1)
+}
+
+// RecordNamedPoolPut records a Put() call for the named pool and returns the new total.
+// Call this immediately before or after returning an object to a sync.Pool.
+// This is safe for concurrent use and uses atomic operations.
+func RecordNamedPoolPut(name string) int64 {
+	c := getOrCreatePoolCounter(name)
+	return atomic.AddInt64(&c.puts, 1)
+}
+
+// GetPoolStats returns a snapshot of all named pool counters.
+// The map is keyed by pool name. Standard pool names ("tokenizer", "parser", "ast")
+// are always present with zero values even if no operations have been recorded.
+// This function is safe for concurrent use.
+func GetPoolStats() map[string]PoolStat {
+	// Ensure standard pools are always present
+	for _, name := range standardPoolNames {
+		getOrCreatePoolCounter(name)
+	}
+
+	poolStatsMu.RLock()
+	defer poolStatsMu.RUnlock()
+	result := make(map[string]PoolStat, len(poolCounters))
+	for name, c := range poolCounters {
+		result[name] = PoolStat{
+			Gets: atomic.LoadInt64(&c.gets),
+			Puts: atomic.LoadInt64(&c.puts),
+		}
+	}
+	return result
+}
+
+// ResetPoolStats zeroes all named pool counters. Primarily intended for testing.
+// This is safe for concurrent use.
+func ResetPoolStats() {
+	poolStatsMu.Lock()
+	defer poolStatsMu.Unlock()
+	poolCounters = map[string]*poolCounter{}
+}

pkg/metrics/pool_stats_test.go

@@ -0,0 +1,125 @@
+// Copyright 2026 GoSQLX Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// 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 metrics_test
+
+import (
+	"testing"
+
+	"github.com/ajitpratap0/GoSQLX/pkg/metrics"
+)
+
+func TestPoolStats_ReturnsNonNilResult(t *testing.T) {
+	stats := metrics.GetPoolStats()
+	if stats == nil {
+		t.Fatal("GetPoolStats returned nil")
+	}
+}
+
+func TestPoolStats_HasTokenizerPool(t *testing.T) {
+	stats := metrics.GetPoolStats()
+	if _, ok := stats["tokenizer"]; !ok {
+		t.Error("expected 'tokenizer' key in pool stats")
+	}
+}
+
+func TestPoolStats_HasParserPool(t *testing.T) {
+	stats := metrics.GetPoolStats()
+	if _, ok := stats["parser"]; !ok {
+		t.Error("expected 'parser' key in pool stats")
+	}
+}
+
+func TestPoolStats_HasASTPool(t *testing.T) {
+	stats := metrics.GetPoolStats()
+	if _, ok := stats["ast"]; !ok {
+		t.Error("expected 'ast' key in pool stats")
+	}
+}
+
+func TestPoolStats_RecordGet(t *testing.T) {
+	metrics.ResetPoolStats()
+
+	_ = metrics.RecordNamedPoolGet("tokenizer")
+	_ = metrics.RecordNamedPoolPut("tokenizer")
+
+	stats := metrics.GetPoolStats()
+	ts, ok := stats["tokenizer"]
+	if !ok {
+		t.Fatal("missing tokenizer key after reset+record")
+	}
+	if ts.Gets < 1 {
+		t.Errorf("expected Gets >= 1 after RecordNamedPoolGet, got %d", ts.Gets)
+	}
+	if ts.Puts < 1 {
+		t.Errorf("expected Puts >= 1 after RecordNamedPoolPut, got %d", ts.Puts)
+	}
+}
+
+func TestPoolStats_ActiveCalculation(t *testing.T) {
+	metrics.ResetPoolStats()
+
+	metrics.RecordNamedPoolGet("parser")
+	metrics.RecordNamedPoolGet("parser")
+	metrics.RecordNamedPoolPut("parser")
+
+	stats := metrics.GetPoolStats()
+	ps := stats["parser"]
+	if ps.Gets != 2 {
+		t.Errorf("expected Gets=2, got %d", ps.Gets)
+	}
+	if ps.Puts != 1 {
+		t.Errorf("expected Puts=1, got %d", ps.Puts)
+	}
+	if ps.Active() != 1 {
+		t.Errorf("expected Active()=1, got %d", ps.Active())
+	}
+}
+
+func TestPoolStats_ResetClearsCounters(t *testing.T) {
+	metrics.RecordNamedPoolGet("ast")
+	metrics.ResetPoolStats()
+
+	stats := metrics.GetPoolStats()
+	// After reset, standard pools are recreated with zero values
+	as := stats["ast"]
+	if as.Gets != 0 {
+		t.Errorf("expected Gets=0 after reset, got %d", as.Gets)
+	}
+}
+
+func TestPoolStats_ConcurrentSafe(t *testing.T) {
+	metrics.ResetPoolStats()
+
+	done := make(chan struct{})
+	for i := 0; i < 100; i++ {
+		go func() {
+			metrics.RecordNamedPoolGet("tokenizer")
+			metrics.RecordNamedPoolPut("tokenizer")
+			done <- struct{}{}
+		}()
+	}
+	for i := 0; i < 100; i++ {
+		<-done
+	}
+
+	stats := metrics.GetPoolStats()
+	ts := stats["tokenizer"]
+	if ts.Gets != 100 {
+		t.Errorf("expected Gets=100, got %d", ts.Gets)
+	}
+	if ts.Puts != 100 {
+		t.Errorf("expected Puts=100, got %d", ts.Puts)
+	}
+}