alef 0.68.0

//! NAPI-RS enum code generation: plain enums and tagged union helpers.

use crate::backends::napi::type_map::NapiMapper;
use crate::core::ir::{EnumDef, EnumVariant, FieldDef, TypeRef};

pub(super) fn tagged_enum_field_is_tuple(field: &FieldDef) -> bool {
    field
        .name
        .strip_prefix('_')
        .is_some_and(|s| s.chars().all(|c| c.is_ascii_digit()))
}

pub(super) fn tagged_enum_field_name(variant: &EnumVariant, field: &FieldDef) -> String {
    if let Some(index) = field
        .name
        .strip_prefix('_')
        .filter(|s| s.chars().all(|c| c.is_ascii_digit()))
    {
        if variant.fields.len() == 1 {
            let source_name = field
                .serde_rename
                .as_deref()
                .or(variant.serde_rename.as_deref())
                .unwrap_or(&variant.name);
            return crate::codegen::naming::to_python_name(source_name);
        }
        return format!("field_{index}");
    }

    field.name.clone()
}

pub(super) fn tagged_enum_field_js_name(variant: &EnumVariant, field: &FieldDef) -> String {
    if let Some(index) = field
        .name
        .strip_prefix('_')
        .filter(|s| s.chars().all(|c| c.is_ascii_digit()))
    {
        if variant.fields.len() == 1 {
            return field
                .serde_rename
                .clone()
                .or_else(|| variant.serde_rename.clone())
                .unwrap_or_else(|| crate::codegen::naming::to_node_name(&variant.name));
        }
        return format!("field{index}");
    }

    crate::codegen::naming::to_node_name(&field.name)
}

pub(super) fn tagged_enum_binding_field_name(enum_def: &EnumDef, variant: &EnumVariant, field: &FieldDef) -> String {
    if enum_def.serde_content.is_some() && variant.fields.len() == 1 && tagged_enum_field_is_tuple(field) {
        return crate::codegen::naming::to_python_name(
            enum_def.serde_content.as_deref().expect("adjacent content is present"),
        );
    }
    tagged_enum_field_name(variant, field)
}

pub(super) fn tagged_enum_binding_field_js_name(enum_def: &EnumDef, variant: &EnumVariant, field: &FieldDef) -> String {
    if enum_def.serde_content.is_some() && variant.fields.len() == 1 && tagged_enum_field_is_tuple(field) {
        return enum_def.serde_content.clone().expect("adjacent content is present");
    }
    tagged_enum_field_js_name(variant, field)
}

/// Collect synthesized variant-data field names emitted on the binding struct for tagged enums
/// where a variant carries a single-tuple Named field. These are the per-variant optional
/// properties (e.g. `excel: Option<JsExcelMetadata>`) added on top of the discriminator and
/// shared variant fields, enabling direct property access in TypeScript.
pub(super) fn variant_data_field_names(enum_def: &EnumDef) -> Vec<String> {
    let mut names = Vec::new();
    for v in &enum_def.variants {
        if v.fields.len() != 1 {
            continue;
        }
        let field = &v.fields[0];
        if !tagged_enum_field_is_tuple(field) {
            continue;
        }
        if matches!(&field.ty, TypeRef::Named(_)) {
            names.push(tagged_enum_binding_field_name(enum_def, v, field));
        }
    }
    names
}

/// The napi `string_enum` case name for an enum's `#[serde(rename_all)]`, if any.
fn napi_string_enum_case(enum_def: &EnumDef) -> Option<&'static str> {
    enum_def.serde_rename_all.as_deref().and_then(|s| match s {
        "snake_case" => Some("snake_case"),
        "camelCase" => Some("camelCase"),
        "kebab-case" => Some("kebab-case"),
        "SCREAMING_SNAKE_CASE" => Some("UPPER_SNAKE"),
        "lowercase" => Some("lowercase"),
        "UPPERCASE" => Some("UPPERCASE"),
        "PascalCase" => Some("PascalCase"),
        _ => None,
    })
}

/// Runtime string values a `#[napi(string_enum)]` accepts, in declaration order.
///
/// `None` when [`gen_enum`] does not emit the enum as a string enum — tagged and untagged data
/// enums become objects and value wrappers instead, and have no set of string literals.
///
/// Mirrors [`gen_enum`]: `#[napi(value = "...")]` from `#[serde(rename)]` wins per variant,
/// otherwise napi applies the enum-wide case to the variant name.
pub(super) fn string_enum_js_values(enum_def: &EnumDef) -> Option<Vec<String>> {
    let has_data_variants = enum_def.variants.iter().any(|v| !v.fields.is_empty());
    // Internal tagging is always an object, even for all-unit variants — mirrors `gen_enum`'s
    // `is_tagged_data_enum` gate. (~keep)
    if enum_def.serde_tag.is_some() {
        return None;
    }
    if enum_def.serde_untagged && has_data_variants {
        return None;
    }
    if has_data_variants || enum_def.variants.is_empty() {
        return None;
    }
    let case = napi_string_enum_case(enum_def);
    Some(
        enum_def
            .variants
            .iter()
            .map(|variant| match variant.serde_rename.as_deref() {
                Some(rename) => rename.to_string(),
                None => apply_napi_case(&variant.name, case),
            })
            .collect(),
    )
}

