Refactor shared analytics schema consistency validators

[Mattsface]

Summary

Implements the final schema/validator cleanup slice of #44.

• extracts small shared helpers for repeated analytics-schema consistency invariants
• preserves explicit baseball-specific models and validators
• consolidates prior-window pair validation
• consolidates summary game-count vs chart-point validation
• consolidates league teams-represented vs team-game-record validation
• consolidates team/league season consistency validation
• adds cross-model characterization tests through the public Pydantic models

Scope intentionally excluded

• route changes
• chart changes
• analytics formula changes
• persistence or ingestion changes
• template/static changes
• Player UI
• generic analytics model/configuration frameworks

Behavior

This is intended to be behavior-preserving. Existing validation messages and domain-specific checks remain explicit where semantics differ.

Validation

PR CI should be treated as the authoritative full pytest/Ruff validation before merge.

Refs #44

[Mattsface]

@claude please review

[claude]

Claude finished @Mattsface's task in 1m 17s —— View job

---

Code Review: Refactor shared analytics schema consistency validators

• Gather context (PR diff, changed files)
• Read app/schemas/analytics.py changes in full
• Read new test file tests/test_analytics_schema_consistency.py
• Check adherence to AGENTS.md (schemas layer rules, abstraction rules)
• Cross-check refactor for behavior preservation
• Post review feedback

Summary

This is a clean, well-scoped refactor. I diffed app/schemas/analytics.py against origin/main line-by-line and confirmed the four extracted helpers (_validate_prior_window_pair, _validate_summary_point_count, _validate_teams_within_records, _validate_league_season) are pure mechanical extractions — every inlined if/raise ValueError block was replaced with an identical error message, with no wording or condition changes. I also grepped for any leftover inline duplicates of these patterns and found none, so the extraction is complete and consistent.

Call-site counts line up with what I'd expect from the class list (8 _validate_prior_window_pair incl. definition → 7 summaries, 9 _validate_summary_point_count → 8 analyses+comparison, 6 _validate_teams_within_records → 5 league contexts, 7 _validate_league_season → 6 comparisons), so nothing was missed or double-applied.

Architecture / AGENTS.md fit

• Helpers live as private module-level functions inside app/schemas/analytics.py itself, not a new utils.py/helpers.py — consistent with the module-ownership rule.
• TeamPitchingSummary's prior_window_era field correctly threads through value_field_name="prior_window_era" so its error message still reads "prior_window_era and change_vs_prior_window..." rather than being silently renamed to "prior_window_average" — good catch, this is exactly the kind of thing that's easy to break in a mechanical refactor.
• Domain-specific validators (rate-consistency checks like hits_per_game == total_hits / team_game_records, ERA/WHIP formulas, Pythagorean record, etc.) were correctly left inline and un-abstracted, matching the "honest duplication over premature abstraction" guidance and the module's own docstring rationale.
• Scope is tight: only app/schemas/analytics.py and the new test file changed — no route/chart/analytics-formula/persistence changes, matching the stated "scope intentionally excluded" list.

Tests

tests/test_analytics_schema_consistency.py characterizes the four shared invariants through the public Pydantic models (via model_dump() → mutate → model_validate()), which fits the testing philosophy of protecting meaningful behavior rather than testing the private helpers directly. It reuses existing tests/factories.py builders rather than adding new ones. Parametrization is sensible (valid/invalid boundary cases, ids based on model type) and asserts exact error message text, so it would catch a regression in the extracted helpers.

Notes / limitations

• I was not able to execute pytest/ruff in this session — those invocations required approval that wasn't available here, so I relied on a careful static/manual review (full diff read, grep cross-checks of call counts) instead. Per the PR description, CI is the authoritative validation gate before merge; I'd defer to that for final pytest/Ruff confirmation.
• No correctness, architecture, or scope issues found.