hakorune/docs/private/roadmap/phases/phase-20-variant-box

Phase 20.X: VariantBox + enum/match実装

ステータス: PLANNED（Phase 15.7セルフホスト完了後に開始） 期間: 18-27人日（4-6週間、1人体制） 前提条件: Phase 15.7完了、マクロシステム安定化（Phase 16暫定版）

---

🎯 目的

Hakoruneにenum的な表現を追加（MIR16維持、Everything-is-Box原則を守る）

設計元: ChatGPT Pro提案（2025-10-08） 分析完了: ultrathink 4タスク並列分析（整合性・代替案・リスク・影響）

---

📋 実装内容

Phase 20.6: VariantBox Core（3-5人日）

目標: enum的な表現の最小実装（マクロなし）

タスク

• VariantBox実装（2日）

  box VariantBox {
      tag: StringBox           // "Some", "None", "Ok", "Err" 等
      fields: ArrayBox         // 位置引数
  
      birth(tag_str) {
          me.tag = new StringBox(tag_str)
          me.fields = new ArrayBox()
      }
  
      get_tag() { return me.tag }
      get_fields() { return me.fields }
      is_tag(name) { return me.tag.equals(name) }
      field(i) {
          if i < 0 || i >= me.fields.len() {
              panic("VariantBox.field: index out of bounds")
          }
          return me.fields.get(i)
      }
  }
  

• EnumSchemaBox実装（1日）

  static box EnumSchemaBox {
      name: StringBox              // "Result", "Option" 等
      variants: ArrayBox           // ["Ok", "Err"]
  
      register_variant(tag, arity) { ... }
      validate_variant(variant_box) { ... }
  }
  

• 手動コンストラクタテスト（1日）

  // apps/tests/variant_basic.hako
  local some = new VariantBox("Some")
  some.fields.push(42)
  
  if some.is_tag("Some") {
      print(some.field(0))  // → 42
  }
  

成果物:

• apps/lib/boxes/variant_box.hako (50-80行)
• apps/lib/boxes/enum_schema_box.hako (40-60行)
• apps/tests/variant_basic.hako (30-50行)

---

Phase 20.7: @enumマクロ（5-7人日）

目標: @enum構文でコンストラクタ関数を自動生成

タスク

• パーサー@enum対応（2日、Rust側）

  • src/parser/mod.rs: @enum構文追加（100-150行）
  • 新AST型: ASTNode::EnumDeclaration

• @enumマクロ実装（3日、Hakorune側）

  // ユーザーコード
  @enum Result {
      Ok(value)
      Err(error)
  }
  
  // 自動生成（脱糖先）:
  static box Result {
      Ok(value) {
          local v = new VariantBox("Ok")
          v.fields.push(value)
          return v
      }
  
      Err(error) {
          local v = new VariantBox("Err")
          v.fields.push(error)
          return v
      }
  
      is_ok(r) { return r.is_tag("Ok") }
      as_ok(r) { return r.field(0) }
  
      is_err(r) { return r.is_tag("Err") }
      as_err(r) { return r.field(0) }
  }
  

• スモークテスト追加（1日）

  • tools/smokes/v2/profiles/quick/core/enum_basic.sh

成果物:

• src/parser/mod.rs 変更（100-150行）
• apps/macros/enum/enum_macro.hako (100-150行)
• apps/macros/enum/README.md

---

Phase 20.8: @matchマクロ（7-10人日）

目標: パターンマッチング構文（if/else脱糖）

タスク

• パーサー@match対応（3日、Rust側）

  • src/parser/mod.rs: @match構文追加（80-120行）
  • 新AST型: ASTNode::MatchExpression

• @matchマクロ実装（4日、Hakorune側）

  // ユーザーコード
  @match result {
      Ok(v) => console.log(v)
      Err(e) => console.error(e)
  }
  
  // 脱糖先:
  if result.is_tag("Ok") {
      local v = result.field(0)
      console.log(v)
  } else if result.is_tag("Err") {
      local e = result.field(0)
      console.error(e)
  } else {
      panic("Non-exhaustive match")
  }
  

• 網羅性チェック（基本版）（2日）

  • 実行時エラー（panic("Non-exhaustive match")）
  • 静的チェックはPhase 25（型パス）で追加

成果物:

• src/parser/mod.rs 変更（80-120行）
• apps/macros/match/match_macro.hako (150-200行)
• apps/macros/match/README.md

---

Phase 20.9: Option/Result enum化（3-5人日）

目標: 既存Option/ResultBoxをVariantBox版に段階移行

タスク

