miniextendr_macros/

miniextendr_trait.rs

//! # Trait Support for `#[miniextendr]`
//!
//! This module handles `#[miniextendr]` applied to trait definitions,
//! generating the ABI infrastructure for cross-package trait dispatch.
//!
//! ## Overview
//!
//! When `#[miniextendr]` is applied to a trait, it generates:
//!
//! 1. **Type tag constant** (`TAG_<TraitName>`) - 128-bit identifier for runtime type checking
//! 2. **Vtable struct** (`<TraitName>VTable`) - Function pointer table for method dispatch
//! 3. **View struct** (`<TraitName>View`) - Runtime wrapper combining data pointer and vtable
//! 4. **Method shims** - `extern "C"` functions that convert SEXP arguments and call methods
//! 5. **Vtable builder** - `__<trait>_build_vtable::<T>()` for impl blocks
//!
//! ## Usage
//!
//! ```ignore
//! #[miniextendr]
//! pub trait Counter {
//!     fn value(&self) -> i32;
//!     fn increment(&mut self);
//!     fn add(&mut self, n: i32);
//! }
//! ```
//!
//! Generates (conceptually):
//!
//! ```text
//! // Original trait (passed through)
//! pub trait Counter {
//!     fn value(&self) -> i32;
//!     fn increment(&mut self);
//!     fn add(&mut self, n: i32);
//! }
//!
//! // Type tag for runtime identification
//! pub const TAG_Counter: mx_tag = mx_tag::new(0x..., 0x...);
//!
//! // Vtable with one entry per method
//! #[repr(C)]
//! pub struct CounterVTable {
//!     pub value: mx_meth,
//!     pub increment: mx_meth,
//!     pub add: mx_meth,
//! }
//!
//! // View over the data and vtable pointers; roots its R receiver
//! pub struct CounterView {
//!     __mx_view: miniextendr_api::trait_abi::TraitViewData<CounterVTable>,
//! }
//!
//! // Shim for each method
//! unsafe extern "C" fn __Counter_value_shim<T: Counter>(
//!     data: *mut c_void, argc: i32, argv: *const SEXP
//! ) -> SEXP {
//!     // 1. Check arity
//!     // 2. Cast data to &T
//!     // 3. Call method
//!     // 4. Convert result to SEXP
//!     // 5. Catch panics
//! }
//!
//! // Builder to create vtable for a concrete type
//! pub const fn __Counter_build_vtable<T: Counter>() -> CounterVTable {
//!     CounterVTable {
//!         value: __Counter_value_shim::<T>,
//!         increment: __Counter_increment_shim::<T>,
//!         add: __Counter_add_shim::<T>,
//!     }
//! }
//! ```
//!
//! ## Supported Method Signatures
//!
//! Methods must follow these constraints:
//!
//! - **Receiver**: `&self`, `&mut self`, `self: ExternalPtrRef<'_, Self>` or
//!   `self: ExternalPtrMut<'_, Self>` for instance methods, or none for static methods.
//!   Borrowed-owner receivers require `Self: TypedExternal`; their emitted Rust
//!   signatures are associated functions accepting the handle by value.
//! - **Arguments**: Types that implement `TryFromSexp`
//! - **Return**: Types that implement `IntoR`, or `()`
//! - **No generics**: Methods cannot have generic type parameters
//! - **No async**: Async methods are not supported
//! - **Static methods**: Methods without a receiver are allowed and resolved at compile time
//!   (they don't go through the vtable)
//!
//! ## Default Methods
//!
//! Default method implementations are supported. The vtable builder will
//! use the default implementation if the concrete type doesn't override it.
//!
//! ```ignore
//! #[miniextendr]
//! pub trait Counter {
//!     fn value(&self) -> i32;
//!
//!     // Default implementation - included in vtable
//!     fn is_zero(&self) -> bool {
//!         self.value() == 0
//!     }
//! }
//! ```
//!
//! ## Error Handling
//!
//! A method shim runs inside `with_r_unwind_protect_shim`, which turns a Rust
//! panic into a tagged condition SEXP; the View re-panics with it in the
//! caller's guard. These panic:
//!
//! - **Arity mismatch**: "expected N arguments, got M"
//! - **Aliased native borrows**: two arguments (or two elements of one) that
//!   borrow the same R vector, at least one mutably, checked before any
//!   argument is converted
//! - **Type conversion failure**: the converter's error message
//! - **The method itself**
//!
//! ## GC Protection
//!
//! A View method converts each argument to a fresh SEXP, and the next
//! conversion allocates, so it protects every converted argument in a
//! `ProtectScope` as soon as it exists and keeps it protected across the
//! vtable call. The returned SEXP is protected across the tagged-error check
//! and its conversion back to Rust.
//!
//! ## Thread Safety
//!
//! All generated shims are **main-thread only**. They do not route through
//! `with_r_thread` because R invokes `.Call` on the main thread.

use proc_macro2::TokenStream;
use syn::ItemTrait;

/// Expand `#[miniextendr]` applied to a trait definition.
///
/// # Arguments
///
/// * `attr` - Attribute arguments (currently unused, reserved for future options)
/// * `item` - The trait definition token stream
///
/// # Returns
///
/// Expanded token stream containing:
/// - Original trait definition
/// - Type tag constant
/// - Vtable struct
/// - View struct
/// - Method shims
/// - Vtable builder function
///
/// # Errors
///
/// Returns a compile error if:
/// - Methods have unsupported signatures
/// - Methods are async
pub fn expand_trait(
    _attr: proc_macro::TokenStream,
    item: proc_macro::TokenStream,
) -> proc_macro::TokenStream {
    let trait_item = syn::parse_macro_input!(item as ItemTrait);

    // Validate trait constraints
    if let Err(e) = validate_trait(&trait_item) {
        return e.into_compile_error().into();
    }

    // Generate the expanded code
    let expanded = generate_trait_abi(&trait_item);

    expanded.into()
}

/// Validate that the trait meets requirements for ABI generation.
///
/// # Constraints
///
/// - Instance methods use shared/mutable references or explicit borrowed-owner receivers
/// - Methods cannot be async
/// - Methods cannot have generic parameters
/// - Generic type parameters on the trait itself are allowed
fn validate_trait(trait_item: &ItemTrait) -> syn::Result<()> {
    let trait_name = &trait_item.ident;

    // Validate each method
    for item in &trait_item.items {
        if let syn::TraitItem::Fn(method) = item {
            validate_method(method, trait_name)?;
        }
    }

    Ok(())
}

