hakorune/docs/development/current/main/phases/phase-287/README.md

# Phase 287: Developer Hygiene（big files / smoke / normalizer）

**Status**: In progress (P0/P1 complete, P2 next)
**Date**: 2025-12-27
**Previous**: Phase 286 (Plan Line完全運用化)

## 概要（SSOT）

Phase 287 は「開発導線の整備（意味論不変）」を優先して、巨大ファイルの責務分離（big files refactoring）と、既存の hygiene（smoke/normalizer）を扱う。

## 2025-12-27 Update: Big Files Refactoring（P0）✅

`merge/mod.rs` を modularize（意味論不変）し、SSOT（boundary-first / continuation SSOT）を強化した。

- 入口: `docs/development/current/main/phases/phase-287/P0-BIGFILES-REFACTORING-INSTRUCTIONS.md`

## 2025-12-27 Update: AST Feature Extractor modularization（P1）✅

`ast_feature_extractor.rs` を facade にして、`pattern_recognizers/` 配下へ recognizer 単位で分割した（意味論不変）。

- 入口: `docs/development/current/main/phases/phase-287/P1-AST_FEATURE_EXTRACTOR-INSTRUCTIONS.md`
- 次（P2）: `docs/development/current/main/phases/phase-287/P2-CONTRACT_CHECKS-MODULARIZATION-INSTRUCTIONS.md`

---

## Next (P2)

- `contract_checks.rs` を facade 化して、契約検証を “1 module = 1 契約” に分割する（意味論不変）。
  - 指示書: `docs/development/current/main/phases/phase-287/P2-CONTRACT_CHECKS-MODULARIZATION-INSTRUCTIONS.md`

---

## Legacy / Historical (2025-12-26 plan)

以下は「Phase 287 を hygiene として計画していた時期のログ」。今後の候補として残すが、P0/P1（big files）とは別系統。

### Legacy docs（smoke quick）

- P1（legacy）: quick 軽量化（~45s 目標）: `docs/development/current/main/phases/phase-287/P1-INSTRUCTIONS.md`
- P2（legacy, optional）: quick をさらに 45s へ寄せる: `docs/development/current/main/phases/phase-287/P2-INSTRUCTIONS.md`

## Phase 286 完了作業（historical）

### ✅ Legacy Pattern5 削除（488行）

**削除理由**: Plan line 完全運用化により、legacy Pattern5 は完全にデッドコード化

**削除ファイル**:
- `src/mir/builder/control_flow/joinir/patterns/pattern5_infinite_early_exit.rs` (488行)

**関連削除**:
- `router.rs` の `LOOP_PATTERNS` テーブルから Pattern5 エントリ削除
- `mod.rs` から `pub mod pattern5_infinite_early_exit;` 削除
- `router.rs` のドキュメント更新（Pattern5 → Pattern4 優先順位へ）

**影響範囲**:
- Pattern5 は Plan line の `extract_pattern5_plan()` 経由で処理されるため、機能退行なし
- `LOOP_PATTERNS` テーブルの優先順位: Pattern5 → Pattern4 → Pattern8... から Pattern4 → Pattern8... に変更

### ✅ Warning クリーンアップ

**実行コマンド**:
```bash
cargo fix --lib -p nyash-rust --allow-dirty
```

**修正内容**:
- 1件の自動修正（`normalizer.rs`）
- 未使用 import などを自動修正

### ✅ ビルド＆テスト確認

**ビルド結果**:
```bash
cargo build --release
# → 成功（130 warnings、エラーなし）
```

**テスト結果**:
```bash
tools/smokes/v2/run.sh --profile quick
# → 154/154 PASS ✅
```

**退行なし**: quick smoke 154/154 PASS を維持

## 削除前後の統計

### コード削減

| 項目 | 削減数 |
|------|--------|
| ソースファイル | 1ファイル (pattern5_infinite_early_exit.rs) |
| 総削減行数 | 488行 |
| router.rs エントリ | 5行（Pattern5 エントリ） |
| mod.rs 宣言 | 1行 |

### Pattern優先順位の変更

**削除前**（Phase 131-11+）:
```
Pattern5 (most specific) → Pattern4 → Pattern3 → Pattern1 → Pattern2
```

