Add extended runtime + ParsedDateTime API for large years

[abhishekpradhan]

Summary

• add ExtendedDateTime runtime support for years beyond Jiff's in-range civil datetime support
• introduce ParsedDateTime (InRange | Extended) and return it from parser entry points
• route parsing/building through an extended path for large-year and boundary-rollover cases
• preserve GNU-compatible relative month/year semantics in both in-range and extended flows
• add focused regression/coverage tests for rollover, parity behavior, offsets, error paths, and named-timezone in-range transitions

Context

• follows merged groundwork PR: Groundwork: widen year parsing bounds for GNU max year #261
• this PR is the runtime/API step and now includes the focused tests needed to keep CI and coverage green
• after this PR merges, the follow-up will be limited to docs polish and any remaining parity cleanup (no additional API surface)

Reviewer Guide

1. API and entrypoint changes
   • src/lib.rs
   • src/items/mod.rs
   • tests/common/mod.rs
2. Runtime behavior and correctness
   • src/items/builder.rs
   • src/extended.rs
3. Parser wiring updates
   • src/items/epoch.rs
   • src/items/offset.rs
   • src/items/weekday.rs
4. Behavioral evidence tests
   • tests/large_year.rs
   • tests/time.rs
   • module tests in src/items/mod.rs, src/items/builder.rs, src/extended.rs

Validation

• cargo fmt --all -- --check
• cargo clippy --all-targets -- -D warnings
• cargo test -q

[codecov]

Codecov Report

❌ Patch coverage is 99.53307% with 6 lines in your changes missing coverage. Please review.
✅ Project coverage is 99.29%. Comparing base (4a1b3f3) to head (103addc).
⚠️ Report is 4 commits behind head on main.

Files with missing lines	Patch %	Lines
src/items/builder.rs	99.06%	4 Missing ⚠️
src/items/mod.rs	99.41%	1 Missing ⚠️
src/lib.rs	98.46%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #263      +/-   ##
==========================================
+ Coverage   98.92%   99.29%   +0.37%     
==========================================
  Files          18       20       +2     
  Lines        2605     3846    +1241     
  Branches       69      121      +52     
==========================================
+ Hits         2577     3819    +1242     
+ Misses         27       26       -1     
  Partials        1        1              

Flag	Coverage Δ
macos_latest	99.29% <99.53%> (+0.37%)	⬆️
ubuntu_latest	99.29% <99.53%> (+0.37%)	⬆️
windows_latest	17.96% <12.52%> (-2.46%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 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.

[abhishekpradhan]

Status update: I closed the two superseded fork-only stacked PRs to reduce review noise.

• Add extended runtime + ParsedDateTime API for large years abhishekpradhan/parse_datetime#1
• Add large-year parity tests and README updates abhishekpradhan/parse_datetime#2

This PR is now the active runtime/API review path. The tests/docs follow-up (clean PR3 branch) is prepared and will be opened upstream immediately after this merges.

[sylvestre]

This is a semver-breaking change.
you are changing the public profile of crate
are you sure it is necessary?

[abhishekpradhan]

How does this work for semver? I've changed it so the existing parse_datetime and parse_datetime_at_date APIs keep returning Zoned, and the ParsedDateTime behavior is exposed through separate extended-aware entrypoints instead.