!!![TASK] Remove Exceptions and use message system for inventories

Author: linawolf

packages/guides/src/Interlink/DefaultInventoryRepository.php

@@ -4,11 +4,15 @@
 
 namespace phpDocumentor\Guides\Interlink;
 
-use phpDocumentor\Guides\Interlink\Exception\InterlinkInventoryNotFound;
-use phpDocumentor\Guides\Interlink\Exception\InterlinkNotFound;
+use phpDocumentor\Guides\Nodes\Inline\CrossReferenceNode;
 use phpDocumentor\Guides\ReferenceResolvers\AnchorNormalizer;
+use phpDocumentor\Guides\ReferenceResolvers\Message;
+use phpDocumentor\Guides\ReferenceResolvers\Messages;
+use phpDocumentor\Guides\RenderContext;
 
 use function array_key_exists;
+use function array_merge;
+use function sprintf;
 
 final class DefaultInventoryRepository implements InventoryRepository
 {
@@ -26,13 +30,12 @@ public function __construct(
         }
     }
 
-    /** @throws InterlinkNotFound */
-    public function getLink(string $inventoryKey, string $groupKey, string $linkKey): InventoryLink
+    public function getLink(CrossReferenceNode $node, RenderContext $renderContext, Messages $messages): InventoryLink|null
     {
-        $inventory = $this->getInventory($inventoryKey);
-        $group = $inventory->getGroup($groupKey);
+        $inventory = $this->getInventory($node, $renderContext, $messages);
+        $group = $inventory?->getGroup($node, $renderContext, $messages);
 
-        return $group->getLink($linkKey);
+        return $group?->getLink($node, $renderContext, $messages);
     }
 
     public function hasInventory(string $key): bool
@@ -42,12 +45,21 @@ public function hasInventory(string $key): bool
         return array_key_exists($reducedKey, $this->inventories);
     }
 
-    /** @throws InterlinkInventoryNotFound */
-    public function getInventory(string $key): Inventory
+    public function getInventory(CrossReferenceNode $node, RenderContext $renderContext, Messages $messages): Inventory|null
     {
-        $reducedKey = $this->anchorNormalizer->reduceAnchor($key);
+        $reducedKey = $this->anchorNormalizer->reduceAnchor($node->getInterlinkDomain());
         if (!$this->hasInventory($reducedKey)) {
-            throw new InterlinkInventoryNotFound('Inventory with key ' . $reducedKey . ' not found. ', 1_671_398_986);
+            $messages->addWarning(
+                new Message(
+                    sprintf(
+                        'Inventory with key %s not found. ',
+                        $node->getInterlinkDomain(),
+                    ),
+                    array_merge($renderContext->getLoggerInformation(), $node->getDebugInformation()),
+                ),
+            );
+
+            return null;
         }
 
         $this->inventoryLoader->loadInventory($this->inventories[$reducedKey]);

packages/guides/src/Interlink/Exception/InterlinkGroupNotFound.php

@@ -4,11 +4,14 @@
 
 namespace phpDocumentor\Guides\Interlink;
 
-use phpDocumentor\Guides\Interlink\Exception\InterlinkGroupNotFound;
-use phpDocumentor\Guides\Interlink\Exception\InterlinkNotFound;
+use phpDocumentor\Guides\Nodes\Inline\CrossReferenceNode;
 use phpDocumentor\Guides\ReferenceResolvers\AnchorNormalizer;
+use phpDocumentor\Guides\ReferenceResolvers\Message;
+use phpDocumentor\Guides\ReferenceResolvers\Messages;
+use phpDocumentor\Guides\RenderContext;
 
 use function array_key_exists;
+use function array_merge;
 use function sprintf;
 
 final class Inventory
@@ -39,25 +42,26 @@ public function getGroups(): array
         return $this->groups;
     }
 
-    /** @throws InterlinkNotFound */
-    public function getGroup(string $key): InventoryGroup
+    public function getGroup(CrossReferenceNode $node, RenderContext $renderContext, Messages $messages): InventoryGroup|null
     {
-        $reducedKey = $this->anchorNormalizer->reduceAnchor($key);
+        $reducedKey = $this->anchorNormalizer->reduceAnchor($node->getInterlinkGroup());
         if (!$this->hasGroup($reducedKey)) {
-            throw new InterlinkGroupNotFound(
-                sprintf('Inventory group with key "%s" (%s) not found. ', $key, $reducedKey),
-                1_671_398_986,
-            );
+            $messages->addWarning(new Message(
+                sprintf(
+                    'Inventory group with key "%s" (%s) not found in inventory %s. ',
+                    $node->getInterlinkGroup(),
+                    $reducedKey,
+                    $this->baseUrl,
+                ),
+                array_merge($renderContext->getLoggerInformation(), $node->getDebugInformation()),
+            ));
+
+            return null;
         }
 
         return $this->groups[$reducedKey];
     }
 
