miniextendr_api/

registry.rs

//! Automatic registration for miniextendr.
//!
//! Every `#[miniextendr]` item self-registers at link time. `package_init()`
//! (generated by `miniextendr_init!`) calls [`miniextendr_register_routines`](crate::registry::miniextendr_register_routines)
//! during `R_init_*` to finalize registration with R. Users never interact
//! with this module.

use crate::abi::{mx_erased, mx_tag};
use crate::sys::{DllInfo, R_CallMethodDef};
#[cfg(not(target_arch = "wasm32"))]
use linkme::distributed_slice;
use std::os::raw::c_void;

// region: Distributed Slices
//
// `linkme::distributed_slice` does not compile for `wasm32-*` targets — the
// proc macro hits a `compile_error!` arm in `linkme-impl/src/declaration.rs`.
// On wasm32 we keep the same public surface for the three runtime-critical
// slices (MX_CALL_DEFS / MX_ALTREP_REGISTRATIONS / MX_TRAIT_DISPATCH) but
// back them with a `OnceLock` populated from the user crate's
// `wasm_registry.rs` snapshot at `R_init_*` time (see
// `install_wasm_runtime_slices` below). The five host-only slices
// (MX_R_WRAPPERS, MX_MATCH_ARG_*, MX_CLASS_NAMES, MX_S7_SIDECAR_PROPS) are
// only consumed by the wrapper-gen pass — that pass is itself
// native-only, so the slices, their consumers, and the `wasm_registry_writer`
// module are all `cfg(not(target_arch = "wasm32"))`-gated.

/// R `.Call` method registrations (function + method C wrappers).
///
/// Each `#[miniextendr]` function or method emits an entry here.
#[cfg(not(target_arch = "wasm32"))]
#[distributed_slice]
pub static MX_CALL_DEFS: [R_CallMethodDef];

/// R wrapper code fragments with priority for ordering. **Host-only.**
///
/// Each `#[miniextendr]` function, impl block, or trait impl emits an entry.
/// Priorities ensure correct evaluation order when R sources the wrapper file
/// (sidecar helpers must be defined before class definitions that reference them).
#[cfg(not(target_arch = "wasm32"))]
#[distributed_slice]
pub static MX_R_WRAPPERS: [RWrapperEntry];

/// ALTREP class registration entries, called once at package init.
///
/// Each ALTREP struct or trait impl emits an entry pairing the registration
/// function pointer with its `#[no_mangle]` symbol name. The fn is declared
/// `pub extern "C"` with `#[unsafe(no_mangle)]`, making it externally
/// addressable from a separate compilation unit (e.g. the WASM snapshot
/// codegen path). The fn pointer is not `unsafe` — R-thread invariants are a
/// module-level contract, not encoded in the type (same convention as the
/// `extern "C-unwind" fn` entries in `MX_CALL_DEFS`). The `symbol` string is
/// consumed by the host-time WASM snapshot writer to emit
/// `extern "C" { fn <symbol>(); }` declarations in `wasm_registry.rs`.
#[cfg(not(target_arch = "wasm32"))]
#[distributed_slice]
pub static MX_ALTREP_REGISTRATIONS: [AltrepRegistration];

/// Trait dispatch entries for [`universal_query`].
///
/// Each `#[miniextendr] impl Trait for Type` emits an entry mapping
/// `(concrete_tag, trait_tag)` to the trait's vtable pointer.
#[cfg(not(target_arch = "wasm32"))]
#[distributed_slice]
pub static MX_TRAIT_DISPATCH: [TraitDispatchEntry];

/// Match-arg choices entries for R wrapper post-processing. **Host-only.**
///
/// Each `#[miniextendr]` function with `match_arg` params emits an entry.
/// During `write_r_wrappers_to_file`, the placeholder in the R formal default
/// is replaced with the actual choices from the enum's `MatchArg::CHOICES`.
#[cfg(not(target_arch = "wasm32"))]
#[distributed_slice]
pub static MX_MATCH_ARG_CHOICES: [MatchArgChoicesEntry];

/// Match-arg `@param` doc entries for R wrapper post-processing. **Host-only.**
///
/// Each `#[miniextendr]` function with `match_arg` params that has no
/// user-written `@param` doc emits an entry here. During
/// `write_r_wrappers_to_file`, the placeholder in the `@param` roxygen tag
/// is replaced with e.g. `One of "Fast", "Safe", "Debug".`
#[cfg(not(target_arch = "wasm32"))]
#[distributed_slice]
pub static MX_MATCH_ARG_PARAM_DOCS: [MatchArgParamDocEntry];

/// Class name entries mapping Rust type names to R-visible class names. **Host-only.**
///
/// Each `#[miniextendr]` impl block emits an entry. During
/// `write_r_wrappers_to_file`, `.__MX_CLASS_REF_<RustName>__` placeholders
/// in generated R wrapper strings are replaced with the registered R class name
/// (which may differ when `class = "Override"` is set on the impl block).
#[cfg(not(target_arch = "wasm32"))]
#[distributed_slice]
pub static MX_CLASS_NAMES: [ClassNameEntry];

/// S7 sidecar property documentation entries. **Host-only.**
///
/// Each `#[derive(ExternalPtr)] #[externalptr(s7)]` struct with `#[r_data]` fields
/// emits one entry per public field. During `write_r_wrappers_to_file`, the
/// `.__MX_S7_SIDECAR_PROP_DOCS_<TypeName>__` placeholder in the S7 class wrapper
/// is replaced with the formatted `#' @prop {field} {doc}` roxygen lines.
#[cfg(not(target_arch = "wasm32"))]
#[distributed_slice]
pub static MX_S7_SIDECAR_PROPS: [SidecarPropEntry];

// endregion

// region: Runtime slice access (cfg-uniform)

/// Native: read directly from the linkme distributed slice.
/// wasm32: read from a `OnceLock` populated by `install_wasm_runtime_slices`.
#[inline]
pub(crate) fn call_defs() -> &'static [R_CallMethodDef] {
    #[cfg(not(target_arch = "wasm32"))]
    {
        &MX_CALL_DEFS
    }
    #[cfg(target_arch = "wasm32")]
    {
        wasm_runtime::call_defs()
    }
}

#[inline]
pub(crate) fn altrep_regs() -> &'static [AltrepRegistration] {
    #[cfg(not(target_arch = "wasm32"))]
    {
        &MX_ALTREP_REGISTRATIONS
    }
    #[cfg(target_arch = "wasm32")]
    {
        wasm_runtime::altrep_regs()
    }
}

#[inline]
pub(crate) fn trait_dispatch() -> &'static [TraitDispatchEntry] {
    #[cfg(not(target_arch = "wasm32"))]
    {
        &MX_TRAIT_DISPATCH
    }
    #[cfg(target_arch = "wasm32")]
    {
        wasm_runtime::trait_dispatch()
    }
}

#[cfg(target_arch = "wasm32")]
mod wasm_runtime {
    use super::{AltrepRegistration, R_CallMethodDef, TraitDispatchEntry};
    use std::sync::OnceLock;

    static CALL_DEFS: OnceLock<&'static [R_CallMethodDef]> = OnceLock::new();
    static ALTREP_REGS: OnceLock<&'static [AltrepRegistration]> = OnceLock::new();
    static TRAIT_DISPATCH: OnceLock<&'static [TraitDispatchEntry]> = OnceLock::new();

    pub(super) fn install(
        c: &'static [R_CallMethodDef],
        a: &'static [AltrepRegistration],
        t: &'static [TraitDispatchEntry],
    ) {
        // Double-install is a programmer error but not memory-unsafe — silently
        // ignore so a second `R_init_*` (e.g. dyn.unload + dyn.load) doesn't
        // panic. The first install wins.
        let _ = CALL_DEFS.set(c);
        let _ = ALTREP_REGS.set(a);
        let _ = TRAIT_DISPATCH.set(t);
    }

    pub(super) fn call_defs() -> &'static [R_CallMethodDef] {
        CALL_DEFS.get().copied().unwrap_or(&[])
    }
    pub(super) fn altrep_regs() -> &'static [AltrepRegistration] {
        ALTREP_REGS.get().copied().unwrap_or(&[])
    }
    pub(super) fn trait_dispatch() -> &'static [TraitDispatchEntry] {
        TRAIT_DISPATCH.get().copied().unwrap_or(&[])
    }
}

/// Install the runtime-critical slice data on `wasm32-*`.
///
/// Called from the user crate's `R_init_<pkg>` (generated by
/// `miniextendr_init!`) before `package_init` runs. The slices are typically
/// the `MX_*_WASM` constants emitted into `<crate>/src/rust/<crate>/src/wasm_registry.rs`
/// by [`crate::wasm_registry_writer::write_wasm_registry_to_file`].
///
/// Calling more than once is harmless — the first install wins (the assumption
/// being all calls supply the same data; second-install is treated as a
/// re-init from `dyn.unload` + `dyn.load`).
#[cfg(target_arch = "wasm32")]
pub fn install_wasm_runtime_slices(
    call_defs: &'static [R_CallMethodDef],
    altrep_regs: &'static [AltrepRegistration],
    trait_dispatch: &'static [TraitDispatchEntry],
) {
    wasm_runtime::install(call_defs, altrep_regs, trait_dispatch);
}

// endregion

// region: Entry Types

/// Ordering priority for R wrapper code fragments.
///
/// Variant declaration order = output order. The order matters because
/// R evaluates the wrapper file top-to-bottom, so dependencies must come first:
/// sidecar accessors before class definitions, classes before functions, etc.
#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum RWrapperPriority {
    /// `#[r_data]` getters/setters — must come before class definitions.
    Sidecar,
    /// Class definitions (impl blocks: env/R6/S3/S4/S7).
    Class,
    /// Standalone `#[miniextendr]` functions.
    Function,
    /// Trait impl wrappers (`impl Trait for Type`).
    TraitImpl,
    /// Vctrs S3 method wrappers (`#[derive(Vctrs)]`).
    Vctrs,
}

/// R wrapper code with priority for ordering.
pub struct RWrapperEntry {
    /// Ordering priority (lower = earlier in output file).
    pub priority: RWrapperPriority,
    /// R source code fragment.
    pub content: &'static str,
    /// Source file path (from `file!()`). Used to derive a default `@rdname`
    /// for standalone functions that don't have an explicit one, so that all
    /// functions from the same source file share a single .Rd page.
    pub source_file: &'static str,
}

// SAFETY: All fields are immutable and valid for 'static lifetime.
unsafe impl Sync for RWrapperEntry {}

/// Entry for replacing match_arg placeholder defaults with actual choices.
pub struct MatchArgChoicesEntry {
    /// Placeholder string in the R formal default, e.g. `".__MX_MATCH_ARG_CHOICES_mode__"`.
    pub placeholder: &'static str,
    /// Function that returns the choices as a comma-separated quoted string,
    /// e.g. `"\"Fast\", \"Safe\", \"Debug\""`.
    pub choices_str: fn() -> String,
    /// User-supplied `default = "..."` value (unquoted, e.g. `"zstd"`), or `""`
    /// if the user did not supply one. When non-empty, the write-time pass
    /// rotates the choice list so this value appears first, so R's
    /// `match.arg(arg)` (no second arg) picks it as the default.
    pub preferred_default: &'static str,
}

// SAFETY: function pointer and &'static str are Send+Sync.
unsafe impl Sync for MatchArgChoicesEntry {}

/// Entry for replacing match_arg `@param` doc placeholders with human-readable
/// choice descriptions.
pub struct MatchArgParamDocEntry {
    /// Placeholder string in the `@param` roxygen tag, e.g.
    /// `".__MX_MATCH_ARG_PARAM_DOC_match_arg_set_mode_mode__"`.
    pub placeholder: &'static str,
    /// `true` for `several_ok` params (emits "One or more of …");
    /// `false` for plain `match_arg` (emits "One of …").
    pub several_ok: bool,
    /// Function that returns the choices as a comma-separated quoted string,
    /// e.g. `"\"Fast\", \"Safe\", \"Debug\""`.
    pub choices_str: fn() -> String,
}

// SAFETY: function pointer, bool, and &'static str are Send+Sync.
unsafe impl Sync for MatchArgParamDocEntry {}

/// Entry mapping a Rust type name to its R-visible class name and class system.
///
/// Emitted by every `#[miniextendr(env|r6|s3|s4|s7|vctrs)]` impl block.
/// Used by the resolver in `write_r_wrappers_to_file` to replace
/// `.__MX_CLASS_REF_<RustName>__` placeholders with the actual R class name.
pub struct ClassNameEntry {
    /// Rust type identifier, e.g. `"S7Shape"`.
    pub rust_type: &'static str,
    /// R-visible class name. Equals `rust_type` unless `class = "Override"` was
    /// set on the impl block, in which case it is the override string.
    pub r_class_name: &'static str,
    /// Class system tag: `"env"` | `"r6"` | `"s3"` | `"s4"` | `"s7"` | `"vctrs"`.
    pub class_system: &'static str,
}

// SAFETY: All fields are &'static str — immutable and valid for program lifetime.
unsafe impl Sync for ClassNameEntry {}

