alef 0.109.6

//! Emits the swift-bridge mirror enum wrapper and its `From` conversion.
//!
//! All-unit enums use a fieldless mirror. Data-carrying serde enums use an opaque newtype around
//! the source enum so associated payloads survive the Swift bridge, and their string boundary is
//! the complete serde JSON representation rather than a discriminant.

use crate::backends::swift::gen_rust_crate::type_bridge::enum_from_string_fn_name;
use crate::codegen::cfg::is_host_owned_rust_path;
use crate::codegen::conversions::{VariantDeclaration, enum_variant_declaration};
use crate::codegen::generators::type_paths::resolve_type_path;
use crate::core::ir::{EnumDef, EnumVariant};
use std::collections::{HashMap, HashSet};

/// The variants a Swift-facing surface for `en` may advertise.
///
/// The swift-bridge mirror enum below is self-contained -- unlike the `From`-impl match arms in
/// [`emit_enum_wrapper`], its variant list never references the core type's path, so it compiles
/// regardless of cfg. That is exactly why it could (before alef #547) unconditionally advertise a
/// FOREIGN cfg-gated variant this binding's own configured feature set proves unreachable: a
/// Swift caller could construct `.extra` even though the `From`-impl already drops that variant's
/// arm unconditionally, so no conversion could ever produce it.
///
/// This is the SAME authority (`enum_variant_declaration`) napi's `gen_enum` consults for the
/// identical decision. It is `pub(crate)` rather than inlined into [`emit_enum_wrapper`] because
/// TWO surfaces must agree on this exact list, in two different modules: the mirror enum
/// declaration plus its to-string match here (both reference `Self::{variant}` against the mirror
/// type), and the public Swift `enum`'s `case` list emitted by
/// `gen_bindings::enums::emit_enum`. A Swift `case` for a variant the mirror dropped is a case no
/// conversion in either direction can ever produce or accept -- the facade advertises API that
/// does not exist. Both callers ask this one function instead of each re-deriving the rule. ~keep
///
/// `en.rust_path` (not the `type_paths`-remapped source path) is the same fact
/// `codegen::cfg::collect_cfg_gates` reads to decide whether a cfg is safe to forward as a Cargo
/// feature; a variant's cfg is only safe to re-emit verbatim when this enum is owned by the host
/// crate. See `is_host_owned_rust_path`'s doc for why both halves must agree. ~keep
pub(crate) fn declared_variants<'a>(
    en: &'a EnumDef,
    source_crate: &str,
    configured_features: Option<&[String]>,
) -> Vec<&'a EnumVariant> {
    let is_host_enum = is_host_owned_rust_path(source_crate, &en.rust_path);
    let configured_features_set: Option<HashSet<&str>> =
        configured_features.map(|features| features.iter().map(String::as_str).collect());
    en.variants
        .iter()
        .filter(|variant| {
            !matches!(
                enum_variant_declaration(variant, is_host_enum, configured_features_set.as_ref()),
                VariantDeclaration::Drop
            )
        })
        .collect()
}

#[cfg(test)]
pub(crate) fn emit_enum_wrapper(
    en: &EnumDef,
    source_crate: &str,
    type_paths: &HashMap<String, String>,
    configured_features: Option<&[String]>,
) -> String {
    emit_enum_wrapper_with_defaults(en, source_crate, type_paths, configured_features, &HashSet::new())
}

