cw_card_utils 0.1.11 → 0.2.1

data/lib/crackling_wit/card_utils.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+# Public: New preferred namespace entrypoint.
+# Usage:
+#   require "crackling_wit/card_utils"
+#   CracklingWit::CardUtils::DeckComparator.new(...)
+#
+# This file aliases the existing implementation under the new namespace
+# to provide a zero-churn migration path. All classes/modules remain
+# implemented in CwCardUtils and are re-exported here.
+
+require_relative "../cw_card_utils"
+
+module CracklingWit
+  module CardUtils
+    # Delegate configuration to the legacy module
+    class << self
+      def card_data_source=(source)
+        ::CwCardUtils.card_data_source = source
+      end
+
+      def card_data_source
+        ::CwCardUtils.card_data_source
+      end
+
+      def configure(&block)
+        ::CwCardUtils.configure(&block)
+      end
+    end
+
+    # Re-export legacy constants under the new namespace
+    Error               = ::CwCardUtils::Error
+    CardDataSource      = ::CwCardUtils::CardDataSource
+    CurveCalculator     = ::CwCardUtils::CurveCalculator
+    DecklistParser      = ::CwCardUtils::DecklistParser
+    ScryfallCmcData     = ::CwCardUtils::ScryfallCmcData
+    SynergyProbability  = ::CwCardUtils::SynergyProbability
+    DeckComparator      = ::CwCardUtils::DeckComparator
+    VERSION             = ::CwCardUtils::VERSION
+  end
+end

data/lib/crackling_wit.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# Top-level namespace for CracklingWit gems
+module CracklingWit
+end

data/lib/cw_card_utils/curve_calculator.rb

@@ -1,7 +1,13 @@
 # frozen_string_literal: true
 
 module CwCardUtils
+  # Public: Computes mana curve distributions from a deck.
+  # 日本語: デッキからマナカーブ分布を計算します。
   class CurveCalculator
+    # Public: Initialize with a deck-like object.
+    # 日本語: デッキ相当のオブジェクトで初期化します。
+    #
+    # @param deck [CwCardUtils::DecklistParser::Deck]
     def initialize(deck)
       @deck = deck
       @deck_size = @deck.count_without_lands
@@ -11,6 +17,18 @@ module CwCardUtils
       @collapsed_curve = {}
     end
 
+    # Public: Collapsed curve counts (0-1,2,3,4,5,6+).
+    # 日本語: まとめられたカーブ分布(0-1,2,3,4,5,6+)。
+    #
+    # How it works (EN): Builds upon the raw curve, bucketing CMCs into
+    # coarse buckets for quick, human-readable summaries. Lands are
+    # excluded, and nil/zero CMC non-lands are treated as 0.
+    #
+    # 仕組み (JA): 素のカーブを基に、CMC を粗い区分へまとめて
+    # 人が読みやすい集計を生成します。土地は除外し、nil/0 の CMC
+    # (土地でない) は 0 として扱います。
+    #
+    # @return [Hash{String=>Integer}]
     def collapsed_curve
       return @collapsed_curve if @collapsed_curve.values.any?
 
@@ -37,16 +55,48 @@ module CwCardUtils
       @collapsed_curve
     end
 
+    # Public: Raw curve counts keyed by CMC bucket.
+    # 日本語: CMCバケットごとの素のカウント。
+    #
+    # How it works (EN): Iterates over non-land cards and increments a
+    # bucket equal to ceil(CMC). Cards with nil/0 CMC and non-land type
+    # are assigned to bucket 0; lands are skipped entirely.
+    #
+    # 仕組み (JA): 土地以外のカードを走査し、ceil(CMC) をバケットに
+    # 加算します。CMC が nil/0 で土地でない場合は 0 バケットへ。
+    # 土地はスキップします。
+    #
+    # @return [Hash{Integer=>Integer}]
     def curve
       calculate_curve if @raw_curve.empty?
       @raw_curve
     end
 
+    # Public: Normalized curve (fractions of non-land count).
+    # 日本語: 正規化されたカーブ (土地を除く総数に対する割合)。
+    #
+    # How it works (EN): Sorts buckets by CMC and divides each count by
+    # the number of non-land cards, rounding to 4 decimals.
+    #
+    # 仕組み (JA): CMC 順にソートし、各バケットを土地以外の総枚数で
+    # 割って 4 桁に丸めます。
+    #
+    # @return [Hash{Integer=>Float}]
     def normalized_curve
       normalize_curve if @normalized_curve.values.empty?
       @normalized_curve
     end
 
