server_less_parse/

lib.rs

//! Shared parsing utilities for server-less proc macros.
//!
//! This crate provides common types and functions for extracting
//! method information from impl blocks.

use syn::{
    FnArg, GenericArgument, Ident, ImplItem, ImplItemFn, ItemImpl, Lit, Meta, Pat, PathArguments,
    ReturnType, Type, TypeReference,
};

/// Parsed method information with full `syn` AST types.
///
/// This is the rich, compile-time representation used by all proc macros
/// during code generation. It retains full `syn::Type` and `syn::Ident`
/// nodes for accurate token generation.
///
/// **Not to be confused with [`server_less_core::MethodInfo`]**, which is
/// a simplified, string-based representation for runtime introspection.
#[derive(Debug, Clone)]
pub struct MethodInfo {
    /// The original method
    pub method: ImplItemFn,
    /// Method name
    pub name: Ident,
    /// Documentation string
    pub docs: Option<String>,
    /// Parameters (excluding self)
    pub params: Vec<ParamInfo>,
    /// Return type info
    pub return_info: ReturnInfo,
    /// Whether the method is async
    pub is_async: bool,
    /// Group assignment from `#[server(group = "...")]`
    pub group: Option<String>,
    /// Explicit wire name override from `#[server(name = "...")]` or protocol-specific
    /// `#[cli(name = "...")]`, `#[mcp(name = "...")]`, etc.
    pub wire_name: Option<String>,
}

/// Registry of declared method groups from `#[server(groups(...))]`.
///
/// When present on an impl block, method `group` values are resolved as IDs
/// against this registry. When absent, `group` values are literal display names.
#[derive(Debug, Clone)]
pub struct GroupRegistry {
    /// Ordered list of (id, display_name) pairs.
    /// Ordering determines display order in help output and documentation.
    pub groups: Vec<(String, String)>,
}

/// Parsed parameter information
#[derive(Debug, Clone)]
pub struct ParamInfo {
    /// Parameter name
    pub name: Ident,
    /// Parameter type
    pub ty: Type,
    /// Whether this is `Option<T>`
    pub is_optional: bool,
    /// Whether this is `bool`
    pub is_bool: bool,
    /// Whether this is `Vec<T>`
    pub is_vec: bool,
    /// Inner type if `Vec<T>`
    pub vec_inner: Option<Type>,
    /// Whether this looks like an ID (ends with _id or is named id)
    pub is_id: bool,
    /// Custom wire name (from #[param(name = "...")])
    pub wire_name: Option<String>,
    /// Parameter location override (from #[param(query/path/body/header)])
    pub location: Option<ParamLocation>,
    /// Default value as a string (from #[param(default = ...)])
    pub default_value: Option<String>,
    /// Short flag character (from #[param(short = 'x')])
    pub short_flag: Option<char>,
    /// Custom help text (from #[param(help = "...")])
    pub help_text: Option<String>,
    /// Whether this is a positional argument (from #[param(positional)] or is_id heuristic)
    pub is_positional: bool,
}

impl MethodInfo {
    /// Rust method name with `r#` prefix stripped.
    ///
    /// Returns the raw identifier name, ignoring any `wire_name` override.
    /// Use this for code generation (`self.method_name()`) and as the base for
    /// protocol-specific transforms (`.to_kebab_case()`, `.to_snake_case()`, etc.).
    pub fn name_str(&self) -> String {
        ident_str(&self.name)
    }

    /// Protocol-facing name, applying a transform to the raw name unless overridden.
    ///
    /// If `wire_name` is set (from `#[server(name = "...")]` or protocol-specific
    /// attributes), returns it as-is. Otherwise applies `transform` to the raw name.
    ///
    /// ```ignore
    /// // CLI: kebab-case
    /// method.wire_name_or(|n| n.to_kebab_case())
    /// // JSON-RPC: raw name
    /// method.wire_name_or(|n| n)
    /// // gRPC: snake_case
    /// method.wire_name_or(|n| n.to_snake_case())
    /// ```
    pub fn wire_name_or(&self, transform: impl FnOnce(String) -> String) -> String {
        if let Some(ref wn) = self.wire_name {
            wn.clone()
        } else {
            transform(self.name_str())
        }
    }
}

impl ParamInfo {
    /// Parameter name as a protocol string, stripping the `r#` prefix from raw identifiers.
    ///
    /// Use this instead of `.name.to_string()` whenever generating protocol-level names
    /// (CLI flags, HTTP query params, JSON schema properties, etc.).
    pub fn name_str(&self) -> String {
        ident_str(&self.name)
    }
}

/// Convert an identifier to a string, stripping the `r#` prefix for raw identifiers.
///
/// `proc_macro2::Ident::to_string()` preserves the `r#` prefix (e.g. `r#type` → `"r#type"`),
/// which produces incorrect protocol names. Use this function whenever an `Ident` is converted
/// to a string for protocol-level output (CLI flags, HTTP routes, JSON-RPC method names, etc.).
pub fn ident_str(ident: &Ident) -> String {
    let s = ident.to_string();
    s.strip_prefix("r#").map(str::to_string).unwrap_or(s)
}

/// Parameter location for HTTP requests
#[derive(Debug, Clone, PartialEq)]
pub enum ParamLocation {
    Query,
    Path,
    Body,
    Header,
}

/// Parsed return type information
#[derive(Debug, Clone)]
pub struct ReturnInfo {
    /// The full return type
    pub ty: Option<Type>,
    /// Inner type if `Result<T, E>`
    pub ok_type: Option<Type>,
    /// Error type if `Result<T, E>`
    pub err_type: Option<Type>,
    /// Inner type if `Option<T>`
    pub some_type: Option<Type>,
    /// Whether it's a Result
    pub is_result: bool,
    /// Whether it's an Option (and not Result)
    pub is_option: bool,
    /// Whether it returns ()
    pub is_unit: bool,
    /// Whether it's impl Stream<Item=T>
    pub is_stream: bool,
    /// The stream item type if is_stream
    pub stream_item: Option<Type>,
    /// Whether it's impl Iterator<Item=T>
    pub is_iterator: bool,
    /// The iterator item type if is_iterator
    pub iterator_item: Option<Type>,
    /// Whether the return type is a reference (&T)
    pub is_reference: bool,
    /// The inner type T if returning &T
    pub reference_inner: Option<Type>,
}

