miniextendr_api/

wasm_registry_writer.rs

//! Host-time generator of `wasm_registry.rs` — the WASM-side replacement for
//! `linkme`'s runtime distributed-slice gather.
//!
//! On native installs, `tools/write-wrappers.R` loads the linked package `.so`, which runs
//! [`crate::wasm_registry_writer::write_wasm_registry_to_file`] to emit
//! Rust source listing every `MX_CALL_DEFS` / `MX_ALTREP_REGISTRATIONS` /
//! `MX_TRAIT_DISPATCH` entry as `extern "C-unwind" {}` declarations + ordinary
//! `&[T]` static slices, plus the crate's `MX_CONVERSION_ERROR_CLASS` classes.
//! On `wasm32-*` targets, the user crate compiles that
//! file in place of the linkme distributed_slices (`miniextendr_init!` emits
//! the wasm32-gated `mod __miniextendr_wasm_registry;` that includes it).
//!
//! The writer is intentionally pure-text-formatting — no `syn`, no
//! `proc-macro2`, no template engine. Registration rows are sorted so linker
//! table order does not affect the output; conversion-error classes retain
//! their dispatch precedence. The generated `wasm_registry.rs` is
//! **gitignored** (regenerated on every host `R CMD INSTALL`); determinism is
//! what lets `just r-cmd-build` reproduce it into the tarball and lets CI
//! assert a non-stub snapshot rather than git-diffing a committed copy.

use crate::abi::mx_tag;
use crate::registry::{
    AltrepRegistration, MX_ALTREP_REGISTRATIONS, MX_CALL_DEFS, MX_TRAIT_DISPATCH,
    TraitDispatchEntry,
};
use std::ffi::CStr;
use std::fmt::Write as _;

// Bumped whenever the generated-file shape changes in a way the receiving
// `build.rs` version check must reject (e.g. registry struct fields renamed
// so an old file no longer compiles). Cosmetic changes — import lines,
// qualified paths, formatting — are NOT part of the checked contract and
// don't warrant a bump (#1307). The receiving `build.rs` (step 5) refuses
// to compile a `wasm_registry.rs` whose header doesn't match.
//
// 2: `MX_CONVERSION_ERROR_CLASS_WASM`, which `miniextendr_init!` passes to
//    `install_wasm_runtime_slices` (#1768).
// 3: ALTREP registration function pointers use the C-unwind ABI.
// 4: Trait vtable symbols preserve crate, trait and type spelling (#1778).
const GENERATOR_VERSION: u32 = 4;

/// Pre-extracted, host-side view of one `R_CallMethodDef`.
///
/// `R_CallMethodDef` carries `name` as a raw `*const c_char`; safely walking
/// it requires `unsafe`. The formatter takes already-extracted, owned values
/// so it can be unit-tested without globals.
pub struct CallDefRow {
    pub name: String,
    pub num_args: i32,
}

/// Pre-extracted view of one `MX_ALTREP_REGISTRATIONS` entry.
pub struct AltrepRegRow {
    pub symbol: String,
}

/// Pre-extracted view of one `MX_TRAIT_DISPATCH` entry.
pub struct TraitDispatchRow {
    pub concrete_tag: mx_tag,
    pub trait_tag: mx_tag,
    pub vtable_symbol: String,
}

