sashite-ggn 0.3.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3841392373c865dd1e96e3cd8321cb8720767585d815fc16449f05a00c8d0900
-  data.tar.gz: a00ebca510e8af7ff2e77ea8056009ca2198a43d79885a61fd8ea682f6c9aaf3
+  metadata.gz: 6dab117559875291772b7e8f60077f670928755870b39badd3555f4d66fd8357
+  data.tar.gz: 2fe3fd39dbb288dc140b10c4c9fec523d2ce00a7d33d7802d8612b95e2268ed3
 SHA512:
-  metadata.gz: 9cc52a786d043b1e2ed437d58f9c939268d23f97df82211732dacf955964bbc27fbc24a3ac280c5cb63a84e6aeaf7fb22aa88e659832020802ac1e78e949f6b5
-  data.tar.gz: 35a6f1b1d9d0f5878ebef7c443f675a0c15027d0895ca96c92c69c1f9a6864c152b7c58fb25e57cbb5ff50223a007003eb994ddb265d1e0e67707fa5b692a6b3
+  metadata.gz: 805c62503574bbc3b985cc21cb4dfe7a15e03198d97a5e7f0d91508111fd7290ed7382f93f2db6d653f07593f06a65c2640ac4e027127e0bdd964cdc61edab5c
+  data.tar.gz: fc0330900649313e22511f44d391d5a73befdabe4038aa4744de3f8af12684767c410bd6f8aa7e4a88f961cecc6d7be1223e00cfd9736396d92d7c781fa5abea

data/README.md

@@ -1,413 +1,147 @@
 # Ggn.rb
 
