riichi_engine 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0705360e35c7551b07930b9c6faf76514066be31cf6c3de5ec7ffd14ec911ef3
+  data.tar.gz: 7216b262185cc200da28ce090f93af3af5305ab44cc335a4492ec2950adc80a3
+SHA512:
+  metadata.gz: 6403afe314adc11f52fb58650ef8cd5037d917643589b5f05a0b67b82d21a3283f04f39665ea6a3148aaf037e7e90e28210dc73f661385d88b09548c9ff41970
+  data.tar.gz: 7b9ae0f5aded16e00b8fd619c538146af2cad725adf1cfb94256c31e024fbcc3107324ee9ddb71eb6fc07794105a6c89f75d28f29733756258e9cb2d360467df

data/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,19 @@
+---
+name: Bug report
+about: Report a defect in riichi_engine
+title: "[Bug] "
+labels: bug
+assignees: ""
+---
+
+## Summary
+
+## Expected
+
+## Actual
+
+## Reproduction
+
+## Version
+
+## Notes

data/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,17 @@
+---
+name: Feature request
+about: Propose a new capability or API addition
+title: "[Feature] "
+labels: enhancement
+assignees: ""
+---
+
+## Summary
+
+## Motivation
+
+## Proposed API / Behavior
+
+## Alternatives
+
+## Notes

data/.github/pull_request_template.md

@@ -0,0 +1,15 @@
+## Summary
+
+## Changes
+
+## Verification
+
+- [ ] `bundle exec rspec` in `vendor/gems/riichi_engine`
+- [ ] `bundle exec rspec` in host app
+
+## Docs
+
+- [ ] `README.md` updated if needed
+- [ ] `docs/api_reference.md` updated if needed
+- [ ] `docs/usage_examples.md` updated if needed
+- [ ] `docs/public_api_policy.md` updated if needed

data/.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: .ruby-version
+          bundler-cache: true
+
+      - name: Run specs
+        run: bundle exec rspec

data/.github/workflows/release.yml

@@ -0,0 +1,31 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: .ruby-version
+          bundler-cache: true
+
+      - name: Run specs
+        run: bundle exec rspec
+
+      - name: Build gem
+        run: gem build riichi_engine.gemspec
+
+      # gem push は手動で行う:
+      #   gem push riichi_engine-*.gem
+      # 事前に RubyGems へのログイン（gem signin）または
+      # ~/.gem/credentials への API キー設定が必要。

data/.gitignore

