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

greenmining/analyzers/version_power_analyzer.py

@@ -0,0 +1,246 @@
+# Version-by-version power analysis.
+# Measure power consumption across multiple software versions/tags.
+
+from __future__ import annotations
+
+import subprocess
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+from greenmining.utils import colored_print
+
+
+@dataclass
+class VersionPowerProfile:
+    # Power profile for a single version.
+
+    version: str
+    commit_sha: str
+    energy_joules: float = 0.0
+    power_watts_avg: float = 0.0
+    duration_seconds: float = 0.0
+    iterations: int = 0
+    energy_std: float = 0.0  # Standard deviation across iterations
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "version": self.version,
+            "commit_sha": self.commit_sha,
+            "energy_joules": round(self.energy_joules, 4),
+            "power_watts_avg": round(self.power_watts_avg, 4),
+            "duration_seconds": round(self.duration_seconds, 4),
+            "iterations": self.iterations,
+            "energy_std": round(self.energy_std, 4),
+        }
+
+
+@dataclass
+class VersionPowerReport:
+    # Complete power analysis report across versions.
+
+    versions: List[VersionPowerProfile] = field(default_factory=list)
+    trend: str = "stable"  # increasing, decreasing, stable
+    total_change_percent: float = 0.0
+    most_efficient: str = ""
+    least_efficient: str = ""
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "versions": [v.to_dict() for v in self.versions],
+            "trend": self.trend,
+            "total_change_percent": round(self.total_change_percent, 2),
+            "most_efficient": self.most_efficient,
+            "least_efficient": self.least_efficient,
+        }
+
+    def summary(self) -> str:
+        # Generate human-readable summary.
+        lines = [
+            "Version Power Analysis Report",
+            "-" * 40,
+            f"Versions analyzed: {len(self.versions)}",
+            f"Trend: {self.trend}",
+            f"Total change: {self.total_change_percent:+.2f}%",
+            f"Most efficient: {self.most_efficient}",
+            f"Least efficient: {self.least_efficient}",
+            "",
+            "Per-version breakdown:",
+        ]
+        for v in self.versions:
+            lines.append(
+                f"  {v.version}: {v.energy_joules:.4f}J "
+                f"({v.power_watts_avg:.2f}W avg, {v.duration_seconds:.2f}s)"
+            )
+        return "\n".join(lines)
+
+
+class VersionPowerAnalyzer:
+    # Measure and compare power consumption across software versions.
+
+    def __init__(
+        self,
+        test_command: str = "pytest tests/",
+        energy_backend: str = "rapl",
+        iterations: int = 10,
+        warmup_iterations: int = 2,
+    ):
+        # Initialize version power analyzer.
+        # Args:
+        #   test_command: Shell command to run for measurement
+        #   energy_backend: Energy measurement backend
+        #   iterations: Number of measurement iterations per version
+        #   warmup_iterations: Warmup runs before measuring
+        self.test_command = test_command
+        self.energy_backend = energy_backend
+        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 _measure_version(self, repo_path: str, version: str) -> VersionPowerProfile:
+        # Measure power consumption for a specific version.
+        meter = self._get_energy_meter()
+
+        # Checkout version
+        sha = self._checkout_version(repo_path, version)
+        colored_print(f"  Measuring {version} ({sha[:8]})...", "cyan")
+
+        # Warmup
+        for i in range(self.warmup_iterations):
+            subprocess.run(
+                self.test_command,
+                shell=True,
+                cwd=repo_path,
+                capture_output=True,
+                text=True,
+                timeout=600,
+            )
+
+        # Measure iterations
+        measurements = []
+        for i in range(self.iterations):
+            meter.start()
+            subprocess.run(
+                self.test_command,
+                shell=True,
+                cwd=repo_path,
+                capture_output=True,
+                text=True,
+                timeout=600,
+            )
+            metrics = meter.stop()
+            measurements.append(metrics)
+
+        # Aggregate
+        import numpy as np
+
+        energies = [m.joules for m in measurements]
+        avg_energy = float(np.mean(energies))
+        std_energy = float(np.std(energies))
+        avg_power = float(np.mean([m.watts_avg for m in measurements]))
+        avg_duration = float(np.mean([m.duration_seconds for m in measurements]))
+
+        profile = VersionPowerProfile(
+            version=version,
+            commit_sha=sha,
+            energy_joules=avg_energy,
+            power_watts_avg=avg_power,
+            duration_seconds=avg_duration,
+            iterations=self.iterations,
+            energy_std=std_energy,
+        )
+
+        colored_print(
+            f"  {version}: {avg_energy:.4f}J +/-{std_energy:.4f} "
+            f"({avg_power:.2f}W, {avg_duration:.2f}s)",
+            "green",
+        )
+        return profile
+
+    def analyze_versions(
+        self,
+        repo_path: str,
+        versions: List[str],
+    ) -> VersionPowerReport:
+        # Analyze power consumption across multiple versions.
+        # Args:
+        #   repo_path: Path to local git repository
+        #   versions: List of version tags or commit references
+        colored_print(f"\nAnalyzing {len(versions)} versions for power consumption", "cyan")
+        colored_print(f"  Test: {self.test_command}", "cyan")
+        colored_print(f"  Iterations: {self.iterations} (+{self.warmup_iterations} warmup)", "cyan")
+
+        profiles = []
+        for version in versions:
+            try:
+                profile = self._measure_version(repo_path, version)
+                profiles.append(profile)
+            except Exception as e:
+                colored_print(f"  Error measuring {version}: {e}", "red")
+
+        if not profiles:
+            return VersionPowerReport()
+
+        # Determine trend
+        first_energy = profiles[0].energy_joules
+        last_energy = profiles[-1].energy_joules
+
+        if first_energy > 0:
+            total_change = ((last_energy - first_energy) / first_energy) * 100
+        else:
+            total_change = 0.0
+
+        if total_change > 5:
+            trend = "increasing"
+        elif total_change < -5:
+            trend = "decreasing"
+        else:
+            trend = "stable"
+
+        # Find most/least efficient
+        most_efficient = min(profiles, key=lambda p: p.energy_joules)
+        least_efficient = max(profiles, key=lambda p: p.energy_joules)
+
+        report = VersionPowerReport(
+            versions=profiles,
+            trend=trend,
+            total_change_percent=total_change,
+            most_efficient=most_efficient.version,
+            least_efficient=least_efficient.version,
+        )
+
+        colored_print(f"\nTrend: {trend} ({total_change:+.2f}%)", "cyan")
+        colored_print(f"Most efficient: {most_efficient.version}", "green")
+        colored_print(f"Least efficient: {least_efficient.version}", "red")
+
+        # Restore to latest version
+        try:
+            self._checkout_version(repo_path, versions[-1])
+        except Exception:
+            pass
+
+        return report
+
+    @staticmethod
+    def _checkout_version(repo_path: str, version: str) -> str:
+        # Checkout a version and return its SHA.
+        subprocess.run(
+            ["git", "checkout", version, "--quiet"],
+            cwd=repo_path,
+            capture_output=True,
+            text=True,
+        )
+        result = subprocess.run(
+            ["git", "rev-parse", "HEAD"],
+            cwd=repo_path,
+            capture_output=True,
+            text=True,
+        )
+        return result.stdout.strip()

