feat(exceptions): introduce custom exceptions + minor fixes (#68)

* feat(exceptions): introduce custom exceptions for community cards and poker game logic

* feat(tests): update exception assertions to use custom exceptions in community cards and poker round tests

* feat(tests): add test for card count validation boundary in HandEvaluator

* fix(commands): catch general exceptions when creating a new game

* feat(persistence): introduce custom exceptions for file and game loading errors

* feat(interfaces): convert LoadGamePort and SaveGamePort to functional interfaces

* feat(tests): added minor tests for game actions and state management

* docs: update README to reflect command syntax changes for gameID

* refactor(tests): remove redundant initial game info retrieval in GameBettingTest

---------

Co-authored-by: dev-laky <laky.dev@proton.me>

Author: juliankuecken

README.md

@@ -153,20 +153,20 @@ Start with free 10$ and try to climb up the wealth ladder.
 
 ### Betting Commands
 
-| Command                                          | Description           |
-|--------------------------------------------------|-----------------------|
-| `poker raise 10 --game=<gameID> --player=<name>` | Raise the bet by 10   |
-| `poker call --game=<gameID> --player=<name>`     | Call the current bet  |
-| `poker check --game=<gameID> --player=<name>`    | Check (pass the turn) |
-| `poker fold --game=<gameID> --player=<name>`     | Fold the hand         |
-| `poker all-in --game=<gameID> --player=<name>`   | Go all-in             |
+| Command                                            | Description           |
+|----------------------------------------------------|-----------------------|
+| `poker raise 10 --gameID=<gameID> --player=<name>` | Raise the bet by 10   |
+| `poker call --gameID=<gameID> --player=<name>`     | Call the current bet  |
+| `poker check --gameID=<gameID> --player=<name>`    | Check (pass the turn) |
+| `poker fold --gameID=<gameID> --player=<name>`     | Fold the hand         |
+| `poker all-in --gameID=<gameID> --player=<name>`   | Go all-in             |
 
 ### Info Commands
 
-| Command                                      | Description                   |
-|----------------------------------------------|-------------------------------|
-| `poker game-info --game=<gameID>`            | Show current game information |
-| `poker hand --game=<gameID> --player=<name>` | Show the hand of the player   |
+| Command                                        | Description                   |
+|------------------------------------------------|-------------------------------|
+| `poker game-info --gameID=<gameID>`            | Show current game information |
+| `poker hand --gameID=<gameID> --player=<name>` | Show the hand of the player   |
 
 [maven]: https://maven.apache.org/
 

src/main/kotlin/hwr/oop/projects/peakpoker/commands/CreateNewGame.kt

@@ -6,7 +6,6 @@ import com.github.ajalt.clikt.parameters.options.convert
 import com.github.ajalt.clikt.parameters.options.help
 import com.github.ajalt.clikt.parameters.options.option
 import com.github.ajalt.clikt.parameters.options.required
-import hwr.oop.projects.peakpoker.core.exceptions.GameException
 import hwr.oop.projects.peakpoker.core.game.PokerGame
 import hwr.oop.projects.peakpoker.core.player.PokerPlayer
 import hwr.oop.projects.peakpoker.persistence.SaveGamePort
@@ -31,7 +30,7 @@ class CreateNewGame(private val saveGamePort: SaveGamePort) :
 
       echo("Game ID: ${gameId.value}")
       echo("New game created with players: ${game.players.joinToString(", ") { it.name }}")
-    } catch (e: GameException) {
+    } catch (e: Exception) {
       echo("Error creating game: ${e.message}")
     }
   }

src/main/kotlin/hwr/oop/projects/peakpoker/core/card/CommunityCards.kt

@@ -1,15 +1,27 @@
 package hwr.oop.projects.peakpoker.core.card
 
 import hwr.oop.projects.peakpoker.core.deck.Deck
