tix-tracker 0.8.0

//! Explicit estimate conversion: one issue's estimate, in the unit a calculation
//! counts in (mission `cycle-capacity-planning-01M3C85C`, WP02).
//!
//! # What an `EstimateValue` is
//!
//! The data model's §3 entity, and nothing more: the text the issue wrote
//! ([`raw`](EstimateValue::raw), preserved verbatim for diagnostics/export), the unit
//! it named ([`unit`](EstimateValue::unit), never inferred), the number when it could
//! be read ([`value`](EstimateValue::value)), the number **after an explicit
//! conversion** when one exists ([`converted_value`](EstimateValue::converted_value)),
//! and the ordered [`diagnostics`](EstimateValue::diagnostics) that say why a step did
//! not happen.
//!
//! # The doors this module keeps shut
//!
//! * **A missing or incompatible conversion is a diagnostic, never a number.** The
//!   arithmetic is [`crate::wip::WipConfig::convert`]'s — the WIP mission's
//!   per-board/team unit/conversion registry, reused and never re-declared — so an
//!   undeclared unit is `missing_conversion`, a unit the board does not know is
//!   `unknown_unit`, and a conversion that does not divide exactly is
//!   `ambiguous_conversion`. None of the three becomes zero, and none becomes the
//!   issue's raw number standing in for the target unit (C-004).
//! * **An unestimated issue stays unestimated.** [`EstimateValue::unestimated`] is a
//!   distinct value — `raw` is `None` — with no diagnostic, because stating no
//!   estimate is not an error. It is never silently counted as zero: a caller that
//!   sums must decide what to do about it, and [`is_unestimated`](EstimateValue::is_unestimated)
//!   is how it asks.
//! * **A blank estimate is unestimated, not invalid.** `estimate: ""` states nothing,
//!   which is what the WIP aggregate already decides ("No estimate is zero estimate"),
//!   so it reads the same here.
//!
//! # Diagnostic wording
//!
//! [`crate::wip::WipConfig::convert`] reports a unit finding with the board's own
//! words but no issue identity, and a finding nobody can locate is not actionable.
//! Every diagnostic this module produces therefore wraps the registry's sentence with
//! the issue number and the raw text — the same shape
//! [`crate::wip::aggregate`] uses — and keeps the registry's `kind` verbatim so every
//! surface branches on one vocabulary.

use crate::wip::{Estimate as WipEstimate, WipConfig, WipDiagnostic};

/// One issue's estimate as the data model defines it (data-model §3).
///
/// Built by [`parse`](Self::parse) (the unit-native reading) and turned into a
/// per-unit reading by [`converted_to`](Self::converted_to). Both are cheap and total:
/// neither returns an error, because "the estimate could not be counted" is a
/// diagnostic on a value that still exists, not a refusal that loses the raw text.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct EstimateValue {
    /// The text the issue wrote, verbatim. `None` means the issue states no estimate
    /// at all — which stays visible as unestimated and is never zero.
    pub raw: Option<String>,
    /// The unit the issue named, when it named one. Never inferred: a bare `3` has no
    /// unit here, and whether it can be counted in a target unit is the registry's
    /// answer (`WipConfig::convert` treats a bare estimate as already in the target).
    pub unit: Option<String>,
    /// The number the issue stated, when it could be read. `None` for an unestimated
    /// issue *and* for an estimate that is not `<number><unit>`.
    pub value: Option<u32>,
    /// The number after an explicit conversion, when one exists. `None` when the
    /// estimate was never converted, is unestimated, or the conversion was refused
    /// (the [`diagnostics`](Self::diagnostics) say which).
    pub converted_value: Option<u32>,
    /// What was wrong, in the order it was found: the parse findings first, then the
    /// conversion findings. Empty for an estimate that read and converted cleanly, and
    /// empty for an unestimated issue.
    pub diagnostics: Vec<WipDiagnostic>,
    /// The unit [`converted_value`](Self::converted_value) counts in.
    ///
    /// `Some` **exactly when** `converted_value` is `Some`, so the number is never
    /// presented without the unit it is expressed in.
    converted_in: Option<String>,
}

impl EstimateValue {
    /// An issue that states no estimate.
    ///
    /// The explicit "none" the data model asks for: nothing is zero, nothing is
    /// guessed, and no diagnostic is raised. A caller summing a scope must count this
    /// separately (C-005).
    #[must_use]
    pub fn unestimated() -> Self {
        Self::default()
    }

