@pai-forge/riichi-mahjong 0.2.0 → 0.3.0

package/dist/features/yaku/lib/structures/mentsu-te.d.ts

@@ -0,0 +1,24 @@
+import type { MentsuHouraStructure } from "../../types";
+import type { Tehai14 } from "../../../../types";
+/**
+ * 手牌を標準形（4面子1雀頭）に構造化する。
+ * 七対子や国士無双は対象外。
+ *
+ * 【役判定について】
+ * この関数は純粋に「4面子1雀頭」の形になっているかのみを検証します。
+ * 役が成立しているかどうか（和了できるかどうか）は判定しません。
+ * そのため、役なし（Yakunashi）の手牌であっても構造的に整合していれば結果を返します。
+ *
+ * 【戻り値が配列である理由について】
+ * 麻雀の手牌は、同じ牌構成であっても複数の解釈（多義性）が成立する場合があります。
+ * 例: `111222333m`
+ * - 三暗刻 (111 + 222 + 333)
+ * - 三連刻/一盃口 (123 + 123 + 123)
+ *
+ * このように成立する役が変わる可能性があるため、可能な全ての構造化パターンをリストとして返します。
+ * 利用側は、これらのパターンのうち最も高得点となるものを選択する必要があります。
+ *
+ * @param tehai 和了形の手牌
+ * @returns 可能な構造化パターンのリスト。構造化できない場合は空配列。
+ */
+export declare function getHouraStructuresForMentsuTe(tehai: Tehai14): MentsuHouraStructure[];

package/dist/features/yaku/lib/structures/mentsu-te.js

@@ -0,0 +1,127 @@
+import { validateTehai14, countHaiKind } from "../../../../core/tehai";
+import { isTuple4 } from "../../../../utils/assertions";
+/**
+ * 手牌を標準形（4面子1雀頭）に構造化する。
+ * 七対子や国士無双は対象外。
+ *
+ * 【役判定について】
+ * この関数は純粋に「4面子1雀頭」の形になっているかのみを検証します。
+ * 役が成立しているかどうか（和了できるかどうか）は判定しません。
+ * そのため、役なし（Yakunashi）の手牌であっても構造的に整合していれば結果を返します。
+ *
+ * 【戻り値が配列である理由について】
+ * 麻雀の手牌は、同じ牌構成であっても複数の解釈（多義性）が成立する場合があります。
+ * 例: `111222333m`
+ * - 三暗刻 (111 + 222 + 333)
+ * - 三連刻/一盃口 (123 + 123 + 123)
+ *
+ * このように成立する役が変わる可能性があるため、可能な全ての構造化パターンをリストとして返します。
+ * 利用側は、これらのパターンのうち最も高得点となるものを選択する必要があります。
+ *
+ * @param tehai 和了形の手牌
+ * @returns 可能な構造化パターンのリスト。構造化できない場合は空配列。
+ */
+export function getHouraStructuresForMentsuTe(tehai) {
+    validateTehai14(tehai);
+    // HaiKindDistributionはreadonlyなので、可変配列に複製する
+    const counts = [...countHaiKind(tehai.closed)];
+    const results = [];
+    // 1. 雀頭候補を探す
+    for (let i = 0; i < 34; i++) {
+        // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+        const kind = i;
+        if ((counts[kind] ?? 0) >= 2) {
+            // 雀頭抜き出し
+            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+            counts[kind] -= 2;
+            // 残りの牌で面子分解
+            const requiredMentsuCount = 4 - tehai.exposed.length;
+            const subResults = decomposeClosedMentsu(counts, requiredMentsuCount);
+            // subResultsには閉じた部分で見つかった面子のリストが含まれる
+            for (const closedMentsu of subResults) {
+                // 副露面子と結合して完全な構成を作成する
+                const fullMentsuList = [...closedMentsu, ...tehai.exposed];
+                // 4面子であることを確認（ロジック上は保証されているはずだが、念のため）
+                if (isTuple4(fullMentsuList)) {
+                    results.push({
+                        type: "Mentsu",
+                        fourMentsu: fullMentsuList,
+                        jantou: { type: "Toitsu", hais: [kind, kind] },
+                    });
+                }
+            }
+            // バックトラック
+            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+            counts[kind] += 2;
+        }
+    }
+    return results;
+}
+/**
+ * 閉じた手牌の残りを面子に分解する再帰関数
+ */
+function decomposeClosedMentsu(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+counts, requiredCount) {
+    if (requiredCount === 0) {
+        // 全ての牌が使用されたか確認
+        const remaining = counts.reduce((acc, c) => acc + c, 0);
+        return remaining === 0 ? [[]] : [];
+    }
+    // 面子の重複順列を防ぎ決定論的な順序を強制するため、カウントが0より大きい最初の牌を見つける
+    let firstIndex = -1;
+    for (let i = 0; i < 34; i++) {
+        if ((counts[i] ?? 0) > 0) {
+            firstIndex = i;
+            break;
+        }
+    }
+    if (firstIndex === -1) {
+        // Should not happen if requiredCount > 0, unless invalid hand
+        return [];
+    }
+    const results = [];
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+    const kind = firstIndex;
+    // 刻子を試す
+    if ((counts[kind] ?? 0) >= 3) {
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        counts[kind] -= 3;
+        const tails = decomposeClosedMentsu(counts, requiredCount - 1);
+        const koutsu = { type: "Koutsu", hais: [kind, kind, kind] };
+        for (const tail of tails) {
+            results.push([koutsu, ...tail]);
+        }
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        counts[kind] += 3; // バックトラック
+    }
+    // 順子を試す
+    // 数牌（0-26）かつ7を超えない（n, n+1, n+2を作れる）場合のみ有効
+    if (kind < 27 && kind % 9 <= 6) {
+        const k1 = kind;
+        // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+        const k2 = (kind + 1);
+        // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+        const k3 = (kind + 2);
+        if ((counts[k2] ?? 0) > 0 && (counts[k3] ?? 0) > 0) {
+            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+            counts[k1] -= 1;
+            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+            counts[k2] -= 1;
+            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+            counts[k3] -= 1;
+            const tails = decomposeClosedMentsu(counts, requiredCount - 1);
+            const shuntsu = { type: "Shuntsu", hais: [k1, k2, k3] };
+            for (const tail of tails) {
+                results.push([shuntsu, ...tail]);
+            }
+            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+            counts[k1] += 1;
+            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+            counts[k2] += 1;
+            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+            counts[k3] += 1; // バックトラック
+        }
+    }
+    return results;
+}

