pycodegate 0.1.0__py3-none-any.whl

pycodegate/profile.py

@@ -0,0 +1,107 @@
+"""Project profile detection and rule/scoring adjustments."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from pycodegate._compat import tomllib
+
+
+@dataclass(frozen=True)
+class Profile:
+    name: str  # "cli", "web", "library", "script"
+    suppressed_rules: frozenset[str] = field(default_factory=frozenset)
+    max_deduction_overrides: dict[str, int] = field(default_factory=dict)
+
+
+# Profile definitions
+PROFILES = {
+    "web": Profile(name="web"),
+    "cli": Profile(
+        name="cli",
+        suppressed_rules=frozenset({"no-subprocess", "no-shell-exec"}),
+        max_deduction_overrides={"Security": 15},
+    ),
+    "library": Profile(name="library"),
+    "script": Profile(
+        name="script",
+        suppressed_rules=frozenset({"structure/no-tests", "structure/no-license"}),
+        max_deduction_overrides={"Structure": 5},
+    ),
+}
+
+
+def detect_profile(project_path: str) -> Profile:
+    """Auto-detect project profile from project structure and dependencies."""
+    path = Path(project_path)
+    pyproject = path / "pyproject.toml"
+
+    deps: set[str] = set()
+    has_build_system = False
+    has_scripts = False
+
+    if pyproject.exists():
+        try:
+            with open(pyproject, "rb") as f:
+                data = tomllib.load(f)
+            # Collect dependency names
+            for dep in data.get("project", {}).get("dependencies", []):
+                deps.add(
+                    dep.split("[")[0]
+                    .split(">")[0]
+                    .split("<")[0]
+                    .split("=")[0]
+                    .split("!")[0]
+                    .strip()
+                    .lower()
+                )
+            has_build_system = "build-system" in data
+            has_scripts = bool(data.get("project", {}).get("scripts"))
+        except Exception:
+            pass
+
+    # Also check requirements.txt
+    for req_file in ["requirements.txt", "requirements-dev.txt"]:
+        req_path = path / req_file
+        if req_path.exists():
+            try:
+                for line in req_path.read_text().splitlines():
+                    line = line.strip()
+                    if line and not line.startswith("#") and not line.startswith("-"):
+                        deps.add(
+                            line.split("[")[0]
+                            .split(">")[0]
+                            .split("<")[0]
+                            .split("=")[0]
+                            .split("!")[0]
+                            .strip()
+                            .lower()
+                        )
+            except Exception:
+                pass
+
+    # Web frameworks
+    web_deps = {"flask", "django", "fastapi", "starlette", "tornado", "aiohttp", "sanic", "bottle"}
+    if deps & web_deps:
+        return PROFILES["web"]
+
+    # CLI tools
+    cli_deps = {"click", "typer", "fire", "cement", "cliff", "argparse"}
+    if (deps & cli_deps) or has_scripts:
+        return PROFILES["cli"]
+
+    # Library
+    if has_build_system and not has_scripts:
+        return PROFILES["library"]
+
+    # Script: no __init__.py and few .py files
+    py_files = list(path.glob("*.py"))
+    has_init = (path / "__init__.py").exists() or any(
+        (path / d / "__init__.py").exists() for d in ["src", "lib"]
+    )
+    if not has_init and len(py_files) <= 5:
+        return PROFILES["script"]
+
+    # Default to library
+    return PROFILES["library"]

pycodegate/rules/__init__.py

@@ -0,0 +1,38 @@
+"""Rule registry for python-doctor."""
+
+from __future__ import annotations
+
+from pycodegate.rules.architecture import ArchitectureRules
+from pycodegate.rules.base import BaseRules
+from pycodegate.rules.complexity import ComplexityRules
+from pycodegate.rules.correctness import CorrectnessRules
+from pycodegate.rules.dependencies import DependencyRules as DependencyRules
+from pycodegate.rules.django import DjangoRules
+from pycodegate.rules.fastapi import FastAPIRules
+from pycodegate.rules.flask import FlaskRules
+from pycodegate.rules.imports import ImportsRules as ImportsRules
+from pycodegate.rules.performance import PerformanceRules
+from pycodegate.rules.security import SecurityRules
+from pycodegate.rules.structure import StructureRules as StructureRules
+
+
+def get_all_rule_sets() -> list[BaseRules]:
+    """Return all available rule sets."""
+    return [
+        SecurityRules(),
+        PerformanceRules(),
+        ArchitectureRules(),
+        CorrectnessRules(),
+        ComplexityRules(),
+    ]
+
+
+def get_framework_rules(framework: str | None) -> list[BaseRules]:
+    """Return framework-specific rule sets."""
+    _framework_map: dict[str, type[BaseRules]] = {
+        "django": DjangoRules,
+        "fastapi": FastAPIRules,
+        "flask": FlaskRules,
+    }
+    cls = _framework_map.get(framework or "")
+    return [cls()] if cls else []

pycodegate/rules/architecture.py

@@ -0,0 +1,121 @@
+"""Architecture rules: giant modules, deep nesting, god functions, too many args."""
+
+from __future__ import annotations
+
+import ast
+
+from pycodegate.rules.base import BaseRules
+from pycodegate.types import Category, Diagnostic, Severity
+
+MAX_MODULE_LINES = 500
+MAX_FUNCTION_LINES = 50
+MAX_NESTING_DEPTH = 5
+MAX_ARGUMENTS = 7
+
+
+class ArchitectureRules(BaseRules):
+    """Architecture-level checks."""
+
+    def check(self, source: str, filename: str) -> list[Diagnostic]:
+        tree = self._parse(source)
+        if tree is None:
+            return []
+
+        diags: list[Diagnostic] = []
+        diags.extend(self._check_giant_module(source, filename))
+        diags.extend(self._check_deep_nesting(tree, filename))
+        diags.extend(self._check_god_functions(tree, filename))
+        diags.extend(self._check_too_many_args(tree, filename))
+        return diags
+
+    def _check_giant_module(self, source: str, filename: str) -> list[Diagnostic]:
+        lines = source.count("\n") + 1
+        if lines > MAX_MODULE_LINES:
+            return [
+                Diagnostic(
+                    file_path=filename,
+                    rule="no-giant-module",
+                    severity=Severity.WARNING,
+                    category=Category.ARCHITECTURE,
+                    message=f"Module has {lines} lines (max {MAX_MODULE_LINES}) — consider splitting",
+                    help="Extract related functions into separate modules",
+                    line=1,
+                    cost=1.0,
+                )
+            ]
+        return []
+
+    def _check_deep_nesting(self, tree: ast.Module, filename: str) -> list[Diagnostic]:
+        diags: list[Diagnostic] = []
+        self._walk_nesting(tree, 0, filename, diags)
+        return diags
+
+    def _walk_nesting(
+        self, node: ast.AST, depth: int, filename: str, diags: list[Diagnostic]
+    ) -> None:
+        nesting_nodes = (ast.If, ast.For, ast.While, ast.With, ast.Try)
+        if isinstance(node, nesting_nodes):
+            depth += 1
+            if depth >= MAX_NESTING_DEPTH:
+                diags.append(
+                    Diagnostic(
+                        file_path=filename,
+                        rule="no-deep-nesting",
+                        severity=Severity.WARNING,
+                        category=Category.ARCHITECTURE,
+                        message=f"Nesting depth {depth} exceeds max {MAX_NESTING_DEPTH}",
+                        help="Extract nested logic into helper functions or use early returns",
+                        line=node.lineno,
+                        column=node.col_offset,
+                        cost=1.0,
+                    )
+                )
+        for child in ast.iter_child_nodes(node):
+            self._walk_nesting(child, depth, filename, diags)
+
+    def _check_god_functions(self, tree: ast.Module, filename: str) -> list[Diagnostic]:
+        diags: list[Diagnostic] = []
+        for node in ast.walk(tree):
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                end = getattr(node, "end_lineno", None)
+                if end is not None:
+                    length = end - node.lineno + 1
+                    if length > MAX_FUNCTION_LINES:
+                        diags.append(
+                            Diagnostic(
+                                file_path=filename,
+                                rule="no-god-function",
+                                severity=Severity.WARNING,
+                                category=Category.ARCHITECTURE,
+                                message=f"Function '{node.name}' is {length} lines (max {MAX_FUNCTION_LINES})",
+                                help="Break into smaller functions with single responsibilities",
+                                line=node.lineno,
+                                column=node.col_offset,
+                                cost=1.0,
+                            )
+                        )
+        return diags
+
+    def _check_too_many_args(self, tree: ast.Module, filename: str) -> list[Diagnostic]:
+        diags: list[Diagnostic] = []
+        for node in ast.walk(tree):
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                args = node.args
+                total = len(args.posonlyargs) + len(args.args) + len(args.kwonlyargs)
+                if total > 0 and args.args and args.args[0].arg in ("self", "cls"):
+                    total -= 1
+                if total > MAX_ARGUMENTS:
+                    diags.append(
+                        Diagnostic(
+                            file_path=filename,
+                            rule="too-many-arguments",
+                            severity=Severity.WARNING,
+                            category=Category.ARCHITECTURE,
+                            message=f"Function '{node.name}' has {total} arguments (max {MAX_ARGUMENTS})",
+                            help="Group related arguments into a dataclass or TypedDict",
+                            line=node.lineno,
+                            column=node.col_offset,
+                            cost=1.0,
+                        )
+                    )
+        return diags

pycodegate/rules/base.py

@@ -0,0 +1,23 @@
+"""Base class for rule sets."""
+
+from __future__ import annotations
+
+import ast
+from abc import ABC, abstractmethod
+
+from pycodegate.types import Diagnostic
+
+
+class BaseRules(ABC):
+    """Base class that all rule sets inherit from."""
+
+    @abstractmethod
+    def check(self, source: str, filename: str) -> list[Diagnostic]:
+        """Analyze source code and return diagnostics."""
+
+    def _parse(self, source: str) -> ast.Module | None:
+        """Safely parse Python source into AST."""
+        try:
+            return ast.parse(source)
+        except SyntaxError:
+            return None

pycodegate/rules/complexity.py

@@ -0,0 +1,87 @@
+"""Complexity rules: cyclomatic complexity analysis using pure AST."""
+
+from __future__ import annotations
+
+import ast
+
+from pycodegate.rules.base import BaseRules
+from pycodegate.types import Category, Diagnostic, Severity
+
+MAX_COMPLEXITY = 15
+CRITICAL_COMPLEXITY = 25
+
+
+def _cyclomatic_complexity(func_node: ast.FunctionDef | ast.AsyncFunctionDef) -> int:
+    """Calculate cyclomatic complexity for a function node.
+
+    Starts at 1 and adds 1 for each decision point:
+      - if / elif statements
+      - for / while loops
+      - except handlers
+      - and / or boolean operators
+      - assert statements
+      - ternary expressions (IfExp)
+    """
+    complexity = 1
+    for node in ast.walk(func_node):
+        # Skip nested function/class definitions to avoid double-counting
+        if node is not func_node and isinstance(
+            node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)
+        ):
+            continue
+        if isinstance(node, (ast.If, ast.For, ast.AsyncFor, ast.While, ast.ExceptHandler)):
+            complexity += 1
+        elif isinstance(node, ast.BoolOp):
+            complexity += len(node.values) - 1
+        elif isinstance(node, (ast.Assert, ast.IfExp)):
+            complexity += 1
+    return complexity
+
+
+class ComplexityRules(BaseRules):
+    """Cyclomatic complexity checks."""
+
+    def check(self, source: str, filename: str) -> list[Diagnostic]:
+        tree = self._parse(source)
+        if tree is None:
+            return []
+
+        diags: list[Diagnostic] = []
+        for node in ast.walk(tree):
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                complexity = _cyclomatic_complexity(node)
+                if complexity > CRITICAL_COMPLEXITY:
+                    diags.append(
+                        Diagnostic(
+                            file_path=filename,
+                            rule="critical-complexity",
+                            severity=Severity.ERROR,
+                            category=Category.COMPLEXITY,
+                            message=(
+                                f"Function '{node.name}' has cyclomatic complexity"
+                                f" {complexity} (max {MAX_COMPLEXITY})"
+                            ),
+                            help="Break into smaller functions or simplify conditional logic",
+                            line=node.lineno,
+                            column=node.col_offset,
+                            cost=3.0,
+                        )
+                    )
+                elif complexity > MAX_COMPLEXITY:
+                    diags.append(
+                        Diagnostic(
+                            file_path=filename,
+                            rule="high-complexity",
+                            severity=Severity.WARNING,
+                            category=Category.COMPLEXITY,
+                            message=(
+                                f"Function '{node.name}' has cyclomatic complexity"
+                                f" {complexity} (max {MAX_COMPLEXITY})"
+                            ),
+                            help="Break into smaller functions or simplify conditional logic",
+                            line=node.lineno,
+                            column=node.col_offset,
+                            cost=1.5,
+                        )
+                    )
+        return diags

pycodegate/rules/correctness.py

@@ -0,0 +1,131 @@
+"""Correctness rules: mutable defaults, bare except, broad exception, assert in prod, return in __init__."""
+
+from __future__ import annotations
+
+import ast
+
+from pycodegate.rules.base import BaseRules
+from pycodegate.types import Category, Diagnostic, Severity
+
+
+class CorrectnessRules(BaseRules):
+    """Correctness-related checks."""
+
+    def check(self, source: str, filename: str) -> list[Diagnostic]:
+        tree = self._parse(source)
+        if tree is None:
+            return []
+
+        diags: list[Diagnostic] = []
+        diags.extend(self._check_mutable_defaults(tree, filename))
+        diags.extend(self._check_bare_except(tree, filename))
+        diags.extend(self._check_broad_exception(tree, filename))
+        diags.extend(self._check_assert_in_production(tree, filename))
+        diags.extend(self._check_return_in_init(tree, filename))
+        return diags
+
+    def _check_mutable_defaults(self, tree: ast.Module, filename: str) -> list[Diagnostic]:
+        diags: list[Diagnostic] = []
+        for node in ast.walk(tree):
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                for default in node.args.defaults + node.args.kw_defaults:
+                    if default is not None and isinstance(default, (ast.List, ast.Dict, ast.Set)):
+                        diags.append(
+                            Diagnostic(
+                                file_path=filename,
+                                rule="no-mutable-default",
+                                severity=Severity.ERROR,
+                                category=Category.CORRECTNESS,
+                                message="Mutable default argument — shared across all calls",
+                                help="Use None as default and create the mutable inside the function body",
+                                line=node.lineno,
+                                column=node.col_offset,
+                                cost=2.0,
+                            )
+                        )
+        return diags
+
+    def _check_bare_except(self, tree: ast.Module, filename: str) -> list[Diagnostic]:
+        diags: list[Diagnostic] = []
+        for node in ast.walk(tree):
+            if isinstance(node, ast.ExceptHandler) and node.type is None:
+                diags.append(
+                    Diagnostic(
+                        file_path=filename,
+                        rule="no-bare-except",
+                        severity=Severity.ERROR,
+                        category=Category.CORRECTNESS,
+                        message="Bare except catches all exceptions including SystemExit and KeyboardInterrupt",
+                        help="Catch a specific exception type, or at minimum use 'except Exception'",
+                        line=node.lineno,
+                        column=node.col_offset,
+                        cost=2.0,
+                    )
+                )
+        return diags
+
+    def _check_broad_exception(self, tree: ast.Module, filename: str) -> list[Diagnostic]:
+        diags: list[Diagnostic] = []
+        for node in ast.walk(tree):
+            if isinstance(node, ast.ExceptHandler) and node.type is not None:
+                if isinstance(node.type, ast.Name) and node.type.id in (
+                    "Exception",
+                    "BaseException",
+                ):
+                    diags.append(
+                        Diagnostic(
+                            file_path=filename,
+                            rule="no-broad-exception",
+                            severity=Severity.WARNING,
+                            category=Category.CORRECTNESS,
+                            message=f"Catching '{node.type.id}' is too broad — masks real errors",
+                            help="Catch specific exception types (ValueError, TypeError, etc.)",
+                            line=node.lineno,
+                            column=node.col_offset,
+                            cost=1.0,
+                        )
+                    )
+        return diags
+
+    def _check_assert_in_production(self, tree: ast.Module, filename: str) -> list[Diagnostic]:
+        if filename.startswith("test_") or "/test_" in filename or filename.endswith("_test.py"):
+            return []
+
+        diags: list[Diagnostic] = []
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Assert):
+                diags.append(
+                    Diagnostic(
+                        file_path=filename,
+                        rule="no-assert-in-production",
+                        severity=Severity.WARNING,
+                        category=Category.CORRECTNESS,
+                        message="assert statements are stripped with python -O flag",
+                        help="Use explicit if/raise for production validation",
+                        line=node.lineno,
+                        column=node.col_offset,
+                        cost=1.0,
+                    )
+                )
+        return diags
+
+    def _check_return_in_init(self, tree: ast.Module, filename: str) -> list[Diagnostic]:
+        diags: list[Diagnostic] = []
+        for node in ast.walk(tree):
+            if isinstance(node, ast.FunctionDef) and node.name == "__init__":
+                for child in ast.walk(node):
+                    if isinstance(child, ast.Return) and child.value is not None:
+                        diags.append(
+                            Diagnostic(
+                                file_path=filename,
+                                rule="no-return-in-init",
+                                severity=Severity.ERROR,
+                                category=Category.CORRECTNESS,
+                                message="__init__ should not return a value",
+                                help="Remove the return value — __init__ must return None",
+                                line=child.lineno,
+                                column=child.col_offset,
+                                cost=2.0,
+                            )
+                        )
+        return diags

pycodegate/rules/dead_code.py

@@ -0,0 +1,58 @@
+"""Dead code detection via vulture."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+try:
+    import vulture
+except ImportError:
+    vulture = None  # type: ignore[assignment]
+
+from pycodegate.types import Category, Diagnostic, Severity
+
+
+class DeadCodeRules:
+    """Detect unused code using vulture."""
+
+    def check_project(self, project_path: str) -> list[Diagnostic]:
+        """Run vulture on the entire project and return diagnostics."""
+        if vulture is None:
+            return []
+
+        v = vulture.Vulture()
+
+        py_files = list(Path(project_path).rglob("*.py"))
+        ignore = {".venv", "venv", "node_modules", "__pycache__", ".git", "dist", "build"}
+        py_files = [
+            f
+            for f in py_files
+            if not any(part in ignore for part in f.relative_to(project_path).parts)
+        ]
+
+        if not py_files:
+            return []
+
+        # Include whitelist if present
+        whitelist = Path(project_path) / "whitelist.py"
+        scan_paths = [str(f) for f in py_files]
+        if whitelist.exists():
+            scan_paths.append(str(whitelist))
+
+        v.scavenge(scan_paths)
+
+        diags: list[Diagnostic] = []
+        for item in v.get_unused_code(min_confidence=60):
+            diags.append(
+                Diagnostic(
+                    file_path=str(item.filename),
+                    rule="dead-code",
+                    severity=Severity.WARNING,
+                    category=Category.DEAD_CODE,
+                    message=f"Unused {item.typ}: '{item.name}' ({item.confidence}% confidence)",
+                    help="Remove this dead code or add it to a vulture whitelist",
+                    line=item.first_lineno,
+                    cost=0.5,
+                )
+            )
+        return diags

