llvm-native-core-ext 0.1.0

//! LLVM Metadata — MDNode, NamedMDNode, DebugInfo, and metadata store.
//!
//! Clean-room behavioral reconstruction. Phase 2 — LLVM.IR.2 Court.
//!
//! @llvm_behavior: LLVM metadata is a hierarchical key-value system for
//! attaching non-code information to the IR. Metadata nodes form a DAG
//! (directed acyclic graph) of operands. Named metadata nodes (like
//! `!llvm.module.flags`) are module-level collections. Debug info
//! metadata (DICompileUnit, DIFile, DILocation, etc.) follows the
//! DWARF debug information model encoded as LLVM metadata.
//!
//! The metadata system supports:
//! - MetadataValue: a single metadata entry with a unique ID
//! - MetadataKind: the type of metadata (string, constant, node, etc.)
//! - MetadataStore: a central registry for all metadata in a module
//! - Debug info structs (DILocation, DIFile, etc.) for DWARF emission

use llvm_native_core::types::Type;

use std::collections::HashMap;

/// A constant value usable in metadata operands.
///
/// @llvm_behavior: Constants in metadata are immutable value expressions.
/// This mirrors `llvm::Constant` for metadata purposes.
#[derive(Debug, Clone)]
pub struct ConstantValue {
    pub ty: Type,
    pub repr: ConstantRepr,
}

/// Representation of a constant value.
#[derive(Debug, Clone)]
pub enum ConstantRepr {
    Int(i64),
    Float(f64),
    Null,
    Undef,
    Poison,
    String(String),
    ZeroInitializer,
}

impl ConstantValue {
    pub fn new_int(ty: Type, val: i64) -> Self {
        Self {
            ty,
            repr: ConstantRepr::Int(val),
        }
    }

    pub fn new_float(ty: Type, val: f64) -> Self {
        Self {
            ty,
            repr: ConstantRepr::Float(val),
        }
    }

    pub fn null(ty: Type) -> Self {
        Self {
            ty,
            repr: ConstantRepr::Null,
        }
    }

    pub fn to_string(&self) -> String {
        match &self.repr {
            ConstantRepr::Int(v) => format!("i{} {}", self.ty.integer_bit_width(), v),
            ConstantRepr::Float(v) => format!("{} {}", self.ty, v),
            ConstantRepr::Null => "null".to_string(),
            ConstantRepr::Undef => "undef".to_string(),
            ConstantRepr::Poison => "poison".to_string(),
            ConstantRepr::String(s) => format!("\"{}\"", s),
            ConstantRepr::ZeroInitializer => "zeroinitializer".to_string(),
        }
    }
}

/// A single metadata value with a unique ID and kind.
///
/// @llvm_behavior: Each metadata entry in LLVM has a unique numeric ID
/// (e.g., `!42`) and a kind that determines its structure. This is the
/// core metadata value type.
#[derive(Debug, Clone)]
pub struct MetadataValue {
    /// Unique identifier for this metadata.
    pub id: u32,
    /// The kind/semantics of this metadata.
    pub kind: MetadataKind,
}

/// The kind of a metadata value.
///
/// @llvm_behavior: Metadata can be a simple string, a constant, a
/// reference to another value, or a composite node (MDNode, MDTuple).
/// Distinct nodes are guaranteed unique even if structurally identical.
#[derive(Debug, Clone)]
pub enum MetadataKind {
    /// A plain metadata string (e.g., `!"hello"`).
    MDString(String),
    /// A constant value embedded in metadata.
    Constant(ConstantValue),
    /// A reference to an IR value (by index).
    Value(usize),
    /// A metadata node: an ordered list of metadata operands.
    MDNode(Vec<MetadataOperand>),
    /// A distinct metadata node: structurally unique, never merged.
    DistinctMDNode(Vec<MetadataOperand>),
    /// A metadata tuple: lightweight ordered collection.
    MDTuple(Vec<MetadataOperand>),
    /// A named metadata node: module-level name with operand metadata IDs.
    NamedNode(String, Vec<u32>),
}

/// An operand within a metadata node.
///
/// @llvm_behavior: Metadata operands can refer to other metadata by ID,
/// reference IR values directly, embed strings, or embed constants.
/// This mirrors `llvm::MDOperand`.
#[derive(Debug, Clone)]
pub enum MetadataOperand {
    /// Reference to another metadata by its ID (e.g., `!42`).
    Metadata(u32),
    /// Direct reference to an IR value (by index in the value table).
    Value(usize),
    /// An inline metadata string.
    MDString(String),
    /// An inline constant value.
    Constant(ConstantValue),
    /// A null metadata operand.
    Null,
}

impl MetadataOperand {
    /// Returns true if this is a metadata reference.
    pub fn is_metadata_ref(&self) -> bool {
        matches!(self, MetadataOperand::Metadata(_))
    }

    /// Returns the metadata ID if this is a metadata reference.
    pub fn as_metadata_id(&self) -> Option<u32> {
        match self {
            MetadataOperand::Metadata(id) => Some(*id),
            _ => None,
        }
    }

    /// Returns a debug string for this operand.
    pub fn to_debug_string(&self) -> String {
        match self {
            MetadataOperand::Metadata(id) => format!("!{}", id),
            MetadataOperand::Value(v) => format!("value(%{})", v),
            MetadataOperand::MDString(s) => format!("!\"{}\"", s),
            MetadataOperand::Constant(c) => c.to_string(),
            MetadataOperand::Null => "null".to_string(),
        }
    }
}

// ============================================================================
// Debug Info Metadata (DINode hierarchy)
// ============================================================================

/// A debug location: line, column, scope, and inlined-at information.
///
/// @llvm_behavior: `DILocation` maps to `!DILocation(...)` in LLVM IR.
/// It describes a specific point in source code and can chain via
/// `inlined_at` to represent inlined call stacks.
#[derive(Debug, Clone)]
pub struct DILocation {
    /// Source line number (1-based).
    pub line: u32,
    /// Source column number (1-based).
    pub column: u32,
    /// Metadata ID of the parent scope (DISubprogram, DILexicalBlock, etc.).
    pub scope: u32,
    /// Optional metadata ID of the inlined-at location.
    pub inlined_at: Option<u32>,
}

impl DILocation {
    pub fn new(line: u32, column: u32, scope: u32) -> Self {
        Self {
            line,
            column,
            scope,
            inlined_at: None,
        }
    }

    pub fn with_inlined_at(mut self, inlined_at: u32) -> Self {
        self.inlined_at = Some(inlined_at);
        self
    }
}

/// A debug info file descriptor.
///
/// @llvm_behavior: `DIFile` maps to `!DIFile(...)` in LLVM IR, containing
/// the filename and directory path of a source file.
#[derive(Debug, Clone)]
pub struct DIFile {
    /// The source filename (e.g., `"main.c"`).
    pub filename: String,
    /// The directory path containing the file (e.g., `"/home/user/src"`).
    pub directory: String,
    /// Optional checksum information.
    pub checksum_kind: Option<String>,
    pub checksum_value: Option<String>,
    /// Optional source text (for embedded source).
    pub source: Option<String>,
}

impl DIFile {
    pub fn new(filename: String, directory: String) -> Self {
        Self {
            filename,
            directory,
            checksum_kind: None,
            checksum_value: None,
            source: None,
        }
    }

    /// Returns the full path by joining directory and filename.
    pub fn full_path(&self) -> String {
        if self.directory.is_empty() {
            self.filename.clone()
        } else {
            format!("{}/{}", self.directory, self.filename)
        }
    }
}

/// A debug info subprogram (function definition).
///
/// @llvm_behavior: `DISubprogram` maps to `!DISubprogram(...)` in LLVM IR.
/// It describes a function's debug information including name, file,
/// line number, and parent compilation unit.
#[derive(Debug, Clone)]
pub struct DISubprogram {
    /// The function name as it appears in source.
    pub name: String,
    /// Optional mangled/linkage name.
    pub linkage_name: Option<String>,
    /// Metadata ID of the DIFile where this function is defined.
    pub file: u32,
    /// Line number of the function definition.
    pub line: u32,
    /// Metadata ID of the parent DICompileUnit.
    pub unit: u32,
    /// Metadata ID of the subroutine type (signature).
    pub ty: Option<u32>,
    /// Metadata ID of the scope (parent scope).
    pub scope: Option<u32>,
    /// Whether this is a definition (vs. declaration).
    pub is_definition: bool,
    /// Whether this function is local to the compilation unit.
    pub is_local: bool,
    /// Whether this function is optimized.
    pub is_optimized: bool,
    /// Virtual index for virtual methods.
    pub virtual_index: Option<u32>,
    /// Flags (e.g., accessibility).
    pub flags: u32,
}

impl DISubprogram {
    pub fn new(name: String, file: u32, line: u32, unit: u32) -> Self {
        Self {
            name,
            linkage_name: None,
            file,
            line,
            unit,
            ty: None,
            scope: None,
            is_definition: true,
            is_local: false,
            is_optimized: false,
            virtual_index: None,
            flags: 0,
        }
    }
}

/// A debug info type descriptor.
///
/// @llvm_behavior: `DIType` maps to `!DIBasicType(...)` and `!DIDerivedType(...)`
/// in LLVM IR. It describes the size, alignment, offset, and encoding of a
/// source-level type.
#[derive(Debug, Clone)]
pub struct DIType {
    /// The type name (e.g., `"int"`, `"struct Foo"`).
    pub name: String,
    /// Size of the type in bits.
    pub size_in_bits: u64,
    /// Alignment of the type in bits.
    pub align_in_bits: u32,
    /// Offset in bits (for struct members, derived types).
    pub offset_in_bits: u64,
    /// DWARF encoding (e.g., DW_ATE_signed = 5).
    pub encoding: u32,
    /// Metadata ID of the base type (for derived types).
    pub base_type: Option<u32>,
    /// Metadata ID of the file where this type is defined.
    pub file: Option<u32>,
    /// Line number where this type is defined.
    pub line: Option<u32>,
    /// Tag identifying the type (e.g., DW_TAG_base_type = 36).
    pub tag: u32,
    /// Flags for the type.
    pub flags: u32,
}

impl DIType {
    pub fn new_basic(name: String, size_in_bits: u64, align_in_bits: u32, encoding: u32) -> Self {
        Self {
            name,
            size_in_bits,
            align_in_bits,
            offset_in_bits: 0,
            encoding,
            base_type: None,
            file: None,
            line: None,
            tag: 36, // DW_TAG_base_type
            flags: 0,
        }
    }

    /// Returns the size in bytes (rounded up).
    pub fn size_in_bytes(&self) -> u64 {
        (self.size_in_bits + 7) / 8
    }
}

/// A debug info local variable.
///
/// @llvm_behavior: `DILocalVariable` maps to `!DILocalVariable(...)` in
/// LLVM IR. It describes a local variable in a function scope, including
/// its name, type, and source location.
#[derive(Debug, Clone)]
pub struct DILocalVariable {
    /// The variable name.
    pub name: String,
    /// Metadata ID of the scope (DISubprogram or DILexicalBlock).
    pub scope: u32,
    /// Metadata ID of the file.
    pub file: u32,
    /// Line number of the variable declaration.
    pub line: u32,
    /// Metadata ID of the variable's type.
    pub var_type: u32,
    /// Argument number for function parameters (1-based).
    pub arg: Option<u32>,
    /// Flags for the variable.
    pub flags: u32,
    /// Alignment in bits.
    pub align_in_bits: u32,
}

impl DILocalVariable {
    pub fn new(name: String, scope: u32, file: u32, line: u32, var_type: u32) -> Self {
        Self {
            name,
            scope,
            file,
            line,
            var_type,
            arg: None,
            flags: 0,
            align_in_bits: 0,
        }
    }
}

/// A debug info global variable.
///
/// @llvm_behavior: `DIGlobalVariable` maps to `!DIGlobalVariable(...)` in
/// LLVM IR. It describes a global variable in a compilation unit.
#[derive(Debug, Clone)]
pub struct DIGlobalVariable {
    /// The variable name.
    pub name: String,
    /// Metadata ID of the scope (typically DICompileUnit).
    pub scope: u32,
    /// Metadata ID of the file where the variable is declared.
    pub file: u32,
    /// Line number of the declaration.
    pub line: u32,
    /// Metadata ID of the variable's type.
    pub var_type: u32,
    /// Whether the variable is local to the compilation unit.
    pub is_local_to_unit: bool,
    /// Whether this is a definition (vs. declaration).
    pub is_definition: bool,
    /// Metadata ID of the static member declaration.
    pub declaration: Option<u32>,
    /// Alignment in bits.
    pub align_in_bits: u32,
}

impl DIGlobalVariable {
    pub fn new(
        name: String,
        scope: u32,
        file: u32,
        line: u32,
        var_type: u32,
        is_local_to_unit: bool,
        is_definition: bool,
    ) -> Self {
        Self {
            name,
            scope,
            file,
            line,
            var_type,
            is_local_to_unit,
            is_definition,
            declaration: None,
            align_in_bits: 0,
        }
    }
}

/// A debug info compile unit (translation unit).
///
/// @llvm_behavior: `DICompileUnit` maps to `!DICompileUnit(...)` in LLVM
/// IR. It describes a compilation unit with language, producer, and
/// retained types.
#[derive(Debug, Clone)]
pub struct DICompileUnit {
    /// DWARF language identifier.
    pub language: u32,
    /// Metadata ID of the DIFile for this unit.
    pub file: u32,
    /// Producer string (e.g., `"clang version 18.0.0"`).
    pub producer: String,
    /// Whether the unit is optimized.
    pub is_optimized: bool,
    /// Compiler flags string.
    pub flags: String,
    /// Runtime version.
    pub runtime_version: u32,
    /// Split debug info filename.
    pub split_debug_filename: Option<String>,
    /// Emission kind (0 = FullDebug, 1 = LineTablesOnly, 2 = NoDebug).
    pub emission_kind: u32,
    /// List of metadata IDs for retained types.
    pub retained_types: Vec<u32>,
    /// List of metadata IDs for global variables.
    pub globals: Vec<u32>,
    /// List of metadata IDs for imported entities.
    pub imports: Vec<u32>,
}

impl DICompileUnit {
    pub fn new(language: u32, file: u32, producer: String) -> Self {
        Self {
            language,
            file,
            producer,
            is_optimized: false,
            flags: String::new(),
            runtime_version: 0,
            split_debug_filename: None,
            emission_kind: 0, // FullDebug
            retained_types: Vec::new(),
            globals: Vec::new(),
            imports: Vec::new(),
        }
    }
}

// ============================================================================
// Temporary MDNode state for deferred resolution
// ============================================================================

