# 画面設計書 1-該当なし

## 概要

本ドキュメントは、clojure-lspプロジェクトにおける「画面」の存在状況について説明するものである。本プロジェクトはLanguage Server Protocol（LSP）サーバーの実装であり、ユーザーが直接操作するUI画面は存在しない。本ドキュメントでは、プロジェクトの特性とインターフェースの構造について詳細に解説する。

### 本画面の処理概要

本プロジェクトには従来の意味での「画面」が存在しないため、代わりにLSPサーバーとしての動作概要を記載する。

**業務上の目的・背景**：clojure-lspは、Clojure/ClojureScript開発者の生産性向上を目的として開発されたLanguage Server Protocol（LSP）サーバーである。LSPは、エディタ・IDE間で共通のインターフェースを提供するプロトコルであり、言語固有の機能（コード補完、定義ジャンプ、リファクタリング等）をエディタに依存せず実装できる。本プロジェクトにより、VSCode、Emacs、Vim、IntelliJ等の多様なエディタにおいて、一貫したClojure開発体験を提供することが可能となる。UI画面はエディタ側が担当するため、本プロジェクト自体には画面実装が不要である。

**画面へのアクセス方法**：本プロジェクトは画面を持たないため、直接的な画面アクセスは存在しない。ユーザーはエディタを通じて間接的にclojure-lspの機能を利用する。CLIコマンドとしては`clojure-lsp listen`でサーバーを起動し、stdinを通じてLSPプロトコルでエディタと通信する。また、`clojure-lsp clean-ns`、`clojure-lsp diagnostics`、`clojure-lsp format`、`clojure-lsp rename`、`clojure-lsp references`、`clojure-lsp dump`などのスタンドアロンコマンドも提供される。

**主要な操作・処理内容**：
1. LSPサーバーモード（`listen`）：stdinからのJSON-RPCリクエストを受信し、LSPプロトコルに準拠したレスポンスを返却
2. コード補完（`textDocument/completion`）：カーソル位置に基づいた補完候補の提供
3. 定義ジャンプ（`textDocument/definition`）：シンボルの定義位置への移動
4. 参照検索（`textDocument/references`）：シンボルの使用箇所一覧の提供
5. リネーム（`textDocument/rename`）：シンボル名の一括変更
6. 診断（`textDocument/publishDiagnostics`）：clj-kondoによる静的解析結果の提供
7. フォーマット（`textDocument/formatting`）：cljfmtによるコード整形
8. コードアクション（`textDocument/codeAction`）：リファクタリング操作の提案

**画面遷移**：本プロジェクトには画面遷移は存在しない。LSPプロトコルを通じた状態遷移のみが存在する。サーバーは`initialize` -> `initialized` -> 各種リクエスト処理 -> `shutdown` -> `exit`というライフサイクルで動作する。

**権限による表示制御**：本プロジェクトは単一プロセスで動作するサーバーであり、ユーザー権限による制御は存在しない。ただし、クライアント（エディタ）の`capabilities`によって利用可能な機能が制限される場合がある。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| N/A | 該当なし | 該当なし | 本プロジェクトはCLIツール/ライブラリであり、UI画面に関連する機能は存在しない |

## 画面種別

該当なし（CLIツール/LSPサーバー）

## URL/ルーティング

該当なし。LSPプロトコルのメソッド名がルーティングに相当する。

主要なLSPメソッド：
- `initialize` / `initialized` / `shutdown` / `exit` - ライフサイクル管理
- `textDocument/didOpen` / `textDocument/didChange` / `textDocument/didClose` - ドキュメント同期
- `textDocument/completion` / `completionItem/resolve` - コード補完
- `textDocument/definition` / `textDocument/declaration` / `textDocument/implementation` - シンボル移動
- `textDocument/references` - 参照検索
- `textDocument/rename` / `textDocument/prepareRename` - リネーム
- `textDocument/hover` - ホバー情報
- `textDocument/codeAction` - コードアクション
- `workspace/executeCommand` - カスタムコマンド実行

## 入出力項目

