atdd 0.4.5__py3-none-any.whl → 0.4.7__py3-none-any.whl

atdd/coach/utils/config.py

@@ -0,0 +1,131 @@
+"""
+ATDD Configuration Loader.
+
+Loads configuration from .atdd/config.yaml for train validation and enforcement.
+"""
+
+import yaml
+from pathlib import Path
+from typing import Dict, Any, Optional
+
+
+def load_atdd_config(repo_root: Path) -> Dict[str, Any]:
+    """
+    Load .atdd/config.yaml configuration file.
+
+    The config file controls:
+    - FastAPI template enforcement (Section 11)
+    - Train validation behavior
+    - Custom path conventions
+
+    Args:
+        repo_root: Repository root path
+
+    Returns:
+        Parsed configuration dict, or empty dict if file doesn't exist
+
+    Example config:
+        trains:
+          enforce_fastapi_template: true
+          backend_runner_paths:
+            - python/trains/runner.py
+            - python/trains/{train_id}/runner.py
+          frontend_allowed_roots:
+            - web/src/
+            - web/components/
+    """
+    config_path = repo_root / ".atdd" / "config.yaml"
+
+    if not config_path.exists():
+        return {}
+
+    try:
+        with open(config_path) as f:
+            config = yaml.safe_load(f)
+            return config if config else {}
+    except Exception:
+        return {}
+
+
+def get_train_config(repo_root: Path) -> Dict[str, Any]:
+    """
+    Get train-specific configuration.
+
+    Args:
+        repo_root: Repository root path
+
+    Returns:
+        Train configuration dict with defaults applied
+    """
+    config = load_atdd_config(repo_root)
+    train_config = config.get("trains", {})
+
+    # Apply defaults
+    defaults = {
+        "enforce_fastapi_template": False,
+        "backend_runner_paths": [
+            "python/trains/runner.py",
+            "python/trains/{train_id}/runner.py"
+        ],
+        "frontend_allowed_roots": [
+            "web/src/",
+            "web/components/",
+            "web/pages/"
+        ],
+        "frontend_python_paths": [
+            "python/streamlit/",
+            "python/apps/"
+        ],
+        "e2e_backend_pattern": "e2e/{theme}/test_{train_id}*.py",
+        "e2e_frontend_pattern": "web/e2e/{train_id}/*.spec.ts"
+    }
+
+    # Merge with defaults
+    for key, default_value in defaults.items():
+        if key not in train_config:
+            train_config[key] = default_value
+
+    return train_config
+
+
+def get_validation_config(repo_root: Path) -> Dict[str, Any]:
+    """
+    Get validation-specific configuration.
+
+    Args:
+        repo_root: Repository root path
+
+    Returns:
+        Validation configuration with defaults
+    """
+    config = load_atdd_config(repo_root)
+    validation_config = config.get("validation", {})
+
+    defaults = {
+        "strict_mode": False,
+        "warn_on_missing_tests": True,
+        "warn_on_missing_code": True,
+        "require_primary_wagon": False
+    }
+
+    for key, default_value in defaults.items():
+        if key not in validation_config:
+            validation_config[key] = default_value
+
+    return validation_config
+
+
+def is_feature_enabled(repo_root: Path, feature: str) -> bool:
+    """
+    Check if a specific feature is enabled in config.
+
+    Args:
+        repo_root: Repository root path
+        feature: Feature name to check
+
+    Returns:
+        True if feature is enabled, False otherwise
+    """
+    config = load_atdd_config(repo_root)
+    features = config.get("features", {})
+    return features.get(feature, False)

atdd/coach/utils/train_spec_phase.py

