From c2077c1835787e21c7e48645b00ee1b864303357 Mon Sep 17 00:00:00 2001
From: Marcos Caceres <caceres_m@apple.com>
Date: Sat, 9 May 2026 14:21:25 +1000
Subject: [PATCH] fix(linter/local-refs-exist): include broken hrefs in warning
 hint

The warning message said "Please fix the links mentioned" without
listing which links were broken. Include the href values so authors
can identify the broken references, especially in CLI output where
element highlighting isn't available.

Closes #4378
---
 src/core/linter-rules/local-refs-exist.js             | 6 +++++-
 tests/unit/core/linter-rules/local-refs-exist-spec.js | 1 +
 2 files changed, 6 insertions(+), 1 deletion(-)

diff --git a/src/core/linter-rules/local-refs-exist.js b/src/core/linter-rules/local-refs-exist.js
index 5d2236c6e8..8cb37d5a37 100644
--- a/src/core/linter-rules/local-refs-exist.js
+++ b/src/core/linter-rules/local-refs-exist.js
@@ -33,8 +33,12 @@ export function run(conf) {
   const elems = document.querySelectorAll("a[href^='#']");
   const offendingElements = [...elems].filter(isBrokenHyperlink);
   if (offendingElements.length) {
+    const links = offendingElements
+      .map(el => el.getAttribute("href"))
+      .join(", ");
+    const hint = `${l10n.hint} Broken links: ${links}`;
     showWarning(l10n.msg, name, {
-      hint: l10n.hint,
+      hint,
       elements: offendingElements,
     });
   }
diff --git a/tests/unit/core/linter-rules/local-refs-exist-spec.js b/tests/unit/core/linter-rules/local-refs-exist-spec.js
index 94a87728fa..1bcc704678 100644
--- a/tests/unit/core/linter-rules/local-refs-exist-spec.js
+++ b/tests/unit/core/linter-rules/local-refs-exist-spec.js
@@ -26,6 +26,7 @@ describe("Core Linter Rule - 'local-refs-exist'", () => {
 
     const [warning] = warnings;
     expect(warning.elements).toHaveSize(2);
+    expect(warning.hint).toContain("#ID-NOT-EXIST");
     const [offendingElement] = warning.elements;
     const { hash } = new URL(offendingElement.href);
     expect(hash).toBe("#ID-NOT-EXIST");