# バッチ設計書 3-changelog.ts

## 概要

本ドキュメントは、OpenCodeプロジェクトのチェンジログ自動生成バッチ（changelog.ts）の設計仕様を定義する。このバッチはコミット履歴を解析し、AIを使用してリリースノートを生成する。

### 本バッチの処理概要

このバッチは、Git履歴とGitHub APIを活用して、2つのリリース間のコミットを解析し、セクション別に整理されたチェンジログを自動生成する。AIモデル（Claude Sonnet 4.5）を使用してコミットメッセージを要約し、人間が読みやすい形式に変換する。

**業務上の目的・背景**：リリースノートの作成は、ユーザーに対して変更内容を伝える重要な作業である。しかし、多数のコミットを手動で整理するのは時間がかかり、一貫性を保つのが難しい。本バッチにより、コミット履歴からAIがインテリジェントにリリースノートを生成し、セクション（Core、TUI、Desktop、SDK、Extensions）別に整理することで、リリースプロセスの効率と品質を向上させる。

**バッチの実行タイミング**：version.tsスクリプト内でbuildNotes関数として呼び出される。CLIからの直接実行も可能（--from、--toオプション指定）。

**主要な処理内容**：
1. GitHub APIから最新リリースのタグを取得
2. 指定範囲のコミット履歴をGitHub比較APIで取得
3. 関連パッケージに影響するコミットのみをフィルタリング
4. リバートコミットのペアを検出し除外
5. AIを使用して各コミットメッセージを要約
6. 変更領域（core、tui、app等）に基づいてセクション分け
7. コントリビューター情報を収集
8. 整形されたマークダウン形式のリリースノートを出力

**前後の処理との関連**：version.tsから呼び出され、生成されたリリースノートはGitHubリリースに設定される。

**影響範囲**：リリースノートの品質に影響。外部AI API（OpenCode SDK経由）を使用する。

## バッチ種別

レポート生成 / データ変換

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | イベント駆動（随時） |
| 実行時刻 | 該当なし |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | version.tsからの呼び出し、CLI手動実行 |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| gitリポジトリ | 有効なgitリポジトリ内であること |
| GitHub API | api.github.comへのアクセス可能 |
| gh CLI | gh CLIがインストール・認証済みであること |
| OpenCode SDK | AI処理用のOpenCode SDKが利用可能 |

### 実行可否判定

fromとtoの間にコミットが存在しない場合は空配列を返す。コミット取得成功後、関連パッケージへの変更がないコミットは自動的に除外される。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| --from, -f | string | No | 最新リリース | 開始バージョン |
| --to, -t | string | No | HEAD | 終了リファレンス |
| --help, -h | boolean | No | false | ヘルプ表示 |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| GitHub Releases API | JSON | 最新リリース情報 |
| GitHub Compare API | JSON | コミット比較情報 |
| git log | テキスト | 関連コミットのハッシュ |
| git diff-tree | テキスト | コミットの影響ファイル |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| 標準出力 | マークダウン | 生成されたリリースノート |
| 関数戻り値 | string[] | リリースノートの行配列 |

### 出力ファイル仕様

CLIモードでは標準出力にマークダウン形式で出力。ファイル保存は呼び出し元（version.ts）が担当。

## 処理フロー

### 処理シーケンス

```
1. 最新リリース取得（getLatestRelease）
   └─ GitHub APIで100件のリリースを取得、ドラフト除外

2. コミット取得（getCommits）
   ├─ gh api compareでコミットデータ取得
   ├─ git logで関連パッケージのコミットハッシュ取得
   ├─ 各コミットの影響ファイルを解析
   └─ 影響領域（areas）を判定

3. リバートコミット除外（filterRevertedCommits）
   └─ "Revert X"とXのペアを検出・除外

4. チェンジログ生成（generateChangelog）
   ├─ AIでコミットメッセージを要約（バッチサイズ10）
   ├─ セクション別にグループ化
   └─ コントリビューター帰属を追加

5. コントリビューター収集（getContributors）
   └─ チームメンバー以外のコミット作成者を収集

6. リリースノート整形（buildNotes）
   └─ セクション見出し付きマークダウン生成
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[getLatestRelease]
    B --> C[getCommits]
    C --> D{コミットあり?}
    D -->|No| E[空配列を返す]
    D -->|Yes| F[filterRevertedCommits]
    F --> G[createOpencode SDK初期化]
    G --> H[generateChangelog]
    H --> I[AIでコミット要約]
    I --> J[セクション別グループ化]
    J --> K[getContributors]
    K --> L[リリースノート整形]
    L --> M[SDK終了処理]
    M --> N[バッチ終了]
    E --> N
```

## データベース操作仕様

### 操作別データベース影響一覧

本バッチはデータベース操作を行わない。外部API（GitHub、OpenCode）への読み取りリクエストのみ。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | GitHub API失敗 | リリース取得失敗 | ネットワーク確認、API制限確認 |
| - | gh CLI失敗 | compareコマンド失敗 | 認証確認、リファレンス確認 |
| - | AIタイムアウト | 120秒超過 | ローコミットにフォールバック |
| - | OpenCode SDK失敗 | セッション作成失敗 | SDK設定確認 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし |
| リトライ間隔 | 該当なし |
| リトライ対象エラー | 該当なし |

### 障害時対応

1. AIタイムアウト時：生のコミットメッセージにフォールバック（L241-247）
2. SDK初期化失敗時：エラーをthrow、上位でハンドリング
3. コミット取得失敗時：空配列を返し、"No notable changes"メッセージ

## トランザクション仕様

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | なし（読み取り専用） |
| コミットタイミング | 該当なし |
| ロールバック条件 | 該当なし |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | コミット数: 10-100件/リリース |
| 目標処理時間 | 2分以内（AI処理含む） |
| メモリ使用量上限 | 特に制限なし |
| AI並列処理 | 最大10件同時（BATCH_SIZE=10） |

## 排他制御

特になし。読み取り専用処理のため並列実行可能。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | changelog生成開始時 | "generating changelog since {version}" |
| 進捗ログ | コミット要約時 | "summarizing commit: {message}" |
| 完了ログ | 生成完了時 | "changelog generation complete" |
| 結果ログ | 生成完了時 | "---- Generated Changelog ----" |
| タイムアウトログ | AI失敗時 | "Changelog generation timed out, using raw commits" |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| AI処理時間 | 120秒 | 自動フォールバック |
| 処理エラー | 発生時 | 呼び出し元に伝播 |

## 備考

- Script.teamに定義されたチームメンバーのコミットにはコントリビューター帰属が付与されない
- セクション優先順位：core > tui > app > tauri > sdk > plugin > extensions/zed > extensions/vscode > github
- フィルタリングされるコミットプレフィックス：ignore:、test:、chore:、ci:、release:
- 対象パッケージ：packages/opencode、packages/sdk、packages/plugin、packages/desktop、packages/app、sdks/vscode、packages/extensions、github
- AIモデル：opencode/claude-sonnet-4-5
- AIセッションタイムアウト：120,000ms（120秒）
