# 画面設計書 22-nimsuggest def（定義ジャンプ）

## 概要

本ドキュメントは、Nimsuggestツールの`def`（定義ジャンプ）サブコマンドに関する画面設計書である。

### 本画面の処理概要

nimsuggest defコマンドは、IDE/エディタ連携において、カーソル位置のシンボルが定義されている場所を特定し、その位置情報を返す「Go to Definition」機能を提供する。

**業務上の目的・背景**：大規模なNimプロジェクトでは、変数、関数、型などが様々なモジュールに分散して定義されている。開発者がコードを読み解く際に、シンボルの定義元に素早くジャンプできることは、コード理解と保守性向上に不可欠である。この機能により、エディタ上でシンボルを選択するだけで定義位置に移動でき、コードナビゲーションの効率を大幅に向上させる。

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

**主要な操作・処理内容**：
1. クライアントからdefコマンドとファイル位置情報（ファイルパス、行番号、カラム番号）を受信
2. 指定位置のシンボルを特定
3. シンボルデータベースからそのシンボルの定義位置を検索
4. 定義元のファイルパス、行番号、カラム番号を返却

**画面遷移**：
- 遷移元: エディタ/IDEからの定義ジャンプリクエスト
- 遷移先: 結果はクライアントに返却され、エディタは定義位置にカーソルを移動

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 25 | Nimsuggest | 主機能 | ideDefコマンドによるシンボル定義位置の検索 |

## 画面種別

コマンドライン / サーバーレスポンス（定義位置情報）

## URL/ルーティング

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

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

# stdinモード
nimsuggest --stdin project.nim
# 標準入力からコマンドを送信
```

## 入出力項目

### 入力項目

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

### 出力項目

| 項目名 | 型 | 説明 |
|--------|-----|------|
| section | IdeCmd | `ideDef`固定 |
| symkind | TSymKind | シンボルの種類（skProc, skVar, skType等） |
| qualifiedPath | seq[string] | 完全修飾パス |
| filePath | string | 定義ファイルのパス |
| forth | string | 型シグネチャ |
| line | int | 定義位置の行番号 |
| column | int | 定義位置のカラム番号 |
| doc | string | ドキュメントコメント |

## 表示項目

定義位置情報として以下の情報がクライアントに返される:

| 表示項目 | 説明 | 例 |
|---------|------|-----|
| ファイルパス | 定義元ファイルの絶対パス | `/path/to/system.nim` |
| 行番号 | 定義位置の行番号 | `1234` |
| カラム番号 | 定義位置のカラム番号 | `5` |
| シンボル名 | 定義されたシンボルの名前 | `echo` |
| シンボル種別 | proc/var/type/field等 | `skProc` |
| 型情報 | シンボルの型シグネチャ | `proc (s: string)` |

## イベント仕様

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

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

### 2-定義位置の検索

1. 指定位置からシンボルデータを検索（`findSymData`関数）
2. 見つかったシンボルの定義情報（`sym.info`）を取得
3. `suggestResult`関数で結果を送信

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

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

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

本コマンドはデータベースを使用せず、コンパイル済みのシンボルデータベース（`SuggestFileSymbolDatabase`）を参照する。

## メッセージ仕様

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

## 例外処理

| 例外状況 | 処理内容 |
|---------|---------|
| ファイルが存在しない | エラーメッセージを返却 |
| 位置情報が無効 | 空の結果を返却 |
| シンボルが見つからない | 空の結果を返却（エラーなし） |
| 定義が別ファイルにある | 該当ファイルのパスと位置を返却 |

## 備考

- defコマンドはideDefとして処理され、シンボルの定義位置を返す
- 結果のsectionがideDefの場合は定義位置、それ以外（ideUse等）の場合は使用位置を示す
- プロトコルバージョン3以上では、`executeNoHooksV3`内の行1113-1116で処理される
- declarationコマンドとの違い: defは定義位置、declarationは宣言位置を返す（実装と宣言が異なる場合）

---

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

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

### 推奨読解順序

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

シンボル情報とその管理構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | suggestsymdb.nim | `compiler/suggestsymdb.nim` | `SuggestFileSymbolDatabase`型、シンボルDB構造 |
| 1-2 | ast.nim | `compiler/ast.nim` | `PSym.info`（定義位置情報）の構造 |
| 1-3 | lineinfos.nim | `compiler/lineinfos.nim` | `TLineInfo`型（ファイル/行/列情報） |

**読解のコツ**: PSym.infoフィールドがシンボルの定義位置を保持しており、defコマンドではこれを返却する。

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

コマンド処理の起点を特定する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | nimsuggest.nim | `nimsuggest/nimsuggest.nim` | `execCmd`関数、行519でideDefを設定 |

**主要処理フロー**:
1. **行519**: `of "def": conf.ideCmd = ideDef` - コマンドの識別
2. **行570**: `execute(conf.ideCmd, ...)` - 実行処理の呼び出し

#### Step 3: 定義検索処理を理解する

v3プロトコルでの定義検索ロジックを追跡する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | nimsuggest.nim | `nimsuggest/nimsuggest.nim` | `executeNoHooksV3`関数、行1113-1116 |
| 3-2 | nimsuggest.nim | `nimsuggest/nimsuggest.nim` | `findSymData`関数、行856-866, 881-886 |

**主要処理フロー**:
- **行1113-1116**: ideDef処理ブロック
```nim
of ideDef:
  let s = graph.findSymData(file, line, col)
  if not s.isNil:
    graph.suggestResult(s.sym, s.sym.info)
