# データベース設計書

## 概要

本ドキュメントは、lua-language-serverプロジェクトにおけるデータ構造設計を記述したものです。

lua-language-serverは、Lua言語のLanguage Server Protocol (LSP) 実装であり、従来のリレーショナルデータベースやNoSQLデータベースは使用していません。代わりに、インメモリのLuaテーブルを使用してランタイムデータを管理しています。

本設計書では、プロジェクト内で使用される主要なデータ構造（エンティティ）をデータベーステーブルに相当するものとして文書化します。

## テーブル一覧

| テーブル名 | 対応エンティティ | 説明 |
| --- | --- | --- |
| file | file (script/files.lua) | 開いているファイルの情報を管理 |
| parser.state | parser.state (script/parser) | パース結果の状態を保持 |
| vm.global | vm.global (script/vm/global.lua) | グローバル変数・型の管理 |
| scope | scope (script/workspace/scope.lua) | ワークスペーススコープの管理 |
| config | config (script/config) | 設定情報の管理 |

## 各テーブル定義

### 1. file

ファイル管理のためのデータ構造。エディタで開かれているLuaファイルの情報を保持します。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| uri | uri (string) | NO | ファイルの一意識別子（URI形式） |
| id | integer | NO | ファイルの内部ID（自動採番） |
| ref | integer | YES | 参照カウント |
| trusted | boolean | YES | 信頼されたソースからのファイルかどうか |
| rows | integer[] | YES | 行のオフセット情報 |
| originText | string | YES | 元のファイルテキスト |
| text | string | YES | 処理後のファイルテキスト |
| version | integer | YES | ファイルバージョン |
| originLines | integer[] | YES | 元の行情報 |
| diffInfo | table[] | YES | 差分情報 |
| cache | table | YES | キャッシュデータ |
| state | parser.state | YES | パース状態 |
| compileCount | integer | YES | コンパイル回数 |
| words | table | YES | 単語インデックス |

### 2. parser.state

パーサーの状態を管理するデータ構造。構文解析結果とメタデータを保持します。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| uri | uri (string) | YES | 関連ファイルのURI |
| lua | string | YES | Luaソースコード |
| ast | table | NO | 抽象構文木 |
| diffInfo | table[] | YES | 差分情報 |
| originLines | integer[] | YES | 元の行情報 |
| originText | string | YES | 元のテキスト |

### 3. vm.global

グローバル変数と型の管理を行うデータ構造。型システムの中核を担います。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| name | string | NO | グローバル変数/型の名前 |
| cate | vm.global.cate | NO | カテゴリ（"variable" または "type"） |
| uri | string | YES | 定義元のURI |
| links | table | NO | URI毎のリンク情報（sets/gets） |
| setsCache | table | YES | セットのキャッシュ |

### 4. vm.global.link

グローバル変数のリンク情報を管理するサブ構造。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| sets | parser.object[] | NO | 設定（代入）箇所のリスト |
| gets | parser.object[] | NO | 取得（参照）箇所のリスト |

### 5. scope

ワークスペーススコープを管理するデータ構造。マルチルートワークスペースに対応します。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| type | scope.type | NO | スコープタイプ（"override", "folder", "fallback"） |
| uri | uri (string) | YES | スコープのルートURI |
| folderName | string | YES | フォルダ名 |
| _links | table | NO | リンクされたURIのマップ |
| _data | table | NO | スコープ固有のデータ |
| _gc | gc | NO | ガベージコレクション管理 |
| _removed | boolean | YES | 削除済みフラグ |

### 6. files（管理クラス）

ファイル管理モジュールのグローバル状態。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| openMap | table | NO | 開いているファイルのマップ |
| fileMap | table | NO | 全ファイルのマップ（URI -> file） |
| dllMap | table | NO | DLLファイルのマップ |
| visible | table | NO | 可視ファイルのマップ |
| globalVersion | integer | NO | グローバルバージョン番号 |
| fileCount | integer | NO | ファイル総数 |
| stateMap | table | NO | パース状態のマップ（URI -> parser.state） |
| stateTrace | table | NO | パース状態の追跡用弱参照テーブル |
| watchList | table | NO | ファイル監視コールバックのリスト |
| notifyCache | table | NO | 通知キャッシュ |
| assocVersion | integer | NO | ファイル関連付けバージョン |
| lazyCache | lazy-cacher | YES | 遅延キャッシュ |

## 備考

### インメモリデータストア

本プロジェクトでは、永続化を必要としないLanguage Server実装であるため、すべてのデータはプロセスのメモリ上に保持されます。データの永続化は以下の場合のみ行われます：

1. **遅延キャッシュ（LAZY モード）**: パフォーマンス最適化のため、パース結果をディスクにキャッシュする実験的機能
2. **設定ファイル**: `.luarc.json` などの設定ファイルはファイルシステムから読み込まれる

### データの関連性

- `file` は `parser.state` と1対1で関連付けられる
- `vm.global` は複数の `file` からの参照を `links` で管理
- `scope` は複数の `file` をグループ化し、可視性を制御

### 型定義の注釈

ソースコード内では `---@class` アノテーションを使用してデータ構造が定義されています。これはLuaDocスタイルの型アノテーションであり、Language Server自身がこれを解析して型情報を提供します。
