pgn2 1.4.0 → 2.0.0

data/spec/fen_spec.rb

@@ -1,120 +1,120 @@
-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
   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_spec.rb

@@ -4,7 +4,11 @@ describe PGN::Game do
   describe '#positions' do
     it 'does not raise an error' do
       tags   = { 'White' => 'Deep Blue', 'Black' => 'Kasparov' }
-      moves  = %w[e4 c5 c3 d5 exd5 Qxd5 d4 Nf6 Nf3 Bg4 Be2 e6 h3 Bh5 O-O Nc6 Be3 cxd4 cxd4 Bb4 a3 Ba5 Nc3 Qd6 Nb5 Qe7 Ne5 Bxe2 Qxe2 O-O Rac1 Rac8 Bg5 Bb6 Bxf6 gxf6 Nc4 Rfd8 Nxb6 axb6 Rfd1 f5 Qe3 Qf6 d5 Rxd5 Rxd5 exd5 b3 Kh8 Qxb6 Rg8 Qc5 d4 Nd6 f4 Nxb7 Ne5 Qd5 f3 g3 Nd3 Rc7 Re8 Nd6 Re1+ Kh2 Nxf2 Nxf7+ Kg7 Ng5+ Kh6 Rxh7+]
+      moves  = %w[e4 c5 c3 d5 exd5 Qxd5 d4 Nf6 Nf3 Bg4 Be2 e6 h3 Bh5 O-O Nc6 Be3 cxd4
+                  cxd4 Bb4 a3 Ba5 Nc3 Qd6 Nb5 Qe7 Ne5 Bxe2 Qxe2 O-O Rac1 Rac8 Bg5 Bb6
+                  Bxf6 gxf6 Nc4 Rfd8 Nxb6 axb6 Rfd1 f5 Qe3 Qf6 d5 Rxd5 Rxd5 exd5 b3
+                  Kh8 Qxb6 Rg8 Qc5 d4 Nd6 f4 Nxb7 Ne5 Qd5 f3 g3 Nd3 Rc7 Re8 Nd6 Re1+
+                  Kh2 Nxf2 Nxf7+ Kg7 Ng5+ Kh6 Rxh7+]
       result = '1-0'
       game = PGN::Game.new(moves, tags, result)
       expect { game.positions }.not_to raise_error
@@ -19,6 +23,40 @@ describe PGN::Game do
     end
   end
 
+  describe '#each_position' do
+    it 'yields each position in order when given a block' do
+      game = PGN::Game.new(%w[e4 e5])
+      yielded = []
+      game.each_position { |p| yielded << p.to_fen.to_s }
+      expect(yielded).to eq(
+        [
+          PGN::Position.start.to_fen.to_s,
+          game.positions[1].to_fen.to_s,
+          game.positions[2].to_fen.to_s
+        ]
+      )
+    end
+
+    it 'returns an Enumerator when no block is given' do
+      game = PGN::Game.new(%w[e4 e5])
+      expect(game.each_position).to be_an(Enumerator)
+    end
+
+    it 'produces the same positions as #positions' do
+      game = PGN::Game.new(%w[e4 c5 Nf3])
+      expect(game.each_position.map { |p| p.to_fen.to_s })
+        .to eq(game.positions.map { |p| p.to_fen.to_s })
+    end
+
+    it 'does not materialize the full array when only the last is needed' do
+      moves = %w[e4 c5 Nf3 d6]
+      game  = PGN::Game.new(moves)
+      last = nil
+      game.each_position { |p| last = p }
+      expect(last.to_fen.to_s).to eq(game.positions.last.to_fen.to_s)
+    end
+  end
+
   describe '#to_pgn' do
     it 'returns a canonical PGN string ending with a newline' do
       game = PGN::Game.new(%w[e4 e5], { 'White' => 'A' }, '1-0')
@@ -34,20 +72,20 @@ describe PGN::Game do
     # *order* does not round-trip; only the set of variations does. We
     # therefore compare variations order-independently via a canonical
     # signature.
-    def move_signature(m)
-      c = m.comment.to_s
+    def move_signature(move)
+      c = move.comment.to_s
       # The current parser does not unescape \\, {, or }, so comments
       # containing those do not round-trip byte-for-byte (design spec v1
       # limitation). Treat them as a single sentinel so the set comparison
       # ignores the difference.
