feat: Add support for rendering a pretty error to the CLI

notheotherben · notheotherben · commit 8df7d6642b0b · 2025-12-23T12:51:48.000Z
diff --git a/Cargo.toml b/Cargo.toml
@@ -14,3 +14,12 @@ edition = "2024"
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
 [dependencies]
+cli-boxes = { version = "0.1", optional = true }
+colored = { version = "2.0", optional = true }
+serde = { version = "1.0", optional = true }
+textwrap = { version = "0.16.2", optional = true }
+
+[features]
+default = []
+cli = ["dep:cli-boxes", "dep:colored", "dep:textwrap"]
+serde = ["dep:serde"]
diff --git a/src/error.rs b/src/error.rs
@@ -1,6 +1,9 @@
 use std::{error, fmt};
 use super::Kind;
 
+#[cfg(feature = "serde")]
+use serde::ser::SerializeStruct;
+
 /// The fundamental error type used by this library.
 ///
 /// An error type which encapsulates information about whether an error
@@ -23,9 +26,9 @@ use super::Kind;
 /// ```
 #[derive(Debug)]
 pub struct Error {
-    kind: Kind,
-    error: Box<dyn error::Error + Send + Sync>,
-    advice: &'static [&'static str],
+    pub(crate) kind: Kind,
+    pub(crate) error: Box<dyn error::Error + Send + Sync>,
+    pub(crate) advice: &'static [&'static str],
 }
 
 impl Error {
@@ -97,6 +100,52 @@ impl Error {
         }
     }
 
+    /// Gets the advice associated with this error and its causes.
+    /// 
+    /// Gathers all advice from this error and any causal errors it wraps,
+    /// returning a deduplicated list of suggestions for how a user should
+    /// deal with this error.
+    /// 
+    /// # Examples
+    /// ```
+    /// use human_errors;
+    /// 
+    /// let err = human_errors::wrap_user(
+    ///   human_errors::user(
+    ///     "We could not find a file at /home/user/.config/demo.yml",
+    ///     &["Make sure that the file exists and is readable by the application."]
+    ///   ),
+    ///   "We could not open the config file you provided.",
+    ///   &["Make sure that you've specified a valid config file with the --config option."],
+    /// );
+    /// 
+    /// // Prints:
+    /// // - Make sure that the file exists and is readable by the application.
+    /// // - Make sure that you've specified a valid config file with the --config option.
+    /// for tip in err.advice() {
+    ///     println!("- {}", tip);
+    /// }
+    /// ``````
+    pub fn advice(&self) -> Vec<&'static str> {
+        let mut advice = self.advice.to_vec();
+
+        let mut cause: Option<&(dyn std::error::Error + 'static)> = Some(self.error.as_ref());
+        while let Some(err) = cause {
+            if let Some(err) = err.downcast_ref::<Error>() {
+                advice.extend_from_slice(err.advice);
+            }
+            
+            cause = err.source();
+        }
+
+        advice.reverse();
+
+        let mut seen = std::collections::HashSet::new();
+        advice.retain(|item| seen.insert(*item));
+
+        advice
+    }
+
     /// Gets the formatted error and its advice.
     ///
     /// Generates a string containing the description of the error and any causes,
@@ -120,7 +169,7 @@ impl Error {
     /// );
     ///
     /// // Prints a message like the following:
-    /// // Oh no! We could not open the config file you provided.
+    /// // We could not open the config file you provided. (User error)
     /// //
     /// // This was caused by:
     /// // We could not find a file at /home/user/.config/demo.yml
@@ -176,23 +225,6 @@ impl Error {
 
         causes
     }
-
-    fn advice(&self) -> Vec<&'static str> {
-        let mut advice = self.advice.to_vec();
-
-        let mut cause = self.error.as_ref();
-        while let Some(err) = cause.downcast_ref::<Error>() {
-            advice.extend_from_slice(err.advice);
-            cause = err.error.as_ref();
-        }
-
-        advice.reverse();
-
-        let mut seen = std::collections::HashSet::new();
-        advice.retain(|item| seen.insert(*item));
-
-        advice
-    }
 }
 
 impl error::Error for Error {
@@ -207,6 +239,20 @@ impl fmt::Display for Error {
     }
 }
 
+#[cfg(feature = "serde")]
+impl serde::Serialize for Error {
+    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+    where
+        S: serde::Serializer,
+    {
+        let mut state = serializer.serialize_struct("Error", 3)?;
+        state.serialize_field("kind", &self.kind)?;
+        state.serialize_field("description", &self.description())?;
+        state.serialize_field("advice", &self.advice())?;
+        state.end()
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -242,4 +288,24 @@ mod tests {
             "Something bad happened. (System failure)\n\nTo try and fix this, you can:\n - Avoid bad things happening in future"
         );
     }
+
+    #[test]
+    fn test_advice_aggregation() {
+        let low_level_err = Error::new(
+            "Low-level failure.",
+            Kind::System,
+            &["Check low-level systems"],
+        );
+
+        let high_level_err = Error::new(
+            low_level_err,
+            Kind::User,
+            &["Check high-level configuration"],
+        );
+
+        assert_eq!(
+            high_level_err.advice(),
+            vec!["Check low-level systems", "Check high-level configuration"]
+        );
+    }
 }
diff --git a/src/kind.rs b/src/kind.rs
@@ -38,4 +38,17 @@ impl Kind {
             Kind::System => format!("{description} (System failure)"),
         }
     }
+}
+
+#[cfg(feature = "serde")]
+impl serde::Serialize for Kind {
+    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+    where
+        S: serde::Serializer,
+    {
+        match self {
+            Kind::User => serializer.serialize_str("User"),
+            Kind::System => serializer.serialize_str("System"),
+        }
+    }
 }
diff --git a/src/lib.rs b/src/lib.rs
@@ -9,11 +9,13 @@ mod error;
 mod from;
 mod helpers;
 mod kind;
+mod renderer;
 mod result;
 mod wrapper;
 
 pub use error::*;
 pub use helpers::*;
 pub use kind::*;
+pub use renderer::*;
 pub use result::ResultExt;
 pub use wrapper::*;
diff --git a/src/renderer.rs b/src/renderer.rs

Original file line number	Diff line number	Diff line change
`@@ -38,4 +38,17 @@ impl Kind {`
`38`	`38`	`Kind::System => format!("{description} (System failure)"),`
`39`	`39`	`}`
`40`	`40`	`}`
	`41`	`+}`
	`42`	`+`
	`43`	`+#[cfg(feature = "serde")]`
	`44`	`+impl serde::Serialize for Kind {`
	`45`	`+ fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>`
	`46`	`+ where`
	`47`	`+ S: serde::Serializer,`
	`48`	`+ {`
	`49`	`+ match self {`
	`50`	`+ Kind::User => serializer.serialize_str("User"),`
	`51`	`+ Kind::System => serializer.serialize_str("System"),`
	`52`	`+ }`
	`53`	`+ }`
`41`	`54`	`}`