code_ownership 2.1.3 → 2.2.0

data/ext/cargo-vendor/{error-stack-0.5.0 → error-stack-0.8.0}/src/lib.rs

@@ -2,13 +2,11 @@
 //!
 //! [![crates.io](https://img.shields.io/crates/v/error-stack)][crates.io]
 //! [![libs.rs](https://img.shields.io/badge/libs.rs-error--stack-orange)][libs.rs]
-//! [![rust-version](https://img.shields.io/static/v1?label=Rust&message=1.63.0/nightly-2024-07-08&color=blue)][rust-version]
-//! [![discord](https://img.shields.io/discord/840573247803097118)][discord]
+//! [![rust-version](https://img.shields.io/static/v1?label=Rust&message=1.83.0/nightly-2026-06-08&color=blue)][rust-version]
 //!
 //! [crates.io]: https://crates.io/crates/error-stack
 //! [libs.rs]: https://lib.rs/crates/error-stack
 //! [rust-version]: https://www.rust-lang.org
-//! [discord]: https://hash.ai/discord?utm_medium=organic&utm_source=github_readme_hash-repo_error-stack
 //!
 //! # Overview
 //!
@@ -18,10 +16,10 @@
 //!   1. Contexts
 //!   2. Attachments
 //!
-//! A [`Context`] is a view of the world, it helps describe how the current section of code
-//! interprets the error. This is used to capture how various scopes require differing levels of
-//! detail and understanding of the error as it propagates. A [`Report`] always captures the
-//! _current context_ in its generic argument.
+//! A context is a view of the world, it helps describe how the current section of code interprets
+//! the error. This is used to capture how various scopes require differing levels of detail and
+//! understanding of the error as it propagates. A [`Report`] always captures the _current context_
+//! in its generic argument.
 //!
 //! As the [`Report`] is built, various pieces of supporting information can be _attached_. These
 //! can be anything that can be shared between threads whether it be a supporting message or a
@@ -33,7 +31,7 @@
 //!
 //! ```rust
 //! # #![allow(dead_code)]
-//! use error_stack::ResultExt;
+//! use error_stack::{Report, ResultExt};
 //! // using `thiserror` is not neccessary, but convenient
 //! use thiserror::Error;
 //!
@@ -47,14 +45,14 @@
 //!     Trivial,
 //! }
 //!
-//! type AppResult<T> = error_stack::Result<T, AppError>;
+//! type AppResult<T> = Result<T, Report<AppError>>;
 //!
 //! // Errors can also be a plain `struct`, somewhat like in `anyhow`.
 //! #[derive(Error, Debug)]
 //! #[error("logic error")]
 //! struct LogicError;
 //!
-//! type LogicResult<T> = error_stack::Result<T, LogicError>;
+//! type LogicResult<T> = Result<T, Report<LogicError>>;
 //!
 //! fn do_logic() -> LogicResult<()> {
 //!     Ok(())
@@ -73,9 +71,7 @@
 //!
 //! ## Where to use a Report
 //!
-//! [`Report`] has been designed to be used as the [`Err`] variant of a `Result`. This crate
-//! provides a [`Result<E, C>`] type alias for convenience which uses [`Report<C>`] as the [`Err`]
-//! variant and can be used as a return type:
+//! [`Report`] has been designed to be used as the [`Err`] variant of a [`Result`]:
 //!
 //! ```rust
 //! # fn has_permission(_: (), _: ()) -> bool { true }
@@ -85,10 +81,10 @@
 //! # impl core::fmt::Display for AccessError {
 //! #    fn fmt(&self, _: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { Ok(()) }
 //! # }
-//! # impl error_stack::Context for AccessError {}
-//! use error_stack::{ensure, Result};
+//! # impl core::error::Error for AccessError {}
+//! use error_stack::{ensure, Report};
 //!
-//! fn main() -> Result<(), AccessError> {
+//! fn main() -> Result<(), Report<AccessError>> {
 //!     let user = get_user()?;
 //!     let resource = get_resource()?;
 //!
@@ -105,10 +101,9 @@
 //!
 //! ### Initializing a Report
 //!
