# 非機能要件定義書

## 概要

本ドキュメントは、Lua Language Server（lua-language-server）プロジェクトにおける非機能要件を定義する。本システムはLua言語のための言語サーバー（Language Server Protocol準拠）であり、リアルタイムコード解析、補完、診断機能を提供する開発ツールである。

## 性能要件

### レスポンスタイム

| 処理種別 | 目標値 | 備考 |
| --- | --- | --- |
| 構文解析（Compile） | 0.1秒以内（警告閾値） | `script/files.lua`にて0.1秒超過で警告ログ出力 |
| LuaDoc解析 | 0.1秒以内（警告閾値） | `script/files.lua`にて0.1秒超過で警告ログ出力 |
| lazy-table変換 | 0.1秒以内（警告閾値） | `script/files.lua`にて0.1秒超過で警告ログ出力 |
| 診断結果プッシュ間隔 | 500ms | `script/provider/diagnostic.lua`にて500ms間隔でプッシュ |
| awaitステップ処理 | 0.5秒以内（警告閾値） | `script/await.lua`にて0.5秒超過で警告ログ出力 |
| プログレスバー遅延表示 | 0.5秒 | 処理開始後0.5秒経過で表示開始 |

### スループット

| 項目 | 目標値 | 備考 |
| --- | --- | --- |
| 最大プリロードファイル数 | 5,000ファイル（デフォルト） | `Lua.workspace.maxPreload`で設定可能 |
| プリロードファイルサイズ上限 | 500KB（デフォルト） | `Lua.workspace.preloadFileSize`で設定可能 |
| 巨大ファイル上限 | 10MB | `script/files.lua`にて10MB超過ファイルはスキップ |
| 診断結果上限（Hint/Info） | 10,000件 | `script/provider/diagnostic.lua`にて制限 |
| 補完候補最大数 | 100件（デフォルト） | `Lua.completion.maxSuggestCount`で設定可能 |
| キャッシュ最大同時オープンファイル数 | 50ファイル | `script/lazy-cacher.lua`にて設定 |
| キャッシュファイルサイズ上限 | 100MB | `script/lazy-cacher.lua`にて設定 |
| ワーカースレッド数 | 4（デフォルト）+ COMPILECORES | `script/service/service.lua`にて設定 |

### 処理遅延設定

| 項目 | 目標値 | 備考 |
| --- | --- | --- |
| ワークスペース診断遅延 | 3,000ms（デフォルト） | `Lua.diagnostics.workspaceDelay`で設定可能 |
| ワークスペース診断最小遅延 | 200ms | `script/provider/diagnostic.lua`にて最小値制限 |
| 診断更新待機時間 | 100ms | `script/provider/diagnostic.lua`にて設定 |

## 可用性要件

| 項目 | 目標値 | 備考 |
| --- | --- | --- |
| 稼働率 | N/A（クライアントアプリケーション） | エディタ/IDE内で動作するツールのため、サーバー稼働率の概念は適用外 |
| 計画停止時間 | N/A | クライアントアプリケーションのため適用外 |
| 障害復旧時間（RTO） | N/A | クライアントアプリケーションのため適用外 |
| 目標復旧時点（RPO） | N/A | ステートレス処理のため適用外 |
| エラーハンドリング | xpcallによるエラー捕捉 | 全体でxpcall/pcallによるエラー捕捉を実施 |
| プロセス分離 | マルチプロセス構成 | ワーカープロセス（brave）による分離処理 |

### 状態管理

| 項目 | 内容 | 備考 |
| --- | --- | --- |
| ファイルキャッシュ | lazy-cacherによるディスクキャッシュ | `${LOGPATH}/cache/${pid}`に保存 |
| メモリ管理 | 定期的GC実行 | 診断完了時にcollectgarbage実行 |
| 状態永続化 | compileCount >= 3で状態永続化 | `script/files.lua`にて3回以上コンパイルされたファイルは状態保持 |

## セキュリティ要件

### ファイルアクセス制御

| 項目 | 内容 | 備考 |
| --- | --- | --- |
| プラグインパス | デフォルト空文字列 | セキュリティ上の理由でデフォルト無効化（changelog.md記載） |
| ファイルエンコーディング検証 | encoderモジュールによるデコード | utf8/ansi/utf16le/utf16beサポート |
| パス正規化 | 相対パス・シンボリックリンク解決 | `script/files.lua`のnormalize関数 |

### 入力検証

| 項目 | 内容 | 備考 |
| --- | --- | --- |
| 設定値検証 | config.templateによる型チェック | `script/config/template.lua`にて定義 |
| ファイルサイズ制限 | 10MB上限 | 巨大ファイルの読み込み防止 |
| URIスキーム制限 | `file`スキームのみ（デフォルト） | `Lua.diagnostics.enableScheme`で設定可能 |

### サードパーティ連携

| 項目 | 内容 | 備考 |
| --- | --- | --- |
| サードパーティチェック | Ask/Apply/ApplyInMemory/Disable | `Lua.workspace.checkThirdParty`で設定可能 |
| ライブラリファイル診断 | Disable/Opened/Enable | `Lua.diagnostics.libraryFiles`で設定可能 |

