buffa_build/

lib.rs

//! Build-time integration for buffa.
//!
//! Use this crate in your `build.rs` to compile `.proto` files into Rust code
//! at build time. Parses `.proto` files into a `FileDescriptorSet` (via
//! `protoc` or `buf`), then uses `buffa-codegen` to generate Rust source.
//!
//! # Example
//!
//! ```rust,ignore
//! // build.rs
//! fn main() {
//!     buffa_build::Config::new()
//!         .files(&["proto/my_service.proto"])
//!         .includes(&["proto/"])
//!         .compile()
//!         .unwrap();
//! }
//! ```
//!
//! # Requirements
//!
//! By default, requires `protoc` on the system PATH (or set via the `PROTOC`
//! environment variable) — the same as `prost-build` and `tonic-build`.
//!
//! If `protoc` is unavailable or outdated on your platform, `buf` can be
//! used instead — see [`Config::use_buf()`]. Alternatively, feed a
//! pre-compiled descriptor set via [`Config::descriptor_set()`].

use std::path::{Path, PathBuf};
use std::process::Command;

use buffa::Message;
use buffa_codegen::generated::descriptor::FileDescriptorSet;

use buffa_codegen::CodeGenConfig;

/// How to produce a `FileDescriptorSet` from `.proto` files.
#[derive(Debug, Clone, Default)]
enum DescriptorSource {
    /// Invoke `protoc` (default). Requires `protoc` on PATH or `PROTOC` env var.
    #[default]
    Protoc,
    /// Invoke `buf build --as-file-descriptor-set`. Requires `buf` on PATH.
    Buf,
    /// Read a pre-built `FileDescriptorSet` from a file.
    Precompiled(PathBuf),
}

/// Builder for configuring and running protobuf compilation.
pub struct Config {
    files: Vec<PathBuf>,
    includes: Vec<PathBuf>,
    out_dir: Option<PathBuf>,
    codegen_config: CodeGenConfig,
    descriptor_source: DescriptorSource,
    /// If set, generate a module-tree include file with this name in the
    /// output directory. Users can then `include!` this single file instead
    /// of manually setting up `pub mod` nesting.
    include_file: Option<String>,
}

impl Config {
    /// Create a new configuration with defaults.
    pub fn new() -> Self {
        Self {
            files: Vec::new(),
            includes: Vec::new(),
            out_dir: None,
            codegen_config: CodeGenConfig::default(),
            descriptor_source: DescriptorSource::default(),
            include_file: None,
        }
    }

    /// Add `.proto` files to compile.
    #[must_use]
    pub fn files(mut self, files: &[impl AsRef<Path>]) -> Self {
        self.files
            .extend(files.iter().map(|f| f.as_ref().to_path_buf()));
        self
    }

    /// Add include directories for protoc to search for imports.
    #[must_use]
    pub fn includes(mut self, includes: &[impl AsRef<Path>]) -> Self {
        self.includes
            .extend(includes.iter().map(|i| i.as_ref().to_path_buf()));
        self
    }

    /// Set the output directory for generated files.
    /// Defaults to `$OUT_DIR` if not set.
    #[must_use]
    pub fn out_dir(mut self, dir: impl Into<PathBuf>) -> Self {
        self.out_dir = Some(dir.into());
        self
    }

    /// Enable or disable view type generation (default: true).
    #[must_use]
    pub fn generate_views(mut self, enabled: bool) -> Self {
        self.codegen_config.generate_views = enabled;
        self
    }

    /// Enable or disable serde JSON generation (default: false).
    ///
    /// When enabled:
    /// - Generated message structs get `Serialize`/`Deserialize` derives.
    /// - Generated enum types get `Serialize`/`Deserialize` derives.
    /// - Generated view types (when `generate_views` is also enabled) get a
    ///   manual `impl Serialize` for zero-copy JSON serialization, so
    ///   `serde_json::to_string(&view)` works directly:
    ///
    ///   ```ignore
    ///   let view = MyMsgView::decode_view(&bytes)?;
    ///   let json = serde_json::to_string(&view)?;
    ///   ```
    ///
    /// The downstream crate must depend on `serde` and enable the `buffa/json`
    /// feature for the runtime helpers. When views are enabled, the crate must
    /// also enable `buffa-types/json` so the well-known type views implement
    /// `Serialize`; without it, references to e.g. `TimestampView<'_>` in the
    /// generated `Serialize` impl will fail with
    /// `the trait bound 'TimestampView<'_>: Serialize' is not satisfied`.
    ///
    /// **Limitations of the view `Serialize` impl:**
    /// - Extension fields are not included in view JSON output; serialize the
    ///   owned form (`view.to_owned_message()`) to include extensions.
    /// - The impl uses `serialize_map(None)` (unknown length) because the
    ///   number of emitted fields depends on default-omission rules. Most
    ///   self-describing serializers (notably `serde_json`) accept this, but
    ///   length-prefixed formats (e.g. `bincode`, `postcard`) will return a
    ///   runtime error. The owned types' derived `Serialize` does not have this
    ///   restriction.
    #[must_use]
    pub fn generate_json(mut self, enabled: bool) -> Self {
        self.codegen_config.generate_json = enabled;
        self
    }

    /// Enable or disable `impl buffa::text::TextFormat` on generated message
    /// structs (default: false).
    ///
    /// When enabled, the downstream crate must enable the `buffa/text`
    /// feature for the runtime textproto encoder/decoder.
    #[must_use]
    pub fn generate_text(mut self, enabled: bool) -> Self {
        self.codegen_config.generate_text = enabled;
        self
    }

