# アーキテクチャ設計書

## 概要

本ドキュメントは、lua-language-server（Lua Language Server）のアーキテクチャ設計を記述したものです。lua-language-serverは、Language Server Protocol（LSP）を実装したLua言語向けのLanguage Serverであり、コード補完、定義へのジャンプ、型チェック、診断機能など多岐にわたる言語機能を提供します。

## システム全体構成

### アーキテクチャ概要図

[アーキテクチャ構成図](./アーキテクチャ構成図.md)を参照してください。

### システム境界と外部連携

| 外部システム | 連携方式 | 用途 |
| --- | --- | --- |
| IDEクライアント（VS Code, NeoVim等） | LSP（stdio/socket） | LSPリクエスト/レスポンスの送受信 |
| ファイルシステム | bee.filesystem | Luaソースファイルの読み込み・監視 |
| EmmyLuaCodeStyle | プラグイン連携 | コードフォーマット機能 |
| サードパーティライブラリ（LPegLabel, bee.lua等） | 内部ライブラリ | パーシング、スレッド管理、ネットワーク処理 |

## レイヤー構成

### アーキテクチャスタイル

**レイヤードアーキテクチャ + イベント駆動型アーキテクチャ**

本システムは、明確なレイヤー分離を持つレイヤードアーキテクチャを基盤とし、LSPプロトコル処理においてはイベント駆動型のリクエスト/レスポンスモデルを採用しています。また、マルチスレッド処理においてはPublisher/Worker（Brave）パターンを用いた並行処理アーキテクチャを実装しています。

### レイヤー定義

| レイヤー | 責務 | 主なコンポーネント |
| --- | --- | --- |
| Protocol Layer | LSPプロトコルの送受信、JSON-RPC処理 | `proto/`, `jsonrpc.lua`, `service/` |
| Provider Layer | LSP機能の提供・登録、クライアントとの通信 | `provider/`, `client.lua` |
| Core Layer | 言語機能の実装（補完、定義、診断等） | `core/`, `core/diagnostics/`, `core/completion/` |
| VM Layer | 型推論、ノード管理、コンパイル | `vm/`, `vm/compiler.lua`, `vm/infer.lua` |
| Parser Layer | Luaソースコードのパーシング、AST構築 | `parser/`, `parser/compile.lua`, `parser/guide.lua` |
| Infrastructure Layer | ファイル管理、ワークスペース管理、設定管理 | `files.lua`, `workspace/`, `config/` |
| Foundation Layer | ユーティリティ、ログ、非同期処理 | `utility.lua`, `log.lua`, `await.lua`, `pub/` |

### レイヤー間の依存関係ルール

- **依存の方向性**: 上位レイヤーから下位レイヤーへの一方向依存
- **許可される参照**:
  - Protocol Layer -> Provider Layer -> Core Layer -> VM Layer -> Parser Layer
  - すべてのレイヤー -> Infrastructure Layer, Foundation Layer
- **禁止される参照**:
  - 下位レイヤーから上位レイヤーへの直接参照
  - Parser LayerからCore Layerへの直接参照

## モジュール構成

### ドメイン分割

| ドメイン | 責務 | 関連モジュール |
| --- | --- | --- |
| LSPプロトコル | LSP通信、JSON-RPC処理 | `proto/`, `jsonrpc.lua`, `service/` |
| 言語機能 | コード補完、定義、参照、診断等 | `core/`, `provider/` |
| 型システム | 型推論、型チェック、ジェネリクス | `vm/` |
| パーシング | Luaソースコードの解析、AST構築 | `parser/` |
| ワークスペース | ファイル管理、スコープ管理 | `workspace/`, `files.lua` |
| 設定 | 設定ロード、設定管理 | `config/` |
| 並行処理 | マルチスレッドタスク管理 | `pub/`, `brave/`, `await.lua` |

### パッケージ構造

