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, collections::BTreeMap, fmt, iter, ops::Deref, vec};

use tracing::error;

use crate::json;

/// Implement `IntoCaveat` for the given type so that it can take part in the `Warning` system.
#[doc(hidden)]
#[macro_export]
macro_rules! into_caveat {
    ($kind:ident<$life:lifetime>) => {
        impl<$life> $crate::IntoCaveat for $kind<$life> {
            fn into_caveat<K: $crate::warning::Kind>(
                self,
                warnings: $crate::warning::Set<K>,
            ) -> $crate::Caveat<Self, K> {
                $crate::Caveat::new(self, warnings)
            }
        }
    };
    ($kind:ty) => {
        impl $crate::IntoCaveat for $kind {
            fn into_caveat<K: $crate::warning::Kind>(
                self,
                warnings: $crate::warning::Set<K>,
            ) -> $crate::Caveat<Self, K> {
                $crate::Caveat::new(self, warnings)
            }
        }
    };
}

/// Implement `IntoCaveat` for the given type so that it can take part in the `Warning` system.
#[doc(hidden)]
#[macro_export]
macro_rules! into_caveat_all {
    ($($kind:ty),+) => {
        $(impl $crate::IntoCaveat for $kind {
            fn into_caveat<K: $crate::warning::Kind>(
                self,
                warnings: $crate::warning::Set<K>,
            ) -> $crate::Caveat<Self, K> {
                $crate::Caveat::new(self, warnings)
            }
        })+
    };
}

#[doc(hidden)]
#[macro_export]
macro_rules! from_warning_all {
    ($($source_kind:path => $target_kind:ident::$target_variant:ident),+) => {
        $(
            /// Convert from `WarningKind` A to B
            impl From<$source_kind> for $target_kind {
                fn from(warn_kind: $source_kind) -> Self {
                    $target_kind::$target_variant(warn_kind)
                }
            }

            /// 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`.
            impl From<$crate::warning::Set<$source_kind>> for $crate::warning::Set<$target_kind> {
                fn from(set_a: warning::Set<$source_kind>) -> Self {
                    set_a.into_set()
                }
            }
        )+
    };
}

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

pub type VerdictX<T, K> = Result<Caveat<T, K>, Vec<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 }
    }
}

/// A Caveat is simply a value with associated warnings, so providing an `impl Deref` makes sense for the interface.
///
/// > The same advice applies to both deref traits. In general, deref traits
/// > **should** be implemented if:
/// >
/// > 1. a value of the type transparently behaves like a value of the target
/// >    type;
/// > 1. the implementation of the deref function is cheap; and
/// > 1. users of the type will not be surprised by any deref coercion behavior.
///
/// See: <https://doc.rust-lang.org/std/ops/trait.Deref.html#when-to-implement-deref-or-derefmut>
impl<T, K> Deref for Caveat<T, K>
where
    K: Kind,
{
    type Target = T;

    fn deref(&self) -> &T {
        &self.value
    }
}

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

    /// Return the value and drop any warnings contained within.
    pub fn ignore_warnings(self) -> T {
        self.value
    }

    /// Map the value to another target type while retaining the warnings about the source type.
    pub fn map<U, F: FnOnce(T) -> U>(self, op: F) -> Caveat<U, K> {
        let Self { value, warnings } = self;
        Caveat {
            value: op(value),
            warnings,
        }
    }
}

/// Convert a `Caveat`-like type into a `T` by gathering up it's [`Warning`]s.
///
/// Gathering warnings into a parent `warning::Set` move's the responsibility of alerting the
/// caller to the existence of those warnings to the owner of the set.
pub(crate) trait GatherWarnings<T, K>
where
    K: Kind,
{
    /// The output type of after all the warnings have been gathered.
    type Output;

    /// Convert a `Caveat`-like type into a `T` by gathering up it's [`Warning`]s.
    #[must_use = "If you want to ignore the value use `let _ =`"]
    fn gather_warnings_into<KA>(self, warnings: &mut Set<KA>) -> Self::Output
    where
        K: Into<KA>,
        KA: Kind;
}

/// Convert a `Caveat<T>` into `T` by gathering up it's `Warning`s.
impl<T, K> GatherWarnings<T, K> for Caveat<T, K>
where
    K: Kind,
{
    type Output = T;

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

        warnings.extend(inner_warnings);

        value
    }
}

