miniextendr_macros/

naming.rs

//! Naming helpers for the static symbols the `#[miniextendr]` attribute emits.
//!
//! These formatters live in one place so the attribute macro and any later
//! consumer (e.g. a registration-chasing linter) can compute the exact same
//! identifiers from a source `syn::Ident`.

use syn::ext::IdentExt;

// region: raw identifiers
//
// Rust keywords are ordinary R names (`type`, `where`, `match`, `mod`, ...),
// so users spell them as raw identifiers: `fn r#match(r#where: &str)`. The
// `r#` prefix is Rust surface syntax only — `Display` for `syn::Ident` keeps it
// (`"r#where"`), which is neither a valid R name, nor a valid C symbol
// fragment, nor accepted by `syn::Ident::new` / `format_ident!`. Every place
// that turns a user identifier into a *name* (R formals, R function/method
// names, list/data-frame column names, C symbols, HashMap keys, synthesized
// Rust bindings) must go through `ident_name` / `unraw` instead of
// `to_string()` / direct interpolation. Token positions (`quote! { #ident }`)
// keep the raw ident — `r#where` is what the Rust side needs.

/// The user's identifier as a plain name: `r#where` → `"where"`, `x` → `"x"`.
pub(crate) fn ident_name(ident: &syn::Ident) -> String {
    ident.unraw().to_string()
}

/// The user's identifier without its `r#` prefix, for `format_ident!` /
/// `quote!` interpolation into *synthesized* identifiers (`__storage_where`).
/// Not for emitting the identifier itself — `where` is not a valid binding.
pub(crate) fn unraw(ident: &syn::Ident) -> syn::Ident {
    ident.unraw()
}

/// A *name* (a column / list-element name, from a user field or a `rename`)
/// as a Rust identifier for a generated struct field or binding. Keywords come
/// back raw so `type` emits `r#type` instead of an unparsable token stream.
pub(crate) fn name_ident(name: &str) -> syn::Ident {
    syn::parse_str::<syn::Ident>(name)
        .unwrap_or_else(|_| syn::Ident::new_raw(name, proc_macro2::Span::call_site()))
}
// endregion

/// Local repr(C) type for a concrete trait vtable. Only the static beside it
/// is exported to C; this type reproduces the declaration's supplied layout.
pub(crate) fn vtable_layout_ident(trait_name: &syn::Ident, type_name: &str) -> syn::Ident {
    let table = vtable_static_ident(trait_name, type_name);
    quote::format_ident!("{table}_Layout")
}

/// Identifier for the registration entry holding the R wrapper source.
///
/// Returns `R_WRAPPER_{rust_ident}`, preserving case.
pub(crate) fn r_wrapper_const_ident_for(rust_ident: &syn::Ident) -> syn::Ident {
    let name = unraw(rust_ident);
    quote::format_ident!("R_WRAPPER_{name}")
}

/// The binder of a conditional bound, `for<'__mx_cond> FieldTy: Trait`.
///
/// A where clause on a concrete type that does not hold is an error where the
/// impl is written (E0277). Behind a higher-ranked binder the same bound is
/// checked where the impl is used, so the impl just does not apply to that
/// type. Derives use it for impls that exist only when the user's field types
/// allow them, such as a companion's `Debug`. The name stays clear of user
/// lifetimes, which a binder must not shadow (E0496).
pub(crate) fn conditional_bound_lifetime() -> syn::Lifetime {
    syn::Lifetime::new("'__mx_cond", proc_macro2::Span::call_site())
}

/// The C wrapper's receiver slot, shared with method extraction and return
/// handling. Its mixed-site span keeps a user parameter named `self_sexp`
/// from replacing the original R handle after conversion.
pub(crate) fn self_sexp_ident() -> syn::Ident {
    syn::Ident::new("self_sexp", proc_macro2::Span::mixed_site())
}

/// The C wrapper's call slot, declared by `CWrapperContext` with `quote!`.
/// A reference inside a `quote_spanned!` template would take the user type's
/// span instead. That only resolves while the macro's call site is the
/// user's, not when the wrapper is generated inside a `macro_rules!`
/// expansion, as a trait impl's is (#1489). So references interpolate this.
pub(crate) fn call_slot_ident() -> syn::Ident {
    syn::Ident::new("__miniextendr_call", proc_macro2::Span::call_site())
}

