pgn2 2.0.0 → 2.0.2

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,50 @@ describe PGN::Game do
       end
     end
   end
+
+  describe 'node mutation round-trip' do
+    non_round_trip = %w[doublequotes.pgn specialcharacters.pgn].freeze
+
+    # 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/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,222 @@
+require 'spec_helper'
+
+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/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/position_attack_spec.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe PGN::Position, 'attack helpers' do
+  describe '#in_check?' do
+    it 'is false for the start position' do
+      expect(PGN::Position.start.in_check?).to be(false)
+    end
+
+    it 'is true when the side to move is checked' do
+      # White king on e1, black rook on e2 giving check.
+      pos = PGN::FEN.new('4k3/8/8/8/8/8/4r3/4K3 w - - 0 1').to_position
+      expect(pos.in_check?).to be(true)
+    end
+
+    it 'is false when a piece blocks the check' do
+      pos = PGN::FEN.new('4k3/8/8/8/8/8/4p3/4R1K1 w - - 0 1').to_position
+      expect(pos.in_check?).to be(false)
+    end
+
+    it 'is false for black to move when black is not in check' do
+      pos = PGN::FEN.new('rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR b KQkq - 0 1').to_position
+      expect(pos.in_check?).to be(false)
+    end
+  end
+
+  describe '#attackers' do
+    it 'lists the attacking squares for the opponent color' do
+      pos = PGN::FEN.new('4k3/8/8/8/8/8/4r3/4K3 w - - 0 1').to_position
+      # White king on e1 is attacked by the black rook on e2.
+      expect(pos.attackers('e1')).to include('e2')
+    end
+
+    it 'lists pawn attackers' do
+      # White pawn d5 attacks e6 and c6; ask for attackers of e6 by white.
+      pos = PGN::FEN.new('4k3/8/8/3P4/8/8/8/4K3 w - - 0 1').to_position
+      expect(pos.attackers('e6', 'w')).to include('d5')
+    end
+
+    it 'lists knight attackers' do
+      pos = PGN::FEN.new('4k3/8/8/8/8/2N5/8/4K3 w - - 0 1').to_position
+      expect(pos.attackers('e4', 'w')).to include('c3')
+    end
+
+    it 'lists bishop/rook/queen attackers' do
+      pos = PGN::FEN.new('4k3/8/8/8/8/8/8/Q3K3 w - - 0 1').to_position
+      expect(pos.attackers('a8', 'w')).to include('a1')
+    end
+
+    it 'returns an empty array when nothing attacks the square' do
+      pos = PGN::Position.start
+      expect(pos.attackers('e4')).to eq([])
+    end
+  end
+end

