pgn2 1.3.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 33036a2920baf0e170efc5e1c387c2a53ae91fe19ad19cf745d4d6f049c9fe20
-  data.tar.gz: 93ccbe0289a72f4af5fb8367a4d1f5bdc0c1d5eb77f1a65e3381b7d17f5d3822
+  metadata.gz: da98f302d6785b75581d53fbe6dab4b7ccad9f5514f7ad278be12a540633d572
+  data.tar.gz: 9b22f32a2b44bd06cfd8d29c82f9b4af8c1c4687ed9650df33c4d5fdc76dd49e
 SHA512:
-  metadata.gz: 25ed517772982909d896b4b372308d235574db54aa44f3ff98f5201f9055120fc64d19fcd634c6676f7bfb66cf5e4de483a2a9ae13293b3162781339434bfac1
-  data.tar.gz: bf2a935f6aa4fedffb5976b0febc5eb351354165275d8b248eac99f7a713d74cf6acb3cb9e0be51c6030a55481663173ab5c9008cf5dfa67904bd09ac4e271f5
+  metadata.gz: 0c99f7034728254221189f9af053bc6c57938d24c96d83d8dacce7ad78cf2bc8b23de3b28a497c9b750b12f63dd17a9ca6ed65b293c5f8f0188d4f79b188e5d2
+  data.tar.gz: 437fbf1d534aa15578bef06c4ca5020116f6b2385d81c886104f69bb8db0124d7e220b3d566a22f8df4e93180929519891ba71279db21e0e2f541f1b6f0f8892

data/CHANGELOG.md

@@ -1,5 +1,76 @@
 # Changelog
 
+## 1.5.0 (2026-08-13)
+
+### Summary
+
+Clarity refactor on the 0x88 hot path, plus a small parser perf win: no
+public API changes, no behavior change; serialized PGN/FEN output stays
+byte-identical; all 201 specs green.
+
+### Changed
+- **`PGN::Board`**: promoted the on-board bitmask test and square-name
+  lookup to public `on_board?(idx)` / `square_name(idx)` methods,
+  replacing private duplicates of the same logic in `MoveCalculator`.
+  Added a named `Board.from_cells(cells)` factory for building a board
+  directly from a 128-cell 0x88 array; `#dup` (called every move) now
+  routes through it instead of reaching around the constructor via
+  `Board.allocate` + `instance_variable_set` directly. Performance is
+  identical — same allocate + one ivar set — just a documented factory
+  instead of a reflective one-off.
+- **`PGN::MoveCalculator`**: calls `board.on_board?`/`board.square_name`
+  instead of its own private copies; named the castling-table square
+  literals (`C1`..`G8`) instead of raw 0x88 integers in `CASTLING`, for
+  readability. `#board`/`#move` are now `attr_reader` instead of
+  `attr_accessor` — there was no external writer, and the `@dest_idx`
+  memo already silently relied on both never changing after
+  `#initialize`; dropping the setters enforces that invariant in the
+  type instead of by convention.
+- **`PGN::Lexer`**: dropped the per-token `@line` counter (one
+  `str.count("\n")` via `advance_line` on every `next_token`/
+  `next_token_pair` call) in favor of a lazy `line_at(off)`, computed
+  only when a line number is actually needed (error messages, the spec
+  `tokens` helper) — the parser itself never reads it. Removes a
+  `str.count("\n")` call from the parse hot path (~6% of parse CPU for
+  a value that was never read).
+
+## 1.4.0 (2026-08-13)
+
+### 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/TODO.md

@@ -17,31 +17,45 @@
     `#tokens` spec helper. Parse allocations −42% (603537 → 347037 / 500 games).
 - Speed up replay via a board-representation rewrite ("Approach B"): done.
   (b) ✓ (done in 1.3.0) Rewrote `Board` internals to the classic 0x88
