sashite-feen 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5bcbcddcc2de55695f9a203e30fa5d3d236deaf7c0e3975011ae1a47f389cd7c
-  data.tar.gz: 98b184086642d30761cf4646dbeac1ca0a88860c11d18a15866f01e7f0b0e040
+  metadata.gz: 98fd7fceb1edd4b6479a217c0932443c76335b4d41238b2ee0d3f2e3fc2dd397
+  data.tar.gz: 6f31b473124e985baab36d30bf84d3c7cf05d129d66bbfe16b4b60068a44c545
 SHA512:
-  metadata.gz: cb41ec980de1a7ae5237da821f0a3be0cabe50768cb0dceec8988465336512a0705aec6f5aa9acfe1b0cf43770996581355029be8623a19d8a44dc737c628d83
-  data.tar.gz: 95507ce051c09837ca92da2b9447b2ef3f3c9a34fdc4e412cce0ed8e32595acf91acdbae37d2ed313315db9c0e29069edae0ec1c71770b3d1f853f20896a3c0c
+  metadata.gz: 6f5c62abd73d7628ded615367f74644933615488fdffdceecb85f06f2c371fe96ad269b3c4722343fd59d6145c5650492f8e1b9ec9f660c1ed57be83877b7eaa
+  data.tar.gz: 19e3e8f686a1d114dc9da267209716b3c28372585c90d061c604ac6d13692b67cb15abbdf967ff62f125518c26a63506e73525b2115421a659c18094c19e270e

data/README.md

@@ -1,236 +1,117 @@
-Here you go — a lean, easy-to-read README that reflects the new “API / parser / dumper” design without drowning the reader in details.
-
----
-
 # Feen.rb
 
