pgn2 2.0.0 → 2.0.1

data/lib/pgn/pgn_parser.rb

@@ -8,7 +8,7 @@ require 'racc/parser.rb'
 module PGN
   class PgnParser < Racc::Parser
 
-module_eval(<<'...end pgn_parser.y/module_eval...', 'pgn_parser.y', 97)
+module_eval(<<'...end pgn_parser.y/module_eval...', 'pgn_parser.y', 96)
 
   def parse(input)
     @lexer = PGN::Lexer.new(input)
@@ -71,37 +71,37 @@ racc_action_table = [
     21,    25,    31 ]
 
 racc_action_check = [
-     1,    28,     2,    28,    17,    28,     5,    17,     6,     1,
-    28,     9,     9,     9,    24,     9,    11,    24,    15,    18,
-    20,    23,    29 ]
+     1,    28,     2,    28,    17,    28,     4,    17,     6,     1,
+    28,    10,    10,    10,    24,    10,    11,    24,    15,    18,
+    19,    23,    29 ]
 
 racc_action_pointer = [
-   nil,     0,     2,   nil,   nil,    -3,     0,   nil,   nil,     8,
-   nil,    14,   nil,   nil,   nil,     7,   nil,     1,     9,   nil,
-     9,   nil,   nil,    15,    11,   nil,   nil,   nil,    -2,    16,
+   nil,     0,     2,   nil,    -3,   nil,     0,   nil,   nil,   nil,
+     8,    14,   nil,   nil,   nil,     7,   nil,     1,     9,     9,
+   nil,   nil,   nil,    15,    11,   nil,   nil,   nil,    -2,    16,
    nil,   nil,   nil ]
 
 racc_action_default = [
-    -1,   -25,   -25,    -2,    -8,    -4,   -25,    33,    -3,   -25,
-    -5,   -25,    -7,    -9,   -10,   -11,   -13,   -14,   -25,   -12,
+    -1,   -25,   -25,    -2,    -8,    -4,   -25,    33,    -3,    -5,
+   -25,   -25,    -7,    -9,   -10,   -11,   -13,   -14,   -25,   -12,
    -22,    -8,   -15,   -16,   -17,   -20,    -6,   -23,   -25,   -19,
    -18,   -21,   -24 ]
 
 racc_goto_table = [
-     9,    24,     4,    19,     1,     3,    10,    29,    27,     8,
-    22,   nil,   nil,   nil,   nil,   nil,   nil,    28 ]
+    10,    24,    20,     1,     3,     5,    27,    29,     9,     4,
+     8,    19,    22,   nil,   nil,   nil,   nil,    28 ]
 
 racc_goto_check = [
-     6,    11,     3,     9,     1,     2,     3,    11,     9,     4,
-    10,   nil,   nil,   nil,   nil,   nil,   nil,     6 ]
+     6,    11,    12,     1,     2,     5,    12,    11,     5,     3,
+     4,     9,    10,   nil,   nil,   nil,   nil,     6 ]
 
 racc_goto_pointer = [
-   nil,     4,     4,     1,     5,   nil,    -4,   nil,   nil,   -12,
-    -7,   -16,   nil ]
+   nil,     3,     3,     8,     6,     4,    -4,   nil,   nil,    -4,
+    -5,   -16,   -13 ]
 
 racc_goto_default = [
-   nil,   nil,   nil,   nil,   nil,     5,   nil,    13,    15,   nil,
-   nil,   nil,    20 ]
+   nil,   nil,   nil,   nil,   nil,   nil,   nil,    13,    15,   nil,
+   nil,   nil,   nil ]
 
 racc_reduce_table = [
   0, 0, :racc_error,
@@ -223,7 +223,7 @@ module_eval(<<'.,.,', 'pgn_parser.y', 15)
   def _reduce_3(val, _values, result)
             result = val[1].pop
         result = {
-          tags:    val[0],
+          tags:    val[0].reverse_each.with_object({}) { |pair, h| h.merge!(pair) },
           result:  result,
           moves:   val[1],
           pgn:     nil,
@@ -236,18 +236,18 @@ module_eval(<<'.,.,', 'pgn_parser.y', 15)
 
 module_eval(<<'.,.,', 'pgn_parser.y', 26)
   def _reduce_4(val, _values, result)
-     result = val[0]
+     result = [val[0]]
     result
   end
 .,.,
 
 module_eval(<<'.,.,', 'pgn_parser.y', 29)
   def _reduce_5(val, _values, result)
-            # Right-recursive with section.merge(pair) reproduces the legacy
-        # whittle parser's tag semantics exactly: reverse source insertion
-        # order, and first-occurrence-wins on duplicate keys. This keeps
-        # serialized tag order byte-compatible with the legacy behavior.
-        result = val[1].merge(val[0])
+            # Left-recursive; the source-order array is reduced to the legacy
+        # tag semantics in {pgn_game} (reverse, then merge with
+        # first-occurrence-wins) so the whittle-order compatibility quirk is
+        # a single explicit line instead of implicit in recursion direction.
+        result = val[0] << val[1]
 
     result
   end
@@ -294,7 +294,7 @@ module_eval(<<'.,.,', 'pgn_parser.y', 50)
 module_eval(<<'.,.,', 'pgn_parser.y', 54)
   def _reduce_12(val, _values, result)
             result = val[0]
-        result.variations = val[1]
+        result.variations = val[1].reverse
         result
 
     result
@@ -377,17 +377,16 @@ module_eval(<<'.,.,', 'pgn_parser.y', 82)
 
 module_eval(<<'.,.,', 'pgn_parser.y', 85)
   def _reduce_23(val, _values, result)
-            # Right-recursive prepend reproduces the legacy whittle parser's
-        # variation-order reversal on every parse. This keeps parsed-game
-        # serialization byte-compatible with the legacy behavior; the quirk
-        # can be fixed in a separate change.
-        result = val[1] << val[0]
+            # Left-recursive; the legacy variation-order reversal is applied as
+        # a single explicit `.reverse` where the list is consumed in
+        # {element}, instead of being implicit in recursion direction.
+        result = val[0] << val[1]
 
     result
   end
 .,.,
 
-module_eval(<<'.,.,', 'pgn_parser.y', 93)
+module_eval(<<'.,.,', 'pgn_parser.y', 92)
   def _reduce_24(val, _values, result)
      result = val[1]
     result

data/lib/pgn/pgn_parser.y

@@ -15,7 +15,7 @@ rule
       {
         result = val[1].pop
         result = {
-          tags:    val[0],
+          tags:    val[0].reverse_each.with_object({}) { |pair, h| h.merge!(pair) },
           result:  result,
           moves:   val[1],
           pgn:     nil,
@@ -24,14 +24,14 @@ rule
       }
 
   tag_section:
-      tag_pair                            { result = val[0] }
-    | tag_pair tag_section
+      tag_pair                            { result = [val[0]] }
+    | tag_section tag_pair
       {
-        # Right-recursive with section.merge(pair) reproduces the legacy
-        # whittle parser's tag semantics exactly: reverse source insertion
-        # order, and first-occurrence-wins on duplicate keys. This keeps
-        # serialized tag order byte-compatible with the legacy behavior.
-        result = val[1].merge(val[0])
+        # Left-recursive; the source-order array is reduced to the legacy
+        # tag semantics in {pgn_game} (reverse, then merge with
+        # first-occurrence-wins) so the whittle-order compatibility quirk is
+        # a single explicit line instead of implicit in recursion direction.
+        result = val[0] << val[1]
       }
 
   tag_pair:
@@ -53,7 +53,7 @@ rule
     | san_move_annotated variation_list
       {
         result = val[0]
-        result.variations = val[1]
+        result.variations = val[1].reverse
         result
       }
     | COMMENT
@@ -81,13 +81,12 @@ rule
 
   variation_list:
       variation                           { result = [val[0]] }
-    | variation variation_list
+    | variation_list variation
       {
-        # Right-recursive prepend reproduces the legacy whittle parser's
-        # variation-order reversal on every parse. This keeps parsed-game
-        # serialization byte-compatible with the legacy behavior; the quirk
-        # can be fixed in a separate change.
-        result = val[1] << val[0]
+        # Left-recursive; the legacy variation-order reversal is applied as
+        # a single explicit `.reverse` where the list is consumed in
+        # {element}, instead of being implicit in recursion direction.
+        result = val[0] << val[1]
       }
 
   variation:

data/lib/pgn/position.rb

@@ -124,10 +124,131 @@ module PGN
       PGN::Bitboard::Engine.new(to_fen.to_s).legal_moves
     end
 
+    # All legal moves from this position as sorted SAN strings, computed
+    # by delegating the native engine's UCI move list through
+    # {PGN::Notation.san}. Requires the compiled native extension; raises
+    # NameError if it is absent.
+    #
+    # @return [Array<String>] sorted lexicographically
+    #
+    def legal_moves_san
+      engine = PGN::Bitboard::Engine.new(to_fen.to_s)
+      engine.legal_moves.map { |uci| uci_to_san(uci) }.sort
+    end
+
+    # Whether +move+ is legal. Accepts SAN ("Nf3", "e4", "O-O", "a8=Q",
+    # "Qxf7#") or UCI ("g1f3", "e2e4", "e1g1", "a7a8q"). Requires the
+    # compiled native extension; raises NameError if it is absent.
+    #
+    # UCI is handed straight to the engine. SAN is resolved against the
+    # engine's legal move list: a SAN string is legal only when it points
+    # at exactly one legal move (so an ambiguous "Nd2" with two knights
+    # is rejected, while "Nbd2"/"Nfd2" are accepted). The engine remains
+    # the single source of truth for legality (king safety, pins, etc.).
+    #
+    # @param move [String] SAN or UCI
+    # @return [Boolean]
+    def legal?(move)
+      engine = PGN::Bitboard::Engine.new(to_fen.to_s)
+      return engine.legal?(move) if uci?(move)
+
+      parsed = PGN::Move.new(move, player)
+      return false if parsed.destination.nil? && parsed.castle.nil?
+
+      candidates = engine.legal_moves.select { |uci| matches_san?(uci, parsed) }
+      candidates.size == 1
+    rescue StandardError
+      false
+    end
+
     def inspect
       "\n#{board.inspect}"
     end
 
+    # The color string for the side to move ('w'/'b').
+    def mover_color
+      player == :white ? 'w' : 'b'
+    end
+
+    # The color string for the opponent of the side to move ('w'/'b').
+    def opponent_color
+      player == :white ? 'b' : 'w'
+    end
+
+    # Whether the side to move's king is currently in check.
+    #
+    # @return [Boolean]
+    def in_check?
+      king = PGN::Attack.king_idx(board, mover_color)
+      !king.nil? && PGN::Attack.attacked?(board, king, opponent_color)
+    end
+
+    # The algebraic squares of every piece of the given color that attacks
+    # +square+ (algebraic, e.g. "e4"). Defaults to the side to move's
+    # opponent, which is useful for check detection.
+    #
+    # @param square [String] e.g. "e4"
+    # @param color [String, nil] 'w' or 'b'; defaults to the opponent color
+    # @return [Array<String>] squares attacking +square+
+    def attackers(square, color = opponent_color)
+      PGN::Attack.attackers(board, board.index_of(square), color)
+    end
+
+    # Whether the side to move has been checkmated (in check and no legal
+    # move). Requires the native extension for legal-move enumeration.
+    #
+    # @return [Boolean]
+    def checkmate?
+      in_check? && legal_moves.empty?
+    end
+
+    # Whether the side to move has been stalemated (not in check and no
+    # legal move). Requires the native extension.
+    #
+    # @return [Boolean]
+    def stalemate?
+      !in_check? && legal_moves.empty?
+    end
+
+    # Whether the position has insufficient material to mate. Covers K vs K,
+    # K + one minor vs K, and same-colored bishops only.
+    #
+    # @return [Boolean]
+    def insufficient_material?
+      non_king = (0...128).each_with_object([]) do |idx, acc|
+        next if idx.anybits?(0x88)
+
+        piece = board.at_index(idx)
+        acc << [piece, idx] if piece && piece.upcase != 'K'
+      end
+      return true if non_king.empty?
+      return true if non_king.size == 1 && %w[B N].include?(non_king.first.first.upcase)
+
+      bishops_same_color?(non_king)
+    end
+
+    # Whether the 50-move rule applies (100 halfmoves since the last pawn
+    # move or capture).
+    #
+    # @return [Boolean]
+    def fifty_move?
+      halfmove >= 100
+    end
+
+    # The terminal status of this position: :checkmate, :stalemate, or :draw
+    # (insufficient material or 50-move rule). nil if the position is still
+    # in progress. Threefold repetition requires game history and is
+    # answered by {PGN::Game#outcome}.
+    #
+    # @return [Symbol, nil]
+    def outcome
+      return :checkmate if checkmate?
+      return :stalemate if stalemate?
+      return :draw if insufficient_material? || fifty_move?
+
+      nil
+    end
+
     # @return [PGN::FEN] a {PGN::FEN} object representing the current position
     #
     def to_fen
@@ -167,5 +288,75 @@ module PGN
     def zobrist
       @zobrist ||= Zobrist.seed(board, player, castling, en_passant)
     end
+
+    private
+
+    # True when +move+ looks like a UCI coordinate string ("e2e4",
+    # "e1g1", "a7a8q"), so it can be handed straight to the engine.
+    def uci?(move)
+      move.is_a?(String) && move.match?(/\A[a-h][1-8][a-h][1-8][qrbn]?\z/)
+    end
+
+    # Convert a UCI string to SAN using the current position, for
+    # {#legal_moves_san}. Promotion (if present) is passed as the letter.
+    def uci_to_san(uci)
+      from = uci[0, 2]
+      to = uci[2, 2]
+      promo = uci[4]
+      PGN::Notation.san(self, from, to, promo)
+    end
+
+    # Map a castling side letter from {PGN::Move#castle} to the king's
+    # from/to UCI squares for the side to move.
+    CASTLE_UCI = {
+      'K' => 'e1g1',
+      'Q' => 'e1c1',
+      'k' => 'e8g8',
+      'q' => 'e8c8'
+    }.freeze
+    private_constant :CASTLE_UCI
+
+    # Does the legal UCI move +uci+ match the parsed SAN +move+? A move
+    # matches when destination, piece, promotion, and castling all agree,
+    # and the origin square satisfies +move+'s disambiguation (if any).
+    def matches_san?(uci, move)
+      return uci == CASTLE_UCI[move.castle] if move.castle
+
+      to = uci[2, 2]
+      return false if move.destination != to
+
+      from_idx = board.index_of(uci[0, 2])
+      return false if board.at_index(from_idx) != move.piece
+
+      promo = uci[4]
+      return false if move.promotion&.downcase != promo
+
+      disambiguation_matches?(move.disambiguation, from_idx)
+    end
+
+    # Whether the disambiguation string from SAN (a file, a rank, or a full
+    # square) describes the origin square at +from_idx+. nil disambiguation
+    # matches any origin (ambiguity is handled by the caller counting matches).
+    def disambiguation_matches?(disambiguation, from_idx)
+      return true if disambiguation.nil? || disambiguation.empty?
+
+      file = Board::INDEX_TO_FILE[from_idx & 0x0F]
+      rank = Board::INDEX_TO_RANK[from_idx >> 4]
+      case disambiguation
+      when /\A[a-h]\z/ then file == disambiguation
+      when /\A[1-8]\z/ then rank == disambiguation
+      else file + rank == disambiguation
+      end
+    end
+
+    # Whether +non_king+ is all bishops on squares of the same color (a known
+    # insufficient-material draw, e.g. KB vs KB with same-colored bishops).
+    def bishops_same_color?(non_king)
+      return false unless non_king.all? { |piece, _| piece.upcase == 'B' }
+      return false if non_king.size > 2
+
+      colors = non_king.map { |_piece, idx| ((idx & 0x0F) + (idx >> 4)) % 2 }
+      colors.uniq.size == 1
+    end
   end
 end

data/lib/pgn/version.rb

@@ -1,3 +1,3 @@
 module PGN
-  VERSION = '2.0.0'.freeze
+  VERSION = '2.0.1'.freeze
 end

data/lib/pgn.rb

@@ -1,10 +1,13 @@
 require 'pgn/board'
 require 'pgn/fen'
+require 'pgn/epd'
 require 'pgn/game'
+require 'pgn/node'
 require 'pgn/move'
 require 'pgn/move_calculator'
 require 'pgn/lexer'
 require 'pgn/notation'
+require 'pgn/attack'
 require 'pgn/zobrist'
 require 'pgn/pgn_parser'
 require 'pgn/parser'

data/spec/castling_normalization_spec.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe 'UCI-style castling normalization' do
+  let(:fen) { 'r3k2r/8/8/8/8/8/8/R3K2R w KQkq - 0 1' }
+  let(:pos) { PGN::FEN.new(fen).to_position }
+
+  it 'parses 0-0 / 0-0-0 the same as O-O / O-O-O in PGN::Move' do
+    expect(PGN::Move.new('0-0', :white).castle).to eq('K')
+    expect(PGN::Move.new('0-0-0', :white).castle).to eq('Q')
+    expect(PGN::Move.new('0-0', :black).castle).to eq('k')
+    expect(PGN::Move.new('0-0-0', :black).castle).to eq('q')
+    expect(PGN::Move.new('0-0', :white).piece).to be_nil
+  end
+
+  it 'normalizes parsed 0-0 movetext to O-O on a game' do
+    game = PGN::Game.new(%w[0-0])
+    expect(game.moves.first.notation).to eq('O-O')
+  end
+
+  it 'Notation.san produces O-O / O-O-O for the king two-file moves' do
+    expect(PGN::Notation.san(pos, 'e1', 'g1')).to eq('O-O')
+    expect(PGN::Notation.san(pos, 'e1', 'c1')).to eq('O-O-O')
+  end
+
+  it 'Position#legal? accepts both O-O and UCI e1g1 castling' do
+    expect(pos.legal?('O-O')).to be(true)
+    expect(pos.legal?('O-O-O')).to be(true)
+    expect(pos.legal?('e1g1')).to be(true)
+    expect(pos.legal?('e1c1')).to be(true)
+  end
+
+  it 'serializes castling as O-O, never 0-0' do
+    game = PGN::Game.new(%w[e4 e5 O-O])
+    expect(game.to_pgn).to include('O-O')
+    expect(game.to_pgn).not_to include('0-0')
+  end
+end

data/spec/comment_round_trip_spec.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe 'comment round-tripping' do
+  it 'round-trips nested braces through parse -> serialize -> parse' do
+    input = +"[White \"A\"]\n\n1. e4 {this {is a} nested {comment}} *\n"
+    g1 = PGN.parse(input, Encoding::UTF_8).first
+    g2 = PGN.parse(g1.to_pgn, Encoding::UTF_8).first
+    expect(g2.moves.first.comment).to eq(g1.moves.first.comment)
+    expect(g2.moves.first.comment).to eq('this {is a} nested {comment}')
+  end
+
+  it 'is stable: serialize -> parse -> serialize is idempotent' do
+    input = +"[White \"A\"]\n\n1. e4 {this {is a} nested {comment}} *\n"
+    once = PGN.parse(input, Encoding::UTF_8).first.to_pgn
+    twice = PGN.parse(once, Encoding::UTF_8).first.to_pgn
+    expect(twice).to eq(once)
+  end
+
+  it 'round-trips escaped braces and backslashes' do
+    input = +"[White \"A\"]\n\n1. e4 {a \\{literal\\} back\\\\slash} *\n"
+    g = PGN.parse(input, Encoding::UTF_8).first
+    expect(g.moves.first.comment).to eq('a {literal} back\\slash')
+    reparsed = PGN.parse(g.to_pgn, Encoding::UTF_8).first
+    expect(reparsed.moves.first.comment).to eq(g.moves.first.comment)
+  end
+
+  it 'round-trips the nested_comments fixture comment body' do
+    input = File.binread('spec/pgn_files/nested_comments.pgn')
+    g = PGN.parse(input, Encoding::UTF_8).first
+    reparsed = PGN.parse(g.to_pgn, Encoding::UTF_8).first
+    expect(reparsed.moves.map(&:comment)).to eq(g.moves.map(&:comment))
+  end
+end

data/spec/epd_spec.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe PGN::EPD do
+  let(:start_epd) { 'rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq -' }
+
+  it 'parses the placement/side/castling/ep fields' do
+    epd = PGN::EPD.new(start_epd)
+    pos = epd.to_position
+    expect(pos.player).to eq(:white)
+    expect(pos.castling).to eq(%w[K Q k q])
+    expect(pos.en_passant).to be_nil
+    expect(pos.halfmove).to eq(0)
+    expect(pos.fullmove).to eq(1)
+  end
+
+  it 'round-trips a simple position' do
+    expect(PGN::EPD.new(start_epd).to_s).to eq(start_epd)
+  end
+
+  it 'preserves trailing operation fields verbatim' do
+    epd = 'rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - bm e4; id "start";'
+    expect(PGN::EPD.new(epd).to_s).to eq(epd)
+    expect(PGN::EPD.new(epd).ops).to eq('bm e4; id "start";')
+  end
+
+  it 'normalizes nil castling/ep to "-"' do
+    epd = PGN::EPD.new('rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w')
+    expect(epd.castling).to eq('-')
+    expect(epd.en_passant).to eq('-')
+  end
+end
+
+RSpec.describe PGN::FEN, '#to_epd' do
+  it 'drops the move counters from the start position' do
+    expect(PGN::FEN.start.to_epd).to eq('rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq -')
+  end
+
+  it 'preserves castling and en passant' do
+    fen = 'rnbqkbnr/ppp1pppp/8/3pP3/8/8/PPPP1PPP/RNBQKBNR w KQkq d6 0 3'
+    expect(PGN::FEN.new(fen).to_epd).to eq('rnbqkbnr/ppp1pppp/8/3pP3/8/8/PPPP1PPP/RNBQKBNR w KQkq d6')
+  end
+end

data/spec/fen_spec.rb

@@ -47,6 +47,12 @@ describe PGN::FEN do
       next_pos = pos.move('d6')
       next_pos.to_fen.en_passant.should == '-'
     end
+
+    it 'preserves the en passant square through FEN#to_position' do
+      fen = 'rnbqkbnr/ppp1pppp/8/3pP3/8/8/PPPP1PPP/RNBQKBNR w KQkq d6 0 3'
+      expect(PGN::FEN.new(fen).to_position.en_passant).to eq('d6')
+      expect(PGN::FEN.new(fen).to_position.to_fen.to_s).to eq(fen)
+    end
   end
 
   describe 'halfmove counter' do

data/spec/game_history_spec.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe PGN::Game, 'mutable history' do
+  skip 'native extension PGN::Bitboard::Engine not compiled' unless PGN::Bitboard.const_defined?(:Engine)
+
+  let(:game) { PGN::Game.new(%w[e4 e5]) }
+
+  it 'appends a move with #push and invalidates the position cache' do
+    expect(game.positions.length).to eq(3) # start, e4, e5
+    game.push('Nf3')
+    expect(game.moves.map(&:notation)).to eq(%w[e4 e5 Nf3])
+    expect(game.positions.length).to eq(4)
+    expect(game.current_position.board.at('f3')).to eq('N')
+  end
+
+  it 'rejects an illegal move with ArgumentError' do
+    expect { game.push('e5') }.to raise_error(ArgumentError, /illegal move/)
+    expect(game.moves.length).to eq(2) # unchanged
+  end
+
+  it 'removes and returns the last move with #pop' do
+    last = game.pop
+    expect(last.notation).to eq('e5')
+    expect(game.moves.map(&:notation)).to eq(%w[e4])
+    expect(game.positions.length).to eq(2)
+  end
+
+  it 'returns nil when popping an empty game' do
+    empty = PGN::Game.new([])
+    expect(empty.pop).to be_nil
+  end
+
+  it 'normalizes castling on push' do
+    game = PGN::Game.new(%w[e4 e5 Nf3 Nc6 Bc4 Bc5 O-O Nf6 d3])
+    game.push('0-0')
+    expect(game.moves.last.notation).to eq('O-O')
+  end
+
+  it 'lets a freshly pushed game reach a checkmate outcome' do
+    game = PGN::Game.new(%w[e4 e5 Bc4 Nc6 Qh5 Nf6])
+    game.push('Qxf7#')
+    expect(game.outcome).to eq(:checkmate)
+  end
+end

data/spec/game_spec.rb

@@ -129,4 +129,64 @@ describe PGN::Game do
       end
     end
   end
+
+  describe 'node mutation round-trip' do
+    non_round_trip = %w[doublequotes.pgn specialcharacters.pgn].freeze
+
+    # A node-sig tree with variations sorted, so the comparison is
+    # order-independent (the parser reverses variation order on each parse).
+    def node_sig(move)
+      [move.notation, (move.variations || []).map { line_sig(_1) }.sort]
+    end
+
+    def line_sig(line)
+      line.map { node_sig(_1) }
+    end
+
+    def tree_sig(game)
+      game.moves.map { node_sig(_1) }
+    end
+
+    # First node (DFS over children) that has at least one variation. Such a
+    # node always has a non-nil continuation, so add_variation can branch.
+    def first_branch_with_variations(node)
+      stack = [node]
+      until stack.empty?
+        n = stack.shift
+        return n unless n.variations.empty?
+
+        stack.concat(n.children)
+      end
+      nil
+    end
+
+    it 'every fixture survives promote/demote/add_variation and re-parses' do
+      fixtures = `git ls-files spec/pgn_files/`.split.map { |p| File.expand_path(p) }
+      fixtures.reject! { |p| non_round_trip.include?(File.basename(p)) }
+      fixtures.each do |path|
+        PGN.parse(File.read(path, encoding: Encoding::ISO_8859_1)).each do |game|
+          root = game.root
+
+          # promote then demote the first variation if one exists
+          branch = first_branch_with_variations(root)
+          if branch && !branch.variations.empty?
+            branch.variations.first.promote
+            game.root
+            b2 = first_branch_with_variations(game.root)
+            if b2 && !b2.variations.empty?
+              b2.variations.first.demote
+              game.root
+            end
+            b3 = first_branch_with_variations(game.root)
+            b3&.add_variation('Nc3')
+          end
+
+          once = game.to_pgn
+          reparsed = PGN.parse(once).first
+          expect(tree_sig(reparsed)).to eq(tree_sig(game)),
+                                        "#{path}: mutated game tree must round-trip (set-stable)"
+        end
+      end
+    end
+  end
 end