[FEATURE] Report the line of unresolved references

Warnings about references that cannot be resolved only name the file,
which makes them hard to find in large documents. Links are resolved
long after parsing, when the line is no longer known, and text roles
only receive the DocumentParserContext, which has no line.

Link nodes now carry their source location, like DirectiveNode does
since 00e6fab, and the reference resolvers include it in their
warnings. It is set centrally by the InlineParser for every link an
inline rule or text role returns, so rules and text roles added by
extensions are covered without changes, and extensions like
render-guides can use it for their own link warnings.

Signed-off-by: linawolf
Assisted-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

Author: linawolf

packages/guides-restructured-text/src/RestructuredText/Directives/ImageDirective.php

@@ -15,9 +15,9 @@
 
 use phpDocumentor\Guides\Compiler\CompilerContextInterface;
 use phpDocumentor\Guides\Nodes\ImageNode;
+use phpDocumentor\Guides\Nodes\Inline\AbstractLinkInlineNode;
 use phpDocumentor\Guides\Nodes\Inline\DocReferenceNode;
 use phpDocumentor\Guides\Nodes\Inline\HyperLinkNode;
-use phpDocumentor\Guides\Nodes\Inline\LinkInlineNode;
 use phpDocumentor\Guides\Nodes\Inline\ReferenceNode;
 use phpDocumentor\Guides\Nodes\Node;
 use phpDocumentor\Guides\ReferenceResolvers\DocumentNameResolverInterface;
@@ -70,17 +70,15 @@ public function createNode(DirectiveNode $directiveNode, CompilerContextInterfac
             ),
         );
         if ($directive->hasOption('target')) {
-            $node->setTarget(
-                $this->resolveLinkTarget(
-                    $directive->getOptionString('target'),
-                ),
-            );
+            $target = $this->resolveLinkTarget($directive->getOptionString('target'));
+            $target->setLoggerInformation($directiveNode->getSourceLocation()->toLoggerInformation());
+            $node->setTarget($target);
         }
 
         return $node;
     }
 
