atdd 0.1.0__py3-none-any.whl

atdd/coder/validators/test_quality_metrics.py

@@ -0,0 +1,420 @@
+"""
+Test code quality metrics meet minimum standards.
+
+Validates:
+- Maintainability index > 60
+- Code has appropriate comments
+- No code duplication
+- Consistent naming conventions
+
+Inspired by: .claude/utils/coder/quality_metrics.py
+But: Self-contained, no utility dependencies
+"""
+
+import pytest
+import re
+from pathlib import Path
+from typing import List, Tuple
+
+
+# Path constants
+REPO_ROOT = Path(__file__).resolve().parents[3]
+PYTHON_DIR = REPO_ROOT / "python"
+
+
+# Quality thresholds
+MIN_MAINTAINABILITY_INDEX = 60
+MIN_COMMENT_RATIO = 0.10  # 10% comments
+MAX_DUPLICATE_LINES = 5
+
+
+def find_python_files() -> List[Path]:
+    """Find all Python source files (excluding tests)."""
+    if not PYTHON_DIR.exists():
+        return []
+
+    files = []
+    for py_file in PYTHON_DIR.rglob("*.py"):
+        if '/test/' in str(py_file) or py_file.name.startswith('test_'):
+            continue
+        if '__pycache__' in str(py_file):
+            continue
+        files.append(py_file)
+
+    return files
+
+
+def calculate_maintainability_index(file_path: Path) -> float:
+    """
+    Calculate simplified maintainability index for a file.
+
+    Based on:
+    - Lines of code
+    - Cyclomatic complexity (simplified)
+    - Comment ratio
+
+    Returns value 0-100 (higher is better)
+    """
+    try:
+        with open(file_path, 'r', encoding='utf-8') as f:
+            lines = f.readlines()
+    except Exception:
+        return 0
+
+    total_lines = len(lines)
+    code_lines = 0
+    comment_lines = 0
+    blank_lines = 0
+
+    for line in lines:
+        stripped = line.strip()
+        if not stripped:
+            blank_lines += 1
+        elif stripped.startswith('#'):
+            comment_lines += 1
+        else:
+            code_lines += 1
+
+    # Simple heuristic for maintainability
+    # Higher comment ratio = better
+    comment_ratio = comment_lines / total_lines if total_lines > 0 else 0
+
+    # Shorter files = better
+    size_factor = max(0, 100 - (code_lines / 10))
+
+    # Calculate index (simplified)
+    index = (size_factor * 0.4) + (comment_ratio * 100 * 0.6)
+
+    return min(100, max(0, index))
+
+
+def calculate_comment_ratio(file_path: Path) -> float:
+    """
+    Calculate ratio of comments and docstrings to code.
+
+    Counts both:
+    - Inline comments (lines starting with #)
+    - Docstrings (triple-quoted strings)
+
+    Returns:
+        Ratio (0.0 to 1.0)
+    """
+    try:
+        with open(file_path, 'r', encoding='utf-8') as f:
+            lines = f.readlines()
+    except Exception:
+        return 0.0
+
+    code_lines = 0
+    comment_lines = 0
+    in_docstring = False
+    docstring_delim = None
+
+    for line in lines:
+        stripped = line.strip()
+        if not stripped:
+            continue
+
+        # Check for docstring delimiters
+        if '"""' in stripped or "'''" in stripped:
+            # Determine delimiter type
+            delim = '"""' if '"""' in stripped else "'''"
+
+            if not in_docstring:
+                # Starting a docstring
+                in_docstring = True
+                docstring_delim = delim
+                comment_lines += 1
+
+                # Check if docstring closes on same line
+                if stripped.count(delim) >= 2:
+                    in_docstring = False
+                    docstring_delim = None
+            else:
+                # Ending a docstring
+                if delim == docstring_delim:
+                    in_docstring = False
+                    docstring_delim = None
+                comment_lines += 1
+        elif in_docstring:
+            # Inside a docstring
+            comment_lines += 1
+        elif stripped.startswith('#'):
+            # Inline comment
+            comment_lines += 1
+        else:
+            # Code line
+            code_lines += 1
+
+    total = code_lines + comment_lines
+    return comment_lines / total if total > 0 else 0.0
+
+
+def find_duplicate_code_blocks(files: List[Path]) -> List[Tuple[Path, Path, List[str]]]:
+    """
+    Find duplicate code blocks across files.
+
+    Returns:
+        List of (file1, file2, duplicate_lines) tuples
+    """
+    duplicates = []
+
+    # Simplified duplicate detection
+    # In reality, would use more sophisticated algorithm
+
+    file_contents = {}
+    for file in files:
+        try:
+            with open(file, 'r', encoding='utf-8') as f:
+                # Get normalized lines (stripped of whitespace)
+                lines = [line.strip() for line in f.readlines() if line.strip() and not line.strip().startswith('#')]
+                file_contents[file] = lines
+        except Exception:
+            continue
+
+    # Compare files pairwise (simplified)
+    files_list = list(file_contents.keys())
+    for i, file1 in enumerate(files_list):
+        for file2 in files_list[i+1:]:
+            lines1 = file_contents[file1]
+            lines2 = file_contents[file2]
+
+            # Find consecutive duplicate lines
+            for start1 in range(len(lines1) - MAX_DUPLICATE_LINES):
+                block1 = lines1[start1:start1 + MAX_DUPLICATE_LINES]
+
+                for start2 in range(len(lines2) - MAX_DUPLICATE_LINES):
+                    block2 = lines2[start2:start2 + MAX_DUPLICATE_LINES]
+
+                    if block1 == block2:
+                        # Skip standard import blocks (common across port/adapter files)
+                        block_text = '\n'.join(block1)
+                        if 'from abc import' in block_text and 'from dataclasses import' in block_text:
+                            # Standard port/adapter imports - acceptable
+                            continue
+                        duplicates.append((file1, file2, block1))
+                        break
+
+    return duplicates
+
+
+def check_naming_consistency(file_path: Path) -> List[str]:
+    """
+    Check naming conventions consistency.
+
+    Returns:
+        List of naming violations
+    """
+    violations = []
+
+    try:
+        with open(file_path, 'r', encoding='utf-8') as f:
+            content = f.read()
+    except Exception:
+        return violations
+
+    # Check class names (should be PascalCase)
+    class_pattern = r'class\s+([a-z][a-zA-Z0-9_]*)\s*[:\(]'
+    lowercase_classes = re.findall(class_pattern, content)
+    for cls in lowercase_classes:
+        violations.append(f"Class '{cls}' should use PascalCase")
+
+    # Check constant names (should be UPPER_CASE)
+    # Pattern: variable assignment at module level that looks like it should be constant
+    const_pattern = r'^([a-z][a-z0-9_]*)\s*=\s*["\'\d\[]'
+    # pytest special variables that must be lowercase
+    pytest_special_vars = ['pytest_plugins']
+
+    for line in content.split('\n'):
+        if not line.startswith(' ') and not line.startswith('\t'):  # Module level
+            match = re.match(const_pattern, line)
+            if match and match.group(1).isupper():
+                # Good - already uppercase
+                pass
+            elif match and match.group(1) in pytest_special_vars:
+                # pytest special variable - must be lowercase
+                pass
+            elif match and '_' in match.group(1):
+                # Might be a constant with wrong case
+                violations.append(f"Constant '{match.group(1)}' should use UPPER_CASE")
+
+    return violations
+
+
+@pytest.mark.coder
+def test_maintainability_index_above_threshold():
+    """
+    SPEC-CODER-QUALITY-0001: Code has acceptable maintainability index.
+
+    Maintainability index measures:
+    - Code complexity
+    - Code size
+    - Documentation level
+
+    Threshold: > 60 (scale 0-100)
+
+    Given: All Python files
+    When: Calculating maintainability index
+    Then: Index > 60 for all files
+    """
+    python_files = find_python_files()
+
+    if not python_files:
+        pytest.skip("No Python files found")
+
+    violations = []
+
+    for py_file in python_files:
+        # Skip very small files
+        try:
+            with open(py_file, 'r', encoding='utf-8') as f:
+                lines = f.readlines()
+            if len(lines) < 10:
+                continue
+        except Exception:
+            continue
+
+        index = calculate_maintainability_index(py_file)
+
+        if index < MIN_MAINTAINABILITY_INDEX:
+            rel_path = py_file.relative_to(REPO_ROOT)
+            violations.append(
+                f"{rel_path}\\n"
+                f"  Maintainability Index: {index:.1f} (min: {MIN_MAINTAINABILITY_INDEX})\\n"
+                f"  Suggestion: Add comments, reduce complexity, or split file"
+            )
+
+    if violations:
+        pytest.fail(
+            f"\\n\\nFound {len(violations)} maintainability violations:\\n\\n" +
+            "\\n\\n".join(violations[:10]) +
+            (f"\\n\\n... and {len(violations) - 10} more" if len(violations) > 10 else "")
+        )
+
+
+@pytest.mark.coder
+def test_adequate_code_comments():
+    """
+    SPEC-CODER-QUALITY-0002: Code has adequate comments.
+
+    Well-commented code is easier to maintain.
+
+    Threshold: > 10% comment ratio
+
+    Given: All Python files
+    When: Calculating comment ratio
+    Then: At least 10% comments
+    """
+    python_files = find_python_files()
+
+    if not python_files:
+        pytest.skip("No Python files found")
+
+    violations = []
+
+    for py_file in python_files:
+        # Skip very small files
+        try:
+            with open(py_file, 'r', encoding='utf-8') as f:
+                lines = f.readlines()
+            if len(lines) < 20:
+                continue
+        except Exception:
+            continue
+
+        ratio = calculate_comment_ratio(py_file)
+
+        if ratio < MIN_COMMENT_RATIO:
+            rel_path = py_file.relative_to(REPO_ROOT)
+            violations.append(
+                f"{rel_path}\\n"
+                f"  Comment ratio: {ratio*100:.1f}% (min: {MIN_COMMENT_RATIO*100:.0f}%)\\n"
+                f"  Suggestion: Add docstrings and inline comments"
+            )
+
+    if violations:
+        pytest.fail(
+            f"\\n\\nFound {len(violations)} files with insufficient comments:\\n\\n" +
+            "\\n\\n".join(violations[:10]) +
+            (f"\\n\\n... and {len(violations) - 10} more" if len(violations) > 10 else "")
+        )
+
+
+@pytest.mark.coder
+def test_no_significant_code_duplication():
+    """
+    SPEC-CODER-QUALITY-0003: No significant code duplication.
+
+    Duplicate code should be extracted into functions.
+
+    Threshold: < 5 consecutive duplicate lines
+
+    Given: All Python files
+    When: Checking for duplicate code blocks
+    Then: No significant duplication found
+    """
+    python_files = find_python_files()
+
+    if not python_files:
+        pytest.skip("No Python files found")
+
+    # Limit to avoid long running time
+    sample_files = python_files[:50]
+
+    duplicates = find_duplicate_code_blocks(sample_files)
+
+    if duplicates:
+        violations = []
+        for file1, file2, block in duplicates[:10]:
+            violations.append(
+                f"{file1.relative_to(REPO_ROOT)} ↔ {file2.relative_to(REPO_ROOT)}\\n"
+                f"  Duplicate block ({len(block)} lines):\\n" +
+                "\\n".join(f"    {line[:60]}" for line in block[:3])
+            )
+
+        pytest.fail(
+            f"\\n\\nFound {len(duplicates)} code duplication instances:\\n\\n" +
+            "\\n\\n".join(violations) +
+            (f"\\n\\n... and {len(duplicates) - 10} more" if len(duplicates) > 10 else "") +
+            "\\n\\nConsider extracting duplicate code into shared functions."
+        )
+
+
+@pytest.mark.coder
+def test_consistent_naming_conventions():
+    """
+    SPEC-CODER-QUALITY-0004: Code follows consistent naming conventions.
+
+    Naming conventions:
+    - Classes: PascalCase
+    - Functions: snake_case
+    - Constants: UPPER_CASE
+    - Variables: snake_case
+
+    Given: All Python files
+    When: Checking naming patterns
+    Then: Consistent naming conventions
+    """
+    python_files = find_python_files()
+
+    if not python_files:
+        pytest.skip("No Python files found")
+
+    all_violations = []
+
+    for py_file in python_files:
+        violations = check_naming_consistency(py_file)
+
+        if violations:
+            rel_path = py_file.relative_to(REPO_ROOT)
+            all_violations.append(
+                f"{rel_path}\\n" +
+                "\\n".join(f"  - {v}" for v in violations[:5])
+            )
+
+    if all_violations:
+        pytest.fail(
+            f"\\n\\nFound {len(all_violations)} files with naming violations:\\n\\n" +
+            "\\n\\n".join(all_violations[:10]) +
+            (f"\\n\\n... and {len(all_violations) - 10} more" if len(all_violations) > 10 else "")
+        )

