# 機能設計書 70-ディレクトリエイリアス

## 概要

本ドキュメントは、Oh My Zshのディレクトリ管理機能におけるディレクトリエイリアスの設計を記載する。この機能は、ディレクトリ移動やファイル一覧表示を効率化するための各種エイリアスを定義する。

### 本機能の処理概要

**業務上の目的・背景**：開発作業では、親ディレクトリへの移動、ディレクトリスタックからの復帰、ファイル一覧の確認など、ディレクトリ操作が頻繁に発生する。この機能は、`...`（2階層上）、`cd -N`（スタックN番目）、`l`/`ll`/`la`（ls各種オプション）といった短縮形エイリアスを提供し、タイピング量を削減して作業効率を向上させる。

**機能の利用シーン**：
- 深いディレクトリ構造から素早く親ディレクトリに移動したい場合
- 最近訪れたディレクトリに番号指定で戻りたい場合
- ファイル一覧を詳細表示、隠しファイル含めて表示したい場合
- ディレクトリの作成と移動を同時に行いたい場合

**主要な処理内容**：
1. `...`, `....`, `.....`, `......`のグローバルエイリアスを定義する
2. `-`, `1`-`9`のディレクトリスタックエイリアスを定義する
3. `md`（mkdir -p）、`rd`（rmdir）のエイリアスを定義する
4. `d`関数（ディレクトリスタック表示）を定義する
5. `lsa`, `l`, `ll`, `la`のlsエイリアスを定義する

**関連システム・外部連携**：
- zshのディレクトリスタック機能
- mkdir、rmdir、lsコマンド

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

## 関連画面

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

## 機能種別

エイリアス定義 / 関数定義

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| なし | - | - | 初期化処理のため入力パラメータなし | - |

### 入力データソース

なし（エイリアス・関数定義のみ）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| グローバルエイリアス | alias | `...`, `....`, `.....`, `......` |
| 通常エイリアス | alias | `-`, `1`-`9`, `md`, `rd`, `lsa`, `l`, `ll`, `la` |
| 関数 | function | `d`関数（ディレクトリスタック表示） |

### 出力先

- シェルエイリアス/関数（グローバルスコープ）

## 処理フロー

### 処理シーケンス

```
1. グローバルエイリアス定義（...〜......）
   └─ alias -g ...='../..'
2. ディレクトリ移動エイリアス定義
   ├─ alias -- -='cd -'
   └─ alias 1='cd -1' 〜 alias 9='cd -9'
3. ディレクトリ操作エイリアス定義
   ├─ alias md='mkdir -p'
   └─ alias rd=rmdir
4. d関数定義
   └─ function d () { dirs "$@" または dirs -v | head -n 10 }
5. ls関連エイリアス定義
   ├─ alias lsa='ls -lah'
   ├─ alias l='ls -lah'
   ├─ alias ll='ls -lh'
   └─ alias la='ls -lAh'
```

### フローチャート