## 拡張性要件

### プラグインシステム

| 項目 | 内容 | 備考 |
| --- | --- | --- |
| プラグインAPI | OnSetText, OnTransformAst | `script/plugin.lua`でディスパッチ |
| プラグイン設定 | 文字列または配列で指定可能 | `Lua.runtime.plugin`で設定 |
| プラグイン引数 | 配列またはハッシュ形式 | `Lua.runtime.pluginArgs`で設定 |

### 設定拡張性

| 項目 | 内容 | 備考 |
| --- | --- | --- |
| スコープ別設定 | workspace/folder/override | `script/workspace/scope.lua`で管理 |
| 設定ウォッチ | コールバックベースの変更通知 | `config.watch()`で登録 |
| 動的設定更新 | クライアントからの設定変更対応 | `client.setConfig()`で更新 |

### 多言語対応

| 項目 | 内容 | 備考 |
| --- | --- | --- |
| 対応言語 | en-us, ja-jp, zh-cn, zh-tw, pt-br, es-419 | `locale/`ディレクトリに言語ファイル |
| ランタイムバージョン | Lua 5.1/5.2/5.3/5.4/5.5/LuaJIT | `Lua.runtime.version`で設定可能 |

## 保守性要件

### ログ機能

| 項目 | 内容 | 備考 |
| --- | --- | --- |
| ログレベル | trace, debug, info, warn, error | グローバルlog関数で出力 |
| ログ出力先 | `${LOGPATH}/log.txt` | ファイルおよびコンソール出力 |
| 性能ログ | 処理時間警告出力 | 0.1秒/0.5秒超過で警告 |

### デバッグ支援

| 項目 | 内容 | 備考 |
| --- | --- | --- |
| 開発モード | DEVELOP変数による制御 | 差分ファイル出力等の追加機能 |
| 診断レポート | メモリ/タスク/キャッシュ/RPC状態出力 | `script/service/service.lua`のreport関数 |
| Tracy連携 | tracy.ZoneBeginN/ZoneEndによるプロファイリング | パフォーマンス分析用 |

### コード品質

| 項目 | 内容 | 備考 |
| --- | --- | --- |
| 型アノテーション | LuaDoc形式の型定義 | `---@class`, `---@param`等 |
| モジュール構造 | requireベースのモジュール分離 | `script/`配下に機能別モジュール |
| テストスイート | test/配下にテストコード | 各機能の単体テスト |

## 運用・監視要件

### 状態監視

| 項目 | 内容 | 備考 |
| --- | --- | --- |
| メモリ監視 | collectgarbage('count')による監視 | ステータスバーにメモリ使用量表示 |
| ファイルキャッシュ監視 | countStates()による監視 | AST状態数をステータスバーに表示 |
| 診断レポート | 600秒間隔で自動出力 | `script/service/service.lua`のreport関数 |

### ステータス通知

| 項目 | 内容 | 備考 |
| --- | --- | --- |
| ステータスバー | 処理状態をアイコンで表示 | loading/sleeping/normalの3状態 |
| プログレス通知 | 長時間処理の進捗表示 | LSPのwindow/workDoneProgress使用 |
| メッセージ通知 | 警告・情報メッセージ表示 | window/showMessage使用 |

### リソース管理

| 項目 | 内容 | 備考 |
| --- | --- | --- |
| GCコンテナ | 自動リソース解放 | `script/gc.lua`によるGC管理 |
| キャッシュロック | プロセス間排他制御 | `.lock`ファイルによるロック |
| ファイル参照カウント | 参照ベースのファイル管理 | addRef/delRefによる参照管理 |

### タイムアウト設定

| 項目 | 設定値 | 備考 |
| --- | --- | --- |
| タイマー精度 | ミリ秒単位 | `script/timer.lua`で管理 |
| ネットワークポーリング | 100ms（スリープ時） | `script/service/service.lua`で設定 |
| awaitスリープ最小値 | 0.1秒 | 診断更新待機等で使用 |

## 備考

### 設定カテゴリ一覧

本システムの設定は以下のカテゴリに分類される（`script/config/template.lua`より）：

- `Lua.runtime.*` - ランタイム設定（バージョン、パス、特殊関数等）
- `Lua.diagnostics.*` - 診断設定（有効/無効、重要度、ファイルステータス等）
- `Lua.workspace.*` - ワークスペース設定（除外、ライブラリ、プリロード等）
- `Lua.completion.*` - 補完設定（スニペット、候補数等）
- `Lua.hover.*` - ホバー設定（表示内容、制限等）
- `Lua.hint.*` - インレイヒント設定
- `Lua.semantic.*` - セマンティックハイライト設定
- `Lua.format.*` - フォーマット設定
- `Lua.type.*` - 型チェック設定

### 制約事項

1. **ファイルサイズ制限**: 10MBを超えるファイルは処理対象外となる
2. **プリロード制限**: maxPreloadを超えるファイル数は警告後スキップ
3. **メモリ使用量**: 大規模プロジェクトでは数GB程度のメモリを消費する可能性がある
4. **プラグイン実行**: プラグインエラーは警告ログに出力され、処理は継続される
