devdoctor-cli 0.1.0__py3-none-any.whl

devdoctor/checks/environment.py

@@ -0,0 +1,146 @@
+"""Check environment variables, .env file presence, and .env vs .env.example discrepancies."""
+
+from __future__ import annotations
+
+import os
+import shutil
+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
+from devdoctor.utils.ast_imports import scan_project_ast
+from devdoctor.utils.env_parser import find_missing_env_keys, parse_env_file
+from devdoctor.utils.platform_info import is_windows
+
+
+@register_check
+class EnvironmentCheck(Check):
+    name = "environment"
+    title = "Environment Configuration"
+    category = "environment"
+    description = "Checks for missing environment files, missing keys from .env.example, and missing required vars found in code."
+
+    def run(self, context: ScanContext) -> List[Diagnostic]:
+        diagnostics: List[Diagnostic] = []
+        project_path = context.project_path
+
+        env_file = project_path / ".env"
+        env_example = project_path / ".env.example"
+
+        # Read active environment variables (system + .env if present)
+        loaded_env = dict(os.environ)
+        if env_file.is_file():
+            loaded_env.update(parse_env_file(env_file))
+        context.env_vars = loaded_env
+
+        # 1. Check .env vs .env.example
+        if env_example.is_file() and not env_file.is_file():
+            cp_cmd = "copy .env.example .env" if is_windows() else "cp .env.example .env"
+            
+            def copy_example_handler(ctx: ScanContext) -> bool:
+                try:
+                    shutil.copy2(env_example, env_file)
+                    return True
+                except Exception:
+                    return False
+
+            diagnostics.append(Diagnostic(
+                title="Environment file missing",
+                severity=Severity.ERROR,
+                message=".env file is missing, but .env.example exists.",
+                why="The project provides a template configuration (.env.example), but no active .env file was found.",
+                evidence="Found .env.example, but .env was not found.",
+                fix="Create .env from template:\n     " + cp_cmd,
+                command=cp_cmd,
+                confidence=Confidence.HIGH,
+                fix_action=FixAction(
+                    description="Copy .env.example to .env",
+                    command=cp_cmd,
+                    safe=True,
+                    handler=copy_example_handler,
+                ),
+                check_id=f"{self.name}_missing_env_file",
+            ))
+
+        elif env_example.is_file() and env_file.is_file():
+            missing_from_env = find_missing_env_keys(env_example, env_file)
+            for key in missing_from_env:
+                def make_add_key_handler(k: str):
+                    def handler(ctx: ScanContext) -> bool:
+                        try:
+                            with open(env_file, "a", encoding="utf-8") as f:
+                                f.write(f"\n{k}=\n")
+                            return True
+                        except Exception:
+                            return False
+                    return handler
+
+                diagnostics.append(Diagnostic(
+                    title="Environment variable",
+                    severity=Severity.ERROR,
+                    message=f"{key} is required by .env.example but missing in .env.",
+                    why=f"{key} is defined in .env.example, indicating it is required for project runtime.",
+                    evidence="Defined in: .env.example",
+                    fix=f"Add {key} to .env",
+                    command=f'echo {key}= >> .env',
+                    confidence=Confidence.HIGH,
+                    fix_action=FixAction(
+                        description=f"Add {key} placeholder to .env",
+                        command=f'echo {key}= >> .env',
+                        safe=True,
+                        handler=make_add_key_handler(key),
+                    ),
+                    check_id=f"{self.name}_example_{key}",
+                    metadata={"var_name": key, "source": ".env.example"},
+                ))
+
+        # 2. Check code files for required environment variable accesses (AST)
+        _, env_usages = scan_project_ast(project_path)
+        reported_vars = set()
+
+        for usage in env_usages:
+            var_name = usage.var_name
+            # Only strictly required environment variable accesses without defaults
+            if not usage.is_required or usage.has_default or var_name in reported_vars:
+                continue
+
+            # Check if set in loaded_env
+            if var_name not in loaded_env or not loaded_env[var_name].strip():
+                reported_vars.add(var_name)
+                try:
+                    rel_file = usage.file_path.relative_to(project_path)
+                except Exception:
+                    rel_file = usage.file_path.name
+                
+                def make_append_var_handler(v: str):
+                    def handler(ctx: ScanContext) -> bool:
+                        try:
+                            target = ctx.project_path / ".env"
+                            with open(target, "a", encoding="utf-8") as f:
+                                f.write(f"\n{v}=\n")
+                            return True
+                        except Exception:
+                            return False
+                    return handler
+
+                diagnostics.append(Diagnostic(
+                    title="Environment variable",
+                    severity=Severity.ERROR,
+                    message=f"{var_name} is required but missing.",
+                    why=f"Code in {rel_file} accesses os.environ['{var_name}'] without a default value.",
+                    evidence=f"Found in:\n     {rel_file} (line {usage.line_number})",
+                    fix=f"Add {var_name} to .env",
+                    command=f'echo {var_name}= >> .env',
+                    confidence=Confidence.HIGH,
+                    fix_action=FixAction(
+                        description=f"Add {var_name} to .env",
+                        command=f'echo {var_name}= >> .env',
+                        safe=True,
+                        handler=make_append_var_handler(var_name),
+                    ),
+                    check_id=f"{self.name}_code_{var_name}",
+                    metadata={"var_name": var_name, "found_in": str(rel_file), "line": usage.line_number},
+                ))
+
+        return diagnostics