@@ -0,0 +1,97 @@
+"""
+Train First-Class Spec v0.6 Rollout Phase Controller.
+
+Manages the phased rollout of train validation rules:
+- Phase 1 (WARNINGS_ONLY): All new validators emit warnings only
+- Phase 2 (BACKEND_ENFORCEMENT): Backend validators become strict
+- Phase 3 (FULL_ENFORCEMENT): All validators become strict
+
+Usage in validators:
+    from atdd.coach.utils.train_spec_phase import TrainSpecPhase, should_enforce
+
+    if should_enforce(TrainSpecPhase.BACKEND_ENFORCEMENT):
+        assert condition, "Error message"
+    else:
+        if not condition:
+            warnings.warn("Warning message")
+"""
+
+from enum import IntEnum
+from typing import Optional
+import warnings
+
+
+class TrainSpecPhase(IntEnum):
+    """
+    Rollout phases for Train First-Class Spec v0.6.
+
+    Phases are ordered by strictness level:
+    - WARNINGS_ONLY (1): All new validators emit warnings, no assertions
+    - BACKEND_ENFORCEMENT (2): Backend validators (0022-0025, 0031-0033) strict
+    - FULL_ENFORCEMENT (3): All validators strict
+    """
+    WARNINGS_ONLY = 1
+    BACKEND_ENFORCEMENT = 2
+    FULL_ENFORCEMENT = 3
+
+
+# Current rollout phase - update this to advance through phases
+CURRENT_PHASE = TrainSpecPhase.WARNINGS_ONLY
+
+
+def should_enforce(validator_phase: TrainSpecPhase) -> bool:
+    """
+    Check if a validator should enforce strict mode.
+
+    Args:
+        validator_phase: The phase at which this validator becomes strict
+
+    Returns:
+        True if current phase >= validator_phase (should enforce)
+        False if current phase < validator_phase (should warn only)
+
+    Example:
+        # This validator becomes strict in Phase 2
+        if should_enforce(TrainSpecPhase.BACKEND_ENFORCEMENT):
+            assert backend_test_exists, "Backend test required"
+        else:
+            if not backend_test_exists:
+                warnings.warn("Backend test missing (warning only)")
+    """
+    return CURRENT_PHASE >= validator_phase
+
+
+def get_current_phase() -> TrainSpecPhase:
+    """Get the current rollout phase."""
+    return CURRENT_PHASE
+
+
+def get_phase_name(phase: Optional[TrainSpecPhase] = None) -> str:
+    """Get human-readable name for a phase."""
+    phase = phase or CURRENT_PHASE
+    return {
+        TrainSpecPhase.WARNINGS_ONLY: "Phase 1: Warnings Only",
+        TrainSpecPhase.BACKEND_ENFORCEMENT: "Phase 2: Backend Enforcement",
+        TrainSpecPhase.FULL_ENFORCEMENT: "Phase 3: Full Enforcement",
+    }.get(phase, "Unknown Phase")
+
+
+def emit_phase_warning(
+    spec_id: str,
+    message: str,
+    validator_phase: TrainSpecPhase = TrainSpecPhase.BACKEND_ENFORCEMENT
+) -> None:
+    """
+    Emit a deprecation/validation warning with phase context.
+
+    Args:
+        spec_id: The SPEC ID (e.g., "SPEC-TRAIN-VAL-0022")
+        message: The warning message
+        validator_phase: Phase when this becomes an error
+    """
+    phase_name = get_phase_name(validator_phase)
+    warnings.warn(
+        f"[{spec_id}] {message} (will become error in {phase_name})",
+        category=UserWarning,
+        stacklevel=3
+    )

atdd/coach/validators/shared_fixtures.py

@@ -14,11 +14,12 @@ Validators should use:
 import json
 import yaml
 from pathlib import Path
-from typing import Dict, Any, List, Tuple
+from typing import Dict, Any, List, Tuple, Optional
 import pytest
 
 import atdd
 from atdd.coach.utils.repo import find_repo_root
+from atdd.coach.utils.config import load_atdd_config, get_train_config
 
 
 # Path constants
@@ -192,6 +193,72 @@ def trains_registry() -> Dict[str, Any]:
     }
 
 
