cw_card_utils 0.1.11 → 0.1.12

data/lib/cw_card_utils/decklist_parser/deck.rb

@@ -2,12 +2,18 @@
 
 module CwCardUtils
   module DecklistParser
-    # A Deck is a collection of cards.
+    # Public: A deck is a collection of cards and utilities around it.
+    # 日本語: デッキはカードの集合であり、各種ユーティリティを提供します。
     class Deck
       IGNORED_TRIBAL_TYPES = %w[
         human wizard soldier scout shaman warrior cleric rogue advisor knight druid
       ].freeze
 
+      # Public: Initialize an empty deck with a data source.
+      # 日本語: データソースを指定して空のデッキを初期化します。
+      #
+      # @param cmc_data_source [CwCardUtils::CardDataSource]
+      # @return [void]
       def initialize(cmc_data_source)
         @main = []
         @sideboard = []
@@ -17,6 +23,10 @@ module CwCardUtils
         @cmc_data_source = cmc_data_source
       end
 
+      # Public: Serialize as a Hash suitable for JSON.
+      # 日本語: JSON化に適したHashへシリアライズします。
+      #
+      # @return [Hash]
       def to_h
         {
           mainboard: main.map(&:to_h),
@@ -25,26 +35,61 @@ module CwCardUtils
         }
       end
 
+      # Public: Unique color identity across mainboard.
+      # 日本語: メインボードの色アイデンティティ集合。
+      #
+      # @return [Array<String>]
       def color_identity
         @color_identity ||= main.map(&:color_identity).flatten.uniq
       end
 
+      # Public: Human readable color label.
+      # 日本語: 人間が読みやすい色表記。
+      #
+      # @return [String]
       def color_identity_string
         @color_identity_string ||= CwCardUtils::DecklistParser::ColorIdentityResolver.resolve(color_identity)
       end
 
+      # Public: JSON representation of the deck.
+      # 日本語: デッキのJSON表現。
+      #
+      # @return [String]
       def to_json(*_args)
         to_h.to_json
       end
 
+      # Public: Mainboard cards with tags applied.
+      # 日本語: タグ適用済みのメインボードカード一覧。
+      #
+      # How it works (EN): Lazily computes tags for each card via
+      # `CardTagger` the first time access occurs, then returns the
+      # mutated card objects for downstream consumers.
+      #
+      # 仕組み (JA): 初回アクセス時に `CardTagger` で各カードのタグを
+      # 遅延計算し、以降はタグ付け済みカードを返します。
+      #
+      # @return [Array<CwCardUtils::DecklistParser::Card>]
       def main
         tag_cards(@main)
       end
 
+      # Public: Sideboard cards with tags applied.
+      # 日本語: タグ適用済みのサイドボードカード一覧。
+      #
+      # How it works (EN): Same lazy-tagging behavior as `main`, but for
+      # sideboard entries.
+      #
+      # 仕組み (JA): `main` と同様に遅延タグ付けを行いますが、対象は
+      # サイドボードです。
+      #
+      # @return [Array<CwCardUtils::DecklistParser::Card>]
       def sideboard
         tag_cards(@sideboard)
       end
 
+      # Internal: Apply tags to cards lazily.
+      # 日本語: 遅延的にカードへタグを適用します。
       def tag_cards(cards)
         cards.map do |c|
           c.tags = CwCardUtils::DecklistParser::CardTagger.new(c, self).tags
@@ -52,44 +97,117 @@ module CwCardUtils
         end
       end
 
+      # Public: Detected archetype label.
+      # 日本語: 検出されたアーキタイプのラベル。
+      #
+      # Intent (EN): Summarize the deck’s strategic identity using
+      # aggregated tag ratios/counts and average CMC.
+      #
+      # 意図 (JA): タグの比率/件数と平均 CMC を用いて、デッキの戦略的
+      # アイデンティティを要約します。
+      #
+      # @return [String]
       def archetype
         @archetype ||= CwCardUtils::DecklistParser::ArchetypeDetector.new(self).detect
       end
 
+      # Public: Human-friendly deck summary string.
+      # 日本語: 人が読みやすいデッキ概要文字列。
+      #
+      # @return [String]
       def inspect
         "<Deck: main: #{mainboard_size} sideboard: #{sideboard_size} lands: #{lands_count} x_to_cast: #{x_to_cast_count} cards: #{cards_count}>"
       end
 
