# 画面設計書 3-ヘルプ補完メニュー

## 概要

本ドキュメントは、Nushell REPLにおけるヘルプ補完メニュー画面の設計仕様を定義する。ヘルプ補完メニューは、コマンドのヘルプ情報（説明、フラグ、パラメータ、使用例）を補完候補として表示する特殊なメニューである。

### 本画面の処理概要

ヘルプ補完メニューは、F1キー等の特定キー押下時に表示されるヘルプ情報を含む補完メニューである。通常の補完メニューとは異なり、コマンド名だけでなく、そのコマンドの詳細な説明、使用方法、パラメータ情報を含む補完候補を生成する。

**業務上の目的・背景**：
シェル操作において、コマンドの使い方を確認するためにmanページやhelpコマンドを実行するのは手間がかかる。ヘルプ補完メニューは、入力中にその場でコマンドのヘルプ情報を確認でき、学習と操作を同時に行えるようにする。特にNushellの豊富なコマンドセットを効率的に習得するために有用である。

**画面へのアクセス方法**：
- メインREPLでF1キー等を押下（設定可能）
- ヘルプメニュー用のキーバインドをトリガー

**主要な操作・処理内容**：
1. 入力テキストからコマンド名を抽出
2. コマンド名の説明、検索ワード、extra_descriptionで検索
3. マッチしたコマンドのヘルプ情報を生成
4. Levenshtein距離でソート（入力に近い順）
5. メニュー表示とナビゲーション

**画面遷移**：
- メインREPL（画面No.1） → F1等押下 → ヘルプ補完メニュー
- ヘルプ補完メニュー → 選択/Esc → メインREPL（画面No.1）

**権限による表示制御**：
- 特になし。全ユーザーが同一の機能を利用可能

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 72 | ヘルプ表示 | 主機能 | コマンドのヘルプ情報（説明・フラグ・パラメータ）の表示 |
| 85 | 補完機能 | 補助機能 | ヘルプ検索結果のSuggestion形式での補完候補生成 |

## 画面種別

ポップアップメニュー（ヘルプ付き補完候補リスト）

## URL/ルーティング

N/A（CLI/TUIアプリケーションのためURL概念なし）

## 入出力項目

| 項目名 | 型 | 入力/出力 | 説明 |
|--------|-----|----------|------|
| 検索クエリ | String | 入力 | ユーザーが入力したコマンド名の一部 |
| カーソル位置 | usize | 入力 | 入力バッファ内のカーソル位置 |
| ヘルプ付き候補 | Vec<Suggestion> | 出力 | ヘルプ情報を含む補完候補リスト |
| 選択された候補 | String | 出力 | ユーザーが選択したコマンド名 |

## 表示項目

| 項目名 | 説明 | 表示形式 |
|--------|------|----------|
| コマンド名 | 候補のコマンド名 | 文字列 |
| 説明 | コマンドの説明文 | 複数行テキスト |
| 使用法 | コマンドの呼び出し形式 | `Usage: > command ...` |
| フラグ一覧 | コマンドのフラグと説明 | リスト形式 |
| パラメータ一覧 | 必須/オプションパラメータ | リスト形式 |
| 使用例 | コマンドの使用例 | extra配列として格納 |

## イベント仕様

### 1-F1押下（ヘルプ補完トリガー）

1. 現在の入力テキストを取得
2. 大文字小文字を無視して検索文字列を正規化
3. 全てのコマンド宣言を走査
4. コマンド名、description、search_terms、extra_descriptionで検索
5. マッチしたコマンドをLevenshtein距離でソート
6. 各コマンドのヘルプ情報を生成
   - description + extra_description
   - Usage（call_signature）
   - Flags（get_flags_section）
   - Parameters（required/optional/rest）
   - Examples（extra配列）
7. Suggestionリストとして返却

### 2-候補選択

1. 選択されたコマンド名を入力バッファに挿入
2. メニューを閉じる

## データベース更新仕様

N/A（データベース操作なし）

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 発生条件 |
|-------------|------|---------------|----------|
| NO_MATCHES | 情報 | （メニュー非表示） | 候補が見つからない場合 |

## 例外処理

