traceforge-toolkit 0.1.0__py3-none-any.whl

traceforge/config/loader.py

@@ -0,0 +1,239 @@
+"""Config loading with hierarchical precedence.
+
+Precedence (highest → lowest):
+  1. Explicit kwargs passed to load_config()
+  2. TRACEFORGE_* environment variables
+  3. TRACEFORGE_CONFIG env var (explicit path override)
+  4. Project-local: ./traceforge.yaml
+  5. User-global: ~/.traceforge/config.yaml
+  6. Built-in defaults
+
+On first config access, ~/.traceforge/ is auto-created with a default config
+if it does not already exist. This is the post-install bootstrap — no separate
+init command needed.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from traceforge.config.defaults import DEFAULT_CONFIG_YAML
+from traceforge.config.models import TraceforgeConfig
+
+logger = logging.getLogger(__name__)
+
+# Module-level singleton (lazily loaded)
+_config: TraceforgeConfig | None = None
+_bootstrapped: bool = False
+
+# Well-known paths
+_USER_CONFIG_DIR = Path.home() / ".traceforge"
+_USER_MAPPINGS_DIR = _USER_CONFIG_DIR / "mappings"
+_USER_CONFIG_FILE = _USER_CONFIG_DIR / "config.yaml"
+_PROJECT_CONFIG_FILE = Path("traceforge.yaml")
+
+
+def _ensure_user_dir() -> None:
+    """Create ~/.traceforge/ with default config if it doesn't exist.
+
+    Called once on first config access. Idempotent — safe to call multiple times.
+    This is the post-install bootstrap: no separate `traceforge init` needed.
+    """
+    global _bootstrapped
+    if _bootstrapped:
+        return
+    _bootstrapped = True
+
+    try:
+        _USER_CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+        _USER_MAPPINGS_DIR.mkdir(parents=True, exist_ok=True)
+
+        if not _USER_CONFIG_FILE.exists():
+            _USER_CONFIG_FILE.write_text(DEFAULT_CONFIG_YAML, encoding="utf-8")
+            logger.info("Created default config at %s", _USER_CONFIG_FILE)
+    except OSError as exc:
+        # Non-fatal: read-only filesystem, containerized env, etc.
+        logger.debug("Could not create ~/.traceforge/: %s", exc)
+
+
+def _find_config_files() -> list[Path]:
+    """Discover config files in precedence order (first = highest priority).
+
+    Returns paths that exist on disk. Higher-priority files override lower.
+    """
+    files: list[Path] = []
+
+    # Explicit override via env var
+    env_path = os.environ.get("TRACEFORGE_CONFIG")
+    if env_path:
+        p = Path(env_path).expanduser().resolve()
+        if p.is_file():
+            files.append(p)
+            return files  # explicit override skips discovery
+        else:
+            logger.warning("TRACEFORGE_CONFIG=%s does not exist, falling back to discovery", p)
+
+    # Project-local
+    project_file = _PROJECT_CONFIG_FILE.resolve()
+    if project_file.is_file():
+        files.append(project_file)
+
+    # User-global
+    if _USER_CONFIG_FILE.is_file():
+        files.append(_USER_CONFIG_FILE)
+
+    return files
+
+
+def _load_yaml_file(path: Path) -> dict[str, Any]:
+    """Load a YAML file, returning empty dict on parse errors."""
+    try:
+        with open(path) as f:
+            data = yaml.safe_load(f)
+        return data if isinstance(data, dict) else {}
+    except Exception as exc:
+        logger.warning("Failed to load config from %s: %s", path, exc)
+        return {}
+
+
+def _merge_dicts(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
+    """Deep-merge override into base. Lists are replaced, not appended."""
+    merged = base.copy()
+    for key, value in override.items():
+        if key in merged and isinstance(merged[key], dict) and isinstance(value, dict):
+            merged[key] = _merge_dicts(merged[key], value)
+        else:
+            merged[key] = value
+    return merged
+
+
+def _apply_env_overrides(data: dict[str, Any]) -> dict[str, Any]:
+    """Apply TRACEFORGE_* environment variables as scalar overrides.
+
+    Supports flat keys only: TRACEFORGE_LOG_LEVEL → log_level.
+    Nested keys use double-underscore: TRACEFORGE_SDK__BATCH_SIZE → sdk.batch_size.
+    """
+    prefix = "TRACEFORGE_"
+    skip = {"TRACEFORGE_CONFIG"}  # meta env var, not a config field
+
+    for key, value in os.environ.items():
+        if not key.startswith(prefix) or key in skip:
+            continue
+
+        # Convert TRACEFORGE_SDK__BATCH_SIZE → ["sdk", "batch_size"]
+        parts = key[len(prefix) :].lower().split("__")
+
+        # Navigate to the right nesting level
+        target = data
+        for part in parts[:-1]:
+            if part not in target or not isinstance(target[part], dict):
+                target[part] = {}
+            target = target[part]
+
+        # Set the leaf value (attempt int/float coercion for numeric fields)
+        leaf = parts[-1]
+        target[leaf] = _coerce_env_value(value)
+
+    return data
+
+
+def _coerce_env_value(value: str) -> str | int | float | bool:
+    """Best-effort coercion of env var string to Python scalar."""
+    if value.lower() in ("true", "1", "yes"):
+        return True
+    if value.lower() in ("false", "0", "no"):
+        return False
+    try:
+        return int(value)
+    except ValueError:
+        pass
+    try:
+        return float(value)
+    except ValueError:
+        pass
+    return value
+
+
+def load_config(**overrides: Any) -> TraceforgeConfig:
+    """Load traceforge configuration with full precedence chain.
+
+    On first call, ensures ~/.traceforge/ exists with a default config.
+
+    Args:
+        **overrides: Explicit field values (highest precedence).
+
+    Returns:
+        Fully validated TraceforgeConfig instance.
+    """
+    global _config
+
+    # Bootstrap user directory (idempotent, once per process)
+    _ensure_user_dir()
+
+    # Start with defaults (empty dict — Pydantic fills defaults)
+    merged: dict[str, Any] = {}
+
+    # Layer config files (lowest priority first)
+    config_files = _find_config_files()
+    for path in reversed(config_files):  # reversed so highest-priority applied last
+        file_data = _load_yaml_file(path)
+        merged = _merge_dicts(merged, file_data)
+        logger.debug("Loaded config from %s", path)
+
+    # Layer env vars
+    merged = _apply_env_overrides(merged)
+
+    # Layer explicit overrides
+    if overrides:
+        merged = _merge_dicts(merged, overrides)
+
+    # Validate and construct
+    _config = TraceforgeConfig.model_validate(merged)
+    return _config
+
+
+def load_config_from_path(path: Any = None) -> TraceforgeConfig:
+    """Resolve a full ``TraceforgeConfig``, optionally forcing a specific file.
+
+    When ``path`` is given it becomes the sole config source (applied via the
+    ``TRACEFORGE_CONFIG`` override, then restored); when ``None`` the standard
+    discovery chain runs (``TRACEFORGE_CONFIG`` env, ``./traceforge.yaml``,
+    ``~/.traceforge/config.yaml``).
+
+    This is the single ``path -> config`` resolution shared by the SDK
+    (:meth:`traceforge.sdk.Pipeline.from_config`) and governance
+    (:meth:`traceforge.governance.pipeline.GovernancePipeline.from_config`)
+    entry points, so both hydrate from the same resolved config.
+    """
+    if path is None:
+        return load_config()
+
+    old_env = os.environ.get("TRACEFORGE_CONFIG")
+    os.environ["TRACEFORGE_CONFIG"] = str(path)
+    try:
+        return load_config()
+    finally:
+        if old_env is None:
+            os.environ.pop("TRACEFORGE_CONFIG", None)
+        else:
+            os.environ["TRACEFORGE_CONFIG"] = old_env
+
+
+def get_config() -> TraceforgeConfig:
+    """Get the current config singleton, loading defaults if needed."""
+    global _config
+    if _config is None:
+        _config = load_config()
+    return _config
+
+
+def reset_config() -> None:
+    """Reset the config singleton (for testing)."""
+    global _config, _bootstrapped
+    _config = None
+    _bootstrapped = False

traceforge/config/mappings.py

@@ -0,0 +1,104 @@
+"""Mapping resolver — finds YAML framework mappings across all search paths.
+
+Search order:
+  1. User mappings dirs (from config.mappings_dirs) — allows overrides
+  2. ~/.traceforge/mappings/ (default user dir)
+  3. Bundled mappings (src/traceforge/mappings/) — shipped with package
+
+First match wins. User mappings override bundled ones with the same name.
+"""
+
+from __future__ import annotations
+
+import importlib.resources
+import logging
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+# Bundled mappings location (inside the installed package)
+_BUNDLED_MAPPINGS_DIR: Path | None = None
+
+
+def _get_bundled_dir() -> Path:
+    """Resolve the bundled mappings directory from the installed package."""
+    global _BUNDLED_MAPPINGS_DIR
+    if _BUNDLED_MAPPINGS_DIR is None:
+        ref = importlib.resources.files("traceforge") / "mappings"
+        # Traversable → Path (works for both installed and editable installs)
+        _BUNDLED_MAPPINGS_DIR = Path(str(ref))
+    return _BUNDLED_MAPPINGS_DIR
+
+
+def resolve_mapping_path(name: str, extra_dirs: list[Path] | None = None) -> Path | None:
+    """Find a YAML mapping file by framework name.
+
+    Args:
+        name: Framework name (e.g. "copilot", "claude"). Resolved as {name}.yaml.
+        extra_dirs: Additional directories to search (from config.mappings_dirs).
+
+    Returns:
+        Path to the YAML file, or None if not found.
+    """
+    filename = f"{name}.yaml"
+    search_dirs: list[Path] = []
+
+    # User-specified dirs (highest priority)
+    if extra_dirs:
+        for d in extra_dirs:
+            resolved = Path(d).expanduser().resolve()
+            if resolved.is_dir():
+                search_dirs.append(resolved)
+
+    # Default user mappings dir
+    user_mappings = Path.home() / ".traceforge" / "mappings"
+    if user_mappings.is_dir() and user_mappings not in search_dirs:
+        search_dirs.append(user_mappings)
+
+    # Bundled mappings (lowest priority)
+    bundled = _get_bundled_dir()
+    if bundled.is_dir():
+        search_dirs.append(bundled)
+
+    # First match wins
+    for directory in search_dirs:
+        candidate = directory / filename
+        if candidate.is_file():
+            return candidate
+
+    return None
+
+
+def list_available_mappings(extra_dirs: list[Path] | None = None) -> dict[str, Path]:
+    """List all available mapping names and their resolved paths.
+
+    Later entries do not override earlier ones (first-found wins).
+
+    Returns:
+        Dict of framework_name → path.
+    """
+    mappings: dict[str, Path] = {}
+    search_dirs: list[Path] = []
+
+    # Build search order (same as resolve_mapping_path)
+    if extra_dirs:
+        for d in extra_dirs:
+            resolved = Path(d).expanduser().resolve()
+            if resolved.is_dir():
+                search_dirs.append(resolved)
+
+    user_mappings = Path.home() / ".traceforge" / "mappings"
+    if user_mappings.is_dir() and user_mappings not in search_dirs:
+        search_dirs.append(user_mappings)
+
+    bundled = _get_bundled_dir()
+    if bundled.is_dir():
+        search_dirs.append(bundled)
+
+    for directory in search_dirs:
+        for yaml_file in sorted(directory.glob("*.yaml")):
+            name = yaml_file.stem
+            if name not in mappings:  # first-found wins (user overrides bundled)
+                mappings[name] = yaml_file
+
+    return mappings