ocpi-tariffs 0.52.0

//! Produce a human-language explanation of a tariff.
//!
//! The explanation is rendered as Markdown, aimed at a person who wants to understand what a tariff
//! charges and when, without having to read the OCPI spec themselves.
//!
//! Rather than describing the tariff field-by-field, the explanation reads the tariff the way a
//! pricing engine does. It groups the price components by dimension (energy, charging
//! time, idle time, flat fee) and narrates how the rate changes as a session progresses.
//! A dimension with more than one tier is rendered as a bulleted list. The interpretation
//! folds in the spec knowledge that:
//!
//! - Tariff elements are matched from the top down, and for each dimension the first element whose
//!   restrictions match supplies the rate. This lets a list of elements express tiers, such as one
//!   rate "for the first 3 hours" and another for "the remaining time".
//! - `TIME` is time spent actively charging, while `PARKING_TIME` is time connected but idle (for
//!   example, after the car has finished charging).
//! - A `min_duration`/`max_duration` restriction bounds a tier by how long the session has lasted;
//!   a `min_kwh`/`max_kwh` restriction bounds it by how much energy has been consumed.
//! - An element with a `reservation` restriction never applies to a regular charging session.
//! - A `start_date`/`end_date` restriction bounds a tier by calendar date. Elements are commonly
//!   authored with one element per price change, in no particular order. A list of tiers gated by
//!   nothing but dates is listed chronologically instead of in matching order (see
//!   [`chronological_order`]).
//!
//! The work is split in two: [`build`] reads the tariff and produces a language-independent
//! [`Explanation`] that captures *what* to say, and the
//! [renderer](super::render) turns that into prose in a chosen [`Language`]. Every semantic
//! decision lives in `build`, so a new language only supplies vocabulary and formatting.
//!
//! * See: [OCPI spec 2.2.1: Tariff](<https://github.com/ocpi/ocpi/blob/release-2.2.1-bugfixes/mod_tariffs.asciidoc#131-tariff-object>)
//! * See: [OCPI spec 2.1.1: Tariff](<https://github.com/ocpi/ocpi/blob/release-2.1.1-bugfixes/mod_tariffs.md#31-tariff-object>)

use chrono::{DateTime, NaiveDate, Utc};
use rust_decimal::Decimal;

use crate::{
    explain::{
        ir::{
            Body, Bounds, Condition, ConditionPart, Dimension, Explanation, Fallback, Flat,
            FlatFee, FlatTier, Rate, Scope, Section, Tier, TimeWindow, Validity,
        },
        render::{render, Language},
    },
    money::VatOrigin,
    tariff::{
        v221::{Element, Restrictions, Tariff},
        v2x::DimensionType,
        Warning,
    },
    warning::VerdictExt as _,
    Money, Price, Verdict,
};

/// Build a human-language explanation of the given tariff as Markdown, in the given language.
///
/// The tariff is parsed into the normalized `v2.2.1` form first, so a `v2.1.1` tariff is explained as
/// its `v2.2.1` equivalent. Any warnings raised while parsing are returned alongside the
/// explanation; a hard parse failure returns an [`ErrorSet`](crate::warning::ErrorSet) instead.
pub(crate) fn explain(
    tariff: &crate::tariff::Versioned<'_>,
    language: Language,
) -> Verdict<String, Warning> {
    let parsed = tariff.to_v221();

    parsed.map_caveat(|tariff| render(&build(&tariff), language))
}

/// Read the parsed tariff into a language-independent explanation.
///
/// Dimensions are narrated energy first, then the time-based charges (charging then idle), then any
/// flat fee, followed by the session-level price bounds and validity window. When nothing produces
/// a section, a [`Fallback`] reason explains why in terms of the tariff.
pub(super) fn build(tariff: &Tariff<'_>) -> Explanation {
    let elements = &tariff.elements;
    let mut sections: Vec<Section> = Vec::new();

    for dimension in [
        DimensionType::Energy,
        DimensionType::Time,
        DimensionType::ParkingTime,
    ] {
        if let Some(section) = build_dimension(elements, dimension) {
            sections.push(Section::Dimension(section));
        }
    }
    if let Some(section) = build_flat(elements) {
        sections.push(Section::Flat(section));
    }
    if let Some(section) = build_bounds(tariff.min_price, tariff.max_price) {
        sections.push(Section::Bounds(section));
    }
    if let Some(section) = build_validity(tariff.start_date_time, tariff.end_date_time) {
        sections.push(Section::Validity(section));
    }

    let body = if sections.is_empty() {
        Body::Fallback(fallback_reason(tariff))
    } else {
        Body::Sections(sections)
    };

    Explanation {
        currency: tariff.currency,
        body,
    }
}

