chess_engine_rb 0.1.1

data/lib/chess_engine/game/state.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+require 'immutable'
+require_relative 'query'
+require_relative 'history'
+require_relative '../errors'
+require_relative '../data_definitions/piece'
+require_relative '../data_definitions/square'
+require_relative '../data_definitions/board'
+require_relative '../data_definitions/position'
+require_relative '../data_definitions/events'
+require_relative '../data_definitions/primitives/colors'
+require_relative '../data_definitions/primitives/castling_data'
+
+module ChessEngine
+  module Game
+    # Represents the immutable state of the game at a specific point in time.
+    #
+    # Holds all the information needed to fully describe the current state of a chess game:
+    # the board layout, which player's turn it is, history, castling rights, en passant target, and more.
+    #
+    # Responsibilities:
+    # - Answer queries about the current position (through the `Game::Query` object).
+    # - Produce the next `State` by applying a valid event (`#apply_event`).
+    #
+    # Internal structure:
+    # - position: A `Position` object representing the current game position
+    # - history: A `Game::History` object representing all that happened since the creation of the originating `State`.
+    # - query: A `Game::Query` object that provides a high-level interface for interrogating the state.
+    #
+    # The design avoids mutable state — each change produces a new `State`, leaving previous states untouched.
+    # This makes reasoning about the engine easier and enables features like undo and state comparison.
+    class State
+      attr_reader :query, :position, :history
+
+      # The state at the game's start
+      def self.start
+        State.new(position: Position.start, history: History.start)
+      end
+
+      # Load a new gamestate from position. Suitable for FEN.
+      def self.load(position)
+        history = History.start.with(start_position: position)
+        State.new(position: position, history: history)
+      end
+
+      # Make a new `State` from an existing one.
+      # Good for computations requiring forking the state.
+      def with(position: @position, history: @history)
+        State.new(position: position, history: history)
+      end
+
+      # Low-level initialization, loads all fields. Use with caution.
+      def initialize(position: Position.start, history: History.start)
+        unless position.is_a?(Position) && history.is_a?(History)
+          raise ArgumentError,
+                "One or more invalid arguments: #{position}, #{history}"
+        end
+
+        @position = position
+        @history = history
+        @query = Query.new(@position, @history)
+      end
+
+      # Process an event to produce the next `State`
+      # Assumes the event is valid and complete.
+      def apply_event(event)
+        raise ArgumentError unless event.is_a?(Events::BaseEvent)
+
+        State.new(
+          position: advance_position(event),
+          history: advance_history(event)
+        )
+      end
+
+      private
+
+      def advance_history(event)
+        signatures = history.position_signatures
+        signature_count = signatures.fetch(@position.signature, 0)
+        new_signatures = signatures.put(@position.signature, signature_count + 1)
+
+        history.with(moves: history.moves.add(event), position_signatures: new_signatures)
+      end
+
+      def advance_position(event)
+        Position.new(
+          board: advance_board(event),
+          current_color: @position.other_color,
+          en_passant_target: compute_en_passant(event),
+          castling_rights: compute_castling_rights(event),
+          halfmove_clock: compute_halfmove_clock(event),
+          fullmove_number: compute_fullmove_number
+        )
+      rescue InvalidEventError; raise
+      rescue InvariantViolationError => e
+        raise InvalidEventError,
+              "Invariant violation during event application: #{e.class} - #{e.message}\nEvent: #{event}"
+      end
+
+      def advance_board(event)
+        board = @position.board
+        case event
+        in MovePieceEvent
+          advance_with_move_piece_event(board, event)
+        in EnPassantEvent => e
+          board.remove(e.captured.square).move(e.from, e.to)
+        in CastlingEvent => e
+          board.move(e.king_from, e.king_to).move(e.rook_from, e.rook_to)
+        else
+          raise InvalidEventError, "Unhandled event type: #{event.class}"
+        end
+      end
+
+      def advance_with_move_piece_event(board, event)
+        final_piece = event.promote_to ? Piece.new(event.piece.color, event.promote_to) : event.piece
+
+        # capture if applicable
+        board = board.remove(event.captured.square) if event.captured
+        # move the piece
+        board.remove(event.from).insert(final_piece, event.to)
+      end
+
+      def compute_en_passant(event)
+        # Get the last move and ensure it was a pawn moving two steps forward
+        return unless event.is_a?(MovePieceEvent) && event.piece.type == :pawn &&
+                      event.from.distance(event.to) == [0, 2]
+
+        # Return the square passed over
+        sq = Square[event.from.file, (event.from.rank + event.to.rank) / 2]
+        raise InvariantViolationError, "Invalid en passant target: #{sq}" unless sq.valid?
+
+        sq
+      end
+
+      def compute_castling_rights(event)
+        current_color_sides = castling_sides_for_current_color(event)
+        other_color_sides = castling_sides_for_other_color(event)
+        @position.castling_rights.with(@position.current_color => current_color_sides,
+                                       @position.other_color => other_color_sides)
+      end
+
+      # Helpers for computing castling rights
+      def castling_sides_for_current_color(event)
+        color = @position.current_color
+        sides = @position.castling_rights.sides color
+
+        case event
+        in MovePieceEvent => e
+          if e.piece.type == :king
+            sides.with(kingside: false, queenside: false)
+          elsif e.from == CastlingData.rook_from(color, :kingside)
+            sides.with(kingside: false)
+          elsif e.from == CastlingData.rook_from(color, :queenside)
+            sides.with(queenside: false)
+          else
+            sides
+          end
+        in CastlingEvent
+          sides.with(kingside: false, queenside: false)
+        else
+          sides
+        end
+      end
+
+      def castling_sides_for_other_color(event)
+        color = @position.other_color
+        sides = @position.castling_rights.sides color
+
+        return sides unless event.is_a?(MovePieceEvent)
+
+        captured = event.captured
+        return sides if captured.nil? || captured.piece.type != :rook
+
+        case captured.square
+        when CastlingData.rook_from(color, :kingside)
+          sides.with(kingside: false)
+        when CastlingData.rook_from(color, :queenside)
+          sides.with(queenside: false)
+        else
+          sides
+        end
+      end
+
+      def compute_halfmove_clock(event)
+        reset_clock = (event.is_a?(MovePieceEvent) && (event.piece.type == :pawn || event.captured)) ||
+                      event.is_a?(EnPassantEvent)
+
+        reset_clock ? 0 : @position.halfmove_clock + 1
+      end
+
+      def compute_fullmove_number
+        increment = @position.current_color == :black ? 1 : 0
+        @position.fullmove_number + increment
+      end
+    end
+  end
+end

