# 画面設計書 11-omz pr test

## 概要

本ドキュメントは、Oh My ZshのPull Request（PR）をテストするためのCLIコマンド `omz pr test` の画面設計書です。

### 本画面の処理概要

`omz pr test` コマンドは、GitHub上のOh My Zshリポジトリに提出されたPull Requestをローカル環境でテストするためのコマンドインターフェースです。

**業務上の目的・背景**：Oh My Zshはオープンソースプロジェクトであり、多くのコントリビューターからPRが提出されます。これらのPRをマージする前に、メンテナーやテスターがローカル環境で動作確認を行う必要があります。本コマンドは、PRの取得からテスト環境の構築、テスト実行後の元の状態への復帰までを自動化し、テストプロセスを効率化します。セキュリティの観点から、メンテナーが「testers needed」ラベルを付けていないPRについては、悪意のあるコードが含まれている可能性について警告を表示します。

**画面へのアクセス方法**：ターミナルで `omz pr test <PR番号>` または `omz pr test <PRのURL>` を実行することでアクセスします。

**主要な操作・処理内容**：
1. PR番号またはURLからPR番号を抽出
2. 現在のgitブランチを保存
3. GitHub APIを使用してPRの「testers needed」ラベルを確認
4. ラベルがない場合、セキュリティ警告を表示し、明示的な確認を要求
5. PRをfetchして `ohmyzsh/pull-<PR番号>` ブランチを作成
6. masterブランチに対してrebaseを実行
7. 新しいzshセッションを起動してPRの変更をテスト
8. テスト終了後、元のブランチに戻るかどうかをユーザーに確認

**画面遷移**：
- 遷移元: `omz pr` コマンドのサブコマンドとして呼び出し
- 遷移先: テスト用の新しいzshセッションを起動、テスト後は元のブランチに復帰可能

**権限による表示制御**：特になし。ただし、$ZSHディレクトリへの書き込み権限とgitコマンドの実行権限が必要です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 6 | omzコマンド | 主機能 | omzコマンドの統合CLIインターフェースを通じてPRテストを実行 |
| 19 | omz pr test | 主機能 | GitHub PRをfetchしてmasterにrebaseし、テスト用に新しいzshを起動 |

## 画面種別

コマンドラインインターフェース（対話型）

## URL/ルーティング

```
omz pr test <PR番号>
omz pr test <PR_URL>
```

例:
- `omz pr test 12345`
- `omz pr test https://github.com/ohmyzsh/ohmyzsh/pull/12345`

## 入出力項目

### 入力項目

| 項目名 | 型 | 必須 | 説明 |
|--------|-----|------|------|
| PR番号/URL | 文字列 | 必須 | テスト対象のPull Request番号またはGitHub URL |

### 出力項目

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ラベル確認結果 | テキスト | 「testers needed」ラベルの有無を表示 |
| fetch結果 | テキスト | PRのfetch処理の結果 |
| rebase結果 | テキスト | masterへのrebase処理の結果 |
| テスト案内 | テキスト | テスト用zshセッションの起動案内 |
| ブランチ復帰確認 | プロンプト | 元のブランチに戻るかどうかの確認 |

## 表示項目

| 表示項目 | 表示条件 | 説明 |
|----------|----------|------|
| ラベル確認メッセージ | 常時 | PRの「testers needed」ラベル確認中メッセージ |
| セキュリティ警告 | ラベルなし時 | メンテナー未レビューの警告メッセージ |
| 確認プロンプト | ラベルなし時 | 続行するかの確認（"yes"入力が必要） |
| fetch進捗 | 常時 | PRブランチのfetch処理状況 |
| rebase結果 | 常時 | rebase成功/失敗のメッセージ |
| テスト案内 | 成功時 | 新しいzshセッションでのテスト案内 |
| ブランチ復帰確認 | テスト後 | 元のブランチに戻るかの確認プロンプト |

## イベント仕様

### 1-PR番号検証

ユーザーが入力したPR番号/URLを検証します。

- URLが渡された場合、末尾からPR番号を抽出
- 数値以外が含まれている場合はエラーを返す
- 検証失敗時はUsageを表示して終了

### 2-現在ブランチの保存

テスト開始前に現在のgitブランチを保存します。

- `git symbolic-ref --short HEAD` で現在のブランチ名を取得
- 取得失敗時はエラーメッセージを表示して終了