impl MethodInfo {
    /// Parse a method from an ImplItemFn
    ///
    /// Returns None for associated functions without `&self` (constructors, etc.)
    pub fn parse(method: &ImplItemFn) -> syn::Result<Option<Self>> {
        let name = method.sig.ident.clone();
        let is_async = method.sig.asyncness.is_some();

        // Skip associated functions without self receiver (constructors, etc.)
        let has_receiver = method
            .sig
            .inputs
            .iter()
            .any(|arg| matches!(arg, FnArg::Receiver(_)));
        if !has_receiver {
            return Ok(None);
        }

        // Extract doc comments
        let docs = extract_docs(&method.attrs);

        // Parse parameters
        let params = parse_params(&method.sig.inputs)?;

        // Parse return type
        let return_info = parse_return_type(&method.sig.output);

        // Extract group from #[server(group = "...")]
        let group = extract_server_group(&method.attrs);

        // Extract wire name from #[server(name = "...")] or protocol-specific attrs
        let wire_name = extract_wire_name(&method.attrs);

        Ok(Some(Self {
            method: method.clone(),
            name,
            docs,
            params,
            return_info,
            is_async,
            group,
            wire_name,
        }))
    }
}

/// Extract doc comments from attributes
pub fn extract_docs(attrs: &[syn::Attribute]) -> Option<String> {
    let docs: Vec<String> = attrs
        .iter()
        .filter_map(|attr| {
            if attr.path().is_ident("doc")
                && let Meta::NameValue(meta) = &attr.meta
                && let syn::Expr::Lit(syn::ExprLit {
                    lit: Lit::Str(s), ..
                }) = &meta.value
            {
                return Some(s.value().trim().to_string());
            }
            None
        })
        .collect();

    if docs.is_empty() {
        None
    } else {
        Some(docs.join("\n"))
    }
}

/// Known protocol attribute identifiers used by server-less macros.
const PROTOCOL_ATTRS: &[&str] = &[
    "server", "cli", "http", "mcp", "jsonrpc", "grpc", "ws", "graphql", "tool",
];

/// Extract `name = "..."` from any protocol attribute on a method.
///
/// Checks `#[server(name = "...")]`, `#[cli(name = "...")]`, `#[mcp(name = "...")]`, etc.
/// If multiple protocol attrs specify `name`, the first one found wins.
fn extract_wire_name(attrs: &[syn::Attribute]) -> Option<String> {
    for attr in attrs {
        let is_protocol = attr
            .path()
            .get_ident()
            .is_some_and(|id| PROTOCOL_ATTRS.iter().any(|p| id == p));
        if !is_protocol {
            continue;
        }
        let mut found = None;
        let _ = attr.parse_nested_meta(|meta| {
            if meta.path.is_ident("name") {
                let value = meta.value()?;
                let s: syn::LitStr = value.parse()?;
                found = Some(s.value());
            } else if meta.input.peek(syn::Token![=]) {
                let _: proc_macro2::TokenStream = meta.value()?.parse()?;
            }
            Ok(())
        });
        if found.is_some() {
            return found;
        }
    }
    None
}

/// Extract the `group` value from `#[server(group = "...")]` on a method.
fn extract_server_group(attrs: &[syn::Attribute]) -> Option<String> {
    for attr in attrs {
        if attr.path().is_ident("server") {
            let mut group = None;
            let _ = attr.parse_nested_meta(|meta| {
                if meta.path.is_ident("group") {
                    let value = meta.value()?;
                    let s: syn::LitStr = value.parse()?;
                    group = Some(s.value());
                } else if meta.input.peek(syn::Token![=]) {
                    // Consume other `key = value` pairs without error.
                    let _: proc_macro2::TokenStream = meta.value()?.parse()?;
                }
                Ok(())
            });
            if group.is_some() {
                return group;
            }
        }
    }
    None
}

/// Extract the group registry from `#[server(groups(...))]` on an impl block.
///
/// Returns `None` if no `groups(...)` attribute is present.
/// Returns ordered `(id, display_name)` pairs matching declaration order.
pub fn extract_groups(impl_block: &ItemImpl) -> syn::Result<Option<GroupRegistry>> {
    for attr in &impl_block.attrs {
        if attr.path().is_ident("server") {
            let mut groups = Vec::new();
            let mut found_groups = false;
            attr.parse_nested_meta(|meta| {
                if meta.path.is_ident("groups") {
                    found_groups = true;
                    meta.parse_nested_meta(|inner| {
                        let id = inner
                            .path
                            .get_ident()
                            .ok_or_else(|| inner.error("expected group identifier"))?
                            .to_string();
                        let value = inner.value()?;
                        let display: syn::LitStr = value.parse()?;
                        groups.push((id, display.value()));
                        Ok(())
                    })?;
                } else if meta.input.peek(syn::Token![=]) {
                    let _: proc_macro2::TokenStream = meta.value()?.parse()?;
                } else if meta.input.peek(syn::token::Paren) {
                    let _content;
                    syn::parenthesized!(_content in meta.input);
                }
                Ok(())
            })?;
            if found_groups {
                return Ok(Some(GroupRegistry { groups }));
            }
        }
    }
    Ok(None)
}

