# 機能設計書 10-Drizzle解析

## 概要

本ドキュメントは、Liamシステムにおける「Drizzle解析」機能の設計を記述したものである。Drizzle ORMのスキーマファイル（TypeScript）をパースしてスキーマ情報を抽出する機能である。

### 本機能の処理概要

本機能は、SWC（Speedy Web Compiler）を使用してDrizzle ORMスキーマのTypeScriptコードをAST（抽象構文木）に変換し、pgTable/mysqlTableなどのテーブル定義、カラム、制約、インデックス、列挙型等の情報をLiam内部形式（Schema型）に変換する。PostgreSQLとMySQLの両方のスキーマに対応しており、データベース種別を自動検出する。

**業務上の目的・背景**：Drizzle ORMはTypeScript/JavaScript向けの軽量ORMとして近年人気が高まっており、TypeScriptファイル内でスキーマを定義する方法が特徴である。本機能により、Drizzle ORMを使用したアプリケーションのデータベース構造を可視化できる。

**機能の利用シーン**：
- 既存Drizzleアプリケーションのスキーマ可視化
- Drizzleスキーマファイルの解析
- データベース設計レビュー
- チーム間でのスキーマ共有

**主要な処理内容**：
1. SWCによるTypeScript構文解析
2. データベース種別の自動検出（PostgreSQL/MySQL）
3. pgTable/mysqlTable呼び出しの解析
4. カラム定義の抽出と型変換
5. インデックス・制約情報の抽出
6. 外部キー参照の解決
7. 列挙型（pgEnum/mysqlEnum）の抽出

**関連システム・外部連携**：@swc/core（TypeScriptパーサー）を使用。

**権限による制御**：解析自体に認証は不要。解析結果の表示は認証状態に依存。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 12 | スキーマ画面 | 主画面 | Drizzleスキーマファイルのパース処理 |
| 20 | 公開ERD画面 | 主画面 | Drizzleスキーマファイルのパース処理 |

## 機能種別

データ変換 / パース処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| schemaContent | string | Yes | Drizzleスキーマファイル内容（TypeScript） | - |

### 入力データソース

- Drizzle schemaファイル（例：schema.ts、db/schema.ts）
- drizzle-orm/pg-core または drizzle-orm/mysql-core を使用

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| value | Schema | パース結果のスキーマ |
| errors | ProcessError[] | パース中に発生したエラー/警告 |

### 出力先

スキーマストア / ER図表示機能

## 処理フロー

### 処理シーケンス

```
1. スキーマ受信
   └─ TypeScriptコード文字列を受け取る
2. データベース種別検出
   └─ detectDrizzleDbTypeでインポートパターンを分析
3. プロセッサ選択
   ├─ postgres → postgresProcessor
   └─ mysql → mysqlProcessor
4. AST生成
   └─ parseSync(@swc/core)でTypeScriptをパース
5. 変数宣言走査
   └─ visitModuleで変数宣言を探索
6. テーブル・Enum解析
   ├─ parsePgTableCall / parseMysqlTableCall
   └─ parsePgEnumCall / parseMysqlEnumCall
7. 内部形式変換
   └─ convertDrizzleTablesToInternal
8. 結果返却
   └─ ProcessResult形式で返却
```

### フローチャート

