[claude] benchmarks-website v3: per-group descriptions + partial-coverage commits

Two independent fixes for the v3 server:

Task A - per-group hover descriptions
=====================================

Port v2's `BENCHMARK_DESCRIPTIONS` + `getBenchmarkDescription` strings into
the v3 server. Adds an editorial `description: Option<String>` field on
`Group` and `GroupChartsResponse`, populated from a small hand-maintained
table in `api/descriptions.rs`. TPC-H / TPC-DS descriptions are derived
from the parsed group name so we don't need one entry per (storage, sf)
pair (TPC-H carries the scale-bytes annotation; TPC-DS does not, matching
v2 verbatim).

The landing page renders an info icon (cursor-help, ⓘ) next to every
group title with a description, surfacing the text via a CSS-only
`data-tooltip` pseudo-element (visible on hover *and* focus, with
`role="note"` + `aria-label` for screen readers and keyboards). The
`/group/{slug}` permalink page renders the same icon next to the
chart-meta header. Vector-search groups have no canonical description in
v2; the icon is omitted for those rather than fabricated.

Task B - render commits with partial / missing series data
==========================================================

Symptom: charts had invisible gaps where commits should be. Diagnosis:

  1. `SeriesAccumulator::ensure_commit` only registered a commit *after*
     a series produced a row, so commits with zero rows in the chart's
     fact table were silently dropped from `commits[]`.
  2. The client-side renderer set `spanGaps: true` on every dataset, so
     surviving nulls were drawn over as continuous lines.

Server fix: each `collect_*_chart` now seeds the accumulator from a
`commits`-dim pre-pass scoped to "every commit in the requested
`CommitWindow` whose timestamp is at or after the earliest commit that
has a row in this chart's fact table." Commits with zero fact rows
appear in `commits[]` with `null` for every series; commits older than
the bench's first row stay excluded so we never render pre-history.

Client fix: `spanGaps: false` on every dataset so missing measurements
render as visible gaps. The external tooltip already cleanly skipped
null rows via `.filter(Boolean)` — preserved that behaviour. LTTB still
operates on the union of non-null x-positions; below the cap every
sparse-series commit is kept (so a series with a few non-null values
across many commits still renders connected points).

Tests
=====

`tests/web_ui.rs` adds:

* description rendering on the landing page and `/group/{slug}` (asserts
  the verbatim v2 strings + the SF-derived TPC blurbs)
* `groups_api_carries_description_field` (the wire shape)
* `vector_search_group_has_no_description_icon` (no description ⇒ no icon)
* `chart_includes_commits_with_partial_series_coverage` (regression: B
  with only series Y appears in `commits[]` with `null` for X)
* `chart_includes_commits_with_zero_rows_in_fact_table`
* `chart_excludes_commits_before_first_fact_row`

Existing landing/chart-page snapshots are unchanged in behaviour but pick
up the new info-icon markup; bumping `STATIC_ASSET_VERSION` to
`bench-v3-ui-18` so cached browsers see the new chart-init.js +
style.css.

Local cargo checks were skipped; relying on GitHub Actions to validate.

Signed-off-by: Claude <noreply@anthropic.com>

Author: claude

benchmarks-website/server/src/api/charts.rs

