@pai-forge/riichi-mahjong 0.1.0

package/dist/features/points/index.js

@@ -0,0 +1,174 @@
+import { HaiKind } from "../../types";
+import { countDora } from "../../core/dora";
+import { getHouraStructures } from "../yaku/lib/structures";
+import { ALL_YAKU_DEFINITIONS } from "../yaku/lib/definitions";
+import { calculateFu } from "./lib/fu";
+import { isMenzen } from "../yaku/utils";
+import { BASE_POINT_LIMIT, HAN_BAIMAN, HAN_HANEMAN, HAN_MANGAN, HAN_SANBAIMAN, HAN_YAKUMAN, SCORE_BASE_BAIMAN, SCORE_BASE_HANEMAN, SCORE_BASE_MANGAN, SCORE_BASE_SANBAIMAN, SCORE_BASE_YAKUMAN, } from "./constants";
+/**
+ * 100点単位で切り上げる
+ */
+function ceil100(points) {
+    return Math.ceil(points / 100) * 100;
+}
+/**
+ * 手牌とコンテキストから点数を計算する（公開API）
+ *
+ * 手牌の構造解析を行い、最も高点となる解釈を採用して点数を返します。
+ *
+ * @param tehai 手牌 (14枚)
+ * @param config 点数計算の設定 (場風、自風、ドラなど)
+ * @returns 点数計算結果
+ */
+export function calculateScore(tehai, config) {
+    const menzen = isMenzen(tehai);
+    const isOya = config.jikaze === HaiKind.Ton;
+    const context = {
+        isMenzen: menzen,
+        agariHai: config.agariHai,
+        bakaze: config.bakaze,
+        jikaze: config.jikaze,
+        isTsumo: config.isTsumo,
+        isOya: isOya,
+        doraMarkers: config.doraMarkers,
+        ...(config.uraDoraMarkers ? { uraDoraMarkers: config.uraDoraMarkers } : {}),
+    };
+    const structuralInterpretations = getHouraStructures(tehai);
+    let bestResult = null;
+    let maxTotalPoints = -1;
+    for (const hand of structuralInterpretations) {
+        // 1. 役の判定
+        let yakuHansu = 0;
+        let isPinfu = false;
+        for (const definition of ALL_YAKU_DEFINITIONS) {
+            if (definition.isSatisfied(hand, context)) {
+                const h = definition.getHansu(hand, context);
+                if (h > 0) {
+                    yakuHansu += h;
+                    if (definition.yaku.name === "Pinfu") {
+                        isPinfu = true;
+                    }
+                }
+            }
+        }
+        // 役がない場合はこの構造は不成立
+        if (yakuHansu === 0)
+            continue;
+        // 2. 符の計算
+        const fuResult = calculateFu(hand, context, isPinfu);
+        // 3. ドラの計算
+        // context.doraMarkers にドラ表示牌が入っている前提
+        const dora = countDora(tehai, context.doraMarkers);
+        // 4. 点数計算 (基本計算)
+        const result = calculateBasicScore(yakuHansu, fuResult, dora, context);
+        if (result.points.total > maxTotalPoints) {
+            maxTotalPoints = result.points.total;
+            bestResult = result;
+        }
+    }
+    if (!bestResult) {
+        throw new Error("役が成立していません (No Yaku found)");
+    }
+    return bestResult;
+}
+/**
+ * 基本的な点数計算ロジック (内部用・テスト用)
+ */
+export function calculateBasicScore(yakuHansu, fuResult, dora, context) {
+    const totalHan = yakuHansu + dora;
+    const fu = fuResult.total;
+    let basePoints = fu * Math.pow(2, 2 + totalHan);
+    let level = "Normal";
+    // 満貫以上の判定
+    // 5飜以上 は満貫確定
+    // 4飜以下でも 基本点が2000を超えたら満貫 (切り上げ満貫採用なら1920->2000)
+    // ここでは厳密な計算 (2000以上) とする。※30符4飜は1920なのでNormal、60符3飜は1920、70符3飜(2240)は満貫
+    if (totalHan >= HAN_YAKUMAN) {
+        // 役満（数え役満）
+        // ダブル役満等は呼び出し元でHandを判定して Han=26 とかに固定して渡してもらう想定
+        // またはHan=13以上はすべてYakumanとして扱う（シングル）
+        // ここでは13以上をYakuman、26以上をDoubleとする簡易判定を入れる
+        if (totalHan >= 26) {
+            level = "DoubleYakuman"; // 例
+            basePoints = SCORE_BASE_YAKUMAN * 2;
+        }
+        else {
+            level = "Yakuman";
+            basePoints = SCORE_BASE_YAKUMAN;
+        }
+    }
+    else if (totalHan >= HAN_SANBAIMAN) {
+        level = "Sanbaiman";
+        basePoints = SCORE_BASE_SANBAIMAN;
+    }
+    else if (totalHan >= HAN_BAIMAN) {
+        level = "Baiman";
+        basePoints = SCORE_BASE_BAIMAN;
+    }
+    else if (totalHan >= HAN_HANEMAN) {
+        level = "Haneman";
+        basePoints = SCORE_BASE_HANEMAN;
+    }
+    else if (totalHan >= HAN_MANGAN || basePoints >= BASE_POINT_LIMIT) {
+        level = "Mangan";
+        basePoints = SCORE_BASE_MANGAN;
+    }
+    // 支払い計算
+    let mainPayment = 0;
+    let subPayment = 0;
+    let totalScore = 0;
+    if (context.isTsumo) {
+        // ツモ和了
+        if (context.isOya) {
+            // 親ツモ: オール (基本点 * 2)
+            const pay = ceil100(basePoints * 2);
+            mainPayment = pay;
+            // ScorePayment型の定義について:
+            // main: ロンなら支払い総額、ツモなら親の支払い
+            // sub: ツモの時の子の支払い
+            // 親ツモの場合、「親の支払い」は発生せず、全員が「子」として支払います。
+            // ここでは `main` を「子一人あたりの支払い」として使用します。
+            // 親ツモ: 子の支払い(main) * 3
+            // 子ツモ: 親の支払い(main) + 子の支払い(sub) * 2
+            const childPay = ceil100(basePoints * 2);
+            mainPayment = childPay; // 各子の支払い
+            subPayment = 0;
+            totalScore = childPay * 3;
+        }
+        else {
+            // 子ツモ
+            // 親の支払い: 基本点 * 2
+            // 子の支払い: 基本点 * 1
+            const parentPay = ceil100(basePoints * 2);
+            const childPay = ceil100(basePoints * 1);
+            mainPayment = parentPay;
+            subPayment = childPay;
+            totalScore = parentPay + childPay * 2;
+        }
+    }
+    else {
+        // ロン和了
+        if (context.isOya) {
+            // 親ロン: 基本点 * 6
+            const pay = ceil100(basePoints * 6);
+            mainPayment = pay;
+            totalScore = pay;
+        }
+        else {
+            // 子ロン: 基本点 * 4
+            const pay = ceil100(basePoints * 4);
+            mainPayment = pay;
+            totalScore = pay;
+        }
+    }
+    return {
+        han: totalHan,
+        fu: fu,
+        level,
+        points: {
+            main: mainPayment,
+            sub: subPayment,
+            total: totalScore,
+        },
+    };
+}