pub(crate) fn emit_enum_wrapper_with_defaults(
    en: &EnumDef,
    source_crate: &str,
    type_paths: &HashMap<String, String>,
    configured_features: Option<&[String]>,
    defaultable_names: &HashSet<&str>,
) -> String {
    let mut out = String::new();
    let source_path = resolve_type_path(&en.name, source_crate, type_paths);
    let is_host_enum = is_host_owned_rust_path(source_crate, &en.rust_path);

    if uses_lossless_payload_carrier(en) {
        return crate::backends::swift::template_env::render(
            "rust_enum_payload_wrapper.rs.jinja",
            crate::alef_context! {
                enum_name => &en.name,
                source_path => &source_path,
                fn_name => enum_from_string_fn_name(&en.name),
            },
        );
    }

    let declared_variants = declared_variants(en, source_crate, configured_features);

    out.push_str(&crate::backends::swift::template_env::render(
        "enum_unit_header.jinja",
        crate::alef_context! {
            name => &en.name,
        },
    ));
    for variant in &declared_variants {
        out.push_str(&crate::backends::swift::template_env::render(
            "enum_unit_variant.jinja",
            crate::alef_context! {
                variant_name => &variant.name,
            },
        ));
    }

    out.push_str("}\n\n");

    out.push_str(&crate::backends::swift::template_env::render(
        "enum_from_impl_header.jinja",
        crate::alef_context! {
            source_path => &source_path,
            name => &en.name,
        },
    ));
    out.push_str("        match val {\n");

    for variant in &en.variants {
        // A variant merged in from a foreign `[[crates.source_crates]]` crate carries that
        // crate's own cfg gate; this swift-bridge crate never declares a Cargo feature for it
        // (see `codegen::cfg::collect_cfg_gates`), so forwarding it verbatim onto the match arm
        // is an `unexpected cfg condition value` error. Drop the arm entirely instead -- named
        // and counted via `tracing::debug!`, not silently -- and fall through to the `_ =>
        // unreachable!()` catch-all below. ~keep
        if variant.cfg.is_some() && !is_host_enum {
            tracing::debug!(
                enum_name = %en.name,
                enum_rust_path = %en.rust_path,
                variant_name = %variant.name,
                cfg = variant.cfg.as_deref().unwrap_or_default(),
                "dropping Swift bridge From-impl arm for a foreign-crate enum variant behind a \
                 #[cfg(...)] this crate cannot declare as a Cargo feature; the variant is \
                 unreachable from this conversion"
            );
            continue;
        }

        let pattern = if variant.fields.is_empty() {
            variant.name.clone()
        } else if variant.is_tuple {
            format!("{}(..)", variant.name)
        } else {
            format!("{} {{ .. }}", variant.name)
        };

        // Mirror the dart enum_conversions emitter: variants gated by upstream `#[cfg(...)]`
        // (e.g. `Heif` under `#[cfg(feature = "heic")]`) must carry that same gate on the
        if let Some(condition) = variant.cfg.as_deref() {
            out.push_str("            #[cfg(");
            out.push_str(condition);
            out.push_str(")]\n");
        }

        out.push_str(&crate::backends::swift::template_env::render(
            "enum_from_variant.jinja",
            crate::alef_context! {
                source_path => &source_path,
                variant_name => &variant.name,
                pattern => pattern,
            },
        ));
    }

    // A foreign cfg-gated variant's arm is dropped unconditionally above, so whether a catch-all
    // is still needed for it depends on whether this binding's own configured feature set proves
    // the variant unreachable -- delegated to
    // `codegen::conversions::enums::enum_conversion_needs_catch_all_for_features`, the same
    // resolver every other Rust-emitting backend's enum conversion uses, so this bespoke Swift
    // generator can't drift from that verdict (alef #547). `!en.excluded_variants.is_empty()`
    // covers the orthogonal gap this match alone can have: a core variant this binding never
    // generates an arm for at all, regardless of cfg. This match is over the real CORE type
    // (`source_path` above) -- swift-bridge only ever generates this one direction for enums, and
    // the bridge wrapper declared just above is never matched over -- so `configured_features`'
    // proof about the dependency is already the complete answer. `true` here. See
    // `ConversionConfig::declaration_drops_unreachable_foreign_variants`'s doc comment. ~keep
    if crate::codegen::conversions::enum_conversion_needs_catch_all_for_features(
        en,
        is_host_enum,
        !en.excluded_variants.is_empty(),
        configured_features,
        true,
    ) {
        out.push_str(&format!(
            "            _ => unreachable!(\"bridge enum variant of {} not exposed in binding\"),\n",
            en.name
        ));
    }

    out.push_str("        }\n");
    out.push_str("    }\n");
    out.push_str("}\n\n");

    // Filtered by `declared_variants`, not `en.variants`: this match arm names `Self::{variant}`
    // against the SAME mirror type declared above, so it must reference exactly the variants that
    // type actually has -- a proven-unreachable foreign variant dropped from the declaration would
    // otherwise still be matched here, an `E0599: no variant found` compile error. ~keep
    let mut variants = String::new();
    for variant in &declared_variants {
        let serde_name = serde_variant_wire_name(variant, en.serde_rename_all.as_deref());
        variants.push_str(&crate::backends::swift::template_env::render(
            "rust_enum_to_string_variant.rs.jinja",
            crate::alef_context! {
                variant_name => &variant.name,
                serde_name => &serde_name,
            },
        ));
    }

    out.push_str(&crate::backends::swift::template_env::render(
        "rust_enum_to_string_impl.rs.jinja",
        crate::alef_context! {
            enum_name => &en.name,
            variants => variants,
        },
    ));

    // ~keep The compatibility initializer generated by swift-bridge historically accepts a
    // fieldless mirror enum. It can preserve the selected variant but never carried associated
    // values, so those values are reconstructed with `Default`. First-class Swift DTOs continue
    // to use the lossless parent JSON bridge instead of this compatibility path.
    let mut from_string_variants = String::new();
    if can_reconstruct_legacy_variant(en, defaultable_names) {
        for variant in &en.variants {
            // This arm names `{{ source_path }}::{{ variant_name }}` directly, with no cfg
            // guard at all until this fix -- a bug independent of host-vs-foreign: a host-owned
            // cfg-gated variant (e.g. `Heif` under `#[cfg(feature = "heic")]`) referenced this
            // way is just as unguarded a reference to a possibly-nonexistent variant as a
            // foreign one is. A foreign cfg additionally cannot be forwarded as a Cargo feature
            // (see the From-impl loop above and `codegen::cfg::collect_cfg_gates`), so that case
            // drops the arm entirely instead of gating it. ~keep
            if variant.cfg.is_some() && !is_host_enum {
                tracing::debug!(
                    enum_name = %en.name,
                    enum_rust_path = %en.rust_path,
                    variant_name = %variant.name,
                    cfg = variant.cfg.as_deref().unwrap_or_default(),
                    "dropping Swift bridge from-string reconstruction arm for a foreign-crate \
                     enum variant behind a #[cfg(...)] this crate cannot declare as a Cargo \
                     feature; the variant is unreachable from this helper"
                );
                continue;
            }

            let serde_name = serde_variant_wire_name(variant, en.serde_rename_all.as_deref());
            if let Some(condition) = variant.cfg.as_deref() {
                from_string_variants.push_str("        #[cfg(");
                from_string_variants.push_str(condition);
                from_string_variants.push_str(")]\n");
            }
            let expression = default_variant_expression(&source_path, variant);
            from_string_variants.push_str(&crate::backends::swift::template_env::render(
                "rust_enum_from_string_variant.rs.jinja",
                crate::alef_context! {
                    serde_name => &serde_name,
                    expression => expression,
                },
            ));
        }

        out.push_str(&crate::backends::swift::template_env::render(
            "rust_enum_from_string_impl.rs.jinja",
            crate::alef_context! {
                fn_name => enum_from_string_fn_name(&en.name),
                enum_name => &en.name,
                source_path => &source_path,
                variants => from_string_variants,
            },
        ));
    }

    out
}

