Add `closest <weekday>` to getdate

[wilsonfreitas]

Add closest <weekday> to getdate

Problem

Add a new getdate expression form, closest <weekday>, so date references can
resolve to the nearest weekday on or before the reference date. Example:
closest fri with a Wednesday reference should return the Friday from the same
week that is before the given date, not the first Friday after it.

Chosen scope

• closest <weekday> is supported only for date refs (YYYY-MM-DD,
  datetime.date, datetime.datetime, numpy.datetime64).
• Month refs (YYYY-MM) and year refs (YYYY / integer) should reject
  closest <weekday> with a clear error instead of inventing an arbitrary anchor.
• When the reference date is already on the requested weekday, closest <weekday>
  returns the same date.

Current parser and behavior notes

• The parser currently supports:
  • simple expressions: <ordinal> <target>
  • composite expressions:
    <ordinal> <target> <before|after> <ordinal> <target>
  • date-relative expressions: <next|previous> <weekday>
• Date refs currently allow only weekday-based relative expressions:
  next <weekday>, previous <weekday>, and positive-count weekday forms such
  as first wed or second fri, which resolve after the reference date.
• Month/year refs currently use period-based resolution and have no date anchor,
  which is why closest is ambiguous there.

Proposed implementation approach

1. Extend bizdays/getdate_parser.py
   • Add a new parsed expression variant for closest <weekday>.
   • Keep it restricted to weekday targets only.
2. Extend bizdays/dateindex.py
   • Add date-ref resolution logic that maps closest <weekday> to the nearest
     matching weekday on or before the reference date.
   • Preserve current next, previous, and first/second/... <weekday>
     behavior.
   • Reject closest <weekday> for month/year refs with an explicit error.
3. Keep the public wrapper unchanged in bizdays/calendar.py
   • Calendar.getdate(...) should continue delegating to DateIndex.
4. Add tests
   • parser coverage for the new 2-token form
   • date-ref examples where the closest weekday is before the date
   • same-day case (closest fri on a Friday)
   • rejection for month refs and year refs
   • DateIndex.getdate(...) parity tests
5. Update docs
   • expand the grammar docs in docs/source/api.rst
   • update docs/source/getdate.ipynb and notebooks/getdate.ipynb
   • clarify that closest is date-ref-only

Files likely to change

• bizdays/getdate_parser.py
• bizdays/dateindex.py
• tests/test_getdate.py
• docs/source/api.rst
• docs/source/getdate.ipynb
• notebooks/getdate.ipynb

Resolved behavior detail

• closest <weekday> means “the same weekday if the reference already matches,
  otherwise the most recent prior weekday”.