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

## 概要

本ドキュメントは、clojure-lspのCLI（コマンドラインインターフェース）から実行するプロジェクトデータダンプ機能の設計書である。プロジェクトの解析結果、依存グラフ、設定情報などを出力する実験的機能である。

### 本機能の処理概要

この機能は、CLIコマンド `clojure-lsp dump` を通じて、Clojureプロジェクトの内部データをEDNまたはJSON形式で出力する。クラスパス、ソースパス、依存グラフ、clj-kondo解析結果、設定情報などの包括的なプロジェクト情報を取得できる。

**業務上の目的・背景**：開発者がclojure-lspの内部動作を理解したり、プロジェクトの解析結果を他のツールで活用したりする際に、内部データへのアクセスが必要となる場合がある。本機能は実験的な機能として、プロジェクトの解析データを外部に出力する手段を提供する。

**機能の利用シーン**：
- clojure-lspのデバッグ・トラブルシューティング
- プロジェクト構造の可視化
- 外部ツールとの連携（解析結果の再利用）
- 依存関係グラフの分析
- 診断情報の一括取得

**主要な処理内容**：
1. コマンドライン引数の解析（出力形式、フィルタキーなど）
2. プロジェクトの解析
3. 内部データの収集と整形
4. 指定形式（EDN/JSON）での出力

**関連システム・外部連携**：
- clj-kondo: 解析結果の主要データソース
- 外部ツール: 出力されたデータを利用可能

**権限による制御**：権限による制御は行わない。読み取り権限のみ必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 該当なし | 該当なし | 該当なし | CLIから実行されるため画面は存在しない |

## 機能種別

データ出力 / デバッグ機能（実験的）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| --project-root, -p | Path | No | プロジェクトルートパス | 存在するディレクトリであること |
| --output, -o | EDN | No | 出力設定（:format, :filter-keys など） | 有効なEDNマップ |
| --settings, -s | EDN | No | 追加設定（EDN形式） | 有効なEDNマップ |
| --analysis | EDN | No | 解析タイプの指定 | :type キーに有効な解析タイプ |

### 出力オプション詳細

| オプションキー | 型 | 説明 |
|---------------|-----|------|
| :format | Keyword | 出力形式（:edn または :json、デフォルト: :edn） |
| :filter-keys | Vector | 出力するキーのリスト（省略時は全キー） |
| :canonical-paths | Boolean | ファイルパスを正規化するか |

### 入力データソース

- ファイルシステム上のClojureソースファイル
- clj-kondo解析結果
- clojure-lsp設定ファイル

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| classpath | Vector | プロジェクトのクラスパス |
| source-paths | Set | ソースパスの一覧 |
| project-root | String | プロジェクトルートのパス |
| analysis | Map | clj-kondo解析結果 |
| dep-graph | Map | 名前空間の依存グラフ |
| settings | Map | 最終的な設定 |
| findings | Vector | clj-kondo診断結果 |
| kondo-config | Map | clj-kondo設定 |
| diagnostics | Map | URI別の診断情報 |

### 出力先

- 標準出力: EDNまたはJSON形式のデータ

## 処理フロー

### 処理シーケンス

