atdd 0.6.0__py3-none-any.whl → 0.7.0__py3-none-any.whl

atdd/coach/schemas/config.schema.json

@@ -121,6 +121,17 @@
         }
       },
       "additionalProperties": false
+    },
+    "localization": {
+      "type": "object",
+      "description": "Localization validation settings (Localization Manifest Spec v1)",
+      "properties": {
+        "manifest": {
+          "type": "string",
+          "description": "Path to localization manifest.json relative to repo root (e.g., web/locales/manifest.json)"
+        }
+      },
+      "additionalProperties": false
     }
   },
   "required": ["version", "release"],

atdd/coach/templates/ATDD.md

@@ -71,7 +71,7 @@ code:
 # Dev Servers
 dev_servers:
   backend:
-    command: "cd python && python3 game.py"
+    command: "cd python && python3 app.py"
     url: "http://127.0.0.1:8000"
     swagger: "http://127.0.0.1:8000/docs"
   frontend:

atdd/coach/utils/locale_phase.py

@@ -0,0 +1,97 @@
+"""
+Localization Manifest Spec v1 Rollout Phase Controller.
+
+Manages the phased rollout of localization validation rules:
+- Phase 1 (WARNINGS_ONLY): All validators emit warnings only
+- Phase 2 (TESTER_ENFORCEMENT): Tester phase validators (LOCALE-TEST-*) strict
+- Phase 3 (FULL_ENFORCEMENT): All validators including Coder (LOCALE-CODE-*) strict
+
+Usage in validators:
+    from atdd.coach.utils.locale_phase import LocalePhase, should_enforce_locale
+
+    if should_enforce_locale(LocalePhase.TESTER_ENFORCEMENT):
+        assert condition, "Error message"
+    else:
+        if not condition:
+            emit_locale_warning("LOCALE-TEST-1.1", "Warning message", LocalePhase.TESTER_ENFORCEMENT)
+"""
+
+from enum import IntEnum
+from typing import Optional
+import warnings
+
+
+class LocalePhase(IntEnum):
+    """
+    Rollout phases for Localization Manifest Spec v1.
+
+    Phases are ordered by strictness level:
+    - WARNINGS_ONLY (1): All new validators emit warnings, no assertions
+    - TESTER_ENFORCEMENT (2): Tester phase validators (LOCALE-TEST-*) strict
+    - FULL_ENFORCEMENT (3): All validators including Coder (LOCALE-CODE-*) strict
+    """
+    WARNINGS_ONLY = 1
+    TESTER_ENFORCEMENT = 2
+    FULL_ENFORCEMENT = 3
+
+
+# Current rollout phase - update this to advance through phases
+CURRENT_LOCALE_PHASE = LocalePhase.WARNINGS_ONLY
+
+
+def should_enforce_locale(validator_phase: LocalePhase) -> bool:
+    """
+    Check if a locale 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_locale(LocalePhase.TESTER_ENFORCEMENT):
+            assert all_keys_match, "Keys must match reference locale"
+        else:
+            if not all_keys_match:
+                emit_locale_warning("LOCALE-TEST-1.4", "Keys don't match", LocalePhase.TESTER_ENFORCEMENT)
+    """
+    return CURRENT_LOCALE_PHASE >= validator_phase
+
+
+def get_current_locale_phase() -> LocalePhase:
+    """Get the current locale rollout phase."""
+    return CURRENT_LOCALE_PHASE
+
+
+def get_locale_phase_name(phase: Optional[LocalePhase] = None) -> str:
+    """Get human-readable name for a locale phase."""
+    phase = phase or CURRENT_LOCALE_PHASE
+    return {
+        LocalePhase.WARNINGS_ONLY: "Phase 1: Warnings Only",
+        LocalePhase.TESTER_ENFORCEMENT: "Phase 2: Tester Enforcement",
+        LocalePhase.FULL_ENFORCEMENT: "Phase 3: Full Enforcement",
+    }.get(phase, "Unknown Phase")
+
+
+def emit_locale_warning(
+    spec_id: str,
+    message: str,
+    validator_phase: LocalePhase = LocalePhase.TESTER_ENFORCEMENT
+) -> None:
+    """
+    Emit a locale validation warning with phase context.
+
+    Args:
+        spec_id: The SPEC ID (e.g., "LOCALE-TEST-1.1")
+        message: The warning message
+        validator_phase: Phase when this becomes an error
+    """
+    phase_name = get_locale_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

