feat(buffa-codegen): gate generated json/views/text impls on crate features

[iainmcgin]

Summary

Adds the codegen mechanism that lets buffa-descriptor (and, if we choose to later, buffa-types) ship every generated impl while keeping the codegen toolchain (buffa-codegen / buffa-build / protoc-gen-buffa) lean. #118 (stacked on this PR) does the buffa-descriptor regen and dep cleanup. Tracked in #113.

What

CodeGenConfig::gate_impls_on_crate_features: bool (default false). When true, generated impls controlled by generate_json, generate_views, and generate_text are wrapped in #[cfg(feature = "json" | "views" | "text")] (or #[cfg_attr(...)] for derives and field attributes) instead of being emitted unconditionally. The consuming crate defines matching Cargo features:

[features]
json  = ["buffa/json", "dep:serde", "dep:serde_json"]
views = []
text  = ["buffa/text"]

The generate_* flags still control whether an impl kind is emitted; the new flag only controls how. generate_arbitrary is unchanged — it was always cfg_attr-gated. Default false is a no-op: task gen-bootstrap-types / task gen-wkt-types produce byte-identical output.

Mechanism

feature_gates.rs adds a FeatureGates struct (resolved once per config from gate_impls_on_crate_features ∧ generate_*) and four pub(crate) helpers:

• cfg_block(tokens, gate) — #[cfg(feature = "x")] <item> for a single item or statement, with a debug_assert against multi-item misuse (a #[cfg] outer attribute attaches only to the next item, so trailing siblings would silently leak ungated).
• cfg_const_block(tokens, gate) — #[cfg(feature = "x")] const _: () = { <impls> }; for sibling impls (the anonymous const is itself a single item; trait impls inside register globally).
• cfg_block_any(tokens, &[gates]) — #[cfg(any(feature = "a", feature = "b"))] for items that exist iff any of a set of modes is enabled. Used by register_types, which registers both JSON and text entries.
• cfg_attr(attr_body, gate) — #[cfg_attr(feature = "x", <attr>)] or #[<attr>] for derives and helper attributes that must only apply when the feature is on (a #[serde(...)] field attribute on a struct that doesn't #[derive(Serialize)] is a hard compile error).

What's gated

Surface	Wrapped as	Where
#[derive(::serde::Serialize, ::serde::Deserialize)], #[serde(default)]	cfg_attr(feature = "json", ...)	message.rs
Field #[serde(rename = ...)], oneof #[serde(flatten)], unknown-fields #[serde(skip)]	cfg_attr	message.rs
Custom impl Deserialize, impl ProtoElemJson, oneof impl Serialize, view impl Serialize	cfg(feature = "json")	message.rs, oneof.rs, view.rs
Enum impl Serialize/Deserialize/ProtoElemJson	cfg(feature = "json") on a const _: () = { ... };	enumeration.rs
__FooExtJson wrapper's Serialize/Deserialize	cfg(feature = "json"); the struct + Deref/DerefMut/From stay unconditional — encode/decode reach the inner UnknownFields through DerefMut and a struct field's type can't change behind a cfg	message.rs
JSON/Text Any consts (__*_JSON_ANY / __*_TEXT_ANY), JSON/Text extension consts	cfg	message.rs, extension.rs
impl ::buffa::text::TextFormat (including the MessageSet early return)	cfg(feature = "text")	impl_text.rs
__buffa::view module in the stitcher, natural-path pub use ... FooView;	cfg(feature = "views")	lib.rs, message.rs
register_types fn body statements, the fn declaration, and its package-root re-export	per-statement cfg; cfg(any(feature = "json", feature = "text")) on the fn and re-export	lib.rs

Tests

• feature_gates.rs helper unit tests: for_config resolution, cfg_block/cfg_const_block/cfg_attr/cfg_block_any shapes, the debug_assert against multi-item cfg_block misuse.
• tests/feature_gating.rs integration tests against generated output: cfg attributes appear in the right places; ungated output has zero feature = "json"|"views"|"text" references; disabling a generate_* flag suppresses both the impl and its gate; the __ExtJson wrapper struct is unconditional but its serde impls are gated; register_types carries any(json, text) gates on both the fn and its re-export; syn::parse_file smoke test for structural validity.

