# 通知設計書 13-WORKSPACE_NOT_ALLOWED

## 概要

本ドキュメントは、Lua Language Serverにおける「ワークスペース読み込み拒否」通知（WORKSPACE_NOT_ALLOWED）の設計仕様を定義する。この通知は、ワークスペースのルートディレクトリがシステムの重要なディレクトリ（ルートディレクトリやホームディレクトリ）に設定されている場合に、セキュリティ上の理由から読み込みを拒否したことをユーザーに警告するエラーメッセージである。

### 本通知の処理概要

**業務上の目的・背景**：ワークスペースがシステムのルートディレクトリ（`/`）やユーザーのホームディレクトリに設定されている場合、言語サーバーが大量のファイルをスキャンしようとし、システムパフォーマンスに深刻な影響を与える可能性がある。また、意図しないファイルへのアクセスやインデックス化によるセキュリティリスクも存在する。このような危険な設定を検出し、ユーザーに警告して適切な設定を促すために本通知が必要である。

**通知の送信タイミング**：ワークスペースの作成時（`workspace.create`関数呼び出し時）に、ワークスペースのURIがルートディレクトリ（`/`）またはホームディレクトリ（`$HOME`）と一致する場合に送信される。

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

**通知内容の概要**：「ワークスペースが `{path}` に設定されているため、Lua言語サービスがこのディレクトリの読み込みを拒否しました。設定を確認してください。」というメッセージが表示され、FAQへのリンクも含まれる。

**期待されるアクション**：ユーザーはワークスペースの設定を確認し、適切なプロジェクトディレクトリを指定するか、FAQを参照して問題を解決することが期待される。

## 通知種別

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

## 送信仕様

### 基本情報

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

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

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

## 通知テンプレート

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

| 項目 | 内容 |
|-----|------|
| 通知タイプ | window/showMessage |
| メッセージタイプ | Error（エラー） |

### 本文テンプレート

```
ワークスペースが `{path}` に設定されているため、Lua言語サービスがこのディレクトリの読み込みを拒否しました。設定を確認してください。[詳細はこちら](https://luals.github.io/wiki/faq#why-is-the-server-scanning-the-wrong-folder)
```

### 添付ファイル

なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| path | 拒否されたディレクトリパス | furi.decode(uri) | Yes |
| lang.script.WORKSPACE_NOT_ALLOWED | メッセージテンプレート | locale/ja-jp/script.lua | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| ワークスペース作成 | workspace.create呼び出し | uri == furi.encode('/') または uri == furi.encode($HOME) | 危険なルートディレクトリ |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| FORCE_ACCEPT_WORKSPACE == true | 強制許可フラグが設定されている場合 |
| 通常のプロジェクトディレクトリ | ルート・ホーム以外のディレクトリ |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[workspace.create呼び出し] --> B{uri == '/' ?}
    B -->|Yes| D{FORCE_ACCEPT_WORKSPACE?}
    B -->|No| C{uri == $HOME ?}
    C -->|Yes| D
    C -->|No| E[通常のワークスペース作成]
    D -->|Yes| E
    D -->|No| F[client.showMessage - Error]
    F --> G[scp:set 'bad root', true]
    G --> H[ワークスペース作成完了 - 読み込み制限]
    E --> I[ワークスペース作成完了 - 正常]
```

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

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| os.getenv('HOME') | ホームディレクトリ取得 | 環境変数 |

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| scope | UPDATE | 'bad root'フラグの設定 |

#### スコープ設定

| 操作 | 項目（カラム名） | 更新値 | 備考 |
|-----|-----------------|-------|------|
| SET | 'bad root' | true | 危険なルートのマーク |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 危険なルート検出 | ルート or ホームディレクトリ | エラー表示、'bad root'フラグ設定 |

### リトライ仕様

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

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | なし（ワークスペース作成時のみ） |
| 1日あたり上限 | なし |

### 配信時間帯

制限なし（エディタ起動時）

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

- 本通知はセキュリティ保護のための重要な警告
- ルートディレクトリやホームディレクトリのスキャンを防止
- システムファイルやセンシティブなファイルへのアクセスを抑制
- FAQリンクで適切な設定方法を案内

## 備考

- FORCE_ACCEPT_WORKSPACE環境変数で強制許可可能（開発・テスト用）
- 'bad root'フラグが設定されたワークスペースはファイルスキャンがスキップされる
- FAQリンク：https://luals.github.io/wiki/faq#why-is-the-server-scanning-the-wrong-folder

---

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

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

### 推奨読解順序

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

ワークスペースとスコープの基本構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | scope.lua | `script/workspace/scope.lua` | スコープの構造と'bad root'フラグ |

**読解のコツ**: scope:set()でフラグを設定し、scope:get()でフラグを取得することを把握する。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | workspace.lua | `script/workspace/workspace.lua` | create関数（行47-58） |

**主要処理フロー**:
1. **行47**: `function m.create(uri, folderName)` - 関数定義
2. **行49**: `scope.createFolder(uri, folderName)` - スコープ作成
3. **行51-52**: ルートディレクトリまたはホームディレクトリのチェック
4. **行53-56**: FORCE_ACCEPT_WORKSPACEチェックと警告表示
5. **行54**: `client.showMessage('Error', lang.script('WORKSPACE_NOT_ALLOWED', furi.decode(uri)))` - 通知送信
6. **行55**: `scp:set('bad root', true)` - フラグ設定

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

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

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

**主要処理フロー**:
- **行214-215**: メッセージテンプレートとFAQリンク

#### Step 4: 'bad root'フラグの影響を理解する

フラグ設定後の動作を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | workspace.lua | `script/workspace/workspace.lua` | awaitPreload関数（行337） |

**主要処理フロー**:
- **行337**: `if scp.uri and not scp:get('bad root') then` - スキャン条件

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

```
workspace.lua
    │
    └─ m.create(uri, folderName)
           │
           ├─ scope.createFolder(uri, folderName)
           │
           ├─ URIチェック: uri == furi.encode('/') or uri == furi.encode($HOME)
           │      │
           │      └─ FORCE_ACCEPT_WORKSPACEチェック
           │             │
           │             └─ client.showMessage('Error', ...)
           │                    │
           │                    └─ proto.notify('window/showMessage', ...)
           │
           └─ scp:set('bad root', true)
```

### データフロー図

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

ワークスペースURI ───▶ workspace.create()
                            │
                            ▼
                   URIチェック (/ or $HOME)
                            │
                            ▼ (危険なルート時)
                   FORCE_ACCEPT_WORKSPACEチェック
                            │
                            ▼ (未設定時)
                   lang.script('WORKSPACE_NOT_ALLOWED', path)
                            │
                            ▼
                   client.showMessage() ───▶ window/showMessage通知
                            │
                            ▼
                   scp:set('bad root', true) ───▶ スキャン抑止
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| workspace.lua | `script/workspace/workspace.lua` | ソース | ワークスペース管理・create関数 |
| scope.lua | `script/workspace/scope.lua` | ソース | スコープ管理 |
| client.lua | `script/client.lua` | ソース | クライアント通知機能 |
| script.lua | `locale/ja-jp/script.lua` | 言語リソース | 日本語メッセージ定義 |
| proto.lua | `script/proto/proto.lua` | ソース | LSPプロトコル通信 |
| file-uri.lua | `script/file-uri.lua` | ソース | URI変換 |