package/dist/features/points/lib/fu/constants.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 符計算に関する定数定義
+ */
+export declare const FU_BASE: {
+    readonly NORMAL: 20;
+    readonly CHIITOITSU: 25;
+    readonly KOKUSHI: 20;
+};
+export declare const FU_AGARI: {
+    readonly TSUMO: 2;
+    readonly MENZEN_RON: 10;
+};
+export declare const FU_JANTOU: {
+    readonly YAKUHAI: 2;
+    readonly DOUBLE_WIND_CAP: 2;
+};
+export declare const FU_MACHI: {
+    readonly KANCHAN: 2;
+    readonly PENCHAN: 2;
+    readonly TANKI: 2;
+    readonly RYANMEN: 0;
+    readonly SHANPON: 0;
+};
+export declare const FU_KOUTSU: {
+    readonly SUUPAI_OPEN: 2;
+    readonly SUUPAI_CLOSED: 4;
+    readonly YAOCHU_OPEN: 4;
+    readonly YAOCHU_CLOSED: 8;
+};
+export declare const FU_KANTSU: {
+    readonly SUUPAI_OPEN: 8;
+    readonly SUUPAI_CLOSED: 16;
+    readonly YAOCHU_OPEN: 16;
+    readonly YAOCHU_CLOSED: 32;
+};
+export declare const FU_PINFU_TSUMO = 20;
+export declare const FU_OPEN_PINFU_GLAZE = 30;