    /// Enable or disable `#[derive(arbitrary::Arbitrary)]` on generated
    /// types (default: false).
    ///
    /// The derive is gated behind `#[cfg_attr(feature = "arbitrary", ...)]`
    /// so the downstream crate compiles with or without the feature enabled.
    ///
    /// Your crate's Cargo feature **must be named exactly `"arbitrary"`** —
    /// the generated `cfg_attr` uses that literal string and cannot be
    /// customised — and it must forward to `buffa/arbitrary`:
    ///
    /// ```toml
    /// [features]
    /// arbitrary = ["dep:arbitrary", "buffa/arbitrary"]
    /// ```
    ///
    /// Forgetting `"buffa/arbitrary"` produces a confusing
    /// `cannot find function 'arbitrary_bytes' in module '__private'` error
    /// in generated code when [`use_bytes_type`](Self::use_bytes_type) or
    /// [`use_bytes_type_in`](Self::use_bytes_type_in) is also enabled,
    /// because the helper that backs `#[arbitrary(with = ...)]` for
    /// `bytes::Bytes` fields lives in `buffa` under that feature gate.
    #[must_use]
    pub fn generate_arbitrary(mut self, enabled: bool) -> Self {
        self.codegen_config.generate_arbitrary = enabled;
        self
    }

    /// Wrap generated `impl`s in `#[cfg(feature = "...")]` instead of
    /// emitting them unconditionally (default: false).
    ///
    /// When enabled, the impls controlled by [`generate_json`],
    /// [`generate_views`], and [`generate_text`] are wrapped in
    /// `#[cfg(feature = "json" | "views" | "text")]` (or
    /// `#[cfg_attr(feature = ..., ...)]` for derives and field attributes)
    /// rather than emitted unconditionally. The crate consuming the
    /// generated code must define matching Cargo features that enable the
    /// corresponding runtime support:
    ///
    /// ```toml
    /// [features]
    /// json  = ["buffa/json", "dep:serde", "dep:serde_json"]
    /// views = []
    /// text  = ["buffa/text"]
    /// ```
    ///
    /// The `generate_*` flags still control *whether* an impl kind is
    /// emitted at all — this flag only controls whether it is `cfg`-gated.
    /// `generate_arbitrary` is always `cfg_attr`-gated on
    /// `feature = "arbitrary"` regardless of this flag, because `arbitrary`
    /// is an optional dependency by design.
    ///
    /// Reach for this when generated code is the **public interface of a
    /// library crate** consumed by downstream projects with different
    /// feature needs — exactly the shape of `buffa-descriptor` and
    /// `buffa-types`, which ship every impl while letting the codegen
    /// toolchain (`buffa-codegen`/`buffa-build`/`protoc-gen-buffa`) depend
    /// on them with `default-features = false` and stay free of
    /// `serde`/`serde_json`/`base64`. Most consumers of `buffa-build` are
    /// **not** in this position: a `build.rs` that decides at build-script
    /// time whether to generate JSON wants `impl Serialize` to just exist.
    /// Default `false`.
    ///
    /// [`generate_json`]: Self::generate_json
    /// [`generate_views`]: Self::generate_views
    /// [`generate_text`]: Self::generate_text
    #[must_use]
    pub fn gate_impls_on_crate_features(mut self, enabled: bool) -> Self {
        self.codegen_config.gate_impls_on_crate_features = enabled;
        self
    }

    /// Enable or disable `with_*` builder-style setter methods for
    /// explicit-presence fields (default: true).
    ///
    /// Each explicit-presence scalar, bytes, or enum field gets a
    /// `pub fn with_<name>(mut self, value: T) -> Self` method that wraps the
    /// value in `Some(...)` and returns `self`, enabling chained construction
    /// without the `Some(...)` boilerplate:
    ///
    /// ```ignore
    /// let req = MyRequest::default()
    ///     .with_name("alice")
    ///     .with_timeout_ms(30_000);
    /// ```
    ///
    /// String, bytes, and enum setters take `impl Into<T>` (so `&str`,
    /// `b"..."` literals, and bare enum variants work directly); other
    /// scalars take `T` to keep integer-literal inference unambiguous.
    ///
    /// Setters are pure inherent methods with no runtime dependency — they
    /// don't interact with the `json`/`views`/`text` feature gates. Disable
    /// only if you want to keep generated code minimal or have a competing
    /// `with_*` convention in your own crate.
    #[must_use]
    pub fn generate_with_setters(mut self, enabled: bool) -> Self {
        self.codegen_config.generate_with_setters = enabled;
        self
    }

    /// Enable or disable unknown field preservation (default: true).
    ///
    /// When enabled (the default), unrecognized fields encountered during
    /// decode are stored and re-emitted on encode — essential for proxy /
    /// middleware services and round-trip fidelity across schema versions.
    ///
    /// **Disabling is primarily a memory optimization** (24 bytes/message for
    /// the `UnknownFields` Vec header), not a throughput one. When no unknown
    /// fields appear on the wire — the common case for schema-aligned
    /// services — decode and encode costs are effectively identical in
    /// either mode. Consider disabling for embedded / `no_std` targets or
    /// large in-memory collections of small messages.
    #[must_use]
    pub fn preserve_unknown_fields(mut self, enabled: bool) -> Self {
        self.codegen_config.preserve_unknown_fields = enabled;
        self
    }

