rakata_formats/

gff_schema.rs

//! Schema types for GFF field validation.
//!
//! Defines [`GffType`], [`FieldSchema`], and the [`GffSchema`] trait used to
//! associate engine-derived field schemas with typed GFF resource wrappers.
//!
//! These types live in `rakata-formats` (next to [`GffValue`](crate::gff::GffValue))
//! so both `rakata-generics` (schema provider) and `rakata-lint` (schema consumer)
//! can depend on them without circular imports.

use crate::gff::GffValue;

/// Expected GFF field type, mirroring the variants of [`GffValue`].
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum GffType {
    /// `BYTE` - unsigned 8-bit integer.
    UInt8,
    /// `CHAR` - signed 8-bit integer.
    Int8,
    /// `WORD` - unsigned 16-bit integer.
    UInt16,
    /// `SHORT` - signed 16-bit integer.
    Int16,
    /// `DWORD` - unsigned 32-bit integer.
    UInt32,
    /// `INT` - signed 32-bit integer.
    Int32,
    /// `DWORD64` - unsigned 64-bit integer.
    UInt64,
    /// `INT64` - signed 64-bit integer.
    Int64,
    /// `FLOAT` - 32-bit float.
    Single,
    /// `DOUBLE` - 64-bit float.
    Double,
    /// `CExoString` - variable-length string.
    String,
    /// `CResRef` - resource reference (max 16 chars).
    ResRef,
    /// `CExoLocString` - localized string with optional StrRef.
    LocalizedString,
    /// `VOID` - raw binary data.
    Binary,
    /// Nested struct.
    Struct,
    /// List of structs.
    List,
    /// Vector3 - 3 packed f32 values (position).
    Vector3,
    /// Vector4 - 4 packed f32 values (orientation/quaternion).
    Vector4,
}

impl GffType {
    /// Human-readable name matching the KotOR GFF wire-format type names.
    pub fn name(self) -> &'static str {
        match self {
            GffType::UInt8 => "BYTE",
            GffType::Int8 => "CHAR",
            GffType::UInt16 => "WORD",
            GffType::Int16 => "SHORT",
            GffType::UInt32 => "DWORD",
            GffType::Int32 => "INT",
            GffType::UInt64 => "DWORD64",
            GffType::Int64 => "INT64",
            GffType::Single => "FLOAT",
            GffType::Double => "DOUBLE",
            GffType::String => "CExoString",
            GffType::ResRef => "CResRef",
            GffType::LocalizedString => "CExoLocString",
            GffType::Binary => "VOID",
            GffType::Struct => "Struct",
            GffType::List => "List",
            GffType::Vector3 => "Vector",
            GffType::Vector4 => "Quaternion",
        }
    }
}

