chess_engine_rb 0.1.1

data/lib/chess_engine/engine.rb

@@ -0,0 +1,299 @@
+# frozen_string_literal: true
+
+# Core components
+require_relative 'data_definitions/position'
+require_relative 'game/init'
+require_relative 'event_handlers/init'
+require_relative 'parsers/init'
+
+module ChessEngine
+  # The `Engine` is the central coordinator and interpreter of the chess game.
+  #
+  # It interprets structured input (chess notation) and translates it into concrete
+  # state transitions, producing `GameUpdate` objects and notifying registered listeners.
+  #
+  # The engine is responsible for a single game session at a time.
+  # On initialization, you must choose the notation parser the engine will use (or use the default one).
+  #
+  # After initializing an engine, you must begin a session either by:
+  # - starting a new game with `#new_game`.
+  # - loading a game from existing state with `#from_fen` or `#load_game_state`.
+  #
+  # The game can be exported at any point with `#to_fen`.
+  #
+  # Clients advance the engine through two mechanisms:
+  # - By playing a turn, via the `#play_turn` method.
+  # - By attempting a game-ending action: offering, accepting, claiming a draw, or by resigning.
+  #   Those actions are triggered by `#offer_draw`, `#accept_draw`, `#claim_draw` and `#resign` respectively.
+  #
+  # To observe game progress, clients can:
+  # - Register as listeners and implement `#on_game_update(game_update)` to get turn-by-turn updates,
+  #   as well as error messages(a `GameUpdate.failure` object) for an invalid client operation.
+  # - call the `#last_update` method to get the last game update status.
+  class Engine # rubocop:disable Metrics/ClassLength
+    DEFAULT_PARSER = Parsers::ERANParser
+
+    def initialize(default_parser: DEFAULT_PARSER)
+      raise ArgumentError, "Not a valid `Parser`: #{default_parser}" unless default_parser.respond_to?(:call)
+
+      @listeners = []
+      @default_parser = default_parser
+    end
+
+    def add_listener(listener)
+      @listeners << listener unless @listeners.include?(listener)
+    end
+
+    def remove_listener(listener) = @listeners.delete(listener)
+
+    def default_parser(parser)
+      raise ArgumentError, "Not a valid `Parser`: #{default_parser}" unless parser.respond_to?(:call)
+
+      @default_parser = parser
+    end
+
+    # Starts a new game. Resets the game's state and starts a new session.
+    def new_game
+      load_game_state(Game::State.start)
+    end
+
+    # Starts a new game session with the given state.
+    # A lower-level operation - use with caution.
+    def load_game_state(state, offered_draw: nil)
+      update_game(
+        state: state,
+        endgame_status: detect_endgame_status(state.query),
+        offered_draw: offered_draw,
+        event: nil,
+        session: @session.nil? ? SessionInfo.started(0) : @session.next
+      )
+    end
+
+    def from_fen(fen_str)
+      position = Position.from_fen(fen_str)
+      load_game_state(Game::State.load(position))
+    end
+
+    def to_fen
+      @state.position.to_fen
+    end
+
+    # The last update that was made.
+    # Useful for directly retrieving the most recent `GameUpdate`,
+    # allowing inspection of game state changes without engaging with the listener model.
+    attr_reader :last_update
+    alias status last_update
+
+    # Plays one side’s turn.
+    #
+    # Parses the given notation, interprets the corresponding event,
+    # updates the engine’s state, and notifies listeners with a `GameUpdate`.
+    #
+    # Returns a corresponding `GameUpdate`.
+    def play_turn(notation, parser = @default_parser)
+      result = interpret_turn(notation, parser)
+      result.success? ? update_game(**result.success_attributes) : notify_listeners(result)
+      result
+    end
+
+    # Registers a draw offer from the current player.
+    # Although FIDE technically allows offering a draw at any point,
+    # the engine enforces that only the current player may do so,
+    # which results in a simpler interface and therefore makes more sense from an engine perspective.
+    def offer_draw
+      failure = detect_general_failure || (GameUpdate.failure(:draw_offer_not_allowed) if @offered_draw)
+
+      failure ? notify_listeners(failure) : update_game(offered_draw: query.position.current_color)
+    end
+
+    # Accepts a pending draw offer from the opponent and ends the game.
+    # Does nothing if no offer exists.
+    def accept_draw
+      invalid_offer = @offered_draw.nil? || @offered_draw == query&.position&.current_color
+      failure = detect_general_failure || (GameUpdate.failure(:draw_accept_not_allowed) if invalid_offer)
+
+      failure ? notify_listeners(failure) : update_game(endgame_status: GameOutcome[:draw, :agreement])
+    end
+
+    # Claims a draw by rule (50-move rule or repetition) if eligible.
+    # Does nothing if the claim is invalid.
+    def claim_draw # rubocop:disable Metrics/CyclomaticComplexity
+      eligible_cause = if query&.threefold_repetition? then :threefold_repetition
+                       elsif query&.fifty_move_rule? then :fifty_move
+                       end
+      failure = detect_general_failure || (GameUpdate.failure(:draw_claim_not_allowed) unless eligible_cause)
+
+      failure ? notify_listeners(failure) : update_game(endgame_status: GameOutcome[:draw, eligible_cause])
+    end
+
+    # Resign and end the game immediately.
+    def resign
+      failure = detect_general_failure
+      winner = query&.position&.other_color # For non-failure
+
+      failure ? notify_listeners(failure) : update_game(endgame_status: GameOutcome[winner, :resignation])
+    end
+
+    private
+
+    # Interprets a move notation through all internal processing stages.
+    # If valid, advances the engine state; Returns a `GameUpdate`.
+    def interpret_turn(notation, parser)
+      failure = detect_general_failure
+      return failure unless failure.nil?
+
+      event = parser.call(notation, @state.query)
+      return GameUpdate.failure(:invalid_notation) unless event
+
+      interpret_event(event)
+    rescue InvariantViolationError => e
+      raise InternalEngineError, "The engine encountered a problem: #{e}"
+    end
+
+    # Executes a given event.
+    #
+    # On success:
+    # - Applies event to the current `Game::State`
+    # - Returns a `GameUpdate.success` with updated fields
+    #
+    # On failure:
+    # - Returns a `GameUpdate.failure(:invalid_event)`
+    def interpret_event(event)
+      result = EventHandlers.handle(event, @state.query)
+      return GameUpdate.failure(:invalid_event) if result.failure?
+
+      state = @state.apply_event(result.event)
+      GameUpdate.success(
+        event: result.event,
+        state: state,
+        endgame_status: detect_endgame_status(state.query),
+        # Clear draw offer if the opponent just moved without accepting
+        offered_draw: state.position.current_color == @offered_draw ? nil : @offered_draw,
+        session: @session.current
+      )
+    end
+
+    # Updates the engine with the provided fields:
+    # - updates the specified subset of instance variables related to current game session
+    # - notifies listeners of the update and returns it
+    def update_game(state: :not_provided, endgame_status: :not_provided, offered_draw: :not_provided,
+                    session: :not_provided, event: :not_provided)
+      @state = state unless state == :not_provided
+      @endgame_status = endgame_status unless endgame_status == :not_provided
+      @offered_draw = offered_draw unless offered_draw == :not_provided
+      @session = session unless session == :not_provided
+      @event = event unless event == :not_provided
+      @last_update = GameUpdate.success(event: @event, state: @state, endgame_status: @endgame_status,
+                                        offered_draw: @offered_draw, session: @session)
+      notify_listeners(@last_update)
+      @last_update
+    end
+
+    def notify_listeners(game_update)
+      @listeners.each do |listener|
+        listener.on_game_update(game_update)
+      end
+      game_update
+    end
+
+    # Checks the given state for checkmate or automatic draw conditions.
+    # The provided `Game::Query` should reflect the latest position after a move,
+    # so this method always returns the endgame status resulting from the most recent update.
+    # Returns a `GameOutcome` object if the game has ended, otherwise returns nil
+    def detect_endgame_status(query)
+      return GameOutcome[query.position.other_color, :checkmate] if query.in_checkmate?
+
+      cause = if query.stalemate? then :stalemate
+              elsif query.insufficient_material? then :insufficient_material
+              elsif query.fivefold_repetition? then :fivefold_repetition
+              end
+
+      return nil if cause.nil?
+
+      GameOutcome[:draw, cause]
+    end
+
+    # General detection for invalid client action
+    def detect_general_failure
+      return GameUpdate.failure(:no_ongoing_session) unless @session
+      return GameUpdate.failure(:game_already_ended) if @endgame_status
+
+      nil
+    end
+
+    # Convenience accessor
+    def query = @state&.query
+  end
+
+  class Engine
+    # Represents the outcome of a change in the state of the game, like playing a turn or accepting a draw.
+    #
+    # On success, it contains:
+    # - The event that describes what happened.
+    # - The full `Game::State` and `Game::Query` for inspection.
+    # - The current endgame status (if any).
+    # - The current draw offer status.
+    # - Metadata about the current game session.
+    #
+    # On failure, contains only `error`, which is one of:
+    # - `:invalid_notation`
+    # - `:invalid_event`
+    # - `:game_already_ended`
+    # - `:no_ongoing_session`
+    # - `:draw_offer_not_allowed`
+    # - `:draw_accept_not_allowed`
+    # - `:draw_claim_not_allowed`
+    #
+    # Note: `error` may later be replaced with a structured object to support
+    # more detailed error handling.
+    #
+    # Typically, clients should rely on the event sequence and status fields;
+    # direct access to `Game::Query` is for specialized use cases.
+    GameUpdate = Data.define(:event, :state, :endgame_status, :offered_draw, :session, :error) do
+      def success? = error.nil?
+      def failure? = !success?
+
+      def self.success(event:, state:, endgame_status:, offered_draw:, session:)
+        new(event, state, endgame_status, offered_draw, session, nil)
+      end
+
+      def self.failure(error)
+        new(nil, nil, nil, nil, nil, error)
+      end
+
+      # A successful result has no `error` field
+      def success_attributes
+        to_h.except(:error)
+      end
+
+      # A failed result has only an `error` field
+      def failure_attributes
+        { error: error }
+      end
+
+      def game_ended? = !endgame_status.nil?
+      def in_check? = game_query.in_check?
+      def can_draw? = game_query.can_draw?
+
+      def game_query = state.query
+      def position = state.position
+      def board = position.board
+      def current_color = position.current_color
+
+      private_class_method :new # enforces use of factories
+    end
+
+    # Metadata about the current game session
+    SessionInfo = Data.define(:id, :new?) do
+      def self.ongoing(id) = new(id, false)
+      def self.started(id) = new(id, true)
+      def next = self.class.started(id + 1)
+      def current = self.class.ongoing(id)
+    end
+
+    # winner is one of: :white, :black, :draw
+    # cause is one of: :checkmate, :resignation, :agreement, :stalemate, :insufficient_material, :fivefold_repetition,
+    #                  :threefold_repetition, :fifty_move
+    GameOutcome = Data.define(:winner, :cause)
+  end
+end

