sashite-qpi 1.0.0 → 2.1.0

data/README.md

@@ -1,17 +1,21 @@
-# Qpi.rb
+# qpi.rb
 
 [![Version](https://img.shields.io/github/v/tag/sashite/qpi.rb?label=Version&logo=github)](https://github.com/sashite/qpi.rb/tags)
 [![Yard documentation](https://img.shields.io/badge/Yard-documentation-blue.svg?logo=github)](https://rubydoc.info/github/sashite/qpi.rb/main)
-![Ruby](https://github.com/sashite/qpi.rb/actions/workflows/main.yml/badge.svg?branch=main)
-[![License](https://img.shields.io/github/license/sashite/qpi.rb?label=License&logo=github)](https://github.com/sashite/qpi.rb/raw/main/LICENSE.md)
+[![CI](https://github.com/sashite/qpi.rb/actions/workflows/ruby.yml/badge.svg?branch=main)](https://github.com/sashite/qpi.rb/actions)
+[![License](https://img.shields.io/github/license/sashite/qpi.rb?label=License&logo=github)](https://github.com/sashite/qpi.rb/raw/main/LICENSE)
 
-> **QPI** (Qualified Piece Identifier) implementation for the Ruby language.
+> **QPI** (Qualified Piece Identifier) implementation for Ruby.
 
-## What is QPI?
+## Overview
 
-QPI (Qualified Piece Identifier) provides a rule-agnostic format for identifying game pieces in abstract strategy board games by combining [Style Identifier Notation (SIN)](https://sashite.dev/specs/sin/1.0.0/) and [Piece Identifier Notation (PIN)](https://sashite.dev/specs/pin/1.0.0/) primitives with a colon separator.
+This library implements the [QPI Specification v1.0.0](https://sashite.dev/specs/qpi/1.0.0/).
 
-This gem implements the [QPI Specification v1.0.0](https://sashite.dev/specs/qpi/1.0.0/) exactly, providing complete piece identification with all four fundamental attributes: **Family**, **Type**, **Side**, and **State**.
+QPI provides complete piece identification by combining two primitive notations:
+- [SIN](https://sashite.dev/specs/sin/1.0.0/) (Style Identifier Notation) — identifies the piece style
+- [PIN](https://sashite.dev/specs/pin/1.0.0/) (Piece Identifier Notation) — identifies the piece attributes
+
+A QPI identifier is a **pair of (SIN, PIN)** that encodes complete **Piece Identity**.
 
 ## Installation
 
@@ -28,8 +32,6 @@ gem install sashite-qpi
 
 ## Dependencies
 
-QPI builds upon two foundational primitive specifications:
-
 ```ruby
 gem "sashite-sin"  # Style Identifier Notation
 gem "sashite-pin"  # Piece Identifier Notation
@@ -37,268 +39,316 @@ gem "sashite-pin"  # Piece Identifier Notation
 
 ## Usage
 
-### Basic Operations
+### Parsing (String → Identifier)
+
+Convert a QPI string into an `Identifier` object.
 
 ```ruby
 require "sashite/qpi"
 
-# Parse QPI strings
-identifier = Sashite::Qpi.parse("C:K")         # Chess king, first player
-identifier.to_s                                # => "C:K"
+# Standard parsing (raises on error)
+qpi = Sashite::Qpi.parse("C:K^")
+qpi.to_s  # => "C:K^"
+
+# Access the five Piece Identity attributes through components
+qpi.sin.style      # => :C (Piece Style)
+qpi.pin.type       # => :K (Piece Name)
+qpi.pin.side       # => :first (Piece Side)
+qpi.pin.state      # => :normal (Piece State)
+qpi.pin.terminal?  # => true (Terminal Status)
+
+# Components are full SIN and PIN instances
+qpi.sin.first_player?  # => true
+qpi.pin.enhanced?      # => false
+
+# Invalid input raises ArgumentError
+Sashite::Qpi.parse("invalid")  # => raises ArgumentError
+```
+
+### Formatting (Identifier → String)
+
+Convert an `Identifier` back to a QPI string.
+
+```ruby
+# From components
+sin = Sashite::Sin.parse("C")
+pin = Sashite::Pin.parse("K^")
+qpi = Sashite::Qpi::Identifier.new(sin, pin)
+qpi.to_s  # => "C:K^"
+
+# With attributes
+sin = Sashite::Sin.parse("s")
+pin = Sashite::Pin.parse("+r")
+qpi = Sashite::Qpi::Identifier.new(sin, pin)
+qpi.to_s  # => "s:+r"
+```
+
+### Validation
 
-# Create identifiers from parameters (strict validation)
-identifier = Sashite::Qpi.identifier(:C, :K, :first, :normal)
-identifier = Sashite::Qpi::Identifier.new(:S, :R, :first, :enhanced)
+```ruby
+# Boolean check
+Sashite::Qpi.valid?("C:K^")     # => true
+Sashite::Qpi.valid?("s:+r")     # => true
+Sashite::Qpi.valid?("invalid")  # => false
+Sashite::Qpi.valid?("C:")       # => false
+Sashite::Qpi.valid?(":K")       # => false
+```
 
-# Validate QPI strings
-Sashite::Qpi.valid?("C:K")                    # => true
-Sashite::Qpi.valid?("s:+p")                   # => true
-Sashite::Qpi.valid?("C:k")                    # => false (semantic mismatch)
+### Accessing Components
+
+```ruby
+qpi = Sashite::Qpi.parse("S:+R^")
+
+# Get components
+qpi.sin  # => #<Sashite::Sin::Identifier style=:S side=:first>
+qpi.pin  # => #<Sashite::Pin::Identifier type=:R state=:enhanced terminal=true>
+
+# Serialize components
+qpi.sin.to_s  # => "S"
+qpi.pin.to_s  # => "+R^"
+qpi.to_s      # => "S:+R^"
 ```
 
-### Strict Parameter Validation
+### Five Piece Identity Attributes
 
-**Important**: QPI enforces the same strict validation as its underlying SIN and PIN primitives:
+All attributes come directly from the components:
 
 ```ruby
-# ✓ Valid - uppercase symbols only for family and type parameters
-Sashite::Qpi.identifier(:C, :K, :first, :normal)   # => "C:K"
-Sashite::Qpi.identifier(:C, :K, :second, :normal)  # => "c:k"
+qpi = Sashite::Qpi.parse("S:+R^")
+
+# From SIN component
+qpi.sin.style  # => :S (Piece Style)
 
-# ✗ Invalid - lowercase symbols rejected with ArgumentError
-Sashite::Qpi.identifier(:c, :K, :first, :normal)   # => ArgumentError
-Sashite::Qpi.identifier(:C, :k, :first, :normal)   # => ArgumentError
+# From PIN component
+qpi.pin.type       # => :R (Piece Name)
+qpi.pin.side       # => :first (Piece Side)
+qpi.pin.state      # => :enhanced (Piece State)
+qpi.pin.terminal?  # => true (Terminal Status)
 ```
 
-**Key principle**: Input parameters must use uppercase symbols (`:A` to `:Z`). The `side` parameter determines the display case, not the input case.
+### Native and Derived Relationship
 
-### Attribute Access
+QPI defines a deterministic relationship based on case comparison between SIN and PIN letters.
 
 ```ruby
-identifier = Sashite::Qpi.parse("S:+R")
-
-# Four fundamental piece attributes
-identifier.family                             # => :S
-identifier.type                               # => :R
-identifier.side                               # => :first
-identifier.state                              # => :enhanced
-
-# Component extraction
-identifier.to_sin                             # => "S"
-identifier.to_pin                             # => "+R"
-identifier.sin_component                      # => #<Sashite::Sin::Identifier>
-identifier.pin_component                      # => #<Sashite::Pin::Identifier>
+qpi = Sashite::Qpi.parse("C:K^")
+
+# Access the relationship
+qpi.sin.side  # => :first (derived from SIN letter case)
+qpi.native?   # => true (sin.side == pin.side)
+qpi.derived?  # => false
+
+# Native: SIN case matches PIN case
+Sashite::Qpi.parse("C:K").native?   # => true (both uppercase/first)
+Sashite::Qpi.parse("c:k").native?   # => true (both lowercase/second)
+
+# Derived: SIN case differs from PIN case
+Sashite::Qpi.parse("C:k").derived?  # => true (uppercase vs lowercase)
+Sashite::Qpi.parse("c:K").derived?  # => true (lowercase vs uppercase)
 ```
 
 ### Transformations
 
+All transformations return new immutable instances.
+
 ```ruby
-# All transformations return new immutable instances
-identifier = Sashite::Qpi.parse("C:K")
+qpi = Sashite::Qpi.parse("C:K^")
 
-# State transformations
-enhanced = identifier.enhance                       # => "C:+K"
-diminished = identifier.diminish                    # => "C:-K"
-normalized = identifier.normalize                   # => "C:K"
+# Replace SIN component
+new_sin = Sashite::Sin.parse("S")
+qpi.with_sin(new_sin).to_s  # => "S:K^"
 
-# Attribute transformations
-different_type = identifier.with_type(:Q)           # => "C:Q"
-different_side = identifier.with_side(:second)      # => "c:k"
-different_state = identifier.with_state(:enhanced)  # => "C:+K"
-different_family = identifier.with_family(:S)       # => "S:K"
+# Replace PIN component
+new_pin = Sashite::Pin.parse("+Q^")
+qpi.with_pin(new_pin).to_s  # => "C:+Q^"
 
-# Player assignment flip
-flipped = identifier.flip # => "c:k"
+# Transform both
+qpi.with_sin(new_sin).with_pin(new_pin).to_s  # => "S:+Q^"
 
-# Chain transformations
-result = identifier.flip.enhance.with_type(:Q) # => "c:+q"
+# Flip both components (change player)
+qpi.flip.to_s  # => "c:k^"
+
+# Native/Derived transformations
+qpi = Sashite::Qpi.parse("C:r")
+qpi.native.to_s  # => "C:R" (PIN case aligned with SIN case)
+qpi.derive.to_s  # => "C:r" (already derived, unchanged)
+
+qpi = Sashite::Qpi.parse("C:R")
+qpi.native.to_s  # => "C:R" (already native, unchanged)
+qpi.derive.to_s  # => "C:r" (PIN case differs from SIN case)
 ```
 
-### State and Comparison Queries
+### Transform via Components
 
 ```ruby
-identifier = Sashite::Qpi.parse("S:+P")
-
-# State queries
-identifier.normal?                             # => false
-identifier.enhanced?                           # => true
-identifier.diminished?                         # => false
-identifier.first_player?                       # => true
-identifier.second_player?                      # => false
-
-# Comparison methods
-other = Sashite::Qpi.parse("C:+P")
-identifier.same_family?(other)                # => false (S vs C)
-identifier.same_type?(other)                  # => true (both P)
-identifier.same_side?(other)                  # => true (both first player)
-identifier.same_state?(other)                 # => true (both enhanced)
-identifier.cross_family?(other)               # => true (different families)
-```
+qpi = Sashite::Qpi.parse("C:K^")
 
-## API Reference
+# Transform SIN via component
+qpi.with_sin(qpi.sin.with_style(:S)).to_s  # => "S:K^"
 
-### Main Module Methods
-
-- `Sashite::Qpi.parse(qpi_string)` - Parse QPI string into Identifier object
-- `Sashite::Qpi.identifier(family, type, side, state = :normal)` - Create identifier from parameters (strict validation)
-- `Sashite::Qpi.valid?(qpi_string)` - Check if string is valid QPI notation
-
-### Identifier Class
-
-#### Creation and Parsing
-- `Sashite::Qpi::Identifier.new(family, type, side, state = :normal)` - Create from parameters (strict validation)
-- `Sashite::Qpi::Identifier.parse(qpi_string)` - Parse QPI string
-
-#### Parameter Validation
-**Strict validation enforced**:
-- `family` parameter: Must be symbol `:A` to `:Z` (uppercase only)
-- `type` parameter: Must be symbol `:A` to `:Z` (uppercase only)
-- `side` parameter: Must be `:first` or `:second`
-- `state` parameter: Must be `:normal`, `:enhanced`, or `:diminished`
-
-#### Attribute Access
-- `#family` - Get style family (symbol `:A` to `:Z`)
-- `#type` - Get piece type (symbol `:A` to `:Z`)
-- `#side` - Get player side (`:first` or `:second`)
-- `#state` - Get piece state (`:normal`, `:enhanced`, or `:diminished`)
-- `#to_s` - Convert to QPI string representation
-
-#### Component Access
-- `#to_sin` - Get SIN string representation
-- `#to_pin` - Get PIN string representation
-- `#sin_component` - Get SIN identifier object
-- `#pin_component` - Get PIN identifier object
-
-#### State Queries
-- `#normal?` - Check if normal state
-- `#enhanced?` - Check if enhanced state
-- `#diminished?` - Check if diminished state
-- `#first_player?` - Check if first player
-- `#second_player?` - Check if second player
-
-#### Transformations (immutable - return new instances)
-- `#enhance` - Create enhanced version
-- `#diminish` - Create diminished version
-- `#normalize` - Remove state modifiers
-- `#with_type(new_type)` - Change piece type
-- `#with_side(new_side)` - Change player side
-- `#with_state(new_state)` - Change piece state
-- `#with_family(new_family)` - Change style family
-- `#flip` - Switch player assignment for both components
-
-#### Comparison Methods
-- `#same_family?(other)` - Check if same style family
-- `#same_type?(other)` - Check if same piece type
-- `#same_side?(other)` - Check if same player side
-- `#same_state?(other)` - Check if same piece state
-- `#cross_family?(other)` - Check if different style families
-- `#==(other)` - Full equality comparison
-
-## Format Specification
-
-### Structure
-```
-<sin>:<pin>
-```
+# Transform PIN via component
+qpi.with_pin(qpi.pin.with_type(:Q)).to_s          # => "C:Q^"
+qpi.with_pin(qpi.pin.with_state(:enhanced)).to_s  # => "C:+K^"
+qpi.with_pin(qpi.pin.with_terminal(false)).to_s   # => "C:K"
 
-### Grammar (BNF)
-```bnf
-<qpi> ::= <uppercase-qpi> | <lowercase-qpi>
-<uppercase-qpi> ::= <uppercase-letter> ":" <uppercase-pin>
-<lowercase-qpi> ::= <lowercase-letter> ":" <lowercase-pin>
-<uppercase-pin> ::= ["+" | "-"] <uppercase-letter>
-<lowercase-pin> ::= ["+" | "-"] <lowercase-letter>
+# Chain transformations
+qpi.flip.with_sin(qpi.sin.with_style(:S)).to_s  # => "s:k^"
 ```
 
-### Regular Expression
+### Component Queries
+
+Since QPI is a composition, use the component APIs directly:
+
 ```ruby
-/\A([A-Z]:[-+]?[A-Z]|[a-z]:[-+]?[a-z])\z/
+qpi = Sashite::Qpi.parse("S:+P^")
+
+# SIN queries (style and side)
+qpi.sin.style          # => :S
+qpi.sin.side           # => :first
+qpi.sin.first_player?  # => true
+qpi.sin.letter         # => "S"
+
+# PIN queries (type, state, terminal)
+qpi.pin.type       # => :P
+qpi.pin.state      # => :enhanced
+qpi.pin.terminal?  # => true
+qpi.pin.enhanced?  # => true
+qpi.pin.letter     # => "P"
+qpi.pin.prefix     # => "+"
+qpi.pin.suffix     # => "^"
+
+# Compare QPIs via components
+other = Sashite::Qpi.parse("C:+P^")
+qpi.sin.same_style?(other.sin)  # => false (S vs C)
+qpi.pin.same_type?(other.pin)   # => true (both P)
+qpi.sin.same_side?(other.sin)   # => true (both first)
+qpi.pin.same_state?(other.pin)  # => true (both enhanced)
 ```
 
-### Examples
+## API Reference
 
-- `C:K` - Chess-style king, first player
-- `c:k` - Chess-style king, second player
-- `S:+R` - Shogi-style enhanced rook, first player
-- `x:-s` - Xiangqi-style diminished soldier, second player
+### Types
 
-## Semantic Consistency
+```ruby
+# Identifier represents a parsed QPI with complete Piece Identity.
+class Sashite::Qpi::Identifier
+  # Creates an Identifier from SIN and PIN components.
+  # Raises ArgumentError if components are invalid.
+  #
+  # @param sin [Sashite::Sin::Identifier] Style component
+  # @param pin [Sashite::Pin::Identifier] Piece component
+  # @return [Identifier]
+  def initialize(sin, pin)
+
+  # Returns the SIN component.
+  #
+  # @return [Sashite::Sin::Identifier]
+  def sin
+
+  # Returns the PIN component.
+  #
+  # @return [Sashite::Pin::Identifier]
+  def pin
+
+  # Returns true if sin.side equals pin.side (Native relationship).
+  #
+  # @return [Boolean]
+  def native?
+
+  # Returns true if sin.side differs from pin.side (Derived relationship).
+  #
+  # @return [Boolean]
+  def derived?
+
+  # Returns the QPI string representation.
+  #
+  # @return [String]
+  def to_s
+end
+```
 
-QPI enforces semantic consistency: the style and piece components must represent the same player. Both components use case to indicate player assignment, and these must align.
+### Parsing
 
-**Valid combinations:**
 ```ruby
-Sashite::Qpi.valid?("C:K")    # => true (both first player)
-Sashite::Qpi.valid?("c:k")    # => true (both second player)
+# Parses a QPI string into an Identifier.
+# Raises ArgumentError if the string is not valid.
+#
+# @param string [String] QPI string
+# @return [Identifier]
+# @raise [ArgumentError] if invalid
+def Sashite::Qpi.parse(string)
 ```
 
-**Invalid combinations:**
+### Validation
+
 ```ruby
-Sashite::Qpi.valid?("C:k")    # => false (family=first, piece=second)
-Sashite::Qpi.valid?("c:K")    # => false (family=second, piece=first)
+# Reports whether string is a valid QPI.
+#
+# @param string [String] QPI string
+# @return [Boolean]
+def Sashite::Qpi.valid?(string)
 ```
 
-## Parameter Validation
+### Transformations
 
-### Strict Validation Rules
+```ruby
+# Component replacement (return new Identifier)
+def with_sin(new_sin)  # => Identifier with different SIN
+def with_pin(new_pin)  # => Identifier with different PIN
 
-QPI enforces strict parameter validation consistent with its underlying SIN and PIN primitives:
+# Flip transformation (transforms both components)
+def flip  # => Identifier with both SIN and PIN flipped
 
-```ruby
-# ✓ Valid parameter examples
-Sashite::Qpi.identifier(:C, :K, :first, :normal)     # All uppercase symbols
-Sashite::Qpi.identifier(:S, :R, :second, :enhanced)  # Display case determined by side
-
-# ✗ Invalid parameter examples (raise ArgumentError)
-Sashite::Qpi.identifier(:c, :K, :first, :normal)     # Lowercase family rejected
-Sashite::Qpi.identifier(:C, :k, :first, :normal)     # Lowercase type rejected
-Sashite::Qpi.identifier("C", :K, :first, :normal)    # String family rejected
-Sashite::Qpi.identifier(:C, "K", :first, :normal)    # String type rejected
+# Native/Derived transformations
+def native  # => Identifier with PIN case aligned to SIN case
+def derive  # => Identifier with PIN case opposite to SIN case
 ```
 
-### Error Handling
+### Errors
 
-QPI delegates validation to its underlying primitives, ensuring consistent error messages:
+All parsing and validation errors raise `ArgumentError` with descriptive messages:
 
-```ruby
-begin
-  Sashite::Qpi.identifier(:c, :K, :first, :normal)
-rescue ArgumentError => e
-  # Same error message as Sashite::Sin::Identifier.new(:c, :first)
-  puts e.message # => "Family must be a symbol from :A to :Z representing Style Family, got: :c"
-end
+| Message | Cause |
+|---------|-------|
+| `"empty input"` | String length is 0 |
+| `"missing colon separator"` | No `:` found in string |
+| `"missing SIN component"` | Nothing before `:` |
+| `"missing PIN component"` | Nothing after `:` |
+| `"invalid SIN component: ..."` | SIN parsing failed |
+| `"invalid PIN component: ..."` | PIN parsing failed |
 
-begin
-  Sashite::Qpi.identifier(:C, :k, :first, :normal)
-rescue ArgumentError => e
-  # Same error message as Sashite::Pin::Identifier.new(:k, :first, :normal)
-  puts e.message # => "Type must be a symbol from :A to :Z, got: :k"
-end
-```
+## Piece Identity Mapping
 
-## Design Properties
+QPI encodes complete **Piece Identity** as defined in the [Glossary](https://sashite.dev/glossary/):
 
-- **Rule-agnostic**: Independent of specific game mechanics
-- **Complete identification**: All four piece attributes represented
-- **Cross-style support**: Enables multi-tradition gaming
-- **Semantic validation**: Ensures component consistency
-- **Primitive foundation**: Built from SIN and PIN specifications
-- **Strict validation**: Consistent parameter validation with underlying primitives
-- **Immutable**: All instances frozen, transformations return new objects
-- **Functional**: Pure functions with no side effects
+| Piece Attribute     | QPI Access           | Encoding                                               |
+|---------------------|----------------------|--------------------------------------------------------|
+| **Piece Style**     | `qpi.sin.style`      | SIN letter (case-insensitive identity)                 |
+| **Piece Name**      | `qpi.pin.type`       | PIN letter (case-insensitive identity)                 |
+| **Piece Side**      | `qpi.pin.side`       | PIN letter case (uppercase = first, lowercase = second)|
+| **Piece State**     | `qpi.pin.state`      | PIN modifier (`+` = enhanced, `-` = diminished)        |
+| **Terminal Status** | `qpi.pin.terminal?`  | PIN marker (`^` = terminal)                            |
 
-## Related Specifications
+Additionally, QPI provides a **Native/Derived relationship** via `native?`, `derived?`, `native`, and `derive`.
 
-- [QPI Specification v1.0.0](https://sashite.dev/specs/qpi/1.0.0/) - Complete technical specification
-- [QPI Examples](https://sashite.dev/specs/qpi/1.0.0/examples/) - Practical implementation examples
-- [SIN Specification v1.0.0](https://sashite.dev/specs/sin/1.0.0/) - Style identification component
-- [PIN Specification v1.0.0](https://sashite.dev/specs/pin/1.0.0/) - Piece identification component
-- [Sashité Protocol](https://sashite.dev/protocol/) - Conceptual foundation
+## Design Principles
 
-## License
+- **Pure composition**: QPI composes SIN and PIN without reimplementing features
+- **Minimal API**: Core methods (`sin`, `pin`, `native?`, `derived?`, `native`, `derive`, `to_s`) plus transformations
+- **Component transparency**: Access components directly, no wrapper methods
+- **QPI-specific conveniences**: `flip`, `native`, `derive` (operations that span both components)
+- **Immutable identifiers**: Frozen instances prevent mutation
+- **Ruby idioms**: `valid?` predicate, `to_s` conversion, `ArgumentError` for invalid input
+- **No duplication**: Delegates to `sashite-sin` and `sashite-pin`
 
-Available as open source under the [MIT License](https://opensource.org/licenses/MIT).
+## Related Specifications
+
+- [Game Protocol](https://sashite.dev/game-protocol/) — Conceptual foundation
+- [QPI Specification](https://sashite.dev/specs/qpi/1.0.0/) — Official specification
+- [QPI Examples](https://sashite.dev/specs/qpi/1.0.0/examples/) — Usage examples
+- [SIN Specification](https://sashite.dev/specs/sin/1.0.0/) — Style component
+- [PIN Specification](https://sashite.dev/specs/pin/1.0.0/) — Piece component
 
-## About
+## License
 
-Maintained by [Sashité](https://sashite.com/) — promoting chess variants and sharing the beauty of board game cultures.
+Available as open source under the [Apache License 2.0](https://opensource.org/licenses/Apache-2.0).

data/lib/sashite/qpi/constants.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Sashite
+  module Qpi
+    # Constants for QPI (Qualified Piece Identifier).
+    #
+    # This module defines the structural constants for QPI tokens.
+    module Constants
+      # Separator between SIN and PIN components.
+      SEPARATOR = ":"
+    end
+  end
+end

data/lib/sashite/qpi/errors/argument/messages.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Sashite
+  module Qpi
+    module Errors
+      class Argument < ::ArgumentError
+        # Centralized error messages for QPI parsing and validation.
+        #
+        # @example
+        #   raise Errors::Argument, Messages::EMPTY_INPUT
+        module Messages
+          # Parsing errors
+          EMPTY_INPUT = "empty input"
+          MISSING_SEPARATOR = "missing colon separator"
+          MISSING_SIN = "missing SIN component"
+          MISSING_PIN = "missing PIN component"
+          INVALID_SIN = "invalid SIN component"
+          INVALID_PIN = "invalid PIN component"
+        end
+      end
+    end
+  end
+end

data/lib/sashite/qpi/errors/argument.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative "argument/messages"
+
+module Sashite
+  module Qpi
+    module Errors
+      # Error raised when QPI parsing or validation fails.
+      #
+      # @example
+      #   raise Argument, Argument::Messages::EMPTY_INPUT
+      class Argument < ::ArgumentError
+      end
+    end
+  end
+end

data/lib/sashite/qpi/errors.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "errors/argument"