Merge pull request #33 from iyanumajekodunmi756/feat/error-handling-module

feat: add error handling module with AppError enum

Author: Mkalbani

src/config/mod.rs

@@ -5,6 +5,7 @@
 //! The resulting [`Config`] is a plain typed struct accessible anywhere in the
 //! application.
 
+use crate::errors::AppError;
 use serde::{Deserialize, Serialize};
 use std::fs;
 use std::path::Path;
@@ -50,14 +51,14 @@ impl Config {
     /// - Returns the parsed config on success.
     /// - Returns [`Config::default`] if the file does not exist.
     /// - Returns an error for IO errors or malformed TOML.
-    pub fn load(path: impl AsRef<Path>) -> Result<Self, ConfigError> {
+        pub fn load(path: impl AsRef<Path>) -> Result<Self, AppError> {
         let path = path.as_ref();
         if !path.exists() {
             return Ok(Config::default());
         }
-        let raw = fs::read_to_string(path).map_err(ConfigError::Io)?;
+        let raw = fs::read_to_string(path).map_err(AppError::Io)?;
         let partial: PartialConfig =
-            toml::from_str(&raw).map_err(|e| ConfigError::Parse(e.to_string()))?;
+            toml::from_str(&raw).map_err(|e| AppError::ConfigParse(e.to_string()))?;
         Ok(partial.into_config())
     }
 }
@@ -87,33 +88,12 @@ impl PartialConfig {
     }
 }
 