/// Resolve a method's group against the registry.
///
/// When the method has `group = "id"`, the registry must be present and must
/// contain a matching ID — otherwise a compile error is emitted. The returned
/// string is the display name from the registry.
///
/// When the method has no `group` attribute, returns `None`.
pub fn resolve_method_group(
    method: &MethodInfo,
    registry: &Option<GroupRegistry>,
) -> syn::Result<Option<String>> {
    let group_value = match &method.group {
        Some(v) => v,
        None => return Ok(None),
    };

    let span = method.method.sig.ident.span();

    match registry {
        Some(reg) => {
            for (id, display) in &reg.groups {
                if id == group_value {
                    return Ok(Some(display.clone()));
                }
            }
            Err(syn::Error::new(
                span,
                format!(
                    "unknown group `{group_value}`; declared groups are: {}",
                    reg.groups
                        .iter()
                        .map(|(id, _)| format!("`{id}`"))
                        .collect::<Vec<_>>()
                        .join(", ")
                ),
            ))
        }
        None => Err(syn::Error::new(
            span,
            format!(
                "method has `group = \"{group_value}\"` but no `groups(...)` registry is declared on the impl block\n\
                 \n\
                 help: add `#[server(groups({group_value} = \"Display Name\"))]` to the impl block"
            ),
        )),
    }
}

/// Parsed result of `#[param(...)]` attributes.
#[derive(Debug, Clone, Default)]
pub struct ParsedParamAttrs {
    pub wire_name: Option<String>,
    pub location: Option<ParamLocation>,
    pub default_value: Option<String>,
    pub short_flag: Option<char>,
    pub help_text: Option<String>,
    pub positional: bool,
    /// Environment variable name (from `#[param(env = "VAR")]`). Used by `#[derive(Config)]`.
    pub env_var: Option<String>,
    /// Config file key override (from `#[param(file_key = "a.b.c")]`). Used by `#[derive(Config)]`.
    pub file_key: Option<String>,
    /// Marks a field as a nested `Config` sub-struct (from `#[param(nested)]`).
    ///
    /// The field's type must also `#[derive(Config)]`.  TOML loading delegates to
    /// the child's `Config::load`, using the field name (or `file_key`) as the
    /// sub-table name.  Env var loading narrows the prefix with the field name.
    pub nested: bool,
    /// Env-var prefix override for a nested field (from `#[param(env_prefix = "SEARCH")]`).
    ///
    /// When set, env vars for the child struct use `{env_prefix}_{CHILD_FIELD}` instead
    /// of `{parent_prefix}_{field_name}_{CHILD_FIELD}`.  Only meaningful with `nested`.
    pub env_prefix: Option<String>,
    /// Serde-passthrough flag for nested fields (from `#[param(nested, serde)]`).
    ///
    /// When `true` (implies `nested = true`), the TOML sub-table for this field is
    /// deserialized via `serde::Deserialize` instead of `Config::load`.  Env-var
    /// overrides are silently skipped for the serde-nested subtree; use
    /// `#[serde(default)]` in the child type for defaults.  Only meaningful with
    /// `nested`.
    pub nested_serde: bool,
}

/// Compute Levenshtein edit distance between two strings.
#[allow(clippy::needless_range_loop)]
fn levenshtein(a: &str, b: &str) -> usize {
    let a: Vec<char> = a.chars().collect();
    let b: Vec<char> = b.chars().collect();
    let m = a.len();
    let n = b.len();
    let mut dp = vec![vec![0usize; n + 1]; m + 1];
    for i in 0..=m {
        dp[i][0] = i;
    }
    for j in 0..=n {
        dp[0][j] = j;
    }
    for i in 1..=m {
        for j in 1..=n {
            dp[i][j] = if a[i - 1] == b[j - 1] {
                dp[i - 1][j - 1]
            } else {
                1 + dp[i - 1][j - 1].min(dp[i - 1][j]).min(dp[i][j - 1])
            };
        }
    }
    dp[m][n]
}

/// Return the closest candidate to `input` within edit distance ≤ 2, or `None`.
fn did_you_mean<'a>(input: &str, candidates: &[&'a str]) -> Option<&'a str> {
    candidates
        .iter()
        .filter_map(|&c| {
            let d = levenshtein(input, c);
            if d <= 2 { Some((d, c)) } else { None }
        })
        .min_by_key(|&(d, _)| d)
        .map(|(_, c)| c)
}

