// file: crates/knowledge-git-lib/src/error.rs
// version: 3

//! Recoverable errors for controlled Git process execution.

/// Git operation category safe to expose in diagnostics.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum GitOperation {
    /// Clone one configured source into a controlled mirror.
    CloneMirror,
    /// Inspect whether a controlled repository is a valid bare mirror.
    InspectMirror,
    /// Refresh refs in one controlled mirror.
    RefreshMirror,
    /// Resolve one configured reference to a commit revision.
    ResolveRevision,
    /// Materialize one detached revision-addressed snapshot.
    CreateSnapshot,
    /// Validate an existing detached snapshot before reuse.
    InspectSnapshot,
}

impl std::fmt::Display for crate::GitOperation {
    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            crate::GitOperation::CloneMirror => return formatter.write_str("clone mirror"),
            crate::GitOperation::InspectMirror => return formatter.write_str("inspect mirror"),
            crate::GitOperation::RefreshMirror => return formatter.write_str("refresh mirror"),
            crate::GitOperation::ResolveRevision => return formatter.write_str("resolve revision"),
            crate::GitOperation::CreateSnapshot => return formatter.write_str("create snapshot"),
            crate::GitOperation::InspectSnapshot => return formatter.write_str("inspect snapshot"),
        }
    }
}

/// Recoverable error returned by the controlled Git backend.
///
/// Process failures intentionally retain only an operation category and exit code. Source URLs,
/// command arguments, stderr and credentials are not embedded in this public error.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum GitBackendError {
    /// The configured Git executable path is empty.
    EmptyGitExecutable,
    /// The configured state root is empty.
    EmptyStateRoot,
    /// A local source path or remote source string is empty.
    EmptySourceLocation,
    /// One logical source identifier was registered more than once in the same backend.
    DuplicateSource,
    /// No physical source configuration is registered for the requested logical source.
    SourceNotConfigured,
    /// The backend could not prepare its generated-state directories.
    StatePreparationFailed,
    /// The Git executable could not be started for the requested operation.
    GitUnavailable {
        /// Operation that could not start.
        operation: crate::GitOperation,
    },
    /// Git returned a non-success status for the requested operation.
    GitCommandFailed {
        /// Operation that failed.
        operation: crate::GitOperation,
        /// Process exit code when the operating system exposed one.
        exit_code: Option<i32>,
    },
    /// An existing controlled repository is not a valid bare mirror.
    InvalidMirror,
    /// A controlled mirror required by a read operation does not exist yet.
    MirrorMissing,
    /// A revision supplied to snapshot materialization is not a safe Git object identity.
    InvalidRevision,
    /// An existing snapshot does not match the requested revision or is not clean.
    InvalidSnapshot,
    /// Git returned output that does not satisfy the backend contract.
    UnexpectedGitOutput {
        /// Operation whose output could not be validated.
        operation: crate::GitOperation,
    },
}

impl std::fmt::Display for crate::GitBackendError {
    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            crate::GitBackendError::EmptyGitExecutable => return formatter.write_str("git executable must not be empty"),
            crate::GitBackendError::EmptyStateRoot => return formatter.write_str("git state root must not be empty"),
            crate::GitBackendError::EmptySourceLocation => return formatter.write_str("git source location must not be empty"),
            crate::GitBackendError::DuplicateSource => return formatter.write_str("git source identifier is already configured"),
            crate::GitBackendError::SourceNotConfigured => return formatter.write_str("git source identifier is not configured"),
            crate::GitBackendError::StatePreparationFailed => return formatter.write_str("git state directories could not be prepared"),
            crate::GitBackendError::GitUnavailable { operation } => return write!(formatter, "git is unavailable while attempting to {operation}"),
            crate::GitBackendError::GitCommandFailed { operation, exit_code } => {
                return write!(formatter, "git failed while attempting to {operation}; exit code {exit_code:?}");
            },
            crate::GitBackendError::InvalidMirror => return formatter.write_str("controlled git repository is not a valid bare mirror"),
            crate::GitBackendError::MirrorMissing => return formatter.write_str("controlled git mirror does not exist"),
            crate::GitBackendError::InvalidRevision => return formatter.write_str("git revision is not a safe object identity"),
            crate::GitBackendError::InvalidSnapshot => return formatter.write_str("controlled git snapshot is invalid or dirty"),
            crate::GitBackendError::UnexpectedGitOutput { operation } => {
                return write!(formatter, "git returned unexpected output while attempting to {operation}");
            },
        }
    }
}

impl std::error::Error for crate::GitBackendError {}