# 機能設計書 46-clj-depend統合

## 概要

本ドキュメントは、clojure-lspの「clj-depend統合」機能の設計を詳細に記載する。この機能は、clj-dependによる依存関係違反の検出をLSP診断として表示するアーキテクチャ検証機能である。

### 本機能の処理概要

**業務上の目的・背景**：大規模なClojureプロジェクトでは、モジュール間の依存関係を適切に管理することが重要である。clj-dependはClojureプロジェクトの依存関係ルールを定義し、違反を検出するツールである。この統合により、開発中にリアルタイムで依存関係違反を検出し、アーキテクチャの一貫性を維持できる。

**機能の利用シーン**：プロジェクトに`.clj-depend/config.edn`または設定が存在する場合、ファイル保存時やプロジェクト読み込み時に自動実行され、依存関係違反がある名前空間に対して診断を表示する。

**主要な処理内容**：
1. clj-depend設定の存在確認
2. clj-depend解析の実行
3. 違反結果を名前空間毎にグループ化
4. 診断形式に変換して表示

**関連システム・外部連携**：clj-dependライブラリ。

**権限による制御**：特になし。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| N/A | エディタ | 主画面 | 診断結果の表示（名前空間宣言部） |

## 機能種別

静的解析 / 診断 / アーキテクチャ検証

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| uri | String | Yes | 解析対象ファイルURI | 有効なファイルURI |
| paths | Array[String] | No | 解析対象パスの配列（バッチ処理時） | 有効なパス |

### 入力データソース

- clj-depend設定（.clj-depend/config.edn または :clj-depend 設定）
- プロジェクトのソースパス

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| violations | Map | 名前空間毎の違反配列 |
| violations[ns] | Array | 違反オブジェクトの配列 |
| violations[ns][].message | String | 違反メッセージ |

### 出力先

- LSP textDocument/publishDiagnostics 通知（変換後）

## 処理フロー

### 処理シーケンス

```
1. clj-depend設定の確認
   └─ should-run? で設定または .clj-depend/config.edn の存在確認
2. オプション構築
   └─ new-options で設定をマージ
   └─ with-project-root, with-source-paths でパス設定
3. clj-depend解析実行
   └─ clj-depend/analyze を呼び出し
4. 結果のグループ化
   └─ violations-grouped-by-namespace で名前空間毎に整理
5. データベース更新
   └─ db-with-results で :diagnostics :clj-depend に格納
6. 診断変換
   └─ clj-depend-violations->diagnostics で LSP 形式に変換
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{設定存在?}
    B -->|いいえ| Z[nil返却]
    B -->|はい| C{レベル:off?}
    C -->|はい| Z
    C -->|いいえ| D[オプション構築]
    D --> E[clj-depend解析]
    E --> F[名前空間毎グループ化]
    F --> G[DB更新]
    G --> H[診断変換]
    H --> I[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 設定存在確認 | .clj-depend/config.edn または :clj-depend 設定が必要 | 起動時 |
| BR-02 | ソースパス自動設定 | config に source-paths がなければプロジェクトの source-paths を使用 | 設定時 |
| BR-03 | 相対パス変換 | source-paths はプロジェクトルートからの相対パスに変換 | 設定時 |
| BR-04 | レベル設定 | :linters :clj-depend :level でデフォルト :info | 常時 |

### 計算ロジック

設定マージ（後方互換性維持）：
```clojure
(defn new-options [{:keys [snapshot?] :as config}]
  (if (:config config)
    config  ; 新形式
    (shared/assoc-some {:config (dissoc config :project-root :files :namespaces :snapshot?)}
                       :snapshot? snapshot?)))  ; 旧形式
```

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 診断格納 | :diagnostics :clj-depend | MERGE | 名前空間毎の違反配列をマージ |

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

#### :diagnostics :clj-depend

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| MERGE | namespace-symbol -> [violations] | clj-depend の violations | シンボルをキーに格納 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| N/A | 解析エラー | clj-depend実行時例外 | エラーログ出力、処理継続 |
| N/A | 設定エラー | clj-depend設定不正 | エラーログ出力、nil返却 |

### リトライ仕様

リトライなし

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

アトム操作による排他制御（swap!）。

## パフォーマンス要件

- 解析時間はプロジェクトサイズ依存
- バッチ処理時はファイル指定で最適化可能

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

特になし

## 備考

- clj-depend 設定は .clj-depend/config.edn または LSP設定の :clj-depend で指定
- snapshot? オプションで依存関係スナップショットを使用可能

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | clj_depend.clj | `lib/src/clojure_lsp/clj_depend.clj` | clj-depend の入出力構造を理解 |

**読解のコツ**: violations の構造と名前空間毎のグループ化を把握する。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | clj_depend.clj | `lib/src/clojure_lsp/clj_depend.clj` | analyze-uri!, analyze-paths! |

**主要処理フロー**:
- **70-82行目**: `analyze-uri!` - 単一URI解析
- **84-92行目**: `analyze-paths!` - パス指定解析

#### Step 3: 設定とオプション構築を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | clj_depend.clj | `lib/src/clojure_lsp/clj_depend.clj` | new-options, with-* 関数群 |

**主要処理フロー**:
- **48-54行目**: `new-options` - 後方互換設定マージ
- **44-46行目**: `with-project-root` - プロジェクトルート設定
- **38-42行目**: `with-source-paths` - ソースパス設定
- **56-68行目**: `should-run?`, `configured?` - 実行条件判定

#### Step 4: 診断変換を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | diagnostics.clj | `lib/src/clojure_lsp/feature/diagnostics.clj` | clj-depend-violations->diagnostics |

**主要処理フロー**:
- **95-107行目**: `clj-depend-violations->diagnostics` - LSP形式への変換

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

```
startup/initialize-project (並列実行)
    │
    └─ clj-depend/analyze-paths!
           │
           ├─ should-run?
           │      └─ configured?
           │
           └─ analyze
                  │
                  ├─ new-options
                  ├─ with-project-root
                  ├─ with-source-paths
                  └─ clj-depend/analyze (ライブラリ)

clj-depend/db-with-results
    │
    └─ update :diagnostics :clj-depend

f.diagnostic/find-diagnostics
    │
    └─ clj-depend-violations->diagnostics
           │
           └─ q/find-namespace-definition-by-uri
```

### データフロー図

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

設定ファイル ────────▶ should-run?
                           │
                           ▼
            ┌──────────────┴──────────────┐
            │                             │
      analyze-uri!                  analyze-paths!
            │                             │
            └──────────────┬──────────────┘
                           │
                           ▼
                 clj-depend/analyze
                           │
                           ▼
          violations-grouped-by-namespace
                           │
                           ▼
                  :diagnostics :clj-depend
                           │
                           ▼
          clj-depend-violations->diagnostics
                           │
                           ▼
                    LSP Diagnostics
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| clj_depend.clj | `lib/src/clojure_lsp/clj_depend.clj` | ソース | clj-depend統合のメインロジック |
| diagnostics.clj | `lib/src/clojure_lsp/feature/diagnostics.clj` | ソース | 診断変換と発行 |
| settings.clj | `lib/src/clojure_lsp/settings.clj` | ソース | 設定管理 |
| startup.clj | `lib/src/clojure_lsp/startup.clj` | ソース | 起動時処理 |
