# 機能設計書 89-Babashka Pod

## 概要

本ドキュメントは、clojure-lspのBabashka Pod機能の設計書である。Babashkaスクリプトからclojure-lspのAPI機能を呼び出すためのPodインターフェースを提供する。

### 本機能の処理概要

この機能は、Babashka Podプロトコルを実装し、Babashkaスクリプトからclojure-lspのAPI（analyze-project-and-deps!, clean-ns!, diagnostics, format!, rename!, dump）を呼び出すことを可能にする。Transit+JSON形式でデータをシリアライズし、bencode形式でメッセージを交換する。

**業務上の目的・背景**：Babashkaは高速起動のClojureスクリプティング環境として広く使用されている。clojure-lspのコード解析・変換機能をBabashkaスクリプトから利用可能にすることで、CI/CDパイプラインやカスタムツールでの活用が容易になる。

**機能の利用シーン**：
- Babashkaスクリプトからのプロジェクト解析
- CI/CDパイプラインでのコードフォーマットチェック
- スクリプトベースの自動リファクタリング
- カスタム開発ツールの構築

**主要な処理内容**：
1. 環境変数 `BABASHKA_POD=true` の検出
2. Podプロトコルでのメッセージループ開始
3. describe オペレーションでAPI情報を返却
4. invoke オペレーションでAPI関数を実行
5. 結果のTransit+JSON形式でのシリアライズ

**関連システム・外部連携**：
- Babashka: Podクライアント
- bencode: メッセージフォーマット
- Transit: データシリアライゼーション

**権限による制御**：権限による制御は行わない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 該当なし | 該当なし | 該当なし | CLIから自動的にPodモードで起動 |

## 機能種別

連携機能 / Pod インターフェース

## 入力仕様

### 入力パラメータ

#### describe オペレーション
入力パラメータ不要。

#### invoke オペレーション

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| var | String | Yes | 呼び出す関数の完全修飾名 | api-vars に存在すること |
| args | String | Yes | Transit+JSON形式の引数 | 有効なTransit形式 |

### 提供されるAPI関数

| 関数名 | 説明 |
|--------|------|
| clojure-lsp.api/analyze-project-and-deps! | プロジェクトと依存関係の解析 |
| clojure-lsp.api/analyze-project-only! | プロジェクトのみの解析 |
| clojure-lsp.api/clean-ns! | 名前空間のクリーンアップ |
| clojure-lsp.api/diagnostics | 診断情報の取得 |
| clojure-lsp.api/format! | コードフォーマット |
| clojure-lsp.api/rename! | シンボルのリネーム |
| clojure-lsp.api/dump | プロジェクトデータのダンプ |

### 入力データソース

- 標準入力（stdin）: bencode形式のPodメッセージ

## 出力仕様

### 出力データ

#### describe レスポンス

| 項目名 | 型 | 説明 |
|--------|-----|------|
| format | String | データ形式（"transit+json"） |
| namespaces | Vector | 提供される名前空間と関数の一覧 |
| id | String | リクエストID |

#### invoke レスポンス

| 項目名 | 型 | 説明 |
|--------|-----|------|
| value | String | Transit+JSON形式の戻り値 |
| id | String | リクエストID |
| status | Vector | ステータス（["done"] または ["done" "error"]） |

### 出力先

- 標準出力（stdout）: bencode形式のPodレスポンス

## 処理フロー

### 処理シーケンス

```
1. 起動時の環境検出
   └─ BABASHKA_POD=true を確認

2. Podループ開始
   └─ bencode メッセージを読み取り

3. オペレーション判定
   └─ describe または invoke

4. 処理実行
   └─ describe: API情報返却
   └─ invoke: 関数実行

5. レスポンス送信
   └─ bencode 形式で出力
```

### フローチャート