@@ -0,0 +1,6 @@
+/.bundle/
+/.rspec_status
+/coverage/
+/tmp/
+/Gemfile.lock
+/*.gem

data/.ruby-version

@@ -0,0 +1 @@
+4.0.2

data/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## 0.1.0 (2026-04-05)
+
+初回リリース
+
+### 機能
+
+- **局進行** — 自摸・打牌・リーチ・ポン・チー・カン（暗槓・加槓・大明槓）・九種九牌の処理
+- **和了判定** — 通常和了形・七対子・国士無双に対応
+- **役判定** — 一般役から役満まで全役対応（ダブル役満はルール設定で切り替え可）
+- **点数計算** — 符・翻計算、基本点・各プレイヤーへの支払い点算出、本場加算
+- **流局処理** — 荒牌流局・途中流局（四風連打・四家リーチ・三家和・四槓散了）、ノーテン罰符計算
+- **ゲーム進行** — 連荘・親流れ・オーラス終了条件・トビ判定・西入対応
+- **順位計算** — ウマ・オカを含む最終スコア算出
+- **CPU AI** — Easy / Normal / Hard の3段階
+- **状態の永続化** — `RoundState` の JSON シリアライズ・デシリアライズ

data/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HenrikStephensen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,164 @@
+# riichi_engine
+
+Pure Ruby 実装のリーチ麻雀エンジン Gem です。
+
+局進行・和了判定・役判定・点数計算・順位計算を Rails・ActiveRecord 非依存で提供します。  
+host app から `RiichiEngine::API` を呼ぶだけで、麻雀の完全なドメインロジックを利用できます。
+
+---
+
+## 機能
+
+| カテゴリ | 内容 |
+|---|---|
+| 局進行管理 | 牌山構築・配牌・自摸・打牌・鳴き（ポン/チー/カン）・リーチ処理 |
+| 和了判定 | 通常和了形・七対子・国士無双 |
+| 役判定 | 一般役から役満まで全役対応 |
+| 点数計算 | 符・翻の計算、基本点・各プレイヤーへの支払い点算出 |
+| 順位計算 | ウマ・オカを含む最終スコア計算 |
+| CPU AI | Easy / Normal / Hard の3段階（host app 側での切り替え対応） |
+
+---
+
+## ドキュメント
+
+| ドキュメント | 内容 |
+|---|---|
+| [概念・用語集](docs/concepts.md) | 牌記法・麻雀用語・アクション種別の解説 |
+| [使用例](docs/usage_examples.md) | 局開始〜終了までのコード例 |
+| [局ステートマシン](docs/state_machine.md) | フェーズ遷移・アクション優先順位・特殊シーケンスの解説 |
+| [API リファレンス](docs/api_reference.md) | 公開メソッドの詳細仕様 |
+| [公開 API ポリシー](docs/public_api_policy.md) | 安定保証の範囲と方針 |
+| [Adapter 契約](docs/adapter_contract.md) | host app と gem の責務境界 |
+
+---
+
+## インストール
+
+```bash
+bundle add riichi_engine
+```
+
+または Gemfile に直接追加：
+
+```ruby
+gem "riichi_engine"
+```
+
+---
+
+## クイックスタート
+
+### 1. 局を開始する
+
+`RuleConfig` を作成し、局の初期情報を `GameSetupSnapshot` に詰めて `setup_round` を呼びます。
+
+```ruby
+rule = Mahjong::Config::RuleConfig.new  # デフォルトルール（東南戦・25000点持ち等）
+
+snapshot = Mahjong::Snapshots::GameSetupSnapshot.new(
+  bakaze:    "ton",  # 東場
+  kyoku:     1,      # 1局目
+  honba:     0,
+  kyoutaku:  0,
+  oya_index: 0,      # seat 0 が親
+  scores: { 0 => 25_000, 1 => 25_000, 2 => 25_000, 3 => 25_000 }
+)
+
+state = RiichiEngine::API.setup_round(
+  game_snapshot: snapshot,
+  rule:          rule,
+  seed:          "round-001"  # 牌山シード（省略可）
+)
+```
+
+### 2. 自摸・打牌を進める
+
+アクションを順に `apply_round_action` へ渡すことで局を進行させます。  
+選択可能なアクション一覧は `available_round_actions` で取得できます。
+
+```ruby
+# 自摸
+RiichiEngine::API.apply_round_action(
+  state:  state,
+  action: { type: :tsumo },
+  rule:   rule
+)
+
+# 現在の手番プレイヤーが選べるアクションを取得
+actions = RiichiEngine::API.available_round_actions(
+  state: state,
+  seat:  state.current_seat,
+  rule:  rule
+)
+
+# 打牌アクションを選んで適用
+dahai = actions.find { |a| a[:type] == :dahai }
+
+result = RiichiEngine::API.apply_round_action(
+  state:  state,
+  action: { type: :dahai, seat: state.current_seat, tile: dahai[:tile] },
+  rule:   rule
+)
+```
+
+`result` は `Mahjong::Results::RoundFlowResult` です。  
+`result.round_end?` が `true` のとき局が終了しており、`result.round_end_info` に終了情報が入ります。
+
+### 3. 局終了後に次局かゲーム終了かを判定する
+
+```ruby
+flow_result = RiichiEngine::API.judge_next_game_round(
+  progress_snapshot: progress_snapshot,
+  round_end_info:    result.round_end_info,
+  rule:              rule
+)
+
+# flow_result.next_round? => true なら次局へ
+# flow_result.game_end?   => true ならゲーム終了
+```
+
+---
+
+## エラー
+
+エンジンが発生させる例外は2種類です。host app 側の adapter で rescue してください。
+
+```ruby
+RiichiEngine::API::InvalidActionError  # 不正なアクション（不正な打牌・存在しない鳴き等）
+RiichiEngine::API::EngineError         # エンジン内部エラー
+```
+
+---
+
+## ルール設定
+
+`RuleConfig.new` にハッシュを渡すことで細かい設定が可能です。
+
+```ruby
+rule = Mahjong::Config::RuleConfig.new(
+  "game_type"      => "hanchan",  # "hanchan"（東南戦）or "tonpuu"（東風戦）
+  "initial_score"  => 25_000,
+  "uma"            => [20_000, 10_000, -10_000, -20_000],
+  "kuitan"         => true,       # 食い断あり
+  "double_ron"     => true,       # ダブロン
+  "tobi"           => true        # トビあり
+)
+```
+
+設定項目の詳細は [API リファレンス](docs/api_reference.md#ruleconfigの設定項目) を参照してください。
+
+---
+
+## テスト実行
+
+```bash
+bundle install --local
+bundle exec rspec
+```
+
+---
+
+## ライセンス
+
+MIT

data/docs/adapter_contract.md

@@ -0,0 +1,144 @@
+# Adapter 契約
+
+`riichi_engine` は pure Ruby のドメインロジックのみを持ち、副作用・永続化は一切持ちません。  
+host app 側の「adapter 層」がこの境界で両者をつなぐ役割を担います。
+
+---
+
+## 責務の境界
+
+### riichi_engine 側が持つもの
+
+- 局進行ロジック
+- 和了判定・役判定
+- 点数計算・順位計算
+- CPU AI の判断ロジック
+
+### host app 側が持つもの（gem に持ち込まないもの）
+
+- ActiveRecord
+- ActionCable / Turbo
+- ActiveJob
+- キャッシュバックエンド
+- ロガー
+- リクエスト / セッション / ユーザーコンテキスト
+
+---
+
+## host app 側 adapter の役割
+
+host app には以下の adapter を実装します。各 adapter の責務を分けることで、gem のバージョンアップ時の修正箇所を局所化できます。
+
+| Adapter | 責務 |
+|---|---|
+| `MahjongAdapter::RuleBuilder` | DB / room 設定から `RuleConfig` を生成する |
+| `MahjongAdapter::SnapshotBuilder` | ActiveRecord モデルから各種 Snapshot を生成する |
+| `MahjongAdapter::RoundEndInfoBuilder` | 局終了情報を `RoundEndInfo` に正規化する |
+| `MahjongAdapter::FinalResultBuilder` | 最終結果にプレイヤー表示情報を合成する |
+| `MahjongAdapter::RoundStateCache` | `RoundState` のキャッシュ保存・復元・削除を管理する |
+| `MahjongAdapter::CpuAiFactory` | CPU レベルに応じた AI インスタンスを選択する |
+
+---
+
+## SnapshotBuilder の契約
+
+ActiveRecord オブジェクトを pure な Snapshot へ変換します。
+
+**生成対象：**
+
+```ruby
+Mahjong::Snapshots::GameSetupSnapshot      # 局開始時
+Mahjong::Snapshots::GameProgressSnapshot   # 局終了後の進行判定時
+Mahjong::Snapshots::FinalResultSnapshot    # ゲーム終了時の最終結果
+Mahjong::Snapshots::WinEvaluationSnapshot  # 和了評価時
+```
+
+**制約：**
+
+- Snapshot の値に ActiveRecord オブジェクトを含めない
+- key は seat 番号基準で統一する
+- `score` や `bakaze` などの値はドメイン側がそのまま読める形にする
+
+---
+
+## RuleBuilder の契約
+
+host app の DB 設定や room/game 設定から `Mahjong::Config::RuleConfig` を作成します。
+
+**制約：**
+
+- `RuleConfig` に渡すのは plain Ruby の `Hash`（ActiveRecord モデルを渡さない）
+- key の正規化は `RuleConfig` 側で行うため、adapter 側で意識しなくてよい
+
+```ruby
+# OK: Hash で渡す
+RuleConfig.new("kuitan" => room.rule_kuitan, "uma" => room.rule_uma)
+
+# NG: モデルを直接渡す
+RuleConfig.new(room)
+```
+
+---
+
+## RoundStateCache の契約
+
+`RoundState` のシリアライズ・デシリアライズとキャッシュキーを管理します。
+
+**制約：**
+
+- キャッシュバックエンドの詳細は adapter 側で隠蔽する
+- gem 側へは `json` 文字列のみを渡す
+- バージョン管理・キャッシュ失効（invalidation）は host app 側で担う
+
+```ruby
+# 保存
+json = state.to_json
+RoundStateCache.save(round_id: round.id, json:)
+
+# 復元
+json  = RoundStateCache.load(round_id: round.id)
+state = RiichiEngine::API.deserialize_round_state(json)
+```
+
+---
+
+## RoundEndInfoBuilder の契約
+
+局終了時の host app 文脈の情報を `Mahjong::Results::RoundEndInfo` に正規化します。
+
+**担当する処理：**
+
+- 流局時のテンパイ座席の算出（`RiichiEngine::API.tenpai_seats` を呼ぶ）
+- ノーテン罰符計算のための API 呼び出し
+- 和了評価のためのスナップショット組み立て
+
+---
+
+## FinalResultBuilder の契約
+
+`RiichiEngine::API.calculate_final_results` が返す `FinalResult` に、host app 固有の表示情報を合成します。
+
+**担当する情報：**
+
+- `player_id`
+- プレイヤー名
+- 表示順・装飾に必要な補足情報
+
+---
+
+## Service / Job 層のルール
+
+service / job が守るべきこと：
+
+1. gem の呼び出しは `RiichiEngine::API` を経由する
+2. API に渡すオブジェクトは adapter が生成したものだけにする
+3. DB 保存・Job enqueue・broadcast は service / job 側で行う
+4. gem の内部 namespace（`Mahjong::Flow::*` など）を直接 stub / mock しない
+
+```ruby
+# OK: API 経由
+result = RiichiEngine::API.apply_round_action(state:, action:, rule:)
+
+# NG: 内部クラスを直接呼ぶ
+result = Mahjong::Flow::Rounds::RoundFlow.apply_action(state:, action:, rule:)
+```