| 例外状態 | 対応処理 |
|---------|---------|
| コマンドなし | 空のリストを返却、メニュー非表示 |

## 備考

- 大文字小文字を無視した検索（to_folded_case）
- Levenshtein距離によるソートで入力に近いコマンドを優先
- HelpStyleでフォーマットをカスタマイズ可能
- 使用例はextra配列として補完候補に含まれる

---

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

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

### 推奨読解順序

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

ヘルプ補完で扱う主要なデータ構造を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | help_completions.rs | `crates/nu-cli/src/menus/help_completions.rs` | NuHelpCompleter構造体（7-10行） |

**読解のコツ**: NuHelpCompleterはreedlineのCompleterトレイトを実装し、Suggestionを返す

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

ヘルプ補完処理の起点を特定する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | help_completions.rs | `crates/nu-cli/src/menus/help_completions.rs` | complete関数（131-134行） |

**主要処理フロー**:
1. **132-133行**: `complete`関数がreedlineから呼び出される
2. **133行**: `completion_helper`を呼び出して実際の処理を実行

#### Step 3: 検索とフィルタリングを理解する

コマンド検索の処理を追う。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | help_completions.rs | `crates/nu-cli/src/menus/help_completions.rs` | completion_helper関数（20-128行） |

**主要処理フロー**:
- **21行**: 検索文字列を小文字に正規化（to_folded_case）
- **26-44行**: 全てのコマンド宣言を走査し、フィルタリング
  - name.contains（コマンド名で検索）
  - description.contains（説明で検索）
  - search_terms.contains（検索ワードで検索）
  - extra_description.contains（追加説明で検索）
- **46行**: Levenshtein距離でソート

#### Step 4: ヘルプ情報生成を理解する

ヘルプ情報のフォーマットを追う。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | help_completions.rs | `crates/nu-cli/src/menus/help_completions.rs` | Suggestionの生成（48-127行） |

**主要処理フロー**:
- **51-56行**: description追加
- **59-63行**: extra_description追加
- **65-66行**: Usage追加（call_signature）
- **68-75行**: Flags追加（get_flags_section）
- **77-108行**: Parameters追加（required/optional/rest）
- **110-114行**: Examples追加（extra配列）

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

```
F1押下 (reedline)
    |
    +-- NuHelpCompleter::complete()      [help_completions.rs:132]
            |
            +-- completion_helper()      [help_completions.rs:20]
                    |
                    +-- engine_state.get_decls_sorted()
                    |
                    +-- decl.name() / description() / search_terms()
                    |
                    +-- levenshtein_distance()  [ソート]
                    |
                    +-- decl.signature()
                    |       +-- call_signature()
                    |       +-- get_flags_section()
                    |
                    +-- decl.examples()
                    |
                    +-- Suggestion { value, description, extra, span }
```

### データフロー図

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

検索クエリ ───────────▶ NuHelpCompleter
     │                    │
     │                    ▼
     │              to_folded_case()    正規化
     │                    │
     │                    ▼
     │              get_decls_sorted() ──────────▶ 全コマンド一覧
     │                    │
     │                    ▼
     │              filter_map() ────────────────▶ マッチしたコマンド
     │                    │
     │                    ▼
     │              sort_by_cached_key() ────────▶ ソート済み候補
     │                    (levenshtein_distance)
     │                    │
     │                    ▼
     └─────────────────▶ Suggestion生成 ─────────▶ ヘルプ付き候補リスト
                          │
                          +-- description
                          +-- Usage
                          +-- Flags
                          +-- Parameters
                          +-- Examples
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| help_completions.rs | `crates/nu-cli/src/menus/help_completions.rs` | ソース | ヘルプ補完のコア実装 |
| mod.rs | `crates/nu-cli/src/menus/mod.rs` | ソース | menusモジュール定義 |
| documentation.rs | `crates/nu-engine/src/documentation.rs` | ソース | get_flags_section関数 |
| signature.rs | `crates/nu-protocol/src/signature.rs` | ソース | Signature構造体定義 |
| decl.rs | `crates/nu-protocol/src/engine/decl.rs` | ソース | Declaration トレイト |
