codemod-react-pipeline

Codemod React パイプライン

大規模なレガシーコードベースに JSX / TSX / React の codemod を適用するための、安全で繰り返し実行可能なワークフローです。50 ファイルの名前変更から 10 万ファイル規模の API 移行まで対応します。Codemod CLI（JSSG、ast-grep、ワークフロー）をインナーループとアウターループに組み合わせ、大規模な変更はすべて、ドライランと検証を通過した後に適用します。各ルールの背景にある理由については、関連する codemod のベストプラクティスリファレンスを参照してください。

適用する場面

次のような場合にこのスキルを使用します。

• 大規模な React / TS コードベース全体でパターンを移行する場合（コンポーネントや prop の名前変更、非推奨 API、インポートの切り替え、フックの移行など）で、手動で実行する codemod jssg run ./t.ts ./src のリスクが高すぎる場合。
• 変更を段階的に適用し、レビュー可能な状態にしたい場合。バッチごとにコミットし、失敗後に再開でき、各チェックポイントでビルド、型チェック、テストがすべて成功する必要があります。
• 大規模にファイルを変更する前に、検出結果（何が変更されるか、安全かどうか）を確認して検証したい場合。
• 変換が冪等であり、一括適用の前にそれを実証する必要がある場合。

1 ファイルのみの編集や、1 回の PR で手作業で行うほうが適切な変更には使用しないでください。

ワークフローの概要

00 plan ─▶ 01 scaffold ─▶ 02 inner loop ─▶ 03 dry-run ─▶ 04 validate ─▶ 05 batched apply ─▶ 06 verify
   goal       templates      fixture tests     preview       gates          per-batch            final
   + blast    (transform/    + 1-file trial    + findings     (idempotency,  apply+verify+commit  assertions
   radius     rule/wf/tests)                    report        type/lint/test) (resumable)
                                                  │                                  │
                                                  └── sentinel ──── required by ──────┘
                              (on any failure: working tree reverted; fix and re-run — nothing committed yet)

手順	アクション	ツール / スクリプト	リスク
0	目的を記録し、変換を分類して、影響範囲を見積もる	scripts/00-plan.sh	読み取り専用
1	テンプレートから変換、フィクスチャ、ワークフローを作成する	scripts/01-scaffold.sh	書き込み（新規ファイル）
2	フィクスチャテストと単一ファイルでの試行実行（自動で元に戻す）	scripts/02-inner-loop.sh	読み取り専用（元に戻す）
3	変更をプレビューし、検出結果レポートとドライラン用センチネルを書き込む	scripts/03-dry-run.sh	読み取り専用（元に戻す）
4	ゲート：冪等性、型チェック、リンター、フォーマット、テスト	scripts/04-validate-findings.sh	読み取り専用（元に戻す）
5	再開可能なバッチで適用し、それぞれを検証してコミットする	scripts/05-run-batched.sh	破壊的（コミット）
6	移行全体に対する最終アサーション	scripts/verify.sh	読み取り専用

PreToolUse フック（hooks/hooks.json）は、ドライラン用センチネルがない状態で --dry-run を付けずに広範囲の codemod jssg run を実行しようとするとブロックします。これにより、手順 5（または個別の適用）で手順 3～4 を飛ばせなくなります。

要件

• Codemod CLI — npm i -g codemod（スクリプトは npx codemod にフォールバックします）。jssg run/test と workflow run/validate/resume/status を提供します。
• git — パイプラインにはクリーンな作業ツリーが必要で、バッチごとにチェックポイントのコミットを作成します。
• jq — スクリプトはこれを使って config.json を読み取ります。
• プロジェクトのゲート用ツール — TypeScript、ESLint、Prettier、テストランナー（config.json で有効にするもの）。

対象リポジトリの .gitignore に state_dir（デフォルトは .codemod-pipeline）を追加してください。

セットアップ

対象リポジトリに合わせて config.json を編集します（各フィールドの _setup_instructions を参照してください）。

• src_globs：codemod が変更可能なファイル（影響範囲とゲートの対象を限定します）
• language：tsx | jsx | typescript | javascript
• typecheck_cmd / lint_cmd / format_cmd / test_cmd：ゲートのコマンド（空にするとゲートを無効にします）
• batch_size：アウターループでチェックポイントごとに処理するファイル数
• gates：各ゲートのオン／オフ切り替え

クイックリファレンス

スクリプト	目的
scripts/00-plan.sh "<goal>" [name]	計画と影響範囲の見積もり
scripts/01-scaffold.sh <name> [--rule]	JSSG 変換（または ast-grep ルール）の作成
scripts/02-inner-loop.sh <name> [--watch|--file P|-u]	短いサイクル：フィクスチャテスト／1 ファイルでの試行
scripts/03-dry-run.sh <name> [--sample N]	プレビュー、検出結果とセンチネルの書き込み
scripts/04-validate-findings.sh <name>	検証ゲートの実行
scripts/05-run-batched.sh <name> [--batch-size N|--dry]	再開可能なバッチ適用とコミット
scripts/verify.sh <name>	最終確認のアサーション
scripts/selftest.sh	このスキルのスクリプト／アセットのセルフテスト

使用方法

1. 対象リポジトリのルートで 00-plan.sh "<goal>" を実行し、生成された plan.md を読みます。
2. 01-scaffold.sh <name> を実行し、codemods/<name>/transform.ts とそのフィクスチャを実装します。
3. フィクスチャがパスするまで 02-inner-loop.sh <name> --watch で繰り返し実行します。実際のファイルでは --file <path> を試してください。
4. 03-dry-run.sh <name> を実行して検出結果レポートを読み、その後 04-validate-findings.sh <name> を実行します。
5. ゲートを通過した後に限り、05-run-batched.sh <name> を実行します（修正後に再実行すれば、中断したところから再開できます）。
6. verify.sh <name> を実行して、移行が完了し、冪等であることを確認します。

各ステップの入力、出力、失敗時の処理、ロールバックについては references/workflow.md を、メンタルモデルについては references/inner-outer-loop.md を、100k ファイル規模でのバッチ処理とロールバックについては references/safety-and-scale.md を参照してください。

注意点

gotchas.md を参照してください。特に重要なのは、ワークフローの commit: チェックポイントはクラウドのみであること（このパイプラインでは代わりにローカルでコミットします）、生成物やベンダー提供のツリーは必ず除外すること、そして最初の行から冪等性を考慮して設計することです。

関連スキル

• codemod — このパイプラインが実際に適用するベストプラクティスのリファレンス（48 のルール）です。ここでの各ステップでは、具体的なルール（例：test-run-on-subset-first、state-use-for-resumability、pattern-ensure-idempotency、security-minimize-capabilities）を参照します。