# 機能設計書 15-YAML出力

## 概要

本ドキュメントは、Liam ERDの内部スキーマ形式をYAML形式で出力する「YAML出力」機能の設計を記述する。

### 本機能の処理概要

**業務上の目的・背景**：スキーマ情報を人間が読みやすく、バージョン管理しやすい形式で出力することで、スキーマの可搬性と可読性を向上させる。YAMLはJSONと比較して可読性が高く、コメントも記述できるため、設計ドキュメントとしての活用も期待できる。

**機能の利用シーン**：
- AIエージェントがスキーマ分析のプロンプトにスキーマ情報を含める際
- スキーマ情報をファイルとしてエクスポートする際
- 設計レビュー用にスキーマを可読形式で出力する際

**主要な処理内容**：
1. スキーマオブジェクトからnull値を除去
2. YAMLライブラリを使用してオブジェクトを文字列に変換
3. 整形オプションを適用してYAML文字列を生成

**関連システム・外部連携**：
- PM Agent（No.20）でスキーマ分析時のプロンプト生成に使用
- DB Agentサブグラフ（No.19）でスキーマ情報の出力に使用

**権限による制御**：本機能は認証・認可を必要としないライブラリ機能である。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 画面からの直接利用なし（AIエージェント内部で使用） |

## 機能種別

データ変換処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| schema | Schema | Yes | Liam ERDの内部スキーマオブジェクト | Schema型に準拠 |

### 入力データソース

- メモリ上のSchemaオブジェクト（tables, enums, extensionsを含む）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| result | Result<string, Error> | 成功時はYAML文字列、失敗時はErrorオブジェクト |

### 出力先

関数の戻り値として返却される（neverthrowのResult型）。

## 処理フロー

### 処理シーケンス

```
1. null値の除去
   └─ removeNullValues関数で再帰的にnull値を除去
2. YAML変換
   └─ yaml.stringify関数でオブジェクトをYAML文字列に変換
3. エラーハンドリング
   └─ fromThrowableでエラーをResult型にラップ
4. 結果の返却
   └─ Result<string, Error>として返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[removeNullValues実行]
    B --> C[yaml.stringify実行]
    C --> D{変換成功?}
    D -->|Yes| E[Ok結果を返却]
    D -->|No| F[Err結果を返却]
    E --> G[終了]
    F --> G
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | null値除去 | 出力YAMLからnull値を含むプロパティを除去 | 常に適用 |
| BR-02 | PLAIN文字列型 | 文字列はクォートなしのPLAIN形式で出力 | 常に適用 |
| BR-03 | 行幅無制限 | 長い行の自動改行を無効化 | 常に適用 |

### YAML出力オプション

| オプション | 値 | 説明 |
|-----------|-----|------|
| defaultStringType | PLAIN | 文字列のデフォルト形式 |
| defaultKeyType | PLAIN | キーのデフォルト形式 |
| lineWidth | 0 | 行幅制限なし |
| minContentWidth | 0 | 最小コンテンツ幅なし |

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

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

本機能はデータベースを操作しない（メモリ上でのデータ変換のみ）。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | YAML変換エラー | オブジェクトがYAMLに変換できない | Result.Errとして返却 |

### リトライ仕様

リトライ不要（同期的な変換処理のため）

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

該当なし（データベース操作を行わない）

## パフォーマンス要件

- 処理時間：100テーブル規模のスキーマで10ミリ秒以内

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

- 特になし（メモリ上の純粋な変換処理）

## 備考

- neverthrowライブラリのResult型を使用してエラーハンドリングを実装
- yamlライブラリを使用（@types/jsyamlではなくyamlパッケージ）

---

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

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

### 推奨読解順序

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

まず、入出力の型定義を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | type.ts | `frontend/packages/schema/src/deparser/type.ts` | SchemaDeparser型の定義（Result型を使用） |

**読解のコツ**: SchemaDeparser型はneverthrowのResult型を返す関数型。LegacySchemaDeparsrとの違いに注目。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `frontend/packages/schema/src/deparser/yaml/index.ts` | yamlSchemaDeparsrのエクスポート |

#### Step 3: YAML変換ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | schemaDeparser.ts | `frontend/packages/schema/src/deparser/yaml/schemaDeparser.ts` | メインのYAML変換ロジック |

**主要処理フロー（schemaDeparser.ts）**:
- **6-18行目**: removeNullValues関数 - null値の再帰的除去
- **20-35行目**: yamlSchemaDeparser関数 - メインロジック
- **21行目**: removeNullValues(schema)でnull値を除去
- **22-29行目**: fromThrowableでyaml.stringifyをラップ
- **24-28行目**: YAML変換オプションの設定

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

```
yamlSchemaDeparser(schema)
    │
    ├─ removeNullValues(schema)
    │      └─ 再帰的にnull値を除去
    │
    └─ fromThrowable(() => yaml.stringify(...))
           │
           └─ yaml.stringify(cleanedSchema, options)
                  └─ YAMLライブラリで文字列変換
```

### データフロー図

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

Schema ──▶ removeNullValues() ──▶ cleanedSchema ──▶ yaml.stringify() ──▶ Result<string, Error>
              │                                           │
              └─ null除去                                 └─ YAML形式文字列
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| schemaDeparser.ts | `frontend/packages/schema/src/deparser/yaml/schemaDeparser.ts` | ソース | YAML変換メインロジック |
| index.ts | `frontend/packages/schema/src/deparser/yaml/index.ts` | ソース | エクスポート定義 |
| type.ts | `frontend/packages/schema/src/deparser/type.ts` | ソース | SchemaDeparser型定義 |
| schemaDeparser.test.ts | `frontend/packages/schema/src/deparser/yaml/schemaDeparser.test.ts` | テスト | YAML変換の単体テスト |
