feat(schema): optional $ref-sibling rendering (EmitRefSiblings, SkipAllOfCompounding)

[fredbi]

A struct field whose Go type resolves to a named model becomes a $ref. Strict JSON-Schema-draft-4 ignores siblings of a $ref, so codescan preserves a field's description / extensions / validations by wrapping the reference in an allOf compound. That shape is correct but breaks downstream consumers (e.g. go-swagger codegen) that expect a bare $ref.

Two new Options give callers control, splitting $ref siblings into two classes — siblings-eligible (description, extensions) and compound-only (validations, externalDocs):

• EmitRefSiblings: emit description & extensions as direct $ref siblings ({$ref, description, x-*}) instead of an allOf wrap. A validation or externalDocs still forces a compound.
• SkipAllOfCompounding: never emit an allOf compound. Validations & externalDocs are dropped; description & extensions too, unless EmitRefSiblings keeps them as siblings. Each drop raises one validate.dropped-ref-sibling diagnostic via OnDiagnostic.

DescWithRef is deprecated in favour of EmitRefSiblings but kept with its original semantics (a no-op when EmitRefSiblings is set). All defaults are unchanged — zero golden drift. required: is always preserved (a parent-side concern, not a $ref sibling).

Includes the builder logic + diagnostic code, unit A/B tests, a tested doc-site example (docs/examples/shaping/refsiblings), and doc updates (schema README, doc-site options table + "Descriptions beside a $ref").

Change type

Please select: 🆕 New feature or enhancement|🔧 Bug fix'|📃 Documentation update

Short description

Fixes

Full description

Checklist

• I have signed all my commits with my name and email (see DCO. This does not require a PGP-signed commit
• I have rebased and squashed my work, so only one commit remains
• I have added tests to cover my changes.
• I have properly enriched go doc comments in code.
• I have properly documented any breaking change.

[codecov]

Codecov Report

❌ Patch coverage is 69.49153% with 18 lines in your changes missing coverage. Please review.
✅ Project coverage is 81.89%. Comparing base (fe9ed77) to head (1f7c42a).
⚠️ Report is 2 commits behind head on master.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
internal/builders/schema/walker.go	67.27%	17 Missing and 1 partial ⚠️

❌ Your patch check has failed because the patch coverage (69.49%) is below the target coverage (80.00%). You can increase the patch coverage or adjust the target coverage.

Additional details and impacted files

@@            Coverage Diff             @@
##           master      #47      +/-   ##
==========================================
+ Coverage   81.83%   81.89%   +0.05%     
==========================================
  Files          80       80              
  Lines        7433     7468      +35     
==========================================
+ Hits         6083     6116      +33     
- Misses       1006     1007       +1     
- Partials      344      345       +1     

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