# 機能設計書 72-プロジェクトのみ解析

## 概要

本ドキュメントは、clojure-lsp の API として提供される `analyze-project-only!` 関数の機能設計を記述する。この関数はプロジェクトのソースコードのみを解析し、外部依存関係の解析をスキップすることで高速な解析を提供する。

### 本機能の処理概要

**業務上の目的・背景**：大規模なプロジェクトや多数の依存関係を持つプロジェクトでは、フル解析に時間がかかる場合がある。プロジェクト内のコードのみを対象とした軽量な解析を行うことで、CI/CD パイプラインでの高速なフィードバックや、プロジェクト固有の問題のみを検出したい場合に有用である。

**機能の利用シーン**：CI/CD でのプロジェクト固有の lint チェック、プロジェクト内コードの名前空間クリーンアップ、外部依存への参照検索が不要な場合のリファクタリング処理など。

**主要な処理内容**：
1. プロジェクトルートの特定とバリデーション
2. プロジェクトソースパスの解析のみを実行
3. 外部依存関係（jar ファイル等）の解析をスキップ
4. 解析結果のキャッシュ

**関連システム・外部連携**：clj-kondo（静的解析）、clj-depend（依存関係検証）。外部ライブラリの解析は行わないが、クラスパス情報自体は取得可能。

**権限による制御**：呼び出し元プロセスのファイルシステム権限に依存。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 該当なし | 該当なし | 該当なし | 本プロジェクトは LSP サーバー実装であり UI 画面は存在しない |

## 機能種別

データ連携 / 計算処理 / キャッシュ管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| :project-root | java.io.File | No | プロジェクトルートディレクトリ | nil または存在するディレクトリを示す File オブジェクト |
| :settings | Map | No | clojure-lsp 設定マップ | nil または map? が true |

### 入力データソース

- ファイルシステム（プロジェクトのソースファイル群のみ）
- クラスパス情報（設定から取得、解析には使用しない）
- 既存の解析キャッシュ

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | truthy/falsey | 解析が新規実行された場合は truthy、既に解析済みの場合は falsey |

### 出力先

- 内部データベース（atom）へのキャッシュ
- ファイルシステム（.lsp/.cache ディレクトリへの永続化）

## 処理フロー

### 処理シーケンス

```
1. パラメータバリデーション
   └─ :project-root と :settings の事前条件チェック
2. コンポーネント構築
   └─ db*、logger、producer の初期化
3. API セットアップ
   └─ :api? フラグの設定
4. 既存キャッシュの確認
   └─ 解析済みならスキップ
5. プロジェクト解析タイプの設定
   └─ :project-only として設定
6. プロジェクトソースの解析
   └─ ソースパス内のファイルのみを解析（外部依存はスキップ）
7. キャッシュの更新
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{パラメータ有効?}
    B -->|No| C[AssertionError]
    B -->|Yes| D[コンポーネント構築]
    D --> E[API セットアップ]
    E --> F{既に解析済み?}
    F -->|Yes| G[nil を返却]
    F -->|No| H[project-analysis-type を :project-only に設定]
    H --> I[プロジェクトソースのみ解析]
    I --> J[キャッシュ更新]
    J --> K[truthy を返却]
    G --> L[終了]
    K --> L
    C --> L
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-72-1 | プロジェクトのみ解析 | 外部依存関係（jar ファイル等）の解析をスキップ | 常時 |
| BR-72-2 | 軽量キャッシュ | project-only 解析は full-dependencies 解析より優先度が低い | 両方のキャッシュが存在する場合 |
| BR-72-3 | 高速起動 | クラスパススキャンは行うが、外部 jar の中身は解析しない | 常時 |

### 計算ロジック

analyze-project-only! と analyze-project-and-deps! の違い：
- `:project-only`: プロジェクトソースのみ解析
- `:project-and-full-dependencies`: 全依存関係を解析

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 該当なし | 該当なし | 該当なし | RDB は使用しない |

### テーブル別操作詳細

atom によるインメモリデータベースを使用。`:project-analysis-type` が `:project-only` として記録される。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| AssertionError | バリデーションエラー | project-root が不正 | 有効な File オブジェクトを渡す |
| ExceptionInfo | 解析エラー | プロジェクト解析中のエラー | エラーメッセージを確認 |

### リトライ仕様

リトライ機構は実装されていない。

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

RDB を使用しないため、トランザクション管理は不要。

## パフォーマンス要件

- analyze-project-and-deps! と比較して大幅に高速（外部依存解析をスキップ）
- プロジェクトサイズに依存

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

- ファイルシステムアクセスはプロセス権限に依存
- 外部ライブラリのコードは解析対象外

## 備考

- 外部ライブラリへの参照検索などの機能は制限される
- コード補完で外部ライブラリのシンボルが表示されない場合がある

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | db.clj | `lib/src/clojure_lsp/db.clj` | initial-db、project-analysis-type の理解 |

**読解のコツ**: `:project-analysis-type` キーが解析タイプを示す。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | api.clj | `lib/src/clojure_lsp/api.clj` | analyze-project-only! 関数定義 |

**主要処理フロー**:
1. **55-85行目**: `analyze-project-only!` 関数定義、docstring と事前条件

#### Step 3: 内部 API 実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | internal_api.clj | `lib/src/clojure_lsp/internal_api.clj` | setup-project-only-analysis! |

**主要処理フロー**:
- **208-211行目**: setup-project-only-analysis! で :project-only タイプを設定
- **292-294行目**: analyze-project-only!* の実装

#### Step 4: プロジェクト初期化との違いを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | startup.clj | `lib/src/clojure_lsp/startup.clj` | 外部依存解析のスキップ条件 |

**主要処理フロー**:
- **268-270行目**: fast-startup? の判定で :project-only が使用される
- **293-296行目**: :project-only では analyze-external-classpath! がスキップ

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

```
api/analyze-project-only!
    |
    +-- internal-api/analyze-project-only!
            |
            +-- build-components
            |
            +-- analyze-project-only!*
                    |
                    +-- setup-api!
                    |
                    +-- setup-project-only-analysis!
                            |
                            +-- analyze!
                                    |
                                    +-- startup/initialize-project
                                            |
                                            +-- analyze-source-paths! (外部依存解析をスキップ)
```

### データフロー図

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

{:project-root File      api/analyze-project-only!            {:result truthy/falsey}
 :settings Map}          |                                    |
        |                v                                    |
        +-------------> internal-api                          |
                        |                                     |
                        v                                     |
                   :project-analysis-type を                  |
                   :project-only に設定                       |
                        |                                     |
                        v                                     |
                   ソースパスのみ解析                          |
                   (外部依存はスキップ)                        |
                        |                                     |
                        v                                     |
                   atom (db*) 更新 -----------------------> キャッシュ
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| api.clj | `lib/src/clojure_lsp/api.clj` | ソース | 公開 API 定義 |
| internal_api.clj | `lib/src/clojure_lsp/internal_api.clj` | ソース | 内部実装 |
| startup.clj | `lib/src/clojure_lsp/startup.clj` | ソース | プロジェクト初期化 |
| api_test.clj | `lib/test/clojure_lsp/api_test.clj` | テスト | API テスト |
