Add perf-diff-stats just recipe (#7480)

## Description

This PR adds the `perf-diff-stats` recipe to the `justfile`. The recipe
calculates a simple statistics of performance improvements and
regressions obtained from the `perf-diff` recipe. The statistics
contains the _count_, _average_, _median_, _max_, and _min_ of
improvements and regressions and can be used to easily communicate
performance differences gained in a PR.

E.g.:

|   | Improvements | Regressions |
| - | -: | -: |
| Count   | 3 | 4 |
| Average | 8.13% | -2.21% |
| Median  | 7.05% | -1.07% |
| Max     | 12.86% | -6.12% |
| Min     | 4.47% | -0.59% |

## Checklist

- [ ] I have linked to any relevant issues.
- [x] I have commented my code, particularly in hard-to-understand
areas.
- [x] I have updated the documentation where relevant (API docs, the
reference, and the Sway book).
- [ ] If my change requires substantial documentation changes, I have
[requested support from the DevRel
team](https://github.com/FuelLabs/devrel-requests/issues/new/choose)
- [ ] I have added tests that prove my fix is effective or that my
feature works.
- [ ] I have added (or requested a maintainer to add) the necessary
`Breaking*` or `New Feature` labels where relevant.
- [x] I have done my best to ensure that my PR adheres to [the Fuel Labs
Code Review
Standards](https://github.com/FuelLabs/rfcs/blob/master/text/code-standards/external-contributors.md).
- [x] I have requested a review from the relevant team or maintainers.

Author: ironcev

justfile

@@ -67,6 +67,12 @@ alias pd := perf-diff
 perf-diff before after format='md':
     ./scripts/perf/perf-diff.sh "{{before}}" "{{after}}" "{{format}}"
 
+alias pds := perf-diff-stats
+# generate performance statistics summary from a `perf-diff` output CSV file
+[group('performance')]
+perf-diff-stats diff_file:
+    cat "{{diff_file}}" | ./scripts/perf/perf-diff-stats.sh
+
 alias pdl := perf-diff-latest
 # generate performance diffs between the latest two CSV files per testing category
 [group('performance')]

scripts/perf/perf-diff-latest.sh

@@ -8,6 +8,7 @@
 output_format="${1:-md}"
 perf_out_dir="./test/perf_out"
 perf_diff_script="./scripts/perf/perf-diff.sh"
+perf_diff_stats_script="./scripts/perf/perf-diff-stats.sh"
 
 categories=("e2e-gas-usages" "e2e-bytecode-sizes" "in-language-gas-usages" "in-language-bytecode-sizes")
 
@@ -70,15 +71,19 @@ process_category() {
     after_ts="${after_base%%-*}"
     now_ts="$(date '+%m%d%H%M%S')"
 
-    outfile="${perf_out_dir}/${now_ts}-diff-${category}-${before_ts}-vs-${after_ts}.${output_format}"
+    diff_outfile="${perf_out_dir}/${now_ts}-diff-${category}-${before_ts}-vs-${after_ts}.${output_format}"
+    stats_outfile="${perf_out_dir}/${now_ts}-stats-${category}-${before_ts}-vs-${after_ts}.md"
 
     echo "Comparing '$category':"
     echo " before: $before_file"
     echo " after:  $after_file"
-    echo "Diff written to: $outfile"
+    echo "Diff written to:  $diff_outfile"
+    echo "Stats written to: $stats_outfile"
     echo
 
-    "$perf_diff_script" "$before_file" "$after_file" "$output_format" | tee "$outfile"
+    "$perf_diff_script" "$before_file" "$after_file" csv | "$perf_diff_stats_script" | tee "$stats_outfile"
+    echo
+    "$perf_diff_script" "$before_file" "$after_file" "$output_format" | tee "$diff_outfile"
     echo
 }
 

scripts/perf/perf-diff-stats.sh

@@ -0,0 +1,98 @@
+#!/bin/bash
+
+# This script calculates a simple statistical summary of performance differences
+# collected from two CSV files, by using `perf-diff.sh` to compute the diffs first.
+#
+# The summary includes count, average, median, max, min of improvements and regressions
+# (percentage changes), and outputs the result as a Markdown table.
+#
+# Usage, e.g.: `cat <output of perf-diff.sh> | perf-diff-stats.sh`.
+
+set -euo pipefail
+
+# Force C locale so both parsing and sorting use '.' as decimal separator.
+export LC_ALL=C
+
+tmp_all="$(mktemp)"; trap 'rm -f "$tmp_all" "$posf" "$negf" "$pos_sorted" "$neg_sorted"' EXIT
+posf="$(mktemp)"
+negf="$(mktemp)"
+pos_sorted="$(mktemp)"
+neg_sorted="$(mktemp)"
+
+# Stash stdin for multiple passes.
+cat > "$tmp_all"
+
+# Extract normalized numeric values from the fourth column.
+awk -F',' -v POS="$posf" -v NEG="$negf" '
+NR==1 { next }  # skip header
+{
+  v = $4
+  v += 0
+  if (v > 0) {
+    print v >> POS
+  } else if (v < 0) {
+    print (-v) >> NEG
+  }
+}
+' "$tmp_all"
+
+# Calculate stats (avg, min, max, count) for a one-column file.
+stats() {
+  local file="$1"
+  if [[ ! -s "$file" ]]; then
+    # no values
+    echo "— — — 0"
+    return
+  fi
+  awk '
+    NR==1 { min=$1; max=$1; sum=$1; c=1; next }
+           { if($1<min) min=$1; if($1>max) max=$1; sum+=$1; c++ }
+    END    { printf("%.2f %.2f %.2f %d\n", sum/c, min, max, c) }
+  ' "$file"
+}
+
+# Calculate median for a one-column file (sorted numerically first).
+median() {
+  local file="$1"
+  if [[ ! -s "$file" ]]; then
+    echo "—"
+    return
+  fi
+  sort -n "$file" > "$file.sorted.$$"
+  awk '
+    { a[++n]=$1 }
+    END {
+      if (n==0) { print "—"; exit }
+      if (n%2==1) {
+        printf("%.2f\n", a[(n+1)/2])
+      } else {
+        printf("%.2f\n", (a[n/2]+a[n/2+1])/2)
+      }
+    }
+  ' "$file.sorted.$$"
+  rm -f "$file.sorted.$$"
+}
+
+# Compute stats.
+read -r p_avg p_min p_max p_cnt <<<"$(stats "$posf")"
+read -r n_avg n_min n_max n_cnt <<<"$(stats "$negf")"
+
+# Compute medians.
+cp "$posf" "$pos_sorted" 2>/dev/null || true
+cp "$negf" "$neg_sorted" 2>/dev/null || true
+p_med="$(median "$pos_sorted")"
+n_med="$(median "$neg_sorted")"
+
+# Print a table cell value or em-dash.
+fmt_cnt() { [[ "$1" == "0" ]] && echo "—" || printf "%d" "$1"; }
+fmt_imp() { [[ "$1" == "—" ]] && echo "—" || printf "%.2f%%" "$1"; }
+fmt_reg() { [[ "$1" == "—" ]] && echo "—" || printf "%.2f%%" "-$1"; }
+
+# Print the summary table.
+echo "|   | Improvements | Regressions |"
+echo "| - | -: | -: |"
+printf "| Count   | %s | %s |\n" "$(fmt_cnt "$p_cnt")" "$(fmt_cnt "$n_cnt")"
+printf "| Average | %s | %s |\n" "$(fmt_imp "$p_avg")" "$(fmt_reg "$n_avg")"
+printf "| Median  | %s | %s |\n" "$(fmt_imp "$p_med")" "$(fmt_reg "$n_med")"
+printf "| Max     | %s | %s |\n" "$(fmt_imp "$p_max")" "$(fmt_reg "$n_max")"
+printf "| Min     | %s | %s |\n" "$(fmt_imp "$p_min")" "$(fmt_reg "$n_min")"

scripts/perf/perf-diff.sh

@@ -45,7 +45,7 @@ if [ "$output_format" == "csv" ]; then
     echo "Test,Before,After,Percentage"
 else
     echo "| Test | Before | After | Percentage |"
-    echo "|------|--------|-------|------------|"
+    echo "| ---- | -----: | ----: | ---------: |"
 fi
 
 paste -d, "$before_file" "$after_file" | while IFS=',' read -r test1 before test2 after; do

test/README.md

@@ -172,6 +172,7 @@ perf-e2e filter=''                    # collect gas usages and bytecode sizes fr
 perf-in-lang filter=''                # collect gas usages from in-language tests [alias: pil]
 perf-all filter=''                    # collect gas usages and bytecode sizes from all tests (E2E and in-language) [alias: pa]
 perf-diff before after format='md'    # generate performance diff between two CSV files [alias: pd]
+perf-diff-stats diff_file             # generate performance statistics summary from a `perf-diff` output CSV file [alias: pds]
 perf-diff-latest format='md'          # generate performance diffs between the latest two CSV files per testing category [alias: pdl]
 perf-snapshot-historical path open='' # collect historic gas usages from a snapshot test that has a `forc test` output [alias: psh]
 perf-list                             # list all performance files (*gas-usages-*.* and *bytecode-sizes-*.*) [alias: pl]