hakorune/docs/private/roadmap/phases/phase-20.24/README.md

# Phase 20.24 — Parser削除（Instant Value Delivery）

**期間**: 1-2ヶ月
**ステータス**: 計画更新（Rust Floor方針に整合）
**前提条件**: Phase 20.23（Arc/RefCell）完了

---

## 🎯 Executive Summary

**Purpose**: Rust Parser/AST を削除し、Hakorune Parser に完全移行。

**Key Benefit**: **即座の価値提供** - 最も安全で最も早く結果が出るフェーズ

### Why Parser First?

| 観点 | Parser削除 | Box System削除 |
|------|-----------|---------------|
| **リスク** | ✅ 超低（完全重複） | ⚠️ 中（複雑な依存） |
| **ブロッカー** | ✅ なし | ❌ Arc/RefCell必須 |
| **削減行数** | **-10,500行** | -2,393行 |
| **検証容易性** | ✅ 高（既存テスト） | ⚠️ 中（新規テスト必要） |
| **ロールバック** | ✅ 1 commit revert | ⚠️ 複雑 |

**結論**: Parser を先に削除することで、早期に大幅な削減を達成し、プロジェクトの勢いを維持。

---

## 📊 削減内容

### Target Files（-10,500行）

```
src/parser/              -6,000 lines  ← 完全重複（lang/src/compiler/parser/）
src/ast/                 -4,500 lines  ← 完全重複（lang/src/compiler/ast/）
────────────────────────────────────────
Total:                  -10,500 lines  ← 全体の 9.0% 削減
```

### Duplication Verification

**Rust Parser**: `src/parser/` (6,000 lines)
```rust
// src/parser/statement.rs
pub fn parse_statement(&mut self) -> Result<Statement> { /* ... */ }

// src/parser/expression.rs
pub fn parse_expression(&mut self) -> Result<Expression> { /* ... */ }
```

**Hakorune Parser**: `lang/src/compiler/parser/` (完全実装済み)
```hakorune
// lang/src/compiler/parser/statement_parser.hako
static box StatementParser {
  parse_statement() { /* ... */ }
}

// lang/src/compiler/parser/expression_parser.hako
static box ExpressionParser {
  parse_expression() { /* ... */ }
}
```

**検証結果**: ✅ 完全重複、機能的パリティ達成済み

---

## 🏗️ Implementation Plan（Rust Floor 整合）

### Month 1: Gate Implementation & Validation

#### Week 1: Gate Infrastructure（ゲート機構構築）

**実装内容（CLI先行・ENVは補助）**:
```rust
// src/cli/mod.rs

#[derive(Debug)]
pub enum ParserBackend {
    Rust,      // Legacy (default for now)
    Hakorune,  // New (opt-in)
}

// CLI: --parser=rust|hako（ENVは HAKO_PARSER_BACKEND=rust|hako をエイリアス）
pub fn get_parser_backend() -> ParserBackend {
    if let Some(v) = cli_opts.parser_backend() { return v; }
    match env::var("HAKO_PARSER_BACKEND").ok().as_deref() {
        Some("hako") => ParserBackend::Hakorune,
        _ => ParserBackend::Rust,
    }
}

// src/main.rs
fn run_compiler(args: &Args) -> Result<()> {
    match get_parser_backend() {
        ParserBackend::Rust => {
            // Existing path
            let ast = parser::parse(&source)?;
            // ...
        }
        ParserBackend::Hakorune => {
            // NEW path — Stage‑1 JSON → FlowEntryBox → MIR(JSON)
            // Avoid AST deserialize in Rust; use existing selfhost pipeline entry
            let stage1 = call_hakorune_stage1_json(&source)?;
            let mir = call_flow_entry_emit(&stage1, prefer_cfg = 0)?;
            // downstream keeps operating on MIR(JSON)
        }
    }
}
```

