qi 12.0.0 → 14.0.0

data/lib/qi/board.rb

@@ -1,129 +1,178 @@
 # frozen_string_literal: true
 
 class Qi
-  # Pure validation functions for multi-dimensional board structures.
+  # Pure functions for flat board operations.
   #
-  # A board is represented as a nested Array where:
+  # A board is stored as a flat +Array+ in row-major order where each
+  # element is either +nil+ (empty square) or a +String+ (a piece).
+  # The board shape (dimensions) is maintained separately.
   #
-  # - A *1D board* is a flat array of squares: +[nil, "K^", nil]+
-  # - A *2D board* is an array of ranks: +[[nil, nil], ["K^", nil]]+
-  # - A *3D board* is an array of layers, each an array of ranks.
+  # This module provides three categories of functions:
   #
-  # Each leaf element (square) is either +nil+ (empty) or any non-nil
-  # object (a piece). String normalization of pieces is the responsibility
-  # of the +Qi+ class, not of this module.
+  # - *Shape validation* — checks dimension count, types, and bounds.
+  # - *Diff application* — applies index-to-piece changes to a flat board.
+  # - *Nested conversion* — reconstructs a nested array from a flat board
+  #   and its shape, for display or serialization.
   #
-  # == Constraints
+  # All functions are stateless and side-effect-free.
   #
-  # - Maximum dimensionality: 3
-  # - Maximum size per dimension: 255
-  # - At least one square (non-empty board)
-  # - Rectangular structure: all sub-arrays at the same depth must have
-  #   identical length (enforced globally, not just per-sibling).
+  # @example Validate a shape
+  #   Qi::Board.validate_shape([8, 8]) #=> 64
   #
-  # @example Validate a 2D board
-  #   Qi::Board.validate([["a", nil], [nil, "b"]]) #=> [4, 2]
+  # @example Apply a diff
+  #   board = Array.new(4)
+  #   new_board, new_count = Qi::Board.apply_diff(board, 4, 0, { 0 => "K", 3 => "k" })
+  #   new_board #=> ["K", nil, nil, "k"]
+  #   new_count #=> 2
   #
-  # @example Validate an empty board
-  #   Qi::Board.validate([[nil, nil, nil], [nil, nil, nil], [nil, nil, nil]]) #=> [9, 0]
+  # @example Convert to nested
+  #   Qi::Board.to_nested(["a", nil, nil, "b"], [2, 2]) #=> [["a", nil], [nil, "b"]]
   module Board
-    MAX_DIMENSIONS    = 3
+    MAX_DIMENSIONS     = 3
     MAX_DIMENSION_SIZE = 255
+    MAX_SQUARE_COUNT   = 65_025
+    MAX_PIECE_BYTESIZE = 255
 
-    # Validates a board and returns its square and piece counts.
+    # Validates board dimensions and returns the total square count.
     #
-    # Validation is performed in a single recursive pass that simultaneously
-    # infers the board shape, verifies structural regularity, checks dimension
-    # limits, and counts squares and pieces.
+    # @param shape [Array<Integer>] dimension sizes (1 to 3 integers, each 1–255).
+    # @return [Integer] the total number of squares.
+    # @raise [ArgumentError] if the shape is invalid.
+    # @raise [ArgumentError] if the total square count exceeds {MAX_SQUARE_COUNT}.
     #
