sashite-ggn 0.7.0 → 0.9.0

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

@@ -1,370 +1,115 @@
 # frozen_string_literal: true
 
-require_relative File.join("..", "..", "..", "move_validator")
-require_relative File.join("engine", "transition")
+require "sashite/lcn"
+require "sashite/qpi"
+require "sashite/stn"
 
 module Sashite
   module Ggn
     class Ruleset
       class Source
         class Destination
-          # Evaluates pseudo-legal move conditions for a specific source-destination pair.
+          # Evaluates movement possibility under given position conditions
           #
-          # 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.
-          #
-          # Since GGN focuses exclusively on board-to-board transformations, the Engine
-          # only handles pieces moving, capturing, or transforming on the game board.
-          #
-          # 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 simple move
-          #   engine = destinations.to('e4')
-          #   transitions = engine.where(board_state, 'CHESS')
-          #   puts "Move valid!" if transitions.any?
-          #
-          # @example Handling promotion choices
-          #   engine = destinations.to('e8')  # pawn promotion
-          #   transitions = engine.where(board_state, 'CHESS')
-          #   transitions.each_with_index do |t, i|
-          #     puts "Choice #{i + 1}: promotes to #{t.diff['e8']}"
-          #   end
+          # @see https://sashite.dev/specs/ggn/1.0.0/
           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
-            # @param target [String] Destination square
+            # Create a new Engine
             #
-            # @raise [ArgumentError] If parameters are invalid
-            #
-            # @example Creating an engine for a pawn move
-            #   transition_rules = [
-            #     {
-            #       "require" => { "e4" => "empty", "e3" => "empty" },
-            #       "perform" => { "e2" => nil, "e4" => "CHESS:P" }
-            #     }
-            #   ]
-            #   engine = Engine.new(*transition_rules, actor: "CHESS:P", origin: "e2", target: "e4")
-            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
-
+            # @param possibilities [Array<Hash>] Movement possibilities data
+            def initialize(*possibilities)
+              @possibilities = possibilities
               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 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<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 }
-            #   transitions = engine.where(board_state, 'CHESS')
-            #   transitions.size  # => 1
-            #   transitions.first.diff  # => { 'e2' => nil, 'e4' => 'CHESS:P' }
-            #
-            # @example Multiple promotion choices
-            #   board_state = { 'e7' => 'CHESS:P', 'e8' => nil }
-            #   transitions = engine.where(board_state, 'CHESS')
-            #   transitions.size  # => 4 (Queen, Rook, Bishop, Knight)
-            #   transitions.map { |t| t.diff['e8'] }  # => ['CHESS:Q', 'CHESS:R', 'CHESS:B', 'CHESS:N']
-            #
-            # @example Invalid move (wrong piece)
-            #   board_state = { 'e2' => 'CHESS:Q', 'e3' => nil, 'e4' => nil }
-            #   transitions = engine.where(board_state, 'CHESS')  # => []
-            #
-            # @example Invalid move (blocked path)
-            #   board_state = { 'e2' => 'CHESS:P', 'e3' => 'CHESS:N', 'e4' => nil }
-            #   transitions = engine.where(board_state, 'CHESS')  # => []
-            def where(board_state, active_game)
-              # Validate all input parameters before processing
-              validate_parameters!(board_state, active_game)
-
-              # Early return if basic move context is invalid (wrong piece, wrong player, etc.)
-              return [] unless valid_move_context?(board_state, active_game)
-
-              # 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, active_game)
+            # Evaluate movement against position and return valid transitions
+            #
+            # @param active_side [Symbol] Active player side (:first or :second)
+            # @param squares [Hash{String => String, nil}] Board state where keys are CELL coordinates
+            #   and values are QPI identifiers or nil for empty squares
+            # @return [Array<Sashite::Stn::Transition>] Valid state transitions (may be empty)
+            #
+            # @example
+            #   active_side = :first
+            #   squares = {
+            #     "e2" => "C:P",
+            #     "e3" => nil,
+            #     "e4" => nil
+            #   }
+            #   transitions = engine.where(active_side, squares)
+            def where(active_side, squares)
+              @possibilities.select do |possibility|
+                satisfies_must?(possibility["must"], active_side, squares) &&
+                  satisfies_deny?(possibility["deny"], active_side, squares)
+              end.map do |possibility|
+                Stn.parse(possibility["diff"])
               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:
