dpp-plugin-sdk 0.21.0

//! Reusable field validation for product group plugins.
//!
//! [`Validator`] is a fluent collector: each `require_*` / `optional_*` method
//! records a [`PluginFieldError`] when a check fails and is chainable, so a
//! plugin's `validate_input` reads as a declarative list of field constraints.
//! [`Validator::finish`] reports *all* failures at once rather than stopping at
//! the first — better for surfacing form errors to a manufacturer.
//!
//! The free functions [`num`] and [`str_of`] are convenience readers for
//! `calculate_metrics` bodies, and [`threshold_status`] is the shared
//! "measured value at or under threshold" classification they compare against.

use dpp_plugin_traits::{PluginComplianceStatus, PluginError, PluginFieldError, PluginInput};
use dpp_rules::common::identifier::{DidRejection, check_did, is_absolute_web_url};
use serde_json::Value;

/// A present, non-null value for `key`, or `None` if absent/null.
fn present<'a>(input: &'a Value, key: &str) -> Option<&'a Value> {
    match input.get(key) {
        Some(Value::Null) | None => None,
        other => other,
    }
}

/// Read a finite number field (ignores absent/non-numeric/NaN/inf).
#[must_use]
pub fn num(input: &PluginInput, key: &str) -> Option<f64> {
    input
        .get(key)
        .and_then(Value::as_f64)
        .filter(|n| n.is_finite())
}

/// Read a string field.
#[must_use]
pub fn str_of<'a>(input: &'a PluginInput, key: &str) -> Option<&'a str> {
    input.get(key).and_then(Value::as_str)
}

/// Classify a measured value against a compliance threshold: `Compliant` if
/// present and at or under `threshold`, `NonCompliant` otherwise (including
/// when `value` is absent — a missing measurement is not assumed compliant).
#[must_use]
pub fn threshold_status(value: Option<f64>, threshold: f64) -> PluginComplianceStatus {
    if value.is_some_and(|v| v <= threshold) {
        PluginComplianceStatus::Compliant
    } else {
        PluginComplianceStatus::NonCompliant
    }
}

/// Fluent per-field validator. See module docs.
pub struct Validator<'a> {
    input: &'a Value,
    errors: Vec<PluginFieldError>,
}

impl<'a> Validator<'a> {
    #[must_use]
    pub fn new(input: &'a PluginInput) -> Self {
        Self {
            input,
            errors: Vec::new(),
        }
    }

    fn push_opt(&mut self, key: &str, err: Option<(&str, String)>) {
        if let Some((code, message)) = err {
            self.errors.push(PluginFieldError {
                field: format!("/{key}"),
                code: code.to_owned(),
                message,
            });
        }
    }

    /// Record a failure against an already-built field path.
    ///
    /// [`push_opt`](Self::push_opt) derives `/{key}` from a single field name,
    /// which cannot name a field *inside* an object. A nested identifier
    /// reports `/productIdentifier/gtin`, so the caller builds the path.
    fn push_at(&mut self, field: String, code: &str, message: String) {
        self.errors.push(PluginFieldError {
            field,
            code: code.to_owned(),
            message,
        });
    }

    /// Require a present, non-empty string.
    pub fn require_str(&mut self, key: &str) -> &mut Self {
        let err = match present(self.input, key) {
            None => Some(("missing", format!("{key} is required"))),
            Some(v) => match v.as_str() {
                Some(s) if !s.trim().is_empty() => None,
                Some(_) => Some(("empty", format!("{key} must not be empty"))),
                None => Some(("type", format!("{key} must be a string"))),
            },
        };
        self.push_opt(key, err);
        self
    }

    /// Require a string field whose value is one of `allowed`.
    pub fn require_enum(&mut self, key: &str, allowed: &[&str]) -> &mut Self {
        let err = match present(self.input, key).and_then(Value::as_str) {
            None => Some(("missing", format!("{key} is required"))),
            Some(s) if allowed.contains(&s) => None,
            Some(_) => Some(("out_of_range", format!("{key} must be one of {allowed:?}"))),
        };
        self.push_opt(key, err);
        self
    }

    /// Require a 14-digit GS1 GTIN string with a valid check digit.
    pub fn require_gtin(&mut self, key: &str) -> &mut Self {
        let err = match present(self.input, key).and_then(Value::as_str) {
            None => Some(("missing", format!("{key} is required"))),
            Some(g) if g.len() == 14 && g.bytes().all(|b| b.is_ascii_digit()) => {
                if gs1_check_digit_valid(g) {
                    None
                } else {
                    Some(("checksum", format!("{key} has an invalid GS1 check digit")))
                }
            }
            Some(_) => Some(("format", format!("{key} must be 14 digits"))),
        };
        self.push_opt(key, err);
        self
    }

