phpDocumentor · linawolf · Nov 25, 2023 · Nov 25, 2023
diff --git a/packages/guides/src/Interlink/InventoryLoader.php b/packages/guides/src/Interlink/InventoryLoader.php
@@ -4,12 +4,16 @@
 
 namespace phpDocumentor\Guides\Interlink;
 
+use Psr\Log\LoggerInterface;
+use Symfony\Component\HttpClient\Exception\ClientException;
+
 use function is_array;
 use function strval;
 
 final class InventoryLoader
 {
     public function __construct(
+        private readonly LoggerInterface $logger,
         private readonly JsonLoader $jsonLoader,
         private readonly string $pathToJson = 'objects.inv.json',
     ) {
@@ -43,8 +47,12 @@ public function loadInventory(Inventory $inventory): void
             return;
         }
 
-        $json = $this->jsonLoader->loadJsonFromUrl($inventory->getBaseUrl() . $this->pathToJson);
+        try {
+            $json = $this->jsonLoader->loadJsonFromUrl($inventory->getBaseUrl() . $this->pathToJson);
 
-        $this->loadInventoryFromJson($inventory, $json);
+            $this->loadInventoryFromJson($inventory, $json);
+        } catch (ClientException $exception) {
+            $this->logger->warning('Interlink inventory not found: ' . $exception->getMessage());
+        }
     }
 }
diff --git a/packages/guides/src/Nodes/Inline/AbstractLinkInlineNode.php b/packages/guides/src/Nodes/Inline/AbstractLinkInlineNode.php
@@ -27,4 +27,14 @@ public function getUrl(): string
     {
         return $this->url;
     }
+
+    /** @return array<string, string> */
+    public function getDebugInformation(): array
+    {
+        return [
+            'type' => $this->getType(),
+            'targetReference' => $this->getTargetReference(),
+            'value' => $this->getValue(),
+        ];
+    }
 }
diff --git a/packages/guides/src/Nodes/Inline/DocReferenceNode.php b/packages/guides/src/Nodes/Inline/DocReferenceNode.php
@@ -4,6 +4,8 @@
 
 namespace phpDocumentor\Guides\Nodes\Inline;
 
+use function array_merge;
+
 /**
  * Represents a link to document
  *
@@ -30,4 +32,12 @@ public function getInterlinkDomain(): string
     {
         return $this->interlinkDomain;
     }
+
+    /** @return array<string, string> */
+    public function getDebugInformation(): array
+    {
+        return array_merge(parent::getDebugInformation(), [
+            'interlinkDomain' => $this->getInterlinkDomain(),
+        ]);
+    }
 }
diff --git a/packages/guides/src/Nodes/Inline/LinkInlineNode.php b/packages/guides/src/Nodes/Inline/LinkInlineNode.php
@@ -13,4 +13,7 @@ public function getTargetReference(): string;
     public function setUrl(string $url): void;
 
     public function getUrl(): string;
+
+    /** @return array<string, string> */
+    public function getDebugInformation(): array;
 }
diff --git a/packages/guides/src/Nodes/Inline/ReferenceNode.php b/packages/guides/src/Nodes/Inline/ReferenceNode.php
@@ -6,6 +6,8 @@
 
 use phpDocumentor\Guides\Nodes\SectionNode;
 
+use function array_merge;
+
 /**
  * CrossReferences are references outside a document. As parsing is file based normal references are in document,
  * refering to other documents.
@@ -39,4 +41,13 @@ public function getInterlinkDomain(): string
     {
         return $this->interlinkDomain;
     }
+
+    /** @return array<string, string> */
+    public function getDebugInformation(): array
+    {
+        return array_merge(parent::getDebugInformation(), [
+            'linkType' => $this->getLinkType(),
+            'interlinkDomain' => $this->getInterlinkDomain(),
+        ]);
+    }
 }
diff --git a/packages/guides/src/ReferenceResolvers/DocReferenceResolver.php b/packages/guides/src/ReferenceResolvers/DocReferenceResolver.php
@@ -8,6 +8,10 @@
 use phpDocumentor\Guides\Nodes\Inline\LinkInlineNode;
 use phpDocumentor\Guides\RenderContext;
 use phpDocumentor\Guides\Renderer\UrlGenerator\UrlGeneratorInterface;
+use Psr\Log\LoggerInterface;
+
+use function array_merge;
+use function sprintf;
 
 class DocReferenceResolver implements ReferenceResolver
 {
@@ -16,6 +20,7 @@ class DocReferenceResolver implements ReferenceResolver
     public function __construct(
         private readonly UrlGeneratorInterface $urlGenerator,
         private readonly DocumentNameResolverInterface $documentNameResolver,
+        private readonly LoggerInterface $logger,
     ) {
     }
 
@@ -29,10 +34,19 @@ public function resolve(LinkInlineNode $node, RenderContext $renderContext): boo
             return false;
         }
 
