Introduce CompilerContextInterface

The Compiler context is a very important class in our compiler, however
extending projects may want to extend the information caried around with the context
to add extra information for specific use cases in custom compiler passes.

To make this possible I introduced a new interface to be able to wrap the compilercontext
and extend the functionality. Changing the interfaces would be a backward compatibility break
so we need to introduce this step by step.

Author: jaapio

packages/guides/src/Compiler/CompilerContext.php

@@ -19,7 +19,18 @@
 use phpDocumentor\Guides\Nodes\Node;
 use phpDocumentor\Guides\Nodes\ProjectNode;
 
-final class CompilerContext
+/**
+ * Context class used in compiler passes to store the state of the nodes.
+ *
+ * The {@see Compiler} is making changes to the nodes in a {@see DocumentNode} as the nodes are immutable cannot
+ * do this directly. This class helps to modify the nodes in the {@see DocumentNode} by creating a shadow tree.
+ *
+ * The class is final and should not be extended, if you need to provide more information to the compiler pass
+ * you can use the {@see CompilerContextInterface} and decorate this class.
+ *
+ * @final
+ */
+class CompilerContext implements CompilerContextInterface
 {
     /** @var TreeNode<Node> */
     private TreeNode $shadowTree;

packages/guides/src/Compiler/CompilerContextInterface.php

@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of phpDocumentor.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ *
+ * @link https://phpdoc.org
+ */
+
+namespace phpDocumentor\Guides\Compiler;
+
+use phpDocumentor\Guides\Compiler\ShadowTree\TreeNode;
+use phpDocumentor\Guides\Nodes\DocumentNode;
+use phpDocumentor\Guides\Nodes\Node;
+use phpDocumentor\Guides\Nodes\ProjectNode;
+
+interface CompilerContextInterface
+{
+    public function getProjectNode(): ProjectNode;
+
+    public function getDocumentNode(): DocumentNode;
+
+    public function withDocumentShadowTree(DocumentNode $documentNode): self;
+
+    /** @param TreeNode<Node> $shadowTree */
+    public function withShadowTree(TreeNode $shadowTree): self;
+
+    /** @return TreeNode<Node> */
+    public function getShadowTree(): TreeNode;
+
+    /** @return array<string, string> */
+    public function getLoggerInformation(): array;
+}

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

@@ -13,15 +13,15 @@
 
 namespace phpDocumentor\Guides\Compiler\NodeTransformers;
 
-use phpDocumentor\Guides\Compiler\CompilerContext;
+use phpDocumentor\Guides\Compiler\CompilerContextInterface;
 use phpDocumentor\Guides\Compiler\NodeTransformer;
 use phpDocumentor\Guides\Nodes\Inline\CitationInlineNode;
 use phpDocumentor\Guides\Nodes\Node;
 
 /** @implements NodeTransformer<Node> */
 final class CitationInlineNodeTransformer implements NodeTransformer
 {
-    public function enterNode(Node $node, CompilerContext $compilerContext): Node
+    public function enterNode(Node $node, CompilerContextInterface $compilerContext): Node
     {
         if ($node instanceof CitationInlineNode) {
             $internalTarget = $compilerContext->getProjectNode()->getCitationTarget($node->getName());
@@ -31,7 +31,7 @@ public function enterNode(Node $node, CompilerContext $compilerContext): Node
         return $node;
     }
 
-    public function leaveNode(Node $node, CompilerContext $compilerContext): Node|null
+    public function leaveNode(Node $node, CompilerContextInterface $compilerContext): Node|null
     {
         return $node;
     }

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

@@ -13,7 +13,7 @@
 
 namespace phpDocumentor\Guides\Compiler\NodeTransformers;
 
-use phpDocumentor\Guides\Compiler\CompilerContext;
+use phpDocumentor\Guides\Compiler\CompilerContextInterface;
 use phpDocumentor\Guides\Compiler\NodeTransformer;
 use phpDocumentor\Guides\Meta\CitationTarget;
 use phpDocumentor\Guides\Nodes\CitationNode;
@@ -22,7 +22,7 @@
 /** @implements NodeTransformer<Node> */
 final class CitationTargetTransformer implements NodeTransformer
 {
-    public function enterNode(Node $node, CompilerContext $compilerContext): Node
+    public function enterNode(Node $node, CompilerContextInterface $compilerContext): Node
     {
         if ($node instanceof CitationNode) {
             $compilerContext->getProjectNode()->addCitationTarget(
@@ -37,7 +37,7 @@ public function enterNode(Node $node, CompilerContext $compilerContext): Node
         return $node;
     }
 
-    public function leaveNode(Node $node, CompilerContext $compilerContext): Node|null
+    public function leaveNode(Node $node, CompilerContextInterface $compilerContext): Node|null
     {
         return $node;
     }

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

@@ -13,7 +13,7 @@
 
 namespace phpDocumentor\Guides\Compiler\NodeTransformers;
 
-use phpDocumentor\Guides\Compiler\CompilerContext;
+use phpDocumentor\Guides\Compiler\CompilerContextInterface;
 use phpDocumentor\Guides\Compiler\NodeTransformer;
 use phpDocumentor\Guides\Nodes\ClassNode;
 use phpDocumentor\Guides\Nodes\DocumentNode;
@@ -32,7 +32,7 @@ final class ClassNodeTransformer implements NodeTransformer
     /** @var string[] */
     private array $classes = [];
 
-    public function enterNode(Node $node, CompilerContext $compilerContext): Node
+    public function enterNode(Node $node, CompilerContextInterface $compilerContext): Node
     {
         if ($node instanceof DocumentNode) {
             // unset classes when entering the next document
@@ -52,7 +52,7 @@ public function enterNode(Node $node, CompilerContext $compilerContext): Node
         return $node;
     }
 
-    public function leaveNode(Node $node, CompilerContext $compilerContext): Node|null
+    public function leaveNode(Node $node, CompilerContextInterface $compilerContext): Node|null
     {
         if ($node instanceof ClassNode) {
             //Remove the class node from the tree.

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

@@ -13,7 +13,7 @@
 
 namespace phpDocumentor\Guides\Compiler\NodeTransformers;
 
-use phpDocumentor\Guides\Compiler\CompilerContext;
+use phpDocumentor\Guides\Compiler\CompilerContextInterface;
 use phpDocumentor\Guides\Compiler\NodeTransformer;
 use phpDocumentor\Guides\Meta\InternalTarget;
 use phpDocumentor\Guides\Nodes\AnchorNode;
@@ -49,7 +49,7 @@ public function __construct(
         $this->documentStack = new SplStack();
     }
 
-    public function enterNode(Node $node, CompilerContext $compilerContext): Node
+    public function enterNode(Node $node, CompilerContextInterface $compilerContext): Node
     {
         if ($node instanceof DocumentNode) {
             $this->documentStack->push($node);
@@ -137,7 +137,7 @@ public function enterNode(Node $node, CompilerContext $compilerContext): Node
         return $node;
     }
 
-    public function leaveNode(Node $node, CompilerContext $compilerContext): Node|null
+    public function leaveNode(Node $node, CompilerContextInterface $compilerContext): Node|null
     {
         if ($node instanceof DocumentNode) {
             $this->documentStack->pop();
@@ -157,7 +157,7 @@ public function getPriority(): int
         return 5000;
     }
 
-    private function addLinkTargetToProject(CompilerContext $compilerContext, InternalTarget $internalTarget): void
+    private function addLinkTargetToProject(CompilerContextInterface $compilerContext, InternalTarget $internalTarget): void
     {
         if ($compilerContext->getProjectNode()->hasInternalTarget($internalTarget->getAnchor(), $internalTarget->getLinkType())) {
             $otherLink = $compilerContext->getProjectNode()->getInternalTarget($internalTarget->getAnchor(), $internalTarget->getLinkType());

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

@@ -13,7 +13,7 @@
 
 namespace phpDocumentor\Guides\Compiler\NodeTransformers;
 
-use phpDocumentor\Guides\Compiler\CompilerContext;
+use phpDocumentor\Guides\Compiler\CompilerContextInterface;
 use phpDocumentor\Guides\Compiler\NodeTransformer;
 use phpDocumentor\Guides\Nodes\DocumentBlockNode;
 use phpDocumentor\Guides\Nodes\Menu\TocNode;
@@ -27,12 +27,12 @@
  */
 final class DocumentBlockNodeTransformer implements NodeTransformer
 {
-    public function enterNode(Node $node, CompilerContext $compilerContext): Node
+    public function enterNode(Node $node, CompilerContextInterface $compilerContext): Node
     {
         return $node;
     }
 
-    public function leaveNode(Node $node, CompilerContext $compilerContext): Node|null
+    public function leaveNode(Node $node, CompilerContextInterface $compilerContext): Node|null
     {
         if ($node instanceof DocumentBlockNode) {
             $children = [];

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

@@ -13,7 +13,7 @@
 
 namespace phpDocumentor\Guides\Compiler\NodeTransformers;
 
-use phpDocumentor\Guides\Compiler\CompilerContext;
+use phpDocumentor\Guides\Compiler\CompilerContextInterface;
 use phpDocumentor\Guides\Compiler\NodeTransformer;
 use phpDocumentor\Guides\Nodes\DocumentNode;
 use phpDocumentor\Guides\Nodes\DocumentTree\DocumentEntryNode;
@@ -29,12 +29,12 @@ public function __construct(
     ) {
     }
 
-    public function enterNode(Node $node, CompilerContext $compilerContext): Node
+    public function enterNode(Node $node, CompilerContextInterface $compilerContext): Node
     {
         return $node;
     }
 
-    public function leaveNode(Node $node, CompilerContext $compilerContext): Node|null
+    public function leaveNode(Node $node, CompilerContextInterface $compilerContext): Node|null
     {
         if (!$node instanceof DocumentNode) {
             return $node;

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

@@ -13,7 +13,7 @@
 
 namespace phpDocumentor\Guides\Compiler\NodeTransformers;
 
-use phpDocumentor\Guides\Compiler\CompilerContext;
+use phpDocumentor\Guides\Compiler\CompilerContextInterface;
 use phpDocumentor\Guides\Compiler\NodeTransformer;
 use phpDocumentor\Guides\Meta\FootnoteTarget;
 use phpDocumentor\Guides\Nodes\FootnoteNode;
@@ -22,7 +22,7 @@
 /** @implements NodeTransformer<Node> */
 final class FootNodeNamedTransformer implements NodeTransformer
 {
-    public function enterNode(Node $node, CompilerContext $compilerContext): Node
+    public function enterNode(Node $node, CompilerContextInterface $compilerContext): Node
     {
         if ($node instanceof FootnoteNode && $this->supports($node)) {
             $number = $compilerContext->getDocumentNode()->addFootnoteTarget(new FootnoteTarget(
@@ -37,7 +37,7 @@ public function enterNode(Node $node, CompilerContext $compilerContext): Node
         return $node;
     }
 
-    public function leaveNode(Node $node, CompilerContext $compilerContext): Node|null
+    public function leaveNode(Node $node, CompilerContextInterface $compilerContext): Node|null
     {
         return $node;
     }

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

@@ -13,7 +13,7 @@
 
 namespace phpDocumentor\Guides\Compiler\NodeTransformers;
 
-use phpDocumentor\Guides\Compiler\CompilerContext;
+use phpDocumentor\Guides\Compiler\CompilerContextInterface;
 use phpDocumentor\Guides\Compiler\NodeTransformer;
 use phpDocumentor\Guides\Meta\FootnoteTarget;
 use phpDocumentor\Guides\Nodes\FootnoteNode;
@@ -22,7 +22,7 @@
 /** @implements NodeTransformer<Node> */
 final class FootNodeNumberedTransformer implements NodeTransformer
 {
-    public function enterNode(Node $node, CompilerContext $compilerContext): Node
+    public function enterNode(Node $node, CompilerContextInterface $compilerContext): Node
     {
         if ($node instanceof FootnoteNode && $this->supports($node)) {
             $compilerContext->getDocumentNode()->addFootnoteTarget(new FootnoteTarget(
@@ -36,7 +36,7 @@ public function enterNode(Node $node, CompilerContext $compilerContext): Node
         return $node;
     }
 
-    public function leaveNode(Node $node, CompilerContext $compilerContext): Node|null
+    public function leaveNode(Node $node, CompilerContextInterface $compilerContext): Node|null
     {
         return $node;
     }

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

@@ -13,15 +13,15 @@
 
 namespace phpDocumentor\Guides\Compiler\NodeTransformers;
 
-use phpDocumentor\Guides\Compiler\CompilerContext;
+use phpDocumentor\Guides\Compiler\CompilerContextInterface;
 use phpDocumentor\Guides\Compiler\NodeTransformer;
 use phpDocumentor\Guides\Nodes\Inline\FootnoteInlineNode;
 use phpDocumentor\Guides\Nodes\Node;
 
 /** @implements NodeTransformer<Node> */
 final class FootnoteInlineNodeTransformer implements NodeTransformer
 {
-    public function enterNode(Node $node, CompilerContext $compilerContext): Node
+    public function enterNode(Node $node, CompilerContextInterface $compilerContext): Node
     {
         if ($node instanceof FootnoteInlineNode) {
             if ($node->getNumber() > 0) {
@@ -38,7 +38,7 @@ public function enterNode(Node $node, CompilerContext $compilerContext): Node
         return $node;
     }
 
-    public function leaveNode(Node $node, CompilerContext $compilerContext): Node|null
+    public function leaveNode(Node $node, CompilerContextInterface $compilerContext): Node|null
     {
         return $node;
     }

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

@@ -13,7 +13,7 @@
 
 namespace phpDocumentor\Guides\Compiler\NodeTransformers;
 
-use phpDocumentor\Guides\Compiler\CompilerContext;
+use phpDocumentor\Guides\Compiler\CompilerContextInterface;
 use phpDocumentor\Guides\Compiler\NodeTransformer;
 use phpDocumentor\Guides\Nodes\ListItemNode;
 use phpDocumentor\Guides\Nodes\ListNode;
@@ -30,12 +30,12 @@ public function __construct(
     ) {
     }
 
-    public function enterNode(Node $node, CompilerContext $compilerContext): Node
+    public function enterNode(Node $node, CompilerContextInterface $compilerContext): Node
     {
         return $node;
     }
 
-    public function leaveNode(Node $node, CompilerContext $compilerContext): Node|null
+    public function leaveNode(Node $node, CompilerContextInterface $compilerContext): Node|null
     {
         assert($node instanceof ListNode);
         foreach ($node->getChildren() as $listItemNode) {

packages/guides/src/Compiler/NodeTransformers/MenuNodeTransformers/AbstractMenuEntryNodeTransformer.php

@@ -14,7 +14,7 @@
 namespace phpDocumentor\Guides\Compiler\NodeTransformers\MenuNodeTransformers;
 
 use Exception;
-use phpDocumentor\Guides\Compiler\CompilerContext;
+use phpDocumentor\Guides\Compiler\CompilerContextInterface;
 use phpDocumentor\Guides\Compiler\NodeTransformer;
 use phpDocumentor\Guides\Nodes\Menu\MenuEntryNode;
 use phpDocumentor\Guides\Nodes\Menu\MenuNode;
@@ -32,13 +32,13 @@ public function __construct(
     ) {
     }
 
-    final public function enterNode(Node $node, CompilerContext $compilerContext): MenuEntryNode
+    final public function enterNode(Node $node, CompilerContextInterface $compilerContext): MenuEntryNode
     {
         return $node;
     }
 
     /** @param MenuEntryNode $node */
-    final public function leaveNode(Node $node, CompilerContext $compilerContext): MenuEntryNode|null
+    final public function leaveNode(Node $node, CompilerContextInterface $compilerContext): MenuEntryNode|null
     {
         assert($node instanceof MenuEntryNode);
         $currentMenuShaddow = $compilerContext->getShadowTree()->getParent();
@@ -70,5 +70,5 @@ final public function leaveNode(Node $node, CompilerContext $compilerContext): M
     }
 
     /** @return list<MenuEntryNode> */
-    abstract protected function handleMenuEntry(MenuNode $currentMenu, MenuEntryNode $entryNode, CompilerContext $compilerContext): array;
+    abstract protected function handleMenuEntry(MenuNode $currentMenu, MenuEntryNode $entryNode, CompilerContextInterface $compilerContext): array;
 }

packages/guides/src/Compiler/NodeTransformers/MenuNodeTransformers/ContentsMenuEntryNodeTransformer.php

@@ -13,7 +13,7 @@
 
 namespace phpDocumentor\Guides\Compiler\NodeTransformers\MenuNodeTransformers;
 
-use phpDocumentor\Guides\Compiler\CompilerContext;
+use phpDocumentor\Guides\Compiler\CompilerContextInterface;
 use phpDocumentor\Guides\Nodes\DocumentTree\SectionEntryNode;
 use phpDocumentor\Guides\Nodes\Menu\ContentMenuNode;
 use phpDocumentor\Guides\Nodes\Menu\MenuEntryNode;
@@ -38,7 +38,7 @@ public function supports(Node $node): bool
     }
 
     /** @return list<MenuEntryNode> */
-    protected function handleMenuEntry(MenuNode $currentMenu, MenuEntryNode $entryNode, CompilerContext $compilerContext): array
+    protected function handleMenuEntry(MenuNode $currentMenu, MenuEntryNode $entryNode, CompilerContextInterface $compilerContext): array
     {
         if (!$currentMenu instanceof ContentMenuNode) {
             return [$entryNode];

packages/guides/src/Compiler/NodeTransformers/MenuNodeTransformers/ExternalMenuEntryNodeTransformer.php

@@ -13,7 +13,7 @@
 
 namespace phpDocumentor\Guides\Compiler\NodeTransformers\MenuNodeTransformers;
 
-use phpDocumentor\Guides\Compiler\CompilerContext;
+use phpDocumentor\Guides\Compiler\CompilerContextInterface;
 use phpDocumentor\Guides\Nodes\DocumentTree\ExternalEntryNode;
 use phpDocumentor\Guides\Nodes\Menu\ExternalMenuEntryNode;
 use phpDocumentor\Guides\Nodes\Menu\MenuEntryNode;
@@ -42,7 +42,7 @@ public function supports(Node $node): bool
     }
 
     /** @return list<MenuEntryNode> */
-    protected function handleMenuEntry(MenuNode $currentMenu, MenuEntryNode $entryNode, CompilerContext $compilerContext): array
+    protected function handleMenuEntry(MenuNode $currentMenu, MenuEntryNode $entryNode, CompilerContextInterface $compilerContext): array
     {
         assert($entryNode instanceof ExternalMenuEntryNode);