-[![Version](https://img.shields.io/github/v/tag/sashite/ggn.rb?label=Version&logo=github)](https://github.com/sashite/ggn.rb/tags)
-[![Yard documentation](https://img.shields.io/badge/Yard-documentation-blue.svg?logo=github)](https://rubydoc.info/github/sashite/ggn.rb/main)
-![Ruby](https://github.com/sashite/ggn.rb/actions/workflows/main.yml/badge.svg?branch=main)
-[![License](https://img.shields.io/github/license/sashite/ggn.rb?label=License&logo=github)](https://github.com/sashite/ggn.rb/raw/main/LICENSE.md)
+A Ruby implementation of the General Gameplay Notation (GGN) specification for describing pseudo-legal moves in abstract strategy board games.
 
-> **GGN** (General Gameplay Notation) support for the Ruby language.
+[![Gem Version](https://badge.fury.io/rb/sashite-ggn.svg)](https://badge.fury.io/rb/sashite-ggn)
+[![Ruby](https://github.com/sashite/ggn.rb/workflows/Ruby/badge.svg)](https://github.com/sashite/ggn.rb/actions)
 
 ## What is GGN?
 
-GGN (General Gameplay Notation) is a rule-agnostic, JSON-based format for describing **pseudo-legal moves** in abstract strategy board games. Unlike move notations that express *what* a move does, GGN expresses *whether* that move is **possible** under basic movement constraints.
+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 is deliberately silent about higher-level, game-specific legality questions (e.g., check, ko, repetition, castling paths). This neutrality makes the format universal: any engine can pre-compute and share a library of pseudo-legal moves for any mix of games.
+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:
 
-This gem implements the [GGN Specification v1.0.0](https://sashite.dev/documents/ggn/1.0.0/), providing a Ruby interface 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
 
-- Loading and validating GGN JSON documents
-- Querying pseudo-legal moves for specific pieces and positions
-- Evaluating move validity under current board conditions
-- Processing complex move conditions including captures, drops, and promotions
+**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
-# In your Gemfile
-gem "sashite-ggn"
-```
-
-Or install manually:
-
-```sh
-gem install sashite-ggn
-```
-
-## GGN Format
-
-A single GGN **entry** answers the question:
-
-> Can this piece, currently on this square, reach that square?
-
-It encodes:
-
-1. **Which piece** (via GAN identifier)
-2. **From where** (source square label, or "`*`" for off-board)
-3. **To where** (destination square label)
-4. **Which pre-conditions** must hold (`require`)
-5. **Which pre-conditions** must not hold (`prevent`)
-6. **Which post-conditions** result (`perform`, plus optional `gain` or `drop`)
-
-### JSON Structure
-
-```json
-{
-  "<Source piece GAN>": {
-    "<Source square>": {
-      "<Destination square>": [
-        {
-          "require":  { "<square>": "<required state>", … },
-          "prevent":  { "<square>": "<forbidden state>", … },
-          "perform":  { "<square>": "<new state | null>", … },
-          "gain":     "<piece GAN>" | null,
-          "drop":     "<piece GAN>" | null
-        }
-      ]
-    }
-  }
-}
+gem 'sashite-ggn'
 ```
 
 ## Basic Usage
 
 ### Loading GGN Data
 
-Load GGN data from various sources:
-
 ```ruby
 require "sashite-ggn"
 
-# From file
-piece_data = Sashite::Ggn.load_file("chess_moves.json")
-
-# From JSON string
-json_string = '{"CHESS:P": {"e2": {"e4": [{"require": {"e3": "empty", "e4": "empty"}, "perform": {"e2": null, "e4": "CHESS:P"}}]}}}'
-piece_data = Sashite::Ggn.load_string(json_string)
+# Load from file
+ruleset = Sashite::Ggn.load_file("chess_moves.json")
 
-# From Hash
-ggn_hash = { "CHESS:P" => { "e2" => { "e4" => [{ "require" => { "e3" => "empty", "e4" => "empty" }, "perform" => { "e2" => nil, "e4" => "CHESS:P" } }] } } }
-piece_data = Sashite::Ggn.load_hash(ggn_hash)
+# Load from string
+json = '{"CHESS:P": {"e2": {"e4": [{"perform": {"e2": null, "e4": "CHESS:P"}}]}}}'
+ruleset = Sashite::Ggn.load_string(json)
 ```
 
-### Querying Moves
-
-Navigate through the GGN structure to find specific moves:
+### Evaluating Moves
 
 ```ruby
-require "sashite-ggn"
+# Query specific move
+engine = ruleset.select("CHESS:P").from("e2").to("e4")
 
-piece_data = Sashite::Ggn.load_file("chess_moves.json")
+# Define board state
+board_state = { "e2" => "CHESS:P", "e3" => nil, "e4" => nil }
 
-# Select a piece type
-source = piece_data.select("CHESS:P")
-
-# Get destinations from a specific source square
-destinations = source.from("e2")
-
-# Get the engine for a specific target square
-engine = destinations.to("e4")
+# Evaluate move
+transitions = engine.where(board_state, "CHESS")
+# => [#<Transition diff={"e2"=>nil, "e4"=>"CHESS:P"}>]
 ```
 
-### Evaluating Move Validity
-
-Check if a move is valid under current board conditions:
+### Generating All Moves
 
 ```ruby
-require "sashite-ggn"
-
-# Load piece data and get the movement engine
-piece_data = Sashite::Ggn.load_file("chess_moves.json")
-engine = piece_data.select("CHESS:P").from("e2").to("e4")
+# Get all pseudo-legal moves for current position
+all_moves = ruleset.pseudo_legal_transitions(board_state, "CHESS")
 
-# Define current board state
-board_state = {
-  "e2" => "CHESS:P",  # White pawn on e2
-  "e3" => nil,        # Empty square
-  "e4" => nil         # Empty square
-}
-
-# Evaluate the move
-result = engine.where(board_state, {}, "CHESS")
-
-if result
-  puts "Move is valid!"
-  puts "Board changes: #{result.diff}"
-  # => { "e2" => nil, "e4" => "CHESS:P" }
-  puts "Piece gained: #{result.gain}"  # => nil (no capture)
-  puts "Piece dropped: #{result.drop}" # => nil (not a drop move)
-else
-  puts "Move is not valid under current conditions"
+# Each move is represented as [actor, origin, target, transitions]
+all_moves.each do |actor, origin, target, transitions|
+  puts "#{actor}: #{origin} → #{target} (#{transitions.size} variants)"
 end
 ```
 
-### Handling Captures
+## Move Variants
 
-Process moves that capture enemy pieces:
+GGN supports multiple outcomes for a single move (e.g., promotion choices):
 
 ```ruby
-require "sashite-ggn"
+# Chess pawn promotion
+engine = ruleset.select("CHESS:P").from("e7").to("e8")
+transitions = engine.where({"e7" => "CHESS:P", "e8" => nil}, "CHESS")
 
-# Load piece data for a capture move
-piece_data = Sashite::Ggn.load_file("chess_moves.json")
-engine = piece_data.select("CHESS:P").from("e5").to("d6")
-
-# Board state with enemy piece to capture
-board_state = {
-  "e5" => "CHESS:P",  # Our pawn
-  "d6" => "chess:p"   # Enemy pawn (lowercase = opponent)
-}
-
-result = engine.where(board_state, {}, "CHESS")
-
-if result
-  puts "Capture is valid!"
-  puts "Board changes: #{result.diff}"
-  # => { "e5" => nil, "d6" => "CHESS:P" }
-  puts "Captured piece: #{result.gain}"  # => "CHESS:P" (gained in hand)
+transitions.each do |transition|
+  promoted_piece = transition.diff["e8"]
+  puts "Promote to #{promoted_piece}"
 end
+# Output: CHESS:Q, CHESS:R, CHESS:B, CHESS:N
 ```
 
-### Piece Drops (Shogi-style)
+## Complex Moves
 
-Handle dropping pieces from hand onto the board:
+GGN can represent multi-square moves like castling:
 
 ```ruby
-require "sashite-ggn"
-
-# Load Shogi piece data
-piece_data = Sashite::Ggn.load_file("shogi_moves.json")
-engine = piece_data.select("SHOGI:P").from("*").to("5e")
-
-# Player has captured pawns available
-captures = { "SHOGI:P" => 2 }
-
-# Current board state (5th file is clear of unpromoted pawns)
+# Castling (king and rook move simultaneously)
+engine = ruleset.select("CHESS:K").from("e1").to("g1")
 board_state = {
-  "5e" => nil,  # Target square is empty
-  "5a" => nil, "5b" => nil, "5c" => nil, "5d" => nil,
-  "5f" => nil, "5g" => nil, "5h" => nil, "5i" => nil
+  "e1" => "CHESS:K", "f1" => nil, "g1" => nil, "h1" => "CHESS:R"
 }
 
-result = engine.where(board_state, captures, "SHOGI")
-
-if result
-  puts "Pawn drop is valid!"
-  puts "Board changes: #{result.diff}"  # => { "5e" => "SHOGI:P" }
-  puts "Piece dropped from hand: #{result.drop}"  # => "SHOGI:P"
-end
+transitions = engine.where(board_state, "CHESS")
+# => [#<Transition diff={"e1"=>nil, "f1"=>"CHESS:R", "g1"=>"CHESS:K", "h1"=>nil}>]
 ```
 
-## Validation
+## Conditional Moves
 
-### Schema Validation
-
-Validate GGN data against the official JSON Schema:
+GGN supports moves with complex requirements and prevent conditions:
 
 ```ruby
-require "sashite-ggn"
-
-# Validate during loading (default behavior)
-begin
-  piece_data = Sashite::Ggn.load_file("moves.json")
-  puts "GGN data is valid!"
-rescue Sashite::Ggn::ValidationError => e
-  puts "Validation failed: #{e.message}"
-end
-
-# Skip validation for performance (large files)
-piece_data = Sashite::Ggn.load_file("large_moves.json", validate: false)
-
-# Validate manually
-begin
-  Sashite::Ggn.validate!(my_data)
-  puts "Data is valid"
-rescue Sashite::Ggn::ValidationError => e
-  puts "Invalid: #{e.message}"
-end
-
-# Check validity without exceptions
-if Sashite::Ggn.valid?(my_data)
-  puts "Data is valid"
-else
-  errors = Sashite::Ggn.validation_errors(my_data)
-  puts "Validation errors: #{errors.join(', ')}"
-end
-```
-
-## Occupation States
-
-GGN recognizes several occupation states for move conditions:
-
-| State            | Meaning                                                                      |
-| ---------------- | ---------------------------------------------------------------------------- |
-| `"empty"`        | Square must be empty                                                         |
-| `"enemy"`        | Square must contain a standard opposing piece                                |
-| *GAN identifier* | Square must contain **exactly** the specified piece                          |
-
-### Implicit States
-
-Through the `prevent` field, additional states can be expressed:
-
-| Implicit State   | Expression                   | Meaning                                                  |
-| ---------------- | ---------------------------- | -------------------------------------------------------- |
-| `"occupied"`     | `"prevent": { "a1": "empty" }` | Square must be occupied by any piece                     |
-| `"ally"`         | `"prevent": { "a1": "enemy" }` | Square must contain a friendly piece                     |
-
-## Examples
-
-### Simple Move
-
-A piece moving from one square to another without conditions:
-
-```json
-{
-  "CHESS:K": {
-    "e1": {
-      "e2": [
-        {
-          "perform": { "e1": null, "e2": "CHESS:K" }
-        }
-      ]
-    }
-  }
-}
-```
-
-### Sliding Move
-
-A piece that slides along empty squares:
-
-```json
-{
-  "CHESS:R": {
-    "a1": {
-      "a3": [
-        {
-          "require": { "a2": "empty", "a3": "empty" },
-          "perform": { "a1": null, "a3": "CHESS:R" }
-        }
-      ]
-    }
-  }
+# 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
 }
-```
 
-### Capture with Gain
-
-A piece capturing an enemy and gaining it in hand:
-
-```json
-{
-  "SHOGI:P": {
-    "5f": {
-      "5e": [
-        {
-          "require": { "5e": "enemy" },
-          "perform": { "5f": null, "5e": "SHOGI:P" },
-          "gain": "SHOGI:P"
-        }
-      ]
-    }
-  }
-}
+transitions = engine.where(board_state, "CHESS")
+# => [#<Transition diff={"d5"=>nil, "e5"=>nil, "e6"=>"CHESS:P"}>]
 ```
 
-### Piece Drop
-
-Dropping a piece from hand onto the board:
-
-```json
-{
-  "SHOGI:P": {
-    "*": {
-      "5e": [
-        {
-          "require": { "5e": "empty" },
-          "prevent": {
-            "5a": "SHOGI:P", "5b": "SHOGI:P", "5c": "SHOGI:P",
-            "5d": "SHOGI:P", "5f": "SHOGI:P", "5g": "SHOGI:P",
-            "5h": "SHOGI:P", "5i": "SHOGI:P"
-          },
-          "perform": { "5e": "SHOGI:P" },
-          "drop": "SHOGI:P"
-        }
-      ]
-    }
-  }
-}
-```
+## Validation
 
-### Promotion
-
-A piece moving and changing to a different piece type:
-
-```json
-{
-  "CHESS:P": {
-    "g7": {
-      "g8": [
-        {
-          "require": { "g8": "empty" },
-          "perform": { "g7": null, "g8": "CHESS:Q" }
-        }
-      ]
-    }
-  }
-}
+```ruby
+# Validate GGN data
+Sashite::Ggn.validate!(data)  # Raises exception on failure
+Sashite::Ggn.valid?(data)     # Returns boolean
 ```
 
-## Error Handling
-
-The library provides comprehensive error handling:
-
-```ruby
-require "sashite-ggn"
+## API Reference
 
-begin
-  # Various operations that might fail
-  piece_data = Sashite::Ggn.load_file("nonexistent.json")
-  source = piece_data.select("INVALID:PIECE")
-  destinations = source.from("invalid_square")
-  engine = destinations.to("another_invalid")
-  result = engine.where({}, {}, "")
-rescue Sashite::Ggn::ValidationError => e
-  puts "GGN validation error: #{e.message}"
-rescue KeyError => e
-  puts "Key not found: #{e.message}"
-rescue ArgumentError => e
-  puts "Invalid argument: #{e.message}"
-end
-```
+### Core Classes
 
-## Performance Considerations
+- `Sashite::Ggn::Ruleset` - Main entry point for querying moves
+- `Sashite::Ggn::Ruleset::Source` - Piece type with source positions
+- `Sashite::Ggn::Ruleset::Source::Destination` - Available destinations
+- `Sashite::Ggn::Ruleset::Source::Destination::Engine` - Move evaluator
+- `Sashite::Ggn::Ruleset::Source::Destination::Engine::Transition` - Move result
 
-For large GGN files or high-frequency operations:
+### Key Methods
 
-```ruby
-# Skip validation for better performance
-piece_data = Sashite::Ggn.load_file("large_dataset.json", validate: false)
-
-# Cache frequently used engines
-@engines = {}
-def get_engine(piece, from, to)
-  key = "#{piece}:#{from}:#{to}"
-  @engines[key] ||= piece_data.select(piece).from(from).to(to)
-end
-```
+- `#pseudo_legal_transitions(board_state, active_game)` - Generate all moves
+- `#select(actor).from(origin).to(target)` - Query specific move
+- `#where(board_state, active_game)` - Evaluate move validity
 
 ## Related Specifications
 
 GGN works alongside other Sashité specifications:
 
-- **[GAN](https://sashite.dev/documents/gan/1.0.0/)** (General Actor Notation): Unique piece identifiers
-- **[FEEN](https://sashite.dev/documents/feen/1.0.0/)** (Forsyth-Edwards Enhanced Notation): Board position representation
-- **[PMN](https://sashite.dev/documents/pmn/1.0.0/)** (Portable Move Notation): Move sequence representation
-
-## Documentation
-
-- [Official GGN Specification](https://sashite.dev/documents/ggn/1.0.0/)
-- [JSON Schema](https://sashite.dev/schemas/ggn/1.0.0/schema.json)
-- [API Documentation](https://rubydoc.info/github/sashite/ggn.rb/main)
+- [GAN](https://sashite.dev/documents/gan/1.0.0/) - General Actor Notation for piece identifiers
+- [FEEN](https://sashite.dev/documents/feen/1.0.0/) - Board position representation
+- [PMN](https://sashite.dev/documents/pmn/1.0.0/) - Move sequence representation
 
 ## License