checkito 5.0.0

use crate::{
    GENERATES, SHRINKS,
    generate::Generate,
    prove::Prove,
    shrink::Shrink,
    state::{self, Modes, Sizes, State, States},
    utility::cast,
};
use core::{
    error,
    fmt::{self, Debug},
    iter,
    mem::take,
    num::NonZeroUsize,
    ops::{self, Deref, DerefMut},
    panic::AssertUnwindSafe,
    result,
};
use std::{borrow::Cow, env, panic::catch_unwind, thread::available_parallelism};

/// Configures the generation process.
#[derive(Clone, Debug)]
pub struct Generates {
    /// The seed for the random number generator.
    ///
    /// Using the same seed will cause the generator to produce the same
    /// sequence of random values, making test runs reproducible. It
    /// defaults to a random value.
    pub seed: u64,
    /// The range of sizes (`0.0..=1.0`) that will be gradually traversed while
    /// generating values.
    ///
    /// Defaults to `0.0..=1.0`.
    pub sizes: Sizes,
    /// The maximum number of values to generate and test.
    ///
    /// Setting this to `0` will prevent any tests from running. Defaults to
    /// [`GENERATES`].
    pub count: usize,
    /// Whether the iterator should yield [`Result::Pass`] items.
    ///
    /// If `false`, the iterator will be empty for successful test runs.
    /// Defaults to `true`.
    pub items: bool,
    /// Overrides the exhaustive check detection.
    /// - `Some(true)`: Forces exhaustive checking, ignoring `seed` and `sizes`.
    /// - `Some(false)`: Forces random sampling.
    /// - `None`: Automatically determines whether to be exhaustive based on
    ///   whether the generator's [`Generate::cardinality`] is less than or
    ///   equal to `count`.
    pub exhaustive: Option<bool>,
}

/// Configures the shrinking process.
#[derive(Clone, Debug)]
pub struct Shrinks {
    /// The maximum number of times to shrink a failing value.
    ///
    /// Setting this to `0` disables shrinking. Defaults to [`SHRINKS`].
    pub count: usize,
    /// Whether the iterator should yield [`Result::Shrink`] items.
    ///
    /// If `false`, successful shrink steps will not be reported. Defaults to
    /// `true`.
    pub items: bool,
    /// Whether the iterator should yield [`Result::Shrunk`] items.
    ///
    /// If `false`, failing shrink steps will not be reported. Defaults to
    /// `true`.
    pub errors: bool,
}

/// Holds a generator and the configuration for the checking and shrinking
/// processes.
///
/// A `Checker` is created by calling [`Check::checker`] on a generator. It
/// provides a builder-like interface for configuring the test run before
/// executing it via [`Checker::check`] or [`Checker::checks`].
#[derive(Debug, Clone)]
pub struct Checker<G: ?Sized, R> {
    /// The configuration for the generation process.
    pub generate: Generates,
    /// The configuration for the shrinking process.
    pub shrink: Shrinks,
    /// The configuration for the running process.
    run: R,
    /// The generator that will produce values for the test.
    pub generator: G,
}

#[derive(Debug, Copy, Clone)]
struct Yields {
    passes: bool,
    shrinks: bool,
    shrunks: bool,
}

/// An extension trait, implemented for all [`Generate`] types, that provides
/// the main entry points for running property tests.
pub trait Check: Generate {
    /// Creates a [`Checker`] for this generator.
    ///
    /// The `Checker` can be used to configure and run the property test.
    ///
    /// # Examples
    ///
    /// ```
    /// # use checkito::*;
    /// let mut checker = (0..100).checker();
    /// checker.generate.count = 500; // Run 500 test cases.
    /// checker.shrink.count = 0; // Disable shrinking.
    ///
    /// let result = checker.check(|x| x < 100);
    /// assert!(result.is_none());
    /// ```
    fn checker(self) -> Checker<Self, synchronous::Run>
    where
        Self: Sized,
    {
        Checker::new(self, state::seed())
    }

    /// Creates an iterator that runs the property test.
    ///
    /// This is useful for consuming the full sequence of test results,
    /// including intermediate shrink steps.
    ///
    /// # Examples
    ///
    /// ```
    /// # use checkito::*;
    /// let mut checks = (0..10).checks(|x| x < 5);
    ///
    /// assert!(matches!(checks.next(), Some(check::Result::Pass(_))));
    /// // ...
    /// assert!(matches!(checks.last(), Some(check::Result::Fail(_))));
    /// ```
    fn checks<P: Prove, C: FnMut(Self::Item) -> P>(
        self,
        check: C,
    ) -> synchronous::Iterator<Self, P, C>
    where
        Self: Sized,
    {
        self.checker().checks(check)
    }