data/lib/chess_engine/errors.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module ChessEngine
+  # Those are errors that should be used internally by `Engine` and its components when something goes wrong.
+  #
+  # Not to be confused with errors that are expected as part of engine-client interaction,
+  # which are a regular part of the control flow, and returned to the listeners in the form of `GameUpdate.error`.
+  module Errors
+    # A base class for the specific invariant violations below.
+    # Signifies that an invariant inside of one of the engine's components, such as `Game::State`, has been violated.
+    class InvariantViolationError < StandardError; end
+
+    # Raised when `Game::State` receives an invalid event.
+    class InvalidEventError < InvariantViolationError; end
+
+    # Raised when attempting illegal manipulations on the `Board`.
+    # (e.g., removing a piece from an empty square)
+    class BoardManipulationError < InvariantViolationError; end
+
+    # Raised when attempting to use an invalid `Square`.
+    # Note that squares can be created invalidly by design, but using them is forbidden.
+    class InvalidSquareError < InvariantViolationError; end
+
+    # Signals to the client that the engine malfunctioned internally.
+    # While the other errors are used inside the engine for communication,
+    # this is the single error that clients should see.
+    class InternalError < StandardError; end
+  end
+
+  InvariantViolationError = Errors::InvariantViolationError
+  InvalidEventError = Errors::InvalidEventError
+  BoardManipulationError = Errors::BoardManipulationError
+  InvalidSquareError = Errors::InvalidSquareError
+  InternalEngineError = Errors::InternalError
+end

