pgn2 1.5.0 → 2.0.1

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,10 +123,70 @@ 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
     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

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/movetext_clean_spec.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe PGN::MoveText, '#clean_text' do
+  it 'strips a single outermost brace pair' do
+    mt = PGN::MoveText.new('e4', nil, '{a comment}')
+    expect(mt.comment).to eq('a comment')
+  end
+
+  it 'is idempotent on a nested-brace comment' do
+    mt = PGN::MoveText.new('e4', nil, '{a {b} c}')
+    once = mt.comment
+    # Re-running clean_text (as MoveText.new would) must not strip the inner braces.
+    twice = PGN::MoveText.new('e4', nil, once).comment
+    expect(twice).to eq(once)
+    expect(twice).to eq('a {b} c')
+  end
+
+  it 'collapses whitespace and strips' do
+    mt = PGN::MoveText.new('e4', nil, "{  multi\nline  }")
+    expect(mt.comment).to eq('multi line')
+  end
+
+  it 'returns nil for a nil comment' do
+    expect(PGN::MoveText.new('e4').comment).to be_nil
+  end
+end
+
+RSpec.describe PGN::Game, '#moves= with braced comments' do
+  it 'reuses a MoveText unchanged when no castling fix is needed' do
+    mt = PGN::MoveText.new('e4', nil, 'a {b} c')
+    game = PGN::Game.new([mt])
+    expect(game.moves.first).to be(mt)
+    expect(game.moves.first.comment).to eq('a {b} c')
+  end
+
+  it 'rebuilds without corrupting a nested-brace comment when fixing castling' do
+    mt = PGN::MoveText.new('0-0', nil, 'a {b} c')
+    game = PGN::Game.new([mt])
+    expect(game.moves.first.notation).to eq('O-O')
+    expect(game.moves.first.comment).to eq('a {b} c')
+  end
+end

data/spec/node_spec.rb

