# バッチ設計書 20-debug-cli

## 概要

本ドキュメントは、clojure-lspプロジェクトにおけるデバッグ用CLIスクリプト生成バッチ（debug-cli）の設計仕様を記載したものです。

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

本バッチは、デバッグ用のCLI実行スクリプト（clojure-lsp / clojure-lsp.bat）を生成します。このスクリプトはUberJARをラップし、cider-nreplやclj-async-profilerを使用したデバッグ機能を有効にした状態でclojure-lspを起動します。

**業務上の目的・背景**：clojure-lspの開発において、パフォーマンス分析やリモートデバッグが必要な場合があります。本バッチで生成されるスクリプトは、デバッグ用UberJAR（cider-nrepl、clj-async-profiler含む）を特定のJVMオプション付きで起動します。これにより、開発者は実行中のLSPサーバーに接続してデバッグやプロファイリングを行うことができます。スタックトレースの省略防止やアタッチ許可などのJVMオプションが事前設定されています。

**バッチの実行タイミング**：開発者がデバッグ機能付きのclojure-lspスクリプトを使用したい場合に手動で実行されます。パフォーマンス問題の調査時やnREPLを使った対話的開発時に使用されます。

**主要な処理内容**：
1. cliモジュールのtargetディレクトリをクリーン
2. :debugおよび:testエイリアスを含むbasisでUberJARを作成
3. devディレクトリのソースもJARに含める
4. AOTコンパイルを実行
5. UberJARをラップする実行スクリプト（clojure-lsp / clojure-lsp.bat）を生成
6. 生成したスクリプトをプロジェクトルートへ移動

**前後の処理との関連**：本バッチは単独で実行可能です。内部的にcli-debug-jarと同様のUberJAR生成処理を行った後、deps-binを使用して実行スクリプトを生成します。

**影響範囲**：cli/targetディレクトリ配下が再作成され、プロジェクトルートにclojure-lsp（またはclojure-lsp.bat）スクリプトが出力されます。既存のスクリプトは上書きされます。

## バッチ種別

ビルドタスク（デバッグ用CLIスクリプト生成）

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時 |
| 実行時刻 | 任意 |
| 実行曜日 | 任意 |
| 実行日 | 任意 |
| トリガー | 手動 |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Babashka | Babashkaがインストールされていること |
| Clojure CLI | Clojure CLIツールがインストールされていること |
| cli/deps.edn | cliディレクトリにdeps.ednが存在すること |
| lib/deps.edn | libディレクトリにdeps.ednが存在すること |
| CLOJURE_LSP_VERSION | lib/resources/CLOJURE_LSP_VERSIONファイルが存在すること |
| 十分なメモリ | AOTコンパイルとUberJAR作成に2GB以上のヒープメモリ |

### 実行可否判定

特別な実行可否判定はありません。前提条件を満たしていれば実行可能です。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| なし | - | - | - | 本バッチはパラメータを受け取りません |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| cli/deps.edn | EDN | cliモジュールの依存関係定義ファイル |
| lib/deps.edn | EDN | libモジュールの依存関係定義ファイル（:extraで参照） |
| cli/src/ | Clojureソース | cliモジュールのソースコード |
| cli/resources/ | リソース | cliモジュールのリソースファイル |
| cli/dev/ | Clojureソース | デバッグ用ソースコード |
| lib/src/ | Clojureソース | libモジュールのソースコード |
| lib/resources/ | リソース | libモジュールのリソースファイル |
| lib/resources/CLOJURE_LSP_VERSION | テキスト | バージョン情報ファイル |
| cider-nrepl | 依存ライブラリ | nREPLミドルウェア |
| clj-async-profiler | 依存ライブラリ | 非同期プロファイラ |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| clojure-lsp（Unix）/ clojure-lsp.bat（Windows） | シェルスクリプト/バッチファイル | デバッグ用CLI実行スクリプト |
| cli/target/clojure-lsp-standalone.jar | UberJAR | デバッグ用スタンドアロンJARファイル |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | clojure-lsp（Unix）/ clojure-lsp.bat（Windows） |
| 出力先 | プロジェクトルート（./) |
| 文字コード | UTF-8 |
| 区切り文字 | N/A |

## 処理フロー

### 処理シーケンス

