# 機能設計書 77-データダンプ

## 概要

本ドキュメントは、clojure-lsp の API として提供される `dump` 関数の機能設計を記述する。この関数はプロジェクトの解析データ（クラスパス、ソースパス、依存グラフ、clj-kondo 解析データ等）をエクスポートする機能を提供する。

### 本機能の処理概要

**業務上の目的・背景**：プロジェクトの解析状態をデバッグや外部ツールとの連携のために出力する必要がある場合がある。この機能は clojure-lsp が保持する全ての解析データを構造化された形式（EDN または JSON）で出力し、トラブルシューティングや他ツールへのデータ連携に活用できる。

**機能の利用シーン**：デバッグ、解析結果の外部ツールへの連携、プロジェクト構造の可視化、CI/CD でのメタデータ出力などで利用される。

**主要な処理内容**：
1. プロジェクトの解析
2. 解析データベースからデータを抽出
3. 指定された形式（EDN/JSON）でシリアライズ
4. フィルタキーによる出力項目の絞り込み

**関連システム・外部連携**：外部ツールとのデータ連携（出力データの利用側）。

**権限による制御**：呼び出し元プロセスのファイルシステム権限に依存。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 該当なし | 該当なし | 該当なし | 本プロジェクトは LSP サーバー実装であり UI 画面は存在しない |

## 機能種別

データ取得 / エクスポート

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| :project-root | java.io.File | No | プロジェクトルートディレクトリ | nil または存在する File |
| :analysis | Map | No | 解析タイプ設定 | :type (:project-only, :project-and-shallow-analysis, :project-and-full-dependencies) |
| :output | Map | No | 出力設定 | :format (:edn/:json)、:filter-keys (キーワードリスト) |
| :settings | Map | No | clojure-lsp 設定マップ | nil または map? |

### 入力データソース

- 解析データベース
- プロジェクト設定

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| :result-code | Integer | 0: 成功、1: エラー |
| :message-fn | Function | 結果を文字列化する関数 |
| :result | Map/String | ダンプデータ（:edn の場合は Map、:json の場合は JSON 文字列） |

### ダンプデータの構造

| フィールド | 型 | 説明 |
|-----------|-----|------|
| :project-root | String | プロジェクトルートパス |
| :source-paths | Collection | ソースパスのリスト |
| :classpath | Collection | クラスパスのリスト |
| :analysis | Map | clj-kondo 解析結果 |
| :dep-graph | Map | 名前空間の依存グラフ |
| :diagnostics | Map | 診断情報 |
| :settings | Map | 適用された設定 |
| :clj-kondo-settings | Map | clj-kondo 設定 |
| :findings | Map | clj-kondo の findings |

### 出力先

- 戻り値としてダンプデータを返却

## 処理フロー

### 処理シーケンス

```
1. パラメータバリデーション
2. プロジェクト解析
   └─ :analysis :type に応じた解析実行（デフォルト: project-only）
3. データ抽出
   └─ db->dump-data でデータベースから必要なデータを抽出
4. フィルタリング
   └─ :filter-keys 指定時は該当キーのみ抽出
5. シリアライズ
   └─ :format に応じて EDN または JSON に変換
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{パラメータ有効?}
    B -->|No| C[AssertionError]
    B -->|Yes| D[API セットアップ]
    D --> E[プロジェクト解析]
    E --> F[db->dump-data でデータ抽出]
    F --> G{filter-keys 指定?}
    G -->|Yes| H[指定キーのみ抽出]
    G -->|No| I[全データ保持]
    H --> J{format = :json?}
    I --> J
    J -->|Yes| K[JSON にシリアライズ]
    J -->|No| L[EDN として返却]
    K --> M[結果返却]
    L --> M
    M --> N[終了]
    C --> N
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-77-1 | デフォルト解析 | :analysis 未指定時は :project-only | 常時 |
| BR-77-2 | デフォルトフォーマット | :format 未指定時は :edn | 常時 |
| BR-77-3 | フィルタ適用 | :filter-keys 指定時は該当キーのみ出力 | :filter-keys が指定された場合 |
| BR-77-4 | 全データ出力 | :filter-keys 未指定時は全データを出力 | :filter-keys が未指定の場合 |

### 計算ロジック

出力フォーマット：
- `:edn`: Clojure のネイティブデータ形式
- `:json`: JSON 形式（cheshire ライブラリで生成）

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 該当なし | 該当なし | 該当なし | RDB は使用しない |

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

atom によるインメモリデータベースからデータを抽出。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| AssertionError | バリデーションエラー | パラメータ不正 | 有効なパラメータを渡す |
| result-code: 1 | フォーマットエラー | サポートされていない :format | :edn または :json を指定 |

### リトライ仕様

リトライ機構は実装されていない。

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

RDB を使用しないため、トランザクション管理は不要。

## パフォーマンス要件

- プロジェクトサイズと解析データ量に依存
- 大規模プロジェクトでは出力データが大きくなる可能性

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

- 出力データにプロジェクトパスや設定情報が含まれる
- 機密情報を含む可能性があるため取り扱い注意

## 備考

- 実験的機能として位置づけられている
- 外部ツールとの連携やデバッグ用途を想定

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | db.clj | `lib/src/clojure_lsp/db.clj` | データベース構造 |

**読解のコツ**: initial-db の各キーがダンプ対象となる。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | api.clj | `lib/src/clojure_lsp/api.clj` | dump 関数定義 |

**主要処理フロー**:
1. **293-345行目**: `dump` 関数定義、docstring と事前条件

#### Step 3: 内部 API 実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | internal_api.clj | `lib/src/clojure_lsp/internal_api.clj` | dump* の実装 |

**主要処理フロー**:
- **456-470行目**: db->dump-data でデータ抽出とフィルタリング
- **472-486行目**: dump* でフォーマット変換と結果生成

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

```
api/dump
    |
    +-- internal-api/dump
            |
            +-- build-components
            |
            +-- dump*
                    |
                    +-- setup-api!
                    |
                    +-- dynamic-setup-project-analysis! (:project-only)
                    |
                    +-- db->dump-data
                    |       |
                    |       +-- select-keys (基本データ抽出)
                    |       +-- diagnostics-by-uri (診断取得)
                    |       +-- filter-keys 適用
                    |
                    +-- json/generate-string (JSON の場合)
```

### データフロー図

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

{:output                 api/dump                            {:result-code 0/1
   {:format :edn         |                                    :message-fn fn
    :filter-keys [...]}} v                                    :result {...}}
        |           dynamic-setup-project-analysis!            |
        |                |                                     |
        +-------------> db->dump-data                          |
                        |                                      |
                        v                                      |
                   filter-keys 適用                            |
                        |                                      |
                        v                                      |
                   format 変換                                 |
                        |                                      |
              +---------+---------+                            |
              |                   |                            |
              v                   v                            |
        :edn              :json                                |
              |                   |                            |
              v                   v                            |
        Map 返却          JSON 文字列返却 -------------------> 結果返却
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| api.clj | `lib/src/clojure_lsp/api.clj` | ソース | 公開 API 定義 |
| internal_api.clj | `lib/src/clojure_lsp/internal_api.clj` | ソース | 内部実装 |
| db.clj | `lib/src/clojure_lsp/db.clj` | ソース | データベース定義 |
| api_test.clj | `lib/test/clojure_lsp/api_test.clj` | テスト | API テスト |
