chess_engine_rb 0.1.1

data/lib/chess_engine/event_handlers/move_event_handler.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require_relative 'base_event_handler'
+require_relative 'en_passant_event_handler'
+require_relative '../data_definitions/piece'
+require_relative '../data_definitions/square'
+require_relative '../data_definitions/events'
+require_relative '../data_definitions/primitives/colors'
+
+module ChessEngine
+  module EventHandlers
+    # Event handler for `MovePieceEvent`
+    class MoveEventHandler < BaseEventHandler
+      private
+
+      def resolve
+        return failure("#{event} is not a MovePieceEvent") unless event.is_a?(MovePieceEvent)
+
+        resolving_methods = %i[resolve_to resolve_piece handle_en_passant
+                               resolve_from resolve_captured resolve_promote_to]
+        en_passant_stop_cond = ->(result) { result.event.is_a?(MovePieceEvent) }
+        run_resolution_pipeline(*resolving_methods, handle_en_passant: en_passant_stop_cond)
+      end
+
+      # Has to have a full, valid :to
+      def resolve_to(event)
+        to = event.to
+        return failure(":to is not a valid Square: #{to}") unless to.is_a?(Square) && to.valid?
+
+        piece_at_to = board.get(to)
+        if piece_at_to&.color == current_color || piece_at_to&.type == :king || (event.captured.nil? && !piece_at_to.nil?)
+          return failure("Cannot move to #{to}")
+        end
+
+        success(event)
+      end
+
+      def resolve_piece(event)
+        return failure(":piece is not a Piece: #{event.piece}") unless event.piece.is_a?(Piece) || event.piece.nil?
+        return failure("Wrong color: #{event.piece.color}") unless [nil, current_color].include?(event.piece&.color)
+
+        piece_color = current_color
+        piece_type = event.piece&.type || :pawn # Default to pawn if no piece specified
+
+        # Validate piece type
+        unless Piece::TYPES.include?(piece_type)
+          return failure("Invalid piece type: #{piece_type}. Must be one of: #{Piece::TYPES.join(', ')}")
+        end
+
+        piece = Piece[piece_color, piece_type]
+        success(event.with(piece: piece))
+      end
+
+      def resolve_from(event)
+        return failure(":from is not a `Square`: #{event.from}") unless event.from.is_a?(Square) || event.from.nil?
+
+        # Determine the appropriate method to get piece moves,
+        # either `Piece#moves` or `Piece#threatened_squares`
+        piece_moves_method = board.get(event.to).nil? ? :moves : :threatened_squares
+        filtered_pieces = board.pieces_with_squares(color: event.piece.color, type: event.piece.type).select do |_p, s|
+          event.from.nil? || event.from.matches?(s)
+        end
+
+        # Filter pieces that can move to the destination
+        filtered_pieces = filtered_pieces.select do |p, s|
+          piece_moves = p.send(piece_moves_method, board, s)
+          piece_moves.any? { event.to == it }
+        end
+
+        return failure('Invalid piece at :from') if filtered_pieces.empty?
+        if filtered_pieces.size > 1
+          return failure(":from square disambiguation faild: too many pieces: #{filtered_pieces.inspect}")
+        end
+
+        _p, from = filtered_pieces.first
+        unless event.from.nil? || event.from.matches?(from)
+          return failure("Invalid :from square given: #{event.from}. Should be: #{from}")
+        end
+
+        success(event.with(from: from))
+      end
+
+      # Delegate to `EnPassantEventHandler` as needed
+      def handle_en_passant(event)
+        return success(event) unless should_en_passant?(event)
+
+        EnPassantEventHandler.call(@query, EnPassantEvent[event.piece.color, event.from, event.to])
+      end
+
+      def resolve_captured(event)
+        captured = event.captured
+        return success(event) if captured.nil?
+
+        return failure(":captured is of type #{captured.class}, not CaptureData") unless captured.is_a?(Events::CaptureData)
+        unless captured.square.nil? || captured.square.is_a?(Square)
+          return failure(":captured.square is not a Square: #{captured.square}")
+        end
+        unless captured.piece.nil? || captured.piece.is_a?(Piece)
+          return failure(":captured.piece is not a Piece: #{captured.piece}")
+        end
+        return failure('Invalid captured square') unless captured.square.nil? || captured.square.matches?(event.to)
+
+        captured_square = event.to
+        captured_piece = board.get(event.to)
+
+        unless [nil, other_color].include?(captured.piece&.color) &&
+               [nil, captured_piece&.type].include?(captured.piece&.type)
+          return failure("Invalid captured piece: #{captured.piece}, should be #{captured_piece}")
+        end
+        return failure("No piece to capture at #{captured_square}") if captured_piece.nil?
+
+        success(event.with(captured: Events::CaptureData[captured_square, captured_piece]))
+      end
+
+      def resolve_promote_to(event)
+        promote_to = event.promote_to
+        unless should_promote?(event)
+          return success(event) if promote_to.nil?
+
+          return failure("Given promotion, but cannot promote #{event.piece.type} at #{event.to}")
+        end
+
+        return failure("Pawn move to #{event.to} requires promotion") if promote_to.nil?
+
+        unless Piece::PROMOTION_TYPES.include?(promote_to)
+          return failure("Invalid promotion piece type: #{promote_to}. Needs to be one of: #{Piece::PROMOTION_TYPES.join(', ')}")
+        end
+
+        success(event)
+      end
+
+      def should_en_passant?(event)
+        position.en_passant_target && (event.piece.type == :pawn) && !event.captured.nil? &&
+          event.to == position.en_passant_target && event.promote_to.nil? &&
+          board.get(event.to).nil?
+      end
+
+      def should_promote?(event)
+        event.piece.type == :pawn &&
+          ((current_color == :white && event.to.rank == 8) || (current_color == :black && event.to.rank == 1))
+      end
+    end
+  end
+end