**削除後**（Phase 286+）:
```
Pattern4 → Pattern8 → Pattern9 → Pattern3 → Pattern1 → Pattern2
```

**注**: Pattern5/6/7 は Plan line 経由で処理（`PLAN_EXTRACTORS` テーブル）

## Legacy backlog (post-2025-12-27)

### (legacy) normalizer.rs 分割計画

**現状**: `src/mir/builder/control_flow/plan/normalizer.rs` が大きすぎる（推定 1,500+ 行）

**分割案**:

#### 1. Pattern5 正規化ロジック分離（430行）
- `normalizer/pattern5.rs` - Pattern5 専用正規化
- Pattern5 の複雑な構造展開ロジックを独立モジュール化

#### 2. Helper 関数共通化（700行）
- `normalizer/helpers.rs` - 共通ヘルパー関数
- 複数パターンで使用される変換ロジック

#### 3. コアロジック残存（300行）
- `normalizer.rs` - PlanNormalizer struct & normalize() エントリーポイント
- パターン横断的な正規化インターフェース

**期待効果**:
- メンテナンス性向上
- テスト分離（Pattern5 正規化のみをユニットテスト）
- 責任分離（SRP原則）

### (legacy) LOOP_PATTERNS テーブル完全削除

**背景**: 全Pattern が Plan line 経由になれば、`LOOP_PATTERNS` テーブルは不要

**前提条件**:
- Pattern1-4 の Plan line 移行完了（Phase 286 でPattern1-4はPlan line化済み）
- Pattern8-9 の Plan line 移行完了（Phase 286 でPlan line化済み）

**削除対象**:
- `router.rs` の `LOOP_PATTERNS` static テーブル（40行程度）
- `LoopPatternEntry` struct（不要化）

**残存**:
- `PLAN_EXTRACTORS` テーブルのみ（SSOT）

**期待効果**:
- 二重管理解消（LOOP_PATTERNS vs PLAN_EXTRACTORS）
- ルーティングロジック一本化

## 実装方針

### フェーズ分割

1. **Phase 286（完了）**: Legacy Pattern5 削除 + Warning クリーンアップ
2. **Phase 287-P0（保留）**: normalizer.rs 分割（P0優先度は低い）
3. **Phase 287-P1（将来）**: LOOP_PATTERNS テーブル削除（全Pattern Plan line化後）

### 段階的移行

- 急がない：normalizer.rs 分割は緊急度低（機能的に問題なし）
- 機会を待つ：P1 はPattern1-4完全移行のタイミングで実施

## 関連ドキュメント

- [Phase 286 計画](../phase-286/README.md) - Plan Line完全運用化
- [Plan Line アーキテクチャ](../../design/plan-line-architecture.md) - Extractor → Normalizer → Verifier → Lowerer
- [Pattern移行ログ](../phase-273/README.md) - Pattern6/7 Plan line移行（Phase 273）

## 検証項目

### ✅ Phase 286 完了検証

- [x] Pattern5 ファイル削除（488行）
- [x] router.rs の LOOP_PATTERNS から Pattern5 エントリ削除
- [x] mod.rs から Pattern5 宣言削除
- [x] `cargo fix` 実行（Warning クリーンアップ）
- [x] `cargo build --release` 成功（0エラー）
- [x] quick smoke 154/154 PASS
- [x] Phase 287 ドキュメント作成

### 📋 Phase 287-P0/P1 検証（将来）

- [ ] normalizer.rs 分割完了（P0）
  - [ ] pattern5.rs 独立（430行）
  - [ ] helpers.rs 共通化（700行）
  - [ ] normalizer.rs 縮小（300行）
- [ ] LOOP_PATTERNS テーブル削除（P1）
  - [ ] 全Pattern Plan line経由確認
  - [ ] `LOOP_PATTERNS` static削除
  - [ ] `LoopPatternEntry` struct削除

## 備考

**注意**: normalizer.rs の分割は行わない（本Phase完了時点では保留）

**理由**:
- 機能的に問題なし（現在の構造で動作）
- 緊急度低（開発速度への影響なし）
- 別Phase対応が適切（Phase 287-P0として計画のみ）