/// Parse #[param(...)] attributes from a parameter
pub fn parse_param_attrs(attrs: &[syn::Attribute]) -> syn::Result<ParsedParamAttrs> {
    let mut wire_name = None;
    let mut location = None;
    let mut default_value = None;
    let mut short_flag = None;
    let mut help_text = None;
    let mut positional = false;
    let mut env_var = None;
    let mut file_key = None;
    let mut nested = false;
    let mut env_prefix = None;
    let mut nested_serde = false;

    for attr in attrs {
        if !attr.path().is_ident("param") {
            continue;
        }

        attr.parse_nested_meta(|meta| {
            // #[param(name = "...")]
            if meta.path.is_ident("name") {
                let value: syn::LitStr = meta.value()?.parse()?;
                wire_name = Some(value.value());
                Ok(())
            }
            // #[param(default = ...)]
            else if meta.path.is_ident("default") {
                // Accept various literal types
                let value = meta.value()?;
                let lookahead = value.lookahead1();
                if lookahead.peek(syn::LitStr) {
                    let lit: syn::LitStr = value.parse()?;
                    default_value = Some(format!("\"{}\"", lit.value()));
                } else if lookahead.peek(syn::LitInt) {
                    let lit: syn::LitInt = value.parse()?;
                    default_value = Some(lit.to_string());
                } else if lookahead.peek(syn::LitBool) {
                    let lit: syn::LitBool = value.parse()?;
                    default_value = Some(lit.value.to_string());
                } else {
                    return Err(lookahead.error());
                }
                Ok(())
            }
            // #[param(query)] or #[param(path)] etc.
            else if meta.path.is_ident("query") {
                location = Some(ParamLocation::Query);
                Ok(())
            } else if meta.path.is_ident("path") {
                location = Some(ParamLocation::Path);
                Ok(())
            } else if meta.path.is_ident("body") {
                location = Some(ParamLocation::Body);
                Ok(())
            } else if meta.path.is_ident("header") {
                location = Some(ParamLocation::Header);
                Ok(())
            }
            // #[param(short = 'v')]
            else if meta.path.is_ident("short") {
                let value: syn::LitChar = meta.value()?.parse()?;
                short_flag = Some(value.value());
                Ok(())
            }
            // #[param(help = "description")]
            else if meta.path.is_ident("help") {
                let value: syn::LitStr = meta.value()?.parse()?;
                help_text = Some(value.value());
                Ok(())
            }
            // #[param(positional)]
            else if meta.path.is_ident("positional") {
                positional = true;
                Ok(())
            }
            // #[param(env = "VAR_NAME")]
            else if meta.path.is_ident("env") {
                let value: syn::LitStr = meta.value()?.parse()?;
                env_var = Some(value.value());
                Ok(())
            }
            // #[param(file_key = "a.b.c")]
            else if meta.path.is_ident("file_key") {
                let value: syn::LitStr = meta.value()?.parse()?;
                file_key = Some(value.value());
                Ok(())
            }
            // #[param(nested)]
            else if meta.path.is_ident("nested") {
                nested = true;
                Ok(())
            }
            // #[param(serde)] — only meaningful alongside `nested`; sets nested_serde = true
            else if meta.path.is_ident("serde") {
                nested_serde = true;
                Ok(())
            }
            // #[param(env_prefix = "SEARCH")]
            else if meta.path.is_ident("env_prefix") {
                let value: syn::LitStr = meta.value()?.parse()?;
                env_prefix = Some(value.value());
                Ok(())
            } else {
                const VALID: &[&str] = &[
                    "name", "default", "query", "path", "body", "header", "short", "help",
                    "positional", "env", "file_key", "nested", "serde", "env_prefix",
                ];
                let unknown = meta
                    .path
                    .get_ident()
                    .map(|i| i.to_string())
                    .unwrap_or_default();
                let suggestion = did_you_mean(&unknown, VALID)
                    .map(|s| format!(" — did you mean `{s}`?"))
                    .unwrap_or_default();
                Err(meta.error(format!(
                    "unknown attribute `{unknown}`{suggestion}\n\
                     \n\
                     Valid attributes: name, default, query, path, body, header, short, help, positional, env, file_key, nested, serde, env_prefix\n\
                     \n\
                     Examples:\n\
                     - #[param(name = \"q\")]\n\
                     - #[param(default = 10)]\n\
                     - #[param(query)]\n\
                     - #[param(header, name = \"X-API-Key\")]\n\
                     - #[param(short = 'v')]\n\
                     - #[param(help = \"Enable verbose output\")]\n\
                     - #[param(positional)]\n\
                     - #[param(env = \"MY_VAR\")]\n\
                     - #[param(file_key = \"database.host\")]\n\
                     - #[param(nested)]\n\
                     - #[param(nested, serde)]\n\
                     - #[param(nested, env_prefix = \"SEARCH\")]"
                )))
            }
        })?;
    }

    Ok(ParsedParamAttrs {
        wire_name,
        location,
        default_value,
        short_flag,
        help_text,
        positional,
        env_var,
        file_key,
        nested,
        env_prefix,
        nested_serde,
    })
}

/// Parse function parameters (excluding self)
pub fn parse_params(
    inputs: &syn::punctuated::Punctuated<FnArg, syn::Token![,]>,
) -> syn::Result<Vec<ParamInfo>> {
    let mut params = Vec::new();

    for arg in inputs {
        match arg {
            FnArg::Receiver(_) => continue, // skip self
            FnArg::Typed(pat_type) => {
                let name = match pat_type.pat.as_ref() {
                    Pat::Ident(pat_ident) => pat_ident.ident.clone(),
                    other => {
                        return Err(syn::Error::new_spanned(
                            other,
                            "unsupported parameter pattern\n\
                             \n\
                             Server-less macros require simple parameter names.\n\
                             Use: name: String\n\
                             Not: (name, _): (String, i32) or &name: &String",
                        ));
                    }
                };

                let ty = (*pat_type.ty).clone();
                let is_optional = is_option_type(&ty);
                let is_bool = is_bool_type(&ty);
                let vec_inner = extract_vec_type(&ty);
                let is_vec = vec_inner.is_some();
                let is_id = is_id_param(&name);

                // Parse #[param(...)] attributes
                let parsed = parse_param_attrs(&pat_type.attrs)?;

                // is_positional: explicit attribute takes priority, is_id heuristic as fallback
                let is_positional = parsed.positional || is_id;

                params.push(ParamInfo {
                    name,
                    ty,
                    is_optional,
                    is_bool,
                    is_vec,
                    vec_inner,
                    is_id,
                    is_positional,
                    wire_name: parsed.wire_name,
                    location: parsed.location,
                    default_value: parsed.default_value,
                    short_flag: parsed.short_flag,
                    help_text: parsed.help_text,
                });
            }
        }
    }

    Ok(params)
}

