关于 eslint-migrate-options
eslint-migrate-options 是用于开发的技能，指导将 ESLint 规则选项自定义迁移为 Biome 配置。内容涵盖源选项建模、语义转换、类型化分发、迁移接线和基于样例的测试。
主要功能
- 01建模 ESLint 选项载荷
- 02将源语义转换为 Biome 选项
- 03添加类型化规则分发
- 04在严重级别处理后接入自定义迁移
- 05测试迁移样例及边界情况
适用场景
- 01保留受支持的 ESLint 规则选项
- 02迁移嵌套规则设置
- 03验证默认值和不支持的字段
- 04检查自定义迁移改动
安装
复制下面的命令，在终端中运行。
npx skills add https:/安装后在 Claude Code 中输入/eslint-migrate-options确认已加载。
详细介绍
ESLint 选项迁移
仅当现有 Biome 规则需要保留有意义的 ESLint 选项时，才使用自定义迁移器。仅迁移严重级别应由生成的规则映射处理。
前置条件
编辑前确认：
- Biome 规则及其选项类型已存在。
- 规则元数据标明了对应的 ESLint 源规则。
- 生成的严重级别迁移已存在，或将重新生成。
- 官方 ESLint 或插件文档明确了确切的选项结构和默认值。
- 支持的 Biome 语义清晰，包括不支持的源选项。
如果 Biome 规则本身或其选项仍需实现，请加载 lint-rule-development。
流程
自定义迁移包含四个部分：
- 插件专用类型反序列化 ESLint 负载。
- 转换逻辑将源语义映射为 Biome 选项类型。
- 共享 ESLint
Rule枚举将该规则识别为类型化变体。 migrate_eslint_rule()在处理通用严重级别后安装生成的 Biome 配置。
关键文件
| 文件 | 职责 |
|---|---|
eslint_eslint.rs | 共享配置模型、Rule、RuleConf<T> 和分发逻辑 |
eslint_unicorn.rs | Unicorn 选项类型和转换逻辑 |
eslint_typescript.rs | TypeScript ESLint 选项类型和转换逻辑 |
eslint_jsxa11y.rs | JSX 无障碍选项类型和转换逻辑 |
eslint_to_biome.rs | 主要转换逻辑和自定义迁移分支 |
eslint_any_rule_to_biome.rs | 生成的严重级别映射 |
tests/specs/migrate_eslint/ | 基于测试样例的迁移快照 |
使用与源规则对应的插件专用模块，并检查一个负载和 Biome 配置类型类似的现有迁移器。
建模源选项
应按照 ESLint JSON 结构建模，而非按照 Biome 目标结构建模。
- 在转换前保留源结构的嵌套关系。
- 源允许省略的字段应使用可选字段。
- 参照相邻选项类型，遵循当前的反序列化命名和默认值约定。
- 对支持的实际配置进行反序列化所需的字段应建模。
- 确认不支持的源字段不会导致有效配置反序列化失败；是否需要显式定义这些字段，取决于当前反序列化器的约定。
不要假设源默认值与目标默认值等效。
转换语义
在源选项类型旁实现转换逻辑。
- 当 ESLint 和 Biome 使用不同术语时，转换相应概念。
- 有意舍弃不支持的行为。
- 避免生成空的嵌套选项对象。
- 如果应用 Biome 默认值会改变仅设置严重级别时的行为，则保留未提供选项的状态。
- 当标准化或条件构造具有明确的领域含义时，使用小型辅助函数。
转换逻辑应通过分支清楚表明不支持的行为和默认行为，而不是依赖逐字段赋值。
添加类型化规则变体
在 eslint_eslint.rs 中更新所有类型化分发位置：
- 将
RuleConf<SourceOptions>添加到Rule； - 让
Rule::name()返回确切的 ESLint 规则名称； - 在通用兜底分支之前，将该名称反序列化为类型化变体。
添加变体后，搜索枚举的所有匹配分支，确保没有遗漏需要更新的分发位置。
接入迁移
在 migrate_eslint_rule() 中添加自定义分支，并首先调用 migrate_eslint_any_rule()。通用路径负责跟踪严重级别、报告不支持的规则以及去重。
使用目标规则实际所属的规则组和配置类型：
- 可修复规则使用
RuleFixConfiguration::WithOptions； - 不可修复规则使用
RuleConfiguration::WithOptions。
根据源结构选择 RuleConf 的访问方式：
- 当仅设置严重级别的输入应通过源默认值映射时，使用
option_or_default()； - 当只有提供选项时才应附加选项，使用显式的
RuleConf::Option匹配； - 对需要聚合或标准化的数组负载使用
into_vec()。
复制一个当前类似的分支，不要依赖记忆中的结构体字段。
测试
在 crates/biome_cli/tests/specs/migrate_eslint/ 下添加有针对性的测试夹具，涵盖：
- 仅包含严重级别的配置；
- 每种受支持的选项模式；
- 在其他方面有效的输入中包含不受支持的字段；
- 为空和部分指定的嵌套对象；
- ESLint 和 Biome 默认值不同的情况；
- 合并行为相关的预先存在的 Biome 配置。
运行针对性的迁移测试，并检查相邻的快照。如果迁移输出取决于规则语义，也要运行分析器选项测试。
常用命令：
cargo check -p biome_cli
cargo test -p biome_cli migrate_eslint
审查清单
- 源类型与官方 ESLint 配置相符。
- 转换映射的是语义，而不是机械地映射名称。
- 仅包含严重级别时的行为仍然正确。
- 类型化变体、名称、反序列化和迁移均完整。
- 通用严重级别迁移先于自定义选项安装运行。
- 分组和可修复性与目标规则相符。
- 测试夹具涵盖省略、默认值、不受支持的字段和嵌套选项。
参考资料
- 迁移实现：
crates/biome_cli/src/execute/migrate/ - 规则选项：
crates/biome_rule_options/src/ - 生成的映射：
xtask/codegen/src/generate_migrate_eslint.rs - ESLint 文档：https://eslint.org/docs/latest/use/configure/rules