feat: enhance error handling with specific error types and recovery suggestions

- Add GitError, ParseError, and ConfigurationError types with detailed recovery suggestions
- Replace generic ParserError with specific ParseError types for better diagnostics
- Enhance ConventionalCommit validation to reject empty types and descriptions
- Implement smart error suggestion logic that avoids redundant suggestions
- Update command error handling with proper stderr output and exit codes
- Fix duplicate CHANGELOG.md entries

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: David Brunow

CHANGELOG.md

@@ -14,21 +14,3 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * Setup CI for releases (9b70416)
 * Add CI (31581ad)
 
-## [0.1.0] - 2024-05-20
-
-### Features
-* Initial implementation of parsing (0c04db6)
-
-### Chores
-* Setup CI for releases (9b70416)
-* Add CI (31581ad)
-
-## [0.1.0] - 2024-05-20
-
-### Features
-* Initial implementation of parsing (0c04db6)
-
-### Chores
-* Setup CI for releases (9b70416)
-* Add CI (31581ad)
-

Package.resolved

@@ -0,0 +1,30 @@
+import Foundation
+
+/// Errors related to configuration and command-line options.
+public enum ConfigurationError: LocalizedError {
+	case invalidStrictMode
+	case conflictingOptions(String)
+	case missingRequiredParameter(String)
+
+	public var errorDescription: String? {
+		switch self {
+		case .invalidStrictMode:
+			return "Strict mode configuration is invalid"
+		case .conflictingOptions(let details):
+			return "Conflicting command line options: \(details)"
+		case .missingRequiredParameter(let param):
+			return "Required parameter missing: \(param)"
+		}
+	}
+
+	public var recoverySuggestion: String? {
+		switch self {
+		case .invalidStrictMode:
+			return "Check strict mode flag usage in documentation"
+		case .conflictingOptions:
+			return "Review command line options and remove conflicting flags"
+		case .missingRequiredParameter(let param):
+			return "Provide the required parameter: \(param)"
+		}
+	}
+}

Sources/Model/ConfigurationError.swift

@@ -99,6 +99,10 @@ public struct ConventionalCommit: Equatable {
 
 		let typeWithoutScope = type.replacingOccurrences(of: scope ?? "", with: "")
 
+		guard !typeWithoutScope.isEmpty else {
+			return nil
+		}
+
 		switch typeWithoutScope {
 		case "feat":
 			self.type = .known(.feat)
@@ -124,9 +128,15 @@ public struct ConventionalCommit: Equatable {
 			self.isBreaking = false
 		}
 
-		self.description = String(
+		let description = String(
 			commit.subject.suffix(from: commit.subject.index(after: colonIndex))
 		).trimmingCharacters(in: .whitespacesAndNewlines)
+
+		guard !description.isEmpty else {
+			return nil
+		}
+
+		self.description = description
 		self.hash = commit.hash
 		self.scope = scope?
 			.replacingOccurrences(of: "(", with: "")

Sources/Model/ConventionalCommit.swift

@@ -0,0 +1,41 @@
+import Foundation
+
+/// Errors related to git operations.
+public enum GitError: LocalizedError {
+	case repositoryNotFound
+	case invalidRepository
+	case gitCommandFailed(String, exitCode: Int)
+	case noCommitsFound
+	case tagOperationFailed
+
+	public var errorDescription: String? {
+		switch self {
+		case .repositoryNotFound:
+			return "No git repository found in current directory"
+		case .invalidRepository:
+			return "Invalid git repository structure"
+		case .gitCommandFailed(let command, let exitCode):
+			return "Git command '\(command)' failed with exit code \(exitCode)"
+		case .noCommitsFound:
+			return "No commits found in repository"
+		case .tagOperationFailed:
+			return "Failed to read git tags"
+		}
+	}
+
+	public var recoverySuggestion: String? {
+		switch self {
+		case .repositoryNotFound:
+			return "Ensure you're running this command from within a git repository"
+		case .invalidRepository:
+			return
+				"Check that the git repository is properly initialized and not corrupted"
+		case .gitCommandFailed(let command, _):
+			return "Check git status and ensure '\(command)' can be run manually"
+		case .noCommitsFound:
+			return "Ensure the repository has commits and you have access to them"
+		case .tagOperationFailed:
+			return "Check that git tags exist and are accessible"
+		}
+	}
+}

Sources/Model/GitError.swift

@@ -0,0 +1,38 @@
+import Foundation
+
+/// Errors related to parsing conventional commits and semantic versions.
+public enum ParseError: LocalizedError {
+	case invalidConventionalCommit(commit: String, reason: String)
+	case invalidSemanticVersion(tag: String)
+	case malformedCommitMessage(hash: String, subject: String)
+	case unsupportedCommitType(type: String, commit: String)
+	case noFormattedCommits(String)
+
+	public var errorDescription: String? {
+		switch self {
+		case .invalidConventionalCommit(let commit, let reason):
+			return "Invalid conventional commit '\(commit)': \(reason)"
+		case .invalidSemanticVersion(let tag):
+			return "Tag '\(tag)' is not a valid semantic version"
+		case .malformedCommitMessage(let hash, let subject):
+			return "Commit \(hash) has malformed message: '\(subject)'"
+		case .unsupportedCommitType(let type, let commit):
+			return "Unsupported commit type '\(type)' in commit: \(commit)"
+		case .noFormattedCommits(let message):
+			return message
+		}
+	}
+
+	public var recoverySuggestion: String? {
+		switch self {
+		case .invalidConventionalCommit, .malformedCommitMessage:
+			return "Check conventional commit format: https://conventionalcommits.org"
+		case .invalidSemanticVersion:
+			return "Ensure tags follow semantic versioning format (e.g., 1.0.0, v2.1.3)"
+		case .unsupportedCommitType:
+			return "Use supported commit types: feat, fix, hotfix, or chore"
+		case .noFormattedCommits:
+			return "Ensure at least one commit follows conventional commit format"
+		}
+	}
+}

Sources/Model/ParseError.swift

@@ -30,7 +30,7 @@ public struct Parser {
 			}
 			//      print("Conventional commits since last branch: \(conventionalCommitsSinceLastBranch)")
 			if conventionalCommitsSinceLastBranch.count == 0 {
-				throw ParserError.noFormattedCommits(noFormattedCommitsErrorMessage)
+				throw ParseError.noFormattedCommits(noFormattedCommitsErrorMessage)
 			}
 		}
 
@@ -41,7 +41,7 @@ public struct Parser {
 		}
 
 		guard conventionalCommits.count > 0 else {
-			throw ParserError.noFormattedCommits(noFormattedCommitsErrorMessage)
+			throw ParseError.noFormattedCommits(noFormattedCommitsErrorMessage)
 		}
 
 		let lastSemanticVersion =
@@ -68,7 +68,7 @@ public struct Parser {
 		} else if conventionalCommits.isEmpty == false {
 			bumpType = .none
 		} else {
-			throw ParserError.noFormattedCommits(noFormattedCommitsErrorMessage)
+			throw ParseError.noFormattedCommits(noFormattedCommitsErrorMessage)
 		}
 
 		let nextSemanticVersion = lastSemanticVersion.bump(bumpType)
@@ -81,15 +81,3 @@ public struct Parser {
 		)
 	}
 }
-
-public enum ParserError: LocalizedError {
-	case noFormattedCommits(String)
-
-	/// No overview available.
-	public var errorDescription: String? {
-		switch self {
-		case let .noFormattedCommits(errorMessage):
-			return errorMessage
-		}
-	}
-}