    /// Require an EN 18219:2026 clause 5 unique product identifier object.
    ///
    /// 🚨 **This replaces [`require_gtin`](Self::require_gtin) for product group
    /// data.** Product group records used to carry a bare top-level `gtin`, and
    /// every plugin required it. They now carry a `productIdentifier` object
    /// whose shape depends on the scheme that issued it, and the GTIN — when
    /// there is one at all — lives *inside* it:
    ///
    /// ```json
    /// { "productIdentifier": { "scheme": "gs1", "gtin": "09506000134352" } }
    /// ```
    ///
    /// A plugin still asking for `gtin` therefore reports *"gtin is required"*
    /// against data that identifies itself perfectly well. That is not a
    /// hypothetical: it is what every non-textile plugin did once the schemas
    /// moved, and because both host call sites discard a plugin error, the
    /// compliance determination silently stopped being made rather than failing
    /// loudly.
    ///
    /// # Why the scheme decides which field is checked
    ///
    /// Clause 5.1 offers three schemes as **alternatives, not a hierarchy**.
    /// Only scheme 1 is GS1-keyed, so only scheme 1 has a GTIN; schemes 2 and 3
    /// are self-issuing and carry a URL and a DID respectively. Validating a
    /// GTIN unconditionally would reject exactly the passports the identifier
    /// work exists to enable, which is the defect this method replaces.
    ///
    /// An unrecognised scheme is refused rather than skipped: a scheme string
    /// nobody has mapped is where an invented identifier passes unexamined.
    pub fn require_product_identifier(&mut self, key: &str) -> &mut Self {
        let Some(object) = present(self.input, key).and_then(Value::as_object) else {
            self.push_opt(key, Some(("missing", format!("{key} is required"))));
            return self;
        };
        let Some(scheme) = object.get("scheme").and_then(Value::as_str) else {
            self.push_at(
                format!("/{key}/scheme"),
                "missing",
                format!("{key}.scheme is required"),
            );
            return self;
        };
        // Each arm names the one field its scheme is keyed on. The branch field
        // is required *because* the scheme was declared, so a missing one is
        // reported against the field, not against the scheme that implies it.
        let (field, err) = match scheme {
            "gs1" => (
                "gtin",
                match object.get("gtin").and_then(Value::as_str) {
                    None => Some(("missing", format!("{key}.gtin is required for scheme gs1"))),
                    Some(g) if g.len() == 14 && g.bytes().all(|b| b.is_ascii_digit()) => {
                        if gs1_check_digit_valid(g) {
                            None
                        } else {
                            Some((
                                "checksum",
                                format!("{key}.gtin has an invalid GS1 check digit"),
                            ))
                        }
                    }
                    Some(_) => Some(("format", format!("{key}.gtin must be 14 digits"))),
                },
            ),
            "identificationLink" => (
                "url",
                match object.get("url").and_then(Value::as_str) {
                    None => Some((
                        "missing",
                        format!("{key}.url is required for scheme identificationLink"),
                    )),
                    // Checked only to be an absolute http(s) URL with a host.
                    // EN IEC 61406 format rules are not applied, so passing is
                    // not a conformance claim — the schema says the same.
                    Some(u) if is_absolute_web_url(u) => None,
                    Some(_) => Some(("format", format!("{key}.url must be an absolute URL"))),
                },
            ),
            "did" => (
                "did",
                match object.get("did").and_then(Value::as_str) {
                    None => Some(("missing", format!("{key}.did is required for scheme did"))),
                    // The method set is closed: a DID method no reader can
                    // resolve identifies nothing.
                    Some(d) => match check_did(d) {
                        Ok(()) => None,
                        Err(DidRejection::UnsupportedMethod(method)) => Some((
                            "format",
                            format!(
                                "{key}.did method '{method}' is not did:web, did:ethr or did:ebsi"
                            ),
                        )),
                        Err(DidRejection::EmptyMethodId) => Some((
                            "format",
                            format!("{key}.did names a method but no identifier"),
                        )),
                        Err(DidRejection::Malformed) => {
                            Some(("format", format!("{key}.did is not a well-formed W3C DID")))
                        }
                    },
                },
            ),
            other => {
                self.push_at(
                    format!("/{key}/scheme"),
                    "unknown",
                    format!("{key}.scheme '{other}' is not an EN 18219 clause 5 scheme"),
                );
                return self;
            }
        };
        if let Some((code, message)) = err {
            self.push_at(format!("/{key}/{field}"), code, message);
        }
        self
    }

