# 機能設計書 8-オーバーレイ

## 概要

本ドキュメントは、Nushellにおけるオーバーレイ機能について定義する。オーバーレイは名前空間の階層的な管理を可能にし、一時的な環境の切り替えや、モジュールベースの作業環境の構築を支援する。

### 本機能の処理概要

**業務上の目的・背景**：異なるプロジェクトや作業コンテキストで異なるコマンド・変数・環境変数のセットを使用したい場合がある。オーバーレイを使用することで、これらの設定を切り替えながら作業できる。また、変更を破棄して元の状態に戻ることも容易である。

**機能の利用シーン**：
- プロジェクト固有の環境設定の適用
- 一時的なコマンド・変数の追加
- 仮想環境（Python venv等）の管理
- 設定変更のロールバック

**主要な処理内容**：
1. `overlay use` - オーバーレイの有効化（モジュールベース）
2. `overlay list` - アクティブなオーバーレイの一覧表示
3. `overlay new` - 空のオーバーレイを新規作成
4. `overlay hide` - オーバーレイの非表示（一時的な無効化）

**関連システム・外部連携**：nu-parser（構文解析）、nu-engine（評価）と連携する。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | メインREPL | 主画面 | オーバーレイの管理 |

## 機能種別

名前空間管理 / 環境切り替え

## 入力仕様

### 入力パラメータ

#### overlay use コマンド
| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| name | String/Nothing | Yes | モジュール名（nullでno-op） | 有効な識別子/パス |
| as | Keyword(as, String) | No | 別名 | - |
| --prefix | Switch | No | コマンド名にモジュール名を前置 | - |
| --reload | Switch | No | 既存オーバーレイの再読み込み | - |

#### overlay hide コマンド
| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| name | String | No | 非表示にするオーバーレイ名 | 有効な識別子 |
| --keep-custom | Switch | No | カスタム定義を保持 | - |
| --keep-env | Switch | No | 環境変数を保持 | - |

### 入力データソース

- ユーザーからのコマンドライン入力
- スクリプトファイル

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| PipelineData | PipelineData | overlay list はリストを返す、その他はEmpty |

### 出力先

- Stack（オーバーレイスタックの更新）
- 画面表示（overlay list）

## 処理フロー

### 処理シーケンス

```
1. overlay use
   └─ モジュール解決
   └─ export-envブロックの評価（あれば）
   └─ オーバーレイの有効化
   └─ 環境変数のマージ
2. overlay hide
   └─ オーバーレイの非表示化
   └─ 必要に応じてカスタム定義・環境の保持
3. overlay new
   └─ 空のオーバーレイを作成して有効化
4. overlay list
   └─ アクティブなオーバーレイ名を返却
```

### フローチャート

```mermaid
flowchart TD
    A[overlay コマンド] --> B{サブコマンド}
    B -->|use| C[モジュール解決]
    C --> D{export-env?}
    D -->|Yes| E[ブロック評価]
    D -->|No| F[オーバーレイ有効化]
    E --> G[環境マージ]
    G --> F
    B -->|hide| H[オーバーレイ非表示]
    H --> I{--keep-*?}
    I -->|Yes| J[指定項目を保持]
    I -->|No| K[完全に非表示]
    B -->|new| L[空オーバーレイ作成]
    B -->|list| M[オーバーレイ一覧返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | スタック構造 | オーバーレイはスタック構造で管理 | 常時 |
| BR-002 | 名前解決優先順位 | 後から有効化したオーバーレイが優先 | 名前解決時 |
| BR-003 | PWD保護 | overlay use時にPWDは復元されない | オーバーレイ切り替え時 |
| BR-004 | as別名 | overlay use X as Y でYとして参照可能 | as指定時 |
| BR-005 | prefix | --prefixで修飾付きインポート | --prefix指定時 |

### 計算ロジック

特になし。

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

本機能はデータベース操作を直接行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| OverlayNotFoundAtRuntime | 解決エラー | オーバーレイが見つからない | 名前を確認 |
| NonUtf8 | エンコードエラー | パスがUTF-8でない | パスを確認 |

### リトライ仕様

リトライは行わない。

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

オーバーレイ操作はトランザクション管理を行わない。

## パフォーマンス要件

特になし。

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

- モジュールファイルへのファイルシステムアクセス

## 備考

- overlay useはパーサーキーワードとして実装
- デフォルトオーバーレイは "zero" という名前

---

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

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

### 推奨読解順序

#### Step 1: コマンド定義を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | use_.rs | `crates/nu-cmd-lang/src/core_commands/overlay/use_.rs` | overlay useの実装 |
| 1-2 | hide.rs | `crates/nu-cmd-lang/src/core_commands/overlay/hide.rs` | overlay hideの実装 |
| 1-3 | new.rs | `crates/nu-cmd-lang/src/core_commands/overlay/new.rs` | overlay newの実装 |
| 1-4 | list.rs | `crates/nu-cmd-lang/src/core_commands/overlay/list.rs` | overlay listの実装 |

**主要処理フロー（use_.rs）**:
- **21-46行目**: シグネチャ定義。name, as, --prefix, --reload
- **57-184行目**: run関数
- **113-178行目**: export-envブロックの評価と環境マージ
- **164行目**: add_overlayでオーバーレイを有効化
- **166-168行目**: PWDの保護処理

#### Step 2: スタック操作を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | stack.rs | `crates/nu-protocol/src/engine/stack.rs` | add_overlay, remove_overlay 等 |

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

```
overlay use spam
    │
    ├─ パース時
    │      └─ overlay_expr生成
    │
    └─ 実行時
           └─ OverlayUse.run
                  ├─ export-env評価
                  ├─ add_overlay
                  ├─ PWD保護
                  └─ redirect_env

overlay hide
    │
    └─ 実行時
           └─ OverlayHide.run
                  ├─ remove_overlay
                  └─ --keep-* 処理
```

### データフロー図

```
[定義]                  [管理]                       [使用]

overlay use spam
    │
    ▼
モジュール解決 ───────▶ オーバーレイスタック ────▶ Stack
                                                │
                                                ▼
                        名前解決 ◀────────────────
                           │
                           ▼
                    コマンド/変数取得
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| use_.rs | `crates/nu-cmd-lang/src/core_commands/overlay/use_.rs` | ソース | overlay use |
| hide.rs | `crates/nu-cmd-lang/src/core_commands/overlay/hide.rs` | ソース | overlay hide |
| new.rs | `crates/nu-cmd-lang/src/core_commands/overlay/new.rs` | ソース | overlay new |
| list.rs | `crates/nu-cmd-lang/src/core_commands/overlay/list.rs` | ソース | overlay list |
| command.rs | `crates/nu-cmd-lang/src/core_commands/overlay/command.rs` | ソース | overlayコマンド（ヘルプ） |
| stack.rs | `crates/nu-protocol/src/engine/stack.rs` | ソース | オーバーレイスタック管理 |