devdoctor/checks/fastapi.py

@@ -0,0 +1,96 @@
+"""FastAPI framework diagnostic checks."""
+
+from __future__ import annotations
+
+import importlib.util
+import re
+from typing import List
+
+from devdoctor.checks.base import Check, register_check
+from devdoctor.models import Confidence, Diagnostic, FixAction, ScanContext, Severity
+from devdoctor.utils.ast_imports import collect_python_files
+from devdoctor.utils.process_utils import is_port_in_use
+
+
+@register_check
+class FastAPICheck(Check):
+    name = "fastapi"
+    title = "FastAPI Framework Diagnostics"
+    category = "framework"
+    description = "Checks FastAPI setup: Uvicorn availability, default port 8000, and CORS configuration."
+
+    def run(self, context: ScanContext) -> List[Diagnostic]:
+        diagnostics: List[Diagnostic] = []
+        is_fastapi = context.project_info and "FastAPI" in context.project_info.frameworks
+
+        if not is_fastapi:
+            return diagnostics
+
+        # 1. Uvicorn installed check
+        uvicorn_spec = importlib.util.find_spec("uvicorn")
+        if uvicorn_spec:
+            diagnostics.append(Diagnostic(
+                title="Uvicorn installed",
+                severity=Severity.OK,
+                message="Uvicorn ASGI server is installed.",
+                check_id=f"{self.name}_uvicorn_installed",
+            ))
+        else:
+            diagnostics.append(Diagnostic(
+                title="Uvicorn not installed",
+                severity=Severity.ERROR,
+                message="Uvicorn is required to serve FastAPI applications.",
+                why="FastAPI applications need an ASGI server like Uvicorn to run.",
+                fix="Install uvicorn:\n     pip install 'uvicorn[standard]'",
+                command="pip install 'uvicorn[standard]'",
+                confidence=Confidence.HIGH,
+                fix_action=FixAction(
+                    description="Install uvicorn[standard]",
+                    command="pip install 'uvicorn[standard]'",
+                    safe=False,
+                ),
+                check_id=f"{self.name}_uvicorn_missing",
+            ))
+
+        # 2. Port 8000 check
+        if is_port_in_use(8000):
+            diagnostics.append(Diagnostic(
+                title="Port 8000 occupied",
+                severity=Severity.WARNING,
+                message="Default FastAPI port (8000) is currently occupied.",
+                why="Uvicorn defaults to port 8000; starting a new server without --port will fail.",
+                fix="Free port 8000 or specify another port:\n     devdoctor port free 8000",
+                command="devdoctor port free 8000",
+                confidence=Confidence.HIGH,
+                check_id=f"{self.name}_port_8000",
+            ))
+        else:
+            diagnostics.append(Diagnostic(
+                title="Port 8000 available",
+                severity=Severity.OK,
+                message="Port 8000 is free and ready for Uvicorn.",
+                check_id=f"{self.name}_port_8000_free",
+            ))
+
+        # 3. CORS allows * check
+        py_files = collect_python_files(context.project_path)
+        for pf in py_files:
+            try:
+                txt = pf.read_text(encoding="utf-8", errors="replace")
+                if 'allow_origins=["*"]' in txt or "allow_origins=['*']" in txt:
+                    rel_p = pf.relative_to(context.project_path) if pf.is_relative_to(context.project_path) else pf.name
+                    diagnostics.append(Diagnostic(
+                        title="CORS allows * wildcard",
+                        severity=Severity.WARNING,
+                        message="CORS middleware is configured with allow_origins=['*'].",
+                        why="Allowing wildcard origins with credentials or in production allows any domain to send authenticated cross-origin requests.",
+                        evidence=f"Found in:\n     {rel_p}",
+                        fix="Restrict allow_origins to specific frontend domains.",
+                        confidence=Confidence.HIGH,
+                        check_id=f"{self.name}_cors_wildcard",
+                    ))
+                    break
+            except Exception:
+                pass
+
+        return diagnostics

