Merge pull request #371 from phpDocumentor/feature/references

Add new compiler pass to move anchors

Author: jaapio

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

@@ -36,6 +36,6 @@ public function apply(ParserContext $parserContext, InlineLexer $lexer): Literal
     public function getPriority(): int
     {
         // Should be executed first as any other rules within may not be interpreted
-        return 10000;
+        return 10_000;
     }
 }

packages/guides/src/Compiler/CompilerContext.php

@@ -16,11 +16,12 @@
 use Exception;
 use phpDocumentor\Guides\Compiler\ShadowTree\TreeNode;
 use phpDocumentor\Guides\Nodes\DocumentNode;
+use phpDocumentor\Guides\Nodes\Node;
 use phpDocumentor\Guides\Nodes\ProjectNode;
 
 class CompilerContext
 {
-    /** @var TreeNode<DocumentNode> */
+    /** @var TreeNode<Node> */
     private TreeNode $shadowTree;
 
     public function __construct(
@@ -42,15 +43,24 @@ public function getDocumentNode(): DocumentNode
         return $this->shadowTree->getRoot()->getNode();
     }
 
-    public function withShadowTree(DocumentNode $documentNode): static
+    public function withDocumentShadowTree(DocumentNode $documentNode): static
     {
         $that = clone $this;
         $that->shadowTree = TreeNode::createFromDocument($documentNode);
 
         return $that;
     }
 
-    /** @return TreeNode<DocumentNode> */
+    /** @param TreeNode<Node> $shadowTree */
+    public function withShadowTree(TreeNode $shadowTree): static
+    {
+        $that = clone $this;
+        $that->shadowTree = $shadowTree;
+
+        return $that;
+    }
+
+    /** @return TreeNode<Node> */
     public function getShadowTree(): TreeNode
     {
         if (!isset($this->shadowTree)) {

packages/guides/src/Compiler/DocumentNodeTraverser.php

@@ -50,7 +50,7 @@ private function traverseForTransformer(
         }
 
         foreach ($shadowNode->getChildren() as $shadowChild) {
-            $this->traverseForTransformer($transformer, $shadowChild, $compilerContext);
+            $this->traverseForTransformer($transformer, $shadowChild, $compilerContext->withShadowTree($shadowChild));
         }
 
         if (!$supports) {

packages/guides/src/Compiler/NodeTransformers/CitationTargetTransformer.php

@@ -40,6 +40,6 @@ public function supports(Node $node): bool
 
     public function getPriority(): int
     {
-        return 20000;
+        return 20_000;
     }
 }

packages/guides/src/Compiler/NodeTransformers/ClassNodeTransformer.php

@@ -61,6 +61,6 @@ public function supports(Node $node): bool
 
     public function getPriority(): int
     {
-        return 40000;
+        return 40_000;
     }
 }

packages/guides/src/Compiler/NodeTransformers/CollectLinkTargetsTransformer.php

@@ -14,6 +14,8 @@
 use SplStack;
 use Webmozart\Assert\Assert;
 
+use function assert;
+
 /** @implements NodeTransformer<DocumentNode|AnchorNode> */
 final class CollectLinkTargetsTransformer implements NodeTransformer
 {
@@ -35,12 +37,17 @@ public function enterNode(Node $node, CompilerContext $compilerContext): Node
         if ($node instanceof DocumentNode) {
             $this->documentStack->push($node);
         } elseif ($node instanceof AnchorNode) {
-            $currentDocument = $this->documentStack->top();
-            Assert::notNull($currentDocument);
+            $currentDocument = $compilerContext->getDocumentNode();
+            $parentSection = $compilerContext->getShadowTree()->getParent()?->getNode();
+            assert($parentSection instanceof SectionNode);
 
             $compilerContext->getProjectNode()->addLinkTarget(
                 $node->toString(),
-                new InternalTarget($currentDocument->getFilePath(), $node->toString()),
+                new InternalTarget(
+                    $currentDocument->getFilePath(),
+                    $node->toString(),
+                    $parentSection->getTitle()->toString(),
+                ),
             );
         } elseif ($node instanceof SectionNode) {
             $currentDocument = $this->documentStack->top();

packages/guides/src/Compiler/NodeTransformers/FootNodeNamedTransformer.php

@@ -41,6 +41,6 @@ public function supports(Node $node): bool
     public function getPriority(): int
     {
         // must be run *after* FootNodeNumberedTransformer
-        return 20000;
+        return 20_000;
     }
 }

packages/guides/src/Compiler/NodeTransformers/FootNodeNumberedTransformer.php

@@ -40,6 +40,6 @@ public function supports(Node $node): bool
     public function getPriority(): int
     {
         // must be run *before* FootNodeNamedTransformer
-        return 30000;
+        return 30_000;
     }
 }

packages/guides/src/Compiler/NodeTransformers/MoveAnchorTransformer.php

@@ -0,0 +1,109 @@
+<?php
+
+declare(strict_types=1);
+
+namespace phpDocumentor\Guides\Compiler\NodeTransformers;
+
+use ArrayIterator;
+use LogicException;
+use phpDocumentor\Guides\Compiler\CompilerContext;
+use phpDocumentor\Guides\Compiler\NodeTransformer;
+use phpDocumentor\Guides\Compiler\ShadowTree\TreeNode;
+use phpDocumentor\Guides\Nodes\AnchorNode;
+use phpDocumentor\Guides\Nodes\Node;
+use phpDocumentor\Guides\Nodes\SectionNode;
+use WeakMap;
+
+/** @implements NodeTransformer<AnchorNode> */
+final class MoveAnchorTransformer implements NodeTransformer
+{
+    /** @var WeakMap<AnchorNode, true> */
+    private WeakMap $seen;
+
+    public function __construct()
+    {
+        $this->seen = new WeakMap();
+    }
+
+    public function enterNode(Node $node, CompilerContext $compilerContext): Node
+    {
+        return $node;
+    }
+
+    public function leaveNode(Node $node, CompilerContext $compilerContext): Node|null
+    {
+        //When exists in seen, it means that the node has already been processed. Ignore it.
+        if (isset($this->seen[$node])) {
+            return $node;
+        }
+
+        $this->seen[$node] = true;
+        $parent = $compilerContext->getShadowTree()->getParent();
+        if ($parent === null) {
+            throw new LogicException('Node not found in shadow tree');
+        }
+
+        $position = $parent->findPosition($node);
+        if ($position === null) {
+            throw new LogicException('Node not found in shadow tree');
+        }
+
+        return $this->attemptMoveToNeighbour($parent, $position, $node);
+    }
+
+    public function supports(Node $node): bool
+    {
+        return $node instanceof AnchorNode;
+    }
+
+    public function getPriority(): int
+    {
+        return 30_000;
+    }
+
+    /** @param TreeNode<Node> $parent */
+    private function attemptMoveToNeighbour(TreeNode $parent, int $position, AnchorNode $node): AnchorNode|null
+    {
+        $current = $this->findNextSection($parent, $position);
+        if ($current === null) {
+            if ($parent->getParent() === null) {
+                return $node;
+            }
+
+            $position = $parent->getParent()->findPosition($parent->getNode());
+            if ($position === null) {
+                throw new LogicException('Node not found in shadow tree');
+            }
+
+            return $this->attemptMoveToNeighbour($parent->getParent(), $position, $node);
+        }
+
+        if ($current->getNode() instanceof SectionNode) {
+            $current->pushChild($node);
+
+            return null;
+        }
+
+        return $node;
+    }
+
+    /**
+     * @param TreeNode<Node> $parent
+     *
+     * @return TreeNode<Node>|null
+     */
+    private function findNextSection(TreeNode $parent, int $position): TreeNode|null
+    {
+        $children = new ArrayIterator($parent->getChildren());
+        if ($children->count() <= $position + 1) {
+            return null;
+        }
+
+        $children->seek($position + 1);
+        while ($children->valid() && $children->current()->getNode() instanceof AnchorNode) {
+            $children->next();
+        }
+
+        return $children->current();
+    }
+}

packages/guides/src/Compiler/NodeTransformers/TransformerPass.php

@@ -34,7 +34,7 @@ public function run(array $documents, CompilerContext $compilerContext): array
                 continue;
             }
 
-            $compilerContext = $compilerContext->withShadowTree($document);
+            $compilerContext = $compilerContext->withDocumentShadowTree($document);
             $documents[$key] = $this->documentNodeTraverser->traverse($document, $compilerContext);
         }