/// Applies the same case transform `napi-derive-backend` applies to a `#[napi(string_enum)]`
/// variant name, so the value alef believes a variant serializes to never drifts from what
/// napi-rs's own macro actually emits at runtime.
///
/// napi-rs computes this with the `convert_case` crate, not `heck`: the two libraries agree on
/// letter-only identifiers but disagree whenever a variant name has a letter-to-digit boundary
/// (`Bm25` -> heck's `snake_case` gives `"bm25"`, convert_case's gives `"bm_25"`). Using `heck`
/// here silently produced a TypeScript `ts_type` literal the Rust side would then reject at
/// runtime. `convert_case::Casing::to_case` is the exact function napi-derive-backend calls
/// (`napi-derive-backend/src/util.rs::to_case`), including its leading-underscore trim.
///
/// ~keep Verified against the shipped sources, not inferred: `napi-derive`'s `string_enum`
/// branch resolves each variant to `to_case(v.ident.to_string(), case)`
/// (`napi-derive-3.6.3/src/parser/mod.rs`), and `convert_case` 0.11 lists `LowerDigit` among
/// `Boundary::defaults()`, which is what splits `Bm` from `25`. A consumer's checked-in
/// `index.d.ts` may still show the old `heck` spelling — that file is a generated artifact and
/// is stale until the binding is rebuilt, so it is not evidence about current runtime behavior.
/// `napi-derive-backend/src/util.rs::to_case` trims *every* leading underscore with
/// `trim_start_matches('_')`, not just the first — mirror that exactly, since a single
/// `strip_prefix('_')` would diverge on a name like `__Private`.
fn apply_napi_case(name: &str, case: Option<&str>) -> String {
    use convert_case::Casing;
    let Some(case) = case.and_then(napi_convert_case) else {
        return name.to_string();
    };
    name.trim_start_matches('_').to_case(case)
}

fn napi_convert_case(case: &str) -> Option<convert_case::Case<'static>> {
    use convert_case::Case;
    match case {
        "snake_case" => Some(Case::Snake),
        "camelCase" => Some(Case::Camel),
        "kebab-case" => Some(Case::Kebab),
        "UPPER_SNAKE" => Some(Case::UpperSnake),
        "lowercase" => Some(Case::Flat),
        "UPPERCASE" => Some(Case::UpperFlat),
        "PascalCase" => Some(Case::Pascal),
        _ => None,
    }
}

pub(super) fn gen_enum(enum_def: &EnumDef, prefix: &str, has_serde: bool) -> String {
    let has_data_variants = enum_def.variants.iter().any(|v| !v.fields.is_empty());
    // Internal tagging always produces an object on the wire (`{"kind":"A"}` for a unit variant),
    // so it must route to the object emitter even when no variant carries fields. (~keep)
    let is_tagged_data_enum = enum_def.serde_tag.is_some();
    let is_untagged_data_enum = enum_def.serde_untagged && has_data_variants;

    if is_tagged_data_enum {
        return gen_tagged_enum_as_object(enum_def, prefix, has_serde);
    }

    if is_untagged_data_enum {
        return gen_untagged_data_enum_as_value_wrapper(enum_def, prefix);
    }

    let napi_case = napi_string_enum_case(enum_def);

    let js_name = &enum_def.name;
    let string_enum_attr = match napi_case {
        Some(case) => format!("#[napi(string_enum = \"{case}\", js_name = \"{js_name}\")]"),
        None => format!("#[napi(string_enum, js_name = \"{js_name}\")]"),
    };

    let derives = if has_serde {
        "#[derive(Clone, serde::Serialize, serde::Deserialize)]".to_string()
    } else {
        "#[derive(Clone)]".to_string()
    };
    let mut enum_doc = String::new();
    let sanitized_enum_doc = crate::codegen::doc_emission::sanitize_rust_idioms(
        &enum_def.doc,
        crate::codegen::doc_emission::DocTarget::TsDoc,
    );
    crate::codegen::doc_emission::emit_rustdoc(&mut enum_doc, &sanitized_enum_doc, "");
    let mut lines: Vec<String> = Vec::new();
    if !enum_doc.is_empty() {
        lines.push(enum_doc.trim_end_matches('\n').to_string());
    }
    lines.push(string_enum_attr);
    lines.push(derives);
    lines.push(format!("pub enum {prefix}{} {{", enum_def.name));

    for variant in &enum_def.variants {
        let mut variant_doc = String::new();
        let sanitized_variant_doc = crate::codegen::doc_emission::sanitize_rust_idioms(
            &variant.doc,
            crate::codegen::doc_emission::DocTarget::TsDoc,
        );
        let escaped_variant_doc = sanitized_variant_doc.replace("*/", "* /");
        crate::codegen::doc_emission::emit_rustdoc(&mut variant_doc, &escaped_variant_doc, "    ");
        if !variant_doc.is_empty() {
            lines.push(variant_doc.trim_end_matches('\n').to_string());
        }
        if let Some(rename) = variant.serde_rename.as_deref() {
            lines.push(format!("    #[napi(value = \"{rename}\")]"));
        }
        lines.push(format!("    {},", variant.name));
    }

    lines.push("}".to_string());

    if let Some(first) = enum_def.variants.first() {
        lines.push(String::new());
        lines.push("#[allow(clippy::derivable_impls)]".to_string());
        lines.push(format!("impl Default for {prefix}{} {{", enum_def.name));
        lines.push(format!("    fn default() -> Self {{ Self::{} }}", first.name));
        lines.push("}".to_string());
    }

    lines.join("\n")
}