/// Format a `wasm_registry.rs` source file from extracted runtime data.
///
/// Output structure:
/// ```text
/// // header (auto-generated marker, generator-version, content-hash)
/// use ...;
/// unsafe extern "C-unwind" { fn <wrapper>(...); ... }
/// unsafe extern "C-unwind" { fn <altrep_reg>(); ... static <vtable>: u8; ... }
/// pub static MX_CALL_DEFS_WASM: &[R_CallMethodDef] = &[ ... ];
/// pub static MX_ALTREP_REGISTRATIONS_WASM: &[AltrepRegistration] = &[ ... ];
/// pub static MX_TRAIT_DISPATCH_WASM: &[TraitDispatchEntry] = &[ ... ];
/// pub static MX_CONVERSION_ERROR_CLASS_WASM: &[&str] = &[ ... ];
/// ```
///
/// Every fn / static referenced from a slice gets a matching `extern` decl —
/// the WASM linker resolves them against the user crate's `#[no_mangle]`
/// exports. `conversion_error_class` is the crate's `conversion_error_class`
/// (the `MX_CONVERSION_ERROR_CLASS` entry), which the raising guards resolve
/// an `arg_error!`'s classes from (#1768).
pub fn format_wasm_registry(
    call_defs: &[CallDefRow],
    altrep_regs: &[AltrepRegRow],
    trait_dispatches: &[TraitDispatchRow],
    conversion_error_class: &[&str],
) -> String {
    // Linkme does not promise a stable order across linking configurations.
    // Sort borrowed rows without cloning their owned symbol names. Condition
    // classes are deliberately not sorted: R dispatch uses their input order.
    let mut call_defs: Vec<_> = call_defs.iter().collect();
    call_defs.sort_unstable_by(|a, b| (&a.name, a.num_args).cmp(&(&b.name, b.num_args)));
    let mut altrep_regs: Vec<_> = altrep_regs.iter().collect();
    altrep_regs.sort_unstable_by(|a, b| a.symbol.cmp(&b.symbol));
    let mut trait_dispatches: Vec<_> = trait_dispatches.iter().collect();
    trait_dispatches.sort_unstable_by_key(|row| {
        (
            &row.vtable_symbol,
            row.concrete_tag.lo,
            row.concrete_tag.hi,
            row.trait_tag.lo,
            row.trait_tag.hi,
        )
    });

    let body = format_body(
        &call_defs,
        &altrep_regs,
        &trait_dispatches,
        conversion_error_class,
    );
    let content_hash = fnv1a_64(body.as_bytes());

    let mut out = String::new();
    writeln!(&mut out, "// AUTO-GENERATED — DO NOT EDIT.").unwrap();
    writeln!(&mut out, "//").unwrap();
    writeln!(
        &mut out,
        "// Produced on host by `miniextendr_write_wasm_registry`. Compiled on"
    )
    .unwrap();
    writeln!(
        &mut out,
        "// wasm32-* targets in place of the linkme distributed_slices."
    )
    .unwrap();
    writeln!(&mut out, "//").unwrap();
    writeln!(&mut out, "// generator-version: {GENERATOR_VERSION}").unwrap();
    writeln!(&mut out, "// content-hash:      {content_hash:016x}").unwrap();
    writeln!(&mut out).unwrap();
    out.push_str(&body);
    out
}

fn format_body(
    call_defs: &[&CallDefRow],
    altrep_regs: &[&AltrepRegRow],
    trait_dispatches: &[&TraitDispatchRow],
    conversion_error_class: &[&str],
) -> String {
    let mut out = String::new();

    // `mx_tag` and `c_void` are referenced only by trait-dispatch entries and
    // deliberately NOT imported here: a minimal package with an empty dispatch
    // table would get `unused_imports` warnings on wasm32 (#1307). The
    // dispatch entries spell both fully qualified instead. `SEXP` appears only
    // in the call-table entries, so it is imported only when there are some.
    if !call_defs.is_empty() {
        writeln!(&mut out, "use ::miniextendr_api::SEXP;").unwrap();
    }
    writeln!(&mut out, "use ::miniextendr_api::sys::R_CallMethodDef;").unwrap();
    writeln!(
        &mut out,
        "use ::miniextendr_api::registry::{{AltrepRegistration, TraitDispatchEntry}};"
    )
    .unwrap();
    writeln!(&mut out).unwrap();

    format_extern_unwind_block(&mut out, call_defs);
    format_extern_registration_block(&mut out, altrep_regs, trait_dispatches);
    format_call_defs_slice(&mut out, call_defs);
    format_altrep_regs_slice(&mut out, altrep_regs);
    format_trait_dispatch_slice(&mut out, trait_dispatches);
    format_conversion_error_class_slice(&mut out, conversion_error_class);

    out
}

fn format_extern_unwind_block(out: &mut String, call_defs: &[&CallDefRow]) {
    writeln!(out, "unsafe extern \"C-unwind\" {{").unwrap();
    for row in call_defs {
        let params = sexp_param_list(row.num_args);
        writeln!(out, "    pub fn {}({params}) -> SEXP;", row.name).unwrap();
    }
    writeln!(out, "}}").unwrap();
    writeln!(out).unwrap();
}

