code_ownership 2.1.4 → 2.2.0

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

@@ -1,56 +1,56 @@
-#[cfg_attr(feature = "std", allow(unused_imports))]
 use alloc::{boxed::Box, vec, vec::Vec};
-#[cfg(rust_1_81)]
-use core::error::Error;
-use core::{fmt, marker::PhantomData, mem, panic::Location};
+use core::{error::Error, marker::PhantomData, mem, ops::ControlFlow, panic::Location};
 #[cfg(feature = "backtrace")]
 use std::backtrace::{Backtrace, BacktraceStatus};
-#[cfg(all(feature = "std", not(rust_1_81)))]
-use std::error::Error;
 #[cfg(feature = "std")]
 use std::process::ExitCode;
 
 #[cfg(feature = "spantrace")]
 use tracing_error::{SpanTrace, SpanTraceStatus};
 
-#[cfg(any(feature = "std", rust_1_81))]
-use crate::context::SourceContext;
 #[cfg(nightly)]
 use crate::iter::{RequestRef, RequestValue};
 use crate::{
-    iter::{Frames, FramesMut},
-    Context, Frame,
+    Attachment, Frame, OpaqueAttachment,
+    context::SourceContext,
+    iter::{self, Frames},
 };
 
-/// Contains a [`Frame`] stack consisting of [`Context`]s and attachments.
+/// Contains a [`Frame`] stack consisting of [`Error`] contexts and attachments.
 ///
-/// Attachments can be added by using [`attach()`]. The [`Frame`] stack can be iterated by using
-/// [`frames()`].
+/// Attachments can be added by using [`attach_opaque()`]. The [`Frame`] stack can be iterated by
+/// using [`frames()`].
 ///
-/// When creating a `Report` by using [`new()`], the passed [`Context`] is used to set the _current
-/// context_ on the `Report`. To provide a new one, use [`change_context()`].
+/// When creating a `Report` by using [`new()`], the passed [`Error`] context is used to set the
+/// _current context_ on the `Report`. To provide a new one, use [`change_context()`].
 ///
-/// Attachments, and objects [`provide`]d by a [`Context`], are directly retrievable by calling
-/// [`request_ref()`] or [`request_value()`].
+/// Attachments, and objects [`provide`]d by a [`Error`] context, are directly retrievable by
+/// calling [`request_ref()`] or [`request_value()`].
 ///
 /// ## Formatting
 ///
 /// `Report` implements [`Display`] and [`Debug`]. When utilizing the [`Display`] implementation,
 /// the current context of the `Report` is printed, e.g. `println!("{report}")`. For the alternate
-/// [`Display`] output (`"{:#}"`), all [`Context`]s are printed. To print the full stack of
-/// [`Context`]s and attachments, use the [`Debug`] implementation (`"{:?}"`). To customize the
-/// output of the attachments in the [`Debug`] output, please see the [`error_stack::fmt`] module.
+/// [`Display`] output (`"{:#}"`), all [`Error`] contexts are printed. To print the full stack of
+/// [`Error`] contexts and attachments, use the [`Debug`] implementation (`"{:?}"`). To customize
+/// the output of the attachments in the [`Debug`] output, please see the [`error_stack::fmt`]
+/// module.
 ///
 /// Please see the examples below for more information.
 ///
-/// [`Display`]: fmt::Display
+/// [`Display`]: core::fmt::Display
 /// [`error_stack::fmt`]: crate::fmt
 ///
 /// ## Multiple Errors
 ///
-/// `Report` is able to represent multiple errors that have occurred. Errors can be combined using
-/// the [`extend_one()`], which will add the [`Frame`] stack of the other error as an additional
-/// source to the current report.
+/// `Report` comes in two variants: `Report<C>` which represents a single error context, and
+/// `Report<[C]>` which can represent multiple error contexts. To combine multiple errors,
+/// first convert a `Report<C>` to `Report<[C]>` using [`expand()`], then use [`push()`] to
+/// add additional errors. This allows for representing complex error scenarios with multiple
+/// related simultaneous errors.
+///
+/// [`expand()`]: Self::expand
+/// [`push()`]: Self::push
 ///
 /// ## `Backtrace` and `SpanTrace`
 ///
