devtoolkit-mcp 0.1.0__py3-none-any.whl

devtoolkit_mcp/tools/explain_code.py

@@ -0,0 +1,233 @@
+import stat
+from pathlib import Path
+import ast
+
+
+MAX_SOURCE_SIZE_BYTES = 1_100_000  # 1.1 MB
+
+def _load_source_code(
+    code: str | None,
+    file_path: str | None,
+) -> tuple[str, str]:
+    
+    if (code is None) == (file_path is None):
+        raise ValueError("Provide either code or file_path, but not both." 
+        )
+    
+    if code is not None:
+        if not code.strip():
+            raise ValueError("Provided code is empty.")
+
+        if len(code.encode("utf-8")) > MAX_SOURCE_SIZE_BYTES:
+            raise ValueError("Provided code exceeds the maximum allowed size of 1.1 MB.")
+        
+        return code, "code_snippet"
+    
+    path = Path(file_path).expanduser().resolve()
+
+    if not path.exists():
+        raise ValueError(f"File path does not exist: {path}")
+    
+    if path.is_symlink():
+        raise ValueError(f"File path is a symbolic link: {path}")
+    
+    if path.suffix.lower() != ".py":
+        raise ValueError(f"File path does not point to a Python file: {path}")
+    
+    file_stat = path.stat()
+
+    if not stat.S_ISREG(file_stat.st_mode):
+        raise ValueError(f"File path is not a regular file: {path}")
+    
+    if file_stat.st_size > MAX_SOURCE_SIZE_BYTES:
+        raise ValueError("File size exceeds the maximum allowed size of 1.1 MB.")
+
+    try:
+        source_code = path.read_text(encoding="utf-8")
+    
+    except UnicodeDecodeError as exc:
+        raise ValueError(f"File path is not a valid UTF-8 encoded text file: {path}") from exc
+    
+    return source_code, "file"
+        
+def _extract_functions(tree: ast.Module) -> list[dict]:
+    """extract top level functions from a python AST"""
+    
+    functions = []
+
+    for node in tree.body:
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            arguments = [
+                argument.arg
+                for argument in (
+                    node.args.posonlyargs + node.args.args
+                )
+            ]
+
+            if node.args.vararg:
+                arguments.append(f"*{node.args.vararg.arg}")
+
+            arguments.extend(
+                argument.arg for argument in node.args.kwonlyargs
+            )
+
+            if node.args.kwarg:
+                arguments.append(f"**{node.args.kwarg.arg}")
+            
+            functions.append({
+                "name": node.name,
+                "arguments": arguments,
+                "line_number": node.lineno,
+                "docstring": ast.get_docstring(node),
+                "is_async": isinstance(node, ast.AsyncFunctionDef),
+            })
+
+    return functions
+
+
+def _extract_classes(tree: ast.Module) -> list[dict]:
+    """Extract top-level classes and their methods from Python AST."""
+
+    classes = []
+
+    for node in tree.body:
+        if isinstance(node, ast.ClassDef):
+            methods = []
+
+            for child in node.body:
+                if isinstance(
+                    child,
+                    (ast.FunctionDef, ast.AsyncFunctionDef),
+                ):
+                    arguments = [
+                        argument.arg
+                        for argument in (
+                            child.args.posonlyargs
+                            + child.args.args
+                        )
+                    ]
+
+                    if child.args.vararg:
+                        arguments.append(f"*{child.args.vararg.arg}")
+
+                    arguments.extend(
+                        argument.arg
+                        for argument in child.args.kwonlyargs
+                    )
+
+                    if child.args.kwarg:
+                        arguments.append(f"**{child.args.kwarg.arg}")
+
+                    methods.append({
+                        "name": child.name,
+                        "arguments": arguments,
+                        "line_number": child.lineno,
+                        "docstring": ast.get_docstring(child),
+                        "is_async": isinstance(
+                            child,
+                            ast.AsyncFunctionDef,
+                        ),
+                    })
+
+            classes.append({
+                "name": node.name,
+                "line_number": node.lineno,
+                "docstring": ast.get_docstring(node),
+                "methods": methods,
+            })
+
+    return classes
+
+
+def _extract_imports(tree: ast.Module) -> list[dict]:
+    """Extract top-level imports from python AST"""
+
+    imports = []
+
+    for node in tree.body:
+        if isinstance(node,ast.Import):
+            for alias in node.names:
+                imports.append({
+                    "type":"import",
+                    "module": None,
+                    "name": alias.name,
+                    "alias": alias.asname,
+                    "level": 0,
+                    "line_number": node.lineno,
+                })
+        
+        elif isinstance(node, ast.ImportFrom):
+            for alias in node.names:
+                imports.append({
+                    "type":"from_import",
+                    "module":node.module,
+                    "name": alias.name,
+                    "alias": alias.asname,
+                    "level": node.level,
+                    "line_number": node.lineno,
+                })
+    return imports
+
+
+def _calculate_statistics(
+    source_code: str,
+    tree: ast.Module,
+) -> dict:
+
+    """Calculate basic statistics for python source code."""
+
+    functions = _extract_functions(tree)
+    classes = _extract_classes(tree)
+    imports = _extract_imports(tree)
+
+    return {
+        "total_lines": len(source_code.splitlines()),
+        "function_count": len(functions),
+        "class_count": len(classes),
+        "import_count": len(imports)
+    }
+
+
+def explain_code(
+    code: str | None = None,
+    file_path: str | None = None,
+) -> dict:
+    """Analyze Python code and explain its basic structure."""
+
+    source_code, source_type = _load_source_code(
+        code=code,
+        file_path=file_path,
+    )
+
+    try:
+        tree = ast.parse(source_code)
+
+    except SyntaxError as exc:
+        return {
+            "source_type": source_type,
+            "language": "Python",
+            "syntax_valid": False,
+            "functions": [],
+            "classes": [],
+            "imports": [],
+            "statistics": None,
+            "syntax_error": {
+                "message": exc.msg,
+                "line_number": exc.lineno,
+                "column": exc.offset,
+            },
+        }
+
+    return {
+        "source_type": source_type,
+        "language": "Python",
+        "syntax_valid": True,
+        "functions": _extract_functions(tree),
+        "classes": _extract_classes(tree),
+        "imports": _extract_imports(tree),
+        "statistics": _calculate_statistics(
+            source_code,
+            tree,
+        ),
+        "syntax_error": None,
+    }