    /// Honor `features.utf8_validation = NONE` by emitting `Vec<u8>` / `&[u8]`
    /// for such string fields instead of `String` / `&str` (default: false).
    ///
    /// When disabled (the default), all string fields map to `String` and
    /// UTF-8 is validated on decode — stricter than proto2 requires, but
    /// ergonomic and safe.
    ///
    /// When enabled, string fields with `utf8_validation = NONE` become
    /// `Vec<u8>` / `&[u8]`. Decode skips validation; the caller chooses
    /// whether to `std::str::from_utf8` (checked) or `from_utf8_unchecked`
    /// (trusted-input fast path). This is the only sound Rust mapping when
    /// strings may actually contain non-UTF-8 bytes.
    ///
    /// **Note for proto2 users**: proto2's default is `utf8_validation = NONE`,
    /// so enabling this turns ALL proto2 string fields into `Vec<u8>`. Use
    /// only for new code or when profiling identifies UTF-8 validation as a
    /// bottleneck (it can be 10%+ of decode CPU for string-heavy messages).
    ///
    /// **JSON note**: fields normalized to bytes serialize as base64 in JSON
    /// (the proto3 JSON encoding for `bytes`). Keep strict mapping disabled
    /// for fields that need JSON string interop with other implementations.
    #[must_use]
    pub fn strict_utf8_mapping(mut self, enabled: bool) -> Self {
        self.codegen_config.strict_utf8_mapping = enabled;
        self
    }

    /// Permit `option message_set_wire_format = true` on input messages.
    ///
    /// MessageSet is a legacy Google-internal wire format. Default: `false`
    /// (such messages produce a codegen error). Set to `true` only when
    /// compiling protos that interoperate with old Google-internal services.
    #[must_use]
    pub fn allow_message_set(mut self, enabled: bool) -> Self {
        self.codegen_config.allow_message_set = enabled;
        self
    }

    /// Declare an external type path mapping.
    ///
    /// Types under the given protobuf path prefix will reference the specified
    /// Rust module path instead of being generated. This allows shared proto
    /// packages to be compiled once in a dedicated crate and referenced from
    /// others.
    ///
    /// `proto_path` is a fully-qualified protobuf package path, e.g.,
    /// `".my.common"` or `"my.common"` (the leading dot is optional and will
    /// be added automatically). `rust_path` is the Rust module path where
    /// those types are accessible (e.g., `"::common_protos"`).
    ///
    /// # Example
    ///
    /// ```rust,ignore
    /// buffa_build::Config::new()
    ///     .extern_path(".my.common", "::common_protos")
    ///     .files(&["proto/my_service.proto"])
    ///     .includes(&["proto/"])
    ///     .compile()
    ///     .unwrap();
    /// ```
    #[must_use]
    pub fn extern_path(
        mut self,
        proto_path: impl Into<String>,
        rust_path: impl Into<String>,
    ) -> Self {
        let mut proto_path = proto_path.into();
        // Normalize: ensure the proto path is fully-qualified (leading dot).
        // Accept both ".my.package" and "my.package" for convenience.
        if !proto_path.starts_with('.') {
            proto_path.insert(0, '.');
        }
        self.codegen_config
            .extern_paths
            .push((proto_path, rust_path.into()));
        self
    }

    /// Configure `bytes` fields to use `bytes::Bytes` instead of `Vec<u8>`.
    ///
    /// Each path is a fully-qualified proto path prefix. Use `"."` to apply
    /// to all bytes fields, or specify individual field paths like
    /// `".my.pkg.MyMessage.data"`.
    ///
    /// # Example
    ///
    /// ```rust,ignore
    /// buffa_build::Config::new()
    ///     .bytes(&["."])  // all bytes fields use Bytes
    ///     .files(&["proto/my_service.proto"])
    ///     .includes(&["proto/"])
    ///     .compile()
    ///     .unwrap();
    /// ```
    #[must_use]
    pub fn use_bytes_type_in(mut self, paths: &[impl AsRef<str>]) -> Self {
        self.codegen_config
            .bytes_fields
            .extend(paths.iter().map(|p| p.as_ref().to_string()));
        self
    }

    /// Use `bytes::Bytes` for all `bytes` fields in all messages.
    ///
    /// This is a convenience for `.use_bytes_type_in(&["."])`. Use `.use_bytes_type_in(&[...])` with
    /// specific proto paths if you only want `Bytes` for certain fields.
    #[must_use]
    pub fn use_bytes_type(mut self) -> Self {
        self.codegen_config.bytes_fields.push(".".to_string());
        self
    }

    /// Add a custom attribute to generated types (messages and enums)
    /// matching a proto path prefix.
    ///
    /// `path` is a fully-qualified proto path prefix: `"."` applies to all
    /// types, `".my.pkg"` to types in that package, `".my.pkg.MyMessage"`
    /// to a specific type. A leading `.` is auto-prepended if omitted; a
    /// trailing `.` is trimmed. Prefix matching respects proto-segment
    /// boundaries, so `".my.pk"` does not match `".my.pkg.Msg"`.
    ///
    /// `attribute` is a raw Rust attribute string
    /// (e.g., `"#[derive(serde::Serialize)]"`). A malformed attribute
    /// produces [`CodeGenError::InvalidCustomAttribute`](buffa_codegen::CodeGenError)
    /// at compile time rather than being silently dropped.
    ///
    /// Multiple calls accumulate in insertion order — all matching attributes
    /// are emitted, and ordering is preserved in generated code.
    ///
    /// Also applies to generated oneof enums when `path` matches
    /// `".pkg.Msg.my_oneof"` (the oneof's fully-qualified path).
    ///
    /// # Pitfalls
    ///
    /// buffa already emits `#[derive(Clone, PartialEq)]` on messages and
    /// `#[derive(Clone, PartialEq, Debug)]` on oneofs; adding a duplicate
    /// derive via `type_attribute(".", "#[derive(Clone)]")` produces a
    /// compile error in the generated code.
    ///
    /// # Example
    ///
    /// ```rust,ignore
    /// buffa_build::Config::new()
    ///     .type_attribute(".", "#[derive(serde::Serialize)]")
    ///     .type_attribute(".my.pkg.MyEnum", "#[derive(strum::EnumIter)]")
    ///     .files(&["proto/my_service.proto"])
    ///     .includes(&["proto/"])
    ///     .compile()
    ///     .unwrap();
    /// ```
    #[must_use]
    pub fn type_attribute(mut self, path: impl Into<String>, attribute: impl Into<String>) -> Self {
        self.codegen_config
            .type_attributes
            .push((normalize_attr_path(path.into()), attribute.into()));
        self
    }

