Chore: Fork-free code generation and regenerated Components.swift

[Krivoblotsky]

What

Makes make generate a one-command, fork-free operation and regenerates Components.swift with it.

• No generator fork. The Makefile clones and builds the stock Swift OpenAPI Generator at a pinned release (1.13.1) under .build/, and installs the one Python dependency (PyYAML) into a virtualenv there. Prerequisites are a Swift toolchain, python3 with venv, and network access on the first run.
• Two new pipeline steps replace the three patches that lived in the private fork. Scripts/transform_openapi.py collapses OpenAI's anyOf: [X, {type: 'null'}] nullability into optional properties (481 sites in the vendored spec; the stock generator otherwise drops every such property) and records the wire values of all 45 discriminated unions, whose discriminators have no mapping in the spec. Scripts/postprocess_components.py re-wraps the generator's 1.13 multi-file output under the existing header, appends the wire values to each union's decoder, and adds the try-both fallback for message, which names both InputMessage and OutputMessage. It supersedes Scripts/extract_components.py.
• Scripts/fix_recursive_reference.py handles any number of $recursiveRef occurrences, each pointed at its enclosing component. The live spec now has two (CompoundFilter, BetaCompoundFilter) and the strict one-occurrence version aborts on it.
• Generation workflow: runs make generate on every PR and fails when the committed Components.swift differs, so the file can never drift from the pipeline again. The built generator is cached per version and Swift toolchain.
• Regenerated Components.swift from the unchanged vendored spec. Two regression tests cover behaviour the fork got wrong: ItemResource now decodes input messages, and InputItem decodes item_reference by its wire value.
• CONTRIBUTING.md describes the new workflow; CHANGELOG has the entries.

Why

Regeneration only worked on one machine: it required a sibling checkout of an unpinned, unpublished fork of the generator. Upstream has not shipped the missing behaviour (nullable anyOf has been open since 2024 and the maintainer considers a proper fix a breaking change), and generator 1.13 changed its output layout in a way the old extraction script could not handle. The upstream maintainer's recommended workaround is exactly this: fix the spec before generation instead of patching the generator. Full analysis: the "Generation Without the Fork" audit.

Affected Areas

Generation tooling (Makefile, Scripts/, openapi-generator-config.yaml unchanged), CI (.github/workflows/generation.yml), the generated Components.swift, two tests, docs. No hand-written source changes.

The regenerated schemas differ from the fork's output in 29 API-gate lines, all recorded in .github/api-breakage-allowlist.txt with the changelog entry:

• 23 nested typealiases that were artifacts of how the fork kept the single-member anyOf alive (for example OutputMessage.MessagePhase, CreateResponse.Value3Payload.IncludeEnum); the top-level types they aliased are unchanged. Keeping the anyOf instead produces 5,000 lines of wrapper structs, so collapsing is the right call.
• CreateTranscriptionRequest.ChunkingStrategyPayload.body is no longer optional (a request-side generated type the SDK does not use itself), and CreateTranscriptionRequest gained a stream part.

If exact parity is preferred, the post-processor can re-add the 23 typealiases; say so and I will add it before merge.

More Info

• Stacked on Chore: Add API breakage gate, platform CI matrix and changelog (Phase 0) #440, which introduces the API gate and the allowlist this PR relies on. GitHub retargets this PR to main when Chore: Add API breakage gate, platform CI matrix and changelog (Phase 0) #440 merges.
• Verified: the Python pipeline reproduces the Ruby prototype byte for byte; make generate runs in about 6 seconds with a built generator; the full suite passes; the same pipeline generates the live September 2026 spec cleanly (Phase 2 then needs changes in two hand-written files only).
• WebSearchActionSearch/query is still removed from required for the vendored spec; the live spec no longer requires it, so that entry goes when the spec is updated (noted in the Makefile).

🤖 Generated with Claude Code