pgn2 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8725cb68fa694a068cba0ee2226fa90b7b9018d18dfd8cbdc61f6f560c3e12e3
-  data.tar.gz: f551b1645e9559df049e2d87da4a99da0ab64ae05d031446d111876be5d1b7b9
+  metadata.gz: b17339791fa63da88b55a180d613c124509f7c286552fd9bb62dcea162eb3325
+  data.tar.gz: 2283fa7d6fbf06d54bebbdb9675427c2c51743627423db6bdd91df71a8e2926f
 SHA512:
-  metadata.gz: 279e222b2cd8a736eb82979ab195b9983d79d3d61f8e1239f13de286efd5f42d6e5ef06b5d59fe0c8e36e323b12bb5567cf3995594ed2ed4eee60bcb70dcc521
-  data.tar.gz: 1f49fb6a4b4d18d161436cb0c2c91df7aab9e1203d8896095e912d12e0623cb7adae73ded9a147dde051ccc3f8af6a2a3ef804dd4f34f96d05c8ca94da954048
+  metadata.gz: 311d858dca8016414e862b016fe694dff758ea575194d1a4256ebfa02e4427bc389ca291db5eb4a4cf547839e74e717aaeaed68fece0b43a1faf840148b87235
+  data.tar.gz: a0ad909b77394c5d7982db61ff37eb4ff02b2e1241b942e48b79bf290c70f5e6e756432fed01a5041179f27546faa2edae2a3b0cd54ff9a7f13a6bb3ac95c006

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/CHANGELOG.md

@@ -1,5 +1,37 @@
 # 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

data/README.md

@@ -156,32 +156,37 @@ snapshots captured before any hot-path work — at that point pgn2's parser
 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).
+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 | 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%) |
+| 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 | 1.132k ips (884 µs/i) | 1.669k ips (599 µs/i) | ~1.5x faster |
+| 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 | 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 |
+| 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:
 
@@ -193,9 +198,22 @@ What changed to get there:
 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 (187 examples) stays green. See `bench/IMPROVEMENTS.md` for the per-step
+suite (182 examples) stays green. See `bench/IMPROVEMENTS.md` for the per-step
 before/after deltas that produced these tables.
 
 ## Installation

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.

data/bench/IMPROVEMENTS.md

@@ -73,3 +73,71 @@ inputs during the migration; 32 explicit parser specs now pin the behavior
 permanently (`spec/parser_explicit_spec.rb`).
 
 Full suite: 187 examples, 0 failures.
+
+## Quick wins (Approach A) — 2026-08-13
+
+Safe, behavior-compatible micro-optimizations on top of the Racc parser.
+Spec: `docs/superpowers/specs/2026-08-13-pgn-performance-quick-wins-design.md`.
+"BEFORE" = `bench/baseline_*.pre-quickwins.txt` (working tree immediately before
+this change). "AFTER" = `bench/baseline_*.txt`.
+
+### bench/profile_moves.rb (immortal game, 45 plies)
+
+| Metric | BEFORE | AFTER | Δ |
+|---|---|---|---|
+| Replay allocations (objects) | 2177 | 1710 | -467 (-21.4%) |
+| Replay allocations (bytes) | 141616 | 103760 | -37856 (-26.7%) |
+| Replay throughput (µs/i) | 931.70 | 848.64 | -83.06 (-8.9%) |
+
+### bench/profile_parse.rb (500 immortal games)
+
+| Metric | BEFORE | AFTER | Δ |
+|---|---|---|---|
+| Parse-only allocations (objects) | 626037 | 603537 | -22500 (-3.6%) |
+| Parse-only allocations (bytes) | 39417414 | 28257414 | -11160000 (-28.3%) |
+| Parse-only throughput (ms/i) | 318.39 | 274.08 | -44.31 (-13.9%) |
+| Parse + replay allocations (objects) | 1683087 | 1427586 | -255501 (-15.2%) |
+| Parse + replay allocations (bytes) | 108184152 | 78104136 | -30080016 (-27.8%) |
+| Parse + replay throughput (ms/i) | 795.32 | 715.05 | -80.27 (-10.1%) |
+
+### Changes applied
+
+1. `PGN::Lexer` — added `next_token_pair` (returns `[type, value]`, no `Token`
+   Struct) built on a shared private `scan_next` routine that preserves the
+   `note_token`/`advance_line`/`game_starts` side effects. `next_token`/`tokens`
+   unchanged. `PgnParser#next_token` (in `.y` and generated `.rb`) now uses
+   `next_token_pair`. Eliminates the per-token `Token` Struct + its
+   `keyword_init` Hash (the larger win in bytes).
+2. `PGN::Game#moves=` — reuses an existing `MoveText` directly when its comment
+   is already fully cleaned (nil or brace-free); still re-wraps (preserving the
+   legacy double-`clean_text` for multi-line/nested comments) when the comment
+   carries braces. Halves `MoveText` allocations on the parse path for
+   comment-free corpora.
+3. `PGN::Move#piece=` — replaced the per-`Move.new` `san.match('O-O')` guard
+   (allocated a `MatchData` on every move, castling or not) with a
+   non-allocating `san.start_with?('O')`. The full hand-rolled SAN parser was
+   **deferred** per the spec's "measure first; defer if marginal" guidance:
+   it would save only ~1 `MatchData`/ply (~2% of replay, ~1.3% of parse+replay)
+   at high risk to SAN edge cases.
+4. `PGN::Position#next_player` — `(PLAYERS - [player]).first` →
+   `player == :white ? :black : :white` (removes 2 array allocations/ply).
+   `Position#move` — skips `castling - restrictions` when `restrictions` is
+   empty (returns the shared `castling` array; safe because castling arrays
+   are replaced, never mutated).
+   `PGN::MoveCalculator` — memoizes `destination_coords` (was recomputed 2–3
+   times/move, each allocating a 2-element array); frozen `ROOK_RESTRICTIONS`
+   constant replaces per-call hash literals in `castling_restrictions`; empty
+   short-circuit avoids `compact.uniq` on the common empty path.
+   `PGN::Move#pawn?` — `%w[P p].include?` → `piece == 'P' || piece == 'p'`.
+   `valid_square?` was left unchanged: its `(0..7)` are frozen range literals
+   cached by the VM, so inlining would only save method dispatch, not
+   allocations (the original rationale was unfounded).
+
+### Behavior preservation
+
+All 182 specs pass unmodified (`bundle exec rspec`). The lexer refactor keeps
+`next_token`/`tokens` and the `game_starts`-driven verbatim `Game#pgn` slicing
+byte-identical (covered by `spec/lexer_spec.rb`, `spec/parser_explicit_spec.rb`,
+and the fixture round-trip in `spec/game_spec.rb`). Racc parser is in sync with
+`pgn_parser.y` (CI racc-sync check passes). No public API or serialized-output
+changes.