**Tasks**:
- [ ] `HAKO_USE_RUST_PARSER` 環境変数追加
- [ ] Parser backend selection logic
- [ ] Hakorune parser plugin call infrastructure
- [ ] AST JSON serialization/deserialization
- [x] Floor crates scaffold（`crates/floor-parser`, `crates/floor-ast`）追加（責務/ガード/READMEのみ、未配線）
 - [x] Default flip: CLI未指定時は既定で `hako`（Fail‑Fast; TTL `HAKO_PARSER_AUTO_FALLBACK=1` でレガシー降格可）

**Acceptance**:
- [ ] `--parser=hako`（または `HAKO_PARSER_BACKEND=hako`）で Hakorune 経路
- [ ] 既定は Rust（互換）。反転は quick/integration が緑で1リリース観測後
- [ ] 比較対象は AST ではなく Stage‑1 JSON と MIR(JSON) の形状（パリティ）

#### Week 2-3: Full Smoke Test Validation

**Testing Strategy**:
```bash
# Phase 1: Core smoke tests（quick profile）
HAKO_USE_RUST_PARSER=0 tools/smokes/v2/run.sh --profile quick

# Phase 2: Integration tests（integration profile）
HAKO_USE_RUST_PARSER=0 tools/smokes/v2/run.sh --profile integration

# Phase 3: Full test suite（all profiles）
HAKO_USE_RUST_PARSER=0 tools/smokes/v2/run.sh --profile all
```

**Expected Results**:
- [ ] **quick**: 100% PASS（~100 tests, 1-2分）
- [ ] **integration**: 100% PASS（~200 tests, 5-10分）
- [ ] **all**: 100% PASS（296 tests, 15-30分）

**Failure Handling**:
- **Zero tolerance**: 1つでも失敗 → Week 3 で原因調査・修正
- **Parity verification**: AST diff で Rust vs Hakorune 完全一致確認

#### Week 4: CI Integration & Documentation

**CI Setup**:
```yaml
# .github/workflows/parser_parity.yml
name: Parser Parity Check
on: [push, pull_request]
jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - name: Test Rust Parser
        run: tools/smokes/v2/run.sh --profile quick

      - name: Test Hakorune Parser
        env:
          HAKO_USE_RUST_PARSER: 0
        run: tools/smokes/v2/run.sh --profile quick

      - name: Compare AST outputs
        run: |
          diff rust_ast.json hakorune_ast.json || exit 1
```

**Documentation**:
- [ ] Migration guide: Rust Parser → Hakorune Parser
- [ ] Troubleshooting: よくある問題と対処法
- [ ] Performance comparison: 速度・メモリ使用量
- [ ] Rollback plan: 問題発生時の切り戻し手順

---

### Month 2: Deletion & Cleanup

#### Week 1: Default Flip（デフォルト切り替え）

**Change default backend**:
```rust
// src/cli/mod.rs
pub fn get_parser_backend() -> ParserBackend {
    match env::var("HAKO_USE_RUST_PARSER") {
        Ok(val) if val == "1" => ParserBackend::Rust,  // Opt-in (legacy)
        _ => ParserBackend::Hakorune,  // NEW DEFAULT ✅
    }
}
```

**Deprecation Warning**:
```rust
fn run_compiler(args: &Args) -> Result<()> {
    if matches!(get_parser_backend(), ParserBackend::Rust) {
        eprintln!("Warning: Rust parser is deprecated and will be removed in Phase 20.25.");
        eprintln!("         Use Hakorune parser (default) or set HAKO_USE_RUST_PARSER=0.");
    }
    // ...
}
```

**Tasks**:
- [ ] Flip default: Hakorune parser が標準
- [ ] Deprecation warning 追加
- [ ] Documentation 更新（default 変更通知）

#### Week 2: Archive → Deletion（段階削除）

