# 帳票設計書 7-ワークスペースシンボル検索結果

## 概要

本ドキュメントは、serve-dのワークスペースシンボル検索結果機能の設計を記述する。ワークスペース全体からクエリに一致するシンボルをファジー検索し、結果一覧を出力する帳票である。

### 本帳票の処理概要

ワークスペースシンボル検索結果は、ワークスペース全体のインデックスからクエリ文字列にファジーマッチするシンボルを検索し、一致するシンボル情報の一覧をLSPクライアントに返す帳票である。

**業務上の目的・背景**：大規模なD言語プロジェクトにおいて、開発者がプロジェクト全体からシンボルを素早く検索できるようにする。ファジー検索により、正確な名前を覚えていなくても部分一致で目的のシンボルを発見できる。エディタの「Go to Symbol in Workspace」機能に必要なデータを提供する。

**帳票の利用シーン**：エディタのコマンドパレットやシンボル検索ダイアログからクエリを入力した際に、ワークスペース全体のインデックスからマッチするシンボルが検索される。開発者はリストからシンボルを選択して該当ファイル・位置にジャンプできる。

**主要な出力内容**：
1. シンボル名（name）
2. シンボル種別（kind）
3. ファイル位置（location: uri + range）
4. コンテナ名（containerName: モジュール名）

**帳票の出力タイミング**：エディタからworkspace/symbolリクエストを受信した際にレスポンスとして返却される。

**帳票の利用者**：D言語開発者（ワークスペース全体のシンボル検索を行う開発者）

## 帳票種別

シンボルレポート（LSPレスポンス）

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| - | シンボル検索ダイアログ | LSP `workspace/symbol` | クエリ入力時に自動リクエスト |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | JSON-RPC（LSPプロトコル） |
| 用紙サイズ | N/A（デジタル出力） |
| 向き | N/A |
| ファイル名 | N/A（ストリーム出力） |
| 出力方法 | workspace/symbolレスポンス |
| 文字コード | UTF-8 |

### PDF固有設定

N/A

### Excel固有設定

N/A

## 帳票レイアウト

### レイアウト概要

SymbolInformation配列として検索結果を返す。

```
┌─────────────────────────────────────┐
│  SymbolInformation[]                 │
├─────────────────────────────────────┤
│  [0] name: string                    │
│      kind: SymbolKind                │
│      location:                       │
│        uri: DocumentUri              │
│        range: TextRange              │
│      containerName: string (モジュール名) │
│  [1] ...                             │
└─────────────────────────────────────┘
```

### ヘッダー部

N/A（リクエストパラメータのqueryフィールドが検索条件）

### 明細部

| No | 項目名 | 説明 | データ取得元 | 表示形式 | 列幅 |
|----|-------|------|-------------|---------|-----|
| 1 | name | シンボル名 | DefinitionElement.name（IndexComponent経由） | 文字列 | - |
| 2 | kind | シンボル種別 | makeSymbolInfoEx -> convertFromDscannerType | SymbolKind列挙値 | - |
| 3 | location.uri | ファイルURI | fileName.uriFromFile | URI文字列 | - |
| 4 | location.range | シンボル位置 | def.line - 1（行のみ、列は0） | TextRange | - |
| 5 | containerName | コンテナ名（モジュール名） | ModuleRef mod（IndexComponentから取得） | 文字列 | - |

### フッター部

N/A

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| インデックス有効 | workspace.config.d.enableIndex == true | Yes |
| IndexComponent有効 | backend.has!IndexComponent(folderPath)がtrue | Yes |
| importable | def.isImportableがtrue | Yes |
| 非標準ライブラリ | mod.isStdLibがfalse | Yes |
| ファジーマッチ | def.name.fuzzyMatchesString(params.query)がtrue | Yes |

### ソート順

| 優先度 | 項目 | 昇順/降順 |
|-------|------|---------|
| 1 | IndexComponentの走査順（インデックス内部順） | - |

### 改ページ条件

N/A

## データベース参照仕様

### 参照テーブル一覧

本帳票はデータベースを使用しない。インメモリインデックスを使用する。

