dotscope 0.8.0

//! Metadata root header and stream directory for .NET assemblies.
//!
//! This module defines the [`crate::metadata::root::Root`] struct, which represents the root metadata header and stream
//! directory as specified by ECMA-335. It provides access to all metadata streams, version info,
//! and structural metadata required for parsing .NET assemblies.
//!
//! # Overview
//!
//! The metadata root is the entry point for reading .NET assembly metadata. It contains the version
//! string, stream directory, and other header fields required to locate and interpret all metadata
//! streams (such as `#~`, `#Strings`, `#Blob`, etc.).
//!
//! # Example
//!
//! ```rust,no_run
//! use dotscope::metadata::root::Root;
//! let root = Root::read(&[
//!            0x42, 0x53, 0x4A, 0x42,
//!            0x00, 0x20,
//!            0x00, 0x30,
//!            0x00, 0x00, 0x00, 0x40,
//!            0x05, 0x00, 0x00, 0x00,
//!            b'H', b'E', b'L', b'L', b'O',
//!            0x00, 0x60,
//!            0x01, 0x00,
//!            0x1, 0x00, 0x00, 0x00, // StreamHeader
//!            0x5, 0x00, 0x00, 0x00,
//!            0x23, 0x7E, 0x00,
//!        ])?;
//! println!("Metadata version: {}", root.version);
//! for stream in &root.stream_headers {
//!     println!("Stream: {} (offset: {}, size: {})", stream.name, stream.offset, stream.size);
//! }
//! # Ok::<(), dotscope::Error>(())
//! ```
//!
//! # References
//!
//! - [ECMA-335 II.24.2.1: Metadata root](https://ecma-international.org/wp-content/uploads/ECMA-335_6th_edition_june_2012.pdf)

use crate::{
    metadata::streams::StreamHeader,
    utils::{read_le, read_le_at},
    Error, ParseFailure, ParseStage, Result,
};
use std::io::Write;

/// The MAGIC value indicating the CIL header ("BSJB" in ASCII).
pub const CIL_HEADER_MAGIC: u32 = 0x424A_5342;

/// Minimum size in bytes required for a valid metadata root header.
/// This includes: signature(4) + major_version(2) + minor_version(2) + reserved(4) +
/// length(4) + version_string(min 4) + flags(2) + stream_number(2) + stream_header(min 12).
const MIN_ROOT_HEADER_SIZE: usize = 36;

/// Offset in the root header where the version string length field is located.
const VERSION_LENGTH_OFFSET: usize = 12;

/// Offset in the root header where the version string begins.
const VERSION_STRING_OFFSET: u16 = 16;

/// Size of the flags field following the version string.
const FLAGS_FIELD_SIZE: usize = 2;

/// Size of the stream count field.
const STREAM_COUNT_FIELD_SIZE: usize = 2;

/// Maximum allowed length for the version string.
const MAX_VERSION_STRING_LENGTH: usize = 255;

/// Maximum number of metadata streams allowed per ECMA-335.
/// Valid streams are: #Strings, #US, #Blob, #GUID, #~, #-
const MAX_STREAM_COUNT: u16 = 6;

/// Minimum size in bytes for a valid stream header.
/// This includes: offset(4) + size(4) + name(min 1 char + null terminator = 2, aligned to 4).
const MIN_STREAM_HEADER_SIZE: usize = 12;

/// Size of the fixed fields in a stream header (offset + size).
const STREAM_HEADER_FIXED_SIZE: usize = 8;

/// Maximum length for a stream name.
const MAX_STREAM_NAME_LENGTH: usize = 32;

/// Field offsets within the root header for fixed-position fields.
const FIELD_OFFSET_MAJOR_VERSION: usize = 4;
const FIELD_OFFSET_MINOR_VERSION: usize = 6;
const FIELD_OFFSET_RESERVED: usize = 8;

