mig_bo4e/

code_lookup.rs

//! Code enrichment lookup — maps EDIFACT companion field codes to human-readable meanings.
//!
//! Built from PID schema JSON files. Used by the mapping engine to automatically
//! enrich companion field values during forward mapping (EDIFACT → BO4E).

use serde_json::Value;
use std::collections::{BTreeMap, HashMap, HashSet};
use std::path::Path;

/// Lookup key: (source_path, segment_tag, qualifier, element_index, component_index).
///
/// `source_path` matches the TOML `source_path` field (e.g., "sg4.sg8_z01.sg10").
/// `segment_tag` is uppercase (e.g., "CCI", "CAV").
/// `qualifier` is the segment's discriminating qualifier when one applies (RFF/STS/CCI:
/// element 0 component 0; DTM: c507.d2005). `None` for segments without a qualifier
/// convention. The qualifier slot scopes lookups so that, for instance, RFF+TN's
/// type=data d1154 (free-text Vorgangsnummer) is not confused with RFF+Z13's
/// type=code d1154 (PID-identifier) at the same path/elem/comp.
pub type CodeLookupKey = (String, String, Option<String>, usize, usize);

/// Enrichment data for a single EDIFACT code value.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct CodeEnrichment {
    pub meaning: String,
    pub enum_key: Option<String>,
}

/// Maps EDIFACT code values to their enrichment data (meaning + optional enum key).
/// E.g., "Z15" → CodeEnrichment { meaning: "Haushaltskunde gem. EnWG", enum_key: Some("HAUSHALTSKUNDE_ENWG") }.
pub type CodeMeanings = BTreeMap<String, CodeEnrichment>;

/// Complete code lookup table built from a PID schema JSON.
///
/// Entries are scoped by the segment variant's qualifier. Tags with a qualifier
/// convention (RFF/STS/CCI/DTM) are stored *only* under their qualifier. Other
/// tags (NAD, CAV, FTX, …) are stored under `None` (the union of all same-tag
/// segments, for unqualified lookups) and additionally under their own leading
/// code when the schema fixes it to one value (e.g. `CAV+Z91`), so a qualified
/// lookup (`cav[Z91]`) sees only the codes of that segment variant.
#[derive(Debug, Clone, Default)]
pub struct CodeLookup {
    entries: BTreeMap<CodeLookupKey, CodeMeanings>,
    /// `(source_path, segment_tag, qualifier)` of every qualifier-scoped entry.
    /// Derived from `entries` (not serialized). A qualifier listed here names a
    /// known segment variant, whose entries are authoritative: lookups for it
    /// never fall back to the unqualified union.
    variants: HashSet<(String, String, String)>,
}

// Custom serialization: convert tuple keys to "source_path|segment_tag|qualifier|elem|comp"
// strings. An empty qualifier slot serializes as the empty string between the surrounding
// pipes (e.g., "sg4|DTM||0|0"). Entries are written sorted by that key so the committed
// cache files are byte-stable.
impl serde::Serialize for CodeLookup {
    fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
        use serde::ser::SerializeMap;
        let mut entries: Vec<(String, &CodeMeanings)> = self
            .entries
            .iter()
            .map(|((path, tag, qual, elem, comp), meanings)| {
                let q = qual.as_deref().unwrap_or("");
                (format!("{path}|{tag}|{q}|{elem}|{comp}"), meanings)
            })
            .collect();
        entries.sort_by(|a, b| a.0.cmp(&b.0));
        let mut map = serializer.serialize_map(Some(entries.len()))?;
        for (key, meanings) in entries {
            map.serialize_entry(&key, meanings)?;
        }
        map.end()
    }
}

impl<'de> serde::Deserialize<'de> for CodeLookup {
    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
        let raw: HashMap<String, CodeMeanings> = HashMap::deserialize(deserializer)?;
        let mut entries = BTreeMap::new();
        for (key_str, meanings) in raw {
            let parts: Vec<&str> = key_str.splitn(5, '|').collect();
            if parts.len() == 5 {
                let qual = if parts[2].is_empty() {
                    None
                } else {
                    Some(parts[2].to_string())
                };
                let elem: usize = parts[3].parse().map_err(serde::de::Error::custom)?;
                let comp: usize = parts[4].parse().map_err(serde::de::Error::custom)?;
                entries.insert(
                    (parts[0].to_string(), parts[1].to_string(), qual, elem, comp),
                    meanings,
                );
            }
        }
        Ok(Self::from_entries(entries))
    }
}

impl CodeLookup {
    /// Build a CodeLookup from a PID schema JSON file.
    pub fn from_schema_file(path: &Path) -> Result<Self, std::io::Error> {
        let content = std::fs::read_to_string(path)?;
        let schema: Value = serde_json::from_str(&content)
            .map_err(|e| std::io::Error::new(std::io::ErrorKind::InvalidData, e))?;
        Ok(Self::from_schema_value(&schema))
    }

    /// Build a CodeLookup from an already-parsed PID schema JSON value.
    pub fn from_schema_value(schema: &Value) -> Self {
        let mut entries = BTreeMap::new();
        if let Some(fields) = schema.get("fields").and_then(|f| f.as_object()) {
            for (group_key, group_value) in fields {
                Self::walk_group(group_key, group_value, &mut entries);
            }
        }
        // Root-level segments (BGM, DTM, etc.) use empty source_path.
        if let Some(root_segments) = schema.get("root_segments").and_then(|s| s.as_array()) {
            for segment in root_segments {
                let seg_id = segment
                    .get("id")
                    .and_then(|v| v.as_str())
                    .unwrap_or("")
                    .to_uppercase();
                Self::process_segment("", &seg_id, segment, &mut entries);
            }
        }
        Self::from_entries(entries)
    }