/// The error a failed argument conversion binds, for the same reason as
/// [`call_slot_ident`]: the binding and the expressions that read it are
/// built in different templates.
pub(crate) fn conversion_error_ident() -> syn::Ident {
    syn::Ident::new("e", proc_macro2::Span::call_site())
}

/// A private export name for a trait's metadata macro. The public macro is
/// re-exported beside the trait under the trait's own name, in Rust's separate
/// macro namespace, so imports carry both. An expansion-local suffix prevents
/// same-named traits in different modules from colliding at the crate root.
/// This name never enters the trait tag or any C/wasm registration symbol.
pub(crate) fn trait_metadata_macro_ident(trait_name: &syn::Ident) -> syn::Ident {
    use std::sync::atomic::{AtomicUsize, Ordering};
    static NEXT: AtomicUsize = AtomicUsize::new(0);
    let suffix = NEXT.fetch_add(1, Ordering::Relaxed);
    let name = unraw(trait_name);
    quote::format_ident!("__mx_trait_metadata_{name}_{suffix}")
}

// region: crate-prefixed C symbol naming (#1273)
//
// Every `#[miniextendr]`-emitted `#[no_mangle]` C symbol is prefixed with the
// consuming crate's name so that two packages loaded into the same webR
// session (which share one GOT under Emscripten's SIDE_MODULE model) can't
// have the first-loaded package's definition of a name silently win for a
// later package's identically-named export. Native `dyn.load` with
// `RTLD_LOCAL` was never affected — this is purely a wasm cross-package
// hygiene fix — but the prefix is applied unconditionally on every target so
// there's a single code path and no target-dependent symbol shape.
//
// Registration name and linker symbol name are kept identical everywhere
// (the invariant the wasm snapshot writer,
// `miniextendr-api/src/wasm_registry_writer.rs`, depends on to reconstruct
// `extern "C" { fn <name>(...); }` blocks from `R_CallMethodDef.name`) — so
// every formatter below produces the *one* string used for both the
// `#[no_mangle]` fn/static definition and its registration entry.

/// The consuming crate's name, used as the prefix for every macro-emitted
/// `#[no_mangle]` C symbol.
///
/// Reads `CARGO_CRATE_NAME`, which cargo sets (with hyphens already
/// normalized to underscores) for the rustc invocation that expands this
/// proc macro — the same precedent `miniextendr_init!()` relies on
/// (`lib.rs`, `miniextendr_init` fn). Real macro expansion (i.e. compiling a
/// downstream crate through cargo) always has this set.
///
/// Falls back to `CARGO_PKG_NAME` (normalized the same way, since it is
/// *not* auto-normalized) for the one context where `CARGO_CRATE_NAME` is
/// absent: this crate's own unit/insta tests call codegen functions directly
/// at test *runtime* rather than through real macro expansion, and cargo
/// does not forward `CARGO_CRATE_NAME` to a test binary's process
/// environment (verified empirically — only `CARGO_PKG_*` vars are). Falls
/// back further to the literal `"crate"` if even that is absent (e.g. a
/// direct `rustc` invocation bypassing cargo entirely).
pub(crate) fn crate_prefix() -> String {
    std::env::var("CARGO_CRATE_NAME").unwrap_or_else(|_| {
        std::env::var("CARGO_PKG_NAME")
            .map(|n| n.replace('-', "_"))
            .unwrap_or_else(|_| "crate".to_string())
    })
}

/// `C_<crate>_<fn>` — bare-fn C wrapper identifier (internal-wrapper arm
/// only; `extern`/`#[export_name]` fns pass through untouched and own their
/// own cross-package uniqueness).
pub(crate) fn bare_fn_c_wrapper_ident(rust_ident: &syn::Ident) -> syn::Ident {
    let prefix = crate_prefix();
    let rust_ident = unraw(rust_ident);
    quote::format_ident!("C_{prefix}_{rust_ident}")
}

/// `C_<crate>_<Type>__<method>` — impl-method C wrapper identifier.
pub(crate) fn impl_method_c_wrapper_ident(
    type_ident: &syn::Ident,
    method_ident: &syn::Ident,
) -> syn::Ident {
    let prefix = crate_prefix();
    let method_ident = unraw(method_ident);
    quote::format_ident!("C_{prefix}_{type_ident}__{method_ident}")
}

