ocpi_tariffs/

tariff.rs

//! Parse a tariff and lint the result.

pub(crate) mod v211;
pub(crate) mod v221;
pub(crate) mod v2x;

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

use crate::{
    country, currency, datetime, duration, from_warning_all, guess, json, lint, money, number,
    string, warning, weekday, ParseError, Version,
};

#[derive(Debug)]
pub enum WarningKind {
    /// The CDR location is not a valid ISO 3166-1 alpha-3 code.
    Country(country::WarningKind),
    Currency(currency::WarningKind),
    DateTime(datetime::WarningKind),
    Decode(json::decode::WarningKind),
    Duration(duration::WarningKind),

    /// A field in the tariff doesn't have the expected type.
    FieldInvalidType {
        /// The type that the given field should have according to the schema.
        expected_type: json::ValueKind,
    },

    /// A field in the tariff doesn't have the expected value.
    FieldInvalidValue {
        /// The value encountered.
        value: String,

        /// A message about what values are expected for this field.
        message: Cow<'static, str>,
    },

    /// The given field is required.
    FieldRequired {
        field_name: Cow<'static, str>,
    },

    Money(money::WarningKind),

    /// The given tariff has a `min_price` set and the `total_cost` fell below it.
    ///
    /// * See: <https://github.com/ocpi/ocpi/blob/release-2.2.1-bugfixes/mod_tariffs.asciidoc#131-tariff-object>
    TotalCostClampedToMin,

    /// The given tariff has a `max_price` set and the `total_cost` exceeded it.
    ///
    /// * See: <https://github.com/ocpi/ocpi/blob/release-2.2.1-bugfixes/mod_tariffs.asciidoc#131-tariff-object>
    TotalCostClampedToMax,

    /// The tariff has no `Element`s.
    NoElements,

    /// The tariff is not active during the `Cdr::start_date_time`.
    NotActive,
    Number(number::WarningKind),

    String(string::WarningKind),
    Weekday(weekday::WarningKind),
}

impl WarningKind {
    /// Create a new `WarningKind::FieldInvalidValue` where the field is built from the given `json::Element`.
    fn field_invalid_value(
        value: impl Into<String>,
        message: impl Into<Cow<'static, str>>,
    ) -> Self {
        WarningKind::FieldInvalidValue {
            value: value.into(),
            message: message.into(),
        }
    }
}

impl fmt::Display for WarningKind {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::String(warning_kind) => write!(f, "{warning_kind}"),
            Self::Country(warning_kind) => write!(f, "{warning_kind}"),
            Self::Currency(warning_kind) => write!(f, "{warning_kind}"),
            Self::DateTime(warning_kind) => write!(f, "{warning_kind}"),
            Self::Decode(warning_kind) => write!(f, "{warning_kind}"),
            Self::Duration(warning_kind) => write!(f, "{warning_kind}"),
            Self::FieldInvalidType { expected_type } => {
                write!(f, "Field has invalid type. Expected type `{expected_type}`")
            }
            Self::FieldInvalidValue { value, message } => {
                write!(f, "Field has invalid value `{value}`: {message}")
            }
            Self::FieldRequired { field_name } => {
                write!(f, "Field is required: {field_name}")
            }
            Self::Money(warning_kind) => write!(f, "{warning_kind}"),
            Self::NoElements => f.write_str("The tariff has no `elements`"),
            Self::NotActive => f.write_str("The tariff is not active for `Cdr::start_date_time`"),
            Self::Number(warning_kind) => write!(f, "{warning_kind}"),
            Self::TotalCostClampedToMin => write!(
                f,
                "The given tariff has a `min_price` set and the `total_cost` fell below it."
            ),
            Self::TotalCostClampedToMax => write!(
                f,
                "The given tariff has a `max_price` set and the `total_cost` exceeded it."
            ),
            Self::Weekday(warning_kind) => write!(f, "{warning_kind}"),
        }
    }
}

