can_tools 2.1.2

//! CanDatabase model (SlotMap-backed).
//!
//! This module defines the in-memory **CAN database** used by the DBC/ARXML parsers.
//! Storage uses **SlotMap** arenas with **stable keys**: [`CanNodeKey`], [`CanMessageKey`], [`CanSignalKey`].
//! Public iteration follows **order vectors** via `iter_nodes()`, `iter_messages()`, `iter_signals()`
//! and you can reorder presentation with `sort_nodes_by_name()`, `sort_messages_by_name()`, `sort_signals_by_name()`.
//!
//! **Lookups** are normalized and O(1): `get_message_by_id/_hex/_name`, `get_node_by_name`, `get_signal_by_name`.
//! Names are case-insensitive; hexadecimal IDs use uppercase `0x...` form.
//!
//! Signal decoding utilities live on [`CanSignal`]: `compile_inline()`, `extract_raw_u64/i64()`.
//! Conversion to `SignalLog` is provided under `asc::core::signal_conversion` when the `asc` feature is enabled.
//!
//! Docs updated: 2025-10-09 — refreshed field documentation and clarified ordering invariants.
//!

use slotmap::{Key, SlotMap, new_key_type};
use std::collections::{BTreeMap, HashMap, HashSet};

use crate::{
    core::message_layout,
    types::{
        attributes::{AttrObject, AttrValueType, AttributeSpec, AttributeValue},
        errors::DatabaseError,
        message::{IdFormat, CanMessage, MuxRole, MuxSelector},
        node::CanNode,
        signal::{Endianness, CanSignal, Signess},
    },
};

// --- Stable keys (SlotMap) ---
new_key_type! { pub struct CanNodeKey; }
new_key_type! { pub struct CanMessageKey; }
new_key_type! { pub struct CanSignalKey; }

/// In-memory representation of a CAN database (DBC).
///
/// Holds metadata (name, bus type, baud rates, version), the arenas of nodes/messages/signals
/// (SlotMaps with stable keys), optional order vectors to control iteration order, and
/// several normalized lookup maps for efficient queries.
#[derive(Default, Clone)]
pub struct CanDatabase {
    // --- General information ---
    /// Human-readable database name (`BA_ "DBName"`), empty if absent.
    pub name: String,
    /// Bus type advertised by `BA_ "BusType"` (defaults to `BusType::Can`).
    pub bustype: BusType,
    /// Free-form version string parsed from the `VERSION` line.
    pub version: String,
    /// Global database comment (populated by the standalone `CM_ "..."` statement).
    pub comment: String,

    // --- Main storage (stable-key maps) ---
    pub nodes: SlotMap<CanNodeKey, CanNode>,
    pub messages: SlotMap<CanMessageKey, CanMessage>,
    pub signals: SlotMap<CanSignalKey, CanSignal>,

    // --- Order "views"  ---
    pub nodes_order: Vec<CanNodeKey>,
    pub messages_order: Vec<CanMessageKey>,
    pub signals_order: Vec<CanSignalKey>,

    // --- DB Attribute Entry ---
    pub attributes: BTreeMap<String, AttributeValue>,

    // --- Attributes Spec ---
    pub attr_spec: BTreeMap<String, AttributeSpec>,

    // --- Relational Attributes Spec ---
    // Definitions (BA_DEF_REL_) and defaults (BA_DEF_DEF_REL_) for attributes that
    // apply to relations between two entities.
    //
    // Vector DBC supports at least these relation kinds:
    // - BU_SG_REL_: Node ↔ Signal
    // - BU_BO_REL_: Node ↔ Message
    pub rel_attr_spec_bu_sg: BTreeMap<String, AttributeSpec>,
    pub rel_attr_spec_bu_bo: BTreeMap<String, AttributeSpec>,

    // --- Lookups (case-normalized) ---
    /// Global map for nodes by (lower) name.
    pub node_key_by_name: HashMap<String, CanNodeKey>, // lower(name) → CanNodeKey
    /// Global map for messages by id.
    pub msg_key_by_id: HashMap<u32, CanMessageKey>, // id10 → CanMessageKey
    /// Global map for messages by id_hex.
    pub msg_key_by_hex: HashMap<String, CanMessageKey>, // "0x...." uppercase → CanMessageKey
    /// Global map for messages by (lower) name.
    pub msg_key_by_name: HashMap<String, CanMessageKey>, // lower(name) → CanMessageKey
    /// Global map for signals by (lower) name. Beware of collisions if two BO_ have same SG_ name.
    pub sig_key_by_name: HashMap<String, CanSignalKey>, // lower(name) → CanSignalKey

    // Parsing state: last message seen (used by SG_ decoder)
    pub(crate) current_msg: Option<CanMessageKey>,

    // --- Relational Attributes (BA_REL_) ---
    // Concrete values attached to a pair of entities.
    // Attribute names are kept sorted (BTreeMap) for stable iteration.
    // Keys for pairs use HashMap since order is not important and SlotMap keys are hashable.
    /// BU_SG_REL_: attributes on (Node, Signal) pairs.
    pub bu_sg_rel_attributes: HashMap<(CanNodeKey, CanSignalKey), BTreeMap<String, AttributeValue>>,
    /// BU_BO_REL_: attributes on (Node, Message) pairs.
    pub bu_bo_rel_attributes: HashMap<(CanNodeKey, CanMessageKey), BTreeMap<String, AttributeValue>>,
}

impl CanDatabase {
    // --------- Nodes --------
    /// Adds a node to the database, seeding attributes with spec defaults, and returns the `CanNodeKey`.
    pub fn add_node(&mut self, name: &str) -> Result<CanNodeKey, DatabaseError> {
        // check that the node name is not already present
        if self.get_node_key_by_name(name).is_some() {
            return Err(DatabaseError::NodeAlreadyExists {
                name: name.to_string(),
            });
        }

        let mut node: CanNode = CanNode {
            name: name.to_string(),
            ..Default::default()
        };

        // add attribute with default value
        for (attr_name, spec) in self
            .attr_spec
            .iter()
            .filter(|(_, s)| s.type_of_object == AttrObject::Node)
        {
            node.attributes
                .insert(attr_name.clone(), spec.default.clone());
        }

        // create CanNodeKey and CanNode
        let key: CanNodeKey = self.nodes.insert(node);

        // push CanNodeKey in relevant variables
        self.nodes_order.push(key);
        self.node_key_by_name.insert(name.to_lowercase(), key);
        Ok(key)
    }

    /// Link a sender node to a message, keeping both sides in sync.
    pub fn add_sender_relation(
        &mut self,
        msg_key: CanMessageKey,
        node_key: CanNodeKey,
    ) -> Result<(), DatabaseError> {
        let mut pending_tx: Vec<CanSignalKey>;
        {
            let message =
                self.get_message_by_key(msg_key)
                    .ok_or(DatabaseError::MessageMissing {
                        message_key: msg_key,
                    })?;
            let node = self
                .get_node_by_key(node_key)
                .ok_or(DatabaseError::NodeMissing { node_key })?;

            // signals of the Message that needs to be added as CanNode.tx_signals
            pending_tx = message
                .signals
                .iter()
                .copied()
                .filter(|sig| !node.tx_signals.contains(sig))
                .collect();
        }

        // check that a CanMessage exist for given CanMessageKey
        let Some(message) = self.get_message_by_key_mut(msg_key) else {
            return Err(DatabaseError::MessageMissing {
                message_key: msg_key,
            });
        };

        // add the CanNodeKey to CanMessage if not already present
        if !message.sender_nodes.contains(&node_key) {
            message.sender_nodes.push(node_key);
        }

        // check that a CanNode exist for given CanNodeKey
        let Some(node) = self.get_node_by_key_mut(node_key) else {
            return Err(DatabaseError::NodeMissing { node_key });
        };

        // add the CanMessageKey to CanNode if not already present
        if !node.messages_sent.contains(&msg_key) {
            node.messages_sent.push(msg_key);
        }

        // add the CanSignalKeys missing from CanNode
        for signal_key in pending_tx.drain(..) {
            node.tx_signals.push(signal_key);
        }

        Ok(())
    }