    /// Add a custom attribute to generated struct fields matching a proto
    /// path prefix.
    ///
    /// `path` is a fully-qualified proto field path (e.g.,
    /// `".my.pkg.MyMessage.my_field"`). `"."` applies to all fields. A
    /// leading `.` is auto-prepended if omitted; a trailing `.` is trimmed.
    /// Prefix matching respects proto-segment boundaries.
    ///
    /// Also applies to oneof variants when `path` matches
    /// `".pkg.Msg.my_oneof.variant_name"`.
    ///
    /// # Example
    ///
    /// ```rust,ignore
    /// buffa_build::Config::new()
    ///     .field_attribute(".my.pkg.MyMessage.secret_key", "#[serde(skip)]")
    ///     .files(&["proto/my_service.proto"])
    ///     .includes(&["proto/"])
    ///     .compile()
    ///     .unwrap();
    /// ```
    #[must_use]
    pub fn field_attribute(
        mut self,
        path: impl Into<String>,
        attribute: impl Into<String>,
    ) -> Self {
        self.codegen_config
            .field_attributes
            .push((normalize_attr_path(path.into()), attribute.into()));
        self
    }

    /// Add a custom attribute to generated message structs only (not enums,
    /// not oneof enums) matching a proto path prefix.
    ///
    /// Same path-matching semantics as [`type_attribute`](Self::type_attribute) —
    /// leading `.` auto-prepended, trailing `.` trimmed, proto-segment-aware
    /// prefix matching, accumulation in insertion order. A malformed attribute
    /// produces a compile-time error. Useful for struct-only attributes like
    /// `#[serde(default)]`.
    ///
    /// # Example
    ///
    /// ```rust,ignore
    /// buffa_build::Config::new()
    ///     .message_attribute(".", "#[serde(default)]")
    ///     .files(&["proto/my_service.proto"])
    ///     .includes(&["proto/"])
    ///     .compile()
    ///     .unwrap();
    /// ```
    #[must_use]
    pub fn message_attribute(
        mut self,
        path: impl Into<String>,
        attribute: impl Into<String>,
    ) -> Self {
        self.codegen_config
            .message_attributes
            .push((normalize_attr_path(path.into()), attribute.into()));
        self
    }

    /// Add a custom attribute to generated enum types only (not message
    /// structs, not oneof enums) matching a proto path prefix.
    ///
    /// Same path-matching semantics as [`type_attribute`](Self::type_attribute) —
    /// leading `.` auto-prepended, trailing `.` trimmed, proto-segment-aware
    /// prefix matching, accumulation in insertion order. A malformed attribute
    /// produces a compile-time error. Useful when you want to inject an
    /// attribute on every enum in a package without also matching the
    /// (often more numerous) messages that share the path prefix — e.g.
    /// `#[derive(strum::EnumIter)]`, which only makes sense on enums.
    ///
    /// # Example
    ///
    /// ```rust,ignore
    /// buffa_build::Config::new()
    ///     .enum_attribute(".my.pkg", "#[derive(strum::EnumIter)]")
    ///     .files(&["proto/my_service.proto"])
    ///     .includes(&["proto/"])
    ///     .compile()
    ///     .unwrap();
    /// ```
    #[must_use]
    pub fn enum_attribute(mut self, path: impl Into<String>, attribute: impl Into<String>) -> Self {
        self.codegen_config
            .enum_attributes
            .push((normalize_attr_path(path.into()), attribute.into()));
        self
    }

    /// Use `buf build` instead of `protoc` for descriptor generation.
    ///
    /// `buf` is often easier to install and keep current than `protoc`
    /// (which many distros pin to old versions). This mode is intended for
    /// the **single-crate case**: a `buf.yaml` at the crate root defining
    /// the module layout.
    ///
    /// Requires `buf` on PATH and a `buf.yaml` at the crate root. The
    /// [`includes()`](Self::includes) setting is ignored — buf resolves
    /// imports via its own module configuration.
    ///
    /// Each path given to [`files()`](Self::files) must be **relative to its
    /// owning module's directory** (the `path:` value inside `buf.yaml`), not
    /// the crate root where `buf.yaml` itself lives. buf strips the module
    /// path when producing `FileDescriptorProto.name`, so for
    /// `modules: [{path: proto}]` and a file on disk at
    /// `proto/api/v1/service.proto`, the descriptor name is
    /// `api/v1/service.proto` — that is what `.files()` must contain.
    /// Multiple modules in one `buf.yaml` work fine; buf enforces that
    /// module-relative names are unique across the workspace.
    ///
    /// # Monorepo / multi-module setups
    ///
    /// For a workspace-root `buf.yaml` with many modules, this mode is a
    /// poor fit. Prefer running `buf generate` with the `protoc-gen-buffa`
    /// plugin and checking in the generated code, or use
    /// [`descriptor_set()`](Self::descriptor_set) with the output of
    /// `buf build --as-file-descriptor-set -o fds.binpb <module-path>`
    /// run as a pre-build step.
    ///
    /// # Example
    ///
    /// ```rust,ignore
    /// // buf.yaml (at crate root):
    /// //   version: v2
    /// //   modules:
    /// //     - path: proto
    /// //
    /// // build.rs:
    /// buffa_build::Config::new()
    ///     .use_buf()
    ///     .files(&["api/v1/service.proto"])  // relative to module root
    ///     .compile()
    ///     .unwrap();
    /// ```
    #[must_use]
    pub fn use_buf(mut self) -> Self {
        self.descriptor_source = DescriptorSource::Buf;
        self
    }