/// Represents the metadata root header and stream directory of a .NET assembly.
///
/// The Root structure is the entry point for all .NET assembly metadata parsing, containing
/// the metadata header information and directory of all available metadata streams. It follows
/// the ECMA-335 specification for physical metadata layout and provides access to version
/// information, stream locations, and structural metadata.
///
/// This structure is typically the first metadata component parsed when analyzing a .NET assembly,
/// as it provides the roadmap for locating all other metadata streams such as the tables stream (`#~`),
/// strings heap (`#Strings`), GUID heap (`#GUID`), blob heap (`#Blob`), and user strings heap (`#US`).
///
/// # Physical Layout
///
/// The metadata root follows this binary structure:
/// ```text
/// Offset | Size | Field           | Description
/// -------|------|-----------------|---------------------------
/// 0x00   | 4    | Signature       | Magic: 0x424A5342 ("BSJB")
/// 0x04   | 2    | MajorVersion    | Metadata format major version
/// 0x06   | 2    | MinorVersion    | Metadata format minor version  
/// 0x08   | 4    | Reserved        | Always 0
/// 0x0C   | 4    | Length          | Length of version string
/// 0x10   | N    | Version         | Version string (null-terminated)
/// ...    | 2    | Flags           | Reserved, always 0
/// ...    | 2    | StreamNumber    | Number of stream headers
/// ...    | ...  | StreamHeaders   | Array of stream headers
/// ```
///
/// # Stream Directory
///
/// The Root contains a directory of all metadata streams, each described by a [`crate::metadata::streams::StreamHeader`]
/// that specifies the stream's name, offset, and size. Common streams include:
/// - `#~` or `#-`: Compressed metadata tables stream
/// - `#Strings`: String heap for identifiers and names
/// - `#GUID`: GUID heap for type and assembly identifiers
/// - `#Blob`: Binary blob heap for signatures and complex data
/// - `#US`: User strings heap for string literals
///
/// # Examples
///
/// ## Basic Root Parsing
///
/// ```rust,no_run
/// use dotscope::metadata::root::Root;
///
/// let root = Root::read(&[
///     0x42, 0x53, 0x4A, 0x42,  // Magic signature "BSJB"
///     0x01, 0x00,              // Major version 1
///     0x00, 0x00,              // Minor version 0
///     0x00, 0x00, 0x00, 0x00,  // Reserved
///     0x0C, 0x00, 0x00, 0x00,  // Version string length
///     b'v', b'4', b'.', b'0',  // Version string "v4.0.30319"
///     b'.', b'3', b'0', b'3',
///     b'1', b'9', 0x00, 0x00,  // Null terminated + padding
///     0x00, 0x00,              // Flags
///     0x01, 0x00,              // Stream count: 1
///     0x5C, 0x00, 0x00, 0x00,  // Stream offset
///     0x08, 0x00, 0x00, 0x00,  // Stream size
///     b'#', b'~', 0x00, 0x00,  // Stream name "#~" + padding
/// ])?;
///
/// println!("Metadata version: {}", root.version);
/// println!("Found {} streams", root.stream_headers.len());
/// for stream in &root.stream_headers {
///     println!("Stream '{}' at offset 0x{:X}, size {} bytes",
///              stream.name, stream.offset, stream.size);
/// }
/// # Ok::<(), dotscope::Error>(())
/// ```
///
/// ## Stream Directory Analysis
///
/// ```rust,no_run
/// use dotscope::metadata::root::Root;
///
/// # let metadata_bytes = &[0u8; 100]; // placeholder
/// let root = Root::read(metadata_bytes)?;
///
/// // Find specific streams
/// if let Some(tables_stream) = root.stream_headers.iter()
///     .find(|s| s.name == "#~" || s.name == "#-") {
///     println!("Tables stream at offset 0x{:X}", tables_stream.offset);
/// }
///
/// if let Some(strings_stream) = root.stream_headers.iter()
///     .find(|s| s.name == "#Strings") {
///     println!("Strings heap at offset 0x{:X}", strings_stream.offset);
/// }
/// # Ok::<(), dotscope::Error>(())
/// ```
///
/// # Validation
///
/// The Root structure performs automatic validation during parsing:
/// - Verifies the magic signature matches `0x424A5342`
/// - Ensures version string length is within reasonable bounds
/// - Validates stream count and directory consistency
/// - Checks for proper null-termination of the version string
///
/// # Thread Safety
///
/// Root instances are immutable after creation and safe to share across threads.
/// All fields use thread-safe types and no internal mutability is required.
///
/// # References
///
/// - [ECMA-335 II.24.2.1: Metadata root](https://ecma-international.org/wp-content/uploads/ECMA-335_6th_edition_june_2012.pdf)
/// - [ECMA-335 II.24.2.2: Stream header](https://ecma-international.org/wp-content/uploads/ECMA-335_6th_edition_june_2012.pdf)
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Root {
    /// Magic signature identifying valid metadata: `0x424A5342` ("BSJB" in ASCII).
    ///
    /// This field must always contain the value [`CIL_HEADER_MAGIC`] for the metadata
    /// to be considered valid by the .NET runtime and analysis tools.
    pub signature: u32,

    /// Major version number of the metadata format.
    ///
    /// Typically 1 for most .NET Framework and .NET Core assemblies. This indicates
    /// the overall structure and capabilities of the metadata format.
    pub major_version: u16,

    /// Minor version number of the metadata format.
    ///
    /// Usually 1 for .NET Framework 2.0+ assemblies. Combined with `major_version`,
    /// this determines the exact metadata format specification being used.
    pub minor_version: u16,

    /// Reserved field, always 0.
    ///
    /// This field is reserved for future use and should always contain zero
    /// in valid .NET assemblies.
    pub reserved: u32,

    /// Length in bytes of the version string that follows.
    ///
    /// This includes the null terminator and any padding bytes required to
    /// align the following fields to 4-byte boundaries.
    pub length: u32,

    /// Version string identifying the .NET runtime version.
    ///
    /// Common values include:
    /// - `"v2.0.50727"` for .NET Framework 2.0/3.0/3.5
    /// - `"v4.0.30319"` for .NET Framework 4.0+
    /// - Various strings for .NET Core/.NET 5+ assemblies
    pub version: String,

    /// Reserved flags field, always 0.
    ///
    /// This field is reserved for future use and should always contain zero
    /// in current .NET assemblies.
    pub flags: u16,

    /// Number of metadata streams in the stream directory.
    ///
    /// Typical assemblies have 3-5 streams (tables, strings, GUID, blob, and optionally user strings).
    /// This count determines how many [`crate::metadata::streams::StreamHeader`] entries follow.
    pub stream_number: u16,

    /// Directory of all metadata streams in this assembly.
    ///
    /// Each entry describes a metadata stream's name, offset, and size. Common streams include:
    /// - `#~` or `#-`: Compressed metadata tables
    /// - `#Strings`: String heap for identifiers  
    /// - `#GUID`: GUID heap for type references
    /// - `#Blob`: Binary blob heap for signatures
    /// - `#US`: User strings heap for literals
    pub stream_headers: Vec<StreamHeader>,
}

