miniextendr_macros/

r_preconditions.rs

//! R-side precondition generation for type checking.
//!
//! Generates argument checks in R wrapper functions that run BEFORE the `.Call()` boundary.
//! This gives users clear, idiomatic R error messages with proper stack traces instead of
//! Rust panic messages.
//!
//! Each check tests ONE thing and names the requirement it enforces:
//!
//! ```r
//! add <- function(a, b) {
//!   if (!isTRUE(is.integer(a))) .miniextendr_arg_error("a", "must be integer")
//!   if (!isTRUE(length(a) == 1L)) .miniextendr_arg_error("a", "must have length 1")
//!   if (!isTRUE(is.integer(b))) .miniextendr_arg_error("b", "must be integer")
//!   if (!isTRUE(length(b) == 1L)) .miniextendr_arg_error("b", "must have length 1")
//!   .Call(C_add, .call = sys.call(), a, b)
//! }
//! ```
//!
//! A failing check calls the preamble helper `.miniextendr_arg_error`
//! (`miniextendr-api/src/registry.rs`), which raises the same condition as a
//! failed Rust conversion: the crate's `conversion_error_class`, `rust_error`,
//! `kind = "conversion"` and `e$param`, with the message `'a' must be integer`
//! (#1591). A passing check costs one `isTRUE()` test; the condition is only
//! built on failure. `isTRUE()` keeps `stopifnot()`'s failure semantics (`NA`
//! fails too), and the guards are cheaper than the `stopifnot()` call they
//! replace. [`conversion_expectation`] gives the Rust conversion the same
//! vocabulary for its messages.

use std::collections::{HashMap, HashSet};

use crate::naming::r_string_escape;

/// A single R-side check on one parameter: a requirement and the R condition
/// enforcing it.
///
/// Formatted as a guard (see [`RAssertion::to_guard`]):
/// `if (!isTRUE(is.numeric(x))) .miniextendr_arg_error("x", "must be numeric")`.
struct RAssertion {
    /// R name of the checked parameter (`e$param` on failure).
    param: String,
    /// What the parameter must satisfy, without the parameter name
    /// (`must be numeric`). The condition message is `'<param>' <requirement>`.
    requirement: String,
    /// R expression that must evaluate to `TRUE` for the check to pass.
    condition: String,
    /// The author's own condition message (`message = "..."` on `inherits` /
    /// `not_inherits` / `no_na`; an `inherits` message also on the
    /// parameter's type checks),
    /// used verbatim instead of `'<param>' <requirement>`.
    message: Option<String>,
}

impl RAssertion {
    /// Create a new assertion on `param` with its requirement and R condition expression.
    fn new(
        param: impl Into<String>,
        requirement: impl Into<String>,
        condition: impl Into<String>,
    ) -> Self {
        Self {
            param: param.into(),
            requirement: requirement.into(),
            condition: condition.into(),
            message: None,
        }
    }

    /// Use `message` verbatim as the condition message of a failure.
    fn with_message(mut self, message: Option<&String>) -> Self {
        self.message = message.cloned();
        self
    }

    /// The condition message a failure raises: the author's message, else
    /// `'<param>' <requirement>`.
    #[cfg(test)]
    fn message(&self) -> String {
        match &self.message {
            Some(message) => message.clone(),
            None => format!("'{}' {}", self.param, self.requirement),
        }
    }

    /// Format as a guard that raises an argument error on failure:
    /// `if (!isTRUE(condition)) .miniextendr_arg_error("param", "requirement")`,
    /// or with the author's message
    /// `if (!isTRUE(condition)) .miniextendr_arg_error("param", message = "...")`.
    ///
    /// `call` is the call the error is attributed to. `None` leaves the
    /// helper's default, the wrapper's own call (what `stopifnot()` reported);
    /// a `call = caller` wrapper passes `.mx_call` (#1548). Next to a named
    /// `message` the call is named too: positionally it would bind to `what`.
    fn to_guard(&self, call: Option<&str>) -> String {
        match &self.message {
            None => {
                let call_arg = call.map(|c| format!(", {c}")).unwrap_or_default();
                format!(
                    "if (!isTRUE({})) .miniextendr_arg_error(\"{}\", \"{}\"{})",
                    self.condition, self.param, self.requirement, call_arg
                )
            }
            Some(message) => {
                let call_arg = call.map(|c| format!(", call = {c}")).unwrap_or_default();
                format!(
                    "if (!isTRUE({})) .miniextendr_arg_error(\"{}\", message = \"{}\"{})",
                    self.condition,
                    self.param,
                    r_string_escape(message),
                    call_arg
                )
            }
        }
    }

    /// Wrap for nullable: prepend `is.null(param) || ` to the condition,
    /// and adjust the requirement to mention NULL.
    fn nullable(self) -> Self {
        let requirement = if let Some(rest) = self.requirement.strip_prefix("must be ") {
            // "must be character" → "must be NULL or character"
            format!("must be NULL or {rest}")
        } else if let Some(rest) = self.requirement.strip_prefix("must have ") {
            // "must have length 1" → "must be NULL or have length 1"
            format!("must be NULL or have {rest}")
        } else {
            format!("{} (or NULL)", self.requirement)
        };
        Self {
            condition: format!("is.null({}) || {}", self.param, self.condition),
            param: self.param,
            requirement,
            message: self.message,
        }
    }
}

/// Per-function knobs that influence precondition codegen.
///
/// Coercion preserves numeric input types, extends `bool` / `Vec<bool>`
/// checks to accept integers as well as logicals, and widens the native
/// `i32` / `Vec<i32>` gates to whole-number doubles. Other types keep their checks.
/// Strict input conversion remains enforced in Rust, where range and precision
/// failures can carry contextual diagnostics.
#[derive(Clone, Default)]
pub struct PreconditionOptions {
    /// `coerce` knob is active for all parameters (`coerce_all`).
    pub coerce_all: bool,
    /// R-normalized names of parameters with a per-param `coerce` attribute.
    pub coerce_params: HashSet<String>,
    /// Checks the author named per parameter (`inherits`, `not_inherits`,
    /// `no_na`), keyed by R-normalized parameter name.
    pub explicit: HashMap<String, ExplicitChecks>,
    /// R-normalized names of the parameters whose type-derived checks are
    /// dropped (each one resolved by [`resolve_type_checks`]). Their
    /// [`explicit`](Self::explicit) checks are still emitted.
    pub unchecked: HashSet<String>,
    /// The R formal of each parameter (#1842): the name every check, every
    /// argument error and every map above uses. Without a declared formal,
    /// the Rust name without leading underscores.
    pub formals: crate::r_wrapper_builder::Formals,
}

impl PreconditionOptions {
    /// Returns `true` if the parameter `r_name` is coerced (function-wide or
    /// per-param).
    fn is_coerced(&self, r_name: &str) -> bool {
        self.coerce_all || self.coerce_params.contains(r_name)
    }
}

// region: which parameters keep their type-derived checks (#1566 §2)

/// Whether one parameter keeps its type-derived R-side checks, from every
/// spelling that can decide it, most specific first; the first that speaks
/// wins:
///
/// 1. `param`: a `Checked<T>` / `Unchecked<T>` marker, the per-parameter
///    `preconditions` / `no_preconditions`, or a method's
///    `preconditions(x)` / `no_preconditions(x)` list (merged at parse time,
///    where a marker and a keyword that disagree are an error);
/// 2. `item`: the function's or method's own `preconditions` /
///    `no_preconditions`;
/// 3. `impl_level`: the impl block's (`None` for a free function);
/// 4. `crate_default`: `[package.metadata.miniextendr] preconditions`;
/// 5. `no_preconditions_default`: the `no-preconditions-default` feature;
/// 6. otherwise the checks are kept.
///
/// `Some(true)` everywhere means "keep".
pub(crate) fn resolve_type_checks(
    param: Option<bool>,
    item: Option<bool>,
    impl_level: Option<bool>,
    crate_default: Option<bool>,
    no_preconditions_default: bool,
) -> bool {
    param.unwrap_or_else(|| {
        resolve_item_type_checks(item, impl_level, crate_default, no_preconditions_default)
    })
}

/// [`resolve_type_checks`] without a per-parameter spelling: whether an item
/// (function or method) keeps its type-derived checks by default, ranks 2 to
/// 6. The condition-raise codegen keys on this item-level decision.
pub(crate) fn resolve_item_type_checks(
    item: Option<bool>,
    impl_level: Option<bool>,
    crate_default: Option<bool>,
    no_preconditions_default: bool,
) -> bool {
    item.or(impl_level)
        .or(crate_default)
        .unwrap_or(!no_preconditions_default)
}

/// The R formals (`formals`) of the parameters of `inputs` whose
/// type-derived checks are dropped, given each one's rank-1 decision
/// (`param`, keyed by Rust name) and the item, impl and crate defaults
/// ([`resolve_type_checks`]; the feature is this macro crate's
/// `no-preconditions-default`).
pub(crate) fn unchecked_params(
    inputs: &syn::punctuated::Punctuated<syn::FnArg, syn::Token![,]>,
    formals: &crate::r_wrapper_builder::Formals,
    param: impl Fn(&str) -> Option<bool>,
    item: Option<bool>,
    impl_level: Option<bool>,
    crate_default: Option<bool>,
) -> HashSet<String> {
    inputs
        .iter()
        .filter_map(|arg| {
            let syn::FnArg::Typed(pt) = arg else {
                return None;
            };
            let syn::Pat::Ident(pat_ident) = pt.pat.as_ref() else {
                return None;
            };
            let name = crate::naming::ident_name(&pat_ident.ident);
            let keep = resolve_type_checks(
                param(&name),
                item,
                impl_level,
                crate_default,
                cfg!(feature = "no-preconditions-default"),
            );
            (!keep).then(|| formals.of(&name))
        })
        .collect()
}

/// Whether a parameter type has type-derived R-side checks at all, i.e.
/// whether `Checked` / `Unchecked` and the per-parameter keywords have
/// anything to keep or drop (`SEXP`, `Missing<T>`, `ExternalPtr<T>`,
/// `&Dots` and unknown types have none).
pub(crate) fn has_type_check(ty: &syn::Type) -> bool {
    r_check_for_type(ty).is_some()
}

// endregion

/// R-side checks the author asked for by name on one parameter, rather than
/// ones derived from its Rust type.
///
/// Spelled `#[miniextendr(inherits = "cls", not_inherits = "bad", no_na)]` on
/// a standalone fn parameter, or `inherits(x = "cls")` /
/// `not_inherits(x = "bad")` / `no_na(x)` on an impl or trait method. They
/// are the same kind of guards as the type checks, raising the same argument
/// error. The class checks run before the parameter's type checks, so a value
/// of the wrong class gets the class message whatever its type: `inherits`
/// first, then `not_inherits` (#1815). That order matters for the classes a
/// `not_inherits` typically refuses: `is.numeric()` is `FALSE` for a
/// `difftime`, `Date` or `POSIXt`, so after an `AsNumeric` type check the
/// refusal would never be reached. An `inherits` message also replaces the
/// messages of the parameter's type checks; a `not_inherits` message does
/// not, since a value that passes it is of none of the refused classes and is
/// judged by its type. The NA check runs after the type checks, with its own
/// message. All survive `no_preconditions`: the Rust conversion does not
/// repeat them, so dropping them would change what the function accepts.
///
/// `no_na` also has a Rust half. A type can read more inputs as missing than
/// `anyNA()` sees (the reading markers `AsNumeric*` / `AsCharacter*` read the
/// text `"NA"`, blank strings, a factor `NA` level as `NA`), so the C wrapper
/// checks the converted value too (`TryFromSexp::__mx_has_na`, see
/// `RustConversionBuilder::with_no_na`) and raises the same condition with
/// the same message ([`no_na_message`]). An `Either` parameter has only the
/// Rust half: the arm the value converted to checks the input
/// ([`no_na_checked_after_conversion`]).
///
/// Each check can carry the author's own condition message
/// (`inherits(class = "cls", message = "...")`,
/// `not_inherits(class = "bad", message = "...")`, `no_na(message = "...")`;
/// method level `inherits(x(class = "cls", message = "..."))`,
/// `not_inherits(x(class = "bad", message = "..."))`,
/// `no_na(x(message = "..."))`), used verbatim in place of the generated
/// `'x' must inherit from 'cls'`. The condition is otherwise the same.
///
/// An `inherits` check can also give a value that fails it a message chosen
/// by the value's class (#1824): `inherits(class = "cls",
/// when(class = "data.frame", message = "..."))`, method level
/// `inherits(x(class = "cls", when(class = "data.frame", message = "...")))`
/// ([`InheritsHint`]).
#[derive(Clone, Debug, Default, PartialEq, Eq)]
pub struct ExplicitChecks {
    /// `inherits = "cls"` / `inherits("a", "b")`: the argument must inherit
    /// from at least one of these classes (`inherits(x, c(...))`).
    pub inherits: Option<Vec<String>>,
    /// `message = "..."` in `inherits(...)`: the message of a failed class
    /// check, for all of its classes, and of that parameter's R type checks.
    /// Only set together with `inherits`.
    pub inherits_message: Option<String>,
    /// `when(class = "...", message = "...")` in `inherits(...)`: the
    /// messages a value that fails the `inherits` check gets for its class,
    /// in the order written. Only set together with `inherits`.
    pub inherits_hints: Vec<InheritsHint>,
    /// `not_inherits = "cls"` / `not_inherits("a", "b")`: the argument must
    /// inherit from none of these classes (`!inherits(x, c(...))`, #1815).
    pub not_inherits: Option<Vec<String>>,
    /// `message = "..."` in `not_inherits(...)`: the message of a failed
    /// `not_inherits` check, for all of its classes. Unlike the `inherits`
    /// message it leaves the type checks' messages alone. Only set together
    /// with `not_inherits`.
    pub not_inherits_message: Option<String>,
    /// `no_na`: the argument must not contain `NA` (`!anyNA(x)`, so `NaN`
    /// is refused too, as `is.na()` does), nor a value its type reads as `NA`
    /// (checked in Rust after the conversion). For an `Either`, both checks
    /// run in Rust, by the arm the value converted to.
    pub no_na: bool,
    /// `no_na(message = "...")`: the message of a failed NA check. Only set
    /// together with `no_na`.
    pub no_na_message: Option<String>,
}

impl ExplicitChecks {
    /// Whether any check is requested.
    pub fn is_empty(&self) -> bool {
        self.inherits.is_none() && self.not_inherits.is_none() && !self.no_na
    }

    /// Merge `other` into `self` (a parameter may carry several attributes).
    /// The `inherits` hints of `other` follow those of `self`, so the hints
    /// keep the order they are written in.
    ///
    /// Fails when both give a message for the same check; the error names
    /// the check.
    pub fn merge(&mut self, other: ExplicitChecks) -> Result<(), String> {
        merge_message(
            &mut self.inherits_message,
            other.inherits_message,
            "inherits",
        )?;
        merge_message(
            &mut self.not_inherits_message,
            other.not_inherits_message,
            "not_inherits",
        )?;
        merge_message(&mut self.no_na_message, other.no_na_message, "no_na")?;
        if let Some(classes) = other.inherits {
            self.inherits.get_or_insert_with(Vec::new).extend(classes);
        }
        self.inherits_hints.extend(other.inherits_hints);
        if let Some(classes) = other.not_inherits {
            self.not_inherits
                .get_or_insert_with(Vec::new)
                .extend(classes);
        }
        self.no_na |= other.no_na;
        Ok(())
    }

    /// The error for a parameter whose checks contradict each other: a class
    /// both in `inherits` and in `not_inherits`, which no argument could
    /// satisfy through that class, or an `inherits` class in a `when(...)`
    /// hint, whose message could never be shown (a value of that class
    /// passes `inherits`). `None` when they agree.
    ///
    /// A hint class may also be a `not_inherits` class: a value of that
    /// class alone gets the hint, and one that also inherits from a required
    /// class passes the hint and `inherits` and is refused by `not_inherits`.
    ///
    /// Run once every attribute of the parameter is merged: the
    /// `inherits = "cls"` spelling adds its class without a merge, and a
    /// hint can name a class that another attribute requires.
    pub fn class_conflict(&self, param: &str) -> Option<String> {
        let required = self.inherits.as_deref().unwrap_or_default();
        if let Some(class) = self
            .not_inherits
            .iter()
            .flatten()
            .find(|c| required.contains(c))
        {
            return Some(format!(
                "class `{class}` is in both `inherits` and `not_inherits` on parameter `{param}`; \
                 name it in only one of them"
            ));
        }
        let class = self
            .inherits_hints
            .iter()
            .flat_map(|hint| &hint.classes)
            .find(|c| required.contains(c))?;
        Some(format!(
            "class `{class}` is in both `inherits` and a `when(...)` hint on parameter \
             `{param}`; a value of that class passes `inherits`, so the hint would never be \
             shown: drop it from `when(...)`"
        ))
    }

