perf: optimize RST parsing with instance and pattern caching

Add caching optimizations for hot paths in RST parsing:

- InlineParser: reuse single InlineLexer instance instead of creating
  new one per parse call (lexer state fully reset via setInput())
- InlineLexer: cache expensive hyperlink pattern built from
  SUPPORTED_SCHEMAS (5600+ chars) as static variable
- LineChecker: add static caches for isDirective(), isLink(), and
  isAnnotation() regex results with proper cache key handling
- Buffer: ensure unindented flag is reset in all mutators (set, pop,
  clear) for consistent cache invalidation
- CachableInlineRule: simplify type annotations

Note: Lexer reuse assumes single-threaded parsing. Concurrent parsing
would require separate instances.

See https://cybottm.github.io/render-guides/ for benchmark data.

Author: CybotTM

packages/guides-restructured-text/src/RestructuredText/Parser/Buffer.php

@@ -27,6 +27,9 @@
 
 final class Buffer
 {
+    /** @var bool Whether unIndent() has already been called */
+    private bool $unindented = false;
+
     /** @param string[] $lines */
     public function __construct(
         private array $lines = [],
@@ -56,11 +59,13 @@ public function get(int $key): string
 
     public function push(string $line): void
     {
+        $this->unindented = false;
         $this->lines[] = $line;
     }
 
     public function set(int $key, string $line): void
     {
+        $this->unindented = false;
         $this->lines[$key] = $line;
     }
 
@@ -81,6 +86,8 @@ public function getLinesString(): string
 
     public function pop(): string|null
     {
+        $this->unindented = false;
+
         return array_pop($this->lines);
     }
 
@@ -97,6 +104,7 @@ public function getLastLine(): string|null
 
     public function clear(): void
     {
+        $this->unindented = false;
         $this->lines = [];
     }
 
@@ -109,12 +117,18 @@ public function trimLines(): void
 
     private function unIndent(): void
     {
+        if ($this->unindented) {
+            return;
+        }
+
         if ($this->unindentStrategy === UnindentStrategy::NONE) {
             return;
         }
 
         $indentation = $this->detectIndentation();
         if ($indentation === 0) {
+            $this->unindented = true;
+
             return;
         }
 
@@ -125,6 +139,8 @@ private function unIndent(): void
 
             $this->lines[$i] = substr($line, $indentation);
         }
+
+        $this->unindented = true;
     }
 
     private function detectIndentation(): int

packages/guides-restructured-text/src/RestructuredText/Parser/InlineLexer.php

@@ -55,6 +55,9 @@ final class InlineLexer extends AbstractLexer
     public const VARIABLE_DELIMITER = 24;
     public const ESCAPED_SIGN = 25;
 
+    /** @var string|null Cached hyperlink pattern (built once from SUPPORTED_SCHEMAS) */
+    private static string|null $hyperlinkPattern = null;
+
     /**
      * Map between string position and position in token list.
      *
@@ -162,7 +165,12 @@ protected function getType(string &$value)
             return self::LITERAL;
         }
 
-        if (preg_match('/' . ExternalReferenceResolver::SUPPORTED_SCHEMAS . ':[-a-zA-Z0-9()@:%_\\+.~#?&\\/=]*[-a-zA-Z0-9()@%_\\+~#&\\/=]/', $value) && parse_url($value, PHP_URL_SCHEME) !== null) {
+        // Cache the expensive hyperlink pattern (5600+ chars from SUPPORTED_SCHEMAS)
+        if (self::$hyperlinkPattern === null) {
+            self::$hyperlinkPattern = '/' . ExternalReferenceResolver::SUPPORTED_SCHEMAS . ':[-a-zA-Z0-9()@:%_\\+.~#?&\\/=]*[-a-zA-Z0-9()@%_\\+~#&\\/=]/';
+        }
+
+        if (preg_match(self::$hyperlinkPattern, $value) && parse_url($value, PHP_URL_SCHEME) !== null) {
             return self::HYPERLINK;
         }
 

packages/guides-restructured-text/src/RestructuredText/Parser/InlineParser.php

@@ -29,9 +29,18 @@ class InlineParser
     /** @var InlineRule[] */
     private array $rules;
 
-    /** @var array<InlineLexer::*, CachableInlineRule> */
+    /** @var array<int, CachableInlineRule> */
     private array $cache = [];
 
+    /**
+     * Reusable lexer instance to avoid repeated instantiation.
+     *
+     * Note: This assumes single-threaded parsing. The lexer state is fully
+     * reset via setInput() before each parse, but concurrent parsing would
+     * cause race conditions.
+     */
+    private InlineLexer $lexer;
+
     /** @param iterable<InlineRule> $inlineRules */
     public function __construct(iterable $inlineRules)
     {
@@ -44,11 +53,13 @@ public function __construct(iterable $inlineRules)
 
             $this->cache[$rule->getToken()] = $rule;
         }
+
+        $this->lexer = new InlineLexer();
     }
 
     public function parse(string $content, BlockContext $blockContext): InlineCompoundNode
     {
-        $lexer = new InlineLexer();
+        $lexer = $this->lexer;
         $lexer->setInput($content);
         $lexer->moveNext();
         $lexer->moveNext();

packages/guides-restructured-text/src/RestructuredText/Parser/LineChecker.php

@@ -20,6 +20,15 @@
 
 final class LineChecker
 {
+    /** @var array<string, bool> Cache for isDirective results */
+    private static array $directiveCache = [];
+
+    /** @var array<string, bool> Cache for isLink results */
+    private static array $linkCache = [];
+
+    /** @var array<string, bool> Cache for isAnnotation results */
+    private static array $annotationCache = [];
+
     private const HEADER_LETTERS = [
         '!',
         '"',
@@ -79,16 +88,38 @@ public static function isSpecialLine(string $line, int $minimumLength = 2): stri
 
     public static function isDirective(string $line): bool
     {
-        return preg_match('/^\.\.\s+(\|(.+)\| |)([^\s]+)::( (.*)|)$/mUsi', $line) > 0;
+        if (isset(self::$directiveCache[$line])) {
+            return self::$directiveCache[$line];
+        }
+
+        $result = preg_match('/^\.\.\s+(\|(.+)\| |)([^\s]+)::( (.*)|)$/mUsi', $line) > 0;
+        self::$directiveCache[$line] = $result;
+
+        return $result;
     }
 
     public static function isLink(string $line): bool
     {
-        return preg_match('/^\.\.\s+_(.+):.*$/mUsi', trim($line)) > 0;
+        $trimmedLine = trim($line);
+        if (isset(self::$linkCache[$trimmedLine])) {
+            return self::$linkCache[$trimmedLine];
+        }
+
+        $result = preg_match('/^\.\.\s+_(.+):.*$/mUsi', $trimmedLine) > 0;
+        self::$linkCache[$trimmedLine] = $result;
+
+        return $result;
     }
 
     public static function isAnnotation(string $line): bool
     {
-        return preg_match('/^\.\.\s+\[([#a-zA-Z0-9]*)\]\s(.*)$$/mUsi', $line) > 0;
+        if (isset(self::$annotationCache[$line])) {
+            return self::$annotationCache[$line];
+        }
+
+        $result = preg_match('/^\.\.\s+\[([#a-zA-Z0-9]*)\]\s(.*)$$/mUsi', $line) > 0;
+        self::$annotationCache[$line] = $result;
+
+        return $result;
     }
 }

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

@@ -13,10 +13,7 @@
 
 namespace phpDocumentor\Guides\RestructuredText\Parser\Productions\InlineRules;
 
-use phpDocumentor\Guides\RestructuredText\Parser\InlineLexer;
-
 interface CachableInlineRule extends InlineRule
 {
-    /** @return InlineLexer::* */
     public function getToken(): int;
 }