# Phase 31.3 Quick Start Guide

**すぐに始められるSelfhost綺麗綺麗計画の最初のステップ**

---

## Week 1 の即座実行タスク（今すぐ開始可能！）

### タスク1: コード品質分析（15分）

```bash
cd /home/tomoaki/git/hakorune-selfhost

# Compiler分析
bash -c 'for file in selfhost/compiler/pipeline_v2/*.hako; do \
  lines=$(wc -l < "$file"); \
  name=$(basename "$file"); \
  echo "$lines $name"; \
done | sort -rn' > docs/private/roadmap/phases/phase-31.3/QUALITY_ANALYSIS_COMPILER.txt

# VM分析
bash -c 'for file in selfhost/hakorune-vm/*.hako; do \
  lines=$(wc -l < "$file"); \
  name=$(basename "$file"); \
  echo "$lines $name"; \
done | sort -rn' > docs/private/roadmap/phases/phase-31.3/QUALITY_ANALYSIS_VM.txt

# 結果確認
cat docs/private/roadmap/phases/phase-31.3/QUALITY_ANALYSIS_COMPILER.txt | head -10
cat docs/private/roadmap/phases/phase-31.3/QUALITY_ANALYSIS_VM.txt | head -10
```

**期待結果**:
```
# Compiler TOP 10
535 pipeline.hako               ⚠️ 巨大関数（要分割）
249 using_resolver_box.hako    ⚠️ 要リファクタリング
209 stage1_extract_flow.hako
187 local_ssa_box.hako
...

# VM TOP 10
315 closure_call_handler.hako  ⚠️ 巨大関数（要分割）
267 terminator_handler.hako    ⚠️ 要リファクタリング
235 hakorune_vm_core.hako
234 phi_handler.hako
...
```

---

### タスク2: TraceBox実装（30分）

#### Step 1: ディレクトリ作成
```bash
mkdir -p selfhost/shared/trace
```

#### Step 2: TraceBox実装

**ファイル**: `selfhost/shared/trace/trace_box.hako`

```hakorune
// TraceBox - 統一トレース出力システム
// Rust LoopTraceBox の Hakorune版移植
// Usage: HAKO_TRACE=1 で有効化

static box TraceBox {
  enabled: IntegerBox
  prefix: StringBox

  // Constructor
  birth(enabled, prefix) {
    me.enabled = enabled
    me.prefix = prefix
  }

  // Basic logging
  log(message) {
    if me.enabled == 1 {
      print(me.prefix + message)
    }
  }

  // Conditional logging
  log_if(condition, message) {
    if me.enabled == 1 && condition == 1 {
      print(me.prefix + message)
    }
  }

  // Formatted logging with value
  log_value(label, value) {
    if me.enabled == 1 {
      print(me.prefix + label + ": " + value)
    }
  }

  // Multi-value logging
  log_values(label, value1, value2) {
    if me.enabled == 1 {
      print(me.prefix + label + ": " + value1 + ", " + value2)
    }
  }

  // Error logging (always enabled)
  error(message) {
    print("[ERROR] " + me.prefix + message)
  }
}
```

**行数**: 約50行 ✅

#### Step 3: hako.toml に追加

**ファイル**: `selfhost/shared/hako.toml`（既存ファイルに追加）

```toml
[exports]
# 既存のexports...
trace = "trace/trace_box.hako"
```

#### Step 4: 動作確認

**テストファイル**: `apps/examples/trace_test.hako`

```hakorune
using selfhost.shared.trace as TraceBox

static box Main {
  main() {
    // トレース有効（enabled=1）
    local trace = new TraceBox(1, "[Test] ")

    trace.log("Starting test")
    trace.log_value("x", 42)
    trace.log_values("a, b", 10, 20)
    trace.log_if(1, "Condition is true")
    trace.log_if(0, "This should NOT appear")

    // トレース無効（enabled=0）
    local silent = new TraceBox(0, "[Silent] ")
    silent.log("This should NOT appear")

    // エラーは常に表示
    trace.error("This is an error")

    return 0
  }
}
```

**実行**:
```bash
./target/release/hakorune apps/examples/trace_test.hako
```

**期待出力**:
```
[Test] Starting test
[Test] x: 42
[Test] a, b: 10, 20
[Test] Condition is true
[ERROR] [Test] This is an error
```

---

### タスク3: 既存コードへのTraceBox適用（30分）

#### Step 1: pipeline.hakoの冒頭でTraceBox初期化

**ファイル**: `selfhost/compiler/pipeline_v2/pipeline.hako`（既存、編集）

```hakorune
// 既存のusing文に追加
using selfhost.shared.trace as TraceBox

flow PipelineV2 {
  lower_stage1_to_mir_trace(ast_json, prefer_cfg, trace_flag) {
    // TraceBox初期化
    local trace = new TraceBox(trace_flag, "[Pipeline] ")

    trace.log("Start: prefer_cfg=" + prefer_cfg)

    // 既存のコード...
    if ast_json == null {
      trace.error("ast_json is null")
      return EmitReturnBox.emit_return_int2(0, 0)
    }

    // ... 処理 ...

    trace.log("Complete")
    return mir_json
  }
}
```