/// Generate an untagged data enum as a thin wrapper around `serde_json::Value`.
///
/// `#[serde(untagged)]` enums (e.g. `enum Input { Single(String), Multiple(Vec<String>) }`)
/// can't be expressed as a `#[napi(string_enum)]` because that loses the inner data.
/// JS users want to pass either shape directly (`"hi"` or `["a", "b"]`), so we wrap the
/// value through `serde_json::Value` (napi-rs's `serde-json` feature provides FromNapiValue/
/// ToNapiValue for it) and bridge to/from the core enum via serde.
pub(super) fn gen_untagged_data_enum_as_value_wrapper(enum_def: &EnumDef, prefix: &str) -> String {
    let name = format!("{prefix}{}", enum_def.name);
    format!(
        "#[derive(Clone, Default, serde::Serialize, serde::Deserialize)]\n\
         #[serde(transparent)]\n\
         pub struct {name}(pub serde_json::Value);\n\
         \n\
         impl napi::bindgen_prelude::TypeName for {name} {{\n    \
             fn type_name() -> &'static str {{ \"{name}\" }}\n    \
             fn value_type() -> napi::ValueType {{ napi::ValueType::Unknown }}\n\
         }}\n\
         \n\
         impl napi::bindgen_prelude::FromNapiValue for {name} {{\n    \
             unsafe fn from_napi_value(env: napi::sys::napi_env, val: napi::sys::napi_value) -> napi::Result<Self> {{\n        \
                 let v: serde_json::Value = unsafe {{ napi::bindgen_prelude::FromNapiValue::from_napi_value(env, val)? }};\n        \
                 Ok(Self(v))\n    \
             }}\n\
         }}\n\
         \n\
         impl napi::bindgen_prelude::ToNapiValue for {name} {{\n    \
             unsafe fn to_napi_value(env: napi::sys::napi_env, val: Self) -> napi::Result<napi::sys::napi_value> {{\n        \
                 unsafe {{ napi::bindgen_prelude::ToNapiValue::to_napi_value(env, val.0) }}\n    \
             }}\n\
         }}\n\
         \n\
         impl napi::bindgen_prelude::ValidateNapiValue for {name} {{}}\n"
    )
}