/// Convert a `Option<Caveat<T>>` into `Option<T>` by gathering up it's `Warning`s.
impl<T, K> GatherWarnings<T, K> for Option<Caveat<T, K>>
where
    K: Kind,
{
    type Output = Option<T>;

    /// Convert a `Caveat` related to type `T` into a `T` by gathering it's [`Warning`]s.
    fn gather_warnings_into<KA>(self, warnings: &mut Set<KA>) -> Self::Output
    where
        K: Into<KA>,
        KA: Kind,
    {
        match self {
            Some(cv) => Some(cv.gather_warnings_into(warnings)),
            None => None,
        }
    }
}

/// Convert a `Result<Caveat<T>>` into `Result<T>` by gathering up it's `Warning`s.
impl<T, K, E> GatherWarnings<T, K> for Result<Caveat<T, K>, E>
where
    K: Kind,
    E: std::error::Error,
{
    type Output = Result<T, E>;

    /// Convert a `Caveat` related to type `T` into a `T` by gathering it's [`Warning`]s.
    fn gather_warnings_into<KA>(self, warnings: &mut Set<KA>) -> Self::Output
    where
        K: Into<KA>,
        KA: Kind,
    {
        match self {
            Ok(cv) => Ok(cv.gather_warnings_into(warnings)),
            Err(err) => Err(err),
        }
    }
}

/// Convert a `Result<Caveat<T>>` into `Result<T>` by gathering up it's `Warning`s.
impl<T, K> GatherWarnings<T, K> for Verdict<T, K>
where
    K: Kind,
{
    type Output = Option<T>;

    /// Convert a `Verdict` into an `Option` by collecting `Warnings` from the `Ok` and `Err` variants
    /// and mapping `Ok` to `Some` and `Err` to `None`.
    fn gather_warnings_into<KA>(self, warnings: &mut Set<KA>) -> Self::Output
    where
        K: Into<KA>,
        KA: Kind,
    {
        match self {
            Ok(cv) => Some(cv.gather_warnings_into(warnings)),
            Err(inner_warnings) => {
                warnings.extend(inner_warnings);
                None
            }
        }
    }
}

/// Convert a `Vec<Caveat<T>>` into `Vec<T>` by gathering up each elements `Warning`s.
impl<T, K> GatherWarnings<T, K> for Vec<Caveat<T, K>>
where
    K: Kind,
{
    type Output = Vec<T>;

    /// Convert a `Caveat` related to type `T` into a `T` by gathering it's [`Warning`]s.
    fn gather_warnings_into<KA>(self, warnings: &mut Set<KA>) -> Self::Output
    where
        K: Into<KA>,
        KA: Kind,
    {
        self.into_iter()
            .map(|cv| cv.gather_warnings_into(warnings))
            .collect()
    }
}

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

macro_rules! peel {
    ($name:ident, $($other:ident,)*) => (into_caveat_tuple! { $($other,)* })
}

macro_rules! into_caveat_tuple {
    () => ();
    ( $($name:ident,)+ ) => (
        impl<$($name),+> $crate::IntoCaveat for ($($name,)+) {
            fn into_caveat<K: $crate::warning::Kind>(
                self,
                warnings: $crate::warning::Set<K>,
            ) -> $crate::Caveat<Self, K> {
                $crate::Caveat::new(self, warnings)
            }
        }
        peel! { $($name,)+ }
    )
}

into_caveat_tuple! { E, D, C, B, A, Z, Y, X, W, V, U, T, }

into_caveat_all!(
    (),
    bool,
    char,
    u8,
    u16,
    u32,
    u64,
    u128,
    i8,
    i16,
    i32,
    i64,
    i128
);

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

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

/// `Verdict` specific extension methods for the `Result` type.
pub trait VerdictExt<T, K: Kind> {
    /// Maps a `Verdict<T, E>` to `Verdict<U, E>` by applying a function to a
    /// contained [`Ok`] value, leaving an [`Err`] value untouched.
    fn map_caveat<F, U>(self, op: F) -> Verdict<U, K>
    where
        F: FnOnce(T) -> U;
}