data/lib/chess_engine/parsers/eran_parser.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require_relative '../data_definitions/events'
+require_relative '../data_definitions/primitives/core_notation'
+
+module ChessEngine
+  module Parsers
+    # A parser for ERAN, a notation made specifically for the engine.
+    # See the docs for more details.
+    class ERANParser
+      SQR = /[a-h][1-8]/i
+      MOVEMENT = /(?<from>#{SQR})((?<silent>-)|(?<capture>x))(?<to>#{SQR})/i
+
+      PIECE = /pawn|rook|bishop|knight|queen|king|[prbnqk]/i
+      PROMOTION = /queen|rook|bishop|knight|[qrbn]/i
+
+      REGULAR_MOVE = /
+          (?<piece>#{PIECE})\s+
+          (?<movement>#{MOVEMENT})
+          (?:\s+(?:->|>)(?<promotion>#{PROMOTION}))?
+        /x
+      SPECIAL_MOVE = /
+        (?:
+          (?<en_passant>ep|en-passant)      |
+          (?<kingside>ck|castling-kingside) |
+          (?<queenside>cq|castling-queenside)
+        )/ix
+
+      MOVE = /
+        \A\s*
+        (?:
+          (?<regular>#{REGULAR_MOVE}) |
+          (?<special>#{SPECIAL_MOVE})
+        )
+        \s*\Z
+        /ixo
+
+      class << self
+        def call(notation, _query = nil)
+          match = MOVE.match(notation)
+          return unless match
+
+          return parse_special_move(match) if match[:special]
+
+          parse_regular_move(match)
+        end
+
+        private
+
+        def parse_special_move(match)
+          if match[:en_passant]
+            EnPassantEvent[nil, nil, nil]
+          elsif match[:kingside]
+            CastlingEvent[nil, :kingside]
+          elsif match[:queenside]
+            CastlingEvent[nil, :queenside]
+          end
+        end
+
+        def parse_regular_move(match)
+          piece = Piece[nil, str_to_piece_type(match[:piece])]
+          from = CoreNotation.str_to_square(match[:from].downcase)
+          to = CoreNotation.str_to_square(match[:to].downcase)
+
+          event = MovePieceEvent[piece, from, to]
+          event = event.capture if match[:capture]
+          if (promotion = match[:promotion])
+            event = event.promote(str_to_piece_type(promotion))
+          end
+
+          event
+        end
+
+        def str_to_piece_type(str)
+          str = str.downcase
+          if Piece::TYPES.include?(str.to_sym)
+            str.to_sym
+          else
+            CoreNotation.str_to_piece(str).type
+          end
+        end
+      end
+    end
+  end
+end

data/lib/chess_engine/parsers/identity_parser.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative '../data_definitions/events'
+
+module ChessEngine
+  module Parsers
+    # A parser that returns the input event unchanged.
+    # Used primarily for testing, as it bypasses actual notation parsing
+    # and assumes the input is already valid.
+    class IdentityParser
+      def self.call(notation, _game_query)
+        return nil unless notation.is_a?(Events::BaseEvent)
+
+        notation
+      end
+    end
+  end
+end

data/lib/chess_engine/parsers/init.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative 'eran_parser'
+require_relative 'identity_parser'
+
+module ChessEngine
+  # Namespace for all chess notation parsers.
+  #
+  # Parsers convert notation input into syntactically correct `Events::BaseEvent` objects.
+  # The output must accurately reflect the provided notation, but need not ensure
+  # that the move is *legally valid* within the game — legality is verified later
+  # by the engine.
+  #
+  # Each parser should implement `.call(notation, game_query)`, returning a syntactically valid event
+  # for the given notation, or `nil` if the notation cannot be parsed.
+  #
+  # A syntactically correct event is a `Events::BaseEvent` for which every provided field is of the expected type,
+  # or `nil`.
+  module Parsers
+  end
+end

data/lib/chess_engine_rb.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'pathname'
+lib_dir = Pathname.new(__FILE__).dirname.expand_path
+
+$LOAD_PATH.unshift(lib_dir.to_s) unless $LOAD_PATH.include?(lib_dir.to_s)
+
+# Main namespace for the engine.
+# Contains all core logic, data definitions, parsers, and more.
+module ChessEngine
+  # --- Main components ---
+  # Main class
+  autoload :Engine, 'chess_engine/engine'
+
+  # components
+  autoload :EventHandlers, 'chess_engine/event_handlers/init'
+  autoload :Game, 'chess_engine/game/init'
+  autoload :Parsers, 'chess_engine/parsers/init'
+  autoload :Formatters, 'chess_engine/formatters/init'
+
+  # --- Data Definitions ---
+  autoload :Piece, 'chess_engine/data_definitions/piece'
+  autoload :Square, 'chess_engine/data_definitions/square'
+  autoload :Board, 'chess_engine/data_definitions/board'
+
+  autoload :Position, 'chess_engine/data_definitions/position'
+  autoload :CastlingRights, 'chess_engine/data_definitions/components/castling_rights'
+
+  # Events
+  autoload :Events, 'chess_engine/data_definitions/events'
+  autoload :MovePieceEvent, 'chess_engine/data_definitions/events'
+  autoload :CastlingEvent, 'chess_engine/data_definitions/events'
+  autoload :EnPassantEvent, 'chess_engine/data_definitions/events'
+
+  # primitive data definitions
+  autoload :CastlingData, 'chess_engine/data_definitions/primitives/castling_data'
+  autoload :Colors, 'chess_engine/data_definitions/primitives/colors'
+  autoload :CoreNotation, 'chess_engine/data_definitions/primitives/core_notation'
+
+  # --- Errors ---
+  autoload :InvariantViolationError, 'chess_engine/errors'
+  autoload :InvalidEventError, 'chess_engine/errors'
+  autoload :BoardManipulationError, 'chess_engine/errors'
+  autoload :InvalidSquareError, 'chess_engine/errors'
+  autoload :InternalEngineError, 'chess_engine/errors'
+end

metadata

@@ -0,0 +1,112 @@
+--- !ruby/object:Gem::Specification
+name: chess_engine_rb
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- nadi726
+bindir: bin
+cert_chain: []
+date: 2025-12-08 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: immutable-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+- !ruby/object:Gem::Dependency
+  name: wholeable
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+description: |+
+  A modular, deterministic chess engine built around immutable objects.
+  Cleanly expresses chess concepts in code and designed for easy integration with any UI.
+
+  > ⚠️ Note: This is not a competitive chess engine like Stockfish.
+  While AI features could be added in the future, the core purpose of this project is to provide a ruby gem for cleanly representing chess in code.
+
+email:
+- 16650084+nadi726@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/chess_engine/data_definitions/README.md
+- lib/chess_engine/data_definitions/board.rb
+- lib/chess_engine/data_definitions/components/castling_rights.rb
+- lib/chess_engine/data_definitions/components/persistent_array.rb
+- lib/chess_engine/data_definitions/events.rb
+- lib/chess_engine/data_definitions/piece.rb
+- lib/chess_engine/data_definitions/position.rb
+- lib/chess_engine/data_definitions/primitives/castling_data.rb
+- lib/chess_engine/data_definitions/primitives/colors.rb
+- lib/chess_engine/data_definitions/primitives/core_notation.rb
+- lib/chess_engine/data_definitions/primitives/movement.rb
+- lib/chess_engine/data_definitions/square.rb
+- lib/chess_engine/engine.rb
+- lib/chess_engine/errors.rb
+- lib/chess_engine/event_handlers/base_event_handler.rb
+- lib/chess_engine/event_handlers/castling_event_handler.rb
+- lib/chess_engine/event_handlers/en_passant_event_handler.rb
+- lib/chess_engine/event_handlers/init.rb
+- lib/chess_engine/event_handlers/move_event_handler.rb
+- lib/chess_engine/formatters/eran_formatters.rb
+- lib/chess_engine/formatters/init.rb
+- lib/chess_engine/formatters/validation.rb
+- lib/chess_engine/game/history.rb
+- lib/chess_engine/game/init.rb
+- lib/chess_engine/game/legal_moves_helper.rb
+- lib/chess_engine/game/query.rb
+- lib/chess_engine/game/state.rb
+- lib/chess_engine/parsers/eran_parser.rb
+- lib/chess_engine/parsers/identity_parser.rb
+- lib/chess_engine/parsers/init.rb
+- lib/chess_engine_rb.rb
+homepage: https://github.com/nadi726/ruby-chess-engine
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/nadi726/ruby-chess-engine
+  source_code_uri: https://github.com/nadi726/ruby-chess-engine
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.4.1
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: A UI-agnostic, event-driven, mostly-immutable chess engine written in pure
+  Ruby.
+test_files: []
+...