pycodegate 0.1.0__py3-none-any.whl

pycodegate/__init__.py

@@ -0,0 +1,3 @@
+"""Python Doctor - Diagnose your Python project's health."""
+
+__version__ = "0.1.0"

pycodegate/_compat.py

@@ -0,0 +1,15 @@
+"""Python version compatibility shims."""
+
+from __future__ import annotations
+
+import sys
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    try:
+        import tomllib
+    except ModuleNotFoundError:
+        import tomli as tomllib  # type: ignore[no-redef]
+
+__all__ = ["tomllib"]

pycodegate/api.py

@@ -0,0 +1,26 @@
+"""Programmatic API for python-doctor."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from pycodegate.config import load_config
+from pycodegate.scan import scan_project
+
+if TYPE_CHECKING:
+    from pycodegate.types import ScanResult
+
+
+def diagnose(
+    project_path: str = ".",
+    *,
+    lint: bool = True,
+    dead_code: bool = True,
+    diff_base: str | None = None,
+) -> ScanResult:
+    """Run python-doctor analysis programmatically."""
+    config = load_config(project_path)
+    config.lint = lint
+    config.dead_code = dead_code
+
+    return scan_project(project_path, config, diff_base=diff_base)

pycodegate/cli.py

@@ -0,0 +1,131 @@
+"""CLI entry point for py-doctor."""
+
+from __future__ import annotations
+
+import sys
+
+import click
+
+from pycodegate import __version__
+from pycodegate.config import load_config
+from pycodegate.output import output_json, print_scan_result
+from pycodegate.scan import scan_project
+from pycodegate.types import Severity
+from pycodegate.utils.badge import generate_badge, generate_ci_workflow
+from pycodegate.utils.fixer import run_ruff_fix
+from pycodegate.utils.precommit import install_precommit_hook
+
+
+@click.command(context_settings={"help_option_names": ["-h", "--help"]})
+@click.version_option(__version__, "-v", "--version", prog_name="Py Gate")
+@click.argument("directory", default=".", type=click.Path(exists=True))
+@click.option("--lint/--no-lint", default=True, help="Enable/disable lint checks.")
+@click.option(
+    "--dead-code/--no-dead-code", default=True, help="Enable/disable dead code detection."
+)
+@click.option("--verbose", is_flag=True, help="Show file details per rule.")
+@click.option("--score", "score_only", is_flag=True, help="Output only the numeric score.")
+@click.option("--json", "json_output", is_flag=True, help="Output results as JSON.")
+@click.option(
+    "--diff",
+    "diff_base",
+    default=None,
+    type=str,
+    help="Scan only files changed vs base branch.",
+)
+@click.option(
+    "--fail-on",
+    type=click.Choice(["error", "warning", "none"]),
+    default="none",
+    help="Exit with code 1 on this severity level.",
+)
+@click.option("--fix", "fix", is_flag=True, default=False, help="Auto-fix issues via ruff.")
+@click.option(
+    "--profile",
+    "profile_override",
+    type=click.Choice(["cli", "web", "library", "script"]),
+    default=None,
+    help="Override auto-detected project profile.",
+)
+@click.option(
+    "--badge", "badge", is_flag=True, default=False, help="Output shields.io badge markdown."
+)
+@click.option(
+    "--ci", "ci_workflow", is_flag=True, default=False, help="Output GitHub Actions workflow YAML."
+)
+@click.option(
+    "--pre-commit", "precommit", is_flag=True, default=False, help="Install git pre-commit hook."
+)
+@click.option(
+    "--min-score",
+    "min_score",
+    type=int,
+    default=None,
+    help="Minimum score threshold (exit 1 if below).",
+)
+def main(
+    directory: str,
+    lint: bool,
+    dead_code: bool,
+    verbose: bool,
+    score_only: bool,
+    json_output: bool,
+    diff_base: str | None,
+    fail_on: str,
+    fix: bool,
+    profile_override: str | None,
+    badge: bool,
+    ci_workflow: bool,
+    precommit: bool,
+    min_score: int | None,
+) -> None:
+    """Py Gate — Diagnose your Python project's health."""
+    if ci_workflow:
+        click.echo(generate_ci_workflow(), nl=False)
+        return
+
+    if precommit:
+        effective_min = min_score if min_score is not None else 50
+        msg = install_precommit_hook(directory, min_score=effective_min)
+        click.echo(msg)
+        return
+
+    if fix:
+        fixes = run_ruff_fix(directory)
+        if fixes == -1:
+            click.echo("ruff not found, skipping auto-fix")
+        else:
+            click.echo(f"Fixed {fixes} issues via ruff")
+
+    config = load_config(directory)
+    config.lint = lint
+    config.dead_code = dead_code
+    config.verbose = verbose
+    config.fail_on = fail_on
+    if profile_override is not None:
+        config.profile = profile_override
+
+    result = scan_project(directory, config, diff_base=diff_base)
+
+    if badge:
+        click.echo(generate_badge(result.score.value, result.score.label))
+        return
+
+    if json_output:
+        output_json(result)
+    elif score_only:
+        click.echo(str(result.score.value))
+    else:
+        print_scan_result(result, verbose=verbose)
+
+    # Exit code based on --fail-on
+    has_errors = any(d.severity == Severity.ERROR for d in result.diagnostics)
+    if (fail_on == "error" and has_errors) or (fail_on == "warning" and result.diagnostics):
+        sys.exit(1)
+
+    if min_score is not None and result.score.value < min_score:
+        click.echo(
+            f"py-gate: score {result.score.value} is below minimum {min_score}",
+            err=True,
+        )
+        sys.exit(1)