devtoolkit_mcp/tools/repository.py

@@ -0,0 +1,134 @@
+import os
+from collections import Counter
+from pathlib import Path
+
+IGNORED_DIRECTORIES = {
+    ".git", 
+    ".venv",
+    "venv",
+    "__pycache__",
+    "node_modules",
+    ".pytest_cache",
+    ".mypy_cache",
+    ".dist",
+    "build",
+}
+
+LANGUAGE_EXTENSIONS = {
+    ".py": "Python",
+    ".js": "JavaScript",
+    ".ts": "TypeScript",
+    ".jsx": "JavaScript",
+    ".tsx": "TypeScript",
+    ".java": "Java",
+    ".cpp": "C++",
+    ".c": "C",
+    ".go": "Go",
+    ".rs": "Rust",
+    ".rb": "Ruby",
+    ".php": "PHP",
+    ".sql": "SQL",
+    ".html": "HTML",
+    ".css": "CSS",
+}
+
+def analyze_repository(
+    repository_path: str,
+    max_files: int = 5000,
+) -> dict:
+    """
+    Analyze the repository at the given path and return a summary of its contents.
+
+    Args:
+        repository_path (str): The path to the repository.
+        max_files (int): The maximum number of files to analyze.
+
+    Returns:
+        dict: A summary of the repository's contents, including total files, 
+              total lines of code, and a breakdown of file types.
+    """
+    
+    if max_files < 1 or max_files > 20000:
+        raise ValueError("max_files must be between 1 and 20000.")
+    
+    root = Path(repository_path).expanduser().resolve()
+
+    if not root.exists():
+        raise ValueError(f"Repository path does not exist:{root}")
+
+    if not root.is_dir():
+        raise ValueError(f"Repository path is not a directory: {root}")
+
+    language_counts = Counter()
+    configuration_files = []
+    directory_count = 0
+    files_scanned = 0
+    truncated = False
+
+    important_files = {
+        "pyproject.toml",
+        "requirements.txt",
+        "package.json",
+        "Cargo.toml",
+        "go.mod",
+        "pom.xml",
+        "Dockerfile",
+        "docker-compose.yml",
+        "alembic.ini",
+        "pytest.ini",
+        "README.md",
+    }
+
+    top_level_entries = sorted(
+        entry.name for entry in root.iterdir() if entry.is_dir() and entry.name not in IGNORED_DIRECTORIES
+    )
+
+    for current_root, directories, files in os.walk(
+        root,
+        followlinks=False,
+    ):
+        directories[:] = [
+            directory
+            for directory in directories
+            if directory not in IGNORED_DIRECTORIES
+            and not (Path(current_root) / directory).is_symlink()
+        ]
+
+        directory_count += len(directories)
+
+        for filename in files:
+            file_path = Path(current_root) / filename
+
+            if file_path.is_symlink():
+                continue
+
+            if files_scanned >= max_files:
+                truncated = True
+                break
+
+            files_scanned += 1
+
+            extension = file_path.suffix.lower()
+
+            if extension in LANGUAGE_EXTENSIONS:
+                language_counts[LANGUAGE_EXTENSIONS[extension]] += 1
+            
+            if filename in important_files:
+                configuration_files.append(str(file_path.relative_to(root)))
+        
+
+        if truncated:
+            break
+
+
+    return {
+        "project_name": root.name,
+        "repository_path": str(root),
+        "files_scanned": files_scanned,
+        "directories": directory_count,
+        "languages": dict(language_counts.most_common()),
+        "important_files": sorted(configuration_files),
+        "top_level_entries": top_level_entries,
+        "truncated": truncated,
+    }
+    

