ocpi_tariffs/

warning.rs

//! These types are the basis for writing functions that can emit a set of [`Warning`]s based on the value they are trying to create.
//!
//! The aim is for functions to be as resilient as possible while creating the value and emit commentary on their progress in the form of a growing set of [`Warning`]s.
//!
//! The caller of the function can use the set of [`Warning`]s to decide whether the operation was a success or failure and whether the value can be used or needs to be modified.
//!  
//! A concrete example is the conversion of a JSON [`json::Element`] into a `country::Code`. The [`json::Element`] may be the incorrect type and so the function issues a [`Warning`] and exits as it cannot continue with the given data. The signature of this fn is something like:
//!
//! ```rust ignore
//! // file: country.rs
//!  
//! pub enum Warning {
//!     InvalidType,
//!     ...
//! }
//!
//! pub enum Expect {
//!     Alpha2,
//!     Alpha3
//! }
//!
//! pub enum Code {
//!     fn from_json_element(json: json::Element, expect: Expect) -> Verdict<Code, Warning> {
//!         ...
//!     }
//! }
//! ```
//!
//! A [`Verdict`] is a [`Result`] where both the `Ok` and `Err` variants return a potential set of [`Warning`]s.
//! The `Ok` variant is `Caveat<T>`, where a [`Caveat`] contains a value but potentially contains cautionary details to be taken into account when using the value.
//! Hence the name.
//!
//! The `Err` variant is `Warnings<K>`, a collection of [`Warning`]s. A [`Warning`] can be converted into an `Error` by the caller. A `Caveat<T>` is more completely described as `Caveat<T, K>` where the `Caveat` contains a value `T` and a set of `Warnings<K>`.
//!
//! All of this is to say that a resilient function can always return [`Warning`]s and the caller can gather them
//! together into a new set or fail.
//!
//! Returning to the example of the [`country::Code`](crate::country::Code), if the [`json::Element`] is the expected string type, then processing continues.
//! The string may contain control chars or escape chars and both these cases will emit a [`Warning`].
//! The string may be made up of three chars when two were expected.
//! This is the interesting case, as some [`country::Code`](crate::country::Code) fields are `alpha-3` where others are `alpha-2`.
//! Processing can still continue, as an `alpha-3` code can be converted to an `alpha-2` simply, while emitting a [`Warning`].
//!
//! The caller can decide whether this is acceptable or not.

use std::{borrow::Cow, fmt, slice};

use tracing::error;

use crate::json;

/// A `Verdict` is a standard [`Result`] with [`Warning`]s potentially issued for both the `Ok` and `Err` variants.
pub type Verdict<T, K> = Result<Caveat<T, K>, Set<K>>;

/// A value that may have associated [`Warning`]s.
///
/// Even though the value has been created there may be certain caveats you should be aware of before using it.
#[derive(Debug)]
pub struct Caveat<T, K: Kind> {
    /// The value created by the function.
    value: T,

    /// A list of [`Warning`]s or caveats issued when creating the value.
    warnings: Set<K>,
}

impl<T, K> Caveat<T, K>
where
    T: IntoCaveat,
    K: Kind,
{
    /// The only way to create `Caveat<T>` is if `T` impls `IntoCaveat`.
    pub(crate) fn new(value: T, warnings: Set<K>) -> Self {
        Self { value, warnings }
    }
}

impl<T, K> Caveat<T, K>
where
    K: Kind,
{
    /// Return the value and any [`Warning`]s stored in the `Caveat`.
    pub fn into_parts(self) -> (T, Set<K>) {
        let Self { value, warnings } = self;
        (value, warnings)
    }
}

impl<T, K> Caveat<T, K>
where
    K: Kind,
{
    /// Convert a `Caveat<T>` into a `T` by gathering it's [`Warning`]s.
    pub(crate) fn gather_warnings_into<KA>(self, outer_warnings: &mut Set<KA>) -> T
    where
        K: Into<KA>,
        KA: Kind,
    {
        let Self { value, warnings } = self;

        outer_warnings.0.extend(warnings.0.into_iter().map(|warn| {
            let Warning { kind, elem_id } = warn;
            Warning {
                kind: kind.into(),
                elem_id,
            }
        }));

        value
    }

    pub fn map<U, F: FnOnce(T) -> U>(self, op: F) -> Caveat<U, K> {
        let Self { value, warnings } = self;
        Caveat {
            value: op(value),
            warnings,
        }
    }
}

