# 機能設計書 37-require追加提案

## 概要

本ドキュメントは、Clojure LSPの「require追加提案」機能の設計仕様を記載する。この機能は、未解決のシンボル（エイリアス付きシンボルや参照）に対して、適切なrequire句の追加を提案・実行するクイックフィックス操作を提供する。

### 本機能の処理概要

**業務上の目的・背景**：Clojureコードを書く際、使用したい名前空間をrequireし忘れることがよくある。clj-kondoは`unresolved-namespace`や`unresolved-symbol`として警告を出すが、正しいrequire句を手動で追加するのは面倒で、エイリアスの選択にも迷うことがある。本機能は、プロジェクト全体で使用されているエイリアスパターンを分析し、最適なrequire句を提案することで、開発者の生産性を向上させる。

**機能の利用シーン**：この機能は以下の場面で利用される：
- 新しいシンボルを使用する際のrequire句の自動追加
- 未解決シンボルの診断に対するクイックフィックス
- エイリアスの一貫性確保

**主要な処理内容**：
1. 未解決シンボルからエイリアスまたはrefer名を抽出
2. プロジェクト全体のエイリアス使用パターンを分析
3. 候補となる名前空間とエイリアスのペアを生成
4. ns宣言にrequire句を追加する編集を生成
5. コード内のシンボルを必要に応じて更新

**関連システム・外部連携**：LSPプロトコルを通じてエディタと連携。clj-kondoの解析結果を使用。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | エディタ画面 | 主画面 | クイックフィックスメニューから「Add require」を選択 |

## 機能種別

コードアクション（クイックフィックス）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| uri | string | Yes | 対象ファイルのURI | 有効なファイルURIであること |
| line | number | Yes | カーソル行（0-indexed） | 0以上の整数 |
| character | number | Yes | カーソル列（0-indexed） | 0以上の整数 |
| ns | string | Yes（add-require-suggestion時） | 追加する名前空間 | 有効な名前空間名 |
| alias | string | No | 使用するエイリアス | 有効なシンボル名 |
| refer | string | No | referするシンボル | 有効なシンボル名 |
| js-require | boolean | No | JavaScript requireか | - |

### 入力データソース

- エディタからのLSP `textDocument/codeAction` リクエスト
- コマンド名: `add-require-suggestion` または `add-missing-libspec`

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| edits | vector | ns宣言への追加とシンボル更新の編集リスト |

### 出力先

- LSPレスポンスとしてエディタに返却

## 処理フロー

### 処理シーケンス

```
1. 診断情報の取得
   └─ unresolved-namespace/unresolved-symbol診断を取得

2. シンボルの解析
   └─ カーソル位置のシンボルからエイリアス/refer名を抽出

3. 候補の検索
   └─ dep-graphからプロジェクト全体のエイリアス使用を検索
   └─ common-sym/common-alias->infoから一般的なエイリアスを検索

4. 候補のランキング
   └─ 使用頻度でソート
   └─ 一意に決まる場合は自動選択

5. ns宣言への編集
   └─ require句の追加
   └─ clean-ns設定に従いフォーマット

6. シンボルの更新
   └─ 完全修飾名をエイリアス形式に変更
```

### フローチャート

```mermaid
flowchart TD
    A[クイックフィックス要求] --> B[シンボル解析]
    B --> C{名前空間付き?}
    C -->|Yes| D[エイリアス候補検索]
    C -->|No| E[refer候補検索]
    D --> F[使用頻度でソート]
    E --> F
    F --> G{候補あり?}
    G -->|No| H[nil返却]
    G -->|Yes| I[ns編集生成]
    I --> J[シンボル更新]
    J --> K[編集返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-37-01 | エイリアス推論 | プロジェクト内で最も使用されているエイリアスを優先 | エイリアス付きシンボルの場合 |
| BR-37-02 | common-sym参照 | common_symbols.cljの定義を参照 | プロジェクトにエイリアスがない場合 |
| BR-37-03 | refer推論 | common-refersから参照候補を検索 | refer形式のシンボルの場合 |
| BR-37-04 | 自動クリーンアップ | 追加後にclean-ns設定に従いフォーマット | clean設定が有効な場合 |
| BR-37-05 | RCFサポート | comment/RCF内ではそのフォーム内にrequireを追加 | RCF内での実行時 |

### 計算ロジック

**エイリアス候補のランキング**：
```clojure
;; 使用頻度でソートし、一意なら自動選択
(->> alias-suggestions
     (sort-by :usages-count)
     reverse)
