sashite-pcn 0.1.0

data/lib/sashite/pcn/game.rb

@@ -0,0 +1,436 @@
+# frozen_string_literal: true
+
+module Sashite
+  module Pcn
+    # Immutable representation of a complete game record.
+    #
+    # A Game consists of:
+    # - setup: Initial position (FEEN format) [required]
+    # - moves: Sequence of moves (PMN format) [required]
+    # - status: Game status [optional]
+    # - meta: Metadata [optional]
+    # - sides: Player information [optional]
+    #
+    # @see https://sashite.dev/specs/pcn/1.0.0/
+    class Game
+      # Valid status values according to PCN specification.
+      VALID_STATUSES = %w[
+        in_progress
+        checkmate
+        stalemate
+        bare_king
+        mare_king
+        resignation
+        illegal_move
+        time_limit
+        move_limit
+        repetition
+        mutual_agreement
+      ].freeze
+
+      # @return [Feen::Position] Initial position
+      attr_reader :setup
+
+      # @return [Array<Pmn::Move>] Move sequence
+      attr_reader :moves
+
+      # @return [String, nil] Game status
+      attr_reader :status
+
+      # @return [Meta, nil] Metadata
+      attr_reader :meta
+
+      # @return [Sides, nil] Player information
+      attr_reader :sides
+
+      # Parse a PCN hash into a Game object.
+      #
+      # @param hash [Hash] PCN document hash
+      # @return [Game] Immutable game object
+      # @raise [Error::Parse] If structure is invalid
+      # @raise [Error::Validation] If format is invalid
+      #
+      # @example
+      #   game = Game.parse({
+      #     "setup" => "8/8/8/8/8/8/8/8 / C/c",
+      #     "moves" => []
+      #   })
+      def self.parse(hash)
+        validate_structure!(hash)
+
+        setup = parse_setup(hash["setup"])
+        moves = parse_moves(hash["moves"])
+        status = hash["status"]
+        meta = parse_meta(hash["meta"])
+        sides = parse_sides(hash["sides"])
+
+        new(
+          setup:  setup,
+          moves:  moves,
+          status: status,
+          meta:   meta,
+          sides:  sides
+        )
+      end
+
+      # Validate a PCN hash without raising exceptions.
+      #
+      # @param hash [Hash] PCN document hash
+      # @return [Boolean] true if valid, false otherwise
+      #
+      # @example
+      #   Game.valid?({ "setup" => "...", "moves" => [] })  # => true
+      def self.valid?(hash)
+        parse(hash)
+        true
+      rescue Error
+        false
+      end
+
+      # Create a new Game.
+      #
+      # @param setup [Feen::Position, String] Initial position
+      # @param moves [Array<Pmn::Move, Array>] Move sequence
+      # @param status [String, nil] Game status
+      # @param meta [Meta, Hash, nil] Metadata
+      # @param sides [Sides, Hash, nil] Player information
+      # @raise [Error::Validation] If validation fails
+      #
+      # @example
+      #   game = Game.new(
+      #     setup: Feen.parse("8/8/8/8/8/8/8/8 / C/c"),
+      #     moves: []
+      #   )
+      def initialize(setup:, moves:, status: nil, meta: nil, sides: nil)
+        @setup = normalize_setup(setup)
+        @moves = normalize_moves(moves)
+        @status = normalize_status(status)
+        @meta = normalize_meta(meta)
+        @sides = normalize_sides(sides)
+
+        validate!
+
+        freeze
+      end
+
+      # Check if the game is valid.
+      #
+      # @return [Boolean] true if valid
+      def valid?
+        validate!
+        true
+      rescue Error
+        false
+      end
+
+      # Get the number of moves.
+      #
+      # @return [Integer] Move count
+      def move_count
+        moves.size
+      end
+      alias size move_count
+      alias length move_count
+
+      # Check if no moves have been played.
+      #
+      # @return [Boolean] true if no moves
+      def empty?
+        moves.empty?
+      end
+
+      # Check if status is present.
+      #
+      # @return [Boolean] true if status field exists
+      def has_status?
+        !status.nil?
+      end
+
+      # Check if metadata is present.
+      #
+      # @return [Boolean] true if meta field exists
+      def has_meta?
+        !meta.nil?
+      end
+
+      # Check if player information is present.
+      #
+      # @return [Boolean] true if sides field exists
+      def has_sides?
+        !sides.nil?
+      end
+
+      # Add a move to the game.
+      #
+      # @param move [Pmn::Move, Array] Move to add
+      # @return [Game] New game with added move
+      #
+      # @example
+      #   new_game = game.add_move(["e2", "e4", "C:P"])
+      def add_move(move)
+        normalized_move = move.is_a?(::Sashite::Pmn::Move) ? move : ::Sashite::Pmn.parse(move)
+
+        self.class.new(
+          setup:  setup,
+          moves:  moves + [normalized_move],
+          status: status,
+          meta:   meta,
+          sides:  sides
+        )
+      end
+
+      # Update the game status.
+      #
+      # @param new_status [String, nil] New status value
+      # @return [Game] New game with updated status
+      #
+      # @example
+      #   finished = game.with_status("checkmate")
+      def with_status(new_status)
+        self.class.new(
+          setup:  setup,
+          moves:  moves,
+          status: new_status,
+          meta:   meta,
+          sides:  sides
+        )
+      end
+
+      # Update the metadata.
+      #
+      # @param new_meta [Meta, Hash, nil] New metadata
+      # @return [Game] New game with updated metadata
+      #
+      # @example
+      #   updated = game.with_meta(Meta.new(event: "Tournament"))
+      def with_meta(new_meta)
+        self.class.new(
+          setup:  setup,
+          moves:  moves,
+          status: status,
+          meta:   new_meta,
+          sides:  sides
+        )
+      end
+
+      # Update the player information.
+      #
+      # @param new_sides [Sides, Hash, nil] New player information
+      # @return [Game] New game with updated sides
+      #
+      # @example
+      #   updated = game.with_sides(Sides.new(first: player1, second: player2))
+      def with_sides(new_sides)
+        self.class.new(
+          setup:  setup,
+          moves:  moves,
+          status: status,
+          meta:   meta,
+          sides:  new_sides
+        )
+      end
+
+      # Convert to hash representation.
+      #
+      # @return [Hash] PCN document hash
+      #
+      # @example
+      #   game.to_h  # => { "setup" => "...", "moves" => [...], ... }
+      def to_h
+        hash = {
+          "setup" => setup.to_s,
+          "moves" => moves.map(&:to_a)
+        }
+
+        hash["status"] = status if has_status?
+        hash["meta"] = meta.to_h if has_meta?
+        hash["sides"] = sides.to_h if has_sides?
+
+        hash
+      end
+
+      # String representation.
+      #
+      # @return [String] Inspectable representation
+      def to_s
+        "#<#{self.class} setup=#{setup.to_s.inspect} moves=#{moves.size} status=#{status.inspect}>"
+      end
+      alias inspect to_s
+
+      # Equality comparison.
+      #
+      # @param other [Game] Other game
+      # @return [Boolean] true if equal
+      def ==(other)
+        other.is_a?(self.class) &&
+          other.setup == setup &&
+          other.moves == moves &&
+          other.status == status &&
+          other.meta == meta &&
+          other.sides == sides
+      end
+      alias eql? ==
+
+      # Hash code for equality.
+      #
+      # @return [Integer] Hash code
+      def hash
+        [self.class, setup, moves, status, meta, sides].hash
+      end
+
+      private
+
+      # Validate PCN hash structure.
+      def self.validate_structure!(hash)
+        raise Error::Parse, "PCN document must be a Hash, got #{hash.class}" unless hash.is_a?(::Hash)
+
+        raise Error::Parse, "Missing required field 'setup'" unless hash.key?("setup")
+
+        raise Error::Parse, "Missing required field 'moves'" unless hash.key?("moves")
+
+        return if hash["moves"].is_a?(::Array)
+
+        raise Error::Parse, "'moves' must be an Array, got #{hash['moves'].class}"
+      end
+
+      # Parse setup field.
+      def self.parse_setup(value)
+        ::Sashite::Feen.parse(value)
+      rescue ::Sashite::Feen::Error => e
+        raise Error::Validation, "Invalid setup: #{e.message}"
+      end
+
+      # Parse moves field.
+      def self.parse_moves(array)
+        array.map.with_index do |move_array, index|
+          ::Sashite::Pmn.parse(move_array)
+        rescue ::Sashite::Pmn::Error => e
+          raise Error::Validation, "Invalid move at index #{index}: #{e.message}"
+        end
+      end
+
+      # Parse meta field.
+      def self.parse_meta(value)
+        return nil if value.nil?
+
+        Meta.parse(value)
+      rescue Error => e
+        raise Error::Validation, "Invalid meta: #{e.message}"
+      end
+
+      # Parse sides field.
+      def self.parse_sides(value)
+        return nil if value.nil?
+
+        Sides.parse(value)
+      rescue Error => e
+        raise Error::Validation, "Invalid sides: #{e.message}"
+      end
+
+      # Normalize setup to Position object.
+      def normalize_setup(value)
+        return value if value.is_a?(::Sashite::Feen::Position)
+
+        ::Sashite::Feen.parse(value)
+      rescue ::Sashite::Feen::Error => e
+        raise Error::Validation, "Invalid setup: #{e.message}"
+      end
+
+      # Normalize moves to array of Move objects.
+      def normalize_moves(value)
+        raise Error::Validation, "Moves must be an Array, got #{value.class}" unless value.is_a?(::Array)
+
+        value.map.with_index do |move, index|
+          next move if move.is_a?(::Sashite::Pmn::Move)
+
+          ::Sashite::Pmn.parse(move)
+        rescue ::Sashite::Pmn::Error => e
+          raise Error::Validation, "Invalid move at index #{index}: #{e.message}"
+        end
+      end
+
+      # Normalize status.
+      def normalize_status(value)
+        return nil if value.nil?
+
+        raise Error::Validation, "Status must be a String, got #{value.class}" unless value.is_a?(::String)
+
+        value
+      end
+
+      # Normalize meta.
+      def normalize_meta(value)
+        return nil if value.nil?
+        return value if value.is_a?(Meta)
+
+        Meta.parse(value)
+      end
+
+      # Normalize sides.
+      def normalize_sides(value)
+        return nil if value.nil?
+        return value if value.is_a?(Sides)
+
+        Sides.parse(value)
+      end
+
+      # Validate all fields.
+      def validate!
+        validate_setup!
+        validate_moves!
+        validate_status!
+        validate_meta!
+        validate_sides!
+      end
+
+      # Validate setup field.
+      def validate_setup!
+        return if setup.is_a?(::Sashite::Feen::Position)
+
+        raise Error::Validation, "Setup must be a Feen::Position"
+      end
+
+      # Validate moves field.
+      def validate_moves!
+        raise Error::Validation, "Moves must be an Array" unless moves.is_a?(::Array)
+
+        moves.each_with_index do |move, index|
+          raise Error::Validation, "Move at index #{index} must be a Pmn::Move" unless move.is_a?(::Sashite::Pmn::Move)
+        end
+      end
+
+      # Validate status field.
+      def validate_status!
+        return if status.nil?
+
+        raise Error::Validation, "Status must be a String, got #{status.class}" unless status.is_a?(::String)
+
+        return if VALID_STATUSES.include?(status)
+
+        raise Error::Validation, "Invalid status value: #{status.inspect}"
+      end
+
+      # Validate meta field.
+      def validate_meta!
+        return if meta.nil?
+
+        raise Error::Validation, "Meta must be a Meta object" unless meta.is_a?(Meta)
+
+        return if meta.valid?
+
+        raise Error::Validation, "Meta validation failed"
+      end
+
+      # Validate sides field.
+      def validate_sides!
+        return if sides.nil?
+
+        raise Error::Validation, "Sides must be a Sides object" unless sides.is_a?(Sides)
+
+        return if sides.valid?
+
+        raise Error::Validation, "Sides validation failed"
+      end
+    end
+  end
+end