greenmining/config.py

@@ -11,7 +11,8 @@ def _load_yaml_config(yaml_path: Path) -> Dict[str, Any]:
         return {}
     try:
         import yaml
-        with open(yaml_path, 'r') as f:
+
+        with open(yaml_path, "r") as f:
             return yaml.safe_load(f) or {}
     except ImportError:
         return {}
@@ -30,7 +31,7 @@ class Config:
             load_dotenv(env_path)
         else:
             load_dotenv()  # Load from system environment
-        
+
         # Load YAML config (takes precedence for certain options)
         yaml_path = Path(yaml_file)
         self._yaml_config = _load_yaml_config(yaml_path)
@@ -45,22 +46,32 @@ class Config:
 
         # Search and Processing Configuration (YAML: sources.search.keywords)
         yaml_search = self._yaml_config.get("sources", {}).get("search", {})
-        self.GITHUB_SEARCH_KEYWORDS = yaml_search.get("keywords", 
-            ["microservices", "microservice-architecture", "cloud-native"])
+        self.GITHUB_SEARCH_KEYWORDS = yaml_search.get(
+            "keywords", ["microservices", "microservice-architecture", "cloud-native"]
+        )
 
         # Supported Languages (YAML: sources.search.languages)
-        self.SUPPORTED_LANGUAGES = yaml_search.get("languages", [
-            "Java", "Python", "Go", "JavaScript", "TypeScript", "C#", "Rust",
-        ])
+        self.SUPPORTED_LANGUAGES = yaml_search.get(
+            "languages",
+            [
+                "Java",
+                "Python",
+                "Go",
+                "JavaScript",
+                "TypeScript",
+                "C#",
+                "Rust",
+            ],
+        )
 
         # Repository and Commit Limits (YAML: extraction.*)
         yaml_extraction = self._yaml_config.get("extraction", {})
         self.MIN_STARS = yaml_search.get("min_stars", int(os.getenv("MIN_STARS", "100")))
         self.MAX_REPOS = int(os.getenv("MAX_REPOS", "100"))
