docs: restore docs/private/roadmap from 7b4908f9 (Phase 20.31)

docs/private/roadmap/phases/phase-20-python-integration/transpiler/README.md

@@ -0,0 +1,201 @@
+# Transpiler - Python→Hakorune トランスパイラー
+
+## 📋 概要
+
+PythonコードをHakoruneコードに変換するトランスパイラーの設計・仕様です。
+
+## 📁 ファイル一覧
+
+- **[python-to-hakorune-spec.md](python-to-hakorune-spec.md)** - Python→Hakorune変換仕様
+
+## 🎯 目的
+
+### トランスパイラーの役割
+
+1. **構文変換**
+   - Python構文 → Hakorune構文
+   - イディオム変換
+   - スタイル変換
+
+2. **型注釈の活用**
+   - Pythonの型ヒント → Hakorune型
+   - 型推論の補助
+   - 型安全性の向上
+
+3. **最適化**
+   - Hakorune向け最適化
+   - 不要なコードの削除
+   - パフォーマンス改善
+
+## 🔄 変換例
+
+### 基本構文
+
+```python
+# Python
+class Player:
+    def __init__(self, name: str):
+        self.name = name
+        self.health = 100
+
+    def heal(self, amount: int):
+        self.health += amount
+```
+
+```hakorune
+// Hakorune
+box Player {
+    name: StringBox
+    health: IntegerBox
+
+    birth(name: StringBox) {
+        me.name = name
+        me.health = integer.create(100)
+    }
+
+    heal(amount: IntegerBox) {
+        me.health = me.health.add(amount)
+    }
+}
+```
+
+### 制御構文
+
+```python
+# Python
+for i in range(10):
+    print(i)
+```
+
+```hakorune
+// Hakorune
+local i = integer.create(0)
+loop(i.compare("<", 10)) {
+    console.log(i.to_string())
+    i = i.add(1)
+}
+```
+
+### リスト操作
+
+```python
+# Python
+items = [1, 2, 3]
+items.append(4)
+```
+
+```hakorune
+// Hakorune
+local items = array.create()
+items.push(integer.create(1))
+items.push(integer.create(2))
+items.push(integer.create(3))
+items.push(integer.create(4))
+```
+
+## 🏗️ アーキテクチャ
+
+### トランスパイラーのフェーズ
+
+1. **パース**
+   - Pythonコードをパース
+   - AST生成
+
+2. **型推論**
+   - 型ヒントの解析
+   - 型推論の実行
+   - 型情報の付与
+
+3. **変換**
+   - Python AST → Hakorune AST
+   - イディオム変換
+   - 最適化
+
+4. **コード生成**
+   - Hakorune ASTからコード生成
+   - フォーマット適用
+   - 出力
+
+### 変換ルール
+
+| Python構文 | Hakorune構文 | 備考 |
+|-----------|-------------|------|
+| `class` | `box` | クラス→Box |
+| `__init__` | `birth` | コンストラクタ |
+| `self` | `me` | 自己参照 |
+| `for ... in range()` | `loop(...)` | ループ |
+| `if ... elif ... else` | `if ... elif ... else` | 条件分岐 |
+| `def func()` | `func()` | 関数定義 |
+| `x = y` | `local x = y` | 変数宣言 |
+| `list[index]` | `list.get(index)` | 配列アクセス |
+| `dict[key]` | `dict.get(key)` | 辞書アクセス |
+
+## 🔧 技術的課題
+
+### 1. Python固有機能の扱い
+
+#### サポートする機能
+- 基本データ型（int, str, list, dict）
+- クラス・メソッド
+- 制御構文（if, for, while）
+- 関数定義
+
+#### サポートしない/制限する機能
+- メタクラス
+- デコレーター（一部のみ）
+- ジェネレーター
+- 内包表記（将来対応）
+- async/await（Phase 15以降）
+
+### 2. 型推論
+
+- 型ヒントを優先使用
+- 未注釈の場合は推論
+- 推論不可能な場合は`AnyBox`
+
+### 3. ネーミング変換
+
+- snake_case → camelCase（オプション）
+- Python予約語の回避
+- Hakorune予約語との衝突回避
+
+## 📊 実装ステータス
+
+| コンポーネント | ステータス | 備考 |
+|--------------|----------|------|
+| 変換仕様 | ✅ 完了 | 設計書完成 |
+| パーサー統合 | 📅 未実装 | - |
+| 型推論 | 📅 未実装 | - |
+| AST変換 | 📅 未実装 | - |
+| コード生成 | 📅 未実装 | - |
+
+## 🎯 使用例
+
+```bash
+# コマンドライン（将来）
+hakorune transpile script.py -o script.hkr
+
+# プログラマティック（将来）
+local transpiler = new PythonTranspiler()
+local hakorune_code = transpiler.transpile(python_code)
+```
+
+## ⚠️ 制限事項
+
+1. **完全互換性は保証しない**
+   - Pythonのすべての機能はサポートしない
+   - 一部機能は手動移植が必要
+
+2. **実行時動的機能**
+   - `eval()`, `exec()` は変換不可
+   - 動的属性追加は制限
+
+3. **標準ライブラリ**
+   - Python標準ライブラリは自動変換しない
+   - Hakorune equivalent への手動マッピング必要
+
+## 🔗 関連ドキュメント
+
+- [Phase 20 メインREADME](../README.md)
+- [Parser Integration](../parser-integration/)
+- [Core Implementation](../core-implementation/)

