feat: add trend visualization with sparklines to perf report (#9939)

## Summary

Add historical trend visualization (ASCII sparklines + directional
arrows) to the performance PR report, showing how each metric has moved
over recent commits on main.

## Changes

- **What**: New `sparkline()`, `trendDirection()`, `trendArrow()`
functions in `perf-stats.ts`. New collapsible "Trend" section in the
perf report showing per-metric sparklines, direction indicators, and
latest values. CI workflow updated to download historical data from the
`perf-data` orphan branch and switched to `setup-frontend` action with
`pnpm exec tsx`.

## Review Focus

- The trend section only renders when ≥3 historical data points exist
(gracefully absent otherwise)
- `trendDirection()` uses a split-half mean comparison with ±10%
threshold — review whether this sensitivity is appropriate
- The `git archive` step in `pr-perf-report.yaml` is idempotent and
fails silently if no perf-history data exists yet on the perf-data
branch

┆Issue is synchronized with this [Notion
page](https://www.notion.so/PR-9939-feat-add-trend-visualization-with-sparklines-to-perf-report-3246d73d36508125a6fcc39612f850fe)
by [Unito](https://www.unito.io)

---------

Co-authored-by: GitHub Action <action@github.com>

Author: christian-byrne

.github/workflows/pr-report.yaml

@@ -173,6 +173,19 @@ jobs:
           path: temp/perf-baseline/
           if_no_artifact_found: warn
 
+      - name: Download perf history from perf-data branch
+        if: steps.pr-meta.outputs.skip != 'true' && steps.find-perf.outputs.status == 'ready'
+        continue-on-error: true
+        run: |
+          if git ls-remote --exit-code origin perf-data >/dev/null 2>&1; then
+            git fetch origin perf-data --depth=1
+            mkdir -p temp/perf-history
+            for file in $(git ls-tree --name-only origin/perf-data baselines/ 2>/dev/null | sort -r | head -10); do
+              git show "origin/perf-data:${file}" > "temp/perf-history/$(basename "$file")" 2>/dev/null || true
+            done
+            echo "Loaded $(ls temp/perf-history/*.json 2>/dev/null | wc -l) historical baselines"
+          fi
+
       - name: Generate unified report
         if: steps.pr-meta.outputs.skip != 'true'
         run: >

scripts/perf-report.ts

@@ -7,6 +7,9 @@ import {
   computeStats,
   formatSignificance,
   isNoteworthy,
+  sparkline,
+  trendArrow,
+  trendDirection,
   zScore
 } from './perf-stats'
 
@@ -73,8 +76,11 @@ function groupByName(
 function loadHistoricalReports(): PerfReport[] {
   if (!existsSync(HISTORY_DIR)) return []
   const reports: PerfReport[] = []
-  for (const dir of readdirSync(HISTORY_DIR)) {
-    const filePath = join(HISTORY_DIR, dir, 'perf-metrics.json')
+  for (const entry of readdirSync(HISTORY_DIR)) {
+    const entryPath = join(HISTORY_DIR, entry)
+    const filePath = entry.endsWith('.json')
+      ? entryPath
+      : join(entryPath, 'perf-metrics.json')
     if (!existsSync(filePath)) continue
     try {
       reports.push(JSON.parse(readFileSync(filePath, 'utf-8')) as PerfReport)
@@ -102,6 +108,27 @@ function getHistoricalStats(
   return computeStats(values)
 }
 
+function getHistoricalTimeSeries(
+  reports: PerfReport[],
+  testName: string,
+  metric: MetricKey
+): number[] {
+  const sorted = [...reports].sort(
+    (a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime()
+  )
+  const values: number[] = []
+  for (const r of sorted) {
+    const group = groupByName(r.measurements)
+    const samples = group.get(testName)
+    if (samples) {
+      values.push(
+        samples.reduce((sum, s) => sum + s[metric], 0) / samples.length
+      )
+    }
+  }
+  return values
+}
+
 function computeCV(stats: MetricStats): number {
   return stats.mean > 0 ? (stats.stddev / stats.mean) * 100 : 0
 }
@@ -233,6 +260,34 @@ function renderFullReport(
   }
   lines.push('', '</details>')
 
+  const trendRows: string[] = []
+  for (const [testName] of prGroups) {
+    for (const { key, label, unit } of REPORTED_METRICS) {
+      const series = getHistoricalTimeSeries(historical, testName, key)
+      if (series.length < 3) continue
+      const dir = trendDirection(series)
+      const arrow = trendArrow(dir)
+      const spark = sparkline(series)
+      const last = series[series.length - 1]
+      trendRows.push(
+        `| ${testName}: ${label} | ${spark} | ${arrow} | ${formatValue(last, unit)} |`
+      )
+    }
+  }
+
+  if (trendRows.length > 0) {
+    lines.push(
+      '',
+      `<details><summary>Trend (last ${historical.length} commits on main)</summary>`,
+      '',
+      '| Metric | Trend | Dir | Latest |',
+      '|--------|-------|-----|--------|',
+      ...trendRows,
+      '',
+      '</details>'
+    )
+  }
+
   return lines
 }
 

scripts/perf-stats.test.ts

@@ -5,6 +5,9 @@ import {
   computeStats,
   formatSignificance,
   isNoteworthy,
+  sparkline,
+  trendArrow,
+  trendDirection,
   zScore
 } from './perf-stats'
 
@@ -131,3 +134,68 @@ describe('isNoteworthy', () => {
     expect(isNoteworthy('noisy')).toBe(false)
   })
 })
+
+describe('sparkline', () => {
+  it('returns empty string for no values', () => {
+    expect(sparkline([])).toBe('')
+  })
+
+  it('returns mid-height for single value', () => {
+    expect(sparkline([50])).toBe('▄')
+  })
+
+  it('renders ascending values low to high', () => {
+    const result = sparkline([0, 25, 50, 75, 100])
+    expect(result).toBe('▁▃▅▆█')
+  })
+
+  it('renders identical values as flat line', () => {
+    const result = sparkline([10, 10, 10])
+    expect(result).toBe('▄▄▄')
+  })
+
+  it('renders descending values high to low', () => {
+    const result = sparkline([100, 50, 0])
+    expect(result).toBe('█▅▁')
+  })
+})
+
+describe('trendDirection', () => {
+  it('returns stable for fewer than 3 values', () => {
+    expect(trendDirection([])).toBe('stable')
+    expect(trendDirection([1])).toBe('stable')
+    expect(trendDirection([1, 2])).toBe('stable')
+  })
+
+  it('detects rising trend', () => {
+    expect(trendDirection([10, 10, 10, 20, 20, 20])).toBe('rising')
+  })
+
+  it('detects falling trend', () => {
+    expect(trendDirection([20, 20, 20, 10, 10, 10])).toBe('falling')
+  })
+
+  it('returns stable for flat data', () => {
+    expect(trendDirection([100, 100, 100, 100])).toBe('stable')
+  })
+
+  it('returns stable for small fluctuations within 10%', () => {
+    expect(trendDirection([100, 100, 100, 105, 105, 105])).toBe('stable')
+  })
+
+  it('detects rising when baseline is zero but current is non-zero', () => {
+    expect(trendDirection([0, 0, 0, 5, 5, 5])).toBe('rising')
+  })
+
+  it('returns stable when both halves are zero', () => {
+    expect(trendDirection([0, 0, 0, 0, 0, 0])).toBe('stable')
+  })
+})
+
+describe('trendArrow', () => {
+  it('returns correct emoji for each direction', () => {
+    expect(trendArrow('rising')).toBe('📈')
+    expect(trendArrow('falling')).toBe('📉')
+    expect(trendArrow('stable')).toBe('➡️')
+  })
+})

scripts/perf-stats.ts

@@ -61,3 +61,53 @@ export function formatSignificance(
 export function isNoteworthy(sig: Significance): boolean {
   return sig === 'regression'
 }
+
+const SPARK_CHARS = '▁▂▃▄▅▆▇█'
+
+export function sparkline(values: number[]): string {
+  if (values.length === 0) return ''
+  if (values.length === 1) return SPARK_CHARS[3]
+
+  const min = Math.min(...values)
+  const max = Math.max(...values)
+  const range = max - min
+
+  return values
+    .map((v) => {
+      if (range === 0) return SPARK_CHARS[3]
+      const idx = Math.round(((v - min) / range) * (SPARK_CHARS.length - 1))
+      return SPARK_CHARS[idx]
+    })
+    .join('')
+}
+
+export type TrendDirection = 'rising' | 'falling' | 'stable'
+
+export function trendDirection(values: number[]): TrendDirection {
+  if (values.length < 3) return 'stable'
+
+  const half = Math.floor(values.length / 2)
+  const firstHalf = values.slice(0, half)
+  const secondHalf = values.slice(-half)
+
+  const firstMean = firstHalf.reduce((a, b) => a + b, 0) / firstHalf.length
+  const secondMean = secondHalf.reduce((a, b) => a + b, 0) / secondHalf.length
+
+  if (firstMean === 0) return secondMean > 0 ? 'rising' : 'stable'
+  const changePct = ((secondMean - firstMean) / firstMean) * 100
+
+  if (changePct > 10) return 'rising'
+  if (changePct < -10) return 'falling'
+  return 'stable'
+}
+
+export function trendArrow(dir: TrendDirection): string {
+  switch (dir) {
+    case 'rising':
+      return '📈'
+    case 'falling':
+      return '📉'
+    case 'stable':
+      return '➡️'
+  }
+}