@@ -0,0 +1,214 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright the Vortex contributors
+
+//! Editorial group descriptions, ported from v2.
+//!
+//! These strings are the source of truth for the hover tooltip rendered on
+//! every `<details>` group title on the landing page and on the
+//! `/group/{slug}` permalink. They are deliberately editorial and
+//! hand-maintained — derived from the group *name*, not from the database —
+//! so that adding a new group's blurb is a one-line edit here rather than a
+//! schema or ingest change.
+//!
+//! Source of truth in v2 (kept verbatim where applicable):
+//! - `benchmarks-website/src/utils.js` — `getBenchmarkDescription`
+//! - `benchmarks-website/src/config.js` — `BENCHMARK_DESCRIPTIONS`,
+//!   `QUERY_SUITES.description`
+//!
+//! TPC-H / TPC-DS fan out by storage and scale factor; the description is
+//! synthesised from the parsed name so we don't have to hand-maintain one
+//! entry per `(storage, sf)` pair.
+
+/// Look up a short editorial description for a group display name. Returns
+/// `None` when the group has no canonical description (e.g. vector-search
+/// groups) — callers render the title without a tooltip in that case.
+pub fn group_description(name: &str) -> Option<String> {
+    if let Some(d) = tpc_description(name) {
+        return Some(d);
+    }
+    static_description(name).map(str::to_string)
+}
+
+/// Hard-coded, name-keyed descriptions for the non-fan-out groups. These
+/// match v2 verbatim where v2 had a description; new strings here should
+/// match the wording style v2 set.
+fn static_description(name: &str) -> Option<&'static str> {
+    match name {
+        "Random Access" => Some(
+            "Tests performance of selecting arbitrary row indices from a file on NVMe storage",
+        ),
+        "Compression" => Some(
+            "Measures encoding and decoding throughput (MB/s) for Vortex files and Parquet \
+             files (with zstd page compression)",
+        ),
+        "Compression Size" => Some(
+            "Compares compressed file sizes and compression ratios across different encoding \
+             strategies",
+        ),
+        "Clickbench" => Some(
+            "ClickHouse's analytical benchmark suite testing real-world query patterns on web \
+             analytics data",
+        ),
+        "Statistical and Population Genetics" => Some(
+            "A suite of Statistical and Population genetics queries using the gnomAD dataset",
+        ),
+        "PolarSignals Profiling" => Some(
+            "Profiling data benchmark modeled on PolarSignals/Parca, exercising scan-layer \
+             performance with projection and filter pushdown on deeply nested schemas",
+        ),
+        _ => None,
+    }
+}
+
+/// Derive a description for `TPC-H (NVMe|S3) (SF=N)` and `TPC-DS (NVMe) (SF=N)`
+/// group names. The shape is fixed because [`crate::api::groups::group_name_query`]
+/// emits exactly this format for tpch/tpcds. Returns `None` for any name that
+/// does not start with `TPC-H ` or `TPC-DS `.
+fn tpc_description(name: &str) -> Option<String> {
+    let parts = if let Some(rest) = name.strip_prefix("TPC-H ") {
+        Some(("TPC-H", rest))
+    } else {
+        name.strip_prefix("TPC-DS ").map(|rest| ("TPC-DS", rest))
+    };
+    let (suite, rest) = parts?;
+    let storage = if rest.starts_with("(NVMe)") {
+        "nvme"
+    } else if rest.starts_with("(S3)") {
+        "s3"
+    } else {
+        return None;
+    };
+    let sf = parse_sf(rest)?;
+    Some(format_tpc(suite, storage, &sf))
+}
+
+/// Pull `SF=N` (digits only) out of strings like `(NVMe) (SF=10)`. Returns
+/// `None` if no `SF=` substring or the digits don't parse.
+fn parse_sf(s: &str) -> Option<String> {
+    let after = s.split_once("SF=")?.1;
+    let digits: String = after.chars().take_while(char::is_ascii_digit).collect();
+    if digits.is_empty() {
+        None
+    } else {
+        Some(digits)
+    }
+}
+
+/// Render the v2-compatible TPC blurb. Storage label comes from the parsed
+/// group name; scale-bytes annotation only renders for TPC-H (TPC-DS in v2
+/// did not annotate scale bytes).
+fn format_tpc(suite: &str, storage: &str, sf: &str) -> String {
+    let storage_phrase = match storage {
+        "nvme" => "on local NVMe storage",
+        "s3" => "against S3 storage",
+        _ => "on local NVMe storage",
+    };
+    let bytes = match sf {
+        "1" => Some("1GB"),
+        "10" => Some("10GB"),
+        "100" => Some("100GB"),
+        "1000" => Some("1TB"),
+        _ => None,
+    };
+    match (suite, bytes) {
+        ("TPC-H", Some(b)) => format!(
+            "TPC-H benchmark queries {storage_phrase} at SF={sf} (~{b} of data)",
+        ),
+        ("TPC-H", None) => format!("TPC-H benchmark queries {storage_phrase} at SF={sf}"),
+        ("TPC-DS", _) => format!("TPC-DS benchmark queries {storage_phrase} at SF={sf}"),
+        _ => format!("{suite} benchmark queries {storage_phrase} at SF={sf}"),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn static_descriptions_match_v2() {
+        assert_eq!(
+            group_description("Random Access").as_deref(),
+            Some("Tests performance of selecting arbitrary row indices from a file on NVMe storage"),
+        );
+        assert_eq!(
+            group_description("Compression").as_deref(),
+            Some(
+                "Measures encoding and decoding throughput (MB/s) for Vortex files and Parquet \
+                 files (with zstd page compression)",
+            ),
+        );
+        assert_eq!(
+            group_description("Compression Size").as_deref(),
+            Some(
+                "Compares compressed file sizes and compression ratios across different encoding \
+                 strategies",
+            ),
+        );
+        assert_eq!(
+            group_description("Clickbench").as_deref(),
+            Some(
+                "ClickHouse's analytical benchmark suite testing real-world query patterns on \
+                 web analytics data",
+            ),
+        );
+        assert_eq!(
+            group_description("Statistical and Population Genetics").as_deref(),
+            Some(
+                "A suite of Statistical and Population genetics queries using the gnomAD dataset",
+            ),
+        );
+        assert_eq!(
+            group_description("PolarSignals Profiling").as_deref(),
+            Some(
+                "Profiling data benchmark modeled on PolarSignals/Parca, exercising scan-layer \
+                 performance with projection and filter pushdown on deeply nested schemas",
+            ),
+        );
+    }
+
+    #[test]
+    fn tpch_descriptions_carry_scale_bytes() {
+        assert_eq!(
+            group_description("TPC-H (NVMe) (SF=1)").as_deref(),
+            Some("TPC-H benchmark queries on local NVMe storage at SF=1 (~1GB of data)"),
+        );
+        assert_eq!(
+            group_description("TPC-H (S3) (SF=10)").as_deref(),
+            Some("TPC-H benchmark queries against S3 storage at SF=10 (~10GB of data)"),
+        );
+        assert_eq!(
+            group_description("TPC-H (NVMe) (SF=100)").as_deref(),
+            Some("TPC-H benchmark queries on local NVMe storage at SF=100 (~100GB of data)"),
+        );
+        assert_eq!(
+            group_description("TPC-H (S3) (SF=1000)").as_deref(),
+            Some("TPC-H benchmark queries against S3 storage at SF=1000 (~1TB of data)"),
+        );
+    }
+
+    #[test]
+    fn tpcds_descriptions_omit_scale_bytes() {
+        assert_eq!(
+            group_description("TPC-DS (NVMe) (SF=1)").as_deref(),
+            Some("TPC-DS benchmark queries on local NVMe storage at SF=1"),
+        );
+        assert_eq!(
+            group_description("TPC-DS (NVMe) (SF=10)").as_deref(),
+            Some("TPC-DS benchmark queries on local NVMe storage at SF=10"),
+        );
+    }
+
+    #[test]
+    fn unknown_groups_have_no_description() {
+        assert_eq!(group_description("cohere-large-10m / partitioned"), None);
+        assert_eq!(group_description("Made-up benchmark"), None);
+    }
+
+    #[test]
+    fn malformed_tpc_names_fall_through() {
+        // No `(NVMe)` / `(S3)` prefix → not matched.
+        assert_eq!(group_description("TPC-H something else"), None);
+        // SF= without digits → not matched.
+        assert_eq!(group_description("TPC-H (NVMe) (SF=)"), None);
+    }
+}

benchmarks-website/server/src/api/descriptions.rs

@@ -61,7 +61,9 @@ pub struct GroupsResponse {
 }
 
 /// One group: a display name, a slug for the group permalink, and the chart
-/// links inside it. Optionally carries a v2-compatible rollup summary.
+/// links inside it. Optionally carries a v2-compatible rollup summary and a
+/// short editorial description (rendered as a hover tooltip on the
+/// disclosure title).
 #[derive(Debug, Serialize)]
 pub struct Group {
     /// Human-readable group label rendered in the disclosure header.
@@ -73,6 +75,12 @@ pub struct Group {
     /// Optional v2-compatible rollup computed from the fact tables.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub summary: Option<Summary>,
+    /// Short editorial description ported from v2's `BENCHMARK_DESCRIPTIONS`
+    /// + `getBenchmarkDescription`. Rendered as a hover tooltip on the
+    /// disclosure title; absent when no description exists for this group
+    /// name (e.g. vector-search groups).
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub description: Option<String>,
 }
 
 /// All charts in one group, returned by `GET /api/group/{slug}`.
@@ -83,6 +91,9 @@ pub struct GroupChartsResponse {
     /// Optional v2-compatible rollup computed from the fact tables.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub summary: Option<Summary>,
+    /// Optional editorial description, mirroring [`Group::description`].
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub description: Option<String>,
     /// Every chart inside the group, with full payload inlined.
     pub charts: Vec<NamedChartResponse>,
 }

benchmarks-website/server/src/api/dto.rs

@@ -11,6 +11,7 @@ use anyhow::Context as _;
 use anyhow::Result;
 use duckdb::Connection;
 
+use super::descriptions::group_description;
 use super::dto::ChartLink;
 use super::dto::Group;
 use super::dto::group_sort_key;
@@ -42,6 +43,7 @@ pub(crate) fn collect_groups(conn: &Connection) -> Result<Vec<Group>> {
         let key = GroupKey::from_slug(&group.slug)
             .with_context(|| format!("invalid generated group slug: {}", group.slug))?;
         group.summary = collect_group_summary(conn, &key, &group.charts)?;
+        group.description = group_description(&group.name);
     }
 
     // Apply canonical ordering. `sort_by_key` is stable, so groups whose
@@ -96,6 +98,7 @@ fn collect_query_groups(conn: &Connection) -> Result<Vec<Group>> {
                 slug: group_slug,
                 charts: Vec::new(),
                 summary: None,
+                description: None,
             });
             current = Some(key);
         }