devdoctor/checks/filesystem.py

@@ -0,0 +1,72 @@
+"""Check filesystem permissions, disk space, and repository clutter."""
+
+from __future__ import annotations
+
+import os
+import tempfile
+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 FilesystemCheck(Check):
+    name = "filesystem"
+    title = "Filesystem Integrity"
+    category = "filesystem"
+    description = "Checks filesystem permissions, write access, and unwanted repository clutter."
+
+    def run(self, context: ScanContext) -> List[Diagnostic]:
+        diagnostics: List[Diagnostic] = []
+        root = context.project_path
+
+        # 1. Test write permissions in project directory
+        try:
+            test_file = root / f".devdoctor_test_{os.getpid()}.tmp"
+            test_file.write_text("ok", encoding="utf-8")
+            test_file.unlink()
+        except Exception as ex:
+            diagnostics.append(Diagnostic(
+                title="Filesystem write permission denied",
+                severity=Severity.ERROR,
+                message=f"Project directory is not writable: {ex}",
+                why="DevDoctor and build tools require write access to create cache files, virtualenvs, and configs.",
+                evidence=f"Directory: {root}",
+                fix="Adjust directory permissions to grant write access to the current user.",
+                confidence=Confidence.HIGH,
+                check_id=f"{self.name}_write_permission",
+            ))
+
+        # 2. Check for large uncommitted files (> 50MB) in project (ignoring .git and .venv)
+        large_files = []
+        ignore_dirs = {".git", ".venv", "venv", "node_modules", "dist", "build"}
+        try:
+            for dirpath, dirnames, filenames in os.walk(root):
+                dirnames[:] = [d for d in dirnames if d not in ignore_dirs]
+                for f in filenames:
+                    fp = Path(dirpath) / f
+                    try:
+                        sz = fp.stat().st_size
+                        if sz > 50 * 1024 * 1024:  # 50MB
+                            large_files.append((fp, sz))
+                    except Exception:
+                        pass
+        except Exception:
+            pass
+
+        if large_files:
+            file_list = "\n     ".join([f"{fp.relative_to(root)} ({sz // (1024*1024)}MB)" for fp, sz in large_files[:3]])
+            diagnostics.append(Diagnostic(
+                title="Large files detected in repository",
+                severity=Severity.WARNING,
+                message=f"Found {len(large_files)} file(s) exceeding 50MB.",
+                why="Large files bloat git repository size and can cause git pushes to fail or slow down operations.",
+                evidence=f"Found:\n     {file_list}",
+                fix="Track large files using Git LFS or add them to .gitignore.",
+                confidence=Confidence.HIGH,
+                check_id=f"{self.name}_large_files",
+            ))
+
+        return diagnostics

devdoctor/checks/git.py

