sashite-ggn 0.2.0 → 0.5.0

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

@@ -0,0 +1,454 @@
+# frozen_string_literal: true
+
+require_relative File.join("..", "..", "..", "move_validator")
+require_relative File.join("engine", "transition")
+
+module Sashite
+  module Ggn
+    class Ruleset
+      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.
+          #
+          # The class uses a functional approach with filter_map for optimal performance
+          # and clean, readable code that avoids mutation of external variables.
+          #
+          # @example Evaluating a move
+          #   engine = destinations.to('e4')
+          #   result = engine.where(board_state, {}, 'CHESS')
+          #   puts "Move valid!" if result.any?
+          class Engine
+            include MoveValidator
+
+            # 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 all resulting transitions.
+            #
+            # Uses a functional approach with filter_map to process transitions efficiently.
+            # This method checks each conditional transition and returns all that match the
+            # current board state, supporting multiple promotion choices and optional
+            # transformations as defined in the GGN specification.
+            #
+            # @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 [Array<Transition>] Array of Transition objects for all valid variants,
+            #   empty array if no valid transitions exist
+            #
+            # @raise [ArgumentError] If any parameter is invalid or malformed
+            #
+            # @example Single valid move
+            #   board_state = { 'e2' => 'CHESS:P', 'e3' => nil, 'e4' => nil }
+            #   results = engine.where(board_state, {}, 'CHESS')
+            #   results.size  # => 1
+            #   results.first.diff  # => { 'e2' => nil, 'e4' => 'CHESS:P' }
+            #
+            # @example Multiple promotion choices
+            #   board_state = { 'e7' => 'CHESS:P', 'e8' => nil }
+            #   results = engine.where(board_state, {}, 'CHESS')
+            #   results.size  # => 4 (Queen, Rook, Bishop, Knight)
+            #   results.map { |r| r.diff['e8'] }  # => ['CHESS:Q', 'CHESS:R', 'CHESS:B', 'CHESS:N']
+            #
+            # @example Invalid move (blocked path)
+            #   board_state = { 'e2' => 'CHESS:P', 'e3' => 'CHESS:N', 'e4' => nil }
+            #   results = engine.where(board_state, {}, 'CHESS')  # => []
+            def where(board_state, captures, turn)
+              # Validate all input parameters before processing
+              validate_parameters!(board_state, captures, turn)
+
+              # Early return if basic move context is invalid (wrong piece, not in hand, etc.)
+              return [] unless valid_move_context?(board_state, captures, turn)
+
+              # Use filter_map for functional approach: filter valid transitions and map to Transition objects
+              # This avoids mutation and is more performant than select + map for large datasets
+              @transitions.filter_map do |transition|
+                # Only create Transition objects for transitions that match current board state
+                create_transition(transition) if transition_matches?(transition, board_state, turn)
+              end
+            end
+
+            private
+
+            # Validates the move context before checking pseudo-legality.
+            # Uses the shared MoveValidator module for consistency across the codebase.
+            #
+            # This method performs essential pre-checks:
+            # - For drops: ensures the piece is available in hand
+            # - For board moves: ensures the piece is at the expected origin square
+            # - For all moves: ensures the piece belongs to the current player
+            #
+            # @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)
+              # Check availability based on move type (drop vs regular move)
+              if @origin == DROP_ORIGIN
+                # For drops, piece must be available in player's hand
+                return false unless piece_available_in_hand?(@actor, captures)
+              else
+                # For regular moves, piece must be on the board at origin square
+                return false unless piece_on_board_at_origin?(@actor, @origin, board_state)
+              end
+
+              # Verify piece ownership - only current player can move their pieces
+              piece_belongs_to_current_player?(@actor, turn)
+            end
+
+            # Creates a new Transition object from a transition rule.
+            # Extracted to improve readability and maintainability of the main logic.
+            #
+            # @param transition [Hash] The transition rule containing gain, drop, and perform data
+            #
+            # @return [Transition] A new immutable Transition object
+            def create_transition(transition)
+              Transition.new(
+                transition["gain"],
+                transition["drop"],
+                **transition["perform"]
+              )
+            end
+
+            # Validates all parameters in one consolidated method.
+            # Provides comprehensive validation with clear error messages for debugging.
+            #
+            # @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 with clear error messages
+              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 - ensures data integrity
+              validate_board_state!(board_state)
+              validate_captures!(captures)
+              validate_turn!(turn)
+            end
+
+            # Validates board_state structure and content.
+            # Ensures all square labels and piece identifiers are properly formatted.
+            #
+            # @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 according to GGN requirements.
+            # Square labels must be non-empty strings and cannot conflict with reserved values.
+            #
+            # @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
+
+              # Prevent conflicts with reserved drop origin marker
+              if square == DROP_ORIGIN
+                raise ::ArgumentError, "Square label cannot be '#{DROP_ORIGIN}' (reserved for drops)."
+              end
+            end
+
+            # Validates a piece on the board.
+            # Pieces can be nil (empty square) or valid GAN identifiers.
+            #
+            # @param piece [Object] Piece to validate
+            # @param square [String] Square where piece is located (for error context)
+            #
+            # @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.
+            # Ensures piece identifiers are base form GAN and counts are non-negative integers.
+            #
+            # @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.
+            # Captured pieces must be in base form (no modifiers) according to FEEN specification.
+            #
+            # @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.
+            # Counts must be non-negative integers representing available pieces.
+            #
+            # @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 according to GAN specification.
+            # Turn must be a non-empty alphabetic game identifier.
+            #
+            # @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.
+            # Ensures game part and piece part have consistent casing (both upper or both lower).
+            #
+            # @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')
+
+              # Ensure consistent casing between game and piece parts
+              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).
+            # Used for pieces in hand which cannot have state 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 for base form
+              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.
+            # Game identifiers must be purely alphabetic (all upper or all lower case).
+            #
+            # @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
+
+            # Checks if a transition matches the current board state.
+            # Evaluates both require conditions (must be true) and prevent conditions (must be false).
+            #
+            # @param transition [Hash] The transition rule to evaluate
+            # @param board_state [Hash] Current board state
+            # @param turn [String] Current player identifier
+            #
+            # @return [Boolean] true if the transition is valid for current state
+            def transition_matches?(transition, board_state, turn)
+              # Ensure transition is properly formatted
+              return false unless transition.is_a?(::Hash) && transition.key?("perform")
+
+              # Check require conditions (all must be satisfied - logical AND)
+              return false if has_require_conditions?(transition) && !check_require_conditions(transition["require"], board_state, turn)
+
+              # Check prevent conditions (none must be satisfied - logical NOR)
+              return false if has_prevent_conditions?(transition) && !check_prevent_conditions(transition["prevent"], board_state, turn)
+
+              true
+            end
+
+            # Checks if transition has require conditions that need validation.
+            #
+            # @param transition [Hash] The transition rule
+            #
+            # @return [Boolean] true if require conditions exist
+            def has_require_conditions?(transition)
+              transition["require"]&.is_a?(::Hash) && !transition["require"].empty?
+            end
+
+            # Checks if transition has prevent conditions that need validation.
+            #
+            # @param transition [Hash] The transition rule
+            #
+            # @return [Boolean] true if prevent conditions exist
+            def has_prevent_conditions?(transition)
+              transition["prevent"]&.is_a?(::Hash) && !transition["prevent"].empty?
+            end
+
+            # Verifies all require conditions are satisfied (logical AND).
+            # All specified conditions must be true for the move to be valid.
+            #
+            # @param require_conditions [Hash] Square -> required state mappings
+            # @param board_state [Hash] Current board state
+            # @param turn [String] Current player identifier
+            #
+            # @return [Boolean] true if all conditions are satisfied
+            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).
+            # If any prevent condition is true, the move is invalid.
+            #
+            # @param prevent_conditions [Hash] Square -> forbidden state mappings
+            # @param board_state [Hash] Current board state
+            # @param turn [String] Current player identifier
+            #
+            # @return [Boolean] true if no forbidden conditions are satisfied
+            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.
+            # Handles special states ("empty", "enemy") and exact piece matching.
+            #
+            # @param actual_piece [String, nil] The piece currently on the square
+            # @param expected_state [String] The expected/forbidden state
+            # @param turn [String] Current player identifier
+            #
+            # @return [Boolean] true if the piece matches the expected 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
+                # Exact piece match
+                actual_piece == expected_state
+              end
+            end
+
+            # Determines if a piece belongs to the opposing player.
+            # Uses GAN casing conventions to determine ownership.
+            #
+            # @param piece [String] The piece identifier to check
+            # @param turn [String] Current player identifier
+            #
+            # @return [Boolean] true if piece belongs to opponent
+            def enemy_piece?(piece, turn)
+              return false if piece.nil? || piece.empty?
+
+              if piece.include?(':')
+                # Use GAN format for ownership determination
+                game_part = piece.split(':', 2).fetch(0)
+                piece_is_uppercase_player = game_part == game_part.upcase
+                current_is_uppercase_player = turn == turn.upcase
+
+                # Enemy if players have different casing
+                piece_is_uppercase_player != current_is_uppercase_player
+              else
+                # Fallback for non-GAN format (legacy support)
+                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/ruleset/source/destination.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require_relative File.join("destination", "engine")
+
+module Sashite
+  module Ggn
+    class Ruleset
+      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/ruleset/source.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative File.join("source", "destination")
+
+module Sashite
+  module Ggn
+    class Ruleset
+      # 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