+    # Public: Collapsed and normalized curve distribution.
+    # 日本語: まとめかつ正規化したカーブ分布。
+    #
+    # How it works (EN): Applies the same normalization as above to the
+    # collapsed buckets, providing an at-a-glance shape of the deck.
+    #
+    # 仕組み (JA): まとめたバケットに対して同様の正規化を行い、
+    # デッキの形状を直感的に把握できるようにします。
+    #
+    # @return [Hash{String=>Float}]
     def collapsed_normalized_curve
       normalize_collapsed_curve if @collapsed_normalized_curve.values.empty?
       @collapsed_normalized_curve

data/lib/cw_card_utils/deck_comparator.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+##
+# Public: Compares two decks and produces matchup insights for play/draw.
+# 日本語: 2つのデッキを比較し、先手/後手のマッチアップ分析を生成します。
 module CwCardUtils
   class DeckComparator
     attr_reader :deck_a, :deck_b, :analysis
@@ -11,12 +14,32 @@ module CwCardUtils
       interaction: 0.20,
     }.freeze
 
+    # Public: Create a comparator for two decks.
+    # 日本語: 2つのデッキを対象にコンパレータを作成します。
+    #
+    # @param deck_a [CwCardUtils::DecklistParser::Deck] 比較対象Aのデッキ
+    # @param deck_b [CwCardUtils::DecklistParser::Deck] 比較対象Bのデッキ
+    # @return [void]
     def initialize(deck_a, deck_b)
       @deck_a = deck_a
       @deck_b = deck_b
       @analysis = {}
     end
 
+    # Public: Compare decks for on-play and on-draw scenarios.
+    # 日本語: 先手/後手の両シナリオで比較します。
+    #
+    # Intent (EN): Produces two analyses (on the play / on the draw)
+    # combining archetype, curve segmentation, synergy hit-rate, and
+    # interaction density. A weighted heuristic yields Deck A's win
+    # rate and a favored label, plus explanatory notes.
+    #
+    # 意図 (JA): アーキタイプ、カーブ分割、シナジー成立率、
+    # インタラクション密度を統合し、先手/後手の 2 通りの分析を
+    # 生成します。重み付きヒューリスティックによりデッキAの勝率と
+    # 有利側のラベルを算出し、説明的なノートを付与します。
+    #
+    # @return [Hash] { on_play: Hash, on_draw: Hash }
     def compare
       results = {
         on_play: matchup_scenario(on_play: true),
@@ -27,6 +50,8 @@ module CwCardUtils
 
     private
 
+    # Internal: Build a single scenario result.
+    # 日本語: 単一シナリオの結果を作成します。
     def matchup_scenario(on_play:)
       a_info = analyze_deck(deck_a, on_play: on_play)
       b_info = analyze_deck(deck_b, on_play: !on_play)
@@ -51,6 +76,10 @@ module CwCardUtils
       }
     end
 
+    # Internal: Extract features used by the comparator from a deck.
+    # 日本語: デッキから比較用の特徴量を抽出します。
+    #
+    # @return [Hash]
     def analyze_deck(deck, on_play:)
       detector = CwCardUtils::DecklistParser::ArchetypeDetector.new(deck)
       archetype = detector.detect
@@ -76,6 +105,8 @@ module CwCardUtils
       }
     end
 
+    # Internal: Average combo hit-rate by turn 5 given play/draw.
+    # 日本語: 先手/後手を考慮した5ターン目までのシナジー成立率の平均。
     def calc_synergy_hit_rate(deck, on_play:)
       synergy_pairs = extract_synergy_pairs(deck)
       return 0 if synergy_pairs.empty?
@@ -88,6 +119,8 @@ module CwCardUtils
       (probs.sum / probs.size).round(2)
     end
 
+    # Internal: Return unordered pairs of synergy-tagged cards.
+    # 日本語: シナジー系タグのカード名ペアを返します。
     def extract_synergy_pairs(deck)
       synergy_cards = deck.main.select do |card|
         card.tags.intersect?([:synergistic_finisher, :tribal_synergy, :scaling_threat])
@@ -96,10 +129,14 @@ module CwCardUtils
       synergy_cards.map(&:name).combination(2).to_a
     end
 
+    # Internal: Cards seen by specified turn.
+    # 日本語: 指定ターンまでに見られるカード枚数。
     def draws_by_turn(turn, on_play:)
       on_play ? (7 + (turn - 1)) : (7 + turn)
     end
 