    /// Read the free-form `estimate:` text an issue states (`raw`, verbatim).
    ///
    /// The text is preserved exactly as written and *parsed* from its trimmed form, so
    /// a stray space cannot turn an estimate into an unreadable one and cannot change
    /// the text a diagnostic quotes. `number` is the diagnostic's context only — the
    /// value carries no issue identity, but a finding that cannot be located is not
    /// actionable, so the message names the issue.
    ///
    /// A failure is a diagnostic, not a refusal: the returned value still carries
    /// `raw`, and `value`/`converted_value` stay `None`.
    #[must_use]
    pub fn parse(number: u32, raw: &str) -> Self {
        match WipEstimate::parse(raw.trim()) {
            Ok(estimate) => Self {
                raw: Some(raw.to_string()),
                unit: estimate.unit,
                value: Some(estimate.value),
                converted_value: None,
                diagnostics: Vec::new(),
                converted_in: None,
            },
            Err(error) => Self {
                raw: Some(raw.to_string()),
                unit: None,
                value: None,
                converted_value: None,
                diagnostics: error
                    .diagnostics()
                    .iter()
                    .map(|finding| {
                        located(
                            number,
                            format!("states `{raw}`, which cannot be counted"),
                            finding,
                        )
                    })
                    .collect(),
                converted_in: None,
            },
        }
    }

    /// This estimate converted into `unit`, through the board's own registry.
    ///
    /// The one place a conversion happens. `converted_value` is set only on success;
    /// a refusal appends the registry's finding (re-worded to name the issue) and
    /// leaves the number absent, so an unconvertible estimate can never be summed as
    /// if it were counted (C-004).
    ///
    /// An unestimated issue — and an estimate whose number could not be read — is
    /// returned unchanged: there is nothing to convert, and its own diagnostic already
    /// says why.
    #[must_use]
    pub fn converted_to(&self, number: u32, registry: &WipConfig, unit: &str) -> Self {
        let mut value = self.clone();
        let (Some(raw), Some(amount)) = (self.raw.as_deref(), self.value) else {
            return value;
        };
        let estimate = WipEstimate {
            value: amount,
            unit: self.unit.clone(),
        };
        match registry.convert(&estimate, unit) {
            Ok(converted) => {
                value.converted_value = Some(converted);
                value.converted_in = Some(unit.to_string());
            }
            Err(error) => value
                .diagnostics
                .extend(error.diagnostics().iter().map(|finding| {
                    located(
                        number,
                        format!("states `{raw}`, which cannot be counted in `{unit}`"),
                        finding,
                    )
                })),
        }
        value
    }

    /// The text the issue wrote, verbatim.
    #[must_use]
    pub fn raw(&self) -> Option<&str> {
        self.raw.as_deref()
    }

    /// The unit the issue named, when it named one.
    #[must_use]
    pub fn unit(&self) -> Option<&str> {
        self.unit.as_deref()
    }

    /// The unit [`converted_value`](Self::converted_value) counts in.
    #[must_use]
    pub fn converted_in(&self) -> Option<&str> {
        self.converted_in.as_deref()
    }

    /// The findings, in the order they were produced.
    #[must_use]
    pub fn diagnostics(&self) -> &[WipDiagnostic] {
        &self.diagnostics
    }

    /// Whether the issue states no estimate. It is visible as unestimated, never zero.
    #[must_use]
    pub fn is_unestimated(&self) -> bool {
        self.raw.is_none()
    }

    /// Whether the text could be read as a number (conversion aside).
    #[must_use]
    pub fn is_valid(&self) -> bool {
        self.value.is_some()
    }

    /// Whether an explicit conversion produced a number — the one predicate a summing
    /// caller may count on.
    #[must_use]
    pub fn is_converted(&self) -> bool {
        self.converted_value.is_some()
    }

    /// The estimate as it reads in a message: the text as written, or `unestimated`.
    #[must_use]
    pub fn render(&self) -> String {
        self.raw
            .clone()
            .unwrap_or_else(|| "unestimated".to_string())
    }
}

/// Wrap the registry's finding so it names the issue it came from (the crate's style).
///
/// The `kind` is kept verbatim: the machine-readable half stays the WIP mission's, so
/// `missing_conversion`/`ambiguous_conversion`/`unknown_unit`/`malformed_estimate` mean
/// one thing in every surface.
fn located(number: u32, context: String, finding: &WipDiagnostic) -> WipDiagnostic {
    WipDiagnostic {
        kind: finding.kind,
        message: format!("issue #{number} {context}: {}", finding.message),
        because: finding.because.clone(),
    }
}