sashite-ggn 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1af50f2e0d1bcc29f645560a6889184b953b18cc5a10096e2fd5042b61adac22
-  data.tar.gz: d01e4f3b4dfe6d34dd68d6155c541dd5fd17488e4b86e08710e9872ccd901cba
+  metadata.gz: 6dab117559875291772b7e8f60077f670928755870b39badd3555f4d66fd8357
+  data.tar.gz: 2fe3fd39dbb288dc140b10c4c9fec523d2ce00a7d33d7802d8612b95e2268ed3
 SHA512:
-  metadata.gz: 8565e8a83cac905bf9cfd368c136964c83e26f81b8e0fbd0c11c28c4c9da358511cda025688304cb37a16a21b79e07965209dd1027aab478b1fd49e976f00a80
-  data.tar.gz: 4bc9121f894dc379b85c4440a1844946f88cd5c9aa3cf25c8036845fc76060072e7d66579efed704b20f4b8ef851ded94e09b267c8249c231a09ae777d9ebf2e
+  metadata.gz: 805c62503574bbc3b985cc21cb4dfe7a15e03198d97a5e7f0d91508111fd7290ed7382f93f2db6d653f07593f06a65c2640ac4e027127e0bdd964cdc61edab5c
+  data.tar.gz: fc0330900649313e22511f44d391d5a73befdabe4038aa4744de3f8af12684767c410bd6f8aa7e4a88f961cecc6d7be1223e00cfd9736396d92d7c781fa5abea

data/README.md

