mxaccess/rust/crates/mxaccess-galaxy/src/metadata.rs

//! `GalaxyTagMetadata` — the resolved attribute-metadata record.
//!
//! Direct port of the `GalaxyTagMetadata` record at the top of
//! `src/MxNativeClient/GalaxyRepositoryTagResolver.cs:6-73`. Carries the
//! exact set of fields the .NET reference reads from a Galaxy SQL row,
//! plus three small derived helpers:
//!
//! - [`GalaxyTagMetadata::is_buffer_property`] (mirrors the `IsBufferProperty`
//!   property at `cs:24`).
//! - [`GalaxyTagMetadata::to_reference_handle`] (mirrors `ToReferenceHandle`
//!   at `cs:26-39`) — converts the metadata into a wire-ready
//!   [`mxaccess_codec::MxReferenceHandle`].
//!
//! The .NET reference's `ToValueKind`, `TryGetValueKind`, `IsSupportedValueKind`,
//! and `ProjectWriteValue` (`cs:41-72`) are deferred to a future iteration
//! when the high-level `NmxClient::write_*` wrappers (followup F13) actually
//! need them. They reduce to a `MxDataType` → `MxValueKind` lookup table that
//! the codec doesn't currently expose; adding both the lookup and the
//! projection together keeps the iteration that needs them coherent.

use mxaccess_codec::{CodecError, MxReferenceHandle};

/// Resolved Galaxy tag metadata. Field order and types match the .NET
/// `GalaxyTagMetadata` record exactly (`cs:6-19`).
///
/// # Numeric ranges
///
/// `platform_id`, `engine_id`, `object_id` are stored as `u16` because they
/// come from `dbo.instance.mx_*_id` (SQL `smallint` checked-cast to ushort
/// in .NET — `cs:155-157`). `primitive_id`, `attribute_id`, `property_id`,
/// `mx_data_type`, `security_classification` are `i16` for the same reason
/// (signed `smallint`).
///
/// `property_id` is sourced from `SQL int` and checked-cast to `i16`
/// (`cs:160`). The Rust port stores `i16` to match the .NET shape; values
/// outside the i16 range are a SQL-side issue, not a Rust-side issue.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct GalaxyTagMetadata {
    pub object_tag_name: String,
    pub attribute_name: String,
    /// `None` for `dynamic` attributes; `Some(name)` for `primitive`.
    /// Mirrors `string? PrimitiveName` (`cs:9`).
    pub primitive_name: Option<String>,
    pub platform_id: u16,
    pub engine_id: u16,
    pub object_id: u16,
    pub primitive_id: i16,
    pub attribute_id: i16,
    pub property_id: i16,
    pub mx_data_type: i16,
    pub is_array: bool,
    pub security_classification: i16,
    /// Provenance tag — either `"dynamic"` or `"primitive"` per the SQL
    /// `attribute_source` column (`cs:247,276,375,399`).
    pub attribute_source: String,
}

impl GalaxyTagMetadata {
    /// Default `property_id` for ordinary value attributes — `cs:21`.
    pub const VALUE_PROPERTY_ID: i16 = 10;

    /// `property_id` used for `(buffer)` property references — `cs:22`.
    pub const BUFFER_PROPERTY_ID: i16 = 50;

    /// `true` when [`Self::property_id`] equals [`Self::BUFFER_PROPERTY_ID`].
    /// Mirrors `IsBufferProperty` (`cs:24`).
    #[must_use]
    pub const fn is_buffer_property(&self) -> bool {
        self.property_id == Self::BUFFER_PROPERTY_ID
    }

