cw_card_utils 0.1.11 → 0.1.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 23145f32617794cf1af83523bf179d6d9260cc75251a24207ae6ea6ce0274599
-  data.tar.gz: 7cd65b1d7e93b8f9c2438df235d77c44e294d543ff1f22e8b0aa16efb5e51192
+  metadata.gz: 8c4c153971824b05a57199518aa8143b81eb2b5d827484ad2a864d93423581cf
+  data.tar.gz: 753fb053d7348cac6b4b65dec309a95f94c98cf4340cc71a00380bf0ea650f02
 SHA512:
-  metadata.gz: 556bc7d3c4dc4d87b752d2923eba061b23356a6e2330f33691e34ee215d7cdd9e6148cd8c4a9082ddbcda179ffd68bef162d0bc6e11c25db3bc05b95589f83d9
-  data.tar.gz: e81abacff1c5dae3476a1ffb9e6a779105546f7a020edcc36fb463082842645a784e922d89660c2e779c4ceaa1d51dadf14b84ed4ae33d6326fe7188ab1135b7
+  metadata.gz: 2a99b206d6a6abd73a1118016d71979ead2205712da4c57eb1251a43c03d425a880fd6ff63068469cf1926a2c6b4dec1f8e6f95dc13675cc144de1a528723935
+  data.tar.gz: 97f303620f866c092048ffa473547e0e70ef610453b08194fc7bf30b732bd78ab043bf43118b53856e31fb5a0ccb5d1ef7e966a6f0b6d4b67777ffeee308e507

data/README.md

@@ -2,6 +2,20 @@
 
 A Ruby gem for analyzing Magic: The Gathering decklists and calculating various metrics.
 
+## 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,6 +30,41 @@ 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.
+```
+
 ## Configuration
 
 You can configure the card data source used by the library:
@@ -34,12 +83,11 @@ The default data source is `CwCardUtils::ScryfallCmcData.instance`, which loads
 
 ## 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 +96,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 +169,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

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("/")