# 機能設計書 9-スコープ管理

## 概要

本ドキュメントは、Nushellにおけるスコープ管理機能について定義する。スコープ管理機能は、現在のスコープ内で利用可能な変数、コマンド、モジュール、エイリアス、外部コマンドの情報を取得するためのコマンド群を提供する。

### 本機能の処理概要

**業務上の目的・背景**：デバッグやスクリプト開発において、現在のスコープでどのような定義が利用可能かを確認したい場合がある。スコープ管理機能により、実行時の状態を可視化し、問題の診断を支援する。

**機能の利用シーン**：
- 定義されている変数の確認
- 利用可能なコマンドの一覧取得
- モジュール・エイリアスの確認
- エンジン統計情報の取得
- デバッグ・開発時の状態確認

**主要な処理内容**：
1. `scope` - スコープ関連コマンドのヘルプ表示
2. `scope variables` - スコープ内の変数一覧
3. `scope commands` - スコープ内のコマンド一覧
4. `scope aliases` - スコープ内のエイリアス一覧
5. `scope modules` - スコープ内のモジュール一覧
6. `scope externs` - スコープ内の外部コマンド宣言一覧
7. `scope engine-stats` - エンジン統計情報

**関連システム・外部連携**：nu-engine（スコープ情報収集）と連携する。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | メインREPL | 主画面 | スコープ情報の取得 |
| 10 | LSP言語サーバ | 参照画面 | 変数・コマンド・モジュールの定義位置・参照の解決 |

## 機能種別

情報取得 / 状態可視化

## 入力仕様

### 入力パラメータ

scopeサブコマンドはパラメータを取らない。

### 入力データソース

- EngineState（グローバル状態）
- Stack（ランタイム状態）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| scope variables | list<record> | 変数情報のリスト |
| scope commands | list<record> | コマンド情報のリスト |
| scope aliases | list<record> | エイリアス情報のリスト |
| scope modules | list<record> | モジュール情報のリスト |
| scope externs | list<record> | 外部コマンド情報のリスト |
| scope engine-stats | record | エンジン統計情報 |

### 出力先

- パイプライン後段
- 画面表示

## 処理フロー

### 処理シーケンス

```
1. ScopeData構築
   └─ EngineState, Stackから情報収集
2. オーバーレイスキャン
   └─ アクティブなオーバーレイから定義を収集
3. データ整形
   └─ Valueのリスト/レコードに変換
4. 結果返却
```

### フローチャート

```mermaid
flowchart TD
    A[scope コマンド] --> B{サブコマンド}
    B -->|variables| C[変数収集]
    B -->|commands| D[コマンド収集]
    B -->|aliases| E[エイリアス収集]
    B -->|modules| F[モジュール収集]
    B -->|externs| G[外部コマンド収集]
    B -->|engine-stats| H[統計収集]
    C --> I[オーバーレイスキャン]
    D --> I
    E --> I
    F --> I
    G --> I
    I --> J[データ整形]
    J --> K[リスト/レコード返却]
    H --> L[エンジン統計返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | アクティブオーバーレイ | アクティブなオーバーレイの定義のみ表示 | 常時 |
| BR-002 | 可視性 | 非公開の定義は表示しない | visibility チェック時 |
| BR-003 | ソート | 結果は名前でソート | 常時 |
| BR-004 | 定数フラグ | 変数のis_constフラグを表示 | scope variables |

### 計算ロジック

特になし。

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | - | スコープ固有のエラーは少ない | - |

### リトライ仕様

リトライは行わない。

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

スコープ管理はトランザクション管理を行わない。

## パフォーマンス要件

特になし。

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

特になし。

## 備考

- ScopeDataはnu-engineで定義
- 変数には値も含まれる（取得可能な場合）

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | command.rs | `crates/nu-cmd-lang/src/core_commands/scope/command.rs` | scopeコマンド（ヘルプ） |
| 1-2 | variables.rs | `crates/nu-cmd-lang/src/core_commands/scope/variables.rs` | scope variables |
| 1-3 | commands.rs | `crates/nu-cmd-lang/src/core_commands/scope/commands.rs` | scope commands |
| 1-4 | aliases.rs | `crates/nu-cmd-lang/src/core_commands/scope/aliases.rs` | scope aliases |
| 1-5 | modules.rs | `crates/nu-cmd-lang/src/core_commands/scope/modules.rs` | scope modules |
| 1-6 | externs.rs | `crates/nu-cmd-lang/src/core_commands/scope/externs.rs` | scope externs |

**主要処理フロー（command.rs）**:
- **22-30行目**: run関数（get_full_helpでヘルプ表示）

#### Step 2: スコープデータ収集を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | scope.rs | `crates/nu-engine/src/scope.rs` | ScopeData構造体と収集ロジック |

**主要処理フロー（scope.rs）**:
- **9-16行目**: ScopeData構造体の定義
- **18-28行目**: newコンストラクタ
- **30-34行目**: populate_vars（変数収集）
- **36-42行目**: populate_decls（コマンド収集）
- **44-48行目**: populate_modules（モジュール収集）
- **50-91行目**: collect_vars（変数情報をValue化）
- **93-160行目**: collect_commands（コマンド情報をValue化）

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

```
scope variables
    │
    └─ run関数
           └─ ScopeData::new
                  └─ populate_vars
                         └─ オーバーレイスキャン
           └─ collect_vars
                  └─ 変数情報をrecordに変換
           └─ Value::list返却
```

### データフロー図

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

EngineState ───────▶ ScopeData ────────────▶ オーバーレイスキャン
Stack                    │
                         ▼
               populate_* で情報収集
                         │
                         ▼
               collect_* でValue化 ────────▶ list<record>
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| command.rs | `crates/nu-cmd-lang/src/core_commands/scope/command.rs` | ソース | scopeコマンド |
| variables.rs | `crates/nu-cmd-lang/src/core_commands/scope/variables.rs` | ソース | scope variables |
| commands.rs | `crates/nu-cmd-lang/src/core_commands/scope/commands.rs` | ソース | scope commands |
| aliases.rs | `crates/nu-cmd-lang/src/core_commands/scope/aliases.rs` | ソース | scope aliases |
| modules.rs | `crates/nu-cmd-lang/src/core_commands/scope/modules.rs` | ソース | scope modules |
| externs.rs | `crates/nu-cmd-lang/src/core_commands/scope/externs.rs` | ソース | scope externs |
| engine_stats.rs | `crates/nu-cmd-lang/src/core_commands/scope/engine_stats.rs` | ソース | scope engine-stats |
| scope.rs | `crates/nu-engine/src/scope.rs` | ソース | ScopeData構造体 |