pycodegate/config.py

@@ -0,0 +1,81 @@
+"""Configuration loading for py-gate."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from pycodegate._compat import tomllib
+
+
+@dataclass
+class Config:
+    lint: bool = True
+    dead_code: bool = True
+    verbose: bool = False
+    fail_on: str = "none"
+    ignore_rules: list[str] = field(default_factory=list)
+    ignore_files: list[str] = field(default_factory=list)
+    profile: str | None = None
+    per_file_suppress: dict[str, list[str]] = field(default_factory=dict)
+    max_deduction: dict[str, int] = field(default_factory=dict)
+
+
+def load_config(project_path: str) -> Config:
+    """Load config from py-gate.toml or pyproject.toml [tool.py-gate]."""
+    root = Path(project_path)
+
+    # py-gate.toml takes precedence
+    doctor_toml = root / "py-gate.toml"
+    if doctor_toml.exists():
+        return _parse_doctor_toml(doctor_toml)
+
+    # Fall back to pyproject.toml
+    pyproject = root / "pyproject.toml"
+    if pyproject.exists():
+        return _parse_pyproject_toml(pyproject)
+
+    return Config()
+
+
+def _parse_doctor_toml(path: Path) -> Config:
+    with open(path, "rb") as f:
+        data = tomllib.load(f)
+
+    options = data.get("options", {})
+    ignore = data.get("ignore", {})
+
+    return Config(
+        lint=options.get("lint", True),
+        dead_code=options.get("dead_code", True),
+        verbose=options.get("verbose", False),
+        fail_on=options.get("fail_on", "none"),
+        ignore_rules=ignore.get("rules", []),
+        ignore_files=ignore.get("files", []),
+        profile=options.get("profile", None),
+        per_file_suppress=data.get("per-file-suppress", {}),
+        max_deduction=data.get("max-deduction", {}),
+    )
+
+
+def _parse_pyproject_toml(path: Path) -> Config:
+    with open(path, "rb") as f:
+        data = tomllib.load(f)
+
+    section = data.get("tool", {}).get("py-gate", {})
+    if not section:
+        return Config()
+
+    ignore = section.get("ignore", {})
+
+    return Config(
+        lint=section.get("lint", True),
+        dead_code=section.get("dead_code", True),
+        verbose=section.get("verbose", False),
+        fail_on=section.get("fail_on", "none"),
+        ignore_rules=ignore.get("rules", []),
+        ignore_files=ignore.get("files", []),
+        profile=section.get("profile", None),
+        per_file_suppress=section.get("per-file-suppress", {}),
+        max_deduction=section.get("max-deduction", {}),
+    )

pycodegate/constants.py

@@ -0,0 +1,32 @@
+"""Constants and thresholds for python-doctor."""
+
+from pycodegate.types import Category
+
+# Score thresholds
+SCORE_GREAT = 75
+SCORE_NEEDS_WORK = 50
+
+# Labels
+LABEL_EXCELLENT = "Excellent"
+LABEL_GREAT = "Great"
+LABEL_NEEDS_WORK = "Needs work"
+LABEL_CRITICAL = "Critical"
+
+# Category weights for budget-based scoring
+CATEGORY_WEIGHTS: dict = {
+    Category.SECURITY: 5,
+    Category.CORRECTNESS: 4,
+    Category.COMPLEXITY: 3,
+    Category.ARCHITECTURE: 3,
+    Category.PERFORMANCE: 2,
+    Category.STRUCTURE: 2,
+    Category.IMPORTS: 1,
+    Category.DEAD_CODE: 1,
+}
+
+# Framework categories map to their parent category for scoring
+FRAMEWORK_CATEGORY_MAP: dict = {
+    Category.DJANGO: Category.SECURITY,
+    Category.FASTAPI: Category.CORRECTNESS,
+    Category.FLASK: Category.SECURITY,
+}

pycodegate/discover.py

@@ -0,0 +1,114 @@
+"""Project discovery: detect framework, Python version, package manager, etc."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from pycodegate._compat import tomllib
+from pycodegate.types import ProjectInfo
+from pycodegate.utils.file_discovery import find_python_files
+
+
+def discover_project(project_path: str) -> ProjectInfo:
+    """Auto-detect project characteristics."""
+    root = Path(project_path)
+    deps = _collect_all_deps(root)
+
+    return ProjectInfo(
+        path=project_path,
+        python_version=_detect_python_version(root),
+        framework=_detect_framework(deps),
+        package_manager=_detect_package_manager(root),
+        test_framework=_detect_test_framework(deps),
+        has_type_hints=_detect_type_hints(root),
+        source_file_count=len(find_python_files(project_path)),
+    )
+
+
+def _collect_all_deps(root: Path) -> set[str]:
+    """Collect dependency names from all sources."""
+    deps: set[str] = set()
+
+    # pyproject.toml
+    pyproject = root / "pyproject.toml"
+    if pyproject.exists():
+        with open(pyproject, "rb") as f:
+            data = tomllib.load(f)
+        project = data.get("project", {})
+        for dep in project.get("dependencies", []):
+            deps.add(_parse_dep_name(dep))
+        for group_deps in project.get("optional-dependencies", {}).values():
+            for dep in group_deps:
+                deps.add(_parse_dep_name(dep))
+        # Poetry format
+        poetry = data.get("tool", {}).get("poetry", {})
+        for dep in poetry.get("dependencies", {}):
+            deps.add(dep.lower())
+        for group in poetry.get("group", {}).values():
+            for dep in group.get("dependencies", {}):
+                deps.add(dep.lower())
+
+    # requirements.txt
+    for req_file in ["requirements.txt", "requirements-dev.txt", "requirements_dev.txt"]:
+        req_path = root / req_file
+        if req_path.exists():
+            for line in req_path.read_text().splitlines():
+                line = line.strip()
+                if line and not line.startswith(("#", "-")):
+                    deps.add(_parse_dep_name(line))
+
+    return deps
+
+
+def _parse_dep_name(dep_str: str) -> str:
+    """Extract package name from a dependency specifier like 'django>=4.2'."""
+    return re.split(r"[><=!~\[;@\s]", dep_str)[0].strip().lower()
+
+
+def _detect_framework(deps: set[str]) -> str | None:
+    if "django" in deps or "django-rest-framework" in deps or "djangorestframework" in deps:
+        return "django"
+    if "fastapi" in deps:
+        return "fastapi"
+    if "flask" in deps:
+        return "flask"
+    return None
+
+
+def _detect_package_manager(root: Path) -> str | None:
+    if (root / "uv.lock").exists():
+        return "uv"
+    if (root / "poetry.lock").exists():
+        return "poetry"
+    if (root / "Pipfile.lock").exists():
+        return "pipenv"
+    if (root / "requirements.txt").exists():
+        return "pip"
+    if (root / "pyproject.toml").exists():
+        return "pip"
+    return None
+
+
+def _detect_test_framework(deps: set[str]) -> str | None:
+    if "pytest" in deps:
+        return "pytest"
+    if "unittest" in deps:
+        return "unittest"
+    return None
+
+
+def _detect_python_version(root: Path) -> str | None:
+    pyproject = root / "pyproject.toml"
+    if pyproject.exists():
+        with open(pyproject, "rb") as f:
+            data = tomllib.load(f)
+        requires = data.get("project", {}).get("requires-python", "")
+        match = re.search(r"(\d+\.\d+)", requires)
+        if match:
+            return match.group(1)
+    return None
+
+
+def _detect_type_hints(root: Path) -> bool:
+    return (root / "py.typed").exists() or (root / "mypy.ini").exists()