/// `C_<crate>_<Type>__<Trait>__<member>` as a `String` — shared by
/// `TraitMethod` and `TraitConst`, and by both the ident and string forms
/// each needs, so the format string can't drift across the four call sites
/// that used to duplicate it.
pub(crate) fn trait_member_c_wrapper_string(
    type_ident: &syn::Ident,
    trait_name: &syn::Ident,
    member_ident: &syn::Ident,
) -> String {
    let prefix = crate_prefix();
    let member_ident = unraw(member_ident);
    format!("C_{prefix}_{type_ident}__{trait_name}__{member_ident}")
}

/// Same as [`trait_member_c_wrapper_string`], as a `syn::Ident` for Rust
/// token generation.
pub(crate) fn trait_member_c_wrapper_ident(
    type_ident: &syn::Ident,
    trait_name: &syn::Ident,
    member_ident: &syn::Ident,
) -> syn::Ident {
    quote::format_ident!(
        "{}",
        trait_member_c_wrapper_string(type_ident, trait_name, member_ident)
    )
}

/// `C_<crate>__mx_rdata_get_<Type>_<field>` — sidecar field getter C symbol.
pub(crate) fn sidecar_getter_c_name(type_name: &str, field_name: &str) -> String {
    let prefix = crate_prefix();
    format!("C_{prefix}__mx_rdata_get_{type_name}_{field_name}")
}

/// `C_<crate>__mx_rdata_set_<Type>_<field>` — sidecar field setter C symbol.
pub(crate) fn sidecar_setter_c_name(type_name: &str, field_name: &str) -> String {
    let prefix = crate_prefix();
    format!("C_{prefix}__mx_rdata_set_{type_name}_{field_name}")
}

/// `C_<crate>__mx_all_equal_<Type>` — the field reader of the `all.equal()`
/// method of `#[derive(AllEqual)]` (#2149).
pub(crate) fn all_equal_c_name(type_name: &str) -> String {
    let prefix = crate_prefix();
    format!("C_{prefix}__mx_all_equal_{type_name}")
}

/// `C_<crate>__mx_rdata_live_<Type>` — the liveness check of a type with
/// `#[externalptr(restored(refuse = "every_read"))]` (#1901).
pub(crate) fn sidecar_live_c_name(type_name: &str) -> String {
    let prefix = crate_prefix();
    format!("C_{prefix}__mx_rdata_live_{type_name}")
}

/// `C_<crate>__mx_rdata_fallback_<Type>` — the field fallback of an S3, S4
/// or env class with `r_data_accessors` (`fallback = "Self::f"`, #2150),
/// which the impl block that has it emits.
pub(crate) fn sidecar_fallback_c_name(type_name: &str) -> String {
    let prefix = crate_prefix();
    format!("C_{prefix}__mx_rdata_fallback_{type_name}")
}

/// `C_<crate>__mx_rdata_names_<Type>` — the names the field fallback
/// answers, for `.DollarNames()` (`fallback_names = "Self::g"`, #2150).
pub(crate) fn sidecar_fallback_names_c_name(type_name: &str) -> String {
    let prefix = crate_prefix();
    format!("C_{prefix}__mx_rdata_names_{type_name}")
}

/// The R helpers `#[derive(ExternalPtr)]` emits for a type's sidecar fields
/// and the `$` / `[[` field methods of `r_data_accessors` call (#1848).
#[derive(Debug, Clone, Copy)]
pub(crate) enum RDataHelper {
    /// `.rdata_fields_<Type>`: the field names, a character vector.
    Fields,
    /// `.rdata_get_<Type>(x, name)`: the field's getter `.Call()`.
    Get,
    /// `.rdata_set_<Type>(x, name, value)`: the field's setter `.Call()`.
    Set,
    /// `.rdata_no_field_<Type>(name, env, cls)`: the `miniextendr_no_field`
    /// error, naming the R class `cls` the method serves.
    NoField,
    /// `.rdata_error_class_<Type>`: the classes the field methods put in
    /// front of their own errors, `#[externalptr(field_error(class = ...))]`
    /// (#1899); `NULL` without them.
    ErrorClass,
    /// `.rdata_every_read_<Type>`: `TRUE` for a type with
    /// `restored(refuse = "every_read")` (#1901), else `FALSE`; it gates the
    /// field methods' calls of [`RDataHelper::Live`].
    EveryRead,
    /// `.rdata_live_<Type>(x, raise)`: the liveness check of a type with
    /// `restored(refuse = "every_read")` (#1901). Other types get a stub that
    /// is never called (gated by [`RDataHelper::EveryRead`]), so a binding
    /// the methods call is always a function, as `R CMD check` expects.
    Live,
}

