# 機能設計書 67-diff関数

## 概要

本ドキュメントは、Oh My Zshのテーマ・外観機能における`diff`関数の設計を記載する。この機能は、システムの`diff`コマンドが`--color`オプションをサポートしている場合、デフォルトでカラー出力を有効にするラッパー関数を定義する。

### 本機能の処理概要

**業務上の目的・背景**：ファイルやテキストの差分を確認する際、カラー出力があると追加行（緑）・削除行（赤）が視覚的に識別しやすくなり、レビュー効率が向上する。この機能は、GNU diff等の`--color`オプションをサポートするdiffコマンドが利用可能な場合に、自動的にカラー出力を有効にし、ユーザーの作業効率を向上させる。

**機能の利用シーン**：
- 2つのファイルの差分を確認する際
- 設定ファイルの変更点を確認する際
- パッチ適用前に差分を確認する際

**主要な処理内容**：
1. システムの`diff`コマンドが`--color`オプションをサポートしているか確認する
2. サポートしている場合、`--color`オプションを自動付与する`diff`関数を定義する

**関連システム・外部連携**：
- GNU diff（coreutils）
- システムの`diff`コマンド

**権限による制御**：特になし

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | CLIコマンドのため関連画面なし |

## 機能種別

コマンドラッパー / 外観カスタマイズ

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| $@ | string... | No | 元のdiffコマンドに渡す引数 | なし |

### 入力データソース

- コマンドライン引数
- 比較対象のファイル

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 差分出力 | string | カラー付きの差分出力（標準出力） |
| 戻り値 | integer | 元のdiffコマンドの戻り値 |

### 出力先

- 標準出力

## 処理フロー

### 処理シーケンス

```
1. ファイル読み込み時（関数定義前）
   └─ diff --color /dev/null /dev/null の実行テスト
2. テスト成功時
   └─ diff関数を定義（command diff --color "$@"）
3. テスト失敗時
   └─ diff関数を定義しない（元のdiffコマンドがそのまま使用される）
```

### フローチャート

```mermaid
flowchart TD
    A[theme-and-appearance.zsh読み込み] --> B{diff --color サポート?}
    B -->|Yes| C[diff関数を定義]
    C --> D["function diff { command diff --color \"$@\" }"]
    B -->|No| E[diff関数を定義しない]
    D --> F[終了]
    E --> F

    G[ユーザーがdiff実行] --> H{diff関数定義済み?}
    H -->|Yes| I[diff --color 引数... を実行]
    H -->|No| J[通常のdiffを実行]
    I --> K[カラー差分出力]
    J --> L[モノクロ差分出力]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | サポート確認 | --colorオプションがエラーなく実行できる場合のみ関数を定義 | ファイル読み込み時 |
| BR-02 | 透過的動作 | ユーザーが追加で指定した引数はすべて元のdiffに渡される | 常時 |
| BR-03 | commandプリフィックス | 無限再帰を防ぐためcommandでシステムのdiffを呼び出す | 常時 |

### 計算ロジック

該当なし

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

該当なし（データベースを使用しない）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | --colorオプション非対応 | BSDのdiff等 | 関数を定義せず、元のdiffコマンドを使用 |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- 関数呼び出しのオーバーヘッドは無視できる程度であること
- サポート確認は起動時に1回のみ実行

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

- 特になし

## 備考

- macOSのデフォルトdiff（BSD diff）は`--color`をサポートしていない
- GNU diffをインストールすることで`--color`が使用可能になる
- この機能はGNU coreutilsの`diff`を前提としている

---

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

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

### 推奨読解順序

#### Step 1: サポート確認と関数定義を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | theme-and-appearance.zsh | `lib/theme-and-appearance.zsh` | 16-21行目のdiff関数定義 |

**主要処理フロー**:
- **17行目**: `if command diff --color /dev/null{,} &>/dev/null; then`
  - `command diff`でシステムのdiffを呼び出し
  - `/dev/null{,}`はブレース展開で`/dev/null /dev/null`になる
  - `&>/dev/null`で出力を破棄
- **18-20行目**: `function diff { command diff --color "$@" }`
  - `--color`オプションを付けてdiffを呼び出す関数を定義
  - `"$@"`で元の引数をすべて渡す

**読解のコツ**:
- `command`プリフィックスはエイリアスや関数をバイパスして、コマンドを直接実行する
- `{,}`はブレース展開でカンマの前後に空文字列を展開（つまり同じファイルを2回指定）
- 同じファイルをdiffしても差分なしで正常終了（戻り値0）

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

```
theme-and-appearance.zsh source
    │
    └─ if command diff --color /dev/null /dev/null
           │
           ├─ 成功 → function diff { command diff --color "$@" } 定義
           │
           └─ 失敗 → 関数定義しない

ユーザーコマンド: diff file1 file2
    │
    └─ diff関数（定義済みの場合）
           │
           └─ command diff --color file1 file2
                  │
                  └─ カラー差分出力
```

### データフロー図

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

$@ (引数) ─────────────────────▶                                ┌─ 標準出力
  "file1 file2"                   diff関数                      │   カラー差分
                                  command diff --color "$@" ───▶│
                                                                └─ 戻り値
                                                                    0: 差分なし
                                                                    1: 差分あり
                                                                    2: エラー
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| theme-and-appearance.zsh | `lib/theme-and-appearance.zsh` | ソース | diff関数定義およびテーマ・外観設定のメイン実装 |