-    # @param board [Object] the board structure to validate.
-    # @return [Array(Integer, Integer)] +[square_count, piece_count]+.
-    # @raise [ArgumentError] if the board is structurally invalid.
-    #
-    # @example A 2D board
-    #   Qi::Board.validate([["r", nil, nil], [nil, nil, "R"]]) #=> [6, 2]
-    #
-    # @example A 1D board
-    #   Qi::Board.validate(["k", nil, nil, "K"]) #=> [4, 2]
-    #
-    # @example A 3D board (2 layers × 2 ranks × 2 files)
-    #   Qi::Board.validate([[["a", nil], [nil, "b"]], [[nil, "c"], ["d", nil]]]) #=> [8, 4]
-    #
-    # @example Non-rectangular boards are rejected
-    #   Qi::Board.validate([["a", "b"], ["c"]])
-    #   # => ArgumentError: non-rectangular board: expected 2 elements, got 1
-    def self.validate(board)
-      unless board.is_a?(::Array)
-        raise ::ArgumentError, "board must be an Array"
+    # @example
+    #   Qi::Board.validate_shape([8, 8])    #=> 64
+    #   Qi::Board.validate_shape([9, 9])    #=> 81
+    #   Qi::Board.validate_shape([5, 5, 5]) #=> 125
+    def self.validate_shape(shape)
+      if shape.empty?
+        raise ::ArgumentError, "at least one dimension is required"
       end
 
-      if board.empty?
-        raise ::ArgumentError, "board must not be empty"
+      if shape.size > MAX_DIMENSIONS
+        raise ::ArgumentError, "board exceeds #{MAX_DIMENSIONS} dimensions (got #{shape.size})"
       end
 
-      validate_recursive(board, nil, 0)
-    end
+      shape.each do |dim|
+        unless dim.is_a?(::Integer)
+          raise ::ArgumentError, "dimension size must be an Integer, got #{dim.class}"
+        end
 
-    # Single-pass recursive validation.
-    #
-    # At each level, determines whether this is a leaf rank (contains
-    # non-Array elements) or an intermediate dimension (contains Arrays).
-    # Infers expected sizes from the first element at each level,
-    # validates all siblings match, and enforces dimension limits.
-    #
-    # @param node [Array] the current sub-array being validated.
-    # @param expected_size [Integer, nil] expected length (nil if first sibling).
-    # @param depth [Integer] current nesting depth (0-based).
-    # @return [Array(Integer, Integer)] +[square_count, piece_count]+.
-    def self.validate_recursive(node, expected_size, depth)
-      if expected_size && node.size != expected_size
-        raise ::ArgumentError, "non-rectangular board: expected #{expected_size} elements, got #{node.size}"
+        if dim < 1
+          raise ::ArgumentError, "dimension size must be at least 1, got #{dim}"
+        end
+
+        if dim > MAX_DIMENSION_SIZE
+          raise ::ArgumentError, "dimension size #{dim} exceeds maximum of #{MAX_DIMENSION_SIZE}"
+        end
       end
 
-      if node.size > MAX_DIMENSION_SIZE
-        raise ::ArgumentError, "dimension size #{node.size} exceeds maximum of #{MAX_DIMENSION_SIZE}"
+      total = shape.reduce(:*)
+
+      if total > MAX_SQUARE_COUNT
+        raise ::ArgumentError, "board exceeds #{MAX_SQUARE_COUNT} squares (got #{total})"
       end
 
-      if node.first.is_a?(::Array)
-        # Intermediate dimension: validate depth, then recurse.
-        if depth >= MAX_DIMENSIONS - 1
-          raise ::ArgumentError, "board exceeds #{MAX_DIMENSIONS} dimensions"
-        end
+      total
+    end
 
-        inner_size = node.first.size
+    # Applies changes to a flat board, returning a new array and updated piece count.
+    #
+    # Each change maps a flat index to a piece (+String+) or +nil+ (empty).
+    # The original board is not modified.
+    #
+    # @param board [Array] the current flat board.
+    # @param square_count [Integer] number of squares on the board.
+    # @param board_piece_count [Integer] current number of pieces on the board.
+    # @param changes [Hash{Integer => String, nil}] flat index to piece mapping.
+    # @return [Array(Array, Integer)] +[new_board, new_board_piece_count]+.
+    # @raise [ArgumentError] if an index is invalid or a piece is not a String.
+    # @raise [ArgumentError] if a piece exceeds {MAX_PIECE_BYTESIZE} bytes.
+    #
+    # @example Place two pieces
+    #   Qi::Board.apply_diff(Array.new(4), 4, 0, { 0 => "K", 3 => "k" })
+    #   #=> [["K", nil, nil, "k"], 2]
+    #
+    # @example Move a piece
+    #   Qi::Board.apply_diff(["K", nil, nil, nil], 4, 1, { 0 => nil, 2 => "K" })
+    #   #=> [[nil, nil, "K", nil], 1]
+    def self.apply_diff(board, square_count, board_piece_count, changes)
+      new_board = board.dup
+      delta = 0
+
+      changes.each do |index, piece|
+        unless index.is_a?(::Integer) && index >= 0 && index < square_count
+          raise ::ArgumentError, "invalid flat index: #{index} (board has #{square_count} squares)"
+        end
 