impl<T, K: Kind> VerdictExt<T, K> for Verdict<T, K>
where
    T: IntoCaveat,
{
    fn map_caveat<F, U>(self, op: F) -> Verdict<U, K>
    where
        F: FnOnce(T) -> U,
    {
        match self {
            Ok(c) => Ok(c.map(op)),
            Err(w) => Err(w),
        }
    }
}

/// 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.
    kind: K,

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

/// A Display object for writing a set of warnings.
///
/// The warnings set is formatted as a tree with element paths on the first level
/// and a list of warning ids on the second.
///
/// ```shell
/// $path.to.json.[0].field:
///   - list_of_warning_ids
///   - next_warning_id
///
/// $next.path.to.[1].json.field
///   - list_of_warning_ids
/// ```
pub struct SetWriter<'caller, 'buf, K: Kind> {
    /// The [`json::Element`] that has [`Warning`]s.
    root_elem: &'caller json::Element<'buf>,

    /// The list of warnings for the [`json::Element`].
    warnings: &'caller Set<K>,

    /// The indent to prefix to each warning id.
    indent: &'caller str,
}

impl<'caller, 'buf, K: Kind> SetWriter<'caller, 'buf, K> {
    /// Create a new `SetWriter` with a default warning id indent of `"  - "`.
    pub fn new(root_elem: &'caller json::Element<'buf>, warnings: &'caller Set<K>) -> Self {
        Self {
            root_elem,
            warnings,
            indent: "  - ",
        }
    }

    /// Create a new `SetWriter` with a custom warning id indent.
    pub fn with_indent(
        root_elem: &'caller json::Element<'buf>,
        warnings: &'caller Set<K>,
        indent: &'caller str,
    ) -> Self {
        Self {
            root_elem,
            warnings,
            indent,
        }
    }
}

impl<K: Kind> fmt::Debug for SetWriter<'_, '_, K> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt::Display::fmt(self, f)
    }
}

impl<K: Kind> fmt::Display for SetWriter<'_, '_, K> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let mut iter = self.warnings.group_by_elem(self.root_elem);

        {
            // Write the first group without an empty line prefix.
            let Some(Group { element, warnings }) = iter.next() else {
                return Ok(());
            };

            writeln!(f, "{}", element.path())?;

            for warning in warnings {
                write!(f, "{}{}", self.indent, warning)?;
            }
        }

        // Write the rest of the Groups with am empty line padding.
        for Group { element, warnings } in iter {
            writeln!(f, "\n{}", element.path())?;

            for warning in warnings {
                write!(f, "{}{}", self.indent, warning)?;
            }
        }

        Ok(())
    }
}

impl<K: Kind> Warning<K> {
    /// Create a Warning from a `Kind`.
    ///
    /// The `Kind` is typically defined in a domain module.
    pub(crate) const fn with_elem(kind: K, elem: &json::Element<'_>) -> Warning<K> {
        Warning {
            kind,
            elem_id: elem.id(),
        }
    }