+    # Internal: Combine sub-scores into a single win-rate for Deck A.
+    # 日本語: 複数の部分スコアを統合し、デッキAの勝率を返します。
     def weighted_score(a, b)
       # Archetype advantage
       archetype_score = case predict_matchup(a, b)
@@ -143,6 +180,8 @@ module CwCardUtils
       ).round(3)
     end
 
+    # Internal: Heuristic label for who is favored and why.
+    # 日本語: どちらが有利かのヒューリスティックな説明を返します。
     def predict_matchup(a, b)
       return "Deck A (Aggro)" if is_aggro?(a) && is_control?(b)
       return "Deck B (Aggro)" if is_aggro?(b) && is_control?(a)
@@ -153,14 +192,20 @@ module CwCardUtils
       "Even Matchup"
     end
 
+    # Internal: Aggro heuristic.
+    # 日本語: アグロ判定のヒューリスティック。
     def is_aggro?(info)
       info[:archetype].downcase.include?("aggro") || info[:early_curve] > 0.5
     end
 
+    # Internal: Control heuristic.
+    # 日本語: コントロール判定のヒューリスティック。
     def is_control?(info)
       info[:archetype].downcase.include?("control") || info[:late_curve] > 0.4
     end
 
+    # Internal: Compare interaction tag density.
+    # 日本語: インタラクションの密度を比較します。
     def compare_interaction_density(a, b)
       a_interact = a[:tag_ratios][:interaction].to_f.round(2)
       b_interact = b[:tag_ratios][:interaction].to_f.round(2)
@@ -174,6 +219,8 @@ module CwCardUtils
       end
     end
 
+    # Internal: Produce human-readable notes for a scenario.
+    # 日本語: シナリオごとの人間に読みやすい注釈を生成します。
     def generate_notes(a, b, on_play:)
       notes = []
       notes << (on_play ? "Deck A is on the play" : "Deck B is on the play")

data/lib/cw_card_utils/decklist_parser/archetype_detector.rb

@@ -2,9 +2,16 @@
 
 module CwCardUtils
   module DecklistParser
+    # Public: Detects deck archetypes and color/tribe labels.
+    # 日本語: デッキのアーキタイプと色/部族ラベルを検出します。
     class ArchetypeDetector
       attr_reader :deck, :format, :tribe, :colors, :tag_counts, :tag_ratios
 
+      # Public: Initialize with a deck.
+      # 日本語: デッキで初期化します。
+      #
+      # @param deck [CwCardUtils::DecklistParser::Deck]
+      # @return [void]
       def initialize(deck)
         @deck = deck
         @format = deck.format.to_s.downcase # :standard, :edh, etc.
@@ -16,6 +23,21 @@ module CwCardUtils
         calculate_ratios
       end
 
+      # Public: Full label, e.g., "Azorius Cat Tribal Midrange".
+      # 日本語: 例 "Azorius Cat Tribal Midrange" のような完全ラベルを返します。
+      #
+      # Intent (EN): Converts detected color identity, dominant tribe, and
+      # archetype into a concise human-readable label. Color comes from
+      # identity resolution, tribe from majority subtype, and archetype
+      # from heuristics over tag counts/ratios and average CMC.
+      #
+      # 意図 (JA): 検出した色アイデンティティ、優勢トライブ、
+      # アーキタイプを人が読みやすい短いラベルへ変換します。色は
+      # アイデンティティ解決、トライブは多数派サブタイプ、
+      # アーキタイプはタグ頻度/比率と平均 CMC のヒューリスティックから
+      # 決定します。
+      #
+      # @return [String]
       def detect
         archetype = detect_archetype
         color_label = resolve_color_label(colors)
@@ -30,6 +52,8 @@ module CwCardUtils
 
       # === TAG COUNTING ===
 
+      # Internal: Count tag frequencies across the deck.
+      # 日本語: デッキ全体のタグ出現数をカウントします。
       def count_tags
         total_tags = 0
 
@@ -45,6 +69,8 @@ module CwCardUtils
         @tag_counts[:_total] = total_tags
       end
 
+      # Internal: Convert counts to ratios.
+      # 日本語: カウントを比率へ変換します。
       def calculate_ratios
         total = @tag_counts[:_total].to_f
         return if total.zero?
@@ -57,6 +83,8 @@ module CwCardUtils
 
       # === CMC UTILITY ===
 
