feat(cli): add codecarbon ci-report

[davidberenstein1957]

What this adds

A new CLI command, codecarbon ci-report, that turns the emissions.csv a CI job leaves behind into something the pipeline can actually show or gate on. It reads the rows of the most recent run (CodeCarbon appends one delta row per flush, all sharing a run_id, so those rows are summed), optionally diffs against a baseline CSV from the target branch, and prints markdown or JSON.

Nothing here is specific to a CI provider — GitLab, Jenkins and Buildkite get it for free alongside GitHub Actions.

User-facing surface

$ codecarbon monitor -- pytest -q
$ codecarbon ci-report --label "pytest -q" --baseline base/emissions.csv
**🌱 CodeCarbon** — `pytest -q`
**12.4 g CO2eq** (0.031 kWh, 94 s) — **+1.9 g (+18%)** vs baseline

Option	Default	Description
--csv PATH	emissions.csv	Run to summarise.
--baseline PATH	none	Run to compare against; a missing file degrades to no comparison rather than an error.
--format markdown|json	markdown	Output format.
--label TEXT	project name	Label shown in the report header.
--threshold-kg FLOAT	none	Exit 1 above this many kgCO2eq.

On GitHub Actions the markdown goes straight to a job summary with no token and no extra permissions:

- run: codecarbon ci-report --label "pytest -q" >> "$GITHUB_STEP_SUMMARY"

Implementation is codecarbon/cli/ci_report.py (stdlib csv, no new dependency and no new extra) plus the Typer command registered next to monitor and detect. Docs go in docs/reference/cli.md alongside the other commands, including an explicit caveat that hosted runners have no RAPL and fall back to the CPU-model TDP estimate, so values are comparable between identical runners rather than absolute.

How it was verified

uv run pytest tests/cli tests/test_docs_examples.py tests/test_package_integrity.py -q — 94 passed, 13 of them the new tests/cli/test_cli_ci_report.py, covering multi-row aggregation by run_id, positive/negative/zero deltas, a zero baseline (no ZeroDivisionError), a missing baseline, missing/empty/foreign CSVs exiting cleanly without a traceback, JSON keys, and both sides of the threshold. black --check and ruff check were run scoped to the touched files; the remaining ruff findings are pre-existing repo-wide style rules (Optional[...], blind except Exception) that the surrounding code already follows.

Deliberately left out

The composite GitHub Action, PR-comment posting, and base-branch artifact download. Those are thin wrappers over this command and carry CI-specific maintenance (token permissions, fork-PR degradation, floating tag policy, marketplace packaging) that shouldn't gate the portable half. A job summary already covers the useful case with no permissions at all. Happy to follow up with the action once this command has settled.

Closes #1351

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 91.56%. Comparing base (065d0e6) to head (6521851).

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1364      +/-   ##
==========================================
+ Coverage   91.39%   91.56%   +0.16%     
==========================================
  Files          49       50       +1     
  Lines        5056     5134      +78     
==========================================
+ Hits         4621     4701      +80     
+ Misses        435      433       -2     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.