---
name: ruby-typeprof
description: Ruby TypeProf（型推論ツール）の使い方リファレンス。CLI コマンド、typeprof.conf.jsonc の設定、RBS 生成、Steep との連携ワークフローをカバーする。Triggers include "TypeProf の使い方", "RBS を生成したい", "typeprof コマンドを教えて", "Ruby の型推論", "/ruby-typeprof".
---

# Ruby TypeProf リファレンス

Ruby コードを型レベルで抽象実行し、RBS（Ruby の標準型記述言語）の雛形を自動生成する公式ツール **TypeProf** の使い方リファレンス。事実のみを提示し、判断や提案は行わない。

---

## 1. TypeProf とは

- Ruby コードを抽象実行してメソッドの引数・戻り値・インスタンス変数の型を観測する**型推論エンジン**
- 出力は **RBS 形式**
- **Ruby 3.3 以降が必須**
- 位置付け: 型チェッカーではなく、**RBS 雛形生成**と **IDE 支援（LSP）バックエンド**
- 設計思想: 不確実なときは `untyped` を返す保守的推論（false positive を出さない）

## 2. インストール

```bash
gem install typeprof
```

Gemfile に追加する場合:

```ruby
group :development do
  gem "typeprof", require: false
end
```

バージョン確認:

```bash
typeprof --version
```

## 3. CLI の基本

### 単一ファイル解析

```bash
typeprof app.rb
```

標準出力に RBS が出る。

### 既存 RBS を併用

```bash
typeprof sig/app.rbs app.rb
```

`sig/app.rbs` を既知情報として読み、未知部分だけ推論。

### ファイル出力

```bash
typeprof app.rb -o sig/app.gen.rbs
```

### オプション一覧

| オプション | 役割 |
|:---|:---|
| `-o <path>` | 結果を指定ファイルに出力 |
| `--init` | プロジェクト初期化（`typeprof.conf.jsonc` 生成） |
| `--lsp` | Language Server モードで起動（エディタ連携用） |
| `--version` | バージョン表示 |
| `--help` | オプション一覧 |

## 4. 入出力サンプル

**入力** (`working_day_calculator.rb`):

```ruby
class WorkingDayCalculator
  attr_accessor :period_start, :period_end
  attr_reader :days_off

  def initialize
    @days_off = []
  end

  def add_day_off(date)
    @days_off << date
  end
end
```

**出力**:

```rbs
class WorkingDayCalculator
  attr_accessor period_start: bot
  attr_accessor period_end: bot
  attr_reader days_off: Array[untyped]
  def initialize: -> void
  def add_day_off: (untyped date) -> Array[untyped]
end
```

**型記号の意味**:

- `bot`（ボトム型）: まだ代入が観測されていない型。全型のサブタイプ
- `untyped`: 推論できないので諦めた型。任意の型を受け入れる

この出力は**出発点**であり、`Date` や `Array[Date]` のように人手で精緻化することが前提。

## 5. `typeprof.conf.jsonc`

プロジェクトルートで初期化:

```bash
typeprof --init
```

JSONC（コメント可 JSON）で解析対象ディレクトリや RBS パスを指定する設定ファイルが生成される。LSP（VSCode 拡張 `Ruby TypeProf`）はこのファイルを読んで動く。

## 6. RBS / Steep 連携ワークフロー

TypeProf 単独では型エラー検出はしない。実戦では以下の 4 段階で使う。

### Step 1: TypeProf で RBS 雛形生成

```bash
typeprof lib/**/*.rb -o sig/app.gen.rbs
```

### Step 2: `sig/` 配下で人手精緻化

`untyped` / `bot` を具体型に置換、オーバーロード追加など。

```rbs
class WorkingDayCalculator
  attr_accessor period_start: Date
  attr_accessor period_end: Date
  attr_reader days_off: Array[Date]
  def initialize: -> void
  def add_day_off: (Date date) -> Array[Date]
end
```

### Step 3: Steepfile 作成

```ruby
target :lib do
  signature "sig"
  check     "lib"
  library   "date"
  configure_code_diagnostics(Steep::Diagnostic::Ruby.strict)
end
```

### Step 4: Steep で型チェック

```bash
steep check
```

型不一致があれば以下のようなエラーが出る。

```
Cannot pass a value of type `::String` as an argument of type `::Date`
```

## 7. 制限事項

- **ランタイムエラー検出はしない**（ゼロ除算・nil 参照など）
- **契約強制・Lint 代替にはならない**
- **メタプログラミング重用コードは苦手**（`define_method`、DSL、Rails のマジック等）
- **パス解析が保守的** — 分岐が多いと `untyped` 化しやすい
- 生成 RBS は**常に出発点**。そのまま Steep の strict にかけると `untyped` だらけで意味が薄い

## 8. 使い分けの指針

| 目的 | 推奨 |
|:---|:---|
| 既存コードに RBS を初期導入したい | TypeProf で雛形生成 → 手で精緻化 |
| エディタで補完・ジャンプを強化したい | VSCode + Ruby TypeProf 拡張 |
| CI で型崩れを検出したい | Steep（TypeProf は前段のみ） |
| Rails のフルスタック型付け | Sorbet + tapioca の方が実績あり |

## 9. 参考リンク

- 公式リポジトリ: https://github.com/ruby/typeprof
- 公式ドキュメント: https://github.com/ruby/typeprof/blob/master/doc/doc.md
- VSCode 拡張: https://github.com/ruby/vscode-typeprof
- Playground: https://mame.github.io/typeprof-playground/
- RBS: https://github.com/ruby/rbs