/// `.rdata_<helper>_<Type>`: the R name of a sidecar field helper, named by
/// the Rust type (not an impl's `class = "..."`), since the derive only knows
/// the type.
pub(crate) fn rdata_helper_name(helper: RDataHelper, type_name: &str) -> String {
    let helper = match helper {
        RDataHelper::Fields => "fields",
        RDataHelper::Get => "get",
        RDataHelper::Set => "set",
        RDataHelper::NoField => "no_field",
        RDataHelper::ErrorClass => "error_class",
        RDataHelper::EveryRead => "every_read",
        RDataHelper::Live => "live",
    };
    format!(".rdata_{helper}_{type_name}")
}

/// `__mx_altrep_reg_<crate>_<Ident>` — ALTREP class registration fn.
pub(crate) fn altrep_reg_fn_ident(ident: &syn::Ident) -> syn::Ident {
    let prefix = crate_prefix();
    quote::format_ident!("__mx_altrep_reg_{prefix}_{ident}")
}

/// `__VTABLE_<crate>_<Trait>_FOR_<Type>` — trait-impl vtable static.
/// Preserve spelling: Rust distinguishes `Counter` from `counter`, as must
/// both the Rust identifier and the exported linker symbol. `type_name` may
/// carry the existing generic-argument hash suffix.
pub(crate) fn vtable_static_ident(trait_name: &syn::Ident, type_name: &str) -> syn::Ident {
    let prefix = crate_prefix();
    let trait_name = unraw(trait_name);
    quote::format_ident!("__VTABLE_{prefix}_{trait_name}_FOR_{type_name}")
}

/// Trait tag, shared by the declaration and both impl expansion paths.
pub(crate) fn trait_tag_ident(trait_name: &syn::Ident) -> syn::Ident {
    let trait_name = unraw(trait_name);
    quote::format_ident!("TAG_{trait_name}")
}

/// Trait vtable builder, defined beside the trait and called from its impls.
pub(crate) fn trait_vtable_builder_ident(trait_name: &syn::Ident) -> syn::Ident {
    let trait_name = unraw(trait_name);
    quote::format_ident!("__{trait_name}_build_vtable")
}

/// Generic shim defined beside a non-generic trait.
pub(crate) fn trait_method_shim_ident(
    trait_name: &syn::Ident,
    method_name: &syn::Ident,
) -> syn::Ident {
    let trait_name = unraw(trait_name);
    let method_name = unraw(method_name);
    quote::format_ident!("__{trait_name}_{method_name}_shim")
}

/// Wrapper fragment registered by either trait impl expansion path.
pub(crate) fn trait_impl_wrappers_ident(type_name: &str, trait_name: &syn::Ident) -> syn::Ident {
    let trait_name = unraw(trait_name);
    quote::format_ident!("R_WRAPPERS_{type_name}_{trait_name}_IMPL")
}

/// Trait dispatch registration; uses the same type suffix as its vtable.
pub(crate) fn trait_dispatch_ident(trait_name: &syn::Ident, type_name: &str) -> syn::Ident {
    let trait_name = unraw(trait_name);
    quote::format_ident!("__MX_DISPATCH_{trait_name}_FOR_{type_name}")
}

/// `__vtshim_<crate>_<Type>__<Trait>__<method>` — trait-impl vtable shim fn.
pub(crate) fn vtshim_ident(
    type_ident: &syn::Ident,
    trait_name: &syn::Ident,
    method_ident: &syn::Ident,
) -> syn::Ident {
    let prefix = crate_prefix();
    let method_ident = unraw(method_ident);
    quote::format_ident!("__vtshim_{prefix}_{type_ident}__{trait_name}__{method_ident}")
}
// endregion

/// Convert a PascalCase string to snake_case.
///
/// Inserts an underscore before each uppercase letter (except the first),
/// then lowercases the entire result. For example, `"InProgress"` becomes
/// `"in_progress"`.
pub(crate) fn to_snake_case(s: &str) -> String {
    let mut out = String::new();
    for (i, c) in s.char_indices() {
        if c.is_uppercase() && i > 0 {
            out.push('_');
        }
        out.extend(c.to_lowercase());
    }
    out
}

/// Convert a PascalCase string to kebab-case (`InProgress` → `in-progress`).
pub(crate) fn to_kebab_case(s: &str) -> String {
    to_snake_case(s).replace('_', "-")
}

