mizan/cores/mizan-rust-macros/src/shape.rs

//! Lower a `syn::Type` to a TypeShape construction expression. Shared by
//! `#[derive(Mizan)]` (for struct fields) and `#[mizan(...)]` (for fn input
//! params + return-type analysis).

use proc_macro2::TokenStream;
use quote::quote;
use syn::{GenericArgument, PathArguments, Type, TypePath};

/// Result of inspecting a fn's return type.
pub struct ReturnAnalysis {
    /// Inner type once `Option<...>` is unwrapped.
    pub inner: Type,
    /// True if the outermost wrapper is `Option<...>`.
    pub nullable: bool,
    /// True if `inner` is `Vec<T>` — caller emits an alias type entry.
    pub is_vec: bool,
    /// When `is_vec`, this is the element type `T`.
    pub vec_inner: Option<Type>,
    /// True when the user's return type is `Result<T, MizanError>` — the
    /// dispatch wrapper emits `?` so user-side errors bubble out as
    /// `MizanError` instead of being serialized into the success payload.
    /// The IR sees only the `T` side; the error variant is the substrate's
    /// invariant, not part of the output shape.
    pub returns_result: bool,
}

pub fn analyze_return(ty: &Type) -> ReturnAnalysis {
    let (effective, returns_result) = if let Some(ok) = unwrap_result_ok(ty) {
        (ok, true)
    } else {
        (ty.clone(), false)
    };
    let (inner, nullable) = if let Some(t) = unwrap_option(&effective) {
        (t, true)
    } else {
        (effective, false)
    };
    if let Some(elem) = unwrap_vec(&inner) {
        ReturnAnalysis {
            inner: inner.clone(),
            nullable,
            is_vec: true,
            vec_inner: Some(elem),
            returns_result,
        }
    } else {
        ReturnAnalysis {
            inner,
            nullable,
            is_vec: false,
            vec_inner: None,
            returns_result,
        }
    }
}

/// If `ty` is `Result<T, E>`, return `T`. Otherwise None. The substrate
/// only honors `Result<T, MizanError>`; the macro doesn't try to verify
/// `E` here — it lets rustc raise the type-mismatch at the `?` site if
/// the consumer used a non-MizanError variant.
pub fn unwrap_result_ok(ty: &Type) -> Option<Type> {
    let path = match ty {
        Type::Path(TypePath { qself: None, path }) => path,
        _ => return None,
    };
    let last = path.segments.last()?;
    if last.ident != "Result" {
        return None;
    }
    extract_single_generic(&last.arguments)
}

