feat: support reverse geocoding for coordinates

[IceCodeNew]

Summary

Allow a watched location to be configured with either a complete name or a complete coordinate pair while keeping id required.

This is intentionally separate from #28: that PR improves notification relevance using the currently required user-provided name; this PR changes the location configuration contract and adds reverse geocoding for coordinate-only entries.

Configuration contract

• id remains required; its existing validation and error semantics are unchanged.
• Provide name, both latitude and longitude, or all three.
• A single coordinate remains invalid.
• Name only: use the existing forward-geocoding and precision-reduction path.
• Name and coordinates: trust the configured values and make no geocoding request.
• Coordinates only: call Nominatim /reverse, then cache the canonical display name, country code, and administrative area.

Changes

• Add a platform-neutral reverse-geocoding provider boundary and Nominatim implementation.
• Share Nominatim request serialization and rate limiting between forward and reverse requests.
• Cache coordinate-only resolutions under a coordinate-specific key.
• Keep the final resolved name available to downstream location-scope logic.
• Update requirements, design, README, configuration validation, and focused tests.

Privacy review

Committed examples and tests use public sample coordinates and place names only. No private location file, runtime cache, feed URL, credentials, recipient identifiers, or state is included.

Dependency note

The branch is rebased on the merge of #28. Its notification-relevance and source-attribution behavior is preserved; this PR changes only the location configuration and resolution contract.

Validation

• mise exec -- uv run --with pytest --with pytest-cov -- pytest --cov --cov-branch --cov-report=xml — 438 passed
• prek run — all checks passed
• Line coverage: 99.69% (master: 99.68%)
• Branch coverage: 98.28% (master: 98.22%)

[coderabbitai]

Warning

Review limit reached

@IceCodeNew, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 27 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: cdd747d0-c092-4279-9214-5d903aff794d

📥 Commits

Reviewing files that changed from the base of the PR and between db028ff and 3ae1f8a.

📒 Files selected for processing (9)

• README.md
• docs/design.md
• docs/requirements.md
• tests/test_config.py
• tests/test_geocoding.py
• weather_briefing/cli.py
• weather_briefing/config.py
• weather_briefing/geocoding.py
• weather_briefing/models.py

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/reverse-geocoding-locations

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.49%. Comparing base (db028ff) to head (3ae1f8a).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##           master      #29      +/-   ##
==========================================
+ Coverage   99.47%   99.49%   +0.01%     
==========================================
  Files          39       39              
  Lines        5334     5506     +172     
  Branches      309      319      +10     
==========================================
+ Hits         5306     5478     +172     
  Misses         17       17              
  Partials       11       11              

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

[Copilot]

Pull request overview

This PR updates the location configuration contract to allow a watched location to be specified by name, coordinates, or both, and adds reverse geocoding (Nominatim /reverse) to resolve coordinate-only entries into a canonical display name plus administrative metadata. It fits into the existing geocoding/resolution pipeline by extending the provider boundary and enhancing the cache-backed resolver to support a coordinate-only path.

Changes:

• Make LocationSpec.name optional and update configuration validation to accept either name or a complete (latitude, longitude) pair.
• Add a reverse-geocoding provider boundary and implement reverse geocoding in NominatimGeocodingProvider, wired into CachedLocationResolver and the CLI.
• Add focused tests and update docs/README to reflect the new configuration and resolution behavior.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
weather_briefing/models.py	Makes LocationSpec.name optional to support coordinate-only entries.
weather_briefing/geocoding.py	Adds reverse geocoding support, integrates it into the cached resolver, and tightens name-handling via helper.
weather_briefing/config.py	Updates location-file parsing/validation to allow name-only, coords-only, or both.
weather_briefing/cli.py	Wires Nominatim reverse geocoding into the runtime resolver configuration.
tests/test_geocoding.py	Adds reverse-geocoding and coordinate-only resolver/cache tests.
tests/test_config.py	Updates config tests for the new location contract and validation errors.
README.md	Updates user-facing configuration and geocoding behavior documentation.
docs/requirements.md	Updates requirements to specify the revised location contract and reverse-geocoding behavior.
docs/design.md	Updates design notes to reflect forward vs reverse resolution paths and caching.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated no new comments.