# 帳票設計書 2-dump

## 概要

本ドキュメントは、clojure-lspのdump（エクスポート）機能によって出力される帳票の設計仕様を定義する。

### 本帳票の処理概要

dump帳票は、プロジェクトのメタデータ（classpath、source-paths、dep-graph、clj-kondo解析データ）をエクスポートする帳票である。プロジェクトの内部構造を外部ツールや分析用途で利用するためのデータダンプ機能を提供する。本機能は実験的機能（experimental）として位置づけられている。

**業務上の目的・背景**：大規模なClojureプロジェクトでは、依存関係の可視化、解析データの外部ツール連携、プロジェクト構造のデバッグ、カスタム分析ツールの開発などの需要がある。本帳票は、clojure-lspが内部で保持しているプロジェクト解析データを標準フォーマット（EDN/JSON）でエクスポートし、これらの二次利用を可能にすることを目的とする。

**帳票の利用シーン**：本帳票は以下の場面で利用される。(1) プロジェクト依存関係グラフの可視化、(2) カスタムリファクタリングツールへのデータ提供、(3) clojure-lspの動作デバッグ、(4) プロジェクト構造の監査、(5) IDE/エディタプラグインでの高度な機能実装。

**主要な出力内容**：
1. project-root - プロジェクトルートパス
2. source-paths - ソースディレクトリ一覧
3. classpath - クラスパス一覧
4. analysis - clj-kondo解析データ（正規化済み）
5. dep-graph - 名前空間依存関係グラフ
6. diagnostics - 診断結果
7. settings - clojure-lsp設定
8. clj-kondo-settings - clj-kondo設定

**帳票の出力タイミング**：CLIコマンド`clojure-lsp dump`の実行時、またはAPI経由での`clojure-lsp.api/dump`関数呼び出し時に出力される。

**帳票の利用者**：開発者、ツール開発者、DevOpsエンジニア、プロジェクトアーキテクト

## 帳票種別

エクスポートレポート / データダンプ

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| CLI-01 | コマンドライン | `clojure-lsp dump` | コマンド実行 |
| API-01 | Clojure REPL | `(clojure-lsp.api/dump opts)` | 関数呼び出し |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | EDN / JSON |
| 用紙サイズ | N/A（データ出力） |
| 向き | N/A |
| ファイル名 | 標準出力（リダイレクト可能） |
| 出力方法 | 標準出力 |
| 文字コード | UTF-8 |

### 出力フォーマット詳細

#### EDN形式（デフォルト）
```clojure
{:project-root "/path/to/project"
 :source-paths ["src" "test"]
 :classpath ["/path/to/lib1.jar" "/path/to/lib2.jar" ...]
 :analysis {:uri1 {:var-definitions [...] :var-usages [...] ...}
            :uri2 {...}}
 :dep-graph {:namespaces {...} :aliases {...}}
 :diagnostics {:uri1 [...] :uri2 [...]}
 :settings {:source-paths [...] ...}
 :clj-kondo-settings {:linters {...} ...}}
```

#### JSON形式（`--output {:format :json}`）
```json
{
  "project-root": "/path/to/project",
  "source-paths": ["src", "test"],
  "classpath": ["/path/to/lib1.jar", ...],
  "analysis": {...},
  "dep-graph": {...},
  "diagnostics": {...},
  "settings": {...},
  "clj-kondo-settings": {...}
}
```

## 帳票レイアウト

### レイアウト概要

単一のマップ/オブジェクトとして構造化されたデータを出力。

```
┌─────────────────────────────────────────────────────────────────┐
│  {:project-root "..."                                           │
│   :source-paths [...]                                           │
│   :classpath [...]                                              │
│   :analysis {...}                                               │
│   :dep-graph {...}                                              │
│   :diagnostics {...}                                            │
│   :settings {...}                                               │
│   :clj-kondo-settings {...}}                                    │
└─────────────────────────────────────────────────────────────────┘
```

