sashite-ggn 0.8.0 → 0.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 71b56f3fe3aa4fe158bc428cb92880751133bfc769ac9a300f78026e51c95ef6
-  data.tar.gz: 779187aa54e75e9ef0d679bc0617b4a6230052e5ab24018409932654cd351be7
+  metadata.gz: e471fdf36ded96b18559ff0c7f6ba47b9210624d019452bc4037b93e484cf29c
+  data.tar.gz: cd99ab6b95f0bdc4377c87c67864c861288d0d7dec536450cf36698c6da5b3de
 SHA512:
-  metadata.gz: 94c8dd3916c7032479547f949e75a6b1865f95a19d1baba421947931b7bb2dd700dc8672b0297734c677ae02152dfd7526eec1a6cfed549d6f484cc3d97dbba3
-  data.tar.gz: 818b73b8a42e82e968e02aac3b9e8cade1f46a59765e56d19f5f3e8fe68478395a8d3134a074e0037890a61eadbc39989a406e7ff86a580f8defda5abb0d1d0d
+  metadata.gz: ce76a683d986574ff72d6830805aa90f636e617349f04514feca2a500b2510d073f59f305a9c666100848a1b5e5806b9d59b97f5bb1aae870eff2fd982f4755e
+  data.tar.gz: 98cc6ac792be2873d3a73fb9154ec0493614f82bcb2d10087224246fbb1d8206b21335f0ab1d175509a815210a4ec22deb8e0103eb5c1c83ad1cfe6f6c65f2ea

data/README.md

@@ -52,7 +52,6 @@ GGN builds upon foundational Sashité specifications:
 
 ```ruby
 gem "sashite-cell"  # Coordinate Encoding for Layered Locations
-gem "sashite-feen"  # Forsyth–Edwards Enhanced Notation
 gem "sashite-hand"  # Hold And Notation Designator
 gem "sashite-lcn"   # Location Condition Notation
 gem "sashite-qpi"   # Qualified Piece Identifier
@@ -66,7 +65,7 @@ gem "sashite-stn"   # State Transition Notation
 ```ruby
 require "sashite/ggn"
 