    /// Build the wire-form [`MxReferenceHandle`] this metadata describes.
    /// Mirrors `ToReferenceHandle(byte galaxyId = 1)` (`cs:26-39`).
    ///
    /// `galaxy_id` defaults to 1 in the .NET signature; the Rust port makes
    /// it explicit so callers don't accidentally use `0` (which would
    /// produce a different wire handle).
    ///
    /// # Errors
    ///
    /// Propagates [`CodecError::InvalidName`] from
    /// [`MxReferenceHandle::from_names`] when either name is empty or
    /// whitespace-only.
    pub fn to_reference_handle(&self, galaxy_id: u8) -> Result<MxReferenceHandle, CodecError> {
        MxReferenceHandle::from_names(
            galaxy_id,
            self.platform_id,
            self.engine_id,
            self.object_id,
            &self.object_tag_name,
            self.primitive_id,
            self.attribute_id,
            self.property_id,
            &self.attribute_name,
            self.is_array,
        )
    }
}

#[cfg(test)]
#[allow(
    clippy::unwrap_used,
    clippy::expect_used,
    clippy::indexing_slicing,
    clippy::panic
)]
mod tests {
    use super::*;

    fn sample(
        property_id: i16,
        primitive_id: i16,
        primitive_name: Option<&str>,
    ) -> GalaxyTagMetadata {
        GalaxyTagMetadata {
            object_tag_name: "TestObject_001".to_string(),
            attribute_name: "TestInt".to_string(),
            primitive_name: primitive_name.map(str::to_string),
            platform_id: 5,
            engine_id: 7,
            object_id: 42,
            primitive_id,
            attribute_id: 99,
            property_id,
            mx_data_type: 4,
            is_array: false,
            security_classification: 0,
            attribute_source: if primitive_name.is_some() {
                "primitive"
            } else {
                "dynamic"
            }
            .to_string(),
        }
    }

    #[test]
    fn property_id_constants_match_dotnet() {
        // .NET `GalaxyTagMetadata.ValuePropertyId` and `BufferPropertyId` at cs:21-22.
        assert_eq!(GalaxyTagMetadata::VALUE_PROPERTY_ID, 10);
        assert_eq!(GalaxyTagMetadata::BUFFER_PROPERTY_ID, 50);
    }

    #[test]
    fn is_buffer_property_true_only_for_50() {
        assert!(!sample(10, 0, None).is_buffer_property());
        assert!(sample(50, 0, None).is_buffer_property());
        assert!(!sample(0, 0, None).is_buffer_property());
        assert!(!sample(11, 0, None).is_buffer_property());
    }

    #[test]
    fn to_reference_handle_builds_wire_handle() {
        let meta = sample(10, -1, None); // primitive_id = -1, the .NET "no primitive" sentinel
        let handle = meta.to_reference_handle(1).unwrap();
        assert_eq!(handle.galaxy_id, 1);
        assert_eq!(handle.platform_id, 5);
        assert_eq!(handle.engine_id, 7);
        assert_eq!(handle.object_id, 42);
        assert_eq!(handle.attribute_id, 99);
        assert_eq!(handle.property_id, 10);
        // is_array = false → attribute_index = 0 per MxReferenceHandle::from_names.
        assert_eq!(handle.attribute_index, 0);
    }

    #[test]
    fn to_reference_handle_array_sets_attribute_index_minus_one() {
        let mut meta = sample(10, 0, None);
        meta.is_array = true;
        let handle = meta.to_reference_handle(1).unwrap();
        assert_eq!(handle.attribute_index, -1);
    }

    #[test]
    fn to_reference_handle_rejects_empty_name() {
        let mut meta = sample(10, 0, None);
        meta.object_tag_name = "   ".to_string();
        let err = meta.to_reference_handle(1).unwrap_err();
        assert!(matches!(err, CodecError::InvalidName));
    }

    #[test]
    fn primitive_name_round_trips() {
        let meta = sample(10, 0, Some("DelmiaReceiver"));
        assert_eq!(meta.primitive_name.as_deref(), Some("DelmiaReceiver"));
        assert_eq!(meta.attribute_source, "primitive");
    }

    #[test]
    fn dynamic_metadata_has_no_primitive_name() {
        let meta = sample(10, 0, None);
        assert_eq!(meta.primitive_name, None);
        assert_eq!(meta.attribute_source, "dynamic");
    }
}