Add run-tests.php --context [n] option.

Mentioned in #5965 (comment)

This PR proposes 3 lines of context so the impact can be seen in tests.
Other `diff` programs show around 3 lines of context.
(This helps indicate exactly which position a test should be updated
to add a new expected line at)

Author: TysonAndre

run-tests.php

@@ -102,6 +102,10 @@ function show_usage(): void
                 seconds. The default value is 60 seconds, or 300 seconds when
                 testing for memory leaks.
 
+    --context [n]
+                Sets the number of lines of surrounding context to print for diffs.
+                The default value is 3.
+
     --show-[all|php|skip|clean|exp|diff|out|mem]
                 Show 'all' files, 'php' test file, 'skip' or 'clean' file. You
                 can also use this to show the output 'out', the expected result
@@ -145,6 +149,7 @@ function main(): void
            $user_tests, $valgrind, $sum_results, $shuffle, $file_cache;
     // Parallel testing
     global $workers, $workerID;
+    global $context_line_count;
 
     define('IS_WINDOWS', substr(PHP_OS, 0, 3) == "WIN");
 
@@ -396,6 +401,7 @@ function main(): void
     $file_cache = null;
     $shuffle = false;
     $workers = null;
+    $context_line_count = 3;
 
     $cfgtypes = ['show', 'keep'];
     $cfgfiles = ['skip', 'php', 'clean', 'out', 'diff', 'exp', 'mem'];
@@ -561,6 +567,13 @@ function main(): void
                 case '--set-timeout':
                     $environment['TEST_TIMEOUT'] = $argv[++$i];
                     break;
+                case '--context':
+                    $context_line_count = $argv[++$i] ?? '';
+                    if (!preg_match('/^\d+$/', $context_line_count)) {
+                        error("'$context_line_count' is not a valid number of lines of context, try e.g. --context 3 for 3 lines");
+                    }
+                    $context_line_count = intval($context_line_count, 10);
+                    break;
                 case '--show-all':
                     foreach ($cfgfiles as $file) {
                         $cfg['show'][$file] = true;
@@ -2878,6 +2891,7 @@ function count_array_diff(
 function generate_array_diff(array $ar1, array $ar2, bool $is_reg, array $w): array
 {
     global $colorize;
+    global $context_line_count;
     $idx1 = 0;
     $cnt1 = @count($ar1);
     $idx2 = 0;
@@ -2904,8 +2918,14 @@ function generate_array_diff(array $ar1, array $ar2, bool $is_reg, array $w): ar
         }
         return $output;
     };
+    $format_context_line = function (int $line_number, string $contents): string {
+        // return sprintf("%03d  ", $line_number) . $contents;  // to print the line number in the expected output
+        return str_repeat(' ', max(strlen((string)$line_number), 3) + 2) . $contents;
+    };
+    $mapping = [];
 
     while ($idx1 < $cnt1 && $idx2 < $cnt2) {
+        $mapping[$idx2] = $idx1;
         if (comp_line($ar1[$idx1], $ar2[$idx2], $is_reg)) {
             $idx1++;
             $idx2++;
@@ -2922,43 +2942,72 @@ function generate_array_diff(array $ar1, array $ar2, bool $is_reg, array $w): ar
                 $old1[$idx1] = $format_expected_line($idx1 + 1, $w[$idx1++]);
                 $old2[$idx2] = $format_actual_line($idx2 + 1, $ar2[$idx2++]);
             }
+            $last_printed_context_line = $idx1;
         }
     }
+    $mapping[$idx2] = $idx1;
 
     reset($old1);
     $k1 = key($old1);
     $l1 = -2;
     reset($old2);
     $k2 = key($old2);
     $l2 = -2;
+    $old_k1 = -1;
+    $add_context_lines = function (int $new_k1) use (&$old_k1, &$diff, $w, $context_line_count, $format_context_line) {
+        $end = $new_k1 - 1;
+        $range_end = min($end, $old_k1 + $context_line_count);
+        if ($old_k1 >= 0) {
+            while ($old_k1 < $range_end) {
+                $diff[] = $format_context_line($old_k1 + 1, $w[$old_k1++]);
+            }
+        }
+        if ($end - $context_line_count > $old_k1) {
+            $old_k1 = $end - $context_line_count;
+            $diff[] = '--';
+        }
+        $old_k1 = max($old_k1, 0);
+        while ($old_k1 < $end) {
+            $diff[] = $format_context_line($old_k1 + 1, $w[$old_k1++]);
+        }
+        $old_k1 = $new_k1;
+    };
 
     while ($k1 !== null || $k2 !== null) {
         if ($k1 == $l1 + 1 || $k2 === null) {
+            $add_context_lines($k1);
             $l1 = $k1;
             $diff[] = current($old1);
+            $old_k1 = $k1;
             $k1 = next($old1) ? key($old1) : null;
         } elseif ($k2 == $l2 + 1 || $k1 === null) {
+            $add_context_lines($mapping[$k2]);
             $l2 = $k2;
             $diff[] = current($old2);
             $k2 = next($old2) ? key($old2) : null;
         } elseif ($k1 < $k2) {
+            $add_context_lines($k1);
             $l1 = $k1;
             $diff[] = current($old1);
             $k1 = next($old1) ? key($old1) : null;
         } else {
+            $add_context_lines($mapping[$k2]);
             $l2 = $k2;
             $diff[] = current($old2);
             $k2 = next($old2) ? key($old2) : null;
         }
     }
 
     while ($idx1 < $cnt1) {
+        $add_context_lines($idx1 + 1);
         $diff[] = $format_expected_line($idx1 + 1, $w[$idx1++]);
     }
 
     while ($idx2 < $cnt2) {
+        $add_context_lines($mapping[$idx2] + 1);
         $diff[] = $format_actual_line($idx2 + 1, $ar2[$idx2++]);
     }
+    $add_context_lines(min($old_k1 + $context_line_count + 1, $cnt1 + 1));
 
     return $diff;
 }