chess_engine_rb 0.1.1

data/lib/chess_engine/data_definitions/piece.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require_relative 'primitives/movement'
+require_relative 'primitives/colors'
+require_relative 'primitives/core_notation'
+
+module ChessEngine
+  # Represents a single chess piece.
+  #
+  # An invalid `Piece` can be created but must not be used, as this will cause an error.
+  # Ensure validity with `#valid?` before usage.
+  class Piece
+    include Movement
+
+    ### Piece types
+    TYPES = %i[king queen rook bishop knight pawn].freeze
+
+    ### Promotable piece types
+    PROMOTION_TYPES = %i[queen knight rook bishop].freeze
+
+    attr_reader :color, :type
+
+    def initialize(color, type)
+      @color = color
+      @type = type
+    end
+
+    # Returns all valid movement destinations for this piece, excluding captures.
+    def moves(board, square)
+      each_potential_move(board, square, is_attacking: false)
+    end
+
+    # Returns all squares this piece *geometrically threatens*,
+    # regardless of whether those squares are occupied or legally capturable.
+    #
+    # This is used for threat detection like check or pins.
+    def threatened_squares(board, square)
+      each_potential_move(board, square, is_attacking: true)
+    end
+
+    def valid?
+      Colors.valid?(color) && TYPES.include?(type)
+    end
+
+    private
+
+    # Yields every square this piece could move to or attack, depending on mode.
+    def each_potential_move(board, square, is_attacking:, &)
+      return enum_for(__method__, board, square, is_attacking: is_attacking) unless block_given?
+
+      yielded = false
+      yield_special_moves(board, square, is_attacking) do |move|
+        yielded = true
+        yield move
+      end
+
+      return if yielded
+
+      deltas = adjust_for_color(is_attacking ? attacks_deltas : base_deltas)
+      deltas.each do |delta|
+        walk_deltas(delta, board, square, is_attacking: is_attacking, &)
+      end
+    end
+
+    # Yields any special-case movement squares defined for this piece,
+    # such as pawn's initial double-step. Only applied in non-attacking context.
+    def yield_special_moves(board, square, is_attacking)
+      return enum_for(__method__, board, square, is_attacking) unless block_given?
+      return if !movement[:special_moves] || is_attacking
+
+      movement[:special_moves]&.each do |special|
+        next unless special[:condition].call(self, square)
+
+        path = adjust_for_color(special[:path])
+        current = square
+        path.each do |delta|
+          current = square.offset(*delta)
+          break if !current.valid? || board.get(current)
+
+          yield current
+        end
+      end
+    end
+
+    # Walks a vector across the board and yields each step until blocked or invalid.
+    def walk_deltas(delta, board, square, is_attacking:)
+      return enum_for(__method__, delta, board, square, is_attacking: is_attacking) unless block_given?
+
+      current_square = square
+
+      loop do
+        new_square = current_square.offset(*delta)
+        break unless new_square.valid?
+
+        blocker = board.get(new_square)
+
+        if blocker
+          yield new_square if is_attacking
+          break
+        else
+          yield new_square
+        end
+
+        break unless movement[:repeat]
+
+        current_square = new_square
+      end
+    end
+
+    def movement
+      MOVEMENT[@type]
+    end
+
+    def base_deltas
+      movement[:moves] || []
+    end
+
+    def attacks_deltas
+      movement[:attacks] || base_deltas
+    end
+
+    # Flips rank deltas for black pieces to account for orientation
+    def adjust_for_color(deltas)
+      @color == :black ? deltas.map { |f, r| [f, -r] } : deltas
+    end
+
+    public
+
+    def to_s
+      return "#<Piece (INVALID) color=#{color.inspect} type=#{type.inspect}>" unless valid?
+
+      CoreNotation.piece_to_str(self)
+    end
+
+    # For cleaner test messages
+    def inspect
+      to_s
+    end
+
+    # For making `Piece` a value object
+    def ==(other)
+      other.is_a?(Piece) && color == other.color && type == other.type
+    end
+
+    def eql?(other)
+      self == other
+    end
+
+    def hash
+      [color, type].hash
+    end
+
+    # For `Piece[color, type]` syntax.
+    # Makes it clearer that this is a value object, similar to Data
+    def self.[](color, type)
+      new(color, type)
+    end
+  end
+end

