pgn2 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 33036a2920baf0e170efc5e1c387c2a53ae91fe19ad19cf745d4d6f049c9fe20
-  data.tar.gz: 93ccbe0289a72f4af5fb8367a4d1f5bdc0c1d5eb77f1a65e3381b7d17f5d3822
+  metadata.gz: 9d90a73cdcc2fc1b2765b35315935c6f20272a0e2374863d0d7c491a21f815ff
+  data.tar.gz: e4b34dfcb1e2d0c63ed479d338a0d58f3808f965db99000844cf7dcfa3af8fc9
 SHA512:
-  metadata.gz: 25ed517772982909d896b4b372308d235574db54aa44f3ff98f5201f9055120fc64d19fcd634c6676f7bfb66cf5e4de483a2a9ae13293b3162781339434bfac1
-  data.tar.gz: bf2a935f6aa4fedffb5976b0febc5eb351354165275d8b248eac99f7a713d74cf6acb3cb9e0be51c6030a55481663173ab5c9008cf5dfa67904bd09ac4e271f5
+  metadata.gz: b222778b4e25b13fbe5e62fe694d1e5189099d8cafd7b5a15f579e3df7413aa60f43a69ee299d3a37fa312c3baf25e798a54e432ad199ec118ebd56e35b9949b
+  data.tar.gz: eacb82757bb6876272f320b6b5402a449d3954d0c39052ef4304682c00435b559b49a29379f77a9c7f34dbbf210c4b1865b59df66f19ae1a72bfb5c0050e1df7

