# 機能設計書 74-omz_diagnostic_dump

## 概要

本ドキュメントは、Oh My Zshの診断ライブラリ（lib/diagnostics.zsh）で提供される`omz_diagnostic_dump`関数の機能設計について記述する。

### 本機能の処理概要

`omz_diagnostic_dump`関数は、Oh My Zsh、Zshシェル、およびユーザーのシステム環境に関する診断情報を収集し、ファイルに出力するユーティリティ関数である。収集した情報は、自身の問題を診断したり、GitHubのバグレポートに添付して第三者が問題を診断する際に役立つ。出力は人間が読める形式で、単一のテキストファイルとして生成される。

**業務上の目的・背景**：Oh My Zshの問題（プラグインの競合、設定の不整合、パフォーマンス問題など）を診断する際、環境情報を手動で収集するのは時間がかかり、重要な情報を見落としがちである。本機能は、バグレポートやトラブルシューティングに必要な情報を自動的に収集し、効率的な問題解決を支援する。

**機能の利用シーン**：
- Oh My Zshに問題が発生し、GitHubでバグレポートを作成する場合
- 自身の環境でOh My Zshの動作を診断する場合
- 新しいプラグインやテーマを導入後に問題が発生した場合
- キーバインドやシェル設定の問題をデバッグする場合

**主要な処理内容**：
1. 出力ファイル名の決定（タイムスタンプ付きデフォルト名または指定名）
2. 基本システム情報の収集（OS、Zshバージョン、ユーザー、umask）
3. インストール済みプログラムの情報収集（sh、zsh、bash、git等）
4. Zshプロセス状態の収集（PWD、環境変数、エクスポート、ロケール）
5. Zsh設定の収集（setopt、zstyle、compaudit、fpath）
6. Oh My Zshインストール情報の収集（gitステータス、カスタムディレクトリ）
7. キーバインドとターミナル情報の収集（verboseレベル1以上）
8. 設定ファイル内容の収集（verboseレベル1以上）
9. zcompdumpファイル内容の収集（verboseレベル2以上）

**関連システム・外部連携**：Git（OMZリポジトリ状態確認）、各種シェルコマンド（uname、date、locale等）との連携。

**権限による制御**：特に権限による制御は行われないが、一部ファイル（/etc/配下）はroot権限がないと読めない場合がある。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| N/A | ターミナル | 主画面 | 診断コマンドの実行と出力ファイル生成 |

## 機能種別

診断・レポート生成

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| -v | flag | No | 詳細度を上げる（複数指定可） | - |
| -V | flag | No | 詳細度を下げる（複数指定可） | - |
| file | string | No | 出力ファイルパス | 引数が2つ以上の場合はエラー |

### 入力データソース

- システム情報（uname、date、環境変数）
- Zsh設定（setopt、zstyle、fpath）
- Oh My Zsh設定（$ZSH、$ZSH_CUSTOM、plugins、ZSH_THEME）
- 各種設定ファイル（~/.zshrc、~/.zshenv等）
- Gitリポジトリ状態

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 診断ダンプファイル | text file | omz_diagdump_YYYYMMDD-HHMMSS.txt形式の診断情報ファイル |

### 出力先

- 指定されたファイル（デフォルト: カレントディレクトリのomz_diagdump_タイムスタンプ.txt）

## 処理フロー

### 処理シーケンス

```
1. 引数解析
   └─ zparseopts で -v/-V オプションを解析
2. 詳細度計算
   └─ verbose = 1 + (-vの数) - (-Vの数)
3. 出力ファイル決定
   └─ 引数指定 or デフォルト名（タイムスタンプ付き）
4. 診断情報収集・出力
   └─ _omz_diag_dump_one_big_text を呼び出し
5. 完了メッセージ表示
   └─ ファイルパスとGist共有の案内
```

### フローチャート

