# 帳票設計書 6-references

## 概要

本ドキュメントは、clojure-lspのreferences（参照）機能によって出力される帳票の設計仕様を定義する。

### 本帳票の処理概要

references帳票は、指定シンボルの参照一覧を出力する帳票である。プロジェクト内および依存関係内の全参照箇所を`uri:row:col`形式で表示する。完全修飾シンボル名を指定することで、そのシンボルが使用されている全ての箇所を特定できる。

**業務上の目的・背景**：大規模なClojureプロジェクトでは、関数や変数がどこで使用されているかを把握することが、影響範囲の分析やリファクタリング計画において重要である。本帳票は、指定したシンボルの全参照箇所を網羅的にリストアップし、コード変更の影響範囲特定、デッドコード検出、依存関係分析を支援することを目的とする。

**帳票の利用シーン**：本帳票は以下の場面で利用される。(1) リファクタリング前の影響範囲調査、(2) API変更時の影響箇所特定、(3) 関数/変数の使用状況確認、(4) デッドコード候補の検出、(5) 依存ライブラリ内での使用箇所確認。

**主要な出力内容**：
1. 参照元ファイルのURI
2. 参照箇所の行番号
3. 参照箇所の列番号
4. 参照要素の詳細情報（API経由）

**帳票の出力タイミング**：CLIコマンド`clojure-lsp references --from <symbol>`の実行時、またはAPI経由での`clojure-lsp.api/references`関数呼び出し時に出力される。

**帳票の利用者**：開発者、テックリード、コードレビュアー

## 帳票種別

参照一覧レポート / 検索結果レポート

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| CLI-01 | コマンドライン | `clojure-lsp references --from <symbol>` | コマンド実行 |
| API-01 | Clojure REPL | `(clojure-lsp.api/references opts)` | 関数呼び出し |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | テキスト（uri:row:col形式） |
| 用紙サイズ | N/A（コンソール出力） |
| 向き | N/A |
| ファイル名 | 標準出力 |
| 出力方法 | 標準出力 |
| 文字コード | UTF-8 |

### 出力フォーマット詳細

#### テキスト形式（CLI）
```
file:///path/to/project/src/my_project/core.clj:15:3
file:///path/to/project/src/my_project/api.clj:42:10
file:///path/to/project/test/my_project/core_test.clj:8:5
```

#### API戻り値形式
```clojure
{:result-code 0
 :message-fn #function
 :references [{:name my-function
               :uri "file:///path/to/file.clj"
               :name-row 15
               :name-col 3
               :name-end-row 15
               :name-end-col 14
               :bucket :var-usages
               :to my-project.core
               ...}
              ...]}
```

## 帳票レイアウト

### レイアウト概要

1行1参照の形式で参照箇所を出力。

```
┌─────────────────────────────────────────────────────────────────┐
│  file:///path/to/file1.clj:10:5                                 │
│  file:///path/to/file2.clj:25:12                                │
│  file:///path/to/file3.clj:42:8                                 │
│  ...                                                            │
└─────────────────────────────────────────────────────────────────┘
```

### 出力項目

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | URI | 参照元ファイルのURI | element.uri | file://形式 |
| 2 | 行番号 | 参照箇所の行 | element.name-row | 整数 |
| 3 | 列番号 | 参照箇所の列 | element.name-col | 整数 |

### API戻り値の詳細項目

| 項目名 | 説明 | 型 |
|-------|------|-----|
| name | シンボル名 | symbol |
| uri | ファイルURI | string |
| name-row | 行番号 | integer |
| name-col | 列番号 | integer |
| name-end-row | 終了行番号 | integer |
| name-end-col | 終了列番号 | integer |
| bucket | 要素タイプ | keyword |
| to | 参照先名前空間 | symbol |
| from | 参照元名前空間 | symbol |
| alias | 使用エイリアス | symbol (optional) |

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| from | 検索対象シンボル（完全修飾名） | Yes |
| project-root | プロジェクトルートディレクトリ | No（デフォルト: カレントディレクトリ） |
| analysis.type | 解析タイプ | No（デフォルト: :project-and-full-dependencies） |

