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

atdd/coach/commands/inventory.py

@@ -75,11 +75,32 @@ class RepositoryInventory:
         }
 
     def scan_trains(self) -> Dict[str, Any]:
-        """Scan plan/ for train manifests (aggregations of wagons)."""
+        """
+        Scan plan/ for train manifests (aggregations of wagons).
+
+        Train First-Class Spec v0.6 Section 14: Gap Reporting
+        Reports missing test/code for each platform (backend/frontend/frontend_python).
+        """
         plan_dir = self.repo_root / "plan"
 
         if not plan_dir.exists():
-            return {"total": 0, "trains": []}
+            return {
+                "total": 0,
+                "trains": [],
+                "by_theme": {},
+                "train_ids": [],
+                "detail_files": 0,
+                "missing_test_backend": [],
+                "missing_test_frontend": [],
+                "missing_test_frontend_python": [],
+                "missing_code_backend": [],
+                "missing_code_frontend": [],
+                "missing_code_frontend_python": [],
+                "gaps": {
+                    "test": {"backend": 0, "frontend": 0, "frontend_python": 0},
+                    "code": {"backend": 0, "frontend": 0, "frontend_python": 0}
+                }
+            }
 
         # Load trains registry
         trains_file = plan_dir / "_trains.yaml"
@@ -103,6 +124,14 @@ class RepositoryInventory:
         by_theme = defaultdict(int)
         train_ids = []
 
+        # Gap tracking (Section 14)
+        missing_test_backend = []
+        missing_test_frontend = []
+        missing_test_frontend_python = []
+        missing_code_backend = []
+        missing_code_frontend = []
+        missing_code_frontend_python = []
+
         for train in all_trains:
             train_id = train.get("train_id", "unknown")
             train_ids.append(train_id)
@@ -118,6 +147,46 @@ class RepositoryInventory:
                 theme = theme_map.get(theme_digit, "unknown")
                 by_theme[theme] += 1
 
+            # Gap analysis
+            expectations = train.get("expectations", {})
+            test_fields = train.get("test", {})
+            code_fields = train.get("code", {})
+
+            # Normalize test/code to dict form
+            if isinstance(test_fields, str):
+                test_fields = {"backend": [test_fields]}
+            elif isinstance(test_fields, list):
+                test_fields = {"backend": test_fields}
+
+            if isinstance(code_fields, str):
+                code_fields = {"backend": [code_fields]}
+            elif isinstance(code_fields, list):
+                code_fields = {"backend": code_fields}
+
+            # Check backend gaps (default expectation is True for backend)
+            expects_backend = expectations.get("backend", True)
+            if expects_backend:
+                if not test_fields.get("backend"):
+                    missing_test_backend.append(train_id)
+                if not code_fields.get("backend"):
+                    missing_code_backend.append(train_id)
+
+            # Check frontend gaps
+            expects_frontend = expectations.get("frontend", False)
+            if expects_frontend:
+                if not test_fields.get("frontend"):
+                    missing_test_frontend.append(train_id)
+                if not code_fields.get("frontend"):
+                    missing_code_frontend.append(train_id)
+
+            # Check frontend_python gaps
+            expects_frontend_python = expectations.get("frontend_python", False)
+            if expects_frontend_python:
+                if not test_fields.get("frontend_python"):
+                    missing_test_frontend_python.append(train_id)
+                if not code_fields.get("frontend_python"):
+                    missing_code_frontend_python.append(train_id)
+
         # Find train detail files
         train_detail_files = list((plan_dir / "_trains").glob("*.yaml")) if (plan_dir / "_trains").exists() else []
 
@@ -125,7 +194,26 @@ class RepositoryInventory:
             "total": len(all_trains),
             "by_theme": dict(by_theme),
             "train_ids": train_ids,
-            "detail_files": len(train_detail_files)
+            "detail_files": len(train_detail_files),
+            # Gap reporting (Section 14)
+            "missing_test_backend": missing_test_backend,
+            "missing_test_frontend": missing_test_frontend,
+            "missing_test_frontend_python": missing_test_frontend_python,
+            "missing_code_backend": missing_code_backend,
+            "missing_code_frontend": missing_code_frontend,
+            "missing_code_frontend_python": missing_code_frontend_python,
+            "gaps": {
+                "test": {
+                    "backend": len(missing_test_backend),
+                    "frontend": len(missing_test_frontend),
+                    "frontend_python": len(missing_test_frontend_python)
+                },
+                "code": {
+                    "backend": len(missing_code_backend),
+                    "frontend": len(missing_code_frontend),
+                    "frontend_python": len(missing_code_frontend_python)
+                }
+            }
         }
 
     def scan_wagons(self) -> Dict[str, Any]:

atdd/coach/commands/registry.py

@@ -910,6 +910,44 @@ class RegistryBuilder:
             mode = "check" if preview_only else "interactive"
         return self.update_telemetry_registry(mode)
 
