sashite-ggn 0.3.0 → 0.5.0

data/lib/sashite/ggn/{piece → ruleset}/source/destination/engine.rb

@@ -1,10 +1,11 @@
 # frozen_string_literal: true
 
+require_relative File.join("..", "..", "..", "move_validator")
 require_relative File.join("engine", "transition")
 
 module Sashite
   module Ggn
-    class Piece
+    class Ruleset
       class Source
         class Destination
           # Evaluates pseudo-legal move conditions for a specific source-destination pair.
@@ -13,15 +14,15 @@ module Sashite
           # 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
+          #   puts "Move valid!" if result.any?
           class Engine
-            # Reserved square identifier for piece drops from hand
-            DROP_ORIGIN = "*"
-
-            private_constant :DROP_ORIGIN
+            include MoveValidator
 
             # Creates a new Engine with conditional transition rules.
             #
@@ -45,49 +46,98 @@ module Sashite
               freeze
             end
 
-            # Evaluates move validity and returns the resulting transition.
+            # Evaluates move validity and returns all resulting transitions.
             #
-            # Checks each conditional transition in order until one matches the
-            # current board state, or returns nil if no valid transition exists.
+            # 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 [Transition, nil] A Transition object if move is valid, nil otherwise
+            # @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 Valid move evaluation
+            # @example Single valid move
             #   board_state = { 'e2' => 'CHESS:P', 'e3' => nil, 'e4' => nil }
-            #   result = engine.where(board_state, {}, 'CHESS')
-            #   result.diff  # => { 'e2' => nil, 'e4' => 'CHESS:P' }
+            #   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 }
-            #   result = engine.where(board_state, {}, 'CHESS')  # => 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)
 
-              return unless valid_move_context?(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
 
-              @transitions.each do |transition|
-                next unless transition_matches?(transition, board_state, turn)
+            private
 
-                return Transition.new(
-                  transition["gain"],
-                  transition["drop"],
-                  **transition["perform"]
-                )
+            # 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
 
-              nil
+              # Verify piece ownership - only current player can move their pieces
+              piece_belongs_to_current_player?(@actor, turn)
             end
 
-            private
+            # 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
@@ -95,7 +145,7 @@ module Sashite
             #
             # @raise [ArgumentError] If any parameter is invalid
             def validate_parameters!(board_state, captures, turn)
-              # Type validation
+              # 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
@@ -108,13 +158,14 @@ module Sashite
                 raise ::ArgumentError, "turn must be a String, got #{turn.class}"
               end
 
-              # Content validation
+              # 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
             #
@@ -126,7 +177,8 @@ module Sashite
               end
             end
 
-            # Validates a square label.
+            # 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
             #
@@ -136,15 +188,17 @@ module Sashite
                 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
+            # @param square [String] Square where piece is located (for error context)
             #
             # @raise [ArgumentError] If piece is invalid
             def validate_board_piece!(piece, square)
@@ -160,6 +214,7 @@ module Sashite
             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
             #
@@ -172,6 +227,7 @@ module Sashite
             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
             #
@@ -187,6 +243,7 @@ module Sashite
             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
@@ -198,7 +255,8 @@ module Sashite
               end
             end
 
-            # Validates turn format.
+            # Validates turn format according to GAN specification.
+            # Turn must be a non-empty alphabetic game identifier.
             #
             # @param turn [String] Turn identifier to validate
             #
@@ -214,6 +272,7 @@ module Sashite
             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
             #
@@ -230,6 +289,7 @@ module Sashite
               # 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
@@ -238,6 +298,7 @@ module Sashite
             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
             #
@@ -250,7 +311,7 @@ module Sashite
               return false unless valid_game_identifier?(game_part)
               return false if piece_part.length != 1
 
-              # Check casing consistency
+              # 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
@@ -259,6 +320,7 @@ module Sashite
             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
             #
@@ -269,91 +331,53 @@ module Sashite
               /\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.
+            # 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 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.
+            # @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.
+            # 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.
+            # 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]
@@ -362,6 +386,13 @@ module Sashite
             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]
@@ -370,6 +401,13 @@ module Sashite
             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"
@@ -377,22 +415,31 @@ module Sashite
               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
+                # Fallback for non-GAN format (legacy support)
                 piece_is_uppercase = piece == piece.upcase
                 current_is_uppercase = turn == turn.upcase
 

data/lib/sashite/ggn/{piece → ruleset}/source/destination.rb

@@ -4,7 +4,7 @@ require_relative File.join("destination", "engine")
 
 module Sashite
   module Ggn
-    class Piece
+    class Ruleset
       class Source
         # Represents the possible destination squares for a piece from a specific source.
         #

data/lib/sashite/ggn/{piece → ruleset}/source.rb

@@ -4,7 +4,7 @@ require_relative File.join("source", "destination")
 
 module Sashite
   module Ggn
-    class Piece
+    class Ruleset
       # Represents the possible source positions for a specific piece type.
       #
       # A Source instance contains all the starting positions from which