    /// The class checks (`inherits`, then `not_inherits`) for parameter
    /// `param` of type `ty`, which run before the parameter's type checks.
    /// Empty without either.
    ///
    /// The `inherits` hints come first, one check each in the order written,
    /// so a refused value gets the first hint naming one of its classes:
    /// `inherits(p, <required>) || !inherits(p, <hint classes>)`, failing
    /// with the hint's message. A value that passes `inherits` passes every
    /// hint, so a hint changes the message of a refusal, never what is
    /// accepted.
    ///
    /// An `Option<T>` / `Missing<T>` parameter passes `NULL` / an omitted
    /// argument (see [`guarded`]).
    fn class_assertions(&self, param: &str, ty: &syn::Type) -> Vec<RAssertion> {
        let mut out = Vec::new();
        if let Some(classes) = &self.inherits {
            let (what, class_arg) = class_list_r(classes);
            for hint in &self.inherits_hints {
                let (_, hint_arg) = class_list_r(&hint.classes);
                out.push(
                    RAssertion::new(
                        param,
                        format!("must inherit from {what}"),
                        format!("inherits({param}, {class_arg}) || !inherits({param}, {hint_arg})"),
                    )
                    .with_message(Some(&hint.message)),
                );
            }
            out.push(
                RAssertion::new(
                    param,
                    format!("must inherit from {what}"),
                    format!("inherits({param}, {class_arg})"),
                )
                .with_message(self.inherits_message.as_ref()),
            );
        }
        if let Some(classes) = &self.not_inherits {
            let (what, class_arg) = class_list_r(classes);
            out.push(
                RAssertion::new(
                    param,
                    format!("must not inherit from {what}"),
                    format!("!inherits({param}, {class_arg})"),
                )
                .with_message(self.not_inherits_message.as_ref()),
            );
        }
        guarded(param, ty, out)
    }

    /// The NA check (`no_na`) for parameter `param` of type `ty`, which runs
    /// after the parameter's type checks, with its own message. Empty without
    /// `no_na`, and for an `Either` parameter that is not a choice parameter
    /// (`choice`: `match_arg` / `choices`), whose NA check runs in Rust after
    /// the conversion ([`no_na_checked_after_conversion`]).
    ///
    /// An `Option<T>` / `Missing<T>` parameter passes `NULL` / an omitted
    /// argument (see [`guarded`]).
    fn value_assertions(&self, param: &str, ty: &syn::Type, choice: bool) -> Vec<RAssertion> {
        let mut out = Vec::new();
        if self.no_na && (choice || !no_na_checked_after_conversion(ty)) {
            out.push(
                RAssertion::new(param, no_na_requirement(ty), format!("!anyNA({param})"))
                    .with_message(self.no_na_message.as_ref()),
            );
        }
        guarded(param, ty, out)
    }

    /// The message of the parameter's R type checks: the `inherits` message,
    /// when there is one. Without it the type checks keep their generated
    /// messages. A `not_inherits` message is not one: a value that passed
    /// `not_inherits` is of none of the refused classes, so its type check
    /// keeps its own wording.
    fn type_check_message(&self) -> Option<&String> {
        self.inherits_message.as_ref()
    }
}

/// One `when(class = "...", message = "...")` hint of an `inherits` check
/// (#1824): the message a value gets when it fails the check and inherits
/// from one of `classes`, in place of the check's own. A `data.frame` passed
/// where a model object is expected can be told which function takes a data
/// frame, while `NULL` or a number gets the plain refusal.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct InheritsHint {
    /// The classes the hint is for (any one of them).
    pub classes: Vec<String>,
    /// The condition message, used verbatim.
    pub message: String,
}

/// A class check's classes in R: the quoted list for its message
/// (`'a', 'b' or 'c'`) and the argument of `inherits()` (`"a"` or
/// `c("a", "b", "c")`), each class escaped as an R string.
fn class_list_r(classes: &[String]) -> (String, String) {
    let quoted: Vec<String> = classes
        .iter()
        .map(|c| format!("'{}'", r_string_escape(c)))
        .collect();
    let literals: Vec<String> = classes
        .iter()
        .map(|c| format!("\"{}\"", r_string_escape(c)))
        .collect();
    let what = match quoted.as_slice() {
        [one] => one.clone(),
        [init @ .., last] => format!("{} or {last}", init.join(", ")),
        [] => unreachable!("a class check is parsed as a non-empty class list"),
    };
    let class_arg = match literals.as_slice() {
        [one] => one.clone(),
        _ => format!("c({})", literals.join(", ")),
    };
    (what, class_arg)
}

/// Let an `Option<T>` parameter pass `NULL`, and a `Missing<T>` parameter an
/// omitted argument, in the named checks `out` on parameter `param` of type
/// `ty`: each condition gains an `is.null(param) || ` / `missing(param) || `
/// prefix. The failure message names only the failed requirement: it is shown
/// only for a present, non-`NULL` value.
fn guarded(param: &str, ty: &syn::Type, mut out: Vec<RAssertion>) -> Vec<RAssertion> {
    let guard = if crate::miniextendr_fn::is_missing_type(ty) {
        Some(format!("missing({param})"))
    } else if crate::type_inspect::is_option_type(ty) {
        Some(format!("is.null({param})"))
    } else {
        None
    };
    if let Some(guard) = guard {
        for a in &mut out {
            a.condition = format!("{guard} || {}", a.condition);
        }
    }
    out
}

/// Whether a `no_na` parameter of Rust type `ty` is checked for `NA` only
/// in Rust, after the conversion, with no R guard: an `Either<L, R>`, also
/// under `Missing` and `Option`. The layers are peeled as for a choice
/// parameter ([`crate::type_inspect::choice_layers`]). A plain
/// `Option<Either<..>>` converts through `TryFromSexp`, which reads `NULL` as
/// `None` (no `NA`) and asks the `Either` otherwise; a choice
/// `Option<Either<Mode, X>>` keeps the guard (see below). The type is read
/// as written: an alias, a newtype or a `Result<Either<..>, ()>` keeps the
/// guard.
///
/// One `!anyNA(x)` on the whole argument is wrong for an arm with its own
/// reading of `NA` (a data frame arm whose cells may be missing), and it
/// scans the input a second time. So the C wrapper asks the arm the value
/// converted to (`TryFromSexp::__mx_input_has_na`): by default the arm runs
/// `anyNA()`'s check on the input in Rust, and a `DataFrame` arm refuses
/// nothing. A choice parameter (`match_arg` / `choices`) keeps the R guard:
/// its conversion does not go through `TryFromSexp`, so no Rust check follows.
pub(crate) fn no_na_checked_after_conversion(ty: &syn::Type) -> bool {
    crate::type_inspect::choice_layers(ty)
        .either_right
        .is_some()
}

/// What a `no_na` parameter of Rust type `ty` must satisfy, without the
/// parameter name: `must not contain NA` for a value holding several values
/// ([`no_na_holds_several`]), else `must not be NA`.
///
/// Shared by the R guard and the Rust check that the C wrapper runs after the
/// conversion (see [`no_na_message`]), so both word a failure alike.
pub(crate) fn no_na_requirement(ty: &syn::Type) -> String {
    let verb = if no_na_holds_several(ty) {
        "contain"
    } else {
        "be"
    };
    format!("must not {verb} NA")
}

/// Whether a `no_na` value of Rust type `ty` holds several values, looking
/// through the layers `no_na` checks through: `Missing`, `Option`,
/// `Result<T, _>` (its `T`) and `Either<L, R>`, which holds several when
/// either arm does. The text is fixed at compile time, before the conversion
/// picks an arm, and `contain` also reads right for one value.
fn no_na_holds_several(ty: &syn::Type) -> bool {
    let ty = crate::miniextendr_fn::get_missing_inner_type(ty).unwrap_or(ty);
    let ty = crate::type_inspect::option_inner_type(ty).unwrap_or(ty);
    if let Some((left, right)) = crate::type_inspect::either_arms(ty) {
        return no_na_holds_several(left) || no_na_holds_several(right);
    }
    if let syn::Type::Path(tp) = ty
        && let Some(seg) = tp.path.segments.last()
        && seg.ident == "Result"
        && let Some(ok) = crate::type_inspect::first_type_argument(seg)
    {
        return no_na_holds_several(ok);
    }
    is_vector_valued(ty)
}

/// The condition message of a failed `no_na` check on parameter `param` of
/// type `ty`: the author's `no_na(message = "...")` verbatim (`custom`), else
/// `'<param>' must not be NA` / `'<param>' must not contain NA`
/// ([`no_na_requirement`]). The R guard builds the same text in R
/// (`.miniextendr_arg_error`); the C wrapper's post-conversion check passes
/// this one to `arg_check_condition_value`.
pub(crate) fn no_na_message(param: &str, ty: &syn::Type, custom: Option<&str>) -> String {
    match custom {
        Some(message) => message.to_string(),
        None => format!("'{param}' {}", no_na_requirement(ty)),
    }
}

/// Whether an argument of Rust type `ty` holds several values, so a `no_na`
/// failure reads `must not contain NA` rather than `must not be NA`.
///
/// The type table decides when it knows the type ([`RTypeCheck::is_vector`]):
/// `Vec<T>` and slices, the vector markers (`AsNumericVec`, `AsCharacterVec`,
/// any marker whose table entry is a vector check), maps and lists. For a type the
/// table does not know, the shape decides: `Vec<T>`, `Box<[T]>`, slices and
/// arrays, and a type named `...Vec` (the vector half of a marker family such
/// as `AsFromStrVec` / `AsDisplayVec`, or a vector type like `BitVec`).
fn is_vector_valued(ty: &syn::Type) -> bool {
    if let Some(check) = r_check_for_type(ty) {
        return check.is_vector();
    }
    crate::miniextendr_fn::is_vector_like_type(ty)
        || matches!(
            ty,
            syn::Type::Path(tp)
                if tp.path.segments.last().is_some_and(|s| s.ident.to_string().ends_with("Vec"))
        )
}

/// Record `from` as the message of `check`, which may have only one.
fn merge_message(
    into: &mut Option<String>,
    from: Option<String>,
    check: &str,
) -> Result<(), String> {
    match (into.is_some(), from) {
        (true, Some(_)) => Err(format!(
            "`{check}` is given more than one `message` on this parameter; give it once"
        )),
        (false, Some(message)) => {
            *into = Some(message);
            Ok(())
        }
        (_, None) => Ok(()),
    }
}