data/bench/baseline_moves.pre-quickwins.txt

@@ -0,0 +1,23 @@
+Workload: immortal game, 45 plies
+
+=== 1. Replay allocations (45 plies, no parse) ===
+total_allocated objects: 2177
+total_allocated bytes:   141616
+
+=== 2. Board#dup x45 (target of flat-board COW) ===
+total_allocated objects: 136
+total_allocated bytes:   10336
+
+=== 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    83.000 i/100ms
+Calculating -------------------------------------
+     replay immortal      1.073k (± 3.2%) i/s  (931.70 μs/i) -      5.395k in   5.026523s
+
+Done. Snapshot of the working tree immediately before the quick-wins (Approach A) changes.
+Compare bench/baseline_moves.txt (after) against this file.

data/bench/baseline_moves.txt

@@ -1,12 +1,12 @@
 Workload: immortal game, 45 plies
 
 === 1. Replay allocations (45 plies, no parse) ===
-total_allocated objects: 2565
-total_allocated bytes:   155296
+total_allocated objects: 1710
+total_allocated bytes:   103760
 
 === 2. Board#dup x45 (target of flat-board COW) ===
-total_allocated objects: 91
-total_allocated bytes:   6736
+total_allocated objects: 136
+total_allocated bytes:   10336
 
 === 3. Board#at(str) x1000 (target of coord-arithmetic at) ===
 total_allocated objects: 0
@@ -15,8 +15,8 @@ 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
+     replay immortal   112.000 i/100ms
 Calculating -------------------------------------
-     replay immortal      1.669k (±46.5%) i/s  (599.18 μs/i) -      8.352k in   5.004383s
+     replay immortal      1.178k (± 4.6%) i/s  (848.64 μs/i) -      5.936k in   5.037516s
 
 Done. Compare this file against bench/baseline_moves.txt after optimizations.

data/bench/baseline_parse.pre-quickwins.txt

@@ -0,0 +1,26 @@
+Corpus: 500 copies of the immortal game
+
+=== 1. Parse-only allocations (500 games) ===
+total_allocated objects: 626037
+total_allocated bytes:   39417414
+
+=== 2. Parse + replay allocations (500 games) ===
+total_allocated objects: 1683087
+total_allocated bytes:   108184152
+
+=== 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      3.141 (± 0.0%) i/s  (318.39 ms/i) -     16.000 in   5.094185s
+
+=== 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.257 (± 0.0%) i/s     (795.32 ms/i) -      7.000 in   5.567259s
+
+Done. Snapshot of the working tree immediately before the quick-wins (Approach A) changes.
+Compare bench/baseline_parse.txt (after) against this file.

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: 1248065
-total_allocated bytes:   120370470
+total_allocated objects: 603537
+total_allocated bytes:   28257414
 
 === 2. Parse + replay allocations (500 games) ===
-total_allocated objects: 2498573
-total_allocated bytes:   195914048
+total_allocated objects: 1427586
+total_allocated bytes:   78104136
 
 === 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
+     parse 500 games      3.649 (±27.4%) i/s  (274.08 ms/i) -     19.000 in   5.207546s
 
 === 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
+parse+replay 500 games      1.399 (± 0.0%) i/s  (715.05 ms/i) -      7.000 in   5.005330s
 
 Done. Compare this file against bench/baseline_parse.txt after optimizations.