sashite-ggn 0.3.0 → 0.6.0

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

@@ -0,0 +1,111 @@
+# 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. Since GGN focuses exclusively on board-to-board
+        # transformations, all destinations represent squares on the game board.
+        #
+        # @example Basic usage
+        #   destinations = source.from('e1')
+        #   engine = destinations.to('e2')
+        #   transitions = engine.where(board_state, 'CHESS')
+        #
+        # @example Exploring all possible destinations
+        #   destinations = source.from('e1')
+        #   # destinations.to('e2') - one square forward
+        #   # destinations.to('f1') - one square right
+        #   # destinations.to('d1') - one square left
+        #   # Each destination has its own movement rules and conditions
+        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
+          #
+          # @example Creating a Destination instance
+          #   destination_data = {
+          #     "e2" => [
+          #       { "require" => { "e2" => "empty" }, "perform" => { "e1" => nil, "e2" => "CHESS:K" } }
+          #     ],
+          #     "f1" => [
+          #       { "require" => { "f1" => "empty" }, "perform" => { "e1" => nil, "f1" => "CHESS:K" } }
+          #     ]
+          #   }
+          #   destination = Destination.new(destination_data, actor: "CHESS:K", origin: "e1")
+          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.
+          #
+          # This method creates an Engine instance that can evaluate whether the move
+          # to the specified target square is valid given the current board conditions.
+          # The engine encapsulates all the conditional logic (require/prevent/perform)
+          # for this specific source-to-destination move.
+          #
+          # @param target [String] The destination square label (e.g., 'e2', '5h', 'a8').
+          #
+          # @return [Engine] An Engine instance that can evaluate move validity
+          #   and return all possible transition variants for this move.
+          #
+          # @raise [KeyError] If the target square is not reachable from the source
+          #
+          # @example Getting movement rules to a specific square
+          #   engine = destinations.to('e2')
+          #   transitions = engine.where(board_state, 'CHESS')
+          #
+          #   if transitions.any?
+          #     puts "Move is valid!"
+          #     transitions.each { |t| puts "Result: #{t.diff}" }
+          #   else
+          #     puts "Move is not valid under current conditions"
+          #   end
+          #
+          # @example Handling unreachable targets
+          #   begin
+          #     engine = destinations.to('invalid_square')
+          #   rescue KeyError => e
+          #     puts "Cannot move to this square: #{e.message}"
+          #   end
+          #
+          # @example Testing multiple destinations
+          #   ['e2', 'f1', 'd1'].each do |target|
+          #     begin
+          #       engine = destinations.to(target)
+          #       transitions = engine.where(board_state, 'CHESS')
+          #       puts "#{target}: #{transitions.size} possible transitions"
+          #     rescue KeyError
+          #       puts "#{target}: not reachable"
+          #     end
+          #   end
+          #
+          # @note The returned Engine handles all the complexity of move validation,
+          #   including require/prevent conditions and multiple move variants
+          #   (such as promotion choices).
+          def to(target)
+            transitions = @data.fetch(target)
+            Engine.new(*transitions, actor: @actor, origin: @origin, target: target)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -1,33 +1,52 @@
 # frozen_string_literal: true
 
+require_relative File.join("..", "move_validator")
 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
-      # a piece can move, including regular board squares and special
-      # positions like "*" for piece drops from hand.
+      # a piece can move on the board. Since GGN focuses exclusively on
+      # board-to-board transformations, all source positions are regular
+      # board squares.
       #
       # @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
+      # @example Complete move evaluation workflow
+      #   piece_data = Sashite::Ggn.load_file('chess.json')
+      #   king_source = piece_data.select('CHESS:K')
+      #   destinations = king_source.from('e1')
+      #   engine = destinations.to('e2')
+      #
+      #   board_state = { 'e1' => 'CHESS:K', 'e2' => nil }
+      #   transitions = engine.where(board_state, 'CHESS')
+      #
+      #   if transitions.any?
+      #     puts "King can move from e1 to e2"
+      #   end
       class Source
+        include MoveValidator
+
         # 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.
+        #   (square labels) and values contain destination data.
         # @param actor [String] The GAN identifier for this piece type
         #
         # @raise [ArgumentError] If data is not a Hash
+        #
+        # @example Creating a Source instance
+        #   source_data = {
+        #     "e1" => { "e2" => [...], "f1" => [...] },
+        #     "d4" => { "d5" => [...], "e5" => [...] }
+        #   }
+        #   source = Source.new(source_data, actor: "CHESS:K")
         def initialize(data, actor:)
           raise ::ArgumentError, "Expected Hash, got #{data.class}" unless data.is_a?(::Hash)
 
@@ -39,8 +58,8 @@ module Sashite
 
         # 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.
