pgn2 0.4.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2ec8fd9ce76a2a1296b89fd64bcdb5a32ba8711cb2a5d38ae14f2c268e1ad189
-  data.tar.gz: 6a3311806004f9334094b703e467b34c750c7632887d9559cc93d6aa79b7d2c6
+  metadata.gz: b17339791fa63da88b55a180d613c124509f7c286552fd9bb62dcea162eb3325
+  data.tar.gz: 2283fa7d6fbf06d54bebbdb9675427c2c51743627423db6bdd91df71a8e2926f
 SHA512:
-  metadata.gz: 0575447c35a81edeabb4b2e3bde142737c4f9c4f1d47cf5698ce8381ba47c5a5a85ad08e5f908a6a287d068c581c39f3f1517f1196b9717b7eb75d1a1c6a1ea2
-  data.tar.gz: 9a873c2fa0870a7c9139e803a0c258c9c4111fa02ed370f58105b277b03c27de8da83df606a6b9bf13780018895c7b70bcff49e40269461571858384aca4d4d2
+  metadata.gz: 311d858dca8016414e862b016fe694dff758ea575194d1a4256ebfa02e4427bc389ca291db5eb4a4cf547839e74e717aaeaed68fece0b43a1faf840148b87235
+  data.tar.gz: a0ad909b77394c5d7982db61ff37eb4ff02b2e1241b942e48b79bf290c70f5e6e756432fed01a5041179f27546faa2edae2a3b0cd54ff9a7f13a6bb3ac95c006

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/.github/workflows/release.yml

@@ -0,0 +1,103 @@
+name: Release
+
+# Auto-releases on any push to `main` whose version (lib/pgn/version.rb) does
+# not yet have a matching `v<x.y.z>` tag. It gates on the RSpec matrix, then
+# creates the tag and pushes the gem to rubygems.org in this same workflow
+# (a tag pushed by the GITHUB_TOKEN does NOT trigger other workflows, so the
+# publish happens here directly to avoid that limitation).
+#
+# Manual releases still work: `git tag vX.Y.Z && git push origin vX.Y.Z` fires
+# publish.yml (human-pushed tags do trigger workflows).
+#
+# Requires the RUBYGEMS_API_KEY repository secret (already set).
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  check:
+    name: Detect version bump
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.ver.outputs.version }}
+      should_release: ${{ steps.ver.outputs.should_release }}
+    steps:
+      - uses: actions/checkout@v4
+      - id: ver
+        run: |
+          version="$(ruby -Ilib -rpgn/version -e 'print PGN::VERSION')"
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+          if git ls-remote --tags origin "refs/tags/v$version" | grep -q .; then
+            echo "should_release=false" >> "$GITHUB_OUTPUT"
+            echo "v$version already tagged; skipping release"
+          else
+            echo "should_release=true" >> "$GITHUB_OUTPUT"
+            echo "v$version is new; will release"
+          fi
+
+  test:
+    name: RSpec (ruby ${{ matrix.ruby }})
+    needs: check
+    if: needs.check.outputs.should_release == 'true'
+    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
+
+  release:
+    name: Tag & publish
+    needs: [check, test]
+    if: needs.check.outputs.should_release == 'true'
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3'
+          bundler-cache: true
+
+      - name: Create and push tag v${{ needs.check.outputs.version }}
+        run: |
+          git config user.name  "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git tag "v${{ needs.check.outputs.version }}" -m "v${{ needs.check.outputs.version }}"
+          git push origin "v${{ needs.check.outputs.version }}"
+
+      - 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="${{ needs.check.outputs.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; check https://rubygems.org/gems/pgn2"

data/.gitignore

@@ -17,4 +17,5 @@ test/version_tmp
 tmp
 
 