    /// Runs the property test and returns the final failure, if any.
    ///
    /// This is the simplest way to run a test. It consumes the entire test
    /// iterator and returns `Some(Fail)` if the property was violated, or
    /// `None` if all test cases passed.
    ///
    /// # Examples
    ///
    /// ```
    /// # use checkito::*;
    /// let success = (0..100).check(|x| x < 100);
    /// assert!(success.is_none());
    ///
    /// let failure = (0..100).check(|x| x < 50);
    /// assert!(failure.is_some());
    ///
    /// let fail = failure.unwrap();
    /// // The shrinker will find the minimal failing value.
    /// assert_eq!(fail.item, 50);
    /// ```
    fn check<P: Prove, C: FnMut(Self::Item) -> P>(
        &self,
        check: C,
    ) -> Option<Fail<Self::Item, P::Error>> {
        self.checker().check(check)
    }
}

/// The result of a single step in the property testing process.
#[derive(Clone, Debug)]
pub enum Result<T, P: Prove> {
    /// A generated value passed the test.
    Pass(Pass<T, P::Proof>),
    /// A shrunk value passed the test, meaning it did not reproduce the
    /// failure.
    Shrink(Pass<T, P::Proof>),
    /// A shrunk value failed the test, becoming the new minimal failing case.
    Shrunk(Fail<T, P::Error>),
    /// The final, minimal value that failed the test after shrinking is
    /// complete.
    Fail(Fail<T, P::Error>),
}

/// Represents a successful test case.
#[derive(Clone, Debug, PartialEq)]
pub struct Pass<T, P> {
    /// The value that passed the test.
    pub item: T,
    /// The proof produced by the [`Prove`] implementation (e.g., `()` or the
    /// `Ok` variant of a `Result`).
    pub proof: P,
    /// The number of generations that occurred before this pass.
    pub generates: usize,
    /// The number of shrinks that occurred before this pass.
    pub shrinks: usize,
    /// The generator state that produced the item.
    pub state: State,
}

/// Represents a failed test case.
#[derive(Clone, Debug, PartialEq)]
pub struct Fail<T, E> {
    /// The value that failed the test.
    pub item: T,
    /// The reason for the failure.
    pub cause: Cause<E>,
    /// The number of generations that occurred before this failure.
    pub generates: usize,
    /// The number of shrinks that occurred before this failure.
    pub shrinks: usize,
    /// The generator state that produced the failing item.
    pub state: State,
}

/// The cause of a check failure.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum Cause<E> {
    /// The property was disproven by the test function's return value
    /// (e.g., it returned `false` or `Err`).
    Disprove(E),
    /// The test function panicked.
    Panic(Option<Cow<'static, str>>),
}

impl<T: PartialEq, P: Prove<Proof: PartialEq, Error: PartialEq>> PartialEq for Result<T, P> {
    fn eq(&self, other: &Self) -> bool {
        match (self, other) {
            (Self::Pass(left), Self::Pass(right)) => left == right,
            (Self::Shrink(left), Self::Shrink(right)) => left == right,
            (Self::Shrunk(left), Self::Shrunk(right)) => left == right,
            (Self::Fail(left), Self::Fail(right)) => left == right,
            _ => false,
        }
    }
}

impl<G: Generate + ?Sized> Check for G {}

impl<G: Generate> Checker<G, synchronous::Run> {
    pub(crate) const fn new(generator: G, seed: u64) -> Self {
        Self {
            generator,
            generate: Generates {
                items: true,
                count: GENERATES,
                seed,
                sizes: Sizes::DEFAULT,
                exhaustive: None,
            },
            shrink: Shrinks {
                count: SHRINKS,
                items: true,
                errors: true,
            },
            run: synchronous::Run,
        }
    }
}

impl<G: ?Sized, R> Checker<G, R> {
    #[doc(hidden)]
    pub fn verbose(&mut self, items: bool, errors: bool) {
        self.generate.items = items;
        self.shrink.items = items;
        self.shrink.errors = errors;
    }

    pub(crate) fn environment(&mut self) {
        self.variables(
            env::vars_os().filter_map(|(key, value)| {
                Some((key.into_string().ok()?, value.into_string().ok()?))
            }),
        )
    }

