hakorune/docs/development/current/main/phases/phase-131/p1.5-task5-env-ssot.md

Phase 131 Task 5: Environment Variable SSOT Implementation

Status: ✅ Complete Date: 2025-12-18 Implementation: Environment variable centralization for smoke tests

Overview

Centralized environment variable configuration for tools/smokes/v2/ smoke tests into a single source of truth (SSOT) at tools/smokes/v2/lib/env.sh to prevent "sparrow bugs" (scattered duplicate settings).

Problem Statement

Before this implementation:

• Environment variables were scattered across multiple files
• NYASH_JOINIR_DEV and HAKO_JOINIR_STRICT duplicated in:
  • test_runner.sh (line 855-856)
  • llvm_exe_runner.sh (line 24-25)
• TMPDIR configuration duplicated in build_llvm.sh
• Using system variables (NYASH_ENABLE_USING, etc.) duplicated in multiple helpers
• Hard to maintain consistency across all smoke tests
• Risk of configuration drift between similar tests

Solution: Centralized env.sh

Created tools/smokes/v2/lib/env.sh (180 lines) as SSOT for all environment variables:

Key Features

1. Centralized Defaults: All environment variables in one place
2. Mode-Based Configuration: Pre-configured modes (dev/integration/quick)
3. Fallback-Safe: Uses ${VAR:-default} pattern for override capability
4. Validation Helpers: Built-in validation and display functions
5. Backward Compatible: Existing scripts work without changes

Environment Variables Managed

JoinIR Development (Phase 131+)

• NYASH_JOINIR_DEV=1 (default: 1)
• HAKO_JOINIR_STRICT=1 (default: 1)

LLVM Features

• NYASH_LLVM_USE_HARNESS=1 (default: 1)
• NYASH_LLVM_BACKEND=crate (default: crate)
• NYASH_LLVM_VERIFY=0 (default: 0)
• NYASH_LLVM_VERIFY_IR=0 (default: 0)

Tmpdir EXDEV Mitigation

• TARGET_TMPDIR=. (default: current directory)

Plugin Loader

• NYASH_LOAD_NY_PLUGINS=0 (default: 0)
• NYASH_DISABLE_PLUGINS=0 (default: 0)

Parser Features

• NYASH_FEATURES=stage3 (default: stage3)
• NYASH_ENABLE_USING=1 (default: 1)
• HAKO_ENABLE_USING=1 (default: 1)
• NYASH_ALLOW_USING_FILE=1 (default: 1)
• HAKO_ALLOW_USING_FILE=1 (default: 1)
• NYASH_USING_AST=1 (default: 1)

Debug Features (gated by SMOKE_DEBUG=1)

• NYASH_CLI_VERBOSE (default: 0, debug: 1)
• HAKO_TRACE_EXECUTION (default: 0, debug: 1)
• HAKO_VERIFY_SHOW_LOGS (default: 0, debug: 1)
• NYASH_DEBUG_FUEL (default: 10000, dev: unlimited)

Other

• HAKO_SILENT_TAGS=1 (default: 1)

Implementation Details

Files Modified

1. New File: tools/smokes/v2/lib/env.sh

Lines: 180 Purpose: SSOT for all environment variables

Key Functions:

• setup_smoke_env [mode]: Configure for dev/integration/quick modes
• validate_env_setup: Validate environment configuration
• show_smoke_env: Display current configuration

Example Usage:

source "$(dirname "$0")/../lib/env.sh"
setup_smoke_env integration
validate_env_setup
show_smoke_env

2. Modified: tools/smokes/v2/lib/llvm_exe_runner.sh

Changes:

• Added env.sh sourcing (lines 14-18)
• Updated require_joinir_dev() to validate env.sh defaults (lines 31-40)

Before:

require_joinir_dev() {
  export NYASH_JOINIR_DEV=1
  export HAKO_JOINIR_STRICT=1
  echo "[INFO] JoinIR dev mode enabled"
}

After:

require_joinir_dev() {
  # Verify env.sh provided the defaults
  if [ "${NYASH_JOINIR_DEV:-0}" != "1" ]; then
    export NYASH_JOINIR_DEV=1
  fi
  if [ "${HAKO_JOINIR_STRICT:-0}" != "1" ]; then
    export HAKO_JOINIR_STRICT=1
  fi
  echo "[INFO] JoinIR dev mode enabled"
}

3. Modified: tools/smokes/v2/lib/test_runner.sh

Changes:

• Added env.sh sourcing (lines 13-17)
• Updated require_joinir_dev() to use env.sh defaults (lines 861-870)
• Updated enable_mirbuilder_dev_env() to reference env.sh (lines 879-884)
• Updated enable_exe_dev_env() to reference env.sh (lines 905-913)