+    def _normalize_test_code_field(self, field_value: Any) -> Dict[str, List[str]]:
+        """
+        Normalize test/code field to canonical structure.
+
+        Train First-Class Spec v0.6 Section 5: Test/Code Field Typing Normalization
+        - string -> {"backend": [string]}
+        - list -> {"backend": list}
+        - dict -> normalize each sub-field to list
+        """
+        if field_value is None:
+            return {}
+
+        if isinstance(field_value, str):
+            return {"backend": [field_value]}
+        elif isinstance(field_value, list):
+            return {"backend": field_value}
+        elif isinstance(field_value, dict):
+            result = {}
+            for key in ["backend", "frontend", "frontend_python"]:
+                if key in field_value:
+                    val = field_value[key]
+                    result[key] = [val] if isinstance(val, str) else (val or [])
+            return result
+        return {}
+
+    def _extract_wagons_from_participants(self, participants: List[str]) -> List[str]:
+        """
+        Extract wagon names from participants list.
+
+        Train First-Class Spec v0.6 Section 4: Participants is Canonical Wagon Source
+        """
+        wagons = []
+        for participant in participants:
+            if isinstance(participant, str) and participant.startswith("wagon:"):
+                wagon_name = participant.replace("wagon:", "")
+                wagons.append(wagon_name)
+        return wagons
+
     def build_trains(self, mode: str = "interactive") -> Dict[str, Any]:
         """
         Build trains registry from train manifest files.
@@ -920,12 +958,19 @@ class RegistryBuilder:
         - XX = category within theme
         - name = train slug
 
+        Train First-Class Spec v0.6 Normalization:
+        - Section 1: Normalize file→path (deprecation)
+        - Section 4: Extract wagons from participants
+        - Section 5: Normalize test/code fields to {backend/frontend/frontend_python: []}
+
         Args:
             mode: "interactive" (prompt), "apply" (no prompt), or "check" (verify only)
 
         Returns:
             Statistics about the update (includes has_changes flag for check mode)
         """
+        import warnings
+
         print("\n📊 Analyzing trains registry from manifest files...")
 
         # Set up paths
@@ -947,6 +992,7 @@ class RegistryBuilder:
             "new": 0,
             "errors": 0,
             "preserved_drafts": 0,
+            "file_to_path_migrations": 0,
             "changes": []
         }
 
@@ -987,31 +1033,92 @@ class RegistryBuilder:
                     # Try to infer from filename (e.g., 01-01-setup.yaml -> 01-01-setup)
                     train_id = manifest_path.stem
 
-                # Parse theme from train_id (first 2 digits)
+                # Parse theme from train_id (first digit maps to theme name)
                 theme = ""
-                if len(train_id) >= 2 and train_id[:2].isdigit():
-                    theme = train_id[:2]
+                theme_map = {
+                    "0": "commons", "1": "mechanic", "2": "scenario", "3": "match",
+                    "4": "sensory", "5": "player", "6": "league", "7": "audience",
+                    "8": "monetization", "9": "partnership"
+                }
+                if train_id and train_id[0].isdigit():
+                    theme = theme_map.get(train_id[0], "")
 
                 # Build train entry
                 rel_manifest = str(manifest_path.relative_to(self.repo_root))
 
+                # Section 1: Normalize file→path
+                path_value = manifest.get("path")
+                file_value = manifest.get("file")
+                if file_value and not path_value:
+                    # Migrate file to path
+                    path_value = file_value
+                    stats["file_to_path_migrations"] += 1
+                    warnings.warn(
+                        f"Train {train_id}: 'file' field is deprecated, migrating to 'path'",
+                        DeprecationWarning,
+                        stacklevel=2
+                    )
+
+                # Section 4: Extract wagons from participants
+                participants = manifest.get("participants", [])
+                wagons = self._extract_wagons_from_participants(participants)
+
+                # Also include explicitly listed wagons
+                explicit_wagons = manifest.get("wagons", [])
+                if explicit_wagons:
+                    # Validate subset relationship
+                    explicit_set = set(explicit_wagons)
+                    participant_set = set(wagons)
+                    if not explicit_set.issubset(participant_set) and participant_set:
+                        extra = explicit_set - participant_set
+                        warnings.warn(
+                            f"Train {train_id}: registry wagons {extra} not in YAML participants",
+                            UserWarning,
+                            stacklevel=2
+                        )
+                    wagons = explicit_wagons  # Use explicit if provided
+
+                # Section 5: Normalize test/code fields
+                test_normalized = self._normalize_test_code_field(manifest.get("test"))
+                code_normalized = self._normalize_test_code_field(manifest.get("code"))
+
                 entry = {
                     "train_id": train_id,
                     "theme": theme,
                     "title": manifest.get("title", manifest.get("description", "")),
                     "description": manifest.get("description", ""),
-                    "wagons": manifest.get("wagons", []),
+                    "wagons": wagons,
                     "status": manifest.get("status", "planned"),
                     "manifest": rel_manifest
                 }
 
+                # Add path if present
+                if path_value:
+                    entry["path"] = path_value
+
+                # Add primary_wagon if present
+                primary_wagon = manifest.get("primary_wagon")
+                if primary_wagon:
+                    entry["primary_wagon"] = primary_wagon
+
+                # Add normalized test/code if present
+                if test_normalized:
+                    entry["test"] = test_normalized
+                if code_normalized:
+                    entry["code"] = code_normalized
+
+                # Add expectations if present
+                expectations = manifest.get("expectations")
+                if expectations:
+                    entry["expectations"] = expectations
+
                 # Check if updating or new
                 if train_id in existing_trains:
                     stats["updated"] += 1
                     # Check for field changes
                     old = existing_trains[train_id]
                     changed_fields = []
-                    for field in ["title", "description", "wagons", "status", "theme"]:
+                    for field in ["title", "description", "wagons", "status", "theme", "path", "test", "code", "expectations"]:
                         if old.get(field) != entry.get(field):
                             changed_fields.append(field)
                     if changed_fields:
@@ -1052,6 +1159,8 @@ class RegistryBuilder:
         print(f"  • {stats['updated']} trains will be updated")
         print(f"  • {stats['new']} new trains will be added")
         print(f"  • {stats['preserved_drafts']} draft trains will be preserved")
+        if stats["file_to_path_migrations"] > 0:
+            print(f"  ⚠️  {stats['file_to_path_migrations']} file→path migrations (deprecation)")
         if stats["errors"] > 0:
             print(f"  ⚠️  {stats['errors']} errors encountered")
 

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]:
     """