ocpi_tariffs/lint/tariff/

v2x.rs

//! The collection of lints that apply to all supported OCPI versions.

pub(crate) mod currency {
    use tracing::{debug, instrument};

    use crate::{
        currency,
        json::{self, FromJson as _},
        warning::{self, GatherWarnings as _, IntoCaveat as _},
        Verdict,
    };

    /// Validate the `country_code` field.
    #[instrument(skip_all)]
    pub(crate) fn lint(elem: &json::Element<'_>) -> Verdict<currency::Code, currency::WarningKind> {
        let mut warnings = warning::Set::<currency::WarningKind>::new();
        let code = currency::Code::from_json(elem)?.gather_warnings_into(&mut warnings);

        debug!("code: {code:?}");

        Ok(code.into_caveat(warnings))
    }
}

pub(crate) mod datetime {
    use chrono::{DateTime, Utc};
    use tracing::instrument;

    use crate::{
        json::{self, FromJson as _},
        lint::tariff::WarningKind,
        warning::{self, GatherWarnings as _, IntoCaveat as _},
        Verdict,
    };

    /// Lint both `start_date_time` and `end_date_time`.
    ///
    /// It's allowed for the `start_date_time` to be equal to the `end_date_time` but the
    /// `start_date_time` should not be greater than the `end_date_time`.
    #[instrument(skip_all)]
    pub(crate) fn lint_start_end(
        start_date_time_elem: Option<&json::Element<'_>>,
        end_date_time_elem: Option<&json::Element<'_>>,
    ) -> Verdict<(), WarningKind> {
        let mut warnings = warning::Set::<WarningKind>::new();

        let start_date = start_date_time_elem
            .map(DateTime::<Utc>::from_json)
            .transpose()?
            .gather_warnings_into(&mut warnings);
        let end_date = end_date_time_elem
            .map(DateTime::<Utc>::from_json)
            .transpose()?
            .gather_warnings_into(&mut warnings);

        if let Some(((start, start_elem), end)) = start_date.zip(start_date_time_elem).zip(end_date)
        {
            if start > end {
                warnings.with_elem(WarningKind::StartDateTimeIsAfterEndDateTime, start_elem);
            }
        }

        Ok(().into_caveat(warnings))
    }
}

pub mod time {
    //! Linting and warning infrastructure for the `start_time` and `end_time` fields.
    //!
    //! * See: [OCPI spec 2.2.1: Tariff Restrictions](<https://github.com/ocpi/ocpi/blob/release-2.2.1-bugfixes/mod_tariffs.asciidoc#146-tariffrestrictions-class>)
    //! * See: [OCPI spec 2.1.1: Tariff Restrictions](<https://github.com/ocpi/ocpi/blob/release-2.1.1-bugfixes/mod_tariffs.md#45-tariffrestrictions-class>)
    use std::{borrow::Cow, fmt};

    use chrono::{NaiveTime, Timelike as _};

    use crate::{
        datetime, from_warning_all,
        json::{self, FromJson as _},
        warning::{self, GatherWarnings as _, IntoCaveat as _},
        Verdict,
    };

    const DAY_BOUNDARY: HourMin = HourMin::new(0, 0);
    const NEAR_END_OF_DAY: HourMin = HourMin::new(23, 59);

    #[derive(Debug, Eq, PartialEq, Ord, PartialOrd)]
    pub enum WarningKind {
        /// Both `start_time` and `end_time` are defined and contain the entire day,
        /// making the restriction superfluous.
        ContainsEntireDay,

        /// The `end_time` restriction is set to `23::59`.
        ///
        /// The spec states: "To stop at end of the day use: 00:00.".
        ///
        /// * See: [OCPI spec 2.2.1: Tariff Restrictions](<https://github.com/ocpi/ocpi/blob/release-2.2.1-bugfixes/mod_tariffs.asciidoc#146-tariffrestrictions-class>)
        EndTimeIsNearEndOfDay,