    /// Return the warning `Kind`'s id.
    pub fn id(&self) -> Cow<'static, str> {
        self.kind.id()
    }

    /// Return the `Kind` as a reference.
    pub fn kind(&self) -> &K {
        &self.kind
    }

    /// Consume the Warning and return the `Kind` of warning.
    pub fn into_kind(self) -> K {
        self.kind
    }
}

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 `WarningKind` in the mod 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![])
    }

    /// Create a `Set` from a `Vec` of [`Warning`]s.
    pub(crate) fn from_vec(warnings: Vec<Warning<K>>) -> Self {
        Self(warnings)
    }

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

    /// Create and push a [`Warning`] from a [`Kind`] defined in a domain module and it's associated [`json::Element`].
    pub(crate) fn with_elem(&mut self, kind: K, elem: &json::Element<'_>) {
        self.push(Warning::with_elem(kind, elem));
    }

    /// Create and add a [`Warning`] from a [`Kind`] to the set while consuming the set into a [`Verdict`].
    ///
    /// This is designed for use as the last [`Warning`] of a function. The function should exit with the `Err` returned.
    pub(crate) fn bail<T>(mut self, kind: K, elem: &json::Element<'_>) -> Verdict<T, K> {
        self.0.push(Warning::with_elem(kind, elem));
        Err(self)
    }

    /// Converts `Set<K>` into `Set<KB>` using the `impl From<K> for KB`.
    ///
    /// This is used by the `from_warning_all` 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)
    }

    /// Converts `Set<K>` into `Set<KU>` using the `impl From<K> for KU`.
    ///
    /// This is used by the `from_warning_all` macro.
    pub(crate) fn map_warning<KU>(self) -> Set<KU>
    where
        KU: 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)
    }

    /// Extend this set with the warnings of another.
    ///
    /// The other set's warnings will be converted if necessary.
    pub(crate) fn extend<KA>(&mut self, warnings: Set<KA>)
    where
        KA: Into<K> + Kind,
    {
        self.0.extend(warnings.0.into_iter().map(|warn| {
            let Warning { kind, elem_id } = warn;
            Warning {
                kind: kind.into(),
                elem_id,
            }
        }));
    }

    /// Return true if the [`Warning`] set is empty.
    pub fn is_empty(&self) -> bool {
        self.0.is_empty()
    }

    /// Return the amount of [`Warning`]s in this set.
    pub fn len(&self) -> usize {
        self.0.len()
    }

    /// Return an iterator of [`Warning`]s grouped by [`json::Element`].
    ///
    /// The iterator emits [`Group`]s that borrows the warnings.
    pub fn group_by_elem<'caller: 'buf, 'buf>(
        &'caller self,
        root: &'caller json::Element<'buf>,
    ) -> GroupByElem<'caller, 'buf, K> {
        let mut warnings = self.0.iter().collect::<Vec<_>>();
        warnings.sort_unstable_by_key(|warning| warning.elem_id);

        GroupByElem {
            walker: json::walk::DepthFirst::new(root),
            warnings: warnings.into_iter().peekable(),
        }
    }

    /// Return an iterator of [`Warning`]s grouped by [`json::Element`].
    ///
    /// The iterator emits [`IntoGroup`]s that owns the warnings.
    pub fn into_group_by_elem<'caller, 'buf>(
        self,
        root: &'caller json::Element<'buf>,
    ) -> IntoGroupByElem<'caller, 'buf, K> {
        let Self(mut warnings) = self;
        warnings.sort_unstable_by_key(|warning| warning.elem_id);

        IntoGroupByElem {
            walker: json::walk::DepthFirst::new(root),
            warnings: warnings.into_iter().peekable(),
        }
    }
}

/// An iterator of owned warning [`Kind`]s grouped by [`json::Element`].
pub struct IntoGroupByElem<'caller, 'buf, K>
where
    K: Kind,
{
    /// The [`json::Element`] tree walker.
    walker: json::walk::DepthFirst<'caller, 'buf>,

    /// The iterator over every [`Warning`].
    warnings: iter::Peekable<vec::IntoIter<Warning<K>>>,
}

impl<K> IntoGroupByElem<'_, '_, K>
where
    K: Kind,
{
    /// Return a map of [`json::Element`] paths to a list of [`Kind`]s.
    pub fn into_kind_map(self) -> BTreeMap<String, Vec<K>> {
        self.map(IntoGroup::into_kinds).collect()
    }

    /// Return a map of [`json::Element`] paths to a list of [`Warning`] ids as Strings.
    ///
    /// This is designed to be used to print out maps of warnings associated with elements.
    /// You can use the debug alternate format `{:#?}` to print the map 'pretty' over multiple lines
    /// with indentation.
    ///
    /// Note: This representation is also valid JSON and can be copied directly to
    /// a test expectation file.
    pub fn into_id_map(self) -> BTreeMap<String, Vec<String>> {
        self.map(IntoGroup::into_str_ids).collect()
    }

    /// Return a map of [`json::Element`] paths to a list of [`Warning`] messages as Strings.
    ///
    /// This is designed to be used to print out maps of warnings associated with elements.
    /// You can use the debug alternate format `{:#?}` to print the map 'pretty' over multiple lines
    /// with indentation.
    pub fn into_msg_map(self) -> BTreeMap<String, Vec<String>> {
        self.map(IntoGroup::into_str_msgs).collect()
    }
}

/// A group of warning `Kind`s associated with an `Element`.
///
/// This group is emitted from the `IntoGroupByElem` iterator.
/// The warning `Kind`s are owned and so can be moved to another location.
#[derive(Debug)]
pub struct IntoGroup<'caller, 'buf, K> {
    /// The [`json::Element`] that has [`Warning`]s.
    pub element: &'caller json::Element<'buf>,

