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`]
//! 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 host-only slices (MX_R_WRAPPERS,
// MX_MATCH_ARG_*, MX_CLASS_NAMES, MX_CLASS_BLOCKS, 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-unwind" { 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];

/// The R class parts of every `#[miniextendr(env|r6|s3|s4|s7|vctrs)]` impl
/// block. **Host-only.**
///
/// [`collect_r_wrappers`] merges the blocks of each Rust type into one class
/// fragment: the class is defined once and every block's members attach to it
/// (#1776).
#[cfg(not(target_arch = "wasm32"))]
#[distributed_slice]
pub static MX_CLASS_BLOCKS: [ClassBlockEntry];

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

/// The standalone sidecar accessors of each `#[derive(ExternalPtr)]` type
/// with public `#[r_data]` fields. **Host-only.** [`collect_r_wrappers`]
/// writes each as exported or internal, from the type's
/// [`ClassNameEntry::field_syntax`] (#1900).
#[cfg(not(target_arch = "wasm32"))]
#[distributed_slice]
pub static MX_SIDECAR_ACCESSORS: [SidecarAccessorsEntry];

/// The `all.equal()` methods `#[derive(AllEqual)]` generates (#2149).
/// **Host-only.** [`collect_r_wrappers`] names and registers each for the
/// type's R class, which the type's impl block gives in its
/// [`ClassNameEntry`]: the derive sits on the struct, a separate expansion.
#[cfg(not(target_arch = "wasm32"))]
#[distributed_slice]
pub static MX_ALL_EQUAL: [AllEqualEntry];

/// The `pkg::name` items of every `reexport!` (#1910). **Host-only.**
/// [`collect_r_wrappers`] writes roxygen2's re-export block for each
/// `pkg::name` once, however many items name it, and
/// [`write_r_wrappers_to_file`] refuses a name re-exported from two packages
/// or bound by the package's own wrappers (`reexport_conflicts`).
#[cfg(not(target_arch = "wasm32"))]
#[distributed_slice]
pub static MX_REEXPORTS: [ReexportEntry];

/// The package crate's `conversion_error_class`. **Host-only.**
///
/// `miniextendr_init!` emits one entry, with the classes it reads from the
/// crate's `[package.metadata.miniextendr]` (empty when unset). During
/// `write_r_wrappers_to_file` it becomes `.miniextendr_conversion_error_class`,
/// the classes `.miniextendr_arg_error` gives every R-side argument error, so
/// they match the ones the macro emits into the Rust conversion arms (#1591).
#[cfg(not(target_arch = "wasm32"))]
#[distributed_slice]
pub static MX_CONVERSION_ERROR_CLASS: [ConversionErrorClassEntry];

// 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()
    }
}

/// The package crate's `conversion_error_class` (empty when it sets none).
///
/// Native: the [`MX_CONVERSION_ERROR_CLASS`] entry `miniextendr_init!`
/// registers (a package has one). wasm32: the copy the `wasm_registry.rs`
/// snapshot carries, installed by `install_wasm_runtime_slices`.
#[inline]
pub(crate) fn conversion_error_class() -> &'static [&'static str] {
    #[cfg(not(target_arch = "wasm32"))]
    {
        MX_CONVERSION_ERROR_CLASS
            .first()
            .map_or(&[][..], |entry| entry.classes)
    }
    #[cfg(target_arch = "wasm32")]
    {
        wasm_runtime::conversion_error_class()
    }
}

#[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();
    static CONVERSION_ERROR_CLASS: OnceLock<&'static [&'static str]> = OnceLock::new();

    pub(super) fn install(
        c: &'static [R_CallMethodDef],
        a: &'static [AltrepRegistration],
        t: &'static [TraitDispatchEntry],
        k: &'static [&'static str],
    ) {
        // 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);
        let _ = CONVERSION_ERROR_CLASS.set(k);
    }

    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(&[])
    }
    pub(super) fn conversion_error_class() -> &'static [&'static str] {
        CONVERSION_ERROR_CLASS.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`].
/// `conversion_error_class` is the crate's `conversion_error_class` from the
/// same snapshot, which the raising guards give an `arg_error!` (#1768).
///
/// 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],
    conversion_error_class: &'static [&'static str],
) {
    wasm_runtime::install(
        call_defs,
        altrep_regs,
        trait_dispatch,
        conversion_error_class,
    );
}

// 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,
    /// The re-export blocks of `reexport!` (#1910). They bind nothing, so
    /// their place is free; last keeps them together.
    Reexport,
}

/// 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,
    /// Line the generating item starts on in `source_file`. Together with the
    /// file it fixes the emission order within a priority group at source
    /// order, so the blocks merged onto a shared `.Rd` page read as written
    /// rather than in link order (#1476).
    pub source_line: u32,
}

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

/// The package crate's `conversion_error_class`, registered by
/// `miniextendr_init!` in [`MX_CONVERSION_ERROR_CLASS`].
pub struct ConversionErrorClassEntry {
    /// The classes, most specific first; empty when the crate sets none.
    pub classes: &'static [&'static str],
}

/// 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,
    /// The parameter type's `MatchArg::CHOICES`, unescaped.
    pub choices: &'static [&'static str],
    /// User-supplied `default = "..."` value (unquoted, e.g. `"zstd"`), or `""`
    /// if the user did not supply one. When non-empty, the write-time pass
    /// moves this choice to the front of the formal ([`match_arg_formal`]),
    /// so `.miniextendr_match_arg()` picks it for `NULL` and for the omitted
    /// argument.
    pub preferred_default: &'static str,
    /// Placeholder for the trailing `aliases =` (and `listed =`) arguments
    /// of the parameter's `.miniextendr_match_arg` /
    /// `.miniextendr_match_arg_several` call, e.g.
    /// `".__MX_MATCH_ARG_ALIASES_run_mode__"`. The writer replaces `, ` and
    /// it with [`match_arg_aliases_arg`]: nothing for a type without aliases.
    pub aliases_placeholder: &'static str,
    /// The parameter type's `MatchArg::ALIASES`, unescaped.
    pub aliases: &'static [crate::match_arg::MatchArgAlias],
}

/// 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,
    /// Text after the rendered choice list, before the closing period:
    /// `""` for a plain param, `", or NULL for no choice"` for an `Option<T>`
    /// one (#1473), an omission note for `Missing<T>` (#1551). Composed by
    /// the macro from the parameter type.
    pub suffix: &'static str,
    /// Function that returns the choices as a comma-separated quoted string,
    /// e.g. `"\"Fast\", \"Safe\", \"Debug\""`.
    pub choices_str: fn() -> String,
}

// SAFETY: function pointer, bools, 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,
    /// The impl block gives the class `$` / `[[` field syntax for the type's
    /// `#[r_data]` fields (`s3(r_data_accessors)`, `s4(...)`, `env(...)`).
    /// The type's standalone `Type_get_f()` / `Type_set_f()` are then
    /// written without an export or a page ([`SidecarAccessorsEntry`],
    /// #1900).
    pub field_syntax: bool,
}

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

/// The line of [`ClassBlockEntry::head`] where the class's roxygen block
/// takes the [`ClassBlockEntry::class_doc_lines`] of every impl block of the
/// type. Spelled the same as `miniextendr_macros`'s `CLASS_DOC_LINES_MARKER`.
pub const CLASS_DOC_LINES_MARKER: &str = ".__MX_CLASS_DOC_LINES__";

/// The line of [`ClassBlockEntry::head`] where the class's roxygen block
/// takes the [`ClassBlockEntry::class_docs`] of every impl block of the
/// type, the defining block's first. Spelled the same as
/// `miniextendr_macros`'s `CLASS_DOCS_MARKER`.
pub const CLASS_DOCS_MARKER: &str = ".__MX_CLASS_DOCS__";

/// Opens a class's roxygen block, in [`ClassBlockEntry::head`], that only
/// carries the impl docs: the block of an S3 or vctrs class without a
/// constructor that the package names and builds itself (`class = "..."`).
/// The writer writes the block, up to its closing `NULL`, only when the
/// type's [`class_docs`](ClassBlockEntry::class_docs) or
/// [`class_doc_lines`](ClassBlockEntry::class_doc_lines) say something beyond
/// the page and export tags, so a readers-only impl adds no page (#1918).
/// Spelled the same as `miniextendr_macros`'s `CLASS_DOCS_ONLY_MARKER`.
pub const CLASS_DOCS_ONLY_MARKER: &str = ".__MX_CLASS_DOCS_ONLY__";

/// Opens a generated line of a class's roxygen block, in
/// [`ClassBlockEntry::head`] or [`ClassBlockEntry::class_doc_lines`], that a
/// doc tag on another impl block of the type replaces: `@title`, `@name`,
/// `@rdname`, `@export`, a constructor's `@param` or an R6 `@field`. The
/// writer drops the line when another block's
/// [`class_docs`](ClassBlockEntry::class_docs) have the tag (for `@param` and
/// `@field`, for the same name), and otherwise writes it without the prefix.
/// Spelled the same as `miniextendr_macros`'s `CLASS_DEFAULT_PREFIX`.
pub const CLASS_DEFAULT_PREFIX: &str = ".__MX_CLASS_DEFAULT__";

/// Generated member page/parameter/prose defaults. The class assembler resolves
/// these against the defining impl's topic, preserving explicit member tags.
/// Spelled the same as the proc-macro's `CLASS_MEMBER_DEFAULT_PREFIX`.
pub const CLASS_MEMBER_DEFAULT_PREFIX: &str = ".__MX_CLASS_MEMBER_DEFAULT__";

/// One `#[miniextendr]` impl block's share of its Rust type's R class (#1776).
///
/// A type's methods may be split over several impl blocks. Each block
/// registers its R wrapper in parts, and [`collect_r_wrappers`] writes one
/// class per type: the defining block's [`head`](Self::head), every block's
/// [`members`](Self::members) in source order, then the defining block's
/// [`tail`](Self::tail). The defining block is the one with a
/// [`defines`](Self::defines) entry (at most one block may have any), else
/// the first in source order. The class's roxygen block has the
/// [`class_docs`](Self::class_docs) of every block, the defining block's
/// first. Every part is R source, framed by the newline the macro's raw
/// string literal adds at each end.
pub struct ClassBlockEntry {
    /// Rust type identifier as written in the impl, e.g. `"Counter"`.
    pub rust_type: &'static str,
    /// The type's `core::any::type_name`, which tells apart two types that
    /// share an identifier. The blocks of one type are merged by it.
    pub type_path: fn() -> &'static str,
    /// R-visible class name (`class = "..."`, else the type's identifier).
    pub r_class_name: &'static str,
    /// Source file of the impl block (`file!()`).
    pub source_file: &'static str,
    /// Line of the impl's type in `source_file`.
    pub source_line: u32,
    /// Column of the impl's type, for the `# Generated from` header.
    pub source_column: u32,
    /// The class-level settings, rendered: class system and its options,
    /// `class = "..."`, `internal` / `noexport`, and the `@noRd` /
    /// `@keywords internal` tags. They shape every block's members, so all
    /// blocks of a type must have the same.
    pub settings: &'static str,
    /// The Rust name of the block's class constructor, `""` when it has
    /// none: the method marked `#[miniextendr(<system>(constructor))]`, else a
    /// receiver-less `new` returning `Self`, else
    /// ([`constructor_inferred`](Self::constructor_inferred)) the block's one
    /// [candidate](Self::constructor_candidates).
    pub constructor: &'static str,
    /// Whether [`constructor`](Self::constructor) was inferred: the block
    /// declares none and has one candidate. The type's constructor is then
    /// decided across its impl blocks when [`collect_r_wrappers`] merges them.
    pub constructor_inferred: bool,
    /// The Rust names of the block's receiver-less methods returning `Self`
    /// other than a declared constructor: the methods that could be the
    /// constructor of a type that declares none.
    pub constructor_candidates: &'static [&'static str],
    /// The block as it reads when another impl block of the type declares
    /// the constructor: present when the block infers one, which there stays
    /// a static method.
    pub demoted: Option<&'static ClassBlockEntry>,
    /// What this block has that only the defining block may: `"a
    /// constructor"` (or `` "the inferred constructor `name`" ``), `"S7
    /// properties"`, `"the field fallback"` (`s3(r_data_accessors, fallback
    /// = ...)`, whose `.Call` entry the block emits and whose field methods
    /// call it).
    pub defines: &'static [&'static str],
    /// The class definition as this block would write it: the class's
    /// roxygen block (with the [`CLASS_DOCS_MARKER`] and
    /// [`CLASS_DOC_LINES_MARKER`] lines, and [`CLASS_DEFAULT_PREFIX`]
    /// lines), the class object, the constructor, and the class-level
    /// helpers.
    pub head: &'static str,
    /// The block's doc comment as roxygen lines (with the constructor's for
    /// S3 and vctrs, whose class block is the constructor's). The class's
    /// roxygen block has every block's, the defining block's first; a tag
    /// repeated exactly is written once, and two blocks giving the class
    /// different `@title`s, or a page other than the defining block's
    /// (`@name`, `@rdname`), are refused.
    pub class_docs: &'static str,
    /// Roxygen lines this block's members add to the class's roxygen block,
    /// such as an R6 active binding's `@field` or a lifecycle import.
    pub class_doc_lines: &'static str,
    /// The block's members: its methods, static methods and coercions.
    pub members: &'static str,
    /// Names the members bind in the class's own namespaces (`$name` of an
    /// env class or of an R6 generator, R6 members, S4 and S7 method
    /// registrations), for the check that two blocks don't bind the same one.
    /// Top-level functions are left to the duplicate-definition scan of the
    /// written file.
    pub member_names: &'static [&'static str],
    /// What follows every block's members, such as R6's `$lock()`.
    pub tail: &'static str,
}

// SAFETY: &'static str fields, a fn pointer, integers and a reference to
// another such entry — immutable and valid for program lifetime.
unsafe impl Sync for ClassBlockEntry {}

/// Implemented by `#[miniextendr]` for each type with an impl block that
/// declares its class constructor (`#[miniextendr(<system>(constructor))]`,
/// or a receiver-less `new` returning `Self`). `Block` is a type private to that
/// impl block, so two such blocks don't conflict here; the wrapper writer
/// refuses them ([`merge_class_blocks`]).
///
/// An impl block with several methods that could be the constructor and
/// none declared requires it ([`require_class_constructor`]): the type then
/// compiles only when another of its impl blocks declares the constructor.
#[doc(hidden)]
#[diagnostic::on_unimplemented(
    message = "`{Self}` has several methods that could be its constructor, and none is declared",
    label = "this method returns `Self` and takes no receiver, like another method of `{Self}`",
    note = "mark the constructor with the class system's `constructor` option, e.g. \
            `#[miniextendr(r6(constructor))]`, or name it `new`; the other methods stay static \
            factory methods"
)]
pub trait ClassConstructor<Block> {}

/// Compiles only when `T` has an impl block that declares its class
/// constructor ([`ClassConstructor`]). Never called.
#[doc(hidden)]
pub const fn require_class_constructor<T: ?Sized + ClassConstructor<Block>, Block>() {}

/// The standalone R accessors `#[derive(ExternalPtr)]` generates for a
/// type's public `#[r_data]` fields, `Type_get_f(x)` / `Type_set_f(x,
/// value)`, in two renderings: exported on a "Type Sidecar Accessors" page,
/// or internal (`@noRd`, no export). [`collect_r_wrappers`] writes the
/// internal one for a type whose class has field syntax
/// ([`ClassNameEntry::field_syntax`]): the class's `$` / `[[` are its R
/// interface to the fields there, and the setters would write in place
/// through every copy (#1900). The internal rendering also carries the field
/// helpers that those methods call. Written with the sidecar fragments.
pub struct SidecarAccessorsEntry {
    /// Rust type identifier, matched against [`ClassNameEntry::rust_type`].
    pub rust_type: &'static str,
    /// The page and the exported accessors.
    pub exported: &'static str,
    /// The same accessors with `@noRd` and no export, plus field-syntax helpers.
    pub internal: &'static str,
    /// Source file of the derive (`file!()`), for the fragment order.
    pub source_file: &'static str,
    /// Line of the derived type in `source_file`.
    pub source_line: u32,
}

// SAFETY: &'static str fields and a u32 — immutable and valid for program lifetime.
unsafe impl Sync for SidecarAccessorsEntry {}

/// The `all.equal()` method `#[derive(AllEqual)]` generates for a type
/// (#2149), without the parts that depend on the type's R class: its name,
/// its title and its registration, which [`collect_r_wrappers`] adds.
pub struct AllEqualEntry {
    /// Rust type identifier, matched against [`ClassNameEntry::rust_type`].
    pub rust_type: &'static str,
    /// The method, `function(target, current, ...) { ... }`.
    pub method: &'static str,
    /// The roxygen lines of the method's page after its title: the
    /// description, the arguments and the value.
    pub docs: &'static str,
    /// Source file of the derive (`file!()`).
    pub source_file: &'static str,
    /// Line of the derived type in `source_file`.
    pub source_line: u32,
    /// Column of the derived type, for the `# Generated from` header.
    pub source_column: u32,
}

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

/// One `pkg::name` item of a `reexport!` invocation (#1910): `name`, an
/// export of the R package `package`, which this package exports too.
/// The macro has checked both names.
pub struct ReexportEntry {
    /// The R package the name comes from, e.g. `"generics"`.
    pub package: &'static str,
    /// The re-exported name as R spells it, unquoted, e.g. `"tidy"` or
    /// `"%>%"`.
    pub name: &'static str,
    /// Source file of the invocation (`file!()`).
    pub source_file: &'static str,
    /// Line of the item in `source_file`.
    pub source_line: u32,
    /// Column of the item, for the `# Generated from` header.
    pub source_column: u32,
}

