sashite-ggn 0.1.0 → 0.3.0

data/lib/sashite/ggn/piece/source/destination/engine/transition.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Sashite
+  module Ggn
+    class Piece
+      class Source
+        class Destination
+          class Engine
+            # Represents the result of a valid pseudo-legal move evaluation.
+            #
+            # A Transition encapsulates the changes that occur when a move is executed:
+            # - Board state changes (pieces moving, appearing, or disappearing)
+            # - Pieces gained in hand (from captures)
+            # - Pieces dropped from hand (for drop moves)
+            #
+            # @example Basic move (pawn advance)
+            #   transition = Transition.new(nil, nil, "e2" => nil, "e4" => "CHESS:P")
+            #   transition.diff  # => { "e2" => nil, "e4" => "CHESS:P" }
+            #   transition.gain  # => nil
+            #   transition.drop  # => nil
+            #
+            # @example Capture with piece gain
+            #   transition = Transition.new("CHESS:R", nil, "g7" => nil, "h8" => "CHESS:Q")
+            #   transition.gain  # => "CHESS:R" (captured rook goes to hand)
+            #
+            # @example Piece drop from hand
+            #   transition = Transition.new(nil, "SHOGI:P", "5e" => "SHOGI:P")
+            #   transition.drop  # => "SHOGI:P" (pawn removed from hand)
+            class Transition
+              # @return [Hash<String, String|nil>] Board state changes after the move.
+              #   Keys are square labels, values are piece identifiers or nil for empty squares.
+              attr_reader :diff
+
+              # @return [String, nil] Piece identifier added to the current player's hand,
+              #   typically from a capture. Nil if no piece is gained.
+              attr_reader :gain
+
+              # @return [String, nil] Piece identifier removed from the current player's hand
+              #   for drop moves. Nil if no piece is dropped.
+              attr_reader :drop
+
+              # Creates a new Transition with the specified changes.
+              #
+              # @param gain [String, nil] Piece gained in hand (usually from capture)
+              # @param drop [String, nil] Piece dropped from hand (for drop moves)
+              # @param diff [Hash] Board state changes as keyword arguments.
+              #   Keys should be square labels, values should be piece identifiers or nil.
+              #
+              # @example Creating a simple move transition
+              #   Transition.new(nil, nil, "e2" => nil, "e4" => "CHESS:P")
+              #
+              # @example Creating a capture transition
+              #   Transition.new("CHESS:R", nil, "d4" => nil, "e5" => "CHESS:P")
+              #
+              # @example Creating a drop transition
+              #   Transition.new(nil, "SHOGI:P", "3c" => "SHOGI:P")
+              def initialize(gain, drop, **diff)
+                @gain = gain
+                @drop = drop
+                @diff = diff
+
+                freeze
+              end
+
+              # Checks if this transition involves gaining a piece.
+              #
+              # @return [Boolean] true if a piece is gained (typically from capture)
+              #
+              # @example
+              #   transition.gain?  # => true if @gain is not nil
+              def gain?
+                !@gain.nil?
+              end
+
+              # Checks if this transition involves dropping a piece from hand.
+              #
+              # @return [Boolean] true if a piece is dropped from hand
+              #
+              # @example
+              #   transition.drop?  # => true if @drop is not nil
+              def drop?
+                !@drop.nil?
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sashite/ggn/piece/source/destination/engine.rb