-# Parse GGN data structure
+# Define GGN data structure
 ggn_data = {
   "C:P" => {
     "e2" => {
@@ -84,12 +83,26 @@ ggn_data = {
   }
 }
 
+# Validate GGN structure
+Sashite::Ggn.valid?(ggn_data) # => true
+
+# Parse into ruleset
 ruleset = Sashite::Ggn.parse(ggn_data)
 
 # Query movement possibility through method chaining
-feen = "+rnbq+kbn+r/+p+p+p+p+p+p+p+p/8/8/8/8/+P+P+P+P+P+P+P+P/+RNBQ+KBN+R / C/c"
-transitions = ruleset.select("C:P").from("e2").to("e4").where(feen)
+source = ruleset.select("C:P")
+destination = source.from("e2")
+engine = destination.to("e4")
+
+# Evaluate against position
+active_side = :first
+squares = {
+  "e2" => "C:P",
+  "e3" => nil,
+  "e4" => nil
+}
 
+transitions = engine.where(active_side, squares)
 transitions.any? # => true
 ```
 
@@ -152,22 +165,6 @@ source = ruleset.select("C:K")
 
 ---
 
-#### `#pseudo_legal_transitions(feen) → Array<Array>`
-
-Generates all pseudo-legal moves for the given position.
-
-```ruby
-moves = ruleset.pseudo_legal_transitions(feen)
-# => [["C:P", "e2", "e4", [#<Transition...>]], ...]
-```
-
-**Parameters:**
-- `feen` (String): Position in FEEN format
-
-**Returns:** `Array<Array>` — Array of `[piece, source, destination, transitions]` tuples
-
----
-
 #### `#piece?(piece) → Boolean`
 
 Checks if ruleset contains movement rules for specified piece.
@@ -195,18 +192,6 @@ ruleset.pieces # => ["C:K", "C:Q", "C:P", ...]
 
 ---
 
-#### `#to_h → Hash`
-
-Converts ruleset to hash representation.
-
-```ruby
-ruleset.to_h # => { "C:K" => { "e1" => { "e2" => [...] } } }
-```
-
-**Returns:** `Hash` — GGN data structure
-
----
-
 ### `Sashite::Ggn::Ruleset::Source` Class
 
 Represents movement possibilities for a piece type.
@@ -307,34 +292,29 @@ destination.destination?("e2") # => true
 
 Evaluates movement possibility under given position conditions.
 
-#### `#where(feen) → Array<Transition>`
+#### `#where(active_side, squares) → Array<Transition>`
 
 Evaluates movement against position and returns valid transitions.
 
 ```ruby
-transitions = engine.where(feen)
+active_side = :first
+squares = {
+  "e2" => "C:P",  # White pawn on e2
+  "e3" => nil,    # Empty square
+  "e4" => nil     # Empty square
+}
+
+transitions = engine.where(active_side, squares)
 ```
 
 **Parameters:**
-- `feen` (String): Position in FEEN format
+- `active_side` (Symbol): Active player side (`:first` or `:second`)
+- `squares` (Hash): Board state where keys are CELL coordinates and values are QPI identifiers or `nil` for empty squares
 
 **Returns:** `Array<Sashite::Stn::Transition>` — Valid state transitions (may be empty)
 
 ---
 
-#### `#possibilities → Array<Hash>`
-
-Returns raw movement possibility rules.
-
-```ruby
-engine.possibilities
-# => [{ "must" => {...}, "deny" => {...}, "diff" => {...} }]
-```
-
-**Returns:** `Array<Hash>` — Movement possibility specifications
-
----
-
 ## GGN Format
 
 ### Structure
@@ -366,6 +346,8 @@ engine.possibilities
 | **deny** | Hash (LCN) | Pre-conditions that must not be satisfied |
 | **diff** | Hash (STN) | State transition specification |
 
+**Note (normative)**: To preserve GGN's board-reachability scope, entries where **`source="*"` and `destination="*"`** (direct **HAND→HAND**) are **forbidden** by the specification.
+
 ---
 
 ## Usage Examples
@@ -374,28 +356,65 @@ engine.possibilities
 
 ```ruby
 # Query specific movement
-feen = "+rnbq+kbn+r/+p+p+p+p+p+p+p+p/8/8/8/8/+P+P+P+P+P+P+P+P/+RNBQ+KBN+R / C/c"
+active_side = :first
+squares = {
+  "e2" => "C:P",
+  "e3" => nil,
+  "e4" => nil
+}
 
 transitions = ruleset
   .select("C:P")
   .from("e2")
   .to("e4")
-  .where(feen)
+  .where(active_side, squares)
 
 transitions.size # => 1
 transitions.first.board_changes # => { "e2" => nil, "e4" => "C:P" }
 ```
 
-### Generate All Pseudo-Legal Moves
+### Building Board State
 
 ```ruby
+# Example: Build squares hash from FEEN position
+require "sashite/feen"
+
 feen = "+rnbq+kbn+r/+p+p+p+p+p+p+p+p/8/8/8/8/+P+P+P+P+P+P+P+P/+RNBQ+KBN+R / C/c"
+position = Sashite::Feen.parse(feen)
+
+# Extract active player side
+active_side = position.styles.active.side # => :first
+
+# Build squares hash from placement
+squares = {}
+position.placement.ranks.each_with_index do |rank, rank_idx|
+  rank.each_with_index do |piece, file_idx|
+    # Convert rank_idx and file_idx to CELL coordinate
+    cell = Sashite::Cell.from_indices(file_idx, 7 - rank_idx)
+    squares[cell] = piece&.to_s
+  end
+end
 
-all_moves = ruleset.pseudo_legal_transitions(feen)
+# Use with GGN
+transitions = engine.where(active_side, squares)
+```
 
-all_moves.each do |piece, source, destination, transitions|
-  puts "#{piece}: #{source} → #{destination} (#{transitions.size} variants)"
-end
+### Capture Validation
+
+```ruby
+# Check capture possibility
+active_side = :first
+squares = {
+  "e4" => "C:P",  # White pawn
+  "d5" => "c:p",  # Black pawn (enemy)
+  "f5" => "c:p"   # Black pawn (enemy)
+}
+
+# Pawn can capture diagonally
+capture_engine = ruleset.select("C:P").from("e4").to("d5")
+transitions = capture_engine.where(active_side, squares)
+
+transitions.any? # => true if capture is allowed
 ```
 
 ### Existence Checks
@@ -424,10 +443,6 @@ source.sources # => ["e1", "d1", "f1", ...]
 
 # List destinations from a source
 destination.destinations # => ["d1", "d2", "e2", "f2", "f1"]
-
-# Access raw possibilities
-engine.possibilities
-# => [{ "must" => {...}, "deny" => {...}, "diff" => {...} }]
 ```
 
 ---
@@ -437,8 +452,9 @@ engine.possibilities
 - **Functional**: Pure functions with no side effects
 - **Immutable**: All data structures frozen and unchangeable
 - **Composable**: Clean method chaining for natural query flow
+- **Minimal API**: Only exposes what's necessary
 - **Type-safe**: Strict validation of all inputs
-- **Delegative**: Leverages CELL, FEEN, HAND, LCN, QPI, STN specifications
+- **Lightweight**: Minimal dependencies, no unnecessary parsing
 - **Spec-compliant**: Strictly follows GGN v1.0.0 specification
 
 ---
@@ -481,7 +497,6 @@ end
 
 - [GGN v1.0.0](https://sashite.dev/specs/ggn/1.0.0/) — General Gameplay Notation specification
 - [CELL v1.0.0](https://sashite.dev/specs/cell/1.0.0/) — Coordinate encoding
-- [FEEN v1.0.0](https://sashite.dev/specs/feen/1.0.0/) — Position notation
 - [HAND v1.0.0](https://sashite.dev/specs/hand/1.0.0/) — Reserve notation
 - [LCN v1.0.0](https://sashite.dev/specs/lcn/1.0.0/) — Location conditions
 - [QPI v1.0.0](https://sashite.dev/specs/qpi/1.0.0/) — Piece identification

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

@@ -1,8 +1,5 @@
 # frozen_string_literal: true
 
-require "sashite/cell"
-require "sashite/epin"
-require "sashite/feen"
 require "sashite/lcn"
 require "sashite/qpi"
 require "sashite/stn"
@@ -16,166 +13,103 @@ module Sashite
           #
           # @see https://sashite.dev/specs/ggn/1.0.0/
           class Engine
-            # @return [String] The QPI piece identifier
-            attr_reader :piece
-
-            # @return [String] The source location
-            attr_reader :source
-
-            # @return [String] The destination location
-            attr_reader :destination
-
-            # @return [Array<Hash>] The movement possibilities
-            attr_reader :data
-
             # Create a new Engine
             #
-            # @param piece [String] QPI piece identifier
-            # @param source [String] Source location
-            # @param destination [String] Destination location
-            # @param data [Array<Hash>] Movement possibilities data
-            def initialize(piece, source, destination, data)
-              @piece = piece
-              @source = source
-              @destination = destination
-              @data = data
-
+            # @param possibilities [Array<Hash>] Movement possibilities data
+            def initialize(*possibilities)
+              @possibilities = possibilities
               freeze
             end
 
             # Evaluate movement against position and return valid transitions
             #
-            # @param feen [String] Position in FEEN format
+            # @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
-            #   transitions = engine.where(feen)
-            def where(feen)
-              position = Feen.parse(feen)
-              reference_side = Qpi.parse(piece).side
-
-              possibilities.select do |possibility|
-                satisfies_must?(possibility["must"], position, reference_side) &&
-                  satisfies_deny?(possibility["deny"], position, reference_side)
+            #   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
 
-            # Return raw movement possibility rules
-            #
-            # @return [Array<Hash>] Movement possibility specifications
-            #
-            # @example
-            #   engine.possibilities
-            #   # => [{ "must" => {...}, "deny" => {...}, "diff" => {...} }]
-            def possibilities
-              data
-            end
-
             private
 
             # Check if all 'must' conditions are satisfied
             #
             # @param conditions [Hash] LCN conditions
-            # @param position [Feen::Position] Current position
-            # @param reference_side [Symbol] Reference piece side (:first or :second)
+            # @param active_side [Symbol] Active player side
+            # @param squares [Hash] Board state
             # @return [Boolean]
-            def satisfies_must?(conditions, position, reference_side)
+            def satisfies_must?(conditions, active_side, squares)
               return true if conditions.empty?
 
               lcn_conditions = Lcn.parse(conditions)
 
               lcn_conditions.locations.all? do |location|
                 expected_state = lcn_conditions[location]
-                check_condition(location, expected_state, position, reference_side)
+                check_condition(location.to_s, expected_state, active_side, squares)
               end
             end
 
             # Check if all 'deny' conditions are not satisfied
             #
             # @param conditions [Hash] LCN conditions
-            # @param position [Feen::Position] Current position
-            # @param reference_side [Symbol] Reference piece side (:first or :second)
+            # @param active_side [Symbol] Active player side
+            # @param squares [Hash] Board state
             # @return [Boolean]
-            def satisfies_deny?(conditions, position, reference_side)
+            def satisfies_deny?(conditions, active_side, squares)
               return true if conditions.empty?
 
               lcn_conditions = Lcn.parse(conditions)
 
               lcn_conditions.locations.none? do |location|
                 expected_state = lcn_conditions[location]
-                check_condition(location, expected_state, position, reference_side)
+                check_condition(location.to_s, expected_state, active_side, squares)
               end
             end
 
             # Check if a location satisfies a condition
             #
-            # @param location [Symbol] Location to check
+            # @param location [String] Location to check (CELL coordinate)
             # @param expected_state [String] Expected state value
-            # @param position [Feen::Position] Current position
-            # @param reference_side [Symbol] Reference piece side
+            # @param active_side [Symbol] Active player side
+            # @param squares [Hash] Board state
             # @return [Boolean]
-            def check_condition(location, expected_state, position, reference_side)
-              location_str = location.to_s
-              epin_value = get_piece_at(position, location_str)
+            def check_condition(location, expected_state, active_side, squares)
+              actual_qpi = squares[location]
 
               case expected_state
               when "empty"
-                epin_value.nil?
+                actual_qpi.nil?
               when "enemy"
-                epin_value && is_enemy?(epin_value, reference_side)
+                actual_qpi && enemy?(actual_qpi, active_side)
               else
-                # Expected state is a QPI identifier - compare EPIN parts
-                epin_value && matches_qpi?(epin_value, expected_state)
+                # Expected state is a QPI identifier
+                actual_qpi == expected_state
               end
             end
 
-            # Get piece at a board location
+            # Check if a piece is an enemy relative to active side
             #
-            # @param position [Feen::Position] Current position
-            # @param location [String] Board location (CELL coordinate)
-            # @return [Object, nil] EPIN value or nil if empty
-            def get_piece_at(position, location)
-              indices = Cell.to_indices(location)
-              col_index = indices[0]
-              row_index_from_bottom = indices[1]
-
-              # FEEN ranks are stored top-to-bottom, but CELL indices are bottom-up
-              # Need to invert the rank index
-              total_ranks = position.placement.ranks.size
-              rank_index = total_ranks - 1 - row_index_from_bottom
-
-              position.placement.ranks[rank_index][col_index]
-            end
-
-            # Check if a piece is an enemy relative to reference side
-            #
-            # @param epin_value [Object] EPIN value from ranks
-            # @param reference_side [Symbol] Reference side
+            # @param qpi_str [String] QPI identifier
+            # @param active_side [Symbol] Active player side
             # @return [Boolean]
-            def is_enemy?(epin_value, reference_side)
-              epin_str = epin_value.to_s
-              piece_side = epin_str.match?(/[A-Z]/) ? :first : :second
-              piece_side != reference_side
-            end
-
-            # Check if EPIN matches QPI identifier
-            #
-            # @param epin_value [Object] EPIN value from ranks
-            # @param qpi_str [String] QPI identifier to match
-            # @return [Boolean]
-            def matches_qpi?(epin_value, qpi_str)
-              epin_str = epin_value.to_s
-
-              # Extract EPIN part from QPI (after the colon)
-              qpi_parts = qpi_str.split(":")
-              return false if qpi_parts.length != 2
-
-              expected_epin = qpi_parts[1]
-
-              # Direct comparison of EPIN strings
-              epin_str == expected_epin
+            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

@@ -10,25 +10,11 @@ module Sashite
         #
         # @see https://sashite.dev/specs/ggn/1.0.0/
         class Destination
-          # @return [String] The QPI piece identifier
-          attr_reader :piece
-
-          # @return [String] The source location
-          attr_reader :source
-
-          # @return [Hash] The destinations data
-          attr_reader :data
-
           # Create a new Destination
           #
-          # @param piece [String] QPI piece identifier
-          # @param source [String] Source location
           # @param data [Hash] Destinations data structure
-          def initialize(piece, source, data)
-            @piece = piece
-            @source = source
+          def initialize(data)
             @data = data
-
             freeze
           end
 
@@ -43,7 +29,7 @@ module Sashite
           def to(destination)
             raise ::KeyError, "Destination not found: #{destination}" unless destination?(destination)
 
-            Engine.new(piece, source, destination, data.fetch(destination))
+            Engine.new(*@data.fetch(destination))
           end
 
           # Return all valid destinations from this source
@@ -53,7 +39,7 @@ module Sashite
           # @example
           #   destination.destinations # => ["d1", "d2", "e2", "f2", "f1"]
           def destinations
-            data.keys
+            @data.keys
           end
 
           # Check if location is a valid destination from this source
@@ -64,7 +50,7 @@ module Sashite
           # @example
           #   destination.destination?("e2") # => true
           def destination?(location)
-            data.key?(location)
+            @data.key?(location)
           end
         end
       end

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

@@ -9,20 +9,11 @@ module Sashite
       #
       # @see https://sashite.dev/specs/ggn/1.0.0/
       class Source
-        # @return [String] The QPI piece identifier
-        attr_reader :piece
-
-        # @return [Hash] The sources data
-        attr_reader :data
-
         # Create a new Source
         #
-        # @param piece [String] QPI piece identifier
         # @param data [Hash] Sources data structure
-        def initialize(piece, data)
-          @piece = piece
+        def initialize(data)
           @data = data
-
           freeze
         end
 
@@ -37,7 +28,7 @@ module Sashite
         def from(source)
           raise ::KeyError, "Source not found: #{source}" unless source?(source)
 
-          Destination.new(piece, source, data.fetch(source))
+          Destination.new(@data.fetch(source))
         end
 
         # Return all valid source locations for this piece
@@ -47,7 +38,7 @@ module Sashite
         # @example
         #   source.sources # => ["e1", "d1", "*"]
         def sources
-          data.keys
+          @data.keys
         end
 
         # Check if location is a valid source for this piece
@@ -58,7 +49,7 @@ module Sashite
         # @example
         #   source.source?("e1") # => true
         def source?(location)
-          data.key?(location)
+          @data.key?(location)
         end
       end
     end

data/lib/sashite/ggn/ruleset.rb

@@ -1,36 +1,28 @@
 # frozen_string_literal: true
 
-require "sashite/cell"
-require "sashite/hand"
-require "sashite/lcn"
-require "sashite/qpi"
-require "sashite/stn"
-
 require_relative "ruleset/source"
 
 module Sashite
   module Ggn
     # Immutable container for GGN movement rules
     #
+    # @note Instances are created through {Sashite::Ggn.parse}, which handles validation.
+    #   The constructor itself does not validate.
+    #
     # @see https://sashite.dev/specs/ggn/1.0.0/
     class Ruleset
-      # @return [Hash] The underlying GGN data structure
-      attr_reader :data
-
       # Create a new Ruleset from GGN data structure
       #
-      # @param data [Hash] GGN data structure
-      # @raise [ArgumentError] If data structure is invalid
-      # @example With invalid structure
-      #   begin
-      #     Sashite::Ggn::Ruleset.new({ "invalid" => "data" })
-      #   rescue ArgumentError => e
-      #     puts e.message # => "Invalid QPI format: invalid"
-      #   end
+      # @note This constructor does not validate the data structure.
+      #   Use {Sashite::Ggn.parse} or {Sashite::Ggn.valid?} for validation.
+      #
+      # @param data [Hash] GGN data structure (pre-validated)
+      #
+      # @example
+      #   # Don't use directly - use Sashite::Ggn.parse instead
+      #   ruleset = Sashite::Ggn::Ruleset.new(data)
       def initialize(data)
-        validate_structure!(data)
         @data = data
-
         freeze
       end
 
@@ -45,39 +37,7 @@ module Sashite
       def select(piece)
         raise ::KeyError, "Piece not found: #{piece}" unless piece?(piece)
 
-        Source.new(piece, data.fetch(piece))
-      end
-
-      # Generate all pseudo-legal moves for the given position
-      #
-      # @note This method evaluates all possible moves in the ruleset.
-      #   For large rulesets, consider filtering by active pieces first.
-      #
-      # @param feen [String] Position in FEEN format
-      # @return [Array<Array(String, String, String, Array<Sashite::Stn::Transition>)>]
-      #   Array of tuples containing:
-      #   - piece (String): QPI identifier
-      #   - source (String): CELL coordinate or HAND "*"
-      #   - destination (String): CELL coordinate or HAND "*"
-      #   - transitions (Array<Sashite::Stn::Transition>): Valid state transitions
-      #
-      # @example
-      #   moves = ruleset.pseudo_legal_transitions(feen)
-      def pseudo_legal_transitions(feen)
-        pieces.flat_map do |piece|
-          source = select(piece)
-
-          source.sources.flat_map do |src|
-            destination = source.from(src)
-
-            destination.destinations.flat_map do |dest|
-              engine = destination.to(dest)
-              transitions = engine.where(feen)
-
-              transitions.empty? ? [] : [[piece, src, dest, transitions]]
-            end
-          end
-        end
+        Source.new(@data.fetch(piece))
       end
 
       # Check if ruleset contains movement rules for specified piece
@@ -88,7 +48,7 @@ module Sashite
       # @example
       #   ruleset.piece?("C:K") # => true
       def piece?(piece)
-        data.key?(piece)
+        @data.key?(piece)
       end
 
       # Return all piece identifiers in ruleset
@@ -98,151 +58,7 @@ module Sashite
       # @example
       #   ruleset.pieces # => ["C:K", "C:Q", "C:P", ...]
       def pieces
-        data.keys
-      end
-
-      # Convert ruleset to hash representation
-      #
-      # @return [Hash] GGN data structure
-      #
-      # @example
-      #   ruleset.to_h # => { "C:K" => { "e1" => { "e2" => [...] } } }
-      def to_h
-        data
-      end
-
-      private
-
-      # Validate GGN data structure
-      #
-      # @param data [Hash] Data to validate
-      # @raise [ArgumentError] If structure is invalid
-      # @return [void]
-      def validate_structure!(data)
-        raise ::ArgumentError, "GGN data must be a Hash" unless data.is_a?(::Hash)
-
-        data.each do |piece, sources|
-          validate_piece!(piece)
-          validate_sources!(sources, piece)
-        end
-      end
-
-      # Validate QPI piece identifier using sashite-qpi
-      #
-      # @param piece [String] Piece identifier to validate
-      # @raise [ArgumentError] If piece identifier is invalid
-      # @return [void]
-      def validate_piece!(piece)
-        raise ::ArgumentError, "Invalid piece identifier: #{piece}" unless piece.is_a?(::String)
-        raise ::ArgumentError, "Invalid QPI format: #{piece}" unless Qpi.valid?(piece)
-      end
-
-      # Validate sources hash structure
-      #
-      # @param sources [Hash] Sources hash to validate
-      # @param piece [String] Piece identifier (for error messages)
-      # @raise [ArgumentError] If sources structure is invalid
-      # @return [void]
-      def validate_sources!(sources, piece)
-        raise ::ArgumentError, "Sources for #{piece} must be a Hash" unless sources.is_a?(Hash)
-
-        sources.each do |source, destinations|
-          validate_location!(source, piece)
-          validate_destinations!(destinations, piece, source)
-        end
-      end
-
-      # Validate destinations hash structure
-      #
-      # @param destinations [Hash] Destinations hash to validate
-      # @param piece [String] Piece identifier (for error messages)
-      # @param source [String] Source location (for error messages)
-      # @raise [ArgumentError] If destinations structure is invalid
-      # @return [void]
-      def validate_destinations!(destinations, piece, source)
-        raise ::ArgumentError, "Destinations for #{piece} from #{source} must be a Hash" unless destinations.is_a?(::Hash)
-
-        destinations.each do |destination, possibilities|
-          validate_location!(destination, piece)
-          validate_possibilities!(possibilities, piece, source, destination)
-        end
-      end
-
-      # Validate possibilities array structure
-      #
-      # @param possibilities [Array] Possibilities array to validate
-      # @param piece [String] Piece identifier (for error messages)
-      # @param source [String] Source location (for error messages)
-      # @param destination [String] Destination location (for error messages)
-      # @raise [ArgumentError] If possibilities structure is invalid
-      # @return [void]
-      def validate_possibilities!(possibilities, piece, source, destination)
-        raise ::ArgumentError, "Possibilities for #{piece} #{source}→#{destination} must be an Array" unless possibilities.is_a?(::Array)
-
-        possibilities.each do |possibility|
-          validate_possibility!(possibility, piece, source, destination)
-        end
-      end
-
-      # Validate individual possibility structure using LCN and STN gems
-      #
-      # @param possibility [Hash] Possibility to validate
-      # @param piece [String] Piece identifier (for error messages)
-      # @param source [String] Source location (for error messages)
-      # @param destination [String] Destination location (for error messages)
-      # @raise [ArgumentError] If possibility structure is invalid
-      # @return [void]
-      def validate_possibility!(possibility, piece, source, destination)
-        raise ::ArgumentError, "Possibility for #{piece} #{source}→#{destination} must be a Hash" unless possibility.is_a?(::Hash)
-        raise ::ArgumentError, "Possibility must have 'must' field" unless possibility.key?("must")
-        raise ::ArgumentError, "Possibility must have 'deny' field" unless possibility.key?("deny")
-        raise ::ArgumentError, "Possibility must have 'diff' field" unless possibility.key?("diff")
-
-        validate_lcn_conditions!(possibility["must"], "must", piece, source, destination)
-        validate_lcn_conditions!(possibility["deny"], "deny", piece, source, destination)
-        validate_stn_transition!(possibility["diff"], piece, source, destination)
-      end
-
-      # Validate LCN conditions using sashite-lcn
-      #
-      # @param conditions [Hash] Conditions to validate
-      # @param field_name [String] Field name for error messages
-      # @param piece [String] Piece identifier (for error messages)
-      # @param source [String] Source location (for error messages)
-      # @param destination [String] Destination location (for error messages)
-      # @raise [ArgumentError] If conditions are invalid
-      # @return [void]
-      def validate_lcn_conditions!(conditions, field_name, piece, source, destination)
-        Lcn.parse(conditions)
-      rescue ArgumentError => e
-        raise ::ArgumentError, "Invalid LCN format in '#{field_name}' for #{piece} #{source}→#{destination}: #{e.message}"
-      end
-
-      # Validate STN transition using sashite-stn
-      #
-      # @param transition [Hash] Transition to validate
-      # @param piece [String] Piece identifier (for error messages)
-      # @param source [String] Source location (for error messages)
-      # @param destination [String] Destination location (for error messages)
-      # @raise [ArgumentError] If transition is invalid
-      # @return [void]
-      def validate_stn_transition!(transition, piece, source, destination)
-        Stn.parse(transition)
-      rescue StandardError => e
-        raise ::ArgumentError, "Invalid STN format in 'diff' for #{piece} #{source}→#{destination}: #{e.message}"
-      end
-
-      # Validate location format using CELL and HAND gems
-      #
-      # @param location [String] Location to validate
-      # @param piece [String] Piece identifier (for error messages)
-      # @raise [ArgumentError] If location format is invalid
-      # @return [void]
-      def validate_location!(location, piece)
-        raise ::ArgumentError, "Location for #{piece} must be a String" unless location.is_a?(::String)
-
-        valid = Cell.valid?(location) || Hand.reserve?(location)
-        raise ::ArgumentError, "Invalid location format: #{location}" unless valid
+        @data.keys
       end
     end
   end

data/lib/sashite/ggn.rb

@@ -1,5 +1,11 @@
 # frozen_string_literal: true
 
+require "sashite/cell"
+require "sashite/hand"
+require "sashite/lcn"
+require "sashite/qpi"
+require "sashite/stn"
+
 require_relative "ggn/ruleset"
 
 module Sashite
@@ -14,7 +20,7 @@ module Sashite
     #
     # @param data [Hash] GGN data structure conforming to specification
     # @return [Ruleset] Immutable ruleset object
-    # @raise [ArgumentError, TypeError] If data structure is invalid
+    # @raise [ArgumentError] If data structure is invalid
     #
     # @example Parse GGN data
     #   ruleset = Sashite::Ggn.parse({
@@ -34,6 +40,7 @@ module Sashite
     #     }
     #   })
     def self.parse(data)
+      validate!(data)
       Ruleset.new(data)
     end
 
@@ -42,17 +49,184 @@ module Sashite
     # @param data [Hash] Data structure to validate
     # @return [Boolean] True if valid, false otherwise
     #
-    # @note Rescues both ArgumentError (invalid structure) and TypeError (wrong type)
-    #
     # @example Validate GGN data
     #   Sashite::Ggn.valid?(ggn_data) # => true
-    #   Sashite::Ggn.valid?("invalid") # => false (TypeError)
-    #   Sashite::Ggn.valid?(nil) # => false (TypeError)
+    #   Sashite::Ggn.valid?("invalid") # => false
+    #   Sashite::Ggn.valid?(nil) # => false
     def self.valid?(data)
-      parse(data)
+      validate!(data)
       true
-    rescue ::ArgumentError, ::TypeError
+    rescue ::ArgumentError
       false
     end
+
+    # Validate GGN data structure
+    #
+    # @param data [Object] Data to validate
+    # @raise [ArgumentError] If structure is invalid
+    # @return [void]
+    # @api private
+    def self.validate!(data)
+      raise ::ArgumentError, "GGN data must be a Hash" unless data.is_a?(::Hash)
+
+      data.each do |piece, sources|
+        validate_piece!(piece)
+        validate_sources!(sources, piece)
+      end
+    end
+    private_class_method :validate!
+
+    # Validate QPI piece identifier
+    #
+    # @param piece [String] Piece identifier to validate
+    # @raise [ArgumentError] If piece identifier is invalid
+    # @return [void]
+    # @api private
+    def self.validate_piece!(piece)
+      raise ::ArgumentError, "Invalid piece identifier: #{piece}" unless piece.is_a?(::String)
+      raise ::ArgumentError, "Invalid QPI format: #{piece}" unless Qpi.valid?(piece)
+    end
+    private_class_method :validate_piece!
+
+    # Validate sources hash structure
+    #
+    # @param sources [Hash] Sources hash to validate
+    # @param piece [String] Piece identifier (for error messages)
+    # @raise [ArgumentError] If sources structure is invalid
+    # @return [void]
+    # @api private
+    def self.validate_sources!(sources, piece)
+      raise ::ArgumentError, "Sources for #{piece} must be a Hash" unless sources.is_a?(::Hash)
+
+      sources.each do |source, destinations|
+        validate_location!(source, piece)
+        validate_destinations!(destinations, piece, source)
+      end
+    end
+    private_class_method :validate_sources!
+
+    # Validate destinations hash structure
+    #
+    # @param destinations [Hash] Destinations hash to validate
+    # @param piece [String] Piece identifier (for error messages)
+    # @param source [String] Source location (for error messages)
+    # @raise [ArgumentError] If destinations structure is invalid
+    # @return [void]
+    # @api private
+    def self.validate_destinations!(destinations, piece, source)
+      raise ::ArgumentError, "Destinations for #{piece} from #{source} must be a Hash" unless destinations.is_a?(::Hash)
+
+      destinations.each do |destination, possibilities|
+        validate_location!(destination, piece)
+        validate_hand_to_hand!(source, destination)
+        validate_possibilities!(possibilities, piece, source, destination)
+      end
+    end
+    private_class_method :validate_destinations!
+
+    # Validate that source and destination are not both HAND ("*")
+    #
+    # @param source [String] Source location
+    # @param destination [String] Destination location
+    # @raise [ArgumentError] If both source and destination are HAND
+    # @return [void]
+    # @api private
+    def self.validate_hand_to_hand!(source, destination)
+      return unless Hand.reserve?(source) && Hand.reserve?(destination)
+
+      raise ::ArgumentError, "Invalid HAND→HAND movement: source and destination cannot both be '*' (forbidden by GGN specification)"
+    end
+    private_class_method :validate_hand_to_hand!
+
+    # Validate possibilities array structure
+    #
+    # @param possibilities [Array] Possibilities array to validate
+    # @param piece [String] Piece identifier (for error messages)
+    # @param source [String] Source location (for error messages)
+    # @param destination [String] Destination location (for error messages)
+    # @raise [ArgumentError] If possibilities structure is invalid
+    # @return [void]
+    # @api private
+    def self.validate_possibilities!(possibilities, piece, source, destination)
+      unless possibilities.is_a?(::Array)
+        raise ::ArgumentError, "Possibilities for #{piece} #{source}→#{destination} must be an Array"
+      end
+
+      possibilities.each do |possibility|
+        validate_possibility!(possibility, piece, source, destination)
+      end
+    end
+    private_class_method :validate_possibilities!
+
+    # Validate individual possibility structure
+    #
+    # @param possibility [Hash] Possibility to validate
+    # @param piece [String] Piece identifier (for error messages)
+    # @param source [String] Source location (for error messages)
+    # @param destination [String] Destination location (for error messages)
+    # @raise [ArgumentError] If possibility structure is invalid
+    # @return [void]
+    # @api private
+    def self.validate_possibility!(possibility, piece, source, destination)
+      unless possibility.is_a?(::Hash)
+        raise ::ArgumentError, "Possibility for #{piece} #{source}→#{destination} must be a Hash"
+      end
+      raise ::ArgumentError, "Possibility must have 'must' field" unless possibility.key?("must")
+      raise ::ArgumentError, "Possibility must have 'deny' field" unless possibility.key?("deny")
+      raise ::ArgumentError, "Possibility must have 'diff' field" unless possibility.key?("diff")
+
+      validate_lcn_conditions!(possibility["must"], "must", piece, source, destination)
+      validate_lcn_conditions!(possibility["deny"], "deny", piece, source, destination)
+      validate_stn_transition!(possibility["diff"], piece, source, destination)
+    end
+    private_class_method :validate_possibility!
+
+    # Validate LCN conditions
+    #
+    # @param conditions [Hash] Conditions to validate
+    # @param field_name [String] Field name for error messages
+    # @param piece [String] Piece identifier (for error messages)
+    # @param source [String] Source location (for error messages)
+    # @param destination [String] Destination location (for error messages)
+    # @raise [ArgumentError] If conditions are invalid
+    # @return [void]
+    # @api private
+    def self.validate_lcn_conditions!(conditions, field_name, piece, source, destination)
+      Lcn.parse(conditions)
+    rescue ::ArgumentError => e
+      raise ::ArgumentError, "Invalid LCN format in '#{field_name}' for #{piece} #{source}→#{destination}: #{e.message}"
+    end
+    private_class_method :validate_lcn_conditions!
+
+    # Validate STN transition
+    #
+    # @param transition [Hash] Transition to validate
+    # @param piece [String] Piece identifier (for error messages)
+    # @param source [String] Source location (for error messages)
+    # @param destination [String] Destination location (for error messages)
+    # @raise [ArgumentError] If transition is invalid
+    # @return [void]
+    # @api private
+    def self.validate_stn_transition!(transition, piece, source, destination)
+      Stn.parse(transition)
+    rescue ::StandardError => e
+      raise ::ArgumentError, "Invalid STN format in 'diff' for #{piece} #{source}→#{destination}: #{e.message}"
+    end
+    private_class_method :validate_stn_transition!
+
+    # Validate location format
+    #
+    # @param location [String] Location to validate
+    # @param piece [String] Piece identifier (for error messages)
+    # @raise [ArgumentError] If location format is invalid
+    # @return [void]
+    # @api private
+    def self.validate_location!(location, piece)
+      raise ::ArgumentError, "Location for #{piece} must be a String" unless location.is_a?(::String)
+
+      valid = Cell.valid?(location) || Hand.reserve?(location)
+      raise ::ArgumentError, "Invalid location format: #{location}" unless valid
+    end
+    private_class_method :validate_location!
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sashite-ggn
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.1
 platform: ruby
 authors:
 - Cyril Kato
@@ -23,34 +23,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
-- !ruby/object:Gem::Dependency
-  name: sashite-epin
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.1'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.1'
-- !ruby/object:Gem::Dependency
-  name: sashite-feen
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.3'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.3'
 - !ruby/object:Gem::Dependency
   name: sashite-hand
   requirement: !ruby/object:Gem::Requirement
@@ -150,7 +122,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.7.1
 specification_version: 4
 summary: General Gameplay Notation (GGN) - movement possibilities for board games
 test_files: []