```mermaid
flowchart TD
    A[omz_diagnostic_dump呼び出し] --> B[引数解析 zparseopts]
    B --> C[詳細度計算]
    C --> D{出力ファイル指定あり?}
    D -->|Yes| E[指定ファイルを使用]
    D -->|No| F[タイムスタンプ付きデフォルト名]
    E --> G[_omz_diag_dump_one_big_text実行]
    F --> G
    G --> H{エラー発生?}
    H -->|Yes| I[エラーメッセージ表示]
    H -->|No| J[完了メッセージ表示]
    I --> K[終了]
    J --> K
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-74-01 | デフォルト詳細度 | 詳細度のデフォルトは1 | verbose計算時 |
| BR-74-02 | 詳細度0 | 基本情報、シェル状態、OMZ設定、git状態 | verbose=0時 |
| BR-74-03 | 詳細度1 | 詳細度0 + キーバインド、設定ファイル内容 | verbose>=1時 |
| BR-74-04 | 詳細度2 | 詳細度1 + zcompdumpファイル内容 | verbose>=2時 |
| BR-74-05 | 引数制限 | 位置引数は1つまで | 常時 |

### 計算ロジック

```
verbose = 1 + (number of -v flags) - (number of -V flags)
```

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

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

データベース操作なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 1 | 引数エラー | 位置引数が2つ以上指定された場合 | エラーメッセージを表示して終了 |
| N/A | 書き込みエラー | 出力ファイルに書き込めない場合 | エラーメッセージを表示 |

### リトライ仕様

リトライは不要

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

トランザクション管理なし

## パフォーマンス要件

数秒〜数十秒（システム情報収集、ファイル読み込み、Git操作を含む）

## セキュリティ考慮事項

- 出力ファイルにはzshrc等の設定ファイル内容が含まれる
- 環境変数やシェル設定に機密情報が含まれる可能性がある
- 警告メッセージで機密情報の共有について注意喚起している
- 公開前に出力ファイルの内容を確認することを推奨

## 備考

- 作者: Andrew Janke <andrew@apjanke.net>
- 出力はGitHub Gist（https://gist.github.com）で共有することを想定
- 防御的なコーディングスタイルで、echoやwhichが再定義されていても動作するよう設計
- GitHubはtarball等のファイル添付に対応していないため、単一テキストファイルとして出力

---

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

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

### 推奨読解順序

#### Step 1: メイン関数の構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | diagnostics.zsh | `lib/diagnostics.zsh` | omz_diagnostic_dump関数の定義（58-100行目） |

**読解のコツ**: `builtin`プレフィックスは、ユーザーによるコマンド再定義を回避するための防御的コーディング。`emulate -L zsh`でZshエミュレーションモードを有効化。

**主要処理フロー**:
- **59行目**: `emulate -L zsh` - Zshエミュレーションモード設定
- **66行目**: タイムスタンプ生成
- **68行目**: `zparseopts` - オプション解析
- **70行目**: 詳細度計算
- **85行目**: `_omz_diag_dump_one_big_text` - メイン処理呼び出し
- **91-98行目**: 完了メッセージとGist共有案内

#### Step 2: 診断情報収集処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | diagnostics.zsh | `lib/diagnostics.zsh` | _omz_diag_dump_one_big_text関数（102-249行目） |

**主要処理フロー**:
- **111-118行目**: 基本システム情報（date、uname、OSTYPE、ZSH_VERSION）
- **122-142行目**: インストール済みプログラム情報（sh、zsh、bash、git等）
- **156-173行目**: Zshプロセス状態（PWD、環境変数、export、locale）
- **176-187行目**: Zsh設定（setopt、zstyle、compaudit、fpath）
- **189-209行目**: Oh My Zshインストール情報（gitステータス、カスタムディレクトリ）
- **212-219行目**: キーバインドとターミナル情報（verbose>=1）
- **221-247行目**: 設定ファイル・zcompdump内容（verbose>=1/2）

#### Step 3: ヘルパー関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | diagnostics.zsh | `lib/diagnostics.zsh` | _omz_diag_dump_check_core_commands（251-308行目） |
| 3-2 | diagnostics.zsh | `lib/diagnostics.zsh` | _omz_diag_dump_echo_file_w_header（310-327行目） |
| 3-3 | diagnostics.zsh | `lib/diagnostics.zsh` | _omz_diag_dump_os_specific_version（329-352行目） |

**主要処理フロー**:
- **_omz_diag_dump_check_core_commands**: ビルトインコマンドやリザーブドワードが再定義されていないかチェック
- **_omz_diag_dump_echo_file_w_header**: ファイル内容をヘッダー付きで出力
- **_omz_diag_dump_os_specific_version**: OS固有のバージョン情報を取得（macOS: sw_vers、Cygwin: systeminfo等）

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

```
omz_diagnostic_dump() (lib/diagnostics.zsh:58-100)
    │
    ├─ zparseopts (オプション解析)
    │
    └─ _omz_diag_dump_one_big_text() (lib/diagnostics.zsh:102-249)
           │
           ├─ _omz_diag_dump_os_specific_version()
           │
           ├─ _omz_diag_dump_check_core_commands()
           │
           └─ _omz_diag_dump_echo_file_w_header() (複数回呼び出し)
```

### データフロー図

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

コマンドライン引数 ────────▶ omz_diagnostic_dump
(-v/-V/file)                      │
                                  ▼
システム情報 ─────────────▶ _omz_diag_dump_one_big_text ───▶ 診断ダンプファイル
(uname, date, locale)             │                          (omz_diagdump_*.txt)
                                  │
Zsh設定 ──────────────────────────┤
(setopt, zstyle, fpath)           │
                                  │
OMZ設定 ──────────────────────────┤
($ZSH, git status)                │
                                  │
設定ファイル ─────────────────────┘
(~/.zshrc, ~/.zshenv等)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| diagnostics.zsh | `lib/diagnostics.zsh` | ソース | omz_diagnostic_dump関数およびヘルパー関数の定義 |
| oh-my-zsh.sh | `oh-my-zsh.sh` | ソース | lib/diagnostics.zshを読み込むメインスクリプト |
| ~/.zshrc | `~/.zshrc` | 設定 | 収集対象の設定ファイル |
| ~/.zshenv | `~/.zshenv` | 設定 | 収集対象の設定ファイル |
| ~/.zcompdump | `~/.zcompdump*` | キャッシュ | 収集対象の補完キャッシュファイル |