-      c = "<unescaped-comment>" if c.match?(/[\\{}]/)
-      vars = (m.variations || []).map { |v| v.map { |mm| move_signature(mm) }.join("\x02") }.sort.join("\x03")
-      "#{m.notation}\x01#{(m.annotation || []).inspect}\x01#{c}\x01#{vars}"
+      c = '<unescaped-comment>' if c.match?(/[\\{}]/)
+      vars = (move.variations || []).map { |v| v.map { |sub| move_signature(sub) }.join("\x02") }.sort.join("\x03")
+      "#{move.notation}\x01#{(move.annotation || []).inspect}\x01#{c}\x01#{vars}"
     end
 
     def expect_moves_equal(expected, actual, ctx)
       expect(actual.map(&:notation)).to eq(expected.map(&:notation)),
-        "#{ctx}: notation"
+                                        "#{ctx}: notation"
       expected.each_with_index do |e, i|
         expect(actual[i].annotation).to eq(e.annotation), "#{ctx}[#{i}]: annotation"
         # The current parser cannot unescape braces, so comments containing
@@ -55,11 +93,11 @@ describe PGN::Game do
         # limitation). Skip the comparison for those.
         unless e.comment.to_s.match?(/[\\{}]/)
           expect(actual[i].comment).to eq(e.comment),
-            "#{ctx}[#{i}]: comment #{e.comment.inspect} vs #{actual[i].comment.inspect}"
+                                       "#{ctx}[#{i}]: comment #{e.comment.inspect} vs #{actual[i].comment.inspect}"
         end
         # Variations compared as an order-independent set of signatures.
-        exp_sigs = (e.variations || []).map { |v| v.map { |mm| move_signature(mm) }.join("\x02") }.sort
-        act_sigs = (actual[i].variations || []).map { |v| v.map { |mm| move_signature(mm) }.join("\x02") }.sort
+        exp_sigs = (e.variations || []).map { |v| v.map { |sub| move_signature(sub) }.join("\x02") }.sort
+        act_sigs = (actual[i].variations || []).map { |v| v.map { |sub| move_signature(sub) }.join("\x02") }.sort
         expect(act_sigs).to eq(exp_sigs), "#{ctx}[#{i}]: variations"
       end
     end
@@ -67,17 +105,16 @@ describe PGN::Game do
     # Fixtures that do not round-trip byte-for-byte: doublequotes has
     # unescaped inner quotes (serializer escapes them) and specialcharacters
     # is multibyte and requires the Encoding::UTF_8 argument to parse.
-    NON_ROUND_TRIP = %w[doublequotes.pgn specialcharacters.pgn].freeze
-
     it 'round-trips every tracked fixture' do
+      non_round_trip = %w[doublequotes.pgn specialcharacters.pgn].freeze
       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.reject! { |p| non_round_trip.include?(File.basename(p)) }
       fixtures.each do |path|
         PGN.parse(File.read(path)).each_with_index do |game, gi|
           reparsed = PGN.parse(game.to_pgn).first
 
           expect(reparsed.result).to eq(game.result),
-            "#{path}##{gi}: result"
+                                     "#{path}##{gi}: result"
           expect_moves_equal(game.moves, reparsed.moves, "#{path}##{gi}")
 
           # Reparsed tags must be a superset of the original (a no-tag game
@@ -86,7 +123,7 @@ describe PGN::Game do
           reparsed_tags = reparsed.tags || {}
           original_tags.each do |k, v|
             expect(reparsed_tags[k]).to eq(v),
-              "#{path}##{gi}: tag #{k} #{v.inspect} vs #{reparsed_tags[k].inspect}"
+                                        "#{path}##{gi}: tag #{k} #{v.inspect} vs #{reparsed_tags[k].inspect}"
           end
         end
       end

data/spec/lexer_spec.rb

@@ -17,7 +17,7 @@ RSpec.describe PGN::Lexer do
 
   it 'discards % rest-of-line comments' do
     toks = lex("% a comment line\n[Event \"X\"]")
-    expect(toks.map(&:type)).to eq([:lbracket, :tag_name, :string, :rbracket])
+    expect(toks.map(&:type)).to eq(%i[lbracket tag_name string rbracket])
   end
 
   it 'tokenizes the four single-character literals' do
@@ -57,8 +57,8 @@ RSpec.describe PGN::Lexer do
   end
 
   it 'tokenizes nested brace comments recursively' do
-    toks = lex("{outer {inner} tail}")
-    expect(toks[0].value).to eq("{outer {inner} tail}")
+    toks = lex('{outer {inner} tail}')
+    expect(toks[0].value).to eq('{outer {inner} tail}')
   end
 
   it 'tokenizes all game terminations' do
@@ -116,8 +116,8 @@ RSpec.describe PGN::Lexer do
   end
 
   it 'records byte offsets on every token' do
