# 画面設計書 13-ワークスペースシンボル

## 概要

本ドキュメントは、Lua Language Serverの「ワークスペースシンボル（workspace/symbol）」機能の画面設計書である。この機能は、ワークスペース全体からシンボル（関数、変数、クラス等）を検索し、一覧表示する機能を提供する。

### 本画面の処理概要

この機能では、ユーザーが入力したクエリ文字列に基づいて、ワークスペース内のすべてのファイルからシンボルを検索し、マッチするシンボルの一覧を返却する。エディタはこの情報を使用してグローバルシンボル検索機能を提供する。

**業務上の目的・背景**：大規模なLuaプロジェクトでは、多数のファイルにわたって関数やクラスが定義されている。特定のシンボルを探す際に、すべてのファイルを手動で検索することは非効率である。ワークスペースシンボル機能により、プロジェクト全体から目的のシンボルを即座に検索でき、開発効率が大幅に向上する。

**画面へのアクセス方法**：エディタのシンボル検索コマンド（Ctrl+T等）を実行し、検索クエリを入力することで、この機能が呼び出される。VS Codeでは「シンボルへ移動...」コマンドで表示される。

**主要な操作・処理内容**：
1. クエリ文字列を受け取る
2. ワークスペース内のすべてのファイルを走査する
3. グローバル変数、クラス定義、関数定義などをクエリと照合する
4. マッチするシンボルの位置情報とともに一覧を返却する

**画面遷移**：検索結果一覧からシンボルを選択すると、そのシンボルの定義位置にジャンプする。そこから「参照検索」や「名前変更」などの機能に遷移できる。

**権限による表示制御**：特になし。LSPプロトコルレベルでの認証・権限管理は行わない。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 21 | ワークスペースシンボル (workspace/symbol) | 主機能 | ワークスペース全体からシンボルを検索する主処理 |

## 画面種別

LSP機能（検索・一覧）

## URL/ルーティング

LSPメソッド: `workspace/symbol`

## 入出力項目

### 入力項目（リクエストパラメータ）

| 項目名 | 型 | 必須 | 説明 |
|--------|-----|------|------|
| query | string | Yes | 検索クエリ文字列 |

### 出力項目（レスポンス）

| 項目名 | 型 | 説明 |
|--------|-----|------|
| symbols | SymbolInformation[] | シンボル情報配列 |

### SymbolInformation構造

| 項目名 | 型 | 説明 |
|--------|-----|------|
| name | string | シンボル名 |
| kind | SymbolKind | シンボル種別（Function, Variable, Class等） |
| location | Location | シンボルの位置情報（URI + Range） |

## 表示項目

| 表示項目 | 説明 |
|---------|------|
| シンボル名 | 変数名、関数名、クラス名等 |
| シンボルアイコン | SymbolKindに応じたアイコン |
| ファイルパス | シンボルが定義されているファイル |
| 位置情報 | 行番号等の位置情報 |

## イベント仕様

### 1-workspaceSymbolリクエスト処理

1. クライアントからworkspace/symbolリクエストを受信
2. クエリ文字列を取得
3. searchGlobalAndClass関数でグローバル変数とクラスを検索
4. searchClassField関数でクラスフィールドを検索
5. オプションでsearchWords関数でローカル定義を検索
6. 結果をLSP形式に変換してレスポンスを返却

## データベース更新仕様

### 操作別データベース影響一覧

この機能はデータベース操作を行わない。インメモリのシンボルキャッシュを検索するのみで、変更は行わない。

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| workspaceSymbolリクエスト | なし | SELECT（読み取り） | シンボルキャッシュの検索のみ |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 発生条件 |
|-------------|------|---------------|---------|
| WINDOW_PROCESSING_WS_SYMBOL | 進捗 | 処理中表示 | シンボル検索処理中 |
| - | 成功 | （シンボル配列返却） | シンボルが見つかった場合 |
| - | 成功 | null | シンボルが見つからない場合 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| シンボルが存在しない | nullを返却 |
| クエリが空 | 全シンボルまたはnullを返却 |

## 備考

- 検索はあいまいマッチ（matchKey関数）を使用し、クエリ文字列の部分一致でシンボルを検索する
- グローバル変数、doc.class、doc.alias定義が優先的に検索される
- クラスフィールド検索は「ClassName.fieldName」形式のクエリに対応
- 結果は最大1000件に制限される
- includeWordsオプションがtrueの場合、ファイル内のローカル定義も検索対象に含まれる

---

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

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

### 推奨読解順序

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

