feat(config): add default/environment sources key-value pairs

[kaihowl]

Add support for default and environment-based source key-value pairs in configuration.

This would allow users to define default metadata or pull configuration values from environment variables.

Related to TODO item: add default / environment sources key-value pairs

[kaihowl]

Research Summary: Environment Variable Tracking

I've researched standard environment variables across CI/CD platforms and propose a solution for automatic metadata tracking.

---

🔍 Key Findings

Standard Environment Variables by Platform

GitHub Actions (current project CI):

• GITHUB_SHA - Commit hash
• GITHUB_REF_NAME - Branch name
• GITHUB_RUN_ID - Unique run identifier
• GITHUB_WORKFLOW - Workflow name
• RUNNER_OS - OS family (Linux/macOS/Windows)
• RUNNER_ARCH - Architecture (X64/ARM64)
• RUNNER_NAME - Runner identifier
• ImageOS - OS version (e.g., "ubuntu24", "macos13")

Other platforms (GitLab CI, CircleCI, Travis, Jenkins) have similar variables with different names.

Current Pain Point

The project currently manually specifies metadata in .github/workflows/ci.yml:

cargo run -- import criterion-json bench.json \
  --metadata ci=true \
  --metadata workflow="${GITHUB_WORKFLOW}" \
  --metadata commit="${GITHUB_SHA:0:7}" \
  --metadata os=${{matrix.os}}

This is tedious and error-prone.

---

💡 Proposed Solution

Configuration-Based Environment Mapping

Add new sections to .gitperfconfig:

[environment]
# Simple mappings
commit = "GITHUB_SHA"           # Auto-truncates to 8 chars
branch = "GITHUB_REF_NAME"
run_id = "GITHUB_RUN_ID"
ci = "CI"
workflow = "GITHUB_WORKFLOW"
runner_os = "RUNNER_OS"
runner_arch = "RUNNER_ARCH"
os_image = "ImageOS"            # GitHub: "ubuntu24", "macos13"

# Multi-source with priority (first found wins)
runner_id = ["RUNNER_NAME", "CI_RUNNER_ID", "NODE_NAME", "Agent.Name"]

[defaults]
# Fallback values when env vars not set
environment = "local"

Precedence Order

For each metadata key:

1. CLI --key-value (highest priority) - explicit override
2. CLI --skip-env - blocks environment detection for specified keys
3. CLI --no-env - blocks all environment detection
4. Environment variable mappings (from [environment] section)
5. Default values (from [defaults] section - lowest priority)

Per-Measurement Control

New CLI flags for fine-grained control:

# Normal measurement - uses environment tracking
cargo run -- measure build

# Disable ALL environment tracking for this measurement
cargo run -- measure build --no-env

# Skip specific environment keys for this measurement
cargo run -- measure build --skip-env runner_id,os_image

# Override environment-detected value for this measurement  
cargo run -- measure build --key-value commit=abc12345

---

🎯 Benefits

1. Eliminates CI boilerplate - No manual --metadata flags needed in workflows
2. Rich automatic context - Tracks commit, branch, runner, OS version, etc.
3. Cross-platform - Works with GitHub Actions, GitLab CI, CircleCI, Jenkins, Travis, Azure
4. Flexible - Users control what gets tracked via config
5. Per-measurement control - Can disable or override for specific measurements
6. Secure - Whitelist-only approach prevents accidental secret leakage
7. Fast - Only reads environment variables (no command execution)

Example: Before vs After

Before (manual):

cargo run -- import criterion-json bench.json \
  --metadata ci=true \
  --metadata workflow="${GITHUB_WORKFLOW}" \
  --metadata commit="${GITHUB_SHA:0:7}" \
  --metadata os=${{matrix.os}} \
  --metadata runner="${{runner.name}}"

After (automatic):

cargo run -- import criterion-json bench.json
# Auto-includes: ci, workflow, commit, branch, run_id, os_image, runner_id, runner_os

---

🤔 Design Questions / Options

1. CLI Flag Naming

Option A: --no-env and --skip-env
Option B: --disable-env and --exclude-env

2. Per-Measurement Config

Option A (CLI-only control): Only use CLI flags for per-measurement overrides
Option B (Config + CLI): Also support measurement-specific config:

[measurement."build_time"]
environment.enabled = false  # Disable for this measurement

[measurement."test_time"]  
environment.skip = ["runner_id"]  # Skip specific keys

3. Default Behavior

When [environment] section exists in config:
Option A (Opt-out): Environment tracking enabled by default, use --no-env to disable
Option B (Opt-in): Environment tracking disabled by default, need flag to enable

4. Scope of Configuration

Option A: Only per-repo (.gitperfconfig)
Option B: System-wide (~/.config/git-perf/config.toml) + per-repo with override

5. OS Version Detection

Option A (Environment variables only): Use ImageOS, TRAVIS_DIST, etc. - simpler, faster
Option B (Command fallback): Also support command execution (e.g., parse /etc/os-release, run sw_vers) - more complex, slower

Current recommendation: Option A (env vars only) for simplicity and performance

---

📋 Implementation Checklist

If this proposal is accepted:

• Extend config system to support [environment] and [defaults] sections
• Add CLI flags: --no-env, --skip-env
• Implement resolve_key_values() function with precedence logic
• Add SHA truncation (8 chars for commit hashes)
• Add security blacklist for sensitive variables (*TOKEN*, *SECRET*, etc.)
• Update measure, add, import commands to use environment resolution
• Unit tests for config parsing, resolution, precedence
• Integration tests for end-to-end workflows
• Update manpages and documentation
• Simplify project's own CI workflows to demonstrate feature

---

📝 Feedback Requested

1. Which options do you prefer for the design questions above?
2. Are there additional environment variables that should be tracked?
3. Should this feature be opt-in or opt-out by default?
4. Any security concerns with the proposed approach?

Happy to refine the design based on feedback before implementation!