impl warning::Kind for WarningKind {
    fn id(&self) -> Cow<'static, str> {
        match self {
            Self::String(kind) => kind.id(),
            Self::Country(kind) => kind.id(),
            Self::Currency(kind) => kind.id(),
            Self::DateTime(kind) => kind.id(),
            Self::Decode(kind) => kind.id(),
            Self::Duration(kind) => kind.id(),
            Self::FieldInvalidType { .. } => "field_invalid_type".into(),
            Self::FieldInvalidValue { .. } => "field_invalid_value".into(),
            Self::FieldRequired { .. } => "field_required".into(),
            Self::Money(kind) => kind.id(),
            Self::NoElements => "no_elements".into(),
            Self::NotActive => "not_active".into(),
            Self::Number(kind) => kind.id(),
            Self::TotalCostClampedToMin => "total_cost_clamped_to_min".into(),
            Self::TotalCostClampedToMax => "total_cost_clamped_to_max".into(),
            Self::Weekday(kind) => kind.id(),
        }
    }
}

from_warning_all!(
    country::WarningKind => WarningKind::Country,
    currency::WarningKind => WarningKind::Currency,
    datetime::WarningKind => WarningKind::DateTime,
    duration::WarningKind => WarningKind::Duration,
    json::decode::WarningKind => WarningKind::Decode,
    money::WarningKind => WarningKind::Money,
    number::WarningKind => WarningKind::Number,
    string::WarningKind => WarningKind::String,
    weekday::WarningKind => WarningKind::Weekday
);

/// Parse a `&str` into a [`Versioned`] tariff using a schema for the given [`Version`][^spec-v211][^spec-v221] to check for
/// any unexpected fields.
///
/// # Example
///
/// ```rust
/// # use ocpi_tariffs::{tariff, Version, ParseError};
/// #
/// # const TARIFF_JSON: &str = include_str!("../test_data/v211/real_world/time_and_parking_time_separate_tariff/tariff.json");
///
/// let report = tariff::parse_with_version(TARIFF_JSON, Version::V211)?;
/// let tariff::ParseReport {
///     tariff,
///     unexpected_fields,
/// } = report;
///
/// if !unexpected_fields.is_empty() {
///     eprintln!("Strange... there are fields in the tariff that are not defined in the spec.");
///
///     for path in &unexpected_fields {
///         eprintln!("{path}");
///     }
/// }
///
/// # Ok::<(), ParseError>(())
/// ```
///
/// [^spec-v211]: <https://github.com/ocpi/ocpi/blob/release-2.1.1-bugfixes/mod_tariffs.md>
/// [^spec-v221]: <https://github.com/ocpi/ocpi/blob/release-2.2.1-bugfixes/mod_tariffs.asciidoc>
pub fn parse_with_version(source: &str, version: Version) -> Result<ParseReport<'_>, ParseError> {
    match version {
        Version::V221 => {
            let schema = &*crate::v221::TARIFF_SCHEMA;
            let report =
                json::parse_with_schema(source, schema).map_err(ParseError::from_cdr_err)?;
            let json::ParseReport {
                element,
                unexpected_fields,
            } = report;
            Ok(ParseReport {
                tariff: Versioned::new(source, element, Version::V221),
                unexpected_fields,
            })
        }
        Version::V211 => {
            let schema = &*crate::v211::TARIFF_SCHEMA;
            let report =
                json::parse_with_schema(source, schema).map_err(ParseError::from_cdr_err)?;
            let json::ParseReport {
                element,
                unexpected_fields,
            } = report;
            Ok(ParseReport {
                tariff: Versioned::new(source, element, Version::V211),
                unexpected_fields,
            })
        }
    }
}

