greenmining 1.0.5__py3-none-any.whl → 1.0.6__py3-none-any.whl

greenmining/__init__.py

@@ -9,7 +9,7 @@ from greenmining.gsf_patterns import (
     is_green_aware,
 )
 
-__version__ = "1.0.5"
+__version__ = "1.0.6"
 
 
 def fetch_repositories(
@@ -32,6 +32,49 @@ def fetch_repositories(
     )
 
 
+def analyze_repositories(
+    urls: list,
+    max_commits: int = 500,
+    parallel_workers: int = 1,
+    output_format: str = "dict",
+    energy_tracking: bool = False,
+    energy_backend: str = "rapl",
+    method_level_analysis: bool = False,
+    include_source_code: bool = False,
+    ssh_key_path: str = None,
+    github_token: str = None,
+):
+    # Analyze multiple repositories from URLs.
+    # Args:
+    #   urls: List of GitHub repository URLs
+    #   max_commits: Maximum commits to analyze per repository
+    #   parallel_workers: Number of parallel analysis workers (1=sequential)
+    #   output_format: Output format (dict, json, csv)
+    #   energy_tracking: Enable automatic energy measurement during analysis
+    #   energy_backend: Energy backend (rapl, codecarbon, cpu_meter, auto)
+    #   method_level_analysis: Include per-method metrics via Lizard
+    #   include_source_code: Include source code before/after in results
+    #   ssh_key_path: SSH key path for private repositories
+    #   github_token: GitHub token for private HTTPS repositories
+    from greenmining.services.local_repo_analyzer import LocalRepoAnalyzer
+
+    analyzer = LocalRepoAnalyzer(
+        max_commits=max_commits,
+        energy_tracking=energy_tracking,
+        energy_backend=energy_backend,
+        method_level_analysis=method_level_analysis,
+        include_source_code=include_source_code,
+        ssh_key_path=ssh_key_path,
+        github_token=github_token,
+    )
+
+    return analyzer.analyze_repositories(
+        urls=urls,
+        parallel_workers=parallel_workers,
+        output_format=output_format,
+    )
+
+
 __all__ = [
     "Config",
     "GSF_PATTERNS",
@@ -39,5 +82,6 @@ __all__ = [
     "is_green_aware",
     "get_pattern_by_keywords",
     "fetch_repositories",
+    "analyze_repositories",
     "__version__",
-]
+]

greenmining/analyzers/__init__.py

@@ -4,10 +4,19 @@ from .code_diff_analyzer import CodeDiffAnalyzer
 from .statistical_analyzer import StatisticalAnalyzer
 from .temporal_analyzer import TemporalAnalyzer
 from .qualitative_analyzer import QualitativeAnalyzer
+from .power_regression import PowerRegressionDetector, PowerRegression
+from .metrics_power_correlator import MetricsPowerCorrelator, CorrelationResult
+from .version_power_analyzer import VersionPowerAnalyzer, VersionPowerReport
 
 __all__ = [
     "CodeDiffAnalyzer",
     "StatisticalAnalyzer",
     "TemporalAnalyzer",
     "QualitativeAnalyzer",
+    "PowerRegressionDetector",
+    "PowerRegression",
+    "MetricsPowerCorrelator",
+    "CorrelationResult",
+    "VersionPowerAnalyzer",
+    "VersionPowerReport",
 ]

greenmining/analyzers/metrics_power_correlator.py

@@ -0,0 +1,165 @@
+# Metrics-to-power correlation analysis.
+# Build models correlating code metrics (complexity, nloc, churn) with power consumption.
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Tuple
+
+import numpy as np
+from scipy import stats
+
+
+@dataclass
+class CorrelationResult:
+    # Result of a metrics-to-power correlation analysis.
+
+    metric_name: str
+    pearson_r: float = 0.0
+    pearson_p: float = 1.0
+    spearman_r: float = 0.0
+    spearman_p: float = 1.0
+    significant: bool = False
+    strength: str = "none"
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "metric_name": self.metric_name,
+            "pearson_r": round(self.pearson_r, 4),
+            "pearson_p": round(self.pearson_p, 6),
+            "spearman_r": round(self.spearman_r, 4),
+            "spearman_p": round(self.spearman_p, 6),
+            "significant": self.significant,
+            "strength": self.strength,
+        }
+
+
+class MetricsPowerCorrelator:
+    # Correlate code metrics with power consumption measurements.
+    # Computes Pearson and Spearman correlations between software metrics
+    # and measured energy/power values.
+
+    def __init__(self, significance_level: float = 0.05):
+        # Initialize correlator.
+        # Args:
+        #   significance_level: P-value threshold for significance
+        self.significance_level = significance_level
+        self._metrics_data: Dict[str, List[float]] = {}
+        self._power_data: List[float] = []
+        self._fitted = False
+        self._results: Dict[str, CorrelationResult] = {}
+        self._feature_importance: Dict[str, float] = {}
+
+    def fit(
+        self,
+        metrics: List[str],
+        metrics_values: Dict[str, List[float]],
+        power_measurements: List[float],
+    ) -> None:
+        # Fit the correlator with metrics and power data.
+        # Args:
+        #   metrics: List of metric names to correlate
+        #   metrics_values: Dict mapping metric name -> list of values
+        #   power_measurements: List of power measurement values
+        self._metrics_data = {m: metrics_values[m] for m in metrics if m in metrics_values}
+        self._power_data = power_measurements
+
+        n = len(power_measurements)
+        if n < 3:
+            raise ValueError("Need at least 3 data points for correlation analysis")
+
+        # Compute correlations
+        for metric_name, values in self._metrics_data.items():
+            if len(values) != n:
+                continue
+
+            result = self._compute_correlation(metric_name, values, power_measurements)
+            self._results[metric_name] = result
+
+        # Compute feature importance (normalized absolute Spearman)
+        max_abs = max((abs(r.spearman_r) for r in self._results.values()), default=1.0)
+        if max_abs > 0:
+            self._feature_importance = {
+                name: abs(r.spearman_r) / max_abs for name, r in self._results.items()
+            }
+
+        self._fitted = True
+
+    def _compute_correlation(
+        self, metric_name: str, metric_values: List[float], power_values: List[float]
+    ) -> CorrelationResult:
+        # Compute Pearson and Spearman correlations for a single metric.
+        x = np.array(metric_values, dtype=float)
+        y = np.array(power_values, dtype=float)
+
+        # Handle constant arrays
+        if np.std(x) == 0 or np.std(y) == 0:
+            return CorrelationResult(metric_name=metric_name)
+
+        # Pearson correlation (linear)
+        pearson_r, pearson_p = stats.pearsonr(x, y)
+
+        # Spearman correlation (monotonic)
+        spearman_r, spearman_p = stats.spearmanr(x, y)
+
+        # Significance
+        significant = pearson_p < self.significance_level or spearman_p < self.significance_level
+
+        # Strength classification
+        abs_r = max(abs(pearson_r), abs(spearman_r))
+        if abs_r >= 0.7:
+            strength = "strong"
+        elif abs_r >= 0.4:
+            strength = "moderate"
+        elif abs_r >= 0.2:
+            strength = "weak"
+        else:
+            strength = "negligible"
+
+        return CorrelationResult(
+            metric_name=metric_name,
+            pearson_r=float(pearson_r),
+            pearson_p=float(pearson_p),
+            spearman_r=float(spearman_r),
+            spearman_p=float(spearman_p),
+            significant=significant,
+            strength=strength,
+        )
+
+    @property
+    def pearson(self) -> Dict[str, float]:
+        # Get Pearson correlations for all metrics.
+        return {name: r.pearson_r for name, r in self._results.items()}
+
+    @property
+    def spearman(self) -> Dict[str, float]:
+        # Get Spearman correlations for all metrics.
+        return {name: r.spearman_r for name, r in self._results.items()}
+
+    @property
+    def feature_importance(self) -> Dict[str, float]:
+        # Get normalized feature importance scores.
+        return self._feature_importance
+
+    def get_results(self) -> Dict[str, CorrelationResult]:
+        # Get all correlation results.
+        return self._results
+
+    def get_significant_correlations(self) -> Dict[str, CorrelationResult]:
+        # Get only statistically significant correlations.
+        return {name: r for name, r in self._results.items() if r.significant}
+
+    def summary(self) -> Dict[str, Any]:
+        # Generate summary of correlation analysis.
+        return {
+            "total_metrics": len(self._results),
+            "significant_count": sum(1 for r in self._results.values() if r.significant),
+            "correlations": {name: r.to_dict() for name, r in self._results.items()},
+            "feature_importance": self._feature_importance,
+            "strongest_positive": max(
+                self._results.values(), key=lambda r: r.spearman_r, default=None
+            ),
+            "strongest_negative": min(
+                self._results.values(), key=lambda r: r.spearman_r, default=None
+            ),
+        }

