ci-time-tracker 0.2.0__tar.gz → 0.3.0__tar.gz

{ci_time_tracker-0.2.0 → ci_time_tracker-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ci-time-tracker
-Version: 0.2.0
+Version: 0.3.0
 Summary: Find where CI time and money go: cost, flaky steps and regressions from GitHub Actions, and a PR comment action
 Author: ci-time-tracker contributors
 License-Expression: MIT
@@ -32,6 +32,7 @@ Dynamic: license-file
 # ci-time-tracker
 
 [![CI](https://github.com/0xWhisp/ci-time-tracker/actions/workflows/ci.yml/badge.svg)](https://github.com/0xWhisp/ci-time-tracker/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/ci-time-tracker)](https://pypi.org/project/ci-time-tracker/)
 
 Find where your CI time and money go. ci-time-tracker reads your GitHub Actions
 history and reports the steps that cost the most, the ones that are flaky, and
@@ -54,7 +55,13 @@ comments on each pull request with how it changes CI time and cost.
 
 ## Installation
 
-Requires Python 3.10+. Not yet published on PyPI; install from source:
+Requires Python 3.10+.
+
+```bash
+pip install ci-time-tracker
+```
+
+Or from source:
 
 ```bash
 git clone https://github.com/0xWhisp/ci-time-tracker.git
@@ -296,7 +303,7 @@ consumers, and the full step table collapsed.
 ```yaml
 - name: CI time report
   run: |
-    pip install git+https://github.com/0xWhisp/ci-time-tracker.git
+    pip install ci-time-tracker
     ci-time-tracker --github ${{ github.repository }} --workflow ci.yml       --last 100 --group-matrix --format markdown >> "$GITHUB_STEP_SUMMARY"
   env:
     GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -369,7 +376,7 @@ jobs:
     if: github.event.workflow_run.event == 'pull_request'
     runs-on: ubuntu-latest
     steps:
-      - uses: 0xWhisp/ci-time-tracker@main   # pin a release tag once published
+      - uses: 0xWhisp/ci-time-tracker@v0.3.0
 ```
 
 `workflow_run` runs the copy of the workflow on the default branch with the
@@ -395,6 +402,31 @@ ci-time-tracker --github acme/web --run-id 39102310449 --group-matrix
 ci-time-tracker --github acme/web --run-id 39102310449 --comment   # post it
 ```
 
+### HTML report
+
+`--format html` writes a single self-contained page: summary cards, build
+duration over time for each of the busiest workflows (failures marked, a
+rolling median, outliers kept from flattening the chart), issues with their
+evidence, recommendations, and where the time goes. It has no scripts and loads
+nothing from elsewhere, so it opens offline and can be attached to an issue or
+kept as a CI artifact. It follows the viewer's light or dark mode.
+
+```bash
+ci-time-tracker --github acme/web --group-matrix --format html --output ci-report.html
+```
+
+```yaml
+- run: ci-time-tracker --github ${{ github.repository }} --format html --output ci-report.html
+  env:
+    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+- uses: actions/upload-artifact@v4
+  with:
+    name: ci-report
+    path: ci-report.html
+```
+
+The JSON output carries the same per-build data under `timeline`.
+
 ### Exit codes
 
 | Code | Meaning |
@@ -405,13 +437,47 @@ ci-time-tracker --github acme/web --run-id 39102310449 --comment   # post it
 | 3 | GitHub API error (rate limit, permissions, not found) |
 | 4 | A quality gate failed |
 
+## Recommendations
+
+With `--github`, ci-time-tracker also reads the workflow files behind the runs
+and suggests changes where the configuration shows a cause and the history
+shows it matters. Neither is enough alone: a slow install step may already be
+cached, and a job without a cache may install in two seconds.
+
+| Recommendation | When |
+|---|---|
+| **Cache dependencies** | A job installs dependencies (pip, uv, poetry, npm, pnpm, yarn, bundler, composer, go) without any cache, and the install takes a median of 20s or more |
+| **Cancel superseded pull request runs** | Pull request runs kept running after a newer push to the same branch started another run, and the workflow has no `concurrency` with `cancel-in-progress` |
+| **Run expensive matrix legs less often** | Over at least 10 builds, the Windows or macOS legs of a job never failed when its Linux legs passed |
+
+Each one comes with its evidence, a concrete change, and what is at stake: the
+time (and cost) the affected steps or jobs used over the analyzed runs. That is
+an upper bound on the saving, not a promise of it. Findings with less than
+10 minutes at stake are left out, so the list stays worth reading.
+
+For example, on pytest-dev/pytest:
+
+```
+RECOMMENDATIONS
+  1. Run the Windows legs of `build` less often (.github/workflows/test.yml)
+     In 79 builds, the Windows legs never failed when the Linux legs passed. They used 68h 08m, 40% of the job's compute.
+     Suggestion: Run the Windows legs only on pushes to the default branch or on a schedule, and keep Linux on pull requests. A platform-specific failure then shows up after merging rather than before.
+     At stake: 68h 08m
+```
+
+Whether a job could start earlier (a `needs` that only orders jobs) is not
+suggested: the configuration cannot tell an ordering from a real dependency on
+the other job's results.
+
 ## Cost Estimates
 
 Costs are estimated from the runner each job ran on, using GitHub's
 [list prices](https://docs.github.com/en/billing/reference/actions-runner-pricing)
 for **private repositories** as of October 2026, with each job rounded up to a
 whole minute. Public repositories pay nothing for standard GitHub-hosted
-runners; larger runners are billed for public repositories too.
+runners; larger runners are billed for public repositories too. When the
+analyzed repository is public (the runs say so), standard runners are priced
+at `$0`, so the estimate counts only what is actually billed.
 
 | Runner | USD per minute |
 |---|---:|
@@ -500,6 +566,11 @@ needs at least **10 builds** to be judged; `regression_checked_steps` says how
 many had enough history. With `--group-matrix`, the legs of a build are
 combined into one sample (their median).
 
+When the analyzed runs span several branches, regressions are looked for on
+the repository's default branch only (`regression_branch`). Pull request
+branches run different code with different caches; mixed into one history
+they look like changes that never happened.
+
 ## Supported CI Providers
 
 | Provider | Config Format | Log Format |
@@ -550,7 +621,7 @@ Then, for each release:
 1. Bump `version` in `pyproject.toml` and `__version__` in
    `ci_time_tracker/__init__.py` (a test checks they agree), and add the
    release to [CHANGELOG.md](CHANGELOG.md).
-2. Tag and push: `git tag v0.2.0 && git push origin v0.2.0`.
+2. Tag and push: `git tag v0.3.0 && git push origin v0.3.0`.
 3. Create the GitHub release from the tag, with the changelog entry as its
    notes, and tick "Publish this Action to the GitHub Marketplace".
 

{ci_time_tracker-0.2.0 → ci_time_tracker-0.3.0}/README.md

@@ -1,6 +1,7 @@
 # ci-time-tracker
 
 [![CI](https://github.com/0xWhisp/ci-time-tracker/actions/workflows/ci.yml/badge.svg)](https://github.com/0xWhisp/ci-time-tracker/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/ci-time-tracker)](https://pypi.org/project/ci-time-tracker/)
 
 Find where your CI time and money go. ci-time-tracker reads your GitHub Actions
 history and reports the steps that cost the most, the ones that are flaky, and
@@ -23,7 +24,13 @@ comments on each pull request with how it changes CI time and cost.
 
 ## Installation
 
-Requires Python 3.10+. Not yet published on PyPI; install from source:
+Requires Python 3.10+.
+
+```bash
+pip install ci-time-tracker
+```
+
+Or from source:
 
 ```bash
 git clone https://github.com/0xWhisp/ci-time-tracker.git
@@ -265,7 +272,7 @@ consumers, and the full step table collapsed.
 ```yaml
 - name: CI time report
   run: |
-    pip install git+https://github.com/0xWhisp/ci-time-tracker.git
+    pip install ci-time-tracker
     ci-time-tracker --github ${{ github.repository }} --workflow ci.yml       --last 100 --group-matrix --format markdown >> "$GITHUB_STEP_SUMMARY"
   env:
     GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -338,7 +345,7 @@ jobs:
     if: github.event.workflow_run.event == 'pull_request'
     runs-on: ubuntu-latest
     steps:
-      - uses: 0xWhisp/ci-time-tracker@main   # pin a release tag once published
+      - uses: 0xWhisp/ci-time-tracker@v0.3.0
 ```
 
 `workflow_run` runs the copy of the workflow on the default branch with the
@@ -364,6 +371,31 @@ ci-time-tracker --github acme/web --run-id 39102310449 --group-matrix
 ci-time-tracker --github acme/web --run-id 39102310449 --comment   # post it
 ```
 
+### HTML report
+
+`--format html` writes a single self-contained page: summary cards, build
+duration over time for each of the busiest workflows (failures marked, a
+rolling median, outliers kept from flattening the chart), issues with their
+evidence, recommendations, and where the time goes. It has no scripts and loads
+nothing from elsewhere, so it opens offline and can be attached to an issue or
+kept as a CI artifact. It follows the viewer's light or dark mode.
+
+```bash
+ci-time-tracker --github acme/web --group-matrix --format html --output ci-report.html
+```
+
+```yaml
+- run: ci-time-tracker --github ${{ github.repository }} --format html --output ci-report.html
+  env:
+    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+- uses: actions/upload-artifact@v4
+  with:
+    name: ci-report
+    path: ci-report.html
+```
+
+The JSON output carries the same per-build data under `timeline`.
+
 ### Exit codes
 
 | Code | Meaning |
@@ -374,13 +406,47 @@ ci-time-tracker --github acme/web --run-id 39102310449 --comment   # post it
 | 3 | GitHub API error (rate limit, permissions, not found) |
 | 4 | A quality gate failed |
 
+## Recommendations
+
+With `--github`, ci-time-tracker also reads the workflow files behind the runs
+and suggests changes where the configuration shows a cause and the history
+shows it matters. Neither is enough alone: a slow install step may already be
+cached, and a job without a cache may install in two seconds.
+
+| Recommendation | When |
+|---|---|
+| **Cache dependencies** | A job installs dependencies (pip, uv, poetry, npm, pnpm, yarn, bundler, composer, go) without any cache, and the install takes a median of 20s or more |
+| **Cancel superseded pull request runs** | Pull request runs kept running after a newer push to the same branch started another run, and the workflow has no `concurrency` with `cancel-in-progress` |
+| **Run expensive matrix legs less often** | Over at least 10 builds, the Windows or macOS legs of a job never failed when its Linux legs passed |
+
+Each one comes with its evidence, a concrete change, and what is at stake: the
+time (and cost) the affected steps or jobs used over the analyzed runs. That is
+an upper bound on the saving, not a promise of it. Findings with less than
+10 minutes at stake are left out, so the list stays worth reading.
+
+For example, on pytest-dev/pytest:
+
+```
+RECOMMENDATIONS
+  1. Run the Windows legs of `build` less often (.github/workflows/test.yml)
+     In 79 builds, the Windows legs never failed when the Linux legs passed. They used 68h 08m, 40% of the job's compute.
+     Suggestion: Run the Windows legs only on pushes to the default branch or on a schedule, and keep Linux on pull requests. A platform-specific failure then shows up after merging rather than before.
+     At stake: 68h 08m
+```
+
+Whether a job could start earlier (a `needs` that only orders jobs) is not
+suggested: the configuration cannot tell an ordering from a real dependency on
+the other job's results.
+
 ## Cost Estimates
 
 Costs are estimated from the runner each job ran on, using GitHub's
 [list prices](https://docs.github.com/en/billing/reference/actions-runner-pricing)
 for **private repositories** as of October 2026, with each job rounded up to a
 whole minute. Public repositories pay nothing for standard GitHub-hosted
-runners; larger runners are billed for public repositories too.
+runners; larger runners are billed for public repositories too. When the
+analyzed repository is public (the runs say so), standard runners are priced
+at `$0`, so the estimate counts only what is actually billed.
 
 | Runner | USD per minute |
 |---|---:|
@@ -469,6 +535,11 @@ needs at least **10 builds** to be judged; `regression_checked_steps` says how
 many had enough history. With `--group-matrix`, the legs of a build are
 combined into one sample (their median).
 
+When the analyzed runs span several branches, regressions are looked for on
+the repository's default branch only (`regression_branch`). Pull request
+branches run different code with different caches; mixed into one history
+they look like changes that never happened.
+
 ## Supported CI Providers
 
 | Provider | Config Format | Log Format |
@@ -519,7 +590,7 @@ Then, for each release:
 1. Bump `version` in `pyproject.toml` and `__version__` in
    `ci_time_tracker/__init__.py` (a test checks they agree), and add the
    release to [CHANGELOG.md](CHANGELOG.md).
-2. Tag and push: `git tag v0.2.0 && git push origin v0.2.0`.
+2. Tag and push: `git tag v0.3.0 && git push origin v0.3.0`.
 3. Create the GitHub release from the tag, with the changelog entry as its
    notes, and tick "Publish this Action to the GitHub Marketplace".
 

{ci_time_tracker-0.2.0 → ci_time_tracker-0.3.0}/ci_time_tracker/__init__.py

@@ -1,3 +1,3 @@
 """ci-time-tracker: A CLI tool for analyzing CI/CD pipeline configurations and build logs."""
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"

{ci_time_tracker-0.2.0 → ci_time_tracker-0.3.0}/ci_time_tracker/analyzer.py

@@ -172,6 +172,7 @@ def analyze_logs(
     group_matrix: bool = False,
     regression_threshold: float = DEFAULT_REGRESSION_THRESHOLD,
     min_samples: int = DEFAULT_MIN_SAMPLES,
+    regression_branch: str | None = None,
 ) -> AnalysisResult:
     """Analyze multiple build logs and compute statistics.
 
@@ -190,6 +191,9 @@ def analyze_logs(
         regression_threshold: Minimum relative duration increase to report,
             e.g. 0.25 for +25%
         min_samples: Minimum builds on each side of a regression
+        regression_branch: When builds span several branches, the one
+            regressions are looked for on (the default branch); defaults to
+            the branch with the most builds
 
     Returns:
         AnalysisResult in log mode with step statistics and detected issues
@@ -297,6 +301,17 @@ def analyze_logs(
             name: {"method": "failure-rate"} for name in detect_flaky_steps(step_stats)
         }
 
+    # Regressions are looked for on one branch only. Pull request branches
+    # run different code with different caches, and mixed into one series
+    # they read as changes that never happened (seen on rubocop, whose
+    # 26 master builds were mixed with 74 from pull requests).
+    branches = Counter(log.metadata.get("branch") for log in logs if log.metadata.get("branch"))
+    if len(branches) > 1:
+        if regression_branch not in branches:
+            regression_branch = branches.most_common(1)[0][0]
+    else:
+        regression_branch = None  # one branch or none known: all builds compare
+
     # Regressions, from one sample per build (the median across matrix legs
     # when they are grouped), in chronological order
     regression_checked = 0
@@ -306,6 +321,7 @@ def analyze_logs(
         samples = [
             (median(values), logs[build_index])
             for build_index, values in sorted(build_durations.items())
+            if regression_branch is None or logs[build_index].metadata.get("branch") == regression_branch
         ]
 
         if len(samples) >= 2 * min_samples:
@@ -344,18 +360,42 @@ def analyze_logs(
     metadata["flaky_detection"] = flaky_method
     metadata["regression_checked_steps"] = regression_checked
     metadata["regression_min_builds"] = 2 * min_samples
+    if regression_branch:
+        metadata["regression_branch"] = regression_branch
     metadata.update(aggregate_job_metrics(logs, pricing))
 
     return AnalysisResult(
         mode="log",
         steps=step_stats,
         total_estimated_duration=None,
+        timeline=build_timeline(logs),
         regressed_steps=[stats.name for stats in step_stats if stats.is_regression],
         flaky_steps=[stats.name for stats in step_stats if stats.is_flaky],
         metadata=metadata,
     )
 
 
+def build_timeline(logs: list[BuildLog]) -> list[dict[str, Any]]:
+    """One entry per build, in the given order, for trend charts.
+
+    Earlier attempts of re-runs are left out: they are part of the same build.
+    """
+    return [
+        {
+            "build_id": log.build_id,
+            "timestamp": log.timestamp.isoformat() if log.timestamp else None,
+            "duration": log.total_duration,
+            "conclusion": log.conclusion,
+            "head_sha": log.head_sha[:7] if log.head_sha else None,
+            "workflow": log.metadata.get("workflow_name"),
+            "branch": log.metadata.get("branch"),
+            "url": log.metadata.get("url"),
+        }
+        for log in logs
+        if not log.metadata.get("superseded_attempt")
+    ]
+
+
 def aggregate_job_metrics(
     logs: list[BuildLog],
     pricing: PricingTable | None = None,

{ci_time_tracker-0.2.0 → ci_time_tracker-0.3.0}/ci_time_tracker/cli.py

@@ -7,6 +7,8 @@ parsing, file I/O, and orchestration of parsing, analysis, and reporting.
 import argparse
 import json
 import sys
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import replace
 from pathlib import Path
 from typing import Any
 
@@ -17,15 +19,18 @@ from ci_time_tracker.detection import DEFAULT_REGRESSION_THRESHOLD
 from ci_time_tracker.gates import GATE_CHOICES, evaluate_gates, evaluate_impact_gates
 from ci_time_tracker.github_api import (
     DEFAULT_RUN_LIMIT,
+    DEFAULT_WORKERS,
     GitHubAPIError,
     GitHubClient,
     fetch_build_logs,
     fetch_impact_inputs,
     resolve_token,
 )
+from ci_time_tracker.html_report import format_html
 from ci_time_tracker.impact import compare_run, format_impact_markdown
 from ci_time_tracker.log_parser import parse_log
-from ci_time_tracker.pricing import load_pricing
+from ci_time_tracker.pricing import PricingTable, load_pricing
+from ci_time_tracker.recommendations import parse_workflow, recommend
 from ci_time_tracker.reporter import (
     format_json,
     format_markdown,
@@ -215,10 +220,10 @@ def parse_args(args: list[str] | None = None) -> argparse.Namespace:
     parser.add_argument(
         "--format",
         type=str,
-        choices=["json", "text", "markdown"],
+        choices=["json", "text", "markdown", "html"],
         default="text",
         help="Output format (default: text). Markdown suits $GITHUB_STEP_SUMMARY "
-             "and PR comments.",
+             "and PR comments; html is a self-contained page with charts.",
     )
     
     parser.add_argument(
@@ -357,6 +362,80 @@ def load_estimates(path: str) -> dict[str, float]:
     return estimates
 
 
+def _default_branch_if_mixed(repo: str, logs: list[Any]) -> str | None:
+    """The repository's default branch, when the runs span several branches.
+
+    Regressions are looked for on that branch only; with a single branch
+    there is nothing to choose and no request is made.
+    """
+    branches = {log.metadata.get("branch") for log in logs if log.metadata.get("branch")}
+    if len(branches) < 2:
+        return None
+    try:
+        return GitHubClient(repo=repo, token=resolve_token()).fetch_default_branch()
+    except (GitHubAPIError, KeyError, TypeError):
+        return None
+
+
+def _visibility_pricing(logs: list[Any], pricing: Any) -> tuple[PricingTable, str | None]:
+    """Pricing for the repository's visibility, read from its runs.
+
+    Public repositories pay nothing for standard GitHub-hosted runners. When
+    the runs do not say, list prices are kept and no visibility is claimed.
+    """
+    pricing = pricing or PricingTable()
+    private = next(
+        (log.metadata["repository_private"] for log in logs if log.metadata.get("repository_private") is not None),
+        None,
+    )
+
+    if private is False:
+        return replace(pricing, public_repository=True), "public"
+    if private is True:
+        return pricing, "private"
+    return pricing, None
+
+
+# Most distinct workflow files fetched to cross with the history
+_MAX_WORKFLOW_FILES = 20
+
+
+def _fetch_workflows(repo: str, logs: list[Any]) -> dict[str, dict[str, Any]]:
+    """Fetch and parse the workflow files behind the analyzed runs.
+
+    Recommendations that need a workflow's configuration skip the ones that
+    cannot be read, so a failure here only narrows what is recommended.
+    """
+    paths = sorted({
+        log.metadata["workflow_path"]
+        for log in logs
+        if str(log.metadata.get("workflow_path") or "").startswith(".github/workflows/")
+    })[:_MAX_WORKFLOW_FILES]
+
+    if not paths:
+        return {}
+
+    client = GitHubClient(repo=repo, token=resolve_token())
+
+    def fetch(path: str) -> tuple[str, str | None]:
+        try:
+            return path, client.fetch_workflow_file(path)
+        except GitHubAPIError as e:
+            print(f"Warning: could not read {path} ({e}); skipping its recommendations", file=sys.stderr)
+            return path, None
+
+    # Fetched concurrently: these requests are not cached, and one after the
+    # other they added over a second to a cached analysis
+    workflows: dict[str, dict[str, Any]] = {}
+    with ThreadPoolExecutor(max_workers=min(DEFAULT_WORKERS, len(paths))) as pool:
+        for path, text in pool.map(fetch, paths):
+            parsed = parse_workflow(text) if text else None
+            if parsed is not None:
+                workflows[path] = parsed
+
+    return workflows
+
+
 def _no_runs_message(args: argparse.Namespace) -> str:
     """Explain an empty result, pointing at the default branch when it differs.
 
@@ -406,6 +485,7 @@ def _run_impact(args: argparse.Namespace, pricing: Any) -> int:
         if cache is not None:
             cache.close()
 
+    pricing, _ = _visibility_pricing(run_logs, pricing)
     impact = compare_run(
         run_logs,
         baseline,
@@ -511,6 +591,11 @@ def main() -> int:
             # Load estimates if provided
             estimates = None
             if args.estimates:
+                print(
+                    "Warning: --estimates is deprecated and will be removed: use --github "
+                    "for durations measured from real runs",
+                    file=sys.stderr,
+                )
                 try:
                     estimates = load_estimates(args.estimates)
                 except (OSError, FileNotFoundError) as e:
@@ -587,6 +672,7 @@ def main() -> int:
                 except Exception as e:
                     print(f"Warning: run cache unavailable ({e})", file=sys.stderr)
 
+            skipped: list[str] = []
             try:
                 logs = fetch_build_logs(
                     repo=args.github,
@@ -594,6 +680,7 @@ def main() -> int:
                     branch=args.branch,
                     limit=args.last,
                     cache=cache,
+                    skipped=skipped,
                 )
             except GitHubAPIError as e:
                 print(f"Error: {e}", file=sys.stderr)
@@ -607,12 +694,27 @@ def main() -> int:
                 return 1
 
             # Analyze
+            pricing, visibility = _visibility_pricing(logs, pricing)
             result = analyze_logs(
                 logs,
                 pricing,
                 args.group_matrix,
                 regression_threshold=args.regression_threshold,
+                regression_branch=_default_branch_if_mixed(args.github, logs),
             )
+            result.metadata["repository"] = args.github
+            if visibility:
+                result.metadata["repository_visibility"] = visibility
+            if skipped:
+                result.metadata["skipped_runs"] = len(skipped)
+                print(
+                    f"Warning: left out {len(skipped)} run(s) GitHub failed to return: "
+                    f"{', '.join(skipped[:5])}",
+                    file=sys.stderr,
+                )
+            result.recommendations = [
+                item.to_dict() for item in recommend(logs, _fetch_workflows(args.github, logs), pricing)
+            ]
 
         else:
             # Should never reach here due to argparse
@@ -627,6 +729,8 @@ def main() -> int:
             output = format_json(report)
         elif args.format == "markdown":
             output = format_markdown(report, args.top)
+        elif args.format == "html":
+            output = format_html(report, args.top)
         else:
             output = format_text(report, args.top)