-        self.COMMITS_PER_REPO = yaml_extraction.get("max_commits", 
-            int(os.getenv("COMMITS_PER_REPO", "50")))
-        self.DAYS_BACK = yaml_extraction.get("days_back", 
-            int(os.getenv("DAYS_BACK", "730")))
+        self.COMMITS_PER_REPO = yaml_extraction.get(
+            "max_commits", int(os.getenv("COMMITS_PER_REPO", "50"))
+        )
+        self.DAYS_BACK = yaml_extraction.get("days_back", int(os.getenv("DAYS_BACK", "730")))
         self.SKIP_MERGES = yaml_extraction.get("skip_merges", True)
 
         # Analysis Configuration (YAML: analysis.*)
@@ -72,14 +83,17 @@ class Config:
         self.TEMPORAL_GRANULARITY = os.getenv("TEMPORAL_GRANULARITY", "quarter")
         self.ENABLE_ML_FEATURES = os.getenv("ENABLE_ML_FEATURES", "false").lower() == "true"
         self.VALIDATION_SAMPLE_SIZE = int(os.getenv("VALIDATION_SAMPLE_SIZE", "30"))
-        
+
         # PyDriller options (YAML: analysis.process_metrics, etc.)
-        self.PROCESS_METRICS_ENABLED = yaml_analysis.get("process_metrics",
-            os.getenv("PROCESS_METRICS_ENABLED", "true").lower() == "true")
-        self.STRUCTURAL_METRICS_ENABLED = yaml_analysis.get("structural_metrics",
-            os.getenv("STRUCTURAL_METRICS_ENABLED", "true").lower() == "true")
-        self.DMM_ENABLED = yaml_analysis.get("delta_maintainability",
-            os.getenv("DMM_ENABLED", "true").lower() == "true")
+        self.PROCESS_METRICS_ENABLED = yaml_analysis.get(
+            "process_metrics", os.getenv("PROCESS_METRICS_ENABLED", "true").lower() == "true"
+        )
+        self.STRUCTURAL_METRICS_ENABLED = yaml_analysis.get(
+            "structural_metrics", os.getenv("STRUCTURAL_METRICS_ENABLED", "true").lower() == "true"
+        )
+        self.DMM_ENABLED = yaml_analysis.get(
+            "delta_maintainability", os.getenv("DMM_ENABLED", "true").lower() == "true"
+        )
 
         # Temporal Filtering
         self.CREATED_AFTER = os.getenv("CREATED_AFTER")
@@ -102,8 +116,7 @@ class Config:
 
         # Output Configuration (YAML: output.directory)
         yaml_output = self._yaml_config.get("output", {})
