pgn2 0.4.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2ec8fd9ce76a2a1296b89fd64bcdb5a32ba8711cb2a5d38ae14f2c268e1ad189
-  data.tar.gz: 6a3311806004f9334094b703e467b34c750c7632887d9559cc93d6aa79b7d2c6
+  metadata.gz: 8725cb68fa694a068cba0ee2226fa90b7b9018d18dfd8cbdc61f6f560c3e12e3
+  data.tar.gz: f551b1645e9559df049e2d87da4a99da0ab64ae05d031446d111876be5d1b7b9
 SHA512:
-  metadata.gz: 0575447c35a81edeabb4b2e3bde142737c4f9c4f1d47cf5698ce8381ba47c5a5a85ad08e5f908a6a287d068c581c39f3f1517f1196b9717b7eb75d1a1c6a1ea2
-  data.tar.gz: 9a873c2fa0870a7c9139e803a0c258c9c4111fa02ed370f58105b277b03c27de8da83df606a6b9bf13780018895c7b70bcff49e40269461571858384aca4d4d2
+  metadata.gz: 279e222b2cd8a736eb82979ab195b9983d79d3d61f8e1239f13de286efd5f42d6e5ef06b5d59fe0c8e36e323b12bb5567cf3995594ed2ed4eee60bcb70dcc521
+  data.tar.gz: 1f49fb6a4b4d18d161436cb0c2c91df7aab9e1203d8896095e912d12e0623cb7adae73ded9a147dde051ccc3f8af6a2a3ef804dd4f34f96d05c8ca94da954048

data/.github/workflows/ci.yml