    /// Remove a message from a Sender Node, keeping both sides in sync.
    pub fn remove_sender_relation(
        &mut self,
        msg_key: CanMessageKey,
        node_key: CanNodeKey,
    ) -> Result<(), DatabaseError> {
        let mut to_prune: Vec<CanSignalKey>;
        {
            let message =
                self.get_message_by_key(msg_key)
                    .ok_or(DatabaseError::MessageMissing {
                        message_key: msg_key,
                    })?;
            // signals of the Message that needs to be removed as CanNode.tx_signals
            to_prune = message.signals.to_vec();
        }

        {
            // check that a CanMessage exist for given CanMessageKey
            let Some(message) = self.get_message_by_key_mut(msg_key) else {
                return Err(DatabaseError::MessageMissing {
                    message_key: msg_key,
                });
            };
            // remove the CanNodeKey from CanMessage.sender_nodes
            message.sender_nodes.retain(|x| x != &node_key);
        }

        // check that a CanNode exist for given CanNodeKey
        let Some(node) = self.get_node_by_key_mut(node_key) else {
            return Err(DatabaseError::NodeMissing { node_key });
        };

        node.messages_sent.retain(|x| x != &msg_key);

        // remove the CanSignalKeys from CanNode.tx_signals
        if !to_prune.is_empty() {
            let prune_set: HashSet<CanSignalKey> = to_prune.drain(..).collect();
            node.tx_signals.retain(|sig| !prune_set.contains(sig));
        }

        Ok(())
    }

    /// Create a new Node from an existing one adding "_copy" to the name
    /// Messages and Signals are modified to include new node relations
    pub fn copy_node(&mut self, source_node_key: CanNodeKey) -> Result<CanNodeKey, DatabaseError> {
        let new_node: CanNode = {
            // check that the source node key correspond to a Node
            let Some(node) = self.get_node_by_key(source_node_key) else {
                return Err(DatabaseError::NodeMissing {
                    node_key: source_node_key,
                });
            };

            // check that new copy name does not already exist
            let mut copy_counter: u32 = 0;
            let mut new_name: String = format!("{}_copy", &node.name);
            while self.get_node_by_name(&new_name).is_some() {
                new_name = format!("{}_copy{}", &node.name, copy_counter);
                copy_counter += 1;
            }
            let mut cloned: CanNode = node.clone();
            cloned.name = new_name;
            cloned
        };

        // Collect current relations to refresh after the insertion
        let messages_sent: Vec<CanMessageKey> = new_node.messages_sent.clone();
        let rx_signals: Vec<CanSignalKey> = new_node.rx_signals.clone();

        // Validate that related messages still exist
        for &msg_key in &messages_sent {
            if self.get_message_by_key(msg_key).is_none() {
                return Err(DatabaseError::MessageMissing {
                    message_key: msg_key,
                });
            }
        }

        // Gather signal/message pairs; ensure the message is still present
        let mut signal_message_pairs: Vec<(CanSignalKey, CanMessageKey)> =
            Vec::with_capacity(rx_signals.len());
        for &sig_key in &rx_signals {
            let Some(signal) = self.get_sig_by_key(sig_key) else {
                return Err(DatabaseError::SignalMissing {
                    signal_key: sig_key,
                });
            };
            if self.get_message_by_key(signal.message).is_none() {
                return Err(DatabaseError::MessageMissing {
                    message_key: signal.message,
                });
            }
            signal_message_pairs.push((sig_key, signal.message));
        }

        let new_name_lower = new_node.name.to_lowercase();
        let new_key: CanNodeKey = self.nodes.insert(new_node);
        self.nodes_order.push(new_key);
        self.node_key_by_name.insert(new_name_lower, new_key);

        // re-link messages_sent and tx_signals
        for msg_key in messages_sent {
            self.add_sender_relation(msg_key, new_key)?;
        }

        // re-link receivers for each signal (and aggregate at message level)
        for (sig_key, msg_key) in signal_message_pairs {
            {
                let Some(signal) = self.get_sig_by_key_mut(sig_key) else {
                    return Err(DatabaseError::SignalMissing {
                        signal_key: sig_key,
                    });
                };
                if !signal.receiver_nodes.contains(&new_key) {
                    signal.receiver_nodes.push(new_key);
                }
            }

            if let Some(message) = self.get_message_by_key_mut(msg_key) {
                if !message.receiver_nodes.contains(&new_key) {
                    message.receiver_nodes.push(new_key);
                }
            } else {
                return Err(DatabaseError::MessageMissing {
                    message_key: msg_key,
                });
            }
        }

        Ok(new_key)
    }

    /// Deletes the node identified by `node_key`, removing every reference across the database.
    pub fn delete_node(&mut self, node_key: CanNodeKey) -> Result<(), DatabaseError> {
        let removed_node: CanNode = self
            .nodes
            .remove(node_key)
            .ok_or(DatabaseError::NodeMissing { node_key })?;

        let node_name_lower: String = removed_node.name.to_lowercase();

        self.nodes_order.retain(|&k| k != node_key);
        self.node_key_by_name.remove(&node_name_lower);

        self.bu_sg_rel_attributes
            .retain(|(nk, _), _| *nk != node_key);
        self.bu_bo_rel_attributes
            .retain(|(nk, _), _| *nk != node_key);

        for (_msg_key, message) in self.messages.iter_mut() {
            message.sender_nodes.retain(|&nk| nk != node_key);
            message.receiver_nodes.retain(|&nk| nk != node_key);
        }

        for (_sig_key, signal) in self.signals.iter_mut() {
            signal.receiver_nodes.retain(|&nk| nk != node_key);
        }

        Ok(())
    }

    /// Looks up the `CanNodeKey` for a given node name (case-insensitive).
    pub fn get_node_key_by_name(&self, name: &str) -> Option<CanNodeKey> {
        self.node_key_by_name.get(&name.to_lowercase()).copied()
    }

    /// Returns an immutable reference to the node addressed by the supplied key.
    pub fn get_node_by_key(&self, key: CanNodeKey) -> Option<&CanNode> {
        self.nodes.get(key)
    }

    /// Returns a mutable reference to the node addressed by the supplied key.
    pub fn get_node_by_key_mut(&mut self, key: CanNodeKey) -> Option<&mut CanNode> {
        self.nodes.get_mut(key)
    }

    /// Returns a `&CanNode` given the name (case-insensitive).
    pub fn get_node_by_name(&self, name: &str) -> Option<&CanNode> {
        let key: CanNodeKey = *self.node_key_by_name.get(&name.to_lowercase())?;
        self.get_node_by_key(key)
    }

    /// Returns a `&mut CanNode` given the name (case-insensitive).
    pub fn get_node_by_name_mut(&mut self, name: &str) -> Option<&mut CanNode> {
        let key: CanNodeKey = *self.node_key_by_name.get(&name.to_lowercase())?;
        self.get_node_by_key_mut(key)
    }

    // ------------- Messages ------------
    /// Adds a message, indexes its id/name and updates `current_msg` for upcoming SG_ rows.
    pub fn add_message(
        &mut self,
        name: &str,
        id: u32,
        byte_length: u16,
    ) -> Result<CanMessageKey, DatabaseError> {
        // check if message with provided name already exist
        if let Some(r) = self.get_msg_key_by_name(name) {
            self.current_msg = Some(r); // set found message as current_msg
            return Err(DatabaseError::MessageAlreadyExists {
                name: name.to_string(),
            });
        }

        // check if message with provided ID already exist
        if let Some(r) = self.get_msg_key_by_id(id) {
            self.current_msg = Some(r); // set found message as current_msg
            let id_hex: String = id_to_hex(id);
            return Err(DatabaseError::MessageIdAlreadyAssigned { id_hex });
        }

        let id_hex: String = id_to_hex(id).to_string();

        let id_format: IdFormat = if id > 2048 {
            IdFormat::Extended
        } else {
            IdFormat::Standard
        };

        let mut message: CanMessage = CanMessage {
            id_format,
            id,
            id_hex: id_hex.clone(),
            name: name.to_string(),
            byte_length,
            msgtype: if byte_length <= 8 {
                "CAN".into()
            } else {
                "CAN FD".into()
            },
            ..Default::default()
        };

        // add attribute with default value
        for (attr_name, spec) in self
            .attr_spec
            .iter()
            .filter(|(_, s)| s.type_of_object == AttrObject::Message)
        {
            message
                .attributes
                .insert(attr_name.clone(), spec.default.clone());
        }

        let msg_key: CanMessageKey = self.messages.insert(message);

        self.messages_order.push(msg_key);

        self.msg_key_by_id.insert(id, msg_key);
        self.msg_key_by_hex.insert(id_hex, msg_key);
        self.msg_key_by_name.insert(name.to_lowercase(), msg_key);

        self.current_msg = Some(msg_key); // set created message as current_msg
        Ok(msg_key)
    }

