# 機能設計書 35-ディレクトリ操作

## 概要

本ドキュメントは、Nushellにおけるディレクトリ操作機能（cd, ls, mkdir, glob）の設計を記述する。これらのコマンドはファイルシステムのディレクトリに対する基本的な操作を提供する。

### 本機能の処理概要

**業務上の目的・背景**：
ディレクトリ操作はシェルの最も基本的な機能であり、ファイルシステムのナビゲーション、内容の確認、新規ディレクトリの作成、パターンマッチングによるファイル検索を可能にする。Nushellは構造化データを扱うため、lsコマンドは単なるテキスト出力ではなくテーブル形式のデータを返し、後続のフィルタリングやソートを容易にする。

**機能の利用シーン**：
- 作業ディレクトリの変更（cd）
- ディレクトリ内容の一覧表示とフィルタリング（ls）
- プロジェクト構造の作成（mkdir）
- 特定パターンのファイル検索（glob）

**主要な処理内容**：
1. `cd`: カレントディレクトリを変更する
2. `ls`: ディレクトリの内容を構造化テーブルとして一覧表示する
3. `mkdir`: ディレクトリを作成する（中間ディレクトリも自動作成）
4. `glob`: globパターンに基づいてファイル/ディレクトリを検索する

**関連システム・外部連携**：
- nu-glob クレート（globパターンマッチング）
- wax クレート（高度なglobパターン）
- uu_mkdir（uutils/coreutils）
- nu-path クレート（パス操作）

**権限による制御**：
- ファイルシステムの権限に従う
- cdはディレクトリへのアクセス権限が必要
- mkdirは親ディレクトリへの書き込み権限が必要

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | メインREPL | 参照画面 | コマンド入力・結果表示 |

## 機能種別

ファイルシステム操作

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| path (cd) | Directory | No | 移動先ディレクトリ | 存在するディレクトリ |
| pattern (ls) | GlobPattern/String | No | 一覧表示するパターン | 有効なパス/globパターン |
| rest (mkdir) | GlobPattern/Directory | Yes | 作成するディレクトリ | 有効なパス |
| glob (glob) | String/GlobPattern | Yes | 検索パターン | 有効なglobパターン |

### 入力データソース

コマンドライン引数

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| cd 出力 | Nothing | 出力なし（環境変数PWDを変更） |
| ls 出力 | Table | name, type, size, modified等のカラムを持つテーブル |
| mkdir 出力 | Nothing/String | 通常は出力なし、-vフラグで作成したディレクトリ名 |
| glob 出力 | List<String> | マッチしたパスのリスト |

### ls コマンド出力カラム

| カラム名 | 型 | 説明 | 条件 |
|----------|-----|------|------|
| name | String | ファイル/ディレクトリ名 | 常に |
| type | String | 種別（dir/file/symlink等） | 常に |
| size | Filesize | サイズ | 常に |
| modified | Date | 最終更新日時 | 常に |
| target | String | シンボリックリンク先 | -l（long）時 |
| readonly | Bool | 読み取り専用フラグ | -l（long）時 |
| mode | String | パーミッション（Unix） | -l（long）時、Unix |
| user | String | 所有者 | -l（long）時、Unix |
| group | String | グループ | -l（long）時、Unix |
| created | Date | 作成日時 | -l（long）時 |
| accessed | Date | 最終アクセス日時 | -l（long）時 |

### 出力先

- cd: 環境変数PWD
- ls/glob: パイプライン出力

## 処理フロー

### 処理シーケンス