/// Generate a tagged enum as a flattened `#[napi(object)]` struct.
/// E.g. `AuthConfig { Basic { username, password }, Bearer { token } }` becomes:
/// ```rust,ignore
/// #[napi(object)]
/// struct JsAuthConfig {
///     #[napi(js_name = "kind")]
///     pub kind_tag: String,
///     pub username: Option<String>,
///     pub password: Option<String>,
///     pub token: Option<String>,
/// }
/// ```
///
/// The discriminant field is always named "kind" in TypeScript (via js_name),
/// regardless of the Rust serde tag attribute, for consistency across bindings.
///
/// For tagged enums where every non-empty variant is a single-tuple field with a Named type
/// (e.g. `FormatMetadata`), a `#[napi]` impl block is additionally emitted with per-variant
/// getter methods, enabling `result.metadata.format.excel.sheetCount`-style access.
pub(super) fn gen_tagged_enum_as_object(enum_def: &EnumDef, prefix: &str, has_serde: bool) -> String {
    use crate::codegen::type_mapper::TypeMapper;
    let mapper = NapiMapper::new(prefix.to_string());

    let tag_field = enum_def.serde_tag.as_deref().unwrap_or("type");
    let ts_discriminant = tag_field;

    let derive = if has_serde {
        "#[derive(Clone, serde::Serialize, serde::Deserialize)]"
    } else {
        "#[derive(Clone)]"
    };
    let js_name = &enum_def.name;
    let mut lines: Vec<String> = Vec::new();
    let mut enum_doc = String::new();
    let sanitized_enum_doc = crate::codegen::doc_emission::sanitize_rust_idioms(
        &enum_def.doc,
        crate::codegen::doc_emission::DocTarget::TsDoc,
    );
    crate::codegen::doc_emission::emit_rustdoc(&mut enum_doc, &sanitized_enum_doc, "");
    if !enum_doc.is_empty() {
        lines.push(enum_doc.trim_end_matches('\n').to_string());
    }
    lines.push(derive.to_string());
    lines.push(format!("#[napi(object, js_name = \"{js_name}\")]"));
    lines.push(format!("pub struct {prefix}{} {{", enum_def.name));
    lines.push(format!("    #[napi(js_name = \"{ts_discriminant}\")]"));
    // serde will serialize using the Rust field name unless #[serde(rename)] is set.
    if has_serde {
        lines.push(format!("    #[serde(rename = \"{ts_discriminant}\")]"));
    }
    lines.push(format!("    pub {tag_field}_tag: String,"));

    let mixed_named_fields = tagged_enum_mixed_named_fields(enum_def);

    let mut seen_fields: std::collections::BTreeSet<String> = std::collections::BTreeSet::new();
    for variant in &enum_def.variants {
        for field in &variant.fields {
            if tagged_enum_field_is_tuple(field) && matches!(&field.ty, TypeRef::Named(_)) {
                continue;
            }
            let field_name = tagged_enum_binding_field_name(enum_def, variant, field);
            if seen_fields.insert(field_name.clone()) {
                let field_type = if (field.sanitized || mixed_named_fields.contains(&field_name))
                    && matches!(&field.ty, TypeRef::Named(_))
                {
                    "String".to_string()
                } else {
                    mapper.map_type(&field.ty).to_string()
                };
                let js_name = tagged_enum_binding_field_js_name(enum_def, variant, field);
                if js_name != field_name {
                    lines.push(format!("    #[napi(js_name = \"{js_name}\")]"));
                    // When js_name differs from field_name, add #[serde(rename)] for serialization
                    if has_serde {
                        lines.push(format!("    #[serde(rename = \"{js_name}\")]"));
                    }
                }
                lines.push(format!("    pub {field_name}: Option<{field_type}>,"));
            }
        }
    }

    enum_def.variants.iter().for_each(|v| {
        if v.fields.len() != 1 {
            return;
        }
        let field = &v.fields[0];
        if !tagged_enum_field_is_tuple(field) {
            return;
        }
        if let TypeRef::Named(inner_type_name) = &field.ty {
            let field_name = tagged_enum_binding_field_name(enum_def, v, field);
            let binding_type = format!("{prefix}{inner_type_name}");
            let js_name = tagged_enum_binding_field_js_name(enum_def, v, field);
            if js_name != field_name {
                lines.push(format!("    #[napi(js_name = \"{js_name}\")]"));
                // When js_name differs from field_name, add #[serde(rename)] for serialization
                if has_serde {
                    lines.push(format!("    #[serde(rename = \"{js_name}\")]"));
                }
            }
            lines.push(format!("    pub {field_name}: Option<{binding_type}>,"));
        }
    });

    lines.push("}".to_string());

    let synth_fields = variant_data_field_names(enum_def);
    let default_inits: Vec<String> = seen_fields
        .iter()
        .cloned()
        .chain(synth_fields.iter().cloned())
        .map(|f| format!("{f}: None"))
        .collect();
    lines.push(String::new());
    lines.push("#[allow(clippy::derivable_impls)]".to_string());
    lines.push(format!("impl Default for {prefix}{} {{", enum_def.name));
    lines.push(format!(
        "    fn default() -> Self {{ Self {{ {tag_field}_tag: String::new(), {} }} }}",
        default_inits.join(", ")
    ));
    lines.push("}".to_string());

    // #[napi] impl block with per-variant getters so callers can do `.excel.sheetCount` etc.
    let _tuple_named_variants: Vec<(&crate::core::ir::EnumVariant, &str)> = enum_def
        .variants
        .iter()
        .filter_map(|v| {
            if v.fields.len() != 1 {
                return None;
            }
            let field = &v.fields[0];
            let is_tuple = field
                .name
                .strip_prefix('_')
                .is_some_and(|s| s.chars().all(|c| c.is_ascii_digit()));
            if !is_tuple {
                return None;
            }
            if let TypeRef::Named(inner_type_name) = &field.ty {
                Some((v, inner_type_name.as_str()))
            } else {
                None
            }
        })
        .collect();

    if enum_def.serde_content.is_some() {
        // Total distinct fields on the binding struct: the tag plus every shared/synthesized
        // data field. A variant constructor only needs `..Default::default()` when it leaves at
        // least one of those fields unspecified — otherwise clippy::needless_update fires because
        // every field was already given a value.
        let total_field_count = 1 + seen_fields.len() + synth_fields.iter().collect::<ahash::AHashSet<_>>().len();
        let variants: Vec<minijinja::Value> = enum_def
            .variants
            .iter()
            .map(|variant| {
                let wire_value = crate::codegen::naming::wire_variant_value(
                    &variant.name,
                    variant.serde_rename.as_deref(),
                    enum_def.serde_rename_all.as_deref(),
                );
                let payload_type = variant
                    .fields
                    .first()
                    .map(|field| mapper.map_type(&field.ty).to_string());
                let has_payload = payload_type.is_some();
                let rust_name = crate::codegen::naming::internal_rust_identifier(&format!(
                    "{}_{}",
                    crate::codegen::naming::pascal_to_snake(&enum_def.name),
                    crate::codegen::naming::to_python_name(&wire_value),
                ));
                let fields_set = if has_payload { 2 } else { 1 };
                minijinja::context! {
                    variant_name => variant.name.clone(),
                    rust_name,
                    wire_value,
                    payload_type,
                    has_payload,
                    needs_default_spread => fields_set < total_field_count,
                }
            })
            .collect();
        lines.push(String::new());
        lines.push(
            crate::backends::napi::template_env::render(
                "adjacent_enum_namespace.rs.jinja",
                minijinja::context! {
                    enum_name => enum_def.name.clone(),
                    binding_name => format!("{prefix}{}", enum_def.name),
                    tag_field => format!("{tag_field}_tag"),
                    content_field => crate::codegen::naming::to_python_name(
                        enum_def.serde_content.as_deref().expect("adjacent content is present"),
                    ),
                    variants,
                },
            )
            .trim_end()
            .to_string(),
        );
    }

    lines.join("\n")
}

