Skip to main content

runic_diagnostics/
registry.rs

1#[cfg(any(test, feature = "linked-registry"))]
2use core::cmp::Ordering;
3use core::{error::Error, fmt};
4
5use crate::{DescriptorOrigin, DiagnosticCode, DiagnosticDescriptor};
6
7/// A deterministic view over explicitly composed diagnostic catalogs.
8///
9/// Explicit composition is the portable registry mechanism. Iteration
10/// preserves catalog order and descriptor order within each catalog.
11#[derive(Clone, Copy, Debug)]
12pub struct StaticRegistry<'a> {
13    catalogs: &'a [&'a [&'static DiagnosticDescriptor]],
14}
15
16impl<'a> StaticRegistry<'a> {
17    /// Compose a registry from explicit descriptor catalogs.
18    pub const fn from_slices(
19        catalogs: &'a [&'a [&'static DiagnosticDescriptor]],
20    ) -> StaticRegistry<'a> {
21        Self { catalogs }
22    }
23
24    /// Iterate over descriptors in explicit catalog order.
25    pub fn iter(&self) -> impl Iterator<Item = &'static DiagnosticDescriptor> + '_ {
26        self.catalogs.iter().flat_map(|catalog| catalog.iter().copied())
27    }
28
29    /// Validate that every canonical code occurs exactly once.
30    ///
31    /// Duplicate descriptor pointers are rejected just like distinct
32    /// descriptors with the same code.
33    pub fn validate(&self) -> Result<(), RegistryError> {
34        for (index, first) in self.iter().enumerate() {
35            for second in self.iter().skip(index + 1) {
36                if first.code == second.code {
37                    return Err(RegistryError::DuplicateCode {
38                        code: first.code,
39                        first_origin: first.origin,
40                        second_origin: second.origin,
41                    });
42                }
43            }
44        }
45        Ok(())
46    }
47
48    /// Look up a canonical code or a unique unqualified code.
49    ///
50    /// A string containing `/` is treated as canonical. An unqualified code
51    /// succeeds only when it is unique across the complete registry.
52    pub fn lookup(&self, code: &str) -> Result<&'static DiagnosticDescriptor, LookupError> {
53        self.validate().map_err(LookupError::InvalidRegistry)?;
54        lookup_descriptors(self.iter(), code)
55    }
56}
57
58/// Failure to construct or validate a diagnostic registry.
59#[derive(Clone, Copy, Debug, Eq, PartialEq)]
60pub enum RegistryError {
61    /// Two definitions use the same canonical diagnostic code.
62    DuplicateCode {
63        code: DiagnosticCode,
64        first_origin: DescriptorOrigin,
65        second_origin: DescriptorOrigin,
66    },
67}
68
69impl fmt::Display for RegistryError {
70    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
71        match self {
72            Self::DuplicateCode {
73                code,
74                first_origin,
75                second_origin,
76            } => write!(
77                formatter,
78                "duplicate diagnostic code {code} at {}:{}:{} and {}:{}:{}",
79                first_origin.file,
80                first_origin.line,
81                first_origin.module_path,
82                second_origin.file,
83                second_origin.line,
84                second_origin.module_path,
85            ),
86        }
87    }
88}
89
90impl Error for RegistryError {}
91
92/// Failure to resolve a diagnostic code.
93#[derive(Clone, Copy, Debug, Eq, PartialEq)]
94pub enum LookupError {
95    /// No descriptor has the requested canonical or unqualified code.
96    UnknownCode,
97    /// An unqualified code matches more than one canonical code.
98    AmbiguousCode {
99        first: DiagnosticCode,
100        second: DiagnosticCode,
101    },
102    /// The selected explicit registry contains duplicate canonical codes.
103    InvalidRegistry(RegistryError),
104}
105
106impl fmt::Display for LookupError {
107    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
108        match self {
109            Self::UnknownCode => formatter.write_str("unknown diagnostic code"),
110            Self::AmbiguousCode { first, second } => {
111                write!(formatter, "ambiguous diagnostic code; matches {first} and {second}")
112            }
113            Self::InvalidRegistry(error) => error.fmt(formatter),
114        }
115    }
116}
117
118impl Error for LookupError {
119    fn source(&self) -> Option<&(dyn Error + 'static)> {
120        match self {
121            Self::InvalidRegistry(error) => Some(error),
122            Self::UnknownCode | Self::AmbiguousCode { .. } => None,
123        }
124    }
125}
126
127impl From<RegistryError> for LookupError {
128    fn from(error: RegistryError) -> Self {
129        Self::InvalidRegistry(error)
130    }
131}
132
133fn lookup_descriptors(
134    descriptors: impl IntoIterator<Item = &'static DiagnosticDescriptor>,
135    code: &str,
136) -> Result<&'static DiagnosticDescriptor, LookupError> {
137    let canonical = match code.split_once('/') {
138        Some((namespace, unqualified))
139            if !namespace.is_empty() && !unqualified.is_empty() && !unqualified.contains('/') =>
140        {
141            Some((namespace, unqualified))
142        }
143        Some(_) => return Err(LookupError::UnknownCode),
144        None => None,
145    };
146    let mut matches = descriptors.into_iter().filter(|descriptor| {
147        if let Some((namespace, unqualified)) = canonical {
148            descriptor.code.namespace == namespace && descriptor.code.code == unqualified
149        } else {
150            descriptor.code.code == code
151        }
152    });
153
154    let Some(first) = matches.next() else {
155        return Err(LookupError::UnknownCode);
156    };
157    let Some(second) = matches.next() else {
158        return Ok(first);
159    };
160    Err(LookupError::AmbiguousCode {
161        first: first.code,
162        second: second.code,
163    })
164}
165
166#[cfg(feature = "linked-registry")]
167mod linked {
168    use alloc::{boxed::Box, vec::Vec};
169    use std::sync::OnceLock;
170
171    use super::{
172        DiagnosticDescriptor, LookupError, RegistryError, canonical_code_cmp, lookup_descriptors,
173        origin_cmp,
174    };
175
176    /// A deterministic index of descriptors contributed by linked crates.
177    #[derive(Debug)]
178    pub struct RegistryIndex {
179        descriptors: Box<[&'static DiagnosticDescriptor]>,
180    }
181
182    impl RegistryIndex {
183        /// Return the number of linked diagnostic definitions.
184        pub fn len(&self) -> usize {
185            self.descriptors.len()
186        }
187
188        /// Return true when no linked diagnostic definitions were retained.
189        pub fn is_empty(&self) -> bool {
190            self.descriptors.is_empty()
191        }
192
193        /// Iterate in canonical-code and definition-origin order.
194        pub fn iter(
195            &self,
196        ) -> impl DoubleEndedIterator<Item = &'static DiagnosticDescriptor> + ExactSizeIterator + '_
197        {
198            self.descriptors.iter().copied()
199        }
200
201        /// Look up a canonical code or a unique unqualified code.
202        pub fn lookup(&self, code: &str) -> Result<&'static DiagnosticDescriptor, LookupError> {
203            lookup_descriptors(self.iter(), code)
204        }
205    }
206
207    #[doc(hidden)]
208    pub struct RegistryEntry {
209        descriptor: &'static DiagnosticDescriptor,
210    }
211
212    impl RegistryEntry {
213        #[doc(hidden)]
214        pub const fn new(descriptor: &'static DiagnosticDescriptor) -> Self {
215            Self { descriptor }
216        }
217    }
218
219    inventory::collect!(RegistryEntry);
220
221    static LINKED_REGISTRY: OnceLock<Result<RegistryIndex, RegistryError>> = OnceLock::new();
222
223    /// Build and return the process-wide linked diagnostic registry.
224    ///
225    /// Applications embedding raw `wasm32-unknown-unknown` modules must run
226    /// their guarded constructor wrapper before the first call.
227    pub fn linked_registry() -> Result<&'static RegistryIndex, &'static RegistryError> {
228        LINKED_REGISTRY.get_or_init(build_index).as_ref()
229    }
230
231    fn build_index() -> Result<RegistryIndex, RegistryError> {
232        let mut descriptors: Vec<_> = inventory::iter::<RegistryEntry>
233            .into_iter()
234            .map(|entry| entry.descriptor)
235            .collect();
236        descriptors.sort_unstable_by(|left, right| {
237            canonical_code_cmp(left.code, right.code)
238                .then_with(|| origin_cmp(left.origin, right.origin))
239        });
240
241        for pair in descriptors.windows(2) {
242            let [first, second] = pair else {
243                unreachable!("windows(2) always contains two descriptors");
244            };
245            if first.code == second.code {
246                return Err(RegistryError::DuplicateCode {
247                    code: first.code,
248                    first_origin: first.origin,
249                    second_origin: second.origin,
250                });
251            }
252        }
253
254        Ok(RegistryIndex {
255            descriptors: descriptors.into_boxed_slice(),
256        })
257    }
258}
259
260#[cfg(feature = "linked-registry")]
261pub use linked::{RegistryEntry, RegistryIndex, linked_registry};
262
263#[cfg(any(test, feature = "linked-registry"))]
264fn canonical_code_cmp(left: DiagnosticCode, right: DiagnosticCode) -> Ordering {
265    left.namespace
266        .bytes()
267        .chain(core::iter::once(b'/'))
268        .chain(left.code.bytes())
269        .cmp(right.namespace.bytes().chain(core::iter::once(b'/')).chain(right.code.bytes()))
270}
271
272#[cfg(feature = "linked-registry")]
273fn origin_cmp(left: DescriptorOrigin, right: DescriptorOrigin) -> Ordering {
274    left.module_path
275        .cmp(right.module_path)
276        .then_with(|| left.file.cmp(right.file))
277        .then_with(|| left.line.cmp(&right.line))
278}
279
280#[cfg(test)]
281mod tests {
282    use alloc::vec::Vec;
283    use core::assert_matches;
284
285    use super::*;
286    use crate::{DiagnosticTag, Explanation, Severity};
287
288    static TAGS: &[DiagnosticTag] = &[];
289
290    static ALPHA_E1000: DiagnosticDescriptor = descriptor("alpha", "E1000", 10);
291    static ALPHA_W2000: DiagnosticDescriptor = descriptor("alpha", "W2000", 20);
292    static BETA_E1000: DiagnosticDescriptor = descriptor("beta", "E1000", 30);
293    static ALPHA: &[&DiagnosticDescriptor] = &[&ALPHA_E1000, &ALPHA_W2000];
294    static BETA: &[&DiagnosticDescriptor] = &[&BETA_E1000];
295
296    const fn descriptor(
297        namespace: &'static str,
298        code: &'static str,
299        line: u32,
300    ) -> DiagnosticDescriptor {
301        DiagnosticDescriptor {
302            code: DiagnosticCode { namespace, code },
303            summary: "summary",
304            default_severity: Severity::Error,
305            explanation: Explanation::NotProvided,
306            documentation_url: None,
307            tags: TAGS,
308            origin: DescriptorOrigin {
309                module_path: "registry::tests",
310                file: "registry.rs",
311                line,
312            },
313        }
314    }
315
316    #[test]
317    fn explicit_iteration_and_lookup_are_repeatable() {
318        let catalogs: &[&[&DiagnosticDescriptor]] = &[ALPHA, BETA];
319        let registry = StaticRegistry::from_slices(catalogs);
320
321        for _ in 0..2 {
322            assert_eq!(
323                registry.iter().map(|descriptor| descriptor.code).collect::<Vec<_>>(),
324                [ALPHA_E1000.code, ALPHA_W2000.code, BETA_E1000.code]
325            );
326            assert_eq!(registry.lookup("alpha/E1000"), Ok(&ALPHA_E1000));
327            assert_eq!(registry.lookup("W2000"), Ok(&ALPHA_W2000));
328            assert_eq!(registry.lookup("/E1000"), Err(LookupError::UnknownCode));
329            assert_eq!(registry.lookup("alpha/"), Err(LookupError::UnknownCode));
330            assert_eq!(registry.lookup("alpha/E1000/extra"), Err(LookupError::UnknownCode));
331            assert_eq!(registry.lookup("missing"), Err(LookupError::UnknownCode));
332            assert_eq!(
333                registry.lookup("E1000"),
334                Err(LookupError::AmbiguousCode {
335                    first: ALPHA_E1000.code,
336                    second: BETA_E1000.code,
337                })
338            );
339        }
340    }
341
342    #[test]
343    fn duplicate_code_reports_both_origins_in_composition_order() {
344        static DUPLICATE: DiagnosticDescriptor = descriptor("alpha", "E1000", 40);
345        let catalog: &[&DiagnosticDescriptor] = &[&ALPHA_E1000, &DUPLICATE];
346        let catalogs: &[&[&DiagnosticDescriptor]] = &[catalog];
347        let registry = StaticRegistry::from_slices(catalogs);
348        let expected = RegistryError::DuplicateCode {
349            code: ALPHA_E1000.code,
350            first_origin: ALPHA_E1000.origin,
351            second_origin: DUPLICATE.origin,
352        };
353
354        assert_eq!(registry.validate(), Err(expected));
355        assert_eq!(registry.lookup("alpha/E1000"), Err(LookupError::InvalidRegistry(expected)));
356    }
357
358    #[test]
359    fn repeated_descriptor_pointer_is_a_duplicate() {
360        let catalog: &[&DiagnosticDescriptor] = &[&ALPHA_E1000, &ALPHA_E1000];
361        let catalogs: &[&[&DiagnosticDescriptor]] = &[catalog];
362        assert_matches!(
363            StaticRegistry::from_slices(catalogs).validate(),
364            Err(RegistryError::DuplicateCode { .. })
365        );
366    }
367
368    #[test]
369    fn canonical_order_compares_the_separator_not_namespace_tuples() {
370        let prefix = DiagnosticCode {
371            namespace: "a",
372            code: "z",
373        };
374        let longer = DiagnosticCode {
375            namespace: "a!",
376            code: "a",
377        };
378        assert_eq!(canonical_code_cmp(longer, prefix), Ordering::Less);
379    }
380}