    /// Deletes the Message identified by `msg_key`, removing every reference across the database.
    pub fn delete_message(&mut self, msg_key: CanMessageKey) -> Result<(), DatabaseError> {
        let removed_msg: CanMessage =
            self.messages
                .remove(msg_key)
                .ok_or(DatabaseError::MessageMissing {
                    message_key: msg_key,
                })?;

        let msg_name_lower: String = removed_msg.name.to_lowercase();

        self.messages_order.retain(|&k| k != msg_key);
        self.msg_key_by_name.remove(&msg_name_lower);

        self.bu_bo_rel_attributes
            .retain(|(_, mk), _| *mk != msg_key);

        // remove the Message from the Nodes.messages_sent
        // remove associate Signals from Node.tx_signals
        for (_node_key, node) in self.nodes.iter_mut() {
            node.messages_sent.retain(|&mk| mk != msg_key);
            for sig_key in &removed_msg.signals {
                node.tx_signals.retain(|&sk| sk != *sig_key);
            }
        }

        // remove the Message from the signal.message
        for (_sig_key, signal) in self.signals.iter_mut() {
            if signal.message == msg_key {
                signal.message = CanMessageKey::default();
            }
        }

        Ok(())
    }

    /// Create a new Message from an existing one adding "_copy" to the name and +1 to ID.
    /// Inside Signals will be copied too.
    pub fn copy_message(
        &mut self,
        source_msg_key: CanMessageKey,
    ) -> Result<CanMessageKey, DatabaseError> {
        // check that the source message key correspond to a Message
        let (src_name, src_id, src_byte_len, src_comment, src_attrs, src_sender_nodes, src_signals) = {
            let source_msg =
                self.get_message_by_key(source_msg_key)
                    .ok_or(DatabaseError::MessageMissing {
                        message_key: source_msg_key,
                    })?;
            (
                source_msg.name.clone(),
                source_msg.id,
                source_msg.byte_length,
                source_msg.comment.clone(),
                source_msg.attributes.clone(),
                source_msg.sender_nodes.clone(),
                source_msg.signals.clone(),
            )
        };

        // check that new copy name does not already exist
        let mut copy_counter: u32 = 0;
        let mut new_name: String = format!("{}_copy", &src_name);
        while self.get_message_by_name(&new_name).is_some() {
            new_name = format!("{}_copy{}", &src_name, copy_counter);
            copy_counter += 1;
        }

        // increment the id by 1 until it is not already existing
        let mut new_id: u32 = src_id + 1;
        while self.get_message_by_id(new_id).is_some() {
            new_id += 1;
        }

        let new_msg_key: CanMessageKey = self.add_message(&new_name, new_id, src_byte_len)?;
        let Some(new_msg) = self.get_message_by_key_mut(new_msg_key) else {
            return Err(DatabaseError::InconsistentState {
                details: "newly created message missing",
            });
        };

        // update comments and attributes
        new_msg.comment = src_comment;
        new_msg.attributes = src_attrs;

        // useful info from old_signals
        let useful_sig_info: Vec<(CanSignalKey, MuxRole, Option<MuxSelector>)> = src_signals
            .iter()
            .filter_map(|&old_sk| {
                let s = self.get_sig_by_key(old_sk)?;
                let role = s.mux_role;
                let sel = if role == MuxRole::Multiplexed {
                    Some(s.mux_selector.clone())
                } else {
                    None
                };
                Some((old_sk, role, sel))
            })
            .collect();

        // copy internal signals and attach them to new message
        for (old_sk, role, sel) in useful_sig_info {
            if let Ok(new_sk) = self.copy_signal(old_sk) {
                let _ = self.add_msg_sig_relation(new_sk, new_msg_key, role, sel.clone());
            }
        }

        // update Nodes.message_sent
        for node_key in src_sender_nodes {
            let _ = self.add_sender_relation(new_msg_key, node_key);
        }

        Ok(new_msg_key)
    }

    /// Looks up the `CanMessageKey` from a case-insensitive message name.
    pub fn get_msg_key_by_name(&self, name: &str) -> Option<CanMessageKey> {
        self.msg_key_by_name.get(&name.to_lowercase()).copied()
    }

    /// Looks up the `CanMessageKey` by numeric CAN identifier.
    pub fn get_msg_key_by_id(&self, id: u32) -> Option<CanMessageKey> {
        self.msg_key_by_id.get(&id).copied()
    }

    /// Looks up the `CanMessageKey` by hexadecimal CAN identifier.
    pub fn get_msg_key_by_id_hex(&self, id_hex: &str) -> Option<CanMessageKey> {
        // let key: String = normalize_id_hex(id_hex); // "0x...UPPERCASE"
        self.msg_key_by_hex.get(id_hex).copied()
    }

    /// Returns an immutable reference to a message given its key.
    pub fn get_message_by_key(&self, key: CanMessageKey) -> Option<&CanMessage> {
        self.messages.get(key)
    }

    /// Returns a mutable reference to a message given its key.
    pub fn get_message_by_key_mut(&mut self, key: CanMessageKey) -> Option<&mut CanMessage> {
        self.messages.get_mut(key)
    }

    /// Returns a `&CanMessage` given the numeric CAN ID.
    pub fn get_message_by_id(&self, id: u32) -> Option<&CanMessage> {
        let key: CanMessageKey = self.get_msg_key_by_id(id)?;
        self.get_message_by_key(key)
    }

    /// Returns a `&mut CanMessage` given the numeric CAN ID.
    pub fn get_message_by_id_mut(&mut self, id: u32) -> Option<&mut CanMessage> {
        let key: CanMessageKey = self.get_msg_key_by_id(id)?;
        self.get_message_by_key_mut(key)
    }

    /// Returns a `&CanMessage` given a hexadecimal ID (case-insensitive).
    ///
    /// The argument may come in various forms, e.g., `"12dd54e3"`, `"0x12dd54e3"`, `"12DD54E3x"`;
    /// it will be normalized internally to `"0x12DD54E3"`.
    pub fn get_message_by_id_hex(&self, id_hex: &str) -> Option<&CanMessage> {
        let key: CanMessageKey = self.get_msg_key_by_id_hex(id_hex)?;
        self.get_message_by_key(key)
    }

    /// Returns a `&mut CanMessage` given a hexadecimal ID (case-insensitive).
    pub fn get_message_by_id_hex_mut(&mut self, id_hex: &str) -> Option<&mut CanMessage> {
        let key: CanMessageKey = self.get_msg_key_by_id_hex(id_hex)?;
        self.get_message_by_key_mut(key)
    }

    /// Returns a `&CanMessage` given the name (case-insensitive).
    pub fn get_message_by_name(&self, name: &str) -> Option<&CanMessage> {
        let key: CanMessageKey = self.get_msg_key_by_name(name)?;
        self.get_message_by_key(key)
    }

    /// Returns a `&mut CanMessage` given the name (case-insensitive).
    pub fn get_message_by_name_mut(&mut self, name: &str) -> Option<&mut CanMessage> {
        let key: CanMessageKey = self.get_msg_key_by_name(name)?;
        self.get_message_by_key_mut(key)
    }

    // -------------- Signals ------------
    /// Adds a signal to the database and returns the corresponding `CanSignalKey`.
    #[allow(clippy::too_many_arguments)]
    pub fn add_signal(
        &mut self,
        name: &str,
        endian: Endianness,
        sign: Signess,
        factor: f64,
        offset: f64,
        min: f64,
        max: f64,
        unit: &str,
    ) -> CanSignalKey {
        let mut sig: CanSignal = CanSignal {
            name: name.to_string(),
            endian,
            sign,
            factor,
            offset,
            min,
            max,
            unit_of_measurement: unit.to_string(),
            ..Default::default()
        };
        sig.compile_inline();

        // add attribute with default value
        for (attr_name, spec) in self
            .attr_spec
            .iter()
            .filter(|(_, s)| s.type_of_object == AttrObject::Signal)
        {
            sig.attributes
                .insert(attr_name.clone(), spec.default.clone());
        }

        let sig_key: CanSignalKey = self.signals.insert(sig);
        self.signals_order.push(sig_key);
        self.sig_key_by_name.insert(name.to_lowercase(), sig_key);

        sig_key
    }