/// Apply a `rename_all` transformation to a variant name.
///
/// Supports `"snake_case"`, `"kebab-case"`, `"lower"`, `"upper"`. Returns the
/// name unchanged if `rename_all` is `None` or unrecognised.
pub(crate) fn apply_rename_all(name: &str, rename_all: Option<&str>) -> String {
    match rename_all {
        Some("snake_case") => to_snake_case(name),
        Some("kebab-case") => to_kebab_case(name),
        Some("lower") => name.to_lowercase(),
        Some("upper") => name.to_uppercase(),
        _ => name.to_string(),
    }
}

// region: R definition names

/// R's reserved words: never usable as a bare name on the left of `<-`.
const R_RESERVED_WORDS: &[&str] = &[
    "if",
    "else",
    "repeat",
    "while",
    "function",
    "for",
    "next",
    "break",
    "TRUE",
    "FALSE",
    "NULL",
    "Inf",
    "NaN",
    "NA",
    "NA_integer_",
    "NA_real_",
    "NA_character_",
    "NA_complex_",
    "in",
];

/// Whether `name` is one of R's reserved words (`if`, `in`, `TRUE`, `NA`, ...).
pub(crate) fn is_r_reserved_word(name: &str) -> bool {
    R_RESERVED_WORDS.contains(&name)
}

/// Whether `name` is a syntactic R name: ASCII letters, digits, `.` and `_`
/// only; starts with a letter, or with a `.` that is not followed by a digit;
/// and is not a reserved word. Anything else (`[.foo`, `$.foo`, `==.foo`,
/// `%in%.foo`) has to be backtick-quoted in source.
pub(crate) fn is_syntactic_r_name(name: &str) -> bool {
    let mut chars = name.chars();
    match chars.next() {
        Some(c) if c.is_ascii_alphabetic() => {}
        Some('.') => {
            if chars.next().is_some_and(|c| c.is_ascii_digit()) {
                return false;
            }
        }
        _ => return false,
    }
    name.chars()
        .all(|c| c.is_ascii_alphanumeric() || c == '.' || c == '_')
        && !is_r_reserved_word(name)
}

/// R's rule for a package name (Writing R Extensions, "The DESCRIPTION
/// file"): ASCII letters, digits and `.`, at least two characters, starting
/// with a letter and not ending in `.`.
pub(crate) fn is_r_package_name(name: &str) -> bool {
    let bytes = name.as_bytes();
    bytes.len() >= 2
        && bytes[0].is_ascii_alphabetic()
        && bytes[bytes.len() - 1] != b'.'
        && bytes
            .iter()
            .all(|b| b.is_ascii_alphanumeric() || *b == b'.')
}

/// The left-hand side of a generated `<name> <- function(...)` definition.
///
/// Syntactic names pass through unchanged so the common output stays readable;
/// a non-syntactic one (an S3 method on `[`, `$`, `==`, ...) is wrapped in
/// backticks, which R accepts for any name. Without this the wrapper file did
/// not parse (#1475).
///
/// R processes backslash escapes inside backticks as it does in strings, so a
/// `\` is doubled (first, so the escapes added for backticks stay single) and a
/// backtick becomes `` \` ``: the name `a\b` is written `` `a\\b` ``.
/// `miniextendr-api`'s duplicate-definition scan
/// (`registry::parse_top_level_fn_def_name`) reads this escaped spelling.
pub(crate) fn r_def_name(name: &str) -> String {
    if is_syntactic_r_name(name) {
        name.to_string()
    } else {
        format!("`{}`", name.replace('\\', "\\\\").replace('`', "\\`"))
    }
}

/// The argument of a raw NAMESPACE directive such as `export(<name>)`.
///
/// `@rawNamespace` lines reach NAMESPACE verbatim, so roxygen2 does not quote
/// them the way it quotes `@export <name>`. Syntactic names stay bare; a
/// non-syntactic one (an S7 generic on `[[` or `%op%`) becomes a double-quoted
/// string, the form roxygen2 itself writes, because `export([[)` does not parse.
/// `miniextendr-api`'s generic-doc pass mirrors this rule
/// (`registry::r_namespace_name`); the two must stay in step so roxygen2 sees
/// one directive, not two spellings of it. Only `\` and `"` are escaped, as
/// the mirror does ([`r_string_escape`] would also escape control and
/// non-ASCII characters).
pub(crate) fn r_namespace_name(name: &str) -> String {
    if is_syntactic_r_name(name) {
        name.to_string()
    } else {
        format!("\"{}\"", name.replace('\\', "\\\\").replace('"', "\\\""))
    }
}