-        if inner_size == 0
-          raise ::ArgumentError, "board must not be empty"
+        unless piece.nil? || piece.is_a?(::String)
+          raise ::ArgumentError, "piece must be a String, got #{piece.class}"
         end
 
-        total_squares = 0
-        total_pieces  = 0
+        if piece.is_a?(::String) && piece.bytesize > MAX_PIECE_BYTESIZE
+          raise ::ArgumentError, "piece exceeds #{MAX_PIECE_BYTESIZE} bytes (got #{piece.bytesize})"
+        end
 
-        node.each do |sub|
-          unless sub.is_a?(::Array)
-            raise ::ArgumentError, "inconsistent board structure: mixed arrays and non-arrays at same level"
-          end
+        old = new_board[index]
+        delta += (piece.nil? ? 0 : 1) - (old.nil? ? 0 : 1)
+        new_board[index] = piece
+      end
 
-          sq, pc = validate_recursive(sub, inner_size, depth + 1)
-          total_squares += sq
-          total_pieces  += pc
-        end
+      [new_board, board_piece_count + delta]
+    end
 
-        [total_squares, total_pieces]
-      else
-        # Leaf rank: validate structure, then count pieces.
-        node.each do |square|
-          if square.is_a?(::Array)
-            raise ::ArgumentError, "inconsistent board structure: expected flat squares at this level"
-          end
-        end
+    # Converts a flat board into a nested array matching the given shape.
+    #
+    # This is an O(n) operation intended for display or serialization,
+    # not for the hot path.
+    #
+    # @param board [Array] the flat board.
+    # @param shape [Array<Integer>] the board dimensions.
+    # @return [Array] a nested array. For a 1D shape, returns a flat array copy.
+    #
+    # @example 1D board
+    #   Qi::Board.to_nested(["a", nil, "b"], [3])
+    #   #=> ["a", nil, "b"]
+    #
+    # @example 2D board
+    #   Qi::Board.to_nested(["a", nil, nil, "b"], [2, 2])
+    #   #=> [["a", nil], [nil, "b"]]
+    #
+    # @example 3D board (2×2×2)
+    #   flat = ["a", nil, nil, "b", nil, "c", "d", nil]
+    #   Qi::Board.to_nested(flat, [2, 2, 2])
+    #   #=> [[["a", nil], [nil, "b"]], [[nil, "c"], ["d", nil]]]
+    def self.to_nested(board, shape)
+      return board.dup if shape.size == 1
+
+      nest(board, compute_chunk_sizes(shape), 0)
+    end
 
-        [node.size, node.count { |sq| !sq.nil? }]
+    # Pre-computes chunk sizes for each dimension level.
+    #
+    # For shape [8, 8], returns [8, 1].
+    # For shape [5, 5, 5], returns [25, 5, 1].
+    # For shape [8], returns [1].
+    def self.compute_chunk_sizes(shape)
+      sizes = ::Array.new(shape.size)
+      sizes[-1] = 1
+      (shape.size - 2).downto(0) do |i|
+        sizes[i] = sizes[i + 1] * shape[i + 1]
       end
+      sizes
     end
 
