kotlin-tooling-java-to-kotlin

Java から Kotlin への変換

Java ソースファイルを、5 つの不変条件を各ステップで確認する、規律ある 4 ステップの変換手法で、慣用的な Kotlin に変換します。アノテーションの使用箇所ターゲット、ライブラリの慣用表現、API の維持に対応した、フレームワークを考慮する変換をサポートします。

ワークフロー

digraph j2k_workflow {
  rankdir=TB;
  "User specifies files" -> "Step 0: Scan & Detect";
  "Step 0: Scan & Detect" -> "Load framework guides";
  "Load framework guides" -> "Step 1: Convert";
  "Step 1: Convert" -> "Step 2: Write .kt";
  "Step 2: Write .kt" -> "Step 3: Git rename";
  "Step 3: Git rename" -> "Step 4: Verify";
  "Step 4: Verify" -> "Next file?" [label="pass"];
  "Step 4: Verify" -> "Fix issues" [label="fail"];
  "Fix issues" -> "Step 1: Convert";
  "Next file?" -> "Step 0: Scan & Detect" [label="batch: yes"];
  "Next file?" -> "Done" [label="no more files"];
}

ステップ 0：スキャンとフレームワークの検出

変換する前に、Java ファイルの import 文をスキャンして、使用中のフレームワークを検出します。コンテキストを絞り込むため、一致するフレームワークのリファレンスファイルのみを読み込みます。

フレームワーク検出テーブル

インポートのプレフィックス	フレームワークガイド
org.springframework.*	SPRING.md
lombok.*	LOMBOK.md
javax.persistence.*、jakarta.persistence.*、org.hibernate.*	HIBERNATE.md
com.fasterxml.jackson.*	JACKSON.md
io.micronaut.*	MICRONAUT.md
io.quarkus.*、javax.enterprise.*、jakarta.enterprise.*	QUARKUS.md
dagger.*、dagger.hilt.*	DAGGER-HILT.md
io.reactivex.*、rx.*	RXJAVA.md
org.junit.*、org.testng.*	JUNIT.md
com.google.inject.*	GUICE.md
retrofit2.*、okhttp3.*	RETROFIT.md
org.mockito.*	MOCKITO.md

javax.inject.* が検出された場合は、該当するフレームワークのほかの import を確認して、Dagger/Hilt と Guice のどちらが使われているかを判別します。判断できない場合は、両方のガイドを読み込みます。

ステップ 1：変換

CONVERSION-METHODOLOGY.md の変換手法に従います。

これは 4 ステップの思考連鎖プロセスです。

1. 忠実な 1 対 1 の翻訳 — セマンティクスを正確に維持します
2. null 許容性と可変性の監査 — val/var、null 許容型を確認します
3. コレクション型の変換 — Java の可変型を Kotlin の型に変換します
4. 慣用的な変換 — プロパティ、文字列テンプレート、ラムダを適用します

各ステップの後に、5 つの不変条件を確認します。不変条件に違反した場合は、前のステップに戻ってやり直します。

ステップ 4（慣用的な変換）では、読み込んだフレームワーク固有のガイダンスを適用します。

ステップ 2：出力を書き込む

変換した Kotlin コードを、元の Java ファイルと同じディレクトリに、同じ名前の .kt ファイルとして書き込みます。

ステップ 3：Git 履歴を維持する

git blame の履歴を維持するには、2 段階の方法を使用します。

# Phase 1: Rename (creates rename tracking)
git mv src/main/java/com/example/Foo.java src/main/kotlin/com/example/Foo.kt
git commit -m "Rename Foo.java to Foo.kt"

# Phase 2: Replace content (tracked as modification, not new file)
# Write the converted Kotlin content to Foo.kt
git commit -m "Convert Foo from Java to Kotlin"

プロジェクトで Java と Kotlin を同じソースルート（例：src/main/java/）に配置している場合は、同じ場所で名前を変更します。

git mv src/main/java/com/example/Foo.java src/main/java/com/example/Foo.kt

プロジェクトで Git を使用していない場合は、.kt ファイルを書き込み、.java ファイルを削除するだけです。

ステップ 4：検証

変換後、checklist.md を使用して検証します。

• 変換したファイルのコンパイルを試みます
• 既存のテストを実行します
• アノテーションの使用箇所ターゲットを確認します
• 動作に変更がないことを確認します

一括変換

複数のファイル（ディレクトリまたはパッケージ）を変換する場合：

1. 対象範囲内のすべての .java ファイルを一覧にします
2. 依存関係の順に並べ替えます — まず依存先のファイル（変換対象内のほかのファイルを import しないファイル）を変換し、次にそれらに依存するファイルへ進みます
3. 1 ファイルずつ変換します — 各ファイルにワークフロー全体（ステップ 0～4）を適用します
4. 進捗を記録します — 完了したファイルと残りのファイルを報告します
5. 相互参照を処理します — ファイルの変換後、必要に応じてほかの Java ファイルの import を更新します（例：クラスのパッケージが変わった場合）

大規模な一括変換では、パッケージ単位で変換することを検討してください（依存先のパッケージから順に進めます）。

よくある落とし穴

以下については、KNOWN-ISSUES.md を参照してください。

• Kotlin のキーワードとの競合（when、in、is、object）
• SAM 変換の曖昧さ
• Java との相互運用におけるプラットフォーム型
• @JvmStatic／@JvmField／@JvmOverloads の使用方法
• チェック例外と @Throws
• ワイルドカードジェネリクス → Kotlin の分散