# 機能設計書 85-補完機能

## 概要

本ドキュメントは、Nushellの補完機能（NuCompleter）の設計について記述する。補完機能は、ユーザーの入力中にコマンド名、ファイルパス、変数名、フラグなどの候補を提示し、入力効率を向上させる。

### 本機能の処理概要

NuCompleterは、reedlineのCompleterトレイトを実装し、カーソル位置のコンテキストに応じた適切な補完候補を生成する。構文解析結果に基づいて補完の種類を判定し、コマンド補完、ファイル補完、変数補完、フラグ補完、カスタム補完など複数の補完戦略を使い分ける。

**業務上の目的・背景**：対話型シェルにおいて、補完機能は生産性に直結する重要な機能である。長いコマンド名やファイルパスを完全に入力する必要がなく、タブキー一つで補完候補を取得できることで、入力ミスを減らし、作業効率を大幅に向上させる。

**機能の利用シーン**：コマンド入力中のタブキー押下時、メニュー補完時、LSPサーバーからのコード補完要求時など、補完候補が必要なあらゆる場面で利用される。

**主要な処理内容**：
1. 入力行の構文解析（パース）
2. カーソル位置に基づく補完対象の特定
3. コンテキストに応じた補完種別の決定
4. 各種補完器からの候補収集
5. 補完オプションに基づくフィルタリング・ソート
6. 補完候補の返却

**関連システム・外部連携**：reedline（補完UI）、nu-lsp（LSP補完）

**権限による制御**：なし

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | メインREPL | 補助機能 | タブキー押下時のコマンド・パス・変数の自動補完処理 |
| 2 | 補完メニュー | 主機能 | コマンド・パス・変数等の補完候補リストの生成と表示 |
| 10 | LSP言語サーバ | 主機能 | エディタ連携のためのコード補完候補の提供 |

## 機能種別

対話支援 / 入力補完

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| line | &str | Yes | 入力行全体 | - |
| pos | usize | Yes | カーソル位置 | 行長以下 |

### 入力データソース

- 現在の入力行（reedlineから渡される）
- EngineState（コマンド定義、変数定義等）
- Stack（現在のスコープ情報）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| suggestions | Vec<Suggestion> | 補完候補リスト |

### 出力先

reedline補完システム

## 処理フロー

### 処理シーケンス

```
1. 入力行のパース
   └─ parse()で構文木を生成
2. 補完対象の特定
   └─ find_pipeline_element_by_positionでカーソル位置の式を取得
3. 補完種別の判定
   └─ 式の種類（Call, ExternalCall, Var等）で分岐
4. 補完候補の生成
   └─ 各種Completerから候補を収集
5. フィルタリングとソート
   └─ プレフィックスマッチ、case sensitivity適用
6. 結果返却
   └─ Vec<Suggestion>として返却
```

### フローチャート