-        $document = $renderContext->getProjectNode()->findDocumentEntry(
-            $this->documentNameResolver->canonicalUrl($renderContext->getDirName(), $node->getTargetReference()),
-        );
+        $canonicalDocumentName = $this->documentNameResolver->canonicalUrl($renderContext->getDirName(), $node->getTargetReference());
+
+        $document = $renderContext->getProjectNode()->findDocumentEntry($canonicalDocumentName);
         if ($document === null) {
+            $this->logger->warning(
+                sprintf(
+                    'Document with name "%s" not found, required in file "%s".',
+                    $canonicalDocumentName,
+                    $renderContext->getCurrentFileName(),
+                ),
+                array_merge($renderContext->getLoggerInformation(), $node->getDebugInformation()),
+            );
+
             return false;
         }
 

diff --git a/packages/guides/src/ReferenceResolvers/InterlinkReferenceResolver.php b/packages/guides/src/ReferenceResolvers/InterlinkReferenceResolver.php
@@ -9,13 +9,19 @@
 use phpDocumentor\Guides\Nodes\Inline\DocReferenceNode;
 use phpDocumentor\Guides\Nodes\Inline\LinkInlineNode;
 use phpDocumentor\Guides\RenderContext;
+use Psr\Log\LoggerInterface;
+
+use function array_merge;
+use function sprintf;
 
 class InterlinkReferenceResolver implements ReferenceResolver
 {
     public final const PRIORITY = 50;
 
-    public function __construct(private readonly InventoryRepository $inventoryRepository)
-    {
+    public function __construct(
+        private readonly InventoryRepository $inventoryRepository,
+        private readonly LoggerInterface $logger,
+    ) {
     }
 
     public function resolve(LinkInlineNode $node, RenderContext $renderContext): bool
@@ -27,17 +33,47 @@ public function resolve(LinkInlineNode $node, RenderContext $renderContext): boo
         $domain = $node->getInterlinkDomain();
         $target = $node->getTargetReference();
         if (!$this->inventoryRepository->hasInventory($domain)) {
+            $this->logger->warning(
+                sprintf(
+                    'Inventory with name "%s" could not be resolved in file "%s". ',
+                    $domain,
+                    $renderContext->getCurrentFileName(),
+                ),
+                array_merge($renderContext->getLoggerInformation(), $node->getDebugInformation()),
+            );
+
             return false;
         }
 
         $inventory = $this->inventoryRepository->getInventory($domain);
         $group = $node instanceof DocReferenceNode ? 'std:doc' : 'std:label';
         if (!$inventory->hasInventoryGroup($group)) {
+            $this->logger->warning(
+                sprintf(
+                    'Inventory with name "%s" does not contain group %s, required in file "%s". ',
+                    $domain,
+                    $group,
+                    $renderContext->getCurrentFileName(),
+                ),
+                array_merge($renderContext->getLoggerInformation(), $node->getDebugInformation()),
+            );
+
             return false;
         }
 
         $inventoryGroup = $inventory->getInventory($group);
         if (!$inventoryGroup->hasLink($target)) {
+            $this->logger->warning(
+                sprintf(
+                    'Link with name "%s:%s" not found in group "%s", required in file "%s".',
+                    $domain,
+                    $target,
+                    $group,
+                    $renderContext->getCurrentFileName(),
+                ),
+                array_merge($renderContext->getLoggerInformation(), $node->getDebugInformation()),
+            );
+
             return false;
         }
 

diff --git a/packages/guides/tests/unit/Interlink/InventoryLoaderTest.php b/packages/guides/tests/unit/Interlink/InventoryLoaderTest.php
@@ -6,6 +6,7 @@
 
 use PHPUnit\Framework\MockObject\MockObject;
 use PHPUnit\Framework\TestCase;
+use Psr\Log\NullLogger;
 
 use function count;
 use function file_get_contents;
@@ -25,7 +26,10 @@ final class InventoryLoaderTest extends TestCase
     protected function setUp(): void
     {
         $this->jsonLoader = $this->createMock(JsonLoader::class);
-        $this->inventoryLoader = new InventoryLoader($this->jsonLoader);
+        $this->inventoryLoader = new InventoryLoader(
+            self::createStub(NullLogger::class),
+            $this->jsonLoader,
+        );
         $this->inventoryRepository = new InventoryRepository($this->inventoryLoader, []);
         $jsonString = file_get_contents(__DIR__ . '/input/objects.inv.json');
         assertIsString($jsonString);

diff --git a/tests/Integration/tests/body-elements/line-blocks/expected/index.html b/tests/Integration/tests/body-elements/line-blocks/expected/index.html
@@ -1,4 +1,3 @@
-
 <!-- content start -->
     <div class="section" id="line-blocks">
     <h1>Line Blocks</h1>

diff --git a/tests/Integration/tests/interlink/interlink-inventory-not-found/expected/Index.html b/tests/Integration/tests/interlink/interlink-inventory-not-found/expected/Index.html
@@ -0,0 +1,9 @@
+<!-- content start -->
+    <div class="section" id="document-title">
+    <h1>Document Title</h1>
+
+            <p>Lorem Ipsum Dolor.</p>
+            <p>See the TYPO3 documentation!</p>
+    </div>
+
+<!-- content end -->
diff --git a/tests/Integration/tests/interlink/interlink-inventory-not-found/expected/logs/warning.log b/tests/Integration/tests/interlink/interlink-inventory-not-found/expected/logs/warning.log
@@ -0,0 +1 @@
+app.WARNING: Interlink inventory not found
diff --git a/tests/Integration/tests/interlink/interlink-inventory-not-found/input/Index.rst b/tests/Integration/tests/interlink/interlink-inventory-not-found/input/Index.rst
@@ -0,0 +1,7 @@
+==============
+Document Title
+==============
+
+Lorem Ipsum Dolor.
+
+See the :doc:`TYPO3 documentation <t3coreapi:Index>`!
diff --git a/tests/Integration/tests/interlink/interlink-inventory-not-found/input/guides.xml b/tests/Integration/tests/interlink/interlink-inventory-not-found/input/guides.xml
@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<guides xmlns="https://www.phpdoc.org/guides"
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xsi:schemaLocation="https://www.phpdoc.org/guides packages/guides-cli/resources/schema/guides.xsd"
+>
+    <project title="My Project" version="main (development)" />
+    <inventory id="t3coreapi" url="https://docs.typo3.org/not-found/" />
+</guides>
diff --git a/tests/Integration/tests/interlink/interlink-inventory-page-unknown/expected/Index.html b/tests/Integration/tests/interlink/interlink-inventory-page-unknown/expected/Index.html
@@ -0,0 +1,9 @@
+<!-- content start -->
+    <div class="section" id="document-title">
+    <h1>Document Title</h1>
+
+            <p>Lorem Ipsum Dolor.</p>
+            <p>See the TYPO3 documentation!</p>
+    </div>
+
+<!-- content end -->
diff --git a/tests/Integration/tests/interlink/interlink-inventory-page-unknown/expected/logs/warning.log b/tests/Integration/tests/interlink/interlink-inventory-page-unknown/expected/logs/warning.log
@@ -0,0 +1 @@
+app.WARNING: Link with name "t3coreapi:Unknown/Page" not found in group "std:doc", required in file "Index".
diff --git a/tests/Integration/tests/interlink/interlink-inventory-page-unknown/input/Index.rst b/tests/Integration/tests/interlink/interlink-inventory-page-unknown/input/Index.rst
@@ -0,0 +1,7 @@
+==============
+Document Title
+==============
+
+Lorem Ipsum Dolor.
+
+See the :doc:`TYPO3 documentation <t3coreapi:Unknown/Page>`!
diff --git a/tests/Integration/tests/interlink/interlink-inventory-page-unknown/input/guides.xml b/tests/Integration/tests/interlink/interlink-inventory-page-unknown/input/guides.xml
@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<guides xmlns="https://www.phpdoc.org/guides"
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xsi:schemaLocation="https://www.phpdoc.org/guides packages/guides-cli/resources/schema/guides.xsd"
+>
+    <project title="My Project" version="main (development)" />
+    <inventory id="t3coreapi" url="https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/" />
+</guides>
diff --git a/tests/Integration/tests/interlink/interlink-inventory-reference-unknown/expected/Index.html b/tests/Integration/tests/interlink/interlink-inventory-reference-unknown/expected/Index.html
@@ -0,0 +1,9 @@
+<!-- content start -->
+    <div class="section" id="document-title">
+    <h1>Document Title</h1>
+
+            <p>Lorem Ipsum Dolor.</p>
+            <p>See the TYPO3 documentation!</p>
+    </div>
+
+<!-- content end -->
diff --git a/...tegration/tests/interlink/interlink-inventory-reference-unknown/expected/logs/warning.log b/...tegration/tests/interlink/interlink-inventory-reference-unknown/expected/logs/warning.log
@@ -0,0 +1 @@
+app.WARNING: Link with name "t3coreapi:unknown" not found in group "std:label", required in file "Index".
diff --git a/...tegration/tests/interlink/interlink-inventory-reference-unknown/input/Index.rst b/...tegration/tests/interlink/interlink-inventory-reference-unknown/input/Index.rst
@@ -0,0 +1,7 @@
+==============
+Document Title
+==============
+
+Lorem Ipsum Dolor.
+
+See the :ref:`TYPO3 documentation <t3coreapi:Unknown>`!
diff --git a/tests/Integration/tests/interlink/interlink-inventory-reference-unknown/input/guides.xml b/tests/Integration/tests/interlink/interlink-inventory-reference-unknown/input/guides.xml
@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<guides xmlns="https://www.phpdoc.org/guides"
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xsi:schemaLocation="https://www.phpdoc.org/guides packages/guides-cli/resources/schema/guides.xsd"
+>
+    <project title="My Project" version="main (development)" />
+    <inventory id="t3coreapi" url="https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/" />
+</guides>
diff --git a/tests/Integration/tests/interlink/interlink-inventory-unknown/expected/Index.html b/tests/Integration/tests/interlink/interlink-inventory-unknown/expected/Index.html
@@ -0,0 +1,9 @@
+<!-- content start -->
+    <div class="section" id="document-title">
+    <h1>Document Title</h1>
+
+            <p>Lorem Ipsum Dolor.</p>
+            <p>See the TYPO3 documentation!</p>
+    </div>
+
+<!-- content end -->
diff --git a/tests/Integration/tests/interlink/interlink-inventory-unknown/expected/logs/warning.log b/tests/Integration/tests/interlink/interlink-inventory-unknown/expected/logs/warning.log
@@ -0,0 +1 @@
+app.WARNING: Inventory with name "unknowninventory" could not be resolved in file "Index".  {"rst-file":"Index","type":"doc","targetReference":"Index","value":"TYPO3 documentation","interlinkDomain":"unknowninventory"} []
diff --git a/tests/Integration/tests/interlink/interlink-inventory-unknown/input/Index.rst b/tests/Integration/tests/interlink/interlink-inventory-unknown/input/Index.rst
@@ -0,0 +1,7 @@
+==============
+Document Title
+==============
+
+Lorem Ipsum Dolor.
+
+See the :doc:`TYPO3 documentation <unknowninventory:Index>`!
diff --git a/tests/Integration/tests/interlink/interlink-inventory-unknown/input/guides.xml b/tests/Integration/tests/interlink/interlink-inventory-unknown/input/guides.xml
@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<guides xmlns="https://www.phpdoc.org/guides"
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xsi:schemaLocation="https://www.phpdoc.org/guides packages/guides-cli/resources/schema/guides.xsd"
+>
+    <project title="My Project" version="main (development)" />
+    <inventory id="t3coreapi" url="https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/" />
+</guides>
diff --git a/tests/Integration/tests/navigation/reference-not-found/expected/index.html b/tests/Integration/tests/navigation/reference-not-found/expected/index.html
@@ -0,0 +1,20 @@
+<!-- content start -->
+    <div class="section" id="overview">
+    <h1>Overview</h1>
+
+            <a id="RST Overview"></a>
+            <p>RST Overview content</p>
+    </div>
+
+<div class="section" id="overview-1">
+    <h1>Overview</h1>
+
+            <a id="Other Overview"></a>
+            <p>Other Overview content</p>
+            <p>This is a link to the RST Overview: alternative</p>
+            <p>This is a link to the Other Overview: </p>
+            <p>This is a link to
+This is a link to with alternative text alternative</p>
+    </div>
+
+<!-- content end -->
diff --git a/tests/Integration/tests/navigation/reference-not-found/expected/logs/warning.log b/tests/Integration/tests/navigation/reference-not-found/expected/logs/warning.log
@@ -0,0 +1,4 @@
+app.WARNING: Reference rst-overview-xx could not be resolved in index
+app.WARNING: Reference other-overview-yy could not be resolved in index
+app.WARNING: Document with name "page-xxx" not found, required in file "index".
+app.WARNING: Document with name "page-yyy" not found, required in file "index".
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		app.WARNING: Link with name "t3coreapi:Unknown/Page" not found in group "std:doc", required in file "Index".
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		app.WARNING: Inventory with name "unknowninventory" could not be resolved in file "Index". {"rst-file":"Index","type":"doc","targetReference":"Index","value":"TYPO3 documentation","interlinkDomain":"unknowninventory"} []