ci-time-tracker 0.2.0__py3-none-any.whl

ci_time_tracker/models.py

@@ -0,0 +1,277 @@
+"""Data models for ci-time-tracker.
+
+This module contains all dataclasses used across the application for
+representing pipeline configurations, build logs, statistics, and reports.
+"""
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Literal
+
+
+@dataclass
+class PipelineStep:
+    """A discrete unit of work within a CI/CD pipeline.
+    
+    Attributes:
+        name: The step identifier/name
+        stage: Optional stage grouping for the step
+        command: Optional command or script executed by the step
+        estimated_duration: Optional estimated runtime in seconds
+    """
+    name: str
+    stage: str | None = None
+    command: str | None = None
+    estimated_duration: float | None = None
+
+    def validate(self) -> list[str]:
+        """Validate the step data and return list of validation errors."""
+        errors = []
+        if not self.name or not self.name.strip():
+            errors.append("Step name cannot be empty")
+        if self.estimated_duration is not None and self.estimated_duration < 0:
+            errors.append("Estimated duration cannot be negative")
+        return errors
+
+
+@dataclass
+class PipelineConfig:
+    """Parsed CI/CD pipeline configuration.
+    
+    Attributes:
+        provider: CI provider name (github, gitlab, circleci)
+        steps: List of pipeline steps
+        stages: List of stage names in order
+        metadata: Additional provider-specific metadata
+    """
+    provider: str
+    steps: list[PipelineStep] = field(default_factory=list)
+    stages: list[str] = field(default_factory=list)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def validate(self) -> list[str]:
+        """Validate the config and return list of validation errors."""
+        errors = []
+        if not self.provider or not self.provider.strip():
+            errors.append("Provider cannot be empty")
+        for step in self.steps:
+            step_errors = step.validate()
+            errors.extend(step_errors)
+        return errors
+
+
+@dataclass
+class StepExecution:
+    """A single execution of a pipeline step from a build log.
+    
+    Attributes:
+        name: The step identifier/name
+        start_time: When the step started executing
+        end_time: When the step finished executing
+        duration_seconds: Computed or extracted duration in seconds
+        status: Execution result (success, failure, skipped)
+        is_retry: Whether this execution was a retry attempt
+        job_name: Name of the job this step ran in, when known
+        runner: Label or name of the machine that ran the step, when known
+    """
+    name: str
+    start_time: datetime | None = None
+    end_time: datetime | None = None
+    duration_seconds: float | None = None
+    status: Literal["success", "failure", "skipped"] = "success"
+    is_retry: bool = False
+    job_name: str | None = None
+    runner: str | None = None
+
+    def validate(self) -> list[str]:
+        """Validate the step execution and return list of validation errors."""
+        errors = []
+        if not self.name or not self.name.strip():
+            errors.append("Step name cannot be empty")
+        if self.duration_seconds is not None and self.duration_seconds < 0:
+            errors.append("Duration cannot be negative")
+        if self.start_time and self.end_time and self.start_time > self.end_time:
+            errors.append("Start time cannot be after end time")
+        return errors
+
+
+@dataclass
+class BuildLog:
+    """Parsed build log containing step executions.
+    
+    Attributes:
+        build_id: Optional identifier for the build
+        steps: List of step executions from the log
+        total_duration: Total build duration in seconds
+        timestamp: When the build occurred
+        head_sha: Commit the build ran against, when known
+        run_attempt: Attempt number of the build (1 unless it was re-run)
+        conclusion: Overall build result as reported by the provider
+        metadata: Additional provider-specific data (jobs, queue times, ...)
+    """
+    build_id: str | None = None
+    steps: list[StepExecution] = field(default_factory=list)
+    total_duration: float | None = None
+    timestamp: datetime | None = None
+    head_sha: str | None = None
+    run_attempt: int = 1
+    conclusion: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def validate(self) -> list[str]:
+        """Validate the build log and return list of validation errors."""
+        errors = []
+        if self.total_duration is not None and self.total_duration < 0:
+            errors.append("Total duration cannot be negative")
+        for step in self.steps:
+            step_errors = step.validate()
+            errors.extend(step_errors)
+        return errors
+
+
+@dataclass
+class StepStatistics:
+    """Aggregated statistics for a pipeline step across multiple builds.
+    
+    Attributes:
+        name: The step identifier/name
+        execution_count: Total number of executions
+        success_count: Number of successful executions
+        failure_count: Number of failed executions
+        durations: List of recorded durations in seconds
+        p50: 50th percentile duration
+        p90: 90th percentile duration
+        p95: 95th percentile duration
+        p99: 99th percentile duration
+        is_regression: Whether the step's duration regressed
+        is_flaky: Whether the step is flagged as flaky
+        failure_rate: Ratio of failures to total executions
+        total_duration: Sum of all recorded durations, i.e. the time this step
+            has consumed across every build
+        mean_duration: Average recorded duration
+        runner: Runner the step ran on, when known
+        estimated_cost_usd: Cost attributed to this step, when the runner's
+            rate is known
+        regression: Details of the duration regression, when there is one
+        flaky_evidence: Why the step was flagged as flaky, when it was
+    """
+    name: str
+    execution_count: int = 0
+    success_count: int = 0
+    failure_count: int = 0
+    durations: list[float] = field(default_factory=list)
+    p50: float | None = None
+    p90: float | None = None
+    p95: float | None = None
+    p99: float | None = None
+    is_regression: bool = False
+    is_flaky: bool = False
+    failure_rate: float = 0.0
+    total_duration: float = 0.0
+    mean_duration: float | None = None
+    runner: str | None = None
+    estimated_cost_usd: float | None = None
+    regression: dict[str, Any] | None = None
+    flaky_evidence: dict[str, Any] | None = None
+
+    def validate(self) -> list[str]:
+        """Validate the statistics and return list of validation errors."""
+        errors = []
+        if not self.name or not self.name.strip():
+            errors.append("Step name cannot be empty")
+        if self.execution_count < 0:
+            errors.append("Execution count cannot be negative")
+        if self.success_count < 0:
+            errors.append("Success count cannot be negative")
+        if self.failure_count < 0:
+            errors.append("Failure count cannot be negative")
+        if self.success_count + self.failure_count > self.execution_count:
+            errors.append("Success + failure count cannot exceed execution count")
+        if not (0.0 <= self.failure_rate <= 1.0):
+            errors.append("Failure rate must be between 0 and 1")
+        for d in self.durations:
+            if d < 0:
+                errors.append("Duration values cannot be negative")
+                break
+        return errors
+
+
+@dataclass
+class AnalysisResult:
+    """Result of analyzing pipeline config or build logs.
+    
+    Attributes:
+        mode: Analysis mode (config or log)
+        steps: List of step statistics (log mode) or pipeline steps (config mode)
+        total_estimated_duration: Sum of estimated durations for config mode
+        regressed_steps: Names of steps whose duration regressed
+        flaky_steps: Names of steps flagged as flaky
+        metadata: Additional analysis metadata
+    """
+    mode: Literal["config", "log"]
+    steps: list[StepStatistics] | list[PipelineStep] = field(default_factory=list)
+    total_estimated_duration: float | None = None
+    regressed_steps: list[str] = field(default_factory=list)
+    flaky_steps: list[str] = field(default_factory=list)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def validate(self) -> list[str]:
+        """Validate the analysis result and return list of validation errors."""
+        errors = []
+        if self.mode not in ("config", "log"):
+            errors.append("Mode must be 'config' or 'log'")
+        if self.total_estimated_duration is not None and self.total_estimated_duration < 0:
+            errors.append("Total estimated duration cannot be negative")
+        return errors
+
+
+@dataclass
+class Report:
+    """Final report generated from analysis results.
+    
+    Attributes:
+        title: Report title
+        mode: Analysis mode that produced this report
+        generated_at: Timestamp when report was generated
+        summary: Summary statistics and counts
+        steps: List of step data dictionaries
+        issues: List of detected issues (regressions, flaky steps)
+    """
+    title: str
+    mode: str
+    generated_at: datetime
+    summary: dict[str, Any] = field(default_factory=dict)
+    steps: list[dict[str, Any]] = field(default_factory=list)
+    issues: list[dict[str, Any]] = field(default_factory=list)
+
+    def validate(self) -> list[str]:
+        """Validate the report and return list of validation errors."""
+        errors = []
+        if not self.title or not self.title.strip():
+            errors.append("Report title cannot be empty")
+        if not self.mode or not self.mode.strip():
+            errors.append("Report mode cannot be empty")
+        return errors
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert report to dictionary for JSON serialization."""
+        return {
+            "title": self.title,
+            "mode": self.mode,
+            "generated_at": self.generated_at.isoformat(),
+            "summary": self.summary,
+            "steps": self.steps,
+            "issues": self.issues,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "Report":
+        """Create Report from dictionary (JSON deserialization)."""
+        return cls(
+            title=data["title"],
+            mode=data["mode"],
+            generated_at=datetime.fromisoformat(data["generated_at"]),
+            summary=data.get("summary", {}),
+            steps=data.get("steps", []),
+            issues=data.get("issues", []),
+        )

ci_time_tracker/pricing.py

@@ -0,0 +1,202 @@
+"""Runner pricing for cost estimates.
+
+The defaults are GitHub's list prices for private repositories, as published at
+PRICES_SOURCE_URL on PRICES_AS_OF. Public repositories pay nothing for
+standard GitHub-hosted runners, and self-hosted runners are free. Prices
+change, so they can be overridden with a JSON file (see load_pricing).
+
+Each job's cost is its duration rounded up to a whole minute. GitHub has
+billed that way; its current documentation does not state the rounding.
+"""
+
+import json
+import math
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+PRICES_AS_OF = "2026-10"
+PRICES_SOURCE_URL = "https://docs.github.com/en/billing/reference/actions-runner-pricing"
+
+# USD per minute for the labels that are not versioned (versioned labels such
+# as ubuntu-24.04 or macos-15 are matched by _LABEL_FAMILIES below)
+DEFAULT_PRICES_USD_PER_MINUTE: dict[str, float] = {
+    "ubuntu-latest": 0.006,
+    "ubuntu-slim": 0.002,
+    "windows-latest": 0.010,
+    "macos-latest": 0.062,
+    "macos-latest-large": 0.077,
+    "macos-latest-xlarge": 0.102,
+}
+
+# GitHub-hosted label families, most specific first, so that labels GitHub
+# adds later (ubuntu-26.04, macos-26-intel, ...) are priced without an update
+_LABEL_FAMILIES: list[tuple[re.Pattern[str], float]] = [
+    (re.compile(r"^ubuntu-(latest|\d+\.\d+)-arm$"), 0.005),  # Linux 2-core arm64
+    (re.compile(r"^ubuntu-(latest|\d+\.\d+)$"), 0.006),  # Linux 2-core x64
+    (re.compile(r"^windows-(latest|\d+)-arm$"), 0.010),  # Windows 2-core arm64
+    (re.compile(r"^windows-(latest|\d{4})$"), 0.010),  # Windows 2-core x64
+    (re.compile(r"^macos-(latest|\d+)-xlarge$"), 0.102),  # macOS 5-core M2 Pro
+    (re.compile(r"^macos-(latest|\d+)-large$"), 0.077),  # macOS 12-core Intel
+    (re.compile(r"^macos-(latest|\d+)(-intel)?$"), 0.062),  # macOS 3/4-core
+]
+
+# Larger runners are named freely (e.g. "ubuntu-24.04-8-cores"), so they are
+# priced from the platform, architecture and core count in the label. The
+# published rates do not scale linearly with cores, hence the tables; a core
+# count that is not published stays unpriced rather than extrapolated.
+_LARGER_RUNNER_PRICES: dict[tuple[str, str], dict[int, float]] = {
+    ("linux", "x64"): {2: 0.006, 4: 0.012, 8: 0.022, 16: 0.042, 32: 0.082, 64: 0.162, 96: 0.252},
+    ("windows", "x64"): {4: 0.022, 8: 0.042, 16: 0.082, 32: 0.162, 64: 0.322, 96: 0.552},
+    ("linux", "arm64"): {2: 0.005, 4: 0.008, 8: 0.014, 16: 0.026, 32: 0.050, 64: 0.098},
+    ("windows", "arm64"): {2: 0.008, 4: 0.014, 8: 0.026, 16: 0.050, 32: 0.098, 64: 0.194},
+}
+
+_CORES_PATTERN = re.compile(r"(\d+)[-_ ]?cores?\b", re.IGNORECASE)
+
+# A self-hosted runner costs the user nothing on GitHub's bill.
+SELF_HOSTED_LABELS = frozenset({"self-hosted", "selfhosted"})
+
+
+@dataclass
+class PricingTable:
+    """Maps runner labels to a USD-per-minute rate.
+
+    Attributes:
+        prices: Runner label (lowercased) to USD per minute; checked before
+            the label families and larger-runner tables, so a file can
+            override any of them
+        source: Where the rates came from, for the report
+    """
+
+    prices: dict[str, float] = field(
+        default_factory=lambda: dict(DEFAULT_PRICES_USD_PER_MINUTE)
+    )
+    source: str = f"GitHub list prices as of {PRICES_AS_OF}"
+    # Resolved rates by runner string: an analysis asks once per step
+    # execution, for a handful of distinct runners
+    _resolved: dict[str | None, float | None] = field(
+        default_factory=dict, init=False, repr=False, compare=False
+    )
+
+    def price_for(self, runner: str | None) -> float | None:
+        """Return the USD-per-minute rate for a runner, or None if unknown.
+
+        `runner` may be a comma-separated label list, as GitHub reports it.
+        Unknown runners return None rather than 0, so that an incomplete
+        estimate is never presented as a complete one.
+        """
+        if runner not in self._resolved:
+            self._resolved[runner] = self._resolve(runner)
+        return self._resolved[runner]
+
+    def _resolve(self, runner: str | None) -> float | None:
+        """Look up a runner's rate, without caching."""
+        if not runner:
+            return None
+
+        labels = [label.strip().lower() for label in runner.split(",") if label.strip()]
+        if not labels:
+            return None
+
+        # A self-hosted job is not billed, whatever else it is labelled with
+        if any(label in SELF_HOSTED_LABELS for label in labels):
+            return 0.0
+
+        for label in labels:
+            if label in self.prices:
+                return self.prices[label]
+
+        for label in labels:
+            for pattern, price in _LABEL_FAMILIES:
+                if pattern.match(label):
+                    return price
+
+        for label in labels:
+            derived = _price_from_core_count(label)
+            if derived is not None:
+                return derived
+
+        return None
+
+
+def _price_from_core_count(label: str) -> float | None:
+    """Price a larger runner from the platform and core count in its label."""
+    cores_match = _CORES_PATTERN.search(label)
+    if not cores_match:
+        return None
+
+    if "windows" in label:
+        platform = "windows"
+    elif "ubuntu" in label or "linux" in label:
+        platform = "linux"
+    else:
+        return None
+
+    architecture = "arm64" if "arm" in label else "x64"
+    return _LARGER_RUNNER_PRICES[(platform, architecture)].get(int(cores_match.group(1)))
+
+
+def load_pricing(path: str | Path) -> PricingTable:
+    """Load a runner pricing table from a JSON file.
+
+    The file maps runner labels to USD per minute:
+
+        {"ubuntu-latest": 0.006, "my-big-runner": 0.032}
+
+    Args:
+        path: Path to the JSON file
+
+    Returns:
+        PricingTable with the file's rates taking precedence over the defaults
+
+    Raises:
+        ValueError: If the file is not a JSON object of non-negative numbers
+        OSError: If the file cannot be read
+    """
+    content = Path(path).read_text(encoding="utf-8")
+
+    try:
+        data: Any = json.loads(content)
+    except json.JSONDecodeError as error:
+        raise ValueError(f"Invalid JSON in pricing file: {error.msg}") from error
+
+    if not isinstance(data, dict):
+        raise ValueError("Pricing file must contain a JSON object of label -> USD per minute")
+
+    prices = dict(DEFAULT_PRICES_USD_PER_MINUTE)
+
+    for label, price in data.items():
+        if isinstance(price, bool) or not isinstance(price, (int, float)):
+            raise ValueError(f"Price for '{label}' must be a number, got {type(price).__name__}")
+        if price < 0:
+            raise ValueError(f"Price for '{label}' cannot be negative")
+        prices[str(label).strip().lower()] = float(price)
+
+    return PricingTable(prices=prices, source=str(path))
+
+
+def job_cost(duration_seconds: float | None, price_per_minute: float | None) -> float | None:
+    """Cost of one job, its duration rounded up to a whole minute.
+
+    Returns None when either the duration or the rate is unknown.
+    """
+    if duration_seconds is None or price_per_minute is None:
+        return None
+    if duration_seconds <= 0:
+        return 0.0
+
+    return math.ceil(duration_seconds / 60.0) * price_per_minute
+
+
+def attributed_cost(duration_seconds: float | None, price_per_minute: float | None) -> float | None:
+    """Cost attributed to a step, without per-job rounding.
+
+    Used to rank steps by spend. The sum over steps is therefore slightly
+    below the job total, which rounds each job up to a whole minute.
+    """
+    if duration_seconds is None or price_per_minute is None:
+        return None
+
+    return (duration_seconds / 60.0) * price_per_minute