    pub(crate) fn variables<K: AsRef<str>, V: AsRef<str>, I: IntoIterator<Item = (K, V)>>(
        &mut self,
        variables: I,
    ) {
        for (key, value) in variables {
            match key.as_ref() {
                "CHECKITO_GENERATE_COUNT" => {
                    if let Ok(value) = value.as_ref().parse() {
                        self.generate.count = value;
                    }
                }
                "CHECKITO_GENERATE_SIZE" => {
                    if let Ok(value) = value.as_ref().parse() {
                        self.generate.sizes = (value..=value).into();
                    }
                }
                "CHECKITO_GENERATE_SEED" => {
                    if let Ok(value) = value.as_ref().parse() {
                        self.generate.seed = value;
                    }
                }
                "CHECKITO_GENERATE_ITEMS" => {
                    if let Ok(value) = value.as_ref().parse() {
                        self.generate.items = value;
                    }
                }
                "CHECKITO_GENERATE_EXHAUSTIVE" => {
                    if let Ok(value) = value.as_ref().parse() {
                        self.generate.exhaustive = Some(value);
                    }
                }
                "CHECKITO_SHRINK_COUNT" => {
                    if let Ok(value) = value.as_ref().parse() {
                        self.shrink.count = value;
                    }
                }
                "CHECKITO_SHRINK_ITEMS" => {
                    if let Ok(value) = value.as_ref().parse() {
                        self.shrink.items = value;
                    }
                }
                "CHECKITO_SHRINK_ERRORS" => {
                    if let Ok(value) = value.as_ref().parse() {
                        self.shrink.errors = value;
                    }
                }
                "CHECKITO_VERBOSE" => {
                    if let Ok(value) = value.as_ref().parse() {
                        self.verbose(value, value);
                    }
                }
                _ => {}
            }
        }
    }
}

impl<G, R> Checker<G, R> {
    fn with<S>(self, run: S) -> Checker<G, S> {
        Checker {
            generate: self.generate,
            shrink: self.shrink,
            generator: self.generator,
            run,
        }
    }
}

impl<T, P: Prove> Result<T, P> {
    /// Returns the seed used to generate the underlying value.
    pub const fn seed(&self) -> u64 {
        match self {
            Result::Pass(pass) | Result::Shrink(pass) => pass.seed(),
            Result::Fail(fail) | Result::Shrunk(fail) => fail.seed(),
        }
    }

    /// Returns the size used to generate the underlying value (`0.0..=1.0`).
    pub const fn size(&self) -> f64 {
        match self {
            Result::Pass(pass) | Result::Shrink(pass) => pass.size(),
            Result::Fail(fail) | Result::Shrunk(fail) => fail.size(),
        }
    }

    /// Returns the number of values generated before this result.
    pub const fn generates(&self) -> usize {
        match self {
            Result::Pass(pass) | Result::Shrink(pass) => pass.generates,
            Result::Fail(fail) | Result::Shrunk(fail) => fail.generates,
        }
    }

    /// Returns the number of shrink steps that occurred before this result.
    pub const fn shrinks(&self) -> usize {
        match self {
            Result::Pass(pass) | Result::Shrink(pass) => pass.shrinks,
            Result::Fail(fail) | Result::Shrunk(fail) => fail.shrinks,
        }
    }

    /// Returns the generator state that produced the underlying value.
    pub const fn state(&self) -> &State {
        match self {
            Result::Pass(pass) | Result::Shrink(pass) => &pass.state,
            Result::Fail(fail) | Result::Shrunk(fail) => &fail.state,
        }
    }

    /// Returns the inner [`Pass`] if this is a `Pass` result, or a `Shrink`
    /// result when `shrink` is `true`.
    pub fn pass(&self, shrink: bool) -> Option<&Pass<T, P::Proof>> {
        match self {
            Result::Pass(pass) => Some(pass),
            Result::Shrink(pass) if shrink => Some(pass),
            _ => None,
        }
    }

    /// Converts this result into the inner [`Pass`] if it is a `Pass` result,
    /// or a `Shrink` result when `shrink` is `true`. Returns `Err(self)`
    /// otherwise.
    #[allow(clippy::result_large_err)]
    pub fn into_pass(self, shrink: bool) -> result::Result<Pass<T, P::Proof>, Self> {
        match self {
            Result::Pass(pass) => Ok(pass),
            Result::Shrink(pass) if shrink => Ok(pass),
            result => Err(result),
        }
    }

    /// Returns the inner [`Fail`] if this is a `Fail` result, or a `Shrunk`
    /// result when `shrunk` is `true`.
    pub fn fail(&self, shrunk: bool) -> Option<&Fail<T, P::Error>> {
        match self {
            Result::Fail(fail) => Some(fail),
            Result::Shrunk(fail) if shrunk => Some(fail),
            _ => None,
        }
    }

    /// Converts this result into the inner [`Fail`] if it is a `Fail` result,
    /// or a `Shrunk` result when `shrunk` is `true`. Returns `Err(self)`
    /// otherwise.
    #[allow(clippy::result_large_err)]
    pub fn into_fail(self, shrunk: bool) -> result::Result<Fail<T, P::Error>, Self> {
        match self {
            Result::Fail(fail) => Ok(fail),
            Result::Shrunk(fail) if shrunk => Ok(fail),
            result => Err(result),
        }
    }