@@ -213,6 +216,7 @@ fn collect_compression_time_group(conn: &Connection) -> Result<Option<Group>> {
             slug: GroupKey::CompressionTimeGroup.to_slug(),
             charts,
             summary: None,
+            description: None,
         }))
     }
 }
@@ -258,6 +262,7 @@ fn collect_compression_size_group(conn: &Connection) -> Result<Option<Group>> {
             slug: GroupKey::CompressionSizeGroup.to_slug(),
             charts,
             summary: None,
+            description: None,
         }))
     }
 }
@@ -287,6 +292,7 @@ fn collect_random_access_group(conn: &Connection) -> Result<Option<Group>> {
             slug: GroupKey::RandomAccessGroup.to_slug(),
             charts,
             summary: None,
+            description: None,
         }))
     }
 }
@@ -324,6 +330,7 @@ fn collect_vector_search_groups(conn: &Connection) -> Result<Vec<Group>> {
                 slug: group_slug,
                 charts: Vec::new(),
                 summary: None,
+                description: None,
             });
             current = Some(key);
         }

benchmarks-website/server/src/api/groups.rs

@@ -9,15 +9,17 @@
 //! [`crate::slug::ChartKey`] / [`crate::slug::GroupKey`].
 //!
 //! Submodules:
-//! - [`mod@dto`]      — every wire-shape struct (`Group`, `ChartResponse`, …).
-//! - [`mod@window`]   — [`CommitWindow`] + [`ChartQuery`].
-//! - [`mod@groups`]   — discovery passes that build the group / chart-link tree.
-//! - [`mod@summary`]  — v2-compatible per-group rollups.
-//! - [`mod@charts`]   — `chart_payload` + the per-fact-table `collect_*_chart`
+//! - [`mod@dto`]          — every wire-shape struct (`Group`, `ChartResponse`, …).
+//! - [`mod@window`]       — [`CommitWindow`] + [`ChartQuery`].
+//! - [`mod@groups`]       — discovery passes that build the group / chart-link tree.
+//! - [`mod@summary`]      — v2-compatible per-group rollups.
+//! - [`mod@charts`]       — `chart_payload` + the per-fact-table `collect_*_chart`
 //!   functions and their shared `SeriesAccumulator`.
