# 機能設計書 88-vcs_info統合

## 概要

本ドキュメントは、zshのvcs_info機能との統合およびセキュリティパッチを提供する機能の設計について記述する。

### 本機能の処理概要

zshのvcs_info関数で使用されるフィールド（base、branch、revision等）に対して、CVE-2021-45444脆弱性対策としての%エスケープ処理を適用するパッチ機能である。また、git以外のVCS（Bazaar、SVN等）のプロンプト情報表示機能も提供する。

**業務上の目的・背景**：zshのvcs_info機能には、プロンプト展開時にコマンドインジェクションを許す脆弱性（CVE-2021-45444）が存在した。この脆弱性はzsh 5.0.3から5.8に影響し、悪意ある入力（ブランチ名、リポジトリ名など）を通じて任意のコマンドが実行される可能性があった。本機能はこの脆弱性に対するワークアラウンドを提供し、vcs_infoを安全に使用できるようにする。

**機能の利用シーン**：Oh My Zsh初期化時に自動的に読み込まれ、vcs_info関数にパッチを適用する。ユーザーがvcs_infoを使用するテーマやプラグインを利用する際に、自動的にセキュリティ保護が適用される。

**主要な処理内容**：
1. VCS_INFO_formats関数の読み込み
2. hook_comフィールドの%文字を%%にエスケープするパッチを適用
3. パッチが二重適用されないよう一意のIDでチェック
4. Bazaarプロンプト情報関数（bzr_prompt_info）の提供

**関連システム・外部連携**：zshビルトインのvcs_info関数、autoload機能。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 画面関連なし（ライブラリ） |

## 機能種別

セキュリティパッチ / VCS統合

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| なし | - | - | 自動適用される | - |

### 入力データソース

- zsh関数定義：`$functions[VCS_INFO_formats]`
- VCS情報：bzr nick、bzr status等のコマンド出力

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| パッチ適用済み関数 | 関数 | 修正されたVCS_INFO_formats関数 |
| bzr_prompt_info出力 | 文字列 | Bazaarブランチ情報 |

### 出力先

- zsh関数テーブル：パッチ適用済み関数
- プロンプト変数：VCS情報文字列

## 処理フロー

### 処理シーケンス

```
1. 関数の読み込み
   └─ autoload -Uz +X regexp-replace VCS_INFO_formats
2. パッチの定義
   └─ hook_comフィールドの%エスケープコード
3. 二重適用チェック
   └─ PATCH_IDで既存パッチを確認
4. パッチ適用
   └─ regexp-replaceで関数本体を修正
5. クリーンアップ
   └─ 一時変数をunset
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{autoload成功?}
    B -->|No| C[return 0 終了]
    B -->|Yes| D[PATCHコード定義]
    D --> E[PATCH_ID定義]
    E --> F{パッチ適用済み?}
    F -->|Yes| G[スキップ]
    F -->|No| H[regexp-replaceでパッチ適用]
    G --> I[unset PATCH PATCH_ID]
    H --> I
    I --> J[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-88-001 | %エスケープ | hook_comフィールド内の%を%%に変換 | VCS_INFO_formats関数実行時 |
| BR-88-002 | 対象フィールド | base、base-name、branch、misc、revision、subdirの6フィールドが対象 | 常時 |
| BR-88-003 | 二重適用防止 | PATCH_IDが関数内に存在する場合はパッチをスキップ | 既にパッチ適用済みの場合 |
| BR-88-004 | フック前適用 | パッチはpost-backendフック呼び出し直前に適用 | 常時 |

### 計算ロジック

%エスケープ処理：
- `${hook_com[$tmp]//\%/%%}` - %を%%に置換

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | データベース操作なし |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | autoload失敗 | VCS_INFO_formats関数が利用不可 | return 0で終了（影響なし） |

### リトライ仕様

リトライは行わない。

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

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

## パフォーマンス要件

- 初期化時に一度だけ実行
- regexp-replaceは高速に完了

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

- CVE-2021-45444への対策を提供
- 悪意あるVCS情報（ブランチ名等）からのコマンドインジェクションを防止
- zsh 5.0.3から5.8に影響する脆弱性に対応

## 備考

- パッチは全てのzshバージョンに適用される（バージョン判定なし）
- 将来のzshリリースで本問題が修正される可能性あり
- PATCH_ID: vcs_info-patch-9b9840f2-91e5-4471-af84-9e9a0dc68c1b

---

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

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

### 推奨読解順序

#### Step 1: 脆弱性の背景を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | vcs_info.zsh | `lib/vcs_info.zsh` | 1-9行目: 脆弱性の説明コメント |

**読解のコツ**: CVE-2021-45444はzshのprompt_substによる再帰展開の脆弱性。vcs_infoフィールド内の%文字がプロンプトシーケンスとして解釈されてしまう問題。

**主要処理フロー**:
- **1-9行目**: 脆弱性の背景説明
- **10-27行目**: パッチが必要なフィールドの説明
- **28-40行目**: パッチの適用場所の説明

#### Step 2: パッチ適用ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | vcs_info.zsh | `lib/vcs_info.zsh` | 41-53行目: パッチ適用コード |

**主要処理フロー**:
- **41行目**: autoloadでVCS_INFO_formats関数を読み込み
- **44行目**: PATCHコード定義（%を%%に変換）
- **46行目**: PATCH_ID定義（一意識別子）
- **48行目**: 二重適用チェック
- **49-51行目**: regexp-replaceによるパッチ適用
- **53行目**: 一時変数のクリーンアップ

#### Step 3: Bazaar統合を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | bzr.zsh | `lib/bzr.zsh` | 1-15行目: bzr_prompt_info関数 |

**主要処理フロー**:
- **3行目**: 関数定義
- **5行目**: bzr nickでブランチ名取得
- **9-11行目**: bzr statusでダーティ状態チェック
- **12行目**: プロンプト文字列の生成

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

```
oh-my-zsh.sh (初期化)
    │
    ├─ lib/vcs_info.zsh
    │      │
    │      ├─ autoload VCS_INFO_formats
    │      └─ regexp-replace (パッチ適用)
    │
    └─ lib/bzr.zsh
           │
           └─ bzr_prompt_info()
                  ├─ bzr nick
                  └─ bzr status
```

### データフロー図

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

VCS_INFO_formats ────────▶ lib/vcs_info.zsh ──────────▶ パッチ適用済み
(zsh関数)                        │                     VCS_INFO_formats
                                 │
                                 └─▶ hook_com[$tmp]//\%/%%
                                     (%エスケープ)

bzr nick ────────────────▶ lib/bzr.zsh ───────────────▶ プロンプト文字列
bzr status                 (bzr_prompt_info)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| vcs_info.zsh | `lib/vcs_info.zsh` | ソース | vcs_infoセキュリティパッチ |
| bzr.zsh | `lib/bzr.zsh` | ソース | Bazaarプロンプト情報関数 |
| git.zsh | `lib/git.zsh` | ソース | Gitプロンプト情報関数（関連） |
