sashite-qpi 1.0.0 → 2.1.0

data/lib/sashite/qpi/identifier.rb

@@ -1,423 +1,243 @@
 # frozen_string_literal: true
 
-require "sashite/pin"
-require "sashite/sin"
+require_relative "constants"
+require_relative "errors"
 
 module Sashite
   module Qpi
-    # Represents an identifier in QPI (Qualified Piece Identifier) format.
+    # Represents a parsed QPI (Qualified Piece Identifier) identifier.
     #
-    # A QPI identifier combines style and piece attributes into a unified representation:
-    # - Family: Style family from SIN component (:A to :Z only)
-    # - Type: Piece type (:A to :Z) from PIN component
-    # - Side: Player assignment (:first or :second) from both components
-    # - State: Piece state (:normal, :enhanced, :diminished) from PIN component
-    # - Semantic constraint: SIN and PIN components must represent the same player
+    # A QPI identifier encodes complete Piece Identity by combining:
+    # - A SIN (Style Identifier Notation) component for Piece Style
+    # - A PIN (Piece Identifier Notation) component for Piece Name, Side, State, and Terminal Status
     #
-    # All instances are immutable - transformation methods return new instances.
-    # This follows the QPI Specification v1.0.0 with strict parameter validation
-    # consistent with the underlying SIN and PIN primitive specifications.
+    # Additionally, QPI defines a Native/Derived relationship based on case comparison
+    # between the SIN and PIN letters.
     #
-    # ## Strict Parameter Validation
+    # Instances are immutable (frozen after creation).
     #
-    # QPI enforces the same strict validation as its underlying primitives:
-    # - Family parameter must be a symbol from :A to :Z (not :a to :z)
-    # - Type parameter must be a symbol from :A to :Z (delegated to PIN)
-    # - Side parameter determines the display case, not the input parameters
+    # @example Creating identifiers
+    #   sin = Sashite::Sin.parse("C")
+    #   pin = Sashite::Pin.parse("K^")
+    #   qpi = Identifier.new(sin, pin)
     #
-    # This ensures consistency with SIN and PIN behavior where lowercase symbols
-    # are rejected with ArgumentError.
+    # @example Accessing components
+    #   qpi.sin.style      # => :C
+    #   qpi.pin.type       # => :K
+    #   qpi.pin.side       # => :first
+    #   qpi.pin.state      # => :normal
+    #   qpi.pin.terminal?  # => true
     #
-    # @example Strict parameter validation
-    #   # Valid - uppercase symbols only
-    #   Sashite::Qpi::Identifier.new(:C, :K, :first, :normal)   # => "C:K"
-    #   Sashite::Qpi::Identifier.new(:C, :K, :second, :normal)  # => "c:k"
+    # @example Native/Derived relationship
+    #   qpi = Identifier.new(Sin.parse("C"), Pin.parse("K"))
+    #   qpi.native?   # => true (both uppercase/first)
     #
-    #   # Invalid - lowercase symbols rejected
-    #   Sashite::Qpi::Identifier.new(:c, :K, :second, :normal)  # => ArgumentError
-    #   Sashite::Qpi::Identifier.new(:C, :k, :second, :normal)  # => ArgumentError
+    #   qpi = Identifier.new(Sin.parse("C"), Pin.parse("k"))
+    #   qpi.derived?  # => true (SIN uppercase, PIN lowercase)
     #
-    # @see https://sashite.dev/specs/qpi/1.0.0/ QPI Specification v1.0.0
+    # @see https://sashite.dev/specs/qpi/1.0.0/
     class Identifier
-      # Component separator for string representation
-      SEPARATOR = ":"
+      # @return [Sashite::Sin::Identifier] The SIN component
+      attr_reader :sin
 
-      # Error messages
-      ERROR_INVALID_QPI = "Invalid QPI string: %s"
-      ERROR_SEMANTIC_MISMATCH = "Family and side must represent the same player: family=%s (side=%s), side=%s"
-      ERROR_MISSING_SEPARATOR = "QPI string must contain exactly one colon separator: %s"
+      # @return [Sashite::Pin::Identifier] The PIN component
+      attr_reader :pin
 
