pgn2 2.0.0 → 2.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9122d51c1216e8cfa7a0dd361fc4c37532dd52c589e21316a841e78a3559eced
-  data.tar.gz: c982424532eb4cf9fe84ddcf95bcd7653cde9679a588d050d25ee22f0c4aea64
+  metadata.gz: 8fdc6dcb9543c25e2e1102902d031f9d733463780b6f5d16a1a4713c6cfe16b9
+  data.tar.gz: 051ba77cdb0e657909ef5a22c1470f229c883e2bcb70cbfd3b9dbfbb83e92b8e
 SHA512:
-  metadata.gz: ab449fed5746ca4b41262ca19b2a5e4db55e2faa12ce89b51cb30427383b4b83db622be644a2c0b3234c0827011fed259f60137694a40593e8013f574151f4f7
-  data.tar.gz: f3b520c9e0bb48b7c06cd379d77f4336703d2ac212f8b013e2815db1c2b767823e4d0659cba8ff7f6003a56094044ece7339c7be82fb2a324eae169c0240edc7
+  metadata.gz: 3999930da7369748415bfb222108d436a64c67bf8e91c5b0d12d9dc5ab38f64c78f1e1e56abca9454ed8e1a215df0918d152e37b1271808d8e1962088029a0e7
+  data.tar.gz: 2dec3d79ee03350d252bd846a789b3b96091f6ec34cd788d60e267506c2837436659395472fef192f3aeec8290ef32e3f7bd235308062a1de12f1add0e110ab7

data/.github/workflows/release-gems.yml

@@ -6,9 +6,12 @@ name: release-gems
 # toolchain required. Push to RubyGems is gated on a published release;
 # `workflow_dispatch` builds + uploads artifacts without pushing.
 #
-# Targets (set inside the rake-compiler-dock environment):
+# The target platform list is configured in the Rakefile's
+# Rake::ExtensionTask (ext.cross_platform); keep that list as the single
+# source of truth.
+#
+# Targets:
 #   x86_64-linux, aarch64-linux, x86_64-darwin, aarch64-darwin
-# (configure the platform list in Rakefile cross-compile settings.)
 
 on:
   release:

data/CHANGELOG.md

@@ -1,6 +1,38 @@
 # Changelog
 
-## 2.0.0 (unreleased)
+## 2.0.2 (2026-08-18)
+
+### Summary
+
+Internal refactor and performance pass — no public API changes. The
+`pgn2-bitboard` adapter drops its hand-rolled `Move`/`MoveList`/`uci_parse`
+layer in favor of `chessie`'s own `MoveList` and `Move: PartialEq<str>`
+(UCI comparison), and the Ruby side DRYs shared FEN/EPD parsing, memoizes
+`Position#in_check?`, and maintains `Game`'s position cache incrementally.
+
+### Changed
+
+- **`ext/pgn2_native`** — remove `pgn2-bitboard/src/moves.rs`;
+  `Board#legal_moves` returns `chessie::MoveList` directly and
+  `Engine#legal?` compares via `chessie::Move`'s `PartialEq<str>` (by
+  `to_uci()`), eliminating the separate UCI parser.
+- **`PGN::PositionFields`** — shared FEN/EPD module for board-string and
+  castling/en-passant field parsing; `FEN` and `EPD` now include it instead
+  of duplicating the logic.
+- **`PGN::Attack.attacked?`** — short-circuits pawn/knight/king checks before
+  the slider ray-walk (cheapest first), matching the previous result.
+- **`PGN::Position#in_check?`** — memoizes its result on first call.
+- **`PGN::Game`** — `push`/`pop` now grow/shrink the memoized `@positions`
+  list in step rather than invalidating it; `threefold?` reuses `#positions`.
+- **`PGN::MoveText.normalize_castling`** — castling `0`→`O` normalization
+  extracted as a class method (was a private `Node` helper).
+- **`PGN::Node`** — `promote`/`demote`/`promote_to_main`/`demote_to_last`/
+  `delete` share a `mutate_sibling` prologue/epilogue and a `splice_line!`
+  helper; behavior unchanged.
+
+---
+
+## 2.0.1 (2026-08-15)
 
 ### Summary
 
@@ -22,6 +54,16 @@ install/packaging contract — hence 2.0.0 even though the Ruby API is
 purely additive (`PGN::Bitboard` is new; existing classes are untouched).
 
 ### Added
