sashite-ggn 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6dab117559875291772b7e8f60077f670928755870b39badd3555f4d66fd8357
-  data.tar.gz: 2fe3fd39dbb288dc140b10c4c9fec523d2ce00a7d33d7802d8612b95e2268ed3
+  metadata.gz: 71b56f3fe3aa4fe158bc428cb92880751133bfc769ac9a300f78026e51c95ef6
+  data.tar.gz: 779187aa54e75e9ef0d679bc0617b4a6230052e5ab24018409932654cd351be7
 SHA512:
-  metadata.gz: 805c62503574bbc3b985cc21cb4dfe7a15e03198d97a5e7f0d91508111fd7290ed7382f93f2db6d653f07593f06a65c2640ac4e027127e0bdd964cdc61edab5c
-  data.tar.gz: fc0330900649313e22511f44d391d5a73befdabe4038aa4744de3f8af12684767c410bd6f8aa7e4a88f961cecc6d7be1223e00cfd9736396d92d7c781fa5abea
+  metadata.gz: 94c8dd3916c7032479547f949e75a6b1865f95a19d1baba421947931b7bb2dd700dc8672b0297734c677ae02152dfd7526eec1a6cfed549d6f484cc3d97dbba3
+  data.tar.gz: 818b73b8a42e82e968e02aac3b9e8cade1f46a59765e56d19f5f3e8fe68478395a8d3134a074e0037890a61eadbc39989a406e7ff86a580f8defda5abb0d1d0d

data/README.md

@@ -1,152 +1,500 @@
 # Ggn.rb
 