pycodegate/output.py

@@ -0,0 +1,270 @@
+"""Rich terminal output: score bar, doctor face, framed summary, category-grouped diagnostics."""
+
+from __future__ import annotations
+
+import json
+import sys
+from collections import defaultdict
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.text import Text
+
+from pycodegate import __version__
+from pycodegate.constants import CATEGORY_WEIGHTS, FRAMEWORK_CATEGORY_MAP
+from pycodegate.types import Category, Diagnostic, ScanResult, Severity
+
+BAR_WIDTH = 50
+
+# Doctor ASCII faces
+_HAPPY = r"""
+  ┌─────┐
+  │ ◕ ◕ │
+  │  ◡  │
+  └─────┘
+"""
+
+_NEUTRAL = r"""
+  ┌─────┐
+  │ ◑ ◑ │
+  │  ━  │
+  └─────┘
+"""
+
+_SAD = r"""
+  ┌─────┐
+  │ ◔ ◔ │
+  │  ◠  │
+  └─────┘
+"""
+
+# Display metadata for each category
+CATEGORY_DISPLAY: dict[Category, tuple[str, str]] = {
+    Category.SECURITY: ("🔒", "Security"),
+    Category.CORRECTNESS: ("✓", "Correctness"),
+    Category.COMPLEXITY: ("⚡", "Complexity"),
+    Category.ARCHITECTURE: ("🏗", "Architecture"),
+    Category.PERFORMANCE: ("🐎", "Performance"),
+    Category.STRUCTURE: ("📁", "Structure"),
+    Category.IMPORTS: ("📦", "Imports"),
+    Category.DEAD_CODE: ("💀", "Dead Code"),
+    Category.DEPENDENCIES: ("🛡", "Dependencies"),
+}
+
+
+def format_score_bar(score: int) -> str:
+    """Return a text-based score bar."""
+    filled = round(score / 100 * BAR_WIDTH)
+    empty = BAR_WIDTH - filled
+    bar = "█" * filled + "░" * empty
+    return f"  {bar} {score}"
+
+
+def format_doctor_face(score: int) -> str:
+    """Return doctor ASCII art based on score."""
+    if score >= 75:
+        return _HAPPY
+    elif score >= 50:
+        return _NEUTRAL
+    else:
+        return _SAD
+
+
+def _score_color(score: int) -> str:
+    if score >= 75:
+        return "green"
+    elif score >= 50:
+        return "yellow"
+    return "red"
+
+
+def _compute_category_sub_scores(
+    diagnostics: list[Diagnostic],
+) -> dict[Category, tuple[int, int]]:
+    """Return {resolved_category: (earned, max)} for each category in CATEGORY_WEIGHTS."""
+    total_weight = sum(CATEGORY_WEIGHTS.values())
+    max_deductions = {cat: round(w / total_weight * 100) for cat, w in CATEGORY_WEIGHTS.items()}
+    # Fix rounding to ensure sum == 100
+    diff = 100 - sum(max_deductions.values())
+    if diff != 0:
+        highest = max(CATEGORY_WEIGHTS, key=lambda k: CATEGORY_WEIGHTS[k])
+        max_deductions[highest] += diff
+
+    # Group diagnostics by resolved category
+    by_category: dict[Category, list[Diagnostic]] = defaultdict(list)
+    for d in diagnostics:
+        resolved = FRAMEWORK_CATEGORY_MAP.get(d.category, d.category)
+        by_category[resolved].append(d)
+
+    # Compute actual deduction per category (same logic as score.py)
+    actual_deductions: dict[Category, float] = {}
+    for cat, diags in by_category.items():
+        costs = sorted([d.cost for d in diags], reverse=True)
+        cat_total = sum(c if i < 3 else c * 0.1 for i, c in enumerate(costs))
+        cap = max_deductions.get(cat, 10)
+        actual_deductions[cat] = min(cat_total, cap)
+
+    # Build (earned, max) per category
+    result: dict[Category, tuple[int, int]] = {}
+    for cat, max_ded in max_deductions.items():
+        deducted = round(actual_deductions.get(cat, 0.0))
+        earned = max_ded - deducted
+        result[cat] = (earned, max_ded)
+
+    return result
+
+
+def format_summary(result: ScanResult) -> str:
+    """Format the full scan summary as a string (for testing)."""
+    lines: list[str] = []
+    lines.append(format_doctor_face(result.score.value))
+    lines.append(f"  Score: {result.score.value}/100 — {result.score.label}")
+    lines.append(format_score_bar(result.score.value))
+    lines.append("")
+
+    errors = sum(1 for d in result.diagnostics if d.severity == Severity.ERROR)
+    warnings = sum(1 for d in result.diagnostics if d.severity == Severity.WARNING)
+    files = len({d.file_path for d in result.diagnostics})
+
+    lines.append(f"  {errors} errors, {warnings} warnings across {files} files")
+    lines.append(f"  Completed in {result.elapsed_ms}ms")
+    return "\n".join(lines)
+
+
+def print_scan_result(result: ScanResult, verbose: bool = False) -> None:
+    """Print the full scan result to terminal using Rich."""
+    console = Console()
+
+    # Project info header
+    p = result.project
+    console.print()
+    console.print("  [bold]Py Gate[/bold] — v0.1.0")
+    console.print()
+    console.print(f"  [dim]Path:[/dim]            {p.path}")
+    if p.python_version:
+        console.print(f"  [dim]Python:[/dim]          {p.python_version}")
+    if p.package_manager:
+        console.print(f"  [dim]Package manager:[/dim] {p.package_manager}")
+    if p.test_framework:
+        console.print(f"  [dim]Test framework:[/dim]  {p.test_framework}")
+    if result.profile:
+        console.print(f"  [dim]Profile:[/dim]         {result.profile}")
+    console.print(f"  [dim]Source files:[/dim]    {p.source_file_count}")
+    console.print()
+
+    # Category-grouped diagnostics with sub-scores
+    _print_category_groups(console, result.diagnostics, verbose)
+
+    # Summary panel
+    color = _score_color(result.score.value)
+    face = format_doctor_face(result.score.value).strip()
+
+    errors = sum(1 for d in result.diagnostics if d.severity == Severity.ERROR)
+    warnings = sum(1 for d in result.diagnostics if d.severity == Severity.WARNING)
+    files = len({d.file_path for d in result.diagnostics})
+
+    summary = Text()
+    summary.append(f"\n{face}\n\n", style="bold")
+    summary.append("  Score: ", style="dim")
+    summary.append(f"{result.score.value}/100", style=f"bold {color}")
+    summary.append(f" — {result.score.label}\n", style=color)
+    summary.append(f"{format_score_bar(result.score.value)}\n\n")
+    summary.append(f"  {errors} errors, {warnings} warnings across {files} files\n", style="dim")
+    summary.append(f"  Completed in {result.elapsed_ms}ms\n", style="dim")
+
+    console.print(Panel(summary, title="[bold]Results[/bold]", border_style=color))
+    console.print()
+
+
+def output_json(result: ScanResult) -> None:
+    """Output the scan result as structured JSON to stdout."""
+    p = result.project
+    errors = sum(1 for d in result.diagnostics if d.severity == Severity.ERROR)
+    warnings = sum(1 for d in result.diagnostics if d.severity == Severity.WARNING)
+
+    payload = {
+        "version": __version__,
+        "path": p.path,
+        "score": result.score.value,
+        "label": result.score.label,
+        "errors": errors,
+        "warnings": warnings,
+        "elapsed_ms": result.elapsed_ms,
+        "project": {
+            "framework": p.framework,
+            "python_version": p.python_version,
+            "package_manager": p.package_manager,
+            "test_framework": p.test_framework,
+            "source_file_count": p.source_file_count,
+        },
+        "diagnostics": [
+            {
+                "rule": d.rule,
+                "severity": d.severity.value,
+                "category": d.category.value,
+                "message": d.message,
+                "help": d.help,
+                "file_path": d.file_path,
+                "line": d.line,
+            }
+            for d in result.diagnostics
+        ],
+    }
+    sys.stdout.write(json.dumps(payload, indent=2) + "\n")
+
+
+def _print_category_groups(
+    console: Console,
+    diagnostics: list[Diagnostic],
+    verbose: bool,
+) -> None:
+    """Print diagnostics grouped by category with sub-scores."""
+    sub_scores = _compute_category_sub_scores(diagnostics)
+
+    # Build rule-grouped diagnostics per resolved category
+    by_category: dict[Category, list[Diagnostic]] = defaultdict(list)
+    for d in diagnostics:
+        resolved = FRAMEWORK_CATEGORY_MAP.get(d.category, d.category)
+        by_category[resolved].append(d)
+
+    # Iterate in canonical order (CATEGORY_WEIGHTS order)
+    for cat in CATEGORY_WEIGHTS:
+        if cat not in CATEGORY_DISPLAY:
+            continue
+        emoji, name = CATEGORY_DISPLAY[cat]
+        earned, maximum = sub_scores.get(cat, (CATEGORY_WEIGHTS[cat], CATEGORY_WEIGHTS[cat]))
+        # Recompute max from sub_scores (already normalised to 100-point scale)
+        cat_diags = by_category.get(cat, [])
+
+        if earned == maximum:
+            # Perfect score for this category
+            console.print(
+                f"  [bold]{emoji} {name}[/bold] "
+                f"[green]({earned}/{maximum})[/green] [green]✓[/green]"
+            )
+            console.print("    [green]✓ All clear.[/green]")
+        else:
+            console.print(f"  [bold]{emoji} {name}[/bold] [yellow]({earned}/{maximum})[/yellow]")
+            # Group by rule within this category
+            by_rule: dict[str, list[Diagnostic]] = defaultdict(list)
+            for d in cat_diags:
+                by_rule[d.rule].append(d)
+
+            # Sort: errors first, then by rule name
+            sorted_rules = sorted(
+                by_rule.keys(),
+                key=lambda r: (0 if by_rule[r][0].severity == Severity.ERROR else 1, r),
+            )
+            for rule in sorted_rules:
+                rule_diags = by_rule[rule]
+                count = len(rule_diags)
+                sev = rule_diags[0].severity
+                icon = "[red]✗[/red]" if sev == Severity.ERROR else "[yellow]⚠[/yellow]"
+                console.print(f"    {icon} {rule} × {count}")
+                if verbose:
+                    for d in rule_diags[:10]:
+                        console.print(f"      [dim]{d.file_path}:{d.line}[/dim]")
+                    if count > 10:
+                        console.print(f"      [dim]... and {count - 10} more[/dim]")
+
+        console.print()