        /// The `start_time` and `end_time` are equal and so the element is never valid.
        NeverValid,

        /// Each field needs to be a valid time.
        DateTime(datetime::WarningKind),
    }

    impl fmt::Display for WarningKind {
        fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
            match self {
                WarningKind::ContainsEntireDay => f.write_str("Both `start_time` and `end_time` are defined and contain the entire day."),
                WarningKind::EndTimeIsNearEndOfDay => f.write_str(r#"
The `end_time` restriction is set to `23::59`.

The spec states: "To stop at end of the day use: 00:00.".

See: <https://github.com/ocpi/ocpi/blob/release-2.2.1-bugfixes/mod_tariffs.asciidoc#146-tariffrestrictions-class>"#),
                WarningKind::NeverValid => f.write_str("The `start_time` and `end_time` are equal and so the element is never valid."),
                WarningKind::DateTime(kind) => fmt::Display::fmt(kind, f),
            }
        }
    }

    impl warning::Kind for WarningKind {
        fn id(&self) -> Cow<'static, str> {
            match self {
                WarningKind::ContainsEntireDay => "contains_entire_day".into(),
                WarningKind::EndTimeIsNearEndOfDay => "end_time_is_near_end_of_day".into(),
                WarningKind::NeverValid => "never_valid".into(),
                WarningKind::DateTime(kind) => kind.id(),
            }
        }
    }

    from_warning_all!(datetime::WarningKind => WarningKind::DateTime);

    /// Lint the `start_time` and `end_time` field.
    pub(crate) fn lint(
        start_time_elem: Option<&json::Element<'_>>,
        end_time_elem: Option<&json::Element<'_>>,
    ) -> Verdict<(), WarningKind> {
        let mut warnings = warning::Set::<WarningKind>::new();

        let start = elem_to_time_hm(start_time_elem, &mut warnings)?;
        let end = elem_to_time_hm(end_time_elem, &mut warnings)?;

        // If both `start_time` and `end_time` are defined, then perform range linting.
        if let Some(((start_time, start_elem), (end_time, end_elem))) = start.zip(end) {
            if end_time == NEAR_END_OF_DAY {
                warnings.with_elem(WarningKind::EndTimeIsNearEndOfDay, end_elem);
            }

            if start_time == DAY_BOUNDARY && is_day_end(end_time) {
                warnings.with_elem(WarningKind::ContainsEntireDay, start_elem);
            } else if start_time == end_time {
                warnings.with_elem(WarningKind::NeverValid, start_elem);
            }
        } else if let Some((start_time, start_elem)) = start {
            if start_time == DAY_BOUNDARY {
                warnings.with_elem(WarningKind::ContainsEntireDay, start_elem);
            }
        } else if let Some((end_time, end_elem)) = end {
            if is_day_end(end_time) {
                warnings.with_elem(WarningKind::ContainsEntireDay, end_elem);
            }
        }

        Ok(().into_caveat(warnings))
    }

    /// The time of day represented as hour and minute.
    #[derive(Copy, Clone, Eq, PartialEq)]
    struct HourMin {
        /// Hour of the day. Stored as `u32` because that's what `chrono` returns from `NaiveTime::hour()`.
        hour: u32,

        /// Minute of the hour. Stored as `u32` because that's what `chrono` returns from `NaiveTime::minute()`.
        min: u32,
    }

    impl HourMin {
        /// Create a new `HourMin` time.
        const fn new(hour: u32, min: u32) -> Self {
            Self { hour, min }
        }
    }

    /// Return true if the given time is close to or at the end of day.
    fn is_day_end(time: HourMin) -> bool {
        time == NEAR_END_OF_DAY || time == DAY_BOUNDARY
    }

    /// Return `Ok((HourMin, json::Element))` if the given [`json::Element`] is a valid [`NaiveTime`].
    fn elem_to_time_hm<'a, 'bin>(
        time_elem: Option<&'a json::Element<'bin>>,
        warnings: &mut warning::Set<WarningKind>,
    ) -> Result<Option<(HourMin, &'a json::Element<'bin>)>, warning::Set<WarningKind>> {
        let v = time_elem.map(NaiveTime::from_json).transpose()?;

        Ok(v.gather_warnings_into(warnings)
            .map(|t| HourMin {
                hour: t.hour(),
                min: t.minute(),
            })
            .zip(time_elem))
    }
}