    /// Consumes this result and returns the underlying item.
    pub fn into_item(self) -> T {
        match self {
            Result::Pass(pass) | Result::Shrink(pass) => pass.item,
            Result::Fail(fail) | Result::Shrunk(fail) => fail.item,
        }
    }

    /// Converts this result into a standard [`result::Result`], where pass
    /// variants map to `Ok` and fail variants map to `Err`.
    #[allow(clippy::result_large_err)]
    pub fn into_result(self) -> result::Result<Pass<T, P::Proof>, Fail<T, P::Error>> {
        match self {
            Result::Pass(pass) | Result::Shrink(pass) => Ok(pass),
            Result::Fail(fail) | Result::Shrunk(fail) => Err(fail),
        }
    }
}

impl<T, P> Pass<T, P> {
    /// Returns the seed used to generate the value.
    pub const fn seed(&self) -> u64 {
        self.state.seed()
    }

    /// Returns the size used to generate the value (`0.0..=1.0`).
    pub const fn size(&self) -> f64 {
        self.state.size()
    }
}

impl<T, P> Fail<T, P> {
    /// Returns the seed used to generate the failing value.
    pub const fn seed(&self) -> u64 {
        self.state.seed()
    }

    /// Returns the size used to generate the failing value (`0.0..=1.0`).
    pub const fn size(&self) -> f64 {
        self.state.size()
    }

    /// Returns a human-readable description of the failure cause.
    ///
    /// - For a [`Cause::Panic`] with a message, returns that message.
    /// - For a [`Cause::Panic`] without a message, returns `"panicked"`.
    /// - For a [`Cause::Disprove`], returns the `Debug` representation of the
    ///   error.
    pub fn message(&self) -> Cow<'static, str>
    where
        P: Debug,
    {
        match &self.cause {
            Cause::Panic(Some(message)) => message.clone(),
            Cause::Panic(None) => "panicked".into(),
            Cause::Disprove(proof) => format!("{proof:?}").into(),
        }
    }
}

impl<T, P: Prove> Deref for Result<T, P> {
    type Target = T;

    fn deref(&self) -> &Self::Target {
        match self {
            Result::Pass(pass) | Result::Shrink(pass) => &pass.item,
            Result::Fail(fail) | Result::Shrunk(fail) => &fail.item,
        }
    }
}

impl<T, P: Prove> DerefMut for Result<T, P> {
    fn deref_mut(&mut self) -> &mut Self::Target {
        match self {
            Result::Pass(pass) | Result::Shrink(pass) => &mut pass.item,
            Result::Fail(fail) | Result::Shrunk(fail) => &mut fail.item,
        }
    }
}

impl<T, P: Prove> AsRef<T> for Result<T, P> {
    fn as_ref(&self) -> &T {
        match self {
            Result::Pass(pass) | Result::Shrink(pass) => &pass.item,
            Result::Fail(fail) | Result::Shrunk(fail) => &fail.item,
        }
    }
}

impl<T, P: Prove> AsMut<T> for Result<T, P> {
    fn as_mut(&mut self) -> &mut T {
        match self {
            Result::Pass(pass) | Result::Shrink(pass) => &mut pass.item,
            Result::Fail(fail) | Result::Shrunk(fail) => &mut fail.item,
        }
    }
}

impl<T, P> Deref for Pass<T, P> {
    type Target = T;

    fn deref(&self) -> &Self::Target {
        &self.item
    }
}

impl<T, P> DerefMut for Pass<T, P> {
    fn deref_mut(&mut self) -> &mut Self::Target {
        &mut self.item
    }
}

impl<T, P> AsRef<T> for Pass<T, P> {
    fn as_ref(&self) -> &T {
        &self.item
    }
}

impl<T, P> AsMut<T> for Pass<T, P> {
    fn as_mut(&mut self) -> &mut T {
        &mut self.item
    }
}

impl<T, P> Deref for Fail<T, P> {
    type Target = T;

    fn deref(&self) -> &Self::Target {
        &self.item
    }
}

impl<T, P> DerefMut for Fail<T, P> {
    fn deref_mut(&mut self) -> &mut Self::Target {
        &mut self.item
    }
}

impl<T, P> AsRef<T> for Fail<T, P> {
    fn as_ref(&self) -> &T {
        &self.item
    }
}

impl<T, P> AsMut<T> for Fail<T, P> {
    fn as_mut(&mut self) -> &mut T {
        &mut self.item
    }
}

impl<T: Debug, E: Debug> fmt::Display for Fail<T, E> {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        Debug::fmt(self, f)
    }
}

impl<T: Debug, E: Debug> error::Error for Fail<T, E> {}

const fn pass<T, P: Prove>(item: T, state: State, proof: P::Proof) -> Result<T, P> {
    Result::Pass(Pass {
        item,
        generates: state.index() + 1,
        shrinks: 0,
        proof,
        state,
    })
}