+- **`PGN::Node`** — a navigable, mutable game-tree view via
+  `PGN::Game#root`: parent/children/variation links, a lazy cached
+  pure-Ruby `Node#position` (no native-engine dependency), and variation
+  management (`add_variation`, `add_main_variation`, `promote`, `demote`,
+  `promote_to_main`, `demote_to_last`, `delete`). `MoveText` remains the
+  source of truth; mutations edit it in place and normalize the affected
+  branching point to flat sibling storage, so `Game#moves` and the
+  serializer stay correct and PGN round-trips remain byte-identical for
+  un-mutated games. Non-breaking — `Game#moves` and `MoveText` keep their
+  shapes.
 - **`PGN::Bitboard::Engine`** (native): `Engine.new(fen)`, `#perft(depth)`,
   `#legal_moves` (sorted UCI), `#legal?(uci)`. Validates against the
   published perft suite (startpos depth 6 = 119,060,324; Kiwipete depth 5
@@ -67,10 +109,67 @@ undefined when the extension is absent.
 
 ---
 
-## Unreleased (attack-masks)
+## 2.0.0 (2026-08-15)
 
 ### Summary
 
+(Pre-release snapshot of the native Rust bitboard perft backend, before
+the small/medium roadmap and game-tree API work landed in 2.0.1.)
+
+---
+
+### Small + medium roadmap
+
+Small + medium TODO pass: public legal-move and outcome APIs on
+`PGN::Position`/`PGN::Game` delegating to the chessie engine, plus parsing
+and packaging hardening. Serialized PGN/FEN output stays byte-identical
+except where a task explicitly normalizes a quirk (nested comments are now
+escaped on output and unescaped on parse for stable round trips); 311
+specs green, RuboCop clean.
+
+### Added
+- **`PGN::Position#legal?(san_or_uci)`** and **`#legal_moves_san`**:
+  public legal-move API. `legal?` accepts SAN or UCI and resolves SAN by
+  matching `PGN::Notation.san` against the engine's legal moves (rejecting
+  ambiguous SAN). Raises `NameError` when the extension is absent.
+- **`PGN::Attack`** module + **`PGN::Position#in_check?`**, **`#attackers`**,
+  **`#mover_color`**, **`#opponent_color`**: attack detection extracted from
+  `Notation` private methods and exposed on `Position`.
+- **Game/position outcome detection**: `Position#checkmate?`/`#stalemate?`/
+  `#insufficient_material?`/`#fifty_move?`/`#outcome`, and `Game#threefold?`
+  (streams Zobrist hashes via `each_position`) / `Game#outcome`.
+- **`PGN::EPD`** read/write + **`PGN::FEN#to_epd`**: EPD shares FEN's first
+  four fields and keeps trailing operation fields verbatim.
+- **`PGN::Game#push(san)`** / **`#pop`**: mutable history; `push` validates
+  legality (raises `ArgumentError`) and invalidates the memoized position
+  list.
+
+### Changed
+- **`PGN::Move`**: parses `0-0`/`0-0-0` as castling (alongside `O-O`), so
+  UCI-style castling normalizes to canonical SAN through one path.
+- **Parser**: `tag_section` and `variation_list` are now ordinary
+  left-recursion with a single explicit `.reverse` (and first-occurrence-wins
+  tag merge) where each list is consumed; parse output is byte-identical
+  (same 2 shift/reduce conflicts).
+- **`MoveText#clean_text`**: idempotent — strips a single outermost brace
+  pair and unescapes `\{`/`\}`/`\\` into the canonical raw comment body, so
+  `Serializer` escaping and the lexer are symmetric and nested-comment
+  round trips are byte-stable. `Game#moves=` no longer sniffs comments for
+  leftover braces.
+- **`FEN#to_position`**: en passant square is no longer dropped (Ruby
+  conditional-assignment gotcha).
+- **Rakefile**: `Rake::ExtensionTask` now sets `cross_compile`/`cross_platform`
+  (single source of truth for `release-gems.yml`) and adds the `native:clean`
+  task that `native:gem` referenced.
+
+### Fixed
+- `FEN#to_position` en-passant round-trip regression (position lost the ep
+  square, which would have corrupted `legal?` and outcome detection).
+
+---
+
+### Attack masks
+
 Attack-mask pass: precomputed knight/king on-board target tables on
 `PGN::Board`, used by `Notation` (reaches/attacked/leaper moves) and
 `MoveCalculator` (knight/king origin lookup), plus a retained-memory

data/README.md

@@ -145,6 +145,33 @@ It handles captures, en passant, promotions, legal-move disambiguation
 (file / rank / full square, respecting pins), and check (`+`) / checkmate
 (`#`) suffixes.
 