/// Explain why a tariff produces no charging narrative, in terms of what the tariff contains.
///
/// This is reached only when no dimension, price bound or validity window produced any content, so
/// the reason describes the cause in the tariff rather than any limitation of this tool.
fn fallback_reason(tariff: &Tariff<'_>) -> Fallback {
    let elements = &tariff.elements;

    // Every element is gated on reservations, so none apply to a regular charging session.
    if elements.iter().all(is_reservation_only) {
        return Fallback::ReservationOnly;
    }

    // None of the applicable elements define any price component to charge on.
    let has_components = elements
        .iter()
        .filter(|element| !is_reservation_only(element))
        .any(|element| !element.price_components.is_empty());

    if !has_components {
        return Fallback::NoPriceComponents;
    }

    // The only thing left that produces no content is a flat fee priced at zero.
    Fallback::FreeFlatOnly
}

/// Returns true when an element applies only to reservation sessions and so never applies to a
/// regular charging session.
fn is_reservation_only(element: &Element) -> bool {
    element
        .restrictions
        .as_ref()
        .is_some_and(|restrictions| restrictions.reservation.is_some())
}

/// A single priced tier of a dimension: a rate that applies under a set of restrictions.
struct Band<'a> {
    /// The rate for this tier.
    price: Money,

    /// The VAT applied to the rate.
    vat: VatOrigin,

    /// The smallest billable unit; consumption is rounded up to a multiple of this. The unit
    /// depends on the dimension: 1 Wh for energy, 1 second for charging or idle time.
    step_size: u64,

    /// The restrictions that bound this tier.
    restrictions: Option<&'a Restrictions>,
}

/// Collect the priced tiers for a single dimension, in matching order.
fn bands(elements: &[Element], dimension: DimensionType) -> Vec<Band<'_>> {
    let mut bands = Vec::new();

    for element in elements {
        // An element gated on reservations never applies to a regular charging session, so it
        // does not contribute a tier to the explanation.
        if is_reservation_only(element) {
            continue;
        }

        // Only the first price component per dimension in an element is used by the pricing
        // engine, so any later duplicates within the same element are ignored here too.
        if let Some(component) = element
            .price_components
            .iter()
            .find(|component| component.dimension_type == dimension)
        {
            bands.push(Band {
                price: component.price,
                vat: component.vat,
                step_size: component.step_size,
                restrictions: element.restrictions.as_ref(),
            });
        }
    }

    bands
}

/// Build the flat (per-session) fee section, or fees.
///
/// Like the metered dimensions, a tariff can have several flat tiers (one per matching element)
/// under different conditions, matched top-down. A flat fee can be gated by time of day, date, or a
/// consumption bound (`min/max_duration`, `min/max_kwh`), so the condition pulls in all of those.
///
/// A list of purely date-gated fees is listed chronologically, as for the metered dimensions.
fn build_flat(elements: &[Element]) -> Option<Flat> {
    let mut bands = bands(elements, DimensionType::Flat);

    // A tier with no condition always matches, so any flat tier after it is unreachable.
    let reachable = bands
        .iter()
        .position(|band| {
            band.restrictions
                .is_none_or(|restrictions| flat_condition(restrictions).is_empty())
        })
        .map(|index| index.saturating_add(1))
        .unwrap_or(bands.len());
    bands.truncate(reachable);

    let mut tiers: Vec<FlatTier> = bands
        .iter()
        .enumerate()
        .map(|(index, band)| {
            let parts = band.restrictions.map(flat_condition).unwrap_or_default();
            let condition = if !parts.is_empty() {
                Condition::When(parts)
            } else if index > 0 {
                Condition::Otherwise
            } else {
                Condition::Always
            };

            let fee = if is_free(band.price) {
                FlatFee::NoFee
            } else {
                FlatFee::Charged {
                    amount: band.price,
                    vat: band.vat,
                }
            };

            FlatTier { condition, fee }
        })
        .collect();

    let conditions: Vec<&Condition> = tiers.iter().map(|tier| &tier.condition).collect();
    let order = chronological_order(&conditions);

    let mut dropped_shadowed = false;
    if let Some(order) = order {
        dropped_shadowed = order.dropped_shadowed;
        tiers = keep_in_order(tiers, &order.keep);
    }

    // No flat tiers, or a lone zero fee, means there is no flat fee worth a sentence.
    match tiers.as_slice() {
        [] => None,
        [tier] if matches!(tier.fee, FlatFee::NoFee) => None,
        _ => Some(Flat {
            tiers,
            dropped_shadowed,
        }),
    }
}

