feat: add trend visualization with sparklines to perf report

- Add sparkline(), trendDirection(), trendArrow() to perf-stats.ts
- Add collapsible 'Trend' section to perf-report.ts showing ASCII
  sparklines and directional arrows for each metric over last N
  commits on main
- Add historical data download step to pr-perf-report.yaml from
  perf-data orphan branch
- Switch pr-perf-report.yaml to setup-frontend action and pnpm exec
- Add tests for all new functions (sparkline, trendDirection, trendArrow)

Author: christian-byrne

.github/workflows/pr-perf-report.yaml

@@ -23,10 +23,8 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v6
 
-      - name: Setup Node
-        uses: actions/setup-node@v6
-        with:
-          node-version-file: '.nvmrc'
+      - name: Setup frontend
+        uses: ./.github/actions/setup-frontend
 
       - name: Download PR metadata
         uses: dawidd6/action-download-artifact@0bd50d53a6d7fb5cb921e607957e9cc12b4ce392 # v12
@@ -113,30 +111,19 @@ jobs:
           path: temp/perf-baseline/
           if_no_artifact_found: warn
 
-      - name: Load historical baselines from perf-data branch
+      - name: Download perf history from perf-data branch
         if: steps.sha-check.outputs.stale != 'true'
         continue-on-error: true
         run: |
-          mkdir -p temp/perf-history
-
-          git fetch origin perf-data 2>/dev/null || {
-            echo "perf-data branch not found, skipping historical data"
-            exit 0
-          }
-
-          INDEX=0
-          for file in $(git ls-tree --name-only origin/perf-data baselines/ 2>/dev/null | sort -r | head -5); do
-            DIR="temp/perf-history/$INDEX"
-            mkdir -p "$DIR"
-            git show "origin/perf-data:${file}" > "$DIR/perf-metrics.json" 2>/dev/null || true
-            INDEX=$((INDEX + 1))
-          done
-
-          echo "Loaded $INDEX historical baselines"
+          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
+            git archive origin/perf-data -- perf-history/ 2>/dev/null | tar -x -C temp/ 2>/dev/null || true
+          fi
 
       - name: Generate perf report
         if: steps.sha-check.outputs.stale != 'true'
-        run: npx --yes tsx scripts/perf-report.ts > perf-report.md
+        run: pnpm exec tsx scripts/perf-report.ts > perf-report.md
 
       - name: Post PR comment
         if: steps.sha-check.outputs.stale != 'true'

scripts/perf-report.ts

@@ -7,6 +7,9 @@ import {
   computeStats,
   formatSignificance,
   isNoteworthy,
+  sparkline,
+  trendArrow,
+  trendDirection,
   zScore
 } from './perf-stats'
 
@@ -96,6 +99,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
 }
@@ -227,6 +251,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,60 @@ 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')
+  })
+})
+
+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,55 @@ 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 '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 '➡️'
+  }
+}