# 機能設計書 61-乱数生成

## 概要

本ドキュメントは、Nushellにおける乱数生成機能（random コマンド群）の設計を記述する。整数、浮動小数点数、ブール値、文字列、バイナリデータなど、様々な形式の乱数を生成するためのサブコマンド群を提供する。

### 本機能の処理概要

乱数生成機能は、シェルスクリプトやデータ処理において必要となる様々な種類のランダムな値を生成する機能を提供する。Rustの`rand`クレートを活用し、暗号学的に安全ではないが高速な疑似乱数生成を行う。

**業務上の目的・背景**：スクリプト開発やテスト、データ生成において、ランダムな値が必要となる場面は多い。例えば、テストデータの自動生成、ランダムなファイル名の作成、モンテカルロシミュレーション、ゲームロジックの実装などが挙げられる。この機能により、外部ツールに頼ることなくNushell内で完結した乱数生成が可能となる。

**機能の利用シーン**：
- テストデータの自動生成時に様々な値を挿入
- 一時ファイルや一意な識別子のためのランダム文字列生成
- データのシャッフルやサンプリング処理
- シミュレーションや確率的アルゴリズムの実装

**主要な処理内容**：
1. `random int` - 指定範囲内の整数を生成
2. `random float` - 指定範囲内の浮動小数点数を生成
3. `random bool` - 真偽値を生成（バイアス設定可能）
4. `random chars` - 英数字のランダム文字列を生成
5. `random binary` - ランダムなバイトデータを生成
6. `random dice` - サイコロの出目をシミュレート

**関連システム・外部連携**：外部システムとの直接連携はない。Rustの`rand`クレートを内部的に使用する。

**権限による制御**：特別な権限制御はなく、すべてのユーザーが実行可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | メインREPL | 結果表示画面 | コマンド実行結果としての乱数値の表示 |

## 機能種別

計算処理 / データ生成

## 入力仕様

### 入力パラメータ

#### random int

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| range | Range | No | 生成する整数の範囲（inclusive） | 開始値 <= 終了値 |

#### random float

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| range | Range | No | 生成する浮動小数点数の範囲 | 開始値 <= 終了値 |

#### random bool

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| --bias, -b | Number | No | trueが出る確率（0.0〜1.0） | 0.0 <= 値 <= 1.0 |

#### random chars

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| --length, -l | Int/Filesize | No | 生成する文字数（デフォルト25） | 非負の整数 |

#### random binary

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| length | Int/Filesize | Yes | 生成するバイト数 | 非負の整数 |

#### random dice

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| --dice, -d | Int | No | サイコロの個数（デフォルト1） | 1以上の整数 |
| --sides, -s | Int | No | サイコロの面数（デフォルト6） | 1以上の整数 |

### 入力データソース

コマンドライン引数およびフラグから入力を受け取る。パイプライン入力は使用しない（Type::Nothing）。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| random int | Int | 指定範囲内のランダム整数 |
| random float | Float | 指定範囲内のランダム浮動小数点数 |
| random bool | Bool | true または false |
| random chars | String | 英数字のランダム文字列 |
| random binary | Binary | ランダムバイトデータ（ByteStream） |
| random dice | List[Int] | サイコロの出目のリスト |

### 出力先

パイプラインへの出力（PipelineData）。他のコマンドとパイプで連結可能。

## 処理フロー

### 処理シーケンス

