evotraders/scripts/verify_docs_consistency.py

#!/usr/bin/env python3
"""Verify documentation and script consistency.

This script checks that:
1. README.md mentions correct service ports
2. start-dev.sh starts services on documented ports
3. deploy/README.md is consistent with production scripts
4. Service ports match across all documentation
"""

from __future__ import annotations

import argparse
import re
import sys
from pathlib import Path

PROJECT_ROOT = Path(__file__).resolve().parents[1]

# Expected service ports (source of truth)
SERVICE_PORTS = {
    "agent_service": 8000,
    "trading_service": 8001,
    "news_service": 8002,
    "runtime_service": 8003,
    "gateway_websocket": 8765,
}


def check_readme_ports() -> list[str]:
    """Check that README.md documents correct ports."""
    errors = []
    readme_path = PROJECT_ROOT / "README.md"
    readme_content = readme_path.read_text(encoding="utf-8")

    # Check for each service port mention
    for service, port in SERVICE_PORTS.items():
        port_patterns = [
            f":{port}",
            f"port {port}",
            f"localhost:{port}",
        ]
        found = any(pattern in readme_content for pattern in port_patterns)
        if not found:
            errors.append(f"README.md: Missing documentation for {service} on port {port}")

    return errors


def check_start_dev_sh_ports() -> list[str]:
    """Check that start-dev.sh uses correct ports."""
    errors = []
    script_path = PROJECT_ROOT / "start-dev.sh"
    script_content = script_path.read_text(encoding="utf-8")

    # Check for port declarations in start_service calls
    for service, port in SERVICE_PORTS.items():
        if service == "gateway_websocket":
            # Gateway uses --port flag
            if f"--port {port}" not in script_content:
                errors.append(f"start-dev.sh: Gateway not using port {port}")
        else:
            # Services use port parameter in start_service
            pattern = rf'start_service\s+"{service}"\s+"[^"]+"\s+{port}'
            if not re.search(pattern, script_content):
                # Also check for explicit port mentions
                if f"port {port}" not in script_content and f":{port}" not in script_content:
                    errors.append(f"start-dev.sh: {service} not using port {port}")

    return errors


def check_deploy_readme_consistency() -> list[str]:
    """Check that deploy/README.md is consistent with scripts."""
    errors = []
    deploy_readme_path = PROJECT_ROOT / "deploy" / "README.md"
    deploy_content = deploy_readme_path.read_text(encoding="utf-8")

    # Check for gateway port consistency
    if "127.0.0.1:8765" not in deploy_content:
        errors.append("deploy/README.md: Gateway port 8765 not documented correctly")

    # Check for production script reference
    if "scripts/run_prod.sh" not in deploy_content:
        errors.append("deploy/README.md: Missing reference to scripts/run_prod.sh")

    return errors


def check_run_prod_sh_ports() -> list[str]:
    """Check that run_prod.sh uses correct ports."""
    errors = []
    script_path = PROJECT_ROOT / "scripts" / "run_prod.sh"
    script_content = script_path.read_text(encoding="utf-8")

    # Production script should use port 8765 for gateway
    if "--port 8765" not in script_content:
        errors.append("scripts/run_prod.sh: Not using gateway port 8765")

    return errors


def check_service_main_blocks() -> list[str]:
    """Check that service modules use correct ports in __main__ blocks."""
    errors = []

    service_files = {
        "agent_service": PROJECT_ROOT / "backend" / "apps" / "agent_service.py",
        "trading_service": PROJECT_ROOT / "backend" / "apps" / "trading_service.py",
        "news_service": PROJECT_ROOT / "backend" / "apps" / "news_service.py",
        "runtime_service": PROJECT_ROOT / "backend" / "apps" / "runtime_service.py",
    }

    for service, file_path in service_files.items():
        if not file_path.exists():
            errors.append(f"{service}: File not found at {file_path}")
            continue

        content = file_path.read_text(encoding="utf-8")
        expected_port = SERVICE_PORTS[service]

        # Check for port= in uvicorn.run or app.run
        if f"port={expected_port}" not in content and f"port= {expected_port}" not in content:
            errors.append(f"{file_path}: Not using expected port {expected_port}")

    return errors


def main() -> int:
    parser = argparse.ArgumentParser(
        description="Verify documentation and script consistency.",
    )
    parser.add_argument(
        "--strict",
        action="store_true",
        help="Treat warnings as errors",
    )
    args = parser.parse_args()

    all_errors = []

    print("Checking README.md ports...")
    all_errors.extend(check_readme_ports())

    print("Checking start-dev.sh ports...")
    all_errors.extend(check_start_dev_sh_ports())

    print("Checking deploy/README.md consistency...")
    all_errors.extend(check_deploy_readme_consistency())

    print("Checking scripts/run_prod.sh ports...")
    all_errors.extend(check_run_prod_sh_ports())

    print("Checking service __main__ blocks...")
    all_errors.extend(check_service_main_blocks())

    if all_errors:
        print("\nConsistency errors found:")
        for error in all_errors:
            print(f"  - {error}")
        return 1 if args.strict else 0
    else:
        print("\nAll consistency checks passed!")
        return 0


if __name__ == "__main__":
    raise SystemExit(main())