package/dist/features/points/lib/fu/constants.js

@@ -0,0 +1,45 @@
+/**
+ * 符計算に関する定数定義
+ */
+// 符底 (FuTei)
+export const FU_BASE = {
+    NORMAL: 20,
+    CHIITOITSU: 25,
+    KOKUSHI: 20, // 便宜上
+};
+// 和了符 (AgariFu)
+export const FU_AGARI = {
+    TSUMO: 2,
+    MENZEN_RON: 10,
+};
+// 雀頭符 (JantouFu)
+export const FU_JANTOU = {
+    YAKUHAI: 2,
+    // 連風牌の扱い（設定により4符または2符）
+    DOUBLE_WIND_CAP: 2,
+};
+// 待ち符 (MachiFu)
+export const FU_MACHI = {
+    KANCHAN: 2,
+    PENCHAN: 2,
+    TANKI: 2,
+    RYANMEN: 0,
+    SHANPON: 0,
+};
+// 面子符 (MentsuFu)
+// [Yaochu/Suupai]_[Open/Closed]
+export const FU_KOUTSU = {
+    SUUPAI_OPEN: 2,
+    SUUPAI_CLOSED: 4,
+    YAOCHU_OPEN: 4,
+    YAOCHU_CLOSED: 8,
+};
+export const FU_KANTSU = {
+    SUUPAI_OPEN: 8,
+    SUUPAI_CLOSED: 16,
+    YAOCHU_OPEN: 16,
+    YAOCHU_CLOSED: 32,
+};
+// 例外処理用定数
+export const FU_PINFU_TSUMO = 20;
+export const FU_OPEN_PINFU_GLAZE = 30; // 喰いタン平和形などの20符切り上げ

package/dist/features/points/lib/fu/index.d.ts

@@ -0,0 +1,11 @@
+import type { HouraStructure, HouraContext } from "../../../yaku/types";
+import type { FuResult } from "./types";
+/**
+ * 手牌の符を計算する (calculateFu)
+ *
+ * @param hand 和了形の手牌構造
+ * @param context 和了コンテキスト (場風、自風、ツモ/ロン等)
+ * @param isPinfu 平和が成立しているかどうか (平和ツモ20符例外の適用に必要)
+ * @returns 符計算結果
+ */
+export declare function calculateFu(hand: HouraStructure, context: HouraContext, isPinfu?: boolean): FuResult;

package/dist/features/points/lib/fu/index.js