@@ -0,0 +1,151 @@
+"""Check Git availability, author configuration, and sensitive file tracking."""
+
+from __future__ import annotations
+
+import re
+import subprocess
+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 GitCheck(Check):
+    name = "git"
+    title = "Git Configuration"
+    category = "git"
+    description = "Verifies Git CLI availability, repository status, and security of sensitive files."
+
+    def run(self, context: ScanContext) -> List[Diagnostic]:
+        diagnostics: List[Diagnostic] = []
+
+        # 1. Check Git CLI availability
+        git_version = None
+        try:
+            res = subprocess.run(["git", "--version"], capture_output=True, text=True, timeout=5)
+            if res.returncode == 0:
+                out = res.stdout.strip()
+                match = re.search(r"git version\s+([0-9]+(?:\.[0-9]+)+)", out)
+                git_version = match.group(1).rstrip(".") if match else "available"
+                diagnostics.append(Diagnostic(
+                    title=f"Git {git_version}",
+                    severity=Severity.OK,
+                    message=f"Git is installed and available (version {git_version}).",
+                    check_id=f"{self.name}_version",
+                    metadata={"version": git_version},
+                ))
+            else:
+                diagnostics.append(Diagnostic(
+                    title="Git CLI unavailable",
+                    severity=Severity.WARNING,
+                    message="Git command failed or is not installed.",
+                    why="Git is required for version control, dependency tracking, and release management.",
+                    fix="Install Git from https://git-scm.com/downloads.",
+                    confidence=Confidence.HIGH,
+                    check_id=f"{self.name}_missing",
+                ))
+                return diagnostics
+        except Exception:
+            diagnostics.append(Diagnostic(
+                title="Git CLI unavailable",
+                severity=Severity.WARNING,
+                message="Git is not installed or not in PATH.",
+                why="Version control commands and repository checks require git.",
+                fix="Install Git and ensure it is added to your PATH.",
+                confidence=Confidence.HIGH,
+                check_id=f"{self.name}_missing",
+            ))
+            return diagnostics
+
+        # 2. Check if this is a Git repository
+        git_dir = context.project_path / ".git"
+        if not git_dir.exists():
+            return diagnostics
+
+        # Check git config user.name and user.email
+        try:
+            res_name = subprocess.run(["git", "config", "user.name"], capture_output=True, text=True, cwd=str(context.project_path))
+            res_email = subprocess.run(["git", "config", "user.email"], capture_output=True, text=True, cwd=str(context.project_path))
+            has_name = bool(res_name.stdout.strip())
+            has_email = bool(res_email.stdout.strip())
+
+            if not (has_name and has_email):
+                diagnostics.append(Diagnostic(
+                    title="Git author configuration",
+                    severity=Severity.WARNING,
+                    message="Git user.name or user.email is not configured.",
+                    why="Commits cannot be properly authored without user name and email configured.",
+                    evidence=f"user.name='{res_name.stdout.strip()}', user.email='{res_email.stdout.strip()}'",
+                    fix="Set your Git author details:\n     git config --global user.name \"Your Name\"\n     git config --global user.email \"you@example.com\"",
+                    command='git config --global user.name "Your Name" && git config --global user.email "you@example.com"',
+                    confidence=Confidence.HIGH,
+                    check_id=f"{self.name}_author",
+                ))
+        except Exception:
+            pass
+
+        # 3. Check .gitignore for .env
+        env_file = context.project_path / ".env"
+        gitignore_file = context.project_path / ".gitignore"
+
+        if env_file.is_file():
+            # Check if .env is ignored
+            is_ignored = False
+            if gitignore_file.is_file():
+                try:
+                    lines = [line.strip() for line in gitignore_file.read_text(encoding="utf-8", errors="replace").splitlines()]
+                    is_ignored = any(line in [".env", "*.env", ".env*", "/.env"] for line in lines)
+                except Exception:
+                    pass
+
+            if not is_ignored:
+                diagnostics.append(Diagnostic(
+                    title="Sensitive file .env not ignored",
+                    severity=Severity.ERROR,
+                    message=".env file exists but is not listed in .gitignore, risking secret leaks.",
+                    why="Committing .env files exposes sensitive credentials, secret keys, and database passwords in git history.",
+                    evidence="Found .env in project root, but '.env' pattern was not found in .gitignore.",
+                    fix="Add .env to .gitignore",
+                    command="echo .env >> .gitignore",
+                    confidence=Confidence.HIGH,
+                    fix_action=FixAction(
+                        description="Add .env to .gitignore",
+                        safe=True,
+                        action_type="file_append",
+                        target_path=gitignore_file,
+                        content=".env",
+                    ),
+                    check_id=f"{self.name}_gitignore_env",
+                ))
+
+            # Check if .env is already tracked in git index
+            try:
+                res_tracked = subprocess.run(
+                    ["git", "ls-files", "--error-unmatch", ".env"],
+                    capture_output=True,
+                    text=True,
+                    cwd=str(context.project_path),
+                )
+                if res_tracked.returncode == 0:
+                    diagnostics.append(Diagnostic(
+                        title=".env is tracked by Git",
+                        severity=Severity.ERROR,
+                        message=".env file is tracked in git index! Secrets may already be committed.",
+                        why="A tracked .env will be pushed to remotes, compromising credentials.",
+                        evidence="git ls-files .env confirmed tracking.",
+                        fix="Remove .env from git cache:\n     git rm --cached .env",
+                        command="git rm --cached .env",
+                        confidence=Confidence.HIGH,
+                        fix_action=FixAction(
+                            description="Remove .env from git cache",
+                            command="git rm --cached .env",
+                            safe=False,
+                        ),
+                        check_id=f"{self.name}_tracked_env",
+                    ))
+            except Exception:
+                pass
+
+        return diagnostics

