devdoctor-cli 0.1.0__py3-none-any.whl

devdoctor/utils/ast_imports.py

@@ -0,0 +1,205 @@
+"""AST-based inspection for Python imports and environment variable accesses."""
+
+from __future__ import annotations
+
+import ast
+import importlib.util
+import os
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Dict, List, Optional, Set, Tuple
+
+SYSTEM_ENV_VARS = {
+    "PATH", "PYTHONPATH", "VIRTUAL_ENV", "CONDA_PREFIX", "HOME", "USER",
+    "USERNAME", "USERPROFILE", "APPDATA", "LOCALAPPDATA", "TEMP", "TMP",
+    "OS", "SHELL", "TERM", "LANG", "LC_ALL", "SYSTEMROOT", "WINDIR",
+}
+
+IGNORE_DIRS = {
+    ".venv", "venv", "env", ".env_dir", ".git", ".tox", ".pytest_cache",
+    "__pycache__", "node_modules", "dist", "build", ".eggs", ".mypy_cache"
+}
+
+
+@dataclass
+class ImportUsage:
+    """Record of a module import in a Python file."""
+    module_name: str
+    file_path: Path
+    line_number: int
+
+
+@dataclass
+class EnvVarUsage:
+    """Record of an environment variable read in a Python file."""
+    var_name: str
+    file_path: Path
+    line_number: int
+    has_default: bool
+    is_required: bool  # True if subscript like os.environ['VAR']
+
+
+def should_skip_path(path: Path) -> bool:
+    """Check if the path is within an ignored directory."""
+    for part in path.parts:
+        if part in IGNORE_DIRS:
+            return True
+    return False
+
+
+def collect_python_files(project_path: Path, max_files: int = 500) -> List[Path]:
+    """Find Python source files in the project, ignoring virtualenvs and caches."""
+    py_files: List[Path] = []
+    try:
+        for root, dirs, files in os.walk(project_path):
+            dirs[:] = [d for d in dirs if d not in IGNORE_DIRS]
+            for file in files:
+                if file.endswith(".py"):
+                    full_path = Path(root) / file
+                    py_files.append(full_path)
+                    if len(py_files) >= max_files:
+                        return py_files
+    except Exception:
+        pass
+    return py_files
+
+
+class SourceVisitor(ast.NodeVisitor):
+    """AST visitor that collects imported top-level modules and environment variable lookups."""
+
+    def __init__(self, file_path: Path):
+        self.file_path = file_path
+        self.imports: List[ImportUsage] = []
+        self.env_vars: List[EnvVarUsage] = []
+
+    def visit_Import(self, node: ast.Import):
+        for alias in node.names:
+            top_level = alias.name.split(".")[0]
+            self.imports.append(ImportUsage(module_name=top_level, file_path=self.file_path, line_number=node.lineno))
+        self.generic_visit(node)
+
+    def visit_ImportFrom(self, node: ast.ImportFrom):
+        if node.level == 0 and node.module:
+            top_level = node.module.split(".")[0]
+            self.imports.append(ImportUsage(module_name=top_level, file_path=self.file_path, line_number=node.lineno))
+        self.generic_visit(node)
+
+    def visit_Subscript(self, node: ast.Subscript):
+        # Detect os.environ['VAR'] or environ['VAR'] -> strictly required, throws KeyError if missing
+        var_name = None
+        if isinstance(node.value, ast.Attribute) and node.value.attr == "environ":
+            var_name = self._extract_string_value(node.slice)
+        elif isinstance(node.value, ast.Name) and node.value.id == "environ":
+            var_name = self._extract_string_value(node.slice)
+
+        if var_name and var_name not in SYSTEM_ENV_VARS:
+            self.env_vars.append(EnvVarUsage(
+                var_name=var_name,
+                file_path=self.file_path,
+                line_number=node.lineno,
+                has_default=False,
+                is_required=True,
+            ))
+        self.generic_visit(node)
+
+    def visit_Call(self, node: ast.Call):
+        # Detect os.getenv('VAR', default) or os.environ.get('VAR', default)
+        var_name = None
+        has_default = len(node.args) > 1 or any(kw.arg == "default" for kw in node.keywords)
+
+        if isinstance(node.func, ast.Attribute):
+            if node.func.attr == "getenv" and isinstance(node.func.value, ast.Name) and node.func.value.id == "os":
+                if node.args:
+                    var_name = self._extract_string_value(node.args[0])
+            elif node.func.attr == "get" and isinstance(node.func.value, ast.Attribute) and node.func.value.attr == "environ":
+                if node.args:
+                    var_name = self._extract_string_value(node.args[0])
+            elif node.func.attr == "get" and isinstance(node.func.value, ast.Name) and node.func.value.id == "environ":
+                if node.args:
+                    var_name = self._extract_string_value(node.args[0])
+        elif isinstance(node.func, ast.Name) and node.func.id == "getenv":
+            if node.args:
+                var_name = self._extract_string_value(node.args[0])
+
+        if var_name and var_name not in SYSTEM_ENV_VARS:
+            self.env_vars.append(EnvVarUsage(
+                var_name=var_name,
+                file_path=self.file_path,
+                line_number=node.lineno,
+                has_default=has_default,
+                is_required=not has_default,
+            ))
+
+        self.generic_visit(node)
+
+    def _extract_string_value(self, node: ast.AST) -> Optional[str]:
+        if isinstance(node, ast.Constant) and isinstance(node.value, str):
+            return node.value
+        return None
+
+
+def scan_project_ast(project_path: Path) -> Tuple[List[ImportUsage], List[EnvVarUsage]]:
+    """Scan all Python files in the project for imports and environment variable references."""
+    py_files = collect_python_files(project_path)
+    all_imports: List[ImportUsage] = []
+    all_env_vars: List[EnvVarUsage] = []
+
+    for file_path in py_files:
+        try:
+            source = file_path.read_text(encoding="utf-8", errors="replace")
+            tree = ast.parse(source, filename=str(file_path))
+            visitor = SourceVisitor(file_path)
+            visitor.visit(tree)
+            all_imports.extend(visitor.imports)
+            all_env_vars.extend(visitor.env_vars)
+        except Exception:
+            continue
+
+    return all_imports, all_env_vars
+
+
+def is_local_module(module_name: str, project_path: Path) -> bool:
+    """Check if the module corresponds to a local file or package within the project."""
+    if (project_path / f"{module_name}.py").is_file():
+        return True
+    if (project_path / module_name / "__init__.py").is_file():
+        return True
+    src_dir = project_path / "src"
+    if src_dir.is_dir():
+        if (src_dir / f"{module_name}.py").is_file():
+            return True
+        if (src_dir / module_name / "__init__.py").is_file():
+            return True
+    return False
+
+
+def is_stdlib_module(module_name: str) -> bool:
+    """Check if the module is part of Python's standard library."""
+    if hasattr(sys, "stdlib_module_names"):
+        return module_name in sys.stdlib_module_names
+    return module_name in sys.builtin_module_names
+
+
+def find_missing_installed_imports(project_path: Path) -> List[Tuple[str, Path, int]]:
+    """Identify third-party imports in project code that are not installed in the active environment."""
+    imports, _ = scan_project_ast(project_path)
+    missing: List[Tuple[str, Path, int]] = []
+    checked: Set[str] = set()
+
+    for item in imports:
+        mod = item.module_name
+        if mod in checked:
+            continue
+        if is_stdlib_module(mod) or is_local_module(mod, project_path):
+            continue
+
+        checked.add(mod)
+        try:
+            spec = importlib.util.find_spec(mod)
+            if spec is None:
+                missing.append((mod, item.file_path, item.line_number))
+        except Exception:
+            missing.append((mod, item.file_path, item.line_number))
+
+    return missing

