Skip to main content

powerio_capi/
diagnostics.rs

1//! The codes the language boundary itself emits, and the workspace gates.
2//!
3//! `BIND` is the one namespace with no Rust error type behind it: these are the
4//! failures a C entry point detects from an argument's representation alone —
5//! a null pointer, bytes that are not UTF-8, a caught panic. A failure that
6//! needs powerio's own vocabulary to detect (an unknown format name, an index
7//! the handle does not have) belongs to `REQUEST` and comes from the crate that
8//! owns the vocabulary.
9
10pub use powerio_core::{
11    Diagnostic, DiagnosticInfo, DiagnosticSeverity, check_registry, check_scope_ownership,
12};
13
14pub mod codes {
15    powerio_core::diagnostic_codes! {
16        BIND_CAPI_NULL_HANDLE = "BIND.CAPI.NULL_HANDLE", Error,
17            "a handle argument was NULL", category = Data;
18        BIND_CAPI_NULL_ARGUMENT = "BIND.CAPI.NULL_ARGUMENT", Error,
19            "a required non-handle argument was NULL", category = Data;
20        BIND_CAPI_INVALID_UTF8 = "BIND.CAPI.INVALID_UTF8", Error,
21            "a string argument is not valid UTF-8", category = Data;
22        BIND_CAPI_INDEX_OUT_OF_RANGE = "BIND.CAPI.INDEX_OUT_OF_RANGE", Error,
23            "an index argument cannot be converted or is out of range", category = Data;
24        BIND_CAPI_PANIC = "BIND.CAPI.PANIC", Error,
25            "a panic was caught at the boundary and did not cross it", category = Data;
26        BIND_CAPI_INVALID_OPTIONS = "BIND.CAPI.INVALID_OPTIONS", Error,
27            "an options struct declared a size or a field value this build cannot honor",
28            category = Data;
29        BIND_CAPI_INVALID_ARGUMENT = "BIND.CAPI.INVALID_ARGUMENT", Error,
30            "a non-handle argument holds a value outside its domain", category = Data;
31        EMIT_CAPI_SERIALIZE_FAILED = "EMIT.CAPI.SERIALIZE_FAILED", Error,
32            "a document or table an entry point returns could not be built or serialized",
33            category = Output;
34        BIND_CAPI_UNCODED_FAILURE = "BIND.CAPI.UNCODED_FAILURE", Error,
35            "a library failure reached the boundary carrying no finding of its own",
36            category = Data;
37        REQUEST_CAPI_UNKNOWN_FORMULA = "REQUEST.CAPI.UNKNOWN_FORMULA", Error,
38            "the caller named a branch susceptance formula this surface does not have",
39            category = Request;
40        REQUEST_CAPI_TYPE_MISMATCH = "REQUEST.CAPI.TYPE_MISMATCH", Error,
41            "the value does not have the structural type required by the operation",
42            category = Request;
43        REQUEST_CAPI_QUANTITY_UNKNOWN = "REQUEST.CAPI.QUANTITY_UNKNOWN", Error,
44            "the requested operating point quantity is not defined",
45            category = Request;
46        REQUEST_CAPI_ALLOCATION_UNKNOWN = "REQUEST.CAPI.ALLOCATION_UNKNOWN", Error,
47            "the requested load allocation rule is not defined",
48            category = Request;
49    }
50}
51
52/// Every code this crate declares.
53#[must_use]
54pub fn registry() -> Vec<&'static DiagnosticInfo> {
55    codes::ALL.to_vec()
56}
57
58// The workspace gate. This crate is the only one that depends on all five
59// library crates at once, and the release features CI job builds it with every
60// feature on, so it is the one place a code shared by two crates shows up.
61#[cfg(all(test, feature = "dist", feature = "prob", feature = "matrix"))]
62mod workspace {
63    use super::*;
64
65    fn registries() -> Vec<(&'static str, Vec<&'static DiagnosticInfo>)> {
66        vec![
67            ("powerio-tx", powerio_tx::diagnostics::registry()),
68            ("powerio (stored + transform)", powerio::codes::registry()),
69            #[cfg(feature = "gridfm")]
70            (
71                "powerio (gridfm reader)",
72                powerio::gridfm_codes::ALL.to_vec(),
73            ),
74            ("powerio-dist", powerio_dist::diagnostics::registry()),
75            ("powerio-matrix", powerio_matrix::diagnostics::registry()),
76            ("powerio-prob", powerio_prob::diagnostics::registry()),
77            ("powerio-capi", registry()),
78        ]
79    }
80
81    #[test]
82    fn every_code_in_the_workspace_is_registered_once_and_well_formed() {
83        let all: Vec<&DiagnosticInfo> = registries()
84            .into_iter()
85            .flat_map(|(_, entries)| entries)
86            .collect();
87        let problems = check_registry(all.iter().copied());
88        assert!(problems.is_empty(), "{problems:#?}");
89    }
90
91    #[test]
92    fn no_two_crates_claim_one_scope() {
93        let owned = registries();
94        let borrowed: Vec<(&str, &[&DiagnosticInfo])> = owned
95            .iter()
96            .map(|(name, entries)| (*name, entries.as_slice()))
97            .collect();
98        let problems = check_scope_ownership(&borrowed);
99        assert!(problems.is_empty(), "{problems:#?}");
100    }
101
102    /// Any stable code string the ABI implementation spells inline resolves to
103    /// a registered entry in some workspace registry, so a bare unregistered
104    /// literal cannot reach a `PioError`. The module's own test block may
105    /// fabricate codes and is excluded. No inline strings is also valid: ABI
106    /// code should normally refer to registry entries directly.
107    #[test]
108    fn every_code_string_the_abi_emits_is_registered() {
109        let source = include_str!("lib.rs")
110            .split("#[cfg(test)]")
111            .next()
112            .expect("split yields the leading source");
113        let registered: std::collections::BTreeSet<&str> = registries()
114            .into_iter()
115            .flat_map(|(_, entries)| entries)
116            .map(|entry| entry.code)
117            .collect();
118        for piece in source.split('"').skip(1).step_by(2) {
119            let dotted = piece.split('.').count() >= 3
120                && piece.split('.').all(|segment| {
121                    !segment.is_empty()
122                        && segment.bytes().all(|byte| {
123                            byte.is_ascii_uppercase() || byte.is_ascii_digit() || byte == b'_'
124                        })
125                });
126            if dotted {
127                assert!(registered.contains(piece), "`{piece}` is not registered");
128            }
129        }
130    }
131}