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

2025-10-31 18:00:10 +09:00
parent 1d49e24bf0
commit 8fd3a2b509
433 changed files with 108935 additions and 0 deletions
--- a/docs/private/roadmap/phases/phase-20-python-integration/parser-integration/implementation-plan.md
+++ b/docs/private/roadmap/phases/phase-20-python-integration/parser-integration/implementation-plan.md
@ -0,0 +1,361 @@
+# PythonParserBox実装計画（統合版）
+更新日: 2025-08-27
+
+## 🎯 エキスパートからの統合フィードバック
+
+### 最重要ポイント（両エキスパートが一致）
+1. **関数単位のフォールバック戦略**
+   - ファイル全体でなく関数レベルでコンパイル/フォールバックを切り替え
+   - 未対応機能を含む関数はCPython exec、対応済み関数はNyash MIR/JIT
+
+2. **Python 3.11固定**
+   - AST安定性の確保（3.8 Constant統一、3.10 match/case、3.12位置情報）
+   - `py_version`と`ast_format`をJSON IRに埋め込む
+
+3. **意味論の正確な実装が最優先**
+   - 最適化より先にPython互換性を確保
+   - 特に: イテレータプロトコル、真偽値判定、スコーピング規則（LEGB）
+
+4. **GIL管理の最小化**
+   - Python側でJSON生成（`ast.NodeVisitor` + `json.dumps`）
+   - Rust側で解析（GIL外で実行）
+   - `py.allow_threads(|| { ... })`で重い処理をGIL外実行
+
+5. **テレメトリー重視**
+   - 未対応ノードの記録（`support_level`フィールド）
+   - フォールバック率の計測
+   - ソース位置情報の保持（`lineno/col_offset/end_*`）
+
+### Differential Testing戦略
+- **世界中のPythonコードがNyashのテストケース**
+- CPythonを「オラクル」として使用
+- 出力、戻り値、例外を比較
+- Grammar-based fuzzing（Hypothesis活用）
+
+## 技術的実装方針
+
+### 1. CPythonパーサー統合（pyo3使用）
+```rust
+// Cargo.toml
+[dependencies]
+pyo3 = { version = "0.22", features = ["auto-initialize"] }
+pyo3-numpy = "0.22"  // NumPy連携用
+
+// 初期化（一度だけ）
+pyo3::prepare_freethreaded_python();
+
+// Python側ヘルパー（embedded）
+const PYTHON_HELPER: &str = r#"
+import ast
+import json
+import sys
+
+def parse_to_json(code, filename="<string>", mode="exec"):
+    tree = ast.parse(code, filename, mode)
+    return json.dumps(ast_to_dict(tree))
+
+def ast_to_dict(node):
+    result = {}
+    
+    # 必須フィールド
+    result['node_type'] = node.__class__.__name__
+    result['py_version'] = f"{sys.version_info.major}.{sys.version_info.minor}"
+    
+    # 位置情報（エラー診断用）
+    if hasattr(node, 'lineno'):
+        result['lineno'] = node.lineno
+        result['col_offset'] = node.col_offset
+        if hasattr(node, 'end_lineno'):  # Python 3.8+
+            result['end_lineno'] = node.end_lineno
+            result['end_col_offset'] = node.end_col_offset
+    
+    # サポートレベル（Nyash側で設定）
+    result['support_level'] = 'unknown'
+    
+    # ASTフィールド
+    if isinstance(node, ast.AST):
+        for field in node._fields:
+            value = getattr(node, field)
+            result[field] = ast_to_dict(value)
+    elif isinstance(node, list):
+        return [ast_to_dict(x) for x in node]
+    else:
+        return node
+        
+    return result
+"#;
+```
+
+### 2. 最小実装セット（Phase 1: Must-Have）
+```
+Phase 1 意味論の必須要素（Codex先生強調）:
+- LEGB + locals/freevars（スコーピング）
+- デフォルト引数の評価タイミング（定義時）
+- イテレータベースのfor文
+- for/else + while/else（Python独特）
+- Python真偽値判定（__bool__ → __len__）
+- 短絡評価（and/or）
+
+Phase 1 AST構造:
+├─ Module (py_version, ast_format)
+├─ FunctionDef (name, args, body, decorator_list=[])
+│   └─ arguments (args, defaults, kwonlyargs=[], kw_defaults=[])
+├─ Return (value)
+├─ Assign (targets, value) 
+├─ AugAssign (target, op, value)  # +=, -=等
+└─ Expr (value)
+
+Phase 1 式:
+├─ BinOp (left, op, right)
+│   └─ ops: Add, Sub, Mult, Div, FloorDiv, Mod, Pow
+├─ Compare (left, ops, comparators)
+│   └─ ops: Eq, NotEq, Lt, LtE, Gt, GtE, Is, IsNot
+├─ BoolOp (op, values)  # and/or
+├─ UnaryOp (op, operand)  # not, -, +
+├─ Call (func, args, keywords=[])
+├─ Name (id, ctx=Load/Store/Del)
+├─ Constant (value)  # Python 3.8+統一
+└─ IfExp (test, body, orelse)  # 三項演算子
+
+Phase 1 制御フロー:
+├─ If (test, body, orelse)
+├─ While (test, body, orelse)  # else節対応必須
+├─ For (target, iter, body, orelse)  # else節対応必須
+├─ Break
+└─ Continue
+```
+
+### 3. 関数単位フォールバック戦略
+```rust
+// 関数単位のコンパイル判定
+pub struct FunctionCompiler {
+    supported_nodes: HashSet<&'static str>,
+    telemetry: CompilationTelemetry,
+}
+
+impl FunctionCompiler {
+    pub fn can_compile(&self, func_def: &PythonAst) -> CompileResult {
+        let mut visitor = SupportChecker::new(&self.supported_nodes);
+        visitor.visit(func_def);
+        
+        if visitor.has_unsupported() {
+            // CPython execへフォールバック
+            CompileResult::Fallback {
+                reason: visitor.unsupported_nodes(),
+                location: func_def.location(),
+            }
+        } else {
+            // Nyash MIR/JITへコンパイル
+            CompileResult::Compile
+        }
+    }
+    
+    pub fn compile_module(&mut self, module: &PythonAst) -> ModuleUnit {
+        let mut units = vec![];
+        
+        // モジュールトップレベルはPythonで実行（globals設定）
+        units.push(ExecutionUnit::PythonExec(module.top_level));
+        
+        // 各関数を判定
+        for func in module.functions() {
+            match self.can_compile(func) {
+                CompileResult::Compile => {
+                    let mir = self.compile_to_mir(func);
+                    units.push(ExecutionUnit::NyashFunction(mir));
+                    self.telemetry.record_compiled(func.name);
+                }
+                CompileResult::Fallback { reason, location } => {
+                    units.push(ExecutionUnit::PythonThunk(func));
+                    self.telemetry.record_fallback(func.name, reason, location);
+                }
+            }
+        }
+        
+        ModuleUnit { units }
+    }
+}
+```
+
+### 4. データ共有戦略
+```rust
+// NdArrayBox定義
+pub struct NdArrayBox {
+    base: BoxBase,
+    py_array: Py<PyArray<f64, Dim<[usize; 2]>>>,  // Python側の参照保持
+    // 操作時のみGIL取得してArrayViewを取る
+}
+
+impl NdArrayBox {
+    pub fn to_view(&self) -> PyResult<ArrayView2<f64>> {
+        Python::with_gil(|py| {
+            let array = self.py_array.as_ref(py);
+            Ok(array.readonly())
+        })
+    }
+}
+```
+
+### 4. 実装ロードマップ
+
+#### Phase 1: パーサー統合（1-2週間）
+- [ ] pyo3セットアップとPythonParserBox骨格
+- [ ] Python側parse_to_jsonヘルパー実装
+- [ ] JSON→Nyash AST最小変換
+- [ ] run()メソッド（CPython exec委譲）
+- [ ] 例外変換（PyErr → NyashError）
+
+#### Phase 2: MIR変換（2-4週間）
+- [ ] AST→MIR変換器（最小セット）
+- [ ] 数値演算プリミティブ実装
+- [ ] スコープ解決（関数ローカル/グローバル）
+- [ ] 基本的な制御フロー（If/While）
+
+#### Phase 3: NumPy統合（並行可能）
+- [ ] pyo3-numpy統合
+- [ ] NdArrayBox実装
+- [ ] ゼロコピーベンチマーク
+- [ ] バッファプロトコル対応
+
+#### Phase 4: 最適化と拡張
+- [ ] 型特化とガード最適化
+- [ ] 例外処理（try/except）
+- [ ] クラス/メソッド対応
+- [ ] import統合
+
+## 性能目標（現実的な見積もり）
+
+| コードタイプ | 期待される高速化 | 備考 |
+|------------|----------------|------|
+| 純Pythonループ | 2-10倍 | 型安定なホットパス |
+| 関数呼び出し多 | 1.5-3倍 | インライン化効果 |
+| NumPy処理中心 | 1.0-1.2倍 | 既に最適化済み |
+| 動的特性多用 | 1.2-3倍 | ガード頻発で限定的 |
+
+## 実装上の注意点（エキスパート推奨）
+
+### 意味論の重要な違い（Phase 1で対応必須）
+
+1. **制御フロー**
+   - `for`文: イテレータプロトコル必須（`__iter__`/`__next__`）
+   - `for/else`, `while/else`: breakしなかった場合のelse実行
+   - 短絡評価: `and`は左がFalseなら右を評価しない
+
+2. **スコープ規則（LEGB）**
+   ```python
+   # Local → Enclosing → Global → Builtins
+   global_var = 1
+   
+   def outer():
+       enclosing_var = 2
+       
+       def inner():
+           local_var = 3
+           nonlocal enclosing_var  # 明示的な宣言
+           global global_var       # 明示的な宣言
+   ```
+
+3. **数値演算の違い**
+   - `/`: Python 3では常にfloat（true division）
+   - `//`: floor division（整数除算）
+   - 大整数: デフォルトで無限精度
+   - `is` vs `==`: オブジェクト同一性 vs 値の等価性
+
+4. **関数定義の罠**
+   ```python
+   def f(x, y=[]): # デフォルト引数は定義時に1度だけ評価！
+       y.append(x) # 全呼び出しで同じリストを共有
+       return y
+   ```
+
+### GIL管理のベストプラクティス
+
+```rust
+// ❌ 悪い例: GILを長時間保持
+let result = Python::with_gil(|py| {
+    let ast = parse_python(py, code)?;
+    let json = convert_to_json(py, ast)?;  // ここまでGIL必要
+    let nyash_ast = parse_json(&json)?;    // GIL不要なのに保持
+    compile_to_mir(nyash_ast)?             // GIL不要なのに保持
+});
+
+// ✅ 良い例: GILを最小限に
+let json = Python::with_gil(|py| {
+    let ast = parse_python(py, code)?;
+    convert_to_json(py, ast)  // JSON生成まで
+})?;
+
+// GIL外で重い処理
+let nyash_ast = parse_json(&json)?;
+let mir = compile_to_mir(nyash_ast)?;
+
+// 必要時のみ再取得
+Python::with_gil(|py| {
+    py.allow_threads(|| {
+        // 時間のかかるRust処理
+        optimize_mir(mir)
+    })
+})
+```
+
+### テレメトリーとデバッグ
+
+```rust
+// 環境変数で制御
+NYASH_PYTHONPARSER_TELEMETRY=1      # 基本統計
+NYASH_PYTHONPARSER_TELEMETRY=2      # 詳細ログ
+NYASH_PYTHONPARSER_STRICT=1         # フォールバック時にパニック（CI用）
+
+// 出力例
+[PythonParser] Module: example.py
+  Functions: 10 total
+  Compiled: 7 (70%)
+  Fallback: 3 (30%)
+    - async_function: unsupported node 'AsyncFunctionDef' at line 23
+    - generator_func: unsupported node 'Yield' at line 45  
+    - class_method: unsupported node 'ClassDef' at line 67
+```
+
+## 次のステップ
+
+### 即座に開始すべきこと
+
+1. **Python 3.11環境固定**
+   ```bash
+   pyenv install 3.11.9
+   pyenv local 3.11.9
+   ```
+
+2. **最小動作確認**
+   ```python
+   # test_minimal.py
+   def add(x, y):
+       return x + y
+   
+   result = add(10, 5)
+   print(f"Result: {result}")  # → Nyashで15が出力されれば成功！
+   ```
+
+3. **テレメトリー基盤構築**
+   - 未対応ノードの記録システム
+   - フォールバック率の可視化
+   - ソース位置情報の保持
+
+4. **Differential Testingの準備**
+   - CPythonとの出力比較フレームワーク
+   - 標準出力、戻り値、例外のキャプチャ
+   - テストコーパスの選定
+
+### 成功の測定基準
+
+| フェーズ | 目標 | 測定指標 |
+|---------|------|----------|
+| Phase 1 | 基本動作 | 簡単な数値計算の70%がコンパイル可能 |
+| Phase 2 | 実用性 | scikit-learnの基本アルゴリズムが動作 |
+| Phase 3 | 性能 | 純Pythonループで5倍以上の高速化 |
+| Phase 4 | 成熟度 | PyPIトップ100の30%が基本動作 |
+
+## まとめ
+
+このPythonParserBox実装は、単なる機能追加ではなく、Nyash言語の成熟度を飛躍的に高める戦略的プロジェクト。
+エキスパートの指摘を踏まえ、関数単位のフォールバック、Python 3.11固定、意味論の正確な実装、
+GIL最小化、テレメトリー重視で着実に実装を進める。