fidius-macro 0.4.0

// Copyright 2026 Colliery, Inc.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

//! Code generation for `#[plugin_impl(TraitName)]`.
//!
//! Generates: the original impl, extern "C" FFI shims, a static instance,
//! a populated vtable static, a PluginDescriptor static, and for single-plugin
//! dylibs, the FIDIUS_PLUGIN_REGISTRY.

use proc_macro2::TokenStream;
use quote::{format_ident, quote};
use syn::{
    parse::Parse, parse::ParseStream, FnArg, Ident, ImplItem, ItemImpl, LitStr, Pat, Path,
    ReturnType, Token, Type,
};

use crate::ir::BufferStrategyAttr;

/// Info about an impl method, extracted from the impl block.
struct MethodInfo<'a> {
    name: &'a Ident,
    is_async: bool,
    returns_result: bool,
    /// Argument types (excluding `self`).
    arg_types: Vec<&'a Type>,
    /// Argument names (excluding `self`).
    arg_names: Vec<Ident>,
    /// Whether the impl method carries `#[wire(raw)]`. Must match the
    /// interface trait's declaration; mismatch surfaces at plugin-load time
    /// as an interface-hash mismatch (the trait's `#[wire(raw)]` flips a
    /// `!raw` marker in the signature string the hash is computed over).
    wire_raw: bool,
    /// The method's return type, if any (`None` for `-> ()`). Used by the
    /// WASM component WIT generator (FIDIUS-T-0106).
    ret_type: Option<&'a Type>,
    /// For a server-streaming method (`-> fidius::Stream<T>`): the item type `T`
    /// (FIDIUS-I-0026). When `Some`, the WASM adapter emits a `resource`
    /// instead of a value-returning func, and the cdylib path is disabled.
    stream_item: Option<&'a Type>,
}

/// Detect a `#[wire(raw)]` attribute on an impl-side method. Mirrors the
/// trait-side parser in `ir.rs` — an explicit `raw` keyword is the only
/// supported form.
fn impl_method_is_raw(attrs: &[syn::Attribute]) -> syn::Result<bool> {
    for attr in attrs {
        if !attr.path().is_ident("wire") {
            continue;
        }
        let mut raw = false;
        attr.parse_nested_meta(|meta| {
            if meta.path.is_ident("raw") {
                raw = true;
                Ok(())
            } else {
                Err(meta.error("expected `raw` — only `#[wire(raw)]` is supported"))
            }
        })?;
        return Ok(raw);
    }
    Ok(false)
}

/// kebab-case → PascalCase, for deriving the wit-bindgen resource type name from
/// a method name: `tick` → resource `tick-stream` → `TickStream` (trait
/// `GuestTickStream`). (FIDIUS-I-0026.)
fn kebab_to_pascal(s: &str) -> String {
    s.split('-')
        .map(|seg| {
            let mut c = seg.chars();
            match c.next() {
                Some(f) => f.to_uppercase().collect::<String>() + c.as_str(),
                None => String::new(),
            }
        })
        .collect()
}

/// Check if a return type looks like `Result<T, ...>`.
fn is_result_type(ty: &Type) -> bool {
    if let Type::Path(type_path) = ty {
        type_path
            .path
            .segments
            .last()
            .map(|seg| seg.ident == "Result")
            .unwrap_or(false)
    } else {
        false
    }
}

/// Arguments to `#[plugin_impl(TraitName)]`, `#[plugin_impl(TraitName, crate = "...")]`,
/// or `#[plugin_impl(TraitName, buffer = Arena)]`.
pub struct PluginImplAttrs {
    pub trait_name: Ident,
    /// The path to the fidius crate. Defaults to `fidius` when not specified.
    pub crate_path: Path,
    /// Must match the interface's `buffer` attribute. Defaults to
    /// `PluginAllocated`. Mismatches produce a vtable fn-pointer type error
    /// at compile time (the emitted shim's signature won't match the
    /// generated vtable's field type).
    pub buffer_strategy: BufferStrategyAttr,
}

impl Parse for PluginImplAttrs {
    fn parse(input: ParseStream) -> syn::Result<Self> {
        let trait_name: Ident = input.parse()?;
        let mut crate_path = None;
        let mut buffer_strategy = None;

        while !input.is_empty() {
            let _comma: Token![,] = input.parse()?;
            if input.peek(Token![crate]) {
                let _kw: Token![crate] = input.parse()?;
                let _eq: Token![=] = input.parse()?;
                let lit: LitStr = input.parse()?;
                let path: Path = lit.parse()?;
                crate_path = Some(path);
            } else {
                let key: Ident = input.parse()?;
                let _eq: Token![=] = input.parse()?;
                match key.to_string().as_str() {
                    "buffer" => {
                        let value: Ident = input.parse()?;
                        buffer_strategy = Some(match value.to_string().as_str() {
                            "PluginAllocated" => BufferStrategyAttr::PluginAllocated,
                            "Arena" => BufferStrategyAttr::Arena,
                            _ => {
                                return Err(syn::Error::new(
                                    value.span(),
                                    "expected PluginAllocated or Arena",
                                ))
                            }
                        });
                    }
                    other => {
                        return Err(syn::Error::new(
                            key.span(),
                            format!("unknown plugin_impl attribute `{other}`"),
                        ));
                    }
                }
            }
        }

        let crate_path = crate_path.unwrap_or_else(|| syn::parse_str::<Path>("fidius").unwrap());
        let buffer_strategy = buffer_strategy.unwrap_or(BufferStrategyAttr::PluginAllocated);

        Ok(PluginImplAttrs {
            trait_name,
            crate_path,
            buffer_strategy,
        })
    }
}

