[FIX] issue with document iterator

Changed the logic of moving in the document iterator,
this removes some complexity to make the iterator easier to understand.

Author: jaapio

packages/guides/src/Renderer/DocumentListIterator.php

@@ -7,6 +7,7 @@
 use AppendIterator;
 use Generator;
 use Iterator;
+use OutOfRangeException;
 use phpDocumentor\Guides\Nodes\DocumentNode;
 use RecursiveIteratorIterator;
 use WeakMap;
@@ -16,10 +17,13 @@
 final class DocumentListIterator implements Iterator
 {
     /** @var WeakReference<DocumentNode>|null */
-    private WeakReference|null $previousDocument;
+    private WeakReference|null $previousDocument = null;
 
     /** @var WeakReference<DocumentNode>|null */
-    private WeakReference|null $nextDocument;
+    private WeakReference|null $currentDocument;
+
+    /** @var WeakReference<DocumentNode>|null */
+    private WeakReference|null $nextDocument = null;
 
     /** @var WeakMap<DocumentNode, bool> */
     private WeakMap $unseenDocuments;
@@ -33,28 +37,30 @@ public function __construct(
         array $documents,
     ) {
         $this->unseenDocuments = new WeakMap();
-        $this->previousDocument = null;
-        $this->nextDocument = null;
         $this->innerIterator = new AppendIterator();
         $this->innerIterator->append(
             new RecursiveIteratorIterator($iterator, RecursiveIteratorIterator::SELF_FIRST),
         );
         $this->innerIterator->append($this->unseenIterator());
+        if ($this->innerIterator->valid()) {
+            $this->currentDocument = WeakReference::create($this->innerIterator->current());
+        }
+
         foreach ($documents as $document) {
             $this->unseenDocuments[$document] = true;
         }
     }
 
     public function next(): void
     {
-        if ($this->innerIterator->valid()) {
-            $this->previousDocument = WeakReference::create($this->current());
-        } else {
-            $this->previousDocument = null;
+        $this->previousDocument = $this->currentDocument;
+        if ($this->nextDocument === null && $this->innerIterator->valid()) {
+            $this->innerIterator->next();
         }
 
-        if ($this->nextDocument === null) {
-            $this->innerIterator->next();
+        $this->currentDocument = null;
+        if ($this->innerIterator->current() !== null) {
+            $this->currentDocument = WeakReference::create($this->innerIterator->current());
         }
 
         $this->nextDocument = null;
@@ -80,7 +86,7 @@ public function nextNode(): DocumentNode|null
             $this->innerIterator->next();
 
             if ($this->innerIterator->valid()) {
-                $this->nextDocument = WeakReference::create($this->current());
+                $this->nextDocument = WeakReference::create($this->innerIterator->current());
             }
         }
 
@@ -89,7 +95,12 @@ public function nextNode(): DocumentNode|null
 
     public function current(): mixed
     {
-        $document = $this->innerIterator->current();
+        $document = $this->currentDocument?->get();
+
+        if ($document === null) {
+            throw new OutOfRangeException('No current document available');
+        }
+
         if ($document instanceof DocumentNode) {
             $this->unseenDocuments[$document] = false;
         }

packages/guides/tests/unit/Renderer/DocumentListIteratorTest.php

@@ -20,7 +20,7 @@ public function testNormalIteration(): void
 
         self::assertSame(self::documentsToTitle($this->flatDocumentList), self::documentsToTitle($result));
         self::assertNull($iterator->nextNode());
-        self::assertNull($iterator->previousNode());
+        self::assertNotNull($iterator->previousNode());
     }
 
     public function testPreviousStepsBackAtSameLevel(): void

phpstan-baseline.neon

@@ -125,6 +125,11 @@ parameters:
 			count: 1
 			path: packages/guides/src/DependencyInjection/GuidesExtension.php
 
+		-
+			message: "#^Property phpDocumentor\\\\Guides\\\\Renderer\\\\DocumentListIterator\\:\\:\\$currentDocument \\(WeakReference\\<phpDocumentor\\\\Guides\\\\Nodes\\\\DocumentNode\\>\\|null\\) does not accept WeakReference\\<TIn of object\\>\\.$#"
+			count: 1
+			path: packages/guides/src/Renderer/DocumentListIterator.php
+
 		-
 			message: "#^Return type \\(iterable\\<phpDocumentor\\\\Guides\\\\Compiler\\\\NodeTransformers\\\\MoveAnchorTransformer\\>\\) of method class@anonymous/packages/guides/tests/unit/Compiler/NodeTransformers/MoveAnchorTransformerTest\\.php\\:23\\:\\:getTransformers\\(\\) should be compatible with return type \\(iterable\\<phpDocumentor\\\\Guides\\\\Compiler\\\\NodeTransformer\\<phpDocumentor\\\\Guides\\\\Nodes\\\\Node\\>\\>\\) of method phpDocumentor\\\\Guides\\\\Compiler\\\\NodeTransformers\\\\NodeTransformerFactory\\:\\:getTransformers\\(\\)$#"
 			count: 1