docs(gosqlx): refresh pkg.go.dev docs for ParseTree and extend examples

doc.go

@@ -24,15 +24,24 @@
 //   - Performance: 1.38M+ ops/sec sustained with memory-efficient pooling
 //   - International: Full Unicode/UTF-8 support for global SQL processing
 //   - Reliability: 95%+ success rate on real-world SQL queries
-//   - Standards: Multi-dialect SQL compatibility (PostgreSQL, MySQL, SQL Server, Oracle, SQLite)
+//   - Standards: Multi-dialect SQL compatibility (PostgreSQL, MySQL, MariaDB, SQL Server, Oracle, SQLite, Snowflake, ClickHouse)
 //   - SQL Compliance: ~80-85% SQL-99 compliance (window functions, CTEs, set operations)
 //   - Test Coverage: AST package 73.4%, Models package 100%
 //
+// Recommended API (v1.15.0+):
+//
+//	tree, err := gosqlx.ParseTree(ctx, sql, gosqlx.WithDialect("postgresql"))
+//	if err != nil {
+//	    return err
+//	}
+//	defer tree.Release()
+//	tables := tree.Tables()
+//
 // Core Features:
 //
 // - Zero-copy tokenization for optimal performance
 // - Object pooling for 60-80% memory reduction
-// - Multi-dialect SQL support (PostgreSQL, MySQL, SQL Server, Oracle, SQLite)
+// - Multi-dialect SQL support (PostgreSQL, MySQL, MariaDB, SQL Server, Oracle, SQLite, Snowflake, ClickHouse)
 // - Thread-safe implementation with linear scaling to 128+ cores
 // - Full Unicode/UTF-8 support for international SQL
 // - Performance monitoring and metrics collection
@@ -88,7 +97,7 @@
 //	gosqlx analyze complex_query.sql                  // Advanced analysis (1M+ queries/sec)
 //	gosqlx parse -f json query.sql                    // AST generation (JSON/YAML output)
 //	gosqlx lsp                                        // Start LSP server for IDE integration
-//	gosqlx lint --config .gosqlx.yml src/**/*.sql     // SQL linting with 10 rules (L001-L010)
+//	gosqlx lint --config .gosqlx.yml src/**/*.sql     // SQL linting with 30 rules (L001-L030)
 //
 // Configuration (.gosqlx.yml):
 //
@@ -220,7 +229,7 @@
 //   - pkg/errors: Structured error handling with position tracking
 //
 // Analysis and Tooling:
-//   - pkg/linter: SQL linting with 10 built-in rules (L001-L010)
+//   - pkg/linter: SQL linting with 30 built-in rules (L001-L030)
 //   - pkg/sql/security: SQL injection detection with severity classification
 //   - pkg/metrics: Performance monitoring and observability
 //   - pkg/lsp: Language Server Protocol server for IDE integration
@@ -251,13 +260,13 @@
 //
 // # SQL Linting
 //
-// Built-in linting rules (L001-L010):
+// Built-in linting rules (L001-L030):
 //   - L001: Enforce uppercase keywords
 //   - L002: Consistent indentation
 //   - L003: Avoid SELECT *
 //   - L004: Consistent alias style
 //   - L005: Trailing whitespace
-//   - L006-L010: Additional style rules
+//   - L006-L030: Additional style, safety and performance rules
 //
 // See docs/LINTING_RULES.md for complete linting reference.
 //

pkg/gosqlx/doc.go

@@ -17,7 +17,9 @@
 //
 // GoSQLX is a production-ready, high-performance SQL parsing SDK for Go that supports
 // multiple SQL dialects with comprehensive SQL-99 and SQL:2003 feature support.
-// The primary entry points are Parse, Validate, Format, and ParseWithDialect.
+// The recommended entry point is ParseTree (v1.15.0+), which returns an opaque *Tree
+// with helpers for walking, extracting metadata, rewriting and formatting. The
+// original Parse, Validate, Format and ParseWithDialect functions remain supported.
 //
 // # Overview
 //
@@ -27,6 +29,8 @@
 // fine-grained performance control.
 //
 // Key functions:
+//   - ParseTree: parses SQL into an opaque *Tree configured with functional options
+//     (WithDialect, WithStrict, WithTimeout, WithRecovery); recommended for new code
 //   - Parse: tokenizes and parses SQL, returning an *ast.AST
 //   - Validate: checks whether SQL is syntactically valid without building a full AST
 //   - Format: formats SQL text according to configurable style options
@@ -44,10 +48,10 @@
 //   - Memory Efficient: 60-80% reduction through intelligent object pooling
 //   - Thread-Safe: Race-free, validated with comprehensive concurrent testing
 //   - Zero-Copy: Direct byte slice operations with <1μs latency
-//   - Multi-Dialect: PostgreSQL, MySQL, SQL Server, Oracle, SQLite support
+//   - Multi-Dialect: PostgreSQL, MySQL, MariaDB, SQL Server, Oracle, SQLite, Snowflake, ClickHouse
 //   - Production-Ready: ~80-85% SQL-99 compliance, battle-tested
 //