    fn from_entries(entries: BTreeMap<CodeLookupKey, CodeMeanings>) -> Self {
        let variants = entries
            .keys()
            .filter_map(|(path, tag, qual, _, _)| {
                qual.as_ref()
                    .map(|q| (path.clone(), tag.clone(), q.clone()))
            })
            .collect();
        Self { entries, variants }
    }

    /// Codes a mapped field is enriched with (`{code, meaning}`), `None` if the
    /// engine writes it as a plain value.
    ///
    /// `path_qualifier` is the field path's `tag[Q]` selector, `disc_qualifier`
    /// the definition's discriminator value when the discriminator is on the same
    /// segment tag. Which positions get enriched follows the discriminator (as it
    /// always has); a path qualifier only narrows the codes to the segment variant
    /// the field actually reads, and suppresses enrichment where that variant has
    /// no code at the position (e.g. `rff[ACW].c506.d1154` next to RFF+Z13).
    pub fn enrichment_codes(
        &self,
        source_path: &str,
        segment_tag: &str,
        path_qualifier: Option<&str>,
        disc_qualifier: Option<&str>,
        element_index: usize,
        component_index: usize,
    ) -> Option<&CodeMeanings> {
        let at = |q| self.resolve_q(source_path, segment_tag, q, element_index, component_index);
        let path_variant =
            path_qualifier.filter(|q| self.is_known_variant(source_path, segment_tag, q));
        match (path_variant, disc_qualifier) {
            (Some(p), Some(d)) if p != d => at(Some(p)),
            (Some(p), None) => at(None).and(at(Some(p))),
            _ => at(disc_qualifier),
        }
    }

    /// Codes a mapped field can hold, whether enriched or not: those of the
    /// segment variant selected by the path qualifier or the same-tag
    /// discriminator; without either, the union over every variant (the field
    /// reads whichever segment instance is present). `None` if not a code field.
    pub fn field_codes(
        &self,
        source_path: &str,
        segment_tag: &str,
        path_qualifier: Option<&str>,
        disc_qualifier: Option<&str>,
        element_index: usize,
        component_index: usize,
    ) -> Option<CodeMeanings> {
        match path_qualifier.or(disc_qualifier) {
            Some(q) => self
                .resolve_q(
                    source_path,
                    segment_tag,
                    Some(q),
                    element_index,
                    component_index,
                )
                .cloned(),
            None => Some(self.codes_all_qualifiers(
                source_path,
                segment_tag,
                element_index,
                component_index,
            ))
            .filter(|c| !c.is_empty()),
        }
    }

    /// Whether `qualifier` names a segment variant of `segment_tag` at `source_path`
    /// (i.e. the schema has a `segment_tag` segment whose leading code is fixed to it).
    pub fn is_known_variant(&self, source_path: &str, segment_tag: &str, qualifier: &str) -> bool {
        self.variants.contains(&(
            source_path.to_string(),
            segment_tag.to_string(),
            qualifier.to_string(),
        ))
    }

    /// The entry a qualifier-aware lookup resolves to: the qualifier's own entry;
    /// for a qualifier that names no segment variant of the tag (or no qualifier),
    /// the unqualified entry. A known variant never falls back to the unqualified
    /// union — that would hand it the codes of a *different* segment variant (e.g.
    /// RFF+Z13's PID code for RFF+ACW's free reference number).
    fn resolve_q(
        &self,
        source_path: &str,
        segment_tag: &str,
        qualifier: Option<&str>,
        element_index: usize,
        component_index: usize,
    ) -> Option<&CodeMeanings> {
        let key = |q: Option<&str>| {
            (
                source_path.to_string(),
                segment_tag.to_string(),
                q.map(String::from),
                element_index,
                component_index,
            )
        };
        match qualifier {
            Some(q) if self.is_known_variant(source_path, segment_tag, q) => {
                self.entries.get(&key(Some(q)))
            }
            Some(q) => self
                .entries
                .get(&key(Some(q)))
                .or_else(|| self.entries.get(&key(None))),
            None => self.entries.get(&key(None)),
        }
    }