    /// Deletes the Signal identified by `sig_key`, removing every reference across the database.
    pub fn delete_signal(&mut self, sig_key: CanSignalKey) -> Result<(), DatabaseError> {
        let removed_sig: CanSignal =
            self.signals
                .remove(sig_key)
                .ok_or(DatabaseError::SignalMissing {
                    signal_key: sig_key,
                })?;

        let sig_name_lower: String = removed_sig.name.to_lowercase();

        self.signals_order.retain(|&k| k != sig_key);
        self.sig_key_by_name.remove(&sig_name_lower);

        self.bu_sg_rel_attributes
            .retain(|(_, sk), _| *sk != sig_key);

        // remove the Signal from the Node rx_signal and tx_signal
        for (_node_key, node) in self.nodes.iter_mut() {
            node.tx_signals.retain(|&sk| sk != sig_key);
            node.rx_signals.retain(|&sk| sk != sig_key);
        }

        // remove the Signal from the Message.signal
        for (_msg_key, message) in self.messages.iter_mut() {
            message.signals.retain(|&sk| sk != sig_key);
        }

        Ok(())
    }

    /// Associates an additional receiver node with an existing signal, keeping both sides in sync.
    pub fn add_sig_receiver_node(
        &mut self,
        sig_key: CanSignalKey,
        node_key: CanNodeKey,
    ) -> Result<(), DatabaseError> {
        let Some(signal) = self.get_sig_by_key_mut(sig_key) else {
            return Err(DatabaseError::SignalMissing {
                signal_key: sig_key,
            });
        };

        let msg_key: CanMessageKey = signal.message;

        // add the CanNodeKey to CanSignal if not already present
        if !signal.receiver_nodes.contains(&node_key) {
            signal.receiver_nodes.push(node_key);
        }

        let Some(node) = self.get_node_by_key_mut(node_key) else {
            return Err(DatabaseError::NodeMissing { node_key });
        };

        // add the CanSignalKey to CanNode if not already present
        if !node.rx_signals.contains(&sig_key) {
            node.rx_signals.push(sig_key);
        }

        // check that the CanMessage containing CanSignalKey contains CanNodeKey as receiver
        let Some(message) = self.get_message_by_key_mut(msg_key) else {
            return Err(DatabaseError::MessageMissing {
                message_key: msg_key,
            });
        };

        // add the CanNodeKey to CanMessage if not already present
        if !message.receiver_nodes.contains(&node_key) {
            message.receiver_nodes.push(node_key);
        }

        Ok(())
    }

    /// Remove a receiver node from an existing signal, keeping both sides in sync.
    pub fn remove_sig_receiver_node(
        &mut self,
        sig_key: CanSignalKey,
        node_key: CanNodeKey,
    ) -> Result<(), DatabaseError> {
        let Some(signal) = self.get_sig_by_key_mut(sig_key) else {
            return Err(DatabaseError::SignalMissing {
                signal_key: sig_key,
            });
        };

        let msg_key: CanMessageKey = signal.message;

        // remove the CanNodeKey from CanSignal.receiver_nodes
        signal.receiver_nodes.retain(|x| x != &node_key);

        let Some(node) = self.get_node_by_key_mut(node_key) else {
            return Err(DatabaseError::NodeMissing { node_key });
        };

        // remove the CanSignalKey from CanNode.rx_signals
        node.rx_signals.retain(|x| x != &sig_key);

        // check if the CanNodeKey still has some signal from the CanMessage
        let still_receives_any_from_msg: bool = {
            let Some(node) = self.get_node_by_key(node_key) else {
                return Err(DatabaseError::NodeMissing { node_key });
            };

            node.rx_signals.iter().copied().any(|sk| {
                self.get_sig_by_key(sk)
                    .map(|s| s.message == msg_key)
                    .unwrap_or(false)
            })
        };

        // if there are no more signals from that CanMessage, remove the CanNodeKey as receiver of it
        if !still_receives_any_from_msg {
            let Some(message) = self.get_message_by_key_mut(msg_key) else {
                return Err(DatabaseError::MessageMissing {
                    message_key: msg_key,
                });
            };
            message.receiver_nodes.retain(|x| x != &node_key);
        }

        Ok(())
    }

    /// Removes a single entry from a signal's value table (if present).
    pub fn remove_value_table_entry(
        &mut self,
        sig_key: CanSignalKey,
        entry: i32,
    ) -> Result<(), DatabaseError> {
        let Some(signal) = self.get_sig_by_key_mut(sig_key) else {
            return Err(DatabaseError::SignalMissing {
                signal_key: sig_key,
            });
        };

        if signal.value_table.remove(&entry).is_none() {
            return Err(DatabaseError::ValueTableEntryMissing {
                signal: signal.name.clone(),
                entry: format!("0x{:02X}", entry),
            });
        }

        Ok(())
    }

    /// Adds or replaces a value table entry for the given signal.
    pub fn add_value_table_entry(
        &mut self,
        sig_key: CanSignalKey,
        entry: i32,
        description: &str,
    ) -> Result<(), DatabaseError> {
        let Some(signal) = self.get_sig_by_key_mut(sig_key) else {
            return Err(DatabaseError::SignalMissing {
                signal_key: sig_key,
            });
        };

        if description.is_empty() {
            return Err(DatabaseError::ValueTableEntryDescriptionEmpty {
                signal: signal.name.clone(),
            });
        }

        if signal.value_table.contains_key(&entry) {
            return Err(DatabaseError::ValueTableEntryAlreadyExists {
                signal: signal.name.clone(),
                entry: format!("0x{:02X}", entry),
            });
        }

        signal.value_table.insert(entry, description.to_string());
        Ok(())
    }