-    toks = lex("1. e4 e5 1-0")
-    expect(toks[0].offset).to eq(0)   # "1."
+    toks = lex('1. e4 e5 1-0')
+    expect(toks[0].offset).to eq(0) # "1."
     expect(toks[1].offset).to eq(3)  # "e4"
     expect(toks[2].offset).to eq(6)  # "e5"
     expect(toks[3].offset).to eq(9)  # "1-0"

data/spec/notation_spec.rb

@@ -22,6 +22,11 @@ describe PGN::Notation do
                                'g1', 'f3')).to eq('Nf3')
     end
 
+    it 'generates a non-castling king walk' do
+      fen = '4k3/8/8/8/8/8/8/4K3 w - - 0 1'
+      expect(PGN::Notation.san(pos(fen), 'e1', 'e2')).to eq('Ke2')
+    end
+
     it 'generates a pawn capture with the origin file' do
       fen = 'rnbqkbnr/ppp1pppp/8/3p4/4P3/8/PPPP1PPP/RNBQKBNR w KQkq d6 0 2'
       expect(PGN::Notation.san(pos(fen), 'e4', 'd5')).to eq('exd5')

data/spec/parser_spec.rb

@@ -107,7 +107,14 @@ describe PGN do
     it 'returns original game pgn' do
       games = PGN.parse(File.read('./spec/pgn_files/fen.pgn'))
       game = games.first
-      expect(game.pgn).to eq "[Event \"Event 1\"]\n[FEN \"4brkn/4bp1p/3q2pP/8/2B3N1/1P4N1/2PP3P/1K2Q3 w - - 0 1\"]\n[PlyCount \"7\"]\n\n1. Qxe7 Qxe7 2. Ne4 Bc6 3. Nef6+ Qxf6 4. Nxf6# 1-0"
+      expected = <<~PGN.chomp
+        [Event "Event 1"]
+        [FEN "4brkn/4bp1p/3q2pP/8/2B3N1/1P4N1/2PP3P/1K2Q3 w - - 0 1"]
+        [PlyCount "7"]
+
+        1. Qxe7 Qxe7 2. Ne4 Bc6 3. Nef6+ Qxf6 4. Nxf6# 1-0
+      PGN
+      expect(game.pgn).to eq expected
     end
 
     it 'returns original game pgn for second game' do

data/spec/position_spec.rb

@@ -1,53 +1,50 @@
 require 'spec_helper'
 
 describe PGN::Position do
-
-  describe "start" do
-
-    it "should have fullmove 1" do
+  describe 'start' do
+    it 'should have fullmove 1' do
       pos = PGN::Position.start
       pos.fullmove.should == 1
     end
-    
   end
-  
-  context "disambiguating moves" do
-    describe "using SAN square disambiguation" do
-      pos = PGN::FEN.new("r1bqkb1r/pp1p1ppp/2n1pn2/8/3NP3/2N5/PPP2PPP/R1BQKB1R w KQkq - 3 6").to_position
-      next_pos = pos.move("Ndb5")
-
-      it "should move the specified piece" do
-        next_pos.board.at("d4").should be_nil
+
+  context 'disambiguating moves' do
+    describe 'using SAN square disambiguation' do
+      pos = PGN::FEN.new('r1bqkb1r/pp1p1ppp/2n1pn2/8/3NP3/2N5/PPP2PPP/R1BQKB1R w KQkq - 3 6').to_position
+      next_pos = pos.move('Ndb5')
+
+      it 'should move the specified piece' do
+        next_pos.board.at('d4').should be_nil
       end
 
-      it "should not move the other piece" do
-        next_pos.board.at("c3").should == "N"
+      it 'should not move the other piece' do
+        next_pos.board.at('c3').should == 'N'
       end
     end
 
-    describe "using discovered check" do
-      pos = PGN::FEN.new("rnbqk2r/p1pp1ppp/1p2pn2/8/1bPP4/2N1P3/PP3PPP/R1BQKBNR w KQkq - 0 5").to_position
-      next_pos = pos.move("Ne2")
+    describe 'using discovered check' do
+      pos = PGN::FEN.new('rnbqk2r/p1pp1ppp/1p2pn2/8/1bPP4/2N1P3/PP3PPP/R1BQKBNR w KQkq - 0 5').to_position
+      next_pos = pos.move('Ne2')
 
       it "should move the piece that doesn't give discovered check" do
-        next_pos.board.at("g1").should be_nil
+        next_pos.board.at('g1').should be_nil
       end
 
       it "shouldn't move the other piece" do
-        next_pos.board.at("c3").should == "N"
+        next_pos.board.at('c3').should == 'N'
       end
     end
 