fn format_extern_registration_block(
    out: &mut String,
    altrep_regs: &[&AltrepRegRow],
    trait_dispatches: &[&TraitDispatchRow],
) {
    writeln!(out, "unsafe extern \"C-unwind\" {{").unwrap();
    // ALTREP register fns get the 2024-edition `safe` qualifier so the fn
    // type stays `extern "C-unwind" fn()` (not `unsafe extern "C-unwind" fn()`), allowing
    // direct assignment to `AltrepRegistration.register`. The dispatcher
    // calls them on R's main thread inside the package-init unwind boundary.
    for row in altrep_regs {
        writeln!(out, "    pub safe fn {}();", row.symbol).unwrap();
    }
    // Vtable shape is opaque from wasm_registry.rs' perspective — we only
    // need the address. Declaring as `u8` is the convention used in the
    // plan sketch and keeps the file independent of trait-specific types.
    for row in trait_dispatches {
        writeln!(out, "    #[allow(non_upper_case_globals)]").unwrap();
        writeln!(out, "    pub static {}: u8;", row.vtable_symbol).unwrap();
    }
    writeln!(out, "}}").unwrap();
    writeln!(out).unwrap();
}

fn format_call_defs_slice(out: &mut String, call_defs: &[&CallDefRow]) {
    writeln!(out, "pub static MX_CALL_DEFS_WASM: &[R_CallMethodDef] = &[").unwrap();
    for row in call_defs {
        // The transmute target signature here is positional-only — Rust's
        // `extern fn` *type* doesn't carry parameter names, only types — so
        // it differs from the `extern { fn ... }` declaration form, which
        // does require named or `_`-bound parameters.
        let arg_types = sexp_type_list(row.num_args);
        writeln!(out, "    R_CallMethodDef {{").unwrap();
        writeln!(out, "        name: c\"{}\".as_ptr(),", row.name).unwrap();
        writeln!(
            out,
            "        fun: Some(unsafe {{ ::core::mem::transmute::<unsafe extern \"C-unwind\" fn({arg_types}) -> SEXP, _>({}) }}),",
            row.name
        )
        .unwrap();
        writeln!(out, "        numArgs: {},", row.num_args).unwrap();
        writeln!(out, "    }},").unwrap();
    }
    writeln!(out, "];").unwrap();
    writeln!(out).unwrap();
}

fn format_altrep_regs_slice(out: &mut String, altrep_regs: &[&AltrepRegRow]) {
    writeln!(
        out,
        "pub static MX_ALTREP_REGISTRATIONS_WASM: &[AltrepRegistration] = &["
    )
    .unwrap();
    for row in altrep_regs {
        writeln!(out, "    AltrepRegistration {{").unwrap();
        writeln!(out, "        register: {},", row.symbol).unwrap();
        writeln!(out, "        symbol: {:?},", row.symbol).unwrap();
        writeln!(out, "    }},").unwrap();
    }
    writeln!(out, "];").unwrap();
    writeln!(out).unwrap();
}

fn format_trait_dispatch_slice(out: &mut String, trait_dispatches: &[&TraitDispatchRow]) {
    writeln!(
        out,
        "pub static MX_TRAIT_DISPATCH_WASM: &[TraitDispatchEntry] = &["
    )
    .unwrap();
    for row in trait_dispatches {
        writeln!(out, "    TraitDispatchEntry {{").unwrap();
        // `mx_tag` / `c_void` are fully qualified (no header import) so
        // dispatch-free files carry no unused imports — see format_body.
        writeln!(
            out,
            "        concrete_tag: ::miniextendr_api::abi::mx_tag::new(0x{:016x}, 0x{:016x}),",
            row.concrete_tag.lo, row.concrete_tag.hi
        )
        .unwrap();
        writeln!(
            out,
            "        trait_tag: ::miniextendr_api::abi::mx_tag::new(0x{:016x}, 0x{:016x}),",
            row.trait_tag.lo, row.trait_tag.hi
        )
        .unwrap();
        writeln!(
            out,
            "        vtable: unsafe {{ ::core::ptr::from_ref(&{}).cast::<::core::ffi::c_void>() }},",
            row.vtable_symbol
        )
        .unwrap();
        writeln!(out, "        vtable_symbol: {:?},", row.vtable_symbol).unwrap();
        writeln!(out, "    }},").unwrap();
    }
    writeln!(out, "];").unwrap();
    writeln!(out).unwrap();
}

