feat: Add JSON output format for CI/CD integration (closes #66)

[ajitpratap0]

Summary

Adds JSON output format support to validate and parse CLI commands for automation and CI/CD integration.

Changes

New Files

• cmd/gosqlx/internal/output/json.go - JSON formatting functions
• cmd/gosqlx/internal/output/json_test.go - Comprehensive test suite

Modified Commands

• validate: Added --output-format json flag
• parse: Added -f json format option

JSON Output Structure

Validation Output:

{
  "command": "validate",
  "input": {"type": "file", "files": ["test.sql"], "count": 1},
  "status": "success",
  "results": {
    "valid": true,
    "total_files": 1,
    "valid_files": 1,
    "invalid_files": 0
  },
  "errors": [],
  "stats": {
    "duration": "217.959µs",
    "throughput_files_per_sec": 4588.0
  }
}

Parse Output:

{
  "command": "parse",
  "status": "success",
  "results": {
    "ast": {"type": "AST", "statements": [...]},
    "metadata": {
      "parser_version": "2.0.0-alpha",
      "sql_compliance": "~80-85% SQL-99"
    }
  }
}

Features

✅ Error categorization (tokenization, parsing, syntax, io)
✅ Input type detection (file, files, stdin)
✅ Optional performance statistics
✅ Structured error reporting
✅ AST details and metadata
✅ Backward compatible (text format default)

Usage Examples

# Validate with JSON output
gosqlx validate --output-format json query.sql

# Parse with JSON output  
gosqlx parse -f json "SELECT * FROM users"

# CI/CD pipeline
gosqlx validate --output-format json --output-file results.json queries/

# Stdin support
cat query.sql | gosqlx validate --output-format json

Testing

✅ All JSON format tests pass
✅ All existing CLI tests pass (100+ tests)
✅ Pre-commit hooks passed

CI/CD Integration Benefits

• Machine-readable output for automated tooling
• Structured error reporting for GitHub Actions
• Problem matchers for IDE integration
• Performance metrics for monitoring
• Standardized format for multiple tools

Closes #66

🤖 Generated with Claude Code

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

[claude]

Claude finished @ajitpratap0's task —— View job

---

PR Review: JSON Output Format Implementation

✅ Code Review Complete

This is a well-implemented JSON output format feature that adds significant value for CI/CD integration. Here's my detailed analysis:

🌟 Strengths

1. Excellent Code Quality

• Clean Architecture: Well-structured JSON output package with clear separation of concerns
• Type Safety: Comprehensive struct definitions with proper JSON tags
• Error Handling: Robust error categorization and position tracking
• Memory Management: Proper use of object pooling patterns (defer tokenizer.PutTokenizer(tkz))

2. Comprehensive Test Coverage

• 409 lines of tests covering all major scenarios
• Edge case testing: Empty files, stdin input, error conditions
• Integration tests: Real SQL parsing with tokenizer and parser
• Error categorization tests: Proper classification of different error types

3. Strong JSON Schema Design

// Well-designed output structure
type JSONValidationOutput struct {
    Command string                `json:"command"`
    Input   JSONInputInfo         `json:"input"`
    Status  string                `json:"status"` 
    Results JSONValidationResults `json:"results"`
    Errors  []JSONValidationError `json:"errors,omitempty"`
    Stats   *JSONValidationStats  `json:"stats,omitempty"`
}

4. Production-Ready Features

• Multiple input types: File, files, stdin, directory detection
• Performance metrics: Throughput calculation and duration tracking
• Backward compatibility: Text format remains default
• Security: Proper file permission handling (0600)

🔍 Minor Issues & Suggestions

1. String Matching Performance (json.go:291-302)

// Current implementation - could be optimized
func contains(s string, substrings ...string) bool {
    for _, substr := range substrings {
        if len(s) >= len(substr) {
            for i := 0; i <= len(s)-len(substr); i++ {
                if s[i:i+len(substr)] == substr {
                    return true
                }
            }
        }
    }
    return false
}

Suggestion: Consider using strings.Contains() for better performance:

func contains(s string, substrings ...string) bool {
    for _, substr := range substrings {
        if strings.Contains(strings.ToLower(s), substr) {
            return true
        }
    }
    return false
}

2. Error Message Truncation (json.go:270-274)

errorLower := errorMsg
if len(errorLower) > 100 {
    errorLower = errorLower[:100]
}

Issue: Variable name errorLower is misleading since no lowercasing happens.
Suggestion: Either actually lowercase or rename the variable.

3. Hardcoded Parser Version (json.go:182)

ParserVersion: "2.0.0-alpha",

Suggestion: Consider making this configurable or importing from a version constant.

🚀 Performance Considerations

Positive Aspects:

• ✅ Proper object pooling usage
• ✅ Efficient JSON marshaling with MarshalIndent
• ✅ Optional statistics to avoid unnecessary computation

Potential Optimizations:

• JSON encoding could be cached for repeated similar outputs
• Consider streaming JSON for very large result sets

🔒 Security Assessment

✅ Good Security Practices:

• File permissions set to 0600 for output files
• Proper input validation and error handling
• No sensitive information logged
• Safe string operations

No Security Concerns Found

📊 Test Coverage Analysis

Excellent Coverage:

• ✅ Success and failure scenarios
• ✅ Different input types (file, files, stdin)
• ✅ Error categorization testing
• ✅ JSON structure validation
• ✅ AST conversion testing
• ✅ Integration with real parser components

Test Quality:

// Example of good test structure
func TestFormatValidationJSON_WithErrors(t *testing.T) {
    result := &ValidationResult{
        TotalFiles:   2,
        ValidFiles:   1, 
        InvalidFiles: 1,
        // ... detailed setup
    }
    
    jsonData, err := FormatValidationJSON(result, []string{"test1.sql", "test2.sql"}, false)
    if err != nil {
        t.Fatalf("FormatValidationJSON failed: %v", err)
    }
    
    // Comprehensive validation of output structure
}

🎯 Integration Quality

CLI Integration (validate.go & parser_cmd.go):

• ✅ Clean flag handling (--output-format json)
• ✅ Proper quiet mode activation for JSON output
• ✅ Consistent error handling across commands
• ✅ Good separation of concerns

📝 Minor Suggestions

1. Add JSON Schema validation for output format consistency
2. Consider adding a --json-compact flag for minified output
3. Documentation: Consider adding godoc examples for public functions
4. Version handling: Make parser version configurable

🏆 Overall Assessment

Rating: ⭐⭐⭐⭐⭐ (Excellent)

This is a production-ready implementation that:

• ✅ Follows Go best practices and project conventions
• ✅ Has comprehensive test coverage
• ✅ Provides valuable CI/CD integration features
• ✅ Maintains backward compatibility
• ✅ Uses proper error handling and security practices

Recommendation: APPROVE - This PR significantly enhances the project's automation capabilities while maintaining high code quality standards.

🚦 CI/CD Benefits Delivered

The JSON output format will enable:

• Automated SQL validation in GitHub Actions
• Integration with problem matchers for IDE support
• Structured error reporting for monitoring tools
• Performance metrics collection for optimization

This is exactly what Issue #66 requested and is implemented excellently.