atdd/coder/validators/test_station_master_pattern.py

@@ -0,0 +1,244 @@
+"""
+Station Master Pattern Validator
+
+Validates that wagons follow the Station Master pattern for monolith composition:
+1. composition.py accepts optional shared dependency parameters
+2. Direct adapters exist for cross-wagon data access
+3. game.py delegates to composition.py instead of duplicating wiring
+
+Convention: atdd/coder/conventions/boundaries.convention.yaml::station_master_pattern
+"""
+
+import ast
+import os
+from pathlib import Path
+from typing import List, Dict, Any, Tuple
+
+
+def get_python_dir() -> Path:
+    """Get the python directory path."""
+    return Path(__file__).parent.parent.parent.parent / "python"
+
+
+def test_composition_accepts_shared_dependencies():
+    """
+    Validate that wagon composition.py files accept optional shared dependencies.
+
+    Convention: boundaries.convention.yaml::station_master_pattern.composition_function_signature
+
+    Expected pattern:
+        def wire_api_dependencies(
+            state_repository=None,
+            player_timebanks=None,
+            match_repository=None,
+            event_bus=None
+        ):
+    """
+    python_dir = get_python_dir()
+
+    # Find all composition.py files in wagon directories
+    composition_files = list(python_dir.glob("*/*/composition.py"))
+
+    # Track which compositions have wire_api_dependencies
+    wagons_with_wire_function: List[str] = []
+    wagons_missing_optional_params: List[Tuple[str, List[str]]] = []
+
+    for comp_file in composition_files:
+        wagon_name = comp_file.parent.parent.name
+
+        try:
+            source = comp_file.read_text()
+            tree = ast.parse(source)
+        except Exception as e:
+            continue  # Skip files that can't be parsed
+
+        # Find wire_api_dependencies function
+        for node in ast.walk(tree):
+            if isinstance(node, ast.FunctionDef) and node.name == "wire_api_dependencies":
+                wagons_with_wire_function.append(wagon_name)
+
+                # Check if it has optional parameters (defaults)
+                # Parameters with defaults are in node.args.defaults
+                # kw_only args with defaults are in node.args.kw_defaults
+
+                # Get all argument names
+                arg_names = [arg.arg for arg in node.args.args]
+
+                # Get number of defaults (these apply to the LAST n arguments)
+                num_defaults = len(node.args.defaults)
+                num_args = len(arg_names)
+
+                # Arguments without defaults (required)
+                required_args = arg_names[:num_args - num_defaults] if num_defaults < num_args else []
+
+                # Recommended optional params for Station Master pattern
+                recommended_optional = ["state_repository", "player_timebanks", "match_repository", "event_bus"]
+
+                # Check if function has any optional parameters
+                optional_count = num_defaults + len([d for d in node.args.kw_defaults if d is not None])
+
+                if optional_count == 0 and num_args > 0:
+                    # Function has only required args - doesn't follow pattern
+                    wagons_missing_optional_params.append((wagon_name, required_args))
+
+    # Report results
+    print("\n" + "=" * 70)
+    print("  Station Master Pattern: Composition Dependencies")
+    print("=" * 70)
+    print(f"\nWagons with wire_api_dependencies(): {len(wagons_with_wire_function)}")
+    for wagon in wagons_with_wire_function:
+        print(f"  ✓ {wagon}")
+
+    if wagons_missing_optional_params:
+        print(f"\n⚠️  Wagons missing optional shared dependency parameters:")
+        for wagon, required in wagons_missing_optional_params:
+            print(f"  ❌ {wagon}: has only required params: {required}")
+        print("\n  Recommendation: Add optional params like state_repository=None")
+
+    # This is a soft check - we want to encourage the pattern but not fail builds
+    # for wagons that don't need cross-wagon data
+    assert True, "Station Master pattern check completed (advisory)"
+
+
+def test_direct_adapters_exist_for_cross_wagon_clients():
+    """
+    Validate that Direct adapters exist alongside HTTP clients for cross-wagon communication.
+
+    Convention: backend.convention.yaml::clients.adapter_variants.direct_adapter
+
+    Expected: If http_*_client.py exists, direct_*_client.py should also exist.
+    """
+    python_dir = get_python_dir()
+
+    # Find all client directories
+    client_dirs = list(python_dir.glob("*/*/src/integration/clients"))
+
+    http_without_direct: List[Tuple[str, str]] = []
+    direct_adapters_found: List[str] = []
+
+    for client_dir in client_dirs:
+        if not client_dir.is_dir():
+            continue
+
+        wagon_name = client_dir.parent.parent.parent.parent.name
+
+        # Find HTTP clients
+        http_clients = list(client_dir.glob("http_*_client.py"))
+
+        for http_client in http_clients:
+            # Extract the service name (e.g., "commit_state" from "http_commit_state_client.py")
+            http_name = http_client.stem  # http_commit_state_client
+            service_name = http_name.replace("http_", "").replace("_client", "")
+
+            # Check for corresponding direct adapter
+            direct_name = f"direct_{service_name}_client.py"
+            direct_path = client_dir / direct_name
+
+            if direct_path.exists():
+                direct_adapters_found.append(f"{wagon_name}/{direct_name}")
+            else:
+                http_without_direct.append((wagon_name, http_client.name))
+
+    # Report results
+    print("\n" + "=" * 70)
+    print("  Station Master Pattern: Direct Adapters")
+    print("=" * 70)
+    print(f"\nDirect adapters found: {len(direct_adapters_found)}")
+    for adapter in direct_adapters_found:
+        print(f"  ✓ {adapter}")
+
+    if http_without_direct:
+        print(f"\n⚠️  HTTP clients without corresponding Direct adapters:")
+        for wagon, http_file in http_without_direct:
+            print(f"  ⚠️  {wagon}/{http_file} → missing direct_*_client.py")
+        print("\n  Note: Direct adapters enable monolith mode without HTTP self-calls")
+
+    # Advisory check - not all HTTP clients need Direct adapters
+    assert True, "Direct adapter check completed (advisory)"
+
+
+def test_game_py_delegates_to_composition():
+    """
+    Validate that game.py delegates wiring to wagon composition.py files
+    instead of duplicating wiring logic.
+
+    Convention: boundaries.convention.yaml::station_master_pattern.station_master_responsibilities
+
+    Forbidden patterns in game.py:
+        - Creating use cases that composition.py should own
+        - Directly instantiating wagon clients without delegation
+
+    Expected patterns:
+        - from wagon.composition import wire_api_dependencies
+        - wire_api_dependencies(state_repository=..., ...)
+    """
+    python_dir = get_python_dir()
+    game_py = python_dir / "game.py"
+
+    if not game_py.exists():
+        print("game.py not found - skipping Station Master delegation check")
+        return
+
+    source = game_py.read_text()
+
+    # Check for composition imports
+    imports_composition = "from play_match.orchestrate_match.composition import wire_api_dependencies" in source
+
+    # Check for delegation calls
+    calls_wire_api = "wire_api_dependencies(" in source
+
+    # Check for forbidden patterns (duplicated wiring)
+    # These are patterns that should be in composition.py, not game.py
+    forbidden_patterns = [
+        ("PlayMatchUseCase(", "PlayMatchUseCase should be created in composition.py"),
+        ("CommitStateClient(mode=", "CommitStateClient mode should be set in composition.py"),
+        ("set_play_match_use_case(PlayMatchUseCase", "Use case creation should be in composition.py"),
+    ]
+
+    violations: List[Tuple[str, str]] = []
+    for pattern, message in forbidden_patterns:
+        if pattern in source:
+            violations.append((pattern, message))
+
+    # Report results
+    print("\n" + "=" * 70)
+    print("  Station Master Pattern: game.py Delegation")
+    print("=" * 70)
+
+    print(f"\nDelegation to composition.py:")
+    print(f"  {'✓' if imports_composition else '❌'} Imports wire_api_dependencies from composition")
+    print(f"  {'✓' if calls_wire_api else '❌'} Calls wire_api_dependencies()")
+
+    if violations:
+        print(f"\n❌ Violations found in game.py:")
+        for pattern, message in violations:
+            print(f"  ❌ {message}")
+            print(f"     Found: {pattern}")
+
+    # This is a real validation
+    assert imports_composition or not calls_wire_api, \
+        "game.py should import wire_api_dependencies from composition.py"
+
+    assert len(violations) == 0, \
+        f"game.py has {len(violations)} Station Master pattern violations"
+
+    print("\n✓ game.py follows Station Master pattern")
+
+
+def main():
+    """Run all Station Master pattern validators."""
+    print("\n" + "=" * 70)
+    print("  STATION MASTER PATTERN VALIDATION")
+    print("=" * 70)
+
+    test_composition_accepts_shared_dependencies()
+    test_direct_adapters_exist_for_cross_wagon_clients()
+    test_game_py_delegates_to_composition()
+
+    print("\n" + "=" * 70)
+    print("  ✓ All Station Master pattern checks passed")
+    print("=" * 70 + "\n")
+
+
+if __name__ == "__main__":
+    main()