-//! A [`Report`] can be created directly from anything that implements [`Context`] by using
-//! [`Report::new()`] or through any of the provided macros ([`report!`], [`bail!`], [`ensure!`]).
-//! Any [`Error`] can be used as a [`Context`], so it's possible to create [`Report`] from an
-//! existing [`Error`]:
+//! A [`Report`] can be created directly from anything that implements [`Error`] by using
+//! [`Report::new()`], [`IntoReport::into_report()`], or through any of the provided macros
+//! ([`bail!`], [`ensure!`]).
 //!
 //! ```rust
 //! use std::{fs, io, path::Path};
@@ -135,18 +130,20 @@
 //! ### Changing Context
 //!
 //! The generic parameter in [`Report`] is called the _current context_. When creating a new
-//! [`Report`], the [`Context`] that's provided will be set as the current context. The current
+//! [`Report`], the [`Error`] that's provided will be set as the current context. The current
 //! context should encapsulate how the current code interprets the error. As the error propagates,
 //! it will cross boundaries where new information is available, and the previous level of detail is
 //! no longer applicable. These boundaries will often occur when crossing between major modules, or
 //! when execution crosses between crates. At this point the [`Report`] should start to operate in a
 //! new context. To change the context, [`Report::change_context()`] is used:
 //!
-//! (Again, for convenience, using [`ResultExt`] will do that on the [`Err`] variant)
+//! (Again, for convenience, using [`ResultExt`] will do that on the [`Err`] variant.)
 //!
 //! ```rust
 //! # use std::{fmt, fs, io, path::Path};
-//! use error_stack::{Context, Result, ResultExt};
+//! use core::error::Error;
+//!
+//! use error_stack::{Report, ResultExt};
 //! # pub type Config = String;
 //!
 //! #[derive(Debug)]
@@ -159,10 +156,10 @@
 //! }
 //!
 //! // It's also possible to implement `Error` instead.
-//! impl Context for ParseConfigError {}
+//! impl Error for ParseConfigError {}
 //!
 //! // For clarification, this example is not using `error_stack::Result`.
-//! fn parse_config(path: impl AsRef<Path>) -> Result<Config, ParseConfigError> {
+//! fn parse_config(path: impl AsRef<Path>) -> Result<Config, Report<ParseConfigError>> {
 //!     let content = fs::read_to_string(path.as_ref())
 //!         .change_context(ParseConfigError)?;
 //!
@@ -180,13 +177,13 @@
 //! Module/crate boundaries are not the only places where information can be embedded within the
 //! [`Report`] however. Additional information can be attached within the current context, whether
 //! this be a string, or any thread-safe object. These attachments are added by using
-//! [`Report::attach()`] and [`Report::attach_printable()`]:
+//! [`Report::attach_opaque()`] and [`Report::attach()`]:
 //!
 //! ```rust
 //! # // we only test the snapshot on nightly, therefore report is unused (so is render)
 //! # #![cfg_attr(not(nightly), allow(dead_code, unused_variables, unused_imports))]
 //! # use std::{fs, path::Path};
-//! # use error_stack::{Context, Report, ResultExt};
+//! # use error_stack::{Report, ResultExt};
 //! # pub type Config = String;
 //! # #[derive(Debug)] struct ParseConfigError;
 //! # impl ParseConfigError { pub fn new() -> Self { Self } }
@@ -195,7 +192,7 @@
 //! #         fmt.write_str("could not parse configuration file")
 //! #     }
 //! # }
-//! # impl Context for ParseConfigError {}
+//! # impl core::error::Error for ParseConfigError {}
 //! # #[derive(Debug, PartialEq)]
 //! struct Suggestion(&'static str);
 //!
@@ -204,8 +201,8 @@
 //!
 //!     let content = fs::read_to_string(path)
 //!         .change_context(ParseConfigError::new())
-//!         .attach(Suggestion("use a file you can read next time!"))
-//!         .attach_printable_lazy(|| format!("could not read file {path:?}"))?;
+//!         .attach_opaque(Suggestion("use a file you can read next time!"))
+//!         .attach_with(|| format!("could not read file {path:?}"))?;
 //!
 //!     Ok(content)
 //! }