/// State tracking for a temporary metadata node.
///
/// @llvm_behavior: LLVM supports temporary MDNodes that can be created
/// before their operands are fully resolved, and later replaced with
/// resolved nodes via RAUW (Replace All Uses With).
#[derive(Debug, Clone)]
pub struct TemporaryNodeState {
    /// The operands of this temporary node.
    pub operands: Vec<MetadataOperand>,
    /// Whether this temporary node has been resolved.
    pub resolved: bool,
    /// The replacement metadata ID, if resolved.
    pub replacement: Option<u32>,
}

impl TemporaryNodeState {
    pub fn new(operands: Vec<MetadataOperand>) -> Self {
        Self {
            operands,
            resolved: false,
            replacement: None,
        }
    }
}

// ============================================================================
// MetadataStore — central metadata registry
// ============================================================================

/// The central metadata store for a module.
///
/// @llvm_behavior: LLVM maintains a metadata registry where all metadata
/// values are stored and referenced by ID. This `MetadataStore` provides
/// the same functionality with separate vectors for different debug info
/// types for efficient lookup.
#[derive(Debug, Clone)]
pub struct MetadataStore {
    /// All metadata values, indexed by ID.
    pub values: Vec<MetadataValue>,
    /// Named metadata nodes (module-level named collections).
    pub named_nodes: HashMap<String, Vec<u32>>,
    /// Debug locations, indexed by metadata ID (may be sparse).
    pub debug_loc: Vec<Option<DILocation>>,
    /// Debug files, indexed by metadata ID.
    pub debug_files: Vec<Option<DIFile>>,
    /// Debug subprograms, indexed by metadata ID.
    pub debug_subprograms: Vec<Option<DISubprogram>>,
    /// Debug types, indexed by metadata ID.
    pub debug_types: Vec<Option<DIType>>,
    /// Debug local variables, indexed by metadata ID.
    pub debug_local_vars: Vec<Option<DILocalVariable>>,
    /// Debug global variables, indexed by metadata ID.
    pub debug_global_vars: Vec<Option<DIGlobalVariable>>,
    /// Debug compile units, indexed by metadata ID.
    pub debug_compile_units: Vec<Option<DICompileUnit>>,
    /// Per-value metadata attachments: value_index -> [(kind_name, metadata_id)].
    pub metadata_attachments: HashMap<usize, Vec<(String, u32)>>,
    /// Temporary metadata nodes awaiting resolution.
    pub temporary_nodes: HashMap<u32, TemporaryNodeState>,
}

impl MetadataStore {
    /// Create a new, empty metadata store.
    pub fn new() -> Self {
        Self {
            values: Vec::new(),
            named_nodes: HashMap::new(),
            debug_loc: Vec::new(),
            debug_files: Vec::new(),
            debug_subprograms: Vec::new(),
            debug_types: Vec::new(),
            debug_local_vars: Vec::new(),
            debug_global_vars: Vec::new(),
            debug_compile_units: Vec::new(),
            metadata_attachments: HashMap::new(),
            temporary_nodes: HashMap::new(),
        }
    }

    /// Add a metadata value and return its assigned ID.
    ///
    /// IDs are assigned sequentially starting from 0. The metadata
    /// is appended to the internal values vector.
    pub fn add_metadata(&mut self, kind: MetadataKind) -> u32 {
        let id = self.values.len() as u32;
        self.values.push(MetadataValue { id, kind });
        id
    }

    /// Get a metadata value by ID.
    pub fn get_metadata(&self, id: u32) -> Option<&MetadataValue> {
        self.values.get(id as usize)
    }

    /// Get a mutable reference to a metadata value by ID.
    pub fn get_metadata_mut(&mut self, id: u32) -> Option<&mut MetadataValue> {
        self.values.get_mut(id as usize)
    }

    /// Add a named metadata node. The operands are metadata IDs.
    pub fn add_named_node(&mut self, name: &str, operands: Vec<u32>) {
        self.named_nodes.insert(name.to_string(), operands);
    }

    /// Get a named metadata node's operands by name.
    pub fn get_named_node(&self, name: &str) -> Option<&Vec<u32>> {
        self.named_nodes.get(name)
    }

    /// Remove a named metadata node.
    pub fn remove_named_node(&mut self, name: &str) {
        self.named_nodes.remove(name);
    }

    /// Check if a named node exists.
    pub fn has_named_node(&self, name: &str) -> bool {
        self.named_nodes.contains_key(name)
    }

    /// Returns the total number of metadata values.
    pub fn count(&self) -> usize {
        self.values.len()
    }

    /// Returns true if the store is empty.
    pub fn is_empty(&self) -> bool {
        self.values.is_empty() && self.named_nodes.is_empty()
    }

    // === Debug location operations ===

    /// Add a debug location and return its metadata ID.
    ///
    /// The ID is the index into the debug_loc vector.
    pub fn add_debug_location(&mut self, loc: DILocation) -> u32 {
        let id = self.debug_loc.len() as u32;
        self.debug_loc.push(Some(loc));
        id
    }

    /// Get a debug location by its metadata ID.
    pub fn get_debug_location(&self, id: u32) -> Option<&DILocation> {
        self.debug_loc.get(id as usize).and_then(|opt| opt.as_ref())
    }

    /// Update an existing debug location.
    pub fn set_debug_location(&mut self, id: u32, loc: DILocation) {
        let idx = id as usize;
        while self.debug_loc.len() <= idx {
            self.debug_loc.push(None);
        }
        self.debug_loc[idx] = Some(loc);
    }

    // === Debug file operations ===

    /// Add a debug file and return its metadata ID.
    pub fn add_debug_file(&mut self, file: DIFile) -> u32 {
        let id = self.debug_files.len() as u32;
        self.debug_files.push(Some(file));
        id
    }

    /// Get a debug file by its metadata ID.
    pub fn get_debug_file(&self, id: u32) -> Option<&DIFile> {
        self.debug_files
            .get(id as usize)
            .and_then(|opt| opt.as_ref())
    }

    /// Find a debug file by filename and directory.
    pub fn find_debug_file(&self, filename: &str, directory: &str) -> Option<u32> {
        self.debug_files
            .iter()
            .position(|opt| {
                opt.as_ref().map_or(false, |f| {
                    f.filename == filename && f.directory == directory
                })
            })
            .map(|idx| idx as u32)
    }

    // === Debug subprogram operations ===

    /// Add a debug subprogram and return its metadata ID.
    pub fn add_debug_subprogram(&mut self, sp: DISubprogram) -> u32 {
        let id = self.debug_subprograms.len() as u32;
        self.debug_subprograms.push(Some(sp));
        id
    }

    /// Get a debug subprogram by its metadata ID.
    pub fn get_debug_subprogram(&self, id: u32) -> Option<&DISubprogram> {
        self.debug_subprograms
            .get(id as usize)
            .and_then(|opt| opt.as_ref())
    }

    /// Find a debug subprogram by name.
    pub fn find_debug_subprogram(&self, name: &str) -> Option<u32> {
        self.debug_subprograms
            .iter()
            .position(|opt| opt.as_ref().map_or(false, |sp| sp.name == name))
            .map(|idx| idx as u32)
    }

    // === Debug type operations ===

    /// Add a debug type and return its metadata ID.
    pub fn add_debug_type(&mut self, ty: DIType) -> u32 {
        let id = self.debug_types.len() as u32;
        self.debug_types.push(Some(ty));
        id
    }

    /// Get a debug type by its metadata ID.
    pub fn get_debug_type(&self, id: u32) -> Option<&DIType> {
        self.debug_types
            .get(id as usize)
            .and_then(|opt| opt.as_ref())
    }

    /// Find a debug type by name.
    pub fn find_debug_type(&self, name: &str) -> Option<u32> {
        self.debug_types
            .iter()
            .position(|opt| opt.as_ref().map_or(false, |ty| ty.name == name))
            .map(|idx| idx as u32)
    }

    // === Debug local variable operations ===

    /// Add a debug local variable and return its metadata ID.
    pub fn add_debug_local_var(&mut self, var: DILocalVariable) -> u32 {
        let id = self.debug_local_vars.len() as u32;
        self.debug_local_vars.push(Some(var));
        id
    }

    /// Get a debug local variable by its metadata ID.
    pub fn get_debug_local_var(&self, id: u32) -> Option<&DILocalVariable> {
        self.debug_local_vars
            .get(id as usize)
            .and_then(|opt| opt.as_ref())
    }

    // === Debug global variable operations ===

    /// Add a debug global variable and return its metadata ID.
    pub fn add_debug_global_var(&mut self, var: DIGlobalVariable) -> u32 {
        let id = self.debug_global_vars.len() as u32;
        self.debug_global_vars.push(Some(var));
        id
    }

    /// Get a debug global variable by its metadata ID.
    pub fn get_debug_global_var(&self, id: u32) -> Option<&DIGlobalVariable> {
        self.debug_global_vars
            .get(id as usize)
            .and_then(|opt| opt.as_ref())
    }

    // === Debug compile unit operations ===

    /// Add a debug compile unit and return its metadata ID.
    pub fn add_debug_compile_unit(&mut self, cu: DICompileUnit) -> u32 {
        let id = self.debug_compile_units.len() as u32;
        self.debug_compile_units.push(Some(cu));
        id
    }

    /// Get a debug compile unit by its metadata ID.
    pub fn get_debug_compile_unit(&self, id: u32) -> Option<&DICompileUnit> {
        self.debug_compile_units
            .get(id as usize)
            .and_then(|opt| opt.as_ref())
    }

    // === Utility: creating metadata from an MDNode-style operand list ===

    /// Create an MDNode metadata value from a list of metadata operands.
    pub fn create_md_node(&mut self, operands: Vec<MetadataOperand>) -> u32 {
        self.add_metadata(MetadataKind::MDNode(operands))
    }

    /// Create a distinct MDNode metadata value from a list of operands.
    pub fn create_distinct_md_node(&mut self, operands: Vec<MetadataOperand>) -> u32 {
        self.add_metadata(MetadataKind::DistinctMDNode(operands))
    }

    /// Create an MDTuple metadata value from a list of operands.
    pub fn create_md_tuple(&mut self, operands: Vec<MetadataOperand>) -> u32 {
        self.add_metadata(MetadataKind::MDTuple(operands))
    }

    /// Create a metadata string value.
    pub fn create_md_string(&mut self, s: &str) -> u32 {
        self.add_metadata(MetadataKind::MDString(s.to_string()))
    }

    /// Helper: create a metadata operand that references another metadata by ID.
    pub fn md_ref(id: u32) -> MetadataOperand {
        MetadataOperand::Metadata(id)
    }

    /// Helper: create a metadata operand that is a string.
    pub fn md_string_op(s: &str) -> MetadataOperand {
        MetadataOperand::MDString(s.to_string())
    }

    /// Helper: create a null metadata operand.
    pub fn md_null() -> MetadataOperand {
        MetadataOperand::Null
    }

    /// Emit the LLVM IR assembly text for all metadata in this store.
    pub fn emit_assembly(&self) -> String {
        let mut lines = Vec::new();

        for mv in &self.values {
            let line = self.emit_metadata_value(mv);
            if !line.is_empty() {
                lines.push(line);
            }
        }

        for (name, operands) in &self.named_nodes {
            let ops_str = operands
                .iter()
                .map(|id| format!("!{}", id))
                .collect::<Vec<_>>()
                .join(", ");
            lines.push(format!("!{} = !{{{}}}", name, ops_str));
        }

        lines.join("\n")
    }

    fn emit_metadata_value(&self, mv: &MetadataValue) -> String {
        match &mv.kind {
            MetadataKind::MDString(s) => {
                format!("!{} = !\"{}\"", mv.id, s)
            }
            MetadataKind::Constant(c) => {
                format!("!{} = !{{{}}}", mv.id, c.to_string())
            }
            MetadataKind::Value(v) => {
                format!("!{} = !{{{}}}", mv.id, v)
            }
            MetadataKind::MDNode(operands)
            | MetadataKind::DistinctMDNode(operands)
            | MetadataKind::MDTuple(operands) => {
                let distinct = matches!(mv.kind, MetadataKind::DistinctMDNode(_));
                let prefix = if distinct { "distinct " } else { "" };
                let ops_str = operands
                    .iter()
                    .map(|op| op.to_debug_string())
                    .collect::<Vec<_>>()
                    .join(", ");
                format!("!{} = {}!{{{}}}", mv.id, prefix, ops_str)
            }
            MetadataKind::NamedNode(name, _) => {
                format!("; named node: {}", name)
            }
        }
    }
}

impl Default for MetadataStore {
    fn default() -> Self {
        Self::new()
    }
}

// ============================================================================
// Standard LLVM Metadata Kind Names
// ============================================================================

/// Well-known metadata kind names used by LLVM for attaching
/// metadata to instructions.
///
/// These constants mirror `llvm::LLVMContext::MD_kind` values.
pub mod md_kind {
    /// Debug info location metadata key.
    pub const DBG: &str = "dbg";
    /// Type-Based Alias Analysis metadata key.
    pub const TBAA: &str = "tbaa";
    /// TBAA struct-path metadata key.
    pub const TBAA_STRUCT: &str = "tbaa.struct";
    /// Alias scope metadata key.
    pub const ALIAS_SCOPE: &str = "alias.scope";
    /// No-alias metadata key.
    pub const NOALIAS: &str = "noalias";
    /// Value range metadata key.
    pub const RANGE: &str = "range";
    /// Floating-point math flags metadata key.
    pub const FPMATH: &str = "fpmath";
    /// Profile data metadata key.
    pub const PROF: &str = "prof";
    /// Loop metadata key.
    pub const LLVM_LOOP: &str = "llvm.loop";
    /// Make-implicit metadata key.
    pub const MAKE_IMPLICIT: &str = "make.implicit";
    /// Absolute symbol metadata key.
    pub const ABSOLUTE_SYMBOL: &str = "absolute_symbol";
    /// Inaccessible-memory-only metadata key.
    pub const INACCESSIBLEMEMONLY: &str = "inaccessiblememonly";
    /// Invariant load metadata key.
    pub const INVARIANT_LOAD: &str = "invariant.load";
    /// Invariant group metadata key.
    pub const INVARIANT_GROUP: &str = "invariant.group";
    /// Dereferenceable metadata key.
    pub const DEREFERENCEABLE: &str = "dereferenceable";
    /// Dereferenceable-or-null metadata key.
    pub const DEREFERENCEABLE_OR_NULL: &str = "dereferenceable_or_null";
    /// Nonnull metadata key.
    pub const NONNULL: &str = "nonnull";
    /// Alignment metadata key.
    pub const ALIGN: &str = "align";
    /// Type metadata key.
    pub const TYPE: &str = "type";
    /// Sanitizer metadata key.
    pub const SANITIZE: &str = "sanitize";
    /// Module flags (named metadata).
    pub const LLVM_MODULE_FLAGS: &str = "llvm.module.flags";
    /// Module identifier (named metadata).
    pub const LLVM_IDENT: &str = "llvm.ident";
    /// Debug compile unit list (named metadata).
    pub const LLVM_DBG_CU: &str = "llvm.dbg.cu";
    /// Used symbols list (named metadata).
    pub const LLVM_USED: &str = "llvm.used";
    /// Compiler-used symbols list (named metadata).
    pub const LLVM_COMPILER_USED: &str = "llvm.compiler.used";