data/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## 1.4.0 (unreleased)
+
+### Summary
+
+New `PGN::Notation` module that *generates* Standard Algebraic Notation
+(SAN) for a single coordinate move (origin square, destination square,
+optional promotion) given the position before the move. The rest of the
+gem only *parses* SAN; this is the reverse direction, needed to render
+moves stored as coordinates (e.g. `e2`-`e4`) in standard chess notation.
+
+### Added
+- `PGN::Notation.san(position, from, to, promotion = nil)` and the
+  convenience `PGN::Notation.san_from_fen(fen, from, to, promotion = nil)`.
+  Builds full SAN: piece letter, capture (`x`), castling (`O-O`/`O-O-O`),
+  pawn capture file (`exd5`), promotion (`=Q`), legal-move disambiguation
+  (file / rank / full square, respecting pins), and check (`+`) / checkmate
+  (`#`) suffixes. Checkmate detection drives full legal-move generation for
+  the side to move (the gem's first move generator). Raise `ArgumentError`
+  if the origin square is empty.
+- New `spec/notation_spec.rb`; all 201 specs green. A round-trip harness over
+  every parseable fixture reproduces the original SAN of all 277 moves
+  exactly (including disambiguation and `+`/`#` suffixes).
+
+### Changed (parser performance)
+- `PGN::Lexer#scan_one` now dispatches on the leading byte of the next
+  token via a frozen `BYTE_DISPATCH` table (with an `ALL_RULES` fallback),
+  trying only the 1-2 rules that can match that byte instead of walking all
+  nine rules in order. Profiling had `StringScanner#scan` at ~23% of parse
+  CPU and the rule loop ~38% inclusive; the dispatch nearly halves scan time.
+- `PGN::PgnParser#next_token` mutates the lexer's `[type, value]` pair in
+  place rather than allocating a second translated pair — one array per token
+  is the Racc floor.
+- Net (500 immortal games): parse-only throughput +25% (305 → 203 ms/i),
+  parse allocations −17% (347037 → 288537 objects / 17977414 → 15640374
+  bytes), parse+replay allocations −7% (831530 → 773030 objects). Serialized
+  PGN/FEN output stays byte-identical; all 201 specs green.
+
 ## 1.3.0 (2026-08-13)
 
 ### Summary

data/README.md

@@ -122,6 +122,29 @@ _ _ _ ♙ _ _ _ _
 => r1bk3r/p2pBpNp/n4n2/1p1NP2P/6P1/3P4/P1P1K3/q5b1 b - - 1 22
 ```
 
+### Generating SAN from coordinates
+
+{PGN::Notation} is the reverse of {PGN::Move}: it *builds* Standard
+Algebraic Notation for a coordinate move (origin square, destination square,
+optional promotion) given the position before the move. Use it to render
+moves stored as coordinates in standard chess notation.
+
+```
+> PGN::Notation.san(PGN::Position.start, "g1", "f3")
+=> "Nf3"
+
+> PGN::Notation.san_from_fen("rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1", "e2", "e4")
+=> "e4"
+
+> fen = "r3k2r/8/8/8/8/8/8/R3K2R w KQkq - 0 1"
+> PGN::Notation.san_from_fen(fen, "e1", "g1")
+=> "O-O"
+```
+
+It handles captures, en passant, promotions, legal-move disambiguation
+(file / rank / full square, respecting pins), and check (`+`) / checkmate
+(`#`) suffixes.
+
 ## Benchmarks
 
 A reproducible profiling harness lives in `bench/`. It measures the
@@ -181,12 +204,12 @@ Parser — 500 immortal games (`bench/profile_parse.rb`):
 
 | Metric | original `pgn` | pgn2 | Δ |
 |---|---:|---:|---:|
-| Parse-only allocations (objects) | 1248065 | 347037 | -901028 (-72.2%) |
-| Parse-only allocations (bytes) | 120370470 | 17977414 | -102393056 (-85.1%) |
-| Parse + replay allocations (objects) | 3778073 | 831530 | -2946543 (-78.0%) |
-| Parse + replay allocations (bytes) | 249570048 | 47966112 | -201603936 (-80.8%) |
-| Parse-only throughput | 1461 ms/i | 305 ms/i | ~4.8x faster |
-| Parse + replay throughput | 1938 ms/i | 534 ms/i | ~3.6x faster |
+| Parse-only allocations (objects) | 1248065 | 288537 | -959528 (-76.9%) |
+| Parse-only allocations (bytes) | 120370470 | 15640374 | -104730096 (-87.0%) |
+| Parse + replay allocations (objects) | 3778073 | 773030 | -3005043 (-79.5%) |
+| Parse + replay allocations (bytes) | 249570048 | 45626128 | -203943920 (-81.7%) |
+| Parse-only throughput | 1461 ms/i | 203 ms/i | ~7.2x faster |
+| Parse + replay throughput | 1938 ms/i | 484 ms/i | ~4.0x faster |
 
 What changed to get there:
 
@@ -239,9 +262,19 @@ What changed to get there:
     must clone the index every move and every move pays maintenance that pawns
     (the common case, geometry-fixed origins) can't use — so it was rejected
     and reverted. The 0x88 board alone is the winner.
+15. `PGN::Lexer#scan_one` — byte-dispatch: the leading byte of the next
+    token selects the 1-2 `RULES` that can possibly match it (a frozen
+    `BYTE_DISPATCH` table; `ALL_RULES` fallback) instead of walking all nine
+    rules in order. `StringScanner#scan` was ~23% of parse CPU and the rule
+    loop ~38% inclusive; the dispatch nearly halves scan time. `PgnParser#
+    next_token` now mutates the lexer's `[type, value]` pair in place instead
+    of allocating a second translated pair (one array per token is the Racc
+    floor). Parse-only throughput +25% (305 → 203 ms/i), parse allocations
+    −17% (347037 → 288537 objects / 17977414 → 15640374 bytes for 500 games).
+    Output byte-identical.
 
 Public output (FEN, PGN) is byte-identical to the original gem; the full
-suite (182 examples) stays green. See `bench/IMPROVEMENTS.md` for the per-step
+suite (201 examples) stays green. See `bench/IMPROVEMENTS.md` for the per-step
 before/after deltas that produced these tables.
 
 ## Installation

data/bench/baseline_parse.txt

@@ -1,25 +1,25 @@
 Corpus: 500 copies of the immortal game
 
 === 1. Parse-only allocations (500 games) ===
-total_allocated objects: 347037
-total_allocated bytes:   17977414
+total_allocated objects: 288537
+total_allocated bytes:   15640374
 
 === 2. Parse + replay allocations (500 games) ===
-total_allocated objects: 831530
-total_allocated bytes:   47966112
+total_allocated objects: 773030
+total_allocated bytes:   45626128
 
 === 3. Parse-only throughput (ips) ===
 ruby 4.0.5 (2026-05-20 revision 64336ffd0e) +PRISM [x86_64-linux]
 Warming up --------------------------------------
      parse 500 games     1.000 i/100ms
 Calculating -------------------------------------
-     parse 500 games      4.053 (± 0.0%) i/s  (246.70 ms/i) -     21.000 in   5.180770s
+     parse 500 games      4.926 (±20.3%) i/s  (203.01 ms/i) -     25.000 in   5.075163s
 
 === 4. Parse + replay throughput (ips) ===
 ruby 4.0.5 (2026-05-20 revision 64336ffd0e) +PRISM [x86_64-linux]
 Warming up --------------------------------------
 parse+replay 500 games     1.000 i/100ms
 Calculating -------------------------------------
-parse+replay 500 games      1.872 (± 0.0%) i/s  (534.26 ms/i) -     10.000 in   5.342615s
+parse+replay 500 games      2.065 (± 0.0%) i/s  (484.34 ms/i) -     11.000 in   5.327699s
 
 Done. Compare this file against bench/baseline_parse.txt after optimizations.

data/lib/pgn/lexer.rb

@@ -117,6 +117,39 @@ module PGN
       [:tag_name,         TAG_NAME,         false]
     ].freeze.each(&:freeze)
 