```
script/
├── service/           # サービス起動・イベントループ
│   ├── service.lua    # メインサービス
│   └── net.lua        # ネットワーク処理
├── proto/             # LSPプロトコル処理
│   ├── proto.lua      # JSON-RPC処理
│   ├── define.lua     # LSP定義
│   └── converter.lua  # データ変換
├── provider/          # LSP機能プロバイダー
│   ├── provider.lua   # メソッド登録・処理
│   ├── capability.lua # クライアント能力管理
│   └── diagnostic.lua # 診断プロバイダー
├── core/              # 言語機能コア実装
│   ├── completion/    # コード補完
│   ├── diagnostics/   # 診断（65種類以上）
│   ├── hover/         # ホバー情報
│   ├── definition.lua # 定義へのジャンプ
│   ├── reference.lua  # 参照検索
│   ├── rename.lua     # リネーム
│   └── ...
├── vm/                # 仮想マシン（型推論エンジン）
│   ├── compiler.lua   # ASTコンパイラ
│   ├── infer.lua      # 型推論
│   ├── node.lua       # ノード管理
│   ├── type.lua       # 型定義
│   └── ...
├── parser/            # Luaパーサー
│   ├── compile.lua    # Luaソースコンパイル
│   ├── guide.lua      # AST操作ガイド
│   └── luadoc.lua     # LuaDocパーサー
├── workspace/         # ワークスペース管理
│   ├── workspace.lua  # ワークスペース操作
│   ├── scope.lua      # スコープ管理
│   └── loading.lua    # ファイルロード
├── config/            # 設定管理
│   ├── config.lua     # 設定操作
│   ├── loader.lua     # 設定ロード
│   └── template.lua   # 設定テンプレート
├── pub/               # マルチスレッド管理
│   ├── pub.lua        # パブリッシャー
│   └── report.lua     # レポート処理
├── brave/             # ワーカースレッド
├── cli/               # CLIツール
├── files.lua          # ファイル管理
├── client.lua         # クライアント管理
├── await.lua          # 非同期処理
├── log.lua            # ロギング
├── utility.lua        # ユーティリティ
└── ...
```

### コンポーネント依存関係

1. **main.lua** -> **service** -> **proto** -> **provider**
2. **provider** -> **core** -> **vm** -> **parser**
3. **workspace** <-> **files** <-> **parser**
4. **pub** -> **brave**（マルチスレッド通信）
5. **await** -> **timer**（非同期処理）

## ミドルウェア構成

### データベース

本システムはデータベースを使用しません。すべてのデータはインメモリで管理されます。

| 種類 | ミドルウェア | バージョン | 用途 |
| --- | --- | --- | --- |
| インメモリ | Luaテーブル | - | AST、型情報、ファイルキャッシュの格納 |

### キャッシュ

| ミドルウェア | バージョン | 用途 | TTL |
| --- | --- | --- | --- |
| ファイルシステムキャッシュ | - | 解析済みASTのキャッシュ | セッション |
| lazyCache | - | VM計算結果のキャッシュ | 動的 |
| stateMap | - | ファイル状態のキャッシュ | ファイル変更まで |

### メッセージキュー

| ミドルウェア | バージョン | 用途 |
| --- | --- | --- |
| bee.channel | - | スレッド間通信（タスク配信・結果受信） |
| bee.select | - | 複数チャネルの監視 |

### 検索エンジン

本システムは専用の検索エンジンを使用せず、独自のインデックスを構築しています。

| ミドルウェア | バージョン | 用途 |
| --- | --- | --- |
| vmグローバルインデックス | - | グローバル変数・型の検索 |
| workspace symbol | - | ワークスペースシンボル検索 |

### その他ミドルウェア

| ミドルウェア | バージョン | 用途 |
| --- | --- | --- |
| bee.lua | - | ファイルシステム、スレッド、プロセス管理 |
| LPegLabel | - | Luaソースコードのパーシング |
| EmmyLuaCodeStyle | - | コードフォーマット |

## データフロー

### リクエスト処理の流れ

同期リクエスト（例: textDocument/hover）の処理フローを記載します。