| テーブル名 | 用途 | 結合条件 |
|-----------|------|---------|
| N/A | - | - |

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

N/A

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| location.range.start.line | def.line - 1（0-indexed変換） | - | 行39 |
| containerName | containerName未設定時はModuleRef modで代替 | - | 行41-42 |
| fuzzyMatch | fuzzymatch.fuzzyMatchesString(params.query) | - | 行36 |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[workspace/symbolリクエスト受信] --> B[全ワークスペースをループ]
    B --> C{enableIndex && IndexComponent有効?}
    C -->|No| B
    C -->|Yes| D[IndexComponent.iterateAll呼び出し]
    D --> E{isImportable && !isStdLib?}
    E -->|No| D
    E -->|Yes| F{fuzzyMatchesString?}
    F -->|No| D
    F -->|Yes| G[makeSymbolInfoExでSymbolInformation生成]
    G --> H{containerName未設定?}
    H -->|Yes| I[モジュール名をcontainerNameに設定]
    H -->|No| J[結果配列に追加]
    I --> J
    J --> D
    D --> K[SymbolInformation配列を返却]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| インデックス無効 | enableIndexがfalseまたはIndexComponentが利用不可 | なし | 該当ワークスペースをスキップ |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | ワークスペース全体で数千〜数万シンボル |
| 目標出力時間 | ファジー検索によるフィルタリングで応答 |
| 同時出力数上限 | 制限なし（iterateAll全件走査） |

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

- インメモリインデックスのみ参照し、外部リソースへのアクセスは行わない
- 標準ライブラリのシンボルは除外される

## 備考

- fuzzymatchモジュールによるファジー検索を使用（行24）
- 標準ライブラリ（isStdLib）のシンボルは結果から除外される（行35）
- containerNameが未設定の場合、モジュール名（ModuleRef）を代用する（行41-42）
- 全ワークスペースを横断して検索する（行27-48）

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | protoext.d | `source/served/lsp/protoext.d` | SymbolInformationEx構造体（行202-222）とdowncast()メソッド |

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | symbol_search.d | `source/served/commands/symbol_search.d` | provideWorkspaceSymbols関数（行21-49）: workspace/symbolハンドラ |

**主要処理フロー**:
1. **行27**: 全ワークスペースをループ
2. **行29-30**: enableIndex設定確認とIndexComponent取得
3. **行33-45**: iterateAllで全定義を走査し、フィルタ条件適用
4. **行36**: fuzzyMatchesStringによるファジー検索
5. **行40**: makeSymbolInfoExでシンボル情報生成（downcast()で標準形式に変換）

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

```
provideWorkspaceSymbols(params)                   [symbol_search.d:21]
    |
    +-- [foreach workspace]
            +-- backend.has!IndexComponent()       [symbol_search.d:30]
            +-- backend.get!IndexComponent()       [symbol_search.d:32]
            +-- indexer.iterateAll(delegate)        [symbol_search.d:33]
            |       +-- fuzzyMatchesString()        [symbol_search.d:36]
            |       +-- makeSymbolInfoEx()          [symbol_search.d:40]
            |       |       +-- convertFromDscannerType()
            |       +-- .downcast()                 [symbol_search.d:40]
            +-- infos.data返却                      [symbol_search.d:48]
```

### データフロー図

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

workspace/symbolリクエスト ──> provideWorkspaceSymbols() ──> SymbolInformation[]
(query文字列)

IndexComponent ──────────────> iterateAll()              ──> (ModuleRef, fileName, DefinitionElement)
(インメモリインデックス)

DefinitionElement ───────────> fuzzyMatchesString()       ──> フィルタ済みシンボル
                               makeSymbolInfoEx()
                               .downcast()
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| symbol_search.d | `source/served/commands/symbol_search.d` | ソース | ワークスペースシンボル検索の主処理 |
| protoext.d | `source/served/lsp/protoext.d` | ソース | SymbolInformationEx構造体定義 |
| types.d | `source/served/types.d` | ソース | 共通型定義 |
| extension.d | `source/served/extension.d` | ソース | LSPサーバー拡張機能 |
