# バッチ設計書 20-debugger.lua

## 概要

本ドキュメントは、デバッガ接続を初期化するスクリプト `debugger.lua` のバッチ設計書です。

### 本バッチの処理概要

このスクリプトは、Lua言語サーバーの開発モードにおいて、VSCode拡張機能「actboy168.lua-debug」デバッガへの接続を初期化します。開発者がLua言語サーバー自体のコードをステップ実行でデバッグするための機能を提供します。

**業務上の目的・背景**：Lua言語サーバーは複雑なLuaコードを処理しており、開発中のバグ調査や動作確認のためにデバッグ機能が必要です。このスクリプトにより、VSCodeのLuaデバッガ拡張機能を使用して、言語サーバー自体のLuaコードをブレークポイント設定、変数検査、ステップ実行などでデバッグできるようになります。

**バッチの実行タイミング**：言語サーバーの起動時（main.lua内）にDEVELOPモードが有効な場合にのみ実行されます。通常のプロダクション使用時には実行されません。

**主要な処理内容**：
1. DEVELOPモードの確認
2. ユーザーのVSCode拡張機能ディレクトリの検索
3. actboy168.lua-debug拡張機能の最新バージョンの特定
4. デバッガエントリポイントの読み込みと初期化
5. 指定ポート（DBGPORT）での接続待機

**前後の処理との関連**：main.luaから呼び出され、言語サーバー本体の起動前にデバッガ接続を確立します。DBGWAITが設定されている場合は、デバッガ接続まで待機します。

**影響範囲**：開発環境でのデバッグセッションのみ。プロダクション環境には影響しません。

## バッチ種別

開発支援・デバッグ初期化

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（開発モード起動時） |
| 実行時刻 | - |
| 実行曜日 | - |
| 実行日 | - |
| トリガー | main.lua起動時（DEVELOP=true時のみ） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| DEVELOP = true | 開発モードが有効であること |
| actboy168.lua-debug拡張機能のインストール | VSCodeにLuaデバッガ拡張機能がインストール済みであること |
| HOME環境変数の設定 | ユーザーのホームディレクトリが特定できること |

### 実行可否判定

DEVELOPグローバル変数がtrueでない場合、スクリプトは即座にreturnして何も行いません。また、デバッガ拡張機能が見つからない場合もログを出力して終了します。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| DEVELOP | boolean | Yes | false | 開発モードフラグ |
| DBGPORT | integer | Yes | - | デバッガ接続ポート |
| DBGWAIT | boolean | No | false | デバッガ接続待機フラグ |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| HOME / USERPROFILE | 環境変数 | ユーザーのホームディレクトリ |
| .vscode/extensions/ | ディレクトリ | VSCode拡張機能のインストール先 |
| actboy168.lua-debug-*/script/debugger.lua | Luaファイル | デバッガのエントリポイント |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| ログ | テキスト | デバッガ起動状況のログ |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | なし（ログのみ） |
| 出力先 | - |
| 文字コード | - |
| 区切り文字 | - |

## 処理フロー

### 処理シーケンス

```
1. DEVELOPモード確認
   └─ DEVELOPがfalseなら即座にreturn

2. ファイルシステムモジュール読み込み
   └─ bee.filesystemをrequire

3. ホームディレクトリ取得
   └─ USERPROFILE（Windows）またはHOME（Unix）環境変数

4. 拡張機能ディレクトリの検索
   └─ .vscode、.vscode-insiders、.vscode-server-insidersを検索

5. actboy168.lua-debug拡張機能の検索
   └─ 各extensionsディレクトリ内で「actboy168.lua-debug-」で始まるディレクトリを検索

6. バージョンソート
   └─ セマンティックバージョンで降順ソート
   └─ 最新バージョンを選択

7. デバッガの初期化
   └─ debugger.luaをloadfile
   └─ dbg:startで接続開始
   └─ 127.0.0.1:DBGPORT に接続

8. 待機処理（オプション）
   └─ DBGWAITがtrueの場合、dbg:event('wait')で待機
```

### フローチャート

```mermaid
flowchart TD
    A[debugger.lua読み込み] --> B{DEVELOP?}
    B -->|false| C[return]
    B -->|true| D[HOME取得]
    D --> E{HOME存在?}
    E -->|No| F[エラーログ出力]
    F --> C
    E -->|Yes| G[VSCodeディレクトリ検索]
    G --> H[lua-debug拡張検索]
    H --> I{拡張見つかった?}
    I -->|No| J[デバッグログ出力]
    J --> C
    I -->|Yes| K[バージョンソート]
    K --> L[最新バージョン選択]
    L --> M[debugger.lua読み込み]
    M --> N[dbg:start]
    N --> O{DBGWAIT?}
    O -->|Yes| P[dbg:event wait]
    O -->|No| Q[完了]
    P --> Q
```

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

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

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | データベースは使用しない |

### テーブル別操作詳細

データベース操作は行いません。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | HOME未設定 | 環境変数が取得できない | 環境変数を設定する |
| - | 拡張機能未インストール | lua-debug拡張が見つからない | VSCodeにインストールする |
| - | デバッガ起動失敗 | loadfileまたはstart失敗 | ログを確認し拡張を再インストール |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし |
| リトライ間隔 | - |
| リトライ対象エラー | - |

### 障害時対応

デバッガ接続に失敗しても、言語サーバー本体の起動は継続されます（main.luaでxpcallでラップされているため）。

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | なし |
| コミットタイミング | - |
| ロールバック条件 | - |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1回（起動時） |
| 目標処理時間 | 数百ミリ秒以内 |
| メモリ使用量上限 | デバッガ依存 |

## 排他制御

排他制御は不要です。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| デバッグログ | 検索時 | 「Search extensions at: パス」 |
| エラーログ | HOME未設定時 | 「Cannot find home directory」 |
| デバッグログ | 拡張未発見時 | 「Cant find "actboy168.lua-debug"」 |
| デバッグログ | 起動成功時 | 「Debugger startup, listen port: ポート」 |
| デバッグログ | 起動成功時 | 「Debugger args: アドレス、ルート、パス、cpath」 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| なし | - | - |

## 備考

- このスクリプトはプロジェクトルートの `debugger.lua` に配置されています
- main.luaからxpcall(dofile, log.debug, ...)で呼び出されます
- 検索対象のVSCode拡張機能ディレクトリ：
  - `.vscode/extensions`
  - `.vscode-insiders/extensions`
  - `.vscode-server-insiders/extensions`
- バージョン番号のパース形式: `actboy168.lua-debug-X.Y.Z`
- バージョンは数値化して比較: `a * 1000000 + b * 1000 + c`
- デバッガのcpath: `/runtime/win64/lua54/?.dll;/runtime/win64/lua54/?.so`
- デバッガのpath: `/script/?.lua`
- 使用するコマンドラインオプション：
  - `--develop=true`: DEVELOPを有効化
  - `--dbgport=ポート番号`: 接続ポートを指定
  - `--dbgwait=true`: デバッガ接続まで待機
