devdoctor-cli 0.1.0__py3-none-any.whl

devdoctor/__init__.py

@@ -0,0 +1,40 @@
+"""DevDoctor: Deterministic developer machine and project diagnostic doctor."""
+
+from devdoctor.api import DevDoctor
+from devdoctor.checks.base import Check, check, get_registered_checks, register_check
+from devdoctor.fixer import FixAction, FixPlan, FixResult, Fixer
+from devdoctor.models import (
+    Confidence,
+    Diagnostic,
+    DiagnosticReport,
+    ProjectInfo,
+    ScanContext,
+    Severity,
+)
+from devdoctor.project import detect_project
+from devdoctor.reporter import Reporter
+from devdoctor.scanner import Scanner
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "DevDoctor",
+    "Diagnostic",
+    "DiagnosticReport",
+    "FixAction",
+    "FixPlan",
+    "FixResult",
+    "Fixer",
+    "ProjectInfo",
+    "ScanContext",
+    "Severity",
+    "Confidence",
+    "Check",
+    "check",
+    "register_check",
+    "get_registered_checks",
+    "detect_project",
+    "Reporter",
+    "Scanner",
+    "__version__",
+]

devdoctor/__main__.py

@@ -0,0 +1,7 @@
+"""Allow running DevDoctor directly via python -m devdoctor."""
+
+import sys
+from devdoctor.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

devdoctor/api.py