-            # - Ensures the piece is at the expected origin square
-            # - Ensures the piece belongs to the current player
-            #
-            # @param board_state [Hash] Current board state
-            # @param active_game [String] Current player identifier
+            # Check if all 'must' conditions are satisfied
             #
-            # @return [Boolean] true if the move context is valid
-            def valid_move_context?(board_state, active_game)
-              # For all moves, piece must be on the board at origin square
-              return false unless piece_on_board_at_origin?(@actor, @origin, board_state)
+            # @param conditions [Hash] LCN conditions
+            # @param active_side [Symbol] Active player side
+            # @param squares [Hash] Board state
+            # @return [Boolean]
+            def satisfies_must?(conditions, active_side, squares)
+              return true if conditions.empty?
 
-              # Verify piece ownership - only current player can move their pieces
-              piece_belongs_to_current_player?(@actor, active_game)
-            end
+              lcn_conditions = Lcn.parse(conditions)
 
-            # Creates a new Transition object from a transition rule.
-            # Extracted to improve readability and maintainability of the main logic.
-            #
-            # Note: GGN no longer supports gain/drop fields, so Transition creation
-            # is simplified to only handle board transformations.
-            #
-            # @param transition [Hash] The transition rule containing perform data
-            #
-            # @return [Transition] A new immutable Transition object
-            def create_transition(transition)
-              Transition.new(**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 active_game [Object] Should be a String
-            #
-            # @raise [ArgumentError] If any parameter is invalid
-            def validate_parameters!(board_state, active_game)
-              # 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 active_game.is_a?(::String)
-                raise ::ArgumentError, "active_game must be a String, got #{active_game.class}"
-              end
-
-              # Content validation - ensures data integrity
-              validate_board_state!(board_state)
-              validate_active_game!(active_game)
-            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)
+              lcn_conditions.locations.all? do |location|
+                expected_state = lcn_conditions[location]
+                check_condition(location.to_s, expected_state, active_side, squares)
               end
             end
 
-            # Validates a square label according to GGN requirements.
-            # Square labels must be non-empty strings.
+            # Check if all 'deny' conditions are not satisfied
             #
-            # @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
-            end
+            # @param conditions [Hash] LCN conditions
+            # @param active_side [Symbol] Active player side
+            # @param squares [Hash] Board state
+            # @return [Boolean]
+            def satisfies_deny?(conditions, active_side, squares)
+              return true if conditions.empty?
 
-            # 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
+              lcn_conditions = Lcn.parse(conditions)
 
-              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')."
+              lcn_conditions.locations.none? do |location|
+                expected_state = lcn_conditions[location]
+                check_condition(location.to_s, expected_state, active_side, squares)
               end
             end
 
-            # Validates active_game format according to GAN specification.
-            # Active game must be a non-empty alphabetic game identifier.
-            #
-            # @param active_game [String] Active game identifier to validate
+            # Check if a location satisfies a condition
             #
-            # @raise [ArgumentError] If active game format is invalid
-            def validate_active_game!(active_game)
-              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
-            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
-
-            # 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 active_game [String] Current player identifier
-            #
-            # @return [Boolean] true if the transition is valid for current state
-            def transition_matches?(transition, board_state, active_game)
-              # 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, active_game)
-
-              # Check prevent conditions (none must be satisfied - logical NOR)
-              return false if has_prevent_conditions?(transition) && !check_prevent_conditions(transition["prevent"], board_state, active_game)
-
-              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 active_game [String] Current player identifier
-            #
-            # @return [Boolean] true if all conditions are satisfied
-            def check_require_conditions(require_conditions, board_state, active_game)
-              require_conditions.all? do |square, required_state|
-                actual_piece = board_state[square]
-                matches_state?(actual_piece, required_state, active_game)
-              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 active_game [String] Current player identifier
-            #
-            # @return [Boolean] true if no forbidden conditions are satisfied
-            def check_prevent_conditions(prevent_conditions, board_state, active_game)
-              prevent_conditions.none? do |square, forbidden_state|
-                actual_piece = board_state[square]
-                matches_state?(actual_piece, forbidden_state, active_game)
-              end
-            end
+            # @param location [String] Location to check (CELL coordinate)
+            # @param expected_state [String] Expected state value
+            # @param active_side [Symbol] Active player side
+            # @param squares [Hash] Board state
+            # @return [Boolean]
+            def check_condition(location, expected_state, active_side, squares)
+              actual_qpi = squares[location]
 