devdoctor/checks/imports.py

@@ -0,0 +1,47 @@
+"""Check for missing or uninstalled Python imports in project code."""
+
+from __future__ import annotations
+
+from typing import List
+
+from devdoctor.checks.base import Check, register_check
+from devdoctor.models import Confidence, Diagnostic, FixAction, ScanContext, Severity
+from devdoctor.utils.ast_imports import find_missing_installed_imports
+
+
+@register_check
+class BrokenImportsCheck(Check):
+    name = "broken_imports"
+    title = "Python Imports"
+    category = "dependencies"
+    description = "Scans project Python files for third-party imports that are not installed in the active environment."
+
+    def run(self, context: ScanContext) -> List[Diagnostic]:
+        diagnostics: List[Diagnostic] = []
+        missing = find_missing_installed_imports(context.project_path)
+
+        for mod, file_path, line_no in missing:
+            try:
+                rel_path = file_path.relative_to(context.project_path)
+            except Exception:
+                rel_path = file_path.name
+
+            diagnostics.append(Diagnostic(
+                title=f"Missing module '{mod}'",
+                severity=Severity.ERROR,
+                message=f"Module '{mod}' is imported but not installed in current environment.",
+                why=f"Code in {rel_path} requires '{mod}', but the package is not found in site-packages.",
+                evidence=f"Found in:\n     {rel_path} (line {line_no})",
+                fix=f"Install {mod} via pip:\n     pip install {mod}",
+                command=f"pip install {mod}",
+                confidence=Confidence.HIGH,
+                fix_action=FixAction(
+                    description=f"Install {mod}",
+                    command=f"pip install {mod}",
+                    safe=False,
+                ),
+                check_id=f"{self.name}_{mod}",
+                metadata={"module": mod, "file": str(rel_path), "line": line_no},
+            ))
+
+        return diagnostics

devdoctor/checks/pip.py

@@ -0,0 +1,67 @@
+"""Check pip installation and availability."""
+
+from __future__ import annotations
+
+import re
+import subprocess
+import sys
+
+from devdoctor.checks.base import Check, register_check
+from devdoctor.models import Confidence, Diagnostic, FixAction, ScanContext, Severity
+
+
+@register_check
+class PipAvailabilityCheck(Check):
+    name = "pip_availability"
+    title = "pip Availability"
+    category = "system"
+    description = "Checks that pip is available and functional in the active environment."
+
+    def run(self, context: ScanContext) -> Diagnostic:
+        try:
+            res = subprocess.run(
+                [sys.executable, "-m", "pip", "--version"],
+                capture_output=True,
+                text=True,
+                timeout=5,
+            )
+            if res.returncode == 0:
+                output = res.stdout.strip()
+                # e.g., "pip 25.0.1 from ..."
+                match = re.search(r"pip\s+([0-9.]+)", output)
+                version_str = match.group(1) if match else "available"
+                return Diagnostic(
+                    title=f"pip {version_str}",
+                    severity=Severity.OK,
+                    message=f"pip is installed and functional (version {version_str}).",
+                    check_id=self.name,
+                    metadata={"version": version_str},
+                )
+            else:
+                return Diagnostic(
+                    title="pip unavailable",
+                    severity=Severity.ERROR,
+                    message="pip command failed to execute in active Python environment.",
+                    why="pip might be corrupt or missing in this Python installation.",
+                    evidence=res.stderr.strip() or res.stdout.strip(),
+                    fix="Run ensurepip to bootstrap pip into this environment.",
+                    command=f"{sys.executable} -m ensurepip --upgrade",
+                    confidence=Confidence.HIGH,
+                    fix_action=FixAction(
+                        description="Bootstrap pip via ensurepip",
+                        command=f"{sys.executable} -m ensurepip --upgrade",
+                        safe=True,
+                    ),
+                    check_id=self.name,
+                )
+        except Exception as ex:
+            return Diagnostic(
+                title="pip unavailable",
+                severity=Severity.ERROR,
+                message=f"Unable to execute pip: {ex}",
+                why="Python executable cannot find or execute the pip module.",
+                fix="Bootstrap pip or repair Python installation.",
+                command=f"{sys.executable} -m ensurepip --upgrade",
+                confidence=Confidence.HIGH,
+                check_id=self.name,
+            )

