# 機能設計書 79-名前空間クリーンアップ

## 概要

本ドキュメントは、clojure-lsp の CLI コマンドとして提供される `clean-ns` コマンドの機能設計を記述する。このコマンドは ns フォームを整理し、未使用の require/refer/import の削除とアルファベット順ソートを実行する。

### 本機能の処理概要

**業務上の目的・背景**：Clojure のソースコードでは、開発中に不要になった require や import が残ったり、参照順序が乱れたりすることがある。この機能はこれらを自動的に整理し、コードの可読性と保守性を向上させる。

**機能の利用シーン**：コードレビュー前のクリーンアップ、CI/CD でのコード品質チェック（dry モード）、リファクタリング後の整理などで利用される。

**主要な処理内容**：
1. 対象名前空間/ファイルの特定
2. 各ファイルの ns フォームを解析
3. 未使用の require/refer/import を検出
4. アルファベット順にソート
5. 変更の適用または差分レポート

**関連システム・外部連携**：なし。

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

## 関連画面

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

## 機能種別

ファイル更新 / リファクタリング

## 入力仕様

### 入力パラメータ（CLI オプション）

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| --project-root / -p | File | No | プロジェクトルートのパス | 存在するディレクトリ |
| --namespace / -n | Symbol | No | 対象名前空間（複数指定可） | 有効なシンボル |
| --filenames | String | No | 対象ファイル（カンマまたはコロン区切り） | 有効なファイルパス |
| --ns-exclude-regex | Regex | No | 除外する名前空間の正規表現 | 有効な正規表現 |
| --dry | Boolean | No | dry モード（ファイル変更なし） | - |
| --raw | Boolean | No | 最小限の出力 | - |
| --settings / -s | EDN | No | 設定を EDN 形式で指定 | 有効な EDN マップ |

### 入力データソース

- ファイルシステム（プロジェクトソースファイル）
- 解析データベース

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| :result-code | Integer | 0: 変更なし/完了、1: 変更あり（dry モード） |
| :message-fn | Function | 結果を文字列化する関数 |
| :edits | Collection | 編集内容のコレクション |

### 出力先

- ファイルシステム（dry が false の場合）
- 標準出力（差分情報）

## 処理フロー

### 処理シーケンス

```
1. CLI オプション解析
2. プロジェクト解析
   └─ project-only で解析
3. 対象 URI の特定
   └─ namespace/filenames から URI リストを生成
4. 各ファイルの clean-ns 実行
   └─ handlers/execute-command "clean-ns"
5. 編集適用または差分生成
   └─ dry に応じて処理を分岐
```

### フローチャート

```mermaid
flowchart TD
    A[clojure-lsp clean-ns] --> B[CLI オプション解析]
    B --> C[プロジェクト解析]
    C --> D[対象 URI 特定]
    D --> E[各 URI に clean-ns 実行]
    E --> F{編集あり?}
    F -->|No| G[Nothing to clear!]
    F -->|Yes| H{dry モード?}
    H -->|Yes| I[差分出力]
    H -->|No| J[ファイルに適用]
    J --> K[Cleaned X namespaces]
    G --> L[終了]
    I --> L
    K --> L
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-79-1 | 未使用検出 | 参照されていない require/refer/import を検出 | 常時 |
| BR-79-2 | アルファベット順 | require/import をアルファベット順にソート | 常時 |
| BR-79-3 | dry モード | --dry 時はファイル変更せず差分のみ表示 | --dry 指定時 |
| BR-79-4 | 除外フィルタ | --ns-exclude-regex にマッチする名前空間は除外 | --ns-exclude-regex 指定時 |

### 計算ロジック

クリーンアップ対象：
- 未使用の `:require`
- 未使用の `:refer` 内シンボル
- 未使用の `:import`

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

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

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

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

atom によるインメモリデータベースを参照。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 該当なし | 名前空間未検出 | 指定した名前空間が見つからない | 正しい名前空間を指定 |

### リトライ仕様

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

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

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

## パフォーマンス要件

- pmap による並列処理で高速化
- プロジェクトサイズに依存

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

- ファイルシステムアクセスはプロセス権限に依存

## 備考

- API 版は `clojure-lsp.api/clean-ns!` として提供
- LSP サーバーモードでは workspace/executeCommand で実行可能

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | clean_ns.clj | `lib/src/clojure_lsp/feature/clean_ns.clj` | クリーンアップロジック |

**読解のコツ**: ns フォームの解析とクリーンアップ処理を理解する。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | main.clj | `cli/src/clojure_lsp/main.clj` | CLI エントリーポイント |

**主要処理フロー**:
1. **202行目**: handle-action! で "clean-ns" アクション処理
2. **202行目**: internal-api/clean-ns! 呼び出し

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

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

**主要処理フロー**:
- **296-323行目**: clean-ns!* で並列クリーンアップ実行
- **303-306行目**: handlers/execute-command "clean-ns" 呼び出し

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

```
main/-main
    |
    +-- main/run!
            |
            +-- parse
            |
            +-- handle-action! "clean-ns"
                    |
                    +-- internal-api/clean-ns!
                            |
                            +-- build-components
                            |
                            +-- clean-ns!*
                                    |
                                    +-- setup-api!
                                    +-- setup-project-only-analysis!
                                    +-- options->uris
                                    +-- pmap
                                            |
                                            +-- handlers/execute-command "clean-ns"
                                                    |
                                                    +-- f.clean-ns/clean-ns
                                    +-- apply-workspace-edit-summary!
```

### データフロー図

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

--namespace [...]        main "clean-ns"                     Cleaned X namespaces
--filenames [...]        |                                   または
        |                v                                   差分出力（dry モード）
        +-------------> options->uris                         |
                        |                                     |
                        v                                     |
                   各 URI に対して                             |
                   handlers/execute-command "clean-ns"        |
                        |                                     |
                        v                                     |
                   document-changes                           |
                        |                                     |
              +---------+---------+                           |
              |                   |                           |
              v                   v                           |
        dry = true          dry = false                       |
              |                   |                           |
              v                   v                           |
        差分出力           ファイル更新 --------------------> 結果出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| main.clj | `cli/src/clojure_lsp/main.clj` | ソース | CLI エントリーポイント |
| internal_api.clj | `lib/src/clojure_lsp/internal_api.clj` | ソース | 内部実装 |
| api.clj | `lib/src/clojure_lsp/api.clj` | ソース | 公開 API |
| clean_ns.clj | `lib/src/clojure_lsp/feature/clean_ns.clj` | ソース | クリーンアップロジック |
| handlers.clj | `lib/src/clojure_lsp/handlers.clj` | ソース | コマンドハンドラー |