@@ -0,0 +1,96 @@
+"""Public Python API for DevDoctor programmatic integration."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import List, Optional, Set, Union
+
+from devdoctor.checks.base import Check, check, get_registered_checks, register_check
+from devdoctor.fixer import FixResult, Fixer
+from devdoctor.models import (
+    Confidence,
+    Diagnostic,
+    DiagnosticReport,
+    FixAction,
+    ProjectInfo,
+    ScanContext,
+    Severity,
+)
+from devdoctor.project import detect_project
+from devdoctor.reporter import Reporter
+from devdoctor.scanner import Scanner
+
+
+class DevDoctor:
+    """High-level Python API for running DevDoctor scans, fixes, and inspections programmatically."""
+
+    def __init__(
+        self,
+        project_path: Union[str, Path] = ".",
+        custom_checks_dir: Optional[Union[str, Path]] = None,
+    ):
+        self.project_path = Path(project_path).resolve()
+        self.custom_checks_dir = Path(custom_checks_dir).resolve() if custom_checks_dir else None
+        self.scanner = Scanner(self.project_path, self.custom_checks_dir)
+        self.reporter = Reporter()
+        self.fixer = Fixer()
+
+    def detect_project(self) -> ProjectInfo:
+        """Analyze project files and detect framework/technologies."""
+        return detect_project(self.project_path)
+
+    def scan(
+        self,
+        categories: Optional[List[str]] = None,
+        check_names: Optional[List[str]] = None,
+        include_frameworks: bool = True,
+    ) -> DiagnosticReport:
+        """Run diagnostic scan and return structured report."""
+        cat_set = set(categories) if categories else None
+        chk_set = set(check_names) if check_names else None
+        return self.scanner.scan(
+            categories=cat_set,
+            check_names=chk_set,
+            include_frameworks=include_frameworks,
+        )
+
+    def fix(
+        self,
+        safe_only: bool = False,
+        dry_run: bool = False,
+        auto_yes: bool = True,
+        interactive: bool = False,
+    ) -> FixResult:
+        """Generate and execute fixes for current project diagnostics."""
+        report = self.scan()
+        context = self.scanner.create_context()
+        plan = self.fixer.build_plan(report)
+        return self.fixer.execute_plan(
+            plan=plan,
+            context=context,
+            safe_only=safe_only,
+            dry_run=dry_run,
+            auto_yes=auto_yes,
+            interactive=interactive,
+        )
+
+    def free_port(self, port: int, auto_yes: bool = True) -> bool:
+        """Terminate process occupying the specified port."""
+        return self.fixer.free_port_interactive(port, auto_yes=auto_yes)
+
+
+__all__ = [
+    "DevDoctor",
+    "Diagnostic",
+    "DiagnosticReport",
+    "FixAction",
+    "ProjectInfo",
+    "ScanContext",
+    "Severity",
+    "Confidence",
+    "Check",
+    "check",
+    "register_check",
+    "get_registered_checks",
+    "FixResult",
+]

devdoctor/checks/__init__.py

@@ -0,0 +1,38 @@
+"""DevDoctor built-in diagnostic checks."""
+
+from devdoctor.checks.base import Check, check, get_registered_checks, register_check
+from devdoctor.checks.dependencies import DependencyConflictsCheck
+from devdoctor.checks.django import DjangoCheck
+from devdoctor.checks.docker import DockerCheck
+from devdoctor.checks.environment import EnvironmentCheck
+from devdoctor.checks.fastapi import FastAPICheck
+from devdoctor.checks.filesystem import FilesystemCheck
+from devdoctor.checks.git import GitCheck
+from devdoctor.checks.imports import BrokenImportsCheck
+from devdoctor.checks.pip import PipAvailabilityCheck
+from devdoctor.checks.ports import PortConflictsCheck
+from devdoctor.checks.postgres import PostgresCheck
+from devdoctor.checks.python import PythonVersionCheck
+from devdoctor.checks.redis import RedisCheck
+from devdoctor.checks.virtualenv import VirtualenvCheck
+
+__all__ = [
+    "Check",
+    "check",
+    "register_check",
+    "get_registered_checks",
+    "PythonVersionCheck",
+    "PipAvailabilityCheck",
+    "VirtualenvCheck",
+    "GitCheck",
+    "EnvironmentCheck",
+    "PortConflictsCheck",
+    "FilesystemCheck",
+    "BrokenImportsCheck",
+    "DependencyConflictsCheck",
+    "DjangoCheck",
+    "FastAPICheck",
+    "DockerCheck",
+    "PostgresCheck",
+    "RedisCheck",
+]

devdoctor/checks/base.py

@@ -0,0 +1,69 @@
+"""Base Check interface and check decorator for DevDoctor."""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, List, Optional, Type, Union
+
+from devdoctor.models import Diagnostic, ScanContext
+
+
+class Check:
+    """Base class for all DevDoctor diagnostic checks."""
+    name: str = "base"
+    title: str = "Base Check"
+    description: str = ""
+    category: str = "system"  # system, environment, git, network, dependencies, framework, filesystem
+    enabled: bool = True
+
+    def run(self, context: ScanContext) -> Union[Diagnostic, List[Diagnostic], None]:
+        """Execute the check and return one or more Diagnostics."""
+        raise NotImplementedError("Subclasses must implement run(context)")
+
+
+_GLOBAL_CHECK_REGISTRY: Dict[str, Type[Check]] = {}
+
+
+def register_check(check_cls: Type[Check]) -> Type[Check]:
+    """Register a Check class in the global registry."""
+    if hasattr(check_cls, "name") and check_cls.name:
+        _GLOBAL_CHECK_REGISTRY[check_cls.name] = check_cls
+    return check_cls
+
+
+def get_registered_checks() -> List[Check]:
+    """Return instantiated instances of all registered checks."""
+    return [cls() for cls in _GLOBAL_CHECK_REGISTRY.values() if cls.enabled]
+
+
+def check(
+    name: str,
+    title: Optional[str] = None,
+    category: str = "custom",
+    description: str = "",
+) -> Callable[[Callable[[ScanContext], Any]], Type[Check]]:
+    """Decorator to convert a simple function into a registered DevDoctor Check.
+    
+    Example:
+        @check("my_api", title="My API Check")
+        def check_my_api(context: ScanContext) -> Diagnostic | None:
+            ...
+    """
+    def decorator(fn: Callable[[ScanContext], Any]) -> Type[Check]:
+        check_name = name
+        check_title = title or name.replace("_", " ").title()
+        check_category = category
+        check_desc = description or (fn.__doc__ or "")
+
+        class FunctionalCheck(Check):
+            def run(self, context: ScanContext) -> Any:
+                return fn(context)
+
+        FunctionalCheck.name = check_name
+        FunctionalCheck.title = check_title
+        FunctionalCheck.category = check_category
+        FunctionalCheck.description = check_desc
+
+        register_check(FunctionalCheck)
+        return FunctionalCheck
+
+    return decorator

devdoctor/checks/dependencies.py

@@ -0,0 +1,125 @@
+"""Check Python dependency conflicts and package requirements."""
+
+from __future__ import annotations
+
+import importlib.metadata
+import re
+import subprocess
+import sys
+from typing import List, Optional
+
+from packaging.specifiers import InvalidSpecifier, SpecifierSet
+from packaging.version import InvalidVersion, Version
+
+from devdoctor.checks.base import Check, register_check
+from devdoctor.models import Confidence, Diagnostic, FixAction, ScanContext, Severity
+
+
+@register_check
+class DependencyConflictsCheck(Check):
+    name = "dependency_conflicts"
+    title = "Dependency Conflicts"
+    category = "dependencies"
+    description = "Checks for package version conflicts, broken requirements, and pip check incompatibilities."
+
+    def run(self, context: ScanContext) -> List[Diagnostic]:
+        diagnostics: List[Diagnostic] = []
+
+        # 1. Run pip check for active environment consistency
+        try:
+            res = subprocess.run(
+                [sys.executable, "-m", "pip", "check"],
+                capture_output=True,
+                text=True,
+                timeout=10,
+            )
+            if res.returncode != 0 and res.stdout.strip():
+                for line in res.stdout.strip().splitlines():
+                    line = line.strip()
+                    if not line:
+                        continue
+                    # Format: "pkgA 1.0.0 has requirement pkgB<3.0, but you have pkgB 3.1.0."
+                    match = re.match(r"^(\S+)\s+(\S+)\s+has requirement\s+([^,]+),\s+but you have\s+(\S+)\s+(\S+)\.?", line)
+                    if match:
+                        parent_pkg = match.group(1)
+                        req_spec = match.group(3).strip()
+                        child_pkg = match.group(4)
+                        installed_ver = match.group(5).rstrip(".")
+
+                        # Suggested action
+                        cmd = f'pip install "{req_spec}"'
+                        action = f"Install a compatible version of {child_pkg} matching {req_spec}."
+
+                        evidence = (
+                            f"{parent_pkg} requires:\n     {req_spec}\n\n   "
+                            f"Installed:\n     {child_pkg} {installed_ver}\n\n   "
+                            f"Suggested action:\n     {action}\n\n   "
+                            f"Run:\n     {cmd}"
+                        )
+
+                        diagnostics.append(Diagnostic(
+                            title="Dependency conflict",
+                            severity=Severity.ERROR,
+                            message=f"{parent_pkg} requires {req_spec}, but {child_pkg} {installed_ver} is installed.",
+                            why=f"Incompatible version of {child_pkg} installed in the environment.",
+                            evidence=evidence,
+                            fix=f"Run:\n     {cmd}",
+                            command=cmd,
+                            confidence=Confidence.HIGH,
+                            fix_action=FixAction(
+                                description=f"Align {child_pkg} with {req_spec}",
+                                command=cmd,
+                                safe=False,
+                            ),
+                            check_id=f"{self.name}_{parent_pkg}_{child_pkg}",
+                            metadata={"parent": parent_pkg, "child": child_pkg, "spec": req_spec, "installed": installed_ver},
+                        ))
+                    else:
+                        diagnostics.append(Diagnostic(
+                            title="Dependency conflict",
+                            severity=Severity.ERROR,
+                            message=line,
+                            why="pip check detected an unsatisfied package requirement.",
+                            evidence=line,
+                            fix="Resolve dependencies using pip install.",
+                            confidence=Confidence.HIGH,
+                            check_id=f"{self.name}_pip_check",
+                        ))
+        except Exception:
+            pass
+
+        # 2. Check project declared requirements against installed packages
+        if context.project_info and context.project_info.dependencies:
+            for pkg, spec_str in context.project_info.dependencies.items():
+                if spec_str == "*":
+                    continue
+                try:
+                    installed_ver_str = importlib.metadata.version(pkg)
+                    installed_ver = Version(installed_ver_str)
+                    spec = SpecifierSet(spec_str)
+                    if installed_ver not in spec:
+                        cmd = f'pip install "{pkg}{spec_str}"'
+                        evidence = f"{pkg} declared as: {spec_str}\nInstalled: {installed_ver_str}"
+                        diagnostics.append(Diagnostic(
+                            title=f"Mismatched package version: {pkg}",
+                            severity=Severity.ERROR,
+                            message=f"{pkg} requires {spec_str}, but installed version is {installed_ver_str}.",
+                            why=f"The project configuration specifies '{pkg}{spec_str}', but the active environment has {installed_ver_str}.",
+                            evidence=evidence,
+                            fix=f"Reinstall compatible version:\n     {cmd}",
+                            command=cmd,
+                            confidence=Confidence.HIGH,
+                            fix_action=FixAction(
+                                description=f"Install {pkg}{spec_str}",
+                                command=cmd,
+                                safe=False,
+                            ),
+                            check_id=f"{self.name}_spec_{pkg}",
+                        ))
+                except importlib.metadata.PackageNotFoundError:
+                    # Missing package will also be caught or highlighted here
+                    pass
+                except (InvalidSpecifier, InvalidVersion):
+                    pass
+
+        return diagnostics

devdoctor/checks/django.py

@@ -0,0 +1,128 @@
+"""Django framework diagnostic checks."""
+
+from __future__ import annotations
+
+import re
+import subprocess
+import sys
+from pathlib import Path
+from typing import List
+
+from devdoctor.checks.base import Check, register_check
+from devdoctor.models import Confidence, Diagnostic, FixAction, ScanContext, Severity
+
+
+@register_check
+class DjangoCheck(Check):
+    name = "django"
+    title = "Django Framework Diagnostics"
+    category = "framework"
+    description = "Checks Django security settings, secret key, allowed hosts, and migration state."
+
+    def run(self, context: ScanContext) -> List[Diagnostic]:
+        diagnostics: List[Diagnostic] = []
+        root = context.project_path
+
+        manage_py = root / "manage.py"
+        is_django = manage_py.is_file() or (context.project_info and "Django" in context.project_info.frameworks)
+
+        if not is_django:
+            return diagnostics
+
+        # Search for settings.py
+        settings_files = list(root.glob("**/settings.py"))
+        # Filter out venvs
+        settings_files = [f for f in settings_files if not any(x in f.parts for x in [".venv", "venv", "build"])]
+
+        for sf in settings_files:
+            try:
+                content = sf.read_text(encoding="utf-8", errors="replace")
+                rel_path = sf.relative_to(root)
+
+                # 1. DEBUG = True check
+                if re.search(r"^\s*DEBUG\s*=\s*True", content, re.MULTILINE):
+                    diagnostics.append(Diagnostic(
+                        title="Django DEBUG is True",
+                        severity=Severity.WARNING,
+                        message="DEBUG is set to True in Django settings.",
+                        why="Running with DEBUG=True in production exposes sensitive tracebacks, settings, and database schema to users.",
+                        evidence=f"Found in:\n     {rel_path}",
+                        fix="Set DEBUG via environment variable:\n     DEBUG = os.getenv('DJANGO_DEBUG', 'False').lower() in ('true', '1')",
+                        confidence=Confidence.HIGH,
+                        check_id=f"{self.name}_debug_true",
+                        metadata={"file": str(rel_path)},
+                    ))
+
+                # 2. Insecure SECRET_KEY check
+                if "django-insecure-" in content:
+                    diagnostics.append(Diagnostic(
+                        title="Insecure Django SECRET_KEY",
+                        severity=Severity.WARNING,
+                        message="SECRET_KEY appears to be using the default development value.",
+                        why="Using a hardcoded or django-insecure secret key compromises session signing and CSRF tokens.",
+                        evidence=f"Found in:\n     {rel_path}",
+                        fix="Load SECRET_KEY from environment:\n     SECRET_KEY = os.environ['DJANGO_SECRET_KEY']",
+                        confidence=Confidence.HIGH,
+                        check_id=f"{self.name}_secret_key",
+                        metadata={"file": str(rel_path)},
+                    ))
+
+                # 3. ALLOWED_HOSTS check
+                allowed_match = re.search(r"^\s*ALLOWED_HOSTS\s*=\s*\[(.*?)\]", content, re.MULTILINE | re.DOTALL)
+                if allowed_match:
+                    hosts_inner = allowed_match.group(1).strip()
+                    if not hosts_inner:
+                        diagnostics.append(Diagnostic(
+                            title="Django ALLOWED_HOSTS is empty",
+                            severity=Severity.WARNING,
+                            message="ALLOWED_HOSTS is empty.",
+                            why="When DEBUG is False, an empty ALLOWED_HOSTS list will block all incoming HTTP requests.",
+                            evidence=f"Found in:\n     {rel_path}",
+                            fix="Configure ALLOWED_HOSTS:\n     ALLOWED_HOSTS = ['localhost', '127.0.0.1']",
+                            confidence=Confidence.HIGH,
+                            check_id=f"{self.name}_allowed_hosts",
+                            metadata={"file": str(rel_path)},
+                        ))
+            except Exception:
+                pass
+
+        # 4. Check migrations if manage.py is present
+        if manage_py.is_file():
+            try:
+                res = subprocess.run(
+                    [sys.executable, str(manage_py), "showmigrations", "--plan"],
+                    capture_output=True,
+                    text=True,
+                    timeout=8,
+                    cwd=str(root),
+                )
+                if res.returncode == 0:
+                    unapplied = [line for line in res.stdout.splitlines() if "[ ]" in line]
+                    if unapplied:
+                        diagnostics.append(Diagnostic(
+                            title="Unapplied Django migrations",
+                            severity=Severity.WARNING,
+                            message=f"{len(unapplied)} unapplied database migration(s) detected.",
+                            why="Running without applied migrations causes database errors or missing tables.",
+                            evidence="\n     ".join(unapplied[:3]),
+                            fix="Apply migrations:\n     python manage.py migrate",
+                            command=f"{sys.executable} manage.py migrate",
+                            confidence=Confidence.HIGH,
+                            fix_action=FixAction(
+                                description="Run python manage.py migrate",
+                                command=f"{sys.executable} manage.py migrate",
+                                safe=False,
+                            ),
+                            check_id=f"{self.name}_migrations",
+                        ))
+                    else:
+                        diagnostics.append(Diagnostic(
+                            title="Django migrations",
+                            severity=Severity.OK,
+                            message="Migrations are up to date.",
+                            check_id=f"{self.name}_migrations_ok",
+                        ))
+            except Exception:
+                pass
+
+        return diagnostics

devdoctor/checks/docker.py

@@ -0,0 +1,124 @@
+"""Docker daemon, container health, and port collision diagnostics."""
+
+from __future__ import annotations
+
+import re
+import subprocess
+from typing import List
+
+from devdoctor.checks.base import Check, register_check
+from devdoctor.models import Confidence, Diagnostic, ScanContext, Severity
+
+
+@register_check
+class DockerCheck(Check):
+    name = "docker"
+    title = "Docker Diagnostics"
+    category = "framework"
+    description = "Checks Docker daemon accessibility, exited container states, and compose service ports."
+
+    def run(self, context: ScanContext) -> List[Diagnostic]:
+        diagnostics: List[Diagnostic] = []
+        is_docker_project = context.project_info and "Docker" in context.project_info.technologies
+
+        # 1. Check docker CLI
+        try:
+            res_ver = subprocess.run(["docker", "--version"], capture_output=True, text=True, timeout=4)
+            if res_ver.returncode != 0:
+                if is_docker_project:
+                    diagnostics.append(Diagnostic(
+                        title="Docker CLI unavailable",
+                        severity=Severity.ERROR,
+                        message="Project uses Docker, but 'docker' command is not available in PATH.",
+                        why="Dockerfile or docker-compose is present, but Docker CLI is not installed.",
+                        fix="Install Docker Desktop from https://www.docker.com/products/docker-desktop/.",
+                        confidence=Confidence.HIGH,
+                        check_id=f"{self.name}_cli_missing",
+                    ))
+                return diagnostics
+
+            match = re.search(r"Docker version\s+([0-9.]+)", res_ver.stdout)
+            ver = match.group(1) if match else "available"
+            diagnostics.append(Diagnostic(
+                title=f"Docker {ver}",
+                severity=Severity.OK,
+                message=f"Docker CLI is installed and available (version {ver}).",
+                check_id=f"{self.name}_version",
+            ))
+
+        except Exception:
+            if is_docker_project:
+                diagnostics.append(Diagnostic(
+                    title="Docker CLI unavailable",
+                    severity=Severity.ERROR,
+                    message="Docker CLI is not found in PATH.",
+                    fix="Install Docker Desktop and ensure it is in your PATH.",
+                    confidence=Confidence.HIGH,
+                    check_id=f"{self.name}_cli_missing",
+                ))
+            return diagnostics
+
+        # 2. Check Docker daemon running
+        try:
+            res_info = subprocess.run(["docker", "info"], capture_output=True, text=True, timeout=5)
+            if res_info.returncode != 0:
+                diagnostics.append(Diagnostic(
+                    title="Docker daemon not running",
+                    severity=Severity.ERROR,
+                    message="Docker daemon is stopped or inaccessible.",
+                    why="The docker client cannot communicate with the Docker daemon engine.",
+                    evidence=res_info.stderr.strip()[:200] if res_info.stderr else "Connection refused",
+                    fix="Start Docker Desktop or run 'sudo systemctl start docker'.",
+                    confidence=Confidence.HIGH,
+                    check_id=f"{self.name}_daemon_stopped",
+                ))
+                return diagnostics
+            else:
+                diagnostics.append(Diagnostic(
+                    title="Docker daemon running",
+                    severity=Severity.OK,
+                    message="Docker engine is healthy and accepting commands.",
+                    check_id=f"{self.name}_daemon_ok",
+                ))
+        except Exception:
+            diagnostics.append(Diagnostic(
+                title="Docker daemon unreachable",
+                severity=Severity.WARNING,
+                message="Timed out communicating with Docker daemon.",
+                fix="Ensure Docker Desktop is active.",
+                check_id=f"{self.name}_daemon_timeout",
+            ))
+            return diagnostics
+
+        # 3. Check for crashed or failed exited containers
+        try:
+            res_ps = subprocess.run(
+                ["docker", "ps", "-a", "--filter", "status=exited", "--format", "{{.Names}}\t{{.Status}}"],
+                capture_output=True,
+                text=True,
+                timeout=5,
+            )
+            if res_ps.returncode == 0 and res_ps.stdout.strip():
+                for line in res_ps.stdout.strip().splitlines():
+                    parts = line.split("\t")
+                    if len(parts) >= 2:
+                        name, status = parts[0], parts[1]
+                        # e.g. "Exited (1) 2 minutes ago"
+                        match_code = re.search(r"Exited\s+\((\d+)\)", status)
+                        if match_code and match_code.group(1) != "0":
+                            code = match_code.group(1)
+                            diagnostics.append(Diagnostic(
+                                title=f"Container {name} crashed",
+                                severity=Severity.ERROR,
+                                message=f"Container '{name}' exited with error code {code}.",
+                                why=f"Container process terminated abnormally ({status}).",
+                                evidence=f"Container: {name} | Status: {status}",
+                                fix=f"Inspect container logs:\n     docker logs {name}",
+                                command=f"docker logs {name}",
+                                confidence=Confidence.HIGH,
+                                check_id=f"{self.name}_container_{name}",
+                            ))
+        except Exception:
+            pass
+
+        return diagnostics