### 3-ラベル確認

GitHub APIを使用してPRの「testers needed」ラベルを確認します。

- `https://api.github.com/repos/ohmyzsh/ohmyzsh/pulls/<PR番号>` にリクエスト
- jqコマンドがある場合はjqでラベルを検索、なければgrepで検索
- ラベルID: `MDU6TGFiZWw4NzY1NTkwNA==`

### 4-セキュリティ確認

「testers needed」ラベルがない場合、セキュリティ警告を表示します。

- 警告メッセージを表示
- 続行するには "yes" を明示的に入力する必要がある
- "yes" 以外の入力は処理をキャンセル

### 5-PRのfetch

PRの変更をローカルにfetchします。

- `git fetch -f <remote> refs/pull/<PR番号>/head:ohmyzsh/pull-<PR番号>`
- fetch失敗時はエラーメッセージを表示して終了

### 6-masterへのrebase

fetchしたPRブランチをmasterにrebaseします。

- commit.gpgsign設定を一時的に無効化
- `git rebase master ohmyzsh/pull-<PR番号>` を実行
- rebase失敗時は警告を表示（テストは続行可能）
- 完了後、gpgsign設定を元に戻す

### 7-テスト用zshセッション起動

PRの変更をテストするための新しいzshセッションを起動します。

- `zsh -l` でログインシェルとして起動
- ユーザーは `exit` で元のセッションに戻る

### 8-ブランチ復帰確認

テスト終了後、元のブランチに戻るかどうかを確認します。

- "Y/n" プロンプトを表示
- Y/y/Enterで元のブランチにcheckout
- それ以外は現在のPRブランチを維持

## データベース更新仕様

本コマンドはデータベースを使用しません。gitリポジトリの操作のみを行います。

### 操作別ファイルシステム影響一覧

| 操作 | 対象 | 操作種別 | 概要 |
|------|------|---------|------|
| PRのfetch | $ZSH/.git | UPDATE | PRブランチをローカルに作成 |
| rebase | $ZSH/.git | UPDATE | PRブランチをmasterにrebase |
| checkout | $ZSH | UPDATE | 作業ディレクトリの内容を変更 |

## メッセージ仕様

| 種別 | メッセージ | 表示条件 |
|------|----------|----------|
| 情報 | "checking if PR #X has the 'testers needed' label..." | ラベル確認開始時 |
| 警告 | "PR #X does not have the 'testers needed' label. This means that the PR has not been reviewed by a maintainer and may contain malicious code." | ラベルなし時 |
| プロンプト | "Do you want to continue testing it? [yes/N]" | ラベルなし時 |
| エラー | "PR test canceled. Please ask a maintainer to review and label the PR." | ラベルなしで続行拒否時 |
| 警告 | "Continuing to check out and test PR #X. Be careful!" | ラベルなしで続行時 |
| 情報 | "fetching PR #X to ohmyzsh/pull-X..." | fetch開始時 |
| エラー | "error when trying to fetch PR #X." | fetch失敗時 |
| 情報 | "rebasing PR #X..." | rebase開始時 |
| 警告 | "could not rebase PR #X on top of master." | rebase失敗時 |
| 情報 | "fetch of PR #X successful." | fetch成功時 |
| 情報 | "running `zsh` to test the changes. Run `exit` to go back." | テスト開始時 |
| プロンプト | "do you want to go back to the previous branch? [Y/n]" | テスト終了時 |
| エラー | "could not go back to the previous branch ('branch')." | checkout失敗時 |

## 例外処理

| 例外状態 | 処理内容 |
|----------|----------|
| PR番号が無効 | Usageを表示して終了 |
| 現在ブランチ取得失敗 | エラーメッセージを表示して終了 |
| ohmyzshリモートが見つからない | エラーメッセージを表示して終了 |
| GitHub API接続エラー | エラーメッセージを表示して終了 |
| fetch失敗 | エラーメッセージを表示して終了 |
| rebase失敗 | 警告を表示、rebaseを中止、テストは続行可能 |
| ブランチ復帰失敗 | エラーメッセージを表示 |

## 備考

- このコマンドはOh My Zshのコントリビューターやメンテナー向けの開発支援ツールです
- セキュリティリスクを軽減するため、「testers needed」ラベルの確認機能が実装されています
- rebaseが失敗した場合でもテストは可能ですが、最新のmaster変更が反映されていない可能性があります
- テスト中のzshセッションでは、PRの変更が適用された状態でOh My Zshが動作します