+    # Byte-dispatch table: maps the leading byte of the next token to the
+    # ordered list of RULES indices that could possibly match it. This lets
+    # {#scan_one} try one or two regexes for the common tokens instead of
+    # walking all nine rules in order (StringScanner#scan was ~23% of parse
+    # CPU and the rule loop ~38% inclusive per profiling). The order within
+    # each list mirrors RULES, so tokenization is byte-compatible with the
+    # linear scan. Indices: 0 wsp, 1 pgn_comment, 2 game_termination,
+    # 3 san_move, 4 move_number, 5 nag, 6 comment, 7 string, 8 tag_name.
+    BYTE_DISPATCH = begin
+      h = {
+        9 => [0], 10 => [0], 11 => [0], 12 => [0], 13 => [0], 32 => [0], # whitespace
+        37 => [1],                                            # % pgn_comment
+        42 => [2],                                            # * game_termination
+        34 => [7],                                            # " string
+        123 => [6],                                           # { comment
+        36 => [5], 63 => [5], 33 => [5], # $ ? ! nag
+        48 => [2, 3, 4, 8], 49 => [2, 4, 8], # 0, 1 (term/castle/num/tag)
+        95 => [8] # _ tag_name
+      }
+      (50..57).each { |b| h[b] = [4, 8] }                  # 2..9 move_number/tag_name
+      [66, 75, 78, 79, 81, 82].each { |b| h[b] = [3, 8] }  # B K N O Q R san_move/tag
+      (97..104).each { |b| h[b] = [3, 8] }                 # a-h pawn san_move/tag
+      # other tag_name letters
+      ((65..90).to_a + (105..122).to_a - [66, 75, 78, 79, 81, 82]).each do |b|
+        h[b] = [8]
+      end
+      h.each_value(&:freeze)
+      h.freeze
+    end
+
+    # Fallback for bytes not in BYTE_DISPATCH: try every rule in order.
+    ALL_RULES = (0...RULES.length).to_a.freeze
+
     # Single-character literals, matched by their byte value: [type, frozen value].
     LITERAL_BYTES = {
       91 => [:lbracket, '['], # [
@@ -185,14 +218,17 @@ module PGN
     # Try each terminal rule in order; return the matched string for the
     # first match (stashing its type and discarded flag in +@scan_type+ /
     # +@scan_discarded+ so the caller avoids allocating a 3-element tuple),
-    # or raise if nothing matches at the current position.
+    # or raise if nothing matches at the current position. Uses
+    # {BYTE_DISPATCH} to try only the rules that can match the leading byte.
     def scan_one
-      RULES.each do |(type, re, discarded)|
-        if (m = @ss.scan(re))
-          @scan_type = type
-          @scan_discarded = discarded
-          return m
-        end
+      indices = BYTE_DISPATCH[@input.getbyte(@ss.pos)] || ALL_RULES
+      indices.each do |i|
+        type, re, discarded = RULES[i]
+        next unless (m = @ss.scan(re))
+
+        @scan_type = type
+        @scan_discarded = discarded
+        return m
       end
       raise UnconsumedInputError,
             "Unmatched input #{@input.byteslice(@ss.pos..).inspect} on line #{@line}"

data/lib/pgn/notation.rb

@@ -0,0 +1,474 @@
+# frozen_string_literal: true
+
+module PGN
+  # {PGN::Notation} generates Standard Algebraic Notation (SAN) for a single
+  # move described in coordinate form -- an origin square, a destination
+  # square, and an optional promotion piece -- given the {PGN::Position}
+  # *before* the move is played.
+  #
+  # Unlike {PGN::Move}, which *parses* an existing SAN string, {PGN::Notation}
+  # *builds* SAN from coordinates. This requires the kind of legality analysis
+  # the rest of the gem does not perform: attack detection, "does this move
+  # leave the mover's king in check", disambiguation among same-type pieces
+  # that can legally reach the destination, and check (+) / checkmate (#)
+  # suffix detection (the latter needing full legal-move generation for the
+  # side to move).
+  #
+  # The board is addressed with the same 0x88 integer indices the rest of the
+  # gem uses (see {PGN::Board}); an index is on-board when
+  # `(idx & 0x88).zero?`.
+  #
+  # @example
+  #   PGN::Notation.san(PGN::Position.start, 'g1', 'f3') #=> "Nf3"
+  #   PGN::Notation.san_from_fen(PGN::FEN::INITIAL, 'e2', 'e4') #=> "e4"
+  #
+  class Notation
+    # 0x88 single-step offsets for a knight (symmetric, so they double as
+    # attack deltas).
+    KNIGHT_OFFS = [33, 31, -31, -33, 18, 14, -14, -18].freeze
+    # 0x88 single-step offsets for a king (symmetric).
+    KING_OFFS = [-1, 1, -16, 16, -15, 15, -17, 17].freeze
+    BISHOP_DIRS = [-15, 15, -17, 17].freeze
+    ROOK_DIRS = [-1, 1, -16, 16].freeze
+
+    # Build SAN for a coordinate move from a {PGN::Position}.
+    #
+    # @param position [PGN::Position] the position *before* the move
+    # @param from [String] origin square in algebraic notation ("e2")
+    # @param to [String] destination square in algebraic notation ("e4")
+    # @param promotion [String, nil] promotion piece letter ("q"/"Q"/"n"...);
+    #   case-insensitive; SAN always emits an uppercase letter
+    # @return [String] the move in SAN, e.g. "Nf3", "exd5", "O-O", "Ra8#"
+    #
+    def self.san(position, from, to, promotion = nil)
+      new(position).san(from, to, promotion)
+    end
+
+    # Convenience: build SAN directly from a FEN string.
+    #
+    # @param fen [String] the FEN of the position *before* the move
+    # @param (see .san)
+    # @return [String] the move in SAN
+    #
+    def self.san_from_fen(fen, from, to, promotion = nil)
+      san(PGN::FEN.new(fen).to_position, from, to, promotion)
+    end
+
+    def initialize(position)
+      @position = position
+      @board = position.board
+      @player = position.player
+      @mover = (@player == :white ? 'w' : 'b')
+      @enemy = (@player == :white ? 'b' : 'w')
+    end
+
+    # @param (see .san)
+    # @return [String]
+    def san(from, to, promotion = nil)
+      from_idx = @board.index_of(from)
+      to_idx = @board.index_of(to)
+      piece = @board.at_index(from_idx)
+      raise ArgumentError, "no piece on #{from}" if piece.nil?
+
+      promotion = promotion.upcase if promotion
+
+      castling = piece.upcase == 'K' && ((from_idx & 0x0F) - (to_idx & 0x0F)).abs == 2
+      capture = castling ? false : capture?(piece, from_idx, to_idx)
+
+      body =
+        if castling
+          to_idx < from_idx ? 'O-O-O' : 'O-O'
+        elsif piece.upcase == 'P'
+          pawn_body(from_idx, to_idx, capture, promotion)
+        else
+          piece_body(piece, from_idx, to_idx, capture)
+        end
+
+      body + suffix(from_idx, to_idx, piece, promotion, castling)
+    end
+
+    private
+
+    # -- body construction -------------------------------------------------
+
+    def pawn_body(from_idx, to_idx, capture, promotion)
+      dest = @board.position_for([to_idx & 0x0F, to_idx >> 4])
+      promo = promotion ? "=#{promotion}" : ''
+      if capture
+        "#{Board::INDEX_TO_FILE[from_idx & 0x0F]}x#{dest}#{promo}"
+      else
+        "#{dest}#{promo}"
+      end
+    end
+
+    def piece_body(piece, from_idx, to_idx, capture)
+      disamb = disambiguation(piece, from_idx, to_idx)
+      dest = @board.position_for([to_idx & 0x0F, to_idx >> 4])
+      parts = [piece.upcase, disamb]
+      parts << 'x' if capture
+      parts << dest
+      parts.join
+    end
+
+    # Disambiguate a non-pawn, non-castling move among same-type pieces that
+    # can *legally* reach the destination. Returns '' when none can.
+    def disambiguation(piece, from_idx, to_idx)
+      others = same_type_legals(piece, from_idx, to_idx)
+      return '' if others.empty?
+
+      from_file = from_idx & 0x0F
+      from_rank = from_idx >> 4
+      file_clash = others.any? { |o| (o & 0x0F) == from_file }
+      rank_clash = others.any? { |o| (o >> 4) == from_rank }
+
+      if !file_clash
+        Board::INDEX_TO_FILE[from_file]
+      elsif !rank_clash
+        Board::INDEX_TO_RANK[from_rank]
+      else
+        Board::INDEX_TO_FILE[from_file] + Board::INDEX_TO_RANK[from_rank]
+      end
+    end
+
+    # Other squares holding `piece` whose move to `to_idx` is legal.
+    def same_type_legals(piece, from_idx, to_idx)
+      (0...128).each_with_object([]) do |idx, acc|
+        next if (idx & 0x88) != 0
+        next if idx == from_idx
+        next unless @board.at_index(idx) == piece
+
+        acc << idx if reaches?(piece, idx, to_idx) && legal_after?(idx, to_idx, piece)
+      end
+    end
+
+    # -- check / checkmate suffix -----------------------------------------
+
+    def suffix(from_idx, to_idx, piece, promotion, castling)
+      nb = apply_move(from_idx, to_idx, piece, promotion, castling)
+      opp_king = king_idx(nb, @enemy)
+      return '' unless opp_king && attacked?(nb, opp_king, @mover)
+
+      result_pos = PGN::Position.new(
+        nb,
+        @player == :white ? :black : :white,
+        [],
+        new_ep_square(piece, from_idx, to_idx),
+        0,
+        @position.fullmove
+      )
+      any_legal_move?(result_pos) ? '+' : '#'
+    end
+
+    # -- move application -------------------------------------------------
+
+    def apply_move(from_idx, to_idx, piece, promotion, castling)
+      nb = @board.dup
+      return castle!(nb, from_idx, to_idx, piece) if castling
+
+      ep = ep_capture_square(piece, from_idx, to_idx)
+      nb.update_index(ep, nil) if ep
+      nb.update_index(from_idx, nil)
+      nb.update_index(to_idx, promotion ? promoted(promotion) : piece)
+      nb
+    end
+
+    def castle!(board, from_idx, to_idx, piece)
+      rank = from_idx >> 4
+      rook = piece.upcase == 'K' ? 'R' : 'r'
+      board.update_index(from_idx, nil)
+      board.update_index(to_idx, piece)
+      if to_idx < from_idx # queenside
+        board.update_index(rank * 16, nil)
+        board.update_index((rank * 16) + 3, rook)
+      else # kingside
+        board.update_index((rank * 16) + 7, nil)
+        board.update_index((rank * 16) + 5, rook)
+      end
+      board
+    end
+
+    def promoted(promotion)
+      @player == :white ? promotion.upcase : promotion.downcase
+    end
+
+    # En-passant captured-pawn square (or nil): a pawn moving diagonally to
+    # an empty destination must be capturing en passant.
+    def ep_capture_square(piece, from_idx, to_idx)
+      return nil unless piece.upcase == 'P'
+      return nil if (from_idx & 0x0F) == (to_idx & 0x0F)
+
+      @board.at_index(to_idx).nil? ? ((from_idx >> 4) * 16) + (to_idx & 0x0F) : nil
+    end
+
+    # The en-passant target square left behind by a double pawn push, for the
+    # resulting position (so an escaping ep capture is considered for mate).
+    def new_ep_square(piece, from_idx, to_idx)
+      return nil unless piece.upcase == 'P'
+      return nil if ((from_idx >> 4) - (to_idx >> 4)).abs != 2
+
+      mid = ((from_idx >> 4) + (to_idx >> 4)) / 2
+      Board::INDEX_TO_FILE[from_idx & 0x0F] + Board::INDEX_TO_RANK[mid]
+    end
+
+    # -- legality ---------------------------------------------------------
+
+    # Is `piece` from `from_idx` to `to_idx` legal (own king safe after)?
+    def legal_after?(from_idx, to_idx, piece)
+      nb = @board.dup
+      ep = ep_capture_square(piece, from_idx, to_idx)
+      nb.update_index(ep, nil) if ep
+      nb.update_index(from_idx, nil)
+      nb.update_index(to_idx, piece)
+      king = king_idx(nb, @mover)
+      king && !attacked?(nb, king, @enemy)
+    end
+
+    # Does `piece` at `from_idx` pseudo-legally reach `to_idx` on the board?
+    # (Sliders honor blockers; the destination may be empty or enemy-occupied.)
+    def reaches?(piece, from_idx, to_idx)
+      return false if from_idx == to_idx
+
+      case piece.upcase
+      when 'N'
+        KNIGHT_OFFS.any? { |o| (from_idx + o) == to_idx }
+      when 'K'
+        KING_OFFS.any? { |o| (from_idx + o) == to_idx }
+      when 'B', 'R', 'Q'
+        slider_reaches?(piece.upcase, from_idx, to_idx)
+      else
+        false
+      end
+    end
+
+    def slider_reaches?(piece_up, from_idx, to_idx)
+      slider_dirs(piece_up).any? do |off|
+        i = from_idx + off
+        while (i & 0x88).zero?
+          return true if i == to_idx
+          break if @board.at_index(i)
+
+          i += off
+        end
+        false
+      end
+    end
+
+    # Capture detection for the *played* move (used in the SAN body).
+    def capture?(piece, from_idx, to_idx)
+      if piece.upcase == 'P'
+        (from_idx & 0x0F) != (to_idx & 0x0F) # any diagonal pawn move captures
+      else
+        target = @board.at_index(to_idx)
+        target && !own?(target, @mover)
+      end
+    end
+
+    def own?(piece, color)
+      color == 'w' ? piece == piece.upcase : piece == piece.downcase
+    end
+
+    # Slider ray directions for a piece letter ('B'/'R'/'Q').
+    def slider_dirs(piece_up)
+      case piece_up
+      when 'B' then BISHOP_DIRS
+      when 'R' then ROOK_DIRS
+      else BISHOP_DIRS + ROOK_DIRS
+      end
+    end
+
+    # -- attack / legality helpers ----------------------------------------
+
+    def king_idx(board, color)
+      king = color == 'w' ? 'K' : 'k'
+      (0...128).each do |idx|
+        next if (idx & 0x88) != 0
+
+        return idx if board.at_index(idx) == king
+      end
+      nil
+    end
+
+    # Is `target` attacked by `color`-colored pieces on `board`?
+    def attacked?(board, target, color)
+      pawn_attacked?(board, target, color) ||
+        knight_attacked?(board, target, color) ||
+        king_attacked?(board, target, color) ||
+        slider_attacked?(board, target, color)
+    end
+
+    def pawn_attacked?(board, target, color)
+      offs = color == 'w' ? [-15, -17] : [15, 17]
+      pawn = color == 'w' ? 'P' : 'p'
+      offs.any? do |off|
+        i = target + off
+        (i & 0x88).zero? && board.at_index(i) == pawn
+      end
+    end
+
+    def knight_attacked?(board, target, color)
+      knight = color == 'w' ? 'N' : 'n'
+      KNIGHT_OFFS.any? do |off|
+        i = target + off
+        (i & 0x88).zero? && board.at_index(i) == knight
+      end
+    end
+
+    def king_attacked?(board, target, color)
+      king = color == 'w' ? 'K' : 'k'
+      KING_OFFS.any? do |off|
+        i = target + off
+        (i & 0x88).zero? && board.at_index(i) == king
+      end
+    end
+
+    def slider_attacked?(board, target, color)
+      bishop = color == 'w' ? 'B' : 'b'
+      rook = color == 'w' ? 'R' : 'r'
+      queen = color == 'w' ? 'Q' : 'q'
+      ray_hit?(board, target, BISHOP_DIRS) { |p| p == bishop || p == queen } ||
+        ray_hit?(board, target, ROOK_DIRS) { |p| p == rook || p == queen }
+    end
+
+    def ray_hit?(board, target, dirs)
+      dirs.each do |off|
+        i = target + off
+        while (i & 0x88).zero?
+          piece = board.at_index(i)
+          if piece
+            return true if yield(piece)
+            break
+          end
+          i += off
+        end
+      end
+      false
+    end
+
+    # -- legal-move generation (for checkmate detection) ------------------
+
+    def any_legal_move?(position)
+      board = position.board
+      color = position.player == :white ? 'w' : 'b'
+      ep_idx = ep_target_idx(position, board)
+
+      (0...128).any? do |idx|
+        next if (idx & 0x88) != 0
+
+        piece = board.at_index(idx)
+        piece && own?(piece, color) && move_from?(board, idx, piece, color, ep_idx)
+      end
+    end
+
+    def ep_target_idx(position, board)
+      ep = position.en_passant
+      return nil if ep.nil? || ep == '-' || ep.empty?
+
+      board.index_of(ep)
+    end
+
+    # Yields true if `piece` at `idx` has any legal move (escapes check).
+    def move_from?(board, idx, piece, color, ep_idx)
+      up = piece.upcase
+      case up
+      when 'N' then leaper_moves?(board, idx, piece, color, KNIGHT_OFFS)
+      when 'K' then leaper_moves?(board, idx, piece, color, KING_OFFS)
+      when 'B', 'R', 'Q'
+        slider_moves?(board, idx, piece, color, slider_dirs(up))
+      when 'P'
+        pawn_moves?(board, idx, piece, color, ep_idx)
+      else
+        false
+      end
+    end
+
+    def leaper_moves?(board, idx, piece, color, offs)
+      offs.any? do |off|
+        t = idx + off
+        (t & 0x88).zero? && landable?(board, t, color) && safe?(board, idx, t, piece, nil)
+      end
+    end
+
+    def slider_moves?(board, idx, piece, color, dirs)
+      dirs.any? do |off|
+        t = idx + off
+        while (t & 0x88).zero?
+          tp = board.at_index(t)
+          if tp.nil?
+            return true if safe?(board, idx, t, piece, nil)
+          else
+            return true if !own?(tp, color) && safe?(board, idx, t, piece, nil)
+            break
+          end
+          t += off
+        end
+        false
+      end
+    end
+
+    def pawn_moves?(board, idx, piece, color, ep_idx)
+      pawn_pushes?(board, idx, piece, color) ||
+        pawn_captures?(board, idx, piece, color, ep_idx)
+    end
+
+    def pawn_pushes?(board, idx, piece, color)
+      dir = color == 'w' ? 16 : -16
+      start_rank = color == 'w' ? 1 : 6
+      promo_rank = color == 'w' ? 7 : 0
+
+      t = idx + dir
+      return false unless (t & 0x88).zero? && board.at_index(t).nil?
+
+      promo = (t >> 4 == promo_rank) ? 'Q' : nil
+      return true if safe?(board, idx, t, piece, promo)
+
+      t2 = idx + (dir * 2)
+      (idx >> 4) == start_rank && board.at_index(t2).nil? && safe?(board, idx, t2, piece, nil)
+    end
+
+    def pawn_captures?(board, idx, piece, color, ep_idx) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      promo_rank = color == 'w' ? 7 : 0
+      caps = color == 'w' ? [15, 17] : [-15, -17]
+      caps.any? do |off|
+        t = idx + off
+        next false unless (t & 0x88).zero?
+
+        tp = board.at_index(t)
+        promo = (t >> 4 == promo_rank) ? 'Q' : nil
+        if tp && !own?(tp, color)
+          safe?(board, idx, t, piece, promo)
+        elsif tp.nil? && t == ep_idx
+          safe?(board, idx, t, piece, nil)
+        else
+          false
+        end
+      end
+    end
+
+    def landable?(board, target, color)
+      tp = board.at_index(target)
+      tp.nil? || !own?(tp, color)
+    end
+
+    # Apply a pseudo-move (with ep + promotion) on a copy and test own-king
+    # safety. The moving side is derived from `piece`'s case.
+    def safe?(board, from_idx, to_idx, piece, promotion)
+      nb = board.dup
+      if piece.upcase == 'P' && (from_idx & 0x0F) != (to_idx & 0x0F) && board.at_index(to_idx).nil?
+        nb.update_index(((from_idx >> 4) * 16) + (to_idx & 0x0F), nil) # ep capture
+      end
+      nb.update_index(from_idx, nil)
+      nb.update_index(to_idx, place_piece(piece, promotion))
+      color = own?(piece, 'w') ? 'w' : 'b'
+      king = king_idx(nb, color)
+      king && !attacked?(nb, king, color == 'w' ? 'b' : 'w')
+    end
+
+    # The piece letter to place on the destination after a pseudo-move.
+    def place_piece(piece, promotion)
+      return piece unless promotion
+
+      white = piece == piece.upcase
+      white ? promotion.upcase : promotion.downcase
+    end
+  end
+end

data/lib/pgn/pgn_parser.rb

@@ -21,8 +21,10 @@ module_eval(<<'...end pgn_parser.y/module_eval...', 'pgn_parser.y', 97)
   def next_token
     pair = @lexer.next_token_pair
     return [false, false] unless pair
-    type, value = pair
-    [translate_type(type), value]
+    # Mutate the lexer's [type, value] pair in place rather than allocating
+    # a second translated pair -- one array per token is the Racc floor.
+    pair[0] = translate_type(pair[0])
+    pair
   end
 
   private

data/lib/pgn/pgn_parser.y

@@ -106,8 +106,10 @@ rule
   def next_token
     pair = @lexer.next_token_pair
     return [false, false] unless pair
-    type, value = pair
-    [translate_type(type), value]
+    # Mutate the lexer's [type, value] pair in place rather than allocating
+    # a second translated pair -- one array per token is the Racc floor.
+    pair[0] = translate_type(pair[0])
+    pair
   end
 
   private

data/lib/pgn/version.rb

@@ -1,3 +1,3 @@
 module PGN
-  VERSION = '1.3.0'.freeze
+  VERSION = '1.4.0'.freeze
 end

data/lib/pgn.rb

@@ -4,6 +4,7 @@ require 'pgn/game'
 require 'pgn/move'
 require 'pgn/move_calculator'
 require 'pgn/lexer'
+require 'pgn/notation'
 require 'pgn/pgn_parser'
 require 'pgn/parser'
 require 'pgn/position'

data/spec/notation_spec.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+# Helper: build a Position from a FEN string.
+def pos(fen)
+  PGN::FEN.new(fen).to_position
+end
+
+describe PGN::Notation do
+  # ------------------------------------------------------------------
+  # Public API
+  # ------------------------------------------------------------------
+  describe '.san' do
+    it 'generates a plain pawn push from coordinates' do
+      expect(PGN::Notation.san(pos('rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1'),
+                               'e2', 'e4')).to eq('e4')
+    end
+
+    it 'generates a knight move with the piece letter' do
+      expect(PGN::Notation.san(pos('rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1'),
+                               'g1', 'f3')).to eq('Nf3')
+    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')
+    end
+
+    it 'generates an en passant capture' do
+      fen = 'rnbqkbnr/ppp1pppp/8/3pP3/8/8/PPPP1PPP/RNBQKBNR w KQkq d6 0 3'
+      expect(PGN::Notation.san(pos(fen), 'e5', 'd6')).to eq('exd6')
+    end
+
+    it 'generates a pawn promotion' do
+      fen = '8/P7/6k1/8/8/8/8/4K3 w - - 0 1'
+      expect(PGN::Notation.san(pos(fen), 'a7', 'a8', 'q')).to eq('a8=Q')
+    end
+
+    it 'generates a capture promotion' do
+      fen = '1n6/P7/6k1/8/8/8/8/4K3 w - - 0 1'
+      expect(PGN::Notation.san(pos(fen), 'a7', 'b8', 'q')).to eq('axb8=Q')
+    end
+
+    it 'generates kingside castling' do
+      fen = 'r3k2r/8/8/8/8/8/8/R3K2R w KQkq - 0 1'
+      expect(PGN::Notation.san(pos(fen), 'e1', 'g1')).to eq('O-O')
+    end
+
+    it 'generates queenside castling' do
+      fen = 'r3k2r/8/8/8/8/8/8/R3K2R w KQkq - 0 1'
+      expect(PGN::Notation.san(pos(fen), 'e1', 'c1')).to eq('O-O-O')
+    end
+
+    it 'generates kingside castling for black' do
+      fen = 'r3k2r/8/8/8/8/8/8/R3K2R b KQkq - 0 1'
+      expect(PGN::Notation.san(pos(fen), 'e8', 'g8')).to eq('O-O')
+    end
+  end
+
+  describe '.san disambiguation' do
+    it 'disambiguates knights by file' do
+      # Knights on c3 and d4 both reach b5.
+      fen = 'r1bqkb1r/pp1p1ppp/2n1pn2/8/3NP3/2N5/PPP2PPP/R1BQKB1R w KQkq - 3 6'
+      expect(PGN::Notation.san(pos(fen), 'd4', 'b5')).to eq('Ndb5')
+      expect(PGN::Notation.san(pos(fen), 'c3', 'b5')).to eq('Ncb5')
+    end
+
+    it 'disambiguates rooks by rank when on the same file' do
+      # White rooks on a1 and a8 both reach a4 (file a clear).
+      fen = 'R7/8/8/4k3/8/8/8/R3K3 w - - 0 1'
+      expect(PGN::Notation.san(pos(fen), 'a1', 'a4')).to eq('R1a4')
+      expect(PGN::Notation.san(pos(fen), 'a8', 'a4')).to eq('R8a4')
+    end
+
+    it 'disambiguates queens by full square when file and rank both clash' do
+      # Queens on c1, f1, f4 all reach c4. The f1 queen shares file f with
+      # f4 and rank 1 with c1, so only the full square disambiguates.
+      fen = '7k/8/8/8/5Q2/8/8/2Q2Q1K w - - 0 1'
+      expect(PGN::Notation.san(pos(fen), 'f1', 'c4')).to eq('Qf1c4')
+    end
+
+    it 'omits disambiguation when only one piece can legally move there' do
+      # Two knights both pseudo-reach d2, but the e4 knight is pinned
+      # on the e-file (moving it exposes the king on e1 to the rook on e8),
+      # so only the b1 knight can legally play Nd2 — no disambiguation.
+      fen = '4r2k/8/8/8/4N3/8/8/1N2K3 w - - 0 1'
+      expect(PGN::Notation.san(pos(fen), 'b1', 'd2')).to eq('Nd2')
+    end
+  end
+
+  describe '.san check and checkmate suffixes' do
+    it 'appends + for a checking move' do
+      fen = '7k/8/8/8/8/8/6R1/6K1 w - - 0 1'
+      expect(PGN::Notation.san(pos(fen), 'g2', 'g8')).to eq('Rg8+')
+    end
+
+    it 'appends # for a checkmating move' do
+      fen = '6k1/5ppp/8/8/8/8/8/R6K w - - 0 1'
+      expect(PGN::Notation.san(pos(fen), 'a1', 'a8')).to eq('Ra8#')
+    end
+
+    it 'appends # to a promotion that gives checkmate' do
+      # White pawn b7 promotes with check on a king cornered on h8.
+      fen = '7k/1P6/8/8/8/8/8/6K1 w - - 0 1'
+      expect(PGN::Notation.san(pos(fen), 'b7', 'b8', 'q')).to eq('b8=Q+')
+    end
+
+    it 'does not append a suffix for a quiet move' do
+      fen = 'rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1'
+      expect(PGN::Notation.san(pos(fen), 'd2', 'd4')).to eq('d4')
+    end
+  end
+
+  describe '.san_from_fen' do
+    it 'computes SAN directly from a FEN string' do
+      expect(PGN::Notation.san_from_fen('rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1',
+                                        'e2', 'e4')).to eq('e4')
+    end
+
+    it 'computes SAN for black to move' do
+      fen = 'rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq e3 0 1'
+      expect(PGN::Notation.san_from_fen(fen, 'd7', 'd5')).to eq('d5')
+    end
+  end
+end

metadata

@@ -1,15 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pgn2
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Stacey Touset
 - Murilo Vasconcelos
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-13 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -168,6 +167,7 @@ files:
 - lib/pgn/lexer.rb
 - lib/pgn/move.rb
 - lib/pgn/move_calculator.rb
+- lib/pgn/notation.rb
 - lib/pgn/parser.rb
 - lib/pgn/pgn_parser.rb
 - lib/pgn/pgn_parser.y
@@ -181,6 +181,7 @@ files:
 - spec/lexer_spec.rb
 - spec/move_calculator_spec.rb
 - spec/move_spec.rb
+- spec/notation_spec.rb
 - spec/parser_explicit_spec.rb
 - spec/parser_spec.rb
 - spec/pgn_files/alternate_castling.pgn
@@ -208,7 +209,6 @@ metadata:
   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
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -223,8 +223,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 4.0.10
 specification_version: 4
 summary: A PGN parser for Ruby
 test_files:
@@ -234,6 +233,7 @@ test_files:
 - spec/lexer_spec.rb
 - spec/move_calculator_spec.rb
 - spec/move_spec.rb
+- spec/notation_spec.rb
 - spec/parser_explicit_spec.rb
 - spec/parser_spec.rb
 - spec/pgn_files/alternate_castling.pgn