# 機能設計書 72-ヘルプ表示

## 概要

本ドキュメントは、Nushellのヘルプ表示機能の設計仕様を定義する。help コマンド群は、コマンド、エイリアス、モジュール、演算子などの使用方法や説明を表示する機能を提供する。

### 本機能の処理概要

helpコマンド群は、Nushellの各種機能（コマンド、エイリアス、モジュール、演算子、extern、パイプ・リダイレクト、エスケープシーケンス）に関するドキュメンテーションを表示する機能である。ユーザーがNushellの機能を学習・理解するための統合的なヘルプシステムを提供する。

**業務上の目的・背景**：シェル環境では多数のコマンドと複雑な構文が存在するため、ユーザーが効率的に学習・参照できるヘルプシステムが不可欠である。本機能により、コマンドラインから即座にドキュメントにアクセスでき、生産性向上と学習曲線の緩和を実現する。

**機能の利用シーン**：
- コマンドの使用方法やパラメータを確認したい場合
- 特定のキーワードを含むコマンドを検索したい場合
- モジュールがエクスポートしているコマンドやエイリアスを確認したい場合
- 演算子の優先順位や動作を確認したい場合
- カスタムコマンドの使い方を確認したい場合

**主要な処理内容**：
1. `help`：総合ヘルプ表示、コマンド/エイリアス/モジュールの自動検索
2. `help commands`：コマンド一覧表示、特定コマンドの詳細表示
3. `help aliases`：エイリアス一覧表示、特定エイリアスの詳細表示
4. `help modules`：モジュール一覧表示、特定モジュールの詳細表示
5. `help operators`：演算子一覧表示
6. `help externs`：extern宣言一覧表示
7. `help pipe-and-redirect`：パイプとリダイレクトの説明表示
8. `help escapes`：エスケープシーケンスの説明表示

**関連システム・外部連携**：
- nu-engineクレート：`get_full_help`関数によるヘルプテキスト生成
- ScopeData：現在のスコープからコマンド、エイリアス、モジュール情報を収集

**権限による制御**：特になし。全ユーザーが使用可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | メインREPL | 主画面 | helpコマンドの実行とヘルプテキストの表示 |
| 3 | ヘルプ補完メニュー | 参照画面 | ヘルプ情報の検索結果のSuggestion形式での表示 |
| 10 | LSP言語サーバ | API連携 | ホバー時のドキュメント表示・シグネチャヘルプ |

## 機能種別

ドキュメンテーション表示・検索機能

## 入力仕様

### 入力パラメータ（helpコマンド共通）

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| rest | String（複数可） | No | ヘルプを表示する対象の名前 | - |
| --find (-f) | String | No | コマンド名・説明文を検索するキーワード | - |

### サブコマンド固有パラメータ

#### help operators
パラメータなし（演算子一覧を表示）

#### help escapes
パラメータなし（エスケープシーケンス一覧を表示）

#### help pipe-and-redirect
パラメータなし（パイプとリダイレクトの説明を表示）

### 入力データソース

- EngineState：登録されているコマンド、エイリアス、モジュールの情報
- ScopeData：現在のスコープで利用可能な定義

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 一覧表示 | Table | コマンド/エイリアス/モジュール/演算子の一覧テーブル |
| 詳細表示 | String | 特定項目の詳細なヘルプテキスト |
| ウェルカムメッセージ | String | helpコマンド単独実行時の案内メッセージ |

### 出力先

標準出力（パイプライン出力）

## 処理フロー

### 処理シーケンス

```
1. コマンド引数の解析
   └─ --findフラグの確認
   └─ rest引数の確認

2. 処理分岐
   ├─ --findが指定: 検索モード
   │     └─ 対象一覧を構築
   │     └─ find_internal で検索実行
   │
   ├─ rest引数なし: 一覧モード
   │     └─ ScopeDataから情報収集
   │     └─ テーブル形式で出力
   │
   └─ rest引数あり: 詳細モード
         └─ 指定された名前で検索
         └─ get_full_help で詳細テキスト生成
         └─ 文字列形式で出力

3. 結果の返却
   └─ PipelineDataとして返却
```

