# 通知設計書 12-WORKSPACE_SKIP_HUGE_FILE

## 概要

本ドキュメントは、Lua Language Serverにおける「巨大ファイル解析停止」通知（WORKSPACE_SKIP_HUGE_FILE）の設計仕様を定義する。この通知は、ファイルサイズが10MBを超える巨大ファイルの解析をスキップしたことをユーザーに警告するメッセージである。

### 本通知の処理概要

**業務上の目的・背景**：Lua Language Serverはファイルの内容を解析して構文チェックや補完機能を提供するが、極端に大きなファイル（10MB超）を処理すると、メモリ消費やパフォーマンスに重大な影響を与える可能性がある。このような巨大ファイルは通常のLuaソースコードとしては異常であり、自動生成されたファイルやデータファイルである可能性が高い。パフォーマンスを維持しつつユーザーに状況を通知するため、本通知が必要である。

**通知の送信タイミング**：ファイルのテキスト設定時（`files.setText`関数呼び出し時）に、ファイルサイズが10MB（10 * 1024 * 1024バイト）を超えている場合に即座に送信される。

**通知の受信者**：LSPクライアント（VSCode等のエディタ）を通じてユーザーに表示される。警告メッセージとしてエディタのUI上にポップアップ表示される。

**通知内容の概要**：「パフォーマンスのため、ファイル {uri} の解析を停止しました。」というメッセージが表示され、どのファイルがスキップされたかを明示する。

**期待されるアクション**：ユーザーは該当ファイルが解析対象外となったことを認識し、必要に応じてファイルを分割するか、設定で除外パターンを追加することが期待される。

## 通知種別

アプリ内通知（LSP Window Message - Warning）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期 |
| 優先度 | 高 |
| リトライ | なし |

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

LSPプロトコルに従い、接続中のLSPクライアントに対してwindow/showMessage通知を送信する。受信者の決定は不要（接続中のクライアントすべてに送信）。

## 通知テンプレート

### メッセージ通知の場合

| 項目 | 内容 |
|-----|------|
| 通知タイプ | window/showMessage |
| メッセージタイプ | Warning（警告） |

### 本文テンプレート

```
パフォーマンスのため、ファイル {uri} の解析を停止しました。
```

### 添付ファイル

なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| uri | 対象ファイルのURI | files.setText関数の引数 | Yes |
| lang.script.WORKSPACE_SKIP_HUGE_FILE | メッセージテンプレート | locale/ja-jp/script.lua | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| ファイル設定 | files.setText呼び出し | #text > 10MB | ファイルサイズが10MBを超える場合 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| ファイルサイズ <= 10MB | 通常サイズのファイルは処理対象 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[files.setText呼び出し] --> B{text引数がnil?}
    B -->|Yes| Z[処理終了]
    B -->|No| C{ファイルサイズ > 10MB?}
    C -->|No| D[通常のファイル処理継続]
    C -->|Yes| E[client.showMessage呼び出し]
    E --> F[Warning: WORKSPACE_SKIP_HUGE_FILE]
    F --> G[return - ファイル処理中止]
    D --> H[ファイルマップに登録]
    H --> I[テキスト設定完了]
```

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

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| なし | - | ファイルサイズのみチェック |

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| なし | - | 巨大ファイルは登録されない |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| ファイルサイズ超過 | 10MB超のファイル | 警告表示後、処理中止 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | なし（同一ファイルは一度のみ） |
| 1日あたり上限 | なし |

### 配信時間帯

制限なし（ファイルオープン時）

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

- ファイルURIがメッセージに含まれるが、ローカル表示のみで外部送信なし
- 巨大ファイルの内容は読み込まれないため、メモリ攻撃を防止

## 備考

- 10MBの閾値はハードコードされており、設定で変更不可
- WORKSPACE_SKIP_LARGE_FILE（プリロード制限）とは異なる通知
- 巨大ファイルは完全にスキップされ、files.fileMapに登録されない

---

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

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

### 推奨読解順序

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

ファイル管理の基本構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | files.lua | `script/files.lua` | fileMapとファイル管理の基本構造 |

**読解のコツ**: files.fileMapがファイルキャッシュの中核であることを把握する。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | files.lua | `script/files.lua` | setText関数（行233-303） |

**主要処理フロー**:
1. **行233**: `function m.setText(uri, text, isTrust, callback)` - 関数定義
2. **行234-236**: textがnilの場合は早期リターン
3. **行237-241**: ファイルサイズチェックと警告表示
4. **行239**: `client.showMessage('Warning', lang.script('WORKSPACE_SKIP_HUGE_FILE', uri))` - 通知送信

#### Step 3: 言語リソースを理解する

通知メッセージの定義を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | script.lua | `locale/ja-jp/script.lua` | WORKSPACE_SKIP_HUGE_FILE定義（行212-213） |

**主要処理フロー**:
- **行212-213**: `WORKSPACE_SKIP_HUGE_FILE = 'パフォーマンスのため、ファイル {} の解析を停止しました。'`

#### Step 4: クライアント通知を理解する

client.showMessageの実装を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | client.lua | `script/client.lua` | showMessage関数（行102-113） |

**主要処理フロー**:
- **行102-113**: window/showMessageとwindow/logMessage通知の送信

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

```
files.lua
    │
    └─ m.setText(uri, text, isTrust, callback)
           │
           ├─ サイズチェック: #text > 1024 * 1024 * 10
           │      │
           │      └─ client.showMessage('Warning', ...)
           │             │
           │             └─ proto.notify('window/showMessage', ...)
           │
           └─ return (ファイル処理中止)
```

### データフロー図

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

ファイルURI ─────────▶ files.setText()
ファイルテキスト ────┘       │
                            ▼
                   サイズチェック (#text > 10MB)
                            │
                            ▼ (サイズ超過時)
                   lang.script('WORKSPACE_SKIP_HUGE_FILE', uri)
                            │
                            ▼
                   client.showMessage() ───▶ window/showMessage通知
                            │
                            ▼
                   return (処理中止) ───▶ ファイル未登録
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| files.lua | `script/files.lua` | ソース | ファイル管理・setText関数 |
| client.lua | `script/client.lua` | ソース | クライアント通知機能 |
| script.lua | `locale/ja-jp/script.lua` | 言語リソース | 日本語メッセージ定義 |
| proto.lua | `script/proto/proto.lua` | ソース | LSPプロトコル通信 |
| define.lua | `script/proto/define.lua` | ソース | メッセージタイプ定義 |