impl Root {
    /// Parses a metadata root header from binary data.
    ///
    /// This method reads and validates the complete metadata root structure including the
    /// magic signature, version information, and stream directory. It performs comprehensive
    /// validation to ensure the metadata conforms to ECMA-335 specifications.
    ///
    /// # Arguments
    ///
    /// * `data` - A byte slice containing the metadata root header and stream directory.
    ///   Must start at the beginning of the metadata root structure.
    ///
    /// # Returns
    ///
    /// Returns a [`crate::Result<Root>`] containing the parsed root structure, or an error
    /// if parsing fails due to invalid data, malformed headers, or insufficient bytes.
    ///
    /// # Validation Performed
    ///
    /// This method performs extensive validation during parsing:
    /// - Verifies minimum required data length (36 bytes)
    /// - Validates magic signature matches [`CIL_HEADER_MAGIC`] (`0x424A5342`)
    /// - Checks version string length for overflow and bounds
    /// - Ensures proper null-termination of version string
    /// - Validates stream count and directory consistency
    /// - Verifies stream header alignment and bounds
    ///
    /// # Binary Format
    ///
    /// The expected binary layout is:
    /// ```text
    /// Offset | Size | Field         | Description
    /// -------|------|---------------|---------------------------
    /// 0x00   | 4    | Signature     | Magic: 0x424A5342 ("BSJB")
    /// 0x04   | 2    | MajorVersion  | Format major version
    /// 0x06   | 2    | MinorVersion  | Format minor version
    /// 0x08   | 4    | Reserved      | Always 0
    /// 0x0C   | 4    | Length        | Version string length
    /// 0x10   | N    | Version       | Null-terminated version string
    /// ...    | 2    | Flags         | Reserved, always 0
    /// ...    | 2    | StreamNumber  | Number of streams
    /// ...    | ...  | StreamHeaders | Stream directory entries
    /// ```
    ///
    /// # Examples
    ///
    /// ## Basic Parsing
    ///
    /// ```rust,no_run
    /// use dotscope::metadata::root::Root;
    ///
    /// // Parse metadata root from assembly bytes
    /// # let metadata_bytes = &[0u8; 100]; // placeholder
    /// let root = Root::read(metadata_bytes)?;
    ///
    /// println!("Metadata version: {}", root.version);
    /// println!("Stream count: {}", root.stream_headers.len());
    ///
    /// // Validate magic signature
    /// assert_eq!(root.signature, 0x424A5342);
    /// # Ok::<(), dotscope::Error>(())
    /// ```
    ///
    /// ## Stream Directory Access
    ///
    /// ```rust,no_run
    /// use dotscope::metadata::root::Root;
    ///
    /// # let metadata_bytes = &[0u8; 100]; // placeholder
    /// let root = Root::read(metadata_bytes)?;
    ///
    /// // Find the tables stream
    /// let tables_stream = root.stream_headers.iter()
    ///     .find(|stream| stream.name == "#~" || stream.name == "#-")
    ///     .expect("Tables stream not found");
    ///
    /// println!("Tables stream at offset 0x{:X}, size {} bytes",
    ///          tables_stream.offset, tables_stream.size);
    /// # Ok::<(), dotscope::Error>(())
    /// ```
    ///
    /// # Errors
    ///
    /// - [`crate::Error::OutOfBounds`]: If the data slice is too short for the required fields
    /// - [`crate::Error::Malformed`]: If the magic signature is invalid, version string is malformed,
    ///   or stream directory is inconsistent
    /// - [`crate::Error::TypeError`]: If integer overflow occurs during parsing
    ///
    /// # Thread Safety
    ///
    /// This method is thread-safe and can be called concurrently from multiple threads
    /// as it performs no mutations and uses only stack-allocated temporary variables.
    pub fn read(data: &[u8]) -> Result<Root> {
        let invalid = |field: &'static str, reason: String| ParseFailure::InvalidField {
            stage: ParseStage::MetadataRoot,
            field,
            reason,
        };
        let oob = || ParseFailure::OutOfBounds {
            stage: ParseStage::MetadataRoot,
        };

