# 画面設計書 24-nimsuggest con（コンテキスト）

## 概要

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

### 本画面の処理概要

nimsuggest conコマンドは、IDE/エディタ連携において、カーソル位置のシンボルに関するコンテキスト情報（型情報、ドキュメント、シグネチャなど）を取得する機能を提供する。

**業務上の目的・背景**：コード編集中に、変数や関数の型情報、ドキュメントコメントを即座に確認できることは、開発効率向上に大きく寄与する。この機能は、エディタのホバー表示（マウスオーバー時のツールチップ）やインレイヒントの基盤となり、コードを読み解く際の理解を支援する。

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

**主要な操作・処理内容**：
1. クライアントからconコマンドとファイル位置情報を受信
2. 指定位置のシンボルを特定
3. シンボルの型情報、ドキュメント、シグネチャを収集
4. コンテキスト情報として整形して返却

**画面遷移**：
- 遷移元: エディタ/IDEからのコンテキスト情報リクエスト
- 遷移先: 結果はクライアントに返却され、ホバーやツールチップとして表示

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 25 | Nimsuggest | 主機能 | ideConコマンドによるコンテキスト情報取得 |
| 13 | 型システム | 補助機能 | 型情報の取得処理 |

## 画面種別

コマンドライン / サーバーレスポンス（コンテキスト情報）

## URL/ルーティング

```
# コマンド形式
con "filepath.nim":line:col
con "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 | `ideCon`固定 |
| symkind | TSymKind | シンボルの種類 |
| qualifiedPath | seq[string] | 完全修飾パス |
| filePath | string | 定義ファイルのパス |
| forth | string | 型シグネチャ |
| line | int | 定義位置の行番号 |
| column | int | 定義位置のカラム番号 |
| doc | string | ドキュメントコメント |

## 表示項目

コンテキスト情報として以下の情報がクライアントに返される:

| 表示項目 | 説明 | 例 |
|---------|------|-----|
| シンボル名 | シンボルの完全修飾名 | `system.echo` |
| 型情報 | シンボルの型シグネチャ | `proc (varargs[string])` |
| ドキュメント | docコメントの内容 | `Prints arguments to stdout` |
| 定義位置 | シンボルが定義されている位置 | `system.nim:1234:5` |

## イベント仕様

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

1. クライアントからconコマンドを受信
2. `execCmd`関数でコマンドをパース（行518: `of "con": conf.ideCmd = ideCon`）
3. ファイル、行、カラム情報を抽出
4. `execute`関数を呼び出してコンテキスト取得処理を実行

### 2-コンテキスト情報の取得

1. 対象ファイルをダーティマーク
2. 部分再コンパイルを実行
3. 指定位置のシンボル情報を収集
4. 結果を送信

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

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

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

## メッセージ仕様

| メッセージ種別 | メッセージ | 発生条件 |
|---------------|----------|---------|
| 成功 | コンテキスト情報（1行以上） | 正常にシンボル情報が取得できた場合 |
| 情報 | 空の結果 | シンボルが見つからない場合 |

## 例外処理

| 例外状況 | 処理内容 |
|---------|---------|
| ファイルが存在しない | エラーメッセージを返却 |
| シンボルが見つからない | 空の結果を返却 |
| コンパイルエラー | エラー情報を収集して返却 |

## 備考

- conコマンドはsugコマンドと同様に部分コンパイルをトリガーする
- 行1150-1156でsugとconが同じブロックで処理される
- 現在のNimsuggestはCapabilitiesに"con"を含む（行136-137）

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | suggest.nim | `compiler/suggest.nim` | Suggest型、コンテキスト情報の構造 |
| 1-2 | types.nim | `compiler/types.nim` | 型情報の表現 |

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

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

**主要処理フロー**:
1. **行518**: `of "con": conf.ideCmd = ideCon`

#### Step 3: コンテキスト取得処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | nimsuggest.nim | `nimsuggest/nimsuggest.nim` | 行1150-1156 - ideSug/ideCon処理 |

**主要処理フロー**:
- **行1150-1156**: ideSug/ideCon処理ブロック
```nim
of ideSug, ideCon:
  # ideSug/ideCon performs partial build of the file
  graph.markDirtyIfNeeded(file.string, fileIndex)
  graph.recompilePartially(fileIndex)
  let m = graph.getModule fileIndex
  incl m, sfDirty
```

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

```
execCmd (行494)
    │
    ├─ parseIdent - "con"コマンド解析 (行518)
    │
    └─ executeNoHooksV3 (行1066)
           │
           ├─ markDirtyIfNeeded
           │
           ├─ recompilePartially
           │
           └─ (結果はセマンティック解析経由で収集)
```

### データフロー図

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

クライアント              nimsuggestサーバー               クライアント
    │                         │                              │
    │  con "file":line:col    │                              │
    │────────────────────────>│                              │
    │                         │                              │
    │                    部分コンパイル                      │
    │                         │                              │
    │                    コンテキスト収集                    │
    │                         │                              │
    │                         │  Suggest(型/doc)             │
    │<───────────────────────────────────────────────────────│
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| nimsuggest.nim | `nimsuggest/nimsuggest.nim` | ソース | ideCon処理 |
| suggest.nim | `compiler/suggest.nim` | ソース | コンテキスト情報収集 |
| types.nim | `compiler/types.nim` | ソース | 型情報の表現・出力 |
