# 機能設計書 59-補完プロバイダ

## 概要

本ドキュメントは、Visual Studio統合におけるF#コードのIntelliSense補完機能について記述する。

### 本機能の処理概要

F#ソースコード編集時に、カーソル位置に基づいてコード補完候補を提供する機能。型、メンバー、キーワード、未開封名前空間のシンボルを補完候補として表示する。

**業務上の目的・背景**：コード補完はIDE開発体験の中核機能であり、開発者の生産性向上に直結する。F#の型推論機能と連携し、文脈に適した補完候補を提供することで、迅速かつ正確なコーディングを支援する。

**機能の利用シーン**：
- メンバーアクセス時（.入力後）
- 識別子入力時
- キーワード入力時
- 名前空間/モジュールの補完

**主要な処理内容**：
1. 補完トリガーの判定
2. 型チェック結果からの補完候補取得
3. キーワード補完の追加
4. 未開封名前空間からのシンボル取得
5. 補完項目の優先度ソート（MRU）
6. 名前空間のopen文自動挿入

**関連システム・外部連携**：
- Microsoft.CodeAnalysis.Completion（Roslyn）
- FSharp.Compiler.Service（FCS）
- Visual Studioエディタサービス

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | コードエディタ | 入力画面 | IntelliSense補完 |

## 機能種別

UI入力支援 / エディタサービス

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| context | CompletionContext | Yes | 補完コンテキスト | - |
| sourceText | SourceText | Yes | ソーステキスト | - |
| caretPosition | int | Yes | カーソル位置 | 0以上 |
| trigger | CompletionTrigger | Yes | トリガー種別 | - |

### 補完トリガー種別

| トリガー | 説明 |
|---------|------|
| Insertion | 文字入力 |
| Deletion | 文字削除 |
| Invoke | 明示的呼び出し（Ctrl+Space） |

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| completionItems | List<CompletionItem> | 補完候補リスト |

### CompletionItem

| フィールド | 説明 |
|-----------|------|
| DisplayText | 表示テキスト |
| FilterText | フィルタリング用テキスト |
| SortText | ソート用テキスト |
| Glyph | アイコン |
| InlineDescription | インライン説明（名前空間名等） |
| Properties | 追加プロパティ（FullName等） |

## 処理フロー

### 処理シーケンス

```
1. トリガー判定（ShouldTriggerCompletion）
   └─ 補完を開始すべき文字か判定
   └─ 範囲式（..）、型注釈（:）等では補完しない

2. 補完コンテキスト取得
   └─ ParsedInput.TryGetCompletionContext
   └─ 補完種別の判定（メンバー、識別子等）

3. 宣言リスト取得（GetDeclarationListInfo）
   └─ 型チェック結果から候補取得
   └─ 未開封名前空間のシンボル取得（オプション）

4. 候補のソート
   └─ 解決済み > 未解決
   └─ Kind優先度
   └─ 自メンバー優先
   └─ アルファベット順
   └─ MRU優先度

5. キーワード追加（オプション）
   └─ 型コンテキスト以外で追加

6. CompletionItem構築
   └─ Glyphの設定
   └─ Propertiesの設定
   └─ SortTextの設定
```

### フローチャート