package/dist/features/yaku/types.d.ts

@@ -0,0 +1,121 @@
+import type { HaiKindId, Kazehai, Shuntsu, Koutsu, Kantsu, Toitsu, Mentsu, CompletedMentsu } from "../../types";
+export type { Kazehai, Shuntsu, Koutsu, Kantsu, Toitsu, Mentsu };
+/**
+ * 役牌 (Yakuhai)
+ *
+ * 構造的に成立する三元牌。
+ * ※場風・自風は状況役（Bakaze, Jikaze）として別途定義するためここには含めない。
+ */
+export type Yakuhai = "Haku" | "Hatsu" | "Chun";
+/**
+ * 手牌役 (TehaiYaku)
+ *
+ * 手牌役（手牌の構成のみで成立する役）の識別子。
+ * 偶然役（嶺上開花など）や状況役（場風、自風、立直など）は含まない。
+ */
+export type TehaiYaku = "Tanyao" | "Pinfu" | "Iipeikou" | Yakuhai | "SanshokuDoujun" | "Ikkitsuukan" | "Honchan" | "Chiitoitsu" | "Toitoi" | "Sanankou" | "Sankantsu" | "SanshokuDoukou" | "Honroutou" | "Shousangen" | "Honitsu" | "Junchan" | "Ryanpeikou" | "Chinitsu" | "KokushiMusou" | "Suuankou" | "Daisangen" | "Shousuushii" | "Daisuushii" | "Tsuuiisou" | "Chinroutou" | "Ryuuiisou" | "ChuurenPoutou" | "Suukantsu" | "MenzenTsumo";
+/**
+ * 役の翻数 (Hansu)
+ *
+ * 1, 2, 3, 5(流し満貫/清一色喰い下がり), 6(清一色), 13(役満), 26(ダブル役満)
+ */
+export type Hansu = 1 | 2 | 3 | 5 | 6 | 13 | 26;
+export interface MentsuHouraStructure {
+    readonly type: "Mentsu";
+    readonly fourMentsu: readonly [
+        CompletedMentsu,
+        CompletedMentsu,
+        CompletedMentsu,
+        CompletedMentsu
+    ];
+    readonly jantou: Toitsu;
+}
+export interface ChiitoitsuHouraStructure {
+    readonly type: "Chiitoitsu";
+    readonly pairs: readonly [
+        Toitsu,
+        Toitsu,
+        Toitsu,
+        Toitsu,
+        Toitsu,
+        Toitsu,
+        Toitsu
+    ];
+}
+export interface KokushiHouraStructure {
+    readonly type: "Kokushi";
+    /** 13種類の么九牌（重複なし） */
+    readonly yaochu: readonly HaiKindId[];
+    /** 雀頭となる牌の種類 */
+    readonly jantou: HaiKindId;
+}
+export type HouraStructure = MentsuHouraStructure | ChiitoitsuHouraStructure | KokushiHouraStructure;
+/**
+ * 役の翻数定義
+ */
+export interface YakuHanConfig {
+    /** 門前時の翻数 */
+    readonly closed: Hansu;
+    /**
+     * 鳴きあり時の翻数 (0なら不成立)
+     *
+     * @remarks
+     * この値が 0 の場合、その役は**門前限定（Menzen-only）**であることを意味します。
+     * 役判定ロジックにおいては、この値が 0 でかつ手牌が副露されている場合、
+     * 役の条件を満たしていても不成立とみなされます。
+     */
+    readonly open: Hansu | 0;
+}
+/**
+ * 役ID (YakuName)
+ *
+ * 全ての役の識別子ユニオン。
+ */
+export type YakuName = TehaiYaku;
+/**
+ * 役判定結果 (YakuResult)
+ *
+ * 成立した役と、その翻数のペアのリスト。
+ * 役が一つも成立しない場合は空配列となる。
+ */
+export type YakuResult = readonly [YakuName, Hansu][];
+export interface HouraContext {
+    /** 手牌が門前かどうか（暗槓が含まれていても門前扱い） */
+    readonly isMenzen: boolean;
+    /** 和了牌（平和判定などに必要）。省略時は判定不能な役がある */
+    readonly agariHai: HaiKindId;
+    /** 場風牌 */
+    readonly bakaze?: Kazehai | undefined;
+    /** 自風牌 */
+    readonly jikaze?: Kazehai | undefined;
+    /** ツモ和了かどうか（暗刻系役の判定などに使用） */
+    readonly isTsumo?: boolean | undefined;
+    /**
+     * ドラ表示牌 (表ドラ) のリスト
+     */
+    readonly doraMarkers: readonly HaiKindId[];
+    /**
+     * 裏ドラ表示牌のリスト (リーチ時のみ有効)
+     */
+    readonly uraDoraMarkers?: readonly HaiKindId[];
+}
+export interface Yaku {
+    readonly name: YakuName;
+    /** 翻数 (喰い下がり考慮) */
+    readonly han: {
+        readonly open: Hansu | 0;
+        readonly closed: Hansu;
+    };
+}
+/**
+ * 役の成立判定関数
+ * @param hand 分解された手牌構造
+ * @param context 判定コンテキスト
+ * @returns 成立回数 (0なら不成立、役牌などで複数成立しうる)
+ */
+export type YakuCheck = (hand: HouraStructure, context: HouraContext) => number;
+export interface YakuDefinition {
+    readonly yaku: Yaku;
+    readonly isSatisfied: (hand: HouraStructure, context: HouraContext) => boolean;
+    readonly getHansu: (hand: HouraStructure, context: HouraContext) => Hansu | 0;
+}

