Namespace ancillary codegen output into parallel kind-trees (view::, oneofs::, ext::)

[iainmcgin]

Summary

Ancillary types emitted by buffa-codegen — borrowed views, oneof enums, oneof view enums, extension consts, and the per-file registration fn — previously lived in the same Rust namespace as user-declared proto types and could collide with them. For example, a message FooView in a .proto would clash with the generated view type of sibling message Foo; message DataType { oneof data_type {...} } would put a struct and an enum of the same name side by side.

This PR moves every ancillary generated type into a dedicated kind-namespaced parallel tree (view::, oneofs::, ext::, view::oneofs::), structurally deconflicting the codegen output from proto-derived names. The design rule (now documented in DESIGN.md) is:

Ancillary kinds are outermost; modifiers (only view today) wrap them; inside every tree the proto message path is mirrored.

Layout changes

Before	After
pkg::FooView	pkg::view::FooView
pkg::foo::BarView (nested msg view)	pkg::view::foo::BarView
pkg::foo::KindOneof (oneof enum)	pkg::oneofs::foo::Kind
pkg::foo::KindOneofView (oneof view enum)	pkg::view::oneofs::foo::Kind
pkg::FOO (extension const)	pkg::ext::FOO
pkg::register_types	pkg::ext::register_types

Suffix policy

• Message view structs keep the View suffix (pkg::view::foo::FooView) — this is the one documented exception to the "tree disambiguates, so drop the suffix" rule. Rationale: users commonly import a message and its view into the same scope (use pkg::{Foo, view::FooView};), and a scope-level rename would be friction for every call site.
• Oneof enums and oneof view enums both drop their suffixes — the parallel-tree position is the disambiguator, and neither name is commonly co-imported with an unrelated type called Kind.

Co-import ergonomics

