qubit-metadata 0.6.1

Type-safe metadata model with schemas and composable filters
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114

// =============================================================================
//    Copyright (c) 2025 - 2026 Haixing Hu.
//
//    SPDX-License-Identifier: Apache-2.0
//
//    Licensed under the Apache License, Version 2.0.
// =============================================================================
//! [`MetadataValidationError`] — aggregate schema validation failures.

use std::fmt;

use crate::metadata_error::MetadataError;

/// Aggregate error returned by schema-level validation APIs.
///
/// Unlike single-entry metadata accessors, schema validation can discover
/// multiple independent issues in one pass. This type preserves all collected
/// [`MetadataError`] values so callers can report or fix them together.
///
/// # Examples
///
/// ```
/// use qubit_metadata::{MetadataError, MetadataValidationError};
///
/// let error = MetadataValidationError::from_issue(MetadataError::MissingKey("tenant".into()));
/// assert_eq!(error.len(), 1);
/// ```
#[derive(Debug, Clone, PartialEq, Eq)]
#[must_use]
pub struct MetadataValidationError {
    /// Collected validation issues.
    issues: Vec<MetadataError>,
}

impl MetadataValidationError {
    /// Creates an aggregate validation error from one issue.
    ///
    /// # Parameters
    ///
    /// * `issue` - Validation issue to store.
    ///
    /// # Returns
    ///
    /// An aggregate error containing exactly one issue.
    #[inline]
    #[must_use = "the validation error should be inspected"]
    pub fn from_issue(issue: MetadataError) -> Self {
        Self { issues: vec![issue] }
    }

    /// Creates an aggregate validation error from a non-empty issue list.
    ///
    /// Returns `None` when `issues` is empty because an empty validation error
    /// has no actionable meaning.
    ///
    /// # Parameters
    ///
    /// * `issues` - Validation issues to aggregate.
    ///
    /// # Returns
    ///
    /// `Some` aggregate error for a non-empty list; otherwise, `None`.
    #[inline]
    pub fn from_issues(issues: Vec<MetadataError>) -> Option<Self> {
        (!issues.is_empty()).then_some(Self { issues })
    }

    /// Returns the collected validation issues.
    ///
    /// # Returns
    ///
    /// The issues in discovery order.
    #[inline]
    #[must_use = "the validation issues should be inspected"]
    pub fn issues(&self) -> &[MetadataError] {
        &self.issues
    }

    /// Returns the number of collected validation issues.
    ///
    /// # Returns
    ///
    /// The issue count.
    #[inline]
    #[must_use]
    #[allow(clippy::len_without_is_empty)]
    pub fn len(&self) -> usize {
        self.issues.len()
    }

    /// Converts this aggregate error into its collected issues.
    ///
    /// # Returns
    ///
    /// The owned issues in discovery order.
    #[inline]
    #[must_use]
    pub fn into_issues(self) -> Vec<MetadataError> {
        self.issues
    }
}

impl fmt::Display for MetadataValidationError {
    /// Formats the validation summary and every collected issue.
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(formatter, "{} metadata validation issue(s)", self.issues.len())?;
        for (index, issue) in self.issues.iter().enumerate() {
            write!(formatter, "; {}: {issue}", index + 1)?;
        }
        Ok(())
    }
}

impl std::error::Error for MetadataValidationError {}