errors

Error Handling System

This package provides a comprehensive, categorized error handling system for the Hitch application. It replaces generic fmt.Errorf calls with structured, context-rich error types that improve debugging, error handling, and user experience.

Overview

The error handling system consists of:

• Error Categories - Structured categorization of error types
• HitchError - Base error type with context and categorization
• Specific Error Types - Specialized errors for different domains
• Error Utilities - Helper functions for error analysis and handling

Error Categories

type ErrorCategory int

const (
    CategoryUnknown ErrorCategory = iota
    CategoryValidation        // Input validation errors
    CategoryGitOperation      // Git-related operation errors
    CategoryUserInput         // User-provided input errors
    CategorySystem           // System-level errors (filesystem, permissions)
    CategoryMetadata         // Metadata-related errors
    CategoryRepository       // Repository state errors
)

Core Components

HitchError

The base error type that provides structured error information:

type HitchError struct {
    Category    ErrorCategory             // Error category for classification
    Message     string                   // Human-readable error message
    Details     string                   // Additional error details
    Underlying  error                   // Wrapped underlying error
    Context     map[string]interface{}   // Additional context information
}

Key Features:

• Categorization - Every error has a specific category for programmatic handling
• Context - Rich context information for debugging and logging
• Error Wrapping - Proper error chain maintenance with Unwrap()
• String Representation - Clean, formatted error messages

ValidationError

Used for input validation failures with field-specific information:

type ValidationError struct {
    Field   string  // Name of the field that failed validation
    Value   string  // The value that failed validation
    Reason  string  // Specific reason for validation failure
    Message string  // Formatted error message
}

GitOperationError

Specialized for Git-related operations with detailed command information:

type GitOperationError struct {
    Operation string  // Git operation that failed (merge, push, pull, etc.)
    Target    string  // Target of the operation (branch, remote, etc.)
    Reason    string  // Human-readable reason for failure
    Output    string  // Git command output for debugging
    ExitCode  int     // Exit code from git command
}

MergeConflictError

Specific to merge operations with file-level conflict information:

type MergeConflictError struct {
    Branch       string   // Source branch that caused conflicts
    ConflictFiles []string // List of files with conflicts
    Message      string   // Detailed conflict information
}

Usage Examples

Creating Validation Errors

import hitcherrors "github.com/DoomedRamen/hitch/internal/errors"

// Basic validation error
err := hitcherrors.NewBranchValidationError("feature/invalid", "contains dangerous characters")

// With custom details
err := hitcherrors.NewValidationError("invalid input", "must be alphanumeric")

Creating Git Operation Errors

// Git merge error
err := hitcherrors.NewGitMergeError("feature-branch", "conflicts detected", gitOutput)

// Git push error
err := hitcherrors.NewGitPushError("main", "origin", "authentication failed", pushOutput)

// Generic git command error
err := hitcherrors.NewGitCommandError("checkout", []string{"-b", "new-branch"}, "branch already exists", output)

Creating System Errors

// System error with underlying error
err := hitcherrors.NewSystemError("failed to access repository", os.ErrNotExist)

// Metadata error
err := hitcherrors.NewMetadataError("environment not found", "staging environment does not exist", nil)

// Repository error
err := hitcherrors.NewRepositoryError("repository is dirty", "uncommitted changes exist")

Adding Context to Errors

err := hitcherrors.NewValidationError("invalid branch name", "contains spaces").
    WithContext("branch_name", "feature invalid").
    WithContext("max_length", 255).
    WithContext("provided_length", len(branchName))

Error Analysis

// Check error category
if hitcherrors.IsCategory(err, hitcherrors.CategoryValidation) {
    // Handle validation error
}

// Extract error category
category := hitcherrors.GetCategory(err)
switch category {
case hitcherrors.CategoryGitOperation:
    // Handle git operation error
case hitcherrors.CategorySystem:
    // Handle system error
}

// Extract context information
if hErr, ok := err.(*hitcherrors.HitchError); ok {
    if branchName, exists := hErr.GetContext("branch_name"); exists {
        fmt.Printf("Failed branch: %v\n", branchName)
    }
}

Error Handling Patterns

1. Category-Based Error Handling

func handleCommandError(err error) error {
    if err == nil {
        return nil
    }

    switch hitcherrors.GetCategory(err) {
    case hitcherrors.CategoryValidation:
        return fmt.Errorf("validation failed: %w", err)
    case hitcherrors.CategoryGitOperation:
        return fmt.Errorf("git operation failed: %w", err)
    case hitcherrors.CategorySystem:
        return fmt.Errorf("system error: %w", err)
    default:
        return fmt.Errorf("unexpected error: %w", err)
    }
}

2. Contextual Error Enhancement

func validateAndCreateBranch(name string) error {
    if err := validateBranchName(name); err != nil {
        // Enhance validation error with additional context
        if hErr, ok := err.(*hitcherrors.HitchError); ok {
            return hErr.WithContext("operation", "branch_creation").
                         WithContext("timestamp", time.Now()).
                         WithContext("user", getCurrentUser())
        }
        return err
    }

    return createBranch(name)
}

3. Error Aggregation

func validateMultipleInputs(inputs map[string]string) error {
    var errors []hitcherrors.ValidationError

    for field, value := range inputs {
        if err := validateField(field, value); err != nil {
            if valErr, ok := err.(*hitcherrors.ValidationError); ok {
                errors = append(errors, *valErr)
            }
        }
    }

    if len(errors) == 0 {
        return nil
    }

    return hitcherrors.CombineValidationErrors(errors)
}

Migration Guide

Before (Old Pattern)

// Scattered error handling
if strings.Contains(branch, ";") {
    return fmt.Errorf("branch name contains dangerous character: ;")
}

if err := gitCommand(branch); err != nil {
    return fmt.Errorf("failed to create branch %s: %w", branch, err)
}

if len(branch) > 255 {
    return fmt.Errorf("branch name too long (max 255 characters)")
}

After (New Pattern)

import hitcherrors "github.com/DoomedRamen/hitch/internal/errors"

// Structured error handling
adapter := validation.BranchValidationAdapter()
if err := adapter.ValidateWithErrors(branch, "branch-name"); err != nil {
    return err // Returns properly categorized ValidationError
}

if err := gitCommand(branch); err != nil {
    return hitcherrors.NewGitBranchError(branch, "create", "git command failed", err.Error())
}

Benefits

1. Consistency - All errors follow the same structure and patterns
2. Debugging - Rich context information makes troubleshooting easier
3. Programmatic Handling - Error categories enable automated error handling
4. User Experience - Clear, actionable error messages
5. Maintainability - Centralized error logic reduces duplication
6. Testing - Structured errors are easier to test and mock

Best Practices

1. Use Specific Error Types - Choose the most specific error type for your use case
2. Provide Context - Add relevant context information for debugging
3. Include Underlying Errors - Always wrap underlying errors when possible
4. Clear Messages - Write human-readable error messages that explain the problem
5. Categorize Correctly - Use the appropriate error category for programmatic handling

Integration

The error handling system integrates seamlessly with:

• Validation Framework - internal/validation package uses these error types
• Git Operations - All git package functions return structured errors
• CLI Commands - Command handlers use category-based error handling
• Logging System - Error context provides structured logging data

File Structure

internal/errors/
├── README.md              # This documentation
├── errors.go             # Base HitchError and utility functions
├── validation.go         # ValidationError and related functions
└── git_operations.go    # Git-specific error types and helpers

This error handling system provides a solid foundation for consistent, maintainable error handling throughout the Hitch application.