/// Build the `rust_type → ClassNameEntry` lookup used by every placeholder
/// resolver in `write_r_wrappers_to_file`.
///
/// Multiple labeled `#[miniextendr]` impl blocks on one type each register a
/// `ClassNameEntry` (#1242) — the class name is a property of the *type*, so
/// identical duplicates collapse here. *Conflicting* registrations (same
/// `rust_type`, different `r_class_name` or `class_system` — e.g. two labeled
/// blocks with disagreeing `class = "..."` overrides) panic: silently keeping
/// whichever entry linkme ordered last would resolve `.__MX_CLASS_REF_*__`
/// placeholders nondeterministically.
///
/// Host-only like `MX_CLASS_NAMES` itself — the consumers all live in the
/// wrapper-writing path, which never runs on wasm32.
#[cfg(not(target_arch = "wasm32"))]
fn build_class_name_index<'a>(
    entries: impl IntoIterator<Item = &'a ClassNameEntry>,
) -> std::collections::HashMap<&'a str, &'a ClassNameEntry> {
    use std::collections::hash_map::Entry;
    let mut index = std::collections::HashMap::new();
    for e in entries {
        match index.entry(e.rust_type) {
            Entry::Vacant(slot) => {
                slot.insert(e);
            }
            Entry::Occupied(slot) => {
                let prev = *slot.get();
                if prev.r_class_name != e.r_class_name || prev.class_system != e.class_system {
                    panic!(
                        "conflicting class registrations for Rust type `{}`: \
                         `{}` ({}) vs `{}` ({}). Multiple #[miniextendr] impl blocks \
                         on one type must agree on the class system and any \
                         `class = \"...\"` override.",
                        e.rust_type,
                        prev.r_class_name,
                        prev.class_system,
                        e.r_class_name,
                        e.class_system,
                    );
                }
            }
        }
    }
    index
}

/// Entry documenting a sidecar (`#[r_data]`) property on an S7 ExternalPtr type.
///
/// Emitted by `#[derive(ExternalPtr)] #[externalptr(s7)]` for each public `#[r_data]`
/// field. Used by `write_r_wrappers_to_file` to substitute the
/// `.__MX_S7_SIDECAR_PROP_DOCS_<TypeName>__` placeholder with `#' @prop` lines.
pub struct SidecarPropEntry {
    /// Rust type name, e.g. `"SidecarS7"`.
    pub rust_type: &'static str,
    /// Field name, e.g. `"prop_int"`.
    pub field_name: &'static str,
    /// Documentation string for this property.
    /// Defaults to `"(undocumented sidecar property)"` when no `prop_doc` was supplied.
    pub prop_doc: &'static str,
}

// SAFETY: All fields are &'static str — immutable and valid for program lifetime.
unsafe impl Sync for SidecarPropEntry {}

/// Trait dispatch entry mapping (concrete_tag, trait_tag) → vtable.
#[repr(C)]
pub struct TraitDispatchEntry {
    /// Tag identifying the concrete type.
    pub concrete_tag: mx_tag,
    /// Tag identifying the trait interface.
    pub trait_tag: mx_tag,
    /// Pointer to the trait's vtable (cast from `&'static SomeVTable`).
    pub vtable: *const c_void,
    /// Symbol name of the `#[no_mangle]` vtable static
    /// (e.g. `"__VTABLE_COUNTER_FOR_MYTYPE"`). Consumed by the host-time WASM
    /// snapshot writer to emit `extern "C" { static <symbol>: u8; }`
    /// declarations in `wasm_registry.rs`.
    pub vtable_symbol: &'static str,
}

// SAFETY: vtable points to a static vtable valid for program lifetime.
// Tags are Copy values. All fields are safe to read from any thread.
unsafe impl Sync for TraitDispatchEntry {}
unsafe impl Send for TraitDispatchEntry {}

/// ALTREP class registration entry: fn pointer + `#[no_mangle]` symbol name.
///
/// See [`MX_ALTREP_REGISTRATIONS`] for context.
#[repr(C)]
pub struct AltrepRegistration {
    /// Registration function called once at `R_init_*`.
    pub register: extern "C" fn(),
    /// Symbol name of `register` (e.g. `"__mx_altrep_reg_MyType"`). Consumed by
    /// the host-time WASM snapshot writer to emit `extern "C" { fn <symbol>(); }`
    /// declarations in `wasm_registry.rs`.
    pub symbol: &'static str,
}

// SAFETY: register is a static fn pointer; symbol is a `'static` string.
unsafe impl Sync for AltrepRegistration {}
unsafe impl Send for AltrepRegistration {}
// endregion

// region: Universal Query

/// Universal query function for trait dispatch.
///
/// Scans [`MX_TRAIT_DISPATCH`] for a matching `(concrete_tag, trait_tag)` pair.
/// Returns the vtable pointer, or null if the trait is not implemented.
///
/// This replaces per-type query functions — a single function handles all types
/// by reading from the global dispatch table.
///
/// # Safety
///
/// - `ptr` must point to a valid `mx_erased` with a valid base vtable.
/// - Must be called on R's main thread.
pub unsafe extern "C" fn universal_query(ptr: *mut mx_erased, trait_tag: mx_tag) -> *const c_void {
    let concrete_tag = unsafe { (*(*ptr).base).concrete_tag };
    for entry in trait_dispatch().iter() {
        if entry.concrete_tag == concrete_tag && entry.trait_tag == trait_tag {
            return entry.vtable;
        }
    }
    std::ptr::null()
}
// endregion

// region: Initialization

/// Register all `#[miniextendr]` routines and ALTREP classes with R.
///
/// Called from `package_init()` during `R_init_*` (via `miniextendr_init!`).
/// Everything else is automatic.
///
/// # Safety
///
/// Must be called from R's main thread during `R_init_*`.
/// `dll` must be a valid pointer provided by R.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn miniextendr_register_routines(dll: *mut DllInfo) {
    // 1. Register ALTREP classes (skip during wrapper generation)
    //
    // During wrapper-gen, the installed shared object is loaded temporarily via
    // dyn.load() then unloaded via dyn.unload(). ALTREP class registration creates
    // R-global entries with method pointers into the loaded code. After dyn.unload(),
    // those pointers become dangling. When R later loads the installed package and
    // re-registers, it may still have the stale entries, leading to heap corruption
    // (e.g., "malloc(): unsorted double linked list corrupted" on Linux).
    // Shares the single read-site with package_init (see init::WRAPPER_GEN_ENV) so
    // the env-var name cannot drift between the two consumers.
    let wrapper_gen = crate::init::wrapper_gen_mode();
    if !wrapper_gen {
        // All ALTREP classes — both user-defined (#[miniextendr] structs) and
        // builtins (Vec, Box, Range, Cow, Arrow) — register via linkme
        // MX_ALTREP_REGISTRATIONS. Each call site emits a
        // `#[distributed_slice(MX_ALTREP_REGISTRATIONS)]` entry, so a single
        // iteration here covers everything. No hand-enumerated builtin list needed.
        for reg in altrep_regs().iter() {
            (reg.register)();
        }

        // Verify no two ALTREP types registered the same class name.
        // Duplicates cause silent overwrites in R — the wrong type gets
        // reconstructed on readRDS, leading to memory corruption.
        crate::altrep::assert_altrep_class_uniqueness();
    }

    // 2. Build call method defs with null sentinel
    let mut call_defs: Vec<R_CallMethodDef> = self::call_defs().to_vec();
    // Always register the wrapper-gen entry points so they're visible
    // via getNativeSymbolInfo even when R_forceSymbols(TRUE) is set. wasm32
    // doesn't run wrapper-gen (it's host-only), so these are gated off there.
    // SAFETY: DL_FUNC is Option<extern "C-unwind" fn() -> *mut c_void> — R's
    // standard erased function pointer. The actual signature (SEXP -> SEXP) is
    // ABI-compatible; R dispatches based on numArgs.
    #[cfg(not(target_arch = "wasm32"))]
    {
        call_defs.push(R_CallMethodDef {
            name: c"miniextendr_write_wrappers".as_ptr(),
            fun: unsafe {
                std::mem::transmute::<
                    *const (),
                    Option<unsafe extern "C-unwind" fn() -> *mut c_void>,
                >(miniextendr_write_wrappers as *const ())
            },
            numArgs: 1,
        });
        call_defs.push(R_CallMethodDef {
            name: c"miniextendr_write_wasm_registry".as_ptr(),
            fun: unsafe {
                std::mem::transmute::<
                    *const (),
                    Option<unsafe extern "C-unwind" fn() -> *mut c_void>,
                >(miniextendr_write_wasm_registry as *const ())
            },
            numArgs: 1,
        });
    }
    call_defs.push(R_CallMethodDef {
        name: std::ptr::null(),
        fun: None,
        numArgs: 0,
    });

    // 3. Register routines
    // Leak the Vec — init runs once at package load, so this is fine.
    unsafe {
        crate::sys::R_registerRoutines_unchecked(
            dll,
            std::ptr::null(),
            call_defs.leak().as_ptr(),
            std::ptr::null(),
            std::ptr::null(),
        );
    }
}

/// Collect all R wrapper entries, sorted by priority and deduplicated.
///
/// Within each priority group, S7 class definitions are topologically sorted
/// so parents are defined before children (S7 `parent = X` requires X to exist).
///
/// Host-only — wasm32 doesn't run wrapper-gen.
#[cfg(not(target_arch = "wasm32"))]
pub fn collect_r_wrappers() -> Vec<std::borrow::Cow<'static, str>> {
    let mut entries: Vec<&RWrapperEntry> = MX_R_WRAPPERS.iter().collect();
    entries.sort_by_key(|e| e.priority);

    let mut seen = std::collections::HashSet::<&str>::new();
    let mut result: Vec<std::borrow::Cow<'static, str>> = Vec::with_capacity(entries.len());
    for entry in entries {
        let trimmed = entry.content.trim();
        if !trimmed.is_empty() && seen.insert(trimmed) {
            // For standalone functions without explicit @rdname, inject one
            // derived from the source file stem so same-file functions share
            // a single .Rd page.
            if entry.priority == RWrapperPriority::Function
                && !has_rdname_tag(trimmed)
                && !has_no_rd_tag(trimmed)
            {
                if let Some(rdname) = rdname_from_source_file(entry.source_file) {
                    result.push(std::borrow::Cow::Owned(inject_rdname(trimmed, &rdname)));
                    continue;
                }
            }
            result.push(std::borrow::Cow::Borrowed(trimmed));
        }
    }

    // Topological sort for S7 inheritance ordering
    sort_s7_classes(&mut result);

    result
}

#[cfg(not(target_arch = "wasm32"))]
/// Check if an R wrapper fragment already has an `@rdname` tag.
fn has_rdname_tag(content: &str) -> bool {
    content.lines().any(|line| {
        let trimmed = line.trim();
        trimmed.starts_with("#' @rdname ")
    })
}

#[cfg(not(target_arch = "wasm32"))]
/// Check if an R wrapper fragment has `@noRd`.
fn has_no_rd_tag(content: &str) -> bool {
    content.lines().any(|line| {
        let trimmed = line.trim();
        trimmed == "#' @noRd"
    })
}

#[cfg(not(target_arch = "wasm32"))]
/// Derive an `@rdname` value from a source file path.
///
/// `"src/rust/zero_copy_tests.rs"` → `"zero_copy_tests"`
/// `"lib.rs"` → `"lib"`
fn rdname_from_source_file(path: &str) -> Option<String> {
    let file_name = path.rsplit(['/', '\\']).next()?;
    let stem = file_name.strip_suffix(".rs").unwrap_or(file_name);
    if stem.is_empty() || stem == "lib" || stem == "mod" {
        return None;
    }
    Some(stem.to_string())
}

#[cfg(not(target_arch = "wasm32"))]
/// Inject `#' @rdname <value>` (and `@title` if missing) into an R wrapper
/// fragment. Inserts before the first `@export`/`@keywords`/`@source` line,
/// or after the last roxygen line.
fn inject_rdname(content: &str, rdname: &str) -> String {
    let rdname_line = format!("#' @rdname {rdname}");
    let has_title = content.lines().any(|l| l.trim().starts_with("#' @title "));
    // Functions with no doc comments need a title so the @rdname page has an anchor
    let title_line = if has_title {
        None
    } else {
        Some(format!("#' @title {}", rdname.replace('_', " ")))
    };

    let lines: Vec<&str> = content.lines().collect();
    let mut result = Vec::with_capacity(lines.len() + 2);
    let mut inserted = false;

    for line in &lines {
        let trimmed = line.trim();
        // Insert before @export, @keywords, or @source lines
        if !inserted
            && (trimmed.starts_with("#' @export")
                || trimmed.starts_with("#' @keywords")
                || trimmed.starts_with("#' @source"))
        {
            if let Some(ref t) = title_line {
                result.push(t.as_str());
            }
            result.push(rdname_line.as_str());
            inserted = true;
        }
        result.push(line);
    }

    // If we never found a good insertion point, insert before the function def
    if !inserted {
        let last_roxy = lines
            .iter()
            .rposition(|l| l.trim().starts_with("#'"))
            .unwrap_or(0);
        let insert_at = last_roxy + 1;
        if let Some(ref t) = title_line {
            result.insert(insert_at, t.as_str());
            result.insert(insert_at + 1, rdname_line.as_str());
        } else {
            result.insert(insert_at, rdname_line.as_str());
        }
    }

    result.join("\n")
}

