derive_defs/

lib.rs

//! # derive-defs
//!
//! Library for generating derive preset macros from TOML configuration.
//!
//! This crate provides functionality to parse TOML configuration files
//! and generate proc-macro code for derive attribute presets.
//!
//! ## How It Works
//!
//! `derive-defs` generates **proc-macro code** during the build process:
//!
//! 1. You define macro presets in `derive_defs.toml`
//! 2. During `cargo build`, the code generator creates Rust proc-macro implementations
//! 3. The generated code is written to `$OUT_DIR/derive_defs.rs`
//! 4. You include this code in your proc-macro crate using `include!`
//! 5. You use the generated macros in your library or binary code
//!
//! **Important**: Proc-macros can only be defined in a separate `proc-macro` type crate.
//! Binary crates **cannot** define and use proc-macros in the same crate.
//!
//! ## Project Setup Guide
//!
//! ### Scenario 1: Library Crate with Inline Macros
//!
//! **Use when**: Your library generates its own macros and exports them.
//!
//! **Structure:**
//! ```text
//! my-library/
//! ├── Cargo.toml              # [lib] proc-macro = true
//! ├── build.rs                # Generates macros
//! ├── derive_defs.toml        # Macro definitions
//! └── src/
//!     └── lib.rs              # Includes generated macros
//! ```
//!
//! **Cargo.toml:**
//! ```toml
//! [package]
//! name = "my-library"
//! version = "0.1.0"
//! edition = "2024"
//!
//! [lib]
//! proc-macro = true
//!
//! [dependencies]
//! proc-macro2 = "1"
//! quote = "1"
//! syn = { version = "2", features = ["full"] }
//!
//! [build-dependencies]
//! derive-defs = "0.1"
//! ```
//!
//! **build.rs:**
//! ```rust,no_run
//! fn main() {
//!     derive_defs::generate("derive_defs.toml")
//!         .expect("Failed to generate derive defs");
//! }
//! ```
//!
//! **src/lib.rs:**
//! ```rust,ignore
//! // Include the generated proc-macro code
//! include!(concat!(env!("OUT_DIR"), "/derive_defs.rs"));
//! ```
//!
//! ### Scenario 2: Binary Crate with Separate Macros Crate ⭐ RECOMMENDED
//!
//! **Use when**: You have a binary application that wants to use derive macros.
//!
//! **Important**: Binary crates cannot define proc-macros that they also use.
//! You must create a separate proc-macro crate in the workspace.
//!
//! **Structure:**
//! ```text
//! my-app/
//! ├── Cargo.toml              # [workspace] with members
//! ├── macros/                 # Proc-macro crate
//! │   ├── Cargo.toml          # [lib] proc-macro = true
//! │   ├── build.rs            # Generates macros
//! │   ├── derive_defs.toml    # Macro definitions
//! │   └── src/
//! │       └── lib.rs          # Includes generated macros
//! └── src/
//!     └── main.rs             # Uses macros from `macros` crate
//! ```
//!
//! **Root Cargo.toml:**
//! ```toml
//! [workspace]
//! members = ["macros", "src"]
//! resolver = "2"
//! ```
//!
//! **macros/Cargo.toml:**
//! ```toml
//! [package]
//! name = "my-app-macros"
//! version = "0.1.0"
//! edition = "2024"
//!
//! [lib]
//! proc-macro = true
//!
//! [dependencies]
//! proc-macro2 = "1"
//! quote = "1"
//! syn = { version = "2", features = ["full"] }
//!
//! [build-dependencies]
//! derive-defs = "0.1"
//! ```
//!
//! **macros/build.rs:**
//! ```rust,no_run
//! fn main() {
//!     derive_defs::generate("derive_defs.toml")
//!         .expect("Failed to generate derive defs");
//! }
//! ```
//!
//! **macros/src/lib.rs:**
//! ```rust,ignore
//! include!(concat!(env!("OUT_DIR"), "/derive_defs.rs"));
//! ```
//!
//! **`macros/derive_defs.toml`:**
//! ```toml
//! [defs.config]
//! traits = ["Debug", "Clone", "Default"]
//!
//! [defs.model]
//! traits = ["Debug", "Clone", "PartialEq"]
//! ```
//!
//! **src/Cargo.toml:**
//! ```toml
//! [package]
//! name = "my-app"
//! version = "0.1.0"
//! edition = "2024"
//!
//! [[bin]]
//! name = "my-app"
//! path = "main.rs"
//!
//! [dependencies]
//! my-app-macros = { path = "../macros" }
//! ```
//!
//! **src/main.rs:**
//! ```rust,ignore
//! use my_app_macros::{Config, Model};
//!
//! #[config]
//! struct AppConfig {
//!     host: String,
//!     port: u16,
//! }
//!
//! #[model]
//! struct User {
//!     name: String,
//!     age: u32,
//! }
//!
//! fn main() {
//!     let config = AppConfig {
//!         host: "localhost".to_string(),
//!         port: 8080,
//!     };
//!     println!("{:?}", config);
//! }
//! ```
//!
//! ### Why Separate Proc-Macro Crate?
//!
//! Rust's proc-macro system has a fundamental limitation: **proc-macros must be
//! defined in a separate crate** from where they are used. This is because:
//!
//! 1. Proc-macros are compiled before the rest of the crate
//! 2. A binary crate cannot simultaneously define and consume macros
//! 3. The macro expansion happens during compilation, not at runtime
//!
//! **Error you'll see if you try to use macros in the same binary crate:**
//! ```text
//! error: can't use a procedural macro from the same crate that defines it
//! ```
//!
//! **Solution**: Create a separate `macros` package in your workspace.
//!
//! ## Using `include!` vs `include_str!`
//!
//! This crate uses `include!` macro for the generated code:
//!
//! ```rust,ignore
//! include!(concat!(env!("OUT_DIR"), "/derive_defs.rs"));
//! ```
//!
//! - **`include!`**: Includes the file as Rust code (what we use)
//! - **`include_str!`**: Includes the file as a `&'static str` string
//!
//! The generated code must be included as Rust code because it contains
//! actual function definitions that the compiler needs to parse.
//!
//! ## Quick Start
//!
//! 1. Create a `derive_defs.toml` configuration file:
//!
//! ```toml
//! [defs.serialization]
//! traits = ["Clone", "Serialize", "Deserialize"]
//! attrs = ['#[serde(rename_all = "camelCase")]']
//!
//! [defs.model]
//! traits = ["Debug", "Clone", "PartialEq"]
//! ```
//!
//! 2. Add to your `build.rs`:
//!
//! ```rust,no_run
//! derive_defs::generate("derive_defs.toml")
//!     .expect("Failed to generate derive defs");
//! ```
//!
//! 3. Include generated code in your `lib.rs` (in the proc-macro crate):
//!
//! ```rust,ignore
//! include!(concat!(env!("OUT_DIR"), "/derive_defs.rs"));
//! ```
//!
//! 4. Use the generated macros in your code:
//!
//! ```rust,ignore
//! use my_crate_macros::*;
//!
//! #[serialization]
//! struct User {
//!     name: String,
//!     age: u32,
//! }
//! ```
//!
//! ## Features
//!
//! - **Declarative Configuration**: Define derive presets in TOML, not code
//! - **Inheritance**: Bundles can extend other bundles via `extends`
//! - **Cross-file Imports**: Split configuration across multiple files
//! - **Runtime Modification**: Use `omit`/`add` to modify bundles at use site
//!
//! ## TOML Configuration
//!
//! ### Basic Syntax
//!
//! ```toml
//! [defs.<name>]
//! traits = ["Trait1", "Trait2"]  # List of derive traits
//! attrs = ["#[attr]"]             # Additional attributes
//! extends = "<parent>"            # Inheritance (optional)
//! ```
//!
//! ### Inheritance
//!
//! ```toml
//! [defs.base]
//! traits = ["Debug", "Clone"]
//!
//! [defs.value_object]
//! extends = "base"
//! traits = ["PartialEq", "Eq", "Hash"]
//! # Result: Debug, Clone, PartialEq, Eq, Hash
//! ```
//!
//! ### Cross-file Imports
//!
//! ```toml
//! [includes]
//! common = "shared/common_defs.toml"
//!
//! [defs.api_response]
//! extends = "common.serialization"
//! traits = ["Default"]
//! ```
//!
//! ### Namespaced Definitions
//!
//! ```toml
//! [defs.cli.config]
//! traits = ["Debug", "Default"]
//!
//! [defs.cli.args]
//! traits = ["Debug", "Clone"]
//!
//! [defs.web.model]
//! traits = ["Debug", "Clone", "Serialize"]
//! ```
//!
//! Generates macros: `cli_config`, `cli_args`, `web_model`.
//!
//! ## API Usage
//!
//! ### Attribute Modifiers
//!
//! ```rust,ignore
//! // Basic usage
//! #[serialization]
//! struct User { ... }
//!
//! // Exclude Clone from the bundle
//! #[serialization(omit(Clone))]
//! struct Session { ... }
//!
//! // Add Default and Hash to the bundle
//! #[serialization(add(Default, Hash))]
//! struct Config { ... }
//!
//! // Exclude serde attributes
//! #[serialization(omit_attrs(serde))]
//! struct Internal { ... }
//!
//! // Combination
//! #[serialization(omit(Clone), add(Copy))]
//! struct Flags { ... }
//! ```
//!
//! ## Common Patterns
//!
//! ### Configuration Structs
//!
//! ```toml
//! [defs.config]
//! traits = ["Debug", "Clone", "Default"]
//! ```
//!
//! ```rust,ignore
//! #[config]
//! struct ServerConfig {
//!     host: String,
//!     port: u16,
//! }
//! ```
//!
//! ### Domain Models
//!
//! ```toml
//! [defs.model]
//! traits = ["Debug", "Clone", "PartialEq", "Eq"]
//! ```
//!
//! ```rust,ignore
//! #[model]
//! struct User {
//!     id: u32,
//!     name: String,
//! }
//! ```
//!
//! ### Serialization-Ready Types
//!
//! ```toml
//! [defs.serializable]
//! traits = ["Serialize", "Deserialize"]
//! attrs = ['#[serde(rename_all = "camelCase")]']
//! ```
//!
//! ```rust,ignore
//! #[serializable]
//! struct ApiResponse {
//!     status_code: u16,
//!     message: String,
//! }
//! ```
//!
//! ## Error Handling
//!
//! The crate provides clear error messages at `build.rs` time:
//!
//! - Circular inheritance detection
//! - Undefined parent references
//! - Missing include files
//! - Duplicate definition names
//!
//! ### Common Pitfalls
//!
//! **Error**: `can't use a procedural macro from the same crate that defines it`
//!
//! **Solution**: Binary crates cannot define and use proc-macros. Create a
//! separate `macros` crate in your workspace (see Scenario 2 above).

