# 機能設計書 72-vimspector

## 概要

本ドキュメントは、space-vimの+tools/vimspectorレイヤーが提供するデバッガー連携機能について、その設計と実装を詳細に記述する。

### 本機能の処理概要

**業務上の目的・背景**：
ソフトウェア開発においてデバッグは不可欠な作業である。従来、Vimユーザーはデバッグ作業のためにIDEに切り替えるか、コマンドラインデバッガーを使用する必要があった。vimspectorは、Vim内でグラフィカルなデバッグ体験を提供し、ブレークポイント設定、ステップ実行、変数監視などの機能を統合する。これにより、開発者はエディタを離れることなく効率的なデバッグ作業が可能となる。

**機能の利用シーン**：
- プログラムの実行中にブレークポイントで停止し、変数の値を確認する
- ステップイン・ステップオーバー・ステップアウトによるコード実行の追跡
- コールスタックの確認とスタックフレーム間の移動
- ウォッチ式による特定の変数・式の監視
- 複数言語（Python、JavaScript、C/C++、Go等）のデバッグ

**主要な処理内容**：
1. vimspectorプラグインの遅延読み込み（タイマーによる900ms後のロード）
2. Debug Adapter Protocol (DAP) を介したデバッガーとの通信
3. デバッグUI（変数ウィンドウ、コールスタック、ブレークポイント一覧）の表示
4. ブレークポイントの設定・解除
5. ステップ実行制御（continue、step in、step out、step over）

**関連システム・外部連携**：
- 外部プラグイン: puremourning/vimspector
- Debug Adapter Protocol (DAP) 対応デバッガー（各言語のデバッグアダプター）
- 言語固有のデバッグサーバー（debugpy、node-debug等）

**権限による制御**：
本機能に権限による制御は存在しない。+tools/vimspectorレイヤーを有効化することで全ユーザーが利用可能となる。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | デバッグ画面 | 主画面 | 変数、コールスタック、ブレークポイント、出力を表示 |
| - | ソースコード画面 | 参照画面 | ブレークポイント位置、現在の実行行を表示 |

## 機能種別

デバッグ機能 / 外部ツール連携

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| launch.json | JSON | Yes | デバッグ構成ファイル | JSON形式、vimspector仕様に準拠 |
| ブレークポイント位置 | Number | No | 行番号 | 有効な行番号 |

### 入力データソース

- プロジェクトルートの.vimspector.jsonファイル（デバッグ構成）
- ユーザーによるブレークポイント設定操作
- ~/.spacevimにおけるレイヤー設定（+tools/vimspectorの有効化）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 変数一覧 | UI Window | ローカル変数・グローバル変数の値表示 |
| コールスタック | UI Window | 関数呼び出し履歴の表示 |
| ブレークポイント一覧 | UI Window | 設定されたブレークポイントの一覧 |
| 出力ログ | UI Window | デバッグ対象プログラムの標準出力 |

### 出力先

- Vimの分割ウィンドウ（デバッグUI）
- サインカラム（ブレークポイントマーカー）
- カーソルライン（現在の実行行ハイライト）

## 処理フロー

### 処理シーケンス

```
1. レイヤー有効化時、vimspectorプラグインを登録
   └─ 遅延読み込み設定（900msタイマー）
2. デバッグ開始コマンド実行
   └─ :call vimspector#Launch() または F5キー
3. デバッグ構成読み込み
   └─ .vimspector.jsonから設定を取得
4. デバッグアダプター起動
   └─ DAPサーバーとの接続確立
5. デバッグUI表示
   └─ 変数、コールスタック、出力ウィンドウを分割表示
6. ブレークポイントで停止時
   └─ 変数値更新、コールスタック更新、カーソル位置移動
```

### フローチャート