• VariantBox版Option実装（1日）

  @enum Option {
      Some(value)
      None
  }
  

• VariantBox版Result実装（1日）

  @enum Result {
      Ok(value)
      Err(error)
  }
  

• 段階移行計画実施（2日）

  • 新規コードのみVariantBox版使用
  • 既存ResultBox（selfhost/vm/boxes/result_box.hako）は互換維持
  • 3-5ファイル試験移行

成果物:

• apps/lib/boxes/option.hako (60-80行)
• apps/lib/boxes/result.hako (60-80行)
• 移行ガイド: docs/guides/option-result-migration.md

---

📊 マイルストーン

Phase	成果物	成功基準	リスク
20.6	VariantBox Core	手動コンストラクタで動作	🟢 低
20.7	@enumマクロ	コンストラクタ自動生成	🟡 中（パーサー拡張）
20.8	@matchマクロ	パターンマッチ動作	🟡 中（複雑な脱糖）
20.9	Option/Result	既存コード一部移行	🟢 低

合計: 18-27人日（4-6週間）

---

⚠️ 前提条件

必須

• ✅ Phase 15.7完了（セルフホスト達成）
• ✅ StringBox/ArrayBox/MapBox安定稼働
• ✅ マクロシステム基本機能（Phase 16暫定版で可）

推奨

• StringBox比較の効率化（SymbolBox実装は後回し可能）
• パーサー拡張の経験蓄積

---

🚨 既知のリスク

🔴 クリティカル

1. SymbolBox未実装

   • 対策: Phase 20.6-20.9はStringBoxタグ版で実装
   • SymbolBox（インターン機構）はPhase 25で追加可能

2. @構文パーサー拡張

   • 現状: @構文の実装例なし
   • 対策: Phase 16で@derive実装時に基盤整備

🟡 中程度

3. 網羅性チェック

   • Phase 20では実行時エラーのみ
   • 静的チェックはPhase 25（型パス）で追加

4. 既存コード移行コスト

   • 影響範囲: ResultBox 5箇所のみ（現状）
   • 対策: 段階的移行、互換API維持

---

📚 参考資料

Phase 20設計書

• DESIGN.md - VariantBox完全設計（主要文書）
• RESULT_BOX_COMPLETE_DESIGN.md - Result<T,E> Box完全設計（2025-10-08新規）
• RESULT_BOX_SUMMARY.md - Result Box 1分サマリー
• RESULT_BOX_MIGRATION_PLAN.md - Result Box段階移行計画
• result_box_v2_reference.hako - Result Box参照実装（467行）

実装計画書（2025-10-08新規）

• ENUM_MATCH_PROJECT_PLAN.md - @enum/@match完全プロジェクト計画（12-17日）
  • 日次タスク詳細、リスク分析、成功基準、ロールバック計画
• ENUM_MATCH_QUICK_START.md - クイックスタートガイド（要約版）
  • 3週間スケジュール、重要リスク、日次チェックリスト

設計提案元

• ChatGPT Pro提案（2025-10-08）
• VariantBox設計完全分析（ultrathink 4タスク）

関連Phase

• Phase 16: マクロ革命（@derive実装）
• Phase 20.0-20.5: マクロフル機能（基盤整備）
• Phase 25: 型パス（静的網羅性チェック）

実装参考

• apps/macros/loop_normalize_macro.nyash (393行)
• apps/macros/if_match_normalize_macro.nyash (404行)
• src/macro/pattern.rs (252行)
• selfhost/vm/boxes/result_box.hako (34行、既存実装)

---

🎯 Phase 20内の優先順位

Phase 20.0-20.3（マクロ基盤＋derive＋test）← 🔴 P1（最優先）
    ↓
Phase 20.6-20.9（VariantBox）← 🟢 P2（推奨）
    ↓
Phase 20.4-20.5（Pattern/Quote）← 🟡 P3（必要時）
    ↓
Python統合（Plan B）← 🔵 P4（長期計画）

理由:

• P1: セルフホストコードの生産性向上に直結
• P2: 型安全性向上（オプショナルだが効果大）
• P3: 複雑マクロ用（必要になってから実装）
• P4: Phase 25以降でも可

---

📝 次のアクション

Phase 15.7完了後すぐ

1. Phase 20.0開始（JsonAstBox基盤）
2. Phase 20.6設計レビュー
3. VariantBox Core実装開始

Phase 20.6完了後

1. @enumマクロ設計
2. パーサー@構文拡張計画
3. Phase 20.7実装開始

---

作成日: 2025-10-08 最終更新: 2025-10-08 ステータス: 計画済み、実装待ち