/// Generate all code for a `#[plugin_impl(TraitName)]` invocation.
pub fn generate_plugin_impl(attrs: &PluginImplAttrs, item: &ItemImpl) -> syn::Result<TokenStream> {
    let trait_name = &attrs.trait_name;
    let impl_type = &item.self_ty;

    // Extract the type name as a string for naming
    let impl_type_str = quote!(#impl_type).to_string().replace(' ', "");
    let impl_ident = format_ident!("{}", impl_type_str);

    // Collect method info from the impl block
    let mut impl_methods: Vec<MethodInfo> = Vec::new();
    for impl_item in &item.items {
        if let ImplItem::Fn(method) = impl_item {
            let ret_type: Option<&Type> = match &method.sig.output {
                ReturnType::Type(_, ty) => Some(ty.as_ref()),
                ReturnType::Default => None,
            };
            // Server-streaming (`-> fidius::Stream<T>`): the WASM adapter emits a
            // resource; the cdylib path is disabled for this plugin (handled in
            // the codegen below). (FIDIUS-I-0026.)
            let stream_item = ret_type.and_then(crate::wit::stream_item_type);
            let returns_result = ret_type.map(is_result_type).unwrap_or(false);
            let mut arg_types = Vec::new();
            let mut arg_names = Vec::new();
            for arg in &method.sig.inputs {
                if let FnArg::Typed(pat_type) = arg {
                    arg_types.push(pat_type.ty.as_ref());
                    if let Pat::Ident(pat_ident) = pat_type.pat.as_ref() {
                        arg_names.push(pat_ident.ident.clone());
                    } else {
                        arg_names.push(format_ident!("_arg"));
                    }
                }
            }
            let wire_raw = impl_method_is_raw(&method.attrs)?;
            impl_methods.push(MethodInfo {
                name: &method.sig.ident,
                is_async: method.sig.asyncness.is_some(),
                returns_result,
                arg_types,
                arg_names,
                wire_raw,
                ret_type,
                stream_item,
            });
        }
    }

    let method_names: Vec<&Ident> = impl_methods.iter().map(|m| m.name).collect();
    let _has_async = impl_methods.iter().any(|m| m.is_async);

    let crate_path = &attrs.crate_path;
    let buffer_strategy = attrs.buffer_strategy;

    // Server-streaming methods (`-> fidius::Stream<T>`, FIDIUS-I-0026) require the
    // PluginAllocated buffer strategy on the cdylib path (the iterator-handle ABI
    // and per-item Box<[u8]> allocation are PluginAllocated-shaped; Arena
    // streaming is out of scope). Fail at macro time — this is a structural
    // misconfiguration, not target-dependent.
    let any_streaming = impl_methods.iter().any(|m| m.stream_item.is_some());
    if any_streaming && matches!(buffer_strategy, BufferStrategyAttr::Arena) {
        return Err(syn::Error::new(
            proc_macro2::Span::call_site(),
            "server-streaming methods (`-> fidius::Stream<T>`) require the PluginAllocated \
             buffer strategy; the Arena strategy does not support streaming.",
        ));
    }

    // Strip `#[wire(...)]` helper attrs from the re-emitted impl block so the
    // Rust compiler doesn't reject them as unknown attributes.
    let mut item_emit = item.clone();
    for impl_item in &mut item_emit.items {
        if let ImplItem::Fn(method) = impl_item {
            method.attrs.retain(|a| !a.path().is_ident("wire"));
        }
    }

    // Generate static instance
    let instance_name = format_ident!("__FIDIUS_INSTANCE_{}", impl_ident);
    let instance = quote! {
        static #instance_name: #impl_type = #impl_type;
    };

    // WASM Component Model auto-export (FIDIUS-T-0106). Emitted under
    // `#[cfg(target_family = "wasm")]`; handles both unary and (FIDIUS-I-0026)
    // server-streaming methods. cdylib/Python builds cfg this out entirely.
    let wasm_adapter = generate_wasm_adapter(trait_name, &instance_name, &impl_methods);

    // The cdylib FFI machinery — shims (unary or, for streaming methods, the
    // iterator-handle init/next/drop), vtable, descriptor, registration. All
    // gated `#[cfg(not(target_family = "wasm"))]` inside; a wasm build uses the
    // adapter above instead.
    let cdylib = {
        let shims = generate_shims(&impl_ident, &impl_methods, crate_path, buffer_strategy);
        let free_fn_name = format_ident!("__fidius_free_buffer_{}", impl_ident);
        let free_buffer = match buffer_strategy {
            BufferStrategyAttr::PluginAllocated => quote! {
                #[cfg(not(target_family = "wasm"))]
                unsafe extern "C" fn #free_fn_name(ptr: *mut u8, len: usize) {
                    if !ptr.is_null() && len > 0 {
                        // Reconstruct the Box<[u8]> from its raw parts. Safe because the
                        // shim emitted by generate_shims always allocates output as a
                        // Box<[u8]> (cap == len by construction — no mismatch possible).
                        // Streaming item buffers use the same contract.
                        unsafe {
                            let slice = std::slice::from_raw_parts_mut(ptr, len);
                            drop(Box::from_raw(slice as *mut [u8]));
                        }
                    }
                }
            },
            BufferStrategyAttr::Arena => quote! {},
        };
        let vtable = generate_vtable_static(trait_name, &impl_ident, &method_names);
        let descriptor = generate_descriptor(
            trait_name,
            &impl_ident,
            &method_names,
            crate_path,
            buffer_strategy,
        );
        let registration = generate_inventory_registration(&impl_ident, crate_path);
        quote! {
            #shims
            #free_buffer
            #vtable
            #descriptor
            #registration
        }
    };

    Ok(quote! {
        #item_emit
        #instance
        #cdylib
        #wasm_adapter
    })
}

