python-checkup 0.0.1__py3-none-any.whl

python_checkup/scoring/engine.py

@@ -0,0 +1,397 @@
+from __future__ import annotations
+
+from python_checkup.config import CheckupConfig
+from python_checkup.models import (
+    Category,
+    CategoryScore,
+    CoverageInfo,
+    Diagnostic,
+    HealthReport,
+    ProjectInfo,
+    Severity,
+)
+
+# --- Critical security rules that cap the security score ---
+CRITICAL_RULES: set[str] = {
+    "B608",
+    "S608",  # SQL injection
+    "B105",
+    "S105",  # Hardcoded password string
+    "B106",
+    "S106",  # Hardcoded password in function arg
+    "B107",
+    "S107",  # Hardcoded password in default
+    "B602",
+    "S602",  # subprocess with shell=True
+    "B301",
+    "S301",  # pickle (arbitrary code exec)
+    "B614",  # torch.load
+    "B615",  # HuggingFace unsafe
+    "B701",
+    "S701",  # Jinja2 autoescape false
+    "B501",
+    "S501",  # requests with no cert validation
+}
+
+
+def compute_health_report(
+    diagnostics: list[Diagnostic],
+    project: ProjectInfo,
+    config: CheckupConfig,
+    duration_ms: int,
+    analyzers_used: list[str],
+    analyzers_skipped: list[str],
+    mi_scores: list[float] | None = None,
+    cache_stats: dict[str, int] | None = None,
+    coverage: CoverageInfo | None = None,
+) -> HealthReport:
+    """Compute the full health report from diagnostics and metadata.
+
+    This is the main entry point for scoring. It:
+    1. Determines which categories are active (have analyzers)
+    2. Redistributes weights for missing categories
+    3. Computes per-category scores
+    4. Computes the weighted overall score
+    5. Assembles the HealthReport
+    """
+    # Determine available categories from the tools that ran
+    available_categories = _categories_from_analyzers(analyzers_used)
+
+    # Redistribute weights
+    redistributed = redistribute_weights(config.weights, available_categories)
+
+    # Compute per-category scores
+    kloc = max(project.total_lines / 1000.0, 0.1)
+    category_scores: list[CategoryScore] = []
+
+    for cat, weight in redistributed.items():
+        cat_diags = [d for d in diagnostics if d.category == cat]
+        errors = sum(1 for d in cat_diags if d.severity == Severity.ERROR)
+        warnings = sum(1 for d in cat_diags if d.severity == Severity.WARNING)
+
+        score: float
+        match cat:
+            case Category.QUALITY:
+                score = _score_quality(cat_diags, kloc)
+            case Category.TYPE_SAFETY:
+                score = _score_type_safety(cat_diags, project.total_files)
+            case Category.SECURITY:
+                score = _score_security(cat_diags)
+            case Category.COMPLEXITY:
+                score = _score_complexity(mi_scores or [], cat_diags)
+            case Category.DEAD_CODE:
+                score = _score_dead_code(cat_diags, project.total_lines)
+            case Category.DEPENDENCIES:
+                score = _score_dependencies(cat_diags)
+
+        details = _build_details(errors, warnings, len(cat_diags))
+        coverage_note = ""
+        status = "scored"
+        if coverage is not None:
+            for item in coverage.category_coverage:
+                if item.category == cat:
+                    status = item.status
+                    coverage_note = item.reason
+                    break
+        category_scores.append(
+            CategoryScore(
+                category=cat,
+                score=int(score),
+                weight=weight,
+                issue_count=len(cat_diags),
+                error_count=errors,
+                warning_count=warnings,
+                details=details,
+                status=status,
+                coverage_note=coverage_note,
+            )
+        )
+
+    # Overall score
+    overall, label = _compute_overall(category_scores, config.thresholds)
+
+    return HealthReport(
+        score=overall,
+        label=label,
+        category_scores=sorted(
+            category_scores,
+            key=lambda cs: cs.weight,
+            reverse=True,
+        ),
+        diagnostics=diagnostics,
+        project=project,
+        duration_ms=duration_ms,
+        analyzers_used=analyzers_used,
+        analyzers_skipped=analyzers_skipped,
+        cache_stats=cache_stats,
+        coverage=coverage,
+    )
+
+
+# --- Per-category scoring functions ---
+
+
+def _score_quality(diagnostics: list[Diagnostic], kloc: float) -> float:
+    """Score code quality from Ruff diagnostics.
+
+    Normalizes by KLOC so a 500-line project and a 50,000-line
+    project are scored on the same scale.
+
+    Deductions: 3 points per error per KLOC, 1 per warning per KLOC.
+    """
+    errors = sum(1 for d in diagnostics if d.severity == Severity.ERROR)
+    warnings = sum(1 for d in diagnostics if d.severity == Severity.WARNING)
+    penalty = (3.0 * errors / kloc) + (1.0 * warnings / kloc)
+    return max(0.0, min(100.0, 100.0 - penalty))
+
+
+def _score_type_safety(diagnostics: list[Diagnostic], total_files: int) -> float:
+    """Score type safety from mypy diagnostics.
+
+    Uses file-level pass rate: what percentage of files have zero
+    type errors. This rewards gradual typing adoption.
+    """
+    if total_files <= 0:
+        return 100.0
+    files_with_errors = len(
+        {d.file_path for d in diagnostics if d.severity == Severity.ERROR}
+    )
+    pass_rate = 1.0 - (files_with_errors / total_files)
+    return max(0.0, min(100.0, pass_rate * 100.0))
+
+
+def _score_security(diagnostics: list[Diagnostic]) -> float:
+    """Score security from Bandit/Ruff S-rule diagnostics.
+
+    Only errors and warnings affect the score.  INFO-level findings
+    (e.g. B404 "import subprocess", B603 "subprocess without shell")
+    are advisory notices, not actionable problems, so they are shown
+    in the report but do not penalise the score.
+
+    Critical findings (SQL injection, hardcoded secrets, pickle)
+    immediately cap the score at 25.
+    """
+    if not diagnostics:
+        return 100.0
+
+    score = 100.0
+    has_critical = False
+
+    for d in diagnostics:
+        match d.severity:
+            case Severity.ERROR:
+                score -= 15.0
+            case Severity.WARNING:
+                score -= 5.0
+            case Severity.INFO:
+                pass  # advisory — no penalty
+        if d.rule_id in CRITICAL_RULES:
+            has_critical = True
+
+    if has_critical:
+        score = min(score, 25.0)
+
+    return max(0.0, score)
+
+
+def _score_complexity(mi_scores: list[float], diagnostics: list[Diagnostic]) -> float:
+    """Score complexity using Radon's Maintainability Index.
+
+    MI is a 0-100 scale where higher is better, but it is *not*
+    directly usable as a quality score.  Industry convention (Microsoft
+    Visual Studio, Radon docs) treats MI >= 20 as "maintainable" and
+    typical well-written code lands at 40-70.  Using raw MI would make
+    healthy codebases look mediocre.
+
+    We rescale so the practical MI range maps to an intuitive score:
+
+        MI >= 65  → 100  (excellent)
+        MI 20-65  → 60-100  (linear, good to excellent)
+        MI < 20   → 0-60  (linear, needs work)
+
+    Falls back to CC-based scoring from diagnostics when MI is not
+    available.
+    """
+    if mi_scores:
+        avg_mi = sum(mi_scores) / len(mi_scores)
+        return _mi_to_score(avg_mi)
+
+    # Fallback: use complexity diagnostics (C901 from Ruff)
+    if not diagnostics:
+        return 100.0
+
+    penalty = len(diagnostics) * 5.0
+    return max(0.0, min(100.0, 100.0 - penalty))
+
+
+def _mi_to_score(avg_mi: float) -> float:
+    """Convert a Maintainability Index average to a 0-100 health score."""
+    if avg_mi >= 65.0:
+        return 100.0
+    if avg_mi >= 20.0:
+        # Linear: MI 20 → score 60, MI 65 → score 100
+        return 60.0 + (avg_mi - 20.0) * (40.0 / 45.0)
+    # Below 20: MI 0 → score 0, MI 20 → score 60
+    return max(0.0, avg_mi * 3.0)
+
+
+def _score_dead_code(diagnostics: list[Diagnostic], total_lines: int) -> float:
+    """Score dead code from Vulture diagnostics.
+
+    Formula: 100 - (dead_code_percentage * 2). A project with 10%
+    dead code scores 80. >50% dead code scores 0.
+    """
+    if total_lines <= 0 or not diagnostics:
+        return 100.0
+
+    dead_lines = 0
+    for d in diagnostics:
+        if d.end_line and d.line:
+            dead_lines += d.end_line - d.line + 1
+        else:
+            dead_lines += 1  # Conservative: count as 1 line
+
+    dead_pct = (dead_lines / total_lines) * 100.0
+    return max(0.0, min(100.0, 100.0 - (dead_pct * 2.0)))
+
+
+def _score_dependencies(diagnostics: list[Diagnostic]) -> float:
+    """Score dependency health from dependency advisories and dep hygiene.
+
+    Deductions:
+    - 10 points per known vulnerability (CVE/GHSA/PYSEC)
+    - 5 points per unused dependency (DEP002)
+    - 3 points per missing dependency (DEP001)
+    - 2 points per transitive/misplaced dep (DEP003/DEP004)
+    """
+    if not diagnostics:
+        return 100.0
+
+    score = 100.0
+    for d in diagnostics:
+        rule = d.rule_id.upper()
+        if rule.startswith(("CVE", "GHSA", "PYSEC")):
+            score -= 10.0
+        elif rule == "DEP002":
+            score -= 5.0
+        elif rule == "DEP001":
+            score -= 3.0
+        elif rule in ("DEP003", "DEP004"):
+            score -= 2.0
+        else:
+            score -= 3.0
+
+    return max(0.0, score)
+
+
+# --- Helpers ---
+
+
+def _compute_overall(
+    category_scores: list[CategoryScore],
+    thresholds: dict[str, int],
+) -> tuple[int, str]:
+    active = [cs for cs in category_scores if cs.weight > 0]
+    if not active:
+        return 100, "Healthy"
+
+    total_weight = sum(cs.weight for cs in active)
+    if total_weight == 0:
+        return 100, "Healthy"
+
+    score = sum(cs.score * cs.weight for cs in active) / total_weight
+    score = int(max(0, min(100, score)))
+
+    healthy = thresholds.get("healthy", 75)
+    needs_work = thresholds.get("needs_work", 50)
+
+    if score >= healthy:
+        label = "Healthy"
+    elif score >= needs_work:
+        label = "Needs work"
+    else:
+        label = "Critical"
+
+    return score, label
+
+
+def redistribute_weights(
+    configured_weights: dict[str, int],
+    available_categories: set[Category],
+) -> dict[Category, int]:
+    """Redistribute weights from unavailable categories.
+
+    When a category has no analyzer, its weight is proportionally
+    distributed to the remaining categories so they still sum to 100.
+    """
+    key_to_cat = {
+        "quality": Category.QUALITY,
+        "types": Category.TYPE_SAFETY,
+        "security": Category.SECURITY,
+        "complexity": Category.COMPLEXITY,
+        "dead_code": Category.DEAD_CODE,
+        "dependencies": Category.DEPENDENCIES,
+    }
+
+    # Filter to available categories
+    active: dict[Category, int] = {}
+    for key, w in configured_weights.items():
+        cat = key_to_cat.get(key)
+        if cat and cat in available_categories:
+            active[cat] = w
+
+    if not active:
+        return {}
+
+    total = sum(active.values())
+    if total == 0:
+        return active
+
+    # Proportional redistribution
+    scale = 100.0 / total
+    result = {cat: round(w * scale) for cat, w in active.items()}
+
+    # Fix rounding errors so weights sum to exactly 100
+    diff = 100 - sum(result.values())
+    if diff != 0:
+        largest = max(result, key=lambda c: result[c])
+        result[largest] += diff
+
+    return result
+
+
+def _categories_from_analyzers(
+    analyzers_used: list[str],
+) -> set[Category]:
+    mapping: dict[str, set[Category]] = {
+        "ruff": {
+            Category.QUALITY,
+            Category.SECURITY,
+            Category.COMPLEXITY,
+        },
+        "mypy": {Category.TYPE_SAFETY},
+        "bandit": {Category.SECURITY},
+        "radon": {Category.COMPLEXITY},
+        "vulture": {Category.DEAD_CODE},
+        "deptry": {Category.DEPENDENCIES},
+        "dependency-vulns": {Category.DEPENDENCIES},
+        "detect-secrets": {Category.SECURITY},
+        "basedpyright": {Category.TYPE_SAFETY},
+        "typos": {Category.QUALITY},
+    }
+    categories: set[Category] = set()
+    for name in analyzers_used:
+        categories.update(mapping.get(name, set()))
+    return categories
+
+
+def _build_details(errors: int, warnings: int, total: int) -> str:
+    parts = []
+    if errors:
+        parts.append(f"{errors} error{'s' if errors != 1 else ''}")
+    if warnings:
+        parts.append(f"{warnings} warning{'s' if warnings != 1 else ''}")
+    infos = total - errors - warnings
+    if infos > 0:
+        parts.append(f"{infos} info")
+    return ", ".join(parts) if parts else "No issues"