feat(collector): add per-installer badge files (installer-mix v2)

[cmeans-claude-dev]

Summary

First v2 badge candidate from the project's "Future badge candidates" backlog: per-installer breakdown of non-CI downloads, surfaced as seven additional shields.io endpoint badge JSON files per package per window (six individual installers + a pip-family aggregate). v1 hero kept side-by-side, additive throughout.

What's in the diff

• run_pypinfo returns dict[str, int] instead of int (allowlist filter and CI filter unchanged; six-keyed dict, zero-filled, ordered via new _INSTALLER_NAMES tuple).
• _collect_one writes 8 badge files per successful package (1 v1 hero + 7 v2). Driven by a new module-level _INSTALLER_BADGE_SPECS tuple so the (filename, label, counts_key) relationship is visible at a glance.
• PackageOutcome.counts: dict[str, int] | None carries the per-installer breakdown.
• _health.json per-package successful entries gain a counts field (additive; top-level count preserved verbatim for backwards compat).
• README.md dogfood badge row expanded with the six individual installer badges; new ## Use this service for your own package section between ## Install and ## Status documents the URL pattern for third-party packages (8-row table + URL-encoding gotcha + copy-pasteable markdown example).
• CHANGELOG.md [Unreleased] gets one ### Added bullet covering all of the above.

Spec / plan

In-tree on this branch:

• Spec: docs/superpowers/specs/2026-04-28-installer-mix-badge-design.md
• Plan: docs/superpowers/plans/2026-04-28-installer-mix-badge.md

Decisions made during brainstorming (Form A absolute counts / B3 bucketing / C1 non-CI filter only / no per-installer brand colors / no per-package configurability) all trace to the spec.

Backwards compatibility

• downloads-<N>d-non-ci.json filename, schema, and value unchanged for any given pypinfo response. Regression test (test_collect_v1_hero_count_unchanged_against_pre_v2_fixture) locks this in — same fixture, hero count must equal sum(per-installer).
• _health.json top-level fields unchanged. Per-package count field unchanged. New counts map is purely additive.

Version bump

This PR ships the feature only. The v0.2.0 release PR (separate, follows the v0.1.3 release flow) bumps pyproject.toml and triggers PyPI publish. Minor bump justified because run_pypinfo's return type changes; the function isn't _underscore-prefixed and tests / future internal callers depend on its shape.

Test plan

• CI passes: lint, typecheck, test (3.11/3.12/3.13), deploy-smoke, all green
• Coverage gate (fail_under = 100) maintained — locally 79 tests pass at 100% coverage (8 new tests + 8 pre-existing tests updated to assert on the new dict return shape, including 1 health-file test updated for the additive counts map)
• On the next v* tag (the v0.2.0 release), publish.yml extracts the ## [Unreleased] ### Added block via the awk extractor — locally validated against this CHANGELOG entry
• After deploying the new collector to CT 112, smoke-check that all 8 badge files appear under https://pypi-badges.intfar.com/<package>/ for each configured package; spot-check one via curl | jq to confirm shields.io endpoint shape

🤖 Generated with Claude Code

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[cmeans]

LGTM

[cmeans]

QA Round 1 — Findings

Reviewed at head 48d1904. CI all green. Local re-run: 79/79 pytest, 100% coverage on src/, ruff/format/mypy clean.

Spec ↔ implementation match

The spec (docs/superpowers/specs/2026-04-28-installer-mix-badge-design.md) calls for: run_pypinfo returns dict[str, int], six-keyed zero-filled allowlist, _collect_one writes 8 badge files (1 v1 hero + 6 individual + 1 pip-family aggregate), _health.json per-package gains additive counts map, README dogfood row expanded with 6 individual installers (pip-family deliberately omitted from dogfood per spec §README addendum), new "Use this service for your own package" section between Install and Status. All matched in the implementation; spec ↔ collector.py ↔ tests ↔ README align cleanly.

Backwards compatibility (the load-bearing claim of this PR)

Surface	Status
downloads-<N>d-non-ci.json filename / label / value	unchanged — hero_total = sum(per_installer.values()) is mathematically equivalent to the v1 single-pass sum over the same allowlist+CI-filtered rows
_health.json top-level fields (started, finished, packages)	unchanged
_health.json per-package count	unchanged (still the v1 hero total)
_health.json per-package error, window_days	unchanged
_health.json per-package counts	new, additive
PackageOutcome.counts field	inserted between count and error with default None — all existing call sites use keyword args, so positional drift doesn't bite

test_collect_v1_hero_count_unchanged_against_pre_v2_fixture and test_health_file_top_level_count_preserved lock both ends of the contract in CI.

Code review notes (no findings, just things checked)

• Allowlist + CI filter unchanged from v1 (installer not in _INSTALLER_ALLOWLIST skips, ci == "True" skips, missing installer_name raises).
• _INSTALLER_NAMES ordered tuple drives _INSTALLER_ALLOWLIST = frozenset(_INSTALLER_NAMES); single source of truth, no risk of the two falling out of sync.
• pip-family aggregate computed in _collect_one (sum of per_installer["pip"] + ["pipenv"] + ["pipx"]); run_pypinfo's zero-fill guarantees the three keys always exist, so no KeyError risk.
• _INSTALLER_BADGE_SPECS tuple makes the (filename, label, dict-key) relationship visible at a glance — clean enough that adding a future installer is an obvious edit.
• Per-package isolation preserved: any CollectorError or OSError inside _collect_one returns a failure outcome and skips badge writes for that package only.
• Failure-path _health.json entry shape unchanged ({error, window_days}, no counts key).
• badge.py and __main__.py unchanged — no surprise escape hatch into adjacent modules.
• shields.io endpoint URL encoding in the new README section (%2F/%3A) matches the existing v1 hero badge's encoding.

