automapper_validation/validator/

kind.rs

//! The machine-readable description of what a validation issue *is*.
//!
//! Wording lives in [`crate::display`]. A kind carries every fact the wording
//! needs, so a consumer can say something other than the sentence we ship.

use mig_assembly::StructureDiagnosticKind;
use serde::{Deserialize, Serialize};

use super::issue::ValidationCategory;

/// Why a condition could not be evaluated.
///
/// Any combination of these may be non-empty; each is a list of AHB condition ids.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct UnresolvedConditions {
    /// Need an external provider to answer.
    pub external: Vec<u32>,
    /// Not determinable from the message data.
    pub undetermined: Vec<u32>,
    /// Not present in the rulebook at all.
    pub missing: Vec<u32>,
}

impl UnresolvedConditions {
    /// True when nothing at all could be attributed — the issue has no detail.
    pub fn is_empty(&self) -> bool {
        self.external.is_empty() && self.undetermined.is_empty() && self.missing.is_empty()
    }
}

/// What kind of problem a [`ValidationIssue`](super::issue::ValidationIssue) reports.
///
/// One variant per problem the validator actually emits. `ErrorCodes` lists 22
/// code strings, but only these are ever constructed; adding a new check means
/// adding a variant, which the compiler then forces every narrator to handle.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "type", rename_all = "camelCase")]
pub enum IssueKind {
    /// AHB001 — a field the AHB marks mandatory for this PID is absent.
    MissingRequiredField { field_name: String },
    /// AHB002 — a segment group is present although its AHB condition does not
    /// hold (`Muss [96]` without STS+7 ZAP). `group` is its path (`SG4/SG5`);
    /// `failed` are the conditions that make it false, as for
    /// [`FieldConditionNotSatisfied`](Self::FieldConditionNotSatisfied).
    GroupNotAllowed {
        group: String,
        #[serde(default, skip_serializing_if = "Vec::is_empty")]
        failed: Vec<u32>,
    },
    /// AHB002 — a segment is present although its own AHB condition does not
    /// hold (`CAV+Z56` Wärmenutzung, `Muss [239]`, without CAV+Z65 in its
    /// SG10). `segment` is its path (`SG4/SG8/SG10/CAV`); `failed` as for
    /// [`GroupNotAllowed`](Self::GroupNotAllowed).
    SegmentNotAllowed {
        segment: String,
        #[serde(default, skip_serializing_if = "Vec::is_empty")]
        failed: Vec<u32>,
    },
    /// AHB003 — the field is present but its AHB condition is not satisfied.
    /// `failed` are the conditions that make it false (see
    /// `ConditionExprEvaluator::false_ids_with_ub`): what kind of error it is
    /// depends on them.
    FieldConditionNotSatisfied {
        field_name: String,
        #[serde(default, skip_serializing_if = "Vec::is_empty")]
        failed: Vec<u32>,
    },
    /// AHB005 — the condition expression could not be fully evaluated.
    ConditionUnknown {
        field_name: String,
        unresolved: UnresolvedConditions,
    },
    /// AHB006 — number of codes present in a package is outside `min..max`.
    PackageCardinality {
        package_id: String,
        present: usize,
        min: usize,
        max: usize,
        codes: Vec<String>,
    },
    /// AHB007 — a group or segment the AHB allows once per transaction
    /// (`[2061]` "genau einmal je SG4 IDE (Vorgang)") is sent `count` times in
    /// one. `path` is the group or segment (`SG4/SG8`, `SG4/STS`).
    RepeatedInTransaction { path: String, count: usize },
    /// AHB008 — a group or segment sent another number of times in its group
    /// than a repetition condition allows there: too often (ORDERS `[2005]`
    /// "Pro SG29 LIN ist die SG34 RFF+Z09 (Gerätenummer) genau einmal
    /// anzugeben") or too rarely (UTILMD `[2317]` "mindestens zweimal").
    /// `path` is the group or segment (`SG29/SG34`), `count` how often the
    /// group instance holds it.
    RepetitionCount { path: String, count: usize },
    /// AHB009 — two parts the AHB makes alternatives are both sent: each is
    /// `Muss` only where the other is absent
    /// ([`exclusive_conditions`](crate::eval::exclusive_conditions)), UTILMD
    /// Strom's PIA+5 (`[81]`) beside the SG10 CCI+11 "Kein Produkt
    /// zugeordnet" (`[80]`). `first` and `second` are the two (`SG4/SG8/PIA`,
    /// `SG4/SG8/SG10`), `conditions` the pair that fails. Unlike content that
    /// is merely superfluous (AHB002), neither can be ignored.
    ExclusiveAlternatives {
        first: String,
        second: String,
        conditions: Vec<u32>,
    },
    /// COD002 — the value is a valid code but not allowed for this PID.
    CodeNotAllowedForPid { value: String, allowed: Vec<String> },
    /// COD003 — a response's answer (AJT 4465, STS C556/9013) is not one of the
    /// codes of the EBD or Codeliste it names beside it (AJT 1082, C556/1131):
    /// `AJT+ZB5+G_0059`. The AHB lists which lists may be named; the EBD
    /// document says what they hold.
    AnswerNotInList {
        answer: String,
        list: String,
        allowed: Vec<String>,
    },
    /// FMT001 — the value is longer than its MIG format allows (`an..512`).
    ValueTooLong {
        field_name: String,
        length: usize,
        max: usize,
    },
    /// FMT002 — a data element of numeric format (`n..10`) holds something
    /// that is not a number (`O5D2DXBG1A`).
    ValueNotNumeric { field_name: String },
    /// FMT004 — a DTM value (C507 DE2380) that does not have the shape of the
    /// format code beside it (DE2379): `DTM+752:20250401:104`, where 104
    /// `MMWW-MMWW` asks for two month-and-week pairs. `format` is the code.
    DateNotInFormat { field_name: String, format: String },
    /// CON001 — a period ends before it begins, or as it begins where it may
    /// not be empty: `DTM+164` not after the `DTM+163` beside it (APERAK Z34
    /// "Zeitintervall negativ oder Null"). `begin` and `end` are the two DTMs
    /// (`DTM+163`); see [`crate::consistency`].
    IntervalNotPositive { begin: String, end: String },
    /// CON002 — a reference within a transaction names nothing in it: an
    /// SG8 `RFF+Z19` (Messlokation) naming none of the transaction's
    /// `LOC+Z17` (APERAK Z21 "Geschäftsvorfallinterne Referenzierung
    /// fehlerhaft"). `reference` is the RFF (`RFF+Z19`), `value` the id it
    /// names, `targets` what it may name (`LOC+Z17`); see
    /// [`crate::consistency`].
    ReferenceNotFound {
        reference: String,
        value: String,
        targets: Vec<String>,
    },
    /// STR007 — UNT's declared segment count disagrees with the actual count.
    UntSegmentCountMismatch { declared: usize, actual: usize },
    /// STR007 — the input holds several messages, so the count is not checkable.
    UntCountNotVerifiable { unh_count: usize },
    /// MAP001 — a field of the BO4E input that the EDIFACT rendered from it
    /// does not carry: no mapping rule of the PID writes it (issue #446).
    /// Only BO4E validation raises it; `path` is the field's place in the
    /// input (`stammdaten.marktteilnehmer[0].ansprechpartner`).
    Bo4eFieldDropped { path: String },
    /// STR003 / STR008 — a structure diagnostic raised during assembly.
    ///
    /// `detail` carries the diagnostic's own message verbatim: some
    /// diagnostics (e.g. `mig_assembly::Assembler::assemble_with_diagnostics`'s
    /// `"Assembly failed: {e}"` case) say something not derivable from
    /// `(kind, segment_id, position)` alone.
    StructureDiagnostic {
        kind: StructureDiagnosticKind,
        segment_id: String,
        position: usize,
        detail: String,
    },
}

