mig-bo4e 0.7.0

//! PID validation errors — typed, LLM-consumable error reports.

use std::borrow::Cow;
use std::collections::{BTreeMap, BTreeSet};
use std::fmt;

use serde_json::Value;

use crate::pid_requirements::{
    CodeValue, EntityRequirement, EntityScope, EntityVariantRequirement, FieldRequirement,
    PidRequirements,
};

/// Severity of a validation error.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Severity {
    /// Field is unconditionally required (Muss/X) or condition evaluated to True.
    Error,
    /// Condition evaluated to Unknown (depends on external context).
    Warning,
}

/// A single PID validation error.
#[derive(Debug, Clone)]
pub enum PidValidationError {
    /// An entire entity is missing from the interchange.
    MissingEntity {
        entity: String,
        ahb_status: String,
        severity: Severity,
    },
    /// A required field is None/missing.
    MissingField {
        entity: String,
        field: String,
        ahb_status: String,
        rust_type: Option<String>,
        valid_values: Vec<(String, String)>,
        severity: Severity,
    },
    /// A code field has a value not in the allowed set.
    InvalidCode {
        entity: String,
        field: String,
        value: String,
        valid_values: Vec<(String, String)>,
    },
}

impl PidValidationError {
    pub fn severity(&self) -> &Severity {
        match self {
            Self::MissingEntity { severity, .. } => severity,
            Self::MissingField { severity, .. } => severity,
            Self::InvalidCode { .. } => &Severity::Error,
        }
    }

    pub fn is_error(&self) -> bool {
        matches!(self.severity(), Severity::Error)
    }
}

impl fmt::Display for PidValidationError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            PidValidationError::MissingEntity {
                entity,
                ahb_status,
                severity,
            } => {
                let label = severity_label(severity);
                write!(
                    f,
                    "{label}: missing entity '{entity}' (required: {ahb_status})"
                )
            }
            PidValidationError::MissingField {
                entity,
                field,
                ahb_status,
                rust_type,
                valid_values,
                severity,
            } => {
                let label = severity_label(severity);
                write!(
                    f,
                    "{label}: missing {entity}.{field} (required: {ahb_status})"
                )?;
                if let Some(rt) = rust_type {
                    write!(f, "\n  → type: {rt}")?;
                }
                if !valid_values.is_empty() {
                    let codes: Vec<String> = valid_values
                        .iter()
                        .map(|(code, meaning)| {
                            if meaning.is_empty() {
                                code.clone()
                            } else {
                                format!("{code} ({meaning})")
                            }
                        })
                        .collect();
                    write!(f, "\n  → valid: {}", codes.join(", "))?;
                }
                Ok(())
            }
            PidValidationError::InvalidCode {
                entity,
                field,
                value,
                valid_values,
            } => {
                write!(f, "INVALID: {entity}.{field} = \"{value}\"")?;
                if !valid_values.is_empty() {
                    let codes: Vec<String> = valid_values.iter().map(|(c, _)| c.clone()).collect();
                    write!(f, "\n  → valid: {}", codes.join(", "))?;
                }
                Ok(())
            }
        }
    }
}

fn severity_label(severity: &Severity) -> &'static str {
    match severity {
        Severity::Error => "ERROR",
        Severity::Warning => "WARNING",
    }
}

/// A collection of validation errors for a PID.
pub struct ValidationReport(pub Vec<PidValidationError>);

impl ValidationReport {
    /// Returns true if the report contains any errors (not just warnings).
    pub fn has_errors(&self) -> bool {
        self.0.iter().any(|e| e.is_error())
    }

    /// Returns only the errors (not warnings).
    pub fn errors(&self) -> Vec<&PidValidationError> {
        self.0.iter().filter(|e| e.is_error()).collect()
    }

    /// Returns true if the report is empty (no errors or warnings).
    pub fn is_empty(&self) -> bool {
        self.0.is_empty()
    }

    /// Returns the number of validation errors.
    pub fn len(&self) -> usize {
        self.0.len()
    }
}

impl fmt::Display for ValidationReport {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        for (i, err) in self.0.iter().enumerate() {
            if i > 0 {
                writeln!(f)?;
            }
            write!(f, "{err}")?;
        }
        Ok(())
    }
}

// ── Validation Logic ──────────────────────────────────────────────────────

/// Validate a BO4E JSON value against PID requirements.
///
/// Validates ALL entities (both message-level and transaction-level).
/// Use [`validate_pid_json_transaction`] to validate only transaction-level entities.
///
/// Walks the requirements and checks:
/// 1. Required entities are present in the JSON
/// 2. Required fields are present within each entity
/// 3. Code fields have values in the allowed set
pub fn validate_pid_json(json: &Value, requirements: &PidRequirements) -> Vec<PidValidationError> {
    validate_entities(json, &requirements.entities, None)
}

/// Validate only transaction-level entities in a BO4E JSON value.
///
/// Skips message-level entities (e.g., Marktteilnehmer, Kontakt from SG2/SG3)
/// that are outside the transaction scope. Use this when validating a transaction
/// payload that doesn't include message-level data.
pub fn validate_pid_json_transaction(
    json: &Value,
    requirements: &PidRequirements,
) -> Vec<PidValidationError> {
    validate_entities(json, &requirements.entities, Some(EntityScope::Transaction))
}