data/lib/chess_engine/event_handlers/base_event_handler.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require_relative '../data_definitions/events'
+
+module ChessEngine
+  module EventHandlers
+    # Base class for all event handlers.
+    #
+    # Each handler validates an event against the current game state.
+    # It either produces a fully resolved event (suitable for application to the game state), or returns an error.
+    #
+    # Handlers are implemented as classes for convenience (shared helpers, instance context),
+    # but their public API is procedural:
+    # `.call(query, event)` runs the handler and returns an `EventResult`.
+    #
+    # Subclasses must implement `#resolve`.
+    class BaseEventHandler
+      attr_reader :query, :event
+
+      def initialize(query, event)
+        @query = query
+        @event = event
+      end
+
+      # Primary entry point.
+
+      def self.call(query, event)
+        new(query, event).call
+      end
+
+      # Validates and completes the event, returning an `EventResult`.
+      # Clients should use the class-level `.call` instead.
+      def call
+        result = resolve
+        return result if result.failure?
+
+        post_process(result.event)
+      end
+
+      private
+
+      # To be implemented by subclasses.
+      # Validates and resolves the given event into a full, valid event, suitable for `Game::State` application.
+      # Returns an `EventResult` with either the finalized event or an error.
+      def resolve
+        raise NotImplementedError
+      end
+
+      # Common post-processing logic, applied to all valid results.
+      # (e.g., flagging check or checkmate events, enforcing turn-based constraints, etc.)
+      def post_process(event)
+        return failure if next_turn_in_check?(event)
+
+        success(event)
+      end
+
+      def next_turn_in_check?(event)
+        new_query = query.state.apply_event(event).query
+        new_query.in_check?(position.current_color)
+      end
+
+      ### Helpers for subclasses
+
+      # Runs a series of resolution steps in order.
+      # Stops when out of steps, or when result doesn't match the specified condition.
+      # By default, the condition is for `result` to be successful.
+      # You can set custom stop conditions for specific steps using `stop_conditions`.
+      #
+      # `steps`: a series of method names on `self` to execute. Each step takes the event and returns an `EventResult`.
+      # `stop_conditions`: a hash where each key is a step and the value is a condition lambda.
+      def run_resolution_pipeline(*steps, **stop_conditions)
+        default_condition = lambda(&:success?)
+        result = success(event)
+        steps.each do |step|
+          result = send(step, result.event)
+          condition = stop_conditions.fetch(step, default_condition)
+          return result unless condition.call(result)
+        end
+        result
+      end
+
+      def success(event)
+        EventResult.success(event)
+      end
+
+      def failure(msg = '')
+        msg = "Message: #{msg}" unless msg.empty?
+        EventResult.failure("Invalid result for #{event.inspect}. #{msg}")
+      end
+
+      # Useful accessors
+      def board = @query.board
+      def position = query.position
+      def current_color = position.current_color
+      def other_color = position.other_color
+    end
+
+    # Represents the outcome of processing a chess event.
+    #
+    # - On success: contains the finalized event, and `error` is nil.
+    # - On failure: contains an error message (`error`), and `event` is nil.
+    EventResult = Data.define(:event, :error) do
+      def success? = error.nil?
+      def failure? = !success?
+
+      def self.success(event) = new(event, nil)
+      def self.failure(error) = new(nil, error)
+
+      private_class_method :new # enforces use of factories
+    end
+  end
+end