    /// All well-known named metadata entries (for iteration).
    pub const NAMED: &[&str] = &[
        LLVM_MODULE_FLAGS,
        LLVM_IDENT,
        LLVM_DBG_CU,
        LLVM_USED,
        LLVM_COMPILER_USED,
    ];

    /// Returns true if the given kind name is a well-known named metadata.
    pub fn is_named(kind: &str) -> bool {
        NAMED.iter().any(|&n| n == kind)
    }
}

// ============================================================================
// DWARF Tag Constants
// ============================================================================

/// DWARF tag constants used by debug info metadata.
///
/// These are the standard `DW_TAG_*` values from the DWARF specification.
pub mod dwarf_tag {
    pub const ARRAY_TYPE: u32 = 1;
    pub const CLASS_TYPE: u32 = 2;
    pub const ENTRY_POINT: u32 = 3;
    pub const ENUMERATION_TYPE: u32 = 4;
    pub const FORMAL_PARAMETER: u32 = 5;
    pub const IMPORTED_DECLARATION: u32 = 8;
    pub const LABEL: u32 = 10;
    pub const LEXICAL_BLOCK: u32 = 11;
    pub const MEMBER: u32 = 13;
    pub const POINTER_TYPE: u32 = 15;
    pub const REFERENCE_TYPE: u32 = 16;
    pub const COMPILE_UNIT: u32 = 17;
    pub const STRUCTURE_TYPE: u32 = 19;
    pub const SUBROUTINE_TYPE: u32 = 21;
    pub const TYPEDEF: u32 = 22;
    pub const UNION_TYPE: u32 = 23;
    pub const INHERITANCE: u32 = 28;
    pub const PTR_TO_MEMBER_TYPE: u32 = 31;
    pub const ENUMERATOR: u32 = 40;
    pub const SUBRANGE_TYPE: u32 = 33;
    pub const CONST_TYPE: u32 = 38;
    pub const VOLATILE_TYPE: u32 = 53;
    pub const RESTRICT_TYPE: u32 = 55;
    pub const IMPORTED_MODULE: u32 = 58;
    pub const TEMPLATE_TYPE_PARAMETER: u32 = 47;
    pub const TEMPLATE_VALUE_PARAMETER: u32 = 48;
    pub const NAMESPACE: u32 = 57;
    pub const LEXICAL_BLOCK_FILE: u32 = 58;
    pub const GLOBAL_VARIABLE: u32 = 52;
    pub const LOCAL_VARIABLE: u32 = 33;
    pub const AUTO_VARIABLE: u32 = 256;
    pub const ARG_VARIABLE: u32 = 257;
    pub const RETURN_VARIABLE: u32 = 258;
    pub const STRING_TYPE: u32 = 67;
}

// ============================================================================
// DWARF Encoding Constants
// ============================================================================

/// DWARF attribute encoding constants used by DIBasicType.
///
/// These are the standard `DW_ATE_*` values from the DWARF specification.
pub mod dwarf_encoding {
    pub const ADDRESS: u32 = 1;
    pub const BOOLEAN: u32 = 2;
    pub const COMPLEX_FLOAT: u32 = 3;
    pub const FLOAT: u32 = 4;
    pub const SIGNED: u32 = 5;
    pub const SIGNED_CHAR: u32 = 6;
    pub const UNSIGNED: u32 = 7;
    pub const UNSIGNED_CHAR: u32 = 8;
    pub const IMAGINARY_FLOAT: u32 = 9;
    pub const PACKED_DECIMAL: u32 = 10;
    pub const NUMERIC_STRING: u32 = 11;
    pub const UTF: u32 = 16;
    pub const UCS: u32 = 17;
    pub const ASCII: u32 = 18;
}

// ============================================================================
// DWARF Language Constants
// ============================================================================

/// DWARF language constants used by DICompileUnit.
pub mod dwarf_lang {
    pub const C89: u32 = 1;
    pub const C: u32 = 2;
    pub const ADA83: u32 = 3;
    pub const C_PLUS_PLUS: u32 = 4;
    pub const COBOL74: u32 = 5;
    pub const COBOL85: u32 = 6;
    pub const FORTRAN77: u32 = 7;
    pub const FORTRAN90: u32 = 8;
    pub const PASCAL83: u32 = 9;
    pub const MODULA2: u32 = 10;
    pub const JAVA: u32 = 11;
    pub const C99: u32 = 12;
    pub const ADA95: u32 = 13;
    pub const FORTRAN95: u32 = 14;
    pub const PL1: u32 = 15;
    pub const OBJC: u32 = 16;
    pub const OBJC_PLUS_PLUS: u32 = 17;
    pub const D: u32 = 19;
    pub const PYTHON: u32 = 20;
    pub const RUST: u32 = 28;
    pub const C11: u32 = 29;
    pub const SWIFT: u32 = 31;
    pub const C_PLUS_PLUS_14: u32 = 33;
    pub const FORTRAN03: u32 = 34;
    pub const FORTRAN08: u32 = 35;
    pub const RENDERSCRIPT: u32 = 36;
    pub const C17: u32 = 38;
    pub const C_PLUS_PLUS_20: u32 = 41;
    pub const MOJO: u32 = 43;
}

// ============================================================================
// DWARF Expression Operation Constants (DW_OP_*)
// ============================================================================

/// DWARF expression operation codes used in DIExpression.
pub mod dwarf_op {
    pub const ADDR: u64 = 0x03;
    pub const DEREF: u64 = 0x06;
    pub const CONST1U: u64 = 0x08;
    pub const CONST1S: u64 = 0x09;
    pub const CONST2U: u64 = 0x0a;
    pub const CONST2S: u64 = 0x0b;
    pub const CONST4U: u64 = 0x0c;
    pub const CONST4S: u64 = 0x0d;
    pub const CONST8U: u64 = 0x0e;
    pub const CONST8S: u64 = 0x0f;
    pub const CONSTU: u64 = 0x10;
    pub const CONSTS: u64 = 0x11;
    pub const DUP: u64 = 0x12;
    pub const DROP: u64 = 0x13;
    pub const OVER: u64 = 0x14;
    pub const PICK: u64 = 0x15;
    pub const SWAP: u64 = 0x16;
    pub const ROT: u64 = 0x17;
    pub const XDEREF: u64 = 0x18;
    pub const ABS: u64 = 0x19;
    pub const AND: u64 = 0x1a;
    pub const DIV: u64 = 0x1b;
    pub const MINUS: u64 = 0x1c;
    pub const MOD: u64 = 0x1d;
    pub const MUL: u64 = 0x1e;
    pub const NEG: u64 = 0x1f;
    pub const NOT: u64 = 0x20;
    pub const OR: u64 = 0x21;
    pub const PLUS: u64 = 0x22;
    pub const PLUS_UCONST: u64 = 0x23;
    pub const SHL: u64 = 0x24;
    pub const SHR: u64 = 0x25;
    pub const SHRA: u64 = 0x26;
    pub const XOR: u64 = 0x27;
    pub const BRA: u64 = 0x28;
    pub const EQ: u64 = 0x29;
    pub const GE: u64 = 0x2a;
    pub const GT: u64 = 0x2b;
    pub const LE: u64 = 0x2c;
    pub const LT: u64 = 0x2d;
    pub const NE: u64 = 0x2e;
    pub const SKIP: u64 = 0x2f;
    pub const LIT0: u64 = 0x30;
    pub const LIT1: u64 = 0x31;
    pub const LIT2: u64 = 0x32;
    pub const LIT3: u64 = 0x33;
    pub const LIT4: u64 = 0x34;
    pub const LIT5: u64 = 0x35;
    pub const LIT6: u64 = 0x36;
    pub const LIT7: u64 = 0x37;
    pub const LIT8: u64 = 0x38;
    pub const LIT9: u64 = 0x39;
    pub const LIT10: u64 = 0x3a;
    pub const LIT11: u64 = 0x3b;
    pub const LIT12: u64 = 0x3c;
    pub const LIT13: u64 = 0x3d;
    pub const LIT14: u64 = 0x3e;
    pub const LIT15: u64 = 0x3f;
    pub const LIT16: u64 = 0x40;
    pub const LIT17: u64 = 0x41;
    pub const LIT18: u64 = 0x42;
    pub const LIT19: u64 = 0x43;
    pub const LIT20: u64 = 0x44;
    pub const LIT21: u64 = 0x45;
    pub const LIT22: u64 = 0x46;
    pub const LIT23: u64 = 0x47;
    pub const LIT24: u64 = 0x48;
    pub const LIT25: u64 = 0x49;
    pub const LIT26: u64 = 0x4a;
    pub const LIT27: u64 = 0x4b;
    pub const LIT28: u64 = 0x4c;
    pub const LIT29: u64 = 0x4d;
    pub const LIT30: u64 = 0x4e;
    pub const LIT31: u64 = 0x4f;
    pub const REG0: u64 = 0x50;
    pub const REG1: u64 = 0x51;
    pub const REG2: u64 = 0x52;
    pub const REG3: u64 = 0x53;
    pub const REG4: u64 = 0x54;
    pub const REG5: u64 = 0x55;
    pub const REG6: u64 = 0x56;
    pub const REG7: u64 = 0x57;
    pub const REG8: u64 = 0x58;
    pub const REG9: u64 = 0x59;
    pub const REG10: u64 = 0x5a;
    pub const REG11: u64 = 0x5b;
    pub const REG12: u64 = 0x5c;
    pub const REG13: u64 = 0x5d;
    pub const REG14: u64 = 0x5e;
    pub const REG15: u64 = 0x5f;
    pub const REG16: u64 = 0x60;
    pub const REG17: u64 = 0x61;
    pub const REG18: u64 = 0x62;
    pub const REG19: u64 = 0x63;
    pub const REG20: u64 = 0x64;
    pub const REG21: u64 = 0x65;
    pub const REG22: u64 = 0x66;
    pub const REG23: u64 = 0x67;
    pub const REG24: u64 = 0x68;
    pub const REG25: u64 = 0x69;
    pub const REG26: u64 = 0x6a;
    pub const REG27: u64 = 0x6b;
    pub const REG28: u64 = 0x6c;
    pub const REG29: u64 = 0x6d;
    pub const REG30: u64 = 0x6e;
    pub const REG31: u64 = 0x6f;
    pub const BREG0: u64 = 0x70;
    pub const BREG1: u64 = 0x71;
    pub const BREG2: u64 = 0x72;
    pub const BREG3: u64 = 0x73;
    pub const BREG4: u64 = 0x74;
    pub const BREG5: u64 = 0x75;
    pub const BREG6: u64 = 0x76;
    pub const BREG7: u64 = 0x77;
    pub const BREG8: u64 = 0x78;
    pub const BREG9: u64 = 0x79;
    pub const BREG10: u64 = 0x7a;
    pub const BREG11: u64 = 0x7b;
    pub const BREG12: u64 = 0x7c;
    pub const BREG13: u64 = 0x7d;
    pub const BREG14: u64 = 0x7e;
    pub const BREG15: u64 = 0x7f;
    pub const BREG16: u64 = 0x80;
    pub const BREG17: u64 = 0x81;
    pub const BREG18: u64 = 0x82;
    pub const BREG19: u64 = 0x83;
    pub const BREG20: u64 = 0x84;
    pub const BREG21: u64 = 0x85;
    pub const BREG22: u64 = 0x86;
    pub const BREG23: u64 = 0x87;
    pub const BREG24: u64 = 0x88;
    pub const BREG25: u64 = 0x89;
    pub const BREG26: u64 = 0x8a;
    pub const BREG27: u64 = 0x8b;
    pub const BREG28: u64 = 0x8c;
    pub const BREG29: u64 = 0x8d;
    pub const BREG30: u64 = 0x8e;
    pub const BREG31: u64 = 0x8f;
    pub const REGX: u64 = 0x90;
    pub const FBREG: u64 = 0x91;
    pub const BREGX: u64 = 0x92;
    pub const PIECE: u64 = 0x93;
    pub const DEREF_SIZE: u64 = 0x94;
    pub const XDEREF_SIZE: u64 = 0x95;
    pub const NOP: u64 = 0x96;
    pub const PUSH_OBJECT_ADDRESS: u64 = 0x97;
    pub const CALL2: u64 = 0x98;
    pub const CALL4: u64 = 0x99;
    pub const CALL_REF: u64 = 0x9a;
    pub const FORM_TLS_ADDRESS: u64 = 0x9b;
    pub const CALL_FRAME_CFA: u64 = 0x9c;
    pub const BIT_PIECE: u64 = 0x9d;
    pub const IMPLICIT_VALUE: u64 = 0x9e;
    pub const STACK_VALUE: u64 = 0x9f;
    pub const IMPLICIT_POINTER: u64 = 0xa0;
    pub const ADDR_OF: u64 = 0xa1;
    pub const ENTRY_VALUE: u64 = 0xa3;
    pub const CONST_TYPE: u64 = 0xa4;
    pub const REGVAL_TYPE: u64 = 0xa5;
    pub const DEREF_TYPE: u64 = 0xa6;
    pub const XDEREF_TYPE: u64 = 0xa7;
    pub const CONVERT: u64 = 0xa8;
    pub const REINTERPRET: u64 = 0xa9;
    /// LLVM-specific: marks a fragment (offset, size).
    pub const LLVM_FRAGMENT: u64 = 0x1000;
    /// LLVM-specific: marks an argument number.
    pub const LLVM_ARG: u64 = 0x1000 + 1;
    /// LLVM-specific: entry value expression.
    pub const LLVM_ENTRY_VALUE: u64 = 0x1000 + 3;
}

// ============================================================================
// DIScope trait — common interface for all debug info scopes
// ============================================================================

/// Trait implemented by all debug info scope types.
///
/// @llvm_behavior: In LLVM, `DIScope` is the base class for all debug info
/// nodes that can serve as a lexical scope (DISubprogram, DILexicalBlock,
/// DICompileUnit, DINamespace, DIType for composite types, etc.).
/// This trait provides the common interface for scope queries.
pub trait DIScope {
    /// Returns the display name of this scope.
    fn get_scope_name(&self) -> &str;

    /// Returns the metadata ID of the DIFile for this scope, if any.
    fn get_scope_file(&self) -> Option<u32>;

    /// Returns the line number where this scope begins, if any.
    fn get_scope_line(&self) -> Option<u32>;
}

// ============================================================================
// DIScope implementations for existing debug info types
// ============================================================================

impl DIScope for DISubprogram {
    fn get_scope_name(&self) -> &str {
        &self.name
    }

    fn get_scope_file(&self) -> Option<u32> {
        Some(self.file)
    }

