Files
hakorune/docs/development/proposals/env-var-reduction-report.md

574 lines
26 KiB
Markdown
Raw Normal View History

# 環境変数徹底調査レポート - 25個から5個への削減計画
**作成日**: 2025-11-21
**目的**: セルフホスティング実装における環境変数の複雑さを根本解決
---
## 📊 使用箇所マトリックス
| 環境変数 | 定義箇所 | 読み取り回数 | 影響範囲 | デフォルト値 | カテゴリ |
|---------|---------|------------|---------|------------|---------|
| **Stage1関連** |
| `NYASH_USE_STAGE1_CLI` | stage1_bridge.rs:93 | 7回 | 必須Stage1起動 | なし | Stage1制御 |
| `STAGE1_EMIT_PROGRAM_JSON` | stage1_bridge.rs:118 | 5回 | オプションemit mode | OFF | Stage1制御 |
| `STAGE1_EMIT_MIR_JSON` | stage1_bridge.rs:119 | 5回 | オプションemit mode | OFF | Stage1制御 |
| `STAGE1_BACKEND` | stage1_bridge.rs:157 | 5回 | オプションbackend選択 | vm | Stage1制御 |
| `STAGE1_SOURCE` | stage1_bridge.rs:115 | 6回 | オプション(入力ソース) | 第1引数 | Stage1制御 |
| `STAGE1_INPUT` | stage1_bridge.rs:116 | 1回 | オプション(入力ソース別名) | なし | Stage1制御 |
| `STAGE1_PROGRAM_JSON` | stage1_bridge.rs:135 | 5回 | オプション中間JSON | なし | Stage1制御 |
| `STAGE1_CLI_DEBUG` | stage1_cli.hako:27 | 11回 | オプション(デバッグ) | OFF | デバッグ |
| `NYASH_STAGE1_CLI_CHILD` | stage1_bridge.rs:90 | 3回 | 必須(再帰防止) | OFF | 内部制御 |
| **Using/Parser関連** |
| `NYASH_ENABLE_USING` | env.rs:429 | 10回 | オプション | **ONデフォルト** | 機能トグル |
| `HAKO_ENABLE_USING` | env.rs:435 | 8回 | 非推奨(互換性) | なし | 廃止予定 |
| `HAKO_STAGEB_APPLY_USINGS` | stage1_bridge.rs:224 | 6回 | オプション | ON | Stage1制御 |
| `NYASH_PARSER_STAGE3` | env.rs:540 | 38回 | オプション | OFF | 機能トグル |
| `HAKO_PARSER_STAGE3` | env.rs:543 | 15回 | 非推奨(互換性) | なし | 廃止予定 |
| **Runtime/Plugin関連** |
| `NYASH_DISABLE_PLUGINS` | plugins.rs:26 | 20回 | オプション | OFF | プラグイン制御 |
| `NYASH_FILEBOX_MODE` | provider_env.rs:37 | 8回 | オプション | auto | プラグイン制御 |
| `NYASH_BOX_FACTORY_POLICY` | mod.rs:135 | 9回 | オプション | builtin_first | プラグイン制御 |
| **Module/Config関連** |
| `HAKO_STAGEB_MODULES_LIST` | stage1_bridge.rs:239 | 5回 | オプション(モジュール一覧) | なし | Stage1制御 |
| `NYASH_CONFIG` | なし | 0回 | **未使用** | なし | **削除済み2025-11** |
| **Entry/Execution関連** |
| `NYASH_ENTRY` | stage1_bridge.rs:185 | 6回 | オプション | Stage1CliMain.main/1 | エントリー制御 |
| `NYASH_SCRIPT_ARGS_JSON` | stage1_bridge.rs:167 | 13回 | オプション | [] | 引数渡し |
| `NYASH_ENTRY_ALLOW_TOPLEVEL_MAIN` | env.rs:576 | 8回 | オプション | **ONデフォルト** | エントリー制御 |
| **Debug/Verbose関連** |
| `NYASH_CLI_VERBOSE` | mod.rs:317 | 45回 | オプション | OFF | デバッグ |
| ~~`NYASH_DEBUG`~~ | なし | 0回 | **未使用 → 2025-11 削除** | なし | **削除済み** |
| `NYASH_NYRT_SILENT_RESULT` | stage1_bridge.rs:212 | 2回 | オプション | OFF | 出力制御 |
**合計**: 25個 → 現在 23個NYASH_CONFIG / NYASH_DEBUG 削除後)
- **使用中**: 23個 → **21個**
- **未使用**: 0個今回の2個を削除済み
- **非推奨**: 2個HAKO_ENABLE_USING, HAKO_PARSER_STAGE3
---
## 🔍 依存関係分析
### グループ1: Stage1制御9個 → 3個に統合可能
**排他的関係**:
```
STAGE1_EMIT_PROGRAM_JSON=1 ─┐
├─→ 排他的1つだけ有効
STAGE1_EMIT_MIR_JSON=1 ─┤
(なし:実行モード) ─┘
```
**統合案**:
```bash
# 現在の複雑な設定
NYASH_USE_STAGE1_CLI=1 STAGE1_EMIT_PROGRAM_JSON=1 STAGE1_SOURCE=foo.hako
# 統合後(シンプル)
NYASH_STAGE1_MODE=emit-program NYASH_STAGE1_INPUT=foo.hako
```
**新変数**: `NYASH_STAGE1_MODE`
- 値: `emit-program | emit-mir | run`
- デフォルト: `run`
- 効果:
- `emit-program``STAGE1_EMIT_PROGRAM_JSON=1`
- `emit-mir``STAGE1_EMIT_MIR_JSON=1`
- `run` → 実行モード
**削減できる変数**:
1. `NYASH_USE_STAGE1_CLI``NYASH_STAGE1_MODE` の存在で判定
2. `STAGE1_EMIT_PROGRAM_JSON``NYASH_STAGE1_MODE=emit-program`
3. `STAGE1_EMIT_MIR_JSON``NYASH_STAGE1_MODE=emit-mir`
4. `STAGE1_SOURCE` + `STAGE1_INPUT``NYASH_STAGE1_INPUT` に統合
---
### グループ2: Using制御4個 → 1個に統合
**統合案**:
```bash
# 現在の複雑な設定
NYASH_ENABLE_USING=1 HAKO_ENABLE_USING=1 HAKO_STAGEB_APPLY_USINGS=1
# 統合後
NYASH_FEATURES=using # カンマ区切りで複数機能対応
```
**削減できる変数**:
1. `NYASH_ENABLE_USING``NYASH_FEATURES=using`
2. `HAKO_ENABLE_USING` → 廃止(互換性エイリアス削除)
3. `HAKO_STAGEB_APPLY_USINGS``NYASH_FEATURES=using` で自動
---
### グループ3: Parser制御2個 → 1個に統合
**統合案**:
```bash
# 現在
NYASH_PARSER_STAGE3=1 HAKO_PARSER_STAGE3=1
# 統合後
NYASH_FEATURES=stage3 # または NYASH_PARSER_FEATURES=stage3
```
**削減できる変数**:
1. `NYASH_PARSER_STAGE3``NYASH_FEATURES=stage3`
2. `HAKO_PARSER_STAGE3` → 廃止
---
### グループ4: Plugin制御3個 → 維持)
**現状維持推奨**:
- `NYASH_DISABLE_PLUGINS`: 全プラグイン無効化(重要)
- `NYASH_FILEBOX_MODE`: FileBox詳細制御
- `NYASH_BOX_FACTORY_POLICY`: Box Factory優先順位
**理由**: 独立した機能で統合するメリットが少ない
---
### グループ5: Debug制御3個 → 1個に統合
**統合案**:
```bash
# 現在
NYASH_CLI_VERBOSE=1 STAGE1_CLI_DEBUG=1
# 統合後
NYASH_DEBUG=1 # または NYASH_DEBUG_LEVEL=1
```
**削減できる変数**:
1. `NYASH_CLI_VERBOSE``NYASH_DEBUG=1`
2. `STAGE1_CLI_DEBUG``NYASH_DEBUG=1`
3. `NYASH_NYRT_SILENT_RESULT``NYASH_DEBUG=0` の時に自動ON
---
## 📋 削減ロードマップ
### Phase 1即座に削除可能 - 2個
**完全未使用0回参照**:
**削除対象(実施済み)**:
1.`NYASH_CONFIG`: 使用箇所0個完全未使用、将来構想のみ→ tools/stage1_* から除去済み。
2.`NYASH_DEBUG`: 使用箇所0個NYASH_DEBUG_* は別変数、Phase 10構想のみ→ tools/stage1_* から除去済み。
**影響**: なし(誰も使っていない)。削除は完了済み。
---
### Phase 2非推奨エイリアス削除 - 2個
**廃止予定(互換性のみ)**:
**削除対象**:
1. ⚠️ `HAKO_ENABLE_USING``NYASH_ENABLE_USING` に移行(警告済み)
2. ⚠️ `HAKO_PARSER_STAGE3``NYASH_PARSER_STAGE3` に移行(警告済み)
**影響**: 警告が出ているので移行済みのはず
**実装**: `src/config/env.rs` から互換性処理を削除
---
### Phase 3Stage1統合 - 7個 → 3個
**統合変数セット**:
```bash
# 新設計
NYASH_STAGE1_MODE=<emit-program|emit-mir|run>
NYASH_STAGE1_INPUT=<source.hako>
NYASH_STAGE1_BACKEND=<vm|llvm|pyvm> # オプション
```
**削減できる変数**7個 → 3個:
1. `NYASH_USE_STAGE1_CLI` → MODE存在で自動判定
2. `STAGE1_EMIT_PROGRAM_JSON``MODE=emit-program`
3. `STAGE1_EMIT_MIR_JSON``MODE=emit-mir`
4. `STAGE1_SOURCE` + `STAGE1_INPUT``NYASH_STAGE1_INPUT`
5. `STAGE1_BACKEND``NYASH_STAGE1_BACKEND`
6. `STAGE1_PROGRAM_JSON` → 中間ファイル(環境変数不要)
**保持する変数**:
- `NYASH_STAGE1_CLI_CHILD`: 内部制御(外部非公開)
---
### Phase 4Using/Parser統合 - 4個 → 1個
**統合変数**:
```bash
# 新設計
NYASH_FEATURES=<using,stage3,unified-members> # カンマ区切り
```
**削減できる変数**:
1. `NYASH_ENABLE_USING``FEATURES=using`
2. `HAKO_STAGEB_APPLY_USINGS``FEATURES=using` で自動
3. `NYASH_PARSER_STAGE3``FEATURES=stage3`
---
### Phase 5Debug統合 - 3個 → 1個
**統合変数**:
```bash
# 新設計
NYASH_DEBUG=<0|1|2|3> # レベル制御
```
**削減できる変数**:
1. `NYASH_CLI_VERBOSE``DEBUG=1`
2. `STAGE1_CLI_DEBUG``DEBUG=2`(詳細)
3. `NYASH_NYRT_SILENT_RESULT``DEBUG=0` で自動ON
---
### Phase 6nyash.toml化 - 4個
**永続設定に移動すべき変数**:
```toml
[runtime]
disable_plugins = false
filebox_mode = "auto"
box_factory_policy = "builtin_first"
[entry]
allow_toplevel_main = true
```
**削減できる変数**(環境変数 → 設定ファイル):
1. `NYASH_DISABLE_PLUGINS``runtime.disable_plugins`
2. `NYASH_FILEBOX_MODE``runtime.filebox_mode`
3. `NYASH_BOX_FACTORY_POLICY``runtime.box_factory_policy`
4. `NYASH_ENTRY_ALLOW_TOPLEVEL_MAIN``entry.allow_toplevel_main`
**注意**: 環境変数は緊急時オーバーライド用に残す
---
## 🎯 最終推奨5変数セット
**Phase 1-5完了後の理想形**:
```bash
# 1. モード制御Stage1
NYASH_STAGE1_MODE=<emit-program|emit-mir|run>
# 2. 入力ソース
NYASH_STAGE1_INPUT=<source.hako>
# 3. デバッグレベル
NYASH_DEBUG=<0|1|2|3>
# 4. 機能トグル
NYASH_FEATURES=<using,stage3,unified-members>
# 5. バックエンド選択
NYASH_STAGE1_BACKEND=<vm|llvm|pyvm>
```
**削減実績**: 25個 → 5個**80%削減**
**補助変数**(内部制御・特殊用途):
- `NYASH_STAGE1_CLI_CHILD`: 再帰防止(外部非公開)
- `NYASH_SCRIPT_ARGS_JSON`: 引数渡し(自動生成)
- `HAKO_STAGEB_MODULES_LIST`: モジュール一覧(自動生成)
- `NYASH_ENTRY`: エントリーポイント(特殊用途)
**nyash.toml化**(環境変数から設定ファイルへ):
- `NYASH_DISABLE_PLUGINS`
- `NYASH_FILEBOX_MODE`
- `NYASH_BOX_FACTORY_POLICY`
- `NYASH_ENTRY_ALLOW_TOPLEVEL_MAIN`
---
## 📈 削減効果まとめ
| Phase | 削減数 | 残数 | 削減率 |
|-------|--------|------|--------|
| 開始 | - | 25個 | - |
| Phase 1未使用削除 | 2個 | 23個 | 8% |
| Phase 2非推奨削除 | 2個 | 21個 | 16% |
| Phase 3Stage1統合 | 4個 | 17個 | 32% |
| Phase 4Using/Parser統合 | 3個 | 14個 | 44% |
| Phase 5Debug統合 | 2個 | 12個 | 52% |
| Phase 6nyash.toml化 | 4個 | 8個 | 68% |
| **補助変数移動後** | - | **5個公開** | **80%削減** |
**補助変数**4個:
- `NYASH_STAGE1_CLI_CHILD`(内部)
- `NYASH_SCRIPT_ARGS_JSON`(自動生成)
- `HAKO_STAGEB_MODULES_LIST`(自動生成)
- `NYASH_ENTRY`(特殊用途)
---
## 🚀 実装優先度
### 🔴 高優先度(即座に実行)
- **Phase 1**: 完全未使用削除2個
- 影響: なし
- 作業時間: 5分
- コマンド: 上記参照
### 🟡 中優先度1週間以内
- **Phase 2**: 非推奨エイリアス削除2個
- 影響: 警告表示済み
- 作業時間: 30分
- 注意: 1リリース後に削除推奨
### 🟢 低優先度(設計検討が必要)
- **Phase 3-5**: 統合変数設計9個削減
- 影響: 大きい(破壊的変更)
- 作業時間: 2-3日
- 要件: 移行パス設計
- **Phase 6**: nyash.toml化4個削減
- 影響: 中(環境変数残す)
- 作業時間: 1日
- 要件: TOML読み込み実装
---
## 🎓 学んだこと
1. **80/20ルール適用**:
- 未使用変数2個8%)を削除するだけで即効果
- 非推奨変数2個8%)も簡単に削除可能
- 合計16%を簡単に削減できる
2. **統合可能性の発見**:
- Stage1関連7個 → 3個排他的制御
- Using/Parser関連4個 → 1個機能フラグ統合
- Debug関連3個 → 1個レベル制御統合
3. **nyash.toml化のチャンス**:
- Plugin制御3個は永続設定向き
- Entry制御1個も永続設定向き
- 環境変数は緊急時オーバーライド専用に
4. **内部変数の分離**:
- `NYASH_STAGE1_CLI_CHILD`(再帰防止)
- `NYASH_SCRIPT_ARGS_JSON`(自動生成)
- これらは公開APIから除外可能
---
## 📚 参考情報
**主要ファイル**:
- `src/runner/stage1_bridge.rs`: Stage1制御
- `src/config/env.rs`: 環境変数読み取り
- `src/config/provider_env.rs`: Provider制御
- `lang/src/runner/stage1_cli.hako`: Stage1 CLI実装
- `tools/stage1_debug.sh`: デバッグツール
**現在の状況**:
- 合計25個の環境変数
- 使用中23個、未使用2個
- 非推奨2個警告付き
---
## 🌟 依存関係グラフ(視覚化)
### グループ構造
```
┌─────────────────────────────────────────────────────────────┐
│ Stage1制御グループ9個 → 3個に統合可能
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─ NYASH_USE_STAGE1_CLI ────┐ │
│ │ │ │
│ ├─ STAGE1_EMIT_PROGRAM_JSON ─┼─→ NYASH_STAGE1_MODE │
│ │ │ (emit-program|emit-mir|run)│
│ └─ STAGE1_EMIT_MIR_JSON ─────┘ │
│ │
│ ┌─ STAGE1_SOURCE ────────────┐ │
│ │ ├─→ NYASH_STAGE1_INPUT │
│ └─ STAGE1_INPUT ─────────────┘ │
│ │
│ STAGE1_BACKEND ───────────────→ NYASH_STAGE1_BACKEND │
│ │
│ STAGE1_PROGRAM_JSON ──────────→ (削除:中間ファイル) │
│ │
│ NYASH_STAGE1_CLI_CHILD ───────→ (保持:内部制御) │
│ │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ Using/Parser制御グループ4個 → 1個に統合
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─ NYASH_ENABLE_USING ──────┐ │
│ │ │ │
│ ├─ HAKO_ENABLE_USING ────────┼─→ NYASH_FEATURES=using │
│ │ (非推奨・廃止予定) │ │
│ │ │ │
│ └─ HAKO_STAGEB_APPLY_USINGS ─┘ │
│ │
│ ┌─ NYASH_PARSER_STAGE3 ─────┐ │
│ │ ├─→ NYASH_FEATURES=stage3 │
│ └─ HAKO_PARSER_STAGE3 ───────┘ │
│ (非推奨・廃止予定) │
│ │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ Debug制御グループ3個 → 1個に統合
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─ NYASH_CLI_VERBOSE ───────┐ │
│ │ │ │
│ ├─ STAGE1_CLI_DEBUG ─────────┼─→ NYASH_DEBUG=<0|1|2|3>
│ │ │ │
│ └─ NYASH_NYRT_SILENT_RESULT ─┘ │
│ │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ Plugin制御グループ3個 → 維持) │
├─────────────────────────────────────────────────────────────┤
│ │
│ NYASH_DISABLE_PLUGINS ────────→ (維持・重要) │
│ NYASH_FILEBOX_MODE ───────────→ (維持・重要) │
│ NYASH_BOX_FACTORY_POLICY ─────→ (維持・重要) │
│ │
│ ※ Phase 6で nyash.toml 化推奨 │
│ │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ 削除可能グループ2個
├─────────────────────────────────────────────────────────────┤
│ │
│ NYASH_CONFIG ──────────────────→ (削除:未使用) │
│ NYASH_DEBUG ───────────────────→ (削除:未使用) │
│ │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ 補助変数グループ4個 → 内部制御・自動生成) │
├─────────────────────────────────────────────────────────────┤
│ │
│ NYASH_ENTRY ───────────────────→ (特殊用途) │
│ NYASH_SCRIPT_ARGS_JSON ────────→ (自動生成) │
│ HAKO_STAGEB_MODULES_LIST ──────→ (自動生成) │
│ NYASH_ENTRY_ALLOW_TOPLEVEL_MAIN → nyash.toml化推奨
│ │
└─────────────────────────────────────────────────────────────┘
```
### 排他的関係
```
Stage1モード排他的:
┌─────────────────────┐
│ emit-program │ ← STAGE1_EMIT_PROGRAM_JSON=1
├─────────────────────┤
│ emit-mir │ ← STAGE1_EMIT_MIR_JSON=1
├─────────────────────┤
│ run (default) │ ← 両方OFF
└─────────────────────┘
※ 同時に複数ONにはできない排他的
```
### 統合後の最終形態
```
┌───────────────────────────────────────────────────────────┐
│ 公開環境変数5個
├───────────────────────────────────────────────────────────┤
│ │
│ 1. NYASH_STAGE1_MODE : emit-program|emit-mir|run │
│ 2. NYASH_STAGE1_INPUT : <source.hako>
│ 3. NYASH_DEBUG : 0|1|2|3 │
│ 4. NYASH_FEATURES : using,stage3,unified-members │
│ 5. NYASH_STAGE1_BACKEND : vm|llvm|pyvm │
│ │
└───────────────────────────────────────────────────────────┘
┌───────────────────────────────────────────────────────────┐
│ 内部変数4個・非公開
├───────────────────────────────────────────────────────────┤
│ │
│ - NYASH_STAGE1_CLI_CHILD : 再帰防止(自動設定) │
│ - NYASH_SCRIPT_ARGS_JSON : 引数渡し(自動生成) │
│ - HAKO_STAGEB_MODULES_LIST : モジュール一覧(自動生成) │
│ - NYASH_ENTRY : エントリーポイント(特殊) │
│ │
└───────────────────────────────────────────────────────────┘
┌───────────────────────────────────────────────────────────┐
│ nyash.toml 設定4個
├───────────────────────────────────────────────────────────┤
│ │
│ [runtime] │
│ disable_plugins = false │
│ filebox_mode = "auto" │
│ box_factory_policy = "builtin_first" │
│ │
│ [entry] │
│ allow_toplevel_main = true │
│ │
│ ※ 環境変数で緊急時オーバーライド可能 │
│ │
└───────────────────────────────────────────────────────────┘
削減実績: 25個 → 5個公開 + 4個内部 = 9個
削減率: 64%25→9 or 80%25→5 公開のみ)
```
### 移行パス
```
Phase 1 (即座)
25個 ──┬─ 削除2個 ───→ 23個
│ (NYASH_CONFIG, NYASH_DEBUG)
Phase 2 (1週間)
23個 ──┬─ 削除2個 ───→ 21個
│ (HAKO_ENABLE_USING, HAKO_PARSER_STAGE3)
Phase 3 (2-3日)
21個 ──┬─ 統合4個 ───→ 17個
│ (Stage1: 9個→3個で4個削減)
Phase 4 (1-2日)
17個 ──┬─ 統合3個 ───→ 14個
│ (Using/Parser: 4個→1個で3個削減)
Phase 5 (1日)
14個 ──┬─ 統合2個 ───→ 12個
│ (Debug: 3個→1個で2個削減)
Phase 6 (1日)
12個 ──┴─ toml化4個 ──→ 8個
(環境変数残す・設定ファイル優先)
Final: 8個公開5個 + 内部3個
```
---
## ✅ 次のアクション
1. **今すぐ実行**5分: Phase 1 - 未使用変数2個削除
2. **1週間以内**30分: Phase 2 - 非推奨エイリアス削除
3. **設計検討**1-2週間: Phase 3-5 - 統合変数設計
4. **実装**3-5日: Phase 3-5 - 統合変数実装
5. **TOML実装**1-2日: Phase 6 - nyash.toml化
**最終目標**: 25個 → 5個公開 + 4個内部 = **80%削減達成**