### フローチャート

```mermaid
flowchart TD
    A[help コマンド開始] --> B{サブコマンド?}

    B -->|help| C{引数あり?}
    B -->|help commands| D[コマンドヘルプ処理]
    B -->|help aliases| E[エイリアスヘルプ処理]
    B -->|help modules| F[モジュールヘルプ処理]
    B -->|help operators| G[演算子一覧表示]
    B -->|help externs| H[extern一覧表示]
    B -->|help escapes| I[エスケープ一覧表示]

    C -->|No| J[ウェルカムメッセージ表示]
    C -->|Yes| K{--find指定?}

    K -->|Yes| L[コマンド一覧を検索]
    K -->|No| M[エイリアス検索]

    M --> N{見つかった?}
    N -->|Yes| O[エイリアス詳細表示]
    N -->|No| P[コマンド検索]

    P --> Q{見つかった?}
    Q -->|Yes| R[コマンド詳細表示]
    Q -->|No| S[モジュール検索]

    S --> T{見つかった?}
    T -->|Yes| U[モジュール詳細表示]
    T -->|No| V[NotFoundエラー]

    D --> W{--find指定?}
    W -->|Yes| X[検索実行]
    W -->|No| Y{rest指定?}
    Y -->|Yes| Z[詳細表示]
    Y -->|No| AA[一覧表示]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-72-1 | 自動検索順序 | helpコマンドはエイリアス→コマンド→モジュールの順で検索 | rest引数ありかつ--find未指定 |
| BR-72-2 | 検索対象フィールド | --findは名前と説明フィールドを検索対象とする | --findフラグ指定時 |
| BR-72-3 | スコープ認識 | モジュールのコマンド/エイリアスは現在のスコープで利用可能かどうかで色分け | help modules [name]実行時 |
| BR-72-4 | ANSI色設定 | config.use_ansi_coloringがfalseの場合は色付けを無効化 | 全てのヘルプ出力 |

### 計算ロジック

特になし

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

該当なし（本機能はデータベースを使用しない）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | AliasNotFound | 指定されたエイリアスが存在しない | help aliasesからエラー送出 |
| - | CommandNotFound | 指定されたコマンドが存在しない | help commandsからエラー送出 |
| - | ModuleNotFoundAtRuntime | 指定されたモジュールが存在しない | help modulesからエラー送出 |
| - | NotFound | helpコマンドで全検索しても見つからない | スパン情報を含むNotFoundエラー |

### リトライ仕様

リトライは行わない。

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

該当なし

## パフォーマンス要件

- コマンド一覧の構築はget_decls_sortedを使用し、ソート済みで取得
- 検索処理はfind_internal関数で効率的に実行

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

- 出力にANSIエスケープコードを含むため、config.use_ansi_coloringで制御可能
- ユーザー定義コマンドのヘルプも表示されるため、信頼できないスクリプトには注意

## 備考

- `--help`フラグは内部的にhelpコマンドを呼び出す
- 標準ライブラリにも代替のhelpコマンドが存在（`use std/help`）

---

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

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

### 推奨読解順序

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

ヘルプシステムで使用されるデータ構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | scope.rs | `crates/nu-engine/src/scope.rs` | ScopeDataの構造、collect_*メソッドの役割 |
| 1-2 | documentation.rs | `crates/nu-engine/src/documentation.rs` | get_full_help関数の実装 |

**読解のコツ**: ScopeDataはEngineStateとStackから情報を収集し、populate_*メソッドで初期化、collect_*メソッドでValue型に変換する。

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

メインのhelpコマンドの実装を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | help_.rs | `crates/nu-command/src/help/help_.rs` | Helpコマンドの引数定義とフォールバック検索ロジック |

**主要処理フロー**:
1. **46-48行目**: 引数（find, rest）の取得
2. **50-75行目**: 引数なし時のウェルカムメッセージ表示
3. **76-77行目**: --find指定時はhelp_commandsにフォールバック
4. **79-103行目**: エイリアス→コマンド→モジュールの順で検索

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

各サブコマンドの実装を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | help_commands.rs | `crates/nu-command/src/help/help_commands.rs` | コマンド一覧/詳細の構築 |
| 3-2 | help_aliases.rs | `crates/nu-command/src/help/help_aliases.rs` | エイリアス一覧/詳細の構築 |
| 3-3 | help_modules.rs | `crates/nu-command/src/help/help_modules.rs` | モジュール一覧/詳細の構築 |
| 3-4 | help_operators.rs | `crates/nu-command/src/help/help_operators.rs` | 演算子一覧の構築 |

**主要処理フロー** (help_commands.rs):
- **46-65行目**: --find指定時の検索処理
- **67-107行目**: 詳細表示時のフルヘルプ生成
- **149-268行目**: build_help_commands - コマンド一覧テーブルの構築

**主要処理フロー** (help_modules.rs):
- **117-120行目**: ANSIカラーコードの定義
- **137-173行目**: エクスポートされたコマンドの色分け表示
- **175-211行目**: エクスポートされたエイリアスの色分け表示

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

```
Help::run (help_.rs)
    │
    ├─ 引数なし: ウェルカムメッセージを返却
    │
    ├─ --find指定: help_commands() にフォールバック
    │
    └─ rest指定:
           │
           ├─ help_aliases (help_aliases.rs)
           │      └─ build_help_aliases / get_full_help
           │
           ├─ help_commands (help_commands.rs)
           │      └─ build_help_commands / get_full_help
           │
           └─ help_modules (help_modules.rs)
                  └─ build_help_modules / 詳細テキスト生成