data/lib/chess_engine/formatters/eran_formatters.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require 'immutable'
+require_relative 'validation'
+require_relative '../data_definitions/primitives/core_notation'
+
+module ChessEngine
+  module Formatters
+    # Provides formatters for ERAN, a custom chess notation made for this engine.
+    #
+    # ERAN supports both long and short forms for many constructs; this module exposes formatters for each style.
+    # See the docs for ERAN for more details.
+    module ERANFormatters
+      extend self
+
+      PROMOTION_PREFIX = { long: '->', short: '>' }.freeze
+      EN_PASSANT = { long: 'en-passant', short: 'ep' }.freeze
+      CASTLING = Immutable.from(
+        {
+          long: {
+            kingside: 'castling-kingside',
+            queenside: 'castling-queenside'
+          },
+          short: {
+            kingside: 'ck',
+            queenside: 'cq'
+          }
+        }
+      )
+
+      # Since ERAN is case-insensitive, capitalizing piece type is only for aesthetic.
+      PIECE_TYPES = Immutable.from(
+        { long: Piece::TYPES.to_h { [it, it.to_s.capitalize] },
+          short: CoreNotation::PIECE_MAP }
+      )
+
+      def format(event, verbosity)
+        case event
+        in MovePieceEvent
+          format_move_piece_event(event, PIECE_TYPES[verbosity], PROMOTION_PREFIX[verbosity])
+        in EnPassantEvent
+          EN_PASSANT[verbosity]
+        in CastlingEvent
+          CASTLING[verbosity][event.side]
+        else
+          nil
+        end
+      end
+
+      def format_move_piece_event(event, piece_types, promotion_prefix) # rubocop:disable Metrics/AbcSize
+        return unless Validation.well_formed_move_piece?(event)
+
+        piece_type = piece_types[event.piece.type]
+        move_type = event.captured.nil? ? '-' : 'x'
+        movement = CoreNotation.square_to_str(event.from) + move_type + CoreNotation.square_to_str(event.to)
+        promotion = event.promote_to ? promotion_prefix + piece_types[event.promote_to] : nil
+
+        [piece_type, movement, promotion].compact.join(' ')
+      end
+
+      private :format, :format_move_piece_event
+
+      # The actual formatters
+      LONG = ->(event, _query = nil) { format(event, :long) }
+      SHORT = ->(event, _query = nil) { format(event, :short) }
+    end
+
+    ERANLongFormatter = ERANFormatters::LONG
+    ERANShortFormatter = ERANFormatters::SHORT
+  end
+end

data/lib/chess_engine/formatters/init.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative 'eran_formatters'
+
+module ChessEngine
+  # Namespace for all chess notation formatters.
+  #
+  # Formatters convert fully-populated `Events::BaseEvent` objects into a single-move notation.
+  # The output must be a valid notation for a single move that accurately reflects the given event.
+  #
+  # It expects the event to be structurally valid:
+  # all fields and nested objects must be well-formed.
+  # Certain formatters and notations might also require the move to be valid under the game context.
+  #
+  # Each formatter should implement `.call(event, game_query)`, returning the corresponding notation,
+  #  or `nil` if the event cannot be parsed.
+  module Formatters
+  end
+end