/// Internal: validate entities, optionally filtering by scope.
fn validate_entities(
    json: &Value,
    entities: &[EntityRequirement],
    scope_filter: Option<EntityScope>,
) -> Vec<PidValidationError> {
    let mut errors = Vec::new();

    for entity_req in entities {
        // Skip entities not matching the requested scope
        if let Some(ref scope) = scope_filter {
            if &entity_req.scope != scope {
                continue;
            }
        }

        let key = to_camel_case(&entity_req.entity);

        match json.get(&key) {
            None | Some(serde_json::Value::Null) => {
                if is_unconditionally_required(&entity_req.ahb_status) {
                    errors.push(PidValidationError::MissingEntity {
                        entity: entity_req.entity.clone(),
                        ahb_status: entity_req.ahb_status.clone(),
                        severity: Severity::Error,
                    });
                }
            }
            Some(val) => {
                if entity_req.cardinality().is_list() {
                    if let Some(arr) = val.as_array() {
                        for element in arr {
                            validate_entity_fields(element, entity_req, &mut errors);
                        }
                    } else {
                        // Caller supplied a single object where the requirement
                        // expects an array (e.g. typed structs that emit one
                        // rep as an object instead of [obj]). Validate it as a
                        // single rep rather than silently skipping field checks.
                        validate_entity_fields(val, entity_req, &mut errors);
                    }
                } else {
                    validate_entity_fields(val, entity_req, &mut errors);
                }
            }
        }
    }

    errors
}

/// Traverse a dot-separated path in a JSON value, trying both the original
/// key and its camelCase variant at each level.
pub fn get_nested<'a>(json: &'a Value, path: &str) -> Option<&'a Value> {
    let mut current = json;
    for part in path.split('.') {
        current = current.get(part).or_else(|| {
            if part.contains('_') {
                current.get(snake_to_camel_case(part))
            } else {
                None
            }
        })?;
    }
    Some(current)
}

/// Validate fields within a single entity JSON object.
fn validate_entity_fields(
    entity_json: &Value,
    entity_req: &EntityRequirement,
    errors: &mut Vec<PidValidationError>,
) {
    let fields = effective_field_requirements(entity_req, entity_json);
    for field_req in fields.iter() {
        // Traverse dot-separated paths (e.g. "produktIdentifikation.funktion")
        // and try camelCase variants at each level for typed struct compatibility.
        let val = get_nested(entity_json, &field_req.bo4e_name);

        // Treat null values as missing — JSON null means "not provided"
        let val = val.filter(|v| !v.is_null());

        match val {
            None => {
                if is_unconditionally_required(&field_req.ahb_status) {
                    errors.push(PidValidationError::MissingField {
                        entity: entity_req.entity.clone(),
                        field: field_req.bo4e_name.clone(),
                        ahb_status: field_req.ahb_status.clone(),
                        rust_type: field_req.enum_name.clone(),
                        valid_values: code_values_to_tuples(&field_req.valid_codes),
                        severity: Severity::Error,
                    });
                }
            }
            Some(val) => {
                validate_code_value(val, entity_req, field_req, errors);
            }
        }
    }
}

/// Validate that a code field's value is in the allowed set.
fn validate_code_value(
    val: &Value,
    entity_req: &EntityRequirement,
    field_req: &FieldRequirement,
    errors: &mut Vec<PidValidationError>,
) {
    if let Some(value) = invalid_code_value(val, field_req) {
        errors.push(PidValidationError::InvalidCode {
            entity: entity_req.entity.clone(),
            field: field_req.bo4e_name.clone(),
            value,
            valid_values: code_values_to_tuples(&field_req.valid_codes),
        });
    }
}

/// The code carried by a BO4E code field: a plain string, or the `code` member of
/// a `{code, meaning, enum}` object as written by `from_edifact`.
pub fn code_field_value(val: &Value) -> Option<&str> {
    val.as_str()
        .or_else(|| val.get("code").and_then(|c| c.as_str()))
}

/// Check a code field's value against `field_req.valid_codes`.
///
/// Returns the offending value if it is invalid, `None` if it is valid or not a
/// code value at all. A value is valid when it equals a valid raw EDIFACT code
/// or the BO4E value the mapping's `enum_map` translates a valid code to — the
/// two spellings `to_edifact` accepts.
pub fn invalid_code_value(val: &Value, field_req: &FieldRequirement) -> Option<String> {
    if field_req.valid_codes.is_empty() {
        return None;
    }
    let value = code_field_value(val)?;
    let is_valid = field_req
        .valid_codes
        .iter()
        .any(|cv| cv.code == value || cv.bo4e_value.as_deref() == Some(value));
    (!is_valid).then(|| value.to_string())
}