/// Parse the JSON and try to guess the [`Version`] based on fields defined in the
/// OCPI v2.1.1[^spec-v211] and v2.2.1[^spec-v221] tariff spec.
///
/// The parser is forgiving and will not complain if the tariff JSON is missing required fields.
/// The parser will also not complain if unexpected fields are present in the JSON.
/// The [`Version`] guess is based on fields that exist.
///
/// # Example
///
/// ```rust
/// # use ocpi_tariffs::{tariff, guess, ParseError, Version, Versioned as _};
/// #
/// # const TARIFF_JSON: &str = include_str!("../test_data/v211/real_world/time_and_parking_time_separate_tariff/tariff.json");
/// let tariff = tariff::parse(TARIFF_JSON)?;
///
/// match tariff {
///     guess::Version::Certain(tariff) => {
///         println!("The tariff version is `{}`", tariff.version());
///     },
///     guess::Version::Uncertain(_tariff) => {
///         eprintln!("Unable to guess the version of given tariff JSON.");
///     }
/// }
///
/// # Ok::<(), ParseError>(())
/// ```
///
/// [^spec-v211]: <https://github.com/ocpi/ocpi/blob/release-2.1.1-bugfixes/mod_tariffs.md>
/// [^spec-v221]: <https://github.com/ocpi/ocpi/blob/release-2.2.1-bugfixes/mod_tariffs.asciidoc>
pub fn parse(tariff_json: &str) -> Result<guess::TariffVersion<'_>, ParseError> {
    guess::tariff_version(tariff_json)
}

/// Guess the [`Version`][^spec-v211][^spec-v221] of the given tariff JSON and report on any unexpected fields.
///
/// The parser is forgiving and will not complain if the tariff JSON is missing required fields.
/// The parser will also not complain if unexpected fields are present in the JSON.
/// The [`Version`] guess is based on fields that exist.
///
/// # Example
///
/// ```rust
/// # use ocpi_tariffs::{guess, tariff, warning};
/// #
/// # const TARIFF_JSON: &str = include_str!("../test_data/v211/real_world/time_and_parking_time_separate_tariff/tariff.json");
///
/// let report = tariff::parse_and_report(TARIFF_JSON)?;
/// let guess::Report {
///     unexpected_fields,
///     version,
/// } = report;
///
/// if !unexpected_fields.is_empty() {
///     eprintln!("Strange... there are fields in the tariff that are not defined in the spec.");
///
///     for path in &unexpected_fields {
///         eprintln!("  * {path}");
///     }
///
///     eprintln!();
/// }
///
/// let guess::Version::Certain(tariff) = version else {
///     return Err("Unable to guess the version of given CDR JSON.".into());
/// };
///
/// let report = tariff::lint(&tariff)?;
///
/// eprintln!("`{}` lint warnings found", report.warnings.len());
///
/// for warning::Group { element, warnings } in report.warnings.group_by_elem(tariff.as_element()) {
///     eprintln!(
///         "Warnings reported for `json::Element` at path: `{}`",
///         element.path()
///     );
///
///     for warning in warnings {
///         eprintln!("  * {warning}");
///     }
///
///     eprintln!();
/// }
///
/// # Ok::<(), Box<dyn std::error::Error + Send + Sync + 'static>>(())
/// ```
///
/// [^spec-v211]: <https://github.com/ocpi/ocpi/blob/release-2.1.1-bugfixes/mod_tariffs.md>
/// [^spec-v221]: <https://github.com/ocpi/ocpi/blob/release-2.2.1-bugfixes/mod_tariffs.asciidoc>
pub fn parse_and_report(tariff_json: &str) -> Result<guess::TariffReport<'_>, ParseError> {
    guess::tariff_version_with_report(tariff_json)
}

/// A [`Versioned`] tariff along with a set of unexpected fields.
#[derive(Debug)]
pub struct ParseReport<'buf> {
    /// The root JSON `Element`.
    pub tariff: Versioned<'buf>,

    /// A list of fields that were not expected: The schema did not define them.
    pub unexpected_fields: json::UnexpectedFields<'buf>,
}

/// A `json::Element` that has been parsed by the either the [`parse_with_version`] or [`parse`] functions
/// and has been identified as being a certain [`Version`].
#[derive(Clone)]
pub struct Versioned<'buf> {
    /// The source JSON as string.
    source: &'buf str,

    /// The parsed JSON as structured [`Element`](crate::json::Element)s.
    element: json::Element<'buf>,

    /// The `Version` of the tariff, determined during parsing.
    version: Version,
}

impl fmt::Debug for Versioned<'_> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        if f.alternate() {
            fmt::Debug::fmt(&self.element, f)
        } else {
            match self.version {
                Version::V211 => f.write_str("V211"),
                Version::V221 => f.write_str("V221"),
            }
        }
    }
}

impl crate::Versioned for Versioned<'_> {
    fn version(&self) -> Version {
        self.version
    }
}