/// What the engine does with a label, in each direction.
///
/// A schema answers "what can a legitimate file contain", which is a wider
/// question than "what does the engine read". Labels the engine never reads
/// still appear in files the toolset wrote and in files the engine itself
/// wrote, so they belong in the schema; leaving them out would make an
/// unrecognized-field check fire once per shipped resource.
///
/// Keeping them in without saying they are dead is not much better. A
/// diagnostic can then only say the field is unrecognized, when the useful
/// message is that setting it does nothing and here is what the engine reads
/// instead. This is the axis that carries the difference.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum FieldLife {
    /// The engine reads this label at this path.
    Live,
    /// Legitimate file content the engine never reads, with why.
    ///
    /// A modder trap: the label looks settable and has no effect. The
    /// canonical case is a value that lives on a blueprint, where the copy on
    /// an instance placement loses to the blueprint's with no overlay.
    ///
    /// The payload is the reason, phrased to finish the sentence "setting it
    /// has no effect, because ...", and it is a payload rather than an
    /// optional note so that no marking can exist without one. A diagnostic
    /// that can only say "this field is dead" tells an author less than the
    /// schema already knows; what makes it worth reading is "the engine takes
    /// a door's tag from the blueprint and ignores this".
    ///
    /// Two entries sharing a leaf label can carry different reasons, which is
    /// why the reason takes part in how diagnostics are grouped rather than
    /// only in how they read.
    ReadOnlyDead(&'static str),
    /// The engine writes this label and never reads it back, with why.
    ///
    /// Distinct from [`Self::ReadOnlyDead`] in who put it there. Editing one
    /// of these is equally pointless, but a file missing it is not a file
    /// anyone authored wrong, so a diagnostic should not treat the two the
    /// same way.
    WriteOnlyDead(&'static str),
}

/// A constant the engine resolves an absent field to.
///
/// Const-constructible so it can sit in the `static` schema tables, which is
/// why it does not reuse [`GffValue`] (whose string variants own a `String`).
///
/// Deliberately narrower than [`GffType`]: there is no `UInt64`, `Int64`,
/// `Double` or `Binary` variant because no audited page reports a default for
/// one. Add the variant when a page does, rather than picking an encoding for
/// a case nobody has traced.
#[derive(Debug, Clone, Copy, PartialEq)]
pub enum DefaultValue {
    /// `BYTE`, and the usual home for a documented boolean default.
    UInt8(u8),
    /// `CHAR`.
    Int8(i8),
    /// `WORD`.
    UInt16(u16),
    /// `SHORT`.
    Int16(i16),
    /// `DWORD`. Also carries sentinels such as `OBJECT_INVALID`.
    UInt32(u32),
    /// `INT`.
    Int32(i32),
    /// `FLOAT`.
    Single(f32),
    /// The text a `CExoString` or `CResRef` resolves to.
    ///
    /// Usually `""`, but not always: a door's fifteen script slots are seeded
    /// with the literal `"default"` before any read runs, which is the
    /// mechanism behind the `traps.2da` hook fallback.
    Text(&'static str),
    /// A `CExoLocString` with no strref and no substrings.
    EmptyLocalizedString,
    /// `Vector`.
    Vector3([f32; 3]),
    /// `Quaternion`.
    Vector4([f32; 4]),
}

impl DefaultValue {
    /// The GFF type this default is a value of.
    ///
    /// Lets a guard check a declared default against its entry's
    /// `expected_type`. A default written at the wrong width never matches
    /// anything, so without this check it reports as a reader mismatch
    /// forever and looks exactly like a real finding.
    ///
    /// [`Self::Text`] answers `String`; a resref default carries the same
    /// literal and is accepted against either by [`Self::matches`].
    pub fn gff_type(&self) -> GffType {
        match self {
            DefaultValue::UInt8(_) => GffType::UInt8,
            DefaultValue::Int8(_) => GffType::Int8,
            DefaultValue::UInt16(_) => GffType::UInt16,
            DefaultValue::Int16(_) => GffType::Int16,
            DefaultValue::UInt32(_) => GffType::UInt32,
            DefaultValue::Int32(_) => GffType::Int32,
            DefaultValue::Single(_) => GffType::Single,
            DefaultValue::Text(_) => GffType::String,
            DefaultValue::EmptyLocalizedString => GffType::LocalizedString,
            DefaultValue::Vector3(_) => GffType::Vector3,
            DefaultValue::Vector4(_) => GffType::Vector4,
        }
    }

    /// Returns whether `value` is what this default describes.
    ///
    /// Text compares against strings and resrefs alike, since the engine's
    /// seeded value is the same literal either way. Floats compare bitwise
    /// rather than by tolerance: both sides originate as a literal from an
    /// audited page, so a mismatch is a wrong constant rather than drift.
    pub fn matches(&self, value: &GffValue) -> bool {
        match (self, value) {
            (DefaultValue::UInt8(a), GffValue::UInt8(b)) => a == b,
            (DefaultValue::Int8(a), GffValue::Int8(b)) => a == b,
            (DefaultValue::UInt16(a), GffValue::UInt16(b)) => a == b,
            (DefaultValue::Int16(a), GffValue::Int16(b)) => a == b,
            (DefaultValue::UInt32(a), GffValue::UInt32(b)) => a == b,
            (DefaultValue::Int32(a), GffValue::Int32(b)) => a == b,
            (DefaultValue::Int32(a), GffValue::StrRef(b)) => *a == b.raw(),
            (DefaultValue::Single(a), GffValue::Single(b)) => a.to_bits() == b.to_bits(),
            (DefaultValue::Text(a), GffValue::String(b)) => a == b,
            (DefaultValue::Text(a), GffValue::ResRef(b)) => b == a,
            (DefaultValue::EmptyLocalizedString, GffValue::LocalizedString(b)) => {
                b.string_ref.is_invalid() && b.substrings.is_empty()
            }
            (DefaultValue::Vector3(a), GffValue::Vector3(b)) => {
                a.iter().zip(b).all(|(x, y)| x.to_bits() == y.to_bits())
            }
            (DefaultValue::Vector4(a), GffValue::Vector4(b)) => {
                a.iter().zip(b).all(|(x, y)| x.to_bits() == y.to_bits())
            }
            _ => false,
        }
    }
}

/// Where an audited absent-value came from.
///
/// A short quotation of the finding rather than a page name, because one
/// sentence routinely answers a whole family: a single line of `utd.md` settles
/// all fifteen door script slots, and one of `uts.md` settles seven playback
/// scalars. Naming the finding is what lets a reader check the entry without
/// reading the page top to bottom, and it is what makes a stale entry visible
/// when the page changes under it.
///
/// No line numbers. They rot faster than the prose does.
pub type DocCitation = &'static str;

/// What the engine holds for a label the file does not carry.
///
/// The two audited variants describe different engine mechanisms and read
/// differently in a diagnostic, so they stay apart. They behave identically
/// for everything this codebase does with them, because a typed view is always
/// built from bytes and never loaded onto an object that already holds state:
/// there is no prior value for a carry-over to carry. Both therefore reduce to
/// "compare against this constant" for the omit rule and the reader guard,
/// which is why those share one code path over [`Self::value`].
///
/// Every variant that claims to know something carries a [`DocCitation`],
/// which is what keeps the axis a record of audited findings rather than a
/// second copy of the reader.
#[derive(Debug, Clone, Copy, PartialEq)]
pub enum AbsentDefault {
    /// The loader stamps this constant whether or not the field was present.
    ///
    /// Overwrites whatever the object already held, which is what makes it
    /// distinct from [`Self::Constructed`] rather than a rewording of it. A
    /// placeable's trap flags are the clear case: the constructor arms all
    /// three, and the read stamps `0` over them regardless.
    Stamped(DefaultValue, DocCitation),
    /// The loader leaves the object's own value alone; this is what a freshly
    /// constructed one holds.
    ///
    /// Reporting the mechanism without the value would leave the question
    /// open, so the constructed value is part of the answer rather than a
    /// footnote to it.
    Constructed(DefaultValue, DocCitation),
    /// Audited, and the answer is known, but it is not one constant.
    ///
    /// Two shapes land here. The value can be a function of a sibling field:
    /// `Uti::MaxCharges` reuses whatever `Charges` resolved to, and `Utc`'s
    /// `MovementRate` and `WalkRate` each fall back to the other's label. Or it
    /// can be structured rather than scalar: an absent `Utc::SkillList` leaves
    /// eight skill ranks at eight zeroes, which no [`DefaultValue`] can hold.
    ///
    /// Carries a citation but no encoding of the answer. Encoding a derivation
    /// would mean a small expression language in a static table to serve a
    /// handful of fields, when the readers already do it in a line or two with
    /// the siblings in scope; encoding a structured value would mean a variant
    /// per shape. What the schema needs to say is that the value is known, is
    /// not a constant, and must never be omitted on write.
    ///
    /// **Not a synonym for [`Self::Unverified`].** Folding these together would
    /// throw away an audit, and it would do real damage downstream: the danger
    /// list a consumer builds is unverified fields weighted by how often their
    /// fallback fires, so filing a known answer as unknown plants a permanent
    /// false alarm in the one output that ranking exists to produce.
    NotAConstant(DocCitation),
    /// Nobody has traced what the engine does without this field.
    ///
    /// A terminal state, not a gap to be embarrassed about: it is what lets
    /// the audited entries be trusted. A writer must emit an unverified field,
    /// since omitting it would bet on a substitution nobody has checked.
    ///
    /// The one variant with no citation, because there is nothing to cite.
    Unverified,
}

impl AbsentDefault {
    /// The constant the engine ends up holding, when it is one.
    ///
    /// `None` for [`Self::NotAConstant`] and [`Self::Unverified`], which is what
    /// keeps both out of the omit rule and out of the reader guard.
    pub fn value(&self) -> Option<DefaultValue> {
        match self {
            AbsentDefault::Stamped(v, _) | AbsentDefault::Constructed(v, _) => Some(*v),
            AbsentDefault::NotAConstant(_) | AbsentDefault::Unverified => None,
        }
    }

    /// The audited finding this entry rests on.
    ///
    /// `None` only for [`Self::Unverified`]. Every entry that claims to know
    /// something says where it learned it.
    pub fn citation(&self) -> Option<DocCitation> {
        match self {
            AbsentDefault::Stamped(_, doc)
            | AbsentDefault::Constructed(_, doc)
            | AbsentDefault::NotAConstant(doc) => Some(*doc),
            AbsentDefault::Unverified => None,
        }
    }
}

/// Schema definition for a single GFF field.
///
/// Describes a field that can legitimately appear in a particular GFF
/// resource type. Whether the engine reads it is [`FieldSchema::life`], not a
/// condition of being here.
#[derive(Debug, Clone)]
pub struct FieldSchema {
    /// GFF field label (e.g., `"Tag"`, `"Appearance_Type"`).
    pub label: &'static str,
    /// Expected GFF value type.
    pub expected_type: GffType,
    /// What the engine does with this label, in each direction.
    ///
    /// [`FieldLife::Live`] for anything the engine reads, which is nearly
    /// everything here. The dead variants exist so a diagnostic can name what
    /// actually happens instead of reporting the label as unrecognized.
    pub life: FieldLife,
    /// Whether the engine misbehaves when this field is absent.
    ///
    /// Set this only where an audit says the loader does something worse than
    /// substitute a default. The one traced case aborts the containing
    /// structure outright, dropping a whole gun bank rather than loading it
    /// with a zero rate of fire, so "absent" and "absent and defaulted" are
    /// not the same outcome.
    ///
    /// An earlier version of this comment said the engine "typically falls
    /// back to a default" and treated the flag as a hint that the author
    /// probably meant to set the field. That was never audited, and the case
    /// we have since traced does the opposite. A field the loader defaults
    /// harmlessly is not required, however much an author might have meant to
    /// fill it in; leave it `false`.
    ///
    /// Consumed by `rakata-lint`'s SCHEMA-002, which warns on absence. The
    /// severity of that warning is the same for every required field, so this
    /// stays a `bool`: one audited failure mode is not two, and until there
    /// are more the type costs nothing to widen later.
    pub required: bool,
    /// What the engine holds when a file omits this label.
    ///
    /// Populated from the audited format pages only. The point of sourcing it
    /// from documentation rather than from the reader is that it can then
    /// disagree with the reader, which is the whole value of the guard built
    /// on it: a round-trip check compares a reader against a writer that
    /// shares its constants, so both being wrong together looks green.
    ///
    /// Per view, so the same label can resolve differently for different
    /// consumers. It does: an absent `TrapDetectable` is `1` on a door and `0`
    /// on a trigger, because a door carries its constructed value over while
    /// a trigger's read stamps a literal.
    pub absent: AbsentDefault,
    /// Sub-schema for List elements or Struct children. `None` for leaf fields.
    ///
    /// When present, validation recurses into each list element or the inner
    /// struct, checking fields against this child schema.
    pub children: Option<&'static [FieldSchema]>,
    /// Optional bounds check for numeric types.
    ///
    /// Defines min/max constraints that the engine actually honors before truncating.
    pub constraint: Option<FieldConstraint>,
}

/// A numeric boundary constraint for engine value truncation/clamping.
#[derive(Debug, Clone, PartialEq)]
pub enum FieldConstraint {
    /// Integer inclusive range `(min, max)`.
    RangeInt(i64, i64),
    /// Floating-point inclusive range `(min, max)`.
    RangeFloat(f64, f64),
}

/// Trait providing the engine-derived field schema for a GFF resource type.
///
/// Implemented by typed generics (e.g., `Utw`, `Utc`) to expose the full
/// engine schema - including fields not modeled as struct fields. The schema
/// is the single source of truth for GFF field validation.
///
/// # Example
///
/// ```
/// use rakata_formats::gff_schema::{AbsentDefault, FieldLife, FieldSchema, GffSchema, GffType};
///
/// struct MyType;
///
/// impl GffSchema for MyType {
///     fn schema() -> &'static [FieldSchema] {
///         &[
///             FieldSchema {
///                 label: "Tag",
///                 expected_type: GffType::String,
///                 life: FieldLife::Live,
///                 required: false,
///                 absent: AbsentDefault::Unverified,
///                 children: None,
///                 constraint: None,
///             },
///         ]
///     }
/// }
///
/// assert_eq!(MyType::schema().len(), 1);
/// ```
pub trait GffSchema {
    /// Returns the root field schema for this GFF resource type.
    fn schema() -> &'static [FieldSchema];
}

/// Map a [`GffValue`] variant to its corresponding [`GffType`].
///
/// Extension variants not part of the standard GFF V3.2 type set are mapped
/// to their logical equivalents:
/// - [`GffValue::Vector3`] -> [`GffType::Vector3`]
/// - [`GffValue::Vector4`] -> [`GffType::Vector4`]
/// - [`GffValue::StrRef`] -> [`GffType::UInt32`]
pub fn gff_value_type(value: &GffValue) -> GffType {
    match value {
        GffValue::UInt8(_) => GffType::UInt8,
        GffValue::Int8(_) => GffType::Int8,
        GffValue::UInt16(_) => GffType::UInt16,
        GffValue::Int16(_) => GffType::Int16,
        GffValue::UInt32(_) => GffType::UInt32,
        GffValue::Int32(_) => GffType::Int32,
        GffValue::UInt64(_) => GffType::UInt64,
        GffValue::Int64(_) => GffType::Int64,
        GffValue::Single(_) => GffType::Single,
        GffValue::Double(_) => GffType::Double,
        GffValue::String(_) => GffType::String,
        GffValue::ResRef(_) => GffType::ResRef,
        GffValue::LocalizedString(_) => GffType::LocalizedString,
        GffValue::Binary(_) => GffType::Binary,
        GffValue::Struct(_) => GffType::Struct,
        GffValue::List(_) => GffType::List,
        GffValue::Vector4(_) => GffType::Vector4,
        GffValue::Vector3(_) => GffType::Vector3,
        GffValue::StrRef(_) => GffType::UInt32,
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::gff::GffLocalizedString;
    use rakata_core::StrRef;

    #[test]
    fn gff_type_name_roundtrip() {
        assert_eq!(GffType::UInt8.name(), "BYTE");
        assert_eq!(GffType::String.name(), "CExoString");
        assert_eq!(GffType::ResRef.name(), "CResRef");
        assert_eq!(GffType::LocalizedString.name(), "CExoLocString");
        assert_eq!(GffType::Binary.name(), "VOID");
        assert_eq!(GffType::List.name(), "List");
    }

    #[test]
    fn gff_value_type_maps_standard_types() {
        assert_eq!(gff_value_type(&GffValue::UInt8(0)), GffType::UInt8);
        assert_eq!(gff_value_type(&GffValue::Int32(0)), GffType::Int32);
        assert_eq!(
            gff_value_type(&GffValue::String("x".into())),
            GffType::String
        );
        assert_eq!(gff_value_type(&GffValue::resref_lit("x")), GffType::ResRef);
        assert_eq!(
            gff_value_type(&GffValue::LocalizedString(GffLocalizedString::new(
                StrRef::invalid()
            ))),
            GffType::LocalizedString
        );
        assert_eq!(gff_value_type(&GffValue::Binary(vec![])), GffType::Binary);
    }

    #[test]
    fn gff_value_type_maps_extension_types() {
        assert_eq!(
            gff_value_type(&GffValue::Vector3([0.0; 3])),
            GffType::Vector3
        );
        assert_eq!(
            gff_value_type(&GffValue::Vector4([0.0; 4])),
            GffType::Vector4
        );
        assert_eq!(
            gff_value_type(&GffValue::StrRef(StrRef::invalid())),
            GffType::UInt32
        );
    }

    #[test]
    fn text_default_matches_strings_and_resrefs_alike() {
        // A door's script slots are seeded with this literal, and the same
        // seeded value reaches us as a CExoString on one field and a CResRef
        // on another, so one default has to answer for both spellings.
        let seeded = DefaultValue::Text("default");
        assert!(seeded.matches(&GffValue::String("default".into())));
        assert!(seeded.matches(&GffValue::resref_lit("default")));
        assert!(!seeded.matches(&GffValue::String(String::new())));
        assert!(!DefaultValue::Text("").matches(&GffValue::resref_lit("default")));
    }

    #[test]
    fn a_default_does_not_match_across_types() {
        // `0` as a BYTE and `0` as an INT are different answers about what the
        // loader holds, so the guard built on this must not accept either for
        // the other.
        assert!(DefaultValue::UInt8(0).matches(&GffValue::UInt8(0)));
        assert!(!DefaultValue::UInt8(0).matches(&GffValue::Int32(0)));
        assert!(!DefaultValue::Int32(0).matches(&GffValue::UInt8(0)));
    }

    #[test]
    fn sentinel_defaults_are_distinguishable_from_zero() {
        // The two that would silently pass a comparison written against zero.
        assert!(DefaultValue::UInt8(0xFF).matches(&GffValue::UInt8(0xFF)));
        assert!(!DefaultValue::UInt8(0xFF).matches(&GffValue::UInt8(0)));
        assert!(DefaultValue::Single(-1.0).matches(&GffValue::Single(-1.0)));
        assert!(!DefaultValue::Single(-1.0).matches(&GffValue::Single(0.0)));
    }

    #[test]
    fn empty_localized_string_needs_both_halves_empty() {
        let mut carries_a_strref = GffLocalizedString::new(StrRef::from_raw(42));
        assert!(!DefaultValue::EmptyLocalizedString
            .matches(&GffValue::LocalizedString(carries_a_strref.clone())));
        carries_a_strref.string_ref = StrRef::invalid();
        assert!(DefaultValue::EmptyLocalizedString
            .matches(&GffValue::LocalizedString(carries_a_strref)));
    }

    #[test]
    fn only_the_audited_variants_yield_a_value_to_compare() {
        // What keeps NotAConstant and Unverified out of both the omit rule and the
        // reader guard: neither can produce a constant to compare against.
        assert_eq!(
            AbsentDefault::Stamped(DefaultValue::UInt8(0), "a page").value(),
            Some(DefaultValue::UInt8(0))
        );
        assert_eq!(
            AbsentDefault::Constructed(DefaultValue::UInt8(1), "a page").value(),
            Some(DefaultValue::UInt8(1))
        );
        assert_eq!(AbsentDefault::NotAConstant("a page").value(), None);
        // Everything that claims to know something says where it learned it.
        assert_eq!(
            AbsentDefault::NotAConstant("a page").citation(),
            Some("a page")
        );
        assert_eq!(AbsentDefault::Unverified.citation(), None);
        assert_eq!(AbsentDefault::Unverified.value(), None);
    }

    #[test]
    fn gff_schema_trait_is_implementable() {
        struct TestType;
        impl GffSchema for TestType {
            fn schema() -> &'static [FieldSchema] {
                &[FieldSchema {
                    label: "Tag",
                    expected_type: GffType::String,
                    life: FieldLife::Live,
                    required: false,
                    absent: AbsentDefault::Unverified,
                    children: None,
                    constraint: None,
                }]
            }
        }
        assert_eq!(TestType::schema().len(), 1);
        assert_eq!(TestType::schema()[0].label, "Tag");
    }
}