/// Validate a single trait method for ABI compatibility.
///
/// Rejects async methods, methods with generic type parameters, and methods
/// that take `self` by value (only `&self` and `&mut self` are allowed).
/// Static methods (no receiver) are permitted.
fn validate_method(method: &syn::TraitItemFn, trait_name: &syn::Ident) -> syn::Result<()> {
    let method_name = &method.sig.ident;

    // Check for async
    if method.sig.asyncness.is_some() {
        return Err(syn::Error::new_spanned(
            method.sig.asyncness,
            format!(
                "#[miniextendr] trait `{}::{}` cannot be async",
                trait_name, method_name
            ),
        ));
    }

    // Check for type/const generics on method.
    // Lifetime params are allowed (erased at codegen); type/const params would require
    // monomorphization and are incompatible with the vtable-shim codegen path.
    {
        let has_type_or_const = method
            .sig
            .generics
            .params
            .iter()
            .any(|p| matches!(p, syn::GenericParam::Type(_) | syn::GenericParam::Const(_)));
        if has_type_or_const {
            return Err(syn::Error::new_spanned(
                &method.sig.generics,
                format!(
                    "#[miniextendr] trait method `{}::{}` cannot have generic type or const parameters",
                    trait_name, method_name
                ),
            ));
        }
    }

    // Instance receivers borrow Self directly or carry an explicit borrowed owner.
    // Static methods are allowed but won't be included in the vtable
    // (they're resolved at compile time via <Type as Trait>::method())
    let receiver = method.sig.inputs.first();
    if let Some(syn::FnArg::Receiver(r)) = receiver {
        // Accept either:
        // - `&self` / `&mut self` (r.reference is Some)
        // - `self: &Self` / `self: &mut Self` (r.colon_token is Some with reference type)
        let is_ref = if r.reference.is_some() {
            true
        } else if r.colon_token.is_some() {
            // Check if the type is a reference type (&Self or &mut Self)
            matches!(r.ty.as_ref(), syn::Type::Reference(_))
        } else {
            false
        };

        if !is_ref && crate::trait_receiver::owner_receiver(&method.sig).is_none() {
            return Err(syn::Error::new_spanned(
                r,
                format!(
                    "#[miniextendr] trait method `{}::{}` receiver must be `&self` or `&mut self`, not `self` by value",
                    trait_name, method_name
                ),
            ));
        }
    }
    // If receiver is None or FnArg::Typed (no self), it's a static method - allowed

    // The unforced dots (#1892) cannot cross the vtable, nor can the RNG
    // guard (#2002).
    crate::miniextendr_fn::refuse_lazy_dots_in_trait_method(&method.sig.inputs)?;
    crate::miniextendr_fn::refuse_rng_guard_in_trait_method(&method.sig.inputs)?;

    Ok(())
}

