# 画面設計書 20-nimsuggestメイン画面

## 概要

本ドキュメントは、Nimコンパイラプロジェクトにおける`nimsuggest`ツールのメイン画面（CLI）の画面設計書です。IDE向けのコード補完、定義ジャンプ、参照検索などの機能を提供するサーバープロセスについて説明します。

### 本画面の処理概要

`nimsuggest`は、IDE（統合開発環境）やエディタにNim言語のインテリジェント機能を提供するツールです。プロジェクトファイルを解析し、TCPソケット、標準入出力、またはEPCプロトコルを通じてクエリに応答します。コード補完（sug）、定義ジャンプ（def）、参照検索（use）、構文ハイライト（highlight）、アウトライン（outline）などの機能を提供します。

**業務上の目的・背景**：現代のソフトウェア開発では、IDEによるコード補完や定義ジャンプなどの機能が不可欠です。nimsuggestは、VS Code、Emacs、Vim、Sublime Textなどの各種エディタがNimのインテリジェント機能を利用できるようにするバックエンドサーバーです。コンパイラのセマンティック解析機能を再利用し、正確な型情報と補完候補を提供します。

**画面へのアクセス方法**：ターミナルから以下のコマンドを実行します。
```
nimsuggest [options] projectfile.nim
```

**主要な操作・処理内容**：
1. プロジェクトファイルの初期コンパイル
2. TCPソケット/標準入出力/EPCでのリクエスト待機
3. sug（補完）コマンドの処理
4. def（定義ジャンプ）コマンドの処理
5. use（参照検索）コマンドの処理
6. con（コンテキスト情報）コマンドの処理
7. highlight（構文ハイライト）コマンドの処理
8. outline（アウトライン）コマンドの処理
9. chk（構文チェック）コマンドの処理
10. inlayHints（インレイヒント）コマンドの処理

**画面遷移**：
- 遷移元: シェル/ターミナルから直接起動、またはIDE/エディタから自動起動
- 遷移先: なし（常駐プロセスとして動作し、クエリに応答）
- 関連: Nimコンパイラのセマンティック解析機能を内部で使用

**権限による表示制御**：特別な権限制御はありません。ファイルシステムへの読み取り権限が必要です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 25 | Nimsuggest | 主機能 | IDE向け補完・定義ジャンプ等を提供するメイン処理 |
| 4 | セマンティック解析 | 補助機能 | コード解析のためのセマンティック解析呼び出し |
| 10 | モジュールグラフ管理 | 補助機能 | モジュール依存関係の管理 |

## 画面種別

CLIサーバープロセス（常駐型）

## URL/ルーティング

```
nimsuggest [options] projectfile.nim
```

コマンドラインオプション:
- `--port:PORT`: TCPポート番号（デフォルト: 6000）
- `--address:HOST`: バインドアドレス（デフォルト: 127.0.0.1）
- `--stdin`: 標準入出力モード
- `--epc`: Emacs EPCモード
- `--autobind`: 自動的に空きポートにバインド
- `--v1`, `--v2`, `--v3`, `--v4`: プロトコルバージョン
- `--refresh`: 自動リフレッシュを有効化
- `--maxresults:N`: 最大結果数
- `--tester`: テスターモード
- `--debug`: デバッグ出力を有効化
- `--log`: 詳細ログをnimsuggest.logに出力
- `--exceptionInlayHints:on|off`: 例外インレイヒントの有効/無効

サポートするコマンド:
- `sug`: コード補完候補を提供
- `con`: コンテキスト情報を取得
- `def`: 定義位置を検索
- `use`: 参照箇所を検索
- `dus`: 定義と使用箇所を検索
- `chk`: 構文・型チェック
- `mod`: モジュール情報
- `highlight`: 構文ハイライト情報
- `outline`: アウトライン情報
- `known`: ファイルが既知かどうか
- `project`: プロジェクトファイルパス
- `globalSymbols`: グローバルシンボル検索
- `declaration`: 宣言位置を検索
- `inlayHints`: インレイヒント情報

## 入出力項目

### 入力項目