+      # Internal: Average CMC across mainboard (lands excluded by caller logic).
+      # 日本語: メインボードの平均 CMC。
       def average_cmc
         @average_cmc ||= begin
           cmcs = deck.main.map { |card| card.respond_to?(:cmc) ? card.cmc.to_f : nil }.compact
@@ -66,6 +94,8 @@ module CwCardUtils
       end
 
       # === FORMAT-AWARE DETECTION ===
+      # Internal: Heuristic archetype classification.
+      # 日本語: アーキタイプのヒューリスティック分類。
       def detect_archetype
         if format == "edh"
           return :combo if tag_ratios[:combo_piece].to_f > 0.10 && tag_ratios[:draw].to_f > 0.08
@@ -105,10 +135,14 @@ module CwCardUtils
 
       # === COLOR IDENTITY ===
 
+      # Internal: Compute unique color identity from deck.
+      # 日本語: デッキから色アイデンティティを抽出します。
       def resolve_color_identity(deck)
         deck.main.flat_map { |c| c.respond_to?(:color_identity) ? c.color_identity : [] }.uniq.sort
       end
 
+      # Internal: Render color identity into label.
+      # 日本語: 色アイデンティティをラベルへ変換します。
       def resolve_color_label(identity)
         ColorIdentityResolver.resolve(identity)
       end

data/lib/cw_card_utils/decklist_parser/card.rb

@@ -2,8 +2,16 @@
 
 module CwCardUtils
   module DecklistParser
-    # A Card is a single card in a deck.
+    # Public: A single card entry in a deck.
+    # 日本語: デッキ内の1枚のカードを表します。
     class Card
+      # Public: Create a card entry.
+      # 日本語: カードエントリを作成します。
+      #
+      # @param name [String]
+      # @param count [Integer]
+      # @param cmc_data_source [CwCardUtils::CardDataSource, nil]
+      # @return [void]
       def initialize(name, count, cmc_data_source = nil)
         @name = name
         @count = count
@@ -11,45 +19,102 @@ module CwCardUtils
         @cmc_data_source = cmc_data_source || CwCardUtils.card_data_source
       end
 
-      attr_reader :name, :count, :cmc_data_source
+      # Public: Card name.
+      # 日本語: カード名。
+      # @return [String]
+      attr_reader :name
+
+      # Public: Number of copies in the deck.
+      # 日本語: デッキ内の枚数。
+      # @return [Integer]
+      attr_reader :count
+
+      # Public: Data source used for lookup.
+      # 日本語: 参照に用いるデータソース。
+      # @return [CwCardUtils::CardDataSource, nil]
+      attr_reader :cmc_data_source
+
+      # Public: Tag symbols inferred for the card.
+      # 日本語: そのカードに付与されたタグ一覧。
+      # @return [Array<Symbol>]
       attr_accessor :tags
 
+      # Public: Converted mana cost from the data source.
+      # 日本語: データソースから取得した点数で見たマナ・コスト。
+      #
+      # @return [Numeric, nil]
       def cmc
         @cmc ||= @cmc_data_source&.cmc_for_card(@name)
       end
 
+      # Public: Type line from the data source.
+      # 日本語: データソースから取得したタイプ行。
+      #
+      # @return [String]
       def type
         @type ||= @cmc_data_source&.type_for_card(@name) || "Land"
       end
 
+      # Public: Keywords from the data source.
+      # 日本語: データソースから取得したキーワード。
+      #
+      # @return [Array<String>]
       def keywords
         @keywords ||= @cmc_data_source&.keywords_for_card(@name) || []
       end
 
+      # Public: Oracle text from the data source.
+      # 日本語: データソースから取得したオラクルテキスト。
+      #
+      # @return [String, nil]
       def oracle_text
         @oracle_text ||= @cmc_data_source&.oracle_text_for_card(@name)
       end
 
+      # Public: Power from the data source.
+      # 日本語: データソースから取得したパワー。
+      #
+      # @return [String, Integer, nil]
       def power
         @power ||= @cmc_data_source&.power_for_card(@name)
       end
 
+      # Public: Toughness from the data source.
+      # 日本語: データソースから取得したタフネス。
+      #
+      # @return [String, Integer, nil]
       def toughness
         @toughness ||= @cmc_data_source&.toughness_for_card(@name)
       end
 
+      # Public: Color identity array from the data source.
+      # 日本語: データソースから取得した色アイデンティティ配列。
+      #
+      # @return [Array<String>]
       def color_identity
         @color_identity ||= @cmc_data_source&.color_identity_for_card(@name) || []
       end
 