/// Gather warnings from an `Option<Caveat<T, K>>`.
pub trait OptionCaveat<T, K>
where
    K: Kind,
{
    fn gather_warnings_into<KA>(self, outer_warnings: &mut Set<KA>) -> Option<T>
    where
        K: Into<KA>,
        KA: Kind;
}

impl<T, K> OptionCaveat<T, K> for Option<Caveat<T, K>>
where
    K: Kind,
{
    /// Convert a `Option<Caveat<T>>` into a `Option<T>` by gathering it's [`Warning`]s.
    fn gather_warnings_into<KA>(self, outer_warnings: &mut Set<KA>) -> Option<T>
    where
        K: Into<KA>,
        KA: Kind,
    {
        self.map(|v| v.gather_warnings_into(outer_warnings))
    }
}
/// Converts a value `T` into a `Caveat`.
///
/// Each module can use this to whitelist their types for conversion to `Caveat<T>`.
pub trait IntoCaveat: Sized {
    /// Any type can be converted to `Caveat<T>` only a list of [`Warning`]s is required.
    fn into_caveat<K: Kind>(self, warnings: Set<K>) -> Caveat<Self, K>;
}

/// Allow unit to be converted into a `Caveat`.
impl IntoCaveat for () {
    fn into_caveat<K: Kind>(self, warnings: Set<K>) -> Caveat<Self, K> {
        Caveat::new(self, warnings)
    }
}

/// Allow `Cow<'a, str>` to be converted into a `Caveat`.
impl IntoCaveat for Cow<'_, str> {
    fn into_caveat<K: Kind>(self, warnings: Set<K>) -> Caveat<Self, K> {
        Caveat::new(self, warnings)
    }
}

/// Allow `Option<T: IntoCaveat>` to be converted into a `Caveat`.
impl<T> IntoCaveat for Option<T>
where
    T: IntoCaveat,
{
    fn into_caveat<K: Kind>(self, warnings: Set<K>) -> Caveat<Self, K> {
        Caveat::new(self, warnings)
    }
}

/// `Verdict` specific extinsion methods for the `Result` type.
pub trait VerdictExt<T, K: Kind> {
    /// Converts from `Verdict<T, K>` to `Caveat<Option<T>, K>`.
    ///
    /// The `Ok` and `Err` variants are encoded as `Some(T)` and `None` respectively and the [`Warning`]s are retained.
    fn ok_caveat(self) -> Caveat<Option<T>, K>;
}

impl<T, K: Kind> VerdictExt<T, K> for Verdict<T, K>
where
    T: IntoCaveat,
{
    fn ok_caveat(self) -> Caveat<Option<T>, K> {
        match self {
            Ok(v) => {
                let (v, warnings) = v.into_parts();
                Some(v).into_caveat(warnings)
            }
            Err(warnings) => None.into_caveat(warnings),
        }
    }
}