        if data.len() < MIN_ROOT_HEADER_SIZE {
            return Err(ParseFailure::Truncated {
                stage: ParseStage::MetadataRoot,
                expected: MIN_ROOT_HEADER_SIZE,
                found: data.len(),
            }
            .into());
        }

        let signature = read_le::<u32>(data)?;
        if signature != CIL_HEADER_MAGIC {
            return Err(ParseFailure::BadMagic {
                stage: ParseStage::MetadataRoot,
                expected: CIL_HEADER_MAGIC,
                found: signature,
            }
            .into());
        }

        let version_string_length = read_le_at::<u32>(data, &mut { VERSION_LENGTH_OFFSET })?;
        match version_string_length.checked_add(u32::from(VERSION_STRING_OFFSET)) {
            Some(str_end) => {
                let data_len = u32::try_from(data.len()).map_err(|_| {
                    invalid("data_length", "metadata root data length too large".into())
                })?;
                if str_end > data_len {
                    return Err(oob().into());
                }
            }
            None => {
                return Err(invalid(
                    "version_string_length",
                    format!(
                        "{version_string_length} causes integer overflow [ECMA-335 §II.24.2.1]",
                    ),
                )
                .into())
            }
        }

        let mut version_string: String = String::with_capacity(version_string_length as usize);
        for counter in 0..version_string_length {
            let mut pos = usize::from(VERSION_STRING_OFFSET)
                .checked_add(counter as usize)
                .ok_or_else(|| invalid("version_string_offset", "offset overflow".into()))?;
            version_string.push(char::from(read_le_at::<u8>(data, &mut pos)?));
        }

        // Validate version string format and content
        if version_string.is_empty() {
            return Err(invalid(
                "version_string",
                "version string cannot be empty [ECMA-335 §II.24.2.1]".into(),
            )
            .into());
        }

        // Check for common malformed version strings
        if !version_string.starts_with('v') {
            return Err(invalid(
                "version_string",
                format!("'{version_string}' must start with 'v' [ECMA-335 §II.24.2.1]",),
            )
            .into());
        }

        // Validate version string contains reasonable content
        if version_string.len() > MAX_VERSION_STRING_LENGTH {
            return Err(invalid(
                "version_string",
                format!(
                    "length {} exceeds reasonable limit ({}) [ECMA-335 §II.24.2.1]",
                    version_string.len(),
                    MAX_VERSION_STRING_LENGTH
                ),
            )
            .into());
        }

        // Stream count is located after: version_string + FLAGS_FIELD_SIZE
        let mut stream_count_offset = version_string
            .len()
            .checked_add(usize::from(VERSION_STRING_OFFSET))
            .and_then(|v| v.checked_add(FLAGS_FIELD_SIZE))
            .ok_or_else(|| invalid("stream_count_offset", "offset overflow".into()))?;
        let stream_count = read_le_at::<u16>(data, &mut stream_count_offset)?;

        // Validate stream count: must have at least one stream, no more than MAX_STREAM_COUNT
        let stream_count_size = (stream_count as usize)
            .checked_mul(MIN_STREAM_HEADER_SIZE)
            .ok_or_else(|| invalid("stream_count", "size overflow".into()))?;
        if stream_count == 0 || stream_count > MAX_STREAM_COUNT || stream_count_size > data.len() {
            return Err(invalid(
                "stream_count",
                format!("{stream_count} (must be 1-{MAX_STREAM_COUNT}) [ECMA-335 §II.24.2.1]",),
            )
            .into());
        }

        let mut streams = Vec::with_capacity(stream_count as usize);
        // Stream directory starts after: version_string + FLAGS_FIELD_SIZE + STREAM_COUNT_FIELD_SIZE
        let mut stream_offset = version_string
            .len()
            .checked_add(usize::from(VERSION_STRING_OFFSET))
            .and_then(|v| v.checked_add(FLAGS_FIELD_SIZE))
            .and_then(|v| v.checked_add(STREAM_COUNT_FIELD_SIZE))
            .ok_or_else(|| invalid("stream_directory_offset", "offset overflow".into()))?;
        let mut streams_seen = [false; MAX_STREAM_COUNT as usize];