-> **FEEN** — Forsyth–Edwards Enhanced Notation for rule-agnostic board positions (Chess, Shōgi-like, Xiangqi-like, variants).
-
-Purely functional, immutable Ruby implementation built on top of **EPIN** (piece identifiers) and **SIN** (style identifiers).
+[![Version](https://img.shields.io/github/v/tag/sashite/feen.rb?label=Version&logo=github)](https://github.com/sashite/feen.rb/tags)
+[![Yard documentation](https://img.shields.io/badge/Yard-documentation-blue.svg?logo=github)](https://rubydoc.info/github/sashite/feen.rb/main)
+![Ruby](https://github.com/sashite/feen.rb/actions/workflows/main.yml/badge.svg?branch=main)
+[![License](https://img.shields.io/github/license/sashite/feen.rb?label=License&logo=github)](https://github.com/sashite/feen.rb/raw/main/LICENSE.md)
 
----
+> **FEEN** (Forsyth–Edwards Enhanced Notation) implementation for the Ruby language.
 
-## Why FEEN?
+## What is FEEN?
 
-* **Rule-agnostic**: expresses a board **position** without baking in game rules.
-* **Portable & canonical**: a single, deterministic string per position.
-* **Composable**: works nicely alongside other Sashité specs (e.g., STN for transitions).
+FEEN (Forsyth–Edwards Enhanced Notation) is a universal, rule-agnostic notation for representing board game positions. It extends traditional FEN to support multiple game systems, cross-style games, multi-dimensional boards, and captured pieces.
 
-FEEN strings have **three space-separated fields**:
-
-```
-<piece_placement> <pieces_in_hand> <style_turn>
-```
-
----
+This gem implements the [FEEN Specification v1.0.0](https://sashite.dev/specs/feen/1.0.0/) as a pure functional library with immutable data structures.
 
 ## Installation
 
-Add to your `Gemfile`:
-
 ```ruby
 gem "sashite-feen"
-````
-
-Then:
-
-```sh
-bundle install
-```
-
-This gem depends on:
-
-```ruby
-gem "sashite-epin"
-gem "sashite-sin"
 ```
 
-Bundler will install them automatically when you use `sashite-feen`.
+## API
 
----
-
-## Quick start
+The library provides two methods for converting between FEEN strings and position objects:
 
 ```ruby
 require "sashite/feen"
 
-# Parse
-pos = Sashite::Feen.parse("<placement> <hands> <style1>/<style2>")
-
-# Validate
-Sashite::Feen.valid?("<your FEEN>") # => true/false
-
-# Normalize (parse → canonical dump)
-Sashite::Feen.normalize("<your FEEN>") # => canonical FEEN string
+# Parse a FEEN string into a position object
+position = Sashite::Feen.parse("+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")
 
-# Build from fields (strings)
-pos = Sashite::Feen.build(
-  piece_placement: "<placement>",
-  pieces_in_hand:  "<bagFirst>/<bagSecond>", # empty bags allowed: "/"
-  style_turn:      "<activeSIN>/<inactiveSIN>"
-)
-
-# Dump a Position (canonical)
-Sashite::Feen.dump(pos) # => "<placement> <hands> <style1>/<style2>"
+# Dump a position object into a canonical FEEN string
+feen_string = Sashite::Feen.dump(position)
 ```
 
-> **Tip:** FEEN itself does not do JSON; keep it minimal and functional. Serialize externally if needed.
+### Methods
 
----
+#### `Sashite::Feen.parse(string)`
 
-## Public API
+Parses a FEEN string and returns an immutable `Position` object.
 
-```ruby
-Sashite::Feen.parse(str)      # => Position (or raises Sashite::Feen::Error)
-Sashite::Feen.valid?(str)     # => Boolean
-Sashite::Feen.dump(position)  # => String (canonical)
-Sashite::Feen.normalize(str)  # => String (dump(parse(str)))
-Sashite::Feen.build(
-  piece_placement:, pieces_in_hand:, style_turn:
-)                             # => Position
-```
+- **Input**: FEEN string with three space-separated fields
+- **Returns**: `Sashite::Feen::Position` instance
+- **Raises**: `Sashite::Feen::Error` subclasses on invalid input
 
-Position value-objects are immutable:
+#### `Sashite::Feen.dump(position)`
 
-```ruby
-pos.placement  # => Sashite::Feen::Placement
-pos.hands      # => Sashite::Feen::Hands
-pos.styles     # => Sashite::Feen::Styles
-pos.to_s       # => canonical FEEN string (same as dump(pos))
-```
+Converts a position object into its canonical FEEN string representation.
 
----
+- **Input**: `Sashite::Feen::Position` instance
+- **Returns**: Canonical FEEN string
+- **Guarantees**: Deterministic output (same position always produces same string)
 
-## Canonicalization (short rules)
+### Position Object
 
-* **Piece placement (field 1)**
+The `Position` object returned by `parse` is immutable and provides read-only access to the three FEEN components:
 
-  * Consecutive empties compress to digits `1..9`; runs `>9` are split into `"9"` + remainder.
-  * Digit `0` in empties is invalid.
-  * EPIN tokens are validated via `sashite-epin` and re-emitted canonically.
-
-* **Pieces in hand (field 2)**
-
-  * Two concatenated bags separated by `/` (either side may be empty).
-  * Counts are aggregated; `1` is omitted in output.
-  * Deterministic sort per EPIN: quantity ↓, letter ↑ (case-insensitive), uppercase before lowercase, prefix `-` < `+` < none, suffix none < `'`.
-
-* **Style-turn (field 3)**
-
-  * Exactly two SIN tokens separated by `/`.
-  * Exactly **one uppercase** style (first player) and **one lowercase** style (second).
-  * The **first token is the active** player’s style.
-
----
-
-## Design overview
-
-The gem is small, layered, and testable:
+```ruby
+position.placement  # => Placement object (board arrangement)
+position.hands      # => Hands object (pieces in hand)
+position.styles     # => Styles object (style-turn information)
+position.to_s       # => Canonical FEEN string (equivalent to dump)
+```
 
-* **API**: `Sashite::Feen` (parse / valid? / dump / normalize / build)
-* **Value objects**: `Position`, `Placement`, `Hands`, `Styles` (immutable, canonical)
-* **Parser**: `Feen::Parser` orchestrates field parsers (`Parser::PiecePlacement`, `Parser::PiecesInHand`, `Parser::StyleTurn`)
-* **Dumper**: `Feen::Dumper` orchestrates field dumpers (`Dumper::PiecePlacement`, `Dumper::PiecesInHand`, `Dumper::StyleTurn`)
-* **Ordering**: `Feen::Ordering` — single comparator used by the hands dumper
-* **Errors**: `Feen::Error` (see below)
+## Format
 
-### Project layout
+A FEEN string consists of three space-separated fields:
 
 ```
-lib/
-├─ sashite-feen.rb
-└─ sashite/
-   ├─ feen.rb                 # Public API
-   └─ feen/
-      ├─ error.rb
-      ├─ position.rb
-      ├─ placement.rb
-      ├─ hands.rb
-      ├─ styles.rb
-      ├─ ordering.rb
-      ├─ parser.rb
-      ├─ parser/
-      │  ├─ piece_placement.rb
-      │  ├─ pieces_in_hand.rb
-      │  └─ style_turn.rb
-      ├─ dumper.rb
-      └─ dumper/
-         ├─ piece_placement.rb
-         ├─ pieces_in_hand.rb
-         └─ style_turn.rb
+<piece-placement> <pieces-in-hand> <style-turn>
 ```
 
-> Version is defined outside of `lib/sashite/feen/version.rb` (e.g., `VERSION.semver`).
-
----
-
-## Errors
+1. **Piece placement**: Board configuration using EPIN notation
+2. **Pieces in hand**: Captured pieces held by each player
+3. **Style-turn**: Game styles and active player
 
-Rescue at the granularity you need:
+For complete format details, see the [FEEN Specification](https://sashite.dev/specs/feen/1.0.0/).
 
-* `Sashite::Feen::Error::Syntax` – tokenization/field arity
-* `Sashite::Feen::Error::Piece`  – EPIN validation failures
-* `Sashite::Feen::Error::Style`  – SIN validation/case issues
-* `Sashite::Feen::Error::Count`  – invalid counts in hands
-* `Sashite::Feen::Error::Bounds` – internal dimension constraints (when relevant)
-* `Sashite::Feen::Error::Validation` – generic structural/semantic errors
+## Error Handling
 
-Example:
+The library defines specific error classes for different validation failures:
 
-```ruby
-begin
-  pos = Sashite::Feen.parse(str)
-rescue Sashite::Feen::Error::Style => e
-  warn "Bad style-turn: #{e.message}"
-end
+```txt
+Sashite::Feen::Error  # Base error class
+├── Error::Syntax     # Malformed FEEN structure
+├── Error::Piece      # Invalid EPIN notation
+├── Error::Style      # Invalid SIN notation
+├── Error::Count      # Invalid piece counts
+└── Error::Validation # Other semantic violations
 ```
 
----
-
-## Dependencies & compatibility
-
-* Runtime: `sashite-epin`, `sashite-sin`
-* Purely functional; all objects are frozen; methods return new values.
-* No JSON serialization in this gem.
-
----
-
-## Development
+## Properties
 
-```sh
-# Clone
-git clone https://github.com/sashite/feen.rb.git
-cd feen.rb
+- **Purely functional**: Immutable data structures, no side effects
+- **Canonical output**: Deterministic string generation
+- **Specification compliant**: Strict adherence to FEEN v1.0.0
+- **Minimal API**: Two methods for complete functionality
+- **Composable**: Built on EPIN and SIN specifications
 
-# Install
-bundle install
+## Dependencies
 
-# Run smoke tests
-ruby test.rb
+- [sashite-epin](https://github.com/sashite/epin.rb) – Extended Piece Identifier Notation
+- [sashite-sin](https://github.com/sashite/sin.rb) – Style Identifier Notation
 
-# Generate YARD docs
-yard doc
-```
-
----
-
-## Contributing
+## Documentation
 
-1. Fork the repository
-2. Create a feature branch: `git checkout -b feat/my-change`
-3. Add tests covering your changes
-4. Ensure everything is green (lint, tests, docs)
-5. Commit with a conventional message
-6. Push and open a Pull Request
-
----
+- [FEEN Specification v1.0.0](https://sashite.dev/specs/feen/1.0.0/)
+- [FEEN Examples](https://sashite.dev/specs/feen/1.0.0/examples/)
+- [API Documentation](https://rubydoc.info/github/sashite/feen.rb/main)
 
 ## License
 
-Open source under the [MIT License](https://opensource.org/licenses/MIT).
-
----
+Available as open source under the [MIT License](https://opensource.org/licenses/MIT).
 
 ## About
 
-Maintained by **Sashité** — promoting chess variants and sharing the beauty of board-game cultures.
+Maintained by [Sashité](https://sashite.com/) – promoting chess variants and sharing the beauty of board game cultures.

data/lib/sashite/feen/dumper/piece_placement.rb

@@ -3,83 +3,106 @@
 module Sashite
   module Feen
     module Dumper
+      # Dumper for the piece placement field (first field of FEEN).
+      #
+      # Converts a Placement object into its FEEN string representation,
+      # encoding board configuration using EPIN notation with empty square
+      # compression and multi-dimensional separator support.
+      #
+      # @see https://sashite.dev/specs/feen/1.0.0/
       module PiecePlacement
-        # Separator between ranks
+        # Rank separator for 2D boards.
         RANK_SEPARATOR = "/"
 
-        module_function
-
-        # Dump a Placement grid to FEEN ranks (e.g., "rnbqkbnr/pppppppp/8/...")
+        # Dump a Placement object into its FEEN piece placement string.
         #
-        # @param placement [Sashite::Feen::Placement]
-        # @return [String]
-        def dump(placement)
-          pl = _coerce_placement(placement)
-
-          grid = pl.grid
-          raise Error::Bounds, "empty grid" if grid.empty?
-          raise Error::Bounds, "grid must be an Array of rows" unless grid.is_a?(Array)
-
-          width = nil
-          dumped_rows = grid.each_with_index.map do |row, r_idx|
-            raise Error::Bounds, "row #{r_idx + 1} must be an Array, got #{row.class}" unless row.is_a?(Array)
-
-            width ||= row.length
-            raise Error::Bounds, "row #{r_idx + 1} has zero width" if width.zero?
+        # Converts the board configuration into FEEN notation by processing
+        # each rank, compressing consecutive empty squares into digits, and
+        # joining ranks with appropriate separators for multi-dimensional boards.
+        #
+        # @param placement [Placement] The board placement object
+        # @return [String] FEEN piece placement field string
+        #
+        # @example Chess starting position
+        #   dump(placement)
+        #   # => "+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"
+        #
+        # @example Empty 8x8 board
+        #   dump(placement)
+        #   # => "8/8/8/8/8/8/8/8"
+        def self.dump(placement)
+          ranks = placement.ranks.map { |rank| dump_rank(rank) }
+          join_ranks(ranks, placement.dimension, placement.sections)
+        end
 
-            if row.length != width
-              raise Error::Bounds,
-                    "inconsistent row width at row #{r_idx + 1} (expected #{width}, got #{row.length})"
+        # Dump a single rank into its FEEN representation.
+        #
+        # Converts a rank (array of pieces and nils) into FEEN notation by:
+        # 1. Converting pieces to EPIN strings
+        # 2. Compressing consecutive nils into digit counts
+        #
+        # @param rank [Array] Array of piece objects and nils
+        # @return [String] FEEN rank string
+        #
+        # @example Rank with pieces and empty squares
+        #   dump_rank([piece1, nil, nil, piece2])
+        #   # => "K2Q"
+        private_class_method def self.dump_rank(rank)
+          result = []
+          empty_count = 0
+
+          rank.each do |square|
+            if square.nil?
+              empty_count += 1
+            else
+              result << empty_count.to_s if empty_count > 0
+              result << square.to_s
+              empty_count = 0
             end
-
-            _dump_row(row, r_idx)
           end
 
-          dumped_rows.join(RANK_SEPARATOR)
+          result << empty_count.to_s if empty_count > 0
+          result.join
         end
 
-        # -- internals ---------------------------------------------------------
-
-        # Accept nil (and legacy "") as empty cells
-        def _empty_cell?(cell)
-          cell.nil? || cell == ""
-        end
-        private_class_method :_empty_cell?
-
-        def _dump_row(row, r_idx)
-          out = +""
-          empty_run = 0
-
-          row.each_with_index do |cell, c_idx|
-            if _empty_cell?(cell)
-              empty_run += 1
-              next
-            end
-
-            if empty_run.positive?
-              out << empty_run.to_s
-              empty_run = 0
+        # Join ranks with appropriate separators for multi-dimensional boards.
+        #
+        # Uses section information if available, otherwise treats all ranks equally.
+        #
+        # @param ranks [Array<String>] Array of rank strings
+        # @param dimension [Integer] Board dimensionality (default 2)
+        # @param sections [Array<Integer>, nil] Section sizes for grouping
+        # @return [String] Complete piece placement string
+        #
+        # @example 2D board
+        #   join_ranks(["8", "8"], 2, nil)
+        #   # => "8/8"
+        #
+        # @example 3D board with sections
+        #   join_ranks(["5", "5", "5", "5"], 3, [2, 2])
+        #   # => "5/5//5/5"
+        private_class_method def self.join_ranks(ranks, dimension = 2, sections = nil)
+          if dimension == 2 || sections.nil?
+            # Simple 2D case or no section info
+            separator = RANK_SEPARATOR * (dimension - 1)
+            ranks.join(separator)
+          else
+            # Multi-dimensional with section info
+            rank_separator = RANK_SEPARATOR
+            section_separator = RANK_SEPARATOR * (dimension - 1)
+
+            # Group ranks by sections
+            result = []
+            offset = 0
+            sections.each do |section_size|
+              section_ranks = ranks[offset, section_size]
+              result << section_ranks.join(rank_separator)
+              offset += section_size
             end
 
-            begin
-              out << ::Sashite::Epin.dump(cell)
-            rescue StandardError => e
-              raise Error::Piece,
-                    "invalid EPIN value at (row #{r_idx + 1}, col #{c_idx + 1}): #{e.message}"
-            end
+            result.join(section_separator)
           end
-
-          out << empty_run.to_s if empty_run.positive?
-          out
-        end
-        private_class_method :_dump_row
-
-        def _coerce_placement(obj)
-          return obj if obj.is_a?(Placement)
-
-          raise TypeError, "expected Sashite::Feen::Placement, got #{obj.class}"
         end
-        private_class_method :_coerce_placement
       end
     end
   end

data/lib/sashite/feen/dumper/pieces_in_hand.rb

@@ -3,56 +3,145 @@
 module Sashite
   module Feen
     module Dumper
+      # Dumper for the pieces-in-hand field (second field of FEEN).
+      #
+      # Converts a Hands object into its FEEN string representation,
+      # encoding captured pieces held by each player in canonical sorted order.
+      #
+      # @see https://sashite.dev/specs/feen/1.0.0/
       module PiecesInHand
-        # Separator between hand entries
-        ENTRY_SEPARATOR = ","
+        # Player separator in pieces-in-hand field.
+        PLAYER_SEPARATOR = "/"
 
-        module_function
-
-        # Dump a Hands multiset to FEEN (e.g., "-", "P,2xN,R")
+        # Dump a Hands object into its FEEN pieces-in-hand string.
+        #
+        # Generates canonical representation with pieces sorted according to
+        # FEEN ordering rules: by quantity (descending), base letter (ascending),
+        # case (uppercase first), prefix (-, +, none), and suffix (none, ').
+        #
+        # @param hands [Hands] The hands object containing pieces for both players
+        # @return [String] FEEN pieces-in-hand field string
+        #
+        # @example No pieces in hand
+        #   dump(hands)
+        #   # => "/"
         #
-        # Canonicalization:
-        #   - entries sorted lexicographically by EPIN token
-        #   - counts rendered as "NxTOKEN" when N > 1
+        # @example First player has pieces
+        #   dump(hands)
+        #   # => "2P/p"
         #
-        # @param hands [Sashite::Feen::Hands]
-        # @return [String]
-        def dump(hands)
-          h = _coerce_hands(hands)
+        # @example Both players have pieces
+        #   dump(hands)
+        #   # => "RBN/2p"
+        def self.dump(hands)
+          first_player_str = dump_player_pieces(hands.first_player)
+          second_player_str = dump_player_pieces(hands.second_player)
 
-          map = h.map
-          raise Error::Count, "negative counts are not allowed" if map.values.any? { |v| Integer(v).negative? }
+          "#{first_player_str}#{PLAYER_SEPARATOR}#{second_player_str}"
+        end
 
-          return "-" if map.empty?
+        # Dump pieces for a single player.
+        #
+        # Groups identical pieces, counts them, sorts canonically, and formats
+        # with count prefix when needed (e.g., "3P" for three pawns).
+        #
+        # @param pieces [Array] Array of piece objects for one player
+        # @return [String] Formatted piece string (empty if no pieces)
+        #
+        # @example Single piece types
+        #   dump_player_pieces([pawn1, pawn2, pawn3, rook1])
+        #   # => "3PR"
+        #
+        # @example Empty hand
+        #   dump_player_pieces([])
+        #   # => ""
+        private_class_method def self.dump_player_pieces(pieces)
+          return "" if pieces.empty?
 
-          entries = map.map do |epin_value, count|
-            c = Integer(count)
-            raise Error::Count, "hand count must be >= 1, got #{c}" if c <= 0
+          grouped = group_pieces(pieces)
+          sorted = sort_grouped_pieces(grouped)
+          format_pieces(sorted)
+        end
 
-            token = begin
-              ::Sashite::Epin.dump(epin_value)
-            rescue StandardError => e
-              raise Error::Piece, "invalid EPIN value in hands: #{e.message}"
-            end
+        # Group identical pieces and count occurrences.
+        #
+        # @param pieces [Array] Array of piece objects
+        # @return [Hash] Hash mapping piece strings to counts
+        #
+        # @example
+        #   group_pieces([pawn1, pawn2, rook1])
+        #   # => {"P" => 2, "R" => 1}
+        private_class_method def self.group_pieces(pieces)
+          pieces.group_by(&:to_s).transform_values(&:size)
+        end
 
-            [token, c]
+        # Sort grouped pieces according to FEEN canonical ordering.
+        #
+        # Sorting rules (in order of precedence):
+        # 1. By quantity (descending) - most pieces first
+        # 2. By base letter (ascending, case-insensitive)
+        # 3. By case - uppercase before lowercase
+        # 4. By prefix - "-", "+", then none
+        # 5. By suffix - none, then "'"
+        #
+        # @param grouped [Hash] Hash of piece strings to counts
+        # @return [Array<Array>] Sorted array of [piece_string, count] pairs
+        #
+        # @example
+        #   sort_grouped_pieces({"p" => 2, "P" => 3, "R" => 1, "+K" => 1, "K'" => 1})
+        #   # => [["+K", 1], ["K'", 1], ["P", 3], ["p", 2], ["R", 1]]
+        private_class_method def self.sort_grouped_pieces(grouped)
+          grouped.sort_by do |piece_str, count|
+            [
+              -count,                              # Quantity (descending)
+              extract_base_letter(piece_str),      # Base letter (ascending)
+              piece_str.match?(/[A-Z]/) ? 0 : 1,   # Case (uppercase first)
+              prefix_order(piece_str),             # Prefix order
+              piece_str.end_with?("'") ? 1 : 0     # Suffix order (none first)
+            ]
           end
-
-          # Sort by EPIN token for deterministic output
-          entries.sort_by! { |(token, _)| token }
-
-          entries.map { |token, c| c == 1 ? token : "#{c}x#{token}" }
-                 .join(ENTRY_SEPARATOR)
         end
 
-        # -- helpers -----------------------------------------------------------
+        # Extract base letter from piece string (without modifiers).
+        #
+        # @param piece_str [String] EPIN piece string
+        # @return [String] Uppercase base letter
+        #
+        # @example
+        #   extract_base_letter("+K'")  # => "K"
+        #   extract_base_letter("-p")   # => "P"
+        private_class_method def self.extract_base_letter(piece_str)
+          piece_str.gsub(/[+\-']/, "").upcase
+        end
 
-        def _coerce_hands(obj)
-          return obj if obj.is_a?(Hands)
+        # Determine prefix sorting order.
+        #
+        # @param piece_str [String] EPIN piece string
+        # @return [Integer] Sort order (0 for "-", 1 for "+", 2 for none)
+        #
+        # @example
+        #   prefix_order("-K")  # => 0
+        #   prefix_order("+K")  # => 1
+        #   prefix_order("K")   # => 2
+        private_class_method def self.prefix_order(piece_str)
+          return 0 if piece_str.start_with?("-")
+          return 1 if piece_str.start_with?("+")
+          2
+        end
 
-          raise TypeError, "expected Sashite::Feen::Hands, got #{obj.class}"
+        # Format sorted pieces with count prefixes.
+        #
+        # @param sorted [Array<Array>] Sorted array of [piece_string, count] pairs
+        # @return [String] Formatted piece string
+        #
+        # @example
+        #   format_pieces([["P", 3], ["R", 1], ["p", 2]])
+        #   # => "3PR2p"
+        private_class_method def self.format_pieces(sorted)
+          sorted.map do |piece_str, count|
+            count > 1 ? "#{count}#{piece_str}" : piece_str
+          end.join
         end
-        private_class_method :_coerce_hands
       end
     end
   end