greenmining/analyzers/power_regression.py

@@ -0,0 +1,212 @@
+# Power regression detection for identifying commits that increased power consumption.
+# Compares energy measurements between baseline and target commits.
+
+from __future__ import annotations
+
+import subprocess
+import time
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+from pydriller import Repository
+
+from greenmining.utils import colored_print
+
+
+@dataclass
+class PowerRegression:
+    # A detected power regression from a commit.
+
+    sha: str
+    message: str
+    author: str
+    date: str
+    power_before: float  # watts
+    power_after: float  # watts
+    power_increase: float  # percentage
+    energy_before: float  # joules
+    energy_after: float  # joules
+    is_regression: bool = True
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "sha": self.sha,
+            "message": self.message,
+            "author": self.author,
+            "date": self.date,
+            "power_before": round(self.power_before, 4),
+            "power_after": round(self.power_after, 4),
+            "power_increase": round(self.power_increase, 2),
+            "energy_before": round(self.energy_before, 4),
+            "energy_after": round(self.energy_after, 4),
+            "is_regression": self.is_regression,
+        }
+
+
+class PowerRegressionDetector:
+    # Detect commits that caused power consumption regressions.
+    # Runs a test command at each commit and measures energy usage.
+
+    def __init__(
+        self,
+        test_command: str = "pytest tests/ -x",
+        energy_backend: str = "rapl",
+        threshold_percent: float = 5.0,
+        iterations: int = 5,
+        warmup_iterations: int = 1,
+    ):
+        # Initialize power regression detector.
+        # Args:
+        #   test_command: Shell command to run for energy measurement
+        #   energy_backend: Energy measurement backend (rapl, codecarbon, cpu_meter)
+        #   threshold_percent: Minimum percentage increase to flag as regression
+        #   iterations: Number of measurement iterations per commit (for accuracy)
+        #   warmup_iterations: Number of warmup runs before measurement
+        self.test_command = test_command
+        self.energy_backend = energy_backend
+        self.threshold_percent = threshold_percent
+        self.iterations = iterations
+        self.warmup_iterations = warmup_iterations
+        self._meter = None
+
+    def _get_energy_meter(self):
+        # Get energy meter instance.
+        if self._meter is None:
+            from greenmining.energy.base import get_energy_meter
+
+            self._meter = get_energy_meter(self.energy_backend)
+        return self._meter
+
+    def _run_test_command(self, cwd: str) -> float:
+        # Run test command and return energy consumed in joules.
+        meter = self._get_energy_meter()
+
+        # Warmup
+        for _ in range(self.warmup_iterations):
+            subprocess.run(
+                self.test_command,
+                shell=True,
+                cwd=cwd,
+                capture_output=True,
+                text=True,
+                timeout=300,
+            )
+
+        # Measure
+        total_joules = 0.0
+        for _ in range(self.iterations):
+            meter.start()
+            subprocess.run(
+                self.test_command,
+                shell=True,
+                cwd=cwd,
+                capture_output=True,
+                text=True,
+                timeout=300,
+            )
+            metrics = meter.stop()
+            total_joules += metrics.joules
+
+        return total_joules / self.iterations
+
+    def detect(
+        self,
+        repo_path: str,
+        baseline_commit: str = "HEAD~10",
+        target_commit: str = "HEAD",
+        max_commits: int = 50,
+    ) -> List[PowerRegression]:
+        # Detect power regressions between baseline and target commits.
+        # Args:
+        #   repo_path: Path to local git repository
+        #   baseline_commit: Baseline commit SHA or reference
+        #   target_commit: Target commit SHA or reference
+        #   max_commits: Maximum commits to analyze
+        regressions = []
+
+        colored_print(f"Detecting power regressions in {repo_path}", "cyan")
+        colored_print(f"  Range: {baseline_commit}..{target_commit}", "cyan")
+        colored_print(f"  Test: {self.test_command}", "cyan")
+        colored_print(f"  Threshold: {self.threshold_percent}%", "cyan")
+
+        # Get commits in range
+        commits = list(
+            Repository(
+                path_to_repo=repo_path,
+                from_commit=baseline_commit,
+                to_commit=target_commit,
+            ).traverse_commits()
+        )
+
+        if not commits:
+            colored_print("No commits found in range", "yellow")
+            return regressions
+
+        # Measure baseline
+        colored_print(f"  Measuring baseline ({commits[0].hash[:8]})...", "cyan")
+        self._checkout(repo_path, commits[0].hash)
+        baseline_energy = self._run_test_command(repo_path)
+        colored_print(f"  Baseline: {baseline_energy:.4f} joules", "green")
+
+        previous_energy = baseline_energy
+        commit_count = 0
+
+        for commit in commits[1:]:
+            if commit_count >= max_commits:
+                break
+
+            try:
+                self._checkout(repo_path, commit.hash)
+                current_energy = self._run_test_command(repo_path)
+
+                # Calculate change
+                if previous_energy > 0:
+                    change_percent = ((current_energy - previous_energy) / previous_energy) * 100
+                else:
+                    change_percent = 0.0
+
+                # Check for regression
+                if change_percent > self.threshold_percent:
+                    regression = PowerRegression(
+                        sha=commit.hash,
+                        message=commit.msg[:200],
+                        author=commit.author.name,
+                        date=commit.author_date.isoformat() if commit.author_date else "",
+                        power_before=previous_energy / max(1, self.iterations),
+                        power_after=current_energy / max(1, self.iterations),
+                        power_increase=change_percent,
+                        energy_before=previous_energy,
+                        energy_after=current_energy,
+                    )
+                    regressions.append(regression)
+                    colored_print(f"  REGRESSION: {commit.hash[:8]} +{change_percent:.1f}%", "red")
+                else:
+                    colored_print(f"  OK: {commit.hash[:8]} {change_percent:+.1f}%", "green")
+
+                previous_energy = current_energy
+                commit_count += 1
+
+            except Exception as e:
+                colored_print(f"  Warning: Failed on {commit.hash[:8]}: {e}", "yellow")
+                continue
+
+        # Restore to target
+        self._checkout(repo_path, target_commit)
+
+        colored_print(
+            f"\nFound {len(regressions)} power regressions "
+            f"(>{self.threshold_percent}% increase)",
+            "cyan" if not regressions else "red",
+        )
+
+        return regressions
+
+    @staticmethod
+    def _checkout(repo_path: str, ref: str):
+        # Checkout a specific commit.
+        subprocess.run(
+            ["git", "checkout", ref, "--quiet"],
+            cwd=repo_path,
+            capture_output=True,
+            text=True,
+        )