/// Generate the ABI infrastructure for a trait.
///
/// This is the main code generation function that produces:
/// - Type tag constant
/// - Vtable struct
/// - View struct (skipped for generic traits)
/// - Method shims (with trait type params threaded through)
/// - Vtable builder (with trait type params threaded through)
fn generate_trait_abi(trait_item: &ItemTrait) -> TokenStream {
    let trait_name = &trait_item.ident;
    let vis = &trait_item.vis;

    // Generate names for generated items
    let tag_name = crate::naming::trait_tag_ident(trait_name);
    let vtable_name = quote::format_ident!("{}VTable", trait_name);
    let view_name = quote::format_ident!("{}View", trait_name);
    let build_vtable_fn = crate::naming::trait_vtable_builder_ident(trait_name);

    // Collect trait-level generic type parameters
    let trait_type_params: Vec<&syn::GenericParam> = trait_item.generics.params.iter().collect();
    let trait_param_idents: Vec<&syn::Ident> = trait_type_params
        .iter()
        .filter_map(|p| {
            if let syn::GenericParam::Type(tp) = p {
                Some(&tp.ident)
            } else {
                None
            }
        })
        .collect();
    let has_generics = !trait_item.generics.params.is_empty();

    // Collect associated types
    let assoc_types: Vec<&syn::Ident> = trait_item
        .items
        .iter()
        .filter_map(|item| {
            if let syn::TraitItem::Type(t) = item {
                Some(&t.ident)
            } else {
                None
            }
        })
        .collect();

    // Collect trait where clause
    let trait_where_clause = &trait_item.generics.where_clause;

    // Collect method information
    // Filter to only include instance methods (with &self or &mut self) that aren't skipped
    let methods: Vec<_> = {
        let mut collected = Vec::new();
        for item in &trait_item.items {
            if let syn::TraitItem::Fn(method) = item {
                let info = match extract_method_info(method) {
                    Ok(info) => info,
                    Err(e) => return e.into_compile_error(),
                };
                if info.has_self && !info.skip {
                    collected.push(info);
                }
            }
        }
        collected
    }
    .into_iter()
    .collect();

    // Query must reject incompatible declarations before a View reads a slot.
    // Package/module paths must not enter the tag: independently compiled
    // declarations of the same interface need to agree across DLLs.
    let tag_path = trait_abi_tag_path(trait_name, &methods);

    // Generate vtable fields
    let vtable_fields: Vec<_> = methods
        .iter()
        .map(|m| {
            let name = &m.name;
            let abi = if m.owner_receiver.is_some() {
                quote::quote!(::miniextendr_api::abi::mx_owner_meth)
            } else {
                quote::quote!(::miniextendr_api::abi::mx_meth)
            };
            quote::quote! { pub #name: #abi }
        })
        .collect();

    // Compute extra bounds needed for shims
    let extra_bounds =
        compute_extra_bounds(&methods, trait_name, &assoc_types, &trait_param_idents);

    // Build trait bound for __ImplT
    let impl_t = quote::format_ident!("__ImplT");
    let trait_bound = if trait_param_idents.is_empty() {
        quote::quote! { #trait_name }
    } else {
        quote::quote! { #trait_name<#(#trait_param_idents),*> }
    };

    // Build combined where clause
    let all_where_predicates = build_where_predicates(trait_where_clause, &extra_bounds);
    let where_clause = if all_where_predicates.is_empty() {
        quote::quote! {}
    } else {
        quote::quote! { where #(#all_where_predicates),* }
    };

    // Declaration-side builders select the same associated callbacks as impls.
    let vtable_inits: Vec<_> = methods
        .iter()
        .map(|m| {
            let name = &m.name;
            let shim_name = crate::naming::trait_method_shim_ident(trait_name, name);
            quote::quote! {
                #name: <#impl_t as #trait_bound>::#shim_name
            }
        })
        .collect();

    // Generate method wrappers for the View struct
    // Skip entirely for generic traits (type-erased view can't know type params)
    let view_methods: Vec<_> = if has_generics {
        vec![]
    } else {
        methods.iter().filter_map(generate_view_method).collect()
    };

    // Strip #[miniextendr(...)] attrs from trait items before emitting
    let mut clean_trait = trait_item.clone();
    for item in &mut clean_trait.items {
        if let syn::TraitItem::Fn(method) = item {
            method
                .attrs
                .retain(|attr| !attr.path().is_ident("miniextendr"));
            crate::trait_receiver::rewrite(&mut method.sig, method.default.as_mut());
        }
    }

    // Non-generic shims are hidden trait methods, so an impl reaches them
    // through any path to the trait. A generic trait's impls generate their
    // own concrete shims from their signatures.
    if !has_generics {
        clean_trait.items.extend(methods.iter().map(|m| {
            syn::TraitItem::Fn(associated_method_shim(generate_method_shim(
                trait_name,
                m,
                &extra_bounds,
                &trait_param_idents,
                &trait_type_params,
                trait_where_clause,
            )))
        }));
    }

    let trait_name_str = trait_name.to_string();
    let source_loc_doc = crate::source_location_doc(trait_name.span());

    let impl_bounds = &extra_bounds.impl_bounds;

    // View struct and its impls (skipped for generic traits)
    let view_tokens = if has_generics {
        quote::quote! {}
    } else {
        quote::quote! {
            #[doc = ::core::concat!(
                "Runtime view for objects implementing `",
                ::core::stringify!(#trait_name),
                "`."
            )]
            #[doc = #source_loc_doc]
            #[doc = ::core::concat!("Generated from source file `", ::core::file!(), "`.")]
            ///
            /// Keeps the receiver alive for method dispatch. Use `try_from_sexp`
            /// to create a view with its own root for the R external pointer.
            /// Construction, use and drop belong on R's main thread.
            #[allow(non_camel_case_types)]
            #vis struct #view_name {
                __mx_view: ::miniextendr_api::trait_abi::TraitViewData<#vtable_name>,
            }

            // TraitView implementation
            impl ::miniextendr_api::TraitView for #view_name {
                const TAG: ::miniextendr_api::abi::mx_tag = #tag_name;

                #[inline]
                unsafe fn from_raw_parts(
                    data: *mut ::std::os::raw::c_void,
                    vtable: *const ::std::os::raw::c_void,
                    owner: ::core::option::Option<::miniextendr_api::SEXP>,
                ) -> Self {
                    Self {
                        __mx_view: unsafe {
                            ::miniextendr_api::trait_abi::TraitViewData::new(data, vtable, owner)
                        },
                    }
                }
            }

            // Method wrappers on View
            impl #view_name {
                /// Try to create a view from an R SEXP.
                ///
                /// Returns `Some(Self)` if the object implements this trait,
                /// `None` otherwise.
                ///
                /// # Safety
                ///
                /// - `sexp` must be a valid R external pointer (EXTPTRSXP)
                /// - The object must stay live through construction; the view then roots it
                /// - A call that conflicts with one still running on the same object
                ///   raises the `miniextendr_borrow_conflict` error
                /// - Construction, use and drop must all run on R's main thread
                #[inline]
                pub unsafe fn try_from_sexp(sexp: ::miniextendr_api::SEXP) -> ::core::option::Option<Self> {
                    unsafe { <Self as ::miniextendr_api::TraitView>::try_from_sexp(sexp) }
                }

                /// Try to create a view, panicking with error message on failure.
                ///
                /// # Safety
                ///
                /// Same as `try_from_sexp`.
                #[inline]
                pub unsafe fn from_sexp(sexp: ::miniextendr_api::SEXP) -> Self {
                    unsafe { Self::try_from_sexp(sexp) }
                        .expect(::core::concat!("Object does not implement ", #trait_name_str, " trait"))
                }

                #(#view_methods)*
            }
        }
    };

    // For generic traits (with type params like <T>), skip shim and builder generation.
    // These are generated at the impl site with concrete types to avoid recursive trait
    // resolution overflow (e.g., `Vec<T>: TryFromSexp` triggers infinite recursion through
    // `impl<T> TryFromSexp for Vec<Vec<T>>`).
    let shim_and_builder = if has_generics {
        quote::quote! {}
    } else {
        quote::quote! {
            #[doc = ::core::concat!(
                "Build a vtable for a concrete type implementing `",
                ::core::stringify!(#trait_name),
                "`."
            )]
            #[doc = #source_loc_doc]
            #[doc = ::core::concat!("Generated from source file `", ::core::file!(), "`.")]
            #[allow(non_snake_case)]
            #vis const fn #build_vtable_fn<#(#trait_type_params,)* #impl_t: #trait_bound #(+ #impl_bounds)*>() -> #vtable_name
            #where_clause
            {
                #vtable_name {
                    #(#vtable_inits),*
                }
            }
        }
    };

    // All impls receive the declaration's R metadata, including generic traits
    // and traits with associated types. Signatures for empty impls still use
    // the established non-generic TPIE path.
    let mut method_metadata = Vec::new();
    let mut tpie_method_metadata = Vec::new();
    for item in &trait_item.items {
        if let syn::TraitItem::Fn(method) = item {
            let info = match extract_method_info(method) {
                Ok(info) => info,
                Err(e) => return e.into_compile_error(),
            };
            let name = &method.sig.ident;
            let r_name_attr = info
                .r_name
                .as_ref()
                .map(|name| quote::quote!(#[miniextendr(r_name = #name)]));
            let skip_attr = info.skip.then(|| quote::quote!(#[miniextendr(skip)]));
            // Copied signatures name every parameter as the declaration's
            // metadata does (`arg<i>` for a pattern), since the generated
            // wrappers pass each argument by name.
            let mut sig = method.sig.clone();
            for (arg, name) in sig
                .inputs
                .iter_mut()
                .filter_map(|arg| match arg {
                    syn::FnArg::Typed(arg) => Some(arg),
                    syn::FnArg::Receiver(_) => None,
                })
                .zip(&info.param_names)
            {
                *arg.pat = syn::parse_quote!(#name);
            }
            // Keep default signatures, but never copy their bodies into an
            // implementation. Generated wrappers call the trait's own default,
            // so an impl that omits a default still gets its R wrapper, generic
            // trait or not. Required methods carry names only, preserving
            // impl-local types.
            if method.default.is_some() {
                let docs = method
                    .attrs
                    .iter()
                    .filter(|attr| attr.path().is_ident("doc"));
                method_metadata.push(quote::quote! {
                    #(#docs)* #r_name_attr #skip_attr #sig {}
                });
            } else {
                let params = &info.param_names;
                method_metadata.push(quote::quote! {
                    #r_name_attr #skip_attr fn #name(#(#params: ()),*);
                });
            }
            if !has_generics && assoc_types.is_empty() && !info.skip {
                let r_name = info
                    .r_name
                    .as_deref()
                    .map(crate::naming::name_ident)
                    .unwrap_or_else(|| name.clone());
                tpie_method_metadata.push(quote::quote! {
                    method { r_name = #r_name; #sig; }
                });
            }
        }
    }
    // The impl receives the exact declaration layout and fingerprint, never
    // a guessed path to companion items. No caller-scope types occur here.
    let abi_metadata = quote::quote! {
        abi #trait_name #has_generics #tag_path { #(#vtable_fields),* }
    };
    let empty_impl_arm = if !has_generics && assoc_types.is_empty() {
        quote::quote! {
            ($concrete_type:ty, $trait_path:path, $class_system:ident, $no_rd:tt, $internal:tt, $noexport:tt, $no_preconditions:tt) => {
                ::miniextendr_api::__mx_trait_impl_expand! {
                    concrete_type = $concrete_type;
                    trait_path = $trait_path;
                    class_system = $class_system;
                    no_rd = $no_rd;
                    internal = $internal;
                    noexport = $noexport;
                    no_preconditions = $no_preconditions;
                    #abi_metadata
                    #(#tpie_method_metadata)*
                }
            };
        }
    } else {
        quote::quote! {}
    };
    let declaration_generics = &trait_item.generics;
    let metadata_macro_name = crate::naming::trait_metadata_macro_ident(trait_name);
    let metadata_macro = quote::quote! {
        #[macro_export]
        #[doc(hidden)]
        macro_rules! #metadata_macro_name {
            (@impl { $($attrs:tt)* } { $($implementation:tt)* }) => {
                ::miniextendr_api::__mx_trait_impl_expand! {
                    @impl { $($attrs)* } { $($implementation)* }
                    { #(#method_metadata)* }
                    { #declaration_generics }
                    #abi_metadata
                }
            };
            #empty_impl_arm
        }
        #[doc(hidden)]
        #[allow(unused_imports)]
        #vis use #metadata_macro_name as #trait_name;
    };

    quote::quote! {
        // Pass through the original trait (with #[miniextendr] attrs stripped from items)
        #clean_trait

        #[doc = ::core::concat!(
            "Type tag for runtime identification of the `",
            ::core::stringify!(#trait_name),
            "` trait."
        )]
        #[doc = #source_loc_doc]
        #[doc = ::core::concat!("Generated from source file `", ::core::file!(), "`.")]
        #[allow(non_upper_case_globals)]
        #vis const #tag_name: ::miniextendr_api::abi::mx_tag =
            ::miniextendr_api::abi::mx_tag_from_path(#tag_path);

        #[doc = ::core::concat!("Vtable for the `", ::core::stringify!(#trait_name), "` trait.")]
        #[doc = #source_loc_doc]
        #[doc = ::core::concat!("Generated from source file `", ::core::file!(), "`.")]
        ///
        /// Contains one `mx_meth` function pointer per trait method.
        #[repr(C)]
        #[doc(hidden)]
        #[allow(non_camel_case_types)]
        #vis struct #vtable_name {
            #(#vtable_fields),*
        }

        #view_tokens

        #shim_and_builder

        #metadata_macro
    }
}

/// Encode the exported interface, in vtable order, for `mx_tag_from_path`.
///
/// Types use syn's token rendering, not their source whitespace. This is a
/// syntactic contract: the macro cannot resolve aliases or imported names.
/// Length-prefix every component so custom R names cannot change its framing.
fn trait_abi_tag_path(trait_name: &syn::Ident, methods: &[MethodInfo]) -> String {
    fn push(out: &mut String, component: &str) {
        use std::fmt::Write;
        write!(out, "{}:{component}", component.len()).unwrap();
    }

    let mut tag = String::from("miniextendr::trait-abi/v2;");
    push(&mut tag, &crate::naming::ident_name(trait_name));
    push(&mut tag, &methods.len().to_string());
    for method in methods {
        let name = crate::naming::ident_name(&method.name);
        push(&mut tag, &name);
        push(&mut tag, method.r_name.as_deref().unwrap_or(&name));
        push(
            &mut tag,
            match method.owner_receiver {
                Some(crate::trait_receiver::OwnerReceiver::Shared) => "owner-ref",
                Some(crate::trait_receiver::OwnerReceiver::Mutable) => "owner-mut",
                None if method.is_mut => "mut",
                None => "ref",
            },
        );
        push(&mut tag, &method.param_types.len().to_string());
        for ty in &method.param_types {
            push(&mut tag, &quote::ToTokens::to_token_stream(ty).to_string());
        }
        let result = method
            .return_type
            .as_ref()
            .map(|ty| quote::ToTokens::to_token_stream(ty).to_string())
            .unwrap_or_else(|| "()".to_owned());
        push(&mut tag, &result);
    }
    tag
}

/// Generate a method wrapper for the View struct.
///
/// This creates a method on the View that calls through the vtable.
/// Returns None for methods with `Self` in return types or `&Self` in parameters,
/// since these can't be meaningfully expressed on the type-erased View.
fn generate_view_method(method: &MethodInfo) -> Option<TokenStream> {
    // Skip methods where Self appears in return type or parameters.
    // In the View context, Self refers to the View struct, not the concrete type,
    // so these methods can't work through the type-erased vtable dispatch.
    if method.return_type.as_ref().is_some_and(type_contains_self) {
        return None;
    }
    if method.param_types.iter().any(type_contains_self) {
        return None;
    }

    let method_name = &method.name;
    let param_names = &method.param_names;
    let param_types = &method.param_types;

    // Generate function parameters
    let params: Vec<_> = param_names
        .iter()
        .zip(param_types.iter())
        .map(|(name, ty)| {
            quote::quote! { #name: #ty }
        })
        .collect();

    // Generate self receiver
    let self_param = if method.is_mut {
        quote::quote! { &mut self }
    } else {
        quote::quote! { &self }
    };

    // Generate argument array for vtable call. A `Missing<T>` argument (an
    // omittable parameter, e.g. a choice, #1551) crosses as R's
    // missing-argument sentinel when absent, which the shim's
    // `TryFromSexp for Missing<T>` reads back; `Missing` has no `IntoR`.
    let argc = param_types.len() as i32;
    let arg_conversions: Vec<_> = param_names
        .iter()
        .zip(param_types.iter())
        .map(|(name, ty)| {
            if crate::miniextendr_fn::get_missing_inner_type(ty).is_some() {
                quote::quote! {
                    ::miniextendr_api::trait_abi::missing_to_sexp(#name)
                }
            } else {
                quote::quote! {
                    ::miniextendr_api::trait_abi::to_sexp(#name)
                }
            }
        })
        .collect();

    // Generate vtable call. Each converted argument is rooted before the next
    // conversion allocates, and stays rooted for the whole call: the shim reads
    // every `argv` entry back, and SEXP-backed parameters live on in the method
    // body (the `mx_meth` contract).
    let owner_argument = method.owner_receiver.map(|_| {
        quote::quote! {
            self.__mx_view.owner().expect("this trait method requires an R-owned receiver"),
        }
    });
    let vtable_call = if argc > 0 {
        quote::quote! {
            let args: [::miniextendr_api::SEXP; #argc as usize] =
                [#(__mx_roots.protect_raw(#arg_conversions)),*];
            ((*self.__mx_view.vtable()).#method_name)(self.__mx_view.data(), #owner_argument #argc, args.as_ptr())
        }
    } else {
        quote::quote! {
            ((*self.__mx_view.vtable()).#method_name)(self.__mx_view.data(), #owner_argument 0, ::std::ptr::null())
        }
    };

    // Generate return type handling. A returned value is rooted across the
    // tagged-error check and its conversion back to Rust.
    let return_type = &method.return_type;
    let (return_sig, result_binding, result_conversion) = if let Some(ret_ty) = return_type {
        (
            quote::quote! { -> #ret_ty },
            quote::quote! { let result = __mx_roots.protect_raw({ #vtable_call }); },
            quote::quote! {
                ::miniextendr_api::trait_abi::from_sexp::<#ret_ty>(result)
            },
        )
    } else {
        (
            quote::quote! {},
            quote::quote! { let result = { #vtable_call }; },
            quote::quote! {
                let _ = result;
            },
        )
    };

    // The scope owns the argument and result protections; a method with
    // neither has nothing to root.
    let roots = if argc > 0 || return_type.is_some() {
        quote::quote! {
            let __mx_roots = ::miniextendr_api::gc_protect::ProtectScope::new();
        }
    } else {
        quote::quote! {}
    };

    // The view keeps the trait's parameter names, so a `_self` parameter (R
    // formal `self`) sits beside the `self` receiver here too.
    Some(quote::quote! {
        #[doc = ::core::concat!("Call `", ::core::stringify!(#method_name), "` through the vtable.")]
        #[inline]
        #[allow(clippy::duplicate_underscore_argument)]
        pub fn #method_name(#self_param #(, #params)*) #return_sig {
            unsafe {
                #roots
                #result_binding
                // Approach 1 (issue #345): if the shim returned a tagged error SEXP,
                // re-panic with the reconstructed RCondition so the consumer's outer
                // `with_r_unwind_protect` guard can apply rust_* class layering.
                ::miniextendr_api::trait_abi::repanic_if_rust_error(result);
                #result_conversion
            }
        }
    })
}

/// Generate a method shim function for a trait method.
///
/// The shim is an `extern "C"` function that, inside `with_r_unwind_protect_shim`:
/// 1. Checks argument arity
/// 2. Refuses aliased native borrows among the arguments
/// 3. Converts SEXP arguments to Rust types
/// 4. Calls the actual method on the concrete type
/// 5. Converts the result back to SEXP
///
/// A panic in any step comes back as a tagged condition SEXP, which the View
/// re-panics with. `generate_concrete_vtable_shims` emits the same steps for
/// a generic trait's impls.
///
/// For generic traits, the shim carries the trait's type parameters plus `__ImplT`.
fn generate_method_shim(
    trait_name: &syn::Ident,
    method: &MethodInfo,
    extra_bounds: &ExtraBounds,
    trait_param_idents: &[&syn::Ident],
    trait_type_params: &[&syn::GenericParam],
    trait_where_clause: &Option<syn::WhereClause>,
) -> TokenStream {
    let method_name = &method.name;
    let shim_name = crate::naming::trait_method_shim_ident(trait_name, method_name);
    let impl_t = quote::format_ident!("__ImplT");
    // User argument bindings keep their source spans. The shim's own
    // bindings must remain distinct even when a parameter has the same name.
    let data = syn::Ident::new("data", proc_macro2::Span::mixed_site());
    let argc = syn::Ident::new("argc", proc_macro2::Span::mixed_site());
    let argv = syn::Ident::new("argv", proc_macro2::Span::mixed_site());
    let self_ref = syn::Ident::new("self_ref", proc_macro2::Span::mixed_site());
    let cell = syn::Ident::new("__mx_cell", proc_macro2::Span::mixed_site());
    let guard = syn::Ident::new("__mx_guard", proc_macro2::Span::mixed_site());
    let owner = syn::Ident::new("owner", proc_macro2::Span::mixed_site());
    let owner_parameter = method.owner_receiver.map(|_| {
        quote::quote! {
            #owner: ::miniextendr_api::SEXP,
        }
    });

    let param_count = method.param_types.len();
    let expected_argc = param_count as i32;

    // Generate argument extraction
    // For &Self params, extract ExternalPtr<__ImplT> and borrow from it
    let arg_extractions: Vec<_> = method
        .param_names
        .iter()
        .zip(method.param_types.iter())
        .enumerate()
        .map(|(i, (name, ty))| {
            crate::trait_self_ref::argument(
                name,
                &crate::naming::ident_name(name),
                ty,
                &impl_t,
                i,
                &argv,
                None,
            )
        })
        .collect();

    let native_borrow_checks = crate::trait_self_ref::native_borrow_checks(
        method
            .param_names
            .iter()
            .zip(&method.param_types)
            .enumerate()
            .map(|(index, (name, ty))| (index, crate::naming::ident_name(name), ty)),
        &argv,
        None,
    );

    let self_refs: Vec<_> = method
        .param_names
        .iter()
        .zip(&method.param_types)
        .enumerate()
        .filter_map(|(index, (name, ty))| {
            crate::type_inspect::self_ref_mutability(ty).map(|mutable| (name, mutable, index))
        })
        .collect();
    let handles: Vec<_> = self_refs
        .iter()
        .map(|(name, mutable, _)| {
            (
                crate::trait_self_ref::handle_ident(name),
                *mutable,
                crate::naming::ident_name(name),
            )
        })
        .collect();
    let alias_checks = crate::trait_self_ref::alias_checks(
        &impl_t,
        &handles,
        Some((crate::trait_self_ref::cell_address(&cell), method.is_mut)),
    );
    let self_borrows = self_refs
        .iter()
        .map(|(name, mutable, _)| crate::trait_self_ref::borrow(name, *mutable));

    // Generate method call (uses __ImplT). The receiver borrows the value's
    // RefCell for the rest of the shim, through the result conversion.
    let param_names = &method.param_names;
    let (receiver, method_call) = if let Some(kind) = method.owner_receiver {
        let handle = kind.type_path();
        let trait_args =
            (!trait_param_idents.is_empty()).then(|| quote::quote!(<#(#trait_param_idents),*>));
        (
            quote::quote! {
                let #self_ref = unsafe {
                    #handle::<#impl_t>::from_raw_parts(
                        &#owner,
                        #cell,
                    )
                };
            },
            quote::quote! {
                <#impl_t as #trait_name #trait_args>::#method_name(#self_ref, #(#param_names),*)
            },
        )
    } else {
        (
            crate::trait_self_ref::receiver_borrow(&cell, &guard, &self_ref, method.is_mut),
            quote::quote! { #self_ref.#method_name(#(#param_names),*) },
        )
    };

    // Generate result conversion
    let result_conversion = if method.return_type.is_some() {
        quote::quote! {
            unsafe { ::miniextendr_api::trait_abi::to_sexp(result) }
        }
    } else {
        quote::quote! {
            let _ = result;
            unsafe { ::miniextendr_api::trait_abi::nil() }
        }
    };

    // Build trait bound for __ImplT
    let trait_bound = if trait_param_idents.is_empty() {
        quote::quote! { #trait_name }
    } else {
        quote::quote! { #trait_name<#(#trait_param_idents),*> }
    };

    let impl_bounds = &extra_bounds.impl_bounds;
    let all_where_predicates = build_where_predicates(trait_where_clause, extra_bounds);
    let where_clause = if all_where_predicates.is_empty() {
        quote::quote! {}
    } else {
        quote::quote! { where #(#all_where_predicates),* }
    };

    let method_name_str = format!("{}::{}", trait_name, method_name);

    quote::quote! {
        #[doc = ::core::concat!(
            "Method shim for `",
            ::core::stringify!(#trait_name),
            "::",
            ::core::stringify!(#method_name),
            "`."
        )]
        ///
        /// Converts SEXP arguments, calls the method, and returns SEXP result.
        /// Both Rust panics and R longjmps are caught via `with_r_unwind_protect`.
        #[doc(hidden)]
        #[allow(non_snake_case)]
        unsafe extern "C" fn #shim_name<#(#trait_type_params,)* #impl_t: #trait_bound #(+ #impl_bounds)*>(
            #data: *mut ::std::os::raw::c_void,
            #owner_parameter
            #argc: i32,
            #argv: *const ::miniextendr_api::SEXP,
        ) -> ::miniextendr_api::SEXP
        #where_clause
        {
            // Wrap in with_r_unwind_protect_shim: catches Rust panics and returns
            // a tagged error SEXP instead of calling Rf_errorcall directly. The
            // tagged SEXP is returned to the View method wrapper which re-panics
            // via repanic_if_rust_error, allowing the consumer's outer
            // `with_r_unwind_protect` guard to produce rust_* class layering
            // (issue #345). R-origin longjmps still propagate via R_ContinueUnwind.
            ::miniextendr_api::unwind_protect::with_r_unwind_protect_shim(|| {
                ::miniextendr_api::trait_abi::check_arity(#argc, #expected_argc, #method_name_str);
                let #cell = unsafe { &*#data.cast::<::core::cell::RefCell<#impl_t>>() };
                #native_borrow_checks
                // Extract arguments
                #(#arg_extractions)*
                #alias_checks
                #(#self_borrows)*

                // Call method
                #receiver
                let result = #method_call;

                // Convert result
                #result_conversion
            })
        }
    }
}

/// Move the declaration shim into the trait so an impl can name it through
/// any path to that trait. `Self: Sized` keeps these static ABI callbacks out
/// of Rust trait objects. Types in the body still resolve at the declaration.
fn associated_method_shim(tokens: TokenStream) -> syn::TraitItemFn {
    use syn::visit_mut::VisitMut;

    struct ImplTypeToSelf;
    impl VisitMut for ImplTypeToSelf {
        fn visit_path_mut(&mut self, path: &mut syn::Path) {
            syn::visit_mut::visit_path_mut(self, path);
            if let Some(first) = path.segments.first_mut()
                && first.ident == "__ImplT"
            {
                first.ident = syn::Ident::new("Self", first.ident.span());
            }
        }
    }

    let mut shim: syn::TraitItemFn = syn::parse2(tokens).expect("generated method shim");
    let syn::GenericParam::Type(implementation) =
        shim.sig.generics.params.pop().unwrap().into_value()
    else {
        unreachable!("the final generated parameter is __ImplT")
    };
    let bounds = implementation.bounds;
    shim.sig
        .generics
        .make_where_clause()
        .predicates
        .push(syn::parse_quote!(Self: ::core::marker::Sized + #bounds));
    ImplTypeToSelf.visit_trait_item_fn_mut(&mut shim);
    shim
}

/// Information extracted from a trait method for code generation.
///
/// Collects everything needed to generate vtable shims, view methods,
/// and extra trait bounds for a single method in a `#[miniextendr]` trait.
#[derive(Debug)]
struct MethodInfo {
    /// Method name (Rust identifier).
    name: syn::Ident,
    /// Whether the method has a self receiver (instance method).
    /// False for static/associated methods.
    has_self: bool,
    /// Whether receiver is `&mut self` (vs `&self`). Only meaningful if `has_self` is true.
    is_mut: bool,
    owner_receiver: Option<crate::trait_receiver::OwnerReceiver>,
    /// Parameter types (excluding the self receiver).
    param_types: Vec<syn::Type>,
    /// Parameter names (excluding the self receiver). Uses `arg{i}` for unnamed patterns.
    param_names: Vec<syn::Ident>,
    /// Return type. `None` when the method returns `()` (unit type or no return annotation).
    return_type: Option<syn::Type>,
    /// Whether method is marked `#[miniextendr(skip)]`, excluding it from codegen.
    skip: bool,
    /// Override the R-facing method name (from `#[miniextendr(r_name = "...")]`).
    /// When set, R wrappers and TPIE metadata use this name instead of the Rust ident.
    r_name: Option<String>,
}

// region: Self-type detection helpers

/// Check if a type syntactically contains `Self`.
///
/// Used to detect when a method returns `Self` (or `Option<Self>`, `Vec<Self>`, etc.)
/// so the generated shim can add `IntoR` bounds.
fn type_contains_self(ty: &syn::Type) -> bool {
    match ty {
        syn::Type::Path(tp) => {
            for seg in &tp.path.segments {
                if seg.ident == "Self" {
                    return true;
                }
                if let syn::PathArguments::AngleBracketed(args) = &seg.arguments {
                    for arg in &args.args {
                        if let syn::GenericArgument::Type(inner) = arg
                            && type_contains_self(inner)
                        {
                            return true;
                        }
                    }
                }
            }
            false
        }
        syn::Type::Reference(r) => type_contains_self(&r.elem),
        syn::Type::Tuple(t) => t.elems.iter().any(type_contains_self),
        syn::Type::Slice(s) => type_contains_self(&s.elem),
        syn::Type::Array(a) => type_contains_self(&a.elem),
        syn::Type::Paren(p) => type_contains_self(&p.elem),
        _ => false,
    }
}

/// Check if a type syntactically contains `Self::AssocType` for a given associated type name.
///
/// Recursively walks the type tree looking for a 2-segment path where the first
/// segment is `Self` and the second matches `assoc_name` (e.g., `Self::Item`).
/// Used to determine whether extra `where` bounds are needed for associated types.
fn type_contains_self_assoc(ty: &syn::Type, assoc_name: &syn::Ident) -> bool {
    match ty {
        syn::Type::Path(tp) => {
            if tp.path.segments.len() == 2
                && tp.path.segments[0].ident == "Self"
                && tp.path.segments[1].ident == *assoc_name
            {
                return true;
            }
            for seg in &tp.path.segments {
                if let syn::PathArguments::AngleBracketed(args) = &seg.arguments {
                    for arg in &args.args {
                        if let syn::GenericArgument::Type(inner) = arg
                            && type_contains_self_assoc(inner, assoc_name)
                        {
                            return true;
                        }
                    }
                }
            }
            false
        }
        syn::Type::Reference(r) => type_contains_self_assoc(&r.elem, assoc_name),
        syn::Type::Tuple(t) => t
            .elems
            .iter()
            .any(|e| type_contains_self_assoc(e, assoc_name)),
        syn::Type::Slice(s) => type_contains_self_assoc(&s.elem, assoc_name),
        syn::Type::Array(a) => type_contains_self_assoc(&a.elem, assoc_name),
        syn::Type::Paren(p) => type_contains_self_assoc(&p.elem, assoc_name),
        _ => false,
    }
}

/// Rewrite `Self` and `Self::AssocType` in a type tree to use `__ImplT`.
///
/// Transforms:
/// - `Self` → `__ImplT`
/// - `Self::Item` → `<__ImplT as TraitName>::Item`
/// - Recursively processes generic arguments (e.g., `Option<Self::Item>` →
///   `Option<<__ImplT as TraitName>::Item>`)
fn rewrite_self_in_type(
    ty: &syn::Type,
    trait_name: &syn::Ident,
    assoc_types: &[&syn::Ident],
) -> syn::Type {
    match ty {
        syn::Type::Path(tp) => {
            // Check for Self::AssocType (2-segment path: Self::Item)
            if tp.path.segments.len() == 2
                && tp.path.segments[0].ident == "Self"
                && assoc_types.iter().any(|a| *a == &tp.path.segments[1].ident)
            {
                let assoc = &tp.path.segments[1].ident;
                let impl_t = quote::format_ident!("__ImplT");
                return syn::parse_quote!(<#impl_t as #trait_name>::#assoc);
            }
            // Check for bare Self
            if tp.path.is_ident("Self") {
                let impl_t = quote::format_ident!("__ImplT");
                return syn::parse_quote!(#impl_t);
            }
            // Recursively process generic args
            let mut new_tp = tp.clone();
            for seg in &mut new_tp.path.segments {
                if let syn::PathArguments::AngleBracketed(args) = &mut seg.arguments {
                    for arg in &mut args.args {
                        if let syn::GenericArgument::Type(inner) = arg {
                            *inner = rewrite_self_in_type(inner, trait_name, assoc_types);
                        }
                    }
                }
            }
            syn::Type::Path(new_tp)
        }
        syn::Type::Reference(r) => {
            let mut new_r = r.clone();
            new_r.elem = Box::new(rewrite_self_in_type(&r.elem, trait_name, assoc_types));
            syn::Type::Reference(new_r)
        }
        syn::Type::Tuple(t) => {
            let mut new_t = t.clone();
            for elem in &mut new_t.elems {
                *elem = rewrite_self_in_type(elem, trait_name, assoc_types);
            }
            syn::Type::Tuple(new_t)
        }
        syn::Type::Slice(s) => {
            let mut new_s = s.clone();
            new_s.elem = Box::new(rewrite_self_in_type(&s.elem, trait_name, assoc_types));
            syn::Type::Slice(new_s)
        }
        syn::Type::Array(a) => {
            let mut new_a = a.clone();
            new_a.elem = Box::new(rewrite_self_in_type(&a.elem, trait_name, assoc_types));
            syn::Type::Array(new_a)
        }
        syn::Type::Paren(p) => {
            let mut new_p = p.clone();
            new_p.elem = Box::new(rewrite_self_in_type(&p.elem, trait_name, assoc_types));
            syn::Type::Paren(new_p)
        }
        _ => ty.clone(),
    }
}

/// Check if a type syntactically contains a specific identifier.
///
/// Used to detect trait type parameters (like `T`) in method signatures so that
/// appropriate `TryFromSexp` or `IntoR` bounds can be added. Recursively walks
/// through path segments, generic arguments, references, tuples, slices, and arrays.
fn type_contains_ident(ty: &syn::Type, ident: &syn::Ident) -> bool {
    match ty {
        syn::Type::Path(tp) => {
            if tp.path.segments.len() == 1 && tp.path.segments[0].ident == *ident {
                return true;
            }
            for seg in &tp.path.segments {
                if let syn::PathArguments::AngleBracketed(args) = &seg.arguments {
                    for arg in &args.args {
                        if let syn::GenericArgument::Type(inner) = arg
                            && type_contains_ident(inner, ident)
                        {
                            return true;
                        }
                    }
                }
            }
            false
        }
        syn::Type::Reference(r) => type_contains_ident(&r.elem, ident),
        syn::Type::Tuple(t) => t.elems.iter().any(|e| type_contains_ident(e, ident)),
        syn::Type::Slice(s) => type_contains_ident(&s.elem, ident),
        syn::Type::Array(a) => type_contains_ident(&a.elem, ident),
        syn::Type::Paren(p) => type_contains_ident(&p.elem, ident),
        _ => false,
    }
}

/// Extra trait bounds inferred from method signatures.
///
/// For generic traits and methods that reference `Self` or associated types,
/// the generated shim and vtable builder functions need additional bounds
/// beyond `__ImplT: TraitName`. This struct collects those bounds.
struct ExtraBounds {
    /// Bounds added directly to `__ImplT` (e.g., `IntoR` when methods return `Self`,
    /// or `TypedExternal + Send + 'static` when methods take `&Self` parameters).
    impl_bounds: Vec<TokenStream>,
    /// Where clause predicates for complex types (e.g.,
    /// `<__ImplT as Trait>::Item: IntoR` or `Vec<T>: TryFromSexp`).
    where_predicates: Vec<TokenStream>,
}

/// Compute extra bounds needed for the shim and build_vtable functions.
///
/// - Methods returning `Self` → `__ImplT: IntoR`
/// - Methods with `&Self` params → `__ImplT: TypedExternal + Send + 'static`
/// - Methods returning types with `Self::AssocType` or trait type params →
///   full rewritten return type `: IntoR` (e.g., `Nullable<<__ImplT as RIterator>::Item>: IntoR`)
/// - Methods with trait type params in params →
///   full param type `: TryFromSexp` (e.g., `Vec<T>: TryFromSexp`)
fn compute_extra_bounds(
    methods: &[MethodInfo],
    trait_name: &syn::Ident,
    assoc_types: &[&syn::Ident],
    trait_param_idents: &[&syn::Ident],
) -> ExtraBounds {
    let mut impl_bounds = Vec::new();
    let mut where_predicates = Vec::new();

    let mut needs_into_r = false;
    let mut needs_typed_external = false;
    let needs_owner = methods.iter().any(|method| method.owner_receiver.is_some());

    // Track full types needing bounds (deduplicated by token string)
    let mut return_type_bound_keys: std::collections::BTreeMap<String, syn::Type> =
        Default::default();
    let mut param_type_bound_keys: std::collections::BTreeMap<String, syn::Type> =
        Default::default();

    for method in methods {
        // Bare Self in returns → __ImplT: IntoR (as impl bound)
        if method.return_type.as_ref().is_some_and(type_contains_self) {
            needs_into_r = true;
        }
        // &Self in params → __ImplT: TypedExternal + 'static
        if method
            .param_types
            .iter()
            .any(|ty| crate::type_inspect::self_ref_mutability(ty).is_some())
        {
            needs_typed_external = true;
        }

        // Full return type bounds for Self::AssocType and/or trait type params.
        // Instead of bare `<__ImplT as Trait>::Item: IntoR`, we add the FULL rewritten
        // return type: `Option<<__ImplT as Trait>::Item>: IntoR`, `Vec<T>: IntoR`, etc.
        // This is required because IntoR impls are concrete (no blanket `Option<T: IntoR>: IntoR`).
        if let Some(ref ret_ty) = method.return_type {
            let has_assoc = assoc_types
                .iter()
                .any(|a| type_contains_self_assoc(ret_ty, a));
            let has_param = trait_param_idents
                .iter()
                .any(|p| type_contains_ident(ret_ty, p));
            if has_assoc || has_param {
                let rewritten = rewrite_self_in_type(ret_ty, trait_name, assoc_types);
                let key = quote::quote!(#rewritten).to_string();
                return_type_bound_keys.entry(key).or_insert(rewritten);
            }
        }

        // Full param type bounds for trait type params.
        // Instead of bare `T: TryFromSexp`, we add `Vec<T>: TryFromSexp` etc.
        for param_ty in &method.param_types {
            if crate::type_inspect::self_ref_mutability(param_ty).is_none() {
                let has_param = trait_param_idents
                    .iter()
                    .any(|p| type_contains_ident(param_ty, p));
                if has_param {
                    let key = quote::quote!(#param_ty).to_string();
                    param_type_bound_keys.entry(key).or_insert(param_ty.clone());
                }
            }
        }
    }

    if needs_into_r {
        impl_bounds.push(quote::quote! { ::miniextendr_api::IntoR });
    }
    if needs_typed_external {
        impl_bounds.push(
            quote::quote! { ::miniextendr_api::TypedExternal + ::core::marker::Send + 'static },
        );
    }

    if needs_owner && !needs_typed_external {
        impl_bounds.push(quote::quote! { ::miniextendr_api::TypedExternal });
    }

    // Add full return type bounds: RewrittenType: IntoR
    for ty in return_type_bound_keys.values() {
        where_predicates.push(quote::quote! {
            #ty: ::miniextendr_api::IntoR
        });
    }

    // Add full param type bounds: ParamType: TryFromSexp, Error: Display
    for ty in param_type_bound_keys.values() {
        where_predicates.push(quote::quote! {
            #ty: ::miniextendr_api::TryFromSexp
        });
        where_predicates.push(quote::quote! {
            <#ty as ::miniextendr_api::TryFromSexp>::Error: ::std::fmt::Display
        });
    }

    ExtraBounds {
        impl_bounds,
        where_predicates,
    }
}

/// Build combined where predicates from the trait's own where clause and computed extra bounds.
///
/// Merges the original trait-level where clause predicates with the extra
/// bounds computed from method signatures (e.g., `IntoR` for return types,
/// `TryFromSexp` for parameters containing trait type params).
///
/// Returns a flat list of predicates suitable for use in a `where` clause.
fn build_where_predicates(
    trait_where_clause: &Option<syn::WhereClause>,
    extra_bounds: &ExtraBounds,
) -> Vec<TokenStream> {
    let mut all = Vec::new();
    if let Some(wc) = trait_where_clause {
        for pred in &wc.predicates {
            all.push(quote::quote! { #pred });
        }
    }
    all.extend(extra_bounds.where_predicates.iter().cloned());
    all
}

/// Extract method information from a trait method definition.
///
/// Parses the method signature to determine receiver type, parameter names/types,
/// return type, and any `#[miniextendr(...)]` attributes like `skip` and `r_name`.
/// Parameters with non-ident patterns are assigned synthetic names (`arg0`, `arg1`, etc.).
fn extract_method_info(method: &syn::TraitItemFn) -> syn::Result<MethodInfo> {
    let name = method.sig.ident.clone();

    // Check for #[miniextendr(skip)] and #[miniextendr(r_name = "...")]
    let mut skip = false;
    let mut r_name: Option<String> = None;
    for attr in &method.attrs {
        if !attr.path().is_ident("miniextendr") {
            continue;
        }
        attr.parse_nested_meta(|meta| {
            if meta.path.is_ident("skip") {
                skip = true;
            } else if meta.path.is_ident("r_name") {
                let value: syn::LitStr = meta.value()?.parse()?;
                r_name = Some(value.value());
            } else if meta.path.is_ident("formal") {
                return Err(meta.error(crate::miniextendr_fn::TRAIT_FORMAL_UNSUPPORTED));
            } else {
                return Err(meta.error(
                    "unknown #[miniextendr] option on trait method; expected `skip` or `r_name`",
                ));
            }
            Ok(())
        })?;
    }

    // Check for receiver
    let (has_self, is_mut) = method.sig.inputs.first().map_or((false, false), |arg| {
        if let syn::FnArg::Receiver(_) = arg {
            (true, crate::trait_receiver::is_mut(&method.sig))
        } else {
            (false, false)
        }
    });

    // Extract parameters (skip self if present)
    let skip_count = if has_self { 1 } else { 0 };
    let mut param_types = Vec::new();
    let mut param_names = Vec::new();
    for (i, arg) in method.sig.inputs.iter().skip(skip_count).enumerate() {
        if let syn::FnArg::Typed(pat_type) = arg {
            if crate::return_wrap::contains_marker(&pat_type.ty) {
                return Err(syn::Error::new_spanned(
                    &pat_type.ty,
                    "class return markers are return-position only",
                ));
            }
            // `Checked<T>` / `Unchecked<T>` (#1566) steer an R wrapper's type
            // checks, and a trait's View passes arguments on as R values: the
            // wrappers belong to each impl, which says it there.
            let (markers, _) = crate::type_inspect::peel_param_markers(&pat_type.ty)?;
            if let Some(marker) = markers.first() {
                let name = match pat_type.pat.as_ref() {
                    syn::Pat::Ident(pat_ident) => crate::naming::ident_name(&pat_ident.ident),
                    _ => "x".to_string(),
                };
                return Err(syn::Error::new_spanned(
                    &pat_type.ty,
                    format!(
                        "`{}<T>` in a `#[miniextendr]` trait method: the trait's View passes \
                         arguments on as R values, and each impl's wrapper checks them; spell it \
                         on the impl, `#[miniextendr({}({name}))]`",
                        marker.name(),
                        if marker.preconditions() == Some(true) {
                            "preconditions"
                        } else {
                            "no_preconditions"
                        },
                    ),
                ));
            }
            param_types.push((*pat_type.ty).clone());
            if let syn::Pat::Ident(pat_ident) = pat_type.pat.as_ref() {
                param_names.push(pat_ident.ident.clone());
            } else {
                param_names.push(quote::format_ident!("arg{}", i));
            }
        }
    }

    // Extract return type. A visibility marker (`Invisible<T>` / `Visible<T>`,
    // #1213) only steers the implementing package's R wrapper; the View and
    // the vtable bounds work on the inner type.
    let return_type = match &method.sig.output {
        syn::ReturnType::Default => None,
        syn::ReturnType::Type(_, ty) => {
            if let Some(err) = crate::type_inspect::visibility_marker_error(ty, "return") {
                return Err(err);
            }
            let (_, ty) = crate::type_inspect::peel_visibility_marker(ty);
            let output: syn::ReturnType = syn::parse_quote!(-> #ty);
            let (wrap, output) = crate::return_wrap::resolve(&output, None)?;
            if wrap.as_ref().is_some_and(|wrap| wrap.conversion.is_some()) {
                return Err(syn::Error::new_spanned(
                    ty,
                    "ConvertTo/ConvertFrom require an inherent S7 impl method",
                ));
            }
            let syn::ReturnType::Type(_, ty) = output else {
                unreachable!()
            };
            let ty = ty.as_ref();
            // Check if it's unit type ()
            if matches!(ty, syn::Type::Tuple(t) if t.elems.is_empty()) {
                None
            } else {
                Some(ty.clone())
            }
        }
    };

    Ok(MethodInfo {
        name,
        has_self,
        is_mut,
        owner_receiver: crate::trait_receiver::owner_receiver(&method.sig),
        param_types,
        param_names,
        return_type,
        skip,
        r_name,
    })
}

#[cfg(test)]
mod tests;
// endregion