まず、SymbolInformationとLocationの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | define.lua | `script/proto/define.lua` | SymbolKind, CompletionItemKindの定義 |
| 1-2 | converter.lua | `script/proto/converter.lua` | location関数（URI + Range変換） |

**読解のコツ**: ワークスペースシンボルはSymbolInformation形式を使用し、これはDocumentSymbolとは異なりネスト構造を持たない。

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

処理の起点となるプロバイダー登録を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | provider.lua | `script/provider/provider.lua` | workspace/symbolの登録（1023-1066行目） |

**主要処理フロー**:
1. **1023行目**: `m.register 'workspace/symbol'`でハンドラー登録
2. **1030行目**: `progress.create`で進捗表示
3. **1031行目**: `core/workspace-symbol`モジュールを呼び出し
4. **1033行目**: クエリと`includeWords=true`で検索実行
5. **1038-1056行目**: convert関数でシンボルをLSP形式に変換

#### Step 3: コア処理を理解する

シンボル検索のコアロジックを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | workspace-symbol.lua | `script/core/workspace-symbol.lua` | 検索処理の全体構造 |
| 3-2 | workspace-symbol.lua | `script/core/workspace-symbol.lua` (7-44行目) | buildSource関数 - ソースからシンボル構築 |
| 3-3 | workspace-symbol.lua | `script/core/workspace-symbol.lua` (60-91行目) | searchGlobalAndClass関数 - グローバル・クラス検索 |
| 3-4 | workspace-symbol.lua | `script/core/workspace-symbol.lua` (96-134行目) | searchClassField関数 - クラスフィールド検索 |
| 3-5 | workspace-symbol.lua | `script/core/workspace-symbol.lua` (139-146行目) | searchWords関数 - ファイル内検索 |
| 3-6 | matchkey.lua | `script/core/matchkey.lua` | あいまいマッチロジック |

**主要処理フロー**:
- **60-91行目**: searchGlobalAndClass - vm.getAllGlobals()で全グローバルを取得し、matchKeyでフィルタ
- **96-134行目**: searchClassField - 「Class.field」形式のクエリを解析し、クラスフィールドを検索
- **139-146行目**: searchWords - files.eachFile()で全ファイルを走査し、searchFileでシンボル検索

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

```
workspace/symbol (provider.lua:1023-1066)
    |
    +-- progress.create (進捗表示)
    |
    +-- core/workspace-symbol (workspace-symbol.lua:151-161)
           |
           +-- searchGlobalAndClass (60-91行目)
           |      |
           |      +-- vm.getAllGlobals (全グローバル取得)
           |      |
           |      +-- matchKey (あいまいマッチ)
           |      |
           |      +-- globalVar:getSets (定義位置取得)
           |
           +-- searchClassField (96-134行目)
           |      |
           |      +-- vm.getGlobal('type', class)
           |      |
           |      +-- vm.getClassFields (クラスフィールド取得)
           |
           +-- searchWords (139-146行目) [includeWords=true時]
                  |
                  +-- files.eachFile (全ファイル走査)
                  |
                  +-- searchFile (46-55行目)
                         |
                         +-- guide.eachSource (各ソース走査)
                         |
                         +-- buildSource (シンボル構築)
```

### データフロー図

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

WorkspaceSymbolParams          provider.lua                        SymbolInformation[]
+------------------+           +------------------+                 +------------------+
| query            |  ------>  | progress.create   |                 | name             |
+------------------+           | core呼び出し      |                 | kind             |
                               +------------------+                 | location         |
                                      |                             |   uri            |
                                      v                             |   range          |
                               workspace-symbol.lua                 +------------------+
                               +----------------------+
                               | searchGlobalAndClass |
                               |   vm.getAllGlobals   |  -------->
                               |   matchKey           |
                               | searchClassField     |
                               |   vm.getClassFields  |
                               | searchWords          |
                               |   files.eachFile     |
                               +----------------------+
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| provider.lua | `script/provider/provider.lua` | ソース | LSPメソッドハンドラー登録 |
| workspace-symbol.lua | `script/core/workspace-symbol.lua` | ソース | シンボル検索コアロジック |
| matchkey.lua | `script/core/matchkey.lua` | ソース | あいまいマッチユーティリティ |
| vm.lua | `script/vm/init.lua` | ソース | グローバル変数・クラス管理 |
| define.lua | `script/proto/define.lua` | ソース | SymbolKind定義 |
| converter.lua | `script/proto/converter.lua` | ソース | Location変換処理 |
| files.lua | `script/files.lua` | ソース | ファイル管理・走査 |
| guide.lua | `script/parser/guide.lua` | ソース | AST操作ユーティリティ |