@@ -0,0 +1,50 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    name: RSpec (ruby ${{ matrix.ruby }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: ['3.1', '3.2', '3.3', '3.4']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+      - run: bundle exec rspec --format documentation
+
+  rubocop:
+    name: RuboCop (non-blocking)
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3'
+          bundler-cache: true
+      - run: bundle exec rubocop
+
+  # Verifies that lib/pgn/pgn_parser.rb (committed) matches what `racc`
+  # regenerates from lib/pgn/pgn_parser.y, so the checked-in parser never
+  # drifts from the grammar source.
+  parser-reproducible:
+    name: Racc parser in sync with grammar
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3'
+          bundler-cache: true
+      - run: |
+          bundle exec racc -o /tmp/pgn_parser.check.rb lib/pgn/pgn_parser.y
+          diff -u lib/pgn/pgn_parser.rb /tmp/pgn_parser.check.rb

data/.github/workflows/publish.yml

@@ -0,0 +1,75 @@
+name: Publish to RubyGems
+
+# Publishes the gem to rubygems.org when a `v*` tag is pushed.
+#
+# Manual one-time setup (see the PR/commit notes):
+#   1. Create a RubyGems API key with at least the "Push rubygem" scope at
+#      https://rubygems.org/profile/api_keys
+#   2. Add it as a repository secret named RUBYGEMS_API_KEY:
+#      Settings -> Secrets and variables -> Actions -> New repository secret
+#
+# To release a new version locally:
+#   bump lib/pgn/version.rb -> commit -> tag v<x.y.z> -> git push --tags
+# This workflow then builds and pushes the .gem automatically.
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  test:
+    name: RSpec (ruby ${{ matrix.ruby }}) on tag
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: true
+      matrix:
+        ruby: ['3.1', '3.2', '3.3', '3.4']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+      - run: bundle exec rspec
+
+  publish:
+    name: Build & push gem
+    needs: test
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3'
+          bundler-cache: true
+
+      - name: Build gem
+        run: bundle exec rake build
+
+      - name: Configure RubyGems credentials
+        run: |
+          mkdir -p "$HOME/.gem"
+          printf -- ":rubygems_api_key: %s\n" "${RUBYGEMS_API_KEY}" > "$HOME/.gem/credentials"
+          chmod 0600 "$HOME/.gem/credentials"
+        env:
+          RUBYGEMS_API_KEY: ${{ secrets.RUBYGEMS_API_KEY }}
+
+      - name: Push gem
+        run: gem push pkg/*.gem
+
+      - name: Verify publication
+        continue-on-error: true
+        run: |
+          ver="$(ruby -rpgn/version -e 'print PGN::VERSION')"
+          for i in 1 2 3 4 5 6; do
+            if gem fetch pgn2 --version "$ver" --platform gem >/dev/null 2>&1; then
+              echo "pgn2 $ver published to rubygems.org"
+              exit 0
+            fi
+            sleep 5
+          done
+          echo "gem push succeeded but fetch verify timed out (rubygems propagation); check https://rubygems.org/gems/pgn2"

data/.rubocop.yml

@@ -0,0 +1,38 @@
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.0
+  SuggestExtensions: false
+  Exclude:
+    - "bin/**/*"
+    - "bench/**/*"
+    - "vendor/**/*"
+    - "pkg/**/*"
+
+# This is a small, mostly-stable gem; skip mandatory top-level docs.
+Style/Documentation:
+  Enabled: false
+
+Style/StringLiterals:
+  EnforcedStyle: single_quotes
+
+Style/FrozenStringLiteralComment:
+  EnabledForRuby: false
+  Enabled: true
+
+Layout/LineLength:
+  Max: 100
+
+# The SAN/PGN grammar and move-calculation logic are inherently branchy;
+# don't fight the domain, just keep an eye on egregious cases.
+Metrics/MethodLength:
+  Max: 20
+
+Metrics/AbcSize:
+  Max: 25
+
+Metrics/ClassLength:
+  Max: 150
+
+Metrics/BlockLength:
+  Exclude:
+    - "spec/**/*"

data/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+## 1.0.0 (2026-08-13)
+
+### Summary
+
+First stable release. The parser has been migrated off the abandoned `whittle`
+gem (v0.0.8, 2011) to a stdlib `Racc` + `StringScanner` parser. The public API
+(`PGN.parse`, `PGN::Game`, `PGN::Serializer`, `PGN::Board`, `PGN::Move`) is
+unchanged and serialized PGN output stays byte-compatible with the previous
+release.
+
+### Added
+- Parser now accepts tag values containing unescaped double-quotes (e.g.
+  `[Event "IRT BLITZ "Sub Zonal""]`), a form found in real-world PGN files.
+  Previously the parser raised on such input.
+- New fixtures `spec/pgn_files/doublequotes.pgn` and
+  `spec/pgn_files/specialcharacters.pgn`, plus tests for parsing tag values
+  with inner quotes and for the `Encoding` argument of `PGN.parse`.
+- `PGN::Serializer` and `PGN::Game#to_pgn` (carried over from the 0.x line).
+- Comprehensive test and profiling infrastructure: exhaustive characterization
+  specs for `Board`, `Move`, and `MoveCalculator`; a round-trip gate over all
+  fixtures; and allocation/throughput harnesses under `bench/`.
+
+### Changed
+- **Parser rewritten on `Racc` + `StringScanner`** (stdlib only, no new runtime
+  dependency). `lib/pgn/pgn_parser.y` (generated to `lib/pgn/pgn_parser.rb`)
+  mirrors the former grammar; `lib/pgn/lexer.rb` is the StringScanner lexer.
+  `PGN::Parser` is now a thin facade over `PGN::PgnParser`.
+- **Removed the `whittle` runtime dependency.**
+- **Fixed a parser reentrancy bug**: the legacy parser accumulated `@@pgn` and
+  `@@game_comment` in class variables shared across calls. The new parser holds
+  all state per instance, so repeated and concurrent parses no longer leak
+  state. `PGN::Game#pgn` is now sliced from per-game byte offsets (eliminating
+  the previous O(n^2) `@@pgn +=` accumulation).
+- Performance: parse-only allocations −55% objects / −70% bytes; parse-only
+  throughput ~3.5× faster; parse + replay ~3.0× faster. Board copy-on-write,
+  zero-allocation `Board#at(str)`, single-pass `FEN#board_string`, and
+  streamlined `Move`/`MoveCalculator` hot paths. See `bench/IMPROVEMENTS.md`.
+- `spec/spec_helper.rb`: removed the deprecated
+  `treat_symbols_as_metadata_keys_with_true_values` config (drops an RSpec
+  deprecation warning).
+
+### Notes
+- The grammar deliberately replicates two legacy parser quirks for
+  byte-compatible serialization: variations are emitted in reverse source
+  order, and duplicate tags keep the first value with reverse insertion order.
+  These can be revisited in a future release.
+
+### Credits
+- The double-quotes parsing fix and the new fixtures were contributed by
+  Alexis Vargas (https://github.com/lexisvar), ported from the `pgn3` fork.

data/README.md

@@ -1,7 +1,13 @@
 # PGN2
 
-This is a fork from [pgn](https://github.com/capicue/pgn) gem.
-A PGN parser and FEN generator for ruby.
+[![CI](https://github.com/muriloime/pgn/actions/workflows/ci.yml/badge.svg)](https://github.com/muriloime/pgn/actions/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/pgn2.svg)](https://rubygems.org/gems/pgn2)
+
+A PGN parser and FEN generator for Ruby, with a serializer and an interactive
+play mode. The parser is built on the Ruby standard library (`Racc` +
+`StringScanner`) and has no native or third-party runtime dependencies.
+
+This is a fork of the [pgn](https://github.com/capicue/pgn) gem.
 
 ## Usage
 
@@ -74,6 +80,22 @@ game = PGN::Game.new(moves)
 Note that if you simply want an abstract syntax tree from the pgn file,
 you can use `PGN::Parser.parse`.
 
+### Serializing games
+
+A game round-trips to PGN text with `PGN::Game#to_pgn` (or `PGN::Serializer`):
+
+```
+> game.to_pgn
+=> "[Event \"?\"]\n[Site \"?\"]\n[White \"Adolf Anderssen\"]\n...\n1. e4 e5 2. Nf3 ... 1-0\n"
+
+> PGN.parse(game.to_pgn).first.result == game.result
+=> true
+```
+
+Comments, variations, annotations, the `FEN` starting position, and game
+comments are all serialized. See `spec/game_spec.rb` for the round-trip
+gate that exercises every fixture.
+
 ### Dealing with FEN strings
 
 [Forsyth Edwards Notation](http://en.wikipedia.org/wiki/Forsyth%E2%80%93Edwards_Notation)
@@ -100,6 +122,82 @@ _ _ _ ♙ _ _ _ _
 => r1bk3r/p2pBpNp/n4n2/1p1NP2P/6P1/3P4/P1P1K3/q5b1 b - - 1 22
 ```
 
+## Benchmarks
+
+A reproducible profiling harness lives in `bench/`. It measures the
+allocation and throughput cost of the hot paths (move application, board
+copying, parsing), so efficiency changes can be proven with a before/after
+diff of committed baselines.
+
+Run the full suite (writes/updates the committed baseline files):
+
+```
+bundle exec rake bench
+```
+
+Individual profiles:
+
+```
+bundle exec rake bench:moves  # move/board profiling only
+bundle exec rake bench:parse  # parse profiling only
+```
+
+`bench/baseline_moves.txt` and `bench/baseline_parse.txt` are committed
+snapshots of the current implementation. After an optimization, re-run
+`rake bench` and `git diff` the baseline files: allocation counts/bytes
+should drop, ips numbers should rise.
+
+### Compared to the original `pgn` gem
+
+pgn2 is a fork of the upstream [`pgn`](https://github.com/capicue/pgn) gem.
+The "original" figures below come from `bench/*.pre-optimization.txt`,
+snapshots captured before any hot-path work — at that point pgn2's parser
+(`whittle`), `Board#dup` (flat copy), and `Board#at(str)` (string-alloc)
+were byte-for-byte the original gem's code. The "pgn2" figures are the
+current committed baselines (stdlib `Racc` + `StringScanner` parser,
+column-level copy-on-write `Board`, getbyte-arithmetic `at`). All numbers
+are from the same machine (Ruby 4.0.5, x86_64-linux); allocation counts are
+deterministic, throughput is over a 5 s window so treat ms/i as the stable
+signal (ips is noisy).
+
+Move pipeline — immortal game, 45 plies (`bench/profile_moves.rb`):
+
+| Metric | original `pgn` | pgn2 | Δ |
+|---|---:|---:|---:|
+| Replay allocations (objects) | 5124 | 2565 | -2559 (-50.0%) |
+| Replay allocations (bytes) | 262608 | 155296 | -107312 (-40.9%) |
+| `Board#dup` x45 (objects) | 451 | 91 | -360 (-79.8%) |
+| `Board#dup` x45 (bytes) | 43096 | 6736 | -36360 (-84.4%) |
+| `Board#at(str)` x1000 (objects) | 6000 | 0 | -6000 (-100%) |
+| `Board#at(str)` x1000 (bytes) | 240000 | 0 | -240000 (-100%) |
+| Replay throughput | 1.132k ips (884 µs/i) | 1.669k ips (599 µs/i) | ~1.5x faster |
+
+Parser — 500 immortal games (`bench/profile_parse.rb`):
+
+| Metric | original `pgn` | pgn2 | Δ |
+|---|---:|---:|---:|
+| Parse-only allocations (objects) | 1248065 | 557035 | -691030 (-55.4%) |
+| Parse-only allocations (bytes) | 120370470 | 36636902 | -83733568 (-69.6%) |
+| Parse + replay allocations (objects) | 3778073 | 1614087 | -2163986 (-57.3%) |
+| Parse + replay allocations (bytes) | 249570048 | 105404152 | -144165896 (-57.7%) |
+| Parse-only throughput | 1.513 ips (661 ms/i) | 4.711 ips (212 ms/i) | ~3.1x faster |
+| Parse + replay throughput | 0.933 ips (1070 ms/i) | 2.698 ips (371 ms/i) | ~2.9x faster |
+
+What changed to get there:
+
+1. `Board#at(str)` / `coordinates_for` — getbyte arithmetic (zero-alloc string lookup).
+2. `MoveCalculator#king_position` — early exit.
+3. `Move#initialize` — explicit setters (no per-move `names` array).
+4. `FEN#board_string` — single-pass serialization.
+5. `Board` — column-level copy-on-write (`dup` shares columns, `update` clones one).
+6. Parser — `whittle` (≈80% of parse allocations) replaced by stdlib `Racc` +
+   `StringScanner`; `PGN::Game#pgn` sliced from per-game byte offsets (no O(n²)
+   `@@pgn +=` accumulation).
+
+Public output (FEN, PGN) is byte-identical to the original gem; the full
+suite (187 examples) stays green. See `bench/IMPROVEMENTS.md` for the per-step
+before/after deltas that produced these tables.
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -117,7 +215,9 @@ Or install it yourself as:
 ## Contributing
 
 1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
+2. Create your feature branch (`git checkout -b my-new-feature` from `main`)
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
+5. Open a Pull Request against `main`
+
+See `CHANGELOG.md` for release history.

data/Rakefile

@@ -1 +1,21 @@
 require "bundler/gem_tasks"
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+namespace :bench do
+  desc "Run move/board profiling and write bench/baseline_moves.txt"
+  task :moves do
+    sh "bundle exec ruby bench/profile_moves.rb > bench/baseline_moves.txt"
+    puts File.read("bench/baseline_moves.txt")
+  end
+
+  desc "Run parse profiling and write bench/baseline_parse.txt"
+  task :parse do
+    sh "bundle exec ruby bench/profile_parse.rb > bench/baseline_parse.txt"
+    puts File.read("bench/baseline_parse.txt")
+  end
+end
+
+desc "Run all benchmarks and (re)write bench/baseline_*.txt"
+task :bench => ["bench:moves", "bench:parse"]

data/bench/IMPROVEMENTS.md

@@ -0,0 +1,75 @@
+# Efficiency improvements — before/after
+
+Captured by `rake bench` on the same machine. "BEFORE" = `bench/*.pre-optimization.txt`
+(pre-optimization snapshot). "AFTER" = `bench/baseline_*.txt`.
+
+## bench/profile_moves.rb (immortal game, 45 plies)
+
+| Metric | BEFORE | AFTER | Δ |
+|---|---|---|---|
+| Replay allocations (objects) | 5124 | 2565 | -2559 |
+| Replay allocations (bytes) | 262608 | 155296 | -107312 |
+| Board#dup x45 (objects) | 451 | 91 | -360 |
+| Board#dup x45 (bytes) | 43096 | 6736 | -36360 |
+| Board#at(str) x1000 (objects) | 6000 | 0 | -6000 |
+| Board#at(str) x1000 (bytes) | 240000 | 0 | -240000 |
+
+## bench/profile_parse.rb (500 immortal games)
+
+| Metric | BEFORE | AFTER | Δ |
+|---|---|---|---|
+| Parse-only allocations (objects) | 1248065 | 1248065 | 0 |
+| Parse-only allocations (bytes) | 120370470 | 120370470 | 0 |
+| Parse + replay allocations (objects) | 3778073 | 2498573 | -1279500 |
+| Parse + replay allocations (bytes) | 249570048 | 195914048 | -53656000 |
+
+## Changes applied
+
+1. `Board#at(str)` / `coordinates_for` — getbyte arithmetic (zero-alloc string lookup).
+2. `MoveCalculator#king_position` — early exit.
+3. `Move#initialize` — explicit setters (no per-move `names` array).
+4. `FEN#board_string` — single-pass serialization.
+5. `Board` — column-level copy-on-write (`dup` shares columns, `update` clones one).
+
+All existing characterization specs remain green; public output (FEN, PGN) is byte-identical.
+
+## Parser migration: whittle -> Racc + StringScanner (2026-08-13)
+
+The abandoned `whittle` gem (v0.0.8, 2011) was replaced by a stdlib `Racc` +
+`StringScanner` parser (`lib/pgn/pgn_parser.y`, generated to
+`lib/pgn/pgn_parser.rb`; lexer in `lib/pgn/lexer.rb`). whittle was responsible
+for ~80% of parse allocations.
+
+Corpus: 500 immortal games (`BENCH_N=500`). Baseline = `bench/baseline_parse.txt`
+(whittle). New = `bench/baseline_parse.racc.txt`. Allocation counts are
+deterministic; throughput is noisy over a 5 s window (use ms/i).
+
+| Metric | whittle | racc | Δ |
+|---|---|---|---|
+| Parse-only allocations (objects) | 1248065 | 557035 | -691030 (-55.4%) |
+| Parse-only allocations (bytes) | 120370470 | 36636902 | -83733568 (-69.6%) |
+| Parse + replay allocations (objects) | 2498573 | 1614087 | -884486 (-35.4%) |
+| Parse + replay allocations (bytes) | 195914048 | 105404152 | -90509896 (-46.2%) |
+| Parse-only throughput (ms/i) | 741 | 212 | -529 (~3.5x faster) |
+| Parse + replay throughput (ms/i) | 1114 | 371 | -743 (~3.0x faster) |
+
+### What changed
+- `lib/pgn/pgn_parser.y` / `pgn_parser.rb`: Racc grammar mirroring the whittle
+  rules, held as instance state (fixes the `@@pgn`/`@@game_comment` reentrancy
+  bug). `PGN::Game#pgn` is sliced from per-game byte offsets (no O(n^2)
+  `@@pgn +=` accumulation).
+- `lib/pgn/lexer.rb`: StringScanner (C ext) lexer reusing whittle's exact
+  terminal regexes; records per-game content-start byte offsets.
+- `lib/pgn/parser.rb`: thin facade delegating to `PGN::PgnParser`.
+- whittle dependency dropped; `lib/pgn/whittle_parser.rb` deleted.
+
+### Behavior preservation
+The grammar deliberately replicates whittle's quirks so parsed-game
+serialization stays byte-compatible: right-recursive `variation_list` (variation
+order reverses) and right-recursive `tag_section` (reverse insertion order,
+first-wins). `game.pgn` is verbatim raw text. A golden-equivalence spec (now
+removed with whittle) confirmed identical output on all 14 fixtures + 11 inline
+inputs during the migration; 32 explicit parser specs now pin the behavior
+permanently (`spec/parser_explicit_spec.rb`).
+
+Full suite: 187 examples, 0 failures.

data/bench/baseline_moves.pre-optimization.txt

@@ -0,0 +1,22 @@
+Workload: immortal game, 45 plies
+
+=== 1. Replay allocations (45 plies, no parse) ===
+total_allocated objects: 5124
+total_allocated bytes:   262608
+
+=== 2. Board#dup x45 (target of flat-board COW) ===
+total_allocated objects: 451
+total_allocated bytes:   43096
+
+=== 3. Board#at(str) x1000 (target of coord-arithmetic at) ===
+total_allocated objects: 6000
+total_allocated bytes:   240000
+
+=== 4. Replay throughput (ips, excluding parse) ===
+ruby 4.0.5 (2026-05-20 revision 64336ffd0e) +PRISM [x86_64-linux]
+Warming up --------------------------------------
+     replay immortal    75.000 i/100ms
+Calculating -------------------------------------
+     replay immortal      1.132k (±46.9%) i/s  (883.58 μs/i) -      5.700k in   5.036401s
+
+Done. Compare this file against bench/baseline_moves.txt after optimizations.

data/bench/baseline_moves.txt

@@ -0,0 +1,22 @@
+Workload: immortal game, 45 plies
+
+=== 1. Replay allocations (45 plies, no parse) ===
+total_allocated objects: 2565
+total_allocated bytes:   155296
+
+=== 2. Board#dup x45 (target of flat-board COW) ===
+total_allocated objects: 91
+total_allocated bytes:   6736
+
+=== 3. Board#at(str) x1000 (target of coord-arithmetic at) ===
+total_allocated objects: 0
+total_allocated bytes:   0
+
+=== 4. Replay throughput (ips, excluding parse) ===
+ruby 4.0.5 (2026-05-20 revision 64336ffd0e) +PRISM [x86_64-linux]
+Warming up --------------------------------------
+     replay immortal    96.000 i/100ms
+Calculating -------------------------------------
+     replay immortal      1.669k (±46.5%) i/s  (599.18 μs/i) -      8.352k in   5.004383s
+
+Done. Compare this file against bench/baseline_moves.txt after optimizations.

data/bench/baseline_parse.pre-optimization.txt

@@ -0,0 +1,25 @@
+Corpus: 500 copies of the immortal game
+
+=== 1. Parse-only allocations (500 games) ===
+total_allocated objects: 1248065
+total_allocated bytes:   120370470
+
+=== 2. Parse + replay allocations (500 games) ===
+total_allocated objects: 3778073
+total_allocated bytes:   249570048
+
+=== 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      1.513 (± 0.0%) i/s  (661.01 ms/i) -      8.000 in   5.288062s
+
+=== 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      0.933 (± 0.0%) i/s     (1.07 s/i) -      6.000 in   6.431545s
+
+Done. Compare this file against bench/baseline_parse.txt after optimizations.

data/bench/baseline_parse.racc.txt

@@ -0,0 +1,25 @@
+Corpus: 500 copies of the immortal game
+
+=== 1. Parse-only allocations (500 games) ===
+total_allocated objects: 557035
+total_allocated bytes:   36636902
+
+=== 2. Parse + replay allocations (500 games) ===
+total_allocated objects: 1614087
+total_allocated bytes:   105404152
+
+=== 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.711 (±63.7%) i/s  (212.27 ms/i) -     24.000 in   5.094454s
+
+=== 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      2.698 (±37.1%) i/s  (370.63 ms/i) -     14.000 in   5.188813s
+
+Done. Compare this file against bench/baseline_parse.txt after optimizations.

data/bench/baseline_parse.txt

@@ -0,0 +1,25 @@
+Corpus: 500 copies of the immortal game
+
+=== 1. Parse-only allocations (500 games) ===
+total_allocated objects: 1248065
+total_allocated bytes:   120370470
+
+=== 2. Parse + replay allocations (500 games) ===
+total_allocated objects: 2498573
+total_allocated bytes:   195914048
+
+=== 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      1.349 (± 0.0%) i/s  (741.33 ms/i) -      7.000 in   5.189280s
+
+=== 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      0.897 (± 0.0%) i/s     (1.11 s/i) -      5.000 in   5.572640s
+
+Done. Compare this file against bench/baseline_parse.txt after optimizations.

data/bench/profile_moves.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+# Measures per-move allocation and replay throughput for the move pipeline.
+# Run with:  bundle exec ruby bench/profile_moves.rb
+# Captured baseline: bench/baseline_moves.txt (via rake bench:moves)
+
+$LOAD_PATH.unshift(File.expand_path('lib', File.join(__dir__, '..')))
+require 'pgn'
+require 'memory_profiler'
+require 'benchmark/ips'
+
+EXAMPLES = File.join(__dir__, '..', 'examples')
+IMMORTAL = File.read(File.join(EXAMPLES, 'immortal_game.pgn'))
+GAME     = PGN.parse(IMMORTAL).freeze
+SAN      = GAME.first.moves.map(&:notation).freeze
+PLY      = SAN.length
+
+puts "Workload: immortal game, #{PLY} plies"
+
+# --- 1. Replay allocations (move application only, no parse) -----------------
+replay_report = MemoryProfiler.report do
+  pos = GAME.first.starting_position
+  SAN.each { |m| pos = pos.move(m) }
+end
+
+puts "\n=== 1. Replay allocations (#{PLY} plies, no parse) ==="
+puts "total_allocated objects: #{replay_report.total_allocated}"
+puts "total_allocated bytes:   #{replay_report.total_allocated_memsize}"
+
+# --- 2. Board#dup share (the flat-board optimization target) ------------------
+dup_report = MemoryProfiler.report { PLY.times { GAME.first.starting_position.board.dup } }
+
+puts "\n=== 2. Board#dup x#{PLY} (target of flat-board COW) ==="
+puts "total_allocated objects: #{dup_report.total_allocated}"
+puts "total_allocated bytes:   #{dup_report.total_allocated_memsize}"
+
+# --- 3. Board#at(str) share (the at(str) optimization target) ---------------
+start_board = GAME.first.starting_position.board
+at_report = MemoryProfiler.report { 1000.times { start_board.at('e4') } }
+
+puts "\n=== 3. Board#at(str) x1000 (target of coord-arithmetic at) ==="
+puts "total_allocated objects: #{at_report.total_allocated}"
+puts "total_allocated bytes:   #{at_report.total_allocated_memsize}"
+
+# --- 4. Replay throughput (fresh game each iter to defeat memoization) ------
+puts "\n=== 4. Replay throughput (ips, excluding parse) ==="
+Benchmark.ips do |x|
+  x.config(time: 5, warmup: 1)
+  x.report('replay immortal') do
+    PGN::Game.new(SAN, GAME.first.tags, GAME.first.result).positions
+  end
+end
+
+puts "\nDone. Compare this file against bench/baseline_moves.txt after optimizations."