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

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)

atdd/coder/validators/test_train_infrastructure.py

@@ -1,5 +1,5 @@
 """
-Test train infrastructure validation (SESSION-12).
+Test train infrastructure validation (SESSION-12 + Train First-Class Spec v0.6).
 
 Validates conventions from:
 - atdd/coder/conventions/train.convention.yaml
@@ -13,6 +13,11 @@ Enforces:
 - E2E tests use production TrainRunner
 - Station Master pattern in game.py
 
+Train First-Class Spec v0.6 additions:
+- SPEC-TRAIN-VAL-0031: Backend runner paths
+- SPEC-TRAIN-VAL-0032: Frontend code allowed roots
+- SPEC-TRAIN-VAL-0033: FastAPI template enforcement
+
 Rationale:
 Trains are production orchestration, not test infrastructure (SESSION-12).
 These audits ensure the train composition root pattern is correctly implemented.
@@ -21,11 +26,18 @@ These audits ensure the train composition root pattern is correctly implemented.
 import pytest
 import ast
 import re
+import yaml
 from pathlib import Path
-from typing import List, Dict, Set, Tuple
+from typing import List, Dict, Set, Tuple, Any
 
 import atdd
 from atdd.coach.utils.repo import find_repo_root
+from atdd.coach.utils.train_spec_phase import (
+    TrainSpecPhase,
+    should_enforce,
+    emit_phase_warning
+)
+from atdd.coach.utils.config import get_train_config
 
 
 # Path constants
@@ -459,3 +471,225 @@ def test_no_wagon_to_wagon_imports():
             "\n\nWagons must communicate via contracts only, not direct imports\n"
             "See: atdd/coder/conventions/boundaries.convention.yaml"
         )
+
+
+# ============================================================================
+# TRAIN FIRST-CLASS SPEC v0.6 VALIDATORS
+# ============================================================================
+
+
+def _get_all_train_ids() -> List[str]:
+    """Get all train IDs from registry."""
+    train_ids = []
+    trains_file = REPO_ROOT / "plan" / "_trains.yaml"
+
+    if trains_file.exists():
+        with open(trains_file) as f:
+            data = yaml.safe_load(f)
+
+        for theme_key, categories in data.get("trains", {}).items():
+            if isinstance(categories, dict):
+                for category_key, trains_list in categories.items():
+                    if isinstance(trains_list, list):
+                        for train in trains_list:
+                            train_id = train.get("train_id")
+                            if train_id:
+                                train_ids.append(train_id)
+
+    return train_ids
+
+
+def test_backend_runner_paths():
+    """
+    SPEC-TRAIN-VAL-0031: Backend runner paths validation.
+
+    Given: Train infrastructure
+    When: Checking runner file locations
+    Then: Runners exist at python/trains/runner.py or python/trains/<train_id>/runner.py
+
+    Section 9: Backend Runner Paths
+    """
+    train_config = get_train_config(REPO_ROOT)
+    allowed_paths = train_config.get("backend_runner_paths", [
+        "python/trains/runner.py",
+        "python/trains/{train_id}/runner.py"
+    ])
+
+    # Check for main runner
+    main_runner = TRAINS_DIR / "runner.py"
+    if not main_runner.exists():
+        if should_enforce(TrainSpecPhase.BACKEND_ENFORCEMENT):
+            pytest.fail(
+                f"Main TrainRunner not found at {main_runner}\n"
+                "Expected: python/trains/runner.py"
+            )
+        else:
+            emit_phase_warning(
+                "SPEC-TRAIN-VAL-0031",
+                f"Main TrainRunner not found at {main_runner}",
+                TrainSpecPhase.BACKEND_ENFORCEMENT
+            )
+        return
+
+    # Check for train-specific runners if trains have custom runners
+    train_ids = _get_all_train_ids()
+    custom_runners = []
+
+    for train_id in train_ids:
+        custom_runner = TRAINS_DIR / train_id / "runner.py"
+        if custom_runner.exists():
+            custom_runners.append((train_id, custom_runner))
+
+    # Validate custom runners extend base TrainRunner
+    for train_id, runner_path in custom_runners:
+        with open(runner_path, 'r', encoding='utf-8') as f:
+            content = f.read()
+
+        if "TrainRunner" not in content:
+            if should_enforce(TrainSpecPhase.BACKEND_ENFORCEMENT):
+                pytest.fail(
+                    f"Custom runner at {runner_path} does not reference TrainRunner\n"
+                    "Custom runners should extend or use the base TrainRunner"
+                )
+            else:
+                emit_phase_warning(
+                    "SPEC-TRAIN-VAL-0031",
+                    f"Custom runner {train_id}/runner.py should reference TrainRunner",
+                    TrainSpecPhase.BACKEND_ENFORCEMENT
+                )
+
+
+def test_frontend_code_allowed_roots():
+    """
+    SPEC-TRAIN-VAL-0032: Frontend code in allowed root directories.
+
+    Given: Frontend (web) code files
+    When: Checking file locations
+    Then: Code is in allowed roots (web/src/, web/components/, web/pages/)
+
+    Section 10: Frontend Code Allowed Roots
+    """
+    train_config = get_train_config(REPO_ROOT)
+    allowed_roots = train_config.get("frontend_allowed_roots", [
+        "web/src/",
+        "web/components/",
+        "web/pages/"
+    ])
+
+    web_dir = REPO_ROOT / "web"
+    if not web_dir.exists():
+        pytest.skip("No web/ directory found")
+
+    # Find all TypeScript/JavaScript files in web/
+    code_files = []
+    for pattern in ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx"]:
+        code_files.extend(web_dir.glob(pattern))
+
+    # Exclude test files, node_modules, and build directories
+    code_files = [
+        f for f in code_files
+        if "node_modules" not in str(f)
+        and ".next" not in str(f)
+        and "dist" not in str(f)
+        and not f.name.endswith(".test.ts")
+        and not f.name.endswith(".test.tsx")
+        and not f.name.endswith(".spec.ts")
+    ]
+
+    violations = []
+    for code_file in code_files:
+        rel_path = code_file.relative_to(REPO_ROOT)
+        in_allowed_root = any(str(rel_path).startswith(root) for root in allowed_roots)
+
+        # Also allow e2e/ directory for tests (already excluded above but be explicit)
+        in_e2e = str(rel_path).startswith("web/e2e/")
+
+        if not in_allowed_root and not in_e2e:
+            # Check if it's a config file at root level (allow those)
+            is_config = code_file.parent == web_dir and code_file.suffix in [".js", ".ts"]
+            if not is_config:
+                violations.append(str(rel_path))
+
+    if violations and len(violations) > 10:
+        if should_enforce(TrainSpecPhase.FULL_ENFORCEMENT):
+            pytest.fail(
+                f"Frontend code outside allowed roots ({len(violations)} files):\n  " +
+                "\n  ".join(violations[:10]) +
+                f"\n  ... and {len(violations) - 10} more" +
+                f"\n\nAllowed roots: {allowed_roots}"
+            )
+        else:
+            emit_phase_warning(
+                "SPEC-TRAIN-VAL-0032",
+                f"{len(violations)} frontend files outside allowed roots",
+                TrainSpecPhase.FULL_ENFORCEMENT
+            )
+
+
+def test_fastapi_template_enforcement():
+    """
+    SPEC-TRAIN-VAL-0033: FastAPI template enforcement when configured.
+
+    Given: .atdd/config.yaml with enforce_fastapi_template=true
+    When: Checking API endpoint files
+    Then: Endpoints follow FastAPI template conventions
+
+    Section 11: FastAPI Template Enforcement
+    """
+    train_config = get_train_config(REPO_ROOT)
+
+    if not train_config.get("enforce_fastapi_template", False):
+        pytest.skip("FastAPI template enforcement not enabled in config")
+
+    # Look for FastAPI app files
+    python_dir = REPO_ROOT / "python"
+    if not python_dir.exists():
+        pytest.skip("No python/ directory found")
+
+    # Find files that define FastAPI apps
+    fastapi_files = []
+    for py_file in python_dir.rglob("*.py"):
+        if "__pycache__" in str(py_file):
+            continue
+
+        try:
+            with open(py_file, 'r', encoding='utf-8') as f:
+                content = f.read()
+
+            if "FastAPI" in content and ("app = FastAPI" in content or "router = APIRouter" in content):
+                fastapi_files.append(py_file)
+        except Exception:
+            pass
+
+    if not fastapi_files:
+        pytest.skip("No FastAPI app files found")
+
+    # Check template conventions
+    violations = []
+    for api_file in fastapi_files:
+        with open(api_file, 'r', encoding='utf-8') as f:
+            content = f.read()
+
+        # Check for required template elements
+        required_elements = [
+            ("response_model", "Endpoints should use response_model parameter"),
+            ("HTTPException", "Endpoints should use HTTPException for errors"),
+        ]
+
+        for element, description in required_elements:
+            if element not in content:
+                violations.append(f"{api_file.name}: {description}")
+
+    if violations:
+        if should_enforce(TrainSpecPhase.FULL_ENFORCEMENT):
+            pytest.fail(
+                f"FastAPI template violations:\n  " + "\n  ".join(violations) +
+                "\n\nSee: train.convention.yaml for FastAPI template requirements"
+            )
+        else:
+            for violation in violations:
+                emit_phase_warning(
+                    "SPEC-TRAIN-VAL-0033",
+                    violation,
+                    TrainSpecPhase.FULL_ENFORCEMENT
+                )

atdd/planner/schemas/train.schema.json

@@ -16,7 +16,7 @@
   "properties": {
     "train_id": {
       "type": "string",
-      "pattern": "^[0-9]{4}-[a-z][a-z0-9-]*$",
+      "pattern": "^\\d{4}-[a-z0-9-]+$",
       "description": "Train identifier with hierarchical numbering: {theme}{category}{variation}-{kebab-case-name} (e.g., 0001-auth-session-standard, 2301-empty-input-file)"
     },
     "title": {
@@ -29,6 +29,15 @@
       "minLength": 10,
       "description": "Concise description of the train's purpose and workflow"
     },
+    "path": {
+      "type": "string",
+      "description": "Canonical path to the train YAML file relative to repo root"
+    },
+    "file": {
+      "type": "string",
+      "description": "DEPRECATED: Use 'path' instead. Alias for backward compatibility",
+      "deprecated": true
+    },
     "themes": {
       "type": "array",
       "description": "Theme categories this train belongs to",
@@ -49,12 +58,17 @@
         ]
       }
     },
+    "primary_wagon": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "description": "The primary wagon responsible for this train's core functionality"
+    },
     "dependencies": {
       "type": "array",
       "description": "Other trains that must run before this train",
       "items": {
         "type": "string",
-        "pattern": "^train:[0-9]{4}-[a-z][a-z0-9-]*$",
+        "pattern": "^train:\\d{4}-[a-z0-9-]+$",
         "description": "Train reference in format: train:{train_id}"
       }
     },
@@ -68,6 +82,115 @@
         "description": "Participant reference: wagon:{wagon-id}, user:{role}, system:{source}"
       }
     },
+    "test": {
+      "oneOf": [
+        {
+          "type": "string",
+          "description": "Single backend test file path"
+        },
+        {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "List of backend test file paths"
+        },
+        {
+          "type": "object",
+          "properties": {
+            "backend": {
+              "oneOf": [
+                { "type": "string" },
+                { "type": "array", "items": { "type": "string" } }
+              ],
+              "description": "Backend test file path(s)"
+            },
+            "frontend": {
+              "oneOf": [
+                { "type": "string" },
+                { "type": "array", "items": { "type": "string" } }
+              ],
+              "description": "Frontend (web) test file path(s)"
+            },
+            "frontend_python": {
+              "oneOf": [
+                { "type": "string" },
+                { "type": "array", "items": { "type": "string" } }
+              ],
+              "description": "Frontend Python (Streamlit) test file path(s)"
+            }
+          },
+          "additionalProperties": false,
+          "description": "Test files organized by platform"
+        }
+      ],
+      "description": "Test file references for this train (string, array, or object with backend/frontend/frontend_python)"
+    },
+    "code": {
+      "oneOf": [
+        {
+          "type": "string",
+          "description": "Single backend implementation file path"
+        },
+        {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "List of backend implementation file paths"
+        },
+        {
+          "type": "object",
+          "properties": {
+            "backend": {
+              "oneOf": [
+                { "type": "string" },
+                { "type": "array", "items": { "type": "string" } }
+              ],
+              "description": "Backend implementation file path(s)"
+            },
+            "frontend": {
+              "oneOf": [
+                { "type": "string" },
+                { "type": "array", "items": { "type": "string" } }
+              ],
+              "description": "Frontend (web) implementation file path(s)"
+            },
+            "frontend_python": {
+              "oneOf": [
+                { "type": "string" },
+                { "type": "array", "items": { "type": "string" } }
+              ],
+              "description": "Frontend Python (Streamlit) implementation file path(s)"
+            }
+          },
+          "additionalProperties": false,
+          "description": "Implementation files organized by platform"
+        }
+      ],
+      "description": "Implementation file references for this train (string, array, or object with backend/frontend/frontend_python)"
+    },
+    "expectations": {
+      "type": "object",
+      "properties": {
+        "backend": {
+          "type": "boolean",
+          "description": "Whether backend implementation is expected"
+        },
+        "frontend": {
+          "type": "boolean",
+          "description": "Whether frontend (web) implementation is expected"
+        },
+        "frontend_python": {
+          "type": "boolean",
+          "description": "Whether frontend Python (Streamlit) implementation is expected"
+        }
+      },
+      "additionalProperties": false,
+      "description": "Explicit expectations for which platforms this train should be implemented on"
+    },
+    "status": {
+      "type": "string",
+      "enum": ["planned", "tested", "implemented"],
+      "default": "planned",
+      "description": "Current implementation status of the train"
+    },
     "sequence": {
       "type": "array",
       "description": "Ordered steps, loops, and routes defining the train workflow",