        for _i in 0..stream_count {
            if stream_offset > data.len() {
                return Err(oob().into());
            }

            let stream_data = data
                .get(stream_offset..)
                .ok_or_else(|| Error::from(oob()))?;
            let new_stream = StreamHeader::from(stream_data)?;
            if new_stream.offset as usize > data.len()
                || new_stream.size as usize > data.len()
                || new_stream.name.len() > MAX_STREAM_NAME_LENGTH
            {
                return Err(oob().into());
            }

            match u32::checked_add(new_stream.offset, new_stream.size) {
                Some(range) => {
                    if range as usize > data.len() {
                        return Err(oob().into());
                    }
                }
                None => {
                    return Err(invalid(
                        "stream_extent",
                        format!(
                            "stream '{}' offset {} + size {} causes integer overflow [ECMA-335 §II.24.2.2]",
                            new_stream.name, new_stream.offset, new_stream.size
                        ),
                    )
                    .into())
                }
            }

            let stream_index = match new_stream.name.as_str() {
                "#Strings" => 0usize,
                "#US" => 1,
                "#Blob" => 2,
                "#GUID" => 3,
                "#~" => 4,
                "#-" => 5,
                _ => {
                    return Err(invalid(
                        "stream_name",
                        format!(
                            "unrecognized stream '{}' [ECMA-335 §II.24.2.2]",
                            new_stream.name
                        ),
                    )
                    .into())
                }
            };

            if *streams_seen
                .get(stream_index)
                .ok_or_else(|| Error::from(oob()))?
            {
                return Err(invalid(
                    "stream_name",
                    format!(
                        "duplicate stream '{}' [ECMA-335 §II.24.2.2]",
                        new_stream.name
                    ),
                )
                .into());
            }
            *streams_seen
                .get_mut(stream_index)
                .ok_or_else(|| Error::from(oob()))? = true;

            let name_aligned = new_stream
                .name
                .len()
                .checked_add(1)
                .and_then(|v| v.checked_add(3))
                .ok_or_else(|| invalid("stream_name", "alignment overflow".into()))?
                & !3usize;
            stream_offset = stream_offset
                .checked_add(STREAM_HEADER_FIXED_SIZE)
                .and_then(|v| v.checked_add(name_aligned))
                .ok_or_else(|| invalid("stream_offset", "offset overflow".into()))?;

            streams.push(new_stream);
        }

        if streams.is_empty() {
            return Err(invalid(
                "streams",
                "no valid streams found [ECMA-335 §II.24.2.1]".into(),
            )
            .into());
        }

        let flags_offset = usize::from(VERSION_STRING_OFFSET)
            .checked_add(version_string.len())
            .ok_or_else(|| invalid("flags_offset", "offset overflow".into()))?;