-// ── Error type ───────────────────────────────────────────────────────────────
-
-/// Errors that can occur while loading configuration.
-#[derive(Debug)]
-pub enum ConfigError {
-    /// An underlying IO error (e.g. permission denied).
-    Io(std::io::Error),
-    /// The TOML content could not be parsed.
-    Parse(String),
-}
-
-impl std::fmt::Display for ConfigError {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        match self {
-            ConfigError::Io(e) => write!(f, "config IO error: {e}"),
-            ConfigError::Parse(msg) => write!(f, "config parse error: {msg}"),
-        }
-    }
-}
-
-impl std::error::Error for ConfigError {}
-
 // ── Tests ────────────────────────────────────────────────────────────────────
 
 #[cfg(test)]
 mod tests {
     use super::*;
+    use crate::errors::AppError;
     use std::io::Write;
     use tempfile::NamedTempFile;
 
@@ -174,7 +154,7 @@ score_multiplier = 2.5
     fn invalid_toml_returns_parse_error() {
         let file = write_toml("not = [ valid toml");
         let err = Config::load(file.path()).expect_err("should fail");
-        assert!(matches!(err, ConfigError::Parse(_)));
+        assert!(matches!(err, AppError::ConfigParse(_)));
     }
 
     #[test]

src/errors/mod.rs

@@ -0,0 +1,242 @@
+//! Errors module.
+//!
+//! Centralises all custom error types and handling logic into a dedicated
+//! [`AppError`] enum that every module in the codebase uses instead of
+//! ad-hoc error strings or module-specific error types.
+
+use std::fmt;
+
+/// Top-level error type covering all major error categories in the game.
+///
+/// Every module converts its internal errors into [`AppError`] so that
+/// callers can handle failures uniformly.
+#[derive(Debug)]
+pub enum AppError {
+    // ── I/O ──────────────────────────────────────────────────────────────────
+    /// An underlying I/O error (e.g. file not found, permission denied).
+    Io(std::io::Error),
+
+    // ── Serialisation ────────────────────────────────────────────────────────
+    /// A JSON serialisation or deserialisation error.
+    Serde(serde_json::Error),
+
+    // ── Config ───────────────────────────────────────────────────────────────
+    /// The TOML configuration could not be parsed.
+    ConfigParse(String),
+
+    // ── Input ────────────────────────────────────────────────────────────────
+    /// The input string was not recognised as a valid game action.
+    InputInvalid(String),
+    /// No input was provided.
+    InputEmpty,
+
+    // ── NFT / Achievements ───────────────────────────────────────────────────
+    /// The achievement has already been minted for this player.
+    NftAlreadyMinted {
+        /// The player ID.
+        player_id: String,
+        /// The milestone type that was already minted.
+        milestone_type: String,
+    },
+
+    // ── Player ───────────────────────────────────────────────────────────────
+    /// A player with the given identifier could not be found.
+    PlayerNotFound(String),
+
+    // ── Inventory ────────────────────────────────────────────────────────────
+    /// An item with the given ID does not exist in the inventory.
+    InventoryItemNotFound(String),
+
+    // ── Puzzle ───────────────────────────────────────────────────────────────
+    /// A general puzzle-domain error.
+    Puzzle(String),
+
+    // ── Leaderboard ──────────────────────────────────────────────────────────
+    /// A leaderboard-domain error.
+    Leaderboard(String),
+}
+
+// ── Display ──────────────────────────────────────────────────────────────────
+
+impl fmt::Display for AppError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            AppError::Io(e) => write!(f, "I/O error: {e}"),
+            AppError::Serde(e) => write!(f, "serialisation error: {e}"),
+            AppError::ConfigParse(msg) => write!(f, "config parse error: {msg}"),
+            AppError::InputInvalid(s) => write!(f, "invalid input: '{s}'"),
+            AppError::InputEmpty => write!(f, "input cannot be empty"),
+            AppError::NftAlreadyMinted {
+                player_id,
+                milestone_type,
+            } => {
+                write!(
+                    f,
+                    "achievement '{milestone_type}' already minted for player '{player_id}'"
+                )
+            }
+            AppError::PlayerNotFound(id) => write!(f, "player '{id}' not found"),
+            AppError::InventoryItemNotFound(id) => {
+                write!(f, "item '{id}' not found in inventory")
+            }
+            AppError::Puzzle(msg) => write!(f, "puzzle error: {msg}"),
+            AppError::Leaderboard(msg) => write!(f, "leaderboard error: {msg}"),
+        }
+    }
+}
+
+// ── std::error::Error ────────────────────────────────────────────────────────
+
+impl std::error::Error for AppError {
+    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+        match self {
+            AppError::Io(e) => Some(e),
+            AppError::Serde(e) => Some(e),
+            _ => None,
+        }
+    }
+}
+
+// ── From implementations ─────────────────────────────────────────────────────
+
+impl From<std::io::Error> for AppError {
+    fn from(e: std::io::Error) -> Self {
+        AppError::Io(e)
+    }
+}
+
+impl From<serde_json::Error> for AppError {
+    fn from(e: serde_json::Error) -> Self {
+        AppError::Serde(e)
+    }
+}
+
+// ── Tests ────────────────────────────────────────────────────────────────────
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::error::Error;
+
+    // ── Display tests ────────────────────────────────────────────────────────
+
+    #[test]
+    fn display_io_error() {
+        let io_err = std::io::Error::new(std::io::ErrorKind::NotFound, "file missing");
+        let err = AppError::Io(io_err);
+        let msg = err.to_string();
+        assert!(msg.contains("I/O error"));
+        assert!(msg.contains("file missing"));
+    }
+
+    #[test]
+    fn display_serde_error() {
+        let serde_err = serde_json::from_str::<()>("invalid").unwrap_err();
+        let err = AppError::Serde(serde_err);
+        let msg = err.to_string();
+        assert!(msg.contains("serialisation error"));
+    }
+
+    #[test]
+    fn display_config_parse() {
+        let err = AppError::ConfigParse("bad toml".into());
+        assert_eq!(err.to_string(), "config parse error: bad toml");
+    }
+
+    #[test]
+    fn display_input_invalid() {
+        let err = AppError::InputInvalid("xyz".into());
+        assert_eq!(err.to_string(), "invalid input: 'xyz'");
+    }
+
+    #[test]
+    fn display_input_empty() {
+        let err = AppError::InputEmpty;
+        assert_eq!(err.to_string(), "input cannot be empty");
+    }
+
+    #[test]
+    fn display_nft_already_minted() {
+        let err = AppError::NftAlreadyMinted {
+            player_id: "p1".into(),
+            milestone_type: "level10".into(),
+        };
+        assert_eq!(
+            err.to_string(),
+            "achievement 'level10' already minted for player 'p1'"
+        );
+    }
+
+    #[test]
+    fn display_player_not_found() {
+        let err = AppError::PlayerNotFound("hero".into());
+        assert_eq!(err.to_string(), "player 'hero' not found");
+    }
+
+    #[test]
+    fn display_inventory_not_found() {
+        let err = AppError::InventoryItemNotFound("sword".into());
+        assert_eq!(err.to_string(), "item 'sword' not found in inventory");
+    }
+
+    #[test]
+    fn display_puzzle_error() {
+        let err = AppError::Puzzle("invalid move".into());
+        assert_eq!(err.to_string(), "puzzle error: invalid move");
+    }
+
+    #[test]
+    fn display_leaderboard_error() {
+        let err = AppError::Leaderboard("capacity reached".into());
+        assert_eq!(err.to_string(), "leaderboard error: capacity reached");
+    }
+
+    // ── Error trait tests ────────────────────────────────────────────────────
+
+    #[test]
+    fn io_error_has_source() {
+        let inner = std::io::Error::new(std::io::ErrorKind::Other, "reason");
+        let err = AppError::Io(inner);
+        assert!(err.source().is_some());
+    }
+
+    #[test]
+    fn serde_error_has_source() {
+        let inner = serde_json::from_str::<()>("[").unwrap_err();
+        let err = AppError::Serde(inner);
+        assert!(err.source().is_some());
+    }
+
+    #[test]
+    fn non_wrapping_variants_have_no_source() {
+        assert!(AppError::ConfigParse("x".into()).source().is_none());
+        assert!(AppError::InputInvalid("x".into()).source().is_none());
+        assert!(AppError::InputEmpty.source().is_none());
+        assert!(AppError::PlayerNotFound("x".into()).source().is_none());
+        assert!(AppError::InventoryItemNotFound("x".into()).source().is_none());
+        assert!(AppError::Puzzle("x".into()).source().is_none());
+        assert!(AppError::Leaderboard("x".into()).source().is_none());
+        assert!(AppError::NftAlreadyMinted {
+            player_id: "p".into(),
+            milestone_type: "m".into(),
+        }
+        .source()
+        .is_none());
+    }
+
+    // ── From impl tests ──────────────────────────────────────────────────────
+
+    #[test]
+    fn from_io_error() {
+        let io = std::io::Error::new(std::io::ErrorKind::PermissionDenied, "denied");
+        let app: AppError = io.into();
+        assert!(matches!(app, AppError::Io(_)));
+    }
+
+    #[test]
+    fn from_serde_error() {
+        let serde = serde_json::from_str::<()>("%%%").unwrap_err();
+        let app: AppError = serde.into();
+        assert!(matches!(app, AppError::Serde(_)));
+    }
+}