```
[cd]
1. 引数の取得
   └─ 未指定の場合はホームディレクトリ
2. パスの検証
   └─ 存在確認、ディレクトリ確認、権限確認
3. OLDPWDの保存
   └─ 現在のPWDをOLDPWDに設定
4. PWDの更新
   └─ 新しいディレクトリをPWDに設定

[ls]
1. パターン引数の取得
   └─ 未指定の場合は現在のディレクトリ
2. glob展開
   └─ パターンにマッチするエントリを取得
3. 各エントリのメタデータ取得
   └─ 並列処理オプション対応
4. テーブル形式で返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{コマンド種別}
    B -->|cd| C{パス指定?}
    C -->|No| D[ホームディレクトリ]
    C -->|Yes| E{"-"?}
    E -->|Yes| F[OLDPWD取得]
    E -->|No| G[パス展開]
    D --> H{ディレクトリ存在?}
    F --> H
    G --> H
    H -->|No| I[エラー返却]
    H -->|Yes| J{権限あり?}
    J -->|No| K[PermissionDeniedエラー]
    J -->|Yes| L[OLDPWD更新]
    L --> M[PWD更新]
    M --> N[終了]
    B -->|ls| O[パターン取得]
    O --> P[glob展開]
    P --> Q[メタデータ取得]
    Q --> R[テーブル生成]
    R --> N
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-35-1 | ホームディレクトリ | cd引数なしでホームに移動 | cd引数未指定 |
| BR-35-2 | 前ディレクトリ | cd -でOLDPWDに移動 | "-"引数 |
| BR-35-3 | 隠しファイル | ls -aで隠しファイルを表示 | -aフラグ |
| BR-35-4 | 再帰作成 | mkdirは中間ディレクトリも作成 | 常に |
| BR-35-5 | 物理パス | cd -Pでシンボリックリンクを解決 | -Pフラグ |

### 計算ロジック

- ディスク使用量（ls -d）: DirInfoを使用して再帰的にサイズを計算
- ソート: パスの辞書順（スレッド使用時は非決定的）

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

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

該当なし（ファイルシステム操作のみ）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| DirectoryNotFound | IOエラー | 指定パスが存在しない | 正しいパスを指定 |
| NotADirectory | IOエラー | パスがディレクトリでない | ディレクトリを指定 |
| PermissionDenied | IOエラー | アクセス権限がない | 権限を確認 |
| GenericError | 一般エラー | globパターンが無効 | 正しいパターンを使用 |

### リトライ仕様

該当なし

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

該当なし（ファイルシステム操作はトランザクションをサポートしない）

## パフォーマンス要件

- ls -t（スレッド使用）で大量ファイルを高速処理
- glob展開はwaxライブラリを使用して効率的に実行

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

- ファイルシステムの権限モデルに従う
- シンボリックリンクの追跡は設定可能
- 隠しファイルはデフォルトで非表示

## 備考

- mkdirはuutils/coreutilsの実装を使用
- lsはPipelineMetadataにDataSource::Lsを設定
- globはwaxライブラリの拡張globパターンをサポート

---

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

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

### 推奨読解順序

#### Step 1: データ構造を理解する

lsコマンドの出力構造とLsEntry型を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ls.rs | `crates/nu-command/src/filesystem/ls.rs` | LsEntry構造体（25-127行目） |

**読解のコツ**: LsEntryはプラットフォーム別にメタデータのキャッシュ方法が異なる（Windowsはmetadata、Unixはfile_type）。

#### Step 2: エントリーポイントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | cd.rs | `crates/nu-command/src/filesystem/cd.rs` | Cdコマンドの実装 |
| 2-2 | ls.rs | `crates/nu-command/src/filesystem/ls.rs` | Lsコマンドの実装 |
| 2-3 | umkdir.rs | `crates/nu-command/src/filesystem/umkdir.rs` | UMkdirコマンドの実装 |
| 2-4 | glob.rs | `crates/nu-command/src/filesystem/glob.rs` | Globコマンドの実装 |

**主要処理フロー**:
1. **32-144行目 (cd.rs)**: run関数でパス検証とPWD更新
2. **191-269行目 (ls.rs)**: run関数でパターン処理と出力生成
3. **51-118行目 (umkdir.rs)**: run関数でuu_mkdir呼び出し
4. **129-291行目 (glob.rs)**: run関数でwaxライブラリ使用

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | ls.rs | `crates/nu-command/src/filesystem/ls.rs` | dir_entry_dict関数（712-898行目） |

**主要処理フロー**:
- **736-746行目**: name, typeカラムの設定
- **748-777行目**: targetカラム（シンボリックリンク先）
- **819-854行目**: sizeカラムの設定
- **856-897行目**: 日時カラムの設定

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

```
Ls::run()
    │
    ├─ call.rest() [パターン引数取得]
    │
    └─ ls_for_one_pattern()
           │
           ├─ glob_from() / read_dir()
           │
           └─ rayon::spawn() [並列処理]
                  │
                  └─ dir_entry_dict()
                         │
                         ├─ get_file_type()
                         │
                         └─ DirInfo::new() [du時]
```

### データフロー図

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

パターン ───────▶ Ls::run() ───────────▶ Table
    │                  │
    │                  ├─ glob展開
    │                  │
    │                  ├─ メタデータ取得
    │                  │
    │                  └─ テーブル構築
    │
フラグ ────────────────┘
(-a, -l, -d, -t等)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| cd.rs | `crates/nu-command/src/filesystem/cd.rs` | ソース | cd コマンド実装 |
| ls.rs | `crates/nu-command/src/filesystem/ls.rs` | ソース | ls コマンド実装 |
| umkdir.rs | `crates/nu-command/src/filesystem/umkdir.rs` | ソース | mkdir コマンド実装 |
| glob.rs | `crates/nu-command/src/filesystem/glob.rs` | ソース | glob コマンド実装 |
| mod.rs | `crates/nu-command/src/filesystem/mod.rs` | ソース | filesystemモジュール定義 |
| util.rs | `crates/nu-command/src/filesystem/util.rs` | ソース | 共通ユーティリティ |