```mermaid
flowchart TD
    A[directories.zsh読み込み] --> B[グローバルエイリアス定義]
    B --> C["alias -g ...='../..' 等"]
    C --> D[ディレクトリ移動エイリアス定義]
    D --> E["alias -- -='cd -'"]
    E --> F["alias 1='cd -1' 〜 9"]
    F --> G[ディレクトリ操作エイリアス定義]
    G --> H["alias md='mkdir -p'"]
    H --> I["alias rd=rmdir"]
    I --> J[d関数定義]
    J --> K[ls関連エイリアス定義]
    K --> L["alias lsa='ls -lah' 等"]
    L --> M[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | グローバルエイリアス | `...`等はコマンドライン中のどこでも展開される | 常時 |
| BR-02 | ダブルダッシュ | `-`エイリアスは`alias -- -`で定義（オプションと区別） | 常時 |
| BR-03 | d関数引数あり | 引数がある場合はdirsにそのまま渡す | 引数指定時 |
| BR-04 | d関数引数なし | 引数がない場合はスタック上位10件を番号付きで表示 | 引数なし時 |

### 計算ロジック

該当なし

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | - | エラーは発生しない設計 | - |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- エイリアス・関数定義のみのため、瞬時に完了

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

- 特になし

## 備考

- グローバルエイリアス（`-g`オプション）は、コマンドライン中のどこでも展開される（例: `ls .../file` → `ls ../../file`）
- `d`関数には補完が設定されている（`compdef _dirs d`）
- `l`と`lsa`は同じ（`ls -lah`）、`ll`は`ls -lh`、`la`は`ls -lAh`（大文字Aは`.`と`..`を除く）

---

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

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

### 推奨読解順序

#### Step 1: グローバルエイリアスを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | directories.zsh | `lib/directories.zsh` | 8-11行目のグローバルエイリアス |

**主要処理フロー**:
- **8行目**: `alias -g ...='../..'` - 2階層上
- **9行目**: `alias -g ....='../../..'` - 3階層上
- **10行目**: `alias -g .....='../../../..'` - 4階層上
- **11行目**: `alias -g ......='../../../../..'` - 5階層上

**読解のコツ**:
- `-g`オプションでグローバルエイリアスとして定義
- グローバルエイリアスはコマンドライン中のどこでも展開される
- 例: `cp .../file .` は `cp ../../file .` に展開

#### Step 2: ディレクトリ移動エイリアスを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | directories.zsh | `lib/directories.zsh` | 13-22行目のディレクトリ移動エイリアス |

**主要処理フロー**:
- **13行目**: `alias -- -='cd -'` - 直前のディレクトリに移動
- **14-22行目**: `alias 1='cd -1'` 〜 `alias 9='cd -9'` - スタックN番目に移動

**読解のコツ**:
- `alias -- -`のダブルダッシュは、`-`がオプションではなくエイリアス名であることを示す
- `cd -N`はpushdminusオプションと組み合わせてスタックのN番目に移動

#### Step 3: ディレクトリ操作エイリアスを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | directories.zsh | `lib/directories.zsh` | 24-25行目のディレクトリ操作エイリアス |

**主要処理フロー**:
- **24行目**: `alias md='mkdir -p'` - 親ディレクトリも同時に作成
- **25行目**: `alias rd=rmdir` - 空ディレクトリ削除

#### Step 4: d関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | directories.zsh | `lib/directories.zsh` | 27-34行目のd関数 |

**主要処理フロー**:
- **27行目**: `function d () {` - 関数定義開始
- **28-29行目**: `if [[ -n $1 ]]; then dirs "$@"` - 引数ありならdirsに渡す
- **30-31行目**: `else dirs -v | head -n 10` - 引数なしなら上位10件表示
- **34行目**: `compdef _dirs d` - 補完設定

**読解のコツ**:
- `dirs -v`は番号付きでスタックを表示
- `head -n 10`で上位10件に制限

#### Step 5: ls関連エイリアスを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | directories.zsh | `lib/directories.zsh` | 36-41行目のlsエイリアス |

**主要処理フロー**:
- **37行目**: `alias lsa='ls -lah'` - 全ファイル詳細表示
- **38行目**: `alias l='ls -lah'` - lsaと同じ
- **39行目**: `alias ll='ls -lh'` - 詳細表示（隠しファイルなし）
- **40行目**: `alias la='ls -lAh'` - .と..以外の隠しファイル含む詳細表示

**読解のコツ**:
- `-a`: 隠しファイル（.始まり）を表示
- `-A`: .と..以外の隠しファイルを表示
- `-l`: 詳細表示
- `-h`: 人間が読みやすいサイズ表示

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

```
oh-my-zsh.sh (エントリポイント)
    │
    └─ source lib/directories.zsh
           │
           ├─ グローバルエイリアス
           │      └─ ..., ...., ....., ......
           │
           ├─ ディレクトリ移動エイリアス
           │      └─ -, 1, 2, ..., 9
           │
           ├─ ディレクトリ操作エイリアス
           │      └─ md, rd
           │
           ├─ d関数
           │      └─ dirs表示
           │
           └─ lsエイリアス
                  └─ lsa, l, ll, la
```

### データフロー図

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

... (エイリアス) ─────────────▶ 展開: ../.. ────────────────────▶ 2階層上パス

cd -3 (コマンド) ─────────────▶ スタック3番目参照 ─────────────▶ ディレクトリ移動

d (コマンド) ─────────────────▶ dirs -v | head -n 10 ──────────▶ スタック一覧表示
  0  ~/Work
  1  /tmp
  2  /etc
  ...

l (エイリアス) ───────────────▶ ls -lah ────────────────────────▶ ファイル一覧
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| directories.zsh | `lib/directories.zsh` | ソース | ディレクトリエイリアスおよびディレクトリ関連設定のメイン実装 |