data/lib/chess_engine/event_handlers/castling_event_handler.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative 'base_event_handler'
+require_relative '../data_definitions/events'
+require_relative '../data_definitions/primitives/colors'
+require_relative '../data_definitions/primitives/castling_data'
+
+module ChessEngine
+  module EventHandlers
+    # Event handler for `CastlingEvent`.
+    class CastlingEventHandler < BaseEventHandler
+      private
+
+      def resolve
+        return failure("#{event} is not a CastlingEvent") unless event.is_a?(CastlingEvent)
+
+        run_resolution_pipeline(:resolve_color, :resolve_side)
+      end
+
+      def resolve_color(event)
+        return failure("Not a color: #{event.color}") unless event.color.nil? || Colors.valid?(event.color)
+        return failure("Unexpected color: #{event.color} (expected #{current_color})") if event.color == other_color
+
+        success(event.with(color: current_color))
+      end
+
+      def resolve_side(event)
+        return failure("Not a valid side: #{event.side}") unless CastlingData::SIDES.include?(event.side)
+
+        sides = position.castling_rights.sides(event.color)
+        return failure("No rights for side #{event.side}") unless sides.side?(event.side)
+
+        king_is_attacked = CastlingData.king_path(event.color, event.side).any? do |sq|
+          query.square_attacked?(sq, other_color)
+        end
+        return failure('King is under attack somewhere on the path') if king_is_attacked
+
+        path_is_clear = CastlingData.intermediate_squares(event.color, event.side).all? do |sq|
+          board.get(sq).nil?
+        end
+
+        return failure('Path between king and rook is obstructed') unless path_is_clear
+
+        success(event)
+      end
+    end
+  end
+end

