docs: fix benchmark ratio bars

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: LessUp

.github/workflows/ci-docs.yml

@@ -30,6 +30,10 @@ jobs:
         working-directory: docs
         run: npm ci
 
+      - name: Run docs tests
+        working-directory: docs
+        run: npm test
+
       - name: Build docs
         working-directory: docs
         run: npm run build

docs/.vitepress/theme/components/BenchmarkChart.vue

@@ -1,6 +1,7 @@
 <script setup lang="ts">
 import { ref, computed, watchEffect } from 'vue'
 import benchmarkData from '../../data/benchmarks.json'
+import { getBarHeight as getMetricBarHeight, isBestCompressionRatio } from './benchmarkChartMetrics.js'
 
 interface BenchmarkResult {
   algorithm: string
@@ -84,20 +85,23 @@ const maxValue = computed(() => {
   return Math.max(...filteredResults.value.map(r => r[selectedMetric.value]))
 })
 
+const compressionRatios = computed(() => filteredResults.value.map(r => r.compressionRatio))
+
 const formatMetricName = (metric: string): string => {
   const names: Record<string, string> = {
     encodeSpeed: 'Encode Speed (MiB/s)',
     decodeSpeed: 'Decode Speed (MiB/s)',
-    compressionRatio: 'Compression Ratio (lower = better)'
+    compressionRatio: 'Size Saved Relative to Input'
   }
   return names[metric] || metric
 }
 
 const getBarHeight = (value: number): number => {
-  const max = selectedMetric.value === 'compressionRatio'
-    ? Math.max(maxValue.value, 0.001)
-    : Math.max(maxValue.value, 300)
-  return Math.max((value / max) * 100, 5)
+  return getMetricBarHeight(selectedMetric.value, value, maxValue.value)
+}
+
+const isCompressionRatioLeader = (value: number): boolean => {
+  return isBestCompressionRatio(selectedMetric.value, value, compressionRatios.value)
 }
 
 const formatMetricValue = (value: number): string => {
@@ -147,14 +151,15 @@ const formatMetricValue = (value: number): string => {
             v-for="result in groupedByAlgorithm[algo]" 
             :key="result.language"
             class="bar-wrapper"
-            :title="`${languageNames[result.language]}: ${formatMetricValue(result[selectedMetric])}`"
-          >
-            <div 
-              class="bar" 
-              :style="{ 
-                height: `${getBarHeight(result[selectedMetric])}%`,
-                backgroundColor: languageColors[result.language]
-              }"
+              :title="`${languageNames[result.language]}: ${formatMetricValue(result[selectedMetric])}`"
+            >
+              <div
+                class="bar"
+                :class="{ 'bar-best': isCompressionRatioLeader(result.compressionRatio) }"
+                :style="{
+                  height: `${getBarHeight(result[selectedMetric])}%`,
+                  backgroundColor: languageColors[result.language]
+                }"
             >
               <span class="bar-value">{{ formatMetricValue(result[selectedMetric]) }}</span>
             </div>
@@ -163,6 +168,9 @@ const formatMetricValue = (value: number): string => {
       </div>
     </div>
 
+    <div v-if="selectedMetric === 'compressionRatio'" class="metric-note">
+      Bars show size saved relative to input; labels show the actual output/input ratio, and the best ratio is highlighted.
+    </div>
     <div class="metric-label">{{ formatMetricName(selectedMetric) }}</div>
   </div>
 </template>
@@ -302,6 +310,11 @@ const formatMetricValue = (value: number): string => {
   opacity: 1;
 }
 
+.bar-best {
+  box-shadow: 0 0 0 2px var(--vp-c-brand-1);
+  opacity: 1;
+}
+
 .bar-value {
   position: absolute;
   top: -20px;
@@ -313,6 +326,13 @@ const formatMetricValue = (value: number): string => {
   white-space: nowrap;
 }
 
+.metric-note {
+  text-align: center;
+  font-size: 0.8125rem;
+  color: var(--vp-c-text-2);
+  margin-top: 1.25rem;
+}
+
 .metric-label {
   text-align: center;
   font-size: 0.875rem;

docs/.vitepress/theme/components/benchmarkChartMetrics.js

@@ -0,0 +1,28 @@
+const MIN_BAR_HEIGHT = 5
+const MIN_COMPRESSION_BAR_HEIGHT = 2
+const MIN_SPEED_SCALE = 300
+const COMPRESSION_RATIO_TOLERANCE = 1e-9
+
+export function getBarHeight(metric, value, maxValue) {
+  if (metric === 'compressionRatio') {
+    const safeRatio = Math.max(value, 0)
+    const sizeSaved = 1 - Math.min(safeRatio, 1)
+    if (sizeSaved <= 0) {
+      return MIN_COMPRESSION_BAR_HEIGHT
+    }
+
+    return MIN_COMPRESSION_BAR_HEIGHT + (sizeSaved * (100 - MIN_COMPRESSION_BAR_HEIGHT))
+  }
+
+  const max = Math.max(maxValue, MIN_SPEED_SCALE)
+  return Math.max((value / max) * 100, MIN_BAR_HEIGHT)
+}
+
+export function isBestCompressionRatio(metric, value, values) {
+  if (metric !== 'compressionRatio' || values.length === 0) {
+    return false
+  }
+
+  const bestRatio = Math.min(...values)
+  return Math.abs(value - bestRatio) <= COMPRESSION_RATIO_TOLERANCE
+}

docs/package.json

@@ -5,6 +5,7 @@
   "scripts": {
     "sync": "node scripts/sync-changelog.mjs",
     "dev": "npm run sync && vitepress dev",
+    "test": "node --test tests/*.test.mjs",
     "build": "npm run sync && vitepress build",
     "preview": "vitepress preview"
   },

docs/tests/benchmark-chart-semantics.test.mjs

@@ -0,0 +1,89 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { readFile } from 'node:fs/promises'
+import { getBarHeight, isBestCompressionRatio } from '../.vitepress/theme/components/benchmarkChartMetrics.js'
+
+const loadCompressionRatios = async dataset => {
+  const source = await readFile(new URL('../.vitepress/data/benchmarks.json', import.meta.url), 'utf8')
+  const { results } = JSON.parse(source)
+  return results
+    .filter(result => result.dataset === dataset)
+    .map(result => result.compressionRatio)
+}
+
+test('compression ratio bars reward smaller output/input ratios', async () => {
+  const values = await loadCompressionRatios('textlike_10MiB')
+  const bestRatio = Math.min(...values)
+  const worstRatio = Math.max(...values)
+
+  assert.ok(
+    getBarHeight('compressionRatio', bestRatio, worstRatio) >
+      getBarHeight('compressionRatio', worstRatio, worstRatio),
+    'smaller compression ratios should render taller bars'
+  )
+})
+
+test('compression ratio bars keep near-identical ratios visually close', () => {
+  const better = getBarHeight('compressionRatio', 0.743, 0.746)
+  const worse = getBarHeight('compressionRatio', 0.746, 0.746)
+
+  assert.ok(better > worse, 'smaller compression ratios should still render taller bars')
+  assert.ok(
+    better - worse < 1,
+    'near-identical compression ratios should not be stretched across the full chart'
+  )
+})
+
+test('compression ratio bars bottom out once compression stops helping', () => {
+  assert.ok(
+    getBarHeight('compressionRatio', 0.95, 1) > getBarHeight('compressionRatio', 1, 1),
+    'small-but-positive savings should still render above the no-compression baseline'
+  )
+  assert.equal(
+    getBarHeight('compressionRatio', 1.01, 2),
+    2,
+    'expanding results should stay at the floor because they save no space'
+  )
+  assert.equal(
+    getBarHeight('compressionRatio', 2, 2),
+    2,
+    'worse expansion should also stay at the floor'
+  )
+})
+
+test('best compression ratio stays highlighted even when bars are close', async () => {
+  const values = await loadCompressionRatios('textlike_10MiB')
+  const bestRatio = Math.min(...values)
+  const worstRatio = Math.max(...values)
+
+  assert.equal(
+    isBestCompressionRatio('compressionRatio', bestRatio, values),
+    true,
+    'the lowest compression ratio should be highlighted'
+  )
+  assert.equal(
+    isBestCompressionRatio('compressionRatio', worstRatio, values),
+    false,
+    'higher compression ratios should not be highlighted'
+  )
+})
+
+test('best compression ratio still gets highlighted among expanding results', () => {
+  assert.equal(
+    isBestCompressionRatio('compressionRatio', 1.01, [1.01, 2]),
+    true,
+    'the smaller expansion ratio should still be highlighted as the better result'
+  )
+  assert.equal(
+    isBestCompressionRatio('compressionRatio', 2, [1.01, 2]),
+    false,
+    'the larger expansion ratio should not be highlighted'
+  )
+})
+
+test('encode speed bars still reward faster results', () => {
+  assert.ok(
+    getBarHeight('encodeSpeed', 277, 277) > getBarHeight('encodeSpeed', 58.8, 277),
+    'higher encode speeds should still render taller bars'
+  )
+})