| 項目名 | 型 | 必須 | 説明 |
|--------|-----|------|------|
| projectfile | path | はい | Nimプロジェクトファイル |
| command | string | はい | 実行するコマンド |
| file | path | はい | 対象ファイル |
| line | int | はい | 行番号（1始まり） |
| col | int | はい | 列番号（0始まり） |
| dirtyfile | path | いいえ | 未保存内容を含む一時ファイル |

### 出力項目

| 項目名 | 型 | 説明 |
|--------|-----|------|
| section | string | 結果セクション（sug, def, use等） |
| symkind | string | シンボル種別 |
| qualifiedPath | array | 完全修飾パス |
| filePath | string | ファイルパス |
| forth | string | 型情報 |
| line | int | 行番号 |
| column | int | 列番号 |
| doc | string | ドキュメント文字列 |
| quality | int | 品質スコア |
| prefix | string | プレフィックスマッチ情報 |

## 表示項目

| 項目名 | 説明 |
|--------|------|
| ポート番号 | autobind使用時に出力されるポート番号 |
| ヘルプ | コマンドヘルプ |
| 結果行 | クエリ結果（タブ区切り） |

## イベント仕様

### 1-サーバー起動

```
nimsuggest --port:6000 project.nim
```

1. コマンドライン引数を解析
2. プロジェクトファイルを初期コンパイル
3. TCPソケットでリクエストを待機
4. リクエストごとに処理を実行

### 2-補完リクエスト

```
sug file.nim:10:5
```

1. ファイル位置を解析
2. セマンティック解析を実行
3. 補完候補を収集
4. 結果を返却

### 3-定義ジャンプリクエスト

```
def file.nim:10:5
```

1. ファイル位置を解析
2. シンボルの定義位置を検索
3. 結果を返却

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

本コマンドはデータベースを使用しません。

### ファイル操作詳細

| 操作 | 対象ファイル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 読み取り | *.nim | READ | Nimソースファイルの解析 |
| 読み取り | *.nims | READ | NimScriptファイルの解析 |
| 読み取り | *.cfg | READ | 設定ファイルの解析 |
| 書き込み | nimsuggest.log | WRITE | ログ出力（--log使用時） |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 発生条件 |
|-------------|------|---------------|---------|
| MSG001 | 情報 | 6000 | autobindでポート出力 |
| MSG002 | 情報 | usage: sug\|con\|def\|use... | ヘルプ表示 |
| MSG003 | エラー | cannot find file: <path> | プロジェクトファイルが見つからない |
| MSG004 | 結果 | <tab区切り結果> | クエリ結果 |

## 例外処理

| 例外 | 発生条件 | 対処 |
|------|---------|------|
| ファイル未検出 | プロジェクトファイルが存在しない | 正しいパスを指定 |
| ポート競合 | 指定ポートが使用中 | 別のポートを指定、または--autobindを使用 |
| 構文エラー | ソースコードに構文エラー | エラー情報を返却して続行 |

## 備考

- nimsuggestはバックグラウンドプロセスとして動作し、IDEから自動的に起動される
- プロトコルバージョン4が最新（inlayHintsをサポート）
- dirtyfileオプションで未保存ファイルの補完が可能
- `--refresh`オプションで自動的にソースの変更を検出

---

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

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

### 推奨読解順序

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

nimsuggestで使用される主要なデータ構造を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | nimsuggest.nim | `nimsuggest/nimsuggest.nim` | L91-97: Mode、CachedMsg、CachedMsgs型定義 |
| 1-2 | nimsuggest.nim | `nimsuggest/nimsuggest.nim` | L99-109: グローバル変数（gPort、gAddress、gMode等） |
| 1-3 | nimsuggest.nim | `nimsuggest/nimsuggest.nim` | L53-90: Usage定数（ヘルプテキスト） |

**読解のコツ**: Modeはnimsuggestの動作モード（stdin、tcp、epc等）を定義しています。

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

nimsuggestのメイン処理を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | nimsuggest.nim | `nimsuggest/nimsuggest.nim` | L1298-1301: isMainModule（エントリーポイント） |
| 2-2 | nimsuggest.nim | `nimsuggest/nimsuggest.nim` | handleCmdLine関数（L758-783）: コマンドライン処理 |
| 2-3 | nimsuggest.nim | `nimsuggest/nimsuggest.nim` | mainCommand関数（L622-668）: メインコマンド処理 |