```mermaid
flowchart TD
    A[開始: 補完リクエスト] --> B{トリガー有効?}
    B -->|No| C[終了: 空リスト]
    B -->|Yes| D[補完コンテキスト取得]
    D --> E[GetDeclarationListInfo]
    E --> F[候補ソート]
    F --> G{型コンテキスト?}
    G -->|No| H[キーワード追加]
    G -->|Yes| I[CompletionItem構築]
    H --> I
    I --> J[結果返却]
    J --> K[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-59-01 | コミット文字制限 | スペース、=、,、<、>、:等ではコミットしない | 常時 |
| BR-59-02 | MRU | 最近使用した項目を優先的に上位表示 | 常時 |
| BR-59-03 | 削除後補完 | ShowAfterCharIsDeleted設定で削除後も補完表示 | 設定依存 |
| BR-59-04 | 未開封シンボル | IncludeSymbolsFromUnopenedNamespacesOrModules設定 | 設定依存 |

### 計算ロジック

**ソート優先度計算**:
```
1. 解決済み（IsResolved）: true優先
2. Kind優先度: getKindPriority(Kind)
3. 自メンバー（IsOwnMember）: true優先
4. 名前: アルファベット順（大文字小文字無視）
5. MinorPriority: 小さい値優先
```

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

本機能はデータベースを使用しない。mruItems（Dictionary）でMRU管理。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | キャンセル | CancellationToken発火 | 空リスト返却 |
| - | 例外 | 解析エラー | 空リスト返却 |

## パフォーマンス要件

- declarationItems配列のインプレースソートで効率化
- キーワード補完項目は静的キャッシュ
- テレメトリによるパフォーマンス監視

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

なし

## 備考

- FSharpCompletionProviderBaseを継承
- Roslyn互換のCompletionItemを返却
- 補完選択時のopen文自動挿入をサポート

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | CompletionProvider.fs | `vsintegration/src/FSharp.Editor/Completion/CompletionProvider.fs` | FSharpCompletionProviderクラス（28-34行目） |
| 1-2 | CompletionProvider.fs | `vsintegration/src/FSharp.Editor/Completion/CompletionProvider.fs` | ProvideCompletionsAsync（319-373行目）がメイン処理 |

#### Step 2: トリガー判定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | CompletionProvider.fs | `vsintegration/src/FSharp.Editor/Completion/CompletionProvider.fs` | ShouldTriggerCompletionAux（102-146行目） |
| 2-2 | CompletionProvider.fs | `vsintegration/src/FSharp.Editor/Completion/CompletionProvider.fs` | ShouldTriggerCompletionImpl（299-317行目） |

#### Step 3: 補完候補取得を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | CompletionProvider.fs | `vsintegration/src/FSharp.Editor/Completion/CompletionProvider.fs` | ProvideCompletionsAsyncAux（148-297行目） |
| 3-2 | CompletionProvider.fs | `vsintegration/src/FSharp.Editor/Completion/CompletionProvider.fs` | GetDeclarationListInfo呼び出し（190-199行目） |
| 3-3 | CompletionProvider.fs | `vsintegration/src/FSharp.Editor/Completion/CompletionProvider.fs` | 候補ソート（203-226行目） |

#### Step 4: 補完確定処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | CompletionProvider.fs | `vsintegration/src/FSharp.Editor/Completion/CompletionProvider.fs` | GetChangeAsync（410-498行目） |
| 4-2 | CompletionProvider.fs | `vsintegration/src/FSharp.Editor/Completion/CompletionProvider.fs` | OpenDeclarationHelper.insertOpenDeclaration（488行目） |

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

```
FSharpCompletionProvider
    │
    ├─ ShouldTriggerCompletionImpl
    │      └─ ShouldTriggerCompletionAux
    │             └─ CompletionUtils.shouldProvideCompletion
    │
    ├─ ProvideCompletionsAsync
    │      └─ ProvideCompletionsAsyncAux
    │             ├─ GetFSharpParseAndCheckResultsAsync
    │             ├─ GetDeclarationListInfo
    │             ├─ Array.sortInPlaceWith (ソート)
    │             └─ keywordCompletionItems追加
    │
    ├─ GetDescriptionAsync
    │      └─ XmlDocumentation.BuildDataTipText
    │
    └─ GetChangeAsync
           ├─ MRU更新
           └─ OpenDeclarationHelper.insertOpenDeclaration
```

### データフロー図

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

カーソル位置          ──▶  TryGetCompletionContext   ──▶  CompletionContext
       │
       ▼
CheckFileResults      ──▶  GetDeclarationListInfo    ──▶  DeclarationListItem[]
       │
       ▼
DeclarationListItem[] ──▶  ソート                    ──▶  ソート済み配列
       │
       ▼
ソート済み + キーワード ──▶ CompletionItem構築       ──▶  List<CompletionItem>
       │
       ▼
選択されたItem        ──▶  GetChangeAsync            ──▶  CompletionChange
       │
       ▼
CompletionChange      ──▶  insertOpenDeclaration     ──▶  TextChange（open文含む）
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| CompletionProvider.fs | `vsintegration/src/FSharp.Editor/Completion/CompletionProvider.fs` | ソース | 補完プロバイダーの中核実装 |
| CompletionUtils.fs | `vsintegration/src/FSharp.Editor/Completion/CompletionUtils.fs` | ソース | 補完ユーティリティ |
| OpenDeclarationHelper.fs | `vsintegration/src/FSharp.Editor/CodeFixes/OpenDeclarationHelper.fs` | ソース | open文挿入ヘルパー |