const fn fail<T, P: Prove>(
    item: T,
    index: usize,
    state: State,
    cause: Cause<P::Error>,
) -> Result<T, P> {
    Result::Fail(Fail {
        item,
        generates: state.index() + 1,
        shrinks: index,
        state,
        cause,
    })
}

const fn shrink<T, P: Prove>(item: T, index: usize, state: State, proof: P::Proof) -> Result<T, P> {
    Result::Shrink(Pass {
        item,
        generates: state.index() + 1,
        shrinks: index,
        proof,
        state,
    })
}

const fn shrunk<T, P: Prove>(
    item: T,
    index: usize,
    state: State,
    cause: Cause<P::Error>,
) -> Result<T, P> {
    Result::Shrunk(Fail {
        item,
        generates: state.index() + 1,
        shrinks: index,
        state,
        cause,
    })
}

fn catch<T, E, F: FnOnce() -> T>(run: F) -> result::Result<T, Cause<E>> {
    catch_unwind(AssertUnwindSafe(run)).map_err(|error| Cause::Panic(cast(error).ok()))
}

pub(crate) mod synchronous {
    use super::*;

    #[derive(Debug, Clone, Copy, Default)]
    pub struct Run;

    /// An iterator over the results of a property test.
    ///
    /// The iterator first enters a generation phase, where it produces values
    /// and runs the test against them.
    ///
    /// - If a check passes, it yields a [`Result::Pass`].
    /// - If a check fails, it enters the shrinking phase.
    ///
    /// In the shrinking phase, it repeatedly tries to simplify the failing
    /// value.
    ///
    /// - If a shrunk value passes the test, it yields a [`Result::Shrink`],
    ///   indicating that this simpler value did not reproduce the failure.
    /// - If a shrunk value fails the test, it yields a [`Result::Shrunk`], and
    ///   this new, simpler value becomes the one to be shrunk further.
    ///
    /// Once a value can no longer be shrunk, the iterator yields a final
    /// [`Result::Fail`] and then terminates.
    pub struct Iterator<G: Generate, P: Prove, C> {
        yields: Yields,
        check: C,
        machine: Machine<G, P>,
    }

    #[derive(Default)]
    enum Machine<G: Generate, P: Prove> {
        Generate {
            generator: G,
            states: States,
            shrinks: usize,
        },
        Shrink {
            state: State,
            shrinks: ops::Range<usize>,
            shrinker: G::Shrink,
            cause: Cause<P::Error>,
        },
        #[default]
        Done,
    }

    impl<G: Generate> Checker<G, Run> {
        #[cfg(feature = "asynchronous")]
        pub fn asynchronous(
            self,
            concurrency: Option<NonZeroUsize>,
        ) -> Checker<G, asynchronous::Run> {
            self.with(asynchronous::Run {
                concurrency: concurrency
                    .map_or_else(available_parallelism, Ok)
                    .unwrap_or(NonZeroUsize::MIN),
            })
        }

        pub fn check<P: Prove, C: FnMut(G::Item) -> P>(
            mut self,
            check: C,
        ) -> Option<Fail<G::Item, P::Error>> {
            self.generate.items = false;
            self.shrink.items = false;
            self.shrink.errors = false;
            self.checks(check).last()?.into_fail(false).ok()
        }

        pub fn checks<P: Prove, C: FnMut(G::Item) -> P>(self, check: C) -> Iterator<G, P, C> {
            let modes = Modes::with(
                self.generate.count,
                self.generate.sizes,
                self.generate.seed,
                self.generator.cardinality(),
                self.generate.exhaustive,
            );
            Iterator {
                check,
                yields: Yields {
                    passes: self.generate.items,
                    shrinks: self.shrink.items,
                    shrunks: self.shrink.errors,
                },
                machine: Machine::Generate {
                    generator: self.generator,
                    states: modes.into(),
                    shrinks: self.shrink.count,
                },
            }
        }
    }

    impl<G: Generate, P: Prove, C: FnMut(G::Item) -> P> iter::Iterator for Iterator<G, P, C> {
        type Item = Result<G::Item, P>;

