ESLint插件unicorn中expiring-todo-comments规则在CI环境失效问题解析

问题背景

在软件开发过程中，我们经常使用TODO注释来标记需要后续处理的代码。eslint-plugin-unicorn插件提供了一个非常有用的规则——expiring-todo-comments，它可以帮助开发者设置TODO注释的过期时间，确保这些待办事项不会被遗忘。

然而，近期有开发者反馈该规则在本地开发环境能正常工作，但在持续集成(CI)环境中却失效了。具体表现为设置了过期日期的TODO注释在CI中不会被标记为错误，尽管当前日期已经超过了TODO注释中指定的截止日期。

问题现象分析

开发者提供的案例显示：

• 在ESLint配置中启用了unicorn/expiring-todo-comments规则并设置为error级别
• 代码中包含过期TODO注释：// Todo @cseas [2024-07-20]: Expecting this to fail on CI
• 本地环境(IST时区)和CI环境(UTC时区)的时间都晚于截止日期2024-07-20
• 本地运行ESLint能正确识别过期TODO，但CI环境中却不报错

问题根源

经过深入分析，发现这是由于expiring-todo-comments规则默认启用了ignoreDatesOnPullRequests选项。这个选项的设计初衷是为了在代码审查过程中避免因TODO注释过期而阻断正常的Pull Request流程。

在CI环境中，特别是GitHub Actions等平台，运行时环境通常会被识别为与Pull Request相关的上下文，因此该选项自动生效，导致规则跳过对TODO过期日期的检查。

解决方案

要解决这个问题，开发者需要在ESLint配置中显式地将ignoreDatesOnPullRequests选项设置为false：

{
  'unicorn/expiring-todo-comments': [
    'error',
    {
      ignoreDatesOnPullRequests: false
    }
  ]
}

最佳实践建议

1. 环境一致性：确保开发环境和CI环境使用相同的ESLint配置，避免因环境差异导致规则执行不一致

2. 时区考虑：虽然在本案例中时区差异不是主要原因，但在分布式团队中，建议统一使用UTC时间作为TODO截止日期的参考标准

3. 团队协作：如果团队使用Pull Request工作流，可以评估是否真的需要关闭ignoreDatesOnPullRequests选项，或者考虑在CI中分阶段检查：

   • 在常规构建中关闭该选项，确保TODO及时处理
   • 在PR构建中保持开启，避免阻断代码合并

4. 渐进式过期：对于重要事项，可以考虑设置多个渐进式过期提醒，例如：

   // TODO [2024-07-20]: 初步提醒
   // TODO [2024-07-27]: 必须修复
   

总结

eslint-plugin-unicorn的expiring-todo-comments规则是一个强大的工具，能有效管理代码中的待办事项。理解其配置选项特别是ignoreDatesOnPullRequests的行为，对于确保规则在不同环境中一致工作至关重要。通过合理配置，开发者可以既保持代码质量，又不影响正常的团队协作流程。