/// Convert a [`Kind`] into a [`Warning`] by supplying a [`json::Element`].
pub trait IntoWarning<K: Kind> {
    /// Convert a [`Kind`] into a [`Warning`] by supplying a [`json::Element`].
    fn into_warning(self, elem: &json::Element<'_>) -> Warning<K>;
}

/// Implement `IntoWarning` for all implementors of `Kind`.
impl<K> IntoWarning<K> for K
where
    K: Kind,
{
    /// Convert a [`Kind`] into a [`Warning`] by supplying a [`json::Element`].
    fn into_warning(self, elem: &json::Element<'_>) -> Warning<K> {
        Warning {
            kind: self,
            elem_id: elem.id(),
        }
    }
}

/// Implement a conversion from `warning::Set<A>` to `warning::Set<B>` so that the `Err` variant
/// of a `Verdict<_, A>` can be converted using the `?` operator to `Verdict<_, B>`.
///
/// `warning::Set::into_set` is used to perform the conversion between set A and B.
#[macro_export]
#[doc(hidden)]
macro_rules! from_warning_set_to {
    ($kind_a:path => $kind_b:path) => {
        impl From<$crate::warning::Set<$kind_a>> for $crate::warning::Set<$kind_b> {
            fn from(set_a: warning::Set<$kind_a>) -> Self {
                set_a.into_set()
            }
        }
    };
}

/// Convert an `Option` into a `Verdict` ready to exit the fn.
pub trait OptionExt<T, K>
where
    K: Kind,
{
    /// Convert an `Option` into a `Verdict` ready to exit the fn.
    fn exit_with_warning<F>(self, warnings: Set<K>, f: F) -> Verdict<T, K>
    where
        F: FnOnce() -> Warning<K>;
}

impl<T, K> OptionExt<T, K> for Option<T>
where
    T: IntoCaveat,
    K: Kind,
{
    fn exit_with_warning<F>(self, mut warnings: Set<K>, f: F) -> Verdict<T, K>
    where
        F: FnOnce() -> Warning<K>,
    {
        if let Some(v) = self {
            Ok(v.into_caveat(warnings))
        } else {
            warnings.push(f());
            Err(warnings)
        }
    }
}

/// Groups together a module's `Kind` and the associated [`json::Element`].
///
/// The [`json::Element`] is referenced by `ElemId`.
#[derive(Debug)]
pub struct Warning<K: Kind> {
    /// The kind of warning.
    pub kind: K,

    /// The Id of the element that caused the [`Warning`].
    pub elem_id: json::ElemId,
}

impl<K: Kind> Warning<K> {
    pub fn id(&self) -> Cow<'static, str> {
        self.kind.id()
    }
}

impl<K: Kind> fmt::Display for Warning<K> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}", self.kind)
    }
}

/// Each mod defines warnings for the type that it's trying to parse or lint from a [`json::Element`].
///
/// The `mod::Kind` should impl this trait to take part in the [`Warning`] system.
pub trait Kind: Sized + fmt::Debug + fmt::Display {
    /// Return the human readable identifier for the [`Warning`].
    ///
    /// This is used in the `auto_test` assertion system.
    /// Changing these strings may require updating `output_price__cdr.json` files.
    fn id(&self) -> Cow<'static, str>;
}

/// A set of [`Warning`]s transported through the system using a `Verdict` or `Caveat`.
#[derive(Debug)]
pub struct Set<K: Kind>(Vec<Warning<K>>);

impl<K: Kind> Set<K> {
    /// Create a new list of [`Warning`]s
    pub(crate) fn new() -> Self {
        Self(vec![])
    }

    /// Push a new [`Warning`] onto the list.
    pub(crate) fn push(&mut self, warning: Warning<K>) {
        self.0.push(warning);
    }

    /// Converts `Set<K>` into `Set<KB>` using the `impl From<K> for KB`.
    ///
    /// This is used by the `from_warning_set_to` macro.
    pub(crate) fn into_set<KB>(self) -> Set<KB>
    where
        KB: Kind + From<K>,
    {
        let warnings = self
            .0
            .into_iter()
            .map(|warn| {
                let Warning { kind, elem_id } = warn;
                Warning {
                    kind: kind.into(),
                    elem_id,
                }
            })
            .collect();

        Set(warnings)
    }
}

impl<K: Kind> Set<K> {
    /// Return true if the [`Warning`] list is empty.
    pub fn is_empty(&self) -> bool {
        self.0.is_empty()
    }

    /// Return true if the [`Warning`] list is empty.
    pub fn len(&self) -> usize {
        self.0.len()
    }

    /// Convert the set of [`Warning`]s into a `Report` ready for presentation.
    pub fn into_report(self) -> Report<K> {
        Report::new(self)
    }
}

/// A collection of [`Warning`]s grouped by [`json::Element`].
///
/// Use the `Report::iter` to iterate over the [`json::Element`]s that have [`Warning`]s in order.
#[derive(Debug)]
pub struct Report<K>
where
    K: Kind,
{
    groups: Vec<Group<K>>,
}

/// A `Group` of `WarningKind`s that all share the same `ElemeId`.
#[derive(Debug)]
struct Group<K> {
    /// The `ElemId` all [`Warning`]s share.
    id: json::ElemId,

    /// The group of `WarningKind`s.
    warnings: Vec<K>,
}

