やあ。Hackの世界へようこそ。君が今、レガシーなPHPの海から、堅牢で型安全なHackの陸地へ渡ろうとしているその勇気、心から歓迎するよ。
大規模なコードベースを移行する際、手作業でエディタを叩き続けるのは「修行」ではなく「苦行」だ。我々アーキテクトは、そんな無駄なことはしない。AST（抽象構文木）を理解し、ツールにコードを書き換えさせる。これが、現代のソフトウェアエンジニアリングの正しい姿だ。
今日は、Hackの守護神 `hh_client` を使ったリファクタリングの極意を伝授しよう。
—
1. なぜ「手作業」は地獄なのか？
PHPからHackへの移行は、単なる構文の書き換えじゃない。型推論の整合性を保ちながら、動的な緩さを削ぎ落とす作業だ。
例えば、`array()` を `vec[]` や `dict[]` に変えるだけなら簡単だが、その中身の型が不明瞭なまま放置すれば、型チェッカー `hh_vm` は君に牙を剥くだけだ。
そこで登場するのが、`hh_client –refactor` だ。これは正規表現による置換とは次元が違う。コードの構造（AST）を理解した上で、意味を壊さずに構文を書き換える。これが「安全」である所以だよ。
—
2. `hh_client –refactor` の魔法
このツールを使うときは、まずは小さな単位で「ルール」を適用するんだ。
実践：PHP配列からHSLのコレクションへ
古いコードの `array(‘a’ => 1, ‘b’ => 2)` を、現代的な `dict[‘a’ => 1, ‘b’ => 2]` に変換したいとしよう。
基本のコマンド構造
hh_client –refactor <ルール名> <対象ファイルまたはディレクトリ>
実際には、カスタムのリファクタリング・スクリプトを定義して適用するが、まずは君がツールに「何を求めているか」を明確にする必要がある。
- 図解的イメージ：
- PHP: 「何でも入る箱」 (array)
- Hack: 「型が保証された厳密な箱」 (vec, dict, keyset)
- リファクタリング: 「箱の中身を確認し、最適な型付きの箱に入れ替える作業」
—
3. 失敗しないための「AST理解」
初心者が陥りやすいのが、「型チェッカーの警告を無視して強引に変換する」ことだ。
例えば、関数の戻り値が不明瞭（`mixed`）な状態で、無理やり戻り値の型を定義しようとすると、`hh_client` は無慈悲にエラーを吐く。これは嫌がらせではない。「ここで型を決めると、後でシステム全体が崩壊するよ」という、HHVMからの慈悲深い警告なんだ。
陥りやすい文法エラー：
1. Nullableの欠落: `?int` とすべき場所を `int` にしてしまう。
2. Shapeの不整合: 辞書型（dict）に特定のキーが必須なのに、オプションとして定義してしまう。
先輩からのアドバイス:
「エラーが出たら、まずはその行を直そうとせず、その関数の入力（引数）と出力（戻り値）の型定義を見直してごらん。データフローが明確になれば、リファクタリングツールは魔法のようにスムーズに動くはずだよ」
—
4. 移行を成功させるワークフロー
大規模コードベースを攻略する際、僕がいつもチームに推奨している手順はこれだ。
1. 段階的導入: `HH_FIXME` を活用し、まずは「動く状態」を目指す。
2. 型チェッカーの強化: `.hhconfig` で `strict` モードを少しずつ適用する。
3. 自動化の活用: `hh_client –refactor` で定型的な修正（`array` → `dict` など）を流し込む。
4. HSL（Hack Standard Library）への差し替え: `count($arr)` を `C\count($vec)` にするなど、標準ライブラリを最大限に活かす。
—
最後に：君のコードは、もっと「賢く」なれる
Hackへの移行は、過去の負債を返済し、未来の安定を買う投資だ。最初は型チェッカーの厳しい指摘に戸惑うかもしれない。でも、思い出してほしい。コンパイラが君のコードを理解し、間違いを指摘してくれるということは、君一人でコードの正しさを保証しなくていいということだ。
これって、すごく贅沢なことだと思わないか？
ここをクリアすれば、君はもう単なるコーダーじゃない。HHVMという巨大なエンジンの心臓部を操る、設計者の一人だ。わからないことがあれば、いつでもまた聞きに来なさい。
さあ、コードを開いて、最初の一歩を踏み出そう。君ならできるよ。