```
1. コマンドライン引数の解析
   └─ 出力オプションの取得

2. コンポーネントの初期化
   └─ CLILogger、APIProducerの生成

3. プロジェクト解析の実行
   └─ デフォルトは :project-only タイプ

4. ダンプデータの収集
   └─ db->dump-data で必要なキーを選択

5. 出力形式の変換
   └─ :edn または :json へ変換

6. 結果の出力
   └─ 標準出力に出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始: dump コマンド実行] --> B[引数解析]
    B --> C[出力オプション取得]
    C --> D[コンポーネント初期化]
    D --> E[プロジェクト解析]
    E --> F[ダンプデータ収集]
    F --> G{filter-keys指定?}
    G -->|Yes| H[指定キーのみ抽出]
    G -->|No| I[全キーを含める]
    H --> J{format?}
    I --> J
    J -->|:edn| K[EDN形式で出力]
    J -->|:json| L[JSON形式で出力]
    J -->|その他| M[エラー: 非対応形式]
    K --> N[result-code: 0]
    L --> N
    M --> O[result-code: 1]
    N --> P[終了]
    O --> P
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-84-1 | デフォルト出力形式 | 出力形式未指定時は :edn を使用 | --output に :format 未指定時 |
| BR-84-2 | デフォルト解析タイプ | 解析タイプ未指定時は :project-only | --analysis 未指定時 |
| BR-84-3 | フィルタキー | filter-keys が coll? の場合のみフィルタ適用 | filter-keys 指定時 |

### 計算ロジック

ダンプデータの構成:
1. dbから以下のキーを選択: :classpath, :analysis, :dep-graph, :settings
2. 追加データを付与:
   - :findings <- :diagnostics :clj-kondo
   - :project-root <- :project-root-uri をファイルパスに変換
   - :source-paths <- :settings :source-paths
   - :clj-kondo-settings <- :kondo-config
   - :diagnostics <- diagnostics-by-uri で生成

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

該当なし（ファイルシステムのみ操作）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 1 | 形式エラー | :format が :edn でも :json でもない | エラーメッセージを表示して終了 |
| 1 | 解析エラー | プロジェクト解析に失敗 | エラーメッセージを表示して終了 |

### リトライ仕様

リトライは行わない。エラー発生時は即座に終了する。

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

該当なし（読み取り専用処理）

## パフォーマンス要件

- 解析結果全体を出力するため、大規模プロジェクトでは出力サイズが大きくなる可能性がある
- filter-keys の使用により出力サイズを削減可能

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

- 読み取り専用操作のためセキュリティリスクは低い
- 出力にはプロジェクトの内部情報（パス、設定など）が含まれる

## 備考

- この機能は実験的（experimental）とマークされている
- 将来のバージョンで出力形式が変更される可能性がある

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | cli-spec | `cli/src/clojure_lsp/main.clj` | --output オプションの定義 |
| 1-2 | dump-data構造 | `lib/src/clojure_lsp/internal_api.clj` | db->dump-data の出力構造 |

**読解のコツ**: ダンプデータは db 内の複数のキーから構成される。filter-keys で出力を制限可能。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | main.clj | `cli/src/clojure_lsp/main.clj` | dumpコマンドの実行フロー |

**主要処理フロー**:
1. **176行目**: "dump" コマンドの認識
2. **213行目**: `internal-api/dump` の呼び出し
3. **38行目**: ヘルプでの説明「Dump all project known data...」

#### Step 3: internal-api層を理解する

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

**主要処理フロー**:
- **456-470行目**: `db->dump-data` - ダンプデータの構成
- **472-486行目**: `dump*` - ダンプ処理の本体
- **474行目**: `dynamic-setup-project-analysis!` でデフォルト :project-only
- **477-486行目**: format による出力形式の分岐

#### Step 4: データ構成を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | internal_api.clj | `lib/src/clojure_lsp/internal_api.clj` | db->dump-data の詳細 |

**主要処理フロー**:
- **457行目**: select-keys でベースキーを選択
- **459-464行目**: assoc で追加データを付与
- **465-470行目**: filter-keys によるフィルタリング

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

```
main/-main
    │
    └─ main/run!
           │
           └─ main/handle-action!
                  │
                  └─ internal-api/dump
                         │
                         ├─ internal-api/build-components
                         │
                         └─ internal-api/dump*
                                │
                                ├─ internal-api/dynamic-setup-project-analysis!
                                │
                                ├─ internal-api/db->dump-data
                                │      │
                                │      └─ internal-api/diagnostics-by-uri
                                │
                                └─ json/generate-string (JSON出力時)
```

### データフロー図

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

--output オプション ──▶ オプション解析 ──────▶ format, filter-keys
                              │
                              ▼
プロジェクト解析 ───▶ db 生成 ─────────────▶ 解析済みDB
                              │
                              ▼
                       db->dump-data ─────▶ ダンプデータマップ
                              │
                              ├─ :classpath
                              ├─ :source-paths
                              ├─ :analysis
                              ├─ :dep-graph
                              ├─ :settings
                              ├─ :findings
                              └─ :diagnostics
                              │
                              ▼
                       format変換 ───────────▶ EDN/JSON文字列
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| main.clj | `cli/src/clojure_lsp/main.clj` | ソース | CLIエントリーポイント |
| internal_api.clj | `lib/src/clojure_lsp/internal_api.clj` | ソース | CLI用API実装 |
| diagnostics.clj | `lib/src/clojure_lsp/feature/diagnostics.clj` | ソース | 診断情報生成 |
| dep_graph.clj | `lib/src/clojure_lsp/dep_graph.clj` | ソース | 依存グラフ管理 |