/// Generate a free function binding.
pub(super) fn tagged_enum_mixed_named_fields(enum_def: &EnumDef) -> ahash::AHashSet<String> {
    use crate::core::ir::TypeRef;
    let mut field_types: std::collections::HashMap<&str, ahash::AHashSet<&str>> = std::collections::HashMap::new();

    for variant in &enum_def.variants {
        for field in &variant.fields {
            if field.sanitized {
                continue;
            }
            if let TypeRef::Named(n) = &field.ty {
                field_types.entry(&field.name).or_default().insert(n.as_str());
            }
        }
    }

    field_types
        .into_iter()
        .filter(|(_, types)| types.len() > 1)
        .map(|(name, _)| name.to_string())
        .collect()
}

/// Determine which Named fields in a tagged enum use binding structs (Into conversion)
/// vs serde JSON String flattening. A field uses a binding struct only if:
/// 1. The field name maps to a single Named type across all variants
/// 2. That Named type has a binding struct (in struct_names)
/// 3. The field is not sanitized
pub(super) fn tagged_enum_binding_struct_fields<'a>(
    enum_def: &'a EnumDef,
    struct_names: &ahash::AHashSet<String>,
) -> ahash::AHashSet<&'a str> {
    use crate::core::ir::TypeRef;
    let mut field_types: std::collections::HashMap<&str, Vec<&str>> = std::collections::HashMap::new();
    let mut sanitized_fields: ahash::AHashSet<&str> = ahash::AHashSet::new();

    for variant in &enum_def.variants {
        for field in &variant.fields {
            if field.sanitized {
                sanitized_fields.insert(&field.name);
            }
            if let TypeRef::Named(n) = &field.ty {
                field_types.entry(&field.name).or_default().push(n);
            }
        }
    }

    let mut result = ahash::AHashSet::new();
    for (field_name, types) in &field_types {
        if sanitized_fields.contains(field_name) {
            continue;
        }
        if types.iter().all(|t| *t == types[0]) && struct_names.contains(types[0]) {
            result.insert(*field_name);
        }
    }
    result
}

#[cfg(test)]
#[allow(clippy::print_stderr)] // test-only debug output ~keep
mod tests {
    use super::{apply_napi_case, gen_enum, string_enum_js_values};
    use crate::core::ir::{EnumDef, EnumVariant, FieldDef, TypeRef};

    fn make_simple_enum(name: &str, variants: &[&str]) -> EnumDef {
        EnumDef {
            name: name.to_string(),
            rust_path: format!("test::{name}"),
            original_rust_path: String::new(),
            variants: variants
                .iter()
                .map(|v| EnumVariant {
                    name: v.to_string(),
                    fields: vec![],
                    doc: String::new(),
                    is_default: false,
                    serde_rename: None,
                    binding_excluded: false,
                    binding_exclusion_reason: None,
                    is_tuple: false,
                    originally_had_data_fields: false,
                    cfg: None,
                    version: Default::default(),
                })
                .collect(),
            methods: vec![],
            doc: String::new(),
            cfg: None,
            is_copy: true,
            has_serde: false,
            serde_content: None,
            serde_tag: None,
            serde_untagged: false,
            serde_rename_all: None,
            binding_excluded: false,
            binding_exclusion_reason: None,
            excluded_variants: vec![],
            version: Default::default(),
            has_default: false,
        }
    }

    /// gen_enum with no variants produces a valid enum declaration.
    #[test]
    fn gen_enum_empty_variants_compiles() {
        let e = make_simple_enum("Status", &[]);
        let result = gen_enum(&e, "", false);
        assert!(result.contains("enum Status") || result.is_empty() || result.contains("Status"));
    }

    /// gen_enum with variants includes variant names.
    #[test]
    fn gen_enum_includes_variant_names() {
        let e = make_simple_enum("Color", &["Red", "Green", "Blue"]);
        let result = gen_enum(&e, "", false);
        assert!(result.contains("Red") || result.contains("red") || result.contains("RED"));
    }

