feat: NCS-13 Implement Threefold Repetition (#31)

Reviewed-on: #31

modules/rule/src/main/scala/de/nowchess/rules/RuleSet.scala

@@ -32,6 +32,9 @@ trait RuleSet:
   /** True if halfMoveClock >= 100 (50-move rule). */
   def isFiftyMoveRule(context: GameContext): Boolean
 
+  /** True if the same position has occurred 3 times (including current position). */
+  def isThreefoldRepetition(context: GameContext): Boolean
+
   /** Apply a legal move to produce the next game context. Handles all special move types: castling, en passant,
     * promotion. Updates castling rights, en passant square, half-move clock, turn, and move history.
     */

modules/rule/src/main/scala/de/nowchess/rules/sets/DefaultRules.scala

@@ -11,6 +11,14 @@ import scala.annotation.tailrec
   */
 object DefaultRules extends RuleSet:
 
+  /** Represents a position for threefold repetition (board state + turn + castling + en passant). */
+  private case class Position(
+      board: Board,
+      turn: Color,
+      castlingRights: CastlingRights,
+      enPassantSquare: Option[Square],
+  )
+
   // ── Direction vectors ──────────────────────────────────────────────
   private val RookDirs: List[(Int, Int)]   = List((1, 0), (-1, 0), (0, 1), (0, -1))
   private val BishopDirs: List[(Int, Int)] = List((1, 1), (1, -1), (-1, 1), (-1, -1))
@@ -62,6 +70,46 @@ object DefaultRules extends RuleSet:
   override def isFiftyMoveRule(context: GameContext): Boolean =
     context.halfMoveClock >= 100
 
+  override def isThreefoldRepetition(context: GameContext): Boolean =
+    val currentPosition = Position(
+      board = context.board,
+      turn = context.turn,
+      castlingRights = context.castlingRights,
+      enPassantSquare = context.enPassantSquare,
+    )
+    countPositionOccurrences(context, currentPosition) >= 3
+
+  private def countPositionOccurrences(context: GameContext, targetPosition: Position): Int =
+    try
+      var count     = 0
+      var tempCtx   = GameContext(
+        board = context.initialBoard,
+        turn = Color.White,
+        castlingRights = CastlingRights.Initial,
+        enPassantSquare = None,
+        halfMoveClock = 0,
+        moves = List.empty,
+        initialBoard = context.initialBoard,
+      )
+      var tempPos   = Position(tempCtx.board, tempCtx.turn, tempCtx.castlingRights, tempCtx.enPassantSquare)
+      if tempPos == targetPosition then count += 1
+
+      for move <- context.moves do
+        tempCtx = applyMove(tempCtx)(move)
+        tempPos = Position(
+          board = tempCtx.board,
+          turn = tempCtx.turn,
+          castlingRights = tempCtx.castlingRights,
+          enPassantSquare = tempCtx.enPassantSquare,
+        )
+        if tempPos == targetPosition then count += 1
+
+      count
+    catch
+      case _: Exception =>
+        // If replay fails, conservatively count only the current position (never triggers a draw)
+        1
+
   // ── Sliding pieces (Bishop, Rook, Queen) ───────────────────────────
 
   private def slidingMoves(

modules/rule/src/test/scala/de/nowchess/rule/DefaultRulesTest.scala

@@ -175,3 +175,48 @@ class DefaultRulesTest extends AnyFunSuite with Matchers:
 
     // White is in check; only moves that block or move the king are legal
     moves.nonEmpty shouldBe true
+
+  // ── Threefold Repetition ─────────────────────────────────────────
+
+  test("threefold repetition returns false for initial position with no moves"):
+    val context = GameContext.initial
+    rules.isThreefoldRepetition(context) shouldBe false
+
+  test("threefold repetition returns false after single move"):
+    val fen     = "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1"
+    val context = FenParser.parseFen(fen).fold(_ => fail(), identity)
+    val move1   = Move(Square(File.E, Rank.R2), Square(File.E, Rank.R4))
+    val ctx1    = rules.applyMove(context)(move1)
+
+    rules.isThreefoldRepetition(ctx1) shouldBe false
+
+  test("threefold repetition detects repeated position after back-and-forth moves"):
+    // Both knights shuffle back and forth: initial position (White to move) occurs 3 times
+    val fen     = "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1"
+    val context = FenParser.parseFen(fen).fold(_ => fail(), identity)
+
+    val nf3 = Move(Square(File.G, Rank.R1), Square(File.F, Rank.R3))
+    val nf6 = Move(Square(File.G, Rank.R8), Square(File.F, Rank.R6))
+    val ng1 = Move(Square(File.F, Rank.R3), Square(File.G, Rank.R1))
+    val ng8 = Move(Square(File.F, Rank.R6), Square(File.G, Rank.R8))
+
+    // After 8 moves the starting position (White to move, both knights home) has occurred 3 times
+    val ctx = List(nf3, nf6, ng1, ng8, nf3, nf6, ng1, ng8)
+      .foldLeft(context)(rules.applyMove(_)(_))
+
+    rules.isThreefoldRepetition(ctx) shouldBe true
+
+  test("threefold repetition catch block returns false for inconsistent context"):
+    // A context whose moves cannot be replayed from initialBoard (forces the catch path)
+    val m = Move(Square(File.E, Rank.R5), Square(File.E, Rank.R6))  // e5→e6, no pawn there in initial board
+    val brokenCtx = GameContext(
+      board = Board.initial,
+      turn = Color.White,
+      castlingRights = CastlingRights.Initial,
+      enPassantSquare = None,
+      halfMoveClock = 0,
+      moves = List(m),
+      initialBoard = Board.initial,
+    )
+    // Replay will fail → catch returns 1 → 1 >= 3 is false
+    rules.isThreefoldRepetition(brokenCtx) shouldBe false