**主要処理フロー**:
1. **L1299**: `handleCmdLine(newIdentCache(), newConfigRef())`でコマンドライン処理
2. **L758-769**: NimProgオブジェクトの初期化
3. **L777-783**: モジュールグラフの作成とmainCommandの呼び出し

#### Step 3: コマンド処理を理解する

各コマンド（sug、def、use等）の処理を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | nimsuggest.nim | `nimsuggest/nimsuggest.nim` | execCmd関数（L494-571）: コマンド実行 |
| 3-2 | nimsuggest.nim | `nimsuggest/nimsuggest.nim` | executeNoHooksV3関数（L1066-1296）: V3プロトコルの実行 |
| 3-3 | nimsuggest.nim | `nimsuggest/nimsuggest.nim` | mainThread関数（L582-617）: メインスレッド処理 |

**主要処理フロー**:
- **L517-545**: コマンド名をパースしてideCmdを設定
- **L546-570**: ファイル位置を解析してexecuteを呼び出し
- **L1112-1295**: 各コマンド（def、use、highlight等）の処理

#### Step 4: 通信処理を理解する

TCP/stdin/EPCの通信処理を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | nimsuggest.nim | `nimsuggest/nimsuggest.nim` | replTcp関数（L406-425）: TCP通信 |
| 4-2 | nimsuggest.nim | `nimsuggest/nimsuggest.nim` | replStdin関数（L385-400）: 標準入出力通信 |
| 4-3 | nimsuggest.nim | `nimsuggest/nimsuggest.nim` | replEpc関数（L444-492）: EPC通信 |

**主要処理フロー**:
- **L406-425**: TCPソケットでリクエストを受信し、結果を送信
- **L385-400**: 標準入力からコマンドを読み取り、標準出力に結果を出力
- **L444-492**: EPCプロトコルでEmacs等と通信

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

```
nimsuggest projectfile.nim
    │
    ├─ handleCmdLine(cache, conf)
    │      │
    │      ├─ processCmdLine()           # コマンドライン解析
    │      │
    │      └─ mainCommand(graph)
    │             │
    │             ├─ compileProject()    # 初期コンパイル
    │             │
    │             ├─ createThread(replTcp/replStdin/replEpc)
    │             │      │
    │             │      └─ requests.send(cmd)
    │             │
    │             └─ mainThread(graph)
    │                    │
    │                    └─ [ループ]
    │                           │
    │                           ├─ requests.tryRecv()
    │                           │
    │                           └─ execCmd(req, graph)
    │                                  │
    │                                  ├─ ideSug: suggestResult()
    │                                  ├─ ideDef: findSymData()
    │                                  ├─ ideUse: listUsages()
    │                                  ├─ ideHighlight: ...
    │                                  └─ ideOutline: ...
```

### データフロー図

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

projectfile.nim ─────────▶ compileProject() ────────────▶ ModuleGraph

クエリ(sug file:10:5) ───▶ execCmd() ──────────────────▶ Suggest結果

    ├─ TCP (port:6000)
    ├─ stdin
    └─ EPC

dirtyfile.nim ───────────▶ setDirtyFile() ──────────────▶ 未保存内容の解析

                              │
                              ▼
                         results.send()
                              │
                              ▼
                         toSocket/toStdout/toEpc
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| nimsuggest.nim | `nimsuggest/nimsuggest.nim` | ソース | nimsuggestメイン処理 |
| sexp.nim | `nimsuggest/sexp.nim` | ソース | S式パーサー（EPC用） |
| procmonitor.nim | `nimsuggest/procmonitor.nim` | ソース | プロセス監視 |
| suggest.nim | `compiler/suggest.nim` | ソース | 補完候補生成（コンパイラ内） |
| sigmatch.nim | `compiler/sigmatch.nim` | ソース | シグネチャマッチング |
| modules.nim | `compiler/modules.nim` | ソース | モジュール管理 |
| sempass2.nim | `compiler/sempass2.nim` | ソース | セマンティック解析パス2 |
| suggestsymdb.nim | `compiler/suggestsymdb.nim` | ソース | シンボルデータベース |