    fn get_scope_line(&self) -> Option<u32> {
        Some(self.line)
    }
}

impl DIScope for DICompileUnit {
    fn get_scope_name(&self) -> &str {
        &self.producer
    }

    fn get_scope_file(&self) -> Option<u32> {
        Some(self.file)
    }

    fn get_scope_line(&self) -> Option<u32> {
        None
    }
}

// ============================================================================
// Full DIType Hierarchy (DWARF type descriptors)
// ============================================================================

/// DIBasicType — a basic/primitive type descriptor (int, float, char, etc.).
///
/// @llvm_behavior: `DIBasicType` maps to `!DIBasicType(...)` in LLVM IR.
/// It describes a primitive type with a name, size, alignment, encoding,
/// and optional flags.
#[derive(Debug, Clone)]
pub struct DIBasicType {
    /// The type name (e.g., "int", "float", "double").
    pub name: String,
    /// Size of the type in bits.
    pub size_in_bits: u64,
    /// Alignment of the type in bits.
    pub align_in_bits: u32,
    /// DWARF encoding (e.g., DW_ATE_signed = 5, DW_ATE_float = 4).
    pub encoding: u32,
    /// Optional flags (e.g., DIFlags for accessibility).
    pub flags: u32,
}

impl DIBasicType {
    /// Create a new DIBasicType.
    pub fn new(name: String, size_in_bits: u64, align_in_bits: u32, encoding: u32) -> Self {
        Self {
            name,
            size_in_bits,
            align_in_bits,
            encoding,
            flags: 0,
        }
    }

    /// Create a DIBasicType for a signed integer.
    pub fn signed_int(name: String, size_in_bits: u64, align_in_bits: u32) -> Self {
        Self::new(name, size_in_bits, align_in_bits, dwarf_encoding::SIGNED)
    }

    /// Create a DIBasicType for an unsigned integer.
    pub fn unsigned_int(name: String, size_in_bits: u64, align_in_bits: u32) -> Self {
        Self::new(name, size_in_bits, align_in_bits, dwarf_encoding::UNSIGNED)
    }

    /// Create a DIBasicType for a floating-point type.
    pub fn float_type(name: String, size_in_bits: u64, align_in_bits: u32) -> Self {
        Self::new(name, size_in_bits, align_in_bits, dwarf_encoding::FLOAT)
    }

    /// Create a DIBasicType for a boolean type.
    pub fn boolean(name: String, size_in_bits: u64, align_in_bits: u32) -> Self {
        Self::new(name, size_in_bits, align_in_bits, dwarf_encoding::BOOLEAN)
    }

    /// Create a DIBasicType for a character type.
    pub fn character(name: String, size_in_bits: u64, align_in_bits: u32, signed: bool) -> Self {
        let enc = if signed {
            dwarf_encoding::SIGNED_CHAR
        } else {
            dwarf_encoding::UNSIGNED_CHAR
        };
        Self::new(name, size_in_bits, align_in_bits, enc)
    }

    /// Returns the size in bytes (rounded up to the nearest byte).
    pub fn size_in_bytes(&self) -> u64 {
        (self.size_in_bits + 7) / 8
    }

    /// Returns true if this is a signed integer type.
    pub fn is_signed(&self) -> bool {
        self.encoding == dwarf_encoding::SIGNED || self.encoding == dwarf_encoding::SIGNED_CHAR
    }

    /// Returns true if this is an unsigned integer type.
    pub fn is_unsigned(&self) -> bool {
        self.encoding == dwarf_encoding::UNSIGNED || self.encoding == dwarf_encoding::UNSIGNED_CHAR
    }

    /// Returns true if this is a floating-point type.
    pub fn is_float(&self) -> bool {
        self.encoding == dwarf_encoding::FLOAT
            || self.encoding == dwarf_encoding::COMPLEX_FLOAT
            || self.encoding == dwarf_encoding::IMAGINARY_FLOAT
    }

    /// Returns true if this is a boolean type.
    pub fn is_boolean(&self) -> bool {
        self.encoding == dwarf_encoding::BOOLEAN
    }

    /// Set the flags for this type (builder pattern).
    pub fn with_flags(mut self, flags: u32) -> Self {
        self.flags = flags;
        self
    }
}

/// DIDerivedType — a derived type descriptor (pointer, reference, const,
/// volatile, typedef, member, inheritance, etc.).
///
/// @llvm_behavior: `DIDerivedType` maps to `!DIDerivedType(...)` in LLVM IR.
/// It describes a type derived from a base type, identified by its DWARF tag.
#[derive(Debug, Clone)]
pub struct DIDerivedType {
    /// DWARF tag (e.g., DW_TAG_pointer_type = 15, DW_TAG_typedef = 22).
    pub tag: u32,
    /// Metadata ID of the base type.
    pub base_type: u32,
    /// Optional name for the derived type (used for typedefs).
    pub name: Option<String>,
    /// Size of the derived type in bits.
    pub size: u64,
    /// Alignment of the derived type in bits.
    pub align: u32,
    /// Offset in bits (for struct/class members).
    pub offset: u64,
    /// Optional DWARF flags.
    pub dw_flags: u32,
    /// Optional metadata ID of the scope containing this type.
    pub scope: Option<u32>,
    /// Optional metadata ID of the file where this type is defined.
    pub file: Option<u32>,
    /// Optional line number where this type is defined.
    pub line: Option<u32>,
    /// Optional extra data metadata operand.
    pub extra_data: Option<u32>,
    /// Optional annotations.
    pub annotations: Option<u32>,
}

impl DIDerivedType {
    /// Create a new DIDerivedType.
    pub fn new(tag: u32, base_type: u32, size: u64, align: u32, offset: u64) -> Self {
        Self {
            tag,
            base_type,
            name: None,
            size,
            align,
            offset,
            dw_flags: 0,
            scope: None,
            file: None,
            line: None,
            extra_data: None,
            annotations: None,
        }
    }

    /// Create a pointer type (DW_TAG_pointer_type).
    pub fn pointer_type(base_type: u32, size: u64, align: u32) -> Self {
        Self::new(dwarf_tag::POINTER_TYPE, base_type, size, align, 0)
    }

    /// Create a reference type (DW_TAG_reference_type).
    pub fn reference_type(base_type: u32, size: u64, align: u32) -> Self {
        Self::new(dwarf_tag::REFERENCE_TYPE, base_type, size, align, 0)
    }

    /// Create a typedef (DW_TAG_typedef).
    pub fn typedef_type(name: String, base_type: u32, file: u32, line: u32) -> Self {
        let mut ty = Self::new(dwarf_tag::TYPEDEF, base_type, 0, 0, 0);
        ty.name = Some(name);
        ty.file = Some(file);
        ty.line = Some(line);
        ty
    }

    /// Create a const-qualified type (DW_TAG_const_type).
    pub fn const_type(base_type: u32) -> Self {
        Self::new(dwarf_tag::CONST_TYPE, base_type, 0, 0, 0)
    }

    /// Create a volatile-qualified type (DW_TAG_volatile_type).
    pub fn volatile_type(base_type: u32) -> Self {
        Self::new(dwarf_tag::VOLATILE_TYPE, base_type, 0, 0, 0)
    }

    /// Create a restrict-qualified type (DW_TAG_restrict_type).
    pub fn restrict_type(base_type: u32) -> Self {
        Self::new(dwarf_tag::RESTRICT_TYPE, base_type, 0, 0, 0)
    }

    /// Create a pointer-to-member type (DW_TAG_ptr_to_member_type).
    pub fn ptr_to_member_type(base_type: u32, class_type: u32, size: u64, align: u32) -> Self {
        let mut ty = Self::new(dwarf_tag::PTR_TO_MEMBER_TYPE, base_type, size, align, 0);
        ty.extra_data = Some(class_type);
        ty
    }

    /// Create a member type (struct/class field).
    pub fn member_type(
        name: String,
        base_type: u32,
        size: u64,
        align: u32,
        offset: u64,
        file: u32,
        line: u32,
    ) -> Self {
        let mut ty = Self::new(dwarf_tag::MEMBER, base_type, size, align, offset);
        ty.name = Some(name);
        ty.file = Some(file);
        ty.line = Some(line);
        ty
    }

    /// Create an inheritance descriptor.
    pub fn inheritance(base_type: u32, offset: u64, dw_flags: u32) -> Self {
        Self::new(dwarf_tag::INHERITANCE, base_type, 0, 0, offset).with_dw_flags(dw_flags)
    }

    /// Returns true if this is a pointer type.
    pub fn is_pointer(&self) -> bool {
        self.tag == dwarf_tag::POINTER_TYPE
    }

    /// Returns true if this is a reference type.
    pub fn is_reference(&self) -> bool {
        self.tag == dwarf_tag::REFERENCE_TYPE
    }

    /// Returns true if this is a typedef.
    pub fn is_typedef(&self) -> bool {
        self.tag == dwarf_tag::TYPEDEF
    }

    /// Returns true if this is a const-qualified type.
    pub fn is_const(&self) -> bool {
        self.tag == dwarf_tag::CONST_TYPE
    }

    /// Returns true if this is a volatile-qualified type.
    pub fn is_volatile(&self) -> bool {
        self.tag == dwarf_tag::VOLATILE_TYPE
    }

    /// Returns true if this is a restrict-qualified type.
    pub fn is_restrict(&self) -> bool {
        self.tag == dwarf_tag::RESTRICT_TYPE
    }

    /// Returns true if this is a member (struct field).
    pub fn is_member(&self) -> bool {
        self.tag == dwarf_tag::MEMBER
    }

    /// Returns true if this is an inheritance descriptor.
    pub fn is_inheritance(&self) -> bool {
        self.tag == dwarf_tag::INHERITANCE
    }

    /// Set the DWARF flags (builder pattern).
    pub fn with_dw_flags(mut self, flags: u32) -> Self {
        self.dw_flags = flags;
        self
    }

    /// Set the scope (builder pattern).
    pub fn with_scope(mut self, scope: u32) -> Self {
        self.scope = Some(scope);
        self
    }

    /// Set the name (builder pattern).
    pub fn with_name(mut self, name: String) -> Self {
        self.name = Some(name);
        self
    }

    /// Set the file and line (builder pattern).
    pub fn with_file_line(mut self, file: u32, line: u32) -> Self {
        self.file = Some(file);
        self.line = Some(line);
        self
    }
}

impl DIScope for DIDerivedType {
    fn get_scope_name(&self) -> &str {
        self.name.as_deref().unwrap_or("<derived>")
    }

    fn get_scope_file(&self) -> Option<u32> {
        self.file
    }

    fn get_scope_line(&self) -> Option<u32> {
        self.line
    }
}

/// DICompositeType — a composite type descriptor (struct, class, union,
/// array, enum, etc.).
///
/// @llvm_behavior: `DICompositeType` maps to `!DICompositeType(...)` in
/// LLVM IR. It describes aggregate types with their elements (members,
/// enumerators, subscripts), vtable holder, template parameters, and
/// optional ODR-unique identifier.
#[derive(Debug, Clone)]
pub struct DICompositeType {
    /// DWARF tag (e.g., DW_TAG_structure_type = 19, DW_TAG_array_type = 1).
    pub tag: u32,
    /// Optional type name.
    pub name: Option<String>,
    /// Metadata ID of the DIFile where this type is defined.
    pub file: Option<u32>,
    /// Line number where this type is defined.
    pub line: Option<u32>,
    /// Metadata ID of the parent scope.
    pub scope: Option<u32>,
    /// Metadata ID of the base type (for arrays: element type; for enums: underlying type).
    pub base_type: Option<u32>,
    /// Size of the type in bits.
    pub size: u64,
    /// Alignment of the type in bits.
    pub align: u32,
    /// Offset in bits (for nested types).
    pub offset: u64,
    /// Flags.
    pub flags: u32,
    /// Metadata IDs of element types (members for struct, elements for array,
    /// enumerators for enum).
    pub elements: Vec<u32>,
    /// Metadata ID of the vtable holder (for classes with virtual dispatch).
    pub vtable_holder: Option<u32>,
    /// Metadata IDs of template parameters.
    pub template_params: Vec<u32>,
    /// Optional unique identifier string (for ODR-uniqued types).
    pub identifier: Option<String>,
    /// Runtime language (e.g., Objective-C runtime version).
    pub runtime_lang: u32,
    /// Optional discriminator type (for variant parts).
    pub discriminator: Option<u32>,
    /// Optional data location expression.
    pub data_location: Option<u32>,
    /// Optional associated metadata.
    pub associated: Option<u32>,
    /// Optional allocated metadata.
    pub allocated: Option<u32>,
    /// Optional rank (for assumed-rank arrays).
    pub rank: Option<u32>,
}

impl DICompositeType {
    /// Create a new DICompositeType.
    pub fn new(tag: u32, name: Option<String>, size: u64, align: u32, offset: u64) -> Self {
        Self {
            tag,
            name,
            file: None,
            line: None,
            scope: None,
            base_type: None,
            size,
            align,
            offset,
            flags: 0,
            elements: Vec::new(),
            vtable_holder: None,
            template_params: Vec::new(),
            identifier: None,
            runtime_lang: 0,
            discriminator: None,
            data_location: None,
            associated: None,
            allocated: None,
            rank: None,
        }
    }

    /// Create a struct type.
    pub fn struct_type(name: String, size: u64, align: u32, file: u32, line: u32) -> Self {
        let mut ty = Self::new(dwarf_tag::STRUCTURE_TYPE, Some(name), size, align, 0);
        ty.file = Some(file);
        ty.line = Some(line);
        ty
    }

    /// Create a class type.
    pub fn class_type(name: String, size: u64, align: u32, file: u32, line: u32) -> Self {
        let mut ty = Self::new(dwarf_tag::CLASS_TYPE, Some(name), size, align, 0);
        ty.file = Some(file);
        ty.line = Some(line);
        ty
    }

    /// Create a union type.
    pub fn union_type(name: String, size: u64, align: u32, file: u32, line: u32) -> Self {
        let mut ty = Self::new(dwarf_tag::UNION_TYPE, Some(name), size, align, 0);
        ty.file = Some(file);
        ty.line = Some(line);
        ty
    }

    /// Create an array type.
    pub fn array_type(
        name: String,
        element_type: u32,
        size: u64,
        align: u32,
        subscripts: Vec<u32>,
    ) -> Self {
        let mut ty = Self::new(dwarf_tag::ARRAY_TYPE, Some(name), size, align, 0);
        ty.base_type = Some(element_type);
        ty.elements = subscripts;
        ty
    }

    /// Create an enumeration type.
    pub fn enum_type(
        name: String,
        underlying_type: u32,
        size: u64,
        align: u32,
        file: u32,
        line: u32,
        enumerators: Vec<u32>,
    ) -> Self {
        let mut ty = Self::new(dwarf_tag::ENUMERATION_TYPE, Some(name), size, align, 0);
        ty.base_type = Some(underlying_type);
        ty.file = Some(file);
        ty.line = Some(line);
        ty.elements = enumerators;
        ty
    }