/// Escape `s` for the inside of an R double-quoted string literal. Every
/// generated R string literal built from user text goes through this (the
/// precondition requirement text and the author's messages, the class names
/// in `inherits()`, lifecycle arguments).
///
/// Besides `\` and `"`, a newline, carriage return or tab becomes its escape
/// (a guard stays on one line of the wrappers file), any other control
/// character and every non-ASCII character a `\u{..}` / `\U{..}` escape: R
/// code in a package must be ASCII, and R reads these escapes back to the
/// same UTF-8 text. A NUL cannot be written (R strings cannot hold one);
/// the attribute parser rejects it in a message.
pub(crate) fn r_string_escape(s: &str) -> String {
    use std::fmt::Write as _;
    let mut out = String::with_capacity(s.len());
    for c in s.chars() {
        match c {
            '\\' => out.push_str("\\\\"),
            '"' => out.push_str("\\\""),
            '\n' => out.push_str("\\n"),
            '\r' => out.push_str("\\r"),
            '\t' => out.push_str("\\t"),
            c if c.is_ascii() && !c.is_ascii_control() => out.push(c),
            c if u32::from(c) <= 0xFFFF => {
                let _ = write!(out, "\\u{{{:x}}}", u32::from(c));
            }
            c => {
                let _ = write!(out, "\\U{{{:x}}}", u32::from(c));
            }
        }
    }
    out
}

// endregion

// region: package-qualified generics (#2154)

/// A `generic = "..."` value split into its package and the generic's own
/// name: `"dplyr::dplyr_reconstruct"` is `(Some("dplyr"), "dplyr_reconstruct")`,
/// `"print"` is `(None, "print")`. The value must have passed
/// [`parse_generic`].
pub(crate) fn split_generic(generic: &str) -> (Option<&str>, &str) {
    match generic.split_once("::") {
        Some((package, name)) => (Some(package), name),
        None => (None, generic),
    }
}

/// Parse a `generic = "..."` value. A generic may name its package,
/// `pkg::generic`, with a valid R package name (ASCII letters, digits and
/// `.`; at least two characters; starts with a letter; doesn't end in `.`)
/// and one `::`.
pub(crate) fn parse_generic(value: &syn::LitStr) -> syn::Result<String> {
    let generic = value.value();
    let error = |message: String| Err(syn::Error::new(value.span(), message));
    if generic.contains(":::") {
        return error(format!(
            "`{generic}`: a method registers on an exported generic; name it `pkg::generic`, \
             not `pkg:::generic`"
        ));
    }
    let Some((package, name)) = generic.split_once("::") else {
        return Ok(generic);
    };
    if name.contains("::") {
        return error(format!(
            "`{generic}`: a generic takes one `pkg::` qualifier"
        ));
    }
    if name.is_empty() {
        return error(format!("`{generic}`: no generic name after `{package}::`"));
    }
    if !is_r_package_name(package) {
        return error(format!(
            "`{generic}`: `{package}` is not an R package name; a package name has only ASCII \
             letters, digits and `.`, at least two characters, starts with a letter and \
             doesn't end in `.`"
        ));
    }
    Ok(generic)
}

// endregion