/// Build the `rust_type → ClassNameEntry` lookup used by every placeholder
/// resolver in `write_r_wrappers_to_file`.
///
/// Each `#[miniextendr]` impl block of a type registers a `ClassNameEntry`
/// (#1242, #1776) — 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 blocks with
/// disagreeing `class = "..."` overrides) panic: silently keeping
/// whichever entry linkme ordered last would resolve `.__MX_CLASS_REF_*__`
/// placeholders nondeterministically. `field_syntax` may differ between the
/// blocks ([`sidecar_accessor_fragments`] reads every entry). Distinct Rust
/// types must also have distinct R class names: otherwise their class bindings
/// and generated methods overwrite each other when the package loads (#1677).
///
/// 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();
    let mut r_class_names = 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,
                    );
                }
            }
        }
        if let Some(prev) = r_class_names.insert(e.r_class_name, e) {
            assert!(
                prev.rust_type == e.rust_type,
                "R class `{}` is registered for both Rust type `{}` ({}) and `{}` ({}). \
                 Distinct Rust types must use distinct R class names; change one \
                 `class = \"...\"` override to avoid overwriting its class and methods.",
                e.r_class_name,
                prev.rust_type,
                prev.class_system,
                e.rust_type,
                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_mypkg_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 inside the package-init unwind boundary.
    pub register: extern "C-unwind" fn(),
    /// Symbol name of `register` (e.g. `"__mx_altrep_reg_MyType"`). Consumed by
    /// the host-time WASM snapshot writer to emit `extern "C-unwind" { 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-unwind" 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
    // R copies every entry into the DLL's own table (`R_addCallRoutine`
    // strdups the name and stores the function pointer), so `call_defs` is
    // freed on return. Leaking it showed up as ~114 KB "definitely lost" per
    // load under Valgrind.
    unsafe {
        crate::sys::R_registerRoutines_unchecked(
            dll,
            std::ptr::null(),
            call_defs.as_ptr(),
            std::ptr::null(),
            std::ptr::null(),
        );
    }
}

/// The standalone sidecar accessors as sidecar fragments: each type's
/// internal rendering when one of its impl blocks gives its class field
/// syntax, else the exported one (#1900).
#[cfg(not(target_arch = "wasm32"))]
fn sidecar_accessor_fragments(
    accessors: &[SidecarAccessorsEntry],
    classes: &[ClassNameEntry],
) -> Vec<WrapperFragment> {
    accessors
        .iter()
        .map(|entry| {
            let field_syntax = classes
                .iter()
                .any(|class| class.rust_type == entry.rust_type && class.field_syntax);
            WrapperFragment {
                priority: RWrapperPriority::Sidecar,
                content: std::borrow::Cow::Borrowed(if field_syntax {
                    entry.internal
                } else {
                    entry.exported
                }),
                source_file: entry.source_file,
                source_line: entry.source_line,
            }
        })
        .collect()
}

/// The `all.equal()` methods of `#[derive(AllEqual)]` as fragments (#2149):
/// each named `all.equal.<Class>` for the R class of the type's
/// [`ClassNameEntry`], on its own page, and registered with
/// `S3method(all.equal, <Class>)`, which an env, R6, S3 or S4 object
/// dispatches on (S4 through R's S3 dispatch on the S4 class, which also
/// reaches callers of `base::all.equal()` such as testthat, where an S4
/// method would not). An S7 object's class attribute is `pkg::Class`, so an
/// S7 class also registers the method with `S7::method(all.equal, Class)`,
/// followed by the unbinding every such replacement call on a base generic
/// needs (see `miniextendr_macros`'s `s7_base_operator_unbind`).
///
/// The fragments are written with the trait impls, after every class
/// definition, which the S7 registration names.
///
/// Every problem is collected into one message: a type no impl block gives
/// an R class, and a vctrs class, whose objects are R vectors with no pointer
/// to the Rust value.
#[cfg(not(target_arch = "wasm32"))]
fn all_equal_fragments(
    entries: &[AllEqualEntry],
    classes: &[ClassNameEntry],
) -> Result<Vec<WrapperFragment>, String> {
    let index = build_class_name_index(classes);
    let mut errors = Vec::new();
    let mut fragments = Vec::new();
    for entry in entries {
        let derive = format!(
            "`#[derive(AllEqual)]` on `{}` ({}:{})",
            entry.rust_type, entry.source_file, entry.source_line
        );
        match index.get(entry.rust_type) {
            None => errors.push(format!(
                "{derive}: no `#[miniextendr(env | r6 | s3 | s4 | s7)]` impl block gives the \
                 type an R class, so there is no class to give the `all.equal()` method"
            )),
            Some(class) if class.class_system == "vctrs" => errors.push(format!(
                "{derive}: the objects of a vctrs class are R vectors, not pointers to the Rust \
                 value, and `all.equal()` already compares them"
            )),
            Some(class) => fragments.push(WrapperFragment {
                priority: RWrapperPriority::TraitImpl,
                source_file: entry.source_file,
                source_line: entry.source_line,
                content: std::borrow::Cow::Owned(all_equal_method(entry, class)),
            }),
        }
    }
    if errors.is_empty() {
        Ok(fragments)
    } else {
        Err(errors.join("\n"))
    }
}

/// The text of one `#[derive(AllEqual)]` method: see [`all_equal_fragments`].
#[cfg(not(target_arch = "wasm32"))]
fn all_equal_method(entry: &AllEqualEntry, class: &ClassNameEntry) -> String {
    let class_name = class.r_class_name;
    let method = format!("all.equal.{class_name}");
    // `all.equal.` makes the name start with a letter; a class name with
    // other characters than R's name characters needs backticks.
    let symbol = if class_name
        .bytes()
        .all(|c| c.is_ascii_alphanumeric() || c == b'.' || c == b'_')
    {
        method.clone()
    } else {
        format!("`{method}`")
    };
    let mut out = format!(
        "# Generated from Rust derive `AllEqual` on `{}` ({}:{}:{})\n\
         #' Compare two `{class_name}` objects\n\
         #'\n\
         {}\n\
         #' @method all.equal {class_name}\n\
         #' @export\n\
         {symbol} <- {}",
        entry.rust_type,
        entry.source_file,
        entry.source_line,
        entry.source_column,
        entry.docs.trim_matches('\n'),
        entry.method.trim_matches('\n'),
    );
    if class.class_system == "s7" {
        out.push_str(&format!(
            "\nS7::method(all.equal, {class_name}) <- {symbol}\nbase::rm(list = \"all.equal\")"
        ));
    }
    out
}

// region: re-exports (#1910)

/// The re-exports of every `reexport!` as one fragment, `None` without any:
/// for each `pkg::name`, roxygen2's re-export block
///
/// ```r
/// # Generated from Rust `reexport!` of `generics::tidy` (fits.rs:3:11)
/// #' @importFrom generics tidy
/// #' @export
/// generics::tidy
/// ```
///
/// from which roxygen2 writes `importFrom(generics,tidy)` and `export(tidy)`
/// to `NAMESPACE` and an alias to `man/reexports.Rd`. A `pkg::name` that
/// several items name is written once, its header listing their sites. The
/// blocks are sorted by package, then name.
///
/// A name re-exported from two packages gets a block for each here;
/// [`reexport_conflicts`] refuses it with the other problems once the file
/// is assembled.
#[cfg(not(target_arch = "wasm32"))]
fn reexport_fragment(entries: &[ReexportEntry]) -> Option<WrapperFragment> {
    let mut by_item: std::collections::BTreeMap<(&str, &str), Vec<&ReexportEntry>> =
        std::collections::BTreeMap::new();
    for entry in entries {
        by_item
            .entry((entry.package, entry.name))
            .or_default()
            .push(entry);
    }
    let first = *by_item.values().next()?.first()?;
    let blocks: Vec<String> = by_item
        .iter()
        .map(|((package, name), sites)| {
            let object = if is_syntactic_r_name(name) {
                format!("{package}::{name}")
            } else {
                format!("{package}::`{name}`")
            };
            format!(
                "# Generated from Rust `reexport!` of `{package}::{name}` {}\n\
                 #' @importFrom {package} {}\n\
                 #' @export\n\
                 {object}",
                reexport_sites(sites),
                r_namespace_name(name),
            )
        })
        .collect();
    Some(WrapperFragment {
        priority: RWrapperPriority::Reexport,
        source_file: first.source_file,
        source_line: first.source_line,
        content: std::borrow::Cow::Owned(blocks.join("\n\n")),
    })
}

/// The sites of `entries`, `(file.rs:line:column)` each, in source order.
#[cfg(not(target_arch = "wasm32"))]
fn reexport_sites(entries: &[&ReexportEntry]) -> String {
    let mut sites: Vec<(&str, u32, u32)> = entries
        .iter()
        .map(|entry| (entry.source_file, entry.source_line, entry.source_column))
        .collect();
    sites.sort_unstable();
    sites.dedup();
    sites
        .iter()
        .map(|(file, line, column)| format!("({file}:{line}:{column})"))
        .collect::<Vec<_>>()
        .join(" ")
}

/// Refuse the re-exports of `entries` that can't be written, all in one
/// message: a name re-exported from two packages (a package exports one
/// object under a name), and a name that `content`, the assembled wrappers,
/// also binds at top level or exports. The package's own binding would hide
/// the imported one inside its namespace, so `export(name)` would export it
/// instead; an export alone repeats the one the re-export writes.
///
/// Only the generated wrappers are read, not the package's hand-written R
/// files.
#[cfg(not(target_arch = "wasm32"))]
fn reexport_conflicts(content: &str, entries: &[ReexportEntry]) -> Result<(), String> {
    use std::collections::BTreeMap;
    let mut by_name: BTreeMap<&str, BTreeMap<&str, Vec<&ReexportEntry>>> = BTreeMap::new();
    for entry in entries {
        by_name
            .entry(entry.name)
            .or_default()
            .entry(entry.package)
            .or_default()
            .push(entry);
    }
    if by_name.is_empty() {
        return Ok(());
    }
    let reexports = |name: &str, packages: &BTreeMap<&str, Vec<&ReexportEntry>>| {
        packages
            .iter()
            .map(|(package, sites)| format!("`{package}::{name}` {}", reexport_sites(sites)))
            .collect::<Vec<_>>()
            .join(", ")
    };

    let mut errors = Vec::new();
    for (name, packages) in &by_name {
        if packages.len() > 1 {
            errors.push(format!(
                "`reexport!` re-exports `{name}` from {} packages: {}. A package exports one \
                 object under a name; re-export it from one of them.",
                packages.len(),
                reexports(name, packages),
            ));
        }
    }

    // Each fragment that binds or exports a re-exported name, once, by its
    // binding when it both binds and exports it.
    let mut own: BTreeMap<&str, Vec<(&'static str, std::rc::Rc<str>)>> = BTreeMap::new();
    for WrapperName {
        name,
        kind,
        producer,
    } in wrapper_names(content)
    {
        if !by_name.contains_key(name) {
            continue;
        }
        let uses = own.entry(name).or_default();
        match uses.iter_mut().find(|(_, other)| *other == producer) {
            Some(used) if used.0 == "export" => used.0 = kind,
            Some(_) => {}
            None => uses.push((kind, producer)),
        }
    }
    for (name, uses) in own {
        let binds = uses.iter().any(|(kind, _)| *kind != "export");
        let what = uses
            .iter()
            .map(|(kind, producer)| {
                if *kind == "export" {
                    format!("an export from {producer}")
                } else {
                    format!("a {kind} from {producer}")
                }
            })
            .collect::<Vec<_>>()
            .join(", ");
        let (does, why) = if binds {
            (
                "bind",
                format!(
                    "The package's own `{name}` would hide the imported one in its namespace, \
                     so `export({name})` would export it instead. Remove the re-export, or \
                     rename the package's binding (`r_name = \"...\"`, `class = \"...\"`)."
                ),
            )
        } else {
            (
                "export",
                "`reexport!` writes the export itself; drop the other one.".to_string(),
            )
        };
        errors.push(format!(
            "`reexport!` re-exports {}, and the package's wrappers also {does} `{name}` ({what}). \
             {why}",
            reexports(name, &by_name[name]),
        ));
    }

    if errors.is_empty() {
        Ok(())
    } else {
        Err(errors
            .iter()
            .map(|error| format!("miniextendr: {error}"))
            .collect::<Vec<_>>()
            .join("\n"))
    }
}

// endregion

// region: impl blocks merged per type (#1776)

/// A wrapper fragment to write: an [`RWrapperEntry`]'s text, or a fragment
/// assembled at write time (a class merged from its impl blocks, a type's
/// sidecar accessors).
#[cfg(not(target_arch = "wasm32"))]
struct WrapperFragment {
    priority: RWrapperPriority,
    source_file: &'static str,
    source_line: u32,
    content: std::borrow::Cow<'static, str>,
}

#[cfg(not(target_arch = "wasm32"))]
impl From<&RWrapperEntry> for WrapperFragment {
    fn from(entry: &RWrapperEntry) -> Self {
        WrapperFragment {
            priority: entry.priority,
            source_file: entry.source_file,
            source_line: entry.source_line,
            content: std::borrow::Cow::Borrowed(entry.content),
        }
    }
}

/// A [`ClassBlockEntry`] part without the newline its raw string literal
/// adds at each end.
#[cfg(not(target_arch = "wasm32"))]
fn class_part(part: &str) -> &str {
    let part = part.strip_prefix('\n').unwrap_or(part);
    part.strip_suffix('\n').unwrap_or(part)
}

/// How a merge error names an impl block: `` `impl Counter` (lib.rs:12) ``.
#[cfg(not(target_arch = "wasm32"))]
fn class_block_name(block: &ClassBlockEntry) -> String {
    format!(
        "`impl {}` ({}:{})",
        block.rust_type, block.source_file, block.source_line
    )
}

/// Merge the impl blocks of each Rust type into one class fragment (#1776).
///
/// Blocks are grouped by [`ClassBlockEntry::type_path`] and taken in source
/// order. A type's fragment is the defining block's head, with the
/// `class_docs` of every block (the defining block's first) at its
/// [`CLASS_DOCS_MARKER`] line and the `class_doc_lines` of every block at its
/// [`CLASS_DOC_LINES_MARKER`] line, then each block's members, then the
/// defining block's tail. A tag repeated exactly is written once, and a
/// generated [`CLASS_DEFAULT_PREFIX`] line gives way to the same tag on
/// another block. A `# Generated from Rust impl` header precedes each
/// part whose block differs from the previous part's, so the
/// duplicate-definition scan of the written file
/// ([`detect_duplicate_wrapper_defs`]) names the block a definition comes from.
///
/// Every problem is collected into one message:
///
/// - two Rust types claim one R class name: their class objects and methods
///   would overwrite each other when the package loads (#1677);
/// - the blocks of a type disagree on the class settings
///   ([`ClassBlockEntry::settings`]), which shape every block's members;
/// - two blocks of a type each have something only the defining block may
///   have ([`ClassBlockEntry::defines`]);
/// - the doc comments of a type's blocks give the class two titles, or a
///   page other than the defining block's ([`class_doc_conflicts`]);
/// - two blocks of a type bind the same member name
///   ([`ClassBlockEntry::member_names`]), the later replacing the earlier;
/// - a type without a declared constructor has several methods that could be
///   one ([`resolve_class_constructor`], which first picks each block's
///   rendering).
#[cfg(not(target_arch = "wasm32"))]
fn merge_class_blocks(blocks: &[ClassBlockEntry]) -> Result<Vec<WrapperFragment>, String> {
    use std::collections::HashMap;

    let mut ordered: Vec<&ClassBlockEntry> = blocks.iter().collect();
    ordered.sort_by_key(|b| (b.source_file, b.source_line, b.source_column));

    // The blocks of each type, in source order; types in order of their first block.
    let mut types: Vec<(&'static str, Vec<&ClassBlockEntry>)> = Vec::new();
    let mut type_index: HashMap<&'static str, usize> = HashMap::new();
    for block in ordered {
        let path = (block.type_path)();
        let i = *type_index.entry(path).or_insert_with(|| {
            types.push((path, Vec::new()));
            types.len() - 1
        });
        types[i].1.push(block);
    }

    let mut errors: Vec<String> = Vec::new();

    // One Rust type per R class name.
    let mut class_owner: HashMap<&'static str, (&'static str, &ClassBlockEntry)> = HashMap::new();
    for (path, type_blocks) in &types {
        for block in type_blocks {
            match class_owner.get(block.r_class_name) {
                Some(&(owner, first)) if owner != *path => {
                    errors.push(format!(
                        "miniextendr: R class `{}` is claimed by two Rust types, `{owner}` \
                         ({}) and `{path}` ({}). Their class objects and methods would \
                         overwrite each other when the package loads; give one a distinct \
                         `class = \"...\"`.",
                        block.r_class_name,
                        class_block_name(first),
                        class_block_name(block),
                    ));
                }
                Some(_) => {}
                None => {
                    class_owner.insert(block.r_class_name, (path, block));
                }
            }
        }
    }

    let mut fragments = Vec::with_capacity(types.len());
    for (_, type_blocks) in &types {
        let type_blocks = match resolve_class_constructor(type_blocks) {
            Ok(blocks) => blocks,
            Err(error) => {
                errors.push(error);
                continue;
            }
        };
        let first = type_blocks[0];
        let type_errors = errors.len();

        for block in &type_blocks[1..] {
            if block.settings != first.settings {
                errors.push(format!(
                    "miniextendr: the impl blocks of `{}` disagree on the class settings: \
                     `{}` on {}, `{}` on {}. The blocks are merged into one class, and \
                     these settings shape every block's methods: spell the same class \
                     system and options, `class = \"...\"`, `internal` / `noexport` and \
                     `@noRd` / `@keywords internal` on each block (#1776).",
                    first.rust_type,
                    first.settings,
                    class_block_name(first),
                    block.settings,
                    class_block_name(block),
                ));
            }
        }

        let defining: Vec<&ClassBlockEntry> = type_blocks
            .iter()
            .copied()
            .filter(|b| !b.defines.is_empty())
            .collect();
        if let [a, b, ..] = defining.as_slice() {
            errors.push(format!(
                "miniextendr: two impl blocks of `{}` each define the class: {} has {}, \
                 {} has {}. A type's impl blocks merge into one class, and only one of \
                 them may have a constructor or S7 properties: move what {} has into \
                 {} (#1776).",
                first.rust_type,
                class_block_name(a),
                a.defines.join(" and "),
                class_block_name(b),
                b.defines.join(" and "),
                class_block_name(b),
                class_block_name(a),
            ));
        }

        let definer = defining.first().copied().unwrap_or(first);
        errors.extend(class_doc_conflicts(definer, &type_blocks));

        let mut members: HashMap<&str, &ClassBlockEntry> = HashMap::new();
        for &block in &type_blocks {
            for &name in block.member_names {
                match members.get(name) {
                    Some(&previous) if !std::ptr::eq(previous, block) => {
                        errors.push(format!(
                            "miniextendr: two impl blocks of `{}` define {name}: {} and {}. \
                             The later definition would replace the earlier one when the \
                             package loads; rename one with \
                             `#[miniextendr(r_name = \"...\")]` (#1776).",
                            first.rust_type,
                            class_block_name(previous),
                            class_block_name(block),
                        ));
                    }
                    Some(_) => {}
                    None => {
                        members.insert(name, block);
                    }
                }
            }
        }

        if errors.len() > type_errors {
            continue;
        }
        fragments.push(WrapperFragment {
            priority: RWrapperPriority::Class,
            source_file: first.source_file,
            source_line: first.source_line,
            content: std::borrow::Cow::Owned(merged_class_content(definer, &type_blocks)),
        });
    }

    if errors.is_empty() {
        Ok(fragments)
    } else {
        Err(errors.join("\n"))
    }
}

/// One roxygen tag of a class's docs: its `#'` lines, the first opening the
/// tag (`#' @name ...`), or the lines before the first tag. `default` marks a
/// generated line ([`CLASS_DEFAULT_PREFIX`], stripped from `lines`).
#[cfg(not(target_arch = "wasm32"))]
#[derive(Clone, PartialEq)]
struct DocTag<'a> {
    default: bool,
    lines: Vec<&'a str>,
}

#[cfg(not(target_arch = "wasm32"))]
impl<'a> DocTag<'a> {
    /// The tags of `text`, a run of roxygen lines: a tag runs from its
    /// `#' @tag` line to the next one, as roxygen2 reads it.
    fn parse(text: &'a str) -> Vec<Self> {
        let mut tags: Vec<Self> = Vec::new();
        for line in text.lines() {
            let (default, line) = match line.strip_prefix(CLASS_DEFAULT_PREFIX) {
                Some(line) => (true, line),
                None => (false, line),
            };
            match tags.last_mut() {
                Some(tag) if !default && !line.starts_with("#' @") => tag.lines.push(line),
                _ => tags.push(Self {
                    default,
                    lines: vec![line],
                }),
            }
        }
        tags
    }

    /// A head's generated default line, as a one-line tag; `None` for
    /// any other line.
    fn default_line(line: &'a str) -> Option<Self> {
        line.strip_prefix(CLASS_DEFAULT_PREFIX).map(|line| Self {
            default: true,
            lines: vec![line],
        })
    }

    /// The tag's name (`title` for `#' @title ...`), or `""` before the
    /// first tag.
    fn name(&self) -> &'a str {
        self.lines[0]
            .strip_prefix("#' @")
            .and_then(|rest| rest.split_whitespace().next())
            .unwrap_or("")
    }

    /// The tag's text after its name, continuation lines included.
    fn value(&self) -> String {
        let first = self.lines[0]
            .strip_prefix("#' @")
            .map_or("", |rest| rest.trim_start()[self.name().len()..].trim());
        let rest = self.lines[1..]
            .iter()
            .map(|line| line.strip_prefix("#'").unwrap_or(line).trim());
        std::iter::once(first)
            .chain(rest)
            .collect::<Vec<_>>()
            .join("\n")
            .trim()
            .to_string()
    }

    /// Whether this tag replaces the generated `default` (a tag of the same
    /// name; for `@param` and `@field`, naming the same argument or field,
    /// and `@inheritParams` for any `@param`).
    fn replaces(&self, default: &DocTag<'_>) -> bool {
        match default.name() {
            name @ ("param" | "field") => {
                let value = default.value();
                let arg = value.split_whitespace().next().unwrap_or("");
                (self.name() == name
                    && self
                        .value()
                        .split_whitespace()
                        .next()
                        .is_some_and(|names| names.split(',').any(|n| n.trim() == arg)))
                    || (name == "param" && self.name() == "inheritParams")
            }
            name => self.name() == name,
        }
    }
}

/// Every block's [`class_docs`](ClassBlockEntry::class_docs) as tags, the
/// defining block's first, then the others' in source order.
#[cfg(not(target_arch = "wasm32"))]
fn block_docs<'a>(
    definer: &'a ClassBlockEntry,
    blocks: &[&'a ClassBlockEntry],
) -> Vec<(&'a ClassBlockEntry, Vec<DocTag<'a>>)> {
    let others = blocks
        .iter()
        .copied()
        .filter(|b| !std::ptr::eq(*b, definer));
    std::iter::once(definer)
        .chain(others)
        .map(|b| (b, DocTag::parse(class_part(b.class_docs))))
        .collect()
}

/// The problems the doc comments of a type's impl blocks make for its merged
/// roxygen block (#1776): every block's doc tags are written, so two
/// different `@title`s give the class two titles (roxygen2 silently keeps
/// the first), and a `@name` or `@rdname` other than the defining block's
/// would move the class block to a page the defining block's generated
/// documentation was not written for.
#[cfg(not(target_arch = "wasm32"))]
fn class_doc_conflicts(definer: &ClassBlockEntry, blocks: &[&ClassBlockEntry]) -> Vec<String> {
    let mut errors = Vec::new();
    let docs = block_docs(definer, blocks);
    let tag_value =
        |tags: &[DocTag<'_>], name: &str| tags.iter().find(|t| t.name() == name).map(|t| t.value());

    let mut title: Option<(&ClassBlockEntry, String)> = None;
    for (block, tags) in &docs {
        let Some(value) = tag_value(tags, "title") else {
            continue;
        };
        match &title {
            None => title = Some((block, value)),
            Some((first, first_value)) if *first_value != value => {
                errors.push(format!(
                    "miniextendr: the impl blocks of `{}` give the class two titles: {} \
                     has `@title {first_value}`, {} has `@title {value}`. A type's impl \
                     blocks merge into one class with one help page: keep one `@title` \
                     (#1776).",
                    definer.rust_type,
                    class_block_name(first),
                    class_block_name(block),
                ));
                break;
            }
            Some(_) => {}
        }
    }

    // The page the defining block documents the class on: its own tag, else
    // the generated default.
    let head_defaults: Vec<DocTag<'_>> = class_part(definer.head)
        .lines()
        .filter_map(DocTag::default_line)
        .collect();
    for name in ["name", "rdname"] {
        let page = tag_value(&docs[0].1, name).or_else(|| tag_value(&head_defaults, name));
        for (block, tags) in &docs[1..] {
            let Some(value) = tag_value(tags, name) else {
                continue;
            };
            if page.as_ref() == Some(&value) {
                continue;
            }
            let page = match &page {
                Some(page) => format!("`@{name} {page}`"),
                None => format!("no `@{name}`"),
            };
            errors.push(format!(
                "miniextendr: the impl blocks of `{}` put the class on two help pages: {}, \
                 which defines the class, has {page}, and {} has `@{name} {value}`. The \
                 block that defines the class decides its page: move `@{name} {value}` \
                 into {}, or remove it (#1776).",
                definer.rust_type,
                class_block_name(definer),
                class_block_name(block),
                class_block_name(definer),
            ));
        }
    }
    errors
}

/// Decide a type's class constructor across its impl blocks: the blocks to
/// merge, each in the rendering that agrees with the decision.
///
/// - A block that declares the constructor
///   (`#[miniextendr(<system>(constructor))]`, or a receiver-less `new`
///   returning `Self`) has it. A block that would
///   infer one takes its [`demoted`](ClassBlockEntry::demoted) rendering,
///   where that method is a static method. Two declaring blocks are refused
///   with the other two-definer cases ([`merge_class_blocks`]).
/// - Without one, the type's one
///   [candidate](ClassBlockEntry::constructor_candidates) is its constructor,
///   whichever block has it. Several candidates are an error naming each
///   with its block (the compiler already refuses several in one block).
#[cfg(not(target_arch = "wasm32"))]
fn resolve_class_constructor<'a>(
    blocks: &[&'a ClassBlockEntry],
) -> Result<Vec<&'a ClassBlockEntry>, String> {
    let declared = blocks
        .iter()
        .any(|b| !b.constructor.is_empty() && !b.constructor_inferred);
    if declared {
        return Ok(blocks
            .iter()
            .map(|&b| match b.demoted {
                Some(demoted) if b.constructor_inferred => demoted,
                _ => b,
            })
            .collect());
    }
    let candidates: usize = blocks.iter().map(|b| b.constructor_candidates.len()).sum();
    if candidates > 1 {
        let listed: Vec<String> = blocks
            .iter()
            .filter(|b| !b.constructor_candidates.is_empty())
            .map(|b| {
                let names: Vec<String> = b
                    .constructor_candidates
                    .iter()
                    .map(|name| format!("`{name}`"))
                    .collect();
                format!("{} in {}", names.join(", "), class_block_name(b))
            })
            .collect();
        // The class system is the first word of the settings, `r6(...)`.
        let settings = blocks[0].settings;
        let system = &settings[..settings
            .find(|c: char| !c.is_ascii_alphanumeric())
            .unwrap_or(settings.len())];
        return Err(format!(
            "miniextendr: `{}` has several methods that could be its constructor, and none \
             is declared: {}. Mark the constructor with `#[miniextendr({system}(constructor))]` \
             (or name it `new`); the others stay static factory methods.",
            blocks[0].rust_type,
            listed.join("; "),
        ));
    }
    Ok(blocks.to_vec())
}

/// Resolve each member's generated page after the defining impl is known.
/// A default page follows that impl's `@rdname`; explicit member pages do not.
/// On an inherited author topic, its block supplies the title and parameter
/// docs, so generated prose/parameters are removed and the member sorts last.
#[cfg(not(target_arch = "wasm32"))]
fn resolve_class_member_docs(content: &str, class: &str, topic: &str) -> String {
    fn unmark(line: &str) -> &str {
        line.strip_prefix(CLASS_MEMBER_DEFAULT_PREFIX)
            .unwrap_or(line)
    }
    let mut lines = content.split('\n').peekable();
    let mut result = Vec::new();
    while let Some(line) = lines.next() {
        if !unmark(line).trim_start().starts_with("#'") {
            result.push(line.to_owned());
            continue;
        }
        let mut block = vec![line];
        while lines
            .peek()
            .is_some_and(|line| unmark(line).trim_start().starts_with("#'"))
        {
            block.push(lines.next().unwrap());
        }
        let default_page = block.iter().any(|line| {
            line.strip_prefix(CLASS_MEMBER_DEFAULT_PREFIX)
                .is_some_and(|line| line.starts_with("#' @rdname "))
        });
        let page = if default_page {
            Some(topic)
        } else {
            block
                .iter()
                .find_map(|line| line.strip_prefix("#' @rdname "))
        };
        let joined = page.is_some_and(|page| page != class)
            || block.iter().any(|line| line.starts_with("#' @describeIn "));
        let has_order = block
            .iter()
            .any(|line| unmark(line).starts_with("#' @order "));
        let no_rd = block.iter().any(|line| unmark(line).trim() == "#' @noRd");
        for line in block {
            match line.strip_prefix(CLASS_MEMBER_DEFAULT_PREFIX) {
                Some(default) if joined => {
                    if default.starts_with("#' @rdname ") {
                        result.push(format!("#' @rdname {topic}"));
                    }
                }
                Some(default) => result.push(default.to_owned()),
                None => result.push(line.to_owned()),
            }
        }
        if joined && !has_order && !no_rd && default_page {
            result.push("#' @order NaN".to_owned());
        }
    }
    result.join("\n")
}

/// The text of a type's merged class: see [`merge_class_blocks`].
#[cfg(not(target_arch = "wasm32"))]
fn merged_class_content(definer: &ClassBlockEntry, blocks: &[&ClassBlockEntry]) -> String {
    let block_docs = block_docs(definer, blocks);
    // A default of `owner` gives way to the same tag on another block; its
    // own docs were seen when it was generated.
    let replaced = |owner: &ClassBlockEntry, default: &DocTag<'_>| {
        block_docs.iter().any(|(block, tags)| {
            !std::ptr::eq(*block, owner) && tags.iter().any(|t| t.replaces(default))
        })
    };
    let mut class_docs: Vec<DocTag<'_>> = Vec::new();
    for tag in block_docs.iter().flat_map(|(_, tags)| tags) {
        if !class_docs.contains(tag) {
            class_docs.push(tag.clone());
        }
    }
    let mut class_doc_lines: Vec<DocTag<'_>> = Vec::new();
    for block in blocks {
        for mut tag in DocTag::parse(class_part(block.class_doc_lines)) {
            if tag.default && replaced(block, &tag) {
                continue;
            }
            tag.default = false;
            if !class_doc_lines.contains(&tag) {
                class_doc_lines.push(tag);
            }
        }
    }
    // A docs-only block (`CLASS_DOCS_ONLY_MARKER`) is written when the docs
    // say something beyond the page and export tags.
    let says_something = !class_doc_lines.is_empty()
        || class_docs.iter().any(|t| {
            !matches!(
                t.name(),
                "rdname" | "noRd" | "keywords" | "order" | "export"
            )
        });
    let mut skipping = false;
    // `split`, not `lines`: a blank last line separates the head from the
    // members.
    let mut head_lines: Vec<&str> = Vec::new();
    for line in class_part(definer.head).split('\n') {
        if skipping {
            skipping = line != "NULL";
            continue;
        }
        if line == CLASS_DOCS_ONLY_MARKER {
            skipping = !says_something;
        } else if line == CLASS_DOCS_MARKER {
            head_lines.extend(class_docs.iter().flat_map(|t| t.lines.iter().copied()));
        } else if line == CLASS_DOC_LINES_MARKER {
            head_lines.extend(class_doc_lines.iter().flat_map(|t| t.lines.iter().copied()));
        } else if let Some(tag) = DocTag::default_line(line) {
            if !replaced(definer, &tag) {
                head_lines.push(tag.lines[0]);
            }
        } else {
            head_lines.push(line);
        }
    }
    let head = head_lines.join("\n");

    let mut parts: Vec<(&ClassBlockEntry, &str)> = vec![(definer, &head)];
    parts.extend(blocks.iter().map(|&b| (b, class_part(b.members))));
    parts.push((definer, class_part(definer.tail)));

    let mut content = String::new();
    let mut previous: Option<&ClassBlockEntry> = None;
    for (block, text) in parts {
        if text.is_empty() {
            continue;
        }
        if previous.is_some_and(|p| std::ptr::eq(p, block)) {
            content.push('\n');
            content.push_str(text);
            continue;
        }
        if previous.is_some() {
            content.truncate(content.trim_end_matches('\n').len());
            content.push_str("\n\n");
        }
        content.push_str(&format!(
            "# Generated from Rust impl `{}` ({}:{}:{})\n",
            block.rust_type, block.source_file, block.source_line, block.source_column
        ));
        content.push_str(text.trim_start_matches('\n'));
        previous = Some(block);
    }
    let topic = block_docs[0]
        .1
        .iter()
        .find(|tag| tag.name() == "rdname")
        .map(|tag| tag.value())
        .unwrap_or_else(|| definer.r_class_name.to_owned());
    resolve_class_member_docs(&content, definer.r_class_name, &topic)
}