+      # Public: Collapsed curve counts.
+      # 日本語: まとめられたカーブのカウント。
+      #
+      # Intent (EN): Provide a coarse view of the deck’s curve using
+      # canonical buckets for quick comparison.
+      #
+      # 意図 (JA): 代表的なバケットでカーブを粗く表し、比較を容易に
+      # します。
+      #
+      # @return [Hash{String=>Integer}]
       def collapsed_curve
         @collapsed_curve ||= CurveCalculator.new(self).collapsed_curve
       end
 
+      # Public: Raw curve counts.
+      # 日本語: 素のカーブカウント。
+      #
+      # Intent (EN): Exact histogram of non-land CMC ceilings used by
+      # calculators and visualizations.
+      #
+      # 意図 (JA): 計算や可視化で用いる、土地以外の CMC 切り上げの
+      # ヒストグラムです。
+      #
+      # @return [Hash{Integer=>Integer}]
       def curve
         @curve ||= CurveCalculator.new(self).curve
       end
 
+      # Public: Normalized curve fractions.
+      # 日本語: 正規化されたカーブ比率。
+      #
+      # Intent (EN): Convert raw counts into proportions of non-land
+      # cards to compare decks of different sizes.
+      #
+      # 意図 (JA): デッキサイズが異なる場合でも比較できるよう、土地以外
+      # の枚数で割った比率に変換します。
+      #
+      # @return [Hash{Integer=>Float}]
       def normalized_curve
         @normalized_curve ||= CurveCalculator.new(self).normalized_curve
       end
 
+      # Public: Collapsed normalized curve.
+      # 日本語: まとめられかつ正規化されたカーブ。
+      #
+      # Intent (EN): Normalize the collapsed buckets for concise and
+      # comparable summaries.
+      #
+      # 意図 (JA): まとめたバケットを正規化し、簡潔かつ比較しやすい
+      # 要約を提供します。
+      #
+      # @return [Hash{String=>Float}]
       def collapsed_normalized_curve
         @collapsed_normalized_curve ||= CurveCalculator.new(self).collapsed_normalized_curve
       end
 
+      # Public: True when both main and sideboard are empty.
+      # 日本語: メイン・サイドの両方が空であれば true。
+      #
+      # @return [Boolean]
       def empty?
         @main.empty? && @sideboard.empty?
       end
 
+      # Public: True when deck has any cards.
+      # 日本語: 1枚でもカードがあれば true。
+      #
+      # @return [Boolean]
       def any?
         !empty?
       end
 
+      # Public: Enumerate mainboard cards.
+      # 日本語: メインボードのカードを列挙します。
+      #
+      # @yield [CwCardUtils::DecklistParser::Card] カードをブロックに渡します
+      # @return [void]
       def each(&block)
         @main.each do |c|
           block.call(c)
         end
       end
 
+      # Public: Add a card hash to mainboard or sideboard.
+      # 日本語: カードをメイン/サイドに追加します。
+      #
+      # @param c [Hash] { name:, count: }
+      # @param target [Symbol] :mainboard or :sideboard
+      # @return [void]
       def add(c, target = :mainboard)
         reset_counters
         card = Card.new(c[:name], c[:count], @cmc_data_source)
@@ -108,6 +226,8 @@ module CwCardUtils
         end
       end
 
+      # Internal: Invalidate derived counters.
+      # 日本語: 派生カウンタを無効化します。
       def reset_counters
         @mainboard_size = nil
         @sideboard_size = nil
@@ -116,10 +236,26 @@ module CwCardUtils
         @cards_count = nil
       end
 
+      # Public: Detected format (:commander, :standard, :modern)。
+      # 日本語: 判定されたフォーマット (:commander, :standard, :modern)。
+      #
+      # @return [Symbol]
       def format
         @format ||= detect_format_for_deck
       end
 
+      # Public: Detect the format from deck size and singleton rules.
+      # 日本語: デッキサイズとシングルトン規則からフォーマットを判定します。
+      #
+      # How it works (EN): Uses size thresholds (>=100 => Commander),
+      # then checks for singleton behavior ignoring basic lands to
+      # disambiguate Commander-like 60+ lists from Standard.
+      #
+      # 仕組み (JA): サイズ閾値 (>=100 は Commander) を用い、基本土地を
+      # 無視したシングルトン性を確認して、Standard と似た 60+ の
+      # Commander らしさを判別します。
+      #
+      # @return [Symbol]
       def detect_format_for_deck
         if mainboard_size >= 100
           :commander
