cw_card_utils 0.1.11 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 23145f32617794cf1af83523bf179d6d9260cc75251a24207ae6ea6ce0274599
-  data.tar.gz: 7cd65b1d7e93b8f9c2438df235d77c44e294d543ff1f22e8b0aa16efb5e51192
+  metadata.gz: 906b2d48d1b46bac9ddae4395dde482acda9017854a8f43a88b554421bc34da5
+  data.tar.gz: de6f89e9b88dc62552f3ad39253ba40522cfceacf78718aa301c30e71598b25e
 SHA512:
-  metadata.gz: 556bc7d3c4dc4d87b752d2923eba061b23356a6e2330f33691e34ee215d7cdd9e6148cd8c4a9082ddbcda179ffd68bef162d0bc6e11c25db3bc05b95589f83d9
-  data.tar.gz: e81abacff1c5dae3476a1ffb9e6a779105546f7a020edcc36fb463082842645a784e922d89660c2e779c4ceaa1d51dadf14b84ed4ae33d6326fe7188ab1135b7
+  metadata.gz: f4c05be5fede670c4dbaaf06a1813db002366dda8e81ff462452fe8252207f7b790ecf22e86bb93b056304f7680886cceff58a83d90ea6cd0a76791bcc8be6a3
+  data.tar.gz: f5da3ba07dc6df50857dada5a27760012d7ecdc344c7be49aafddafcae1564997f1530fab99d018cf3e552d273ba02efa62269a16dfecdecad33cbeb1f1f8d84

data/README.md

@@ -2,6 +2,39 @@
 
 A Ruby gem for analyzing Magic: The Gathering decklists and calculating various metrics.
 
+> Note: A new preferred namespace is available: `CracklingWit::CardUtils`.
+> The legacy `CwCardUtils` namespace remains for backward compatibility and will be softly deprecated.
+>
+> New usage (preferred):
+>
+> ```ruby
+> require "crackling_wit/card_utils"
+> a = CracklingWit::CardUtils::DecklistParser::Parser.new(decklist_a).parse
+> b = CracklingWit::CardUtils::DecklistParser::Parser.new(decklist_b).parse
+> cmp = CracklingWit::CardUtils::DeckComparator.new(a, b)
+> ```
+>
+> Legacy usage (still supported):
+>
+> ```ruby
+> require "cw_card_utils"
+> a = CwCardUtils::DecklistParser::Parser.new(decklist_a).parse
+> ```
+
+## Features
+
+- Parse decklists (MTGA/MTGO/Moxfield) into a rich `Deck` model
+- Compute curves: raw, normalized, and collapsed-normalized
+- Detect archetypes from tag ratios, average CMC, and color/tribe labels
+- Tag cards using lightweight text/keyword heuristics (threat, interaction, ramp, synergy, tribal)
+- Calculate synergy probabilities for single/pair/triple combos
+- Compare two decks and produce on-play/on-draw matchup insights
+
+## Requirements
+
+- Ruby 3.0+ (tested on 3.x)
+- No external services required for defaults (bundled Scryfall JSON)
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -16,30 +49,82 @@ And then execute:
 bundle install
 ```
 
+Or install directly:
+
+```bash
+gem install cw_card_utils
+```
+
+## Quickstart
+
+```ruby
+require "cw_card_utils"
+
+decklist_a = <<~DECK
+4 Lightning Bolt
+4 Monastery Swiftspear
+20 Mountain
+DECK
+
+decklist_b = <<~DECK
+4 Counterspell
+4 Memory Deluge
+4 Supreme Verdict
+24 Island
+DECK
+
+a = CwCardUtils::DecklistParser::Parser.new(decklist_a).parse
+b = CwCardUtils::DecklistParser::Parser.new(decklist_b).parse
+
+puts a.archetype                  # => e.g., "Mono-Red Aggro"
+puts a.color_identity_string      # => "Red"
+puts a.collapsed_normalized_curve # => { "0-1"=>..., "2"=>..., ... }
+
+cmp = CwCardUtils::DeckComparator.new(a, b)
+pp cmp.compare[:on_play] # => win_rate_a, favored, notes, etc.
+```
+
+New namespace quickstart:
+
+```ruby
+require "crackling_wit/card_utils"
+
+a = CracklingWit::CardUtils::DecklistParser::Parser.new(decklist_a).parse
+b = CracklingWit::CardUtils::DecklistParser::Parser.new(decklist_b).parse
+
+cmp = CracklingWit::CardUtils::DeckComparator.new(a, b)
+pp cmp.compare[:on_play]
+```
+
 ## Configuration
 
 You can configure the card data source used by the library:
 
 ```ruby
