alef_codegen/generators/

functions.rs

use crate::generators::binding_helpers::{
    gen_async_body, gen_call_args, gen_call_args_cfg, gen_call_args_with_let_bindings, gen_named_let_bindings,
    gen_named_let_bindings_by_ref, gen_serde_let_bindings, gen_unimplemented_body, has_named_params,
};
use crate::generators::{AdapterBodies, AsyncPattern, RustBindingConfig};
use crate::shared::{function_params, function_sig_defaults};
use crate::type_mapper::TypeMapper;
use ahash::{AHashMap, AHashSet};
use alef_core::ir::{ApiSurface, FunctionDef, TypeRef};

/// Generate a free function.
pub fn gen_function(
    func: &FunctionDef,
    mapper: &dyn TypeMapper,
    cfg: &RustBindingConfig,
    adapter_bodies: &AdapterBodies,
    opaque_types: &AHashSet<String>,
) -> String {
    let map_fn = |ty: &alef_core::ir::TypeRef| mapper.map_type(ty);
    // When named_non_opaque_params_by_ref is true (extendr backend), Named non-opaque struct
    // params must use references because extendr only generates TryFrom<&Robj> for &T.
    // - Required params: `&T` (extendr generates TryFrom<&Robj> for &T)
    // - Optional params: `Nullable<&T>` (extendr's Nullable<T: TryFrom<&Robj>>)
    // - Promoted-optional (required following optional): `Nullable<&T>` (treated as optional)
    // After the first optional/Nullable param, all subsequent params are also promoted.
    let params = if cfg.named_non_opaque_params_by_ref {
        let mut seen_optional = false;
        func.params
            .iter()
            .enumerate()
            .map(|(idx, p)| {
                if p.optional {
                    seen_optional = true;
                }
                let promoted = seen_optional && !p.optional && crate::shared::is_promoted_optional(&func.params, idx);
                let ty = match &p.ty {
                    TypeRef::Named(n) if !opaque_types.contains(n.as_str()) => {
                        if p.optional || seen_optional || promoted {
                            format!("Nullable<&{}>", map_fn(&p.ty))
                        } else {
                            format!("&{}", map_fn(&p.ty))
                        }
                    }
                    _ => {
                        if p.optional || seen_optional {
                            format!("Option<{}>", map_fn(&p.ty))
                        } else {
                            map_fn(&p.ty)
                        }
                    }
                };
                format!("{}: {}", p.name, ty)
            })
            .collect::<Vec<_>>()
            .join(", ")
    } else {
        function_params(&func.params, &map_fn)
    };
    let return_type = mapper.map_type(&func.return_type);
    let ret = mapper.wrap_return(&return_type, func.error_type.is_some());

    // Use let-binding pattern for non-opaque Named params so core fns can take &CoreType.
    // When named_non_opaque_params_by_ref is set (extendr), the binding signature uses &T,
    // so we simulate is_ref=true for Named non-opaque params when generating call args.
    let effective_params: std::borrow::Cow<[alef_core::ir::ParamDef]> = if cfg.named_non_opaque_params_by_ref {
        let modified: Vec<alef_core::ir::ParamDef> = func
            .params
            .iter()
            .map(|p| {
                if matches!(&p.ty, TypeRef::Named(n) if !opaque_types.contains(n.as_str())) {
                    alef_core::ir::ParamDef {
                        is_ref: true,
                        ..p.clone()
                    }
                } else {
                    p.clone()
                }
            })
            .collect();
        std::borrow::Cow::Owned(modified)
    } else {
        std::borrow::Cow::Borrowed(&func.params)
    };
    let use_let_bindings = has_named_params(&effective_params, opaque_types);
    let call_args = if use_let_bindings {
        gen_call_args_with_let_bindings(&effective_params, opaque_types)
    } else if cfg.cast_uints_to_i32 || cfg.cast_large_ints_to_f64 {
        gen_call_args_cfg(
            &effective_params,
            opaque_types,
            cfg.cast_uints_to_i32,
            cfg.cast_large_ints_to_f64,
        )
    } else {
        gen_call_args(&effective_params, opaque_types)
    };
    let core_import = cfg.core_import;
    let let_bindings = if use_let_bindings {
        if cfg.named_non_opaque_params_by_ref {
            // Params are `&T` in the signature — use .clone().into() for conversion.
            gen_named_let_bindings_by_ref(&func.params, opaque_types, core_import)
        } else {
            gen_named_let_bindings(&func.params, opaque_types, core_import)
        }
    } else {
        String::new()
    };

    // Use the function's rust_path for correct module path resolution
    let core_fn_path = {
        let path = func.rust_path.replace('-', "_");
        if path.starts_with(core_import) {
            path
        } else {
            format!("{core_import}::{}", func.name)
        }
    };

    let can_delegate = crate::shared::can_auto_delegate_function(func, opaque_types)
        || can_delegate_with_named_let_bindings(func, opaque_types);

    // Backend-specific error conversion string for serde bindings
    let serde_err_conv = match cfg.async_pattern {
        AsyncPattern::Pyo3FutureIntoPy => ".map_err(|e| pyo3::exceptions::PyRuntimeError::new_err(e.to_string()))",
        AsyncPattern::NapiNativeAsync => ".map_err(|e| napi::Error::new(napi::Status::GenericFailure, e.to_string()))",
        AsyncPattern::WasmNativeAsync => ".map_err(|e| JsValue::from_str(&e.to_string()))",
        AsyncPattern::TokioBlockOn => {
            ".map_err(|e| extendr_api::Error::Other(e.to_string().replace(\":\", \"_\").replace(\"/\", \"_\").replace(\"-\", \"_\").chars().take(255).collect::<String>()))"
        }
        _ => ".map_err(|e| e.to_string())",
    };

    // Generate the body based on async pattern
    let body = if !can_delegate {
        // Check if an adapter provides the body
        if let Some(adapter_body) = adapter_bodies.get(&func.name) {
            adapter_body.clone()
        } else if cfg.has_serde && use_let_bindings && func.error_type.is_some() {
            // MARKER_SERDE_PATH
            // Serde-based param conversion: serialize binding types to JSON, deserialize to core types.
            // This handles Named params (e.g., ProcessConfig) that lack binding→core From impls.
            // For async functions with Pyo3FutureIntoPy, serde bindings use indented format.
            let is_async_pyo3 = func.is_async && cfg.async_pattern == AsyncPattern::Pyo3FutureIntoPy;
            let (serde_indent, serde_err_async) = if is_async_pyo3 {
                (
                    "        ",
                    ".map_err(|e| pyo3::exceptions::PyRuntimeError::new_err(e.to_string()))",
                )
            } else {
                ("    ", serde_err_conv)
            };
            let serde_bindings =
                gen_serde_let_bindings(&func.params, opaque_types, core_import, serde_err_async, serde_indent);
            let core_call = format!("{core_fn_path}({call_args})");

            // Determine return wrapping strategy for serde async (uses explicit types to avoid E0283)
            let returns_ref = func.returns_ref;
            let wrap_return = |expr: &str| -> String {
                match &func.return_type {
                    TypeRef::Vec(inner) => {
                        // Vec<T>: check if elements need conversion
                        match inner.as_ref() {
                            TypeRef::Named(_) => {
                                // Vec<Named>: convert each element using Into::into
                                format!("{expr}.into_iter().map(Into::into).collect()")
                            }
                            _ => expr.to_string(),
                        }
                    }
                    TypeRef::Named(name) if opaque_types.contains(name.as_str()) => {
                        if returns_ref {
                            format!("{name} {{ inner: Arc::new({expr}.clone()) }}")
                        } else {
                            format!("{name} {{ inner: Arc::new({expr}) }}")
                        }
                    }
                    TypeRef::Named(_) => {
                        // Use explicit type with ::from() to avoid E0283 type inference issues in async context
                        if returns_ref {
                            format!("{return_type}::from({expr}.clone())")
                        } else {
                            format!("{return_type}::from({expr})")
                        }
                    }
                    // String/Bytes are identity across all backends (String->String,
                    // Vec<u8>->Vec<u8>) — no .into() needed for owned values.
                    TypeRef::String | TypeRef::Bytes => expr.to_string(),
                    TypeRef::Path => format!("{expr}.to_string_lossy().to_string()"),
                    TypeRef::Json => format!("{expr}.to_string()"),
                    _ => expr.to_string(),
                }
            };

            if is_async_pyo3 {
                // Async serde path: wrap everything in future_into_py
                let is_unit = matches!(func.return_type, TypeRef::Unit);
                let wrapped = wrap_return("result");
                let core_await = format!(
                    "{core_call}.await\n            .map_err(|e| PyErr::new::<PyRuntimeError, _>(e.to_string()))?"
                );
                let inner_body = if is_unit {
                    format!("{serde_bindings}{core_await};\n            Ok(())")
                } else {
                    // When wrapped contains type conversions like .into() or ::from(),
                    // bind to a variable to help type inference for the generic future_into_py.
                    // This avoids E0283 "type annotations needed".
                    if wrapped.contains(".into()") || wrapped.contains("::from(") || wrapped.contains("Into::into") {
                        // Add explicit type annotation to help type inference
                        format!(
                            "{serde_bindings}let result = {core_await};\n            let wrapped_result: {return_type} = {wrapped};\n            Ok(wrapped_result)"
                        )
                    } else {
                        format!("{serde_bindings}let result = {core_await};\n            Ok({wrapped})")
                    }
                };
                format!("pyo3_async_runtimes::tokio::future_into_py(py, async move {{\n{inner_body}\n        }})")
            } else if func.is_async {
                // Async serde path for other backends (NAPI, etc.): use gen_async_body
                let is_unit = matches!(func.return_type, TypeRef::Unit);
                let wrapped = wrap_return("result");
                let async_body = gen_async_body(
                    &core_call,
                    cfg,
                    func.error_type.is_some(),
                    &wrapped,
                    false,
                    "",
                    is_unit,
                    Some(&return_type),
                );
                format!("{serde_bindings}{async_body}")
            } else if matches!(func.return_type, TypeRef::Unit) {
                // Unit return with error: avoid let_unit_value
                let await_kw = if func.is_async { ".await" } else { "" };
                let debug_marker = if func.is_async { "/*ASYNC_UNIT*/ " } else { "" };
                format!("{serde_bindings}{debug_marker}{core_call}{await_kw}{serde_err_conv}?;\n    Ok(())")
            } else {
                let wrapped = wrap_return("val");
                let await_kw = if func.is_async { ".await" } else { "" };
                if wrapped == "val" {
                    format!("{serde_bindings}{core_call}{await_kw}{serde_err_conv}")
                } else if wrapped == "val.into()" {
                    format!("{serde_bindings}{core_call}{await_kw}.map(Into::into){serde_err_conv}")
                } else if let Some(type_path) = wrapped.strip_suffix("::from(val)") {
                    format!("{serde_bindings}{core_call}{await_kw}.map({type_path}::from){serde_err_conv}")
                } else {
                    format!("{serde_bindings}{core_call}{await_kw}.map(|val| {wrapped}){serde_err_conv}")
                }
            }
        } else if func.is_async && cfg.async_pattern == AsyncPattern::Pyo3FutureIntoPy {
            // Async function that can't be auto-delegated — wrap unimplemented body in future_into_py
            let suppress = if func.params.is_empty() {
                String::new()
            } else {
                let names: Vec<&str> = func.params.iter().map(|p| p.name.as_str()).collect();
                format!("let _ = ({});\n        ", names.join(", "))
            };
            format!(
                "{suppress}Err(pyo3::exceptions::PyNotImplementedError::new_err(\"not implemented: {}\"))",
                func.name
            )
        } else {
            // Function can't be auto-delegated — return a default/error based on return type
            gen_unimplemented_body(
                &func.return_type,
                &func.name,
                func.error_type.is_some(),
                cfg,
                &func.params,
                opaque_types,
            )
        }
    } else if func.is_async {
        // MARKER_DELEGATE_ASYNC
        let core_call = format!("{core_fn_path}({call_args})");
        // In async contexts (future_into_py, etc.), the compiler often can't infer the
        // target type for .into(). Use explicit From::from() / collect::<Vec<T>>() instead.
        let return_wrap = match &func.return_type {
            TypeRef::Named(n) if opaque_types.contains(n.as_str()) => {
                format!("{n} {{ inner: Arc::new(result) }}")
            }
            TypeRef::Named(_) => {
                format!("{return_type}::from(result)")
            }
            TypeRef::Vec(inner) => match inner.as_ref() {
                TypeRef::Named(n) if opaque_types.contains(n.as_str()) => {
                    format!("result.into_iter().map(|v| {n} {{ inner: Arc::new(v) }}).collect::<Vec<_>>()")
                }
                TypeRef::Named(_) => {
                    let inner_mapped = mapper.map_type(inner);
                    format!("result.into_iter().map({inner_mapped}::from).collect::<Vec<_>>()")
                }
                _ => "result".to_string(),
            },
            TypeRef::Unit => "result".to_string(),
            _ => super::binding_helpers::wrap_return(
                "result",
                &func.return_type,
                "",
                opaque_types,
                false,
                func.returns_ref,
                false,
            ),
        };
        let async_body = gen_async_body(
            &core_call,
            cfg,
            func.error_type.is_some(),
            &return_wrap,
            false,
            "",
            matches!(func.return_type, TypeRef::Unit),
            Some(&return_type),
        );
        format!("{let_bindings}{async_body}")
    } else {
        let core_call = format!("{core_fn_path}({call_args})");

        // Determine return wrapping strategy
        let returns_ref = func.returns_ref;
        let wrap_return = |expr: &str| -> String {
            match &func.return_type {
                // Opaque type return: wrap in Arc
                TypeRef::Named(name) if opaque_types.contains(name.as_str()) => {
                    if returns_ref {
                        format!("{name} {{ inner: Arc::new({expr}.clone()) }}")
                    } else {
                        format!("{name} {{ inner: Arc::new({expr}) }}")
                    }
                }
                // Non-opaque Named: use .into() if From impl exists
                TypeRef::Named(_name) => {
                    if returns_ref {
                        format!("{expr}.clone().into()")
                    } else {
                        format!("{expr}.into()")
                    }
                }
                // String/Bytes: .into() handles &str→String, skip for owned
                TypeRef::String | TypeRef::Bytes => {
                    if returns_ref {
                        format!("{expr}.into()")
                    } else {
                        expr.to_string()
                    }
                }
                // Path: PathBuf→String needs to_string_lossy
                TypeRef::Path => format!("{expr}.to_string_lossy().to_string()"),
                // Json: serde_json::Value to string
                TypeRef::Json => format!("{expr}.to_string()"),
                // Optional with opaque inner
                TypeRef::Optional(inner) => match inner.as_ref() {
                    TypeRef::Named(name) if opaque_types.contains(name.as_str()) => {
                        if returns_ref {
                            format!("{expr}.map(|v| {name} {{ inner: Arc::new(v.clone()) }})")
                        } else {
                            format!("{expr}.map(|v| {name} {{ inner: Arc::new(v) }})")
                        }
                    }
                    TypeRef::Named(_) => {
                        if returns_ref {
                            format!("{expr}.map(|v| v.clone().into())")
                        } else {
                            format!("{expr}.map(Into::into)")
                        }
                    }
                    TypeRef::Path => {
                        format!("{expr}.map(|v| v.to_string_lossy().to_string())")
                    }
                    TypeRef::String | TypeRef::Bytes => {
                        if returns_ref {
                            format!("{expr}.map(Into::into)")
                        } else {
                            expr.to_string()
                        }
                    }
                    TypeRef::Vec(vi) => match vi.as_ref() {
                        TypeRef::Named(name) if opaque_types.contains(name.as_str()) => {
                            format!("{expr}.map(|v| v.into_iter().map(|x| {name} {{ inner: Arc::new(x) }}).collect())")
                        }
                        TypeRef::Named(_) => {
                            format!("{expr}.map(|v| v.into_iter().map(Into::into).collect())")
                        }
                        _ => expr.to_string(),
                    },
                    _ => expr.to_string(),
                },
                // Vec<Named>: map each element through Into
                TypeRef::Vec(inner) => match inner.as_ref() {
                    TypeRef::Named(name) if opaque_types.contains(name.as_str()) => {
                        if returns_ref {
                            format!("{expr}.into_iter().map(|v| {name} {{ inner: Arc::new(v.clone()) }}).collect()")
                        } else {
                            format!("{expr}.into_iter().map(|v| {name} {{ inner: Arc::new(v) }}).collect()")
                        }
                    }
                    TypeRef::Named(_) => {
                        if returns_ref {
                            format!("{expr}.into_iter().map(|v| v.clone().into()).collect()")
                        } else {
                            format!("{expr}.into_iter().map(Into::into).collect()")
                        }
                    }
                    TypeRef::Path => {
                        format!("{expr}.into_iter().map(|v| v.to_string_lossy().to_string()).collect()")
                    }
                    TypeRef::String | TypeRef::Bytes => {
                        if returns_ref {
                            format!("{expr}.into_iter().map(Into::into).collect()")
                        } else {
                            expr.to_string()
                        }
                    }
                    _ => expr.to_string(),
                },
                _ => expr.to_string(),
            }
        };

        if func.error_type.is_some() {
            // Backend-specific error conversion
            let err_conv = match cfg.async_pattern {
                AsyncPattern::Pyo3FutureIntoPy => {
                    ".map_err(|e| pyo3::exceptions::PyRuntimeError::new_err(e.to_string()))"
                }
                AsyncPattern::NapiNativeAsync => {
                    ".map_err(|e| napi::Error::new(napi::Status::GenericFailure, e.to_string()))"
                }
                AsyncPattern::WasmNativeAsync => ".map_err(|e| JsValue::from_str(&e.to_string()))",
                AsyncPattern::TokioBlockOn => {
                    ".map_err(|e| extendr_api::Error::Other(e.to_string().replace(\":\", \"_\").replace(\"/\", \"_\").replace(\"-\", \"_\").chars().take(255).collect::<String>()))"
                }
                _ => ".map_err(|e| e.to_string())",
            };
            let wrapped = wrap_return("val");
            if wrapped == "val" {
                format!("{core_call}{err_conv}")
            } else if wrapped == "val.into()" {
                format!("{core_call}.map(Into::into){err_conv}")
            } else if let Some(type_path) = wrapped.strip_suffix("::from(val)") {
                format!("{core_call}.map({type_path}::from){err_conv}")
            } else {
                format!("{core_call}.map(|val| {wrapped}){err_conv}")
            }
        } else {
            wrap_return(&core_call)
        }
    };

    // Prepend let bindings for non-opaque Named params (sync delegate case).
    // Only prepend when can_delegate is true — the !can_delegate serde path does its own bindings.
    // However, always prepend Vec<String> ref bindings (names_refs) since serde path doesn't handle them.
    let body = if !let_bindings.is_empty() && !func.is_async {
        if can_delegate {
            format!("{let_bindings}{body}")
        } else {
            // For the !can_delegate path, only prepend Vec<String>+is_ref bindings (names_refs)
            // since serde bindings handle Named type conversions.
            let vec_str_bindings: String = func.params.iter().filter(|p| {
                p.is_ref && matches!(&p.ty, TypeRef::Vec(inner) if matches!(inner.as_ref(), TypeRef::String | TypeRef::Char))
            }).map(|p| {
                // Handle both Vec<String> and Option<Vec<String>> parameters.
                // When p.optional=true, p.ty is the inner type (Vec<String>), so we need to unwrap first.
                if p.optional {
                    format!("let {}_refs: Vec<&str> = {}.as_ref().map(|v| v.iter().map(|s| s.as_str()).collect()).unwrap_or_default();\n    ", p.name, p.name)
                } else {
                    format!("let {}_refs: Vec<&str> = {}.iter().map(|s| s.as_str()).collect();\n    ", p.name, p.name)
                }
            }).collect();
            if !vec_str_bindings.is_empty() {
                format!("{vec_str_bindings}{body}")
            } else {
                body
            }
        }
    } else {
        body
    };

    // Wrap long signature if necessary
    // TokioBlockOn functions block synchronously inside the body — the generated function
    // must NOT be `async fn` because extendr's `#[extendr]` cannot return a Future.
    let async_kw = if func.is_async && cfg.async_pattern != AsyncPattern::TokioBlockOn {
        "async "
    } else {
        ""
    };
    let func_needs_py = func.is_async && cfg.async_pattern == AsyncPattern::Pyo3FutureIntoPy;

    // For async PyO3 free functions, override return type and add lifetime generic.
    let ret = if func_needs_py {
        "PyResult<Bound<'py, PyAny>>".to_string()
    } else {
        ret
    };
    let func_lifetime = if func_needs_py { "<'py>" } else { "" };

    let (func_sig, _params_formatted) = if params.len() > 100 {
        // When formatting for long signatures, promote optional params like function_params() does
        let mut seen_optional = false;
        let wrapped_params = func
            .params
            .iter()
            .map(|p| {
                if p.optional {
                    seen_optional = true;
                }
                let ty = if p.optional || seen_optional {
                    format!("Option<{}>", mapper.map_type(&p.ty))
                } else {
                    mapper.map_type(&p.ty)
                };
                format!("{}: {}", p.name, ty)
            })
            .collect::<Vec<_>>()
            .join(",\n    ");

        // For async PyO3, we need special signature handling
        if func_needs_py {
            (
                format!(
                    "pub fn {}{func_lifetime}(py: Python<'py>,\n    {}\n) -> {ret}",
                    func.name,
                    wrapped_params,
                    ret = ret
                ),
                "",
            )
        } else {
            (
                format!(
                    "pub {async_kw}fn {}(\n    {}\n) -> {ret}",
                    func.name,
                    wrapped_params,
                    ret = ret
                ),
                "",
            )
        }
    } else if func_needs_py {
        (
            format!(
                "pub fn {}{func_lifetime}(py: Python<'py>, {params}) -> {ret}",
                func.name
            ),
            "",
        )
    } else {
        (format!("pub {async_kw}fn {}({params}) -> {ret}", func.name), "")
    };

    let total_params = func.params.len() + if func_needs_py { 1 } else { 0 };
    let sig_defaults = if cfg.needs_signature {
        function_sig_defaults(&func.params)
    } else {
        String::new()
    };
    let attr_inner = cfg
        .function_attr
        .trim_start_matches('#')
        .trim_start_matches('[')
        .trim_end_matches(']');

    crate::template_env::render(
        "generators/functions/function_definition.jinja",
        minijinja::context! {
            has_too_many_arguments => total_params > 7,
            has_missing_errors_doc => func.error_type.is_some(),
            attr_inner => attr_inner,
            needs_signature => cfg.needs_signature,
            signature_prefix => cfg.signature_prefix,
            sig_defaults => sig_defaults,
            signature_suffix => cfg.signature_suffix,
            func_sig => func_sig,
            body => body,
        },
    )
}