-tags
+tags
+*.output

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,84 @@
+# Changelog
+
+## 1.1.0 (2026-08-13)
+
+### Summary
+
+Performance quick wins ("Approach A"): safe, behavior-compatible
+micro-optimizations on top of the 1.0 parser. No public API changes; serialized
+PGN/FEN output stays byte-identical. See
+`docs/superpowers/specs/2026-08-13-pgn-performance-quick-wins-design.md` and
+`bench/IMPROVEMENTS.md` for the design and per-step deltas.
+
+### Changed
+- **Lexer hot path**: `PGN::Lexer#next_token_pair` returns `[type, value]`
+  without allocating a `Token` Struct (or its `keyword_init` Hash), via a shared
+  scanning routine that preserves `game_starts` for verbatim `pgn` slicing.
+  `PgnParser#next_token` uses it.
+- **`PGN::Game#moves=`**: reuses an existing `MoveText` when its comment is
+  already clean (halving `MoveText` allocations on the parse path); still
+  re-wraps to preserve the legacy double-`clean_text` for multi-line/nested
+  comments.
+- **`PGN::Move#piece=`**: non-allocating castling guard (`start_with?('O')`
+  instead of `match('O-O')`), removing a `MatchData` from every `Move.new`.
+- **`PGN::Position`**: `next_player` uses a ternary instead of
+  `(PLAYERS - [player])`; `Position#move` skips `castling - restrictions` when
+  there are no restrictions.
+- **`PGN::MoveCalculator`**: memoized `destination_coords`, frozen
+  `ROOK_RESTRICTIONS` constant, empty short-circuit in `castling_restrictions`.
+- **`PGN::Move#pawn?`**: non-allocating (`==` instead of `%w[P p].include?`).
+- Performance vs 1.0: replay allocations −21% objects / −27% bytes; parse-only
+  allocations −3.6% objects / −28% bytes; parse + replay −15% objects / −28%
+  bytes. The full hand-rolled SAN parser was deferred (marginal payoff, high
+  risk) per the design's "measure first" guidance.
+
+## 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,100 @@ _ _ _ ♙ _ _ _ _
 => 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** and the headline signal. **Throughput is reported as the
+median of N back-to-back wall-clock runs** (whittle-era commit `1360bfc` vs
+current `main`): the `benchmark-ips` harness has ±30–60% per-run variance, so
+its single-run `ms/i` is not reliable across versions — e.g. the Racc baseline
+once recorded 371 ms/i (±37%) for parse+replay but the same commit measures
+~1017 ms reproduced today. `bench/baseline_*.txt` remains the harness of
+record for allocations.
+
+Move pipeline — immortal game, 45 plies (`bench/profile_moves.rb`):
+
+| Metric | original `pgn` | pgn2 | Δ |
+|---|---:|---:|---:|
+| Replay allocations (objects) | 5124 | 1710 | -3414 (-66.7%) |
+| Replay allocations (bytes) | 262608 | 103760 | -158848 (-60.5%) |
+| `Board#dup` x45 (objects) | 451 | 136 | -315 (-69.8%) |
+| `Board#dup` x45 (bytes) | 43096 | 10336 | -32760 (-76.0%) |
+| `Board#at(str)` x1000 (objects) | 6000 | 0 | -6000 (-100%) |
+| `Board#at(str)` x1000 (bytes) | 240000 | 0 | -240000 (-100%) |
+| Replay throughput | 841 µs/i | 766 µs/i | ~1.10x faster |
+
+Parser — 500 immortal games (`bench/profile_parse.rb`):
+
+| Metric | original `pgn` | pgn2 | Δ |
+|---|---:|---:|---:|
+| Parse-only allocations (objects) | 1248065 | 603537 | -644528 (-51.6%) |
+| Parse-only allocations (bytes) | 120370470 | 28257414 | -92113056 (-76.5%) |
+| Parse + replay allocations (objects) | 3778073 | 1427586 | -2350487 (-62.2%) |
+| Parse + replay allocations (bytes) | 249570048 | 78104136 | -171465912 (-68.7%) |
+| Parse-only throughput | 1461 ms/i | 327 ms/i | ~4.5x faster |
+| Parse + replay throughput | 1938 ms/i | 826 ms/i | ~2.35x 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).
+7. `PGN::Lexer#next_token_pair` — parser hot path returns `[type, value]`
+   without allocating a `Token` Struct (or its `keyword_init` Hash), via a
+   shared scanning routine that preserves `game_starts` for verbatim `pgn` slicing.
+8. `PGN::Game#moves=` — reuse existing `MoveText` when its comment is already
+   clean; halve `MoveText` allocations on the parse path (still re-wraps to
+   preserve the legacy double-`clean_text` for multi-line/nested comments).
+9. `PGN::Move#piece=` — non-allocating castling guard (`start_with?('O')`
+   instead of `match('O-O')`), removing a `MatchData` from every `Move.new`.
+10. `PGN::Position#next_player` — ternary instead of `(PLAYERS - [player])`;
+    `Position#move` skips `castling - restrictions` when there are none.
+11. `PGN::MoveCalculator` — memoized `destination_coords`, frozen
+    `ROOK_RESTRICTIONS`, empty short-circuit in `castling_restrictions`;
+    `Move#pawn?` non-allocating.
+
+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
+before/after deltas that produced these tables.
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -117,7 +233,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/TODO.md

@@ -10,3 +10,12 @@
 
 - Support converting a game to pgn format
 - Speed up parsing
+  - Collapse PGN::Lexer's per-token allocation chain (Array in `scan_one` ->
+    `Token` struct -> Array in racc's `next_token`) to fewer allocations on
+    the hot path; keep the full `Token` (with offset/line) only for the
+    `#tokens` spec helper, which is its only consumer.
+- 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.