// endregion

/// Collect all R wrapper entries, sorted and deduplicated.
///
/// Each type's impl blocks are first merged into one class fragment
/// (`merge_class_blocks`, #1776); a conflict between them panics with every
/// problem found. The `reexport!` blocks are one more fragment
/// (`reexport_fragment`). Entries are then ordered by `sort_wrapper_entries`: priority
/// first, then source file, then source line. Within each priority group, S7
/// class definitions are additionally 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 classes = merge_class_blocks(&MX_CLASS_BLOCKS).unwrap_or_else(|msg| panic!("{msg}"));
    let mut entries: Vec<WrapperFragment> = MX_R_WRAPPERS
        .iter()
        .map(WrapperFragment::from)
        .chain(classes)
        .chain(sidecar_accessor_fragments(
            &MX_SIDECAR_ACCESSORS,
            &MX_CLASS_NAMES,
        ))
        .chain(
            all_equal_fragments(&MX_ALL_EQUAL, &MX_CLASS_NAMES)
                .unwrap_or_else(|msg| panic!("{msg}")),
        )
        .chain(reexport_fragment(&MX_REEXPORTS))
        .collect();
    sort_wrapper_entries(&mut entries);

    let mut seen = std::collections::HashSet::<String>::new();
    let mut fragments: Vec<(
        RWrapperPriority,
        &'static str,
        std::borrow::Cow<'static, str>,
    )> = Vec::with_capacity(entries.len());
    for entry in entries {
        let trimmed = match entry.content {
            std::borrow::Cow::Borrowed(content) => std::borrow::Cow::Borrowed(content.trim()),
            std::borrow::Cow::Owned(content) => std::borrow::Cow::Owned(content.trim().to_string()),
        };
        if !trimmed.is_empty() && seen.insert(trimmed.to_string()) {
            fragments.push((entry.priority, entry.source_file, trimmed));
        }
    }

    // Standalone functions: the default `@title`, the generated `@param`
    // fillers and the `@order` of blocks on an author topic are decided
    // together, per page.
    let standalone: Vec<StandaloneFragment<'_>> = fragments
        .iter()
        .filter(|(priority, _, _)| *priority == RWrapperPriority::Function)
        .map(|(_, source_file, content)| StandaloneFragment {
            content,
            stem: source_file_stem(source_file),
        })
        .collect();
    let mut resolved = resolve_standalone_pages(&standalone).into_iter();

    let mut result: Vec<std::borrow::Cow<'static, str>> = fragments
        .into_iter()
        .map(|(priority, _, content)| {
            if priority == RWrapperPriority::Function {
                std::borrow::Cow::Owned(
                    resolved
                        .next()
                        .expect("one resolved fragment per standalone function"),
                )
            } else {
                content
            }
        })
        .collect();

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

    result
}

// region: standalone-function pages (#1590)

/// Prefix of a generated `@param` line in a standalone function's fragment,
/// after the `#' ` roxygen lead. Spelled the same as
/// `miniextendr_macros::roxygen::PARAM_FILLER_MARKER`, which emits it.
#[cfg(not(target_arch = "wasm32"))]
const PARAM_FILLER_MARKER: &str = ".__MX_PARAM_FILLER__ ";

/// The `@order` line for a block on an author topic. Spelled the same as
/// `miniextendr_macros::roxygen::ORDER_AFTER_TOPIC_BLOCKS`, which documents
/// why `NaN` sorts the block after the topic's own block.
#[cfg(not(target_arch = "wasm32"))]
const ORDER_AFTER_TOPIC_BLOCKS: &str = "#' @order NaN";

/// A standalone function's wrapper fragment and the stem of its source file
/// (`None` for `lib.rs` / `mod.rs`, see [`source_file_stem`]).
///
/// The stem is the topic an explicit `@rdname <stem>` names to group the
/// file's functions on one page (#1289): such a block is on its own file's
/// page, not joining a topic defined elsewhere, so it keeps its generated
/// `@param` lines where no function on the page documents the argument.
#[cfg(not(target_arch = "wasm32"))]
struct StandaloneFragment<'a> {
    content: &'a str,
    stem: Option<String>,
}

/// Where a standalone function's block lands, read from its own tags.
#[cfg(not(target_arch = "wasm32"))]
struct StandalonePage {
    /// The `.Rd` topic, `None` for an `@noRd` block.
    page: Option<String>,
    /// The block joins a topic defined elsewhere: `@describeIn`, or an
    /// `@rdname` naming neither its file's stem page nor the block's own
    /// `@name` / function name.
    joined: bool,
    /// The `@title` to inject: the function name, for a roxygen block that
    /// documents its own page and has no `@title` (roxygen2 renders no page
    /// without one).
    title: Option<String>,
}

#[cfg(not(target_arch = "wasm32"))]
fn standalone_page(fragment: &StandaloneFragment<'_>) -> StandalonePage {
    let content = fragment.content;
    let stem = fragment.stem.as_deref();
    if has_no_rd_tag(content) {
        return StandalonePage {
            page: None,
            joined: false,
            title: None,
        };
    }
    let rdname = roxygen_tag_value(content, "rdname");
    let describe_in = roxygen_tag_value(content, "describeIn");
    let own_name = roxygen_tag_value(content, "name");
    let fn_name = content.lines().find_map(parse_top_level_fn_def_name);
    let own_page =
        |topic: &str| Some(topic) == stem || Some(topic) == own_name || Some(topic) == fn_name;
    let joined = describe_in.is_some() || rdname.is_some_and(|topic| !own_page(topic));
    let page = describe_in
        .or(rdname)
        .or(own_name)
        .or(fn_name)
        .map(str::to_string);
    let is_roxygen_block = content.lines().any(|l| l.trim_start().starts_with("#'"));
    let has_title = content.lines().any(|l| l.trim().starts_with("#' @title "));
    let title = fn_name
        .filter(|_| is_roxygen_block && !has_title && !has_page_assignment_tag(content))
        .map(str::to_string);
    StandalonePage {
        page,
        joined,
        title,
    }
}

/// Resolve the standalone functions' fragments, in emission order (#1590):
///
/// - give a roxygen block that picks no page itself (see
///   [`has_page_assignment_tag`]) and has no `@title` the function name as
///   its title. Such a block documents the function's own page, as in
///   roxygen2; grouping functions on one page is opt-in through an explicit
///   `@rdname` (#1289);
/// - resolve each generated `@param` filler (marked with
///   [`PARAM_FILLER_MARKER`] by the macro): keep it, unmarked, when the block
///   stays on its own page or its file's stem page (`@rdname <file stem>`)
///   and no other block of that page documents the argument; drop it when
///   the block joins a topic defined elsewhere (that topic's block documents
///   the arguments) or another function on the page documents the argument
///   (roxygen2 keeps the later of two `@param` lines for a name, so a filler
///   would replace the real text);
/// - give a block that joins a topic defined elsewhere `@order NaN`
///   ([`ORDER_AFTER_TOPIC_BLOCKS`]), so the topic's own block names and
///   titles the merged page whatever the R file order (an author `@order`
///   is kept).
///
/// Only the wrapper file is visible here: an R-file block that joins a
/// file-stem page does not count as documenting its arguments. Reading the
/// package's `R/*.R` blocks would tie the generated wrappers to R sources the
/// build does not track: they are regenerated only when the shared library is
/// relinked, so they would not follow an R-file edit.
#[cfg(not(target_arch = "wasm32"))]
fn resolve_standalone_pages(fragments: &[StandaloneFragment<'_>]) -> Vec<String> {
    use std::collections::{HashMap, HashSet};

    let pages: Vec<StandalonePage> = fragments.iter().map(standalone_page).collect();

    // Arguments each page documents for real (the author's `@param` lines).
    let mut documented: HashMap<&str, HashSet<&str>> = HashMap::new();
    for (fragment, page) in fragments.iter().zip(&pages) {
        let Some(topic) = page.page.as_deref() else {
            continue;
        };
        let names = documented.entry(topic).or_default();
        for line in fragment.content.lines() {
            if let Some(rest) = line.trim().strip_prefix("#' @param ")
                && let Some(token) = rest.split_whitespace().next()
            {
                names.extend(token.split(',').map(str::trim));
            }
        }
    }

    let filler_prefix = format!("#' {PARAM_FILLER_MARKER}");
    fragments
        .iter()
        .zip(&pages)
        .map(|(fragment, page)| {
            let mut kept = Vec::new();
            for line in fragment.content.lines() {
                let Some(param) = line.trim().strip_prefix(filler_prefix.as_str()) else {
                    kept.push(line.to_string());
                    continue;
                };
                let name = param
                    .strip_prefix("@param ")
                    .and_then(|rest| rest.split_whitespace().next());
                let documented_on_page = page
                    .page
                    .as_deref()
                    .zip(name)
                    .is_some_and(|(topic, name)| documented[topic].contains(name));
                if page.page.is_some() && !page.joined && !documented_on_page {
                    kept.push(format!("#' {param}"));
                }
            }
            let mut content = kept.join("\n");
            if page.joined && !content.lines().any(|l| l.trim().starts_with("#' @order ")) {
                content = insert_roxygen_line(&content, ORDER_AFTER_TOPIC_BLOCKS);
            }
            match page.title.as_deref() {
                Some(title) => insert_roxygen_line(&content, &format!("#' @title {title}")),
                None => content,
            }
        })
        .collect()
}

/// The value of a fragment's first `#' @<tag> <value>` line (its first word).
#[cfg(not(target_arch = "wasm32"))]
fn roxygen_tag_value<'a>(content: &'a str, tag: &str) -> Option<&'a str> {
    content.lines().find_map(|line| {
        let rest = line.trim().strip_prefix("#' @")?.strip_prefix(tag)?;
        if rest.starts_with(char::is_whitespace) {
            rest.split_whitespace().next()
        } else {
            None
        }
    })
}

/// Insert a roxygen line into a fragment at a tag boundary: before the first
/// `@export` / `@keywords` / `@source` line, else after the last roxygen line.
#[cfg(not(target_arch = "wasm32"))]
fn insert_roxygen_line(content: &str, new_line: &str) -> String {
    let lines: Vec<&str> = content.lines().collect();
    let at = lines
        .iter()
        .position(|l| {
            let t = l.trim();
            t.starts_with("#' @export")
                || t.starts_with("#' @keywords")
                || t.starts_with("#' @source")
        })
        .or_else(|| {
            lines
                .iter()
                .rposition(|l| l.trim().starts_with("#'"))
                .map(|i| i + 1)
        })
        .unwrap_or(0);
    let mut result = lines;
    result.insert(at, new_line);
    result.join("\n")
}

// endregion

/// Order wrapper entries for emission: by priority (the load-order
/// dependencies between sidecar accessors, classes, functions, trait impls and
/// vctrs methods), then by source file, then by the line the item starts on.
///
/// Within one source file that is source order, so the `@description`
/// paragraphs and `\usage` entries roxygen merges onto a shared `@rdname` /
/// `@describeIn` page appear in the order the Rust file defines them, not in
/// link order (#1476). The sort is stable, so entries generated at the same
/// file and line (a `macro_rules!` expansion) keep their registration order.
#[cfg(not(target_arch = "wasm32"))]
fn sort_wrapper_entries(entries: &mut [WrapperFragment]) {
    entries.sort_by_key(|e| (e.priority, e.source_file, e.source_line));
}

#[cfg(not(target_arch = "wasm32"))]
/// Check if an R wrapper fragment already assigns itself to a documentation
/// page: `@rdname <topic>`, `@describeIn <topic> <desc>`, or `@name <topic>`.
///
/// A fragment without one documents the function's own page, and only such a
/// fragment gets the default `@title` (the function name) when it has none
/// (#1289).
fn has_page_assignment_tag(content: &str) -> bool {
    content.lines().any(|line| {
        let trimmed = line.trim();
        trimmed.starts_with("#' @rdname ")
            || trimmed.starts_with("#' @describeIn ")
            || trimmed.starts_with("#' @name ")
    })
}