-// # Supported SQL Features (v1.6.0)
+// # Supported SQL Features
 //
 // SQL Standards Compliance:
 //   - DML: SELECT, INSERT, UPDATE, DELETE with complex expressions
@@ -115,7 +119,27 @@
 //
 // # Quick Start
 //
-// Basic SQL parsing:
+// Parse into a Tree (recommended). Options are functional, and errors wrap
+// sentinels (ErrTokenize, ErrSyntax, ErrTimeout, ErrUnsupportedDialect) that work
+// with errors.Is:
+//
+//	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
+//	defer cancel()
+//	tree, err := gosqlx.ParseTree(ctx, "SELECT id, name FROM users WHERE active = true",
+//	    gosqlx.WithDialect("postgresql"),
+//	)
+//	if err != nil {
+//	    log.Fatal(err)
+//	}
+//	defer tree.Release()
+//	fmt.Println(tree.Tables())   // [users]
+//	fmt.Println(tree.Columns())  // [active id name]
+//	fmt.Println(tree.Format())   // formatted SQL, no re-parse
+//
+// Tree also provides Walk, Functions, Statements, Rewrite, Clone and Raw (an
+// escape hatch to the underlying *ast.AST).
+//
+// Basic SQL parsing with the original API:
 //
 //	sql := "SELECT * FROM users WHERE active = true"
 //	ast, err := gosqlx.Parse(sql)
@@ -424,7 +448,7 @@
 //   - docs/GETTING_STARTED.md - Quick start guide for new users
 //   - docs/USAGE_GUIDE.md - Comprehensive usage guide
 //   - docs/LSP_GUIDE.md - LSP server and IDE integration
-//   - docs/LINTING_RULES.md - All 10 linting rules (L001-L010)
+//   - docs/LINTING_RULES.md - All 30 linting rules (L001-L030)
 //   - docs/CONFIGURATION.md - Configuration file reference
 //   - docs/SQL_COMPATIBILITY.md - SQL dialect compatibility matrix
 //
@@ -460,7 +484,7 @@
 //	├── models/          # Core data structures (100% test coverage)
 //	├── errors/          # Structured error handling
 //	├── metrics/         # Performance monitoring
-//	├── linter/          # SQL linting engine (10 rules)
+//	├── linter/          # SQL linting engine (30 rules)
 //	└── lsp/             # Language Server Protocol server
 //
 // For fine-grained control, use the lower-level packages directly.

pkg/gosqlx/example_test.go

@@ -16,6 +16,7 @@ package gosqlx_test
 
 import (
 	"context"
+	"errors"
 	"fmt"
 	"log"
 	"time"
@@ -693,3 +694,58 @@ func Example_extractWindowFunctions() {
 	fmt.Printf("Window functions found: %d\n", len(functions))
 	// Output: Window functions found: 2
 }
+
+// ExampleParseTree demonstrates the recommended entry point: ParseTree returns
+// an opaque Tree with metadata helpers, so no AST import is required.
+func ExampleParseTree() {
+	tree, err := gosqlx.ParseTree(context.Background(),
+		"SELECT u.id, u.name FROM users u WHERE u.active = true")
+	if err != nil {
+		log.Fatal(err)
+	}
+	defer tree.Release()
+
+	fmt.Println("tables:", tree.Tables())
+	// Output: tables: [users]
+}
+
+// ExampleParseTree_dialect demonstrates functional options and sentinel errors.
+func ExampleParseTree_dialect() {
+	_, err := gosqlx.ParseTree(context.Background(), "SELECT 1",
+		gosqlx.WithDialect("postgresql"))
+	fmt.Println("postgresql error:", err)
+
+	_, err = gosqlx.ParseTree(context.Background(), "SELECT FROM WHERE")
+	fmt.Println("syntax error:", errors.Is(err, gosqlx.ErrSyntax))
+	// Output:
+	// postgresql error: <nil>
+	// syntax error: true
+}
+
+// ExampleTree_Format demonstrates rendering a parsed Tree back to SQL without
+// re-parsing.
+func ExampleTree_Format() {
+	tree, err := gosqlx.ParseTree(context.Background(), "select id from users")
+	if err != nil {
+		log.Fatal(err)
+	}
+	defer tree.Release()
+
+	fmt.Println(tree.Format(gosqlx.WithUppercaseKeywords(true)))
+	// Output:
+	// SELECT id
+	// FROM users
+}
+
+// ExampleTree_Functions demonstrates extracting function names from a Tree.
+func ExampleTree_Functions() {
+	tree, err := gosqlx.ParseTree(context.Background(),
+		"SELECT COUNT(*) FROM orders")
+	if err != nil {
+		log.Fatal(err)
+	}
+	defer tree.Release()
+
+	fmt.Println("functions:", tree.Functions())
+	// Output: functions: [COUNT]
+}