data/lib/sashite/pcn/meta.rb

@@ -0,0 +1,275 @@
+# frozen_string_literal: true
+
+module Sashite
+  module Pcn
+    # Immutable representation of game metadata.
+    #
+    # All fields are optional. Metadata provides contextual information
+    # about the game session.
+    #
+    # @see https://sashite.dev/specs/pcn/1.0.0/
+    class Meta
+      # ISO 8601 date format: YYYY-MM-DD
+      DATE_PATTERN = /\A\d{4}-\d{2}-\d{2}\z/
+
+      # ISO 8601 datetime format with UTC timezone: YYYY-MM-DDTHH:MM:SSZ
+      DATETIME_PATTERN = /\A\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z\z/
+
+      # Absolute URL pattern (http:// or https://)
+      URL_PATTERN = %r{\Ahttps?://.+\z}
+
+      # @return [String, nil] Game name or opening identification
+      attr_reader :name
+
+      # @return [String, nil] Tournament or event name
+      attr_reader :event
+
+      # @return [String, nil] Physical or virtual venue
+      attr_reader :location
+
+      # @return [Integer, nil] Round number in tournament context
+      attr_reader :round
+
+      # @return [String, nil] Game start date (ISO 8601: YYYY-MM-DD)
+      attr_reader :started_on
+
+      # @return [String, nil] Game completion timestamp (ISO 8601 UTC: YYYY-MM-DDTHH:MM:SSZ)
+      attr_reader :finished_at
+
+      # @return [String, nil] Reference link to external resource
+      attr_reader :href
+
+      # Parse a meta hash into a Meta object.
+      #
+      # @param hash [Hash] Metadata hash
+      # @return [Meta] Immutable meta object
+      # @raise [Error::Validation] If validation fails
+      #
+      # @example
+      #   meta = Meta.parse({
+      #     "event" => "World Championship",
+      #     "round" => 5
+      #   })
+      def self.parse(hash)
+        raise Error::Validation, "Meta must be a Hash, got #{hash.class}" unless hash.is_a?(::Hash)
+
+        new(
+          name:        hash["name"],
+          event:       hash["event"],
+          location:    hash["location"],
+          round:       hash["round"],
+          started_on:  hash["started_on"],
+          finished_at: hash["finished_at"],
+          href:        hash["href"]
+        )
+      end
+
+      # Validate a meta hash without raising exceptions.
+      #
+      # @param hash [Hash] Metadata hash
+      # @return [Boolean] true if valid, false otherwise
+      #
+      # @example
+      #   Meta.valid?({ "event" => "Tournament" })  # => true
+      def self.valid?(hash)
+        parse(hash)
+        true
+      rescue Error
+        false
+      end
+
+      # Create a new Meta.
+      #
+      # @param name [String, nil] Game name
+      # @param event [String, nil] Event name
+      # @param location [String, nil] Location
+      # @param round [Integer, nil] Round number
+      # @param started_on [String, nil] Start date (YYYY-MM-DD)
+      # @param finished_at [String, nil] Finish timestamp (YYYY-MM-DDTHH:MM:SSZ)
+      # @param href [String, nil] Reference URL
+      # @raise [Error::Validation] If validation fails
+      #
+      # @example
+      #   meta = Meta.new(
+      #     event: "World Championship",
+      #     round: 5,
+      #     started_on: "2025-11-15"
+      #   )
+      def initialize(name: nil, event: nil, location: nil, round: nil, started_on: nil, finished_at: nil, href: nil)
+        @name = name
+        @event = event
+        @location = location
+        @round = round
+        @started_on = started_on
+        @finished_at = finished_at
+        @href = href
+
+        validate!
+
+        freeze
+      end
+
+      # Check if the meta is valid.
+      #
+      # @return [Boolean] true if valid
+      def valid?
+        validate!
+        true
+      rescue Error
+        false
+      end
+
+      # Check if metadata is empty (all fields nil).
+      #
+      # @return [Boolean] true if all fields are nil
+      def empty?
+        name.nil? && event.nil? && location.nil? && round.nil? &&
+          started_on.nil? && finished_at.nil? && href.nil?
+      end
+
+      # Convert to hash representation.
+      #
+      # @return [Hash] Metadata hash (excludes nil values)
+      #
+      # @example
+      #   meta.to_h  # => { "event" => "Tournament", "round" => 5 }
+      def to_h
+        hash = {}
+
+        hash["name"] = name unless name.nil?
+        hash["event"] = event unless event.nil?
+        hash["location"] = location unless location.nil?
+        hash["round"] = round unless round.nil?
+        hash["started_on"] = started_on unless started_on.nil?
+        hash["finished_at"] = finished_at unless finished_at.nil?
+        hash["href"] = href unless href.nil?
+
+        hash
+      end
+
+      # String representation.
+      #
+      # @return [String] Inspectable representation
+      def to_s
+        fields = []
+        fields << "event=#{event.inspect}" unless event.nil?
+        fields << "round=#{round}" unless round.nil?
+        fields << "location=#{location.inspect}" unless location.nil?
+
+        "#<#{self.class} #{fields.join(' ')}>"
+      end
+      alias inspect to_s
+
+      # Equality comparison.
+      #
+      # @param other [Meta] Other meta
+      # @return [Boolean] true if equal
+      def ==(other)
+        other.is_a?(self.class) &&
+          other.name == name &&
+          other.event == event &&
+          other.location == location &&
+          other.round == round &&
+          other.started_on == started_on &&
+          other.finished_at == finished_at &&
+          other.href == href
+      end
+      alias eql? ==
+
+      # Hash code for equality.
+      #
+      # @return [Integer] Hash code
+      def hash
+        [self.class, name, event, location, round, started_on, finished_at, href].hash
+      end
+
+      private
+
+      # Validate all fields.
+      def validate!
+        validate_name!
+        validate_event!
+        validate_location!
+        validate_round!
+        validate_started_on!
+        validate_finished_at!
+        validate_href!
+      end
+
+      # Validate name field.
+      def validate_name!
+        return if name.nil?
+
+        return if name.is_a?(::String)
+
+        raise Error::Validation, "Meta 'name' must be a String, got #{name.class}"
+      end
+
+      # Validate event field.
+      def validate_event!
+        return if event.nil?
+
+        return if event.is_a?(::String)
+
+        raise Error::Validation, "Meta 'event' must be a String, got #{event.class}"
+      end
+
+      # Validate location field.
+      def validate_location!
+        return if location.nil?
+
+        return if location.is_a?(::String)
+
+        raise Error::Validation, "Meta 'location' must be a String, got #{location.class}"
+      end
+
+      # Validate round field.
+      def validate_round!
+        return if round.nil?
+
+        raise Error::Validation, "Meta 'round' must be an Integer, got #{round.class}" unless round.is_a?(::Integer)
+
+        return unless round < 1
+
+        raise Error::Validation, "Meta 'round' must be >= 1, got #{round}"
+      end
+
+      # Validate started_on field.
+      def validate_started_on!
+        return if started_on.nil?
+
+        unless started_on.is_a?(::String)
+          raise Error::Validation, "Meta 'started_on' must be a String, got #{started_on.class}"
+        end
+
+        return if DATE_PATTERN.match?(started_on)
+
+        raise Error::Validation, "Meta 'started_on' must match format YYYY-MM-DD, got #{started_on.inspect}"
+      end
+
+      # Validate finished_at field.
+      def validate_finished_at!
+        return if finished_at.nil?
+
+        unless finished_at.is_a?(::String)
+          raise Error::Validation, "Meta 'finished_at' must be a String, got #{finished_at.class}"
+        end
+
+        return if DATETIME_PATTERN.match?(finished_at)
+
+        raise Error::Validation, "Meta 'finished_at' must match format YYYY-MM-DDTHH:MM:SSZ, got #{finished_at.inspect}"
+      end
+
+      # Validate href field.
+      def validate_href!
+        return if href.nil?
+
+        raise Error::Validation, "Meta 'href' must be a String, got #{href.class}" unless href.is_a?(::String)
+
+        return if URL_PATTERN.match?(href)
+
+        raise Error::Validation, "Meta 'href' must be an absolute URL (http:// or https://), got #{href.inspect}"
+      end
+    end
+  end
+end