fn format_conversion_error_class_slice(out: &mut String, classes: &[&str]) {
    writeln!(
        out,
        "pub static MX_CONVERSION_ERROR_CLASS_WASM: &[&str] = &["
    )
    .unwrap();
    for class in classes {
        // `{:?}` renders a valid Rust string literal (quotes, backslashes and
        // control characters escaped).
        writeln!(out, "    {class:?},").unwrap();
    }
    writeln!(out, "];").unwrap();
}

/// Comma-joined `_: SEXP` parameter list for an `extern { fn ...; }` decl.
///
/// Extern fn declarations require parameter bindings — bare `SEXP, SEXP`
/// is parsed as pattern-typed which fails. Each slot is `_: SEXP`.
fn sexp_param_list(num_args: i32) -> String {
    if num_args <= 0 {
        return String::new();
    }
    std::iter::repeat_n("_: SEXP", num_args as usize)
        .collect::<Vec<_>>()
        .join(", ")
}

/// Comma-joined `SEXP` type list for an `extern fn(...)` *type* expression
/// (e.g. inside `transmute::<...>`). Function pointer types don't carry
/// parameter names, so `_:` would be invalid here.
fn sexp_type_list(num_args: i32) -> String {
    if num_args <= 0 {
        return String::new();
    }
    std::iter::repeat_n("SEXP", num_args as usize)
        .collect::<Vec<_>>()
        .join(", ")
}

/// FNV-1a 64-bit hash. Matches the implementation in
/// `miniextendr-macros/src/miniextendr_impl_trait.rs::type_to_symbol_name`
/// so a future build.rs check can recompute it portably.
fn fnv1a_64(data: &[u8]) -> u64 {
    const OFFSET_BASIS: u64 = 0xcbf29ce484222325;
    const PRIME: u64 = 0x00000100000001b3;
    let mut h = OFFSET_BASIS;
    for &b in data {
        h ^= b as u64;
        h = h.wrapping_mul(PRIME);
    }
    h
}

/// Read the live linkme distributed slices and return rows safe to pass to
/// [`format_wasm_registry`].
fn read_runtime_slices() -> (Vec<CallDefRow>, Vec<AltrepRegRow>, Vec<TraitDispatchRow>) {
    let call_defs: Vec<CallDefRow> = MX_CALL_DEFS
        .iter()
        .map(|d| {
            // SAFETY: every emission site sets `name` from a static CStr literal
            // (see `c_wrapper_builder.rs` and friends), so the pointer is valid
            // for the program lifetime and points to a NUL-terminated UTF-8
            // ASCII string.
            let name = unsafe { CStr::from_ptr(d.name) }
                .to_str()
                .expect("MX_CALL_DEFS.name is not valid UTF-8")
                .to_string();
            CallDefRow {
                name,
                num_args: d.numArgs,
            }
        })
        .collect();

    let altrep_regs: Vec<AltrepRegRow> = MX_ALTREP_REGISTRATIONS
        .iter()
        .map(|r: &AltrepRegistration| AltrepRegRow {
            symbol: r.symbol.to_string(),
        })
        .collect();

    let trait_dispatches: Vec<TraitDispatchRow> = MX_TRAIT_DISPATCH
        .iter()
        .map(|t: &TraitDispatchEntry| TraitDispatchRow {
            concrete_tag: t.concrete_tag,
            trait_tag: t.trait_tag,
            vtable_symbol: t.vtable_symbol.to_string(),
        })
        .collect();

    (call_defs, altrep_regs, trait_dispatches)
}