### analysis.typeオプション

| 値 | 説明 |
|---|------|
| :project-only | プロジェクトのみ検索 |
| :project-and-shallow-analysis | プロジェクト＋浅い依存検索 |
| :project-and-full-dependencies | プロジェクト＋全依存検索（デフォルト） |

### ソート順

| 優先度 | 項目 | 昇順/降順 |
|-------|------|---------|
| 1 | URI | 昇順 |
| 2 | 行番号 | 昇順 |
| 3 | 列番号 | 昇順 |

### 改ページ条件

N/A（コンソール出力のため）

## データベース参照仕様

### 参照テーブル一覧

| テーブル名 | 用途 | 結合条件 |
|-----------|------|---------|
| db.analysis | シンボル解析データ | URI, name, ns |

### 解析データ詳細

| 参照項目 | 用途 | 検索条件 |
|---------|------|---------|
| var-definitions | 定義の検索 | ns, name |
| var-usages | 使用箇所の検索 | to, name |
| namespace-definitions | 名前空間定義の検索 | name |
| namespace-usages | 名前空間使用の検索 | to |
| keyword-definitions | キーワード定義の検索 | ns, name |
| keyword-usages | キーワード使用の検索 | ns, name |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| result-code | 成功:0, 失敗:1 | - | 終了コード |
| element | q/find-element-from-sym(db, ns, name) | - | シンボル検索 |
| references | q/find-references(db, element, true) | - | 参照一覧取得 |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[referencesコマンド実行] --> B[オプション解析]
    B --> C{from指定あり?}
    C -->|No| D[エラー: Missing required option]
    C -->|Yes| E[プロジェクト解析初期化]
    E --> F[解析タイプに応じた解析実行]
    F --> G[シンボル検索]
    G --> H{シンボル存在?}
    H -->|No| I[エラー: Symbol not found]
    H -->|Yes| J[参照一覧取得]
    J --> K[参照情報をuri:row:col形式に変換]
    K --> L[出力]
    L --> M[終了]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| 必須オプション不足 | fromオプション未指定 | Missing required --from option for this command | --fromオプション指定 |
| シンボル未発見 | fromシンボルが存在しない | Symbol X not found in project | シンボル名確認 |
| プロジェクト解析失敗 | 不正なプロジェクト構成 | Error during project analysis | プロジェクト設定確認 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | 数十〜数百参照 |
| 目標出力時間 | 解析完了後: 数秒以内 |
| 同時出力数上限 | 1（シングルスレッド処理） |

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

- ファイルパス（URI）が出力されるため、機密性の高いパス情報に注意
- 依存ライブラリの解析情報も含まれる可能性あり

## 備考

- 完全修飾シンボル名（`namespace/name`形式）のみ対応
- 依存ライブラリ内の参照も検索可能（analysis.typeに依存）
- LSPサーバーモードでは`textDocument/references`として提供

---

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

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

### 推奨読解順序

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

references機能で扱われる主要なデータ構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | queries.clj | `lib/src/clojure_lsp/queries.clj` | 参照要素の構造（bucket, name, uri等） |
| 1-2 | db.clj | `lib/src/clojure_lsp/db.clj` | `db.analysis`の構造 |

**読解のコツ**: clj-kondoの解析結果構造を理解することが重要。各要素はbucket（:var-usages, :var-definitions等）でカテゴライズされている。

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

CLIからの呼び出しフローを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | main.clj | `cli/src/clojure_lsp/main.clj` | **176行目**: `"references"`アクション分岐 |
| 2-2 | main.clj | `cli/src/clojure_lsp/main.clj` | **209-212行目**: `with-required-options`でfromチェック |

**主要処理フロー**:
1. **156-180行目**: `parse`関数でコマンドライン引数を解析
2. **187-192行目**: `with-required-options`で必須オプション確認
3. **209-212行目**: referencesの場合`internal-api/references`を呼び出し

