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 元素、属性、React hooks、导入或 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 属性、prop、类型注解的 context/selector
3	JSX 节点类型	jsx	自闭合与成对元素、属性值元变量
4	TypeScript 构造	ts	仅类型导入、as 强制类型转换、React.FC 泛型
5	重写与 Codemod	fix	重新输出 JSX 元变量，避免子项/prop 被丢弃
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 — 使用 context/selector 包装片段（属性、prop、类型注解）

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 的特定内容。