# バッチ設計書 3-diagnostics

## 概要

本ドキュメントは、clojure-lspのdiagnosticsコマンド（診断情報検出機能）のバッチ設計を記載する。

### 本バッチの処理概要

Clojure/ClojureScriptプロジェクト全体を解析し、コード内の警告、エラー、潜在的な問題を検出して報告する機能を提供する。clj-kondoの静的解析エンジンとclojure-lsp独自の診断機能を組み合わせて、包括的なコード品質チェックを実現する。

**業務上の目的・背景**：大規模なClojureプロジェクトでは、未使用の変数、型の不一致、非推奨APIの使用など、様々な問題がコードベースに混入しやすい。本コマンドにより、プロジェクト全体を一括でスキャンし、問題を早期に発見できる。CIパイプラインでの品質ゲートとして利用することで、問題のあるコードがマージされることを防止できる。

**バッチの実行タイミング**：開発者が手動で実行、またはCIパイプラインで自動実行。プルリクエストのチェックとしても使用される。

**主要な処理内容**：
1. プロジェクトの解析（classpath、source-paths取得）
2. clj-kondoによる静的解析の実行
3. clojure-lsp独自の診断（unused-public-var等）の実行
4. 全診断情報の収集とフィルタリング
5. 結果の出力（テキスト、EDN、またはJSON形式）

**前後の処理との関連**：他のコマンドの前提条件ではない。lint-diagnosticsタスクはこのコマンドを--dryモードで実行する。

**影響範囲**：プロジェクト内の全Clojure/ClojureScriptファイルを読み取り専用でスキャン。ファイルの変更は行わない。

## バッチ種別

静的解析 / 品質チェック処理

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（手動）/ CI実行時 |
| 実行時刻 | 該当なし |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | 手動実行 / CIパイプライン |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| プロジェクト存在 | deps.edn/project.clj等のプロジェクトファイルが存在すること |
| Clojureファイル | 対象となる.clj/.cljs/.cljcファイルが存在すること |

### 実行可否判定

プロジェクトが解析可能な状態であること。除外パターン（--ns-exclude-regex）に一致するファイルはスキャン対象外となる。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| --project-root | Path | No | カレントディレクトリ | プロジェクトルートパス |
| --namespace / -n | Symbol | No | 全ns | 対象とする名前空間（複数指定可） |
| --filenames | String | No | 全ファイル | 対象ファイル（カンマまたはコロン区切り） |
| --ns-exclude-regex | Regex | No | なし | 除外する名前空間の正規表現パターン |
| --output / -o | EDN | No | {} | 出力形式設定（:format指定可） |
| --settings / -s | EDN | No | {} | 追加設定をEDN形式で指定 |
| --raw | Boolean | No | false | 出力を最小限にする |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| Clojureソースファイル | .clj/.cljs/.cljc | 解析対象のソースコード |
| プロジェクトファイル | deps.edn等 | classpathとsource-paths取得用 |
| .clj-kondo/config.edn | EDN | clj-kondoの解析設定 |
| .lsp/config.edn | EDN | clojure-lsp設定ファイル |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| 標準出力 | テキスト/EDN/JSON | 診断結果（--output :formatで形式指定） |
| 標準エラー出力 | テキスト | 進捗情報、ログ |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | 該当なし（標準出力のみ） |
| 出力先 | 標準出力 |
| 文字コード | UTF-8 |
| 区切り文字 | 改行（テキスト）/ データ構造（EDN/JSON） |

## 処理フロー

### 処理シーケンス

```
1. CLI引数パース
   └─ オプションの解析と検証
2. コンポーネント構築
   └─ CLILogger、APIProducerの初期化
3. プロジェクト解析
   └─ setup-project-and-clojure-only-deps-analysis!実行
4. 対象ファイル特定
   └─ options->urisでフィルタリング
5. 診断情報収集
   └─ f.diagnostic/find-diagnosticsを並列実行
6. 結果集約
   └─ URI別に診断情報をマップ化
7. 出力生成
   └─ 指定形式（テキスト/EDN/JSON）で結果出力
8. 終了
   └─ 結果コード返却（エラー:3、警告:2、正常:0）
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[CLI引数パース]
    B --> C[コンポーネント構築]
    C --> D[プロジェクト解析]
    D --> E[対象ファイル特定]
    E --> F[診断情報収集（並列）]
    F --> G{診断結果あり?}
    G -->|なし| H[No diagnostics found!]
    H --> I[終了コード0]
    G -->|あり| J{エラーあり?}
    J -->|Yes| K[終了コード3]
    J -->|No| L{警告あり?}
    L -->|Yes| M[終了コード2]
    L -->|No| I
    K --> N[結果出力]
    M --> N
    I --> N
    N --> O[バッチ終了]
```

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

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

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 該当なし | - | - | 外部DBは使用しない |

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

本バッチは外部データベースを使用しない。内部的にAtom（db*）を使用してプロジェクト解析結果を管理する。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 3 | エラー検出 | severity=1（error）の診断がある | コードのエラー修正 |
| 2 | 警告検出 | severity=2（warning）の診断がある | コードの警告対応 |
| 1 | 解析エラー | ファイルの構文エラー等 | ソースコード修正 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0（リトライなし） |
| リトライ間隔 | 該当なし |
| リトライ対象エラー | 該当なし |

### 障害時対応

解析エラーが発生した場合、該当ファイルをスキップして続行する。エラーの詳細はログに出力される。

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 該当なし（読み取り専用） |
| コミットタイミング | 該当なし |
| ロールバック条件 | 該当なし |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | プロジェクト規模に依存 |
| 目標処理時間 | 初回解析含め数秒〜数分 |
| メモリ使用量上限 | JVMヒープに依存 |

## 排他制御

読み取り専用のため、複数の同時実行が可能。ただし、同時実行するとCPU/メモリ負荷が増加する。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | 処理開始時 | "Finding diagnostics..." |
| 進捗ログ | 解析中 | 解析進捗率 |
| 結果ログ | 処理完了時 | 診断件数または"No diagnostics found!" |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 終了コード | 2以上 | CI/CDパイプライン |
| エラー件数 | 1以上 | CI/CDパイプライン |

## 備考

- 出力形式は--output '{:format :edn}'または--output '{:format :json}'で変更可能
- 診断結果の各行は「ファイル:行:列: レベル: [コード] メッセージ」形式
- --output '{:canonical-paths true}'で絶対パス表示に切り替え可能
- setup-project-and-clojure-only-deps-analysis!によりClojure依存関係も解析される
- pmapによる並列処理でパフォーマンス最適化されている
- severityは1=error、2=warning、3=info、4=hint