    /// Use a pre-compiled `FileDescriptorSet` binary file as input.
    ///
    /// Skips invoking `protoc` or `buf` entirely. The file must contain a
    /// serialized `google.protobuf.FileDescriptorSet` (as produced by
    /// `protoc --descriptor_set_out` or `buf build --as-file-descriptor-set`).
    ///
    /// When using this, `.files()` specifies which proto files in the
    /// descriptor set to generate code for (matching by proto file name).
    #[must_use]
    pub fn descriptor_set(mut self, path: impl Into<PathBuf>) -> Self {
        self.descriptor_source = DescriptorSource::Precompiled(path.into());
        self
    }

    /// Generate a module-tree include file alongside the per-package `.rs`
    /// files.
    ///
    /// The include file contains nested `pub mod` declarations with
    /// `include!()` directives that assemble the generated code into a
    /// module hierarchy matching the protobuf package structure. Users can
    /// then include this single file instead of manually creating the
    /// module tree.
    ///
    /// The form of the emitted `include!` directives depends on whether
    /// [`out_dir`](Self::out_dir) was set:
    ///
    /// - **Default (`$OUT_DIR`)**: emits
    ///   `include!(concat!(env!("OUT_DIR"), "/foo.rs"))`, for use from
    ///   `build.rs` via `include!(concat!(env!("OUT_DIR"), "/<name>"))`.
    /// - **Explicit `out_dir`**: emits sibling-relative `include!("foo.rs")`,
    ///   for checking the generated code into the source tree and referencing
    ///   it as a module (e.g. `mod gen;`).
    ///
    /// # Example — `build.rs` / `$OUT_DIR`
    ///
    /// ```rust,ignore
    /// // build.rs
    /// buffa_build::Config::new()
    ///     .files(&["proto/my_service.proto"])
    ///     .includes(&["proto/"])
    ///     .include_file("_include.rs")
    ///     .compile()
    ///     .unwrap();
    ///
    /// // lib.rs
    /// include!(concat!(env!("OUT_DIR"), "/_include.rs"));
    /// ```
    ///
    /// # Example — checked-in source
    ///
    /// ```rust,ignore
    /// // codegen.rs (run manually, not from build.rs)
    /// buffa_build::Config::new()
    ///     .files(&["proto/my_service.proto"])
    ///     .includes(&["proto/"])
    ///     .out_dir("src/gen")
    ///     .include_file("mod.rs")
    ///     .compile()
    ///     .unwrap();
    ///
    /// // lib.rs
    /// mod gen;
    /// ```
    #[must_use]
    pub fn include_file(mut self, name: impl Into<String>) -> Self {
        self.include_file = Some(name.into());
        self
    }

    /// Compile proto files and generate Rust source.
    ///
    /// # Errors
    ///
    /// Returns an error if:
    /// - `OUT_DIR` is not set and no `out_dir` was configured
    /// - `protoc` or `buf` cannot be found on `PATH` (when using those sources)
    /// - the proto compiler exits with a non-zero status (syntax errors,
    ///   missing imports, etc.)
    /// - a precompiled descriptor set file cannot be read
    /// - the descriptor set bytes cannot be decoded as a `FileDescriptorSet`
    /// - code generation fails (e.g. unsupported proto feature)
    /// - the output directory cannot be created or written to
    pub fn compile(self) -> Result<(), Box<dyn std::error::Error>> {
        // When out_dir is explicitly set, the include file should use
        // relative `include!("foo.rs")` paths (the index is a sibling of the
        // generated files). When defaulted to $OUT_DIR, keep the
        // `concat!(env!("OUT_DIR"), ...)` form so that
        // `include!(concat!(env!("OUT_DIR"), "/_include.rs"))` from src/
        // still resolves to absolute paths.
        let relative_includes = self.out_dir.is_some();
        let out_dir = self
            .out_dir
            .or_else(|| std::env::var("OUT_DIR").ok().map(PathBuf::from))
            .ok_or("OUT_DIR not set and no out_dir configured")?;

        // Produce a FileDescriptorSet from the configured source.
        let descriptor_bytes = match &self.descriptor_source {
            DescriptorSource::Protoc => invoke_protoc(&self.files, &self.includes)?,
            DescriptorSource::Buf => invoke_buf()?,
            DescriptorSource::Precompiled(path) => std::fs::read(path).map_err(|e| {
                format!("failed to read descriptor set '{}': {}", path.display(), e)
            })?,
        };
        let fds = FileDescriptorSet::decode_from_slice(&descriptor_bytes)
            .map_err(|e| format!("failed to decode FileDescriptorSet: {}", e))?;

        // Determine which files were explicitly requested.
        //
        // `FileDescriptorProto.name` contains the path relative to the proto
        // source root (protoc: `--proto_path`; buf: the module root). For
        // Precompiled and Buf mode, `.files()` are expected to already be
        // proto-relative names. For Protoc mode, strip the longest matching
        // include prefix.
        let files_to_generate: Vec<String> = if matches!(
            self.descriptor_source,
            DescriptorSource::Precompiled(_) | DescriptorSource::Buf
        ) {
            self.files
                .iter()
                .filter_map(|f| f.to_str().map(str::to_string))
                .collect()
        } else {
            self.files
                .iter()
                .map(|f| proto_relative_name(f, &self.includes))
                .filter(|s| !s.is_empty())
                .collect()
        };

        // Generate Rust source. Per-proto content files plus a per-package
        // `.mod.rs` stitcher; only the stitchers need wiring into the
        // module tree (content files are reached via `include!` from
        // there).
        let generated =
            buffa_codegen::generate(&fds.file, &files_to_generate, &self.codegen_config)?;

        // Write output files; collect (name, package) for PackageMod entries.
        let mut output_entries: Vec<(String, String)> = Vec::new();
        for file in generated {
            let path = out_dir.join(&file.name);
            if let Some(parent) = path.parent() {
                std::fs::create_dir_all(parent)?;
            }
            write_if_changed(&path, file.content.as_bytes())?;
            if file.kind == buffa_codegen::GeneratedFileKind::PackageMod {
                output_entries.push((file.name, file.package));
            }
        }

        // Generate the include file if requested.
        if let Some(ref include_name) = self.include_file {
            let include_content = generate_include_file(&output_entries, relative_includes);
            let include_path = out_dir.join(include_name);
            write_if_changed(&include_path, include_content.as_bytes())?;
        }

        // Tell cargo to re-run if any proto file changes.
        //
        // For Buf mode, `self.files` are module-root-relative and cargo can't
        // stat them — use `buf ls-files` instead, which lists all workspace
        // protos with workspace-relative paths. This also catches changes to
        // transitively-imported protos (a gap in the Protoc mode, which only
        // watches explicitly-listed files).
        match self.descriptor_source {
            DescriptorSource::Buf => emit_buf_rerun_if_changed(),
            DescriptorSource::Protoc => {
                // Rerun if PROTOC changes (different binary may accept
                // protos the previous one rejected, e.g. newer editions).
                println!("cargo:rerun-if-env-changed=PROTOC");
                for proto_file in &self.files {
                    println!("cargo:rerun-if-changed={}", proto_file.display());
                }
            }
            DescriptorSource::Precompiled(ref path) => {
                println!("cargo:rerun-if-changed={}", path.display());
            }
        }

        Ok(())
    }
}

