Declaration-based generated types file splitting #974

Description

Track the public proposal and review discussion for opt-in declaration-based file splitting of generated Swift types.

The generator currently splits types by namespace, but APIs with a large proportion of schemas can still place most generated source in one file. A declaration limit would allow those large namespaces to be divided further.

Related PRs and issues:

• SOAR-0017: Declaration-based types file splitting #973 contains the SOAR-0017 proposal.
• Add namespace-based types file splitting #925 adds namespace-based types file splitting.
• SOAR-0015: Add namespace file splitting proposal #930 contains the namespace-splitting proposal.
• Track proposal for namespace-based generated types file splitting #929 tracks the namespace-splitting proposal discussion.
• [Generator][Experimental] Add opt-in dependency-aware sharded Types generation #866 contains earlier sharding discussion.

The intended proposal scope is:

• Add an optional output.maxDeclarationsPerFile setting for generated types.
• Keep the normal eight output files when the setting is omitted.
• Split each supported namespace's immediate declarations into chunks, retaining the unsuffixed filename for the first chunk and adding numbered extension files for overflow.
• Preserve generated adopter-facing API names, signatures, and access levels.
• Support direct generation and the command plugin; defer dynamic-output support in the SwiftPM and Xcode build-tool plugin.
• Consider a fixed number of files as an alternative, including its build-tool plugin advantages and the empty-file overhead of applying one count to every namespace.

The proposal includes benchmark charts comparing namespace splitting with declaration limits of 100 and 1,000. Dependency-aware layering remains a future direction.