@pai-forge/riichi-mahjong 0.1.0

package/README.md

@@ -0,0 +1,58 @@
+# Riichi Mahjong Library
+
+リーチ麻雀のロジック（シャンテン数計算、点数計算など）を提供するTypeScriptライブラリです。
+
+> [!NOTE]
+> This package is **Pure ESM**. Please use `import` (not `require`) to use this library.
+<br>
+本パッケージは **Pure ESM** です。利用する際は `require` ではなく `import` を使用してください。
+
+## 前提条件 (Prerequisites)
+
+開発やテスト実行には以下のツールが必要です。
+
+- **Node.js**: v20.0.0 以上
+- **Docker**: 受け入れテスト（リファレンス実装との比較）を実行する場合は必要
+
+## セットアップ (Setup)
+
+依存パッケージをインストールします。
+
+```bash
+npm install @pai-forge/riichi-mahjong
+```
+
+## テストの実行 (Running Tests)
+
+### ユニットテスト (Unit Tests)
+
+`src` ディレクトリ内の主要なロジックに対するユニットテストを実行します。
+
+```bash
+npm test
+```
+または
+```bash
+npx vitest src
+```
+
+### 受け入れテスト (Acceptance Tests)
+
+Pythonの [`mahjong`](https://github.com/MahjongRepository/mahjong) ライブラリをリファレンス実装として使用し、計算結果の相互検証を行います。
+実行時に自動的に検証用のDockerイメージ (`riichi-mahjong-verifier`) がビルドされます。
+
+```bash
+npx vitest tests/acceptance
+```
+
+特定のテストファイルのみを実行する場合:
+
+```bash
+npx vitest tests/acceptance/shanten.test.ts
+```
+
+## その他のコマンド (Other Commands)
+
+- **ビルド**: `npm run build`
+- **リント**: `npm run lint`
+- **フォーマット**: `npm run format`

package/dist/core/dora.d.ts

@@ -0,0 +1,14 @@
+import { type HaiKindId, type Tehai } from "../types";
+/**
+ * ドラ表示牌から次の牌（ドラ）を求める
+ * @param indicator ドラ表示牌のID (HaiKindId)
+ * @returns ドラ牌のID (HaiKindId)
+ */
+export declare function getDoraNext(indicator: HaiKindId): HaiKindId;
+/**
+ * 手牌に含まれるドラの数を数える
+ * @param tehai 手牌
+ * @param indicators ドラ表示牌のリスト
+ * @returns ドラの総数
+ */
+export declare function countDora(tehai: Tehai, indicators: readonly HaiKindId[]): number;

package/dist/core/dora.js

@@ -0,0 +1,71 @@
+import { HaiKind } from "../types";
+import { kindIdToHaiType } from "./hai";
+import { HaiType } from "../types";
+import { asHaiKindId } from "../utils/assertions";
+/**
+ * ドラ表示牌から次の牌（ドラ）を求める
+ * @param indicator ドラ表示牌のID (HaiKindId)
+ * @returns ドラ牌のID (HaiKindId)
+ */
+export function getDoraNext(indicator) {
+    const type = kindIdToHaiType(indicator);
+    if (type === HaiType.Manzu) {
+        if (indicator === HaiKind.ManZu9)
+            return HaiKind.ManZu1;
+        return asHaiKindId(indicator + 1);
+    }
+    if (type === HaiType.Pinzu) {
+        if (indicator === HaiKind.PinZu9)
+            return HaiKind.PinZu1;
+        return asHaiKindId(indicator + 1);
+    }
+    if (type === HaiType.Souzu) {
+        if (indicator === HaiKind.SouZu9)
+            return HaiKind.SouZu1;
+        return asHaiKindId(indicator + 1);
+    }
+    // Jihai
+    // Ton(27) -> Nan(28) -> Sha(29) -> Pei(30) -> Ton(27)
+    if (indicator === HaiKind.Pei)
+        return HaiKind.Ton;
+    if (indicator >= HaiKind.Ton && indicator < HaiKind.Pei) {
+        return asHaiKindId(indicator + 1);
+    }
+    // Haku(31) -> Hatsu(32) -> Chun(33) -> Haku(31)
+    if (indicator === HaiKind.Chun)
+        return HaiKind.Haku;
+    if (indicator >= HaiKind.Haku && indicator < HaiKind.Chun) {
+        return asHaiKindId(indicator + 1);
+    }
+    // Should not happen for valid HaiKindId
+    return indicator;
+}
+/**
+ * 手牌に含まれるドラの数を数える
+ * @param tehai 手牌
+ * @param indicators ドラ表示牌のリスト
+ * @returns ドラの総数
+ */
+export function countDora(tehai, indicators) {
+    let count = 0;
+    // Calculate actual dora hinds
+    const doraHais = indicators.map(getDoraNext);
+    // Count in closed hand
+    for (const hai of tehai.closed) {
+        for (const dora of doraHais) {
+            if (hai === dora)
+                count++;
+        }
+    }
+    // Count in exposed mentsu
+    for (const mentsu of tehai.exposed) {
+        for (const hai of mentsu.hais) {
+            for (const dora of doraHais) {
+                if (hai === dora)
+                    count++;
+            }
+        }
+    }
+    // TODO: Add Akadora counting logic here
+    return count;
+}

package/dist/core/hai.d.ts

@@ -0,0 +1,30 @@
+import { type HaiId, type HaiKindId, HaiType } from "../types";
+/**
+ * 牌種IDから牌種タイプを取得する
+ */
+export declare function kindIdToHaiType(kind: HaiKindId): HaiType;
+/**
+ * 物理牌IDから牌種IDを取得する
+ * 0-35: 萬子 (36枚 = 9種 * 4枚) -> 0-8
+ * 36-71: 筒子 (36枚) -> 9-17
+ * 72-107: 索子 (36枚) -> 18-26
+ * 108-135: 字牌 (28枚 = 7種 * 4枚) -> 27-33
+ */
+export declare function haiIdToKindId(id: HaiId): HaiKindId;
+/**
+ * 牌種IDから数値(1-9)を取得する
+ * 字牌の場合は undefined を返す
+ */
+export declare function haiKindToNumber(kind: HaiKindId): number | undefined;
+/**
+ * 数牌かどうかを判定する
+ */
+export declare function isSuupai(kind: HaiKindId): boolean;
+/**
+ * 么九牌（1,9,字牌）の牌種IDセット
+ */
+export declare const YAOCHU_KIND_IDS: readonly [0, 8, 9, 17, 18, 26, 27, 28, 29, 30, 31, 32, 33];
+/**
+ * 么九牌（1,9,字牌）かどうかを判定する
+ */
+export declare function isYaochu(kind: HaiKindId): boolean;

package/dist/core/hai.js

@@ -0,0 +1,78 @@
+import { HaiKind, HaiType } from "../types";
+import { asHaiKindId } from "../utils/assertions";
+/**
+ * 牌種IDから牌種タイプを取得する
+ */
+export function kindIdToHaiType(kind) {
+    if (kind >= HaiKind.ManZu1 && kind <= HaiKind.ManZu9) {
+        return HaiType.Manzu;
+    }
+    if (kind >= HaiKind.PinZu1 && kind <= HaiKind.PinZu9) {
+        return HaiType.Pinzu;
+    }
+    if (kind >= HaiKind.SouZu1 && kind <= HaiKind.SouZu9) {
+        return HaiType.Souzu;
+    }
+    return HaiType.Jihai;
+}
+/**
+ * 物理牌IDから牌種IDを取得する
+ * 0-35: 萬子 (36枚 = 9種 * 4枚) -> 0-8
+ * 36-71: 筒子 (36枚) -> 9-17
+ * 72-107: 索子 (36枚) -> 18-26
+ * 108-135: 字牌 (28枚 = 7種 * 4枚) -> 27-33
+ */
+export function haiIdToKindId(id) {
+    if (id < 36)
+        return asHaiKindId(Math.floor(id / 4));
+    if (id < 72)
+        return asHaiKindId(Math.floor((id - 36) / 4) + 9);
+    if (id < 108)
+        return asHaiKindId(Math.floor((id - 72) / 4) + 18);
+    return asHaiKindId(Math.floor((id - 108) / 4) + 27);
+}
+/**
+ * 牌種IDから数値(1-9)を取得する
+ * 字牌の場合は undefined を返す
+ */
+export function haiKindToNumber(kind) {
+    const type = kindIdToHaiType(kind);
+    if (type === HaiType.Jihai)
+        return undefined;
+    if (type === HaiType.Manzu)
+        return kind - HaiKind.ManZu1 + 1;
+    if (type === HaiType.Pinzu)
+        return kind - HaiKind.PinZu1 + 1;
+    // if (kindIdToHaiType(kind) === HaiType.Souzu)
+    return kind - HaiKind.SouZu1 + 1;
+}
+/**
+ * 数牌かどうかを判定する
+ */
+export function isSuupai(kind) {
+    return kindIdToHaiType(kind) !== HaiType.Jihai;
+}
+/**
+ * 么九牌（1,9,字牌）の牌種IDセット
+ */
+export const YAOCHU_KIND_IDS = [
+    HaiKind.ManZu1,
+    HaiKind.ManZu9,
+    HaiKind.PinZu1,
+    HaiKind.PinZu9,
+    HaiKind.SouZu1,
+    HaiKind.SouZu9,
+    HaiKind.Ton,
+    HaiKind.Nan,
+    HaiKind.Sha,
+    HaiKind.Pei,
+    HaiKind.Haku,
+    HaiKind.Hatsu,
+    HaiKind.Chun,
+];
+/**
+ * 么九牌（1,9,字牌）かどうかを判定する
+ */
+export function isYaochu(kind) {
+    return YAOCHU_KIND_IDS.some((k) => k === kind);
+}

package/dist/core/machi.d.ts

@@ -0,0 +1,11 @@
+import type { HaiKindId } from "../types";
+import type { HouraStructure } from "../features/yaku/types";
+/** 待ちの形 */
+export type MachiType = "Tanki" | "Shanpon" | "Ryanmen" | "Kanchan" | "Penchan";
+/**
+ * 手牌構造と和了牌から待ちの形を判定する
+ * @param hand 分解された手牌構造
+ * @param agariHai 和了牌
+ * @returns 待ちの形（判定できない、または Shanpon などの場合は undefined）
+ */
+export declare function classifyMachi(hand: HouraStructure, agariHai: HaiKindId): MachiType | undefined;

package/dist/core/machi.js

@@ -0,0 +1,58 @@
+/**
+ * 手牌構造と和了牌から待ちの形を判定する
+ * @param hand 分解された手牌構造
+ * @param agariHai 和了牌
+ * @returns 待ちの形（判定できない、または Shanpon などの場合は undefined）
+ */
+export function classifyMachi(hand, agariHai) {
+    if (hand.type !== "Mentsu")
+        return undefined;
+    // 1. 雀頭での和了（単騎待ち）
+    if (hand.jantou.hais.includes(agariHai)) {
+        return "Tanki";
+    }
+    // 2. 順子・刻子・槓子での和了
+    for (const mentsu of hand.fourMentsu) {
+        if (mentsu.type === "Shuntsu") {
+            const machi = classifyShuntsuWait(mentsu, agariHai);
+            if (machi)
+                return machi;
+        }
+        else {
+            // 3. 刻子・槓子での和了（双碰待ち）
+            // 刻子の一部が和了牌＝シャボ待ちで和了
+            if (mentsu.hais.includes(agariHai)) {
+                return "Shanpon";
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * 順子における待ちの形を判定する（内部ヘルパー）
+ */
+function classifyShuntsuWait(shuntsu, agariHai) {
+    const { hais } = shuntsu;
+    if (!hais.includes(agariHai))
+        return undefined;
+    const [a, b, c] = hais; // 順子はソートされている前提
+    if (agariHai === a) {
+        // [Agari, b, c]
+        const valC = c % 9;
+        if (valC === 8)
+            return "Penchan";
+        return "Ryanmen";
+    }
+    if (agariHai === c) {
+        // [a, b, Agari]
+        const valA = a % 9;
+        if (valA === 0)
+            return "Penchan";
+        return "Ryanmen";
+    }
+    if (agariHai === b) {
+        // [a, Agari, c]
+        return "Kanchan";
+    }
+    return undefined;
+}

package/dist/core/mentsu.d.ts

@@ -0,0 +1,26 @@
+import type { HaiKindId } from "../types";
+/**
+ * 順子かどうかを検証する
+
+ */
+export declare function isValidShuntsu(kindIds: readonly HaiKindId[]): boolean;
+/**
+ * 刻子かどうかを検証する
+
+ */
+export declare function isValidKoutsu(kindIds: readonly HaiKindId[]): boolean;
+/**
+ * 槓子かどうかを検証する
+
+ */
+export declare function isValidKantsu(kindIds: readonly HaiKindId[]): boolean;
+/**
+ * 対子かどうかを検証する
+
+ */
+export declare function isValidToitsu(kindIds: readonly HaiKindId[]): boolean;
+/**
+ * 塔子かどうかを検証する
+
+ */
+export declare function isValidTatsu(kindIds: readonly HaiKindId[]): boolean;

package/dist/core/mentsu.js

@@ -0,0 +1,87 @@
+import { haiKindToNumber, isSuupai, kindIdToHaiType } from "./hai";
+import { isTuple2, isTuple3, isTuple4 } from "../utils/assertions";
+// バリデーションロジックは「HaiKindId の配列」に対して行うものと定義する。
+// HaiId を持つ Mentsu を検証したい場合は、呼び出し側で KindId に変換してから渡す必要がある。
+// ただし、利便性のために `convertHaiIdToKindId` ヘルパーを export する。
+/**
+ * 順子かどうかを検証する
+
+ */
+export function isValidShuntsu(kindIds) {
+    if (!isTuple3(kindIds))
+        return false;
+    const [a, b, c] = kindIds;
+    if (!isSuupai(a) || !isSuupai(b) || !isSuupai(c))
+        return false;
+    const typeA = kindIdToHaiType(a);
+    const typeB = kindIdToHaiType(b);
+    const typeC = kindIdToHaiType(c);
+    if (typeA !== typeB || typeA !== typeC)
+        return false;
+    const numA = haiKindToNumber(a);
+    const numB = haiKindToNumber(b);
+    const numC = haiKindToNumber(c);
+    if (numA === undefined || numB === undefined || numC === undefined)
+        return false;
+    // ソートして連続性をチェック
+    const sorted = [numA, numB, numC].sort((x, y) => x - y);
+    // Safe to access since we just created it with 3 elements
+    // But strict check might complain about index access on array
+    if (!isTuple3(sorted))
+        return false; // Should be always true
+    return sorted[0] + 1 === sorted[1] && sorted[1] + 1 === sorted[2];
+}
+/**
+ * 刻子かどうかを検証する
+
+ */
+export function isValidKoutsu(kindIds) {
+    if (!isTuple3(kindIds))
+        return false;
+    const [a, b, c] = kindIds;
+    return a === b && b === c;
+}
+/**
+ * 槓子かどうかを検証する
+
+ */
+export function isValidKantsu(kindIds) {
+    if (!isTuple4(kindIds))
+        return false;
+    const [a, b, c, d] = kindIds;
+    return a === b && b === c && c === d;
+}
+/**
+ * 対子かどうかを検証する
+
+ */
+export function isValidToitsu(kindIds) {
+    if (!isTuple2(kindIds))
+        return false;
+    const [a, b] = kindIds;
+    return a === b;
+}
+/**
+ * 塔子かどうかを検証する
+
+ */
+export function isValidTatsu(kindIds) {
+    if (!isTuple2(kindIds))
+        return false;
+    const [a, b] = kindIds;
+    // 数牌でなければならない
+    if (!isSuupai(a) || !isSuupai(b))
+        return false;
+    // 同じ種類でなければならない
+    const typeA = kindIdToHaiType(a);
+    const typeB = kindIdToHaiType(b);
+    if (typeA !== typeB)
+        return false;
+    const numA = haiKindToNumber(a);
+    const numB = haiKindToNumber(b);
+    if (numA === undefined || numB === undefined)
+        return false;
+    const diff = Math.abs(numA - numB);
+    // 差が1 (ペンチャン/リャンメン) または 2 (カンチャン) ならOK
+    return diff === 1 || diff === 2;
+}

package/dist/core/tehai.d.ts

@@ -0,0 +1,38 @@
+import type { HaiId, HaiKindDistribution, HaiKindId, Tehai, Tehai13, Tehai14 } from "../types";
+/**
+ * 手牌の有効枚数を計算します。
+ * 副露（槓子含む）は一律3枚として計算します。
+ */
+export declare function calculateTehaiCount<T extends HaiKindId | HaiId>(tehai: Tehai<T>): number;
+/**
+ * 牌種ごとの枚数をカウントします。
+ */
+export declare function countHaiKind(hais: readonly HaiKindId[]): HaiKindDistribution;
+/**
+ * 手牌がTehai13（有効枚数13枚）であるか検証します。
+ * @throws {ShoushaiError} 枚数が不足している場合
+ * @throws {TahaiError} 枚数が超過している場合
+ */
+export declare function validateTehai13<T extends HaiKindId | HaiId>(tehai: Tehai<T>): void;
+/**
+ * 手牌がTehai14（有効枚数14枚）であるか検証します。
+ * @throws {ShoushaiError} 枚数が不足している場合
+ * @throws {TahaiError} 枚数が超過している場合
+ */
+export declare function validateTehai14<T extends HaiKindId | HaiId>(tehai: Tehai<T>): void;
+/**
+ * 手牌がTehai13またはTehai14（有効枚数が13または14枚）であるか検証します。
+ * シャンテン計算や待ち判定など、13枚/14枚の区別なく手牌として扱いたい場合に使用します。
+ *
+ * @throws {ShoushaiError} 枚数が不足している場合 (< 13)
+ * @throws {TahaiError} 枚数が超過している場合 (> 14)
+ */
+export declare function validateTehai<T extends HaiKindId | HaiId>(tehai: Tehai<T>): void;
+/**
+ * Type Guard for Tehai13
+ */
+export declare function isTehai13<T extends HaiKindId | HaiId>(tehai: Tehai<T>): tehai is Tehai13<T>;
+/**
+ * Type Guard for Tehai14
+ */
+export declare function isTehai14<T extends HaiKindId | HaiId>(tehai: Tehai<T>): tehai is Tehai14<T>;

package/dist/core/tehai.js

@@ -0,0 +1,87 @@
+import { ShoushaiError, TahaiError } from "../errors";
+/**
+ * 手牌の有効枚数を計算します。
+ * 副露（槓子含む）は一律3枚として計算します。
+ */
+export function calculateTehaiCount(tehai) {
+    return tehai.closed.length + tehai.exposed.length * 3;
+}
+/**
+ * 牌種ごとの枚数をカウントします。
+ */
+export function countHaiKind(hais) {
+    const counts = Array.from({ length: 34 }, () => 0);
+    for (const hai of hais) {
+        counts[hai] = (counts[hai] ?? 0) + 1;
+    }
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+    return counts;
+}
+/**
+ * 手牌がTehai13（有効枚数13枚）であるか検証します。
+ * @throws {ShoushaiError} 枚数が不足している場合
+ * @throws {TahaiError} 枚数が超過している場合
+ */
+export function validateTehai13(tehai) {
+    const count = calculateTehaiCount(tehai);
+    if (count < 13) {
+        throw new ShoushaiError();
+    }
+    if (count > 13) {
+        throw new TahaiError();
+    }
+}
+/**
+ * 手牌がTehai14（有効枚数14枚）であるか検証します。
+ * @throws {ShoushaiError} 枚数が不足している場合
+ * @throws {TahaiError} 枚数が超過している場合
+ */
+export function validateTehai14(tehai) {
+    const count = calculateTehaiCount(tehai);
+    if (count < 14) {
+        throw new ShoushaiError();
+    }
+    if (count > 14) {
+        throw new TahaiError();
+    }
+}
+/**
+ * 手牌がTehai13またはTehai14（有効枚数が13または14枚）であるか検証します。
+ * シャンテン計算や待ち判定など、13枚/14枚の区別なく手牌として扱いたい場合に使用します。
+ *
+ * @throws {ShoushaiError} 枚数が不足している場合 (< 13)
+ * @throws {TahaiError} 枚数が超過している場合 (> 14)
+ */
+export function validateTehai(tehai) {
+    const count = calculateTehaiCount(tehai);
+    if (count < 13) {
+        throw new ShoushaiError();
+    }
+    if (count > 14) {
+        throw new TahaiError();
+    }
+}
+/**
+ * Type Guard for Tehai13
+ */
+export function isTehai13(tehai) {
+    try {
+        validateTehai13(tehai);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Type Guard for Tehai14
+ */
+export function isTehai14(tehai) {
+    try {
+        validateTehai14(tehai);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,40 @@
+/**
+ * riichi-mahjong ライブラリの基本エラークラス
+ * 全てのカスタムエラーはこのクラスを継承します。
+ */
+export declare class MahjongError extends Error {
+    /**
+     *
+     */
+    constructor(message: string);
+}
+/**
+ * ツモれなかった場合のエラー (少牌)
+ * 手牌が規定枚数（13枚）より少ない場合にスローされます。
+ */
+export declare class ShoushaiError extends MahjongError {
+    /**
+     *
+     */
+    constructor(message?: string);
+}
+/**
+ * 切り忘れの場合のエラー (多牌)
+ * 手牌が規定枚数（13枚）より多い場合にスローされます。
+ */
+export declare class TahaiError extends MahjongError {
+    /**
+     *
+     */
+    constructor(message?: string);
+}
+/**
+ * 引数が不正な場合のエラー
+ * 必要なパラメータが不足している、または不正な値の場合にスローされます。
+ */
+export declare class MahjongArgumentError extends MahjongError {
+    /**
+     *
+     */
+    constructor(message: string);
+}

package/dist/errors.js

@@ -0,0 +1,58 @@
+/**
+ * riichi-mahjong ライブラリの基本エラークラス
+ * 全てのカスタムエラーはこのクラスを継承します。
+ */
+export class MahjongError extends Error {
+    /**
+     *
+     */
+    constructor(message) {
+        super(message);
+        this.name = "MahjongError";
+        // TypeScriptでカスタムエラーを正しく動作させるためのハック
+        // TypeScriptでカスタムエラーを正しく動作させるためのハック
+        Object.setPrototypeOf(this, MahjongError.prototype);
+    }
+}
+/**
+ * ツモれなかった場合のエラー (少牌)
+ * 手牌が規定枚数（13枚）より少ない場合にスローされます。
+ */
+export class ShoushaiError extends MahjongError {
+    /**
+     *
+     */
+    constructor(message = "手牌が規定枚数（13枚）より少ないです。") {
+        super(message);
+        this.name = "ShoushaiError";
+        Object.setPrototypeOf(this, ShoushaiError.prototype);
+    }
+}
+/**
+ * 切り忘れの場合のエラー (多牌)
+ * 手牌が規定枚数（13枚）より多い場合にスローされます。
+ */
+export class TahaiError extends MahjongError {
+    /**
+     *
+     */
+    constructor(message = "手牌が規定枚数（13枚）より多いです。") {
+        super(message);
+        this.name = "TahaiError";
+        Object.setPrototypeOf(this, TahaiError.prototype);
+    }
+}
+/**
+ * 引数が不正な場合のエラー
+ * 必要なパラメータが不足している、または不正な値の場合にスローされます。
+ */
+export class MahjongArgumentError extends MahjongError {
+    /**
+     *
+     */
+    constructor(message) {
+        super(message);
+        this.name = "MahjongArgumentError";
+        Object.setPrototypeOf(this, MahjongArgumentError.prototype);
+    }
+}

package/dist/features/machi/index.d.ts

@@ -0,0 +1,9 @@
+import type { HaiKindId, Tehai13 } from "../../types";
+/**
+ * 手牌の受け入れ（有効牌）を計算する。
+ * 今回は面子手のみを対象とし、七対子や国士無双は考慮しない。
+ *
+ * @param tehai 手牌 (13枚)
+ * @returns シャンテン数を進める牌のリスト
+ */
+export declare function getUkeire(tehai: Tehai13): HaiKindId[];