data/lib/chess_engine/formatters/validation.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative '../data_definitions/piece'
+require_relative '../data_definitions/square'
+require_relative '../data_definitions/primitives/colors'
+require_relative '../data_definitions/primitives/castling_data'
+
+module ChessEngine
+  module Formatters
+    # Utilities for checking the structural validity of the given event
+    module Validation
+      module_function
+
+      # --- Shallow validity: basic fields required for most notation ---
+      # Only checks presence and immediate validity of fields, not nested captured pieces, color, etc.
+      def well_formed_move_piece?(event)
+        Piece::TYPES.include?(event.piece&.type) &&
+          square_and_valid?(event.from) &&
+          square_and_valid?(event.to) &&
+          (event.promote_to.nil? || Piece::PROMOTION_TYPES.include?(event.promote_to))
+      end
+
+      def well_formed_en_passant?(_event)
+        true # Most notations don't need any special validation for en passant
+      end
+
+      def well_formed_castling?(event)
+        CastlingData::SIDES.include?(event.side)
+      end
+
+      # --- Full validity: all nested fields and optional data are checked ---
+      # Useful when you want to ensure the event is completely well-formed for any purpose.
+      def fully_well_formed_move_piece?(event)
+        well_formed_move_piece?(event) && Colors.valid?(event.piece.color) &&
+          (event.captured.nil? || (square_and_valid?(event.captured.square) && piece_and_valid?(event.captured.piece)))
+      end
+
+      def fully_well_formed_en_passant?(event)
+        Colors.valid?(event.color) &&
+          (event.from.nil? || square_and_valid?(event.from)) &&
+          (event.to.nil? || square_and_valid?(event.to))
+      end
+
+      def fully_well_formed_castling?(event)
+        well_formed_castling?(event) && Colors.valid?(event.color)
+      end
+
+      # --- Components helpers ---
+      # Validate basic pieces or squares
+      def piece_and_valid?(piece) = piece.is_a?(Piece) && piece.valid?
+      def square_and_valid?(square) = square.is_a?(Square) && square.valid?
+    end
+  end
+end

data/lib/chess_engine/game/history.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'immutable'
+require_relative '../data_definitions/position'
+
+module ChessEngine
+  module Game
+    # Encapsulates all of the game's history, from a certain point up to a current point.
+    #
+    # Includes:
+    # - `start_position`: a `Position` object representing the position from which the history started.
+    # - `moves` - an `Enumerable` of events that happened up until the current point.
+    # - `position_signatures` - a hash of position signatures,
+    #      that counts how much times each one occurred up to this point.
+    History = Data.define(:start_position, :moves, :position_signatures) do
+      def initialize(moves:, position_signatures: Immutable::Hash[], start_position: Position.start)
+        moves = Immutable.from moves
+        position_signatures = Immutable.from position_signatures
+        super
+      end
+
+      def self.start = new(Position.start, Immutable::List[], Immutable::Hash[])
+    end
+  end
+end

data/lib/chess_engine/game/init.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative 'state'
+require_relative 'query'
+require_relative 'history'
+
+module ChessEngine
+  # Contains the core abstractions for representing and manipulating chess game state.
+  # The main entry point is `State`, which models the entire game at a given moment.
+  # Other components (`Query`, `History`) are dependencies of `State` but can be used standalone if needed.
+  #
+  # For details and usage, see the documentation in `State`.
+  module Game
+  end
+end

