qubit_fs_testkit/cleanup_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//! Cleanup evidence retained across explicit retries.
9
10use crate::ContractFailure;
11
12/// Cleanup attempts and their historical failures.
13///
14/// A later successful teardown does not erase a failed facade deletion.
15///
16/// # Examples
17///
18/// ```
19/// # mod support { include!(concat!(env!("CARGO_MANIFEST_DIR"), "/tests/common/rustdoc_support.rs")); }
20/// # use support::RustdocSyncFixture;
21/// use qubit_fs_testkit::{FileSystemContract, FileSystemContractSuite};
22///
23/// let fixture = RustdocSyncFixture::new();
24/// let mut suite = FileSystemContractSuite::new(&fixture);
25/// suite.run_contract(FileSystemContract::Properties);
26/// assert!(suite.run().cleanup().completed());
27/// ```
28#[must_use]
29pub struct CleanupReport {
30 /// Number of cleanup attempts that started, including cancelled attempts.
31 pub(crate) attempts: usize,
32 /// Whether the latest cleanup attempt returned successfully.
33 pub(crate) completed: bool,
34 /// Failures observed across all cleanup attempts, in observation order.
35 pub(crate) failures: Vec<ContractFailure>,
36}
37
38impl CleanupReport {
39 /// Creates an empty cleanup history.
40 pub(crate) const fn new() -> Self {
41 Self {
42 attempts: 0,
43 completed: false,
44 failures: Vec::new(),
45 }
46 }
47
48 /// Returns the number of cleanup attempts started, including cancelled
49 /// ones.
50 ///
51 /// # Returns
52 /// The number of attempts that began before this report was observed.
53 #[must_use = "inspect the retained cleanup failures"]
54 #[inline]
55 pub const fn attempts(&self) -> usize {
56 self.attempts
57 }
58
59 /// Returns whether the latest cleanup attempt returned successfully.
60 ///
61 /// # Returns
62 /// `true` when the latest attempt returned successfully, and `false` when
63 /// it failed or was cancelled.
64 #[must_use = "inspect the retained cleanup failures"]
65 #[inline]
66 pub const fn completed(&self) -> bool {
67 self.completed
68 }
69
70 /// Returns every observed failure, including failures before a retry.
71 ///
72 /// # Returns
73 /// The failures from all attempts in the order they were observed.
74 #[must_use = "inspect the retained cleanup failures"]
75 #[inline]
76 pub fn failures(&self) -> &[ContractFailure] {
77 &self.failures
78 }
79}