data/lib/chess_engine/data_definitions/position.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require_relative 'board'
+require_relative 'primitives/colors'
+require_relative 'primitives/core_notation'
+require_relative 'components/castling_rights'
+
+module ChessEngine
+  # Namespace for `Position` and related stuff
+  module PositionModule
+    # Immutable container for all the data about the current chess position:
+    # board layout, active color, en passant target, castling rights, halfmove clock, and fullmove number.
+    Position = Data.define(
+      :board,
+      :current_color,
+      :en_passant_target,
+      :castling_rights,
+      :halfmove_clock,
+      :fullmove_number
+    ) do
+      def self.start
+        Position[
+          board: Board.start,
+          current_color: :white,
+          en_passant_target: nil,
+          castling_rights: CastlingRights.start,
+          halfmove_clock: 0,
+          fullmove_number: 1
+        ]
+      end
+
+      def self.from_fen(str)
+        FENConverter.from_fen(str)
+      end
+
+      def to_fen
+        FENConverter.to_fen(self)
+      end
+
+      # An identifier for indicating whether positions are identical in the context of position repetitions,
+      # as used for threefold/fivefold repetition detection.
+      def signature
+        [
+          board,
+          current_color,
+          en_passant_target,
+          castling_rights
+        ].hash
+      end
+
+      def other_color
+        Colors.flip(current_color)
+      end
+    end
+
+    # Converts between `Position` and FEN.
+    module FENConverter
+      extend self
+
+      def from_fen(str)
+        arr = str.split
+        raise ArgumentError, 'Not a valid FEN' unless arr.size == 6
+
+        board_str, color_str, castling_rights_str, en_passant_target_str, halfmove_clock_str, fullmove_number_str = arr
+
+        board = fen_to_board(board_str)
+        color = case color_str
+                when 'w' then :white
+                when 'b' then :black
+                else raise ArgumentError, "Not a valid color #{color_str}"
+                end
+        castling_rights = CoreNotation.str_to_castling_rights(castling_rights_str)
+        en_passant_target = en_passant_target_str == '-' ? nil : CoreNotation.str_to_square(en_passant_target_str)
+
+        Position[
+          board: board,
+          current_color: color,
+          en_passant_target: en_passant_target,
+          castling_rights: castling_rights,
+          halfmove_clock: halfmove_clock_str.to_i,
+          fullmove_number: fullmove_number_str.to_i
+        ]
+      end
+
+      def to_fen(pos)
+        board_str = board_to_fen(pos.board)
+        color_str = pos.current_color == :white ? 'w' : 'b'
+        castling_rights_str = CoreNotation.castling_rights_to_str(pos.castling_rights)
+        en_passant_target_str = pos.en_passant_target.nil? ? '-' : CoreNotation.square_to_str(pos.en_passant_target)
+
+        "#{board_str} #{color_str} #{castling_rights_str} #{en_passant_target_str} #{pos.halfmove_clock} #{pos.fullmove_number}"
+      end
+
+      private
+
+      def fen_to_board(str)
+        board_array = str.split('/').reverse.map do |row|
+          row.chars.map do |piece|
+            if ('1'..'8').include?(piece)
+              [nil] * piece.to_i
+            else
+              CoreNotation.str_to_piece(piece)
+            end
+          end
+        end
+        Board.from_flat_array(board_array.flatten)
+      end
+
+      def board_to_fen(board)
+        ranks = board.each_rank.map do |rank|
+          rank_to_fen(rank)
+        end
+        ranks.reverse.join('/')
+      end
+
+      def rank_to_fen(rank)
+        rank_str = ''
+        nil_count = 0
+        rank.each do |piece|
+          if piece.nil?
+            nil_count += 1
+          else
+            rank_str += nil_count.to_s unless nil_count.zero?
+            rank_str += CoreNotation.piece_to_str(piece)
+            nil_count = 0
+          end
+        end
+        rank_str += nil_count.to_s unless nil_count.zero?
+        rank_str
+      end
+    end
+  end
+
+  CastlingSides = PositionModule::CastlingSides
+  CastlingRights = PositionModule::CastlingRights
+  Position = PositionModule::Position
+end

