docs: add SQL validator and formatter tutorials (DOC-002)

Implemented the first two tutorials in a progressive tutorial series:

Tutorial 1: Building a SQL Validator for CI/CD
- Complete documentation in docs/tutorials/01-sql-validator-cicd.md
- Working example code in examples/tutorials/01-sql-validator/
- Features: file validation, directory scanning, error reporting, exit codes
- Integration examples for GitHub Actions, GitLab CI, and pre-commit hooks

Tutorial 2: Creating a SQL Formatter with Custom Rules
- Complete documentation in docs/tutorials/02-custom-sql-formatter.md
- Working example code in examples/tutorials/02-sql-formatter/
- Features: configurable formatting, keyword casing, indentation, operators
- Integration examples for pre-commit hooks and CI validation

Both tutorials are beginner-friendly, completable in <30 minutes each,
and include fully runnable, tested code examples.

Related to issue #58

Author: Ajit Pratap Singh

docs/tutorials/01-sql-validator-cicd.md

@@ -0,0 +1,29 @@
+name: Validate SQL Files
+
+on:
+  push:
+    branches: [ main, develop ]
+  pull_request:
+    branches: [ main, develop ]
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Set up Go
+      uses: actions/setup-go@v4
+      with:
+        go-version: '1.21'
+
+    - name: Build SQL Validator
+      run: |
+        cd examples/tutorials/01-sql-validator
+        go build -o sql-validator
+
+    - name: Validate SQL Files
+      run: |
+        cd examples/tutorials/01-sql-validator
+        ./sql-validator testdata/valid.sql

docs/tutorials/02-custom-sql-formatter.md

@@ -0,0 +1,65 @@
+# Tutorial 1: SQL Validator for CI/CD
+
+This is the working code example for Tutorial 1. It demonstrates how to build a SQL validator using GoSQLX.
+
+## Quick Start
+
+```bash
+# Build the validator
+go build -o sql-validator
+
+# Validate a single file
+./sql-validator testdata/valid.sql
+
+# Validate all SQL files in a directory
+./sql-validator testdata/
+```
+
+## What It Does
+
+This validator:
+- Scans directories recursively for `.sql` files
+- Validates SQL syntax using GoSQLX tokenizer and parser
+- Reports errors with detailed messages
+- Returns proper exit codes for CI/CD integration
+
+## Expected Output
+
+### Valid SQL File
+
+```
+Validating file: testdata/valid.sql
+
+=== SQL Validation Results ===
+
+✓ testdata/valid.sql
+
+=== Summary ===
+Total files: 1
+Valid: 1
+Invalid: 0
+
+All SQL files are valid!
+```
+
+### Invalid SQL File
+
+```
+Validating file: testdata/invalid.sql
+
+=== SQL Validation Results ===
+
+✗ testdata/invalid.sql
+  Error: parse error: ...
+
+=== Summary ===
+Total files: 1
+Valid: 0
+Invalid: 1
+```
+
+## Integration
+
+See `.github/workflows/validate.yml` for GitHub Actions integration example.
+
+For the complete tutorial, see: `docs/tutorials/01-sql-validator-cicd.md`

examples/tutorials/01-sql-validator/.github/workflows/validate.yml

@@ -0,0 +1,7 @@
+module github.com/ajitpratap0/GoSQLX/examples/tutorials/01-sql-validator
+
+go 1.24.0
+
+replace github.com/ajitpratap0/GoSQLX => ../../../
+
+require github.com/ajitpratap0/GoSQLX v0.0.0-00010101000000-000000000000

examples/tutorials/01-sql-validator/README.md

@@ -0,0 +1,55 @@
+package main
+
+import (
+	"fmt"
+	"os"
+)
+
+func main() {
+	if len(os.Args) < 2 {
+		fmt.Println("Usage: sql-validator <file-or-directory>")
+		fmt.Println("\nExamples:")
+		fmt.Println("  sql-validator query.sql")
+		fmt.Println("  sql-validator ./migrations")
+		fmt.Println("  sql-validator .")
+		os.Exit(1)
+	}
+
+	target := os.Args[1]
+
+	// Check if target exists
+	info, err := os.Stat(target)
+	if err != nil {
+		fmt.Printf("Error: %v\n", err)
+		os.Exit(1)
+	}
+
+	var results []ValidationResult
+
+	// Process file or directory
+	if info.IsDir() {
+		fmt.Printf("Scanning directory: %s\n", target)
+		results, err = ValidateDirectory(target)
+		if err != nil {
+			fmt.Printf("Error scanning directory: %v\n", err)
+			os.Exit(1)
+		}
+	} else {
+		fmt.Printf("Validating file: %s\n", target)
+		result := ValidateFile(target)
+		results = []ValidationResult{result}
+	}
+
+	// Print results
+	PrintResults(results)
+
+	// Exit with error code if any files are invalid
+	for _, result := range results {
+		if !result.Valid {
+			os.Exit(1)
+		}
+	}
+
+	fmt.Println("\nAll SQL files are valid!")
+	os.Exit(0)
+}

