# 機能設計書 83-コミットメッセージフォーマット

## 概要

本ドキュメントは、Decap CMSのGitコミットメッセージのテンプレートベースのフォーマッティング機能について記述する。`commitMessageFormatter`関数により、エントリの作成・更新・削除、メディアのアップロード・削除時のコミットメッセージをカスタマイズ可能な形式で生成する。

### 本機能の処理概要

**業務上の目的・背景**：Decap CMSはGitベースのCMSであり、エントリの保存やメディアの操作はGitコミットとして記録される。コミットメッセージはリポジトリの変更履歴を追跡するために重要であり、プロジェクトの運用ルールに合わせてカスタマイズできる必要がある。本機能は、デフォルトのコミットメッセージテンプレートを提供しつつ、設定ファイルでのカスタマイズを可能にする。

**機能の利用シーン**：エントリの保存（新規作成・更新）、エントリの削除、メディアファイルのアップロード・削除時にGitコミットが行われる際に、コミットメッセージを生成するために使用される。Open Authoringモードではメッセージのラッピングも行う。

**主要な処理内容**：
1. 操作種別（create/update/delete/uploadMedia/deleteMedia/openAuthoring）に応じたテンプレート選択
2. テンプレート内の変数（`{{slug}}`、`{{collection}}`、`{{path}}`、`{{author-login}}`、`{{author-name}}`）の置換
3. 設定ファイル（`config.backend.commit_messages`）によるカスタムテンプレートのマージ
4. Open Authoringモード時のメッセージラッピング

**関連システム・外部連携**：各Gitバックエンド（GitHub、GitLab、Bitbucket等）のコミットAPI

**権限による制御**：Open Authoring時は`openAuthoring`テンプレートが適用される。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 6 | エントリ編集画面 | 主画面 | エントリ保存時のコミットメッセージ生成 |
| 7 | エントリ新規作成画面 | 主画面 | 新規エントリ作成時のコミットメッセージ生成 |
| 9 | メディアライブラリ画面 | 参照画面 | メディアアップロード・削除時のコミットメッセージ生成 |

## 機能種別

テンプレート処理 / 文字列フォーマット

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| type | 'create' / 'update' / 'delete' / 'uploadMedia' / 'deleteMedia' / 'openAuthoring' | Yes | 操作種別 | commitMessageTemplatesのキーに限定 |
| config | CmsConfig | Yes | CMS設定オブジェクト | backend.commit_messagesプロパティを参照 |
| options.slug | string | No | エントリスラッグ | - |
| options.path | string | No | ファイルパス | - |
| options.collection | Collection | No | コレクションオブジェクト | - |
| options.authorLogin | string | No | 作者のログイン名 | - |
| options.authorName | string | No | 作者の表示名 | - |
| isOpenAuthoring | boolean | No | Open Authoringモードかどうか | - |

### 入力データソース

CMS設定ファイル（config.yml）の`backend.commit_messages`セクション、エントリデータ、コレクション設定

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| commitMessage | string | フォーマットされたコミットメッセージ文字列 |

### 出力先

各Gitバックエンドのコミット操作（persistEntry、persistMedia、deleteFiles等）

## 処理フロー

### 処理シーケンス

```
1. テンプレート選択
   ├─ デフォルトテンプレートとconfig.backend.commit_messagesをマージ
   └─ typeに応じたテンプレートを選択
2. 変数置換
   ├─ {{slug}} → options.slug
   ├─ {{path}} → options.path
   ├─ {{collection}} → collection.label_singular || collection.label
   ├─ {{author-login}} → options.authorLogin
   └─ {{author-name}} → options.authorName
3. Open Authoring処理（isOpenAuthoringがtrue時）
   ├─ openAuthoringテンプレートを選択
   ├─ {{message}} → ステップ2で生成したcommitMessage
   ├─ {{author-login}} → options.authorLogin
   └─ {{author-name}} → options.authorName
```

### フローチャート