本プロジェクトはLSPプロトコルに準拠したJSON-RPCインターフェースを使用する。

| 項目名 | 入/出 | 型 | 説明 |
|--------|-------|-----|------|
| JSON-RPCリクエスト | 入力 | Object | LSPプロトコルに準拠したリクエスト（method, params, id） |
| JSON-RPCレスポンス | 出力 | Object | リクエストに対するレスポンス（result, id）またはエラー（error, id） |
| JSON-RPC通知 | 双方向 | Object | 応答を期待しないメッセージ（diagnostics等） |

## 表示項目

該当なし。エディタ側のUI表示はエディタの実装に依存する。

## イベント仕様

### 1-サーバー初期化（initialize）

クライアント（エディタ）からの`initialize`リクエストを受信すると、プロジェクトの解析を開始し、サーバーの`capabilities`を返却する。

処理フロー：
1. クライアント情報、ルートURI、クライアントcapabilitiesの受信
2. プロジェクトルートの設定とclj-kondoによる静的解析の実行
3. 依存関係の解析とクラスパスの取得
4. サーバーcapabilities（対応機能一覧）の返却

### 2-ドキュメント変更（textDocument/didChange）

エディタでファイルが編集されると、変更内容がサーバーに通知される。

処理フロー：
1. 変更通知の受信（URI、変更内容、バージョン番号）
2. 内部バッファの更新
3. 非同期での再解析実行
4. 診断結果の更新と`publishDiagnostics`通知の送信

### 3-コード補完（textDocument/completion）

カーソル位置での補完候補を要求する。

処理フロー：
1. 補完リクエストの受信（URI、行・列位置）
2. カーソル位置のコンテキスト解析
3. 名前空間、関数、変数等の補完候補の生成
4. 補完アイテムリストの返却

## データベース更新仕様

該当なし。本プロジェクトはインメモリで解析データを保持し、外部データベースは使用しない。

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| N/A | 該当なし | 該当なし | データベースを使用しないため対象外 |

### テーブル別更新項目詳細

該当なし。

## メッセージ仕様

LSPプロトコルで定義されたメッセージを使用する。

| メッセージ種別 | タイプ | 内容 | 発生条件 |
|---------------|-------|------|---------|
| 初期化完了 | Info | Server initialized | initializeリクエスト処理完了時 |
| 診断結果 | Info/Warning/Error | clj-kondo解析結果 | ファイル保存/変更時 |
| プロジェクトルート未指定 | Warning | No project-root-uri was specified | ルートURIなしでの初期化時 |
| リクエストタイムアウト | Error | Timed out waiting for analysis | 解析待ちが60秒を超過した場合 |
| リクエストキャンセル | Debug | Request cancelled by client | クライアントがリクエストをキャンセルした場合 |

## 例外処理

| 例外状態 | 対処方法 |
|---------|---------|
| プロジェクトルート未指定 | 警告メッセージを表示し、機能制限モードで動作 |
| ファイル解析エラー | エラーをログに記録し、該当ファイルの解析をスキップ |
| clj-kondo解析エラー | エラーを診断メッセージとして報告 |
| クラスパス取得失敗 | 警告を記録し、限定的な解析モードで継続 |
| JSON-RPCパースエラー | エラーレスポンスを返却 |

## 備考

- 本プロジェクトはBabashka Podとしても動作可能であり、`BABASHKA_POD=true`環境変数設定時はPodモードで起動する
- nREPLサーバーを内蔵しており、開発時のデバッグに使用可能
- OpenTelemetryによるトレーシングに対応
- GraalVM Native Imageによるネイティブバイナリとしてもビルド可能

---

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

本プロジェクトを理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

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

まず、プログラム間で受け渡されるデータ構造を理解することが重要である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | db.clj | `lib/src/clojure_lsp/db.clj` | サーバーの状態を保持するatom `db*` の構造、`initial-db`の定義を理解する |
| 1-2 | shared.clj | `lib/src/clojure_lsp/shared.clj` | URI変換、位置情報変換など共通ユーティリティを把握する |

