env-validator

Env Validator

.env ファイルとプロジェクトの要件を照合して、環境変数の設定を検証します。不足している変数、型エラー、安全でないデフォルト値、孤立した項目を、実行時エラーの原因になる前に検出します。

参照ファイル

ファイル	内容	読み込むタイミング
references/validation-rules.md	組み込みの検証ルールと重大度の定義	常に

前提条件

• プロジェクト内に .env ファイル（または同等のファイル）があること
• 任意：相互参照用の .env.example、docker-compose.yml、またはデプロイメントマニフェスト

ワークフロー

フェーズ 1：検出

プロジェクト内の環境設定ソースを特定します。

1. 主要ファイル： プロジェクトのルートにある .env を探します。ない場合は、.env.local、.env.development、.env.production を確認します
2. スキーマファイル： .env.example または .env.template を探します。これらには想定される変数が定義されています
3. コード内の参照： os.environ、process.env、env::var、os.Getenv のパターンを grep し、コード内で参照されている変数を見つけます
4. デプロイメントマニフェスト： docker-compose.yml、Dockerfile、k8s/ のマニフェストを確認し、${VAR} または ENV VAR のパターンを探します

続行する前に、見つかった内容を報告します。

フェーズ 2：スキーマの抽出

検出したソースから、想定される変数スキーマを作成します。

すべてのソースから見つかった変数について、次の項目を記録します。

項目	ソース
名前	変数名（例：DATABASE_URL）
必須	コード内で参照されている、または例で必須と指定されている
型のヒント	使用方法から推測（URL、整数、ブール値、文字列、パス）
デフォルト	存在する場合は .env.example の値
使用箇所	この変数を参照するファイルの一覧

フェーズ 3：検証

主要な .env ファイルに対して、次のチェックを実行します。

1. 必須変数の不足（重大）

   • コード内で参照されているが、.env に存在しない変数
   • .env.example にあり、デフォルト値がないものの、.env に存在しない変数

2. 型の不一致（高）

   • コードで int(os.environ["PORT"]) を実行するのに PORT=abc が設定されている
   • コードでブール値（true／false）が想定されているのに DEBUG=yes が設定されている
   • 有効な URL 形式ではない URL 変数

3. 安全でないデフォルト値（高）

   • SECRET_KEY=changeme、PASSWORD=password、API_KEY=xxx
   • 本番環境向けのファイルに DEBUG=true または DEBUG=1 が設定されている
   • セキュリティ上重要な変数の値が空

4. 参照されていない変数（中）

   • コードまたはマニフェストのどこからも参照されていない .env 内の変数
   • 古い設定である可能性があります

5. 形式の問題（低）

   • KEY=VALUE 形式ではない行
   • 値の末尾にある空白
   • 引用符の形式が一貫していない（一重引用符、二重引用符、引用符なしが混在）
   • 変数の定義が重複している（最後の定義が有効になりますが、誤りの可能性があります）

ルールの全一覧については、references/validation-rules.md を参照してください。

フェーズ 4：レポート

構造化された検証レポートを作成します。

# Environment Validation Report

**File:** `.env`
**Schema:** `.env.example` + code references
**Verdict:** PASS | FAIL

## Summary

| Severity | Count |
|----------|-------|
| CRITICAL | N     |
| HIGH     | N     |
| MEDIUM   | N     |
| LOW      | N     |

## CRITICAL

### [ENV-001] Missing required variable: DATABASE_URL

- **Referenced in:** `src/db.py:12`, `docker-compose.yml:8`
- **Expected type:** URL (postgresql://...)
- **Fix:** Add `DATABASE_URL=postgresql://user:pass@localhost:5432/dbname` to `.env`

## HIGH

...

## Unreferenced Variables

| Variable        | In .env | In Code | In Manifests | Status       |
|-----------------|---------|---------|--------------|--------------|
| LEGACY_API_KEY  | Yes     | No      | No           | Unreferenced |

## Recommendations

1. [Highest priority fix]
2. [Second fix]

エラー処理

エラー	解決方法
.env ファイルが見つからない	不在を報告し、代替の環境変数ソースを確認します
.env.example またはスキーマがない	コード内の参照のみを基に検証します
バイナリ形式または非常に大きい .env	スキップし、未対応の形式として報告します
コード内の参照が見つからない	形式とセキュリティのみを検証し、完全性の確認は省略します

制限事項

• Vault、AWS SSM などから実行時に注入される変数は検証できません
• 型推論はヒューリスティックなため、複雑な値を誤分類する場合があります
• 変数の値を外部サービスに照らして検証することはできません（例：有効な API キーの形式）
• 本番環境と開発環境の区別には、ファイル名の規則が必要です