# 通知設計書 7-workspace/didRenameFiles

## 概要

本ドキュメントは、LSP(Language Server Protocol)におけるworkspace/didRenameFiles通知の設計仕様を記載する。クライアントからサーバーへ送信される通知であり、ファイル名が変更されたことをサーバーに通知する。

### 本通知の処理概要

workspace/didRenameFiles通知は、ファイルシステム上でファイルがリネームされた後に、クライアントからclojure-lspサーバーへ送信される通知である。この通知は、workspace/willRenameFilesリクエストの後に送信され、ファイルリネームの完了をサーバーに伝える。

**業務上の目的・背景**：Clojureプロジェクトでは、ファイル名と名前空間名が密接に関連している。ファイルがリネームされた際、サーバーは古いファイルの解析データをクリーンアップし、プロジェクト全体の整合性を保つ必要がある。なお、名前空間のリネームはwillRenameFilesリクエストで先行処理されるため、この通知では主にクリーンアップ処理が行われる。

**通知の送信タイミング**：ファイルリネーム操作が完了した直後に、エディタ(LSPクライアント)がこの通知を送信する。willRenameFilesリクエストへのレスポンス（ワークスペース編集）が適用された後に送信される。

**通知の受信者**：clojure-lspサーバープロセスがこの通知を受信する。サーバーは非同期（eventually）で処理を実行する。

**通知内容の概要**：通知には、リネームされたファイルの旧URIと新URIのペアのリストが含まれる。

**期待されるアクション**：サーバーは受信後、旧URIに関連するデータ（ドキュメント情報、解析結果、診断情報）をDBから削除し、空の診断情報を旧URIに対して公開する。新しいファイルの解析は、didChangeWatchedFiles通知またはdidOpen通知で別途処理される。

## 通知種別

LSP通知 (クライアント → サーバー)

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 非同期（eventually） |
| 優先度 | 中（リネーム後処理） |
| リトライ | なし（通知のため応答なし） |

### 送信先決定ロジック

クライアントからサーバーへの一方向通知のため、送信先決定ロジックは不要。

## 通知テンプレート

### パラメータ構造

| 項目 | 内容 |
|-----|------|
| メソッド名 | workspace/didRenameFiles |
| パラメータ型 | RenameFilesParams |
| プロトコル | JSON-RPC 2.0 over stdio |

### パラメータ定義

```json
{
  "files": [
    {
      "oldUri": "file:///path/to/old_name.clj",
      "newUri": "file:///path/to/new_name.clj"
    }
  ]
}
```

### 添付ファイル

