masterror-derive 0.12.0

Derive macros for masterror
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136

// SPDX-FileCopyrightText: 2025 RAprogramm <andrey.rozanov.vl@gmail.com>
//
// SPDX-License-Identifier: MIT

//! Masterror derive macro implementation.
//!
//! This module provides the core implementation for the `#[derive(Masterror)]`
//! macro, which generates `From` trait implementations converting error types
//! into `masterror::Error` along with protocol mappings (HTTP, gRPC, Problem
//! JSON).
//!
//! # Architecture
//!
//! The implementation is split into specialized modules:
//!
//! - [`conversion`] - Core `From` trait implementation generation
//! - [`mapping`] - Protocol mapping constant generation
//! - [`binding`] - Field destructuring and binding logic
//! - [`attachment`] - Error context attachment (source, backtrace, metadata)
//!
//! # Example
//!
//! ```ignore
//! use masterror::Masterror;
//!
//! #[derive(Masterror)]
//! #[masterror(
//!     code = "AUTH_001",
//!     category = ErrorCategory::Authentication,
//!     map_grpc = "tonic::Code::Unauthenticated"
//! )]
//! struct AuthError {
//!     message: String,
//! }
//! ```

use proc_macro2::TokenStream;
use syn::Error;

use crate::input::{ErrorData, ErrorInput, StructData, VariantData};

pub mod attachment;
pub mod binding;
pub mod conversion;
pub mod mapping;

use conversion::{
    ensure_all_variants_have_masterror, enum_conversion_impl, struct_conversion_impl
};
use mapping::{enum_mapping_impl, struct_mapping_impl};

/// Main entry point for Masterror derive macro expansion.
///
/// Dispatches to struct or enum-specific implementations based on the input
/// type structure.
///
/// # Arguments
///
/// * `input` - The parsed error type definition
///
/// # Returns
///
/// A `TokenStream` containing generated `From` trait implementation and
/// mapping constants, or a compile error if validation fails.
///
/// # Errors
///
/// Returns an error if:
/// - A struct is missing the required `#[masterror(...)]` attribute
/// - An enum variant is missing the required `#[masterror(...)]` attribute
/// - Code or category values are invalid
pub fn expand(input: &ErrorInput) -> Result<TokenStream, Error> {
    match &input.data {
        ErrorData::Struct(data) => expand_struct(input, data),
        ErrorData::Enum(variants) => expand_enum(input, variants)
    }
}

/// Expands derive macro for struct error types.
///
/// Generates both conversion and mapping implementations for struct types.
///
/// # Arguments
///
/// * `input` - The parsed error type definition
/// * `data` - Struct-specific data and fields
///
/// # Returns
///
/// Combined conversion and mapping implementations.
fn expand_struct(input: &ErrorInput, data: &StructData) -> Result<TokenStream, Error> {
    let spec = data.masterror.as_ref().ok_or_else(|| {
        Error::new(
            input.ident.span(),
            "#[derive(Masterror)] requires #[masterror(...)] on structs"
        )
    })?;
    let conversion = struct_conversion_impl(input, data, spec);
    let mappings = struct_mapping_impl(input, spec);
    use quote::quote;
    Ok(quote! {
        #conversion
        #mappings
    })
}

/// Expands derive macro for enum error types.
///
/// Validates that all variants have masterror attributes, then generates
/// conversion and mapping implementations.
///
/// # Arguments
///
/// * `input` - The parsed error type definition
/// * `variants` - List of enum variants with their specifications
///
/// # Returns
///
/// Combined conversion and mapping implementations.
fn expand_enum(input: &ErrorInput, variants: &[VariantData]) -> Result<TokenStream, Error> {
    ensure_all_variants_have_masterror(variants)?;
    let conversion = enum_conversion_impl(input, variants);
    let mappings = enum_mapping_impl(input, variants);
    use quote::quote;
    Ok(quote! {
        #conversion
        #mappings
    })
}

#[cfg(test)]
mod tests {
    // Unit tests for individual functions are located in their respective
    // submodules (conversion, mapping, binding, attachment).
    // Integration tests are in the tests/ directory.
}