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