impl<'buf> Versioned<'buf> {
    pub(crate) fn new(source: &'buf str, element: json::Element<'buf>, version: Version) -> Self {
        Self {
            source,
            element,
            version,
        }
    }

    /// Return the inner [`json::Element`] and discard the version info.
    pub fn into_element(self) -> json::Element<'buf> {
        self.element
    }

    /// Return the inner [`json::Element`] and discard the version info.
    pub fn as_element(&self) -> &json::Element<'buf> {
        &self.element
    }

    /// Return the inner JSON `str` and discard the version info.
    pub fn as_json_str(&self) -> &'buf str {
        self.source
    }
}

/// A [`json::Element`] that has been parsed by the either the [`parse_with_version`] or [`parse`] functions
/// and was determined to not be one of the supported [`Version`]s.
#[derive(Debug)]
pub struct Unversioned<'buf> {
    /// The source JSON as string.
    source: &'buf str,

    /// A list of fields that were not expected: The schema did not define them.
    element: json::Element<'buf>,
}

impl<'buf> Unversioned<'buf> {
    /// Create an unversioned [`json::Element`].
    pub(crate) fn new(source: &'buf str, elem: json::Element<'buf>) -> Self {
        Self {
            source,
            element: elem,
        }
    }

    /// Return the inner [`json::Element`] and discard the version info.
    pub fn into_element(self) -> json::Element<'buf> {
        self.element
    }

    /// Return the inner [`json::Element`] and discard the version info.
    pub fn as_element(&self) -> &json::Element<'buf> {
        &self.element
    }

    /// Return the inner JSON `&str` and discard the version info.
    pub fn as_json_str(&self) -> &'buf str {
        self.source
    }
}

impl<'buf> crate::Unversioned for Unversioned<'buf> {
    type Versioned = Versioned<'buf>;

    fn force_into_versioned(self, version: Version) -> Versioned<'buf> {
        let Self { source, element } = self;
        Versioned {
            source,
            element,
            version,
        }
    }
}

/// Lint the given tariff and return a [`lint::tariff::Report`] of any `Warning`s found.
///
/// # Example
///
/// ```rust
/// # use ocpi_tariffs::{guess, tariff, warning};
/// #
/// # const TARIFF_JSON: &str = include_str!("../test_data/v211/real_world/time_and_parking_time_separate_tariff/tariff.json");
///
/// let report = tariff::parse_and_report(TARIFF_JSON)?;
/// let guess::Report {
///     unexpected_fields,
///     version,
/// } = report;
///
/// if !unexpected_fields.is_empty() {
///     eprintln!("Strange... there are fields in the tariff that are not defined in the spec.");
///
///     for path in &unexpected_fields {
///         eprintln!("  * {path}");
///     }
///
///     eprintln!();
/// }
///
/// let guess::Version::Certain(tariff) = version else {
///     return Err("Unable to guess the version of given CDR JSON.".into());
/// };
///
/// let report = tariff::lint(&tariff)?;
///
/// eprintln!("`{}` lint warnings found", report.warnings.len());
///
/// for warning::Group { element, warnings } in report.warnings.group_by_elem(tariff.as_element()) {
///     eprintln!(
///         "Warnings reported for `json::Element` at path: `{}`",
///         element.path()
///     );
///
///     for warning in warnings {
///         eprintln!("  * {warning}");
///     }
///
///     eprintln!();
/// }
///
/// # Ok::<(), Box<dyn std::error::Error + Send + Sync + 'static>>(())
/// ```
pub fn lint(tariff: &Versioned<'_>) -> Result<lint::tariff::Report, lint::Error> {
    lint::tariff(tariff)
}

#[cfg(test)]
mod test_real_world {
    use std::path::Path;

    use assert_matches::assert_matches;

    use crate::{guess, test, Version, Versioned as _};

    use super::{parse_and_report, test::assert_parse_guess_report};