-    private_class_method :validate_recursive
+    # Recursively slices a flat array into nested sub-arrays.
+    def self.nest(flat, chunk_sizes, dim)
+      if dim == chunk_sizes.size - 1
+        return flat.dup
+      end
+
+      chunk = chunk_sizes[dim]
+      flat.each_slice(chunk).map { |slice| nest(slice, chunk_sizes, dim + 1) }
+    end
 
-    freeze
+    private_class_method :compute_chunk_sizes,
+                         :nest
   end
 end

data/lib/qi/hands.rb

@@ -1,80 +1,99 @@
 # frozen_string_literal: true
 
 class Qi
-  # Pure validation functions for player hands.
+  # Pure functions for player hand operations.
   #
-  # Hands are represented as a Hash with exactly two keys:
+  # A hand is represented as a +Hash{String => Integer}+ mapping each
+  # piece to its count. An empty hand is +{}+. Entries whose count
+  # reaches zero are removed from the hash.
   #
-  # - +:first+ — array of pieces held by the first player.
-  # - +:second+ — array of pieces held by the second player.
+  # This representation gives O(1) add, remove, and count queries per
+  # piece type, compared to O(n) scans on a flat array.
   #
-  # Each piece in a hand can be any non-nil object. String normalization
-  # of pieces is the responsibility of the +Qi+ class, not of this module.
-  # The ordering of pieces within a hand carries no semantic meaning.
+  # All functions are stateless and side-effect-free.
   #
-  # @example Validate hands with pieces
-  #   Qi::Hands.validate({ first: ["+P", "+P"], second: ["b"] }) #=> 3
+  # @example Apply a diff
+  #   hand = { "P" => 1 }
+  #   new_hand, count = Qi::Hands.apply_diff(hand, 1, { "P" => 1, "B" => 1 })
+  #   new_hand #=> { "P" => 2, "B" => 1 }
+  #   count    #=> 3
   #
-  # @example Validate empty hands
-  #   Qi::Hands.validate({ first: [], second: [] }) #=> 0
+  # @example Remove pieces
+  #   hand = { "P" => 2, "B" => 1 }
+  #   new_hand, count = Qi::Hands.apply_diff(hand, 3, { "P" => -1, "B" => -1 })
+  #   new_hand #=> { "P" => 1 }
+  #   count    #=> 1
   module Hands
-    # Validates hands structure and returns the total piece count.
+    MAX_PIECE_BYTESIZE = 255
+
+    # Applies delta changes to a hand, returning the new hash and its
+    # piece count.
     #
-    # Validation checks shape (exactly two keys), type (both values are
-    # arrays), and rejects +nil+ elements in each hand.
+    # Each change maps a piece (+String+) to an integer delta: positive
+    # to add copies, negative to remove, zero is a no-op. Entries whose
+    # count reaches zero are removed from the result.
     #
-    # @param hands [Object] the hands structure to validate.
-    # @return [Integer] the total number of pieces across both hands.
-    # @raise [ArgumentError] if the hands structure is invalid.
+    # The piece count is computed incrementally during the diff — no
+    # extra iteration over the result hash is needed.
     #
-    # @example Valid hands
-    #   Qi::Hands.validate({ first: ["P", "B"], second: ["p"] }) #=> 3
+    # The original hand is not modified.
     #
-    # @example Nil piece rejected
-    #   Qi::Hands.validate({ first: [nil], second: [] })
-    #   # => ArgumentError: hand pieces must not be nil
+    # @param hand [Hash{String => Integer}] the current hand.
+    # @param hand_count [Integer] current total piece count of +hand+.
+    # @param changes [Hash{String => Integer}] piece to delta mapping.
+    #   Keys are normalized from Symbol to String (Ruby keyword argument
+    #   convention).
+    # @return [Array(Hash{String => Integer}, Integer)]
+    #   +[new_hand, new_piece_count]+.
+    # @raise [ArgumentError] if a delta is not an Integer.
+    # @raise [ArgumentError] if a piece exceeds {MAX_PIECE_BYTESIZE} bytes.
+    # @raise [ArgumentError] if removing more pieces than present.
     #