#[cfg(not(target_arch = "wasm32"))]
/// Sort S7 class definitions so parents come before children.
///
/// Detects `S7::new_class()` calls, extracts `parent = ClassName` relationships,
/// and performs topological sort. Non-S7 entries keep their relative order.
fn sort_s7_classes(entries: &mut [std::borrow::Cow<'static, str>]) {
    use std::collections::HashMap;

    // Parse S7 class definitions: find (index, name, parent)
    let mut s7_info: Vec<(usize, String, Option<String>)> = Vec::new();

    for (i, entry) in entries.iter().enumerate() {
        if let Some(nc_pos) = entry.find("S7::new_class(") {
            // Extract class name: "NAME <- S7::new_class("
            let before = entry[..nc_pos].trim_end();
            let name = before
                .strip_suffix("<-")
                .or_else(|| before.rsplit_once("<-").map(|(_, r)| r))
                .map(|s| s.trim())
                .and_then(|s| s.split_whitespace().last());

            let Some(name) = name else { continue };

            // Extract parent: "parent = ParentName,"
            let after = &entry[nc_pos..];
            let parent = after.find("parent = ").and_then(|p| {
                let rest = &after[p + "parent = ".len()..];
                let end = rest.find([',', ')', '\n']).unwrap_or(rest.len());
                let p = rest[..end].trim();
                if p.is_empty() {
                    None
                } else {
                    Some(p.to_string())
                }
            });

            s7_info.push((i, name.to_string(), parent));
        }
    }

    if s7_info.len() <= 1 {
        return;
    }

    // Build name → position-in-s7_info map.
    // Also map placeholder .__MX_CLASS_REF_<Name>__ to the same position, since
    // the placeholder carries the Rust type name which equals the R class name
    // (before any `class = "Override"` resolution — good enough for ordering).
    let mut name_to_pos: HashMap<String, usize> = HashMap::new();
    for (pos, (_, name, _)) in s7_info.iter().enumerate() {
        name_to_pos.insert(name.clone(), pos);
        // Also register the placeholder form so a child class that references
        // `parent = .__MX_CLASS_REF_ParentName__` can still be sorted correctly.
        name_to_pos.insert(format!(".__MX_CLASS_REF_{name}__"), pos);
    }

    // Topological sort: repeatedly emit classes whose parent is already placed
    let n = s7_info.len();
    let mut order: Vec<usize> = Vec::with_capacity(n);
    let mut placed = vec![false; n];

    for _ in 0..n {
        for (pos, (_, _, parent)) in s7_info.iter().enumerate() {
            if placed[pos] {
                continue;
            }
            let ready = match parent {
                None => true,
                Some(pname) => match name_to_pos.get(pname.as_str()) {
                    None => true, // external parent
                    Some(&pp) => placed[pp],
                },
            };
            if ready {
                order.push(pos);
                placed[pos] = true;
            }
        }
    }

    // Fallback: add any remaining (cycles) in original order
    for (pos, &is_placed) in placed.iter().enumerate().take(n) {
        if !is_placed {
            order.push(pos);
        }
    }

    // Apply: place sorted S7 entries back at their original indices
    let s7_indices: Vec<usize> = s7_info.iter().map(|(i, _, _)| *i).collect();
    let original: Vec<std::borrow::Cow<'static, str>> =
        s7_indices.iter().map(|&i| entries[i].clone()).collect();

    for (slot, &src) in order.iter().enumerate() {
        entries[s7_indices[slot]] = original[src].clone();
    }
}
// endregion

#[cfg(not(target_arch = "wasm32"))]
/// Rotate a comma-separated quoted-choice string so `preferred` is first.
///
/// `choices_str` has the shape `"\"a\", \"b\", \"c\""` (already quoted +
/// joined). `preferred` is the unquoted user-supplied default (e.g. `"b"`).
/// On miss, panics with the placeholder name — the wrapper-gen write step is the
/// only caller, so a panic surfaces as a load-time error in the host R session
/// rather than silently producing a broken wrapper.
fn rotate_choices_for_default(choices_str: &str, preferred: &str, placeholder: &str) -> String {
    let parts: Vec<&str> = choices_str.split(", ").collect();
    let pos = parts
        .iter()
        .position(|p| p.strip_prefix('"').and_then(|s| s.strip_suffix('"')) == Some(preferred))
        .unwrap_or_else(|| {
            panic!(
                "miniextendr: preferred default `{preferred}` for placeholder `{placeholder}` \
                 does not match any choice in [{choices_str}]"
            )
        });
    let mut rotated: Vec<&str> = Vec::with_capacity(parts.len());
    rotated.push(parts[pos]);
    for (i, p) in parts.iter().enumerate() {
        if i != pos {
            rotated.push(p);
        }
    }
    rotated.join(", ")
}

// region: R Wrapper File Generation

// region: Generic doc marker resolution

/// Parse the payload of a `.__MX_GENERIC_DOC__(...)` marker line.
///
/// Returns `(kind, generic_name, class_name, export, dispatch, no_dots)` on success.
/// The marker format (emitted by proc-macros) is:
/// ```text
/// .__MX_GENERIC_DOC__(kind="S7", generic="get_value", class="MyClass",
///                     export=true, dispatch="x", no_dots=false)
/// ```
/// S4 markers omit `dispatch` and `no_dots` (always `"x"` / `false`).
#[cfg(not(target_arch = "wasm32"))]
fn parse_generic_doc_marker(marker: &str) -> Option<(String, String, String, bool, String, bool)> {
    // Strip prefix and trailing ')'
    let inner = marker
        .strip_prefix(".__MX_GENERIC_DOC__(")?
        .strip_suffix(')')?;

    let mut kind = String::new();
    let mut generic = String::new();
    let mut class = String::new();
    let mut export = false;
    let mut dispatch = "x".to_string();
    let mut no_dots = false;

    for part in inner.split(", ") {
        let part = part.trim();
        if let Some(val) = part.strip_prefix("kind=") {
            kind = val.trim_matches('"').to_string();
        } else if let Some(val) = part.strip_prefix("generic=") {
            generic = val.trim_matches('"').to_string();
        } else if let Some(val) = part.strip_prefix("class=") {
            class = val.trim_matches('"').to_string();
        } else if let Some(val) = part.strip_prefix("export=") {
            export = val == "true";
        } else if let Some(val) = part.strip_prefix("dispatch=") {
            dispatch = val.trim_matches('"').to_string();
        } else if let Some(val) = part.strip_prefix("no_dots=") {
            no_dots = val == "true";
        }
    }

    if kind.is_empty() || generic.is_empty() || class.is_empty() {
        return None;
    }

    Some((kind, generic, class, export, dispatch, no_dots))
}

/// Synthesise a standalone roxygen doc block for a generic.
///
/// Produces a block with:
/// - `@title` / `@description` describing the generic
/// - `@param` lines for each dispatch argument (plus `...` unless no_dots)
/// - `@name <generic>` — yields the bare `\alias{<generic>}` that `?generic` resolves
/// - `@export` or `@rawNamespace export(<generic>)` as appropriate
/// - `NULL` anchor
///
/// The method blocks emitted by the class generators keep their qualified
/// `@name Class-generic` so there is no duplicate-alias regression.
#[cfg(not(target_arch = "wasm32"))]
fn synthesise_generic_doc_block(
    kind: &str,
    generic: &str,
    classes: &[String],
    export: bool,
    dispatch: &str,
    no_dots: bool,
) -> String {
    let mut lines: Vec<String> = Vec::new();

    // Title
    lines.push(format!("#' The `{generic}()` generic"));
    lines.push("#'".to_string());

    // Description
    let kind_phrase = if kind == "S4" {
        "an S4 generic"
    } else {
        "an S7 generic"
    };
    lines.push("#' @description".to_string());
    lines.push(format!(
        "#' `{generic}()` is {kind_phrase} generated by miniextendr. Methods in this"
    ));
    lines.push("#' package are available for:".to_string());
    lines.push("#' \\itemize{".to_string());
    for cls in classes {
        lines.push(format!("#'   \\item \\code{{\\link{{{cls}}}}}"));
    }
    lines.push("#' }".to_string());

    // @param lines for dispatch formals
    let dispatch_args: Vec<&str> = dispatch.split(',').map(|s| s.trim()).collect();
    for arg in &dispatch_args {
        lines.push(format!("#' @param {arg} An object."));
    }
    if !no_dots {
        lines.push("#' @param ... Passed on to methods.".to_string());
    }

    // Bare @name — this is what produces the bare \\alias{<generic>} in Rd
    lines.push(format!("#' @name {generic}"));

    // Export directive
    if export {
        if kind == "S4" {
            // S4 generics use @exportMethod (matches the method blocks)
            lines.push(format!("#' @exportMethod {generic}"));
        } else {
            // S7 generics use @rawNamespace export(...) (matches the method blocks)
            lines.push(format!("#' @rawNamespace export({generic})"));
        }
    }

    lines.push("NULL".to_string());

    lines.join("\n")
}

/// Scan `content` for `.__MX_GENERIC_DOC__(...)` marker lines, group by
/// generic name, replace the first marker per generic with a synthesised
/// standalone doc block, and delete all remaining markers.
///
/// This is the write-time counterpart to the proc-macro marker emission in
/// `s7_class.rs` and `s4_class.rs`.
#[cfg(not(target_arch = "wasm32"))]
fn resolve_generic_doc_markers(content: String) -> String {
    use std::collections::HashMap;

    const MARKER_PREFIX: &str = ".__MX_GENERIC_DOC__(";

    // First pass: collect all (generic, kind, classes[], export, dispatch, no_dots) grouped
    // by generic name.  Preserve insertion order (first class encountered wins for kind/export).
    let mut by_generic: HashMap<String, (String, Vec<String>, bool, String, bool)> = HashMap::new();
    let mut generic_order: Vec<String> = Vec::new(); // tracks first-seen order

    for line in content.lines() {
        let trimmed = line.trim();
        if !trimmed.starts_with(MARKER_PREFIX) {
            continue;
        }
        if let Some((kind, generic, class, export, dispatch, no_dots)) =
            parse_generic_doc_marker(trimmed)
        {
            let entry = by_generic.entry(generic.clone()).or_insert_with(|| {
                generic_order.push(generic.clone());
                (kind, Vec::new(), export, dispatch, no_dots)
            });
            entry.1.push(class);
        }
    }

    if by_generic.is_empty() {
        return content;
    }

    // Second pass: walk the content line by line.  For each generic, the first
    // marker line is replaced by the synthesised doc block; subsequent markers
    // for the same generic are dropped entirely.
    let mut first_seen: std::collections::HashSet<String> = std::collections::HashSet::new();
    let mut result = String::with_capacity(content.len() + 512 * by_generic.len());

    for line in content.lines() {
        let trimmed = line.trim();
        if trimmed.starts_with(MARKER_PREFIX) {
            if let Some((_kind, generic, _class, _export, _dispatch, _no_dots)) =
                parse_generic_doc_marker(trimmed)
            {
                if first_seen.insert(generic.clone()) {
                    // First occurrence: replace with synthesised block
                    if let Some((kind, classes, export, dispatch, no_dots)) =
                        by_generic.get(&generic)
                    {
                        let block = synthesise_generic_doc_block(
                            kind, &generic, classes, *export, dispatch, *no_dots,
                        );
                        result.push_str(&block);
                        result.push('\n');
                    }
                }
                // Subsequent occurrences: drop the line entirely (no push)
                continue;
            }
        }
        result.push_str(line);
        result.push('\n');
    }

    // Trim trailing newlines added by the line-by-line loop and restore the
    // original termination (content typically ends with \n).
    result
}

// endregion

// region: Inherited param marker resolution

/// Parse a `.__MX_INHERITED_PARAM__(...)` marker line.
///
/// The marker format is:
/// ```text
/// .__MX_INHERITED_PARAM__(class="R6Dog", parent="R6Animal", method="speak", param="times")
/// ```
/// Returns `(class, parent, method, param)` on success.
#[cfg(not(target_arch = "wasm32"))]
fn parse_inherited_param_marker(marker: &str) -> Option<(String, String, String, String)> {
    let inner = marker
        .strip_prefix(".__MX_INHERITED_PARAM__(")?
        .strip_suffix(')')?;

    let mut class = String::new();
    let mut parent = String::new();
    let mut method = String::new();
    let mut param = String::new();

    for part in inner.split(", ") {
        let part = part.trim();
        if let Some(val) = part.strip_prefix("class=") {
            class = val.trim_matches('"').to_string();
        } else if let Some(val) = part.strip_prefix("parent=") {
            parent = val.trim_matches('"').to_string();
        } else if let Some(val) = part.strip_prefix("method=") {
            method = val.trim_matches('"').to_string();
        } else if let Some(val) = part.strip_prefix("param=") {
            param = val.trim_matches('"').to_string();
        }
    }

    if class.is_empty() || parent.is_empty() || method.is_empty() || param.is_empty() {
        return None;
    }

    Some((class, parent, method, param))
}

/// Resolve `.__MX_INHERITED_PARAM__(...)` markers.
///
/// For each marker, checks whether the parent class is in-package and has
/// `@param <param>` documented for either:
/// - The same method name (in any of its method doc blocks), or
/// - The class-level `@param` (emitted in the class header).
///
/// If the parent is documented → delete the marker line (roxygen2 8.0.0 inherits
/// the parent method's `@param` into the subclass method).
///
/// If the parent is cross-package or the param is not documented there → replace
/// with `#' @param {param} (no documentation available)` to preserve the zero-warning
/// guarantee on rendered Rd.
///
/// Cross-package parents: markers are always replaced with the fallback text because
/// we cannot inspect foreign packages' wrapper content at write time.
#[cfg(not(target_arch = "wasm32"))]
fn resolve_inherited_param_markers(content: String) -> String {
    use std::collections::{HashMap, HashSet};

    const MARKER_PREFIX: &str = ".__MX_INHERITED_PARAM__(";

    // Check if the marker is present at all (fast path).
    if !content.contains(MARKER_PREFIX) {
        return content;
    }

    // Build an index of in-package class param documentation:
    //   class_name → Set<param_name>
    // We scan the content for:
    //   1. Class-level @param tags: lines like `#' @param <name> ...` appearing
    //      between `#' @name <ClassName>` and the R6Class(...) definition.
    //   2. Method-level @param tags for a specific method: lines like
    //      `    #' @param <name> ...` inside the method's doc block.
    //
    // Strategy: build a map of (class_name, method_name_or_class) → Set<param_name>
    // where method_name_or_class = "" means class-level.
    let mut class_method_params: HashMap<(String, String), HashSet<String>> = HashMap::new();

    // We need to scan the wrapper content to find documented params.
    // Simple heuristic: find `#' @name ClassName` then collect `#' @param` lines
    // until the next non-doc line (the R6Class definition).
    let lines: Vec<&str> = content.lines().collect();
    let mut i = 0;
    while i < lines.len() {
        let line = lines[i].trim();
        // Class-level: `#' @name ClassName` followed by class-level @param lines
        if let Some(rest) = line.strip_prefix("#' @name ") {
            let class_name = rest.trim().to_string();
            // Scan forward for @param lines in the class header (until non-doc)
            let mut j = i + 1;
            while j < lines.len() {
                let next = lines[j].trim();
                if next.starts_with("#'") {
                    if let Some(param_rest) = next.strip_prefix("#' @param ") {
                        if let Some(param_name) = param_rest.split_whitespace().next() {
                            class_method_params
                                .entry((class_name.clone(), String::new()))
                                .or_default()
                                .insert(param_name.to_string());
                        }
                    }
                    j += 1;
                } else {
                    break;
                }
            }
        }
        // Method-level: `    #' @description Method \`method_name\`.` or source comment
        // Simpler: look for `    #' @param` lines at method indent — attribute to the
        // nearest preceding `#' @rdname ClassName` (method blocks carry this).
        // Actually, method-level @param inside an R6 class block are indented with 4 spaces.
        // We track the current class context from the most recent R6Class definition.
        i += 1;
    }

    // Walk the content to track current R6 class + method context, and also
    // build method-level param maps. We do a second pass specifically for method params.
    let mut current_class: Option<String> = None;
    let mut current_method: Option<String> = None;
    i = 0;
    while i < lines.len() {
        let raw = lines[i];
        let trimmed = raw.trim();
        // Detect R6Class definition: `ClassName <- R6::R6Class("ClassName",`
        if trimmed.contains("R6::R6Class(\"") {
            if let Some(start) = trimmed.find("R6::R6Class(\"") {
                let rest = &trimmed[start + "R6::R6Class(\"".len()..];
                if let Some(end) = rest.find('"') {
                    current_class = Some(rest[..end].to_string());
                    current_method = None;
                }
            }
        }
        // Detect method source comment: `    # ClassName::method_name (file:line)`
        if let Some(ref cls) = current_class.clone() {
            let prefix = format!("# {}::", cls);
            if trimmed.starts_with(&prefix) {
                let rest = &trimmed[prefix.len()..];
                let method_name = rest.split_whitespace().next().unwrap_or("").to_string();
                if !method_name.is_empty() {
                    current_method = Some(method_name);
                }
            }
            // Detect indented method @param: `    #' @param name ...`
            if let Some(ref method) = current_method.clone() {
                if let Some(rest) = raw.strip_prefix("    #' @param ") {
                    if let Some(param_name) = rest.split_whitespace().next() {
                        class_method_params
                            .entry((cls.clone(), method.clone()))
                            .or_default()
                            .insert(param_name.to_string());
                    }
                }
            }
        }
        i += 1;
    }

    // Second pass: resolve markers.
    let mut result = String::with_capacity(content.len());
    for line in content.lines() {
        let trimmed = line.trim();
        // Marker format: `    #' .__MX_INHERITED_PARAM__(class="...", parent="...", method="...", param="...")`
        let inner = trimmed.strip_prefix("#' ").unwrap_or(trimmed);
        if inner.starts_with(MARKER_PREFIX) {
            if let Some((_class, parent, method, param)) = parse_inherited_param_marker(inner) {
                // Check if parent is in-package and has the param documented:
                // Either at method level (parent, method) or class level (parent, "").
                let parent_method_key = (parent.clone(), method.clone());
                let parent_class_key = (parent.clone(), String::new());
                let documented_in_method = class_method_params
                    .get(&parent_method_key)
                    .map(|s| s.contains(&param))
                    .unwrap_or(false);
                let documented_at_class = class_method_params
                    .get(&parent_class_key)
                    .map(|s| s.contains(&param))
                    .unwrap_or(false);

                if documented_in_method || documented_at_class {
                    // Parent is documented in-package → drop this line entirely.
                    // roxygen2 8.0.0 inherits the parent method's @param.
                    continue;
                } else {
                    // Parent not found or param not documented → keep fallback.
                    // Reconstruct indentation from the original line.
                    let indent: String = line.chars().take_while(|c| c.is_whitespace()).collect();
                    result.push_str(&indent);
                    result.push_str(&format!("#' @param {} (no documentation available)", param));
                    result.push('\n');
                    continue;
                }
            }
        }
        result.push_str(line);
        result.push('\n');
    }

    result
}

// endregion

// region: cross-class return wrapper resolvers

/// Scan `content` for `<prefix><RustName>__(<expr>)` markers and replace each
/// with whatever `emit` pushes for the resolved class entry (or `None` when
/// `RustName` is not registered).
///
/// Shared scan loop behind [`resolve_scalar_return_wrappers`] and
/// [`resolve_list_return_wrappers`]. The two marker families use
/// non-overlapping prefixes (`.__MX_WRAP_RETURN_` vs `.__MX_WRAP_LIST_RETURN_`)
/// so each resolver only ever consumes its own markers — the scalar resolver
/// rewrites *unrecognized* names of its own prefix to the bare expression, so
/// a shared prefix would destroy list markers before the list pass ran (#1284).
///
/// Malformed markers (missing `__(` or the closing `)`) are emitted as-is and
/// scanning stops, matching the other placeholder resolvers in this file.
#[cfg(not(target_arch = "wasm32"))]
fn resolve_wrap_return_markers(
    content: &str,
    prefix: &str,
    class_index: &std::collections::HashMap<&str, &ClassNameEntry>,
    emit: impl Fn(&mut String, Option<&ClassNameEntry>, &str),
) -> String {
    const ARG_OPEN: &str = "__(";
    const ARG_CLOSE: char = ')';

    let mut result = String::with_capacity(content.len());
    let mut remaining = content;
    while let Some(start) = remaining.find(prefix) {
        result.push_str(&remaining[..start]);
        let rest_from_prefix = &remaining[start..];
        let marker_body = &rest_from_prefix[prefix.len()..];
        let Some(name_end) = marker_body.find(ARG_OPEN) else {
            // Malformed placeholder (no opening `__(`) — emit as-is and stop scanning.
            result.push_str(prefix);
            remaining = marker_body;
            break;
        };
        let rust_name = &marker_body[..name_end];
        let after_open = &marker_body[name_end + ARG_OPEN.len()..];
        let Some(expr_end) = after_open.find(ARG_CLOSE) else {
            // Malformed placeholder (no closing `)`) — emit as-is and stop scanning.
            result.push_str(prefix);
            remaining = marker_body;
            break;
        };
        let expr = &after_open[..expr_end];
        remaining = &after_open[expr_end + ARG_CLOSE.len_utf8()..];
        emit(&mut result, class_index.get(rust_name).copied(), expr);
    }
    result.push_str(remaining);
    result
}

/// Resolve scalar `.__MX_WRAP_RETURN_<RustName>__(<expr>)` placeholders
/// emitted by class-method wrappers whose Rust return type may name a
/// different ExternalPtr-backed class.
///
/// Unlike `CLASS_REF`, an unresolved return wrapper is a quiet no-op (the bare
/// `<expr>`): the syntactic macro-time heuristic intentionally allows false
/// positives, and write time is where we know whether `<RustName>` is
/// registered in this package.
#[cfg(not(target_arch = "wasm32"))]
fn resolve_scalar_return_wrappers(
    content: &str,
    class_index: &std::collections::HashMap<&str, &ClassNameEntry>,
) -> String {
    resolve_wrap_return_markers(
        content,
        ".__MX_WRAP_RETURN_",
        class_index,
        |result, entry, expr| match entry {
            Some(entry) => match entry.class_system {
                "r6" => {
                    result.push_str(&format!("{}$new(.ptr = {})", entry.r_class_name, expr));
                }
                "s7" => {
                    result.push_str(&format!("{}(.ptr = {})", entry.r_class_name, expr));
                }
                "s4" => {
                    result.push_str(&format!(
                        "methods::new(\"{}\", ptr = {})",
                        entry.r_class_name, expr
                    ));
                }
                _ => {
                    result.push_str(&format!(
                        "structure({}, class = \"{}\")",
                        expr, entry.r_class_name
                    ));
                }
            },
            None => result.push_str(expr),
        },
    )
}

/// Resolve list-shaped `.__MX_WRAP_LIST_RETURN_<RustName>__(<expr>)`
/// placeholders emitted for `Vec<Class>`-returning class methods (#1284).
///
/// `<expr>` is a bare R list of external pointers (the `IntoRVecElement`
/// conversion emitted by `#[derive(ExternalPtr)]`); each element gets the same
/// per-element wrap the scalar resolver applies, via `lapply`. Unregistered
/// element types fall back to the bare list, mirroring the scalar fallback.
#[cfg(not(target_arch = "wasm32"))]
fn resolve_list_return_wrappers(
    content: &str,
    class_index: &std::collections::HashMap<&str, &ClassNameEntry>,
) -> String {
    resolve_wrap_return_markers(
        content,
        ".__MX_WRAP_LIST_RETURN_",
        class_index,
        |result, entry, expr| match entry {
            Some(entry) => match entry.class_system {
                "r6" => {
                    result.push_str(&format!(
                        "lapply({}, function(.el) {}$new(.ptr = .el))",
                        expr, entry.r_class_name
                    ));
                }
                "s7" => {
                    result.push_str(&format!(
                        "lapply({}, function(.el) {}(.ptr = .el))",
                        expr, entry.r_class_name
                    ));
                }
                "s4" => {
                    result.push_str(&format!(
                        "lapply({}, function(.el) methods::new(\"{}\", ptr = .el))",
                        expr, entry.r_class_name
                    ));
                }
                _ => {
                    result.push_str(&format!(
                        "lapply({}, function(.el) structure(.el, class = \"{}\"))",
                        expr, entry.r_class_name
                    ));
                }
            },
            None => result.push_str(expr),
        },
    )
}

// endregion

/// Write all R wrapper entries to a file.
///
/// Called from [`miniextendr_write_wrappers`] (via `dyn.load`/`.Call` of the
/// installed shared object). All distributed_slice entries from `#[miniextendr]`
/// items are available because stub.c force-loads the whole user crate.
///
/// Host-only — wasm32 doesn't run wrapper-gen.
#[cfg(not(target_arch = "wasm32"))]
pub fn write_r_wrappers_to_file(path: &str) {
    // Build the new content in memory
    let mut content = String::from(
        "# ---- AUTO-GENERATED FILE - DO NOT EDIT ----
# This file is generated by the miniextendr proc-macro during package build.
# Any manual changes will be overwritten.
#
# To regenerate: rebuild the package (R CMD INSTALL or devtools::install).
# nolint start
# nocov start

# Internal helper: re-raise a tagged Rust error/condition value as an R condition.
# Generated wrappers call this whenever `.Call()` returns a `rust_condition_value`.
# `.call_default` is the wrapper's `sys.call()`, used as the fallback when the
# Rust panic payload didn't carry a captured call (e.g. lambda contexts that
# pass `.call = NULL` to `.Call`). For error/panic kinds `stop()` longjmps;
# for warning/message/condition the helper signals and returns invisible(NULL),
# which the wrapper's surrounding `return(...)` propagates as its result.
.miniextendr_raise_condition <- function(.val, .call_default) {
  .msg <- .val$error
  .call <- (if (is.null(.val$call)) .call_default else .val$call)
  .class <- .val$class
  # `.val$data` is an optional named list of structured fields (from the
  # macros' `data = ...` form). When present, splice its named elements into
  # the condition object alongside message/call/kind so handlers can read
  # `e$<name>`. `utils::modifyList` keeps the base fields and appends the
  # data fields; a malformed (non-list / unnamed) payload is ignored.
  .data <- .val$data
  .cond_fields <- function(base) {
    if (is.null(.data) || !is.list(.data) || is.null(names(.data))) {
      base
    } else {
      utils::modifyList(base, .data)
    }
  }
  switch(.val$kind,
    error = stop(structure(.cond_fields(list(message = .msg, call = .call, kind = \"error\")),
      class = c(.class, \"rust_error\", \"simpleError\", \"error\", \"condition\"))),
    warning = warning(structure(.cond_fields(list(message = .msg, call = .call, kind = \"warning\")),
      class = c(.class, \"rust_warning\", \"simpleWarning\", \"warning\", \"condition\"))),
    message = message(structure(.cond_fields(list(message = paste0(.msg, \"\\n\"), call = NULL, kind = \"message\")),
      class = c(.class, \"rust_message\", \"simpleMessage\", \"message\", \"condition\"))),
    condition = signalCondition(structure(.cond_fields(list(message = .msg, call = .call, kind = \"condition\")),
      class = c(.class, \"rust_condition\", \"simpleCondition\", \"condition\"))),
    panic = stop(structure(list(message = .msg, call = .call, kind = \"panic\"),
      class = c(\"rust_error\", \"simpleError\", \"error\", \"condition\"))),
    stop(structure(list(message = .msg, call = .call, kind = .val$kind),
      class = c(\"rust_error\", \"simpleError\", \"error\", \"condition\")))
  )
  invisible(NULL)
}

",
    );

    for fragment in collect_r_wrappers() {
        content.push_str(fragment.as_ref());
        content.push_str("\n\n");
    }

    content.push_str("# nocov end\n# nolint end\n");

    // Replace match_arg choices placeholders with actual enum choices.
    // If the entry has a `preferred_default`, rotate the list so that value
    // is first — R's `match.arg(arg)` returns `arg[1]` when arg matches the
    // formal default, so the position-0 element becomes the effective default.
    for entry in MX_MATCH_ARG_CHOICES.iter() {
        let choices_str = (entry.choices_str)();
        let rotated = if entry.preferred_default.is_empty() {
            choices_str
        } else {
            rotate_choices_for_default(&choices_str, entry.preferred_default, entry.placeholder)
        };
        let replacement = format!("c({rotated})");
        content = content.replace(entry.placeholder, &replacement);
    }

    // Replace match_arg @param doc placeholders with human-readable choice descriptions
    for entry in MX_MATCH_ARG_PARAM_DOCS.iter() {
        let choices = (entry.choices_str)();
        let prefix = if entry.several_ok {
            "One or more of"
        } else {
            "One of"
        };
        let replacement = format!("{prefix} {choices}.");
        content = content.replace(entry.placeholder, &replacement);
    }

    // Replace .__MX_S7_SIDECAR_PROP_DOCS_<TypeName>__ placeholders with @prop lines.
    //
    // Each S7 class wrapper with `r_data_accessors` embeds one placeholder per type.
    // We collect all entries for each type name and emit `#' @prop field doc` lines.
    {
        use std::collections::HashMap;
        // Group entries by rust_type
        let mut by_type: HashMap<&'static str, Vec<&SidecarPropEntry>> = HashMap::new();
        for entry in MX_S7_SIDECAR_PROPS.iter() {
            by_type.entry(entry.rust_type).or_default().push(entry);
        }

        const SIDECAR_PREFIX: &str = ".__MX_S7_SIDECAR_PROP_DOCS_";
        const SIDECAR_SUFFIX: &str = "__";
        let mut result = String::with_capacity(content.len());
        let mut remaining = content.as_str();
        while let Some(start) = remaining.find(SIDECAR_PREFIX) {
            result.push_str(&remaining[..start]);
            remaining = &remaining[start + SIDECAR_PREFIX.len()..];
            if let Some(end) = remaining.find(SIDECAR_SUFFIX) {
                let rust_name = &remaining[..end];
                remaining = &remaining[end + SIDECAR_SUFFIX.len()..];
                // Emit @prop lines for each sidecar field registered for this type
                if let Some(entries) = by_type.get(rust_name) {
                    let prop_lines: String = entries
                        .iter()
                        .map(|e| format!("#' @prop {} {}", e.field_name, e.prop_doc))
                        .collect::<Vec<_>>()
                        .join("\n");
                    result.push_str(&prop_lines);
                }
                // If no entries, the placeholder is simply removed (empty replacement)
            } else {
                // Malformed placeholder — emit prefix and stop
                result.push_str(SIDECAR_PREFIX);
                break;
            }
        }
        result.push_str(remaining);
        content = result;
    }

    // Replace .__MX_CLASS_REF_<RustName>__ placeholders with actual R class names.
    //
    // Build a lookup from rust_type → ClassNameEntry, then do a linear scan over
    // the content for each placeholder. We avoid pulling in a regex dependency
    // by scanning for the sentinel prefix directly.
    {
        let class_index = build_class_name_index(MX_CLASS_NAMES.iter());

        // Two placeholder forms:
        //   .__MX_CLASS_REF_<RustName>__         → loud fallback on miss
        //     (used by R6 `inherit =`, S7 parent class, convert_from / convert_to)
        //   .__MX_CLASS_REF_OR_ANY_<RustName>__  → silent `S7::class_any` on miss
        //     (used by S7 property class constraints — #203: a getter returning
        //     `SEXP`, `PathBuf`, or an R6/S3/S4 type shouldn't break load-time
        //     with "object '…' not found"; the property just falls back to the
        //     permissive class_any it had pre-#154.)
        const OR_ANY_PREFIX: &str = ".__MX_CLASS_REF_OR_ANY_";
        const PREFIX: &str = ".__MX_CLASS_REF_";
        const SUFFIX: &str = "__";

        let mut result = String::with_capacity(content.len());
        let mut remaining = content.as_str();
        while let Some(start) = remaining.find(PREFIX) {
            result.push_str(&remaining[..start]);
            // Does this occurrence have the OR_ANY form?
            let rest_from_prefix = &remaining[start..];
            let (quiet_fallback, header_len) = if rest_from_prefix.starts_with(OR_ANY_PREFIX) {
                (true, OR_ANY_PREFIX.len())
            } else {
                (false, PREFIX.len())
            };
            remaining = &rest_from_prefix[header_len..];
            // Find the closing __
            if let Some(end) = remaining.find(SUFFIX) {
                let rust_name = &remaining[..end];
                remaining = &remaining[end + SUFFIX.len()..];
                match class_index.get(rust_name) {
                    Some(entry) if quiet_fallback => {
                        // S7 property resolved to an S7 class → use the
                        // registered name. Registered-but-non-S7 types
                        // (R6 / S3 / S4 / Env / Vctrs) fall through to
                        // class_any because S7 can't use them as class
                        // constraints.
                        if entry.class_system == "s7" {
                            result.push_str(entry.r_class_name);
                        } else {
                            result.push_str("S7::class_any");
                        }
                    }
                    Some(entry) => {
                        result.push_str(entry.r_class_name);
                    }
                    None if quiet_fallback => {
                        // Unresolved S7 property type → silent class_any,
                        // matching pre-#154 behavior.
                        result.push_str("S7::class_any");
                    }
                    None => {
                        // Unresolved non-property CLASS_REF: fall back to the
                        // bare Rust name with a warning.
                        eprintln!(
                            "miniextendr: unresolved class reference `{rust_name}` \
                             in R wrapper — is the class defined in a reachable crate?"
                        );
                        result.push_str(rust_name);
                    }
                }
            } else {
                // Malformed placeholder (no closing __): emit as-is and stop scanning.
                result.push_str(PREFIX);
                break;
            }
        }
        result.push_str(remaining);
        content = result;
    }

    // Resolve the cross-class return wrapper placeholders: the scalar
    // `.__MX_WRAP_RETURN_<RustName>__(<expr>)` family and the list-shaped
    // `.__MX_WRAP_LIST_RETURN_<RustName>__(<expr>)` family (#1284). The
    // prefixes are non-overlapping, so pass order does not matter — each
    // resolver only consumes its own markers.
    {
        let class_index = build_class_name_index(MX_CLASS_NAMES.iter());
        content = resolve_scalar_return_wrappers(&content, &class_index);
        content = resolve_list_return_wrappers(&content, &class_index);
    }

    // Resolve .__MX_GENERIC_DOC__(...) markers into standalone Rd pages.
    //
    // Each package-owned S7/S4 generic-creation site emits one marker line:
    //   .__MX_GENERIC_DOC__(kind="S7", generic="get_value", class="MyClass",
    //                       export=true, dispatch="x", no_dots=false)
    //
    // This pass:
    //   1. Scans all fragments for marker lines.
    //   2. Groups markers by generic name.
    //   3. Replaces the FIRST marker per generic with a synthesised standalone
    //      roxygen block (bare @name <generic> → bare \alias{<generic>}, listing
    //      every in-package implementing class).
    //   4. Deletes all remaining markers (keeping none in the final file).
    //
    // Method blocks keep their qualified @name Class-generic so the PR #83
    // duplicate-alias fix is not re-introduced.
    content = resolve_generic_doc_markers(content);

    // Resolve .__MX_INHERITED_PARAM__(...) markers.
    //
    // Each R6 subclass method param that might be inherited from a parent class
    // emits one marker line per undocumented param. The write-time pass:
    //   1. Scans the assembled content for method and class-level @param docs.
    //   2. For each marker: if the parent class is in-package and has the param
    //      documented (at method or class level) → delete the marker line
    //      (roxygen2 8.0.0 inherits the parent's @param into the subclass method).
    //   3. Otherwise → replace the marker with the fallback placeholder text.
    //
    // This guarantees zero markers remain in the final wrappers.R and zero
    // roxygen2 warnings about undocumented parameters.
    content = resolve_inherited_param_markers(content);

    // Detect collisions between separately-expanded wrapper definitions (#991).
    //
    // Two top-level `name <- function` definitions of the same name silently
    // clobber each other at load time (last write wins), dispatching calls to
    // the wrong implementation. The compile-time `check_s7_shortcut_collisions`
    // only sees a single impl block; collisions that span macro expansions --
    // an S7 shortcut vs a `#[derive(ExternalPtr)]` sidecar accessor, or two S7
    // impl blocks on the same type -- are only visible here, where every name
    // set is assembled. We resolve the sidecar-accessor prefix through
    // MX_CLASS_NAMES so a `class = "Override"` is honoured, then scan the final
    // content. This runs after all placeholder resolution so names are final.
    {
        let class_index = build_class_name_index(MX_CLASS_NAMES.iter());
        let accessor_producers = sidecar_accessor_names(&MX_S7_SIDECAR_PROPS, &class_index);
        if let Err(msg) = detect_duplicate_wrapper_defs(&content, &accessor_producers) {
            panic!("{msg}");
        }
    }

    // Only write if content changed (avoids unnecessary NAMESPACE/man regeneration).
    //
    // "Semantic equality" means equal after stripping source-position suffixes from
    // the source-attribution comments emitted by the `#[miniextendr]` proc-macro:
    //
    //   # Generated from Rust fn `foo` (lib.rs:42:8)
    //                                           ^^^^^ positional suffix — ignored here
    //
    // These positions shift whenever any unrelated Rust source above a wrapper is
    // edited. The NOTE and the file rewrite should only fire when the actual
    // wrapper code, exports, or docstrings change — not when line numbers move.
    // The written file still carries the real line:col for jump-to-source.
    let existing = std::fs::read_to_string(path).unwrap_or_default();
    if wrappers_semantically_equal(&existing, &content) {
        return;
    }

    // Write via a sibling temp file then rename for atomicity.
    //
    // A plain `std::fs::write` truncates in place; a concurrent reader (e.g. a
    // second `R CMD INSTALL` process) can observe a torn file. `rename(2)` is
    // atomic on POSIX — the destination is replaced in a single syscall, so
    // readers always see either the old or the new content. On Windows, `rename`
    // fails when the destination exists, so we remove it first; that window is
    // benign (worst case the reader gets "file not found" and retries, which is
    // the same outcome as a torn write).
    let dest = std::path::Path::new(path);
    let tmp = dest.with_extension("tmp");
    std::fs::write(&tmp, content.as_bytes())
        .unwrap_or_else(|e| panic!("failed to write {}: {e}", tmp.display()));
    #[cfg(windows)]
    let _ = std::fs::remove_file(dest);
    std::fs::rename(&tmp, dest).unwrap_or_else(|e| {
        panic!(
            "failed to rename {} → {}: {e}",
            tmp.display(),
            dest.display()
        )
    });

    if !existing.is_empty() {
        let filename = dest
            .file_name()
            .and_then(|f| f.to_str())
            .unwrap_or("wrappers.R");
        eprintln!();
        eprintln!("NOTE: {filename} changed — run devtools::document() to update NAMESPACE.");
        eprintln!();
    }
}

/// Returns `true` when `a` and `b` are equal after normalising away
/// `(<file>.rs:LINE:COL)` positional suffixes in source-attribution comments.
///
/// The `#[miniextendr]` proc-macro emits comments of the form:
/// ```r
/// # Generated from Rust fn `foo` (lib.rs:42:8)
/// ```
/// The `42:8` part shifts whenever unrelated code above the wrapper is edited,
/// producing spurious wrapper-file rewrites and misleading NOTEs. Normalisation
/// replaces `(lib.rs:42:8)` → `(lib.rs:_:_)` for the comparison only; the
/// file on disk still carries the real positions.
///
/// A match requires `(` + one or more non-`()`/non-newline chars + `.rs:` +
/// ASCII digits + `:` + ASCII digits + `)`. Malformed or non-`.rs` patterns
/// are left untouched.
///
/// Host-only: the sole caller is [`write_r_wrappers_to_file`], gated off on
/// wasm32 (the wrapper-gen pass doesn't run there).
#[cfg(not(target_arch = "wasm32"))]
fn wrappers_semantically_equal(a: &str, b: &str) -> bool {
    normalize_source_locs(a) == normalize_source_locs(b)
}

/// Replace every `(<stem>.rs:LINE:COL)` occurrence with `(<stem>.rs:_:_)`.
///
/// Returns a [`std::borrow::Cow::Borrowed`] slice when no replacements are
/// needed (zero-allocation fast path for the common case where the file has
/// never been written or is truly unchanged).
#[cfg(not(target_arch = "wasm32"))]
fn normalize_source_locs(s: &str) -> std::borrow::Cow<'_, str> {
    // Fast path: bail early if there is no `.rs:` anywhere in the string.
    if !s.contains(".rs:") {
        return std::borrow::Cow::Borrowed(s);
    }

    let bytes = s.as_bytes();
    let len = bytes.len();
    let mut out = String::with_capacity(len);
    let mut pos = 0usize;
    let mut any_replaced = false;

    while pos < len {
        // Look for the next `(`.
        let Some(open) = memchr(bytes, pos, b'(') else {
            break;
        };

        // After `(`, scan for `.rs:` without crossing `)` or `(` or a newline.
        let inner_start = open + 1;
        let Some(dot_rs) = find_substr(bytes, inner_start, b".rs:") else {
            // No `.rs:` at all in the rest of the string — copy remainder and stop.
            out.push_str(&s[pos..]);
            return std::borrow::Cow::Owned(out);
        };

        // Make sure `.rs:` precedes any closing `)`, `(`, or newline (no nesting).
        let intervening = &bytes[inner_start..dot_rs];
        if intervening
            .iter()
            .any(|&b| b == b')' || b == b'(' || b == b'\n')
        {
            // Guard crossed; copy up to and including `(` and continue after it.
            out.push_str(&s[pos..=open]);
            pos = open + 1;
            continue;
        }

        // After `.rs:`, consume digits for LINE.
        let after_colon1 = dot_rs + 4; // skip `.rs:`
        let Some(colon2) = scan_digits(bytes, after_colon1) else {
            // Not digits after `.rs:` — not a source-attribution pattern.
            out.push_str(&s[pos..=open]);
            pos = open + 1;
            continue;
        };
        if colon2 >= len || bytes[colon2] != b':' {
            out.push_str(&s[pos..=open]);
            pos = open + 1;
            continue;
        }

        // After the second `:`, consume digits for COL.
        let after_colon2 = colon2 + 1;
        let Some(close_pos) = scan_digits(bytes, after_colon2) else {
            out.push_str(&s[pos..=open]);
            pos = open + 1;
            continue;
        };
        if close_pos >= len || bytes[close_pos] != b')' {
            out.push_str(&s[pos..=open]);
            pos = open + 1;
            continue;
        }

        // We have a match: `(stem.rs:LINE:COL)` — emit `(stem.rs:_:_)`.
        any_replaced = true;
        out.push_str(&s[pos..inner_start]); // text before inner_start (includes `(`)
        out.push_str(&s[inner_start..dot_rs + 3]); // `stem.rs` (without the colon)
        out.push_str(":_:_)");
        pos = close_pos + 1; // skip past the closing `)`
    }

    if !any_replaced {
        return std::borrow::Cow::Borrowed(s);
    }

    out.push_str(&s[pos..]);
    std::borrow::Cow::Owned(out)
}

/// Find the first occurrence of `needle` in `haystack[from..]`.
/// Returns the absolute index in `haystack`, or `None`.
#[cfg(not(target_arch = "wasm32"))]
#[inline]
fn find_substr(haystack: &[u8], from: usize, needle: &[u8]) -> Option<usize> {
    let window = haystack.get(from..)?;
    window
        .windows(needle.len())
        .position(|w| w == needle)
        .map(|rel| from + rel)
}

/// Find the first byte equal to `needle` in `haystack[from..]`.
/// Returns the absolute index, or `None`.
#[cfg(not(target_arch = "wasm32"))]
#[inline]
fn memchr(haystack: &[u8], from: usize, needle: u8) -> Option<usize> {
    haystack[from..]
        .iter()
        .position(|&b| b == needle)
        .map(|rel| from + rel)
}

/// Advance past a run of ASCII digits starting at `haystack[from]`.
/// Returns the absolute index of the first non-digit byte, or `None` if
/// there are no digits at `from` (empty run is not valid).
#[cfg(not(target_arch = "wasm32"))]
#[inline]
fn scan_digits(haystack: &[u8], from: usize) -> Option<usize> {
    let start = haystack.get(from..)?;
    let count = start.iter().take_while(|&&b| b.is_ascii_digit()).count();
    if count == 0 { None } else { Some(from + count) }
}
// endregion

// region: Duplicate wrapper-definition detection (#991)

/// Compute the sidecar accessor function names a `#[derive(ExternalPtr)]` emits
/// for each `#[r_data]` field, resolving the R-visible prefix through the
/// class-name registry.
///
/// The derive emits two top-level functions per field —
/// `<prefix>_get_<field>` and `<prefix>_set_<field>` — where `<prefix>` is the
/// R-visible class name. That equals the Rust type name unless the impl block
/// set `class = "Override"`, in which case `MX_CLASS_NAMES` carries the
/// override. We resolve through `class_index` so the names we attribute match
/// what actually lands in the wrapper file.
///
/// Returns a map from accessor function name -> the human-readable producer
/// description used in the collision message.
#[cfg(not(target_arch = "wasm32"))]
fn sidecar_accessor_names(
    sidecar_props: &[SidecarPropEntry],
    class_index: &std::collections::HashMap<&str, &ClassNameEntry>,
) -> std::collections::HashMap<String, String> {
    let mut out = std::collections::HashMap::new();
    for entry in sidecar_props {
        // Resolve the R-visible prefix (honours `class = "Override"`).
        let prefix = class_index
            .get(entry.rust_type)
            .map(|c| c.r_class_name)
            .unwrap_or(entry.rust_type);
        let producer = format!(
            "#[derive(ExternalPtr)] sidecar field `{}` on `{}`",
            entry.field_name, entry.rust_type
        );
        out.insert(
            format!("{prefix}_get_{}", entry.field_name),
            producer.clone(),
        );
        out.insert(format!("{prefix}_set_{}", entry.field_name), producer);
    }
    out
}

/// Detect a second top-level `name <- function` definition of any wrapper
/// function in the assembled R wrapper text.
///
/// This is the write-time counterpart to the compile-time
/// `check_s7_shortcut_collisions` (in `miniextendr-macros`): it catches name
/// collisions that span *separate* macro expansions and are therefore invisible
/// to any single proc-macro invocation. The two motivating cases (#991):
///
/// 1. An S7 fast-path shortcut `<Class>_<method>` colliding with a
///    `#[derive(ExternalPtr)]` sidecar accessor `<Class>_get_<field>` /
///    `<Class>_set_<field>` -- the sidecar field names live in the
///    `MX_S7_SIDECAR_PROPS` slice, which the impl-block macro can't see.
/// 2. Two `#[miniextendr(s7)]` impl blocks on the same type each emitting a
///    `<Class>_<method>` shortcut -- cross-impl-block, also invisible to a
///    single expansion.
///
/// Without this check the second definition silently clobbers the first
/// (last-write-wins in R), so a call dispatches to the wrong implementation.
///
/// `accessor_producers` maps a known sidecar-accessor name to a description of
/// its producing derive; when a duplicate matches one we name the derive in the
/// message, otherwise we report the generic "defined more than once" form.
///
/// Returns `Err(message)` naming the offending function on the first collision
/// found; `Ok(())` when every top-level definition name is unique.
#[cfg(not(target_arch = "wasm32"))]
fn detect_duplicate_wrapper_defs(
    content: &str,
    accessor_producers: &std::collections::HashMap<String, String>,
) -> Result<(), String> {
    use std::collections::HashSet;

    let mut seen: HashSet<&str> = HashSet::new();

    for line in content.lines() {
        // Only top-level definitions matter -- class-method assignments like
        // `S7::method(generic, Class) <- function(...)` and indented closures
        // (R6 methods, S7 getters) are not bare `name <- function` forms and
        // must not trip the scan.
        let Some(name) = parse_top_level_fn_def_name(line) else {
            continue;
        };

        if !seen.insert(name) {
            // Second definition of this name -> collision.
            if let Some(producer) = accessor_producers.get(name) {
                return Err(format!(
                    "miniextendr: wrapper function `{name}` is defined more than once. \
                     One definition comes from {producer}; the other from an S7 fast-path \
                     shortcut or `#[miniextendr]` function of the same name. The second \
                     definition silently overwrites the first at load time. Rename the \
                     colliding S7 method (`#[miniextendr(s7(r_name = \"...\"))]`), opt it \
                     out of the shortcut (`#[miniextendr(s7(no_shortcut))]`), or rename the \
                     sidecar field."
                ));
            }
            return Err(format!(
                "miniextendr: wrapper function `{name}` is defined more than once in the \
                 generated R wrappers. Two `#[miniextendr]`-generated top-level functions \
                 emit the same name and the second silently overwrites the first at load \
                 time. Common causes: two `#[miniextendr(s7)]` impl blocks (or an S7 \
                 shortcut and another generated function) sharing a `<Class>_<method>` \
                 name — rename one (`#[miniextendr(s7(r_name = \"...\"))]`) or opt it out \
                 of the shortcut (`#[miniextendr(s7(no_shortcut))]`); or two trait impls \
                 whose generated standalone wrapper names are not class-qualified — rename \
                 the colliding method (`#[miniextendr(<system>(r_name = \"...\"))]`)."
            ));
        }
    }

    Ok(())
}

/// Parse the function name from a top-level `name <- function(...)` definition
/// line, or return `None` when the line is not such a definition.
///
/// Recognises only **top-level** definitions: the line must start at column 0
/// (no leading whitespace -- indented forms are R6/S7 closures, not standalone
/// wrappers) and the left-hand side must be a single bare R identifier. Lines
/// where the LHS is a call (e.g. `S7::method(...) <- function`) or contains `$`
/// / `[[` / `::` are not bare definitions and are skipped.
#[cfg(not(target_arch = "wasm32"))]
fn parse_top_level_fn_def_name(line: &str) -> Option<&str> {
    // Top-level only: reject any leading whitespace.
    if line.starts_with([' ', '\t']) {
        return None;
    }
    let (lhs, rhs) = line.split_once("<-")?;
    // RHS must be (after trimming) the start of a `function` definition.
    if !rhs.trim_start().starts_with("function") {
        return None;
    }
    let name = lhs.trim();
    if name.is_empty() {
        return None;
    }
    // Bare identifier only: R names may contain letters, digits, `.` and `_`,
    // and must not start with a digit. Anything else (a call on the LHS, a `$`
    // assignment, a `::`-qualified target, backtick-quoted names with spaces)
    // is not a standalone wrapper definition we own.
    let mut chars = name.chars();
    let first = chars.next()?;
    if !(first.is_ascii_alphabetic() || first == '.') {
        return None;
    }
    if name
        .chars()
        .all(|c| c.is_ascii_alphanumeric() || c == '.' || c == '_')
    {
        Some(name)
    } else {
        None
    }
}
// endregion

// region: C-Callable Entry Points (wrapper generation)
//
// All wrapper-gen entry points are host-only — wasm32 builds skip
// them (the wrapper-gen pass itself doesn't run on wasm32; wrappers and
// `wasm_registry.rs` are pre-generated on native and shipped into the
// wasm32 install).

/// C-callable entry point for R wrapper generation.
///
/// Called from Makevars via Rscript: loads the installed shared object with
/// `dyn.load()`, then `.Call("miniextendr_write_wrappers", path)` to write
/// `R/miniextendr-wrappers.R`. NAMESPACE generation is left to roxygen2
/// (`devtools::document()`).
///
/// # Safety
///
/// `path_sexp` must be a valid STRSXP of length >= 1.
#[cfg(not(target_arch = "wasm32"))]
#[unsafe(no_mangle)]
pub unsafe extern "C" fn miniextendr_write_wrappers(path_sexp: crate::SEXP) -> crate::SEXP {
    unsafe {
        use crate::{SEXP, SexpExt};

        let char_sexp = path_sexp.string_elt_unchecked(0);
        let c_str = std::ffi::CStr::from_ptr(char_sexp.r_char_unchecked());
        let path = c_str
            .to_str()
            .unwrap_or_else(|e| panic!("invalid UTF-8 in path: {e}"));

        write_r_wrappers_to_file(path);

        SEXP::nil()
    }
}

/// C-callable entry point for `wasm_registry.rs` generation.
///
/// Pairs with [`miniextendr_write_wrappers`]: same loaded object, separate `.Call`,
/// independent output path. Host-only; the generated file itself is then
/// consumed at compile time by the user crate's wasm32 build via
/// `install_wasm_runtime_slices`.
///
/// # Safety
///
/// `path_sexp` must be a valid STRSXP of length >= 1.
#[cfg(not(target_arch = "wasm32"))]
#[unsafe(no_mangle)]
pub unsafe extern "C" fn miniextendr_write_wasm_registry(path_sexp: crate::SEXP) -> crate::SEXP {
    unsafe {
        use crate::{SEXP, SexpExt};

        let char_sexp = path_sexp.string_elt_unchecked(0);
        let c_str = std::ffi::CStr::from_ptr(char_sexp.r_char_unchecked());
        let path = c_str
            .to_str()
            .unwrap_or_else(|e| panic!("invalid UTF-8 in path: {e}"));

        crate::wasm_registry_writer::write_wasm_registry_to_file(path);

        SEXP::nil()
    }
}
// endregion

// region: Unit tests for class-ref placeholder resolution

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

    /// Run the class-ref placeholder resolver over `content` using `entries` as the registry.
    ///
    /// This mirrors the logic in `write_r_wrappers_to_file` but operates on a caller-supplied
    /// slice so it can be called from unit tests without a live distributed_slice.
    fn resolve_class_refs(content: &str, entries: &[ClassNameEntry]) -> String {
        let class_index = build_class_name_index(entries.iter());

        const OR_ANY_PREFIX: &str = ".__MX_CLASS_REF_OR_ANY_";
        const PREFIX: &str = ".__MX_CLASS_REF_";
        const SUFFIX: &str = "__";

        let mut result = String::with_capacity(content.len());
        let mut remaining = content;
        while let Some(start) = remaining.find(PREFIX) {
            result.push_str(&remaining[..start]);
            let rest_from_prefix = &remaining[start..];
            let (quiet_fallback, header_len) = if rest_from_prefix.starts_with(OR_ANY_PREFIX) {
                (true, OR_ANY_PREFIX.len())
            } else {
                (false, PREFIX.len())
            };
            remaining = &rest_from_prefix[header_len..];
            if let Some(end) = remaining.find(SUFFIX) {
                let rust_name = &remaining[..end];
                remaining = &remaining[end + SUFFIX.len()..];
                match class_index.get(rust_name) {
                    Some(entry) if quiet_fallback => {
                        if entry.class_system == "s7" {
                            result.push_str(entry.r_class_name);
                        } else {
                            result.push_str("S7::class_any");
                        }
                    }
                    Some(entry) => result.push_str(entry.r_class_name),
                    None if quiet_fallback => result.push_str("S7::class_any"),
                    None => result.push_str(rust_name),
                }
            } else {
                result.push_str(PREFIX);
                break;
            }
        }
        result.push_str(remaining);
        result
    }

    /// Two labeled impl blocks on one type register identical entries (#1242);
    /// the index collapses them instead of treating the duplicate key as an error.
    #[test]
    fn class_name_index_dedups_identical_entries() {
        let entries = [
            ClassNameEntry {
                rust_type: "Foo",
                r_class_name: "Foo",
                class_system: "env",
            },
            ClassNameEntry {
                rust_type: "Foo",
                r_class_name: "Foo",
                class_system: "env",
            },
        ];
        let index = build_class_name_index(entries.iter());
        assert_eq!(index.len(), 1);
        assert_eq!(index["Foo"].r_class_name, "Foo");
    }

    /// Disagreeing `class = "..."` overrides across blocks must fail loudly —
    /// placeholder resolution would otherwise pick whichever entry linkme
    /// ordered last.
    #[test]
    #[should_panic(expected = "conflicting class registrations for Rust type `Foo`")]
    fn class_name_index_panics_on_conflicting_override() {
        let entries = [
            ClassNameEntry {
                rust_type: "Foo",
                r_class_name: "Foo",
                class_system: "env",
            },
            ClassNameEntry {
                rust_type: "Foo",
                r_class_name: "FooOverride",
                class_system: "env",
            },
        ];
        let _ = build_class_name_index(entries.iter());
    }

    /// Run the production scalar cross-class return wrapper resolver over
    /// `content` using `entries` as the class registry.
    fn resolve_return_wrappers(content: &str, entries: &[ClassNameEntry]) -> String {
        let class_index = build_class_name_index(entries.iter());
        resolve_scalar_return_wrappers(content, &class_index)
    }

    /// Run the production list cross-class return wrapper resolver (#1284)
    /// over `content` using `entries` as the class registry.
    fn resolve_list_wrappers(content: &str, entries: &[ClassNameEntry]) -> String {
        let class_index = build_class_name_index(entries.iter());
        resolve_list_return_wrappers(content, &class_index)
    }

    #[test]
    fn test_class_ref_resolver_with_override() {
        // S7Shape is registered with r_class_name = "Shape" (override)
        let entries = [
            ClassNameEntry {
                rust_type: "S7Shape",
                r_class_name: "Shape",
                class_system: "s7",
            },
            ClassNameEntry {
                rust_type: "S7Circle",
                r_class_name: "S7Circle",
                class_system: "s7",
            },
        ];

        let input = r#"S7Circle <- S7::new_class("S7Circle", parent = .__MX_CLASS_REF_S7Shape__, properties = list())"#;
        let output = resolve_class_refs(input, &entries);
        assert_eq!(
            output,
            r#"S7Circle <- S7::new_class("S7Circle", parent = Shape, properties = list())"#
        );
    }

    #[test]
    fn test_class_ref_resolver_multiple_placeholders() {
        let entries = [
            ClassNameEntry {
                rust_type: "Point2D",
                r_class_name: "Point2D",
                class_system: "s7",
            },
            ClassNameEntry {
                rust_type: "Point3D",
                r_class_name: "Point3D",
                class_system: "s7",
            },
        ];

        let input = "S7::method(convert, list(.__MX_CLASS_REF_Point2D__, Point3D)) <- function(from, to) {}";
        let output = resolve_class_refs(input, &entries);
        assert_eq!(
            output,
            "S7::method(convert, list(Point2D, Point3D)) <- function(from, to) {}"
        );
    }

    #[test]
    fn test_class_ref_resolver_unresolved_falls_back_to_rust_name() {
        let entries: [ClassNameEntry; 0] = [];
        let input = "parent = .__MX_CLASS_REF_UnknownClass__";
        let output = resolve_class_refs(input, &entries);
        // Falls back to the bare Rust name
        assert_eq!(output, "parent = UnknownClass");
    }

    #[test]
    fn test_class_ref_resolver_verbatim_passthrough() {
        // Strings that are NOT bare identifiers should not have been wrapped in
        // a placeholder, so they pass through the resolver unchanged.
        let entries: [ClassNameEntry; 0] = [];
        let input = "parent = S7::class_any";
        let output = resolve_class_refs(input, &entries);
        assert_eq!(output, "parent = S7::class_any");
    }

    #[test]
    fn test_is_bare_identifier_via_resolver() {
        // A placeholder for a bare identifier should be resolved.
        let entries = [ClassNameEntry {
            rust_type: "MyClass",
            r_class_name: "MyClass",
            class_system: "r6",
        }];
        let input = "inherit = .__MX_CLASS_REF_MyClass__";
        let output = resolve_class_refs(input, &entries);
        assert_eq!(output, "inherit = MyClass");
    }

    // #203 — OR_ANY variant: S7 property class constraints should fall back
    // silently to S7::class_any when the type isn't a registered S7 class.

    #[test]
    fn or_any_resolves_registered_s7_class() {
        let entries = [ClassNameEntry {
            rust_type: "S7PropInner",
            r_class_name: "S7PropInner",
            class_system: "s7",
        }];
        let input = "class = .__MX_CLASS_REF_OR_ANY_S7PropInner__";
        let output = resolve_class_refs(input, &entries);
        assert_eq!(output, "class = S7PropInner");
    }

    #[test]
    fn or_any_unregistered_type_falls_back_to_class_any_silently() {
        // No entry for SEXP, PathBuf, Json, etc.
        let entries: [ClassNameEntry; 0] = [];
        let input = "class = .__MX_CLASS_REF_OR_ANY_SEXP__";
        let output = resolve_class_refs(input, &entries);
        assert_eq!(output, "class = S7::class_any");
    }

    #[test]
    fn or_any_registered_non_s7_type_falls_back_to_class_any() {
        // A type registered as an R6 class can't serve as an S7 class
        // constraint — S7 would error at load time. Quiet fallback avoids
        // that footgun.
        let entries = [ClassNameEntry {
            rust_type: "R6Counter",
            r_class_name: "R6Counter",
            class_system: "r6",
        }];
        let input = "class = .__MX_CLASS_REF_OR_ANY_R6Counter__";
        let output = resolve_class_refs(input, &entries);
        assert_eq!(output, "class = S7::class_any");
    }

    #[test]
    fn loud_class_ref_still_emits_bare_name_when_unresolved() {
        // The existing CLASS_REF variant (without OR_ANY) keeps its loud
        // behavior: bare Rust name + compile-time warning. Regression test
        // for that path alongside the OR_ANY introduction.
        let entries: [ClassNameEntry; 0] = [];
        let input = "parent = .__MX_CLASS_REF_UnknownClass__";
        let output = resolve_class_refs(input, &entries);
        assert_eq!(output, "parent = UnknownClass");
    }

    #[test]
    fn mixed_placeholders_resolve_independently() {
        // A single wrapper can mix both variants — `inherit = parent` (loud)
        // and `class = prop_type` (quiet). Verify each takes its own path.
        let entries = [
            ClassNameEntry {
                rust_type: "Parent",
                r_class_name: "Parent",
                class_system: "s7",
            },
            // PropInner deliberately missing → should resolve to class_any.
        ];
        let input =
            "inherit = .__MX_CLASS_REF_Parent__, class = .__MX_CLASS_REF_OR_ANY_PropInner__";
        let output = resolve_class_refs(input, &entries);
        assert_eq!(output, "inherit = Parent, class = S7::class_any");
    }

    #[test]
    fn return_wrapper_resolves_r6_constructor() {
        let entries = [ClassNameEntry {
            rust_type: "R6Board",
            r_class_name: "R6Board",
            class_system: "r6",
        }];
        let input = "return(.__MX_WRAP_RETURN_R6Board__(.val))";
        let output = resolve_return_wrappers(input, &entries);
        assert_eq!(output, "return(R6Board$new(.ptr = .val))");
    }

    #[test]
    fn return_wrapper_resolves_s7_override_constructor() {
        let entries = [ClassNameEntry {
            rust_type: "S7Board",
            r_class_name: "PrettyBoard",
            class_system: "s7",
        }];
        let input = ".__MX_WRAP_RETURN_S7Board__(.val)";
        let output = resolve_return_wrappers(input, &entries);
        assert_eq!(output, "PrettyBoard(.ptr = .val)");
    }

    #[test]
    fn return_wrapper_resolves_s4_constructor() {
        let entries = [ClassNameEntry {
            rust_type: "S4Board",
            r_class_name: "S4Board",
            class_system: "s4",
        }];
        let input = ".__MX_WRAP_RETURN_S4Board__(.val)";
        let output = resolve_return_wrappers(input, &entries);
        assert_eq!(output, "methods::new(\"S4Board\", ptr = .val)");
    }

    #[test]
    fn return_wrapper_resolves_attribute_classes() {
        let entries = [
            ClassNameEntry {
                rust_type: "S3Board",
                r_class_name: "S3Board",
                class_system: "s3",
            },
            ClassNameEntry {
                rust_type: "EnvBoard",
                r_class_name: "EnvBoard",
                class_system: "env",
            },
        ];
        let input =
            "a <- .__MX_WRAP_RETURN_S3Board__(.val)\nb <- .__MX_WRAP_RETURN_EnvBoard__(.ptr)";
        let output = resolve_return_wrappers(input, &entries);
        assert_eq!(
            output,
            "a <- structure(.val, class = \"S3Board\")\nb <- structure(.ptr, class = \"EnvBoard\")"
        );
    }

    #[test]
    fn return_wrapper_unregistered_type_falls_back_to_value() {
        let entries: [ClassNameEntry; 0] = [];
        let input = ".__MX_WRAP_RETURN_JsonValue__(.val)";
        let output = resolve_return_wrappers(input, &entries);
        assert_eq!(output, ".val");
    }

    // #1284 — list-shaped cross-class return markers (`Vec<Class>` returns).

    /// CRITICAL non-overlap pin: the scalar resolver rewrites *unrecognized*
    /// names of its own prefix to the bare expression, so if the list marker
    /// shared the `.__MX_WRAP_RETURN_` prefix the scalar pass would consume
    /// and destroy it before the list pass ran. The `LIST_` infix keeps the
    /// families disjoint — the scalar resolver must leave list markers
    /// completely untouched (and vice versa).
    #[test]
    fn scalar_resolver_leaves_list_markers_untouched() {
        let entries = [ClassNameEntry {
            rust_type: "R6Board",
            r_class_name: "R6Board",
            class_system: "r6",
        }];
        let input = "a <- .__MX_WRAP_LIST_RETURN_R6Board__(.val)";
        let output = resolve_return_wrappers(input, &entries);
        assert_eq!(output, input, "scalar pass must not consume list markers");
    }

    #[test]
    fn list_resolver_leaves_scalar_markers_untouched() {
        let entries = [ClassNameEntry {
            rust_type: "R6Board",
            r_class_name: "R6Board",
            class_system: "r6",
        }];
        let input = "a <- .__MX_WRAP_RETURN_R6Board__(.val)";
        let output = resolve_list_wrappers(input, &entries);
        assert_eq!(output, input, "list pass must not consume scalar markers");
    }

    /// Both passes over content mixing the two families resolve each marker
    /// with its own resolver, in either pass order.
    #[test]
    fn scalar_and_list_markers_resolve_independently() {
        let entries = [ClassNameEntry {
            rust_type: "R6Board",
            r_class_name: "R6Board",
            class_system: "r6",
        }];
        let input =
            "a <- .__MX_WRAP_RETURN_R6Board__(.val)\nb <- .__MX_WRAP_LIST_RETURN_R6Board__(.val)";
        let expected = "a <- R6Board$new(.ptr = .val)\nb <- lapply(.val, function(.el) R6Board$new(.ptr = .el))";

        let scalar_first =
            resolve_list_wrappers(&resolve_return_wrappers(input, &entries), &entries);
        let list_first = resolve_return_wrappers(&resolve_list_wrappers(input, &entries), &entries);
        assert_eq!(scalar_first, expected);
        assert_eq!(list_first, expected);
    }

    #[test]
    fn list_return_wrapper_resolves_r6_lapply() {
        let entries = [ClassNameEntry {
            rust_type: "R6Board",
            r_class_name: "R6Board",
            class_system: "r6",
        }];
        let input = "return(.__MX_WRAP_LIST_RETURN_R6Board__(.val))";
        let output = resolve_list_wrappers(input, &entries);
        assert_eq!(
            output,
            "return(lapply(.val, function(.el) R6Board$new(.ptr = .el)))"
        );
    }

    #[test]
    fn list_return_wrapper_resolves_s7_override_lapply() {
        let entries = [ClassNameEntry {
            rust_type: "S7Board",
            r_class_name: "PrettyBoard",
            class_system: "s7",
        }];
        let input = ".__MX_WRAP_LIST_RETURN_S7Board__(.val)";
        let output = resolve_list_wrappers(input, &entries);
        assert_eq!(
            output,
            "lapply(.val, function(.el) PrettyBoard(.ptr = .el))"
        );
    }

    #[test]
    fn list_return_wrapper_resolves_s4_lapply() {
        let entries = [ClassNameEntry {
            rust_type: "S4Board",
            r_class_name: "S4Board",
            class_system: "s4",
        }];
        let input = ".__MX_WRAP_LIST_RETURN_S4Board__(.val)";
        let output = resolve_list_wrappers(input, &entries);
        assert_eq!(
            output,
            "lapply(.val, function(.el) methods::new(\"S4Board\", ptr = .el))"
        );
    }

    #[test]
    fn list_return_wrapper_resolves_attribute_classes_lapply() {
        let entries = [
            ClassNameEntry {
                rust_type: "S3Board",
                r_class_name: "S3Board",
                class_system: "s3",
            },
            ClassNameEntry {
                rust_type: "EnvBoard",
                r_class_name: "EnvBoard",
                class_system: "env",
            },
        ];
        let input = "a <- .__MX_WRAP_LIST_RETURN_S3Board__(.val)\nb <- .__MX_WRAP_LIST_RETURN_EnvBoard__(.ptr)";
        let output = resolve_list_wrappers(input, &entries);
        assert_eq!(
            output,
            "a <- lapply(.val, function(.el) structure(.el, class = \"S3Board\"))\nb <- lapply(.ptr, function(.el) structure(.el, class = \"EnvBoard\"))"
        );
    }

    #[test]
    fn list_return_wrapper_unregistered_type_falls_back_to_bare_list() {
        let entries: [ClassNameEntry; 0] = [];
        let input = ".__MX_WRAP_LIST_RETURN_JsonValue__(.val)";
        let output = resolve_list_wrappers(input, &entries);
        assert_eq!(output, ".val");
    }

    // region: normalize_source_locs unit tests (#528)

    #[test]
    fn normalize_source_locs_noop_on_plain_text() {
        // No `.rs:N:M` pattern — should return the input string unchanged (Borrowed).
        let input = "# just a comment\nfoo <- function() {}\n";
        let result = normalize_source_locs(input);
        assert_eq!(result.as_ref(), input);
        // Verify it's the zero-allocation borrowed path.
        assert!(matches!(result, std::borrow::Cow::Borrowed(_)));
    }

    #[test]
    fn normalize_source_locs_single_attribution() {
        let input = "# Generated from Rust fn `foo` (lib.rs:42:8)";
        let result = normalize_source_locs(input);
        assert_eq!(
            result.as_ref(),
            "# Generated from Rust fn `foo` (lib.rs:_:_)"
        );
    }

    #[test]
    fn normalize_source_locs_multiple_attributions() {
        let input = concat!(
            "# (conversions.rs:1:5)\n",
            "foo <- function() {}\n",
            "# (conversions.rs:158:8)\n",
            "bar <- function() {}\n",
        );
        let result = normalize_source_locs(input);
        assert_eq!(
            result.as_ref(),
            concat!(
                "# (conversions.rs:_:_)\n",
                "foo <- function() {}\n",
                "# (conversions.rs:_:_)\n",
                "bar <- function() {}\n",
            )
        );
    }

    #[test]
    fn normalize_source_locs_does_not_match_extra_colon() {
        // `(lib.rs:1:5:6)` — four components — is NOT a valid attribution; leave alone.
        let input = "(lib.rs:1:5:6)";
        let result = normalize_source_locs(input);
        // The pattern `(lib.rs:1:5` matches, but then we expect `)` after the col
        // digits and find `:` instead — so it should NOT be replaced.
        assert_eq!(result.as_ref(), input);
    }

    #[test]
    fn normalize_source_locs_does_not_match_without_parens() {
        // Bare `lib.rs:1:5` without surrounding parens — leave untouched.
        let input = "lib.rs:1:5";
        let result = normalize_source_locs(input);
        assert_eq!(result.as_ref(), input);
        assert!(matches!(result, std::borrow::Cow::Borrowed(_)));
    }

    #[test]
    fn wrappers_semantically_equal_position_only_diff() {
        // Two wrappers identical except for line:col are semantically equal.
        let old = "# Generated from Rust fn `foo` (lib.rs:42:8)\nfoo <- function() {}\n";
        let new = "# Generated from Rust fn `foo` (lib.rs:99:8)\nfoo <- function() {}\n";
        assert!(wrappers_semantically_equal(old, new));
    }

    #[test]
    fn wrappers_semantically_equal_content_diff() {
        // A real semantic change (different function body) is NOT equal.
        let old = "# Generated from Rust fn `foo` (lib.rs:42:8)\nfoo <- function() { 1L }\n";
        let new = "# Generated from Rust fn `foo` (lib.rs:42:8)\nfoo <- function() { 2L }\n";
        assert!(!wrappers_semantically_equal(old, new));
    }

    #[test]
    fn wrappers_semantically_equal_both_position_and_content_diff() {
        // Both positions and content differ — still NOT equal.
        let old = "# Generated from Rust fn `foo` (lib.rs:1:1)\nfoo <- function() { 1L }\n";
        let new = "# Generated from Rust fn `bar` (lib.rs:9:1)\nbar <- function() { 2L }\n";
        assert!(!wrappers_semantically_equal(old, new));
    }

    // endregion

    // region: generic doc marker tests

    #[test]
    fn test_parse_generic_doc_marker_s7() {
        let marker = r#".__MX_GENERIC_DOC__(kind="S7", generic="get_value", class="MyClass", export=true, dispatch="x", no_dots=false)"#;
        let result = parse_generic_doc_marker(marker);
        assert!(result.is_some());
        let (kind, generic, class, export, dispatch, no_dots) = result.unwrap();
        assert_eq!(kind, "S7");
        assert_eq!(generic, "get_value");
        assert_eq!(class, "MyClass");
        assert!(export);
        assert_eq!(dispatch, "x");
        assert!(!no_dots);
    }

    #[test]
    fn test_parse_generic_doc_marker_s4() {
        let marker =
            r#".__MX_GENERIC_DOC__(kind="S4", generic="s4_get", class="Counter", export=true)"#;
        let result = parse_generic_doc_marker(marker);
        assert!(result.is_some());
        let (kind, generic, class, export, dispatch, no_dots) = result.unwrap();
        assert_eq!(kind, "S4");
        assert_eq!(generic, "s4_get");
        assert_eq!(class, "Counter");
        assert!(export);
        assert_eq!(dispatch, "x"); // default
        assert!(!no_dots); // default
    }

    #[test]
    fn test_resolve_generic_doc_markers_single_class() {
        let input = concat!(
            r#".__MX_GENERIC_DOC__(kind="S7", generic="get_value", class="MyClass", export=true, dispatch="x", no_dots=false)"#,
            "\n",
            "if (!exists(\"get_value\", mode = \"function\")) {\n",
            "  get_value <- S7::new_generic(\"get_value\", \"x\", function(x, ...) S7::S7_dispatch())\n",
            "}\n",
        );
        let output = resolve_generic_doc_markers(input.to_string());

        // Marker must be gone
        assert!(!output.contains(".__MX_GENERIC_DOC__"));
        // Standalone page must have bare @name
        assert!(output.contains("#' @name get_value"));
        // Must list the class
        assert!(output.contains("\\link{MyClass}"));
        // Must have NULL anchor
        assert!(output.contains("\nNULL\n"));
        // Generic guard must survive
        assert!(output.contains("if (!exists(\"get_value\""));
    }

    #[test]
    fn test_resolve_generic_doc_markers_two_classes_one_generic() {
        // Two classes sharing one generic: both appear in the listing, only one doc page.
        let input = concat!(
            r#".__MX_GENERIC_DOC__(kind="S7", generic="get_value", class="ClassA", export=true, dispatch="x", no_dots=false)"#,
            "\n",
            "line_a\n",
            r#".__MX_GENERIC_DOC__(kind="S7", generic="get_value", class="ClassB", export=true, dispatch="x", no_dots=false)"#,
            "\n",
            "line_b\n",
        );
        let output = resolve_generic_doc_markers(input.to_string());

        // No markers remain
        assert!(!output.contains(".__MX_GENERIC_DOC__"));
        // Only one @name line
        let name_count = output.matches("#' @name get_value").count();
        assert_eq!(
            name_count, 1,
            "expected exactly one @name get_value, got {name_count}"
        );
        // Both classes listed
        assert!(output.contains("\\link{ClassA}"));
        assert!(output.contains("\\link{ClassB}"));
        // Other lines survive
        assert!(output.contains("line_a"));
        assert!(output.contains("line_b"));
    }

    #[test]
    fn test_resolve_generic_doc_markers_external_generic_excluded() {
        // External generics (has_generic_override) do NOT emit markers.
        // Verify that content without any markers passes through unchanged.
        let input = "if (!exists(\"size\", mode = \"function\")) {\n  size <- S7::new_external_generic(\"vctrs\", \"size\")\n}\n";
        let output = resolve_generic_doc_markers(input.to_string());
        // Content should be identical (the line-by-line reconstruction adds \n)
        let output_trimmed: Vec<&str> = output.lines().collect();
        let input_trimmed: Vec<&str> = input.lines().collect();
        assert_eq!(output_trimmed, input_trimmed);
    }

    #[test]
    fn test_resolve_generic_doc_markers_no_dots() {
        let input = concat!(
            r#".__MX_GENERIC_DOC__(kind="S7", generic="strict_fn", class="A", export=true, dispatch="x", no_dots=true)"#,
            "\n",
        );
        let output = resolve_generic_doc_markers(input.to_string());
        // no_dots=true → @param ... must NOT appear in the standalone block
        assert!(!output.contains("@param ..."));
        // @param x must appear
        assert!(output.contains("@param x"));
    }

    #[test]
    fn test_resolve_generic_doc_markers_s4() {
        let input = concat!(
            r#".__MX_GENERIC_DOC__(kind="S4", generic="s4_compute", class="S4Counter", export=true)"#,
            "\n",
            "if (!methods::isGeneric(\"s4_compute\")) methods::setGeneric(\"s4_compute\", function(x, ...) standardGeneric(\"s4_compute\"))\n",
        );
        let output = resolve_generic_doc_markers(input.to_string());
        assert!(!output.contains(".__MX_GENERIC_DOC__"));
        assert!(output.contains("#' @name s4_compute"));
        assert!(output.contains("an S4 generic"));
        assert!(output.contains("\\link{S4Counter}"));
        // S4 export uses @exportMethod
        assert!(output.contains("#' @exportMethod s4_compute"));
        // setGeneric guard must survive
        assert!(output.contains("if (!methods::isGeneric(\"s4_compute\")"));
    }

    // endregion

    // region: duplicate wrapper-definition detection (#991)

    /// Build an accessor-producer map the way `write_r_wrappers_to_file` does,
    /// from synthetic sidecar + class registries, for unit testing.
    fn accessor_map(
        sidecar: &[SidecarPropEntry],
        classes: &[ClassNameEntry],
    ) -> std::collections::HashMap<String, String> {
        let class_index: std::collections::HashMap<&str, &ClassNameEntry> =
            classes.iter().map(|e| (e.rust_type, e)).collect();
        sidecar_accessor_names(sidecar, &class_index)
    }

    #[test]
    fn parse_top_level_fn_def_name_accepts_bare_def() {
        assert_eq!(
            parse_top_level_fn_def_name("Foo_get_value <- function(x) .Call(C, x)"),
            Some("Foo_get_value")
        );
        // Dotted/internal helper names are valid R identifiers.
        assert_eq!(
            parse_top_level_fn_def_name(".miniextendr_raise_condition <- function(.val) {"),
            Some(".miniextendr_raise_condition")
        );
    }

    #[test]
    fn parse_top_level_fn_def_name_rejects_non_defs() {
        // Indented closures (R6 methods, S7 getters) are not top-level wrappers.
        assert_eq!(
            parse_top_level_fn_def_name("    get_value = function(self) self$x"),
            None
        );
        // S7::method(...) <- function : LHS is a call, not a bare ident.
        assert_eq!(
            parse_top_level_fn_def_name("S7::method(get_value, Shape) <- function(x) .Call(C, x)"),
            None
        );
        // `$`-assignment target is not a bare ident.
        assert_eq!(
            parse_top_level_fn_def_name("obj$method <- function() {}"),
            None
        );
        // Not a function definition at all.
        assert_eq!(parse_top_level_fn_def_name("x <- 1L"), None);
        // Comment / arbitrary line.
        assert_eq!(parse_top_level_fn_def_name("# a comment"), None);
    }

    #[test]
    fn detect_duplicate_clean_content_passes() {
        // A sidecar accessor and an unrelated S7 shortcut: distinct names, no clash.
        let content = concat!(
            "Shape_get_area <- function(x) .Call(C_get, x)\n",
            "Shape_set_area <- function(x, value) { .Call(C_set, x, value); invisible(x) }\n",
            "Shape_describe <- function(x, ...) .Call(C_describe, x)\n",
        );
        let map = accessor_map(
            &[SidecarPropEntry {
                rust_type: "Shape",
                field_name: "area",
                prop_doc: "",
            }],
            &[ClassNameEntry {
                rust_type: "Shape",
                r_class_name: "Shape",
                class_system: "s7",
            }],
        );
        assert!(detect_duplicate_wrapper_defs(content, &map).is_ok());
    }

    #[test]
    fn detect_duplicate_shortcut_vs_sidecar_accessor_fails() {
        // S7 method `get_area` emits `Shape_get_area`, colliding with the sidecar
        // accessor for field `area`. This is the core #991 case.
        let content = concat!(
            "Shape_get_area <- function(x) .Call(C_get, x)\n",
            "Shape_set_area <- function(x, value) { .Call(C_set, x, value); invisible(x) }\n",
            "Shape_get_area <- function(x, ...) .Call(C_method, x)\n",
        );
        let map = accessor_map(
            &[SidecarPropEntry {
                rust_type: "Shape",
                field_name: "area",
                prop_doc: "",
            }],
            &[ClassNameEntry {
                rust_type: "Shape",
                r_class_name: "Shape",
                class_system: "s7",
            }],
        );
        let err = detect_duplicate_wrapper_defs(content, &map).unwrap_err();
        assert!(err.contains("Shape_get_area"), "msg: {err}");
        // Message must name the sidecar producer and the field.
        assert!(err.contains("sidecar field `area`"), "msg: {err}");
        assert!(err.contains("Shape"), "msg: {err}");
    }

    #[test]
    fn detect_duplicate_honours_class_override_prefix() {
        // The impl block set `class = "Shape"` on Rust type `S7Shape`, so the
        // sidecar accessor is `Shape_get_area`, not `S7Shape_get_area`. The
        // collision must be attributed via the override prefix.
        let content = concat!(
            "Shape_get_area <- function(x) .Call(C_get, x)\n",
            "Shape_get_area <- function(x, ...) .Call(C_method, x)\n",
        );
        let map = accessor_map(
            &[SidecarPropEntry {
                rust_type: "S7Shape",
                field_name: "area",
                prop_doc: "",
            }],
            &[ClassNameEntry {
                rust_type: "S7Shape",
                r_class_name: "Shape",
                class_system: "s7",
            }],
        );
        let err = detect_duplicate_wrapper_defs(content, &map).unwrap_err();
        assert!(err.contains("Shape_get_area"), "msg: {err}");
        assert!(err.contains("sidecar field `area`"), "msg: {err}");
    }

    #[test]
    fn detect_duplicate_cross_impl_block_generic_message() {
        // Two S7 impl blocks both emit `Counter_inc` -- no sidecar involved, so
        // the generic "more than once" message is used.
        let content = concat!(
            "Counter_inc <- function(x, ...) .Call(C_inc_a, x)\n",
            "Counter_inc <- function(x, ...) .Call(C_inc_b, x)\n",
        );
        let map = std::collections::HashMap::new();
        let err = detect_duplicate_wrapper_defs(content, &map).unwrap_err();
        assert!(err.contains("Counter_inc"), "msg: {err}");
        assert!(err.contains("defined more than once"), "msg: {err}");
    }

    #[test]
    fn detect_duplicate_ignores_repeated_s7_method_assignments() {
        // `S7::method(...) <- function` lines are NOT top-level bare defs; a class
        // may legitimately have many method assignments. These must never trip.
        let content = concat!(
            "S7::method(describe, Shape) <- function(x) .Call(C1, x)\n",
            "S7::method(area, Shape) <- function(x) .Call(C2, x)\n",
            "S7::method(describe, Circle) <- function(x) .Call(C3, x)\n",
        );
        let map = std::collections::HashMap::new();
        assert!(detect_duplicate_wrapper_defs(content, &map).is_ok());
    }

    // endregion
}
// endregion