TypeScript-ESLint 中 TSImportType 选项对象键名解析问题分析

问题背景

在 TypeScript 5.8 版本中引入了一个新的语法特性 - import类型断言，它允许开发者在类型导入时指定解析模式。这个特性有两种语法形式：

// 使用 with 关键字
type T = import("m", { with: { "resolution-mode": "import" } });

// 使用 assert 关键字
type U = import("m", { assert: { "resolution-mode": "import" } });

在 TypeScript-ESLint 项目的 typescript-estree 包中，当解析这两种语法结构时，生成的 AST 节点存在一个关键差异未被正确处理的问题。

技术细节

预期行为

在理想情况下，TypeScript-ESLint 的解析器应该能够区分这两种语法形式：

1. 对于使用 with 关键字的导入类型，生成的 AST 中 TSImportType 节点的 options 属性应该包含一个键为 with 的对象属性
2. 对于使用 assert 关键字的导入类型，生成的 AST 中相同位置的属性键名应该是 assert

实际行为

然而当前实现中，无论源代码中使用的是 with 还是 assert，解析器生成的 AST 节点中该属性键名始终被标记为 with。这导致工具无法准确区分这两种语法形式。

根本原因

深入分析后发现，这个问题源于两个层面：

1. TypeScript 编译器 API 的限制：TypeScript 自身的 AST 并没有区分这两种语法形式，它们在 TypeScript 内部被同等对待。

2. typescript-estree 转换逻辑：在将 TypeScript AST 转换为 ESTree 格式时，代码直接获取了 token 而没有检查其实际文本内容。具体来说，在转换过程中，解析器只是简单地获取了标识符的位置信息（range），而没有验证标识符的实际文本内容。

有趣的是，虽然键名被错误地统一标记为 with，但标识符的位置信息（range）却是正确的。这意味着：

• 当源代码使用 assert 时，标识符的 range 长度是 6（对应 "assert" 的长度）
• 当源代码使用 with 时，标识符的 range 长度是 4（对应 "with" 的长度）

影响范围

这个问题主要影响以下场景：

1. 自定义 ESLint 规则：那些需要根据导入类型断言语法（with 或 assert）来实施不同逻辑的规则将无法正常工作。

2. 代码转换工具：任何基于 AST 进行代码转换的工具（如 codemod）在处理这两种语法时可能会产生错误结果。

3. 代码格式化工具：依赖精确 AST 信息的格式化工具可能无法正确保留原始代码中的语法选择。

解决方案

修复这个问题的思路相对明确：

1. 在转换过程中，除了获取标识符的位置信息外，还需要检查标识符的实际文本内容。
2. 根据实际文本内容（"with" 或 "assert"）来正确设置 AST 节点的属性键名。
3. 同时保留正确的位置信息，确保源代码映射的准确性。

由于 TypeScript 语法中 with 和 assert 是仅有的两个合法关键字用于此上下文，这种修复方案将是可靠且准确的。

对开发者的建议

在问题修复前，开发者如果需要在规则中区分这两种语法形式，可以暂时采用以下替代方案：

1. 通过标识符的 range 长度来间接判断（4 对应 "with"，6 对应 "assert"）
2. 直接检查源代码文本内容（虽然这种方法不够优雅）

不过，这些只是临时解决方案，建议关注 TypeScript-ESLint 的更新，等待官方修复此问题后再采用更规范的实现方式。

总结

这个问题展示了在构建编程语言工具链时常见的挑战 - 如何在保持与底层编译器（TypeScript）兼容性的同时，提供更精确和有用的语法树信息。TypeScript-ESLint 作为连接 TypeScript 和 ESLint 生态的桥梁，需要仔细处理这类语义差异，以确保开发者能够基于准确的 AST 信息构建可靠的代码分析工具。