test: Add line numbers to the spec file (#1020)

This helps to navigate directly to the spec. Note however that if no
title was given, no line number will be found. Maybe it is possible to
find it still, but I don't think it is worth my efforts.

Author: theofidry

tests/SpecFramework/SpecParser.php

@@ -29,7 +29,11 @@
 use function array_merge;
 use function is_int;
 use function is_string;
+use function Safe\preg_match;
 use function sprintf;
+use function substr;
+use function substr_count;
+use const PREG_OFFSET_CAPTURE;
 
 /**
  * @internal
@@ -60,6 +64,7 @@ public static function parseSpecFile(
                 $relativePath = basename($sourceDir).'/'.$file->getRelativePathname();
 
                 yield $relativePath.': '.$title => self::parseSpec(
+                    $file->getContents(),
                     $relativePath,
                     $meta,
                     $title,
@@ -91,6 +96,7 @@ private static function checkSpecFileSchema(mixed $specs): void
     }
 
     private static function parseSpec(
+        string $fileContents,
         string $file,
         Meta $meta,
         int|string $title,
@@ -102,6 +108,11 @@ private static function parseSpec(
             is_int($title) ? 'spec #'.$title : $title,
         );
 
+        $lineNumber = self::findLineNumber($fileContents, $title);
+        if (null !== $lineNumber) {
+            $file .= ':'.$lineNumber;
+        }
+
         $specWithConfig = is_string($specWithConfigOrSimpleSpec)
             ? SpecWithConfig::fromSimpleSpec($specWithConfigOrSimpleSpec)
             : $specWithConfigOrSimpleSpec;
@@ -120,6 +131,29 @@ private static function parseSpec(
         );
     }
 
+    /**
+     * @return positive-int|0
+     */
+    private static function findLineNumber(string $fileContents, int|string $title): ?int
+    {
+        if (is_int($title)) {
+            return null;
+        }
+
+        $titleRegex = sprintf(
+            '/ *\'%s\' => (?:SpecWithConfig|<<<\'PHP\')/',
+            $title,
+        );
+
+        if (1 !== preg_match($titleRegex, $fileContents, $matches, PREG_OFFSET_CAPTURE)) {
+            return null;
+        }
+
+        $titlePosition = $matches[0][1];
+
+        return substr_count(substr($fileContents, 0, $titlePosition), "\n") + 1;
+    }
+
     private static function createSymbolsConfiguration(
         SpecWithConfig $specWithConfig,
         Meta $meta,

tests/SpecFrameworkTest/SpecParserTest.php

@@ -86,7 +86,7 @@ public static function specProvider(): iterable
                 'Fixtures/simple-spec-file.php: A spec with a title' => new SpecScenario(
                     null,
                     null,
-                    'Fixtures/simple-spec-file.php',
+                    'Fixtures/simple-spec-file.php:33',
                     '[Example of simple spec file] A spec with a title',
                     $specCode,
                     'Humbug',
@@ -108,7 +108,7 @@ public static function specProvider(): iterable
                 'Fixtures/complete-spec-file.php: Spec with default meta values' => new SpecScenario(
                     72_000,
                     83_000,
-                    'Fixtures/complete-spec-file.php',
+                    'Fixtures/complete-spec-file.php:39',
                     '[Example of simple spec file] Spec with default meta values',
                     $specCode,
                     'Humbug',
@@ -132,7 +132,7 @@ public static function specProvider(): iterable
                 'Fixtures/complete-spec-file.php: Spec with the more verbose form' => new SpecScenario(
                     72_000,
                     83_000,
-                    'Fixtures/complete-spec-file.php',
+                    'Fixtures/complete-spec-file.php:49',
                     '[Example of simple spec file] Spec with the more verbose form',
                     $specCode,
                     'Humbug',
@@ -156,7 +156,7 @@ public static function specProvider(): iterable
                 'Fixtures/complete-spec-file.php: Spec with overridden meta values' => new SpecScenario(
                     73_000,
                     82_000,
-                    'Fixtures/complete-spec-file.php',
+                    'Fixtures/complete-spec-file.php:61',
                     '[Example of simple spec file] Spec with overridden meta values',
                     $specCode,
                     'AnotherPrefix',