Notes for review

rust-code-reviewer ran. Findings addressed:

• HIGH: the MessageSet early return in impl_text.rs bypassed the gate — fixed.
• HIGH: register_types referenced TypeRegistry unconditionally when its body could be all-cfg'd-out — gated the fn and re-export on any(json, text).
• MEDIUM: doc comments incorrectly described an inner #![cfg] (it's an outer #[cfg] on the const) — fixed.
• MEDIUM: string-match assertions were brittle to prettyplease line-wrapping — added a squash() helper and normalised them.
• MEDIUM: cfg_block had no enforcement against multi-item misuse — debug_assert added.
• MEDIUM: no test for generate_json = false + gating on — added.
• HIGH (acknowledged, deferred): no compile coverage with each feature combination. Added a syn::parse_file smoke test as a structural floor; this PR adds a feature_gating_compile matrix test against the buffa-test/protos/ fixture set, and feat(buffa-descriptor): regen with views/json/text/arbitrary behind crate features #118 (the buffa-descriptor regen) is verified end-to-end against bufbuild/registry/bufbuild/buf with each feature combo.

Follow-ups (separate PRs)

• feat(buffa-descriptor): regen with views/json/text/arbitrary behind crate features #118 (stacked on this one) — regen buffa-descriptor with gate_impls_on_crate_features = true, define json/views/text/arbitrary features in its Cargo.toml, and dep on it from buffa-codegen with default-features = false. Closes Feature-gated codegen impls + buffa-descriptor regen for descriptor message types as fields #113.
• buffa-build builder method + protoc-gen-buffa plugin opt to expose the knob for downstream codegen integrations.
• Decide whether buffa-types should also be regen'd with the gate. Less urgent — WKT views/text are the only unconditional impls that would benefit; JSON is hand-written and arbitrary is already cfg_attr-gated.
• CI matrix building buffa-descriptor with each feature combination (the feature_gating_compile test in this PR covers the codegen-output shape; feat(buffa-descriptor): regen with views/json/text/arbitrary behind crate features #118's cargo check matrix covers buffa-descriptor itself; a CI step would pin both).

[github-actions]

All contributors have signed the CLA ✍️ ✅
_{Posted by the CLA Assistant Lite bot.}

[iainmcgin]

Update: compile-matrix coverage

Pushed a second commit adding tests/feature_gating_compile.rs. The string-match assertions and syn::parse_file smoke test verify the shape of gated output but not that it resolves — a cfg-gated item referenced from an ungated context is valid Rust syntax and only fails at name resolution.

The new test generates all 24 protoc-buildable buffa-test/protos/*.proto files with gate_impls_on_crate_features = true, lays them out in a temp crate that defines json/views/text features, and cargo checks each of the 8 {json, views, text} subsets. #[ignore]d (slow ~30s warm); CI runs it explicitly via a new Feature-gating compile matrix step.

It caught a real bug the existing tests missed: top-level message view re-exports (pub use self::__buffa::view::FooView;, emitted in lib.rs rather than message.rs where the nested-message and view-oneof re-exports live) were not cfg-gated. With --no-default-features, the view module is cfg'd out but the re-export survives and the build fails with could not find view in __buffa. Fixed and pinned with a regression test.

Coverage now:

• ✅ Ungated default — full coverage (regen no-op, all 1649 workspace tests, CI conformance + stress test).
• ✅ Gated structure — string assertions + syn::parse_file.
• ✅ Gated compile, full feature matrix — tests/feature_gating_compile.rs against the buffa-test fixture set.
• ⏳ Gated round-trip behaviour (conformance) — needs feat(buffa-descriptor): regen with views/json/text/arbitrary behind crate features #118's buffa-descriptor regen (the conformance binary path-deps on buffa-descriptor transitively and would need its features defined to build with each combo). feat(buffa-descriptor): regen with views/json/text/arbitrary behind crate features #118 verifies the more important end-to-end case directly: bufbuild/registry and bufbuild/buf modules generate and compile cleanly with views=true, json=true.
• ✅ googleapis stress test (verified in feat(buffa-descriptor): regen with views/json/text/arbitrary behind crate features #118 — task stress-googleapis PASS with the regen'd buffa-descriptor in the build chain).