@@ -234,42 +231,54 @@
 //! ```
 //!
 //! As seen above, there are ways on attaching more information to the [`Report`]: [`attach`] and
-//! [`attach_printable`]. These two functions behave similar, but the latter has a more restrictive
+//! [`attach_opaque`]. These two functions behave similar, but the former has a more restrictive
 //! bound on the attachment: [`Display`] and [`Debug`]. Depending on the function used, printing the
 //! [`Report`] will also use the [`Display`] and [`Debug`] traits to describe the attachment.
 //!
 //! This outputs something like:
 //!
 //! <pre>
-#![doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/tests/snapshots/doc/lib__suggestion.snap"))]
+#![cfg_attr(doc, doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/tests/snapshots/doc/lib__suggestion.snap")))]
 //! </pre>
 //!
 //! The `Suggestion` which was added via [`attach`] is not shown directly and only increases the
-//! counter of opaque attachments for the containing [`Context`]. The message which was passed to
-//! [`attach_printable`], however, is displayed in full. To be able to show attachments that have
+//! counter of opaque attachments for the containing [`Error`]. The message which was passed to
+//! [`attach_opaque`], however, is displayed in full. To be able to show attachments that have
 //! been added via [`attach`], one must make use of [hooks](#debug-and-display-hooks) instead.
 //!
-//! [`attach_printable`]: Report::attach_printable
+//! [`attach_opaque`]: Report::attach_opaque
 //! [`Display`]: core::fmt::Display
 //! [`Debug`]: core::fmt::Debug
 //!
 //! ### Multiple Errors
 //!
-//! [`Report`] supports the combination and propagation of multiple errors natively. This is useful
-//! in cases like parallel processing where multiple errors might happen independently from each
-//! other, in these use-cases you are able to use the implementations of [`Extend`] and
-//! [`extend_one()`] and are able to propagate all errors instead of just a single one.
+//! [`Report`] provides native support for combining and propagating multiple errors. This feature
+//! is particularly useful in scenarios such as parallel processing, where multiple errors might
+//! occur independently. In these cases, you can utilize the [`Extend`] trait implementation and the
+//! [`push()`] method to aggregate and propagate all encountered errors, rather than just a single
+//! one.
+//!
+//! error-stack is designed to be explicit about the presence of single or multiple current
+//! contexts. This distinction is reflected in the generic type parameter:
+//!
+//! - [`Report<C>`] indicates that a single current context is present.
+//! - [`Report<[C]>`](Report) signifies that at least one current context is present, with the
+//!   possibility of multiple contexts.
 //!
-//! [`extend_one()`]: Report::extend_one
+//! You can seamlessly convert between these representations using [`Report::expand`] to transform
+//! a single-context report into a multi-context one. Using [`Report::change_context`] will
+//! transform a [`Report<[C]>`](Report) to a [`Report<C2>`], where `C2` is a new context type.
+//!
+//! [`push()`]: Report::push
 //!
 //! ```rust
 //! # use std::{fs, path::Path};
 //! # use error_stack::Report;
 //! # pub type Config = String;
 //!
-//! fn parse_configs(paths: &[impl AsRef<Path>]) -> Result<Vec<Config>, Report<std::io::Error>> {
+//! fn parse_configs(paths: &[impl AsRef<Path>]) -> Result<Vec<Config>, Report<[std::io::Error]>> {
 //!     let mut configs = Vec::new();
-//!     let mut error: Option<Report<std::io::Error>> = None;
+//!     let mut error: Option<Report<[std::io::Error]>> = None;
 //!
 //!     for path in paths {
 //!         let path = path.as_ref();
@@ -280,9 +289,9 @@
 //!             }
 //!             Err(err) => {
 //!                 if let Some(error) = error.as_mut() {
-//!                     error.extend_one(err.into());
+//!                     error.push(Report::from(err));
 //!                 } else {
-//!                     error = Some(err.into());
+//!                     error = Some(Report::from(err).expand());
 //!                 }
 //!             }
 //!         }
@@ -313,9 +322,9 @@
 //! well-defined type forces users to be conscious about how they classify and group their
 //! **custom** error types, which improves their usability in error-_handling_.
 //!