devdoctor/utils/env_parser.py

@@ -0,0 +1,57 @@
+"""Parsing utilities for .env and .env.example files."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Dict, List, Set
+
+
+def parse_env_content(content: str) -> Dict[str, str]:
+    """Parse .env formatted text into key-value pairs."""
+    result: Dict[str, str] = {}
+    for line in content.splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        # Support 'export KEY=VAL'
+        if line.startswith("export "):
+            line = line[len("export "):].strip()
+
+        # Match KEY=VALUE or KEY="VALUE" or KEY='VALUE'
+        match = re.match(r"^([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$", line)
+        if match:
+            key = match.group(1).strip()
+            val = match.group(2).strip()
+            # Unquote if enclosed in matching quotes
+            if (val.startswith('"') and val.endswith('"')) or (val.startswith("'") and val.endswith("'")):
+                val = val[1:-1]
+            else:
+                # Strip inline comments: KEY=foo # comment
+                val = re.sub(r"\s+#.*$", "", val).strip()
+            result[key] = val
+    return result
+
+
+def parse_env_file(file_path: Path) -> Dict[str, str]:
+    """Read and parse a .env file."""
+    if not file_path.is_file():
+        return {}
+    try:
+        content = file_path.read_text(encoding="utf-8", errors="replace")
+        return parse_env_content(content)
+    except Exception:
+        return {}
+
+
+def get_env_keys(file_path: Path) -> Set[str]:
+    """Return all defined keys in an environment file."""
+    return set(parse_env_file(file_path).keys())
+
+
+def find_missing_env_keys(example_file: Path, target_env_file: Path) -> List[str]:
+    """Compare keys in .env.example against .env and return missing keys."""
+    example_keys = get_env_keys(example_file)
+    target_keys = get_env_keys(target_env_file)
+    missing = example_keys - target_keys
+    return sorted(list(missing))

devdoctor/utils/platform_info.py

@@ -0,0 +1,70 @@
+"""Platform and Python environment helper utilities."""
+
+from __future__ import annotations
+
+import os
+import platform
+import sys
+from pathlib import Path
+from typing import Optional, Tuple
+
+
+def is_windows() -> bool:
+    """Return True if running on Windows."""
+    return sys.platform.startswith("win") or platform.system() == "Windows"
+
+
+def is_macos() -> bool:
+    """Return True if running on macOS."""
+    return sys.platform == "darwin" or platform.system() == "Darwin"
+
+
+def is_linux() -> bool:
+    """Return True if running on Linux."""
+    return sys.platform.startswith("linux") or platform.system() == "Linux"
+
+
+def is_in_virtualenv() -> bool:
+    """Deterministically check if current Python is running inside a virtual environment.
+    
+    Checks both sys.prefix != sys.base_prefix (standard Python 3.3+ venv behavior)
+    and common environment variables like VIRTUAL_ENV or CONDA_PREFIX.
+    """
+    has_base = hasattr(sys, "base_prefix") and sys.prefix != sys.base_prefix
+    has_real = hasattr(sys, "real_prefix")  # old virtualenv
+    has_env = bool(os.environ.get("VIRTUAL_ENV") or os.environ.get("CONDA_PREFIX"))
+    return has_base or has_real or has_env
+
+
+def find_local_venv(project_path: Path) -> Optional[Path]:
+    """Look for standard virtualenv directories in the project root (.venv, venv, env)."""
+    candidates = [".venv", "venv", "env", ".env_dir"]
+    for name in candidates:
+        candidate = project_path / name
+        # Check for scripts/bin inside candidate
+        if candidate.is_dir():
+            if is_windows() and (candidate / "Scripts" / "python.exe").exists():
+                return candidate
+            elif (candidate / "bin" / "python").exists():
+                return candidate
+            elif (candidate / "pyvenv.cfg").exists():
+                return candidate
+    return None
+
+
+def get_venv_activation_command(venv_dir: Path | str = ".venv") -> str:
+    """Return the platform-specific shell command to activate the virtualenv."""
+    venv_path = Path(venv_dir)
+    if is_windows():
+        return f"{venv_path}\\Scripts\\activate"
+    return f"source {venv_path}/bin/activate"
+
+
+def get_python_version_tuple() -> Tuple[int, int, int]:
+    """Return Python version as a tuple of (major, minor, micro)."""
+    return (sys.version_info.major, sys.version_info.minor, sys.version_info.micro)
+
+
+def get_python_version_str() -> str:
+    """Return Python version as 'X.Y.Z'."""
+    return f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}"

devdoctor/utils/process_utils.py

@@ -0,0 +1,167 @@
+"""Cross-platform port scanning, process inspection, and process termination utilities."""
+
+from __future__ import annotations
+
+import csv
+import io
+import os
+import re
+import signal
+import socket
+import subprocess
+import sys
+from dataclasses import dataclass
+from typing import Optional
+
+from devdoctor.utils.platform_info import is_windows
+
+
+@dataclass
+class PortListenerInfo:
+    """Information about a process listening on a network port."""
+    port: int
+    pid: int
+    process_name: str
+    command_line: Optional[str] = None
+
+
+def is_port_in_use(port: int, host: str = "127.0.0.1") -> bool:
+    """Check whether a port is currently occupied or listening."""
+    # First, test connecting to host:port
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.settimeout(0.3)
+        result = s.connect_ex((host, port))
+        if result == 0:
+            return True
+
+    # Check 0.0.0.0
+    if host == "127.0.0.1":
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+            s.settimeout(0.3)
+            if s.connect_ex(("0.0.0.0", port)) == 0:
+                return True
+
+    # Also test binding: if bind fails with EADDRINUSE, it is in use
+    try:
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+            s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 0)
+            s.bind((host, port))
+        return False
+    except OSError:
+        return True
+
+
+def get_process_name_by_pid(pid: int) -> str:
+    """Look up the process name for a given PID."""
+    if pid <= 0:
+        return "unknown"
+
+    if is_windows():
+        try:
+            cmd = f'tasklist /FI "PID eq {pid}" /FO CSV /NH'
+            out = subprocess.check_output(cmd, shell=True, text=True, stderr=subprocess.DEVNULL)
+            reader = csv.reader(io.StringIO(out.strip()))
+            for row in reader:
+                if row and len(row) > 0 and row[0].strip():
+                    return row[0].strip()
+        except Exception:
+            pass
+        return "unknown"
+
+    # Unix-like (macOS / Linux)
+    try:
+        out = subprocess.check_output(["ps", "-p", str(pid), "-o", "comm="], text=True, stderr=subprocess.DEVNULL)
+        return out.strip() or "unknown"
+    except Exception:
+        return "unknown"
+
+
+def get_port_listener_info(port: int) -> Optional[PortListenerInfo]:
+    """Identify the PID and process name listening on a specific port."""
+    if not is_port_in_use(port):
+        return None
+
+    if is_windows():
+        try:
+            out = subprocess.check_output("netstat -ano -p tcp", shell=True, text=True, stderr=subprocess.DEVNULL)
+            for line in out.splitlines():
+                line = line.strip()
+                if not line or "LISTENING" not in line:
+                    continue
+                parts = re.split(r"\s+", line)
+                if len(parts) >= 5:
+                    local_addr = parts[1]
+                    state = parts[3]
+                    pid_str = parts[4]
+                    if state == "LISTENING":
+                        port_match = re.search(r":(\d+)$", local_addr)
+                        if port_match and int(port_match.group(1)) == port:
+                            try:
+                                pid = int(pid_str)
+                                proc_name = get_process_name_by_pid(pid)
+                                return PortListenerInfo(port=port, pid=pid, process_name=proc_name)
+                            except ValueError:
+                                pass
+        except Exception:
+            pass
+
+    else:
+        # macOS / Linux: use lsof or ss
+        try:
+            out = subprocess.check_output(["lsof", "-i", f":{port}", "-sTCP:LISTEN", "-Fp,c"], text=True, stderr=subprocess.DEVNULL)
+            pid = 0
+            proc_name = "unknown"
+            for line in out.splitlines():
+                if line.startswith("p"):
+                    pid = int(line[1:])
+                elif line.startswith("c"):
+                    proc_name = line[1:]
+            if pid > 0:
+                return PortListenerInfo(port=port, pid=pid, process_name=proc_name)
+        except Exception:
+            pass
+
+        try:
+            # Fallback to ss on Linux
+            out = subprocess.check_output(["ss", "-lptn", f"sport = :{port}"], text=True, stderr=subprocess.DEVNULL)
+            pid_match = re.search(r'pid=(\d+)', out)
+            proc_match = re.search(r'"([^"]+)"', out)
+            if pid_match:
+                pid = int(pid_match.group(1))
+                proc_name = proc_match.group(1) if proc_match else get_process_name_by_pid(pid)
+                return PortListenerInfo(port=port, pid=pid, process_name=proc_name)
+        except Exception:
+            pass
+
+    return PortListenerInfo(port=port, pid=0, process_name="unknown")
+
+
+def kill_process_by_pid(pid: int, force: bool = True) -> bool:
+    """Terminate a process by its PID."""
+    if pid <= 0:
+        return False
+
+    if is_windows():
+        try:
+            flag = "/F" if force else ""
+            cmd = f"taskkill /PID {pid} {flag} /T"
+            subprocess.run(cmd, shell=True, check=True, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+            return True
+        except Exception:
+            return False
+
+    # Unix
+    try:
+        sig = signal.SIGKILL if force else signal.SIGTERM
+        os.kill(pid, sig)
+        return True
+    except Exception:
+        return False
+
+
+def free_port(port: int) -> bool:
+    """Find the process listening on port and terminate it."""
+    info = get_port_listener_info(port)
+    if not info or info.pid <= 0:
+        return False
+    return kill_process_by_pid(info.pid, force=True)