@@ -0,0 +1,240 @@
+require 'spec_helper'
+
+# Helpers for order-independent variation comparison. The parser's
+# `variation_list` rule is right-recursive, so a move's variations are stored
+# in reverse of their PGN-text order; round-tripping flips that order each
+# parse. We therefore compare variation trees as sorted signatures (the same
+# approach the existing game_spec round-trip gate uses), and reference
+# variations by notation rather than by index.
+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
+
+describe PGN::Node do
+  let(:game) { PGN.parse(File.read(File.expand_path('pgn_files/variations.pgn', __dir__), encoding: Encoding::ISO_8859_1)).first }
+  let(:root) { game.root }
+
+  it 'root is a root node with no move' do
+    expect(root).to be_root
+    expect(root.move).to be_nil
+    expect(root.notation).to be_nil
+    expect(root.previous).to be_nil
+  end
+
+  it 'main_line matches game.moves notations (root excluded)' do
+    expect(root.main_line.map(&:notation)).to eq(game.moves.map(&:notation))
+  end
+
+  it 'main_line is an Enumerator without a block' do
+    expect(root.main_line).to be_an(Enumerator)
+  end
+
+  it 'children of the position after 1.e4 e5 are Nf3 (main), Nc3, f4 (any order)' do
+    node = root.next.next # after e4 (white), after e5 (black) => before Nf3
+    expect(node.children.map(&:notation)).to contain_exactly('Nf3', 'Nc3', 'f4')
+    expect(node.next.notation).to eq('Nf3') # mainline continuation is first
+    expect(node.variations.map(&:notation)).to contain_exactly('Nc3', 'f4')
+  end
+
+  it 'nested variation f5 is a sibling of d5 under the Nc3 node' do
+    nc3_node = root.next.next.children.find { |n| n.notation == 'Nc3' }
+    expect(nc3_node.children.map(&:notation)).to contain_exactly('d5', 'f5')
+  end
+
+  it 'previous walks back to the root' do
+    node = root.next.next.next # Nf3 node
+    expect(node.previous.notation).to eq('e5')
+    expect(node.previous.previous.notation).to eq('e4')
+    expect(node.previous.previous.previous).to be_root
+  end
+
+  describe '#position' do
+    it 'root position is the starting position' do
+      expect(root.position.to_fen.to_s).to eq(PGN::Position.start.to_fen.to_s)
+    end
+
+    it 'main_line positions match game.positions[1..]' do
+      expect(root.main_line.map { |n| n.position.to_fen.to_s })
+        .to eq(game.positions[1..].map { |p| p.to_fen.to_s })
+    end
+
+    it 'a variation node position is replayed from the root' do
+      # After 1.e4 e5 2.Nc3 (the Nc3 variation first move)
+      nc3_node = root.next.next.children.find { |n| n.notation == 'Nc3' }
+      expected = PGN::Position.start.move('e4').move('e5').move('Nc3')
+      expect(nc3_node.position.to_fen.to_s).to eq(expected.to_fen.to_s)
+    end
+
+    it 'is cached (returns the same object on second call)' do
+      node = root.next
+      expect(node.position).to equal(node.position)
+    end
+  end
+
+  describe '#add_variation' do
+    it 'appends a single-SAN variation branching before the next move' do
+      root.next.next.add_variation('Nc6')
+      expect(game.moves[2].variations.map { |v| v.map(&:notation) })
+        .to include(['Nc6'], %w[Nc3 d5 exd5], %w[f4 exf4])
+    end
+
+    it 'appends a multi-move variation line' do
+      root.next.next.add_variation(%w[Nc6 Bc4])
+      expect(game.moves[2].variations.map { |v| v.map(&:notation) }).to include(%w[Nc6 Bc4])
+    end
+
+    it 'normalizes castling 0 -> O' do
+      g = PGN::Game.new(%w[e4 e5 Nf3])
+      g.root.next.next.add_variation('0-0')
+      expect(g.moves[2].variations.map { |v| v.map(&:notation) }).to include(['O-O'])
+    end
+
+    it 'round-trips (variation set stable under re-parse)' do
+      root.next.next.add_variation(%w[Nc6 Bc4])
+      reparsed = PGN.parse(game.to_pgn).first
+      expect(tree_sig(reparsed)).to eq(tree_sig(game))
+    end
+  end
+
+  describe '#add_variation at a terminal node' do
+    it 'raises ArgumentError' do
+      g = PGN::Game.new(%w[e4 e5])
+      last = g.root.main_line.to_a.last
+      expect { last.add_variation('Nf6') }.to raise_error(ArgumentError)
+    end
+  end
+
+  describe '#add_main_variation' do
+    it 'extends the line at a terminal node' do
+      g = PGN::Game.new(%w[e4 e5])
+      g.root.main_line.to_a.last.add_main_variation('Nf3')
+      expect(g.moves.map(&:notation)).to eq(%w[e4 e5 Nf3])
+    end
+
+    it 'inserts a new mainline move and demotes the old continuation to a variation' do
+      node = root.next.next # position before Nf3
+      node.add_main_variation('Nc6')
+      expect(game.moves.map(&:notation)).to eq(%w[e4 e5 Nc6])
+      # old mainline Nf3 + Nf6 is now a variation of Nc6
+      expect(game.moves[2].variations.map { |v| v.map(&:notation) }).to include(%w[Nf3 Nf6])
+    end
+  end
+
+  describe 'variation reordering' do
+    # Storage order of Nf3's variations is reverse of the PGN text
+    # (`[f4-line, Nc3-line]`) because the parser reverses variation order.
+    # Tests reference variations by notation, never by index.
+    let(:branch) { root.next.next }
+    let(:nf3) { game.moves[2] }
+
+    def find_variation(notation)
+      branch.children.find { |n| n.notation == notation }
+    end
+
+    it 'promote moves a variation one slot toward mainline' do
+      find_variation('Nc3').promote
+      # Nc3 was behind f4 in storage; now it is first (just after the mainline)
+      expect(nf3.variations.first.first.notation).to eq('Nc3')
+    end
+
+    it 'promote is a no-op for the first variation' do
+      find_variation('f4').promote # f4 is already the first stored variation
+      expect(nf3.variations.first.first.notation).to eq('f4')
+    end
+
+    it 'demote moves a variation one slot toward the end' do
+      find_variation('f4').demote
+      expect(nf3.variations.last.first.notation).to eq('f4')
+    end
+
+    it 'demote at index 0 (mainline) is the inverse swap' do
+      branch.next.demote # Nf3 (mainline) -> variation #1
+      # the first stored variation (f4) becomes the new mainline
+      expect(game.moves[2].notation).to eq('f4')
+      expect(game.moves[3].notation).to eq('exf4')
+      # old mainline Nf3 + Nf6 is now the first variation of f4
+      expect(game.moves[2].variations.first.map(&:notation)).to eq(%w[Nf3 Nf6])
+    end
+
+    it 'promote_to_main makes a variation the new mainline' do
+      find_variation('Nc3').promote_to_main
+      expect(game.moves.map(&:notation)).to eq(%w[e4 e5 Nc3 d5 exd5])
+      # old mainline Nf3 + Nf6 is now a variation of Nc3
+      expect(game.moves[2].variations.map { |v| v.map(&:notation) }).to include(%w[Nf3 Nf6])
+    end
+
+    it 'demote_to_last moves a variation to the end' do
+      find_variation('f4').demote_to_last
+      expect(nf3.variations.last.first.notation).to eq('f4')
+    end
+
+    it 'demote_to_last on the mainline makes it the last variation' do
+      branch.next.demote_to_last # Nf3 -> last variation
+      # the last stored variation (Nc3) is promoted to mainline
+      expect(game.moves[2].notation).to eq('Nc3')
+      # old mainline Nf3 + Nf6 is the LAST variation of Nc3
+      expect(game.moves[2].variations.last.map(&:notation)).to eq(%w[Nf3 Nf6])
+    end
+
+    it 'every reorder round-trips (variation set stable under re-parse)' do
+      find_variation('Nc3').promote_to_main
+      reparsed = PGN.parse(game.to_pgn).first
+      expect(tree_sig(reparsed)).to eq(tree_sig(game))
+    end
+  end
+
+  describe 'flatten-on-mutation for same-point nested variations' do
+    it 'flattens ( V1 ( V2 ) ) into flat siblings on promote_to_main' do
+      # 1. e4 ( e5 ( e6 ) ) ( d5 )  — e5, e6, d5 all branch before e4 (at root).
+      g = PGN.parse(%([White "x"]\n\n1. e4 ( e5 ( e6 ) ) ( d5 ) *\n).force_encoding(Encoding::ISO_8859_1)).first
+      expect(g.root.children.map(&:notation)).to contain_exactly('e4', 'e5', 'e6', 'd5')
+      e6 = g.root.children.find { |n| n.notation == 'e6' }
+      e6.promote_to_main
+      # e6 is now the mainline; e4, e5, d5 are flat variations of e6
+      expect(g.moves.map(&:notation)).to eq(['e6'])
+      expect(g.moves[0].variations.map { |v| v.first.notation }).to contain_exactly('e4', 'e5', 'd5')
+      reparsed = PGN.parse(g.to_pgn).first
+      expect(tree_sig(reparsed)).to eq(tree_sig(g))
+    end
+  end
+
+  describe '#delete' do
+    let(:branch) { root.next.next }
+    let(:nf3) { game.moves[2] }
+
+    it 'removes a variation' do
+      branch.children.find { |n| n.notation == 'f4' }.delete
+      expect(nf3.variations.map { |v| v.first.notation }).to contain_exactly('Nc3')
+    end
+
+    it 'removing the mainline continuation promotes the first variation' do
+      branch.next.delete # delete Nf3 (mainline)
+      # the first stored variation (f4) takes its place
+      expect(game.moves[2].notation).to eq('f4')
+      expect(game.moves[3].notation).to eq('exf4')
+      # the remaining variation (Nc3) is now f4's variation
+      expect(game.moves[2].variations.map { |v| v.first.notation }).to contain_exactly('Nc3')
+    end
+
+    it 'removing the mainline continuation with no variations truncates' do
+      g = PGN::Game.new(%w[e4 e5 Nf3 Nf6])
+      nf3 = g.root.main_line.to_a[2]
+      nf3.delete
+      expect(g.moves.map(&:notation)).to eq(%w[e4 e5])
+    end
+
+    it 'round-trips after delete' do
+      branch.children.find { |n| n.notation == 'f4' }.delete
+      reparsed = PGN.parse(game.to_pgn).first
+      expect(tree_sig(reparsed)).to eq(tree_sig(game))
+    end
+  end
+end

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/outcome_spec.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe PGN::Position, 'outcome' do
+  skip 'native extension PGN::Bitboard::Engine not compiled' unless PGN::Bitboard.const_defined?(:Engine)
+
+  it 'is nil for the start position' do
+    expect(PGN::Position.start.outcome).to be_nil
+  end
+
+  it 'detects checkmate (fool\'s mate)' do
+    pos = PGN::FEN.new('rnb1kbnr/pppp1ppp/8/4p3/6Pq/5P2/PPPPP2P/RNBQKBNR w KQkq - 1 3').to_position
+    expect(pos.outcome).to eq(:checkmate)
+    expect(pos.checkmate?).to be(true)
+    expect(pos.stalemate?).to be(false)
+  end
+
+  it 'detects stalemate' do
+    pos = PGN::FEN.new('7k/5Q2/6K1/8/8/8/8/8 b - - 0 1').to_position
+    expect(pos.outcome).to eq(:stalemate)
+    expect(pos.stalemate?).to be(true)
+    expect(pos.in_check?).to be(false)
+  end
+
+  it 'detects insufficient material: K vs K' do
+    pos = PGN::FEN.new('4k3/8/8/8/8/8/8/4K3 w - - 0 1').to_position
+    expect(pos.insufficient_material?).to be(true)
+    expect(pos.outcome).to eq(:draw)
+  end
+
+  it 'detects insufficient material: K+B vs K' do
+    pos = PGN::FEN.new('4k3/8/8/8/8/8/8/3BK3 w - - 0 1').to_position
+    expect(pos.insufficient_material?).to be(true)
+  end
+
+  it 'detects insufficient material: K+N vs K' do
+    pos = PGN::FEN.new('4k3/8/8/8/8/8/8/3NK3 w - - 0 1').to_position
+    expect(pos.insufficient_material?).to be(true)
+  end
+
+  it 'does not consider K+Q vs K insufficient' do
+    pos = PGN::FEN.new('4k3/8/8/8/8/8/8/3QK3 w - - 0 1').to_position
+    expect(pos.insufficient_material?).to be(false)
+  end
+
+  it 'detects the 50-move rule' do
+    pos = PGN::FEN.new('4k3/8/8/8/8/8/8/4K3 w - - 100 60').to_position
+    expect(pos.fifty_move?).to be(true)
+    expect(pos.outcome).to eq(:draw)
+  end
+
+  it 'does not trigger 50-move before 100 halfmoves' do
+    pos = PGN::FEN.new('4k3/8/8/8/8/8/8/4K3 w - - 99 60').to_position
+    expect(pos.fifty_move?).to be(false)
+  end
+end
+
+RSpec.describe PGN::Game, 'outcome' do
+  skip 'native extension PGN::Bitboard::Engine not compiled' unless PGN::Bitboard.const_defined?(:Engine)
+
+  it 'is nil for a game in progress' do
+    game = PGN::Game.new(%w[e4 e5 Nf3 Nc6])
+    expect(game.outcome).to be_nil
+  end
+
+  it 'detects a checkmate game (scholar\'s mate)' do
+    game = PGN::Game.new(%w[e4 e5 Bc4 Nc6 Qh5 Nf6 Qxf7])
+    expect(game.outcome).to eq(:checkmate)
+  end
+
+  it 'detects a stalemate game' do
+    # Black king h8, white queen f7, white king g6; black to move is stalemated.
+    game = PGN::Game.new(
+      %w[],
+      { 'FEN' => '7k/5Q2/6K1/8/8/8/8/8 b - - 0 1' },
+      '1/2-1/2'
+    )
+    expect(game.outcome).to eq(:stalemate)
+  end
+
+  it 'detects threefold repetition' do
+    # 1. Nf3 Nf6 2. Ng1 Ng8 repeats the start position three times.
+    game = PGN::Game.new(%w[Nf3 Nf6 Ng1 Ng8 Nf3 Nf6 Ng1 Ng8])
+    expect(game.threefold?).to be(true)
+    expect(game.outcome).to eq(:draw)
+  end
+
+  it 'does not claim threefold without three repeats' do
+    game = PGN::Game.new(%w[Nf3 Nf6 Ng1])
+    expect(game.threefold?).to be(false)
+  end
+end

data/spec/parser_left_recursion_spec.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe 'left-recursive parser list rules' do
+  let(:pgn) do
+    +<<~PGN
+      [Event "A"]
+      [Site "B"]
+      [Event "C"]
+      [White "W"]
+      [Black "X"]
+
+      1. e4 (1...c5 (1...d5)) (1...e5) *
+    PGN
+  end
+  let(:game) { PGN.parse(pgn).first }
+
+  it 'preserves the legacy reversed tag order' do
+    expect(game.tags.keys).to eq(%w[Black White Event Site])
+  end
+
+  it 'keeps first-occurrence-wins on duplicate tags' do
+    expect(game.tags['Event']).to eq('A')
+  end
+
+  it 'preserves the legacy reversed variation order' do
+    variations = game.moves.first.variations.map { |v| v.map(&:notation) }
+    expect(variations).to eq([%w[e5], %w[c5]])
+  end
+
+  it 'keeps nested variations inside their parent' do
+    c5 = game.moves.first.variations.last
+    expect(c5.map(&:notation)).to eq(%w[c5])
+    expect(c5.first.variations.map { |v| v.map(&:notation) }).to eq([%w[d5]])
+  end
+end

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