# 通知設計書 67-WINDOW_SEARCHING_IN_FILES

## 概要

本ドキュメントは、Lua Language Server における `WINDOW_SEARCHING_IN_FILES` 通知の設計仕様を定義する。この通知は、ワークスペース内のファイルを検索している状態をユーザーに表示するための進捗メッセージとして使用される。

### 本通知の処理概要

**業務上の目的・背景**：Lua Language Serverでは、「すべての参照を検索」（Find All References）などの機能を実行する際に、ワークスペース内のすべてのファイルを走査する必要がある。この処理は時間がかかる場合があるため、ユーザーに対して処理中であることを示す進捗表示が必要となる。本通知は、ファイル検索処理の進捗を示すプログレスバーのタイトルとして使用される。

**通知の送信タイミング**：`vm.getRefs`関数などでワークスペース全体のファイルを検索する際に、プログレス表示の作成時に使用される。具体的には、`searchInAllFiles`関数内で`progress.create`が呼び出される際にタイトルとして設定される。

**通知の受信者**：IDEやエディタを使用している開発者（ユーザー）に対して、ステータスバーやプログレスダイアログとして表示される。

**通知内容の概要**：「ファイルを検索しています...」という進捗状態を示すメッセージ。

**期待されるアクション**：ユーザーは処理完了を待つか、必要に応じてキャンセルボタン（利用可能な場合）をクリックして処理を中断できる。

## 通知種別

アプリ内通知（LSP $/progress - 進捗表示）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 非同期（進捗更新） |
| 優先度 | 低（進捗表示） |
| リトライ | 無 |

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

LSPプロトコルを通じて、接続中のクライアント（IDE/エディタ）に直接送信される。

## 通知テンプレート

### メール通知の場合

該当なし（LSP通知のみ）

### 本文テンプレート

英語:
```
Searching in files...
```

日本語:
```
ファイルを検索しています...
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| なし | テンプレート変数は使用されない | - | - |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| ユーザー操作 | すべての参照を検索（Find All References） | ワークスペース全体の検索が必要な場合 | vm.getRefs関数で使用 |
| ユーザー操作 | シンボルの名前変更 | ワークスペース全体の検索が必要な場合 | リネーム時の参照検索 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| 単一ファイル検索 | ファイル内のみの検索では表示されない |
| 検索対象なし | 検索対象のファイルがない場合は表示されない |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[参照検索リクエスト] --> B[vm.getRefs呼び出し]
    B --> C[searchByParentNode]
    C --> D[searchInAllFiles呼び出し]
    D --> E[progress.create]
    E --> F[WINDOW_SEARCHING_IN_FILES設定]
    F --> G[プログレス表示開始]
    G --> H{ファイル走査ループ}
    H --> I[setMessage - 進捗更新]
    I --> J[setPercentage - パーセント更新]
    J --> K{処理完了?}
    K -->|No| H
    K -->|Yes| L[プログレス終了]
    L --> M[終了]
```

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

### 参照テーブル一覧

該当なし（データベースは使用しない）

### 更新テーブル一覧

該当なし

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| ユーザーキャンセル | キャンセルボタンクリック | 処理を中断し、部分結果を返す |

### リトライ仕様

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

## 配信設定

### レート制限

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

### 配信時間帯

制限なし（随時送信）

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

- 進捗表示のみであり、セキュリティ上の懸念は特にない
- ファイルパスなどの機密情報は進捗メッセージには含まれない

## 備考

- 進捗メッセージには処理中のファイル数（例：「003/150」）が別途表示される
- パーセンテージも併せて表示される
- ユーザーはキャンセルして処理を中断できる（onCancelコールバック）
- `await.delay()`によって処理が細分化され、UIの応答性が維持される

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | progress.lua | `script/progress.lua` | progress.create関数の構造を理解する |

**読解のコツ**: progressオブジェクトはsetMessage、setPercentage、onCancelなどのメソッドを持つ

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | ref.lua | `script/vm/ref.lua` | vm.getRefs関数（303-328行目）が参照検索の起点 |

**主要処理フロー**:
1. **321行**: searchBySimpleで単純検索
2. **322行**: searchByLocalIDでローカル識別子検索
3. **323行**: searchByGlobalでグローバル検索
4. **324行**: searchByDefで定義検索
5. **325行**: searchByParentNodeでワークスペース全体検索

#### Step 3: ファイル検索ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | ref.lua | `script/vm/ref.lua` | searchInAllFiles関数（31-65行目）で進捗表示が行われる |

**主要処理フロー**:
- **45行**: progress.createでプログレス作成、WINDOW_SEARCHING_IN_FILESがタイトル
- **46-49行**: onCancelでキャンセル処理を設定
- **57行**: setMessageで進捗メッセージ更新
- **58行**: setPercentageでパーセンテージ更新

#### Step 4: 多言語対応を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | script.lua | `locale/en-us/script.lua` | 607-608行目で英語メッセージテンプレートを確認 |
| 4-2 | script.lua | `locale/ja-jp/script.lua` | 607-608行目で日本語メッセージテンプレートを確認 |

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

```
textDocument/references (LSPハンドラ)
    |
    └─ vm.getRefs (303行)
           |
           ├─ searchBySimple (321行)
           |
           ├─ searchByLocalID (322行)
           |
           ├─ searchByGlobal (323行)
           |
           ├─ searchByDef (324行)
           |
           └─ searchByParentNode (325行)
                  |
                  └─ searchInAllFiles (31行)
                         |
                         ├─ progress.create (45行)
                         |      └─ WINDOW_SEARCHING_IN_FILES
                         |
                         ├─ loading:onCancel (47行)
                         |
                         └─ ファイル走査ループ (50-64行)
                                |
                                ├─ setMessage (57行)
                                |
                                └─ setPercentage (58行)
```

### データフロー図

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

参照検索リクエスト  ───▶  vm.getRefs               ───▶  参照リスト
                           |
                           v
                    searchByParentNode
                           |
                           v
                    searchInAllFiles
                           |
                           v
                    progress.create (45行)
                           |
                           v
                WINDOW_SEARCHING_IN_FILES ───▶ $/progress通知 ───▶ UI表示
                           |
                           v
                    ファイル走査ループ
                           |
                           v
                    setMessage/setPercentage ───▶ 進捗更新
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| ref.lua | `script/vm/ref.lua` | ソース | 参照検索ロジック |
| progress.lua | `script/progress.lua` | ソース | 進捗表示管理 |
| script.lua | `locale/en-us/script.lua` | ローカライズ | 英語メッセージテンプレート |
| script.lua | `locale/ja-jp/script.lua` | ローカライズ | 日本語メッセージテンプレート |
| language.lua | `script/language.lua` | ソース | 多言語テンプレート展開 |