    #[test_each::file(
        glob = "ocpi-tariffs/test_data/v211/real_world/*/tariff*.json",
        name(segments = 2)
    )]
    fn test_parse_v211(tariff_json: &str, path: &Path) {
        test::setup();
        expect_version(tariff_json, path, Version::V211);
    }

    #[test_each::file(
        glob = "ocpi-tariffs/test_data/v221/real_world/*/tariff*.json",
        name(segments = 2)
    )]
    fn test_parse_v221(tariff_json: &str, path: &Path) {
        test::setup();
        expect_version(tariff_json, path, Version::V221);
    }

    /// Parse the given JSON as a tariff and generate a report on the unexpected fields.
    fn expect_version(tariff_json: &str, path: &Path, expected_version: Version) {
        let report = parse_and_report(tariff_json).unwrap();

        let expect_json = test::read_expect_json(path, "parse");
        let parse_expect = test::parse_expect_json(expect_json.as_deref());

        let tariff = assert_matches!(&report.version, guess::Version::Certain(tariff) => tariff);
        assert_eq!(tariff.version(), expected_version);

        assert_parse_guess_report(report, parse_expect);
    }
}

#[cfg(test)]
pub mod test {
    #![allow(clippy::missing_panics_doc, reason = "tests are allowed to panic")]
    #![allow(clippy::panic, reason = "tests are allowed panic")]

    use std::collections::BTreeMap;

    use crate::{
        guess, json,
        test::{ExpectFile, Expectation},
        warning,
    };

    /// Expectations for the result of calling `json::parse_and_report`.
    #[derive(Debug, serde::Deserialize)]
    pub struct ParseExpect {
        #[serde(default)]
        unexpected_fields: Expectation<Vec<json::test::PathGlob>>,
    }

    /// Expectations for the result of calling `json::parse_and_report`.
    #[derive(Debug, serde::Deserialize)]
    pub struct FromJsonExpect {
        #[serde(default)]
        warnings: Expectation<BTreeMap<String, Vec<String>>>,
    }

    /// Assert that the `TariffReport` resulting from the call to `tariff::parse_and_report`
    /// matches the expectations of the `ParseExpect` file.
    #[track_caller]
    pub(crate) fn assert_parse_guess_report(
        report: guess::TariffReport<'_>,
        expect: ExpectFile<ParseExpect>,
    ) -> guess::TariffVersion<'_> {
        let guess::Report {
            version,
            mut unexpected_fields,
        } = report;

        let ExpectFile {
            value: expect,
            expect_file_name,
        } = expect;

        let Some(expect) = expect else {
            json::test::expect_no_unexpected_fields(&expect_file_name, &unexpected_fields);
            return version;
        };

        let ParseExpect {
            unexpected_fields: expected,
        } = expect;

        json::test::expect_unexpected_fields(&expect_file_name, &mut unexpected_fields, expected);

        version
    }

    /// Assert that the unexpected fields resulting from the call to [`tariff::parse_with_version`](crate::tariff::parse_with_version)
    /// match the expectations of the `ParseExpect` file.
    #[track_caller]
    pub(crate) fn assert_parse_report(
        mut unexpected_fields: json::UnexpectedFields<'_>,
        expect: ExpectFile<ParseExpect>,
    ) {
        let ExpectFile {
            value,
            expect_file_name,
        } = expect;

        let Some(ParseExpect {
            unexpected_fields: expected,
        }) = value
        else {
            json::test::expect_no_unexpected_fields(&expect_file_name, &unexpected_fields);
            return;
        };

        json::test::expect_unexpected_fields(&expect_file_name, &mut unexpected_fields, expected);
    }

    pub(crate) fn assert_from_json_warnings(
        root: &json::Element<'_>,
        warnings: &warning::Set<super::WarningKind>,
        expect: ExpectFile<FromJsonExpect>,
    ) {
        let ExpectFile {
            value,
            expect_file_name,
        } = expect;

        // If there are warnings reported and there is no `expect` file
        // then panic printing the fields of the expect JSON object that would silence these warnings.
        // These can be copied into an `output_lint__*.json` file.
        let Some(expect) = value else {
            assert!(
                warnings.is_empty(),
                "There is no expectation file at `{expect_file_name}` but the tariff has warnings;\n{:?}",
                warnings.group_by_elem(root).into_id_map()
            );
            return;
        };

        warning::test::assert_warnings(&expect_file_name, root, warnings, expect.warnings);
    }
}