```mermaid
flowchart TD
    A[schema.ts入力] --> B[detectDrizzleDbType]
    B --> C{データベース種別?}
    C -->|postgres| D[postgresProcessor]
    C -->|mysql| E[mysqlProcessor]
    D --> F[parseSync SWC]
    E --> F
    F --> G[AST生成]
    G --> H[visitModule]
    H --> I{CallExpression種別}
    I -->|pgTable/mysqlTable| J[parseTableCall]
    I -->|pgEnum/mysqlEnum| K[parseEnumCall]
    J --> L[DrizzleTableDefinition]
    K --> M[DrizzleEnumDefinition]
    L --> N[convertDrizzleTablesToInternal]
    M --> O[convertDrizzleEnumsToInternal]
    N --> P[Schema構築]
    O --> P
    P --> Q[結果返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | DB自動検出 | drizzle-orm/pg-core→PostgreSQL、drizzle-orm/mysql-core→MySQL | インポート文検出 |
| BR-002 | 変数→テーブル名マッピング | JS変数名と実際のテーブル名を別管理 | variableToTableMapping |
| BR-003 | 型変換 | Drizzle型をPostgreSQL/MySQL型に変換 | convertDrizzleTypeToPgType |
| BR-004 | 複合主キー | primaryKey()で複合主キーを定義 | 第3引数のアロー関数内 |
| BR-005 | 外部キーターゲット解決 | 変数名から実際のテーブル名を解決 | fixForeignKeyTargetColumnNames |

### 計算ロジック

Drizzle型（PostgreSQL）の変換:
- varchar(length) → varchar(length)
- char(length) → char(length)
- decimal(precision,scale) → decimal(precision,scale)
- timestamp(withTimezone) → timestamp with time zone
- doublePrecision → double precision
- serial → serial（自動連番）

参照アクションの変換:
- cascade → CASCADE
- restrict → RESTRICT
- setNull / set null → SET_NULL
- setDefault / set default → SET_DEFAULT
- その他 → NO_ACTION

## データベース操作仕様

### 操作別データベース影響一覧

本機能はデータベースを直接操作しない。パース処理のみ。

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | データベース操作なし |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| PARSE_ERROR | 構文エラー | TypeScript構文エラー | SWC parseSync例外をキャッチ |
| TABLE_CONVERSION_ERROR | テーブル変換エラー | テーブル定義の解析失敗 | エラー配列に追加して継続 |

### リトライ仕様

なし（再パースで対応）

## トランザクション仕様

該当なし（メモリ内処理）

## パフォーマンス要件

- 大規模Drizzleスキーマ（数百テーブル）でも高速処理
- SWCによる高速TypeScriptパース

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

- TypeScriptコードの実行は行わない（パースのみ）
- 機密情報を含むスキーマは認証後のみ処理

## 備考

SWCはRust製の高速TypeScript/JavaScriptコンパイラであり、ASTの生成に使用される。PostgreSQLとMySQLの両方のDrizzleスキーマに対応している。

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | index.ts | `frontend/packages/schema/src/parser/drizzle/index.ts` | processor関数、DB種別自動検出 |

**主要処理フロー**:
1. **8-36行目**: detectDrizzleDbType - インポートパターンからDB種別を判定
2. **41-52行目**: processor - 種別に応じてプロセッサを選択

#### Step 2: PostgreSQLパーサーを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | mainParser.ts | `frontend/packages/schema/src/parser/drizzle/postgres/mainParser.ts` | メインパース処理 |
| 2-2 | tableParser.ts | `frontend/packages/schema/src/parser/drizzle/postgres/tableParser.ts` | テーブル解析 |
| 2-3 | columnParser.ts | `frontend/packages/schema/src/parser/drizzle/postgres/columnParser.ts` | カラム解析 |

**主要処理フロー**:
- **24-45行目**: parseDrizzleSchema - SWCでAST生成、モジュール走査
- **50-80行目**: visitModule - 変数宣言の探索
- **174-196行目**: visitVariableDeclarator - CallExpression種別判定

#### Step 3: 型変換とコンバーターを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | converter.ts | `frontend/packages/schema/src/parser/drizzle/postgres/converter.ts` | 内部形式変換 |
| 3-2 | convertToPgType.ts | `frontend/packages/schema/src/parser/drizzle/postgres/convertToPgType.ts` | 型変換 |

**主要処理フロー**:
- **24-179行目**: convertToTable - DrizzleTableDefinition→Table変換
- **210-239行目**: convertDrizzleTablesToInternal - 全テーブル変換
- **5-59行目**: convertDrizzleTypeToPgType - Drizzle型→PostgreSQL型

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

```
processor (index.ts)
    │
    ├─ detectDrizzleDbType
    │      ├─ drizzle-orm/pg-core → 'postgres'
    │      └─ drizzle-orm/mysql-core → 'mysql'
    │
    └─ postgresProcessor / mysqlProcessor
           │
           └─ parseDrizzleSchemaString
                  │
                  ├─ parseDrizzleSchema
                  │      │
                  │      ├─ parseSync (@swc/core)
                  │      │      └─ AST生成
                  │      │
                  │      └─ visitModule
                  │             └─ visitVariableDeclarator
                  │                    ├─ handleCommentCall
                  │                    ├─ handleSchemaTableCall
                  │                    ├─ handlePgEnumCall
                  │                    └─ handlePgTableCall
                  │                           └─ parsePgTableCall
                  │                                  └─ parseColumnFromProperty
                  │
                  ├─ convertDrizzleTablesToInternal
                  │      ├─ convertToTable
                  │      │      └─ convertDrizzleTypeToPgType
                  │      └─ fixForeignKeyTargetColumnNames
                  │
                  └─ convertDrizzleEnumsToInternal
```

### データフロー図

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

schema.ts ──────────▶ detectDrizzleDbType ───▶ 'postgres' | 'mysql'
                           │
                           ▼
TypeScriptコード ───▶ parseSync (SWC) ────────▶ AST (Module)
                           │
                           ▼
AST ────────────────▶ visitModule ────────────▶ tables{}, enums{}
                           │
                           ├─▶ pgTable() → DrizzleTableDefinition
                           ├─▶ pgEnum() → DrizzleEnumDefinition
                           └─▶ variableToTableMapping{}

tables{} ───────────▶ convertDrizzleTablesToInternal ─▶ Table{}
                           │
                           ├─▶ convertToTable
                           │      └─▶ convertDrizzleTypeToPgType
                           │
                           └─▶ fixForeignKeyTargetColumnNames

enums{} ────────────▶ convertDrizzleEnumsToInternal ──▶ Enum{}
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `frontend/packages/schema/src/parser/drizzle/index.ts` | ソース | エントリーポイント・DB種別検出 |
| postgres/mainParser.ts | `frontend/packages/schema/src/parser/drizzle/postgres/mainParser.ts` | ソース | PostgreSQLパーサー |
| postgres/tableParser.ts | `frontend/packages/schema/src/parser/drizzle/postgres/tableParser.ts` | ソース | テーブル解析 |
| postgres/columnParser.ts | `frontend/packages/schema/src/parser/drizzle/postgres/columnParser.ts` | ソース | カラム解析 |
| postgres/converter.ts | `frontend/packages/schema/src/parser/drizzle/postgres/converter.ts` | ソース | 内部形式変換 |
| postgres/convertToPgType.ts | `frontend/packages/schema/src/parser/drizzle/postgres/convertToPgType.ts` | ソース | 型変換 |
| postgres/enumParser.ts | `frontend/packages/schema/src/parser/drizzle/postgres/enumParser.ts` | ソース | Enum解析 |
| postgres/astUtils.ts | `frontend/packages/schema/src/parser/drizzle/postgres/astUtils.ts` | ソース | ASTユーティリティ |
| mysql/mainParser.ts | `frontend/packages/schema/src/parser/drizzle/mysql/mainParser.ts` | ソース | MySQLパーサー |
| mysql/converter.ts | `frontend/packages/schema/src/parser/drizzle/mysql/converter.ts` | ソース | MySQL内部形式変換 |
