cw_card_utils 0.1.10 → 0.1.12

data/lib/cw_card_utils/synergy_probability.rb

@@ -1,31 +1,70 @@
 # frozen_string_literal: true
 
 module CwCardUtils
-  # Calculates probability of drawing specific card combinations for synergy analysis
+  # Public: Calculates probability of drawing specific card combinations.
+  # 日本語: 特定カードの組み合わせを引く確率を計算します。
   class SynergyProbability
+    # Public: Initialize with a deck and its size.
+    # 日本語: デッキとそのサイズで初期化します。
+    #
+    # @param deck [CwCardUtils::DecklistParser::Deck]
+    # @param deck_size [Integer]
+    # @return [void]
     def initialize(deck, deck_size: 60)
       @deck = deck
       @deck_size = deck_size
     end
 
     # Probability of drawing at least one of the target cards
+    # Public: Probability of drawing at least one of targets in given draws.
+    # 日本語: 指定枚数のドローで、対象のいずれか1枚以上を引く確率。
+    #
+    # How it works (EN): Uses the complement rule with hypergeometric
+    # coefficients: 1 - C(N - T, d) / C(N, d), where N is deck size,
+    # T is total copies of targets, and d is draws (clamped).
+    #
+    # 仕組み (JA): 超幾何係数の補集合を用います。N をデッキ枚数、T を
+    # 対象の総枚数、d をドロー枚数 (クランプ済み) とすると、
+    # 1 - C(N - T, d) / C(N, d) で計算します。
+    #
+    # @param target_names [Array<String>]
+    # @param draws [Integer]
+    # @return [Float] 0.0..1.0
     def prob_single(target_names, draws)
-      total_copies = count_copies(target_names)
-      1 - hypergeometric(@deck_size - total_copies, draws).to_f / hypergeometric(@deck_size, draws)
+      targets = Array(target_names).uniq
+      draws_clamped = clamp_draws(draws)
+      total_copies = count_copies(targets)
+      total = hypergeometric(@deck_size, draws_clamped).to_f
+      prob = 1 - hypergeometric(@deck_size - total_copies, draws_clamped).to_f / total
+      prob.clamp(0.0, 1.0)
     end
 
     # Probability of drawing ALL cards in the targets list (synergy pair/trio)
+    # Public: Probability of drawing all targets in given draws.
+    # 日本語: 指定枚数のドローで対象の全カードを揃える確率。
+    #
+    # How it works (EN): For 1/2/3-card combos, uses exact inclusion–
+    # exclusion with hypergeometric terms. For 4+ cards, uses a
+    # conservative approximation by summing miss-probabilities.
+    #
+    # 仕組み (JA): 1/2/3 枚コンボは超幾何項の包除原理で厳密に算出。
+    # 4 枚以上では各カードの不在確率を合算する保守的近似を用います。
+    #
+    # @param target_names [Array<String>]
+    # @param draws [Integer]
+    # @return [Float] 0.0..1.0
     def prob_combo(target_names, draws)
-      case target_names.size
+      targets = Array(target_names).uniq
+      case targets.size
       when 1
-        prob_single(target_names, draws)
+        prob_single(targets, draws)
       when 2
-        prob_two_card_combo(target_names, draws)
+        prob_two_card_combo(targets, draws)
       when 3
-        prob_three_card_combo(target_names, draws)
+        prob_three_card_combo(targets, draws)
       else
         # For >3 cards, fallback to approximation
-        approx_combo(target_names, draws)
+        approx_combo(targets, draws)
       end
     end
 
@@ -33,60 +72,70 @@ module CwCardUtils
 
     # Exact for 2-card combos
     def prob_two_card_combo(names, draws)
-      copies_a = count_copies([names[0]])
-      copies_b = count_copies([names[1]])
+      draws_clamped = clamp_draws(draws)
 
-      total = hypergeometric(@deck_size, draws).to_f
+      copies_a = copies_by_name[names[0]]
+      copies_b = copies_by_name[names[1]]
+
+      total = hypergeometric(@deck_size, draws_clamped).to_f
 
       # Probability missing A
-      miss_a = hypergeometric(@deck_size - copies_a, draws) / total
+      miss_a = hypergeometric(@deck_size - copies_a, draws_clamped) / total
       # Probability missing B
-      miss_b = hypergeometric(@deck_size - copies_b, draws) / total
+      miss_b = hypergeometric(@deck_size - copies_b, draws_clamped) / total
       # Probability missing both
-      miss_both = hypergeometric(@deck_size - (copies_a + copies_b), draws) / total
+      miss_both = hypergeometric(@deck_size - (copies_a + copies_b), draws_clamped) / total
 
       # Inclusion–exclusion
-      [1 - (miss_a + miss_b - miss_both), 0].max
+      prob = 1 - (miss_a + miss_b - miss_both)
+      prob.clamp(0.0, 1.0)
     end
 
     # Exact for 3-card combos
     def prob_three_card_combo(names, draws)
-      copies_a = count_copies([names[0]])
-      copies_b = count_copies([names[1]])
-      copies_c = count_copies([names[2]])
+      draws_clamped = clamp_draws(draws)
+
+      copies_a = copies_by_name[names[0]]
+      copies_b = copies_by_name[names[1]]
+      copies_c = copies_by_name[names[2]]
 
-      total = hypergeometric(@deck_size, draws).to_f
+      total = hypergeometric(@deck_size, draws_clamped).to_f
 