-    describe "with two pawns on the same file" do
-      pos = PGN::FEN.new("r2q1rk1/4bppp/p3n3/1p2n3/4N3/1B2BP2/PP3P1P/R2Q1RK1 w - - 4 19").to_position
-      next_pos = pos.move("f4")
+    describe 'with two pawns on the same file' do
+      pos = PGN::FEN.new('r2q1rk1/4bppp/p3n3/1p2n3/4N3/1B2BP2/PP3P1P/R2Q1RK1 w - - 4 19').to_position
+      next_pos = pos.move('f4')
 
-      it "should move the pawn in front" do
-        next_pos.board.at("f3").should be_nil
+      it 'should move the pawn in front' do
+        next_pos.board.at('f3').should be_nil
       end
 
-      it "should not move the other pawn" do
-        next_pos.board.at("f2").should == "P"
+      it 'should not move the other pawn' do
+        next_pos.board.at('f2').should == 'P'
       end
     end
   end
@@ -124,4 +121,108 @@ describe PGN::Position do
       expect(parsed.to_fen.to_s).to eq(fen)
     end
   end
+
+  describe '#zobrist and equality' do
+    it 'seeds the start position with a stable hash' do
+      expect(PGN::Position.start.zobrist).to be_an(Integer)
+      expect(PGN::Position.start.zobrist).to eq(PGN::Position.start.zobrist)
+    end
+
+    it 'updates the hash after a move (and matches a fresh seed)' do
+      start = PGN::Position.start
+      after = start.move('e4')
+      expect(after.zobrist).to eq(
+        PGN::Zobrist.seed(after.board, after.player, after.castling, after.en_passant)
+      )
+    end
+
+    it 'is equal to an independently built equivalent position' do
+      a = PGN::Position.start.move('e4').move('e5')
+      b = PGN::Position.start.move('e4').move('e5')
+      expect(a).to eq(b)
+      expect(a.hash).to eq(b.hash)
+    end
+
+    it 'is not equal when only the side to move differs' do
+      a = PGN::Position.start
+      b = PGN::Position.start.move('e4')
+      expect(a).not_to eq(b)
+    end
+
+    it 'is not equal when castling rights differ' do
+      fen = 'r3k2r/8/8/8/8/8/8/R3K2R w KQkq - 0 1'
+      a = PGN::FEN.new(fen).to_position
+      b = a.move('O-O')
+      expect(a).not_to eq(b)
+    end
+
+    it 'ignores halfmove and fullmove counters for equality' do
+      a = PGN::Position.new(PGN::Board.start, :white, %w[K Q k q], nil, 0, 1)
+      b = PGN::Position.new(PGN::Board.start, :white, %w[K Q k q], nil, 7, 9)
+      expect(a).to eq(b)
+      expect(a.hash).to eq(b.hash)
+    end
+
+    it 'keeps the replay hash in sync with a fresh seed for a whole game' do
+      moves = %w[e4 c5 Nf3 d6 d4 cxd4 Nxd4 Nf6 Nc3 a6 Be2 e6]
+      pos = PGN::Position.start
+      moves.each do |m|
+        pos = pos.move(m)
+        expect(pos.zobrist).to eq(
+          PGN::Zobrist.seed(pos.board, pos.player, pos.castling, pos.en_passant)
+        ), "drift after #{m}"
+      end
+    end
+  end
+end
+
+RSpec.describe PGN::Position, '#perft' do
+  it 'returns 1 at depth 0 for the start position' do
+    expect(PGN::Position.start.perft(0)).to eq(1)
+  end
+
+  it 'matches published startpos perft values' do
+    p = PGN::Position.start
+    expect(p.perft(1)).to eq(20)
+    expect(p.perft(2)).to eq(400)
+    expect(p.perft(3)).to eq(8_902)
+    expect(p.perft(4)).to eq(197_281)
+  end
+
+  it 'matches published Kiwipete perft values' do
+    fen = 'r3k2r/p1ppqpb1/bn2pnp1/3PN3/1p2P3/2N2Q1p/PPPBBPPP/R3K2R w KQkq - 0 1'
+    p = PGN::FEN.new(fen).to_position
+    expect(p.perft(1)).to eq(48)
+    expect(p.perft(2)).to eq(2_039)
+    expect(p.perft(3)).to eq(97_862)
+  end
+
+  it 'raises ArgumentError on negative depth' do
+    expect { PGN::Position.start.perft(-1) }.to raise_error(ArgumentError)
+  end
+end
+
+RSpec.describe PGN::Position, '#legal_moves' do
+  it 'lists 20 legal moves from the start position' do
+    expect(PGN::Position.start.legal_moves.length).to eq(20)
+  end
+
+  it 'returns sorted UCI strings matching the UCI format' do
+    moves = PGN::Position.start.legal_moves
+    expect(moves).to eq(moves.sort)
+    expect(moves).to all(match(/\A[a-h][1-8][a-h][1-8][qrbn]?\z/))
+  end
+
+  it 'matches the engine direct output for the same FEN (delegation equivalence)' do
+    fen = 'r3k2r/p1ppqpb1/bn2pnp1/3PN3/1p2P3/2N2Q1p/PPPBBPPP/R3K2R w KQkq - 0 1'
+    pos = PGN::FEN.new(fen).to_position
+    expect(pos.legal_moves).to eq(PGN::Bitboard::Engine.new(fen).legal_moves)
+  end
+
+  it 'includes a promotion UCI when one is legal' do
+    # White king e1, black king h1, white pawn e7 — e7e8q must be legal.
+    fen = '8/4P3/8/8/8/8/8/4K2k w - - 0 1'
+    pos = PGN::FEN.new(fen).to_position
+    expect(pos.legal_moves).to include('e7e8q')
+  end
 end

