Skip to main content

ifc_template_catalog/compliance/
contract.rs

1use crate::definition::QuantityKind;
2
3/// Value form of one observed member, mirrors [`crate::definition::PropertyKind`]
4/// or a quantity value.
5#[derive(Debug, Clone, Copy, PartialEq, Eq)]
6#[non_exhaustive]
7pub enum MemberForm {
8    /// Matches [`crate::definition::PropertyKind::SingleValue`].
9    SingleValue,
10    /// Matches [`crate::definition::PropertyKind::BoundedValue`].
11    BoundedValue,
12    /// Matches [`crate::definition::PropertyKind::EnumeratedValue`].
13    EnumeratedValue,
14    /// Matches [`crate::definition::PropertyKind::ListValue`].
15    ListValue,
16    /// Matches [`crate::definition::PropertyKind::ReferenceValue`].
17    ReferenceValue,
18    /// Matches [`crate::definition::PropertyKind::TableValue`].
19    TableValue,
20    /// Matches [`crate::definition::PropertyKind::Complex`].
21    Complex,
22    /// A quantity member of the given physical family.
23    Quantity(QuantityKind),
24}
25
26/// One authored property or quantity as observed in a caller's own model,
27/// used as validation input against a [`crate::definition::SetTemplate`].
28#[derive(Debug, Clone, PartialEq, Eq)]
29pub struct ObservedMember {
30    /// Dotted path matching [`super::apply_template`]'s `path` argument for
31    /// nested `Complex` properties, or the bare name at the top level.
32    pub name: String,
33    /// Observed value form.
34    pub form: MemberForm,
35    /// Observed IFC type metadata. An empty vector means "not observed";
36    /// validation then skips type conformance rather than proving it.
37    pub data_types: Vec<String>,
38    /// Observed enumeration value, if `form` is `EnumeratedValue` and one was read.
39    pub enumeration_value: Option<String>,
40}
41
42impl ObservedMember {
43    /// Start an observed property member with no data types or enumeration value set.
44    pub fn property(name: impl Into<String>, form: MemberForm) -> Self {
45        Self {
46            name: name.into(),
47            form,
48            data_types: Vec::new(),
49            enumeration_value: None,
50        }
51    }
52    /// Start an observed quantity member of the given physical family.
53    pub fn quantity(name: impl Into<String>, kind: QuantityKind) -> Self {
54        Self::property(name, MemberForm::Quantity(kind))
55    }
56    /// Record one observed IFC type name for this member.
57    pub fn with_data_type(mut self, type_name: impl Into<String>) -> Self {
58        self.data_types.push(type_name.into());
59        self
60    }
61    /// Record the observed enumeration value for this member.
62    pub fn with_enumeration_value(mut self, value: impl Into<String>) -> Self {
63        self.enumeration_value = Some(value.into());
64        self
65    }
66}
67
68/// One authored property or quantity set as observed in a caller's own
69/// model, the [`validate`](super::validate) input paired with a template.
70#[derive(Debug, Clone, PartialEq, Eq)]
71pub struct ObservedSet {
72    /// Observed set name, compared against the template's `name`.
73    pub name: String,
74    /// Observed members, in the order they were added.
75    pub members: Vec<ObservedMember>,
76}
77impl ObservedSet {
78    /// Start an observed set with no members.
79    pub fn new(name: impl Into<String>) -> Self {
80        Self {
81            name: name.into(),
82            members: Vec::new(),
83        }
84    }
85    /// Append one observed member.
86    pub fn with_member(mut self, member: ObservedMember) -> Self {
87        self.members.push(member);
88        self
89    }
90}
91
92/// How [`validate`](super::validate) treats an observed member that the
93/// template does not declare.
94#[derive(Debug, Clone, Copy, PartialEq, Eq)]
95#[non_exhaustive]
96pub enum UnexpectedMemberPolicy {
97    /// Silently accept the extra member; no issue is reported.
98    Ignore,
99    /// Report the extra member as a [`ValidationSeverity::Warning`].
100    Warning,
101    /// Report the extra member as a [`ValidationSeverity::Error`].
102    Error,
103}
104/// Validation rules applied by [`validate`](super::validate).
105#[derive(Debug, Clone, Copy, PartialEq, Eq)]
106pub struct ValidationPolicy {
107    /// When true, every template-declared member must appear in the
108    /// observed set or a [`ValidationCode::MissingMember`] error is reported.
109    pub require_all_members: bool,
110    /// How to treat an observed member the template does not declare.
111    pub unexpected_members: UnexpectedMemberPolicy,
112}
113impl Default for ValidationPolicy {
114    fn default() -> Self {
115        Self {
116            require_all_members: false,
117            unexpected_members: UnexpectedMemberPolicy::Warning,
118        }
119    }
120}
121
122/// Severity of one [`ValidationIssue`].
123#[derive(Debug, Clone, Copy, PartialEq, Eq)]
124#[non_exhaustive]
125pub enum ValidationSeverity {
126    /// Notable but does not make [`ValidationReport::is_valid`] return false.
127    Warning,
128    /// Makes [`ValidationReport::is_valid`] return false.
129    Error,
130}
131/// Category of one [`ValidationIssue`], identifying which check produced it.
132#[derive(Debug, Clone, Copy, PartialEq, Eq)]
133#[non_exhaustive]
134pub enum ValidationCode {
135    /// The observed set's `name` does not match the template's `name`.
136    SetNameMismatch,
137    /// The same member name appeared more than once in the observed set.
138    DuplicateMember,
139    /// An observed member is not declared by the template; see [`UnexpectedMemberPolicy`].
140    UnexpectedMember,
141    /// A template-declared member is absent from the observed set, under
142    /// [`ValidationPolicy::require_all_members`].
143    MissingMember,
144    /// The observed member's [`MemberForm`] does not match the template's.
145    FormMismatch,
146    /// The observed member's data type(s) do not match the template's.
147    DataTypeMismatch,
148    /// The observed enumeration value is not among the template's declared values.
149    InvalidEnumerationValue,
150}
151/// One deviation found while validating an [`ObservedSet`] against a template.
152#[derive(Debug, Clone, PartialEq, Eq)]
153#[non_exhaustive]
154pub struct ValidationIssue {
155    /// Which check produced this issue.
156    pub code: ValidationCode,
157    /// Whether this issue counts against [`ValidationReport::is_valid`].
158    pub severity: ValidationSeverity,
159    /// Member path the issue concerns, `None` for set-level issues.
160    pub member: Option<String>,
161    /// Human-readable description of the deviation.
162    pub message: String,
163}
164/// Every deviation found by one [`validate`](super::validate) call.
165#[derive(Debug, Clone, PartialEq, Eq, Default)]
166#[non_exhaustive]
167pub struct ValidationReport {
168    /// Issues found, in the order they were detected.
169    pub issues: Vec<ValidationIssue>,
170}
171impl ValidationReport {
172    /// Returns true when validation found no errors in the metadata the caller supplied.
173    /// Missing observed type metadata is unresolved, not proof of type conformance.
174    pub fn is_valid(&self) -> bool {
175        !self
176            .issues
177            .iter()
178            .any(|issue| issue.severity == ValidationSeverity::Error)
179    }
180}