Add period-completeness helpers

[mcaselli]

Summary

Adds a shared, business-day-aware period-completeness toolkit, and aligns the existing most_recent_* helpers with it.

New functions

• period_is_complete(date, unit, as_of, calendar, week_start) — is the period (week/month/quarter/year) containing each date complete as of the cutoff as_of? A period is complete once no business days remain after as_of up to and including the period end, evaluated in a QuantLib calendar.
  • calendar = "WeekendsOnly" (default): complete once only weekends remain.
  • a national calendar (e.g. "UnitedStates"): holiday-accurate.
  • calendar = "Null": pure calendar-day semantics (period_end_date(date) <= as_of).
• period_start_date() / period_end_date() — canonical first/last calendar day of the period. Business-day calendars only ever inform completeness, never the returned dates.
• filter_complete_periods(data, date_col, ...) — keep only rows whose period is complete; as_of defaults to max(date_col) so completeness tracks how current the data is.
• last_complete_period_start() / last_complete_period_end() — boundaries of the most recent complete period as of a cutoff.
• scale_alpha_logical() — ggplot2 alpha scale to fade the in-progress period; pairs with period_is_complete().

as_of has no wall-clock default

period_is_complete() and last_complete_period_*() require an explicit as_of — there is no Sys.Date() default. Completeness is a data-currency judgment, and this work runs mostly on cached extracts, so silently keying off the wall clock would misread stale data (e.g. marking a past-but-partial month complete). Pass Sys.Date() to opt into wall-clock behaviour. filter_complete_periods(), which sees the data frame, defaults as_of to max(date_col).

max(date) is deliberately not a default for period_is_complete(): its date argument is frequently period anchors from group_by(month = period_start_date(...)), where the max is the latest bucket start, not how current the data is.

Behaviour change: most_recent_*

most_recent_monday() / most_recent_sunday()'s ref_date argument is renamed as_of, for a consistent reference-date name across the temporal helpers (both name the date that state is evaluated as of). Their current-date default is unchanged and positional calls are unaffected — only callers passing ref_date = by name need to switch to as_of =.

Notes

• Built on the existing qlcal engine (bizdays_between()) and calendar scoping.
• week_start defaults to getOption("lubridate.week.start", 7) so the package defers to the session's week convention.
• Vectorizes correctly over a date span (a fix over a prior implementation that mis-judged future periods when as_of sat on its own period's last business day).
• Vignette gains a Period completeness section whose examples are chosen so each illustrated argument visibly changes the output — e.g. a holiday example on the July-4th work week, where "UnitedStates" reports the week complete but the default "WeekendsOnly" does not.

Tests

test-period_completeness.R (33 test_that blocks) covers weekend/holiday month-end edges, as_of on the period end, "Null" equivalence, the vectorization regression, last_complete_period_* step-back, filter_complete_periods default / guarded as_of, required-as_of errors, NA propagation, leap-February, year-end, and week_start; plus a named-as_of test for most_recent_*. Full suite: 275 pass, 0 failures, 0 warnings. R CMD check: 0 errors, 0 warnings (2 environmental NOTEs).