    /// Returns true if this is a struct or class type.
    pub fn is_struct_or_class(&self) -> bool {
        self.tag == dwarf_tag::STRUCTURE_TYPE || self.tag == dwarf_tag::CLASS_TYPE
    }

    /// Returns true if this is a union type.
    pub fn is_union(&self) -> bool {
        self.tag == dwarf_tag::UNION_TYPE
    }

    /// Returns true if this is an array type.
    pub fn is_array(&self) -> bool {
        self.tag == dwarf_tag::ARRAY_TYPE
    }

    /// Returns true if this is an enumeration type.
    pub fn is_enum(&self) -> bool {
        self.tag == dwarf_tag::ENUMERATION_TYPE
    }

    /// Returns true if this is a forward declaration (no size, no elements).
    pub fn is_forward_declaration(&self) -> bool {
        self.size == 0 && self.elements.is_empty()
    }

    /// Returns true if this is a complete definition.
    pub fn is_complete_definition(&self) -> bool {
        !self.is_forward_declaration()
    }

    /// Add an element (member/enumerator/subscript) metadata ID.
    pub fn add_element(&mut self, element_id: u32) {
        self.elements.push(element_id);
    }

    /// Add a template parameter metadata ID.
    pub fn add_template_param(&mut self, param_id: u32) {
        self.template_params.push(param_id);
    }

    /// Set the ODR-unique identifier (builder pattern).
    pub fn with_identifier(mut self, identifier: String) -> Self {
        self.identifier = Some(identifier);
        self
    }

    /// Set the vtable holder (builder pattern).
    pub fn with_vtable_holder(mut self, vtable_holder: u32) -> Self {
        self.vtable_holder = Some(vtable_holder);
        self
    }

    /// Set the scope (builder pattern).
    pub fn with_scope(mut self, scope: u32) -> Self {
        self.scope = Some(scope);
        self
    }

    /// Set the flags (builder pattern).
    pub fn with_flags(mut self, flags: u32) -> Self {
        self.flags = flags;
        self
    }

    /// Set the discriminator for variant parts (builder pattern).
    pub fn with_discriminator(mut self, disc: u32) -> Self {
        self.discriminator = Some(disc);
        self
    }

    /// Set the data location expression (builder pattern).
    pub fn with_data_location(mut self, dl: u32) -> Self {
        self.data_location = Some(dl);
        self
    }

    /// Set the rank for assumed-rank arrays (builder pattern).
    pub fn with_rank(mut self, rank: u32) -> Self {
        self.rank = Some(rank);
        self
    }
}

impl DIScope for DICompositeType {
    fn get_scope_name(&self) -> &str {
        self.name.as_deref().unwrap_or("<unnamed>")
    }

    fn get_scope_file(&self) -> Option<u32> {
        self.file
    }

    fn get_scope_line(&self) -> Option<u32> {
        self.line
    }
}

/// DISubroutineType — a subroutine type descriptor (function signature).
///
/// @llvm_behavior: `DISubroutineType` maps to `!DISubroutineType(...)` in
/// LLVM IR. It describes the type signature of a function: the first element
/// in the `types` array is the return type; subsequent elements are the
/// parameter types in declaration order.
#[derive(Debug, Clone)]
pub struct DISubroutineType {
    /// Flags (e.g., calling convention info).
    pub flags: u32,
    /// Metadata IDs of type nodes. `types[0]` is the return type;
    /// `types[1..]` are the parameter types. May be empty for void-returning
    /// functions with no parameters.
    pub types: Vec<u32>,
    /// Optional calling convention.
    pub cc: Option<u32>,
}

impl DISubroutineType {
    /// Create a new DISubroutineType.
    pub fn new(flags: u32, types: Vec<u32>) -> Self {
        Self {
            flags,
            types,
            cc: None,
        }
    }

    /// Create a subroutine type with a return type and parameter types.
    pub fn with_signature(return_type: u32, param_types: Vec<u32>) -> Self {
        let mut types = vec![return_type];
        types.extend(param_types);
        Self::new(0, types)
    }

    /// Create a void-returning subroutine type.
    pub fn void_returning(param_types: Vec<u32>) -> Self {
        let mut types = Vec::with_capacity(param_types.len() + 1);
        types.push(0); // null = void in DWARF
        types.extend(param_types);
        Self::new(0, types)
    }

    /// Returns the return type metadata ID (first element of types).
    /// Returns None if the types list is empty.
    pub fn return_type(&self) -> Option<u32> {
        self.types.first().copied()
    }

    /// Returns the parameter type metadata IDs (everything after the return type).
    pub fn param_types(&self) -> &[u32] {
        if self.types.is_empty() {
            &[]
        } else {
            &self.types[1..]
        }
    }

    /// Returns the total number of types (return type + parameters).
    pub fn num_types(&self) -> usize {
        self.types.len()
    }

    /// Returns the number of parameters.
    pub fn num_params(&self) -> usize {
        if self.types.is_empty() {
            0
        } else {
            self.types.len() - 1
        }
    }

    /// Add a parameter type (appended to the end of the types list).
    pub fn add_param_type(&mut self, ty: u32) {
        self.types.push(ty);
    }

    /// Set the calling convention (builder pattern).
    pub fn with_cc(mut self, cc: u32) -> Self {
        self.cc = Some(cc);
        self
    }

    /// Set the flags (builder pattern).
    pub fn with_flags(mut self, flags: u32) -> Self {
        self.flags = flags;
        self
    }
}

impl DIScope for DISubroutineType {
    fn get_scope_name(&self) -> &str {
        "<subroutine>"
    }

    fn get_scope_file(&self) -> Option<u32> {
        None
    }

    fn get_scope_line(&self) -> Option<u32> {
        None
    }
}

/// DIEnumerator — an enumerator value descriptor.
///
/// @llvm_behavior: `DIEnumerator` maps to `!DIEnumerator(...)` in LLVM IR.
/// It describes a named constant value in an enumeration type.
#[derive(Debug, Clone)]
pub struct DIEnumerator {
    /// The enumerator name.
    pub name: String,
    /// The enumerator value (signed representation).
    pub value: i64,
    /// Whether the value should be interpreted as unsigned.
    pub is_unsigned: bool,
}

impl DIEnumerator {
    /// Create a new DIEnumerator.
    pub fn new(name: String, value: i64, is_unsigned: bool) -> Self {
        Self {
            name,
            value,
            is_unsigned,
        }
    }

    /// Create a signed enumerator.
    pub fn signed(name: String, value: i64) -> Self {
        Self::new(name, value, false)
    }

    /// Create an unsigned enumerator.
    pub fn unsigned(name: String, value: u64) -> Self {
        Self::new(name, value as i64, true)
    }

    /// Returns the value as u64 if unsigned. Panics if called on a signed
    /// enumerator with a negative value.
    pub fn value_as_u64(&self) -> u64 {
        if self.is_unsigned {
            self.value as u64
        } else {
            assert!(
                self.value >= 0,
                "Cannot convert negative signed enumerator value to u64"
            );
            self.value as u64
        }
    }

    /// Returns the value as i64.
    pub fn value_as_i64(&self) -> i64 {
        self.value
    }

    /// Returns a display representation of the value.
    pub fn value_display(&self) -> String {
        if self.is_unsigned {
            format!("{}", self.value as u64)
        } else {
            format!("{}", self.value)
        }
    }
}

/// DINamespace — a namespace descriptor.
///
/// @llvm_behavior: `DINamespace` maps to `!DINamespace(...)` in LLVM IR.
/// It describes a C++ namespace or module-level scope.
#[derive(Debug, Clone)]
pub struct DINamespace {
    /// The namespace name.
    pub name: String,
    /// Metadata ID of the parent scope (typically the enclosing namespace,
    /// compile unit, or another namespace).
    pub scope: u32,
    /// Whether this namespace exports its symbols (e.g., inline namespace).
    pub export_symbols: bool,
}

impl DINamespace {
    /// Create a new DINamespace.
    pub fn new(name: String, scope: u32, export_symbols: bool) -> Self {
        Self {
            name,
            scope,
            export_symbols,
        }
    }

    /// Create a regular (non-exporting) namespace.
    pub fn regular(name: String, scope: u32) -> Self {
        Self::new(name, scope, false)
    }

    /// Create an inline/exporting namespace.
    pub fn exporting(name: String, scope: u32) -> Self {
        Self::new(name, scope, true)
    }

    /// Returns true if this is an inline (exporting) namespace.
    pub fn is_inline(&self) -> bool {
        self.export_symbols
    }
}

impl DIScope for DINamespace {
    fn get_scope_name(&self) -> &str {
        &self.name
    }

    fn get_scope_file(&self) -> Option<u32> {
        None
    }

    fn get_scope_line(&self) -> Option<u32> {
        None
    }
}

/// DITemplateTypeParameter — a template type parameter descriptor.
///
/// @llvm_behavior: `DITemplateTypeParameter` maps to
/// `!DITemplateTypeParameter(...)` in LLVM IR. It describes a type template
/// parameter in a templated entity (e.g., `typename T`).
#[derive(Debug, Clone)]
pub struct DITemplateTypeParameter {
    /// The parameter name (e.g., "T").
    pub name: String,
    /// Metadata ID of the parameter's type.
    pub ty: u32,
    /// Whether this is a default template parameter.
    pub is_default: bool,
}

impl DITemplateTypeParameter {
    /// Create a new DITemplateTypeParameter.
    pub fn new(name: String, ty: u32) -> Self {
        Self {
            name,
            ty,
            is_default: false,
        }
    }

    /// Mark this parameter as a default (builder pattern).
    pub fn with_default(mut self) -> Self {
        self.is_default = true;
        self
    }
}

/// DITemplateValueParameter — a template value parameter descriptor (non-type
/// template parameter).
///
/// @llvm_behavior: `DITemplateValueParameter` maps to
/// `!DITemplateValueParameter(...)` in LLVM IR. It describes a non-type
/// template parameter (e.g., `int N` in `template<int N>`).
#[derive(Debug, Clone)]
pub struct DITemplateValueParameter {
    /// The parameter name.
    pub name: String,
    /// Metadata ID of the parameter's type.
    pub ty: u32,
    /// The constant value (as a metadata operand).
    pub value: MetadataOperand,
    /// Whether this is a default template parameter.
    pub is_default: bool,
}

impl DITemplateValueParameter {
    /// Create a new DITemplateValueParameter.
    pub fn new(name: String, ty: u32, value: MetadataOperand) -> Self {
        Self {
            name,
            ty,
            value,
            is_default: false,
        }
    }

    /// Create a value parameter with an integer value.
    pub fn integer(name: String, ty: u32, val: i64) -> Self {
        let cv = ConstantValue::new_int(Type::i32(), val);
        Self::new(name, ty, MetadataOperand::Constant(cv))
    }

    /// Mark this parameter as a default (builder pattern).
    pub fn with_default(mut self) -> Self {
        self.is_default = true;
        self
    }
}

/// DIObjCProperty — an Objective-C property descriptor.
///
/// @llvm_behavior: `DIObjCProperty` maps to `!DIObjCProperty(...)` in
/// LLVM IR. It describes a property declaration in an Objective-C class.
#[derive(Debug, Clone)]
pub struct DIObjCProperty {
    /// The property name.
    pub name: String,
    /// Metadata ID of the file where the property is declared.
    pub file: u32,
    /// Line number of the declaration.
    pub line: u32,
    /// Getter method name.
    pub getter_name: String,
    /// Setter method name.
    pub setter_name: String,
    /// Property attributes (bitmask of ObjCPropertyAttribute values).
    pub attributes: u32,
    /// Metadata ID of the property's type.
    pub ty: u32,
}

/// Objective-C property attribute flags.
pub mod objc_property_attribute {
    pub const READONLY: u32 = 1 << 0;
    pub const READWRITE: u32 = 1 << 1;
    pub const ASSIGN: u32 = 1 << 2;
    pub const COPY: u32 = 1 << 3;
    pub const RETAIN: u32 = 1 << 4;
    pub const NONATOMIC: u32 = 1 << 5;
    pub const ATOMIC: u32 = 1 << 6;
    pub const WEAK: u32 = 1 << 7;
    pub const STRONG: u32 = 1 << 8;
    pub const UNSAFE_UNRETAINED: u32 = 1 << 9;
    pub const NULLABILITY: u32 = 1 << 10;
    pub const NULL_RESETTABLE: u32 = 1 << 11;
    pub const CLASS: u32 = 1 << 12;
    pub const DIRECT: u32 = 1 << 13;
}

impl DIObjCProperty {
    /// Create a new DIObjCProperty.
    pub fn new(
        name: String,
        file: u32,
        line: u32,
        getter_name: String,
        setter_name: String,
        attributes: u32,
        ty: u32,
    ) -> Self {
        Self {
            name,
            file,
            line,
            getter_name,
            setter_name,
            attributes,
            ty,
        }
    }

    /// Returns true if the property is read-only.
    pub fn is_readonly(&self) -> bool {
        self.attributes & objc_property_attribute::READONLY != 0
    }

    /// Returns true if the property is read-write.
    pub fn is_readwrite(&self) -> bool {
        self.attributes & objc_property_attribute::READWRITE != 0
    }

    /// Returns true if the property uses retain semantics.
    pub fn is_retain(&self) -> bool {
        self.attributes & objc_property_attribute::RETAIN != 0
    }

    /// Returns true if the property uses copy semantics.
    pub fn is_copy(&self) -> bool {
        self.attributes & objc_property_attribute::COPY != 0
    }

    /// Returns true if the property is non-atomic.
    pub fn is_nonatomic(&self) -> bool {
        self.attributes & objc_property_attribute::NONATOMIC != 0
    }

    /// Returns true if the property is weak.
    pub fn is_weak(&self) -> bool {
        self.attributes & objc_property_attribute::WEAK != 0
    }

    /// Returns true if the property is strong.
    pub fn is_strong(&self) -> bool {
        self.attributes & objc_property_attribute::STRONG != 0
    }
}

/// DIImportedEntity — an imported entity descriptor (using declaration,
/// using directive, etc.).
///
/// @llvm_behavior: `DIImportedEntity` maps to `!DIImportedEntity(...)` in
/// LLVM IR. It describes an entity imported into a scope, such as a C++
/// `using` declaration, `using namespace` directive, or module import.
#[derive(Debug, Clone)]
pub struct DIImportedEntity {
    /// DWARF tag (e.g., DW_TAG_imported_module = 58,
    /// DW_TAG_imported_declaration = 8).
    pub tag: u32,
    /// Metadata ID of the scope into which the entity is imported.
    pub scope: u32,
    /// Metadata ID of the imported entity/declaration.
    pub entity: u32,
    /// Metadata ID of the file where the import occurs.
    pub file: Option<u32>,
    /// Line number where the import occurs.
    pub line: Option<u32>,
    /// Optional name (for imported declarations).
    pub name: Option<String>,
}