    /// The list of warnings for the [`json::Element`].
    pub warnings: Vec<K>,
}

impl<K> IntoGroup<'_, '_, K>
where
    K: Kind,
{
    /// Convert the Group into String versions of its Element path.
    ///
    /// The first tuple field is the [`Element`](json::Element) path as a String.
    /// The second tuple field is a list of [`Warning`](Kind)s.
    pub fn into_kinds(self) -> (String, Vec<K>) {
        let Self { element, warnings } = self;
        (element.path().to_string(), warnings)
    }

    /// Convert the Group into String versions of its parts.
    ///
    /// The first tuple field is the [`Element`](json::Element) path as a String.
    /// The second tuple field is a list of [`Warning`](Kind) ids.
    pub fn into_str_ids(self) -> (String, Vec<String>) {
        let Self { element, warnings } = self;
        (
            element.path().to_string(),
            warnings.iter().map(|kind| kind.id().to_string()).collect(),
        )
    }

    /// Convert the Group into String versions of its parts.
    ///
    /// The first tuple field is the [`Element`](json::Element) path as a String.
    /// The second tuple field is a list of [`Warning`](Kind) messages.
    pub fn into_str_msgs(self) -> (String, Vec<String>) {
        let Self { element, warnings } = self;
        (
            element.path().to_string(),
            warnings.iter().map(ToString::to_string).collect(),
        )
    }
}

impl<'caller, 'buf, K: Kind> Iterator for IntoGroupByElem<'caller, 'buf, K> {
    type Item = IntoGroup<'caller, 'buf, K>;

    fn next(&mut self) -> Option<Self::Item> {
        // The warnings are sorted and grouped by consecutive and compacted ids.
        let warning = self.warnings.next()?;

        // Search for the element associated with warning.
        let element = loop {
            let Some(element) = self.walker.next() else {
                error!("An Element with id: `{}` was not found", warning.elem_id);
                return None;
            };

            if element.id() < warning.elem_id {
                // This element does not have any warnings continue the search for the
                // element associated with the warning.
                continue;
            }

            if element.id() > warning.elem_id {
                debug_assert!(
                    element.id() <= warning.elem_id,
                    "The elements or the warnings are not sorted."
                );
                return None;
            }

            // We found the element for the first warning in the group.
            break element;
        };

        // Insert the first warning into the `grouped` list.
        let mut warnings_grouped = vec![warning.into_kind()];

        // Collect all warnings in the group.
        loop {
            let warning = self.warnings.next_if(|w| w.elem_id == element.id());
            let Some(warning) = warning else {
                break;
            };

            warnings_grouped.push(warning.into_kind());
        }

        Some(IntoGroup {
            element,
            warnings: warnings_grouped,
        })
    }
}

/// An iterator of borrowed warning [`Kind`]s grouped by [`json::Element`].
pub struct GroupByElem<'caller, 'buf, K>
where
    K: Kind,
{
    /// The [`json::Element`] tree walker.
    walker: json::walk::DepthFirst<'caller, 'buf>,

    /// The iterator over every [`Warning`].
    warnings: iter::Peekable<vec::IntoIter<&'caller Warning<K>>>,
}

impl<K> GroupByElem<'_, '_, K>
where
    K: Kind,
{
    /// Return a map of [`json::Element`] paths to a list of [`Warning`] ids as Strings.
    ///
    /// This is designed to be used to print out maps of warnings associated with elements.
    /// You can use the debug alternate format `{:#?}` to print the map 'pretty' over multiple lines
    /// with indentation.
    ///
    /// Note: This representation is also valid JSON and can be copied directly to
    /// a test expectation file.
    pub fn into_id_map(self) -> BTreeMap<String, Vec<String>> {
        self.map(Group::into_str_ids).collect()
    }

    /// Return a map of [`json::Element`] paths to a list of [`Warning`] messages as Strings.
    ///
    /// This is designed to be used to print out maps of warnings associated with elements.
    /// You can use the debug alternate format `{:#?}` to print the map 'pretty' over multiple lines
    /// with indentation.
    pub fn into_msg_map(self) -> BTreeMap<String, Vec<String>> {
        self.map(Group::into_str_msgs).collect()
    }
}

