feat: Enhance benchmark infrastructure with profiling and parallelism matrix

Changes to benchmark-docker.sh:
- Use GUIDES_PROFILING=1 for accurate memory metrics via memory_get_peak_usage()
- Add 4th parameter for parallel mode: sequential, auto, or number (e.g., 16)
- Include parallel_mode in result filenames and JSON output
- Memory now sourced from PHP profiling instead of /usr/bin/time

New benchmark-main.sh:
- Dedicated script for benchmarking main branch with official container
- Uses ghcr.io/typo3-documentation/render-guides:latest
- Memory via /usr/bin/time (PHP profiling not available in official image)

New run-full-matrix.sh:
- Runs complete benchmark matrix:
  * main branch (official container)
  * feature branch: sequential (--parallel-workers=-1)
  * feature branch: auto (--parallel-workers=0)
  * feature branch: 16 workers (--parallel-workers=16)
- Supports small, large, changelog, or 'all' doc types

Usage examples:
  ./benchmark/benchmark-docker.sh cold 3 large sequential
  ./benchmark/benchmark-docker.sh cold 3 large auto
  ./benchmark/benchmark-docker.sh cold 3 large 16
  ./benchmark/run-full-matrix.sh large

Author: CybotTM

benchmark/benchmark-docker.sh

@@ -2,10 +2,11 @@
 #
 # Run benchmarks inside Docker container for reproducibility
 #
-# Usage: ./benchmark/benchmark-docker.sh [scenario] [runs] [docs-type]
+# Usage: ./benchmark/benchmark-docker.sh [scenario] [runs] [docs-type] [parallel-mode]
 #
 # Scenarios: cold, warm, partial, all
-# Docs: small (Documentation-rendertest), large (TYPO3CMS-Reference-CoreApi)
+# Docs: small (Documentation-rendertest), large (TYPO3CMS-Reference-CoreApi), changelog
+# Parallel modes: auto (default), sequential, 16, or any number
 #
 
 set -euo pipefail
@@ -17,6 +18,24 @@ RESULTS_DIR="$SCRIPT_DIR/results"
 SCENARIO="${1:-cold}"
 RUNS="${2:-3}"
 DOCS_TYPE="${3:-small}"
+PARALLEL_MODE="${4:-auto}"
+
+# Convert parallel mode to --parallel-workers value
+case "$PARALLEL_MODE" in
+    auto)
+        PARALLEL_WORKERS="0"
+        PARALLEL_LABEL="auto"
+        ;;
+    sequential|seq|none)
+        PARALLEL_WORKERS="-1"
+        PARALLEL_LABEL="sequential"
+        ;;
+    *)
+        # Assume it's a number
+        PARALLEL_WORKERS="$PARALLEL_MODE"
+        PARALLEL_LABEL="p${PARALLEL_MODE}"
+        ;;
+esac
 
 BRANCH=$(cd "$PROJECT_DIR" && git rev-parse --abbrev-ref HEAD 2>/dev/null | sed 's/\//_/g' || echo "unknown")
 COMMIT=$(cd "$PROJECT_DIR" && git rev-parse --short HEAD 2>/dev/null || echo "unknown")