/// Parse a dispatch receiver that is safe to emit as a bare R symbol.
pub(crate) fn parse_r_receiver(value: &syn::LitStr) -> syn::Result<String> {
    let name = value.value();
    if !is_syntactic_r_name(&name) || !crate::r_class_formatter::is_bare_identifier(&name) {
        return Err(syn::Error::new(
            value.span(),
            "receiver must start with a letter and contain only letters, digits and underscores",
        ));
    }
    Ok(name)
}

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

    // At unit-test runtime cargo does not forward CARGO_CRATE_NAME to the
    // test binary's process env, so crate_prefix() takes the CARGO_PKG_NAME
    // fallback: "miniextendr-macros" → "miniextendr_macros". Real macro
    // expansion (inside rustc) always sees CARGO_CRATE_NAME. The insta
    // snapshots pin the same value; if this test fails the snapshots are
    // stale too.
    #[test]
    fn crate_prefix_fallback_is_normalized_pkg_name() {
        assert_eq!(crate_prefix(), "miniextendr_macros");
    }

    #[test]
    fn c_symbols_are_crate_prefixed() {
        let ty = quote::format_ident!("Counter");
        let tr = quote::format_ident!("Resettable");
        let m = quote::format_ident!("reset");
        assert_eq!(
            bare_fn_c_wrapper_ident(&m).to_string(),
            "C_miniextendr_macros_reset"
        );
        assert_eq!(
            impl_method_c_wrapper_ident(&ty, &m).to_string(),
            "C_miniextendr_macros_Counter__reset"
        );
        assert_eq!(
            trait_member_c_wrapper_string(&ty, &tr, &m),
            "C_miniextendr_macros_Counter__Resettable__reset"
        );
        assert_eq!(
            trait_member_c_wrapper_ident(&ty, &tr, &m).to_string(),
            trait_member_c_wrapper_string(&ty, &tr, &m)
        );
        assert_eq!(
            sidecar_getter_c_name("Counter", "count"),
            "C_miniextendr_macros__mx_rdata_get_Counter_count"
        );
        assert_eq!(
            sidecar_setter_c_name("Counter", "count"),
            "C_miniextendr_macros__mx_rdata_set_Counter_count"
        );
        assert_eq!(
            altrep_reg_fn_ident(&ty).to_string(),
            "__mx_altrep_reg_miniextendr_macros_Counter"
        );
        assert_eq!(
            vtable_static_ident(&tr, "Counter").to_string(),
            "__VTABLE_miniextendr_macros_Resettable_FOR_Counter"
        );
        assert_eq!(
            vtshim_ident(&ty, &tr, &m).to_string(),
            "__vtshim_miniextendr_macros_Counter__Resettable__reset"
        );
    }

    #[test]
    fn trait_symbols_preserve_case_and_strip_raw_prefixes() {
        let upper = quote::format_ident!("Counter");
        let lower = quote::format_ident!("counter");
        let method = quote::format_ident!("value");
        assert_ne!(
            vtable_static_ident(&upper, "Foo"),
            vtable_static_ident(&lower, "Foo")
        );
        assert_ne!(
            vtable_static_ident(&upper, "Foo"),
            vtable_static_ident(&upper, "foo")
        );
        assert_ne!(trait_tag_ident(&upper), trait_tag_ident(&lower));
        assert_ne!(
            trait_vtable_builder_ident(&upper),
            trait_vtable_builder_ident(&lower)
        );
        assert_ne!(
            trait_method_shim_ident(&upper, &method),
            trait_method_shim_ident(&lower, &method)
        );
        assert_ne!(
            trait_impl_wrappers_ident("Foo", &upper),
            trait_impl_wrappers_ident("Foo", &lower)
        );
        assert_ne!(
            trait_dispatch_ident(&upper, "Foo"),
            trait_dispatch_ident(&lower, "Foo")
        );
        let raw: syn::Ident = syn::parse_quote!(r#match);
        assert_eq!(trait_tag_ident(&raw), "TAG_match");
        assert_eq!(trait_vtable_builder_ident(&raw), "__match_build_vtable");
        assert_eq!(
            trait_method_shim_ident(&upper, &raw),
            "__Counter_match_shim"
        );
    }

    #[test]
    fn raw_identifiers_lose_their_prefix_in_names() {
        let raw: syn::Ident = syn::parse_quote!(r#where);
        let plain: syn::Ident = syn::parse_quote!(x);
        assert_eq!(raw.to_string(), "r#where", "Display keeps the prefix");
        assert_eq!(ident_name(&raw), "where");
        assert_eq!(ident_name(&plain), "x");
        assert_eq!(unraw(&raw).to_string(), "where");
        assert_eq!(
            quote::format_ident!("__storage_{}", unraw(&raw)),
            "__storage_where"
        );
        // The C symbol / const-name formatters unraw internally.
        assert_eq!(
            bare_fn_c_wrapper_ident(&syn::parse_quote!(r#match)).to_string(),
            "C_miniextendr_macros_match"
        );
        assert_eq!(
            r_wrapper_const_ident_for(&syn::parse_quote!(r#match)).to_string(),
            "R_WRAPPER_match"
        );
        let ty: syn::Ident = syn::parse_quote!(Row);
        assert_eq!(
            impl_method_c_wrapper_ident(&ty, &syn::parse_quote!(r#type)).to_string(),
            "C_miniextendr_macros_Row__type"
        );
    }

    #[test]
    fn name_ident_makes_keywords_raw() {
        assert_eq!(name_ident("type").to_string(), "r#type");
        assert_eq!(name_ident("where").to_string(), "r#where");
        assert_eq!(name_ident("value").to_string(), "value");
        // Round-trips: a raw ident's name maps back to the same raw ident.
        let raw: syn::Ident = syn::parse_quote!(r#type);
        assert_eq!(name_ident(&ident_name(&raw)), raw);
    }

    #[test]
    fn snake_case() {
        assert_eq!(to_snake_case("HelloWorld"), "hello_world");
        assert_eq!(to_snake_case("InProgress"), "in_progress");
        assert_eq!(to_snake_case("ABC"), "a_b_c");
        assert_eq!(to_snake_case("Red"), "red");
    }

    #[test]
    fn kebab_case() {
        assert_eq!(to_kebab_case("HelloWorld"), "hello-world");
        assert_eq!(to_kebab_case("InProgress"), "in-progress");
    }

    #[test]
    fn rename_all() {
        assert_eq!(
            apply_rename_all("HelloWorld", Some("snake_case")),
            "hello_world"
        );
        assert_eq!(
            apply_rename_all("HelloWorld", Some("kebab-case")),
            "hello-world"
        );
        assert_eq!(apply_rename_all("HelloWorld", Some("lower")), "helloworld");
        assert_eq!(apply_rename_all("HelloWorld", Some("upper")), "HELLOWORLD");
        assert_eq!(apply_rename_all("HelloWorld", None), "HelloWorld");
    }

    #[test]
    fn namespace_names_quote_operators_only() {
        for name in ["get", "var", ".hidden", "s7_trait_Ops_value", "Foo_at"] {
            assert_eq!(r_namespace_name(name), name);
            assert_eq!(r_def_name(name), name);
        }
        for (name, ns, def) in [
            ("[", r#""[""#, "`[`"),
            ("[[", r#""[[""#, "`[[`"),
            ("$", r#""$""#, "`$`"),
            ("%custom%", r#""%custom%""#, "`%custom%`"),
            ("Foo_[[", r#""Foo_[[""#, "`Foo_[[`"),
            ("if", r#""if""#, "`if`"),
        ] {
            assert_eq!(r_namespace_name(name), ns);
            assert_eq!(r_def_name(name), def);
        }
        // The NAMESPACE form is an R string literal: escape `"` and `\`.
        assert_eq!(r_namespace_name(r#"a"b\c"#), r#""a\"b\\c""#);
    }

    #[test]
    fn def_names_escape_backslashes_before_backticks() {
        // R reads backslash escapes inside backticks, so `\` must be doubled
        // (`` `a\\b` `` is the three-character name `a\b`) and a trailing one must
        // not escape the closing backtick.
        assert_eq!(r_def_name(r"a\b"), r"`a\\b`");
        assert_eq!(r_def_name(r"trail\"), r"`trail\\`");
        assert_eq!(r_def_name("a`b"), r"`a\`b`");
        // A backslash next to a backtick: each is escaped once, in order.
        assert_eq!(r_def_name(r"x\`y"), r"`x\\\`y`");
        assert_eq!(r_def_name(r"%\%"), r"`%\\%`");
    }

    #[test]
    fn package_qualified_generics() {
        let parse = |s: &str| parse_generic(&syn::LitStr::new(s, proc_macro2::Span::call_site()));
        for ok in [
            "print",
            "[[",
            "dplyr::dplyr_reconstruct",
            "data.table::as.data.table",
        ] {
            assert_eq!(parse(ok).unwrap(), ok);
        }
        assert_eq!(
            split_generic("vctrs::vec_ptype2"),
            (Some("vctrs"), "vec_ptype2")
        );
        assert_eq!(split_generic("format"), (None, "format"));
        for (bad, why) in [
            ("dplyr:::dplyr_reconstruct", "not `pkg:::generic`"),
            ("a::b::c", "one `pkg::` qualifier"),
            ("dplyr::", "no generic name"),
            ("::print", "not an R package name"),
            ("x::print", "not an R package name"),
            ("2pkg::print", "not an R package name"),
            ("pkg.::print", "not an R package name"),
            ("my_pkg::print", "not an R package name"),
        ] {
            let message = parse(bad).unwrap_err().to_string();
            assert!(message.contains(why), "{bad}: {message}");
        }
    }
}