@@ -0,0 +1,23 @@
+import { calculateChiitoitsuFu } from "./lib/chiitoitsu";
+import { calculateKokushiFu } from "./lib/kokushi";
+import { calculateMentsuFu } from "./lib/mentsu";
+/**
+ * 手牌の符を計算する (calculateFu)
+ *
+ * @param hand 和了形の手牌構造
+ * @param context 和了コンテキスト (場風、自風、ツモ/ロン等)
+ * @param isPinfu 平和が成立しているかどうか (平和ツモ20符例外の適用に必要)
+ * @returns 符計算結果
+ */
+export function calculateFu(hand, context, isPinfu = false) {
+    // 1. 七対子 (ChiiToitsu)
+    if (hand.type === "Chiitoitsu") {
+        return calculateChiitoitsuFu();
+    }
+    // 2. 国士無双 (Kokushi)
+    if (hand.type === "Kokushi") {
+        return calculateKokushiFu();
+    }
+    // 3. 面子手 (Mentsu)
+    return calculateMentsuFu(hand, context, isPinfu);
+}

package/dist/features/points/lib/fu/lib/chiitoitsu.d.ts

@@ -0,0 +1,5 @@
+import type { FuResult } from "../types";
+/**
+ * 七対子の符を計算する
+ */
+export declare function calculateChiitoitsuFu(): FuResult;

package/dist/features/points/lib/fu/lib/chiitoitsu.js

@@ -0,0 +1,17 @@
+import { FU_BASE } from "../constants";
+/**
+ * 七対子の符を計算する
+ */
+export function calculateChiitoitsuFu() {
+    const details = {
+        base: FU_BASE.CHIITOITSU,
+        mentsu: 0,
+        jantou: 0,
+        machi: 0,
+        agari: 0,
+    };
+    return {
+        total: FU_BASE.CHIITOITSU,
+        details,
+    };
+}

package/dist/features/points/lib/fu/lib/kokushi.d.ts

@@ -0,0 +1,6 @@
+import type { FuResult } from "../types";
+/**
+ * 国士無双の符を計算する
+ * (点数計算上は役満固定だが、便宜上符底のみを返す)
+ */
+export declare function calculateKokushiFu(): FuResult;

package/dist/features/points/lib/fu/lib/kokushi.js

@@ -0,0 +1,18 @@
+import { FU_BASE } from "../constants";
+/**
+ * 国士無双の符を計算する
+ * (点数計算上は役満固定だが、便宜上符底のみを返す)
+ */
+export function calculateKokushiFu() {
+    const details = {
+        base: FU_BASE.KOKUSHI,
+        mentsu: 0,
+        jantou: 0,
+        machi: 0,
+        agari: 0,
+    };
+    return {
+        total: FU_BASE.KOKUSHI,
+        details,
+    };
+}

package/dist/features/points/lib/fu/lib/mentsu.d.ts

@@ -0,0 +1,11 @@
+import type { FuResult } from "../types";
+import type { HouraContext } from "../../../../yaku/types";
+import type { MentsuHouraStructure } from "../../../../yaku/types";
+/**
+ * 面子手の符を計算する
+ *
+ * @param hand 面子手の構造
+ * @param context 和了コンテキスト
+ * @param isPinfu 平和成立フラグ
+ */
+export declare function calculateMentsuFu(hand: MentsuHouraStructure, context: HouraContext, isPinfu: boolean): FuResult;

package/dist/features/points/lib/fu/lib/mentsu.js