    /// Regression test D4A: tagged enum with unit variant emits { kind: 'bold' }
    /// and not { annotation_type: 'bold' }.
    #[test]
    fn gen_tagged_enum_unit_variant_uses_kind_discriminant() {
        use crate::core::ir::{FieldDef, TypeRef};

        let e = EnumDef {
            name: "AnnotationKind".to_string(),
            rust_path: "test::AnnotationKind".to_string(),
            original_rust_path: String::new(),
            variants: vec![
                EnumVariant {
                    name: "Bold".to_string(),
                    fields: vec![],
                    doc: String::new(),
                    is_default: false,
                    serde_rename: Some("bold".to_string()),
                    binding_excluded: false,
                    binding_exclusion_reason: None,
                    is_tuple: false,
                    originally_had_data_fields: false,
                    cfg: None,
                    version: Default::default(),
                },
                EnumVariant {
                    name: "FontSize".to_string(),
                    fields: vec![FieldDef {
                        version: Default::default(),
                        name: "_0".to_string(),
                        ty: TypeRef::String,
                        optional: false,
                        default: None,
                        doc: String::new(),
                        sanitized: false,
                        is_boxed: false,
                        type_rust_path: None,
                        cfg: None,
                        typed_default: None,
                        core_wrapper: crate::core::ir::CoreWrapper::None,
                        vec_inner_core_wrapper: crate::core::ir::CoreWrapper::None,
                        newtype_wrapper: None,
                        serde_rename: None,
                        serde_flatten: false,
                        serde_with: None,
                        serde_skip_serializing_if: false,
                        binding_excluded: false,
                        binding_exclusion_reason: None,
                        original_type: None,
                    }],
                    is_tuple: true,
                    doc: String::new(),
                    is_default: false,
                    serde_rename: Some("fontSize".to_string()),
                    binding_excluded: false,
                    binding_exclusion_reason: None,
                    originally_had_data_fields: false,
                    cfg: None,
                    version: Default::default(),
                },
            ],
            methods: vec![],
            doc: String::new(),
            cfg: None,
            is_copy: false,
            has_serde: true,
            has_default: false,
            serde_content: None,
            serde_tag: Some("annotation_type".to_string()),
            serde_untagged: false,
            serde_rename_all: None,
            binding_excluded: false,
            binding_exclusion_reason: None,
            excluded_variants: vec![],
            version: Default::default(),
        };

        let result = gen_enum(&e, "Js", true);

        assert!(
            result.contains("js_name = \"annotation_type\""),
            "tagged enum must use js_name matching serde tag (annotation_type);\nactual:\n{result}"
        );
    }

    /// Regression test D4B: tagged enum with tuple variant (payload) emits camelCase
    /// value name in serde_rename, e.g., 'fontSize' not 'font_size'.
    #[test]
    fn gen_tagged_enum_tuple_variant_uses_camel_case_value() {
        use crate::core::ir::{FieldDef, TypeRef};

        let e = EnumDef {
            name: "AnnotationKind".to_string(),
            rust_path: "test::AnnotationKind".to_string(),
            original_rust_path: String::new(),
            variants: vec![EnumVariant {
                name: "FontSize".to_string(),
                fields: vec![FieldDef {
                    version: Default::default(),
                    name: "_0".to_string(),
                    ty: TypeRef::String,
                    optional: false,
                    default: None,
                    doc: String::new(),
                    sanitized: false,
                    is_boxed: false,
                    type_rust_path: None,
                    cfg: None,
                    typed_default: None,
                    core_wrapper: crate::core::ir::CoreWrapper::None,
                    vec_inner_core_wrapper: crate::core::ir::CoreWrapper::None,
                    newtype_wrapper: None,
                    serde_rename: Some("fontSize".to_string()),
                    serde_flatten: false,
                    serde_with: None,
                    serde_skip_serializing_if: false,
                    binding_excluded: false,
                    binding_exclusion_reason: None,
                    original_type: None,
                }],
                is_tuple: true,
                doc: String::new(),
                is_default: false,
                serde_rename: Some("fontSize".to_string()),
                binding_excluded: false,
                binding_exclusion_reason: None,
                originally_had_data_fields: false,
                cfg: None,
                version: Default::default(),
            }],
            methods: vec![],
            doc: String::new(),
            cfg: None,
            is_copy: false,
            has_serde: true,
            has_default: false,
            serde_content: None,
            serde_tag: Some("annotation_type".to_string()),
            serde_untagged: false,
            serde_rename_all: None,
            binding_excluded: false,
            binding_exclusion_reason: None,
            excluded_variants: vec![],
            version: Default::default(),
        };

        let result = gen_enum(&e, "Js", true);

        assert!(
            result.contains("js_name = \"fontSize\"") && result.contains("pub font_size: Option<String>"),
            "tagged enum with tuple variant must expose camelCase js_name and keep Rust snake_case;\nactual:\n{result}"
        );
    }