#### Step 3: 公開API層を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | api.clj | `lib/src/clojure_lsp/api.clj` | **249-291行目**: `references`関数定義とドキュメント |

**主要処理フロー**:
- **249-252行目**: 関数シグネチャと目的の説明
- **253-280行目**: オプションと出力形式の詳細ドキュメント
- **281-291行目**: 前提条件チェックと実行

#### Step 4: 内部API層を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | internal_api.clj | `lib/src/clojure_lsp/internal_api.clj` | **434-436行目**: `element->string`関数 |
| 4-2 | internal_api.clj | `lib/src/clojure_lsp/internal_api.clj` | **438-454行目**: `references*`関数 |

**主要処理フロー**:
- **439行目**: `setup-api!`でAPI初期化
- **440行目**: `dynamic-setup-project-analysis!`で解析タイプに応じた解析
- **443-446行目**: fromシンボルからns/name抽出
- **447行目**: `q/find-element-from-sym`でシンボル検索
- **448行目**: `q/find-references`で参照一覧取得
- **450-452行目**: 結果をuri:row:col形式に変換

#### Step 5: 参照検索のコア処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | queries.clj | `lib/src/clojure_lsp/queries.clj` | `find-element-from-sym`関数 |
| 5-2 | queries.clj | `lib/src/clojure_lsp/queries.clj` | `find-references`関数 |

**主要処理フロー**:
- `find-element-from-sym`: 名前空間とシンボル名からelement（定義）を検索
- `find-references`: elementの全参照箇所を検索（include-definition=trueで定義も含む）

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

```
clojure-lsp.main/-main
    |
    +-- parse (コマンド解析)
    |
    +-- with-required-options (fromチェック)
    |
    +-- handle-action!
           |
           +-- clojure-lsp.internal-api/references
                  |
                  +-- build-components (コンポーネント初期化)
                  |
                  +-- references*
                         |
                         +-- setup-api!
                         |
                         +-- dynamic-setup-project-analysis!
                         |      |
                         |      +-- :project-and-full-dependencies (デフォルト)
                         |      +-- :project-and-shallow-analysis
                         |      +-- :project-only
                         |
                         +-- q/find-element-from-sym
                         |      |
                         |      +-- find-first (analysis検索)
                         |
                         +-- q/find-references
                         |      |
                         |      +-- find-all-references (全バケット検索)
                         |
                         +-- element->string (uri:row:col変換)
                         |
                         +-- string/join (出力生成)
```

### データフロー図

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

--from symbol ────────▶ parse ────────────────────────▶ from-ns, from-name
     |                                                      |
     v                                                      v
analysis.type ────────▶ dynamic-setup-project-analysis! ──▶ db (analysis)
     |                                                      |
     v                                                      v
from-ns/name ─────────▶ find-element-from-sym ────────▶ element
     |                                                      |
     v                                                      v
element ──────────────▶ find-references ──────────────▶ [reference ...]
     |                                                      |
     v                                                      v
reference ────────────▶ element->string ──────────────▶ "uri:row:col"
     |                                                      |
     v                                                      v
[strings] ────────────▶ string/join ──────────────────▶ stdout
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| main.clj | `cli/src/clojure_lsp/main.clj` | ソース | CLIエントリーポイント |
| api.clj | `lib/src/clojure_lsp/api.clj` | ソース | 公開API定義 |
| internal_api.clj | `lib/src/clojure_lsp/internal_api.clj` | ソース | 内部API実装 |
| queries.clj | `lib/src/clojure_lsp/queries.clj` | ソース | 参照検索コア |
| handlers.clj | `lib/src/clojure_lsp/handlers.clj` | ソース | LSPハンドラ |
| db.clj | `lib/src/clojure_lsp/db.clj` | ソース | データベース定義 |
| dep_graph.clj | `lib/src/clojure_lsp/dep_graph.clj` | ソース | 依存関係グラフ |
| shared.clj | `lib/src/clojure_lsp/shared.clj` | ソース | 共通ユーティリティ |
| references_test.clj | `cli/integration-test/integration/api/references_test.clj` | テスト | references API統合テスト |