#[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"))]
/// The stem of a standalone function's source file: the topic an explicit
/// `@rdname` names to group the file's functions on one page (see
/// [`StandaloneFragment`]). `None` for `lib.rs` / `mod.rs`, whose stems name
/// no page of their own.
///
/// `"src/rust/zero_copy_tests.rs"` → `Some("zero_copy_tests")`
/// `"lib.rs"` → `None`
fn source_file_stem(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"))]
/// 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

/// The R formal of a `match_arg` parameter, `c("a", "b")`, that the wrappers
/// writer splices in place of its placeholder: `choices` (the type's
/// `MatchArg::CHOICES`), each quoted and escaped for an R string literal
/// ([`escape_r_string`](crate::match_arg::escape_r_string)).
///
/// With a `default = "..."` (`preferred`: the literal's text without its
/// quotes, so escaped as R source is), that choice comes first and the others
/// keep their order ([`crate::match_arg::default_first`], the order
/// [`crate::match_arg::match_arg_param_with_default`] matches against,
/// #1767). An empty `preferred` keeps the declaration order.
///
/// A `preferred` that names no choice panics with the placeholder: the
/// wrappers writer is the only caller, so the panic surfaces as a load-time
/// error in the host R session rather than a broken wrapper.
#[cfg(not(target_arch = "wasm32"))]
#[doc(hidden)]
pub fn match_arg_formal(choices: &[&str], preferred: &str, placeholder: &str) -> String {
    use crate::match_arg::{default_first, escape_r_string};
    let formal = if preferred.is_empty() {
        choices.to_vec()
    } else {
        default_first(choices, |choice| escape_r_string(choice) == preferred).unwrap_or_else(|| {
            panic!(
                "miniextendr: preferred default `{preferred}` for placeholder `{placeholder}` \
                 does not match any choice in {choices:?}"
            )
        })
    };
    let quoted: Vec<String> = formal
        .iter()
        .map(|choice| format!("\"{}\"", escape_r_string(choice)))
        .collect();
    format!("c({})", quoted.join(", "))
}

/// The trailing arguments a `match_arg` parameter's check passes to
/// `.miniextendr_match_arg` / `.miniextendr_match_arg_several` for the
/// type's `MatchArg::ALIASES` (#1843), which the wrappers writer splices in
/// place of `, <placeholder>`: `, aliases = base::c("grey" = "gray")`, each
/// alias and choice escaped for an R string literal. For a type without
/// aliases it is empty, so that wrapper keeps the text it had before aliases
/// existed. `base::c` is spelled out because the argument is written after
/// the shadowing pass, which would otherwise qualify it for a parameter
/// named `c`.
///
/// When an alias is listed, `, listed = " (or \"grey\" for \"gray\")"`
/// follows: the clause the check's message appends after the choices,
/// rendered here by the same function as the Rust side's messages
/// (`match_arg::listed_aliases_clause`), so the two word it alike (#2148). A
/// type whose aliases are all unlisted passes no `listed`, and its check
/// words its message as without aliases.
///
/// Aliases a hand-written impl got wrong (empty, `"NA"`, a choice, repeated,
/// a prefix of another choice, or naming no choice; the rules
/// `#[derive(MatchArg)]` enforces at compile time) panic with the
/// placeholder, as [`match_arg_formal`] does for a bad default.
#[cfg(not(target_arch = "wasm32"))]
#[doc(hidden)]
pub fn match_arg_aliases_arg(
    choices: &[&str],
    aliases: &[crate::match_arg::MatchArgAlias],
    placeholder: &str,
) -> String {
    use crate::match_arg::{alias_problems, escape_r_string, listed_aliases_clause, r_quote};
    if aliases.is_empty() {
        return String::new();
    }
    let problems = alias_problems(choices, aliases);
    if !problems.is_empty() {
        panic!(
            "miniextendr: the `MatchArg::ALIASES` behind placeholder `{placeholder}` \
             can't be used (choices {choices:?}): {}",
            problems.join("; ")
        );
    }
    let pairs: Vec<String> = aliases
        .iter()
        .map(|alias| {
            format!(
                "\"{}\" = \"{}\"",
                escape_r_string(alias.alias),
                escape_r_string(alias.choice)
            )
        })
        .collect();
    let mut arg = format!(", aliases = base::c({})", pairs.join(", "));
    let listed = listed_aliases_clause(choices, aliases, r_quote);
    if !listed.is_empty() {
        arg.push_str(&format!(", listed = \"{}\"", escape_r_string(&listed)));
    }
    arg
}

/// `content` with one `match_arg` parameter's placeholders resolved from its
/// [`MatchArgChoicesEntry`]: every choices placeholder (the formal and the
/// check) by [`match_arg_formal`], and the check's `, <aliases placeholder>`
/// by [`match_arg_aliases_arg`], which is empty for a type without aliases.
#[cfg(not(target_arch = "wasm32"))]
fn splice_match_arg_entry(content: &str, entry: &MatchArgChoicesEntry) -> String {
    let formal = match_arg_formal(entry.choices, entry.preferred_default, entry.placeholder);
    let aliases = match_arg_aliases_arg(entry.choices, entry.aliases, entry.aliases_placeholder);
    content
        .replace(entry.placeholder, &formal)
        .replace(&format!(", {}", entry.aliases_placeholder), &aliases)
}

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

/// Whether `name` is a syntactic R name (letters, digits, `.` and `_`; starts
/// with a letter or a `.` not followed by a digit; not a reserved word).
///
/// Mirrors `is_syntactic_r_name` in `miniextendr-macros`' `naming` module,
/// which decides how the class generators spell the same names.
#[cfg(not(target_arch = "wasm32"))]
fn is_syntactic_r_name(name: &str) -> bool {
    const RESERVED: &[&str] = &[
        "if",
        "else",
        "repeat",
        "while",
        "function",
        "for",
        "next",
        "break",
        "TRUE",
        "FALSE",
        "NULL",
        "Inf",
        "NaN",
        "NA",
        "NA_integer_",
        "NA_real_",
        "NA_character_",
        "NA_complex_",
        "in",
    ];
    let mut chars = name.chars();
    match chars.next() {
        Some(c) if c.is_ascii_alphabetic() => {}
        Some('.') => {
            if chars.next().is_some_and(|c| c.is_ascii_digit()) {
                return false;
            }
        }
        _ => return false,
    }
    name.chars()
        .all(|c| c.is_ascii_alphanumeric() || c == '.' || c == '_')
        && !RESERVED.contains(&name)
}

/// The argument of a raw `export(...)` NAMESPACE directive: bare for a
/// syntactic name, a double-quoted string for an operator such as `[[`
/// (`export([[)` does not parse). Must match `r_namespace_name` in
/// `miniextendr-macros`' `naming` module, which writes the method blocks'
/// directive for the same generic; roxygen2 only merges identical lines.
#[cfg(not(target_arch = "wasm32"))]
fn r_namespace_name(name: &str) -> String {
    if is_syntactic_r_name(name) {
        name.to_string()
    } else {
        format!("\"{}\"", name.replace('\\', "\\\\").replace('"', "\\\""))
    }
}

/// 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();

    // An operator generic (`[[`, `%op%`) is not called as `name()`.
    let display = if is_syntactic_r_name(generic) {
        format!("`{generic}()`")
    } else {
        format!("`{generic}`")
    };

    // Title
    lines.push(format!("#' The {display} 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!(
        "#' {display} 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,
            // including the quoting of operator names).
            lines.push(format!(
                "#' @rawNamespace export({})",
                r_namespace_name(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

/// R source of the `.miniextendr_caller_call` helper, with its comment
/// block, as written into the wrappers preamble by
/// [`write_r_wrappers_to_file`]: the call a `call = caller` wrapper reports
/// (#1450, #1548, #1552), including the frame or call a hand-written helper
/// passed as the wrapper's `.call` formal (#1613), and the frame or call a
/// `call_arg` wrapper was passed (`own = TRUE`, #1834).
#[cfg(not(target_arch = "wasm32"))]
const CALLER_CALL_HELPER: &str = r#"# Internal helper: the call a wrapper with a `.call` formal attributes its
# conditions to, as written. A `#[miniextendr(noexport, call = caller)]`
# wrapper calls it as its first statement, `.mx_call <- .miniextendr_caller_call(.call)`,
# with its trailing `.call = NULL` formal (an S3 method has none and calls it
# without an argument). A `#[miniextendr(call_arg)]` wrapper binds
# `.mx_call <- if (is.null(.call)) sys.call() else .miniextendr_caller_call(.call, own = TRUE)`,
# so it calls the helper only for a `.call` that isn't NULL. The calling chain
# is [caller's caller] <- [caller] <- [wrapper] <- [this helper]:
# `sys.parent(1L)` is the wrapper's frame, `sys.parent(2L)` its caller's.
# `call` is what the wrapper's caller passed as `.call`:
# - an environment: a hand-written helper between the public function and the
#   wrapper passes its caller's frame (`call = parent.frame()` in the helper's
#   formals), or a function composing the wrapper its own (`environment()`).
#   The result is the call of the closure owning that frame.
#   `match(TRUE, ...)` takes the oldest frame with that environment, the
#   closure's own, ahead of a later `eval()` over it. An environment that is no
#   closure's live frame (`globalenv()`) counts as NULL.
# - a call object: used as is.
# - NULL, the default: under `own = TRUE`, the wrapper's own call, without
#   `.call`. Otherwise, when the wrapper's caller is a closure, that caller's
#   call; else (top level, or an `eval()` frame such as a testthat block,
#   `source()` or `local()`, whose frame function is not a closure and whose
#   call names `eval`) the wrapper's own call, without `.call`.
# - anything else: an argument error on `.call` against the wrapper's own call,
#   which also catches a positional argument too many.
.miniextendr_caller_call <- function(call = NULL, own = FALSE) {
  wrapper <- sys.parent(1L)
  if (is.environment(call)) {
    frames <- sys.frames()
    i <- match(TRUE, vapply(frames, identical, NA, call))
    if (!is.na(i) && typeof(sys.function(i)) == "closure") return(sys.call(i))
  } else if (is.call(call)) {
    return(call)
  } else if (!is.null(call)) {
    .miniextendr_arg_error(".call", "must be NULL, an environment or a call", sys.call(wrapper))
  }
  if (!own) {
    parent <- sys.parent(2L)
    if (parent > 0L && typeof(sys.function(parent)) == "closure") return(sys.call(parent))
  }
  call <- sys.call(wrapper)
  call$.call <- NULL
  call
}
"#;

/// R source of `.miniextendr_frame_call` as a bare `function(env)`
/// expression: the call a generated S3 method's conditions report, resolved
/// from the method's frame (#1851).
///
/// A generated S3 method passes `environment()` as its `.call` and as the
/// raise fallback (`CallAttribution::Generic` in the macros), so the success
/// path pays no more than for `sys.call()`, and the frame becomes a call only
/// when a condition is raised. [`write_r_wrappers_to_file`] binds the
/// expression under that name in the preamble ([`FRAME_CALL_HELPER`]) for the
/// package's raise helper, the R-side checks (`.miniextendr_arg_error`) and a
/// method with a `Call` parameter, which resolves it up front;
/// [`RAISE_CONDITION_HELPER_FN`] inlines it, because that copy of the raise
/// helper signals deferred conditions from the base namespace, where the
/// preamble's binding is not visible.
///
/// The frame is looked up among the live frames (`sys.frames()`), newest
/// first, so the helper works from the method itself, from the raise helper
/// the method calls, and from the deferred-condition path, which R runs from
/// C while the method's `.Call()` is still on the stack (a `.Call` context
/// is not a function frame, so the frame numbers line up). `.Generic` is
/// bound in the frame of a method R dispatched (`UseMethod()`, an internal
/// generic such as `[[`, `NextMethod()`, a group generic such as `Ops`) and
/// not in a method called by name, so a direct call keeps the method's name.
/// For a replacement generic R's call is
/// `` `$<-.cls`(`*tmp*`, name, value = <value>) ``: the result is the
/// assignment as written, `x$name <- value`, which never deparses the value.
/// No comment inside: the text is inlined into another function. A macro,
/// not a `const`, because `concat!` takes literals only.
macro_rules! frame_call_helper_fn {
    () => {
        r#"function(env) {
  frames <- sys.frames()
  i <- length(frames)
  while (i > 0L && !identical(frames[[i]], env)) i <- i - 1L
  if (i == 0L) return(NULL)
  call <- sys.call(i)
  generic <- env[[".Generic"]]
  if (!is.character(generic) || length(generic) != 1L) return(call)
  if (length(call) > 1L && identical(call[[2L]], quote(`*tmp*`))) {
    call[[2L]] <- as.name(names(formals(sys.function(i)))[[1L]])
  }
  if (!endsWith(generic, "<-")) {
    call[[1L]] <- as.name(generic)
    return(call)
  }
  call$value <- NULL
  call[[1L]] <- as.name(substr(generic, 1L, nchar(generic) - 2L))
  call("<-", call, quote(value))
}"#
    };
}

/// The preamble's `.miniextendr_frame_call` binding of
/// [`frame_call_helper_fn!`], with its comment block, as written by
/// [`write_r_wrappers_to_file`].
#[cfg(not(target_arch = "wasm32"))]
const FRAME_CALL_HELPER: &str = concat!(
    r#"# Internal helper: the call a generated S3 method's conditions report, from
# the method's frame (`environment()`, which the method passes as `.call`).
# Under R's dispatch the method's own call names the method,
# `summary.cls(x, a = 1)`, and `.Generic` is bound in its frame; the result
# names the generic the user called instead: `summary(x, a = 1)`, `x[i]`,
# `x + 1` for an `Ops` method. For a replacement generic (`$<-`, `[[<-`, `[<-`,
# `names<-`, ...), which R calls as `` `$<-.cls`(`*tmp*`, name, value = <v>) ``,
# the result is the assignment as written, `x$name <- value`, with the
# method's first formal as the receiver and the symbol `value` in place of the
# value, so a large value is never deparsed into the call. A method called
# directly by name has no `.Generic` and keeps its own call. The frame is
# looked up among the live frames, so the helper serves the method's own
# checks, the raise helper and the conditions deferred while the method's
# `.Call()` runs; a frame that is no longer live gives NULL.
.miniextendr_frame_call <- "#,
    frame_call_helper_fn!(),
    "\n"
);

/// R source of the `.miniextendr_field_at` helper, with its comment block,
/// as written into the wrappers preamble by [`write_r_wrappers_to_file`]: the
/// field a position picks in the generated `[[.Class` of an S3 class with
/// `s3(r_data_accessors)`, on the bare classed pointer (#1891). The method
/// checks for `NA` first (a list's `[[NA]]` is `NULL`, a character vector's
/// is `NA`). A position is truncated and a logical is taken, as by a list's
/// `[[`; every position that picks no field (past the last one, `0`, a
/// negative one) raises `subscriptOutOfBoundsError` with the type's
/// field-error classes in front (`class`, the derive's
/// `.rdata_error_class_<Type>`, #1899), on the generic's call. Also
/// `.miniextendr_field_index_error`, the same method's refusal of an index
/// that is neither one name nor one position (#1920), and under
/// `lookup = "strict"` of a non-whole number, a logical or `NA` (#1921).
#[cfg(not(target_arch = "wasm32"))]
const FIELD_AT_HELPER: &str = r#"# Internal helper: the field a position picks on a bare classed pointer, as
# `[[` picks a list element: `2.9` is the second field, `TRUE` the first. A
# position that picks no field (past the last one, `0`, a negative one)
# raises `subscriptOutOfBoundsError`, with the type's own classes (`class`)
# in front, reporting the generic's call, `x[[9]]`, resolved from the
# method's frame (`env`).
.miniextendr_field_at <- function(fields, i, env, class = NULL) {
  k <- trunc(i)
  if (k < 1 || k > length(fields)) stop(errorCondition("subscript out of bounds", class = c(class, "subscriptOutOfBoundsError"), call = .miniextendr_frame_call(env)))
  fields[[k]]
}

# Internal helper: refuses a `[[` index on a bare classed pointer that is
# neither one field name nor one position (`x[[1:2]]`, `x[[list(1)]]`, and
# under strict lookup `x[[TRUE]]`, `x[[NA]]` or `x[[1.5]]` too), where R's
# `[[.default` would report itself. The type's own classes (`class`) go in
# front of R's `notSubsettableError`; the call is the generic's, `x[[1:2]]`,
# resolved from the method's frame (`env`). `cls` is the R class.
.miniextendr_field_index_error <- function(cls, env, class = NULL, strict = FALSE) {
  stop(errorCondition(sprintf("`[[` on a `%s` object takes one field name or one %sposition", cls, if (strict) "whole-number " else ""), class = c(class, "notSubsettableError"), call = .miniextendr_frame_call(env)))
}
"#;

/// R source blocks for the argument-check helpers of the wrappers preamble,
/// `.miniextendr_arg_error`, `.miniextendr_match_arg_several` and
/// `.miniextendr_match_arg`, with their comment blocks, as written by
/// [`write_r_wrappers_to_file`] (they read `.miniextendr_conversion_error_class`,
/// bound after them, and `.miniextendr_frame_call`, bound before).
/// Each block is emitted only when needed; this ordered array lets the
/// equivalence tests evaluate the same source as the wrapper writer.
///
/// `.miniextendr_match_arg`'s messages are the ones
/// [`crate::match_arg::match_arg_param`] and the generated conversion of a
/// `match_arg` type word in Rust (#1767): all take their words from
/// `match_arg::match_arg_wording!`, and the API tests
/// (`miniextendr-api/tests/match_arg_param.rs`) evaluate this source and
/// compare them on every input class (#1741).
///
/// History, kept here because the R comments ship in every package and cite
/// no PR numbers (#1832): `.miniextendr_arg_error` is #1591, the `call`
/// argument a `call = caller` wrapper passes is #1548, the frame an S3 method
/// passes there and the `NULL` of `call = none` are #1851, the strict
/// `several_ok` match is #1472, reading a factor as its labels is #1552, the
/// `aliases` argument ([`match_arg_aliases_arg`]) is #1843, and the `listed`
/// argument, the clause naming the listed aliases, is #2148.
#[cfg(not(target_arch = "wasm32"))]
#[doc(hidden)]
pub const ARG_CHECK_HELPERS: [&str; 3] =
    [ARG_ERROR_HELPER, MATCH_ARG_SEVERAL_HELPER, MATCH_ARG_HELPER];

#[cfg(not(target_arch = "wasm32"))]
const ARG_ERROR_HELPER: &str = r#"# Internal helper: raise an argument error from an R-side check: a
# type / length precondition, `no_na`, `inherits`, or a `match_arg` /
# `choices` value. The condition is the one a failed Rust conversion raises:
# the crate's `conversion_error_class` (`.miniextendr_conversion_error_class`,
# at the end of this preamble), then `rust_error`, with
# `kind = "conversion"` and `e$param`, so one handler catches an argument
# error whichever side finds it. The message is `'<param>' <what>`, or the
# author's own `message` (`inherits(..., message = )` / `no_na(message = )`),
# used as given. `call` defaults to the wrapper's own call, as `stopifnot()`
# reported it; a `call = caller` wrapper passes `.mx_call`, by name
# next to a named `message`; an S3 method passes its frame, resolved here to
# the generic's call (`.miniextendr_frame_call`); a `call = none` wrapper
# passes NULL. Only a failing check calls this: the passing path is one
# `isTRUE()` test per check.
.miniextendr_arg_error <- function(param, what, call = sys.call(-1L), message = sprintf("'%s' %s", param, what)) {
  if (is.environment(call)) call <- .miniextendr_frame_call(call)
  stop(structure(
    list(message = message, call = call, kind = "conversion", param = param),
    class = c(.miniextendr_conversion_error_class, "rust_error", "simpleError", "error", "condition")
  ))
}
"#;

/// The check of `#[miniextendr(dots = empty | empty(allow = ..) | forward(allow
/// = ..))]` (#2157): a wrapper with such an attribute calls it as
/// `if (...length()) .miniextendr_check_dots(...names(), ...length(),
/// <formals>, allow = .., forward = TRUE, class = .., call = ..)`, the
/// statement `miniextendr-macros`' `dots_policy::DotsPolicy::r_check` writes
/// (`forward = TRUE` for `forward` only). The `[[`, `as.list()` and `[[<-`
/// field methods of `s3(r_data_accessors)` and an env class's `[[` make the
/// `empty` check on a bare pointer (#2174). It builds its own condition, an
/// argument error with two more fields, and depends only on the helpers every
/// preamble has.
#[cfg(not(target_arch = "wasm32"))]
const DOTS_CHECK_HELPER: &str = r#"# Internal helper: refuse the arguments in a wrapper's `...` that its
# `dots = empty | empty(allow = ...) | forward(allow = ...)` attribute does not
# take, or that a generated field method or env class `[[` (`empty`) gets.
# The wrapper calls it only when `...length()` is nonzero, with
# `...names()` and `...length()`, so no argument is forced. Every name outside
# `allow` is refused. An unnamed argument stands for an allowed name given by
# position: under `forward` (`forward = TRUE`) it passes, since the function
# the dots go on to matches it by position itself; under `empty` nothing reads
# it, so only the count matters, and the unnamed arguments past the number of
# allowed names not given by name are refused. All of them go in one
# condition: `argument` holds each one (`..<i>` for an unnamed one, its
# position in `...`) and `suggestion` the formal or allowed name each one most
# likely meant, or NA. That is the one name it is a prefix of, else the first
# one closest by edit distance (a swap of two neighbours counts as one edit),
# at most a third of its length in edits but at least one, and fewer than its
# length. The condition is an argument error (`kind = "conversion"`,
# `param = "..."`) classed `miniextendr_error_unused_argument` after the
# attribute's own `class`. `call` is the wrapper's call by default; a
# `call = caller` wrapper passes `.mx_call`, an S3 method its frame (resolved
# to the generic's call), a `call = none` wrapper NULL.
.miniextendr_check_dots <- function(names, n, formals, allow = character(), forward = FALSE, class = character(), call = sys.call(-1L)) {
  if (is.null(names)) names <- character(n)
  names[is.na(names)] <- ""
  unnamed <- !nzchar(names)
  bad <- !unnamed & !(names %in% allow)
  if (!forward) bad <- bad | (unnamed & cumsum(unnamed) > length(setdiff(allow, names)))
  bad <- which(bad)
  if (!length(bad)) return(invisible())
  if (is.environment(call)) call <- .miniextendr_frame_call(call)
  candidates <- c(formals, allow)
  distance <- function(a, b) {
    a <- strsplit(a, "", fixed = TRUE)[[1L]]
    b <- strsplit(b, "", fixed = TRUE)[[1L]]
    d <- matrix(0L, length(a) + 1L, length(b) + 1L)
    d[, 1L] <- seq.int(0L, length(a))
    d[1L, ] <- seq.int(0L, length(b))
    for (i in seq_along(a)) for (j in seq_along(b)) {
      d[i + 1L, j + 1L] <- min(d[i, j + 1L] + 1L, d[i + 1L, j] + 1L, d[i, j] + (a[[i]] != b[[j]]))
      if (i > 1L && j > 1L && a[[i]] == b[[j - 1L]] && a[[i - 1L]] == b[[j]]) {
        d[i + 1L, j + 1L] <- min(d[i + 1L, j + 1L], d[i - 1L, j - 1L] + 1L)
      }
    }
    d[[length(a) + 1L, length(b) + 1L]]
  }
  suggest <- function(name) {
    if (!nzchar(name) || !length(candidates)) return(NA_character_)
    prefixed <- candidates[startsWith(candidates, name)]
    if (length(prefixed) == 1L) return(prefixed)
    edits <- vapply(candidates, distance, 0L, b = name, USE.NAMES = FALSE)
    best <- which(edits == min(edits) & edits <= max(1L, nchar(name) %/% 3L) & edits < nchar(name))
    if (length(best)) candidates[[best[[1L]]]] else NA_character_
  }
  unnamed <- !nzchar(names[bad])
  argument <- ifelse(unnamed, paste0("..", bad), names[bad])
  suggestion <- vapply(names[bad], suggest, "", USE.NAMES = FALSE)
  what <- sprintf("'%s'%s", argument, ifelse(unnamed, " (unnamed)", ""))
  hint <- !is.na(suggestion)
  what[hint] <- sprintf("%s (did you mean '%s'?)", what[hint], suggestion[hint])
  message <- sprintf("unused argument%s %s", if (length(bad) > 1L) "s" else "", paste(what, collapse = ", "))
  stop(structure(
    list(message = message, call = call, kind = "conversion", param = "...", argument = argument, suggestion = suggestion),
    class = c(class, "miniextendr_error_unused_argument", .miniextendr_conversion_error_class, "rust_error", "simpleError", "error", "condition")
  ))
}
"#;

#[cfg(not(target_arch = "wasm32"))]
const MATCH_ARG_SEVERAL_HELPER: &str = concat!(
    r#"# Internal helper: strict `match.arg(several.ok = TRUE)` for `several_ok` params.
# Base R keeps only the elements that match as long as one of them does, so a
# misspelled entry silently shortens the selection and the per-element check on
# the Rust side never sees it. Here every element has to match a choice
# (exactly or as a unique prefix), the first that does not is reported with its
# position, and `NULL` selects every choice, like an omitted argument does. A
# factor is read as its labels. `aliases`, a named character vector
# (`c(grey = "gray")`), maps each element typed exactly as an alias to its
# choice first; a prefix of an alias is not one. `listed` is the text the
# message names the listed aliases with after the choices
# (` (or "grey" for "gray")`, empty when none is listed). The error is an
# argument error (`.miniextendr_arg_error`) attributed to `call`: by default
# the wrapper's own call, not this helper; a `call = caller` wrapper passes
# its caller's matched call.
.miniextendr_match_arg_several <- function(arg, choices, arg_name, call = sys.call(-1L), aliases = NULL, listed = "") {
  if (is.null(arg)) return(choices)
  if (is.factor(arg)) arg <- as.character(arg)
  if (!is.character(arg)) .miniextendr_arg_error(arg_name, ""#,
    crate::match_arg::match_arg_wording!(not_character),
    r#"", call)
  if (length(arg) == 0L) .miniextendr_arg_error(arg_name, "must be of length >= 1", call)
  if (!is.null(aliases)) {
    a <- match(arg, names(aliases))
    arg[!is.na(a)] <- aliases[a[!is.na(a)]]
  }
  i <- pmatch(arg, choices, nomatch = 0L, duplicates.ok = TRUE)
  bad <- which(is.na(i) | i == 0L)
  if (length(bad)) {
    .miniextendr_arg_error(arg_name, sprintf("element %d (\"%s\") "#,
    crate::match_arg::match_arg_wording!(not_a_choice),
    r#" %s%s", bad[[1L]], arg[[bad[[1L]]]], paste(dQuote(choices, FALSE), collapse = ", "), listed), call)
  }
  choices[i]
}
"#
);

#[cfg(not(target_arch = "wasm32"))]
const MATCH_ARG_HELPER: &str = concat!(
    r#"# Internal helper: scalar `match.arg()` for `match_arg` / `choices` params.
# `base::match.arg()` says `'arg'` in its messages and reports its own frame;
# this names the argument and raises an argument error
# (`.miniextendr_arg_error`) attributed to `call`: by default the wrapper's own
# call, for a `call = caller` wrapper its caller's matched call.
# Semantics follow `match.arg(arg, choices)`: `NULL` and the full choice vector
# (the formal default) select the first choice; otherwise exactly one string
# that matches a choice exactly or as a unique prefix. A factor is read as its
# labels. `aliases`, a named character vector (`c(grey = "gray")`), maps a
# string typed exactly as an alias to its choice; a prefix of an alias is not
# one. `listed` is the text the message names the listed aliases with after
# the choices (` (or "grey" for "gray")`, empty when none is listed). The
# Rust side's `match_arg_param()` gives a body the same results and messages
# for a choice argument it matches itself.
.miniextendr_match_arg <- function(arg, choices, arg_name, call = sys.call(-1L), aliases = NULL, listed = "") {
  if (is.null(arg)) return(choices[[1L]])
  if (is.factor(arg)) arg <- as.character(arg)
  if (!is.character(arg)) .miniextendr_arg_error(arg_name, ""#,
    crate::match_arg::match_arg_wording!(not_character),
    r#"", call)
  if (identical(arg, choices)) return(arg[[1L]])
  if (length(arg) != 1L) .miniextendr_arg_error(arg_name, ""#,
    crate::match_arg::match_arg_wording!(not_scalar),
    r#"", call)
  if (!is.null(aliases) && !is.na(a <- match(arg, names(aliases)))) return(aliases[[a]])
  i <- pmatch(arg, choices, nomatch = 0L, duplicates.ok = TRUE)
  if (is.na(i) || i == 0L) {
    .miniextendr_arg_error(arg_name, sprintf(""#,
    crate::match_arg::match_arg_wording!(not_a_choice),
    r#" %s%s", paste(dQuote(choices, FALSE), collapse = ", "), listed), call)
  }
  choices[[i]]
}
"#
);

/// One condition-transport body for the package and standalone Rust helpers.
/// The resolver is a package binding or a self-contained function expression.
macro_rules! raise_condition_helper_fn {
    ($resolver:expr) => {
        concat!(
            r#"function(.val, .call_default) {
  # The condition object for one tagged value `.v`.
  .cond <- function(.v) {
    .msg <- .v$error
    # `.v$call` is the call the Rust side captured, NULL to use the wrapper's
    # call, or FALSE for a condition raised without one (`call = none`, R's
    # `call. = FALSE`), which is signalled with `call = NULL`.
    .call <- if (isFALSE(.v$call)) NULL else if (is.null(.v$call)) .call_default else .v$call
    # A generated S3 method passes its frame instead of a call, so that the
    # generic's call (`summary(x)` for `summary.cls(x)`, the assignment for a
    # replacement method) is built only now, when a condition is raised. The
    # resolver recovers the generic's call from that method frame.
    if (is.environment(.call)) .call <- "#,
            $resolver,
            r#"(.call)
    .class <- .v$class
    # `arg_error!` writes the class ".miniextendr_conversion_error_class"
    # where the crate's `conversion_error_class` belongs: only the generated R
    # knows those classes, bound under that name at the end of the wrappers
    # preamble, so they replace it here. The copy of this helper that signals
    # deferred conditions lives in the base namespace, where the name is
    # unbound and the marker is dropped.
    .at <- match(".miniextendr_conversion_error_class", .class)
    if (!is.na(.at)) {
      .class <- append(.class[-.at], get0(".miniextendr_conversion_error_class", ifnotfound = NULL), after = .at - 1L)
    }
    # `.v$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.
    # `keep.null = TRUE`: a field the Rust side set to `RValue::Null` is a
    # present field whose value is NULL, and must stay in `names(e)`; the
    # default would silently drop it (found downstream via a
    # `RConditionData::data()` returning an explicit NULL entry).
    .data <- .v$data
    # A cause the Rust side attached (`RCondition::with_parent`) travels as
    # the tagged value `.mx_parent` and becomes the condition object
    # `e$parent`, as `rlang::abort(parent = )` chains conditions. It is not
    # signalled, and its classes stay out of this condition's.
    if (is.list(.data) && !is.null(.data[[".mx_parent", exact = TRUE]])) {
      .parent <- .cond(.data[[".mx_parent", exact = TRUE]])
      .data[[".mx_parent"]] <- NULL
      .data[["parent"]] <- .parent
    }
    .cond_fields <- function(base) {
      if (is.null(.data) || !is.list(.data) || is.null(names(.data))) {
        base
      } else {
        utils::modifyList(base, .data, keep.null = TRUE)
      }
    }
    switch(.v$kind,
      warning = structure(.cond_fields(list(message = .msg, call = .call, kind = "warning")),
        class = c(.class, "rust_warning", "simpleWarning", "warning", "condition")),
      message = structure(.cond_fields(list(message = paste0(.msg, "\n"), call = NULL, kind = "message")),
        class = c(.class, "rust_message", "simpleMessage", "message", "condition")),
      condition = structure(.cond_fields(list(message = .msg, call = .call, kind = "condition")),
        class = c(.class, "rust_condition", "simpleCondition", "condition")),
      panic = structure(list(message = .msg, call = .call, kind = "panic"),
        class = c("rust_error", "simpleError", "error", "condition")),
      # error / result_err / none_err / conversion / other: an error whose class
      # vector and data (if any) come from the Rust side, e.g. a
      # `Result<T, E: RConditionData>`.
      structure(.cond_fields(list(message = .msg, call = .call, kind = .v$kind)),
        class = c(.class, "rust_error", "simpleError", "error", "condition")))
  }
  .c <- .cond(.val)
  switch(.val$kind,
    warning = warning(.c),
    message = message(.c),
    condition = signalCondition(.c),
    stop(.c)
  )
  invisible(NULL)
}"#
        )
    };
}

/// R source of the `.miniextendr_raise_condition` helper as a bare
/// `function(.val, .call_default)` expression.
///
/// [`crate::deferred_condition`] evaluates this self-contained expression
/// once (in the base namespace) to signal queued conditions from Rust without
/// depending on any package namespace. [`write_r_wrappers_to_file`] renders
/// the same template with the preamble's `.miniextendr_frame_call` binding as
/// the resolver instead of a second inline copy. Keeping one source
/// guarantees identical class layering and `data` splicing.
///
/// The helper dispatches on `.val$kind` (see [`crate::error_value::kind`]) and
/// re-raises the tagged Rust condition value as the matching R condition:
/// `stop()` for the error kinds, `warning()` / `message()` /
/// `signalCondition()` for the non-fatal ones (returning `invisible(NULL)`).
/// The marker class it replaces is the one `arg_error!` writes (#1740). A
/// frame in the call slot or as the default (a generated S3 method passes
/// `environment()`, #1851) is resolved to the generic's call with an inline
/// copy of [`frame_call_helper_fn!`], since the base-namespace copy of this
/// helper cannot see the preamble's `.miniextendr_frame_call`.
pub(crate) const RAISE_CONDITION_HELPER_FN: &str =
    raise_condition_helper_fn!(concat!("(", frame_call_helper_fn!(), ")"));

/// The package preamble already binds the resolver; reuse it there.
#[cfg(not(target_arch = "wasm32"))]
const WRAPPER_RAISE_CONDITION_HELPER_FN: &str =
    raise_condition_helper_fn!(".miniextendr_frame_call");

/// Shared method lookup for environment classes. Each returned closure gets
/// its own receiver-binding frame. An inherent method keeps its original
/// enclosure behind that frame, so native symbols and author-supplied R code
/// never resolve through the lookup helper's locals (#1677). Field lookup and
/// its condition call stay in the S3 method. Flat trait lookup must find a
/// unique method; inherent methods and explicit trait namespaces take priority.
#[cfg(not(target_arch = "wasm32"))]
const ENV_METHOD_HELPER: &str = r#"# Internal helper: bind an environment class's methods to one receiver.
# The class's `$` / `[[` methods handle fields before calling this lookup.
.miniextendr_env_method <- function(self, name, methods) {
  obj <- methods[[name]]
  if (is.environment(obj)) {
    bound <- new.env(parent = emptyenv())
    for (method_name in names(obj)) {
      method <- obj[[method_name]]
      if (is.function(method)) {
        if (isTRUE(attr(method, ".__mx_instance__"))) {
          local({
            m <- method
            bound[[method_name]] <<- function(...) m(self, ...)
          })
        } else {
          bound[[method_name]] <- method
        }
      }
    }
    bound
  } else if (is.null(obj)) {
    matches <- list()
    for (ns_name in names(methods)) {
      ns <- methods[[ns_name]]
      if (is.environment(ns) && exists(name, envir = ns, inherits = FALSE)) {
        method <- ns[[name]]
        if (is.function(method)) matches[[ns_name]] <- method
      }
    }
    if (!length(matches)) return(NULL)
    if (length(matches) > 1L) {
      traits <- sort(names(matches))
      stop(errorCondition(
        sprintf("Method '%s' is provided by multiple traits (%s). Use obj$Trait to select a trait explicitly.", name, paste(traits, collapse = ", ")),
        class = "miniextendr_ambiguous_method", method = name, traits = traits,
        call = .miniextendr_frame_call(parent.frame())
      ))
    }
    m <- matches[[1L]]
    if (isTRUE(attr(m, ".__mx_instance__"))) {
      s <- self
      function(...) m(s, ...)
    } else {
      m
    }
  } else {
    environment(obj) <- list2env(list(.mx_self = self), parent = environment(obj))
    obj
  }
}
"#;

/// The `.miniextendr_conversion_error_class` binding that closes the wrappers
/// preamble: the classes `.miniextendr_arg_error` puts on every R-side
/// argument error, from the [`MX_CONVERSION_ERROR_CLASS`] entry that
/// `miniextendr_init!` registers for the package crate (#1591).
///
/// The Rust conversion arms carry the same classes, emitted by the macro from
/// the same `[package.metadata.miniextendr]` key, so the two paths agree for
/// every item of that crate. A package has one `miniextendr_init!`, hence one
/// entry; with none (or a crate that sets no class) the binding is `NULL`.
#[cfg(not(target_arch = "wasm32"))]
fn conversion_error_class_binding() -> String {
    format_conversion_error_class_binding(conversion_error_class())
}

/// [`conversion_error_class_binding`] for an explicit class list.
#[cfg(not(target_arch = "wasm32"))]
fn format_conversion_error_class_binding(classes: &[&str]) -> String {
    let value = if classes.is_empty() {
        "NULL".to_string()
    } else {
        let quoted: Vec<String> = classes
            .iter()
            .map(|c| format!("\"{}\"", c.replace('\\', "\\\\").replace('"', "\\\"")))
            .collect();
        format!("c({})", quoted.join(", "))
    };
    format!(
        "# Internal: the crate's `conversion_error_class` ([package.metadata.miniextendr]),\n\
         # the classes of every argument error ahead of `rust_error`; NULL when unset.\n\
         .miniextendr_conversion_error_class <- {value}"
    )
}

/// The comment block that opens the wrappers preamble, ahead of the
/// `.miniextendr_raise_condition` binding, as written by
/// [`write_r_wrappers_to_file`].
#[cfg(not(target_arch = "wasm32"))]
const WRAPPERS_PREAMBLE_HEADER: &str =
    "# 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()` (or its `.mx_call`, the
# caller's call as written, for `#[miniextendr(noexport, call = caller)]` entry
# points, which honours a `.call` a helper passed on; an S3 method's frame,
# `environment()`, resolved to the generic's call here; NULL for a
# `call = none` wrapper), 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.
";

/// Emit an optional preamble helper only when a collected fragment names it.
///
/// A name in a roxygen comment also keeps its helper, which is harmless.
/// The one dependency between optional helpers is explicit:
/// `.miniextendr_caller_call` raises through `.miniextendr_arg_error`. The
/// helpers every preamble has (condition transport, the frame resolver, the
/// conversion-error class) are written unconditionally.
#[cfg(not(target_arch = "wasm32"))]
fn append_used_wrapper_helpers(content: &mut String, fragments: &[std::borrow::Cow<'_, str>]) {
    let uses = |name: &str| fragments.iter().any(|fragment| fragment.contains(name));
    let caller = uses(".miniextendr_caller_call");
    // Generated calls have no space before '('; include it to distinguish
    // the scalar matcher from the several-choice matcher's name.
    let scalar = uses(".miniextendr_match_arg(");
    let several = uses(".miniextendr_match_arg_several(");
    for (needed, helper) in [
        (caller, CALLER_CALL_HELPER),
        (
            uses(".miniextendr_field_at") || uses(".miniextendr_field_index_error"),
            FIELD_AT_HELPER,
        ),
        (uses(".miniextendr_env_method"), ENV_METHOD_HELPER),
        (uses(".miniextendr_check_dots("), DOTS_CHECK_HELPER),
        (
            caller || scalar || several || uses(".miniextendr_arg_error"),
            ARG_ERROR_HELPER,
        ),
        (several, MATCH_ARG_SEVERAL_HELPER),
        (scalar, MATCH_ARG_HELPER),
    ] {
        if needed {
            content.push_str(helper);
            content.push('\n');
        }
    }
}

/// 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; `wrappers_file_content` prepends the
    // header (marker line + version/fingerprint line) once the body is final.
    let mut content = String::from(WRAPPERS_PREAMBLE_HEADER);
    content.push_str(".miniextendr_raise_condition <- ");
    content.push_str(WRAPPER_RAISE_CONDITION_HELPER_FN);
    content.push_str("\n\n");
    content.push_str(FRAME_CALL_HELPER);
    content.push('\n');
    let fragments = collect_r_wrappers();
    append_used_wrapper_helpers(&mut content, &fragments);
    content.push_str(&conversion_error_class_binding());
    content.push_str("\n\n");

    for fragment in fragments {
        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`, that choice comes first —
    // `.miniextendr_match_arg()` returns `arg[1]` when arg is the formal
    // default, so the position-0 element becomes the effective default. The
    // check's aliases placeholder becomes its `aliases =` argument, or
    // nothing (#1843).
    for entry in MX_MATCH_ARG_CHOICES.iter() {
        content = splice_match_arg_entry(&content, entry);
    }

    // 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}{}.", entry.suffix);
        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).
    //
    // Repeated top-level function or class/namespace definitions silently
    // clobber each other at load time (last write wins), dispatching calls to
    // the wrong implementation or replacing the class object altogether.
    // The compile-time `check_s7_shortcut_collisions` only sees one 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}");
        }
    }

    // Refuse the `reexport!` names the package's wrappers bind or export
    // themselves, and a name re-exported from two packages (#1910). Like the
    // scan above, it reads the final names.
    if let Err(msg) = reexport_conflicts(&content, &MX_REEXPORTS) {
        panic!("{msg}");
    }

    let content = wrappers_file_content(&content);

    // 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.
///
/// First line of the generated wrappers file.
#[cfg(not(target_arch = "wasm32"))]
const WRAPPERS_FILE_MARKER: &str = "# ---- AUTO-GENERATED FILE - DO NOT EDIT ----";

/// The complete wrappers file for a finished `body`: the marker line, a line
/// naming the `miniextendr-api` version that generated it and an FNV-1a 64
/// digest of the body, then the body (#1552).
///
/// The digest is taken over [`normalize_source_locs`]`(body)`, the same view
/// [`wrappers_semantically_equal`] compares, so a Rust edit that only shifts
/// line numbers leaves the header alone and the no-rewrite check keeps
/// holding; any change to wrapper code, exports or docstrings changes it.
/// It lets a reviewer or a build tool tell two copies of the file apart from
/// the first two lines instead of diffing ~40k lines, and identifies the
/// generator version when a shipped wrapper is reported against.
#[cfg(not(target_arch = "wasm32"))]
fn wrappers_file_content(body: &str) -> String {
    let digest = crate::abi::fnv1a_64(
        normalize_source_locs(body).as_bytes(),
        crate::abi::FNV1A_64_OFFSET,
    );
    format!(
        "{WRAPPERS_FILE_MARKER}\n# miniextendr-api {} | fnv1a-64 of the normalized lines below: {digest:016x}\n{body}",
        env!("CARGO_PKG_VERSION"),
    )
}

/// 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 conflicting top-level function and class/namespace definitions 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.
///
/// Class and namespace bindings (`new.env`, `R6::R6Class`, `S7::new_class`)
/// occupy the same namespace as functions. Include them so a free function
/// cannot silently replace a class object (#1677). S4's `setClass()` is not a
/// binding assignment: its same-named constructor function remains valid.
/// Guarded S3/S4/S7 generic declarations may repeat across classes, but must
/// not share their binding with an ordinary function or class object (#1677).
/// A class object defined twice would replace the first together with the
/// methods bound to it. The impl blocks of one Rust type are merged into one
/// class before this scan, and two types claiming one class name are refused
/// there ([`merge_class_blocks`], #1776), so this is the last line of defence.
///
/// Every message names both producers, read from the
/// `# Generated from Rust …` header that opens each wrapper fragment.
///
/// Returns `Err(message)` naming the offending binding on the first collision
/// found; `Ok(())` when names are unique apart from shared generic declarations.
#[cfg(not(target_arch = "wasm32"))]
fn detect_duplicate_wrapper_defs(
    content: &str,
    accessor_producers: &std::collections::HashMap<String, String>,
) -> Result<(), String> {
    use std::collections::HashMap;

    // Binding name -> (kind, producer) of its first definition.
    let mut seen: HashMap<&str, (&str, std::rc::Rc<str>)> = HashMap::new();

    for WrapperName {
        name,
        kind,
        producer,
    } in wrapper_names(content)
    {
        if kind == "export" {
            continue;
        }
        let Some((previous, first)) = seen.get(name) else {
            seen.insert(name, (kind, producer));
            continue;
        };
        let previous = *previous;
        if previous == "guarded generic" && kind == "guarded generic" {
            // Several classes intentionally dispatch through one generic.
            continue;
        }
        let both = format!("{previous} from {first}, {kind} from {producer}");
        if previous == "guarded generic" || kind == "guarded generic" {
            return Err(format!(
                "miniextendr: wrapper name `{name}` is used by both a guarded generic \
                 and another generated binding ({both}). Package load order would \
                 replace one binding or prevent method dispatch. Rename the ordinary \
                 function with `r_name = \"...\"`, the class with `class = \"...\"`, \
                 or choose a distinct generic name."
            ));
        }
        if previous != "function" && kind != "function" {
            return Err(format!(
                "miniextendr: class `{name}` is defined more than once ({both}). The \
                 second definition replaces the first at load time, together with the \
                 methods bound to it. Give one of the classes a distinct \
                 `class = \"...\"`."
            ));
        }
        if previous != "function" || kind != "function" {
            return Err(format!(
                "miniextendr: wrapper name `{name}` is defined more than once ({both}). \
                 The second definition overwrites the first at load time. Give the \
                 class a distinct `class = \"...\"` name or rename the colliding \
                 function with `r_name = \"...\"`."
            ));
        }
        // Second function definition of this name -> collision.
        if let Some(derive) = accessor_producers.get(name) {
            return Err(format!(
                "miniextendr: wrapper function `{name}` is defined more than once \
                 ({both}). One definition comes from {derive}; 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 ({both}). 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(())
}

/// A name the assembled wrappers bind at top level or export, and the
/// fragment that does, as the `# Generated from Rust …` header opening each
/// fragment names it.
#[cfg(not(target_arch = "wasm32"))]
struct WrapperName<'a> {
    name: &'a str,
    /// `"function"`, `"class/namespace object"` (`new.env`, `R6::R6Class`,
    /// `S7::new_class`), `"guarded generic"` ([`parse_guarded_generic`]), or
    /// `"export"`: an `@export <name>` target or an
    /// `@rawNamespace export(<name>)` argument.
    kind: &'static str,
    producer: std::rc::Rc<str>,
}

/// The names of the assembled wrappers `content` in file order: see
/// [`WrapperName`]. Read by [`detect_duplicate_wrapper_defs`] and
/// [`reexport_conflicts`].
#[cfg(not(target_arch = "wasm32"))]
fn wrapper_names(content: &str) -> Vec<WrapperName<'_>> {
    let mut names = Vec::new();
    let mut producer: std::rc::Rc<str> = std::rc::Rc::from("an unattributed wrapper fragment");
    let mut lines = content.lines();
    while let Some(line) = lines.next() {
        if let Some(header) = line.strip_prefix("# Generated from ") {
            producer = std::rc::Rc::from(header);
            continue;
        }
        // A sidecar accessor's header gives only a source position; the line
        // after it names the field and the Rust type.
        if let Some(wraps) = line.strip_prefix("# Wraps ") {
            let what = wraps.split_once(" via ").map_or(wraps, |(what, _)| what);
            producer = std::rc::Rc::from(format!("{what} ({producer})"));
            continue;
        }
        if let Some(targets) = line.strip_prefix("#' @export ") {
            names.extend(targets.split_whitespace().map(|target| WrapperName {
                name: unquote_r_name(target),
                kind: "export",
                producer: producer.clone(),
            }));
            continue;
        }
        if let Some(directives) = line.strip_prefix("#' @rawNamespace ") {
            names.extend(raw_namespace_exports(directives).map(|name| WrapperName {
                name,
                kind: "export",
                producer: producer.clone(),
            }));
            continue;
        }
        let (name, kind) = if let Some(name) = parse_guarded_generic(line, lines.clone()) {
            (name, "guarded generic")
        } else {
            // Method assignments and indented closures are not bare top-level
            // bindings. Only the known generic guards above expose nested defs.
            let Some((name, rhs)) = parse_top_level_assignment(line) else {
                continue;
            };
            let kind = if rhs.starts_with("function") {
                "function"
            } else if ["new.env(", "R6::R6Class(", "S7::new_class("]
                .iter()
                .any(|prefix| rhs.starts_with(prefix))
            {
                "class/namespace object"
            } else {
                continue;
            };
            (name, kind)
        };
        names.push(WrapperName {
            name,
            kind,
            producer: producer.clone(),
        });
    }
    names
}

/// The names the `export(...)` directives of an `@rawNamespace` tag's text
/// export: `export(a, "[[")` gives `a` and `[[`. `exportPattern(...)`,
/// `exportClasses(...)` and the like are not `export(`.
#[cfg(not(target_arch = "wasm32"))]
fn raw_namespace_exports(directives: &str) -> impl Iterator<Item = &str> {
    directives
        .match_indices("export(")
        .filter(move |(at, _)| {
            !directives[..*at]
                .chars()
                .next_back()
                .is_some_and(|c| c.is_ascii_alphanumeric() || c == '.' || c == '_')
        })
        .flat_map(move |(at, open)| {
            let args = &directives[at + open.len()..];
            let args = args.split_once(')').map_or(args, |(args, _)| args);
            args.split(',')
                .map(|arg| unquote_r_name(arg.trim()))
                .filter(|name| !name.is_empty())
        })
}

/// `name` without the double quotes, single quotes or backticks around it.
#[cfg(not(target_arch = "wasm32"))]
fn unquote_r_name(name: &str) -> &str {
    ['"', '\'', '`']
        .iter()
        .find_map(|quote| {
            name.strip_prefix(*quote)
                .and_then(|inner| inner.strip_suffix(*quote))
        })
        .unwrap_or(name)
}

/// Recognize the generic guards emitted by `r_class_formatter` and the S4/S7
/// inherent/trait generators. This is a scan of generated forms, not an R parser:
/// the guard must start at column zero and its first statement must create a
/// generic. Never scan arbitrary indented assignments inside function bodies.
/// Documentation markers cannot stand in for this: `noexport` / `@noRd` classes
/// and trait implementations still declare generics without generic-doc markers.
#[cfg(not(target_arch = "wasm32"))]
fn parse_guarded_generic<'a>(line: &'a str, mut following: std::str::Lines<'a>) -> Option<&'a str> {
    if !(line.starts_with("if (!base::exists(\"")
        || line.starts_with("if (!exists(\"")
        || line.starts_with("if (!base::inherits(base::get0(\""))
    {
        return None;
    }
    // S4 emits its complete guard and setGeneric call on one line.
    if let Some((_, call)) = line.split_once(")) methods::setGeneric(\"") {
        return call.split_once("\", ").map(|(name, _)| name);
    }
    if !line.ends_with(" {") {
        return None;
    }
    // S3 and S7 put the assignment first in the guarded block, optionally
    // preceded by a generated comment. Their shadow-fallback branch need not
    // be scanned: it defines the same binding as the first branch.
    let body = following.find(|line| {
        let line = line.trim();
        !line.is_empty() && !line.starts_with('#')
    })?;
    let (name, rhs) = parse_top_level_assignment(body.strip_prefix("  ")?)?;
    // The wrapper's shadowed-formal pass can qualify UseMethod with base::.
    let s3 = rhs.strip_prefix("function(x, ...) ").is_some_and(|body| {
        body.strip_prefix("base::").unwrap_or(body) == format!("UseMethod(\"{name}\")")
    });
    (s3 || rhs.starts_with("S7::new_generic(") || rhs.starts_with("S7::new_external_generic("))
        .then_some(name)
}

/// Parse a top-level `name <- function(...)` definition. Used both by the
/// duplicate scan and by standalone-function documentation grouping.
#[cfg(not(target_arch = "wasm32"))]
fn parse_top_level_fn_def_name(line: &str) -> Option<&str> {
    let (name, rhs) = parse_top_level_assignment(line)?;
    rhs.starts_with("function").then_some(name)
}

/// Parse a bare top-level assignment, returning its name and trimmed RHS.
///
/// Ignore indented closures and targets containing `$`, `[[` or `::`, or a
/// call such as `S7::method(...)`. Backtick-quoted names are returned without
/// the quotes, with escapes kept as emitted. Find the closing backtick before
/// the arrow so replacement names such as `` `[<-.Foo` `` parse correctly.
#[cfg(not(target_arch = "wasm32"))]
fn parse_top_level_assignment(line: &str) -> Option<(&str, &str)> {
    if line.starts_with([' ', '\t']) {
        return None;
    }
    if let Some(quoted) = line.strip_prefix('`') {
        let mut escaped = false;
        for (index, ch) in quoted.char_indices() {
            if escaped {
                escaped = false;
            } else if ch == '\\' {
                escaped = true;
            } else if ch == '`' {
                let rhs = quoted[index + 1..].trim_start().strip_prefix("<-")?;
                return (!quoted[..index].is_empty())
                    .then_some((&quoted[..index], rhs.trim_start()));
            }
        }
        return None;
    }
    let (lhs, rhs) = line.split_once("<-")?;
    let name = lhs.trim();
    let first = name.chars().next()?;
    if !(first.is_ascii_alphabetic() || first == '.') {
        return None;
    }
    name.chars()
        .all(|c| c.is_ascii_alphanumeric() || c == '.' || c == '_')
        .then_some((name, rhs.trim_start()))
}
// 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()`).
///
/// A panic, such as a name collision found while assembling the wrappers, is
/// raised as an R error, so the install stops with the message instead of
/// aborting R at this non-unwinding boundary.
///
/// # 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 {
    crate::unwind_protect::with_r_unwind_protect_or_raise(
        || 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()
        },
        None,
    )
}

/// 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`. A panic is raised as an R error, as in
/// [`miniextendr_write_wrappers`].
///
/// # 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 {
    crate::unwind_protect::with_r_unwind_protect_or_raise(
        || 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()
        },
        None,
    )
}
// endregion

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

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

    #[test]
    #[cfg(not(target_arch = "wasm32"))]
    fn optional_preamble_helpers_follow_fragment_dependencies() {
        use std::borrow::Cow;
        let render = |fragment: &'static str| {
            let mut text = String::new();
            super::append_used_wrapper_helpers(&mut text, &[Cow::Borrowed(fragment)]);
            text
        };
        assert!(render("f <- function() .Call(C_f)").is_empty());

        let caller = render("f <- function() .miniextendr_caller_call()");
        assert!(caller.contains(".miniextendr_caller_call <- function"));
        assert!(caller.contains(".miniextendr_arg_error <- function"));
        assert!(!caller.contains(".miniextendr_field_at <- function"));
        assert!(!caller.contains(".miniextendr_env_method <- function"));
        assert!(!caller.contains(".miniextendr_match_arg"));

        let check = render("f <- function(x) .miniextendr_arg_error('x', 'must be positive')");
        assert!(check.contains(".miniextendr_arg_error <- function"));
        assert!(!check.contains(".miniextendr_match_arg"));

        let field = render("f <- function(x) .miniextendr_field_at(fields, x, environment())");
        assert!(field.contains(".miniextendr_field_at <- function"));
        assert!(!field.contains(".miniextendr_arg_error <- function"));
        let index = render("f <- function(x) .miniextendr_field_index_error('cls', environment())");
        assert!(index.contains(".miniextendr_field_index_error <- function"));

        let choices = render("f <- function(x) .miniextendr_match_arg_several(x, choices, 'x')");
        assert!(choices.contains(".miniextendr_arg_error <- function"));
        assert!(choices.contains(".miniextendr_match_arg_several <- function"));
        assert!(!choices.contains(".miniextendr_match_arg <- function"));

        let scalar = render("f <- function(x) .miniextendr_match_arg(x, choices, 'x')");
        assert!(scalar.contains(".miniextendr_arg_error <- function"));
        assert!(scalar.contains(".miniextendr_match_arg <- function"));
        assert!(!scalar.contains(".miniextendr_match_arg_several <- function"));

        // The `...` check builds its own condition (#2157).
        let dots = render(
            "f <- function(x, ...) {\n  if (...length()) .miniextendr_check_dots(...names(), ...length(), \"x\")\n}",
        );
        assert!(dots.contains(".miniextendr_check_dots <- function"));
        assert!(!dots.contains(".miniextendr_arg_error <- function"));
        assert!(!scalar.contains(".miniextendr_check_dots <- function"));
    }

    /// 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 impl blocks of one type register identical entries (#1242, #1776);
    /// 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",
                field_syntax: false,
            },
            ClassNameEntry {
                rust_type: "Foo",
                r_class_name: "Foo",
                class_system: "env",
                field_syntax: false,
            },
        ];
        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",
                field_syntax: false,
            },
            ClassNameEntry {
                rust_type: "Foo",
                r_class_name: "FooOverride",
                class_system: "env",
                field_syntax: false,
            },
        ];
        let _ = build_class_name_index(entries.iter());
    }

    /// R class names belong to one Rust type, regardless of the selected
    /// class systems or the order linkme supplies the registrations.
    #[test]
    fn class_name_index_rejects_shared_r_class_names() {
        for class_system in ["env", "r6", "s3", "s4", "s7", "vctrs"] {
            let entries = [
                ClassNameEntry {
                    rust_type: "First",
                    r_class_name: "Shared",
                    class_system: "env",
                    field_syntax: false,
                },
                ClassNameEntry {
                    rust_type: "Second",
                    r_class_name: "Shared",
                    class_system,
                    field_syntax: true,
                },
            ];
            for ordered in [[&entries[0], &entries[1]], [&entries[1], &entries[0]]] {
                let error = std::panic::catch_unwind(|| build_class_name_index(ordered))
                    .err()
                    .expect("a shared R class would overwrite the other type's methods");
                let message = error.downcast_ref::<String>().unwrap();
                assert!(message.contains("R class `Shared`"), "{message}");
                assert!(message.contains("`First` (env)"), "{message}");
                assert!(
                    message.contains(&format!("`Second` ({class_system})")),
                    "{message}"
                );
                assert!(message.contains("class = \"...\""), "{message}");
            }
        }
    }

    #[test]
    fn class_name_index_preserves_case_distinct_r_class_names() {
        let entries = [
            ClassNameEntry {
                rust_type: "First",
                r_class_name: "Widget",
                class_system: "env",
                field_syntax: false,
            },
            ClassNameEntry {
                rust_type: "Second",
                r_class_name: "widget",
                class_system: "env",
                field_syntax: false,
            },
        ];
        let index = build_class_name_index(entries.iter());
        assert_eq!(index["First"].r_class_name, "Widget");
        assert_eq!(index["Second"].r_class_name, "widget");
    }

    /// A type's standalone sidecar accessors are written internal when one of
    /// its impl blocks gives the class field syntax, exported otherwise (#1900).
    #[test]
    fn sidecar_accessors_follow_the_field_syntax() {
        let accessors = [
            SidecarAccessorsEntry {
                rust_type: "Fields",
                exported: "exported Fields",
                internal: "internal Fields",
                source_file: "lib.rs",
                source_line: 1,
            },
            SidecarAccessorsEntry {
                rust_type: "Plain",
                exported: "exported Plain",
                internal: "internal Plain",
                source_file: "lib.rs",
                source_line: 2,
            },
        ];
        let class = |rust_type, field_syntax| ClassNameEntry {
            rust_type,
            r_class_name: rust_type,
            class_system: "s3",
            field_syntax,
        };
        let classes = [
            class("Fields", false),
            class("Fields", true),
            class("Plain", false),
        ];
        let fragments = sidecar_accessor_fragments(&accessors, &classes);
        let contents: Vec<&str> = fragments.iter().map(|f| f.content.as_ref()).collect();
        assert_eq!(contents, ["internal Fields", "exported Plain"]);
        assert!(
            fragments
                .iter()
                .all(|f| f.priority == RWrapperPriority::Sidecar)
        );
        // A type no impl block registers keeps its exported accessors.
        assert_eq!(
            sidecar_accessor_fragments(&accessors, &[])[0].content,
            "exported Fields"
        );
    }

    /// The `all.equal()` method of `#[derive(AllEqual)]` takes the R class
    /// of the type's impl block: an S3 method for every class system, and an
    /// S7 class's own registration too (#2149).
    #[test]
    fn all_equal_methods_follow_the_class() {
        let entry = |rust_type| AllEqualEntry {
            rust_type,
            method: "\nfunction(target, current, ...) TRUE\n",
            docs: "#' Docs.",
            source_file: "lib.rs",
            source_line: 3,
            source_column: 12,
        };
        let class = |rust_type, r_class_name, class_system| ClassNameEntry {
            rust_type,
            r_class_name,
            class_system,
            field_syntax: false,
        };
        let entries = [entry("Fit"), entry("Shape")];
        let classes = [class("Fit", "fit_rec", "r6"), class("Shape", "Shape", "s7")];
        let fragments = all_equal_fragments(&entries, &classes).unwrap();
        assert!(
            fragments
                .iter()
                .all(|f| f.priority == RWrapperPriority::TraitImpl)
        );
        assert_eq!(
            fragments[0].content,
            "# Generated from Rust derive `AllEqual` on `Fit` (lib.rs:3:12)\n\
             #' Compare two `fit_rec` objects\n\
             #'\n\
             #' Docs.\n\
             #' @method all.equal fit_rec\n\
             #' @export\n\
             all.equal.fit_rec <- function(target, current, ...) TRUE"
        );
        assert!(fragments[1].content.ends_with(
            "all.equal.Shape <- function(target, current, ...) TRUE\n\
             S7::method(all.equal, Shape) <- all.equal.Shape\n\
             base::rm(list = \"all.equal\")"
        ));

        // A class name R can't read as a name is quoted.
        let quoted = all_equal_fragments(&[entry("Fit")], &[class("Fit", "fit-rec", "s3")]);
        assert!(
            quoted.unwrap()[0]
                .content
                .contains("`all.equal.fit-rec` <- function")
        );
    }

    /// A type without a class, and a vctrs class, are refused together.
    #[test]
    fn all_equal_methods_need_a_pointer_class() {
        let entry = |rust_type, source_line| AllEqualEntry {
            rust_type,
            method: "function(target, current, ...) TRUE",
            docs: "",
            source_file: "lib.rs",
            source_line,
            source_column: 1,
        };
        let classes = [ClassNameEntry {
            rust_type: "Rec",
            r_class_name: "Rec",
            class_system: "vctrs",
            field_syntax: false,
        }];
        let Err(msg) = all_equal_fragments(&[entry("Loose", 1), entry("Rec", 2)], &classes) else {
            panic!("expected the derives to be refused");
        };
        assert_eq!(
            msg,
            "`#[derive(AllEqual)]` on `Loose` (lib.rs:1): no `#[miniextendr(env | r6 | s3 | s4 | s7)]` \
             impl block gives the type an R class, so there is no class to give the `all.equal()` method\n\
             `#[derive(AllEqual)]` on `Rec` (lib.rs:2): the objects of a vctrs class are R vectors, \
             not pointers to the Rust value, and `all.equal()` already compares them"
        );
    }

    fn reexport(
        package: &'static str,
        name: &'static str,
        source_file: &'static str,
        source_line: u32,
    ) -> ReexportEntry {
        ReexportEntry {
            package,
            name,
            source_file,
            source_line,
            source_column: 11,
        }
    }

    /// One block per `pkg::name` whatever the number of sites, sorted by
    /// package then name, a non-syntactic name quoted (#1910).
    #[test]
    fn reexport_blocks_are_one_per_item_and_sorted() {
        assert!(reexport_fragment(&[]).is_none());
        let entries = [
            reexport("generics", "tidy", "models.rs", 8),
            reexport("magrittr", "%>%", "fits.rs", 4),
            reexport("generics", "tidy", "fits.rs", 3),
            reexport("generics", "glance", "fits.rs", 3),
            reexport("data.table", "fread", "io.rs", 1),
            reexport("generics", "tidy", "models.rs", 8),
        ];
        let fragment = reexport_fragment(&entries).expect("a fragment");
        assert!(fragment.priority == RWrapperPriority::Reexport);
        assert_eq!(
            fragment.content,
            "# Generated from Rust `reexport!` of `data.table::fread` (io.rs:1:11)\n\
             #' @importFrom data.table fread\n\
             #' @export\n\
             data.table::fread\n\
             \n\
             # Generated from Rust `reexport!` of `generics::glance` (fits.rs:3:11)\n\
             #' @importFrom generics glance\n\
             #' @export\n\
             generics::glance\n\
             \n\
             # Generated from Rust `reexport!` of `generics::tidy` (fits.rs:3:11) (models.rs:8:11)\n\
             #' @importFrom generics tidy\n\
             #' @export\n\
             generics::tidy\n\
             \n\
             # Generated from Rust `reexport!` of `magrittr::%>%` (fits.rs:4:11)\n\
             #' @importFrom magrittr \"%>%\"\n\
             #' @export\n\
             magrittr::`%>%`"
        );
        // The line numbers of the sites don't change the normalized file.
        let moved = [reexport("generics", "tidy", "models.rs", 80)];
        assert_eq!(
            normalize_source_locs(&reexport_fragment(&moved).unwrap().content),
            normalize_source_locs(
                &reexport_fragment(&[reexport("generics", "tidy", "models.rs", 8)])
                    .unwrap()
                    .content
            )
        );
    }

    /// The blocks bind nothing, so they pass both scans of the file.
    #[test]
    fn reexport_blocks_pass_the_wrapper_scans() {
        let entries = [
            reexport("generics", "tidy", "fits.rs", 3),
            reexport("magrittr", "%>%", "fits.rs", 4),
        ];
        let content = format!(
            "# Generated from Rust fn `fit` (fits.rs:9:8)\n\
             #' @export\n\
             fit <- function(x) .Call(C_fit, x)\n\n{}",
            reexport_fragment(&entries).unwrap().content
        );
        let names: Vec<&str> = wrapper_names(&content).iter().map(|n| n.name).collect();
        assert_eq!(names, ["fit"]);
        assert!(detect_duplicate_wrapper_defs(&content, &std::collections::HashMap::new()).is_ok());
        assert_eq!(reexport_conflicts(&content, &entries), Ok(()));
    }

    /// A name from two packages, and names the wrappers bind or export, are
    /// refused in one message naming every site (#1910).
    #[test]
    fn reexport_conflicts_are_refused_together() {
        let content = concat!(
            "# Generated from Rust impl `Fit` (fits.rs:20:6)\n",
            "#' @export glance\n",
            "if (!base::exists(\"glance\", mode = \"function\")) {\n",
            "  glance <- function(x, ...) UseMethod(\"glance\")\n",
            "}\n",
            "# Generated from Rust fn `augment` (fits.rs:30:8)\n",
            "#' @export\n",
            "augment <- function(x) .Call(C_augment, x)\n",
            "# Generated from Rust fn `fit_print` (fits.rs:40:8)\n",
            "#' @rawNamespace export(tidy, \"%>%\")\n",
            "#' @method print fit\n",
            "print.fit <- function(x, ...) invisible(x)\n",
        );
        let entries = [
            reexport("generics", "tidy", "fits.rs", 3),
            reexport("broom", "tidy", "models.rs", 5),
            reexport("generics", "tidy", "models.rs", 6),
            reexport("generics", "glance", "fits.rs", 3),
            reexport("generics", "augment", "fits.rs", 3),
            reexport("generics", "interpolate", "fits.rs", 3),
        ];
        assert_eq!(
            reexport_conflicts(content, &entries).unwrap_err(),
            "miniextendr: `reexport!` re-exports `tidy` from 2 packages: `broom::tidy` \
             (models.rs:5:11), `generics::tidy` (fits.rs:3:11) (models.rs:6:11). A package \
             exports one object under a name; re-export it from one of them.\n\
             miniextendr: `reexport!` re-exports `generics::augment` (fits.rs:3:11), and the \
             package's wrappers also bind `augment` (a function from Rust fn `augment` \
             (fits.rs:30:8)). The package's own `augment` would hide the imported one in its \
             namespace, so `export(augment)` would export it instead. Remove the re-export, or \
             rename the package's binding (`r_name = \"...\"`, `class = \"...\"`).\n\
             miniextendr: `reexport!` re-exports `generics::glance` (fits.rs:3:11), and the \
             package's wrappers also bind `glance` (a guarded generic from Rust impl `Fit` \
             (fits.rs:20:6)). The package's own `glance` would hide the imported one in its \
             namespace, so `export(glance)` would export it instead. Remove the re-export, or \
             rename the package's binding (`r_name = \"...\"`, `class = \"...\"`).\n\
             miniextendr: `reexport!` re-exports `broom::tidy` (models.rs:5:11), \
             `generics::tidy` (fits.rs:3:11) (models.rs:6:11), and the package's wrappers also \
             export `tidy` (an export from Rust fn `fit_print` (fits.rs:40:8)). `reexport!` \
             writes the export itself; drop the other one."
        );
    }

    #[test]
    fn raw_namespace_exports_are_read_by_name() {
        let names: Vec<&str> = raw_namespace_exports(
            "export(a, \"[[\") exportPattern(\"^x\") S3method(print, foo) if (TRUE) export(`b`)",
        )
        .collect();
        assert_eq!(names, ["a", "[[", "b"]);
    }

    /// 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",
                field_syntax: false,
            },
            ClassNameEntry {
                rust_type: "S7Circle",
                r_class_name: "S7Circle",
                class_system: "s7",
                field_syntax: false,
            },
        ];

        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",
                field_syntax: false,
            },
            ClassNameEntry {
                rust_type: "Point3D",
                r_class_name: "Point3D",
                class_system: "s7",
                field_syntax: false,
            },
        ];

        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",
            field_syntax: false,
        }];
        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",
            field_syntax: false,
        }];
        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",
            field_syntax: false,
        }];
        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",
                field_syntax: false,
            },
            // 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",
            field_syntax: false,
        }];
        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",
            field_syntax: false,
        }];
        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",
            field_syntax: false,
        }];
        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",
                field_syntax: false,
            },
            ClassNameEntry {
                rust_type: "EnvBoard",
                r_class_name: "EnvBoard",
                class_system: "env",
                field_syntax: false,
            },
        ];
        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",
            field_syntax: false,
        }];
        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",
            field_syntax: false,
        }];
        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",
            field_syntax: false,
        }];
        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",
            field_syntax: false,
        }];
        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",
            field_syntax: false,
        }];
        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",
            field_syntax: false,
        }];
        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",
                field_syntax: false,
            },
            ClassNameEntry {
                rust_type: "EnvBoard",
                r_class_name: "EnvBoard",
                class_system: "env",
                field_syntax: false,
            },
        ];
        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: wrappers_file_content header (#1552)

    #[test]
    fn wrappers_file_header_carries_version_and_body_digest() {
        // FNV-1a 64 reference vectors: "" and "a".
        assert_eq!(
            crate::abi::fnv1a_64(b"", crate::abi::FNV1A_64_OFFSET),
            0xcbf29ce484222325
        );
        assert_eq!(
            crate::abi::fnv1a_64(b"a", crate::abi::FNV1A_64_OFFSET),
            0xaf63dc4c8601ec8c
        );

        let content = wrappers_file_content("a");
        let mut lines = content.lines();
        assert_eq!(lines.next(), Some(WRAPPERS_FILE_MARKER));
        assert_eq!(
            lines.next(),
            Some(concat!(
                "# miniextendr-api ",
                env!("CARGO_PKG_VERSION"),
                " | fnv1a-64 of the normalized lines below: af63dc4c8601ec8c"
            ))
        );
        assert_eq!(lines.next(), Some("a"));
        assert_eq!(lines.next(), None);
    }

    #[test]
    fn wrappers_file_header_ignores_source_position_shifts() {
        let old = "# Generated from Rust fn `foo` (lib.rs:10:5)\nfoo <- function() 1\n";
        let new = "# Generated from Rust fn `foo` (lib.rs:42:8)\nfoo <- function() 1\n";
        let header = |s: &str| wrappers_file_content(s).lines().nth(1).unwrap().to_string();
        assert_eq!(header(old), header(new));
        assert!(wrappers_semantically_equal(
            &wrappers_file_content(old),
            &wrappers_file_content(new)
        ));

        let changed = "# Generated from Rust fn `foo` (lib.rs:10:5)\nfoo <- function() 2\n";
        assert_ne!(header(old), header(changed));
    }

    // endregion

    // 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\")"));
    }

    #[test]
    fn test_resolve_generic_doc_markers_quotes_operator_exports() {
        for generic in ["[", "[[", "$", "%custom%"] {
            let input = format!(
                ".__MX_GENERIC_DOC__(kind=\"S7\", generic=\"{generic}\", class=\"Foo\", export=true, dispatch=\"x\", no_dots=false)\n"
            );
            let output = resolve_generic_doc_markers(input);
            // Must match the method block's directive (`naming::r_namespace_name`
            // in miniextendr-macros); `export([[)` would not parse.
            assert!(
                output.contains(&format!("#' @rawNamespace export(\"{generic}\")")),
                "{output}"
            );
            assert!(
                output.contains(&format!("#' @name {generic}\n")),
                "{output}"
            );
            assert!(
                output.contains(&format!("#' The `{generic}` generic\n")),
                "{output}"
            );
        }
        let output = resolve_generic_doc_markers(
            r#".__MX_GENERIC_DOC__(kind="S7", generic="get", class="Foo", export=true, dispatch="x", no_dots=false)"#
                .to_string(),
        );
        assert!(
            output.contains("#' @rawNamespace export(get)\n"),
            "{output}"
        );
        assert!(output.contains("#' The `get()` generic\n"), "{output}");
    }

    #[test]
    fn test_is_syntactic_r_name_matches_r() {
        for name in ["get", "var", ".hidden", "s7_trait_Ops_value", "a.b_c1"] {
            assert!(is_syntactic_r_name(name), "{name}");
        }
        for name in [
            "[", "[[", "$", "%custom%", "Foo_[[", "if", "NA", ".1x", "1a", "_a", "",
        ] {
            assert!(!is_syntactic_r_name(name), "{name}");
        }
        assert_eq!(r_namespace_name(r#"a"b\c"#), r#""a\"b\\c""#);
    }

    // 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_accepts_backticked_def() {
        // Non-syntactic S3 method names are emitted backtick-quoted (#1475);
        // the scan sees the bare name so two `[.foo` definitions still collide.
        assert_eq!(
            parse_top_level_fn_def_name("`[.mx_bag` <- function(x, i, ...) {"),
            Some("[.mx_bag")
        );
        assert_eq!(
            parse_top_level_fn_def_name("`$.mx_bag` <- function(x, name) {"),
            Some("$.mx_bag")
        );
        // Unterminated or empty quoting is not a definition we own.
        assert_eq!(parse_top_level_fn_def_name("`[.foo <- function() {}"), None);
        assert_eq!(parse_top_level_fn_def_name("`` <- function() {}"), None);
    }

    #[test]
    fn detect_duplicate_wrapper_defs_sees_through_backticks() {
        let content = "`[.foo` <- function(x, i) 1\n`[.foo` <- function(x, i) 2\n";
        let err = detect_duplicate_wrapper_defs(content, &std::collections::HashMap::new())
            .expect_err("duplicate backticked definition must be reported");
        assert!(err.contains("`[.foo`"), "{err}");
    }

    #[test]
    fn has_page_assignment_tag_recognises_rdname_describein_and_name() {
        assert!(has_page_assignment_tag(
            "#' @rdname topic\nf <- function() 1"
        ));
        assert!(has_page_assignment_tag(
            "#' @describeIn topic Short text\n#' wrapped\nf <- function() 1"
        ));
        // `@name topic` documents `topic.Rd` in roxygen2.
        assert!(has_page_assignment_tag("#' @name topic\nf <- function() 1"));
        // A `@name` with no topic is malformed and does not count.
        assert!(!has_page_assignment_tag("#' @name\nf <- function() 1"));
        assert!(!has_page_assignment_tag(
            "#' @title T\n#' @export\nf <- function() 1"
        ));
        // Prefix-only matches do not count.
        assert!(!has_page_assignment_tag("#' @rdnamex\nf <- function() 1"));
    }

    // region: standalone-function pages (#1590)

    fn resolve_pages(fragments: &[(&str, Option<&str>)]) -> Vec<String> {
        let fragments: Vec<StandaloneFragment<'_>> = fragments
            .iter()
            .map(|(content, stem)| StandaloneFragment {
                content,
                stem: stem.map(str::to_string),
            })
            .collect();
        resolve_standalone_pages(&fragments)
    }

    /// A generated `@param` line as the macro emits it.
    fn filler(param: &str) -> String {
        format!("#' {PARAM_FILLER_MARKER}@param {param} (no documentation available)")
    }

    fn filler_resolved(param: &str) -> String {
        format!("#' @param {param} (no documentation available)")
    }

    /// The `.Rd` topic each fragment lands on, as `resolve_standalone_pages`
    /// reads it.
    fn page_topics(fragments: &[(&str, Option<&str>)]) -> Vec<Option<String>> {
        fragments
            .iter()
            .map(|(content, stem)| {
                standalone_page(&StandaloneFragment {
                    content,
                    stem: stem.map(str::to_string),
                })
                .page
            })
            .collect()
    }

    /// Two free functions of one source file document a page each (#1289):
    /// no file-stem `@rdname` is injected, and each keeps the generated lines
    /// of the arguments it leaves undocumented, even an argument the other
    /// function documents.
    #[test]
    fn free_functions_of_one_file_get_a_page_each() {
        let scale = format!(
            "#' @title stem_scale\n#' @param values Numbers.\n{}\n#' @export\nstem_scale <- function(values, factor) 1",
            filler("factor")
        );
        let floor = format!(
            "#' @title stem_floor\n{}\n{}\n#' @export\nstem_floor <- function(values, floor) 1",
            filler("values"),
            filler("floor")
        );
        let fragments = [
            (scale.as_str(), Some("stem_docs")),
            (&floor, Some("stem_docs")),
        ];
        assert_eq!(
            page_topics(&fragments),
            [
                Some("stem_scale".to_string()),
                Some("stem_floor".to_string())
            ]
        );
        let out = resolve_pages(&fragments);
        for page in &out {
            assert!(!page.contains("@rdname"), "{page}");
            assert!(!page.contains(PARAM_FILLER_MARKER), "{page}");
            assert!(!page.contains("@order"), "own page, no order: {page}");
        }
        assert!(out[0].contains(&filler_resolved("factor")), "{}", out[0]);
        assert!(out[1].contains(&filler_resolved("values")), "{}", out[1]);
        assert!(out[1].contains(&filler_resolved("floor")), "{}", out[1]);
    }

    /// Grouping is opt-in through an explicit `@rdname <file stem>`. On that
    /// page a filler survives only for an argument no function on the page
    /// documents: roxygen2 keeps the later `@param` of a name, so a filler
    /// would replace the real description another block wrote. The blocks are
    /// the file's own page, so none of them gets `@order NaN`.
    #[test]
    fn explicit_stem_page_keeps_fillers_only_for_undocumented_arguments() {
        let first = format!(
            "#' @name stem_docs\n#' @rdname stem_docs\n#' @param values Numbers.\n{}\n#' @export\nstem_scale <- function(values, factor) 1",
            filler("factor")
        );
        let second = format!(
            "#' @rdname stem_docs\n#' @param offset Amount.\n{}\n#' @export\nstem_shift <- function(values, offset) 1",
            filler("values")
        );
        let third = format!(
            "#' @title stem_floor\n#' @rdname stem_docs\n{}\n{}\n#' @export\nstem_floor <- function(values, floor) 1",
            filler("values"),
            filler("floor")
        );
        let fragments = [
            (first.as_str(), Some("stem_docs")),
            (&second, Some("stem_docs")),
            (&third, Some("stem_docs")),
        ];
        assert!(
            page_topics(&fragments)
                .iter()
                .all(|page| page.as_deref() == Some("stem_docs"))
        );
        let out = resolve_pages(&fragments);
        for page in &out {
            assert!(!page.contains(PARAM_FILLER_MARKER), "{page}");
            assert!(!page.contains("@order"), "own page, no order: {page}");
            assert_eq!(page.matches("#' @rdname").count(), 1, "{page}");
        }
        assert!(out[0].contains(&filler_resolved("factor")), "{}", out[0]);
        assert!(!out[1].contains("@param values"), "{}", out[1]);
        assert!(!out[2].contains("@param values"), "{}", out[2]);
        assert!(out[2].contains(&filler_resolved("floor")), "{}", out[2]);
    }

    /// The case that made a merged `.Rd` reach 3.7 MB and stall
    /// `R CMD INSTALL` (#1289): functions of one file with their own `@title`,
    /// the first defining a section the others `@inheritSection`. Each
    /// function keeps its own page, so the inheritance names another page
    /// instead of the merged page itself.
    #[test]
    fn titled_blocks_inheriting_a_section_keep_separate_pages() {
        let first = "#' @title First setter\n#' @section Shared rules:\n#' Values are checked.\n#' @param x A value.\n#' @export\nfirst_setter <- function(x) 1";
        let second = "#' @title Second setter\n#' @inheritSection first_setter Shared rules\n#' @param x A value.\n#' @export\nsecond_setter <- function(x) 1";
        let third = "#' @title Third setter\n#' @inheritSection first_setter Shared rules\n#' @param x A value.\n#' @export\nthird_setter <- function(x) 1";
        let fragments = [
            (first, Some("setters")),
            (second, Some("setters")),
            (third, Some("setters")),
        ];
        assert_eq!(
            page_topics(&fragments),
            ["first_setter", "second_setter", "third_setter"].map(|t| Some(t.to_string()))
        );
        // Nothing to resolve: the blocks are written as the macro emitted them.
        assert_eq!(resolve_pages(&fragments), [first, second, third]);
    }

    /// A roxygen block that picks no page and has no `@title` gets the
    /// function name as its title, so roxygen2 renders its page; `lib.rs`
    /// functions (no stem) too. A block with no roxygen line, or `@noRd`,
    /// renders no page and gets none.
    #[test]
    fn untitled_own_page_blocks_get_the_function_name_as_title() {
        let bare = "#' @export\nbare_fn <- function() 1";
        let internal = "#' @keywords internal\ninternal_fn <- function() 1";
        let undocumented = "plain_fn <- function() 1";
        let no_rd = "#' @noRd\nhidden <- function() 1";
        let out = resolve_pages(&[
            (bare, Some("helpers")),
            (internal, None),
            (undocumented, Some("helpers")),
            (no_rd, Some("helpers")),
        ]);
        assert_eq!(
            out[0],
            "#' @title bare_fn\n#' @export\nbare_fn <- function() 1"
        );
        assert_eq!(
            out[1],
            "#' @title internal_fn\n#' @keywords internal\ninternal_fn <- function() 1"
        );
        assert_eq!(out[2], undocumented);
        assert_eq!(out[3], no_rd);
    }

    /// A grouped `@param lower,upper` documents both names.
    #[test]
    fn grouped_param_names_count_as_documented() {
        let a = "#' @rdname bounds\n#' @param lower,upper Bounds.\n#' @export\nf <- function(lower, upper) 1";
        let b = format!(
            "#' @rdname bounds\n{}\n{}\n#' @export\ng <- function(lower, upper) 1",
            filler("lower"),
            filler("upper")
        );
        let out = resolve_pages(&[(a, Some("bounds")), (&b, Some("bounds"))]);
        assert!(!out[1].contains("@param"), "{}", out[1]);
    }

    /// A block that joins a topic defined elsewhere drops its fillers (that
    /// topic's block documents the arguments) and sorts after the topic's own
    /// block, whatever the R file order. `@rdname` naming the function itself
    /// or its own `@name` is its own page.
    #[test]
    fn author_topic_blocks_drop_fillers_and_sort_last() {
        let joined = format!(
            "#' @title range_width\n#' @rdname range_summaries\n{}\n#' @export\nrange_width <- function(values) 1",
            filler("values")
        );
        let own_fn = format!(
            "#' @title mx_bag_sum\n#' @rdname mx_bag_sum\n{}\n#' @export\nmx_bag_sum <- function(x) 1",
            filler("x")
        );
        let own_name = format!(
            "#' @name bag_topic\n#' @rdname bag_topic\n#' @title Bags\n{}\nbag_len <- function(x) 1",
            filler("x")
        );
        let ordered = "#' @rdname range_summaries\n#' @order 3\nrange_mid <- function(values) 1";
        let out = resolve_pages(&[
            (&joined, Some("shared_param_docs")),
            (&own_fn, Some("s3_nonsyntactic_tests")),
            (&own_name, Some("bags")),
            (ordered, Some("shared_param_docs")),
        ]);
        assert!(!out[0].contains("@param"), "{}", out[0]);
        assert!(
            out[0].contains("#' @order NaN\n#' @export"),
            "order inserted at a tag boundary: {}",
            out[0]
        );
        for own in &out[1..3] {
            assert!(own.contains(&filler_resolved("x")), "{own}");
            assert!(!own.contains("@order"), "{own}");
        }
        // The author's own `@order` is kept, not doubled.
        assert_eq!(out[3].matches("@order").count(), 1, "{}", out[3]);
        assert!(out[3].contains("#' @order 3"), "{}", out[3]);
    }

    /// `@describeIn` always joins another topic; an `@noRd` block has no page
    /// and keeps no fillers; `lib.rs` functions (no stem) keep theirs.
    #[test]
    fn describe_in_no_rd_and_stemless_blocks() {
        let described = "#' @describeIn range_summaries Midpoint.\n#' wrapped\nrange_midpoint <- function(values) 1";
        let no_rd = format!("{}\n#' @noRd\nhidden <- function(x) 1", filler("x"));
        let stemless = format!(
            "#' @title top\n{}\n#' @export\ntop <- function(x) 1",
            filler("x")
        );
        let out = resolve_pages(&[
            (described, Some("shared_param_docs")),
            (&no_rd, Some("shared_param_docs")),
            (&stemless, None),
        ]);
        assert_eq!(
            out[0],
            "#' @describeIn range_summaries Midpoint.\n#' wrapped\n#' @order NaN\nrange_midpoint <- function(values) 1"
        );
        assert_eq!(out[1], "#' @noRd\nhidden <- function(x) 1");
        assert!(out[2].contains(&filler_resolved("x")), "{}", out[2]);
        assert!(!out[2].contains("@rdname"), "{}", out[2]);
    }

    // endregion

    #[test]
    fn sort_wrapper_entries_is_priority_then_file_then_line() {
        fn entry(
            priority: RWrapperPriority,
            source_file: &'static str,
            source_line: u32,
            content: &'static str,
        ) -> WrapperFragment {
            WrapperFragment {
                priority,
                content: std::borrow::Cow::Borrowed(content),
                source_file,
                source_line,
            }
        }
        let mut entries = vec![
            entry(RWrapperPriority::Function, "b.rs", 10, "b10"),
            entry(RWrapperPriority::Function, "a.rs", 30, "a30"),
            entry(RWrapperPriority::Class, "z.rs", 1, "class"),
            entry(RWrapperPriority::Function, "a.rs", 5, "a5"),
            entry(RWrapperPriority::Function, "a.rs", 5, "a5-second"),
        ];
        sort_wrapper_entries(&mut entries);
        let order: Vec<&str> = entries.iter().map(|e| e.content.as_ref()).collect();
        // Classes first; then functions in file order, then source order; the
        // two entries at the same file:line keep their registration order.
        assert_eq!(order, ["class", "a5", "a5-second", "a30", "b10"]);
    }

    #[test]
    fn parse_top_level_fn_def_name_accepts_quoted_operators() {
        for name in [
            "[.Foo", "[[.Foo", "$.Foo", "==.Foo", "+.Foo", "[<-.Foo", r"a\`b\\c",
        ] {
            let line = format!("`{name}` <- function(x, ...) {{}}");
            assert_eq!(parse_top_level_fn_def_name(&line), Some(name));
        }
        for line in [
            "`obj`$method <- function() {}",
            "`obj`[[1]] <- function() {}",
            "`unclosed <- function() {}",
            "`value` <- 1L",
        ] {
            assert_eq!(parse_top_level_fn_def_name(line), None);
        }
    }

    #[test]
    fn parse_top_level_fn_def_name_reads_escaped_backslashes() {
        // `naming::r_def_name` (miniextendr-macros) writes `a\b` as `` `a\\b` ``
        // and `trail\` as `` `trail\\` ``: R reads backslash escapes inside
        // backticks. The scan returns that escaped spelling, and the doubled
        // backslash before the closing backtick must not hide it.
        for (line, name) in [
            (r"`a\\b` <- function(x) {}", r"a\\b"),
            (r"`trail\\` <- function(x) {}", r"trail\\"),
            (r"`x\\\`y` <- function(x) {}", r"x\\\`y"),
        ] {
            assert_eq!(parse_top_level_fn_def_name(line), Some(name), "{line}");
        }
        // The pre-escaping spelling of `trail\` never closed its backtick.
        assert_eq!(
            parse_top_level_fn_def_name(r"`trail\` <- function(x) {}"),
            None
        );
        let map = std::collections::HashMap::new();
        let twice = "`a\\\\b` <- function() 1\n`a\\\\b` <- function() 2\n";
        assert!(detect_duplicate_wrapper_defs(twice, &map).is_err());
    }

    #[test]
    fn detect_duplicate_quoted_operator_defs() {
        let map = std::collections::HashMap::new();
        let content = "`[.Foo` <- function(x, ...) {}\n`[.Foo` <- function(x, ...) {}\n";
        let err = detect_duplicate_wrapper_defs(content, &map).unwrap_err();
        assert!(err.contains("`[.Foo` is defined more than once"), "{err}");
        let mixed = "foo <- function() {}\n`foo` <- function() {}\n";
        assert!(detect_duplicate_wrapper_defs(mixed, &map).is_err());
        let distinct = "`[.Foo` <- function(x, ...) {}\n`[[.Foo` <- function(x, ...) {}\n";
        assert!(detect_duplicate_wrapper_defs(distinct, &map).is_ok());
    }

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

    /// The preamble ships in every package's `R/` and source tarball, where a
    /// bare `#1548` reads as that package's own issue, so its R text cites
    /// none (#1832). The citations live in the Rust comments around it.
    #[test]
    fn preamble_cites_no_issue_numbers() {
        let binding = format_conversion_error_class_binding(&["pkg_error"]);
        for (name, text) in [
            ("WRAPPERS_PREAMBLE_HEADER", WRAPPERS_PREAMBLE_HEADER),
            ("RAISE_CONDITION_HELPER_FN", RAISE_CONDITION_HELPER_FN),
            (
                "WRAPPER_RAISE_CONDITION_HELPER_FN",
                WRAPPER_RAISE_CONDITION_HELPER_FN,
            ),
            ("CALLER_CALL_HELPER", CALLER_CALL_HELPER),
            ("FRAME_CALL_HELPER", FRAME_CALL_HELPER),
            ("FIELD_AT_HELPER", FIELD_AT_HELPER),
            ("ENV_METHOD_HELPER", ENV_METHOD_HELPER),
            ("ARG_ERROR_HELPER", ARG_ERROR_HELPER),
            ("DOTS_CHECK_HELPER", DOTS_CHECK_HELPER),
            ("MATCH_ARG_SEVERAL_HELPER", MATCH_ARG_SEVERAL_HELPER),
            ("MATCH_ARG_HELPER", MATCH_ARG_HELPER),
            ("the conversion_error_class binding", binding.as_str()),
        ] {
            for line in text.lines() {
                let cites = line
                    .as_bytes()
                    .windows(2)
                    .any(|w| w[0] == b'#' && w[1].is_ascii_digit());
                assert!(!cites, "{name} cites an issue number: {line}");
            }
        }
    }

    /// The preamble's caller-call helper (#1613) takes the wrapper's `.call`
    /// as an argument defaulting to `NULL` (an S3 method calls it without
    /// one) and `own`, which a `call_arg` wrapper sets so that a frame no
    /// closure owns gives its own call, not its caller's (#1834). It is the
    /// only top-level definition in its block, so the duplicate-name scan
    /// sees it once.
    #[test]
    fn caller_call_helper_takes_the_call_formal() {
        let defs: Vec<&str> = CALLER_CALL_HELPER
            .lines()
            .filter_map(parse_top_level_fn_def_name)
            .collect();
        assert_eq!(defs, [".miniextendr_caller_call"]);
        assert!(
            CALLER_CALL_HELPER
                .contains(".miniextendr_caller_call <- function(call = NULL, own = FALSE) {")
        );
        // `own` skips the caller lookup.
        assert!(CALLER_CALL_HELPER.contains("  if (!own) {\n    parent <- sys.parent(2L)"));
        // The fallback call leaves the plumbing formal out.
        assert!(CALLER_CALL_HELPER.contains("call$.call <- NULL"));
        // Every call it returns is the call as written (`sys.call()`), never
        // a matched one.
        assert!(!CALLER_CALL_HELPER.contains("match.call"));
        assert!(CALLER_CALL_HELPER.ends_with("}\n"));
    }

    /// The preamble's frame-call helper (#1851) binds the bare
    /// `frame_call_helper_fn!()` expression, the same text the raise helper
    /// inlines for its base-namespace copy, and `.miniextendr_arg_error`
    /// resolves a frame with it before raising.
    #[test]
    fn frame_call_helper_is_shared_by_the_raise_helper_and_the_checks() {
        let fn_text = frame_call_helper_fn!();
        let defs: Vec<&str> = FRAME_CALL_HELPER
            .lines()
            .filter_map(parse_top_level_fn_def_name)
            .collect();
        assert_eq!(defs, [".miniextendr_frame_call"]);
        assert!(FRAME_CALL_HELPER.ends_with(&format!(".miniextendr_frame_call <- {fn_text}\n")));
        assert!(RAISE_CONDITION_HELPER_FN.contains(&format!(
            "if (is.environment(.call)) .call <- ({fn_text})(.call)\n"
        )));
        assert!(
            WRAPPER_RAISE_CONDITION_HELPER_FN
                .contains("if (is.environment(.call)) .call <- .miniextendr_frame_call(.call)\n")
        );
        assert!(!WRAPPER_RAISE_CONDITION_HELPER_FN.contains(fn_text));
        // No comment inside the shared text: it is inlined into the raise
        // helper, whose own comments sit outside it.
        assert!(!fn_text.contains('#'));
        // The generic's call replaces the method's; a replacement generic's
        // call is the assignment, with the value as the symbol `value`.
        assert!(fn_text.contains("generic <- env[[\".Generic\"]]"));
        assert!(fn_text.contains("call(\"<-\", call, quote(value))"));
        assert!(
            ARG_ERROR_HELPER
                .contains("  if (is.environment(call)) call <- .miniextendr_frame_call(call)\n")
        );
    }

    /// The preamble's field-position helper (#1891) and the bad-index error
    /// (#1920) are the two definitions in their block. A position is
    /// truncated as `[[` truncates it on a list; one that picks no field
    /// (past the last, `0`, negative) raises R's own
    /// `subscriptOutOfBoundsError` with the type's `field_error` classes in
    /// front (#1899), reporting the generic's call resolved from the method's
    /// frame. An index that is no name or position raises the `field_error`
    /// classes, then `notSubsettableError`, on that call.
    #[test]
    fn field_at_helper_picks_a_field_as_a_list_does() {
        let defs: Vec<&str> = FIELD_AT_HELPER
            .lines()
            .filter_map(parse_top_level_fn_def_name)
            .collect();
        assert_eq!(
            defs,
            [".miniextendr_field_at", ".miniextendr_field_index_error"]
        );
        assert!(FIELD_AT_HELPER.contains(
            ".miniextendr_field_index_error <- function(cls, env, class = NULL, strict = FALSE) {"
        ));
        assert!(FIELD_AT_HELPER.contains(
            "class = c(class, \"notSubsettableError\"), call = .miniextendr_frame_call(env)))"
        ));
        assert!(
            FIELD_AT_HELPER
                .contains(".miniextendr_field_at <- function(fields, i, env, class = NULL) {")
        );
        assert!(FIELD_AT_HELPER.contains(
            "if (k < 1 || k > length(fields)) stop(errorCondition(\"subscript out of bounds\", \
             class = c(class, \"subscriptOutOfBoundsError\"), call = .miniextendr_frame_call(env)))"
        ));
        assert!(FIELD_AT_HELPER.contains("  fields[[k]]\n"));
        assert!(FIELD_AT_HELPER.starts_with("# Internal helper"));
        assert!(FIELD_AT_HELPER.ends_with("}\n"));
    }

    /// The preamble's class binding (#1591): the crate classes as an R
    /// character vector, escaped, or `NULL` when the crate sets none. It is a
    /// plain assignment, not a function definition, so the duplicate-name
    /// scan skips it.
    #[test]
    fn conversion_error_class_binding_quotes_or_nulls() {
        let last_line = |classes: &[&str]| {
            format_conversion_error_class_binding(classes)
                .lines()
                .last()
                .unwrap()
                .to_string()
        };
        assert_eq!(
            last_line(&[]),
            ".miniextendr_conversion_error_class <- NULL"
        );
        assert_eq!(
            last_line(&["pkg_error_argument", "pkg_error"]),
            ".miniextendr_conversion_error_class <- c(\"pkg_error_argument\", \"pkg_error\")"
        );
        assert_eq!(
            last_line(&["a\"b\\c"]),
            ".miniextendr_conversion_error_class <- c(\"a\\\"b\\\\c\")"
        );
        let binding = format_conversion_error_class_binding(&["pkg_error"]);
        assert!(
            binding
                .lines()
                .all(|l| parse_top_level_fn_def_name(l).is_none())
        );
    }

    /// The raise helper resolves `arg_error!`'s class marker (#1740) against
    /// the binding the preamble defines under the same name, and only inside
    /// the `if`, so the base-namespace copy that signals deferred conditions
    /// never needs the binding.
    #[test]
    fn raise_helper_resolves_the_conversion_class_marker() {
        let marker = crate::condition::CONVERSION_ERROR_CLASS_MARKER;
        assert_eq!(
            format!("{marker} <- NULL"),
            format_conversion_error_class_binding(&[])
                .lines()
                .last()
                .unwrap()
        );
        let lookup = format!(".at <- match(\"{marker}\", .class)");
        let resolve = format!("get0(\"{marker}\", ifnotfound = NULL)");
        let at = RAISE_CONDITION_HELPER_FN
            .find(&lookup)
            .expect("marker lookup");
        let at_resolve = RAISE_CONDITION_HELPER_FN
            .find(&resolve)
            .expect("resolution");
        let at_switch = RAISE_CONDITION_HELPER_FN.find("switch(.val$kind").unwrap();
        assert!(at < at_resolve && at_resolve < at_switch);
        // The bare binding name appears only as a string (no direct lookup).
        assert_eq!(
            RAISE_CONDITION_HELPER_FN.matches(marker).count(),
            RAISE_CONDITION_HELPER_FN
                .matches(&format!("\"{marker}\""))
                .count()
        );
    }

    /// A `match_arg` check as the macro writes it, for `splice_match_arg_entry`.
    const ALIASES_CHECK: &str = "f <- function(mode = .__MX_MATCH_ARG_CHOICES_f_mode__) {\n  \
        mode <- .miniextendr_match_arg(mode, .__MX_MATCH_ARG_CHOICES_f_mode__, \"mode\", \
        .__MX_MATCH_ARG_ALIASES_f_mode__)\n}";

    fn aliases_entry(
        choices: &'static [&'static str],
        aliases: &'static [MatchArgAlias],
    ) -> MatchArgChoicesEntry {
        MatchArgChoicesEntry {
            placeholder: ".__MX_MATCH_ARG_CHOICES_f_mode__",
            choices,
            preferred_default: "",
            aliases_placeholder: ".__MX_MATCH_ARG_ALIASES_f_mode__",
            aliases,
        }
    }

    /// A type without aliases gets the check it had before aliases existed;
    /// one with aliases gets the `aliases =` argument, after the others
    /// (#1843), then the clause naming the listed ones (#2148), which a type
    /// whose aliases are all unlisted does without.
    #[test]
    fn splice_match_arg_entry_writes_the_aliases_argument() {
        assert_eq!(
            splice_match_arg_entry(ALIASES_CHECK, &aliases_entry(&["red", "gray"], &[])),
            "f <- function(mode = c(\"red\", \"gray\")) {\n  \
             mode <- .miniextendr_match_arg(mode, c(\"red\", \"gray\"), \"mode\")\n}"
        );
        assert_eq!(
            splice_match_arg_entry(
                ALIASES_CHECK,
                &aliases_entry(&["red", "gray"], {
                    const LISTED: &[MatchArgAlias] = &[
                        MatchArgAlias::new("grey", "gray"),
                        MatchArgAlias::new("rouge", "red"),
                    ];
                    LISTED
                })
            ),
            "f <- function(mode = c(\"red\", \"gray\")) {\n  \
             mode <- .miniextendr_match_arg(mode, c(\"red\", \"gray\"), \"mode\", \
             aliases = base::c(\"grey\" = \"gray\", \"rouge\" = \"red\"), \
             listed = \" (or \\\"rouge\\\" for \\\"red\\\", \\\"grey\\\" for \\\"gray\\\")\")\n}"
        );
        assert_eq!(
            splice_match_arg_entry(
                ALIASES_CHECK,
                &aliases_entry(&["red", "gray"], {
                    const UNLISTED: &[MatchArgAlias] = &[MatchArgAlias::unlisted("grey", "gray")];
                    UNLISTED
                })
            ),
            "f <- function(mode = c(\"red\", \"gray\")) {\n  \
             mode <- .miniextendr_match_arg(mode, c(\"red\", \"gray\"), \"mode\", \
             aliases = base::c(\"grey\" = \"gray\"))\n}"
        );
        // With a call argument before it, as under `call = caller`.
        let caller = ALIASES_CHECK.replace("\"mode\", .__MX", "\"mode\", .mx_call, .__MX");
        assert!(
            splice_match_arg_entry(&caller, &aliases_entry(&["red", "gray"], &[]))
                .contains("c(\"red\", \"gray\"), \"mode\", .mx_call)\n")
        );
    }

    /// Aliases and choices are escaped for an R string literal, and so is
    /// the clause, which quotes them as the R check quotes the choices.
    #[test]
    fn match_arg_aliases_arg_escapes() {
        assert_eq!(match_arg_aliases_arg(&["a"], &[], "p"), "");
        assert_eq!(
            match_arg_aliases_arg(
                &["say \"hi\"", r"c:\path"],
                &[
                    MatchArgAlias::unlisted("hello", "say \"hi\""),
                    MatchArgAlias::new(r"d:\", r"c:\path")
                ],
                "p"
            ),
            r#", aliases = base::c("hello" = "say \"hi\"", "d:\\" = "c:\\path"), listed = " (or \"d:\\\" for \"c:\\path\")""#
        );
    }

    /// The wrappers writer refuses the aliases of a hand-written impl that the
    /// derive refuses at compile time, naming the placeholder, every problem
    /// at once.
    #[test]
    fn match_arg_aliases_arg_refuses_bad_aliases() {
        let refused = |aliases: &'static [MatchArgAlias]| {
            std::panic::catch_unwind(|| {
                match_arg_aliases_arg(&["red", "gray", "green"], aliases, ".__MX_ALIASES_p__")
            })
            .expect_err("refused")
            .downcast::<String>()
            .map(|m| *m)
            .unwrap()
        };
        const BAD: &[MatchArgAlias] = &[
            MatchArgAlias::new("", "red"),
            MatchArgAlias::new("NA", "red"),
            MatchArgAlias::new("red", "gray"),
            MatchArgAlias::new("grey", "gray"),
            MatchArgAlias::unlisted("grey", "gray"),
            MatchArgAlias::new("blue", "navy"),
            MatchArgAlias::new("gr", "green"),
        ];
        let message = refused(BAD);
        assert!(message.contains(".__MX_ALIASES_p__"), "{message}");
        for problem in [
            "an alias can't be empty",
            "alias \"NA\" would read as a missing value",
            "alias \"red\" is already a choice",
            "alias \"grey\" is given more than once",
            "alias \"blue\" names \"navy\", which is not a choice",
            "alias \"gr\" for \"green\" is a prefix of the choice \"gray\"",
        ] {
            assert!(message.contains(problem), "{problem:?} in {message}");
        }
        // A prefix of its own choice only is fine.
        assert_eq!(
            match_arg_aliases_arg(
                &["red", "gray"],
                &[MatchArgAlias::unlisted("gr", "gray")],
                "p"
            ),
            r#", aliases = base::c("gr" = "gray")"#
        );
    }

    /// The argument-check helpers define exactly the three preamble functions
    /// and end on a closing brace.
    #[test]
    fn arg_check_helpers_define_the_three_functions() {
        let defs: Vec<&str> = ARG_CHECK_HELPERS
            .iter()
            .flat_map(|helper| helper.lines())
            .filter_map(parse_top_level_fn_def_name)
            .collect();
        assert_eq!(
            defs,
            [
                ".miniextendr_arg_error",
                ".miniextendr_match_arg_several",
                ".miniextendr_match_arg"
            ]
        );
        for helper in ARG_CHECK_HELPERS {
            assert!(helper.starts_with("# Internal helper"));
            assert!(helper.ends_with("}\n"));
        }
    }

    #[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",
                field_syntax: false,
            }],
        );
        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",
                field_syntax: false,
            }],
        );
        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",
                field_syntax: false,
            }],
        );
        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 duplicate_class_and_function_bindings_fail_in_either_order() {
        for class in [
            "Widget <- new.env(parent = emptyenv())",
            "Widget <- R6::R6Class(\"Widget\")",
            "Widget <- S7::new_class(\"Widget\")",
            "`Widget` <- new.env(parent = emptyenv())",
        ] {
            let class = format!("# Generated from Rust impl `Widget` (lib.rs:10:6)\n{class}\n");
            let function = "# Generated from Rust fn `widget` (lib.rs:30:8)\n\
                            Widget <- function() .Call(C_widget)\n";
            for content in [format!("{class}{function}"), format!("{function}{class}")] {
                let error =
                    detect_duplicate_wrapper_defs(&content, &std::collections::HashMap::new())
                        .expect_err("a function must not replace a class or namespace object");
                assert!(error.contains("`Widget`"), "{error}");
                assert!(error.contains("class/namespace object"), "{error}");
                assert!(error.contains("r_name"), "{error}");
                assert!(
                    error.contains("Rust impl `Widget` (lib.rs:10:6)"),
                    "{error}"
                );
                assert!(error.contains("Rust fn `widget` (lib.rs:30:8)"), "{error}");
            }
        }
    }

    /// Two class objects of one name in the written file: the second would
    /// drop the first one's methods (#1677, #1776).
    #[test]
    fn duplicate_class_objects_name_both_producers() {
        for class in [
            "Widget <- new.env(parent = emptyenv())",
            "Widget <- R6::R6Class(\"Widget\",",
            "Widget <- S7::new_class(\"Widget\",",
        ] {
            let content = format!(
                "# Generated from Rust impl `Widget` (lib.rs:10:6)\n{class}\n\
                 Widget$new <- function() .Call(C_new)\n\
                 # Generated from Rust impl `Widget` (lib.rs:40:6)\n{class}\n"
            );
            let error = detect_duplicate_wrapper_defs(&content, &std::collections::HashMap::new())
                .expect_err("a second class object drops the first one's methods");
            assert!(
                error.contains("class `Widget` is defined more than once"),
                "{error}"
            );
            assert!(error.contains("(lib.rs:10:6)"), "{error}");
            assert!(error.contains("(lib.rs:40:6)"), "{error}");
            assert!(error.contains("distinct `class = \"...\"`"), "{error}");
        }
    }

    #[test]
    fn duplicate_scan_keeps_class_members_and_s4_constructors_separate() {
        let content = concat!(
            "Widget <- new.env(parent = emptyenv())\n",
            "Widget$new <- function() .Call(C_new)\n",
            "Widget$get <- function() .Call(C_get)\n",
            "methods::setClass(\"S4Widget\", slots = c(ptr = \"externalptr\"))\n",
            "S4Widget <- function() .Call(C_new_s4)\n",
            "R6Widget <- R6::R6Class(\"R6Widget\",\n",
            "  public = list(\n",
            "    initialize = function() {}\n",
            "  )\n",
            ")\n",
            "S7Widget <- S7::new_class(\"S7Widget\",\n",
            "  constructor = function() {}\n",
            ")\n",
            "if (!base::exists(\"shared\", mode = \"function\")) {\n",
            "  shared <- function(x, ...) UseMethod(\"shared\")\n",
            "}\n",
            "if (!base::exists(\"shared\", mode = \"function\")) {\n",
            "  shared <- function(x, ...) UseMethod(\"shared\")\n",
            "}\n",
        );
        assert!(detect_duplicate_wrapper_defs(content, &std::collections::HashMap::new()).is_ok());
    }

    #[test]
    fn guarded_generics_cannot_collide_with_plain_bindings() {
        for generic in [
            concat!(
                "if (!base::exists(\"probe\", mode = \"function\")) {\n",
                "  probe <- function(x, ...) UseMethod(\"probe\")\n",
                "}\n",
            ),
            concat!(
                "if (!base::exists(\"probe\", mode = \"function\")) {\n",
                "  probe <- function(x, ...) base::UseMethod(\"probe\")\n",
                "}\n",
            ),
            concat!(
                "if (!exists(\"probe\", where = topenv(environment()), inherits = FALSE)) ",
                "methods::setGeneric(\"probe\", function(x, ...) standardGeneric(\"probe\"))\n",
            ),
            concat!(
                "if (!base::exists(\"probe\", mode = \"function\")) {\n",
                "  # No existing binding; define a plain package-local S7 generic.\n",
                "  probe <- S7::new_generic(\"probe\", \"x\", function(x, ...) S7::S7_dispatch())\n",
                "}\n",
            ),
            concat!(
                "if (!exists(\"probe\", mode = \"function\")) {\n",
                "  probe <- S7::new_generic(\"probe\", \"x\", function(x, ...) S7::S7_dispatch())\n",
                "}\n",
            ),
            concat!(
                "if (!base::inherits(base::get0(\"probe\", inherits = FALSE), \"S7_external_generic\")) {\n",
                "  probe <- S7::new_external_generic(\"pkg\", \"probe\", \"x\")\n",
                "}\n",
            ),
        ] {
            // The same generic may be emitted by many inherent/trait impls.
            let repeated = format!("{generic}{generic}");
            assert!(
                detect_duplicate_wrapper_defs(&repeated, &std::collections::HashMap::new()).is_ok(),
                "{repeated}"
            );
            let generic = format!("# Generated from Rust impl `Shape` (shape.rs:3:6)\n{generic}");
            for binding in [
                "# Generated from Rust fn `probe` (probe.rs:7:8)\n\
                 probe <- function(x) .Call(C_probe, x)\n",
                "# Generated from Rust impl `probe` (probe.rs:7:8)\n\
                 probe <- new.env(parent = emptyenv())\n",
            ] {
                // Classes precede free functions; trait impls follow them.
                for content in [format!("{generic}{binding}"), format!("{binding}{generic}")] {
                    let error =
                        detect_duplicate_wrapper_defs(&content, &std::collections::HashMap::new())
                            .expect_err("a generated binding must not mask a generic");
                    assert!(error.contains("`probe`"), "{error}");
                    assert!(error.contains("guarded generic"), "{error}");
                    assert!(error.contains("r_name"), "{error}");
                    assert!(error.contains("`Shape` (shape.rs:3:6)"), "{error}");
                    assert!(error.contains("`probe` (probe.rs:7:8)"), "{error}");
                }
            }
        }
    }

    /// A generic shared by several classes is reported with the class that
    /// declared it first, and a sidecar accessor with its field and type.
    #[test]
    fn duplicate_scan_names_first_generic_and_sidecar_producers() {
        let generic = "if (!base::exists(\"Shape_get_area\", mode = \"function\")) {\n  \
                       Shape_get_area <- function(x, ...) UseMethod(\"Shape_get_area\")\n}\n";
        let content = format!(
            "# Generated from Rust source line 4:5\n\
             # Wraps sidecar field `area` on Rust type `Shape` via `C_get` and `C_set`.\n\
             Shape_get_area <- function(x) .Call(C_get, x)\n\
             # Generated from Rust impl `Circle` (circle.rs:9:6)\n{generic}\
             # Generated from Rust impl `Square` (square.rs:9:6)\n{generic}"
        );
        let error = detect_duplicate_wrapper_defs(&content, &std::collections::HashMap::new())
            .expect_err("the generic would replace the sidecar accessor");
        assert!(
            error.contains(
                "function from sidecar field `area` on Rust type `Shape` (Rust source line 4:5)"
            ),
            "{error}"
        );
        assert!(
            error.contains("guarded generic from Rust impl `Circle` (circle.rs:9:6)"),
            "{error}"
        );
        assert!(!error.contains("Square"), "{error}");

        // Reported with the first declaration when the plain binding follows.
        let content = format!(
            "# Generated from Rust impl `Circle` (circle.rs:9:6)\n{generic}\
             # Generated from Rust impl `Square` (square.rs:9:6)\n{generic}\
             # Generated from Rust fn `Shape_get_area` (lib.rs:1:8)\n\
             Shape_get_area <- function(x) .Call(C_area, x)\n"
        );
        let error = detect_duplicate_wrapper_defs(&content, &std::collections::HashMap::new())
            .expect_err("the function would replace the generic");
        assert!(error.contains("`Circle` (circle.rs:9:6)"), "{error}");
        assert!(
            error.contains("Rust fn `Shape_get_area` (lib.rs:1:8)"),
            "{error}"
        );
        assert!(!error.contains("Square"), "{error}");
    }

    #[test]
    fn guarded_generics_recognize_quoted_operator_names() {
        let generic = concat!(
            "if (!base::exists(\"%probe%\", mode = \"function\")) {\n",
            "  `%probe%` <- function(x, ...) UseMethod(\"%probe%\")\n",
            "}\n",
        );
        let content = format!("{generic}`%probe%` <- function(x, y) .Call(C_probe, x, y)\n");
        let error = detect_duplicate_wrapper_defs(&content, &std::collections::HashMap::new())
            .expect_err("quoted assignment names must match the generic name");
        assert!(error.contains("`%probe%`"), "{error}");
    }

    #[test]
    fn duplicate_scan_ignores_local_and_non_generic_guards() {
        let content = concat!(
            "probe <- function(x) {\n",
            "  if (!base::exists(\"probe\", mode = \"function\")) {\n",
            "    probe <- function(x, ...) UseMethod(\"probe\")\n",
            "  }\n",
            "}\n",
            "if (!base::exists(\"cached\", mode = \"function\")) {\n",
            "  cached <- function(x) x\n",
            "}\n",
            "cached <- function(x) .Call(C_cached, x)\n",
        );
        assert!(detect_duplicate_wrapper_defs(content, &std::collections::HashMap::new()).is_ok());
    }

    #[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

    // region: impl blocks merged per type (#1776)

    fn widget_path() -> &'static str {
        "pkg::widgets::Widget"
    }

    fn other_widget_path() -> &'static str {
        "pkg::legacy::Widget"
    }

    /// An env-class impl block of `Widget` at `lib.rs:<line>`, with the
    /// `parts` given as raw-literal text (framed by newlines) and no
    /// settings, definitions or member names.
    fn widget_block(line: u32, head: &'static str, members: &'static str) -> ClassBlockEntry {
        ClassBlockEntry {
            rust_type: "Widget",
            type_path: widget_path,
            r_class_name: "Widget",
            source_file: "lib.rs",
            source_line: line,
            source_column: 6,
            settings: "env",
            constructor: "",
            constructor_inferred: false,
            constructor_candidates: &[],
            demoted: None,
            defines: &[],
            head,
            class_docs: "\n\n",
            class_doc_lines: "\n\n",
            members,
            member_names: &[],
            tail: "\n\n",
        }
    }

    fn merged(blocks: &[ClassBlockEntry]) -> Vec<String> {
        merge_class_blocks(blocks)
            .unwrap_or_else(|msg| panic!("{msg}"))
            .into_iter()
            .map(|f| f.content.into_owned())
            .collect()
    }

    /// The defining block's topic governs defaults from every block, while
    /// an explicit method page (including the original class page) wins.
    #[test]
    fn class_member_docs_inherit_the_defining_blocks_topic() {
        let mut first = widget_block(10, "\n.__MX_CLASS_DOCS__\nWidget <- new.env()\n", "\n\n");
        first.class_docs = "\n#' @rdname widget_api\n";
        first.defines = &["constructor"];
        let second = widget_block(
            20,
            "\n\n",
            concat!(
                "\n#' @description Author prose.\n",
                "#' @param n Author parameter.\n",
                ".__MX_CLASS_MEMBER_DEFAULT__#' @title Generated title\n",
                ".__MX_CLASS_MEMBER_DEFAULT__#' @param x An object.\n",
                ".__MX_CLASS_MEMBER_DEFAULT__#' @param missing (undocumented)\n",
                ".__MX_CLASS_MEMBER_DEFAULT__#' @rdname Widget\n",
                "#' @name Widget_origin\nWidget_origin <- function(x, n, missing) 1\n\n",
                "#' @rdname Widget\n",
                ".__MX_CLASS_MEMBER_DEFAULT__#' @param n (undocumented)\n",
                "#' @name Widget_explicit\nWidget_explicit <- function(n) 1\n\n",
                "#' @rdname own_page\n#' @order 2\n",
                "Widget_own <- function() 1\n\n",
                "#' @describeIn widget_api A described member.\n",
                "Widget_described <- function() 1\n",
            ),
        );
        let output = merged(&[second, first]).remove(0);
        assert!(
            output.contains(concat!(
                "#' @description Author prose.\n#' @param n Author parameter.\n",
                "#' @rdname widget_api\n#' @name Widget_origin\n#' @order NaN\n",
                "Widget_origin <- function(x, n, missing) 1"
            )),
            "{output}"
        );
        assert!(
            output.contains("#' @rdname Widget\n#' @param n (undocumented)"),
            "{output}"
        );
        assert!(
            output.contains("#' @rdname own_page\n#' @order 2\nWidget_own"),
            "{output}"
        );
        assert!(
            output.contains("#' @describeIn widget_api A described member.\nWidget_described"),
            "{output}"
        );
        assert!(!output.contains(CLASS_MEMBER_DEFAULT_PREFIX), "{output}");
        assert!(!output.contains("Generated title"), "{output}");
        assert!(!output.contains("@param missing"), "{output}");
    }

    #[test]
    fn class_member_docs_keep_default_page_and_author_order() {
        let member = concat!(
            ".__MX_CLASS_MEMBER_DEFAULT__#' @rdname Widget\n",
            ".__MX_CLASS_MEMBER_DEFAULT__#' @param x An object.\n",
            "#' @order 3\nWidget_value <- function(x) x\n",
        );
        assert_eq!(
            resolve_class_member_docs(member, "Widget", "Widget"),
            concat!(
                "#' @rdname Widget\n#' @param x An object.\n",
                "#' @order 3\nWidget_value <- function(x) x\n",
            )
        );
        assert_eq!(
            resolve_class_member_docs(member, "Widget", "widget_api"),
            "#' @rdname widget_api\n#' @order 3\nWidget_value <- function(x) x\n"
        );
    }

    /// The docs-only block of a class the package names and builds itself
    /// is written when an impl block's docs say something, and dropped up
    /// to its `NULL` when they name a page at most (#1918).
    #[test]
    fn docs_only_class_block_needs_something_to_say() {
        const HEAD: &str = "\n.__MX_CLASS_DOCS_ONLY__\n\
                            .__MX_CLASS_DEFAULT__#' @title widget_rec S3 Class\n\
                            .__MX_CLASS_DEFAULT__#' @name widget_rec\n\
                            .__MX_CLASS_DOCS__\n.__MX_CLASS_DOC_LINES__\nNULL\n\n";
        let with_docs = |first_docs: &'static str, second_docs: &'static str| {
            let mut first = widget_block(10, HEAD, "\n# first\n");
            first.class_docs = first_docs;
            let mut second = widget_block(20, "\n\n", "\n# second\n");
            second.class_docs = second_docs;
            merged(&[first, second]).remove(0)
        };

        let silent = with_docs("\n\n", "\n\n");
        assert!(!silent.contains("widget_rec"), "{silent}");
        assert!(!silent.contains("NULL"), "{silent}");
        assert!(
            silent.contains("# first") && silent.contains("# second"),
            "{silent}"
        );

        let page_only = with_docs("\n#' @rdname widget_rec\n", "\n\n");
        assert!(!page_only.contains("NULL"), "{page_only}");

        let documented = with_docs("\n\n", "\n#' @description Records the package builds.\n");
        assert!(
            documented.contains(
                "#' @title widget_rec S3 Class\n#' @name widget_rec\n\
                 #' @description Records the package builds.\nNULL\n"
            ),
            "{documented}"
        );

        let titled = with_docs(
            "\n\n",
            "\n#' @title Package records\n#' @description Records.\n",
        );
        assert!(!titled.contains("S3 Class"), "{titled}");
        assert!(titled.contains("#' @title Package records\n"), "{titled}");
    }

    #[test]
    fn merge_defines_the_class_once_with_every_blocks_members() {
        let mut ctor = widget_block(
            10,
            "\n#' Widget\n.__MX_CLASS_DOC_LINES__\n#' @export\nWidget <- new.env()\n",
            "\nWidget$get <- function() 1\n",
        );
        ctor.defines = &["a constructor"];
        ctor.class_doc_lines = "\n#' @importFrom lifecycle deprecate_warn\n";
        ctor.tail = "\n`$.Widget` <- function(self, name) NULL\n";
        let mut more = widget_block(
            40,
            "\n#' Widget\n.__MX_CLASS_DOC_LINES__\n#' @export\nWidget <- new.env()\n",
            "\nWidget$set <- function() 2\n",
        );
        more.class_doc_lines =
            "\n#' @importFrom lifecycle deprecate_warn\n#' @importFrom lifecycle badge\n";
        // The registration order of the blocks doesn't matter.
        let classes = merged(&[more, ctor]);
        assert_eq!(classes.len(), 1);
        assert_eq!(
            classes[0],
            "# Generated from Rust impl `Widget` (lib.rs:10:6)\n\
             #' Widget\n\
             #' @importFrom lifecycle deprecate_warn\n\
             #' @importFrom lifecycle badge\n\
             #' @export\n\
             Widget <- new.env()\n\
             Widget$get <- function() 1\n\
             \n\
             # Generated from Rust impl `Widget` (lib.rs:40:6)\n\
             Widget$set <- function() 2\n\
             \n\
             # Generated from Rust impl `Widget` (lib.rs:10:6)\n\
             `$.Widget` <- function(self, name) NULL"
        );
    }

    #[test]
    fn merge_defines_the_class_from_the_block_with_the_constructor() {
        let first = widget_block(10, "\nWidget <- new.env() # first\n", "\nWidget$a <- 1\n");
        let mut ctor = widget_block(40, "\nWidget <- new.env() # ctor\n", "\nWidget$b <- 2\n");
        ctor.defines = &["a constructor"];
        let classes = merged(&[first, ctor]);
        assert_eq!(
            classes[0],
            "# Generated from Rust impl `Widget` (lib.rs:40:6)\n\
             Widget <- new.env() # ctor\n\
             \n\
             # Generated from Rust impl `Widget` (lib.rs:10:6)\n\
             Widget$a <- 1\n\
             \n\
             # Generated from Rust impl `Widget` (lib.rs:40:6)\n\
             Widget$b <- 2"
        );
        // Without one, the first block in source order defines the class.
        let first = widget_block(10, "\nWidget <- new.env() # first\n", "\n\n");
        let second = widget_block(40, "\nWidget <- new.env() # second\n", "\n\n");
        assert_eq!(
            merged(&[second, first])[0],
            "# Generated from Rust impl `Widget` (lib.rs:10:6)\nWidget <- new.env() # first"
        );
    }

    #[test]
    fn merge_keeps_one_block_as_written() {
        // The head's blank last line separates it from the members.
        let mut block = widget_block(
            10,
            "\n#' Widget\n.__MX_CLASS_DOC_LINES__\n#' @export\nWidget <- new.env()\n\n",
            "\nWidget$get <- function() 1\n",
        );
        block.tail = "\nWidget$lock()\n";
        assert_eq!(
            merged(&[block])[0],
            "# Generated from Rust impl `Widget` (lib.rs:10:6)\n\
             #' Widget\n\
             #' @export\n\
             Widget <- new.env()\n\
             \n\
             Widget$get <- function() 1\n\
             Widget$lock()"
        );
    }

    #[test]
    fn merge_refuses_blocks_with_different_settings() {
        // `@noRd` on one block only: the other's methods would be documented
        // on a page that does not exist.
        let mut hidden = widget_block(10, "\n\n", "\n\n");
        hidden.settings = "env, @noRd";
        let plain = widget_block(40, "\n\n", "\n\n");
        let msg = merge_class_blocks(&[hidden, plain])
            .err()
            .expect("settings differ");
        assert!(
            msg.contains("the impl blocks of `Widget` disagree on the class settings"),
            "{msg}"
        );
        assert!(
            msg.contains("`env, @noRd` on `impl Widget` (lib.rs:10)"),
            "{msg}"
        );
        assert!(msg.contains("`env` on `impl Widget` (lib.rs:40)"), "{msg}");
    }

    #[test]
    fn merge_refuses_two_defining_blocks() {
        let mut ctor = widget_block(10, "\n\n", "\n\n");
        ctor.defines = &["a constructor"];
        let mut props = widget_block(40, "\n\n", "\n\n");
        props.defines = &["a constructor", "S7 properties"];
        let msg = merge_class_blocks(&[ctor, props])
            .err()
            .expect("two blocks define the class");
        assert!(
            msg.contains(
                "two impl blocks of `Widget` each define the class: `impl Widget` (lib.rs:10) \
                 has a constructor, `impl Widget` (lib.rs:40) has a constructor and S7 \
                 properties."
            ),
            "{msg}"
        );
        assert!(
            msg.contains("move what `impl Widget` (lib.rs:40) has into `impl Widget` (lib.rs:10)"),
            "{msg}"
        );
    }

    #[test]
    fn merge_refuses_a_member_bound_by_two_blocks() {
        let mut first = widget_block(10, "\n\n", "\n\n");
        first.member_names = &["`Widget$get`", "`Widget$set`"];
        let mut second = widget_block(40, "\n\n", "\n\n");
        second.member_names = &["`Widget$get`"];
        let msg = merge_class_blocks(&[first, second])
            .err()
            .expect("`$get` is bound twice");
        assert!(
            msg.contains(
                "two impl blocks of `Widget` define `Widget$get`: `impl Widget` (lib.rs:10) \
                 and `impl Widget` (lib.rs:40)."
            ),
            "{msg}"
        );
        assert!(!msg.contains("Widget$set"), "{msg}");
    }

    #[test]
    fn merge_refuses_two_types_with_one_class_name() {
        // Same identifier, different modules: two types, not two blocks of one.
        let mine = widget_block(10, "\nWidget <- new.env()\n", "\n\n");
        let mut theirs = widget_block(40, "\nWidget <- new.env()\n", "\n\n");
        theirs.type_path = other_widget_path;
        theirs.source_file = "legacy.rs";
        let msg = merge_class_blocks(&[mine, theirs])
            .err()
            .expect("one class, two types");
        assert!(
            msg.contains(
                "R class `Widget` is claimed by two Rust types, `pkg::legacy::Widget` \
                 (`impl Widget` (legacy.rs:40)) and `pkg::widgets::Widget` \
                 (`impl Widget` (lib.rs:10))"
            ),
            "{msg}"
        );
    }

    /// A class head as the class generators write it: generated defaults, the
    /// docs and doc-lines markers, then the class object.
    const DOCUMENTED_HEAD: &str = "\n\
        .__MX_CLASS_DEFAULT__#' @title Widget Class\n\
        .__MX_CLASS_DEFAULT__#' @name Widget\n\
        .__MX_CLASS_DEFAULT__#' @rdname Widget\n\
        .__MX_CLASS_DOCS__\n\
        .__MX_CLASS_DEFAULT__#' @param .ptr Internal pointer.\n\
        #' @source Generated by miniextendr\n\
        .__MX_CLASS_DOC_LINES__\n\
        .__MX_CLASS_DEFAULT__#' @export\n\
        Widget <- new.env()\n";

    #[test]
    fn merge_writes_every_blocks_docs_after_the_definers() {
        let mut ctor = widget_block(40, DOCUMENTED_HEAD, "\n\n");
        ctor.defines = &["a constructor"];
        ctor.class_docs = "\n#' @description Widgets hold a value.\n#' @importFrom stats median\n";
        let mut first = widget_block(10, DOCUMENTED_HEAD, "\n\n");
        first.class_docs = "\n#' @description More methods.\n#' @details One.\n#'\n#' }\n\
                            #' @importFrom stats median\n#' @export\n";
        let mut last = widget_block(70, DOCUMENTED_HEAD, "\n\n");
        last.class_docs = "\n#' @details Two.\n#'\n#' }\n#' @param .ptr Pointer.\n";
        let classes = merged(&[last, first, ctor]);
        // The defining block's docs, then the others' in source order; an
        // identical tag once, the blank and `}` lines of two tags each kept;
        // a default another block writes itself gives way.
        assert_eq!(
            classes[0],
            "# Generated from Rust impl `Widget` (lib.rs:40:6)\n\
             #' @title Widget Class\n\
             #' @name Widget\n\
             #' @rdname Widget\n\
             #' @description Widgets hold a value.\n\
             #' @importFrom stats median\n\
             #' @description More methods.\n\
             #' @details One.\n\
             #'\n\
             #' }\n\
             #' @export\n\
             #' @details Two.\n\
             #'\n\
             #' }\n\
             #' @param .ptr Pointer.\n\
             #' @source Generated by miniextendr\n\
             Widget <- new.env()"
        );
    }

    #[test]
    fn merge_takes_the_title_from_any_block() {
        let mut ctor = widget_block(10, DOCUMENTED_HEAD, "\n\n");
        ctor.defines = &["a constructor"];
        let mut more = widget_block(40, DOCUMENTED_HEAD, "\n\n");
        more.class_docs = "\n#' @title Widgets\n#' @rdname Widget\n";
        let classes = merged(&[ctor, more]);
        assert!(
            classes[0].starts_with(
                "# Generated from Rust impl `Widget` (lib.rs:10:6)\n\
                 #' @name Widget\n\
                 #' @title Widgets\n\
                 #' @rdname Widget\n\
                 #' @param .ptr Internal pointer.\n"
            ),
            "{}",
            classes[0]
        );
    }

    #[test]
    fn merge_drops_a_member_default_another_block_documents() {
        let mut ctor = widget_block(10, DOCUMENTED_HEAD, "\n\n");
        ctor.defines = &["a constructor"];
        ctor.class_docs = "\n#' @field doubled Twice the value.\n#' @inheritParams widget_ops\n";
        let mut more = widget_block(40, DOCUMENTED_HEAD, "\n\n");
        more.class_doc_lines = "\n.__MX_CLASS_DEFAULT__#' @field doubled Active binding.\n\
                                .__MX_CLASS_DEFAULT__#' @field halved Active binding.\n";
        let class = &merged(&[ctor, more])[0];
        assert!(
            class.contains("#' @field doubled Twice the value.\n"),
            "{class}"
        );
        assert!(!class.contains("@field doubled Active binding."), "{class}");
        assert!(
            class.contains("#' @field halved Active binding.\n"),
            "{class}"
        );
        // The defining block's own docs were seen when its defaults were
        // generated: its `@param .ptr` default stays.
        assert!(
            class.contains("#' @param .ptr Internal pointer.\n"),
            "{class}"
        );
    }

    #[test]
    fn merge_refuses_two_titles() {
        let mut ctor = widget_block(10, DOCUMENTED_HEAD, "\n\n");
        ctor.defines = &["a constructor"];
        ctor.class_docs = "\n#' @title Widgets\n";
        let mut more = widget_block(40, DOCUMENTED_HEAD, "\n\n");
        more.class_docs = "\n#' @title Gadgets\n";
        let same = widget_block(70, DOCUMENTED_HEAD, "\n\n");
        let msg = merge_class_blocks(&[ctor, more, same])
            .err()
            .expect("two titles");
        assert_eq!(
            msg,
            "miniextendr: the impl blocks of `Widget` give the class two titles: \
             `impl Widget` (lib.rs:10) has `@title Widgets`, `impl Widget` (lib.rs:40) has \
             `@title Gadgets`. A type's impl blocks merge into one class with one help \
             page: keep one `@title` (#1776)."
        );
    }

    #[test]
    fn merge_refuses_a_page_other_than_the_definers() {
        let mut ctor = widget_block(10, DOCUMENTED_HEAD, "\n\n");
        ctor.defines = &["a constructor"];
        let mut more = widget_block(40, DOCUMENTED_HEAD, "\n\n");
        more.class_docs = "\n#' @rdname widget_ops\n";
        let msg = merge_class_blocks(&[ctor, more]).err().expect("two pages");
        assert_eq!(
            msg,
            "miniextendr: the impl blocks of `Widget` put the class on two help pages: \
             `impl Widget` (lib.rs:10), which defines the class, has `@rdname Widget`, and \
             `impl Widget` (lib.rs:40) has `@rdname widget_ops`. The block that defines \
             the class decides its page: move `@rdname widget_ops` into `impl Widget` \
             (lib.rs:10), or remove it (#1776)."
        );
    }

    #[test]
    fn merge_reports_every_problem_at_once() {
        let mut first = widget_block(10, "\n\n", "\n\n");
        first.defines = &["a constructor"];
        first.member_names = &["`Widget$get`"];
        let mut second = widget_block(40, "\n\n", "\n\n");
        second.defines = &["a constructor"];
        second.member_names = &["`Widget$get`"];
        second.settings = "env, internal";
        let msg = merge_class_blocks(&[first, second])
            .err()
            .expect("three problems");
        assert_eq!(msg.lines().count(), 3, "{msg}");
    }

    // endregion

    // region: the constructor decided per type

    /// A block of `Widget` that infers `from_value` as its constructor: its
    /// own rendering defines the class with it, its `demoted` one keeps it a
    /// static method.
    fn inferring_block(line: u32) -> ClassBlockEntry {
        let mut demoted = widget_block(
            line,
            "\nWidget <- new.env() # no constructor\n",
            "\nWidget$from_value <- function(x) 1\n",
        );
        demoted.constructor_candidates = &["from_value"];
        let mut block = widget_block(
            line,
            "\nWidget <- new.env() # from_value\nWidget$new <- function(x) 1\n",
            "\n\n",
        );
        block.constructor = "from_value";
        block.constructor_inferred = true;
        block.constructor_candidates = &["from_value"];
        block.defines = &["the inferred constructor `from_value`"];
        block.demoted = Some(Box::leak(Box::new(demoted)));
        block
    }

    #[test]
    fn a_lone_candidate_is_the_constructor_whichever_block_has_it() {
        let methods = widget_block(10, "\nWidget <- new.env() # first\n", "\nWidget$get <- 2\n");
        let classes = merged(&[methods, inferring_block(40)]);
        assert_eq!(
            classes[0],
            "# Generated from Rust impl `Widget` (lib.rs:40:6)\n\
             Widget <- new.env() # from_value\n\
             Widget$new <- function(x) 1\n\
             \n\
             # Generated from Rust impl `Widget` (lib.rs:10:6)\n\
             Widget$get <- 2"
        );
    }

    #[test]
    fn a_declared_constructor_keeps_the_candidate_a_static_method() {
        let mut new = widget_block(10, "\nWidget <- new.env() # new\n", "\n\n");
        new.constructor = "new";
        new.constructor_candidates = &["from_file"];
        new.defines = &["a constructor"];
        let classes = merged(&[inferring_block(40), new]);
        assert_eq!(
            classes[0],
            "# Generated from Rust impl `Widget` (lib.rs:10:6)\n\
             Widget <- new.env() # new\n\
             \n\
             # Generated from Rust impl `Widget` (lib.rs:40:6)\n\
             Widget$from_value <- function(x) 1"
        );
    }

    #[test]
    fn candidates_in_two_blocks_without_a_declared_constructor_are_refused() {
        let mut other = widget_block(10, "\n\n", "\n\n");
        other.constructor_candidates = &["empty", "from_file"];
        let msg = merge_class_blocks(&[other, inferring_block(40)])
            .err()
            .expect("three candidates");
        assert!(
            msg.contains(
                "`Widget` has several methods that could be its constructor, and none is \
                 declared: `empty`, `from_file` in `impl Widget` (lib.rs:10); `from_value` in \
                 `impl Widget` (lib.rs:40)."
            ),
            "{msg}"
        );
        assert!(msg.contains("`#[miniextendr(env(constructor))]`"), "{msg}");
        // The candidates are the only problem reported.
        assert_eq!(msg.lines().count(), 1, "{msg}");
    }

    // endregion
}
// endregion