### 出力項目

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | project-root | プロジェクトルートパス | db.project-root-uri | 文字列（パス） |
| 2 | source-paths | ソースディレクトリ一覧 | db.settings.source-paths | 文字列リスト |
| 3 | classpath | クラスパス一覧 | db.classpath | 文字列リスト |
| 4 | analysis | clj-kondo解析データ | db.analysis | マップ |
| 5 | dep-graph | 依存関係グラフ | db.dep-graph | マップ |
| 6 | diagnostics | 診断結果 | diagnostics-by-uri | マップ |
| 7 | findings | clj-kondo findings | db.diagnostics.clj-kondo | マップ |
| 8 | settings | clojure-lsp設定 | db.settings | マップ |
| 9 | clj-kondo-settings | clj-kondo設定 | db.kondo-config | マップ |

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| project-root | プロジェクトルートディレクトリ | No（デフォルト: カレントディレクトリ） |
| output.format | 出力形式（:edn / :json） | No（デフォルト: :edn） |
| output.filter-keys | 出力項目の絞り込み | No（デフォルト: 全項目） |
| analysis.type | 解析タイプ | No（デフォルト: :project-only） |

### analysis.typeオプション

| 値 | 説明 |
|---|------|
| :project-only | プロジェクトのみ解析（デフォルト） |
| :project-and-shallow-analysis | プロジェクト＋浅い依存解析 |
| :project-and-full-dependencies | プロジェクト＋全依存解析 |

### ソート順

N/A（構造化データのため順序は形式依存）

### 改ページ条件

N/A（データ出力のため）

## データベース参照仕様

### 参照テーブル一覧

| テーブル名 | 用途 | 結合条件 |
|-----------|------|---------|
| db.classpath | クラスパス情報 | - |
| db.analysis | 解析データ | - |
| db.dep-graph | 依存関係グラフ | - |
| db.settings | 設定情報 | - |
| db.kondo-config | clj-kondo設定 | - |
| db.diagnostics.clj-kondo | clj-kondo診断 | - |

### テーブル別参照項目詳細

#### db.analysis

| 参照項目（キー名） | 帳票項目との対応 | 取得条件 | 備考 |
|-------------------|----------------|---------|------|
| :var-definitions | analysis内 | URI単位 | 変数定義 |
| :var-usages | analysis内 | URI単位 | 変数使用 |
| :namespace-definitions | analysis内 | URI単位 | 名前空間定義 |
| :namespace-usages | analysis内 | URI単位 | 名前空間使用 |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| result-code | 成功:0, 失敗:1 | - | 終了コード |
| project-root | uri->filename(db.project-root-uri) | - | URI→パス変換 |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[dumpコマンド実行] --> B[オプション解析]
    B --> C[プロジェクト解析初期化]
    C --> D{analysis.type}
    D -->|project-only| E[プロジェクトのみ解析]
    D -->|shallow| F[浅い依存解析]
    D -->|full| G[全依存解析]
    E --> H[db->dump-data変換]
    F --> H
    G --> H
    H --> I{filter-keys指定?}
    I -->|あり| J[指定キーのみ抽出]
    I -->|なし| K[全キー出力]
    J --> L{出力形式}
    K --> L
    L -->|EDN| M[EDN形式出力]
    L -->|JSON| N[JSON形式出力]
    M --> O[終了]
    N --> O
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| プロジェクト解析失敗 | 不正なプロジェクト構成 | Error during project analysis | プロジェクト設定確認 |
| 未サポート形式 | 不正なoutput.format | Output format X not supported | :edn または :json を指定 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | 数百〜数千ファイル |
| 目標出力時間 | 解析完了後: 数秒以内 |
| 同時出力数上限 | 1（シングルスレッド処理） |

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

- 解析データにはプロジェクト構造が含まれるため、出力先の管理に注意
- classpathにはローカルパスが含まれる可能性あり
- 本番環境での実行は推奨しない

## 備考

- 本機能は実験的機能（experimental）として提供
- filter-keysオプションで必要な項目のみ抽出可能
- 大規模プロジェクトでは出力データが非常に大きくなる可能性あり

---

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

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

### 推奨読解順序

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

dump機能で出力される主要なデータ構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | db.clj | `lib/src/clojure_lsp/db.clj` | `initial-db`定義、主要キー構造 |
| 1-2 | dep_graph.clj | `lib/src/clojure_lsp/dep_graph.clj` | 依存関係グラフ構造 |