```mermaid
flowchart TD
    A[デバッグ開始] --> B[.vimspector.json読み込み]
    B --> C[デバッグアダプター起動]
    C --> D[プログラム実行開始]
    D --> E{ブレークポイント?}
    E -->|Yes| F[実行停止]
    F --> G[変数/スタック更新]
    G --> H{ユーザー操作}
    H -->|Continue| D
    H -->|Step| I[1ステップ実行]
    I --> E
    H -->|Stop| J[デバッグ終了]
    E -->|No| K{プログラム終了?}
    K -->|No| E
    K -->|Yes| J
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-72-1 | 遅延読み込み | 起動時間短縮のため900ms後にロード | speed_up_via_timer有効時 |
| BR-72-2 | DAP準拠 | Debug Adapter Protocolに準拠したデバッガーと通信 | 常時 |
| BR-72-3 | 設定ファイル必須 | デバッグ実行には.vimspector.jsonが必要 | デバッグ開始時 |

### 計算ロジック

本機能に独自の計算ロジックは存在しない（vimspectorプラグインに委譲）。

## データベース操作仕様

本機能にデータベース操作は存在しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 設定ファイル未検出 | .vimspector.jsonが存在しない | プロジェクトルートに設定ファイルを作成 |
| - | デバッグアダプター未インストール | 対象言語のDAPアダプターがない | :VimspectorInstall コマンドで導入 |
| - | 接続タイムアウト | デバッグサーバーに接続できない | ポート設定、ファイアウォールを確認 |

### リトライ仕様

デバッグアダプターへの接続失敗時、vimspectorがエラーメッセージを表示。手動での再試行が必要。

## トランザクション仕様

本機能にトランザクション処理は存在しない。

## パフォーマンス要件

- 遅延読み込みにより起動時間への影響を最小化（900ms後にバックグラウンドロード）
- デバッグセッション中はDAPプロトコルによる非同期通信

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

- デバッグ対象プログラムはローカル環境で実行される
- リモートデバッグ時はネットワーク経由での通信となるため、適切なファイアウォール設定が推奨される
- .vimspector.jsonに認証情報を含めないよう注意

## 備考

- vimspectorはpuremourning氏が開発・メンテナンスしている外部プラグイン
- Vim 8.1+またはNeoVim 0.4+が必要
- Python3サポートが必要

---

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

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

### 推奨読解順序

#### Step 1: パッケージ定義を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | packages.vim | `layers/+tools/vimspector/packages.vim` | プラグイン登録と遅延読み込みの条件分岐 |

**読解のコツ**: `g:spacevim.speed_up_via_timer`変数によって遅延読み込みの方式が切り替わる。タイマー有効時は`{ 'on': [] }`で即座にロードせず、900msのタイマーで`spacevim#defer#vimspector`関数を呼び出す。

**主要処理フロー**:
- **1-3行目**: タイマーによる遅延読み込み設定
- **4-6行目**: 通常ロード設定（タイマー無効時）

#### Step 2: 遅延読み込み関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | defer.vim | `core/autoload/spacevim/defer.vim` | 遅延読み込みの実装 |

**読解のコツ**: `spacevim#defer#vimspector`関数は内部で`s:lod`（load on demand）関数を呼び出し、vim-plugの`plug#load`を実行する。

**主要処理フロー**:
- **55-58行目**: `spacevim#defer#vimspector`関数 - vimspectorプラグインをロード
- **1-6行目**: `s:lod`関数 - vim-plugのプラグインロード処理

#### Step 3: 設定ファイルを確認する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | config.vim | `layers/+tools/vimspector/config.vim` | 追加設定の有無を確認（現状は空） |

**読解のコツ**: config.vimが空であることは、vimspectorプラグインがデフォルト設定で動作することを意味する。

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

```
~/.spacevim（ユーザー設定）
    │
    └─ Layer('+tools/vimspector')
           │
           ├─ packages.vim
           │      ├─ MP 'puremourning/vimspector'（プラグイン登録）
           │      └─ timer_start(900, 'spacevim#defer#vimspector')
           │
           └─ config.vim（空）

core/autoload/spacevim/defer.vim
    │
    └─ spacevim#defer#vimspector()
           └─ s:lod('vimspector')
                  └─ plug#load('vimspector')
```

### データフロー図

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

Vim起動              ───▶  タイマー設定(900ms)    ───▶  （待機）
                                ↓
900ms経過            ───▶  vimspectorロード      ───▶  プラグイン利用可能
                                ↓
F5/デバッグ開始      ───▶  .vimspector.json読込  ───▶  デバッグUI表示
                                ↓
ブレークポイント設定  ───▶  DAPサーバー通信       ───▶  実行停止/変数表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| packages.vim | `layers/+tools/vimspector/packages.vim` | ソース | プラグイン登録と遅延読み込み設定 |
| config.vim | `layers/+tools/vimspector/config.vim` | ソース | 追加設定（現状空） |
| defer.vim | `core/autoload/spacevim/defer.vim` | ソース | 遅延読み込み実装 |