**読解のコツ**: Clojureではデータはイミュータブルなマップとして扱われる。`db*`はatomでラップされており、`@db*`でデリファレンス、`swap!`で更新する。

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

処理の起点となるファイル・関数を特定する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | main.clj | `cli/src/clojure_lsp/main.clj` | CLIのエントリーポイント。`-main`関数から処理が開始される |
| 2-2 | server.clj | `cli/src/clojure_lsp/server.clj` | LSPサーバーの本体。`run-lsp-io-server!`でサーバーを起動 |

**主要処理フロー**:
1. **250-253行目（main.clj）**: `-main`関数が`run`マクロを呼び出し
2. **226-228行目（main.clj）**: `main`関数で引数をパースし`run!`を呼び出し
3. **217-224行目（main.clj）**: `run!`関数でアクションを判定し`handle-action!`を呼び出し
4. **194-215行目（main.clj）**: `handle-action!`で各コマンドを実行
5. **672-678行目（server.clj）**: `run-lsp-io-server!`でstdio経由のサーバーを起動
6. **647-670行目（server.clj）**: `start-server!`でコンポーネントを初期化しサーバーを開始

#### Step 3: LSPリクエストハンドラを理解する

LSPプロトコルの各メソッドがどのように処理されるかを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | server.clj | `cli/src/clojure_lsp/server.clj` | `defmethod jsonrpc.server/receive-request`でLSPメソッドのディスパッチを定義 |
| 3-2 | handlers.clj | `lib/src/clojure_lsp/handlers.clj` | 各LSPメソッドの実装ロジック。`initialize`、`completion`、`definition`等 |

**主要処理フロー**:
- **549-570行目（server.clj）**: `initialize`リクエストのハンドリング
- **163-201行目（handlers.clj）**: `initialize`の実装。プロジェクト解析と初期化処理
- **278-283行目（server.clj）**: `textDocument/completion`リクエスト
- **254-268行目（handlers.clj）**: `completion`の実装

#### Step 4: 機能モジュールを理解する

各機能の詳細な実装を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | completion.clj | `lib/src/clojure_lsp/feature/completion.clj` | コード補完ロジック |
| 4-2 | rename.clj | `lib/src/clojure_lsp/feature/rename.clj` | リネーム機能の実装 |
| 4-3 | diagnostics.clj | `lib/src/clojure_lsp/feature/diagnostics.clj` | 診断機能の実装 |
| 4-4 | format.clj | `lib/src/clojure_lsp/feature/format.clj` | フォーマット機能の実装 |

**主要処理フロー**:
- 各featureモジュールは、handlersから呼び出され、dbからデータを取得して処理を行う

#### Step 5: 解析基盤を理解する

clj-kondoとの連携と解析データの管理を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | kondo.clj | `lib/src/clojure_lsp/kondo.clj` | clj-kondoとの連携。静的解析の実行 |
| 5-2 | startup.clj | `lib/src/clojure_lsp/startup.clj` | プロジェクト初期化時の解析処理 |
| 5-3 | dep_graph.clj | `lib/src/clojure_lsp/dep_graph.clj` | 名前空間の依存関係グラフ |

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

```
-main (main.clj:250)
    │
    ├─ run マクロ (main.clj:236-248)
    │      └─ main (main.clj:226-228)
    │             └─ run! (main.clj:217-224)
    │                    └─ handle-action! (main.clj:194-215)
    │                           │
    │                           ├─ [listen] server/run-lsp-io-server! (server.clj:672-678)
    │                           │      └─ start-server! (server.clj:647-670)
    │                           │             │
    │                           │             ├─ TimbreLogger作成
    │                           │             ├─ ClojureLspProducer作成
    │                           │             ├─ spawn-async-tasks! (server.clj:597-622)
    │                           │             └─ jsonrpc.server/start
    │                           │
    │                           ├─ [clean-ns] internal-api/clean-ns!
    │                           ├─ [diagnostics] internal-api/diagnostics
    │                           ├─ [format] internal-api/format!
    │                           ├─ [rename] internal-api/rename!
    │                           ├─ [references] internal-api/references
    │                           └─ [dump] internal-api/dump
    │
    └─ LSPリクエスト処理 (サーバーモード時)
           │
           ├─ initialize → handler/initialize (handlers.clj:163-201)
           │      └─ startup/initialize-project
           │             └─ clj-kondo解析実行
           │
           ├─ textDocument/completion → handler/completion (handlers.clj:254-268)
           │      └─ f.completion/completion
           │
           ├─ textDocument/definition → handler/definition (handlers.clj:288-294)
           │      └─ q/find-definition-from-cursor
           │
           └─ その他LSPメソッド → 対応するhandler関数
```

