# 機能設計書 46-zsh_stats

## 概要

本ドキュメントは、Oh My Zshのzsh_stats機能について、その設計と実装の詳細を記載したものである。この機能は、コマンド履歴を分析し、最も頻繁に使用されたコマンドのTop20を集計して表示する。

### 本機能の処理概要

この機能は、ユーザーのコマンド履歴を統計的に分析し、使用頻度の高いコマンドをランキング形式で表示する。履歴全体を読み込み、各コマンドの出現回数をカウントし、使用率（パーセンテージ）とともに上位20件を表示する。

**業務上の目的・背景**：コマンドライン作業の効率化において、自分がどのコマンドをよく使用しているかを把握することは重要である。本機能により、ユーザーは自身の作業パターンを可視化でき、エイリアスの設定や作業効率化の指針を得ることができる。また、教育目的で他者のコマンド使用傾向を分析する場合にも有用である。

**機能の利用シーン**：
- 自分の作業パターンを分析したい場面
- よく使うコマンドに対してエイリアスを設定するための調査
- シェルの使用状況を把握したい場面
- 新しい環境でどのようなコマンドが使われているかを確認したい場面

**主要な処理内容**：
1. `fc -l 1` で全コマンド履歴を取得
2. AWKで各コマンドの出現回数と使用率を集計
3. `./*`で始まるローカルスクリプト実行を除外
4. 出現回数の降順でソート
5. 上位20件を抽出
6. カラム整形して行番号付きで表示

**関連システム・外部連携**：
- fc コマンド（ZSHビルトイン）
- awk、grep、sort、head、column、nl コマンド

**権限による制御**：特になし。全ユーザーが利用可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 本機能はターミナル上にテキストを出力する |

## 機能種別

集計処理 / 統計分析 / レポート表示

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| なし | - | - | コマンドライン引数なし | なし |

### 入力データソース

- コマンド履歴（fc -l 1で取得）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 順位 | 数値 | 1-20のランキング番号 |
| 出現回数 | 数値 | コマンドの使用回数 |
| 使用率 | パーセンテージ | 全履歴に対する使用割合 |
| コマンド名 | 文字列 | コマンド名 |

### 出力先

- 標準出力（ターミナル画面）

## 処理フロー

### 処理シーケンス

```
1. 履歴の取得
   └─ fc -l 1 で全履歴を取得

2. 集計処理
   └─ AWKで各コマンドの出現回数をカウント

3. フィルタリング
   └─ "./"で始まるコマンドを除外

4. ソート
   └─ 出現回数の降順でソート

5. 上位抽出
   └─ 上位20件を抽出

6. 整形出力
   └─ カラム整形して行番号を付与
```

### フローチャート

```mermaid
flowchart TD
    A[zsh_stats実行] --> B[fc -l 1で全履歴取得]
    B --> C[AWKで集計]
    C --> D[grep -v で./*除外]
    D --> E[sort -nr でソート]
    E --> F[head -n 20 で上位20件]
    F --> G[column -c3 で整形]
    G --> H[nl で行番号付与]
    H --> I[標準出力に表示]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-46-1 | 全履歴対象 | fc -l 1により履歴番号1から全履歴を対象とする | 常時 |
| BR-46-2 | コマンド名のみ集計 | 履歴の2番目のフィールド（コマンド名）のみを集計 | 常時 |
| BR-46-3 | ローカルスクリプト除外 | "./"で始まるコマンドは集計から除外 | 常時 |
| BR-46-4 | Top20表示 | 上位20件のみを表示 | 常時 |

### 計算ロジック

```
使用率(%) = (コマンドの出現回数 / 全コマンド数) × 100
```

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | 本機能はデータベースを使用しない |

### テーブル別操作詳細

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 履歴なし | コマンド履歴が空の場合 | 空の結果を表示 |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- 履歴サイズに比例した処理時間
- 通常の使用では数秒以内に完了

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

- コマンド履歴の内容が表示されるため、機密情報を含むコマンドがある場合は注意
- 履歴ファイルへのアクセス権限が必要

## 備考

- 履歴サイズが大きい場合は処理時間が増加する可能性がある
- 引数やオプションは集計対象外（コマンド名のみ）

---

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

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

### 推奨読解順序

#### Step 1: 関数定義を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | functions.zsh | `lib/functions.zsh` | 1-5行目のzsh_stats関数定義 |

**主要処理フロー**:
1. **2行目**: `fc -l 1` - 履歴番号1から全履歴を取得
2. **3行目**: AWKスクリプト - コマンドの集計処理
   - `CMD[$2]++`: 2番目のフィールド（コマンド名）をキーとして出現回数をカウント
   - `count++`: 全コマンド数をカウント
   - `END { ... }`: 集計結果を出力
3. **4行目**: パイプライン処理
   - `grep -v "./"`: ローカルスクリプト実行を除外
   - `sort -nr`: 数値降順ソート
   - `head -n 20`: 上位20件を抽出
   - `column -c3 -s " " -t`: カラム整形
   - `nl`: 行番号付与

**読解のコツ**:
- AWKの`$2`は空白区切りの2番目のフィールド（fcの出力では行番号が$1、コマンド名が$2）
- 連想配列`CMD`を使用してコマンドごとの出現回数を集計
- パーセンテージは`CMD[a]*100/count`で算出

#### Step 2: 出力パイプラインを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | functions.zsh | `lib/functions.zsh` | 4行目のパイプライン |

**コマンドチェーン**:
```
fc -l 1 | awk '...' | grep -v "./" | sort -nr | head -n 20 | column -c3 -s " " -t | nl
```

各コマンドの役割:
- `fc -l 1`: 履歴を行番号付きで出力
- `awk '{...}'`: コマンド集計とパーセンテージ計算
- `grep -v "./"`: "./xxx"形式のコマンドを除外
- `sort -nr`: 数値降順ソート（出現回数順）
- `head -n 20`: 上位20件のみ抽出
- `column -c3 -s " " -t`: テーブル形式に整形
- `nl`: 行番号（順位）を付与

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

```
zsh_stats関数
    │
    ├─ fc -l 1（ZSHビルトイン）
    │      └─ 全履歴を取得
    │
    ├─ awk（外部コマンド）
    │      └─ 集計処理
    │
    ├─ grep -v "./"（外部コマンド）
    │      └─ フィルタリング
    │
    ├─ sort -nr（外部コマンド）
    │      └─ ソート
    │
    ├─ head -n 20（外部コマンド）
    │      └─ 上位抽出
    │
    ├─ column -c3 -s " " -t（外部コマンド）
    │      └─ カラム整形
    │
    └─ nl（外部コマンド）
           └─ 行番号付与
```

### データフロー図

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

HISTFILE               fc -l 1                        標準出力
    │                      │                              │
    ▼                      ▼                              ▼
全コマンド履歴 ───▶  AWKで集計 ───▶  grep/sort/head ───▶  Top20リスト
                     ・出現回数
                     ・使用率計算
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| functions.zsh | `lib/functions.zsh` | ソース | zsh_stats関数の定義 |
| .zsh_history | `~/.zsh_history` | データ | コマンド履歴ファイル（fc経由で参照） |