/// The field requirements that apply to one element of an entity.
///
/// For an entity without [`EntityRequirement::variants`] this is simply its
/// `fields`. For a multi-variant entity (e.g. `Geschaeftspartner` fed by
/// `sg12_z03`/`sg12_z07`/…), the element's discriminator value (raw code or
/// `enum_map`ped BO4E value, string or code object) selects the matching
/// variant, and the variant-owned fields are replaced by that variant's
/// requirements — fields the variant's group lacks do not apply.
///
/// If the discriminator is missing or matches no variant, all variants are
/// candidates and are combined leniently: codes are unioned, and a field keeps
/// its AHB status only if every candidate agrees on it (otherwise it is treated
/// as optional), so an unidentifiable element is never held to the required
/// fields of a variant it may not be.
pub fn effective_field_requirements<'a>(
    entity_req: &'a EntityRequirement,
    element: &Value,
) -> Cow<'a, [FieldRequirement]> {
    if entity_req.variants.is_empty() {
        return Cow::Borrowed(&entity_req.fields);
    }

    // Candidate variants, per discriminator field.
    let mut by_field: BTreeMap<&str, Vec<&EntityVariantRequirement>> = BTreeMap::new();
    for v in &entity_req.variants {
        by_field
            .entry(v.discriminator_field.as_str())
            .or_default()
            .push(v);
    }
    let mut candidates: Vec<&EntityVariantRequirement> = Vec::new();
    for (field, group) in by_field {
        let value = get_nested(element, field).and_then(code_field_value);
        let matched: Vec<&EntityVariantRequirement> = group
            .iter()
            .copied()
            .filter(|v| value.is_some_and(|s| v.code == s || v.bo4e_value.as_deref() == Some(s)))
            .collect();
        candidates.extend(if matched.is_empty() { group } else { matched });
    }

    // Fields governed by variants (in first-seen order).
    let mut owned: Vec<&str> = Vec::new();
    let mut owned_set: BTreeSet<&str> = BTreeSet::new();
    for v in &entity_req.variants {
        for f in &v.fields {
            if owned_set.insert(f.bo4e_name.as_str()) {
                owned.push(f.bo4e_name.as_str());
            }
        }
    }

    let mut combined: BTreeMap<&str, FieldRequirement> = BTreeMap::new();
    for name in owned {
        let reqs: Vec<&FieldRequirement> = candidates
            .iter()
            .filter_map(|v| v.fields.iter().find(|f| f.bo4e_name == name))
            .collect();
        let Some((first, rest)) = reqs.split_first() else {
            continue; // not applicable to any candidate variant
        };
        let mut field = (*first).clone();
        let mut statuses_agree = reqs.len() == candidates.len();
        for r in rest {
            if r.ahb_status != field.ahb_status {
                statuses_agree = false;
            }
            for cv in &r.valid_codes {
                if !field.valid_codes.iter().any(|c| c.code == cv.code) {
                    field.valid_codes.push(cv.clone());
                }
            }
        }
        if !statuses_agree {
            field.ahb_status = String::new();
        }
        combined.insert(name, field);
    }

    let mut result: Vec<FieldRequirement> = Vec::with_capacity(entity_req.fields.len());
    for f in &entity_req.fields {
        if owned_set.contains(f.bo4e_name.as_str()) {
            if let Some(c) = combined.remove(f.bo4e_name.as_str()) {
                result.push(c);
            }
        } else {
            result.push(f.clone());
        }
    }
    result.extend(combined.into_values());
    Cow::Owned(result)
}

/// Convert CodeValue vec to (code, meaning) tuples.
fn code_values_to_tuples(codes: &[CodeValue]) -> Vec<(String, String)> {
    codes
        .iter()
        .map(|cv| (cv.code.clone(), cv.meaning.clone()))
        .collect()
}

/// Convert PascalCase entity name to camelCase JSON key.
///
/// "Prozessdaten" → "prozessdaten"
/// "RuhendeMarktlokation" → "ruhendeMarktlokation"
/// "Marktlokation" → "marktlokation"
fn to_camel_case(s: &str) -> String {
    if s.is_empty() {
        return String::new();
    }
    let mut chars = s.chars();
    let first = chars.next().unwrap();
    let mut result = first.to_lowercase().to_string();
    result.extend(chars);
    result
}

/// Convert a snake_case field name to camelCase.
///
/// This mirrors what `#[serde(rename_all = "camelCase")]` does at runtime, allowing
/// the validator to find fields in JSON that was produced by typed structs even when
/// the requirement stores the field name as snake_case (as it comes from TOML).
///
/// Examples:
/// - `"code_codepflege"` → `"codeCodepflege"`
/// - `"vorgang_id"` → `"vorgangId"`
/// - `"marktlokation"` → `"marktlokation"` (unchanged — no underscores)
fn snake_to_camel_case(s: &str) -> String {
    let mut result = String::with_capacity(s.len());
    let mut capitalize_next = false;
    for ch in s.chars() {
        if ch == '_' {
            capitalize_next = true;
        } else if capitalize_next {
            result.extend(ch.to_uppercase());
            capitalize_next = false;
        } else {
            result.push(ch);
        }
    }
    result
}