-      # @return [Symbol] the style family (:A to :Z based on SIN component)
-      def family
-        @sin_identifier.family
-      end
-
-      # @return [Symbol] the piece type (:A to :Z)
-      def type
-        @pin_identifier.type
-      end
-
-      # @return [Symbol] the player side (:first or :second)
-      def side
-        @pin_identifier.side
-      end
-
-      # @return [Symbol] the piece state (:normal, :enhanced, or :diminished)
-      def state
-        @pin_identifier.state
-      end
-
-      # Create a new identifier instance
-      #
-      # @param family [Symbol] style family identifier (:A to :Z only)
-      # @param type [Symbol] piece type (:A to :Z only)
-      # @param side [Symbol] player side (:first or :second)
-      # @param state [Symbol] piece state (:normal, :enhanced, or :diminished)
-      # @raise [ArgumentError] if parameters are invalid or semantically inconsistent
+      # Creates a new Identifier instance.
       #
-      # @example Create identifiers with strict parameter validation
-      #   # Valid - uppercase symbols only
-      #   chess_king = Sashite::Qpi::Identifier.new(:C, :K, :first, :normal)   # => "C:K"
-      #   chess_pawn = Sashite::Qpi::Identifier.new(:C, :P, :second, :normal)  # => "c:p"
+      # @param sin [Sashite::Sin::Identifier] The SIN component
+      # @param pin [Sashite::Pin::Identifier] The PIN component
+      # @return [Identifier] A new frozen Identifier instance
+      # @raise [Errors::Argument] If components are invalid
       #
-      #   # Invalid - lowercase symbols rejected
-      #   # Sashite::Qpi::Identifier.new(:c, :K, :first, :normal)   # => ArgumentError
-      #   # Sashite::Qpi::Identifier.new(:C, :k, :first, :normal)   # => ArgumentError
-      def initialize(family, type, side, state = Pin::Identifier::NORMAL_STATE)
-        # Strict validation - delegate to underlying primitives for consistency
-        Sin::Identifier.validate_family(family)
-        Pin::Identifier.validate_type(type)
-        Pin::Identifier.validate_side(side)
-        Pin::Identifier.validate_state(state)
+      # @example
+      #   sin = Sashite::Sin.parse("C")
+      #   pin = Sashite::Pin.parse("K^")
+      #   Identifier.new(sin, pin)
+      def initialize(sin, pin)
+        validate_sin!(sin)
+        validate_pin!(pin)
 
-        # Create PIN component
-        @pin_identifier = Pin::Identifier.new(type, side, state)
-
-        # Create SIN component - pass family directly without normalization
-        @sin_identifier = Sin::Identifier.new(family, side)
-
-        # Validate semantic consistency
-        validate_semantic_consistency
+        @sin = sin
+        @pin = pin
 
         freeze
       end
 
-      # Parse a QPI string into an Identifier object
-      #
-      # @param qpi_string [String] QPI notation string (format: sin:pin)
-      # @return [Identifier] new identifier instance
-      # @raise [ArgumentError] if the QPI string is invalid
-      #
-      # @example Parse QPI strings with automatic component separation
-      #   Sashite::Qpi::Identifier.parse("C:K")   # => #<Qpi::Identifier family=:C type=:K side=:first state=:normal>
-      #   Sashite::Qpi::Identifier.parse("s:+r")  # => #<Qpi::Identifier family=:S type=:R side=:second state=:enhanced>
-      #   Sashite::Qpi::Identifier.parse("X:-S")  # => #<Qpi::Identifier family=:X type=:S side=:first state=:diminished>
-      def self.parse(qpi_string)
-        string_value = String(qpi_string)
-        sin_part, pin_part = split_components(string_value)
-
-        # Parse components
-        sin_identifier = Sin::Identifier.parse(sin_part)
-        pin_identifier = Pin::Identifier.parse(pin_part)
-
-        # Validate semantic consistency BEFORE creating new instance
-        unless sin_identifier.side == pin_identifier.side
-          raise ::ArgumentError, format(ERROR_SEMANTIC_MISMATCH,
-                                        sin_part, sin_identifier.side, pin_identifier.side)
-        end
-
-        # Extract parameters and create new instance
-        new(sin_identifier.family, pin_identifier.type, pin_identifier.side, pin_identifier.state)
-      end
+      # ========================================================================
+      # String Conversion
+      # ========================================================================
 
-      # Check if a string is a valid QPI notation
+      # Returns the QPI string representation.
       #
-      # @param qpi_string [String] the string to validate
-      # @return [Boolean] true if valid QPI, false otherwise
+      # @return [String] The QPI string in format "SIN:PIN"
       #
