# 画面設計書 2-補完メニュー

## 概要

本ドキュメントは、Nushell REPLにおける補完メニュー画面の設計仕様を定義する。補完メニューは、ユーザーがコマンドやパス、変数などを入力する際に、候補をリスト表示し選択できるようにするUIコンポーネントである。

### 本画面の処理概要

補完メニューは、メインREPLでTabキーを押下した際に表示されるポップアップメニューである。コマンド名、ファイルパス、変数名、フラグ名など、コンテキストに応じた補完候補を動的に生成・表示する。

**業務上の目的・背景**：
シェル操作において、長いコマンド名やファイルパスを正確に入力することは効率が悪く、エラーの原因となる。補完メニューは、入力途中の文字列から候補を推測し、ユーザーが素早く正確な入力を完了できるようサポートする。Nushellは構造化データを扱うため、レコードのキー名やセルパスの補完など、従来のシェルにない高度な補完機能も提供する。

**画面へのアクセス方法**：
- メインREPLでTabキーを押下
- 入力コンテキストに応じて自動的に補完候補が表示される

**主要な操作・処理内容**：
1. 入力位置でのコンテキスト解析（コマンド名/引数/パス/変数等）
2. コンテキストに応じた補完候補の生成
3. 候補リストのフィルタリング（プレフィックスマッチ/ファジーマッチ）
4. メニュー表示とナビゲーション（上下キー）
5. 候補選択と入力バッファへの挿入

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

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 85 | 補完機能 | 主機能 | コマンド・パス・変数等の補完候補リストの生成と表示 |
| 2 | パーサー | 補助機能 | 補完対象の構文解析とコンテキスト判定 |
| 1 | シェル実行環境 | API連携 | エンジン状態から補完対象の情報取得 |

## 画面種別

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

## URL/ルーティング

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

## 入出力項目

| 項目名 | 型 | 入力/出力 | 説明 |
|--------|-----|----------|------|
| 入力バッファ | String | 入力 | 現在の入力テキスト |
| カーソル位置 | usize | 入力 | 入力バッファ内のカーソル位置 |
| 補完候補 | Vec<Suggestion> | 出力 | 生成された補完候補リスト |
| 選択された候補 | String | 出力 | ユーザーが選択した候補テキスト |
| スパン情報 | Span | 出力 | 置換対象の範囲 |

## 表示項目

| 項目名 | 説明 | 表示形式 |
|--------|------|----------|
| 候補リスト | 補完候補の一覧 | 縦並びリスト |
| 候補値 | 補完候補のテキスト | 文字列 |
| 説明文 | 候補の説明（ある場合） | グレー文字 |
| 選択マーカー | 現在選択中の候補を示す | 反転表示/ハイライト |

## イベント仕様

### 1-Tab押下（補完トリガー）

1. 現在のカーソル位置を取得
2. 入力バッファをパースしてAST生成
3. `find_pipeline_element_by_position`でカーソル位置の式を特定
4. 式の種類に応じた補完処理を実行
   - Expr::Call → コマンド補完、引数補完
   - Expr::ExternalCall → 外部コマンド補完
   - Expr::Var → 変数名補完
   - Expr::FullCellPath → セルパス補完
   - その他 → ファイル補完（フォールバック）
5. 補完候補をメニューに表示

### 2-上下キー（候補ナビゲーション）

1. 選択インデックスを更新
2. 選択された候補をハイライト表示
3. 必要に応じてスクロール

### 3-Enter/Tab（候補選択）

1. 選択された候補のテキストを取得
2. スパン情報に基づいて入力バッファを更新
3. メニューを閉じる

### 4-Esc（キャンセル）

1. メニューを閉じる
2. 入力バッファは変更なし

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

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

## メッセージ仕様

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

## 例外処理

| 例外状態 | 対応処理 |
|---------|---------|
| パースエラー | 補完をスキップ、メニュー非表示 |
| 補完候補なし | メニュー非表示 |
| カスタム補完エラー | フォールバック補完（ファイル補完）を試行 |

## 備考

- 補完アルゴリズムはプレフィックスマッチまたはファジーマッチを設定可能
- 大文字小文字の区別も設定可能
- カスタム補完はユーザー定義のクロージャで拡張可能
- 外部コマンドの補完は設定で有効/無効を切り替え可能

---

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

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

### 推奨読解順序

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

補完機能で扱う主要なデータ構造を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | base.rs | `crates/nu-cli/src/completions/base.rs` | SemanticSuggestion構造体 |
| 1-2 | completion_options.rs | `crates/nu-cli/src/completions/completion_options.rs` | CompletionOptions（マッチアルゴリズム設定） |

**読解のコツ**: Suggestionはreedlineの型、SemanticSuggestionはNushell独自の拡張と理解する

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

補完処理の起点となる関数を特定する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | completer.rs | `crates/nu-cli/src/completions/completer.rs` | NuCompleter構造体とcomplete関数（759-765行） |

