refactor: Use file path comparison instead of object identity for DocumentEntryNode

packages/guides/src/Compiler/Passes/GlobalMenuPass.php

@@ -62,8 +62,9 @@ public function run(array $documents, CompilerContextInterface $compilerContext)
         }
 
         $rootDocument = null;
+        $rootFile = $rootDocumentEntry->getFile();
         foreach ($documents as $document) {
-            if ($document->getDocumentEntry() === $rootDocumentEntry) {
+            if ($document->getDocumentEntry()->getFile() === $rootFile) {
                 $rootDocument = $document;
                 break;
             }

packages/guides/src/Compiler/Passes/ToctreeValidationPass.php

@@ -68,6 +68,7 @@ public function run(array $documents, CompilerContextInterface $compilerContext)
 
     public function isMissingInToctree(DocumentEntryNode $documentEntry, ProjectNode $projectNode): bool
     {
-        return $documentEntry->getParent() === null && $documentEntry !== $projectNode->getRootDocumentEntry();
+        return $documentEntry->getParent() === null
+            && $documentEntry->getFile() !== $projectNode->getRootDocumentEntry()->getFile();
     }
 }

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,10 @@ public function getAllInternalTargets(): array
 
     public function addDocumentEntry(DocumentEntryNode $documentEntry): void
     {
+        if ($documentEntry->isRoot()) {
+            $this->rootDocumentEntry = $documentEntry;
+        }
+
         $this->documentEntries[$documentEntry->getFile()] = $documentEntry;
     }
 
@@ -193,8 +200,15 @@ public function getAllDocumentEntries(): array
 
     public function getRootDocumentEntry(): DocumentEntryNode
     {
+        if ($this->rootDocumentEntry !== null) {
+            return $this->rootDocumentEntry;
+        }
+
+        // Fallback: scan entries (handles setDocumentEntries with numeric keys)
         foreach ($this->documentEntries as $documentEntry) {
             if ($documentEntry->isRoot()) {
+                $this->rootDocumentEntry = $documentEntry;
+
                 return $documentEntry;
             }
         }
@@ -205,6 +219,12 @@ public function getRootDocumentEntry(): DocumentEntryNode
     /** @throws DocumentEntryNotFound */
     public function getDocumentEntry(string $file): DocumentEntryNode
     {
+        // O(1) lookup - documentEntries is keyed by file path (from addDocumentEntry)
+        if (isset($this->documentEntries[$file])) {
+            return $this->documentEntries[$file];
+        }
+
+        // Fallback: iterate for numerically-indexed arrays (from setDocumentEntries)
         foreach ($this->documentEntries as $documentEntry) {
             if ($documentEntry->getFile() === $file) {
                 return $documentEntry;
@@ -218,6 +238,7 @@ public function getDocumentEntry(string $file): DocumentEntryNode
     public function setDocumentEntries(array $documentEntries): void
     {
         $this->documentEntries = $documentEntries;
+        $this->rootDocumentEntry = null; // Invalidate cache
     }
 
     public function findDocumentEntry(string $filePath): DocumentEntryNode|null
@@ -228,6 +249,7 @@ public function findDocumentEntry(string $filePath): DocumentEntryNode|null
     public function reset(): void
     {
         $this->documentEntries = [];
+        $this->rootDocumentEntry = null;
     }
 
     public function getLastRendered(): DateTimeImmutable

packages/guides/src/RenderContext.php

@@ -222,8 +222,9 @@ public function getProjectNode(): ProjectNode
 
     public function getDocumentNodeForEntry(DocumentEntryNode $entryNode): DocumentNode
     {
+        $file = $entryNode->getFile();
         foreach ($this->allDocuments as $child) {
-            if ($child->getDocumentEntry() === $entryNode) {
+            if ($child->getDocumentEntry()->getFile() === $file) {
                 return $child;
             }
         }

packages/guides/src/Renderer/DocumentTreeIterator.php

@@ -41,8 +41,9 @@ public function __construct(
 
     public function current(): DocumentNode
     {
+        $file = $this->levelNodes[$this->position]->getFile();
         foreach ($this->documents as $document) {
-            if ($document->getDocumentEntry() === $this->levelNodes[$this->position]) {
+            if ($document->getDocumentEntry()->getFile() === $file) {
                 return $document;
             }
         }