    /// Binds a signal to a message, configuring its layout and multiplexing metadata.
    pub fn add_msg_sig_relation(
        &mut self,
        sig_key: CanSignalKey,
        msg_key: CanMessageKey,
        mux_role: MuxRole,
        mux_selector: Option<MuxSelector>,
    ) -> Result<CanSignalKey, DatabaseError> {
        // check if the CanSignal is already associated to a CanMessage
        let Some(signal) = self.get_sig_by_key(sig_key) else {
            return Err(DatabaseError::SignalMissing {
                signal_key: sig_key,
            });
        };
        let bit_start: u16 = signal.bit_start;
        let bit_length: u16 = signal.bit_length;
        if !signal.message.is_null() {
            let mkey: CanMessageKey = signal.message;
            let associated_with = if let Some(message) = self.get_message_by_key(mkey) {
                format!("message '{}' (ID {})", message.name, message.id_hex)
            } else {
                "an unknown message".to_string()
            };
            return Err(DatabaseError::SignalAlreadyAssociated {
                signal: signal.name.clone(),
                associated_with,
            });
        }

        // check if the signal bit_start and bit_length are not too big for Message.bytes_length
        let Some(message) = self.get_message_by_key(msg_key) else {
            return Err(DatabaseError::MessageMissing {
                message_key: msg_key,
            });
        };
        let dlc: u16 = message.byte_length;
        let endianness: Endianness = signal.endian.clone();
        message_layout::check_signal_fits(dlc, bit_start, bit_length, endianness)?;

        // if CanSignal is Multiplexed, try to guess the Multiplexor if there is only one in the message
        let inferred_switch: Option<CanSignalKey> = if mux_role == MuxRole::Multiplexed {
            self.get_message_by_key(msg_key).and_then(|msg| {
                if msg.mux_multiplexors.len() == 1 {
                    Some(msg.mux_multiplexors[0])
                } else {
                    None
                }
            })
        } else {
            None
        };

        // We'll need receiver_nodes later to aggregate into CanMessage.receiver_nodes
        let msg_receivers: Vec<CanNodeKey> = {
            let Some(signal) = self.get_sig_by_key_mut(sig_key) else {
                return Err(DatabaseError::SignalMissing {
                    signal_key: sig_key,
                });
            };

            // update relevant signal fields
            signal.message = msg_key;
            signal.bit_start = bit_start;
            signal.bit_length = bit_length;
            signal.mux_role = mux_role;
            signal.mux_group = 0;
            signal.mux_switch = if mux_role == MuxRole::Multiplexed {
                inferred_switch
            } else {
                None
            };
            signal.mux_selector = mux_selector.clone().unwrap_or_default();

            signal.steps.clear();
            signal.compile_inline();

            signal.receiver_nodes.clone()
        };

        {
            let Some(message) = self.get_message_by_key_mut(msg_key) else {
                return Err(DatabaseError::MessageMissing {
                    message_key: msg_key,
                });
            };

            // add the signal within current message
            if !message.signals.contains(&sig_key) {
                message.signals.push(sig_key);
            }

            // Aggregate receivers at message level (union of all signal receivers)
            for nk in &msg_receivers {
                if !message.receiver_nodes.contains(nk) {
                    message.receiver_nodes.push(*nk);
                }
            }
        }

        // Also back-link: for each sender node of this message, mark this signal as sent
        // This keeps CanNode.tx_signals consistent when the transmitter is specified on BO_
        // and SG_ lines are parsed afterwards (common case without BO_TX_BU_ lines).
        let sender_nodes: Vec<CanNodeKey> = self
            .get_message_by_key(msg_key)
            .map(|m| m.sender_nodes.clone())
            .unwrap_or_default();
        for nk in sender_nodes {
            if let Some(node) = self.get_node_by_key_mut(nk)
                && !node.tx_signals.contains(&sig_key)
            {
                node.tx_signals.push(sig_key);
            }
        }

        // --- update message multiplexing info ---
        match mux_role {
            MuxRole::None => { /* Nothing to do */ }
            MuxRole::Multiplexor => {
                // Register the Multiplexor inside proper message list
                if let Some(m) = self.get_message_by_key_mut(msg_key)
                    && !m.mux_multiplexors.contains(&sig_key)
                {
                    m.mux_multiplexors.push(sig_key);
                }

                // link dependant signals with no Multiplexor yet to this new Multiplexor
                // Usually, this should never happen because Multiplexor must always be first line in a message
                let dep_to_attach: Vec<(CanSignalKey, MuxSelector)> = {
                    let Some(msg) = self.get_message_by_key(msg_key) else {
                        return Err(DatabaseError::MessageMissingDuringMultiplexing);
                    };
                    msg.signals
                        .iter()
                        .copied()
                        .filter_map(|sk| {
                            let s: &CanSignal = self.get_sig_by_key(sk)?;
                            if s.mux_role == MuxRole::Multiplexed && s.mux_switch.is_none() {
                                Some((sk, s.mux_selector.clone()))
                            } else {
                                None
                            }
                        })
                        .collect()
                };

                // Update the signals and the mux_cases
                for (sk, sel) in dep_to_attach {
                    // set the Multiplexor to the signal
                    if let Some(s) = self.get_sig_by_key_mut(sk)
                        && s.mux_role == MuxRole::Multiplexed
                        && s.mux_switch.is_none()
                    {
                        s.mux_switch = Some(sig_key);
                    }

                    // Update the map of the message
                    if let Some(m) = self.get_message_by_key_mut(msg_key) {
                        let by_sel = m.mux_cases.entry(sig_key).or_default();
                        by_sel.entry(sel.clone()).or_default().push(sk);
                    }
                }
            }
            MuxRole::Multiplexed => {
                if let Some(sw) = inferred_switch
                    && let Some(m) = self.get_message_by_key_mut(msg_key)
                {
                    let by_sel = m.mux_cases.entry(sw).or_default();
                    if let Some(sel) = mux_selector.clone() {
                        by_sel.entry(sel).or_default().push(sig_key);
                    }
                }
            }
        }

        Ok(sig_key)
    }

    /// Detaches a signal from a message, reversing [`Self::add_msg_sig_relation`].
    pub fn remove_msg_sig_relation(
        &mut self,
        sig_key: CanSignalKey,
        msg_key: CanMessageKey,
    ) -> Result<(), DatabaseError> {
        // Ensure the message exists.
        self.get_message_by_key(msg_key)
            .ok_or(DatabaseError::MessageMissing {
                message_key: msg_key,
            })?;

        // Snapshot the signal state and verify that it is bound to the target message.
        let mux_snapshot: Option<(MuxRole, Option<CanSignalKey>, MuxSelector)> = {
            let signal = self
                .get_sig_by_key(sig_key)
                .ok_or(DatabaseError::SignalMissing {
                    signal_key: sig_key,
                })?;
            if signal.message.is_null() {
                return Err(DatabaseError::InconsistentState {
                    details: "Signal is not associated with any message",
                });
            }
            if signal.message != msg_key {
                let associated_with = if let Some(message) = self.get_message_by_key(signal.message)
                {
                    format!("Message '{}' (ID {})", message.name, message.id_hex)
                } else {
                    "An unknown message".to_string()
                };
                return Err(DatabaseError::SignalAlreadyAssociated {
                    signal: signal.name.clone(),
                    associated_with,
                });
            }
            let role = signal.mux_role;
            if role == MuxRole::None {
                None
            } else {
                Some((role, signal.mux_switch, signal.mux_selector.clone()))
            }
        };

        let mut multiplexed_to_detach: Vec<CanSignalKey> = Vec::new();

        {
            let Some(message) = self.get_message_by_key_mut(msg_key) else {
                return Err(DatabaseError::MessageMissing {
                    message_key: msg_key,
                });
            };

            let before = message.signals.len();
            message.signals.retain(|&sk| sk != sig_key);
            if before == message.signals.len() {
                return Err(DatabaseError::InconsistentState {
                    details: "Signal not registered within the message.",
                });
            }

            if let Some((role, switch, _selector)) = &mux_snapshot {
                match role {
                    MuxRole::Multiplexor => {
                        message.mux_multiplexors.retain(|&mk| mk != sig_key);
                        if let Some(by_sel) = message.mux_cases.remove(&sig_key) {
                            for sigs in by_sel.values() {
                                multiplexed_to_detach.extend(sigs.iter().copied());
                            }
                        }
                    }
                    MuxRole::Multiplexed => {
                        if let Some(sw) = *switch
                            && let Some(by_sel) = message.mux_cases.get_mut(&sw)
                        {
                            by_sel.retain(|_, list| {
                                list.retain(|&sk| sk != sig_key);
                                !list.is_empty()
                            });
                            if by_sel.is_empty() {
                                message.mux_cases.remove(&sw);
                            }
                        }
                    }
                    MuxRole::None => {}
                }
            }
        }

        // Clear multiplexing switch references on dependents that previously pointed at this signal.
        for dep in multiplexed_to_detach {
            if let Some(sig) = self.get_sig_by_key_mut(dep)
                && sig.mux_role == MuxRole::Multiplexed
            {
                sig.mux_switch = None;
            }
        }

        // Reset the detached signal metadata.
        if let Some(signal) = self.get_sig_by_key_mut(sig_key) {
            signal.message = CanMessageKey::default();
            signal.mux_role = MuxRole::None;
            signal.mux_group = 0;
            signal.mux_switch = None;
            signal.mux_selector = MuxSelector::default();
        }

        // Remove the signal from every sender node's transmitted list.
        let sender_nodes: Vec<CanNodeKey> = self
            .get_message_by_key(msg_key)
            .map(|m| m.sender_nodes.clone())
            .unwrap_or_default();
        for nk in sender_nodes {
            if let Some(node) = self.get_node_by_key_mut(nk) {
                node.tx_signals.retain(|&sk| sk != sig_key);
            }
        }

        // Rebuild the receiver list for the message (union of the remaining signal receivers).
        let new_receivers: Vec<CanNodeKey> = if let Some(message) = self.get_message_by_key(msg_key) {
            let mut seen: HashSet<CanNodeKey> = HashSet::new();
            let mut ordered: Vec<CanNodeKey> = Vec::new();
            for &sk in &message.signals {
                if let Some(sig) = self.get_sig_by_key(sk) {
                    for &nk in &sig.receiver_nodes {
                        if seen.insert(nk) {
                            ordered.push(nk);
                        }
                    }
                }
            }
            ordered
        } else {
            Vec::new()
        };

        if let Some(message) = self.get_message_by_key_mut(msg_key) {
            message.receiver_nodes = new_receivers;
        }

        Ok(())
    }

