generating-sorbet-inline

Sorbet 内联生成技能

直接在 Ruby 源文件中使用 sig {} 块生成或更新 Sorbet 类型签名。支持从头开始完整生成，也支持仅更新单个已更改文件。Sorbet 签名是有效的 Ruby 代码，可启用静态和运行时类型检查。

说明

生成 Sorbet 内联签名时，请始终遵循以下步骤。

复制此清单并跟踪进度：

Sorbet Inline Generation Progress:
- [ ] Step 1: Analyze the Ruby source
- [ ] Step 2: Add Sorbet signatures
- [ ] Step 3: Eliminate `T.untyped` in signatures
- [ ] Step 4: Review and refine signatures
- [ ] Step 5: Validate signatures with Sorbet

规则

• 不得运行项目的 Ruby 代码。
• 不得使用 T.untyped。请推断正确的类型。
• 不得使用 T.unsafe，它会完全绕过类型检查。
• 不得使用 T.cast，它会在未经验证的情况下强制转换类型。
• 如果有不清楚的地方，必须请用户提供更多详情。
• 如果项目有 Gemfile，所有命令前都必须加上 bundle exec。
• 必须使用 sig { } 块语法编写方法签名。
• 使用 sig 前，必须在类或模块中添加 extend T::Sig。
• 必须仅关注方法签名。跳过局部变量、中间表达式和其他非方法注解。
• 不得使用或生成 .rbi 文件。此技能仅用于内联签名。
• 如果文件中已有 # typed: 标记，必须保留其级别。未经用户明确同意，不得升级或更改严格程度。
• 处理多个文件时，必须使用跟踪文件，确保没有遗漏文件。

多文件处理

处理多个 Ruby 文件时，创建跟踪文件，确保涵盖所有文件：

1. 创建跟踪文件 .sorbet-inline-generation-todo.tmp：

   [ ] app/models/user.rb
   [ ] app/models/post.rb
   [ ] app/services/auth_service.rb
   

2. 逐个处理文件：

   • 选择下一个待处理的 [ ] 条目
   • 完成该文件的所有步骤（1-5）
   • 标记为已处理 [x]
   • 保存跟踪文件
   • 继续处理下一个待处理条目

3. 清理：处理完所有文件后，删除跟踪文件：

   rm .sorbet-inline-generation-todo.tmp
   

如果处理中断，跟踪文件可帮助从上次进度继续。

1. 分析 Ruby 源代码

始终执行此步骤。

阅读并理解 Ruby 源文件：

• 确认所有类、模块、方法、常量和实例变量。
• 注意继承、模块包含以及基于元编程的定义。
• 注意可见性修饰符：public、private、protected。
• 注意文件顶部现有的 # typed: 标记级别。
• 注意泛型类的类型参数。

2. 添加 Sorbet 签名

始终执行此步骤。

1. 首先，检查文件顶部是否已有 # typed: 标记：

   • 如果已有标记：保留现有级别。未经用户同意，不得更改。
   • 如果没有标记：添加 # typed: true，作为合理的默认值（支持渐进式类型检查）。

   标记级别（从最低到最高严格度）：ignore < false < true < strict < strong

2. 在类或模块中添加 extend T::Sig：

   class MyClass
     extend T::Sig
   end
   

3. 然后使用 sig {} 块添加类型签名：

示例 - 之前：

class User
  attr_reader :name, :age

  def initialize(name, age)
    @name = name
    @age = age
  end

  def greet(greeting)
    "#{greeting}, #{@name}!"
  end
end

示例 - 之后：

# typed: true

class User
  extend T::Sig

  sig { returns(String) }
  attr_reader :name

  sig { returns(Integer) }
  attr_reader :age

  sig { params(name: String, age: Integer).void }
  def initialize(name, age)
    @name = name
    @age = age
  end

  sig { params(greeting: String).returns(String) }
  def greet(greeting)
    "#{greeting}, #{@name}!"
  end
end

• 仅关注方法和属性签名
• 完整的 Sorbet 语法指南请参阅 syntax.md

3. 消除签名中的 T.untyped

始终执行此步骤。

• 检查所有签名，并将 T.untyped 替换为正确的类型。
• 根据代码上下文、方法调用和测试推断类型。
• 只有在无法确定类型时，才将 T.untyped 作为最后手段使用。

4. 检查并完善签名

始终执行此步骤。

• 验证签名是否正确、一致且完整。
• 删除不必要的 T.untyped 类型。
• 确保所有方法和属性都有签名。
• 修复所有错误并重复检查，直到签名正确为止。

5. 使用 Sorbet 验证签名

始终执行此步骤。

运行 Sorbet 类型检查器以验证签名：

srb tc

或者使用 bundle：

bundle exec srb tc

此检查包括：

• 签名语法是否正确
• 类型是否一致
• 方法参数类型与返回类型是否匹配
• 实例变量是否已初始化

修复报告的所有错误并重复执行，直到验证通过。

参考资料

• syntax.md - Sorbet 签名语法指南
• sorbet_examples/ - 生产级 gem 中的真实 Sorbet 示例
• Sorbet 文档 - Sorbet 官方文档