data/spec/serializer_spec.rb

@@ -62,10 +62,10 @@ describe PGN::Serializer do
     it 'reproduces the variations.pgn movetext shape, including 2... after variations' do
       game = PGN.parse(File.read('./spec/pgn_files/variations.pgn')).first
       expected = "[Black \"Petrov\"]\n[White \"Somebody\"]\n\n" \
-                "1. e4 e5 2. Nf3 { comment } " \
-                "(2. f4 exf4 { final variation }) " \
-                "(2. Nc3 { other } 2... d5 (2... f5) 3. exd5) " \
-                "2... Nf6 *\n"
+                 '1. e4 e5 2. Nf3 { comment } ' \
+                 '(2. f4 exf4 { final variation }) ' \
+                 '(2. Nc3 { other } 2... d5 (2... f5) 3. exd5) ' \
+                 "2... Nf6 *\n"
       expect(PGN::Serializer.new(game).to_s).to eq(expected)
     end
 

data/spec/zobrist_spec.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe PGN::Zobrist do
+  it 'exposes table, side, castling, and ep_file constants' do
+    expect(PGN::Zobrist::TABLE).to be_a(Hash)
+    expect(PGN::Zobrist::TABLE.keys.sort).to eq(%w[B K N P Q R b k n p q r].sort)
+    expect(PGN::Zobrist::TABLE['P'].length).to eq(128)
+    expect(PGN::Zobrist::SIDE).to be_an(Integer)
+    expect(PGN::Zobrist::CASTLING).to be_a(Hash)
+    expect(PGN::Zobrist::CASTLING.keys.sort).to eq(%w[K Q k q].sort)
+    expect(PGN::Zobrist::EP_FILE.length).to eq(8)
+  end
+
+  it 'seeds the starting position to a stable integer' do
+    first  = PGN::Zobrist.seed(PGN::Board.start, :white, %w[K Q k q], nil)
+    second = PGN::Zobrist.seed(PGN::Board.start, :white, %w[K Q k q], nil)
+    expect(first).to eq(second)
+    expect(first).to be_an(Integer)
+  end
+
+  it 'differs when the side to move changes' do
+    white_to_move = PGN::Zobrist.seed(PGN::Board.start, :white, %w[K Q k q], nil)
+    black_to_move = PGN::Zobrist.seed(PGN::Board.start, :black, %w[K Q k q], nil)
+    expect(white_to_move).not_to eq(black_to_move)
+  end
+
+  it 'differs when castling rights change' do
+    full = PGN::Zobrist.seed(PGN::Board.start, :white, %w[K Q k q], nil)
+    no_k = PGN::Zobrist.seed(PGN::Board.start, :white, %w[Q k q], nil)
+    expect(full).not_to eq(no_k)
+  end
+
+  it 'differs when an en-passant file is present vs absent' do
+    with_ep = PGN::Zobrist.seed(PGN::Board.start, :white, %w[K Q k q], 'e3')
+    no_ep   = PGN::Zobrist.seed(PGN::Board.start, :white, %w[K Q k q], nil)
+    expect(with_ep).not_to eq(no_ep)
+  end
+
+  it 'is deterministic across processes (frozen constants)' do
+    expect(PGN::Zobrist::TABLE).to be_frozen
+    expect(PGN::Zobrist::CASTLING).to be_frozen
+    expect(PGN::Zobrist::EP_FILE).to be_frozen
+  end
+end