Add benchmarking suite for parallel.sh performance

[inxilpro]

This PR adds a comprehensive benchmarking suite to measure the performance gains of using parallel.sh chains versus sequential script execution.

Summary

A new bench/bench.sh script has been added that benchmarks four realistic build scenarios, comparing execution time when steps run sequentially (traditional set -e script) versus in parallel chains. The benchmarks are integrated into the CI pipeline and documented in the README.

Key Changes

• New bench/bench.sh — A POSIX shell benchmarking script that:

  • Defines four realistic build scenarios (PHP app with frontend, CI checks, failing lint, dominant step)
  • Runs each scenario twice: once sequentially and once with chains
  • Uses sleep commands to simulate build steps without competing for system resources
  • Supports configurable repetitions (REPS), time scaling (SCALE), and shell selection (SHELL_UNDER_TEST)
  • Automatically detects the best available timing mechanism (GNU date, Perl, Python, or fallback to seconds)
  • Reports results as a table and fails only if chains are not faster than sequential execution

• Updated Makefile — Added bench target to run benchmarks (not part of default check target since it takes several minutes)

• Updated .github/workflows/ci.yml — Added bench job that:

  • Runs benchmarks on every push
  • Publishes results to the GitHub Actions run summary
  • Only fails if a scenario was not faster in chains than in order (tolerates noise from hosted runners)

• Updated README.md — Added documentation including:

  • Gantt diagrams showing parallel vs sequential execution timelines
  • Benchmark results table with speedup metrics
  • Explanation of each scenario and what it demonstrates
  • Instructions for running benchmarks locally with different configurations

Notable Implementation Details

• The benchmark uses sleep instead of real work to isolate the parallelization benefit from CPU/IO contention
• Results report the best of multiple runs rather than the mean, since slower runs only reflect machine noise
• The library overhead is measured separately (eight empty chains) to contextualize results
• Timing precision adapts to available tools, with millisecond precision preferred over whole seconds
• Scenarios demonstrate different parallelization benefits: 1.6x–5.8x speedup depending on build shape

https://claude.ai/code/session_01Bn7kapsRo75cCUfU6nfNpS