-    # @example Missing key
-    #   Qi::Hands.validate({ first: [] })
-    #   # => ArgumentError: hands must have exactly keys :first and :second
-    def self.validate(hands)
-      validate_shape(hands)
-      validate_arrays(hands)
-      validate_hand(hands[:first])
-      validate_hand(hands[:second])
-      hands[:first].size + hands[:second].size
-    end
+    # @example Add pieces
+    #   Qi::Hands.apply_diff({}, 0, { "P" => 2, "B" => 1 })
+    #   #=> [{ "P" => 2, "B" => 1 }, 3]
+    #
+    # @example Remove a piece
+    #   Qi::Hands.apply_diff({ "P" => 2, "B" => 1 }, 3, { "P" => -1 })
+    #   #=> [{ "P" => 1, "B" => 1 }, 2]
+    #
+    # @example Zero delta is a no-op
+    #   Qi::Hands.apply_diff({ "P" => 1 }, 1, { "P" => 0 })
+    #   #=> [{ "P" => 1 }, 1]
+    def self.apply_diff(hand, hand_count, changes)
+      result = hand.dup
+      count  = hand_count
 
-    # --- Shape validation -----------------------------------------------------
+      changes.each do |piece_key, delta|
+        unless delta.is_a?(::Integer)
+          raise ::ArgumentError, "delta must be an Integer, got #{delta.class} for piece #{piece_key.inspect}"
+        end
 
-    def self.validate_shape(hands)
-      unless hands.is_a?(::Hash)
-        raise ::ArgumentError, "hands must be a Hash with keys :first and :second"
-      end
+        next if delta == 0
 
-      return if hands.size == 2 && hands.key?(:first) && hands.key?(:second)
+        piece = piece_key.is_a?(::Symbol) ? piece_key.name : piece_key
 
-      raise ::ArgumentError, "hands must have exactly keys :first and :second"
-    end
+        if piece.bytesize > MAX_PIECE_BYTESIZE
+          raise ::ArgumentError, "piece exceeds #{MAX_PIECE_BYTESIZE} bytes (got #{piece.bytesize})"
+        end
 
-    def self.validate_arrays(hands)
-      return if hands[:first].is_a?(::Array) && hands[:second].is_a?(::Array)
+        current = result[piece] || 0
+        new_count = current + delta
 
-      raise ::ArgumentError, "each hand must be an Array"
-    end
+        if new_count < 0
+          raise ::ArgumentError, "cannot remove #{piece.inspect}: not found in hand"
+        end
 
-    # --- Piece validation -----------------------------------------------------
+        if new_count == 0
+          result.delete(piece)
+        else
+          result[piece] = new_count
+        end
 
-    def self.validate_hand(pieces)
-      pieces.each do |piece|
-        raise ::ArgumentError, "hand pieces must not be nil" if piece.nil?
+        count += delta
       end
-    end
 
-    private_class_method :validate_shape,
-                         :validate_arrays,
-                         :validate_hand
-
-    freeze
+      [result, count]
+    end
   end
 end

data/lib/qi/styles.rb

@@ -1,74 +1,58 @@
 # frozen_string_literal: true
 
 class Qi
-  # Pure validation functions for player styles.
+  # Pure validation function for player styles.
   #
-  # Styles are represented as a Hash with exactly two keys:
+  # A style is a +String+ label denoting a movement tradition or game
+  # family (e.g., +"C"+, +"S"+, +"X"+). Semantic validation (e.g., SIN
+  # compliance) is the responsibility of the encoding layer (FEEN, PON,
+  # etc.).
   #
