2.9 KiB
Changes Internals
internal/changes deterministically compares a compatible prior module
snapshot with the current snapshot. It returns compact structured changes for
prompt input; it never reads state, finds a prior report, renders Markdown, or
compares generated text. Snapshot construction belongs to
module internals, and prior-snapshot discovery belongs to
state internals.
Comparison inputs and output
Each comparator receives a prior snapshot, a current snapshot, and
Thresholds. A Change has a stable type and message plus previous and
current values where useful. Changes are sorted by type and then message, so
the same inputs always yield the same order.
Threshold values are supplied by application orchestration from the Recent Changes configuration; this package does not load configuration or choose defaults. Numeric changes are emitted when the absolute difference meets the configured threshold. Precipitation also requires a change between its low, possible, likely, and high categories.
Strategies
| Comparator | Required snapshot data | Compared values |
|---|---|---|
CompareDaily |
derived_daily_summary, derived_daypart_summaries |
Low and high temperature, daily precipitation probability and timing, peak gust, alerts, and aggregate indicators |
CompareThreeDay |
derived_daypart_summaries |
Per-day temperatures, precipitation probability and timing, peak gust, indicators, and added or removed outlook days |
CompareWeekend |
derived_daypart_summaries |
The three-day values with weekend-prefixed change types |
For daily comparison, alert_digest and precip_timing are optional: alerts
are compared when present, and timing is compared only when both snapshots
contain it. The multi-day comparators build their day map from daypart
summaries. A missing or added day becomes a dedicated change rather than a
comparison against invented data.
The application selects a comparator only after state lookup establishes a compatible prior snapshot. Daily, Today, and Tomorrow use the daily comparator; Three-day and Weekend use their named comparators. Other report types, such as Storm, produce no Recent Changes list.
Missing data and failures
Required stanzas that are absent or cannot be decoded return an error with the snapshot and stanza context. Optional stanzas may be absent. A snapshot with no eligible predecessor is not a comparison failure: the caller supplies an empty change list without invoking this package.
The package has no filesystem, transport, CLI, renderer, or persistence behavior. It does not decide report compatibility or retain snapshots.
Verification and invariants
Focused tests cover the daily, three-day, and weekend strategies, threshold boundaries, indicator and alert changes, and missing required stanzas:
go test ./internal/changes
Recent Changes always compare structured snapshot values, never report prose.