package/dist/features/yaku/types.js

@@ -0,0 +1 @@
+export {};

package/dist/features/yaku/utils.d.ts

@@ -0,0 +1,19 @@
+import { type HaiKindId, type Kazehai, type Tehai14 } from "../../types";
+/**
+ * 手牌が門前（メンゼン）かどうかを判定する。
+ *
+ * 門前の定義:
+ * - 明刻、明順、明槓などの「晒し」が含まれていないこと。
+ * - 暗槓は門前として扱う。
+ *
+ * @param tehai 判定対象の手牌
+ * @returns 門前であれば true、そうでなければ false
+ */
+export declare function isMenzen(tehai: Tehai14): boolean;
+/**
+ * 指定された牌が風牌かどうかを判定する。
+ *
+ * @param id 判定対象の牌種ID
+ * @returns 風牌（東・南・西・北）であれば true
+ */
+export declare function isKazehai(id: HaiKindId): id is Kazehai;

package/dist/features/yaku/utils.js

@@ -0,0 +1,34 @@
+import { HaiKind, } from "../../types";
+/**
+ * 手牌が門前（メンゼン）かどうかを判定する。
+ *
+ * 門前の定義:
+ * - 明刻、明順、明槓などの「晒し」が含まれていないこと。
+ * - 暗槓は門前として扱う。
+ *
+ * @param tehai 判定対象の手牌
+ * @returns 門前であれば true、そうでなければ false
+ */
+export function isMenzen(tehai) {
+    // exposed（副露ブロック）が空なら門前
+    if (tehai.exposed.length === 0) {
+        return true;
+    }
+    // 副露ブロックがある場合、全てが「暗槓」であれば門前とみなす
+    // 暗槓の定義: typeが"Kantsu"かつfuro情報を持たない（現状のデータ構造における定義）
+    return tehai.exposed.every((m) => {
+        return m.type === "Kantsu" && !m.furo;
+    });
+}
+/**
+ * 指定された牌が風牌かどうかを判定する。
+ *
+ * @param id 判定対象の牌種ID
+ * @returns 風牌（東・南・西・北）であれば true
+ */
+export function isKazehai(id) {
+    return (id === HaiKind.Ton ||
+        id === HaiKind.Nan ||
+        id === HaiKind.Sha ||
+        id === HaiKind.Pei);
+}

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Riichi Mahjong Library
+ */
+export { HaiKind, Tacha, FuroType, MentsuType, HaiType } from "./types";
+export type { HaiId, HaiKindId, Furo, Shuntsu, Koutsu, Kantsu, CompletedMentsu, Tehai, Tehai13, Tehai14, Mentsu, IncompletedMentsu, Kazehai, Fu, } from "./types";
+export type { YakuResult, YakuName, Hansu } from "./features/yaku";
+export type { ScoreResult, ScoreCalculationConfig, Payment, Ron, KoTsumo, OyaTsumo, } from "./features/score/types";
+export { MahjongError, ShoushaiError, TahaiError, MahjongArgumentError, DuplicatedHaiIdError, InvalidHaiQuantityError, ChomboError, NoYakuError, } from "./errors";
+export { haiIdToKindId, kindIdToHaiType, haiKindToNumber, isSuupai, isYaochu, YAOCHU_KIND_IDS, } from "./core/hai";
+export { validateTehai, isTehai13, isTehai14 } from "./core/tehai";
+export { isValidShuntsu, isValidKoutsu, isValidKantsu, isValidToitsu, isValidTatsu, } from "./core/mentsu";
+export { getDoraNext, countDora } from "./core/dora";
+export { classifyMachi } from "./core/machi";
+export type { MachiType } from "./core/machi";
+export { calculateShanten } from "./features/shanten";
+export { getUkeire } from "./features/machi";
+export { detectYaku } from "./features/yaku";
+export { isMenzen, isKazehai } from "./features/yaku/utils";
+export { parseMspz, parseExtendedMspz } from "./features/parser";
+export { isMspz, isExtendedMspz } from "./features/parser/mspz";
+export { calculateScoreForTehai, getPaymentTotal } from "./features/score";