devdoctor/checks/ports.py

@@ -0,0 +1,90 @@
+"""Check port availability and detect process conflicts."""
+
+from __future__ import annotations
+
+import re
+from typing import List, Set
+
+from devdoctor.checks.base import Check, register_check
+from devdoctor.models import Confidence, Diagnostic, FixAction, ScanContext, Severity
+from devdoctor.utils.process_utils import get_port_listener_info, is_port_in_use
+
+
+@register_check
+class PortConflictsCheck(Check):
+    name = "port_conflicts"
+    title = "Port Conflicts"
+    category = "network"
+    description = "Checks common development ports for process occupation and port collisions."
+
+    def run(self, context: ScanContext) -> List[Diagnostic]:
+        diagnostics: List[Diagnostic] = []
+
+        # Determine ports to check based on project and common dev ports
+        target_ports: Set[int] = set()
+
+        # Check project type defaults
+        proj = context.project_info
+        if proj:
+            if proj.project_type in ("Django", "FastAPI"):
+                target_ports.add(8000)
+            elif proj.project_type == "Flask":
+                target_ports.add(5000)
+            if "Node.js" in proj.technologies:
+                target_ports.update([3000, 5173])
+
+        # Check .env for PORT=...
+        if context.env_vars:
+            for k, v in context.env_vars.items():
+                if "PORT" in k:
+                    try:
+                        p = int(v.strip())
+                        if 1 <= p <= 65535:
+                            target_ports.add(p)
+                    except ValueError:
+                        pass
+
+        # If no specific ports found, check the standard dev ports
+        if not target_ports:
+            target_ports = {8000, 3000, 5000, 5173, 8080}
+
+        for port in sorted(list(target_ports)):
+            if is_port_in_use(port):
+                info = get_port_listener_info(port)
+                proc_name = info.process_name if info else "unknown"
+                pid = info.pid if info else 0
+
+                evidence_lines = []
+                if proc_name and proc_name != "unknown":
+                    evidence_lines.append(f"Process: {proc_name}")
+                if pid > 0:
+                    evidence_lines.append(f"PID: {pid}")
+
+                evidence_text = "\n   ".join(evidence_lines) if evidence_lines else "Listening on local interface"
+                fix_cmd = f"devdoctor port free {port}"
+
+                fix_action = None
+                if pid > 0:
+                    fix_action = FixAction(
+                        description=f"Kill process {proc_name} (PID: {pid}) on port {port}",
+                        command=fix_cmd,
+                        safe=False,
+                        action_type="kill_process",
+                        metadata={"port": port, "pid": pid, "process_name": proc_name},
+                    )
+
+                diagnostics.append(Diagnostic(
+                    title=f"Port {port}",
+                    severity=Severity.WARNING,
+                    message="Port is already occupied.",
+                    why=f"Another process ({proc_name}) is already listening on port {port}, which prevents starting the local dev server.",
+                    evidence=evidence_text,
+                    fix=f"devdoctor port free {port}",
+                    command=fix_cmd,
+                    confidence=Confidence.HIGH,
+                    fix_action=fix_action,
+                    check_id=f"{self.name}_{port}",
+                    metadata={"port": port, "pid": pid, "process_name": proc_name},
+                ))
+
+        return diagnostics