card_dealer 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0c3f3a33b1bc150361102599843b3cf9e7e1eb3d2b799b4116411f3445a00cf2
-  data.tar.gz: 6f32d0a5b10e0703424304aba1e8e3172a50b56066c49505c08f1752ca0c5bbe
+  metadata.gz: 740499d4aa92d740445805a9e78e4c2ff72e0fdd79a44c1abd34d25aeed17b1d
+  data.tar.gz: 482ee0d77fcc5f171b220f601c99ce3beebfab94e60f989d2cf395ecd836178c
 SHA512:
-  metadata.gz: 07f8695bf89b50776b4dbd412ed774679ae1d7cd9dccf78581148bd200b7afd30e97fdbe8eb392b640569faf3945dc738a67fd34d8501c6028216fb1d942a73f
-  data.tar.gz: b6936af01081753ab4f0e46174ddab834c2c84091923eb73794660fa2f6ea30c04c495a72121f8ffcc2ac998fb6754927b305d50bd4eabfaf3ae815d988a4c47
+  metadata.gz: 67fe4b4516e2c4dd8857270330c7300a65abc6d038f9a0b8634cd63a003d6c96ccb4243ec9dbe86c5348dab9e783d9f2110d8c87443418a9bd11e5dc0aca5f29
+  data.tar.gz: 408fcce45791e37cc982665cf3432b104a21f15b937ecefed14c8dc360b9ed22ce695f4051a4e5a3a425d15eb58e2ff93e42effbb4cde84ba21e5f7abccf8f92

data/.rspec

@@ -1,3 +1,2 @@
---format documentation
 --color
 --require spec_helper

data/CHANGELOG.md

@@ -16,6 +16,12 @@ removed.
 
 ## [Unreleased]
 
+## [0.3.1] - 2026-11-06
+
+### Fixed
+
+- Binary decoding rejects payload lengths that do not match the declared card count with `CardDealer::BinaryDeck::InvalidEncodingError`, including truncated decks.
+
 ## [0.3.0] - 2026-09-07
 
 ### Changed
@@ -71,7 +77,8 @@ Initial release!
 - Ability to shuffle a deck
 - Ability to reset a deck
 
-[unreleased]: https://github.com/svyatov/card_dealer/compare/v0.3.0...HEAD
+[unreleased]: https://github.com/svyatov/card_dealer/compare/v0.3.1...HEAD
+[0.3.1]: https://github.com/svyatov/card_dealer/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/svyatov/card_dealer/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/svyatov/card_dealer/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/svyatov/card_dealer/releases/tag/v0.1.0

data/CLAUDE.md

@@ -0,0 +1,57 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+CardDealer is a Ruby gem for creating, shuffling, and dealing decks of playing cards. It supports standard 52-card and 36-card decks, custom deck configurations, and binary serialization for storage.
+
+## Commands
+
+```bash
+# Install dependencies
+bin/setup
+
+# Run all checks (default task: steep + rubocop + rspec)
+bundle exec rake
+
+# Run tests only
+bundle exec rake spec
+
+# Run a single test file
+bundle exec rspec spec/card_dealer/card_spec.rb
+
+# Run a specific test by line number
+bundle exec rspec spec/card_dealer/deck_spec.rb:42
+
+# Run linter
+bundle exec rake rubocop
+
+# Run type checker
+bundle exec rake steep
+
+# Interactive console
+bin/console
+```
+
+## Architecture
+
+The gem has four main classes under the `CardDealer` module:
+
+- **Card** (`lib/card_dealer/card.rb`) - Represents a single playing card with rank (2-A, where T=10) and suit (c/d/h/s). Cards are comparable and can be used as hash keys.
+
+- **Deck** (`lib/card_dealer/deck.rb`) - A collection of cards supporting shuffle (Fisher-Yates with optional seed), deal, and burn operations. Tracks burned cards separately.
+
+- **BuildDeck** (`lib/card_dealer/build_deck.rb`) - Factory class with class methods for creating decks:
+  - `standard52` / `standard36` for common configurations
+  - `custom` for specifying decks count, cards per suit, ranks (`:highest`, `:lowest`, or array), and suits
+
+- **BinaryDeck** (`lib/card_dealer/binary_deck.rb`) - Encodes/decodes decks to/from binary strings using 6-bit card representations. Supports decks up to 4 billion cards with three template sizes (8/16/32-bit headers).
+
+## Type Definitions
+
+RBS type signatures are in `sig/`. The project uses Steep for type checking with lenient diagnostics configured in `Steepfile`.
+
+## Requirements
+
+- Ruby >= 3.3.0

