[TASK] Warn about duplicate link targets

releases: main, 1.0
(cherry picked from commit 9daa2a3)

Author: linawolf

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

@@ -23,9 +23,12 @@
 use phpDocumentor\Guides\Nodes\Node;
 use phpDocumentor\Guides\Nodes\SectionNode;
 use phpDocumentor\Guides\ReferenceResolvers\AnchorNormalizer;
+use Psr\Log\LoggerInterface;
 use SplStack;
 use Webmozart\Assert\Assert;
 
+use function sprintf;
+
 /** @implements NodeTransformer<DocumentNode|AnchorNode|SectionNode> */
 final class CollectLinkTargetsTransformer implements NodeTransformer
 {
@@ -34,6 +37,7 @@ final class CollectLinkTargetsTransformer implements NodeTransformer
 
     public function __construct(
         private readonly AnchorNormalizer $anchorReducer,
+        private LoggerInterface|null $logger = null,
     ) {
         /*
          * TODO: remove stack here, as we should not have sub documents in this way, sub documents are
@@ -68,17 +72,43 @@ public function enterNode(Node $node, CompilerContext $compilerContext): Node
             $currentDocument = $this->documentStack->top();
             Assert::notNull($currentDocument);
             $anchor = $node->getId();
-            $compilerContext->getProjectNode()->addLinkTarget(
-                $anchor,
-                new InternalTarget(
-                    $currentDocument->getFilePath(),
+            if ($compilerContext->getProjectNode()->hasInternalTarget($anchor, $node->getLinkType())) {
+                $this->logger?->warning(
+                    sprintf(
+                        'Duplicate anchor "%s" for link type "%s" in document "%s". The anchor is already used at "%s"',
+                        $anchor,
+                        $node->getLinkType(),
+                        $compilerContext->getDocumentNode()->getFilePath(),
+                        $compilerContext->getProjectNode()->getInternalTarget($anchor, $node->getLinkType())?->getDocumentPath(),
+                    ),
+                    $compilerContext->getLoggerInformation(),
+                );
+            } else {
+                $compilerContext->getProjectNode()->addLinkTarget(
                     $anchor,
-                    $node->getLinkText(),
-                    $node->getLinkType(),
-                ),
-            );
+                    new InternalTarget(
+                        $currentDocument->getFilePath(),
+                        $anchor,
+                        $node->getLinkText(),
+                        $node->getLinkType(),
+                    ),
+                );
+            }
             if ($node instanceof MultipleLinkTargetsNode) {
                 foreach ($node->getAdditionalIds() as $id) {
+                    if ($compilerContext->getProjectNode()->hasInternalTarget($id, $node->getLinkType())) {
+                        $this->logger?->warning(
+                            sprintf(
+                                'Duplicate anchor "%s" for link type "%s" in document "%s". The anchor is already used at "%s"',
+                                $anchor,
+                                $node->getLinkType(),
+                                $compilerContext->getDocumentNode()->getFilePath(),
+                                $compilerContext->getProjectNode()->getInternalTarget($anchor, $node->getLinkType())?->getDocumentPath(),
+                            ),
+                            $compilerContext->getLoggerInformation(),
+                        );
+                    }
+
                     $compilerContext->getProjectNode()->addLinkTarget(
                         $id,
                         new InternalTarget(

packages/guides/src/Nodes/ProjectNode.php

@@ -152,6 +152,11 @@ public function addLinkTarget(string $anchorName, InternalTarget $target): void
         $this->internalLinkTargets[$target->getLinkType()][$anchorName] = $target;
     }
 
+    public function hasInternalTarget(string $anchorName, string $linkType = SectionNode::STD_LABEL): bool
+    {
+        return isset($this->internalLinkTargets[$linkType][$anchorName]);
+    }
+
     public function getInternalTarget(string $anchorName, string $linkType = SectionNode::STD_LABEL): InternalTarget|null
     {
         return $this->internalLinkTargets[$linkType][$anchorName] ?? null;

tests/Functional/tests/section-nesting/section-nesting.html

@@ -37,9 +37,9 @@ <h1>
     <h1>
         Level 1 Test 4
     </h1>
-    <div class="section" id="level-2-test-3">
+    <div class="section" id="level-2-test-3b">
         <h2>
-            Level 2 Test 3
+            Level 2 Test 3b
         </h2>
         <div class="section" id="level-3-test-1">
             <h3>

tests/Functional/tests/section-nesting/section-nesting.rst

@@ -22,8 +22,8 @@ Level 1 Test 3
 Level 1 Test 4
 ==============
 
-Level 2 Test 3
---------------
+Level 2 Test 3b
+---------------
 
 Level 3 Test 1
 **************