/// The condition under which a flat tier applies: the qualifiers plus any consumption bounds.
fn flat_condition(restrictions: &Restrictions) -> Vec<ConditionPart> {
    let mut parts = qualifiers(restrictions);
    if let Some(scope) = duration_scope(restrictions) {
        parts.push(ConditionPart::DurationScope(scope));
    }
    if let Some(scope) = energy_scope(restrictions) {
        parts.push(ConditionPart::EnergyScope(scope));
    }
    parts
}

/// Build a metered dimension (energy, charging time or idle time) as a sequence of tiers.
///
/// A dimension can have several priced tiers, one per matching element, matched top-down: the first
/// matching element wins. Each tier carries the condition under which it applies, its rate, and
/// (when the billing step varies across tiers) its own billing step.
///
/// A trailing tier with no condition is the catch-all: it becomes [`Condition::Remaining`] when the
/// earlier tiers were purely consumption-bounded, and [`Condition::Otherwise`] when an earlier tier
/// was gated by something else (power, current, time of day). Tiers made unreachable by an earlier
/// catch-all are dropped and noted.
fn build_dimension(elements: &[Element], dimension: DimensionType) -> Option<Dimension> {
    let bands = bands(elements, dimension);
    if bands.is_empty() {
        return None;
    }

    // Compute each band's condition pieces: the dimension's own bound (primary), the other
    // consumption bound (secondary, which the spec also allows, e.g. an energy threshold on a
    // charging-time tier), and the non-consumption qualifiers (time of day, weekday, ...).
    let pieces: Vec<(
        Option<ConditionPart>,
        Option<ConditionPart>,
        Vec<ConditionPart>,
    )> = bands
        .iter()
        .map(|band| {
            let primary = band
                .restrictions
                .and_then(|restrictions| primary_scope(restrictions, dimension));
            let secondary = band
                .restrictions
                .and_then(|restrictions| secondary_scope(restrictions, dimension));
            let qualifiers = band.restrictions.map(qualifiers).unwrap_or_default();
            (primary, secondary, qualifiers)
        })
        .collect();

    // A tier with no consumption bound and no qualifiers always matches, so it is the catch-all:
    // every tier listed after it is unreachable. Keep the catch-all and drop the dead tiers.
    let reachable = pieces
        .iter()
        .position(|(primary, secondary, qualifiers)| {
            primary.is_none() && secondary.is_none() && qualifiers.is_empty()
        })
        .map(|index| index.saturating_add(1))
        .unwrap_or(pieces.len());
    let dropped = pieces.len().saturating_sub(reachable);

    // When every reachable tier shares the same billing step, describe it once for the dimension;
    // otherwise the step varies per tier and is noted inline on each.
    let first_step = bands.first().map(|band| band.step_size);
    let uniform = first_step.is_some_and(|step| {
        bands
            .iter()
            .take(reachable)
            .all(|band| band.step_size == step)
    });
    // A shared step of 1 (the smallest unit) is effectively continuous billing and not described.
    let uniform_step = first_step.filter(|&step| uniform && step != 1);

    // Track what earlier tiers looked like, to classify a trailing catch-all: "the remaining ..."
    // only follows purely consumption-bounded tiers; anything else makes it "otherwise".
    let mut seen_bound = false;
    let mut seen_qualifier = false;
    let mut tiers: Vec<Tier> = Vec::with_capacity(reachable);

    for (index, (band, (primary, secondary, qualifiers))) in
        bands.iter().zip(pieces).enumerate().take(reachable)
    {
        // A qualifier or a secondary bound is an extra gate (not the dimension's own tiering), so
        // it makes a trailing catch-all read "otherwise" rather than "the remaining ...".
        let has_qualifier = !qualifiers.is_empty() || secondary.is_some();
        let primary_present = primary.is_some();
        let is_catch_all = primary.is_none() && secondary.is_none() && qualifiers.is_empty();

        let condition = if !is_catch_all {
            // The qualifiers lead, then the dimension's own bound, then the secondary bound.
            let mut parts = qualifiers;
            if let Some(primary) = primary {
                parts.push(primary);
            }
            if let Some(secondary) = secondary {
                parts.push(secondary);
            }
            Condition::When(parts)
        } else if index == 0 {
            Condition::Always
        } else if seen_bound && !seen_qualifier {
            Condition::Remaining
        } else {
            Condition::Otherwise
        };

        let free = is_free(band.price);
        let rate = if free {
            Rate::Free
        } else {
            Rate::Priced {
                amount: band.price,
                vat: band.vat,
            }
        };

        // A step of 1 (the smallest unit) is effectively continuous billing, and a free tier has
        // nothing to bill in steps, so neither earns a note. When the step is shared across tiers
        // it is described once for the dimension instead of inline here.
        let step = if uniform || band.step_size == 1 || free {
            None
        } else {
            Some(band.step_size)
        };

        seen_bound |= primary_present;
        seen_qualifier |= has_qualifier;
        tiers.push(Tier {
            condition,
            rate,
            step,
        });
    }

    let conditions: Vec<&Condition> = tiers.iter().map(|tier| &tier.condition).collect();
    let order = chronological_order(&conditions);

    let mut dropped_shadowed = false;
    if let Some(order) = order {
        dropped_shadowed = order.dropped_shadowed;
        tiers = keep_in_order(tiers, &order.keep);
    }

    Some(Dimension {
        kind: dimension,
        tiers,
        uniform_step,
        dropped_unreachable: dropped > 0,
        dropped_shadowed,
    })
}