-import hwr.oop.projects.peakpoker.core.exceptions.DuplicateCardException
-import hwr.oop.projects.peakpoker.core.exceptions.InvalidCardConfigurationException
 import hwr.oop.projects.peakpoker.core.game.RoundPhase
 import kotlinx.serialization.Serializable
 
 @Serializable
 class CommunityCards(
   private val cards: MutableList<Card> = mutableListOf(),
 ) : Iterable<Card> by cards {
+  /**
+   * Exception thrown when duplicate cards are found in the community cards
+   */
+  class DuplicateCardException(message: String) : IllegalStateException(message)
+
+  /**
+   * Exception thrown when the number of community cards is invalid
+   */
+  class InvalidCardConfigurationException(message: String) : IllegalStateException(message)
+
+  /**
+   * Exception thrown when attempting to deal community cards in an invalid round phase
+   */
+  class InvalidDealPhaseException(message: String) : IllegalStateException(message)
 
   init {
     if (cards.isNotEmpty() && cards.size !in listOf(3, 4, 5)) {
@@ -22,7 +34,7 @@ class CommunityCards(
 
   fun dealCommunityCards(roundPhase: RoundPhase, deck: Deck) {
     when (roundPhase) {
-      RoundPhase.PRE_FLOP -> throw IllegalStateException("Cannot deal community cards before the flop")
+      RoundPhase.PRE_FLOP -> throw InvalidDealPhaseException("Cannot deal community cards before the flop")
       RoundPhase.FLOP -> {
         cards.addAll(deck.draw(3))
       }
@@ -35,7 +47,7 @@ class CommunityCards(
         cards.addAll(deck.draw(1))
       }
 
-      RoundPhase.SHOWDOWN -> throw IllegalStateException("Cannot deal community cards after the showdown")
+      RoundPhase.SHOWDOWN -> throw InvalidDealPhaseException("Cannot deal community cards after the showdown")
     }
   }
 

src/main/kotlin/hwr/oop/projects/peakpoker/core/card/HoleCards.kt

@@ -1,22 +1,30 @@
 package hwr.oop.projects.peakpoker.core.card
 
-import hwr.oop.projects.peakpoker.core.exceptions.DuplicateCardException
-import hwr.oop.projects.peakpoker.core.exceptions.InvalidCardConfigurationException
 import hwr.oop.projects.peakpoker.core.player.PokerPlayer
 import kotlinx.serialization.Serializable
 import kotlinx.serialization.Transient
 
 @Serializable
 class HoleCards(
-  val cards: List<Card>,
-  @Transient val player: PokerPlayer? = null,
+    val cards: List<Card>,
+    @Transient val player: PokerPlayer? = null,
 ) : Iterable<Card> by cards {
-  init {
-    if (cards.isNotEmpty() && cards.size != 2) {
-      throw InvalidCardConfigurationException("Hole cards must be empty or contain exactly two cards.")
-    }
-    if (cards.distinct().size != cards.size) {
-      throw DuplicateCardException("Hole cards must not contain duplicates.")
+    /**
+     * Exception thrown when duplicate cards are found in the hole cards
+     */
+    class DuplicateCardException(message: String) : IllegalStateException(message)
+
+    /**
+     * Exception thrown when the number of hole cards is invalid
+     */
+    class InvalidCardConfigurationException(message: String) : IllegalStateException(message)
+
+    init {
+        if (cards.isNotEmpty() && cards.size != 2) {
+            throw InvalidCardConfigurationException("Hole cards must be empty or contain exactly two cards.")
+        }
+        if (cards.distinct().size != cards.size) {
+            throw DuplicateCardException("Hole cards must not contain duplicates.")
+        }
     }
-  }
 }

src/main/kotlin/hwr/oop/projects/peakpoker/core/card/Rank.kt

@@ -4,19 +4,19 @@ import kotlinx.serialization.Serializable
 
 @Serializable
 enum class Rank(
-  val value: Int,
+    val value: Int,
 ) {
-  TWO(1),
-  THREE(2),
-  FOUR(3),
-  FIVE(4),
-  SIX(5),
-  SEVEN(6),
-  EIGHT(7),
-  NINE(8),
-  TEN(9),
-  JACK(10),
-  QUEEN(11),
-  KING(12),
-  ACE(13)
+    TWO(1),
+    THREE(2),
+    FOUR(3),
+    FIVE(4),
+    SIX(5),
+    SEVEN(6),
+    EIGHT(7),
+    NINE(8),
+    TEN(9),
+    JACK(10),
+    QUEEN(11),
+    KING(12),
+    ACE(13)
 }

src/main/kotlin/hwr/oop/projects/peakpoker/core/card/Suit.kt

@@ -4,5 +4,5 @@ import kotlinx.serialization.Serializable
 
 @Serializable
 enum class Suit {
-  HEARTS, DIAMONDS, CLUBS, SPADES
+    HEARTS, DIAMONDS, CLUBS, SPADES
 }

src/main/kotlin/hwr/oop/projects/peakpoker/core/deck/Deck.kt

@@ -3,12 +3,16 @@ package hwr.oop.projects.peakpoker.core.deck
 import hwr.oop.projects.peakpoker.core.card.Card
 import hwr.oop.projects.peakpoker.core.card.Rank
 import hwr.oop.projects.peakpoker.core.card.Suit
-import hwr.oop.projects.peakpoker.core.exceptions.InsufficientCardsException
 import kotlinx.serialization.Serializable
 import kotlinx.serialization.Transient
 
 @Serializable
 class Deck() {
+  /**
+   * Thrown when trying to draw more cards than are available in the deck
+   */
+  class InsufficientCardsException(message: String) : IllegalStateException(message)
+
   // Create a list of all possible cards and shuffle it right away
   @Transient
   private val cards: MutableList<Card> = Suit.entries.flatMap { suit ->