/// Emit a `TypeShape` const-expression for `ty`. Used inside `#[derive(Mizan)]`
/// when constructing the struct field shapes.
pub fn type_shape_expr(ty: &Type) -> TokenStream {
    if let Some(inner) = unwrap_option(ty) {
        let inner_shape = type_shape_expr(&inner);
        return quote! {
            ::mizan_core::TypeShape::Optional(::std::boxed::Box::new(#inner_shape))
        };
    }
    if let Some(elem) = unwrap_vec(ty) {
        let inner_shape = type_shape_expr(&elem);
        return quote! {
            ::mizan_core::TypeShape::List(::std::boxed::Box::new(#inner_shape))
        };
    }
    if let Some(elem) = unwrap_array(ty) {
        // `[T; N]` lowers to `list { T }` on the wire — JSON arrays don't
        // carry length, so the IR contract is the same as `Vec<T>`.
        let inner_shape = type_shape_expr(&elem);
        return quote! {
            ::mizan_core::TypeShape::List(::std::boxed::Box::new(#inner_shape))
        };
    }
    if let Some(elem) = unwrap_btreemap_value(ty) {
        // `BTreeMap<K, V>` on the wire is a JSON object keyed by `K`'s
        // string form. The Mizan IR doesn't model dynamic-keyed maps as a
        // distinct shape — closest equivalent is a list of value entries.
        let inner_shape = type_shape_expr(&elem);
        return quote! {
            ::mizan_core::TypeShape::List(::std::boxed::Box::new(#inner_shape))
        };
    }
    if let Some(p) = primitive_of(ty) {
        return quote! { ::mizan_core::TypeShape::Primitive(#p) };
    }
    // Fallback: assume a user-defined struct/enum implementing MizanType.
    // The Ref name comes from `<T as MizanType>::TYPE_NAME` (associated const).
    quote! { ::mizan_core::TypeShape::Ref(<#ty as ::mizan_core::MizanType>::TYPE_NAME) }
}

/// If `ty` is `[T; N]`, return `T`. Otherwise None.
pub fn unwrap_array(ty: &Type) -> Option<Type> {
    if let Type::Array(a) = ty {
        Some((*a.elem).clone())
    } else {
        None
    }
}

/// If `ty` is `BTreeMap<K, V>` or `HashMap<K, V>`, return `V` (the value).
/// String-keyed maps land on the wire as JSON objects; the IR carries the
/// value shape as a list element since KDL doesn't model dynamic-keyed maps
/// distinctly yet.
pub fn unwrap_btreemap_value(ty: &Type) -> Option<Type> {
    let path = match ty {
        Type::Path(TypePath { qself: None, path }) => path,
        _ => return None,
    };
    let last = path.segments.last()?;
    let name = last.ident.to_string();
    if name != "BTreeMap" && name != "HashMap" {
        return None;
    }
    let args = match &last.arguments {
        PathArguments::AngleBracketed(a) => a,
        _ => return None,
    };
    // BTreeMap<K, V> — second type argument is V.
    let mut type_args = args.args.iter().filter_map(|a| {
        if let GenericArgument::Type(t) = a {
            Some(t.clone())
        } else {
            None
        }
    });
    type_args.next()?; // skip K
    type_args.next()
}

/// Emit a `Primitive` const-expression for `ty`, or `None` if `ty` isn't a
/// known primitive scalar.
pub fn primitive_of(ty: &Type) -> Option<TokenStream> {
    let path = match ty {
        Type::Path(TypePath { qself: None, path }) => path,
        _ => return None,
    };
    let last = path.segments.last()?;
    let name = last.ident.to_string();
    match name.as_str() {
        "i8" | "i16" | "i32" | "i64" | "i128" | "isize" | "u8" | "u16" | "u32" | "u64" | "u128"
        | "usize" => Some(quote! { ::mizan_core::Primitive::Integer }),
        "f32" | "f64" => Some(quote! { ::mizan_core::Primitive::Number }),
        "bool" => Some(quote! { ::mizan_core::Primitive::Boolean }),
        "String" | "str" => Some(quote! { ::mizan_core::Primitive::String }),
        _ => None,
    }
}

/// If `ty` is `Option<T>`, return `T`. Otherwise None.
pub fn unwrap_option(ty: &Type) -> Option<Type> {
    let path = match ty {
        Type::Path(TypePath { qself: None, path }) => path,
        _ => return None,
    };
    let last = path.segments.last()?;
    if last.ident != "Option" {
        return None;
    }
    extract_single_generic(&last.arguments)
}

/// If `ty` is `Vec<T>`, return `T`. Otherwise None.
pub fn unwrap_vec(ty: &Type) -> Option<Type> {
    let path = match ty {
        Type::Path(TypePath { qself: None, path }) => path,
        _ => return None,
    };
    let last = path.segments.last()?;
    if last.ident != "Vec" {
        return None;
    }
    extract_single_generic(&last.arguments)
}

fn extract_single_generic(args: &PathArguments) -> Option<Type> {
    let args = match args {
        PathArguments::AngleBracketed(a) => a,
        _ => return None,
    };
    for arg in &args.args {
        if let GenericArgument::Type(t) = arg {
            return Some(t.clone());
        }
    }
    None
}