@@ -0,0 +1,407 @@
+# frozen_string_literal: true
+
+require_relative File.join("engine", "transition")
+
+module Sashite
+  module Ggn
+    class Piece
+      class Source
+        class Destination
+          # Evaluates pseudo-legal move conditions for a specific source-destination pair.
+          #
+          # The Engine is the core logic component that determines whether a move
+          # is valid under the basic movement constraints defined in GGN. It evaluates
+          # require/prevent conditions and returns the resulting board transformation.
+          #
+          # @example Evaluating a move
+          #   engine = destinations.to('e4')
+          #   result = engine.where(board_state, {}, 'CHESS')
+          #   puts "Move valid!" if result
+          class Engine
+            # Reserved square identifier for piece drops from hand
+            DROP_ORIGIN = "*"
+
+            private_constant :DROP_ORIGIN
+
+            # Creates a new Engine with conditional transition rules.
+            #
+            # @param transitions [Array] Transition rules as individual arguments,
+            #   each containing require/prevent conditions and perform actions.
+            # @param actor [String] GAN identifier of the piece being moved
+            # @param origin [String] Source square or "*" for drops
+            # @param target [String] Destination square
+            #
+            # @raise [ArgumentError] If parameters are invalid
+            def initialize(*transitions, actor:, origin:, target:)
+              raise ::ArgumentError, "actor must be a String" unless actor.is_a?(::String)
+              raise ::ArgumentError, "origin must be a String" unless origin.is_a?(::String)
+              raise ::ArgumentError, "target must be a String" unless target.is_a?(::String)
+
+              @transitions = transitions
+              @actor = actor
+              @origin = origin
+              @target = target
+
+              freeze
+            end
+
+            # Evaluates move validity and returns the resulting transition.
+            #
+            # Checks each conditional transition in order until one matches the
+            # current board state, or returns nil if no valid transition exists.
+            #
+            # @param board_state [Hash] Current board state mapping square labels
+            #   to piece identifiers (nil for empty squares)
+            # @param captures [Hash] Available pieces in hand (for drops)
+            # @param turn [String] Current player's game identifier (e.g., 'CHESS', 'shogi')
+            #
+            # @return [Transition, nil] A Transition object if move is valid, nil otherwise
+            #
+            # @raise [ArgumentError] If any parameter is invalid or malformed
+            #
+            # @example Valid move evaluation
+            #   board_state = { 'e2' => 'CHESS:P', 'e3' => nil, 'e4' => nil }
+            #   result = engine.where(board_state, {}, 'CHESS')
+            #   result.diff  # => { 'e2' => nil, 'e4' => 'CHESS:P' }
+            #
+            # @example Invalid move (blocked path)
+            #   board_state = { 'e2' => 'CHESS:P', 'e3' => 'CHESS:N', 'e4' => nil }
+            #   result = engine.where(board_state, {}, 'CHESS')  # => nil
+            def where(board_state, captures, turn)
+              validate_parameters!(board_state, captures, turn)
+
+              return unless valid_move_context?(board_state, captures, turn)
+
+              @transitions.each do |transition|
+                next unless transition_matches?(transition, board_state, turn)
+
+                return Transition.new(
+                  transition["gain"],
+                  transition["drop"],
+                  **transition["perform"]
+                )
+              end
+
+              nil
+            end
+
+            private
+
+            # Validates all parameters in one consolidated method.
+            #
+            # @param board_state [Object] Should be a Hash
+            # @param captures [Object] Should be a Hash
+            # @param turn [Object] Should be a String
+            #
+            # @raise [ArgumentError] If any parameter is invalid
+            def validate_parameters!(board_state, captures, turn)
+              # Type validation
+              unless board_state.is_a?(::Hash)
+                raise ::ArgumentError, "board_state must be a Hash, got #{board_state.class}"
+              end
+
+              unless captures.is_a?(::Hash)
+                raise ::ArgumentError, "captures must be a Hash, got #{captures.class}"
+              end
+
+              unless turn.is_a?(::String)
+                raise ::ArgumentError, "turn must be a String, got #{turn.class}"
+              end
+
+              # Content validation
+              validate_board_state!(board_state)
+              validate_captures!(captures)
+              validate_turn!(turn)
+            end
+
+            # Validates board_state structure and content.
+            #
+            # @param board_state [Hash] Board state to validate
+            #
+            # @raise [ArgumentError] If board_state contains invalid data
+            def validate_board_state!(board_state)
+              board_state.each do |square, piece|
+                validate_square_label!(square)
+                validate_board_piece!(piece, square)
+              end
+            end
+
+            # Validates a square label.
+            #
+            # @param square [Object] Square label to validate
+            #
+            # @raise [ArgumentError] If square label is invalid
+            def validate_square_label!(square)
+              unless square.is_a?(::String) && !square.empty?
+                raise ::ArgumentError, "Invalid square label: #{square.inspect}. Must be a non-empty String."
+              end
+
+              if square == DROP_ORIGIN
+                raise ::ArgumentError, "Square label cannot be '#{DROP_ORIGIN}' (reserved for drops)."
+              end
+            end
+
+            # Validates a piece on the board.
+            #
+            # @param piece [Object] Piece to validate
+            # @param square [String] Square where piece is located
+            #
+            # @raise [ArgumentError] If piece is invalid
+            def validate_board_piece!(piece, square)
+              return if piece.nil? # Empty squares are valid
+
+              unless piece.is_a?(::String)
+                raise ::ArgumentError, "Invalid piece at square #{square}: #{piece.inspect}. Must be a String or nil."
+              end
+
+              unless valid_gan_identifier?(piece)
+                raise ::ArgumentError, "Invalid GAN identifier at square #{square}: #{piece.inspect}. Must follow GAN format (e.g., 'CHESS:P', 'shogi:+k')."
+              end
+            end
+
+            # Validates captures structure and content.
+            #
+            # @param captures [Hash] Captures to validate
+            #
+            # @raise [ArgumentError] If captures contains invalid data
+            def validate_captures!(captures)
+              captures.each do |piece, count|
+                validate_capture_piece!(piece)
+                validate_capture_count!(count, piece)
+              end
+            end
+
+            # Validates a piece identifier in captures.
+            #
+            # @param piece [Object] Piece identifier to validate
+            #
+            # @raise [ArgumentError] If piece identifier is invalid
+            def validate_capture_piece!(piece)
+              unless piece.is_a?(::String) && !piece.empty?
+                raise ::ArgumentError, "Invalid piece identifier in captures: #{piece.inspect}. Must be a non-empty String."
+              end
+
+              unless valid_base_gan_identifier?(piece)
+                raise ::ArgumentError, "Invalid base GAN identifier in captures: #{piece.inspect}. Must be base form GAN (e.g., 'CHESS:P', 'shogi:k') without modifiers."
+              end
+            end
+
+            # Validates a capture count.
+            #
+            # @param count [Object] Count to validate
+            # @param piece [String] Associated piece for error context
+            #
+            # @raise [ArgumentError] If count is invalid
+            def validate_capture_count!(count, piece)
+              unless count.is_a?(::Integer) && count >= 0
+                raise ::ArgumentError, "Invalid count for piece #{piece}: #{count.inspect}. Must be a non-negative Integer."
+              end
+            end
+
+            # Validates turn format.
+            #
+            # @param turn [String] Turn identifier to validate
+            #
+            # @raise [ArgumentError] If turn format is invalid
+            def validate_turn!(turn)
+              if turn.empty?
+                raise ::ArgumentError, "turn cannot be empty"
+              end
+
+              unless valid_game_identifier?(turn)
+                raise ::ArgumentError, "Invalid turn format: #{turn.inspect}. Must be a valid game identifier (alphabetic characters only, e.g., 'CHESS', 'shogi')."
+              end
+            end
+
+            # Validates if a string is a valid GAN identifier with casing consistency.
+            #
+            # @param identifier [String] GAN identifier to validate
+            #
+            # @return [Boolean] true if valid GAN format
+            def valid_gan_identifier?(identifier)
+              return false unless identifier.include?(':')
+
+              game_part, piece_part = identifier.split(':', 2)
+
+              return false unless valid_game_identifier?(game_part)
+              return false if piece_part.empty?
+              return false unless /\A[-+]?[A-Za-z]'?\z/.match?(piece_part)
+
+              # Extract base letter and check casing consistency
+              base_letter = piece_part.gsub(/\A[-+]?([A-Za-z])'?\z/, '\1')
+
+              if game_part == game_part.upcase
+                base_letter == base_letter.upcase
+              else
+                base_letter == base_letter.downcase
+              end
+            end
+
+            # Validates if a string is a valid base GAN identifier (no modifiers).
+            #
+            # @param identifier [String] Base GAN identifier to validate
+            #
+            # @return [Boolean] true if valid base GAN format
+            def valid_base_gan_identifier?(identifier)
+              return false unless identifier.include?(':')
+
+              game_part, piece_part = identifier.split(':', 2)
+
+              return false unless valid_game_identifier?(game_part)
+              return false if piece_part.length != 1
+
+              # Check casing consistency
+              if game_part == game_part.upcase
+                piece_part == piece_part.upcase && /\A[A-Z]\z/.match?(piece_part)
+              else
+                piece_part == piece_part.downcase && /\A[a-z]\z/.match?(piece_part)
+              end
+            end
+
+            # Validates if a string is a valid game identifier.
+            #
+            # @param identifier [String] Game identifier to validate
+            #
+            # @return [Boolean] true if valid game identifier format
+            def valid_game_identifier?(identifier)
+              return false if identifier.empty?
+
+              /\A([A-Z]+|[a-z]+)\z/.match?(identifier)
+            end
+
+            # Validates the move context before checking pseudo-legality.
+            #
+            # @param board_state [Hash] Current board state
+            # @param captures [Hash] Available pieces in hand
+            # @param turn [String] Current player's game identifier
+            #
+            # @return [Boolean] true if the move context is valid
+            def valid_move_context?(board_state, captures, turn)
+              if @origin == DROP_ORIGIN
+                return false unless piece_available_in_hand?(captures)
+              else
+                return false unless piece_on_board_at_origin?(board_state)
+              end
+
+              piece_belongs_to_current_player?(turn)
+            end
+
+            # Checks if the piece is available in the player's hand for drop moves.
+            #
+            # @param captures [Hash] Available pieces in hand
+            #
+            # @return [Boolean] true if piece is available for dropping
+            def piece_available_in_hand?(captures)
+              base_piece = extract_base_piece(@actor)
+              (captures[base_piece] || 0) > 0
+            end
+
+            # Checks if the piece is on the board at the origin square.
+            #
+            # @param board_state [Hash] Current board state
+            #
+            # @return [Boolean] true if the correct piece is at the origin
+            def piece_on_board_at_origin?(board_state)
+              board_state[@origin] == @actor
+            end
+
+            # Checks if the piece belongs to the current player.
+            #
+            # @param turn [String] Current player's game identifier
+            #
+            # @return [Boolean] true if piece belongs to current player
+            def piece_belongs_to_current_player?(turn)
+              return false unless @actor.include?(':')
+
+              game_part = @actor.split(':', 2).fetch(0)
+              piece_is_uppercase_player = game_part == game_part.upcase
+              current_is_uppercase_player = turn == turn.upcase
+
+              piece_is_uppercase_player == current_is_uppercase_player
+            end
+
+            # Extracts the base form of a piece (removes modifiers).
+            #
+            # @param actor [String] Full GAN identifier
+            #
+            # @return [String] Base form suitable for hand storage
+            def extract_base_piece(actor)
+              return actor unless actor.include?(':')
+
+              game_part, piece_part = actor.split(':', 2)
+              clean_piece = piece_part.gsub(/\A[-+]?([A-Za-z])'?\z/, '\1')
+
+              "#{game_part}:#{clean_piece}"
+            end
+
+            # Checks if a transition matches the current board state.
+            def transition_matches?(transition, board_state, turn)
+              return false unless transition.is_a?(::Hash) && transition.key?("perform")
+              return false if has_require_conditions?(transition) && !check_require_conditions(transition["require"], board_state, turn)
+              return false if has_prevent_conditions?(transition) && !check_prevent_conditions(transition["prevent"], board_state, turn)
+
+              true
+            end
+
+            # Checks if transition has require conditions.
+            def has_require_conditions?(transition)
+              transition["require"]&.is_a?(::Hash) && !transition["require"].empty?
+            end
+
+            # Checks if transition has prevent conditions.
+            def has_prevent_conditions?(transition)
+              transition["prevent"]&.is_a?(::Hash) && !transition["prevent"].empty?
+            end
+
+            # Verifies all require conditions are satisfied (logical AND).
+            def check_require_conditions(require_conditions, board_state, turn)
+              require_conditions.all? do |square, required_state|
+                actual_piece = board_state[square]
+                matches_state?(actual_piece, required_state, turn)
+              end
+            end
+
+            # Verifies none of the prevent conditions are satisfied (logical NOR).
+            def check_prevent_conditions(prevent_conditions, board_state, turn)
+              prevent_conditions.none? do |square, forbidden_state|
+                actual_piece = board_state[square]
+                matches_state?(actual_piece, forbidden_state, turn)
+              end
+            end
+
+            # Determines if a piece matches a required/forbidden state.
+            def matches_state?(actual_piece, expected_state, turn)
+              case expected_state
+              when "empty"
+                actual_piece.nil?
+              when "enemy"
+                actual_piece && enemy_piece?(actual_piece, turn)
+              else
+                actual_piece == expected_state
+              end
+            end
+
+            # Determines if a piece belongs to the opposing player.
+            def enemy_piece?(piece, turn)
+              return false if piece.nil? || piece.empty?
+
+              if piece.include?(':')
+                game_part = piece.split(':', 2).fetch(0)
+                piece_is_uppercase_player = game_part == game_part.upcase
+                current_is_uppercase_player = turn == turn.upcase
+
+                piece_is_uppercase_player != current_is_uppercase_player
+              else
+                # Fallback for non-GAN format
+                piece_is_uppercase = piece == piece.upcase
+                current_is_uppercase = turn == turn.upcase
+
+                piece_is_uppercase != current_is_uppercase
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sashite/ggn/piece/source/destination.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require_relative File.join("destination", "engine")
+
+module Sashite
+  module Ggn
+    class Piece
+      class Source
+        # Represents the possible destination squares for a piece from a specific source.
+        #
+        # A Destination instance contains all the target squares a piece can reach
+        # from a given starting position, along with the conditional rules that
+        # govern each potential move.
+        #
+        # @example Basic usage
+        #   destinations = source.from('e1')
+        #   engine = destinations.to('e2')
+        #   result = engine.evaluate(board_state, captures, current_player)
+        class Destination
+          # Creates a new Destination instance from target square data.
+          #
+          # @param data [Hash] The destination data where keys are target square
+          #   labels and values are arrays of conditional transition rules.
+          # @param actor [String] The GAN identifier for this piece type
+          # @param origin [String] The source position
+          #
+          # @raise [ArgumentError] If data is not a Hash
+          def initialize(data, actor:, origin:)
+            raise ::ArgumentError, "Expected Hash, got #{data.class}" unless data.is_a?(::Hash)
+
+            @data = data
+            @actor = actor
+            @origin = origin
+
+            freeze
+          end
+
+          # Retrieves the movement engine for a specific target square.
+          #
+          # @param target [String] The destination square label (e.g., 'e2', '5h').
+          #
+          # @return [Engine] An Engine instance that can evaluate whether the move
+          #   to this target is valid given current board conditions.
+          #
+          # @raise [KeyError] If the target square is not reachable from the source
+          #
+          # @example Getting movement rules to a specific square
+          #   engine = destinations.to('e2')
+          #   result = engine.evaluate(board_state, captures, current_player)
+          #
+          # @example Handling unreachable targets
+          #   begin
+          #     engine = destinations.to('invalid_square')
+          #   rescue KeyError => e
+          #     puts "Cannot move to this square: #{e.message}"
+          #   end
+          def to(target)
+            transitions = @data.fetch(target)
+            Engine.new(*transitions, actor: @actor, origin: @origin, target:)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sashite/ggn/piece/source.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative File.join("source", "destination")
+
+module Sashite
+  module Ggn
+    class Piece
+      # Represents the possible source positions for a specific piece type.
+      #
+      # A Source instance contains all the starting positions from which
+      # a piece can move, including regular board squares and special
+      # positions like "*" for piece drops from hand.
+      #
+      # @example Basic usage with chess king
+      #   piece_data = Sashite::Ggn.load_file('chess.json')
+      #   source = piece_data.select('CHESS:K')
+      #   destinations = source.from('e1')
+      #
+      # @example Usage with Shogi pawn drops
+      #   piece_data = Sashite::Ggn.load_file('shogi.json')
+      #   pawn_source = piece_data.select('SHOGI:P')
+      #   drop_destinations = pawn_source.from('*')  # For piece drops from hand
+      class Source
+        # Creates a new Source instance from movement data.
+        #
+        # @param data [Hash] The movement data where keys are source positions
+        #   (square labels or "*" for drops) and values contain destination data.
+        # @param actor [String] The GAN identifier for this piece type
+        #
+        # @raise [ArgumentError] If data is not a Hash
+        def initialize(data, actor:)
+          raise ::ArgumentError, "Expected Hash, got #{data.class}" unless data.is_a?(::Hash)
+
+          @data = data
+          @actor = actor
+
+          freeze
+        end
+
+        # Retrieves possible destinations from a specific source position.
+        #
+        # @param origin [String] The source position label. Can be a regular
+        #   square label (e.g., 'e1', '5i') or "*" for piece drops from hand.
+        #
+        # @return [Destination] A Destination instance containing all possible
+        #   target squares and their movement conditions from this origin.
+        #
+        # @raise [KeyError] If the origin position is not found in the data
+        #
+        # @example Getting moves from a specific square
+        #   destinations = source.from('e1')
+        #   engine = destinations.to('e2')
+        #
+        # @example Getting drop moves (for games like Shogi)
+        #   drop_destinations = source.from('*')
+        #   engine = drop_destinations.to('5e')
+        #
+        # @example Handling missing origins
+        #   begin
+        #     destinations = source.from('invalid_square')
+        #   rescue KeyError => e
+        #     puts "No moves from this position: #{e.message}"
+        #   end
+        def from(origin)
+          data = @data.fetch(origin)
+          Destination.new(data, actor: @actor, origin:)
+        end
+      end
+    end
+  end
+end