-  # - +:first+ — the style associated with the first player side.
-  # - +:second+ — the style associated with the second player side.
-  #
-  # Style values can be any non-nil object. String normalization is the
-  # responsibility of the +Qi+ class, not of this module. Semantic
-  # validation (e.g., SIN compliance) is the responsibility of the
-  # encoding layer (FEEN, PON, etc.).
-  #
-  # @example Validate string styles
-  #   Qi::Styles.validate({ first: "C", second: "c" }) #=> nil
-  #
-  # @example Validate symbol styles
-  #   Qi::Styles.validate({ first: :chess, second: :shogi }) #=> nil
+  # @example Validate a style
+  #   Qi::Styles.validate(:first, "C") #=> "C"
   module Styles
-    # Validates the styles structure.
+    MAX_STYLE_BYTESIZE = 255
+
+    # Validates a single player style and returns it.
     #
-    # Returns +nil+ if the Hash has exactly keys +:first+ and +:second+ with
-    # non-nil values, or raises +ArgumentError+ otherwise.
+    # The style must not be +nil+, must be a +String+, and must not
+    # exceed {MAX_STYLE_BYTESIZE} bytes. The validated value is
+    # returned as-is (no coercion, no allocation).
     #
-    # @param styles [Object] the styles structure to validate.
-    # @return [nil]
-    # @raise [ArgumentError] if the styles structure is invalid.
+    # @param side [Symbol] +:first+ or +:second+, used in error messages.
+    # @param style [Object] the style value to validate.
+    # @return [String] the validated style.
+    # @raise [ArgumentError] if the style is nil or not a String.
+    # @raise [ArgumentError] if the style exceeds {MAX_STYLE_BYTESIZE} bytes.
     #
-    # @example Valid styles
-    #   Qi::Styles.validate({ first: "S", second: "s" }) #=> nil
+    # @example Valid style
+    #   Qi::Styles.validate(:first, "C") #=> "C"
     #
-    # @example Nil first style
-    #   Qi::Styles.validate({ first: nil, second: "c" })
+    # @example Nil style
+    #   Qi::Styles.validate(:first, nil)
     #   # => ArgumentError: first player style must not be nil
     #
-    # @example Nil second style
-    #   Qi::Styles.validate({ first: "C", second: nil })
-    #   # => ArgumentError: second player style must not be nil
-    #
-    # @example Missing key
-    #   Qi::Styles.validate({ first: "C" })
-    #   # => ArgumentError: styles must have exactly keys :first and :second
+    # @example Non-string style
+    #   Qi::Styles.validate(:second, :chess)
+    #   # => ArgumentError: second player style must be a String
     #
-    # @example Not a Hash
-    #   Qi::Styles.validate("not a hash")
-    #   # => ArgumentError: styles must be a Hash with keys :first and :second
-    def self.validate(styles)
-      validate_shape(styles)
-      validate_non_nil(styles)
-    end
-
-    def self.validate_shape(styles)
-      unless styles.is_a?(::Hash)
-        raise ::ArgumentError, "styles must be a Hash with keys :first and :second"
+    # @example Oversized style
+    #   Qi::Styles.validate(:first, "A" * 256)
+    #   # => ArgumentError: first player style exceeds 255 bytes
+    def self.validate(side, style)
+      if style.nil?
+        raise ::ArgumentError, "#{side} player style must not be nil"
       end
 
-      return if styles.size == 2 && styles.key?(:first) && styles.key?(:second)
+      unless style.is_a?(::String)
+        raise ::ArgumentError, "#{side} player style must be a String"
+      end
 
-      raise ::ArgumentError, "styles must have exactly keys :first and :second"
-    end
+      if style.bytesize > MAX_STYLE_BYTESIZE
+        raise ::ArgumentError, "#{side} player style exceeds #{MAX_STYLE_BYTESIZE} bytes"
+      end
 
-    def self.validate_non_nil(styles)
-      raise ::ArgumentError, "first player style must not be nil" if styles[:first].nil?
-      raise ::ArgumentError, "second player style must not be nil" if styles[:second].nil?
+      style
     end
-
-    private_class_method :validate_shape,
-                         :validate_non_nil
-
-    freeze
   end
 end