pub mod elements {
    //! The linting and Warning infrastructure for the `elements` field.
    //!
    //! * See: [OCPI spec 2.2.1: Tariff Element](<https://github.com/ocpi/ocpi/blob/release-2.2.1-bugfixes/mod_tariffs.asciidoc#144-tariffelement-class>)
    //! * See: [OCPI spec 2.1.1: Tariff Element](<https://github.com/ocpi/ocpi/blob/release-2.1.1-bugfixes/mod_tariffs.md#43-tariffelement-class>)

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

    use tracing::instrument;

    use crate::{
        from_warning_all,
        json::{self, FieldsAsExt as _},
        warning::{self, GatherWarnings as _, IntoCaveat as _},
        Verdict,
    };

    use super::restrictions;

    #[derive(Debug, Eq, PartialEq, Ord, PartialOrd)]
    pub enum WarningKind {
        /// The array exists but is empty. This means that no day is allowed.
        Empty,

        /// The JSON value given is not an array.
        InvalidType,

        /// There is no `elements` array and it's required.
        RequiredField,

        /// The `restriction` field is nested in the `elements` array.
        Restrictions(restrictions::WarningKind),
    }

    impl fmt::Display for WarningKind {
        fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
            match self {
                WarningKind::Empty => write!(
                    f,
                    "An empty list of days means that no day is allowed. Is this what you want?"
                ),
                WarningKind::InvalidType => write!(f, "The value should be an array."),
                WarningKind::RequiredField => write!(f, "The `$.elements` field is required."),
                WarningKind::Restrictions(kind) => fmt::Display::fmt(kind, f),
            }
        }
    }

    impl warning::Kind for WarningKind {
        fn id(&self) -> Cow<'static, str> {
            match self {
                WarningKind::Empty => "empty".into(),
                WarningKind::InvalidType => "invalid_type".into(),
                WarningKind::RequiredField => "required".into(),
                WarningKind::Restrictions(kind) => kind.id(),
            }
        }
    }

    from_warning_all!(restrictions::WarningKind => WarningKind::Restrictions);

    /// Lint the `elements` field.
    ///
    /// * See: [OCPI v2.2.1 Tariff Element](<https://github.com/ocpi/ocpi/blob/release-2.2.1-bugfixes/mod_tariffs.asciidoc#mod_tariffs_tariffelement_class>)
    #[instrument(skip_all)]
    pub(crate) fn lint(elem: &json::Element<'_>) -> Verdict<(), WarningKind> {
        let mut warnings = warning::Set::<WarningKind>::new();

        // The `elements` field should be an array.
        let Some(items) = elem.as_array() else {
            return warnings.bail(WarningKind::InvalidType, elem);
        };

        // The `elements` array should contain at least one `Element`.
        if items.is_empty() {
            return warnings.bail(WarningKind::Empty, elem);
        }

        for ocpi_element in items {
            let Some(fields) = ocpi_element.as_object_fields() else {
                return warnings.bail(WarningKind::InvalidType, ocpi_element);
            };

            let restrictions = fields.find_field("restrictions");

            // The `restrictions` field is optional
            if let Some(field) = restrictions {
                let _drop = restrictions::lint(field.element()).gather_warnings_into(&mut warnings);
            }
        }

        Ok(().into_caveat(warnings))
    }
}

