Skip to main content

buffa_build/
lib.rs

1// Modified by ReallyMe Technologies Limited.
2//! Build-time integration for buffa.
3//!
4//! Use this crate in your `build.rs` to compile `.proto` files into Rust code
5//! at build time. Parses `.proto` files into a `FileDescriptorSet` (via
6//! `protoc` or `buf`), then uses `buffa-codegen` to generate Rust source.
7//!
8//! # Example
9//!
10//! ```rust,ignore
11//! // build.rs
12//! fn main() {
13//!     buffa_build::Config::new()
14//!         .files(&["proto/my_service.proto"])
15//!         .includes(&["proto/"])
16//!         .compile()
17//!         .unwrap();
18//! }
19//! ```
20//!
21//! # Requirements
22//!
23//! By default, requires `protoc` on the system PATH (or set via the `PROTOC`
24//! environment variable) — the same as `prost-build` and `tonic-build`.
25//!
26//! If `protoc` is unavailable or outdated on your platform, `buf` can be
27//! used instead — see [`Config::use_buf()`]. Alternatively, feed a
28//! pre-compiled descriptor set via [`Config::descriptor_set()`] (a file) or
29//! [`Config::descriptor_set_bytes()`] (in-memory bytes).
30
31use std::borrow::Cow;
32use std::collections::BTreeSet;
33use std::path::{Component, Path, PathBuf};
34use std::process::Command;
35
36use buffa_codegen::generated::descriptor::FileDescriptorSet;
37
38/// Typed configuration for opt-in native adapters.
39pub use buffa_codegen::adapters;
40#[doc(inline)]
41pub use buffa_codegen::CodeGenConfig;
42#[doc(inline)]
43pub use buffa_codegen::FeatureGateNames;
44#[doc(inline)]
45pub use buffa_codegen::ReflectMode;
46#[doc(inline)]
47pub use buffa_codegen::{BytesRepr, CodecStrategy, MapRepr, PointerRepr, RepeatedRepr, StringRepr};
48#[doc(inline)]
49pub use buffa_codegen::{EnumTypeOverride, FeatureOverride};
50
51/// How to produce a `FileDescriptorSet` from `.proto` files.
52#[derive(Debug, Clone, Default)]
53enum DescriptorSource {
54    /// Invoke `protoc` (default). Requires `protoc` on PATH or `PROTOC` env var.
55    #[default]
56    Protoc,
57    /// Invoke `buf build --as-file-descriptor-set`. Requires `buf` on PATH.
58    Buf,
59    /// Read a pre-built `FileDescriptorSet` from a file.
60    Precompiled(PathBuf),
61    /// Use a pre-built `FileDescriptorSet` already in memory.
62    Bytes(Vec<u8>),
63}
64
65/// Builder for configuring and running protobuf compilation.
66pub struct Config {
67    files: Vec<PathBuf>,
68    includes: Vec<PathBuf>,
69    out_dir: Option<PathBuf>,
70    codegen_config: CodeGenConfig,
71    descriptor_source: DescriptorSource,
72    /// If set, generate a module-tree include file with this name in the
73    /// output directory. Users can then `include!` this single file instead
74    /// of manually setting up `pub mod` nesting.
75    include_file: Option<String>,
76}
77
78impl Config {
79    /// Enable typed `(buffa.ext.file).adapters` options (default: false).
80    ///
81    /// Native files are written beside the portable output and included
82    /// explicitly in their API modules. No native adapter enters the portable
83    /// module tree. Missing or incomplete mappings fail before output is written.
84    /// Without an explicit [`Self::adapters`] configuration, at least one
85    /// requested file must declare the options, otherwise `compile()` fails
86    /// with [`adapters::ErrorReason::MissingSchemaAdapters`]. This setting
87    /// only controls the schema options: it does not suppress an explicit
88    /// [`Self::adapters`] configuration.
89    #[must_use]
90    pub fn generate_adapters(mut self, enabled: bool) -> Self {
91        self.codegen_config.generate_adapters = enabled;
92        self
93    }
94
95    /// Add descriptor-checked native adapters from a typed Rust configuration.
96    /// Replaces the previous explicit configuration; schema options, if enabled,
97    /// are combined with it and checked for collisions.
98    #[must_use]
99    pub fn adapters(mut self, config: adapters::AdapterConfig) -> Self {
100        self.codegen_config.adapters = Some(config);
101        self
102    }
103
104    /// Create a new configuration with defaults.
105    pub fn new() -> Self {
106        Self {
107            files: Vec::new(),
108            includes: Vec::new(),
109            out_dir: None,
110            codegen_config: CodeGenConfig::default(),
111            descriptor_source: DescriptorSource::default(),
112            include_file: None,
113        }
114    }
115
116    /// Add `.proto` files to compile.
117    #[must_use]
118    pub fn files(mut self, files: &[impl AsRef<Path>]) -> Self {
119        self.files
120            .extend(files.iter().map(|f| f.as_ref().to_path_buf()));
121        self
122    }
123
124    /// Add include directories for protoc to search for imports.
125    ///
126    /// Directories are searched in order. If directories overlap, the first
127    /// matching directory determines the proto-relative file name.
128    #[must_use]
129    pub fn includes(mut self, includes: &[impl AsRef<Path>]) -> Self {
130        self.includes
131            .extend(includes.iter().map(|i| i.as_ref().to_path_buf()));
132        self
133    }
134
135    /// Set the output directory for generated files.
136    /// Defaults to `$OUT_DIR` if not set.
137    #[must_use]
138    pub fn out_dir(mut self, dir: impl Into<PathBuf>) -> Self {
139        self.out_dir = Some(dir.into());
140        self
141    }
142
143    /// Enable or disable view type generation (default: true).
144    #[must_use]
145    pub fn generate_views(mut self, enabled: bool) -> Self {
146        self.codegen_config.generate_views = enabled;
147        self
148    }
149
150    /// Additionally generate the lazy view family (`FooLazyView<'a>`)
151    /// alongside the unchanged eager views (default: false).
152    ///
153    /// Lazy views decode in a single non-recursive pass, recording nested and
154    /// repeated message fields as undecoded byte ranges that decode on access
155    /// via fallible, by-value accessors (`.get()` / iteration) — untouched
156    /// sub-trees cost nothing. Validation of deferred bytes happens on
157    /// *access* (and in the fallible `to_owned_message`), not at decode.
158    /// Groups, oneof message variants, and map message values stay eager;
159    /// lazy views have no `ReflectMessage`/`OwnedView`/text surface. Eager
160    /// codegen output is byte-identical with or without the flag. Requires
161    /// [`generate_views`](Self::generate_views). See
162    /// [`CodeGenConfig::lazy_views`] for full semantics.
163    #[must_use]
164    pub fn lazy_views(mut self, enabled: bool) -> Self {
165        self.codegen_config.lazy_views = enabled;
166        self
167    }
168
169    /// Enable or disable serde JSON generation (default: false).
170    ///
171    /// When enabled:
172    /// - Generated message structs get `Serialize`/`Deserialize` derives.
173    /// - Generated enum types get `Serialize`/`Deserialize` derives.
174    /// - Generated view types (when `generate_views` is also enabled) get a
175    ///   manual `impl Serialize` for zero-copy JSON serialization, so
176    ///   `serde_json::to_string(&view)` works directly:
177    ///
178    ///   ```ignore
179    ///   let view = MyMsgView::decode_view(&bytes)?;
180    ///   let json = serde_json::to_string(&view)?;
181    ///   ```
182    ///
183    /// The downstream crate must depend on `serde` and enable the `buffa/json`
184    /// feature for the runtime helpers. When views are enabled, the crate must
185    /// also enable `buffa-types/json` so the well-known type views implement
186    /// `Serialize`; without it, references to e.g. `TimestampView<'_>` in the
187    /// generated `Serialize` impl will fail with
188    /// `the trait bound 'TimestampView<'_>: Serialize' is not satisfied`.
189    ///
190    /// **Limitations of the view `Serialize` impl:**
191    /// - Extension fields are not included in view JSON output; serialize the
192    ///   owned form (`view.to_owned_message()`) to include extensions.
193    /// - The impl uses `serialize_map(None)` (unknown length) because the
194    ///   number of emitted fields depends on default-omission rules. Most
195    ///   self-describing serializers (notably `serde_json`) accept this, but
196    ///   length-prefixed formats (e.g. `bincode`, `postcard`) will return a
197    ///   runtime error. The owned types' derived `Serialize` does not have this
198    ///   restriction.
199    #[must_use]
200    pub fn generate_json(mut self, enabled: bool) -> Self {
201        self.codegen_config.generate_json = enabled;
202        self
203    }
204
205    /// Enable or disable `impl buffa::text::TextFormat` on generated message
206    /// structs (default: false).
207    ///
208    /// When enabled, the downstream crate must enable the `buffa/text`
209    /// feature for the runtime textproto encoder/decoder.
210    #[must_use]
211    pub fn generate_text(mut self, enabled: bool) -> Self {
212        self.codegen_config.generate_text = enabled;
213        self
214    }
215
216    /// Enable or disable `#[derive(arbitrary::Arbitrary)]` on generated
217    /// types (default: false).
218    ///
219    /// The derive is gated behind `#[cfg_attr(feature = "arbitrary", ...)]`
220    /// so the downstream crate compiles with or without the feature enabled.
221    /// An enum with a `[deprecated = true]` variant gets a generated impl
222    /// under the same gate instead, because the derive would warn on that
223    /// variant. The impl maps input to variants as the derive does.
224    ///
225    /// Your crate's Cargo feature **must be named exactly `"arbitrary"`** —
226    /// the generated `cfg_attr` uses that literal string and cannot be
227    /// customised — and it must forward to `buffa/arbitrary`:
228    ///
229    /// ```toml
230    /// [features]
231    /// arbitrary = ["dep:arbitrary", "buffa/arbitrary"]
232    /// ```
233    ///
234    /// Forgetting `"buffa/arbitrary"` produces a confusing error in generated
235    /// code, such as ``cannot find function `arbitrary_proto_bytes` in module
236    /// `buffa::__private` ``, when a `string_type` or `bytes_type` rule selects
237    /// a non-default type: the functions that back `#[arbitrary(with = ...)]`
238    /// on those fields live in `buffa` under that feature gate.
239    #[must_use]
240    pub fn generate_arbitrary(mut self, enabled: bool) -> Self {
241        self.codegen_config.generate_arbitrary = enabled;
242        self
243    }
244
245    /// Omit the generated `Debug` implementation for the matching messages
246    /// and enums, so that your crate can write its own.
247    ///
248    /// Each path is a fully-qualified proto path. For messages it is a
249    /// prefix: `".demo.Uuid4"` names that message and the messages nested
250    /// inside it, `".demo"` every message in the package and its
251    /// sub-packages, and `"."` every message. A matched message's oneof
252    /// enums lose their `Debug` with it. An enum loses its `Debug` only when
253    /// a path is its exact name, such as `".demo.Level"`: a message or
254    /// package path leaves the enums under it as they are. A leading dot is
255    /// added if missing and trailing dots are trimmed. Repeated calls
256    /// accumulate.
257    ///
258    /// Eager, lazy, and owned views of matched messages, and their view oneofs,
259    /// keep `Debug` but print only the type name and `[REDACTED]`. This also
260    /// hides preserved unknown wire fields. The rule affects generated
261    /// formatting only. For selective redaction in generated and reflective
262    /// formatting, use `[debug_redact = true]`. A hand-written `Debug` impl
263    /// for a matched owned message or oneof decides what that value prints.
264    ///
265    /// Your crate then implements `Debug`:
266    ///
267    /// - for every matched enum, because [`buffa::Enumeration`] requires it;
268    /// - for a matched message that an unmatched message or oneof holds
269    ///   (their generated `Debug` formats it), that is generated with
270    ///   reflection, or that a custom `repeated_type` collection holds;
271    /// - for a matched message's oneof enum, if your `Debug` for the message
272    ///   prints it. For a oneof `kind` in `demo.Uuid4` the enum is
273    ///   `demo::uuid4::Kind`.
274    ///
275    /// A missing impl is a compile error. For an enum it is error E0277
276    /// (`Level` doesn't implement `Debug`) at the generated
277    /// `impl ::buffa::Enumeration for Level`. A path that matches no
278    /// generated message and names no generated enum prints a
279    /// `cargo:warning`.
280    ///
281    /// # Example
282    ///
283    /// ```rust,ignore
284    /// // build.rs
285    /// buffa_build::Config::new()
286    ///     .files(&["proto/demo.proto"])
287    ///     .includes(&["proto/"])
288    ///     .skip_debug(&[".demo.Uuid4", ".demo.Level"])
289    ///     .compile()?;
290    ///
291    /// // src/lib.rs
292    /// pub mod demo {
293    ///     buffa::include_proto!("demo");
294    /// }
295    ///
296    /// impl core::fmt::Debug for demo::Uuid4 {
297    ///     fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
298    ///         write!(f, "Uuid4({:016x}{:016x})", self.msb, self.lsb)
299    ///     }
300    /// }
301    ///
302    /// // Prints the value's proto name, as the derive it replaces does.
303    /// impl core::fmt::Debug for demo::Level {
304    ///     fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
305    ///         f.write_str(buffa::Enumeration::proto_name(self))
306    ///     }
307    /// }
308    /// ```
309    #[must_use]
310    pub fn skip_debug(mut self, paths: &[impl AsRef<str>]) -> Self {
311        for raw in paths.iter().map(AsRef::as_ref) {
312            let normalized = normalize_override_path(raw);
313            if normalized.is_empty() {
314                println!(
315                    "cargo:warning=buffa: skip_debug path '{raw}' \
316                     normalizes to empty and will be ignored"
317                );
318                continue;
319            }
320            self.codegen_config.skip_debug.push(normalized);
321        }
322        self
323    }
324
325    /// Reject JSON serialization of the selected messages' eager, lazy and owned
326    /// views before writing any output. Owned-message JSON remains available.
327    /// The restriction propagates to containing messages, including map values.
328    /// `.` selects every message; unmatched rules cause a code generation error.
329    /// Empty paths are errors. Disabling JSON or views warns that the rule is inactive.
330    #[must_use]
331    pub fn deny_view_json(mut self, paths: &[impl AsRef<str>]) -> Self {
332        self.codegen_config.deny_view_json.extend(
333            paths
334                .iter()
335                .map(|path| normalize_override_path(path.as_ref())),
336        );
337        self
338    }
339
340    /// Omit standard owned-view wrappers and `HasMessageView` for matching
341    /// messages and their containers. Borrowed views remain available.
342    /// Use `.` to select every message. Rules must match a known message.
343    /// Messages selected for cleanup, and their containers, are always
344    /// treated as selected.
345    ///
346    /// This controls what code is generated. It does not disable explicit
347    /// use of the public `buffa::OwnedView` runtime with a borrowed view type.
348    #[must_use]
349    pub fn borrowed_views_only_in(mut self, paths: &[impl AsRef<str>]) -> Self {
350        self.codegen_config.borrowed_views_only_in.extend(
351            paths
352                .iter()
353                .map(|path| normalize_override_path(path.as_ref())),
354        );
355        self
356    }
357
358    /// Wrap generated `impl`s in `#[cfg(feature = "...")]` instead of
359    /// emitting them unconditionally (default: false).
360    ///
361    /// When enabled, the impls controlled by [`generate_json`],
362    /// [`generate_views`], and [`generate_text`] are wrapped in
363    /// `#[cfg(feature = "json" | "views" | "text")]` (or
364    /// `#[cfg_attr(feature = ..., ...)]` for derives and field attributes)
365    /// rather than emitted unconditionally. The crate consuming the
366    /// generated code must define matching Cargo features that enable the
367    /// corresponding runtime support:
368    ///
369    /// ```toml
370    /// [features]
371    /// json  = ["buffa/json", "dep:serde", "dep:serde_json"]
372    /// views = []
373    /// text  = ["buffa/text"]
374    /// ```
375    ///
376    /// The `generate_*` flags still control *whether* an impl kind is
377    /// emitted at all — this flag only controls whether it is `cfg`-gated.
378    /// `generate_arbitrary` is always `cfg_attr`-gated on
379    /// `feature = "arbitrary"` regardless of this flag, because `arbitrary`
380    /// is an optional dependency by design.
381    ///
382    /// Reach for this when generated code is the **public interface of a
383    /// library crate** consumed by downstream projects with different
384    /// feature needs — exactly the shape of `buffa-descriptor` and
385    /// `buffa-types`, which ship every impl while letting the codegen
386    /// toolchain (`buffa-codegen`/`buffa-build`/`protoc-gen-reallyme-buffa`) depend
387    /// on them with `default-features = false` and stay free of
388    /// `serde`/`serde_json`/`base64`. Most consumers of `buffa-build` are
389    /// **not** in this position: a `build.rs` that decides at build-script
390    /// time whether to generate JSON wants `impl Serialize` to just exist.
391    /// Default `false`.
392    ///
393    /// [`generate_json`]: Self::generate_json
394    /// [`generate_views`]: Self::generate_views
395    /// [`generate_text`]: Self::generate_text
396    #[must_use]
397    pub fn gate_impls_on_crate_features(mut self, enabled: bool) -> Self {
398        self.codegen_config.gate_impls_on_crate_features = enabled;
399        self
400    }
401
402    /// Gate only the reflection impls behind a `reflect` crate feature, without
403    /// gating json/views/text (unlike
404    /// [`gate_impls_on_crate_features`](Self::gate_impls_on_crate_features),
405    /// which gates them together).
406    ///
407    /// For crates that ship views/text unconditionally but want the
408    /// `buffa-descriptor`-dependent (and `std`-requiring) reflection surface to
409    /// be opt-in. `buffa-types` is the motivating case.
410    ///
411    /// **Experimental and `#[doc(hidden)]`.** This knob only controls the
412    /// crate-feature gate on the emitted reflection impls; the reflection
413    /// codegen mode itself is selected via the public
414    /// [`reflect_mode`](Self::reflect_mode) selector.
415    #[doc(hidden)]
416    #[must_use]
417    pub fn gate_reflect_on_crate_feature(mut self, enabled: bool) -> Self {
418        self.codegen_config.gate_reflect_on_crate_feature = enabled;
419        self
420    }
421
422    /// Set the crate feature name the gated JSON impls are conditioned on
423    /// (default: `"json"`).
424    ///
425    /// Only meaningful together with
426    /// [`gate_impls_on_crate_features`](Self::gate_impls_on_crate_features);
427    /// inert otherwise. Use when the consuming crate gates its JSON support
428    /// behind a differently-named feature:
429    ///
430    /// ```toml
431    /// [features]
432    /// serde = ["buffa/json", "dep:serde", "dep:serde_json"]
433    /// ```
434    ///
435    /// ```rust,ignore
436    /// buffa_build::Config::new()
437    ///     .generate_json(true)
438    ///     .gate_impls_on_crate_features(true)
439    ///     .json_feature_name("serde")
440    /// # ;
441    /// ```
442    ///
443    /// The name is emitted verbatim into `#[cfg(feature = "...")]`
444    /// attributes and must be a valid Cargo feature name **declared in the
445    /// consuming crate's `[features]` table**. A misspelled or undeclared
446    /// name fails open: the `#[cfg]` is permanently false, so the gated
447    /// impls silently compile away (on Rust ≥ 1.80 an undeclared name at
448    /// least triggers the `unexpected_cfgs` warning). A name that is not a
449    /// valid Cargo feature name at all (empty, or containing characters
450    /// outside alphanumerics and `_`/`-`/`+`/`.`) makes [`compile`](Self::compile)
451    /// fail with an error when the gate is active.
452    #[must_use]
453    pub fn json_feature_name(mut self, name: impl Into<String>) -> Self {
454        self.codegen_config.feature_gate_names.json = name.into();
455        self
456    }
457
458    /// Set the crate feature name the gated view impls are conditioned on
459    /// (default: `"views"`).
460    ///
461    /// Only meaningful together with
462    /// [`gate_impls_on_crate_features`](Self::gate_impls_on_crate_features);
463    /// inert otherwise. See [`json_feature_name`](Self::json_feature_name).
464    #[must_use]
465    pub fn views_feature_name(mut self, name: impl Into<String>) -> Self {
466        self.codegen_config.feature_gate_names.views = name.into();
467        self
468    }
469
470    /// Set the crate feature name the gated textproto impls are conditioned
471    /// on (default: `"text"`).
472    ///
473    /// Only meaningful together with
474    /// [`gate_impls_on_crate_features`](Self::gate_impls_on_crate_features);
475    /// inert otherwise. See [`json_feature_name`](Self::json_feature_name).
476    #[must_use]
477    pub fn text_feature_name(mut self, name: impl Into<String>) -> Self {
478        self.codegen_config.feature_gate_names.text = name.into();
479        self
480    }
481
482    /// Set the crate feature name the gated reflection impls are conditioned
483    /// on (default: `"reflect"`).
484    ///
485    /// Only meaningful together with
486    /// [`gate_impls_on_crate_features`](Self::gate_impls_on_crate_features)
487    /// (or the experimental, hidden `gate_reflect_on_crate_feature`, which
488    /// gates reflection alone); inert otherwise. See
489    /// [`json_feature_name`](Self::json_feature_name).
490    #[must_use]
491    pub fn reflect_feature_name(mut self, name: impl Into<String>) -> Self {
492        self.codegen_config.feature_gate_names.reflect = name.into();
493        self
494    }
495
496    /// Prepend a prefix to every generated Rust type name (default: none).
497    ///
498    /// With prefix `"Rpc"`, `message User {}` generates `struct RpcUser`
499    /// (and `RpcUserView` / `RpcUserOwnedView`); every cross-reference uses
500    /// the prefixed name. Useful in multi-protocol systems where generated
501    /// types from different domains would otherwise collide with each other
502    /// or with a canonical hand-written model.
503    ///
504    /// Applies to message structs and enum types (top-level and nested).
505    /// Module names, oneof enums, [`extern_path`](Self::extern_path)-mapped
506    /// types (including well-known types), and the wire/JSON format are
507    /// unaffected.
508    ///
509    /// When another crate references these prefixed types via its own
510    /// [`extern_path`](Self::extern_path) mapping, the mapped Rust path must
511    /// spell out the prefixed name (e.g. `::crate_a::RpcUser`) — the proto
512    /// name carries no prefix, so the mapping is not derived automatically.
513    ///
514    /// The prefix must be PascalCase (`[A-Z][A-Za-z0-9]*`) — an ASCII
515    /// uppercase letter followed by ASCII letters and digits — so the
516    /// prefixed names stay conventionally cased; [`compile`](Self::compile)
517    /// fails otherwise.
518    #[must_use]
519    pub fn type_name_prefix(mut self, prefix: impl Into<String>) -> Self {
520        self.codegen_config.type_name_prefix = prefix.into();
521        self
522    }
523
524    /// Enable or disable `with_*` builder-style setter methods for
525    /// explicit-presence fields (default: true).
526    ///
527    /// Each explicit-presence scalar, bytes, or enum field gets a
528    /// `pub fn with_<name>(mut self, value: T) -> Self` method that wraps the
529    /// value in `Some(...)` and returns `self`, enabling chained construction
530    /// without the `Some(...)` boilerplate:
531    ///
532    /// ```ignore
533    /// let req = MyRequest::default()
534    ///     .with_name("alice")
535    ///     .with_timeout_ms(30_000);
536    /// ```
537    ///
538    /// String, bytes, and enum setters take `impl Into<T>` (so `&str`,
539    /// `b"..."` literals, and bare enum variants work directly); other
540    /// scalars take `T` to keep integer-literal inference unambiguous.
541    ///
542    /// Setters are pure inherent methods with no runtime dependency — they
543    /// don't interact with the `json`/`views`/`text` feature gates. Disable
544    /// only if you want to keep generated code minimal or have a competing
545    /// `with_*` convention in your own crate.
546    #[must_use]
547    pub fn generate_with_setters(mut self, enabled: bool) -> Self {
548        self.codegen_config.generate_with_setters = enabled;
549        self
550    }
551
552    /// Enable reflection on generated types (default: off).
553    ///
554    /// `generate_reflection(true)` selects [`ReflectMode::VTable`] — the fast
555    /// path: `foo.reflect()` borrows `foo` directly (no encode/decode
556    /// round-trip), and owned and view types implement `ReflectMessage`. For
557    /// the smaller bridge implementation (`reflect()` round-trips through a
558    /// [`DynamicMessage`]), use [`reflect_mode(ReflectMode::Bridge)`](Self::reflect_mode)
559    /// instead. `generate_reflection(false)` is [`ReflectMode::Off`].
560    ///
561    /// Either mode embeds a lazily-built [`DescriptorPool`] (as
562    /// `FileDescriptorSet` bytes) reachable as
563    /// `your_crate::your_pkg::descriptor_pool()`.
564    ///
565    /// # Cargo.toml setup
566    ///
567    /// The consuming crate must depend on `buffa-descriptor` with the
568    /// `reflect` feature and on `std`:
569    ///
570    /// ```toml
571    /// [dependencies]
572    /// buffa = { package = "reallyme-buffa", version = "=0.1.3", features = ["std"] }
573    /// buffa-descriptor = { package = "reallyme-buffa-descriptor", version = "=0.1.3", features = ["reflect", "std"] }
574    /// ```
575    ///
576    /// When [`gate_impls_on_crate_features`](Self::gate_impls_on_crate_features)
577    /// is also on, the impls are wrapped in `#[cfg(feature = "reflect")]`,
578    /// so the consuming crate must declare a forwarding feature:
579    ///
580    /// ```toml
581    /// [features]
582    /// reflect = ["buffa-descriptor/reflect"]
583    /// ```
584    ///
585    /// **Without the feature declared, the generated `Reflectable` impls
586    /// silently disappear** — `cfg(feature = "reflect")` is permanently
587    /// false in a crate that doesn't declare it. The first call to
588    /// `.reflect()` fails to compile with "trait `Reflectable` not
589    /// implemented", which is a misleading diagnostic. Most consumers
590    /// should leave `gate_impls_on_crate_features` off.
591    ///
592    /// Reflecting message-typed fields also requires every crate that field
593    /// types resolve to via an extern path — notably `buffa-types` for
594    /// well-known types — to enable its own reflection feature; see
595    /// [`reflect_mode`](Self::reflect_mode) ("Extern-path types") for the
596    /// `Cargo.toml` requirement and mixed-mode behavior.
597    ///
598    /// # Performance
599    ///
600    /// In the default vtable mode, `reflect()` borrows `self` — no round-trip,
601    /// no allocation; reflective accessors read fields in place. (Bridge mode
602    /// instead pays one encode/decode round-trip plus a heap allocation per
603    /// call.) Either way the first call pays a one-time pool build cost.
604    ///
605    /// # Build time and binary size
606    ///
607    /// By default each generated package embeds its own copy of the full
608    /// `FileDescriptorSet` (transitive closure). For a single-package
609    /// crate this is one copy. For a multi-package codegen run the bytes
610    /// duplicate per package — measurable for large proto trees;
611    /// [`shared_descriptor_pool`](Self::shared_descriptor_pool) collapses that
612    /// to one `include_bytes!` sidecar. The serialization happens once per
613    /// `compile()` call (not per package), so build-time CPU does not scale
614    /// with package count. Vtable mode also emits an `impl ReflectMessage` per
615    /// type, so it produces more code than bridge mode.
616    ///
617    /// [`ReflectCow`]: https://docs.rs/reallyme-buffa-descriptor/latest/buffa_descriptor/reflect/enum.ReflectCow.html
618    /// [`DynamicMessage`]: https://docs.rs/reallyme-buffa-descriptor/latest/buffa_descriptor/reflect/struct.DynamicMessage.html
619    /// [`DescriptorPool`]: https://docs.rs/reallyme-buffa-descriptor/latest/buffa_descriptor/struct.DescriptorPool.html
620    #[must_use]
621    pub fn generate_reflection(mut self, enabled: bool) -> Self {
622        // The simple on/off knob selects the fast vtable path; Bridge is opt-in
623        // via `reflect_mode`.
624        let mode = if enabled {
625            ReflectMode::VTable
626        } else {
627            ReflectMode::Off
628        };
629        mode.apply(&mut self.codegen_config);
630        self
631    }
632
633    /// Select the reflection mode (the fuller form of
634    /// [`generate_reflection`](Self::generate_reflection)).
635    ///
636    /// - [`ReflectMode::Off`] — no reflection (the default); equivalent to
637    ///   `generate_reflection(false)`.
638    /// - [`ReflectMode::Bridge`] — `reflect()` round-trips through
639    ///   `DynamicMessage`; smaller generated code, slower reflective access.
640    /// - [`ReflectMode::VTable`] — `impl ReflectMessage` on owned and view
641    ///   types, and `reflect()` borrows `self` with no round-trip; equivalent
642    ///   to `generate_reflection(true)`. Does not require view generation —
643    ///   with views off, only the owned impls are emitted.
644    ///
645    /// All non-`Off` modes require the consuming crate to depend on
646    /// `buffa-descriptor` with its `reflect` feature and on `std`. The call
647    /// site (`foo.reflect().get(fd)`) is identical across modes.
648    ///
649    /// # Extern-path types
650    ///
651    /// Reflection on a message reaches into its message-typed fields, so
652    /// every crate that field types resolve to via an extern path must have
653    /// its own reflection enabled. In particular, well-known types resolve
654    /// to `buffa-types` by default, and its impls are behind a cargo
655    /// feature: depend on `buffa-types = { ..., features = ["reflect"] }`
656    /// or the build fails with unsatisfied `Reflectable` /
657    /// `ReflectMessage` bounds on the WKT.
658    ///
659    /// # Mixed modes
660    ///
661    /// A vtable-mode message may embed owned message types generated in
662    /// bridge mode (e.g. a dependency crate that chose the smaller output):
663    /// reflective access degrades to an owned `DynamicMessage` snapshot at
664    /// that boundary instead of failing. For a bridge-grade `repeated` or
665    /// `map` field the snapshot is taken per element on every access, so
666    /// reflecting a large mixed-mode collection scales the encode/decode
667    /// cost by the element count. The *view* reflection surface cannot
668    /// degrade — every view type embedded in a vtable-mode view must itself
669    /// be vtable-grade, and a bridge-grade view field is a compile error.
670    #[must_use]
671    pub fn reflect_mode(mut self, mode: ReflectMode) -> Self {
672        mode.apply(&mut self.codegen_config);
673        self
674    }
675
676    /// Deduplicate the embedded reflection descriptor pool across packages.
677    ///
678    /// With reflection enabled, each package normally embeds its own copy of
679    /// the full-closure `FileDescriptorSet`. For a multi-package build those
680    /// copies are identical, so a large proto tree carries the same bytes once
681    /// per package. When this is on, the descriptor set is written once as a
682    /// binary sidecar next to the generated tree and `include_bytes!`-d by a
683    /// single shared `__buffa_fds` module; every package's `descriptor_pool()`
684    /// / `FILE_DESCRIPTOR_SET_BYTES` delegates to it. This removes both the
685    /// per-package duplication and the byte-literal source expansion.
686    ///
687    /// The sidecar is named `<include-file-stem>.descriptor_set.binpb` (so
688    /// `.include_file("gen_mod.rs")` writes `gen_mod.descriptor_set.binpb`)
689    /// and lands in the output directory next to the include file. With a
690    /// checked-in [`out_dir`](Self::out_dir), commit the sidecar alongside
691    /// the generated `.rs` files — the `include_bytes!` resolves relative to
692    /// the include file, so the pair must travel together.
693    ///
694    /// Requires [`include_file`](Self::include_file) (the shared module is
695    /// emitted into that file at the tree root) and reflection to be enabled;
696    /// [`compile`](Self::compile) errors otherwise. The include file name must
697    /// be a bare file name, not a path: the sidecar is named after the stem
698    /// alone, so `a/gen.rs` and `b/gen.rs` would share one sidecar. See
699    /// [`CodeGenConfig::shared_descriptor_pool`].
700    ///
701    /// In this mode the generated tree must be consumed *through the include
702    /// file* (`include!(concat!(env!("OUT_DIR"), "/gen_mod.rs"))`, or the
703    /// checked-in `mod gen;` flavour). Each package delegates to `__buffa_fds`
704    /// by a fixed number of `super::` hops from the tree root, so wiring
705    /// packages individually with `buffa::include_proto!` does not compile
706    /// here: the delegation resolves against whatever module the macro lands
707    /// in. Two shared-pool `compile()` calls included at the same module scope
708    /// likewise collide on `__buffa_fds`; give each include file its own
709    /// module.
710    #[must_use]
711    pub fn shared_descriptor_pool(mut self, enabled: bool) -> Self {
712        self.codegen_config.shared_descriptor_pool = enabled;
713        self
714    }
715
716    /// Enable or disable idiomatic `UpperCamelCase` enum aliases (matches the
717    /// [`CodeGenConfig`] default, currently on).
718    ///
719    /// Protobuf enum values are `SHOUTY_SNAKE_CASE` and stay the definitive Rust
720    /// variants. When enabled, codegen additionally emits associated `const`s
721    /// with the enum-name prefix stripped and the name converted to
722    /// `UpperCamelCase` (`RULE_LEVEL_HIGH` → `RuleLevel::High`), purely
723    /// additively — existing references and `Debug` output are unchanged.
724    ///
725    /// Aliases are suppressed per enum (with a build warning and a doc note) if
726    /// any two values would collide after conversion, so a match is never forced
727    /// to mix conventions. See [`CodeGenConfig::idiomatic_enum_aliases`].
728    #[must_use]
729    pub fn idiomatic_enum_aliases(mut self, enabled: bool) -> Self {
730        self.codegen_config.idiomatic_enum_aliases = enabled;
731        self
732    }
733
734    /// Convert proto field and oneof names to idiomatic snake_case Rust
735    /// identifiers (`webMessageInfo` → `web_message_info`), matching
736    /// prost-build's behavior for protos that use camelCase field names.
737    /// Default: `false` (proto names are emitted verbatim).
738    ///
739    /// Only the generated Rust source names change; the wire format, JSON
740    /// (`json_name` plus the original proto name accepted on parse), text
741    /// format, and reflection lookups all keep the descriptor's names, so the
742    /// option is fully wire- and JSON-compatible. Enum values are covered by
743    /// [`idiomatic_enum_aliases`](Self::idiomatic_enum_aliases) instead.
744    ///
745    /// Word boundaries match prost-build's (heck's) segmentation, including
746    /// digit-transparent case boundaries (`v2Field` → `v2_field`); unlike
747    /// prost, authored underscores are always preserved (`_foo` stays
748    /// `_foo`), so already-snake_case names are never rewritten.
749    ///
750    /// If two members of one message collide after conversion (`userName` and
751    /// `user_name` — rejected by protoc for proto3/editions, so proto2 only),
752    /// the names are adjusted deterministically and a build warning is
753    /// emitted; see [`CodeGenConfig::idiomatic_field_names`] for the rules.
754    #[must_use]
755    pub fn idiomatic_field_names(mut self, enabled: bool) -> Self {
756        self.codegen_config.idiomatic_field_names = enabled;
757        self
758    }
759
760    /// Emit one `<dotted.package>.rs` file per proto package instead of the
761    /// per-proto-file content set plus `<pkg>.mod.rs` stitcher. Default:
762    /// `false`.
763    ///
764    /// The single file inlines what the stitcher would otherwise `include!`,
765    /// producing the same module structure. Required by
766    /// [`idiomatic_imports`](Self::idiomatic_imports). See
767    /// [`CodeGenConfig::file_per_package`] for caveats about packages that
768    /// span multiple directories.
769    #[must_use]
770    pub fn file_per_package(mut self, enabled: bool) -> Self {
771        self.codegen_config.file_per_package = enabled;
772        self
773    }
774
775    /// **Experimental.** Emit `use`-backed short type names at the package
776    /// root instead of fully-qualified paths, so struct fields read
777    /// `MessageField<Timestamp>` instead of
778    /// `::buffa::MessageField<::buffa_types::google::protobuf::Timestamp>`.
779    /// Default: `false` (output is byte-for-byte identical to previous
780    /// releases).
781    ///
782    /// Requires [`file_per_package`](Self::file_per_package) — the build
783    /// fails otherwise. Short names that would collide with another item at
784    /// the package root (or a name referenced bare by sibling emissions)
785    /// fall back to parent-module qualification, then to the
786    /// fully-qualified path.
787    ///
788    /// Only package-root type *declarations* are shortened; impl bodies,
789    /// nested-message modules, and `__buffa` internals keep fully-qualified
790    /// paths. "Experimental" means the output shape may change between
791    /// releases and the option may be renamed or removed outside semver
792    /// guarantees. See [`CodeGenConfig::idiomatic_imports`] for details.
793    #[must_use]
794    pub fn idiomatic_imports(mut self, enabled: bool) -> Self {
795        self.codegen_config.idiomatic_imports = enabled;
796        self
797    }
798
799    /// Enable or disable unknown field preservation (default: true).
800    ///
801    /// When enabled (the default), unrecognized fields encountered during
802    /// decode are stored and re-emitted on encode — essential for proxy /
803    /// middleware services and round-trip fidelity across schema versions.
804    ///
805    /// **Disabling is mostly a memory optimization**: 24 bytes per owned
806    /// message for the `UnknownFields` `Vec` header, and one pointer per
807    /// view, whose backing state is allocated only once an unknown field
808    /// actually arrives.
809    ///
810    /// A wire payload with no unknown fields does no per-field work either
811    /// way, but that does not make the two modes equivalent: carrying the
812    /// handle still shapes how the compiler moves the view, and that is
813    /// measurable on view-decode throughput for message-dense shapes.
814    /// Disabling is the only setting that removes the field outright, so it
815    /// is the lever to reach for when view decode is hot and round-trip
816    /// fidelity across schema versions is not required — as it is for
817    /// embedded / `no_std` targets and large in-memory collections of small
818    /// messages.
819    ///
820    /// To keep the global off-switch and still preserve selected messages, use
821    /// [`preserve_unknown_fields_in`](Self::preserve_unknown_fields_in).
822    #[must_use]
823    pub fn preserve_unknown_fields(mut self, enabled: bool) -> Self {
824        self.codegen_config.preserve_unknown_fields = enabled;
825        self
826    }
827
828    /// Generate recursive cleanup for every owned message.
829    /// Requires `buffa/zeroize` and guarded field representations; see the guarded-fields guide.
830    /// No owned-view wrapper or `HasMessageView` impl is generated, as with
831    /// [`borrowed_views_only_in`](Self::borrowed_views_only_in).
832    #[must_use]
833    pub fn generate_zeroize(mut self, enabled: bool) -> Self {
834        self.codegen_config.generate_zeroize = enabled;
835        self
836    }
837
838    /// Generate recursive cleanup for messages under these proto path prefixes.
839    /// `.` matches every message. Calls accumulate. Empty or unmatched paths
840    /// are errors; scoped requests can explicitly allow unmatched rules.
841    /// Selected messages and their containers get no owned-view wrapper or
842    /// `HasMessageView` impl, as with
843    /// [`borrowed_views_only_in`](Self::borrowed_views_only_in).
844    #[must_use]
845    pub fn zeroize_in(mut self, paths: &[impl AsRef<str>]) -> Self {
846        self.codegen_config.zeroize_messages.extend(
847            paths
848                .iter()
849                .map(|path| normalize_override_path(path.as_ref())),
850        );
851        self
852    }
853
854    /// Enable unknown-field preservation for matching messages, on top of
855    /// the global [`preserve_unknown_fields`](Self::preserve_unknown_fields)
856    /// setting.
857    ///
858    /// Each path is a fully-qualified proto path prefix, e.g.
859    /// `".wa.CallLogRecord"` for one message or `".wa"` for a package (same
860    /// matching as [`unbox_oneof_in`](Self::unbox_oneof_in)); `"."` matches
861    /// every message. A leading dot is added if missing and trailing dots
862    /// are trimmed. An empty path is warned about and ignored so `"."`
863    /// remains the only catch-all spelling.
864    ///
865    /// A rule covers the message it names **and every message nested inside
866    /// it**; a rule naming a nested message does not cover its enclosing
867    /// message. Rules are enable-only, so this builder cannot exclude a
868    /// nested message from a rule that names its parent
869    /// ([`CodeGenConfig::preserve_unknown_fields_in`](buffa_codegen::CodeGenConfig::preserve_unknown_fields_in)
870    /// also accepts disabling entries, and the last matching entry wins).
871    /// Preservation is a property of each message *type*: a preserved
872    /// message's sub-messages keep their own unknown fields only if their
873    /// types are covered too.
874    ///
875    /// Repeated calls accumulate. The call order relative to
876    /// [`preserve_unknown_fields`](Self::preserve_unknown_fields) does not
877    /// matter; the rules apply on top of whichever global value is in force
878    /// at [`compile`](Self::compile) time. They only change the outcome when
879    /// the global setting is off. A rule that matches no generated message
880    /// produces a `cargo:warning` from this build (surfaced via
881    /// [`CodeGenWarning`](buffa_codegen::CodeGenWarning)), since an inert
882    /// rule silently loses round-trip fidelity for the type it was meant to
883    /// keep.
884    ///
885    /// A message that does not preserve unknown fields has no
886    /// `__buffa_unknown_fields` field, and so also loses everything built on
887    /// it: the `ExtensionSet` impl (`extension()` / `set_extension()` /
888    /// `has_extension()`), `ReflectMessage::unknown_fields`, extension
889    /// round-tripping through textproto, and `[ext]` keys in JSON.
890    ///
891    /// ```rust,ignore
892    /// buffa_build::Config::new()
893    ///     .preserve_unknown_fields(false)
894    ///     .preserve_unknown_fields_in(&[".wa.CallLogRecord", ".wa.SyncdMutation"])
895    /// ```
896    #[must_use]
897    pub fn preserve_unknown_fields_in(mut self, paths: &[impl AsRef<str>]) -> Self {
898        for raw in paths.iter().map(AsRef::as_ref) {
899            let normalized = normalize_override_path(raw);
900            if normalized.is_empty() {
901                println!(
902                    "cargo:warning=buffa: preserve_unknown_fields_in path '{raw}' \
903                     normalizes to empty and will be ignored"
904                );
905                continue;
906            }
907            self.codegen_config
908                .preserve_unknown_fields_in
909                .push((normalized, true));
910        }
911        self
912    }
913
914    /// Make generated JSON deserializers reject unknown keys instead of
915    /// ignoring them (default: `false`, unknown keys are ignored).
916    ///
917    /// Strictness is fixed in the generated type: code that uses the type
918    /// cannot switch it per call or per process. To be strict for selected
919    /// messages only, use
920    /// [`deny_unknown_json_fields_in`](Self::deny_unknown_json_fields_in).
921    ///
922    /// With [`generate_json`](Self::generate_json) off there are no JSON
923    /// deserializers, so the option changes nothing and the build emits a
924    /// `cargo:warning` saying so.
925    ///
926    /// The guide's "Unknown fields in JSON" section covers the error a
927    /// rejected key produces, how `"[pkg.ext]"` extension keys are treated,
928    /// and what to weigh before enabling this for every message.
929    #[must_use]
930    pub fn deny_unknown_json_fields(mut self, enabled: bool) -> Self {
931        self.codegen_config.deny_unknown_json_fields = enabled;
932        self
933    }
934
935    /// Reject unknown JSON fields for matching messages, on top of the global
936    /// [`deny_unknown_json_fields`](Self::deny_unknown_json_fields) setting.
937    ///
938    /// Each path is a fully-qualified proto path prefix, e.g. `".demo.Config"`
939    /// for one message or `".demo"` for a package (same matching as
940    /// [`preserve_unknown_fields_in`](Self::preserve_unknown_fields_in));
941    /// `"."` matches every message. A leading dot is added if missing and
942    /// trailing dots are trimmed. An empty path is warned about and ignored so
943    /// `"."` remains the only catch-all spelling.
944    ///
945    /// A rule covers the message it names **and every message nested inside
946    /// it**; a rule naming a nested message does not cover its enclosing
947    /// message. Strictness is a property of each message *type*: a strict
948    /// message's sub-messages reject unknown keys only if their types are
949    /// covered too.
950    ///
951    /// Rules only enable, so this builder cannot exempt a message. With the
952    /// global flag on, every message is already strict and these rules add
953    /// nothing; to be strict everywhere except a few messages, leave the
954    /// global flag off and list the strict packages here.
955    /// (`buffa_codegen::CodeGenConfig` accepts disabling entries; neither
956    /// this builder nor the plugin exposes them.) With
957    /// [`generate_json`](Self::generate_json) off the rules change nothing,
958    /// and the build warns as it does for the global flag.
959    ///
960    /// Repeated calls accumulate. A rule that matches no generated message
961    /// produces a `cargo:warning` from this build (surfaced via
962    /// [`CodeGenWarning`](buffa_codegen::CodeGenWarning)), since an inert rule
963    /// leaves the message silently ignoring the keys it was meant to reject.
964    ///
965    /// ```rust,ignore
966    /// buffa_build::Config::new()
967    ///     .generate_json(true)
968    ///     .deny_unknown_json_fields_in(&[".demo.DeviceConfig"])
969    /// ```
970    #[must_use]
971    pub fn deny_unknown_json_fields_in(mut self, paths: &[impl AsRef<str>]) -> Self {
972        for raw in paths.iter().map(AsRef::as_ref) {
973            let normalized = normalize_override_path(raw);
974            if normalized.is_empty() {
975                println!(
976                    "cargo:warning=buffa: deny_unknown_json_fields_in path '{raw}' \
977                     normalizes to empty and will be ignored"
978                );
979                continue;
980            }
981            self.codegen_config
982                .deny_unknown_json_fields_in
983                .push((normalized, true));
984        }
985        self
986    }
987
988    /// Apply a path-scoped editions [`FeatureOverride`] to the compiled
989    /// descriptors before generation.
990    ///
991    /// This is buffa's mechanism for integrators who must work with protos
992    /// they cannot modify: editions unification models proto2 and proto3 as
993    /// editions with fixed feature defaults, and an override behaves as if
994    /// the proto had been migrated to editions with that feature set at the
995    /// matched paths. The supported overrides are the [`FeatureOverride`]
996    /// variants — each is admitted only once buffa's codegen, runtime, and
997    /// validation handle the descriptor states it can create. Overrides
998    /// never change the wire format.
999    ///
1000    /// `path` is a fully-qualified proto path prefix. A rule may name a type
1001    /// (for example, `".my.pkg.Status"`), a field
1002    /// (`".my.pkg.Response.status"`), a package/message prefix, or `"."` for
1003    /// everything the override targets. A leading dot is added if missing.
1004    /// Map enum values match the outer map field path; oneof enum variants
1005    /// match the direct field path. An empty path is warned about and
1006    /// ignored so `"."` remains the only global opt-in spelling. (The
1007    /// `protoc-gen-reallyme-buffa` plugin's `override_feature_in=` option rejects
1008    /// empty paths with a hard error instead: a stray build-script entry
1009    /// shouldn't fail the build, but plugin options are usually
1010    /// machine-assembled, where an empty value is a bug.)
1011    ///
1012    /// Repeated calls accumulate; rule order does not matter. A rule that
1013    /// matches nothing produces a `cargo:warning` from this build (surfaced
1014    /// via [`CodeGenWarning`](buffa_codegen::CodeGenWarning)), since an
1015    /// inert rule silently leaves the affected paths on the semantics the
1016    /// override exists to change.
1017    ///
1018    /// Under reflection, the embedded descriptor pool carries the injected
1019    /// features, so runtime reflection and descriptor-driven dynamic JSON
1020    /// stay consistent with the generated types for both enum-scoped and
1021    /// field-scoped rules. A field-scoped injection is buffa-specific,
1022    /// though: other runtimes reading the exported descriptor set ignore it.
1023    /// See [`FeatureOverride::EnumType`] for how the two scopes differ.
1024    #[must_use]
1025    pub fn override_feature_in(mut self, path: impl AsRef<str>, feature: FeatureOverride) -> Self {
1026        let raw = path.as_ref();
1027        let normalized = normalize_override_path(raw);
1028        if normalized.is_empty() {
1029            // Neutral wording: this also fires for the `open_enums_in` sugar,
1030            // so the message must not name a method the caller didn't invoke.
1031            println!(
1032                "cargo:warning=buffa: feature override path '{raw}' normalizes to empty and will be ignored"
1033            );
1034            return self;
1035        }
1036        self.codegen_config
1037            .feature_overrides
1038            .push((normalized, feature));
1039        self
1040    }
1041
1042    /// Treat selected closed enums (or closed enum fields) as open in the
1043    /// generated representation — shorthand for
1044    /// [`override_feature_in(path, FeatureOverride::EnumType(EnumTypeOverride::Open))`](Self::override_feature_in)
1045    /// applied to each path.
1046    ///
1047    /// Matching closed enum fields generate as `EnumValue<E>` instead of `E`,
1048    /// so unknown wire values are directly visible as `EnumValue::Unknown(n)`.
1049    /// This is an opt-in migration / interop mode: it deliberately changes
1050    /// closed-enum presence behavior for matching fields, making an unknown
1051    /// value read as present instead of unset with the raw value represented
1052    /// through unknown fields. An enum-type rule opens the enum itself, so
1053    /// every field referencing it is affected; a field rule opens just that
1054    /// field, leaving the enum's own declared openness unchanged. Both are
1055    /// honored by buffa's descriptor-driven codecs, which resolve openness
1056    /// per field. Prefer enum-type rules when the descriptor set leaves the
1057    /// process: a field-level `enum_type` is not a spec-valid editions
1058    /// feature, so other runtimes reading the exported set ignore it. That
1059    /// preference does not help for an enum reached through `extern_path` —
1060    /// its descriptor is not in the compiled set to mutate, so even an
1061    /// enum-type rule is carried as a field-level override. Path grammar,
1062    /// accumulation, and inert-rule warnings are as described on
1063    /// [`override_feature_in`](Self::override_feature_in).
1064    #[must_use]
1065    pub fn open_enums_in(mut self, paths: &[impl AsRef<str>]) -> Self {
1066        for path in paths {
1067            self = self.override_feature_in(
1068                path.as_ref(),
1069                FeatureOverride::EnumType(EnumTypeOverride::Open),
1070            );
1071        }
1072        self
1073    }
1074
1075    /// Honor `features.utf8_validation = NONE` by emitting `Vec<u8>` / `&[u8]`
1076    /// for such string fields instead of `String` / `&str` (default: false).
1077    ///
1078    /// When disabled (the default), all string fields map to `String` and
1079    /// UTF-8 is validated on decode — stricter than proto2 requires, but
1080    /// ergonomic and safe.
1081    ///
1082    /// When enabled, string fields with `utf8_validation = NONE` become
1083    /// `Vec<u8>` / `&[u8]`. Decode skips validation; the caller chooses
1084    /// whether to `std::str::from_utf8` (checked) or `from_utf8_unchecked`
1085    /// (trusted-input fast path). This is the only sound Rust mapping when
1086    /// strings may actually contain non-UTF-8 bytes.
1087    ///
1088    /// **Note for proto2 users**: proto2's default is `utf8_validation = NONE`,
1089    /// so enabling this turns ALL proto2 string fields into `Vec<u8>`. Use
1090    /// only for new code or when profiling identifies UTF-8 validation as a
1091    /// bottleneck (it can be 10%+ of decode CPU for string-heavy messages).
1092    ///
1093    /// **JSON note**: fields normalized to bytes serialize as base64 in JSON
1094    /// (the proto3 JSON encoding for `bytes`). Keep strict mapping disabled
1095    /// for fields that need JSON string interop with other implementations.
1096    ///
1097    /// **Interaction with [`use_bytes_type`]**: when both are enabled,
1098    /// `map<bytes, bytes>` values stay `Vec<u8>` (the bytes-keyed JSON helper
1099    /// is concrete `HashMap<Vec<u8>, Vec<u8>>`). All other `bytes` shapes —
1100    /// singular / optional / repeated / oneof / `map<non-bytes, bytes>` —
1101    /// still become `bytes::Bytes`. The asymmetry is documented; if you hit
1102    /// it, see issue #76.
1103    ///
1104    /// [`use_bytes_type`]: Self::use_bytes_type
1105    #[must_use]
1106    pub fn strict_utf8_mapping(mut self, enabled: bool) -> Self {
1107        self.codegen_config.strict_utf8_mapping = enabled;
1108        self
1109    }
1110
1111    /// Permit `option message_set_wire_format = true` on input messages.
1112    ///
1113    /// MessageSet is a legacy Google-internal wire format. Default: `false`
1114    /// (such messages produce a codegen error). Set to `true` only when
1115    /// compiling protos that interoperate with old Google-internal services.
1116    #[must_use]
1117    pub fn allow_message_set(mut self, enabled: bool) -> Self {
1118        self.codegen_config.allow_message_set = enabled;
1119        self
1120    }
1121
1122    /// Declare an external type path mapping.
1123    ///
1124    /// The matched types reference the specified Rust path instead of being
1125    /// generated. This allows shared proto packages to be compiled once in a
1126    /// dedicated crate and referenced from others.
1127    ///
1128    /// `proto_path` is a fully-qualified protobuf path — either a **package**
1129    /// (`".my.common"`, mapping every type under it to a Rust module root) or a
1130    /// single **type FQN** (`".google.protobuf.Timestamp"`, mapping just that
1131    /// type, the prost/tonic idiom). The leading dot is optional and is added
1132    /// automatically. As in prost, the most specific entry wins: an exact type
1133    /// FQN beats a covering package prefix, which in turn beats a shorter
1134    /// prefix.
1135    ///
1136    /// `rust_path` is where the type(s) are accessible — a module root for a
1137    /// package mapping (e.g. `"::common_protos"`) or a full type path for a
1138    /// per-type mapping (e.g. `"::pbjson_types::Timestamp"`). It must be an
1139    /// absolute path (starting with `::` or `crate::`); any other value is
1140    /// emitted into the generated code verbatim and will fail to resolve there.
1141    ///
1142    /// **Nested types** inherit an enclosing message's per-type override:
1143    /// mapping `.my.pkg.Outer` to `::ext::Outer` resolves `.my.pkg.Outer.Inner`
1144    /// to `::ext::outer::Inner` — the override's parent module plus buffa's
1145    /// usual `snake_case(MessageName)` nested-types module (snake case of the
1146    /// *proto* message name, regardless of the override's final segment). This
1147    /// matches the layout of another buffa-generated crate; for a target crate
1148    /// laid out differently, add explicit per-type entries for the nested types
1149    /// as well.
1150    ///
1151    /// # Limitations
1152    ///
1153    /// An extern type that is referenced by a generated **view** must map to
1154    /// another buffa-generated crate — the view path is composed as
1155    /// `<rust_path_root>::__buffa::view::…`, which a non-buffa crate (e.g.
1156    /// `pbjson_types`) does not provide. Map per-type to a buffa crate, or
1157    /// disable views ([`generate_views(false)`](Self::generate_views)), for
1158    /// such types.
1159    ///
1160    /// When JSON generation is enabled, an external message routed through a
1161    /// ProtoJSON container helper must implement
1162    /// `buffa::json_helpers::ProtoElemJson` so generated containers can apply
1163    /// ProtoJSON encoding and reject null elements/values. This includes
1164    /// external wrapper types in repeated/map fields and external message
1165    /// values in bytes-keyed maps; ordinary message containers use serde
1166    /// directly.
1167    ///
1168    /// `proto_path` is `.` or a dotted protobuf package or type name. The
1169    /// leading dot is optional and one trailing dot is ignored;
1170    /// [`compile`](Self::compile) returns an error for a name with an empty
1171    /// segment (`my..common`) or a segment that is not a protobuf identifier.
1172    ///
1173    /// Other misconfigurations (a typo'd FQN target, a non-absolute
1174    /// `rust_path`, or a view-referenced type mapped to a non-buffa crate)
1175    /// are not diagnosed at generation time; they surface as an
1176    /// unresolved-path error when the generated code is compiled.
1177    ///
1178    /// # Example
1179    ///
1180    /// ```rust,ignore
1181    /// buffa_build::Config::new()
1182    ///     // Whole-package mapping.
1183    ///     .extern_path(".my.common", "::common_protos")
1184    ///     // Per-type mapping (issue #111) — overrides the package prefix for
1185    ///     // just this type.
1186    ///     .extern_path(".google.protobuf.Timestamp", "::common_protos::well_known::Timestamp")
1187    ///     .files(&["proto/my_service.proto"])
1188    ///     .includes(&["proto/"])
1189    ///     .compile()
1190    ///     .unwrap();
1191    /// ```
1192    #[must_use]
1193    pub fn extern_path(
1194        mut self,
1195        proto_path: impl Into<String>,
1196        rust_path: impl Into<String>,
1197    ) -> Self {
1198        // Stored as given: `compile` validates the name and normalizes it to
1199        // the fully-qualified form (".my.package" for "my.package"), so its
1200        // error can quote what the caller wrote.
1201        self.codegen_config
1202            .extern_paths
1203            .push((proto_path.into(), rust_path.into()));
1204        self
1205    }
1206
1207    /// Exclude a proto package from code generation.
1208    ///
1209    /// `package` is the proto package to exclude (e.g. `"buf.validate"`,
1210    /// `".gnostic.openapi.v3"`). A leading dot is optional and stripped
1211    /// automatically. The package and all of its sub-packages are excluded:
1212    /// `"buf.validate"` drops both `buf.validate` and `buf.validate.priv`.
1213    ///
1214    /// Use this when proto files from option-only packages (e.g.
1215    /// `buf/validate/validate.proto`, gnostic annotations) end up in the
1216    /// generate set through directory globbing, but you do not want Rust types
1217    /// generated for those packages. Their descriptors remain available for
1218    /// cross-package type resolution; only code generation is skipped.
1219    ///
1220    /// **Warning**: if any kept file references an excluded package as a field
1221    /// type, the generated code will contain dangling `super::…::Type` paths
1222    /// that fail to compile; the build emits a `cargo:warning` naming the
1223    /// file, message, and field before that happens. Pair `exclude_package` with
1224    /// [`extern_path`](Self::extern_path) to map the excluded types to an
1225    /// external crate, or do not list those `.proto` files in
1226    /// [`files`](Self::files).
1227    ///
1228    /// This method can be called multiple times to exclude multiple packages.
1229    ///
1230    /// # Validation
1231    ///
1232    /// [`compile`](Self::compile) returns an error, before running `protoc`, if
1233    /// `package` is empty or contains invalid components (empty segments,
1234    /// consecutive dots). A single leading dot is allowed and stripped.
1235    ///
1236    /// # Example
1237    ///
1238    /// ```rust,ignore
1239    /// buffa_build::Config::new()
1240    ///     .exclude_package("buf.validate")
1241    ///     .exclude_package(".gnostic.openapi.v3")
1242    ///     .files(&["proto/my_service.proto"])
1243    ///     .includes(&["proto/", "vendor/"])
1244    ///     .compile()
1245    ///     .unwrap();
1246    /// ```
1247    #[must_use]
1248    pub fn exclude_package(mut self, package: impl Into<String>) -> Self {
1249        // Stored raw. `compile()` rejects malformed entries up front, and
1250        // `generate_with_diagnostics` strips the optional leading dot.
1251        self.codegen_config.exclude_packages.push(package.into());
1252        self
1253    }
1254
1255    /// Configure `bytes` fields to use `bytes::Bytes` instead of `Vec<u8>`.
1256    ///
1257    /// Each path is a fully-qualified proto path prefix. Use `"."` to apply
1258    /// to all bytes fields, or specify individual field paths like
1259    /// `".my.pkg.MyMessage.data"`. Path normalization and the warning for a
1260    /// rule that matches nothing are as described on
1261    /// [`bytes_type_in`](Self::bytes_type_in).
1262    ///
1263    /// Applies uniformly to singular, optional, repeated, oneof, **and
1264    /// `map<K, bytes>`** values — the map case lets `view → owned`
1265    /// conversion participate in the `to_owned_from_source` zero-copy
1266    /// `slice_ref` path. One carve-out: an effective `map<bytes, bytes>` keeps
1267    /// `Vec<u8>` values (the JSON helper for that combination is concrete
1268    /// `HashMap<Vec<u8>, Vec<u8>>`); every other shape becomes `Bytes`. A
1269    /// `bytes` map key is only reachable when [`strict_utf8_mapping`] is enabled
1270    /// *and* the `map<string, bytes>` field carries
1271    /// `[features.utf8_validation = NONE]` on its key, which normalizes the
1272    /// string key to `bytes` — `strict_utf8_mapping` alone does not trigger it.
1273    ///
1274    /// A **custom** `bytes` representation
1275    /// ([`bytes_type_custom`](Self::bytes_type_custom)) is honored for
1276    /// `map<K, bytes>` values too, the same as the built-in `Bytes` — but a
1277    /// custom map value (like a custom `repeated` element) must be a crate-local
1278    /// type, since codegen emits its `ReflectElement` / `InspectElement` /
1279    /// `ProtoElemJson` impls (the orphan rule forbids them for a foreign type).
1280    /// A type listed with [`json_policy_type`](Self::json_policy_type) gets no
1281    /// `ProtoElemJson` impl, so only vtable reflection or reflection with
1282    /// message cleanup requires it to be local.
1283    ///
1284    /// [`strict_utf8_mapping`]: Self::strict_utf8_mapping
1285    ///
1286    /// # Example
1287    ///
1288    /// ```rust,ignore
1289    /// buffa_build::Config::new()
1290    ///     .use_bytes_type_in(&["."])  // all bytes fields use Bytes
1291    ///     .files(&["proto/my_service.proto"])
1292    ///     .includes(&["proto/"])
1293    ///     .compile()
1294    ///     .unwrap();
1295    /// ```
1296    #[must_use]
1297    pub fn use_bytes_type_in(self, paths: &[impl AsRef<str>]) -> Self {
1298        self.bytes_type_in(BytesRepr::Bytes, paths)
1299    }
1300
1301    /// Use `bytes::Bytes` for all `bytes` fields in all messages.
1302    ///
1303    /// This is a convenience for `.use_bytes_type_in(&["."])`. Use
1304    /// [`use_bytes_type_in`] with specific proto paths if you only want `Bytes`
1305    /// for certain fields. See that method for the path-matching semantics, the
1306    /// `map<K, bytes>` rule, and the `map<bytes, bytes>` carve-out under
1307    /// [`strict_utf8_mapping`].
1308    ///
1309    /// [`use_bytes_type_in`]: Self::use_bytes_type_in
1310    /// [`strict_utf8_mapping`]: Self::strict_utf8_mapping
1311    #[must_use]
1312    pub fn use_bytes_type(self) -> Self {
1313        self.bytes_type(BytesRepr::Bytes)
1314    }
1315
1316    /// Map `bytes` fields to a [`BytesRepr`] other than `Vec<u8>` for the given
1317    /// proto path prefixes. The bytes counterpart to
1318    /// [`string_type_in`](Self::string_type_in).
1319    ///
1320    /// Each path is a fully-qualified proto path prefix: a field
1321    /// (`".my.pkg.Msg.data"`), a message, a package, or `"."` for every field.
1322    /// A leading dot is added to each path if missing, surrounding whitespace
1323    /// and trailing dots are ignored, and a blank entry is skipped with a
1324    /// `cargo:warning`.
1325    ///
1326    /// A rule whose path does not match a field of any type in a generated
1327    /// message produces a `cargo:warning`
1328    /// ([`CodeGenWarning::FieldTypeRuleMatchedNothing`](buffa_codegen::CodeGenWarning::FieldTypeRuleMatchedNothing)).
1329    /// A path that matches only fields of another type does not warn.
1330    ///
1331    /// Rules accumulate and the **last** matching rule wins, so call the broad
1332    /// [`bytes_type`](Self::bytes_type) *first*, then `bytes_type_in` for
1333    /// narrower overrides. For [`BytesRepr::Custom`], the downstream crate must
1334    /// depend on the crate providing the type (buffa does not re-export it).
1335    /// Only the owned Rust type changes — the wire format is unchanged and view
1336    /// types still borrow `&[u8]`.
1337    #[must_use]
1338    pub fn bytes_type_in(mut self, repr: BytesRepr, paths: &[impl AsRef<str>]) -> Self {
1339        self.codegen_config.bytes_fields.extend(
1340            field_rule_paths("bytes_type_in", paths)
1341                .into_iter()
1342                .map(|path| (path, repr.clone())),
1343        );
1344        self
1345    }
1346
1347    /// Map every `bytes` field in all messages to the given [`BytesRepr`].
1348    /// Convenience for `.bytes_type_in(repr, &["."])`; call before any
1349    /// [`bytes_type_in`](Self::bytes_type_in) overrides (last matching rule
1350    /// wins).
1351    #[must_use]
1352    pub fn bytes_type(mut self, repr: BytesRepr) -> Self {
1353        self.codegen_config
1354            .bytes_fields
1355            .push((".".to_string(), repr));
1356        self
1357    }
1358
1359    /// Map the matching `bytes` fields to a custom type named by its
1360    /// fully-qualified Rust path (e.g. `"::my_crate::MyBytes"`). The type must
1361    /// satisfy `buffa::ProtoBytes`, and the downstream crate must depend on the
1362    /// crate providing it. Shorthand for
1363    /// [`bytes_type_in`](Self::bytes_type_in)`(BytesRepr::Custom(path), paths)`.
1364    ///
1365    /// # Limitations
1366    ///
1367    /// - A **foreign** custom type used as a `repeated` element — or a
1368    ///   `map<K, bytes>` value — fails to compile under JSON, vtable reflection
1369    ///   or reflection with message cleanup: codegen emits `ProtoElemJson` /
1370    ///   `ReflectElement` / `InspectElement` impls for it, which the orphan
1371    ///   rule forbids for a foreign type. Wrap it in a crate-local newtype, or use
1372    ///   [`emit_custom_type_impls(false)`](Self::emit_custom_type_impls) when
1373    ///   the defining crate supplies those integrations. Singular / optional /
1374    ///   oneof uses work directly. A type listed with
1375    ///   [`json_policy_type`](Self::json_policy_type) gets no `ProtoElemJson`
1376    ///   impl, so only vtable reflection or reflection with message cleanup
1377    ///   requires it to be local.
1378    /// - A `Custom` rule **does** apply to `map<K, bytes>` values (honored like
1379    ///   the built-in [`BytesRepr::Bytes`]); only the `map<bytes, bytes>`
1380    ///   carve-out keeps `Vec<u8>` values.
1381    /// - A `path` that is not a Rust type path like `crate::Name` (for
1382    ///   example `_`, `()` or `&'static [u8]`) is reported as a codegen error
1383    ///   from [`compile`](Self::compile). Associated-type projections and
1384    ///   parenthesized type paths are supported.
1385    /// - A custom bytes type needs no native `arbitrary::Arbitrary` impl (a
1386    ///   generic builder handles it under `generate_arbitrary`).
1387    #[must_use]
1388    pub fn bytes_type_custom_in(self, path: &str, paths: &[impl AsRef<str>]) -> Self {
1389        self.bytes_type_in(BytesRepr::Custom(path.to_string()), paths)
1390    }
1391
1392    /// Map every `bytes` field to the given custom type path. Convenience for
1393    /// `.bytes_type_custom_in(path, &["."])`; see it for the limitations
1394    /// (foreign `repeated` elements, `map` values, path parsing).
1395    #[must_use]
1396    pub fn bytes_type_custom(self, path: &str) -> Self {
1397        self.bytes_type(BytesRepr::Custom(path.to_string()))
1398    }
1399
1400    /// Store the matching message-typed oneof variants inline instead of
1401    /// wrapping them in `Box<T>`.
1402    ///
1403    /// By default every message/group oneof variant is boxed so that recursive
1404    /// types compile. For non-recursive variants the `Box` is pure overhead (an
1405    /// allocation per construction); this opts the matching variants out.
1406    /// This affects the owned message enum only — view oneof variants remain
1407    /// boxed.
1408    ///
1409    /// Each path is a fully-qualified proto variant path prefix, e.g.
1410    /// `".my.pkg.MyMessage.body.small"` for one variant or `".my.pkg"` for a
1411    /// package (same matching as [`use_bytes_type_in`](Self::use_bytes_type_in)).
1412    /// Paths are normalized as for [`bytes_type_in`](Self::bytes_type_in). A
1413    /// rule that matches no variant is not reported.
1414    ///
1415    /// Recursive variants cannot be stored inline (the type would be
1416    /// unsized). A rule that names a recursive variant *exactly* is rejected
1417    /// at codegen time; a broader prefix rule silently keeps recursive
1418    /// variants boxed and inlines the rest. For example, with
1419    /// `unbox_oneof_in(&[".my.pkg.Node"])`, a self-referential
1420    /// `Node.kind.child` variant stays boxed while `Node`'s other message
1421    /// variants become inline.
1422    #[must_use]
1423    pub fn unbox_oneof_in(mut self, paths: &[impl AsRef<str>]) -> Self {
1424        self.codegen_config
1425            .unboxed_oneof_fields
1426            // The exact-path recursion error compares against the normalized
1427            // form.
1428            .extend(field_rule_paths("unbox_oneof_in", paths));
1429        self
1430    }
1431
1432    /// Store every non-recursive message-typed oneof variant inline instead of
1433    /// boxing it. Convenience for `.unbox_oneof_in(&["."])`; recursive
1434    /// variants stay boxed.
1435    #[must_use]
1436    pub fn unbox_oneof(mut self) -> Self {
1437        self.codegen_config
1438            .unboxed_oneof_fields
1439            .push(".".to_string());
1440        self
1441    }
1442
1443    /// Map `string` fields to a [`StringRepr`] other than `String` for the
1444    /// given proto path prefixes. The string counterpart to
1445    /// [`use_bytes_type_in`](Self::use_bytes_type_in).
1446    ///
1447    /// Each path is a fully-qualified proto path prefix (e.g.
1448    /// `".my.pkg.MyMessage.name"` for one field, `".my.pkg"` for a package).
1449    ///
1450    /// Rules accumulate and the **last** matching rule wins. Order therefore
1451    /// matters: call [`string_type`](Self::string_type) (the broad default)
1452    /// *first*, then `string_type_in` for narrower overrides — a broad rule
1453    /// added after a specific one will shadow it.
1454    ///
1455    /// For [`StringRepr::Custom`], the type must implement `buffa::ProtoString`,
1456    /// and the downstream crate must depend on the crate providing it (buffa does
1457    /// not re-export it). A foreign type cannot implement `ProtoString` directly
1458    /// (orphan rule) — point at a local newtype, or the `buffa-smolstr` crate for
1459    /// `smol_str::SmolStr`.
1460    ///
1461    /// Only the owned Rust type changes: the wire format is unchanged and view
1462    /// types still borrow `&str`. A rule that matches a `map` field applies to
1463    /// its `string` key and its `string` value.
1464    ///
1465    /// Path normalization and the warning for a rule that matches nothing are
1466    /// as described on [`bytes_type_in`](Self::bytes_type_in).
1467    ///
1468    /// # Example
1469    ///
1470    /// ```rust,ignore
1471    /// buffa_build::Config::new()
1472    ///     .string_type_custom("::buffa_smolstr::SmolStr")  // broad default first
1473    ///     .string_type_custom_in("::my_crate::CompactStr", &[".my.pkg.Msg.body"]) // narrow override
1474    ///     .files(&["proto/my_service.proto"])
1475    ///     .includes(&["proto/"])
1476    ///     .compile()
1477    ///     .unwrap();
1478    /// ```
1479    #[must_use]
1480    pub fn string_type_in(mut self, repr: StringRepr, paths: &[impl AsRef<str>]) -> Self {
1481        self.codegen_config.string_fields.extend(
1482            field_rule_paths("string_type_in", paths)
1483                .into_iter()
1484                .map(|path| (path, repr.clone())),
1485        );
1486        self
1487    }
1488
1489    /// Map every `string` field in all messages to the given [`StringRepr`].
1490    ///
1491    /// Convenience for `.string_type_in(repr, &["."])`. Call this *before* any
1492    /// [`string_type_in`](Self::string_type_in) overrides, since the last
1493    /// matching rule wins (a `"."` rule added later shadows earlier specific
1494    /// rules). The rule also covers the `string` keys and values of `map`
1495    /// fields.
1496    #[must_use]
1497    pub fn string_type(mut self, repr: StringRepr) -> Self {
1498        self.codegen_config
1499            .string_fields
1500            .push((".".to_string(), repr));
1501        self
1502    }
1503
1504    /// Map the matching `string` fields to a custom type that implements
1505    /// `buffa::ProtoString`, named by its fully-qualified Rust path (e.g.
1506    /// `"::buffa_smolstr::SmolStr"`, or a local newtype — a foreign type cannot
1507    /// implement the trait directly). The downstream crate must depend on the
1508    /// crate providing it. Shorthand for
1509    /// [`string_type_in`](Self::string_type_in)`(StringRepr::Custom(path), paths)`.
1510    ///
1511    /// # Limitations
1512    ///
1513    /// - Under vtable reflection ([`reflect_mode`](Self::reflect_mode) with
1514    ///   `ReflectMode::VTable`), or any reflection with message cleanup, a
1515    ///   **foreign** custom type used as a `repeated` element or as a `map` key
1516    ///   or value fails to compile: codegen emits a `ReflectElement`,
1517    ///   `InspectElement` or `ReflectMapKey` impl for it, which the orphan rule
1518    ///   forbids for a foreign type. Wrap it in a crate-local newtype, or use
1519    ///   [`emit_custom_type_impls(false)`](Self::emit_custom_type_impls) when
1520    ///   the defining crate supplies those integrations. Singular / optional /
1521    ///   oneof uses work directly.
1522    /// - **JSON of a custom string with explicit presence (proto3 or proto2
1523    ///   `optional`, and the edition 2023 default), in a `repeated` field, in
1524    ///   a oneof, or in a `map`,** serializes through the type's own `serde`
1525    ///   impls, so such a type must implement `Serialize` / `Deserialize`. A
1526    ///   `buffa-remote-derive` newtype gets them from
1527    ///   `#[buffa(remote = ..., serde)]`; any other type derives them (an
1528    ///   external type enables its `serde` feature). A singular field with
1529    ///   implicit presence, or a proto2 `required` field, uses the
1530    ///   `proto_string` with-module and needs no `serde` impl, and so does a
1531    ///   type listed with [`json_policy_type`](Self::json_policy_type), whose
1532    ///   JSON goes through its policy in every generated JSON position.
1533    /// - A custom type used as a `map` key must implement `Hash + Eq` for the
1534    ///   default `HashMap` container, or `Ord` for `BTreeMap`.
1535    /// - A `path` that is not a Rust type path like `crate::Name` (for
1536    ///   example `_`, `()` or `&'static [u8]`) is reported as a codegen error
1537    ///   from [`compile`](Self::compile). Associated-type projections and
1538    ///   parenthesized type paths are supported.
1539    /// - A custom string type needs no native `arbitrary::Arbitrary` impl (a
1540    ///   generic builder handles it under `generate_arbitrary`, as a `map` key
1541    ///   or value too).
1542    #[must_use]
1543    pub fn string_type_custom_in(self, path: &str, paths: &[impl AsRef<str>]) -> Self {
1544        self.string_type_in(StringRepr::Custom(path.to_string()), paths)
1545    }
1546
1547    /// Route the protobuf JSON of a custom `bytes` or `string` representation
1548    /// through its `buffa::json_helpers::ProtoBytesJson` or `ProtoStringJson`
1549    /// impl.
1550    ///
1551    /// `path` names the type exactly as its
1552    /// [`bytes_type_custom_in`](Self::bytes_type_custom_in) or
1553    /// [`string_type_custom_in`](Self::string_type_custom_in) rule does
1554    /// (whitespace aside). Every field of that type then serializes and
1555    /// deserializes through the policy in the generated `serde` impls:
1556    /// singular, optional, repeated and oneof fields, `map` keys and values,
1557    /// and the matching fields of generated views, lazy views and owned views.
1558    /// The type's own `serde` impls are not consulted.
1559    /// Generated code implements no JSON trait for the type (repeated elements
1560    /// and `map` values go through buffa's policy with-modules). With JSON
1561    /// alone, the type may therefore be defined, together with its
1562    /// representation and policy impls, in another crate, and separate
1563    /// `compile()` runs into one crate may share it. With vtable reflection,
1564    /// or reflection with message cleanup, its `repeated` and `map` uses still
1565    /// get per-run element impls, so there it must be crate-local and
1566    /// generated in one run (or use
1567    /// [`emit_custom_type_impls(false)`](Self::emit_custom_type_impls)). Call
1568    /// it once per type, in every `Config` that generates a field of the type:
1569    /// a run that does not list it never calls the policy (bytes fields become
1570    /// plain base64; string fields use the type's own `serde` impls). Unlisted
1571    /// custom types keep their existing JSON behavior.
1572    ///
1573    /// A policy shapes only the generated JSON and is not a confidentiality
1574    /// boundary. Binary encoding, generated text format and descriptor-driven
1575    /// reflection never call it: JSON produced or read through `DynamicMessage`
1576    /// (including a message converted with `ReflectMessage::to_dynamic`, or with
1577    /// `DynamicMessage::try_from_message`, which works whether or not
1578    /// reflection is generated) encodes the field as standard base64 or a
1579    /// plain string, so a policy that refuses export does not stop it and its
1580    /// import checks do not run.
1581    ///
1582    /// # Limitations
1583    ///
1584    /// - The type must implement the policy trait; a missing impl is a
1585    ///   compile error in the generated code, naming the trait.
1586    /// - A listed `string` type used as the key of a `map` with enum values
1587    ///   is a codegen error from [`compile`](Self::compile).
1588    /// - A listed `string` type used as a `map` key must have a policy that
1589    ///   round-trips, and so is injective (see the `ProtoStringJson` contract):
1590    ///   otherwise import loses or alters entries. This is not checked.
1591    /// - A type that no effective representation rule selects is an error.
1592    ///   Binding and spelling errors remain errors with JSON disabled. A valid
1593    ///   listed type while [`generate_json`](Self::generate_json) is off
1594    ///   produces a `cargo:warning` because its policy is inactive.
1595    /// - With JSON and reflection both on
1596    ///   ([`generate_reflection`](Self::generate_reflection), or any
1597    ///   [`reflect_mode`](Self::reflect_mode) other than off), listing any type
1598    ///   produces one `cargo:warning` per `compile()` that reflective JSON
1599    ///   bypasses the policy. It is a standing reminder, not a check of your
1600    ///   schema, and buffa-build always prints it.
1601    #[must_use]
1602    pub fn json_policy_type(mut self, path: &str) -> Self {
1603        self.codegen_config
1604            .json_policy_types
1605            .push(path.trim().to_string());
1606        self
1607    }
1608
1609    /// Control emission of custom bytes/string element integration impls.
1610    ///
1611    /// Set this to `false` when shared representation types provide their
1612    /// `ProtoElemJson`, `ReflectElement`, `ReflectMapKey` and `InspectElement` implementations in
1613    /// their defining crate. A type listed with
1614    /// [`json_policy_type`](Self::json_policy_type) needs no `ProtoElemJson`.
1615    /// This permits foreign types and multiple generation calls without
1616    /// orphan-rule or duplicate-impl errors. Missing traits fail
1617    /// compilation; JSON policy selection is still required separately.
1618    #[must_use]
1619    pub fn emit_custom_type_impls(mut self, enabled: bool) -> Self {
1620        self.codegen_config.emit_custom_type_impls = enabled;
1621        self
1622    }
1623
1624    /// Permit global message selectors absent from a scoped generation request.
1625    /// Unmatched selectors still warn. Validate the complete project with this
1626    /// disabled to catch misspelled cleanup or view-export rules as errors.
1627    #[must_use]
1628    pub fn allow_unmatched_message_rules(mut self, enabled: bool) -> Self {
1629        self.codegen_config.allow_unmatched_message_rules = enabled;
1630        self
1631    }
1632
1633    /// Map every `string` field to the given custom type path. Convenience for
1634    /// `.string_type_custom_in(path, &["."])`; see it for the limitations.
1635    #[must_use]
1636    pub fn string_type_custom(self, path: &str) -> Self {
1637        self.string_type(StringRepr::Custom(path.to_string()))
1638    }
1639
1640    /// Map the matching `map` fields to a [`MapRepr`] other than the default
1641    /// `HashMap`. Rules are matched with proto-segment-aware prefix logic; the
1642    /// **last** matching rule wins, so add a broad rule first and narrower
1643    /// overrides after.
1644    ///
1645    /// Path normalization and the warning for a rule that matches nothing are
1646    /// as described on [`bytes_type_in`](Self::bytes_type_in).
1647    ///
1648    /// Use [`MapRepr::BTreeMap`] for the buffa-provided `BTreeMap` (deterministic
1649    /// key order, no extra dependency, no consumer code), or
1650    /// [`MapRepr::Custom`] for a crate-local newtype that implements
1651    /// `buffa::map_codec::MapStorage`.
1652    ///
1653    /// Only the owned collection changes: the wire format is unchanged and view
1654    /// types are unaffected.
1655    ///
1656    /// # Example
1657    ///
1658    /// ```rust,ignore
1659    /// buffa_build::Config::new()
1660    ///     .map_type(buffa_build::MapRepr::BTreeMap)                       // broad default
1661    ///     .map_type_in(buffa_build::MapRepr::HashMap, &[".my.pkg.Msg.cache"]) // narrow override
1662    ///     .compile()
1663    ///     .unwrap();
1664    /// ```
1665    #[must_use]
1666    pub fn map_type_in(mut self, repr: MapRepr, paths: &[impl AsRef<str>]) -> Self {
1667        self.codegen_config.map_fields.extend(
1668            field_rule_paths("map_type_in", paths)
1669                .into_iter()
1670                .map(|path| (path, repr.clone())),
1671        );
1672        self
1673    }
1674
1675    /// Map every `map` field in all messages to the given [`MapRepr`].
1676    /// Convenience for `.map_type_in(repr, &["."])`. Call this *before* any
1677    /// [`map_type_in`](Self::map_type_in) overrides, since the last matching
1678    /// rule wins.
1679    #[must_use]
1680    pub fn map_type(mut self, repr: MapRepr) -> Self {
1681        self.codegen_config.map_fields.push((".".to_string(), repr));
1682        self
1683    }
1684
1685    /// Encode map entries as prost does: leave an entry's key or value out
1686    /// when it holds the default (default: false, both are always written, as
1687    /// the C++ and Java runtimes write them). Entries themselves are never
1688    /// dropped.
1689    ///
1690    /// For migrations from prost where stored or hashed map encodings must
1691    /// not change. Decoding is unchanged: buffa, like every protobuf runtime,
1692    /// reads both forms to the same map. One value does not survive the round
1693    /// trip: a `-0.0` float value is left out, as prost leaves it out, and
1694    /// decodes as `0.0`.
1695    ///
1696    /// The default is what a missing field decodes to: zero, `false`, empty,
1697    /// an open enum's 0 or a closed enum's first value. A message value is
1698    /// left out when it encodes to nothing.
1699    ///
1700    /// # Differences from prost
1701    ///
1702    /// - prost leaves out a message value equal to its default. A value that
1703    ///   equals its default and still encodes a field, such as one with a
1704    ///   `required` field at its default or a float field holding `-0.0`, is
1705    ///   written here and not by prost.
1706    /// - A value of an enum made open with
1707    ///   [`open_enums_in`](Self::open_enums_in) is left out at 0, which a
1708    ///   missing open enum decodes to, where prost leaves out the enum's
1709    ///   first value. The two differ only for an enum whose first value is
1710    ///   not 0. protoc rejects that as a map value, so the case can occur
1711    ///   only with a descriptor set that another tool built
1712    ///   ([`use_buf`](Self::use_buf), [`descriptor_set`](Self::descriptor_set)).
1713    /// - The option covers the entries' bytes only. For a map with more than
1714    ///   one entry to encode identically, the entries must also come in the
1715    ///   same order: use [`map_type`](Self::map_type) with
1716    ///   [`MapRepr::BTreeMap`] where prost used `btree_map`.
1717    ///
1718    /// # Scope
1719    ///
1720    /// - The option applies to the owned, view and lazy view encoders of the
1721    ///   messages generated in this run. Each crate's types encode as that
1722    ///   crate was generated.
1723    /// - `google.protobuf.Struct`, the well-known type with a map field,
1724    ///   comes from `buffa-types` and writes both fields, and so does
1725    ///   `DynamicMessage`.
1726    /// - A lazy view keeps its singular and repeated message fields undecoded
1727    ///   and writes them as they were read, so map entries inside them keep
1728    ///   the encoding they arrived with. Every encoder writes entries kept as
1729    ///   unknown fields as they were read.
1730    /// - With [`CodecStrategy::Table`], messages with a map field keep the
1731    ///   unrolled codec, and a
1732    ///   [`codec_strategy_in`](Self::codec_strategy_in) rule that selects the
1733    ///   table for such a message by its exact path is an error.
1734    #[must_use]
1735    pub fn map_entries_omit_defaults(mut self, enabled: bool) -> Self {
1736        self.codegen_config.map_entries_omit_defaults = enabled;
1737        self
1738    }
1739
1740    /// Map the matching `map` fields to a custom collection implementing
1741    /// `buffa::map_codec::MapStorage`, named by its fully-qualified Rust path
1742    /// (e.g. `"::my_crate::OrderedMap"`). The path must **not** include the
1743    /// `<K, V>` parameters — they are applied positionally. Shorthand for
1744    /// [`map_type_in`](Self::map_type_in)`(MapRepr::Custom(path), paths)`.
1745    ///
1746    /// # Limitations
1747    ///
1748    /// - The path must name a **crate-local newtype** — a foreign map cannot
1749    ///   implement the buffa-owned reflection / serde traits (orphan rule).
1750    ///   Prefer the built-in [`MapRepr::BTreeMap`] unless you need a specific
1751    ///   foreign map.
1752    /// - The newtype must implement `buffa::MapStorage` plus the derive /
1753    ///   `FromIterator` / `ReflectMap` / serde / `arbitrary` bounds documented on
1754    ///   `buffa::map_codec::MapStorage` (the canonical list). JSON and
1755    ///   `arbitrary` work for every proto map key/value type regardless of the
1756    ///   container.
1757    /// - A path that does not parse as a Rust type is reported as a codegen
1758    ///   error from [`compile`](Self::compile).
1759    #[must_use]
1760    pub fn map_type_custom_in(self, path: &str, paths: &[impl AsRef<str>]) -> Self {
1761        self.map_type_in(MapRepr::Custom(path.to_string()), paths)
1762    }
1763
1764    /// Map every `map` field to the given custom collection path. Convenience
1765    /// for `.map_type_custom_in(path, &["."])`; see it for the limitations (the
1766    /// crate-local newtype requirement, the trait bounds, path parsing).
1767    #[must_use]
1768    pub fn map_type_custom(self, path: &str) -> Self {
1769        self.map_type(MapRepr::Custom(path.to_string()))
1770    }
1771
1772    /// Map the matching message fields to a [`PointerRepr`] other than the
1773    /// default `Inline`. Rules are matched with proto-segment-aware prefix
1774    /// logic; the **last** matching rule wins, so add a broad rule first and
1775    /// narrower overrides after.
1776    ///
1777    /// Paths are normalized as for [`bytes_type_in`](Self::bytes_type_in). A
1778    /// rule that matches no field is not reported.
1779    ///
1780    /// The default `Inline` is recursion-aware (recursive fields stay on
1781    /// `Box`), so this knob is for opting *out*: `PointerRepr::Box` for large
1782    /// or rarely-set submessages where reserving `size_of::<T>()` in the parent
1783    /// is wasteful, or `PointerRepr::Custom` for a third-party pointer.
1784    ///
1785    /// Applies to singular (and proto2 optional/required) message fields and to
1786    /// **boxed** oneof message/group variants (matched by the variant's path).
1787    /// A oneof variant opted into inline storage via [`unbox_oneof_in`](Self::unbox_oneof_in)
1788    /// takes precedence and gets no pointer; recursive variants stay boxed and so
1789    /// accept a custom pointer. Repeated message fields use a collection, not a
1790    /// pointer. For [`PointerRepr::Custom`], the pointer must implement
1791    /// `buffa::ProtoBox<T>` and be a crate-local newtype; the path is a
1792    /// **template** with a `*` placeholder for the message type (e.g.
1793    /// `"::my_crate::SmallBox<*>"`).
1794    ///
1795    /// Only the in-memory pointer changes: the wire format is unchanged and view
1796    /// types are unaffected.
1797    #[must_use]
1798    pub fn box_type_in(mut self, repr: PointerRepr, paths: &[impl AsRef<str>]) -> Self {
1799        self.codegen_config
1800            .pointer_fields
1801            // The exact-path Inline recursion error compares against the
1802            // normalized form.
1803            .extend(
1804                field_rule_paths("box_type_in", paths)
1805                    .into_iter()
1806                    .map(|path| (path, repr.clone())),
1807            );
1808        self
1809    }
1810
1811    /// Choose how the binary `Message` implementation of every message is
1812    /// generated (default: [`CodecStrategy::Unrolled`]).
1813    ///
1814    /// On a large schema, [`CodecStrategy::Table`] makes the compiled code
1815    /// about 40% smaller at `opt-level = "z"`, and it slows messages made of
1816    /// many small fields; a message that cannot use it keeps its size.
1817    /// [`CodecStrategy::Table`] says which messages stay unrolled and how a
1818    /// table message behaves differently, and this build reports the messages
1819    /// that stay unrolled in one `cargo:warning`. The option never changes the
1820    /// wire format. The generated code needs Rust 1.77 or later, and `compile`
1821    /// returns an error on an older compiler when a build script runs it (the
1822    /// compiler is read from `RUSTC`).
1823    ///
1824    /// Path-scoped rules for individual messages go in
1825    /// [`codec_strategy_in`](Self::codec_strategy_in), and take precedence
1826    /// over this setting whatever the call order.
1827    ///
1828    /// ```rust,ignore
1829    /// // build.rs
1830    /// buffa_build::Config::new()
1831    ///     .files(&["proto/wa.proto"])
1832    ///     .includes(&["proto/"])
1833    ///     .codec_strategy(buffa_build::CodecStrategy::Table)
1834    ///     .codec_strategy_in(buffa_build::CodecStrategy::Unrolled, &[".wa.Message"])
1835    ///     .compile()?;
1836    /// ```
1837    #[must_use]
1838    pub fn codec_strategy(mut self, strategy: CodecStrategy) -> Self {
1839        self.codegen_config.codec_strategy = strategy;
1840        self
1841    }
1842
1843    /// Choose the [`CodecStrategy`] of the matching messages, on top of the
1844    /// global [`codec_strategy`](Self::codec_strategy).
1845    ///
1846    /// Each path is a fully-qualified proto path prefix, e.g. `".wa.Message"`
1847    /// for one message or `".wa"` for a package (same matching as
1848    /// [`preserve_unknown_fields_in`](Self::preserve_unknown_fields_in));
1849    /// `"."` matches every message. A leading dot is added if missing,
1850    /// trailing dots are trimmed, and a path that is empty after that prints a
1851    /// `cargo:warning` and is ignored. A rule covers the message it names
1852    /// **and every message nested inside it**. The **last** matching rule wins,
1853    /// so call this after any broader rule.
1854    ///
1855    /// A message selected for the table by a rule that cannot use it stays
1856    /// unrolled and is counted in the warning, and it is an error if the rule
1857    /// names the message by its exact path. A rule that matches no message
1858    /// produces a warning.
1859    ///
1860    /// A rule does not extend to the messages a message holds; see
1861    /// [`CodecStrategy::Table`].
1862    #[must_use]
1863    pub fn codec_strategy_in(mut self, strategy: CodecStrategy, paths: &[impl AsRef<str>]) -> Self {
1864        for raw in paths.iter().map(AsRef::as_ref) {
1865            let normalized = normalize_override_path(raw);
1866            if normalized.is_empty() {
1867                println!(
1868                    "cargo:warning=buffa: codec_strategy_in path '{raw}' \
1869                     normalizes to empty and will be ignored"
1870                );
1871                continue;
1872            }
1873            self.codegen_config
1874                .codec_strategy_in
1875                .push((normalized, strategy));
1876        }
1877        self
1878    }
1879
1880    /// Map every message field (and boxed oneof variant) to the given [`PointerRepr`].
1881    /// Convenience for `.box_type_in(repr, &["."])`. Call before any
1882    /// [`box_type_in`](Self::box_type_in) overrides, since the last matching
1883    /// rule wins. `box_type(PointerRepr::Box)` restores the pre-0.9 boxed
1884    /// default for every singular message field.
1885    #[must_use]
1886    pub fn box_type(mut self, repr: PointerRepr) -> Self {
1887        self.codegen_config
1888            .pointer_fields
1889            .push((".".to_string(), repr));
1890        self
1891    }
1892
1893    /// Map the matching singular message fields to a custom pointer implementing
1894    /// `buffa::ProtoBox<T>`, named by a Rust type-path **template** with a `*`
1895    /// placeholder for the message type (e.g. `"::my_crate::SmallBox<*>"`).
1896    /// Shorthand for
1897    /// [`box_type_in`](Self::box_type_in)`(PointerRepr::Custom(template), paths)`.
1898    ///
1899    /// # Limitations
1900    ///
1901    /// - The template must contain at least one `*`; a template that omits it,
1902    ///   or whose substitution does not parse as a Rust type, is reported as a
1903    ///   codegen error from [`compile`](Self::compile).
1904    /// - The pointer must be exclusively owned (`Rc`/`Arc` are unusable — the
1905    ///   decoder needs `DerefMut`) and a crate-local newtype (a foreign pointer
1906    ///   cannot implement the buffa-owned `ProtoBox`).
1907    #[must_use]
1908    pub fn box_type_custom_in(self, template: &str, paths: &[impl AsRef<str>]) -> Self {
1909        self.box_type_in(PointerRepr::Custom(template.to_string()), paths)
1910    }
1911
1912    /// Map every message field (and boxed oneof variant) to the given custom pointer template.
1913    /// Convenience for `.box_type_custom_in(template, &["."])`; see it for the
1914    /// limitations (the `*` placeholder, `Rc`/`Arc` exclusion, newtype rule).
1915    #[must_use]
1916    pub fn box_type_custom(self, template: &str) -> Self {
1917        self.box_type(PointerRepr::Custom(template.to_string()))
1918    }
1919
1920    /// Map the matching `repeated` fields to a [`RepeatedRepr`] other than the
1921    /// default `Vec<T>`. Rules are matched with proto-segment-aware prefix
1922    /// logic; the **last** matching rule wins, so add a broad rule first and
1923    /// narrower overrides after. Applies only to `repeated` fields (not `map`).
1924    ///
1925    /// Path normalization and the warning for a rule that matches nothing are
1926    /// as described on [`bytes_type_in`](Self::bytes_type_in).
1927    ///
1928    /// For [`RepeatedRepr::Custom`], the collection must implement
1929    /// `buffa::ProtoList<T>`. Unlike the scalar `string_type_custom` /
1930    /// `bytes_type_custom` knobs (which take a *complete* type path), this path
1931    /// is a **template** with a `*` placeholder for the element type. Existing
1932    /// `ProtoList` implementations work through aliases and associated types.
1933    /// If the defining crate provides no implementation, use a crate-local
1934    /// newtype to satisfy the orphan rule. See [`RepeatedRepr::Custom`] for
1935    /// the bounds required by JSON, reflection and arbitrary generation.
1936    ///
1937    /// Only the owned collection changes: the wire format is unchanged and view
1938    /// types still borrow `&[T]`.
1939    ///
1940    /// # Example
1941    ///
1942    /// ```rust,ignore
1943    /// // `SmallList<T>` is a crate-local newtype over smallvec::SmallVec that
1944    /// // implements buffa::ProtoList (see the ProtoList docs for the template).
1945    /// buffa_build::Config::new()
1946    ///     .repeated_type_custom("::my_crate::SmallList<*>")               // broad default
1947    ///     .repeated_type_custom_in("::my_crate::SmallList8<*>", &[".my.pkg.Msg.tags"])
1948    ///     .compile()
1949    ///     .unwrap();
1950    /// ```
1951    #[must_use]
1952    pub fn repeated_type_in(mut self, repr: RepeatedRepr, paths: &[impl AsRef<str>]) -> Self {
1953        self.codegen_config.repeated_fields.extend(
1954            field_rule_paths("repeated_type_in", paths)
1955                .into_iter()
1956                .map(|path| (path, repr.clone())),
1957        );
1958        self
1959    }
1960
1961    /// Map every `repeated` field in all messages to the given
1962    /// [`RepeatedRepr`]. Convenience for `.repeated_type_in(repr, &["."])`.
1963    /// Call this *before* any [`repeated_type_in`](Self::repeated_type_in)
1964    /// overrides, since the last matching rule wins.
1965    #[must_use]
1966    pub fn repeated_type(mut self, repr: RepeatedRepr) -> Self {
1967        self.codegen_config
1968            .repeated_fields
1969            .push((".".to_string(), repr));
1970        self
1971    }
1972
1973    /// Map the matching `repeated` fields to a custom collection implementing
1974    /// `buffa::ProtoList<T>`, named by a Rust type-path **template** with a `*`
1975    /// placeholder for the element type (e.g. `"::my_crate::SmallList<*>"`).
1976    /// Note the asymmetry with the scalar `string_type_custom` /
1977    /// `bytes_type_custom` knobs: those take a *complete* path, this takes a
1978    /// `*`-template that wraps the element. Shorthand for
1979    /// [`repeated_type_in`](Self::repeated_type_in)`(RepeatedRepr::Custom(template), paths)`.
1980    ///
1981    /// # Limitations
1982    ///
1983    /// - The template must contain at least one `*`; a template that omits it,
1984    ///   or whose substitution is not a Rust type path, is reported as a
1985    ///   codegen error from [`compile`](Self::compile).
1986    /// - The resolved collection must implement `buffa::ProtoList<T>`. An
1987    ///   associated type resolving to `Vec<T>` already satisfies this; a
1988    ///   foreign collection without an implementation needs a crate-local
1989    ///   newtype to satisfy the orphan rule.
1990    /// - Vtable reflection requires `ReflectList`; cleanup-profile borrowed
1991    ///   inspection requires `InspectList`. Ordinary bridge reflection needs
1992    ///   neither on the owned collection.
1993    /// - JSON scalar, enum and policy helpers decode through `ProtoList<T>`
1994    ///   and the element's JSON traits, without requiring the collection's
1995    ///   `Deserialize`. Positions using ordinary serde instead require the
1996    ///   collection's `Serialize` / `Deserialize`. See [`RepeatedRepr::Custom`]
1997    ///   for the complete representation requirements and `buffa::ProtoList`
1998    ///   for a worked newtype example.
1999    #[must_use]
2000    pub fn repeated_type_custom_in(self, template: &str, paths: &[impl AsRef<str>]) -> Self {
2001        self.repeated_type_in(RepeatedRepr::Custom(template.to_string()), paths)
2002    }
2003
2004    /// Map every `repeated` field to the given custom collection template.
2005    /// Convenience for `.repeated_type_custom_in(template, &["."])`; see it for
2006    /// the limitations (the `*` placeholder, foreign reflection, the JSON /
2007    /// `arbitrary` requirements).
2008    #[must_use]
2009    pub fn repeated_type_custom(self, template: &str) -> Self {
2010        self.repeated_type(RepeatedRepr::Custom(template.to_string()))
2011    }
2012
2013    /// Add a custom attribute to generated types (messages and enums)
2014    /// matching a proto path prefix.
2015    ///
2016    /// `path` is a fully-qualified proto path prefix: `"."` applies to all
2017    /// types, `".my.pkg"` to types in that package, `".my.pkg.MyMessage"`
2018    /// to a specific type. A leading `.` is auto-prepended if omitted; a
2019    /// trailing `.` is trimmed. Prefix matching respects proto-segment
2020    /// boundaries, so `".my.pk"` does not match `".my.pkg.Msg"`.
2021    ///
2022    /// `attribute` is one or more outer Rust attributes, each written with
2023    /// its `#[...]` (e.g., `"#[derive(serde::Serialize)]"`). Any other
2024    /// string, such as `"serde(skip)"` or an empty one, makes
2025    /// [`compile`](Self::compile) fail with
2026    /// [`CodeGenError::InvalidCustomAttribute`](buffa_codegen::CodeGenError),
2027    /// whether or not `path` matches a generated type.
2028    ///
2029    /// Multiple calls accumulate in insertion order — all matching attributes
2030    /// are emitted, and ordering is preserved in generated code.
2031    ///
2032    /// Also applies to generated oneof enums when `path` matches
2033    /// `".pkg.Msg.my_oneof"` (the oneof's fully-qualified path).
2034    ///
2035    /// # Pitfalls
2036    ///
2037    /// buffa already emits `#[derive(Clone, PartialEq)]` on messages and
2038    /// `#[derive(Clone, PartialEq, Debug)]` on oneofs (oneofs with a
2039    /// `[debug_redact = true]` variant get a generated `Debug` impl instead
2040    /// of the `Debug` derive); adding a duplicate derive via
2041    /// `type_attribute(".", "#[derive(Clone)]")` produces a compile error in
2042    /// the generated code.
2043    ///
2044    /// A custom `serde::Serialize` derive has two additional requirements:
2045    /// messages must disable unknown-field preservation because
2046    /// `UnknownFields` does not implement `serde::Serialize`, and the `json`
2047    /// feature must be enabled for buffa's `EnumValue` and `MessageField`
2048    /// serde implementations. Do not combine a custom derive with
2049    /// [`generate_json(true)`](Self::generate_json), which already generates
2050    /// the message's serde implementations.
2051    ///
2052    /// # Example
2053    ///
2054    /// ```rust,ignore
2055    /// buffa_build::Config::new()
2056    ///     // `UnknownFields` does not implement `serde::Serialize`; with this
2057    ///     // off, unknown fields are dropped on decode.
2058    ///     .preserve_unknown_fields(false)
2059    ///     .type_attribute(".", "#[derive(serde::Serialize)]")
2060    ///     .type_attribute(".my.pkg.MyEnum", "#[derive(strum::EnumIter)]")
2061    ///     .files(&["proto/my_service.proto"])
2062    ///     .includes(&["proto/"])
2063    ///     .compile()
2064    ///     .unwrap();
2065    /// ```
2066    #[must_use]
2067    pub fn type_attribute(mut self, path: impl Into<String>, attribute: impl Into<String>) -> Self {
2068        self.codegen_config
2069            .type_attributes
2070            .push((normalize_attr_path(path.into()), attribute.into()));
2071        self
2072    }
2073
2074    /// Add a custom attribute to generated struct fields matching a proto
2075    /// path prefix.
2076    ///
2077    /// `path` is a fully-qualified proto field path (e.g.,
2078    /// `".my.pkg.MyMessage.my_field"`). `"."` applies to all fields. A
2079    /// leading `.` is auto-prepended if omitted; a trailing `.` is trimmed.
2080    /// Prefix matching respects proto-segment boundaries.
2081    ///
2082    /// Also applies to oneof variants when `path` matches
2083    /// `".pkg.Msg.my_oneof.variant_name"`, but not to the struct field holding
2084    /// the oneof; use
2085    /// [`oneof_struct_field_attribute`](Self::oneof_struct_field_attribute) for
2086    /// that.
2087    ///
2088    /// `attribute` follows the rule given for
2089    /// [`type_attribute`](Self::type_attribute): any string that is not one
2090    /// or more `#[...]` attributes, an empty one included, makes
2091    /// [`compile`](Self::compile) fail.
2092    ///
2093    /// A `#[deprecated]` supplied here wins over the one codegen derives from
2094    /// the field's `[deprecated = true]` option — rustc permits only one
2095    /// `deprecated` attribute per item — so this is also how to attach a note
2096    /// naming the replacement. Either source marks every generated way to
2097    /// reach a message field: the `with_*` setter, the same field on the
2098    /// views, its `OwnedView` accessor and, for a `required` field, the views'
2099    /// `has_*` method. Those carry a bare `#[deprecated]`; the attribute given
2100    /// here, with its note, stays on the owned struct's field. Either source
2101    /// also makes the generated items that visit the field carry
2102    /// `#[allow(deprecated)]`.
2103    ///
2104    /// A `deprecated` inside `cfg_attr` counts too: it replaces the
2105    /// option-derived marker on the owned field, and the setter and view
2106    /// markers stay unconditional.
2107    ///
2108    /// A oneof variant gets only the attribute given here. Its view variant is
2109    /// unmarked and the generated impls that match on it are not guarded, so
2110    /// put `#[allow(deprecated)]` on the `mod` that includes the generated
2111    /// file.
2112    ///
2113    /// # Example
2114    ///
2115    /// ```rust,ignore
2116    /// buffa_build::Config::new()
2117    ///     .field_attribute(".my.pkg.MyMessage.secret_key", "#[serde(skip)]")
2118    ///     .files(&["proto/my_service.proto"])
2119    ///     .includes(&["proto/"])
2120    ///     .compile()
2121    ///     .unwrap();
2122    /// ```
2123    #[must_use]
2124    pub fn field_attribute(
2125        mut self,
2126        path: impl Into<String>,
2127        attribute: impl Into<String>,
2128    ) -> Self {
2129        self.codegen_config
2130            .field_attributes
2131            .push((normalize_attr_path(path.into()), attribute.into()));
2132        self
2133    }
2134
2135    /// Add a custom attribute to generated message structs only (not enums,
2136    /// not oneof enums — those are reached by
2137    /// [`enum_attribute`](Self::enum_attribute) and
2138    /// [`oneof_attribute`](Self::oneof_attribute) respectively) matching a
2139    /// proto path prefix.
2140    ///
2141    /// Same path-matching semantics as [`type_attribute`](Self::type_attribute) —
2142    /// leading `.` auto-prepended, trailing `.` trimmed, proto-segment-aware
2143    /// prefix matching, accumulation in insertion order. Useful for
2144    /// struct-only attributes like `#[serde(default)]`.
2145    ///
2146    /// `attribute` follows the rule given for
2147    /// [`type_attribute`](Self::type_attribute): any string that is not one
2148    /// or more `#[...]` attributes, an empty one included, makes
2149    /// [`compile`](Self::compile) fail.
2150    ///
2151    /// # Example
2152    ///
2153    /// ```rust,ignore
2154    /// buffa_build::Config::new()
2155    ///     .message_attribute(".", "#[serde(default)]")
2156    ///     .files(&["proto/my_service.proto"])
2157    ///     .includes(&["proto/"])
2158    ///     .compile()
2159    ///     .unwrap();
2160    /// ```
2161    #[must_use]
2162    pub fn message_attribute(
2163        mut self,
2164        path: impl Into<String>,
2165        attribute: impl Into<String>,
2166    ) -> Self {
2167        self.codegen_config
2168            .message_attributes
2169            .push((normalize_attr_path(path.into()), attribute.into()));
2170        self
2171    }
2172
2173    /// Add a custom attribute to generated enum types only (not message
2174    /// structs, not oneof enums — those are reached by
2175    /// [`type_attribute`](Self::type_attribute) on the oneof's path or by
2176    /// [`oneof_attribute`](Self::oneof_attribute)) matching a proto path
2177    /// prefix.
2178    ///
2179    /// Same path-matching semantics as [`type_attribute`](Self::type_attribute) —
2180    /// leading `.` auto-prepended, trailing `.` trimmed, proto-segment-aware
2181    /// prefix matching, accumulation in insertion order. Useful when you want
2182    /// to inject an attribute on every enum in a package without also matching
2183    /// the (often more numerous) messages that share the path prefix — e.g.
2184    /// `#[derive(strum::EnumIter)]`, which only makes sense on enums.
2185    ///
2186    /// `attribute` follows the rule given for
2187    /// [`type_attribute`](Self::type_attribute): any string that is not one
2188    /// or more `#[...]` attributes, an empty one included, makes
2189    /// [`compile`](Self::compile) fail.
2190    ///
2191    /// # Example
2192    ///
2193    /// ```rust,ignore
2194    /// buffa_build::Config::new()
2195    ///     .enum_attribute(".my.pkg", "#[derive(strum::EnumIter)]")
2196    ///     .files(&["proto/my_service.proto"])
2197    ///     .includes(&["proto/"])
2198    ///     .compile()
2199    ///     .unwrap();
2200    /// ```
2201    #[must_use]
2202    pub fn enum_attribute(mut self, path: impl Into<String>, attribute: impl Into<String>) -> Self {
2203        self.codegen_config
2204            .enum_attributes
2205            .push((normalize_attr_path(path.into()), attribute.into()));
2206        self
2207    }
2208
2209    /// Add a custom attribute to generated oneof enums only (not message
2210    /// structs, not regular enums) matching a proto path prefix.
2211    ///
2212    /// Same path-matching semantics as [`type_attribute`](Self::type_attribute):
2213    /// a leading `.` is auto-prepended, a trailing `.` is trimmed, prefixes
2214    /// match on proto-path segments, and attributes accumulate in insertion
2215    /// order. The match key is the oneof's fully-qualified path
2216    /// (`.my.pkg.MyMessage.my_oneof`) — the whole-enum path has no variant
2217    /// segment; to target a single variant's field, append `.variant_name`
2218    /// and use [`field_attribute`](Self::field_attribute) instead, and for the
2219    /// message struct's field holding the oneof, use
2220    /// [`oneof_struct_field_attribute`](Self::oneof_struct_field_attribute).
2221    /// `attribute` follows the rule given for
2222    /// [`type_attribute`](Self::type_attribute): any string that is not one
2223    /// or more `#[...]` attributes, an empty one included, makes
2224    /// [`compile`](Self::compile) fail.
2225    ///
2226    /// Useful when a oneof needs a different attribute set than the
2227    /// surrounding types — for example to keep `#[derive(serde::Serialize)]`
2228    /// on messages and oneofs while
2229    /// [`enum_attribute`](Self::enum_attribute) gives the regular enums a
2230    /// different serde derive.
2231    ///
2232    /// Applies to the owned oneof enum only; the zero-copy view-of-oneof
2233    /// enum receives no custom attributes (true of the whole attribute
2234    /// family). For JSON serialization of both owned types and views, use
2235    /// [`generate_json(true)`](Self::generate_json), which emits canonical
2236    /// protobuf-JSON impls rather than derived ones.
2237    ///
2238    /// # Pitfalls
2239    ///
2240    /// Generated oneof enums already derive `Clone`, `PartialEq`, and
2241    /// `Debug` (oneofs containing `[debug_redact = true]` fields replace the
2242    /// `Debug` derive with a manual impl). Re-deriving any of these via
2243    /// `oneof_attribute` produces a conflicting-implementation compile error
2244    /// inside the generated code.
2245    ///
2246    /// For the `serde::Serialize` requirements when the surrounding messages
2247    /// also use a custom derive, see the [`type_attribute`](Self::type_attribute)
2248    /// pitfalls: disable unknown-field preservation for messages and enable
2249    /// the `json` feature for buffa's serde implementations. Do not combine
2250    /// custom derives with [`generate_json(true)`](Self::generate_json).
2251    ///
2252    /// # Example
2253    ///
2254    /// ```rust,ignore
2255    /// buffa_build::Config::new()
2256    ///     // one specific oneof; ".my.pkg" would match every oneof in the package
2257    ///     .oneof_attribute(".my.pkg.MyMessage.my_oneof", "#[derive(serde::Serialize)]")
2258    ///     .files(&["proto/my_service.proto"])
2259    ///     .includes(&["proto/"])
2260    ///     .compile()
2261    ///     .unwrap();
2262    /// ```
2263    #[must_use]
2264    pub fn oneof_attribute(
2265        mut self,
2266        path: impl Into<String>,
2267        attribute: impl Into<String>,
2268    ) -> Self {
2269        self.codegen_config
2270            .oneof_attributes
2271            .push((normalize_attr_path(path.into()), attribute.into()));
2272        self
2273    }
2274
2275    /// Add a custom attribute to the message struct's field holding a oneof
2276    /// (the `Option<OneofEnum>` member), not to the oneof's variants.
2277    ///
2278    /// The match key is the oneof's fully-qualified path
2279    /// (`.my.pkg.MyMessage.my_oneof`), with the same path-matching semantics
2280    /// as [`type_attribute`](Self::type_attribute): `".my.pkg"` reaches the
2281    /// oneof field of every message in the package, nested ones included.
2282    /// Attributes accumulate in insertion order, after buffa's own attributes
2283    /// on the field.
2284    ///
2285    /// `attribute` follows the rule given for
2286    /// [`type_attribute`](Self::type_attribute): any string that is not one
2287    /// or more `#[...]` attributes, an empty one included, makes
2288    /// [`compile`](Self::compile) fail.
2289    ///
2290    /// A rule on a variant's path (`.my.pkg.MyMessage.my_oneof.variant_name`)
2291    /// does not match the oneof, so it has no effect, and the build does not
2292    /// warn about it. Variants take their attributes from
2293    /// [`field_attribute`](Self::field_attribute).
2294    ///
2295    /// Each of these lines of the generated code for a oneof takes its
2296    /// attributes from a different method:
2297    ///
2298    /// ```rust,ignore
2299    /// pub struct Event {
2300    ///     // oneof_struct_field_attribute(".pkg.Event.payload", ..)
2301    ///     pub payload: Option<event::Payload>,
2302    /// }
2303    ///
2304    /// // oneof_attribute(".pkg.Event.payload", ..), or type_attribute on the same path
2305    /// pub enum Payload {
2306    ///     // field_attribute(".pkg.Event.payload.text", ..)
2307    ///     Text(String),
2308    /// }
2309    /// ```
2310    ///
2311    /// `field_attribute` on the oneof's path (`.pkg.Event.payload`) matches
2312    /// the variants only, where an attribute
2313    /// such as `#[serde(skip_serializing_if = "...")]` is rejected. prost-build
2314    /// puts such a `field_attribute` on the struct field as well; use this
2315    /// method for the struct field.
2316    ///
2317    /// Applies to the owned message struct only; the view structs do not get
2318    /// the attribute.
2319    ///
2320    /// A `#[deprecated]` given here marks the owned struct's field only. The
2321    /// same field on the view structs stays unmarked, so reading the oneof
2322    /// through a view does not warn, unlike a field deprecated through
2323    /// `field_attribute`. The generated items that visit the owned field
2324    /// carry `#[allow(deprecated)]`.
2325    ///
2326    /// # Pitfalls
2327    ///
2328    /// With [`generate_json(true)`](Self::generate_json) the field already
2329    /// carries buffa's `#[serde(flatten)]` for the derived `Serialize`, and
2330    /// buffa generates the `Deserialize` impl of a message with a oneof
2331    /// instead of deriving it. So a serde attribute given here changes the
2332    /// owned message's `Serialize` output only: `Deserialize` and the views'
2333    /// `Serialize` ignore it. A second `flatten` is a compile error in the
2334    /// generated code. Serde attributes here are for a serde derive that you
2335    /// attach yourself, with `generate_json` off.
2336    ///
2337    /// With
2338    /// [`gate_impls_on_crate_features(true)`](Self::gate_impls_on_crate_features)
2339    /// buffa's serde derive is compiled only under the JSON feature. Write a
2340    /// serde attribute for it as `#[cfg_attr(feature = "json", serde(...))]`,
2341    /// with your JSON feature's name if you renamed it, so that it is compiled
2342    /// under the same feature.
2343    ///
2344    /// # Example
2345    ///
2346    /// ```rust,ignore
2347    /// buffa_build::Config::new()
2348    ///     // `UnknownFields` does not implement `serde::Serialize`. With this
2349    ///     // off, unknown fields are dropped on decode.
2350    ///     .preserve_unknown_fields(false)
2351    ///     .message_attribute(".my.pkg.MyMessage", "#[derive(serde::Serialize)]")
2352    ///     .oneof_attribute(".my.pkg.MyMessage.my_oneof", "#[derive(serde::Serialize)]")
2353    ///     .oneof_struct_field_attribute(
2354    ///         ".my.pkg.MyMessage.my_oneof",
2355    ///         "#[serde(skip_serializing_if = \"Option::is_none\")]",
2356    ///     )
2357    ///     .files(&["proto/my_service.proto"])
2358    ///     .includes(&["proto/"])
2359    ///     .compile()
2360    ///     .unwrap();
2361    /// ```
2362    #[must_use]
2363    pub fn oneof_struct_field_attribute(
2364        mut self,
2365        path: impl Into<String>,
2366        attribute: impl Into<String>,
2367    ) -> Self {
2368        self.codegen_config
2369            .oneof_struct_field_attributes
2370            .push((normalize_attr_path(path.into()), attribute.into()));
2371        self
2372    }
2373
2374    /// Use `buf build` instead of `protoc` for descriptor generation.
2375    ///
2376    /// `buf` is often easier to install and keep current than `protoc`
2377    /// (which many distros pin to old versions). This mode is intended for
2378    /// the **single-crate case**: a `buf.yaml` at the crate root defining
2379    /// the module layout.
2380    ///
2381    /// Requires `buf` on PATH and a `buf.yaml` at the crate root. The
2382    /// [`includes()`](Self::includes) setting is ignored — buf resolves
2383    /// imports via its own module configuration.
2384    ///
2385    /// Each path given to [`files()`](Self::files) must be **relative to its
2386    /// owning module's directory** (the `path:` value inside `buf.yaml`), not
2387    /// the crate root where `buf.yaml` itself lives. buf strips the module
2388    /// path when producing `FileDescriptorProto.name`, so for
2389    /// `modules: [{path: proto}]` and a file on disk at
2390    /// `proto/api/v1/service.proto`, the descriptor name is
2391    /// `api/v1/service.proto` — that is what `.files()` must contain.
2392    /// Multiple modules in one `buf.yaml` work fine; buf enforces that
2393    /// module-relative names are unique across the workspace.
2394    ///
2395    /// # Monorepo / multi-module setups
2396    ///
2397    /// For a workspace-root `buf.yaml` with many modules, this mode is a
2398    /// poor fit. Prefer running `buf generate` with the `protoc-gen-reallyme-buffa`
2399    /// plugin and checking in the generated code, or use
2400    /// [`descriptor_set()`](Self::descriptor_set) with the output of
2401    /// `buf build --as-file-descriptor-set -o fds.binpb <module-path>`
2402    /// run as a pre-build step.
2403    ///
2404    /// # Example
2405    ///
2406    /// ```rust,ignore
2407    /// // buf.yaml (at crate root):
2408    /// //   version: v2
2409    /// //   modules:
2410    /// //     - path: proto
2411    /// //
2412    /// // build.rs:
2413    /// buffa_build::Config::new()
2414    ///     .use_buf()
2415    ///     .files(&["api/v1/service.proto"])  // relative to module root
2416    ///     .compile()
2417    ///     .unwrap();
2418    /// ```
2419    #[must_use]
2420    pub fn use_buf(mut self) -> Self {
2421        self.descriptor_source = DescriptorSource::Buf;
2422        self
2423    }
2424
2425    /// Use a pre-compiled `FileDescriptorSet` binary file as input.
2426    ///
2427    /// Skips invoking `protoc` or `buf` entirely. The file must contain a
2428    /// serialized `google.protobuf.FileDescriptorSet` (as produced by
2429    /// `protoc --descriptor_set_out` or `buf build --as-file-descriptor-set`).
2430    ///
2431    /// When using this, `.files()` specifies which proto files in the
2432    /// descriptor set to generate code for (matching by proto file name).
2433    /// For in-memory input, use [`descriptor_set_bytes()`](Self::descriptor_set_bytes).
2434    #[must_use]
2435    pub fn descriptor_set(mut self, path: impl Into<PathBuf>) -> Self {
2436        self.descriptor_source = DescriptorSource::Precompiled(path.into());
2437        self
2438    }
2439
2440    /// Use a serialized `google.protobuf.FileDescriptorSet` held in memory.
2441    ///
2442    /// Use this when the build script produces the descriptor set itself, for
2443    /// example with an in-process compiler such as `protox`.
2444    /// [`compile()`](Self::compile) decodes the bytes and does not invoke
2445    /// `protoc` or `buf`. This replaces any previously configured descriptor
2446    /// source. Pass a slice as `bytes.to_vec()`.
2447    ///
2448    /// [`files()`](Self::files) selects which proto files in the descriptor set
2449    /// to generate, using their exact descriptor names (relative to the proto
2450    /// source root). The set must also contain their transitive imports.
2451    /// [`includes()`](Self::includes) is ignored.
2452    ///
2453    /// # Rebuilds
2454    ///
2455    /// Print a `cargo:rerun-if-changed` or `cargo:rerun-if-env-changed` line
2456    /// for every input the bytes were built from. `buffa-build` cannot see
2457    /// those inputs, and `compile()` always prints a `rerun-if-env-changed`
2458    /// line of its own, which turns off Cargo's default of rerunning the build
2459    /// script when any file in the package changes. Without your own lines, an
2460    /// edited `.proto` file does not rerun the script, and the generated code
2461    /// goes stale.
2462    ///
2463    /// # Example
2464    ///
2465    /// ```no_run
2466    /// # fn compile_protos_in_process() -> Vec<u8> { Vec::new() }
2467    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
2468    /// let bytes: Vec<u8> = compile_protos_in_process();
2469    /// println!("cargo:rerun-if-changed=proto");
2470    /// buffa_build::Config::new()
2471    ///     .descriptor_set_bytes(bytes)
2472    ///     .files(&["api/v1/service.proto"])
2473    ///     .compile()?;
2474    /// # Ok(())
2475    /// # }
2476    /// ```
2477    #[must_use]
2478    pub fn descriptor_set_bytes(mut self, bytes: Vec<u8>) -> Self {
2479        self.descriptor_source = DescriptorSource::Bytes(bytes);
2480        self
2481    }
2482
2483    /// Generate a module-tree include file alongside the per-package `.rs`
2484    /// files.
2485    ///
2486    /// The include file contains nested `pub mod` declarations with
2487    /// `include!()` directives that assemble the generated code into a
2488    /// module hierarchy matching the protobuf package structure. Users can
2489    /// then include this single file instead of manually creating the
2490    /// module tree.
2491    ///
2492    /// The form of the emitted `include!` directives depends on whether
2493    /// [`out_dir`](Self::out_dir) was set:
2494    ///
2495    /// - **Default (`$OUT_DIR`)**: emits
2496    ///   `include!(concat!(env!("OUT_DIR"), "/foo.rs"))`, for use from
2497    ///   `build.rs` via `include!(concat!(env!("OUT_DIR"), "/<name>"))`.
2498    /// - **Explicit `out_dir`**: emits sibling-relative `include!("foo.rs")`,
2499    ///   for checking the generated code into the source tree and referencing
2500    ///   it as a module (e.g. `mod gen;`). The include file then has to sit in
2501    ///   `out_dir` itself: `name` must be a bare file name, and
2502    ///   [`compile`](Self::compile) rejects a name with a directory part.
2503    ///
2504    /// With [`shared_descriptor_pool`](Self::shared_descriptor_pool), `name`
2505    /// must be a bare file name in both modes. In `$OUT_DIR` mode without the
2506    /// shared pool, `name` may have a directory part (`"nested/_include.rs"`),
2507    /// and [`compile`](Self::compile) creates that directory.
2508    ///
2509    /// # Example — `build.rs` / `$OUT_DIR`
2510    ///
2511    /// ```rust,ignore
2512    /// // build.rs
2513    /// buffa_build::Config::new()
2514    ///     .files(&["proto/my_service.proto"])
2515    ///     .includes(&["proto/"])
2516    ///     .include_file("_include.rs")
2517    ///     .compile()
2518    ///     .unwrap();
2519    ///
2520    /// // lib.rs
2521    /// include!(concat!(env!("OUT_DIR"), "/_include.rs"));
2522    /// ```
2523    ///
2524    /// # Example — checked-in source
2525    ///
2526    /// ```rust,ignore
2527    /// // codegen.rs (run manually, not from build.rs)
2528    /// buffa_build::Config::new()
2529    ///     .files(&["proto/my_service.proto"])
2530    ///     .includes(&["proto/"])
2531    ///     .out_dir("src/gen")
2532    ///     .include_file("mod.rs")
2533    ///     .compile()
2534    ///     .unwrap();
2535    ///
2536    /// // lib.rs
2537    /// mod gen;
2538    /// ```
2539    #[must_use]
2540    pub fn include_file(mut self, name: impl Into<String>) -> Self {
2541        self.include_file = Some(name.into());
2542        self
2543    }
2544
2545    /// Compile proto files and generate Rust source.
2546    ///
2547    /// # Errors
2548    ///
2549    /// Returns an error if:
2550    /// - `OUT_DIR` is not set and no `out_dir` was configured
2551    /// - [`shared_descriptor_pool`](Self::shared_descriptor_pool) is set
2552    ///   without reflection enabled, without
2553    ///   [`include_file`](Self::include_file), or with an `include_file`
2554    ///   that is not a bare file name or lacks a file-name stem
2555    /// - an explicit [`out_dir`](Self::out_dir) is combined with an
2556    ///   [`include_file`](Self::include_file) that is not a bare file name
2557    /// - `protoc` or `buf` cannot be found on `PATH` (when using those sources)
2558    /// - the proto compiler exits with a non-zero status (syntax errors,
2559    ///   missing imports, etc.)
2560    /// - a precompiled descriptor set file cannot be read
2561    /// - the descriptor set bytes cannot be decoded as a `FileDescriptorSet`
2562    /// - an [`extern_path`](Self::extern_path) proto name has an empty
2563    ///   segment or a segment that is not a protobuf identifier
2564    /// - a custom attribute string, given to
2565    ///   [`type_attribute`](Self::type_attribute) or one of the five methods
2566    ///   beside it, is not one or more `#[...]` attributes
2567    /// - code generation fails (e.g. unsupported proto feature), including a
2568    ///   [`codec_strategy_in`](Self::codec_strategy_in) rule that names by its
2569    ///   exact path a message that cannot use the table codec
2570    /// - [`CodecStrategy::Table`] is requested and the compiler is older than
2571    ///   Rust 1.77
2572    /// - the output directory cannot be created or written to
2573    pub fn compile(mut self) -> Result<(), Box<dyn std::error::Error>> {
2574        // Table code needs `offset_of!`, stable in Rust 1.77. Say so once here,
2575        // and not once per field in the compiler's output.
2576        let table_codec_requested = self.codegen_config.codec_strategy == CodecStrategy::Table
2577            || self
2578                .codegen_config
2579                .codec_strategy_in
2580                .iter()
2581                .any(|(_, strategy)| *strategy == CodecStrategy::Table);
2582        // Outside a build script `RUSTC` is unset, and the toolchain that
2583        // compiles the generated code is unknown, so it is not checked.
2584        if table_codec_requested {
2585            if let Some(minor) = rustc_minor_version() {
2586                if minor < 77 {
2587                    return Err(format!(
2588                        "CodecStrategy::Table needs Rust 1.77 or later, and this build uses \
2589                         1.{minor}; use a newer compiler or select CodecStrategy::Unrolled"
2590                    )
2591                    .into());
2592                }
2593            }
2594        }
2595
2596        // Reject malformed `exclude_package` entries before protoc runs; the
2597        // codegen normalizes them again, but a typo should not cost a protoc
2598        // invocation to surface.
2599        for entry in &self.codegen_config.exclude_packages {
2600            if let Err(e) = buffa_codegen::normalize_exclude_package(entry) {
2601                return Err(format!("exclude_package {entry:?}: {e}").into());
2602            }
2603        }
2604
2605        // Same for `extern_path`: a name that can match no type would leave
2606        // the mapping silently unused. The plugin applies the same function.
2607        for (proto, _) in &mut self.codegen_config.extern_paths {
2608            *proto = buffa_codegen::normalize_extern_path_proto_name(proto)?;
2609        }
2610
2611        // Validate the shared-pool prerequisites before doing any work, and
2612        // check reflection first so the error names the actually-missing
2613        // prerequisite rather than a downstream one. `generate_reflection` is
2614        // also enforced in `buffa-codegen`, but catching it here gives a
2615        // buffa-build-shaped message.
2616        let sidecar = if self.codegen_config.shared_descriptor_pool {
2617            if !self.codegen_config.generate_reflection {
2618                return Err("shared_descriptor_pool requires reflection to be enabled \
2619                            (call generate_reflection(true) or reflect_mode(...))"
2620                    .into());
2621            }
2622            // The shared `__buffa_fds` module is emitted into the include file
2623            // at the tree root; without it the per-package delegations have
2624            // nothing to resolve against.
2625            let Some(include_name) = self.include_file.as_deref() else {
2626                return Err("shared_descriptor_pool requires include_file to be set \
2627                            (the shared descriptor module is emitted into it)"
2628                    .into());
2629            };
2630            // The sidecar is named after the include file's stem; reject names
2631            // without one ("", ".", "..") here rather than writing a stray
2632            // misnamed sidecar before the include-file write fails. The stem
2633            // is computed once here and reused when the sidecar is written.
2634            let Some(stem) = Path::new(include_name).file_stem().and_then(|s| s.to_str()) else {
2635                return Err(format!(
2636                    "shared_descriptor_pool requires include_file to have a file name \
2637                     (the descriptor-set sidecar is named after its stem); \
2638                     got {include_name:?}"
2639                )
2640                .into());
2641            };
2642            // The sidecar is named after the stem alone and written at the
2643            // output root, so `a/gen.rs` and `b/gen.rs` from two compile()
2644            // calls would share `gen.descriptor_set.binpb`, and the first tree
2645            // would build its pool from the second tree's descriptors.
2646            if !is_bare_file_name(include_name) {
2647                let reason = if include_name.contains('\0') {
2648                    NUL_IN_FILE_NAME
2649                } else {
2650                    "the descriptor-set sidecar is named after the stem alone and \
2651                     written at the output root, so include files in two directories \
2652                     would share it"
2653                };
2654                return Err(format!(
2655                    "shared_descriptor_pool requires include_file to be a bare file name \
2656                     ({reason}); got {include_name:?}"
2657                )
2658                .into());
2659            }
2660            Some(format!("{stem}.descriptor_set.binpb"))
2661        } else {
2662            None
2663        };
2664
2665        // When out_dir is explicitly set, the include file should use
2666        // relative `include!("foo.rs")` paths (the index is a sibling of the
2667        // generated files). When defaulted to $OUT_DIR, keep the
2668        // `concat!(env!("OUT_DIR"), ...)` form so that
2669        // `include!(concat!(env!("OUT_DIR"), "/_include.rs"))` from src/
2670        // still resolves to absolute paths.
2671        let relative_includes = self.out_dir.is_some();
2672        // Those relative paths name siblings of the include file, so the
2673        // include file has to sit in the output directory itself, with or
2674        // without the shared pool (which has already required a bare name
2675        // above). `$OUT_DIR` mode emits absolute paths, which resolve from any
2676        // directory.
2677        if let Some(include_name) = self.include_file.as_deref() {
2678            if relative_includes && !is_bare_file_name(include_name) {
2679                let reason = if include_name.contains('\0') {
2680                    NUL_IN_FILE_NAME
2681                } else {
2682                    "the generated include! paths are relative to the include file"
2683                };
2684                return Err(format!(
2685                    "include_file must be a bare file name when out_dir is set \
2686                     ({reason}); got {include_name:?}"
2687                )
2688                .into());
2689            }
2690        }
2691        let out_dir = self
2692            .out_dir
2693            .or_else(|| std::env::var("OUT_DIR").ok().map(PathBuf::from))
2694            .ok_or("OUT_DIR not set and no out_dir configured")?;
2695
2696        // Produce a FileDescriptorSet from the configured source.
2697        let descriptor_bytes: Cow<'_, [u8]> = match &self.descriptor_source {
2698            DescriptorSource::Protoc => invoke_protoc(&self.files, &self.includes)?.into(),
2699            DescriptorSource::Buf => invoke_buf()?.into(),
2700            DescriptorSource::Precompiled(path) => std::fs::read(path)
2701                .map_err(|e| format!("failed to read descriptor set '{}': {}", path.display(), e))?
2702                .into(),
2703            DescriptorSource::Bytes(bytes) => Cow::Borrowed(bytes),
2704        };
2705        // This descriptor set came from a protoc (or buf) invocation this build
2706        // controls, or a path or bytes the caller supplied, so the bound is far above
2707        // buffa's untrusted-input default — that default is sized for wire
2708        // input and a schema of a few hundred `.proto` files exceeds it,
2709        // descriptor types being wide structs. Still finite, so a truncated or
2710        // stale precompiled set fails with an error rather than an OOM.
2711        let decode_options = buffa_codegen::tooling_decode_options()?;
2712        let fds = decode_options
2713            .decode_from_slice::<FileDescriptorSet>(&descriptor_bytes)
2714            .map_err(|e| {
2715                buffa_codegen::decode_failure(
2716                    "FileDescriptorSet",
2717                    &e,
2718                    decode_options.element_memory_limit(),
2719                )
2720            })?;
2721
2722        // Determine which files were explicitly requested.
2723        //
2724        // `FileDescriptorProto.name` contains the path relative to the proto
2725        // source root (protoc: `--proto_path`; buf: the module root). For
2726        // Precompiled, Bytes, and Buf mode, `.files()` are expected to already be
2727        // proto-relative names. For Protoc mode, strip the first matching
2728        // include prefix.
2729        let files_to_generate: Vec<String> = if matches!(
2730            self.descriptor_source,
2731            DescriptorSource::Precompiled(_) | DescriptorSource::Bytes(_) | DescriptorSource::Buf
2732        ) {
2733            self.files
2734                .iter()
2735                .filter_map(|f| f.to_str().map(str::to_string))
2736                .collect()
2737        } else {
2738            self.files
2739                .iter()
2740                .map(|f| proto_relative_name(f, &self.includes))
2741                .filter(|s| !s.is_empty())
2742                .collect()
2743        };
2744
2745        // Generate Rust source. Per-proto content files plus a per-package
2746        // `.mod.rs` stitcher; only the stitchers need wiring into the
2747        // module tree (content files are reached via `include!` from
2748        // there).
2749        let (generated, warnings) = buffa_codegen::generate_with_diagnostics(
2750            &fds.file,
2751            &files_to_generate,
2752            &self.codegen_config,
2753        )?;
2754
2755        // An include tree is written after content files. Compare destinations
2756        // before any writes: relative components, absolute paths, and existing
2757        // directory symlinks may name an adapter despite different spellings.
2758        // Runs without native adapters retain their existing include behavior.
2759        if let Some(include) = self.include_file.as_deref().filter(|_| {
2760            generated
2761                .iter()
2762                .any(|file| file.kind == buffa_codegen::GeneratedFileKind::Adapter)
2763        }) {
2764            let include_path = normalize_output_destination(&out_dir.join(include))?;
2765            for file in generated
2766                .iter()
2767                .filter(|file| file.kind == buffa_codegen::GeneratedFileKind::Adapter)
2768            {
2769                let adapter_path = normalize_output_destination(&out_dir.join(&file.name))?;
2770                if adapter_path
2771                    .as_os_str()
2772                    .as_encoded_bytes()
2773                    .eq_ignore_ascii_case(include_path.as_os_str().as_encoded_bytes())
2774                {
2775                    return Err(adapters::AdapterError::from(
2776                        adapters::ErrorReason::DuplicateOutput,
2777                    )
2778                    .into());
2779                }
2780            }
2781        }
2782
2783        // Surface non-fatal codegen diagnostics as Cargo build warnings. This
2784        // runs inside the consumer's `build.rs`, so `cargo:warning=` is shown in
2785        // their normal `cargo build` output.
2786        for warning in warnings {
2787            println!("cargo:warning=buffa: {warning}");
2788        }
2789
2790        // Write output files; collect (name, package) for PackageMod entries.
2791        let mut output_entries: Vec<(String, String)> = Vec::new();
2792        for file in generated {
2793            let path = out_dir.join(&file.name);
2794            if let Some(parent) = path.parent() {
2795                std::fs::create_dir_all(parent)?;
2796            }
2797            write_if_changed(&path, file.content.as_bytes())?;
2798            if file.kind == buffa_codegen::GeneratedFileKind::PackageMod {
2799                output_entries.push((file.name, file.package));
2800            }
2801        }
2802
2803        // Shared-pool mode needs a tree root to host the one `__buffa_fds`
2804        // module; that root is the include file. The reflection and
2805        // include-file prerequisites were validated up front, and `sidecar`
2806        // is `Some` exactly when the mode is on.
2807
2808        // Generate the include file if requested.
2809        if let Some(ref include_name) = self.include_file {
2810            std::fs::create_dir_all(&out_dir)?;
2811            let tree = generate_include_file(&output_entries, relative_includes);
2812            let include_content = if let Some(sidecar) = sidecar {
2813                // Embed the descriptor set once, at the tree root, instead of a
2814                // per-package copy. Write it as a binary sidecar and
2815                // `include_bytes!` it from the shared `__buffa_fds` module, so
2816                // the bytes never expand into Rust byte-literal source. Every
2817                // package's `__buffa::reflect` delegates to that module.
2818                // The sidecar name was derived from the include file's stem up
2819                // front, so two compile() calls sharing an out_dir don't
2820                // clobber each other's descriptor set as long as their include
2821                // file stems differ (`a.rs` and `b.rs`; `gen.rs` and `gen.txt`
2822                // share `gen.descriptor_set.binpb`). The bare-name requirement
2823                // keeps two directories from hiding one stem.
2824                let fds_bytes = buffa_codegen::encode_descriptor_set(
2825                    &fds.file,
2826                    &self.codegen_config.feature_overrides,
2827                );
2828                write_if_changed(&out_dir.join(&sidecar), &fds_bytes)?;
2829                let mode = if relative_includes {
2830                    buffa_codegen::IncludeMode::Relative("")
2831                } else {
2832                    buffa_codegen::IncludeMode::OutDir
2833                };
2834                let root = buffa_codegen::shared_descriptor_root_module(
2835                    &fds_bytes,
2836                    buffa_codegen::FdsEmbedding::Sidecar {
2837                        file_name: &sidecar,
2838                        mode,
2839                    },
2840                    self.codegen_config.reflect_feature_gate(),
2841                );
2842                // Keep the tree's `// @generated` marker on line 1 —
2843                // first-line generated-file detection (rustfmt's five-line
2844                // window, diff-collapse heuristics) misses a mid-file marker —
2845                // and put the shared root module between the header and the
2846                // `include!` items. This relies on `generate_include_file`
2847                // passing `emit_inner_allow = false`: an inner `#![allow]` on
2848                // the tree's second line would be illegal after an outer item.
2849                let (header, items) = tree
2850                    .split_once('\n')
2851                    .expect("generate_module_tree output starts with a header line");
2852                debug_assert!(
2853                    !items.trim_start().starts_with("#!["),
2854                    "shared root module cannot precede an inner attribute"
2855                );
2856                format!("{header}\n{root}{items}")
2857            } else {
2858                tree
2859            };
2860            let include_path = out_dir.join(include_name);
2861            // In `$OUT_DIR` mode the name may have a directory part.
2862            if let Some(parent) = include_path.parent() {
2863                std::fs::create_dir_all(parent)?;
2864            }
2865            write_if_changed(&include_path, include_content.as_bytes())?;
2866        }
2867
2868        // Tell cargo to re-run if any proto file changes.
2869        //
2870        // For Buf mode, `self.files` are module-root-relative and cargo can't
2871        // stat them — use `buf ls-files` instead, which lists all workspace
2872        // protos with workspace-relative paths. Protoc mode uses the decoded
2873        // descriptor set below to watch resolved transitive imports.
2874        // The decode bound is read from the environment, and this script
2875        // disables cargo's default env tracking by emitting rerun-if-* keys.
2876        println!(
2877            "cargo:rerun-if-env-changed={}",
2878            buffa_codegen::ELEMENT_MEMORY_LIMIT_ENV
2879        );
2880        match self.descriptor_source {
2881            DescriptorSource::Buf => emit_buf_rerun_if_changed(),
2882            DescriptorSource::Protoc => {
2883                // Rerun if PROTOC changes (different binary may accept
2884                // protos the previous one rejected, e.g. newer editions).
2885                println!("cargo:rerun-if-env-changed=PROTOC");
2886                for proto_file in protoc_rerun_if_changed_paths(&fds, &self.files, &self.includes) {
2887                    println!("cargo:rerun-if-changed={}", proto_file.display());
2888                }
2889            }
2890            DescriptorSource::Precompiled(ref path) => {
2891                println!("cargo:rerun-if-changed={}", path.display());
2892            }
2893            // The caller tracks the inputs used to produce these bytes.
2894            DescriptorSource::Bytes(_) => {}
2895        }
2896
2897        Ok(())
2898    }
2899}
2900
2901/// The reason given when an include file name contains a NUL byte.
2902const NUL_IN_FILE_NAME: &str = "a file name cannot contain a NUL byte";
2903
2904/// Resolve an output's existing components without creating its missing ones.
2905/// Resolve symlinks before processing `..`, matching filesystem traversal;
2906/// reducing all `..` components first would misidentify symlinked parents.
2907fn normalize_output_destination(path: &Path) -> Result<PathBuf, adapters::AdapterError> {
2908    let invalid = || adapters::AdapterError::from(adapters::ErrorReason::InvalidOutput);
2909    let absolute = if path.is_absolute() {
2910        path.to_owned()
2911    } else {
2912        std::env::current_dir().map_err(|_| invalid())?.join(path)
2913    };
2914    let mut normalized = PathBuf::new();
2915    for component in absolute.components() {
2916        match component {
2917            Component::Prefix(_) | Component::RootDir => normalized.push(component.as_os_str()),
2918            Component::CurDir => {}
2919            Component::ParentDir => {
2920                normalized.pop();
2921            }
2922            Component::Normal(name) => {
2923                normalized.push(name);
2924                match normalized.canonicalize() {
2925                    Ok(existing) => normalized = existing,
2926                    Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
2927                        // A dangling link can become live when an earlier output
2928                        // is written. Do not treat that link as a new file: its
2929                        // eventual destination cannot be compared safely yet.
2930                        match normalized.symlink_metadata() {
2931                            Ok(metadata) if !metadata.file_type().is_symlink() => {}
2932                            Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
2933                            _ => return Err(invalid()),
2934                        }
2935                    }
2936                    Err(_) => return Err(invalid()),
2937                }
2938            }
2939        }
2940    }
2941    Ok(normalized)
2942}
2943
2944/// Whether `name` places a file directly in the directory it is joined to. A
2945/// leading `./` is accepted; a backslash and a drive prefix are rejected on
2946/// every platform, so one build script behaves the same everywhere. A name
2947/// containing a NUL byte, which cannot name a file, is rejected too.
2948fn is_bare_file_name(name: &str) -> bool {
2949    let name = name.strip_prefix("./").unwrap_or(name);
2950    if name.contains('/') || name.contains('\\') || name.contains('\0') {
2951        return false;
2952    }
2953    if name.as_bytes().get(1) == Some(&b':')
2954        && name.as_bytes().first().is_some_and(u8::is_ascii_alphabetic)
2955    {
2956        return false;
2957    }
2958    // With the separators and the drive prefix ruled out, `name` is one
2959    // component: empty, `.`, `..`, or the file name itself.
2960    let mut components = Path::new(name).components();
2961    matches!(components.next(), Some(Component::Normal(_))) && components.next().is_none()
2962}
2963
2964impl Default for Config {
2965    fn default() -> Self {
2966        Self::new()
2967    }
2968}
2969
2970/// Normalize a user-supplied attribute-match path.
2971///
2972/// - Prepends `.` if absent so all stored paths are rooted.
2973/// - Trims trailing `.` so `".my.pkg."` and `".my.pkg"` behave identically
2974///   (trailing-dot patterns otherwise never match a real FQN).
2975/// - The bare catch-all `"."` is preserved as-is.
2976fn normalize_attr_path(mut path: String) -> String {
2977    if !path.starts_with('.') {
2978        path.insert(0, '.');
2979    }
2980    if path.len() > 1 {
2981        while path.ends_with('.') {
2982            path.pop();
2983        }
2984    }
2985    path
2986}
2987
2988/// The minor version of the compiler that builds the crate, if `RUSTC` names
2989/// one and it can be read.
2990fn rustc_minor_version() -> Option<u32> {
2991    let rustc = std::env::var_os("RUSTC")?;
2992    let output = std::process::Command::new(rustc)
2993        .arg("--version")
2994        .output()
2995        .ok()?;
2996    parse_rustc_minor_version(&String::from_utf8_lossy(&output.stdout))
2997}
2998
2999/// The minor version in the output of `rustc --version`, such as `75` in
3000/// `rustc 1.75.0 (82e1608df 2023-12-21)`.
3001fn parse_rustc_minor_version(version_output: &str) -> Option<u32> {
3002    version_output
3003        .split_whitespace()
3004        .nth(1)?
3005        .split('.')
3006        .nth(1)?
3007        .parse()
3008        .ok()
3009}
3010
3011/// Normalize a path-scoped rule's proto path: trim whitespace, prepend the
3012/// leading dot if absent, and strip trailing dots. Unlike
3013/// [`normalize_attr_path`], an entry that normalizes to empty (e.g. `"..."`)
3014/// is returned empty rather than collapsing to the `"."` catch-all — the
3015/// caller skips it, so `"."` stays the only global opt-in spelling.
3016fn normalize_override_path(path: &str) -> String {
3017    let mut path = path.trim().to_string();
3018    if path.is_empty() || path == "." {
3019        return path;
3020    }
3021    if !path.starts_with('.') {
3022        path.insert(0, '.');
3023    }
3024    while path.ends_with('.') {
3025        path.pop();
3026    }
3027    path
3028}
3029
3030/// Normalize the paths given to the field-rule builder method `method` with
3031/// [`normalize_override_path`]. An entry that normalizes to empty is skipped
3032/// with a `cargo:warning`.
3033fn field_rule_paths(method: &str, paths: &[impl AsRef<str>]) -> Vec<String> {
3034    paths
3035        .iter()
3036        .map(AsRef::as_ref)
3037        .filter_map(|raw| {
3038            let normalized = normalize_override_path(raw);
3039            if normalized.is_empty() {
3040                println!(
3041                    "cargo:warning=buffa: {method} path '{raw}' normalizes to empty \
3042                     and will be ignored"
3043                );
3044                return None;
3045            }
3046            Some(normalized)
3047        })
3048        .collect()
3049}
3050
3051/// Write `content` to `path` only if the file doesn't already exist with
3052/// identical content. Avoids bumping timestamps on unchanged files, which
3053/// prevents unnecessary downstream recompilation.
3054fn write_if_changed(path: &Path, content: &[u8]) -> std::io::Result<()> {
3055    if let Ok(existing) = std::fs::read(path) {
3056        if existing == content {
3057            return Ok(());
3058        }
3059    }
3060    std::fs::write(path, content)
3061}
3062
3063/// Invoke `protoc` to produce a `FileDescriptorSet` (serialized bytes).
3064fn invoke_protoc(
3065    files: &[PathBuf],
3066    includes: &[PathBuf],
3067) -> Result<Vec<u8>, Box<dyn std::error::Error>> {
3068    let protoc = std::env::var("PROTOC").unwrap_or_else(|_| "protoc".to_string());
3069
3070    let descriptor_file =
3071        tempfile::NamedTempFile::new().map_err(|e| format!("failed to create temp file: {}", e))?;
3072    let descriptor_path = descriptor_file.path().to_path_buf();
3073
3074    let mut cmd = Command::new(&protoc);
3075    cmd.arg("--include_imports");
3076    cmd.arg("--include_source_info");
3077    cmd.arg(format!(
3078        "--descriptor_set_out={}",
3079        descriptor_path.display()
3080    ));
3081
3082    for include in includes {
3083        cmd.arg(format!("--proto_path={}", include.display()));
3084    }
3085
3086    for file in files {
3087        cmd.arg(file.as_os_str());
3088    }
3089
3090    let output = cmd
3091        .output()
3092        .map_err(|e| format!("failed to run protoc ({}): {}", protoc, e))?;
3093
3094    if !output.status.success() {
3095        let stderr = String::from_utf8_lossy(&output.stderr);
3096        return Err(format!("protoc failed: {}", stderr).into());
3097    }
3098
3099    let bytes = std::fs::read(&descriptor_path)
3100        .map_err(|e| format!("failed to read descriptor set: {}", e))?;
3101
3102    Ok(bytes)
3103}
3104
3105/// Invoke `buf build` to produce a `FileDescriptorSet` (serialized bytes).
3106///
3107/// Requires a `buf.yaml` discoverable from the build script's cwd. Builds
3108/// the entire workspace — no `--path` filtering, because buf's `--path` flag
3109/// expects workspace-relative paths while `FileDescriptorProto.name` is
3110/// module-root-relative; passing user paths to both would be a contradiction.
3111/// Codegen filtering happens on our side via `files_to_generate` matching.
3112fn invoke_buf() -> Result<Vec<u8>, Box<dyn std::error::Error>> {
3113    // buf build includes SourceCodeInfo by default (there's an
3114    // --exclude-source-info flag to disable it), so proto comments
3115    // propagate to generated code without an explicit opt-in here.
3116    let output = Command::new("buf")
3117        .arg("build")
3118        .arg("--as-file-descriptor-set")
3119        .arg("-o")
3120        .arg("-")
3121        .output()
3122        .map_err(|e| format!("failed to run buf (is it installed and on PATH?): {e}"))?;
3123
3124    if !output.status.success() {
3125        let stderr = String::from_utf8_lossy(&output.stderr);
3126        return Err(
3127            format!("buf build failed (is buf.yaml present at crate root?): {stderr}").into(),
3128        );
3129    }
3130
3131    Ok(output.stdout)
3132}
3133
3134/// Emit `cargo:rerun-if-changed` directives for a buf workspace.
3135///
3136/// Runs `buf ls-files` to discover all proto files with workspace-relative
3137/// paths (which cargo can stat). Also watches `buf.yaml` and `buf.lock`
3138/// (the latter only if it exists — cargo treats a missing rerun-if-changed
3139/// path as always-dirty). Failure is non-fatal: worst case cargo reruns
3140/// every build.
3141fn emit_buf_rerun_if_changed() {
3142    println!("cargo:rerun-if-changed=buf.yaml");
3143    if Path::new("buf.lock").exists() {
3144        println!("cargo:rerun-if-changed=buf.lock");
3145    }
3146    match Command::new("buf").arg("ls-files").output() {
3147        Ok(out) if out.status.success() => {
3148            for line in String::from_utf8_lossy(&out.stdout).lines() {
3149                let path = line.trim();
3150                if !path.is_empty() {
3151                    println!("cargo:rerun-if-changed={path}");
3152                }
3153            }
3154        }
3155        _ => {
3156            // ls-files failed; cargo already knows about buf.yaml above.
3157            // If buf itself is missing, invoke_buf() will error clearly.
3158        }
3159    }
3160}
3161
3162/// Convert a filesystem proto path to the name protoc uses in the descriptor.
3163///
3164/// `FileDescriptorProto.name` is relative to the `--proto_path` include
3165/// directory. The name is what remains after the first include that is a
3166/// prefix of the file and leaves no `..` in the remainder: protoc refuses to
3167/// map a file through an include when the result would contain `..`, and
3168/// tries the next one. If no include qualifies, the name is the full path
3169/// (not just file_name — that would break nested proto directories).
3170/// Current-directory components and redundant separators are removed first,
3171/// as protoc does, without resolving symlinks or `..`.
3172fn proto_relative_name(file: &Path, includes: &[PathBuf]) -> String {
3173    let file = normalize_proto_path(file);
3174    let name = includes
3175        .iter()
3176        .find_map(|include| {
3177            let include = normalize_proto_path(include);
3178            // `.` contains every relative path and no rooted one. `has_root`
3179            // also covers a Windows path that starts at the root of the
3180            // current drive, which `is_absolute` reports as relative.
3181            if include.as_os_str().is_empty() && file.has_root() {
3182                return None;
3183            }
3184            file.strip_prefix(include).ok().filter(|name| {
3185                !name
3186                    .components()
3187                    .any(|component| component == Component::ParentDir)
3188            })
3189        })
3190        .unwrap_or(&file)
3191        .to_str()
3192        .unwrap_or("")
3193        .to_string();
3194    #[cfg(windows)]
3195    let name = name.replace('\\', "/");
3196    name
3197}
3198
3199fn normalize_proto_path(path: &Path) -> PathBuf {
3200    path.components()
3201        .filter(|component| *component != Component::CurDir)
3202        .collect()
3203}
3204
3205/// Files Cargo should watch for protoc-based builds.
3206///
3207/// `protoc --include_imports` records the full transitive import closure in
3208/// the descriptor set. Convert descriptor-relative names back to filesystem
3209/// paths under the configured include roots so edits to imported protos rerun
3210/// codegen even when `.files()` listed only the leaf proto. Imports resolved
3211/// from protoc's bundled includes (the well-known types) are not under any
3212/// configured root and are deliberately left unwatched — they ship with the
3213/// protoc binary and are not user-editable.
3214fn protoc_rerun_if_changed_paths(
3215    fds: &FileDescriptorSet,
3216    files: &[PathBuf],
3217    includes: &[PathBuf],
3218) -> Vec<PathBuf> {
3219    let mut paths: BTreeSet<PathBuf> = files.iter().cloned().collect();
3220    for file in &fds.file {
3221        if let Some(name) = file.name.as_deref() {
3222            if let Some(path) = resolve_descriptor_name_under_include(name, includes) {
3223                paths.insert(path);
3224            }
3225        }
3226    }
3227    paths.into_iter().collect()
3228}
3229
3230/// Map an include-relative descriptor name back to an on-disk path, trying
3231/// the include roots in `-I` order (matching protoc's own resolution).
3232/// Absolute or parent-traversing names are rejected outright; with no
3233/// include roots, the name is tried relative to the working directory.
3234fn resolve_descriptor_name_under_include(name: &str, includes: &[PathBuf]) -> Option<PathBuf> {
3235    let rel = Path::new(name);
3236    if rel.is_absolute()
3237        || rel
3238            .components()
3239            .any(|c| matches!(c, Component::ParentDir | Component::Prefix(_)))
3240    {
3241        return None;
3242    }
3243
3244    if includes.is_empty() {
3245        let path = PathBuf::from(rel);
3246        return path.exists().then_some(path);
3247    }
3248
3249    for include in includes {
3250        let path = include.join(rel);
3251        if path.exists() {
3252            return Some(path);
3253        }
3254    }
3255    None
3256}
3257
3258/// Generate the content of an include file that assembles generated `.rs`
3259/// files into a nested module tree matching the protobuf package hierarchy.
3260///
3261/// Each generated file is named like `my.package.file_name.rs`. The package
3262/// segments become `pub mod` wrappers, and the file is `include!`d inside
3263/// the innermost module.
3264///
3265/// For example, files `["foo.bar.rs", "foo.baz.rs"]` produce:
3266/// ```text
3267/// pub mod foo {
3268///     #[allow(unused_imports)]
3269///     use super::*;
3270///     include!(concat!(env!("OUT_DIR"), "/foo.bar.rs"));
3271///     include!(concat!(env!("OUT_DIR"), "/foo.baz.rs"));
3272/// }
3273/// ```
3274///
3275/// When `relative` is true (the caller set [`Config::out_dir`] explicitly),
3276/// `include!` directives use bare sibling paths (`include!("foo.bar.rs")`)
3277/// instead of the `env!("OUT_DIR")` prefix, so the include file works when
3278/// checked into the source tree and referenced via `mod`.
3279fn generate_include_file(entries: &[(String, String)], relative: bool) -> String {
3280    let mode = if relative {
3281        buffa_codegen::IncludeMode::Relative("")
3282    } else {
3283        buffa_codegen::IncludeMode::OutDir
3284    };
3285    // Inner-allow off: this output is consumed via `include!` from
3286    // user-authored `lib.rs`, where `#![allow(...)]` is not valid.
3287    buffa_codegen::generate_module_tree(entries, mode, false)
3288}
3289
3290#[cfg(test)]
3291mod tests {
3292    use super::*;
3293
3294    fn native_adapter_input() -> (Vec<u8>, adapters::AdapterConfig) {
3295        use buffa_codegen::generated::descriptor::{
3296            EnumDescriptorProto, EnumValueDescriptorProto, FileDescriptorProto,
3297        };
3298        let file = FileDescriptorProto {
3299            name: Some("mode.proto".into()),
3300            package: Some("p".into()),
3301            syntax: Some("proto3".into()),
3302            enum_type: vec![EnumDescriptorProto {
3303                name: Some("Mode".into()),
3304                value: vec![
3305                    EnumValueDescriptorProto {
3306                        name: Some("MODE_UNSPECIFIED".into()),
3307                        number: Some(0),
3308                        ..Default::default()
3309                    },
3310                    EnumValueDescriptorProto {
3311                        name: Some("MODE_MESSAGE".into()),
3312                        number: Some(1),
3313                        ..Default::default()
3314                    },
3315                ],
3316                ..Default::default()
3317            }],
3318            ..Default::default()
3319        };
3320        let config = adapters::AdapterConfig::from_json(br#"{"version":1,"selectors":[{
3321            "file":"native.rs","name":"NativeMode","wire":{"source":".p.Mode","rust_type":"crate::wire::Mode"},
3322            "error":{"rust_type":"crate::ContractError","value":"crate::ContractError::Invalid"},
3323            "variants":[{"source":"MODE_MESSAGE","name":"Message"}]
3324        }]}"#).unwrap();
3325        (buffa_codegen::encode_descriptor_set(&[file], &[]), config)
3326    }
3327
3328    #[test]
3329    fn native_adapters_are_written_outside_the_portable_include_tree() {
3330        let (bytes, adapters) = native_adapter_input();
3331        let directory = tempfile::tempdir().unwrap();
3332        Config::new()
3333            .descriptor_set_bytes(bytes)
3334            .files(&["mode.proto"])
3335            .adapters(adapters)
3336            .out_dir(directory.path())
3337            .include_file("tree.rs")
3338            .compile()
3339            .unwrap();
3340        assert!(directory.path().join("native.rs").is_file());
3341        let tree = std::fs::read_to_string(directory.path().join("tree.rs")).unwrap();
3342        assert!(!tree.contains("native.rs"));
3343        assert!(tree.contains("p.mod.rs"));
3344    }
3345
3346    #[test]
3347    fn native_include_collisions_fail_before_writing_any_output() {
3348        for include in ["native.rs", "NATIVE.rs", "./native.rs", "./NATIVE.rs"] {
3349            assert_native_include_collision(include, true);
3350        }
3351    }
3352
3353    fn assert_native_include_collision(include: &str, explicit_out_dir: bool) {
3354        let (bytes, adapters) = native_adapter_input();
3355        let directory = explicit_out_dir.then(|| tempfile::tempdir().unwrap());
3356        let path = directory.as_ref().map_or_else(
3357            || PathBuf::from(std::env::var_os("OUT_DIR").unwrap()),
3358            |dir| dir.path().to_owned(),
3359        );
3360        std::fs::create_dir_all(&path).unwrap();
3361        let preserved = path.join("native.rs");
3362        std::fs::write(&preserved, b"preserved adapter").unwrap();
3363        std::fs::write(path.join("p.rs"), b"preserved portable").unwrap();
3364        let mut config = Config::new()
3365            .descriptor_set_bytes(bytes)
3366            .files(&["mode.proto"])
3367            .adapters(adapters)
3368            .include_file(include);
3369        if explicit_out_dir {
3370            config = config.out_dir(&path);
3371        }
3372        let error = config.compile().unwrap_err();
3373        assert_eq!(
3374            error
3375                .downcast_ref::<adapters::AdapterError>()
3376                .unwrap()
3377                .reason,
3378            adapters::ErrorReason::DuplicateOutput
3379        );
3380        assert_eq!(std::fs::read(preserved).unwrap(), b"preserved adapter");
3381        assert_eq!(
3382            std::fs::read(path.join("p.rs")).unwrap(),
3383            b"preserved portable"
3384        );
3385        assert!(!path.join("p.mod.rs").exists());
3386        assert_eq!(std::fs::read_dir(&path).unwrap().count(), 2);
3387    }
3388
3389    #[test]
3390    fn native_include_out_dir_collision_child() {
3391        // OUT_DIR belongs to the child process so parallel tests never observe
3392        // a temporary change to their build environment.
3393        let Some(include) = std::env::var_os("NATIVE_COLLISION_INCLUDE") else {
3394            return;
3395        };
3396        assert_native_include_collision(include.to_str().unwrap(), false);
3397    }
3398
3399    #[test]
3400    fn native_include_out_dir_aliases_fail_before_writing() {
3401        let directory = tempfile::tempdir().unwrap();
3402        let output = directory.path().join("out");
3403        for include in [
3404            "././native.rs".to_owned(),
3405            "unused/../native.rs".to_owned(),
3406            "../out/NATIVE.rs".to_owned(),
3407            output.join("native.rs").to_str().unwrap().to_owned(),
3408        ] {
3409            let result = std::process::Command::new(std::env::current_exe().unwrap())
3410                .args(["--exact", "tests::native_include_out_dir_collision_child"])
3411                .env("OUT_DIR", &output)
3412                .env("NATIVE_COLLISION_INCLUDE", &include)
3413                .output()
3414                .unwrap();
3415            assert!(
3416                result.status.success(),
3417                "{include}: {}",
3418                String::from_utf8_lossy(&result.stdout)
3419            );
3420        }
3421    }
3422
3423    #[test]
3424    fn native_noncolliding_out_dir_include_child() {
3425        let Some(include) = std::env::var_os("NATIVE_VALID_INCLUDE") else {
3426            return;
3427        };
3428        let (bytes, adapters) = native_adapter_input();
3429        Config::new()
3430            .descriptor_set_bytes(bytes)
3431            .files(&["mode.proto"])
3432            .adapters(adapters)
3433            .include_file(include.to_str().unwrap())
3434            .compile()
3435            .unwrap();
3436        let output = PathBuf::from(std::env::var_os("OUT_DIR").unwrap());
3437        assert!(std::fs::read_to_string(output.join("native.rs"))
3438            .unwrap()
3439            .contains("pub enum NativeMode"));
3440        assert!(std::fs::read_to_string(output.join(include))
3441            .unwrap()
3442            .contains("p.mod.rs"));
3443    }
3444
3445    #[test]
3446    fn native_out_dir_includes_keep_distinct_destinations() {
3447        let directory = tempfile::tempdir().unwrap();
3448        let output = directory.path().join("out");
3449        let includes = vec![
3450            PathBuf::from("nested/tree.rs"),
3451            directory.path().join("separate/native.rs"),
3452        ];
3453        #[cfg(unix)]
3454        let includes = {
3455            let mut includes = includes;
3456            // `link/..` is the symlink target's parent, not the output
3457            // directory. A lexical reduction alone would reject this valid case.
3458            std::fs::create_dir_all(directory.path().join("target/child")).unwrap();
3459            std::fs::create_dir(&output).unwrap();
3460            std::os::unix::fs::symlink(directory.path().join("target/child"), output.join("link"))
3461                .unwrap();
3462            includes.push(PathBuf::from("link/../native.rs"));
3463            includes
3464        };
3465        for include in includes {
3466            let result = std::process::Command::new(std::env::current_exe().unwrap())
3467                .args([
3468                    "--exact",
3469                    "tests::native_noncolliding_out_dir_include_child",
3470                ])
3471                .env("OUT_DIR", &output)
3472                .env("NATIVE_VALID_INCLUDE", &include)
3473                .output()
3474                .unwrap();
3475            assert!(
3476                result.status.success(),
3477                "{include:?}: {}",
3478                String::from_utf8_lossy(&result.stdout)
3479            );
3480        }
3481    }
3482
3483    #[cfg(unix)]
3484    #[test]
3485    fn native_include_directory_symlink_alias_is_a_collision() {
3486        let directory = tempfile::tempdir().unwrap();
3487        let output = directory.path().join("out");
3488        std::fs::create_dir(&output).unwrap();
3489        let alias = directory.path().join("alias");
3490        std::os::unix::fs::symlink(&output, &alias).unwrap();
3491        let result = std::process::Command::new(std::env::current_exe().unwrap())
3492            .args(["--exact", "tests::native_include_out_dir_collision_child"])
3493            .env("OUT_DIR", &output)
3494            .env("NATIVE_COLLISION_INCLUDE", alias.join("native.rs"))
3495            .output()
3496            .unwrap();
3497        assert!(
3498            result.status.success(),
3499            "{}",
3500            String::from_utf8_lossy(&result.stdout)
3501        );
3502    }
3503
3504    #[cfg(unix)]
3505    #[test]
3506    fn native_include_dangling_symlink_is_rejected_before_any_writes() {
3507        let (bytes, adapters) = native_adapter_input();
3508        let directory = tempfile::tempdir().unwrap();
3509        let include = directory.path().join("tree.rs");
3510        std::os::unix::fs::symlink("native.rs", &include).unwrap();
3511        let portable = directory.path().join("p.rs");
3512        std::fs::write(&portable, b"preserved portable").unwrap();
3513        let error = Config::new()
3514            .descriptor_set_bytes(bytes)
3515            .files(&["mode.proto"])
3516            .adapters(adapters)
3517            .out_dir(directory.path())
3518            .include_file("tree.rs")
3519            .compile()
3520            .unwrap_err();
3521        assert_eq!(
3522            error
3523                .downcast_ref::<adapters::AdapterError>()
3524                .unwrap()
3525                .reason,
3526            adapters::ErrorReason::InvalidOutput
3527        );
3528        assert_eq!(std::fs::read(portable).unwrap(), b"preserved portable");
3529        assert_eq!(std::fs::read_link(include).unwrap(), Path::new("native.rs"));
3530        assert!(!directory.path().join("native.rs").exists());
3531        assert_eq!(std::fs::read_dir(directory.path()).unwrap().count(), 2);
3532    }
3533
3534    #[test]
3535    fn feature_name_setters_reach_codegen_config() {
3536        let config = Config::new()
3537            .json_feature_name("serde")
3538            .views_feature_name("zero-copy")
3539            .text_feature_name(String::from("textproto"))
3540            .reflect_feature_name("reflection")
3541            .codegen_config;
3542        let names = &config.feature_gate_names;
3543        assert_eq!(names.json, "serde");
3544        assert_eq!(names.views, "zero-copy");
3545        assert_eq!(names.text, "textproto");
3546        assert_eq!(names.reflect, "reflection");
3547    }
3548
3549    #[test]
3550    fn shared_descriptor_pool_requires_include_file() {
3551        // The shared root module has no home without an include file, so
3552        // compile() must reject the combination before doing any work.
3553        let err = Config::new()
3554            .generate_reflection(true)
3555            .shared_descriptor_pool(true)
3556            .out_dir("unused")
3557            .compile()
3558            .expect_err("shared_descriptor_pool without include_file must error");
3559        assert!(
3560            err.to_string().contains("include_file"),
3561            "error should name the missing include_file: {err}"
3562        );
3563    }
3564
3565    #[test]
3566    fn shared_descriptor_pool_setter_reaches_codegen_config() {
3567        let config = Config::new().shared_descriptor_pool(true).codegen_config;
3568        assert!(config.shared_descriptor_pool);
3569    }
3570
3571    #[test]
3572    fn shared_descriptor_pool_rejects_stemless_include_file() {
3573        // The sidecar is named after the include file's stem; a name without
3574        // one ("", ".", "..") must fail up front rather than writing a
3575        // misnamed stray sidecar before the include-file write errors.
3576        let err = Config::new()
3577            .generate_reflection(true)
3578            .shared_descriptor_pool(true)
3579            .include_file("..")
3580            .out_dir("unused")
3581            .compile()
3582            .expect_err("shared_descriptor_pool with a stemless include_file must error");
3583        assert!(
3584            err.to_string().contains("file name"),
3585            "error should name the degenerate include_file: {err}"
3586        );
3587    }
3588
3589    #[test]
3590    fn is_bare_file_name_accepts_names_in_the_joined_directory() {
3591        for name in ["gen_mod.rs", ".gen_mod.rs", "gen_mod", "./gen_mod.rs"] {
3592            assert!(is_bare_file_name(name), "{name:?} should be bare");
3593        }
3594    }
3595
3596    #[test]
3597    fn is_bare_file_name_rejects_paths_and_nul() {
3598        for name in [
3599            "",
3600            ".",
3601            "./",
3602            "..",
3603            "../gen_mod.rs",
3604            "nested/gen_mod.rs",
3605            "nested\\gen_mod.rs",
3606            "/gen_mod.rs",
3607            "C:gen_mod.rs",
3608            "gen_mod.rs/",
3609            "gen_mod.rs\0",
3610        ] {
3611            assert!(!is_bare_file_name(name), "{name:?} should not be bare");
3612        }
3613    }
3614
3615    #[test]
3616    fn shared_descriptor_pool_rejects_path_include_file() {
3617        let dir = tempfile::tempdir().unwrap();
3618        std::fs::create_dir(dir.path().join("nested")).unwrap();
3619
3620        let err = Config::new()
3621            .generate_reflection(true)
3622            .shared_descriptor_pool(true)
3623            .include_file("nested/gen_mod.rs")
3624            .descriptor_set_bytes(Vec::new())
3625            .out_dir(dir.path())
3626            .compile()
3627            .expect_err("shared descriptor include_file paths must be rejected");
3628        let message = err.to_string();
3629        assert!(
3630            message.contains("bare file name") && message.contains("sidecar"),
3631            "error should name the bare-file requirement and its reason: {message}"
3632        );
3633    }
3634
3635    #[test]
3636    fn shared_descriptor_pool_rejects_nul_include_file() {
3637        let dir = tempfile::tempdir().unwrap();
3638
3639        let err = Config::new()
3640            .generate_reflection(true)
3641            .shared_descriptor_pool(true)
3642            .include_file("gen_mod.rs\0")
3643            .descriptor_set_bytes(Vec::new())
3644            .out_dir(dir.path())
3645            .compile()
3646            .expect_err("shared descriptor include_file names must not contain NUL");
3647        let message = err.to_string();
3648        assert!(
3649            message.contains("bare file name") && message.contains("NUL"),
3650            "error should name the bare-file requirement and the NUL byte: {message}"
3651        );
3652        assert!(
3653            !message.contains("sidecar"),
3654            "a NUL name is not a path problem: {message}"
3655        );
3656    }
3657
3658    #[test]
3659    fn explicit_out_dir_rejects_nul_include_file() {
3660        let dir = tempfile::tempdir().unwrap();
3661
3662        let err = Config::new()
3663            .include_file("gen_mod.rs\0")
3664            .descriptor_set_bytes(Vec::new())
3665            .out_dir(dir.path())
3666            .compile()
3667            .expect_err("include_file names must not contain NUL");
3668        let message = err.to_string();
3669        assert!(
3670            message.contains("bare file name") && message.contains("NUL"),
3671            "error should name the bare-file requirement and the NUL byte: {message}"
3672        );
3673        assert!(
3674            !message.contains("relative to the include file"),
3675            "a NUL name is not a path problem: {message}"
3676        );
3677    }
3678
3679    #[test]
3680    fn shared_descriptor_pool_requires_reflection() {
3681        // Checked before include_file so the error names the first missing
3682        // prerequisite.
3683        let err = Config::new()
3684            .shared_descriptor_pool(true)
3685            .include_file("gen_mod.rs")
3686            .out_dir("unused")
3687            .compile()
3688            .expect_err("shared_descriptor_pool without reflection must error");
3689        assert!(
3690            err.to_string().contains("reflection"),
3691            "error should name the missing reflection prerequisite: {err}"
3692        );
3693    }
3694
3695    #[test]
3696    fn shared_descriptor_pool_writes_sidecar_and_shared_root() {
3697        use buffa_codegen::generated::descriptor::field_descriptor_proto::{Label, Type};
3698        use buffa_codegen::generated::descriptor::{
3699            DescriptorProto, FieldDescriptorProto, FileDescriptorProto,
3700        };
3701
3702        // A minimal one-package descriptor set, fed through descriptor_set()
3703        // so the test needs no protoc.
3704        let file = FileDescriptorProto {
3705            name: Some("foo/v1/thing.proto".into()),
3706            package: Some("foo.v1".into()),
3707            syntax: Some("proto3".into()),
3708            message_type: vec![DescriptorProto {
3709                name: Some("Thing".into()),
3710                field: vec![FieldDescriptorProto {
3711                    name: Some("id".into()),
3712                    number: Some(1),
3713                    label: Some(Label::LABEL_OPTIONAL),
3714                    r#type: Some(Type::TYPE_INT32),
3715                    ..Default::default()
3716                }],
3717                ..Default::default()
3718            }],
3719            ..Default::default()
3720        };
3721        let fds_bytes = buffa_codegen::encode_descriptor_set(std::slice::from_ref(&file), &[]);
3722
3723        let dir = tempfile::tempdir().unwrap();
3724        let fds_path = dir.path().join("set.binpb");
3725        std::fs::write(&fds_path, &fds_bytes).unwrap();
3726        let out = dir.path().join("gen");
3727
3728        Config::new()
3729            .descriptor_set(&fds_path)
3730            .files(&["foo/v1/thing.proto"])
3731            .out_dir(&out)
3732            .include_file("gen_mod.rs")
3733            .generate_reflection(true)
3734            .shared_descriptor_pool(true)
3735            .compile()
3736            .expect("shared-pool compile should succeed");
3737
3738        // The sidecar is named after the include file's stem and carries the
3739        // same bytes the generated code was built against.
3740        let sidecar = std::fs::read(out.join("gen_mod.descriptor_set.binpb"))
3741            .expect("sidecar must be written next to the include file");
3742        assert_eq!(sidecar, fds_bytes);
3743
3744        // The include file hosts the shared root and `include_bytes!`s the
3745        // sidecar (out_dir is explicit, so paths are include-file-relative)
3746        // instead of inlining the descriptor bytes as a source literal.
3747        let include = std::fs::read_to_string(out.join("gen_mod.rs")).unwrap();
3748        // The generated-file marker must stay on line 1 (first-line `@generated`
3749        // detection: rustfmt, diff-collapsing heuristics), with the shared root
3750        // module below it.
3751        assert!(
3752            include.starts_with("// @generated"),
3753            "include file must lead with the @generated marker: {include}"
3754        );
3755        assert!(include.contains("pub mod __buffa_fds"), "{include}");
3756        // (Two containment checks rather than one exact call text —
3757        // prettyplease may wrap the macro call across lines.)
3758        assert!(include.contains("include_bytes!"), "{include}");
3759        assert!(
3760            include.contains("\"gen_mod.descriptor_set.binpb\""),
3761            "{include}"
3762        );
3763        assert!(
3764            !include.contains("FILE_DESCRIPTOR_SET_BYTES: &[u8] = b\""),
3765            "sidecar mode must not inline the bytes: {include}"
3766        );
3767
3768        // The package's `__buffa::reflect` surface (authored by the package
3769        // stitcher) delegates to the shared root instead of embedding its own
3770        // copy of the descriptor set.
3771        let pkg = std::fs::read_to_string(out.join("foo.v1.mod.rs")).unwrap();
3772        assert!(
3773            pkg.contains("__buffa_fds"),
3774            "package reflect surface must delegate to the shared root: {pkg}"
3775        );
3776        assert!(
3777            !pkg.contains("FILE_DESCRIPTOR_SET_BYTES: &[u8] = b\""),
3778            "package must not embed its own descriptor copy: {pkg}"
3779        );
3780    }
3781
3782    #[test]
3783    fn box_type_in_normalizes_leading_dot() {
3784        // Without normalization a dotless path would silently match nothing,
3785        // and the exact-path Inline recursion error would never fire for it.
3786        let config = Config::new()
3787            .box_type_in(PointerRepr::Box, &["my.pkg.Msg.inner", ".my.pkg.Other"])
3788            .codegen_config;
3789        assert_eq!(
3790            config.pointer_fields,
3791            vec![
3792                (".my.pkg.Msg.inner".to_string(), PointerRepr::Box),
3793                (".my.pkg.Other".to_string(), PointerRepr::Box),
3794            ]
3795        );
3796    }
3797
3798    fn rule_paths<R>(rules: &[(String, R)]) -> Vec<&str> {
3799        rules.iter().map(|(path, _)| path.as_str()).collect()
3800    }
3801
3802    #[test]
3803    fn type_in_builders_normalize_paths() {
3804        // A missing leading dot, surrounding whitespace and a trailing dot
3805        // are normalized; a blank entry is skipped, so `"."` is the only
3806        // spelling of "every field".
3807        let paths = &["my.pkg.Msg.field", " .my.pkg.Other. ", ".", "", " ", "..."];
3808        let expected = [".my.pkg.Msg.field", ".my.pkg.Other", "."];
3809        let config = Config::new()
3810            .bytes_type_in(BytesRepr::Bytes, paths)
3811            .string_type_in(StringRepr::String, paths)
3812            .map_type_in(MapRepr::BTreeMap, paths)
3813            .repeated_type_in(RepeatedRepr::Vec, paths)
3814            .box_type_in(PointerRepr::Box, paths)
3815            .unbox_oneof_in(paths)
3816            .codegen_config;
3817
3818        assert_eq!(rule_paths(&config.bytes_fields), expected);
3819        assert_eq!(rule_paths(&config.string_fields), expected);
3820        assert_eq!(rule_paths(&config.map_fields), expected);
3821        assert_eq!(rule_paths(&config.repeated_fields), expected);
3822        assert_eq!(rule_paths(&config.pointer_fields), expected);
3823        assert_eq!(config.unboxed_oneof_fields, expected);
3824    }
3825
3826    #[test]
3827    fn bytes_alias_and_custom_in_builders_normalize_paths() {
3828        let config = Config::new()
3829            .use_bytes_type_in(&["my.pkg.A.data"])
3830            .bytes_type_custom_in("::my::Bytes", &["my.pkg.B.data"])
3831            .string_type_custom_in("::my::Str", &["my.pkg.C.name"])
3832            .map_type_custom_in("::my::Map", &["my.pkg.D.entries"])
3833            .repeated_type_custom_in("::my::List<*>", &["my.pkg.E.items"])
3834            .codegen_config;
3835        assert_eq!(config.bytes_fields[0].0, ".my.pkg.A.data");
3836        assert_eq!(config.bytes_fields[1].0, ".my.pkg.B.data");
3837        assert_eq!(config.string_fields[0].0, ".my.pkg.C.name");
3838        assert_eq!(config.map_fields[0].0, ".my.pkg.D.entries");
3839        assert_eq!(config.repeated_fields[0].0, ".my.pkg.E.items");
3840    }
3841
3842    #[test]
3843    fn unbox_oneof_in_normalizes_leading_dot() {
3844        // Without normalization a dotless path would silently match nothing,
3845        // and the exact-path recursion error would never fire for it.
3846        let config = Config::new()
3847            .unbox_oneof_in(&["my.pkg.Msg.body.small", ".my.pkg.Other"])
3848            .codegen_config;
3849        assert_eq!(
3850            config.unboxed_oneof_fields,
3851            vec![
3852                ".my.pkg.Msg.body.small".to_string(),
3853                ".my.pkg.Other".to_string()
3854            ]
3855        );
3856    }
3857
3858    #[test]
3859    fn skip_debug_normalizes_and_accumulates_paths() {
3860        let config = Config::new()
3861            .skip_debug(&["demo.Uuid4", ".demo.Level.", "..."])
3862            .skip_debug(&[" .demo.Other ", "."])
3863            .codegen_config;
3864        // `"..."` normalizes to empty and is dropped.
3865        assert_eq!(
3866            config.skip_debug,
3867            [".demo.Uuid4", ".demo.Level", ".demo.Other", "."]
3868        );
3869    }
3870
3871    #[test]
3872    fn deny_view_json_normalizes_and_accumulates_paths() {
3873        let config = Config::new()
3874            .deny_view_json(&["demo.Private.", " .demo.Other "])
3875            .deny_view_json(&["."])
3876            .codegen_config;
3877        assert_eq!(config.deny_view_json, [".demo.Private", ".demo.Other", "."]);
3878    }
3879
3880    #[test]
3881    fn codec_strategy_in_normalizes_paths_and_keeps_rule_order() {
3882        let config = Config::new()
3883            .codec_strategy(CodecStrategy::Table)
3884            .codec_strategy_in(CodecStrategy::Unrolled, &["my.pkg.Msg", ".my.pkg.Other."])
3885            .codec_strategy_in(CodecStrategy::Table, &[" .my.pkg.Msg.Inner ", "."])
3886            .codegen_config;
3887        assert_eq!(config.codec_strategy, CodecStrategy::Table);
3888        assert_eq!(
3889            config.codec_strategy_in,
3890            vec![
3891                (".my.pkg.Msg".to_string(), CodecStrategy::Unrolled),
3892                (".my.pkg.Other".to_string(), CodecStrategy::Unrolled),
3893                (".my.pkg.Msg.Inner".to_string(), CodecStrategy::Table),
3894                (".".to_string(), CodecStrategy::Table),
3895            ]
3896        );
3897    }
3898
3899    #[test]
3900    fn rustc_minor_version_is_read_from_the_version_line() {
3901        assert_eq!(
3902            parse_rustc_minor_version("rustc 1.75.0 (82e1608df 2023-12-21)"),
3903            Some(75)
3904        );
3905        assert_eq!(
3906            parse_rustc_minor_version("rustc 1.98.0-nightly (abc 2027-01-01)\n"),
3907            Some(98)
3908        );
3909        assert_eq!(parse_rustc_minor_version(""), None);
3910        assert_eq!(parse_rustc_minor_version("not rustc"), None);
3911    }
3912
3913    #[test]
3914    fn codec_strategy_defaults_to_unrolled() {
3915        let config = Config::new().codegen_config;
3916        assert_eq!(config.codec_strategy, CodecStrategy::Unrolled);
3917        assert!(config.codec_strategy_in.is_empty());
3918    }
3919
3920    #[test]
3921    fn deny_unknown_json_fields_in_normalizes_paths() {
3922        let config = Config::new()
3923            .deny_unknown_json_fields_in(&["demo.Config", ".demo.Other.", " .demo.Third ", "."])
3924            .codegen_config;
3925        // The global default is untouched by the path-scoped builder.
3926        assert!(!config.deny_unknown_json_fields);
3927        assert_eq!(
3928            config.deny_unknown_json_fields_in,
3929            vec![
3930                (".demo.Config".to_string(), true),
3931                (".demo.Other".to_string(), true),
3932                (".demo.Third".to_string(), true),
3933                (".".to_string(), true),
3934            ]
3935        );
3936    }
3937
3938    #[test]
3939    fn deny_unknown_json_fields_sets_the_global_flag() {
3940        assert!(
3941            Config::new()
3942                .deny_unknown_json_fields(true)
3943                .codegen_config
3944                .deny_unknown_json_fields
3945        );
3946    }
3947
3948    #[test]
3949    fn preserve_unknown_fields_in_normalizes_paths() {
3950        let config = Config::new()
3951            .preserve_unknown_fields(false)
3952            .preserve_unknown_fields_in(&[
3953                "wa.CallLogRecord",
3954                ".wa.SyncdMutation.",
3955                " .wa.Other ",
3956                ".",
3957            ])
3958            .codegen_config;
3959        assert!(!config.preserve_unknown_fields);
3960        assert_eq!(
3961            config.preserve_unknown_fields_in,
3962            vec![
3963                (".wa.CallLogRecord".to_string(), true),
3964                (".wa.SyncdMutation".to_string(), true),
3965                (".wa.Other".to_string(), true),
3966                (".".to_string(), true),
3967            ]
3968        );
3969    }
3970
3971    #[test]
3972    fn preserve_unknown_fields_in_empty_path_is_not_catchall() {
3973        // `""` and `"..."` must not collapse to the `"."` catch-all, which
3974        // would re-enable preservation for every message.
3975        let config = Config::new()
3976            .preserve_unknown_fields(false)
3977            .preserve_unknown_fields_in(&["", "   ", "...", ".wa.Keep"])
3978            .codegen_config;
3979        assert_eq!(
3980            config.preserve_unknown_fields_in,
3981            vec![(".wa.Keep".to_string(), true)]
3982        );
3983    }
3984
3985    #[test]
3986    fn open_enums_in_normalizes_paths() {
3987        // Without normalization, dotless or trailing-dot paths would silently
3988        // match nothing.
3989        let config = Config::new()
3990            .open_enums_in(&[
3991                "my.pkg.Status.",
3992                ".my.pkg.Msg.status",
3993                ".",
3994                "  my.pkg.Trimmed  ",
3995            ])
3996            .codegen_config;
3997        let paths: Vec<&str> = config
3998            .feature_overrides
3999            .iter()
4000            .map(|(p, _)| p.as_str())
4001            .collect();
4002        assert_eq!(
4003            paths,
4004            vec![
4005                ".my.pkg.Status",
4006                ".my.pkg.Msg.status",
4007                ".",
4008                ".my.pkg.Trimmed"
4009            ]
4010        );
4011        assert!(config
4012            .feature_overrides
4013            .iter()
4014            .all(|(_, o)| *o == FeatureOverride::EnumType(EnumTypeOverride::Open)));
4015    }
4016
4017    #[test]
4018    fn override_feature_in_accumulates_and_normalizes() {
4019        let config = Config::new()
4020            .override_feature_in(
4021                "my.pkg.Status.",
4022                FeatureOverride::EnumType(EnumTypeOverride::Open),
4023            )
4024            .override_feature_in(
4025                ".my.pkg.Msg.e",
4026                FeatureOverride::EnumType(EnumTypeOverride::Open),
4027            )
4028            .override_feature_in("...", FeatureOverride::EnumType(EnumTypeOverride::Open))
4029            .codegen_config;
4030        assert_eq!(
4031            config.feature_overrides,
4032            vec![
4033                (
4034                    ".my.pkg.Status".to_string(),
4035                    FeatureOverride::EnumType(EnumTypeOverride::Open)
4036                ),
4037                (
4038                    ".my.pkg.Msg.e".to_string(),
4039                    FeatureOverride::EnumType(EnumTypeOverride::Open)
4040                ),
4041            ]
4042        );
4043    }
4044
4045    #[test]
4046    fn open_enums_in_empty_path_is_not_catchall() {
4047        let config = Config::new()
4048            .open_enums_in(&["", "   ", "..."])
4049            .codegen_config;
4050        assert!(config.feature_overrides.is_empty());
4051    }
4052
4053    #[test]
4054    fn proto_relative_name_strips_include() {
4055        let got = proto_relative_name(
4056            Path::new("proto/my/service.proto"),
4057            &[PathBuf::from("proto/")],
4058        );
4059        assert_eq!(got, "my/service.proto");
4060    }
4061
4062    #[test]
4063    fn proto_relative_name_normalizes_current_directory_components() {
4064        for (file, includes, expected) in [
4065            (
4066                "./proto/my/service.proto",
4067                vec!["proto"],
4068                "my/service.proto",
4069            ),
4070            (
4071                "proto/my/service.proto",
4072                vec!["./proto"],
4073                "my/service.proto",
4074            ),
4075            (
4076                "./proto/my/service.proto",
4077                vec!["./proto"],
4078                "my/service.proto",
4079            ),
4080            (
4081                "proto/my/./service.proto",
4082                vec!["proto"],
4083                "my/service.proto",
4084            ),
4085            ("./my//pkg/./service.proto", vec![], "my/pkg/service.proto"),
4086            ("./my/pkg/service.proto", vec!["."], "my/pkg/service.proto"),
4087            ("my/pkg/service.proto", vec!["./."], "my/pkg/service.proto"),
4088            (
4089                "./my/pkg/service.proto",
4090                vec!["other"],
4091                "my/pkg/service.proto",
4092            ),
4093        ] {
4094            let includes = includes.into_iter().map(PathBuf::from).collect::<Vec<_>>();
4095            assert_eq!(proto_relative_name(Path::new(file), &includes), expected);
4096        }
4097    }
4098
4099    #[test]
4100    fn proto_relative_name_normalization_preserves_include_order() {
4101        let file = Path::new("./proto/vendor/./ext.proto");
4102        assert_eq!(
4103            proto_relative_name(
4104                file,
4105                &[PathBuf::from("./proto"), PathBuf::from("proto/vendor")]
4106            ),
4107            "vendor/ext.proto"
4108        );
4109        assert_eq!(
4110            proto_relative_name(
4111                file,
4112                &[PathBuf::from("./proto/vendor"), PathBuf::from("proto")]
4113            ),
4114            "ext.proto"
4115        );
4116    }
4117
4118    #[test]
4119    fn proto_relative_name_current_directory_include_contains_relative_files() {
4120        // `.` listed first names the file by its full relative path, even
4121        // when a later include is a closer match.
4122        assert_eq!(
4123            proto_relative_name(
4124                Path::new("proto/my/service.proto"),
4125                &[PathBuf::from("."), PathBuf::from("proto")]
4126            ),
4127            "proto/my/service.proto"
4128        );
4129    }
4130
4131    #[test]
4132    fn proto_relative_name_current_directory_does_not_match_absolute_path() {
4133        let root = std::env::current_dir().unwrap().join("proto");
4134        let file = root.join("my/service.proto");
4135        assert_eq!(
4136            proto_relative_name(&file, &[PathBuf::from("."), root]),
4137            "my/service.proto"
4138        );
4139    }
4140
4141    #[test]
4142    fn proto_relative_name_preserves_parent_directory_components() {
4143        assert_eq!(
4144            proto_relative_name(Path::new("./proto/../vendor/service.proto"), &[]),
4145            "proto/../vendor/service.proto"
4146        );
4147        assert_eq!(
4148            proto_relative_name(
4149                Path::new("./proto/../vendor/service.proto"),
4150                &[PathBuf::from("proto/../vendor")],
4151            ),
4152            "service.proto"
4153        );
4154    }
4155
4156    #[test]
4157    fn proto_relative_name_skips_prefixes_leaving_parent_components() {
4158        assert_eq!(
4159            proto_relative_name(
4160                Path::new("./proto/../vendor/service.proto"),
4161                &[
4162                    PathBuf::from("."),
4163                    PathBuf::from("proto"),
4164                    PathBuf::from("proto/../vendor"),
4165                ],
4166            ),
4167            "service.proto"
4168        );
4169    }
4170
4171    #[test]
4172    fn proto_relative_name_first_matching_prefix_wins() {
4173        let got = proto_relative_name(
4174            Path::new("proto/vendor/ext.proto"),
4175            &[PathBuf::from("proto/"), PathBuf::from("proto/vendor/")],
4176        );
4177        assert_eq!(got, "vendor/ext.proto");
4178        let got = proto_relative_name(
4179            Path::new("proto/vendor/ext.proto"),
4180            &[PathBuf::from("proto/vendor/"), PathBuf::from("proto/")],
4181        );
4182        assert_eq!(got, "ext.proto");
4183    }
4184
4185    #[test]
4186    fn proto_relative_name_skips_unmatched_prefixes() {
4187        let got = proto_relative_name(
4188            Path::new("proto/vendor/ext.proto"),
4189            &[
4190                PathBuf::from("unrelated"),
4191                PathBuf::from("proto/"),
4192                PathBuf::from("proto/vendor/"),
4193            ],
4194        );
4195        assert_eq!(got, "vendor/ext.proto");
4196    }
4197
4198    #[test]
4199    fn proto_relative_name_requires_a_complete_path_component() {
4200        let got = proto_relative_name(
4201            Path::new("proto/vendor2/ext.proto"),
4202            &[PathBuf::from("proto/vendor"), PathBuf::from("proto/")],
4203        );
4204        assert_eq!(got, "vendor2/ext.proto");
4205    }
4206
4207    #[cfg(windows)]
4208    #[test]
4209    fn proto_relative_name_normalizes_windows_separators() {
4210        let got = proto_relative_name(
4211            Path::new(r"C:\proto\vendor\ext.proto"),
4212            &[
4213                PathBuf::from(r"C:\proto"),
4214                PathBuf::from(r"C:\proto\vendor"),
4215            ],
4216        );
4217        assert_eq!(got, "vendor/ext.proto");
4218        let got = proto_relative_name(Path::new(r"vendor\ext.proto"), &[]);
4219        assert_eq!(got, "vendor/ext.proto");
4220    }
4221
4222    #[cfg(unix)]
4223    #[test]
4224    fn proto_relative_name_preserves_literal_backslashes() {
4225        let got = proto_relative_name(
4226            Path::new(r"proto/vendor\ext.proto"),
4227            &[PathBuf::from("proto")],
4228        );
4229        assert_eq!(got, r"vendor\ext.proto");
4230    }
4231
4232    #[test]
4233    fn proto_relative_name_no_match_returns_full_path() {
4234        // The fallback is the whole path: file_name() alone would drop the
4235        // directories that descriptor_set() mode needs for nested packages.
4236        let got = proto_relative_name(Path::new("my/pkg/service.proto"), &[]);
4237        assert_eq!(got, "my/pkg/service.proto");
4238    }
4239
4240    #[test]
4241    fn proto_relative_name_no_match_with_unrelated_includes() {
4242        let got = proto_relative_name(
4243            Path::new("src/my.proto"),
4244            &[PathBuf::from("other/"), PathBuf::from("third/")],
4245        );
4246        assert_eq!(got, "src/my.proto");
4247    }
4248
4249    #[test]
4250    fn protoc_rerun_paths_include_transitive_imports() {
4251        use buffa_codegen::generated::descriptor::FileDescriptorProto;
4252
4253        let dir = tempfile::tempdir().unwrap();
4254        let include = dir.path().join("proto");
4255        std::fs::create_dir_all(include.join("svc")).unwrap();
4256        std::fs::write(include.join("svc/service.proto"), b"syntax = \"proto3\";").unwrap();
4257        std::fs::write(include.join("common.proto"), b"syntax = \"proto3\";").unwrap();
4258
4259        let fds = FileDescriptorSet {
4260            file: vec![
4261                FileDescriptorProto {
4262                    name: Some("svc/service.proto".into()),
4263                    ..Default::default()
4264                },
4265                FileDescriptorProto {
4266                    name: Some("common.proto".into()),
4267                    ..Default::default()
4268                },
4269            ],
4270            ..Default::default()
4271        };
4272        let explicit = vec![include.join("svc/service.proto")];
4273
4274        let got: BTreeSet<_> =
4275            protoc_rerun_if_changed_paths(&fds, &explicit, std::slice::from_ref(&include))
4276                .into_iter()
4277                .collect();
4278        let expected: BTreeSet<_> = [
4279            include.join("svc/service.proto"),
4280            include.join("common.proto"),
4281        ]
4282        .into_iter()
4283        .collect();
4284        assert_eq!(got, expected);
4285    }
4286
4287    #[test]
4288    fn protoc_rerun_paths_skip_descriptor_names_not_under_include_roots() {
4289        use buffa_codegen::generated::descriptor::FileDescriptorProto;
4290
4291        let dir = tempfile::tempdir().unwrap();
4292        let include = dir.path().join("proto");
4293        std::fs::create_dir_all(&include).unwrap();
4294
4295        let fds = FileDescriptorSet {
4296            file: vec![
4297                FileDescriptorProto {
4298                    name: Some("missing.proto".into()),
4299                    ..Default::default()
4300                },
4301                FileDescriptorProto {
4302                    name: Some("../outside.proto".into()),
4303                    ..Default::default()
4304                },
4305            ],
4306            ..Default::default()
4307        };
4308        let explicit = vec![PathBuf::from("service.proto")];
4309
4310        assert_eq!(
4311            protoc_rerun_if_changed_paths(&fds, &explicit, &[include]),
4312            explicit
4313        );
4314    }
4315
4316    #[test]
4317    fn include_file_out_dir_mode_uses_env_var() {
4318        let entries = vec![
4319            ("foo.bar.rs".to_string(), "foo".to_string()),
4320            ("root.rs".to_string(), String::new()),
4321        ];
4322        let out = generate_include_file(&entries, false);
4323        assert!(
4324            out.contains(r#"include!(concat!(env!("OUT_DIR"), "/foo.bar.rs"));"#),
4325            "nested-package file should use env!(OUT_DIR): {out}"
4326        );
4327        assert!(
4328            out.contains(r#"include!(concat!(env!("OUT_DIR"), "/root.rs"));"#),
4329            "empty-package file should use env!(OUT_DIR): {out}"
4330        );
4331        assert!(!out.contains(r#"include!("foo.bar.rs")"#));
4332    }
4333
4334    #[test]
4335    fn include_file_relative_mode_uses_sibling_paths() {
4336        let entries = vec![
4337            ("foo.bar.rs".to_string(), "foo".to_string()),
4338            ("root.rs".to_string(), String::new()),
4339        ];
4340        let out = generate_include_file(&entries, true);
4341        assert!(
4342            out.contains(r#"include!("foo.bar.rs");"#),
4343            "nested-package file should use relative path: {out}"
4344        );
4345        assert!(
4346            out.contains(r#"include!("root.rs");"#),
4347            "empty-package file should use relative path: {out}"
4348        );
4349        assert!(
4350            !out.contains("OUT_DIR"),
4351            "relative mode must not reference OUT_DIR: {out}"
4352        );
4353    }
4354
4355    fn config_with_excluded_package() -> Config {
4356        use buffa_codegen::generated::descriptor::{DescriptorProto, FileDescriptorProto};
4357
4358        let file = FileDescriptorProto {
4359            name: Some("example.proto".into()),
4360            package: Some("example".into()),
4361            syntax: Some("proto3".into()),
4362            message_type: vec![DescriptorProto {
4363                name: Some("Message".into()),
4364                ..Default::default()
4365            }],
4366            ..Default::default()
4367        };
4368        Config::new()
4369            .descriptor_set_bytes(buffa_codegen::encode_descriptor_set(&[file], &[]))
4370            .files(&["example.proto"])
4371            .exclude_package("example")
4372    }
4373
4374    #[test]
4375    fn include_file_creates_output_directory_without_generated_files() {
4376        for config in [
4377            Config::new().descriptor_set_bytes(Vec::new()),
4378            config_with_excluded_package(),
4379        ] {
4380            let dir = tempfile::tempdir().unwrap();
4381            let out = dir.path().join("nested/gen");
4382            assert!(!out.exists());
4383
4384            config
4385                .out_dir(&out)
4386                .include_file("gen_mod.rs")
4387                .compile()
4388                .unwrap();
4389
4390            assert_eq!(
4391                std::fs::read_to_string(out.join("gen_mod.rs")).unwrap(),
4392                generate_include_file(&[], true)
4393            );
4394            assert_eq!(std::fs::read_dir(&out).unwrap().count(), 1);
4395        }
4396    }
4397
4398    #[test]
4399    fn shared_descriptor_pool_writes_output_without_generated_files() {
4400        let config = config_with_excluded_package();
4401        let DescriptorSource::Bytes(ref bytes) = config.descriptor_source else {
4402            unreachable!();
4403        };
4404        let expected_bytes = bytes.clone();
4405        let dir = tempfile::tempdir().unwrap();
4406        let out = dir.path().join("nested/gen");
4407
4408        config
4409            .out_dir(&out)
4410            .include_file("gen_mod.rs")
4411            .generate_reflection(true)
4412            .shared_descriptor_pool(true)
4413            .compile()
4414            .unwrap();
4415
4416        assert_eq!(
4417            std::fs::read(out.join("gen_mod.descriptor_set.binpb")).unwrap(),
4418            expected_bytes
4419        );
4420        let include = std::fs::read_to_string(out.join("gen_mod.rs")).unwrap();
4421        assert!(include.contains("pub mod __buffa_fds"), "{include}");
4422        assert!(
4423            include.contains("\"gen_mod.descriptor_set.binpb\""),
4424            "{include}"
4425        );
4426        assert_eq!(std::fs::read_dir(&out).unwrap().count(), 2);
4427    }
4428
4429    #[test]
4430    fn include_file_preserves_existing_directory_without_generated_files() {
4431        let dir = tempfile::tempdir().unwrap();
4432        let preserved = dir.path().join("existing.rs");
4433        std::fs::write(&preserved, b"existing content").unwrap();
4434
4435        config_with_excluded_package()
4436            .out_dir(dir.path())
4437            .include_file("gen_mod.rs")
4438            .compile()
4439            .unwrap();
4440
4441        assert_eq!(std::fs::read(&preserved).unwrap(), b"existing content");
4442        assert_eq!(
4443            std::fs::read_to_string(dir.path().join("gen_mod.rs")).unwrap(),
4444            generate_include_file(&[], true)
4445        );
4446    }
4447
4448    #[test]
4449    fn include_file_reports_output_directory_that_is_a_file() {
4450        let dir = tempfile::tempdir().unwrap();
4451        let out = dir.path().join("gen");
4452        std::fs::write(&out, b"existing content").unwrap();
4453
4454        let err = config_with_excluded_package()
4455            .out_dir(&out)
4456            .include_file("gen_mod.rs")
4457            .compile()
4458            .unwrap_err();
4459
4460        assert!(err.downcast_ref::<std::io::Error>().is_some(), "{err}");
4461        assert_eq!(std::fs::read(&out).unwrap(), b"existing content");
4462    }
4463
4464    #[test]
4465    fn compile_without_include_file_does_not_create_empty_output_directory() {
4466        let dir = tempfile::tempdir().unwrap();
4467        let out = dir.path().join("nested/gen");
4468
4469        config_with_excluded_package()
4470            .out_dir(&out)
4471            .compile()
4472            .unwrap();
4473
4474        assert!(!out.exists());
4475    }
4476
4477    #[test]
4478    fn include_file_relative_mode_nested_packages() {
4479        // Two files in the same depth-2 package: verifies the relative flag
4480        // propagates through recursive emit() calls and both files land in
4481        // the same innermost mod.
4482        let entries = vec![
4483            ("a.b.one.rs".to_string(), "a.b".to_string()),
4484            ("a.b.two.rs".to_string(), "a.b".to_string()),
4485        ];
4486        let out = generate_include_file(&entries, true);
4487        // Both includes should appear once, at the same depth-2 indent,
4488        // inside a single `pub mod b { ... }`.
4489        let indent = "        "; // depth 2 = 8 spaces
4490        assert!(
4491            out.contains(&format!(r#"{indent}include!("a.b.one.rs");"#)),
4492            "first file at depth 2: {out}"
4493        );
4494        assert!(
4495            out.contains(&format!(r#"{indent}include!("a.b.two.rs");"#)),
4496            "second file at depth 2: {out}"
4497        );
4498        assert_eq!(
4499            out.matches("pub mod b {").count(),
4500            1,
4501            "both files share one `mod b`: {out}"
4502        );
4503        assert!(!out.contains("OUT_DIR"));
4504    }
4505
4506    #[test]
4507    fn write_if_changed_creates_new_file() {
4508        let dir = tempfile::tempdir().unwrap();
4509        let path = dir.path().join("new.rs");
4510        write_if_changed(&path, b"hello").unwrap();
4511        assert_eq!(std::fs::read(&path).unwrap(), b"hello");
4512    }
4513
4514    #[test]
4515    fn write_if_changed_skips_identical_content() {
4516        let dir = tempfile::tempdir().unwrap();
4517        let path = dir.path().join("same.rs");
4518        std::fs::write(&path, b"content").unwrap();
4519        let mtime_before = std::fs::metadata(&path).unwrap().modified().unwrap();
4520
4521        // Sleep briefly so any write would produce a different mtime.
4522        std::thread::sleep(std::time::Duration::from_millis(50));
4523
4524        write_if_changed(&path, b"content").unwrap();
4525        let mtime_after = std::fs::metadata(&path).unwrap().modified().unwrap();
4526        assert_eq!(mtime_before, mtime_after);
4527    }
4528
4529    #[test]
4530    fn write_if_changed_overwrites_different_content() {
4531        let dir = tempfile::tempdir().unwrap();
4532        let path = dir.path().join("changed.rs");
4533        std::fs::write(&path, b"old").unwrap();
4534
4535        write_if_changed(&path, b"new").unwrap();
4536        assert_eq!(std::fs::read(&path).unwrap(), b"new");
4537    }
4538
4539    #[test]
4540    fn security_rule_normalization_never_turns_an_empty_path_into_a_catch_all() {
4541        let config = Config::new()
4542            .zeroize_in(&["", " . ", " demo.Record. "])
4543            .deny_view_json(&["", " . ", " demo.Record. "]);
4544        assert_eq!(
4545            config.codegen_config.zeroize_messages,
4546            ["", ".", ".demo.Record"]
4547        );
4548        assert_eq!(
4549            config.codegen_config.deny_view_json,
4550            ["", ".", ".demo.Record"]
4551        );
4552    }
4553
4554    #[test]
4555    fn normalize_attr_path_prepends_leading_dot() {
4556        assert_eq!(normalize_attr_path("my.pkg".into()), ".my.pkg");
4557    }
4558
4559    #[test]
4560    fn normalize_attr_path_preserves_leading_dot() {
4561        assert_eq!(normalize_attr_path(".my.pkg".into()), ".my.pkg");
4562    }
4563
4564    #[test]
4565    fn normalize_attr_path_trims_trailing_dot() {
4566        assert_eq!(normalize_attr_path("my.pkg.".into()), ".my.pkg");
4567        assert_eq!(normalize_attr_path(".my.pkg.".into()), ".my.pkg");
4568        assert_eq!(normalize_attr_path(".my.pkg...".into()), ".my.pkg");
4569    }
4570
4571    #[test]
4572    fn normalize_attr_path_preserves_catchall() {
4573        assert_eq!(normalize_attr_path(".".into()), ".");
4574        assert_eq!(normalize_attr_path("".into()), ".");
4575    }
4576
4577    #[test]
4578    fn type_attribute_forwards_normalized_path() {
4579        let cfg = Config::new().type_attribute("my.pkg.", "#[derive(Foo)]");
4580        assert_eq!(
4581            cfg.codegen_config.type_attributes,
4582            vec![(".my.pkg".to_string(), "#[derive(Foo)]".to_string())]
4583        );
4584    }
4585
4586    #[test]
4587    fn field_attribute_forwards_normalized_path() {
4588        let cfg = Config::new().field_attribute("pkg.Msg.f", "#[serde(skip)]");
4589        assert_eq!(
4590            cfg.codegen_config.field_attributes,
4591            vec![(".pkg.Msg.f".to_string(), "#[serde(skip)]".to_string())]
4592        );
4593    }
4594
4595    #[test]
4596    fn message_attribute_forwards_normalized_path() {
4597        let cfg = Config::new().message_attribute(".", "#[serde(default)]");
4598        assert_eq!(
4599            cfg.codegen_config.message_attributes,
4600            vec![(".".to_string(), "#[serde(default)]".to_string())]
4601        );
4602    }
4603
4604    #[test]
4605    fn enum_attribute_forwards_normalized_path() {
4606        let cfg = Config::new().enum_attribute("my.pkg.", "#[derive(strum::EnumIter)]");
4607        assert_eq!(
4608            cfg.codegen_config.enum_attributes,
4609            vec![(
4610                ".my.pkg".to_string(),
4611                "#[derive(strum::EnumIter)]".to_string(),
4612            )]
4613        );
4614        // Other attribute lists must remain untouched.
4615        assert!(cfg.codegen_config.type_attributes.is_empty());
4616        assert!(cfg.codegen_config.message_attributes.is_empty());
4617        assert!(cfg.codegen_config.field_attributes.is_empty());
4618    }
4619
4620    #[test]
4621    fn oneof_struct_field_attribute_forwards_normalized_path() {
4622        let cfg =
4623            Config::new().oneof_struct_field_attribute("my.pkg.Msg.payload.", "#[serde(skip)]");
4624        assert_eq!(
4625            cfg.codegen_config.oneof_struct_field_attributes,
4626            vec![(
4627                ".my.pkg.Msg.payload".to_string(),
4628                "#[serde(skip)]".to_string()
4629            )]
4630        );
4631        assert!(cfg.codegen_config.oneof_attributes.is_empty());
4632        assert!(cfg.codegen_config.field_attributes.is_empty());
4633        assert!(cfg.codegen_config.type_attributes.is_empty());
4634        assert!(cfg.codegen_config.message_attributes.is_empty());
4635        assert!(cfg.codegen_config.enum_attributes.is_empty());
4636    }
4637
4638    #[test]
4639    fn oneof_attribute_forwards_normalized_path() {
4640        let cfg = Config::new().oneof_attribute("my.pkg.Msg.payload.", "#[derive(Hash)]");
4641        assert_eq!(
4642            cfg.codegen_config.oneof_attributes,
4643            vec![(
4644                ".my.pkg.Msg.payload".to_string(),
4645                "#[derive(Hash)]".to_string()
4646            )]
4647        );
4648        // Other attribute lists must remain untouched.
4649        assert!(cfg.codegen_config.type_attributes.is_empty());
4650        assert!(cfg.codegen_config.enum_attributes.is_empty());
4651        assert!(cfg.codegen_config.message_attributes.is_empty());
4652        assert!(cfg.codegen_config.field_attributes.is_empty());
4653        assert!(cfg.codegen_config.oneof_struct_field_attributes.is_empty());
4654    }
4655
4656    #[test]
4657    fn attribute_calls_accumulate_in_insertion_order() {
4658        let cfg = Config::new()
4659            .type_attribute(".", "#[derive(A)]")
4660            .type_attribute(".pkg.M", "#[derive(B)]")
4661            .type_attribute(".", "#[derive(C)]");
4662        let paths: Vec<_> = cfg
4663            .codegen_config
4664            .type_attributes
4665            .iter()
4666            .map(|(_, a)| a.as_str())
4667            .collect();
4668        assert_eq!(paths, vec!["#[derive(A)]", "#[derive(B)]", "#[derive(C)]"]);
4669    }
4670
4671    #[test]
4672    fn descriptor_set_bytes_matches_file_input() {
4673        use buffa_codegen::generated::descriptor::field_descriptor_proto::{Label, Type};
4674        use buffa_codegen::generated::descriptor::{
4675            DescriptorProto, FieldDescriptorProto, FileDescriptorProto,
4676        };
4677
4678        let files = [
4679            FileDescriptorProto {
4680                name: Some("common/types.proto".into()),
4681                package: Some("common".into()),
4682                syntax: Some("proto3".into()),
4683                message_type: vec![DescriptorProto {
4684                    name: Some("Item".into()),
4685                    ..Default::default()
4686                }],
4687                ..Default::default()
4688            },
4689            FileDescriptorProto {
4690                name: Some("api/v1/service.proto".into()),
4691                package: Some("api.v1".into()),
4692                syntax: Some("proto3".into()),
4693                dependency: vec!["common/types.proto".into()],
4694                message_type: vec![DescriptorProto {
4695                    name: Some("Request".into()),
4696                    field: vec![FieldDescriptorProto {
4697                        name: Some("item".into()),
4698                        number: Some(1),
4699                        label: Some(Label::LABEL_OPTIONAL),
4700                        r#type: Some(Type::TYPE_MESSAGE),
4701                        type_name: Some(".common.Item".into()),
4702                        ..Default::default()
4703                    }],
4704                    ..Default::default()
4705                }],
4706                ..Default::default()
4707            },
4708        ];
4709        let bytes = buffa_codegen::encode_descriptor_set(&files, &[]);
4710        let dir = tempfile::tempdir().unwrap();
4711        let path = dir.path().join("set.binpb");
4712        std::fs::write(&path, &bytes).unwrap();
4713
4714        // The file and in-memory sources produce the same output, and
4715        // `descriptor_set_bytes` replaces a previously configured file or
4716        // `buf` source. No proto sources or external compiler are needed.
4717        let configs = [
4718            Config::new().descriptor_set(&path),
4719            Config::new()
4720                .descriptor_set(dir.path().join("missing.binpb"))
4721                .descriptor_set_bytes(bytes.clone()),
4722            Config::new().use_buf().descriptor_set_bytes(bytes),
4723        ];
4724        let mut outputs = Vec::new();
4725        for (i, config) in configs.into_iter().enumerate() {
4726            let out = dir.path().join(i.to_string());
4727            config
4728                .files(&["api/v1/service.proto"])
4729                // Must not strip this prefix from descriptor-relative names.
4730                .includes(&["api"])
4731                .out_dir(&out)
4732                .include_file("gen_mod.rs")
4733                .generate_reflection(true)
4734                .shared_descriptor_pool(true)
4735                .compile()
4736                .unwrap();
4737            let generated: std::collections::BTreeMap<_, _> = std::fs::read_dir(&out)
4738                .unwrap()
4739                .map(|entry| {
4740                    let entry = entry.unwrap();
4741                    (entry.file_name(), std::fs::read(entry.path()).unwrap())
4742                })
4743                .collect();
4744            let source = generated
4745                .values()
4746                .map(|bytes| String::from_utf8_lossy(bytes))
4747                .collect::<Vec<_>>()
4748                .join("\n");
4749            assert!(source.contains("pub struct Request"));
4750            assert!(!source.contains("pub struct Item"));
4751            outputs.push(generated);
4752        }
4753        assert_eq!(outputs[0], outputs[1]);
4754        assert_eq!(outputs[0], outputs[2]);
4755    }
4756
4757    #[test]
4758    fn descriptor_set_bytes_rejects_malformed_input() {
4759        let dir = tempfile::tempdir().unwrap();
4760        let out = dir.path().join("gen");
4761        let err = Config::new()
4762            .descriptor_set_bytes(vec![0xff])
4763            .out_dir(&out)
4764            .compile()
4765            .unwrap_err();
4766        assert!(err.to_string().contains("FileDescriptorSet"), "{err}");
4767        assert!(!out.exists(), "invalid input must not produce output");
4768    }
4769
4770    #[test]
4771    fn descriptor_set_bytes_can_be_replaced() {
4772        let cfg = Config::new().descriptor_set_bytes(Vec::new()).use_buf();
4773        assert!(matches!(cfg.descriptor_source, DescriptorSource::Buf));
4774
4775        let cfg = Config::new()
4776            .descriptor_set_bytes(Vec::new())
4777            .descriptor_set("set.binpb");
4778        assert!(matches!(
4779            cfg.descriptor_source,
4780            DescriptorSource::Precompiled(path) if path == Path::new("set.binpb")
4781        ));
4782    }
4783
4784    #[test]
4785    fn exclude_package_stores_raw_value_for_deferred_normalization() {
4786        // Normalization (leading-dot strip, validation) happens in
4787        // generate_with_diagnostics; the builder stores the raw string so
4788        // compile() can surface errors with the original user-supplied value.
4789        let cfg = Config::new()
4790            .exclude_package(".buf.validate")
4791            .exclude_package("gnostic");
4792        assert_eq!(
4793            cfg.codegen_config.exclude_packages,
4794            vec![".buf.validate", "gnostic"],
4795        );
4796    }
4797
4798    #[test]
4799    fn exclude_package_accumulates_in_order() {
4800        let cfg = Config::new()
4801            .exclude_package("a.b")
4802            .exclude_package("c.d")
4803            .exclude_package("e.f");
4804        assert_eq!(
4805            cfg.codegen_config.exclude_packages,
4806            vec!["a.b", "c.d", "e.f"]
4807        );
4808    }
4809
4810    #[test]
4811    fn exclude_package_rejects_malformed_entries_before_reading_input() {
4812        // The descriptor set path does not exist, so an error can only come
4813        // from the validation that runs ahead of any input processing.
4814        let err = Config::new()
4815            .descriptor_set("/nonexistent/set.binpb")
4816            .files(&["foo/v1/thing.proto"])
4817            .out_dir("/nonexistent/out")
4818            .exclude_package("buf..validate")
4819            .compile()
4820            .expect_err("malformed exclude_package must fail compile()");
4821        let msg = err.to_string();
4822        assert!(msg.contains("exclude_package \"buf..validate\""), "{msg}");
4823        assert!(msg.contains("empty components"), "{msg}");
4824    }
4825
4826    #[test]
4827    fn exclude_package_drops_the_package_from_the_output() {
4828        use buffa_codegen::generated::descriptor::field_descriptor_proto::{Label, Type};
4829        use buffa_codegen::generated::descriptor::{
4830            DescriptorProto, FieldDescriptorProto, FileDescriptorProto,
4831        };
4832
4833        // Two single-message packages, both listed for generation; the
4834        // excluded one must produce no module, no include entry, and no
4835        // stitcher.
4836        let file = |name: &str, package: &str, message: &str| FileDescriptorProto {
4837            name: Some(name.into()),
4838            package: Some(package.into()),
4839            syntax: Some("proto3".into()),
4840            message_type: vec![DescriptorProto {
4841                name: Some(message.into()),
4842                field: vec![FieldDescriptorProto {
4843                    name: Some("id".into()),
4844                    number: Some(1),
4845                    label: Some(Label::LABEL_OPTIONAL),
4846                    r#type: Some(Type::TYPE_INT32),
4847                    ..Default::default()
4848                }],
4849                ..Default::default()
4850            }],
4851            ..Default::default()
4852        };
4853        let files = [
4854            file("foo/v1/thing.proto", "foo.v1", "Thing"),
4855            file("buf/validate/validate.proto", "buf.validate", "Rule"),
4856        ];
4857        let fds_bytes = buffa_codegen::encode_descriptor_set(&files, &[]);
4858
4859        let dir = tempfile::tempdir().unwrap();
4860        let fds_path = dir.path().join("set.binpb");
4861        std::fs::write(&fds_path, &fds_bytes).unwrap();
4862        let out = dir.path().join("gen");
4863
4864        Config::new()
4865            .descriptor_set(&fds_path)
4866            .files(&["foo/v1/thing.proto", "buf/validate/validate.proto"])
4867            .out_dir(&out)
4868            .include_file("gen_mod.rs")
4869            .exclude_package(".buf.validate")
4870            .compile()
4871            .expect("compile with an excluded package should succeed");
4872
4873        let names: Vec<String> = std::fs::read_dir(&out)
4874            .unwrap()
4875            .map(|e| e.unwrap().file_name().to_string_lossy().into_owned())
4876            .collect();
4877        assert!(
4878            names.iter().any(|n| n.starts_with("foo.v1.")),
4879            "kept package must be generated: {names:?}"
4880        );
4881        assert!(
4882            !names.iter().any(|n| n.contains("buf.validate")),
4883            "excluded package must produce no files: {names:?}"
4884        );
4885        let include = std::fs::read_to_string(out.join("gen_mod.rs")).unwrap();
4886        assert!(include.contains("foo"), "{include}");
4887        assert!(!include.contains("validate"), "{include}");
4888    }
4889}