    /// Require a recognized ISO 3166-1 alpha-2 country code.
    pub fn require_country(&mut self, key: &str) -> &mut Self {
        let err = match present(self.input, key).and_then(Value::as_str) {
            None => Some(("missing", format!("{key} is required"))),
            Some(c) if c.len() == 2 && c.bytes().all(|b| b.is_ascii_uppercase()) => {
                if dpp_rules::country_code_valid(c) {
                    None
                } else {
                    Some((
                        "invalid",
                        format!("{key} is not a recognized ISO 3166-1 alpha-2 code"),
                    ))
                }
            }
            Some(_) => Some((
                "format",
                format!("{key} must be a 2-letter uppercase country code"),
            )),
        };
        self.push_opt(key, err);
        self
    }

    /// Require a present, finite number greater than 0.
    pub fn require_positive(&mut self, key: &str) -> &mut Self {
        let err = match num(self.input, key) {
            None => Some((
                "missing",
                format!("{key} is required and must be a finite number"),
            )),
            Some(v) if v <= 0.0 => Some(("out_of_range", format!("{key} must be greater than 0"))),
            Some(_) => None,
        };
        self.push_opt(key, err);
        self
    }

    /// Require a present, finite number greater than or equal to 0.
    pub fn require_non_negative(&mut self, key: &str) -> &mut Self {
        let err = match num(self.input, key) {
            None => Some((
                "missing",
                format!("{key} is required and must be a finite number"),
            )),
            Some(v) if v < 0.0 => Some(("out_of_range", format!("{key} must be 0 or greater"))),
            Some(_) => None,
        };
        self.push_opt(key, err);
        self
    }

    /// Require a present, finite number in `[0, 100]`.
    pub fn require_pct(&mut self, key: &str) -> &mut Self {
        let err = match num(self.input, key) {
            None => Some((
                "missing",
                format!("{key} is required and must be a number in 0..=100"),
            )),
            Some(v) if !(0.0..=100.0).contains(&v) => {
                Some(("out_of_range", format!("{key} must be in 0..=100")))
            }
            Some(_) => None,
        };
        self.push_opt(key, err);
        self
    }

    /// Require a present non-negative integer that is at least 1.
    pub fn require_positive_int(&mut self, key: &str) -> &mut Self {
        let err = match present(self.input, key).and_then(Value::as_u64) {
            None => Some((
                "missing",
                format!("{key} is required and must be a non-negative integer"),
            )),
            Some(0) => Some(("out_of_range", format!("{key} must be at least 1"))),
            Some(_) => None,
        };
        self.push_opt(key, err);
        self
    }

    /// If present (and non-null), the value must be an integer of at least 1.
    ///
    /// The optional counterpart of [`Self::require_positive_int`], for a field
    /// whose *presence* is conditional but whose *value*, once given, is still
    /// constrained. Deliberately not expressible as
    /// [`Self::optional_non_negative`], which would admit `0` and a fractional
    /// count.
    pub fn optional_positive_int(&mut self, key: &str) -> &mut Self {
        let err = match present(self.input, key) {
            None => None,
            Some(v) => match v.as_u64() {
                None => Some((
                    "invalid_type",
                    format!("{key} must be a non-negative integer"),
                )),
                Some(0) => Some(("out_of_range", format!("{key} must be at least 1"))),
                Some(_) => None,
            },
        };
        self.push_opt(key, err);
        self
    }

    /// Require a present boolean.
    pub fn require_bool(&mut self, key: &str) -> &mut Self {
        let err = match present(self.input, key) {
            None => Some(("missing", format!("{key} is required"))),
            Some(v) if v.is_boolean() => None,
            Some(_) => Some(("type", format!("{key} must be a boolean"))),
        };
        self.push_opt(key, err);
        self
    }

    /// Require a present, non-empty array.
    pub fn require_non_empty_array(&mut self, key: &str) -> &mut Self {
        let err = match present(self.input, key).and_then(Value::as_array) {
            None => Some(("missing", format!("{key} is required and must be an array"))),
            Some(a) if a.is_empty() => Some(("empty", format!("{key} must not be empty"))),
            Some(_) => None,
        };
        self.push_opt(key, err);
        self
    }