-//! ### Improving Result::Err Types
+//! ### Improving `Result::Err` Types
 //!
-//! By capturing the current [`Context`] in the type parameter, return types in function signatures
+//! By capturing the current [`Error`] in the type parameter, return types in function signatures
 //! continue to explicitly capture the perspective of the current code. This means that **more often
 //! than not** the user is _forced_ to re-describe the error when entering a substantially different
 //! part of the code because the constraints of typed return types will require it. This will happen
@@ -329,9 +338,8 @@
 //!
 //! ### Compatibility with other Libraries
 //!
-//! In `std` (or `nightly`) environments a blanket implementation for `Context` for any `Error` is
-//! provided. This blanket implementation for [`Error`] means `error-stack` is compatible with
-//! almost all other libraries that use the [`Error`] trait.
+//! `error-stack` uses the standard [`Error`] type which makes it compatible with almost all other
+//! libraries that use that trait.
 //!
 //! This has the added benefit that migrating from other error libraries can often be incremental,
 //! as a lot of popular error library types will work within the [`Report`] struct.
@@ -341,17 +349,16 @@
 //!
 //! ### Doing more
 //!
-//! Beyond making new [`Context`] types, the library supports the attachment of arbitrary
-//! thread-safe data. These attachments (and data that is [`provide`]d by the [`Context`] can be
+//! Beyond making new [`Error`] types, the library supports the attachment of arbitrary
+//! thread-safe data. These attachments (and data that is [`provide`]d by the [`Error`] can be
 //! requested through [`Report::request_ref()`]. This gives a novel way to expand standard
 //! error-handling approaches, without decreasing the ergonomics of creating the actual error
 //! variants:
 //!
 //! ```rust
 //! # #![cfg_attr(not(nightly), allow(unused_variables, dead_code))]
-//! # use error_stack::Result;
 //! # struct Suggestion(&'static str);
-//! # fn parse_config(_: &str) -> Result<(), std::io::Error> { Ok(()) }
+//! # fn parse_config(_: &str) -> Result<(), error_stack::Report<std::io::Error>> { Ok(()) }
 //! fn main() {
 //!     if let Err(report) = parse_config("config.json") {
 //!         # #[cfg(nightly)]
@@ -362,7 +369,7 @@
 //! }
 //! ```
 //!
-//! [`provide`]: Context::provide
+//! [`provide`]: core::error::Error::provide
 //!
 //! ## Additional Features
 //!
@@ -371,10 +378,10 @@
 //!
 //! ### Automatic Backtraces
 //!
-//! When on a Rust 1.65 or later, [`Report`] will try to capture a [`Backtrace`] if `RUST_BACKTRACE`
-//! or `RUST_BACKTRACE_LIB` is set and the `backtrace` feature is enabled (by default this is the
-//! case). If on a nightly toolchain, it will use the [`Backtrace`] if provided by the base
-//! [`Context`], and will try to capture one otherwise.
+//! [`Report`] will try to capture a [`Backtrace`] if `RUST_BACKTRACE` or `RUST_LIB_BACKTRACE` is
+//! set and the `backtrace` feature is enabled (by default this is the case). If on a nightly
+//! toolchain, it will use the [`Backtrace`] if provided by the base [`Error`], and will try to
+//! capture one otherwise.
 //!
 //! Unlike some other approaches, this does not require the user modifying their custom error types
 //! to be aware of backtraces, and doesn't require manual implementations to forward calls down any
@@ -388,9 +395,7 @@
 //! ### Provider API
 //!
 //! This crate uses the [`Provider` API] to provide arbitrary data. This can be done either by
-//! [`attach`]ing them to a [`Report`] or by providing it directly when implementing [`Context`].
-//! The blanket implementation of [`Context`] for [`Error`] will provide any data provided by
-//! [`Error::provide`].
+//! [`attach`]ing them to a [`Report`] or by providing it directly when implementing [`Error`].
 //!
 //! To request a provided type, [`Report::request_ref`] or [`Report::request_value`] are used. Both
 //! return an iterator of all provided values with the specified type. The value, which was provided