@@ -0,0 +1,122 @@
+import { isYaochu } from "../../../../../core/hai";
+import { HaiKind } from "../../../../../types";
+import { classifyMachi } from "../../../../../core/machi";
+import { FU_BASE, FU_KOUTSU, FU_KANTSU, FU_JANTOU, FU_MACHI, FU_AGARI, FU_PINFU_TSUMO, FU_OPEN_PINFU_GLAZE, } from "../constants";
+/**
+ * 面子手の符を計算する
+ *
+ * @param hand 面子手の構造
+ * @param context 和了コンテキスト
+ * @param isPinfu 平和成立フラグ
+ */
+export function calculateMentsuFu(hand, context, isPinfu) {
+    const details = {
+        base: FU_BASE.NORMAL,
+        mentsu: 0,
+        jantou: 0,
+        machi: 0,
+        agari: 0,
+    };
+    // 1. 面子符 (MentsuFu)
+    for (const mentsu of hand.fourMentsu) {
+        let fu = 0;
+        const isYaochuMentsu = isYaochu(mentsu.hais[0]);
+        if (mentsu.type === "Koutsu") {
+            // 刻子
+            const openFu = isYaochuMentsu
+                ? FU_KOUTSU.YAOCHU_OPEN
+                : FU_KOUTSU.SUUPAI_OPEN;
+            const closedFu = isYaochuMentsu
+                ? FU_KOUTSU.YAOCHU_CLOSED
+                : FU_KOUTSU.SUUPAI_CLOSED;
+            fu = closedFu;
+            // 明刻判定
+            let isOpen = !!mentsu.furo;
+            if (!isOpen && !context.isTsumo) {
+                // ロン和了で、かつその牌を含む刻子であれば明刻扱い
+                if (mentsu.hais.includes(context.agariHai)) {
+                    isOpen = true;
+                }
+            }
+            if (isOpen) {
+                fu = openFu;
+            }
+            details.mentsu += fu;
+        }
+        else if (mentsu.type === "Kantsu") {
+            // 槓子
+            const openFu = isYaochuMentsu
+                ? FU_KANTSU.YAOCHU_OPEN
+                : FU_KANTSU.SUUPAI_OPEN;
+            const closedFu = isYaochuMentsu
+                ? FU_KANTSU.YAOCHU_CLOSED
+                : FU_KANTSU.SUUPAI_CLOSED;
+            fu = closedFu;
+            if (mentsu.furo) {
+                fu = openFu;
+            }
+            details.mentsu += fu;
+        }
+    }
+    // 2. 雀頭符 (JantouFu)
+    const headHai = hand.jantou.hais[0];
+    let jantouFu = 0;
+    if (headHai === HaiKind.Haku ||
+        headHai === HaiKind.Hatsu ||
+        headHai === HaiKind.Chun) {
+        jantouFu += FU_JANTOU.YAKUHAI;
+    }
+    if (headHai === context.bakaze) {
+        jantouFu += FU_JANTOU.YAKUHAI;
+    }
+    if (headHai === context.jikaze) {
+        jantouFu += FU_JANTOU.YAKUHAI;
+    }
+    // 連風牌の加算上限
+    if (jantouFu > FU_JANTOU.DOUBLE_WIND_CAP) {
+        jantouFu = FU_JANTOU.DOUBLE_WIND_CAP;
+    }
+    details.jantou = jantouFu;
+    // 3. 待ち符 (MachiFu)
+    const machiType = classifyMachi(hand, context.agariHai);
+    if (machiType === "Kanchan")
+        details.machi = FU_MACHI.KANCHAN;
+    else if (machiType === "Penchan")
+        details.machi = FU_MACHI.PENCHAN;
+    else if (machiType === "Tanki")
+        details.machi = FU_MACHI.TANKI;
+    else
+        details.machi = 0; // Ryanmen, Shanpon
+    // 4. 和了符 (AgariFu)
+    if (context.isTsumo) {
+        if (!isPinfu) {
+            details.agari = FU_AGARI.TSUMO;
+        }
+    }
+    else {
+        if (context.isMenzen) {
+            details.agari = FU_AGARI.MENZEN_RON;
+        }
+    }
+    // 合計
+    let sum = details.base +
+        details.mentsu +
+        details.jantou +
+        details.machi +
+        details.agari;
+    // 平和ツモ例外
+    if (isPinfu && context.isTsumo) {
+        return { total: FU_PINFU_TSUMO, details };
+    }
+    // 切り上げ (喰いタン平和形など)
+    if (sum === 20 && !context.isTsumo && !context.isMenzen) {
+        sum = FU_OPEN_PINFU_GLAZE;
+    }
+    else {
+        sum = Math.ceil(sum / 10) * 10;
+    }
+    return {
+        total: sum,
+        details,
+    };
+}