---

## コードリーディングガイド

本画面を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

まず、コマンドで使用される主要な変数とデータ構造を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | cli.zsh | `lib/cli.zsh` | `_omz::pr::test`関数で使用されるローカル変数（branch, pr_json, label等）を確認 |

**読解のコツ**: zsh特有の変数展開（${1:t}でパスの末尾を取得など）に注意してください。

#### Step 2: エントリーポイントを理解する

処理の起点となるファイル・関数を特定します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | cli.zsh | `lib/cli.zsh` | omz関数（3-21行目）がコマンドのエントリーポイント |

**主要処理フロー**:
1. **行3-8**: コマンドライン引数の確認、引数なしならヘルプ表示
2. **行10-11**: 最初の引数をcommand変数に格納しshift
3. **行15-18**: サブコマンド関数の存在確認
4. **行20**: 該当するサブコマンド関数を呼び出し

#### Step 3: prサブコマンドルーターを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | cli.zsh | `lib/cli.zsh` | `_omz::pr`関数（541-559行目）がprサブコマンドのルーター |

**主要処理フロー**:
- **行542-553**: 引数なしまたは無効なサブコマンドの場合、ヘルプを表示
- **行555-558**: サブコマンドに対応する関数を呼び出し

#### Step 4: pr testコマンドの実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | cli.zsh | `lib/cli.zsh` | `_omz::pr::test`関数（591-724行目）がメインの実装 |

**主要処理フロー**:
- **行593-595**: URLからPR番号を抽出
- **行597-601**: PR番号の検証
- **行603-608**: 現在のブランチを保存
- **行613-666**: PRのラベル確認とセキュリティチェック（サブシェル内）
- **行668-673**: PRのfetch処理
- **行676-698**: masterへのrebase処理
- **行700-701**: fetch成功メッセージ
- **行707-708**: テスト用zshセッション起動
- **行711-723**: ブランチ復帰処理

#### Step 5: ユーティリティ関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | cli.zsh | `lib/cli.zsh` | `_omz::confirm`関数（121-135行目）- 確認プロンプト表示 |
| 5-2 | cli.zsh | `lib/cli.zsh` | `_omz::log`関数（137-162行目）- ログ出力（色付き） |

### プログラム呼び出し階層図

```
omz pr test <PR番号>
    │
    ├─ omz [lib/cli.zsh:3-21]
    │      └─ _omz::pr [lib/cli.zsh:541-559]
    │             └─ _omz::pr::test [lib/cli.zsh:591-724]
    │                    │
    │                    ├─ git symbolic-ref (現在ブランチ取得)
    │                    ├─ curl (GitHub API呼び出し)
    │                    ├─ jq/grep (ラベル検索)
    │                    ├─ _omz::log [lib/cli.zsh:137-162]
    │                    ├─ _omz::confirm [lib/cli.zsh:121-135]
    │                    ├─ git fetch (PR取得)
    │                    ├─ git rebase (masterへrebase)
    │                    ├─ zsh -l (テストセッション起動)
    │                    └─ git checkout (ブランチ復帰)
    │
    └─ _omz [lib/cli.zsh:23-112] (補完関数)
```

### データフロー図

```
[入力]                    [処理]                           [出力]

PR番号/URL ───────────▶ URL解析・検証 ───────────────────▶ エラー時: Usage表示
                              │
                              ▼
                        現在ブランチ保存
                              │
                              ▼
                        GitHub API呼び出し ─────────────▶ ラベル確認結果
                              │
                              ▼ (ラベルなし)
                        セキュリティ確認 ────────────────▶ 警告メッセージ
                              │
                              ▼
                        git fetch PR ────────────────────▶ fetch結果
                              │
                              ▼
                        git rebase master ───────────────▶ rebase結果
                              │
                              ▼
                        zsh -l (テストセッション) ────────▶ 新しいzsh起動
                              │
                              ▼ (exit後)
                        ブランチ復帰確認 ─────────────────▶ checkout結果
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| cli.zsh | `lib/cli.zsh` | ソース | omzコマンドおよびpr testサブコマンドの実装 |
| oh-my-zsh.sh | `oh-my-zsh.sh` | ソース | Oh My Zshのメイン初期化スクリプト（cli.zshをsource） |
