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::ffi::{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 cdylib 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 {}

/// 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 cdylib wrapper generation)
    //
    // During wrapper-gen, the cdylib is loaded temporarily via dyn.load() then
    // unloaded via dyn.unload(). ALTREP class registration creates R-global entries
    // with method pointers into the cdylib code. After dyn.unload(), those pointers
    // become dangling. When the staticlib later re-registers, R may still have the
    // stale entries, leading to heap corruption (e.g., "malloc(): unsorted double
    // linked list corrupted" on Linux).
    let wrapper_gen = std::env::var_os("MINIEXTENDR_CDYLIB_WRAPPERS").is_some();
    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 cdylib 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::ffi::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 cdylib 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

/// Write all R wrapper entries to a file.
///
/// Called from [`miniextendr_write_wrappers`] (via cdylib `dyn.load`/`.Call`).
/// All distributed_slice entries from `#[miniextendr]` items are available
/// because the cdylib includes all symbols by design.
///
/// 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
  switch(.val$kind,
    error = stop(structure(list(message = .msg, call = .call, kind = \"error\"),
      class = c(.class, \"rust_error\", \"simpleError\", \"error\", \"condition\"))),
    warning = warning(structure(list(message = .msg, call = .call, kind = \"warning\"),
      class = c(.class, \"rust_warning\", \"simpleWarning\", \"warning\", \"condition\"))),
    message = message(structure(list(message = paste0(.msg, \"\\n\"), call = NULL, kind = \"message\"),
      class = c(.class, \"rust_message\", \"simpleMessage\", \"message\", \"condition\"))),
    condition = signalCondition(structure(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.
    {
        use std::collections::HashMap;
        let class_index: HashMap<&'static str, &ClassNameEntry> =
            MX_CLASS_NAMES.iter().map(|e| (e.rust_type, e)).collect();

        // 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;
    }

    // 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;
    }

    std::fs::write(path, content.as_bytes())
        .unwrap_or_else(|e| panic!("failed to write {path}: {e}"));

    if !existing.is_empty() {
        let filename = std::path::Path::new(path)
            .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.
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).
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`.
#[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`.
#[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).
#[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: C-Callable Entry Points (cdylib)
//
// All cdylib wrapper-gen entry points are host-only — wasm32 builds skip
// them (the cdylib 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 via cdylib.
///
/// Called from Makevars via Rscript: loads the cdylib 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::ffi::SEXP,
) -> crate::ffi::SEXP {
    unsafe {
        use crate::ffi::{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 via cdylib.
///
/// Pairs with [`miniextendr_write_wrappers`]: same cdylib, 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::ffi::SEXP,
) -> crate::ffi::SEXP {
    unsafe {
        use crate::ffi::{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 {
        use std::collections::HashMap;
        let class_index: HashMap<&str, &ClassNameEntry> =
            entries.iter().map(|e| (e.rust_type, e)).collect();

        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
    }

    #[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");
    }

    // 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
}
// endregion