package/dist/features/points/lib/fu/types.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 符の構成要素 (FuDetails)
+ *
+ * 符計算の内訳を保持するインターフェース。
+ */
+export interface FuDetails {
+    /**
+     * 符底 (FuTei)
+     *
+     * 一般的な和了形: 20符
+     * 七対子: 25符
+     */
+    readonly base: 20 | 25;
+    /**
+     * 面子符の合計 (MentsuFu)
+     *
+     * 刻子・槓子による加算符。順子は0符。
+     */
+    readonly mentsu: number;
+    /**
+     * 雀頭符 (JantouFu)
+     *
+     * 役牌の対子による加算符。
+     */
+    readonly jantou: number;
+    /**
+     * 待ち符 (MachiFu)
+     *
+     * 単騎・嵌張・辺張待ちによる加算符（2符）。
+     */
+    readonly machi: number;
+    /**
+     * 和了符 (AgariFu)
+     *
+     * ツモ和了: 2符
+     * 門前ロン: 10符
+     */
+    readonly agari: number;
+}
+/**
+ * 符計算結果 (FuResult)
+ */
+export interface FuResult {
+    /**
+     * 最終的な符数 (Total)
+     *
+     * 内訳の合計を10符単位で切り上げたもの。
+     * (例: 22符 -> 30符)
+     */
+    readonly total: number;
+    /**
+     * 計算の内訳
+     */
+    readonly details: FuDetails;
+}

package/dist/features/points/lib/fu/types.js

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

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

@@ -0,0 +1,27 @@
+import type { HaiKindId, Kazehai } from "../../types";
+export interface ScoreCalculationConfig {
+    /** 和了牌 */
+    agariHai: HaiKindId;
+    /** ツモ和了かどうか (必須) */
+    isTsumo: boolean;
+    /** 自風 (必須) */
+    jikaze: Kazehai;
+    /** 場風 (必須) */
+    bakaze: Kazehai;
+    /** ドラ表示牌 (必須、なければ空配列) */
+    doraMarkers: readonly HaiKindId[];
+    /** 裏ドラ表示牌 (任意) */
+    uraDoraMarkers?: readonly HaiKindId[];
+}
+export type ScoreLevel = "Normal" | "Mangan" | "Haneman" | "Baiman" | "Sanbaiman" | "Yakuman" | "DoubleYakuman" | "TripleYakuman";
+export interface ScorePayment {
+    main: number;
+    sub?: number;
+    total: number;
+}
+export interface ScoreResult {
+    han: number;
+    fu: number;
+    level: ScoreLevel;
+    points: ScorePayment;
+}

package/dist/features/points/types.js

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

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

@@ -0,0 +1,16 @@
+import type { Tehai13 } from "../../types";
+import { calculateChiitoitsuShanten } from "./logic/chiitoitsu";
+import { calculateKokushiShanten } from "./logic/kokushi";
+import { calculateMentsuTeShanten } from "./logic/mentsu-te";
+export { calculateChiitoitsuShanten, calculateKokushiShanten, calculateMentsuTeShanten, };
+/**
+ * シャンテン数を計算します。
+ * 面子手、七対子、国士無双のシャンテン数のうち最小値を返します。
+ *
+ * NOTE: 入力は必ず牌種ID (`HaiKindId`) である必要があります。
+ * 物理牌ID (`HaiId`) を持っている場合は、事前に `haiIdToKindId` で変換してください。
+ *
+ * @param tehai 手牌
+ * @returns シャンテン数
+ */
+export declare function calculateShanten(tehai: Tehai13, useChiitoitsu?: boolean, useKokushi?: boolean): number;

package/dist/features/shanten/index.js