#### Step 2: 既存のprint()をtraceに置換（5-10箇所）

**置換パターン**:
```hakorune
// Before
print("[DEBUG] Some message: " + value)

// After
trace.log_value("Some message", value)
```

**対象ファイル**（優先順位順）:
1. `pipeline.hako`（3-5箇所）
2. `local_ssa_box.hako`（2-3箇所）
3. `using_resolver_box.hako`（1-2箇所）

#### Step 3: 動作確認

```bash
# トレース無効（デフォルト）
./target/release/hakorune apps/selfhost-compiler/main.hako

# トレース有効
# 注: HAKO_TRACE環境変数の実装は後で（今は trace_flag=1 で直接指定）
# 暫定的に pipeline.hako 内で trace_flag を 1 にして実行
```

---

## Week 1 の達成目標

### ✅ 完了チェックリスト

- [ ] **タスク1**: コード品質分析完了（QUALITY_ANALYSIS_*.txt作成）
- [ ] **タスク2**: TraceBox実装完了（trace_box.hako, 50行）
- [ ] **タスク3**: 既存コードへのTraceBox適用（5-10箇所）
- [ ] **テスト**: trace_test.hako実行成功
- [ ] **ドキュメント**: SELFHOST_QUALITY_REPORT.md作成開始

### 📊 成果物

- `QUALITY_ANALYSIS_COMPILER.txt`: Compiler品質分析
- `QUALITY_ANALYSIS_VM.txt`: VM品質分析
- `selfhost/shared/trace/trace_box.hako`: TraceBox実装（50行）
- `apps/examples/trace_test.hako`: TraceBoxテスト
- 既存コードのTraceBox適用（5-10箇所）

### 📈 削減/追加行数

- **追加**: +50行（TraceBox）
- **変更**: 5-10箇所（既存のprint()をtraceに置換）

---

## Week 2 の準備（余裕があれば）

### CompilerConfigBox実装の準備

**ファイル**: `selfhost/compiler/pipeline_v2/compiler_config_box.hako`（新規）

```hakorune
// CompilerConfigBox - コンパイラ設定の一元管理
// Rust ConfigBox の Hakorune版

box CompilerConfigBox {
  prefer_cfg: IntegerBox
  trace_enabled: IntegerBox
  trace: TraceBox

  birth(prefer_cfg, trace_enabled) {
    me.prefer_cfg = prefer_cfg
    me.trace_enabled = trace_enabled
    me.trace = new TraceBox(trace_enabled, "[Config] ")

    me.trace.log_value("prefer_cfg", prefer_cfg)
    me.trace.log_value("trace_enabled", trace_enabled)
  }

  get_prefer_cfg() {
    return me.prefer_cfg
  }

  get_trace() {
    return me.trace
  }
}
```

**行数**: 約30行

---

## トラブルシューティング

### Q1: TraceBoxのusing文でエラーが出る

**エラー**:
```
Unknown module: selfhost.shared.trace
```

**解決**:
1. `selfhost/shared/hako.toml` に `trace = "trace/trace_box.hako"` を追加したか確認
2. ファイルパスが正しいか確認: `selfhost/shared/trace/trace_box.hako`
3. hako.tomlのsyntaxエラーがないか確認（TOML形式）

---

### Q2: TraceBox.birth()でエラーが出る

**エラー**:
```
Constructor birth not found
```

**解決**:
TraceBoxは `static box` ではなく `box` として定義する（インスタンス化が必要）

**修正**:
```hakorune
// ❌ 誤り
static box TraceBox { ... }

// ✅ 正しい
box TraceBox { ... }  // staticなし
```

---

### Q3: TraceBoxのlog()が何も出力しない

**原因**: `enabled = 0` で初期化されている

**確認**:
```hakorune
local trace = new TraceBox(1, "[Test] ")  // enabled=1 にする
trace.log("Test message")
```

---

## 次のステップ

Week 1完了後:
1. **SELFHOST_QUALITY_REPORT.md作成**（分析結果のまとめ）
2. **Week 2開始**: 箱化パターン確立
3. **CompilerConfigBox実装**（30行）
4. **LoopStateBox実装**（80行）

詳細: [SELFHOST_CLEANUP_PLAN.md](./SELFHOST_CLEANUP_PLAN.md)

---

**今すぐ始めましょう！** 🚀

```bash
# コマンド1つでWeek 1タスク1開始
cd /home/tomoaki/git/hakorune-selfhost && \
bash -c 'for file in selfhost/compiler/pipeline_v2/*.hako; do \
  lines=$(wc -l < "$file"); \
  name=$(basename "$file"); \
  echo "$lines $name"; \
done | sort -rn' > docs/private/roadmap/phases/phase-31.3/QUALITY_ANALYSIS_COMPILER.txt && \
echo "✅ QUALITY_ANALYSIS_COMPILER.txt created!"
```