@@ -9,13 +9,15 @@ A Ruby implementation of the General Gameplay Notation (GGN) specification for d
 
 GGN (General Gameplay Notation) is a rule-agnostic, JSON-based format for representing pseudo-legal moves in abstract strategy board games. This gem implements the [GGN Specification v1.0.0](https://sashite.dev/documents/ggn/1.0.0/).
 
-GGN focuses on basic movement constraints rather than game-specific legality rules, making it suitable for:
+GGN focuses exclusively on **board-to-board transformations**: pieces moving, capturing, or transforming on the game board. It describes basic movement constraints rather than game-specific legality rules, making it suitable for:
 
 - Cross-game move analysis and engine development
 - Hybrid games combining elements from different chess variants
 - Database systems requiring piece disambiguation across game types
 - Performance-critical applications with pre-computed move libraries
 
+**Note**: GGN does not support hand management, piece drops, or captures-to-hand. These mechanics should be handled at a higher level by game engines.
+
 ## Installation
 
 ```ruby
@@ -47,7 +49,7 @@ engine = ruleset.select("CHESS:P").from("e2").to("e4")
 board_state = { "e2" => "CHESS:P", "e3" => nil, "e4" => nil }
 
 # Evaluate move
-transitions = engine.where(board_state, {}, "CHESS")
+transitions = engine.where(board_state, "CHESS")
 # => [#<Transition diff={"e2"=>nil, "e4"=>"CHESS:P"}>]
 ```
 
@@ -55,7 +57,7 @@ transitions = engine.where(board_state, {}, "CHESS")
 
 ```ruby
 # Get all pseudo-legal moves for current position
-all_moves = ruleset.pseudo_legal_transitions(board_state, captures, "CHESS")
+all_moves = ruleset.pseudo_legal_transitions(board_state, "CHESS")
 
 # Each move is represented as [actor, origin, target, transitions]
 all_moves.each do |actor, origin, target, transitions|
@@ -70,7 +72,7 @@ GGN supports multiple outcomes for a single move (e.g., promotion choices):
 ```ruby
 # Chess pawn promotion
 engine = ruleset.select("CHESS:P").from("e7").to("e8")
-transitions = engine.where({"e7" => "CHESS:P", "e8" => nil}, {}, "CHESS")
+transitions = engine.where({"e7" => "CHESS:P", "e8" => nil}, "CHESS")
 
 transitions.each do |transition|
   promoted_piece = transition.diff["e8"]
@@ -79,19 +81,34 @@ end
 # Output: CHESS:Q, CHESS:R, CHESS:B, CHESS:N
 ```
 
-## Piece Drops
+## Complex Moves
 
-For games supporting piece drops (e.g., Shogi):
+GGN can represent multi-square moves like castling:
 
 ```ruby
-# Drop from hand (origin "*")
-engine = ruleset.select("SHOGI:P").from("*").to("5e")
+# Castling (king and rook move simultaneously)
+engine = ruleset.select("CHESS:K").from("e1").to("g1")
+board_state = {
+  "e1" => "CHESS:K", "f1" => nil, "g1" => nil, "h1" => "CHESS:R"
+}
+
+transitions = engine.where(board_state, "CHESS")
+# => [#<Transition diff={"e1"=>nil, "f1"=>"CHESS:R", "g1"=>"CHESS:K", "h1"=>nil}>]
+```
 
-captures = { "SHOGI:P" => 1 }  # One pawn in hand
-board_state = { "5e" => nil }   # Empty target square
+## Conditional Moves
 
-transitions = engine.where(board_state, captures, "SHOGI")
-# => [#<Transition diff={"5e"=>"SHOGI:P"} drop="SHOGI:P">]
+GGN supports moves with complex requirements and prevent conditions:
+
+```ruby
+# En passant capture (removes pawn from different square)
+engine = ruleset.select("CHESS:P").from("d5").to("e6")
+board_state = {
+  "d5" => "CHESS:P", "e5" => "chess:p", "e6" => nil
+}
+
+transitions = engine.where(board_state, "CHESS")
+# => [#<Transition diff={"d5"=>nil, "e5"=>nil, "e6"=>"CHESS:P"}>]
 ```
 
 ## Validation
@@ -114,9 +131,9 @@ Sashite::Ggn.valid?(data)     # Returns boolean
 
 ### Key Methods
 
-- `#pseudo_legal_transitions(board_state, captures, turn)` - Generate all moves
+- `#pseudo_legal_transitions(board_state, active_game)` - Generate all moves
 - `#select(actor).from(origin).to(target)` - Query specific move
-- `#where(board_state, captures, turn)` - Evaluate move validity
+- `#where(board_state, active_game)` - Evaluate move validity
 
 ## Related Specifications
 

data/lib/sashite/ggn/move_validator.rb

@@ -3,40 +3,48 @@
 module Sashite
   module Ggn
     # Centralized module for move condition validation.
-    # Contains shared logic between Engine and performance optimizations.
+    # Contains shared logic for validating piece ownership and board positions
+    # in GGN move evaluation.
+    #
+    # This module focuses exclusively on board-based validation since GGN
+    # only handles board-to-board transformations. All methods work with
+    # pieces on the board and use GAN (General Actor Notation) identifiers.
     module MoveValidator
-      # Reserved for drops from hand
-      DROP_ORIGIN = "*"
-
-      # Separator in GAN (General Actor Notation) identifiers
+      # Separator in GAN (General Actor Notation) identifiers.
+      # Used to split game identifiers from piece identifiers.
+      #
+      # @example GAN format
+      #   "CHESS:K"  # game: "CHESS", piece: "K"
+      #   "shogi:+p" # game: "shogi", piece: "+p"
       GAN_SEPARATOR = ":"
 
-      private_constant :DROP_ORIGIN, :GAN_SEPARATOR
-
       private
 
-      # Checks if the piece is available in hand for a drop move.
-      #
-      # @param actor [String] GAN identifier of the piece
-      # @param captures [Hash] Pieces available in hand
-      #
-      # @return [Boolean] true if the piece can be dropped
-      def piece_available_in_hand?(actor, captures)
-        return false unless valid_gan_format?(actor)
-
-        base_piece = extract_base_piece(actor)
-        return false if base_piece.nil?
-
-        (captures[base_piece] || 0) > 0
-      end
-
       # Checks if the correct piece is present at the origin square on the board.
       #
+      # This method validates that the expected piece is actually present at the
+      # specified origin square, which is a fundamental requirement for any move.
+      #
       # @param actor [String] GAN identifier of the piece
       # @param origin [String] Origin square
       # @param board_state [Hash] Current board state
       #
       # @return [Boolean] true if the piece is at the correct position
+      #
+      # @example Valid piece placement
+      #   board_state = { "e1" => "CHESS:K", "e2" => "CHESS:P" }
+      #   piece_on_board_at_origin?("CHESS:K", "e1", board_state)
+      #   # => true
+      #
+      # @example Invalid piece placement
+      #   board_state = { "e1" => "CHESS:Q", "e2" => "CHESS:P" }
+      #   piece_on_board_at_origin?("CHESS:K", "e1", board_state)
+      #   # => false (wrong piece at e1)
+      #
+      # @example Empty square
+      #   board_state = { "e1" => nil, "e2" => "CHESS:P" }
+      #   piece_on_board_at_origin?("CHESS:K", "e1", board_state)
+      #   # => false (no piece at e1)
       def piece_on_board_at_origin?(actor, origin, board_state)
         return false unless valid_gan_format?(actor)
         return false unless origin.is_a?(String) && !origin.empty?
@@ -45,67 +53,56 @@ module Sashite
         board_state[origin] == actor
       end
 
-      # Checks if the piece belongs to the current player.
-      # Fixed version that verifies both the game name AND the case.
+      # Checks if the piece belongs to the current player based on case matching.
       #
-      # This method now performs strict validation by ensuring:
-      # - The game identifier matches exactly with the turn parameter
-      # - The case convention is consistent (uppercase/lowercase players)
-      # - The piece part follows the same case convention as the game part
+      # This method implements the corrected ownership logic based on FEEN specification:
+      # - Ownership is determined by case correspondence, not exact string matching
+      # - If active_game is uppercase, the player owns uppercase-cased pieces
+      # - If active_game is lowercase, the player owns lowercase-cased pieces
+      # - This allows for hybrid games where a player may control pieces from different games
       #
       # @param actor [String] GAN identifier of the piece
-      # @param turn [String] Current player's game identifier
+      # @param active_game [String] Current player's game identifier
       #
       # @return [Boolean] true if the piece belongs to the current player
-      def piece_belongs_to_current_player?(actor, turn)
+      #
+      # @example Same game, same case (typical scenario)
+      #   piece_belongs_to_current_player?("CHESS:K", "CHESS")
+      #   # => true (both uppercase)
+      #
+      # @example Different games, same case (hybrid scenario)
+      #   piece_belongs_to_current_player?("MAKRUK:K", "CHESS")
+      #   # => true (both uppercase, player controls both)
+      #
+      # @example Same game, different case
+      #   piece_belongs_to_current_player?("chess:k", "CHESS")
+      #   # => false (different players)
+      #
+      # @example Mixed case active_game (invalid)
+      #   piece_belongs_to_current_player?("CHESS:K", "Chess")
+      #   # => false (invalid active_game format)
+      def piece_belongs_to_current_player?(actor, active_game)
         return false unless valid_gan_format?(actor)
-        return false unless valid_game_identifier?(turn)
+        return false unless valid_game_identifier?(active_game)
 
         game_part, piece_part = actor.split(GAN_SEPARATOR, 2)
 
-        # Strict verification: the game name must match exactly
-        # while considering case to determine the player
-        case turn
-        when turn.upcase
+        # Determine player ownership based on case correspondence
+        # If active_game is uppercase, player owns uppercase pieces
+        # If active_game is lowercase, player owns lowercase pieces
+        case active_game
+        when active_game.upcase
           # Current player is the uppercase one
-          game_part == turn && game_part == game_part.upcase && piece_part.match?(/\A[-+]?[A-Z][']?\z/)
-        when turn.downcase
+          game_part == game_part.upcase && piece_part.match?(/\A[-+]?[A-Z]'?\z/)
+        when active_game.downcase
           # Current player is the lowercase one
-          game_part == turn && game_part == game_part.downcase && piece_part.match?(/\A[-+]?[a-z][']?\z/)
+          game_part == game_part.downcase && piece_part.match?(/\A[-+]?[a-z]'?\z/)
         else
-          # Turn is neither entirely uppercase nor lowercase
+          # active_game is neither entirely uppercase nor lowercase
           false
         end
       end
 
-      # Extracts the base form of a piece (removes modifiers).
-      #
-      # According to FEEN specification, pieces in hand are always stored
-      # in their base form without any state modifiers (prefixes/suffixes).
-      #
-      # @param actor [String] Complete GAN identifier
-      #
-      # @return [String, nil] Base form for hand storage, nil if invalid format
-      def extract_base_piece(actor)
-        return nil unless valid_gan_format?(actor)
-
-        game_part, piece_part = actor.split(GAN_SEPARATOR, 2)
-
-        # Safe extraction of the base character
-        match = piece_part.match(/\A[-+]?([A-Za-z])[']?\z/)
-        return nil unless match
-
-        clean_piece = match[1]
-
-        # Case consistency verification
-        game_is_upper = game_part == game_part.upcase
-        piece_is_upper = clean_piece == clean_piece.upcase
-
-        return nil unless game_is_upper == piece_is_upper
-
-        "#{game_part}#{GAN_SEPARATOR}#{clean_piece}"
-      end
-
       # Validates the GAN format of an identifier.
       #
       # A valid GAN identifier must:
@@ -117,6 +114,16 @@ module Sashite
       # @param actor [String] Identifier to validate
       #
       # @return [Boolean] true if the format is valid
+      #
+      # @example Valid GAN identifiers
+      #   valid_gan_format?("CHESS:K")     # => true
+      #   valid_gan_format?("shogi:+p")    # => true
+      #   valid_gan_format?("MAKRUK:R'")   # => true
+      #
+      # @example Invalid GAN identifiers
+      #   valid_gan_format?("CHESS")       # => false (no colon)
+      #   valid_gan_format?("chess:K")     # => false (case mismatch)
+      #   valid_gan_format?("CHESS:")      # => false (no piece part)
       def valid_gan_format?(actor)
         return false unless actor.is_a?(String)
         return false unless actor.include?(GAN_SEPARATOR)
@@ -131,7 +138,7 @@ module Sashite
 
         # Case consistency verification between game and piece
         game_is_upper = game_part == game_part.upcase
-        piece_match = piece_part.match(/\A[-+]?([A-Za-z])[']?\z/)
+        piece_match = piece_part.match(/\A[-+]?([A-Za-z])'?\z/)
         return false unless piece_match
 
         piece_char = piece_match[1]
@@ -149,6 +156,16 @@ module Sashite
       # @param game_id [String] Game identifier to validate
       #
       # @return [Boolean] true if the identifier is valid
+      #
+      # @example Valid game identifiers
+      #   valid_game_identifier?("CHESS")   # => true
+      #   valid_game_identifier?("shogi")   # => true
+      #   valid_game_identifier?("XIANGQI") # => true
+      #
+      # @example Invalid game identifiers
+      #   valid_game_identifier?("Chess")   # => false (mixed case)
+      #   valid_game_identifier?("")        # => false (empty)
+      #   valid_game_identifier?("CHESS1")  # => false (contains digit)
       def valid_game_identifier?(game_id)
         return false unless game_id.is_a?(String)
         return false if game_id.empty?
@@ -168,12 +185,23 @@ module Sashite
       # @param piece_id [String] Piece identifier to validate
       #
       # @return [Boolean] true if the identifier is valid
+      #
+      # @example Valid piece identifiers
+      #   valid_piece_identifier?("K")      # => true
+      #   valid_piece_identifier?("+p")     # => true
+      #   valid_piece_identifier?("R'")     # => true
+      #   valid_piece_identifier?("-Q'")    # => true
+      #
+      # @example Invalid piece identifiers
+      #   valid_piece_identifier?("")       # => false (empty)
+      #   valid_piece_identifier?("++K")    # => false (double prefix)
+      #   valid_piece_identifier?("K''")    # => false (double suffix)
       def valid_piece_identifier?(piece_id)
         return false unless piece_id.is_a?(String)
         return false if piece_id.empty?
 
         # Format: [optional prefix][letter][optional suffix]
-        piece_id.match?(/\A[-+]?[A-Za-z][']?\z/)
+        piece_id.match?(/\A[-+]?[A-Za-z]'?\z/)
       end
     end
   end

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

@@ -8,79 +8,70 @@ module Sashite
           class Engine
             # Represents the result of a valid pseudo-legal move evaluation.
             #
-            # A Transition encapsulates the changes that occur when a move is executed:
-            # - Board state changes (pieces moving, appearing, or disappearing)
-            # - Pieces gained in hand (from captures)
-            # - Pieces dropped from hand (for drop moves)
+            # A Transition encapsulates the changes that occur when a move is executed
+            # on the game board. Since GGN focuses exclusively on board-to-board
+            # transformations, a Transition only contains board state changes: pieces
+            # moving, appearing, or disappearing on the board.
             #
             # @example Basic move (pawn advance)
-            #   transition = Transition.new(nil, nil, "e2" => nil, "e4" => "CHESS:P")
+            #   transition = Transition.new("e2" => nil, "e4" => "CHESS:P")
             #   transition.diff  # => { "e2" => nil, "e4" => "CHESS:P" }
-            #   transition.gain  # => nil
-            #   transition.drop  # => nil
             #
-            # @example Capture with piece gain
-            #   transition = Transition.new("CHESS:R", nil, "g7" => nil, "h8" => "CHESS:Q")
-            #   transition.gain  # => "CHESS:R" (captured rook goes to hand)
+            # @example Capture (piece takes enemy piece)
+            #   transition = Transition.new("d4" => nil, "e5" => "CHESS:P")
+            #   transition.diff  # => { "d4" => nil, "e5" => "CHESS:P" }
             #
-            # @example Piece drop from hand
-            #   transition = Transition.new(nil, "SHOGI:P", "5e" => "SHOGI:P")
-            #   transition.drop  # => "SHOGI:P" (pawn removed from hand)
+            # @example Complex move (castling with king and rook)
+            #   transition = Transition.new(
+            #     "e1" => nil, "f1" => "CHESS:R", "g1" => "CHESS:K", "h1" => nil
+            #   )
+            #   transition.diff  # => { "e1" => nil, "f1" => "CHESS:R", "g1" => "CHESS:K", "h1" => nil }
+            #
+            # @example Promotion (pawn becomes queen)
+            #   transition = Transition.new("e7" => nil, "e8" => "CHESS:Q")
+            #   transition.diff  # => { "e7" => nil, "e8" => "CHESS:Q" }
             class Transition
               # @return [Hash<String, String|nil>] Board state changes after the move.
               #   Keys are square labels, values are piece identifiers or nil for empty squares.
               attr_reader :diff
 
-              # @return [String, nil] Piece identifier added to the current player's hand,
-              #   typically from a capture. Nil if no piece is gained.
-              attr_reader :gain
-
-              # @return [String, nil] Piece identifier removed from the current player's hand
-              #   for drop moves. Nil if no piece is dropped.
-              attr_reader :drop
-
-              # Creates a new Transition with the specified changes.
+              # Creates a new Transition with the specified board changes.
               #
-              # @param gain [String, nil] Piece gained in hand (usually from capture)
-              # @param drop [String, nil] Piece dropped from hand (for drop moves)
               # @param diff [Hash] Board state changes as keyword arguments.
               #   Keys should be square labels, values should be piece identifiers or nil.
               #
               # @example Creating a simple move transition
-              #   Transition.new(nil, nil, "e2" => nil, "e4" => "CHESS:P")
+              #   Transition.new("e2" => nil, "e4" => "CHESS:P")
               #
               # @example Creating a capture transition
-              #   Transition.new("CHESS:R", nil, "d4" => nil, "e5" => "CHESS:P")
+              #   Transition.new("d4" => nil, "e5" => "CHESS:P")
               #
-              # @example Creating a drop transition
-              #   Transition.new(nil, "SHOGI:P", "3c" => "SHOGI:P")
-              def initialize(gain, drop, **diff)
-                @gain = gain
-                @drop = drop
+              # @example Creating a complex multi-square transition (castling)
+              #   Transition.new(
+              #     "e1" => nil,        # King leaves e1
+              #     "f1" => "CHESS:R",  # Rook moves to f1
+              #     "g1" => "CHESS:K",  # King moves to g1
+              #     "h1" => nil         # Rook leaves h1
+              #   )
+              #
+              # @example Creating a promotion transition
+              #   Transition.new("e7" => nil, "e8" => "CHESS:Q")
+              #
+              # @example Creating an en passant capture
+              #   Transition.new(
+              #     "d5" => nil,        # Attacking pawn leaves d5
+              #     "e5" => nil,        # Captured pawn removed from e5
+              #     "e6" => "CHESS:P"   # Attacking pawn lands on e6
+              #   )
+              def initialize(**diff)
                 @diff = diff
 
                 freeze
               end
 
-              # Checks if this transition involves gaining a piece.
-              #
-              # @return [Boolean] true if a piece is gained (typically from capture)
-              #
-              # @example
-              #   transition.gain?  # => true if @gain is not nil
-              def gain?
-                !@gain.nil?
-              end
-
-              # Checks if this transition involves dropping a piece from hand.
-              #
-              # @return [Boolean] true if a piece is dropped from hand
-              #
-              # @example
-              #   transition.drop?  # => true if @drop is not nil
-              def drop?
-                !@drop.nil?
-              end
+              # This class remains intentionally simple and rule-agnostic.
+              # Any interpretation of what constitutes a "capture" or "promotion"
+              # is left to higher-level game logic, maintaining GGN's neutrality.
             end
           end
         end