/// Parse return type information
pub fn parse_return_type(output: &ReturnType) -> ReturnInfo {
    match output {
        ReturnType::Default => ReturnInfo {
            ty: None,
            ok_type: None,
            err_type: None,
            some_type: None,
            is_result: false,
            is_option: false,
            is_unit: true,
            is_stream: false,
            stream_item: None,
            is_iterator: false,
            iterator_item: None,
            is_reference: false,
            reference_inner: None,
        },
        ReturnType::Type(_, ty) => {
            let ty = ty.as_ref().clone();

            // Check for Result<T, E>
            if let Some((ok, err)) = extract_result_types(&ty) {
                return ReturnInfo {
                    ty: Some(ty),
                    ok_type: Some(ok),
                    err_type: Some(err),
                    some_type: None,
                    is_result: true,
                    is_option: false,
                    is_unit: false,
                    is_stream: false,
                    stream_item: None,
                    is_iterator: false,
                    iterator_item: None,
                    is_reference: false,
                    reference_inner: None,
                };
            }

            // Check for Option<T>
            if let Some(inner) = extract_option_type(&ty) {
                return ReturnInfo {
                    ty: Some(ty),
                    ok_type: None,
                    err_type: None,
                    some_type: Some(inner),
                    is_result: false,
                    is_option: true,
                    is_unit: false,
                    is_stream: false,
                    stream_item: None,
                    is_iterator: false,
                    iterator_item: None,
                    is_reference: false,
                    reference_inner: None,
                };
            }

            // Check for impl Stream<Item=T>
            if let Some(item) = extract_stream_item(&ty) {
                return ReturnInfo {
                    ty: Some(ty),
                    ok_type: None,
                    err_type: None,
                    some_type: None,
                    is_result: false,
                    is_option: false,
                    is_unit: false,
                    is_stream: true,
                    stream_item: Some(item),
                    is_iterator: false,
                    iterator_item: None,
                    is_reference: false,
                    reference_inner: None,
                };
            }

            // Check for impl Iterator<Item=T>
            if let Some(item) = extract_iterator_item(&ty) {
                return ReturnInfo {
                    ty: Some(ty),
                    ok_type: None,
                    err_type: None,
                    some_type: None,
                    is_result: false,
                    is_option: false,
                    is_unit: false,
                    is_stream: false,
                    stream_item: None,
                    is_iterator: true,
                    iterator_item: Some(item),
                    is_reference: false,
                    reference_inner: None,
                };
            }

            // Check for ()
            if is_unit_type(&ty) {
                return ReturnInfo {
                    ty: Some(ty),
                    ok_type: None,
                    err_type: None,
                    some_type: None,
                    is_result: false,
                    is_option: false,
                    is_unit: true,
                    is_stream: false,
                    stream_item: None,
                    is_iterator: false,
                    iterator_item: None,
                    is_reference: false,
                    reference_inner: None,
                };
            }

            // Check for &T (reference return — mount point)
            if let Type::Reference(TypeReference { elem, .. }) = &ty {
                let inner = elem.as_ref().clone();
                return ReturnInfo {
                    ty: Some(ty),
                    ok_type: None,
                    err_type: None,
                    some_type: None,
                    is_result: false,
                    is_option: false,
                    is_unit: false,
                    is_stream: false,
                    stream_item: None,
                    is_iterator: false,
                    iterator_item: None,
                    is_reference: true,
                    reference_inner: Some(inner),
                };
            }

            // Regular type
            ReturnInfo {
                ty: Some(ty),
                ok_type: None,
                err_type: None,
                some_type: None,
                is_result: false,
                is_option: false,
                is_unit: false,
                is_stream: false,
                stream_item: None,
                is_iterator: false,
                iterator_item: None,
                is_reference: false,
                reference_inner: None,
            }
        }
    }
}

/// Check if a type is `bool`
pub fn is_bool_type(ty: &Type) -> bool {
    if let Type::Path(type_path) = ty
        && let Some(segment) = type_path.path.segments.last()
        && type_path.path.segments.len() == 1
    {
        return segment.ident == "bool";
    }
    false
}

/// Check if a type is `Vec<T>` and extract T
pub fn extract_vec_type(ty: &Type) -> Option<Type> {
    if let Type::Path(type_path) = ty
        && let Some(segment) = type_path.path.segments.last()
        && segment.ident == "Vec"
        && let PathArguments::AngleBracketed(args) = &segment.arguments
        && let Some(GenericArgument::Type(inner)) = args.args.first()
    {
        return Some(inner.clone());
    }
    None
}

/// Check if a type is `HashMap<K, V>` or `BTreeMap<K, V>` and extract K and V
pub fn extract_map_type(ty: &Type) -> Option<(Type, Type)> {
    if let Type::Path(type_path) = ty
        && let Some(segment) = type_path.path.segments.last()
        && (segment.ident == "HashMap" || segment.ident == "BTreeMap")
        && let PathArguments::AngleBracketed(args) = &segment.arguments
    {
        let mut iter = args.args.iter();
        if let (Some(GenericArgument::Type(key)), Some(GenericArgument::Type(val))) =
            (iter.next(), iter.next())
        {
            return Some((key.clone(), val.clone()));
        }
    }
    None
}

/// Check if a type is `Option<T>` and extract T
pub fn extract_option_type(ty: &Type) -> Option<Type> {
    if let Type::Path(type_path) = ty
        && let Some(segment) = type_path.path.segments.last()
        && segment.ident == "Option"
        && let PathArguments::AngleBracketed(args) = &segment.arguments
        && let Some(GenericArgument::Type(inner)) = args.args.first()
    {
        return Some(inner.clone());
    }
    None
}

/// Check if a type is `Option<T>`
pub fn is_option_type(ty: &Type) -> bool {
    extract_option_type(ty).is_some()
}

/// Check if a type is Result<T, E> and extract T and E
pub fn extract_result_types(ty: &Type) -> Option<(Type, Type)> {
    if let Type::Path(type_path) = ty
        && let Some(segment) = type_path.path.segments.last()
        && segment.ident == "Result"
        && let PathArguments::AngleBracketed(args) = &segment.arguments
    {
        let mut iter = args.args.iter();
        if let (Some(GenericArgument::Type(ok)), Some(GenericArgument::Type(err))) =
            (iter.next(), iter.next())
        {
            return Some((ok.clone(), err.clone()));
        }
    }
    None
}