+### Navigating and mutating the game tree
+
+{PGN::Game#root} returns a navigable {PGN::Node} tree over the mainline and
+its variations. A node knows its parent, its children (the mainline
+continuation first, then the variations), and the {PGN::Position} it
+represents. Mutations edit the underlying structure in place; call `#root`
+again for a fresh tree after mutating.
+
+```
+> game = PGN.parse(File.read("./examples/immortal_game.pgn")).first
+> root = game.root
+> root.main_line.map(&:notation)            # => ["e4", "e5", ...]
+> root.next.next.children.map(&:notation)   # alternatives at that position
+> root.next.next.position.to_fen.to_s       # the FEN after 1.e4 e5
+
+> root.next.next.add_variation("Nc6")       # add a variation
+> root = game.root                          # fresh tree after mutation
+> root.next.next.children.find { |n| n.notation == "Nc6" }.promote_to_main
+> game.to_pgn                                # serialized with the new mainline
+```
+
+`Node#position` is pure-Ruby (no native engine); it replays from the
+starting position and raises on an illegal SAN exactly like
+`Game#positions`. See `spec/node_spec.rb` for the full surface
+(`add_variation`, `add_main_variation`, `promote`, `demote`,
+`promote_to_main`, `demote_to_last`, `delete`).
+
 ## Benchmarks
 
 A reproducible profiling harness lives in `bench/`. It measures the

data/Rakefile

@@ -6,6 +6,18 @@ spec = Gem::Specification.load('pgn2.gemspec')
 Rake::ExtensionTask.new('pgn2_native', spec) do |ext|
   ext.ext_dir = 'ext/pgn2_native'
   ext.lib_dir = 'lib/pgn2_native'
+
+  # Cross-compile prebuilt platform gems via rake-compiler-dock. The list
+  # here is the single source of truth for {release-gems.yml}; keep them in
+  # sync. rb-sys's extconf picks up the Rake::ExtensionTask cross env vars.
+  ext.cross_compile  = true
+  ext.cross_platform = %w[
+    x86_64-linux
+    aarch64-linux
+    x86_64-darwin
+    aarch64-darwin
+  ]
+  ext.cross_config_options << '--enable-cross'
 end
 
 RuboCop::RakeTask.new
@@ -36,6 +48,12 @@ task bench: ['bench:moves', 'bench:parse']
 # Produces fat-binary platform gems so end users (and the chessellence
 # Docker build) need no Rust toolchain. Requires Docker locally.
 namespace :native do
+  desc 'Remove cross-compiled build artifacts and pkg/ (Docker build prep)'
+  task :clean do
+    Rake::Task['clean'].invoke
+    rm_rf 'pkg' if Dir.exist?('pkg')
+  end
+
   desc 'Cross-compile prebuilt platform gems via rake-compiler-dock'
   task :gem do
     require 'rake_compiler_dock'

data/TODO.md

@@ -3,70 +3,8 @@
 ## Parsing
 
 - Accept a more flexible input format
-- Support recursive variations
-- Support numeric annotation glyphs
-
-## Misc
-
-- Support converting a game to pgn format
-- Speed up parsing
-  - ✓ (done in 1.2.0) Removed `PGN::Lexer`'s per-token `Token` Struct
-    allocation on the parser hot path (`next_token_pair`), and collapsed
-    `scan_one`'s `[type, m, discarded]` tuple to a single returned string
-    (type/discarded stashed in ivars). The full `Token` is kept only for the
-    `#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).
-  (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.
-- 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
-  compatibility quirk is a single greppable line instead of implicit in
-  recursion direction.
-- Make `MoveText#clean_text` idempotent (or run it exactly once, at
-  construction) so `Game#moves=`/`#standardize_castling` doesn't need to
-  sniff a comment for leftover `{`/`}` to decide whether a MoveText is safe
-  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.
+- Tolerant parse mode: collect warnings/errors instead of failing on the
+  first bad move.
 
 ## Roadmap ideas (from pioz/chess + python-chess review)
 
@@ -76,58 +14,38 @@ Out of scope for now: SVG rendering, Chess960, Shredder-FEN, FRC castling.
 
 - [ ] Streaming/lazy PGN reader: yield games from an `IO` without slurping
       the whole file.
-- [ ] EPD read/write (`EPD#to_position`, `FEN#to_epd`).
-- [ ] Richer game-tree API: node-style mainline/variations, add/promote/
-      demote variations.
-- [ ] Nested-comment normalization + brace escaping for byte-perfect round
-      trips.
-- [ ] Tolerant parse mode: collect warnings/errors instead of failing on the
-      first bad move.
 
 ### Group 2 — Position Intelligence / Game Rules
 
