feat: Add query analysis and index recommendations (Option 2, fixes #50) (#81)

Implement AnalyzeQuery() function that analyzes CEL expressions and
recommends PostgreSQL indexes to optimize query performance.

Features:
- Detects JSON/JSONB path operations → recommends GIN indexes
- Detects array operations and comprehensions → recommends GIN indexes
- Detects regex matching → recommends GIN indexes with pg_trgm
- Detects comparison operations → recommends B-tree indexes
- Returns complete CREATE INDEX statements with explanations

Implementation:
- New analysis.go with AnalyzeQuery() function
- IndexRecommendation struct with Column, IndexType, Expression, Reason
- Comprehensive test coverage in analysis_test.go
- Working example in examples/index_analysis/
- Updated README.md and CLAUDE.md with usage documentation

Testing:
- All tests pass (make test)
- Code passes linting (make lint)
- 72.5% code coverage

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude <noreply@anthropic.com>

Author: richardwooding

CLAUDE.md

@@ -210,6 +210,72 @@ sqlCondition, err := cel2sql.Convert(ast)
 // Returns: table.field = 'value' AND table.age > 30
 ```
 
+### Query Analysis and Index Recommendations
+
+cel2sql can analyze CEL expressions and recommend database indexes to optimize performance.
+
+#### Using AnalyzeQuery
+
+```go
+ast, issues := env.Compile(`person.age > 18 && person.metadata.verified == true`)
+if issues != nil && issues.Err() != nil {
+    return issues.Err()
+}
+
+sql, recommendations, err := cel2sql.AnalyzeQuery(ast,
+    cel2sql.WithSchemas(schemas))
+if err != nil {
+    return err
+}
+
+// Use the generated SQL
+rows, err := db.Query("SELECT * FROM people WHERE " + sql)
+
+// Review and apply index recommendations
+for _, rec := range recommendations {
+    fmt.Printf("Column: %s, Type: %s\n", rec.Column, rec.IndexType)
+    fmt.Printf("Reason: %s\n", rec.Reason)
+    fmt.Printf("Execute: %s\n\n", rec.Expression)
+}
+```
+
+#### Index Recommendation Types
+
+AnalyzeQuery detects patterns and recommends appropriate index types:
+
+- **B-tree indexes**: Comparison operations (`==, >, <, >=, <=`)
+  - Best for: Equality checks, range queries, sorting
+  - Example: `person.age > 18` → B-tree on `person.age`
+
+- **GIN indexes**: JSON/JSONB path operations, array operations
+  - Best for: JSON field access, array membership, containment
+  - Example: `person.metadata.verified == true` → GIN on `person.metadata`
+  - Example: `"premium" in person.tags` → GIN on `person.tags`
+
+- **GIN indexes with pg_trgm**: Regex pattern matching
+  - Best for: Text search, pattern matching, fuzzy matching
+  - Requires: PostgreSQL pg_trgm extension
+  - Example: `person.email.matches(r"@example\.com$")` → GIN on `person.email`
+
+#### IndexRecommendation Structure
+
+```go
+type IndexRecommendation struct {
+    Column     string  // Full column name (e.g., "person.metadata")
+    IndexType  string  // "BTREE", "GIN", or "GIST"
+    Expression string  // Complete CREATE INDEX statement
+    Reason     string  // Explanation of why this index is recommended
+}
+```
+
+#### When to Use
+
+- **Development**: Discover which indexes your queries need
+- **Performance tuning**: Identify missing indexes causing slow queries
+- **Production monitoring**: Analyze user-generated filter expressions
+
+See `examples/index_analysis/` for a complete working example.
+
 ### Logging and Observability
 
 cel2sql supports structured logging using Go's standard `log/slog` package (Go 1.21+).

README.md

@@ -119,6 +119,79 @@ sql, err := cel2sql.Convert(ast,
 - `WithLogger(*slog.Logger)` - Enable structured logging
 - `WithMaxDepth(int)` - Set custom recursion depth limit (default: 100)
 
+## Query Analysis and Index Recommendations
+
+cel2sql can analyze your CEL queries and recommend database indexes to optimize performance. The `AnalyzeQuery()` function returns both the converted SQL and actionable index recommendations.
+
+### How It Works
+
+`AnalyzeQuery()` examines your CEL expression and detects patterns that would benefit from specific PostgreSQL index types:
+
+- **JSON/JSONB path operations** (`->>, ?`) → GIN indexes
+- **Array operations** (comprehensions, `IN` clauses) → GIN indexes
+- **Regex matching** (`matches()`) → GIN indexes with `pg_trgm` extension
+- **Comparison operations** (`==, >, <, >=, <=`) → B-tree indexes
+
+### Usage
+
+```go
+sql, recommendations, err := cel2sql.AnalyzeQuery(ast,
+    cel2sql.WithSchemas(schemas))
+if err != nil {
+    log.Fatal(err)
+}
+
+// Use the generated SQL
+rows, err := db.Query("SELECT * FROM users WHERE " + sql)
+
+// Review and apply index recommendations
+for _, rec := range recommendations {
+    fmt.Printf("Column: %s\n", rec.Column)
+    fmt.Printf("Type: %s\n", rec.IndexType)
+    fmt.Printf("Reason: %s\n", rec.Reason)
+    fmt.Printf("Execute: %s\n\n", rec.Expression)
+
+    // Apply the recommendation
+    // _, err := db.Exec(rec.Expression)
+}
+```
+
+### Example
+
+```go
+// Query with multiple index-worthy patterns
+celExpr := `person.age > 18 &&
+            person.email.matches(r"@example\.com$") &&
+            person.metadata.verified == true`
+
+ast, _ := env.Compile(celExpr)
+sql, recs, _ := cel2sql.AnalyzeQuery(ast, cel2sql.WithSchemas(schemas))
+
+// Generated SQL:
+// person.age > 18 AND person.email ~ '@example\.com$'
+// AND person.metadata->>'verified' = 'true'
+
+// Recommendations:
+// 1. CREATE INDEX idx_person_age_btree ON table_name (person.age);
+//    Reason: Comparison operations benefit from B-tree for range queries
+//
+// 2. CREATE INDEX idx_person_email_gin_trgm ON table_name
+//    USING GIN (person.email gin_trgm_ops);
+//    Reason: Regex matching benefits from GIN index with pg_trgm
+//
+// 3. CREATE INDEX idx_person_metadata_gin ON table_name
+//    USING GIN (person.metadata);
+//    Reason: JSON path operations benefit from GIN index
+```
+
+### When to Use
+
+- **Development**: Discover which indexes your queries need
+- **Performance tuning**: Identify missing indexes causing slow queries
+- **Production monitoring**: Analyze user-generated filter expressions
+
+See `examples/index_analysis/` for a complete working example.
+
 ## Parameterized Queries
 
 cel2sql supports **parameterized queries** (prepared statements) for improved performance, security, and monitoring.