/// A tier list rewritten into chronological order.
struct DateOrder {
    /// The tiers to list, by their index in the original list, in the order to list them.
    keep: Vec<usize>,

    /// Whether any tier was left out because earlier tiers already cover every date it applies to.
    dropped_shadowed: bool,
}

/// One tier's date range, as a half-open `[start, end)` span with any open end filled in.
struct DateSpan {
    /// The tier's index in the original list.
    index: usize,

    /// The first date the tier applies to (`start_date` is inclusive).
    start: NaiveDate,

    /// The first date the tier no longer applies to (`end_date` is exclusive).
    end: NaiveDate,
}

/// Rewrite a purely date-gated tier list into chronological order, dropping the tiers whose dates
/// are already covered by earlier tiers.
///
/// Tiers are otherwise listed in matching order, because the pricing engine takes the rate from the
/// first element whose restrictions match and a reader has to apply that same rule to work out which
/// rate wins.
///
/// Reordering is only honest once no two listed tiers can match the same session. This
/// happens in two steps: a tier whose whole date range is already covered by earlier tiers can never
/// supply the rate and is dropped, and the survivors are only reordered when their ranges no longer
/// overlap at all.
///
/// `None` means the list has to stay in matching order: some tier is gated by more than a date
/// range, or the surviving ranges still overlap so their order carries which rate wins.
fn chronological_order(conditions: &[&Condition]) -> Option<DateOrder> {
    let mut spans: Vec<DateSpan> = Vec::with_capacity(conditions.len());
    for (index, condition) in conditions.iter().enumerate() {
        // A single tier gated by anything other than dates makes the whole list order-dependent.
        let (start, end) = date_span(condition)?;
        spans.push(DateSpan { index, start, end });
    }

    let mut covered: Vec<(NaiveDate, NaiveDate)> = Vec::with_capacity(spans.len());
    let mut kept: Vec<DateSpan> = Vec::with_capacity(spans.len());
    let mut dropped_shadowed = false;

    for span in spans {
        if is_covered(&covered, span.start, span.end) {
            dropped_shadowed = true;
            continue;
        }
        covered.push((span.start, span.end));
        kept.push(span);
    }

    kept.sort_by_key(|span| (span.start, span.end));

    // Two surviving tiers that share a date can both match one session, so which of them is listed
    // first still says which rate wins. Such a list stays in matching order.
    for pair in kept.windows(2) {
        let [earlier, later] = pair else {
            continue;
        };
        if earlier.end > later.start {
            return None;
        }
    }

    Some(DateOrder {
        keep: kept.iter().map(|span| span.index).collect(),
        dropped_shadowed,
    })
}