+      # Public: Human-readable summary.
+      # 日本語: 人間が読みやすい概要。
+      #
+      # @return [String]
       def inspect
         "<Card: #{@name} (#{@count}) #{cmc}>"
       end
 
+      # Public: Serialize to a Hash.
+      # 日本語: Hash へシリアライズします。
+      #
+      # @return [Hash]
       def to_h
         { name: @name, count: @count, cmc: cmc, type: type, keywords: keywords, power: power, toughness: toughness, oracle_text: oracle_text }
       end
 
+      # Public: JSON representation.
+      # 日本語: JSON 文字列を返します。
+      #
+      # @return [String]
       def to_json(*_args)
         to_h.to_json
       end

data/lib/cw_card_utils/decklist_parser/card_tagger.rb

@@ -3,7 +3,15 @@
 module CwCardUtils
   module DecklistParser
 
+    # Public: Derives semantic tags from card text/type/keywords.
+    # 日本語: カードのテキスト/タイプ/キーワードから意味的なタグを導出します。
     class CardTagger
+      # Public: Initialize a tagger for a card within a deck context.
+      # 日本語: デッキ文脈でのカード用タグ付け器を初期化します。
+      #
+      # @param card [CwCardUtils::DecklistParser::Card]
+      # @param deck [CwCardUtils::DecklistParser::Deck]
+      # @return [void]
       def initialize(card, deck)
         @card = card
         @text = card.oracle_text.to_s.downcase
@@ -24,6 +32,22 @@ module CwCardUtils
         @tribe = deck.tribe&.to_s&.downcase
       end
 
+      # Public: Compute tags for a card in the context of a deck.
+      # 日本語: デッキ文脈でカードのタグを算出します。
+      #
+      # How it works (EN): Applies lightweight NLP-style regex heuristics
+      # over oracle text, type line, and keywords. Recognizes role tags
+      # such as :threat, :interaction, :ramp, and synergy/tribal patterns
+      # (e.g., token/ETB triggers, scaling effects, chosen type). Uses
+      # deck context (tribe) to infer tribal roles and finishers.
+      #
+      # 仕組み (JA): オラクルテキスト、タイプ行、キーワードへ簡易な
+      # 正規表現ベースのヒューリスティックを適用します。:threat、
+      # :interaction、:ramp などの役割タグや、トークン/ETB、スケール系、
+      # 選択タイプなどのシナジー・部族パターンを検出します。デッキの
+      # 文脈 (トライブ) を用いて部族ロールやフィニッシャーも推論します。
+      #
+      # @return [Array<Symbol>]
       def tags
         t = []
 
@@ -116,20 +140,28 @@ module CwCardUtils
 
       private
 
+      # Internal: Whether the card is a creature.
+      # 日本語: そのカードがクリーチャーかどうか。
       def creature?
         @type_line.include?("creature")
       end
 
+      # Internal: Whether the card is a planeswalker.
+      # 日本語: そのカードがプレインズウォーカーかどうか。
       def planeswalker?
         @type_line.include?("planeswalker")
       end
 
+      # Internal: Extract creature subtypes as array.
+      # 日本語: クリーチャーのサブタイプを配列として抽出します。
       def creature_subtypes
         return [] unless creature?
         raw = @type_line.split(/[—-]/).last.to_s.strip
         raw.split.map(&:downcase)
       end
 
+      # Internal: Heuristic for finisher classification.
+      # 日本語: フィニッシャー判定のヒューリスティック。
       def likely_finisher?
         return true if @cmc >= 6 && @text.match?(/flying|trample|indestructible|each opponent|you win|extra turn|double/i)
         return true if planeswalker? && @text.match?(/creatures.*get.*flying|you get an emblem|each opponent/i)

data/lib/cw_card_utils/decklist_parser/color_identity_resolver.rb

@@ -2,6 +2,8 @@
 
 module CwCardUtils
   module DecklistParser
+    # Public: Convert color identity arrays to human-readable labels.
+    # 日本語: 色アイデンティティの配列をわかりやすい名称へ変換します。
     class ColorIdentityResolver
       COLOR_NAMES = {
         %w[W] => "White",
@@ -42,6 +44,11 @@ module CwCardUtils
         [] => "Colorless",
       }.freeze
 
+      # Public: Resolve a color identity array to a label.
+      # 日本語: 色アイデンティティ配列をラベルへ変換します。
+      #
+      # @param identity [Array<String>] like ["U", "W"]
+      # @return [String]
       def self.resolve(identity)
         key = identity.sort
         COLOR_NAMES[key] || key.join("/")