qubit_redact/facade/
redaction_summary.rs

1// =============================================================================
2//    Copyright (c) 2026 Haixing Hu.
3//
4//    SPDX-License-Identifier: Apache-2.0
5//
6//    Licensed under the Apache License, Version 2.0.
7// =============================================================================
8//! Machine-readable redaction summaries.
9
10use super::RedactionReason;
11use super::RedactionReasons;
12use super::RedactionUsage;
13use crate::output::RedactionCompletion;
14
15/// Machine-readable summary of one redaction operation.
16///
17/// # Examples
18///
19/// ```
20/// use qubit_redact::RedactionCompletion;
21/// use qubit_redact::Redactor;
22///
23/// let output = Redactor::standard().redact_field("password", "raw-secret");
24/// assert_eq!(output.summary().completion(), RedactionCompletion::Complete);
25/// assert!(!output.summary().is_redaction_disabled());
26/// ```
27#[derive(Debug, Clone, Copy, PartialEq, Eq)]
28pub struct RedactionSummary {
29    /// Whether the operation intentionally bypassed redaction.
30    redaction_disabled: bool,
31    /// Final completion state of the operation.
32    completion: RedactionCompletion,
33    /// Reasons explaining degraded completion.
34    reasons: RedactionReasons,
35    /// Resource accounting captured by the operation.
36    usage: RedactionUsage,
37}
38
39impl RedactionSummary {
40    /// Creates a summary from runtime-owned completion, reasons, and usage.
41    ///
42    /// # Parameters
43    ///
44    /// - `redaction_disabled`: Whether the operation intentionally bypassed
45    ///   redaction.
46    /// - `completion`: Final state of the safe representation.
47    /// - `reasons`: Independent causes recorded by the operation.
48    /// - `usage`: Completed resource measurements.
49    ///
50    /// # Returns
51    ///
52    /// A summary retaining the supplied completion, reasons, and accounting.
53    #[must_use]
54    #[inline(always)]
55    pub(crate) const fn from_parts(
56        redaction_disabled: bool,
57        completion: RedactionCompletion,
58        reasons: RedactionReasons,
59        usage: RedactionUsage,
60    ) -> Self {
61        Self {
62            redaction_disabled,
63            completion,
64            reasons,
65            usage,
66        }
67    }
68
69    /// Creates a degraded summary.
70    ///
71    /// # Parameters
72    ///
73    /// - `reason`: Cause of the degraded safe representation.
74    ///
75    /// # Returns
76    ///
77    /// A truncated summary with the supplied reason and empty accounting.
78    #[must_use]
79    #[inline(always)]
80    pub(crate) const fn truncated(reason: RedactionReason) -> Self {
81        Self {
82            redaction_disabled: false,
83            completion: RedactionCompletion::Truncated,
84            reasons: RedactionReasons::empty().with(reason),
85            usage: RedactionUsage::empty(),
86        }
87    }
88
89    /// Creates a summary for a transaction that exhausted safe output capacity.
90    ///
91    /// # Returns
92    ///
93    /// An exhausted summary with the output-limit reason and empty accounting.
94    #[must_use]
95    #[inline(always)]
96    pub(crate) const fn exhausted() -> Self {
97        Self {
98            redaction_disabled: false,
99            completion: RedactionCompletion::Exhausted,
100            reasons: RedactionReasons::empty().with(RedactionReason::OutputLimitReached),
101            usage: RedactionUsage::empty(),
102        }
103    }
104
105    /// Returns completion state.
106    ///
107    /// # Returns
108    ///
109    /// The final completion state of the safe representation.
110    #[must_use = "the completion state describes whether the output is complete"]
111    #[inline(always)]
112    pub const fn completion(self) -> RedactionCompletion {
113        self.completion
114    }
115
116    /// Returns whether redaction was globally disabled for this operation.
117    ///
118    /// # Returns
119    ///
120    /// True when this operation intentionally bypassed redaction.
121    #[must_use]
122    #[inline(always)]
123    pub const fn is_redaction_disabled(self) -> bool {
124        self.redaction_disabled
125    }
126
127    /// Returns accumulated reasons.
128    ///
129    /// # Returns
130    ///
131    /// All machine-readable causes retained by the operation.
132    #[must_use]
133    #[inline(always)]
134    pub const fn reasons(self) -> RedactionReasons {
135        self.reasons
136    }
137
138    /// Returns resource use measured by the operation that produced this
139    /// summary.
140    ///
141    /// # Returns
142    ///
143    /// The resource measurements associated with this operation.
144    #[must_use]
145    #[inline(always)]
146    pub const fn usage(self) -> RedactionUsage {
147        self.usage
148    }
149}
qubit_redact/facade/redaction_summary.rs

qubit_redact/facade/
redaction_summary.rs