-# In a Rails initializer (config/initializers/cw_card_utils.rb)
+# Legacy namespace
 CwCardUtils.configure do |config|
   config.card_data_source = MyCustomDataSource.new
 end
 
+# New namespace (delegates to the same config under the hood)
+CracklingWit::CardUtils.configure do |config|
+  config.card_data_source = MyCustomDataSource.new
+end
+
 # Or set it directly
 CwCardUtils.card_data_source = MyCustomDataSource.new
+CracklingWit::CardUtils.card_data_source = MyCustomDataSource.new
 ```
 
 The default data source is `CwCardUtils::ScryfallCmcData.instance`, which loads card data from a local JSON file.
 
 ## Usage
 
-### Basic Deck Parsing
+### Deck Parsing and Formats
 
 ```ruby
 require 'cw_card_utils'
 
-# Parse a decklist
 decklist = <<~DECK
   4 Lightning Bolt
   4 Mountain
@@ -48,12 +133,57 @@ DECK
 
 deck = CwCardUtils::DecklistParser::Parser.new(decklist).parse
 
-# Access deck information
+# Common accessors
 puts deck.mainboard_size  # => 10
 puts deck.color_identity  # => ["R"]
-puts deck.archetype      # => :aggro
+puts deck.archetype       # => "Mono-Red Aggro" (string label)
+puts deck.format          # => :standard, :modern, :commander (heuristic)
 ```
 
+Parses common formats (MTGA, MTGO, Moxfield). Sideboard sections are detected (e.g., lines starting with "Sideboard").
+
+### Curves and Summaries
+
+```ruby
+deck.curve                    # => { 0=>2, 1=>8, 2=>6, 3=>4, ... }
+deck.normalized_curve         # => { 1=>0.22, 2=>0.18, ... }
+deck.collapsed_curve          # => { "0-1"=>10, "2"=>6, "3"=>4, ... }
+deck.collapsed_normalized_curve
+```
+
+### Archetype Detection and Tags
+
+```ruby
+deck.archetype            # => "Izzet Control", "Selesnya Midrange", etc.
+deck.main.first.tags      # => [:interaction, :draw, :etb, ...]
+deck.color_identity_string# => "Azorius"
+```
+
+### Synergy Probabilities
+
+```ruby
+sp = CwCardUtils::SynergyProbability.new(deck, deck_size: deck.size)
+sp.prob_single(["Lightning Bolt"], 7)    # => Float 0..1
+sp.prob_combo(["Card A", "Card B"], 10)  # => Float 0..1
+```
+
+### Deck Comparison (Matchup)
+
+```ruby
+cmp = CwCardUtils::DeckComparator.new(deck_a, deck_b)
+pp cmp.compare # => { on_play: {...}, on_draw: {...} }
+```
+
+### Generating API Docs (RDoc)
+
+Bilingual (EN/JA) RDoc is embedded in the source. Generate HTML docs:
+
+```bash
+rdoc -f darkfish -o doc lib README.md --title "Crackling Wit: Card Utilities" --exclude '\.json$'
+```
+
+Then open `doc/index.html`.
+
 ### Custom Data Sources
 
 You can implement your own card data source by inheriting from `CwCardUtils::CardDataSource`:
@@ -76,4 +206,19 @@ After checking out the repo, run `bin/setup` to install dependencies. Then, run
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/cracklingwit/cw_card_utils.
+Bug reports and pull requests are welcome on GitHub at https://github.com/cracklingwit/cw_card_utils.
+
+## Data Sources
+
+The default data source for this gem is an extraction from the wonderful [Scryfall Bulk Data][1] set. It is intended to be used only to test the functionality of the gem and serve as a fallback source of data.
+
+You should use your own source, preferably backed by a database that conforms to our `card_data_source` API for your own production projects.
+
+A huge, huge thank you to the wonderful folks at [Scryfall][2] for the hard work they put into keeping their data accurate, up to date, and free for the community to use. We are not endorsed or supported by [Scryfall][2] in any way.
+
+## Fan Content Policy
+
+Crackling Wit's Card Utils gem is unofficial Fan Content permitted under the Fan Content Policy. It is not approved/endorsed by Wizards. Portions of the materials used are property of Wizards of the Coast. © Wizards of the Coast LLC.
+
+[1]: https://scryfall.com/docs/api/bulk-data
+[2]: https://scryfall.com