+@pytest.fixture(scope="module")
+def trains_registry_with_groups() -> Dict[str, Dict[str, List[Dict]]]:
+    """
+    Load trains registry preserving full group structure for theme validation.
+
+    Returns:
+        Trains data with full nesting preserved:
+        {"0-commons": {"00-commons-nominal": [train1, train2], ...}, ...}
+
+    This fixture is used for validating theme derivation from group keys.
+    """
+    trains_file = PLAN_DIR / "_trains.yaml"
+    if trains_file.exists():
+        with open(trains_file) as f:
+            data = yaml.safe_load(f)
+            return data.get("trains", {})
+    return {}
+
+
+@pytest.fixture(scope="module")
+def train_files() -> List[Tuple[Path, Dict]]:
+    """
+    Load all train YAML files with their data.
+
+    Returns:
+        List of (path, train_data) tuples for all train files in plan/_trains/
+    """
+    trains_dir = PLAN_DIR / "_trains"
+    train_files_data = []
+
+    if trains_dir.exists():
+        for train_file in sorted(trains_dir.glob("*.yaml")):
+            if not train_file.name.startswith("_"):
+                try:
+                    with open(train_file) as f:
+                        train_data = yaml.safe_load(f)
+                        if train_data:
+                            train_files_data.append((train_file, train_data))
+                except Exception:
+                    pass
+
+    return train_files_data
+
+
+@pytest.fixture(scope="module")
+def atdd_config() -> Dict[str, Any]:
+    """
+    Load .atdd/config.yaml configuration.
+
+    Returns:
+        Configuration dict with train and validation settings
+    """
+    return load_atdd_config(REPO_ROOT)
+
+
+@pytest.fixture(scope="module")
+def train_config() -> Dict[str, Any]:
+    """
+    Load train-specific configuration with defaults.
+
+    Returns:
+        Train configuration dict with defaults applied
+    """
+    return get_train_config(REPO_ROOT)
+
+
 @pytest.fixture(scope="module")
 def wagons_registry() -> Dict[str, Any]:
     """

atdd/coach/validators/test_train_registry.py

@@ -0,0 +1,189 @@
+"""
+Coach validators: Train registry gap validation.
+
+Train First-Class Spec v0.6 Section 14: Inventory Reporting
+
+Validates:
+- SPEC-TRAIN-VAL-0037: Inventory reports train gaps
+- SPEC-TRAIN-VAL-0038: Gap report format validation
+
+Ensures the inventory command properly reports gaps in train implementation
+across backend, frontend, and frontend_python platforms.
+"""
+
+import pytest
+from pathlib import Path
+from typing import Dict, Any, List
+
+from atdd.coach.utils.repo import find_repo_root
+from atdd.coach.commands.inventory import RepositoryInventory
+from atdd.coach.utils.train_spec_phase import (
+    TrainSpecPhase,
+    should_enforce,
+    emit_phase_warning
+)
+
+
+# Path constants
+REPO_ROOT = find_repo_root()
+
+
+@pytest.fixture(scope="module")
+def train_inventory() -> Dict[str, Any]:
+    """Generate train inventory with gap reporting."""
+    inventory = RepositoryInventory(REPO_ROOT)
+    return inventory.scan_trains()
+
+
+@pytest.mark.platform
+def test_inventory_reports_train_gaps(train_inventory):
+    """
+    SPEC-TRAIN-VAL-0037: Inventory reports train gaps
+
+    Given: Inventory scan of trains
+    When: Checking gap reporting fields
+    Then: Inventory includes missing_test_* and missing_code_* arrays
+
+    Section 14: Gap Reporting
+    """
+    required_gap_fields = [
+        "missing_test_backend",
+        "missing_test_frontend",
+        "missing_test_frontend_python",
+        "missing_code_backend",
+        "missing_code_frontend",
+        "missing_code_frontend_python"
+    ]
+
+    missing_fields = []
+    for field in required_gap_fields:
+        if field not in train_inventory:
+            missing_fields.append(field)
+
+    if missing_fields:
+        pytest.fail(
+            f"Inventory missing gap reporting fields:\n  " +
+            "\n  ".join(missing_fields) +
+            "\n\nExpected fields for Train First-Class Spec v0.6 Section 14"
+        )
+
+    # Verify all gap fields are lists
+    for field in required_gap_fields:
+        value = train_inventory.get(field)
+        assert isinstance(value, list), \
+            f"Gap field '{field}' should be a list, got {type(value).__name__}"
+
+
+@pytest.mark.platform
+def test_gap_report_format_validation(train_inventory):
+    """
+    SPEC-TRAIN-VAL-0038: Gap report format validation
+
+    Given: Inventory with gap reporting
+    When: Checking gap report structure
+    Then: Gaps summary exists with correct format
+
+    Section 14: Gap Report Format
+    """
+    # Check for gaps summary
+    assert "gaps" in train_inventory, \
+        "Inventory should include 'gaps' summary object"
+
+    gaps = train_inventory["gaps"]
+
+    # Validate structure
+    assert isinstance(gaps, dict), \
+        "gaps should be a dictionary"
+
+    assert "test" in gaps, \
+        "gaps should include 'test' category"
+
+    assert "code" in gaps, \
+        "gaps should include 'code' category"
+
+    # Validate test gaps structure
+    test_gaps = gaps["test"]
+    assert isinstance(test_gaps, dict), \
+        "gaps.test should be a dictionary"
+
+    required_platforms = ["backend", "frontend", "frontend_python"]
+    for platform in required_platforms:
+        assert platform in test_gaps, \
+            f"gaps.test should include '{platform}'"
+        assert isinstance(test_gaps[platform], int), \
+            f"gaps.test.{platform} should be an integer count"
+
+    # Validate code gaps structure
+    code_gaps = gaps["code"]
+    assert isinstance(code_gaps, dict), \
+        "gaps.code should be a dictionary"
+
+    for platform in required_platforms:
+        assert platform in code_gaps, \
+            f"gaps.code should include '{platform}'"
+        assert isinstance(code_gaps[platform], int), \
+            f"gaps.code.{platform} should be an integer count"
+
+
+@pytest.mark.platform
+def test_gap_counts_match_arrays(train_inventory):
+    """
+    Verify gap counts match corresponding array lengths.
+
+    Given: Inventory with gap reporting
+    When: Comparing counts to arrays
+    Then: Counts equal array lengths
+    """
+    gaps = train_inventory.get("gaps", {})
+
+    # Test gaps
+    test_gaps = gaps.get("test", {})
+    assert test_gaps.get("backend", 0) == len(train_inventory.get("missing_test_backend", [])), \
+        "gaps.test.backend count mismatch"
+    assert test_gaps.get("frontend", 0) == len(train_inventory.get("missing_test_frontend", [])), \
+        "gaps.test.frontend count mismatch"
+    assert test_gaps.get("frontend_python", 0) == len(train_inventory.get("missing_test_frontend_python", [])), \
+        "gaps.test.frontend_python count mismatch"
+
+    # Code gaps
+    code_gaps = gaps.get("code", {})
+    assert code_gaps.get("backend", 0) == len(train_inventory.get("missing_code_backend", [])), \
+        "gaps.code.backend count mismatch"
+    assert code_gaps.get("frontend", 0) == len(train_inventory.get("missing_code_frontend", [])), \
+        "gaps.code.frontend count mismatch"
+    assert code_gaps.get("frontend_python", 0) == len(train_inventory.get("missing_code_frontend_python", [])), \
+        "gaps.code.frontend_python count mismatch"
+
+
+@pytest.mark.platform
+def test_gap_train_ids_are_valid(train_inventory):
+    """
+    Verify train IDs in gap arrays are valid.
+
+    Given: Inventory with gap arrays
+    When: Checking train IDs
+    Then: All train IDs in gaps are in train_ids list
+    """
+    all_train_ids = set(train_inventory.get("train_ids", []))
+
+    if not all_train_ids:
+        pytest.skip("No trains found in inventory")
+
+    gap_fields = [
+        "missing_test_backend",
+        "missing_test_frontend",
+        "missing_test_frontend_python",
+        "missing_code_backend",
+        "missing_code_frontend",
+        "missing_code_frontend_python"
+    ]
+
+    invalid_ids = []
+    for field in gap_fields:
+        gap_ids = train_inventory.get(field, [])
+        for train_id in gap_ids:
+            if train_id not in all_train_ids:
+                invalid_ids.append(f"{field}: {train_id}")
+
+    assert not invalid_ids, \
+        f"Gap arrays contain invalid train IDs:\n  " + "\n  ".join(invalid_ids)