pycodegate/rules/dependencies.py

@@ -0,0 +1,107 @@
+"""Dependency rules: vulnerability scanning via pip-audit."""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+
+from pycodegate.types import Category, Diagnostic, Severity
+
+
+class DependencyRules:
+    """Dependency vulnerability checks using pip-audit (optional)."""
+
+    def check_project(self, project_path: str) -> list[Diagnostic]:
+        if not shutil.which("pip-audit"):
+            return []
+
+        path = Path(project_path)
+        req_file = self._find_or_export_requirements(path)
+        if not req_file:
+            return []
+
+        try:
+            result = subprocess.run(
+                [
+                    "pip-audit",
+                    "--requirement",
+                    str(req_file),
+                    "--format",
+                    "json",
+                    "--output",
+                    "-",
+                ],
+                capture_output=True,
+                text=True,
+                timeout=60,
+            )
+            # pip-audit exits non-zero when vulnerabilities found
+            if not result.stdout.strip():
+                return []
+            data = json.loads(result.stdout)
+        except (subprocess.TimeoutExpired, json.JSONDecodeError, OSError):
+            return []
+        finally:
+            # Clean up temp file if we created one
+            if req_file and str(req_file).startswith(tempfile.gettempdir()):
+                req_file.unlink(missing_ok=True)
+
+        diags: list[Diagnostic] = []
+        for vuln in data.get("dependencies", []):
+            pkg_name = vuln.get("name", "unknown")
+            version = vuln.get("version", "?")
+            for v in vuln.get("vulns", []):
+                vuln_id = v.get("id", "unknown")
+                fix_versions = v.get("fix_versions", [])
+                fix_str = f" (fix: {', '.join(fix_versions)})" if fix_versions else ""
+                diags.append(
+                    Diagnostic(
+                        file_path="requirements",
+                        rule="deps/vulnerability",
+                        severity=Severity.ERROR,
+                        category=Category.DEPENDENCIES,
+                        message=f"{pkg_name}=={version} has known vulnerability {vuln_id}{fix_str}",
+                        help=f"Upgrade {pkg_name} to a patched version",
+                        line=0,
+                        cost=3.0,
+                    )
+                )
+        return diags
+
+    def _find_or_export_requirements(self, path: Path) -> Path | None:
+        # Try existing requirements.txt
+        for name in ["requirements.txt", "requirements.lock"]:
+            req = path / name
+            if req.exists():
+                return req
+
+        # Try uv export
+        if shutil.which("uv") and (path / "pyproject.toml").exists():
+            try:
+                tmp = Path(tempfile.gettempdir()) / "py-gate-reqs.txt"
+                result = subprocess.run(
+                    [
+                        "uv",
+                        "export",
+                        "--no-dev",
+                        "--no-editable",
+                        "--no-emit-project",
+                        "--format",
+                        "requirements-txt",
+                        "--quiet",
+                    ],
+                    capture_output=True,
+                    text=True,
+                    timeout=30,
+                    cwd=str(path),
+                )
+                if result.returncode == 0 and result.stdout.strip():
+                    tmp.write_text(result.stdout)
+                    return tmp
+            except (subprocess.TimeoutExpired, OSError):
+                pass
+
+        return None