koma-strict

koma(KMP の MVI 状態管理ライブラリ)向けの KSP プラグイン。

State 定義から Store を typesafe に組み上げる DSL を自動生成する実験プロジェクト。

koma の素の DSL には強制が一切ない ── state の網羅は要求されず、遷移先も emit する event も無制限。 koma-strict はこの規約を「レビューで守る」のではなく コンパイルエラーで守る:

① 宣言していない遷移・イベントは 書けない。 ② 宣言した State / Action のハンドリングは 書き忘れられない 仕組みを提供する。

この 2 つを、実行時チェックではなく すべてコンパイルエラーとして実現する。

// module/build.gradle.kts
plugins {
    id("com.google.devtools.ksp") version "<ksp-version>"
}

dependencies {
    implementation("me.tbsten.koma.strict:koma-strict-runtime:<koma-strict-version>")
    ksp("me.tbsten.koma.strict:koma-strict-ksp:<koma-strict-version>")
}

（KMP プロジェクトの場合は KSP の制限を回避するためのワークアラウンド が必要です）

また IDE 拡張機能をインストールすることで、@StoreSpec を IDE 上で可視化したり、追加のコード生成機能などを利用することができます。最新リリース から koma-strict-idea-<version>.zip をダウンロードして、お使いの IDE の Settings → Plugins → ⚙ → Install Plugin from Disk… から選択してインストールしてください（IntelliJ IDEA / Android Studio 2026.1 以降が必要です）。

@StoreSpec(initial = [LceState.Loading::class])          // actions / events は宣言から推論
sealed interface LceState : State {
    companion object                                     // 生成拡張の生やし先

    @OnEnter(nextState = [Content::class, Error::class], emit = [LceEvent.LoadFailed::class])
    interface Loading : LceState { companion object }

    @OnAction<LceAction.Reload>(nextState = [Loading::class])
    interface Content : LceState { val data: String; companion object }

    @OnAction<LceAction.Retry>(nextState = [Loading::class])
    interface Error : LceState { val message: String?; companion object }
}

sealed interface LceAction : Action {
    data object Reload : LceAction
    data object Retry : LceAction
}

sealed interface LceEvent : Event {
    data class LoadFailed(val message: String?) : LceEvent
}

val store = createLceStore(                              // 生成 factory(型引数を書かない糖衣入口)
    initialState = LceState.Loading(),                   // 宣言済み initial 候補に型で絞り込まれる
    loading = LceState.Loading.actions(
        enter = {
            runCatching { fetchData() }.fold(
                onSuccess = { nextState.toContent(data = it) },  // 宣言済み遷移だけが生える
                onFailure = {
                    emitLoadFailed(it.message)                   // 宣言済み event だけが emit できる
                    nextState.toError(message = it.message)
                },
            )
        },
    ),
    content = LceState.Content.actions(reload = { nextState.toLoading() }),
    error = LceState.Error.actions(retry = { nextState.toLoading() }),
)

• content を渡し忘れる → コンパイルエラー(必須引数)
• 宣言していない遷移(nextState.toXxx)や event(emitXxx)はそもそも生えないので書けない
• 出来上がる store は本物の Store<LceState, LceAction, LceEvent> ── koma-compose / koma-test 等がそのまま使える
• 生成 factory は 2 つ ── createLceStore の initialState は宣言済み @StoreSpec(initial = ...) 候補 (LceState.Loading)に型で絞り込まれる。永続化 state からの復元やテストでの途中 state 起動には、 任意の LceState を受け付ける restoreLceStore を使う

このフレームワークの入出力は snapshot test されています。 snapshot は ./koma-strict-ksp/snapshots に格納されており、 特に koma-strict-ksp/snapshots/StoreSpecUseCasesTest/samples.md のユースケースとオプションの全組み合わせ/option=Default は実際のユースケースを想定した入出力がまとまっているため、これを参照して以下のような具体的なユースケース別の生成例を確認できます。

• 基本的な LCE (Load-Content-Error) パターン
• 中間 sealed(Stable)/ 条件付き遷移(Stay)/ prop 持ち越しを伴う LCE(pull-to-refresh + additional load)
• root 共有アクション / 宣言ゼロ state(それでも必須引数)/ data object 宣言 / E = Nothing(タブ切替)
• stay + emit(バリデーション)/ 自己遷移との違い / prop の必須・デフォルト混在(フォームウィザード)
• @OnRecover(root 共有)/ @OnExit / 例外→宣言済み遷移の強制(認証 + セッション切れ)