/// Check if a type is impl Stream<Item=T> and extract T
pub fn extract_stream_item(ty: &Type) -> Option<Type> {
    if let Type::ImplTrait(impl_trait) = ty {
        for bound in &impl_trait.bounds {
            if let syn::TypeParamBound::Trait(trait_bound) = bound
                && let Some(segment) = trait_bound.path.segments.last()
                && segment.ident == "Stream"
                && let PathArguments::AngleBracketed(args) = &segment.arguments
            {
                for arg in &args.args {
                    if let GenericArgument::AssocType(assoc) = arg
                        && assoc.ident == "Item"
                    {
                        return Some(assoc.ty.clone());
                    }
                }
            }
        }
    }
    None
}

/// Check if a type is impl Iterator<Item=T> and extract T
pub fn extract_iterator_item(ty: &Type) -> Option<Type> {
    if let Type::ImplTrait(impl_trait) = ty {
        for bound in &impl_trait.bounds {
            if let syn::TypeParamBound::Trait(trait_bound) = bound
                && let Some(segment) = trait_bound.path.segments.last()
                && segment.ident == "Iterator"
                && let PathArguments::AngleBracketed(args) = &segment.arguments
            {
                for arg in &args.args {
                    if let GenericArgument::AssocType(assoc) = arg
                        && assoc.ident == "Item"
                    {
                        return Some(assoc.ty.clone());
                    }
                }
            }
        }
    }
    None
}

/// Check if a type is ()
pub fn is_unit_type(ty: &Type) -> bool {
    if let Type::Tuple(tuple) = ty {
        return tuple.elems.is_empty();
    }
    false
}

/// Check if a parameter name looks like an ID
pub fn is_id_param(name: &Ident) -> bool {
    let name_str = ident_str(name);
    name_str == "id" || name_str.ends_with("_id")
}

/// Extract all methods from an impl block
///
/// Skips:
/// - Private methods (starting with `_`)
/// - Associated functions without `&self` receiver (constructors, etc.)
pub fn extract_methods(impl_block: &ItemImpl) -> syn::Result<Vec<MethodInfo>> {
    let mut methods = Vec::new();

    for item in &impl_block.items {
        if let ImplItem::Fn(method) = item {
            // Skip private methods (those starting with _)
            if method.sig.ident.to_string().starts_with('_') {
                continue;
            }
            // Parse method - returns None for associated functions without self
            if let Some(info) = MethodInfo::parse(method)? {
                methods.push(info);
            }
        }
    }

    Ok(methods)
}

/// Categorized methods for code generation.
///
/// Methods returning `&T` (non-async) are mount points; everything else is a leaf.
/// Mount points are further split by whether they take parameters (slug) or not (static).
pub struct PartitionedMethods<'a> {
    /// Regular leaf methods (no reference return).
    pub leaf: Vec<&'a MethodInfo>,
    /// Static mounts: `fn foo(&self) -> &T` (no params).
    pub static_mounts: Vec<&'a MethodInfo>,
    /// Slug mounts: `fn foo(&self, id: Id) -> &T` (has params).
    pub slug_mounts: Vec<&'a MethodInfo>,
}

/// Partition methods into leaf commands, static mounts, and slug mounts.
///
/// The `skip` predicate allows each protocol to apply its own skip logic
/// (e.g., `#[cli(skip)]`, `#[mcp(skip)]`).
pub fn partition_methods<'a>(
    methods: &'a [MethodInfo],
    skip: impl Fn(&MethodInfo) -> bool,
) -> PartitionedMethods<'a> {
    let mut result = PartitionedMethods {
        leaf: Vec::new(),
        static_mounts: Vec::new(),
        slug_mounts: Vec::new(),
    };

    for method in methods {
        if skip(method) {
            continue;
        }

        if method.return_info.is_reference && !method.is_async {
            if method.params.is_empty() {
                result.static_mounts.push(method);
            } else {
                result.slug_mounts.push(method);
            }
        } else {
            result.leaf.push(method);
        }
    }

    result
}

/// Get the struct name from an impl block
pub fn get_impl_name(impl_block: &ItemImpl) -> syn::Result<Ident> {
    if let Type::Path(type_path) = impl_block.self_ty.as_ref()
        && let Some(segment) = type_path.path.segments.last()
    {
        return Ok(segment.ident.clone());
    }
    Err(syn::Error::new_spanned(
        &impl_block.self_ty,
        "Expected a simple type name",
    ))
}

#[cfg(test)]
mod tests {
    use super::*;
    use quote::quote;

    // ── extract_docs ────────────────────────────────────────────────

    #[test]
    fn extract_docs_returns_none_when_no_doc_attrs() {
        let method: ImplItemFn = syn::parse_quote! {
            fn hello(&self) {}
        };
        assert!(extract_docs(&method.attrs).is_none());
    }

    #[test]
    fn extract_docs_extracts_single_line() {
        let method: ImplItemFn = syn::parse_quote! {
            /// Hello world
            fn hello(&self) {}
        };
        assert_eq!(extract_docs(&method.attrs).unwrap(), "Hello world");
    }

    #[test]
    fn extract_docs_joins_multiple_lines() {
        let method: ImplItemFn = syn::parse_quote! {
            /// Line one
            /// Line two
            fn hello(&self) {}
        };
        assert_eq!(extract_docs(&method.attrs).unwrap(), "Line one\nLine two");
    }

    #[test]
    fn extract_docs_ignores_non_doc_attrs() {
        let method: ImplItemFn = syn::parse_quote! {
            #[inline]
            /// Documented
            fn hello(&self) {}
        };
        assert_eq!(extract_docs(&method.attrs).unwrap(), "Documented");
    }

    // ── parse_return_type ───────────────────────────────────────────

    #[test]
    fn parse_return_type_default_is_unit() {
        let ret: ReturnType = syn::parse_quote! {};
        let info = parse_return_type(&ret);
        assert!(info.is_unit);
        assert!(info.ty.is_none());
        assert!(!info.is_result);
        assert!(!info.is_option);
        assert!(!info.is_reference);
    }