### データフロー図

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

stdin                  ┌─────────────────────────┐
  │                    │   jsonrpc.io-server     │
  │ JSON-RPC           │   (stdio-server)        │
  ▼                    └──────────┬──────────────┘
┌──────────┐                      │
│LSPリクエスト│                   ▼
│(method,  │          ┌─────────────────────────┐
│ params,  │          │   jsonrpc.server        │
│ id)      │          │   receive-request/      │          stdout
└──────────┘          │   receive-notification  │            │
                      └──────────┬──────────────┘            │
                                 │                           │
                                 ▼                           │
                      ┌─────────────────────────┐            │
                      │   handlers.clj          │            │
                      │   (各LSPメソッドの実装)   │            │
                      └──────────┬──────────────┘            │
                                 │                           │
                                 ▼                           │
                      ┌─────────────────────────┐            │
                      │   feature/*.clj         │            │
                      │   (completion, rename,  │            │
                      │    diagnostics等)       │            │
                      └──────────┬──────────────┘            │
                                 │                           │
                                 ▼                           │
                      ┌─────────────────────────┐            │
                      │   db* (atom)            │            │
                      │   - analysis            │            ▼
                      │   - documents           │    ┌──────────────┐
                      │   - settings            │    │LSPレスポンス  │
                      │   - client-capabilities │    │(result/error,│
                      └─────────────────────────┘    │ id)          │
                                 ▲                   └──────────────┘
                                 │
                      ┌─────────────────────────┐
                      │   clj-kondo             │
                      │   (静的解析エンジン)     │
                      └─────────────────────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| main.clj | `cli/src/clojure_lsp/main.clj` | ソース | CLIエントリーポイント、コマンドパーサー |
| server.clj | `cli/src/clojure_lsp/server.clj` | ソース | LSPサーバー本体、リクエストディスパッチャー |
| handlers.clj | `lib/src/clojure_lsp/handlers.clj` | ソース | LSPメソッドのハンドラ実装 |
| api.clj | `lib/src/clojure_lsp/api.clj` | ソース | 公開API定義 |
| internal_api.clj | `lib/src/clojure_lsp/internal_api.clj` | ソース | 内部API実装 |
| db.clj | `lib/src/clojure_lsp/db.clj` | ソース | サーバー状態管理 |
| startup.clj | `lib/src/clojure_lsp/startup.clj` | ソース | プロジェクト初期化処理 |
| settings.clj | `lib/src/clojure_lsp/settings.clj` | ソース | 設定管理 |
| shared.clj | `lib/src/clojure_lsp/shared.clj` | ソース | 共通ユーティリティ |
| kondo.clj | `lib/src/clojure_lsp/kondo.clj` | ソース | clj-kondo連携 |
| completion.clj | `lib/src/clojure_lsp/feature/completion.clj` | ソース | コード補完機能 |
| rename.clj | `lib/src/clojure_lsp/feature/rename.clj` | ソース | リネーム機能 |
| diagnostics.clj | `lib/src/clojure_lsp/feature/diagnostics.clj` | ソース | 診断機能 |
| format.clj | `lib/src/clojure_lsp/feature/format.clj` | ソース | フォーマット機能 |
| code_actions.clj | `lib/src/clojure_lsp/feature/code_actions.clj` | ソース | コードアクション機能 |
| hover.clj | `lib/src/clojure_lsp/feature/hover.clj` | ソース | ホバー情報機能 |
| file_management.clj | `lib/src/clojure_lsp/feature/file_management.clj` | ソース | ファイル管理機能 |