    /// Regression test D4C: struct variant with named field emits field name unchanged.
    /// E.g., Custom { reason: String } → { kind: 'custom'; reason: string }
    #[test]
    fn gen_tagged_enum_struct_variant_emits_field_names() {
        use crate::core::ir::{FieldDef, TypeRef};

        let e = EnumDef {
            name: "AnnotationKind".to_string(),
            rust_path: "test::AnnotationKind".to_string(),
            original_rust_path: String::new(),
            variants: vec![EnumVariant {
                name: "Custom".to_string(),
                fields: vec![FieldDef {
                    version: Default::default(),
                    name: "reason".to_string(),
                    ty: TypeRef::String,
                    optional: false,
                    default: None,
                    doc: String::new(),
                    sanitized: false,
                    is_boxed: false,
                    type_rust_path: None,
                    cfg: None,
                    typed_default: None,
                    core_wrapper: crate::core::ir::CoreWrapper::None,
                    vec_inner_core_wrapper: crate::core::ir::CoreWrapper::None,
                    newtype_wrapper: None,
                    serde_rename: None,
                    serde_flatten: false,
                    serde_with: None,
                    serde_skip_serializing_if: false,
                    binding_excluded: false,
                    binding_exclusion_reason: None,
                    original_type: None,
                }],
                doc: String::new(),
                is_default: false,
                serde_rename: Some("custom".to_string()),
                binding_excluded: false,
                binding_exclusion_reason: None,
                is_tuple: false,
                originally_had_data_fields: false,
                cfg: None,
                version: Default::default(),
            }],
            methods: vec![],
            doc: String::new(),
            cfg: None,
            is_copy: false,
            has_serde: true,
            has_default: false,
            serde_content: None,
            serde_tag: Some("annotation_type".to_string()),
            serde_untagged: false,
            serde_rename_all: None,
            binding_excluded: false,
            binding_exclusion_reason: None,
            excluded_variants: vec![],
            version: Default::default(),
        };

        let result = gen_enum(&e, "Js", true);

        assert!(
            result.contains("reason"),
            "struct variant must emit field names (reason);\nactual:\n{result}"
        );
        assert!(
            result.contains("js_name = \"annotation_type\""),
            "struct variant enum must use js_name matching serde tag;\nactual:\n{result}"
        );
    }

    /// Regression test for JSDoc block-close escaping in enum variant docs.
    /// When a variant doc contains `/* ... */` inside backticks (e.g., a code example),
    /// the `*/` must be escaped to `* /` so it doesn't prematurely close the JSDoc block
    /// in the generated TypeScript .d.ts file.
    #[test]
    fn gen_enum_escapes_jsdoc_block_close_in_variant_docs() {
        let e = EnumDef {
            name: "CommentType".to_string(),
            rust_path: "test::CommentType".to_string(),
            original_rust_path: String::new(),
            variants: vec![
                EnumVariant {
                    name: "Block".to_string(),
                    fields: vec![],
                    doc: "A block or multi-line comment (e.g., `/* ... */`).".to_string(),
                    is_default: false,
                    serde_rename: Some("block".to_string()),
                    binding_excluded: false,
                    binding_exclusion_reason: None,
                    is_tuple: false,
                    originally_had_data_fields: false,
                    cfg: None,
                    version: Default::default(),
                },
                EnumVariant {
                    name: "Doc".to_string(),
                    fields: vec![],
                    doc: "A documentation comment (e.g., `/// ...` or `/** ... */`).".to_string(),
                    is_default: false,
                    serde_rename: Some("doc".to_string()),
                    binding_excluded: false,
                    binding_exclusion_reason: None,
                    is_tuple: false,
                    originally_had_data_fields: false,
                    cfg: None,
                    version: Default::default(),
                },
            ],
            methods: vec![],
            doc: String::new(),
            cfg: None,
            is_copy: true,
            has_serde: true,
            has_default: false,
            serde_content: None,
            serde_tag: None,
            serde_untagged: false,
            serde_rename_all: None,
            binding_excluded: false,
            binding_exclusion_reason: None,
            excluded_variants: vec![],
            version: Default::default(),
        };

        let result = gen_enum(&e, "", false);
        eprintln!("Generated code:\n{}\n", result);

        assert!(
            result.contains("* /"),
            "enum variant doc must escape */ sequences:\nactual:\n{result}"
        );
        let unescaped_count = result.matches("*/").count();
        let escaped_count = result.matches("* /").count();
        eprintln!("Unescaped */ count: {}", unescaped_count);
        eprintln!("Escaped * / count: {}", escaped_count);
        assert!(
            escaped_count > 0 && unescaped_count == 0,
            "enum variant doc should contain escaped * / but no bare */:\nactual:\n{result}"
        );
    }

    #[test]
    fn adjacent_tagged_enum_uses_shared_content_field() {
        let enum_def = EnumDef {
            name: "Action".to_string(),
            variants: vec![
                EnumVariant {
                    name: "Continue".to_string(),
                    ..Default::default()
                },
                EnumVariant {
                    name: "Custom".to_string(),
                    fields: vec![FieldDef {
                        name: "_0".to_string(),
                        ty: TypeRef::String,
                        ..Default::default()
                    }],
                    ..Default::default()
                },
            ],
            serde_tag: Some("type".to_string()),
            serde_content: Some("output".to_string()),
            serde_rename_all: Some("snake_case".to_string()),
            ..Default::default()
        };

        let output = gen_enum(&enum_def, "Js", true);
        assert!(output.contains("pub type_tag: String"));
        assert!(output.contains("pub output: Option<String>"));
        assert!(!output.contains("pub custom: Option<String>"));
        assert!(output.contains("#[napi(namespace = \"Action\", js_name = \"Continue\")]"));
        assert!(!output.contains("getter"));
        assert!(output.contains("#[napi(namespace = \"Action\", js_name = \"Custom\")]"));
        assert!(output.contains("pub fn action_custom(output: String) -> JsAction"));
        assert!(output.contains("output: Some(output)"));
    }