/// A group of warning `Kind`s associated with an `Element`.
///
/// This group is emitted from the `GroupByElem` iterator.
/// The warning `Kind`s are borrowed so the source Set does not need to be consumed/moved.
#[derive(Debug)]
pub struct Group<'caller, 'buf, K> {
    /// The [`json::Element`] that has [`Warning`]s.
    pub element: &'caller json::Element<'buf>,

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

impl<K> Group<'_, '_, K>
where
    K: Kind,
{
    /// Convert the Group into String versions of its parts.
    ///
    /// The first tuple field is the [`Element`](json::Element) path as a String.
    /// The second tuple field is a list of [`Warning`](Kind) ids.
    pub fn into_str_ids(self) -> (String, Vec<String>) {
        let Self { element, warnings } = self;
        (
            element.path().to_string(),
            warnings.iter().map(|kind| kind.id().to_string()).collect(),
        )
    }

    /// Convert the Group into String versions of its parts.
    ///
    /// The first tuple field is the [`Element`](json::Element) path as a String.
    /// The second tuple field is a list of [`Warning`](Kind) messages.
    pub fn into_str_msgs(self) -> (String, Vec<String>) {
        let Self { element, warnings } = self;
        (
            element.path().to_string(),
            warnings.iter().map(ToString::to_string).collect(),
        )
    }
}

impl<'caller, 'buf, K: Kind> Iterator for GroupByElem<'caller, 'buf, K> {
    type Item = Group<'caller, 'buf, K>;

    fn next(&mut self) -> Option<Self::Item> {
        // The warnings are sorted and grouped by consecutive and compacted ids.
        let warning = self.warnings.next()?;

        // Search for the element associated with warning.
        let element = loop {
            let Some(element) = self.walker.next() else {
                error!("An Element with id: `{}` was not found", warning.elem_id);
                return None;
            };

            if element.id() < warning.elem_id {
                // This element does not have any warnings continue the search for the
                // element associated with the warning.
                continue;
            }

            if element.id() > warning.elem_id {
                debug_assert!(
                    element.id() <= warning.elem_id,
                    "The elements or the warnings are not sorted."
                );
                return None;
            }

            // We found the element for the first warning in the group.
            break element;
        };

        // Insert the first warning into the `grouped` list.
        let mut warnings_grouped = vec![warning.kind()];

        // Collect all warnings in the group.
        loop {
            let warning = self.warnings.next_if(|w| w.elem_id == element.id());
            let Some(warning) = warning else {
                break;
            };

            warnings_grouped.push(warning.kind());
        }

        Some(Group {
            element,
            warnings: warnings_grouped,
        })
    }
}

#[cfg(test)]
pub(crate) mod test {
    use std::{
        borrow::Cow,
        collections::{BTreeMap, BTreeSet},
        ops, slice,
    };

    use assert_matches::assert_matches;

    use crate::{
        json,
        test::{ExpectValue, Expectation},
    };

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

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

        pub fn into_parts_vec(self) -> Vec<(K, json::ElemId)> {
            self.0
                .into_iter()
                .map(|Warning { kind, elem_id }| (kind, elem_id))
                .collect()
        }

        /// Return the inner kinds.
        ///
        /// This should only be used in tests and the `mod price`.
        pub fn into_kind_vec(self) -> Vec<K> {
            self.0.into_iter().map(Warning::into_kind).collect()
        }