```

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

本機能はclj-kondo解析データベースを参照のみ行う。

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 参照 | dep-graph | SELECT | エイリアス使用パターンを検索 |
| 参照 | :analysis | SELECT | 名前空間定義を検索 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 候補なし | 該当する名前空間が見つからない | 空の結果を返却 |

### リトライ仕様

リトライは行わない。

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

トランザクション管理は不要。

## パフォーマンス要件

- 応答時間: 200ms以内

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

- ファイルシステムへの書き込みは行わない

## 備考

- ClojureScript向けのJavaScript requireもサポート
- common_symbols.cljにはclojure.coreや一般的なライブラリのエイリアス情報が含まれている

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | common_symbols.clj | `lib/src/clojure_lsp/common_symbols.clj` | common-alias->info, common-refers->info |

**読解のコツ**: common_symbols.cljには、よく使われるエイリアスとその対応する名前空間のマッピングが定義されている。

#### Step 2: 候補検索を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | add_missing_libspec.clj | `lib/src/clojure_lsp/feature/add_missing_libspec.clj` | find-require-suggestions |

**主要処理フロー**:
- **63-74行目**: `find-missing-ns-alias-require` - エイリアス付きシンボルの解決
- **76-83行目**: `find-missing-ns-refer-require` - refer形式シンボルの解決
- **486-562行目**: `find-namespace-suggestions` - 名前空間候補の生成
- **572-597行目**: `find-require-suggestions` - 全候補の検索

#### Step 3: ns編集を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | add_missing_libspec.clj | `lib/src/clojure_lsp/feature/add_missing_libspec.clj` | add-to-namespace* |

**主要処理フロー**:
- **200-251行目**: `add-to-namespace*` - ns宣言への追加編集を生成
- **344-358行目**: `add-to-namespace` - 内部ヘルパー
- **613-656行目**: `add-require-suggestion` - 公開API

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

```
textDocument/codeAction (LSP)
    │
    └─ code-actions/all
           │
           ├─ find-require-suggestions
           │     ├─ find-namespace-suggestions
           │     │     ├─ dep-graph/ns-aliases-for-langs
           │     │     └─ common-sym/common-alias->info
           │     └─ find-all-require-suggestions
           │
           └─ require-suggestion-actions (コードアクション生成)
                  │
                  └─ [ユーザー選択]
                         │
                         └─ command/run-command :add-require-suggestion
                               │
                               └─ add-require-suggestion
                                     ├─ add-known-alias / add-known-refer
                                     ├─ add-to-namespace*
                                     ├─ cleaning-ns-edits
                                     └─ add-ns-to-loc-change
```

### データフロー図

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

未解決シンボル      ──▶  safe-sym                   ──▶  シンボル/エイリアス
                         (シンボル抽出)

シンボル           ──▶  find-namespace-suggestions  ──▶  [{:ns, :alias, :count}]
                         (候補検索)

候補              ──▶  require-suggestion-actions  ──▶  コードアクションリスト
                         (アクション生成)

選択された候補     ──▶  add-require-suggestion      ──▶  [{:range, :loc}]
                         (ns編集生成)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| add_missing_libspec.clj | `lib/src/clojure_lsp/feature/add_missing_libspec.clj` | ソース | require追加のコアロジック |
| common_symbols.clj | `lib/src/clojure_lsp/common_symbols.clj` | ソース | 一般的なエイリアス定義 |
| dep_graph.clj | `lib/src/clojure_lsp/dep_graph.clj` | ソース | 依存関係グラフ |
| code_actions.clj | `lib/src/clojure_lsp/feature/code_actions.clj` | ソース | コードアクション生成 |
| command.clj | `lib/src/clojure_lsp/feature/command.clj` | ソース | コマンドディスパッチ |
| add_missing_libspec_test.clj | `lib/test/clojure_lsp/feature/add_missing_libspec_test.clj` | テスト | require追加のテスト |