impl DIImportedEntity {
    /// Create a new DIImportedEntity.
    pub fn new(tag: u32, scope: u32, entity: u32) -> Self {
        Self {
            tag,
            scope,
            entity,
            file: None,
            line: None,
            name: None,
        }
    }

    /// Create an imported module (using namespace / import module).
    pub fn imported_module(scope: u32, entity: u32) -> Self {
        Self::new(dwarf_tag::IMPORTED_MODULE, scope, entity)
    }

    /// Create an imported declaration (using declaration).
    pub fn imported_declaration(
        scope: u32,
        entity: u32,
        name: String,
        file: u32,
        line: u32,
    ) -> Self {
        Self {
            tag: dwarf_tag::IMPORTED_DECLARATION,
            scope,
            entity,
            file: Some(file),
            line: Some(line),
            name: Some(name),
        }
    }

    /// Returns true if this is an imported module.
    pub fn is_imported_module(&self) -> bool {
        self.tag == dwarf_tag::IMPORTED_MODULE
    }

    /// Returns true if this is an imported declaration.
    pub fn is_imported_declaration(&self) -> bool {
        self.tag == dwarf_tag::IMPORTED_DECLARATION
    }

    /// Set the file and line (builder pattern).
    pub fn with_file_line(mut self, file: u32, line: u32) -> Self {
        self.file = Some(file);
        self.line = Some(line);
        self
    }

    /// Set the name (builder pattern).
    pub fn with_name(mut self, name: String) -> Self {
        self.name = Some(name);
        self
    }
}

impl DIScope for DIImportedEntity {
    fn get_scope_name(&self) -> &str {
        self.name.as_deref().unwrap_or("<imported>")
    }

    fn get_scope_file(&self) -> Option<u32> {
        self.file
    }

    fn get_scope_line(&self) -> Option<u32> {
        self.line
    }
}

// ============================================================================
// DIFile extensions — additional methods for the existing DIFile struct
// ============================================================================

impl DIFile {
    /// Sets the checksum kind (e.g., "CSK_MD5", "CSK_SHA1", "CSK_SHA256").
    pub fn set_checksum_kind(&mut self, kind: String) {
        self.checksum_kind = Some(kind);
    }

    /// Sets the checksum value (hex-encoded digest string).
    pub fn set_checksum_value(&mut self, value: String) {
        self.checksum_value = Some(value);
    }

    /// Sets the source text (for embedded source support).
    pub fn set_source(&mut self, source: String) {
        self.source = Some(source);
    }

    /// Returns the checksum kind, if set.
    pub fn get_checksum_kind(&self) -> Option<&str> {
        self.checksum_kind.as_deref()
    }

    /// Returns the checksum value, if set.
    pub fn get_checksum_value(&self) -> Option<&str> {
        self.checksum_value.as_deref()
    }

    /// Returns the embedded source text, if set.
    pub fn get_source(&self) -> Option<&str> {
        self.source.as_deref()
    }

    /// Returns true if checksum information is present.
    pub fn has_checksum(&self) -> bool {
        self.checksum_kind.is_some() && self.checksum_value.is_some()
    }

    /// Returns true if source text is embedded.
    pub fn has_source(&self) -> bool {
        self.source.is_some()
    }

    /// Creates a builder-style setter for the checksum kind.
    pub fn with_checksum_kind(mut self, kind: String) -> Self {
        self.checksum_kind = Some(kind);
        self
    }

    /// Creates a builder-style setter for the checksum value.
    pub fn with_checksum_value(mut self, value: String) -> Self {
        self.checksum_value = Some(value);
        self
    }

    /// Creates a builder-style setter for the source text.
    pub fn with_source(mut self, source: String) -> Self {
        self.source = Some(source);
        self
    }

    /// Creates a MD5 checksum entry (convenience).
    pub fn with_md5_checksum(mut self, value: String) -> Self {
        self.checksum_kind = Some("CSK_MD5".to_string());
        self.checksum_value = Some(value);
        self
    }

    /// Creates a SHA1 checksum entry (convenience).
    pub fn with_sha1_checksum(mut self, value: String) -> Self {
        self.checksum_kind = Some("CSK_SHA1".to_string());
        self.checksum_value = Some(value);
        self
    }
}

// ============================================================================
// DIExpression — debug info expression for variable locations
// ============================================================================

/// A debug info expression: a sequence of DW_OP_* operations describing
/// how to compute the value or address of a variable.
///
/// @llvm_behavior: `DIExpression` maps to `!DIExpression(...)` in LLVM IR.
/// It encodes a DWARF expression — a sequence of opcodes that the debugger
/// evaluates to find the location of a variable. Common operations include
/// `DW_OP_regN` (value is in register N), `DW_OP_fbreg` (value is at an
/// offset from the frame base), and `DW_OP_LLVM_fragment` (the value is a
/// subrange of bits within a larger location).
///
/// The expression can also carry fragment information (offset and size in
/// bits) to describe partial locations (e.g., a struct field within a
/// register).
#[derive(Debug, Clone, PartialEq)]
pub struct DIExpression {
    /// DWARF expression element sequence (raw u64 values encoding opcodes
    /// and their operands).
    elements: Vec<u64>,
    /// Optional fragment information: (offset_in_bits, size_in_bits).
    /// This is extracted from a trailing `DW_OP_LLVM_fragment` if present.
    fragment: Option<(u64, u64)>,
}

impl DIExpression {
    /// Create a new DIExpression from a vector of elements.
    /// Fragment information is automatically extracted if a trailing
    /// `DW_OP_LLVM_fragment` is present.
    pub fn new(elements: Vec<u64>) -> Self {
        let mut expr = Self {
            elements,
            fragment: None,
        };
        expr.extract_fragment();
        expr
    }

    /// Create an empty DIExpression (no operations).
    pub fn empty() -> Self {
        Self {
            elements: Vec::new(),
            fragment: None,
        }
    }

    /// Create a DIExpression that represents a fragment of a value.
    /// `offset_in_bits` is the bit offset from the start of the containing
    /// location; `size_in_bits` is the number of bits in the fragment.
    pub fn create_fragment_expression(offset_in_bits: u64, size_in_bits: u64) -> Self {
        Self {
            elements: vec![dwarf_op::LLVM_FRAGMENT, offset_in_bits, size_in_bits],
            fragment: Some((offset_in_bits, size_in_bits)),
        }
    }

    /// Extract fragment information from the last three elements, if they
    /// form a `DW_OP_LLVM_fragment` operation.
    fn extract_fragment(&mut self) {
        let len = self.elements.len();
        if len >= 3 && self.elements[len - 3] == dwarf_op::LLVM_FRAGMENT {
            self.fragment = Some((self.elements[len - 2], self.elements[len - 1]));
        }
    }

    /// Returns true if the expression is valid (not empty or has fragment info).
    pub fn is_valid(&self) -> bool {
        !self.elements.is_empty() || self.fragment.is_some()
    }

    /// Returns the fragment information as (offset_in_bits, size_in_bits),
    /// if a fragment is present.
    pub fn get_fragment_info(&self) -> Option<(u64, u64)> {
        self.fragment
    }

    /// Returns the element at the given index, or None if out of bounds.
    pub fn get_element(&self, index: usize) -> Option<u64> {
        self.elements.get(index).copied()
    }

    /// Returns the total number of elements in the expression.
    pub fn get_num_elements(&self) -> usize {
        self.elements.len()
    }

    /// Returns the raw elements slice.
    pub fn elements(&self) -> &[u64] {
        &self.elements
    }

    /// Returns true if the expression is complex (more than a simple
    /// register or frame-base reference). A complex expression involves
    /// arithmetic, dereferencing, or multiple operations.
    pub fn is_complex(&self) -> bool {
        // An expression is complex if it has more than one operation
        // besides fragment info, or contains arithmetic/computation ops.
        let non_fragment_len = if self.fragment.is_some() {
            self.elements.len().saturating_sub(3)
        } else {
            self.elements.len()
        };
        if non_fragment_len > 2 {
            return true;
        }
        if non_fragment_len == 1 {
            let op = self.elements[0];
            // Simple single-op: register, fbreg, or empty.
            let is_simple_register = (dwarf_op::REG0..=dwarf_op::REG31).contains(&op);
            let is_simple_fbreg = op == dwarf_op::FBREG;
            if is_simple_register || is_simple_fbreg {
                return false;
            }
        }
        non_fragment_len > 0
    }

    /// Returns true if the expression is an implicit location description
    /// (last element is `DW_OP_stack_value` = 0x9f).
    pub fn is_implicit(&self) -> bool {
        self.elements
            .last()
            .map_or(false, |&e| e == dwarf_op::STACK_VALUE)
    }

    /// Returns true if the expression represents a constant value
    /// (starts with `DW_OP_constu` or `DW_OP_consts`).
    pub fn is_constant(&self) -> bool {
        if self.elements.is_empty() {
            return false;
        }
        let first = self.elements[0];
        first == dwarf_op::CONSTU || first == dwarf_op::CONSTS
    }

    /// Append an element to the expression. If a fragment is present at the
    /// end, the new element is inserted before the fragment operation.
    pub fn append(&mut self, element: u64) {
        if let Some(_) = self.fragment {
            let insert_pos = self.elements.len() - 3;
            self.elements.insert(insert_pos, element);
        } else {
            self.elements.push(element);
        }
    }

    /// Prepend an element to the beginning of the expression.
    pub fn prepend(&mut self, element: u64) {
        self.elements.insert(0, element);
    }

    /// Get the operand value that follows an opcode at the given index.
    /// For example, `DW_OP_constu` is followed by a ULEB128-encoded constant.
    /// Returns the next element in the sequence, or None if at the end.
    pub fn get_expr_operand(&self, index: usize) -> Option<u64> {
        if index + 1 < self.elements.len() {
            Some(self.elements[index + 1])
        } else {
            None
        }
    }

    /// Create a simple register expression (`DW_OP_regN`).
    /// The register number must be 0-31 for `DW_OP_reg0..DW_OP_reg31`.
    /// For register numbers >= 32 use `reg_x` instead.
    pub fn reg(register: u64) -> Self {
        assert!(register < 32, "Use reg_x for register numbers >= 32");
        Self {
            elements: vec![dwarf_op::REG0 + register],
            fragment: None,
        }
    }

    /// Create an extended register expression (`DW_OP_regx reg`).
    /// This supports any register number.
    pub fn reg_x(register: u64) -> Self {
        Self {
            elements: vec![dwarf_op::REGX, register],
            fragment: None,
        }
    }

    /// Create a frame-base relative expression (`DW_OP_fbreg offset`).
    /// `offset` is a signed offset from the frame base pointer.
    pub fn fb_reg(offset: i64) -> Self {
        Self {
            elements: vec![dwarf_op::FBREG, offset as u64],
            fragment: None,
        }
    }

    /// Create a "dereference" expression (`DW_OP_deref`).
    pub fn deref() -> Self {
        Self {
            elements: vec![dwarf_op::DEREF],
            fragment: None,
        }
    }

    /// Create a "plus" expression (`DW_OP_plus`).
    /// Pops two values from the stack and pushes their sum.
    pub fn plus() -> Self {
        Self {
            elements: vec![dwarf_op::PLUS],
            fragment: None,
        }
    }

    /// Create a constant unsigned expression (`DW_OP_constu val`).
    pub fn const_u(val: u64) -> Self {
        Self {
            elements: vec![dwarf_op::CONSTU, val],
            fragment: None,
        }
    }

    /// Create a constant signed expression (`DW_OP_consts val`).
    pub fn const_s(val: i64) -> Self {
        Self {
            elements: vec![dwarf_op::CONSTS, val as u64],
            fragment: None,
        }
    }

    /// Create a stack-value marker expression (`DW_OP_stack_value`).
    /// This marks the top of the stack as the value (vs. address) of the variable.
    pub fn stack_value() -> Self {
        Self {
            elements: vec![dwarf_op::STACK_VALUE],
            fragment: None,
        }
    }

    /// Create an "and" expression (`DW_OP_and`).
    pub fn and() -> Self {
        Self {
            elements: vec![dwarf_op::AND],
            fragment: None,
        }
    }

    /// Create an "or" expression (`DW_OP_or`).
    pub fn or() -> Self {
        Self {
            elements: vec![dwarf_op::OR],
            fragment: None,
        }
    }

    /// Create an "xor" expression (`DW_OP_xor`).
    pub fn xor() -> Self {
        Self {
            elements: vec![dwarf_op::XOR],
            fragment: None,
        }
    }

    /// Create a "not" expression (`DW_OP_not`).
    pub fn not() -> Self {
        Self {
            elements: vec![dwarf_op::NOT],
            fragment: None,
        }
    }

    /// Create a "neg" expression (`DW_OP_neg`).
    pub fn neg() -> Self {
        Self {
            elements: vec![dwarf_op::NEG],
            fragment: None,
        }
    }

    /// Create an "address of" expression (`DW_OP_addr` followed by address value).
    pub fn addr(address: u64) -> Self {
        Self {
            elements: vec![dwarf_op::ADDR, address],
            fragment: None,
        }
    }

    /// Create an entry value expression (`DW_OP_LLVM_entry_value`).
    /// This describes the value of a variable at function entry.
    pub fn entry_value(expr: &DIExpression) -> Self {
        let mut elements = vec![dwarf_op::LLVM_ENTRY_VALUE];
        // Encode the nested expression length and elements.
        elements.push(expr.elements.len() as u64);
        elements.extend_from_slice(&expr.elements);
        Self {
            elements,
            fragment: None,
        }
    }

    /// Create a bit-piece expression (DW_OP_bit_piece size offset).
    pub fn bit_piece(size_in_bits: u64, offset_in_bits: u64) -> Self {
        Self {
            elements: vec![dwarf_op::BIT_PIECE, size_in_bits, offset_in_bits],
            fragment: None,
        }
    }

    /// Add fragment information to the expression. If a fragment already
    /// exists, it is replaced.
    pub fn with_fragment(mut self, offset_in_bits: u64, size_in_bits: u64) -> Self {
        // Remove existing fragment if present.
        if self.fragment.is_some() {
            let len = self.elements.len();
            if len >= 3 && self.elements[len - 3] == dwarf_op::LLVM_FRAGMENT {
                self.elements.truncate(len - 3);
            }
        }
        self.elements.push(dwarf_op::LLVM_FRAGMENT);
        self.elements.push(offset_in_bits);
        self.elements.push(size_in_bits);
        self.fragment = Some((offset_in_bits, size_in_bits));
        self
    }