-A Ruby implementation of the General Gameplay Notation (GGN) specification for describing pseudo-legal moves in abstract strategy board games.
+[![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)
 
-[![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)
+> **GGN** (General Gameplay Notation) implementation for Ruby — a pure, functional library for evaluating **movement possibilities** in abstract strategy board games.
+
+---
 
 ## What is GGN?
 
-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 (General Gameplay Notation) is a rule-agnostic format for describing **pseudo-legal moves** in abstract strategy board games. GGN serves as a **movement possibility oracle**: given a movement context (piece and source location) plus a destination location, it determines if the movement is feasible under specified pre-conditions.
+
+This gem implements the [GGN Specification v1.0.0](https://sashite.dev/specs/ggn/1.0.0/), providing complete movement possibility evaluation with environmental constraint checking.
+
+### Core Philosophy
 
-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:
+GGN answers the fundamental question:
 
-- 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
+> **Can this piece, currently at this location, reach that location?**
 
-**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.
+It encodes:
+- **Which piece** (via QPI format)
+- **From where** (source location using CELL or HAND)
+- **To where** (destination location using CELL or HAND)
+- **Which environmental pre-conditions** must hold (`must`)
+- **Which environmental pre-conditions** must not hold (`deny`)
+- **What changes occur** if executed (`diff` in STN format)
+
+---
 
 ## Installation
 
 ```ruby
-gem 'sashite-ggn'
+# In your Gemfile
+gem "sashite-ggn"
 ```
 
-## Basic Usage
+Or install manually:
+
+```sh
+gem install sashite-ggn
+```
 
-### Loading GGN Data
+---
+
+## Dependencies
+
+GGN builds upon foundational Sashité specifications:
 
 ```ruby
-require "sashite-ggn"
+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
+gem "sashite-stn"   # State Transition Notation
+```
 
-# Load from file
-ruleset = Sashite::Ggn.load_file("chess_moves.json")
+---
 
-# Load from string
-json = '{"CHESS:P": {"e2": {"e4": [{"perform": {"e2": null, "e4": "CHESS:P"}}]}}}'
-ruleset = Sashite::Ggn.load_string(json)
+## Quick Start
+
+```ruby
+require "sashite/ggn"
+
+# Parse GGN data structure
+ggn_data = {
+  "C:P" => {
+    "e2" => {
+      "e4" => [
+        {
+          "must" => { "e3" => "empty", "e4" => "empty" },
+          "deny" => {},
+          "diff" => {
+            "board" => { "e2" => nil, "e4" => "C:P" },
+            "toggle" => true
+          }
+        }
+      ]
+    }
+  }
+}
+
+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)
+
+transitions.any? # => true
 ```
 
-### Evaluating Moves
+---
+
+## API Reference
+
+### Module Functions
+
+#### `Sashite::Ggn.parse(data) → Ruleset`
+
+Parses GGN data structure into an immutable Ruleset object.
 
 ```ruby
-# Query specific move
-engine = ruleset.select("CHESS:P").from("e2").to("e4")
+ruleset = Sashite::Ggn.parse(ggn_data)
+```
 
-# Define board state
-board_state = { "e2" => "CHESS:P", "e3" => nil, "e4" => nil }
+**Parameters:**
+- `data` (Hash): GGN data structure conforming to specification
 
-# Evaluate move
-transitions = engine.where(board_state, "CHESS")
-# => [#<Transition diff={"e2"=>nil, "e4"=>"CHESS:P"}>]
+**Returns:** `Ruleset` — Immutable ruleset object
+
+**Raises:** `ArgumentError` — If data structure is invalid
+
+---
+
+#### `Sashite::Ggn.valid?(data) → Boolean`
+
+Validates GGN data structure against specification.
+
+```ruby
+Sashite::Ggn.valid?(ggn_data) # => true
 ```
 
-### Generating All Moves
+**Parameters:**
+- `data` (Hash): Data structure to validate
+
+**Returns:** `Boolean` — True if valid, false otherwise
+
+---
+
+### `Sashite::Ggn::Ruleset` Class
+
+Immutable container for GGN movement rules.
+
+#### `#select(piece) → Source`
+
+Selects movement rules for a specific piece type.
 
 ```ruby
-# Get all pseudo-legal moves for current position
-all_moves = ruleset.pseudo_legal_transitions(board_state, "CHESS")
+source = ruleset.select("C:K")
+```
 
-# 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
+**Parameters:**
+- `piece` (String): QPI piece identifier
+
+**Returns:** `Source` — Source selector object
+
+**Raises:** `KeyError` — If piece not found in ruleset
+
+---
+
+#### `#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...>]], ...]
 ```
 
-## Move Variants
+**Parameters:**
+- `feen` (String): Position in FEEN format
+
+**Returns:** `Array<Array>` — Array of `[piece, source, destination, transitions]` tuples
+
+---
 
-GGN supports multiple outcomes for a single move (e.g., promotion choices):
+#### `#piece?(piece) → Boolean`
+
+Checks if ruleset contains movement rules for specified piece.
 
 ```ruby
-# Chess pawn promotion
-engine = ruleset.select("CHESS:P").from("e7").to("e8")
-transitions = engine.where({"e7" => "CHESS:P", "e8" => nil}, "CHESS")
+ruleset.piece?("C:K") # => true
+```
 
-transitions.each do |transition|
-  promoted_piece = transition.diff["e8"]
-  puts "Promote to #{promoted_piece}"
-end
-# Output: CHESS:Q, CHESS:R, CHESS:B, CHESS:N
+**Parameters:**
+- `piece` (String): QPI piece identifier
+
+**Returns:** `Boolean`
+
+---
+
+#### `#pieces → Array<String>`
+
+Returns all piece identifiers in ruleset.
+
+```ruby
+ruleset.pieces # => ["C:K", "C:Q", "C:P", ...]
 ```
 
-## Complex Moves
+**Returns:** `Array<String>` — QPI piece identifiers
+
+---
+
+#### `#to_h → Hash`
 
-GGN can represent multi-square moves like castling:
+Converts ruleset to hash representation.
 
 ```ruby
-# 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"
-}
+ruleset.to_h # => { "C:K" => { "e1" => { "e2" => [...] } } }
+```
+
+**Returns:** `Hash` — GGN data structure
+
+---
+
+### `Sashite::Ggn::Ruleset::Source` Class
+
+Represents movement possibilities for a piece type.
+
+#### `#from(source) → Destination`
+
+Specifies the source location for the piece.
+
+```ruby
+destination = source.from("e1")
+```
+
+**Parameters:**
+- `source` (String): Source location (CELL coordinate or HAND "*")
+
+**Returns:** `Destination` — Destination selector object
+
+**Raises:** `KeyError` — If source not found for this piece
+
+---
+
+#### `#sources → Array<String>`
+
+Returns all valid source locations for this piece.
+
+```ruby
+source.sources # => ["e1", "d1", "*"]
+```
+
+**Returns:** `Array<String>` — Source locations
+
+---
+
+#### `#source?(location) → Boolean`
+
+Checks if location is a valid source for this piece.
+
+```ruby
+source.source?("e1") # => true
+```
 
-transitions = engine.where(board_state, "CHESS")
-# => [#<Transition diff={"e1"=>nil, "f1"=>"CHESS:R", "g1"=>"CHESS:K", "h1"=>nil}>]
+**Parameters:**
+- `location` (String): Source location
+
+**Returns:** `Boolean`
+
+---
+
+### `Sashite::Ggn::Ruleset::Source::Destination` Class
+
+Represents movement possibilities from a specific source.
+
+#### `#to(destination) → Engine`
+
+Specifies the destination location.
+
+```ruby
+engine = destination.to("e2")
+```
+
+**Parameters:**
+- `destination` (String): Destination location (CELL coordinate or HAND "*")
+
+**Returns:** `Engine` — Movement evaluation engine
+
+**Raises:** `KeyError` — If destination not found from this source
+
+---
+
+#### `#destinations → Array<String>`
+
+Returns all valid destinations from this source.
+
+```ruby
+destination.destinations # => ["d1", "d2", "e2", "f2", "f1"]
+```
+
+**Returns:** `Array<String>` — Destination locations
+
+---
+
+#### `#destination?(location) → Boolean`
+
+Checks if location is a valid destination from this source.
+
+```ruby
+destination.destination?("e2") # => true
+```
+
+**Parameters:**
+- `location` (String): Destination location
+
+**Returns:** `Boolean`
+
+---
+
+### `Sashite::Ggn::Ruleset::Source::Destination::Engine` Class
+
+Evaluates movement possibility under given position conditions.
+
+#### `#where(feen) → Array<Transition>`
+
+Evaluates movement against position and returns valid transitions.
+
+```ruby
+transitions = engine.where(feen)
+```
+
+**Parameters:**
+- `feen` (String): Position in FEEN format
+
+**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" => {...} }]
 ```
 
-## Conditional Moves
+**Returns:** `Array<Hash>` — Movement possibility specifications
+
+---
+
+## GGN Format
 
-GGN supports moves with complex requirements and prevent conditions:
+### Structure
 
 ```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
+{
+  "<qpi-piece>" => {
+    "<source-location>" => {
+      "<destination-location>" => [
+        {
+          "must" => { /* LCN format */ },
+          "deny" => { /* LCN format */ },
+          "diff" => { /* STN format */ }
+        }
+      ]
+    }
+  }
 }
+```
+
+### Field Specifications
+
+| Field | Type | Description |
+|-------|------|-------------|
+| **Piece** | String (QPI) | Piece identifier (e.g., `"C:K"`, `"s:+p"`) |
+| **Source** | String (CELL/HAND) | Origin location (e.g., `"e2"`, `"*"`) |
+| **Destination** | String (CELL/HAND) | Target location (e.g., `"e4"`, `"*"`) |
+| **must** | Hash (LCN) | Pre-conditions that must be satisfied |
+| **deny** | Hash (LCN) | Pre-conditions that must not be satisfied |
+| **diff** | Hash (STN) | State transition specification |
+
+---
+
+## Usage Examples
+
+### Method Chaining
+
+```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"
 
-transitions = engine.where(board_state, "CHESS")
-# => [#<Transition diff={"d5"=>nil, "e5"=>nil, "e6"=>"CHESS:P"}>]
+transitions = ruleset
+  .select("C:P")
+  .from("e2")
+  .to("e4")
+  .where(feen)
+
+transitions.size # => 1
+transitions.first.board_changes # => { "e2" => nil, "e4" => "C:P" }
 ```
 
-## Validation
+### Generate All Pseudo-Legal Moves
 
 ```ruby
-# Validate GGN data
-Sashite::Ggn.validate!(data)  # Raises exception on failure
-Sashite::Ggn.valid?(data)     # Returns boolean
+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"
+
+all_moves = ruleset.pseudo_legal_transitions(feen)
+
+all_moves.each do |piece, source, destination, transitions|
+  puts "#{piece}: #{source} → #{destination} (#{transitions.size} variants)"
+end
 ```
 
-## API Reference
+### Existence Checks
 
-### Core Classes
+```ruby
+# Check if piece exists in ruleset
+ruleset.piece?("C:K") # => true
+
+# Check valid sources
+source = ruleset.select("C:K")
+source.source?("e1") # => true
 
-- `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
+# Check valid destinations
+destination = source.from("e1")
+destination.destination?("e2") # => true
+```
 
-### Key Methods
+### Introspection
+
+```ruby
+# List all pieces
+ruleset.pieces # => ["C:K", "C:Q", "C:R", ...]
 
-- `#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
+# List sources for a piece
+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" => {...} }]
+```
+
+---
+
+## Design Properties
+
+- **Functional**: Pure functions with no side effects
+- **Immutable**: All data structures frozen and unchangeable
+- **Composable**: Clean method chaining for natural query flow
+- **Type-safe**: Strict validation of all inputs
+- **Delegative**: Leverages CELL, FEEN, HAND, LCN, QPI, STN specifications
+- **Spec-compliant**: Strictly follows GGN v1.0.0 specification
+
+---
+
+## Error Handling
+
+```ruby
+# Handle missing piece
+begin
+  source = ruleset.select("INVALID:X")
+rescue KeyError => e
+  puts "Piece not found: #{e.message}"
+end
+
+# Handle missing source
+begin
+  destination = source.from("z9")
+rescue KeyError => e
+  puts "Source not found: #{e.message}"
+end
+
+# Handle missing destination
+begin
+  engine = destination.to("z9")
+rescue KeyError => e
+  puts "Destination not found: #{e.message}"
+end
+
+# Safe validation before parsing
+if Sashite::Ggn.valid?(data)
+  ruleset = Sashite::Ggn.parse(data)
+else
+  puts "Invalid GGN structure"
+end
+```
+
+---
 
 ## Related Specifications
 
-GGN works alongside other Sashité specifications:
+- [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
+- [STN v1.0.0](https://sashite.dev/specs/stn/1.0.0/) — State transitions
 
-- [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
 
-The [gem](https://rubygems.org/gems/sashite-ggn) is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+Available as open source under the [MIT License](https://opensource.org/licenses/MIT).
+
+---
 
-## About Sashité
+## About
 
-This project is maintained by [Sashité](https://sashite.com/) — promoting chess variants and sharing the beauty of Chinese, Japanese, and Western chess cultures.
+Maintained by [Sashité](https://sashite.com/) — promoting chess variants and sharing the beauty of board game cultures.