# 画面設計書 23-nimsuggest use（参照検索）

## 概要

本ドキュメントは、Nimsuggestツールの`use`（参照検索）サブコマンドに関する画面設計書である。

### 本画面の処理概要

nimsuggest useコマンドは、IDE/エディタ連携において、カーソル位置のシンボルがプロジェクト全体で使用されている箇所を検索し、すべての使用位置を返す「Find All References」機能を提供する。

**業務上の目的・背景**：リファクタリングや影響範囲調査において、特定のシンボル（変数、関数、型など）がどこで使用されているかを把握することは非常に重要である。この機能により、シンボルの名前変更前の影響確認、未使用コードの検出、依存関係の把握が可能となり、安全なコード修正を支援する。

**画面へのアクセス方法**：nimsuggestサーバーが起動した状態で、クライアント（エディタ/IDE）から以下のコマンド形式でリクエストを送信する。
- TCP接続の場合: `use "file.nim":line:col`
- stdin/EPCモードでも同様のコマンド形式を使用
- 通常、エディタ上での「Find All References」操作（Shift+F12等）をトリガーとする

**主要な操作・処理内容**：
1. クライアントからuseコマンドとファイル位置情報を受信
2. 指定位置のシンボルを特定
3. プロジェクト全体のシンボルデータベースを走査
4. 同一シンボルの使用箇所をすべて収集
5. 各使用位置の情報（ファイル、行、カラム）を返却

**画面遷移**：
- 遷移元: エディタ/IDEからの参照検索リクエスト
- 遷移先: 結果はクライアントに返却され、参照一覧として表示される

**権限による表示制御**：本ツールはCLI/サーバーベースであり、権限による表示制御は存在しない。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 25 | Nimsuggest | 主機能 | ideUseコマンドによるシンボル使用箇所の検索 |

## 画面種別

コマンドライン / サーバーレスポンス（参照位置一覧）

## URL/ルーティング

```
# コマンド形式
use "filepath.nim":line:col
use "filepath.nim";"dirtyfile.nim":line:col

# TCPモード
nimsuggest --port:6000 project.nim
# その後、ソケット接続して上記コマンドを送信
```

## 入出力項目

### 入力項目

| 項目名 | 型 | 必須 | 説明 |
|--------|-----|------|------|
| file | string | Yes | 対象ファイルのパス |
| dirtyfile | string | No | 編集中の一時ファイルパス |
| line | int | Yes | 行番号（1始まり） |
| col | int | Yes | カラム番号（0始まり） |

### 出力項目（複数行で返却）

| 項目名 | 型 | 説明 |
|--------|-----|------|
| section | IdeCmd | `ideUse`固定 |
| symkind | TSymKind | シンボルの種類 |
| qualifiedPath | seq[string] | 完全修飾パス |
| filePath | string | 使用箇所のファイルパス |
| line | int | 使用箇所の行番号 |
| column | int | 使用箇所のカラム番号 |

## 表示項目

参照位置一覧として以下の情報がクライアントに返される:

| 表示項目 | 説明 | 例 |
|---------|------|-----|
| ファイルパス | 使用箇所のファイル | `/path/to/mymodule.nim` |
| 行番号 | 使用箇所の行番号 | `45` |
| カラム番号 | 使用箇所のカラム番号 | `12` |
| シンボル名 | 参照されているシンボル名 | `myFunction` |

## イベント仕様

### 1-useコマンド受信

1. クライアントからuseコマンドを受信
2. `execCmd`関数でコマンドをパース（行520: `of "use": conf.ideCmd = ideUse`）
3. ファイル、行、カラム情報を抽出
4. `execute`関数を呼び出して参照検索処理を実行

### 2-参照位置の検索

1. 必要に応じてプロジェクト全体を再コンパイル（`recompilePartially`）
2. 指定位置からシンボルを特定（`findSymData`）
3. `suggestSymbolsIter`を使用してプロジェクト全体を走査
4. 同一シンボルの使用箇所を収集（`symbolEqual`で比較）
5. 重複を排除（`deduplicateSymInfoPair`）
6. 各使用位置を`suggestResult`で送信

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| - | - | - | データベースへの更新は発生しない（メモリ内処理のみ） |

## メッセージ仕様

| メッセージ種別 | メッセージ | 発生条件 |
|---------------|----------|---------|
| 成功 | 参照位置リスト（複数行） | 正常に使用箇所が見つかった場合 |
| 情報 | 空の結果 | 使用箇所がない場合（定義のみ） |
| エラー | `found no symbol at this position` | 指定位置でシンボルが見つからない場合 |

## 例外処理

| 例外状況 | 処理内容 |
|---------|---------|
| ファイルが存在しない | エラーメッセージを返却 |
| シンボルが見つからない | エラーメッセージを出力 |
| 再コンパイルが必要 | 自動的に再コンパイルを実行 |

## 備考

- useコマンドは完全なプロジェクトコンパイルを必要とするため、他のコマンドより時間がかかる場合がある
- プロトコルバージョン3以上では、より効率的な増分検索が行われる
- `dus`コマンド（definitions and usages）はuse機能の拡張版

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | suggestsymdb.nim | `compiler/suggestsymdb.nim` | シンボルデータベース構造 |
| 1-2 | nimsuggest.nim | `nimsuggest/nimsuggest.nim` | SymInfoPair型、シンボル比較 |

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | nimsuggest.nim | `nimsuggest/nimsuggest.nim` | 行520でideUseを設定 |

**主要処理フロー**:
1. **行520**: `of "use": conf.ideCmd = ideUse`

#### Step 3: 参照検索処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | nimsuggest.nim | `nimsuggest/nimsuggest.nim` | 行1126-1134 - ideUse処理 |

**主要処理フロー**:
- **行1126-1134**: ideUse/ideDus処理ブロック
```nim
of ideUse, ideDus:
  let symbol = graph.findSymData(file, line, col)
  if not symbol.isNil:
    var res: seq[SymInfoPair] = @[]
    for s in graph.suggestSymbolsIter:
      if s.sym.symbolEqual(symbol.sym):
        res.add(s)
    for s in res.deduplicateSymInfoPair():
      graph.suggestResult(s.sym, s.info)
```

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

```
execCmd (行494)
    │
    ├─ parseIdent - "use"コマンド解析 (行520)
    │
    └─ executeNoHooksV3 (行1066)
           │
           ├─ recompilePartially (必要時)
           │
           ├─ findSymData - 対象シンボル特定
           │
           ├─ suggestSymbolsIter - 全シンボル走査
           │
           ├─ symbolEqual - シンボル比較
           │
           ├─ deduplicateSymInfoPair - 重複排除
           │
           └─ suggestResult - 各結果送信
```

### データフロー図

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

クライアント              nimsuggestサーバー               クライアント
    │                         │                              │
    │  use "file":line:col    │                              │
    │────────────────────────>│                              │
    │                         │                              │
    │                    シンボル特定                        │
    │                         │                              │
    │                    プロジェクト全体走査                │
    │                         │                              │
    │                    一致シンボル収集                    │
    │                         │                              │
    │                    重複排除                            │
    │                         │                              │
    │                         │  Suggest[] (複数)            │
    │<───────────────────────────────────────────────────────│
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| nimsuggest.nim | `nimsuggest/nimsuggest.nim` | ソース | ideUse処理、シンボル走査 |
| suggestsymdb.nim | `compiler/suggestsymdb.nim` | ソース | シンボルデータベース |
| modulegraphs.nim | `compiler/modulegraphs.nim` | ソース | suggestSymbolsIter提供 |