        Ok(Root {
            signature,
            major_version: read_le::<u16>(
                data.get(FIELD_OFFSET_MAJOR_VERSION..)
                    .ok_or_else(|| Error::from(oob()))?,
            )?,
            minor_version: read_le::<u16>(
                data.get(FIELD_OFFSET_MINOR_VERSION..)
                    .ok_or_else(|| Error::from(oob()))?,
            )?,
            reserved: read_le::<u32>(
                data.get(FIELD_OFFSET_RESERVED..)
                    .ok_or_else(|| Error::from(oob()))?,
            )?,
            length: u32::try_from(version_string.len()).map_err(|_| {
                invalid(
                    "version_string_length",
                    "string length too large [ECMA-335 §II.24.2.1]".into(),
                )
            })?,
            flags: read_le::<u16>(data.get(flags_offset..).ok_or_else(|| Error::from(oob()))?)?,
            stream_number: u16::try_from(streams.len()).map_err(|_| {
                invalid(
                    "stream_count",
                    "too many streams [ECMA-335 §II.24.2.1]".into(),
                )
            })?,
            stream_headers: streams,
            version: version_string,
        })
    }

    /// Validates that loaded streams do not overlap in memory
    ///
    /// This method should be called after all streams have been loaded and their actual
    /// positions and sizes are known. It performs comprehensive overlap detection that
    /// was deferred during initial parsing.
    ///
    /// # Arguments
    /// * `meta_root_offset` - The offset where the metadata root starts
    /// * `total_metadata_size` - The total size of the metadata section
    ///
    /// # Errors
    /// Returns an error if any streams overlap or extend beyond the metadata bounds
    pub fn validate_stream_layout(
        &self,
        meta_root_offset: usize,
        total_metadata_size: u32,
    ) -> Result<()> {
        let invalid = |field: &'static str, reason: String| ParseFailure::InvalidField {
            stage: ParseStage::MetadataRoot,
            field,
            reason,
        };
        let mut stream_ranges: Vec<(u32, u32, &str)> = Vec::new();

        // Validate stream doesn't exceed metadata bounds
        let metadata_end = meta_root_offset
            .checked_add(total_metadata_size as usize)
            .ok_or_else(|| {
                invalid(
                    "metadata_size",
                    format!("size causes overflow: {meta_root_offset} + {total_metadata_size}",),
                )
            })?;

        // Calculate actual stream positions
        for stream in &self.stream_headers {
            let absolute_start = meta_root_offset
                .checked_add(stream.offset as usize)
                .ok_or_else(|| {
                    invalid(
                        "stream_offset",
                        format!(
                            "stream '{}' offset causes overflow: {} + {}",
                            stream.name, meta_root_offset, stream.offset
                        ),
                    )
                })?;

            let absolute_end = absolute_start
                .checked_add(stream.size as usize)
                .ok_or_else(|| {
                    invalid(
                        "stream_size",
                        format!(
                            "stream '{}' size causes overflow: {} + {}",
                            stream.name, absolute_start, stream.size
                        ),
                    )
                })?;

            if absolute_end > metadata_end {
                return Err(invalid(
                    "stream_extent",
                    format!(
                        "stream '{}' extends beyond metadata bounds (end {} > metadata end {})",
                        stream.name, absolute_end, metadata_end
                    ),
                )
                .into());
            }

            stream_ranges.push((
                u32::try_from(absolute_start).map_err(|_| {
                    invalid(
                        "stream_start",
                        format!(
                            "stream '{}' start position {} exceeds u32 range",
                            stream.name, absolute_start
                        ),
                    )
                })?,
                u32::try_from(absolute_end).map_err(|_| {
                    invalid(
                        "stream_end",
                        format!(
                            "stream '{}' end position {} exceeds u32 range",
                            stream.name, absolute_end
                        ),
                    )
                })?,
                &stream.name,
            ));
        }

        for (i, &(start1, end1, name1)) in stream_ranges.iter().enumerate() {
            let skip = i.saturating_add(1);
            for &(start2, end2, name2) in stream_ranges.iter().skip(skip) {
                if start1 < end2 && start2 < end1 {
                    return Err(invalid(
                        "stream_overlap",
                        format!(
                            "stream '{name1}' ({start1}..{end1}) overlaps with stream '{name2}' ({start2}..{end2})",
                        ),
                    )
                    .into());
                }
            }
        }

        Ok(())
    }

    /// Writes the metadata root header to a writer in ECMA-335 binary format.
    ///
    /// Serializes the complete metadata root header including signature, version info,
    /// and stream directory according to ECMA-335 Section II.24.2.1.
    ///
    /// ## Binary Format Written
    /// ```text
    /// Offset | Size | Field        | Description
    /// -------|------|--------------|----------------------------------
    /// 0x00   | 4    | Signature    | Magic: 0x424A5342 ("BSJB")
    /// 0x04   | 2    | MajorVersion | Metadata format major version
    /// 0x06   | 2    | MinorVersion | Metadata format minor version
    /// 0x08   | 4    | Reserved     | Always 0
    /// 0x0C   | 4    | Length       | Version string length (padded)
    /// 0x10   | N    | Version      | Version string + null padding
    /// ...    | 2    | Flags        | Reserved, always 0
    /// ...    | 2    | StreamNumber | Number of stream headers
    /// ...    | ...  | Streams      | Stream header directory
    /// ```
    ///
    /// # Arguments
    /// * `writer` - Any type implementing [`std::io::Write`]
    ///
    /// # Returns
    /// * `Ok(())` - Root header written successfully
    /// * `Err(Error)` - Write operation failed
    ///
    /// # Examples
    /// ```rust,no_run
    /// use dotscope::metadata::root::Root;
    /// use dotscope::metadata::streams::StreamHeader;
    ///
    /// # fn example() -> dotscope::Result<()> {
    /// let root = Root {
    ///     signature: 0x424A5342,
    ///     major_version: 1,
    ///     minor_version: 1,
    ///     reserved: 0,
    ///     length: 12,
    ///     version: "v4.0.30319".to_string(),
    ///     flags: 0,
    ///     stream_number: 1,
    ///     stream_headers: vec![
    ///         StreamHeader { offset: 0x6C, size: 0x1000, name: "#~".to_string() },
    ///     ],
    /// };
    ///
    /// let mut buffer = Vec::new();
    /// root.write_to(&mut buffer)?;
    /// # Ok(())
    /// # }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns an error if writing to the writer fails or if the version string
    /// length exceeds u32 range.
    pub fn write_to<W: Write>(&self, writer: &mut W) -> Result<()> {
        // Signature (4 bytes) - "BSJB" magic
        writer.write_all(&self.signature.to_le_bytes())?;

        // Major version (2 bytes)
        writer.write_all(&self.major_version.to_le_bytes())?;

        // Minor version (2 bytes)
        writer.write_all(&self.minor_version.to_le_bytes())?;

        // Reserved (4 bytes)
        writer.write_all(&self.reserved.to_le_bytes())?;

        // Version string length (padded to 4-byte boundary)
        let version_bytes = self.version.as_bytes();
        let padded_len =
            version_bytes
                .len()
                .checked_add(3)
                .ok_or_else(|| ParseFailure::InvalidField {
                    stage: ParseStage::MetadataRoot,
                    field: "version_string_length",
                    reason: "padded length overflow".into(),
                })?
                & !3usize;
        let padded_len_u32 = u32::try_from(padded_len).map_err(|_| ParseFailure::InvalidField {
            stage: ParseStage::MetadataRoot,
            field: "version_string_length",
            reason: format!("padded length {padded_len} exceeds u32 range"),
        })?;
        writer.write_all(&padded_len_u32.to_le_bytes())?;

        // Version string + null padding to 4-byte boundary
        writer.write_all(version_bytes)?;
        let padding = padded_len.saturating_sub(version_bytes.len());
        if padding > 0 {
            writer.write_all(&vec![0u8; padding])?;
        }

        // Flags (2 bytes)
        writer.write_all(&self.flags.to_le_bytes())?;

        // Stream count (2 bytes)
        writer.write_all(&self.stream_number.to_le_bytes())?;

        // Stream headers
        for stream in &self.stream_headers {
            stream.write_to(writer)?;
        }

        Ok(())
    }

    /// Returns the total serialized size of this metadata root header in bytes.
    ///
    /// The size includes the fixed header fields plus the padded version string
    /// and all stream headers with their alignment padding.
    ///
    /// # Returns
    /// The total size in bytes when written with [`write_to`](Self::write_to).
    ///
    /// # Examples
    /// ```rust
    /// use dotscope::metadata::root::Root;
    /// use dotscope::metadata::streams::StreamHeader;
    ///
    /// let root = Root {
    ///     signature: 0x424A5342,
    ///     major_version: 1,
    ///     minor_version: 1,
    ///     reserved: 0,
    ///     length: 12,
    ///     version: "v4.0.30319".to_string(),
    ///     flags: 0,
    ///     stream_number: 1,
    ///     stream_headers: vec![
    ///         StreamHeader { offset: 0x6C, size: 0x1000, name: "#~".to_string() },
    ///     ],
    /// };
    ///
    /// // Fixed: 4+2+2+4+4+2+2 = 20
    /// // Version: "v4.0.30319" (10 chars) padded to 12
    /// // Stream header: 12 bytes (for "#~")
    /// // Total: 20 + 12 + 12 = 44
    /// assert_eq!(root.serialized_size(), 44);
    /// ```
    #[must_use]
    pub fn serialized_size(&self) -> usize {
        // Fixed fields: signature(4) + major(2) + minor(2) + reserved(4) + length(4) + flags(2) + stream_number(2)
        let fixed_size = 20usize;

        // Version string padded to 4-byte boundary
        let version_padded = self.version.len().saturating_add(3) & !3usize;

        // Stream headers
        let streams_size: usize = self
            .stream_headers
            .iter()
            .map(crate::StreamHeader::serialized_size)
            .fold(0usize, usize::saturating_add);

        fixed_size
            .saturating_add(version_padded)
            .saturating_add(streams_size)
    }
}

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

    #[test]
    fn crafted() {
        #[rustfmt::skip]
            let header_bytes = [
            0x42, 0x53, 0x4A, 0x42,
            0x00, 0x20,
            0x00, 0x30,
            0x00, 0x00, 0x00, 0x40,
            0x06, 0x00, 0x00, 0x00, // length = 6 for "v4.0.0"
            b'v', b'4', b'.', b'0', b'.', b'0',
            0x00, 0x60,
            0x01, 0x00,

            0x1, 0x00, 0x00, 0x00, // StreamHeader
            0x8, 0x00, 0x00, 0x00,
            0x23, 0x7E, 0x00,
        ];

        let parsed_header = Root::read(&header_bytes).unwrap();

        assert_eq!(parsed_header.signature, CIL_HEADER_MAGIC);
        assert_eq!(parsed_header.major_version, 0x2000);
        assert_eq!(parsed_header.minor_version, 0x3000);
        assert_eq!(parsed_header.reserved, 0x40000000);
        assert_eq!(parsed_header.length, 6);
        assert_eq!(parsed_header.version, "v4.0.0");
        assert_eq!(parsed_header.flags, 0x6000);
        assert_eq!(parsed_header.stream_number, 1);
        assert_eq!(parsed_header.stream_headers.len(), 1);
        assert_eq!(parsed_header.stream_headers[0].offset, 0x1);
        assert_eq!(parsed_header.stream_headers[0].size, 0x8);
        assert_eq!(parsed_header.stream_headers[0].name, "#~");
    }

    #[test]
    fn duplicate_stream_names_should_fail() {
        #[rustfmt::skip]
        let mut header_bytes = vec![
            0x42, 0x53, 0x4A, 0x42,  // CIL_HEADER_MAGIC
            0x00, 0x20,              // major_version
            0x00, 0x30,              // minor_version
            0x00, 0x00, 0x00, 0x40,  // reserved
            0x06, 0x00, 0x00, 0x00,  // length (version string length)
            b'v', b'4', b'.', b'0', b'.', b'0',  // version string
            0x00, 0x60,              // flags
            0x02, 0x00,              // stream_number (2 streams)

            // First StreamHeader - #~
            0x52, 0x00, 0x00, 0x00,  // offset (82 - past all headers)
            0x08, 0x00, 0x00, 0x00,  // size (8 bytes - aligned)
            0x23, 0x7E, 0x00, 0x00,  // "#~\0" + padding

            // Second StreamHeader - duplicate #~
            0x5A, 0x00, 0x00, 0x00,  // offset (90 - after first stream)
            0x08, 0x00, 0x00, 0x00,  // size (8 bytes - aligned)
            0x23, 0x7E, 0x00, 0x00,  // "#~\0" + padding (duplicate)
        ];

        // Add enough padding to reach offset 82 and then the stream data
        header_bytes.resize(98, 0x00);

        let result = Root::read(&header_bytes);
        let err = result.expect_err("Expected error for duplicate stream names");
        let error_string = err.to_string();
        assert!(
            error_string.contains("duplicate stream") && error_string.contains("#~"),
            "Expected error about duplicate stream '#~', got: {}",
            error_string
        );
    }

    #[test]
    fn test_write_to_basic() {
        let root = Root {
            signature: CIL_HEADER_MAGIC,
            major_version: 1,
            minor_version: 1,
            reserved: 0,
            length: 12, // Will be recalculated during write
            version: "v4.0.30319".to_string(),
            flags: 0,
            stream_number: 1,
            stream_headers: vec![StreamHeader {
                offset: 0x6C,
                size: 0x1000,
                name: "#~".to_string(),
            }],
        };

        let mut buffer = Vec::new();
        root.write_to(&mut buffer).unwrap();

        // Verify signature "BSJB"
        assert_eq!(&buffer[0..4], &[0x42, 0x53, 0x4A, 0x42]);
        // Verify major version
        assert_eq!(&buffer[4..6], &[0x01, 0x00]);
        // Verify minor version
        assert_eq!(&buffer[6..8], &[0x01, 0x00]);
        // Verify reserved
        assert_eq!(&buffer[8..12], &[0x00, 0x00, 0x00, 0x00]);
        // Verify version string length (padded to 12)
        assert_eq!(&buffer[12..16], &[0x0C, 0x00, 0x00, 0x00]);
        // Verify version string starts with "v4.0"
        assert_eq!(&buffer[16..20], b"v4.0");
    }

    #[test]
    fn test_serialized_size() {
        let root = Root {
            signature: CIL_HEADER_MAGIC,
            major_version: 1,
            minor_version: 1,
            reserved: 0,
            length: 12,
            version: "v4.0.30319".to_string(), // 10 chars, padded to 12
            flags: 0,
            stream_number: 1,
            stream_headers: vec![StreamHeader {
                offset: 0x6C,
                size: 0x1000,
                name: "#~".to_string(), // "#~" + null (3) padded to 4, + 8 fixed = 12
            }],
        };

        // Fixed: 20 bytes
        // Version: 12 bytes (10 chars padded to 12)
        // Stream header: 12 bytes
        // Total: 44 bytes
        assert_eq!(root.serialized_size(), 44);
    }

    #[test]
    fn test_serialized_size_multiple_streams() {
        let root = Root {
            signature: CIL_HEADER_MAGIC,
            major_version: 1,
            minor_version: 1,
            reserved: 0,
            length: 12,
            version: "v4.0.30319".to_string(),
            flags: 0,
            stream_number: 3,
            stream_headers: vec![
                StreamHeader {
                    offset: 0x6C,
                    size: 0x1000,
                    name: "#~".to_string(),
                }, // 12 bytes
                StreamHeader {
                    offset: 0x106C,
                    size: 0x500,
                    name: "#Strings".to_string(),
                }, // 20 bytes
                StreamHeader {
                    offset: 0x156C,
                    size: 0x100,
                    name: "#Blob".to_string(),
                }, // 16 bytes
            ],
        };

        // Fixed: 20 bytes
        // Version: 12 bytes
        // Stream headers: 12 + 20 + 16 = 48 bytes
        // Total: 80 bytes
        assert_eq!(root.serialized_size(), 80);
    }
}