-    representation (128-cell array indexed by `rank*16+file`) and rewrote
-    `MoveCalculator` to work entirely in single-integer square indices via
-    `Board#at_index`/`#apply!`, so the replay hot path no longer allocates
-    `[file,rank]` coordinate arrays or square-name strings. Off-board is a
-    single bitmask (`(idx & 0x88).zero?`, ~1.6x faster than a 0..7 bounds
-    check) and ray stepping is a single integer add. Algorithm unchanged, so
-    output is byte-identical. Measured (immortal game): replay 798→535 µs/i
-    (+49% throughput), allocations 1571→976 objects (−38%) / 92440→62064 bytes
-    (−33%); parse+replay +21% throughput. 182 specs green, 0 new rubocop
-    offenses vs main. The public string/coord API is preserved (additive).
+  representation (128-cell array indexed by `rank*16+file`) and rewrote
+  `MoveCalculator` to work entirely in single-integer square indices via
+  `Board#at_index`/`#apply!`, so the replay hot path no longer allocates
+  `[file,rank]` coordinate arrays or square-name strings. Off-board is a
+  single bitmask (`(idx & 0x88).zero?`, ~1.6x faster than a 0..7 bounds
+  check) and ray stepping is a single integer add. Algorithm unchanged, so
+  output is byte-identical. Measured (immortal game): replay 798→535 µs/i
+  (+49% throughput), allocations 1571→976 objects (−38%) / 92440→62064 bytes
+  (−33%); parse+replay +21% throughput. 182 specs green, 0 new rubocop
+  offenses vs main. The public string/coord API is preserved (additive).
+  (c) One related idea was left alone during cleanup rather than "fixed",
+  since fixing it would cost more than it's worth right now: `Board#squares`
+  rebuilds the full 8x8 array from `@cells` on every call (9 allocations,
+  64 reads); it's off the replay hot path by design, but `FEN#to_s`
+  round-trips through it on every position-to-FEN call, so FEN generation
+  pays that cost repeatedly. Memoizing would mean invalidating the cache
+  from `update`/`apply!`, i.e. adding a write to the actual hot path to
+  speed up a path that isn't hot -- the wrong trade; if FEN generation
+  becomes hot, have it read `@cells` directly instead. Also considered
+  and not attempted: column-granularity copy-on-write in `dup` (the pre-0x88
+  Board only duplicated touched file-columns on write); the flat 0x88 array
+  trades that away for simplicity and the +49% throughput measured above,
+  and reintroducing it would need its own A/B before it's worth the
+  complexity.
   (a) ✗ (attempted, rejected) A piece-location index (piece → 0x88 indices)
