0.0.2-alpha.2

crates/knowledge-git-lib/src/error.rs

@@ -0,0 +1,78 @@
+// file: crates/knowledge-git-lib/src/error.rs
+// version: 1
+
+//! 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,
+}
+
+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"),
+        }
+    }
+}
+
+/// 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,
+    /// 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,
+    /// 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::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::UnexpectedGitOutput { operation } => {
+                return write!(formatter, "git returned unexpected output while attempting to {operation}");
+            }
+        }
+    }
+}
+
+impl std::error::Error for crate::GitBackendError {}