sashite-ggn 0.6.0 → 0.8.0

data/lib/sashite/ggn/move_validator.rb

@@ -1,208 +0,0 @@
-# frozen_string_literal: true
-
-module Sashite
-  module Ggn
-    # Centralized module for move condition validation.
-    # 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
-      # 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
-
-      # 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?
-        return false unless board_state.is_a?(Hash)
-
-        board_state[origin] == actor
-      end
-
-      # Checks if the piece belongs to the current player based on case matching.
-      #
-      # 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 active_game [String] Current player's game identifier
-      #
-      # @return [Boolean] true if the piece belongs to the current player
-      #
-      # @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?(active_game)
-
-        game_part, piece_part = actor.split(GAN_SEPARATOR, 2)
-
-        # 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 == game_part.upcase && piece_part.match?(/\A[-+]?[A-Z]'?\z/)
-        when active_game.downcase
-          # Current player is the lowercase one
-          game_part == game_part.downcase && piece_part.match?(/\A[-+]?[a-z]'?\z/)
-        else
-          # active_game is neither entirely uppercase nor lowercase
-          false
-        end
-      end
-
-      # Validates the GAN format of an identifier.
-      #
-      # A valid GAN identifier must:
-      # - Be a string containing exactly one colon separator
-      # - Have a valid game identifier before the colon
-      # - Have a valid piece identifier after the colon
-      # - Maintain case consistency between game and piece parts
-      #
-      # @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)
-
-        parts = actor.split(GAN_SEPARATOR, 2)
-        return false unless parts.length == 2
-
-        game_part, piece_part = parts
-
-        return false unless valid_game_identifier?(game_part)
-        return false unless valid_piece_identifier?(piece_part)
-
-        # 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/)
-        return false unless piece_match
-
-        piece_char = piece_match[1]
-        piece_is_upper = piece_char == piece_char.upcase
-
-        game_is_upper == piece_is_upper
-      end
-
-      # Validates a game identifier.
-      #
-      # Game identifiers must be non-empty strings containing only
-      # alphabetic characters, either all uppercase or all lowercase.
-      # Mixed case is not allowed as it breaks the player distinction.
-      #
-      # @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?
-
-        # Must be either entirely uppercase or entirely lowercase
-        game_id.match?(/\A[A-Z]+\z/) || game_id.match?(/\A[a-z]+\z/)
-      end
-
-      # Validates a piece identifier (part after the colon).
-      #
-      # Piece identifiers follow the pattern: [optional prefix][letter][optional suffix]
-      # Where:
-      # - Optional prefix: + or -
-      # - Letter: A-Z or a-z (must match game part case)
-      # - Optional suffix: ' (apostrophe)
-      #
-      # @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/)
-      end
-    end
-  end
-end

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

@@ -1,81 +0,0 @@
-# frozen_string_literal: true
-
-module Sashite
-  module Ggn
-    class Ruleset
-      class Source
-        class Destination
-          class Engine
-            # Represents the result of a valid pseudo-legal move evaluation.
-            #
-            # 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("e2" => nil, "e4" => "CHESS:P")
-            #   transition.diff  # => { "e2" => nil, "e4" => "CHESS:P" }
-            #
-            # @example Capture (piece takes enemy piece)
-            #   transition = Transition.new("d4" => nil, "e5" => "CHESS:P")
-            #   transition.diff  # => { "d4" => nil, "e5" => "CHESS:P" }
-            #
-            # @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
-
-              # Creates a new Transition with the specified board changes.
-              #
-              # @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("e2" => nil, "e4" => "CHESS:P")
-              #
-              # @example Creating a capture transition
-              #   Transition.new("d4" => nil, "e5" => "CHESS:P")
-              #
-              # @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
-
-              # 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
-      end
-    end
-  end
-end

data/lib/sashite/ggn/schema.rb

@@ -1,171 +0,0 @@
-# frozen_string_literal: true
-
-module Sashite
-  module Ggn
-    # JSON Schema for General Gameplay Notation (GGN) validation.
-    #
-    # This schema defines the structure and constraints for GGN documents,
-    # which describe pseudo-legal moves in abstract strategy board games.
-    # GGN is rule-agnostic and focuses exclusively on board-to-board transformations:
-    # pieces moving, capturing, or transforming on the game board.
-    #
-    # The schema has been updated to reflect GGN's focus on board transformations only.
-    # Hand management, piece drops, and captures-to-hand are outside the scope of GGN.
-    #
-    # @example Basic GGN document structure
-    #   {
-    #     "CHESS:K": {
-    #       "e1": {
-    #         "e2": [
-    #           {
-    #             "require": { "e2": "empty" },
-    #             "perform": { "e1": null, "e2": "CHESS:K" }
-    #           }
-    #         ]
-    #       }
-    #     }
-    #   }
-    #
-    # @example Complex move with multiple conditions
-    #   {
-    #     "CHESS:P": {
-    #       "d5": {
-    #         "e6": [
-    #           {
-    #             "require": { "e5": "chess:p", "e6": "empty" },
-    #             "perform": { "d5": null, "e5": null, "e6": "CHESS:P" }
-    #           }
-    #         ]
-    #       }
-    #     }
-    #   }
-    #
-    # @example Multi-square move (castling)
-    #   {
-    #     "CHESS:K": {
-    #       "e1": {
-    #         "g1": [
-    #           {
-    #             "require": { "f1": "empty", "g1": "empty", "h1": "CHESS:R" },
-    #             "perform": { "e1": null, "f1": "CHESS:R", "g1": "CHESS:K", "h1": null }
-    #           }
-    #         ]
-    #       }
-    #     }
-    #   }
-    #
-    # @see https://sashite.dev/documents/ggn/1.0.0/ GGN Specification
-    # @see https://sashite.dev/schemas/ggn/1.0.0/schema.json JSON Schema URL
-    Schema = {
-      # JSON Schema meta-information
-      "$schema": "https://json-schema.org/draft/2020-12/schema",
-      "$id": "https://sashite.dev/schemas/ggn/1.0.0/schema.json",
-      "title": "General Gameplay Notation (GGN)",
-      "description": "JSON Schema for pseudo-legal moves in abstract board games using the GGN format. GGN focuses exclusively on board-to-board transformations.",
-      "type": "object",
-
-      # Optional schema reference property
-      "properties": {
-        # Allows documents to self-reference the schema
-        "$schema": {
-          "type": "string",
-          "format": "uri"
-        }
-      },
-
-      # Pattern-based validation for GAN (General Actor Notation) identifiers
-      # Matches format: GAME:piece_char (e.g., "CHESS:K'", "shogi:+p", "XIANGQI:E")
-      "patternProperties": {
-        # GAN pattern: game identifier (with casing) + colon + piece identifier
-        # Supports prefixes (-/+), suffixes ('), and both uppercase/lowercase games
-        "^([A-Z]+:[-+]?[A-Z][']?|[a-z]+:[-+]?[a-z][']?)$": {
-          "type": "object",
-          "minProperties": 1,
-
-          # Source squares: where the piece starts (regular board squares only)
-          "patternProperties": {
-            ".+": {
-              "type": "object",
-              "minProperties": 1,
-
-              # Destination squares: where the piece can move to (regular board squares only)
-              "patternProperties": {
-                ".+": {
-                  "type": "array",
-                  "minItems": 1,
-
-                  # Array of conditional transitions for this source->destination pair
-                  "items": {
-                    "type": "object",
-                    "properties": {
-                      # Conditions that MUST be satisfied before the move (logical AND)
-                      "require": {
-                        "type": "object",
-                        "minProperties": 1,
-                        "patternProperties": {
-                          ".+": {
-                            "type": "string",
-                            # Occupation states: "empty", "enemy", or exact GAN identifier
-                            "pattern": "^(empty|enemy|[A-Z]+:[-+]?[A-Z][']?|[a-z]+:[-+]?[a-z][']?)$"
-                          }
-                        },
-                        "additionalProperties": false
-                      },
-
-                      # Conditions that MUST NOT be satisfied before the move (logical OR)
-                      "prevent": {
-                        "type": "object",
-                        "minProperties": 1,
-                        "patternProperties": {
-                          ".+": {
-                            "type": "string",
-                            # Same occupation states as require
-                            "pattern": "^(empty|enemy|[A-Z]+:[-+]?[A-Z][']?|[a-z]+:[-+]?[a-z][']?)$"
-                          }
-                        },
-                        "additionalProperties": false
-                      },
-
-                      # Board state changes after the move (REQUIRED field)
-                      # This is the core of GGN: describing board transformations
-                      "perform": {
-                        "type": "object",
-                        "minProperties": 1,
-                        "patternProperties": {
-                          ".+": {
-                            "anyOf": [
-                              {
-                                # Square contains a piece (GAN identifier)
-                                "type": "string",
-                                "pattern": "^([A-Z]+:[-+]?[A-Z][']?|[a-z]+:[-+]?[a-z][']?)$"
-                              },
-                              {
-                                # Square becomes empty (null)
-                                "type": "null"
-                              }
-                            ]
-                          }
-                        },
-                        "additionalProperties": false
-                      }
-                    },
-
-                    # Only "perform" is mandatory; "require" and "prevent" are optional
-                    # NOTE: "gain" and "drop" fields are no longer supported in GGN
-                    "required": ["perform"],
-                    "additionalProperties": false
-                  }
-                }
-              },
-              "additionalProperties": false
-            }
-          },
-          "additionalProperties": false
-        }
-      },
-
-      # No additional properties allowed at root level (strict validation)
-      "additionalProperties": false
-    }.freeze
-  end
-end

data/lib/sashite/ggn/validation_error.rb

@@ -1,56 +0,0 @@
-# frozen_string_literal: true
-
-module Sashite
-  module Ggn
-    # Custom exception class for GGN validation and processing errors.
-    #
-    # This exception is raised when GGN documents fail validation against
-    # the JSON Schema, contain malformed data, or encounter processing errors
-    # during parsing and evaluation of pseudo-legal moves.
-    #
-    # Since GGN focuses exclusively on board-to-board transformations, validation
-    # errors typically relate to:
-    # - Invalid board position representations
-    # - Malformed GAN identifiers or square labels
-    # - Logical contradictions in require/prevent conditions
-    # - Missing or invalid perform actions
-    #
-    # Common scenarios that raise ValidationError:
-    # - Invalid JSON syntax in GGN files
-    # - Schema validation failures (missing required fields, invalid patterns)
-    # - File system errors (file not found, permission denied)
-    # - Malformed GAN identifiers or square labels
-    # - Logical contradictions in require/prevent conditions
-    # - Invalid board transformation specifications
-    #
-    # @example Handling validation errors during file loading
-    #   begin
-    #     piece_data = Sashite::Ggn.load_file('invalid_moves.json')
-    #   rescue Sashite::Ggn::ValidationError => e
-    #     puts "GGN validation failed: #{e.message}"
-    #     # Handle the error appropriately
-    #   end
-    #
-    # @example Handling validation errors during move evaluation
-    #   begin
-    #     transitions = engine.where(board_state, 'CHESS')
-    #   rescue Sashite::Ggn::ValidationError => e
-    #     puts "Move evaluation failed: #{e.message}"
-    #     # Handle invalid board state or parameters
-    #   end
-    #
-    # @example Handling schema validation errors
-    #   begin
-    #     Sashite::Ggn.validate!(ggn_data)
-    #   rescue Sashite::Ggn::ValidationError => e
-    #     puts "Schema validation failed: #{e.message}"
-    #     # The data doesn't conform to GGN specification
-    #   end
-    #
-    # @see Sashite::Ggn.load_file Main method that can raise this exception
-    # @see Sashite::Ggn.validate! Schema validation method
-    # @see Sashite::Ggn::Schema JSON Schema used for validation
-    class ValidationError < ::StandardError
-    end
-  end
-end