feat: implement structured validation error responses

[SebastienMelki]

Summary

This PR implements comprehensive structured validation error responses across the sebuf toolkit, providing consistent error handling for both request body and header validation.

Key Changes

• Add ValidationError proto definitions (proto/sebuf/http/errors.proto)

  • ValidationError message with list of field violations
  • FieldViolation message with field path and description
  • Support for both JSON and protobuf serialization

• Update HTTP generator (internal/httpgen/generator.go)

  • Generate structured error response functions
  • Convert protovalidate errors to ValidationError format
  • Support content-type aware error serialization (JSON/protobuf)
  • Update header validation to return structured errors

• Update OpenAPI v3 generator (internal/openapiv3/generator.go)

  • Add ValidationError and FieldViolation schemas to components
  • Include 400 validation error responses in all API methods
  • Provide comprehensive error documentation for API consumers

• Refactor for code quality

  • Break down long functions to fix linting issues (funlen violations)
  • Improve code readability and maintainability
  • Update golden files for comprehensive test coverage

• Update documentation and examples

  • Update validation documentation with structured error examples
  • Refresh simple-api example with new error handling
  • Add structured error responses to main feature list

Error Response Format

{
  "violations": [
    {
      "field": "user.email",
      "description": "must be a valid email address"
    },
    {
      "field": "X-API-Key", 
      "description": "required header 'X-API-Key' is missing"
    }
  ]
}

Benefits

• Consistent error handling across request body and header validation
• Better API documentation with OpenAPI 400 response specifications
• Enhanced developer experience with detailed field-level error information
• Content-type awareness supporting both JSON and protobuf error responses
• Comprehensive test coverage with updated golden files

Test Plan

• All existing tests pass
• Golden files updated for OpenAPI generator
• Linting issues resolved (funlen violations fixed)
• Simple-api example generates correctly with new error schemas
• Both JSON and YAML OpenAPI formats include ValidationError schemas

🤖 Generated with Claude Code

[github-actions]

🔍 CI Pipeline Status

✅ Lint: success
✅ Test: success
✅ Coverage: success
✅ Build: success
✅ Integration: success

---

📊 Coverage Report: Available in checks above
🔗 Artifacts: Test results and coverage reports uploaded

[codecov]

Codecov Report

❌ Patch coverage is 80.00000% with 10 lines in your changes missing coverage. Please review.
✅ Project coverage is 13.77%. Comparing base (724ab8a) to head (d94d110).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
internal/openapiv3/generator.go	80.00%	10 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #38      +/-   ##
==========================================
+ Coverage   10.61%   13.77%   +3.16%     
==========================================
  Files           5        5              
  Lines        1046     1096      +50     
==========================================
+ Hits          111      151      +40     
- Misses        930      940      +10     
  Partials        5        5              

Flag	Coverage Δ
unittests	13.77% <80.00%> (+3.16%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.