    /// Regression test for a clippy::needless_update failure: when an adjacently-tagged enum's
    /// binding struct has exactly the tag field plus the shared content field, a variant that
    /// sets both (a payload variant) must NOT emit `..Default::default()` — every field is
    /// already specified, so the spread has no effect and clippy denies it. A variant that
    /// leaves the content field unset (a unit variant) must still emit the spread, since it is
    /// the only way to fill that field in.
    #[test]
    fn adjacent_tagged_enum_omits_spread_only_when_all_fields_are_set() {
        let enum_def = EnumDef {
            name: "VisitResult".to_string(),
            variants: vec![
                EnumVariant {
                    name: "Skip".to_string(),
                    ..Default::default()
                },
                EnumVariant {
                    name: "Custom".to_string(),
                    fields: vec![FieldDef {
                        name: "_0".to_string(),
                        ty: TypeRef::String,
                        ..Default::default()
                    }],
                    ..Default::default()
                },
            ],
            serde_tag: Some("type".to_string()),
            serde_content: Some("output".to_string()),
            serde_rename_all: Some("snake_case".to_string()),
            ..Default::default()
        };

        let output = gen_enum(&enum_def, "Js", true);

        let skip_fn = output
            .split("pub fn visit_result_skip() -> JsVisitResult")
            .nth(1)
            .expect("Skip constructor must be generated")
            .split("\n}\n")
            .next()
            .expect("Skip constructor body must be terminated");
        assert!(
            skip_fn.contains("..Default::default()"),
            "Skip only sets type_tag, leaving output unset; the spread is required to fill it in:\n{skip_fn}"
        );

        let custom_fn = output
            .split("pub fn visit_result_custom(output: String) -> JsVisitResult")
            .nth(1)
            .expect("Custom constructor must be generated")
            .split("\n}\n")
            .next()
            .expect("Custom constructor body must be terminated");
        assert!(
            !custom_fn.contains("..Default::default()"),
            "Custom sets both type_tag and output, i.e. every field on JsVisitResult; a spread here is a needless_update clippy denial:\n{custom_fn}"
        );
    }

    /// `apply_napi_case` must derive its output from `convert_case` — the exact crate and
    /// algorithm `napi-derive-backend` uses to compute a `#[napi(string_enum)]` variant's
    /// runtime wire string — rather than reimplementing the transform with a different case
    /// library. Comparing against `convert_case::Casing::to_case` directly (the canonical
    /// oracle, not a hard-coded literal) is what would have caught alef using `heck` instead:
    /// `heck` and `convert_case` agree on letter-only identifiers but diverge on any name with
    /// a letter-to-digit boundary, e.g. `Bm25`.
    #[test]
    fn apply_napi_case_matches_convert_case_for_every_supported_case() {
        use convert_case::{Case, Casing};

        let cases: &[(&str, Case)] = &[
            ("snake_case", Case::Snake),
            ("camelCase", Case::Camel),
            ("kebab-case", Case::Kebab),
            ("UPPER_SNAKE", Case::UpperSnake),
            ("lowercase", Case::Flat),
            ("UPPERCASE", Case::UpperFlat),
            ("PascalCase", Case::Pascal),
        ];
        let names = [
            "Bm25",
            "Utf8",
            "Sha256",
            "Md5",
            "Bfs",
            "BestFirst",
            "HttpV2Client",
            "_Reserved",
            "__Private",
        ];

        for (napi_case, canonical_case) in cases {
            for name in names {
                let actual = apply_napi_case(name, Some(napi_case));
                let expected = name.trim_start_matches('_').to_case(*canonical_case);
                assert_eq!(
                    actual, expected,
                    "apply_napi_case({name:?}, {napi_case:?}) = {actual:?}, but convert_case \
                     (napi-rs's own algorithm) gives {expected:?}"
                );
            }
        }
    }

    /// Regression test: a single-variant `#[napi(string_enum = "snake_case")]` enum whose lone
    /// variant name has a letter-to-digit boundary (mirrors crawlberg's
    /// `JsContentFilterKind::Bm25`) must report the wire value napi-rs's own macro actually
    /// emits at runtime (`"bm_25"`), not the value `heck::ToSnakeCase` would compute
    /// (`"bm25"`). Before this fix, `string_enum_js_values` fed `"bm25"` into the generated
    /// `ts_type` union literal, so TypeScript accepted a string the Rust `FromNapiValue`
    /// conversion rejected at runtime.
    #[test]
    fn string_enum_js_values_matches_napi_runtime_wire_value_for_digit_boundary_variant() {
        let enum_def = EnumDef {
            name: "ContentFilterKind".to_string(),
            rust_path: "test::ContentFilterKind".to_string(),
            variants: vec![EnumVariant {
                name: "Bm25".to_string(),
                ..Default::default()
            }],
            serde_rename_all: Some("snake_case".to_string()),
            ..Default::default()
        };

        let values = string_enum_js_values(&enum_def).expect("plain string enum must yield wire values");

        assert_eq!(
            values,
            vec!["bm_25".to_string()],
            "napi-rs's convert_case-based macro emits \"bm_25\" for variant Bm25 under snake_case; \
             alef must report the same value or the generated ts_type literal accepts a string Rust rejects"
        );
    }
}