feat: add cache staleness classification

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

2 files changed, 31 insertions, 0 deletions

diff --git a/lib/weather.lua b/lib/weather.lua
index d36bcf5..b1fda4d 100644
--- a/lib/weather.lua
+++ b/lib/weather.lua
@@ -186,4 +186,21 @@ function M.parse(src)
   return w
 end
 
+-- Three missed fetches at the 15-minute interval.
+M.STALE_AFTER = 45 * 60
+
+function M.is_stale(dt, now)
+  if type(dt) ~= 'number' then return true end
+  return (now - dt) > M.STALE_AFTER
+end
+
+-- Short age for the marker beside the city: "12m", "3h", "2d".
+function M.age_str(dt, now)
+  if type(dt) ~= 'number' then return '?' end
+  local s = now - dt
+  if s < 3600 then return math.floor(s / 60) .. 'm' end
+  if s < 86400 then return math.floor(s / 3600) .. 'h' end
+  return math.floor(s / 86400) .. 'd'
+end
+
 return M
diff --git a/test/test_weather.lua b/test/test_weather.lua
index 739161b..95908ce 100644
--- a/test/test_weather.lua
+++ b/test/test_weather.lua
@@ -208,4 +208,18 @@ local exp = weather.parse(
   '"sys":{"sunrise":100,"sunset":200}}')
 assert(exp and exp.temp == 18, 'exponent form, got ' .. tostring(exp and exp.temp))
 
+-- === Staleness ============================================================
+-- 45 minutes is three missed fetches at the 15-minute interval, so one
+-- transient failure does not flag the card.
+assert(weather.is_stale(1000, 1000) == false, 'a fresh reading is not stale')
+assert(weather.is_stale(1000, 1000 + 45 * 60) == false, 'exactly 45 min is the boundary')
+assert(weather.is_stale(1000, 1000 + 45 * 60 + 1) == true, 'past 45 min is stale')
+assert(weather.is_stale(nil, 1000) == true, 'no observation time counts as stale')
+
+-- The age string is what the card prints beside the city, so it must be short.
+assert(weather.age_str(1000, 1000 + 90) == '1m', 'ninety seconds reads as 1m')
+assert(weather.age_str(1000, 1000 + 3600) == '1h', 'an hour reads as 1h')
+assert(weather.age_str(1000, 1000 + 7200) == '2h', 'two hours')
+assert(weather.age_str(1000, 1000 + 86400 * 2) == '2d', 'days, once it gets that bad')
+
 print('test_weather: all assertions passed')