data/lib/chess_engine/game/legal_moves_helper.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require_relative '../errors'
+require_relative '../data_definitions/piece'
+require_relative '../data_definitions/events'
+require_relative '../data_definitions/primitives/colors'
+require_relative '../data_definitions/primitives/castling_data'
+
+module ChessEngine
+  module Game
+    class Query
+      # Implements the method `#legal_moves` for `Query`,
+      # which generates all legal moves for the given color.
+      module LegalMovesHelper
+        def legal_moves(color = @position.current_color)
+          return INVALID_ARGUMENT unless Colors.valid?(color)
+          return enum_for(__method__, color) unless block_given?
+
+          each_pseudo_legal_event(color).each do |event|
+            yield event unless state.apply_event(event).query.in_check?(color)
+          rescue InvalidEventError
+            next # Malformed events are considered illegal moves
+          end
+        end
+
+        private
+
+        # A pseudo-legal move is a move that is valid according to the rules of chess,
+        # except that it does not account for whether the move would leave the king in check.
+        def each_pseudo_legal_event(color, &)
+          return enum_for(__method__, color) unless block_given?
+
+          board.pieces_with_squares(color: color).each do |piece, square|
+            each_move_only_event(piece, square, &)
+            each_capture_event(piece, square, &)
+          end
+
+          each_enpassant_event(color, &)
+          each_castling_event(color, &)
+        end
+
+        def each_move_only_event(piece, square, &)
+          to_squares = piece.moves(board, square).select { board.get(it).nil? }
+
+          each_move_event(piece, square, to_squares, &)
+        end
+
+        def each_capture_event(piece, square, &)
+          capturable_squares = piece.threatened_squares(board, square).select do |target_square|
+            target_piece = board.get(target_square)
+            !target_piece.nil? && piece.color != target_piece.color
+          end
+
+          each_move_event(piece, square, capturable_squares) do |event|
+            yield event.capture(event.to, board.get(event.to))
+          end
+        end
+
+        def each_move_event(piece, square, to_squares, &)
+          to_squares.each do |target_square|
+            event = MovePieceEvent[piece, square, target_square]
+
+            if move_should_promote?(piece, target_square)
+              each_promotion_event(event, &)
+            else
+              yield event
+            end
+          end
+        end
+
+        def each_promotion_event(event, &)
+          Piece::PROMOTION_TYPES.each do |piece_type|
+            yield event.promote(piece_type)
+          end
+        end
+
+        def each_enpassant_event(color, &)
+          return unless can_en_passant?(color)
+
+          rank_offset = color == :white ? -1 : 1
+          [1, -1].each do |file_offset|
+            square = position.en_passant_target.offset(file_offset, rank_offset)
+            next unless square.valid? && board.get(square) == Piece[color, :pawn]
+
+            yield EnPassantEvent[color, square, position.en_passant_target]
+          end
+        end
+
+        def each_castling_event(color)
+          CastlingData::SIDES.each do |side|
+            next unless castling_available?(color, side)
+
+            yield CastlingEvent[color, side]
+          end
+        end
+
+        def move_should_promote?(piece, target_pos)
+          piece.type == :pawn &&
+            ((piece.color == :white && target_pos.rank == 8) ||
+            (piece.color == :black && target_pos.rank == 1))
+        end
+
+        def can_en_passant?(color)
+          position.en_passant_target && (
+            (color == :white && position.en_passant_target.rank == 6) ||
+            (color == :black && position.en_passant_target.rank == 3)
+          )
+        end
+
+        def castling_available?(color, side)
+          has_rights = @position.castling_rights.sides(color).public_send(side)
+          return false unless has_rights
+
+          king_is_attacked = CastlingData.king_path(color, side).any? do |sq|
+            square_attacked?(sq, position.other_color)
+          end
+          path_is_clear = CastlingData.intermediate_squares(color, side).all? do |sq|
+            board.get(sq).nil?
+          end
+
+          !king_is_attacked && path_is_clear
+        end
+      end
+    end
+  end
+end

