49 lines
3.7 KiB
Markdown
49 lines
3.7 KiB
Markdown
# OpenSpec Change: datetime-spec-conformance
|
|
|
|
- **Change ID**: datetime-spec-conformance
|
|
- **Package**: `@suaveplan/datetime`
|
|
- **Status**: PROPOSED
|
|
- **Date**: 2026-04-26
|
|
|
|
## Summary
|
|
|
|
Bring `@suaveplan/datetime` into spec conformance with `openspec/specs/datetime/spec.md`. Add `**Verified by:**` lines to every requirement, pin implicit scenarios with a single `*.spec-conformance.test.ts`, and rectify one piece of real OTel drift (DT-09) inline. Clear the `retroactive-ticking` marker so `bun scripts/openspec-conformance.ts @suaveplan/datetime` exits 0.
|
|
|
|
## Current state
|
|
|
|
`@suaveplan/datetime` ships a complete enterprise-grade implementation: `DatetimeError` extending `SuaveplanError` with three `DATETIME.*` codes, Zod boundary schemas in `types/datetime.schemas.ts`, injectable `Clock` on `formatRelative` / `timeAgo` / `timeUntil` / `expandRecurrence`, `BusinessDayOptions` with custom `holidays` and `weekendDays`, AbortSignal cooperative cancellation, RRULE parser/formatter with `FREQ`/`INTERVAL`/`COUNT`/`UNTIL`/`BYDAY`/`BYMONTHDAY`, calendar arithmetic with month-clamp, fast-check property tests, and a mitata benchmark suite. The conformance gaps are:
|
|
|
|
- DT-09 spec mandates **histograms** for both `expandRecurrence` and `businessDaysBetween` tracking call duration **and** output size. Implementation only had a duration histogram for `expandRecurrence` and a counter for `businessDaysBetween` — missing the size histogram for both and the duration histogram for `businessDaysBetween`.
|
|
- 11/11 requirements lacked `**Verified by:**` lines.
|
|
- Implicit scenarios across DT-01..DT-10 were exercised indirectly only.
|
|
- `tasks.md` of `2026-04-19-enterprise-datetime/` carries the `retroactive-ticking` marker.
|
|
|
|
## What changes
|
|
|
|
1. Wire four additional OTel histograms inline (DT-09) without breaking the pre-existing surface:
|
|
- `expandRecurrenceSize` — number of occurrences emitted per call.
|
|
- `businessDaysBetweenDuration` — wall-clock duration per call.
|
|
- `businessDaysBetweenSize` — day-intervals walked per call.
|
|
- `recordExpandRecurrence(durationMs, size?)` and `recordBusinessDaysBetween(count, durationMs?)` updated additively (extra params are optional, all old call sites still compile).
|
|
- Both hot paths (`expandRecurrence` + `businessDaysBetween`) now feed both duration and size on every call.
|
|
2. Add `**Verified by:**` line under every requirement in `openspec/specs/datetime/spec.md`.
|
|
3. Add `src/datetime.spec-conformance.test.ts` (20 tests) pinning DT-01..DT-10:
|
|
- DT-01 — DateInput accept Date / ISO / epoch + invalid throws PARSE.INVALID_INPUT.
|
|
- DT-02 — `formatRelative` / `timeAgo` / `timeUntil` / `expandRecurrence` honour injected clock.
|
|
- DT-03 — six business-day functions accept holidays + custom weekendDays + pre-aborted signal.
|
|
- DT-04 — Jan 31 + 1 month clamp (Feb 28 / 29), `subtractDuration` mirrors `addDuration`, `daysInMonth` + `isLeapYear`.
|
|
- DT-05 — RRULE field round-trip + INFINITE_EXPANSION throw.
|
|
- DT-06 — codes namespaced under `DATETIME.*` and registry frozen.
|
|
- DT-07 — every Zod schema parses a representative payload.
|
|
- DT-08 — English pass-through label variants (just-now / past / future / plural).
|
|
- DT-09 — duration + size histograms + counter exist for both hot paths.
|
|
- DT-10 — `package.json` declares `sideEffects: false`.
|
|
4. Re-run `bun scripts/openspec-conformance.ts @suaveplan/datetime` and confirm exit 0.
|
|
|
|
## Impact
|
|
|
|
- Public API gains four additional OTel histogram exports (additive only; all prior exports preserved).
|
|
- One new test file (~330 lines).
|
|
- `openspec/specs/datetime/spec.md` gains 11 `**Verified by:**` lines.
|
|
- `recordExpandRecurrence` and `recordBusinessDaysBetween` accept additional optional parameters (backwards compatible).
|