# 機能設計書 15-自動インポート補完

## 概要

本ドキュメントは、serve-d LSPサーバーにおける「自動インポート補完」機能の設計を記述する。インデックスされたシンボルから未インポートのモジュールを検索し、自動インポート付き補完候補を提供する内部機能である。

### 本機能の処理概要

バックグラウンドインデックスで収集されたシンボル情報を基に、現在のドキュメントでまだインポートされていないモジュールのシンボルを補完候補として提供する。候補選択時には自動的にインポート文が追加される。リネーム済みインポートや静的インポートにも対応する。

**業務上の目的・背景**：D言語では明示的なインポート文が必要であるため、未インポートのシンボルを使用する際にインポート文を手動で追加する手間が発生する。本機能は、入力中の識別子に一致するシンボルをインデックスから検索し、インポート文の自動挿入とともに補完候補を提供することで、インポート管理の手間を削減する。

**機能の利用シーン**：開発者がまだインポートしていないモジュールの関数や型の名前を入力し始めた際に、自動インポート補完候補が表示される。候補を選択すると、ソースコードの適切な位置にインポート文が自動的に挿入される。

**主要な処理内容**：
1. IndexComponentからプレフィックス一致するシンボルを検索
2. ImporterComponentで現在のインポート状態を取得
3. 既にインポート済み（直接またはpublicインポート経由）のモジュールを除外
4. リネーム済みインポート/静的インポートの場合はプレフィックス付き補完を生成
5. 未インポートモジュールの場合はインポート追加情報を補完候補のdata属性に格納

**関連システム・外部連携**：IndexComponent、ImporterComponent

**権限による制御**：`d.enableIndex` および `d.enableAutoImportCompletions` 設定、カーソル位置の識別子プレフィックスの存在

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 17 | コード補完（textDocument/completion） | 補助機能 | コード補完の一部として未インポートモジュールからのシンボル候補を提供する |

## 機能種別

データ検索・変換処理 / インデックス活用

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| params | TextDocumentPositionParams | Yes | 補完要求の位置情報 | - |
| instance | WorkspaceD.Instance | Yes | ワークスペースインスタンス | IndexComponent, ImporterComponent必要 |
| document | Document | Yes | 対象ドキュメント | - |
| completion | CompletionItem[] | Yes | 追加先の補完リスト（参照） | - |
| byteOff | int | Yes | カーソルのバイトオフセット | 0以上 |
| prefixIdentifier | string | Yes | 入力中の識別子プレフィックス | 長さ1以上 |
| exactMatch | bool | No | 完全一致検索フラグ（デフォルトfalse） | - |

### 入力データソース

- provideDSourceCompleteからの内部呼び出し
- IndexComponentからのインデックスされたシンボル情報
- ImporterComponentからの現在のインポート状態

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| completion (参照) | CompletionItem[] | 自動インポート補完アイテムが追加される |

### 出力先

呼び出し元（provideDSourceComplete）のcompletion配列への参照追加

## 処理フロー

### 処理シーケンス

```
1. IndexComponent と ImporterComponent を取得
2. ImporterComponent.get で現在のインポート情報を取得
   └─ availableImports: 既存インポートモジュール一覧
3. モジュールルックアップテーブル構築
   └─ modLookup: モジュール名 → インポート情報インデックス
4. publicインポート経由の間接インポート収集
   └─ iteratePublicImportsRecursive で再帰的にpublicインポートを辿る
5. IndexComponent.iterateSymbolsStartingWith でプレフィックス一致シンボルを列挙
   5-1. "object"モジュール/自モジュール/空シンボルをスキップ
   5-2. exactMatch時は完全一致のみ
   5-3. publicインポート経由のモジュールをスキップ
   5-4. 既にインポート済みの場合:
        ├─ 静的/リネームインポート: プレフィックス付き補完を生成
        └─ 選択的インポート: TODO（未実装）
   5-5. 未インポートの場合:
        └─ "auto-import from {module}" の補完を生成
6. 各補完アイテムのdata属性にuri, line, column, imports, moduleNameを格納
```

### フローチャート