@@ -0,0 +1,25 @@
+import { validateTehai13 } from "../../core/tehai";
+import { calculateChiitoitsuShanten } from "./logic/chiitoitsu";
+import { calculateKokushiShanten } from "./logic/kokushi";
+import { calculateMentsuTeShanten } from "./logic/mentsu-te";
+export { calculateChiitoitsuShanten, calculateKokushiShanten, calculateMentsuTeShanten, };
+/**
+ * シャンテン数を計算します。
+ * 面子手、七対子、国士無双のシャンテン数のうち最小値を返します。
+ *
+ * NOTE: 入力は必ず牌種ID (`HaiKindId`) である必要があります。
+ * 物理牌ID (`HaiId`) を持っている場合は、事前に `haiIdToKindId` で変換してください。
+ *
+ * @param tehai 手牌
+ * @returns シャンテン数
+ */
+export function calculateShanten(tehai, useChiitoitsu = true, useKokushi = true) {
+    // Facadeパターン: 公開APIのエントリーポイントで入力を保証する
+    validateTehai13(tehai);
+    const chiitoitsuShanten = useChiitoitsu
+        ? calculateChiitoitsuShanten(tehai)
+        : Infinity;
+    const kokushiShanten = useKokushi ? calculateKokushiShanten(tehai) : Infinity;
+    const mentsuShanten = calculateMentsuTeShanten(tehai);
+    return Math.min(chiitoitsuShanten, kokushiShanten, mentsuShanten);
+}

package/dist/features/shanten/logic/chiitoitsu.d.ts

@@ -0,0 +1,8 @@
+import type { Tehai13 } from "../../../types";
+/**
+ * 七対子のシャンテン数を計算する
+ *
+ * @param tehai 手牌 (13枚)
+ * @returns シャンテン数 (0: 聴牌, -1: 和了 - 理論上)
+ */
+export declare function calculateChiitoitsuShanten(tehai: Tehai13): number;

package/dist/features/shanten/logic/chiitoitsu.js

@@ -0,0 +1,36 @@
+import { countHaiKind, validateTehai13 } from "../../../core/tehai";
+/**
+ * 七対子のシャンテン数を計算する
+ *
+ * @param tehai 手牌 (13枚)
+ * @returns シャンテン数 (0: 聴牌, -1: 和了 - 理論上)
+ */
+export function calculateChiitoitsuShanten(tehai) {
+    // 防御的プログラミング (Defensive Programming):
+    // 公開API（calculateShanten）側でもバリデーションが行われる想定だが（Facadeパターン）、
+    // 内部整合性を保つため、ここでも独立してバリデーションを実施する。
+    validateTehai13(tehai);
+    // シャンテン数を計算する前にバリデーションを実行する
+    // 七対子は門前のみ
+    if (tehai.exposed.length > 0) {
+        return Infinity;
+    }
+    // HaiId/HaiKindId の正規化は廃止。呼び出し元で HaiKindId を保証する。
+    const haiCounts = countHaiKind(tehai.closed);
+    let pairs = 0;
+    let kinds = 0;
+    for (const count of haiCounts) {
+        if (count > 0) {
+            kinds++;
+        }
+        if (count >= 2) {
+            pairs++;
+        }
+    }
+    let shanten = 6 - pairs;
+    // 種類不足ペナルティ
+    if (kinds < 7) {
+        shanten += 7 - kinds;
+    }
+    return shanten;
+}

package/dist/features/shanten/logic/kokushi.d.ts

@@ -0,0 +1,16 @@
+import type { Tehai13 } from "../../../types";
+/**
+ * 国士無双のシャンテン数を計算します。
+ *
+ * ルール:
+ * - 13種類の么九牌（1,9,字牌）を各1枚ずつ揃える。
+ * - そのうちのどれか1種類が対子（2枚）になっている必要がある。
+ * - 門前限定。
+ *
+ * 計算式:
+ * シャンテン数 = 13 - (么九牌の種類数) - (么九牌の対子があるか ? 1 : 0)
+ *
+ * @param tehai 手牌
+ * @returns シャンテン数 (0: 聴牌, -1: 和了(理論上))。副露している場合は Infinity。
+ */
+export declare function calculateKokushiShanten(tehai: Tehai13): number;