```mermaid
flowchart TD
    A[起動] --> B{BABASHKA_POD=true?}
    B -->|No| C[通常起動]
    B -->|Yes| D[Podループ開始]
    D --> E[メッセージ読み取り]
    E --> F{EOF?}
    F -->|Yes| G[終了]
    F -->|No| H{op?}
    H -->|describe| I[API情報返却]
    H -->|invoke| J[関数検索]
    J --> K{関数あり?}
    K -->|Yes| L[関数実行]
    K -->|No| M[エラー返却]
    L --> N{成功?}
    N -->|Yes| O[結果シリアライズ]
    N -->|No| P[エラーシリアライズ]
    I --> Q[レスポンス送信]
    O --> Q
    P --> Q
    M --> Q
    Q --> E
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-89-1 | Pod検出 | BABASHKA_POD=true の場合にPodモードで起動 | 環境変数の値 |
| BR-89-2 | Transit形式 | データはTransit+JSON形式でシリアライズ | 常時 |
| BR-89-3 | java.io.File ハンドラ | java.io.File をカスタムハンドラで処理 | ファイルパス引数 |
| BR-89-4 | message-fn 除去 | 戻り値から :message-fn を除去 | 関数戻り値に含まれる場合 |

### 計算ロジック

Transitハンドラ:
- java.io.File はカスタムの読み取り/書き込みハンドラで処理
- 文字列パスとFile オブジェクトの相互変換を行う

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | EOF | 標準入力が閉じられた | ループ終了 |
| error | 関数未発見 | var が api-vars に存在しない | エラーレスポンス送信 |
| error | 実行時エラー | 関数実行中に例外発生 | ex-message と ex-data を送信 |

### リトライ仕様

リトライは行わない。エラー発生時はエラーレスポンスを返却して次のメッセージを待機。

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

該当なし

## パフォーマンス要件

- 各リクエストは独立して処理
- API関数のパフォーマンスは各機能に依存

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

- 標準入力/出力を通じた通信のためプロセス間のセキュリティに依存
- ファイルシステムへのアクセスは呼び出される関数の権限に従う

## 備考

- Babashka から `(require '[babashka.pods :as pods])` と `(pods/load-pod "clojure-lsp")` で使用
- clojure-lsp.api 名前空間として公開される

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | api-vars | `lib/src/pod/clojure_lsp/api.clj` | 提供されるAPI関数のマッピング |

**読解のコツ**: api-vars マップがBabashkaから呼び出し可能な関数を定義

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | main.clj | `cli/src/clojure_lsp/main.clj` | Pod モード検出と起動 |

**主要処理フロー**:
1. **158-161行目**: `BABASHKA_POD` 環境変数の検出
2. **201行目**: `pod/run-pod` の呼び出し

#### Step 3: Podプロトコル実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | api.clj | `lib/src/pod/clojure_lsp/api.clj` | Podプロトコルの実装 |

**主要処理フロー**:
- **77-84行目**: `api-vars` - 公開API関数のマッピング
- **86-141行目**: `run-pod` - メインループ
- **99-107行目**: `describe` オペレーション処理
- **109-138行目**: `invoke` オペレーション処理

#### Step 4: Transit シリアライゼーションを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | api.clj | `lib/src/pod/clojure_lsp/api.clj` | Transit ハンドラ |

**主要処理フロー**:
- **29-35行目**: java.io.File のカスタムハンドラ
- **37-49行目**: クライアント側ハンドラ登録コード生成
- **61-66行目**: `read-transit` 関数
- **68-75行目**: `write-transit` 関数

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

```
main/-main
    │
    └─ main/parse
           │
           └─ (pod? = true)
                  │
                  └─ handle-action!
                         │
                         └─ pod/run-pod
                                │
                                ├─ (loop)
                                │    │
                                │    ├─ bencode/read-bencode
                                │    │
                                │    ├─ (case op)
                                │    │    │
                                │    │    ├─ :describe ──▶ namespace/vars 情報返却
                                │    │    │
                                │    │    └─ :invoke ───▶ api-vars から関数実行
                                │    │                        │
                                │    │                        └─ (apply f args)
                                │    │
                                │    └─ bencode/write-bencode
                                │
                                └─ (recur)
```

### データフロー図

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

stdin (bencode) ────▶ read-bencode ────────▶ message マップ
                              │
                              ▼
                       op 判定
                              │
                              ├─ :describe ───▶ namespaces/vars 情報
                              │
                              └─ :invoke ─────▶ read-transit (args)
                                      │
                                      ▼
                               api 関数実行
                                      │
                                      ▼
                               write-transit (result)
                                      │
                                      ▼
stdout (bencode) ◀──── write-bencode ◀─── response マップ
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| api.clj | `lib/src/pod/clojure_lsp/api.clj` | ソース | Podプロトコル実装 |
| main.clj | `cli/src/clojure_lsp/main.clj` | ソース | エントリーポイント |
| api.clj | `lib/src/clojure_lsp/api.clj` | ソース | 公開API関数 |
| pod_test.clj | `cli/pod-test/clojure_lsp/pod_test.clj` | テスト | Pod統合テスト |