    #[test]
    fn parse_return_type_regular_type() {
        let ret: ReturnType = syn::parse_quote! { -> String };
        let info = parse_return_type(&ret);
        assert!(!info.is_unit);
        assert!(!info.is_result);
        assert!(!info.is_option);
        assert!(!info.is_reference);
        assert!(info.ty.is_some());
    }

    #[test]
    fn parse_return_type_result() {
        let ret: ReturnType = syn::parse_quote! { -> Result<String, MyError> };
        let info = parse_return_type(&ret);
        assert!(info.is_result);
        assert!(!info.is_option);
        assert!(!info.is_unit);

        let ok = info.ok_type.unwrap();
        assert_eq!(quote!(#ok).to_string(), "String");

        let err = info.err_type.unwrap();
        assert_eq!(quote!(#err).to_string(), "MyError");
    }

    #[test]
    fn parse_return_type_option() {
        let ret: ReturnType = syn::parse_quote! { -> Option<i32> };
        let info = parse_return_type(&ret);
        assert!(info.is_option);
        assert!(!info.is_result);
        assert!(!info.is_unit);

        let some = info.some_type.unwrap();
        assert_eq!(quote!(#some).to_string(), "i32");
    }

    #[test]
    fn parse_return_type_unit_tuple() {
        let ret: ReturnType = syn::parse_quote! { -> () };
        let info = parse_return_type(&ret);
        assert!(info.is_unit);
        assert!(info.ty.is_some());
    }

    #[test]
    fn parse_return_type_reference() {
        let ret: ReturnType = syn::parse_quote! { -> &SubRouter };
        let info = parse_return_type(&ret);
        assert!(info.is_reference);
        assert!(!info.is_unit);

        let inner = info.reference_inner.unwrap();
        assert_eq!(quote!(#inner).to_string(), "SubRouter");
    }

    #[test]
    fn parse_return_type_stream() {
        let ret: ReturnType = syn::parse_quote! { -> impl Stream<Item = u64> };
        let info = parse_return_type(&ret);
        assert!(info.is_stream);
        assert!(!info.is_result);

        let item = info.stream_item.unwrap();
        assert_eq!(quote!(#item).to_string(), "u64");
    }

    // ── is_option_type / extract_option_type ────────────────────────

    #[test]
    fn is_option_type_true() {
        let ty: Type = syn::parse_quote! { Option<String> };
        assert!(is_option_type(&ty));
        let inner = extract_option_type(&ty).unwrap();
        assert_eq!(quote!(#inner).to_string(), "String");
    }

    #[test]
    fn is_option_type_false_for_non_option() {
        let ty: Type = syn::parse_quote! { String };
        assert!(!is_option_type(&ty));
        assert!(extract_option_type(&ty).is_none());
    }

    // ── extract_result_types ────────────────────────────────────────

    #[test]
    fn extract_result_types_works() {
        let ty: Type = syn::parse_quote! { Result<Vec<u8>, std::io::Error> };
        let (ok, err) = extract_result_types(&ty).unwrap();
        assert_eq!(quote!(#ok).to_string(), "Vec < u8 >");
        assert_eq!(quote!(#err).to_string(), "std :: io :: Error");
    }

    #[test]
    fn extract_result_types_none_for_non_result() {
        let ty: Type = syn::parse_quote! { Option<i32> };
        assert!(extract_result_types(&ty).is_none());
    }

    // ── is_unit_type ────────────────────────────────────────────────

    #[test]
    fn is_unit_type_true() {
        let ty: Type = syn::parse_quote! { () };
        assert!(is_unit_type(&ty));
    }

    #[test]
    fn is_unit_type_false_for_non_tuple() {
        let ty: Type = syn::parse_quote! { String };
        assert!(!is_unit_type(&ty));
    }

    #[test]
    fn is_unit_type_false_for_nonempty_tuple() {
        let ty: Type = syn::parse_quote! { (i32, i32) };
        assert!(!is_unit_type(&ty));
    }

    // ── is_id_param ─────────────────────────────────────────────────

    #[test]
    fn is_id_param_exact_id() {
        let ident: Ident = syn::parse_quote! { id };
        assert!(is_id_param(&ident));
    }

    #[test]
    fn is_id_param_suffix_id() {
        let ident: Ident = syn::parse_quote! { user_id };
        assert!(is_id_param(&ident));
    }

    #[test]
    fn is_id_param_false_for_other_names() {
        let ident: Ident = syn::parse_quote! { name };
        assert!(!is_id_param(&ident));
    }

    #[test]
    fn is_id_param_false_for_identity() {
        // "identity" ends with "id" but not "_id"
        let ident: Ident = syn::parse_quote! { identity };
        assert!(!is_id_param(&ident));
    }

    // ── MethodInfo::parse ───────────────────────────────────────────

    #[test]
    fn method_info_parse_basic() {
        let method: ImplItemFn = syn::parse_quote! {
            /// Does a thing
            fn greet(&self, name: String) -> String {
                format!("Hello {name}")
            }
        };
        let info = MethodInfo::parse(&method).unwrap().unwrap();
        assert_eq!(info.name.to_string(), "greet");
        assert!(!info.is_async);
        assert_eq!(info.docs.as_deref(), Some("Does a thing"));
        assert_eq!(info.params.len(), 1);
        assert_eq!(info.params[0].name.to_string(), "name");
        assert!(!info.params[0].is_optional);
        assert!(!info.params[0].is_id);
    }

    #[test]
    fn method_info_parse_async_method() {
        let method: ImplItemFn = syn::parse_quote! {
            async fn fetch(&self) -> Vec<u8> {
                vec![]
            }
        };
        let info = MethodInfo::parse(&method).unwrap().unwrap();
        assert!(info.is_async);
    }

    #[test]
    fn method_info_parse_skips_associated_function() {
        let method: ImplItemFn = syn::parse_quote! {
            fn new() -> Self {
                Self
            }
        };
        assert!(MethodInfo::parse(&method).unwrap().is_none());
    }

    #[test]
    fn method_info_parse_optional_param() {
        let method: ImplItemFn = syn::parse_quote! {
            fn search(&self, query: Option<String>) {}
        };
        let info = MethodInfo::parse(&method).unwrap().unwrap();
        assert!(info.params[0].is_optional);
    }

    #[test]
    fn method_info_parse_id_param() {
        let method: ImplItemFn = syn::parse_quote! {
            fn get_user(&self, user_id: u64) -> String {
                String::new()
            }
        };
        let info = MethodInfo::parse(&method).unwrap().unwrap();
        assert!(info.params[0].is_id);
    }

    #[test]
    fn method_info_parse_no_docs() {
        let method: ImplItemFn = syn::parse_quote! {
            fn bare(&self) {}
        };
        let info = MethodInfo::parse(&method).unwrap().unwrap();
        assert!(info.docs.is_none());
    }

    // ── extract_methods ─────────────────────────────────────────────

    #[test]
    fn extract_methods_basic() {
        let impl_block: ItemImpl = syn::parse_quote! {
            impl MyApi {
                fn hello(&self) -> String { String::new() }
                fn world(&self) -> String { String::new() }
            }
        };
        let methods = extract_methods(&impl_block).unwrap();
        assert_eq!(methods.len(), 2);
        assert_eq!(methods[0].name.to_string(), "hello");
        assert_eq!(methods[1].name.to_string(), "world");
    }

    #[test]
    fn extract_methods_skips_underscore_prefix() {
        let impl_block: ItemImpl = syn::parse_quote! {
            impl MyApi {
                fn public(&self) {}
                fn _private(&self) {}
                fn __also_private(&self) {}
            }
        };
        let methods = extract_methods(&impl_block).unwrap();
        assert_eq!(methods.len(), 1);
        assert_eq!(methods[0].name.to_string(), "public");
    }

    #[test]
    fn extract_methods_skips_associated_functions() {
        let impl_block: ItemImpl = syn::parse_quote! {
            impl MyApi {
                fn new() -> Self { Self }
                fn from_config(cfg: Config) -> Self { Self }
                fn greet(&self) -> String { String::new() }
            }
        };
        let methods = extract_methods(&impl_block).unwrap();
        assert_eq!(methods.len(), 1);
        assert_eq!(methods[0].name.to_string(), "greet");
    }

    // ── partition_methods ───────────────────────────────────────────

    #[test]
    fn partition_methods_splits_correctly() {
        let impl_block: ItemImpl = syn::parse_quote! {
            impl Router {
                fn leaf_action(&self) -> String { String::new() }
                fn static_mount(&self) -> &SubRouter { &self.sub }
                fn slug_mount(&self, id: u64) -> &SubRouter { &self.sub }
                async fn async_ref(&self) -> &SubRouter { &self.sub }
            }
        };
        let methods = extract_methods(&impl_block).unwrap();
        let partitioned = partition_methods(&methods, |_| false);

        // leaf_action and async_ref (async reference returns are leaf, not mounts)
        assert_eq!(partitioned.leaf.len(), 2);
        assert_eq!(partitioned.leaf[0].name.to_string(), "leaf_action");
        assert_eq!(partitioned.leaf[1].name.to_string(), "async_ref");

        assert_eq!(partitioned.static_mounts.len(), 1);
        assert_eq!(
            partitioned.static_mounts[0].name.to_string(),
            "static_mount"
        );

        assert_eq!(partitioned.slug_mounts.len(), 1);
        assert_eq!(partitioned.slug_mounts[0].name.to_string(), "slug_mount");
    }

    #[test]
    fn partition_methods_respects_skip() {
        let impl_block: ItemImpl = syn::parse_quote! {
            impl Router {
                fn keep(&self) -> String { String::new() }
                fn skip_me(&self) -> String { String::new() }
            }
        };
        let methods = extract_methods(&impl_block).unwrap();
        let partitioned = partition_methods(&methods, |m| m.name == "skip_me");

        assert_eq!(partitioned.leaf.len(), 1);
        assert_eq!(partitioned.leaf[0].name.to_string(), "keep");
    }

    // ── get_impl_name ───────────────────────────────────────────────

    #[test]
    fn get_impl_name_extracts_struct_name() {
        let impl_block: ItemImpl = syn::parse_quote! {
            impl MyService {
                fn hello(&self) {}
            }
        };
        let name = get_impl_name(&impl_block).unwrap();
        assert_eq!(name.to_string(), "MyService");
    }

    #[test]
    fn get_impl_name_with_generics() {
        let impl_block: ItemImpl = syn::parse_quote! {
            impl MyService<T> {
                fn hello(&self) {}
            }
        };
        let name = get_impl_name(&impl_block).unwrap();
        assert_eq!(name.to_string(), "MyService");
    }

    // ── ident_str ────────────────────────────────────────────────────

    #[test]
    fn ident_str_strips_raw_prefix() {
        let ident: Ident = syn::parse_quote!(r#type);
        assert_eq!(ident_str(&ident), "type");
    }

    #[test]
    fn ident_str_leaves_normal_ident_unchanged() {
        let ident: Ident = syn::parse_quote!(name);
        assert_eq!(ident_str(&ident), "name");
    }

    #[test]
    fn name_str_strips_raw_prefix_on_param() {
        let method: ImplItemFn = syn::parse_quote! {
            fn get(&self, r#type: String) -> String { r#type }
        };
        let info = MethodInfo::parse(&method).unwrap().unwrap();
        assert_eq!(info.params[0].name_str(), "type");
        // The Ident itself still has the raw prefix for code generation
        assert_eq!(info.params[0].name.to_string(), "r#type");
    }
}