data/Gemfile

@@ -10,7 +10,7 @@ gem "rake", "~> 13.4"
 gem "rspec", "~> 3.13"
 gem "simplecov", require: false
 
-gem "rubocop", "~> 1.90"
+gem "rubocop", "~> 1.92"
 gem "rubocop-rake", "~> 0.7"
 gem "rubocop-rspec", "~> 3.10"
 

data/Gemfile.lock

@@ -1,28 +1,28 @@
 PATH
   remote: .
   specs:
-    card_dealer (0.3.0)
+    card_dealer (0.3.1)
 
 GEM
   remote: https://rubygems.org/
   specs:
     ast (2.4.3)
     concurrent-ruby (1.3.8)
-    csv (3.3.6)
+    csv (3.3.7)
     diff-lcs (1.6.2)
     ffi (1.17.4-arm64-darwin)
     ffi (1.17.4-x86_64-linux-gnu)
-    fileutils (1.8.0)
-    json (2.21.2)
+    fileutils (1.8.1)
+    json (3.1.0)
     language_server-protocol (3.17.0.6)
     lint_roller (1.1.0)
-    listen (3.10.0)
+    listen (3.10.1)
       logger
       rb-fsevent (~> 0.10, >= 0.10.3)
       rb-inotify (~> 0.9, >= 0.9.10)
     logger (1.7.0)
-    parallel (2.1.0)
-    parser (3.3.12.0)
+    parallel (2.3.0)
+    parser (3.3.13.0)
       ast (~> 2.4.1)
       racc
     prism (1.9.0)
@@ -36,7 +36,7 @@ GEM
       logger
       prism (>= 1.6.0)
       tsort
-    regexp_parser (2.12.0)
+    regexp_parser (2.13.1)
     rspec (3.13.2)
       rspec-core (~> 3.13.0)
       rspec-expectations (~> 3.13.0)
@@ -50,14 +50,14 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
     rspec-support (3.13.7)