        fn next(&mut self) -> Option<Self::Item> {
            loop {
                match take(&mut self.machine) {
                    Machine::Generate {
                        generator,
                        mut states,
                        shrinks,
                    } => {
                        let mut state = states.next()?;
                        let shrinker = generator.generate(&mut state);
                        match handle(shrinker.item(), &mut self.check) {
                            Ok(proof) => {
                                self.machine = Machine::Generate {
                                    generator,
                                    states,
                                    shrinks,
                                };
                                if self.yields.passes {
                                    break Some(pass(shrinker.item(), state, proof));
                                }
                            }
                            Err(cause) => {
                                self.machine = Machine::Shrink {
                                    state,
                                    shrinker,
                                    shrinks: 0..shrinks,
                                    cause,
                                };
                            }
                        }
                    }
                    Machine::Shrink {
                        state,
                        mut shrinks,
                        shrinker: mut old_shrinker,
                        cause: old_cause,
                    } => {
                        let index = shrinks.start;
                        let next = match shrinks.next() {
                            Some(index) => index,
                            None => break Some(fail(old_shrinker.item(), index, state, old_cause)),
                        };
                        let new_shrinker = match old_shrinker.shrink() {
                            Some(shrinker) => shrinker,
                            None => break Some(fail(old_shrinker.item(), index, state, old_cause)),
                        };
                        match handle(new_shrinker.item(), &mut self.check) {
                            Ok(proof) => {
                                self.machine = Machine::Shrink {
                                    state: state.clone(),
                                    shrinks,
                                    shrinker: old_shrinker,
                                    cause: old_cause,
                                };
                                if self.yields.shrinks {
                                    break Some(shrink(new_shrinker.item(), next, state, proof));
                                }
                            }
                            Err(new_cause) => {
                                self.machine = Machine::Shrink {
                                    state: state.clone(),
                                    shrinks,
                                    shrinker: new_shrinker,
                                    cause: new_cause,
                                };
                                if self.yields.shrunks {
                                    break Some(shrunk(
                                        old_shrinker.item(),
                                        next,
                                        state,
                                        old_cause,
                                    ));
                                }
                            }
                        }
                    }
                    Machine::Done => break None,
                }
            }
        }
    }

    fn handle<T, P: Prove, C: FnMut(T) -> P>(
        item: T,
        mut check: C,
    ) -> result::Result<P::Proof, Cause<P::Error>> {
        catch(move || check(item))?.prove().map_err(Cause::Disprove)
    }
}

#[cfg(feature = "asynchronous")]
pub(crate) mod asynchronous {
    //! Asynchronous property testing with concurrent execution.
    //!
    //! This module implements an asynchronous version of the property checker
    //! that can execute multiple test cases concurrently, controlled by the
    //! `concurrency` parameter.
    //!
    //! Up to `concurrency` futures are spawned and polled concurrently. The
    //! stream maintains strict FIFO ordering of results: even when futures
    //! complete out of order, results are yielded in the order they were
    //! generated/shrunk.
    use super::*;
    use core::{
        future::Future,
        pin::Pin,
        task::{Context, Poll, ready},
    };
    use futures_lite::{StreamExt, stream};
    use pin_project_lite::pin_project;

    #[derive(Debug, Clone, Copy)]
    pub struct Run {
        pub(crate) concurrency: NonZeroUsize,
    }

    pin_project! {
        /// An asynchronous stream over the results of a property test.
        ///
        /// The stream first enters a generation phase, where it produces values and
        /// runs the test against them concurrently (up to `concurrency` futures).
        ///
        /// - If a check passes, it yields a [`Result::Pass`].
        /// - If a check fails, it enters the shrinking phase.
        ///
        /// In the shrinking phase, it repeatedly tries to simplify the failing value.
        ///
        /// - If a shrunk value passes the test, it yields a [`Result::Shrink`],
        ///   indicating that this simpler value did not reproduce the failure.
        /// - If a shrunk value fails the test, it yields a [`Result::Shrunk`], and this
        ///   new, simpler value becomes the one to be shrunk further.
        ///
        /// Once a value can no longer be shrunk, the stream yields a final
        /// [`Result::Fail`] and then terminates.
        ///
        /// ## Ordering
        ///
        /// Results are always yielded in generation order, regardless of which futures
        /// complete first. This ensures deterministic behavior when using a fixed seed.
        pub struct Stream<G: Generate, P: Future<Output: Prove>, C> {
            yields: Yields,
            check: C,
            head: usize,
            tail: usize,
            shrinks: usize,
            machine: Machine<G, P::Output>,
            #[pin]
            entries: Box<[Entry<G::Shrink, P>]>,
        }
    }

    pin_project! {
        #[project = EntryProjection]
        #[derive(Default)]
        enum Entry<S: Shrink, P: Future<Output: Prove>> {
            #[default]
            Vacant,
            Proving {
                state: Option<State>,
                shrinker: Option<S>,
                #[pin]
                prove: P,
            },
            Resolved {
                state: Option<State>,
                shrinker: Option<S>,
                result: Option<result::Result<<P::Output as Prove>::Proof, Cause<<P::Output as Prove>::Error>>>,
            },
        }
    }

    enum Resolution<S: Shrink, P: Future<Output: Prove>> {
        Vacant {
            index: usize,
        },
        Proving,
        Resolved {
            index: usize,
            state: State,
            shrinker: S,
            result: result::Result<<P::Output as Prove>::Proof, Cause<<P::Output as Prove>::Error>>,
        },
    }