examples/tutorials/01-sql-validator/go.mod

@@ -0,0 +1,2 @@
+SELECT id, name, email
+WHERE active = true;

examples/tutorials/01-sql-validator/main.go

@@ -0,0 +1,4 @@
+SELECT id, name, email
+FROM users
+WHERE active = true
+ORDER BY created_at DESC;

examples/tutorials/01-sql-validator/testdata/invalid.sql

@@ -0,0 +1,132 @@
+package main
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/ajitpratap0/GoSQLX/pkg/sql/parser"
+	"github.com/ajitpratap0/GoSQLX/pkg/sql/tokenizer"
+)
+
+// ValidationResult holds the result of validating a single SQL file
+type ValidationResult struct {
+	FilePath string
+	Valid    bool
+	Error    error
+}
+
+// ValidateFile validates a single SQL file
+func ValidateFile(filePath string) ValidationResult {
+	// Read the file
+	content, err := os.ReadFile(filePath)
+	if err != nil {
+		return ValidationResult{
+			FilePath: filePath,
+			Valid:    false,
+			Error:    fmt.Errorf("failed to read file: %w", err),
+		}
+	}
+
+	// Get tokenizer from pool
+	tkz := tokenizer.GetTokenizer()
+	defer tokenizer.PutTokenizer(tkz)
+
+	// Tokenize the SQL
+	tokens, err := tkz.Tokenize(content)
+	if err != nil {
+		return ValidationResult{
+			FilePath: filePath,
+			Valid:    false,
+			Error:    fmt.Errorf("tokenization error: %w", err),
+		}
+	}
+
+	// Convert tokens for parser
+	parserTokens, err := parser.ConvertTokensForParser(tokens)
+	if err != nil {
+		return ValidationResult{
+			FilePath: filePath,
+			Valid:    false,
+			Error:    fmt.Errorf("token conversion error: %w", err),
+		}
+	}
+
+	// Create parser
+	p := parser.NewParser()
+	defer p.Release()
+
+	// Parse the tokens
+	_, err = p.Parse(parserTokens)
+	if err != nil {
+		return ValidationResult{
+			FilePath: filePath,
+			Valid:    false,
+			Error:    fmt.Errorf("parse error: %w", err),
+		}
+	}
+
+	return ValidationResult{
+		FilePath: filePath,
+		Valid:    true,
+		Error:    nil,
+	}
+}
+
+// ValidateDirectory recursively validates all .sql files in a directory
+func ValidateDirectory(dirPath string) ([]ValidationResult, error) {
+	var results []ValidationResult
+
+	err := filepath.Walk(dirPath, func(path string, info os.FileInfo, err error) error {
+		if err != nil {
+			return err
+		}
+
+		// Skip directories
+		if info.IsDir() {
+			return nil
+		}
+
+		// Only process .sql files
+		if !strings.HasSuffix(strings.ToLower(path), ".sql") {
+			return nil
+		}
+
+		// Validate the file
+		result := ValidateFile(path)
+		results = append(results, result)
+
+		return nil
+	})
+
+	if err != nil {
+		return nil, fmt.Errorf("failed to walk directory: %w", err)
+	}
+
+	return results, nil
+}
+
+// PrintResults prints validation results in a user-friendly format
+func PrintResults(results []ValidationResult) {
+	validCount := 0
+	invalidCount := 0
+
+	fmt.Println("\n=== SQL Validation Results ===\n")
+
+	for _, result := range results {
+		if result.Valid {
+			fmt.Printf("✓ %s\n", result.FilePath)
+			validCount++
+		} else {
+			fmt.Printf("✗ %s\n", result.FilePath)
+			fmt.Printf("  Error: %v\n\n", result.Error)
+			invalidCount++
+		}
+	}
+
+	fmt.Printf("\n=== Summary ===\n")
+	fmt.Printf("Total files: %d\n", len(results))
+	fmt.Printf("Valid: %d\n", validCount)
+	fmt.Printf("Invalid: %d\n", invalidCount)
+}

examples/tutorials/01-sql-validator/testdata/valid.sql

@@ -0,0 +1,9 @@
+repos:
+  - repo: local
+    hooks:
+      - id: format-sql
+        name: Format SQL Files
+        entry: sql-formatter format -i
+        language: system
+        files: \.sql$
+        pass_filenames: true