# バッチ設計書 44-ls-lint（ls-lint.yml）

## 概要

本ドキュメントは、GitHub Actionsワークフロー「Lint」（ls-lint.yml）のバッチ設計書である。Pull Request時にls-lintを使用してリポジトリ内のファイル名およびディレクトリ名がプロジェクトの命名規則に準拠しているかを検証するワークフローについて記載する。

### 本バッチの処理概要

本ワークフローは、Pull Request時にls-lintツールを使用してファイル名の命名規則（snake_case等）を自動検証し、プロジェクトの一貫したファイル命名規則を維持する。

**業務上の目的・背景**：mrubyプロジェクトでは、ソースファイル（.c, .h, .rb等）にsnake_case、設定ファイル（.yaml, .yml）にはケバブケースの命名規則を採用している。多数のコントリビューターが参加するOSSプロジェクトにおいて、ファイル命名規則の違反を自動検出することで、コードベースの統一性を保ち、ファイルの検索性や可読性を維持する。

**バッチの実行タイミング**：Pull Request作成時および更新時に自動実行される。

**主要な処理内容**：
1. リポジトリのソースコードをチェックアウトする
2. ls-lintを`.github/linters/.ls-lint.yml`の設定に従って実行し、ファイル名規則を検証する

**前後の処理との関連**：本ワークフローはPull Requestの品質ゲートとして機能し、pre-commit（No.42）やSuper-Linter（No.43）等の他のLintワークフローと並行して実行される。命名規則の設定は`.github/linters/.ls-lint.yml`で管理される。

**影響範囲**：Pull Requestのマージ可否判定。ファイル名規則の検証結果がPull Requestのステータスチェックとして表示される。

## バッチ種別

品質管理 / ファイル名規則チェック / CI（継続的インテグレーション）

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（イベント駆動） |
| 実行時刻 | 該当なし（イベントトリガー） |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | Pull Request作成・更新時 |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| GitHubリポジトリ | mrubyリポジトリがGitHub上に存在すること |
| Pull Request | Pull Requestイベントが発生していること |
| ls-lint設定 | `.github/linters/.ls-lint.yml`が存在すること |

### 実行可否判定

GitHub Actionsのpull_requestイベントトリガーにより自動判定される。全てのPull Requestに対して実行され、ブランチのフィルタリングは行われない。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| config | string | Yes | .github/linters/.ls-lint.yml | ls-lint設定ファイルのパス |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| リポジトリソースコード | ファイルシステム | チェックアウトされたソースコード全体 |
| .github/linters/.ls-lint.yml | YAML | ファイル名命名規則の設定ファイル |

### ls-lint設定内容

`.github/linters/.ls-lint.yml`で定義されている命名規則は以下の通り：

| 拡張子 | 命名規則 |
|--------|---------|
| .c | snake_case |
| .cpp | snake_case |
| .h | snake_case |
| .json | snake_case |
| .rb | snake_case |
| .yaml | regex:`.?[a-z]+(-[a-z]+)*` |
| .yml | regex:`.?[a-z]+(-[a-z]+)*` |

除外ディレクトリ：
- `build_config`
- `mrbgems/mruby-compiler/core/y.tab.c`

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| Pull Requestステータス | GitHub Check | ワークフローの成功/失敗ステータス |
| GitHub Actionsログ | テキスト | ファイル名規則検証結果の詳細ログ |

### 出力ファイル仕様

本ワークフローはファイル出力を行わない。結果はGitHub Actionsのログおよびチェックステータスとして出力される。

| 項目 | 内容 |
|-----|------|
| ファイル名 | 該当なし |
| 出力先 | GitHub Actionsログ |
| 文字コード | 該当なし |
| 区切り文字 | 該当なし |

## 処理フロー

### 処理シーケンス

```
1. リポジトリチェックアウト
   └─ actions/checkout@v6でソースコードを取得
2. ls-lint実行
   └─ ls-lint/action@v2.3.1で.github/linters/.ls-lint.ymlに従ってファイル名規則を検証
```

### フローチャート

```mermaid
flowchart TD
    A[ワークフロー開始<br>Pull Request] --> B[リポジトリチェックアウト<br>actions/checkout@v6]
    B --> C[ls-lint実行<br>config: .github/linters/.ls-lint.yml]
    C --> D{検証結果}
    D -->|規則準拠| E[ワークフロー成功]
    D -->|規則違反| F[ワークフロー失敗<br>違反ファイル名を出力]
```

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

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

本ワークフローはデータベース操作を行わない。

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 該当なし | 該当なし | 該当なし | 該当なし |

### テーブル別操作詳細

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ファイル名規則違反 | ファイル名が設定された命名規則に準拠していない場合 | ファイル名を規則に合わせてリネームしPRを更新する |
| - | 設定ファイルエラー | .ls-lint.ymlの構文エラーまたはファイル不存在 | 設定ファイルを修正する |
| - | ls-lintセットアップエラー | ls-lintアクションのインストールに失敗した場合 | GitHub Actionsを再実行する |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 手動で再実行（GitHub Actions UIまたはPR更新） |
| リトライ間隔 | 該当なし（手動） |
| リトライ対象エラー | 一時的なインフラエラー |

### 障害時対応

ファイル名規則違反による失敗の場合は、ログから違反ファイル名を特定し、リネームしてPull Requestを更新する。設定ファイルの問題の場合は`.github/linters/.ls-lint.yml`を修正する。

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 該当なし（CI/CDパイプライン） |
| コミットタイミング | 該当なし |
| ロールバック条件 | 該当なし |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | リポジトリ全ファイル（除外ディレクトリを除く） |
| 目標処理時間 | 明示的な規定なし（ファイル名チェックのため高速に完了する想定） |
| メモリ使用量上限 | ubuntu-latestランナーのデフォルト（7GB RAM） |

## 排他制御

GitHub Actionsの標準動作により、同一PRに対する複数のワークフロー実行が発生する可能性がある。concurrencyの設定は定義されていないため、同時実行が許可されている。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | ワークフロー開始時 | GitHub Actionsの標準ログ（PRイベント情報） |
| 進捗ログ | 検証中 | 検証対象ファイルの走査状況 |
| 終了ログ | ワークフロー終了時 | 検証結果サマリー |
| エラーログ | 違反検出時 | 違反ファイル名、期待される命名規則 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| ワークフロー失敗 | 1回 | GitHubリポジトリの通知設定に従う |
| ファイル名規則違反 | 1件以上 | Pull Requestのステータスチェック |

## 備考

- ls-lint/action@v2.3.1を使用している
- 設定ファイルは`.github/linters/.ls-lint.yml`に配置されている
- ソースファイル（.c, .cpp, .h, .json, .rb）はsnake_case、設定ファイル（.yaml, .yml）はケバブケース（正規表現指定）の命名規則
- `build_config`ディレクトリと`mrbgems/mruby-compiler/core/y.tab.c`は検証対象から除外されている
- 権限設定は`contents: read`のみ
- ワークフロー名は「Lint」、ジョブ名は「Run ls-lint」
