qubit-fs-testkit 0.9.2

Reusable provider contract checks for qubit-fs implementations
Documentation
// =============================================================================
//    Copyright (c) 2026 Haixing Hu.
//
//    SPDX-License-Identifier: Apache-2.0
//
//    Licensed under the Apache License, Version 2.0.
// =============================================================================
//! Dispatches temporary-resource checks through the typed catalog.

use super::AsyncFileSystemContractSuite;
use super::FileSystemCapability;
use crate::ContractCheckId;
use crate::ContractCheckOutcome;
use crate::ContractFailure;

impl<'a> AsyncFileSystemContractSuite<'a> {
    /// Executes all asynchronous temporary-resource checks in catalog order.
    ///
    /// # Returns
    ///
    /// Returns `Ok(())` after every temporary-resource check completes, or a
    /// `ContractFailure` when a check cannot complete.
    ///
    /// # Errors
    ///
    /// Returns a `ContractFailure` if any temporary-resource check fails.
    pub(super) async fn check_temp_resources(&mut self) -> Result<(), ContractFailure> {
        for id in [
            ContractCheckId::TempFile,
            ContractCheckId::TempDirectory,
            ContractCheckId::TempAtomic,
            ContractCheckId::TempRepeatedLifecycle,
        ] {
            self.check_temp_item(id).await?;
        }
        Ok(())
    }

    /// Executes exactly one temporary-resource catalog entry.
    ///
    /// The selected identifier must belong to the temporary lifecycle
    /// contract; execution records the resulting check outcome in the suite
    /// context.
    ///
    /// # Returns
    ///
    /// Returns `Ok(())` after recording the check outcome.
    ///
    /// # Errors
    ///
    /// Returns a `ContractFailure` if `id` does not select a temporary
    /// lifecycle entry, or if the selected provider operation or observation
    /// fails to satisfy its contract.
    ///
    /// # Parameters
    ///
    /// - `id`: Temporary-resource check identity selecting the lifecycle case.
    pub(super) async fn check_temp_item(&mut self, id: ContractCheckId) -> Result<(), ContractFailure> {
        self.context.begin_check(id);
        let file = self.capable(FileSystemCapability::TempFile);
        let directory = self.capable(FileSystemCapability::TempDirectory);
        let mut unverified_reason = None;
        let outcome = match id {
            ContractCheckId::TempFile => {
                unverified_reason = self.execute_temp_file(id).await?;
                if file {
                    ContractCheckOutcome::Passed
                } else {
                    ContractCheckOutcome::RejectedAsExpected
                }
            }
            ContractCheckId::TempDirectory => {
                unverified_reason = self.execute_temp_directory(id).await?;
                if directory {
                    ContractCheckOutcome::Passed
                } else {
                    ContractCheckOutcome::RejectedAsExpected
                }
            }
            ContractCheckId::TempAtomic | ContractCheckId::TempRepeatedLifecycle => {
                if file {
                    unverified_reason = self.execute_temp_file(id).await?;
                }
                if directory && let Some(reason) = self.execute_temp_directory(id).await? {
                    unverified_reason.get_or_insert(reason);
                }
                if !file && !directory {
                    ContractCheckOutcome::NotApplicable {
                        reason: "no temporary resource capability".to_owned(),
                    }
                } else if id == ContractCheckId::TempAtomic && !self.capable(FileSystemCapability::AtomicTempPersist) {
                    ContractCheckOutcome::RejectedAsExpected
                } else {
                    ContractCheckOutcome::Passed
                }
            }
            _ => {
                return Err(ContractFailure::message_only("selected entry is not temporary lifecycle").at(id));
            }
        };
        let outcome = match unverified_reason {
            Some(reason) => ContractCheckOutcome::Unverified { reason },
            None => outcome,
        };
        self.context.record_check(
            id,
            crate::internal::check_catalog::specification(id).capability,
            outcome,
        );
        Ok(())
    }
}