fn can_delegate_with_named_let_bindings(func: &FunctionDef, opaque_types: &AHashSet<String>) -> bool {
    !func.sanitized
        && func
            .params
            .iter()
            .all(|p| !p.sanitized && crate::shared::is_delegatable_param(&p.ty, opaque_types))
        && crate::shared::is_delegatable_return(&func.return_type)
}

/// Collect all unique trait import paths from types' methods.
///
/// Returns a deduplicated, sorted list of trait paths (e.g. `["liter_llm::LlmClient"]`)
/// that need to be imported in generated binding code so that trait methods can be called.
/// Both opaque and non-opaque types are scanned because non-opaque wrapper types also
/// delegate trait method calls to their inner core type.
pub fn collect_trait_imports(api: &ApiSurface) -> Vec<String> {
    // Collect all trait paths, then deduplicate by last segment (trait name).
    // When two paths resolve to the same trait name (e.g. `mylib_core::Dependency`
    // and `mylib_core::di::Dependency`), only one import is needed. Keep the
    // shorter (public re-export) path to avoid E0252 duplicate-import errors.
    let mut traits: AHashSet<String> = AHashSet::new();
    for typ in api.types.iter().filter(|typ| !typ.is_trait) {
        for method in &typ.methods {
            if let Some(ref trait_path) = method.trait_source {
                traits.insert(trait_path.clone());
            }
        }
    }

    // Deduplicate by last path segment: keep the shortest path for each trait name.
    let mut by_name: AHashMap<String, String> = AHashMap::new();
    for path in traits {
        let name = path.split("::").last().unwrap_or(&path).to_string();
        let entry = by_name.entry(name).or_insert_with(|| path.clone());
        // Prefer shorter paths (public re-exports are shorter than internal paths)
        if path.len() < entry.len() {
            *entry = path;
        }
    }

    let mut sorted: Vec<String> = by_name.into_values().collect();
    sorted.sort();
    sorted
}