+        # @param origin [String] The source position label. Must be a regular
+        #   square label (e.g., 'e1', '5i', 'a1').
         #
         # @return [Destination] A Destination instance containing all possible
         #   target squares and their movement conditions from this origin.
@@ -51,19 +70,28 @@ module Sashite
         #   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
+        #
+        # @example Iterating through all possible origins
+        #   # Assuming you have access to the source data keys
+        #   available_origins = ['e1', 'd1', 'f1']  # example origins
+        #   available_origins.each do |pos|
+        #     begin
+        #       destinations = source.from(pos)
+        #       puts "Piece can move from #{pos}"
+        #       # Process destinations...
+        #     rescue KeyError
+        #       puts "No moves available from #{pos}"
+        #     end
+        #   end
         def from(origin)
           data = @data.fetch(origin)
-          Destination.new(data, actor: @actor, origin:)
+          Destination.new(data, actor: @actor, origin: origin)
         end
       end
     end

data/lib/sashite/ggn/ruleset.rb

@@ -0,0 +1,311 @@
+# frozen_string_literal: true
+
+require_relative "move_validator"
+require_relative File.join("ruleset", "source")
+
+module Sashite
+  module Ggn
+    # Represents a collection of piece definitions from a GGN document.
+    #
+    # A Ruleset instance contains all the pseudo-legal move definitions for
+    # various game pieces, organized by their GAN (General Actor Notation)
+    # identifiers. This class provides the entry point for querying specific
+    # piece movement rules and generating all possible transitions for a given
+    # game state.
+    #
+    # The class uses functional programming principles throughout, leveraging
+    # Ruby's Enumerable methods (flat_map, filter_map, select) to create
+    # efficient, readable, and maintainable code that avoids mutation and
+    # side effects.
+    #
+    # GGN focuses exclusively on board-to-board transformations. All moves
+    # represent pieces moving, capturing, or transforming on the game board.
+    #
+    # @example Basic usage
+    #   piece_data = Sashite::Ggn.load_file('chess.json')
+    #   chess_king = piece_data.select('CHESS:K')
+    #   shogi_pawn = piece_data.select('SHOGI:P')
+    #
+    # @example Complete workflow
+    #   piece_data = Sashite::Ggn.load_file('game_moves.json')
+    #
+    #   # Query specific piece moves
+    #   begin
+    #     king_source = piece_data.select('CHESS:K')
+    #     puts "Found chess king movement rules"
+    #   rescue KeyError
+    #     puts "Chess king not found in this dataset"
+    #   end
+    #
+    # @example Finding all possible moves in a position
+    #   board_state = { 'e1' => 'CHESS:K', 'e2' => 'CHESS:P', 'd1' => 'CHESS:Q' }
+    #   all_moves = piece_data.pseudo_legal_transitions(board_state, 'CHESS')
+    #   puts "Found #{all_moves.size} possible moves"
+    #
+    # @see https://sashite.dev/documents/gan/ GAN Specification
+    # @see https://sashite.dev/documents/ggn/ GGN Specification
+    class Ruleset
+      include MoveValidator
+
+      # Creates a new Ruleset instance from GGN data.
+      #
+      # @param data [Hash] The parsed GGN JSON data structure, where keys are
+      #   GAN identifiers and values contain the movement definitions.
+      #
+      # @raise [ArgumentError] If data is not a Hash
+      #
+      # @example Creating from parsed JSON data
+      #   ggn_data = JSON.parse(File.read('chess.json'))
+      #   ruleset = Ruleset.new(ggn_data)
+      def initialize(data)
+        raise ::ArgumentError, "Expected Hash, got #{data.class}" unless data.is_a?(::Hash)
+
+        @data = data
+
+        freeze
+      end
+
+      # Retrieves movement rules for a specific piece type.
+      #
+      # @param actor [String] The GAN identifier for the piece type
+      #   (e.g., 'CHESS:K', 'SHOGI:P', 'chess:q'). Must match exactly
+      #   including case sensitivity.
+      #
+      # @return [Source] A Source instance containing all movement rules
+      #   for this piece type from different board positions.
+      #
+      # @raise [KeyError] If the actor is not found in the GGN data
+      #
+      # @example Fetching chess king moves
+      #   source = piece_data.select('CHESS:K')
+      #   destinations = source.from('e1')
+      #   engine = destinations.to('e2')
+      #
+      # @example Handling missing pieces
+      #   begin
+      #     moves = piece_data.select('NONEXISTENT:X')
+      #   rescue KeyError => e
+      #     puts "Piece not found: #{e.message}"
+      #   end
+      #
+      # @note The actor format must follow GAN specification:
+      #   GAME:piece (e.g., CHESS:K, shogi:p, XIANGQI:E)
+      def select(actor)
+        data = @data.fetch(actor)
+        Source.new(data, actor:)
+      end
+
+      # Returns all pseudo-legal move transitions for the given position.
+      #
+      # This method traverses all actors defined in the GGN data using a functional
+      # approach with flat_map and filter_map to efficiently process and filter
+      # valid moves. Each result contains the complete transition information
+      # including all variants for moves with multiple outcomes (e.g., promotion choices).
+      #
+      # The implementation uses a three-level functional decomposition:
+      # 1. Process each actor (piece type) that belongs to current player
+      # 2. Process each valid origin position for that actor
+      # 3. Process each destination and evaluate transition rules
+      #
+      # @param board_state [Hash] Current board state mapping square labels
+      #   to piece identifiers (nil for empty squares)
+      # @param active_game [String] Current player's game identifier (e.g., 'CHESS', 'shogi').
+      #   This corresponds to the first element of the GAMES-TURN field in FEEN notation.
+      #
+      # @return [Array<Array>] List of move transitions, where each element is:
+      #   [actor, origin, target, transitions]
+      #   - actor [String]: GAN identifier of the moving piece
+      #   - origin [String]: Source square
+      #   - target [String]: Destination square
+      #   - transitions [Array<Transition>]: All valid transition variants
+      #
+      # @raise [ArgumentError] If any parameter is invalid or malformed
+      #
+      # @example Getting all possible transitions including promotion variants
+      #   board_state = { 'e7' => 'CHESS:P', 'e8' => nil }
+      #   transitions = piece_data.pseudo_legal_transitions(board_state, 'CHESS')
+      #   # => [
+      #   #   ["CHESS:P", "e7", "e8", [
+      #   #     #<Transition diff={"e7"=>nil, "e8"=>"CHESS:Q"}>,
+      #   #     #<Transition diff={"e7"=>nil, "e8"=>"CHESS:R"}>,
+      #   #     #<Transition diff={"e7"=>nil, "e8"=>"CHESS:B"}>,
+      #   #     #<Transition diff={"e7"=>nil, "e8"=>"CHESS:N"}>
+      #   #   ]]
+      #   # ]
+      #
+      # @example Processing grouped transitions
+      #   transitions = piece_data.pseudo_legal_transitions(board_state, 'CHESS')
+      #   transitions.each do |actor, origin, target, variants|
+      #     puts "#{actor} from #{origin} to #{target}:"
+      #     variants.each_with_index do |transition, i|
+      #       puts "  Variant #{i + 1}: #{transition.diff}"
+      #     end
+      #   end
+      #
+      # @example Filtering for specific move types
+      #   # Find all promotion moves
+      #   promotions = piece_data.pseudo_legal_transitions(board_state, 'CHESS')
+      #     .select { |actor, origin, target, variants| variants.size > 1 }
+      #
+      #   # Find all multi-square moves (like castling)
+      #   complex_moves = piece_data.pseudo_legal_transitions(board_state, 'CHESS')
+      #     .select { |actor, origin, target, variants|
+      #       variants.any? { |t| t.diff.keys.size > 2 }
+      #     }
+      #
+      # @example Performance considerations
+      #   # For large datasets, consider filtering by piece type first
+      #   specific_piece_moves = piece_data.select('CHESS:Q')
+      #     .from('d1').to('d8').where(board_state, 'CHESS')
+      def pseudo_legal_transitions(board_state, active_game)
+        validate_pseudo_legal_parameters!(board_state, active_game)
+
+        # Use flat_map to process all actors and flatten the results in one pass
+        # This functional approach avoids mutation and intermediate arrays
+        @data.flat_map do |actor, source_data|
+          # Early filter: only process pieces belonging to current player
+          # This optimization significantly reduces processing time
+          next [] unless piece_belongs_to_current_player?(actor, active_game)
+
+          # Process all source positions for this actor using functional decomposition
+          process_actor_transitions(actor, source_data, board_state, active_game)
+        end
+      end
+
+      private
+
+      # Processes all possible transitions for a single actor (piece type).
+      #
+      # This method represents the second level of functional decomposition,
+      # handling all source positions (origins) for a given piece type.
+      # It uses flat_map to efficiently process each origin and flatten the results.
+      #
+      # @param actor [String] GAN identifier of the piece type
+      # @param source_data [Hash] Movement data for this piece type, mapping
+      #   origin squares to destination data
+      # @param board_state [Hash] Current board state
+      # @param active_game [String] Current player identifier
+      #
+      # @return [Array] Array of valid transition tuples for this actor
+      #
+      # @example Source data structure
+      #   {
+      #     "e1" => { "e2" => [...], "f1" => [...] }  # Regular moves
+      #   }
+      def process_actor_transitions(actor, source_data, board_state, active_game)
+        source_data.flat_map do |origin, destination_data|
+          # Early filter: check piece presence at origin square
+          # Piece must be present at origin square for the move to be valid
+          next [] unless piece_on_board_at_origin?(actor, origin, board_state)
+
+          # Process all destination squares for this origin
+          process_origin_transitions(actor, origin, destination_data, board_state, active_game)
+        end
+      end
+
+      # Processes all possible transitions from a single origin square.
+      #
+      # This method represents the third level of functional decomposition,
+      # handling all destination squares from a given origin. It creates
+      # engines to evaluate each move and uses filter_map to efficiently
+      # combine filtering and transformation operations.
+      #
+      # @param actor [String] GAN identifier of the piece
+      # @param origin [String] Source square
+      # @param destination_data [Hash] Available destinations and their transition rules
+      # @param board_state [Hash] Current board state
+      # @param active_game [String] Current player identifier
+      #
+      # @return [Array] Array of valid transition tuples for this origin
+      #
+      # @example Destination data structure
+      #   {
+      #     "e4" => [
+      #       { "require" => { "e4" => "empty" }, "perform" => { "e2" => nil, "e4" => "CHESS:P" } }
+      #     ],
+      #     "f3" => [
+      #       { "require" => { "f3" => "enemy" }, "perform" => { "e2" => nil, "f3" => "CHESS:P" } }
+      #     ]
+      #   }
+      def process_origin_transitions(actor, origin, destination_data, board_state, active_game)
+        destination_data.filter_map do |target, transition_rules|
+          # Create engine to evaluate this specific source-destination pair
+          # Each engine encapsulates the conditional logic for one move
+          engine = Source::Destination::Engine.new(*transition_rules, actor: actor, origin: origin, target: target)
+
+          # Get all valid transitions for this move (supports multiple variants)
+          # The engine handles require/prevent conditions and returns Transition objects
+          transitions = engine.where(board_state, active_game)
+
+          # Only return successful moves (with at least one valid transition)
+          # filter_map automatically filters out nil values
+          [actor, origin, target, transitions] unless transitions.empty?
+        end
+      end
+
+      # Validates parameters for pseudo_legal_transitions method.
+      #
+      # Provides comprehensive validation with clear error messages for debugging.
+      # This method ensures data integrity and helps catch common usage errors
+      # early in the processing pipeline.
+      #
+      # @param board_state [Object] Should be a Hash mapping squares to pieces
+      # @param active_game [Object] Should be a String representing current player's game
+      #
+      # @raise [ArgumentError] If any parameter is invalid
+      #
+      # @example Valid parameters
+      #   validate_pseudo_legal_parameters!(
+      #     { "e1" => "CHESS:K", "e2" => nil },
+      #     "CHESS"
+      #   )
+      #
+      # @example Invalid parameters (raises ArgumentError)
+      #   validate_pseudo_legal_parameters!("invalid", "CHESS")
+      #   validate_pseudo_legal_parameters!({}, 123)
+      #   validate_pseudo_legal_parameters!({}, "")
+      def validate_pseudo_legal_parameters!(board_state, active_game)
+        # Type validation with clear, specific error messages
+        unless board_state.is_a?(::Hash)
+          raise ::ArgumentError, "board_state must be a Hash, got #{board_state.class}"
+        end
+
+        unless active_game.is_a?(::String)
+          raise ::ArgumentError, "active_game must be a String, got #{active_game.class}"
+        end
+
+        # Content validation - ensures meaningful data
+        if active_game.empty?
+          raise ::ArgumentError, "active_game cannot be empty"
+        end
+
+        unless valid_game_identifier?(active_game)
+          raise ::ArgumentError, "Invalid active_game format: #{active_game.inspect}. Must be a valid game identifier (alphabetic characters only, e.g., 'CHESS', 'shogi')."
+        end
+
+        # Validate board_state structure (optional deep validation)
+        validate_board_state_structure!(board_state) if ENV['GGN_STRICT_VALIDATION']
+      end
+
+      # Validates board_state structure in strict mode.
+      #
+      # This optional validation can be enabled via environment variable
+      # to catch malformed board states during development and testing.
+      #
+      # @param board_state [Hash] Board state to validate
+      #
+      # @raise [ArgumentError] If board_state contains invalid data
+      def validate_board_state_structure!(board_state)
+        board_state.each do |square, piece|
+          unless square.is_a?(::String) && !square.empty?
+            raise ::ArgumentError, "Invalid square label: #{square.inspect}"
+          end
+
+          if piece && (!piece.is_a?(::String) || piece.empty?)
+            raise ::ArgumentError, "Invalid piece at #{square}: #{piece.inspect}"
+          end
+        end
+      end
+    end
+  end
+end