**Deletion targets**:
```bash
# Backup first (safety)
git tag phase-20.24-pre-deletion
git branch backup/rust-parser

# Delete parser
mv src/parser/ archive/legacy/parser/
mv src/ast/    archive/legacy/ast/
# 参照ゼロをCIで確認し、1リリース後に完全削除

# Update imports
# Remove all `use crate::parser::*` references
# Remove all `use crate::ast::*` references
```

**Affected files** (~50 files need import cleanup):
- `src/main.rs`
- `src/cli/*.rs`
- `src/mir/builder.rs`
- Tests: `tests/**/*.rs`

**Tasks**:
- [ ] Git tag/branch for safety
- [ ] Delete `src/parser/` and `src/ast/`
- [ ] Remove imports（50ファイル）
- [ ] Cargo.toml dependency cleanup
- [ ] Full rebuild & test

#### Week 3: Integration Testing

**Validation**:
```bash
# Clean build
cargo clean
cargo build --release

# Full smoke test suite
tools/smokes/v2/run.sh --profile all

# Regression tests
cargo test --all

# Performance benchmark
tools/bench_unified.sh --backend all --warmup 10 --repeat 50
```

**Expected**:
- [ ] **Build success**: No compilation errors
- [ ] **Tests**: 100% PASS（296/296）
- [ ] **Performance**: No regression（±5% 許容）
- [ ] **Binary size**: -500KB reduction（目安）

#### Week 4: Documentation & Rollback Plan

**Documentation Updates**:
- [ ] CHANGELOG.md: Parser deletion 記録
- [ ] README.md: "Hakorune Parser only" 明記
- [ ] Architecture docs: Parser flow diagram 更新
- [ ] Migration guide: 完全版

**Rollback Plan**:
```bash
# If critical issue found
git revert <deletion_commit>
git cherry-pick backup/rust-parser

# Or restore from tag
git checkout phase-20.24-pre-deletion
git checkout -b phase-20.24-rollback
```

**Final Checks**:
- [ ] All CI passing
- [ ] Documentation complete
- [ ] Rollback tested（dry run）
- [ ] Phase 20.24 completion announcement

---

## ✅ 受け入れ基準（Acceptance Criteria）

### Functional Requirements

- [ ] **Rust Parser 完全削除**: `src/parser/`, `src/ast/` 不存在
- [ ] **Hakorune Parser デフォルト**: `HAKO_USE_RUST_PARSER` 不要
- [ ] **全テスト PASS**: 296/296 smoke tests
- [ ] **Parity 検証**: Rust vs Hakorune AST 完全一致（Month 1 で確認済み）

### Performance Requirements

- [ ] **Parse speed**: ±10% 以内（regression なし）
- [ ] **Memory usage**: ±10% 以内
- [ ] **Binary size**: -500KB 削減（目安）

### Safety Requirements

- [ ] **Rollback tested**: Git tag からの復元成功
- [ ] **Backup branch**: `backup/rust-parser` 存在
- [ ] **CI verification**: Parser parity check 毎日実行

### Documentation Requirements

- [ ] **Migration guide**: Rust → Hakorune 完全版
- [ ] **Architecture update**: Parser flow 最新化
- [ ] **CHANGELOG**: 削除内容明記
- [ ] **Rollback plan**: 手順書完備

---

## 🚨 リスク分析と軽減策

### Risk Matrix

| リスク | 確率 | 影響 | 軽減策 |
|--------|------|------|--------|
| **Hakorune parser バグ** | 低 | 高 | Month 1 で徹底検証（296 tests） |
| **Import 削除ミス** | 中 | 低 | Cargo build check + CI |
| **Performance 劣化** | 低 | 中 | Benchmark driven + rollback |
| **Rollback 失敗** | 極低 | 高 | Git tag + backup branch |
| **依存関係見落とし** | 低 | 中 | Cargo check --all-targets |

### Mitigation Strategies

1. **Extensive Testing**: Month 1 で 100% テスト通過確認
2. **Git Safety Net**: Tag + branch で即座に復元可能
3. **Incremental Approach**: Week 1 gate → Week 2 flip → Week 3 delete
4. **CI Automation**: 毎日 parser parity check
5. **Documentation First**: 問題発生前に rollback plan 完備