    /// Require a present, non-empty object.
    ///
    /// The counterpart to [`require_non_empty_array`](Self::require_non_empty_array)
    /// for a schema-required field whose value is a nested object — an
    /// unsold-goods report's `entity` and `financialYear`, for instance.
    ///
    /// 🚨 **Presence only. It does not reach inside.** `present` is
    /// `input.get(key)` with no path traversal, so nothing here can assert a
    /// field *within* the object; the nested `required` list is enforced by
    /// schema validation at publish and not at this tier. An empty object is
    /// refused because it satisfies "present" while carrying none of what made
    /// the field required.
    pub fn require_object(&mut self, key: &str) -> &mut Self {
        let err = match present(self.input, key).and_then(Value::as_object) {
            None => Some((
                "missing",
                format!("{key} is required and must be an object"),
            )),
            Some(o) if o.is_empty() => Some(("empty", format!("{key} must not be empty"))),
            Some(_) => None,
        };
        self.push_opt(key, err);
        self
    }

    /// If present (and non-null), the value must be a finite number in `[0, 100]`.
    pub fn optional_pct(&mut self, key: &str) -> &mut Self {
        let err = match present(self.input, key) {
            None => None,
            Some(v) => match v.as_f64().filter(|n| n.is_finite()) {
                Some(n) if (0.0..=100.0).contains(&n) => None,
                _ => Some(("out_of_range", format!("{key} must be a number in 0..=100"))),
            },
        };
        self.push_opt(key, err);
        self
    }

    /// If present (and non-null), the value must be a finite number in `[min, max]`.
    ///
    /// For a field that is optional (its absence is meaningful) but must be
    /// bounded when supplied — e.g. a 0–10 repairability score that gates a
    /// verdict only when present.
    pub fn optional_range(&mut self, key: &str, min: f64, max: f64) -> &mut Self {
        let err = match present(self.input, key) {
            None => None,
            Some(v) => match v.as_f64().filter(|n| n.is_finite()) {
                Some(n) if (min..=max).contains(&n) => None,
                _ => Some((
                    "out_of_range",
                    format!("{key} must be a number in {min}..={max}"),
                )),
            },
        };
        self.push_opt(key, err);
        self
    }

    /// If present (and non-null), the value must be a finite number ≥ 0.
    pub fn optional_non_negative(&mut self, key: &str) -> &mut Self {
        let err = match present(self.input, key) {
            None => None,
            Some(v) => match v.as_f64().filter(|n| n.is_finite()) {
                Some(n) if n >= 0.0 => None,
                _ => Some(("out_of_range", format!("{key} must be a finite number ≥ 0"))),
            },
        };
        self.push_opt(key, err);
        self
    }

    /// Finish validation, returning every collected error at once.
    pub fn finish(&mut self) -> Result<(), PluginError> {
        if self.errors.is_empty() {
            Ok(())
        } else {
            Err(PluginError::ValidationErrors(std::mem::take(
                &mut self.errors,
            )))
        }
    }
}

/// GS1 check-digit validation for GTIN-14.
///
/// Even-indexed positions (0, 2, 4, … 12) are weighted ×3; odd-indexed ×1.
/// The check digit at position 13 must equal `(10 − sum mod 10) mod 10`.
fn gs1_check_digit_valid(gtin: &str) -> bool {
    let bytes = gtin.as_bytes();
    debug_assert_eq!(bytes.len(), 14, "caller must check length == 14 first");
    let sum: u32 = bytes[..13]
        .iter()
        .enumerate()
        .map(|(i, &b)| {
            let d = (b - b'0') as u32;
            if i % 2 == 0 { d * 3 } else { d }
        })
        .sum();
    let expected = (10 - sum % 10) % 10;
    expected == (bytes[13] - b'0') as u32
}

#[cfg(test)]
mod tests {
    use super::*;
    use serde_json::json;

    #[test]
    fn collects_all_failures() {
        let input = json!({ "gtin": "12-34", "voltage": -1.0 });
        let err = Validator::new(&input)
            .require_gtin("gtin")
            .require_positive("voltage")
            .require_str("name")
            .finish()
            .unwrap_err();
        match err {
            PluginError::ValidationErrors(errs) => assert_eq!(errs.len(), 3),
            other => panic!("expected ValidationErrors, got {other:?}"),
        }
    }

