qubit_fs_testkit/contract_report.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//! Public report of the checks performed by a contract suite.
9
10use qubit_fs::metadata::FileSystemCapability;
11
12use crate::ContractCheck;
13use crate::ContractCheckId;
14use crate::ContractCheckOutcome;
15
16/// A report containing stable check identities and their outcomes.
17///
18/// This report describes check evidence only. It does not establish that the
19/// contract run completed, that its execution succeeded, or that cleanup
20/// succeeded. Use
21/// [`ContractRun::assert_satisfied`](crate::ContractRun::assert_satisfied)
22/// or [`ContractRun::assert_satisfied_with`](crate::ContractRun::assert_satisfied_with)
23/// to validate the complete run.
24///
25/// # Examples
26///
27/// ```
28/// # mod support { include!(concat!(env!("CARGO_MANIFEST_DIR"), "/tests/common/rustdoc_support.rs")); }
29/// # use support::RustdocSyncFixture;
30/// use qubit_fs_testkit::{FileSystemContract, FileSystemContractSuite};
31///
32/// let fixture = RustdocSyncFixture::new();
33/// let mut suite = FileSystemContractSuite::new(&fixture);
34/// suite.run_contract(FileSystemContract::Properties);
35/// assert!(!suite.run().report().checks().is_empty());
36/// ```
37#[must_use]
38#[derive(Clone, Debug, Eq, PartialEq)]
39pub struct ContractReport {
40 /// Checks recorded so far in execution order.
41 pub(crate) checks: Vec<ContractCheck>,
42 /// Check identities registered by the phase catalog.
43 ///
44 /// Keeping this set separately from `checks` lets completeness detect a
45 /// phase whose implementation forgot to record one of its cataloged
46 /// checks. A report that only contains ad-hoc checks must not be able to
47 /// claim that a contract phase was fully exercised.
48 pub(crate) expected: Vec<ContractCheckId>,
49 /// Catalog entries that have not yet received a completion.
50 pending: Vec<ContractCheckId>,
51 /// Invalid registrations or completion transitions retained for diagnosis.
52 violations: Vec<String>,
53}
54
55impl ContractReport {
56 /// Returns checks in execution order.
57 ///
58 /// # Returns
59 /// The recorded checks in the order their outcomes were produced.
60 #[inline]
61 #[must_use = "inspect the recorded contract checks"]
62 pub fn checks(&self) -> &[ContractCheck] {
63 &self.checks
64 }
65
66 /// Returns whether the registered contract requirements have evidence.
67 ///
68 /// An unavailable optional probe is acceptable. A probe that ran and failed
69 /// is always a failure, even when it was optional.
70 /// This checks report evidence only; it does not include execution or
71 /// cleanup status. Use
72 /// [`ContractRun::requirements_satisfied`](crate::ContractRun::requirements_satisfied)
73 /// to check the complete run.
74 #[must_use]
75 pub fn requirements_satisfied(&self) -> bool {
76 self.requirements_satisfied_with(&[])
77 }
78
79 /// Also requires evidence for the caller-selected optional checks.
80 ///
81 /// A requested identity absent from this run cannot satisfy the request.
82 /// This checks report evidence only; it does not include execution or
83 /// cleanup status. Use
84 /// [`ContractRun::requirements_satisfied_with`](crate::ContractRun::requirements_satisfied_with)
85 /// to check the complete run.
86 ///
87 /// # Parameters
88 /// - `required`: Optional check identities that must have evidence.
89 ///
90 /// # Returns
91 /// Whether the registered requirements and selected optional checks are
92 /// satisfied.
93 #[must_use]
94 pub fn requirements_satisfied_with(&self, required: &[ContractCheckId]) -> bool {
95 !self.expected.is_empty()
96 && self.pending.is_empty()
97 && self.violations.is_empty()
98 && self
99 .expected
100 .iter()
101 .all(|id| self.checks.iter().any(|check| check.id() == *id))
102 && self.checks.iter().all(|check| match check.outcome() {
103 ContractCheckOutcome::Passed | ContractCheckOutcome::RejectedAsExpected => true,
104 ContractCheckOutcome::NotApplicable { reason } => !reason.trim().is_empty(),
105 ContractCheckOutcome::SkippedOptional { reason } => {
106 !reason.trim().is_empty() && !required.contains(&check.id())
107 }
108 ContractCheckOutcome::Unverified { .. }
109 | ContractCheckOutcome::Failed { .. }
110 | ContractCheckOutcome::NotRun { .. } => false,
111 })
112 && required.iter().all(|id| self.expected.contains(id))
113 }
114
115 /// Returns whether every applicable check, including optional probes, was
116 /// verified.
117 /// This checks report evidence only; it does not include execution or
118 /// cleanup status. Use
119 /// [`ContractRun::all_applicable_checks_verified`](crate::ContractRun::all_applicable_checks_verified)
120 /// to check the complete run.
121 ///
122 /// # Returns
123 /// Whether all applicable checks have evidence, including optional probes.
124 #[must_use]
125 pub fn all_applicable_checks_verified(&self) -> bool {
126 self.requirements_satisfied_with(&self.expected)
127 }
128
129 /// Panics if registered requirements lack successful evidence.
130 /// This checks report evidence only; it does not include execution or
131 /// cleanup status. Use
132 /// [`ContractRun::assert_satisfied`](crate::ContractRun::assert_satisfied)
133 /// to validate the complete run.
134 ///
135 /// # Panics
136 /// Panics with a summary when any registered requirement lacks successful
137 /// evidence.
138 #[track_caller]
139 pub fn assert_satisfied(&self) {
140 self.assert_satisfied_with(&[]);
141 }
142
143 /// Also requires the selected optional probes to have evidence.
144 /// This checks report evidence only; it does not include execution or
145 /// cleanup status. Use
146 /// [`ContractRun::assert_satisfied_with`](crate::ContractRun::assert_satisfied_with)
147 /// to validate the complete run.
148 ///
149 /// # Panics
150 /// Panics when any required check or selected optional probe is unverified.
151 ///
152 /// # Parameters
153 /// - `required`: Optional check identities that must have evidence.
154 #[track_caller]
155 pub fn assert_satisfied_with(&self, required: &[ContractCheckId]) {
156 if self.requirements_satisfied_with(required) {
157 return;
158 }
159 let mut issues = self.violations.clone();
160 if self.expected.is_empty() {
161 issues.push("report has no registered phase".to_owned());
162 }
163 for id in &self.expected {
164 if !self.checks.iter().any(|check| check.id() == *id) {
165 issues.push(format!("{id} (check was not recorded)"));
166 }
167 }
168 for check in &self.checks {
169 match check.outcome() {
170 ContractCheckOutcome::Unverified { reason }
171 | ContractCheckOutcome::Failed { reason }
172 | ContractCheckOutcome::NotRun { reason } => {
173 issues.push(format!("{} ({reason})", check.id()));
174 }
175 ContractCheckOutcome::SkippedOptional { reason } if required.contains(&check.id()) => {
176 issues.push(format!("{} (required optional probe: {reason})", check.id()));
177 }
178 ContractCheckOutcome::SkippedOptional { reason } | ContractCheckOutcome::NotApplicable { reason }
179 if reason.trim().is_empty() =>
180 {
181 issues.push(format!("{} (missing applicability reason)", check.id()));
182 }
183 _ => {}
184 }
185 }
186 for id in required {
187 if !self.expected.contains(id) {
188 issues.push(format!("{id} (requested probe is outside this run)"));
189 }
190 }
191 panic!(
192 "[fs-testkit:report/incomplete] unverified checks: {}",
193 issues.join(", ")
194 );
195 }
196
197 /// Creates an empty report for a suite run.
198 #[inline]
199 pub(crate) const fn new() -> Self {
200 Self {
201 checks: Vec::new(),
202 expected: Vec::new(),
203 pending: Vec::new(),
204 violations: Vec::new(),
205 }
206 }
207
208 /// Registers a catalog entry before a phase starts running.
209 ///
210 /// # Parameters
211 /// - `id`: Stable identity of the check expected from the phase.
212 pub(crate) fn expect(&mut self, id: ContractCheckId) {
213 if !self.expected.contains(&id) {
214 self.expected.push(id);
215 self.pending.push(id);
216 }
217 }
218
219 /// Appends one check produced by a suite phase.
220 ///
221 /// # Parameters
222 /// - `id`: Stable identity of the check.
223 /// - `capability`: Filesystem capability associated with the check, if any.
224 /// - `outcome`: Result recorded for the check.
225 #[inline]
226 pub(crate) fn push(
227 &mut self,
228 id: ContractCheckId,
229 capability: Option<FileSystemCapability>,
230 outcome: ContractCheckOutcome,
231 ) {
232 self.checks.push(ContractCheck {
233 id,
234 capability,
235 outcome,
236 });
237 }
238
239 /// Registers a pending catalog check without completing it.
240 ///
241 /// # Parameters
242 ///
243 /// - `id`: Stable identity of the check expected from the phase.
244 /// - `capability`: Filesystem capability associated with the check, if any.
245 pub(crate) fn register(&mut self, id: ContractCheckId, capability: Option<FileSystemCapability>) {
246 if self.expected.contains(&id) {
247 self.violations.push(format!("{id} (duplicate registration)"));
248 return;
249 }
250 self.expect(id);
251 self.push(
252 id,
253 capability,
254 ContractCheckOutcome::NotRun {
255 reason: "check not yet executed".to_owned(),
256 },
257 );
258 }
259
260 /// Completes a registered check exactly once, retaining invalid
261 /// transitions.
262 ///
263 /// # Parameters
264 /// - `id`: Stable identity of the pending check.
265 /// - `capability`: Filesystem capability associated with the completed
266 /// check, if any.
267 /// - `outcome`: Completion outcome to retain in the report.
268 pub(crate) fn record(
269 &mut self,
270 id: ContractCheckId,
271 capability: Option<FileSystemCapability>,
272 outcome: ContractCheckOutcome,
273 ) {
274 if matches!(outcome, ContractCheckOutcome::SkippedOptional { .. })
275 && !crate::internal::check_catalog::specification(id).optional
276 {
277 self.violations
278 .push(format!("{id} (core check cannot be skipped as optional)"));
279 }
280 let Some(index) = self.pending.iter().position(|pending| *pending == id) else {
281 let reason = if self.expected.contains(&id) {
282 "duplicate completion"
283 } else {
284 "unregistered check"
285 };
286 self.violations.push(format!("{id} ({reason})"));
287 return;
288 };
289 let _ = self.pending.remove(index);
290 if let Some(check) = self.checks.iter_mut().find(|check| check.id == id) {
291 check.capability = capability;
292 check.outcome = outcome;
293 } else {
294 self.push(id, capability, outcome);
295 }
296 }
297}