-    private function resolveLinkTarget(string $targetReference): LinkInlineNode
+    private function resolveLinkTarget(string $targetReference): AbstractLinkInlineNode
     {
         if (filter_var($targetReference, FILTER_VALIDATE_EMAIL)) {
             return new HyperLinkNode([], $targetReference);

packages/guides-restructured-text/src/RestructuredText/Parser/InlineParser.php

@@ -14,13 +14,15 @@
 namespace phpDocumentor\Guides\RestructuredText\Parser;
 
 use Exception;
+use phpDocumentor\Guides\Nodes\Inline\AbstractLinkInlineNode;
 use phpDocumentor\Guides\Nodes\Inline\PlainTextInlineNode;
 use phpDocumentor\Guides\Nodes\InlineCompoundNode;
 use phpDocumentor\Guides\RestructuredText\Parser\Productions\InlineRules\CachableInlineRule;
 use phpDocumentor\Guides\RestructuredText\Parser\Productions\InlineRules\InlineRule;
 
 use function array_filter;
 use function array_key_exists;
+use function substr_count;
 use function usort;
 
 /** @internal */
@@ -48,15 +50,21 @@ public function __construct(
         }
     }
 
-    public function parse(string $content, BlockContext $blockContext): InlineCompoundNode
+    /**
+     * @param int|null $firstLineNumber Line in the source file $content starts on, defaults to the current line of
+     *                                  $blockContext
+     */
+    public function parse(string $content, BlockContext $blockContext, int|null $firstLineNumber = null): InlineCompoundNode
     {
+        $firstLineNumber ??= $blockContext->getCurrentLineNumber();
         $lexer = new InlineLexer($this->disableLegacyTilde);
         $lexer->setInput($content);
         $lexer->moveNext();
         $lexer->moveNext();
         $nodes = [];
         $previous = null;
         while ($lexer->token !== null) {
+            $position = $lexer->token->position;
             foreach ($this->rules as $inlineRule) {
                 $node = null;
                 if (array_key_exists($lexer->token->type ?? -1, $this->cache)) {
@@ -69,6 +77,12 @@ public function parse(string $content, BlockContext $blockContext): InlineCompou
                     continue;
                 }
 
+                if ($node instanceof AbstractLinkInlineNode && $node->getLoggerInformation() === []) {
+                    $loggerInformation = $blockContext->getDocumentParserContext()->getLoggerInformation();
+                    $loggerInformation['currentLineNumber'] = $firstLineNumber + substr_count($content, "\n", 0, $position);
+                    $node->setLoggerInformation($loggerInformation);
+                }
+
                 if ($previous instanceof PlainTextInlineNode && $node instanceof PlainTextInlineNode) {
                     $previous->append($node);
                 } else {

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

@@ -66,9 +66,10 @@ public function applies(BlockContext $blockContext): bool
     public function apply(BlockContext $blockContext, CompoundNode|null $on = null): CompoundNode|InlineCompoundNode
     {
         $documentIterator = $blockContext->getDocumentIterator();
+        $firstLineNumber = $blockContext->getCurrentLineNumber();
         $buffer = $this->collectContent($documentIterator);
 
-        $node = $this->inlineTokenParser->parse($buffer->getLinesString(), $blockContext);
+        $node = $this->inlineTokenParser->parse($buffer->getLinesString(), $blockContext, $firstLineNumber);
 
         if ($on !== null) {
             $on->setValue([$node]);

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

@@ -66,6 +66,7 @@ public function apply(BlockContext $blockContext, CompoundNode|null $on = null):
             $title = trim($documentIterator->current()); // Title with over and underlines may be indented
         }
 
+        $titleLineNumber = $blockContext->getCurrentLineNumber();
         $underlineLetter = $this->nextLineIsAnUnderline($documentIterator->current(), $documentIterator->getNextLine());
         if ($underlineLetter !== '') {
             if (($overlineLetter === '' || $overlineLetter === $underlineLetter)) {
@@ -82,7 +83,7 @@ public function apply(BlockContext $blockContext, CompoundNode|null $on = null):
         $level = $blockContext->getDocumentParserContext()->getLevel($overlineLetter, $underlineLetter);
 
         return new TitleNode(
-            $this->inlineTokenParser->parse($title, $blockContext),
+            $this->inlineTokenParser->parse($title, $blockContext, $titleLineNumber),
             $level,
             (new AsciiSlugger())->slug($title)->lower()->toString(),
         );

packages/guides-restructured-text/tests/unit/Parser/InlineTokenParserTest.php

@@ -13,6 +13,7 @@
 
 namespace phpDocumentor\Guides\RestructuredText\Parser;
 
+use phpDocumentor\Guides\Nodes\Inline\AbstractLinkInlineNode;
 use phpDocumentor\Guides\Nodes\Inline\CitationInlineNode;
 use phpDocumentor\Guides\Nodes\Inline\DocReferenceNode;
 use phpDocumentor\Guides\Nodes\Inline\EmphasisInlineNode;
@@ -95,9 +96,38 @@ public function setUp(): void
     public function testString(string $content, InlineCompoundNode $expected): void
     {
         $result = $this->inlineTokenParser->parse($content, new BlockContext($this->documentParserContext, ''));
+        // Link nodes also carry their source location, covered by testLinkLineNumbers()
+        foreach ($result->getChildren() as $child) {
+            if (!($child instanceof AbstractLinkInlineNode)) {
+                continue;
+            }
+
+            $child->setLoggerInformation([]);
+        }
+
         self::assertEquals($expected, $result);
     }
 
+    public function testLinkLineNumbers(): void
+    {
+        $result = $this->inlineTokenParser->parse(
+            "first line\nsecond :doc:`some/document` and\nthird myref_",
+            new BlockContext($this->documentParserContext, ''),
+            5,
+        );
+
+        $lineNumbers = [];
+        foreach ($result->getChildren() as $child) {
+            if (!($child instanceof AbstractLinkInlineNode)) {
+                continue;
+            }
+
+            $lineNumbers[$child->getTargetReference()] = $child->getLoggerInformation()['currentLineNumber'] ?? null;
+        }
+
+        self::assertSame(['some/document' => 6, 'myref' => 7], $lineNumbers);
+    }
+
     /** @return array<string, array<string | InlineCompoundNode>> */
     public static function inlineNodeProvider(): array
     {

packages/guides/src/Nodes/Inline/AbstractLinkInlineNode.php

@@ -26,6 +26,9 @@ abstract class AbstractLinkInlineNode extends InlineCompoundNode implements Link
 
     private string $url = '';
 
+    /** @var array<string, int|string> */
+    private array $loggerInformation = [];
+
     /** @param InlineNodeInterface[] $children */
     public function __construct(
         private readonly string $type,
@@ -78,6 +81,23 @@ public function getDebugInformation(): array
         ];
     }
 
+    /**
+     * Source location (file, line) of the link, for warnings logged after
+     * parsing, like a reference that cannot be resolved.
+     *
+     * @param array<string, int|string> $loggerInformation
+     */
+    public function setLoggerInformation(array $loggerInformation): void
+    {
+        $this->loggerInformation = $loggerInformation;
+    }
+
+    /** @return array<string, int|string> */
+    public function getLoggerInformation(): array
+    {
+        return $this->loggerInformation;
+    }
+
     public function getType(): string
     {
         return $this->type;

packages/guides/src/ReferenceResolvers/ImageReferenceResolverPreRender.php

@@ -15,6 +15,7 @@
 
 use phpDocumentor\Guides\NodeRenderers\PreRenderers\PreNodeRenderer;
 use phpDocumentor\Guides\Nodes\ImageNode;
+use phpDocumentor\Guides\Nodes\Inline\AbstractLinkInlineNode;
 use phpDocumentor\Guides\Nodes\Node;
 use phpDocumentor\Guides\RenderContext;
 use Psr\Log\LoggerInterface;
@@ -53,7 +54,11 @@ public function execute(Node $node, RenderContext $renderContext): Node
                     $referenceLinkNode->getTargetReference(),
                     $renderContext->getCurrentFileName(),
                 ),
-                array_merge($renderContext->getLoggerInformation(), $messages->getLastWarning()?->getDebugInfo() ?? []),
+                array_merge(
+                    $referenceLinkNode instanceof AbstractLinkInlineNode ? $referenceLinkNode->getLoggerInformation() : [],
+                    $renderContext->getLoggerInformation(),
+                    $messages->getLastWarning()?->getDebugInfo() ?? [],
+                ),
             );
         }
 

packages/guides/src/ReferenceResolvers/ReferenceResolverPreRender.php

@@ -14,6 +14,7 @@
 namespace phpDocumentor\Guides\ReferenceResolvers;
 
 use phpDocumentor\Guides\NodeRenderers\PreRenderers\PreNodeRenderer;
+use phpDocumentor\Guides\Nodes\Inline\AbstractLinkInlineNode;
 use phpDocumentor\Guides\Nodes\Inline\LinkInlineNode;
 use phpDocumentor\Guides\Nodes\Node;
 use phpDocumentor\Guides\RenderContext;
@@ -48,7 +49,11 @@ public function execute(Node $node, RenderContext $renderContext): Node
                     $node->getTargetReference(),
                     $renderContext->getCurrentFileName(),
                 ),
-                array_merge($renderContext->getLoggerInformation(), $messages->getLastWarning()?->getDebugInfo() ?? []),
+                array_merge(
+                    $node instanceof AbstractLinkInlineNode ? $node->getLoggerInformation() : [],
+                    $renderContext->getLoggerInformation(),
+                    $messages->getLastWarning()?->getDebugInfo() ?? [],
+                ),
             );
         }
 

tests/Integration/tests/interlink/interlink-inventory-unknown/expected/logs/warning.log

@@ -1 +1 @@
-app.WARNING: Inventory with key unknowninventory not found.  {"rst-file":"Index","type":"doc","targetReference":"Index","value":"TYPO3 documentation","interlinkDomain":"unknowninventory"} []
+app.WARNING: Inventory with key unknowninventory not found.  {"rst-file":"Index","currentLineNumber":7,"type":"doc","targetReference":"Index","value":"TYPO3 documentation","interlinkDomain":"unknowninventory"} []

tests/Integration/tests/references/unresolved-reference-line-numbers/expected/logs/warning.log

@@ -0,0 +1,24 @@
+app.WARNING: Reference ref-line-4 could not be resolved in index {"rst-file":"index","currentLineNumber":4} []
+app.WARNING: Reference ref-line-6 could not be resolved in index {"rst-file":"index","currentLineNumber":6} []
+app.WARNING: Document with name "doc-line-7" not found, required in file "index". {"rst-file":"index","currentLineNumber":7} []
+app.WARNING: Reference hyperlink-line-8 could not be resolved in index {"rst-file":"index","currentLineNumber":8} []
+app.WARNING: Reference ref-line-11 could not be resolved in index {"rst-file":"index","currentLineNumber":11} []
+app.WARNING: Reference ref-line-14 could not be resolved in index {"rst-file":"index","currentLineNumber":14} []
+app.WARNING: Reference ref-line-16 could not be resolved in index {"rst-file":"index","currentLineNumber":16} []
+app.WARNING: Reference ref-line-18 could not be resolved in index {"rst-file":"index","currentLineNumber":18} []
+app.WARNING: Reference ref-line-20 could not be resolved in index {"rst-file":"index","currentLineNumber":20} []
+app.WARNING: Reference ref-line-21 could not be resolved in index {"rst-file":"index","currentLineNumber":21} []
+app.WARNING: Reference ref-line-23 could not be resolved in index {"rst-file":"index","currentLineNumber":23} []
+app.WARNING: Reference ref-line-24 could not be resolved in index {"rst-file":"index","currentLineNumber":24} []
+app.WARNING: Reference ref-line-26 could not be resolved in index {"rst-file":"index","currentLineNumber":26} []
+app.WARNING: Reference ref-line-28 could not be resolved in index {"rst-file":"index","currentLineNumber":28} []
+app.WARNING: Reference ref-line-30 could not be resolved in index {"rst-file":"index","currentLineNumber":30} []
+app.WARNING: Reference ref-line-31 could not be resolved in index {"rst-file":"index","currentLineNumber":31} []
+app.WARNING: Reference ref-line-33 could not be resolved in index {"rst-file":"index","currentLineNumber":33} []
+app.WARNING: Reference ref-line-36 could not be resolved in index {"rst-file":"index","currentLineNumber":36} []
+app.WARNING: Reference ref-line-37 could not be resolved in index {"rst-file":"index","currentLineNumber":37} []
+app.WARNING: Target image-target-line-40 of image could not be resolved in index {"rst-file":"index","currentLineNumber":40} []
+app.WARNING: Reference ref-line-48 could not be resolved in index {"rst-file":"index","currentLineNumber":48} []
+app.WARNING: Reference anonymous-line-49 could not be resolved in index {"rst-file":"index","currentLineNumber":49} []
+app.WARNING: Reference ref-line-51 could not be resolved in index {"rst-file":"index","currentLineNumber":51} []
+app.WARNING: Reference ref-line-58 could not be resolved in index {"rst-file":"index","currentLineNumber":58} []