/// Read the live distributed slices, format `wasm_registry.rs`, and write it
/// to `path`. No-op when content is unchanged (matches `write_r_wrappers_to_file`).
pub fn write_wasm_registry_to_file(path: &str) {
    let (call_defs, altrep_regs, trait_dispatches) = read_runtime_slices();
    let content = format_wasm_registry(
        &call_defs,
        &altrep_regs,
        &trait_dispatches,
        crate::registry::conversion_error_class(),
    );

    let existing = std::fs::read_to_string(path).unwrap_or_default();
    if existing == content {
        return;
    }

    // Write via a sibling temp file then rename for atomicity.
    //
    // Matches the strategy in `write_r_wrappers_to_file`: `rename(2)` is atomic
    // on POSIX, so concurrent readers always see a complete file. On Windows,
    // `rename` fails when the destination exists, so we remove it first.
    let dest = std::path::Path::new(path);
    let tmp = dest.with_extension("tmp");
    std::fs::write(&tmp, content.as_bytes())
        .unwrap_or_else(|e| panic!("failed to write {}: {e}", tmp.display()));
    #[cfg(windows)]
    let _ = std::fs::remove_file(dest);
    std::fs::rename(&tmp, dest).unwrap_or_else(|e| {
        panic!(
            "failed to rename {} → {}: {e}",
            tmp.display(),
            dest.display()
        )
    });
}

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

    const CLASSES: &[&str] = &["pkg_error_argument", "pkg_error"];

    fn sample_inputs() -> (Vec<CallDefRow>, Vec<AltrepRegRow>, Vec<TraitDispatchRow>) {
        let call_defs = vec![
            CallDefRow {
                name: "miniextendr_my_fn".into(),
                num_args: 0,
            },
            CallDefRow {
                name: "miniextendr_other".into(),
                num_args: 3,
            },
        ];
        let altrep_regs = vec![AltrepRegRow {
            symbol: "__mx_altrep_reg_MyType".into(),
        }];
        let trait_dispatches = vec![TraitDispatchRow {
            concrete_tag: mx_tag::new(0xdead_beef_dead_beef, 0x1234_5678_1234_5678),
            trait_tag: mx_tag::new(0xcafe_babe_cafe_babe, 0xfeed_face_feed_face),
            vtable_symbol: "__VTABLE_mypkg_Counter_FOR_MyType".into(),
        }];
        (call_defs, altrep_regs, trait_dispatches)
    }

    #[test]
    fn case_distinct_vtables_keep_separate_externs_and_dispatch_rows() {
        let upper = TraitDispatchRow {
            concrete_tag: mx_tag::new(1, 2),
            trait_tag: mx_tag::new(3, 4),
            vtable_symbol: "__VTABLE_mypkg_Counter_FOR_Foo".into(),
        };
        let lower = TraitDispatchRow {
            concrete_tag: upper.concrete_tag,
            trait_tag: mx_tag::new(5, 6),
            vtable_symbol: "__VTABLE_mypkg_counter_FOR_Foo".into(),
        };
        let out = format_wasm_registry(&[], &[], &[upper, lower], &[]);
        for symbol in [
            "__VTABLE_mypkg_Counter_FOR_Foo",
            "__VTABLE_mypkg_counter_FOR_Foo",
        ] {
            assert!(out.contains(&format!(
                "#[allow(non_upper_case_globals)]\n    pub static {symbol}: u8;"
            )));
            assert!(out.contains(&format!("from_ref(&{symbol})")));
        }
    }

    #[test]
    fn header_carries_generator_version_and_content_hash() {
        let (a, b, c) = sample_inputs();
        let out = format_wasm_registry(&a, &b, &c, CLASSES);
        assert!(
            out.contains(&format!("generator-version: {GENERATOR_VERSION}")),
            "expected generator-version line; got:\n{out}"
        );
        assert!(
            out.contains("content-hash:      "),
            "expected content-hash line; got:\n{out}"
        );
    }

    #[test]
    fn content_hash_is_deterministic() {
        let (a, b, c) = sample_inputs();
        let first = format_wasm_registry(&a, &b, &c, CLASSES);
        let second = format_wasm_registry(&a, &b, &c, CLASSES);
        assert_eq!(first, second);
    }

    #[test]
    fn registration_order_does_not_change_snapshot() {
        let (mut calls, mut altreps, mut dispatches) = sample_inputs();
        altreps.push(AltrepRegRow {
            symbol: "__mx_altrep_reg_AnotherType".into(),
        });
        dispatches.push(TraitDispatchRow {
            concrete_tag: mx_tag::new(1, 2),
            trait_tag: mx_tag::new(3, 4),
            vtable_symbol: "__VTABLE_ANOTHER".into(),
        });
        let expected = format_wasm_registry(&calls, &altreps, &dispatches, CLASSES);
        calls.reverse();
        altreps.reverse();
        dispatches.reverse();
        assert_eq!(
            expected,
            format_wasm_registry(&calls, &altreps, &dispatches, CLASSES)
        );
    }

    #[test]
    fn conversion_error_class_precedence_is_preserved() {
        let (calls, altreps, dispatches) = sample_inputs();
        let forward = format_wasm_registry(&calls, &altreps, &dispatches, CLASSES);
        let reversed =
            format_wasm_registry(&calls, &altreps, &dispatches, &[CLASSES[1], CLASSES[0]]);
        assert_ne!(forward, reversed);
        assert!(
            forward.find("\"pkg_error_argument\"").unwrap()
                < forward.find("\"pkg_error\"").unwrap()
        );
    }

    #[test]
    fn content_hash_changes_when_body_changes() {
        let (a, b, c) = sample_inputs();
        let (mut a2, _, _) = sample_inputs();
        a2.push(CallDefRow {
            name: "different_fn".into(),
            num_args: 1,
        });
        let first = format_wasm_registry(&a, &b, &c, CLASSES);
        let second = format_wasm_registry(&a2, &b, &c, CLASSES);
        assert_ne!(first, second);
    }

    #[test]
    fn emits_extern_decls_for_every_referenced_symbol() {
        let (a, b, c) = sample_inputs();
        let out = format_wasm_registry(&a, &b, &c, CLASSES);
        // call wrappers in the C-unwind block — params bound to `_` so the
        // declaration parses (extern fn decls require parameter bindings).
        assert!(out.contains("pub fn miniextendr_my_fn() -> SEXP;"));
        assert!(out.contains("pub fn miniextendr_other(_: SEXP, _: SEXP, _: SEXP) -> SEXP;"));
        // ALTREP registrations + vtables in the registration block
        assert!(out.contains("pub safe fn __mx_altrep_reg_MyType();"));
        assert!(out.contains("pub static __VTABLE_mypkg_Counter_FOR_MyType: u8;"));
    }

    #[test]
    fn emits_named_slice_constants() {
        let (a, b, c) = sample_inputs();
        let out = format_wasm_registry(&a, &b, &c, CLASSES);
        assert!(out.contains("pub static MX_CALL_DEFS_WASM: &[R_CallMethodDef]"));
        assert!(out.contains("pub static MX_ALTREP_REGISTRATIONS_WASM: &[AltrepRegistration]"));
        assert!(out.contains("pub static MX_TRAIT_DISPATCH_WASM: &[TraitDispatchEntry]"));
        assert!(out.contains("pub static MX_CONVERSION_ERROR_CLASS_WASM: &[&str]"));
    }

    /// #1768: the crate's `conversion_error_class` crosses to wasm32 in the
    /// snapshot, in order, as Rust string literals.
    #[test]
    fn emits_conversion_error_class_literals() {
        let (a, b, c) = sample_inputs();
        let out = format_wasm_registry(&a, &b, &c, &["pkg_error_argument", r#"odd"\class"#]);
        assert!(
            out.contains(
                "pub static MX_CONVERSION_ERROR_CLASS_WASM: &[&str] = &[\n    \
                 \"pkg_error_argument\",\n    \"odd\\\"\\\\class\",\n];"
            ),
            "expected the escaped class literals in order; got:\n{out}"
        );
    }

    #[test]
    fn conversion_error_class_changes_the_content_hash() {
        let (a, b, c) = sample_inputs();
        assert_ne!(
            format_wasm_registry(&a, &b, &c, CLASSES),
            format_wasm_registry(&a, &b, &c, &[])
        );
    }

    #[test]
    fn renders_mx_tag_with_const_constructor() {
        let (a, b, c) = sample_inputs();
        let out = format_wasm_registry(&a, &b, &c, CLASSES);
        assert!(
            out.contains(
                "::miniextendr_api::abi::mx_tag::new(0xdeadbeefdeadbeef, 0x1234567812345678)"
            ),
            "expected fully-qualified concrete_tag literal; got:\n{out}"
        );
        assert!(
            out.contains(
                "::miniextendr_api::abi::mx_tag::new(0xcafebabecafebabe, 0xfeedfacefeedface)"
            ),
            "expected fully-qualified trait_tag literal; got:\n{out}"
        );
    }

    /// #1307: a minimal package (call defs only — no trait impls, no ALTREP)
    /// produces an empty dispatch table; the generated file must not carry
    /// imports that only dispatch entries would use, or wasm32 `cargo check`
    /// reports `unused_imports` on every build.
    #[test]
    fn dispatch_free_output_has_no_dispatch_only_imports() {
        let (call_defs, _, _) = sample_inputs();
        let out = format_wasm_registry(&call_defs, &[], &[], &[]);
        assert!(
            !out.contains("mx_tag"),
            "dispatch-free output must not mention mx_tag; got:\n{out}"
        );
        assert!(
            !out.contains("c_void"),
            "dispatch-free output must not mention c_void; got:\n{out}"
        );
    }

    /// Every emitted `use` line must be referenced in the body that follows —
    /// the generalized no-unused-imports property for the minimal-package
    /// shape (#1307). Imports are single-segment or `{A, B}` groups; each
    /// imported ident must reappear after the import block.
    #[test]
    fn every_import_is_used_in_dispatch_free_output() {
        let (call_defs, _, _) = sample_inputs();
        let out = format_wasm_registry(&call_defs, &[], &[], &[]);
        let (imports, rest): (Vec<&str>, Vec<&str>) =
            out.lines().partition(|l| l.starts_with("use "));
        assert!(!imports.is_empty(), "output has imports; got:\n{out}");
        let body = rest.join("\n");
        for line in imports {
            let idents = line
                .trim_start_matches("use ")
                .trim_end_matches(';')
                .rsplit("::")
                .next()
                .unwrap()
                .trim_matches(['{', '}'])
                .split(',')
                .map(str::trim);
            for ident in idents {
                assert!(
                    body.contains(ident),
                    "import `{ident}` from `{line}` is unused; got:\n{out}"
                );
            }
        }
    }

    /// With dispatch entries present, the emitted entries must reference
    /// `mx_tag` / `c_void` fully qualified (no header import exists to
    /// resolve bare names — #1307 dropped them).
    #[test]
    fn dispatch_entries_reference_items_fully_qualified() {
        let (a, b, c) = sample_inputs();
        let out = format_wasm_registry(&a, &b, &c, CLASSES);
        assert!(
            !out.contains("use ::miniextendr_api::abi::mx_tag;"),
            "mx_tag header import must not be emitted; got:\n{out}"
        );
        assert!(
            !out.contains("use ::core::ffi::c_void;"),
            "c_void header import must not be emitted; got:\n{out}"
        );
        assert!(
            out.contains("::miniextendr_api::abi::mx_tag::new("),
            "dispatch tags must be fully qualified; got:\n{out}"
        );
        assert!(
            out.contains(".cast::<::core::ffi::c_void>()"),
            "vtable cast must be fully qualified; got:\n{out}"
        );
    }

    #[test]
    fn empty_inputs_produce_empty_slices() {
        let out = format_wasm_registry(&[], &[], &[], &[]);
        assert!(!out.contains("use ::miniextendr_api::SEXP;"));
        assert!(out.contains("pub static MX_CALL_DEFS_WASM: &[R_CallMethodDef] = &[\n];"));
        assert!(
            out.contains("pub static MX_ALTREP_REGISTRATIONS_WASM: &[AltrepRegistration] = &[\n];")
        );
        assert!(out.contains("pub static MX_TRAIT_DISPATCH_WASM: &[TraitDispatchEntry] = &[\n];"));
        assert!(out.contains("pub static MX_CONVERSION_ERROR_CLASS_WASM: &[&str] = &[\n];"));
    }

    #[test]
    fn param_list_uses_underscore_bindings() {
        assert_eq!(sexp_param_list(0), "");
        assert_eq!(sexp_param_list(1), "_: SEXP");
        assert_eq!(sexp_param_list(3), "_: SEXP, _: SEXP, _: SEXP");
    }

    #[test]
    fn type_list_is_bare_types() {
        assert_eq!(sexp_type_list(0), "");
        assert_eq!(sexp_type_list(1), "SEXP");
        assert_eq!(sexp_type_list(3), "SEXP, SEXP, SEXP");
    }

    #[test]
    fn altrep_register_decls_use_safe_unwind_abi() {
        let (a, b, c) = sample_inputs();
        let out = format_wasm_registry(&a, &b, &c, CLASSES);
        assert!(
            out.contains("unsafe extern \"C-unwind\" {\n    pub safe fn __mx_altrep_reg_MyType();"),
            "expected `safe extern C-unwind` to match AltrepRegistration.register; got:\n{out}"
        );
    }
}