ast-grep-typescript-react

TypeScript と React 向けの ast-grep

ast-grep を .ts／.tsx コードに適用すると、性能の高いモデルでも誤ったデフォルト設定に行き当たります。主に、言語やノードの種類を誤って推測したために、ルールが何もマッチしないままになるケースです。このスキルでは、ast-grep のルールの仕組み（パターン、メタ変数、all／any／has／inside、制約）をすでに理解していることを前提とし、TypeScript と React によって加わる点だけを補足します。

ast-grep のルール作成の一般的な仕組みについては、関連する ast-grep スキルを使用してください。

適用する場面

• .ts または .tsx コードを対象とする ast-grep パターンや YAML ルールを書くとき
• JSX 要素、props、React フック、インポート、または TS の型構文を検索するとき
• JSX や TypeScript を書き換える codemod を作成するとき（コンポーネント名の変更、React.FC の削除、インポートの移行など）
• TSX でルールが「何もマッチしない」原因が分からないとき（通常は言語またはノードの種類が原因です）
• @ast-grep/napi を介して JS／TS スクリプトから ast-grep をプログラムで実行するとき

TS／React ルールが想定どおりに動かないときの最初の対処

1. 言語を確認します。 JSX を含むファイルは必ず tsx で処理し、typescript は使用しないでください。これは、何もマッチしないままになる最もよくある原因です。詳しくは lang-tsx-for-jsx を参照してください。
2. パターンの AST をデバッグします。 実際のコード断片に対して ast-grep run --pattern '<your pattern>' --lang tsx --debug-query=ast を実行すると、ノードの種類が表示され、ERROR ノードも確認できます。推測したノード名より、こちらを信頼してください。
3. 断片をラップします。 パターンが属性、prop、または型注釈の場合は、context と selector が必要です。詳しくは ctx-fragment-context-selector を参照してください。

ルールのカテゴリ

#	カテゴリ	プレフィックス	対象
1	言語の選択	lang	tsx と typescript の使い分け、.ts と .tsx のスキャン、languageGlobs
2	断片のマッチング	ctx	JSX 属性、props、型注釈に対する context／selector
3	JSX ノードの種類	jsx	自己終了要素と対になる要素、属性値のメタ変数
4	TypeScript の構文	ts	型のみのインポート、as キャスト、React.FC のジェネリクス
5	書き換えと codemod	fix	子要素や props が削除されないよう、JSX のメタ変数を再出力する
6	プログラムからの使用	napi	@ast-grep/napi の Lang.Tsx、NapiConfig の形式

クイックリファレンス

1. 言語の選択（lang）

• lang-tsx-for-jsx — JSX には必ず tsx を使用します。typescript では JSX が ERROR として解析され、何もマッチしません
• lang-scan-ts-and-tsx — .ts と .tsx の両方を対象にします。再利用には languageGlobs を使用します（ただし、<T> キャストには注意が必要です）

2. 断片のマッチング（ctx）

• ctx-fragment-context-selector — 断片（属性、props、型注釈）を context／selector でラップします

3. JSX ノードの種類（jsx）

• jsx-self-closing-vs-paired — <X/> と <X></X> は異なる種類です。any を使って両方にマッチさせます
• jsx-attribute-metavars — メタ変数は、有効な属性値の位置に置く必要があります

4. TypeScript の構文（ts）

• ts-type-only-imports — import type およびインラインの type と、値のインポートを区別します
• ts-as-expression-casts — キャストは山かっこではなく、as_expression としてマッチさせます
• ts-generic-react-fc — 型注釈を対象にして React.FC を削除します

5. 書き換えと codemod（fix）

• fix-jsx-rewrite-completeness — $$$PROPS／$$$CHILDREN を再出力してください。そうしないと削除されます

6. プログラムからの使用（napi）

• napi-lang-tsx-findall — Lang.Tsx で解析します。findAll は NapiConfig を受け取ります

使用方法

判断に応じて、該当するリファレンスファイルを読んでください。それぞれ単独で完結しており、標準的な例が記載されています。references/_sections.md ではカテゴリを定義し、AGENTS.md には全項目をまとめたインデックスがあります。

関連スキル

• ast-grep — ast-grep のルール作成全般の仕組み（パターン、構成、制約、テスト）。このスキルでは、その上に TS／React 固有の内容を加えています。