**読解のコツ**: dbアトムの構造を把握することが重要。`:analysis`, `:dep-graph`, `:settings`などの主要キーの役割を理解する。

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

CLIからの呼び出しフローを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | main.clj | `cli/src/clojure_lsp/main.clj` | **176行目**: `"dump"`アクション分岐 |
| 2-2 | main.clj | `cli/src/clojure_lsp/main.clj` | **213行目**: `internal-api/dump`呼び出し |

**主要処理フロー**:
1. **156-180行目**: `parse`関数でコマンドライン引数を解析
2. **194-215行目**: `handle-action!`関数でアクション実行
3. **213行目**: dumpの場合`internal-api/dump`を呼び出し

#### Step 3: 公開API層を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | api.clj | `lib/src/clojure_lsp/api.clj` | **293-345行目**: `dump`関数定義とドキュメント |

**主要処理フロー**:
- **293-296行目**: 関数シグネチャと目的の説明
- **297-324行目**: オプションと出力形式の詳細ドキュメント
- **335-345行目**: 前提条件チェックと実行

#### Step 4: 内部API層を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | internal_api.clj | `lib/src/clojure_lsp/internal_api.clj` | **456-470行目**: `db->dump-data`関数 |
| 4-2 | internal_api.clj | `lib/src/clojure_lsp/internal_api.clj` | **472-486行目**: `dump*`関数 |

**主要処理フロー**:
- **456行目**: `db->dump-data`でDBからエクスポートデータを構築
- **457-460行目**: 基本キーの選択（classpath, analysis, dep-graph, settings）
- **461-464行目**: 追加データの付与（findings, project-root, source-paths等）
- **472行目**: `dump*`で解析タイプに応じた処理
- **477-486行目**: EDN/JSON形式での出力

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

```
clojure-lsp.main/-main
    |
    +-- parse (コマンド解析)
    |
    +-- handle-action!
           |
           +-- clojure-lsp.internal-api/dump
                  |
                  +-- build-components (コンポーネント初期化)
                  |
                  +-- dump*
                         |
                         +-- setup-api!
                         |
                         +-- dynamic-setup-project-analysis!
                         |      |
                         |      +-- setup-project-only-analysis! (デフォルト)
                         |      +-- setup-project-and-shallow-analysis!
                         |      +-- setup-project-and-full-deps-analysis!
                         |
                         +-- db->dump-data
                         |      |
                         |      +-- select-keys (classpath, analysis, dep-graph, settings)
                         |      +-- diagnostics-by-uri
                         |      +-- filter-keys適用
                         |
                         +-- EDN/JSON出力
```

### データフロー図

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

CLIオプション ────────▶ parse ────────────────────────▶ options map
     |                                                      |
     v                                                      v
project-root ─────────▶ analyze! ─────────────────────▶ db (full data)
     |                                                      |
     v                                                      v
analysis.type ────────▶ dynamic-setup-project-analysis! ──▶ db.analysis
     |                                                      |
     v                                                      v
db ───────────────────▶ db->dump-data ────────────────▶ dump-data map
     |                                                      |
     v                                                      v
filter-keys ──────────▶ select-keys ──────────────────▶ filtered dump-data
     |                                                      v
output.format ────────▶ pr / json/generate-string ────▶ stdout (EDN/JSON)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| main.clj | `cli/src/clojure_lsp/main.clj` | ソース | CLIエントリーポイント |
| api.clj | `lib/src/clojure_lsp/api.clj` | ソース | 公開API定義 |
| internal_api.clj | `lib/src/clojure_lsp/internal_api.clj` | ソース | 内部API実装 |
| db.clj | `lib/src/clojure_lsp/db.clj` | ソース | データベース構造定義 |
| dep_graph.clj | `lib/src/clojure_lsp/dep_graph.clj` | ソース | 依存関係グラフ |
| startup.clj | `lib/src/clojure_lsp/startup.clj` | ソース | プロジェクト初期化 |
| settings.clj | `lib/src/clojure_lsp/settings.clj` | ソース | 設定管理 |
| shared.clj | `lib/src/clojure_lsp/shared.clj` | ソース | 共通ユーティリティ |
| dump_test.clj | `cli/integration-test/integration/api/dump_test.clj` | テスト | dump機能テスト |
