# 通知設計書 72-COMPLETION_IMPORT_FROM

## 概要

本ドキュメントは、Lua Language Serverにおける `COMPLETION_IMPORT_FROM` 通知の設計を記述する。この通知は、コード補完時に自動requireの候補が表示される際、インポート元のファイルを示すために使用される。

### 本通知の処理概要

この通知は、コード補完において別のファイルで定義されたモジュールやシンボルを候補として表示する際に、そのシンボルがどのファイルからインポートされるかを示す説明テキストとして表示される。

**業務上の目的・背景**：Luaプロジェクトでは、複数のファイルで同名の変数や関数が定義されることがある。自動require機能で補完候補を表示する際、ユーザーがどのファイルからインポートされるかを把握できるようにすることで、意図しないファイルの参照を防ぎ、正確なコーディングを支援する。

**通知の送信タイミング**：ユーザーがコード補完を実行し、ワークスペース内の他のファイルに定義されたモジュールが候補として提示される際に、その補完アイテムの説明文として表示される。

**通知の受信者**：VSCode等のLSPクライアントを使用している開発者。補完リストのアイテム詳細として表示される。

**通知内容の概要**：「{ファイルパス}からインポート」という形式のテキストで、インポート元のファイルパスを含むMarkdown形式のリンクが表示される。

**期待されるアクション**：ユーザーはこの情報を参考に、適切な補完候補を選択する。

## 通知種別

アプリ内通知（コード補完アイテムの説明文）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 非同期（補完アイテムの詳細解決時） |
| 優先度 | 中 |
| リトライ | なし |

### 送信先決定ロジック

LSPプロトコルのcompletionItem/resolve応答の一部として、補完アイテムのdescriptionフィールドに含めて返却される。

## 通知テンプレート

### 補完アイテム説明文の場合

| 項目 | 内容 |
|-----|------|
| 形式 | Markdown |
| 本文 | COMPLETION_IMPORT_FROM（インポート元表示） |

### 本文テンプレート

```
日本語: {ファイルパス}からインポート
英語: Import from {ファイルパス}
```

### 添付ファイル

なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| {ファイルパス} | インポート元ファイルの相対パス（Markdownリンク形式） | workspace.getRelativePath(uri) | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| LSPリクエスト | textDocument/completion | 自動require候補がある場合 | コード補完時に他ファイルのモジュールを候補表示 |
| LSPリクエスト | completionItem/resolve | 補完アイテムの詳細取得時 | 選択された補完アイテムの詳細情報を取得 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| autoRequire無効 | Lua.completion.autoRequire設定がfalseの場合 |
| 同一ファイル内 | 補完候補が同一ファイル内で定義されている場合 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[textDocument/completion発生] --> B[単語入力判定]
    B --> C[ローカル変数チェック]
    C --> D{グローバル/モジュール検索}
    D -->|モジュール発見| E[checkModule呼び出し]
    E --> F[auto-require.check実行]
    F --> G[補完候補生成]
    G --> H[COMPLETION_IMPORT_FROMを説明に設定]
    H --> I[補完リスト返却]
```

## データベース参照・更新仕様

### 参照テーブル一覧

本通知はデータベースを使用しない。インメモリでファイル情報を管理する。

### テーブル別参照項目詳細

該当なし

### 更新テーブル一覧

該当なし

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| ファイル未検出 | 対象ファイルが削除されている | 補完候補から除外 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0回（リトライなし） |
| リトライ間隔 | - |
| リトライ対象エラー | - |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | 制限なし |
| 1日あたり上限 | 制限なし |

### 配信時間帯

制限なし（エディタ操作時のみ）

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

- ファイルパス情報のみを扱うため、個人情報の取り扱いはない
- ワークスペース外のファイルパスは表示されない

## 備考

- この通知は補完アイテムのdescriptionの一部として表示される
- ファイルパスはMarkdownリンク形式で表示され、クリックで該当ファイルにジャンプ可能

---

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

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

### 推奨読解順序

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

まず、通知で使用されるローカライズ文字列の定義を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | script.lua | `locale/ja-jp/script.lua` | COMPLETION_IMPORT_FROMの日本語定義（510-511行目）を確認 |
| 1-2 | script.lua | `locale/en-us/script.lua` | COMPLETION_IMPORT_FROMの英語定義（510-511行目）を確認 |

**読解のコツ**: `{}` はテンプレート変数のプレースホルダーとして使用される。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | completion.lua | `script/core/completion/completion.lua` | checkModule関数（414-449行目） |

**主要処理フロー**:
1. **414-417行目**: autoRequire設定のチェック
2. **418-448行目**: auto-require.checkの呼び出しと補完候補の生成
3. **436-437行目**: COMPLETION_IMPORT_FROMの使用箇所

#### Step 3: 自動require処理を理解する

モジュール検索とインポート処理の詳細を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | auto-require.lua | `script/core/completion/auto-require.lua` | check関数の実装（38-153行目） |

**主要処理フロー**:
- **38-41行目**: 設定とローカル変数の取得
- **42-97行目**: ワークスペース内ファイルの検索とマッチング
- **91-92行目**: コールバック呼び出しによる補完候補の返却

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

```
textDocument/completion (provider.lua:621)
    │
    └─ completion.completion() (completion.lua:2379)
           │
           ├─ tryWord() (completion.lua:1499)
           │      │
           │      └─ checkModule() (completion.lua:414)
           │             │
           │             └─ autoRequire.check() (auto-require.lua:38)
           │                    │
           │                    └─ callback(uri, stemName, targetSource)
           │
           └─ stack() + resolve() - 説明文の遅延解決
                  │
                  └─ lang.script('COMPLETION_IMPORT_FROM', ...)
```

### データフロー図

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

ユーザー入力 ───▶ 補完トリガー ───▶ モジュール検索
                       │               │
                       │               └─▶ ワークスペースファイルスキャン
                       │                       │
                       │                       └─▶ マッチする候補抽出
                       │
                       └─▶ 補完アイテム生成 ───▶ COMPLETION_IMPORT_FROM
                                                       │
                                                       └─▶ description設定
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| completion.lua | `script/core/completion/completion.lua` | ソース | コード補完のメイン処理 |
| auto-require.lua | `script/core/completion/auto-require.lua` | ソース | 自動require候補の検索 |
| provider.lua | `script/provider/provider.lua` | ソース | LSPハンドラ |
| script.lua | `locale/ja-jp/script.lua` | ローカライズ | 日本語メッセージ定義 |
| script.lua | `locale/en-us/script.lua` | ローカライズ | 英語メッセージ定義 |
| workspace.lua | `script/workspace/workspace.lua` | ソース | ワークスペース管理 |