@@ -135,6 +271,8 @@ module CwCardUtils
         end
       end
 
+      # Internal: Whether the deck is singleton ignoring basic lands.
+      # 日本語: 基本土地を無視してシングルトンかどうか。
       def is_singleton_deck?
         # Count non-basic land cards and check for duplicates
         non_basic_lands = @main.reject { |card| is_basic_land?(card) }
@@ -149,44 +287,82 @@ module CwCardUtils
         card_counts.values.all? { |count| count == 1 }
       end
 
+      # Internal: Whether a card is a basic land.
+      # 日本語: 基本土地であるかどうか。
       def is_basic_land?(card)
         basic_land_names = %w[Plains Island Swamp Mountain Forest Wastes]
         basic_land_names.include?(card.name)
       end
 
+      # Public: Total mainboard card count.
+      # 日本語: メインボードの総枚数。
+      #
+      # @return [Integer]
       def mainboard_size
         @mainboard_size ||= main.sum { |card| card.count }
       end
 
+      # Public: Total sideboard card count.
+      # 日本語: サイドボードの総枚数。
+      #
+      # @return [Integer]
       def sideboard_size
         @sideboard_size ||= sideboard.sum { |card| card.count }
       end
 
+      # Public: Land count.
+      # 日本語: 土地の枚数。
+      #
+      # @return [Integer]
       def lands_count
         @lands.sum { |card| card.count }
       end
 
+      # Public: X-to-cast count.
+      # 日本語: Xコストのカード枚数。
+      #
+      # @return [Integer]
       def x_to_cast_count
         @x_to_cast.sum { |card| card.count }
       end
 
+      # Public: Total main+sideboard count.
+      # 日本語: メイン+サイドの合計枚数。
+      #
+      # @return [Integer]
       def cards_count
         mainboard_size + sideboard_size
       end
 
+      # Public: Total non-land count.
+      # 日本語: 土地以外の総枚数。
+      #
+      # @return [Integer]
       def count_without_lands
         cards_count - lands_count
       end
 
+      # Public: Deck size including sideboard.
+      # 日本語: サイドボードを含むデッキサイズ。
+      #
+      # @return [Integer]
       def size
         cards_count
       end
 
+      # Public: Dominant tribe symbol or nil.
+      # 日本語: 優勢な部族(トライブ)のシンボル、もしくは nil。
+      #
+      # @return [Symbol, nil]
       def tribe
         return @tribe if @tribe
         @tribe = detect_tribe_for_deck
       end
 
+      # Public: Detect dominant creature subtype if present.
+      # 日本語: 優勢なクリーチャー・サブタイプがあれば検出します。
+      #
+      # @return [Symbol, nil]
       def detect_tribe_for_deck
         subtype_counts = Hash.new(0)
         total_creatures = 0

data/lib/cw_card_utils/decklist_parser/parser.rb

@@ -3,19 +3,45 @@
 module CwCardUtils
   module DecklistParser
     # Parses a decklist and returns a Deck object.
+    # Public: Parses a decklist string/IO into a Deck.
+    # 日本語: デッキリスト文字列/IOを解析して Deck を生成します。
     class Parser
       attr_reader :deck
 
+      # Public: Create a new parser.
+      # 日本語: 新しいパーサを作成します。
+      #
+      # @param decklist [String, IO]
+      # @param cmc_data_source [CwCardUtils::CardDataSource]
+      # @return [void]
       def initialize(decklist, cmc_data_source = nil)
         @decklist = decklist.is_a?(IO) ? decklist.read : decklist
         @deck = Deck.new(cmc_data_source || CwCardUtils.card_data_source)
       end
 
+      # Public: Human-readable summary.
+      # 日本語: 人間が読みやすい概要。
+      #
+      # @return [String]
       def inspect
         "<DecklistParser::Parser: #{@decklist.length}>"
       end
 
       # Parses the decklist and returns a Deck object.