-    rubocop (1.90.0)
+    rubocop (1.92.2)
       json (>= 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
       parallel (>= 1.10)
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
-      regexp_parser (>= 2.9.3, < 3.0)
+      regexp_parser (>= 2.11.3, < 3.0)
       rubocop-ast (>= 1.49.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
@@ -73,7 +73,7 @@ GEM
       rubocop (~> 1.86, >= 1.86.2)
     ruby-progressbar (1.13.0)
     securerandom (0.4.1)
-    simplecov (1.1.1)
+    simplecov (1.3.2)
     steep (2.1.0)
       concurrent-ruby (>= 1.1.10)
       csv (>= 3.0.9)
@@ -94,26 +94,27 @@ GEM
     terminal-table (4.0.0)
       unicode-display_width (>= 1.1.1, < 4)
     tsort (0.2.0)
-    unicode-display_width (3.2.0)
-      unicode-emoji (~> 4.1)
-    unicode-emoji (4.2.0)
-    uri (1.1.1)
+    unicode-display_width (3.3.0)
+      unicode-emoji (~> 4.3)
+    unicode-emoji (4.3.0)
+    uri (1.1.2)
 
 PLATFORMS
   arm64-darwin-22
   arm64-darwin-23
   arm64-darwin-24
+  arm64-darwin-25
   x86_64-linux
 
 DEPENDENCIES
   card_dealer!
   rake (~> 13.4)
   rspec (~> 3.13)
-  rubocop (~> 1.90)
+  rubocop (~> 1.92)
   rubocop-rake (~> 0.7)
   rubocop-rspec (~> 3.10)
   simplecov
   steep
 
 BUNDLED WITH
-  4.0.17
+  4.0.23

data/README.md

@@ -119,6 +119,8 @@ deck = CardDealer::Deck.from_binary(encoded)
 deck.to_a # => ["As", "Td"]
 ```
 
+If the payload length does not match the declared card count, decoding raises `CardDealer::BinaryDeck::InvalidEncodingError`.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Run `bundle exec rake` to run the type checker, the linter, and the tests. Run `bin/console` for an interactive prompt.

data/docs/ideation/2026-11-06-next-feature.md

@@ -0,0 +1,131 @@
+# Next feature for CardDealer
+
+## Subject
+
+Identify the next obvious missing feature in this Ruby gem. Rank one feature, as requested.
+
+The best feature candidate is atomic round-robin dealing to multiple hands. There is no evidence that any feature is mandatory.
+
+Repair the confirmed binary-decoder truncation defect before adding features. The validation section records its reproduction.
+
+Follow-up: commit `4376fae` implements the length check and documents `CardDealer::BinaryDeck::InvalidEncodingError`. The findings below describe the checkout examined before that repair.
+
+### Grounding
+
+- README.md:3 defines the purpose: "CardDealer builds, shuffles, and deals decks of playing cards for Ruby card game applications."
+- `lib/card_dealer/deck.rb:56-58` implements one contiguous deal with optional burns. Multi-hand distribution requires caller loops.
+- `spec/card_dealer/deck_spec.rb:97-102` intentionally permits empty results. Exact dealing must use an explicit new contract.
+- `lib/card_dealer/binary_deck.rb:68-98` stores remaining card order. It omits the seed and burned cards.
+- `CHANGELOG.md:54-56` records removal of `Deck#reset` and recommends rebuilding with `BuildDeck`.
+- Recent commits `83513ab`, `bb3d2ce`, and `afa9a3d` concern dependency maintenance. They supply no feature-demand evidence.
+- GitHub returned no open issues for `svyatov/card_dealer` on 2026-11-06. No glossary, ADRs, or tracker guide were found.
+
+### Method
+
+One read-only explorer supplied grounding. Four generation tasks covered all six ideation frames. Their results merged into 18 distinct candidates and three combinations.
+
+An independent verifier checked all 21 candidates against the source and arguments. No verifier verdict was overruled.
+
+Utility is inferred from the API. Source evidence establishes capability gaps, not consumer demand. Sizes include implementation, signatures, documentation, and meaningful tests.
+
+## Ranked ideas
+
+### 1. Atomic round-robin dealing to multiple hands
+
+Distribute one card to each hand per round, returning ordinary arrays of cards. Check the entire request before removing cards.
+
+If capacity is insufficient, raise a documented error and leave the deck unchanged. Preserve the permissive behavior of `deal`.
+
+**Basis, direct:** `lib/card_dealer/deck.rb:56` defines `def deal(num = 1, burn: 0)`. Line 57 executes `@burned_cards += cards.shift(burn) if burn.positive?`. Line 58 executes `cards.shift(num)`. This returns a single contiguous group and performs no capacity preflight. `spec/card_dealer/deck_spec.rb:97-102` explicitly tests empty-array results for empty decks.
+
+**Why it matters:** Games that distribute alternating cards need a caller loop. Games that require complete hands also need a capacity check.
+
+Combining those operations gives one bounded dealing capability. It fits the stated purpose without introducing game rules, players, or hand classes.
+
+**Size:** M. The algorithm is small, but public error semantics, signatures, compatibility, and examples need care.
+
+**Proposed shape, subject to design:**
+
+```ruby
+hands = deck.deal_hands(players: 3, cards_each: 2)
+# From an unshuffled standard deck:
+# [[2c, 5c], [3c, 6c], [4c, 7c]] as Card objects
+```
+
+The smallest scope has positive player counts, nonnegative card counts, capacity validation, and no burns. Names and zero-count behavior require design review.
+
+Atomic means capacity validation before mutation. It does not imply thread safety or protection against external mutation through `cards`.
+
+**Main objection:** A short Ruby loop already performs distribution. The feature earns its maintenance cost only if consumers need the shared ordering and failure contract.
+
+**Take it further**
+
+```text
+$grill-with-docs Atomic round-robin dealing to multiple hands in CardDealer.
+
+Basis, direct: lib/card_dealer/deck.rb:56 defines `def deal(num = 1, burn: 0)`. Line 57 executes `@burned_cards += cards.shift(burn) if burn.positive?`. Line 58 executes `cards.shift(num)`. This returns a single contiguous group and performs no capacity preflight. spec/card_dealer/deck_spec.rb:97-102 explicitly tests empty-array results for empty decks.
+
+Why it matters: Games that distribute alternating cards need a caller loop. Games that require complete hands also need a capacity check. Combining those operations gives one bounded dealing capability. It fits the stated purpose without introducing game rules, players, or hand classes.
+
+Consider a separate API such as deal_hands(players:, cards_each:), returning arrays of Card objects. Distribute one card per player per round. Validate the complete request before mutation. Insufficient capacity must leave the deck unchanged. Preserve existing deal behavior. Start without burns.
+
+Challenge whether a documented loop is sufficient before accepting a permanent API. There is no open-issue demand evidence. Resolve names, zero counts, error types, size limits, and compatibility before implementation.
+```
+
+## Cut
+
+These cuts rank one next feature. They do not declare every alternative useless. IDs refer to the merged candidate list.
+
+| ID | Idea | Basis | Reason |
+| --- | --- | --- | --- |
+| I1 | Round-robin dealing alone | direct: `deck.rb:58`, `cards.shift(num)`, returns one group. | Duplicate of the stronger ranked combination, I20. |
+| I2 | Exact dealing alone | direct: `deck.rb:57-58` burns before dealing, without preflight. | Combined into I20; a standalone strict API remains a separate design choice. |
+| I3 | Peek | direct: `deck.rb:12`, `attr_reader :cards`, already exposes inspection. | Cost over value: `deck.cards.first(n)` already expresses the operation. |
+| I4 | Enumerable iteration | direct: `deck.rb:93`, `cards.map(&:to_s)`, defines string-valued `to_a`. | Cost over value: collection methods exist through `cards`; iteration would need a careful `to_a` contract. |
+| I5 | Full state snapshots | direct: `binary_deck.rb:70-71` encodes cards and size; `:98`, `Deck.new cards`, reconstructs fresh state. | Cost over value: no demonstrated consumer needs seed and burned cards restored. |
+| I6 | Independent deck copies | direct: `deck.rb:23`, `@cards = cards`; `:35` and `:58` mutate the collection. | Cost over value for the next feature: branching demand is unproven and card mutability needs a defined policy. |
+| I7 | Exclude known cards by multiplicity | direct: `build_deck.rb:112-115` repeats decks; `card.rb:91` compares rank and suit values. | Cost over value: useful for simulations, but the scenario is not evidenced. |
+| I8 | Validated binary decoding | direct: `binary_deck.rb:94-95` uses `scan(/.{6}/).take(deck_size)` and map `fetch`; a truncated payload silently decoded one of two declared cards. | Classify as a confirmed repair, not a speculative feature. Prioritize the repair before the ranked feature. |
+| I9 | Ordered import from card notation | direct: `README.md:103` constructs individual cards inside `Deck.new`. | Cost over value: mapping card strings through `Card.new` is already small. |
+| I10 | Generic arbitrary-card decks | reasoned: dealing requires ordered removal, not ranks or suits; separating those concerns enables more games. | Cost over value: expands the domain and conflicts with assumptions in card encoding. |
+| I11 | Caller-supplied random generator | direct: `deck.rb:35`, `Random.new(@seed.to_i)`, constructs the generator internally. | Cost over value: coordinating random streams is unproven demand and complicates replay semantics. |
+| I12 | Replayable operation transcript | direct: `deck.rb:33-35` records a seed; `:56-58` does not log deal operations. | Cost over value: operation history adds persistent session responsibilities. |
+| I13 | Conservation checks | reasoned: comparing initial multiplicities with remaining, burned, and supplied dealt cards detects missing or extra values. | Cost over value: the caller must supply dealt inventory; equal physical copies remain indistinguishable. |
+| I14 | Scenario builder | reasoned: subtracting known cards from the starting multiset reconstructs a remaining population, with multiplicity preserved. | Duplicate of I7 plus existing shuffle composition. |
+| I15 | Streaming binary encoding | direct: `binary_deck.rb:70` builds a complete mapped binary-text string with `join`. | Cost over value: no measured memory or throughput problem justifies the added interface. |
+| I16 | Batch independent simulations | reasoned: each independent trial requires a fresh population; a helper can enforce reconstruction and seed handling. | Outside the focus: adds a simulation workflow above the deck primitives. |
+| I17 | Jokers | reasoned: a distinct joker needs an identity outside ordinary rank/suit pairs; built-in support enables joker games. | Cost over value: no demand evidence justifies changes to Card and binary-format compatibility. |
+| I18 | Documentation recipe only | reasoned: a recipe can teach composition without adding public compatibility obligations. | Outside the requested missing-feature result; retain as the main alternative during design. |
+| I19 | Safe inspection, peek plus iteration | direct: `deck.rb:12` exposes mutable cards; `:93` converts them to strings. | Duplicate of I3 and I4; a combined inspection interface adds scope without stronger demand. |
+| I21 | Reproducible simulation branches | direct: I5, I6, and I7 establish snapshot, copying, and exclusion gaps. | Cost over value: combining three speculative needs creates a larger simulation feature set. |
+
+Paths abbreviated in this table refer to `lib/card_dealer/`, except `README.md`.
+
+## Validation
+
+Read-only Ruby checks confirmed contiguous repeated deals and round-robin distribution using a caller loop.
+
+Three two-card contiguous deals produced `[["2c", "3c"], ["4c", "5c"], ["6c", "7c"]]`.
+
+The equivalent round-robin loop produced `[["2c", "5c"], ["3c", "6c"], ["4c", "7c"]]` and left 46 cards.
+
+A one-card deck given `deal(5, burn: 1)` returned `[]`, left zero remaining cards, and recorded the card as burned.
+
+These checks validate the observed primitives. The proposed API has not been implemented.
+
+### Confirmed maintenance priority
+
+The independent verifier found that a truncated payload can decode successfully with fewer cards than its header declares. A separate local reproduction confirmed it:
+
+```ruby
+payload = [2, 0].pack("CC")
+CardDealer::Deck.from_binary(payload).to_a # => ["2c"]
+```
+
+Location: `lib/card_dealer/binary_deck.rb:93-98`. The header declares two cards, but the returned deck contains one.
+
+Cause: scanning produces available six-bit groups, and `take(deck_size)` accepts fewer groups without validating the declared count.
+
+Proposed repair: reject incomplete payloads before returning a deck. Define a documented format error and preserve valid binary encodings.
+
+The repair is implemented in `4376fae`. Broader malformed-input cases require a separate bounded investigation.

data/lib/card_dealer/binary_deck.rb

@@ -12,6 +12,7 @@ module CardDealer
   #
   class BinaryDeck
     class DeckTooLargeError < Error; end
+    class InvalidEncodingError < Error; end
 
     SUIT_MAP = Card::SUIT_MAP.transform_values { |value| value * 13 }
     RANK_MAP = Card::RANK_MAP
@@ -83,6 +84,8 @@ module CardDealer
       #
       # @return [Deck] The decoded deck of cards.
       #
+      # @raise [InvalidEncodingError] If the payload length does not match the declared card count.
+      #
       # @example
       #   encoded_deck = "\x02\xCDP" # (binary string)
       #   decoded_deck = CardDealer::BinaryDeck.decode(encoded_deck)
@@ -91,6 +94,10 @@ module CardDealer
       def decode(encoded_deck)
         template = decoding_template_for encoded_deck.bytesize
         deck_size, binary_numbers = encoded_deck.unpack(template)
+        if deck_size.nil? || binary_numbers.size != (((deck_size * 6) + 7) / 8) * 8
+          raise InvalidEncodingError, "Encoded deck length does not match its card count"
+        end
+
         cards = binary_numbers.scan(/.{6}/).take(deck_size).map do |binary_number|
           REVERSE_CARD_BINARY_NUMBER_MAP.fetch(binary_number)
         end

data/lib/card_dealer/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module CardDealer
-  VERSION = "0.3.0"
+  VERSION = "0.3.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: card_dealer
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Leonid Svyatov
@@ -23,6 +23,7 @@ files:
 - ".rspec"
 - ".rubocop.yml"
 - CHANGELOG.md
+- CLAUDE.md
 - CODE_OF_CONDUCT.md
 - CONTRIBUTING.md
 - Gemfile
@@ -33,6 +34,7 @@ files:
 - SECURITY.md
 - Steepfile
 - card_dealer.gemspec
+- docs/ideation/2026-11-06-next-feature.md
 - lib/card_dealer.rb
 - lib/card_dealer/binary_deck.rb
 - lib/card_dealer/build_deck.rb