    /// Create a new Signal from an existing one adding "_copy" to the name.
    pub fn copy_signal(&mut self, source_sig_key: CanSignalKey) -> Result<CanSignalKey, DatabaseError> {
        // check that the source node key correspond to a Node
        let (
            src_name,
            src_endian,
            src_sign,
            src_factor,
            src_offset,
            src_min,
            src_max,
            src_unit,
            src_value_table,
            src_receivers,
            bit_start,
            bit_length,
            src_comment,
            src_attrs,
        ) = {
            let s = self
                .get_sig_by_key(source_sig_key)
                .ok_or(DatabaseError::SignalMissing {
                    signal_key: source_sig_key,
                })?;
            (
                s.name.clone(),
                s.endian.clone(),
                s.sign.clone(),
                s.factor,
                s.offset,
                s.min,
                s.max,
                s.unit_of_measurement.clone(),
                s.value_table.clone(),
                s.receiver_nodes.clone(),
                s.bit_start,
                s.bit_length,
                s.comment.clone(),
                s.attributes.clone(),
            )
        }; // <-- fine borrow immutabile

        // check that new copy name does not already exist
        let mut copy_counter: u32 = 0;
        let mut new_name: String = format!("{}_copy", &src_name);
        while self.get_signal_by_name(&new_name).is_some() {
            new_name = format!("{}_copy{}", &src_name, copy_counter);
            copy_counter += 1;
        }

        let new_sig_key: CanSignalKey = self.add_signal(
            &new_name, src_endian, src_sign, src_factor, src_offset, src_min, src_max, &src_unit,
        );
        {
            let Some(new_sig) = self.get_sig_by_key_mut(new_sig_key) else {
                return Err(DatabaseError::InconsistentState {
                    details: "newly created signal missing",
                });
            };

            // update comments and attributes
            new_sig.comment = src_comment;
            new_sig.attributes = src_attrs;
            new_sig.value_table = src_value_table;
            new_sig.bit_length = bit_length;
            new_sig.bit_start = bit_start;

            for node_key in src_receivers {
                let _ = self.add_sig_receiver_node(new_sig_key, node_key);
            }
        }

        Ok(new_sig_key)
    }

    /// Returns `true` if the signal exists and is bound to a message.
    pub fn signal_has_message(&self, signal_key: CanSignalKey) -> bool {
        self.get_sig_by_key(signal_key)
            .map(|sig| !sig.message.is_null())
            .unwrap_or(false)
    }

    /// Looks up the `CanSignalKey` for a case-insensitive signal name.
    pub fn get_sig_key_by_name(&self, name: &str) -> Option<CanSignalKey> {
        self.sig_key_by_name.get(&name.to_lowercase()).copied()
    }

    /// Returns an immutable reference to a signal given its key.
    pub fn get_sig_by_key(&self, key: CanSignalKey) -> Option<&CanSignal> {
        self.signals.get(key)
    }

    /// Returns a mutable reference to a signal given its key.
    pub fn get_sig_by_key_mut(&mut self, key: CanSignalKey) -> Option<&mut CanSignal> {
        self.signals.get_mut(key)
    }

    /// Returns a `&CanSignal` given the name (case-insensitive).
    pub fn get_signal_by_name(&self, name: &str) -> Option<&CanSignal> {
        let key: CanSignalKey = *self.sig_key_by_name.get(&name.to_lowercase())?;
        self.get_sig_by_key(key)
    }

    /// Returns a `&mut CanSignal` given the name (case-insensitive).
    pub fn get_signal_by_name_mut(&mut self, name: &str) -> Option<&mut CanSignal> {
        let key: CanSignalKey = *self.sig_key_by_name.get(&name.to_lowercase())?;
        self.get_sig_by_key_mut(key)
    }