+      # Public: Parse and return a Deck. Idempotent.
+      # 日本語: 解析して Deck を返します。多重実行に耐性があります。
+      #
+      # How it works (EN): Streams the decklist line-by-line, skipping
+      # section headers and comments, toggling sideboard state as
+      # appropriate, and parsing counts/names using a permissive regex
+      # that tolerates set codes and collector numbers.
+      #
+      # 仕組み (JA): デッキリストを 1 行ずつ処理し、セクション見出しや
+      # コメントをスキップ、適宜サイドボード状態を切替えながら、
+      # 枚数とカード名を寛容な正規表現で抽出します (セットコードや
+      # コレクタ番号を許容)。
+      #
+      # @return [CwCardUtils::DecklistParser::Deck]
       def parse
         return @deck if @deck.any?
 

data/lib/cw_card_utils/scryfall_cmc_data.rb

@@ -4,12 +4,23 @@ require "json"
 require "singleton"
 
 module CwCardUtils
-  # Abstract base class for card data sources
+  # Public: Abstract base class for card data sources.
+  # 日本語: カードデータソースの抽象基底クラスです。
   class CardDataSource
+    # Public: Find a card record by name.
+    # 日本語: カード名でレコードを検索します。
+    #
+    # @param name [String]
+    # @return [Hash, #dig, nil]
     def find_card(name)
       raise NotImplementedError, "Subclasses must implement find_card"
     end
 
+    # Public: Fetch converted mana cost for card.
+    # 日本語: 指定カードの点数で見たマナ・コストを取得します。
+    #
+    # @param name [String]
+    # @return [Numeric, nil]
     def cmc_for_card(name)
       card = find_card(name)
       card&.dig("cmc") || card&.cmc
@@ -17,6 +28,11 @@ module CwCardUtils
       nil
     end
 
+    # Public: Fetch color identity for card.
+    # 日本語: 指定カードの色アイデンティティを取得します。
+    #
+    # @param name [String]
+    # @return [Array<String>]
     def color_identity_for_card(name)
       card = find_card(name)
       card&.dig("color_identity") || card&.color_identity || []
@@ -24,6 +40,11 @@ module CwCardUtils
       []
     end
 
+    # Public: Fetch keywords for card.
+    # 日本語: 指定カードのキーワードを取得します。
+    #
+    # @param name [String]
+    # @return [Array<String>]
     def keywords_for_card(name)
       card = find_card(name)
       card&.dig("keywords") || card&.keywords || []
@@ -31,6 +52,11 @@ module CwCardUtils
       []
     end
 
+    # Public: Fetch toughness for card.
+    # 日本語: 指定カードのタフネスを取得します。
+    #
+    # @param name [String]
+    # @return [String, Integer, nil]
     def toughness_for_card(name)
       card = find_card(name)
       card&.dig("toughness") || card&.toughness
@@ -38,6 +64,11 @@ module CwCardUtils
       nil
     end
 
+    # Public: Fetch power for card.
+    # 日本語: 指定カードのパワーを取得します。
+    #
+    # @param name [String]
+    # @return [String, Integer, nil]
     def power_for_card(name)
       card = find_card(name)
       card&.dig("power") || card&.power
@@ -45,6 +76,11 @@ module CwCardUtils
       nil
     end
 
+    # Public: Fetch oracle text for card.
+    # 日本語: 指定カードのオラクルテキストを取得します。
+    #
+    # @param name [String]
+    # @return [String, nil]
     def oracle_text_for_card(name)
       card = find_card(name)
       card&.dig("oracle_text") || card&.oracle_text
@@ -52,6 +88,11 @@ module CwCardUtils
       nil
     end
 
+    # Public: Fetch type line for card (nil for Lands).
+    # 日本語: 指定カードのタイプ行を取得します (土地は nil)。
+    #
+    # @param name [String]
+    # @return [String, nil]
     def type_for_card(name)
       card = find_card(name)
       type = card&.dig("type_line") || card&.type_line
@@ -62,14 +103,24 @@ module CwCardUtils
     end
   end
 
-  # Example MongoDB data source implementation
-  # Users can implement their own data sources by inheriting from CardDataSource
+  # Public: Example MongoDB data source implementation.
+  # 日本語: MongoDB を用いた例示的なデータソース実装です。
   class MongoCardDataSource < CardDataSource
+    # Public: Initialize with a Mongo-like collection.
+    # 日本語: Mongo 互換コレクションで初期化します。
+    #
+    # @param collection [#find_one]
+    # @return [void]
     def initialize(collection)
       super()
       @collection = collection
     end
 