@@ -401,14 +406,10 @@
 //!
 //! ### Macros for Convenience
 //!
-//! Three macros are provided to simplify the generation of a [`Report`].
+//! Two macros are provided to simplify the generation of a [`Report`].
 //!
-//! - [`report!`] will only create a [`Report`] from its parameter. It will take into account if the
-//!   passed type itself is a [`Report`] or a [`Context`]. For the former case, it will retain the
-//!   details stored on a [`Report`], for the latter case it will create a new [`Report`] from the
-//!   [`Context`].
-//! - [`bail!`] acts like [`report!`] but also immediately returns the [`Report`] as [`Err`]
-//!   variant.
+//! - [`bail!`] acts like calling [`IntoReport::into_report()`] but also immediately returns the
+//!   [`Report`] as [`Err`] variant.
 //! - [`ensure!`] will check an expression and if it's evaluated to `false`, it will act like
 //!   [`bail!`].
 //!
@@ -416,7 +417,7 @@
 //!
 //! The crate comes with built-in support for `tracing`s [`SpanTrace`]. If the `spantrace` feature
 //! is enabled and an [`ErrorLayer`] is set, a [`SpanTrace`] is either used when provided by the
-//! root [`Context`] or will be captured when creating the [`Report`].
+//! root [`Error`] or will be captured when creating the [`Report`].
 //!
 //! [`ErrorLayer`]: tracing_error::ErrorLayer
 //!
@@ -432,8 +433,8 @@
 //!
 //! ### Additional Adaptors
 //!
-//! [`ResultExt`] is a convenient wrapper around `Result<_, impl Context>` and `Result<_,
-//! Report<impl Context>`. It offers [`attach`](ResultExt::attach) and
+//! [`ResultExt`] is a convenient wrapper around `Result<_, impl Error>` and `Result<_, Report<impl
+//! Error>`. It offers [`attach`](ResultExt::attach) and
 //! [`change_context`](ResultExt::change_context) on the [`Result`] directly, but also a lazy
 //! variant that receives a function which is only called if an error happens.
 //!
@@ -462,29 +463,32 @@
 //! `serde`        | Enables serialization support for [`Report`]                        | disabled
 //! `anyhow`       | Provides `into_report` to convert [`anyhow::Error`] to [`Report`]   | disabled
 //! `eyre`         | Provides `into_report` to convert [`eyre::Report`] to [`Report`]    | disabled
+//! `futures`      | Enables support for [`Stream`], requires `unstable`                 | disabled
+//! `unstable`     | Enables unstable features, these features are not covered by semver | disabled
 //!
 //!
-//! [`set_debug_hook`]: Report::set_debug_hook
-//!
 //! [`Error`]: core::error::Error
 //! [`Error::provide`]: core::error::Error::provide
 //! [`Backtrace`]: std::backtrace::Backtrace
 //! [`Display`]: core::fmt::Display
 //! [`Debug`]: core::fmt::Debug
 //! [`SpanTrace`]: tracing_error::SpanTrace
+//! [`Stream`]: futures_core::Stream
 #![cfg_attr(not(feature = "std"), no_std)]
-#![cfg_attr(
-    nightly,
-    feature(error_generic_member_access),
-    allow(clippy::incompatible_msrv)
-)]
-#![cfg_attr(all(doc, nightly), feature(doc_auto_cfg))]
-#![cfg_attr(all(nightly, feature = "std"), feature(backtrace_frames))]
+#![cfg_attr(nightly, feature(error_generic_member_access))]
+#![cfg_attr(all(nightly, feature = "unstable"), feature(try_trait_v2))]
+#![cfg_attr(all(doc, nightly), feature(doc_cfg))]
+#![cfg_attr(all(nightly, feature = "backtrace"), feature(backtrace_frames))]
 #![cfg_attr(
     not(miri),
-    doc(test(attr(deny(warnings, clippy::pedantic, clippy::nursery))))
+    doc(test(attr(
+        deny(warnings, clippy::pedantic, clippy::nursery),
+        allow(exported_private_dependencies)
+    )))
 )]
 #![allow(unsafe_code)]