-    maintained in `update`/`apply!` and used for O(1) slider/leaper/king
-    origin lookups. Implemented on top of (b), all 182 specs green, but it
-    **regressed**: replay 526→727 µs/i (+38% slower), allocations 976→1591
-    objects (+63%). Root cause: `Board#dup` (called every move) must clone
-    the index (`transform_values(&:dup)` ≈ 12 piece arrays) — Board#dup went
-    91→676 objects — and every move pays per-update index maintenance
-    (`<<`/`delete`) that pawns (the most common move type, whose origins are
-    geometry-fixed and can't use the index) pay for no benefit. The index
-    helps sliders/leapers (minority of moves) but the dup + maintenance cost
-    is paid by every move. Conclusion: a global piece index is a loss for
-    replay (where only ONE given move is validated, so ray-scanning from the
-    destination is already cheap); it pays in move-*generation* libraries
-    (chess.js/python-chess) that enumerate ALL legal moves. Not worth a COW
-    variant either (maintenance + pawns). Reverted; (b) alone is the winner.
+  maintained in `update`/`apply!` and used for O(1) slider/leaper/king
+  origin lookups. Implemented on top of (b), all 182 specs green, but it
+  **regressed**: replay 526→727 µs/i (+38% slower), allocations 976→1591
+  objects (+63%). Root cause: `Board#dup` (called every move) must clone
+  the index (`transform_values(&:dup)` ≈ 12 piece arrays) — Board#dup went
+  91→676 objects — and every move pays per-update index maintenance
+  (`<<`/`delete`) that pawns (the most common move type, whose origins are
+  geometry-fixed and can't use the index) pay for no benefit. The index
+  helps sliders/leapers (minority of moves) but the dup + maintenance cost
+  is paid by every move. Conclusion: a global piece index is a loss for
+  replay (where only ONE given move is validated, so ray-scanning from the
+  destination is already cheap); it pays in move-_generation_ libraries
+  (chess.js/python-chess) that enumerate ALL legal moves. Not worth a COW
+  variant either (maintenance + pawns). Reverted; (b) alone is the winner.
 - Replace the right-recursive `tag_section`/`variation_list` rules in
   `pgn_parser.y` with ordinary left-recursion plus one explicit `.reverse`
   at the point each list is consumed, so the legacy whittle-order
@@ -53,10 +67,3 @@
   to reuse as-is. The brace check is a bandaid for `clean_text` not fully
   normalizing multi-line/nested comments in one pass; fixing that at the
   source would let `moves=` reuse unconditionally.
-- `MoveCalculator#destination_coords` memoizes into `@dest_coords` based on
-  `board`/`move`/`origin` never changing after `#initialize` — true today,
-  but only by convention, since `board`, `move`, `origin` are all public
-  `attr_accessor`s with no cache invalidation tied to their setters. If a
-  future caller ever mutates and reuses a `MoveCalculator` instance, this
-  memo goes stale silently. Either drop the public setters or invalidate
-  `@dest_coords` when they're used.

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

@@ -27,10 +27,10 @@ module PGN
     ].freeze
 
     FILE_TO_INDEX = ('a'..'h').each_with_index.to_h
-    INDEX_TO_FILE = FILE_TO_INDEX.map(&:reverse).to_h
+    INDEX_TO_FILE = FILE_TO_INDEX.invert
 
     RANK_TO_INDEX = ('1'..'8').each_with_index.to_h
-    INDEX_TO_RANK = RANK_TO_INDEX.map(&:reverse).to_h
+    INDEX_TO_RANK = RANK_TO_INDEX.invert
 
     # algebraic to unicode piece lookup
     #
@@ -102,7 +102,6 @@ module PGN
           @cells[(r * 16) + f] = squares[f][r]
         end
       end
-      @cells
     end
 
     # @overload at(str)
@@ -119,9 +118,9 @@ module PGN
     #   board.at("e4") #=> "P"
     #
     def at(arg0, arg1 = nil)
-      return @cells[(arg1 * 16) + arg0] unless arg1.nil?
+      return at_index(index_for(arg0, arg1)) unless arg1.nil?
 
-      @cells[(rank_of(arg0) * 16) + file_of(arg0)]
+      at_index(index_of(arg0))
     end
 
     # @param changes [Hash<String, <String, nil>>] changes to make to the board
@@ -141,8 +140,7 @@ module PGN
     #   board.update("e4", "P")
     #
     def update(square, piece)
-      @cells[(rank_of(square) * 16) + file_of(square)] = piece
-      self
+      update_index(index_of(square), piece)
     end
 
     # @param position [String] the square in algebraic notation
@@ -173,13 +171,25 @@ module PGN
       end.join("\n")
     end
 
+    # Build a {Board} directly from a 0x88 cell array, bypassing the 8x8
+    # -> 0x88 conversion in {#initialize}. Used by {#dup} (which runs every
+    # move) to skip the per-square rebuild; the cell array is already in the
+    # canonical 128-cell layout.
+    #
+    # @param cells [Array<String, nil>] a 128-cell 0x88 array
+    # @return [PGN::Board]
+    #
+    def self.from_cells(cells)
+      board = allocate
+      board.instance_variable_set(:@cells, cells)
+      board
+    end
+
     # @return [PGN::Board] a copy of self. Copies the 128-cell 0x88 array;
     #   mutations to the copy do not affect the original.
     #
     def dup
-      copy = PGN::Board.allocate
-      copy.instance_variable_set(:@cells, @cells.dup)
-      copy
+      self.class.from_cells(@cells.dup)
     end
 
     # -- 0x88 hot-path API (integer indices) ---------------------------------
@@ -235,6 +245,25 @@ module PGN
       self
     end
 
+    # Whether a 0x88 index is on the board (see the class doc for the
+    # bitmask this tests).
+    #
+    # @param idx [Integer] a 0x88 square index
+    # @return [Boolean]
+    #
+    def on_board?(idx)
+      (idx & 0x88).zero? # rubocop:disable Style/BitwisePredicate
+    end
+
+    # The algebraic square name of a 0x88 index.
+    #
+    # @param idx [Integer] a 0x88 square index
+    # @return [String] e.g. "e4"
+    #
+    def square_name(idx)
+      INDEX_TO_FILE[idx & 0x0F] + INDEX_TO_RANK[idx >> 4]
+    end
+
     private
 
     def file_of(square)

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, '['], # [
@@ -128,7 +161,6 @@ module PGN
     def initialize(input)
       @input = input
       @ss = StringScanner.new(input)
-      @line = 1
       @game_starts = []
       @between_games = true # at start we are "between" games
     end
@@ -149,7 +181,8 @@ module PGN
       type, value = next_token_pair
       return nil unless type
 
-      Token.new(type: type, value: value, offset: @last_offset, line: @line)
+      Token.new(type: type, value: value, offset: @last_offset,
+                line: line_at(@last_offset))
     end
 
     # Fast path for the parser: returns [type, value] for the next
@@ -170,7 +203,6 @@ module PGN
         end
 
         value = scan_one
-        advance_line(value)
         next if @scan_discarded
 
         note_token(@scan_type, off)
@@ -185,17 +217,20 @@ 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}"
+            "Unmatched input #{@input.byteslice(@ss.pos..).inspect} on line #{line_at(@ss.pos)}"
     end
 
     # Track per-game content-start offsets for verbatim pgn slicing.
@@ -210,8 +245,12 @@ module PGN
       end
     end
 
-    def advance_line(str)
-      @line += str.count("\n")
+    # Line number at a byte offset, computed lazily only for error messages
+    # and the spec `tokens` helper. Keeping a running `@line` on the parse hot
+    # path (one `str.count("\n")` per token) was ~6% of parse CPU for a value
+    # the parser never reads.
+    def line_at(off)
+      1 + @input.byteslice(0, off).count("\n")
     end
   end
 

