[1.x] [TASK] Warn about duplicate anchors

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

@@ -15,6 +15,7 @@
 
 use phpDocumentor\Guides\Compiler\CompilerContextInterface;
 use phpDocumentor\Guides\Compiler\NodeTransformer;
+use phpDocumentor\Guides\Exception\DuplicateLinkAnchorException;
 use phpDocumentor\Guides\Meta\InternalTarget;
 use phpDocumentor\Guides\Nodes\AnchorNode;
 use phpDocumentor\Guides\Nodes\DocumentNode;
@@ -66,14 +67,18 @@ public function enterNode(Node $node, CompilerContextInterface $compilerContext)
             }
 
             $anchorName = $this->anchorReducer->reduceAnchor($node->toString());
-            $compilerContext->getProjectNode()->addLinkTarget(
-                $anchorName,
-                new InternalTarget(
-                    $currentDocument->getFilePath(),
-                    $node->toString(),
-                    $title,
-                ),
-            );
+            try {
+                $compilerContext->getProjectNode()->addLinkTarget(
+                    $anchorName,
+                    new InternalTarget(
+                        $currentDocument->getFilePath(),
+                        $node->toString(),
+                        $title,
+                    ),
+                );
+            } catch (DuplicateLinkAnchorException $exception) {
+                $this->logger?->warning($exception->getMessage(), $compilerContext->getLoggerInformation());
+            }
 
             return $node;
         }
@@ -82,15 +87,19 @@ public function enterNode(Node $node, CompilerContextInterface $compilerContext)
             $currentDocument = $this->documentStack->top();
             Assert::notNull($currentDocument);
             $anchorName = $node->getId();
-            $compilerContext->getProjectNode()->addLinkTarget(
-                $anchorName,
-                new InternalTarget(
-                    $currentDocument->getFilePath(),
+            try {
+                $compilerContext->getProjectNode()->addLinkTarget(
                     $anchorName,
-                    $node->getLinkText(),
-                    SectionNode::STD_TITLE,
-                ),
-            );
+                    new InternalTarget(
+                        $currentDocument->getFilePath(),
+                        $anchorName,
+                        $node->getLinkText(),
+                        SectionNode::STD_TITLE,
+                    ),
+                );
+            } catch (DuplicateLinkAnchorException $exception) {
+                $this->logger?->warning($exception->getMessage(), $compilerContext->getLoggerInformation());
+            }
 
             return $node;
         }
@@ -175,9 +184,13 @@ private function addLinkTargetToProject(CompilerContextInterface $compilerContex
             return;
         }
 
-        $compilerContext->getProjectNode()->addLinkTarget(
-            $internalTarget->getAnchor(),
-            $internalTarget,
-        );
+        try {
+            $compilerContext->getProjectNode()->addLinkTarget(
+                $internalTarget->getAnchor(),
+                $internalTarget,
+            );
+        } catch (DuplicateLinkAnchorException $exception) {
+            $this->logger?->warning($exception->getMessage(), $compilerContext->getLoggerInformation());
+        }
     }
 }

packages/guides/src/Exception/DuplicateLinkAnchorException.php

@@ -0,0 +1,20 @@
+<?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\Exception;
+
+use Exception;
+
+final class DuplicateLinkAnchorException extends Exception
+{
+}

packages/guides/src/Nodes/ProjectNode.php

@@ -16,6 +16,7 @@
 use DateTimeImmutable;
 use Exception;
 use phpDocumentor\Guides\Exception\DocumentEntryNotFound;
+use phpDocumentor\Guides\Exception\DuplicateLinkAnchorException;
 use phpDocumentor\Guides\Meta\CitationTarget;
 use phpDocumentor\Guides\Meta\InternalTarget;
 use phpDocumentor\Guides\Nodes\DocumentTree\DocumentEntryNode;
@@ -24,6 +25,7 @@
 
 use function array_merge;
 use function array_unique;
+use function sprintf;
 
 use const DATE_RFC2822;
 
@@ -143,13 +145,19 @@ public function getCitationTarget(string $name): CitationTarget|null
         return $this->citationTargets[$name] ?? null;
     }
 
+    /** @throws DuplicateLinkAnchorException */
     public function addLinkTarget(string $anchorName, InternalTarget $target): void
     {
-        if (!isset($this->internalLinkTargets[$target->getLinkType()])) {
-            $this->internalLinkTargets[$target->getLinkType()] = [];
+        $linkType = $target->getLinkType();
+        if (!isset($this->internalLinkTargets[$linkType])) {
+            $this->internalLinkTargets[$linkType] = [];
         }
 
-        $this->internalLinkTargets[$target->getLinkType()][$anchorName] = $target;
+        if (isset($this->internalLinkTargets[$linkType][$anchorName]) && $linkType !== 'std:title') {
+            throw new DuplicateLinkAnchorException(sprintf('Duplicate anchor "%s". There is already another anchor of that name in document "%s"', $anchorName, $this->internalLinkTargets[$linkType][$anchorName]->getDocumentPath()));
+        }
+
+        $this->internalLinkTargets[$linkType][$anchorName] = $target;
     }
 
     public function hasInternalTarget(string $anchorName, string $linkType = SectionNode::STD_LABEL): bool

tests/Integration/tests/anchor/anchor-duplicate-warning/expected/index.html

@@ -0,0 +1,31 @@
+<!-- content start -->
+    <div class="section" id="overview">
+            <a id="rst-overview"></a>
+            <h1>Overview</h1>
+
+    <p>RST Overview content</p>
+
+    </div>
+<div class="section" id="overview-1">
+            <a id="sphinx-overview"></a>
+            <h1>Overview</h1>
+
+    <p>Sphinx Overview content</p>
+
+            <div class="section" id="somewhere-else">
+            <h2>Somewhere else</h2>
+
+    <p>This is a link to the RST Overview: <a href="/index.html#rst-overview">Overview</a></p>
+
+            <div class="toc">
+    <ul class="menu-level">
+    <li class="toc-item">
+    <a href="/page.html#page">Page</a>
+
+
+</li>
+    </ul>
+</div>
+    </div>
+    </div>
+<!-- content end -->

tests/Integration/tests/anchor/anchor-duplicate-warning/expected/logs/warning.log

@@ -0,0 +1 @@
+app.WARNING: Duplicate anchor "rst-overview". There is already another anchor of that name in document "index" {"rst-file":"page.rst"} []

tests/Integration/tests/anchor/anchor-duplicate-warning/input/index.rst

@@ -0,0 +1,23 @@
+.. _rst-overview:
+
+Overview
+**********
+
+RST Overview content
+
+.. _sphinx-overview:
+
+Overview
+*********
+
+Sphinx Overview content
+
+Somewhere else
+=============
+
+This is a link to the RST Overview: :ref:`rst-overview`
+
+..  toctree::
+    :glob:
+
+    *

tests/Integration/tests/anchor/anchor-duplicate-warning/input/page.rst

@@ -0,0 +1,7 @@
+.. _rst-overview:
+
+====
+Page
+====
+
+RST Overview content