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 four 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`].
//! - [`GalaxyTagMetadata::resolve_write_kind`] + [`GalaxyTagMetadata::is_writable`]
//!   (mirrors the `MxDataType` → `MxValueKind` selection from
//!   `ToValueKind` / `TryGetValueKind` / `IsSupportedValueKind` /
//!   `ProjectWriteValue` at `cs:41-72`). Delegates to
//!   [`MxValueKind::for_data_type`] in `mxaccess-codec` which fuses the
//!   primary `NmxWriteMessage.GetValueKind` table with the two scalar
//!   fallbacks (`ElapsedTime` → `Int32`, `InternationalizedString` →
//!   `String`).
//!
//! What's still deferred: the value-side of `ProjectWriteValue`
//! (`cs:53-72`) — converting a caller-supplied value (e.g. .NET `TimeSpan`)
//! into the `MxValue` variant the wire kind expects. That belongs at the
//! consumer boundary in Rust, not in the metadata; F13's `NmxClient::write_*`
//! wrappers will handle it.

use mxaccess_codec::{CodecError, MxDataType, MxReferenceHandle, MxValueKind};
use thiserror::Error;

/// Returned by [`GalaxyTagMetadata::resolve_write_kind`] when the metadata's
/// `(mx_data_type, is_array)` combination is not writable on the LMX wire.
///
/// Mirrors the `ArgumentOutOfRangeException` paths in the .NET reference
/// at `NmxWriteMessage.cs:62-65,108` and `GalaxyRepositoryTagResolver.cs:62,70`.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Error)]
#[error("MX data type {mx_data_type} (is_array={is_array}) has no supported MxValueKind mapping")]
pub struct UnsupportedDataType {
    pub mx_data_type: i16,
    pub is_array: bool,
}

/// 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
    }

    /// Resolve the wire-side [`MxValueKind`] this attribute writes as,
    /// based on `(mx_data_type, is_array)`. Mirrors the .NET
    /// `GalaxyTagMetadata.ProjectWriteValue` kind selection at
    /// `GalaxyRepositoryTagResolver.cs:53-72` (delegated to
    /// [`MxValueKind::for_data_type`] which fuses both
    /// `NmxWriteMessage.GetValueKind` and the `ProjectWriteValue` scalar
    /// fallbacks for `ElapsedTime` → `Int32` and `InternationalizedString` →
    /// `String`).
    ///
    /// # Errors
    ///
    /// [`UnsupportedDataType`] when the `(mx_data_type, is_array)` pair has
    /// no LMX wire encoding (e.g. arrays of `ElapsedTime`, scalars of
    /// `ReferenceType` / `StatusType` / `Enum` / etc.).
    ///
    /// # Note
    ///
    /// This only resolves the **kind**; converting the caller's value
    /// payload into the right `MxValue` variant is the caller's job.
    /// The .NET reference's `TimeSpan` → `int millis` conversion at
    /// `cs:67-68` happens at the consumer boundary in Rust, not here —
    /// the Rust port doesn't expose `TimeSpan`-style types in the codec.
    pub fn resolve_write_kind(&self) -> Result<MxValueKind, UnsupportedDataType> {
        let data_type = MxDataType::from_i16(self.mx_data_type);
        MxValueKind::for_data_type(data_type, self.is_array).ok_or(UnsupportedDataType {
            mx_data_type: self.mx_data_type,
            is_array: self.is_array,
        })
    }

    /// `true` when [`Self::resolve_write_kind`] would succeed. Useful as a
    /// pre-flight check in browse UIs.
    #[must_use]
    pub fn is_writable(&self) -> bool {
        self.resolve_write_kind().is_ok()
    }

    /// 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");
    }

    #[test]
    fn resolve_write_kind_double_scalar_is_float64() {
        // sample defaults mx_data_type=4 (Double), is_array=false.
        let meta = sample(10, 0, None);
        assert_eq!(meta.resolve_write_kind(), Ok(MxValueKind::Float64));
        assert!(meta.is_writable());
    }

    #[test]
    fn resolve_write_kind_boolean_array_is_bool_array() {
        let mut meta = sample(10, 0, None);
        meta.mx_data_type = 1; // Boolean
        meta.is_array = true;
        assert_eq!(meta.resolve_write_kind(), Ok(MxValueKind::BoolArray));
    }

    #[test]
    fn resolve_write_kind_elapsed_time_scalar_is_int32() {
        let mut meta = sample(10, 0, None);
        meta.mx_data_type = 7; // ElapsedTime
        meta.is_array = false;
        assert_eq!(meta.resolve_write_kind(), Ok(MxValueKind::Int32));
    }

    #[test]
    fn resolve_write_kind_array_of_elapsed_time_unsupported() {
        let mut meta = sample(10, 0, None);
        meta.mx_data_type = 7; // ElapsedTime
        meta.is_array = true;
        let err = meta.resolve_write_kind().unwrap_err();
        assert_eq!(
            err,
            UnsupportedDataType {
                mx_data_type: 7,
                is_array: true,
            }
        );
        assert!(!meta.is_writable());
    }

    #[test]
    fn resolve_write_kind_internationalized_string_scalar_is_string() {
        let mut meta = sample(10, 0, None);
        meta.mx_data_type = 15; // InternationalizedString
        meta.is_array = false;
        assert_eq!(meta.resolve_write_kind(), Ok(MxValueKind::String));
    }

    #[test]
    fn resolve_write_kind_reference_type_unsupported() {
        let mut meta = sample(10, 0, None);
        meta.mx_data_type = 8; // ReferenceType — never writable on the wire
        meta.is_array = false;
        assert!(meta.resolve_write_kind().is_err());
        assert!(!meta.is_writable());
    }

    #[test]
    fn resolve_write_kind_unknown_data_type_unsupported() {
        let mut meta = sample(10, 0, None);
        meta.mx_data_type = -1; // Unknown sentinel
        assert!(meta.resolve_write_kind().is_err());
    }
}