/// Check if any type has methods from trait impls whose trait_source could not be resolved.
///
/// When true, the binding crate should add a glob import of the core crate (e.g.
/// `use kreuzberg::*`) to bring all publicly exported traits into scope.
/// This handles traits defined in private submodules that are re-exported.
pub fn has_unresolved_trait_methods(api: &ApiSurface) -> bool {
    // Count method names that appear on multiple non-trait types but lack trait_source.
    // Such methods likely come from trait impls whose trait path could not be resolved
    // (e.g. traits defined in private modules but re-exported via `pub use`).
    let mut method_counts: AHashMap<&str, (usize, usize)> = AHashMap::new(); // (total, with_source)
    for typ in api.types.iter().filter(|typ| !typ.is_trait) {
        if typ.is_trait {
            continue;
        }
        for method in &typ.methods {
            let entry = method_counts.entry(&method.name).or_insert((0, 0));
            entry.0 += 1;
            if method.trait_source.is_some() {
                entry.1 += 1;
            }
        }
    }
    // A method appearing on 3+ types without trait_source on any is almost certainly a trait method
    method_counts
        .values()
        .any(|&(total, with_source)| total >= 3 && with_source == 0)
}

/// Collect explicit type and enum names from the API surface for named imports.
///
/// Returns a sorted, deduplicated list of type and enum names that should be
/// imported from the core crate. This replaces glob imports (`use core::*`)
/// which can cause name conflicts with local binding definitions (e.g. a
/// `convert` function or `Result` type alias from the core crate shadowing
/// the binding's own `convert` wrapper or `std::result::Result`).
///
/// Only struct/enum names are included — functions and type aliases are
/// intentionally excluded because they are the source of conflicts.
pub fn collect_explicit_core_imports(api: &ApiSurface) -> Vec<String> {
    let mut names = std::collections::BTreeSet::new();
    for typ in api.types.iter().filter(|typ| !typ.is_trait) {
        names.insert(typ.name.clone());
    }
    for e in &api.enums {
        names.insert(e.name.clone());
    }
    names.into_iter().collect()
}