/// Generate the WASM component auto-export adapter for `#[plugin_impl]`.
///
/// Emits, under `#[cfg(target_family = "wasm")]`, a `wit_bindgen::generate!`
/// invocation (inline WIT generated from the method signatures) plus a `Guest`
/// impl that forwards to the plugin's static instance, and `export!`. If any
/// method has a reference argument or a type outside the supported set, it
/// instead emits a wasm-gated `compile_error!` (a clear failure on wasm builds;
/// a no-op on cdylib/Python builds where the whole adapter is cfg'd out).
fn generate_wasm_adapter(
    trait_name: &Ident,
    instance_name: &Ident,
    methods: &[MethodInfo],
) -> TokenStream {
    use crate::wit::{
        conv_expr, render_wit, result_ok_type, return_to_wit, return_to_wit_with, rust_type_to_wit,
        to_kebab_case, wit_type_with, WitMethod,
    };
    use std::collections::BTreeSet;

    let iface_kebab = to_kebab_case(&trait_name.to_string());
    let iface_snake = iface_kebab.replace('-', "_");
    let pkg_seg = format_ident!("{}", iface_snake);
    let world = format!("{iface_kebab}-plugin");
    // The interface-hash const lives in the `#[plugin_interface]` companion
    // module (`__fidius_<Trait>`), a sibling of the impl — reference it there.
    let companion = format_ident!("__fidius_{}", trait_name);
    let hash_const = format_ident!("{}_INTERFACE_HASH", trait_name);
    let module_ident = format_ident!("__fidius_wasm_{}", instance_name);

    // Collect candidate user types (non-primitive path idents in signatures;
    // `#[derive(WitType)]` records/variants). Reject reference args (owned only,
    // v1). Then validate every type maps to WIT — a structurally-unsupported
    // type emits a wasm-gated compile_error rather than a silently-broken export.
    let mut known: BTreeSet<String> = BTreeSet::new();
    for m in methods {
        for ty in &m.arg_types {
            if matches!(ty, Type::Reference(_)) {
                return wasm_unsupported(
                    m.name,
                    "reference arguments are not supported — take owned types (String, Vec<u8>, …)",
                );
            }
            collect_user_idents(ty, &mut known);
        }
        // For a streaming method, classify the stream *item* type, not the
        // `Stream<T>` wrapper (which isn't a WIT type). (FIDIUS-I-0026.)
        if let Some(item) = m.stream_item {
            collect_user_idents(item, &mut known);
        } else if m.returns_result {
            if let Some(ok) = m.ret_type.and_then(result_ok_type) {
                collect_user_idents(ok, &mut known);
            }
        } else if let Some(rt) = m.ret_type {
            collect_user_idents(rt, &mut known);
        }
    }
    for m in methods {
        for ty in &m.arg_types {
            if let Err(e) = wit_type_with(ty, &known) {
                return wasm_unsupported(m.name, &e);
            }
        }
        if let Some(item) = m.stream_item {
            if let Err(e) = wit_type_with(item, &known) {
                return wasm_unsupported(m.name, &e);
            }
        } else if let Err(e) = return_to_wit_with(m.ret_type, &known) {
            return wasm_unsupported(m.name, &e);
        }
    }

    let has_user = !known.is_empty();

    // v1 scope: server-streaming is supported only with primitive/String item
    // types and only in interfaces with no `#[derive(WitType)]` user types. The
    // build.rs/user-type streaming path is a follow-on.
    if has_user {
        if let Some(m) = methods.iter().find(|m| m.stream_item.is_some()) {
            return wasm_unsupported(
                m.name,
                "server-streaming alongside #[derive(WitType)] user types is not yet supported; \
                 use a primitive or String stream item type in a user-type-free interface",
            );
        }
    }

    if !has_user {
        // ── Primitives-only: self-contained inline WIT (no build.rs needed). ──
        let mut wit_methods = Vec::new();
        for m in methods {
            let mut params = Vec::new();
            for (name, ty) in m.arg_names.iter().zip(&m.arg_types) {
                let wt = rust_type_to_wit(ty).expect("validated above");
                params.push((to_kebab_case(&name.to_string()), wt));
            }
            let (ret, stream_item) = if let Some(item) = m.stream_item {
                (None, Some(rust_type_to_wit(item).expect("validated above")))
            } else {
                (return_to_wit(m.ret_type).expect("validated above"), None)
            };
            wit_methods.push(WitMethod {
                name: to_kebab_case(&m.name.to_string()),
                params,
                ret,
                stream_item,
            });
        }
        let wit_doc = render_wit(&iface_kebab, &wit_methods);

        // Items inside `impl Guest` (fns + streaming `type` decls), plus
        // module-level resource defs (struct + `Guest<M>Stream` impl) for each
        // streaming method.
        let mut guest_items: Vec<TokenStream> = Vec::new();
        let mut resource_defs: Vec<TokenStream> = Vec::new();
        for m in methods {
            let mname = m.name;
            let arg_names = &m.arg_names;
            let arg_types = &m.arg_types;

            if let Some(item) = m.stream_item {
                // Server-streaming → a wit-bindgen exported resource. Resource
                // `<m>-stream` → Pascal `<M>Stream`, trait `Guest<M>Stream`.
                let res_pascal =
                    kebab_to_pascal(&format!("{}-stream", to_kebab_case(&mname.to_string())));
                let res_ident = format_ident!("{}", res_pascal);
                let guest_trait = format_ident!("Guest{}", res_pascal);
                let state_ident = format_ident!("__Fidius{}", res_pascal);
                let stream_ty = m.ret_type.expect("streaming method has a return type");

                resource_defs.push(quote! {
                    struct #state_ident {
                        stream: ::core::cell::RefCell<#stream_ty>,
                    }
                    impl exports::fidius::#pkg_seg::#pkg_seg::#guest_trait for #state_ident {
                        fn next(&self) -> ::core::result::Result<
                            ::core::option::Option<#item>,
                            exports::fidius::#pkg_seg::#pkg_seg::PluginError,
                        > {
                            ::core::result::Result::Ok(self.stream.borrow_mut().next_item())
                        }
                    }
                });
                guest_items.push(quote! {
                    type #res_ident = #state_ident;
                    fn #mname(#(#arg_names: #arg_types),*)
                        -> exports::fidius::#pkg_seg::#pkg_seg::#res_ident {
                        let __s = super::#instance_name.#mname(#(#arg_names),*);
                        exports::fidius::#pkg_seg::#pkg_seg::#res_ident::new(
                            #state_ident { stream: ::core::cell::RefCell::new(__s) }
                        )
                    }
                });
            } else {
                let call = quote! { super::#instance_name.#mname(#(#arg_names),*) };
                if m.returns_result {
                    let ok = match m.ret_type.and_then(result_ok_type) {
                        Some(t) => quote! { #t },
                        None => quote! { () },
                    };
                    guest_items.push(quote! {
                        fn #mname(#(#arg_names: #arg_types),*)
                            -> Result<#ok, exports::fidius::#pkg_seg::#pkg_seg::PluginError> {
                            #call.map_err(|__e| exports::fidius::#pkg_seg::#pkg_seg::PluginError {
                                code: __e.code, message: __e.message, details: __e.details,
                            })
                        }
                    });
                } else {
                    match m.ret_type {
                        Some(rt) => guest_items.push(
                            quote! { fn #mname(#(#arg_names: #arg_types),*) -> #rt { #call } },
                        ),
                        None => guest_items
                            .push(quote! { fn #mname(#(#arg_names: #arg_types),*) { #call } }),
                    }
                }
            }
        }
        return quote! {
            #[cfg(target_family = "wasm")]
            #[allow(warnings, clippy::all)]
            mod #module_ident {
                use super::*;
                ::wit_bindgen::generate!({ inline: #wit_doc, world: #world });
                #(#resource_defs)*
                struct __FidiusComponent;
                impl exports::fidius::#pkg_seg::#pkg_seg::Guest for __FidiusComponent {
                    #(#guest_items)*
                    fn fidius_interface_hash() -> u64 { super::#companion::#hash_const }
                }
                export!(__FidiusComponent);
            }
        };
    }

    // ── User types present: consume the build.rs-generated wit/ + conversions. ──
    // The Guest uses wit-bindgen's generated types; we convert at the boundary
    // via the generated `From` impls (`conv_expr` is identity for primitive-only
    // fields and `.into()`/map for user types).
    let guest_methods: Vec<TokenStream> = methods
        .iter()
        .map(|m| {
            let mname = m.name;
            let arg_sig: Vec<TokenStream> = m
                .arg_names
                .iter()
                .zip(&m.arg_types)
                .map(|(n, t)| {
                    let gt = gen_type(t, &known, &pkg_seg);
                    quote! { #n: #gt }
                })
                .collect();
            let call_args: Vec<syn::Expr> = m
                .arg_names
                .iter()
                .zip(&m.arg_types)
                .map(|(n, t)| {
                    let s = conv_expr(&n.to_string(), t, &known);
                    syn::parse_str::<syn::Expr>(&s).expect("conv expr parses")
                })
                .collect();
            let call = quote! { super::#instance_name.#mname(#(#call_args),*) };
            if m.returns_result {
                let ok = m.ret_type.and_then(result_ok_type);
                let gen_ok = match ok {
                    Some(t) => gen_type(t, &known, &pkg_seg),
                    None => quote! { () },
                };
                let ok_map = match ok {
                    Some(t) => {
                        let e: syn::Expr =
                            syn::parse_str(&conv_expr("__v", t, &known)).expect("conv expr");
                        quote! { .map(|__v| #e) }
                    }
                    None => quote! {},
                };
                quote! {
                    fn #mname(#(#arg_sig),*)
                        -> Result<#gen_ok, exports::fidius::#pkg_seg::#pkg_seg::PluginError> {
                        #call #ok_map .map_err(|__e| exports::fidius::#pkg_seg::#pkg_seg::PluginError {
                            code: __e.code, message: __e.message, details: __e.details,
                        })
                    }
                }
            } else {
                match m.ret_type {
                    Some(rt) => {
                        let gen_ret = gen_type(rt, &known, &pkg_seg);
                        let e: syn::Expr =
                            syn::parse_str(&conv_expr("__r", rt, &known)).expect("conv expr");
                        quote! { fn #mname(#(#arg_sig),*) -> #gen_ret { let __r = #call; #e } }
                    }
                    None => quote! { fn #mname(#(#arg_sig),*) { #call } },
                }
            }
        })
        .collect();

    quote! {
        #[cfg(target_family = "wasm")]
        #[allow(warnings, clippy::all)]
        mod #module_ident {
            use super::*;
            // wit/ + the conversions are (re)generated from source by the crate's
            // build.rs (`fidius_build::emit_wit()`), since a proc-macro can't see
            // external type definitions.
            ::wit_bindgen::generate!({ path: "wit", world: #world });
            include!(concat!(env!("OUT_DIR"), "/fidius_wit_conversions.rs"));
            struct __FidiusComponent;
            impl exports::fidius::#pkg_seg::#pkg_seg::Guest for __FidiusComponent {
                #(#guest_methods)*
                fn fidius_interface_hash() -> u64 { super::#companion::#hash_const }
            }
            export!(__FidiusComponent);
        }
    }
}

/// Collect candidate user-type idents (non-primitive path leaves) from a type,
/// descending through `Vec`/`Option`/`Box` and `Result`'s ok type.
fn collect_user_idents(ty: &Type, out: &mut std::collections::BTreeSet<String>) {
    match ty {
        Type::Reference(r) => collect_user_idents(&r.elem, out),
        Type::Slice(s) => collect_user_idents(&s.elem, out),
        Type::Path(p) => {
            if let Some(seg) = p.path.segments.last() {
                let id = seg.ident.to_string();
                let prim = matches!(
                    id.as_str(),
                    "bool"
                        | "i8"
                        | "i16"
                        | "i32"
                        | "i64"
                        | "u8"
                        | "u16"
                        | "u32"
                        | "u64"
                        | "f32"
                        | "f64"
                        | "char"
                        | "String"
                        | "str"
                        | "PluginError"
                );
                match id.as_str() {
                    "Vec" | "Option" | "Box" => {
                        if let Some(inner) = wasm_first_generic(seg) {
                            collect_user_idents(inner, out);
                        }
                    }
                    "Result" => {
                        if let Some(ok) = wasm_first_generic(seg) {
                            collect_user_idents(ok, out);
                        }
                    }
                    _ if !prim => {
                        out.insert(id);
                    }
                    _ => {}
                }
            }
        }
        _ => {}
    }
}

/// The wit-bindgen-generated type for an author type: identity for types holding
/// no user type (wit-bindgen uses the same Rust type), else the generated path
/// `exports::fidius::<iface>::<iface>::<T>`, recursing through `Vec`/`Option`.
fn gen_type(ty: &Type, known: &std::collections::BTreeSet<String>, pkg_seg: &Ident) -> TokenStream {
    if !crate::wit::contains_user_type(ty, known) {
        return quote! { #ty };
    }
    if let Type::Path(p) = ty {
        if let Some(seg) = p.path.segments.last() {
            let id = seg.ident.to_string();
            if id == "Vec" {
                if let Some(inner) = wasm_first_generic(seg) {
                    let g = gen_type(inner, known, pkg_seg);
                    return quote! { ::std::vec::Vec<#g> };
                }
            }
            if id == "Option" {
                if let Some(inner) = wasm_first_generic(seg) {
                    let g = gen_type(inner, known, pkg_seg);
                    return quote! { ::core::option::Option<#g> };
                }
            }
            if known.contains(&id) {
                let tid = &seg.ident;
                return quote! { exports::fidius::#pkg_seg::#pkg_seg::#tid };
            }
        }
    }
    quote! { #ty }
}

fn wasm_first_generic(seg: &syn::PathSegment) -> Option<&Type> {
    if let syn::PathArguments::AngleBracketed(ab) = &seg.arguments {
        for a in &ab.args {
            if let syn::GenericArgument::Type(t) = a {
                return Some(t);
            }
        }
    }
    None
}

/// Emit a `#[cfg(target_family = "wasm")]`-gated `compile_error!` for a method
/// the WASM auto-export can't handle. On native (cdylib/Python) builds the cfg
/// is false, so this is a no-op there; on a wasm build it fails the compile with
/// a clear message instead of silently producing a component that exports nothing.
fn wasm_unsupported(method: &Ident, reason: &str) -> TokenStream {
    let msg = format!(
        "fidius WASM auto-export: method `{method}` cannot be exported to a component — {reason}. \
         Supported types: bool, i8..i64, u8..u64, f32/f64, char, String, Vec<T>, Option<T>, \
         and Result<T, PluginError>. (User struct/enum support via #[derive(WitType)] is planned.)"
    );
    quote! {
        #[cfg(target_family = "wasm")]
        ::core::compile_error!(#msg);
    }
}

/// Generate extern "C" shim functions for each method. Shim signatures and
/// bodies vary by buffer strategy — see the two emit paths below.
fn generate_shims(
    impl_ident: &Ident,
    methods: &[MethodInfo],
    crate_path: &Path,
    buffer_strategy: BufferStrategyAttr,
) -> TokenStream {
    let instance_name = format_ident!("__FIDIUS_INSTANCE_{}", impl_ident);

    let shim_fns: Vec<TokenStream> = methods
        .iter()
        .map(|method| {
            let method_name = method.name;
            let shim_name = format_ident!("__fidius_shim_{}_{}", impl_ident, method_name);

            let arg_types = &method.arg_types;
            let arg_names = &method.arg_names;

            // Raw mode: skip bincode on the input. The single arg is a
            // Vec<u8> built directly from the FFI buffer (one alloc + memcpy).
            // Typed mode: deserialize input as a tuple of all argument types.
            let deserialize_args = if method.wire_raw {
                let arg_name = method
                    .arg_names
                    .first()
                    .cloned()
                    .unwrap_or_else(|| format_ident!("_arg"));
                quote! {
                    let #arg_name: ::std::vec::Vec<u8> = in_slice.to_vec();
                }
            } else {
                quote! {
                    let (#(#arg_names,)*) = match #crate_path::wire::deserialize::<(#(#arg_types,)*)>(in_slice) {
                        Ok(v) => v,
                        Err(_) => return #crate_path::status::STATUS_SERIALIZATION_ERROR,
                    };
                }
            };

            // Server-streaming (FIDIUS-I-0026 CS.1): the vtable slot holds an
            // `init` shim that returns a `FidiusStreamHandle` (via the standard
            // out_ptr); generated `next`/`drop_fn` drive and free it. Items cross
            // as self-describing JSON(`Value`). Requires PluginAllocated (enforced
            // in `generate_plugin_impl`).
            if let Some(item_ty) = method.stream_item {
                let stream_ty = method
                    .ret_type
                    .expect("a streaming method has a `-> fidius::Stream<T>` return type");
                let next_name = format_ident!("__fidius_snext_{}_{}", impl_ident, method_name);
                let drop_name = format_ident!("__fidius_sdrop_{}_{}", impl_ident, method_name);
                // Per-stream state = `StreamState<ItemTy>` (producer + the bincode
                // of the current item, retained across BUFFER_TOO_SMALL retries).
                let state_ty = quote! { #crate_path::stream_ffi::StreamState<#item_ty> };
                return quote! {
                    // Arena-style next (FIDIUS-T-0138): the host passes a reusable
                    // buffer; we write the bincode item into it. No per-item alloc,
                    // no `free_buffer` crossing.
                    #[cfg(not(target_family = "wasm"))]
                    unsafe extern "C" fn #next_name(
                        handle: *mut #crate_path::stream_ffi::FidiusStreamHandle,
                        buf_ptr: *mut u8,
                        buf_cap: u32,
                        out_len: *mut u32,
                    ) -> i32 {
                        let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
                            let __state = unsafe { &mut *((*handle).state as *mut #state_ty) };
                            let __buf = unsafe {
                                ::core::slice::from_raw_parts_mut(buf_ptr, buf_cap as usize)
                            };
                            match __state.next_into(__buf) {
                                #crate_path::stream_ffi::NextStatus::Item(__n) => {
                                    unsafe { *out_len = __n as u32; }
                                    #crate_path::status::STATUS_OK
                                }
                                #crate_path::stream_ffi::NextStatus::End => {
                                    #crate_path::status::STATUS_STREAM_END
                                }
                                #crate_path::stream_ffi::NextStatus::TooSmall(__need) => {
                                    unsafe { *out_len = __need as u32; }
                                    #crate_path::status::STATUS_BUFFER_TOO_SMALL
                                }
                                #crate_path::stream_ffi::NextStatus::SerErr => {
                                    #crate_path::status::STATUS_SERIALIZATION_ERROR
                                }
                            }
                        }));
                        match result {
                            ::core::result::Result::Ok(s) => s,
                            ::core::result::Result::Err(_) => #crate_path::status::STATUS_PANIC,
                        }
                    }

                    #[cfg(not(target_family = "wasm"))]
                    unsafe extern "C" fn #drop_name(
                        handle: *mut #crate_path::stream_ffi::FidiusStreamHandle,
                    ) {
                        if handle.is_null() { return; }
                        // Reclaim the handle box + the producer it owns (guest
                        // frees its own allocations — never the host).
                        unsafe {
                            let __h = Box::from_raw(handle);
                            drop(Box::from_raw(__h.state as *mut #state_ty));
                        }
                    }

                    #[cfg(not(target_family = "wasm"))]
                    unsafe extern "C" fn #shim_name(
                        in_ptr: *const u8,
                        in_len: u32,
                        out_ptr: *mut *mut u8,
                        out_len: *mut u32,
                    ) -> i32 {
                        let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
                            let in_slice = unsafe { std::slice::from_raw_parts(in_ptr, in_len as usize) };
                            #deserialize_args
                            let __stream: #stream_ty = #instance_name.#method_name(#(#arg_names),*);
                            let __state: Box<#state_ty> = Box::new(
                                #crate_path::stream_ffi::StreamState::new(__stream),
                            );
                            let __state = Box::into_raw(__state) as *mut ::core::ffi::c_void;
                            let __handle = Box::into_raw(Box::new(
                                #crate_path::stream_ffi::FidiusStreamHandle {
                                    next: #next_name,
                                    drop_fn: #drop_name,
                                    state: __state,
                                },
                            ));
                            unsafe { *out_ptr = __handle as *mut u8; *out_len = 0; }
                            #crate_path::status::STATUS_OK
                        }));
                        match result {
                            ::core::result::Result::Ok(s) => s,
                            ::core::result::Result::Err(_) => #crate_path::status::STATUS_PANIC,
                        }
                    }
                };
            }

            // The method call — either sync or async via block_on
            let method_call = if method.is_async {
                quote! {
                    #crate_path::async_runtime::FIDIUS_RUNTIME.block_on(
                        #instance_name.#method_name(#(#arg_names),*)
                    )
                }
            } else {
                quote! { #instance_name.#method_name(#(#arg_names),*) }
            };

            // Generate the output handling based on whether the method returns Result.
            // Raw mode bypasses bincode on the success payload (the Vec<u8> *is*
            // the wire payload). Error path still bincode-encodes for typed errors.
            let output_handling = if method.wire_raw {
                if method.returns_result {
                    quote! {
                        match output {
                            Ok(val) => (val, #crate_path::status::STATUS_OK),
                            Err(err) => {
                                match #crate_path::wire::serialize(&err) {
                                    Ok(v) => (v, #crate_path::status::STATUS_PLUGIN_ERROR),
                                    Err(_) => return #crate_path::status::STATUS_SERIALIZATION_ERROR,
                                }
                            }
                        }
                    }
                } else {
                    quote! { (output, #crate_path::status::STATUS_OK) }
                }
            } else if method.returns_result {
                quote! {
                    match output {
                        Ok(val) => {
                            match #crate_path::wire::serialize(&val) {
                                Ok(v) => (v, #crate_path::status::STATUS_OK),
                                Err(_) => return #crate_path::status::STATUS_SERIALIZATION_ERROR,
                            }
                        }
                        Err(err) => {
                            match #crate_path::wire::serialize(&err) {
                                Ok(v) => (v, #crate_path::status::STATUS_PLUGIN_ERROR),
                                Err(_) => return #crate_path::status::STATUS_SERIALIZATION_ERROR,
                            }
                        }
                    }
                }
            } else {
                quote! {
                    match #crate_path::wire::serialize(&output) {
                        Ok(v) => (v, #crate_path::status::STATUS_OK),
                        Err(_) => return #crate_path::status::STATUS_SERIALIZATION_ERROR,
                    }
                }
            };

            match buffer_strategy {
                BufferStrategyAttr::Arena => quote! {
                    #[cfg(not(target_family = "wasm"))]
                    unsafe extern "C" fn #shim_name(
                        in_ptr: *const u8,
                        in_len: u32,
                        arena_ptr: *mut u8,
                        arena_cap: u32,
                        out_offset: *mut u32,
                        out_len: *mut u32,
                    ) -> i32 {
                        let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
                            let in_slice = unsafe { std::slice::from_raw_parts(in_ptr, in_len as usize) };
                            #deserialize_args

                            let output = #method_call;

                            let (output_bytes, status) = #output_handling;

                            // Arena strategy: write into host-provided buffer.
                            // If too small, return BUFFER_TOO_SMALL with needed size.
                            if output_bytes.len() > arena_cap as usize {
                                unsafe {
                                    *out_len = output_bytes.len() as u32;
                                }
                                return #crate_path::status::STATUS_BUFFER_TOO_SMALL;
                            }
                            let arena = unsafe {
                                ::std::slice::from_raw_parts_mut(arena_ptr, arena_cap as usize)
                            };
                            arena[..output_bytes.len()].copy_from_slice(&output_bytes);
                            unsafe {
                                *out_offset = 0;
                                *out_len = output_bytes.len() as u32;
                            }
                            status
                        }));

                        match result {
                            Ok(status) => status,
                            Err(_panic_payload) => {
                                // Arena strategy cannot reliably transmit panic
                                // messages (the arena may be too small and we
                                // can't re-request from here). Return STATUS_PANIC
                                // with out_len = 0; host reports an opaque panic.
                                unsafe {
                                    *out_offset = 0;
                                    *out_len = 0;
                                }
                                #crate_path::status::STATUS_PANIC
                            }
                        }
                    }
                },
                BufferStrategyAttr::PluginAllocated => quote! {
                #[cfg(not(target_family = "wasm"))]
                unsafe extern "C" fn #shim_name(
                    in_ptr: *const u8,
                    in_len: u32,
                    out_ptr: *mut *mut u8,
                    out_len: *mut u32,
                ) -> i32 {
                    let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
                        let in_slice = unsafe { std::slice::from_raw_parts(in_ptr, in_len as usize) };
                        #deserialize_args

                        let output = #method_call;

                        let (output_bytes, status) = #output_handling;

                        // Hand ownership to the host via Box<[u8]>. cap == len
                        // by construction, so free_buffer's reconstruction is
                        // always well-defined.
                        let boxed: Box<[u8]> = output_bytes.into_boxed_slice();
                        let len = boxed.len();
                        let ptr = Box::into_raw(boxed) as *mut u8;
                        unsafe {
                            *out_ptr = ptr;
                            *out_len = len as u32;
                        }
                        status
                    }));

                    match result {
                        Ok(status) => status,
                        Err(panic_payload) => {
                            // Extract panic message and serialize into output buffer
                            let msg = panic_payload
                                .downcast_ref::<&str>()
                                .map(|s| s.to_string())
                                .or_else(|| panic_payload.downcast_ref::<String>().cloned())
                                .unwrap_or_else(|| "unknown panic".to_string());

                            if let Ok(msg_bytes) = #crate_path::wire::serialize(&msg) {
                                let boxed: Box<[u8]> = msg_bytes.into_boxed_slice();
                                let len = boxed.len();
                                let ptr = Box::into_raw(boxed) as *mut u8;
                                unsafe {
                                    *out_ptr = ptr;
                                    *out_len = len as u32;
                                }
                            }
                            #crate_path::status::STATUS_PANIC
                        }
                    }
                }
                },
            }
        })
        .collect();

    // cdylib FFI shims are only meaningful for native dynamic loading. Each
    // emitted shim carries its own `#[cfg(not(target_family = "wasm"))]` (a
    // streaming method emits three fns — init/next/drop — so the gate can't live
    // on the group), so a wasm component build (which exports via the WIT
    // adapter, not these extern "C" shims) doesn't compile them.
    quote! { #(#shim_fns)* }
}