---

## 📈 Timeline Visualization

```
Month 1: Gate & Validation
├─ Week 1: Gate infrastructure     [████░░░░] HAKO_USE_RUST_PARSER=0
├─ Week 2-3: Full smoke testing    [████████] 296/296 PASS
└─ Week 4: CI + Documentation      [████░░░░] Parity check automation

Month 2: Deletion & Cleanup
├─ Week 1: Default flip            [████░░░░] Hakorune default
├─ Week 2: File deletion           [████████] -10,500 lines ⚡
├─ Week 3: Integration testing     [████████] 100% PASS
└─ Week 4: Docs & Rollback plan    [████░░░░] Completion ✅
```

**Total Duration**: 8 weeks = 2 months

---

## 💡 Strategic Value（戦略的価値）

### Immediate Benefits

1. **Codebase Size**: -10,500 lines（-9.0%）
2. **Maintenance Burden**: Parser を1つに統一
3. **Confidence Boost**: 大幅削減を早期達成
4. **Risk Reduction**: 最も安全なフェーズから開始

### Long-term Impact

- **Phase 20.25 準備**: Parser 削除成功 → MIR Builder 削除への道筋
- **Community Trust**: 計画通り進行でステークホルダー信頼獲得
- **Momentum**: 早期成功でチーム士気向上

### Comparison with Alternative Orders

**Option A: Arc/RefCell First, Parser Second（This Plan）**
```
Phase 20.23: Arc/RefCell (2-3 weeks)   ← Low risk, foundation
Phase 20.24: Parser削除 (1-2 months)    ← Instant value ⚡
Total: ~3 months
```

**Option B: Parser First, Arc/RefCell Second**
```
Phase 20.23: Parser削除 (1-2 months)    ← Instant value ⚡
Phase 20.24: Arc/RefCell (2-3 weeks)   ← Low risk, foundation
Total: ~3 months
```

**Option C: Parallel Tracks**
```
Track A: Arc/RefCell + Box System (3-5 months)
Track B: Parser + MIR Builder (4-8 months)
Total: 4-8 months (higher coordination overhead)
```

**Recommendation**: **Option A**（This Plan）
- Arc/RefCell は Box System の基盤（Phase 20.25 で必須）
- Parser 削除は独立しており Arc/RefCell 不要
- 順序: Foundation → Value の自然な流れ

---

## 🔗 関連ドキュメント

- **Phase 20.23**: [Arc/RefCell in Hakorune](../phase-20.23/README.md) - 前提フェーズ
- **Phase 20.25**: [Box System + MIR Builder削除](../phase-20.25/README.md) - 次のフェーズ
- **Rust Removal Roadmap**: [rust-removal-comprehensive-roadmap.md](../../../development/analysis/rust-removal-comprehensive-roadmap.md)
- **Parser Design**: `lang/src/compiler/parser/README.md` - Hakorune Parser 仕様

---

## 🎉 Expected Outcome（期待される成果）

### Before Phase 20.24

```
src/                    99,406 lines (85.1%)
├── parser/              6,000 lines ❌
├── ast/                 4,500 lines ❌
├── mir/                13,635 lines
└── other/              75,271 lines
```

### After Phase 20.24

```
src/                    88,906 lines (76.1%) ✅
├── parser/              (DELETED)     -6,000 lines ⚡
├── ast/                 (DELETED)     -4,500 lines ⚡
├── mir/                13,635 lines
└── other/              75,271 lines

Total reduction: -10,500 lines (-9.0%)
```

**Key Achievement**: ✅ **10% codebase reduction in 2 months**

---

**ステータス**: 未開始
**開始可能条件**: Phase 20.23（Arc/RefCell）完了
**期間**: 1-2ヶ月（8週間）
**次フェーズ**: Phase 20.25（Box System + MIR Builder削除）