Merge pull request #869 from phpDocumentor/task/document-regex

[TASK] Enforce REGEX Documentation

Author: jaapio

composer.json

@@ -66,6 +66,7 @@
         "rector/rector": "^1.0.1",
         "squizlabs/php_codesniffer": "^3.9",
         "symfony/finder": "^6.4.0 || ^7.0",
+        "symplify/phpstan-rules": "^12.4",
         "vimeo/psalm": "^5.22"
     },
     "suggest": {

composer.lock

@@ -23,6 +23,7 @@
 
 final class SectionauthorDirective extends BaseDirective
 {
+    /** @see https://regex101.com/r/vGy4Uu/1 */
     public const NAME_EMAIL_REGEX = '/^(?P<name>[\w\s]+)(?: <(?P<email>[^>]+)>)?$/';
 
     public function __construct(

packages/guides-restructured-text/src/RestructuredText/Directives/SectionauthorDirective.php

@@ -44,10 +44,11 @@ final class ListRule implements Rule
     /**
      * A regex matching all bullet list markers and a subset of the enumerated list markers.
      *
+     * @see https://regex101.com/r/LBXWFV/1
      * @see https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#bullet-lists
      * @see https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#enumerated-lists
      */
-    private const LIST_MARKER = '/
+    private const LIST_MARKER_REGEX = '/
         ^(
             [-+*\x{2022}\x{2023}\x{2043}]     # match bullet list markers: "*", "+", "-", "•", "‣", or "⁃"        
         )
@@ -120,13 +121,13 @@ private function isListLine(string|null $line): bool
             return false;
         }
 
-        return preg_match(self::LIST_MARKER, $line) > 0;
+        return preg_match(self::LIST_MARKER_REGEX, $line) > 0;
     }
 
     /** @return array{marker: string, indenting: int} */
     public function getItemConfig(string $line): array
     {
-        $isList = preg_match(self::LIST_MARKER, $line, $m) > 0;
+        $isList = preg_match(self::LIST_MARKER_REGEX, $line, $m) > 0;
         if (!$isList) {
             throw new InvalidArgumentException('Line is not a valid item line');
         }
@@ -143,7 +144,7 @@ private function isListItemStart(string|null $line, string|null $listMarker = nu
             return false;
         }
 
-        $isList = preg_match(self::LIST_MARKER, $line, $m) > 0;
+        $isList = preg_match(self::LIST_MARKER_REGEX, $line, $m) > 0;
         if (!$isList) {
             return false;
         }

packages/guides-restructured-text/src/RestructuredText/Parser/Productions/ListRule.php

@@ -30,7 +30,8 @@
 //TODO remove this, as it is copied form phpDocumentor to make things work.
 final class UriFactory
 {
-    public const WINDOWS_URI_FORMAT = '~^(file:\/\/\/)?(?<root>[a-zA-Z][:|\|])~';
+    /** @see https://regex101.com/r/4UN6ZR/1 */
+    public const WINDOWS_URI_FORMAT_REGEX = '~^(file:\/\/\/)?(?<root>[a-zA-Z][:|\|])~';
 
     public static function createUri(string $uriString): UriInterface
     {
@@ -40,7 +41,7 @@ public static function createUri(string $uriString): UriInterface
                 return self::createPharUri($uriString);
             }
 
-            if (preg_match(self::WINDOWS_URI_FORMAT, $uriString)) {
+            if (preg_match(self::WINDOWS_URI_FORMAT_REGEX, $uriString)) {
                 if (str_starts_with($uriString, 'file:///')) {
                     $uriString = substr($uriString, strlen('file:///'));
                 }

packages/guides/src/UriFactory.php

@@ -1,5 +1,8 @@
 includes:
 	- phpstan-baseline.neon
+rules:
+  - Symplify\PHPStanRules\Rules\AnnotateRegexClassConstWithRegexLinkRule
+  - Symplify\PHPStanRules\Rules\RegexSuffixInRegexConstantRule
 parameters:
   level: max