+    # Public: Find a card by exact name.
+    # 日本語: カード名の完全一致で検索します。
+    #
+    # @param name [String]
+    # @return [Hash, nil]
     def find_card(name)
       @collection.find_one({ "name" => name })
     rescue StandardError
@@ -77,44 +128,58 @@ module CwCardUtils
     end
   end
 
-  # Represents a card with Scryfall data
+  # Public: Represents a card with Scryfall data.
+  # 日本語: Scryfall データを持つカードの表現です。
   class ScryfallCard
+    # Public: Wrap a Scryfall-backed card object.
+    # 日本語: Scryfall データに基づくカードをラップします。
+    #
+    # @param name [String]
+    # @param data_source [CwCardUtils::CardDataSource, nil]
+    # @return [void]
     def initialize(name, data_source = nil)
       @name = name
       @data = (data_source || CwCardUtils.card_data_source).find_card(@name) || {}
     end
 
+    # @return [Numeric, nil]
     def cmc
       @data["cmc"]
     end
 
+    # @return [String, nil]
     def type
       @data["type_line"]
     end
 
+    # @return [Array<String>, nil]
     def keywords
       @data["keywords"]
     end
 
+    # @return [String, Integer, nil]
     def power
       @data["power"]
     end
 
+    # @return [String, Integer, nil]
     def toughness
       @data["toughness"]
     end
 
+    # @return [String, nil]
     def oracle_text
       @data["oracle_text"]
     end
 
+    # @return [Array<String>, nil]
     def color_identity
       @data["color_identity"]
     end
   end
 
-  # Handles conversion mana cost (CMC) data for Magic: The Gathering cards
-  # Uses Singleton pattern to avoid loading the large JSON file multiple times
+  # Public: Singleton accessor for Scryfall-based CMC/type data.
+  # 日本語: Scryfall ベースの CMC/タイプ情報へのシングルトンアクセスを提供します。
   class ScryfallCmcData < CardDataSource
     include Singleton
 
@@ -125,6 +190,11 @@ module CwCardUtils
       @found_cards = {}
     end
 
+    # Public: Find a card hash by name, using index or linear search.
+    # 日本語: インデックスまたは線形探索でカード名からデータを検索します。
+    #
+    # @param name [String]
+    # @return [Hash, nil]
     def find_card(name)
       load_data_if_needed
       @card_index[name] || @found_cards[name] ||= linear_search(name)
@@ -132,6 +202,18 @@ module CwCardUtils
       nil
     end
 
+    # Public: Full CMC dataset as parsed JSON array.
+    # 日本語: 解析済みの JSON 配列データ全体を返します。
+    #
+    # How it works (EN): Lazily loads the bundled JSON once, building an
+    # in-memory hash index by card name for fast lookups. Subsequent
+    # calls reuse the cached data.
+    #
+    # 仕組み (JA): バンドルされた JSON を遅延読み込みし、カード名をキー
+    # にしたインメモリのハッシュインデックスを構築します。以降の呼び出し
+    # ではキャッシュを再利用します。
+    #
+    # @return [Array<Hash>]
     def cmc_data
       load_data_if_needed
       @data
@@ -139,6 +221,8 @@ module CwCardUtils
 
     private
 
+    # Internal: Lazy-load JSON and build index once.
+    # 日本語: JSON を遅延読み込みし、インデックスを一度だけ構築します。
     def load_data_if_needed
       return if @data
 
@@ -146,6 +230,8 @@ module CwCardUtils
       build_card_index
     end
 
+    # Internal: Build hash from card name to card info.
+    # 日本語: カード名から情報へのハッシュインデックスを作成します。
     def build_card_index
       @card_index = {}
       @data.each do |card|
@@ -153,6 +239,8 @@ module CwCardUtils
       end
     end
 
+    # Internal: Linear scan fallback by exact name.
+    # 日本語: 完全一致名での線形探索フォールバック。
     def linear_search(name)
       @data.find { |card| card["name"] == name }
     end

data/lib/cw_card_utils/synergy_probability.rb

@@ -1,14 +1,35 @@
 # 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)
       targets = Array(target_names).uniq
       draws_clamped = clamp_draws(draws)
@@ -19,6 +40,19 @@ module CwCardUtils
     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)
       targets = Array(target_names).uniq
       case targets.size

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.11"
+  # Public: The current version string.
+  # 日本語: 現在のバージョン文字列です。
+  #
+  # @return [String]
+  VERSION = "0.1.12"
 end