ifc_validate/report/detail.rs
1//! Typed detail behind a finding's message.
2//!
3//! The message is for people; this is for programs. A caller that wants to
4//! group EXPRESS rule results by declaration, tell an indeterminate result
5//! from a violation, or list the rules a budget stopped, matches on these
6//! instead of parsing text.
7
8/// Structured detail of a finding, when its check provides one.
9#[derive(Debug, Clone, PartialEq, Eq)]
10#[non_exhaustive]
11pub enum FindingDetail {
12 /// An EXPRESS WHERE rule, global rule or type rule evaluated from the
13 /// schema's own text.
14 Rule(RuleDetail),
15 /// A property or quantity set whose name uses a prefix buildingSMART
16 /// reserves, but which the release's catalog does not define.
17 ReservedSetName(ReservedSetName),
18 /// A property or quantity of a catalog set that the release's catalog
19 /// does not declare, or declares differently (`property.undeclared_member`,
20 /// `property.member_type`, #537).
21 CatalogMember(CatalogMemberDetail),
22 /// The file declares a release known by name whose normative EXPRESS
23 /// is not published (`header.schema.unpublished`, #467): the report
24 /// was not made against that release's own tables.
25 UnpublishedSchema(ifc_schema::UnpublishedRelease),
26}
27
28/// One EXPRESS rule result.
29#[derive(Debug, Clone, PartialEq, Eq)]
30#[non_exhaustive]
31pub struct RuleDetail {
32 /// The schema the rule text came from, as its `SCHEMA` line names it
33 /// (`IFC4`, `IFC4X3_ADD2`).
34 pub release: String,
35 /// The declaration the rule belongs to.
36 pub scope: RuleScope,
37 /// The rule's label as the schema writes it (`WR11`,
38 /// `CorrectItemsForType`).
39 pub label: String,
40 /// What evaluation concluded.
41 pub outcome: RuleOutcome,
42}
43
44/// The declaration holding a rule.
45#[derive(Debug, Clone, PartialEq, Eq)]
46#[non_exhaustive]
47pub enum RuleScope {
48 /// A WHERE rule of an entity, binding it and every subtype.
49 Entity {
50 /// The entity declaring the rule.
51 declared_on: String,
52 },
53 /// A WHERE rule of a defined type, binding every value of it.
54 Type {
55 /// The type declaring the rule.
56 type_name: String,
57 },
58 /// A global `RULE`.
59 Global {
60 /// The rule's name.
61 rule: String,
62 },
63}
64
65/// What evaluating a rule on one instance, value or file concluded.
66///
67/// A satisfied rule produces no finding, so there is no variant for it.
68#[derive(Debug, Clone, PartialEq, Eq)]
69#[non_exhaustive]
70pub enum RuleOutcome {
71 /// The rule evaluated to FALSE.
72 Violated,
73 /// The rule evaluated to UNKNOWN or indeterminate (`?`). ISO 10303-11
74 /// does not count that as a violation; it is reported so a reader knows
75 /// the data could not decide the rule.
76 Indeterminate,
77 /// The rule could not be evaluated.
78 NotEvaluated(NotEvaluated),
79}
80
81/// Why a rule was not evaluated.
82#[derive(Debug, Clone, PartialEq, Eq)]
83#[non_exhaustive]
84pub enum NotEvaluated {
85 /// The rule needs something this evaluator does not implement; the
86 /// construct or function is named.
87 Unsupported {
88 /// What is missing, e.g. `FORMAT` or `assignment to a file
89 /// instance's attribute`.
90 construct: String,
91 },
92 /// A limit stopped evaluation.
93 BudgetExceeded(BudgetExceeded),
94 /// The file's data has a shape the rule cannot read, e.g. a string
95 /// where the rule compares numbers.
96 InvalidData {
97 /// What was found.
98 detail: String,
99 },
100}
101
102/// Which limit stopped an evaluation.
103#[derive(Debug, Clone, Copy, PartialEq, Eq)]
104#[non_exhaustive]
105pub enum BudgetExceeded {
106 /// One rule on one instance took more steps than allowed.
107 Steps {
108 /// The limit.
109 limit: u64,
110 },
111 /// Function calls and derived attributes nested deeper than allowed.
112 Depth {
113 /// The limit.
114 limit: usize,
115 },
116 /// The whole run took more steps than allowed; the remaining rules
117 /// were not evaluated.
118 Total {
119 /// The limit.
120 limit: u64,
121 },
122}
123
124/// A set name using a reserved prefix the catalog does not define.
125#[derive(Debug, Clone, PartialEq, Eq)]
126#[non_exhaustive]
127pub struct ReservedSetName {
128 /// The set's `Name`.
129 pub name: String,
130 /// The reserved prefix it uses, `Pset_` or `Qto_`.
131 pub prefix: String,
132 /// The release whose catalog was consulted.
133 pub release: String,
134}
135
136/// A member of a catalog set that disagrees with the catalog's template.
137#[derive(Debug, Clone, PartialEq, Eq)]
138#[non_exhaustive]
139pub struct CatalogMemberDetail {
140 /// The set's `Name`.
141 pub set: String,
142 /// The member's dotted path inside the set (`Outer.Inner` for a
143 /// property nested in a complex property); `None` when the set itself
144 /// is at fault.
145 pub member: Option<String>,
146 /// The release whose catalog was consulted.
147 pub release: String,
148 /// How it disagrees.
149 pub mismatch: CatalogMismatch,
150}
151
152/// How a set or member disagrees with its catalog template.
153///
154/// Names are in the schema's spelling (`IfcLabel`), never the upper-cased
155/// token a file writes.
156#[derive(Debug, Clone, PartialEq, Eq)]
157#[non_exhaustive]
158pub enum CatalogMismatch {
159 /// The catalog declares no member of that name.
160 UndeclaredMember,
161 /// The set is an `IfcPropertySet` where the catalog declares a quantity
162 /// set, or the reverse.
163 SetKind {
164 /// The entity the catalog declares.
165 declared: String,
166 /// The entity the file uses.
167 found: String,
168 },
169 /// The member is written as another entity than the catalog declares.
170 Form {
171 /// The entity the catalog declares.
172 declared: String,
173 /// The entity the file uses.
174 found: String,
175 },
176 /// A value has another type than the catalog declares.
177 DataType {
178 /// The type (or, for a reference, entity) the catalog declares.
179 declared: String,
180 /// The type the file uses.
181 found: String,
182 },
183}
184
185impl std::fmt::Display for BudgetExceeded {
186 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
187 match self {
188 Self::Steps { limit } => write!(f, "more than {limit} evaluation steps"),
189 Self::Depth { limit } => write!(f, "calls nested deeper than {limit}"),
190 Self::Total { limit } => write!(f, "the run's {limit} evaluation steps were spent"),
191 }
192 }
193}
194
195impl std::fmt::Display for NotEvaluated {
196 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
197 match self {
198 Self::Unsupported { construct } => {
199 write!(
200 f,
201 "needs {construct}, which this evaluator does not implement"
202 )
203 }
204 Self::BudgetExceeded(budget) => write!(f, "stopped after {budget}"),
205 Self::InvalidData { detail } => write!(f, "cannot read the data: {detail}"),
206 }
207 }
208}