data/lib/pgn/move_calculator.rb

@@ -30,7 +30,7 @@ module PGN
     # 0x88 single-step offsets for knight and king.
     #
     STEP = {
-      'k' => [-1, 1, -16, 16, -15, 15, -17, 17],
+      'k' => SLIDE['q'],
       'n' => [33, 31, -31, -33, 18, 14, -14, -18]
     }.freeze
 
@@ -42,15 +42,6 @@ module PGN
       'p' => { capture: [15, 17], normal: [16], double: [32] }
     }.freeze
 
-    # The squares to update for each castling move, keyed by 0x88 index.
-    #
-    CASTLING = {
-      'Q' => { 0 => nil, 2 => 'K', 3 => 'R', 4 => nil },
-      'K' => { 4 => nil, 5 => 'R', 6 => 'K', 7 => nil },
-      'q' => { 112 => nil, 114 => 'k', 115 => 'r', 116 => nil },
-      'k' => { 116 => nil, 117 => 'r', 118 => 'k', 119 => nil }
-    }.freeze
-
     # Corner-square 0x88 indices, used for castling-restriction bookkeeping
     # (a rook leaving or being captured on a corner drops the matching right).
     #
@@ -59,6 +50,29 @@ module PGN
     A8 = 112
     H8 = 119
 
+    # King/rook landing squares for castling, named for readability in
+    # {CASTLING} below.
+    #
+    C1 = 2
+    D1 = 3
+    E1 = 4
+    F1 = 5
+    G1 = 6
+    C8 = 114
+    D8 = 115
+    E8 = 116
+    F8 = 117
+    G8 = 118
+
+    # The squares to update for each castling move, keyed by 0x88 index.
+    #
+    CASTLING = {
+      'Q' => { A1 => nil, C1 => 'K', D1 => 'R', E1 => nil },
+      'K' => { E1 => nil, F1 => 'R', G1 => 'K', H1 => nil },
+      'q' => { A8 => nil, C8 => 'k', D8 => 'r', E8 => nil },
+      'k' => { E8 => nil, F8 => 'r', G8 => 'k', H8 => nil }
+    }.freeze
+
     # rook-origin (0x88 index) -> castling restriction it drops.
     #
     ROOK_RESTRICTIONS = { A1 => 'Q', H1 => 'K', A8 => 'q', H8 => 'k' }.freeze
@@ -69,14 +83,14 @@ module PGN
     WHITE_CASTLE = %w[K Q].freeze
     BLACK_CASTLE = %w[k q].freeze
 
-    attr_accessor :board, :move
+    attr_reader :board, :move
 
     # @param board [PGN::Board] the current board
     # @param move [PGN::Move] the current move
     #
     def initialize(board, move)
-      self.board = board
-      self.move  = move
+      @board = board
+      @move  = move
       @origin_idx = compute_origin
     end
 
@@ -87,7 +101,7 @@ module PGN
     def origin
       return nil if @origin_idx.nil?
 
-      board.position_for([@origin_idx & 0x0F, @origin_idx >> 4])
+      board.square_name(@origin_idx)
     end
 
     # @return [PGN::Board] the board after the move is made
@@ -215,7 +229,7 @@ module PGN
       possibilities = []
       offsets.each do |off|
         target = dest + off
-        next unless (target & 0x88).zero? # rubocop:disable Style/BitwisePredicate
+        next unless board.on_board?(target)
 
         possibilities << target if board.at_index(target) == move.piece
       end
@@ -250,7 +264,7 @@ module PGN
       return possibilities unless move.disambiguation
 
       possibilities.select do |idx|
-        board.position_for([idx & 0x0F, idx >> 4]).match(move.disambiguation)
+        board.square_name(idx).match(move.disambiguation)
       end
     end
 
@@ -290,7 +304,7 @@ module PGN
     #
     def first_piece(idx, off)
       idx += off
-      while (idx & 0x88).zero? # rubocop:disable Style/BitwisePredicate
+      while board.on_board?(idx)
         square = board.at_index(idx)
         return idx if square
 
@@ -315,7 +329,7 @@ module PGN
       return nil if move.castle
       return nil unless move.capture && board.at_index(dest_idx).nil?
 
-      (origin_rank * 16) + (dest_idx & 0x0F)
+      board.index_for(dest_idx & 0x0F, origin_rank)
     end
 
     def king_position
@@ -323,7 +337,7 @@ module PGN
 
       0.upto(7) do |rank|
         0.upto(7) do |file|
-          idx = (rank * 16) + file
+          idx = board.index_for(file, rank)
           return idx if board.at_index(idx) == king
         end
       end

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.5.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,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pgn2
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.5.0
 platform: ruby
 authors:
 - Stacey Touset
@@ -168,6 +168,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 +182,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
@@ -234,6 +236,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