/// Generate the static vtable with function pointers.
///
/// Uses the `new_{trait}` constructor generated by `#[plugin_interface]`,
/// which knows which fields are optional (Option<fn>) vs required (fn).
fn generate_vtable_static(
    trait_name: &Ident,
    impl_ident: &Ident,
    methods: &[&Ident],
) -> TokenStream {
    let companion = format_ident!("__fidius_{}", trait_name);
    let vtable_type = format_ident!("{}_VTable", trait_name);
    let vtable_name = format_ident!("__FIDIUS_VTABLE_{}", impl_ident);
    let constructor = format_ident!("new_{}_vtable", trait_name.to_string().to_lowercase());

    let shim_args: Vec<TokenStream> = methods
        .iter()
        .map(|method_name| {
            let shim_name = format_ident!("__fidius_shim_{}_{}", impl_ident, method_name);
            quote! { #shim_name }
        })
        .collect();

    quote! {
        #[cfg(not(target_family = "wasm"))]
        static #vtable_name: #companion::#vtable_type = #companion::#constructor(#(#shim_args),*);
    }
}

/// Generate the PluginDescriptor static.
fn generate_descriptor(
    trait_name: &Ident,
    impl_ident: &Ident,
    methods: &[&Ident],
    crate_path: &Path,
    buffer_strategy: BufferStrategyAttr,
) -> TokenStream {
    let companion = format_ident!("__fidius_{}", trait_name);
    let vtable_name = format_ident!("__FIDIUS_VTABLE_{}", impl_ident);
    let descriptor_name = format_ident!("__FIDIUS_DESCRIPTOR_{}", impl_ident);
    let free_fn_name = format_ident!("__fidius_free_buffer_{}", impl_ident);
    let builder_fn = format_ident!(
        "__fidius_build_{}_descriptor",
        trait_name.to_string().to_lowercase()
    );
    let plugin_name_const = format_ident!("__FIDIUS_PLUGIN_NAME_{}", impl_ident);
    let impl_name_str = impl_ident.to_string();

    let optional_methods_ident = format_ident!("{}_OPTIONAL_METHODS", trait_name);
    let method_strs: Vec<String> = methods.iter().map(|m| m.to_string()).collect();
    let method_count = methods.len() as u32;

    // free_buffer is only meaningful for PluginAllocated. Arena strategy
    // doesn't allocate output buffers — nothing to free.
    let free_buffer_expr = match buffer_strategy {
        BufferStrategyAttr::PluginAllocated => quote! { Some(#free_fn_name) },
        BufferStrategyAttr::Arena => quote! { None },
    };

    quote! {
        #[cfg(not(target_family = "wasm"))]
        const #plugin_name_const: &std::ffi::CStr = unsafe {
            std::ffi::CStr::from_bytes_with_nul_unchecked(concat!(#impl_name_str, "\0").as_bytes())
        };

        #[cfg(not(target_family = "wasm"))]
        static #descriptor_name: #crate_path::descriptor::PluginDescriptor = unsafe {
            // Compute capabilities inline: check which impl'd methods
            // appear in the optional methods list.
            // Uses manual byte-by-byte comparison because stable Rust does not
            // support str::eq in const contexts.
            const CAPS: u64 = {
                let optional = #companion::#optional_methods_ident;
                let impl_methods: &[&str] = &[#(#method_strs),*];
                let mut caps: u64 = 0;
                let mut opt_idx = 0;
                while opt_idx < optional.len() {
                    let opt_name = optional[opt_idx];
                    let mut impl_idx = 0;
                    while impl_idx < impl_methods.len() {
                        let impl_name = impl_methods[impl_idx];
                        if opt_name.len() == impl_name.len() {
                            let ob = opt_name.as_bytes();
                            let ib = impl_name.as_bytes();
                            let mut j = 0;
                            let mut eq = true;
                            while j < ob.len() {
                                if ob[j] != ib[j] { eq = false; }
                                j += 1;
                            }
                            if eq {
                                caps |= 1u64 << opt_idx;
                            }
                        }
                        impl_idx += 1;
                    }
                    opt_idx += 1;
                }
                caps
            };

            #companion::#builder_fn(
                #plugin_name_const.as_ptr(),
                &#vtable_name as *const _ as *const _,
                CAPS,
                #free_buffer_expr,
                #method_count,
            )
        };
    }
}

/// Register the descriptor via inventory for multi-plugin support.
fn generate_inventory_registration(impl_ident: &Ident, crate_path: &Path) -> TokenStream {
    let descriptor_name = format_ident!("__FIDIUS_DESCRIPTOR_{}", impl_ident);

    quote! {
        #[cfg(not(target_family = "wasm"))]
        #crate_path::inventory::submit! {
            #crate_path::registry::DescriptorEntry {
                descriptor: &#descriptor_name,
            }
        }
    }
}