package/dist/index.js

@@ -0,0 +1,53 @@
+/**
+ * Riichi Mahjong Library
+ */
+// =============================================================================
+// Types & Constants
+// =============================================================================
+export { HaiKind, Tacha, FuroType, MentsuType, HaiType } from "./types";
+// =============================================================================
+// Errors
+// =============================================================================
+export { MahjongError, ShoushaiError, TahaiError, MahjongArgumentError, DuplicatedHaiIdError, InvalidHaiQuantityError, ChomboError, NoYakuError, } from "./errors";
+// =============================================================================
+// Core - Hai (Tile) Utilities
+// =============================================================================
+export { haiIdToKindId, kindIdToHaiType, haiKindToNumber, isSuupai, isYaochu, YAOCHU_KIND_IDS, } from "./core/hai";
+// =============================================================================
+// Core - Tehai (Hand) Validation
+// =============================================================================
+export { validateTehai, isTehai13, isTehai14 } from "./core/tehai";
+// =============================================================================
+// Core - Mentsu (Meld) Validation
+// =============================================================================
+export { isValidShuntsu, isValidKoutsu, isValidKantsu, isValidToitsu, isValidTatsu, } from "./core/mentsu";
+// =============================================================================
+// Core - Dora
+// =============================================================================
+export { getDoraNext, countDora } from "./core/dora";
+// =============================================================================
+// Core - Machi (Wait) Classification
+// =============================================================================
+export { classifyMachi } from "./core/machi";
+// =============================================================================
+// Features - Shanten
+// =============================================================================
+export { calculateShanten } from "./features/shanten";
+// =============================================================================
+// Features - Machi
+// =============================================================================
+export { getUkeire } from "./features/machi";
+// =============================================================================
+// Features - Yaku
+// =============================================================================
+export { detectYaku } from "./features/yaku";
+export { isMenzen, isKazehai } from "./features/yaku/utils";
+// =============================================================================
+// Features - Parser
+// =============================================================================
+export { parseMspz, parseExtendedMspz } from "./features/parser";
+export { isMspz, isExtendedMspz } from "./features/parser/mspz";
+// =============================================================================
+// Features - Score
+// =============================================================================
+export { calculateScoreForTehai, getPaymentTotal } from "./features/score";