-        self.OUTPUT_DIR = Path(yaml_output.get("directory", 
-            os.getenv("OUTPUT_DIR", "./data")))
+        self.OUTPUT_DIR = Path(yaml_output.get("directory", os.getenv("OUTPUT_DIR", "./data")))
         self.OUTPUT_DIR.mkdir(parents=True, exist_ok=True)
 
         # File Paths
@@ -119,25 +132,24 @@ class Config:
         yaml_urls = self._yaml_config.get("sources", {}).get("urls", [])
         env_urls = self._parse_repository_urls(os.getenv("REPOSITORY_URLS", ""))
         self.REPOSITORY_URLS: List[str] = yaml_urls if yaml_urls else env_urls
-        
+
         # Clone path (YAML: extraction.clone_path)
-        self.CLONE_PATH = Path(yaml_extraction.get("clone_path",
-            os.getenv("CLONE_PATH", "/tmp/greenmining_repos")))
-        self.CLEANUP_AFTER_ANALYSIS = (
-            os.getenv("CLEANUP_AFTER_ANALYSIS", "true").lower() == "true"
+        self.CLONE_PATH = Path(
+            yaml_extraction.get("clone_path", os.getenv("CLONE_PATH", "/tmp/greenmining_repos"))
         )
+        self.CLEANUP_AFTER_ANALYSIS = os.getenv("CLEANUP_AFTER_ANALYSIS", "true").lower() == "true"
 
         # Energy Measurement (YAML: energy.*)
         yaml_energy = self._yaml_config.get("energy", {})
-        self.ENERGY_ENABLED = yaml_energy.get("enabled",
-            os.getenv("ENERGY_ENABLED", "false").lower() == "true")
-        self.ENERGY_BACKEND = yaml_energy.get("backend",
-            os.getenv("ENERGY_BACKEND", "rapl"))
-        self.CARBON_TRACKING = yaml_energy.get("carbon_tracking",
-            os.getenv("CARBON_TRACKING", "false").lower() == "true")
-        self.COUNTRY_ISO = yaml_energy.get("country_iso",
-            os.getenv("COUNTRY_ISO", "USA"))
-        
+        self.ENERGY_ENABLED = yaml_energy.get(
+            "enabled", os.getenv("ENERGY_ENABLED", "false").lower() == "true"
+        )
+        self.ENERGY_BACKEND = yaml_energy.get("backend", os.getenv("ENERGY_BACKEND", "rapl"))
+        self.CARBON_TRACKING = yaml_energy.get(
+            "carbon_tracking", os.getenv("CARBON_TRACKING", "false").lower() == "true"
+        )
+        self.COUNTRY_ISO = yaml_energy.get("country_iso", os.getenv("COUNTRY_ISO", "USA"))
+
         # Power profiling (YAML: energy.power_profiling.*)
         yaml_power = yaml_energy.get("power_profiling", {})
         self.POWER_PROFILING_ENABLED = yaml_power.get("enabled", False)

greenmining/dashboard/__init__.py

@@ -0,0 +1,5 @@
+# Web dashboard module for GreenMining visualization.
+
+from .app import create_app, run_dashboard
+
+__all__ = ["create_app", "run_dashboard"]

greenmining/dashboard/app.py

@@ -0,0 +1,200 @@
+# Flask-based web dashboard for GreenMining analysis visualization.
+# Provides interactive charts for repository analysis, pattern distribution,
+# temporal trends, and energy consumption.
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+
+def create_app(data_dir: str = "./data"):
+    # Create Flask application for the dashboard.
+    # Args:
+    #   data_dir: Path to directory containing analysis JSON files
+    # Returns:
+    #   Flask application instance
+    try:
+        from flask import Flask, render_template_string, jsonify, request
+    except ImportError:
+        raise ImportError("Flask is required for the dashboard. Install it with: pip install flask")
+
+    app = Flask(__name__)
+    data_path = Path(data_dir)
+
+    def _load_data(filename: str) -> Dict[str, Any]:
+        filepath = data_path / filename
+        if filepath.exists():
+            with open(filepath, encoding="utf-8") as f:
+                return json.load(f)
+        return {}
+
+    @app.route("/")
+    def index():
+        return render_template_string(DASHBOARD_HTML)
+
+    @app.route("/api/repositories")
+    def api_repositories():
+        data = _load_data("repositories.json")
+        return jsonify(data)
+
+    @app.route("/api/analysis")
+    def api_analysis():
+        data = _load_data("analysis_results.json")
+        return jsonify(data)
+
+    @app.route("/api/statistics")
+    def api_statistics():
+        data = _load_data("aggregated_statistics.json")
+        return jsonify(data)
+
+    @app.route("/api/energy")
+    def api_energy():
+        data = _load_data("energy_report.json")
+        return jsonify(data)
+
+    @app.route("/api/summary")
+    def api_summary():
+        # Build summary from available data
+        repos = _load_data("repositories.json")
+        analysis = _load_data("analysis_results.json")
+
+        repo_count = 0
+        if isinstance(repos, list):
+            repo_count = len(repos)
+        elif isinstance(repos, dict):
+            repo_count = repos.get("total_repositories", len(repos.get("repositories", [])))
+
+        commit_count = 0
+        green_count = 0
+        if isinstance(analysis, list):
+            commit_count = len(analysis)
+            green_count = sum(1 for a in analysis if a.get("green_aware"))
+        elif isinstance(analysis, dict):
+            results = analysis.get("results", [])
+            for r in results:
+                commits = r.get("commits", [])
+                commit_count += len(commits)
+                green_count += sum(1 for c in commits if c.get("green_aware"))
+
+        green_rate = (green_count / commit_count * 100) if commit_count > 0 else 0
+
+        return jsonify(
+            {
+                "repositories": repo_count,
+                "commits_analyzed": commit_count,
+                "green_commits": green_count,
+                "green_rate": round(green_rate, 1),
+            }
+        )
+
+    return app
+
+
+def run_dashboard(data_dir: str = "./data", host: str = "127.0.0.1", port: int = 5000):
+    # Run the dashboard server.
+    # Args:
+    #   data_dir: Path to analysis data directory
+    #   host: Host to bind to
+    #   port: Port to bind to
+    app = create_app(data_dir)
+    print(f"GreenMining Dashboard running at http://{host}:{port}")
+    print(f"Data directory: {data_dir}")
+    app.run(host=host, port=port, debug=False)
+
+
+# Dashboard HTML template with embedded JS (no external dependencies)
+DASHBOARD_HTML = """
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>GreenMining Dashboard</title>
+    <style>
+        * { margin: 0; padding: 0; box-sizing: border-box; }
+        body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+               background: #f5f7fa; color: #333; }
+        .header { background: #1a472a; color: white; padding: 20px 40px; }
+        .header h1 { font-size: 24px; font-weight: 600; }
+        .header p { font-size: 14px; opacity: 0.8; margin-top: 4px; }
+        .container { max-width: 1200px; margin: 0 auto; padding: 20px; }
+        .grid { display: grid; grid-template-columns: repeat(4, 1fr); gap: 16px; margin-bottom: 24px; }
+        .card { background: white; border-radius: 8px; padding: 20px; box-shadow: 0 1px 3px rgba(0,0,0,0.1); }
+        .card h3 { font-size: 13px; color: #666; text-transform: uppercase; letter-spacing: 0.5px; }
+        .card .value { font-size: 32px; font-weight: 700; color: #1a472a; margin-top: 8px; }
+        .card .subtitle { font-size: 12px; color: #999; margin-top: 4px; }
+        .section { margin-bottom: 24px; }
+        .section h2 { font-size: 18px; margin-bottom: 12px; color: #1a472a; }
+        table { width: 100%; border-collapse: collapse; background: white; border-radius: 8px;
+                overflow: hidden; box-shadow: 0 1px 3px rgba(0,0,0,0.1); }
+        th, td { padding: 12px 16px; text-align: left; border-bottom: 1px solid #eee; }
+        th { background: #f8f9fa; font-size: 12px; text-transform: uppercase; color: #666; }
+        td { font-size: 14px; }
+        .badge { display: inline-block; padding: 2px 8px; border-radius: 12px; font-size: 11px; }
+        .badge-green { background: #d4edda; color: #155724; }
+        .badge-gray { background: #e9ecef; color: #495057; }
+        .bar { height: 8px; background: #e9ecef; border-radius: 4px; overflow: hidden; }
+        .bar-fill { height: 100%; background: #1a472a; border-radius: 4px;
+                     transition: width 0.5s ease; }
+        .loading { text-align: center; padding: 40px; color: #999; }
+    </style>
+</head>
+<body>
+    <div class="header">
+        <h1>GreenMining Dashboard</h1>
+        <p>Mining Software Repositories for Green IT Research</p>
+    </div>
+    <div class="container">
+        <div class="grid" id="summary-cards">
+            <div class="card"><h3>Repositories</h3><div class="value" id="repo-count">-</div></div>
+            <div class="card"><h3>Commits Analyzed</h3><div class="value" id="commit-count">-</div></div>
+            <div class="card"><h3>Green Commits</h3><div class="value" id="green-count">-</div></div>
+            <div class="card"><h3>Green Rate</h3><div class="value" id="green-rate">-</div></div>
+        </div>
+        <div class="section">
+            <h2>Repositories</h2>
+            <div id="repo-table"><div class="loading">Loading data...</div></div>
+        </div>
+    </div>
+    <script>
+        async function loadDashboard() {
+            try {
+                const summary = await fetch('/api/summary').then(r => r.json());
+                document.getElementById('repo-count').textContent = summary.repositories;
+                document.getElementById('commit-count').textContent = summary.commits_analyzed.toLocaleString();
+                document.getElementById('green-count').textContent = summary.green_commits.toLocaleString();
+                document.getElementById('green-rate').textContent = summary.green_rate + '%';
+            } catch(e) {
+                console.log('Summary not available:', e);
+            }
+
+            try {
+                const repos = await fetch('/api/repositories').then(r => r.json());
+                const list = repos.repositories || (Array.isArray(repos) ? repos : []);
+                if (list.length > 0) {
+                    let html = '<table><thead><tr><th>Repository</th><th>Language</th>' +
+                        '<th>Stars</th><th>Description</th></tr></thead><tbody>';
+                    list.slice(0, 50).forEach(r => {
+                        html += '<tr><td><strong>' + (r.full_name || r.name) + '</strong></td>' +
+                            '<td><span class="badge badge-green">' + (r.language || '-') + '</span></td>' +
+                            '<td>' + (r.stars || 0).toLocaleString() + '</td>' +
+                            '<td>' + (r.description || '-').substring(0, 80) + '</td></tr>';
+                    });
+                    html += '</tbody></table>';
+                    document.getElementById('repo-table').innerHTML = html;
+                } else {
+                    document.getElementById('repo-table').innerHTML =
+                        '<div class="card">No repository data found. Run an analysis first.</div>';
+                }
+            } catch(e) {
+                document.getElementById('repo-table').innerHTML =
+                    '<div class="card">Run an analysis to populate the dashboard.</div>';
+            }
+        }
+        loadDashboard();
+    </script>
+</body>
+</html>
+"""

greenmining/energy/__init__.py

@@ -1,13 +1,20 @@
 # Energy measurement module for GreenMining.
 
-from .base import EnergyMeter, EnergyMetrics, EnergyBackend
+from .base import EnergyMeter, EnergyMetrics, EnergyBackend, CommitEnergyProfile, get_energy_meter
 from .rapl import RAPLEnergyMeter
 from .codecarbon_meter import CodeCarbonMeter
+from .cpu_meter import CPUEnergyMeter
+from .carbon_reporter import CarbonReporter, CarbonReport
 
 __all__ = [
     "EnergyMeter",
     "EnergyMetrics",
     "EnergyBackend",
+    "CommitEnergyProfile",
+    "get_energy_meter",
     "RAPLEnergyMeter",
     "CodeCarbonMeter",
+    "CPUEnergyMeter",
+    "CarbonReporter",
+    "CarbonReport",
 ]