    /// Check if the field at the given position is a code-type field.
    ///
    /// Legacy shim — scans across all qualifier slots and returns true if ANY
    /// matching entry exists for the (path, tag, elem, comp) tuple. This drifts
    /// from the original "call _q with None" prescription but is more useful
    /// for tests that don't have a qualifier handy. Production code paths use
    /// [`is_code_field_q`] with the discriminator qualifier and a `None`
    /// fallback for tags without a stored qualifier convention.
    #[deprecated(
        note = "use is_code_field_q with the discriminator qualifier; this shim scans across all qualifiers"
    )]
    pub fn is_code_field(
        &self,
        source_path: &str,
        segment_tag: &str,
        element_index: usize,
        component_index: usize,
    ) -> bool {
        // Match if either the unqualified entry exists or any qualifier-scoped
        // entry matches the path/tag/elem/comp.
        self.entries.iter().any(|((p, t, _q, e, c), _)| {
            p == source_path && t == segment_tag && *e == element_index && *c == component_index
        })
    }

    /// Qualifier-aware variant: check if the position is a code field for the
    /// given qualifier.
    ///
    /// When `qualifier` names a segment variant of the tag (see
    /// [`is_known_variant`](Self::is_known_variant)), only that variant's entry
    /// counts: RFF+TN d1154 (data) is not a code field even though RFF+Z13 d1154
    /// is. A qualifier that names no variant (e.g. a discriminator value of
    /// another segment) and `None` use the unqualified entry.
    pub fn is_code_field_q(
        &self,
        source_path: &str,
        segment_tag: &str,
        qualifier: Option<&str>,
        element_index: usize,
        component_index: usize,
    ) -> bool {
        self.resolve_q(
            source_path,
            segment_tag,
            qualifier,
            element_index,
            component_index,
        )
        .is_some()
    }

    /// All codes (with their enrichment data) of the code field at the given
    /// position, resolved exactly like [`is_code_field_q`]. `None` if the
    /// position is not a code field (for that segment variant).
    ///
    /// [`is_code_field_q`]: Self::is_code_field_q
    pub fn codes_q(
        &self,
        source_path: &str,
        segment_tag: &str,
        qualifier: Option<&str>,
        element_index: usize,
        component_index: usize,
    ) -> Option<&CodeMeanings> {
        self.resolve_q(
            source_path,
            segment_tag,
            qualifier,
            element_index,
            component_index,
        )
    }

    /// Codes of the given position under every qualifier slot, merged. A
    /// definition without a discriminator reads whichever segment instance is
    /// present, so its values range over all of them.
    pub fn codes_all_qualifiers(
        &self,
        source_path: &str,
        segment_tag: &str,
        element_index: usize,
        component_index: usize,
    ) -> CodeMeanings {
        // Deterministic merge: the unqualified slot first, then by qualifier.
        let mut slots: Vec<(&Option<String>, &CodeMeanings)> = self
            .entries
            .iter()
            .filter(|((p, t, _, e, c), _)| {
                p == source_path && t == segment_tag && *e == element_index && *c == component_index
            })
            .map(|((_, _, q, _, _), meanings)| (q, meanings))
            .collect();
        slots.sort_by(|a, b| a.0.cmp(b.0));
        let mut merged = CodeMeanings::new();
        for (_, meanings) in slots {
            for (code, enrichment) in meanings {
                merged
                    .entry(code.clone())
                    .or_insert_with(|| enrichment.clone());
            }
        }
        merged
    }

    /// Get the full enrichment data for a code value at the given position.
    ///
    /// Legacy shim — scans across all qualifier slots. See [`enrichment_for_q`]
    /// for the qualifier-aware version used by the engine. Kept for tests.
    #[deprecated(
        note = "use enrichment_for_q with the discriminator qualifier; this shim scans across all qualifiers"
    )]
    pub fn enrichment_for(
        &self,
        source_path: &str,
        segment_tag: &str,
        element_index: usize,
        component_index: usize,
        value: &str,
    ) -> Option<&CodeEnrichment> {
        // Try unqualified first, then any qualifier-scoped match.
        let unqualified_key = (
            source_path.to_string(),
            segment_tag.to_string(),
            None,
            element_index,
            component_index,
        );
        if let Some(e) = self
            .entries
            .get(&unqualified_key)
            .and_then(|meanings| meanings.get(value))
        {
            return Some(e);
        }
        self.entries
            .iter()
            .filter(|((p, t, q, e, c), _)| {
                p == source_path
                    && t == segment_tag
                    && q.is_some()
                    && *e == element_index
                    && *c == component_index
            })
            .find_map(|(_, meanings)| meanings.get(value))
    }

    /// Qualifier-aware enrichment lookup, resolved like
    /// [`is_code_field_q`](Self::is_code_field_q).
    pub fn enrichment_for_q(
        &self,
        source_path: &str,
        segment_tag: &str,
        qualifier: Option<&str>,
        element_index: usize,
        component_index: usize,
        value: &str,
    ) -> Option<&CodeEnrichment> {
        self.resolve_q(
            source_path,
            segment_tag,
            qualifier,
            element_index,
            component_index,
        )
        .and_then(|meanings| meanings.get(value))
    }

    /// Get the human-readable meaning for a code value at the given position.
    /// Returns `None` if the position is not a code field or the value is unknown.
    ///
    /// Legacy shim — scans across all qualifier slots via [`enrichment_for`].
    /// Kept for tests; production code paths use the qualifier-aware
    /// `enrichment_for_q`.
    #[deprecated(
        note = "use enrichment_for_q with the discriminator qualifier; this shim scans across all qualifiers"
    )]
    pub fn meaning_for(
        &self,
        source_path: &str,
        segment_tag: &str,
        element_index: usize,
        component_index: usize,
        value: &str,
    ) -> Option<&str> {
        #[allow(deprecated)]
        self.enrichment_for(
            source_path,
            segment_tag,
            element_index,
            component_index,
            value,
        )
        .map(|e| e.meaning.as_str())
    }

    /// Whether this code-field's only allowed value equals the given PID.
    /// Used to suppress decoration for self-referential PID-identifier fields
    /// (Class C in the 2026-04-28 audit). The qualifier scopes the lookup —
    /// e.g., RFF+Z13's d1154 in PID 55002 has `value=55002` as the lone code,
    /// so calling with `qualifier=Some("Z13"), pid="55002"` returns true.
    pub fn is_pid_self_reference(
        &self,
        source_path: &str,
        segment_tag: &str,
        qualifier: Option<&str>,
        element_index: usize,
        component_index: usize,
        pid: &str,
    ) -> bool {
        let key = (
            source_path.to_string(),
            segment_tag.to_string(),
            qualifier.map(String::from),
            element_index,
            component_index,
        );
        if let Some(meanings) = self.entries.get(&key) {
            meanings.len() == 1 && meanings.contains_key(pid)
        } else {
            false
        }
    }

    /// Walk a group node recursively, collecting code entries.
    fn walk_group(
        path_prefix: &str,
        group: &Value,
        entries: &mut BTreeMap<CodeLookupKey, CodeMeanings>,
    ) {
        if let Some(segments) = group.get("segments").and_then(|s| s.as_array()) {
            for segment in segments {
                let seg_id = segment
                    .get("id")
                    .and_then(|v| v.as_str())
                    .unwrap_or("")
                    .to_uppercase();
                Self::process_segment(path_prefix, &seg_id, segment, entries);
            }
        }
        if let Some(children) = group.get("children").and_then(|c| c.as_object()) {
            for (child_key, child_value) in children {
                let child_path = format!("{}.{}", path_prefix, child_key);
                Self::walk_group(&child_path, child_value, entries);
            }
            // Create aggregate entries at the base path for discriminated variants.
            // E.g., sg12_z63, sg12_z65, sg12_z66 → also register at sg12 (unioned codes).
            // This supports TOMLs using non-discriminated source_path (e.g., "sg4.sg12").
            Self::merge_variant_entries(path_prefix, children, entries);
        }
    }

    /// Process a single segment, collecting code entries for its elements/components.
    ///
    /// Extracts the segment's qualifier (per-tag convention) and uses it to scope
    /// the entries. This avoids the (path, tag, elem, comp) collision between
    /// type=code and type=data segments at the same position (e.g., RFF+Z13's
    /// PID-identifier d1154 vs RFF+TN's free-text Vorgangsnummer d1154).
    fn process_segment(
        source_path: &str,
        segment_tag: &str,
        segment: &Value,
        entries: &mut BTreeMap<CodeLookupKey, CodeMeanings>,
    ) {
        let Some(elements) = segment.get("elements").and_then(|e| e.as_array()) else {
            return;
        };

        let qualifier = Self::extract_qualifier(segment_tag, elements);
        // Tags without a qualifier convention keep their unqualified entries and
        // are additionally registered under their own fixed leading code.
        let own_variant = if qualifier.is_none() && !Self::has_qualifier_convention(segment_tag) {
            Self::single_leading_code(elements)
        } else {
            None
        };
        let slots: Vec<Option<String>> = std::iter::once(qualifier)
            .chain(own_variant.map(Some))
            .collect();

        for element in elements {
            let element_index = element.get("index").and_then(|v| v.as_u64()).unwrap_or(0) as usize;

            // Simple element (no composite) with codes
            if let Some("code") = element.get("type").and_then(|v| v.as_str()) {
                if let Some(codes) = element.get("codes").and_then(|c| c.as_array()) {
                    let meanings = Self::extract_codes(codes);
                    if !meanings.is_empty() {
                        for slot in &slots {
                            let key = (
                                source_path.to_string(),
                                segment_tag.to_string(),
                                slot.clone(),
                                element_index,
                                0,
                            );
                            entries.entry(key).or_default().extend(meanings.clone());
                        }
                    }
                }
            }

            // Composite components
            if let Some(components) = element.get("components").and_then(|c| c.as_array()) {
                for component in components {
                    if let Some("code") = component.get("type").and_then(|v| v.as_str()) {
                        let sub_index = component
                            .get("sub_index")
                            .and_then(|v| v.as_u64())
                            .unwrap_or(0) as usize;
                        if let Some(codes) = component.get("codes").and_then(|c| c.as_array()) {
                            let meanings = Self::extract_codes(codes);
                            if !meanings.is_empty() {
                                for slot in &slots {
                                    let key = (
                                        source_path.to_string(),
                                        segment_tag.to_string(),
                                        slot.clone(),
                                        element_index,
                                        sub_index,
                                    );
                                    entries.entry(key).or_default().extend(meanings.clone());
                                }
                            }
                        }
                    }
                }
            }
        }
    }

    /// Extract a segment's discriminating qualifier from its schema element list.
    ///
    /// Conventions:
    /// - `RFF`, `STS`, `CCI`: qualifier is the type=code value at element 0,
    ///   component 0 (RFF d1153, STS d9013, CCI d7059).
    /// - `DTM`: qualifier is at composite c507's component 0 (d2005). This is
    ///   the same physical position (element 0 component 0) — DTM's element 0
    ///   IS the c507 composite — so the same lookup applies.
    /// - All other tags: no qualifier convention; returns `None`.
    ///
    /// Only single-value enumerations count as a qualifier (the schema lists
    /// exactly one allowed code at that position). Segments whose first
    /// component lists multiple codes don't have a discriminating qualifier
    /// at the schema level and fall back to `None`.
    fn extract_qualifier(segment_tag: &str, elements: &[Value]) -> Option<String> {
        if !Self::has_qualifier_convention(segment_tag) {
            return None;
        }
        Self::single_leading_code(elements)
    }

    /// Tags whose entries are stored exclusively under their qualifier.
    fn has_qualifier_convention(segment_tag: &str) -> bool {
        matches!(segment_tag, "RFF" | "STS" | "CCI" | "DTM")
    }

    /// The segment's leading code (element 0, component 0) when the schema fixes
    /// it to exactly one value — the value a `tag[QUAL]` field path selects on.
    fn single_leading_code(elements: &[Value]) -> Option<String> {
        // Find element index 0 (or the first element if no index 0 is set).
        let element0 = elements
            .iter()
            .find(|el| el.get("index").and_then(|v| v.as_u64()) == Some(0))
            .or_else(|| elements.first())?;

        // Inspect component sub_index 0.
        let component0 = element0
            .get("components")
            .and_then(|c| c.as_array())
            .and_then(|comps| {
                comps
                    .iter()
                    .find(|c| c.get("sub_index").and_then(|v| v.as_u64()) == Some(0))
                    .or_else(|| comps.first())
            });

        let codes_node = if let Some(comp) = component0 {
            // Composite case (RFF/DTM/CCI/STS — qualifier nested inside composite).
            if comp.get("type").and_then(|v| v.as_str()) == Some("code") {
                comp.get("codes").and_then(|c| c.as_array())
            } else {
                None
            }
        } else if element0.get("type").and_then(|v| v.as_str()) == Some("code") {
            // Simple-element case.
            element0.get("codes").and_then(|c| c.as_array())
        } else {
            None
        };

        let codes = codes_node?;
        if codes.len() != 1 {
            return None; // Multiple allowed qualifiers — not a single discriminator.
        }
        codes[0]
            .get("value")
            .and_then(|v| v.as_str())
            .map(|s| s.to_string())
    }

    /// Merge code entries from discriminated variant children into aggregate base-path entries.
    ///
    /// When the schema has `sg12_z63`, `sg12_z65`, etc., each gets its own CodeLookup entries
    /// at `prefix.sg12_z63`, `prefix.sg12_z65`. This method also creates entries at the
    /// base path `prefix.sg12` by unioning all codes from the variants. This supports
    /// TOMLs that use a non-discriminated `source_path` (e.g., the Geschaeftspartner pattern).
    fn merge_variant_entries(
        path_prefix: &str,
        children: &serde_json::Map<String, Value>,
        entries: &mut BTreeMap<CodeLookupKey, CodeMeanings>,
    ) {
        // Group children by base name (part before '_'): sg12_z63 → sg12
        let mut bases: HashMap<&str, Vec<&str>> = HashMap::new();
        for child_key in children.keys() {
            if let Some(underscore_pos) = child_key.find('_') {
                let base = &child_key[..underscore_pos];
                bases.entry(base).or_default().push(child_key);
            }
        }

        for (base, variant_keys) in &bases {
            if variant_keys.len() < 2 {
                continue; // Not a discriminated group
            }
            let base_path = format!("{}.{}", path_prefix, base);
            // Collect all variant-path entries and merge into base-path entries.
            // Aggregation key keeps the qualifier slot so that, e.g., NAD+Z63 vs
            // NAD+Z65 don't collapse into one entry at the merged base path.
            let mut merged: HashMap<(String, Option<String>, usize, usize), CodeMeanings> =
                HashMap::new();
            for variant_key in variant_keys {
                let variant_path = format!("{}.{}", path_prefix, variant_key);
                for (key, meanings) in entries.iter() {
                    if key.0 == variant_path {
                        let agg_key = (key.1.clone(), key.2.clone(), key.3, key.4);
                        let target = merged.entry(agg_key).or_default();
                        for (k, v) in meanings {
                            target.insert(k.clone(), v.clone());
                        }
                    }
                }
            }
            for ((seg_tag, qual, elem_idx, comp_idx), meanings) in merged {
                let key = (base_path.clone(), seg_tag, qual, elem_idx, comp_idx);
                entries.entry(key).or_default().extend(meanings);
            }
        }
    }

    /// Extract code value→enrichment mappings from a JSON codes array.
    fn extract_codes(codes: &[Value]) -> CodeMeanings {
        let mut meanings = BTreeMap::new();
        for code in codes {
            if let (Some(value), Some(name)) = (
                code.get("value").and_then(|v| v.as_str()),
                code.get("name").and_then(|v| v.as_str()),
            ) {
                let enum_key = code
                    .get("enum")
                    .and_then(|v| v.as_str())
                    .map(|s| s.to_string());
                meanings.insert(
                    value.to_string(),
                    CodeEnrichment {
                        meaning: name.to_string(),
                        enum_key,
                    },
                );
            }
        }
        meanings
    }
}

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

    #[test]
    fn test_parse_pid_55001_schema() {
        let schema_path = Path::new(concat!(
            env!("CARGO_MANIFEST_DIR"),
            "/../../crates/mig-types/src/generated/fv2504/utilmd/pids/pid_55001_schema.json"
        ));
        if !schema_path.exists() {
            eprintln!("Skipping: PID schema not found");
            return;
        }

        let lookup = CodeLookup::from_schema_file(schema_path).unwrap();

        // CCI element 2 component 0 in sg4.sg8_z01.sg10 — Haushaltskunde codes
        assert!(lookup.is_code_field("sg4.sg8_z01.sg10", "CCI", 2, 0));
        assert_eq!(
            lookup.meaning_for("sg4.sg8_z01.sg10", "CCI", 2, 0, "Z15"),
            Some("Haushaltskunde gem. EnWG")
        );
        assert_eq!(
            lookup.meaning_for("sg4.sg8_z01.sg10", "CCI", 2, 0, "Z18"),
            Some("Kein Haushaltskunde gem. EnWG")
        );

        // CCI element 0 in sg4.sg8_z79.sg10 — Produkteigenschaft
        assert!(lookup.is_code_field("sg4.sg8_z79.sg10", "CCI", 0, 0));
        assert_eq!(
            lookup.meaning_for("sg4.sg8_z79.sg10", "CCI", 0, 0, "Z66"),
            Some("Produkteigenschaft")
        );

        // CAV element 0 component 0 — code field
        assert!(lookup.is_code_field("sg4.sg8_z79.sg10", "CAV", 0, 0));

        // CAV element 0 component 3 — data field, NOT a code
        assert!(!lookup.is_code_field("sg4.sg8_z79.sg10", "CAV", 0, 3));

        // LOC element 1 — data field
        assert!(!lookup.is_code_field("sg4.sg5_z16", "LOC", 1, 0));
    }

    #[test]
    fn test_from_inline_schema() {
        let schema = serde_json::json!({
            "fields": {
                "sg4": {
                    "children": {
                        "sg8_test": {
                            "children": {
                                "sg10": {
                                    "segments": [{
                                        "id": "CCI",
                                        "elements": [{
                                            "index": 2,
                                            "components": [{
                                                "sub_index": 0,
                                                "type": "code",
                                                "codes": [
                                                    {"value": "A1", "name": "Alpha"},
                                                    {"value": "B2", "name": "Beta"}
                                                ]
                                            }]
                                        }]
                                    }],
                                    "source_group": "SG10"
                                }
                            },
                            "segments": [],
                            "source_group": "SG8"
                        }
                    },
                    "segments": [],
                    "source_group": "SG4"
                }
            }
        });

        let lookup = CodeLookup::from_schema_value(&schema);

        assert!(lookup.is_code_field("sg4.sg8_test.sg10", "CCI", 2, 0));
        assert_eq!(
            lookup.meaning_for("sg4.sg8_test.sg10", "CCI", 2, 0, "A1"),
            Some("Alpha")
        );
        assert_eq!(
            lookup.meaning_for("sg4.sg8_test.sg10", "CCI", 2, 0, "B2"),
            Some("Beta")
        );
        assert_eq!(
            lookup.meaning_for("sg4.sg8_test.sg10", "CCI", 2, 0, "XX"),
            None
        );
        assert!(!lookup.is_code_field("sg4.sg8_test.sg10", "CCI", 0, 0));
    }

    #[test]
    fn test_discriminated_variant_merge() {
        // Schema with discriminated SG12 variants (sg12_z63, sg12_z65)
        let schema = serde_json::json!({
            "fields": {
                "sg4": {
                    "children": {
                        "sg12_z63": {
                            "segments": [{
                                "id": "NAD",
                                "elements": [{
                                    "index": 0,
                                    "type": "code",
                                    "codes": [{"value": "Z63", "name": "Standortadresse"}]
                                }]
                            }],
                            "source_group": "SG12"
                        },
                        "sg12_z65": {
                            "segments": [{
                                "id": "NAD",
                                "elements": [
                                    {
                                        "index": 0,
                                        "type": "code",
                                        "codes": [{"value": "Z65", "name": "Kunde des LF"}]
                                    },
                                    {
                                        "index": 3,
                                        "components": [{
                                            "sub_index": 5,
                                            "type": "code",
                                            "codes": [
                                                {"value": "Z01", "name": "Herr"},
                                                {"value": "Z02", "name": "Frau"}
                                            ]
                                        }]
                                    }
                                ]
                            }],
                            "source_group": "SG12"
                        }
                    },
                    "segments": [],
                    "source_group": "SG4"
                }
            }
        });

        let lookup = CodeLookup::from_schema_value(&schema);

        // Variant-specific paths still work
        assert!(lookup.is_code_field("sg4.sg12_z63", "NAD", 0, 0));
        assert!(lookup.is_code_field("sg4.sg12_z65", "NAD", 0, 0));

        // Base path also works (merged from variants)
        assert!(lookup.is_code_field("sg4.sg12", "NAD", 0, 0));
        assert_eq!(
            lookup.meaning_for("sg4.sg12", "NAD", 0, 0, "Z63"),
            Some("Standortadresse")
        );
        assert_eq!(
            lookup.meaning_for("sg4.sg12", "NAD", 0, 0, "Z65"),
            Some("Kunde des LF")
        );

        // Anrede code from z65 also available at base path
        assert!(lookup.is_code_field("sg4.sg12", "NAD", 3, 5));
        assert_eq!(
            lookup.meaning_for("sg4.sg12", "NAD", 3, 5, "Z01"),
            Some("Herr")
        );
    }

    #[test]
    fn test_pid_55013_sg12_base_path() {
        let schema_path = Path::new(concat!(
            env!("CARGO_MANIFEST_DIR"),
            "/../../crates/mig-types/src/generated/fv2504/utilmd/pids/pid_55013_schema.json"
        ));
        if !schema_path.exists() {
            eprintln!("Skipping: PID schema not found");
            return;
        }

        let lookup = CodeLookup::from_schema_file(schema_path).unwrap();

        // Base path "sg4.sg12" should have merged NAD qualifier codes from all variants
        assert!(lookup.is_code_field("sg4.sg12", "NAD", 0, 0));
        // Z67 meaning comes from sg12_z67 variant
        assert!(lookup.meaning_for("sg4.sg12", "NAD", 0, 0, "Z67").is_some());
        // All 7 SG12 qualifiers should be present
        for code in &["Z63", "Z65", "Z66", "Z67", "Z68", "Z69", "Z70"] {
            assert!(
                lookup.meaning_for("sg4.sg12", "NAD", 0, 0, code).is_some(),
                "Missing meaning for NAD qualifier {code} at base path sg4.sg12"
            );
        }
    }

    #[test]
    fn test_multi_segment_code_merge() {
        // SG10 with 3 CCI segments at same element position but different codes.
        // All codes should be merged, not overwritten by last CCI.
        let schema = serde_json::json!({
            "fields": {
                "sg4": {
                    "children": {
                        "sg8_z98": {
                            "children": {
                                "sg10": {
                                    "segments": [
                                        {
                                            "id": "CCI",
                                            "elements": [{"index": 2, "components": [{
                                                "sub_index": 0, "type": "code",
                                                "codes": [{"value": "ZB3", "name": "Zugeordneter Marktpartner"}]
                                            }]}]
                                        },
                                        {
                                            "id": "CAV",
                                            "elements": [{"index": 0, "components": [{
                                                "sub_index": 0, "type": "code",
                                                "codes": [{"value": "Z91", "name": "MSB"}]
                                            }]}]
                                        },
                                        {
                                            "id": "CCI",
                                            "elements": [{"index": 2, "components": [{
                                                "sub_index": 0, "type": "code",
                                                "codes": [{"value": "E03", "name": "Spannungsebene"}]
                                            }]}]
                                        },
                                        {
                                            "id": "CAV",
                                            "elements": [{"index": 0, "components": [{
                                                "sub_index": 0, "type": "code",
                                                "codes": [
                                                    {"value": "E05", "name": "Mittelspannung"},
                                                    {"value": "E06", "name": "Niederspannung"}
                                                ]
                                            }]}]
                                        },
                                        {
                                            "id": "CCI",
                                            "elements": [{"index": 2, "components": [{
                                                "sub_index": 0, "type": "code",
                                                "codes": [
                                                    {"value": "Z15", "name": "Haushaltskunde"},
                                                    {"value": "Z18", "name": "Kein Haushaltskunde"}
                                                ]
                                            }]}]
                                        }
                                    ],
                                    "source_group": "SG10"
                                }
                            },
                            "segments": [],
                            "source_group": "SG8"
                        }
                    },
                    "segments": [],
                    "source_group": "SG4"
                }
            }
        });

        let lookup = CodeLookup::from_schema_value(&schema);

        // All CCI codes at (2,0) should be present (merged, not overwritten)
        assert_eq!(
            lookup.meaning_for("sg4.sg8_z98.sg10", "CCI", 2, 0, "ZB3"),
            Some("Zugeordneter Marktpartner")
        );
        assert_eq!(
            lookup.meaning_for("sg4.sg8_z98.sg10", "CCI", 2, 0, "E03"),
            Some("Spannungsebene")
        );
        assert_eq!(
            lookup.meaning_for("sg4.sg8_z98.sg10", "CCI", 2, 0, "Z15"),
            Some("Haushaltskunde")
        );

        // All CAV codes at (0,0) should be present
        assert_eq!(
            lookup.meaning_for("sg4.sg8_z98.sg10", "CAV", 0, 0, "Z91"),
            Some("MSB")
        );
        assert_eq!(
            lookup.meaning_for("sg4.sg8_z98.sg10", "CAV", 0, 0, "E06"),
            Some("Niederspannung")
        );
    }

    #[test]
    fn test_enrichment_for_with_enum() {
        let schema = serde_json::json!({
            "fields": {
                "sg4": {
                    "children": {
                        "sg10": {
                            "segments": [{
                                "id": "CCI",
                                "elements": [{
                                    "index": 2,
                                    "components": [{
                                        "sub_index": 0,
                                        "type": "code",
                                        "codes": [
                                            {"value": "Z15", "name": "Haushaltskunde", "enum": "HAUSHALTSKUNDE"},
                                            {"value": "Z18", "name": "Kein Haushaltskunde", "enum": "KEIN_HAUSHALTSKUNDE"}
                                        ]
                                    }]
                                }]
                            }],
                            "source_group": "SG10"
                        }
                    },
                    "segments": [],
                    "source_group": "SG4"
                }
            }
        });

        let lookup = CodeLookup::from_schema_value(&schema);

        let enrichment = lookup.enrichment_for("sg4.sg10", "CCI", 2, 0, "Z15");
        assert!(enrichment.is_some());
        let e = enrichment.unwrap();
        assert_eq!(e.meaning, "Haushaltskunde");
        assert_eq!(e.enum_key.as_deref(), Some("HAUSHALTSKUNDE"));

        let e2 = lookup
            .enrichment_for("sg4.sg10", "CCI", 2, 0, "Z18")
            .unwrap();
        assert_eq!(e2.enum_key.as_deref(), Some("KEIN_HAUSHALTSKUNDE"));

        // meaning_for still works
        assert_eq!(
            lookup.meaning_for("sg4.sg10", "CCI", 2, 0, "Z15"),
            Some("Haushaltskunde")
        );
    }

    #[test]
    fn test_backward_compat_no_enum() {
        // Old schema format without "enum" field — should still work, enum_key is None
        let schema = serde_json::json!({
            "fields": {
                "sg4": {
                    "children": {
                        "sg10": {
                            "segments": [{
                                "id": "CCI",
                                "elements": [{
                                    "index": 2,
                                    "components": [{
                                        "sub_index": 0,
                                        "type": "code",
                                        "codes": [
                                            {"value": "Z15", "name": "Haushaltskunde"}
                                        ]
                                    }]
                                }]
                            }],
                            "source_group": "SG10"
                        }
                    },
                    "segments": [],
                    "source_group": "SG4"
                }
            }
        });

        let lookup = CodeLookup::from_schema_value(&schema);
        let enrichment = lookup.enrichment_for("sg4.sg10", "CCI", 2, 0, "Z15");
        assert!(enrichment.is_some());
        let e = enrichment.unwrap();
        assert_eq!(e.meaning, "Haushaltskunde");
        assert_eq!(e.enum_key, None); // No enum in old schema
    }

    /// SG15 of IFTSTA 21037: RFF+Z13 (d1154 = the PID, a code), RFF+ACW and
    /// RFF+ACE (d1154 = free reference, data); plus two CAV variants whose value
    /// component carries different code lists.
    fn qualified_variants_schema() -> Value {
        let rff = |qual: &str, name: &str, id_codes: Option<Value>| {
            let id = match id_codes {
                Some(codes) => {
                    serde_json::json!({"sub_index": 1, "id": "1154", "type": "code", "codes": codes})
                }
                None => serde_json::json!({"sub_index": 1, "id": "1154", "type": "data"}),
            };
            serde_json::json!({"id": "RFF", "elements": [{"index": 0, "composite": "C506", "components": [
                {"sub_index": 0, "id": "1153", "type": "code", "codes": [{"value": qual, "name": name}]},
                id,
            ]}]})
        };
        let cav = |qual: &str, codes: Value| {
            serde_json::json!({"id": "CAV", "elements": [{"index": 0, "composite": "C889", "components": [
                {"sub_index": 0, "id": "7111", "type": "code", "codes": [{"value": qual, "name": qual}]},
                {"sub_index": 1, "id": "7110", "type": "code", "codes": codes},
            ]}]})
        };
        serde_json::json!({"fields": {"sg14": {"segments": [], "children": {"sg15": {"segments": [
            rff("Z13", "Prüfidentifikator", Some(serde_json::json!([{"value": "21037", "name": "RD / NB-Bewertung"}]))),
            rff("ACW", "Referenznummer einer vorangegangenen Nachricht", None),
            rff("ACE", "Nummer des zugehörigen Dokuments", None),
            cav("Z91", serde_json::json!([{"value": "A", "name": "Alpha"}, {"value": "B", "name": "Beta"}])),
            cav("ZF0", serde_json::json!([{"value": "C", "name": "Gamma"}])),
        ]}}}}})
    }

    #[test]
    fn qualified_lookup_uses_only_codes_of_that_segment_variant() {
        let lookup = CodeLookup::from_schema_value(&qualified_variants_schema());
        let sp = "sg14.sg15";

        // RFF+ACW / RFF+ACE d1154 are data: no fallback to RFF+Z13's PID code.
        for qual in ["ACW", "ACE"] {
            assert!(
                lookup.codes_q(sp, "RFF", Some(qual), 0, 1).is_none(),
                "{qual}"
            );
            assert!(
                !lookup.is_code_field_q(sp, "RFF", Some(qual), 0, 1),
                "{qual}"
            );
            assert!(lookup
                .enrichment_for_q(sp, "RFF", Some(qual), 0, 1, "21037")
                .is_none());
        }
        let z13: Vec<&String> = lookup
            .codes_q(sp, "RFF", Some("Z13"), 0, 1)
            .unwrap()
            .keys()
            .collect();
        assert_eq!(z13, ["21037"]);
        let acw: Vec<&String> = lookup
            .codes_q(sp, "RFF", Some("ACW"), 0, 0)
            .unwrap()
            .keys()
            .collect();
        assert_eq!(acw, ["ACW"]);

        // Tags without a qualifier convention (CAV) are variant-scoped too when a
        // qualifier is given; without one they keep the union of all variants.
        let z91: Vec<&String> = lookup
            .codes_q(sp, "CAV", Some("Z91"), 0, 1)
            .unwrap()
            .keys()
            .collect();
        assert_eq!(z91, ["A", "B"]);
        assert!(lookup
            .enrichment_for_q(sp, "CAV", Some("Z91"), 0, 1, "C")
            .is_none());
        let zf0: Vec<&String> = lookup
            .codes_q(sp, "CAV", Some("ZF0"), 0, 1)
            .unwrap()
            .keys()
            .collect();
        assert_eq!(zf0, ["C"]);
        let all: Vec<&String> = lookup
            .codes_q(sp, "CAV", None, 0, 1)
            .unwrap()
            .keys()
            .collect();
        assert_eq!(all, ["A", "B", "C"]);
        // A qualifier that names no variant of the tag (e.g. a discriminator on
        // another segment) still falls back to the unqualified entry.
        assert!(lookup.is_code_field_q(sp, "CAV", Some("Z98"), 0, 1));
    }

    #[test]
    fn qualified_lookup_survives_cache_serialization() {
        let lookup = CodeLookup::from_schema_value(&qualified_variants_schema());
        let back: CodeLookup =
            serde_json::from_str(&serde_json::to_string(&lookup).unwrap()).unwrap();
        assert!(back
            .codes_q("sg14.sg15", "RFF", Some("ACW"), 0, 1)
            .is_none());
        let z91: Vec<&String> = back
            .codes_q("sg14.sg15", "CAV", Some("Z91"), 0, 1)
            .unwrap()
            .keys()
            .collect();
        assert_eq!(z91, ["A", "B"]);
    }

    #[test]
    fn rff_tn_in_55002_is_not_a_code_field() {
        let schema_path = Path::new(concat!(
            env!("CARGO_MANIFEST_DIR"),
            "/../../crates/mig-types/src/generated/fv2504/utilmd/pids/pid_55002_schema.json"
        ));
        if !schema_path.exists() {
            return;
        }
        let lookup = CodeLookup::from_schema_file(schema_path).unwrap();

        // RFF+TN component 1 is type=data (Vorgangsnummer), must NOT be a code field.
        assert!(
            !lookup.is_code_field_q("sg4.sg6", "RFF", Some("TN"), 0, 1),
            "RFF+TN d1154 is free-text Vorgangsnummer, must not be classified as code"
        );

        // RFF+Z13 component 1 IS a code field with the PID value (Class C; suppression
        // happens elsewhere — here we just confirm the lookup classifies it as code).
        assert!(
            lookup.is_code_field_q("sg4.sg6", "RFF", Some("Z13"), 0, 1),
            "RFF+Z13 d1154 is type=code with PID-identifier value"
        );
    }

    #[test]
    fn pid_self_reference_detection() {
        let schema_path = Path::new(concat!(
            env!("CARGO_MANIFEST_DIR"),
            "/../../crates/mig-types/src/generated/fv2504/utilmd/pids/pid_55002_schema.json"
        ));
        if !schema_path.exists() {
            return;
        }
        let lookup = CodeLookup::from_schema_file(schema_path).unwrap();

        // RFF+Z13 d1154's only allowed value is "55002" — the PID itself.
        assert!(
            lookup.is_pid_self_reference("sg4.sg6", "RFF", Some("Z13"), 0, 1, "55002"),
            "Z13 d1154 with single value '55002' must be detected as PID self-ref"
        );
        // Same field for a different PID should NOT count as self-reference.
        assert!(
            !lookup.is_pid_self_reference("sg4.sg6", "RFF", Some("Z13"), 0, 1, "55001"),
            "Z13 d1154's '55002' should not count as self-ref for PID 55001"
        );
    }
}