/// Returns true if the AHB status indicates an unconditionally required field.
fn is_unconditionally_required(ahb_status: &str) -> bool {
    matches!(ahb_status, "X" | "Muss" | "Soll")
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::pid_requirements::{
        Bo4eRefType, Cardinality, CodeValue, EntityRequirement, FieldRequirement, PidRequirements,
    };
    use serde_json::json;

    fn sample_requirements() -> PidRequirements {
        PidRequirements {
            pid: "55001".to_string(),
            beschreibung: "Anmeldung verb. MaLo".to_string(),
            entities: vec![
                EntityRequirement {
                    entity: "Prozessdaten".to_string(),
                    ref_type: Bo4eRefType::Object {
                        type_name: "Prozessdaten".to_string(),

                        cardinality: Cardinality::REQUIRED,
                    },

                    ahb_status: "Muss".to_string(),
                    map_key: None,
                    scope: EntityScope::Transaction,
                    variants: vec![],
                    fields: vec![
                        FieldRequirement {
                            bo4e_name: "vorgangId".to_string(),
                            ahb_status: "X".to_string(),
                            field_type: "data".to_string(),
                            format: None,
                            enum_name: None,
                            valid_codes: vec![],
                            child_group: None,
                            ref_type: Bo4eRefType::Unknown,
                        },
                        FieldRequirement {
                            bo4e_name: "transaktionsgrund".to_string(),
                            ahb_status: "X".to_string(),
                            field_type: "code".to_string(),
                            format: None,
                            enum_name: Some("Transaktionsgrund".to_string()),
                            valid_codes: vec![
                                CodeValue {
                                    code: "E01".to_string(),
                                    meaning: "Ein-/Auszug (Einzug)".to_string(),
                                    enum_name: None,
                                    bo4e_value: None,
                                },
                                CodeValue {
                                    code: "E03".to_string(),
                                    meaning: "Wechsel".to_string(),
                                    enum_name: None,
                                    bo4e_value: None,
                                },
                            ],
                            child_group: None,
                            ref_type: Bo4eRefType::Unknown,
                        },
                    ],
                },
                EntityRequirement {
                    entity: "Marktlokation".to_string(),
                    ref_type: Bo4eRefType::Object {
                        type_name: "Marktlokation".to_string(),

                        cardinality: Cardinality::REQUIRED,
                    },

                    ahb_status: "Muss".to_string(),
                    map_key: None,
                    scope: EntityScope::Transaction,
                    variants: vec![],
                    fields: vec![
                        FieldRequirement {
                            bo4e_name: "marktlokationsId".to_string(),
                            ahb_status: "X".to_string(),
                            field_type: "data".to_string(),
                            format: None,
                            enum_name: None,
                            valid_codes: vec![],
                            child_group: None,
                            ref_type: Bo4eRefType::Unknown,
                        },
                        FieldRequirement {
                            bo4e_name: "haushaltskunde".to_string(),
                            ahb_status: "X".to_string(),
                            field_type: "code".to_string(),
                            format: None,
                            enum_name: Some("Haushaltskunde".to_string()),
                            valid_codes: vec![
                                CodeValue {
                                    code: "Z15".to_string(),
                                    meaning: "Ja".to_string(),
                                    enum_name: None,
                                    bo4e_value: None,
                                },
                                CodeValue {
                                    code: "Z18".to_string(),
                                    meaning: "Nein".to_string(),
                                    enum_name: None,
                                    bo4e_value: None,
                                },
                            ],
                            child_group: None,
                            ref_type: Bo4eRefType::Unknown,
                        },
                    ],
                },
                EntityRequirement {
                    entity: "Geschaeftspartner".to_string(),
                    ref_type: Bo4eRefType::Object {
                        type_name: "Geschaeftspartner".to_string(),

                        cardinality: Cardinality {
                            min: 1,
                            max: Some(7),
                        },
                    },

                    ahb_status: "Muss".to_string(),
                    map_key: None,
                    scope: EntityScope::Transaction,
                    variants: vec![],
                    fields: vec![FieldRequirement {
                        bo4e_name: "identifikation".to_string(),
                        ahb_status: "X".to_string(),
                        field_type: "data".to_string(),
                        format: None,
                        enum_name: None,
                        valid_codes: vec![],
                        child_group: None,
                        ref_type: Bo4eRefType::Unknown,
                    }],
                },
            ],
        }
    }

    #[test]
    fn test_validate_complete_json() {
        let reqs = sample_requirements();
        let json = json!({
            "prozessdaten": {
                "vorgangId": "ABC123",
                "transaktionsgrund": "E01"
            },
            "marktlokation": {
                "marktlokationsId": "51234567890",
                "haushaltskunde": "Z15"
            },
            "geschaeftspartner": [
                { "identifikation": "9900000000003" }
            ]
        });

        let errors = validate_pid_json(&json, &reqs);
        assert!(errors.is_empty(), "Expected no errors, got: {errors:?}");
    }

    #[test]
    fn test_validate_missing_entity() {
        let reqs = sample_requirements();
        let json = json!({
            "prozessdaten": {
                "vorgangId": "ABC123",
                "transaktionsgrund": "E01"
            },
            "geschaeftspartner": [
                { "identifikation": "9900000000003" }
            ]
        });
        // Marktlokation is missing

        let errors = validate_pid_json(&json, &reqs);
        assert_eq!(errors.len(), 1);
        match &errors[0] {
            PidValidationError::MissingEntity {
                entity,
                ahb_status,
                severity,
            } => {
                assert_eq!(entity, "Marktlokation");
                assert_eq!(ahb_status, "Muss");
                assert_eq!(severity, &Severity::Error);
            }
            other => panic!("Expected MissingEntity, got: {other:?}"),
        }

        // Display check
        let msg = errors[0].to_string();
        assert!(msg.contains("ERROR"));
        assert!(msg.contains("Marktlokation"));
        assert!(msg.contains("Muss"));
    }

    #[test]
    fn test_validate_missing_field() {
        let reqs = sample_requirements();
        let json = json!({
            "prozessdaten": {
                "transaktionsgrund": "E01"
                // vorgangId is missing
            },
            "marktlokation": {
                "marktlokationsId": "51234567890",
                "haushaltskunde": "Z15"
            },
            "geschaeftspartner": [
                { "identifikation": "9900000000003" }
            ]
        });

        let errors = validate_pid_json(&json, &reqs);
        assert_eq!(errors.len(), 1);
        match &errors[0] {
            PidValidationError::MissingField {
                entity,
                field,
                ahb_status,
                severity,
                ..
            } => {
                assert_eq!(entity, "Prozessdaten");
                assert_eq!(field, "vorgangId");
                assert_eq!(ahb_status, "X");
                assert_eq!(severity, &Severity::Error);
            }
            other => panic!("Expected MissingField, got: {other:?}"),
        }

        let msg = errors[0].to_string();
        assert!(msg.contains("ERROR"));
        assert!(msg.contains("Prozessdaten.vorgangId"));
    }

    #[test]
    fn test_validate_invalid_code() {
        let reqs = sample_requirements();
        let json = json!({
            "prozessdaten": {
                "vorgangId": "ABC123",
                "transaktionsgrund": "E01"
            },
            "marktlokation": {
                "marktlokationsId": "51234567890",
                "haushaltskunde": "Z99"  // Invalid code
            },
            "geschaeftspartner": [
                { "identifikation": "9900000000003" }
            ]
        });

        let errors = validate_pid_json(&json, &reqs);
        assert_eq!(errors.len(), 1);
        match &errors[0] {
            PidValidationError::InvalidCode {
                entity,
                field,
                value,
                valid_values,
            } => {
                assert_eq!(entity, "Marktlokation");
                assert_eq!(field, "haushaltskunde");
                assert_eq!(value, "Z99");
                assert_eq!(valid_values.len(), 2);
                assert!(valid_values.iter().any(|(c, _)| c == "Z15"));
                assert!(valid_values.iter().any(|(c, _)| c == "Z18"));
            }
            other => panic!("Expected InvalidCode, got: {other:?}"),
        }

        let msg = errors[0].to_string();
        assert!(msg.contains("INVALID"));
        assert!(msg.contains("Z99"));
        assert!(msg.contains("Z15"));
    }

    #[test]
    fn test_validate_array_entity() {
        let reqs = sample_requirements();
        let json = json!({
            "prozessdaten": {
                "vorgangId": "ABC123",
                "transaktionsgrund": "E01"
            },
            "marktlokation": {
                "marktlokationsId": "51234567890",
                "haushaltskunde": "Z15"
            },
            "geschaeftspartner": [
                { "identifikation": "9900000000003" },
                { }  // Missing identifikation in second element
            ]
        });

        let errors = validate_pid_json(&json, &reqs);
        assert_eq!(errors.len(), 1);
        match &errors[0] {
            PidValidationError::MissingField { entity, field, .. } => {
                assert_eq!(entity, "Geschaeftspartner");
                assert_eq!(field, "identifikation");
            }
            other => panic!("Expected MissingField, got: {other:?}"),
        }
    }

    #[test]
    fn test_to_camel_case() {
        assert_eq!(to_camel_case("Prozessdaten"), "prozessdaten");
        assert_eq!(
            to_camel_case("RuhendeMarktlokation"),
            "ruhendeMarktlokation"
        );
        assert_eq!(to_camel_case("Marktlokation"), "marktlokation");
        assert_eq!(to_camel_case(""), "");
    }

    #[test]
    fn test_snake_to_camel_case() {
        assert_eq!(snake_to_camel_case("code_codepflege"), "codeCodepflege");
        assert_eq!(snake_to_camel_case("vorgang_id"), "vorgangId");
        assert_eq!(snake_to_camel_case("marktlokation"), "marktlokation");
        assert_eq!(snake_to_camel_case(""), "");
        assert_eq!(snake_to_camel_case("a_b_c"), "aBC");
    }

    /// A field stored as snake_case in requirements (e.g. from TOML) must be found
    /// in JSON that was produced by a typed struct using `#[serde(rename_all = "camelCase")]`.
    #[test]
    fn test_camel_case_fallback_for_snake_case_bo4e_name() {
        let reqs = PidRequirements {
            pid: "55077".to_string(),
            beschreibung: "Test camelCase fallback".to_string(),
            entities: vec![EntityRequirement {
                entity: "Zuordnung".to_string(),
                ref_type: Bo4eRefType::Object {
                    type_name: "Zuordnung".to_string(),

                    cardinality: Cardinality::REQUIRED,
                },

                ahb_status: "Muss".to_string(),
                map_key: None,
                scope: EntityScope::Transaction,
                variants: vec![],
                fields: vec![
                    FieldRequirement {
                        // snake_case as stored in TOML requirements
                        bo4e_name: "code_codepflege".to_string(),
                        ahb_status: "X".to_string(),
                        field_type: "data".to_string(),
                        format: None,
                        enum_name: None,
                        valid_codes: vec![],
                        child_group: None,
                        ref_type: Bo4eRefType::Unknown,
                    },
                    FieldRequirement {
                        bo4e_name: "codeliste".to_string(),
                        ahb_status: "X".to_string(),
                        field_type: "data".to_string(),
                        format: None,
                        enum_name: None,
                        valid_codes: vec![],
                        child_group: None,
                        ref_type: Bo4eRefType::Unknown,
                    },
                ],
            }],
        };

        // JSON produced by a typed struct with #[serde(rename_all = "camelCase")]:
        // code_codepflege → codeCodepflege
        let json_camel = json!({
            "zuordnung": {
                "codeCodepflege": "DE_BDEW",
                "codeliste": "6"
            }
        });

        let errors = validate_pid_json(&json_camel, &reqs);
        assert!(
            errors.is_empty(),
            "Expected no errors when field is present under camelCase key, got: {errors:?}"
        );

        // Also verify that snake_case key in JSON still works (backward compat).
        let json_snake = json!({
            "zuordnung": {
                "code_codepflege": "DE_BDEW",
                "codeliste": "6"
            }
        });

        let errors = validate_pid_json(&json_snake, &reqs);
        assert!(
            errors.is_empty(),
            "Expected no errors when field is present under snake_case key, got: {errors:?}"
        );

        // When the field is truly absent, a MissingField error must still be raised.
        let json_missing = json!({
            "zuordnung": {
                "codeliste": "6"
            }
        });

        let errors = validate_pid_json(&json_missing, &reqs);
        assert_eq!(errors.len(), 1);
        match &errors[0] {
            PidValidationError::MissingField { field, .. } => {
                assert_eq!(field, "code_codepflege");
            }
            other => panic!("Expected MissingField, got: {other:?}"),
        }
    }

    #[test]
    fn test_is_unconditionally_required() {
        assert!(is_unconditionally_required("X"));
        assert!(is_unconditionally_required("Muss"));
        assert!(is_unconditionally_required("Soll"));
        assert!(!is_unconditionally_required("Kann"));
        assert!(!is_unconditionally_required("[1]"));
        assert!(!is_unconditionally_required(""));
    }

    #[test]
    fn test_validation_report_display() {
        let errors = vec![
            PidValidationError::MissingEntity {
                entity: "Marktlokation".to_string(),
                ahb_status: "Muss".to_string(),
                severity: Severity::Error,
            },
            PidValidationError::MissingField {
                entity: "Prozessdaten".to_string(),
                field: "vorgangId".to_string(),
                ahb_status: "X".to_string(),
                rust_type: None,
                valid_values: vec![],
                severity: Severity::Error,
            },
        ];
        let report = ValidationReport(errors);
        assert!(report.has_errors());
        assert_eq!(report.len(), 2);
        assert!(!report.is_empty());

        let display = report.to_string();
        assert!(display.contains("missing entity 'Marktlokation'"));
        assert!(display.contains("missing Prozessdaten.vorgangId"));
    }

    #[test]
    fn test_missing_field_with_type_and_values_display() {
        let err = PidValidationError::MissingField {
            entity: "Marktlokation".to_string(),
            field: "haushaltskunde".to_string(),
            ahb_status: "Muss".to_string(),
            rust_type: Some("Haushaltskunde".to_string()),
            valid_values: vec![
                ("Z15".to_string(), "Ja".to_string()),
                ("Z18".to_string(), "Nein".to_string()),
            ],
            severity: Severity::Error,
        };
        let msg = err.to_string();
        assert!(msg.contains("type: Haushaltskunde"));
        assert!(msg.contains("valid: Z15 (Ja), Z18 (Nein)"));
    }

    #[test]
    fn test_optional_fields_not_flagged() {
        let reqs = PidRequirements {
            pid: "99999".to_string(),
            beschreibung: "Test".to_string(),
            entities: vec![EntityRequirement {
                entity: "Test".to_string(),
                ref_type: Bo4eRefType::Object {
                    type_name: "Test".to_string(),

                    cardinality: Cardinality::OPTIONAL,
                },

                ahb_status: "Kann".to_string(),
                map_key: None,
                scope: EntityScope::Transaction,
                variants: vec![],
                fields: vec![FieldRequirement {
                    bo4e_name: "optionalField".to_string(),
                    ahb_status: "Kann".to_string(),
                    field_type: "data".to_string(),
                    format: None,
                    enum_name: None,
                    valid_codes: vec![],
                    child_group: None,
                    ref_type: Bo4eRefType::Unknown,
                }],
            }],
        };

        // Entity missing but optional — no error
        let errors = validate_pid_json(&json!({}), &reqs);
        assert!(errors.is_empty());

        // Entity present, field missing but optional — no error
        let errors = validate_pid_json(&json!({ "test": {} }), &reqs);
        assert!(errors.is_empty());
    }

    /// Regression test for issue #48: nested dot-path fields reported as missing
    /// even when present (e.g. `produktIdentifikation.funktion`).
    #[test]
    fn test_nested_dot_path_fields_not_falsely_missing() {
        let reqs = PidRequirements {
            pid: "55001".to_string(),
            beschreibung: "Test nested paths".to_string(),
            entities: vec![EntityRequirement {
                entity: "ProduktpaketDaten".to_string(),
                ref_type: Bo4eRefType::Object {
                    type_name: "ProduktpaketDaten".to_string(),

                    cardinality: Cardinality {
                        min: 1,
                        max: Some(99999),
                    },
                },

                ahb_status: "Muss".to_string(),
                map_key: None,
                scope: EntityScope::Transaction,
                variants: vec![],
                fields: vec![
                    FieldRequirement {
                        bo4e_name: "produktIdentifikation.funktion".to_string(),
                        ahb_status: "X".to_string(),
                        field_type: "code".to_string(),
                        format: None,
                        enum_name: Some("Produktidentifikation".to_string()),
                        valid_codes: vec![CodeValue {
                            code: "5".to_string(),
                            meaning: "Produktidentifikation".to_string(),
                            enum_name: None,
                            bo4e_value: None,
                        }],
                        child_group: None,
                        ref_type: Bo4eRefType::Unknown,
                    },
                    FieldRequirement {
                        bo4e_name: "produktMerkmal.code".to_string(),
                        ahb_status: "X".to_string(),
                        field_type: "code".to_string(),
                        format: None,
                        enum_name: None,
                        valid_codes: vec![],
                        child_group: None,
                        ref_type: Bo4eRefType::Unknown,
                    },
                ],
            }],
        };

        // Exact JSON from issue #48
        let json = json!({
            "produktpaketDaten": [{
                "produktIdentifikation": { "funktion": "5", "id": "9991000002082", "typ": "Z11" },
                "produktMerkmal": { "code": "ZH9" }
            }]
        });

        let errors = validate_pid_json(&json, &reqs);
        assert!(
            errors.is_empty(),
            "Nested dot-path fields should be found (issue #48), got: {errors:?}"
        );
    }

    #[test]
    fn test_nested_dot_path_truly_missing() {
        let reqs = PidRequirements {
            pid: "55001".to_string(),
            beschreibung: "Test nested paths missing".to_string(),
            entities: vec![EntityRequirement {
                entity: "ProduktpaketDaten".to_string(),
                ref_type: Bo4eRefType::Object {
                    type_name: "ProduktpaketDaten".to_string(),

                    cardinality: Cardinality {
                        min: 1,
                        max: Some(99999),
                    },
                },

                ahb_status: "Muss".to_string(),
                map_key: None,
                scope: EntityScope::Transaction,
                variants: vec![],
                fields: vec![FieldRequirement {
                    bo4e_name: "produktIdentifikation.funktion".to_string(),
                    ahb_status: "X".to_string(),
                    field_type: "data".to_string(),
                    format: None,
                    enum_name: None,
                    valid_codes: vec![],
                    child_group: None,
                    ref_type: Bo4eRefType::Unknown,
                }],
            }],
        };

        // Parent exists but nested field is missing
        let json = json!({
            "produktpaketDaten": [{
                "produktIdentifikation": { "id": "123" }
            }]
        });

        let errors = validate_pid_json(&json, &reqs);
        assert_eq!(errors.len(), 1, "Should report missing nested field");
        match &errors[0] {
            PidValidationError::MissingField { field, .. } => {
                assert_eq!(field, "produktIdentifikation.funktion");
            }
            other => panic!("Expected MissingField, got: {other:?}"),
        }
    }

    fn field(name: &str, status: &str, codes: &[(&str, &str)]) -> FieldRequirement {
        FieldRequirement {
            bo4e_name: name.to_string(),
            ahb_status: status.to_string(),
            field_type: if codes.is_empty() { "data" } else { "code" }.to_string(),
            format: None,
            enum_name: None,
            valid_codes: codes
                .iter()
                .map(|(code, mapped)| CodeValue {
                    code: code.to_string(),
                    meaning: String::new(),
                    enum_name: None,
                    bo4e_value: Some(mapped.to_string()),
                })
                .collect(),
            child_group: None,
            ref_type: Bo4eRefType::Unknown,
        }
    }

    /// Geschaeftspartner fed by two NAD variants: Z03 (address, no name) and
    /// Z07 (name, no address), shaped like PID 55042 (issue #104).
    fn multi_variant_requirements() -> PidRequirements {
        let z03 = ("Z03", "messlokationsadresse");
        let z07 = ("Z07", "kundeMsb");
        PidRequirements {
            pid: "55042".to_string(),
            beschreibung: String::new(),
            entities: vec![EntityRequirement {
                entity: "Geschaeftspartner".to_string(),
                ref_type: Bo4eRefType::Object {
                    type_name: "Geschaeftspartner".to_string(),
                    cardinality: Cardinality {
                        min: 1,
                        max: Some(99),
                    },
                },
                ahb_status: "Muss".to_string(),
                // Entity-level union, as built from the merged schema groups.
                fields: vec![
                    field("adresse.ort", "X", &[]),
                    field("name1", "X", &[]),
                    field("partnerrolle", "X", &[z03, z07]),
                ],
                map_key: None,
                scope: EntityScope::Transaction,
                variants: vec![
                    EntityVariantRequirement {
                        discriminator_field: "partnerrolle".to_string(),
                        code: "Z03".to_string(),
                        bo4e_value: Some("messlokationsadresse".to_string()),
                        source_paths: vec!["sg4.sg12_z03".to_string()],
                        fields: vec![
                            field("adresse.ort", "X", &[]),
                            field("partnerrolle", "X", &[z03]),
                        ],
                    },
                    EntityVariantRequirement {
                        discriminator_field: "partnerrolle".to_string(),
                        code: "Z07".to_string(),
                        bo4e_value: Some("kundeMsb".to_string()),
                        source_paths: vec!["sg4.sg12_z07".to_string()],
                        fields: vec![field("name1", "X", &[]), field("partnerrolle", "X", &[z07])],
                    },
                ],
            }],
        }
    }

    #[test]
    fn multi_variant_entity_uses_the_elements_own_variant() {
        let reqs = multi_variant_requirements();
        // Every spelling of the qualifier: raw code / enum_map name, string / object.
        let json = json!({
            "geschaeftspartner": [
                { "partnerrolle": "Z03", "adresse": { "ort": "Berlin" } },
                { "partnerrolle": "kundeMsb", "name1": "Muster" },
                { "partnerrolle": { "code": "messlokationsadresse", "meaning": "x" },
                  "adresse": { "ort": "Köln" } },
                { "partnerrolle": { "code": "Z07" }, "name1": "Beispiel" },
            ]
        });
        let errors = validate_pid_json(&json, &reqs);
        assert!(errors.is_empty(), "{}", ValidationReport(errors));
    }

    #[test]
    fn multi_variant_entity_reports_variant_required_fields() {
        let reqs = multi_variant_requirements();
        let json = json!({ "geschaeftspartner": [{ "partnerrolle": "kundeMsb" }] });
        let errors = validate_pid_json(&json, &reqs);
        assert_eq!(errors.len(), 1, "{}", ValidationReport(errors));
        assert!(matches!(
            &errors[0],
            PidValidationError::MissingField { field, .. } if field == "name1"
        ));
    }

    #[test]
    fn multi_variant_entity_unknown_qualifier_is_invalid_code_only() {
        let reqs = multi_variant_requirements();
        for bad in [json!("Z99"), json!("bogus"), json!({ "code": "Z99" })] {
            let json = json!({ "geschaeftspartner": [{ "partnerrolle": bad }] });
            let errors = validate_pid_json(&json, &reqs);
            // No variant matches: variant fields become optional, codes are unioned.
            assert_eq!(errors.len(), 1, "{bad}: {}", ValidationReport(errors));
            match &errors[0] {
                PidValidationError::InvalidCode {
                    field,
                    valid_values,
                    ..
                } => {
                    assert_eq!(field, "partnerrolle");
                    let codes: Vec<&str> = valid_values.iter().map(|(c, _)| c.as_str()).collect();
                    assert_eq!(codes, ["Z03", "Z07"]);
                }
                other => panic!("expected InvalidCode, got {other:?}"),
            }
        }
    }

    #[test]
    fn code_objects_and_enum_mapped_names_are_code_checked() {
        let f = field("partnerrolle", "X", &[("Z07", "kundeMsb")]);
        assert_eq!(invalid_code_value(&json!("Z07"), &f), None);
        assert_eq!(invalid_code_value(&json!("kundeMsb"), &f), None);
        assert_eq!(invalid_code_value(&json!({ "code": "kundeMsb" }), &f), None);
        assert_eq!(invalid_code_value(&json!({ "code": "Z07" }), &f), None);
        assert_eq!(
            invalid_code_value(&json!({ "code": "Z99", "meaning": null }), &f),
            Some("Z99".to_string())
        );
        assert_eq!(
            invalid_code_value(&json!("kundeLf"), &f),
            Some("kundeLf".to_string())
        );
        // Non-code values (numbers, objects without code) are not code-checked.
        assert_eq!(invalid_code_value(&json!(7), &f), None);
        assert_eq!(invalid_code_value(&json!({ "meaning": "x" }), &f), None);
    }
}