#![cfg_attr(docsrs, feature(doc_cfg))]
#![doc(
    html_logo_url = "https://raw.githubusercontent.com/opentc/rust-derive-defs/main/assets/logo.png"
)]
#![doc(
    html_favicon_url = "https://raw.githubusercontent.com/opentc/rust-derive-defs/main/assets/favicon.ico"
)]
#![allow(clippy::needless_doctest_main)]

use std::path::Path;

pub mod codegen;
pub mod includes;
pub mod parser;
pub mod resolver;
pub mod validation;

/// Errors that can occur during code generation.
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum Error {
    /// Failed to read the configuration file.
    #[error("failed to read config file: {0}")]
    ConfigRead(#[source] std::io::Error),

    /// Failed to parse TOML.
    #[error("failed to parse TOML: {0}")]
    TomlParse(#[source] toml::de::Error),

    /// Validation error.
    #[error("validation error: {0}")]
    Validation(String),

    /// Failed to write generated code.
    #[error("failed to write generated code: {0}")]
    CodegenWrite(#[source] std::io::Error),

    /// Circular dependency detected.
    #[error("circular extends detected: {0}")]
    CircularDependency(String),

    /// Reference to undefined definition.
    #[error("def \"{def}\" extends \"{parent}\" which is not defined")]
    UndefinedParent {
        /// The name of the definition with the invalid extends.
        def: String,
        /// The name of the undefined parent.
        parent: String,
    },

    /// Include file not found.
    #[error("include file \"{path}\" not found (resolved to {resolved})")]
    IncludeNotFound {
        /// The path as specified in the config.
        path: String,
        /// The resolved absolute path.
        resolved: String,
    },
}

/// Result type alias for this crate.
pub type Result<T> = std::result::Result<T, Error>;

/// Generate proc-macro code from a TOML configuration file.
///
/// This function parses the TOML configuration at `path` and generates
/// proc-macro code in the `OUT_DIR` directory. The generated code should
/// be included in your proc-macro crate.
///
/// # Errors
///
/// Returns an error if:
/// - The configuration file cannot be read
/// - The TOML is invalid
/// - There are validation errors (circular dependencies, undefined parents, etc.)
/// - The output file cannot be written
///
/// # Example
///
/// ```no_run
/// derive_defs::generate("derive_defs.toml")
///     .expect("Failed to generate derive defs");
/// ```
///
/// # Panics
///
/// This function panics if the `OUT_DIR` environment variable is not set.
/// This should only happen if called outside of a build script context.
pub fn generate<P: AsRef<Path>>(path: P) -> Result<()> {
    let path_ref = path.as_ref();

    // Validate that the crate type is compatible with proc-macro generation
    let manifest_dir = path_ref.parent().unwrap_or_else(|| Path::new("."));
    validation::validate_crate_type_for_macros(manifest_dir)?;

    let config = parser::parse_file(path_ref)?;
    let config = includes::resolve_includes(config, path_ref)?;
    let resolved = resolver::resolve(&config)?;
    codegen::generate(resolved)
}

/// Generate proc-macro code from a TOML configuration file with custom output path.
///
/// Similar to [`generate`], but allows specifying a custom output path instead
/// of using `OUT_DIR`.
///
/// # Errors
///
/// Same as [`generate`].
///
/// # Example
///
/// ```no_run
/// derive_defs::generate_to("derive_defs.toml", "/tmp/output.rs")
///     .expect("Failed to generate derive defs");
/// ```
pub fn generate_to<P: AsRef<Path>, O: AsRef<Path>>(path: P, output: O) -> Result<()> {
    let path_ref = path.as_ref();

    // Validate that the crate type is compatible with proc-macro generation
    let manifest_dir = path_ref.parent().unwrap_or_else(|| Path::new("."));
    validation::validate_crate_type_for_macros(manifest_dir)?;

    let config = parser::parse_file(path_ref)?;
    let config = includes::resolve_includes(config, path_ref)?;
    let resolved = resolver::resolve(&config)?;
    codegen::generate_to(resolved, output)
}

/// Generate proc-macro code from an already resolved configuration.
///
/// This is useful when you want to programmatically build a configuration
/// and generate code without reading from a file.
///
/// # Errors
///
/// Returns an error if writing the output file fails.
///
/// # Example
///
/// ```no_run
/// use derive_defs::resolver::{ResolvedConfig, ResolvedDef};
/// use std::collections::HashMap;
///
/// let mut defs = HashMap::new();
/// defs.insert("model".to_string(), ResolvedDef {
///     name: "model".to_string(),
///     traits: vec!["Debug".to_string(), "Clone".to_string()],
///     attrs: vec![],
/// });
///
/// let config = ResolvedConfig { defs };
/// derive_defs::generate_from_resolved(config, "/tmp/output.rs").unwrap();
/// ```
pub fn generate_from_resolved<O: AsRef<Path>>(
    resolved: resolver::ResolvedConfig,
    output: O,
) -> Result<()> {
    codegen::generate_to(resolved, output)
}

/// Common imports for convenience.
pub mod prelude {
    pub use crate::{Error, Result, generate, generate_to};
}

// Re-export validation types for users who want to do custom validation
pub use validation::{CrateType, detect_crate_type, validate_crate_type_for_macros};