openbim_ifc_capi/checks.rs
1//! Validation and the reachability lint, as value tapes (#244).
2//!
3//! Both results are lists of records, so both cross as one tape each. The
4//! C protocol sizes a buffer with a first call, so a size query runs the
5//! check; a host that wants a single run passes buffers it expects to be
6//! large enough and retries only on `BufferTooSmall`.
7
8use openbim_ifc_binding_core::{unreachable, validation};
9
10use crate::buffer::{put, text};
11use crate::model::{done, fill_tape, with_model, OpenbimIfcModel};
12use crate::status::{boundary, OpenbimIfcStatus};
13use crate::tape::{OpenbimIfcValueNode, Tape};
14
15/// Counts from one validation run.
16#[repr(C)]
17#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
18pub struct OpenbimIfcValidationSummary {
19 /// Number of findings on the tape.
20 pub finding_count: usize,
21 /// Schema violations.
22 pub errors: usize,
23 /// Implemented rules that could not be decided for an instance.
24 pub evaluation_errors: usize,
25 /// Legal but suspicious conditions.
26 pub warnings: usize,
27 /// Rules this validator does not evaluate.
28 pub unsupported: usize,
29 /// 1 when there are no errors and no evaluation errors, else 0.
30 pub conformant: u32,
31 /// 1 when the run hit `max_findings`: the counts are lower bounds.
32 pub truncated: u32,
33}
34
35/// Validate against the schema the header declares.
36///
37/// `out_summary` gets the counts, also when the tape does not fit. The tape
38/// is a `LIST` of findings, sorted by severity, rule, entity and slot; each
39/// finding is a `LIST` of seven values: severity (`TEXT`: `error`,
40/// `evaluation-error`, `warning` or `unsupported`; also `indeterminate` from
41/// `openbim_ifc_v0_1_model_validate_express`), rule id (`TEXT`),
42/// entity (`REF`, or `NULL` for the file), attribute index (`INTEGER` or
43/// `NULL`), attribute name (`TEXT` or `NULL`), path (`TEXT`) and message
44/// (`TEXT`). `max_findings` 0 is the validator's default budget (10,000).
45/// `UnsupportedSchema` when the declared schema is not bundled;
46/// `FeatureDisabled` in a build without the `validate` feature.
47///
48/// # Safety
49/// `out_summary` valid for one write; otherwise as for
50/// `openbim_ifc_v0_1_entity_attribute`.
51#[no_mangle]
52pub unsafe extern "C" fn openbim_ifc_v0_1_model_validate(
53 model: OpenbimIfcModel,
54 max_findings: usize,
55 out_summary: *mut OpenbimIfcValidationSummary,
56 nodes: *mut OpenbimIfcValueNode,
57 node_capacity: usize,
58 out_nodes_required: *mut usize,
59 strings: *mut u8,
60 string_capacity: usize,
61 out_strings_required: *mut usize,
62) -> OpenbimIfcStatus {
63 boundary(|| {
64 if out_summary.is_null() {
65 return OpenbimIfcStatus::NullPointer;
66 }
67 with_model(model, |m| {
68 let report = m.validate((max_findings != 0).then_some(max_findings))?;
69 let summary = OpenbimIfcValidationSummary {
70 finding_count: report.findings.len(),
71 errors: report.summary.errors,
72 evaluation_errors: report.summary.evaluation_errors,
73 warnings: report.summary.warnings,
74 unsupported: report.summary.unsupported,
75 conformant: u32::from(report.conformant),
76 truncated: u32::from(report.truncated),
77 };
78 // SAFETY: checked non-null; caller contract above.
79 if let Err(status) = unsafe { put(out_summary, summary) } {
80 return done(status);
81 }
82 let tape = Tape::encode(&validation::findings_to_tagged(&report.findings));
83 // SAFETY: caller contract above.
84 done(unsafe {
85 fill_tape(
86 &tape,
87 nodes,
88 node_capacity,
89 out_nodes_required,
90 strings,
91 string_capacity,
92 out_strings_required,
93 )
94 })
95 })
96 })
97}
98
99/// Counts from one validation run with EXPRESS rules (#538).
100///
101/// A separate record from [`OpenbimIfcValidationSummary`], which the frozen
102/// `v0_1` symbol `openbim_ifc_v0_1_model_validate` keeps: this one adds the
103/// `indeterminate` count.
104#[repr(C)]
105#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
106pub struct OpenbimIfcExpressValidationSummary {
107 /// Number of findings on the tape.
108 pub finding_count: usize,
109 /// Schema violations.
110 pub errors: usize,
111 /// Implemented rules that could not be decided for an instance.
112 pub evaluation_errors: usize,
113 /// Legal but suspicious conditions.
114 pub warnings: usize,
115 /// EXPRESS rules that evaluated to UNKNOWN for an instance.
116 pub indeterminate: usize,
117 /// Rules this validator does not evaluate.
118 pub unsupported: usize,
119 /// 1 when there are no errors and no evaluation errors, else 0.
120 pub conformant: u32,
121 /// 1 when the run hit `max_findings`: the counts are lower bounds.
122 pub truncated: u32,
123}
124
125/// Validate with the EXPRESS rules of the declared release, read from
126/// `express`, the UTF-8 text of that release's `.exp` file (#538).
127///
128/// As `openbim_ifc_v0_1_model_validate` (the same findings tape and
129/// `max_findings` convention), with every WHERE, type and global rule
130/// evaluated and INVERSE cardinality checked; findings of severity
131/// `indeterminate` are rules that evaluated to UNKNOWN. The text is parsed on
132/// every call, so a size query parses and validates. `InvalidArgument` when
133/// `express` is not UTF-8; `ExpressMismatch` when it declares another schema
134/// than the model's or disagrees with the release's tables; `InvalidExpress`
135/// when it does not parse; `UnsupportedSchema` when the declared schema is
136/// not bundled; `FeatureDisabled` in a build without the `validate-express`
137/// feature. The schemas are CC BY-ND, so none is bundled.
138///
139/// # Safety
140/// `express` valid for reads of `express_len` bytes; `out_summary` valid for
141/// one write; otherwise as for `openbim_ifc_v0_1_entity_attribute`.
142#[no_mangle]
143pub unsafe extern "C" fn openbim_ifc_v0_1_model_validate_express(
144 model: OpenbimIfcModel,
145 express: *const u8,
146 express_len: usize,
147 max_findings: usize,
148 out_summary: *mut OpenbimIfcExpressValidationSummary,
149 nodes: *mut OpenbimIfcValueNode,
150 node_capacity: usize,
151 out_nodes_required: *mut usize,
152 strings: *mut u8,
153 string_capacity: usize,
154 out_strings_required: *mut usize,
155) -> OpenbimIfcStatus {
156 boundary(|| {
157 if out_summary.is_null() {
158 return OpenbimIfcStatus::NullPointer;
159 }
160 // SAFETY: caller contract above.
161 let express = match unsafe { text(express, express_len) } {
162 Ok(express) => express,
163 Err(status) => return status,
164 };
165 with_model(model, |m| {
166 let report =
167 m.validate_express(express, (max_findings != 0).then_some(max_findings))?;
168 let summary = OpenbimIfcExpressValidationSummary {
169 finding_count: report.findings.len(),
170 errors: report.summary.errors,
171 evaluation_errors: report.summary.evaluation_errors,
172 warnings: report.summary.warnings,
173 indeterminate: report.summary.indeterminate,
174 unsupported: report.summary.unsupported,
175 conformant: u32::from(report.conformant),
176 truncated: u32::from(report.truncated),
177 };
178 // SAFETY: checked non-null; caller contract above.
179 if let Err(status) = unsafe { put(out_summary, summary) } {
180 return done(status);
181 }
182 let tape = Tape::encode(&validation::findings_to_tagged(&report.findings));
183 // SAFETY: caller contract above.
184 done(unsafe {
185 fill_tape(
186 &tape,
187 nodes,
188 node_capacity,
189 out_nodes_required,
190 strings,
191 string_capacity,
192 out_strings_required,
193 )
194 })
195 })
196 })
197}
198
199/// Products no viewer will draw, in id order, and how many.
200///
201/// The tape is a `LIST` of products; each is a `LIST` of four values: the
202/// product (`REF`), the reason (`TEXT`: `not-contained-in-spatial-structure`,
203/// `no-representation-in-model-context` or `representation-without-context`),
204/// the target views its geometry was found in instead (`LIST` of `TEXT`,
205/// empty unless the reason is the second), and a one-line message (`TEXT`).
206/// `FeatureDisabled` in a build without the `unreachable` feature.
207///
208/// # Safety
209/// `out_count` valid for one write; otherwise as for
210/// `openbim_ifc_v0_1_entity_attribute`.
211#[no_mangle]
212pub unsafe extern "C" fn openbim_ifc_v0_1_model_unreachable_products(
213 model: OpenbimIfcModel,
214 out_count: *mut usize,
215 nodes: *mut OpenbimIfcValueNode,
216 node_capacity: usize,
217 out_nodes_required: *mut usize,
218 strings: *mut u8,
219 string_capacity: usize,
220 out_strings_required: *mut usize,
221) -> OpenbimIfcStatus {
222 boundary(|| {
223 if out_count.is_null() {
224 return OpenbimIfcStatus::NullPointer;
225 }
226 with_model(model, |m| {
227 let products = m.unreachable_products()?;
228 // SAFETY: checked non-null; caller contract above.
229 if let Err(status) = unsafe { put(out_count, products.len()) } {
230 return done(status);
231 }
232 let tape = Tape::encode(&unreachable::products_to_tagged(&products));
233 // SAFETY: caller contract above.
234 done(unsafe {
235 fill_tape(
236 &tape,
237 nodes,
238 node_capacity,
239 out_nodes_required,
240 strings,
241 string_capacity,
242 out_strings_required,
243 )
244 })
245 })
246 })
247}