Sebuf

Phase 4 Plan 5: Cross-Generator Consistency Tests Summary

Cross-generator consistency tests verifying all 4 generators produce identical JSON for int64 and enum encoding, with programmatic Phase 4 success criteria verification

Performance#

  • Duration: 6 min
  • Started: 2026-02-05T22:56:00Z
  • Completed: 2026-02-05T23:02:00Z
  • Tasks: 3 (combined into single commit)
  • Files modified: 2

Accomplishments#

  • Created comprehensive cross-generator consistency test suite with 11 test functions
  • Verified all 6 Phase 4 ROADMAP success criteria programmatically
  • Ensured go-http and go-client produce byte-identical int64 and enum encoding code
  • Confirmed TypeScript types correctly match Go NUMBER vs STRING encoding
  • Verified OpenAPI schemas accurately reflect configured encoding
  • Added backward compatibility tests for protos without encoding annotations
  • Standardized openapiv3 testdata to use symlinks like other generators

Task Commits#

Each task was committed atomically:

  1. Tasks 1-3: Cross-generator consistency tests and verification - 960e8b6 (test)

Plan metadata: See final commit below

Files Created/Modified#

  • internal/httpgen/encoding_consistency_test.go - Cross-generator consistency tests with:

    • TestGoGeneratorsProduceIdenticalInt64Encoding
    • TestGoGeneratorsProduceIdenticalEnumEncoding
    • TestTypeScriptInt64TypesMatchGoEncoding
    • TestTypeScriptEnumTypesMatchGoEncoding
    • TestOpenAPIInt64SchemasMatchGoEncoding
    • TestOpenAPIEnumSchemasMatchGoEncoding
    • TestPhase4SuccessCriteria (6 criteria subtests)
    • TestBackwardCompatibility

  • internal/openapiv3/testdata/proto/enum_encoding.proto - Changed from duplicate file to symlink pointing to ../../../httpgen/testdata/proto/enum_encoding.proto

Decisions Made#

  1. D-04-05-01: Split test functions for linting compliance - The original TestEncodingConsistencyAcrossGenerators had cyclomatic complexity > 30. Split into 6 separate test functions and 6 helper functions to verify each criterion independently.

  2. D-04-05-02: Use normalizeGeneratorComment for byte-level comparison - The go-http and go-client generators produce identical encoding code except for the "Code generated by protoc-gen-go-http" vs "protoc-gen-go-client" comment. Normalize this to enable byte-for-byte comparison.

  3. D-04-05-03: Convert openapiv3 enum_encoding.proto to symlink - The openapiv3 testdata had a duplicate copy of enum_encoding.proto while other generators (tsclientgen, clientgen) use symlinks to httpgen. Converted to symlink for consistency and single source of truth.

Deviations from Plan#

Adaptation from Plan#

1. No exhaustive.proto creation needed

The plan specified creating an exhaustive.proto with encoding test cases, but this was already implemented in plans 04-02 through 04-04 as separate int64_encoding.proto and enum_encoding.proto files. These existing files provide comprehensive coverage.

Impact: Plan adapted to use existing infrastructure. No new proto files needed.

Total deviations: 1 adaptation Impact on plan: Simplified execution by leveraging existing test infrastructure from prior plans.

Issues Encountered#

  • Linting issues with cyclomatic complexity and variable shadowing - resolved by splitting large test function into smaller focused tests with unique variable names

User Setup Required#

None - no external service configuration required.

Next Phase Readiness#

Phase 4 (JSON - Primitive Encoding) is complete:

  • All 6 ROADMAP success criteria verified programmatically:

    1. int64_encoding = STRING produces JSON strings in all generators
    2. int64_encoding = NUMBER produces JSON numbers with precision warning
    3. enum_encoding = STRING produces proto name strings in all generators
    4. enum_value annotations produce custom JSON strings in all generators
    5. OpenAPI schemas accurately reflect configured encoding
    6. Cross-generator consistency verified for every encoding combination

  • Zero regressions in existing tests (all 6 packages pass with 85%+ coverage)

  • Backward compatible (protos without annotations unchanged)

  • Full test suite passes

  • All binaries build successfully

  • Lint clean

Ready for Phase 5: JSON - Nullable & Empty

Phase: 04-json-primitive-encoding Completed: 2026-02-06