data/lib/chess_engine/data_definitions/primitives/castling_data.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require 'immutable'
+require_relative '../square'
+
+module ChessEngine
+  # Movement squares for castling pieces, based on the color and side
+  module CastlingData
+    SIDES = %i[kingside queenside].freeze
+
+    FILES = Immutable.from(
+      {
+        kingside: {
+          king_to: :g,
+          rook_from: :h,
+          rook_to: :f,
+          king_path: %i[e f g],
+          intermediate_squares: %i[f g]
+        },
+        queenside: {
+          king_to: :c,
+          rook_from: :a,
+          rook_to: :d,
+          king_path: %i[e d c],
+          intermediate_squares: %i[b c d]
+        }
+      }
+    ).freeze
+
+    RANK_FOR_COLOR = { white: 1, black: 8 }.freeze
+
+    def self.rank(color)
+      RANK_FOR_COLOR.fetch(color)
+    end
+
+    def self.king_from(color, _side = nil)
+      Square[:e, rank(color)]
+    end
+
+    def self.king_to(color, side)
+      Square[FILES.fetch(side)[:king_to], rank(color)]
+    end
+
+    def self.king_path(color, side)
+      FILES.fetch(side)[:king_path].map { |f| Square[f, rank(color)] }
+    end
+
+    def self.rook_from(color, side)
+      Square[FILES.fetch(side)[:rook_from], rank(color)]
+    end
+
+    def self.rook_to(color, side)
+      Square[FILES.fetch(side)[:rook_to], rank(color)]
+    end
+
+    # Every square passed through either by the king or the rook, not including starting squares
+    def self.intermediate_squares(color, side)
+      FILES.fetch(side)[:intermediate_squares].map { |f| Square[f, rank(color)] }
+    end
+  end
+end

data/lib/chess_engine/data_definitions/primitives/colors.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module ChessEngine
+  # Defines player colors and helpers.
+  module Colors
+    COLORS = %i[white black].freeze
+
+    module_function
+
+    # Returns the opposite color (:white <-> :black)
+    def flip(color)
+      case color
+      when :white then :black
+      when :black then :white
+      else raise ArgumentError, "Invalid color: #{color.inspect}"
+      end
+    end
+
+    # Alias
+    def other(color) = flip(color)
+
+    def valid?(color) = COLORS.include?(color)
+    def each(&) = COLORS.each(&)
+    def to_string(color) = color.to_s.capitalize
+  end
+end

data/lib/chess_engine/data_definitions/primitives/core_notation.rb

