feat: Add structured logging with log/slog for observability (#47)

Implements comprehensive structured logging using Go's standard log/slog
package (Go 1.21+). Logging is optional with zero overhead when disabled.

## Changes

### Core Infrastructure
- Added WithLogger() functional option to Convert()
- Default behavior uses slog.DiscardHandler (zero overhead)
- Added logger field to converter struct
- Performance metrics with conversion duration tracking

### Logging Points Added

1. **JSON Path Detection** (json.go)
   - shouldUseJSONPath: Logs table, field, and JSON detection results
   - buildJSONPath: Logs JSON path construction
   - buildJSONPathInternal: Logs operator selection (->>, ->)

2. **Comprehension Analysis** (comprehensions.go)
   - analyzeComprehensionPattern: Logs identified comprehension type
   - Logs for all, exists, exists_one, map, filter comprehensions
   - Includes iter_var, accu_var, and has_filter details

3. **Schema Lookups** (cel2sql.go)
   - isFieldJSON: Logs field type lookups with hits/misses
   - Logs when schemas not provided or table/field not found

4. **Operator Conversion** (cel2sql.go)
   - visitCallBinary: Logs CEL to SQL operator mapping

5. **Regex Conversion** (cel2sql.go)
   - callMatches: Logs RE2 to POSIX pattern transformation
   - Includes original pattern, converted pattern, case sensitivity

6. **Conversion Lifecycle** (cel2sql.go)
   - Start/completion events with duration metrics
   - Error logging with full context

### Testing
- Added 11 comprehensive tests in logging_test.go
- Tests cover JSON handler, text handler, all logging points
- Verifies zero overhead default behavior
- All existing tests pass

### Documentation
- Updated CLAUDE.md with logging section
- Added examples/logging/ with working example
- Demonstrates both JSON and text handlers
- README with integration guidance

### Example Usage

```go
// Zero overhead (default)
sql, err := cel2sql.Convert(ast)

// With logging enabled
logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
    Level: slog.LevelDebug,
}))
sql, err := cel2sql.Convert(ast,
    cel2sql.WithSchemas(schemas),
    cel2sql.WithLogger(logger))
```

## Benefits

- **Zero Overhead**: DiscardHandler when logging disabled
- **Standards-Based**: Uses Go 1.21+ standard library
- **Structured**: All logs use key-value pairs
- **Flexible**: Supports any slog.Handler
- **Production-Ready**: JSON handler for log aggregation
- **Developer-Friendly**: Text handler for debugging

## Log Events

- JSON path detection decisions
- Comprehension type identification
- Schema lookups (hits/misses, field types)
- Performance metrics
- Regex pattern transformations
- Operator mapping decisions
- Error contexts with full details

Closes #47

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

Co-Authored-By: Claude <noreply@anthropic.com>

Author: richardwooding

CLAUDE.md

@@ -175,6 +175,64 @@ sqlCondition, err := cel2sql.Convert(ast)
 // Returns: table.field = 'value' AND table.age > 30
 ```
 
+### Logging and Observability
+
+cel2sql supports structured logging using Go's standard `log/slog` package (Go 1.21+).
+
+Logging is optional and has **zero overhead** when not enabled (uses `slog.DiscardHandler` by default).
+
+#### Enable Logging
+
+```go
+import "log/slog"
+
+// JSON handler for production/machine parsing
+logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
+    Level: slog.LevelDebug,
+}))
+
+// Text handler for development/debugging
+logger := slog.New(slog.NewTextHandler(os.Stderr, nil))
+
+sql, err := cel2sql.Convert(ast,
+    cel2sql.WithSchemas(schemas),
+    cel2sql.WithLogger(logger))
+```
+
+#### What Gets Logged
+
+- **JSON path detection decisions** - Table, field, operator selection (->>, ?)
+- **Comprehension type identification** - all, exists, exists_one, filter, map
+- **Schema lookups** - Hits/misses, field type detection
+- **Performance metrics** - Conversion duration
+- **Regex pattern transformations** - RE2 to POSIX conversion
+- **Operator mapping decisions** - CEL to SQL operator conversion
+- **Error contexts** - Full details when conversions fail
+
+#### Log Levels
+
+- **Debug**: Detailed conversion steps, operator mappings, schema lookups
+- **Error**: Conversion failures with full context
+
+#### Example Usage
+
+```go
+// Without logger - zero overhead (default)
+sql, err := cel2sql.Convert(ast)
+
+// With logging - detailed observability
+logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
+    Level: slog.LevelDebug,
+}))
+
+sql, err := cel2sql.Convert(ast,
+    cel2sql.WithSchemas(schemas),
+    cel2sql.WithContext(ctx),
+    cel2sql.WithLogger(logger))
+```
+
+See `examples/logging/` for a complete working example with both JSON and text handlers.
+
 ## Important Notes
 
 ### Migration Context

cel2sql.go

@@ -5,9 +5,11 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"log/slog"
 	"regexp"
 	"strconv"
 	"strings"
+	"time"
 
 	"github.com/google/cel-go/cel"
 	"github.com/google/cel-go/common/operators"
@@ -42,6 +44,7 @@ type ConvertOption func(*convertOptions)
 type convertOptions struct {
 	schemas map[string]pg.Schema
 	ctx     context.Context
+	logger  *slog.Logger
 }
 
 // WithSchemas provides schema information for proper JSON/JSONB field handling.
@@ -78,6 +81,33 @@ func WithContext(ctx context.Context) ConvertOption {
 	}
 }
 
+// WithLogger provides a logger for observability and debugging.
+// If not provided, logging is disabled with zero overhead using slog.DiscardHandler.
+//
+// The logger enables visibility into:
+//   - JSON path detection decisions (table, field, operator selection)
+//   - Comprehension type identification (all, exists, filter, map)
+//   - Schema lookups (hits/misses, field types)
+//   - Performance metrics (conversion duration)
+//   - Regex pattern transformations (RE2 to POSIX)
+//   - Operator mapping decisions
+//   - Error contexts with full details
+//
+// Example with JSON output:
+//
+//	logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{Level: slog.LevelDebug}))
+//	sql, err := cel2sql.Convert(ast, cel2sql.WithLogger(logger))
+//
+// Example with text output:
+//
+//	logger := slog.New(slog.NewTextHandler(os.Stderr, nil))
+//	sql, err := cel2sql.Convert(ast, cel2sql.WithSchemas(schemas), cel2sql.WithLogger(logger))
+func WithLogger(logger *slog.Logger) ConvertOption {
+	return func(o *convertOptions) {
+		o.logger = logger
+	}
+}
+
 // Convert converts a CEL AST to a PostgreSQL SQL WHERE clause condition.
 // Options can be provided to configure the conversion behavior.
 //
@@ -89,31 +119,53 @@ func WithContext(ctx context.Context) ConvertOption {
 //
 //	sql, err := cel2sql.Convert(ast, cel2sql.WithSchemas(schemas))
 func Convert(ast *cel.Ast, opts ...ConvertOption) (string, error) {
-	options := &convertOptions{}
+	start := time.Now()
+
+	options := &convertOptions{
+		logger: slog.New(slog.DiscardHandler), // Default: no-op logger with zero overhead
+	}
 	for _, opt := range opts {
 		opt(options)
 	}
 
+	options.logger.Debug("starting CEL to SQL conversion")
+
 	checkedExpr, err := cel.AstToCheckedExpr(ast)
 	if err != nil {
+		options.logger.Error("AST to CheckedExpr conversion failed", slog.Any("error", err))
 		return "", err
 	}
+
 	un := &converter{
 		typeMap: checkedExpr.TypeMap,
 		schemas: options.schemas,
 		ctx:     options.ctx,
+		logger:  options.logger,
 	}
+
 	if err := un.visit(checkedExpr.Expr); err != nil {
+		options.logger.Error("conversion failed", slog.Any("error", err))
 		return "", err
 	}
-	return un.str.String(), nil
+
+	result := un.str.String()
+	duration := time.Since(start)
+
+	options.logger.LogAttrs(context.Background(), slog.LevelDebug,
+		"conversion completed",
+		slog.String("sql", result),
+		slog.Duration("duration", duration),
+	)
+
+	return result, nil
 }
 
 type converter struct {
 	str     strings.Builder
 	typeMap map[int64]*exprpb.Type
 	schemas map[string]pg.Schema
 	ctx     context.Context
+	logger  *slog.Logger
 }
 
 // checkContext checks if the context has been cancelled or expired.
@@ -158,20 +210,31 @@ func (con *converter) visit(expr *exprpb.Expr) error {
 // isFieldJSON checks if a field in a table is a JSON/JSONB type using schema information
 func (con *converter) isFieldJSON(tableName, fieldName string) bool {
 	if con.schemas == nil {
+		con.logger.Debug("no schemas provided for JSON detection")
 		return false
 	}
 
 	schema, ok := con.schemas[tableName]
 	if !ok {
+		con.logger.Debug("schema not found for table", slog.String("table", tableName))
 		return false
 	}
 
 	for _, field := range schema {
 		if field.Name == fieldName {
+			con.logger.LogAttrs(context.Background(), slog.LevelDebug,
+				"field type lookup",
+				slog.String("table", tableName),
+				slog.String("field", fieldName),
+				slog.Bool("is_json", field.IsJSON),
+			)
 			return field.IsJSON
 		}
 	}
 
+	con.logger.Debug("field not found in schema",
+		slog.String("table", tableName),
+		slog.String("field", fieldName))
 	return false
 }
 
@@ -359,6 +422,13 @@ func (con *converter) visitCallBinary(expr *exprpb.Expr) error {
 	} else {
 		return fmt.Errorf("cannot unmangle operator: %s", fun)
 	}
+
+	con.logger.LogAttrs(context.Background(), slog.LevelDebug,
+		"binary operator conversion",
+		slog.String("cel_op", fun),
+		slog.String("sql_op", operator),
+	)
+
 	con.str.WriteString(" ")
 	con.str.WriteString(operator)
 	con.str.WriteString(" ")
@@ -623,6 +693,16 @@ func (con *converter) callMatches(target *exprpb.Expr, args []*exprpb.Expr) erro
 			return fmt.Errorf("invalid regex pattern: %w", err)
 		}
 
+		// Determine case sensitivity
+		caseInsensitive := strings.HasPrefix(re2Pattern, "(?i)")
+
+		con.logger.LogAttrs(context.Background(), slog.LevelDebug,
+			"regex pattern conversion",
+			slog.String("original_pattern", re2Pattern),
+			slog.String("converted_pattern", posixPattern),
+			slog.Bool("case_insensitive", caseInsensitive),
+		)
+
 		// Write the converted pattern as a string literal
 		escaped := strings.ReplaceAll(posixPattern, "'", "''")
 		con.str.WriteString("'")

comprehensions.go

@@ -1,8 +1,10 @@
 package cel2sql
 
 import (
+	"context"
 	"errors"
 	"fmt"
+	"log/slog"
 
 	"github.com/google/cel-go/common/operators"
 	exprpb "google.golang.org/genproto/googleapis/api/expr/v1alpha1"
@@ -95,6 +97,12 @@ func (con *converter) analyzeComprehensionPattern(comp *exprpb.Expr_Comprehensio
 		if con.isLogicalAndStep(comp.GetLoopStep(), comp.GetAccuVar()) {
 			info.Type = ComprehensionAll
 			info.Predicate = con.extractPredicateFromAndStep(comp.GetLoopStep(), comp.GetAccuVar())
+			con.logger.LogAttrs(context.Background(), slog.LevelDebug,
+				"comprehension identified",
+				slog.String("type", info.Type.String()),
+				slog.String("iter_var", info.IterVar),
+				slog.String("accu_var", info.AccuVar),
+			)
 			return info, nil
 		}
 	}
@@ -104,6 +112,12 @@ func (con *converter) analyzeComprehensionPattern(comp *exprpb.Expr_Comprehensio
 		if con.isLogicalOrStep(comp.GetLoopStep(), comp.GetAccuVar()) {
 			info.Type = ComprehensionExists
 			info.Predicate = con.extractPredicateFromOrStep(comp.GetLoopStep(), comp.GetAccuVar())
+			con.logger.LogAttrs(context.Background(), slog.LevelDebug,
+				"comprehension identified",
+				slog.String("type", info.Type.String()),
+				slog.String("iter_var", info.IterVar),
+				slog.String("accu_var", info.AccuVar),
+			)
 			return info, nil
 		}
 	}
@@ -113,6 +127,12 @@ func (con *converter) analyzeComprehensionPattern(comp *exprpb.Expr_Comprehensio
 		if con.isConditionalCountStep(comp.GetLoopStep(), comp.GetAccuVar()) && con.isEqualsOneResult(comp.GetResult(), comp.GetAccuVar()) {
 			info.Type = ComprehensionExistsOne
 			info.Predicate = con.extractPredicateFromConditionalStep(comp.GetLoopStep())
+			con.logger.LogAttrs(context.Background(), slog.LevelDebug,
+				"comprehension identified",
+				slog.String("type", info.Type.String()),
+				slog.String("iter_var", info.IterVar),
+				slog.String("accu_var", info.AccuVar),
+			)
 			return info, nil
 		}
 	}
@@ -122,6 +142,12 @@ func (con *converter) analyzeComprehensionPattern(comp *exprpb.Expr_Comprehensio
 		if con.isListAppendStep(comp.GetLoopStep(), comp.GetAccuVar()) {
 			info.Type = ComprehensionMap
 			info.Transform = con.extractTransformFromAppendStep(comp.GetLoopStep(), comp.GetAccuVar())
+			con.logger.LogAttrs(context.Background(), slog.LevelDebug,
+				"comprehension identified",
+				slog.String("type", info.Type.String()),
+				slog.String("iter_var", info.IterVar),
+				slog.Bool("has_filter", false),
+			)
 			return info, nil
 		}
 		// Map with filter: step = conditional(filter, accu + [transform], accu)
@@ -131,6 +157,12 @@ func (con *converter) analyzeComprehensionPattern(comp *exprpb.Expr_Comprehensio
 			filter, transform := con.extractFilterAndTransformFromConditionalStep(comp.GetLoopStep(), comp.GetAccuVar())
 			info.Filter = filter
 			info.Transform = transform
+			con.logger.LogAttrs(context.Background(), slog.LevelDebug,
+				"comprehension identified",
+				slog.String("type", info.Type.String()),
+				slog.String("iter_var", info.IterVar),
+				slog.Bool("has_filter", true),
+			)
 			return info, nil
 		}
 	}
@@ -140,6 +172,11 @@ func (con *converter) analyzeComprehensionPattern(comp *exprpb.Expr_Comprehensio
 		if con.isConditionalFilterStep(comp.GetLoopStep(), comp.GetAccuVar(), comp.GetIterVar()) {
 			info.Type = ComprehensionFilter
 			info.Predicate = con.extractPredicateFromConditionalStep(comp.GetLoopStep())
+			con.logger.LogAttrs(context.Background(), slog.LevelDebug,
+				"comprehension identified",
+				slog.String("type", info.Type.String()),
+				slog.String("iter_var", info.IterVar),
+			)
 			return info, nil
 		}
 	}