data/spec/position_legal_spec.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe PGN::Position, '#legal?' do
+  skip 'native extension PGN::Bitboard::Engine not compiled' unless PGN::Bitboard.const_defined?(:Engine)
+
+  let(:start) { PGN::Position.start }
+
+  it 'accepts SAN pawn moves' do
+    expect(start.legal?('e4')).to be(true)
+    expect(start.legal?('d4')).to be(true)
+    expect(start.legal?('e5')).to be(false) # no pawn on e5 can move
+  end
+
+  it 'accepts SAN piece moves' do
+    expect(start.legal?('Nf3')).to be(true)
+    expect(start.legal?('Nc3')).to be(true)
+    expect(start.legal?('Nb1')).to be(false) # no piece can move to b1 from start
+  end
+
+  it 'accepts UCI strings' do
+    expect(start.legal?('e2e4')).to be(true)
+    expect(start.legal?('e2e5')).to be(false)
+    expect(start.legal?('g1f3')).to be(true)
+    expect(start.legal?('b1a3')).to be(true) # knight on b1 can reach a3
+    expect(start.legal?('b1b3')).to be(false) # knights do not move two squares
+  end
+
+  it 'accepts SAN with check/mate suffixes' do
+    # Scholar's mate position before the queen move: 1. e4 e5 2. Bc4 Nc6 3. Qh5 Nf6?? 4. Qxf7#
+    pos = PGN::FEN.new('r1bqkb1r/pppp1ppp/2n2n2/4p2Q/2B1P3/8/PPPP1PPP/RNB1K1NR w KQkq - 4 4').to_position
+    expect(pos.legal?('Qxf7#')).to be(true)
+    expect(pos.legal?('Qxf7+')).to be(true)
+    expect(pos.legal?('Qxf7')).to be(true)
+  end
+
+  it 'accepts redundant disambiguation in SAN' do
+    # Two knights (b1 and f1) can reach d2; "Nbd2" and "Nfd2" are both legal,
+    # and the unambiguous "Nd2" is rejected as ambiguous.
+    pos = PGN::FEN.new('4k3/8/8/8/8/8/8/1N3NK1 w - - 0 1').to_position
+    expect(pos.legal?('Nbd2')).to be(true)
+    expect(pos.legal?('Nfd2')).to be(true)
+    expect(pos.legal?('Nd2')).to be(false) # ambiguous, no disambiguation
+  end
+
+  it 'handles castling SAN and UCI' do
+    pos = PGN::FEN.new('r3k2r/8/8/8/8/8/8/R3K2R w KQkq - 0 1').to_position
+    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 'handles promotion SAN and UCI' do
+    pos = PGN::FEN.new('8/P7/8/8/8/8/8/4k2K w - - 0 1').to_position
+    expect(pos.legal?('a8=Q')).to be(true)
+    expect(pos.legal?('a8=N')).to be(true)
+    expect(pos.legal?('a7a8q')).to be(true)
+    expect(pos.legal?('a7a8n')).to be(true)
+  end
+
+  it 'handles en passant SAN' do
+    pos = PGN::FEN.new('rnbqkbnr/ppp1pppp/8/3pP3/8/8/PPPP1PPP/RNBQKBNR w KQkq d6 0 3').to_position
+    expect(pos.legal?('exd6')).to be(true)
+    expect(pos.legal?('e5d6')).to be(true)
+  end
+
+  it 'rejects moves that leave the king in check' do
+    # White king on e1, rook pinning the knight on e2 to the king along the e-file.
+    pos = PGN::FEN.new('4r3/8/8/8/8/8/4N3/4K3 w - - 0 1').to_position
+    expect(pos.legal?('Nf4')).to be(false) # knight moves away, king is in check from rook
+  end
+
+  it 'returns false for malformed input' do
+    expect(start.legal?('z9z9')).to be(false)
+    expect(start.legal?('Qxh8')).to be(false) # no legal queen move from start
+    expect(start.legal?('')).to be(false)
+  end
+
+  it 'respects the side to move' do
+    # Black to move; a white move should be illegal.
+    pos = PGN::FEN.new('rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR b KQkq - 0 1').to_position
+    expect(pos.legal?('e4')).to be(false)
+    expect(pos.legal?('e5')).to be(true)
+  end
+end
+
+RSpec.describe PGN::Position, '#legal_moves_san' do
+  skip 'native extension PGN::Bitboard::Engine not compiled' unless PGN::Bitboard.const_defined?(:Engine)
+
+  it 'returns 20 sorted SAN moves for the start position' do
+    sans = PGN::Position.start.legal_moves_san
+    expect(sans.length).to eq(20)
+    expect(sans).to eq(sans.sort)
+    expect(sans).to include('e4', 'Nf3', 'd4', 'a3')
+  end
+
+  it 'includes castling and promotion SAN' do
+    pos = PGN::FEN.new('r3k2r/8/8/8/8/8/8/R3K2R w KQkq - 0 1').to_position
+    sans = pos.legal_moves_san
+    expect(sans).to include('O-O', 'O-O-O')
+  end
+
+  it 'produces SAN whose moves are all legal? and vice versa' do
+    pos = PGN::FEN.new('r1bqkb1r/pppp1ppp/2n2n2/4p2Q/2B1P3/8/PPPP1PPP/RNB1K1NR w KQkq - 4 4').to_position
+    sans = pos.legal_moves_san
+    uci = pos.legal_moves
+    expect(sans.length).to eq(uci.length)
+    expect(sans.all? { |s| pos.legal?(s) }).to be(true)
+  end
+
+  it 'round-trips: every legal UCI maps to a SAN that legal? accepts' do
+    pos = PGN::FEN.new('rnbqkbnr/ppp1pppp/8/3pP3/8/8/PPPP1PPP/RNBQKBNR w KQkq d6 0 3').to_position
+    pos.legal_moves.each do |uci|
+      from = uci[0, 2]
+      to = uci[2, 2]
+      promo = uci[5]
+      san = PGN::Notation.san(pos, from, to, promo)
+      expect(pos.legal?(san)).to be(true), "#{san} (from #{uci}) should be legal"
+    end
+  end
+end