```mermaid
flowchart TD
    A[complete呼び出し] --> B[入力行パース]
    B --> C[カーソル位置の式を特定]
    C --> D{式の種類}
    D -->|Call| E[コマンド補完 + フラグ補完]
    D -->|ExternalCall| F[外部コマンド補完]
    D -->|Var/FullCellPath| G[変数補完]
    D -->|BinaryOp| H[演算子補完]
    D -->|AttributeBlock| I[アトリビュート補完]
    E --> J[引数位置判定]
    J --> K{カスタム補完あり?}
    K -->|Yes| L[CustomCompletion実行]
    K -->|No| M[デフォルト補完]
    F --> N[外部completer設定確認]
    G --> O[VariableCompletion]
    H --> P[OperatorCompletion]
    L --> Q[結果マージ]
    M --> Q
    N --> Q
    O --> Q
    P --> Q
    I --> Q
    Q --> R[フィルタリング・ソート]
    R --> S[Suggestion返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-85-01 | カスタム補完優先 | コマンドシグネチャにカスタム補完が定義されている場合は優先 | positional/flagにcompletion定義あり |
| BR-85-02 | フォールバック | 補完候補がない場合はファイル補完にフォールバック | 候補が空の場合 |
| BR-85-03 | 大文字小文字感度 | 設定に応じてcase-sensitive/insensitiveを切り替え | completions.case_sensitive設定 |
| BR-85-04 | 外部コマンド補完 | 外部コマンドにはexternal.completerを使用 | ExternalCall時 |
| BR-85-05 | プレフィックスマッチ | 入力済み文字列をプレフィックスとして候補をフィルタ | 常時 |

### 計算ロジック

**補完オプション生成**:
```rust
CompletionOptions {
    case_sensitive: config.completions.case_sensitive,
    match_algorithm: config.completions.algorithm.into(),
    sort: config.completions.sort,
}
```

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | - | パース失敗 | 空の補完リストを返却 |
| - | - | カスタム補完エラー | フォールバック補完を使用 |

### リトライ仕様

該当なし（エラー時は空リスト返却）

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

該当なし

## パフォーマンス要件

- 補完候補生成は100ms以内
- 大量の候補がある場合でもUIがフリーズしないこと

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

特になし

## 備考

- 複数の補完戦略を統合する複雑なシステム
- LSP対応のためfetch_completions_within_fileメソッドも提供

---

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

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

### 推奨読解順序

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

補完システムで使用する主要な構造体とトレイトを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | base.rs | `crates/nu-cli/src/completions/base.rs` | SemanticSuggestion, Completerトレイト |
| 1-2 | completion_options.rs | `crates/nu-cli/src/completions/completion_options.rs` | CompletionOptions構造体 |

**読解のコツ**: Completerトレイトのfetchメソッドが各補完器の共通インターフェース

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | completer.rs | `crates/nu-cli/src/completions/completer.rs` | NuCompleter構造体 |

**主要処理フロー**:
1. **149-153行目**: NuCompleter構造体定義
2. **179-185行目**: new()コンストラクタ
3. **187-200行目**: fetch_completions_at() - REPLからの呼び出しエントリ
4. **223-260行目**: fetch_completions_by_block() - ブロックからの補完候補取得
5. **270-648行目**: complete_by_expression() - 式の種類に応じた補完処理

#### Step 3: 各種補完器を理解する

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

**各補完器のパターン**:
- Completerトレイトを実装
- fetchメソッドで候補を生成
- SemanticSuggestionのリストを返却

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

```
NuCompleter::complete() [reedline Completer]
    │
    └─ fetch_completions_at()
           │
           ├─ parse() [構文解析]
           │
           └─ fetch_completions_by_block()
                  │
                  ├─ find_pipeline_element_by_position()
                  │
                  └─ complete_by_expression()
                         │
                         ├─ match expr.expr
                         │      ├─ Var → VariableCompletion
                         │      ├─ FullCellPath → CellPathCompletion
                         │      ├─ BinaryOp → OperatorCompletion
                         │      ├─ Call → CommandCompletion + FlagCompletion
                         │      └─ ExternalCall → FileCompletion
                         │
                         └─ process_completion()
                                │
                                └─ completer.fetch()
```

### データフロー図

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

入力行 + pos ───▶ パース ───▶ 式の特定 ───▶ 補完器選択 ───▶ 候補リスト
  "ls -l"          Block      Call             CommandCompletion    ["ls"]
  "$env."          Block      FullCellPath     CellPathCompletion   ["PATH", ...]
  "open "          Block      Call             FileCompletion       ["file.txt", ...]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| completer.rs | `crates/nu-cli/src/completions/completer.rs` | ソース | メイン補完ロジック |
| base.rs | `crates/nu-cli/src/completions/base.rs` | ソース | 基本型定義 |
| completion_options.rs | `crates/nu-cli/src/completions/completion_options.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` | ソース | セルパス補完 |
| attribute_completions.rs | `crates/nu-cli/src/completions/attribute_completions.rs` | ソース | アトリビュート補完 |
| dotnu_completions.rs | `crates/nu-cli/src/completions/dotnu_completions.rs` | ソース | .nuファイル補完 |
| mod.rs | `crates/nu-cli/src/completions/mod.rs` | ソース | モジュールエクスポート |