```mermaid
flowchart TD
    A[commitMessageFormatter呼び出し] --> B[デフォルトテンプレートとカスタムテンプレートをマージ]
    B --> C[typeに応じたテンプレート選択]
    C --> D[変数パターン検索・置換]
    D --> E{isOpenAuthoring?}
    E -->|Yes| F[openAuthoringテンプレートでラッピング]
    E -->|No| G[コミットメッセージ返却]
    F --> G
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-83-01 | デフォルトテンプレート | create: `Create {{collection}} "{{slug}}"`、update: `Update {{collection}} "{{slug}}"`、delete: `Delete {{collection}} "{{slug}}"`等のデフォルトメッセージ | カスタムテンプレート未設定時 |
| BR-83-02 | カスタムテンプレート優先 | config.backend.commit_messagesで指定されたテンプレートはデフォルトを上書きする | 設定ファイルにcommit_messagesがある場合 |
| BR-83-03 | コレクション名取得優先順 | collection.label_singularを優先し、なければcollection.labelを使用 | {{collection}}変数の置換時 |
| BR-83-04 | 未知変数の警告 | テンプレート内の未知変数はconsole.warnで警告し、空文字に置換される | 定義されていない変数が使用された場合 |

### 計算ロジック

テンプレートの変数置換は正規表現 `/\{\{([^}]+)\}\}/g` を使用し、matchした変数名をswitch文で分岐して値を返す。

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

該当なし。本機能は文字列処理のみを行う。

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

なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | console.warn | テンプレート内の未知変数 | 警告ログ出力、空文字で置換 |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

正規表現ベースの文字列置換であり、特別なパフォーマンス要件はない。

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

- コミットメッセージにユーザー入力値（slug、author-name等）が含まれるが、Gitの仕組み上インジェクションリスクは低い
- authorLoginやauthorNameはOpen Authoringモードで外部ユーザーの値が使用される可能性がある

## 備考

- デフォルトテンプレートの一覧:
  - create: `Create {{collection}} "{{slug}}"`
  - update: `Update {{collection}} "{{slug}}"`
  - delete: `Delete {{collection}} "{{slug}}"`
  - uploadMedia: `Upload "{{path}}"`
  - deleteMedia: `Delete "{{path}}"`
  - openAuthoring: `{{message}}`

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | formatters.ts | `packages/decap-cms-core/src/lib/formatters.ts` | Options型（slug、path、collection、authorLogin、authorName） |

**読解のコツ**: `commitMessageTemplates`定数オブジェクト（30-37行目）が全てのデフォルトテンプレートを定義している。

#### Step 2: コミットメッセージフォーマット処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | formatters.ts | `packages/decap-cms-core/src/lib/formatters.ts` | commitMessageFormatter関数 |

**主要処理フロー**:
1. **30-37行目**: commitMessageTemplates定数の定義
2. **39行目**: 変数検出用正規表現 `/\{\{([^}]+)\}\}/g`
3. **49-54行目**: commitMessageFormatter関数のシグネチャ
4. **55行目**: デフォルトテンプレートとカスタムテンプレートのマージ
5. **57-73行目**: typeに応じたテンプレートの変数置換（slug/path/collection/author-login/author-name）
6. **75-93行目**: Open Authoring時のメッセージラッピング処理

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

```
commitMessageFormatter（formatters.ts 49行目）
    |
    +-- templates[type].replace（変数置換）
    |      +-- case 'slug' → options.slug
    |      +-- case 'path' → options.path
    |      +-- case 'collection' → collection.label_singular || collection.label
    |      +-- case 'author-login' → options.authorLogin
    |      +-- case 'author-name' → options.authorName
    |
    +-- [isOpenAuthoring] templates.openAuthoring.replace
           +-- case 'message' → commitMessage
           +-- case 'author-login' → options.authorLogin
           +-- case 'author-name' → options.authorName
```

### データフロー図

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

type（操作種別） ──────────▶ commitMessageFormatter ──────▶ コミットメッセージ文字列
config（CMS設定） ─────────▶   |
options（slug等） ─────────▶   +-- テンプレート選択
isOpenAuthoring ───────────▶   +-- 変数置換
                               +-- [OA] メッセージラッピング
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| formatters.ts | `packages/decap-cms-core/src/lib/formatters.ts` | ソース | commitMessageFormatter関数の定義（49-94行目） |
| entries.ts | `packages/decap-cms-core/src/actions/entries.ts` | ソース | エントリ保存時にcommitMessageFormatterを呼び出す |
| mediaLibrary.ts | `packages/decap-cms-core/src/actions/mediaLibrary.ts` | ソース | メディア操作時にcommitMessageFormatterを呼び出す |
| editorialWorkflow.ts | `packages/decap-cms-core/src/actions/editorialWorkflow.ts` | ソース | ワークフロー操作時にcommitMessageFormatterを呼び出す |