fn default_variant_expression(source_path: &str, variant: &EnumVariant) -> String {
    if variant.fields.is_empty() {
        return format!("{source_path}::{}", variant.name);
    }
    if variant.is_tuple {
        let values = vec!["::std::default::Default::default()"; variant.fields.len()].join(", ");
        return format!("{source_path}::{}({values})", variant.name);
    }
    let fields = variant
        .fields
        .iter()
        .map(|field| {
            format!(
                "{}: ::std::default::Default::default()",
                crate::core::keywords::rust_raw_ident(&field.name)
            )
        })
        .collect::<Vec<_>>()
        .join(", ");
    format!("{source_path}::{} {{ {fields} }}", variant.name)
}

pub(crate) fn can_reconstruct_legacy_variant(en: &EnumDef, defaultable_names: &HashSet<&str>) -> bool {
    if uses_lossless_payload_carrier(en) {
        return true;
    }
    en.variants.iter().all(|variant| {
        variant
            .fields
            .iter()
            .all(|field| type_is_defaultable(&field.ty, defaultable_names))
    })
}

fn uses_lossless_payload_carrier(en: &EnumDef) -> bool {
    en.has_serde && en.variants.iter().any(|variant| !variant.fields.is_empty())
}

fn type_is_defaultable(ty: &crate::core::ir::TypeRef, defaultable_names: &HashSet<&str>) -> bool {
    match ty {
        crate::core::ir::TypeRef::Named(name) => defaultable_names.contains(name.as_str()),
        crate::core::ir::TypeRef::Optional(_)
        | crate::core::ir::TypeRef::Vec(_)
        | crate::core::ir::TypeRef::Map(_, _) => true,
        _ => true,
    }
}

