# 機能設計書 6-モジュールシステム

## 概要

本ドキュメントは、Nushellにおけるモジュールシステム（module、use、export）について定義する。モジュールシステムはコードの構造化と再利用を支援し、名前空間の分離を実現する。

### 本機能の処理概要

**業務上の目的・背景**：大規模なスクリプト開発では、コードの整理と名前空間の管理が重要になる。モジュールシステムにより、関連する機能をグループ化し、必要な部分のみをインポートすることで、コードの保守性と再利用性を高める。

**機能の利用シーン**：
- 関連する関数・定数のグループ化
- 外部スクリプトファイルのインポート
- 標準ライブラリの利用
- 名前空間の分離による名前衝突の回避

**主要な処理内容**：
1. `module name { ... }` - インラインモジュールの定義
2. `module path` - ファイルからのモジュール読み込み
3. `use module` - モジュール全体のインポート（修飾付き）
4. `use module *` - 全エクスポートのインポート
5. `use module [items]` - 選択的インポート
6. `export` - コマンド・定数・エイリアスのエクスポート
7. `export-env` - 環境変数のエクスポート

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

**権限による制御**：ファイルシステムへのアクセスが必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | メインREPL | 主画面 | モジュール定義とuseの実行 |

## 機能種別

モジュール管理 / 名前空間管理

## 入力仕様

### 入力パラメータ

#### module コマンド
| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| module | String | Yes | モジュール名またはパス | 有効な識別子/パス |
| block | Block | No | モジュール本体（インライン時） | 有効なブロック |

#### use コマンド
| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| module | String/Nothing | Yes | モジュール名（nullでno-op） | 有効な識別子 |
| members | Any (rest) | No | インポートするメンバー | - |

### 入力データソース

- ユーザーからのコマンドライン入力
- スクリプトファイル
- モジュールファイル（.nuファイル、mod.nuディレクトリ）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| PipelineData | PipelineData | Empty |

### 出力先

- EngineState（モジュール、宣言、定数の登録）
- 現在のスコープ（環境変数のマージ）

## 処理フロー

### 処理シーケンス

```
1. module定義（パース時）
   └─ モジュール名の検証
   └─ ブロック/ファイルの解析
   └─ ModuleIdの割り当て
   └─ エクスポート一覧の収集
2. use実行
   └─ モジュールの解決
   └─ インポートパターンの解析
   └─ 定数のスタックへの追加
   └─ export-envブロックの評価
   └─ 環境変数のマージ
```

### フローチャート

```mermaid
flowchart TD
    A[module / use] --> B{コマンド}
    B -->|module| C[モジュール定義]
    C --> D{ブロック指定?}
    D -->|Yes| E[インラインモジュール解析]
    D -->|No| F[ファイル読み込み]
    E --> G[ModuleId登録]
    F --> G
    B -->|use| H[モジュール解決]
    H --> I[インポートパターン解析]
    I --> J[定数をスタックに追加]
    J --> K{export-env あり?}
    K -->|Yes| L[ブロック評価]
    L --> M[環境マージ]
    K -->|No| N[完了]
    M --> N
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 修飾付きインポート | `use mod` は `mod cmd` の形式で呼び出し | useのみ |
| BR-002 | ワイルドカード | `use mod *` で全エクスポートをインポート | * 指定時 |
| BR-003 | 選択的インポート | `use mod [a, b]` で特定メンバーのみ | リスト指定時 |
| BR-004 | export-env | モジュールの環境設定はuse時に実行 | export-env定義時 |
| BR-005 | ディレクトリモジュール | ディレクトリ名/mod.nu がエントリーポイント | ディレクトリパス時 |

### 計算ロジック

特になし。

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ModuleNotFound | 解決エラー | モジュールが見つからない | パスを確認 |
| GenericError | 汎用エラー | インポートパターンが不正 | 構文を確認 |
| NushellFailedSpanned | 内部エラー | 定数が未定義 | モジュール定義を確認 |

### リトライ仕様

リトライは行わない。

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

モジュール定義はトランザクション管理を行わない。

## パフォーマンス要件

特になし。

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

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

## 備考

- moduleとuseはパーサーキーワードとして実装
- std（標準ライブラリ）は`use std`でインポート可能

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | module.rs | `crates/nu-cmd-lang/src/core_commands/module.rs` | moduleコマンドの実装 |
| 1-2 | use_.rs | `crates/nu-cmd-lang/src/core_commands/use_.rs` | useコマンドの実装 |
| 1-3 | export.rs | `crates/nu-cmd-lang/src/core_commands/export.rs` | exportコマンド |
| 1-4 | export_use.rs | `crates/nu-cmd-lang/src/core_commands/export_use.rs` | export use |

**主要処理フロー（use_.rs）**:
- **54-167行目**: run関数
- **61-63行目**: noop チェック（nullの場合は何もしない）
- **81-95行目**: 定数のスタックへの追加
- **100-152行目**: export-envブロックの評価と環境マージ

#### Step 2: モジュール構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | module.rs | `crates/nu-protocol/src/module.rs` | Module構造体の定義 |

#### Step 3: パース処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | parse_keywords.rs | `crates/nu-parser/src/parse_keywords.rs` | parse_module, parse_use 関数 |

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

```
module spam { export def foo [] { ... } }
    │
    └─ パース時
           └─ parse_module
                  ├─ モジュールブロック解析
                  ├─ エクスポート収集
                  └─ ModuleId登録

use spam foo
    │
    └─ パース時: parse_use
    │      └─ import_pattern 生成
    │
    └─ 実行時: Use.run
           ├─ 定数追加
           ├─ export-env評価
           └─ redirect_env
```

### データフロー図

```
[定義]                  [登録]                       [使用]

module spam { ... }
    │
    ▼
パース ───────────▶ Module構造体 ───────────▶ EngineState
                                                │
                                                ▼
use spam ────────▶ import_pattern解析 ────▶ スコープに追加
                       │
                       ▼
               export-env評価 ────────────▶ 環境マージ
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| module.rs | `crates/nu-cmd-lang/src/core_commands/module.rs` | ソース | moduleコマンド |
| use_.rs | `crates/nu-cmd-lang/src/core_commands/use_.rs` | ソース | useコマンド |
| export.rs | `crates/nu-cmd-lang/src/core_commands/export.rs` | ソース | exportコマンド |
| export_use.rs | `crates/nu-cmd-lang/src/core_commands/export_use.rs` | ソース | export use |
| export_def.rs | `crates/nu-cmd-lang/src/core_commands/export_def.rs` | ソース | export def |
| export_const.rs | `crates/nu-cmd-lang/src/core_commands/export_const.rs` | ソース | export const |
| export_alias.rs | `crates/nu-cmd-lang/src/core_commands/export_alias.rs` | ソース | export alias |
| module.rs | `crates/nu-protocol/src/module.rs` | ソース | Module構造体 |
| parse_keywords.rs | `crates/nu-parser/src/parse_keywords.rs` | ソース | モジュールパース |
