Skip to main content

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}