pub mod restrictions {
    //! The linting and Warning infrastructure for the `restriction` field.
    //!
    //! * See: [OCPI spec 2.2.1: Tariff Restrictions](<https://github.com/ocpi/ocpi/blob/release-2.2.1-bugfixes/mod_tariffs.asciidoc#mod_tariffs_tariffrestrictions_class>)
    //! * See: [OCPI spec 2.1.1: Tariff Restrictions](<https://github.com/ocpi/ocpi/blob/release-2.1.1-bugfixes/mod_tariffs.md#45-tariffrestrictions-class>)

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

    use tracing::instrument;

    use crate::{
        from_warning_all,
        json::{self, FieldsAsExt as _},
        warning::{self, GatherWarnings as _, IntoCaveat as _},
        Verdict,
    };

    use super::{time, weekday};

    #[derive(Debug, Eq, PartialEq, Ord, PartialOrd)]
    pub enum WarningKind {
        /// The `day_of_week` field is nested in the `restrictions` object.
        Weekday(weekday::WarningKind),

        /// The JSON value given is not an array.
        InvalidType,

        /// The `start_time` and `end_time` fields are nested in the `restrictions` object.
        Time(time::WarningKind),
    }

    impl fmt::Display for WarningKind {
        fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
            match self {
                WarningKind::Weekday(kind) => fmt::Display::fmt(kind, f),
                WarningKind::InvalidType => write!(f, "The value should be an object."),
                WarningKind::Time(kind) => fmt::Display::fmt(kind, f),
            }
        }
    }

    impl warning::Kind for WarningKind {
        fn id(&self) -> Cow<'static, str> {
            match self {
                WarningKind::Weekday(kind) => kind.id(),
                WarningKind::InvalidType => "invalid_type".into(),
                WarningKind::Time(kind) => kind.id(),
            }
        }
    }

    from_warning_all!(
        weekday::WarningKind => WarningKind::Weekday,
        time::WarningKind => WarningKind::Time
    );

    /// Lint the `restrictions` field.
    #[instrument(skip_all)]
    pub(crate) fn lint(elem: &json::Element<'_>) -> Verdict<(), WarningKind> {
        let mut warnings = warning::Set::<WarningKind>::new();

        let Some(fields) = elem.as_object_fields() else {
            return warnings.bail(WarningKind::InvalidType, elem);
        };

        let fields = fields.as_raw_map();

        {
            let start_time = fields.get("start_time").map(|e| &**e);
            let end_time = fields.get("end_time").map(|e| &**e);

            let _drop = time::lint(start_time, end_time).gather_warnings_into(&mut warnings);
        }

        {
            let day_of_week = fields.get("day_of_week").map(|e| &**e);

            let _drop = weekday::lint(day_of_week).gather_warnings_into(&mut warnings);
        }

        Ok(().into_caveat(warnings))
    }
}

pub mod weekday {
    //! Linting and warning infrastructure for the `day_of_week` field.
    //!
    //! * See: [OCPI spec 2.2.1: Tariff Restrictions](<https://github.com/ocpi/ocpi/blob/release-2.2.1-bugfixes/mod_tariffs.asciidoc#146-tariffrestrictions-class>)
    //! * See: [OCPI spec 2.2.1: Tariff DayOfWeek](<https://github.com/ocpi/ocpi/blob/release-2.2.1-bugfixes/mod_tariffs.asciidoc#mod_tariffs_dayofweek_enum>)
    //! * See: [OCPI spec 2.1.1: Tariff Restrictions](<https://github.com/ocpi/ocpi/blob/release-2.1.1-bugfixes/mod_tariffs.md#45-tariffrestrictions-class>)
    //! * See: [OCPI spec 2.1.1: Tariff DayOfWeek](<https://github.com/ocpi/ocpi/blob/release-2.1.1-bugfixes/mod_tariffs.md#41-dayofweek-enum>)

    use std::{borrow::Cow, collections::BTreeSet, fmt, sync::LazyLock};

    use crate::{
        from_warning_all,
        json::{self, FromJson},
        warning::{self, GatherWarnings as _, IntoCaveat as _},
        Verdict, Weekday,
    };