package はすべて me.tbsten.koma.strict 直下。

アクション能力ルール: nextState リストがそのハンドラの全能力を決める ── [](省略)= stayState() のみ / [X::class] = nextState.toX() のみ / [Stay::class, X::class] = 両方(条件分岐)。 遷移先は具象 leaf のみ(nextState: Array<KClass<out State>> のため State 非実装型は型エラー、中間 sealed 型は KSP エラー)。

annotation 付き sealed State + Action / Event
  → KSP 解析 (koma-strict-ksp)
  → 生成: StoreBuilder への states()/actions() などの typesafe builder の生成
  → 利用者は koma 標準の Store {} 内で states() を呼ぶ(全 handler = 必須 named param)
  → 出来上がるのは素の koma Store<S, A, E>(入口から本物・エコシステムがそのまま使える)

思想は 4 本:状態遷移とその実装を分離/ 遷移は State 定義の近くに置く(annotation のつけ外し = 扱える遷移の増減)/ 強い制約とシンプルな定義(複雑さは生成コードが背負い、利用者の定義は素の sealed interface + 少数の annotation)/ エンジンを密閉しない(入口は koma 標準の Store {} そのもの)。

Kotlin でコンパイル時に「全部書かせる」道具は 必須引数 と abstract メンバー の 2 つだけ。そこで:

同じ store を、好みに合わせて複数の形で書ける(混在も可):

• 生成 factory ── createLceStore(initialState, loading = ..., ...)(型引数不要の糖衣入口。 initialState は宣言済み initial 候補に絞り込まれる)/ 任意の state から始める restoreLceStore
• koma 直入口 ── Store<S, A, E>(initialState) { states(...) }(正。型引数は明示)
• 値渡し / scope lambda ── loading = X.actions(...) でも loading = { actions(...) } でも(両対応)
• plus 合成 ── 自宣言 + 子を持つ中間 sealed は X.actions(...) + X.states(...)(片方忘れは型エラー)
• builder 形式 ── actions { reload { ... } } / states { idle { ... } } (※ この形式のみ、アクション網羅は構築時 fail-fast に弱まる ── opt-in のトレードオフ)
• エスケープハッチ ── actions(...) { /* per-state 素の koma DSL */ } や Store {} 末尾の configuration で、v1 スコープ外の koma 機能(launch {} / transaction {} 等)を差し込める

詳細と全ユースケースは doc/internal/samples.md を参照。

KSP 非依存の shared(model・命名・codegen)を核に、KSP は frontend に徹する層構成 (将来の Analysis API / compiler plugin 移行を見据えた設計。.claude/rules/ksp-architecture.md)。

@StoreSpec 一式は遷移グラフの全データを静的に持つので、図生成は KSP 解析の副産物として実現できる。

KSP オプション koma.strict.generateDiagramModel(既定 false)を有効にすると、store ごとに <Root>.diagram.generated.kt が生成される。中身は:

• <Root>DiagramModel: StoreDiagramModel ── @StoreSpec を静的に射影した IR(states / actions / initial / 到達可能性など)
• <Root>.diagramStateId(): StateId ── 生きた state 値を上の IR の StateId へ写す拡張関数(sealed 網羅・ else 無しなので新しい leaf を足すと生成が追いつくまでコンパイルが止まる)

描画するにはこの 2 つを koma-strict-diagram-compose の StoreDiagramPanel composable に渡す。実例は integrationTest/composeApp の tripletriad サンプル(GamePane のトグル可能な右パネル)。

// 生成される <Root>DiagramModel / diagramStateId() を解決するのに必須
implementation("me.tbsten.koma.strict:koma-strict-diagram:<version>")
// StoreDiagramPanel で実際に描画する場合に追加 (Compose Multiplatform)
implementation("me.tbsten.koma.strict:koma-strict-diagram-compose:<version>")

Mermaid / PlantUML の「図 + 遷移表」ペアを docs として出力し、CI の drift check で宣言との乖離を防ぐ構想は 未着手。設計は doc/internal/generate-state-diagrams.md。