/// Compute the serde-serialized name for a unit enum variant.
///
/// Priority order:
/// 1. Explicit `#[serde(rename = "...")]` on the variant.
/// 2. `rename_all` transformation applied to the Rust identifier.
/// 3. Raw Rust identifier (no transformation).
fn serde_variant_wire_name(variant: &crate::core::ir::EnumVariant, rename_all: Option<&str>) -> String {
    crate::codegen::naming::wire_variant_value(&variant.name, variant.serde_rename.as_deref(), rename_all)
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::core::ir::{EnumDef, EnumVariant};

    fn make_unit_variant(name: &str, cfg: Option<&str>) -> EnumVariant {
        EnumVariant {
            name: name.to_string(),
            cfg: cfg.map(str::to_string),
            ..Default::default()
        }
    }

    fn make_tuple_variant(name: &str) -> EnumVariant {
        EnumVariant {
            name: name.to_string(),
            fields: vec![crate::core::ir::FieldDef {
                name: "0".to_string(),
                ty: crate::core::ir::TypeRef::String,
                ..Default::default()
            }],
            is_tuple: true,
            ..Default::default()
        }
    }

    fn make_struct_variant(name: &str) -> EnumVariant {
        EnumVariant {
            name: name.to_string(),
            fields: vec![crate::core::ir::FieldDef {
                name: "value".to_string(),
                ty: crate::core::ir::TypeRef::String,
                ..Default::default()
            }],
            is_tuple: false,
            ..Default::default()
        }
    }

    /// A fieldless enum is exactly what `__alef_{enum}_from_swift_string` can reconstruct
    /// from a wire string, and every call site that would invoke it only does so once
    /// `unit_enum_names` (all variants fieldless) contains the enum. The helper must still
    /// be emitted for this shape.
    #[test]
    fn fieldless_enum_still_emits_from_string_helper() {
        let en = EnumDef {
            name: "Mode".to_string(),
            variants: vec![make_unit_variant("Fast", None), make_unit_variant("Thorough", None)],
            methods: vec![],
            excluded_variants: vec![],
            ..Default::default()
        };
        let type_paths = std::collections::HashMap::new();
        let out = emit_enum_wrapper(&en, "mylib", &type_paths, None);
        assert!(
            out.contains("fn __alef_mode_from_swift_string"),
            "expected the from-string helper for a fieldless enum, got:\n{out}"
        );
        assert!(
            out.contains("\"Fast\" => Ok(mylib::Mode::Fast),"),
            "expected an `Ok`-wrapped unit-variant arm now that the helper is fallible \
             (unknown wire values used to panic across the FFI boundary), got:\n{out}"
        );
        assert!(
            out.contains("Result<mylib::Mode, String>"),
            "the helper must return a Result so an unrecognised wire string can be reported \
             as a real error instead of unwinding a panic across the FFI boundary, got:\n{out}"
        );
        assert!(
            !out.contains("panic!"),
            "an unrecognised enum wire string must no longer panic across the FFI boundary, got:\n{out}"
        );
        assert!(
            out.contains("pub enum Mode"),
            "an all-unit enum must retain its fieldless swift-bridge mirror:\n{out}"
        );
    }

    #[test]
    fn fielded_serde_enum_preserves_and_round_trips_the_complete_payload() {
        let en = EnumDef {
            name: "AuthHeaderFormat".to_string(),
            has_serde: true,
            variants: vec![make_unit_variant("None", None), make_tuple_variant("ApiKey")],
            methods: vec![],
            excluded_variants: vec![],
            ..Default::default()
        };
        let type_paths = std::collections::HashMap::new();
        let out = emit_enum_wrapper(&en, "mylib", &type_paths, None);
        assert!(
            out.contains("pub struct AuthHeaderFormat(pub mylib::AuthHeaderFormat);"),
            "a data-carrying enum mirror must retain the complete source value:\n{out}"
        );
        assert!(
            out.contains("Self(val)"),
            "the From conversion must store the complete source value:\n{out}"
        );
        assert!(
            out.contains("serde_json::to_string(&self.0)"),
            "the opaque carrier must serialize the complete source enum:\n{out}"
        );
        assert!(
            out.contains("serde_json::from_str::<mylib::AuthHeaderFormat>(value)"),
            "the compatibility helper must deserialize the complete source enum:\n{out}"
        );
        assert!(
            !out.contains("::std::default::Default::default()"),
            "a data-carrying serde enum must never reconstruct a synthetic default payload:\n{out}"
        );
    }

    #[test]
    fn struct_variant_reconstruction_escapes_reserved_field_names() {
        let mut variant = make_struct_variant("OpenDal");
        variant.fields[0].name = "type".to_string();
        let en = EnumDef {
            name: "CacheBackend".to_string(),
            variants: vec![make_unit_variant("Memory", None), variant],
            methods: vec![],
            excluded_variants: vec![],
            ..Default::default()
        };
        let type_paths = std::collections::HashMap::new();
        let out = emit_enum_wrapper(&en, "mylib", &type_paths, None);
        assert!(
            out.contains("CacheBackend::OpenDal { r#type: ::std::default::Default::default() }"),
            "struct payload defaults must use valid Rust identifiers:\n{out}"
        );
    }

    #[test]
    fn non_serde_non_default_payload_type_disables_the_compatibility_helper() {
        let mut variant = make_struct_variant("External");
        variant.fields[0].ty = crate::core::ir::TypeRef::Named("NoDefault".to_string());
        let en = EnumDef {
            name: "Backend".to_string(),
            variants: vec![variant],
            ..Default::default()
        };
        let out = emit_enum_wrapper(&en, "mylib", &HashMap::new(), None);
        assert!(!out.contains("__alef_backend_from_swift_string"), "{out}");
    }

    #[test]
    fn serde_payload_type_does_not_require_default_to_be_lossless() {
        let mut variant = make_struct_variant("External");
        variant.fields[0].ty = crate::core::ir::TypeRef::Named("NoDefault".to_string());
        let en = EnumDef {
            name: "Backend".to_string(),
            has_serde: true,
            variants: vec![variant],
            ..Default::default()
        };
        let out = emit_enum_wrapper(&en, "mylib", &HashMap::new(), None);
        assert!(out.contains("serde_json::from_str::<mylib::Backend>(value)"), "{out}");
        assert!(!out.contains("Default::default"), "{out}");
    }

    /// When a FOREIGN variant in the primary list carries a `#[cfg(...)]` gate not proven
    /// unreachable (`configured_features: None` is "unknown"), the From-impl match must emit a
    /// `_ => unreachable!()` catch-all arm so it remains exhaustive when that feature is inactive
    /// (E0004 guard). See `host_cfg_variant_keeps_its_arm_and_gains_a_cfg_guard_in_from_string_helper`
    /// below for the sibling host-owned case, which needs NO catch-all since its arm carries the
    /// identical `#[cfg(...)]` guard as the variant itself. ~keep
    #[test]
    fn cfg_gated_variant_emits_catch_all_in_from_impl() {
        let en = EnumDef {
            name: "ImageOutputFormat".to_string(),
            rust_path: "dep_crate::ImageOutputFormat".to_string(),
            variants: vec![
                make_unit_variant("Jpeg", None),
                make_unit_variant("Heif", Some(r#"feature = "heic""#)),
            ],
            methods: vec![],
            excluded_variants: vec![],
            ..Default::default()
        };
        let type_paths = std::collections::HashMap::new();
        let out = emit_enum_wrapper(&en, "mylib", &type_paths, None);
        assert!(
            out.contains("_ => unreachable!"),
            "expected catch-all `_ => unreachable!` arm when cfg-gated variant present, got:\n{out}"
        );
        assert!(
            out.contains("ImageOutputFormat"),
            "catch-all message must include the enum name, got:\n{out}"
        );
    }

    /// When no variant is cfg-gated and `excluded_variants` is empty, no catch-all
    /// should be emitted (the match is statically exhaustive without it).
    #[test]
    fn no_cfg_or_excluded_variants_does_not_emit_catch_all() {
        let en = EnumDef {
            name: "SimpleEnum".to_string(),
            variants: vec![make_unit_variant("A", None), make_unit_variant("B", None)],
            methods: vec![],
            excluded_variants: vec![],
            ..Default::default()
        };
        let type_paths = std::collections::HashMap::new();
        let out = emit_enum_wrapper(&en, "mylib", &type_paths, None);
        assert!(
            !out.contains("_ => unreachable!"),
            "unexpected catch-all arm in From impl for fully-covered enum:\n{out}"
        );
    }

    /// `excluded_variants` alone (no inline cfg gates) must still trigger the catch-all.
    #[test]
    fn excluded_variants_alone_emits_catch_all() {
        let en = EnumDef {
            name: "ImageOutputFormat".to_string(),
            variants: vec![make_unit_variant("Jpeg", None)],
            methods: vec![],
            excluded_variants: vec![make_unit_variant("ExcludedVariant", None)],
            ..Default::default()
        };
        let type_paths = std::collections::HashMap::new();
        let out = emit_enum_wrapper(&en, "mylib", &type_paths, None);
        assert!(
            out.contains("_ => unreachable!"),
            "expected catch-all arm when excluded_variants is non-empty, got:\n{out}"
        );
    }

    /// The regression this task fixes: a variant merged in from a foreign
    /// `[[crates.source_crates]]` crate (`rust_path` rooted in a crate other than the host)
    /// carries that crate's own cfg. Forwarding it verbatim onto the From-impl match arm names a
    /// feature this swift-bridge crate never declares -- an `unexpected cfg condition value`
    /// error -- so the arm must be dropped entirely instead of cfg-gated.
    #[test]
    fn foreign_cfg_variant_arm_is_dropped_not_gated_in_from_impl() {
        let en = EnumDef {
            name: "TierStrategy".to_string(),
            rust_path: "dep_crate::TierStrategy".to_string(),
            variants: vec![
                make_unit_variant("Auto", None),
                make_unit_variant("Tier1", Some(r#"feature = "testkit""#)),
            ],
            methods: vec![],
            excluded_variants: vec![],
            ..Default::default()
        };
        let type_paths = std::collections::HashMap::new();
        let out = emit_enum_wrapper(&en, "mylib", &type_paths, None);
        assert!(
            !out.contains("#[cfg(feature = \"testkit\")]"),
            "no invalid #[cfg] naming an undeclared feature may be emitted, got:\n{out}"
        );
        assert!(
            !out.contains("dep_crate::TierStrategy::Tier1 =>"),
            "a foreign-crate cfg-gated variant must not be referenced in the From-impl match, got:\n{out}"
        );
        assert!(
            out.contains("_ => unreachable!"),
            "dropping the arm must still leave the match exhaustive via the catch-all, got:\n{out}"
        );
    }

    /// Same regression, in the `__alef_{enum}_from_swift_string` reconstruction helper: before
    /// this fix that helper never gated a cfg'd variant's arm at all (host or foreign), so a
    /// foreign one is an outright compile error and even a host-owned one was an unguarded
    /// reference. The foreign case drops the arm.
    #[test]
    fn foreign_cfg_variant_arm_is_dropped_from_from_string_helper() {
        let en = EnumDef {
            name: "TierStrategy".to_string(),
            rust_path: "dep_crate::TierStrategy".to_string(),
            variants: vec![
                make_unit_variant("Auto", None),
                make_unit_variant("Tier1", Some(r#"feature = "testkit""#)),
            ],
            methods: vec![],
            excluded_variants: vec![],
            ..Default::default()
        };
        let type_paths = std::collections::HashMap::new();
        let out = emit_enum_wrapper(&en, "mylib", &type_paths, None);
        assert!(
            out.contains("fn __alef_tier_strategy_from_swift_string"),
            "the helper is still emitted for the enum's remaining unit variants, got:\n{out}"
        );
        assert!(
            !out.contains("dep_crate::TierStrategy::Tier1"),
            "a foreign-crate cfg-gated variant must not be referenced in the from-string helper, got:\n{out}"
        );
    }

    /// A host-owned cfg-gated variant (`rust_path` rooted in the host crate) keeps its arm in
    /// both the From-impl match and the from-string helper, but the from-string helper's arm
    /// must now carry the same `#[cfg(...)]` guard the From-impl arm already carried -- omitting
    /// it is an unguarded reference to a variant that may not exist when the feature is off.
    #[test]
    fn host_cfg_variant_keeps_its_arm_and_gains_a_cfg_guard_in_from_string_helper() {
        let en = EnumDef {
            name: "ImageOutputFormat".to_string(),
            rust_path: "mylib::ImageOutputFormat".to_string(),
            variants: vec![
                make_unit_variant("Jpeg", None),
                make_unit_variant("Heif", Some(r#"feature = "heic""#)),
            ],
            methods: vec![],
            excluded_variants: vec![],
            ..Default::default()
        };
        let type_paths = std::collections::HashMap::new();
        let out = emit_enum_wrapper(&en, "mylib", &type_paths, None);
        assert!(
            out.contains("mylib::ImageOutputFormat::Heif => Self::Heif,"),
            "the host-owned variant's From-impl arm must still be emitted, got:\n{out}"
        );
        assert!(
            out.contains("\"Heif\" => Ok(mylib::ImageOutputFormat::Heif),"),
            "the host-owned variant's from-string arm must still be emitted, got:\n{out}"
        );
        assert_eq!(
            out.matches("#[cfg(feature = \"heic\")]").count(),
            2,
            "both the From-impl arm and the from-string arm must carry the #[cfg] guard, got:\n{out}"
        );
        // alef #547: a host-owned cfg-gated variant's own arm carries the identical #[cfg(...)]
        // guard as the variant itself, so the two always compile in or out together and the match
        // stays exhaustive either way -- unlike the foreign case, no catch-all is ever needed
        // here, regardless of `configured_features`.
        assert!(
            !out.contains("_ => unreachable!"),
            "a host-owned cfg-gated variant alone must not trigger a catch-all, got:\n{out}"
        );
    }

    /// The regression this task fixes: the swift-bridge mirror enum's own variant list is a
    /// self-contained declaration -- unlike the From-impl arms above it, it never references
    /// `source_path`, so it compiled fine even while unconditionally listing a FOREIGN cfg-gated
    /// variant this binding's own configured feature set proves unreachable. A Swift caller could
    /// then construct `.extra` even though no From-impl arm (dropped unconditionally regardless
    /// of provenance, see the tests above) could ever produce it.
    #[test]
    fn foreign_variant_proven_unreachable_is_absent_from_mirror_declaration() {
        let en = EnumDef {
            name: "SampleMode".to_string(),
            rust_path: "dep_crate::SampleMode".to_string(),
            variants: vec![
                make_unit_variant("Base", None),
                make_unit_variant("Extra", Some(r#"feature = "testkit""#)),
            ],
            methods: vec![],
            excluded_variants: vec![],
            ..Default::default()
        };
        let type_paths = std::collections::HashMap::new();
        let configured_features: Vec<String> = vec![];
        let out = emit_enum_wrapper(&en, "hostlib", &type_paths, Some(&configured_features));

        assert!(
            out.contains("pub enum SampleMode {\n    Base,\n}\n\n"),
            "the mirror enum must declare only the reachable variant, got:\n{out}"
        );
        assert!(
            !out.contains("Extra,"),
            "a proven-unreachable foreign variant must not be declared on the mirror enum, got:\n{out}"
        );
        assert!(
            !out.contains("Self::Extra"),
            "the to-string match must not reference a variant the mirror enum no longer declares, got:\n{out}"
        );
    }

    /// Same foreign variant, but `configured_features` is `None` -- "unknown", not proven absent,
    /// since Cargo feature unification could still enable it -- so the mirror declaration must
    /// keep advertising it, unchanged from before this fix.
    #[test]
    fn foreign_variant_not_proven_unreachable_stays_on_mirror_declaration() {
        let en = EnumDef {
            name: "SampleMode".to_string(),
            rust_path: "dep_crate::SampleMode".to_string(),
            variants: vec![
                make_unit_variant("Base", None),
                make_unit_variant("Extra", Some(r#"feature = "testkit""#)),
            ],
            methods: vec![],
            excluded_variants: vec![],
            ..Default::default()
        };
        let type_paths = std::collections::HashMap::new();
        let out = emit_enum_wrapper(&en, "hostlib", &type_paths, None);

        assert!(
            out.contains("pub enum SampleMode {\n    Base,\n    Extra,\n}\n\n"),
            "an unproven foreign variant must stay on the mirror declaration, got:\n{out}"
        );
        assert!(
            out.contains("Self::Extra => \"Extra\".to_string(),"),
            "the to-string match must still cover it, got:\n{out}"
        );
    }

    /// A host-owned cfg-gated variant must never be dropped from the mirror declaration --
    /// existing behavior, unchanged by this fix -- regardless of what `configured_features` says.
    #[test]
    fn host_owned_cfg_gated_variant_stays_on_mirror_declaration_regardless_of_configured_features() {
        let en = EnumDef {
            name: "SampleMode".to_string(),
            rust_path: "hostlib::SampleMode".to_string(),
            variants: vec![
                make_unit_variant("Base", None),
                make_unit_variant("Extra", Some(r#"feature = "extra_feature""#)),
            ],
            methods: vec![],
            excluded_variants: vec![],
            ..Default::default()
        };
        let type_paths = std::collections::HashMap::new();
        let configured_features: Vec<String> = vec![];
        let out = emit_enum_wrapper(&en, "hostlib", &type_paths, Some(&configured_features));

        assert!(
            out.contains("pub enum SampleMode {\n    Base,\n    Extra,\n}\n\n"),
            "a host-owned cfg-gated variant must stay declared, got:\n{out}"
        );
    }
}