+// There is a false positive for the badge
+#![allow(clippy::doc_paragraphs_missing_punctuation)]
 // This is an error handling library producing Results, not Errors
 #![allow(clippy::missing_errors_doc)]
 
@@ -501,25 +505,33 @@ mod result;
 
 mod context;
 mod error;
+#[cfg(feature = "unstable")]
+pub mod ext;
 pub mod fmt;
 #[cfg(any(feature = "std", feature = "hooks"))]
 mod hook;
 #[cfg(feature = "serde")]
 mod serde;
+#[cfg(feature = "unstable")]
+mod sink;
 
+#[cfg(all(feature = "unstable", feature = "futures"))]
+pub use self::ext::stream::TryReportStreamExt;
+#[cfg(feature = "unstable")]
+pub use self::ext::{iter::TryReportIteratorExt, tuple::TryReportTupleExt};
+#[cfg(feature = "unstable")]
+pub use self::sink::ReportSink;
 pub use self::{
     compat::IntoReportCompat,
-    context::Context,
+    context::{Attachment, OpaqueAttachment},
     frame::{AttachmentKind, Frame, FrameKind},
-    macros::*,
-    report::Report,
-    result::Result,
+    report::{IntoReport, Report},
 };
 #[doc(inline)]
 pub use self::{future::FutureExt, result::ResultExt};
 
 #[cfg(test)]