    // -------------- Immutable Iterators ---------------
    /// Iterator according to the orders (defualt order is name based)
    pub fn iter_nodes(&self) -> impl Iterator<Item = &CanNode> + '_ {
        self.nodes_order.iter().filter_map(|&k| self.nodes.get(k))
    }
    /// Iterate messages following `messages_order`. If empty, insertion order is used.
    pub fn iter_messages(&self) -> impl Iterator<Item = &CanMessage> + '_ {
        self.messages_order
            .iter()
            .filter_map(|&k| self.messages.get(k))
    }
    /// Iterate signals following `signals_order`. If empty, insertion order is used.
    pub fn iter_signals(&self) -> impl Iterator<Item = &CanSignal> + '_ {
        self.signals_order
            .iter()
            .filter_map(|&k| self.signals.get(k))
    }

    // -------------- Mutable Closures ---------------
    /// Closure to edit all CanNode
    pub fn for_each_node_mut(&mut self, mut f: impl FnMut(&mut CanNode)) {
        let keys = self.nodes_order.clone(); // evitiamo borrow lungo su nodes_order
        for k in keys {
            if let Some(node) = self.nodes.get_mut(k) {
                f(node);
            }
        }
    }

    /// Closure to edit all CanMessage
    pub fn for_each_message_mut(&mut self, mut f: impl FnMut(&mut CanMessage)) {
        let keys = self.messages_order.clone();
        for k in keys {
            if let Some(msg) = self.messages.get_mut(k) {
                f(msg);
            }
        }
    }

    /// Closure to edit all CanSignal
    pub fn for_each_signal_mut(&mut self, mut f: impl FnMut(&mut CanSignal)) {
        let keys = self.signals_order.clone();
        for k in keys {
            if let Some(sig) = self.signals.get_mut(k) {
                f(sig);
            }
        }
    }

    // -------------- Attribute Definition ---------------
    /// Registers a new attribute specification on the database.
    pub fn add_attribute_definition(&mut self, spec: AttributeSpec) -> Result<(), DatabaseError> {
        if let Some(existing) = self.attr_spec.get(&spec.name)
            && existing.type_of_object == spec.type_of_object
        {
            return Err(DatabaseError::AttributeAlreadyExists {
                name: spec.name.clone(),
                scope: spec.type_of_object,
            });
        }

        let attr_name = spec.name.clone();
        let default_value = spec.default.clone();
        let scope = spec.type_of_object;

        self.attr_spec.insert(attr_name.clone(), spec);

        match scope {
            AttrObject::Database => {
                self.attributes.entry(attr_name).or_insert(default_value);
                CanDatabase::sort_attribute_map(&mut self.attributes);
            }
            AttrObject::Node => {
                let attr_name = attr_name.clone();
                let default_value = default_value.clone();
                self.for_each_node_mut(|node| {
                    node.attributes
                        .entry(attr_name.clone())
                        .or_insert_with(|| default_value.clone());
                });
                self.sort_all_node_fields();
            }
            AttrObject::Message => {
                let attr_name = attr_name.clone();
                let default_value = default_value.clone();
                self.for_each_message_mut(|message| {
                    message
                        .attributes
                        .entry(attr_name.clone())
                        .or_insert_with(|| default_value.clone());
                });
                self.sort_all_message_fields();
            }
            AttrObject::Signal => {
                let attr_name = attr_name.clone();
                let default_value = default_value.clone();
                self.for_each_signal_mut(|signal| {
                    signal
                        .attributes
                        .entry(attr_name.clone())
                        .or_insert_with(|| default_value.clone());
                });
                self.sort_all_signal_fields();
            }
        }

        Ok(())
    }

    /// Edit an already existing attribute
    pub fn edit_attribute_definition(
        &mut self,
        old_name: &str,
        old_object: &AttrObject,
        new_spec: &AttributeSpec,
    ) -> Result<(), DatabaseError> {
        if new_spec.type_of_object != *old_object {
            return Err(DatabaseError::AttributeObjectChanging);
        }

        let Some(current_spec) = self.attr_spec.get(old_name) else {
            return Err(DatabaseError::AttributeNotFound {
                name: old_name.to_string(),
                scope: *old_object,
            });
        };

        if current_spec.type_of_object != *old_object {
            return Err(DatabaseError::AttributeNotFound {
                name: old_name.to_string(),
                scope: *old_object,
            });
        }

        let new_name: String = new_spec.name.clone();

        if new_name != old_name {
            if let Some(existing) = self.attr_spec.get(&new_name)
                && existing.type_of_object == new_spec.type_of_object
            {
                return Err(DatabaseError::AttributeAlreadyExists {
                    name: new_name.clone(),
                    scope: new_spec.type_of_object,
                });
            }

            self.attr_spec.remove(old_name);
            self.attr_spec.insert(new_name.clone(), new_spec.clone());
        } else if let Some(stored_spec) = self.attr_spec.get_mut(old_name) {
            *stored_spec = new_spec.clone();
        }

        match *old_object {
            AttrObject::Database => {
                Self::reconcile_attribute_entry(&mut self.attributes, old_name, new_spec);
                CanDatabase::sort_attribute_map(&mut self.attributes);
            }
            AttrObject::Node => {
                self.for_each_node_mut(|node| {
                    Self::reconcile_attribute_entry(&mut node.attributes, old_name, new_spec);
                });
                self.sort_all_node_fields();
            }
            AttrObject::Message => {
                self.for_each_message_mut(|message| {
                    Self::reconcile_attribute_entry(&mut message.attributes, old_name, new_spec);
                });
                self.sort_all_message_fields();
            }
            AttrObject::Signal => {
                self.for_each_signal_mut(|signal| {
                    Self::reconcile_attribute_entry(&mut signal.attributes, old_name, new_spec);
                });
                self.sort_all_signal_fields();
            }
        }

        Ok(())
    }

    fn attribute_value_matches_spec(value: &AttributeValue, spec: &AttributeSpec) -> bool {
        match (value, spec.value_type) {
            (AttributeValue::Str(_), AttrValueType::String) => true,
            (AttributeValue::Int(v), AttrValueType::Int) => {
                spec.int_min.is_none_or(|min| *v >= min) && spec.int_max.is_none_or(|max| *v <= max)
            }
            (AttributeValue::Hex(v), AttrValueType::Hex) => {
                spec.hex_min.is_none_or(|min| *v >= min) && spec.hex_max.is_none_or(|max| *v <= max)
            }
            (AttributeValue::Float(v), AttrValueType::Float) => {
                spec.float_min.is_none_or(|min| *v >= min)
                    && spec.float_max.is_none_or(|max| *v <= max)
            }
            (AttributeValue::Enum(v), AttrValueType::Enum) => {
                spec.enum_values.iter().any(|entry| entry == v)
            }
            _ => false,
        }
    }

    fn reconcile_attribute_entry(
        map: &mut BTreeMap<String, AttributeValue>,
        old_name: &str,
        spec: &AttributeSpec,
    ) {
        if old_name == spec.name {
            match map.get_mut(old_name) {
                Some(value) => {
                    if !Self::attribute_value_matches_spec(value, spec) {
                        *value = spec.default.clone();
                    }
                }
                None => {
                    map.insert(spec.name.clone(), spec.default.clone());
                }
            }
            return;
        }

        let default_value = spec.default.clone();
        let new_name = spec.name.clone();
        let candidate = map
            .remove(old_name)
            .or_else(|| map.remove(new_name.as_str()));
        let mut updated = candidate.unwrap_or_else(|| default_value.clone());
        if !Self::attribute_value_matches_spec(&updated, spec) {
            updated = default_value;
        }
        map.insert(new_name, updated);
    }

    /// Removes an attribute specification and clears it from all matching entities.
    pub fn delete_attribute_definition(
        &mut self,
        name: &str,
        type_of_object: &AttrObject,
    ) -> Result<(), DatabaseError> {
        let Some(spec) = self.attr_spec.get(name) else {
            return Err(DatabaseError::AttributeNotFound {
                name: name.to_string(),
                scope: *type_of_object,
            });
        };

        if spec.type_of_object != *type_of_object {
            return Err(DatabaseError::AttributeNotFound {
                name: name.to_string(),
                scope: *type_of_object,
            });
        }

        self.attr_spec.remove(name);

        match *type_of_object {
            AttrObject::Database => {
                self.attributes.remove(name);
            }
            AttrObject::Node => {
                self.for_each_node_mut(|node| {
                    node.attributes.remove(name);
                });
            }
            AttrObject::Message => {
                self.for_each_message_mut(|message| {
                    message.attributes.remove(name);
                });
            }
            AttrObject::Signal => {
                self.for_each_signal_mut(|signal| {
                    signal.attributes.remove(name);
                });
            }
        }

        Ok(())
    }

    // -------------- Sorting ---------------
    /// Sort nodes_by_name case insensitive
    pub fn sort_db_nodes_by_name(&mut self) {
        self.nodes_order
            .sort_by_cached_key(|&k| self.nodes.get(k).map(|n| n.name.to_ascii_lowercase()));
    }

    /// Sort messages_by_name case insensitive
    pub fn sort_db_messages_by_name(&mut self) {
        self.messages_order
            .sort_by_cached_key(|&k| self.messages.get(k).map(|m| m.name.to_ascii_lowercase()));
    }

    /// Sort signals_by_name case insensitive
    pub fn sort_db_signals_by_name(&mut self) {
        self.signals_order
            .sort_by_cached_key(|&k| self.signals.get(k).map(|s| s.name.to_ascii_lowercase()));
    }

    /// Sort `messages_sent`, `tx_signals` and `rx_signals` inside the specific given CanNode
    /// by the target names (ASCII case-insensitive).
    pub fn sort_node_fields(&mut self, node_key: CanNodeKey) {
        // Compute the new order on immutable borrows
        let (sorted_msgs, sorted_sigs_sent, sorted_sigs_received) = {
            let Some(node) = self.get_node_by_key(node_key) else {
                return;
            };

            // messages_sent -> by CanMessage.name
            let mut ms: Vec<CanMessageKey> = node.messages_sent.clone();
            ms.sort_by_cached_key(|&mk| {
                self.get_message_by_key(mk)
                    .map(|m| m.name.to_ascii_lowercase())
                    .unwrap_or_default()
            });

            // tx_signals -> by CanSignal.name
            let mut sr1: Vec<CanSignalKey> = node.tx_signals.clone();
            sr1.sort_by_cached_key(|&sk| {
                self.get_sig_by_key(sk)
                    .map(|s| s.name.to_ascii_lowercase())
                    .unwrap_or_default()
            });

            // rx_signals -> by CanSignal.name
            let mut sr2: Vec<CanSignalKey> = node.rx_signals.clone();
            sr2.sort_by_cached_key(|&sk| {
                self.get_sig_by_key(sk)
                    .map(|s| s.name.to_ascii_lowercase())
                    .unwrap_or_default()
            });

            (ms, sr1, sr2)
        };

        // Write back with a mutable borrow
        if let Some(node) = self.get_node_by_key_mut(node_key) {
            node.messages_sent = sorted_msgs;
            node.tx_signals = sorted_sigs_sent;
            node.rx_signals = sorted_sigs_received;
            Self::sort_attribute_map(&mut node.attributes);
        }
    }

    /// Sort `sender_nodes` and `signals` inside the specific given CanMessage
    /// by the target names (ASCII case-insensitive).
    pub fn sort_message_fields(&mut self, msg_key: CanMessageKey) {
        let (sorted_senders, sorted_sigs, sorted_receivers) = {
            let Some(msg) = self.get_message_by_key(msg_key) else {
                return;
            };

            // sender_nodes -> by CanNode.name
            let mut ns: Vec<CanNodeKey> = msg.sender_nodes.clone();
            ns.sort_by_cached_key(|&nk| {
                self.get_node_by_key(nk)
                    .map(|n| n.name.to_ascii_lowercase())
                    .unwrap_or_default()
            });

            // receiver_nodes -> by CanNode.name
            let mut rn: Vec<CanNodeKey> = msg.receiver_nodes.clone();
            rn.sort_by_cached_key(|&nk| {
                self.get_node_by_key(nk)
                    .map(|n| n.name.to_ascii_lowercase())
                    .unwrap_or_default()
            });

            // signals -> by CanSignal.name
            let mut ss: Vec<CanSignalKey> = msg.signals.clone();
            ss.sort_by_cached_key(|&sk| {
                self.get_sig_by_key(sk)
                    .map(|s| s.name.to_ascii_lowercase())
                    .unwrap_or_default()
            });

            (ns, ss, rn)
        };

        if let Some(msg) = self.get_message_by_key_mut(msg_key) {
            msg.sender_nodes = sorted_senders;
            msg.signals = sorted_sigs;
            msg.receiver_nodes = sorted_receivers;
            Self::sort_attribute_map(&mut msg.attributes);
        }
    }

    /// Sort `receiver_nodes` inside the specific given CanSignal
    /// by the target names (ASCII case-insensitive).
    pub fn sort_signal_fields(&mut self, sig_key: CanSignalKey) {
        let sorted_nodes: Vec<CanNodeKey> = {
            let Some(sig) = self.get_sig_by_key(sig_key) else {
                return;
            };

            // receiver_nodes -> by CanNode.name
            let mut ns: Vec<CanNodeKey> = sig.receiver_nodes.clone();
            ns.sort_by_key(|&nk| {
                self.get_node_by_key(nk)
                    .map(|n| n.name.to_ascii_lowercase())
                    .unwrap_or_default()
            });

            ns
        };

        if let Some(sig) = self.get_sig_by_key_mut(sig_key) {
            sig.receiver_nodes = sorted_nodes;
            Self::sort_attribute_map(&mut sig.attributes);
        }
    }

    /// Sorts an attribute map using case-insensitive keys with ASCII tie-breaking.
    pub fn sort_attribute_map(map: &mut BTreeMap<String, AttributeValue>) {
        let mut entries: Vec<_> = map.iter().map(|(k, v)| (k.clone(), v.clone())).collect();
        entries.sort_by(|(ka, _), (kb, _)| {
            let lower_cmp = ka.to_ascii_lowercase().cmp(&kb.to_ascii_lowercase());
            if lower_cmp == std::cmp::Ordering::Equal {
                ka.cmp(kb)
            } else {
                lower_cmp
            }
        });
        map.clear();
        map.extend(entries);
    }

    /// For ALL CanNode entries, sort:
    /// - `messages_sent`  by the target CanMessage.name (ASCII case-insensitive)
    /// - `tx_signals`  by the target CanMessage.name (ASCII case-insensitive)
    /// - `rx_signals`   by the target CanSignal.name  (ASCII case-insensitive)
    ///
    /// Missing/invalid keys are pushed to the end; ties are broken by the key for determinism.
    pub fn sort_all_node_fields(&mut self) {
        // Build write plans using only immutable borrows (avoids borrow conflicts).
        let plans: Vec<NodePlan> = self
            .nodes
            .iter()
            .map(|(nk, node)| {
                // messages_sent -> sort by message name (case-insensitive)
                let mut ms: Vec<CanMessageKey> = node.messages_sent.clone();
                ms.sort_by_cached_key(|&mk| {
                    let (missing, name) = match self.get_message_by_key(mk) {
                        Some(m) => (false, m.name.to_ascii_lowercase()),
                        None => (true, String::new()),
                    };
                    (missing, name, mk) // missing last, then by lowercase name, then key as tie-breaker
                });

                // tx_signals -> sort by signal name (case-insensitive)
                let mut sr1: Vec<CanSignalKey> = node.tx_signals.clone();
                sr1.sort_by_cached_key(|&sk| {
                    let (missing, name) = match self.get_sig_by_key(sk) {
                        Some(s) => (false, s.name.to_ascii_lowercase()),
                        None => (true, String::new()),
                    };
                    (missing, name, sk)
                });

                // rx_signals -> sort by signal name (case-insensitive)
                let mut sr2: Vec<CanSignalKey> = node.rx_signals.clone();
                sr2.sort_by_cached_key(|&sk| {
                    let (missing, name) = match self.get_sig_by_key(sk) {
                        Some(s) => (false, s.name.to_ascii_lowercase()),
                        None => (true, String::new()),
                    };
                    (missing, name, sk)
                });
                let mut attributes = node.attributes.clone();
                Self::sort_attribute_map(&mut attributes);
                NodePlan {
                    nk,
                    messages_sent: ms,
                    tx_signals: sr1,
                    rx_signals: sr2,
                    attributes,
                }
            })
            .collect();

        // Apply the plans with mutable borrows.
        for p in plans {
            if let Some(node) = self.get_node_by_key_mut(p.nk) {
                node.messages_sent = p.messages_sent;
                node.tx_signals = p.tx_signals;
                node.rx_signals = p.rx_signals;
                node.attributes = p.attributes;
            }
        }
    }

    /// For ALL CanMessage entries, sort:
    /// - `sender_nodes` by CanNode.name    (ASCII case-insensitive)
    /// - `signals`      by CanSignal.name  (ASCII case-insensitive)
    ///
    /// Missing/invalid keys are pushed to the end; ties are broken by the key.
    pub fn sort_all_message_fields(&mut self) {
        let plans: Vec<MessageFieldPlan> = self
            .messages
            .iter()
            .map(|(mk, msg)| {
                // sender_nodes -> sort by node name (case-insensitive)
                let mut ns = msg.sender_nodes.clone();
                ns.sort_by_cached_key(|&nk| {
                    let (missing, name) = match self.get_node_by_key(nk) {
                        Some(n) => (false, n.name.to_ascii_lowercase()),
                        None => (true, String::new()),
                    };
                    (missing, name, nk)
                });

                // receiver_nodes -> sort by node name (case-insensitive)
                let mut rn = msg.receiver_nodes.clone();
                rn.sort_by_cached_key(|&nk| {
                    let (missing, name) = match self.get_node_by_key(nk) {
                        Some(n) => (false, n.name.to_ascii_lowercase()),
                        None => (true, String::new()),
                    };
                    (missing, name, nk)
                });

                // signals -> sort by signal name (case-insensitive)
                let mut ss = msg.signals.clone();
                ss.sort_by_cached_key(|&sk| {
                    let (missing, name) = match self.get_sig_by_key(sk) {
                        Some(s) => (false, s.name.to_ascii_lowercase()),
                        None => (true, String::new()),
                    };
                    (missing, name, sk)
                });
                let mut attributes = msg.attributes.clone();
                Self::sort_attribute_map(&mut attributes);

                (mk, ns, ss, rn, attributes)
            })
            .collect();

        for (mk, ns, ss, rn, attributes) in plans {
            if let Some(msg) = self.get_message_by_key_mut(mk) {
                msg.sender_nodes = ns;
                msg.signals = ss;
                msg.receiver_nodes = rn;
                msg.attributes = attributes;
            }
        }
    }

    /// For ALL CanSignal entries, sort:
    /// - `receiver_nodes` by CanNode.name (ASCII case-insensitive)
    ///
    /// Missing/invalid keys are pushed to the end; ties are broken by the key.
    pub fn sort_all_signal_fields(&mut self) {
        let plans: Vec<(CanSignalKey, Vec<CanNodeKey>, BTreeMap<String, AttributeValue>)> = self
            .signals
            .iter()
            .map(|(sk, sig)| {
                let mut ns = sig.receiver_nodes.clone();
                ns.sort_by_cached_key(|&nk| {
                    let (missing, name) = match self.get_node_by_key(nk) {
                        Some(n) => (false, n.name.to_ascii_lowercase()),
                        None => (true, String::new()),
                    };
                    (missing, name, nk)
                });
                let mut attributes = sig.attributes.clone();
                Self::sort_attribute_map(&mut attributes);
                (sk, ns, attributes)
            })
            .collect();

        for (sk, ns, attributes) in plans {
            if let Some(sig) = self.get_sig_by_key_mut(sk) {
                sig.receiver_nodes = ns;
                sig.attributes = attributes;
            }
        }
    }

    /// Resets the entire database to an empty state (drops nodes, messages, signals, and metadata).
    pub fn clear(&mut self) {
        *self = CanDatabase::default();
    }
}