data/lib/chess_engine/event_handlers/en_passant_event_handler.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require_relative 'base_event_handler'
+require_relative '../data_definitions/events'
+require_relative '../data_definitions/square'
+require_relative '../data_definitions/primitives/colors'
+
+module ChessEngine
+  module EventHandlers
+    # Event handler for `EnPassantEvent`
+    class EnPassantEventHandler < BaseEventHandler
+      private
+
+      def resolve
+        return failure("#{event} is not an EnPassantEvent") unless event.is_a?(EnPassantEvent)
+        return failure('EnPassant not available') unless en_passant_target
+
+        run_resolution_pipeline(:resolve_color, :resolve_to, :resolve_from)
+      end
+
+      def resolve_color(event)
+        return failure("Not a color: #{event.color}") unless event.color.nil? || Colors.valid?(event.color)
+        return failure("Unexpected color: #{event.color} (expected #{current_color})") if event.color == other_color
+
+        success(event.with(color: current_color))
+      end
+
+      def resolve_to(event)
+        return failure(":to is not a Square: #{event.to}") unless event.to.is_a?(Square)
+        return failure("Cannot en passant to #{event.to}") unless event.to.matches?(en_passant_target)
+
+        success(event.with(to: en_passant_target))
+      end
+
+      def resolve_from(event)
+        return failure(":from is not a Square: #{event.from}") unless event.from.nil? || event.from.is_a?(Square)
+
+        filtered_squares = determine_from(event)
+        return failure("#{event.from} is not a valid :from square for this move") if filtered_squares.empty?
+        if filtered_squares.size > 1
+          return failure("Disambiguation failed. :from (#{event.from}) could be either one of: #{filtered_squares.inspect}")
+        end
+
+        success(event.with(from: filtered_squares.first))
+      end
+
+      def determine_from(event)
+        rank_offset = event.color == :white ? -1 : 1
+        offsets = [[1, rank_offset], [-1, rank_offset]]
+        offsets.filter_map do |file_off, rank_off|
+          sq = en_passant_target.offset(file_off, rank_off)
+          sq if sq.valid? && board.get(sq) == event.piece && (event.from.nil? || event.from.matches?(sq))
+        end
+      end
+
+      def en_passant_target = position.en_passant_target
+    end
+  end
+end

data/lib/chess_engine/event_handlers/init.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative 'move_event_handler'
+require_relative 'en_passant_event_handler'
+require_relative 'castling_event_handler'
+require_relative '../errors'
+require_relative '../data_definitions/events'
+
+module ChessEngine
+  # Handles chess events by dispatching them to the appropriate event handler class.
+  #
+  # Event handling workflow:
+  # 1. The Engine provides an event representing a move or action as interpreted from user input or UI.
+  # 2. The `handle` method selects the correct handler for the event type and invokes it.
+  # 3. The handler validates the event against the current `Game::State`, resolves ambiguities, fills in missing data,
+  #    and returns an `EventResult`:
+  #    - On success: returns `EventResult.success` with a fully resolved event.
+  #    - On failure: returns `EventResult.failure` with an error message.
+  #
+  # Entry point: `handle(event, query)`
+  # Raises `InvalidEventError` if no handler exists for the event type.
+  module EventHandlers
+    # Individual handlers
+    HANDLER_MAP = {
+      MovePieceEvent => MoveEventHandler,
+      EnPassantEvent => EnPassantEventHandler,
+      CastlingEvent => CastlingEventHandler
+    }.freeze
+
+    module_function
+
+    # Get the appropriate event handler and process the event
+    def handle(event, query)
+      handler_class = HANDLER_MAP.fetch(event.class) do
+        raise InvalidEventError, "no handler for #{event}"
+      end
+
+      handler_class.call(query, event)
+    end
+  end
+end