fix: handle schema ref siblings when downgrading

[ShellWen]

Summary

• rewrite Schema Object $ref siblings to an OpenAPI 3.0-compatible allOf wrapper during downgrade
• preserve field-level descriptions and existing allOf entries
• keep schema traversal scoped to OpenAPI schema fields so examples/extensions are not rewritten

Tests

• GOCACHE=/tmp/huma-go-cache GOMODCACHE=/tmp/huma-go-mod-cache go test . -run TestDowngrade
• GOCACHE=/tmp/huma-go-cache GOMODCACHE=/tmp/huma-go-mod-cache go test ./...

Fixes #1001

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds targeted downgrading logic and tests to ensure OpenAPI 3.1 $ref siblings are properly converted to OpenAPI 3.0-compatible allOf structures without incorrectly rewriting non-schema payloads.

Changes:

• Added schema-aware downgrade pass that rewrites $ref siblings into allOf only in OpenAPI schema locations.
• Added regression tests for $ref sibling wrapping, preserving existing allOf, recursive schemas, and avoiding non-schema keys.
• Added YAML-specific test assertions for $ref sibling wrapping behavior.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File	Description
openapi.go	Splits downgrade into a generic transform pass + a schema-location-aware $ref-sibling rewrite pass.
openapi_test.go	Adds regression tests covering $ref sibling wrapping, recursion, YAML output, and non-schema “schema” keys in examples.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[codecov]

Codecov Report

❌ Patch coverage is 63.04348% with 51 lines in your changes missing coverage. Please review.
✅ Project coverage is 92.24%. Comparing base (c3f1651) to head (9f69869).
⚠️ Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
openapi.go	63.04%	36 Missing and 15 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1031      +/-   ##
==========================================
- Coverage   93.07%   92.24%   -0.83%     
==========================================
  Files          23       23              
  Lines        4781     4916     +135     
==========================================
+ Hits         4450     4535      +85     
- Misses        271      306      +35     
- Partials       60       75      +15     

☔ 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.