@@ -0,0 +1,111 @@
+require_relative '../piece'
+require_relative '../square'
+require_relative '../components/castling_rights'
+
+module ChessEngine
+  # Represents the components of chess notation that are shared by common notation formats.
+  # Includes utilities for importing and exporting those components.
+  module CoreNotation
+    module_function
+
+    # -- Mappings ---
+    PIECE_MAP = {
+      king: 'K',
+      queen: 'Q',
+      rook: 'R',
+      bishop: 'B',
+      knight: 'N',
+      pawn: 'P'
+    }.freeze
+
+    CASTLING_MAP = {
+      %i[white kingside] => 'K',
+      %i[white queenside] => 'Q',
+      %i[black kingside] => 'k',
+      %i[black queenside] => 'q'
+    }.freeze
+
+    FILES_STR = Square::FILES.map(&:to_s).freeze
+    RANKS_STR = Square::RANKS.map(&:to_s).freeze
+
+    # Derived mappings
+    PIECE_MAP_REVERSE = PIECE_MAP.invert.freeze
+    CASTLING_MAP_REVERSE = CASTLING_MAP.invert.freeze
+
+    # --- Pieces ---
+    def piece_to_str(piece)
+      raise ArgumentError, "Not a valid Piece: #{piece}" unless piece.is_a?(Piece) && piece.valid?
+
+      symbol = PIECE_MAP[piece.type]
+      piece.color == :black ? symbol.downcase : symbol
+    end
+
+    def str_to_piece(str)
+      color = str == str.upcase ? :white : :black
+      type = PIECE_MAP_REVERSE.fetch(str.upcase) do
+        raise ArgumentError, "Not a valid string: #{str}"
+      end
+
+      Piece[color, type]
+    end
+
+    # --- Squares ---
+    def square_to_str(square)
+      raise ArgumentError, "Not a valid Square: #{square}" unless square.is_a?(Square) && square.valid?
+
+      "#{square.file}#{square.rank}"
+    end
+
+    def str_to_square(str)
+      file, rank = nil
+      if str.size == 2
+        file, rank = str.chars
+        raise ArgumentError, "Not a valid string: #{str}" unless FILES_STR.include?(file) && RANKS_STR.include?(rank)
+      elsif FILES_STR.include?(str)
+        file = str
+      elsif RANKS_STR.include?(str)
+        rank = str
+      else
+        raise ArgumentError, "Not a valid string: #{str}"
+      end
+
+      Square[file&.to_sym, rank&.to_i]
+    end
+
+    # --- Castling rights ---
+    def castling_rights_to_str(rights)
+      raise ArgumentError, "Not a CastlingRights: #{rights}" unless rights.is_a?(CastlingRights)
+
+      result = CASTLING_MAP.reduce('') do |result, (color_side, char)|
+        color, side = color_side
+        if rights.sides(color).side?(side)
+          result + char
+        else
+          result
+        end
+      end
+
+      result.empty? ? '-' : result
+    end
+
+    def str_to_castling_rights(str)
+      rights = CastlingRights.none
+      return rights if str == '-'
+
+      allowed_chars = CASTLING_MAP_REVERSE.keys
+      str.chars.each do |char|
+        raise ArgumentError, "Not valid string for castling rights: #{str}" unless allowed_chars.include?(char)
+
+        color, side = CASTLING_MAP_REVERSE[char]
+        sides = rights.sides(color).with(side => true)
+        rights = rights.with(color => sides)
+
+        # Remove all characters up to and including the found character
+        # Prevents repeating characters and incorrect char order
+        allowed_chars = allowed_chars.drop_while { |c| c != char }.drop(1)
+      end
+
+      rights
+    end
+  end
+end