HelpCommands::run
    └─ help_commands()
           ├─ --find: find_internal()
           ├─ 一覧: build_help_commands()
           └─ 詳細: get_full_help()

HelpOperators::run
    └─ Operator::iter() で全演算子を列挙
           └─ レコードとして出力
```

### データフロー図

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

引数なし ──────────▶ ウェルカムメッセージ生成 ──────────▶ String

--find "keyword" ──▶ build_help_* ──▶ find_internal ──▶ Table
                          │                │
                     全項目収集        キーワード検索

rest "name" ───────▶ find_decl / find_module ──────────▶ String
                          │
                     get_full_help
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| mod.rs | `crates/nu-command/src/help/mod.rs` | ソース | モジュール定義、公開関数 |
| help_.rs | `crates/nu-command/src/help/help_.rs` | ソース | Helpコマンド（統合ヘルプ） |
| help_commands.rs | `crates/nu-command/src/help/help_commands.rs` | ソース | HelpCommandsコマンド |
| help_aliases.rs | `crates/nu-command/src/help/help_aliases.rs` | ソース | HelpAliasesコマンド |
| help_modules.rs | `crates/nu-command/src/help/help_modules.rs` | ソース | HelpModulesコマンド |
| help_operators.rs | `crates/nu-command/src/help/help_operators.rs` | ソース | HelpOperatorsコマンド |
| help_externs.rs | `crates/nu-command/src/help/help_externs.rs` | ソース | HelpExternsコマンド |
| help_escapes.rs | `crates/nu-command/src/help/help_escapes.rs` | ソース | HelpEscapesコマンド |
| help_pipe_and_redirect.rs | `crates/nu-command/src/help/help_pipe_and_redirect.rs` | ソース | HelpPipeAndRedirectコマンド |
| scope.rs | `crates/nu-engine/src/scope.rs` | ソース | ScopeData構造体 |
| documentation.rs | `crates/nu-engine/src/documentation.rs` | ソース | get_full_help関数 |