impl Default for Config {
    fn default() -> Self {
        Self::new()
    }
}

/// Normalize a user-supplied attribute-match path.
///
/// - Prepends `.` if absent so all stored paths are rooted.
/// - Trims trailing `.` so `".my.pkg."` and `".my.pkg"` behave identically
///   (trailing-dot patterns otherwise never match a real FQN).
/// - The bare catch-all `"."` is preserved as-is.
fn normalize_attr_path(mut path: String) -> String {
    if !path.starts_with('.') {
        path.insert(0, '.');
    }
    if path.len() > 1 {
        while path.ends_with('.') {
            path.pop();
        }
    }
    path
}

/// Write `content` to `path` only if the file doesn't already exist with
/// identical content. Avoids bumping timestamps on unchanged files, which
/// prevents unnecessary downstream recompilation.
fn write_if_changed(path: &Path, content: &[u8]) -> std::io::Result<()> {
    if let Ok(existing) = std::fs::read(path) {
        if existing == content {
            return Ok(());
        }
    }
    std::fs::write(path, content)
}

/// Invoke `protoc` to produce a `FileDescriptorSet` (serialized bytes).
fn invoke_protoc(
    files: &[PathBuf],
    includes: &[PathBuf],
) -> Result<Vec<u8>, Box<dyn std::error::Error>> {
    let protoc = std::env::var("PROTOC").unwrap_or_else(|_| "protoc".to_string());

    let descriptor_file =
        tempfile::NamedTempFile::new().map_err(|e| format!("failed to create temp file: {}", e))?;
    let descriptor_path = descriptor_file.path().to_path_buf();

    let mut cmd = Command::new(&protoc);
    cmd.arg("--include_imports");
    cmd.arg("--include_source_info");
    cmd.arg(format!(
        "--descriptor_set_out={}",
        descriptor_path.display()
    ));

    for include in includes {
        cmd.arg(format!("--proto_path={}", include.display()));
    }

    for file in files {
        cmd.arg(file.as_os_str());
    }

    let output = cmd
        .output()
        .map_err(|e| format!("failed to run protoc ({}): {}", protoc, e))?;

    if !output.status.success() {
        let stderr = String::from_utf8_lossy(&output.stderr);
        return Err(format!("protoc failed: {}", stderr).into());
    }

    let bytes = std::fs::read(&descriptor_path)
        .map_err(|e| format!("failed to read descriptor set: {}", e))?;

    Ok(bytes)
}

/// Invoke `buf build` to produce a `FileDescriptorSet` (serialized bytes).
///
/// Requires a `buf.yaml` discoverable from the build script's cwd. Builds
/// the entire workspace — no `--path` filtering, because buf's `--path` flag
/// expects workspace-relative paths while `FileDescriptorProto.name` is
/// module-root-relative; passing user paths to both would be a contradiction.
/// Codegen filtering happens on our side via `files_to_generate` matching.
fn invoke_buf() -> Result<Vec<u8>, Box<dyn std::error::Error>> {
    // buf build includes SourceCodeInfo by default (there's an
    // --exclude-source-info flag to disable it), so proto comments
    // propagate to generated code without an explicit opt-in here.
    let output = Command::new("buf")
        .arg("build")
        .arg("--as-file-descriptor-set")
        .arg("-o")
        .arg("-")
        .output()
        .map_err(|e| format!("failed to run buf (is it installed and on PATH?): {e}"))?;

    if !output.status.success() {
        let stderr = String::from_utf8_lossy(&output.stderr);
        return Err(
            format!("buf build failed (is buf.yaml present at crate root?): {stderr}").into(),
        );
    }

    Ok(output.stdout)
}