    /// Create an implicit pointer expression (DW_OP_implicit_pointer).
    pub fn implicit_pointer(deref_id: u64, offset: i64) -> Self {
        Self {
            elements: vec![dwarf_op::IMPLICIT_POINTER, deref_id, offset as u64],
            fragment: None,
        }
    }

    /// Returns a human-readable debug string for the expression.
    pub fn to_debug_string(&self) -> String {
        if self.elements.is_empty() {
            return "<empty>".to_string();
        }
        let parts: Vec<String> = self.elements.iter().map(|e| format!("0x{:x}", e)).collect();
        parts.join(", ")
    }

    /// Returns true if the expression can be folded to a constant at
    /// compile time (contains only constants and stack_value).
    pub fn is_constant_expression(&self) -> bool {
        if self.elements.is_empty() {
            return false;
        }
        // A constant expression starts with a const operation and ends
        // with stack_value.
        let first = self.elements[0];
        let last = *self.elements.last().unwrap();
        matches!(first, dwarf_op::CONSTU | dwarf_op::CONSTS) && last == dwarf_op::STACK_VALUE
    }

    /// Combine two expressions by concatenating their elements (excluding
    /// fragments).
    pub fn combine(&self, other: &DIExpression) -> Self {
        let mut elements = Vec::with_capacity(
            self.non_fragment_elements().len() + other.non_fragment_elements().len(),
        );
        elements.extend_from_slice(self.non_fragment_elements());
        elements.extend_from_slice(other.non_fragment_elements());
        Self::new(elements)
    }

    /// Returns the elements excluding any trailing fragment operation.
    fn non_fragment_elements(&self) -> &[u64] {
        if self.fragment.is_some() && self.elements.len() >= 3 {
            &self.elements[..self.elements.len() - 3]
        } else {
            &self.elements
        }
    }
}

// ============================================================================
// Metadata Attachment — per-value metadata associations
// ============================================================================

/// Methods for attaching metadata to IR values (instructions, globals,
/// functions, etc.).
///
/// @llvm_behavior: LLVM allows metadata to be "attached" to instructions
/// and other values using a metadata kind string. For example, a load
/// instruction might have `!tbaa !5` and `!alias.scope !10` attached.
/// These methods manage those per-value, per-kind associations.
impl MetadataStore {
    /// Attach metadata of a given kind to a value.
    ///
    /// `value_index` identifies the IR value (instruction index, global index,
    /// etc.). `kind` is the metadata kind name (e.g., `"dbg"`, `"tbaa"`).
    /// `metadata_id` is the metadata node ID to attach.
    ///
    /// Multiple metadata of different kinds can be attached to the same value.
    pub fn attach_metadata(&mut self, value_index: usize, kind: &str, metadata_id: u32) {
        let attachments = self.metadata_attachments.entry(value_index).or_default();
        attachments.push((kind.to_string(), metadata_id));
    }

    /// Get the metadata attachment for a specific value and kind.
    ///
    /// Returns the metadata ID if found, or `None` if no attachment of that
    /// kind exists for the given value.
    pub fn get_metadata_attachment(&self, value_index: usize, kind: &str) -> Option<u32> {
        self.metadata_attachments
            .get(&value_index)
            .and_then(|attachments| {
                attachments
                    .iter()
                    .find(|(k, _)| k == kind)
                    .map(|(_, id)| *id)
            })
    }

    /// Erase (remove) a specific metadata attachment from a value.
    ///
    /// If no attachment of the given kind exists for the value, this is a no-op.
    pub fn erase_metadata_attachment(&mut self, value_index: usize, kind: &str) {
        if let Some(attachments) = self.metadata_attachments.get_mut(&value_index) {
            attachments.retain(|(k, _)| k != kind);
        }
    }

    /// Get all metadata attachments for a value.
    ///
    /// Returns a slice of `(kind, metadata_id)` pairs. The returned slice
    /// is empty if no attachments exist for the given value.
    pub fn get_all_metadata_attachments(&self, value_index: usize) -> &[(String, u32)] {
        match self.metadata_attachments.get(&value_index) {
            Some(attachments) => attachments.as_slice(),
            None => &[],
        }
    }

    /// Set (replace or add) a metadata attachment for a value.
    ///
    /// If an attachment of the same kind already exists for the given value,
    /// it is replaced with the new metadata ID. Otherwise, the attachment
    /// is added as a new entry.
    pub fn set_metadata_attachment(&mut self, value_index: usize, kind: &str, metadata_id: u32) {
        let attachments = self.metadata_attachments.entry(value_index).or_default();
        if let Some(existing) = attachments.iter_mut().find(|(k, _)| k == kind) {
            *existing = (kind.to_string(), metadata_id);
        } else {
            attachments.push((kind.to_string(), metadata_id));
        }
    }

    /// Returns true if the given value has any metadata attachments.
    pub fn has_metadata_attachments(&self, value_index: usize) -> bool {
        self.metadata_attachments
            .get(&value_index)
            .map_or(false, |v| !v.is_empty())
    }

    /// Remove all metadata attachments from a value.
    pub fn erase_all_metadata_attachments(&mut self, value_index: usize) {
        self.metadata_attachments.remove(&value_index);
    }

    /// Returns the number of metadata attachments for a value.
    pub fn num_metadata_attachments(&self, value_index: usize) -> usize {
        self.metadata_attachments
            .get(&value_index)
            .map_or(0, |v| v.len())
    }

    /// Iterate over all values that have metadata attachments.
    /// Returns an iterator yielding `(value_index, &[(kind, id)])` pairs.
    pub fn iter_metadata_attachments(&self) -> impl Iterator<Item = (usize, &[(String, u32)])> {
        self.metadata_attachments
            .iter()
            .map(|(&idx, attachments)| (idx, attachments.as_slice()))
    }

    /// Copy all metadata attachments from one value to another.
    pub fn copy_metadata_attachments(&mut self, from: usize, to: usize) {
        if let Some(attachments) = self.metadata_attachments.get(&from) {
            let cloned: Vec<(String, u32)> = attachments.clone();
            self.metadata_attachments.insert(to, cloned);
        }
    }
}

// ============================================================================
// Extended MetadataStore Methods — temporary nodes, uniquing, named metadata
// ============================================================================

impl MetadataStore {
    /// Get a metadata string value by ID. Returns the string if the metadata
    /// at the given ID is an MDString, or `None` otherwise.
    ///
    /// This complements the existing `create_md_string` with a getter.
    pub fn get_md_string(&self, id: u32) -> Option<&str> {
        self.get_metadata(id).and_then(|mv| match &mv.kind {
            MetadataKind::MDString(s) => Some(s.as_str()),
            _ => None,
        })
    }

    /// Create a temporary metadata node. Temporary nodes can be created
    /// before all their operands are known, and later resolved (replaced)
    /// with final metadata nodes.
    ///
    /// @llvm_behavior: LLVM's `MDNode::getTemporary()` creates a node that
    /// is not yet uniqued and can be replaced via RAUW.
    pub fn create_temporary_md_node(&mut self, operands: Vec<MetadataOperand>) -> u32 {
        let id = self.values.len() as u32;
        self.values.push(MetadataValue {
            id,
            kind: MetadataKind::MDNode(operands.clone()),
        });
        self.temporary_nodes
            .insert(id, TemporaryNodeState::new(operands));
        id
    }

    /// Replace a temporary MDNode with a resolved (permanent) node.
    ///
    /// Conceptually, all uses of the temporary node are updated to refer
    /// to the replacement. In this implementation, the temporary node's
    /// value is updated in-place and its state is marked as resolved.
    pub fn replace_temporary_md_node(&mut self, temp_id: u32, replacement_id: u32) {
        if let Some(temp) = self.temporary_nodes.get_mut(&temp_id) {
            temp.resolved = true;
            temp.replacement = Some(replacement_id);
        }
        // Update the stored metadata value to reference the replacement.
        if let Some(mv) = self.values.get_mut(temp_id as usize) {
            mv.kind = MetadataKind::MDNode(vec![MetadataOperand::Metadata(replacement_id)]);
        }
    }

    /// Resolve all temporary MDNodes by walking all metadata values and
    /// replacing references to resolved temporaries with their replacements.
    ///
    /// This processes named nodes and all MDNode/MDTuple operands.
    pub fn resolve_temporary_md_nodes(&mut self) {
        // Collect all resolved replacements.
        let replacements: Vec<(u32, u32)> = self
            .temporary_nodes
            .iter()
            .filter_map(|(&temp_id, state)| {
                if state.resolved {
                    state.replacement.map(|rep_id| (temp_id, rep_id))
                } else {
                    None
                }
            })
            .collect();

        if replacements.is_empty() {
            return;
        }

        // Walk all metadata values and replace references.
        for mv in &mut self.values {
            match &mut mv.kind {
                MetadataKind::MDNode(ops)
                | MetadataKind::DistinctMDNode(ops)
                | MetadataKind::MDTuple(ops) => {
                    for op in ops {
                        if let MetadataOperand::Metadata(id) = op {
                            for (temp_id, rep_id) in &replacements {
                                if *id == *temp_id {
                                    *id = *rep_id;
                                }
                            }
                        }
                    }
                }
                _ => {}
            }
        }

        // Update named metadata nodes.
        for (_name, operands) in &mut self.named_nodes {
            for op_id in operands {
                for (temp_id, rep_id) in &replacements {
                    if *op_id == *temp_id {
                        *op_id = *rep_id;
                    }
                }
            }
        }

        // Update metadata attachments.
        for (_value_idx, attachments) in &mut self.metadata_attachments {
            for (_kind, md_id) in attachments {
                for (temp_id, rep_id) in &replacements {
                    if *md_id == *temp_id {
                        *md_id = *rep_id;
                    }
                }
            }
        }
    }

    /// Returns true if the metadata at the given ID is marked as distinct.
    ///
    /// Distinct nodes are guaranteed to be unique even if structurally
    /// identical to another node. They are never merged or uniqued.
    pub fn is_distinct(&self, id: u32) -> bool {
        self.get_metadata(id).map_or(false, |mv| {
            matches!(mv.kind, MetadataKind::DistinctMDNode(_))
        })
    }

    /// Returns true if the metadata at the given ID is a temporary node.
    pub fn is_temporary(&self, id: u32) -> bool {
        self.temporary_nodes.contains_key(&id)
    }

    /// Returns true if the temporary node at the given ID has been resolved
    /// (replaced) with a permanent node.
    pub fn is_resolved(&self, id: u32) -> bool {
        self.temporary_nodes
            .get(&id)
            .map_or(false, |state| state.resolved)
    }

    /// Returns true if the metadata at the given ID is uniqued (not distinct
    /// and not temporary). Uniqued nodes with identical operands may be
    /// merged with existing nodes when created.
    pub fn is_uniqued(&self, id: u32) -> bool {
        self.get_metadata(id).map_or(false, |mv| {
            matches!(mv.kind, MetadataKind::MDNode(_) | MetadataKind::MDTuple(_))
                && !self.temporary_nodes.contains_key(&id)
        })
    }

    /// Create a uniqued MDNode. If an existing MDNode has identical operands
    /// (and is not temporary), its ID is returned instead of creating a new
    /// node. Otherwise, a new MDNode is created.
    pub fn create_uniqued_md_node(&mut self, operands: Vec<MetadataOperand>) -> u32 {
        // Search for an existing MDNode with identical operands.
        for mv in &self.values {
            if let MetadataKind::MDNode(existing_ops) = &mv.kind {
                // Skip temporary nodes — temporaries are never uniqued against.
                if self.temporary_nodes.contains_key(&mv.id) {
                    continue;
                }
                if operands_match(existing_ops, &operands) {
                    return mv.id;
                }
            }
        }
        // No match found; create a new one.
        self.create_md_node(operands)
    }

    /// Add a named metadata node. Alias for `add_named_node`.
    pub fn add_named_metadata(&mut self, name: &str, operands: Vec<u32>) {
        self.add_named_node(name, operands);
    }

    /// Get a named metadata node's operands by name. Alias for `get_named_node`.
    pub fn get_named_metadata(&self, name: &str) -> Option<&Vec<u32>> {
        self.get_named_node(name)
    }

    /// Get or create a named metadata node. If the named node does not exist,
    /// it is created with an empty operand list. Returns an immutable reference
    /// to the operand list.
    pub fn get_or_create_named_metadata(&mut self, name: &str) -> &Vec<u32> {
        if !self.named_nodes.contains_key(name) {
            self.named_nodes.insert(name.to_string(), Vec::new());
        }
        self.named_nodes.get(name).unwrap()
    }

    /// Get or create a named metadata node with mutable access to the operand
    /// list.
    pub fn get_or_create_named_metadata_mut(&mut self, name: &str) -> &mut Vec<u32> {
        self.named_nodes
            .entry(name.to_string())
            .or_insert_with(Vec::new)
    }

    /// Erase (remove) a named metadata node. Alias for `remove_named_node`.
    pub fn erase_named_metadata(&mut self, name: &str) {
        self.remove_named_node(name);
    }

    /// Returns true if the given metadata ID is a distinct node.
    /// This is the same as `is_distinct`, provided for API completeness.
    pub fn is_distinct_node(&self, id: u32) -> bool {
        self.is_distinct(id)
    }

    /// Returns true if the given metadata ID is a temporary node that has
    /// not yet been resolved.
    pub fn is_unresolved_temporary(&self, id: u32) -> bool {
        self.is_temporary(id) && !self.is_resolved(id)
    }

    /// Return the replacement ID for a resolved temporary node, if any.
    pub fn get_temporary_replacement(&self, id: u32) -> Option<u32> {
        self.temporary_nodes
            .get(&id)
            .and_then(|state| state.replacement)
    }

    /// Returns the number of temporary metadata nodes (both resolved and
    /// unresolved).
    pub fn num_temporaries(&self) -> usize {
        self.temporary_nodes.len()
    }

    /// Returns the number of unresolved temporary nodes.
    pub fn num_unresolved_temporaries(&self) -> usize {
        self.temporary_nodes
            .values()
            .filter(|state| !state.resolved)
            .count()
    }

    /// Add a DIBasicType to the store and return its metadata ID.
    /// The DIBasicType is converted to the common DIType format for
    /// storage compatibility.
    pub fn add_di_basic_type(&mut self, basic: DIBasicType) -> u32 {
        let id = self.debug_types.len() as u32;
        let ty = DIType {
            name: basic.name,
            size_in_bits: basic.size_in_bits,
            align_in_bits: basic.align_in_bits,
            offset_in_bits: 0,
            encoding: basic.encoding,
            base_type: None,
            file: None,
            line: None,
            tag: 36, // DW_TAG_base_type
            flags: basic.flags,
        };
        self.debug_types.push(Some(ty));
        id
    }

    /// Returns an iterator over all metadata values (excluding named nodes).
    pub fn iter_metadata(&self) -> impl Iterator<Item = &MetadataValue> {
        self.values.iter()
    }