@@ -599,3 +599,52 @@ def wagon_to_train_mapping(train_files: List[Tuple[Path, Dict]]) -> Dict[str, Li
                 mapping[wagon_slug].append(train_id)
 
     return mapping
+
+
+# ============================================================================
+# LOCALIZATION FIXTURES (Localization Manifest Spec v1)
+# ============================================================================
+
+
+@pytest.fixture(scope="module")
+def locale_manifest_path(atdd_config: Dict[str, Any]) -> Optional[Path]:
+    """
+    Get path to localization manifest file from config.
+
+    Returns:
+        Path to manifest file, or None if localization not configured
+    """
+    manifest_rel = atdd_config.get("localization", {}).get("manifest")
+    if not manifest_rel:
+        return None
+    return REPO_ROOT / manifest_rel
+
+
+@pytest.fixture(scope="module")
+def locale_manifest(locale_manifest_path: Optional[Path]) -> Optional[Dict[str, Any]]:
+    """
+    Load localization manifest from configured path.
+
+    Returns:
+        Manifest dict with reference, locales, namespaces, or None if not configured
+    """
+    if locale_manifest_path is None:
+        return None
+    if not locale_manifest_path.exists():
+        return None
+
+    with open(locale_manifest_path) as f:
+        return json.load(f)
+
+
+@pytest.fixture(scope="module")
+def locales_dir(locale_manifest_path: Optional[Path]) -> Optional[Path]:
+    """
+    Get locales directory (parent of manifest file).
+
+    Returns:
+        Path to locales directory, or None if not configured
+    """
+    if locale_manifest_path is None:
+        return None
+    return locale_manifest_path.parent

atdd/coder/conventions/backend.convention.yaml

@@ -281,7 +281,7 @@ backend:
 
             direct_adapter:
               pattern: "direct_*_client.py"
-              use_when: "Wagons run in same process (monolith via game.py)"
+              use_when: "Wagons run in same process (monolith via app.py)"
               example: "DirectCommitStateClient reads from shared StateRepository"
               benefits:
                 - "No network latency"

atdd/coder/conventions/boundaries.convention.yaml

@@ -243,7 +243,7 @@ interaction:
 
   composition_roots:
     description: |
-      Composition roots (composition.py, wagon.py, trains/runner.py, game.py) are entrypoints
+      Composition roots (composition.py, wagon.py, trains/runner.py, app.py) are entrypoints
       that wire dependencies. They are executed, never imported by other code.
 
     feature_composition:
@@ -332,15 +332,15 @@ interaction:
     # ========================================================================
     station_master_pattern:
       description: |
-        When multiple wagons run in a single process (game.py), the Station Master
+        When multiple wagons run in a single process (app.py), the Station Master
         pattern enables shared dependency injection without HTTP self-calls.
 
-        game.py creates shared singletons (StateRepository, EventBus, etc.) and
+        app.py creates shared singletons (StateRepository, EventBus, etc.) and
         passes them to wagon composition.py functions, which decide internally
         whether to use Direct adapters (monolith) or HTTP adapters (microservices).
 
       architecture: |
-        game.py (Station Master / Thin Router)
+        app.py (Station Master / Thin Router)
           │
           ├── Creates shared singletons:
           │     - StateRepository (commit-state data)
@@ -391,7 +391,7 @@ interaction:
               """Wire dependencies with optional SharedDependencies.
 
               Args:
-                  shared: SharedDependencies from game.py (monolith mode).
+                  shared: SharedDependencies from app.py (monolith mode).
                           When provided, uses Direct adapters for cross-wagon data.
                           When None, uses Fake adapters for standalone testing.
               """
@@ -424,7 +424,7 @@ interaction:
           Same interface (implements Port), different implementation.
 
       station_master_responsibilities:
-        game_py:
+        app_py:
           - "Create shared singletons (StateRepository, EventBus)"
           - "Pass shared deps to wagon composition.py"
           - "Include wagon routers in FastAPI app"
@@ -440,12 +440,12 @@ interaction:
         required:
           - "composition.py accepts optional shared dependency parameters"
           - "Direct adapters exist for cross-wagon data access"
-          - "game.py calls composition.py, not duplicates wiring"
+          - "app.py calls composition.py, not duplicates wiring"
 
         forbidden:
-          - "game.py creating use cases that composition.py should own"
+          - "app.py creating use cases that composition.py should own"
           - "HTTP clients calling localhost in production monolith"
-          - "Duplicated wiring logic between game.py and composition.py"
+          - "Duplicated wiring logic between app.py and composition.py"
 
   forbidden_cross_wagon_imports:
     rule: "Code in wagon A MUST NOT import directly from wagon B"

atdd/coder/conventions/presentation.convention.yaml

@@ -540,25 +540,25 @@ validation:
       - "Simple error handling has TODO(REFACTOR) marker"
 
     unified_game_server:
-      description: "python/game.py must aggregate all wagon presentation layers"
-      file: "python/game.py"
+      description: "python/app.py must aggregate all wagon presentation layers"
+      file: "python/app.py"
       requirements:
-        - "When new wagon adds FastAPI controller, game.py MUST be updated"
-        - "game.py imports controller's app and includes via app.include_router()"
+        - "When new wagon adds FastAPI controller, app.py MUST be updated"
+        - "app.py imports controller's app and includes via app.include_router()"
         - "All wagon endpoints accessible via unified game server"
-        - "Validator checks: all wagons with presentation are registered in game.py"
+        - "Validator checks: all wagons with presentation are registered in app.py"
 
       rationale: |
-        game.py is the unified entry point for all backend services.
+        app.py is the unified entry point for all backend services.
         Without registration, wagon endpoints are inaccessible to game server/mobile app.
 
       pattern: |
-        # python/game.py
+        # python/app.py
         from burn_timebank.track_remaining.src.presentation.controllers.remaining_controller import app as timebank_app
         app.include_router(timebank_app.router, prefix="/timebank")
 
       anti_pattern: |
-        # ❌ WRONG: Wagon has FastAPI controller but not registered in game.py
+        # ❌ WRONG: Wagon has FastAPI controller but not registered in app.py
         # Result: Endpoints exist but unreachable from unified server
 
   usage: |

atdd/coder/conventions/train.convention.yaml

@@ -8,8 +8,8 @@ rationale: |
   defined in YAML specifications by coordinating wagons through contract-based communication.
 
   TRANSFORMATION (SESSION-12):
-    - OLD: Trains in e2e/ (test-only), custom orchestration in game.py
-    - NEW: Trains in python/trains/ (production), game.py becomes thin Station Master
+    - OLD: Trains in e2e/ (test-only), custom orchestration in app.py
+    - NEW: Trains in python/trains/ (production), app.py becomes thin Station Master
 
   BENEFITS:
     - Single source of truth (YAML defines both production AND tests)
@@ -21,7 +21,7 @@ cross_references:
   composition_hierarchy:
     - file: "refactor.convention.yaml"
       section: "composition_root.hierarchy"
-      note: "Trains add new orchestration layer between game.py and wagon.py"
+      note: "Trains add new orchestration layer between app.py and wagon.py"
 
   boundaries:
     - file: "boundaries.convention.yaml"
@@ -37,14 +37,15 @@ cross_references:
 # ============================================================================
 
 composition_hierarchy:
-  description: "Trains sit between application (game.py) and wagons (wagon.py)"
+  description: "Trains sit between application (app.py) and wagons (wagon.py)"
 
   levels:
     application:
-      file: "python/game.py"
+      file: "python/app.py"
       role: "Station Master - thin router"
       responsibility: "Map user actions → train_ids, invoke TrainRunner"
       size: "< 50 lines of routing logic"
+      note: "app.py is the Station Master entrypoint"
 
     train:
       file: "python/trains/runner.py"
@@ -65,8 +66,8 @@ composition_hierarchy:
 
   dependency_flow:
     rule: "Dependencies flow downward only"
-    chain: "game.py → trains.runner → wagon.py → composition.py → src/"
-    forbidden: "NEVER: wagon imports from trains or game"
+    chain: "app.py → trains.runner → wagon.py → composition.py → src/"
+    forbidden: "NEVER: wagon imports from trains or app"
 
 # ============================================================================
 # TRAIN INFRASTRUCTURE
@@ -138,7 +139,7 @@ wagon_train_mode:
   multi_mode_pattern:
     description: "Wagons support multiple execution modes"
     cli: "Interactive demo (python3 wagon.py)"
-    http: "API endpoints (via game.py)"
+    http: "API endpoints (via app.py)"
     train: "Production orchestration (via TrainRunner)"
 
 # ============================================================================
@@ -170,14 +171,14 @@ cargo_pattern:
     method: "JSON Schema Draft-07 validation"
 
 # ============================================================================
-# STATION MASTER PATTERN (game.py)
+# STATION MASTER PATTERN (app.py)
 # ============================================================================
 
 station_master:
-  description: "game.py becomes thin router that delegates to TrainRunner"
+  description: "app.py becomes thin router that delegates to TrainRunner"
 
   pattern: |
-    # game.py - Station Master
+    # app.py - Station Master
     from trains.runner import TrainRunner
 
     JOURNEY_MAP = {
@@ -198,7 +199,7 @@ station_master:
     - "Translate HTTP ↔ artifacts"
     - "Handle errors"
 
-  anti_pattern: "Business logic in game.py (belongs in trains/wagons)"
+  anti_pattern: "Business logic in app.py (belongs in trains/wagons)"
 
 # ============================================================================
 # TESTING
@@ -278,10 +279,10 @@ observability:
 # ============================================================================
 
 migration:
-  step_1: "Identify user journeys in game.py"
+  step_1: "Identify user journeys in app.py"
   step_2: "Create train YAML (plan/_trains/{train_id}.yaml)"
   step_3: "Add run_train() to participating wagons"
-  step_4: "Refactor game.py to Station Master pattern"
+  step_4: "Refactor app.py to Station Master pattern"
   step_5: "Update tests to use TrainRunner"
 
 # ============================================================================

atdd/coder/validators/test_i18n_runtime.py

@@ -0,0 +1,171 @@
+"""
+i18n runtime validation (Localization Manifest Spec v1).
+
+Validates that runtime code uses the centralized locale manifest:
+- LOCALE-CODE-2.1: i18nConfig.ts imports from manifest (not hardcoded arrays)
+- LOCALE-CODE-2.2: LanguageSwitcher uses shared SUPPORTED_LOCALES
+"""
+
+import re
+import pytest
+from pathlib import Path
+from typing import Optional
+
+from atdd.coach.utils.locale_phase import (
+    LocalePhase,
+    should_enforce_locale,
+    emit_locale_warning,
+)
+from atdd.coach.utils.repo import find_repo_root
+
+# Path constants
+REPO_ROOT = find_repo_root()
+WEB_DIR = REPO_ROOT / "web"
+
+
+def _find_file(base_dir: Path, *possible_paths: str) -> Optional[Path]:
+    """Find first existing file from list of possible paths."""
+    for rel_path in possible_paths:
+        full_path = base_dir / rel_path
+        if full_path.exists():
+            return full_path
+    return None
+
+
+def _read_file_content(path: Path) -> Optional[str]:
+    """Read file content, return None on error."""
+    try:
+        return path.read_text()
+    except Exception:
+        return None
+
+
+@pytest.mark.locale
+@pytest.mark.coder
+def test_i18n_config_uses_manifest(locale_manifest, locale_manifest_path):
+    """
+    LOCALE-CODE-2.1: i18nConfig.ts imports from manifest (not hardcoded arrays)
+
+    Given: Web application with i18n configuration
+    When: Checking i18nConfig.ts or i18n.ts
+    Then: Configuration imports locales from manifest or shared constant
+          NOT hardcoded locale arrays like ['en', 'es', 'fr']
+    """
+    if locale_manifest is None:
+        pytest.skip("Localization not configured")
+
+    i18n_config = _find_file(
+        WEB_DIR,
+        "src/i18nConfig.ts",
+        "src/i18n/config.ts",
+        "src/i18n.ts",
+        "src/lib/i18n.ts",
+        "src/config/i18n.ts",
+    )
+
+    if i18n_config is None:
+        pytest.skip("No i18n config file found in web/src/")
+
+    content = _read_file_content(i18n_config)
+    if content is None:
+        pytest.skip(f"Cannot read {i18n_config}")
+
+    hardcoded_array_pattern = re.compile(
+        r"(?:locales|supportedLocales|SUPPORTED_LOCALES|languages)\s*[=:]\s*\[\s*['\"][a-z]{2}",
+        re.IGNORECASE
+    )
+
+    if hardcoded_array_pattern.search(content):
+        manifest_import_patterns = [
+            r"from\s+['\"].*manifest",
+            r"import.*manifest",
+            r"require\s*\(\s*['\"].*manifest",
+            r"SUPPORTED_LOCALES",
+            r"getSupportedLocales",
+        ]
+
+        has_manifest_usage = any(
+            re.search(pattern, content, re.IGNORECASE)
+            for pattern in manifest_import_patterns
+        )
+
+        if not has_manifest_usage:
+            msg = (
+                f"i18n config has hardcoded locale array: {i18n_config.relative_to(REPO_ROOT)}\n"
+                f"  Should import from manifest.json or use shared SUPPORTED_LOCALES constant"
+            )
+            if should_enforce_locale(LocalePhase.FULL_ENFORCEMENT):
+                pytest.fail(msg)
+            else:
+                emit_locale_warning("LOCALE-CODE-2.1", msg, LocalePhase.FULL_ENFORCEMENT)
+                pytest.skip(msg)
+
+
+@pytest.mark.locale
+@pytest.mark.coder
+def test_language_switcher_uses_shared_locales(locale_manifest, locale_manifest_path):
+    """
+    LOCALE-CODE-2.2: LanguageSwitcher uses shared SUPPORTED_LOCALES
+
+    Given: Web application with language switcher component
+    When: Checking LanguageSwitcher component
+    Then: Component imports locales from shared constant or manifest
+          NOT hardcoded locale arrays
+    """
+    if locale_manifest is None:
+        pytest.skip("Localization not configured")
+
+    switcher_patterns = [
+        "src/components/LanguageSwitcher.tsx",
+        "src/components/LocaleSwitcher.tsx",
+        "src/components/ui/LanguageSwitcher.tsx",
+        "src/components/common/LanguageSwitcher.tsx",
+        "src/features/i18n/LanguageSwitcher.tsx",
+    ]
+
+    switcher_file = _find_file(WEB_DIR, *switcher_patterns)
+
+    if switcher_file is None:
+        switcher_files = list(WEB_DIR.rglob("*[Ll]anguage*[Ss]witcher*.tsx"))
+        if not switcher_files:
+            switcher_files = list(WEB_DIR.rglob("*[Ll]ocale*[Ss]witcher*.tsx"))
+        if switcher_files:
+            switcher_file = switcher_files[0]
+
+    if switcher_file is None:
+        pytest.skip("No LanguageSwitcher component found")
+
+    content = _read_file_content(switcher_file)
+    if content is None:
+        pytest.skip(f"Cannot read {switcher_file}")
+
+    hardcoded_array_pattern = re.compile(
+        r"(?:locales|languages|options)\s*[=:]\s*\[\s*(?:\{[^}]*locale[^}]*['\"][a-z]{2}|['\"][a-z]{2})",
+        re.IGNORECASE
+    )
+
+    if hardcoded_array_pattern.search(content):
+        shared_patterns = [
+            r"SUPPORTED_LOCALES",
+            r"getSupportedLocales",
+            r"from\s+['\"].*manifest",
+            r"from\s+['\"].*i18n",
+            r"from\s+['\"].*config",
+            r"useLocales",
+        ]
+
+        has_shared_usage = any(
+            re.search(pattern, content, re.IGNORECASE)
+            for pattern in shared_patterns
+        )
+
+        if not has_shared_usage:
+            msg = (
+                f"LanguageSwitcher has hardcoded locale array: {switcher_file.relative_to(REPO_ROOT)}\n"
+                f"  Should import from shared SUPPORTED_LOCALES or manifest"
+            )
+            if should_enforce_locale(LocalePhase.FULL_ENFORCEMENT):
+                pytest.fail(msg)
+            else:
+                emit_locale_warning("LOCALE-CODE-2.2", msg, LocalePhase.FULL_ENFORCEMENT)
+                pytest.skip(msg)

atdd/coder/validators/test_presentation_convention.py

@@ -180,16 +180,16 @@ class PresentationValidator:
 
 
     def validate_game_server_registration(self):
-        """Validate python/game.py includes all wagons with presentation."""
-        game_file = self.python_root / "game.py"
+        """Validate python/app.py includes all wagons with presentation."""
+        server_file = self.python_root / "app.py"
 
-        if not game_file.exists():
-            self.violations.append("❌ python/game.py not found - unified game server missing")
+        if not server_file.exists():
+            self.violations.append("❌ python/app.py not found - unified server missing")
             return
 
-        print(f"\nValidating unified game server: python/game.py")
+        print("\nValidating unified server: python/app.py")
 
-        content = game_file.read_text()
+        content = server_file.read_text()
 
         # Find all wagons with FastAPI controllers
         wagons_with_controllers = {}
@@ -209,7 +209,7 @@ class PresentationValidator:
                         if "fastapi" in controller_file.read_text().lower():
                             wagons_with_controllers[f"{wagon_dir.name}/{feature_dir.name}"] = controller_file
 
-        # Check if each controller is registered in game.py
+        # Check if each controller is registered in the unified server file
         for wagon_feature, controller_file in wagons_with_controllers.items():
             wagon, feature = wagon_feature.split('/')
 
@@ -217,17 +217,17 @@ class PresentationValidator:
             import_pattern = f"from {wagon}.{feature}.src.presentation.controllers"
             if import_pattern not in content:
                 self.violations.append(
-                    f"❌ game.py missing import for {wagon}/{feature} controller"
+                    f"❌ app.py missing import for {wagon}/{feature} controller"
                 )
 
             # Check for include_router
             if "include_router" in content and wagon not in content.lower():
                 self.violations.append(
-                    f"⚠️  game.py may not be registering {wagon}/{feature} routes"
+                    f"⚠️  app.py may not be registering {wagon}/{feature} routes"
                 )
 
         if not self.violations:
-            print(f"  ✓ All {len(wagons_with_controllers)} wagons registered in game.py")
+            print(f"  ✓ All {len(wagons_with_controllers)} wagons registered in app.py")
 
 
 def main():
@@ -236,7 +236,7 @@ def main():
 
     parser = argparse.ArgumentParser(description="Validate presentation layer convention")
     parser.add_argument("--check-game-server", action="store_true",
-                       help="Validate python/game.py is up to date")
+                       help="Validate python/app.py is up to date")
     args = parser.parse_args()
 
     python_root = REPO_ROOT / "python"