Improvements:

• Removed hardcoded environment variable settings
• Added SSOT comments referencing env.sh
• Maintained fallback behavior with ${VAR:-default} pattern

4. Modified: tools/build_llvm.sh

Changes:

• Updated TMPDIR configuration to support TARGET_TMPDIR from env.sh (lines 54-58)

Before:

TMPDIR_EFFECTIVE="${TMPDIR:-$CARGO_TARGET_DIR_EFFECTIVE/release/deps}"

After:

# TMPDIR configuration (SSOT: tools/smokes/v2/lib/env.sh sets TARGET_TMPDIR)
# Use TARGET_TMPDIR if set by smoke framework, otherwise fallback to cargo deps dir
TMPDIR_EFFECTIVE="${TMPDIR:-${TARGET_TMPDIR:-$CARGO_TARGET_DIR_EFFECTIVE/release/deps}}"

Documentation

Created tools/smokes/v2/lib/ENV_README.md (comprehensive guide):

• Usage instructions
• Environment variable reference
• Mode presets (dev/integration/quick)
• Migration notes
• Examples
• Troubleshooting

Testing

Validation Tests

# Test env.sh configuration display
source tools/smokes/v2/lib/env.sh && show_smoke_env
# ✅ Pass: Displays all variables correctly

# Test validation
source tools/smokes/v2/lib/env.sh && validate_env_setup
# ✅ Pass: Validation succeeds

# Test dev mode
source tools/smokes/v2/lib/env.sh && setup_smoke_env dev
# ✅ Pass: VERBOSE=1 FUEL=unlimited JOINIR_DEV=1

# Test integration mode
source tools/smokes/v2/lib/env.sh && setup_smoke_env integration
# ✅ Pass: VERBOSE=0 FUEL=10000 JOINIR_DEV=1

# Test quick mode
source tools/smokes/v2/lib/env.sh && setup_smoke_env quick
# ✅ Pass: VERBOSE=0 FUEL=10000 SILENT_TAGS=1

Smoke Test Validation

# Phase 131 VM smoke test
bash tools/smokes/v2/profiles/integration/apps/phase131_loop_true_break_once_vm.sh
# ✅ Pass: All tests passed

# Phase 131 LLVM EXE smoke test
bash tools/smokes/v2/profiles/integration/apps/phase131_loop_true_break_once_llvm_exe.sh
# ✅ Pass: exit code matches expected (1)

# Integration profile (all Phase 131 tests)
bash tools/smokes/v2/run.sh --profile integration --filter "phase131_*"
# ✅ Pass: 2/2 tests passed

Success Criteria

✅ SSOT Achievement

• All environment variables defined in one place (env.sh)
• No duplicate settings across scripts
• Clear documentation of each variable's purpose

✅ Sparrow Prevention

• Individual smoke scripts no longer set environment variables directly
• Helper functions reference env.sh defaults
• Consistent behavior across all tests

✅ Clarity

• Comprehensive comments explain each variable
• Mode-based presets for common scenarios
• Display and validation helpers for debugging

✅ Existing Tests Pass

• All Phase 131 smoke tests pass
• No regression in other smoke tests
• Backward compatible with existing scripts

✅ Reasonable Change Size

• New file: 180 lines (env.sh)
• Modified files: 4 files with minimal changes
• Documentation: 1 comprehensive README

Benefits

1. Maintainability: Single place to update environment variables
2. Consistency: All tests use same defaults
3. Clarity: Clear documentation of available settings
4. Flexibility: Easy to add new variables or modes
5. Debugging: Built-in display and validation helpers
6. Backward Compatibility: Existing scripts work without changes

Future Improvements

1. Auto-validation: Consider enabling SMOKE_ENV_VALIDATE=1 by default
2. Profile-specific configs: Add more mode presets if needed
3. Environment export: Function to export minimal env for CI/CD
4. Deprecation warnings: Warn when scripts set variables directly

Related Documentation

• tools/smokes/v2/lib/ENV_README.md: Comprehensive usage guide
• tools/smokes/v2/README.md: Smoke test system overview
• docs/development/current/main/phases/phase-131/README.md: Phase 131 overview

Conclusion

Task 5 successfully centralizes environment variable configuration into a single source of truth, preventing "sparrow bugs" and improving maintainability. All existing smoke tests pass without modification, demonstrating backward compatibility.

The implementation provides:

• SSOT: Single file (env.sh) for all environment variables
• Mode-based: Pre-configured modes for common scenarios
• Validated: All tests pass with new configuration
• Documented: Comprehensive README for users

This foundation will make future smoke test development more reliable and easier to maintain.