pgn2 1.5.0 → 2.0.1

data/pgn2.gemspec

@@ -1,3 +1,4 @@
+require 'English'
 lib = File.expand_path('lib', __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'pgn/version'
@@ -10,27 +11,33 @@ Gem::Specification.new do |spec|
   spec.description   = 'A PGN parser and FEN generator for Ruby'
   spec.summary       = 'A PGN parser for Ruby'
   spec.homepage      = 'https://github.com/muriloime/pgn'
-  spec.license       = 'MIT'
+  spec.licenses      = ['MIT', 'MPL-2.0']
   spec.required_ruby_version = '>= 3.0'
 
   spec.metadata = {
-    'homepage_uri'      => 'https://github.com/muriloime/pgn',
-    'source_code_uri'   => 'https://github.com/muriloime/pgn',
-    'bug_tracker_uri'   => 'https://github.com/muriloime/pgn/issues',
-    'changelog_uri'     => 'https://github.com/muriloime/pgn/blob/main/CHANGELOG.md'
+    'homepage_uri' => 'https://github.com/muriloime/pgn',
+    'source_code_uri' => 'https://github.com/muriloime/pgn',
+    'bug_tracker_uri' => 'https://github.com/muriloime/pgn/issues',
+    'changelog_uri' => 'https://github.com/muriloime/pgn/blob/main/CHANGELOG.md',
+    'rubygems_mfa_required' => 'true'
   }
 
-  spec.files         = `git ls-files`.split($/)
+  spec.files         = `git ls-files`.split($INPUT_RECORD_SEPARATOR)
   spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
-  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ['lib']
 
+  spec.extensions = ['ext/pgn2_native/extconf.rb']
+  spec.add_dependency 'rb_sys', '~> 0.9.39'
+  spec.add_development_dependency 'rake-compiler', '~> 1.2'
+  spec.add_development_dependency 'rake-compiler-dock', '~> 1.6'
+
+  spec.add_development_dependency 'benchmark-ips'
   spec.add_development_dependency 'bundler', '~> 2.3'
+  spec.add_development_dependency 'bundler-audit'
+  spec.add_development_dependency 'memory_profiler'
   spec.add_development_dependency 'pry'
+  spec.add_development_dependency 'racc'
   spec.add_development_dependency 'rake'
   spec.add_development_dependency 'rspec'
-  spec.add_development_dependency 'racc'
-  spec.add_development_dependency 'benchmark-ips'
-  spec.add_development_dependency 'memory_profiler'
   spec.add_development_dependency 'rubocop', '~> 1.60'
 end

data/spec/bitboard_spec.rb

@@ -0,0 +1,54 @@
+require 'spec_helper'
+
+RSpec.describe PGN::Bitboard::Engine do
+  let(:startpos) { 'rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1' }
+
+  # The native extension is optional from the gem's perspective; skip the
+  # whole suite if it isn't compiled in this environment.
+  skip 'native extension PGN::Bitboard::Engine not compiled' unless PGN::Bitboard.const_defined?(:Engine)
+
+  it 'perfts the start position' do
+    e = described_class.new(startpos)
+    expect(e.perft(1)).to eq(20)
+    expect(e.perft(2)).to eq(400)
+    expect(e.perft(3)).to eq(8902)
+    expect(e.perft(4)).to eq(197_281)
+  end
+
+  it 'perfts Kiwipete' do
+    e = described_class.new('r3k2r/p1ppqpb1/bn2pnp1/3PN3/1p2P3/2N2Q1p/PPPBBPPP/R3K2R w KQkq - 0 1')
+    expect(e.perft(1)).to eq(48)
+    expect(e.perft(3)).to eq(97_862)
+  end
+
+  it 'raises on a bad FEN' do
+    expect { described_class.new('not a fen') }.to raise_error(ArgumentError)
+  end
+
+  it 'lists legal moves in sorted UCI' do
+    e = described_class.new(startpos)
+    moves = e.legal_moves
+    expect(moves.length).to eq(20)
+    expect(moves).to eq(moves.sort)
+    expect(moves).to include('e2e4', 'g1f3', 'd2d4')
+  end
+
+  it 'answers legal? with UCI' do
+    e = described_class.new(startpos)
+    expect(e.legal?('e2e4')).to be(true)
+    expect(e.legal?('e2e5')).to be(false)
+    expect(e.legal?('g1f3')).to be(true)
+  end
+
+  it 'encodes promotions in legal_moves' do
+    e = described_class.new('8/P7/8/8/8/8/8/4k2K w - - 0 1')
+    moves = e.legal_moves
+    expect(moves).to include('a7a8q', 'a7a8r', 'a7a8b', 'a7a8n')
+  end
+
+  it 'recognizes castling as legal' do
+    e = described_class.new('r3k2r/8/8/8/8/8/8/R3K2R w KQkq - 0 1')
+    expect(e.legal?('e1g1')).to be(true)
+    expect(e.legal?('e1c1')).to be(true)
+  end
+end

data/spec/board_spec.rb

@@ -7,6 +7,36 @@ describe PGN::Board do
     end
   end
 
+  describe 'attack masks' do
+    it 'KNIGHT_ATTACKS lists the on-board knight targets for each 0x88 index' do
+      expect(PGN::Board::KNIGHT_ATTACKS[0]).to contain_exactly(18, 33) # a1: c3(0x12), b3(0x21)
+      expect(PGN::Board::KNIGHT_ATTACKS[0x54].length).to eq(8) # e4 = 0x54, centre
+      expect(PGN::Board::KNIGHT_ATTACKS[0x77]).to contain_exactly(86, 101) # h8: f7(0x56), g6(0x65)
+    end
+
+    it 'KING_ATTACKS lists the on-board king targets for each 0x88 index' do
+      expect(PGN::Board::KING_ATTACKS[0]).to contain_exactly(1, 16, 17) # a1: b1, a2, b2
+      expect(PGN::Board::KING_ATTACKS[0x54].length).to eq(8)
+      expect(PGN::Board::KING_ATTACKS[0x77]).to contain_exactly(102, 103, 118) # h8: g7, h7, g8
+    end
+
+    it 'only contains on-board squares and is nil for off-board source indices' do
+      on_board = (0...128).select { |i| i.nobits?(0x88) }
+      expect(PGN::Board::KNIGHT_ATTACKS.length).to eq(128)
+      expect(PGN::Board::KING_ATTACKS.length).to eq(128)
+      on_board.each do |i|
+        expect(PGN::Board::KNIGHT_ATTACKS[i]).to be_an(Array)
+        expect(PGN::Board::KING_ATTACKS[i]).to be_an(Array)
+        expect(PGN::Board::KNIGHT_ATTACKS[i]).to all(satisfy { |sq| sq.nobits?(0x88) })
+        expect(PGN::Board::KING_ATTACKS[i]).to all(satisfy { |sq| sq.nobits?(0x88) })
+      end
+      (0...128).reject { |i| i.nobits?(0x88) }.each do |i|
+        expect(PGN::Board::KNIGHT_ATTACKS[i]).to be_nil
+        expect(PGN::Board::KING_ATTACKS[i]).to be_nil
+      end
+    end
+  end
+
   describe '#at' do
     # Use .dup because PGN::Board.start returns the same shared board
     # backed by the frozen START constant.
@@ -100,6 +130,29 @@ describe PGN::Board do
     end
   end
 
+  describe '#fen_board_string' do
+    it 'serializes the start position to the FEN board string' do
+      expect(PGN::Board.start.fen_board_string)
+        .to eq('rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR')
+    end
+
+    it 'collapses runs of empty squares into digits' do
+      board = PGN::FEN.new('8/8/8/8/8/8/8/8 w - - 0 1').board
+      expect(board.fen_board_string).to eq('8/8/8/8/8/8/8/8')
+    end
+
+    it 'serializes a mid-game board byte-for-byte like FEN#board_string' do
+      fen = 'r1bqkb1r/pp1p1ppp/2n1pn2/8/3NP3/2N5/PPP2PPP/R1BQKB1R w KQkq - 3 6'
+      board = PGN::FEN.new(fen).board
+      expect(board.fen_board_string).to eq(fen.split.first)
+    end
+
+    it 'serializes rank 8 first and rank 1 last (FEN order)' do
+      board = PGN::FEN.new('4k3/8/8/8/8/8/8/4K3 w - - 0 1').board
+      expect(board.fen_board_string).to eq('4k3/8/8/8/8/8/8/4K3')
+    end
+  end
+
   describe '#inspect' do
     it 'returns a string with unicode pieces and newlines' do
       inspected = PGN::Board.start.inspect

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

@@ -1,120 +1,126 @@
-require "spec_helper"
+require 'spec_helper'
 
 describe PGN::FEN do
-  describe "castling availability" do
-    it "should remove all castling availabilitiy after castling" do
-      pos = PGN::FEN.new("rnbqk2r/1p3pbp/p2p1np1/2pP4/P3PB2/2N2N2/1P3PPP/R2QKB1R b KQkq e3 0 8").to_position
-      next_pos = pos.move("O-O")
+  describe 'castling availability' do
+    it 'should remove all castling availabilitiy after castling' do
+      pos = PGN::FEN.new('rnbqk2r/1p3pbp/p2p1np1/2pP4/P3PB2/2N2N2/1P3PPP/R2QKB1R b KQkq e3 0 8').to_position
+      next_pos = pos.move('O-O')
       next_pos.to_fen.castling.should_not match(/k|q/)
     end
 
-    it "should remove all castling availability after moving a king" do
-      pos = PGN::FEN.new("r1b1kb1r/pp2pppp/2n5/4P3/1nB5/P4N2/1P3PPP/RNBqK2R w KQkq - 0 9").to_position
-      next_pos = pos.move("Kxd1")
+    it 'should remove all castling availability after moving a king' do
+      pos = PGN::FEN.new('r1b1kb1r/pp2pppp/2n5/4P3/1nB5/P4N2/1P3PPP/RNBqK2R w KQkq - 0 9').to_position
+      next_pos = pos.move('Kxd1')
       next_pos.to_fen.castling.should_not match(/K|Q/)
     end
 
-    it "should remove only the one castling option after moving a rook" do
-      pos = PGN::FEN.new("r3k2r/1pp2pp1/p1pb1qn1/4p3/3PP1p1/8/PPPN1PPN/R1BQR1K1 b kq - 1 11").to_position
-      next_pos = pos.move("Rxh2")
+    it 'should remove only the one castling option after moving a rook' do
+      pos = PGN::FEN.new('r3k2r/1pp2pp1/p1pb1qn1/4p3/3PP1p1/8/PPPN1PPN/R1BQR1K1 b kq - 1 11').to_position
+      next_pos = pos.move('Rxh2')
       next_pos.to_fen.castling.should_not match(/k/)
       next_pos.to_fen.castling.should match(/q/)
     end
 
-    it "should remove one castling option when a rook is taken" do
-      pos = PGN::FEN.new("rn1qkbnr/pbpppppp/1p6/8/6P1/2N4P/PPPPPP2/R1BQKBNR b KQkq - 2 3").to_position
-      next_pos = pos.move("Bxh1")
+    it 'should remove one castling option when a rook is taken' do
+      pos = PGN::FEN.new('rn1qkbnr/pbpppppp/1p6/8/6P1/2N4P/PPPPPP2/R1BQKBNR b KQkq - 2 3').to_position
+      next_pos = pos.move('Bxh1')
       next_pos.to_fen.castling.should_not match(/K/)
     end
 
-    it "should change to a hyphen once no side can castle" do
-      pos = PGN::FEN.new("r1bq1rk1/pp1nbppp/3ppn2/8/2PP1N2/P1N5/1P2BPPP/R1BQK2R w KQ - 2 9").to_position
-      pos.to_fen.castling.should_not == "-"
-      next_pos = pos.move("O-O")
-      next_pos.to_fen.castling.should == "-"
+    it 'should change to a hyphen once no side can castle' do
+      pos = PGN::FEN.new('r1bq1rk1/pp1nbppp/3ppn2/8/2PP1N2/P1N5/1P2BPPP/R1BQK2R w KQ - 2 9').to_position
+      pos.to_fen.castling.should_not
+      next_pos = pos.move('O-O')
+      next_pos.to_fen.castling.should == '-'
     end
   end
 
-  describe "en passant" do
-    it "should display the en passant square whenever a pawn moves two spaces" do
-      pos = PGN::FEN.new("rnbqkb1r/pppppppp/5n2/8/8/5N2/PPPPPPPP/RNBQKB1R w KQkq - 2 1").to_position
-      next_pos = pos.move("c4")
-      next_pos.to_fen.en_passant.should == "c3"
+  describe 'en passant' do
+    it 'should display the en passant square whenever a pawn moves two spaces' do
+      pos = PGN::FEN.new('rnbqkb1r/pppppppp/5n2/8/8/5N2/PPPPPPPP/RNBQKB1R w KQkq - 2 1').to_position
+      next_pos = pos.move('c4')
+      next_pos.to_fen.en_passant.should == 'c3'
     end
 
-    it "should be a hyphen if no pawn moved two spaces the previous move" do
-      pos = PGN::FEN.new("rnbqkb1r/pppppppp/5n2/8/2P5/5N2/PP1PPPPP/RNBQKB1R b KQkq c3 0 1").to_position
-      next_pos = pos.move("d6")
-      next_pos.to_fen.en_passant.should == "-"
+    it 'should be a hyphen if no pawn moved two spaces the previous move' do
+      pos = PGN::FEN.new('rnbqkb1r/pppppppp/5n2/8/2P5/5N2/PP1PPPPP/RNBQKB1R b KQkq c3 0 1').to_position
+      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
-    it "should reset after a pawn advance" do
-      pos = PGN::FEN.new("2b2rk1/2pp1ppp/1p6/r3P2q/3Q4/2P5/PP3PPP/RN3RK1 w - - 3 15").to_position
-      pos.to_fen.halfmove.should == "3"
-      next_pos = pos.move("f4")
-      next_pos.to_fen.halfmove.should == "0"
+  describe 'halfmove counter' do
+    it 'should reset after a pawn advance' do
+      pos = PGN::FEN.new('2b2rk1/2pp1ppp/1p6/r3P2q/3Q4/2P5/PP3PPP/RN3RK1 w - - 3 15').to_position
+      pos.to_fen.halfmove.should
+      next_pos = pos.move('f4')
+      next_pos.to_fen.halfmove.should == '0'
     end
 
-    it "should reset after a capture" do
-      pos = PGN::FEN.new("2r2rk1/1p2ppbp/1q1p1np1/pN4B1/Pnb1PP2/2N5/1PP1B1PP/R2Q1R1K w - - 5 14").to_position
-      pos.to_fen.halfmove.should == "5"
-      next_pos = pos.move("Bxc4")
-      next_pos.to_fen.halfmove.should == "0"
+    it 'should reset after a capture' do
+      pos = PGN::FEN.new('2r2rk1/1p2ppbp/1q1p1np1/pN4B1/Pnb1PP2/2N5/1PP1B1PP/R2Q1R1K w - - 5 14').to_position
+      pos.to_fen.halfmove.should
+      next_pos = pos.move('Bxc4')
+      next_pos.to_fen.halfmove.should == '0'
     end
 
-    it "should not reset otherwise" do
-      pos = PGN::FEN.new("2k2b1r/p4p1p/q1p2p2/8/2br4/5P2/PPQB2PP/R1N1K2R w KQ - 0 17").to_position
-      pos.to_fen.halfmove.should == "0"
-      moves = %w{Qf5+ Rd7 Bc3 Bh6 Qa5 Re8+ Kf2 Be3+ Kg3 Rg8+ Kh4}
+    it 'should not reset otherwise' do
+      pos = PGN::FEN.new('2k2b1r/p4p1p/q1p2p2/8/2br4/5P2/PPQB2PP/R1N1K2R w KQ - 0 17').to_position
+      pos.to_fen.halfmove.should
+      moves = %w[Qf5+ Rd7 Bc3 Bh6 Qa5 Re8+ Kf2 Be3+ Kg3 Rg8+ Kh4]
       moves.each_with_index do |move, i|
         pos = pos.move(move)
-        pos.to_fen.halfmove.should == (i+1).to_s
+        pos.to_fen.halfmove.should == (i + 1).to_s
       end
     end
   end
 
-  describe "fullmove counter" do
-    it "should not increase after white moves" do
-      pos = PGN::FEN.new("4br1k/ppqnr1b1/3p3p/P1pP1p2/2P1pB2/6PP/1P2BP1N/R2QR1K1 w - - 3 25").to_position
-      pos.to_fen.fullmove.should == "25"
-      next_pos = pos.move("Qd2")
-      next_pos.to_fen.fullmove.should == "25"
+  describe 'fullmove counter' do
+    it 'should not increase after white moves' do
+      pos = PGN::FEN.new('4br1k/ppqnr1b1/3p3p/P1pP1p2/2P1pB2/6PP/1P2BP1N/R2QR1K1 w - - 3 25').to_position
+      pos.to_fen.fullmove.should
+      next_pos = pos.move('Qd2')
+      next_pos.to_fen.fullmove.should == '25'
     end
 
-    it "should increase after black moves" do
-      pos = PGN::FEN.new("4br1k/ppqnr1b1/3p3p/P1pP1p2/2P1pB2/6PP/1P1QBP1N/R3R1K1 b - - 4 25").to_position
-      pos.to_fen.fullmove.should == "25"
-      next_pos = pos.move("Kh7")
-      next_pos.to_fen.fullmove.should == "26"
+    it 'should increase after black moves' do
+      pos = PGN::FEN.new('4br1k/ppqnr1b1/3p3p/P1pP1p2/2P1pB2/6PP/1P1QBP1N/R3R1K1 b - - 4 25').to_position
+      pos.to_fen.fullmove.should
+      next_pos = pos.move('Kh7')
+      next_pos.to_fen.fullmove.should == '26'
     end
   end
 
-  describe "displaying FEN notation" do
-    it "should return a string on inspect" do
+  describe 'displaying FEN notation' do
+    it 'should return a string on inspect' do
       fen = PGN::FEN.start
       fen.inspect.should be_a(String)
     end
   end
 
-  describe "board_string round-trip" do
+  describe 'board_string round-trip' do
     fens = [
       PGN::FEN::INITIAL,
-      "r1bqkb1r/pp1p1ppp/2n1pn2/8/3NP3/2N5/PPP2PPP/R1BQKB1R w KQkq - 3 6",
-      "8/8/8/8/8/8/8/8 w - - 0 1",
-      "r3k2r/8/8/8/8/8/8/R3K2R w KQkq - 0 1",
-      "4k3/4P3/8/8/8/8/8/4K3 w - - 0 1",
-      "rnbqkbnr/ppp1pppp/8/3pP3/8/8/PPPP1PPP/RNBQKBNR w KQkq d6 0 3",
+      'r1bqkb1r/pp1p1ppp/2n1pn2/8/3NP3/2N5/PPP2PPP/R1BQKB1R w KQkq - 3 6',
+      '8/8/8/8/8/8/8/8 w - - 0 1',
+      'r3k2r/8/8/8/8/8/8/R3K2R w KQkq - 0 1',
+      '4k3/4P3/8/8/8/8/8/4K3 w - - 0 1',
+      'rnbqkbnr/ppp1pppp/8/3pP3/8/8/PPPP1PPP/RNBQKBNR w KQkq d6 0 3'
     ]
 
-    it "round-trips every fixture through FEN#to_s" do
+    it 'round-trips every fixture through FEN#to_s' do
       fens.each do |fen|
         expect(PGN::FEN.new(fen).to_s).to eq(fen), fen
       end
     end
 
-    it "round-trips the board portion through FEN#to_position.to_fen" do
+    it 'round-trips the board portion through FEN#to_position.to_fen' do
       fens.each do |fen|
         original  = PGN::FEN.new(fen)
         roundtrip = original.to_position.to_fen

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