perf: add caching layer for frequently accessed operations

Add instance and result caching for hot paths in the rendering pipeline:

- ProjectNode: cache root document entry with O(1) lookup, add fast-path
  to getDocumentEntry(), lazy cache invalidation in setDocumentEntries()
- DocumentNode: add hasDocumentEntry() helper for safe checks
- RenderContext: use hash map for O(1) document lookup by file path,
  optimize withDocument() to clone directly instead of rebuilding
- DocumentNameResolver: cache URI analysis and resolved paths
- ExternalReferenceResolver: pre-compile schema regex pattern
- SluggerAnchorNormalizer: cache slugger instance and normalization results
- AbstractUrlGenerator: cache isRelativePath() checks
- RelativeUrlGenerator: cache computed relative paths
- PreNodeRendererFactory: cache renderer lookups by node class
- TwigEnvironmentBuilder: enable filesystem template caching
- TwigTemplateRenderer: cache global context to avoid redundant addGlobal()

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

Author: CybotTM

packages/guides/src/NodeRenderers/PreRenderers/PreNodeRendererFactory.php

@@ -21,9 +21,16 @@
 
 /**
  * Decorator to add pre-rendering logic to node renderers.
+ *
+ * Note: Caching assumes PreNodeRenderer::supports() only checks the node's
+ * class type, not instance-specific properties. If a PreNodeRenderer needs
+ * to check node properties, caching by class would return incorrect results.
  */
 final class PreNodeRendererFactory implements NodeRendererFactory
 {
+    /** @var array<class-string<Node>, NodeRenderer<Node>> */
+    private array $cache = [];
+
     public function __construct(
         private readonly NodeRendererFactory $innerFactory,
         /** @var iterable<PreNodeRenderer> */
@@ -33,6 +40,12 @@ public function __construct(
 
     public function get(Node $node): NodeRenderer
     {
+        // Cache by node class to avoid repeated preRenderer iteration
+        $nodeFqcn = $node::class;
+        if (isset($this->cache[$nodeFqcn])) {
+            return $this->cache[$nodeFqcn];
+        }
+
         $preRenderers = [];
         foreach ($this->preRenderers as $preRenderer) {
             if (!$preRenderer->supports($node)) {
@@ -43,9 +56,9 @@ public function get(Node $node): NodeRenderer
         }
 
         if (count($preRenderers) === 0) {
-            return $this->innerFactory->get($node);
+            return $this->cache[$nodeFqcn] = $this->innerFactory->get($node);
         }
 
-        return new PreRenderer($this->innerFactory->get($node), $preRenderers);
+        return $this->cache[$nodeFqcn] = new PreRenderer($this->innerFactory->get($node), $preRenderers);
     }
 }

packages/guides/src/Nodes/DocumentNode.php

@@ -279,6 +279,11 @@ public function getFootnoteTargetAnonymous(): FootnoteTarget|null
         return null;
     }
 
+    public function hasDocumentEntry(): bool
+    {
+        return $this->documentEntry !== null;
+    }
+
     public function getDocumentEntry(): DocumentEntryNode
     {
         if ($this->documentEntry === null) {

packages/guides/src/ReferenceResolvers/DocumentNameResolver.php

@@ -23,6 +23,18 @@
 
 final class DocumentNameResolver implements DocumentNameResolverInterface
 {
+    /** @var array<string, string> */
+    private array $absoluteUrlCache = [];
+
+    /** @var array<string, string> */
+    private array $canonicalUrlCache = [];
+
+    /** @var array<string, bool> */
+    private array $isAbsoluteCache = [];
+
+    /** @var array<string, bool> */
+    private array $isAbsolutePathCache = [];
+
     /**
      * Returns the absolute path, including prefixing '/'.
      *
@@ -31,20 +43,31 @@ final class DocumentNameResolver implements DocumentNameResolverInterface
      */
     public function absoluteUrl(string $basePath, string $url): string
     {
-        $uri = BaseUri::from($url);
-        if ($uri->isAbsolute()) {
-            return $url;
+        $cacheKey = $basePath . '|' . $url;
+        if (isset($this->absoluteUrlCache[$cacheKey])) {
+            return $this->absoluteUrlCache[$cacheKey];
+        }
+
+        // Cache URI analysis results separately by URL
+        if (!isset($this->isAbsoluteCache[$url])) {
+            $uri = BaseUri::from($url);
+            $this->isAbsoluteCache[$url] = $uri->isAbsolute();
+            $this->isAbsolutePathCache[$url] = $uri->isAbsolutePath();
+        }
+
+        if ($this->isAbsoluteCache[$url]) {
+            return $this->absoluteUrlCache[$cacheKey] = $url;
         }
 
-        if ($uri->isAbsolutePath()) {
-            return $url;
+        if ($this->isAbsolutePathCache[$url]) {
+            return $this->absoluteUrlCache[$cacheKey] = $url;
         }
 
         if ($basePath === '/') {
-            return $basePath . $url;
+            return $this->absoluteUrlCache[$cacheKey] = $basePath . $url;
         }
 
-        return '/' . trim($basePath, '/') . '/' . $url;
+        return $this->absoluteUrlCache[$cacheKey] = '/' . trim($basePath, '/') . '/' . $url;
     }
 
     /**
@@ -57,8 +80,13 @@ public function absoluteUrl(string $basePath, string $url): string
      */
     public function canonicalUrl(string $basePath, string $url): string
     {
+        $cacheKey = $basePath . '|' . $url;
+        if (isset($this->canonicalUrlCache[$cacheKey])) {
+            return $this->canonicalUrlCache[$cacheKey];
+        }
+
         if ($url[0] === '/') {
-            return ltrim($url, '/');
+            return $this->canonicalUrlCache[$cacheKey] = ltrim($url, '/');
         }
 
         $dirNameParts = explode('/', $basePath);
@@ -78,6 +106,6 @@ public function canonicalUrl(string $basePath, string $url): string
             $urlPass1[] = $part;
         }
 
-        return ltrim(implode('/', $dirNameParts) . '/' . implode('/', $urlPass1), '/');
+        return $this->canonicalUrlCache[$cacheKey] = ltrim(implode('/', $dirNameParts) . '/' . implode('/', $urlPass1), '/');
     }
 }