-//! - [`mod@filter`]   — chip-universe collection for the global filter bar.
+//! - [`mod@filter`]       — chip-universe collection for the global filter bar.
+//! - [`mod@descriptions`] — editorial blurbs surfaced as hover tooltips.
 
 pub mod charts;
+pub mod descriptions;
 pub mod dto;
 pub mod filter;
 pub mod groups;
@@ -34,6 +36,7 @@ use duckdb::Connection;
 
 pub(crate) use self::charts::chart_payload;
 pub(crate) use self::charts::collect_group_charts;
+pub use self::descriptions::group_description;
 pub use self::dto::ChartLink;
 pub use self::dto::ChartResponse;
 pub use self::dto::CommitPoint;

benchmarks-website/server/src/api/mod.rs

@@ -12,6 +12,7 @@ use maud::PreEscaped;
 use maud::html;
 
 use super::landing::downsample_badge_slot;
+use super::landing::group_description_icon;
 use super::render::escape_json_for_script;
 use super::summary::summary_markup;
 use super::toolbar::per_chart_toolbar;
@@ -55,6 +56,7 @@ pub(super) fn group_body(group: &GroupChartsResponse) -> Markup {
     html! {
         p.chart-meta {
             (chart_count) " chart" @if chart_count != 1 { "s" }
+            (group_description_icon(group.description.as_deref()))
         }
         (summary_markup(group.summary.as_ref()))
         div.chart-grid {