/// Classification of an R-side type check for a function parameter.
///
/// Each variant maps to a specific set of R-side checks. Numeric checks
/// use a broad predicate (`is.numeric || is.logical || is.raw`) because R coerces
/// logical to numeric freely and raw to integer is valid for byte-sized types.
/// Borderline cases (e.g., raw to i64 in strict mode) pass the precondition and
/// reach Rust's strict checker, which produces better contextual error messages.
enum RTypeCheck {
    /// Numeric scalar: type check + length-1 check (2 assertions).
    /// Used for the multi-source scalars `f32`, `i8`, `i16`, `i64`, `isize`, and
    /// for a coerced native `f64`. Native `i32` / `f64` without coerce use
    /// [`RTypeCheck::Scalar`] with `"integer"` / `"double"`.
    ScalarNumeric,
    /// Coerced bool: logical or integer, with length one.
    ScalarLogicalOrInteger,
    /// Coerced bool vector: logical or integer.
    VectorLogicalOrInteger,
    /// Coerced native `i32` scalar: integer, logical, raw, or a whole-number
    /// double, with length one. The vector form is [`RTypeCheck::VectorIntegerWide`].
    ScalarIntegerWide,
    /// Non-negative numeric scalar: type + length-1 + `>= 0` (3 assertions).
    /// Used for `u16`, `u32`, `u64`, `usize`.
    ScalarNonNeg,
    /// Non-numeric scalar: `is.<type>(x)` + length-1 check (2 assertions).
    /// The string is the R type predicate name (e.g., `"logical"`, `"character"`).
    Scalar(&'static str),
    /// Floating-point numeric vector: loose `is.numeric || is.logical || is.raw`
    /// (1 assertion). Used for `Vec<f32>` (multi-source converter) and for a
    /// coerced native `Vec<f64>`; `Vec<f64>` / `&[f64]` without coerce use
    /// [`RTypeCheck::Vector`] with `"double"` because the native path reads
    /// REALSXP only.
    VectorNumeric,
    /// **INTSXP-only** integer vector: `is.integer(x)` (1 assertion). Used *only*
    /// for `Vec<i32>` / `&[i32]` (issue #616). These use the native `RNativeType`
    /// inbound path (`impl_vec_try_from_sexp_native!(i32)`), which requires
    /// `INTSXP` and rejects `REALSXP` outright. The loose `is.numeric` predicate
    /// previously let a `double` like `c(1, 2)` pass the R gate only to fail with
    /// a cryptic "expected INTSXP, got REALSXP". `is.integer(x)` rejects every
    /// `double` (whole or fractional) at the boundary with a clean message,
    /// matching the actual Rust behaviour and closing the silent-truncation gap.
    VectorIntegerStrict,
    /// **Wide** integer vector accepting `REALSXP` whole-number values: the
    /// lossless whole-number predicate (1 assertion). Used for every non-`i32`
    /// integer element type — `Vec<i8>` / `Vec<i16>` / `Vec<u16>` / `Vec<u32>`
    /// and the 64-bit family `Vec<i64>` / `Vec<u64>` / `Vec<isize>` / `Vec<usize>`
    /// (issue #616). These use the coercing inbound path
    /// (`impl_vec_try_from_sexp_numeric!` → `from_numeric_vec_with`) which accepts
    /// INTSXP/REALSXP/RAWSXP/LGLSXP and rejects fractional doubles element-wise
    /// (`f64: TryCoerce<T>` checks `self.fract() != 0`). We accept
    /// integer/logical/raw **and** whole-number doubles, and reject genuinely
    /// lossy fractional doubles (`1.5`) at the boundary.
    VectorIntegerWide,
    /// Non-numeric vector: `is.<type>(x)` only (1 assertion).
    /// The string is the R type predicate name.
    Vector(&'static str),
    /// `AsNumeric` scalar: numeric, logical, character, or factor, with length
    /// one (2 assertions). The marker parses character and factor labels the way
    /// `as.numeric()` does, so the gate admits exactly the types it reads.
    ScalarNumericOrText,
    /// `AsNumericVec`: numeric, logical, character, or factor (1 assertion).
    VectorNumericOrText,
    /// Nullable wrapper around an inner check: prepends `is.null(x) ||` to each assertion
    /// and adjusts messages to mention NULL.
    Nullable(Box<RTypeCheck>),
    /// List check: `is.list(x)` (1 assertion).
    /// Used for `HashMap`, `BTreeMap`, `NamedList`, `List`, `ListMut`.
    List,
}

/// Build the R expression for the numeric type predicate.
///
/// Returns `"is.numeric(p) || is.logical(p) || is.raw(p)"` for a given parameter `p`.
/// This broad predicate matches R's coercion rules: logical coerces to numeric freely,
/// and raw is accepted because it represents byte-level data.
fn numeric_type_check(param: &str) -> String {
    format!(
        "is.numeric({p}) || is.logical({p}) || is.raw({p})",
        p = param
    )
}

/// Build the lossless whole-number predicate for a `REALSXP`-accepting integer
/// vector (the `i64` / `u64` / `isize` / `usize` family).
///
/// Accepts integer/logical/raw and whole-number doubles, rejects fractional
/// doubles. The whole-number test is NA-safe (`is.na(p) | p == trunc(p)`):
/// `NA_real_` passes (maps to `NA_integer_`), `1.5` fails. `Inf`/`NaN` satisfy
/// `x == trunc(x)` in R but are caught by the Rust-side range/NaN conversion
/// check instead.
fn integer_vector_wide_check(param: &str) -> String {
    format!(
        "is.integer({p}) || is.logical({p}) || is.raw({p}) || \
         (is.numeric({p}) && all(is.na({p}) | {p} == trunc({p})))",
        p = param
    )
}

/// Build the predicate for the `AsNumeric` / `AsNumericVec` markers.
///
/// `is.numeric()` is `FALSE` for a factor, so `is.factor()` is listed on its
/// own: the marker reads a factor by its labels. Raw and complex stay out, as
/// the marker refuses them.
fn numeric_or_text_check(param: &str) -> String {
    format!(
        "is.numeric({p}) || is.logical({p}) || is.character({p}) || is.factor({p})",
        p = param
    )
}

impl RTypeCheck {
    /// Produce the individual checks for this type check.
    ///
    /// Returns one or more `RAssertion` values, each one requirement on
    /// `param` (the R parameter name used in the conditions and messages).
    fn assertions(&self, param: &str) -> Vec<RAssertion> {
        let length_one = || {
            RAssertion::new(
                param,
                "must have length 1",
                format!("length({param}) == 1L"),
            )
        };
        match self {
            RTypeCheck::ScalarNumeric => vec![
                RAssertion::new(
                    param,
                    "must be numeric, logical, or raw",
                    numeric_type_check(param),
                ),
                length_one(),
            ],
            RTypeCheck::ScalarLogicalOrInteger => vec![
                RAssertion::new(
                    param,
                    "must be logical or integer",
                    format!("is.logical({p}) || is.integer({p})", p = param),
                ),
                length_one(),
            ],
            RTypeCheck::VectorLogicalOrInteger => vec![RAssertion::new(
                param,
                "must be logical or integer",
                format!("is.logical({p}) || is.integer({p})", p = param),
            )],
            RTypeCheck::ScalarIntegerWide => vec![
                RAssertion::new(
                    param,
                    "must be integer or whole-number numeric",
                    integer_vector_wide_check(param),
                ),
                length_one(),
            ],
            RTypeCheck::ScalarNonNeg => vec![
                RAssertion::new(
                    param,
                    "must be numeric, logical, or raw",
                    numeric_type_check(param),
                ),
                length_one(),
                RAssertion::new(
                    param,
                    "must be non-negative",
                    // raw is always non-negative; guard with is.raw() to avoid
                    // "comparison not implemented" error for raw values
                    format!("is.raw({p}) || {p} >= 0", p = param),
                ),
            ],
            RTypeCheck::Scalar(r_type) => vec![
                RAssertion::new(
                    param,
                    format!("must be {r_type}"),
                    format!("is.{r_type}({param})"),
                ),
                length_one(),
            ],
            RTypeCheck::VectorNumeric => vec![RAssertion::new(
                param,
                "must be numeric, logical, or raw",
                numeric_type_check(param),
            )],
            RTypeCheck::VectorIntegerStrict => vec![RAssertion::new(
                param,
                "must be an integer vector",
                format!("is.integer({param})"),
            )],
            RTypeCheck::VectorIntegerWide => vec![RAssertion::new(
                param,
                "must be integer or whole-number numeric",
                integer_vector_wide_check(param),
            )],
            RTypeCheck::Vector(r_type) => vec![RAssertion::new(
                param,
                format!("must be {r_type}"),
                format!("is.{r_type}({param})"),
            )],
            RTypeCheck::ScalarNumericOrText => vec![
                RAssertion::new(
                    param,
                    "must be numeric, logical, character, or factor",
                    numeric_or_text_check(param),
                ),
                length_one(),
            ],
            RTypeCheck::VectorNumericOrText => vec![RAssertion::new(
                param,
                "must be numeric, logical, character, or factor",
                numeric_or_text_check(param),
            )],
            RTypeCheck::Nullable(inner) => inner
                .assertions(param)
                .into_iter()
                .map(RAssertion::nullable)
                .collect(),
            RTypeCheck::List => vec![RAssertion::new(
                param,
                "must be a list",
                format!("is.list({param})"),
            )],
        }
    }

    /// Whether the check admits several values: the vector checks and
    /// [`RTypeCheck::List`], through [`RTypeCheck::Nullable`]. Matched
    /// exhaustively, so a new check has to say which it is.
    fn is_vector(&self) -> bool {
        match self {
            RTypeCheck::VectorLogicalOrInteger
            | RTypeCheck::VectorNumeric
            | RTypeCheck::VectorIntegerStrict
            | RTypeCheck::VectorIntegerWide
            | RTypeCheck::Vector(_)
            | RTypeCheck::VectorNumericOrText
            | RTypeCheck::List => true,
            RTypeCheck::ScalarNumeric
            | RTypeCheck::ScalarLogicalOrInteger
            | RTypeCheck::ScalarIntegerWide
            | RTypeCheck::ScalarNonNeg
            | RTypeCheck::Scalar(_)
            | RTypeCheck::ScalarNumericOrText => false,
            RTypeCheck::Nullable(inner) => inner.is_vector(),
        }
    }

    /// What an argument of this type must be, in R terms: the `<expected>` of
    /// a Rust conversion failure's message, `'<p>' must be <expected>: <reason>`
    /// (#1591).
    ///
    /// The R-side checks test one requirement at a time (type, then length);
    /// a conversion failure names the whole expectation once. Scalars read
    /// `a single <noun>` (`a single integer`, `a single string`, `TRUE or
    /// FALSE`), vectors name the R type (`numeric`, `character`, `a list`).
    /// `AsNumeric` / `AsNumericVec` say `a single number` / `numeric`, the
    /// value they produce, rather than the inputs they read. `AsCharacter` /
    /// `AsCharacterVec` likewise say `coercible to a single string` /
    /// `coercible to character`: their R-side check has already required an
    /// atomic argument, so what is left to fail is the `as.character()` step
    /// (a failing method, a non-character or wrong-length result).
    fn expectation(&self) -> String {
        match self {
            RTypeCheck::ScalarNumeric | RTypeCheck::ScalarNumericOrText => "a single number".into(),
            RTypeCheck::ScalarLogicalOrInteger => "a single logical or integer".into(),
            RTypeCheck::VectorLogicalOrInteger => "logical or integer".into(),
            RTypeCheck::ScalarIntegerWide => "a single whole number".into(),
            RTypeCheck::ScalarNonNeg => "a single non-negative number".into(),
            RTypeCheck::Scalar(r_type) => match *r_type {
                "logical" => "TRUE or FALSE".into(),
                "character" => "a single string".into(),
                "integer" | "double" => format!("a single {r_type}"),
                "atomic" => "coercible to a single string".into(),
                // `raw`, `complex`.
                other => format!("a single {other} value"),
            },
            RTypeCheck::VectorNumeric | RTypeCheck::VectorNumericOrText => "numeric".into(),
            RTypeCheck::VectorIntegerStrict => "integer".into(),
            RTypeCheck::VectorIntegerWide => "integer or whole-number numeric".into(),
            RTypeCheck::Vector("atomic") => "coercible to character".into(),
            RTypeCheck::Vector(r_type) => (*r_type).into(),
            RTypeCheck::Nullable(inner) => match inner.expectation().as_str() {
                "TRUE or FALSE" => "NULL, TRUE or FALSE".into(),
                inner => format!("NULL or {inner}"),
            },
            RTypeCheck::List => "a list".into(),
        }
    }
}

/// The R-facing expectation for a parameter of Rust type `ty`, for the
/// message of its Rust conversion failure: `'<p>' must be <expected>: ...`
/// (see [`RTypeCheck::expectation`]).
///
/// Derived from the same type classification as the R-side checks, including
/// the `coerce` widening (`coerced`) and the `Missing<T>` / `Option<T>`
/// wrappers, so the two paths describe an argument the same way. A few types
/// without an R-side check still have an R-facing expectation
/// ([`unchecked_expectation`]): `Either<L, R>`, the `AsFromStr` markers and
/// tuples. `None` only for an opaque type (a custom `TryFromSexp` type, or an
/// `Either` with such an arm): the wrapper then asks the type at run time
/// (`rust_conversion_builder::declared_expectation`: a derived newtype's
/// declared expectation, an `Either` side by side), else reports
/// `invalid '<p>' argument: <reason>`.
pub(crate) fn conversion_expectation(ty: &syn::Type, coerced: bool) -> Option<String> {
    let ty = crate::miniextendr_fn::get_missing_inner_type(ty).unwrap_or(ty);
    let Some(check) = r_check_for_type(ty) else {
        return unchecked_expectation(ty);
    };
    let check = if coerced {
        coerce_widened(check, ty)
    } else {
        check
    };
    Some(check.expectation())
}

/// The R-facing expectation of a type that has no R-side check, so its
/// conversion alone says what it accepts (#1594):
///
/// | type | `<expected>` |
/// |------|--------------|
/// | `AsFromStr<T>` / `AsFromStrVec<T>` | `a single string` / `character` (the input `T` is parsed from) |
/// | `Either<L, R>` | `<L> or <R>`, when both sides have one (`a single integer or a single string`) |
/// | `(A, B, ...)` | `a list of length N` |
/// | `DataFrame` | `a data frame` |
/// | `Option<T>` of the above | `NULL or <T>` |
fn unchecked_expectation(ty: &syn::Type) -> Option<String> {
    match ty {
        syn::Type::Tuple(tuple) if !tuple.elems.is_empty() => {
            Some(format!("a list of length {}", tuple.elems.len()))
        }
        syn::Type::Path(type_path) => {
            let segment = type_path.path.segments.last()?;
            match segment.ident.to_string().as_str() {
                "AsFromStr" => Some("a single string".into()),
                "AsFromStrVec" => Some("character".into()),
                "DataFrame" => Some("a data frame".into()),
                "Either" => {
                    let left = crate::type_inspect::first_type_argument(segment)?;
                    let right = crate::type_inspect::second_type_argument(segment)?;
                    Some(format!(
                        "{} or {}",
                        conversion_expectation(left, false)?,
                        conversion_expectation(right, false)?
                    ))
                }
                "Option" => {
                    let inner = extract_single_generic_arg(segment)?;
                    Some(format!("NULL or {}", unchecked_expectation(inner)?))
                }
                _ => None,
            }
        }
        _ => None,
    }
}

/// The R-facing expectation of a `strict` lossy-integer parameter (`i64`,
/// `u64`, `isize`, `usize` and their `Vec` / `Vec<Option<_>>` forms), whose
/// Rust conversion accepts only integer and whole-number double input
/// (#1594): `a single whole number` / `a single non-negative whole number`
/// for a scalar, the vector's usual `integer or whole-number numeric`
/// otherwise.
pub(crate) fn strict_conversion_expectation(ty: &syn::Type) -> Option<String> {
    let scalar = match ty {
        syn::Type::Path(tp) => tp.path.segments.last().map(|s| s.ident.to_string()),
        _ => None,
    };
    match scalar.as_deref() {
        Some("i64" | "isize") => Some("a single whole number".into()),
        Some("u64" | "usize") => Some("a single non-negative whole number".into()),
        _ => conversion_expectation(ty, false),
    }
}

/// Keep the R gate in sync with the conversion actually selected for this type.
///
/// Native `i32` widens to whole-number doubles (plus logical/raw), so its gate
/// becomes the lossless whole-number predicate; `Vec<i32>` moves from the
/// INTSXP-only gate (#616) to the same wide predicate the other integer vectors
/// use. Native `f64` / `Vec<f64>` move from the `is.double` gate to the loose
/// numeric predicate. `Option<bool>` has no coercion mapping and stays nullable
/// logical.
fn coerce_widened(check: RTypeCheck, ty: &syn::Type) -> RTypeCheck {
    use crate::miniextendr_fn::CoercionMapping;
    match CoercionMapping::from_type(ty) {
        Some(CoercionMapping::Bool) => RTypeCheck::ScalarLogicalOrInteger,
        Some(CoercionMapping::BoolVec) => RTypeCheck::VectorLogicalOrInteger,
        Some(CoercionMapping::NativeInt) => RTypeCheck::ScalarIntegerWide,
        Some(CoercionMapping::NativeIntVec) => RTypeCheck::VectorIntegerWide,
        Some(CoercionMapping::NativeReal) => RTypeCheck::ScalarNumeric,
        Some(CoercionMapping::NativeRealVec) => RTypeCheck::VectorNumeric,
        _ => check,
    }
}

/// Map a Rust type to its R-side type check, if applicable.
///
/// Returns `None` for types that should skip precondition checks (SEXP, Dots, ExternalPtr, etc.).
fn r_check_for_type(ty: &syn::Type) -> Option<RTypeCheck> {
    match ty {
        syn::Type::Path(type_path) => r_check_for_type_path(type_path),
        syn::Type::Reference(type_ref) => r_check_for_reference(type_ref),
        _ => None,
    }
}

/// Map a `syn::TypePath` to its R-side type check.
///
/// Handles the most common case: simple types (`i32`, `String`, `bool`),
/// generic wrappers (`Vec<T>`, `Option<T>`), map types, and skip types.
/// Returns `None` for types that cannot be prechecked from R.
fn r_check_for_type_path(type_path: &syn::TypePath) -> Option<RTypeCheck> {
    let segment = type_path.path.segments.last()?;
    let ident = segment.ident.to_string();

    match ident.as_str() {
        // Native scalars convert from exactly one SEXPTYPE (`i32::try_from_sexp`
        // is INTSXP-only, `f64` REALSXP-only), so the R gate names that storage
        // instead of letting a double reach Rust and fail with "expected INTSXP,
        // got REALSXP" (#1112). Under `coerce` the gate widens with the conversion
        // (see `coerce_widened`).
        "i32" => Some(RTypeCheck::Scalar("integer")),
        "f64" => Some(RTypeCheck::Scalar("double")),

        // Non-native numeric scalars use the multi-source converters (integer,
        // double, logical, raw), so the loose predicate matches what Rust accepts.
        "f32" | "i8" | "i16" | "i64" | "isize" => Some(RTypeCheck::ScalarNumeric),

        // Unsigned numeric scalars (non-negative constraint)
        "u16" | "u32" | "u64" | "usize" => Some(RTypeCheck::ScalarNonNeg),

        // Logical scalar
        "bool" | "Rbool" | "Rboolean" => Some(RTypeCheck::Scalar("logical")),

        // Character scalar
        "String" | "char" | "PathBuf" => Some(RTypeCheck::Scalar("character")),

        // Raw scalar
        "u8" => Some(RTypeCheck::Scalar("raw")),

        // Complex scalar
        "Rcomplex" => Some(RTypeCheck::Scalar("complex")),

        // `as.numeric()`-style markers: numbers, text, and factor labels.
        "AsNumeric" => Some(RTypeCheck::ScalarNumericOrText),
        "AsNumericVec" => Some(RTypeCheck::VectorNumericOrText),

        // `as.character()`-style markers: any atomic vector (a list or data
        // frame is refused, as `as.character()` would flatten it), with length
        // one for the scalar. "'x' must be atomic" is base R's own wording.
        "AsCharacter" => Some(RTypeCheck::Scalar("atomic")),
        "AsCharacterVec" => Some(RTypeCheck::Vector("atomic")),

        // Option<T> → Nullable
        "Option" => {
            let inner_ty = extract_single_generic_arg(segment)?;
            r_check_for_type(inner_ty).map(|inner| RTypeCheck::Nullable(Box::new(inner)))
        }

        // Vec<T> → Vector (depends on element type)
        "Vec" => {
            let inner_ty = extract_single_generic_arg(segment)?;
            r_check_for_vec_element(inner_ty)
        }

        // Map types and named list → List
        "HashMap" | "BTreeMap" | "NamedList" => Some(RTypeCheck::List),

        // List (bare) → List
        "List" | "ListMut" => Some(RTypeCheck::List),

        // Skip types: SEXP, Dots, Missing, ExternalPtr, RLogical, etc.
        // `LazyDots` is `...`, passed as the wrapper's frame (#1892).
        "SEXP" | "Dots" | "LazyDots" | "Missing" | "ExternalPtr" | "OwnedProtect" => None,

        // Unknown type → skip (let Rust side validate)
        _ => None,
    }
}

/// Map a reference type to its R-side type check.
///
/// Handles `&str` and `&Path` (character scalar), `&[T]` (vector based on element type),
/// and `&Dots` (skipped). Returns `None` for unrecognized reference types.
fn r_check_for_reference(type_ref: &syn::TypeReference) -> Option<RTypeCheck> {
    match type_ref.elem.as_ref() {
        // &str → character scalar
        syn::Type::Path(tp) => {
            let seg = tp.path.segments.last()?;
            match seg.ident.to_string().as_str() {
                "str" => Some(RTypeCheck::Scalar("character")),
                "Path" => Some(RTypeCheck::Scalar("character")),
                "Dots" => None,
                _ => None,
            }
        }
        // &[T] → vector check based on element type
        syn::Type::Slice(slice) => r_check_for_vec_element(&slice.elem),
        _ => None,
    }
}

/// Map a `Vec<T>` or `&[T]` element type to the appropriate vector type check.
///
/// Numeric elements produce `VectorNumeric`, `bool` produces `Vector("logical")`,
/// `String` produces `Vector("character")`, etc. Handles nested `Option<T>` for
/// nullable element types (e.g., `Vec<Option<String>>` becomes character vector).
fn r_check_for_vec_element(elem_ty: &syn::Type) -> Option<RTypeCheck> {
    let syn::Type::Path(tp) = elem_ty else {
        return None;
    };
    let seg = tp.path.segments.last()?;
    let ident = seg.ident.to_string();

    match ident.as_str() {
        // `Vec<f64>` / `&[f64]` read the REALSXP payload directly (native path),
        // so the gate is `is.double`; `Vec<f32>` coerces from every numeric source.
        "f64" => Some(RTypeCheck::Vector("double")),
        "f32" => Some(RTypeCheck::VectorNumeric),

        // `Vec<i32>` / `&[i32]` is the *only* INTSXP-only integer vector (issue
        // #616): its inbound conversion uses the native `RNativeType` path
        // (`impl_vec_try_from_sexp_native!(i32)` in `from_r/collections.rs`),
        // which rejects REALSXP outright. So the R gate is `is.integer` — a
        // `double` like `c(1, 2)` fails cleanly at the boundary instead of
        // producing a cryptic "expected INTSXP, got REALSXP". `u8` is handled
        // below as a raw vector.
        "i32" => Some(RTypeCheck::VectorIntegerStrict),

        // Every other integer-element vector (`i8`/`i16`/`u16`/`u32` and the
        // 64-bit family `i64`/`u64`/`isize`/`usize`) uses the coercing inbound
        // path (`impl_vec_try_from_sexp_numeric!` → `from_numeric_vec_with`),
        // which accepts INTSXP/REALSXP/RAWSXP/LGLSXP and rejects fractional
        // doubles element-wise via `f64: TryCoerce<T>` (the `self.fract() != 0`
        // check in `coerce.rs`). The R gate mirrors that: accept integer/logical/
        // raw + whole-number doubles, reject fractional. (64-bit ints also arrive
        // as REALSXP since R has no native 64-bit integer type.)
        "i8" | "i16" | "u16" | "u32" | "i64" | "u64" | "isize" | "usize" => {
            Some(RTypeCheck::VectorIntegerWide)
        }

        // Logical vector
        "bool" => Some(RTypeCheck::Vector("logical")),

        // Character vector
        "String" => Some(RTypeCheck::Vector("character")),

        // Raw vector
        "u8" => Some(RTypeCheck::Vector("raw")),

        // Complex vector
        "Rcomplex" => Some(RTypeCheck::Vector("complex")),

        // Vec<Option<T>> — e.g., Vec<Option<String>> for nullable strings
        "Option" => {
            let inner = extract_single_generic_arg(seg)?;
            // Vec<Option<String>> → character, Vec<Option<i32>> → numeric, etc.
            r_check_for_vec_element(inner)
        }

        _ => None,
    }
}

/// Extract the single generic type argument from a path segment.
///
/// e.g., `Option<String>` → `String`, `Vec<i32>` → `i32`
fn extract_single_generic_arg(segment: &syn::PathSegment) -> Option<&syn::Type> {
    if let syn::PathArguments::AngleBracketed(ref args) = segment.arguments
        && let Some(syn::GenericArgument::Type(ty)) = args.args.first()
    {
        return Some(ty);
    }
    None
}

/// A parameter whose Rust type is not in the static type table.
///
/// Currently, fallback params are recorded but no R-side validation is generated
/// for them -- the Rust-side conversion handles type errors with its own messages.
#[allow(dead_code)] // Read in tests
pub struct FallbackParam {
    /// R-normalized parameter name (e.g., `_dots` becomes `dots`).
    pub r_name: String,
}

/// Output of precondition analysis for a function's parameters.
///
/// Holds the R-side checks for known types and a list of parameters with
/// unknown types that were not statically prechecked.
pub struct PreconditionOutput {
    /// The checks, in parameter order: each parameter's class checks, its
    /// type checks, then its NA check ([`ExplicitChecks`]). Rendered by
    /// [`PreconditionOutput::guards`].
    assertions: Vec<RAssertion>,
    /// Parameters with unknown custom types that were not prechecked.
    #[allow(dead_code)] // Read in tests
    pub fallback_params: Vec<FallbackParam>,
}

impl PreconditionOutput {
    /// One guard line per check, raising an argument error through
    /// `.miniextendr_arg_error` when it fails (#1591); empty when there is
    /// nothing to check.
    ///
    /// `call` is the call every failure is attributed to: `None` for the
    /// wrapper's own call (the helper's default, the call `stopifnot()`
    /// reported), or `.mx_call` for a `call = caller` wrapper, which binds the
    /// caller's matched call before the checks run (#1548).
    pub fn guards(&self, call: Option<&str>) -> Vec<String> {
        self.assertions.iter().map(|a| a.to_guard(call)).collect()
    }
}

/// Returns `true` for types that should never get a fallback precheck.
///
/// These types are either handled specially by the FFI layer (`SEXP`),
/// consumed by the macro infrastructure (`Dots`, `LazyDots`, `Missing`), or
/// managed internally (`ExternalPtr`, `OwnedProtect`).
fn is_skip_type(ident: &str) -> bool {
    matches!(
        ident,
        "SEXP" | "Dots" | "LazyDots" | "Missing" | "ExternalPtr" | "OwnedProtect"
    )
}

/// Returns `true` if a type is unknown to the static type table and should
/// be recorded as a fallback parameter.
///
/// Returns `false` for skip types (SEXP, Dots, etc.) and reference types
/// (which are handled by the static table or skipped).
fn needs_fallback(ty: &syn::Type) -> bool {
    match ty {
        syn::Type::Path(tp) => {
            let Some(seg) = tp.path.segments.last() else {
                return false;
            };
            !is_skip_type(&seg.ident.to_string())
        }
        // References (&str, &[T], &Dots) are handled by static table or skipped
        syn::Type::Reference(_) => false,
        _ => false,
    }
}

/// Build precondition checks for a function's parameters.
///
/// Returns the checks for known types (render them with
/// [`PreconditionOutput::guards`]) and the parameters with unknown custom
/// types (`fallback_params`). The guards read:
/// ```r
/// if (!isTRUE(is.integer(a))) .miniextendr_arg_error("a", "must be integer")
/// if (!isTRUE(length(a) == 1L)) .miniextendr_arg_error("a", "must have length 1")
/// ```
///
/// Skips:
/// - `self`/`&self`/`&mut self` (receiver args)
/// - Parameters in `skip_params` (e.g., match_arg params already validated)
/// - Skip types (SEXP, Dots, ExternalPtr, etc.)
/// - The type-derived checks of the parameters in `opts.unchecked`
///
/// A parameter's [`ExplicitChecks`] are never skipped: its class checks
/// (`inherits`, then `not_inherits`) come before its type checks, which take
/// the `inherits` message when there is one, and its NA check after them.
pub fn build_precondition_checks(
    inputs: &syn::punctuated::Punctuated<syn::FnArg, syn::Token![,]>,
    skip_params: &HashSet<String>,
    opts: &PreconditionOptions,
) -> PreconditionOutput {
    let mut assertions = Vec::new();
    let mut fallback_params = Vec::new();

    for arg in inputs {
        // Skip receiver (self/&self/&mut self)
        let syn::FnArg::Typed(pt) = arg else {
            continue;
        };

        // `NArgs` is no R formal: the wrapper passes `nargs()`, which no
        // check needs to look at (#1860). Nor is a `LazyDots` parameter's name:
        // its formal is `...`, passed unforced as the wrapper's frame (#1892).
        if crate::type_inspect::is_nargs_marker(&pt.ty)
            || crate::type_inspect::is_lazy_dots_marker(&pt.ty)
        {
            continue;
        }

        // Extract parameter name
        let syn::Pat::Ident(pat_ident) = pt.pat.as_ref() else {
            continue;
        };

        // The parameter's R formal (#1842): what the checks read and name
        let r_name = opts.formals.of_ident(&pat_ident.ident);
        let explicit = opts.explicit.get(&r_name);

        // The class checks first, so a value of the wrong class gets their
        // message whatever its type.
        if let Some(checks) = explicit {
            assertions.extend(checks.class_assertions(&r_name, pt.ty.as_ref()));
        }

        // Type-derived checks: skipped for match_arg params (already validated
        // by match.arg()) and for the parameters that drop them.
        if !opts.unchecked.contains(&r_name) && !skip_params.contains(&r_name) {
            // Preserve the ordinary input domain and include any coercion extensions.
            if let Some(mut check) = r_check_for_type(pt.ty.as_ref()) {
                if opts.is_coerced(&r_name) {
                    check = coerce_widened(check, pt.ty.as_ref());
                }
                let mut type_assertions = check.assertions(&r_name);
                // An `inherits` message covers the type checks too.
                if let Some(message) = explicit.and_then(ExplicitChecks::type_check_message) {
                    for a in &mut type_assertions {
                        a.message = Some(message.clone());
                    }
                }
                assertions.extend(type_assertions);
            } else if needs_fallback(pt.ty.as_ref()) {
                // Unknown type → record for potential future validation
                fallback_params.push(FallbackParam {
                    r_name: r_name.clone(),
                });
            }
        }

        if let Some(checks) = explicit {
            assertions.extend(checks.value_assertions(
                &r_name,
                pt.ty.as_ref(),
                skip_params.contains(&r_name),
            ));
        }
    }

    PreconditionOutput {
        assertions,
        fallback_params,
    }
}

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

    /// Helper to parse a type string into syn::Type
    fn parse_type(s: &str) -> syn::Type {
        syn::parse_str(s).unwrap()
    }

    /// Helper to get assertions for a type.
    fn assertions_for(ty_str: &str, param: &str) -> Vec<RAssertion> {
        let ty = parse_type(ty_str);
        r_check_for_type(&ty).unwrap().assertions(param)
    }

    #[test]
    fn scalar_numeric_produces_two_assertions() {
        let asserts = assertions_for("i64", "x");
        assert_eq!(asserts.len(), 2);
        assert_eq!(asserts[0].message(), "'x' must be numeric, logical, or raw");
        assert_eq!(
            asserts[0].condition,
            "is.numeric(x) || is.logical(x) || is.raw(x)"
        );
        assert_eq!(asserts[1].message(), "'x' must have length 1");
        assert_eq!(asserts[1].condition, "length(x) == 1L");
    }

    #[test]
    fn native_scalars_use_their_storage_gate() {
        // `i32` / `f64` convert from one SEXPTYPE, so the gate says so (#1112).
        let asserts = assertions_for("i32", "x");
        assert_eq!(asserts.len(), 2);
        assert_eq!(asserts[0].message(), "'x' must be integer");
        assert_eq!(asserts[0].condition, "is.integer(x)");
        let asserts = assertions_for("f64", "x");
        assert_eq!(asserts[0].message(), "'x' must be double");
        assert_eq!(asserts[0].condition, "is.double(x)");
        let asserts = assertions_for("Vec<f64>", "x");
        assert_eq!(asserts.len(), 1);
        assert_eq!(asserts[0].condition, "is.double(x)");
        let asserts = assertions_for("&[f64]", "x");
        assert_eq!(asserts[0].condition, "is.double(x)");
    }

    #[test]
    fn all_signed_numeric_types_use_scalar_numeric() {
        for ty_str in &["f32", "i8", "i16", "i64", "isize"] {
            let asserts = assertions_for(ty_str, "x");
            assert_eq!(asserts.len(), 2, "{} should produce 2 assertions", ty_str);
            assert!(
                asserts[0].condition.contains("is.numeric(x)"),
                "{} type check",
                ty_str
            );
            assert!(
                asserts[0].condition.contains("is.logical(x)"),
                "{} accepts logical",
                ty_str
            );
            assert!(
                asserts[0].condition.contains("is.raw(x)"),
                "{} accepts raw",
                ty_str
            );
        }
    }

    #[test]
    fn scalar_non_neg_produces_three_assertions() {
        let asserts = assertions_for("u32", "n");
        assert_eq!(asserts.len(), 3);
        assert_eq!(asserts[0].message(), "'n' must be numeric, logical, or raw");
        assert_eq!(asserts[1].message(), "'n' must have length 1");
        assert_eq!(asserts[2].message(), "'n' must be non-negative");
        assert_eq!(asserts[2].condition, "is.raw(n) || n >= 0");
    }

    #[test]
    fn all_unsigned_types_use_scalar_non_neg() {
        for ty_str in &["u16", "u32", "u64", "usize"] {
            let asserts = assertions_for(ty_str, "x");
            assert_eq!(asserts.len(), 3, "{} should produce 3 assertions", ty_str);
            assert!(
                asserts[2].condition.contains(">= 0"),
                "{} non-neg check",
                ty_str
            );
        }
    }

    #[test]
    fn scalar_logical() {
        let asserts = assertions_for("bool", "x");
        assert_eq!(asserts.len(), 2);
        assert_eq!(asserts[0].message(), "'x' must be logical");
        assert_eq!(asserts[0].condition, "is.logical(x)");
        assert_eq!(asserts[1].condition, "length(x) == 1L");
    }

    #[test]
    fn scalar_character() {
        for ty_str in &["String", "char", "PathBuf"] {
            let asserts = assertions_for(ty_str, "s");
            assert_eq!(asserts.len(), 2);
            assert_eq!(asserts[0].message(), "'s' must be character");
            assert_eq!(asserts[0].condition, "is.character(s)");
        }
    }

    #[test]
    fn ref_str() {
        let ty: syn::Type = syn::parse_str("& str").unwrap();
        let asserts = r_check_for_type(&ty).unwrap().assertions("s");
        assert_eq!(asserts.len(), 2);
        assert_eq!(asserts[0].condition, "is.character(s)");
    }

    #[test]
    fn scalar_raw() {
        let asserts = assertions_for("u8", "x");
        assert_eq!(asserts.len(), 2);
        assert_eq!(asserts[0].message(), "'x' must be raw");
        assert_eq!(asserts[0].condition, "is.raw(x)");
    }

    #[test]
    fn vector_float_stays_loose() {
        // `Vec<f32>` coerces from every numeric source, so it keeps the loose predicate.
        let asserts = assertions_for("Vec<f32>", "x");
        assert_eq!(asserts.len(), 1);
        assert_eq!(
            asserts[0].condition,
            "is.numeric(x) || is.logical(x) || is.raw(x)"
        );
    }

    #[test]
    fn vector_i32_is_intsxp_strict() {
        // `Vec<i32>` is the only INTSXP-only integer vector: the native inbound
        // conversion rejects REALSXP, so the R gate is `is.integer(x)` — a clean
        // boundary rejection for any double (issue #616).
        let asserts = assertions_for("Vec<i32>", "x");
        assert_eq!(asserts.len(), 1);
        assert_eq!(asserts[0].condition, "is.integer(x)");
        assert_eq!(asserts[0].message(), "'x' must be an integer vector");
    }

    #[test]
    fn vector_integer_wide_is_lossless() {
        // Every non-i32 integer element type uses the coercing inbound path that
        // accepts whole REALSXP and rejects fractional → lossless whole-number gate.
        for ty_str in &[
            "Vec<i8>",
            "Vec<i16>",
            "Vec<u16>",
            "Vec<u32>",
            "Vec<i64>",
            "Vec<u64>",
            "Vec<isize>",
            "Vec<usize>",
        ] {
            let asserts = assertions_for(ty_str, "x");
            assert_eq!(asserts.len(), 1, "{} should produce 1 assertion", ty_str);
            assert_eq!(
                asserts[0].condition,
                "is.integer(x) || is.logical(x) || is.raw(x) || \
                 (is.numeric(x) && all(is.na(x) | x == trunc(x)))",
                "{}",
                ty_str
            );
            assert_eq!(
                asserts[0].message(),
                "'x' must be integer or whole-number numeric"
            );
        }
    }

    #[test]
    fn slice_int_is_strict() {
        let ty: syn::Type = syn::parse_str("& [i32]").unwrap();
        let asserts = r_check_for_type(&ty).unwrap().assertions("x");
        assert_eq!(asserts.len(), 1);
        assert_eq!(asserts[0].condition, "is.integer(x)");
    }

    #[test]
    fn coerced_native_int_widens_to_whole_number_gate() {
        let ty = parse_type("i32");
        let asserts = coerce_widened(r_check_for_type(&ty).unwrap(), &ty).assertions("x");
        assert_eq!(asserts.len(), 2);
        assert_eq!(
            asserts[0].message(),
            "'x' must be integer or whole-number numeric"
        );
        assert!(asserts[0].condition.contains("x == trunc(x)"));
        assert_eq!(asserts[1].condition, "length(x) == 1L");

        let ty = parse_type("Vec<i32>");
        let asserts = coerce_widened(r_check_for_type(&ty).unwrap(), &ty).assertions("x");
        assert_eq!(asserts.len(), 1);
        assert!(asserts[0].condition.contains("x == trunc(x)"));

        // Native doubles move from `is.double` to the loose numeric gate;
        // borrowed slices have no mapping and stay strict.
        for name in ["f64", "Vec<f64>"] {
            let ty = parse_type(name);
            let actual = coerce_widened(r_check_for_type(&ty).unwrap(), &ty).assertions("x");
            assert_eq!(
                actual[0].condition, "is.numeric(x) || is.logical(x) || is.raw(x)",
                "{name}"
            );
        }
        let ty = parse_type("&[i32]");
        let actual = coerce_widened(r_check_for_type(&ty).unwrap(), &ty).assertions("x");
        assert_eq!(actual[0].condition, "is.integer(x)");
    }

    #[test]
    fn coerced_numeric_and_optional_checks_are_preserved() {
        for name in ["Vec<u16>", "Vec<f32>", "Option<bool>"] {
            let ty = parse_type(name);
            let expected = r_check_for_type(&ty).unwrap().assertions("x");
            let actual = coerce_widened(r_check_for_type(&ty).unwrap(), &ty).assertions("x");
            assert_eq!(actual.len(), expected.len());
            for (actual, expected) in actual.iter().zip(&expected) {
                assert_eq!(actual.condition, expected.condition);
            }
        }
    }

    #[test]
    fn coerced_bool_checks_accept_logical_and_integer() {
        for name in ["bool", "Vec<bool>"] {
            let ty = parse_type(name);
            let actual = coerce_widened(r_check_for_type(&ty).unwrap(), &ty).assertions("x");
            assert_eq!(actual[0].condition, "is.logical(x) || is.integer(x)");
            assert_eq!(actual.len(), if name == "bool" { 2 } else { 1 });
        }
    }

    #[test]
    fn build_checks_coerced_param_preserves_whole_number_check() {
        let sig: syn::Signature = syn::parse_str("fn f(x: Vec<u16>)").unwrap();
        let mut coerce_params = HashSet::new();
        coerce_params.insert("x".to_string());
        let opts = PreconditionOptions {
            coerce_params,
            ..Default::default()
        };
        let output = build_precondition_checks(&sig.inputs, &HashSet::new(), &opts);
        let joined = output.guards(None).join("\n");
        assert!(joined.contains("is.integer(x)"));
        assert!(joined.contains("trunc(x)"));
    }

    /// Every check is one guard raising the shared argument error (#1591):
    /// the wrapper's own call by default, the captured `.mx_call` under
    /// `call = caller` (#1548). The requirement leaves out the parameter name,
    /// which the helper puts in front.
    #[test]
    fn guards_raise_the_argument_error_with_the_given_call() {
        let sig: syn::Signature = syn::parse_str("fn f(n: i32, xs: Vec<f64>)").unwrap();
        let output = build_precondition_checks(
            &sig.inputs,
            &HashSet::new(),
            &PreconditionOptions::default(),
        );
        assert_eq!(
            output.guards(None),
            vec![
                "if (!isTRUE(is.integer(n))) .miniextendr_arg_error(\"n\", \"must be integer\")",
                "if (!isTRUE(length(n) == 1L)) .miniextendr_arg_error(\"n\", \"must have length 1\")",
                "if (!isTRUE(is.double(xs))) .miniextendr_arg_error(\"xs\", \"must be double\")",
            ]
        );
        assert_eq!(
            output.guards(Some(".mx_call")),
            vec![
                "if (!isTRUE(is.integer(n))) .miniextendr_arg_error(\"n\", \"must be integer\", .mx_call)",
                "if (!isTRUE(length(n) == 1L)) .miniextendr_arg_error(\"n\", \"must have length 1\", .mx_call)",
                "if (!isTRUE(is.double(xs))) .miniextendr_arg_error(\"xs\", \"must be double\", .mx_call)",
            ]
        );
        let no_params: syn::Signature = syn::parse_str("fn g()").unwrap();
        let empty = build_precondition_checks(
            &no_params.inputs,
            &HashSet::new(),
            &PreconditionOptions::default(),
        );
        assert!(empty.guards(None).is_empty());
        assert!(empty.guards(Some(".mx_call")).is_empty());
    }

    /// The conversion-side expectation (#1591) reads the same classification:
    /// scalars name one value, vectors the R type, `Option` adds `NULL`,
    /// `coerce` widens with the gate, and types without a check have none.
    #[test]
    fn conversion_expectation_follows_the_type_check() {
        let exp = |ty: &str, coerced: bool| conversion_expectation(&parse_type(ty), coerced);
        let some = |s: &str| Some(s.to_string());
        assert_eq!(exp("AsNumericVec", false), some("numeric"));
        assert_eq!(exp("AsNumeric", false), some("a single number"));
        assert_eq!(
            exp("Option<AsNumeric>", false),
            some("NULL or a single number")
        );
        assert_eq!(exp("i32", false), some("a single integer"));
        assert_eq!(exp("i32", true), some("a single whole number"));
        assert_eq!(exp("f64", false), some("a single double"));
        assert_eq!(exp("f64", true), some("a single number"));
        assert_eq!(exp("i64", false), some("a single number"));
        assert_eq!(exp("u32", false), some("a single non-negative number"));
        assert_eq!(exp("bool", false), some("TRUE or FALSE"));
        assert_eq!(exp("Option<bool>", false), some("NULL, TRUE or FALSE"));
        assert_eq!(exp("bool", true), some("a single logical or integer"));
        assert_eq!(exp("String", false), some("a single string"));
        assert_eq!(exp("&str", false), some("a single string"));
        assert_eq!(exp("u8", false), some("a single raw value"));
        assert_eq!(exp("Rcomplex", false), some("a single complex value"));
        assert_eq!(exp("Vec<i32>", false), some("integer"));
        assert_eq!(
            exp("Vec<i32>", true),
            some("integer or whole-number numeric")
        );
        assert_eq!(
            exp("Vec<u16>", false),
            some("integer or whole-number numeric")
        );
        assert_eq!(exp("Vec<f64>", false), some("double"));
        assert_eq!(exp("&[f64]", false), some("double"));
        assert_eq!(exp("Vec<Option<String>>", false), some("character"));
        assert_eq!(exp("Vec<bool>", true), some("logical or integer"));
        assert_eq!(exp("HashMap<String, i32>", false), some("a list"));
        assert_eq!(exp("Missing<f64>", false), some("a single double"));
        assert_eq!(
            exp("AsCharacter", false),
            some("coercible to a single string")
        );
        assert_eq!(exp("AsCharacterVec", false), some("coercible to character"));
        assert_eq!(
            exp("Option<AsCharacter>", false),
            some("NULL or coercible to a single string")
        );
        // Types without an R-side check that still say what they accept.
        assert_eq!(exp("AsFromStr<IpAddr>", false), some("a single string"));
        assert_eq!(exp("AsFromStrVec<i32>", false), some("character"));
        assert_eq!(
            exp("Option<AsFromStr<IpAddr>>", false),
            some("NULL or a single string")
        );
        assert_eq!(
            exp("Either<i32, String>", false),
            some("a single integer or a single string")
        );
        assert_eq!(
            exp("Either<f64, Vec<i32>>", false),
            some("a single double or integer")
        );
        assert_eq!(
            exp("Either<bool, Either<i32, String>>", false),
            some("TRUE or FALSE or a single integer or a single string")
        );
        assert_eq!(
            exp("Option<Either<i32, String>>", false),
            some("NULL or a single integer or a single string")
        );
        assert_eq!(
            exp("Option<Either<f64, String>>", false),
            some("NULL or a single double or a single string")
        );
        assert_eq!(
            exp("Option<Either<AsNumericVec, DataFrame>>", false),
            some("NULL or numeric or a data frame")
        );
        assert_eq!(exp("(i32, String)", false), some("a list of length 2"));
        assert_eq!(exp("DataFrame", false), some("a data frame"));
        assert_eq!(
            exp("Option<DataFrame>", false),
            some("NULL or a data frame")
        );
        // Choice parameters, including the `Missing` / `Option` / `Either`
        // layers of #1551, have no static expectation: their conversion error
        // supplies it at run time (`one of "a", "b"`). An opaque side leaves
        // the whole `Either` without a static one; the wrapper words it side
        // by side at run time.
        for unknown in [
            "Hyperparams",
            "Either<i32, Hyperparams>",
            "SEXP",
            "()",
            "Mode",
            "Option<Mode>",
            "Missing<Option<Mode>>",
            "Missing<Vec<Mode>>",
            "Either<Route, DataFrame>",
            "Option<Either<Route, DataFrame>>",
            "Missing<Option<Either<Mode, List>>>",
            "Either<Vec<Mode>, DataFrame>",
            "Option<Either<Vec<Mode>, DataFrame>>",
        ] {
            assert_eq!(exp(unknown, false), None, "{unknown}");
        }
        // A `choices(...)` `several_ok` string list with another kind of value
        // (#1612).
        assert_eq!(
            exp("Either<Vec<String>, f64>", false),
            some("character or a single double")
        );
    }

    #[test]
    fn strict_expectation_names_a_whole_number() {
        let exp = |ty: &str| strict_conversion_expectation(&parse_type(ty));
        let some = |s: &str| Some(s.to_string());
        assert_eq!(exp("i64"), some("a single whole number"));
        assert_eq!(exp("isize"), some("a single whole number"));
        assert_eq!(exp("u64"), some("a single non-negative whole number"));
        assert_eq!(exp("usize"), some("a single non-negative whole number"));
        assert_eq!(exp("Vec<i64>"), some("integer or whole-number numeric"));
        assert_eq!(
            exp("Vec<Option<u64>>"),
            some("integer or whole-number numeric")
        );
    }

    #[test]
    fn vector_character() {
        let asserts = assertions_for("Vec<String>", "x");
        assert_eq!(asserts.len(), 1);
        assert_eq!(asserts[0].condition, "is.character(x)");
    }

    #[test]
    fn vector_optional_string() {
        let asserts = assertions_for("Vec<Option<String>>", "x");
        assert_eq!(asserts.len(), 1);
        assert_eq!(asserts[0].condition, "is.character(x)");
    }

    #[test]
    fn slice_u8() {
        let ty: syn::Type = syn::parse_str("& [u8]").unwrap();
        let asserts = r_check_for_type(&ty).unwrap().assertions("x");
        assert_eq!(asserts.len(), 1);
        assert_eq!(asserts[0].condition, "is.raw(x)");
    }

    #[test]
    fn nullable_wraps_inner_assertions() {
        let asserts = assertions_for("Option<i64>", "x");
        assert_eq!(asserts.len(), 2);
        assert_eq!(
            asserts[0].message(),
            "'x' must be NULL or numeric, logical, or raw"
        );
        assert_eq!(
            asserts[0].condition,
            "is.null(x) || is.numeric(x) || is.logical(x) || is.raw(x)"
        );
        let asserts = assertions_for("Option<i32>", "x");
        assert_eq!(asserts[0].condition, "is.null(x) || is.integer(x)");
        assert_eq!(asserts[1].message(), "'x' must be NULL or have length 1");
        assert_eq!(asserts[1].condition, "is.null(x) || length(x) == 1L");
    }

    #[test]
    fn nullable_character() {
        let asserts = assertions_for("Option<String>", "s");
        assert_eq!(asserts.len(), 2);
        assert_eq!(asserts[0].message(), "'s' must be NULL or character");
        assert_eq!(asserts[0].condition, "is.null(s) || is.character(s)");
        assert_eq!(asserts[1].message(), "'s' must be NULL or have length 1");
    }

    #[test]
    fn as_numeric_markers_admit_numbers_text_and_factors() {
        let condition = "is.numeric(x) || is.logical(x) || is.character(x) || is.factor(x)";
        let asserts = assertions_for("AsNumeric", "x");
        assert_eq!(asserts.len(), 2);
        assert_eq!(
            asserts[0].message(),
            "'x' must be numeric, logical, character, or factor"
        );
        assert_eq!(asserts[0].condition, condition);
        assert_eq!(asserts[1].message(), "'x' must have length 1");
        assert_eq!(asserts[1].condition, "length(x) == 1L");

        // Path-qualified spellings resolve by their last segment.
        let asserts = assertions_for("miniextendr_api::AsNumericVec", "x");
        assert_eq!(asserts.len(), 1);
        assert_eq!(
            asserts[0].message(),
            "'x' must be numeric, logical, character, or factor"
        );
        assert_eq!(asserts[0].condition, condition);
    }

    #[test]
    fn optional_as_numeric_is_nullable() {
        let asserts = assertions_for("Option<AsNumeric>", "x");
        assert_eq!(asserts.len(), 2);
        assert_eq!(
            asserts[0].message(),
            "'x' must be NULL or numeric, logical, character, or factor"
        );
        assert_eq!(
            asserts[0].condition,
            "is.null(x) || is.numeric(x) || is.logical(x) || is.character(x) || is.factor(x)"
        );
        assert_eq!(asserts[1].message(), "'x' must be NULL or have length 1");
        let asserts = assertions_for("Option<AsNumericVec>", "x");
        assert_eq!(asserts.len(), 1);
        assert!(asserts[0].condition.starts_with("is.null(x) || "));
    }

    #[test]
    fn as_character_markers_admit_atomic_vectors() {
        let asserts = assertions_for("AsCharacter", "x");
        assert_eq!(asserts.len(), 2);
        assert_eq!(asserts[0].message(), "'x' must be atomic");
        assert_eq!(asserts[0].condition, "is.atomic(x)");
        assert_eq!(asserts[1].message(), "'x' must have length 1");
        assert_eq!(asserts[1].condition, "length(x) == 1L");

        // Path-qualified spellings resolve by their last segment.
        let asserts = assertions_for("miniextendr_api::AsCharacterVec", "x");
        assert_eq!(asserts.len(), 1);
        assert_eq!(asserts[0].message(), "'x' must be atomic");
        assert_eq!(asserts[0].condition, "is.atomic(x)");
    }

    #[test]
    fn optional_as_character_is_nullable() {
        let asserts = assertions_for("Option<AsCharacter>", "x");
        assert_eq!(asserts.len(), 2);
        assert_eq!(asserts[0].message(), "'x' must be NULL or atomic");
        assert_eq!(asserts[0].condition, "is.null(x) || is.atomic(x)");
        assert_eq!(asserts[1].message(), "'x' must be NULL or have length 1");
        let asserts = assertions_for("Option<AsCharacterVec>", "x");
        assert_eq!(asserts.len(), 1);
        assert_eq!(asserts[0].message(), "'x' must be NULL or atomic");
        assert_eq!(asserts[0].condition, "is.null(x) || is.atomic(x)");
    }

    #[test]
    fn as_character_vec_with_no_na_checks_type_then_na() {
        let out = explicit_output("fn f(x: AsCharacterVec)", &[("x", no_na())], false);
        assert_eq!(
            out.guards(None),
            vec![
                "if (!isTRUE(is.atomic(x))) .miniextendr_arg_error(\"x\", \"must be atomic\")",
                "if (!isTRUE(!anyNA(x))) .miniextendr_arg_error(\"x\", \"must not contain NA\")",
            ]
        );
    }

    #[test]
    fn coerce_keeps_the_as_numeric_gate() {
        // `AsNumeric` has no coercion mapping: `coerce` leaves its gate alone.
        let ty = parse_type("AsNumericVec");
        let check = coerce_widened(r_check_for_type(&ty).unwrap(), &ty);
        let asserts = check.assertions("x");
        assert_eq!(asserts.len(), 1);
        assert!(asserts[0].condition.contains("is.factor(x)"));
    }

    #[test]
    fn map_types() {
        for ty_str in &["HashMap<String, i32>", "BTreeMap<String, f64>"] {
            let ty = parse_type(ty_str);
            let asserts = r_check_for_type(&ty).unwrap().assertions("x");
            assert_eq!(asserts.len(), 1);
            assert_eq!(asserts[0].condition, "is.list(x)");
        }
    }

    #[test]
    fn skip_types() {
        for ty_str in &["SEXP", "ExternalPtr<MyType>"] {
            let ty = parse_type(ty_str);
            assert!(
                r_check_for_type(&ty).is_none(),
                "{} should be skipped",
                ty_str
            );
        }
    }

    #[test]
    fn scalar_param_produces_one_guard_per_check() {
        let sig: syn::Signature = syn::parse_str("fn f(n: i32)").unwrap();
        let output = build_precondition_checks(
            &sig.inputs,
            &HashSet::new(),
            &PreconditionOptions::default(),
        );
        let checks = output.guards(None);
        assert_eq!(checks.len(), 2);
        assert!(checks[0].contains("\"must be integer\""));
        assert!(checks[1].contains("\"must have length 1\""));
        assert!(output.fallback_params.is_empty());
    }

    #[test]
    fn vector_param_single_guard() {
        // Vec<f64> produces 1 check → one guard line
        let sig: syn::Signature = syn::parse_str("fn f(x: Vec<f64>)").unwrap();
        let output = build_precondition_checks(
            &sig.inputs,
            &HashSet::new(),
            &PreconditionOptions::default(),
        );
        assert_eq!(
            output.guards(None),
            vec!["if (!isTRUE(is.double(x))) .miniextendr_arg_error(\"x\", \"must be double\")"]
        );
    }

    #[test]
    fn two_scalar_params_produce_four_guards_in_order() {
        let sig: syn::Signature = syn::parse_str("fn f(a: i32, b: f64)").unwrap();
        let output = build_precondition_checks(
            &sig.inputs,
            &HashSet::new(),
            &PreconditionOptions::default(),
        );
        let checks = output.guards(None);
        // 2 checks per param
        assert_eq!(checks.len(), 4);
        assert!(checks[0].contains("(\"a\", ") && checks[0].contains("integer"));
        assert!(checks[1].contains("(\"a\", ") && checks[1].contains("length 1"));
        assert!(checks[2].contains("(\"b\", ") && checks[2].contains("double"));
        assert!(checks[3].contains("(\"b\", ") && checks[3].contains("length 1"));
    }

    #[test]
    fn build_checks_skips_match_arg() {
        let sig: syn::Signature = syn::parse_str("fn f(n: i32, mode: String)").unwrap();
        let mut skip = HashSet::new();
        skip.insert("mode".to_string());
        let output = build_precondition_checks(&sig.inputs, &skip, &PreconditionOptions::default());
        // Only n's 2 checks remain
        let joined = output.guards(None).join("\n");
        assert!(joined.contains("(\"n\", "));
        assert!(!joined.contains("mode"));
    }

    #[test]
    fn unknown_type_produces_fallback() {
        let sig: syn::Signature = syn::parse_str("fn f(x: MyCustomType)").unwrap();
        let output = build_precondition_checks(
            &sig.inputs,
            &HashSet::new(),
            &PreconditionOptions::default(),
        );
        assert!(output.guards(None).is_empty());
        assert_eq!(output.fallback_params.len(), 1);
        assert_eq!(output.fallback_params[0].r_name, "x");
    }

    #[test]
    fn mixed_known_and_unknown_types() {
        let sig: syn::Signature = syn::parse_str("fn f(a: i32, b: MyType, c: String)").unwrap();
        let output = build_precondition_checks(
            &sig.inputs,
            &HashSet::new(),
            &PreconditionOptions::default(),
        );
        // a (i32) and c (String) are known → checks
        let joined = output.guards(None).join("\n");
        assert!(joined.contains("(\"a\", "));
        assert!(joined.contains("(\"c\", "));
        assert!(!joined.contains("(\"b\", "));
        // b (MyType) is unknown → fallback
        assert_eq!(output.fallback_params.len(), 1);
        assert_eq!(output.fallback_params[0].r_name, "b");
    }

    #[test]
    fn sexp_not_fallback() {
        let sig: syn::Signature = syn::parse_str("fn f(x: SEXP)").unwrap();
        let output = build_precondition_checks(
            &sig.inputs,
            &HashSet::new(),
            &PreconditionOptions::default(),
        );
        assert!(output.guards(None).is_empty());
        assert!(output.fallback_params.is_empty());
    }

    /// Build checks for `sig` with the given explicit checks keyed by R name.
    /// The checks of `sig` with the named `explicit` checks; `no_type_checks`
    /// drops every parameter's type-derived checks.
    fn explicit_output(
        sig: &str,
        explicit: &[(&str, ExplicitChecks)],
        no_type_checks: bool,
    ) -> PreconditionOutput {
        let sig: syn::Signature = syn::parse_str(sig).unwrap();
        let unchecked = if no_type_checks {
            unchecked_params(
                &sig.inputs,
                &Default::default(),
                |_| Some(false),
                None,
                None,
                None,
            )
        } else {
            HashSet::new()
        };
        let opts = PreconditionOptions {
            explicit: explicit
                .iter()
                .map(|(name, checks)| (name.to_string(), checks.clone()))
                .collect(),
            unchecked,
            ..Default::default()
        };
        build_precondition_checks(&sig.inputs, &HashSet::new(), &opts)
    }

    /// The precedence table of `resolve_type_checks`: the first spelling that
    /// speaks wins, from the parameter down to the feature; the framework
    /// default keeps the checks. `(param, item, impl, crate, feature) → keep`.
    #[test]
    fn resolve_type_checks_follows_the_precedence_table() {
        /// `(param, item, impl, crate, feature, keep)`.
        type Case = (
            Option<bool>,
            Option<bool>,
            Option<bool>,
            Option<bool>,
            bool,
            bool,
        );
        let cases: &[Case] = &[
            // Rank 6: nothing speaks.
            (None, None, None, None, false, true),
            // Rank 5: the feature drops them.
            (None, None, None, None, true, false),
            // Rank 4 over rank 5: the crate default beats the feature.
            (None, None, None, Some(true), true, true),
            (None, None, None, Some(false), false, false),
            // Rank 3 over 4 and 5: the impl block.
            (None, None, Some(true), Some(false), true, true),
            (None, None, Some(false), Some(true), false, false),
            // Rank 2 over 3: the fn / method keyword.
            (None, Some(true), Some(false), Some(false), true, true),
            (None, Some(false), Some(true), Some(true), false, false),
            // Rank 1 over everything: marker, per-param keyword, method list.
            (
                Some(true),
                Some(false),
                Some(false),
                Some(false),
                true,
                true,
            ),
            (
                Some(false),
                Some(true),
                Some(true),
                Some(true),
                false,
                false,
            ),
        ];
        for &(param, item, impl_level, crate_default, feature, keep) in cases {
            assert_eq!(
                resolve_type_checks(param, item, impl_level, crate_default, feature),
                keep,
                "{param:?} {item:?} {impl_level:?} {crate_default:?} {feature}"
            );
        }
        // The item-level decision is ranks 2 to 6.
        assert!(!resolve_item_type_checks(None, None, Some(false), false));
        assert!(resolve_item_type_checks(
            Some(true),
            Some(false),
            None,
            true
        ));
        assert!(!resolve_item_type_checks(None, None, None, true));
    }

    /// `unchecked` drops one parameter's type-derived checks and keeps the
    /// others', and keeps that parameter's named checks.
    #[test]
    fn unchecked_drops_one_parameter_and_keeps_its_named_checks() {
        let sig: syn::Signature = syn::parse_str("fn f(n: i32, xs: Vec<f64>)").unwrap();
        let unchecked = unchecked_params(
            &sig.inputs,
            &Default::default(),
            |name| (name == "xs").then_some(false),
            None,
            None,
            Some(true),
        );
        assert_eq!(unchecked, ["xs".to_string()].into_iter().collect());
        let opts = PreconditionOptions {
            explicit: [("xs".to_string(), no_na())].into_iter().collect(),
            unchecked,
            ..Default::default()
        };
        let guards = build_precondition_checks(&sig.inputs, &HashSet::new(), &opts).guards(None);
        assert_eq!(
            guards,
            vec![
                "if (!isTRUE(is.integer(n))) .miniextendr_arg_error(\"n\", \"must be integer\")",
                "if (!isTRUE(length(n) == 1L)) .miniextendr_arg_error(\"n\", \"must have length 1\")",
                "if (!isTRUE(!anyNA(xs))) .miniextendr_arg_error(\"xs\", \"must not contain NA\")",
            ]
        );
        // The set holds R names: `_n` is the R formal `n`.
        let sig: syn::Signature = syn::parse_str("fn f(_n: i32)").unwrap();
        let unchecked = unchecked_params(
            &sig.inputs,
            &Default::default(),
            |_| None,
            Some(false),
            None,
            None,
        );
        assert_eq!(unchecked, ["n".to_string()].into_iter().collect());
    }

    /// An item-level `no_preconditions` leaves `no_na` alone: a plain
    /// parameter keeps its R guard, and an `Either` (which has no type-derived
    /// check, so no rank-1 spelling) still gets none, its NA check running in
    /// Rust after the conversion.
    #[test]
    fn item_no_preconditions_keeps_no_na_and_either_stays_rust_side() {
        let sig: syn::Signature =
            syn::parse_str("fn f(x: Either<AsNumeric, DataFrame>, y: f64)").unwrap();
        let opts = PreconditionOptions {
            explicit: [("x".to_string(), no_na()), ("y".to_string(), no_na())]
                .into_iter()
                .collect(),
            unchecked: unchecked_params(
                &sig.inputs,
                &Default::default(),
                |_| None,
                Some(false),
                None,
                None,
            ),
            ..Default::default()
        };
        let guards = build_precondition_checks(&sig.inputs, &HashSet::new(), &opts).guards(None);
        assert_eq!(
            guards,
            vec!["if (!isTRUE(!anyNA(y))) .miniextendr_arg_error(\"y\", \"must not be NA\")"]
        );
    }

    #[test]
    fn has_type_check_is_false_for_unguarded_types() {
        for guarded in [
            "i32",
            "Option<f64>",
            "&str",
            "&[f64]",
            "Vec<String>",
            "u16",
            "List",
        ] {
            assert!(has_type_check(&parse_type(guarded)), "{guarded}");
        }
        for bare in [
            "SEXP",
            "Missing<i32>",
            "ExternalPtr<T>",
            "&Dots",
            "MyType",
            "Call",
            "Either<AsNumeric, DataFrame>",
        ] {
            assert!(!has_type_check(&parse_type(bare)), "{bare}");
        }
    }

    fn inherits(classes: &[&str]) -> ExplicitChecks {
        ExplicitChecks {
            inherits: Some(classes.iter().map(|c| c.to_string()).collect()),
            ..Default::default()
        }
    }

    fn no_na() -> ExplicitChecks {
        ExplicitChecks {
            no_na: true,
            ..Default::default()
        }
    }

    fn with_inherits_message(classes: &[&str], message: &str) -> ExplicitChecks {
        ExplicitChecks {
            inherits_message: Some(message.to_string()),
            ..inherits(classes)
        }
    }

    fn with_no_na_message(message: &str) -> ExplicitChecks {
        ExplicitChecks {
            no_na_message: Some(message.to_string()),
            ..no_na()
        }
    }

    #[test]
    fn inherits_precedes_the_type_check() {
        let out = explicit_output("fn f(x: List)", &[("x", inherits(&["pkg_obj"]))], false);
        assert_eq!(
            out.guards(None),
            vec![
                "if (!isTRUE(inherits(x, \"pkg_obj\"))) .miniextendr_arg_error(\"x\", \"must inherit from 'pkg_obj'\")",
                "if (!isTRUE(is.list(x))) .miniextendr_arg_error(\"x\", \"must be a list\")",
            ]
        );
    }

    /// An `inherits` message is the message of every type check on the
    /// parameter too: storage and length alike.
    #[test]
    fn inherits_message_covers_the_type_checks() {
        let out = explicit_output(
            "fn f(x: f64)",
            &[("x", with_inherits_message(&["pkg_unit"], "need a pkg_unit"))],
            false,
        );
        assert_eq!(
            out.guards(None),
            vec![
                "if (!isTRUE(inherits(x, \"pkg_unit\"))) .miniextendr_arg_error(\"x\", message = \"need a pkg_unit\")",
                "if (!isTRUE(is.double(x))) .miniextendr_arg_error(\"x\", message = \"need a pkg_unit\")",
                "if (!isTRUE(length(x) == 1L)) .miniextendr_arg_error(\"x\", message = \"need a pkg_unit\")",
            ]
        );
    }

    #[test]
    fn inherits_message_on_option() {
        let out = explicit_output(
            "fn f(x: Option<List>)",
            &[("x", with_inherits_message(&["pkg_obj"], "need a pkg_obj"))],
            false,
        );
        assert_eq!(
            out.guards(None),
            vec![
                "if (!isTRUE(is.null(x) || inherits(x, \"pkg_obj\"))) .miniextendr_arg_error(\"x\", message = \"need a pkg_obj\")",
                "if (!isTRUE(is.null(x) || is.list(x))) .miniextendr_arg_error(\"x\", message = \"need a pkg_obj\")",
            ]
        );
    }

    /// The `inherits` message does not cover the NA check, which keeps its
    /// generated message.
    #[test]
    fn no_na_keeps_its_own_message() {
        let mut checks = with_inherits_message(&["pkg_num"], "need a pkg_num");
        checks.merge(no_na()).unwrap();
        let out = explicit_output("fn f(x: Vec<f64>)", &[("x", checks)], false);
        assert_eq!(
            out.guards(None),
            vec![
                "if (!isTRUE(inherits(x, \"pkg_num\"))) .miniextendr_arg_error(\"x\", message = \"need a pkg_num\")",
                "if (!isTRUE(is.double(x))) .miniextendr_arg_error(\"x\", message = \"need a pkg_num\")",
                "if (!isTRUE(!anyNA(x))) .miniextendr_arg_error(\"x\", \"must not contain NA\")",
            ]
        );
    }

    /// `coerce` widens the type checks; the widened checks carry the message.
    #[test]
    fn inherits_message_with_coerce() {
        let sig: syn::Signature = syn::parse_str("fn f(x: i32)").unwrap();
        let opts = PreconditionOptions {
            coerce_all: true,
            explicit: [(
                "x".to_string(),
                with_inherits_message(&["pkg_count"], "need a pkg_count"),
            )]
            .into_iter()
            .collect(),
            ..Default::default()
        };
        let out = build_precondition_checks(&sig.inputs, &HashSet::new(), &opts);
        let guards = out.guards(None);
        assert_eq!(guards.len(), 3, "{guards:?}");
        assert!(guards[0].starts_with("if (!isTRUE(inherits(x, \"pkg_count\")))"));
        assert!(
            guards[1].contains("is.integer(x) || is.logical(x) || is.raw(x)"),
            "{}",
            guards[1]
        );
        assert!(guards[2].contains("length(x) == 1L"), "{}", guards[2]);
        for guard in &guards {
            assert!(
                guard.ends_with(".miniextendr_arg_error(\"x\", message = \"need a pkg_count\")"),
                "{guard}"
            );
        }
    }

    /// `Missing<T>` has no R type check, so the class check is its only guard.
    #[test]
    fn inherits_message_on_missing() {
        let out = explicit_output(
            "fn f(x: Missing<List>)",
            &[("x", with_inherits_message(&["pkg_obj"], "need a pkg_obj"))],
            false,
        );
        assert_eq!(
            out.guards(None),
            vec![
                "if (!isTRUE(missing(x) || inherits(x, \"pkg_obj\"))) .miniextendr_arg_error(\"x\", message = \"need a pkg_obj\")"
            ]
        );
    }

    #[test]
    fn inherits_any_of_several_classes() {
        let out = explicit_output("fn f(x: SEXP)", &[("x", inherits(&["a", "b", "c"]))], false);
        assert_eq!(
            out.guards(None),
            vec![
                "if (!isTRUE(inherits(x, c(\"a\", \"b\", \"c\")))) .miniextendr_arg_error(\"x\", \"must inherit from 'a', 'b' or 'c'\")"
            ]
        );
    }

    #[test]
    fn inherits_escapes_quotes_and_backslashes() {
        let out = explicit_output("fn f(x: SEXP)", &[("x", inherits(&["a\"b\\c"]))], false);
        assert_eq!(
            out.guards(None),
            vec![
                "if (!isTRUE(inherits(x, \"a\\\"b\\\\c\"))) .miniextendr_arg_error(\"x\", \"must inherit from 'a\\\"b\\\\c'\")"
            ]
        );
    }

    fn not_inherits(classes: &[&str]) -> ExplicitChecks {
        ExplicitChecks {
            not_inherits: Some(classes.iter().map(|c| c.to_string()).collect()),
            ..Default::default()
        }
    }

    fn with_not_inherits_message(classes: &[&str], message: &str) -> ExplicitChecks {
        ExplicitChecks {
            not_inherits_message: Some(message.to_string()),
            ..not_inherits(classes)
        }
    }

    /// The #1815 case: `not_inherits` with a message on an `Option<AsNumeric>`
    /// with `no_na`. The refusal runs before the marker's type checks
    /// (`is.numeric()` is `FALSE` for these classes, so after them it would
    /// never be reached), passes `NULL`, and leaves the type and NA checks
    /// their generated messages.
    #[test]
    fn not_inherits_precedes_the_type_checks_and_keeps_their_messages() {
        let mut checks = with_not_inherits_message(
            &["difftime", "Date", "POSIXt"],
            "`tau` must be a plain number",
        );
        checks.merge(no_na()).unwrap();
        let out = explicit_output("fn f(tau: Option<AsNumeric>)", &[("tau", checks)], false);
        assert_eq!(
            out.guards(None),
            vec![
                "if (!isTRUE(is.null(tau) || !inherits(tau, c(\"difftime\", \"Date\", \"POSIXt\")))) .miniextendr_arg_error(\"tau\", message = \"`tau` must be a plain number\")",
                "if (!isTRUE(is.null(tau) || is.numeric(tau) || is.logical(tau) || is.character(tau) || is.factor(tau))) .miniextendr_arg_error(\"tau\", \"must be NULL or numeric, logical, character, or factor\")",
                "if (!isTRUE(is.null(tau) || length(tau) == 1L)) .miniextendr_arg_error(\"tau\", \"must be NULL or have length 1\")",
                "if (!isTRUE(is.null(tau) || !anyNA(tau))) .miniextendr_arg_error(\"tau\", \"must not be NA\")",
            ]
        );
    }

    /// Without a message, the refusal names the classes the way `inherits`
    /// names the required ones.
    #[test]
    fn not_inherits_generated_message() {
        let one = explicit_output("fn f(x: SEXP)", &[("x", not_inherits(&["Date"]))], false);
        assert_eq!(
            one.guards(None),
            vec![
                "if (!isTRUE(!inherits(x, \"Date\"))) .miniextendr_arg_error(\"x\", \"must not inherit from 'Date'\")"
            ]
        );
        let several = explicit_output(
            "fn f(x: SEXP)",
            &[("x", not_inherits(&["difftime", "Date", "POSIXt"]))],
            false,
        );
        let guards = several.guards(None);
        assert_eq!(
            guards,
            vec![
                "if (!isTRUE(!inherits(x, c(\"difftime\", \"Date\", \"POSIXt\")))) .miniextendr_arg_error(\"x\", \"must not inherit from 'difftime', 'Date' or 'POSIXt'\")"
            ]
        );
        let asserts = not_inherits(&["a\"b"]).class_assertions("x", &parse_type("SEXP"));
        assert_eq!(asserts[0].message(), "'x' must not inherit from 'a\\\"b'");
    }

    /// `inherits` and `not_inherits` on one parameter: the required classes
    /// first, then the refused ones, then the type checks, which take the
    /// `inherits` message only.
    #[test]
    fn inherits_and_not_inherits_compose() {
        let mut checks = with_inherits_message(&["pkg_obj"], "need a pkg_obj");
        checks
            .merge(with_not_inherits_message(
                &["pkg_old"],
                "pkg_old is retired",
            ))
            .unwrap();
        let out = explicit_output("fn f(x: List)", &[("x", checks)], false);
        assert_eq!(
            out.guards(None),
            vec![
                "if (!isTRUE(inherits(x, \"pkg_obj\"))) .miniextendr_arg_error(\"x\", message = \"need a pkg_obj\")",
                "if (!isTRUE(!inherits(x, \"pkg_old\"))) .miniextendr_arg_error(\"x\", message = \"pkg_old is retired\")",
                "if (!isTRUE(is.list(x))) .miniextendr_arg_error(\"x\", message = \"need a pkg_obj\")",
            ]
        );
        // A `not_inherits` message alone leaves the type check's wording.
        let out = explicit_output(
            "fn f(x: List)",
            &[("x", with_not_inherits_message(&["pkg_old"], "retired"))],
            false,
        );
        assert_eq!(
            out.guards(None)[1],
            "if (!isTRUE(is.list(x))) .miniextendr_arg_error(\"x\", \"must be a list\")"
        );
    }

    /// The check is plain R on the formal, so it needs no type check: an
    /// `Either` (no R guard at all, its `no_na` checked in Rust) gets it, and
    /// so does a parameter under `no_preconditions`. `Missing<T>` passes an
    /// omitted argument, `Option<Either<..>>` `NULL`. A bare `Either` arm
    /// that reads `NULL` needs no prefix: `!inherits(NULL, cls)` is `TRUE`.
    #[test]
    fn not_inherits_without_type_checks() {
        let refused = || not_inherits(&["difftime"]);
        let guards = |sig: &str, no_type_checks: bool| {
            let mut checks = refused();
            checks.merge(no_na()).unwrap();
            explicit_output(sig, &[("x", checks)], no_type_checks).guards(None)
        };
        let either = guards("fn f(x: Either<Option<AsNumeric>, DataFrame>)", false);
        assert_eq!(
            either,
            vec![
                "if (!isTRUE(!inherits(x, \"difftime\"))) .miniextendr_arg_error(\"x\", \"must not inherit from 'difftime'\")"
            ]
        );
        let optional_either = guards("fn f(x: Option<Either<AsNumeric, DataFrame>>)", false);
        assert_eq!(optional_either.len(), 1);
        assert!(
            optional_either[0]
                .starts_with("if (!isTRUE(is.null(x) || !inherits(x, \"difftime\")))"),
            "{optional_either:?}"
        );
        let unchecked = guards("fn f(x: Option<AsNumeric>)", true);
        assert_eq!(unchecked.len(), 2, "{unchecked:?}");
        assert!(unchecked[0].contains("!inherits(x, \"difftime\")"));
        assert!(unchecked[1].contains("!anyNA(x)"));
        let missing = explicit_output("fn f(x: Missing<f64>)", &[("x", refused())], false);
        assert_eq!(
            missing.guards(None)[0],
            "if (!isTRUE(missing(x) || !inherits(x, \"difftime\"))) .miniextendr_arg_error(\"x\", \"must not inherit from 'difftime'\")"
        );
    }

    /// Under `call = caller` the refusal names the caller's call: positional
    /// after the generated requirement, by name after a message.
    #[test]
    fn not_inherits_takes_the_caller_call() {
        let plain = explicit_output("fn f(x: SEXP)", &[("x", not_inherits(&["Date"]))], false);
        assert!(plain.guards(Some(".mx_call"))[0].ends_with(
            ".miniextendr_arg_error(\"x\", \"must not inherit from 'Date'\", .mx_call)"
        ));
        let custom = explicit_output(
            "fn f(x: SEXP)",
            &[("x", with_not_inherits_message(&["Date"], "no dates"))],
            false,
        );
        assert!(
            custom.guards(Some(".mx_call"))[0].ends_with(
                ".miniextendr_arg_error(\"x\", message = \"no dates\", call = .mx_call)"
            )
        );
    }

    /// A class in both lists is a contradiction the parsers reject; any
    /// other pairing, or one list alone, is fine. Merging keeps the two
    /// lists and their messages apart.
    #[test]
    fn not_inherits_merge_and_conflict() {
        let mut checks = inherits(&["a", "b"]);
        checks.merge(not_inherits(&["c"])).unwrap();
        assert_eq!(checks.class_conflict("x"), None);
        checks
            .merge(with_not_inherits_message(&["d"], "m"))
            .unwrap();
        assert_eq!(checks.not_inherits, Some(vec!["c".into(), "d".into()]));
        assert_eq!(checks.not_inherits_message.as_deref(), Some("m"));
        assert!(checks.inherits_message.is_none());
        let err = checks
            .merge(with_not_inherits_message(&["e"], "n"))
            .unwrap_err();
        assert!(err.contains("`not_inherits`"), "{err}");
        checks.merge(not_inherits(&["b"])).unwrap();
        let err = checks.class_conflict("x").expect("b is in both");
        assert!(
            err.contains("class `b` is in both `inherits` and `not_inherits` on parameter `x`"),
            "{err}"
        );
        assert!(!not_inherits(&["a"]).is_empty());
        assert_eq!(not_inherits(&["a"]).class_conflict("x"), None);
    }

    // region: `when(...)` hints on `inherits` (#1824)

    /// `inherits(classes, message, when(...) ...)`: `hints` are
    /// `(classes, message)` pairs, in the order written.
    fn with_hints(
        classes: &[&str],
        message: Option<&str>,
        hints: &[(&[&str], &str)],
    ) -> ExplicitChecks {
        ExplicitChecks {
            inherits_message: message.map(str::to_string),
            inherits_hints: hints
                .iter()
                .map(|(classes, message)| InheritsHint {
                    classes: classes.iter().map(|c| c.to_string()).collect(),
                    message: message.to_string(),
                })
                .collect(),
            ..inherits(classes)
        }
    }

    /// Each hint is one check ahead of the `inherits` check, in the order
    /// written, so the first hint naming one of a refused value's classes is
    /// raised. A value that passes `inherits` passes every hint
    /// (`inherits(p, <required>) || ...`), so a `pkg_model` that is also a
    /// `data.frame` is accepted. The type checks keep the `inherits` message.
    #[test]
    fn inherits_hints_precede_the_check_in_written_order() {
        let checks = with_hints(
            &["pkg_model"],
            Some("`model` must be a `pkg_model` object"),
            &[
                (&["data.frame"], "a data frame: use `col_dose()`"),
                (&["pkg_fit", "pkg_results"], "a fit: use `fit$model`"),
            ],
        );
        let out = explicit_output("fn f(model: List)", &[("model", checks)], false);
        assert_eq!(
            out.guards(None),
            vec![
                "if (!isTRUE(inherits(model, \"pkg_model\") || !inherits(model, \"data.frame\"))) .miniextendr_arg_error(\"model\", message = \"a data frame: use `col_dose()`\")",
                "if (!isTRUE(inherits(model, \"pkg_model\") || !inherits(model, c(\"pkg_fit\", \"pkg_results\")))) .miniextendr_arg_error(\"model\", message = \"a fit: use `fit$model`\")",
                "if (!isTRUE(inherits(model, \"pkg_model\"))) .miniextendr_arg_error(\"model\", message = \"`model` must be a `pkg_model` object\")",
                "if (!isTRUE(is.list(model))) .miniextendr_arg_error(\"model\", message = \"`model` must be a `pkg_model` object\")",
            ]
        );
        // Without its own message the check keeps the generated one; several
        // required classes are all accepted by every hint.
        let checks = with_hints(&["pkg_a", "pkg_b"], None, &[(&["data.frame"], "hint")]);
        let out = explicit_output("fn f(x: SEXP)", &[("x", checks)], false);
        assert_eq!(
            out.guards(None),
            vec![
                "if (!isTRUE(inherits(x, c(\"pkg_a\", \"pkg_b\")) || !inherits(x, \"data.frame\"))) .miniextendr_arg_error(\"x\", message = \"hint\")",
                "if (!isTRUE(inherits(x, c(\"pkg_a\", \"pkg_b\")))) .miniextendr_arg_error(\"x\", \"must inherit from 'pkg_a' or 'pkg_b'\")",
            ]
        );
    }

    /// A hint is an R string literal like any message: quotes, backslashes,
    /// control characters and non-ASCII text are escaped, and so are its
    /// class names.
    #[test]
    fn inherits_hints_are_escaped() {
        let checks = with_hints(
            &["pkg_model"],
            None,
            &[(
                &["caf\u{e9}", "a\"b\\c"],
                "say \"hi\" \\ back\nline caf\u{e9} \u{1F600}",
            )],
        );
        let out = explicit_output("fn f(x: SEXP)", &[("x", checks)], false);
        assert_eq!(
            out.guards(None)[0],
            r#"if (!isTRUE(inherits(x, "pkg_model") || !inherits(x, c("caf\u{e9}", "a\"b\\c")))) .miniextendr_arg_error("x", message = "say \"hi\" \\ back\nline caf\u{e9} \U{1f600}")"#
        );
    }

    /// Under `call = caller` a hint names the caller's call, by name after
    /// its message.
    #[test]
    fn inherits_hints_take_the_caller_call() {
        let checks = with_hints(&["pkg_model"], None, &[(&["data.frame"], "hint")]);
        let out = explicit_output("fn f(x: SEXP)", &[("x", checks)], false);
        assert_eq!(
            out.guards(Some(".mx_call")),
            vec![
                "if (!isTRUE(inherits(x, \"pkg_model\") || !inherits(x, \"data.frame\"))) .miniextendr_arg_error(\"x\", message = \"hint\", call = .mx_call)",
                "if (!isTRUE(inherits(x, \"pkg_model\"))) .miniextendr_arg_error(\"x\", \"must inherit from 'pkg_model'\", .mx_call)",
            ]
        );
    }

    /// An `Option<T>` parameter passes `NULL`, and a `Missing<T>` parameter
    /// an omitted argument, through the hints as through the check. Under
    /// `no_preconditions` the hints stay with the check.
    #[test]
    fn inherits_hints_pass_null_and_missing() {
        let hinted = || with_hints(&["pkg_model"], None, &[(&["data.frame"], "hint")]);
        let optional = explicit_output("fn f(x: Option<List>)", &[("x", hinted())], true);
        assert_eq!(
            optional.guards(None)[0],
            "if (!isTRUE(is.null(x) || inherits(x, \"pkg_model\") || !inherits(x, \"data.frame\"))) .miniextendr_arg_error(\"x\", message = \"hint\")"
        );
        let missing = explicit_output("fn f(x: Missing<List>)", &[("x", hinted())], true);
        assert_eq!(
            missing.guards(None),
            vec![
                "if (!isTRUE(missing(x) || inherits(x, \"pkg_model\") || !inherits(x, \"data.frame\"))) .miniextendr_arg_error(\"x\", message = \"hint\")",
                "if (!isTRUE(missing(x) || inherits(x, \"pkg_model\"))) .miniextendr_arg_error(\"x\", \"must inherit from 'pkg_model'\")",
            ]
        );
    }

    /// Several `inherits` attributes on one parameter concatenate their
    /// hints in the order written; every hint then accepts every required
    /// class.
    #[test]
    fn inherits_hints_merge_in_order() {
        let mut checks = with_hints(&["pkg_a"], Some("need an a"), &[(&["df"], "one")]);
        checks
            .merge(with_hints(&["pkg_b"], None, &[(&["tbl"], "two")]))
            .unwrap();
        checks.merge(inherits(&["pkg_c"])).unwrap();
        let hints: Vec<&str> = checks
            .inherits_hints
            .iter()
            .map(|h| h.message.as_str())
            .collect();
        assert_eq!(hints, ["one", "two"]);
        assert_eq!(checks.class_conflict("x"), None);
        let out = explicit_output("fn f(x: SEXP)", &[("x", checks)], false);
        let guards = out.guards(None);
        assert_eq!(guards.len(), 3);
        assert!(
            guards[0].starts_with(
                "if (!isTRUE(inherits(x, c(\"pkg_a\", \"pkg_b\", \"pkg_c\")) || !inherits(x, \"df\")))"
            ),
            "{}",
            guards[0]
        );
        assert!(guards[1].contains("!inherits(x, \"tbl\"))) "));
        assert!(guards[1].ends_with("message = \"two\")"));
        assert!(guards[2].ends_with("message = \"need an a\")"));
    }

    /// A hint class that `inherits` requires could never be shown: an error,
    /// also when another attribute requires it. A hint class that
    /// `not_inherits` refuses is fine: a value of that class alone gets the
    /// hint, one that also has a required class gets the refusal.
    #[test]
    fn inherits_hint_class_conflicts() {
        let checks = with_hints(&["pkg_model"], None, &[(&["df", "pkg_model"], "hint")]);
        let err = checks
            .class_conflict("model")
            .expect("pkg_model is required");
        assert!(
            err.contains(
                "class `pkg_model` is in both `inherits` and a `when(...)` hint on parameter `model`"
            ),
            "{err}"
        );
        let mut checks = with_hints(&["pkg_model"], None, &[(&["pkg_old"], "hint")]);
        assert_eq!(checks.class_conflict("model"), None);
        checks.merge(inherits(&["pkg_old"])).unwrap();
        assert!(checks.class_conflict("model").is_some());

        let mut checks = with_hints(&["pkg_model"], None, &[(&["pkg_old"], "hint")]);
        checks.merge(not_inherits(&["pkg_old"])).unwrap();
        assert_eq!(checks.class_conflict("model"), None);
        let out = explicit_output("fn f(x: SEXP)", &[("x", checks)], false);
        assert_eq!(
            out.guards(None),
            vec![
                "if (!isTRUE(inherits(x, \"pkg_model\") || !inherits(x, \"pkg_old\"))) .miniextendr_arg_error(\"x\", message = \"hint\")",
                "if (!isTRUE(inherits(x, \"pkg_model\"))) .miniextendr_arg_error(\"x\", \"must inherit from 'pkg_model'\")",
                "if (!isTRUE(!inherits(x, \"pkg_old\"))) .miniextendr_arg_error(\"x\", \"must not inherit from 'pkg_old'\")",
            ]
        );
    }

    // endregion

    #[test]
    fn no_na_wording_follows_the_shape() {
        let scalar = explicit_output("fn f(x: f64)", &[("x", no_na())], true);
        assert_eq!(
            scalar.guards(None),
            vec!["if (!isTRUE(!anyNA(x))) .miniextendr_arg_error(\"x\", \"must not be NA\")"]
        );
        let vector = explicit_output("fn f(x: Vec<f64>)", &[("x", no_na())], true);
        assert_eq!(
            vector.guards(None),
            vec!["if (!isTRUE(!anyNA(x))) .miniextendr_arg_error(\"x\", \"must not contain NA\")"]
        );
        let slice = explicit_output("fn f(x: &[f64])", &[("x", no_na())], true);
        assert!(slice.guards(None)[0].contains("must not contain NA"));
        // The vector markers are vectors too; their scalar forms are not.
        for (ty, verb) in [
            ("AsNumericVec", "contain"),
            ("AsCharacterVec", "contain"),
            ("Option<AsCharacterVec>", "contain"),
            ("AsNumeric", "be"),
            ("AsCharacter", "be"),
        ] {
            let out = explicit_output(&format!("fn f(x: {ty})"), &[("x", no_na())], true);
            assert!(
                out.guards(None)[0].contains(&format!("must not {verb} NA")),
                "{ty}: {:?}",
                out.guards(None)
            );
        }
    }

    /// Beyond the type table's vector checks (above): a `Missing<_>` marker,
    /// maps, arrays, and a marker the table does not know, by its `...Vec`
    /// name (`AsFromStrVec<T>`, `AsDisplayVec<T>`), hold several values too;
    /// their scalar halves and opaque types do not.
    #[test]
    fn no_na_wording_knows_the_vector_markers() {
        let verb = |sig: &str| {
            let out = explicit_output(sig, &[("x", no_na())], false);
            let guards = out.guards(None);
            let guard = guards.last().expect("the no_na guard");
            if guard.contains("must not contain NA") {
                "contain"
            } else {
                assert!(guard.contains("must not be NA"), "{guard}");
                "be"
            }
        };
        for (sig, expected) in [
            ("fn f(x: Option<AsNumericVec>)", "contain"),
            ("fn f(x: Missing<AsNumericVec>)", "contain"),
            ("fn f(x: AsFromStrVec<std::net::IpAddr>)", "contain"),
            ("fn f(x: AsDisplayVec<u8>)", "contain"),
            ("fn f(x: HashMap<String, f64>)", "contain"),
            ("fn f(x: [f64; 3])", "contain"),
            // An optional data frame is worded as a bare one.
            ("fn f(x: Option<DataFrame>)", "be"),
            ("fn f(x: Option<AsNumeric>)", "be"),
            ("fn f(x: AsFromStr<std::net::IpAddr>)", "be"),
            ("fn f(x: String)", "be"),
            ("fn f(x: MyCustomType)", "be"),
            // Through `Result<T, _>` and `Either`, the layers `no_na` checks
            // through: an `Either` holds several when either arm does.
            ("fn f(x: Result<AsNumericVec, ()>)", "contain"),
            ("fn f(x: Result<AsNumeric, ()>)", "be"),
            ("fn f(x: Either<AsNumericVec, Vec<u8>>)", "contain"),
            ("fn f(x: Either<AsNumericVec, i32>)", "contain"),
            ("fn f(x: Either<i32, AsCharacterVec>)", "contain"),
            ("fn f(x: Either<AsNumeric, AsCharacter>)", "be"),
            // An `Option` arm is read by its value.
            ("fn f(x: Either<Option<AsNumeric>, DataFrame>)", "be"),
            (
                "fn f(x: Either<Option<AsNumericVec>, DataFrame>)",
                "contain",
            ),
            (
                "fn f(x: Option<Either<i32, Either<String, Vec<f64>>>>)",
                "contain",
            ),
        ] {
            let ty = match syn::parse_str::<syn::Signature>(sig).unwrap().inputs[0].clone() {
                syn::FnArg::Typed(pt) => *pt.ty,
                syn::FnArg::Receiver(_) => unreachable!(),
            };
            // An `Either` has only the Rust check; the others have the R guard
            // too, and the Rust check words it the same way.
            if !no_na_checked_after_conversion(&ty) {
                assert_eq!(verb(sig), expected, "{sig}");
            }
            assert_eq!(
                no_na_requirement(&ty),
                format!("must not {expected} NA"),
                "{sig}"
            );
        }
    }

    /// `no_na` on an `Either` (also under `Missing` or `Option`) emits no R
    /// guard: the C wrapper checks the input by the arm the value converted
    /// to. A plain parameter keeps the guard (`Option<DataFrame>` behind its
    /// `is.null(x)` pass), and so does a choice `Either` (`match_arg` /
    /// `choices`, also under `Option` / `Missing<Option<..>>`), whose
    /// conversion has no Rust check.
    #[test]
    fn no_na_on_an_either_is_checked_after_the_conversion() {
        let guards = |sig: &str, skip: &[&str]| {
            let sig: syn::Signature = syn::parse_str(sig).unwrap();
            let opts = PreconditionOptions {
                explicit: [("x".to_string(), no_na())].into_iter().collect(),
                ..Default::default()
            };
            let skip: HashSet<String> = skip.iter().map(|s| s.to_string()).collect();
            build_precondition_checks(&sig.inputs, &skip, &opts).guards(None)
        };
        for sig in [
            "fn f(x: Either<AsNumeric, DataFrame>)",
            "fn f(x: Either<Option<AsNumeric>, DataFrame>)",
            "fn f(x: either::Either<Vec<f64>, List>)",
            "fn f(x: Missing<Either<AsNumeric, DataFrame>>)",
            "fn f(x: Option<Either<AsNumericVec, DataFrame>>)",
            "fn f(x: Missing<Option<Either<f64, String>>>)",
        ] {
            assert!(
                guards(sig, &[]).iter().all(|g| !g.contains("anyNA")),
                "{sig}: {:?}",
                guards(sig, &[])
            );
        }
        for (sig, skip) in [
            ("fn f(x: AsNumeric)", &[][..]),
            ("fn f(x: DataFrame)", &[]),
            ("fn f(x: Either<Mode, DataFrame>)", &["x"]),
        ] {
            let guards = guards(sig, skip);
            assert!(
                guards
                    .last()
                    .is_some_and(|g| g.contains("!isTRUE(!anyNA(x))")),
                "{sig}: {guards:?}"
            );
        }
        // A choice `Either` under `Option` / `Missing<Option<..>>` keeps the
        // guard too, after the layer's `is.null(x)` / `missing(x)` pass, as
        // does an optional data frame.
        for (sig, layer, skip) in [
            (
                "fn f(x: Option<Either<Mode, DataFrame>>)",
                "is.null(x)",
                &["x"][..],
            ),
            (
                "fn f(x: Missing<Option<Either<Mode, List>>>)",
                "missing(x)",
                &["x"],
            ),
            ("fn f(x: Option<DataFrame>)", "is.null(x)", &[]),
        ] {
            let guards = guards(sig, skip);
            let expected = format!("!isTRUE({layer} || !anyNA(x))");
            assert!(
                guards.last().is_some_and(|g| g.contains(&expected)),
                "{sig}: {guards:?}"
            );
        }
        // `Result<Either<..>, ()>` is not a layer the predicate peels: it
        // keeps the guard, and the plain Rust check.
        assert!(!no_na_checked_after_conversion(
            &syn::parse_str("Result<Either<f64, String>, ()>").unwrap()
        ));
    }

    /// The message the Rust `no_na` check raises: generated from the
    /// parameter's R name and type, or the author's message verbatim.
    #[test]
    fn no_na_message_is_generated_or_custom() {
        let ty = |s: &str| syn::parse_str::<syn::Type>(s).unwrap();
        assert_eq!(
            no_na_message("x", &ty("AsNumeric"), None),
            "'x' must not be NA"
        );
        assert_eq!(
            no_na_message("dv", &ty("Missing<Option<AsNumericVec>>"), None),
            "'dv' must not contain NA"
        );
        // A vector alias not named `...Vec` reads `be`, as its R guard does.
        assert_eq!(no_na_message("d", &ty("Doses"), None), "'d' must not be NA");
        let custom = "`x` can't be NA: it's \"required\" \\ 100%\ncaf\u{e9}()";
        assert_eq!(no_na_message("x", &ty("AsNumeric"), Some(custom)), custom);
    }

    #[test]
    fn explicit_checks_pass_null_and_missing() {
        let optional = explicit_output(
            "fn f(x: Option<List>)",
            &[("x", inherits(&["pkg_obj"]))],
            true,
        );
        assert_eq!(
            optional.guards(None),
            vec![
                "if (!isTRUE(is.null(x) || inherits(x, \"pkg_obj\"))) .miniextendr_arg_error(\"x\", \"must inherit from 'pkg_obj'\")"
            ]
        );
        let missing = explicit_output("fn f(x: Missing<f64>)", &[("x", no_na())], true);
        assert_eq!(
            missing.guards(None),
            vec![
                "if (!isTRUE(missing(x) || !anyNA(x))) .miniextendr_arg_error(\"x\", \"must not be NA\")"
            ]
        );
        let optional_vec = explicit_output("fn f(x: Option<Vec<f64>>)", &[("x", no_na())], true);
        assert!(optional_vec.guards(None)[0].contains("must not contain NA"));
    }

    #[test]
    fn explicit_checks_survive_no_type_checks() {
        let both = ExplicitChecks {
            inherits: Some(vec!["pkg_obj".into()]),
            no_na: true,
            ..Default::default()
        };
        let out = explicit_output("fn f(n: i32, x: List)", &[("x", both)], true);
        // `n`'s type checks and `x`'s `is.list()` are gone; the named checks stay,
        // the class first. A list holds several values, so its NA check says
        // `contain`.
        assert_eq!(
            out.guards(None),
            vec![
                "if (!isTRUE(inherits(x, \"pkg_obj\"))) .miniextendr_arg_error(\"x\", \"must inherit from 'pkg_obj'\")",
                "if (!isTRUE(!anyNA(x))) .miniextendr_arg_error(\"x\", \"must not contain NA\")",
            ]
        );
        let none = explicit_output("fn f(n: i32)", &[], true);
        assert!(none.guards(None).is_empty());
    }

    #[test]
    fn explicit_checks_apply_to_match_arg_params() {
        let sig: syn::Signature = syn::parse_str("fn f(mode: String)").unwrap();
        let opts = PreconditionOptions {
            explicit: [("mode".to_string(), no_na())].into_iter().collect(),
            ..Default::default()
        };
        let skip: HashSet<String> = ["mode".to_string()].into_iter().collect();
        let out = build_precondition_checks(&sig.inputs, &skip, &opts);
        assert_eq!(
            out.guards(None),
            vec!["if (!isTRUE(!anyNA(mode))) .miniextendr_arg_error(\"mode\", \"must not be NA\")"]
        );
    }

    #[test]
    fn explicit_checks_take_the_caller_call() {
        let out = explicit_output("fn f(x: f64)", &[("x", no_na())], true);
        assert_eq!(
            out.guards(Some(".mx_call")),
            vec![
                "if (!isTRUE(!anyNA(x))) .miniextendr_arg_error(\"x\", \"must not be NA\", .mx_call)"
            ]
        );
    }

    #[test]
    fn explicit_checks_merge() {
        let mut a = inherits(&["a"]);
        a.merge(no_na()).unwrap();
        a.merge(inherits(&["b"])).unwrap();
        assert_eq!(
            a,
            ExplicitChecks {
                inherits: Some(vec!["a".into(), "b".into()]),
                no_na: true,
                ..Default::default()
            }
        );
        assert!(ExplicitChecks::default().is_empty());

        // One message per check: it may come from either attribute, not both.
        let mut b = inherits(&["a"]);
        b.merge(with_inherits_message(&["b"], "one")).unwrap();
        assert_eq!(b.inherits_message.as_deref(), Some("one"));
        assert_eq!(b.inherits, Some(vec!["a".into(), "b".into()]));
        b.merge(with_no_na_message("two")).unwrap();
        assert_eq!(b.no_na_message.as_deref(), Some("two"));
        let err = b.merge(with_inherits_message(&["c"], "three")).unwrap_err();
        assert!(
            err.contains("`inherits`") && err.contains("more than one `message`"),
            "{err}"
        );
        let err = b.merge(with_no_na_message("four")).unwrap_err();
        assert!(err.contains("`no_na`"), "{err}");
    }

    /// The author's message replaces `'<p>' <requirement>` verbatim: the
    /// helper gets it as `message = `, and the call, when there is one, by
    /// name too (after a named `message` a positional call would bind to
    /// `what`). One message covers every class of the check, and the
    /// parameter's type checks.
    #[test]
    fn custom_messages_are_passed_verbatim_by_name() {
        let checks = ExplicitChecks {
            inherits: Some(vec!["pkg_a".into(), "pkg_b".into()]),
            inherits_message: Some("`model` must be a `pkg_model`; see pkg_model().".into()),
            no_na: true,
            no_na_message: Some("no NA in `model`".into()),
            ..Default::default()
        };
        let out = explicit_output("fn f(model: List)", &[("model", checks)], false);
        assert_eq!(
            out.guards(None),
            vec![
                "if (!isTRUE(inherits(model, c(\"pkg_a\", \"pkg_b\")))) .miniextendr_arg_error(\"model\", message = \"`model` must be a `pkg_model`; see pkg_model().\")",
                "if (!isTRUE(is.list(model))) .miniextendr_arg_error(\"model\", message = \"`model` must be a `pkg_model`; see pkg_model().\")",
                "if (!isTRUE(!anyNA(model))) .miniextendr_arg_error(\"model\", message = \"no NA in `model`\")",
            ]
        );
        let caller = out.guards(Some(".mx_call"));
        assert!(
            caller[0].ends_with(
                ".miniextendr_arg_error(\"model\", message = \"`model` must be a `pkg_model`; see pkg_model().\", call = .mx_call)"
            ),
            "{}",
            caller[0]
        );
        // A type check with the class message names the call too.
        assert!(
            caller[1].ends_with(
                ".miniextendr_arg_error(\"model\", message = \"`model` must be a `pkg_model`; see pkg_model().\", call = .mx_call)"
            ),
            "{}",
            caller[1]
        );
        assert!(
            caller[2].ends_with(
                ".miniextendr_arg_error(\"model\", message = \"no NA in `model`\", call = .mx_call)"
            ),
            "{}",
            caller[2]
        );
        // A type check without a class message keeps the positional call.
        let plain = explicit_output("fn f(model: List)", &[("model", no_na())], false);
        assert!(
            plain.guards(Some(".mx_call"))[0]
                .ends_with(".miniextendr_arg_error(\"model\", \"must be a list\", .mx_call)"),
            "{:?}",
            plain.guards(Some(".mx_call"))
        );
        // The `Option` / `Missing` guards are unchanged.
        let optional = explicit_output(
            "fn f(x: Option<List>)",
            &[("x", with_inherits_message(&["pkg_obj"], "need a pkg_obj"))],
            true,
        );
        assert_eq!(
            optional.guards(None),
            vec![
                "if (!isTRUE(is.null(x) || inherits(x, \"pkg_obj\"))) .miniextendr_arg_error(\"x\", message = \"need a pkg_obj\")"
            ]
        );
        let asserts = with_no_na_message("mine").value_assertions("x", &parse_type("f64"), false);
        assert_eq!(asserts[0].message(), "mine");
    }

    /// A message is an R string literal: quotes, backslashes, newlines, tabs
    /// and control characters are escaped, and non-ASCII text becomes
    /// `\u{..}` / `\U{..}` escapes (R code in a package must be ASCII). `%`
    /// needs nothing: the message never goes through `sprintf()`.
    #[test]
    fn custom_messages_are_escaped_as_r_string_literals() {
        let message = "say \"hi\" \\ back\nline\ttab 100% caf\u{e9} \u{1F600} bell\u{7}";
        let out = explicit_output("fn f(x: f64)", &[("x", with_no_na_message(message))], true);
        assert_eq!(
            out.guards(None),
            vec![
                r#"if (!isTRUE(!anyNA(x))) .miniextendr_arg_error("x", message = "say \"hi\" \\ back\nline\ttab 100% caf\u{e9} \U{1f600} bell\u{7}")"#
            ]
        );
        assert_eq!(r_string_escape("a\rb"), r"a\rb");
        assert_eq!(r_string_escape("plain 'text'"), "plain 'text'");
        // Class names take the same escaping.
        let out = explicit_output("fn f(x: SEXP)", &[("x", inherits(&["caf\u{e9}"]))], true);
        assert_eq!(
            out.guards(None),
            vec![
                r#"if (!isTRUE(inherits(x, "caf\u{e9}"))) .miniextendr_arg_error("x", "must inherit from 'caf\u{e9}'")"#
            ]
        );
    }
}