impl<K> Report<K>
where
    K: Kind,
{
    /// Create a new `Report` ready to present each [`json::Element`] that has [`Warning`]s.
    fn new(warnings: Set<K>) -> Self {
        let Set(mut warnings) = warnings;
        // sort the warnings list so that we know the warngs are grouped by `ElemId`.
        warnings.sort_unstable_by(|a, b| a.elem_id.cmp(&b.elem_id));
        let mut warnings = warnings.into_iter();

        let Some(first) = warnings.next() else {
            return Self { groups: vec![] };
        };

        // Insert the first warning into the resulting elements list.
        // This is used as the first id to start grouping by.
        let mut groups = vec![Group {
            id: first.elem_id,
            warnings: vec![first.kind],
        }];

        // Group the warnings by `ElemId`, the warnings list is already compacted so that the warnings
        // Are sorted by `ElemId`. This loop simplify cuts the [`Warning`] list up into those groups.
        for warn in warnings {
            // Compare the current [`Warning`] with the next to detect the end of the current run/group.
            if let Some(s) = groups.last_mut() {
                if warn.elem_id == s.id {
                    // The run continues, add the current `WarningKind` to the `Group`.
                    s.warnings.push(warn.kind);
                } else {
                    // This is the end of the run/group. Create a new `Group`.
                    groups.push(Group {
                        id: warn.elem_id,
                        warnings: vec![warn.kind],
                    });
                }
            }
        }

        Self { groups }
    }

    /// Iterate over all [`json::Element`]s that have [`Warning`]s.
    ///
    /// The iteration happens in the order of the `Element::id`
    pub fn iter<'a, 'bin>(&'a self, root: &'a json::Element<'bin>) -> ReportIter<'a, 'bin, K> {
        ReportIter {
            walker: json::walk::DepthFirst::new(root),
            groups: self.groups.iter(),
        }
    }

    /// Return true if there are no [`json::Element`]s with [`Warning`]s.
    pub fn is_empty(&self) -> bool {
        self.groups.is_empty()
    }

    /// Return the number of [`json::Element`]s with [`Warning`]s.
    pub fn len(&self) -> usize {
        self.groups.len()
    }
}

/// An iterator the walks over all [`json::Element`]s and returns `Some` if the given
/// [`json::Element`] has any [`Warning`]s.
pub struct ReportIter<'a, 'bin, K: Kind> {
    /// The [`json::Element`] tree walker.
    walker: json::walk::DepthFirst<'a, 'bin>,

    /// The iterator for all [`Warning`] `Group`s.
    groups: slice::Iter<'a, Group<K>>,
}

impl<'a, 'bin, K: Kind> Iterator for ReportIter<'a, 'bin, K> {
    type Item = ElementReport<'a, 'bin, K>;

    fn next(&mut self) -> Option<Self::Item> {
        let group = self.groups.next()?;

        // Resolve the [`Warning`] `Group`'s `ElemId` to an [`json::Element`] in the given tree.
        loop {
            let Some(element) = self.walker.next() else {
                error!("An Element with id: `{}` was not found", group.id);
                return None;
            };

            if element.id() == group.id {
                return Some(ElementReport {
                    element,
                    warnings: &group.warnings,
                });
            }
        }
    }
}

/// A report of all warnings for a given [`json::Element`].
pub struct ElementReport<'a, 'bin, K: Kind> {
    /// The [`json::Element`] that has [`Warning`]s.
    pub element: &'a json::Element<'bin>,

    /// The list of warnings for the [`json::Element`].
    pub warnings: &'a [K],
}

impl<K: Kind> fmt::Debug for ElementReport<'_, '_, K> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("ElementReport")
            .field("element", &self.element.path())
            .field("warnings", &self.warnings)
            .finish()
    }
}

#[cfg(test)]
mod test {
    use std::{ops, slice};

    use assert_matches::assert_matches;

    use super::{Caveat, Kind, Set, Warning};

    impl<K: Kind> Set<K> {
        /// Return the inner storage.
        pub fn into_vec(self) -> Vec<Warning<K>> {
            self.0
        }

        /// Return the inner storgae as a slice.
        pub fn as_slice(&self) -> &[Warning<K>] {
            self.0.as_slice()
        }

