fix(kql): reject a bin() width we cannot bucket by, instead of silently using 5m

`kqlTimespanToTimeBucket` ended in `fromMaybe "5 minutes"`, so every width it
failed to parse became five minutes with no error anywhere. Measured on prod
against a fixed one-hour window, by row count:

  bin(timestamp, 30sec)  -> 5-minute buckets   (asked for 30 seconds)
  bin(timestamp, 10min)  -> 5-minute buckets   (asked for 10 minutes)
  bin(timestamp, 1mo/1M/1y/2wk) -> 5-minute buckets

The chart answered a different question than the one asked, and said nothing.
`5min` "worked" only by coincidence. Anyone arriving from Grafana or PromQL,
where `10min` and `1M` are ordinary, got a wrong chart silently.

It now returns Maybe, and `unsupportedTimespan` turns the Nothing into a
positioned parse error alongside the existing unknown-field diagnostics, so the
editor squiggles the width and names the spelling to use. `defaultBinWidth` is
a named constant because the fallback being an inline "5 minutes" is precisely
what kept this invisible; the two render sites keep it only for callers that
skip validation, and both say so.

DELIBERATELY NOT WIDENED: accepting sec/min/hr/wk was implemented and reverted.
The function rendered them correctly — the doctests prove "30sec" -> Just
"30 seconds" — but end to end the query still bucketed at one minute, and
10min at roughly five. Whatever mangles them between here and the SQL was not
found, and shipping an alias that buckets wrong while PASSING validation is
strictly worse than the bug being fixed. `timespanSuffixes` records the
measurement and requires an end-to-end row-count check before any re-add; a
green doctest is what misled the first attempt.

Verified on the running app: 30s/1m/10m/1h give 120/60/6/1 rows over a fixed
hour, and every spelling above is now rejected with an actionable message.
This commit is contained in:
Anthony Alaribe 2026-08-31 18:00:17 +02:00
commit 6a23360e09
3 changed files with 107 additions and 19 deletions