-#[allow(dead_code)]
+#[expect(dead_code)]
 mod tests {
 
     use core::mem;
@@ -539,7 +551,7 @@ mod tests {
     }
 
     #[test]
-    fn test_size() {
+    fn size() {
         assert_eq!(mem::size_of::<Report<()>>(), mem::size_of::<*const ()>());
     }
 }

data/ext/cargo-vendor/error-stack-0.8.0/src/macros.rs

@@ -0,0 +1,212 @@
+/// Creates a [`Report`] and returns it as [`Result`].
+///
+/// Shorthand for `return Err(report!(..))`.
+///
+/// [`Report`]: crate::Report
+/// [`report!(...)`]: report
+///
+/// # Examples
+///
+/// Create a [`Report`] from [`Error`]:
+///
+/// [`Error`]: core::error::Error
+///
+/// ```
+/// use std::fs;
+///
+/// use error_stack::bail;
+/// # fn wrapper() -> error_stack::Result<(), impl core::fmt::Debug> {
+/// match fs::read_to_string("/path/to/file") {
+///     Ok(content) => println!("file contents: {content}"),
+///     Err(err) => bail!(err),
+/// }
+/// # Ok(()) }
+/// # assert!(wrapper().unwrap_err().contains::<std::io::Error>());
+/// ```
+///
+/// Create a [`Report`] from [`Context`]:
+///
+/// [`Context`]: crate::Context
+///
+/// ```rust
+/// # fn has_permission(_: &u32, _: &u32) -> bool { true }
+/// # type User = u32;
+/// # let user = 0;
+/// # type Resource = u32;
+/// # let resource = 0;
+/// use core::fmt;
+///
+/// use error_stack::{bail, Context};
+///
+/// #[derive(Debug)]
+/// # #[allow(dead_code)]
+/// struct PermissionDenied(User, Resource);
+///
+/// impl fmt::Display for PermissionDenied {
+///     # #[allow(unused_variables)]
+///     fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
+///         # const _: &str = stringify! {
+///         ...
+///         # }; Ok(())}
+/// }
+///
+/// impl Context for PermissionDenied {}
+///
+/// if !has_permission(&user, &resource) {
+///     bail!(PermissionDenied(user, resource));
+/// }
+/// # Ok(())
+/// ```
+#[cfg(not(feature = "unstable"))]
+#[macro_export]
+macro_rules! bail {
+    ($err:expr $(,)?) => {{
+        return ::core::result::Result::Err($crate::IntoReport::into_report($err));
+    }};
+
+    [$($err:expr),+ $(,)?] => {{
+        compile_error!("enable the `unstable` feature flag to use `bail` to create multiple errors")
+    }};
+}
+
+/// Creates a [`Report`] and returns it as [`Result`].
+///
+/// [`Report`]: crate::Report
+///
+/// # `unstable`
+///
+/// The match arm: `[$($err:expr),+ $(,)?]` is considered unstable and can be used to construct a
+/// `Report<[C]>`.
+///
+/// # Examples
+///
+/// Create a [`Report`] from [`Error`]:
+///
+/// [`Error`]: core::error::Error
+///
+/// ```
+/// use std::fs;
+///
+/// use error_stack::bail;
+/// # fn wrapper() -> Result<(), error_stack::Report<impl core::fmt::Debug>> {
+/// match fs::read_to_string("/path/to/file") {
+///     Ok(content) => println!("file contents: {content}"),
+///     Err(err) => bail!(err),
+/// }
+/// # Ok(()) }
+/// # assert!(wrapper().unwrap_err().contains::<std::io::Error>());
+/// ```
+///
+/// Create a `Report<[C]>` from multiple errors (**unstable only**):
+///
+/// ```rust
+/// # fn has_permission(_: &u32, _: &u32) -> bool { true }
+/// # type User = u32;
+/// # let user = 0;
+/// # type Resource = u32;
+/// # let create_user = 0;
+/// # let create_resource = 0;
+/// use error_stack::bail;
+///
+/// #[derive(Debug)]
+/// # #[allow(dead_code)]
+/// struct PermissionDenied(User, Resource);
+///
+/// impl core::fmt::Display for PermissionDenied {
+///    # #[allow(unused_variables)]
+///     fn fmt(&self, fmt: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
+///         # const _: &str = stringify! {
+///         ...
+///         # }; Ok(())
+///     }
+/// }
+///
+/// impl core::error::Error for PermissionDenied {}
+///
+/// // You might want to look into `ReportSink` for a more incremental approach.
+/// if !has_permission(&user, &create_user) && !has_permission(&user, &create_resource) {
+///     bail![
+///         PermissionDenied(user, create_user),
+///         PermissionDenied(user, create_resource)
+///     ];
+/// }
+/// # Ok(())
+/// ```
+#[cfg(feature = "unstable")]
+#[cfg_attr(doc, doc(cfg(all())))]
+#[macro_export]
+macro_rules! bail {
+    ($err:expr $(,)?) => {{
+        return ::core::result::Result::Err($crate::IntoReport::into_report($err));
+    }};
+
+    [$($err:expr),+ $(,)?] => {{
+        let mut sink = $crate::ReportSink::new();
+
+        $(
+            sink.capture($err);
+        )+
+
+        let error = match sink.finish() {
+            Ok(()) => unreachable!(),
+            Err(error) => error,
+        };
+
+        return ::core::result::Result::Err(error);
+    }};
+}
+
+/// Ensures `$cond` is met, otherwise return an error.
+///
+/// Shorthand for <code>if !$cond { [bail!(..)]) }</code>
+///
+/// [`Report`]: crate::Report
+/// [bail!(..)]: bail
+///
+/// # Examples
+///
+/// Create a [`Report`] from an [`Error`]:
+///
+/// [`Error`]: core::error::Error
+///
+/// ```rust
+/// # fn has_permission(_: &u32, _: &u32) -> bool { true }
+/// # type User = u32;
+/// # let user = 0;
+/// # type Resource = u32;
+/// # let resource = 0;
+/// use core::error::Error;
+/// use core::fmt;
+///
+/// use error_stack::ensure;
+///
+/// #[derive(Debug)]
+/// # #[allow(dead_code)]
+/// struct PermissionDenied(User, Resource);
+///
+/// impl fmt::Display for PermissionDenied {
+///     # #[allow(unused_variables)]
+///     fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
+///         # const _: &str = stringify! {
+///         ...
+///         # };
+///         Ok(())
+///     }
+/// }
+///
+/// impl Error for PermissionDenied {}
+///
+/// ensure!(
+///     has_permission(&user, &resource),
+///     PermissionDenied(user, resource)
+/// );
+/// # Ok(())
+/// ```
+#[macro_export]
+macro_rules! ensure {
+    ($cond:expr, $err:expr $(,)?) => {{
+        if !bool::from($cond) {
+            $crate::bail!($err)
+        }
+    }};
+}