    #[derive(Debug, Eq, PartialEq, Ord, PartialOrd)]
    pub enum WarningKind {
        /// The list contains all days of the week.
        ContainsEntireWeek,

        /// Each field needs to be a valid weekday.
        Weekday(crate::weekday::WarningKind),

        /// There is at least one duplicate day.
        Duplicates,

        /// An empty array means that no day is allowed.
        Empty,

        /// The JSON value given is not an array.
        InvalidType,

        /// The days are unsorted.
        Unsorted,
    }

    impl fmt::Display for WarningKind {
        fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
            match self {
                WarningKind::ContainsEntireWeek => write!(f, "All days of the week are defined. You can simply leave out the `day_of_week` field."),
                WarningKind::Weekday(kind) => fmt::Display::fmt(kind, f),
                WarningKind::Duplicates => write!(f, "There's at least one duplicate day."),
                WarningKind::Empty => write!(
                    f,
                    "An empty list of days means that no day is allowed. Is this what you want?"
                ),
                WarningKind::InvalidType => write!(f, "The value should be an array."),
                WarningKind::Unsorted => write!(f, "The days are unsorted."),
            }
        }
    }

    impl warning::Kind for WarningKind {
        fn id(&self) -> Cow<'static, str> {
            match self {
                WarningKind::ContainsEntireWeek => "contains_entire_week".into(),
                WarningKind::Weekday(kind) => kind.id(),
                WarningKind::Duplicates => "duplicates".into(),
                WarningKind::Empty => "empty".into(),
                WarningKind::InvalidType => "invalid_type".into(),
                WarningKind::Unsorted => "unsorted".into(),
            }
        }
    }

    from_warning_all!(crate::weekday::WarningKind => WarningKind::Weekday);

    /// Lint the `day_of_week` field.
    pub(crate) fn lint(elem: Option<&json::Element<'_>>) -> Verdict<(), WarningKind> {
        /// This is the correct order of the days of the week.
        static ALL_DAYS_OF_WEEK: LazyLock<BTreeSet<Weekday>> = LazyLock::new(|| {
            BTreeSet::from([
                Weekday::Monday,
                Weekday::Tuesday,
                Weekday::Wednesday,
                Weekday::Thursday,
                Weekday::Friday,
                Weekday::Saturday,
                Weekday::Sunday,
            ])
        });

        let mut warnings = warning::Set::<WarningKind>::new();

        // The `day_of_week` field is optional.
        let Some(elem) = elem else {
            return Ok(().into_caveat(warnings));
        };

        // The `day_of_week` field should be an array.
        let Some(items) = elem.as_array() else {
            return warnings.bail(WarningKind::InvalidType, elem);
        };

        // Issue a warning if the `day_of_week` array is defined but empty.
        // This can be a user misunderstanding.
        if items.is_empty() {
            warnings.with_elem(WarningKind::Empty, elem);
            return Ok(().into_caveat(warnings));
        }

        // Convert each array item to a day and bail out on serious errors.
        let days = items
            .iter()
            .map(Weekday::from_json)
            .collect::<Result<Vec<_>, _>>()?;

        // Collect warnings from the conversion of each array item to a day.
        let days = days.gather_warnings_into(&mut warnings);

        // Issue a warning if the days are not sorted.
        if !days.is_sorted() {
            warnings.with_elem(WarningKind::Unsorted, elem);
        }

        let day_set: BTreeSet<_> = days.iter().copied().collect();

        // If the set length is less than the list, that means at least one duplicate was removed
        // during the conversion.
        if day_set.len() != days.len() {
            warnings.with_elem(WarningKind::Duplicates, elem);
        }

        // Issue a warning of all days of the week are defined.
        // This is equivalent to not defining the `day_of_week` array.
        if day_set == *ALL_DAYS_OF_WEEK {
            warnings.with_elem(WarningKind::ContainsEntireWeek, elem);
        }

        Ok(().into_caveat(warnings))
    }
}