該当なし（LSP通知にファイル添付機能なし）

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| files | リネームファイルリスト | クライアント（ファイル操作） | Yes |
| files[].oldUri | 旧ファイルURI | クライアント | Yes |
| files[].newUri | 新ファイルURI | クライアント | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| ファイル操作 | ファイルリネーム | リネーム完了後 | エクスプローラーでのリネーム |
| ファイル操作 | ファイル移動 | 移動完了後 | エクスプローラーでのドラッグ&ドロップ |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| サーバー未接続 | LSPサーバーが起動していない/接続されていない場合 |
| 非対象ファイル | globパターン（**/*.{clj,cljs,cljc,cljd,edn,bb,clj_kondo}）に一致しないファイル |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[ファイルリネーム完了] --> B[workspace/didRenameFiles通知送信]
    B --> C[サーバーで受信]
    C --> D[handler/did-rename-filesを呼び出し]
    D --> E[files-deleted処理]
    E --> F[旧URIのドキュメント削除]
    F --> G[旧URIの解析結果削除]
    G --> H[旧URIの診断情報削除]
    H --> I[依存グラフ更新]
    I --> J[空の診断情報公開]
    J --> K[関連ファイル通知]
    K --> L[終了]
```

## データベース参照・更新仕様

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| db/analysis | 解析結果の参照 | 参照ファイル通知用 |

### テーブル別参照項目詳細

#### db/analysis

| 参照項目（カラム名） | 用途 | 取得条件 |
|-------------------|------|---------|
| [:analysis old-uri] | 旧ファイルの解析結果 | キー: old-uri |

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| db/documents | DELETE | 旧URIのドキュメント情報削除 |
| db/analysis | DELETE | 旧URIの解析結果削除 |
| db/diagnostics | DELETE | 旧URIの診断情報削除 |
| db/dep-graph | UPDATE | 依存グラフから旧URI削除 |

#### 削除処理詳細（db-without-uri関数）

| 操作 | 項目（カラム名） | 備考 |
|-----|-----------------|------|
| DISSOC | [:documents old-uri] | ドキュメント情報削除 |
| DISSOC | [:analysis old-uri] | 解析結果削除 |
| DISSOC | [:diagnostics :clj-kondo old-uri] | 診断情報削除 |
| UPDATE | dep-graph | 依存グラフから削除 |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| URI解決エラー | 無効なファイルパス | ログ出力して処理継続 |
| DB更新エラー | アトム操作失敗 | 例外処理で対応 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0（通知のためリトライなし） |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | なし |
| 1日あたり上限 | なし |

### 配信時間帯

制限なし（常時処理可能）

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

- ファイルパス(URI)はユーザーのローカルファイルシステム上のパスを含む
- 旧ファイルの解析データが削除されるため、リネーム操作は慎重に行う必要がある

## 備考

- LSP仕様: https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#workspace_didRenameFiles
- この通知は応答を返さない(notification)
- 名前空間のリネームはwillRenameFilesリクエストで処理される（この通知の前に実行）
- サーバーのcapabilitiesでdidRenameのフィルターが設定される（known-files-pattern）

---

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

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

### 推奨読解順序

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | server.clj | `cli/src/clojure_lsp/server.clj` | capabilities定義のworkspace.file-operations |

**読解のコツ**: willRenameFilesとdidRenameFilesの違いを理解すること。willは事前処理（編集提案）、didは事後処理（クリーンアップ）。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | server.clj | `cli/src/clojure_lsp/server.clj` | receive-notification multimethod定義 |

**主要処理フロー**:
1. **485-488行目**: `workspace/didRenameFiles`メソッドのdefmethod定義
2. **486-488行目**: handler/did-rename-filesへの委譲、eventually内で実行

#### Step 3: ハンドラー層を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | handlers.clj | `lib/src/clojure_lsp/handlers.clj` | did-rename-files関数の定義 |

**主要処理フロー**:
- **530-533行目**: did-rename-files関数本体
- **533行目**: f.file-management/did-rename-filesへの委譲

#### Step 4: ファイル管理機能層を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | file_management.clj | `lib/src/clojure_lsp/feature/file_management.clj` | did-rename-files関数 |
| 4-2 | file_management.clj | `lib/src/clojure_lsp/feature/file_management.clj` | files-deleted関数 |

**主要処理フロー**:
- **413-414行目**: did-rename-files関数本体
- **414行目**: files-deleted関数の呼び出し（旧URIのみ）
- **319-323行目**: files-deleted関数

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

```
jsonrpc.server/receive-notification "workspace/didRenameFiles"
    |
    +-- server.clj (485-488行目)
           |
           +-- eventually (非同期)
                  |
                  +-- handler/did-rename-files (handlers.clj 530-533行目)
                         |
                         +-- f.file-management/did-rename-files (file_management.clj 413-414行目)
                                |
                                +-- files-deleted (319-323行目)
                                       |
                                       +-- db-without-uri (312-317行目)
                                       |      +-- dep-graph/remove-doc
                                       |      +-- dissoc [:documents uri]
                                       |      +-- dissoc [:analysis uri]
                                       |      +-- dissoc [:diagnostics :clj-kondo uri]
                                       |
                                       +-- publish-empty-diagnostics! (321行目)
                                       +-- notify-references (322-323行目)
```

### データフロー図

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

RenameFilesParams
    |
    +-- files -------+
         |           |
         +-- oldUri  +---> 旧URIリストを抽出 (mapv :old-uri files)
         +-- newUri        |
                           v
                    files-deleted (旧URIのみ処理)
                           |
                           +---> db-without-uri
                           |           |
                           |           +---> dep-graph/remove-doc
                           |           +---> dissoc [:documents old-uri]
                           |           +---> dissoc [:analysis old-uri]
                           |           +---> dissoc [:diagnostics :clj-kondo old-uri]
                           |
                           +---> publish-empty-diagnostics!
                           |           |
                           |           v
                           |     textDocument/publishDiagnostics (空)
                           |
                           +---> notify-references
                                        |
                                        v
                                  関連ファイル再解析
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| server.clj | `cli/src/clojure_lsp/server.clj` | ソース | LSPサーバーのエントリーポイント、通知受信、capabilities設定 |
| handlers.clj | `lib/src/clojure_lsp/handlers.clj` | ソース | 各種LSPメッセージのハンドラー |
| file_management.clj | `lib/src/clojure_lsp/feature/file_management.clj` | ソース | ファイル管理機能の実装 |
| dep_graph.clj | `lib/src/clojure_lsp/dep_graph.clj` | ソース | 依存グラフの管理 |
| diagnostics.clj | `lib/src/clojure_lsp/feature/diagnostics.clj` | ソース | 診断情報の公開 |