```
1. コマンドの引数解析
   └─ 範囲や長さなどのパラメータを取得

2. バリデーション
   └─ 範囲の妥当性チェック（開始 <= 終了）
   └─ バイアス値の範囲チェック（0.0〜1.0）

3. 乱数生成
   └─ rand クレートの関数を呼び出し
   └─ random_range() または random_bool() を使用

4. 結果のラッピング
   └─ Value型（Int/Float/Bool/String/Binary）に変換
   └─ PipelineDataとして返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{引数を解析}
    B --> C{範囲指定あり?}
    C -->|Yes| D[範囲をパース]
    C -->|No| E[デフォルト範囲を使用]
    D --> F{範囲が有効?}
    F -->|No| G[エラーを返却]
    F -->|Yes| H[乱数を生成]
    E --> H
    H --> I[Value型に変換]
    I --> J[PipelineDataとして返却]
    J --> K[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 範囲の包含性 | random int の範囲は両端を含む（inclusive） | 範囲指定時 |
| BR-002 | デフォルト範囲 | random int は範囲省略時 0..=i64::MAX | 範囲省略時 |
| BR-003 | float デフォルト | random float は範囲省略時 0.0..1.0 | 範囲省略時 |
| BR-004 | bool バイアス | バイアス省略時は50%の確率 | --bias 省略時 |
| BR-005 | chars 文字種 | a-z, A-Z, 0-9 のみ使用 | 常時 |

### 計算ロジック

- **random int**: `rand::random_range(start..=end)` を使用
- **random float**: `rand::random_range(start..end)` を使用
- **random bool**: `rand::random_bool(probability)` を使用。probability は 0.0〜1.0 の値で、trueが返る確率を表す

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| InvalidRange | 範囲エラー | 開始値 > 終了値 の場合 | 正しい範囲を指定 |
| InvalidProbability | バリデーションエラー | バイアス値が 0.0〜1.0 の範囲外 | 有効な確率値を指定 |
| UnsupportedInput | 型エラー | float範囲をrandom intに指定 | 整数範囲を使用 |
| InvalidValue | 値エラー | 負の長さを指定 | 非負の値を指定 |

### リトライ仕様

リトライは不要。乱数生成は常に成功するため、エラーは入力値の問題に限定される。

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

本機能はトランザクション管理を行わない。

## パフォーマンス要件

- 単一の乱数生成は即座に完了する（マイクロ秒オーダー）
- random binary および random chars の大量データ生成はストリーミング処理で対応
- ByteStreamによるチャンク出力（8192バイト単位）で大容量データも効率的に処理

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

- 本機能は暗号学的に安全な乱数生成器（CSPRNG）を使用していない
- パスワード生成やセキュリティトークン生成には使用しないこと
- テストデータやシミュレーション用途に限定して使用することを推奨

## 備考

- `random dice` コマンドは v0.107.0 で非推奨となり、v0.108.0 で削除予定
- 代替として `std/random` モジュールの `random dice` を使用

---

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

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

### 推奨読解順序

#### Step 1: モジュール構成を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | mod.rs | `crates/nu-command/src/random/mod.rs` | 公開されるコマンド一覧を確認 |

**読解のコツ**: `pub use` 文で外部に公開されるコマンド構造体を把握する。RandomInt、RandomFloat、RandomBool、RandomChars、RandomBinary、RandomDice、RandomUuid が登録されている。

#### Step 2: 親コマンドを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | random_.rs | `crates/nu-command/src/random/random_.rs` | random コマンド本体（ヘルプ表示のみ） |

**主要処理フロー**:
- **6-38行目**: Command トレイト実装。単独実行時はヘルプを表示
- **36行目**: `get_full_help()` でサブコマンド一覧を含むヘルプを生成

#### Step 3: 各サブコマンドを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | int.rs | `crates/nu-command/src/random/int.rs` | 整数乱数生成のロジック |
| 3-2 | float.rs | `crates/nu-command/src/random/float.rs` | 浮動小数点乱数生成のロジック |
| 3-3 | bool.rs | `crates/nu-command/src/random/bool.rs` | ブール値乱数生成のロジック |
| 3-4 | chars.rs | `crates/nu-command/src/random/chars.rs` | 文字列乱数生成のロジック |
| 3-5 | binary.rs | `crates/nu-command/src/random/binary.rs` | バイナリ乱数生成のロジック |
| 3-6 | dice.rs | `crates/nu-command/src/random/dice.rs` | サイコロ乱数生成のロジック |

**主要処理フロー（int.rs）**:
- **14-24行目**: シグネチャ定義。オプショナルな範囲パラメータ
- **70-115行目**: `integer()` 関数で実際の乱数生成
- **82-92行目**: 範囲の step が負の場合のエラーチェック
- **94-98行目**: Bound の種類に応じた `random_range()` 呼び出し

#### Step 4: ストリーミング処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | byte_stream.rs | `crates/nu-command/src/random/byte_stream.rs` | 大容量データのストリーミング生成 |

**主要処理フロー**:
- **9-12行目**: `RandomDistribution` 列挙型（Binary または Alphanumeric）
- **14-50行目**: `random_byte_stream()` でチャンク単位のストリーム生成
- **25行目**: `OUTPUT_CHUNK_SIZE = 8192` バイト単位での出力
- **36-39行目**: 分布タイプに応じた iterator の選択

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

```
random (random_.rs)
    │
    ├─ random int (int.rs)
    │      └─ integer() → rand::random_range()
    │
    ├─ random float (float.rs)
    │      └─ float() → rand::random_range()
    │
    ├─ random bool (bool.rs)
    │      └─ bool() → rand::random_bool()
    │
    ├─ random chars (chars.rs)
    │      └─ chars() → random_byte_stream(Alphanumeric)
    │             └─ byte_stream.rs
    │
    ├─ random binary (binary.rs)
    │      └─ run() → random_byte_stream(Binary)
    │             └─ byte_stream.rs
    │
    └─ random dice (dice.rs)
           └─ dice() → rand::random_range()
```

### データフロー図

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

コマンドライン引数 ───▶ 引数解析・バリデーション ───▶ エラー or 次処理へ
         │
         ▼
   範囲/長さ/バイアス ───▶ rand クレート関数呼び出し ───▶ 乱数値
         │
         ▼
    乱数値 ───▶ Value型ラッピング ───▶ PipelineData ───▶ パイプライン出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| mod.rs | `crates/nu-command/src/random/mod.rs` | ソース | モジュール定義、公開エクスポート |
| random_.rs | `crates/nu-command/src/random/random_.rs` | ソース | 親コマンド（ヘルプ表示） |
| int.rs | `crates/nu-command/src/random/int.rs` | ソース | random int 実装 |
| float.rs | `crates/nu-command/src/random/float.rs` | ソース | random float 実装 |
| bool.rs | `crates/nu-command/src/random/bool.rs` | ソース | random bool 実装 |
| chars.rs | `crates/nu-command/src/random/chars.rs` | ソース | random chars 実装 |
| binary.rs | `crates/nu-command/src/random/binary.rs` | ソース | random binary 実装 |
| dice.rs | `crates/nu-command/src/random/dice.rs` | ソース | random dice 実装 |
| byte_stream.rs | `crates/nu-command/src/random/byte_stream.rs` | ソース | ストリーミング乱数生成ユーティリティ |