-      # @example Validate QPI strings with semantic checking
-      #   Sashite::Qpi::Identifier.valid?("C:K")     # => true
-      #   Sashite::Qpi::Identifier.valid?("s:+r")    # => true
-      #   Sashite::Qpi::Identifier.valid?("C:k")     # => false (semantic mismatch)
-      #   Sashite::Qpi::Identifier.valid?("Chess")   # => false (no separator)
-      def self.valid?(qpi_string)
-        return false unless qpi_string.is_a?(::String)
-
-        # Split components and validate each part
-        sin_part, pin_part = split_components(qpi_string)
-        return false unless Sashite::Sin.valid?(sin_part) && Sashite::Pin.valid?(pin_part)
-
-        # Semantic consistency check
-        sin_identifier = Sashite::Sin.parse(sin_part)
-        pin_identifier = Sashite::Pin.parse(pin_part)
-        sin_identifier.side == pin_identifier.side
-      rescue ArgumentError
-        false
-      end
-
-      # Convert the identifier to its QPI string representation
-      #
-      # @return [String] QPI notation string (format: sin:pin)
-      # @example Display QPI identifiers
-      #   identifier.to_s  # => "C:K"
+      # @example
+      #   qpi.to_s  # => "C:K^"
       def to_s
-        "#{@sin_identifier}#{SEPARATOR}#{@pin_identifier}"
+        "#{sin}#{Constants::SEPARATOR}#{pin}"
       end
 
-      # Convert to SIN string representation (style component only)
-      #
-      # @return [String] SIN notation string
-      # @example Extract style component
-      #   identifier.to_sin  # => "C"
-      def to_sin
-        @sin_identifier.to_s
-      end
+      # ========================================================================
+      # Native/Derived Relationship
+      # ========================================================================
 
-      # Convert to PIN string representation (piece component only)
+      # Checks if the identifier is native.
       #
-      # @return [String] PIN notation string
-      # @example Extract piece component
-      #   identifier.to_pin  # => "+K"
-      def to_pin
-        @pin_identifier.to_s
-      end
-
-      # Get the parsed SIN identifier object
+      # A QPI is native when sin.side equals pin.side (same case).
       #
-      # @return [Sashite::Sin::Identifier] SIN component as identifier object
-      def sin_component
-        @sin_identifier
-      end
-
-      # Get the parsed PIN identifier object
+      # @return [Boolean] true if native
       #
-      # @return [Sashite::Pin::Identifier] PIN component as identifier object
-      def pin_component
-        @pin_identifier
+      # @example
+      #   Identifier.new(Sin.parse("C"), Pin.parse("K")).native?  # => true
+      #   Identifier.new(Sin.parse("c"), Pin.parse("k")).native?  # => true
+      #   Identifier.new(Sin.parse("C"), Pin.parse("k")).native?  # => false
+      def native?
+        sin.side.equal?(pin.side)
       end
 
-      # Create a new identifier with enhanced state
+      # Checks if the identifier is derived.
       #
-      # @return [Identifier] new identifier with enhanced PIN component
-      def enhance
-        return self if enhanced?
-
-        self.class.new(family, type, side, Pin::Identifier::ENHANCED_STATE)
-      end
-
-      # Create a new identifier with diminished state
+      # A QPI is derived when sin.side differs from pin.side (different case).
       #
-      # @return [Identifier] new identifier with diminished PIN component
-      def diminish
-        return self if diminished?
-
-        self.class.new(family, type, side, Pin::Identifier::DIMINISHED_STATE)
-      end
-
-      # Create a new identifier with normal state (no modifiers)
+      # @return [Boolean] true if derived
       #
-      # @return [Identifier] new identifier with normalized PIN component
-      def normalize
-        return self if normal?
-
-        self.class.new(family, type, side, Pin::Identifier::NORMAL_STATE)
+      # @example
+      #   Identifier.new(Sin.parse("C"), Pin.parse("k")).derived?  # => true
+      #   Identifier.new(Sin.parse("c"), Pin.parse("K")).derived?  # => true
+      #   Identifier.new(Sin.parse("C"), Pin.parse("K")).derived?  # => false
+      def derived?
+        !native?
       end
 
-      # Create a new identifier with different piece type
-      #
-      # @param new_type [Symbol] new piece type (:A to :Z)
-      # @return [Identifier] new identifier with different type
-      def with_type(new_type)
-        return self if type == new_type
-
-        self.class.new(family, new_type, side, state)
-      end
+      # ========================================================================
+      # Native/Derived Transformations
+      # ========================================================================
 
-      # Create a new identifier with different side
+      # Returns a new Identifier with PIN case aligned to SIN case.
       #
-      # @param new_side [Symbol] new player side (:first or :second)
-      # @return [Identifier] new identifier with different side
-      def with_side(new_side)
-        return self if side == new_side
-
-        self.class.new(family, type, new_side, state)
-      end
-
-      # Create a new identifier with different state
+      # If already native, returns self.
       #