    #[derive(Default)]
    enum Machine<G: Generate, P: Prove> {
        Generate {
            generator: G,
            states: States,
        },
        Shrink {
            state: State,
            shrinker: G::Shrink,
            cause: Cause<P::Error>,
        },
        #[default]
        Done,
    }

    impl<G: Generate> Checker<G, Run> {
        pub fn synchronous(self) -> Checker<G, synchronous::Run> {
            self.with(synchronous::Run)
        }

        pub async fn check<P: Future<Output: Prove>, C: FnMut(G::Item) -> P>(
            mut self,
            check: C,
        ) -> Option<Fail<G::Item, <P::Output as Prove>::Error>> {
            self.generate.items = false;
            self.shrink.items = false;
            self.shrink.errors = false;
            self.checks(check).last().await?.into_fail(false).ok()
        }

        pub fn checks<P: Future<Output: Prove>, C: FnMut(G::Item) -> P>(
            self,
            check: C,
        ) -> Stream<G, P, C> {
            let modes = Modes::with(
                self.generate.count,
                self.generate.sizes,
                self.generate.seed,
                self.generator.cardinality(),
                self.generate.exhaustive,
            );
            Stream {
                yields: Yields {
                    passes: self.generate.items,
                    shrinks: self.shrink.items,
                    shrunks: self.shrink.errors,
                },
                head: 0,
                tail: 0,
                shrinks: self.shrink.count,
                entries: Iterator::map(0..self.run.concurrency.get(), |_| Entry::Vacant).collect(),
                machine: Machine::Generate {
                    generator: self.generator,
                    states: modes.into(),
                },
                check,
            }
        }
    }

    impl<G: Generate, P: Future<Output: Prove>, C: FnMut(G::Item) -> P> stream::Stream
        for Stream<G, P, C>
    {
        type Item = Result<G::Item, P::Output>;

        fn poll_next(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
            let mut this = self.project();
            loop {
                match take(this.machine) {
                    Machine::Generate {
                        generator,
                        mut states,
                    } => {
                        fill(
                            this.head,
                            this.tail,
                            this.entries.as_mut(),
                            &mut this.check,
                            |_| {
                                let mut state = states.next()?;
                                let shrinker = generator.generate(&mut state);
                                Some((shrinker, state))
                            },
                        );
                        poll(this.head, this.tail, this.entries.as_mut(), cx);
                        match resolve(this.head, this.entries.as_mut()) {
                            Resolution::Resolved {
                                state,
                                shrinker,
                                result,
                                ..
                            } => match result {
                                Ok(proof) => {
                                    *this.machine = Machine::Generate { generator, states };
                                    if this.yields.passes {
                                        break Poll::Ready(Some(pass(
                                            shrinker.item(),
                                            state,
                                            proof,
                                        )));
                                    }
                                }
                                Err(cause) => {
                                    *this.head = 0;
                                    *this.tail = 0;
                                    *this.machine = Machine::Shrink {
                                        state,
                                        shrinker,
                                        cause,
                                    };
                                }
                            },
                            Resolution::Proving => {
                                *this.machine = Machine::Generate { generator, states };
                                break Poll::Pending;
                            }
                            Resolution::Vacant { .. } => {}
                        }
                    }
                    Machine::Shrink {
                        state,
                        shrinker: mut old_shrinker,
                        cause: old_cause,
                    } => {
                        fill(
                            this.head,
                            this.tail,
                            this.entries.as_mut(),
                            &mut this.check,
                            |index| {
                                if index < *this.shrinks {
                                    let shrinker = old_shrinker.shrink()?;
                                    let state = state.clone();
                                    Some((shrinker, state))
                                } else {
                                    None
                                }
                            },
                        );
                        poll(this.head, this.tail, this.entries.as_mut(), cx);
                        match resolve(this.head, this.entries.as_mut()) {
                            Resolution::Resolved {
                                index,
                                state,
                                shrinker: new_shrinker,
                                result,
                            } => match result {
                                Ok(proof) => {
                                    *this.machine = Machine::Shrink {
                                        state: state.clone(),
                                        shrinker: old_shrinker,
                                        cause: old_cause,
                                    };
                                    if this.yields.shrinks {
                                        break Poll::Ready(Some(shrink(
                                            new_shrinker.item(),
                                            index,
                                            state,
                                            proof,
                                        )));
                                    }
                                }
                                Err(new_cause) => {
                                    *this.head = *this.tail;
                                    *this.machine = Machine::Shrink {
                                        state: state.clone(),
                                        shrinker: new_shrinker,
                                        cause: new_cause,
                                    };
                                    if this.yields.shrunks {
                                        break Poll::Ready(Some(shrunk(
                                            old_shrinker.item(),
                                            index,
                                            state,
                                            old_cause,
                                        )));
                                    }
                                }
                            },
                            Resolution::Proving => {
                                *this.machine = Machine::Shrink {
                                    state,
                                    shrinker: old_shrinker,
                                    cause: old_cause,
                                };
                                break Poll::Pending;
                            }
                            Resolution::Vacant { index } => {
                                break Poll::Ready(Some(fail(
                                    old_shrinker.item(),
                                    index,
                                    state,
                                    old_cause,
                                )));
                            }
                        }
                    }
                    Machine::Done => break Poll::Ready(None),
                }
            }
        }
    }

