oxlint

Oxlint

当工作涉及 Oxlint 或 Oxc lint 时，使用此技能：包括安装和配置、日常使用、规则和插件、React Compiler lint 规则、类型感知 lint、与 ESLint 共存或迁移、编辑器或 CI。

工作流程

1. 修改代码前，检查本地 Oxlint 的情况：
   • oxlint、可选的 oxlint-tsgolint、eslint-plugin-oxlint、@oxlint/migrate 的软件包版本。
   • 配置：优先使用带 defineConfig 的 oxlint.config.ts / .mts；也接受 .oxlintrc.json(c)（每个目录只能使用一种类型）。
   • 剩余的 ESLint 配置、忽略文件、脚本（lint / lint:fix）以及编辑器中的 Oxc 设置。
   • 是否启用了类型感知 lint、JS 插件或 React Compiler 规则。
2. 对于设置、使用方法、渐进式采用、诊断循环、基线或故障排查，先阅读完整指南：usage-guide.md。
3. 如果版本与快照不同，或工作涉及类型感知 lint、JS 插件、React Compiler 或迁移，请查阅最新官方文档。从 source-map.md 开始。
4. 深入细节请参阅对应的参考文档：
   • 安装、CLI、配置结构、嵌套配置、忽略项：setup-cli-config.md。
   • 类别、插件、React Compiler、JS 插件、规则、行内忽略、类型感知 lint：rules-plugins-typeaware.md。
   • ESLint 共存、迁移、编辑器、CI：eslint-ci-editors.md。
5. 除非用户要求迁移或扩大覆盖范围，否则保留仓库现有的 lint 严重级别和插件选择。
6. 使用最精简且有用的 bunx oxlint / bun run lint 命令进行验证。

核心判断

• Oxlint 默认只启用 correctness 类别。请谨慎启用其他类别和插件。
• 设置 plugins: [...] 会替换默认插件集。如果仍需使用 eslint、typescript、unicorn 和 oxc，请在列表中重新添加。
• 新配置优先使用 oxlint.config.ts + defineConfig（支持类型检查，可通过导入共享）。仅当项目已有 .oxlintrc.json，或使用不带 Node 运行时的独立二进制文件时，才保留或使用 .oxlintrc.json。CLI 帮助仍将 JS/TS 配置加载标记为实验性；官方配置文档则将 oxlint.config.ts 视为一等配置方式。
• 嵌套配置不会自动与父配置合并，请使用 extends（TS：导入对象；JSON：相对路径）。-c/--config 会禁用嵌套配置查找。
• Vite+（vp lint，Vite+ 1.0 固定使用特定版本的 Oxlint）会读取 vite.config.* 中的 lint 配置块；在 Vite+ 模式（1.85+）下，嵌套配置始终处于关闭状态，因此请使用根级 lint.overrides。
• 优先在配置中使用 ignorePatterns，而不是分散的忽略文件，以确保编辑器和 CI 的行为一致。.gitignore 适用于遍历发现；显式指定的文件仍会被 lint。
• 长期来看优先使用 oxlint-disable* 注释；迁移期间仍可使用 eslint-disable*（respectEslintDisableDirectives 默认值为 true）。
• 类型感知 lint 需要 oxlint-tsgolint + --type-aware / options.typeAware。这些选项只能用于根级配置。启用类型感知 lint 时，不要同时传入 --tsconfig。
• oxlint 和 eslint-plugin-oxlint 应使用相同的小版本。在 ESLint 中，将 oxlint 扁平配置放在最后，以禁用重叠规则。
• JS 插件（jsPlugins）处于 alpha 阶段，不受常规语义化版本约束，除非必要，否则请避免使用。
• React Compiler lint 规则仍处于实验阶段。从 1.79 开始，它们是按类别划分的 react/* 规则（不再是 react/react-compiler）。启用 react 插件并使用默认的 correctness 类别后，会启用推荐的 Compiler 规则。请移除任何遗留的 react/react-compiler 条目。
• Vue/Svelte/Astro/Angular：Oxlint 只覆盖脚本块，不覆盖模板。
• 不要将 Oxlint 当作格式化工具。格式化应交由单独的格式化工具处理（例如 Oxfmt 或 Prettier）。

验证

优先使用仓库自有命令。对于有意义的 Oxlint 工作，覆盖相关子集：

• 对变更路径运行 bunx oxlint（或项目的 lint 脚本）。
• 预期会自动修复时运行 bunx oxlint --fix；检查剩余诊断。
• 类型感知：在依赖项构建完成、.d.ts 文件已生成后运行 bunx oxlint --type-aware。
• 若这些门禁属于项目策略，则运行符合 CI 形态的检查，并使用 --deny-warnings 或 --max-warnings。
• 更改 ESLint 共存配置后：运行 oxlint && eslint，并确认没有重复规则噪声。
• 更改 Oxc 扩展设置或 options.typeAware 时，进行编辑器/LSP 冒烟测试。
• 在 1.79+ 版本启用 react 插件后：确认实验性编译器规则是否应继续启用。

报告运行了哪些检查、哪些未运行，以及仍存在的任何软件包版本、React Compiler 或类型感知方面的假设。