devtoolkit_mcp/tools/run_tests.py

@@ -0,0 +1,332 @@
+import os
+import signal
+import ast
+import subprocess
+import sys
+import threading
+import tomllib
+from pathlib import Path
+
+
+def _validate_project_path(project_path: str) -> Path:
+    """Validate the supplied project directory."""
+
+    if not isinstance(project_path, str):
+        raise TypeError("Project path must be a string.")
+
+    if not project_path.strip():
+        raise ValueError("Project path cannot be empty.")
+
+    root = Path(project_path).expanduser()
+
+    if not root.exists():
+        raise ValueError("Project directory does not exist.")
+
+    if root.is_symlink():
+        raise ValueError("Symbolic links are not supported.")
+
+    if not root.is_dir():
+        raise ValueError("Path must point to a directory.")
+
+    return root.resolve()
+
+
+def _has_pytest_config(project_root: Path) -> bool:
+    """check whether the project has explicit pytest configuration"""
+
+    if (project_root/"pytest.ini").is_file():
+        return True
+    
+    pyproject_file = project_root/"pyproject.toml"
+
+    if pyproject_file.is_file():
+        try:
+            with pyproject_file.open("rb") as file:
+                config = tomllib.load(file)
+            
+            if "pytest" in config.get("tool", {}):
+                return True
+            
+        except (tomllib.TOMLDecodeError, OSError):
+            pass
+
+    config_files = {
+        "setup.cfg": "[tool:pytest]",
+        "tox.ini":"[pytest]",
+    }
+
+    for filename, section in config_files.items():
+        config_file = project_root/filename
+
+        if config_file.is_file():
+            try:
+                content = config_file.read_text(encoding="utf-8").lower()
+                if section.lower() in content:
+                    return True
+                
+            except (OSError, UnicodeDecodeError):
+                continue
+    return False
+
+
+def _get_test_framework_imports(project_root: Path) -> set[str]:
+    """Find pytest and unittest imports in test files"""
+
+    test_files = set(project_root.glob("test_*.py"))
+    test_files.update(project_root.glob("*_test.py"))
+
+    tests_directory = project_root/ "tests"
+
+    if tests_directory.is_dir() and not tests_directory.is_symlink():
+        test_files.update(tests_directory.rglob("*.py"))
+    
+    detected = set()
+
+    for test_file in test_files:
+        if test_file.is_symlink():
+            continue
+
+        try:
+            source = test_file.read_text(encoding="utf-8")
+            tree = ast.parse(source)
+        except (OSError, UnicodeDecodeError, SyntaxError):
+            continue
+
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Import):
+                for alias in node.names:
+                    if alias.name == "pytest":
+                        detected.add("pytest")
+                    if alias.name == "unittest":
+                        detected.add("unittest")
+            elif isinstance(node, ast.ImportFrom):
+                if node.module == "pytest" or (
+                    node.module and node.module.startswith("pytest.")
+                ):
+                    detected.add("pytest")
+                if node.module == "unittest" or (
+                    node.module and node.module.startswith("unittest.")
+                ):
+                    detected.add("unittest")
+    return detected
+
+def _detect_test_framework(project_root: Path) -> dict:
+    """Detect pytest and unittest using configuration and imports"""
+
+    detected = _get_test_framework_imports(project_root)
+
+    if _has_pytest_config(project_root):
+        detected.add("pytest")
+    
+    frameworks = sorted(detected)
+
+    if len(frameworks) > 1:
+        status = "multiple_detected"
+    elif len(frameworks) == 1:
+        status = "detected"
+    else:
+        status = "not_found"
+
+    return {
+        "frameworks": frameworks,
+        "status": status,
+    }
+
+
+def _get_python_executable(project_root: Path) -> str:
+    """Find the Python executable for the target project"""
+
+    if sys.platform == "win32":
+        python_path = project_root / ".venv" / "Scripts" / "python.exe"
+    else:
+        python_path = project_root / ".venv" / "bin" / "python"
+    
+    if python_path.is_file():
+        return str(python_path)
+    
+    return sys.executable
+
+
+def _read_process_output(
+    pipe,
+    output: bytearray,
+    max_bytes: int = 10000,
+) -> None:
+    """Read process output while retaining only a limited amount."""
+
+    while True:
+        chunk = pipe.read(1024)
+
+        if not chunk:
+            break
+
+        remaining = max_bytes - len(output)
+
+        if remaining > 0:
+            output.extend(chunk[:remaining])
+
+
+def _terminate_process_tree(process: subprocess.Popen) -> None:
+    """Terminate a process and its child processes."""
+
+    if process.poll() is not None:
+        return
+
+    try:
+        if os.name == "nt":
+            subprocess.run(
+                ["taskkill", "/F", "/T", "/PID", str(process.pid)],
+                capture_output=True,
+                timeout=10,
+                shell=False,
+                check=False,
+            )
+        else:
+            os.killpg(process.pid, signal.SIGKILL)
+
+    except (OSError, subprocess.TimeoutExpired):
+        pass
+
+    if process.poll() is None:
+        process.kill()
+
+
+def _execute_tests(
+    project_root: Path,
+    command: list[str],
+    timeout: int = 120,
+) -> dict:
+    """Execute tests with bounded output and timeout handling."""
+
+    output = bytearray()
+    process = None
+
+    try:
+        process = subprocess.Popen(
+            command,
+            cwd=project_root,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            shell=False,
+            creationflags=subprocess.CREATE_NEW_PROCESS_GROUP if os.name == "nt" else 0,
+            start_new_session=os.name != "nt",
+        )
+
+        reader = threading.Thread(
+            target=_read_process_output,
+            args=(process.stdout, output),
+            daemon=True,
+        )
+        reader.start()
+
+        try:
+            return_code = process.wait(timeout=timeout)
+
+        except subprocess.TimeoutExpired:
+            _terminate_process_tree(process)
+            process.wait()
+            reader.join(timeout=5)
+
+            if reader.is_alive():
+                process.stdout.close()
+                reader.join(timeout=1)
+
+            return {
+                "status": "timeout",
+                "return_code": None,
+                "output": output.decode("utf-8", errors="replace"),
+            }
+
+        reader.join()
+
+        return {
+            "status": "completed",
+            "return_code": return_code,
+            "output": output.decode("utf-8", errors="replace"),
+        }
+
+    except OSError as exc:
+        if process is not None and process.poll() is None:
+            process.kill()
+            process.wait()
+
+        return {
+            "status": "error",
+            "return_code": None,
+            "output": str(exc)[:10000],
+        }
+
+
+
+def run_tests(
+    project_path: str,
+    timeout: int = 120,
+) -> dict:
+    """Run detected Python tests in a project"""
+
+    try:
+        project_root = _validate_project_path(project_path)
+
+        if isinstance(timeout, bool) or not isinstance(timeout, int):
+            raise TypeError("Timeout must be an integer")
+        
+        if not 1<=timeout<=600:
+            raise ValueError("Timeout must be between 1 and 600 seconds.")
+
+        detection = _detect_test_framework(project_root)
+        frameworks = detection["frameworks"]
+
+        if not frameworks:
+            return {
+                "status": "not_found",
+                "framework": None,
+                "return_code": None,
+                "output": "No supported test framework detected"
+            }
+        
+        if "pytest" in frameworks:
+            framework = "pytest"
+            command = [
+                _get_python_executable(project_root),
+                "-m",
+                "pytest",
+                "-q",
+            ]
+        else:
+            framework = "unittest"
+            command = [
+                _get_python_executable(project_root),
+                "-m",
+                "unittest",
+                "discover",
+            ]
+        result = _execute_tests(
+            project_root=project_root,
+            command=command,
+            timeout=timeout,
+        )
+
+        if result["status"] == "completed":
+            status = (
+                "passed"
+                if result["return_code"] == 0
+                else "failed"
+            )
+        else:
+            status = result["status"]
+
+        return {
+            "status": status,
+            "framework": framework,
+            "return_code": result["return_code"],
+            "output": result["output"],
+        }
+
+    except (ValueError, TypeError) as exc:
+        return {
+            "status": "error",
+            "framework": None,
+            "return_code": None,
+            "output": str(exc),
+        }
+