# 機能設計書 83-参照検索

## 概要

本ドキュメントは、clojure-lspのCLI（コマンドラインインターフェース）から実行するシンボル参照検索機能の設計書である。指定したシンボルの全参照箇所をプロジェクト全体および依存関係から検索する。

### 本機能の処理概要

この機能は、CLIコマンド `clojure-lsp references` を通じて、Clojureプロジェクト内の指定されたシンボル（関数、変数、名前空間など）の全ての参照箇所を検索し、位置情報を出力する。依存関係内の参照も含めて検索可能。

**業務上の目的・背景**：大規模なClojureプロジェクトにおいて、特定のシンボルがどこで使用されているかを把握することは、影響範囲の分析、リファクタリング計画、コードレビューなどで重要である。本機能により、プロジェクト全体と依存関係を含めた包括的な参照検索が可能となる。

**機能の利用シーン**：
- リファクタリング前の影響範囲調査
- 未使用関数や変数の検出補助
- コードベースの理解・調査
- 依存関係における使用箇所の確認
- スクリプトやCI/CDパイプラインでの自動分析

**主要な処理内容**：
1. コマンドライン引数の解析（--from: 検索対象シンボル）
2. プロジェクトの解析（依存関係を含む完全解析）
3. 指定シンボルの定義と全参照箇所の検索
4. 検索結果の出力（URI:行:列 形式）

**関連システム・外部連携**：
- clj-kondo: シンボル解析に使用
- 依存関係のJARファイル: 外部ライブラリの解析

**権限による制御**：権限による制御は行わない。読み取り権限のみ必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 該当なし | 該当なし | 該当なし | CLIから実行されるため画面は存在しない |

## 機能種別

検索処理 / 参照解析

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| --from | Symbol | Yes | 検索対象の完全修飾シンボル名（例: my-project/my-var） | 有効なClojureシンボル形式 |
| --project-root, -p | Path | No | プロジェクトルートパス | 存在するディレクトリであること |
| --raw | Boolean | No | 必要最小限の出力（デフォルト: false） | - |
| --settings, -s | EDN | No | 追加設定（EDN形式） | 有効なEDNマップ |
| --analysis | EDN | No | 解析タイプの指定 | :type キーに有効な解析タイプ |

### 入力データソース

- ファイルシステム上のClojureソースファイル
- clj-kondo解析結果（シンボル定義・参照情報）
- 依存関係のJARファイル（--analysisで指定時）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| result-code | Integer | 実行結果コード（0: 成功、1: エラー） |
| message-fn | Function | 結果メッセージを生成する関数 |
| references | Vector | 参照要素のリスト |

### 出力先

- 標準エラー出力: 進捗メッセージ
- 標準出力: 参照一覧（URI:行:列 形式、改行区切り）

## 処理フロー

### 処理シーケンス