```
1. バッチ起動（bb debug-cli）
   └─ make/debug-cli関数の呼び出し

2. ビルドタスク実行
   └─ cliディレクトリでclojure -T:build debug-cliを実行

3. standalone-aot-jar処理（内部呼び出し）
   └─ targetディレクトリ削除
   └─ :debug :testエイリアス有効化
   └─ devディレクトリをextra-dirsに追加

4. ソースコピー
   └─ src, resourcesをtarget/classesへコピー

5. AOTコンパイル
   └─ b/compile-cljでClojureソースをコンパイル
   └─ JVMオプション: -Xmx2g -server

6. UberJAR作成
   └─ b/uberによるUberJAR作成
   └─ メインクラス: clojure-lsp.main
   └─ 出力: cli/target/clojure-lsp-standalone.jar

7. 実行スクリプト生成
   └─ deps-binによるスクリプト生成
   └─ JVMオプション設定:
      - -XX:-OmitStackTraceInFastThrow
      - -Djdk.attach.allowAttachSelf=true
      - -Dclojure.core.async.go-checking=true
      - -Xmx3g -server

8. ファイル移動
   └─ cli/clojure-lsp（.bat）をプロジェクトルートへ移動
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[cliディレクトリへ移動]
    B --> C[clojure -T:build debug-cli 実行]
    C --> D[standalone-aot-jar呼び出し]
    D --> E[targetディレクトリ削除]
    E --> F[":debug :test エイリアス有効化"]
    F --> G["devディレクトリをextra-dirsに追加"]
    G --> H[ソースコピー・AOTコンパイル]
    H --> I[UberJAR作成]
    I --> J["Generating bin..." 出力]
    J --> K[deps-binでスクリプト生成]
    K --> L[デバッグ用JVMオプション設定]
    L --> M[clojure-lspスクリプトをルートへ移動]
    M --> N[バッチ終了]
```

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

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

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| なし | - | - | 本バッチはデータベースを使用しません |

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

本バッチはデータベースを使用しません。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | FileNotFound | deps.ednが存在しない | cliディレクトリにdeps.ednを配置 |
| - | FileNotFound | ソースファイルが存在しない | cli/src, lib/srcにソースコードを配置 |
| - | CompilationError | Clojureソースのコンパイルエラー | ソースコードのエラーを修正 |
| - | ProcessError | Clojure CLIが見つからない | Clojure CLIをインストール |
| - | OutOfMemoryError | ヒープメモリ不足 | ヒープサイズを増加（-Xmx2g以上） |
| - | IOException | ディスク容量不足 | ディスク容量を確保 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし（手動再実行） |
| リトライ間隔 | - |
| リトライ対象エラー | - |

### 障害時対応

エラー発生時は標準エラー出力にエラーメッセージが表示されます。コンパイルエラーの場合は、エラーメッセージに従ってソースコードを修正してください。OutOfMemoryErrorの場合は、JAVA_OPTS環境変数でヒープサイズを増加させてください。

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | N/A（ファイル操作のみ） |
| コミットタイミング | - |
| ロールバック条件 | - |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1回の実行で1 UberJARファイル + 1スクリプトファイル生成 |
| 目標処理時間 | 150秒以内 |
| メモリ使用量上限 | AOTコンパイルのため2GB以上必要（-Xmx2g設定） |

## 排他制御

同時実行は想定されていません。同じディレクトリで複数のビルドプロセスが同時に実行される場合、ファイル競合が発生する可能性があります。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | ビルド開始時 | "Building uberjar..." |
| 進捗ログ | スクリプト生成時 | "Generating bin..." |
| 進捗ログ | 処理中 | Clojure CLIの標準出力 |
| エラーログ | エラー発生時 | 例外スタックトレース、コンパイルエラー |

## 監視・アラート

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

本バッチはローカル開発環境で実行されるため、専用の監視・アラート設定はありません。

## 備考

- 生成されるスクリプトには以下のJVMオプションが埋め込まれます
  - -XX:-OmitStackTraceInFastThrow（スタックトレースの省略を防止）
  - -Djdk.attach.allowAttachSelf=true（自己アタッチ許可、プロファイラ用）
  - -Dclojure.core.async.go-checking=true（core.asyncのデバッグチェック有効化）
  - -Xmx3g -server（ヒープサイズ3GB、サーバーモード）
- deps-bin（com.github.ericdallo/deps-bin）を使用してスクリプトを生成します
- cider-nrepl（バージョン0.58.0）が含まれます
- clj-async-profiler（バージョン1.6.2）が含まれます
- cli/devディレクトリの開発用ソースコードもJARに含まれます
- Windows環境ではclojure-lsp.bat、Unix環境ではclojure-lspが生成されます
- バージョン情報はlib/resources/CLOJURE_LSP_VERSIONファイルから読み込まれます
- 生成後、スクリプトはmv-here関数によりプロジェクトルートへ移動されます
- skip-realignオプションがtrueに設定されています
