jscodeshift

Facebook/Meta jscodeshift のベストプラクティス

AI エージェントと LLM 向けに設計された、jscodeshift による codemod 開発の包括的なベストプラクティスガイドです。影響度に基づいて、重要度の高いもの（パーサー設定、AST のトラバース）から段階的に取り組むもの（高度なパターン）まで、8 つのカテゴリにわたる 40 のルールを掲載しています。各ルールには、詳しい説明、実例、具体的な影響指標が含まれています。

適用するタイミング

次の場合に、これらのガイドラインを参照してください。

• コード移行用の新しい jscodeshift codemod を作成するとき
• 変換の失敗や予期しない動作をデバッグするとき
• 大規模なコードベースでの codemod のパフォーマンスを最適化するとき
• codemod のコードが正しいかレビューするとき
• エッジケースやリグレッションに対して codemod をテストするとき

優先度別のルールカテゴリ

優先度	カテゴリ	影響度	接頭辞
1	パーサー設定	CRITICAL	parser-
2	AST トラバースパターン	CRITICAL	traverse-
3	ノードのフィルタリング	HIGH	filter-
4	AST 変換	HIGH	transform-
5	コード生成	MEDIUM	codegen-
6	テスト戦略	MEDIUM	test-
7	ランナーの最適化	LOW-MEDIUM	runner-
8	高度なパターン	LOW	advanced-

クイックリファレンス

1. パーサー設定（CRITICAL）

• parser-typescript-config - TypeScript ファイルには適切なパーサーを使用する
• parser-flow-annotation - Flow 型付きコードには Flow パーサーを使用する
• parser-babel5-compat - 最新の構文ではデフォルトの babel5compat を避ける
• parser-export-declaration - 変換モジュールからパーサーをエクスポートする
• parser-astexplorer-match - AST Explorer のパーサーを jscodeshift のパーサーに合わせる

2. AST トラバースパターン（CRITICAL）

• traverse-find-specific-type - find() 呼び出しでは特定のノード型を指定する
• traverse-two-pass-pattern - 複雑な変換には 2 パスパターンを使用する
• traverse-early-return - 変換が不要な場合は早期に return する
• traverse-find-filter-pattern - filter() の連結ではなく、フィルターオブジェクトを使った find() を使用する
• traverse-closest-scope - スコープを考慮した変換には closestScope() を使用する
• traverse-avoid-repeated-find - 同じノード型に対する find() 呼び出しの繰り返しを避ける

3. ノードのフィルタリング（HIGH）

• filter-path-parent-check - 変換前に親パスを確認する
• filter-import-binding - 正確に使用状況を検出するため、インポートのバインディングを追跡する
• filter-nullish-checks - プロパティにアクセスする前に nullish チェックを追加する
• filter-jsx-context - JSX コンテキストと通常の JavaScript を区別する
• filter-computed-properties - フィルターで計算されたプロパティキーを処理する

4. AST 変換（HIGH）

• transform-builder-api - AST ノードの作成にはビルダー API を使用する
• transform-replacewith-callback - コンテキストを考慮した変換には replaceWith コールバックを使用する
• transform-insert-import - 正しい位置にインポートを挿入する
• transform-preserve-comments - ノードを置き換える際にコメントを保持する
• transform-renameto - 変数名の変更には renameTo を使用する
• transform-remove-unused-imports - 変換後に未使用のインポートを削除する

5. コード生成（MEDIUM）

• codegen-tosource-options - 一貫したフォーマットになるように toSource() を設定します
• codegen-preserve-style - recast で元のコードスタイルを保持します
• codegen-template-literals - 複雑なノードの作成にはテンプレートリテラルを使用します
• codegen-print-width - 長い行に適切な印刷幅を設定します

6. テスト戦略（MEDIUM）

• test-inline-snapshots - 入出力の検証に defineInlineTest を使用します
• test-negative-cases - まず否定的なテストケースを作成します
• test-dry-run-exploration - コードベースの調査にはドライランモードを使用します
• test-fixture-files - 複雑なテストケースにはフィクスチャファイルを使用します
• test-parse-errors - 解析エラーの処理をテストします

7. ランナーの最適化（LOW-MEDIUM）

• runner-parallel-workers - 最適な並列化のためにワーカー数を設定します
• runner-ignore-patterns - ソース以外のファイルをスキップするには無視パターンを使用します
• runner-extensions-filter - 拡張子でファイルをフィルタリングします
• runner-batch-processing - 大規模なコードベースをバッチ処理します
• runner-verbose-output - 変換のデバッグには詳細出力を使用します

8. 高度なパターン（LOW）

• advanced-compose-transforms - 複数の変換をパイプラインに組み合わせます
• advanced-scope-analysis - 安全な変数変換にはスコープ解析を使用します
• advanced-multi-file-state - オプションを使ってファイル間で状態を共有します
• advanced-custom-collections - カスタムコレクションメソッドを作成します

使用方法

詳しい説明とコード例については、各リファレンスファイルをお読みください。

• セクションの定義 - カテゴリー構成と影響レベル
• ルールテンプレート - 新しいルールを追加するためのテンプレート

コンパイル済みの全文書

すべてのルールを含む包括的な単一のドキュメントについては、AGENTS.md をご覧ください。

リファレンスファイル

ファイル	説明
AGENTS.md	すべてのルールを含む、コンパイル済みの完全なガイド
references/_sections.md	カテゴリーの定義と並び順
assets/templates/_template.md	新しいルール用のテンプレート
metadata.json	バージョンとリファレンス情報