        /// Return an immutable iterator over the slice.
        pub fn iter(&self) -> slice::Iter<'_, Warning<K>> {
            self.0.iter()
        }
    }

    impl<K: Kind> ops::Deref for Set<K> {
        type Target = [Warning<K>];

        fn deref(&self) -> &[Warning<K>] {
            self.as_slice()
        }
    }

    impl<K: Kind> IntoIterator for Set<K> {
        type Item = Warning<K>;

        type IntoIter = <Vec<Self::Item> as IntoIterator>::IntoIter;

        fn into_iter(self) -> Self::IntoIter {
            self.0.into_iter()
        }
    }

    impl<'a, K: Kind> IntoIterator for &'a Set<K> {
        type Item = &'a Warning<K>;

        type IntoIter = slice::Iter<'a, Warning<K>>;

        fn into_iter(self) -> Self::IntoIter {
            self.0.iter()
        }
    }

    impl<T, K> Caveat<T, K>
    where
        K: Kind,
    {
        /// Return the value and assert there are no [`Warning`]s.
        pub fn unwrap(self) -> T {
            let Self { value, warnings } = self;
            assert_matches!(warnings.into_vec().as_slice(), []);
            value
        }
    }
}

#[cfg(test)]
mod test_report {
    use std::fmt;

    use assert_matches::assert_matches;

    use crate::{json, test, warning::ElementReport};

    use super::{Kind, Report, Set, Warning};

    #[derive(Debug)]
    enum WarningKind {
        Root,
        One,
        OneAgain,
        Three,
    }

    impl Kind for WarningKind {
        fn id(&self) -> std::borrow::Cow<'static, str> {
            match self {
                WarningKind::Root => "root".into(),
                WarningKind::One => "one".into(),
                WarningKind::OneAgain => "one_again".into(),
                WarningKind::Three => "three".into(),
            }
        }
    }

    impl fmt::Display for WarningKind {
        fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
            match self {
                WarningKind::Root => write!(f, "NopeRoot"),
                WarningKind::One => write!(f, "NopeOne"),
                WarningKind::OneAgain => write!(f, "NopeOneAgain"),
                WarningKind::Three => write!(f, "NopeThree"),
            }
        }
    }

    #[test]
    fn should_group_warnings() {
        const JSON: &str = r#"{
    "field_one#": "one",
    "field_two": "two",
    "field_three": "three"
}"#;

        test::setup();

        let elem = parse(JSON);
        let mut warnings = Set::<WarningKind>::new();

        // Push warnings into the set out of order.
        // They should be sorted by `ElemId`.
        warnings.push(Warning {
            kind: WarningKind::Root,
            elem_id: 0.into(),
        });
        warnings.push(Warning {
            kind: WarningKind::Three,
            elem_id: 3.into(),
        });
        warnings.push(Warning {
            kind: WarningKind::One,
            elem_id: 1.into(),
        });
        warnings.push(Warning {
            kind: WarningKind::OneAgain,
            elem_id: 1.into(),
        });

        let report = Report::new(warnings);
        let mut iter = report.iter(&elem);
        let ElementReport { element, warnings } = iter.next().unwrap();

        assert!(
            element.value().is_object(),
            "The root object should be reported first"
        );
        assert_eq!(
            element.id(),
            json::ElemId::from(0),
            "The root object should be reported first"
        );
        assert_matches!(warnings, [WarningKind::Root]);

        let ElementReport { element, warnings } = iter.next().unwrap();

        assert_eq!(element.value().as_raw_str().unwrap().as_raw(), "one");
        assert_eq!(element.id(), json::ElemId::from(1));
        assert_matches!(
            warnings,
            [WarningKind::One, WarningKind::OneAgain],
            "[`json::Element`] 1 should have two warnings"
        );

        // [`json::Element`] 2 has no [`Warning`]s so we expect [`json::Element`] 3 next
        let ElementReport { element, warnings } = iter.next().unwrap();

        assert_eq!(element.value().as_raw_str().unwrap().as_raw(), "three");
        assert_eq!(element.id(), json::ElemId::from(3));
        assert_matches!(warnings, [WarningKind::Three]);
    }

    fn parse(json: &str) -> json::Element<'_> {
        json::parse(json).unwrap()
    }
}