```
- **行881-886**: ファイルと位置からシンボルを検索

#### Step 4: 結果出力を理解する

結果の生成と送信方法を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | nimsuggest.nim | `nimsuggest/nimsuggest.nim` | `suggestResult`関数、行905-916 |

**主要処理フロー**:
- **行905-916**: シンボルと位置情報からSuggestオブジェクトを構築
- **行907-910**: sectionの決定（定義位置ならideDef、使用位置ならideUse）

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

```
execCmd (行494)
    │
    ├─ parseIdent - "def"コマンド解析 (行519)
    │
    └─ execute (行296) / executeNoHooks (行245)
           │
           └─ executeNoHooksV3 (行1066)
                  │
                  ├─ recompilePartially (行1110) - 必要時のみ
                  │
                  ├─ findSymData (行881)
                  │      │
                  │      └─ fileSymbols - シンボルDB参照
                  │             │
                  │             └─ deduplicateSymInfoPair - 重複排除
                  │
                  └─ suggestResult (行905)
                         │
                         └─ symToSuggest - Suggestオブジェクト生成
```

### データフロー図

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

クライアント              nimsuggestサーバー               クライアント
    │                         │                              │
    │  def "file":line:col    │                              │
    │────────────────────────>│                              │
    │                         │                              │
    │                    execCmd()                           │
    │                         │                              │
    │                    parseコマンド                       │
    │                         │                              │
    │                    executeNoHooksV3()                  │
    │                         │                              │
    │                    findSymData()                       │
    │                         │                              │
    │                    シンボルDB検索                      │
    │                         │                              │
    │                    s.sym.info取得                      │
    │                         │                              │
    │                    suggestResult()                     │
    │                         │                              │
    │                         │  Suggest(ideDef)             │
    │<───────────────────────────────────────────────────────│
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| nimsuggest.nim | `nimsuggest/nimsuggest.nim` | ソース | メインエントリ、ideDef処理 |
| suggestsymdb.nim | `compiler/suggestsymdb.nim` | ソース | シンボルデータベース管理 |
| suggest.nim | `compiler/suggest.nim` | ソース | Suggest型定義、シンボル情報変換 |
| ast.nim | `compiler/ast.nim` | ソース | PSym型定義（シンボル） |
| lineinfos.nim | `compiler/lineinfos.nim` | ソース | TLineInfo型定義（位置情報） |
| modulegraphs.nim | `compiler/modulegraphs.nim` | ソース | モジュールグラフ管理 |