-- [ ] Full legal-move API (`Position#legal_moves`, `Position#legal?(san)`).
-- [ ] Check / pin / attackers helper methods (logic already exists privately
-      in `Notation`).
-- [ ] Game outcome detection: checkmate, stalemate, insufficient material,
-      50-move rule, threefold repetition.
-- [ ] Mutable push/pop history (`game.push(san)`, `game.pop`).
-- [ ] Position equality/hash based on the FEN-relevant parts.
+`PGN::Bitboard::Engine` is a thin adapter over the `chessie` crate, so
+several of these are implemented by delegating from `PGN::Position` to the
+native engine rather than rewriting the logic in pure Ruby.
+
+- [ ] Pin-aware helpers beyond `Position#attackers` (e.g. pinned-piece
+      detection, discovered-check detection), delegating to chessie where
+      useful.
 
 ### Group 3 — Engine & Analysis Integration
 
 - [ ] Lightweight UCI/XBoard engine wrapper (`PGN::Engine`-style).
 - [ ] PGN annotation helpers: auto-generate NAGs/comments from engine info.
 - [ ] Optional Polyglot opening-book reader and/or Syzygy tablebase prober.
-- [ ] UCI-style castling normalization (see pioz/chess).
 
-### Group 4 — Performance / Internals  *(in progress on `perf/internals-plan`)*
+### Group 4 — Performance / Internals
 
-- [ ] FEN serializer that walks the 0x88 `@cells` array directly (skip
-      rebuilding `board.squares`).
 - [ ] Incremental Zobrist hashing in `Board`/`Position` for fast repetition /
-      transposition checks.
-- [ ] Lazy position iterator instead of eagerly building `Game#positions`.
-- [ ] Precomputed knight/king attack masks for SAN generation and legal-move
-      checks.
-- [x] Optional bitboard / C-extension backend for move generation / perft,
-      with a pure-Ruby fallback. *(done on `feat/rust-bitboard-perft` — see
-      `docs/superpowers/specs/2026-08-13-rust-bitboard-perft-design.md`;
-      `PGN::Bitboard::Engine#perft`/`#legal_moves`/`#legal?` via a Rust
-      `cdylib` shipped as precompiled platform gems.)*
-  - [ ] **Perft speed: pin-aware legal move generation.** Current legal perft
-        is ~20 Mnps (release, LTO); pseudo-legal perft is 76 Mnps, so the
-        per-move `in_check` (`is_attacked`) scan is ~3.7× of the runtime and
-        the whole gap to fast engines. Implementing pin-aware legality
-        (compute checkers + pinned pieces once per node, validate moves
-        without make/unmake, true bulk-count at depth 1) targets ~50–70 Mnps
-        (~2× off Stockfish). Keep the make/unmake path for the Ruby
-        `#legal_moves` API; only the `perft` hot path switches. Validated by
-        the existing perft oracle vs Stockfish (`bench/cross_check.rb`).
-  - [ ] Bulk-count at depth 1 (small, low-risk) and per-node `MoveList` buffer
-        reuse (avoid the per-node `Vec<Move>` alloc) — incremental wins below
-        the pin-aware rewrite.
-  - [ ] aarch64 (non-BMI2) falls back to the ray-walker sliders; add magic
-        bitboard tables there if its perft nps matters.
-  - [ ] Verify the `release-gems.yml` cross-compile (rake-compiler-dock) for
-        x86_64/aarch64 linux+darwin before relying on prebuilt gems.
+      transposition checks. Note: the previous attempt regressed replay
+      because `Bignum` XOR allocations on every move dwarfed the gains;
+      incremental update is only worth revisiting if something starts
+      consuming hashes on the hot path (e.g. `Game#threefold?` now streams
+      Zobrist hashes, so revisit if it shows up in profiles).
+- [ ] Final Docker verification of the `release-gems.yml` cross-compile
+      (rake-compiler-dock) for x86_64/aarch64 linux+darwin; the Rakefile
+      cross-compile config and `native:clean` task are wired, but the full
+      Docker build still wants confirming on a machine with Docker.
+- [ ] `Engine#legal_p`/`legal?` compares candidate moves via
+      `chessie::Move`'s `PartialEq<str>`, which allocates a `String` via
+      `to_uci()` per candidate scanned. Currently negligible (offset by
+      `legal_moves()` now being stack-allocated `ArrayVec` instead of a
+      heap `Vec`, and dwarfed by movegen/FFI cost) — only worth a cheap
+      numeric comparison if `legal?` ever ends up in a genuine hot loop.