data/lib/chess_engine/game/query.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require 'immutable'
+require_relative 'state'
+require_relative 'history'
+require_relative 'legal_moves_helper'
+require_relative '../data_definitions/square'
+require_relative '../data_definitions/position'
+require_relative '../data_definitions/primitives/colors'
+
+module ChessEngine
+  module Game
+    # Provides derived information about the current game state.
+    #
+    # `Query` acts as the single entry point for all game-related queries.
+    # It exposes methods for:
+    # - **legal moves enumeration** (`legal_moves(color)`)
+    # - **Check and checkmate detection** (`in_check?`, `in_checkmate?`)
+    # - **draw detection** ( `must_draw?`, `in_draw?`, and detailed draw queries like `stalemate?` )
+    # - **Pieces and squares relations** (`piece_attacking?`, `piece_can_move?`, `square_attacked?`)
+    class Query
+      include LegalMovesHelper
+
+      INVALID_ARGUMENT = :invalid
+      attr_reader :position, :history
+
+      def initialize(position, history = History.start)
+        unless position.is_a?(Position) && history.is_a?(History)
+          raise ArgumentError,
+                "One or more invalid arguments for Game::Query: #{position}, #{history}"
+        end
+
+        @position = position
+        @history = history
+      end
+
+      def with(position: @position, history: @history)
+        self.class.new(position, history)
+      end
+
+      def state
+        @state ||= State.new(position: position, history: history)
+      end
+
+      # For easier access
+      def board = position.board
+      def position_signatures = history.position_signatures
+
+      # Determine whether a piece at square "from" can move to "to" without capturing,
+      # not taking into account other considerations like pins.
+      def piece_can_move?(from, to)
+        return INVALID_ARGUMENT unless valid_square?(from) && valid_square?(to)
+
+        piece = board.get(from)
+        board.find_pieces.include?(piece) && board.get(to).nil? && piece.moves(board, from).include?(to)
+      end
+
+      # Determines if a piece at the given square is attacking a target square.
+      def piece_attacking?(from, target_square)
+        return INVALID_ARGUMENT unless valid_square?(from) && valid_square?(target_square)
+
+        piece = board.get(from)
+        target_piece = board.get(target_square)
+        return false unless piece && piece.color != target_piece&.color
+
+        piece.threatened_squares(board, from).include?(target_square)
+      end
+
+      # Determines whether the given square is attacked by a piece of the specified color
+      def square_attacked?(attacked_square, color = @position.other_color)
+        return INVALID_ARGUMENT unless valid_square?(attacked_square) && Colors.valid?(color)
+
+        other_pieces_squares = board.pieces_with_squares(color: color)
+        other_pieces_squares.any? do |_p, attacking_square|
+          piece_attacking?(attacking_square, attacked_square)
+        end
+      end
+
+      # returns true if the king of the specified color is in check
+      def in_check?(color = @position.current_color)
+        return INVALID_ARGUMENT unless Colors.valid?(color)
+
+        _k, king_square = board.pieces_with_squares(color: color, type: :king).first
+        square_attacked?(king_square, Colors.flip(color))
+      end
+
+      # returns true if the king of the specified color is in checkmate
+      def in_checkmate?(color = @position.current_color)
+        return INVALID_ARGUMENT unless Colors.valid?(color)
+
+        in_check?(color) && legal_moves(color).none?
+      end
+
+      # Returns true if the game must end in a draw
+      def must_draw?
+        stalemate? || insufficient_material? || fivefold_repetition?
+      end
+
+      # returns true if the current player can request a draw to force the game to end
+      def can_draw?
+        threefold_repetition? || fifty_move_rule?
+      end
+
+      # returns true if the game is in stalemate
+      def stalemate?
+        !in_check? && legal_moves(@position.current_color).none?
+      end
+
+      # According to FIDE rules, as listed here:
+      # https://www.chess.com/terms/draw-chess#dead-position
+      def insufficient_material?
+        white_types = board.find_pieces(color: :white).map(&:type)
+        black_types = board.find_pieces(color: :black).map(&:type)
+
+        INSUFFICIENT_COMBINATIONS.any? do |combo|
+          match_combination?(white_types, black_types, combo) ||
+            match_combination?(black_types, white_types, combo)
+        end
+      end
+
+      # Added by FIDE in 2014
+      def fivefold_repetition?
+        @history.position_signatures.fetch(@position.signature, 0) >= 5
+      end
+
+      def threefold_repetition?
+        @history.position_signatures.fetch(@position.signature, 0) >= 3
+      end
+
+      def fifty_move_rule?
+        @position.halfmove_clock >= 100
+      end
+
+      INSUFFICIENT_COMBINATIONS = [
+        [%i[king], %i[king]],
+        [%i[king bishop], %i[king]],
+        [%i[king knight], %i[king]],
+        [%i[king bishop], %i[king bishop], :same_color_bishops]
+      ].freeze
+
+      private
+
+      # Match piece type combination for #insufficient_material?
+      def match_combination?(types1, types2, combo)
+        pattern1, pattern2, condition = combo
+        return false unless types1.sort == pattern1.sort && types2.sort == pattern2.sort
+
+        condition == :same_color_bishops ? same_color_bishops? : true
+      end
+
+      # Returns true if both sides have bishops on the same color squares
+      # (only relevant when each side has exactly one bishop)
+      # Used in #insufficient_material?
+      def same_color_bishops?
+        bishop_pos1 = board.pieces_with_squares(color: :white, type: :bishop).first&.last
+        bishop_pos2 = board.pieces_with_squares(color: :black, type: :bishop).first&.last
+        return false unless bishop_pos1 && bishop_pos2
+
+        file_distance, rank_distance = bishop_pos1.distance(bishop_pos2)
+        (file_distance + rank_distance).even?
+      end
+
+      def valid_square?(square)
+        square.is_a?(Square) && square.valid?
+      end
+    end
+  end
+end