        /// Return the inner storage 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
        }
    }

    /// Assert that the warnings given are expected.
    ///
    /// Panic with print out of the warnings and the expectations if any warnings were unexpected.
    pub(crate) fn assert_warnings<K>(
        expect_file_name: &str,
        root: &json::Element<'_>,
        warnings: &Set<K>,
        expected: Expectation<BTreeMap<String, Vec<String>>>,
    ) where
        K: Kind,
    {
        let Expectation::Present(ExpectValue::Some(expected)) = expected else {
            assert!(
                warnings.is_empty(),
                "There is no `warnings` field in the `{expect_file_name}` file but the tariff has warnings;\n{:?}",
                warnings.group_by_elem(root).into_id_map()
            );
            return;
        };

        {
            // Assert that the `expect` file doesn't have extraneous entries.
            let warnings_grouped = warnings
                .group_by_elem(root)
                .map(|Group { element, warnings }| (element.path().to_string(), warnings))
                .collect::<BTreeMap<_, _>>();

            let mut elems_in_expect_without_warning = vec![];

            for elem_path in expected.keys() {
                if !warnings_grouped.contains_key(elem_path) {
                    elems_in_expect_without_warning.push(elem_path);
                }
            }

            assert!(elems_in_expect_without_warning.is_empty(),
                "The expect file `{expect_file_name}` has entries for elements that have no warnings:\n\
                {elems_in_expect_without_warning:#?}"
            );
        }

        // The elements that have warnings but have no entry for the elements path in the `expect` file.
        let mut elems_missing_from_expect = vec![];
        // The element that have warnings and an entry in the `expect` file, but the list of expected warnings
        // is not equal to the list of actual warnings.
        let mut unequal_warnings = vec![];

        for group in warnings.group_by_elem(root) {
            let path_str = group.element.path().to_string();
            let Some(warnings_expected) = expected.get(&*path_str) else {
                elems_missing_from_expect.push(group);
                continue;
            };

            // Make two sets of actual and expected warnings.
            let warnings_expected = warnings_expected
                .iter()
                .map(|s| Cow::Borrowed(&**s))
                .collect::<BTreeSet<_>>();
            let warnings = group
                .warnings
                .iter()
                .map(|w| w.id())
                .collect::<BTreeSet<_>>();

            if warnings_expected != warnings {
                unequal_warnings.push(group);
            }
        }

        if !elems_missing_from_expect.is_empty() || !unequal_warnings.is_empty() {
            let missing = elems_missing_from_expect
                .into_iter()
                .map(Group::into_str_ids)
                .collect::<BTreeMap<_, _>>();

            let unequal = unequal_warnings
                .into_iter()
                .map(Group::into_str_ids)
                .collect::<BTreeMap<_, _>>();

            match (!missing.is_empty(), !unequal.is_empty()) {
                (true, true) => panic!(
                    "Elements with warnings but are not defined in the `{expect_file_name}` file:\n{missing:#?}\n\
                    Elements that are in the `{expect_file_name}` file but the warnings list is not correct.\n\
                    The warnings reported are: \n{unequal:#?}"                  
                ),
                (true, false) => panic!("Elements with warnings but are not defined in the `{expect_file_name}` file:\n{missing:#?}"),
                (false, true) => panic!(
                    "Elements that are in the `{expect_file_name}` file but the warnings list is not correct.\n\
                    The warnings reported are: \n{unequal:#?}"
                ),
                (false, false) => (),
            }
        }
    }
}

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

    use assert_matches::assert_matches;

    use crate::{json, test};

    use super::{Group, IntoGroup, Kind, Set, Warning};

    const JSON: &str = r#"{
    "field_one#": "one",
    "field_two": "two",
    "field_three": "three"
}"#;

    #[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_by_elem() {
        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: json::ElemId::from(0),
        });
        warnings.push(Warning {
            kind: WarningKind::One,
            elem_id: json::ElemId::from(1),
        });
        warnings.push(Warning {
            kind: WarningKind::Three,
            elem_id: json::ElemId::from(3),
        });
        warnings.push(Warning {
            kind: WarningKind::OneAgain,
            elem_id: json::ElemId::from(1),
        });

        let mut iter = warnings.group_by_elem(&elem);

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

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

        {
            let Group { 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.as_slice(),
                [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 Group { 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.as_slice(), [WarningKind::Three]);
        }
    }

    #[test]
    fn should_into_group_by_elem() {
        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: json::ElemId::from(0),
        });
        warnings.push(Warning {
            kind: WarningKind::Three,
            elem_id: json::ElemId::from(3),
        });
        warnings.push(Warning {
            kind: WarningKind::One,
            elem_id: json::ElemId::from(1),
        });
        warnings.push(Warning {
            kind: WarningKind::OneAgain,
            elem_id: json::ElemId::from(1),
        });

        let mut iter = warnings.into_group_by_elem(&elem);

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

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

        {
            let IntoGroup { 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.as_slice(),
                [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 IntoGroup { 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.as_slice(), [WarningKind::Three]);
        }
    }

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