Skip to main content

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}