-      miss_a = hypergeometric(@deck_size - copies_a, draws) / total
-      miss_b = hypergeometric(@deck_size - copies_b, draws) / total
-      miss_c = hypergeometric(@deck_size - copies_c, draws) / total
+      miss_a = hypergeometric(@deck_size - copies_a, draws_clamped) / total
+      miss_b = hypergeometric(@deck_size - copies_b, draws_clamped) / total
+      miss_c = hypergeometric(@deck_size - copies_c, draws_clamped) / total
 
-      miss_ab = hypergeometric(@deck_size - (copies_a + copies_b), draws) / total
-      miss_ac = hypergeometric(@deck_size - (copies_a + copies_c), draws) / total
-      miss_bc = hypergeometric(@deck_size - (copies_b + copies_c), draws) / total
+      miss_ab = hypergeometric(@deck_size - (copies_a + copies_b), draws_clamped) / total
+      miss_ac = hypergeometric(@deck_size - (copies_a + copies_c), draws_clamped) / total
+      miss_bc = hypergeometric(@deck_size - (copies_b + copies_c), draws_clamped) / total
 
-      miss_abc = hypergeometric(@deck_size - (copies_a + copies_b + copies_c), draws) / total
+      miss_abc = hypergeometric(@deck_size - (copies_a + copies_b + copies_c), draws_clamped) / total
 
       # Inclusion–exclusion for 3 sets
-      [1 - (miss_a + miss_b + miss_c) +
+      prob = 1 - (miss_a + miss_b + miss_c) +
         (miss_ab + miss_ac + miss_bc) -
-        miss_abc, 0].max
+        miss_abc
+      prob.clamp(0.0, 1.0)
     end
 
-    # Approximation for >3 cards (same as old method)
+    # Approximation for >3 cards
     def approx_combo(target_names, draws)
-      prob_missing = 0.0
-      target_names.each do |name|
-        copies = count_copies([name])
-        miss_prob = hypergeometric(@deck_size - copies, draws).to_f / hypergeometric(@deck_size, draws)
-        prob_missing += miss_prob
+      draws_clamped = clamp_draws(draws)
+      total = hypergeometric(@deck_size, draws_clamped).to_f
+
+      prob_missing = target_names.sum do |name|
+        copies = copies_by_name[name]
+        hypergeometric(@deck_size - copies, draws_clamped).to_f / total
       end
-      [1 - prob_missing, 0].max
+
+      prob = 1 - prob_missing
+      prob.clamp(0.0, 1.0)
     end
 
     # Utility: count how many copies of given cards are in the deck
     def count_copies(names)
-      @deck.main.sum { |card| names.include?(card.name) ? card.count : 0 }
+      unique = names.uniq
+      @deck.main.sum { |card| unique.include?(card.name) ? card.count : 0 }
     end
 
     # Hypergeometric combination helper
@@ -95,9 +144,19 @@ module CwCardUtils
       factorial(n) / (factorial(k) * factorial(n - k))
     end
 
+    def clamp_draws(draws)
+      return 0 if draws.to_i < 0
+      [draws.to_i, @deck_size].min
+    end
+
     def factorial(n)
       return 1 if n.zero?
       (1..n).reduce(1, :*)
     end
+
+    # Only need to calculate this once for the deck passed in.
+    def copies_by_name
+      @copies_by_name ||= @deck.main.each_with_object(Hash.new(0)) { |card, h| h[card.name] += card.count }
+    end
   end
 end

data/lib/cw_card_utils/version.rb

@@ -1,5 +1,12 @@
 # frozen_string_literal: true
 
+##
+# Public: Version of the CwCardUtils gem.
+# 日本語: この CwCardUtils gem のバージョン定義です。
 module CwCardUtils
-  VERSION = "0.1.10"
+  # Public: The current version string.
+  # 日本語: 現在のバージョン文字列です。
+  #
+  # @return [String]
+  VERSION = "0.1.12"
 end

data/lib/cw_card_utils.rb

@@ -7,17 +7,37 @@ require_relative "cw_card_utils/scryfall_cmc_data"
 require_relative "cw_card_utils/synergy_probability"
 require_relative "cw_card_utils/deck_comparator"
 
+##
+# Public: Top-level namespace for Card Utils.
+# 日本語: Card Utils のトップレベル名前空間です。
 module CwCardUtils
+  ##
+  # Public: Gem-specific error base class.
+  # 日本語: このライブラリ用の基本的なエラークラスです。
   class Error < StandardError; end
 
-  # Configuration for the library
+  # Public: Configuration for the library.
+  # 日本語: ライブラリの設定を行います。
   class << self
+    # Public: Overrides the global card data source.
+    # 日本語: グローバルなカードデータソースを上書きします。
+    #
+    # @param source [CwCardUtils::CardDataSource]
     attr_writer :card_data_source
 
+    # Public: Returns the global card data source used by parsers and models.
+    # 日本語: パーサやモデルが使用するグローバルなカードデータソースを返します。
+    #
+    # @return [CwCardUtils::CardDataSource]
     def card_data_source
       @card_data_source ||= ScryfallCmcData.instance
     end
 
+    # Public: Yields the module for configuration.
+    # 日本語: 設定用にモジュール自身をブロックに渡します。
+    #
+    # @yield [CwCardUtils]
+    # @return [void]
     def configure
       yield self if block_given?
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cw_card_utils
 version: !ruby/object:Gem::Version
-  version: 0.1.10
+  version: 0.1.12
 platform: ruby
 authors:
 - Ryan Stenhouse
@@ -57,6 +57,7 @@ metadata:
   homepage_uri: https://cracklingwit.com
   source_code_uri: https://github.com/cracklingwit/card_utils
   changelog_uri: https://github.com/cracklingwit/card_utils/commits/main/
+  documentation_uri: https://card-utils.rdoc.cracklingwit.com
 rdoc_options: []
 require_paths:
 - lib