-            # 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 active_game [String] Current player identifier
-            #
-            # @return [Boolean] true if the piece matches the expected state
-            def matches_state?(actual_piece, expected_state, active_game)
               case expected_state
               when "empty"
-                actual_piece.nil?
+                actual_qpi.nil?
               when "enemy"
-                actual_piece && enemy_piece?(actual_piece, active_game)
+                actual_qpi && enemy?(actual_qpi, active_side)
               else
-                # Exact piece match
-                actual_piece == expected_state
+                # Expected state is a QPI identifier
+                actual_qpi == expected_state
               end
             end
 
-            # Determines if a piece belongs to the opposing player.
-            # Uses GAN casing conventions to determine ownership based on case correspondence.
-            #
-            # @param piece [String] The piece identifier to check (must be GAN format)
-            # @param active_game [String] Current player identifier
+            # Check if a piece is an enemy relative to active side
             #
-            # @return [Boolean] true if piece belongs to opponent
-            def enemy_piece?(piece, active_game)
-              return false if piece.nil? || piece.empty?
-              return false unless 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 = active_game == active_game.upcase
-
-              # Enemy if players have different casing
-              piece_is_uppercase_player != current_is_uppercase_player
+            # @param qpi_str [String] QPI identifier
+            # @param active_side [Symbol] Active player side
+            # @return [Boolean]
+            def enemy?(qpi_str, active_side)
+              piece_side = Qpi.parse(qpi_str).side
+              piece_side != active_side
             end
           end
         end

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

@@ -1,108 +1,56 @@
 # frozen_string_literal: true
 
-require_relative File.join("destination", "engine")
+require_relative "destination/engine"
 
 module Sashite
   module Ggn
     class Ruleset
       class Source
-        # Represents the possible destination squares for a piece from a specific source.
+        # Represents movement possibilities 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
+        # @see https://sashite.dev/specs/ggn/1.0.0/
         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
+          # Create a new Destination
           #
-          # @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)
-
+          # @param data [Hash] Destinations data structure
+          def initialize(data)
             @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.
+          # Specify the destination location
           #
-          # @param target [String] The destination square label (e.g., 'e2', '5h', 'a8').
+          # @param destination [String] Destination location (CELL coordinate or HAND "*")
+          # @return [Engine] Movement evaluation engine
+          # @raise [KeyError] If destination not found from this source
           #
-          # @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')
+          # @example
+          #   engine = destination.to("e2")
+          def to(destination)
+            raise ::KeyError, "Destination not found: #{destination}" unless destination?(destination)
+
+            Engine.new(*@data.fetch(destination))
+          end
+
+          # Return all valid destinations from this source
           #
-          #   if transitions.any?
-          #     puts "Move is valid!"
-          #     transitions.each { |t| puts "Result: #{t.diff}" }
-          #   else
-          #     puts "Move is not valid under current conditions"
-          #   end
+          # @return [Array<String>] Destination locations
           #
-          # @example Handling unreachable targets
-          #   begin
-          #     engine = destinations.to('invalid_square')
-          #   rescue KeyError => e
-          #     puts "Cannot move to this square: #{e.message}"
-          #   end
+          # @example
+          #   destination.destinations # => ["d1", "d2", "e2", "f2", "f1"]
+          def destinations
+            @data.keys
+          end
+
+          # Check if location is a valid destination from this source
           #
-          # @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
+          # @param location [String] Destination location
+          # @return [Boolean]
           #
-          # @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)
+          # @example
+          #   destination.destination?("e2") # => true
+          def destination?(location)
+            @data.key?(location)
           end
         end
       end