use pkg::{Foo, view::FooView};
fn process(m: &Foo, v: FooView<'_>) { /* ... */ }

Codegen internals

• GeneratedFile gains kind: GeneratedFileKind and package: String fields. GeneratedFileKind has five variants: Owned, View, Ext, Oneofs, ViewOneofs. Each proto produces five sibling output files (.rs, .__view.rs, .__ext.rs, .__oneofs.rs, .__view_oneofs.rs); empty bodies when the kind has no content for that proto.
• generate_module_tree accepts &[ModuleTreeEntry<'_>] and coalesces per-package streams across multiple .proto files so packages that span files (e.g. google.rpc) merge their view:: / ext:: / oneofs:: / view::oneofs:: blocks into single wrappers per kind.
• CodeGenError::OneofNameConflict and the reserved-name machinery around oneof-vs-nested-type collisions are deleted — the collisions they guarded against are now structurally impossible.
• Checked-in generated code (WKTs + bootstrap descriptor types) fully regenerated. Bootstrap uses generate_views=false, so its .__view*.rs siblings are empty stubs; the file count is kept consistent for the module tree stitcher.

Deconfliction wins

Patterns that were previously rejected at codegen time (or required OneofNameConflict errors with proto renames) now compile as-is:

• message DataType { oneof data_type {...} }
• message Foo { nested message Kind {...} oneof kind {...} }
• message M { nested message FooView {...} oneof foo {...} }
• Sibling oneofs my_field and my_field_view

DESIGN.md

Adds a "Generated code layout — parallel trees per kind" section covering the formula, the five-sibling invariant, the path-table worked example for my.pkg.Foo, the View-suffix exception with rationale, and the three structural benefits (collision-free / predictable / feature-gatable per kind).

Migration for downstream consumers

// Before
use pkg::{Foo, FooView, FOO, register_types};
use pkg::foo::{KindOneof, InnerMessage};

// After
use pkg::Foo;
use pkg::view::FooView;
use pkg::ext::{FOO, register_types};
use pkg::oneofs::foo::Kind;
use pkg::foo::InnerMessage;

Test plan

• cargo check --workspace clean
• task test — 1448 tests pass (18 suites), 0 failed
• task test-codegen — snapshot tests pass
• task lint — cargo fmt --check and cargo clippy --workspace --all-targets -- -D warnings both clean
• task lint-md — markdownlint clean
• task conformance — 6 CONFORMANCE SUITE PASSED lines, baseline numbers match exactly (std 5549 / no_std 5529 / view 2797 binary+JSON; 883/883/0 text)
• task stress-googleapis — 235 files compile cleanly (including multi-file google.rpc)
• Three previously-inverted tests/naming.rs collision tests are further updated to coexist assertions; OneofNameConflict test references removed with the variant

Diff breakdown by category

Total: 113 files, +6339 / -3562.

Category	Files	+lines	-lines	Notes
Core codegen source (buffa-codegen/src/*.rs, non-test)	7	744	320	Path resolution + module-tree stitching for the full kind matrix, including oneofs and view-oneofs wrappers. Net +424.
Codegen tests (snapshot + integration)	8	423	261	Snapshot updates + coexist regression tests for the deconfliction patterns. Net +162.
buffa-build API adaptation	1	103	42	Plumbing the five-kind ModuleTreeEntry through the build-script path. Net +61.
buffa-test consumer test suite	14	289	205	Mechanical import-path migration across the end-to-end suite. Net +84.
buffa-types / buffa-descriptor hand-maintained	5	96	37	lib.rs / mod.rs hand-stitch the pub mod view { pub mod oneofs {} }, pub mod oneofs, pub mod ext wrappers. Net +59.
Conformance runner + examples (addressbook, envelope, logging)	7	230	33	Path reference updates + regenerated logging example. Net +197.
protoc-gen-buffa-packaging	1	44	13	Emits five ModuleTreeEntrys per proto. Net +31.
Googleapis stress tooling (gen_lib_rs.py)	1	74	25	Groups the two new sibling kinds and emits the oneofs / view_oneofs wrappers. Net +49.
DESIGN.md	1	45	0	New "Generated code layout" section. Net +45.
Subtotal — human-authored	45	2048	936	Net +1112
Regenerated WKT types (buffa-types/src/generated/)	35	3169	2588	7 protos × 5 siblings, with inlined view/oneof code relocated to sibling files. Net +581 (mostly because the sibling-file scheme adds some boilerplate per kind).
Regenerated bootstrap descriptor types (buffa-descriptor/src/generated/)	12	38	4	Regenerated mod.rs + sibling stubs. Net +34.
Regenerated examples/logging output	21	1084	34	task gen-logging-example output after the layout move. Net +1050.
Subtotal — regenerated	68	4291	2626	Net +1665

Human-authored change: ~2048 / 936 (32% / 26%) of the total. The rest is codegen-regenerated output where the file count expands because every proto now emits five siblings, but the per-file content shrinks correspondingly.

Breaking changes

API-breaking for downstream consumers of generated code. Pre-1.0 this is expected; the migration is mechanical (adjust import paths per the table above).

[iainmcgin]

[claude code] Addressed the kind-tree collision feedback: all three ancillary modules now live under a single pub mod __buffa { view / oneofs / ext } wrapper at each package depth, so message View { message Inner } and package foo.view no longer collide (regression tests added for both). The __buffa prefix is validated against message names, enum names, and package segments — CodeGenError::ReservedName rather than rustc E0428.

Kept the existing tree shape under the wrapper (__buffa::view::oneofs:: rather than reorganizing to __buffa::oneof::view::) to minimize the delta. No conditional re-exports for now — paths are pkg::__buffa::view::FooView etc.; happy to revisit ergonomics in a follow-up.

Also fixed a latent issue found during this: benchmarks/{buffa,gen-datasets} use hand-written include! blocks (not _include.rs) so they were silently broken — now use the four-file pattern.

One known follow-up: buffa-build::generate_include_file and buffa-codegen::generate_module_tree now hold near-identical __buffa { view { oneofs } / ext / oneofs } stitcher logic — worth extracting a shared helper to prevent drift.

[rpb-ant]

The __buffa wrapper closes the collision hole, nice. Three things I think are still worth doing:

1. register_types is still per-file. Moving it under __buffa::ext:: doesn't change that 7 WKT protos would emit 7 fns into one module; the emit_register_fn=false hack in gen_wkt_types.rs is still load-bearing. If whichever stitcher emits the __buffa wrapper also emitted one merged register_types per package, that goes away.

2. The pub mod __buffa { ... } shape gets rendered in three places (generate_module_tree, buffa-build's generate_include_file, the packaging plugin). Probably want one of those canonical and the others delegating, otherwise adding a kind means touching all three plus the hand-rolled copies in conformance/buffa-test/buffa-types/benchmarks.

3. Related to 2: a buffa::include_proto!("pkg") macro would let the hand-rolled consumers stop copy-pasting the wrapper. codegen: namespace ancillary types under buffa_:: sentinel + per-package stitcher #62 has codegen emit a <pkg>.mod.rs per package and the macro just includes that, pretty cheap.

(I'd thought the file-level enum reservation was a gap too but check_siblings already covers it, my bad.)

Also we should just pick __buffa vs buffa_ and oneofs vs oneof and converge, the two PRs are basically a rename apart at this point.

[iainmcgin]

[claude code] Superseded by #62 — same goal, cleaner architecture (per-package .mod.rs stitcher + include_proto! macro, single canonical ALLOW_LINTS, merged per-package register_types). The reserved-name validator and collision regression tests from this branch were ported into #62.