-      # @param new_state [Symbol] new piece state (:normal, :enhanced, or :diminished)
-      # @return [Identifier] new identifier with different state
-      def with_state(new_state)
-        return self if state == new_state
-
-        self.class.new(family, type, side, new_state)
-      end
-
-      # Create a new identifier with different family
+      # @return [Identifier] A native Identifier
+      #
+      # @example
+      #   qpi = Identifier.new(Sin.parse("C"), Pin.parse("r"))
+      #   qpi.native.to_s  # => "C:R"
       #
-      # @param new_family [Symbol] new style family identifier (:A to :Z)
-      # @return [Identifier] new identifier with different family
-      def with_family(new_family)
-        return self if family == new_family
+      #   qpi = Identifier.new(Sin.parse("C"), Pin.parse("R"))
+      #   qpi.native.to_s  # => "C:R" (unchanged)
+      def native
+        return self if native?
 
-        self.class.new(new_family, type, side, state)
+        self.class.new(sin, pin.with_side(sin.side))
       end
 
-      # Create a new identifier with opposite player assignment
+      # Returns a new Identifier with PIN case opposite to SIN case.
       #
-      # Changes the player assignment (side) while preserving the family and piece attributes.
-      # This maintains semantic consistency between the components.
+      # If already derived, returns self.
       #
-      # @return [Identifier] new identifier with opposite side but same family
+      # @return [Identifier] A derived Identifier
       #
-      # @example Flip player assignment while preserving family and attributes
-      #   chess_first = Sashite::Qpi::Identifier.parse("C:K")   # Chess king, first player
-      #   chess_second = chess_first.flip                       # => "c:k" (Chess king, second player)
+      # @example
+      #   qpi = Identifier.new(Sin.parse("C"), Pin.parse("R"))
+      #   qpi.derive.to_s  # => "C:r"
       #
-      #   shogi_first = Sashite::Qpi::Identifier.parse("S:+R")  # Shogi enhanced rook, first player
-      #   shogi_second = shogi_first.flip                       # => "s:+r" (Shogi enhanced rook, second player)
-      def flip
-        self.class.new(family, type, opposite_side, state)
-      end
+      #   qpi = Identifier.new(Sin.parse("C"), Pin.parse("r"))
+      #   qpi.derive.to_s  # => "C:r" (unchanged)
+      def derive
+        return self if derived?
 
-      # Check if the identifier has normal state
-      #
-      # @return [Boolean] true if normal state
-      def normal?
-        @pin_identifier.normal?
+        opposite_side = sin.side.equal?(:first) ? :second : :first
+        self.class.new(sin, pin.with_side(opposite_side))
       end
 
-      # Check if the identifier has enhanced state
-      #
-      # @return [Boolean] true if enhanced state
-      def enhanced?
-        @pin_identifier.enhanced?
-      end
-
-      # Check if the identifier has diminished state
-      #
-      # @return [Boolean] true if diminished state
-      def diminished?
-        @pin_identifier.diminished?
-      end
+      # ========================================================================
+      # Component Transformations
+      # ========================================================================
 
-      # Check if the identifier belongs to the first player
+      # Returns a new Identifier with a different SIN component.
       #
-      # @return [Boolean] true if first player
-      def first_player?
-        @pin_identifier.first_player?
-      end
-
-      # Check if the identifier belongs to the second player
+      # @param new_sin [Sashite::Sin::Identifier] The new SIN component
+      # @return [Identifier] A new Identifier with the specified SIN
+      # @raise [Errors::Argument] If the SIN is invalid
       #
-      # @return [Boolean] true if second player
-      def second_player?
-        @pin_identifier.second_player?
+      # @example
+      #   qpi = Identifier.new(Sin.parse("C"), Pin.parse("K"))
+      #   qpi.with_sin(Sin.parse("S")).to_s  # => "S:K"
+      def with_sin(new_sin)
+        self.class.new(new_sin, pin)
       end
 
-      # Check if this identifier has the same family as another
+      # Returns a new Identifier with a different PIN component.
       #
-      # @param other [Identifier] identifier to compare with
-      # @return [Boolean] true if same family (case-insensitive)
-      def same_family?(other)
-        return false unless other.is_a?(self.class)
-
-        @sin_identifier.same_family?(other.sin_component)
-      end
-
-      # Check if this identifier has different family from another
+      # @param new_pin [Sashite::Pin::Identifier] The new PIN component
+      # @return [Identifier] A new Identifier with the specified PIN
+      # @raise [Errors::Argument] If the PIN is invalid
       #