-    public function getLink(string $groupKey, string $key): InventoryLink
-    {
-        return $this->getGroup($groupKey)->getLink($key);
-    }
-
     public function hasGroup(string $key): bool
     {
         $reducedKey = $this->anchorNormalizer->reduceAnchor($key);

packages/guides/src/Interlink/Exception/InterlinkInventoryNotFound.php

@@ -4,11 +4,14 @@
 
 namespace phpDocumentor\Guides\Interlink;
 
-use phpDocumentor\Guides\Interlink\Exception\InterlinkNotFound;
-use phpDocumentor\Guides\Interlink\Exception\InterlinkTargetNotFound;
+use phpDocumentor\Guides\Nodes\Inline\CrossReferenceNode;
 use phpDocumentor\Guides\ReferenceResolvers\AnchorNormalizer;
+use phpDocumentor\Guides\ReferenceResolvers\Message;
+use phpDocumentor\Guides\ReferenceResolvers\Messages;
+use phpDocumentor\Guides\RenderContext;
 
 use function array_key_exists;
+use function array_merge;
 use function sprintf;
 
 final class InventoryGroup
@@ -33,12 +36,23 @@ public function hasLink(string $key): bool
         return array_key_exists($reducedKey, $this->links);
     }
 
-    /** @throws InterlinkNotFound */
-    public function getLink(string $key): InventoryLink
+    public function getLink(CrossReferenceNode $node, RenderContext $renderContext, Messages $messages): InventoryLink|null
     {
-        $reducedKey = $this->anchorNormalizer->reduceAnchor($key);
+        $reducedKey = $this->anchorNormalizer->reduceAnchor($node->getTargetReference());
         if (!array_key_exists($reducedKey, $this->links)) {
-            throw new InterlinkTargetNotFound(sprintf('Inventory link with key "%s" (%s) not found. ', $key, $reducedKey), 1_671_398_986);
+            $messages->addWarning(
+                new Message(
+                    sprintf(
+                        'Inventory link with key "%s:%s" (%s) not found. ',
+                        $node->getInterlinkDomain(),
+                        $node->getTargetReference(),
+                        $reducedKey,
+                    ),
+                    array_merge($renderContext->getLoggerInformation(), $node->getDebugInformation()),
+                ),
+            );
+
+            return null;
         }
 
         return $this->links[$reducedKey];

packages/guides/src/Interlink/Exception/InterlinkNotFound.php

@@ -4,14 +4,15 @@
 
 namespace phpDocumentor\Guides\Interlink;
 
-use phpDocumentor\Guides\Interlink\Exception\InterlinkNotFound;
+use phpDocumentor\Guides\Nodes\Inline\CrossReferenceNode;
+use phpDocumentor\Guides\ReferenceResolvers\Messages;
+use phpDocumentor\Guides\RenderContext;
 
 interface InventoryRepository
 {
-    /** @throws InterlinkNotFound */
-    public function getLink(string $inventoryKey, string $groupKey, string $linkKey): InventoryLink;
+    public function getLink(CrossReferenceNode $node, RenderContext $renderContext, Messages $messages): InventoryLink|null;
 
     public function hasInventory(string $key): bool;
 
-    public function getInventory(string $key): Inventory;
+    public function getInventory(CrossReferenceNode $node, RenderContext $renderContext, Messages $messages): Inventory|null;
 }

packages/guides/src/Interlink/Exception/InterlinkTargetNotFound.php

@@ -14,4 +14,6 @@
 interface CrossReferenceNode extends LinkInlineNode
 {
     public function getInterlinkDomain(): string;
+
+    public function getInterlinkGroup(): string;
 }

packages/guides/src/Interlink/Inventory.php

@@ -40,4 +40,9 @@ public function getDebugInformation(): array
             'interlinkDomain' => $this->getInterlinkDomain(),
         ]);
     }
+
+    public function getInterlinkGroup(): string
+    {
+        return 'std:doc';
+    }
 }