/// Emit `cargo:rerun-if-changed` directives for a buf workspace.
///
/// Runs `buf ls-files` to discover all proto files with workspace-relative
/// paths (which cargo can stat). Also watches `buf.yaml` and `buf.lock`
/// (the latter only if it exists — cargo treats a missing rerun-if-changed
/// path as always-dirty). Failure is non-fatal: worst case cargo reruns
/// every build.
fn emit_buf_rerun_if_changed() {
    println!("cargo:rerun-if-changed=buf.yaml");
    if Path::new("buf.lock").exists() {
        println!("cargo:rerun-if-changed=buf.lock");
    }
    match Command::new("buf").arg("ls-files").output() {
        Ok(out) if out.status.success() => {
            for line in String::from_utf8_lossy(&out.stdout).lines() {
                let path = line.trim();
                if !path.is_empty() {
                    println!("cargo:rerun-if-changed={path}");
                }
            }
        }
        _ => {
            // ls-files failed; cargo already knows about buf.yaml above.
            // If buf itself is missing, invoke_buf() will error clearly.
        }
    }
}

/// Convert a filesystem proto path to the name protoc uses in the descriptor.
///
/// `FileDescriptorProto.name` is relative to the `--proto_path` include
/// directory. This strips the longest matching include prefix; if no include
/// matches, returns the path as-is (not just file_name — that would break
/// nested proto directories).
fn proto_relative_name(file: &Path, includes: &[PathBuf]) -> String {
    // Longest prefix wins: a file under both "proto/" and "proto/vendor/"
    // should strip "proto/vendor/" for a correct relative name.
    let mut best: Option<&Path> = None;
    for include in includes {
        if let Ok(rel) = file.strip_prefix(include) {
            match best {
                Some(prev) if prev.as_os_str().len() <= rel.as_os_str().len() => {}
                _ => best = Some(rel),
            }
        }
    }
    best.unwrap_or(file).to_str().unwrap_or("").to_string()
}

