perf: add O(1) lookup caching for ProjectNode document entries

- Cache root document entry on add for O(1) getRootDocumentEntry()
- Use direct hash lookup for getDocumentEntry() instead of iteration
- Properly invalidate cache on setDocumentEntries() and reset()

Author: CybotTM

packages/guides/src/Nodes/ProjectNode.php

@@ -47,6 +47,9 @@ final class ProjectNode extends CompoundNode
     /** @var array<string, array<string, InternalTarget>> */
     private array $internalLinkTargets = [];
 
+    /** Cached root document entry for O(1) lookup */
+    private DocumentEntryNode|null $rootDocumentEntry = null;
+
     /** @var DocumentEntryNode[] */
     private array $documentEntries = [];
     private DateTimeImmutable $lastRendered;
@@ -182,6 +185,11 @@ public function getAllInternalTargets(): array
 
     public function addDocumentEntry(DocumentEntryNode $documentEntry): void
     {
+        // Cache root document entry for O(1) lookup
+        if ($documentEntry->isRoot()) {
+            $this->rootDocumentEntry = $documentEntry;
+        }
+
         $this->documentEntries[$documentEntry->getFile()] = $documentEntry;
     }
 
@@ -193,8 +201,15 @@ public function getAllDocumentEntries(): array
 
     public function getRootDocumentEntry(): DocumentEntryNode
     {
+        if ($this->rootDocumentEntry !== null) {
+            return $this->rootDocumentEntry;
+        }
+
+        // Fallback: scan and cache if set via setDocumentEntries()
         foreach ($this->documentEntries as $documentEntry) {
             if ($documentEntry->isRoot()) {
+                $this->rootDocumentEntry = $documentEntry;
+
                 return $documentEntry;
             }
         }
@@ -205,10 +220,8 @@ public function getRootDocumentEntry(): DocumentEntryNode
     /** @throws DocumentEntryNotFound */
     public function getDocumentEntry(string $file): DocumentEntryNode
     {
-        foreach ($this->documentEntries as $documentEntry) {
-            if ($documentEntry->getFile() === $file) {
-                return $documentEntry;
-            }
+        if (isset($this->documentEntries[$file])) {
+            return $this->documentEntries[$file];
         }
 
         throw new DocumentEntryNotFound('No document Entry found for file ' . $file);
@@ -218,6 +231,7 @@ public function getDocumentEntry(string $file): DocumentEntryNode
     public function setDocumentEntries(array $documentEntries): void
     {
         $this->documentEntries = $documentEntries;
+        $this->rootDocumentEntry = null;
     }
 
     public function findDocumentEntry(string $filePath): DocumentEntryNode|null
@@ -228,6 +242,7 @@ public function findDocumentEntry(string $filePath): DocumentEntryNode|null
     public function reset(): void
     {
         $this->documentEntries = [];
+        $this->rootDocumentEntry = null;
     }
 
     public function getLastRendered(): DateTimeImmutable