impl IssueKind {
    /// The stable machine identifier, unchanged from the former `code` field.
    pub fn code(&self) -> &'static str {
        match self {
            Self::MissingRequiredField { .. } => "AHB001",
            Self::GroupNotAllowed { .. } | Self::SegmentNotAllowed { .. } => "AHB002",
            Self::FieldConditionNotSatisfied { .. } => "AHB003",
            Self::ConditionUnknown { .. } => "AHB005",
            Self::PackageCardinality { .. } => "AHB006",
            Self::RepeatedInTransaction { .. } => "AHB007",
            Self::RepetitionCount { .. } => "AHB008",
            Self::ExclusiveAlternatives { .. } => "AHB009",
            Self::CodeNotAllowedForPid { .. } => "COD002",
            Self::AnswerNotInList { .. } => "COD003",
            Self::ValueTooLong { .. } => "FMT001",
            Self::ValueNotNumeric { .. } => "FMT002",
            Self::DateNotInFormat { .. } => "FMT004",
            Self::IntervalNotPositive { .. } => "CON001",
            Self::ReferenceNotFound { .. } => "CON002",
            Self::UntSegmentCountMismatch { .. } | Self::UntCountNotVerifiable { .. } => "STR007",
            Self::Bo4eFieldDropped { .. } => "MAP001",
            // One code per kind (#81). An orphaned group segment is a skipped
            // segment too (its content is equally absent); the kind and
            // message tell the missing entry segment apart. A segment whose
            // qualifier no slot at its place accepts is unexpected there.
            Self::StructureDiagnostic { kind, .. } => match kind {
                StructureDiagnosticKind::MissingRequiredSegment => "STR001",
                StructureDiagnosticKind::MaxRepetitionsExceeded => "STR002",
                StructureDiagnosticKind::UnexpectedSegment
                | StructureDiagnosticKind::UnrecognizedQualifier => "STR003",
                StructureDiagnosticKind::MissingRequiredGroup => "STR005",
                StructureDiagnosticKind::GroupMaxRepetitionsExceeded => "STR006",
                StructureDiagnosticKind::SkippedUnknownSegment
                | StructureDiagnosticKind::OrphanedGroupSegment => "STR008",
            },
        }
    }

    /// The issue's category. Derived, so it can never disagree with the kind.
    pub fn category(&self) -> ValidationCategory {
        match self {
            Self::MissingRequiredField { .. }
            | Self::GroupNotAllowed { .. }
            | Self::SegmentNotAllowed { .. }
            | Self::FieldConditionNotSatisfied { .. }
            | Self::ConditionUnknown { .. }
            | Self::PackageCardinality { .. }
            | Self::RepeatedInTransaction { .. }
            | Self::RepetitionCount { .. }
            | Self::ExclusiveAlternatives { .. }
            | Self::IntervalNotPositive { .. }
            | Self::ReferenceNotFound { .. } => ValidationCategory::Ahb,
            Self::CodeNotAllowedForPid { .. } | Self::AnswerNotInList { .. } => {
                ValidationCategory::Code
            }
            Self::UntSegmentCountMismatch { .. }
            | Self::UntCountNotVerifiable { .. }
            | Self::Bo4eFieldDropped { .. }
            | Self::StructureDiagnostic { .. } => ValidationCategory::Structure,
            Self::ValueTooLong { .. }
            | Self::ValueNotNumeric { .. }
            | Self::DateNotInFormat { .. } => ValidationCategory::Format,
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use mig_assembly::StructureDiagnosticKind;

    #[test]
    fn code_matches_the_legacy_error_code_for_every_kind() {
        let cases: Vec<(IssueKind, &str)> = vec![
            (
                IssueKind::MissingRequiredField {
                    field_name: "f".into(),
                },
                "AHB001",
            ),
            (
                IssueKind::GroupNotAllowed {
                    group: "SG4/SG5".into(),
                    failed: Vec::new(),
                },
                "AHB002",
            ),
            (
                IssueKind::SegmentNotAllowed {
                    segment: "SG4/SG8/SG10/CAV".into(),
                    failed: Vec::new(),
                },
                "AHB002",
            ),
            (
                IssueKind::FieldConditionNotSatisfied {
                    field_name: "f".into(),
                    failed: vec![],
                },
                "AHB003",
            ),
            (
                IssueKind::ConditionUnknown {
                    field_name: "f".into(),
                    unresolved: UnresolvedConditions::default(),
                },
                "AHB005",
            ),
            (
                IssueKind::PackageCardinality {
                    package_id: "1P0..1".into(),
                    present: 2,
                    min: 0,
                    max: 1,
                    codes: vec![],
                },
                "AHB006",
            ),
            (
                IssueKind::RepetitionCount {
                    path: "SG29/SG34".into(),
                    count: 2,
                },
                "AHB008",
            ),
            (
                IssueKind::ExclusiveAlternatives {
                    first: "SG4/SG8/PIA".into(),
                    second: "SG4/SG8/SG10".into(),
                    conditions: vec![80, 81],
                },
                "AHB009",
            ),
            (
                IssueKind::CodeNotAllowedForPid {
                    value: "X".into(),
                    allowed: vec![],
                },
                "COD002",
            ),
            (
                IssueKind::AnswerNotInList {
                    answer: "ZB5".into(),
                    list: "G_0059".into(),
                    allowed: vec![],
                },
                "COD003",
            ),
            (
                IssueKind::ValueTooLong {
                    field_name: "f".into(),
                    length: 600,
                    max: 512,
                },
                "FMT001",
            ),
            (
                IssueKind::UntSegmentCountMismatch {
                    declared: 30,
                    actual: 31,
                },
                "STR007",
            ),
            (IssueKind::UntCountNotVerifiable { unh_count: 2 }, "STR007"),
            (
                IssueKind::Bo4eFieldDropped {
                    path: "stammdaten.x".into(),
                },
                "MAP001",
            ),
            (
                IssueKind::StructureDiagnostic {
                    kind: StructureDiagnosticKind::SkippedUnknownSegment,
                    segment_id: "CCI".into(),
                    position: 15,
                    detail: "irrelevant to the code".into(),
                },
                "STR008",
            ),
            (
                IssueKind::StructureDiagnostic {
                    kind: StructureDiagnosticKind::UnexpectedSegment,
                    segment_id: "CCI".into(),
                    position: 15,
                    detail: "irrelevant to the code".into(),
                },
                "STR003",
            ),
        ];
        for (kind, expected) in cases {
            assert_eq!(kind.code(), expected, "wrong code for {kind:?}");
        }
    }

    /// Every structure diagnostic keeps its own code (#81): a repetition
    /// overrun must not surface as "unexpected segment".
    #[test]
    fn each_structure_kind_has_its_own_code() {
        use StructureDiagnosticKind as K;
        for (kind, expected) in [
            (K::MissingRequiredSegment, "STR001"),
            (K::MaxRepetitionsExceeded, "STR002"),
            (K::UnexpectedSegment, "STR003"),
            (K::UnrecognizedQualifier, "STR003"),
            (K::MissingRequiredGroup, "STR005"),
            (K::GroupMaxRepetitionsExceeded, "STR006"),
            (K::SkippedUnknownSegment, "STR008"),
            (K::OrphanedGroupSegment, "STR008"),
        ] {
            let issue = IssueKind::StructureDiagnostic {
                kind,
                segment_id: "RFF".into(),
                position: 1,
                detail: String::new(),
            };
            assert_eq!(issue.code(), expected, "{kind:?}");
        }
    }

    #[test]
    fn category_is_derived_from_the_kind() {
        assert_eq!(
            IssueKind::MissingRequiredField {
                field_name: "f".into()
            }
            .category(),
            ValidationCategory::Ahb
        );
        assert_eq!(
            IssueKind::CodeNotAllowedForPid {
                value: "X".into(),
                allowed: vec![]
            }
            .category(),
            ValidationCategory::Code
        );
        assert_eq!(
            IssueKind::UntSegmentCountMismatch {
                declared: 1,
                actual: 2
            }
            .category(),
            ValidationCategory::Structure
        );
    }
}