feat(ts): emit discriminated-union oneofs in TS generators

[hishamank]

What

Both TypeScript generators (protoc-gen-ts-client, protoc-gen-ts-server) now render oneofs that have no explicit sebuf.http oneof_config annotation as presence-discriminated flat unions:

export type PlainEventContent =
  | { text: TextContent; image?: never }
  | { image: ImageContent; text?: never }
  | { text?: never; image?: never };   // oneof unset

export interface PlainEventBase { id: string; }
export type PlainEvent = PlainEventBase & PlainEventContent;

instead of a flattened bag of independent optional fields (text?: ...; image?: ...).

Why

Un-annotated oneofs serialize as plain protojson: the set member's JSON key appears directly on the parent object, and no discriminator field exists on the wire. The generated clients are conversion-free (JSON.stringify(req) / resp.json() as T), so the TS types must describe exactly that wire shape — which rules out both alternatives:

• the old flattened bag carries no exactly-one guarantee and gives consumers nothing to narrow on;
• a $case-style discriminated union (ts-proto's oneof=unions) describes JSON that never exists on the wire, and only works behind generated fromJSON/toJSON converters — which sebuf deliberately doesn't have.

A union discriminated by key presence, with ?: never sibling guards, is assignable to and from the exact protojson wire format while restoring the oneof guarantees:

• narrowing works: if (e.text) { /* e.text: TextContent; e.image: undefined */ }
• constructing an object with two members set is a compile error
• the all-never arm models the unset oneof
• set members are non-optional — oneof fields have explicit presence, so protojson always emits a set member, even at its zero value

Behavior

• This is the default and only behavior — there is no configuration flag.
• Synthetic oneofs (proto3 optional) are unaffected.
• Oneofs with an explicit oneof_config annotation keep their annotated shape (the annotation always wins).
• Messages whose fields all belong to oneofs skip the empty Base interface and alias the union directly.
• Scalar members: presence-narrow with "count" in e or e.count !== undefined — truthiness misfires on 0/"".

Notes

• Breaking change for consumers of the old flattened-bag shape that set multiple members at once (now a compile error) or relied on all members being independently optional.
• Un-annotated non-synthetic oneofs route through the same intersection emission used by flattened annotated oneofs.

Tests

• Golden fixtures regenerated; oneof_discriminator output shows presence unions, and the httpgen consistency test asserts $case never appears.
• Cross-generator consistency tests (httpgen) updated.
• Unit tests added in tscommon (TestSynthesizeOneofInfo, TestGeneratePresenceOneofUnionType, TestGenerateInterface_PresenceOneof), compiling a hand-built proto3 FileDescriptorProto into a protogen.Plugin to exercise the presence-union emitter and interface routing on real protogen inputs.
• Full suite + staticcheck green.

[codecov]

Codecov Report

❌ Patch coverage is 79.62963% with 22 lines in your changes missing coverage. Please review.
✅ Project coverage is 4.66%. Comparing base (b3f6487) to head (c84aec4).

Files with missing lines	Patch %	Lines
internal/tscommon/types.go	77.31%	21 Missing and 1 partial ⚠️

Additional details and impacted files

@@           Coverage Diff            @@
##            main    #199      +/-   ##
========================================
+ Coverage   3.32%   4.66%   +1.33%     
========================================
  Files         62      62              
  Lines      10966   11025      +59     
========================================
+ Hits         365     514     +149     
+ Misses     10595   10488     -107     
- Partials       6      23      +17     

Flag	Coverage Δ
unittests	4.66% <79.62%> (+1.33%)	⬆️

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

☔ View full report in Codecov by Harness.
📢 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.

[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

[SebastienMelki]

Review — approve in principle ✅

Read through the full diff and cross-checked the wire-shape reasoning against the other generators. The direction is right and this fixes two genuine pre-existing bugs where the TS types described JSON that never exists on the wire. Since the clients do conversion-free JSON.stringify(req) / resp.json() as T, the types must match protojson exactly — and now they do.

Confirmed correct

• Un-annotated oneof → plain protojson (set member's key flat on parent, no discriminator). No custom MarshalJSON is generated for these, and the Python client (independent Optional fields) and OpenAPI (flat optional properties, no oneOf) already emit the same shape — so this aligns TS with the rest of the toolkit rather than diverging.
• Non-optional set members, the all-never unset arm, and the ?: never presence guards all correctly model protojson's explicit-presence behavior.
• The flatten:false fix (dropping the phantom content?: Wrapper property) matches the generated MarshalJSONSebuf and also kills the snake_case-name leak. Nice regression test.

Findings

1. (strong-recommend, pre-existing) Discriminator/variant-key collision is unvalidated for flatten:false annotated oneofs. validateDiscriminatorNameCollision (internal/annotations/oneof_discriminator.go:160-163) skips the oneof's own fields, and ValidateOneofDiscriminator only runs the flatten validator when flatten=true. So a non-flatten annotated oneof whose discriminator equals a variant's JSON name is accepted, and nonFlattenedOneofBranch emits a duplicate key ({ text: "text"; text: TextContent } → TS2300) while MarshalJSONSebuf overwrites the payload with the discriminator string. Note it collides with the sibling ?: never guards too (e.g. discriminator:"image" dupes image in every arm). This isn't a regression from this PR — the old branch had the same hazard — but since the PR already owns the oneof surface, it's a good place to add a check rejecting discriminator == any variant JSON name on the flatten:false path.

2. (nit) Dead code. GenerateStandardInterface is now only ever called with zero discriminated oneofs; its oneof-handling branch and discriminatedOneofs param are unreachable and can be dropped.

3. (nit) Internal inconsistency. The flattened-scalar branch still emits an optional payload (body?: string) while the non-flatten scalar path is now non-optional — same explicit-presence logic should apply to both.

4. (tests) Coverage gaps — no fixture for (a) two un-annotated oneofs in one message (intersection of presence unions), (b) synthetic proto3 optional + real oneof in the same message, or (c) the flattened-scalar case. At least (a) is worth locking in.

Docs / caveats to add on this PR

No TS-specific oneof docs exist today (CLAUDE.md documents only annotated oneof_config; docs/client-generation.md has no oneof mention). Please add:

• CLAUDE.md oneof section — the default un-annotated behavior + the TS presence-union shape.
• docs/client-generation.md — an "Oneofs in TypeScript" subsection (mirror the Python docs' "Discriminated oneofs") carrying these caveats:
  1. Breaking change — old flattened-bag (un-annotated) and event.content wrapper (flatten:false) consumers break; setting two members is now a compile error.
  2. Scalar narrowing — use "count" in e / e.count !== undefined, not truthiness (misfires on 0 / "" / false).
  3. Exactly-one is enforced only at object-literal construction; TS is now stricter than the Python/OpenAPI outputs.
  4. ?: never is a compile-time guard, not runtime exclusivity (under non-strict TS, field: undefined is still assignable). Reads are an unchecked as T cast.
  5. Unset state is modeled via the all-never arm in TS but via oneOf/discriminator in OpenAPI — the unset story isn't equally visible across the two.
• A TS example that uses a oneof — none of the TS examples currently do; add one so the shape is exercised end-to-end.

Thanks for the thorough tests (the FileDescriptorProto → protogen.Plugin harness in tscommon is a nice touch).

[hishamank]

Thanks for the thorough review — all addressed on this branch (c84aec4):

1. Discriminator/variant collision — added validateDiscriminatorVariantCollision on the flatten:false path, rejecting a discriminator equal to any variant's JSON name (unit test covers the non-flatten error, the safe case, and flatten still being allowed). Implemented as a hard error since it only ever fired on input that already produced uncompilable TS. — d2a4aac
   2 & 3. Dead code — dropped GenerateStandardInterface's unused discriminatedOneofs param + field skip, and removed the unreachable flatten-scalar branch (scalar+flatten is rejected upstream by validateOneofFlatten); the scalar path is now always non-optional via nonFlattenedOneofBranch. — 5123052
2. Tests — added a two_oneofs fixture (two independent un-annotated oneofs → TwoOneofs = TwoOneofsBase & TwoOneofsA & TwoOneofsB, each union guarding only its own siblings), asserted verbatim in both generators. — ad7f235

Docs — new "Oneofs in TypeScript" sections in CLAUDE.md and docs/client-generation.md covering the un-annotated / flatten:false / flatten:true shapes, a construct-and-narrow example, and all five caveats (breaking change incl. the two-member compile error; scalar narrowing by presence not truthiness; construction-time exactly-one; ?: never is compile-time-only + as T reads; unset via the all-never arm in TS vs oneOf in OpenAPI). — c84aec4

No existing goldens changed — only the two new two_oneofs fixtures were added.

[SebastienMelki]

Follow-up review — thanks, all the substantive findings are addressed (collision validation, the dead-code/param cleanup, and the two-oneofs test all look great, and deleting the unreachable flatten+scalar branch is a sharper fix than I'd suggested).

One item from the docs ask is still open: a runnable TS example that uses a oneof. The shape is now well covered in the docs snippets and locked into golden testdata, but none of the examples/ TS demos (ts-client-demo, ts-fullstack-demo, rn-client-demo) actually exercise a oneof end-to-end — the only examples/ oneofs are still Go/Python (simple-api, python-encoding-demo). Would be nice to add an un-annotated oneof to one of the TS demo protos and a row in docs/examples/README.md so consumers see the presence-union shape in a real, buildable client. Optional/non-blocking — everything else is good to go from my side.