@@ -82,21 +101,22 @@ clean_caches() {
     # Clean shared cache directory (Twig cache, inventory cache, etc.)
     rm -rf /tmp/typo3-guides-benchmark-cache/* 2>/dev/null || true
     # Use docker to clean root-owned files from previous runs
-    docker run --rm -v /tmp:/tmp alpine sh -c "rm -rf /tmp/typo3-guides-* /tmp/benchmark-output /tmp/benchmark-log*" 2>/dev/null || true
+    docker run --rm -v /tmp:/tmp alpine sh -c "rm -rf /tmp/typo3-guides-* /tmp/benchmark-output /tmp/benchmark-log* /tmp/benchmark-profiling*" 2>/dev/null || true
     # Remove incremental rendering cache from docs directory (if stored there)
     rm -f "$PROJECT_DIR/$DOCS_INPUT/_build_meta.json" 2>/dev/null || true
     # Remove .cache directory used by incremental rendering
     rm -rf "$PROJECT_DIR/.cache" 2>/dev/null || true
 }
 
-# Run single benchmark with CPU and memory metrics via /usr/bin/time inside container
+# Run single benchmark with profiling for accurate memory metrics
 # Pass "fresh" as second arg to force clean output directory
 run_benchmark_simple() {
     local run_num=$1
     local fresh_output="${2:-no}"
     local output_dir="/tmp/benchmark-output"
     local log_file="/tmp/benchmark-log-$run_num.txt"
     local time_file="/tmp/benchmark-time-$run_num.txt"
+    local profiling_file="/tmp/benchmark-profiling-$run_num.json"
 
     # Only clean output dir if fresh is requested (cold scenario)
     if [ "$fresh_output" = "fresh" ]; then
@@ -110,37 +130,52 @@ run_benchmark_simple() {
         config_arg="--config=$DOCS_INPUT"
     fi
 
-    # Run container with /usr/bin/time -v INSIDE the container for accurate metrics
-    # Note: project mounted read-write so incremental rendering cache can be written
     # Mount shared /tmp for Twig cache persistence between warm runs
     local shared_tmp="/tmp/typo3-guides-benchmark-cache"
     mkdir -p "$shared_tmp"
 
-    # Run time inside container, output time stats to stderr which we capture
+    # Run with:
+    # - /usr/bin/time -v for wall time and CPU%
+    # - GUIDES_PROFILING=1 for PHP-reported memory via memory_get_peak_usage()
+    # - GUIDES_PROFILING_OUTPUT for JSON output
     docker run --rm \
         --user "$(id -u):$(id -g)" \
         -v "$PROJECT_DIR:/project" \
         -v "$output_dir:/output" \
         -v "$shared_tmp:/tmp" \
+        -e GUIDES_PROFILING=1 \
+        -e GUIDES_PROFILING_OUTPUT="/tmp/profiling.json" \
         --entrypoint /usr/bin/time \
         "$IMAGE_TAG" \
-        -v php /opt/guides/vendor/bin/guides --no-progress $config_arg --output=/output "$DOCS_INPUT" \
+        -v php /opt/guides/vendor/bin/guides --no-progress $config_arg --output=/output --parallel-workers="$PARALLEL_WORKERS" "$DOCS_INPUT" \
         > "$log_file" 2> "$time_file"
     local docker_exit=$?
 
-    # Parse /usr/bin/time output for metrics (GNU time format)
-    local elapsed user_time sys_time peak_memory_kb cpu_percent
+    # Copy profiling output from container's /tmp (which is shared_tmp)
+    cp "$shared_tmp/profiling.json" "$profiling_file" 2>/dev/null || true
+
+    # Parse /usr/bin/time output for wall time and CPU%
+    local elapsed user_time sys_time cpu_percent
     elapsed=$(grep "Elapsed (wall clock)" "$time_file" | sed 's/.*: //' | awk -F: '{if (NF==3) print $1*3600+$2*60+$3; else if (NF==2) print $1*60+$2; else print $1}')
     user_time=$(grep "User time" "$time_file" | awk '{print $NF}')
     sys_time=$(grep "System time" "$time_file" | awk '{print $NF}')
-    peak_memory_kb=$(grep "Maximum resident set size" "$time_file" | awk '{print $NF}')
     cpu_percent=$(grep "Percent of CPU" "$time_file" | sed 's/.*: //' | tr -d '%')
 
-    # Convert to MB and calculate totals
-    local peak_memory_mb cpu_time
-    peak_memory_mb=$(echo "scale=1; ${peak_memory_kb:-0} / 1024" | bc)
+    local cpu_time
     cpu_time=$(echo "scale=2; ${user_time:-0} + ${sys_time:-0}" | bc)
 
+    # Get memory from PHP profiling (accurate memory_get_peak_usage)
+    local peak_memory_mb
+    if [ -f "$profiling_file" ]; then
+        peak_memory_mb=$(jq -r '.memory_mb.peak // 0' "$profiling_file" 2>/dev/null || echo "0")
+    else
+        # Fallback to /usr/bin/time if profiling not available
+        local peak_memory_kb
+        peak_memory_kb=$(grep "Maximum resident set size" "$time_file" | awk '{print $NF}')
+        peak_memory_mb=$(echo "scale=1; ${peak_memory_kb:-0} / 1024" | bc)
+        log_warn "Profiling output not found, using /usr/bin/time for memory (less accurate)"
+    fi
+
     # Count output files
     local file_count
     file_count=$(find "$output_dir" -name "*.html" 2>/dev/null | wc -l | tr -d ' ')
@@ -159,7 +194,7 @@ run_scenario() {
     local memories=()
     local files=0
 
-    log_info "Running scenario: $scenario ($RUNS runs, docs: $DOCS_TYPE)"
+    log_info "Running scenario: $scenario ($RUNS runs, docs: $DOCS_TYPE, parallel: $PARALLEL_LABEL)"
 
     case "$scenario" in
         cold)
@@ -254,16 +289,18 @@ run_scenario() {
     local cpu_pct_avg=$(echo "scale=0; $cpu_pct_sum / ${#cpu_percents[@]}" | bc)
     local mem_avg=$(echo "scale=1; $mem_sum / ${#memories[@]}" | bc)
 
-    # Save to JSON
+    # Save to JSON - include parallel mode in filename
     mkdir -p "$RESULTS_DIR"
-    local result_file="$RESULTS_DIR/${BRANCH}_${scenario}_${DOCS_TYPE}_${TIMESTAMP}.json"
+    local result_file="$RESULTS_DIR/${BRANCH}_${PARALLEL_LABEL}_${scenario}_${DOCS_TYPE}_${TIMESTAMP}.json"
 
     cat > "$result_file" << EOF
 {
     "branch": "$BRANCH",
     "commit": "$COMMIT",
     "scenario": "$scenario",
     "docs_type": "$DOCS_TYPE",
+    "parallel_mode": "$PARALLEL_LABEL",
+    "parallel_workers": "$PARALLEL_WORKERS",
     "timestamp": "$TIMESTAMP",
     "runs": $RUNS,
     "metrics": {
@@ -281,7 +318,8 @@ run_scenario() {
         "memory": {
             "avg_mb": $mem_avg,
             "min_mb": $mem_min,
-            "max_mb": $mem_max
+            "max_mb": $mem_max,
+            "source": "php_profiling"
         },
         "files_rendered": $files
     },
@@ -296,10 +334,10 @@ EOF
 
     # Print summary
     echo ""
-    echo "=== $scenario Summary ==="
+    echo "=== $scenario Summary (parallel: $PARALLEL_LABEL) ==="
     echo "  Wall Time:  ${time_avg}s (min: ${time_min}s, max: ${time_max}s)"
     echo "  CPU Time:   ${cpu_avg}s (~${cpu_pct_avg}% utilization)"
-    echo "  Memory:     ${mem_avg}MB peak"
+    echo "  Memory:     ${mem_avg}MB peak (from PHP profiling)"
     echo "  Files:      $files"
     echo ""
 }
@@ -309,6 +347,7 @@ echo "============================================"
 echo "Benchmark: $SCENARIO"
 echo "Branch:    $BRANCH ($COMMIT)"
 echo "Docs:      $DOCS_TYPE ($DOCS_INPUT)"
+echo "Parallel:  $PARALLEL_LABEL (--parallel-workers=$PARALLEL_WORKERS)"
 echo "Runs:      $RUNS"
 echo "============================================"
 echo ""