    fn get<S: Shrink, P: Future<Output: Prove>>(
        entries: Pin<&mut Box<[Entry<S, P>]>>,
        index: usize,
    ) -> Pin<&mut Entry<S, P>> {
        let count = entries.len();
        // SAFETY: `index % count` is always in bounds (assuming count > 0, which is
        // guaranteed by the caller since the buffer is allocated with at least one
        // slot). `Pin::map_unchecked_mut` is sound because the `Entry` values
        // inside the `Box<[Entry]>` are never moved — the `Box` itself may
        // move, but its contents stay at a stable address.
        unsafe { entries.map_unchecked_mut(|entries| &mut entries[index % count]) }
    }

    fn fill<
        S: Shrink,
        P: Future<Output: Prove>,
        C: FnMut(S::Item) -> P,
        N: FnMut(usize) -> Option<(S, State)>,
    >(
        head: &mut usize,
        tail: &mut usize,
        mut entries: Pin<&mut Box<[Entry<S, P>]>>,
        mut check: C,
        mut next: N,
    ) {
        while *tail - *head < entries.len() {
            match next(*tail) {
                Some((shrinker, state)) => {
                    let index = increment(tail);
                    let mut entry = get(entries.as_mut(), index);
                    entry.set(match prepare(shrinker.item(), &mut check) {
                        Ok(prove) => Entry::Proving {
                            state: Some(state.clone()),
                            shrinker: Some(shrinker),
                            prove,
                        },
                        Err(cause) => Entry::Resolved {
                            state: Some(state.clone()),
                            shrinker: Some(shrinker),
                            result: Some(Err(cause)),
                        },
                    });
                }
                None => break,
            }
        }
    }

    fn poll<S: Shrink, P: Future<Output: Prove>>(
        head: &mut usize,
        tail: &mut usize,
        mut entries: Pin<&mut Box<[Entry<S, P>]>>,
        context: &mut Context<'_>,
    ) {
        for index in *head..*tail {
            let mut entry = get(entries.as_mut(), index);
            match entry.as_mut().project() {
                EntryProjection::Proving {
                    state,
                    shrinker,
                    prove,
                } => {
                    if let Poll::Ready(result) = handle(prove, context) {
                        let state = state.take();
                        let shrinker = shrinker.take();
                        entry.set(Entry::Resolved {
                            state,
                            shrinker,
                            result: Some(result),
                        });
                    }
                }
                EntryProjection::Resolved { .. } => continue,
                EntryProjection::Vacant => break,
            }
        }
    }

    fn resolve<S: Shrink, P: Future<Output: Prove>>(
        head: &mut usize,
        mut entries: Pin<&mut Box<[Entry<S, P>]>>,
    ) -> Resolution<S, P> {
        let mut entry = get(entries.as_mut(), *head);
        match entry.as_mut().project() {
            EntryProjection::Resolved {
                state,
                shrinker,
                result,
            } => {
                let index = increment(head);
                let Some(state) = state.take() else {
                    return Resolution::Vacant { index };
                };
                let Some(shrinker) = shrinker.take() else {
                    return Resolution::Vacant { index };
                };
                let Some(result) = result.take() else {
                    return Resolution::Vacant { index };
                };
                entry.set(Entry::Vacant);
                Resolution::Resolved {
                    index,
                    shrinker,
                    state,
                    result,
                }
            }
            EntryProjection::Vacant => Resolution::Vacant { index: *head },
            EntryProjection::Proving { .. } => Resolution::Proving,
        }
    }

    fn increment(value: &mut usize) -> usize {
        let old = *value;
        *value += 1;
        old
    }

    fn prepare<T, P: Future<Output: Prove>, C: FnMut(T) -> P>(
        item: T,
        mut check: C,
    ) -> result::Result<P, Cause<<P::Output as Prove>::Error>> {
        catch(move || check(item))
    }

    #[allow(clippy::type_complexity)]
    fn handle<P: Future<Output: Prove>>(
        prove: Pin<&mut P>,
        context: &mut Context,
    ) -> Poll<result::Result<<P::Output as Prove>::Proof, Cause<<P::Output as Prove>::Error>>> {
        Poll::Ready(
            ready!(catch(move || prove.poll(context))?)
                .prove()
                .map_err(Cause::Disprove),
        )
    }
}