/// Generate the content of an include file that assembles generated `.rs`
/// files into a nested module tree matching the protobuf package hierarchy.
///
/// Each generated file is named like `my.package.file_name.rs`. The package
/// segments become `pub mod` wrappers, and the file is `include!`d inside
/// the innermost module.
///
/// For example, files `["foo.bar.rs", "foo.baz.rs"]` produce:
/// ```text
/// pub mod foo {
///     #[allow(unused_imports)]
///     use super::*;
///     include!(concat!(env!("OUT_DIR"), "/foo.bar.rs"));
///     include!(concat!(env!("OUT_DIR"), "/foo.baz.rs"));
/// }
/// ```
///
/// When `relative` is true (the caller set [`Config::out_dir`] explicitly),
/// `include!` directives use bare sibling paths (`include!("foo.bar.rs")`)
/// instead of the `env!("OUT_DIR")` prefix, so the include file works when
/// checked into the source tree and referenced via `mod`.
fn generate_include_file(entries: &[(String, String)], relative: bool) -> String {
    let mode = if relative {
        buffa_codegen::IncludeMode::Relative("")
    } else {
        buffa_codegen::IncludeMode::OutDir
    };
    // Inner-allow off: this output is consumed via `include!` from
    // user-authored `lib.rs`, where `#![allow(...)]` is not valid.
    buffa_codegen::generate_module_tree(entries, mode, false)
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn proto_relative_name_strips_include() {
        let got = proto_relative_name(
            Path::new("proto/my/service.proto"),
            &[PathBuf::from("proto/")],
        );
        assert_eq!(got, "my/service.proto");
    }

    #[test]
    fn proto_relative_name_longest_prefix_wins() {
        // Overlapping includes: file under both proto/ and proto/vendor/.
        // Must strip the LONGER prefix for the correct relative name.
        let got = proto_relative_name(
            Path::new("proto/vendor/ext.proto"),
            &[PathBuf::from("proto/"), PathBuf::from("proto/vendor/")],
        );
        assert_eq!(got, "ext.proto");
        // Same with reversed include order.
        let got = proto_relative_name(
            Path::new("proto/vendor/ext.proto"),
            &[PathBuf::from("proto/vendor/"), PathBuf::from("proto/")],
        );
        assert_eq!(got, "ext.proto");
    }

    #[test]
    fn proto_relative_name_no_match_returns_full_path() {
        // Regression: previously fell back to file_name(), which stripped
        // directory components and broke descriptor_set() mode with nested
        // proto packages. Now returns the full path as-is.
        let got = proto_relative_name(Path::new("my/pkg/service.proto"), &[]);
        assert_eq!(got, "my/pkg/service.proto");
    }

    #[test]
    fn proto_relative_name_no_match_with_unrelated_includes() {
        let got = proto_relative_name(
            Path::new("src/my.proto"),
            &[PathBuf::from("other/"), PathBuf::from("third/")],
        );
        assert_eq!(got, "src/my.proto");
    }

    #[test]
    fn include_file_out_dir_mode_uses_env_var() {
        let entries = vec![
            ("foo.bar.rs".to_string(), "foo".to_string()),
            ("root.rs".to_string(), String::new()),
        ];
        let out = generate_include_file(&entries, false);
        assert!(
            out.contains(r#"include!(concat!(env!("OUT_DIR"), "/foo.bar.rs"));"#),
            "nested-package file should use env!(OUT_DIR): {out}"
        );
        assert!(
            out.contains(r#"include!(concat!(env!("OUT_DIR"), "/root.rs"));"#),
            "empty-package file should use env!(OUT_DIR): {out}"
        );
        assert!(!out.contains(r#"include!("foo.bar.rs")"#));
    }

    #[test]
    fn include_file_relative_mode_uses_sibling_paths() {
        let entries = vec![
            ("foo.bar.rs".to_string(), "foo".to_string()),
            ("root.rs".to_string(), String::new()),
        ];
        let out = generate_include_file(&entries, true);
        assert!(
            out.contains(r#"include!("foo.bar.rs");"#),
            "nested-package file should use relative path: {out}"
        );
        assert!(
            out.contains(r#"include!("root.rs");"#),
            "empty-package file should use relative path: {out}"
        );
        assert!(
            !out.contains("OUT_DIR"),
            "relative mode must not reference OUT_DIR: {out}"
        );
    }

    #[test]
    fn include_file_relative_mode_nested_packages() {
        // Two files in the same depth-2 package: verifies the relative flag
        // propagates through recursive emit() calls and both files land in
        // the same innermost mod.
        let entries = vec![
            ("a.b.one.rs".to_string(), "a.b".to_string()),
            ("a.b.two.rs".to_string(), "a.b".to_string()),
        ];
        let out = generate_include_file(&entries, true);
        // Both includes should appear once, at the same depth-2 indent,
        // inside a single `pub mod b { ... }`.
        let indent = "        "; // depth 2 = 8 spaces
        assert!(
            out.contains(&format!(r#"{indent}include!("a.b.one.rs");"#)),
            "first file at depth 2: {out}"
        );
        assert!(
            out.contains(&format!(r#"{indent}include!("a.b.two.rs");"#)),
            "second file at depth 2: {out}"
        );
        assert_eq!(
            out.matches("pub mod b {").count(),
            1,
            "both files share one `mod b`: {out}"
        );
        assert!(!out.contains("OUT_DIR"));
    }

    #[test]
    fn write_if_changed_creates_new_file() {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("new.rs");
        write_if_changed(&path, b"hello").unwrap();
        assert_eq!(std::fs::read(&path).unwrap(), b"hello");
    }

    #[test]
    fn write_if_changed_skips_identical_content() {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("same.rs");
        std::fs::write(&path, b"content").unwrap();
        let mtime_before = std::fs::metadata(&path).unwrap().modified().unwrap();

        // Sleep briefly so any write would produce a different mtime.
        std::thread::sleep(std::time::Duration::from_millis(50));

        write_if_changed(&path, b"content").unwrap();
        let mtime_after = std::fs::metadata(&path).unwrap().modified().unwrap();
        assert_eq!(mtime_before, mtime_after);
    }

    #[test]
    fn write_if_changed_overwrites_different_content() {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("changed.rs");
        std::fs::write(&path, b"old").unwrap();

        write_if_changed(&path, b"new").unwrap();
        assert_eq!(std::fs::read(&path).unwrap(), b"new");
    }

    #[test]
    fn normalize_attr_path_prepends_leading_dot() {
        assert_eq!(normalize_attr_path("my.pkg".into()), ".my.pkg");
    }

    #[test]
    fn normalize_attr_path_preserves_leading_dot() {
        assert_eq!(normalize_attr_path(".my.pkg".into()), ".my.pkg");
    }

    #[test]
    fn normalize_attr_path_trims_trailing_dot() {
        assert_eq!(normalize_attr_path("my.pkg.".into()), ".my.pkg");
        assert_eq!(normalize_attr_path(".my.pkg.".into()), ".my.pkg");
        assert_eq!(normalize_attr_path(".my.pkg...".into()), ".my.pkg");
    }

    #[test]
    fn normalize_attr_path_preserves_catchall() {
        assert_eq!(normalize_attr_path(".".into()), ".");
        assert_eq!(normalize_attr_path("".into()), ".");
    }

    #[test]
    fn type_attribute_forwards_normalized_path() {
        let cfg = Config::new().type_attribute("my.pkg.", "#[derive(Foo)]");
        assert_eq!(
            cfg.codegen_config.type_attributes,
            vec![(".my.pkg".to_string(), "#[derive(Foo)]".to_string())]
        );
    }

    #[test]
    fn field_attribute_forwards_normalized_path() {
        let cfg = Config::new().field_attribute("pkg.Msg.f", "#[serde(skip)]");
        assert_eq!(
            cfg.codegen_config.field_attributes,
            vec![(".pkg.Msg.f".to_string(), "#[serde(skip)]".to_string())]
        );
    }

    #[test]
    fn message_attribute_forwards_normalized_path() {
        let cfg = Config::new().message_attribute(".", "#[serde(default)]");
        assert_eq!(
            cfg.codegen_config.message_attributes,
            vec![(".".to_string(), "#[serde(default)]".to_string())]
        );
    }

    #[test]
    fn enum_attribute_forwards_normalized_path() {
        let cfg = Config::new().enum_attribute("my.pkg.", "#[derive(strum::EnumIter)]");
        assert_eq!(
            cfg.codegen_config.enum_attributes,
            vec![(
                ".my.pkg".to_string(),
                "#[derive(strum::EnumIter)]".to_string(),
            )]
        );
        // Other attribute lists must remain untouched.
        assert!(cfg.codegen_config.type_attributes.is_empty());
        assert!(cfg.codegen_config.message_attributes.is_empty());
        assert!(cfg.codegen_config.field_attributes.is_empty());
    }

    #[test]
    fn attribute_calls_accumulate_in_insertion_order() {
        let cfg = Config::new()
            .type_attribute(".", "#[derive(A)]")
            .type_attribute(".pkg.M", "#[derive(B)]")
            .type_attribute(".", "#[derive(C)]");
        let paths: Vec<_> = cfg
            .codegen_config
            .type_attributes
            .iter()
            .map(|(_, a)| a.as_str())
            .collect();
        assert_eq!(paths, vec!["#[derive(A)]", "#[derive(B)]", "#[derive(C)]"]);
    }
}