/// The date range of a tier gated by nothing but a `start_date`/`end_date` range, as a half-open
/// `[start, end)` span. An absent bound is filled in with the extreme date so that spans compare
/// directly.
///
/// `None` when the tier is gated by anything besides a date range, or by nothing at all.
fn date_span(condition: &Condition) -> Option<(NaiveDate, NaiveDate)> {
    let Condition::When(parts) = condition else {
        return None;
    };
    let [ConditionPart::DateRange { start, end }] = parts.as_slice() else {
        return None;
    };

    Some((
        start.unwrap_or(NaiveDate::MIN),
        end.unwrap_or(NaiveDate::MAX),
    ))
}

/// Returns true when the half-open span `[start, end)` falls entirely within the union of the
/// `covered` spans, so a tier bounded by it can never be reached.
fn is_covered(covered: &[(NaiveDate, NaiveDate)], start: NaiveDate, end: NaiveDate) -> bool {
    // An empty span means the tier never applies for its own reasons, not because it is covered.
    // Leaving it in the list keeps that visible rather than quietly hiding it.
    if start >= end {
        return false;
    }

    let mut sorted = covered.to_vec();
    sorted.sort_unstable();

    let mut reached = start;
    for (covered_start, covered_end) in sorted {
        // A gap before the next covered span leaves part of the range uncovered.
        if covered_start > reached {
            return false;
        }
        reached = reached.max(covered_end);
        if reached >= end {
            return true;
        }
    }

    false
}

/// Rebuild a tier list as the tiers at the given indices, in the order those indices are given.
fn keep_in_order<T>(tiers: Vec<T>, keep: &[usize]) -> Vec<T> {
    let mut slots: Vec<Option<T>> = tiers.into_iter().map(Some).collect();
    let mut ordered: Vec<T> = Vec::with_capacity(keep.len());

    for &index in keep {
        let Some(tier) = slots.get_mut(index).and_then(Option::take) else {
            continue;
        };
        ordered.push(tier);
    }

    ordered
}

/// The consumption bound that matches the dimension: duration for charging/idle time, energy for
/// the energy dimension. This is the tier's natural "for the first N" bound.
fn primary_scope(restrictions: &Restrictions, dimension: DimensionType) -> Option<ConditionPart> {
    match dimension {
        DimensionType::Time | DimensionType::ParkingTime => {
            duration_scope(restrictions).map(ConditionPart::DurationScope)
        }
        DimensionType::Energy => energy_scope(restrictions).map(ConditionPart::EnergyScope),
        DimensionType::Flat => None,
    }
}

/// The consumption bound of the other kind than the dimension's own. The spec allows, for example,
/// an energy threshold on a charging-time tier; this surfaces it as an extra condition.
fn secondary_scope(restrictions: &Restrictions, dimension: DimensionType) -> Option<ConditionPart> {
    match dimension {
        DimensionType::Time | DimensionType::ParkingTime => {
            energy_scope(restrictions).map(ConditionPart::EnergyScope)
        }
        DimensionType::Energy => duration_scope(restrictions).map(ConditionPart::DurationScope),
        DimensionType::Flat => None,
    }
}