data/lib/chess_engine/data_definitions/primitives/movement.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'immutable'
+
+module ChessEngine
+  class Piece
+    # Describes the movement pattern of a piece.
+    # Does not account for special moves.
+    # Each entry consists of:
+    # - moves: movement deltas in [file_delta, rank_delta] format (x -> file, y -> rank)
+    # - repeat: a boolean indicating whether the piece can move repeatedly in a direction
+    # For pawns (and optionally other pieces in variants), additional keys may be present:
+    # - attacks: movement deltas for capturing (e.g., pawn diagonal captures)
+    # - special_moves: an array of special move definitions.
+    #   Each special move is a hash with:
+    #     - path: an array of deltas (each [file_delta, rank_delta]) describing the move sequence
+    #     - condition: a lambda that takes the piece and returns true if the move is allowed
+    #         (e.g., only on the pawn's first move)
+    module Movement
+      straight = [[0, 1], [0, -1], [1, 0], [-1, 0]]
+      diagonal = [[1, 1], [-1, 1], [1, -1], [-1, -1]]
+      knight = [
+        [2, 1], [1, 2], [-1, 2], [-2, 1],
+        [2, -1], [1, -2], [-1, -2], [-2, -1]
+      ]
+
+      MOVEMENT = Immutable.from(
+        {
+          king: { moves: straight + diagonal, repeat: false },
+          queen: { moves: straight + diagonal, repeat: true },
+          rook: { moves: straight, repeat: true },
+          bishop: { moves: diagonal, repeat: true },
+          knight: { moves: knight, repeat: false },
+          pawn: {
+            moves: [[0, 1]],
+            attacks: [[1, 1], [-1, 1]],
+            repeat: false,
+            special_moves: [
+              {
+                path: [[0, 1], [0, 2]],
+                condition: lambda { |piece, square|
+                  (piece.color == :white && square.rank == 2) ||
+                    (piece.color == :black && square.rank == 7)
+                }
+              }
+            ]
+          }
+        }
+      )
+    end
+  end
+end

data/lib/chess_engine/data_definitions/square.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require_relative '../errors'
+
+module ChessEngine
+  # Represents chessboard squares, each with a rank and a file,
+  # and provides methods for validation, conversion, and manipulation of squares within the chess engine.
+  #
+  # An invalid `Square` (e.g., off the board) can be created but must not be used, as this will cause an error.
+  # Ensure validity with `#valid?` before usage.
+  class Square
+    FILES = (:a..:h).to_a.freeze
+    RANKS = (1..8).to_a.freeze
+
+    attr_reader :file, :rank
+
+    def initialize(file, rank)
+      @file = file
+      @rank = rank
+    end
+
+    def self.from_index(row, col)
+      return new(nil, nil) unless (0..7).cover?(row) && (0..7).cover?(col)
+
+      new(FILES[col], RANKS[row])
+    end
+
+    # Produces a standard array representation of [row, column]
+    def to_a
+      return InvalidSquareError unless valid?
+
+      [@rank - 1, FILES.index(@file)]
+    end
+
+    def offset(file_delta, rank_delta)
+      row, col = to_a
+      row += rank_delta
+      col += file_delta
+      Square.from_index(row, col)
+    end
+
+    # Returns the distance between self and the given Square object.
+    # The result is of the format [file_distance, rank_distance].
+    # For example, the distance from b2 to d2 is [2, 0].
+    def distance(other)
+      raise InvalidSquareError unless valid? && other&.valid?
+
+      file_distance = (FILES.index(file) - FILES.index(other.file)).abs
+      rank_distance = (rank - other.rank).abs
+      [file_distance, rank_distance]
+    end
+
+    # Returns true if self is partially included in the other square.
+    # For this method, self doesn't have to be a full, valid square.
+    # It can have any of the following: specific rank and file,
+    # specific file (nil rank), specific rank (nil file), or both being nil.
+    # `other` is a complete, valid square.
+    def matches?(other)
+      file_matches = file.nil? || file == other.file
+      rank_matches = rank.nil? || rank == other.rank
+
+      file_matches && rank_matches
+    end
+
+    def valid?
+      FILES.include?(file) && RANKS.include?(rank)
+    end
+
+    def to_s
+      return "#<Square (INVALID) file=#{file.inspect}, rank=#{rank.inspect}>" unless valid?
+
+      "#{file}#{rank}"
+    end
+
+    # For cleaner test messages
+    def inspect
+      to_s
+    end
+
+    def ==(other)
+      other.is_a?(Square) && file == other.file && rank == other.rank
+    end
+
+    def eql?(other)
+      self == other
+    end
+
+    def hash
+      [file, rank].hash
+    end
+
+    # For `Square[file, rank]` syntax.
+    # Makes it clearer that this is a value object, similar to Data
+    def self.[](file, rank)
+      new(file, rank)
+    end
+  end
+end