    #[test]
    fn valid_input_passes() {
        let input = json!({
            "gtin": "12345678901231",
            "country": "DE",
            "pct": 42.0,
            "count": 3,
            "flag": true,
            "items": [1]
        });
        assert!(
            Validator::new(&input)
                .require_gtin("gtin")
                .require_country("country")
                .require_pct("pct")
                .require_positive_int("count")
                .require_bool("flag")
                .require_non_empty_array("items")
                .finish()
                .is_ok()
        );
    }

    #[test]
    fn enum_and_country_and_pct_bounds() {
        let input = json!({ "cls": "Z", "country": "de", "pct": 150.0 });
        let err = Validator::new(&input)
            .require_enum("cls", &["A", "B"])
            .require_country("country")
            .require_pct("pct")
            .finish()
            .unwrap_err();
        match err {
            PluginError::ValidationErrors(errs) => assert_eq!(errs.len(), 3),
            other => panic!("expected ValidationErrors, got {other:?}"),
        }
    }

    #[test]
    fn gtin_invalid_check_digit_is_rejected() {
        // "12345678901234" — correct digits, correct length, but check digit should be 1, not 4.
        let input = json!({ "gtin": "12345678901234" });
        let err = Validator::new(&input)
            .require_gtin("gtin")
            .finish()
            .unwrap_err();
        match err {
            PluginError::ValidationErrors(errs) => {
                assert_eq!(errs.len(), 1);
                assert_eq!(errs[0].code, "checksum");
            }
            other => panic!("expected ValidationErrors, got {other:?}"),
        }
    }

    #[test]
    fn gtin_valid_check_digit_passes() {
        // "12345678901231" — check digit = 1, matches GS1 calculation.
        let input = json!({ "gtin": "12345678901231" });
        assert!(Validator::new(&input).require_gtin("gtin").finish().is_ok());
    }

    #[test]
    fn country_not_in_iso_list_is_rejected() {
        // "XX" has the right format (2 uppercase letters) but is not an assigned code.
        let input = json!({ "country": "XX" });
        let err = Validator::new(&input)
            .require_country("country")
            .finish()
            .unwrap_err();
        match err {
            PluginError::ValidationErrors(errs) => {
                assert_eq!(errs.len(), 1);
                assert_eq!(errs[0].code, "invalid");
            }
            other => panic!("expected ValidationErrors, got {other:?}"),
        }
    }

    #[test]
    fn country_valid_iso_code_passes() {
        for code in ["DE", "NO", "FR", "US", "JP"] {
            let input = json!({ "country": code });
            assert!(
                Validator::new(&input)
                    .require_country("country")
                    .finish()
                    .is_ok(),
                "{code} should be a valid ISO 3166-1 alpha-2 code"
            );
        }
    }

    #[test]
    fn optional_pct_absent_is_ok_present_out_of_range_fails() {
        let ok = json!({});
        assert!(Validator::new(&ok).optional_pct("x").finish().is_ok());
        let bad = json!({ "x": 101.0 });
        assert!(Validator::new(&bad).optional_pct("x").finish().is_err());
    }

    #[test]
    fn optional_range_absent_ok_present_bounded() {
        // Absent → ok (the field's absence is meaningful).
        assert!(
            Validator::new(&json!({}))
                .optional_range("s", 0.0, 10.0)
                .finish()
                .is_ok()
        );
        // In range → ok.
        assert!(
            Validator::new(&json!({ "s": 6.0 }))
                .optional_range("s", 0.0, 10.0)
                .finish()
                .is_ok()
        );
        // Out of range → err (the fail-open case the plugins guard against).
        for bad in [json!({ "s": 999999.0 }), json!({ "s": -1.0 })] {
            assert!(
                Validator::new(&bad)
                    .optional_range("s", 0.0, 10.0)
                    .finish()
                    .is_err()
            );
        }
    }

    #[test]
    fn optional_non_negative_absent_ok_negative_fails() {
        assert!(
            Validator::new(&json!({}))
                .optional_non_negative("c")
                .finish()
                .is_ok()
        );
        assert!(
            Validator::new(&json!({ "c": 0.0 }))
                .optional_non_negative("c")
                .finish()
                .is_ok()
        );
        assert!(
            Validator::new(&json!({ "c": -999.0 }))
                .optional_non_negative("c")
                .finish()
                .is_err()
        );
    }

    #[test]
    fn readers_extract_values() {
        let input = json!({ "n": 3.5, "s": "hi", "bad": "x" });
        assert_eq!(num(&input, "n"), Some(3.5));
        assert_eq!(num(&input, "bad"), None);
        assert_eq!(str_of(&input, "s"), Some("hi"));
    }
}