    /// Returns an iterator over all named metadata entries.
    pub fn iter_named_metadata(&self) -> impl Iterator<Item = (&String, &Vec<u32>)> {
        self.named_nodes.iter()
    }

    /// Dump the entire metadata store to a human-readable string (for
    /// debugging).
    pub fn dump_debug(&self) -> String {
        let mut lines = Vec::new();
        lines.push(format!(
            "MetadataStore: {} values, {} named nodes",
            self.values.len(),
            self.named_nodes.len()
        ));
        for mv in &self.values {
            let kind_str = match &mv.kind {
                MetadataKind::MDString(s) => format!("MDString(\"{}\")", s),
                MetadataKind::Constant(c) => format!("Constant({})", c.to_string()),
                MetadataKind::Value(v) => format!("Value(%{})", v),
                MetadataKind::MDNode(ops) => {
                    format!("MDNode([{} ops])", ops.len())
                }
                MetadataKind::DistinctMDNode(ops) => {
                    format!("DistinctMDNode([{} ops])", ops.len())
                }
                MetadataKind::MDTuple(ops) => {
                    format!("MDTuple([{} ops])", ops.len())
                }
                MetadataKind::NamedNode(name, _) => format!("NamedNode({})", name),
            };
            lines.push(format!("  !{} = {}", mv.id, kind_str));
        }
        for (name, ops) in &self.named_nodes {
            lines.push(format!("  !{} -> [{} ops]", name, ops.len()));
        }
        lines.join("\n")
    }
}

/// Compare two metadata operand slices for structural equality.
///
/// Two operand slices match if they have the same length and each pair
/// of corresponding operands is equal. Constant equality is checked
/// by debug string representation (a simplification; full implementations
/// would compare constant values directly).
fn operands_match(a: &[MetadataOperand], b: &[MetadataOperand]) -> bool {
    if a.len() != b.len() {
        return false;
    }
    a.iter().zip(b.iter()).all(|(a, b)| match (a, b) {
        (MetadataOperand::Metadata(id_a), MetadataOperand::Metadata(id_b)) => id_a == id_b,
        (MetadataOperand::MDString(s_a), MetadataOperand::MDString(s_b)) => s_a == s_b,
        (MetadataOperand::Null, MetadataOperand::Null) => true,
        (MetadataOperand::Value(v_a), MetadataOperand::Value(v_b)) => v_a == v_b,
        (MetadataOperand::Constant(c_a), MetadataOperand::Constant(c_b)) => {
            c_a.to_string() == c_b.to_string()
        }
        _ => false,
    })
}

// ============================================================================
// Checksum Kind Constants
// ============================================================================

/// Standard checksum kind strings for DIFile.
pub mod checksum_kind {
    pub const MD5: &str = "CSK_MD5";
    pub const SHA1: &str = "CSK_SHA1";
    pub const SHA256: &str = "CSK_SHA256";
}

// ============================================================================
// Emission Kind Constants
// ============================================================================

/// Emission kind values for DICompileUnit.
pub mod emission_kind {
    pub const FULL_DEBUG: u32 = 0;
    pub const LINE_TABLES_ONLY: u32 = 1;
    pub const NO_DEBUG: u32 = 2;
}

// ============================================================================
// Tests
// ============================================================================

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

    // === MetadataOperand tests ===

    #[test]
    fn test_metadata_operand_is_metadata_ref() {
        let op_ref = MetadataOperand::Metadata(42);
        assert!(op_ref.is_metadata_ref());
        assert_eq!(op_ref.as_metadata_id(), Some(42));

        let op_str = MetadataOperand::MDString("hello".to_string());
        assert!(!op_str.is_metadata_ref());
        assert_eq!(op_str.as_metadata_id(), None);

        let op_null = MetadataOperand::Null;
        assert!(!op_null.is_metadata_ref());
        assert_eq!(op_null.as_metadata_id(), None);
    }

    #[test]
    fn test_metadata_operand_debug_string() {
        assert_eq!(MetadataOperand::Metadata(7).to_debug_string(), "!7");
        assert_eq!(
            MetadataOperand::MDString("test".to_string()).to_debug_string(),
            "!\"test\""
        );
        assert_eq!(MetadataOperand::Null.to_debug_string(), "null");
    }

    // === ConstantValue tests ===

    #[test]
    fn test_constant_value_to_string() {
        let ci = ConstantValue::new_int(llvm_native_core::types::Type::i32(), 42);
        assert_eq!(ci.to_string(), "i32 42");

        let cf = ConstantValue::new_float(llvm_native_core::types::Type::double(), 3.14);
        assert!(cf.to_string().contains("3.14"));

        let cn = ConstantValue::null(llvm_native_core::types::Type::pointer(0));
        assert_eq!(cn.to_string(), "null");
    }

    // === MetadataStore basic tests ===

    #[test]
    fn test_metadata_store_new_empty() {
        let store = MetadataStore::new();
        assert!(store.is_empty());
        assert_eq!(store.count(), 0);
    }

    #[test]
    fn test_metadata_store_add_and_get() {
        let mut store = MetadataStore::new();

        let id1 = store.add_metadata(MetadataKind::MDString("hello".to_string()));
        let id2 = store.add_metadata(MetadataKind::MDString("world".to_string()));

        assert_eq!(id1, 0);
        assert_eq!(id2, 1);
        assert_eq!(store.count(), 2);

        let mv1 = store.get_metadata(0);
        assert!(mv1.is_some());
        if let MetadataKind::MDString(s) = &mv1.unwrap().kind {
            assert_eq!(s, "hello");
        } else {
            panic!("Expected MDString");
        }

        assert!(store.get_metadata(999).is_none());
    }

    #[test]
    fn test_metadata_store_mdnode() {
        let mut store = MetadataStore::new();

        let str_id = store.create_md_string("my_string");
        let node_id = store.create_md_node(vec![
            MetadataOperand::MDString("key".to_string()),
            MetadataOperand::Metadata(str_id),
            MetadataOperand::Null,
        ]);

        assert_eq!(str_id, 0);
        assert_eq!(node_id, 1);
        assert_eq!(store.count(), 2);

        let node = store.get_metadata(node_id).unwrap();
        match &node.kind {
            MetadataKind::MDNode(ops) => {
                assert_eq!(ops.len(), 3);
            }
            _ => panic!("Expected MDNode"),
        }
    }

    #[test]
    fn test_metadata_store_named_nodes() {
        let mut store = MetadataStore::new();

        let id0 = store.add_metadata(MetadataKind::MDString("flag1".to_string()));
        let id1 = store.add_metadata(MetadataKind::MDString("flag2".to_string()));

        store.add_named_node("llvm.module.flags", vec![id0, id1]);

        assert!(store.has_named_node("llvm.module.flags"));
        assert!(!store.has_named_node("nonexistent"));

        let ops = store.get_named_node("llvm.module.flags").unwrap();
        assert_eq!(ops.len(), 2);
        assert_eq!(ops[0], id0);
        assert_eq!(ops[1], id1);

        store.remove_named_node("llvm.module.flags");
        assert!(!store.has_named_node("llvm.module.flags"));
    }

    // === Debug info tests ===

    #[test]
    fn test_di_location() {
        let loc = DILocation::new(42, 10, 1);
        assert_eq!(loc.line, 42);
        assert_eq!(loc.column, 10);
        assert_eq!(loc.scope, 1);
        assert!(loc.inlined_at.is_none());

        let loc2 = DILocation::new(100, 5, 2).with_inlined_at(1);
        assert_eq!(loc2.inlined_at, Some(1));
    }

    #[test]
    fn test_di_file() {
        let file = DIFile::new("main.c".to_string(), "/home/user/src".to_string());
        assert_eq!(file.filename, "main.c");
        assert_eq!(file.full_path(), "/home/user/src/main.c");

        let file2 = DIFile::new("standalone.s".to_string(), String::new());
        assert_eq!(file2.full_path(), "standalone.s");
    }

    #[test]
    fn test_di_subprogram() {
        let sp = DISubprogram::new("my_func".to_string(), 0, 42, 1);
        assert_eq!(sp.name, "my_func");
        assert_eq!(sp.file, 0);
        assert_eq!(sp.line, 42);
        assert_eq!(sp.unit, 1);
        assert!(sp.is_definition);
        assert!(!sp.is_local);
    }

    #[test]
    fn test_di_type() {
        let ty = DIType::new_basic("int".to_string(), 32, 32, 5); // DW_ATE_signed = 5
        assert_eq!(ty.name, "int");
        assert_eq!(ty.size_in_bits, 32);
        assert_eq!(ty.align_in_bits, 32);
        assert_eq!(ty.size_in_bytes(), 4);
        assert_eq!(ty.encoding, 5);
    }

    #[test]
    fn test_di_local_variable() {
        let var = DILocalVariable::new("x".to_string(), 0, 1, 10, 2);
        assert_eq!(var.name, "x");
        assert_eq!(var.scope, 0);
        assert_eq!(var.line, 10);
        assert_eq!(var.var_type, 2);
        assert!(var.arg.is_none());
    }

    #[test]
    fn test_di_global_variable() {
        let var = DIGlobalVariable::new("g_counter".to_string(), 0, 1, 5, 2, false, true);
        assert_eq!(var.name, "g_counter");
        assert!(var.is_definition);
        assert!(!var.is_local_to_unit);
    }

    #[test]
    fn test_di_compile_unit() {
        let cu = DICompileUnit::new(12, 0, "clang 18.0".to_string()); // DW_LANG_C99 = 12
        assert_eq!(cu.language, 12);
        assert_eq!(cu.file, 0);
        assert_eq!(cu.producer, "clang 18.0");
        assert!(!cu.is_optimized);
        assert_eq!(cu.emission_kind, 0);
    }

    // === MetadataStore debug info operations ===

    #[test]
    fn test_metadata_store_debug_location() {
        let mut store = MetadataStore::new();
        let loc = DILocation::new(10, 5, 0);
        let id = store.add_debug_location(loc);

        let retrieved = store.get_debug_location(id);
        assert!(retrieved.is_some());
        assert_eq!(retrieved.unwrap().line, 10);
        assert_eq!(retrieved.unwrap().column, 5);
    }

    #[test]
    fn test_metadata_store_debug_file() {
        let mut store = MetadataStore::new();
        let file = DIFile::new("test.rs".to_string(), "/src".to_string());
        let id = store.add_debug_file(file);

        let retrieved = store.get_debug_file(id);
        assert!(retrieved.is_some());
        assert_eq!(retrieved.unwrap().filename, "test.rs");

        let found = store.find_debug_file("test.rs", "/src");
        assert_eq!(found, Some(id));

        let not_found = store.find_debug_file("nonexistent.rs", "/src");
        assert_eq!(not_found, None);
    }

    #[test]
    fn test_metadata_store_debug_subprogram() {
        let mut store = MetadataStore::new();
        let sp = DISubprogram::new("main".to_string(), 0, 1, 2);
        let id = store.add_debug_subprogram(sp);

        let retrieved = store.get_debug_subprogram(id);
        assert!(retrieved.is_some());
        assert_eq!(retrieved.unwrap().name, "main");

        let found = store.find_debug_subprogram("main");
        assert_eq!(found, Some(id));
        assert_eq!(store.find_debug_subprogram("nonexistent"), None);
    }

    #[test]
    fn test_metadata_store_debug_type() {
        let mut store = MetadataStore::new();
        let ty = DIType::new_basic("i32".to_string(), 32, 32, 5);
        let id = store.add_debug_type(ty);

        let retrieved = store.get_debug_type(id);
        assert!(retrieved.is_some());
        assert_eq!(retrieved.unwrap().name, "i32");
    }

    #[test]
    fn test_metadata_store_debug_var() {
        let mut store = MetadataStore::new();

        let local = DILocalVariable::new("x".to_string(), 0, 1, 5, 2);
        let local_id = store.add_debug_local_var(local);

        let global = DIGlobalVariable::new("g".to_string(), 0, 1, 3, 4, true, true);
        let global_id = store.add_debug_global_var(global);

        assert!(store.get_debug_local_var(local_id).is_some());
        assert!(store.get_debug_global_var(global_id).is_some());
        assert!(store.get_debug_local_var(999).is_none());
    }

    #[test]
    fn test_metadata_store_debug_compile_unit() {
        let mut store = MetadataStore::new();
        let cu = DICompileUnit::new(12, 0, "rustc".to_string());
        let id = store.add_debug_compile_unit(cu);

        let retrieved = store.get_debug_compile_unit(id);
        assert!(retrieved.is_some());
        assert_eq!(retrieved.unwrap().producer, "rustc");
    }

    #[test]
    fn test_metadata_store_emit_assembly() {
        let mut store = MetadataStore::new();

        store.add_metadata(MetadataKind::MDString("test".to_string()));
        store.create_md_node(vec![MetadataOperand::Metadata(0)]);
        store.add_named_node("llvm.ident", vec![0]);

        let asm = store.emit_assembly();
        assert!(asm.contains("test"));
        assert!(asm.contains("llvm.ident"));
    }

    #[test]
    fn test_metadata_store_default() {
        let store = MetadataStore::default();
        assert!(store.is_empty());
        assert_eq!(store.count(), 0);
    }

    #[test]
    fn test_metadata_store_set_debug_location() {
        let mut store = MetadataStore::new();
        store.set_debug_location(5, DILocation::new(50, 5, 1));

        let loc = store.get_debug_location(5);
        assert!(loc.is_some());
        assert_eq!(loc.unwrap().line, 50);
    }

    #[test]
    fn test_constant_value_zeroinit() {
        let cv = ConstantValue {
            ty: llvm_native_core::types::Type::i32(),
            repr: ConstantRepr::ZeroInitializer,
        };
        assert_eq!(cv.to_string(), "zeroinitializer");
    }

    #[test]
    fn test_metadata_value_id_consistency() {
        let mut store = MetadataStore::new();
        let ids: Vec<u32> = (0..10)
            .map(|i| store.add_metadata(MetadataKind::MDString(format!("v{}", i))))
            .collect();

        for (i, id) in ids.iter().enumerate() {
            assert_eq!(*id, i as u32);
            let mv = store.get_metadata(*id).unwrap();
            assert_eq!(mv.id, *id);
        }
    }

    #[test]
    fn test_metadata_store_mdref_helper() {
        let op = MetadataStore::md_ref(42);
        assert_eq!(op.as_metadata_id(), Some(42));

        let op_str = MetadataStore::md_string_op("hello");
        match op_str {
            MetadataOperand::MDString(s) => assert_eq!(s, "hello"),
            _ => panic!("Expected MDString"),
        }
    }

    #[test]
    fn test_dilocation_with_inlined_at() {
        let loc = DILocation::new(10, 1, 0).with_inlined_at(5);
        assert_eq!(loc.line, 10);
        assert_eq!(loc.column, 1);
        assert_eq!(loc.scope, 0);
        assert_eq!(loc.inlined_at, Some(5));
    }
}