/// Bus type for a DBC-backed database.
#[derive(Default, Clone, PartialEq, Debug)]
pub enum BusType {
    #[default]
    Can,
    CanFd,
}

impl BusType {
    /// Returns a display-friendly label (allocates a new `String`).
    pub fn to_str(&self) -> String {
        match self {
            BusType::Can => "CAN".to_string(),
            BusType::CanFd => "CAN FD".to_string(),
        }
    }
}

// suport struct for node parsing
#[derive(Debug, Clone)]
struct NodePlan {
    nk: CanNodeKey,
    messages_sent: Vec<CanMessageKey>,
    tx_signals: Vec<CanSignalKey>,
    rx_signals: Vec<CanSignalKey>,
    attributes: BTreeMap<String, AttributeValue>,
}

/// Type alias to simplify clippy::type_complexity for message sorting plans.
type MessageFieldPlan = (
    CanMessageKey,
    Vec<CanNodeKey>,
    Vec<CanSignalKey>,
    Vec<CanNodeKey>,
    BTreeMap<String, AttributeValue>,
);

const CAN_EFF_MASK: u32 = 0x1FFF_FFFF; // 29 bit
const CAN_SFF_MASK: u32 = 0x0000_07FF; // 11 bit

#[inline]
pub fn id_to_hex(id: u32) -> String {
    if id <= CAN_SFF_MASK {
        format!("0x{:03X}", id)
    } else {
        format!("0x{:08X}", id & CAN_EFF_MASK)
    }
}