/// Classify the duration restrictions of a tier as a scope. These bounds are on how long the
/// session has lasted, not a time of day.
fn duration_scope(restrictions: &Restrictions) -> Option<Scope<chrono::TimeDelta>> {
    match (restrictions.min_duration, restrictions.max_duration) {
        (None, Some(max)) => Some(Scope::UpTo(max)),
        (Some(min), None) => Some(Scope::After(min)),
        (Some(min), Some(max)) => Some(Scope::Between(min, max)),
        (None, None) => None,
    }
}

/// Classify the energy restrictions of a tier as a scope, bounded by consumed kWh.
fn energy_scope(restrictions: &Restrictions) -> Option<Scope<crate::Kwh>> {
    match (restrictions.min_kwh, restrictions.max_kwh) {
        (None, Some(max)) => Some(Scope::UpTo(max)),
        (Some(min), None) => Some(Scope::After(min)),
        (Some(min), Some(max)) => Some(Scope::Between(min, max)),
        (None, None) => None,
    }
}

/// Collect the non-tiering restrictions (time of day, weekday, date, power, current) into condition
/// parts, in the order they should be listed.
fn qualifiers(restrictions: &Restrictions) -> Vec<ConditionPart> {
    let mut parts = Vec::new();

    match (restrictions.start_time, restrictions.end_time) {
        // Equal start and end times describe an empty window, so the element never applies. The
        // spec uses 00:00 for "end of day", which is the only case where equal times would not be
        // degenerate, but that is the wrapping branch below, not this one.
        (Some(start), Some(end)) if start == end => {
            parts.push(ConditionPart::TimeWindow(TimeWindow::Empty { start, end }));
        }
        // An end time earlier than the start time means the window wraps past midnight.
        (Some(start), Some(end)) if end < start => {
            parts.push(ConditionPart::TimeWindow(TimeWindow::Wrapping {
                start,
                end,
            }));
        }
        (Some(start), Some(end)) => {
            parts.push(ConditionPart::TimeWindow(TimeWindow::Between {
                start,
                end,
            }));
        }
        (Some(start), None) => parts.push(ConditionPart::TimeWindow(TimeWindow::From { start })),
        (None, Some(end)) => parts.push(ConditionPart::TimeWindow(TimeWindow::Before { end })),
        (None, None) => {}
    }

    if let Some(days) = restrictions.day_of_week.as_ref().filter(|d| !d.is_empty()) {
        parts.push(ConditionPart::Weekdays(days.clone()));
    }

    match (restrictions.start_date, restrictions.end_date) {
        (None, None) => {}
        (start, end) => parts.push(ConditionPart::DateRange { start, end }),
    }

    if let Some(min) = restrictions.min_power {
        parts.push(ConditionPart::MinPower(min));
    }
    if let Some(max) = restrictions.max_power {
        parts.push(ConditionPart::MaxPower(max));
    }
    if let Some(min) = restrictions.min_current {
        parts.push(ConditionPart::MinCurrent(min));
    }
    if let Some(max) = restrictions.max_current {
        parts.push(ConditionPart::MaxCurrent(max));
    }

    parts
}

/// Build the overall `min_price`/`max_price` bounds section, if either bound is present.
fn build_bounds(min_price: Option<Price>, max_price: Option<Price>) -> Option<Bounds> {
    if min_price.is_none() && max_price.is_none() {
        None
    } else {
        Some(Bounds {
            min: min_price,
            max: max_price,
        })
    }
}

/// Build the validity-window section from the tariff's own start/end instants.
fn build_validity(
    start_date_time: Option<DateTime<Utc>>,
    end_date_time: Option<DateTime<Utc>>,
) -> Option<Validity> {
    match (start_date_time, end_date_time) {
        (Some(start), Some(end)) => Some(Validity::Between { start, end }),
        (Some(start), None) => Some(Validity::From { start }),
        (None, Some(end)) => Some(Validity::Until { end }),
        (None, None) => None,
    }
}

/// Return true when a rate is exactly zero, so it can be narrated as "free".
fn is_free(money: Money) -> bool {
    Decimal::from(money) == Decimal::ZERO
}