1. **proto.lua**: クライアントからJSON-RPCリクエストを受信
2. **proto.doMethod**: リクエストをメソッドキューに追加
3. **proto.applyMethod**: 登録されたability（ハンドラー）を呼び出し
4. **provider.lua**: 対応するLSPメソッドハンドラーを実行
5. **core/**: 言語機能の実装を呼び出し（例: hover）
6. **vm/**: 必要に応じて型推論・ノード検索を実行
7. **parser/**: ASTからソース情報を取得
8. **proto.response**: 結果をJSON-RPCレスポンスとして送信

### 非同期処理の流れ

ファイル解析などの非同期処理フローを記載します。

1. **pub.task**: タスクを作成し、パブリッシャーに登録
2. **pub.pushTask**: 空いているBrave（ワーカースレッド）にタスクを配信
3. **brave**: タスクを受信し、処理を実行
4. **pub.popTask**: Braveから結果を受信、コールバックを実行
5. **await.resume**: 待機中のコルーチンを再開

### データ永続化の流れ

1. **workspace.loading**: ワークスペース内のファイルをスキャン
2. **files.setText**: ファイル内容をメモリに保存
3. **parser.compile**: Luaソースコードをパースし、ASTを生成
4. **files.getState**: パース済みASTをキャッシュから取得
5. **vm.compiler**: ASTをコンパイルし、型情報を付与
6. **キャッシュ**: LRUキャッシュディレクトリにキャッシュを保存（セッション間）

## 横断的関心事

### 認証・認可

本システムはローカル実行を前提としており、認証・認可機能は実装されていません。

| 方式 | 実装箇所 | 対象 |
| --- | --- | --- |
| なし | - | - |

### ロギング・監査

| 種類 | 実装方式 | 保存先 |
| --- | --- | --- |
| アプリケーションログ | log.lua | `LOGPATH/service.log` |
| RPC通信ログ | proto.lua（RPCLOG有効時） | アプリケーションログ |
| メモリレポート | service.reportMemory | ログファイル（10分間隔） |

### エラーハンドリング

| エラー種別 | ハンドリング方式 | レスポンス |
| --- | --- | --- |
| パースエラー | parser.compile内でキャッチ | 診断情報として返却 |
| 型エラー | vm/diagnosticsで検出 | 診断情報として返却 |
| LSPエラー | proto.responseErr | JSON-RPCエラーレスポンス |
| 内部エラー | xpcall + log.error | InternalErrorコード返却 |
| スレッドエラー | pub.checkDead | エラーログ出力 |

### トランザクション管理

本システムはデータベースを使用しないため、トランザクション管理は不要です。ファイル変更の一貫性は以下の方式で管理されます。

| 範囲 | 管理方式 | 分離レベル |
| --- | --- | --- |
| ファイル更新 | バージョン管理（file.version） | - |
| AST更新 | globalVersion管理 | - |
| キャッシュ無効化 | vm.cacheTracker | - |

## 設計原則・コーディング規約

### 適用している設計原則

| 原則 | 適用箇所 | 実装例 |
| --- | --- | --- |
| 単一責任の原則 | 各モジュール | core/definition.lua は定義検索のみ担当 |
| 依存性逆転の原則 | vm.compiler | 外部からのコールバック注入 |
| イベント駆動 | proto.on | LSPメソッドのコールバック登録 |
| コルーチンベース非同期 | await.lua | async/await パターンの実装 |
| Publisher/Worker | pub/brave | マルチスレッドタスク処理 |
| 遅延評価 | lazyCache | 必要時のみ計算を実行 |

### コーディング規約

1. **型注釈**: `---@class`, `---@param`, `---@return` 等のLuaDocアノテーションを使用
2. **モジュール構造**: 各ファイルはテーブル `m` を返す形式
3. **非同期関数**: `---@async` アノテーションで非同期関数を明示
4. **エラーハンドリング**: `xpcall` と `log.error` を使用
5. **命名規則**:
   - ローカル関数: camelCase
   - モジュール関数: m.functionName
   - プライベート関数: 先頭にアンダースコア

## 備考

- 本システムは Lua 5.4 で実装されており、bee.lua を通じてクロスプラットフォーム（Windows, macOS, Linux）で動作します
- サポートするLuaバージョン: Lua 5.1, 5.2, 5.3, 5.4, 5.5, LuaJIT
- 多言語対応: 6言語（en-us, zh-cn, zh-tw, pt-br, ja-jp, es-419）
- プラグインシステムにより、カスタム機能の追加が可能