**主要処理フロー**:
1. **187-200行**: `fetch_completions_at` - 補完取得のエントリーポイント
2. **192-198行**: 入力をパースしてブロックを生成
3. **199行**: `fetch_completions_by_block` - ブロックから補完を取得

#### Step 3: コンテキスト判定を理解する

カーソル位置のコンテキストを判定する処理を追う。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | completer.rs | `crates/nu-cli/src/completions/completer.rs` | find_pipeline_element_by_position関数（25-102行） |

**主要処理フロー**:
- **36-45行**: ブロック/クロージャ/サブ式の処理
- **46-53行**: Call式の処理（内部コマンド）
- **54-71行**: ExternalCall式の処理（外部コマンド）
- **73-78行**: BinaryOp式の処理（演算子）
- **79-89行**: FullCellPath式の処理（セルパス）

#### Step 4: 補完種別ごとの処理を理解する

各種補完の実装を追う。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | command_completions.rs | `crates/nu-cli/src/completions/command_completions.rs` | コマンド名補完 |
| 4-2 | file_completions.rs | `crates/nu-cli/src/completions/file_completions.rs` | ファイルパス補完 |
| 4-3 | variable_completions.rs | `crates/nu-cli/src/completions/variable_completions.rs` | 変数名補完 |
| 4-4 | flag_completions.rs | `crates/nu-cli/src/completions/flag_completions.rs` | フラグ名補完 |
| 4-5 | custom_completions.rs | `crates/nu-cli/src/completions/custom_completions.rs` | カスタム補完 |

#### Step 5: メニュー表示を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | menu_completions.rs | `crates/nu-cli/src/menus/menu_completions.rs` | NuMenuCompleter構造体 |

**主要処理フロー**:
- **38-68行**: `complete`関数 - reedlineのCompleterトレイト実装
- **44-56行**: ブロックのパラメータにバッファと位置を設定
- **60-61行**: ブロックを評価して補完候補を取得

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

```
Tab押下 (reedline)
    |
    +-- NuCompleter::complete()             [completer.rs:760]
            |
            +-- fetch_completions_at()      [completer.rs:187]
                    |
                    +-- parse()             [nu-parser]
                    |
                    +-- fetch_completions_by_block()  [completer.rs:223]
                            |
                            +-- find_pipeline_element_by_position()  [completer.rs:25]
                            |
                            +-- complete_by_expression()  [completer.rs:270]
                                    |
                                    +-- CommandCompletion::fetch()
                                    |
                                    +-- FileCompletion::fetch()
                                    |
                                    +-- VariableCompletion::fetch()
                                    |
                                    +-- FlagCompletion::fetch()
                                    |
                                    +-- CustomCompletion::fetch()
```

### データフロー図

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

入力バッファ ──────────▶ NuCompleter
カーソル位置              |
     │                    ▼
     │              parse()
     │                    │
     │                    ▼
     │              find_pipeline_element_by_position()
     │                    │
     │                    ▼
     │              complete_by_expression() ────────▶ 補完候補リスト
     │                    │                           (Vec<Suggestion>)
     │                    ▼
     │              process_completion()
     │                    │
     │                    ▼
     │              Completer::fetch()
     │                    │
     └─────────────────▶ スパン情報 ──────────────────▶ 置換範囲
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| completer.rs | `crates/nu-cli/src/completions/completer.rs` | ソース | 補完機能のコア実装 |
| menu_completions.rs | `crates/nu-cli/src/menus/menu_completions.rs` | ソース | メニュー補完実装 |
| command_completions.rs | `crates/nu-cli/src/completions/command_completions.rs` | ソース | コマンド名補完 |
| file_completions.rs | `crates/nu-cli/src/completions/file_completions.rs` | ソース | ファイルパス補完 |
| directory_completions.rs | `crates/nu-cli/src/completions/directory_completions.rs` | ソース | ディレクトリ補完 |
| variable_completions.rs | `crates/nu-cli/src/completions/variable_completions.rs` | ソース | 変数名補完 |
| flag_completions.rs | `crates/nu-cli/src/completions/flag_completions.rs` | ソース | フラグ名補完 |
| custom_completions.rs | `crates/nu-cli/src/completions/custom_completions.rs` | ソース | カスタム補完 |
| operator_completions.rs | `crates/nu-cli/src/completions/operator_completions.rs` | ソース | 演算子補完 |
| cell_path_completions.rs | `crates/nu-cli/src/completions/cell_path_completions.rs` | ソース | セルパス補完 |
| base.rs | `crates/nu-cli/src/completions/base.rs` | ソース | 基本型定義 |
| completion_options.rs | `crates/nu-cli/src/completions/completion_options.rs` | ソース | 補完オプション |
| mod.rs | `crates/nu-cli/src/completions/mod.rs` | ソース | モジュール定義 |
