Maintain/Build/

Error.rs

//=============================================================================//
// File Path: Element/Maintain/Source/Build/Error.rs
//=============================================================================//
// Module: Error
//
// Brief Description: Build system error types and handling.
//
// RESPONSIBILITIES:
// ================
//
// Primary:
// - Define comprehensive error types for build operations
// - Provide automatic error conversions from underlying libraries
// - Support clear error messages for debugging build failures
//
// Secondary:
// - Enable proper error propagation through the build system
// - Provide context for build failure diagnosis
//
// ARCHITECTURAL ROLE:
// ===================
//
// Position:
// - Infrastructure/Error handling layer
// - Error type definitions
//
// Dependencies (What this module requires):
// - External crates: thiserror, std
// - Internal modules: None
// - Traits implemented: None
//
// Dependents (What depends on this module):
// - Build orchestration functions
// - File manipulation functions
// - Guard implementation
//
// IMPLEMENTATION DETAILS:
// =======================
//
// Design Patterns:
// - Error handling pattern with thiserror derive macro
// - From trait implementations for automatic error conversion
//
// Performance Considerations:
// - Complexity: O(1) - enum variant selection
// - Memory usage patterns: Enum discrimination + variant data
// - Hot path optimizations: None
//
// Thread Safety:
// - Thread-safe: Yes (immutable error enum)
// - Synchronization mechanisms used: None
// - Interior mutability considerations: None
//
// Error Handling:
// - Error types returned: This module defines all build errors
// - Recovery strategies: Propagate errors up; Guard restores files
//
// EXAMPLES:
// =========
//
// Example 1: Returning an error
/// ```rust
/// use std::fs;
///
/// use crate::Maintain::Source::Build::Error;
/// fn read_file(path:&Path) -> Result<String, Error> { fs::read_to_string(path)? }
/// ```
// Example 2: Handling errors
/// ```rust
/// use crate::Maintain::Source::Build::Error;
/// match result {
/// 	Ok(_) => println!("Success"),
/// 	Err(Error::Io(e)) => println!("IO error: {}", e),
/// 	Err(Error::Missing(path)) => println!("Missing: {}", path.display()),
/// 	Err(e) => println!("Error: {}", e),
/// }
/// ```
//
//=============================================================================//
// IMPLEMENTATION
//=============================================================================//
use std::{io, path::PathBuf};

use thiserror::Error;

/// Represents all possible errors that can occur during the build script's
/// execution.
///
/// This enum provides a comprehensive error type for the build orchestration
/// system, covering all failure modes from IO operations to parsing errors
/// to command execution failures. Each variant includes relevant context
/// to help diagnose the issue.
///
/// The enum derives `Error` from the `thiserror` crate, which provides
/// automatic implementations of the `Error` trait and error display formatting.
///
/// # Automatic Conversions
///
/// This type implements `From` for several error types, allowing the `?`
/// operator to automatically convert library-specific errors into `Error`:
/// - `io::Error` → `Error::Io`
/// - `toml_edit::TomlError` → `Error::Edit`
/// - `toml::de::Error` → `Error::Parse`
/// - `serde_json::Error` → `Error::Json`
/// - `json5::Error` → `Error::Jsonfive`
/// - `std::string::FromUtf8Error` → `Error::Utf`
#[derive(Error, Debug)]
pub enum Error {
	/// IO operation error.
	///
	/// This variant wraps standard Rust IO errors that can occur during
	/// file operations like reading, writing, copying, or deleting files.
	#[error("IO: {0}")]
	Io(#[from] io::Error),

	/// Toml editing error.
	///
	/// This variant wraps errors that occur when manipulating TOML documents
	/// using the `toml_edit` library, such as invalid mutations or parsing
	/// issues when reading TOML content.
	#[error("Toml Editing: {0}")]
	Edit(#[from] toml_edit::TomlError),

	/// Toml deserialization error.
	///
	/// This variant wraps errors that occur when parsing TOML files into
	/// Rust structs using the `toml` library's deserialization functionality.
	#[error("Toml Parsing: {0}")]
	Parse(#[from] toml::de::Error),

	/// JSON parsing/error.
	///
	/// This variant wraps errors that occur when parsing or validating
	/// standard JSON files using the `serde_json` library.
	#[error("Json: {0}")]
	Json(#[from] serde_json::Error),

	/// JSON5 parsing/error.
	///
	/// This variant wraps errors that occur when parsing or validating
	/// JSON5 files (a more flexible JSON format) using the `json5` library.
	#[error("Json5: {0}")]
	Jsonfive(#[from] json5::Error),

	/// Missing directory error.
	///
	/// This variant is used when a required directory does not exist at
	/// the specified path. The path is included for debugging purposes,
	#[error("Missing Directory: {0}")]
	Missing(PathBuf),

	/// Shell command execution failure.
	///
	/// This variant is used when the final build command fails to execute
	/// successfully. The exit status is included to provide information
	/// about the failure.
	#[error("Command Failed: {0}")]
	Shell(std::process::ExitStatus),

	/// No command provided error.
	///
	/// This variant is used when the build script is invoked without
	/// specifying a build command to execute.
	#[error("No Command Provided")]
	NoCommand,

	/// Tauri configuration file not found error.
	///
	/// This variant is used when neither `tauri.conf.json` nor
	/// `tauri.conf.json5` can be found in the project directory.
	#[error("Tauri Configuration File Not Found")]
	Config,

	/// Backup file already exists error.
	///
	/// This variant is used when the Guard attempts to create a backup but
	/// a backup file already exists at the target location. This prevents
	/// overwriting existing backups and ensures data safety.
	#[error("Backup File Exists: {0}")]
	Exists(PathBuf),

	/// UTF-8 conversion error.
	///
	/// This variant wraps errors that occur when converting byte vectors
	/// to UTF-8 strings, particularly when dealing with file contents or
	/// command output.
	#[error("UTF-8 Conversion: {0}")]
	Utf(#[from] std::string::FromUtf8Error),

	/// Missing environment variable error.
	///
	/// This variant is used when a required environment variable is not
	/// set. The variable name is included in the error message for easy
	/// identification and resolution.
	#[error("Environment Variable Missing: {0}")]
	Environment(String),
}