```mermaid
flowchart TD
    A[provideAutoImports 呼び出し] --> B[IndexComponent/ImporterComponent取得]
    B --> C[既存インポート情報取得]
    C --> D[publicインポート再帰収集]
    D --> E[iterateSymbolsStartingWith]
    E --> F{各シンボルの判定}
    F -->|object/self/empty| G[スキップ]
    F -->|publicインポート経由| G
    F -->|既にインポート済み| H{静的/リネーム?}
    H -->|Yes| I[プレフィックス付き補完生成]
    H -->|No| G
    F -->|未インポート| J[auto-import補完生成]
    I --> K[data属性にメタデータ格納]
    J --> K
    K --> L[completion配列に追加]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-15-01 | objectモジュール除外 | "object"モジュールのシンボルは自動インポート候補に含めない | 全シンボル判定時 |
| BR-15-02 | 自モジュール除外 | 現在編集中のモジュール自身のシンボルは除外 | 全シンボル判定時 |
| BR-15-03 | publicインポート除外 | publicインポート経由で既にアクセス可能なシンボルは除外 | 全シンボル判定時 |
| BR-15-04 | ソートサブキー | モジュール名に応じたサブソートキー（0_=インポート済み, 1_=std.*, 2_=core.*等） | ソートテキスト生成時 |
| BR-15-05 | リネームインポート対応 | リネーム/静的インポートの場合はプレフィックス付きで補完 | 既存インポートにリネーム名がある場合 |
| BR-15-06 | ソートプレフィックス | 自動インポート補完には sortPrefixAutoImport("3_") を付与 | 全自動インポート補完 |

### 計算ロジック

モジュールソートキー（getModuleSortKey）の生成:
- インポート済みモジュール: "0_"
- std.* モジュール: "1_"
- core.* / etc.* モジュール: "2_"
- その他: デフォルト

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

本機能ではデータベース操作は行わない。インメモリインデックスのみ使用。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | コンポーネント不在 | IndexComponent/ImporterComponent未ロード | 自動インポート補完をスキップ |

### リトライ仕様

リトライなし。

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

トランザクション管理なし。読み取り専用操作。

## パフォーマンス要件

コード補完のサブ処理として並列実行。プレフィックス識別子が存在する場合のみ実行される。インデックスの走査は O(N)（Nはインデックスされたシンボル数）。

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

特になし。

## 備考

- data属性の "moduleName" キーはcode_actions.dでも参照されるため、互換性に注意
- completionItem/resolveで自動インポートのadditionalTextEditsが解決される

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | complete.d | `source/served/commands/complete.d` | `sortPrefixAutoImport` 定数（39行目）を確認 |

**読解のコツ**: ImporterComponentの `get` メソッドは、現在のドキュメント内のインポート状態（モジュール名、リネーム、選択的インポート等）を返却する。`availableImports` は `ImportInfo[]` 型。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | complete.d | `source/served/commands/complete.d` | `provideAutoImports` 関数（735-839行目）が自動インポート補完のエントリーポイント |

**主要処理フロー**:
1. **739行目**: IndexComponent取得
2. **740行目**: ImporterComponent.getで現在のインポート情報取得
3. **741-743行目**: モジュールルックアップテーブル構築
4. **746-753行目**: publicインポートの再帰収集
5. **760-838行目**: iterateSymbolsStartingWithでシンボル列挙と補完アイテム生成
6. **771-810行目**: 既存インポート済みシンボルの処理（リネーム/静的インポート対応）
7. **812-837行目**: 未インポートシンボルの補完アイテム生成

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

```
provideDSourceComplete (complete.d:550)
    │
    └─ provideAutoImports (complete.d:735)
           │
           ├─ IndexComponent.iterateSymbolsStartingWith
           │
           ├─ ImporterComponent.get
           │
           └─ IndexComponent.iteratePublicImportsRecursive
```

### データフロー図

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

prefixIdentifier ──────────▶ provideAutoImports ────────────▶ completion[] (参照追加)
Document + ImporterComponent ──┘      │
                                      ├── IndexComponent ──▶ シンボル一覧
                                      ├── ImporterComponent ──▶ インポート状態
                                      └── publicImport再帰 ──▶ 除外リスト
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| complete.d | `source/served/commands/complete.d` | ソース | provideAutoImports関数 |
| extension.d | `source/served/extension.d` | ソース | コマンド登録 |