docs/private/roadmap/phases/phase-20-python-integration/transpiler/python-to-hakorune-spec.md

@@ -0,0 +1,225 @@
+# Python → Nyashトランスパイラー機能
+～PythonParserBoxの応用による自動変換～
+
+## 🎯 概要
+
+PythonParserBoxでPython AST → Nyash ASTの変換ができるなら、それを**Nyashソースコードとして出力**できる！
+
+## 🚀 実現可能な機能
+
+### 1. Python → Nyashファイル変換
+```python
+# input.py
+def calculate(x, y):
+    result = x * 2 + y
+    return result
+
+for i in range(10):
+    print(calculate(i, 5))
+```
+
+↓ 変換
+
+```nyash
+# output.nyash
+function calculate(x, y) {
+    local result
+    result = x * 2 + y
+    return result
+}
+
+local i
+for i in range(0, 10) {
+    print(calculate(i, 5))
+}
+```
+
+### 2. 実装方法
+
+```rust
+impl PythonParserBox {
+    // Python → Nyashファイル出力
+    pub fn transpile_to_file(&self, python_code: &str, output_path: &str) -> Result<(), String> {
+        // 1. Python → JSON AST
+        let json_ast = self.parse_to_json(python_code)?;
+        
+        // 2. JSON AST → Nyash AST
+        let nyash_ast = self.json_to_nyash_ast(&json_ast)?;
+        
+        // 3. Nyash AST → Nyashソースコード
+        let nyash_code = self.ast_to_nyash_source(&nyash_ast)?;
+        
+        // 4. ファイルに出力
+        std::fs::write(output_path, nyash_code)?;
+        
+        Ok(())
+    }
+    
+    // AST → Nyashソースコード生成
+    fn ast_to_nyash_source(&self, ast: &NyashAst) -> Result<String, String> {
+        let mut output = String::new();
+        let formatter = NyashFormatter::new();
+        
+        for item in &ast.items {
+            formatter.format_item(item, &mut output)?;
+        }
+        
+        Ok(output)
+    }
+}
+```
+
+## 📋 使用例
+
+### コマンドライン版
+```bash
+# PythonファイルをNyashに変換
+nyash-transpile input.py -o output.nyash
+
+# 標準出力に出力
+nyash-transpile script.py
+
+# 部分変換（サポートされる構文のみ）
+nyash-transpile --partial complex_script.py
+```
+
+### Nyashスクリプト内での使用
+```nyash
+local transpiler = new PythonParserBox()
+
+// Pythonコードを読み込み
+local python_code = FileBox.read("algorithm.py")
+
+// Nyashに変換
+local nyash_code = transpiler.to_nyash_source(python_code)
+
+// ファイルに保存
+FileBox.write("algorithm.nyash", nyash_code)
+
+// または直接実行
+eval(nyash_code)
+```
+
+## 🎨 変換マッピング例
+
+### 基本構文
+| Python | Nyash |
+|--------|-------|
+| `def func():` | `function func() {` |
+| `if x > 0:` | `if (x > 0) {` |
+| `for i in range(10):` | `for i in range(0, 10) {` |
+| `while x < 10:` | `while (x < 10) {` |
+| `x = 5` | `local x; x = 5` または `x = 5`（スコープによる）|
+
+### データ型
+| Python | Nyash |
+|--------|-------|
+| `x = 42` | `x = 42` |
+| `s = "hello"` | `s = "hello"` |
+| `lst = [1, 2, 3]` | `lst = new ArrayBox([1, 2, 3])` |
+| `d = {"a": 1}` | `d = new MapBox(); d.set("a", 1)` |
+
+### 特殊なケース
+```python
+# Pythonのfor/else
+for i in items:
+    if condition:
+        break
+else:
+    print("No break")
+```
+
+```nyash
+# Nyashでの実装（フラグを使用）
+local broke = false
+for i in items {
+    if (condition) {
+        broke = true
+        break
+    }
+}
+if (not broke) {
+    print("No break")
+}
+```
+
+## 🌟 利点
+
+### 1. 段階的移行支援
+- 既存のPythonプロジェクトを段階的にNyashに移行
+- 変換されたコードを手動で最適化可能
+
+### 2. 学習ツールとして
+- PythonユーザーがNyash構文を学ぶ
+- 両言語の違いを理解
+
+### 3. コード生成
+- Pythonで書いたアルゴリズムをNyashネイティブコードに
+- より高速な実行のための前処理
+
+### 4. 逆方向変換の可能性
+- Nyash → Pythonも将来的に可能
+- 真のバイリンガル環境
+
+## ⚠️ 制限事項と課題
+
+### 1. 完全な互換性は不可能
+- Pythonの動的機能すべては変換できない
+- 一部の構文は手動調整が必要
+
+### 2. 意味論の違い
+```python
+# Pythonのデフォルト引数（定義時評価）
+def f(x, lst=[]):
+    lst.append(x)
+    return lst
+```
+
+```nyash
+// Nyashでは毎回新しいリスト（異なる挙動）
+function f(x, lst) {
+    if (lst == null) {
+        lst = new ArrayBox()
+    }
+    lst.push(x)
+    return lst
+}
+```
+
+### 3. サポートレベルの明示
+```nyash
+// 生成されたファイルのヘッダー
+// Generated from Python by Nyash Transpiler v1.0
+// Original file: script.py
+// Conversion rate: 85% (15/17 functions transpiled)
+// Manual review recommended for: async_func, generator_func
+```
+
+## 📊 実装フェーズ
+
+### Phase 1.5: 基本トランスパイラ（Phase 1と並行）
+- [ ] NyashFormatter実装（AST → ソースコード）
+- [ ] 基本構文の出力（def, if, for, while）
+- [ ] インデント管理
+- [ ] コメント保持（可能な範囲で）
+
+### Phase 2.5: 高度な変換
+- [ ] クラス → Box変換
+- [ ] 特殊メソッド → Nyashメソッド
+- [ ] import文の処理
+
+### Phase 3.5: ツール化
+- [ ] コマンドラインツール
+- [ ] VSCode拡張機能
+- [ ] オンライン変換ツール
+
+## 🎉 期待される効果
+
+1. **Pythonエコシステムの資産をNyashネイティブ化**
+2. **パフォーマンスクリティカルな部分をNyash/MIR/JITで高速化**
+3. **両言語間のシームレスな相互運用**
+4. **Nyashの採用障壁を大幅に下げる**
+
+---
+
+これは**PythonParserBoxの価値をさらに高める**素晴らしい応用です！