Findings

1. PR-body test-plan parenthetical undercounts the test work (observation).

Test-plan checkbox 2 reads: "locally 79 tests pass at 100% coverage (6 new tests + 1 pre-existing test updated for the additive health-entry shape)". The count is correct, but the breakdown is stale.

Counted against the diff:

• 8 new test functions: test_run_pypinfo_returns_per_installer_dict, test_run_pypinfo_zeroes_installers_with_no_rows, test_package_outcome_carries_per_installer_counts, test_health_file_includes_per_installer_counts_map, test_health_file_top_level_count_preserved, test_collect_writes_eight_files_per_successful_package, test_collect_pip_family_aggregate_equals_pip_plus_pipenv_plus_pipx, test_collect_v1_hero_count_unchanged_against_pre_v2_fixture.
• 8 pre-existing tests updated for the new return shape (the 7 test_run_pypinfo_* tests that previously asserted on count == X now assert on sum(result.values()) == X, plus test_collect_writes_health_file_with_per_package_counts_and_timestamps which got an expanded equality on the additive counts map).

The discrepancy doesn't affect outcome (coverage gate is 100%, all 79 pass) — it's a reading-accuracy nit. Spec's "Tests" section lists six named scenarios, two of which got split into two tests during implementation (e.g., returns_per_installer_dict and zeroes_installers_with_no_rows); the spec didn't make a "6 total" claim, so it's the PR body parenthetical that's stale, not the spec.

Suggested edit: update the parenthetical to "(8 new tests + ~8 pre-existing tests updated to assert on the new dict return shape)".

[cmeans]

QA round 1 → QA Failed (one observation).

Verdict basis: standing rule — every observation blocks signoff. The finding is low-priority (PR-body parenthetical inaccuracy, no behavioral impact); Dev can edit the test-plan parenthetical and re-apply Ready for QA.

What I ran:

• Local pytest: 79/79 pass at 100% coverage on src/, fail_under = 100 gate honored
• Local ruff check + format check: clean
• Local mypy: clean
• Spec ↔ collector.py ↔ tests ↔ README cross-walk: all match (8 badge files written, 6-keyed zero-filled run_pypinfo dict, pip-family aggregate = pip+pipenv+pipx, _health.json additive, dogfood row shows 6 individual installers per spec §README addendum)
• Backwards-compat regression locked by test_collect_v1_hero_count_unchanged_against_pre_v2_fixture and test_health_file_top_level_count_preserved

CI green at 48d1904 (lint, typecheck, test 3.11/3.12/3.13, deploy-smoke).

Checkbox 2 left unchecked because the finding is about its parenthetical text, not its substantive claim — once Dev edits, check on round 2.

[cmeans-claude-dev]

QA round 1 finding addressed.

Change: PR body test-plan parenthetical updated from (6 new tests + 1 pre-existing test updated for the additive health-entry shape) to (8 new tests + 8 pre-existing tests updated to assert on the new dict return shape, including 1 health-file test updated for the additive counts map).

Audit: counted against the diff exactly as QA did:

• 8 new test functions (across Tasks 1, 2, 3, 4): test_run_pypinfo_returns_per_installer_dict, test_run_pypinfo_zeroes_installers_with_no_rows, test_package_outcome_carries_per_installer_counts, test_collect_writes_eight_files_per_successful_package, test_collect_pip_family_aggregate_equals_pip_plus_pipenv_plus_pipx, test_collect_v1_hero_count_unchanged_against_pre_v2_fixture, test_health_file_includes_per_installer_counts_map, test_health_file_top_level_count_preserved.
• 8 pre-existing tests adapted: 7 test_run_pypinfo_* tests rewritten from count == X to sum(result.values()) == X (the int-to-dict ripple from Task 1), plus test_collect_writes_health_file_with_per_package_counts_and_timestamps updated for the additive counts map (Task 4).

No code changes — just the PR body text. CI re-run isn't needed since the diff at 48d1904 is unchanged.

[cmeans]

QA Round 2 — PASS

Head unchanged at 48d1904 — Dev's round-2 update was a PR-body edit only (test-plan parenthetical now correctly reads "8 new tests + 8 pre-existing tests updated to assert on the new dict return shape, including 1 health-file test updated for the additive counts map"). Round-1 finding fully addressed.

Re-verified in this session at the same SHA: 79/79 pytest, ruff check + format clean, mypy clean. All round-1 substantive verifications (spec ↔ collector.py ↔ tests ↔ README cross-walk, backwards-compat regression locked by test_collect_v1_hero_count_unchanged_against_pre_v2_fixture and test_health_file_top_level_count_preserved) carry forward unchanged.

CI green at 48d1904 (lint, typecheck, test 3.11/3.12/3.13, deploy-smoke).

Zero findings. Ready for QA Signoff.

[cmeans]

QA round 2 → Ready for QA Signoff.

Round 1's parenthetical observation is fully addressed at the PR-body level. Head SHA unchanged (48d1904), so the substantive verification carries forward; re-ran 79/79 pytest + ruff/format/mypy clean in this session per the standing pre-signoff verification rule. Spec ↔ implementation alignment, backwards-compat regression coverage, and CI green status all confirmed unchanged from round 1.

Awaiting maintainer QA Approved.