Skip to main content

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}