feat(cli): add codecarbon badge command

[davidberenstein1957]

Implements #1349.

What it adds

A codecarbon badge command that turns an existing emissions.csv into README badge artefacts. Strictly local: it reads the CSV, writes files, and prints a snippet. No network call, no hosted service, no account, no new dependency (stdlib csv, json and string templating only).

User-facing surface

codecarbon badge [--file PATH] [--project TEXT] [--select last|mean|total]
                 [--metric emissions|energy|both] [--output-dir PATH]
                 [--label TEXT] [--color TEXT] [--format svg|json|all]

It writes codecarbon-badge.svg (a flat shields-style badge from a small string template) and codecarbon-badge.json (the shields.io endpoint schema, for users who want to publish it themselves), then prints the markdown to paste into a README.

The logic lives in codecarbon/badge.py, whose functions (load_runs, summarise, format_value, render_svg, render_endpoint_json, render, write) are usable directly from Python. The CLI command sits next to detect in codecarbon/cli/main.py. No tracker or output-method changes.

Colour-neutral by default. No automatic green/orange/red thresholds. CodeCarbon numbers are frequently estimates (TDP-modelled CPU power, country-average intensity), and no fixed gram threshold means anything across arbitrary workloads, so an automatic green badge would be greenwashing. Users who want a colour pass --color. The docs say plainly that a badge is an order-of-magnitude signal, not an audited figure.

Verification

tests/test_badge.py, 15 tests, no network, tmp_path for outputs: project filtering, the three aggregations against hand-computed values, unit formatting from mg to Mg, SVG well-formedness via xml.etree.ElementTree plus XML escaping, endpoint JSON schema, clean errors on a missing file and an empty project selection, and two typer.testing.CliRunner runs against the real command.

uv run pytest tests/test_badge.py tests/test_package_integrity.py tests/test_docs_examples.py -q   # all pass

black --check and ruff check were run scoped to the touched files; formatting is clean and the remaining ruff notes are pre-existing repo-wide style patterns (Optional[...], typer.Option defaults) that the surrounding code already uses.

Deliberately left out

• Colour thresholds (see above).
• The four badge_* config keys from the proposal. Flags only for now; config keys are permanent surface for a command normally run by hand, and can follow if the CI recipe turns out common.
• A badge output method firing on every tracker stop. The CSV is the source of truth, regenerate on demand.
• Any hosted endpoint or ingestion service, badge history/trend graphs, and a GitHub Action.
• Font metrics for pixel-accurate text width. Widths are estimated per character, which can be a pixel or two off, and a font dependency is not worth that.

Docs: a codecarbon badge section in docs/reference/cli.md and a cross-link from docs/how-to/visualize.md.

Closes #1349

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 97.95918% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 91.55%. Comparing base (065d0e6) to head (07f0373).

Files with missing lines	Patch %	Lines
codecarbon/badge.py	97.50%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1357      +/-   ##
==========================================
+ Coverage   91.39%   91.55%   +0.16%     
==========================================
  Files          49       50       +1     
  Lines        5056     5153      +97     
==========================================
+ Hits         4621     4718      +97     
  Misses        435      435              

☔ 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.