devdoctor-cli 0.1.0__py3-none-any.whl

devdoctor/fixer.py

@@ -0,0 +1,160 @@
+"""Fix engine for DevDoctor: safe automatic fixes vs action-required fixes."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import List, Optional
+
+from rich.console import Console
+from rich.prompt import Confirm
+
+from devdoctor.models import Diagnostic, DiagnosticReport, FixAction, ScanContext
+from devdoctor.utils.process_utils import free_port, get_port_listener_info
+
+
+@dataclass
+class FixItem:
+    """A single diagnostic that has an executable fix."""
+    diagnostic: Diagnostic
+    action: FixAction
+
+    @property
+    def is_safe(self) -> bool:
+        return self.action.safe
+
+    @property
+    def description(self) -> str:
+        return self.action.description or self.diagnostic.fix or "Apply suggested fix"
+
+
+@dataclass
+class FixPlan:
+    """A collection of fixes ready for review or execution."""
+    items: List[FixItem] = field(default_factory=list)
+
+    @property
+    def safe_items(self) -> List[FixItem]:
+        return [i for i in self.items if i.is_safe]
+
+    @property
+    def action_items(self) -> List[FixItem]:
+        return [i for i in self.items if not i.is_safe]
+
+    @property
+    def total_count(self) -> int:
+        return len(self.items)
+
+
+@dataclass
+class FixResult:
+    """Outcome of applying a fix plan."""
+    applied: List[FixItem] = field(default_factory=list)
+    failed: List[FixItem] = field(default_factory=list)
+    skipped: List[FixItem] = field(default_factory=list)
+
+
+class Fixer:
+    """Coordinates deterministic, safe fix application."""
+
+    def __init__(self, console: Optional[Console] = None):
+        self.console = console or Console()
+
+    def build_plan(self, report: DiagnosticReport) -> FixPlan:
+        """Create a FixPlan from report diagnostics that have fix actions."""
+        items: List[FixItem] = []
+        for d in report.problems:
+            if d.fix_action:
+                items.append(FixItem(diagnostic=d, action=d.fix_action))
+        return FixPlan(items=items)
+
+    def execute_plan(
+        self,
+        plan: FixPlan,
+        context: ScanContext,
+        safe_only: bool = False,
+        dry_run: bool = False,
+        auto_yes: bool = False,
+        interactive: bool = True,
+    ) -> FixResult:
+        """Execute or preview fixes in the plan."""
+        result = FixResult()
+
+        if plan.total_count == 0:
+            self.console.print("[dim]No automated fixes available for identified problems.[/dim]")
+            return result
+
+        candidates = plan.safe_items if safe_only else plan.items
+
+        if not candidates:
+            self.console.print("[yellow]No safe automatic fixes found. Remaining fixes require manual confirmation.[/yellow]")
+            return result
+
+        self.console.print(f"[bold cyan]Found {len(candidates)} problem(s) with available fixes:[/bold cyan]\n")
+        for i, item in enumerate(candidates, start=1):
+            badge = "[green][SAFE][/green]" if item.is_safe else "[yellow][ACTION][/yellow]"
+            self.console.print(f" {i}. {badge} {item.description}")
+            if item.action.command:
+                self.console.print(f"    [dim]Command: {item.action.command}[/dim]")
+
+        self.console.print()
+
+        if dry_run:
+            self.console.print("[bold yellow][DRY RUN] No changes were made to your machine or project.[/bold yellow]")
+            return result
+
+        # Confirm if interactive and not auto_yes and not safe_only
+        if interactive and not auto_yes and not safe_only:
+            try:
+                proceed = Confirm.ask("Apply fixes?", default=True)
+                if not proceed:
+                    self.console.print("[dim]Aborted by user. No fixes applied.[/dim]")
+                    result.skipped.extend(candidates)
+                    return result
+            except (KeyboardInterrupt, EOFError):
+                self.console.print("\n[dim]Aborted.[/dim]")
+                return result
+
+        # Apply fixes
+        self.console.print("\n[bold]Applying fixes...[/bold]\n")
+        for item in candidates:
+            try:
+                success = item.action.execute(context)
+                if success:
+                    self.console.print(f"[green]✓ Fixed:[/green] {item.description}")
+                    result.applied.append(item)
+                else:
+                    self.console.print(f"[red]❌ Failed:[/red] {item.description}")
+                    result.failed.append(item)
+            except Exception as e:
+                self.console.print(f"[red]❌ Error fixing {item.description}:[/red] {e}")
+                result.failed.append(item)
+
+        self.console.print(f"\n[bold green]Completed:[/bold green] {len(result.applied)} applied, {len(result.failed)} failed.")
+        return result
+
+    def free_port_interactive(self, port: int, auto_yes: bool = False) -> bool:
+        """Safely free an occupied port."""
+        info = get_port_listener_info(port)
+        if not info or info.pid <= 0:
+            self.console.print(f"[green]✓ Port {port} is already free.[/green]")
+            return True
+
+        self.console.print(f"[yellow]Port {port} is occupied by {info.process_name} (PID: {info.pid}).[/yellow]")
+        if not auto_yes:
+            try:
+                proceed = Confirm.ask(f"Terminate process {info.process_name} (PID: {info.pid})?", default=False)
+                if not proceed:
+                    self.console.print("[dim]Action cancelled.[/dim]")
+                    return False
+            except (KeyboardInterrupt, EOFError):
+                self.console.print("\n[dim]Cancelled.[/dim]")
+                return False
+
+        freed = free_port(port)
+        if freed:
+            self.console.print(f"[bold green]✓ Port {port} has been freed.[/bold green]")
+            return True
+        else:
+            self.console.print(f"[bold red]❌ Failed to terminate process on port {port}. Run with elevated permissions if required.[/bold red]")
+            return False

devdoctor/models.py

@@ -0,0 +1,257 @@
+"""Core data models for DevDoctor diagnostics, reports, and fix actions."""
+
+from __future__ import annotations
+
+import os
+import sys
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from enum import Enum
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional
+
+
+class Severity(str, Enum):
+    """Diagnostic severity levels."""
+    OK = "ok"
+    INFO = "info"
+    WARNING = "warning"
+    ERROR = "error"
+
+
+class Confidence(str, Enum):
+    """Confidence rating for diagnostic conclusions."""
+    HIGH = "HIGH"
+    MEDIUM = "MEDIUM"
+    LOW = "LOW"
+
+
+@dataclass
+class FixAction:
+    """An executable or proposed fix action for an identified problem."""
+    description: str
+    command: Optional[str] = None
+    safe: bool = True
+    action_type: str = "command"  # "command", "file_create", "file_append", "kill_process", "custom"
+    target_path: Optional[Path] = None
+    content: Optional[str] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    handler: Optional[Callable[[ScanContext], bool]] = None
+
+    def execute(self, context: ScanContext) -> bool:
+        """Execute the fix safely."""
+        if self.handler:
+            return self.handler(context)
+
+        if self.action_type == "file_create" and self.target_path:
+            if not self.target_path.exists():
+                self.target_path.parent.mkdir(parents=True, exist_ok=True)
+                self.target_path.write_text(self.content or "", encoding="utf-8")
+                return True
+            return False
+
+        if self.action_type == "file_append" and self.target_path:
+            self.target_path.parent.mkdir(parents=True, exist_ok=True)
+            current = self.target_path.read_text(encoding="utf-8") if self.target_path.exists() else ""
+            if self.content and self.content not in current:
+                with open(self.target_path, "a", encoding="utf-8") as f:
+                    if current and not current.endswith("\n"):
+                        f.write("\n")
+                    f.write(self.content + "\n")
+                return True
+            return False
+
+        if self.action_type == "kill_process" and "pid" in self.metadata:
+            pid = int(self.metadata["pid"])
+            from devdoctor.utils.process_utils import kill_process_by_pid
+            return kill_process_by_pid(pid)
+
+        if self.action_type == "command" and self.command:
+            import subprocess
+            try:
+                subprocess.run(self.command, shell=True, check=True, cwd=str(context.project_path))
+                return True
+            except Exception:
+                return False
+
+        return False
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "description": self.description,
+            "command": self.command,
+            "safe": self.safe,
+            "action_type": self.action_type,
+            "target_path": str(self.target_path) if self.target_path else None,
+            "metadata": self.metadata,
+        }
+
+
+@dataclass
+class Diagnostic:
+    """Represents a single diagnostic result from a check."""
+    title: str
+    severity: Severity = Severity.OK
+    message: str = ""
+    why: Optional[str] = None
+    evidence: Optional[str] = None
+    fix: Optional[str] = None
+    command: Optional[str] = None
+    confidence: Confidence = Confidence.HIGH
+    fix_action: Optional[FixAction] = None
+    check_id: Optional[str] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def is_ok(self) -> bool:
+        return self.severity == Severity.OK
+
+    @property
+    def is_warning(self) -> bool:
+        return self.severity == Severity.WARNING
+
+    @property
+    def is_error(self) -> bool:
+        return self.severity == Severity.ERROR
+
+    @property
+    def is_problem(self) -> bool:
+        return self.severity in (Severity.WARNING, Severity.ERROR)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "title": self.title,
+            "severity": self.severity.value,
+            "message": self.message,
+            "why": self.why,
+            "evidence": self.evidence,
+            "fix": self.fix,
+            "command": self.command,
+            "confidence": self.confidence.value,
+            "check_id": self.check_id,
+            "has_fix": self.fix_action is not None,
+            "fix_action": self.fix_action.to_dict() if self.fix_action else None,
+            "metadata": self.metadata,
+        }
+
+
+@dataclass
+class ProjectInfo:
+    """Metadata regarding the project under inspection."""
+    root: Path
+    name: str = "project"
+    project_type: Optional[str] = None
+    technologies: List[str] = field(default_factory=list)
+    frameworks: List[str] = field(default_factory=list)
+    config_files: List[str] = field(default_factory=list)
+    dependencies: Dict[str, str] = field(default_factory=dict)
+
+    @property
+    def summary_stack(self) -> str:
+        """Returns readable tech stack string like 'Django + PostgreSQL + Redis'."""
+        items = []
+        if self.project_type and self.project_type not in ("Generic Python", "Unknown"):
+            items.append(self.project_type)
+        for t in self.technologies:
+            if t not in items and t.lower() != "python":
+                items.append(t)
+        return " + ".join(items) if items else (self.project_type or "Python Project")
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "root": str(self.root),
+            "name": self.name,
+            "project_type": self.project_type,
+            "technologies": self.technologies,
+            "frameworks": self.frameworks,
+            "config_files": self.config_files,
+            "dependencies_count": len(self.dependencies),
+            "summary_stack": self.summary_stack,
+        }
+
+
+@dataclass
+class ScanContext:
+    """Context passed to each diagnostic check during scanning."""
+    project_path: Path
+    python_executable: str = field(default_factory=lambda: sys.executable)
+    python_version: str = field(default_factory=lambda: f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}")
+    is_venv: bool = False
+    project_info: Optional[ProjectInfo] = None
+    env_vars: Dict[str, str] = field(default_factory=dict)
+    cache: Dict[str, Any] = field(default_factory=dict)
+
+    def get_cached(self, key: str, default: Any = None) -> Any:
+        return self.cache.get(key, default)
+
+    def set_cached(self, key: str, value: Any) -> None:
+        self.cache[key] = value
+
+
+@dataclass
+class DiagnosticReport:
+    """Comprehensive diagnostic run report."""
+    project_path: Path
+    project_info: ProjectInfo
+    diagnostics: List[Diagnostic] = field(default_factory=list)
+    timestamp: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+    duration_ms: float = 0.0
+
+    @property
+    def passed(self) -> List[Diagnostic]:
+        return [d for d in self.diagnostics if d.is_ok]
+
+    @property
+    def warnings(self) -> List[Diagnostic]:
+        return [d for d in self.diagnostics if d.is_warning]
+
+    @property
+    def errors(self) -> List[Diagnostic]:
+        return [d for d in self.diagnostics if d.is_error]
+
+    @property
+    def problems(self) -> List[Diagnostic]:
+        return [d for d in self.diagnostics if d.is_problem]
+
+    @property
+    def total_problems(self) -> int:
+        return len(self.problems)
+
+    @property
+    def is_healthy(self) -> bool:
+        return len(self.errors) == 0
+
+    @property
+    def score(self) -> int:
+        """Deterministic health score from 0 to 100.
+        
+        Formula:
+        Base 100.
+        Each error subtracts 12 points.
+        Each warning subtracts 4 points.
+        Clamped to [0, 100].
+        If no problems exist, score is 100.
+        """
+        if not self.problems:
+            return 100
+        penalty = (len(self.errors) * 12) + (len(self.warnings) * 4)
+        return max(0, min(100, 100 - penalty))
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "version": "0.1.0",
+            "timestamp": self.timestamp.isoformat(),
+            "duration_ms": round(self.duration_ms, 2),
+            "score": self.score,
+            "healthy": self.is_healthy,
+            "project_path": str(self.project_path),
+            "project": self.project_info.to_dict(),
+            "summary": {
+                "total": len(self.diagnostics),
+                "passed": len(self.passed),
+                "warnings": len(self.warnings),
+                "errors": len(self.errors),
+                "problems": self.total_problems,
+            },
+            "diagnostics": [d.to_dict() for d in self.diagnostics],
+        }

devdoctor/plugin.py

@@ -0,0 +1,89 @@
+"""Plugin discovery and check extension loader."""
+
+from __future__ import annotations
+
+import importlib.metadata
+import importlib.util
+import logging
+from pathlib import Path
+from typing import List, Optional
+
+from devdoctor.checks import get_registered_checks
+from devdoctor.checks.base import Check, register_check
+
+logger = logging.getLogger("devdoctor.plugins")
+
+
+def load_entrypoint_checks() -> List[Check]:
+    """Discover checks registered via Python packaging entry-points ('devdoctor.checks')."""
+    discovered: List[Check] = []
+    try:
+        eps = importlib.metadata.entry_points()
+        if hasattr(eps, "select"):
+            check_eps = eps.select(group="devdoctor.checks")
+        else:
+            check_eps = eps.get("devdoctor.checks", [])
+
+        for ep in check_eps:
+            try:
+                obj = ep.load()
+                if isinstance(obj, type) and issubclass(obj, Check):
+                    register_check(obj)
+                    discovered.append(obj())
+                elif callable(obj):
+                    # Check factory
+                    inst = obj()
+                    if isinstance(inst, Check):
+                        discovered.append(inst)
+            except Exception as e:
+                logger.debug(f"Failed to load entry point {ep.name}: {e}")
+    except Exception as e:
+        logger.debug(f"Error querying entry points: {e}")
+
+    return discovered
+
+
+def load_local_checks(checks_dir: Path) -> List[Check]:
+    """Load custom check modules from a local directory (e.g. .devdoctor/checks/*.py)."""
+    custom_checks: List[Check] = []
+    if not checks_dir.is_dir():
+        return custom_checks
+
+    for py_file in checks_dir.glob("*.py"):
+        if py_file.name.startswith("_"):
+            continue
+        try:
+            spec = importlib.util.spec_from_file_location(f"devdoctor_local_{py_file.stem}", py_file)
+            if spec and spec.loader:
+                mod = importlib.util.module_from_spec(spec)
+                spec.loader.exec_module(mod)
+                for attr_name in dir(mod):
+                    val = getattr(mod, attr_name)
+                    if isinstance(val, type) and issubclass(val, Check) and val is not Check:
+                        register_check(val)
+                        custom_checks.append(val())
+        except Exception as e:
+            logger.debug(f"Failed to load local check from {py_file}: {e}")
+
+    return custom_checks
+
+
+def discover_all_checks(project_path: Optional[Path] = None, custom_dir: Optional[Path] = None) -> List[Check]:
+    """Collect all builtin, entrypoint, and local directory checks."""
+    # 1. Built-in checks
+    all_checks = list(get_registered_checks())
+
+    # 2. Package entry points
+    load_entrypoint_checks()
+
+    # 3. Project-local .devdoctor/checks/
+    if project_path:
+        local_dir = project_path / ".devdoctor" / "checks"
+        if local_dir.is_dir():
+            load_local_checks(local_dir)
+
+    # 4. Explicit custom directory if provided
+    if custom_dir and custom_dir.is_dir():
+        load_local_checks(custom_dir)
+
+    return get_registered_checks()