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.
// =============================================================================
//! Independent hierarchy and raw object-key listing checks.

use qubit_fs::directory::ListFilter;
use qubit_fs::directory::ListOptions;
use qubit_fs::directory::ListScope;
use qubit_fs::error::FsErrorKind;
use qubit_fs::error::FsOperation;
use qubit_fs::metadata::FileKind;
use qubit_fs::metadata::FileSystemCapability;
use qubit_fs::path::PathSemantics;

use crate::ContractCheckId;
use crate::ContractCheckOutcome;
use crate::ContractFailure;
use crate::FileSystemContractSuite;
use crate::FixtureSupport;
use crate::internal::verify_condition;
use crate::internal::verify_fs_error;

impl FileSystemContractSuite<'_> {
    /// Runs one isolated request for each listing requirement.
    ///
    /// # Errors
    ///
    /// Returns the first setup, provider, stream, or assertion failure from a
    /// listing check.
    pub(super) fn check_list(&mut self) -> Result<(), ContractFailure> {
        for id in [
            ContractCheckId::ListBasic,
            ContractCheckId::ListPrefix,
            ContractCheckId::ListPagination,
            ContractCheckId::ListLiteralPrefix,
            ContractCheckId::ListNamespace,
            ContractCheckId::ListRawRootPrefix,
        ] {
            self.check_list_item(id)?;
        }
        Ok(())
    }

    /// Prepares the expected entries and verifies one listing requirement.
    ///
    /// Flat-scope requirements are delegated to the corresponding helper;
    /// path-scope requirements seed entries, read the provider stream, and
    /// compare the observed paths with the expected set.
    ///
    /// # Parameters
    ///
    /// * `id` - Listing check to execute.
    ///
    /// # Errors
    ///
    /// Returns a failure when setup, provider listing, stream reading, or a
    /// listing assertion fails.
    pub(super) fn check_list_item(&mut self, id: ContractCheckId) -> Result<(), ContractFailure> {
        if matches!(id, ContractCheckId::ListNamespace | ContractCheckId::ListRawRootPrefix) {
            return self.check_flat_scope_item(id);
        }
        if !matches!(
            id,
            ContractCheckId::ListBasic
                | ContractCheckId::ListPrefix
                | ContractCheckId::ListPagination
                | ContractCheckId::ListLiteralPrefix
        ) {
            return Err(ContractFailure::message_only("selected entry is not listing").at(id));
        }
        self.context.begin_check(id);
        let hierarchical = self.context.properties().info().path_semantics() == PathSemantics::Hierarchical;
        let relative = self.context.relative_name("list-root");
        let root = self
            .fixture
            .path(&if hierarchical {
                relative.clone()
            } else {
                format!("{relative}/")
            })
            .map_err(|error| ContractFailure::with_source("list root preparation failed", error).at(id))?;
        let mut options = if hierarchical {
            ListOptions::default()
        } else {
            ListOptions::object_keys()
        };
        if id == ContractCheckId::ListLiteralPrefix {
            options = ListOptions::object_keys().with_filter(Some(ListFilter::LiteralPrefix("literal[1]".to_owned())));
        } else if id == ContractCheckId::ListPrefix {
            options = ListOptions::default()
                .with_recursive(true)
                .with_filter(Some(ListFilter::Subtree("prefixed".to_owned())));
        }
        let incompatible = (hierarchical && id == ContractCheckId::ListLiteralPrefix)
            || (!hierarchical && id == ContractCheckId::ListPrefix);
        let capability = FileSystemCapability::List;
        if incompatible || !self.capable(capability) {
            let error = match self.fixture.file_system().list(&ListScope::Path(root.clone()), options) {
                Err(error) => error,
                Ok(_) => {
                    return Err(ContractFailure::message_only("unsupported list request succeeded").at(id));
                }
            };
            let kind = if incompatible {
                FsErrorKind::InvalidOptions
            } else {
                FsErrorKind::UnsupportedCapability
            };
            let required = if incompatible { None } else { Some(capability) };
            verify_fs_error(
                error,
                kind,
                FsOperation::List,
                &root,
                self.context.properties().info().provider_id(),
                required,
                id,
            )?;
            self.context
                .record_check(id, Some(capability), ContractCheckOutcome::RejectedAsExpected);
            return Ok(());
        }
        let mut expected = Vec::new();
        if id == ContractCheckId::ListPrefix {
            let directories: &[&str] = if hierarchical {
                &["prefixed", "prefixed/nested"]
            } else {
                &["prefixed"]
            };
            for directory in directories {
                let prepared = self
                    .fixture
                    .seed_empty_directory(&format!("{relative}/{directory}"))
                    .map_err(|error| ContractFailure::with_source("list subtree preparation failed", error).at(id))?;
                let FixtureSupport::Supported(path) = prepared else {
                    self.context.record_check(
                        id,
                        Some(capability),
                        ContractCheckOutcome::Unverified {
                            reason: "subtree listing needs independently prepared directories".to_owned(),
                        },
                    );
                    return Ok(());
                };
                self.context.record_created(path.clone());
                expected.push((path, true));
            }
        } else if id == ContractCheckId::ListBasic && hierarchical {
            let prepared = self
                .fixture
                .seed_empty_directory(&format!("{relative}/nested"))
                .map_err(|error| {
                    ContractFailure::with_source("list child directory preparation failed", error).at(id)
                })?;
            let FixtureSupport::Supported(path) = prepared else {
                self.context.record_check(
                    id,
                    Some(capability),
                    ContractCheckOutcome::Unverified {
                        reason: "hierarchical listing needs an independently prepared child directory".to_owned(),
                    },
                );
                return Ok(());
            };
            self.context.record_created(path.clone());
            expected.push((path, true));
        }
        let names: &[&str] = match id {
            ContractCheckId::ListPrefix if hierarchical => {
                &["prefixed/first", "prefixed/second", "prefixed/nested/child", "decoy"]
            }
            ContractCheckId::ListPrefix => &["prefixed/first", "prefixed/second", "decoy"],
            ContractCheckId::ListLiteralPrefix => &["literal[1]-match", "literal1-decoy"],
            ContractCheckId::ListPagination => &["first", "second", "third"],
            _ if !hierarchical => &["first", "nested/second"],
            _ if hierarchical => &["first", "second", "nested/child"],
            _ => &["first", "second"],
        };
        for name in names {
            let prepared = self
                .fixture
                .seed_file(&format!("{relative}/{name}"), b"list entry")
                .map_err(|error| ContractFailure::with_source("list entry preparation failed", error).at(id))?;
            let FixtureSupport::Supported(path) = prepared else {
                self.context.record_check(
                    id,
                    Some(capability),
                    ContractCheckOutcome::Unverified {
                        reason: "listing needs independently prepared entries".to_owned(),
                    },
                );
                return Ok(());
            };
            self.context.record_created(path.clone());
            let selected = match id {
                ContractCheckId::ListPrefix => name.starts_with("prefixed/"),
                ContractCheckId::ListBasic if hierarchical => *name != "nested/child",
                ContractCheckId::ListLiteralPrefix => name.starts_with("literal[1]"),
                _ => true,
            };
            if selected {
                expected.push((path, false));
            }
        }
        let metadata = matches!(id, ContractCheckId::ListPrefix | ContractCheckId::ListPagination);
        options = options
            .with_include_metadata(metadata)
            .with_max_entries(Some(expected.len() + 1));
        if id == ContractCheckId::ListPagination {
            options = options.with_page_size(Some(1));
        }
        let mut stream = self
            .fixture
            .file_system()
            .list(&ListScope::Path(root.clone()), options)
            .map_err(|error| ContractFailure::with_source("list request failed", error).at(id))?;
        let mut actual = Vec::new();
        while let Some(entry) = stream
            .next_entry()
            .map_err(|error| ContractFailure::with_source("list stream error", error).at(id))?
        {
            if metadata {
                verify_condition(
                    entry.metadata.is_some(),
                    id,
                    "list contract: requested entry metadata is missing",
                )?;
            }
            let expected_directory = expected
                .iter()
                .find(|(path, _)| *path == entry.path)
                .map(|(_, expected_directory)| *expected_directory);
            let Some(expected_directory) = expected_directory else {
                return Err(ContractFailure::message_only("listing returned duplicate or unexpected entries").at(id));
            };
            let correct_kind = if expected_directory {
                matches!(entry.kind, FileKind::Directory)
            } else {
                matches!(entry.kind, FileKind::File | FileKind::Object)
            };
            verify_condition(
                correct_kind,
                id,
                "list entry kind differs from independently seeded resource",
            )?;
            actual.push(entry.path);
            verify_condition(
                actual.len() <= expected.len(),
                id,
                "listing returned duplicate or unexpected entries",
            )?;
        }
        actual.sort_by(|left, right| left.as_str().cmp(right.as_str()));
        expected.sort_by(|(left, _), (right, _)| left.as_str().cmp(right.as_str()));
        let expected = expected.into_iter().map(|(path, _)| path).collect::<Vec<_>>();
        verify_condition(
            actual == expected,
            id,
            "list/basic: direct children mismatch or filtered entries mismatch",
        )?;
        self.context
            .record_check(id, Some(capability), ContractCheckOutcome::Passed);
        Ok(())
    }
}