```
1. コマンドライン引数の解析
   └─ --from の必須チェック

2. コンポーネントの初期化
   └─ CLILogger、APIProducerの生成

3. プロジェクト解析の実行
   └─ :project-and-full-dependencies タイプで完全解析

4. シンボルの検索
   └─ from シンボルの定義を特定

5. 参照検索の実行
   └─ find-references で全参照を取得

6. 結果の出力
   └─ URI:行:列 形式で出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始: references コマンド実行] --> B[引数解析]
    B --> C{--from あり?}
    C -->|No| D[エラー: 必須オプション不足]
    C -->|Yes| E[コンポーネント初期化]
    E --> F[プロジェクト解析<br/>依存関係含む]
    F --> G[シンボル検索]
    G --> H{シンボル見つかった?}
    H -->|No| I[エラー: シンボル未発見]
    H -->|Yes| J[参照検索実行]
    J --> K[結果フォーマット]
    K --> L[URI:行:列 形式で出力]
    L --> M[result-code: 0]
    I --> N[result-code: 1]
    D --> N
    M --> O[終了]
    N --> O
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-83-1 | 名前空間のみ検索 | from が simple-symbol? の場合は名前空間定義を検索 | from に "/" がない場合 |
| BR-83-2 | 解析タイプ | デフォルトは :project-and-full-dependencies | --analysis 未指定時 |
| BR-83-3 | 定義を含む | 参照検索結果に定義自体も含める | include-declaration = true |

### 計算ロジック

出力フォーマット:
- 各参照について `URI:行:列` の形式で出力
- 行番号・列番号は参照の name-row, name-col から取得
- 改行（System/lineSeparator）で区切って出力

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

該当なし（ファイルシステムのみ操作）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 1 | 引数エラー | --from が未指定 | エラーメッセージを表示して終了 |
| 1 | シンボル未発見 | 指定されたシンボルがプロジェクト内に存在しない | エラーメッセージを表示して終了 |

### リトライ仕様

リトライは行わない。エラー発生時は即座に終了する。

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

該当なし（読み取り専用処理）

## パフォーマンス要件

- 依存関係を含む完全解析のため、初回実行時は時間がかかる場合がある
- 解析結果はキャッシュされ、2回目以降は高速に動作

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

- 読み取り専用操作のためセキュリティリスクは低い
- 依存関係のJARファイルを読み取る場合がある

## 備考

- --analysis オプションで解析タイプを変更可能
  - :project-and-full-dependencies: 依存関係を含む完全解析（デフォルト）
  - :project-and-shallow-analysis: 浅い依存関係解析
  - :project-only: プロジェクトのみ

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | cli-spec | `cli/src/clojure_lsp/main.clj` | --from オプションと --analysis オプションの定義 |
| 1-2 | element構造 | `lib/src/clojure_lsp/queries.clj` | 参照要素のデータ構造（uri, name-row, name-col など） |

**読解のコツ**: 参照要素は clj-kondo の解析結果から取得される。`:bucket` キーでシンボルタイプを識別。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | main.clj | `cli/src/clojure_lsp/main.clj` | referencesコマンドの実行フロー |

**主要処理フロー**:
1. **209-212行目**: `"references"` コマンドで `with-required-options` を経由して `internal-api/references` を呼び出し
2. **37行目**: ヘルプメッセージでの説明「Find all references of a full qualified symbol...」

#### Step 3: internal-api層を理解する

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

**主要処理フロー**:
- **438-454行目**: `references*` 関数 - 参照検索処理の本体
- **440行目**: `dynamic-setup-project-analysis!` でデフォルト :project-and-full-dependencies
- **441-446行目**: シンボルの名前空間と名前を分離、simple-symbol? で判定
- **447行目**: `q/find-element-from-sym` でシンボル定義を検索
- **448行目**: `q/find-references` で全参照を取得

#### Step 4: 出力フォーマットを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | internal_api.clj | `lib/src/clojure_lsp/internal_api.clj` | element->string 関数 |

**主要処理フロー**:
- **434-436行目**: `element->string` 関数 - URI:行:列 形式への変換
- **450-452行目**: message-fn でフォーマットして出力

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

```
main/-main
    │
    └─ main/run!
           │
           └─ main/handle-action!
                  │
                  └─ main/with-required-options
                         │
                         └─ internal-api/references
                                │
                                ├─ internal-api/build-components
                                │
                                └─ internal-api/references*
                                       │
                                       ├─ internal-api/dynamic-setup-project-analysis!
                                       │
                                       ├─ q/find-element-from-sym
                                       │
                                       └─ q/find-references
```

### データフロー図

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

--from シンボル ────▶ find-element-from-sym ──▶ element
                              │
                              ▼
プロジェクト解析 ───▶ find-references ──────▶ references リスト
(依存関係含む)                │
                              ▼
                       element->string ──────▶ URI:行:列 形式
                              │
                              ▼
                       string/join ───────────▶ 改行区切りテキスト
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| main.clj | `cli/src/clojure_lsp/main.clj` | ソース | CLIエントリーポイント |
| internal_api.clj | `lib/src/clojure_lsp/internal_api.clj` | ソース | CLI用API実装 |
| queries.clj | `lib/src/clojure_lsp/queries.clj` | ソース | シンボル検索・参照検索クエリ |
| startup.clj | `lib/src/clojure_lsp/startup.clj` | ソース | プロジェクト解析初期化 |