@@ -68,7 +68,7 @@ use crate::{
 ///
 /// [`provide`]: core::error::Error::provide
 /// [`ErrorLayer`]: tracing_error::ErrorLayer
-/// [`attach()`]: Self::attach
+/// [`attach_opaque()`]: Self::attach
 /// [`extend_one()`]: Self::extend_one
 /// [`new()`]: Self::new
 /// [`frames()`]: Self::frames
@@ -85,13 +85,13 @@ use crate::{
 /// ## Provide a context for an error
 ///
 /// ```rust
-/// use error_stack::{ResultExt, Result};
+/// use error_stack::ResultExt;
 ///
 /// # #[allow(dead_code)]
-/// # fn fake_main() -> Result<String, std::io::Error> {
+/// # fn fake_main() -> Result<String, error_stack::Report<std::io::Error>> {
 /// let config_path = "./path/to/config.file";
 /// let content = std::fs::read_to_string(config_path)
-///     .attach_printable_lazy(|| format!("failed to read config file {config_path:?}"))?;
+///     .attach_with(|| format!("failed to read config file {config_path:?}"))?;
 ///
 /// # const _: &str = stringify! {
 /// ...
@@ -101,9 +101,9 @@ use crate::{
 /// ## Enforce a context for an error
 ///
 /// ```rust
-/// use std::{fmt, path::{Path, PathBuf}};
+/// use std::{error::Error, fmt, path::{Path, PathBuf}};
 ///
-/// use error_stack::{Context, Report, ResultExt};
+/// use error_stack::{Report, ResultExt};
 ///
 /// #[derive(Debug)]
 /// # #[derive(PartialEq)]
@@ -142,8 +142,8 @@ use crate::{
 ///     # }
 /// }
 ///
-/// impl Context for RuntimeError {}
-/// impl Context for ConfigError {}
+/// impl Error for RuntimeError {}
+/// impl Error for ConfigError {}
 ///
 /// # #[allow(unused_variables)]
 /// fn read_config(path: impl AsRef<Path>) -> Result<String, Report<ConfigError>> {
@@ -191,31 +191,31 @@ use crate::{
 ///
 /// If the [`Display`] implementation of `Report` will be invoked, this will print something like:
 /// <pre>
-#[doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/tests/snapshots/doc/report_display__doc.snap"))]
+#[cfg_attr(doc, doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/tests/snapshots/doc/report_display__doc.snap")))]
 /// </pre>
 ///
 /// If the alternate [`Display`] implementation of `Report` is invoked (`{report:#}`), this will
 /// print something like:
 /// <pre>
-#[doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/tests/snapshots/doc/report_display_alt__doc.snap"))]
+#[cfg_attr(doc, doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/tests/snapshots/doc/report_display_alt__doc.snap")))]
 /// </pre>
 ///
 /// The [`Debug`] implementation of `Report` will print something like:
 /// <pre>
-#[doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/tests/snapshots/doc/report_debug__doc.snap"))]
+#[cfg_attr(doc, doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/tests/snapshots/doc/report_debug__doc.snap")))]
 /// </pre>
 ///
 ///
 /// ## Get the attached [`Backtrace`] and [`SpanTrace`]:
 ///
 /// ```rust,should_panic
-/// use error_stack::{ResultExt, Result};
+/// use error_stack::{ResultExt, Report};
 ///
 /// # #[allow(unused_variables)]
-/// # fn main() -> Result<(), std::io::Error> {
+/// # fn main() -> Result<(), Report<std::io::Error>> {
 /// let config_path = "./path/to/config.file";
 /// let content = std::fs::read_to_string(config_path)
-///     .attach_printable_lazy(|| format!("failed to read config file {config_path:?}"));
+///     .attach_with(|| format!("failed to read config file {config_path:?}"));
 ///
 /// let content = match content {
 ///     Err(err) => {
@@ -241,14 +241,14 @@ use crate::{
 /// # }
 /// ```
 #[must_use]
-#[allow(clippy::field_scoped_visibility_modifiers)]
-pub struct Report<C> {
+#[expect(clippy::field_scoped_visibility_modifiers)]
+pub struct Report<C: ?Sized> {
     // The vector is boxed as this implies a memory footprint equal to a single pointer size
     // instead of three pointer sizes. Even for small `Result::Ok` variants, the `Result` would
     // still have at least the size of `Report`, even at the happy path. It's unexpected, that
     // creating or traversing a report will happen in the hot path, so a double indirection is
     // a good trade-off.
-    #[allow(clippy::box_collection)]
+    #[expect(clippy::box_collection)]
     pub(super) frames: Box<Vec<Frame>>,
     _context: PhantomData<fn() -> *const C>,
 }
@@ -263,13 +263,12 @@ impl<C> Report<C> {
     /// [`Backtrace` and `SpanTrace` section]: #backtrace-and-spantrace
     #[inline]
     #[track_caller]
-    #[allow(clippy::missing_panics_doc)] // Reason: No panic possible
+    #[expect(clippy::missing_panics_doc, reason = "No panic possible")]
     pub fn new(context: C) -> Self
     where
-        C: Context,
+        C: Error + Send + Sync + 'static,
     {
-        #[cfg(any(feature = "std", rust_1_81))]
-        if let Some(mut current_source) = context.__source() {
+        if let Some(mut current_source) = context.source() {
             // The sources needs to be applied in reversed order, so we buffer them in a vector
             let mut sources = vec![SourceContext::from_error(current_source)];
             while let Some(source) = current_source.source() {
@@ -306,8 +305,7 @@ impl<C> Report<C> {
 
         #[cfg(all(nightly, feature = "backtrace"))]
         let backtrace = core::error::request_ref::<Backtrace>(&frame.as_error())
-            .filter(|backtrace| backtrace.status() == BacktraceStatus::Captured)
-            .is_none()
+            .is_none_or(|backtrace| backtrace.status() != BacktraceStatus::Captured)
             .then(Backtrace::capture);
 
         #[cfg(all(not(nightly), feature = "backtrace"))]
@@ -315,133 +313,194 @@ impl<C> Report<C> {
 
         #[cfg(all(nightly, feature = "spantrace"))]
         let span_trace = core::error::request_ref::<SpanTrace>(&frame.as_error())
-            .filter(|span_trace| span_trace.status() == SpanTraceStatus::CAPTURED)
-            .is_none()
+            .is_none_or(|span_trace| span_trace.status() != SpanTraceStatus::CAPTURED)
             .then(SpanTrace::capture);
 
         #[cfg(all(not(nightly), feature = "spantrace"))]
         let span_trace = Some(SpanTrace::capture());
 
-        #[allow(unused_mut)]
         let mut report = Self {
             frames: Box::new(vec![frame]),
             _context: PhantomData,
         };
 
         if let Some(location) = location {
-            report = report.attach(*location);
+            report = report.attach_opaque(*location);
         }
 
         #[cfg(feature = "backtrace")]
         if let Some(backtrace) =
             backtrace.filter(|bt| matches!(bt.status(), BacktraceStatus::Captured))
         {
-            report = report.attach(backtrace);
+            report = report.attach_opaque(backtrace);
         }
 
         #[cfg(feature = "spantrace")]
         if let Some(span_trace) = span_trace.filter(|st| st.status() == SpanTraceStatus::CAPTURED) {
-            report = report.attach(span_trace);
+            report = report.attach_opaque(span_trace);
         }
 
         report
     }
 
-    /// Merge two [`Report`]s together
+    /// Converts a `Report` with a single context into a `Report` with multiple contexts.
     ///
-    /// This function appends the [`current_frames()`] of the other [`Report`] to the
-    /// [`current_frames()`] of this report.
-    /// Meaning `A.extend_one(B) -> A.current_frames() = A.current_frames() + B.current_frames()`
+    /// This function allows for the transformation of a `Report<C>` into a `Report<[C]>`,
+    /// enabling the report to potentially hold multiple current contexts of the same type.
     ///
-    /// [`current_frames()`]: Self::current_frames
-    ///
-    /// ```rust
-    /// use std::{
-    ///     fmt::{Display, Formatter},
-    ///     path::Path,
-    /// };
+    /// # Example
     ///
-    /// use error_stack::{Context, Report, ResultExt};
+    /// ```
+    /// use error_stack::Report;
     ///
     /// #[derive(Debug)]
-    /// struct IoError;
+    /// struct SystemFailure;
     ///
-    /// impl Display for IoError {
-    ///     # fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
-    ///     #     const _: &str = stringify!(
-    ///             ...
-    ///     #     );
-    ///     #     f.write_str("Io Error")
-    ///     # }
+    /// impl std::fmt::Display for SystemFailure {
+    ///     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+    ///         f.write_str("System failure occured")
+    ///     }
     /// }
     ///
-    /// # impl Context for IoError {}
+    /// impl core::error::Error for SystemFailure {}
     ///
-    /// # #[allow(unused_variables)]
-    /// fn read_config(path: impl AsRef<Path>) -> Result<String, Report<IoError>> {
-    ///     # #[cfg(any(miri, not(feature = "std")))]
-    ///     # return Err(error_stack::report!(IoError).attach_printable("Not supported"));
-    ///     # #[cfg(all(not(miri), feature = "std"))]
-    ///     std::fs::read_to_string(path.as_ref())
-    ///         .change_context(IoError)
-    /// }
+    /// // Type annotations are used here to illustrate the types used, these are not required
+    /// let failure: Report<SystemFailure> = Report::new(SystemFailure);
+    /// let mut failures: Report<[SystemFailure]> = failure.expand();
     ///
-    /// let mut error1 = read_config("config.txt").unwrap_err();
-    /// let error2 = read_config("config2.txt").unwrap_err();
-    /// let mut error3 = read_config("config3.txt").unwrap_err();
+    /// assert_eq!(failures.current_frames().len(), 1);
     ///
-    /// error1.extend_one(error2);
-    /// error3.extend_one(error1);
+    /// let another_failure = Report::new(SystemFailure);
+    /// failures.push(another_failure);
     ///
-    /// // ^ This is equivalent to:
-    /// // error3.extend_one(error1);
-    /// // error3.extend_one(error2);
+    /// assert_eq!(failures.current_frames().len(), 2);
     /// ```
+    pub fn expand(self) -> Report<[C]> {
+        Report {
+            frames: self.frames,
+            _context: PhantomData,
+        }
+    }
+
+    /// Returns the direct current frames of this report.
     ///
-    /// This function implements the same functionality as
-    /// [`Extend::extend_one` (#7261)](https://github.com/rust-lang/rust/issues/72631).
-    /// Once stabilised this function will be removed in favor of [`Extend`].
+    /// To get an iterator over the topological sorting of all frames refer to [`frames()`].
     ///
-    /// [`extend_one()`]: Self::extend_one
-    // TODO: once #7261 is stabilized deprecate and remove this function
-    #[allow(clippy::same_name_method)]
-    pub fn extend_one(&mut self, mut report: Self) {
-        self.frames.append(&mut report.frames);
+    /// This is not the same as [`Report::current_context`], this function gets the underlying
+    /// frames that make up this report, while [`Report::current_context`] traverses the stack of
+    /// frames to find the current context. A [`Report`] and be made up of multiple [`Frame`]s,
+    /// which stack on top of each other. Considering `PrintableA<PrintableA<Context>>`,
+    /// [`Report::current_frame`] will return the "outer" layer `PrintableA`, while
+    /// [`Report::current_context`] will return the underlying `Error` (the current type
+    /// parameter of this [`Report`]).
+    ///
+    /// A report can be made up of multiple stacks of frames and builds a "group" of them, this can
+    /// be achieved through first calling [`Report::expand`] and then either using [`Extend`]
+    /// or [`Report::push`].
+    ///
+    /// [`frames()`]: Self::frames
+    #[must_use]
+    pub fn current_frame(&self) -> &Frame {
+        self.frames.first().unwrap_or_else(|| {
+            unreachable!(
+                "Report does not contain any frames. This should not happen as a Report must \
+                 always contain at least one frame.\n\n
+                 Please file an issue to https://github.com/hashintel/hash/issues/new?template=bug-report-error-stack.yml\n\n
+                 Report:\n{self:?}",
+            )
+        })
     }
 
-    /// Adds additional information to the [`Frame`] stack.
+    /// Returns the current context of the `Report`.
+    ///
+    /// If the user want to get the latest context, `current_context` can be called. If the user
+    /// wants to handle the error, the context can then be used to directly access the context's
+    /// type. This is only possible for the latest context as the Report does not have multiple
+    /// generics as this would either require variadic generics or a workaround like tuple-list.
     ///
-    /// This behaves like [`attach_printable()`] but will not be shown when printing the [`Report`].
-    /// To benefit from seeing attachments in normal error outputs, use [`attach_printable()`]
+    /// This is one disadvantage of the library in comparison to plain Errors, as in these cases,
+    /// all context types are known.
     ///
-    /// **Note:** [`attach_printable()`] will be deprecated when specialization is stabilized and
-    /// it becomes possible to merge these two methods.
+    /// ## Example
     ///
-    /// [`Display`]: core::fmt::Display
-    /// [`Debug`]: core::fmt::Debug
-    /// [`attach_printable()`]: Self::attach_printable
-    #[track_caller]
-    pub fn attach<A>(mut self, attachment: A) -> Self
+    /// ```rust
+    /// # use std::{fs, path::Path};
+    /// # use error_stack::Report;
+    /// use std::io;
+    ///
+    /// fn read_file(path: impl AsRef<Path>) -> Result<String, Report<io::Error>> {
+    ///     # const _: &str = stringify! {
+    ///     ...
+    ///     # };
+    ///     # fs::read_to_string(path.as_ref()).map_err(Report::from)
+    /// }
+    ///
+    /// let report = read_file("test.txt").unwrap_err();
+    /// let io_error = report.current_context();
+    /// assert_eq!(io_error.kind(), io::ErrorKind::NotFound);
+    /// ```
+    #[must_use]
+    pub fn current_context(&self) -> &C
     where
-        A: Send + Sync + 'static,
+        C: Send + Sync + 'static,
     {
-        let old_frames = mem::replace(self.frames.as_mut(), Vec::with_capacity(1));
-        self.frames.push(Frame::from_attachment(
-            attachment,
-            old_frames.into_boxed_slice(),
-        ));
-        self
+        self.downcast_ref().unwrap_or_else(|| {
+            // Panics if there isn't an attached context which matches `T`. As it's not possible to
+            // create a `Report` without a valid context and this method can only be called when `T`
+            // is a valid context, it's guaranteed that the context is available.
+            unreachable!(
+                "Report does not contain a context. This should not happen as a Report must \
+                 always contain at least one frame.\n\n
+                 Please file an issue to https://github.com/hashintel/hash/issues/new?template=bug-report-error-stack.yml\n\n
+                 Report:\n{self:?}",
+            )
+        })
+    }
+
+    /// Converts this `Report` to an [`Error`].
+    #[must_use]
+    pub fn into_error(self) -> impl Error + Send + Sync + 'static
+    where
+        C: 'static,
+    {
+        crate::error::ReportError::new(self)
+    }
+
+    /// Returns this `Report` as an [`Error`].
+    #[must_use]
+    pub fn as_error(&self) -> &(impl Error + Send + Sync + 'static)
+    where
+        C: 'static,
+    {
+        crate::error::ReportError::from_ref(self)
+    }
+}
+
+impl<C: ?Sized> Report<C> {
+    /// Retrieves the current frames of the `Report`, regardless of its current type state.
+    ///
+    /// You should prefer using [`Report::current_frame`] or [`Report::current_frames`] instead of
+    /// this function, as those properly interact with the type state of the `Report`.
+    ///
+    /// # Use Cases
+    ///
+    /// This function is primarily used to implement traits that require access to the frames,
+    /// such as [`Debug`]. It allows for code reuse between `Report<C>` and `Report<[C]>`
+    /// implementations without duplicating logic.
+    #[must_use]
+    pub(crate) fn current_frames_unchecked(&self) -> &[Frame] {
+        &self.frames
     }
 
     /// Adds additional (printable) information to the [`Frame`] stack.
     ///
-    /// This behaves like [`attach()`] but the display implementation will be called when
+    /// This behaves like [`attach_opaque()`] but the display implementation will be called when
     /// printing the [`Report`].
     ///
-    /// **Note:** This will be deprecated in favor of [`attach()`] when specialization is
-    /// stabilized it becomes possible to merge these two methods.
+    /// **Note:** [`attach_opaque()`] will be deprecated when specialization is stabilized and
+    /// it becomes possible to merge these two methods.
     ///
-    /// [`attach()`]: Self::attach
+    /// [`attach_opaque()`]: Self::attach
     ///
     /// ## Example
     ///
@@ -471,9 +530,9 @@ impl<C> Report<C> {
     /// assert_eq!(suggestion.0, "better use a file which exists next time!");
     /// ```
     #[track_caller]
-    pub fn attach_printable<A>(mut self, attachment: A) -> Self
+    pub fn attach<A>(mut self, attachment: A) -> Self
     where
-        A: fmt::Display + fmt::Debug + Send + Sync + 'static,
+        A: Attachment,
     {
         let old_frames = mem::replace(self.frames.as_mut(), Vec::with_capacity(1));
         self.frames.push(Frame::from_printable_attachment(
@@ -483,14 +542,38 @@ impl<C> Report<C> {
         self
     }
 
-    /// Add a new [`Context`] object to the top of the [`Frame`] stack, changing the type of the
+    /// Adds additional information to the [`Frame`] stack.
+    ///
+    /// This behaves like [`attach()`] but will not be shown when printing the [`Report`].
+    /// To benefit from seeing attachments in normal error outputs, use [`attach()`].
+    ///
+    /// **Note:** This will be deprecated in favor of [`attach()`] when specialization is
+    /// stabilized it becomes possible to merge these two methods.
+    ///
+    /// [`Display`]: core::fmt::Display
+    /// [`Debug`]: core::fmt::Debug
+    /// [`attach()`]: Self::attach
+    #[track_caller]
+    pub fn attach_opaque<A>(mut self, attachment: A) -> Self
+    where
+        A: OpaqueAttachment,
+    {
+        let old_frames = mem::replace(self.frames.as_mut(), Vec::with_capacity(1));
+        self.frames.push(Frame::from_attachment(
+            attachment,
+            old_frames.into_boxed_slice(),
+        ));
+        self
+    }
+
+    /// Add a new [`Error`] object to the top of the [`Frame`] stack, changing the type of the
     /// `Report`.
     ///
-    /// Please see the [`Context`] documentation for more information.
+    /// Please see the [`Error`] documentation for more information.
     #[track_caller]
     pub fn change_context<T>(mut self, context: T) -> Report<T>
     where
-        T: Context,
+        T: Error + Send + Sync + 'static,
     {
         let old_frames = mem::replace(self.frames.as_mut(), Vec::with_capacity(1));
         let context_frame = vec![Frame::from_context(context, old_frames.into_boxed_slice())];
@@ -504,48 +587,65 @@ impl<C> Report<C> {
         }
     }
 
-    /// Return the direct current frames of this report,
-    /// to get an iterator over the topological sorting of all frames refer to [`frames()`]
-    ///
-    /// This is not the same as [`Report::current_context`], this function gets the underlying
-    /// frames that make up this report, while [`Report::current_context`] traverses the stack of
-    /// frames to find the current context. A [`Report`] and be made up of multiple [`Frame`]s,
-    /// which stack on top of each other. Considering `PrintableA<PrintableA<Context>>`,
-    /// [`Report::current_frames`] will return the "outer" layer `PrintableA`, while
-    /// [`Report::current_context`] will return the underlying `Context` (the current type
-    /// parameter of this [`Report`])
-    ///
-    /// Using [`Extend`] and [`extend_one()`], a [`Report`] can additionally be made up of multiple
-    /// stacks of frames and builds a "group" of them, but a [`Report`] can only ever have a single
-    /// `Context`, therefore this function returns a slice instead, while
-    /// [`Report::current_context`] only returns a single reference.
-    ///
-    /// [`frames()`]: Self::frames
-    /// [`extend_one()`]: Self::extend_one
-    #[must_use]
-    pub fn current_frames(&self) -> &[Frame] {
-        &self.frames
-    }
-
     /// Returns an iterator over the [`Frame`] stack of the report.
     pub fn frames(&self) -> Frames<'_> {
         Frames::new(&self.frames)
     }
 
-    /// Returns an iterator over the [`Frame`] stack of the report with mutable elements.
-    pub fn frames_mut(&mut self) -> FramesMut<'_> {
-        FramesMut::new(&mut self.frames)
+    /// Visits every [`Frame`] of the report mutably, in the same order as [`frames()`].
+    ///
+    /// Returning [`ControlFlow::Break`] from `visitor` stops the traversal early. The break is
+    /// propagated to the caller, a full traversal returns [`ControlFlow::Continue`].
+    ///
+    /// This is deliberately not an [`Iterator`]: an iterator over `&mut Frame` hands out
+    /// references whose lifetimes are independent of each other, so a frame and one of its
+    /// sources (reachable via [`Frame::sources_mut`]) could be borrowed mutably at the same
+    /// time. Scoping mutable access to a visitor rules that out.
+    ///
+    /// ## Example
+    ///
+    /// ```rust
+    /// # use std::{fs, io, path::Path};
+    /// # use core::ops::ControlFlow;
+    /// # use error_stack::Report;
+    /// # fn read_file(path: impl AsRef<Path>) -> Result<String, Report<io::Error>> {
+    /// #     fs::read_to_string(path.as_ref()).map_err(Report::from)
+    /// # }
+    /// let mut report = read_file("test.txt").unwrap_err();
+    /// let flow = report.frames_mut(|frame| {
+    ///     if let Some(io_error) = frame.downcast_mut::<io::Error>() {
+    ///         *io_error = io::Error::from(io::ErrorKind::Other);
+    ///         return ControlFlow::Break(());
+    ///     }
+    ///     ControlFlow::Continue(())
+    /// });
+    /// assert!(flow.is_break());
+    /// ```
+    ///
+    /// [`frames()`]: Self::frames
+    pub fn frames_mut(
+        &mut self,
+        mut visitor: impl FnMut(&mut Frame) -> ControlFlow<()>,
+    ) -> ControlFlow<()> {
+        // If lending iterators ever land in `core`, this should become one: yielding `&mut Frame`
+        // bound to the `next()` borrow is sound and more ergonomic than a visitor.
+        let mut stack = vec![self.frames.iter_mut()];
+        while let Some(frame) = iter::next(&mut stack) {
+            visitor(frame)?;
+            stack.push(frame.sources_mut().iter_mut());
+        }
+        ControlFlow::Continue(())
     }
 
     /// Creates an iterator of references of type `T` that have been [`attached`](Self::attach) or
-    /// that are [`provide`](Error::provide)d by [`Context`] objects.
+    /// that are [`provide`](Error::provide)d by [`Error`] objects.
     #[cfg(nightly)]
     pub fn request_ref<T: ?Sized + Send + Sync + 'static>(&self) -> RequestRef<'_, T> {
         RequestRef::new(&self.frames)
     }
 
     /// Creates an iterator of values of type `T` that have been [`attached`](Self::attach) or
-    /// that are [`provide`](Error::provide)d by [`Context`] objects.
+    /// that are [`provide`](Error::provide)d by [`Error`] objects.
     #[cfg(nightly)]
     pub fn request_value<T: Send + Sync + 'static>(&self) -> RequestValue<'_, T> {
         RequestValue::new(&self.frames)
@@ -553,7 +653,7 @@ impl<C> Report<C> {
 
     /// Returns if `T` is the type held by any frame inside of the report.
     ///
-    /// `T` could either be an attachment or a [`Context`].
+    /// `T` could either be an attachment or a [`Error`] context.
     ///
     /// ## Example
     ///
@@ -578,7 +678,7 @@ impl<C> Report<C> {
     /// Searches the frame stack for a context provider `T` and returns the most recent context
     /// found.
     ///
-    /// `T` can either be an attachment or a [`Context`].
+    /// `T` can either be an attachment or a new [`Error`] context.
     ///
     /// ## Example
     ///
@@ -605,21 +705,149 @@ impl<C> Report<C> {
 
     /// Searches the frame stack for an instance of type `T`, returning the most recent one found.
     ///
-    /// `T` can either be an attachment or a [`Context`].
+    /// `T` can either be an attachment or a new [`Error`] context.
     #[must_use]
     pub fn downcast_mut<T: Send + Sync + 'static>(&mut self) -> Option<&mut T> {
-        self.frames_mut().find_map(Frame::downcast_mut::<T>)
+        // This cannot use `frames_mut` as the found reference needs to outlive the visitor
+        // closure. Each frame is either returned or descended into, never both, so the borrow
+        // checker accepts this without `unsafe`.
+        let mut stack = vec![self.frames.iter_mut()];
+        while let Some(frame) = iter::next(&mut stack) {
+            if frame.is::<T>() {
+                return frame.downcast_mut();
+            }
+            stack.push(frame.sources_mut().iter_mut());
+        }
+        None
     }
+}
 
-    /// Returns the current context of the `Report`.
+impl<C> Report<[C]> {
+    /// Returns the direct current frames of this report.
     ///
-    /// If the user want to get the latest context, `current_context` can be called. If the user
-    /// wants to handle the error, the context can then be used to directly access the context's
-    /// type. This is only possible for the latest context as the Report does not have multiple
-    /// generics as this would either require variadic generics or a workaround like tuple-list.
+    /// To get an iterator over the topological sorting of all frames refer to [`frames()`].
     ///
-    /// This is one disadvantage of the library in comparison to plain Errors, as in these cases,
-    /// all context types are known.
+    /// This is not the same as [`Report::current_context`], this function gets the underlying
+    /// frames that make up this report, while [`Report::current_context`] traverses the stack of
+    /// frames to find the current context. A [`Report`] and be made up of multiple [`Frame`]s,
+    /// which stack on top of each other. Considering `PrintableA<PrintableA<Context>>`,
+    /// [`Report::current_frames`] will return the "outer" layer `PrintableA`, while
+    /// [`Report::current_context`] will return the underlying `Error` (the current type
+    /// parameter of this [`Report`]).
+    ///
+    /// Using [`Extend`], [`push()`] and [`append()`], a [`Report`] can additionally be made up of
+    /// multiple stacks of frames and builds a "group" of them, therefore this function returns a
+    /// slice instead, while [`Report::current_context`] only returns a single reference.
+    ///
+    /// [`push()`]: Self::push
+    /// [`append()`]: Self::append
+    /// [`frames()`]: Self::frames
+    /// [`extend_one()`]: Self::extend_one
+    #[must_use]
+    pub fn current_frames(&self) -> &[Frame] {
+        &self.frames
+    }
+
+    /// Pushes a new context to the `Report`.
+    ///
+    /// This function adds a new [`Frame`] to the current frames with the frame from the given
+    /// [`Report`].
+    ///
+    /// [`current_frames()`]: Self::current_frames
+    ///
+    /// ## Example
+    ///
+    /// ```rust
+    /// use std::{fmt, path::Path};
+    ///
+    /// use error_stack::{Report, ResultExt};
+    ///
+    /// #[derive(Debug)]
+    /// struct IoError;
+    ///
+    /// impl fmt::Display for IoError {
+    ///     # fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
+    ///     #     const _: &str = stringify!(
+    ///             ...
+    ///     #     );
+    ///     #     fmt.write_str("Io Error")
+    ///     # }
+    /// }
+    ///
+    /// # impl core::error::Error for IoError {}
+    ///
+    /// # #[allow(unused_variables)]
+    /// fn read_config(path: impl AsRef<Path>) -> Result<String, Report<IoError>> {
+    ///     # #[cfg(any(miri, not(feature = "std")))]
+    ///     # return Err(error_stack::report!(IoError).attach("Not supported"));
+    ///     # #[cfg(all(not(miri), feature = "std"))]
+    ///     std::fs::read_to_string(path.as_ref())
+    ///         .change_context(IoError)
+    /// }
+    ///
+    /// let mut error1 = read_config("config.txt").unwrap_err().expand();
+    /// let error2 = read_config("config2.txt").unwrap_err();
+    /// let error3 = read_config("config3.txt").unwrap_err();
+    ///
+    /// error1.push(error2);
+    /// error1.push(error3);
+    /// ```
+    pub fn push(&mut self, mut report: Report<C>) {
+        self.frames.append(&mut report.frames);
+    }
+
+    /// Appends the frames from another `Report` to this one.
+    ///
+    /// This method combines the frames of the current `Report` with those of the provided `Report`,
+    /// effectively merging the two error reports.
+    ///
+    /// ## Example
+    ///
+    /// ```rust
+    /// use std::{fmt, path::Path};
+    ///
+    /// use error_stack::{Report, ResultExt};
+    ///
+    /// #[derive(Debug)]
+    /// struct IoError;
+    ///
+    /// impl fmt::Display for IoError {
+    ///     # fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
+    ///     #     const _: &str = stringify!(
+    ///             ...
+    ///     #     );
+    ///     #     fmt.write_str("Io Error")
+    ///     # }
+    /// }
+    ///
+    /// # impl core::error::Error for IoError {}
+    ///
+    /// # #[allow(unused_variables)]
+    /// fn read_config(path: impl AsRef<Path>) -> Result<String, Report<IoError>> {
+    ///     # #[cfg(any(miri, not(feature = "std")))]
+    ///     # return Err(error_stack::report!(IoError).attach("Not supported"));
+    ///     # #[cfg(all(not(miri), feature = "std"))]
+    ///     std::fs::read_to_string(path.as_ref())
+    ///         .change_context(IoError)
+    /// }
+    ///
+    /// let mut error1 = read_config("config.txt").unwrap_err().expand();
+    /// let error2 = read_config("config2.txt").unwrap_err();
+    /// let mut error3 = read_config("config3.txt").unwrap_err().expand();
+    ///
+    /// error1.push(error2);
+    /// error3.append(error1);
+    /// ```
+    pub fn append(&mut self, mut report: Self) {
+        self.frames.append(&mut report.frames);
+    }
+
+    /// Returns an iterator over the current contexts of the `Report`.
+    ///
+    /// This method is similar to [`current_context`], but instead of returning a single context,
+    /// it returns an iterator over all contexts in the `Report`.
+    ///
+    /// The order of the contexts should not be relied upon, as it is not guaranteed to be stable.
     ///
     /// ## Example
     ///
@@ -635,77 +863,93 @@ impl<C> Report<C> {
     ///     # fs::read_to_string(path.as_ref()).map_err(Report::from)
     /// }
     ///
-    /// let report = read_file("test.txt").unwrap_err();
-    /// let io_error = report.current_context();
-    /// assert_eq!(io_error.kind(), io::ErrorKind::NotFound);
+    /// let mut a = read_file("test.txt").unwrap_err().expand();
+    /// let b = read_file("test2.txt").unwrap_err();
+    ///
+    /// a.push(b);
+    ///
+    /// let io_error = a.current_contexts();
+    /// assert_eq!(io_error.count(), 2);
     /// ```
-    #[must_use]
-    pub fn current_context(&self) -> &C
+    ///
+    /// [`current_context`]: Self::current_context
+    pub fn current_contexts(&self) -> impl Iterator<Item = &C>
     where
         C: Send + Sync + 'static,
     {
-        self.downcast_ref().unwrap_or_else(|| {
-            // Panics if there isn't an attached context which matches `T`. As it's not possible to
-            // create a `Report` without a valid context and this method can only be called when `T`
-            // is a valid context, it's guaranteed that the context is available.
-            unreachable!(
-                "Report does not contain a context. This is considered a bug and should be \
-                reported to https://github.com/hashintel/hash/issues/new/choose"
-            );
-        })
-    }
+        // this needs a manual traveral implementation, why?
+        // We know that each arm has a current context, but we don't know where that context is,
+        // therefore we need to search for it on each branch, but stop once we found it, that way
+        // we're able to return the current context, even if it is "buried" underneath a bunch of
+        // attachments.
+        let mut output = Vec::new();
 
-    /// Converts this `Report` to an [`Error`].
-    #[must_use]
-    #[cfg(any(feature = "std", rust_1_81))]
-    pub fn into_error(self) -> impl Error + Send + Sync + 'static
-    where
-        C: 'static,
-    {
-        crate::error::ReportError::new(self)
-    }
+        // this implementation does some "weaving" in a sense, it goes L->R for the frames, then
+        // R->L for the sources, which means that some sources might be out of order, but this
+        // simplifies implementation.
+        let mut stack = vec![self.current_frames()];
+        while let Some(frames) = stack.pop() {
+            for frame in frames {
+                // check if the frame is the current context, in that case we don't need to follow
+                // the tree anymore
+                if let Some(context) = frame.downcast_ref::<C>() {
+                    output.push(context);
+                    continue;
+                }
 
-    /// Returns this `Report` as an [`Error`].
-    #[must_use]
-    #[cfg(any(feature = "std", rust_1_81))]
-    pub fn as_error(&self) -> &(impl Error + Send + Sync + 'static)
-    where
-        C: 'static,
-    {
-        crate::error::ReportError::from_ref(self)
+                // descend into the tree
+                let sources = frame.sources();
+                match sources {
+                    [] => unreachable!(
+                        "Report does not contain a context. This is considered a bug and should be \
+                        reported to https://github.com/hashintel/hash/issues/new/choose"
+                    ),
+                    sources => {
+                        stack.push(sources);
+                    }
+                }
+            }
+        }
+
+        output.into_iter()
     }
 }
 
-#[cfg(any(feature = "std", rust_1_81))]
 impl<C: 'static> From<Report<C>> for Box<dyn Error> {
     fn from(report: Report<C>) -> Self {
         Box::new(report.into_error())
     }
 }
 
-#[cfg(any(feature = "std", rust_1_81))]
 impl<C: 'static> From<Report<C>> for Box<dyn Error + Send> {
     fn from(report: Report<C>) -> Self {
         Box::new(report.into_error())
     }
 }
 
-#[cfg(any(feature = "std", rust_1_81))]
 impl<C: 'static> From<Report<C>> for Box<dyn Error + Sync> {
     fn from(report: Report<C>) -> Self {
         Box::new(report.into_error())
     }
 }
 
-#[cfg(any(feature = "std", rust_1_81))]
 impl<C: 'static> From<Report<C>> for Box<dyn Error + Send + Sync> {
     fn from(report: Report<C>) -> Self {
         Box::new(report.into_error())
     }
 }
 
+impl<C> From<Report<C>> for Report<[C]> {
+    fn from(report: Report<C>) -> Self {
+        Self {
+            frames: report.frames,
+            _context: PhantomData,
+        }
+    }
+}
+
 #[cfg(feature = "std")]
-impl<Context> std::process::Termination for Report<Context> {
+impl<C> std::process::Termination for Report<C> {
     fn report(self) -> ExitCode {
         #[cfg(not(nightly))]
         return ExitCode::FAILURE;
@@ -718,23 +962,97 @@ impl<Context> std::process::Termination for Report<Context> {
     }
 }
 
-impl<Context> FromIterator<Report<Context>> for Option<Report<Context>> {
-    fn from_iter<T: IntoIterator<Item = Report<Context>>>(iter: T) -> Self {
+impl<C> FromIterator<Report<C>> for Option<Report<[C]>> {
+    fn from_iter<T: IntoIterator<Item = Report<C>>>(iter: T) -> Self {
         let mut iter = iter.into_iter();
 
-        let mut base = iter.next()?;
+        let mut base = iter.next()?.expand();
         for rest in iter {
-            base.extend_one(rest);
+            base.push(rest);
         }
 
         Some(base)
     }
 }
 
-impl<Context> Extend<Self> for Report<Context> {
-    fn extend<T: IntoIterator<Item = Self>>(&mut self, iter: T) {
+impl<C> FromIterator<Report<[C]>> for Option<Report<[C]>> {
+    fn from_iter<T: IntoIterator<Item = Report<[C]>>>(iter: T) -> Self {
+        let mut iter = iter.into_iter();
+
+        let mut base = iter.next()?;
+        for mut rest in iter {
+            base.frames.append(&mut rest.frames);
+        }
+
+        Some(base)
+    }
+}
+
+impl<C> Extend<Report<C>> for Report<[C]> {
+    fn extend<T: IntoIterator<Item = Report<C>>>(&mut self, iter: T) {
         for item in iter {
-            self.extend_one(item);
+            self.push(item);
+        }
+    }
+}
+
+impl<C> Extend<Self> for Report<[C]> {
+    fn extend<T: IntoIterator<Item = Self>>(&mut self, iter: T) {
+        for mut item in iter {
+            self.frames.append(&mut item.frames);
         }
     }
 }
+
+/// Provides unified way to convert an error-like structure to a [`Report`].
+///
+/// This trait allows both [`Report<C>`] instances and regular error types to be converted into a
+/// [`Report`]. It is automatically implemented for any type that can be converted into a [`Report`]
+/// via the [`Into`] trait.
+///
+/// This trait is particularly useful when working with functions that need to return a [`Report`],
+/// as it provides a consistent way to convert errors into reports without explicitly calling
+/// conversion methods.
+///
+/// # Examples
+///
+/// ```rust
+/// use std::io;
+///
+/// use error_stack::{IntoReport as _, Report};
+///
+/// # #[expect(dead_code)]
+/// fn example() -> Result<(), Report<io::Error>> {
+///     // io::Error implements Into<Report<io::Error>>, so we can use into_report()
+///     let err = io::Error::new(io::ErrorKind::Other, "oh no!");
+///     Err(err.into_report())
+/// }
+/// ```
+pub trait IntoReport {
+    /// The context type that will be used in the resulting [`Report`].
+    type Context: ?Sized;
+
+    /// Converts this value into a [`Report`].
+    fn into_report(self) -> Report<Self::Context>;
+}
+
+impl<C: ?Sized> IntoReport for Report<C> {
+    type Context = C;
+
+    #[track_caller]
+    fn into_report(self) -> Report<Self::Context> {
+        self
+    }
+}
+
+impl<E> IntoReport for E
+where
+    E: Into<Report<E>>,
+{
+    type Context = E;
+
+    #[track_caller]
+    fn into_report(self) -> Report<Self::Context> {
+        self.into()
+    }
+}