-      # @param other [Identifier] identifier to compare with
-      # @return [Boolean] true if different families
-      def cross_family?(other)
-        return false unless other.is_a?(self.class)
-
-        !same_family?(other)
+      # @example
+      #   qpi = Identifier.new(Sin.parse("C"), Pin.parse("K"))
+      #   qpi.with_pin(Pin.parse("+Q^")).to_s  # => "C:+Q^"
+      def with_pin(new_pin)
+        self.class.new(sin, new_pin)
       end
 
-      # Check if this identifier has the same side as another
+      # Returns a new Identifier with both components flipped.
       #
-      # @param other [Identifier] identifier to compare with
-      # @return [Boolean] true if same side
-      def same_side?(other)
-        return false unless other.is_a?(self.class)
-
-        @pin_identifier.same_side?(other.pin_component)
-      end
-
-      # Check if this identifier has the same type as another
+      # @return [Identifier] A new Identifier with both SIN and PIN flipped
       #
-      # @param other [Identifier] identifier to compare with
-      # @return [Boolean] true if same type
-      def same_type?(other)
-        return false unless other.is_a?(self.class)
-
-        @pin_identifier.same_type?(other.pin_component)
+      # @example
+      #   qpi = Identifier.new(Sin.parse("C"), Pin.parse("K^"))
+      #   qpi.flip.to_s  # => "c:k^"
+      def flip
+        self.class.new(sin.flip, pin.flip)
       end
 
-      # Check if this identifier has the same state as another
-      #
-      # @param other [Identifier] identifier to compare with
-      # @return [Boolean] true if same state
-      def same_state?(other)
-        return false unless other.is_a?(self.class)
+      # ========================================================================
+      # Equality
+      # ========================================================================
 
-        @pin_identifier.same_state?(other.pin_component)
-      end
-
-      # Custom equality comparison
+      # Checks equality with another Identifier.
       #
-      # @param other [Object] object to compare with
-      # @return [Boolean] true if identifiers are equal
+      # @param other [Object] The object to compare
+      # @return [Boolean] true if equal
       def ==(other)
-        return false unless other.is_a?(self.class)
+        return false unless self.class === other
 
-        @sin_identifier == other.sin_component && @pin_identifier == other.pin_component
+        sin == other.sin && pin == other.pin
       end
 
-      # Alias for == to ensure Set functionality works correctly
       alias eql? ==
 
-      # Custom hash implementation for use in collections
+      # Returns a hash code for the Identifier.
       #
-      # @return [Integer] hash value
+      # @return [Integer] Hash code
       def hash
-        [self.class, @sin_identifier, @pin_identifier].hash
+        [sin, pin].hash
       end
 
-      private
-
-      # Split QPI string into SIN and PIN components
+      # Returns an inspect string for the Identifier.
       #
-      # @param qpi_string [String] QPI string to split
-      # @return [Array<String>] array containing [sin_part, pin_part]
-      def self.split_components(qpi_string)
-        parts = qpi_string.split(SEPARATOR, 2)
-        raise ::ArgumentError, format(ERROR_MISSING_SEPARATOR, qpi_string) unless parts.size == 2
-
-        parts
+      # @return [String] Inspect representation
+      def inspect
+        "#<#{self.class} #{self}>"
       end
 
-      private_class_method :split_components
+      private
 
-      # Validate semantic consistency between SIN and PIN components
-      #
-      # @raise [ArgumentError] if family case doesn't match side
-      def validate_semantic_consistency
-        expected_side = @sin_identifier.side
-        actual_side = @pin_identifier.side
+      # ========================================================================
+      # Private Validation
+      # ========================================================================
 
-        return if expected_side == actual_side
+      def validate_sin!(sin)
+        return if sin.is_a?(Sashite::Sin::Identifier)
 
-        raise ::ArgumentError, format(ERROR_SEMANTIC_MISMATCH,
-                                      @sin_identifier.letter, expected_side, actual_side)
+        raise Errors::Argument, Errors::Argument::Messages::INVALID_SIN
       end
 
-      # Get the opposite player side
-      #
-      # @return [Symbol] the opposite side
-      def opposite_side
-        first_player? ? Pin::Identifier::SECOND_PLAYER : Pin::Identifier::FIRST_PLAYER
+      def validate_pin!(pin)
+        return if pin.is_a?(Sashite::Pin::Identifier)
+
+        raise Errors::Argument, Errors::Argument::Messages::INVALID_PIN
       end
     end
   end