fix(linter): improve jsx-a11y/anchor-ambiguous-text diagnostic message (#9789)

fix #9787

Author: 1zumii

apps/oxlint/src/snapshots/fixtures__extends_config_overrides@oxlint.snap

@@ -1,5 +1,6 @@
 ---
 source: apps/oxlint/src/tester.rs
+snapshot_kind: text
 ---
 ########## 
 arguments: overrides
@@ -21,13 +22,14 @@ working directory: fixtures/extends_config
    `----
   help: Use `unknown` instead, this will force you to explicitly, and safely, assert the type is correct.
 
-  x ]8;;https://oxc.rs/docs/guide/usage/linter/rules/jsx_a11y/anchor-ambiguous-text.html\eslint-plugin-jsx-a11y(anchor-ambiguous-text)]8;;\: Unexpected ambagious anchor link text.
+  x ]8;;https://oxc.rs/docs/guide/usage/linter/rules/jsx_a11y/anchor-ambiguous-text.html\eslint-plugin-jsx-a11y(anchor-ambiguous-text)]8;;\: Ambiguous text within anchor, screen reader users rely on link text for context.
    ,-[overrides/test.tsx:2:10]
  1 | function component(): any {
  2 |   return <a>click here</a>;
    :          ^^^^^^^^^^^^^^^^^
  3 | }
    `----
+  help: Avoid using ambiguous text like "click here", replace it with more descriptive text that provides context.
 
 Found 0 warnings and 3 errors.
 Finished in <variable>ms on 2 files using 1 threads.

crates/oxc_linter/src/rules/jsx_a11y/anchor_ambiguous_text.rs

@@ -18,8 +18,12 @@ use crate::{
     },
 };
 
-fn anchor_has_ambiguous_text(span: Span) -> OxcDiagnostic {
-    OxcDiagnostic::warn("Unexpected ambagious anchor link text.").with_label(span)
+fn anchor_has_ambiguous_text(span: Span, text: &CompactStr) -> OxcDiagnostic {
+    OxcDiagnostic::warn(
+        "Ambiguous text within anchor, screen reader users rely on link text for context.",
+    )
+    .with_label(span)
+    .with_help(format!("Avoid using ambiguous text like \"{text}\", replace it with more descriptive text that provides context."))
 }
 
 #[derive(Debug, Default, Clone)]
@@ -122,8 +126,10 @@ impl Rule for AnchorAmbiguousText {
             return;
         }
 
-        if self.words.contains(&normalize_str(&text)) {
-            ctx.diagnostic(anchor_has_ambiguous_text(jsx_el.span));
+        let text = normalize_str(&text);
+
+        if self.words.contains(&text) {
+            ctx.diagnostic(anchor_has_ambiguous_text(jsx_el.span, &text));
         }
     }
 }

crates/oxc_linter/src/snapshots/jsx_a11y_anchor_ambiguous_text.snap

@@ -1,170 +1,199 @@
 ---
 source: crates/oxc_linter/src/tester.rs
+snapshot_kind: text
 ---
-  ⚠ eslint-plugin-jsx-a11y(anchor-ambiguous-text): Unexpected ambagious anchor link text.
+  ⚠ eslint-plugin-jsx-a11y(anchor-ambiguous-text): Ambiguous text within anchor, screen reader users rely on link text for context.
    ╭─[anchor_ambiguous_text.tsx:1:1]
  1 │ <a>here</a>;
    · ───────────
    ╰────
+  help: Avoid using ambiguous text like "here", replace it with more descriptive text that provides context.
 
-  ⚠ eslint-plugin-jsx-a11y(anchor-ambiguous-text): Unexpected ambagious anchor link text.
+  ⚠ eslint-plugin-jsx-a11y(anchor-ambiguous-text): Ambiguous text within anchor, screen reader users rely on link text for context.
    ╭─[anchor_ambiguous_text.tsx:1:1]
  1 │ <a>HERE</a>;
    · ───────────
    ╰────
+  help: Avoid using ambiguous text like "here", replace it with more descriptive text that provides context.
 
-  ⚠ eslint-plugin-jsx-a11y(anchor-ambiguous-text): Unexpected ambagious anchor link text.
+  ⚠ eslint-plugin-jsx-a11y(anchor-ambiguous-text): Ambiguous text within anchor, screen reader users rely on link text for context.
    ╭─[anchor_ambiguous_text.tsx:1:1]
  1 │ <a>click here</a>;
    · ─────────────────
    ╰────
+  help: Avoid using ambiguous text like "click here", replace it with more descriptive text that provides context.
 
-  ⚠ eslint-plugin-jsx-a11y(anchor-ambiguous-text): Unexpected ambagious anchor link text.
+  ⚠ eslint-plugin-jsx-a11y(anchor-ambiguous-text): Ambiguous text within anchor, screen reader users rely on link text for context.
    ╭─[anchor_ambiguous_text.tsx:1:1]
  1 │ <a>learn more</a>;
    · ─────────────────
    ╰────
+  help: Avoid using ambiguous text like "learn more", replace it with more descriptive text that provides context.
 
-  ⚠ eslint-plugin-jsx-a11y(anchor-ambiguous-text): Unexpected ambagious anchor link text.
+  ⚠ eslint-plugin-jsx-a11y(anchor-ambiguous-text): Ambiguous text within anchor, screen reader users rely on link text for context.
    ╭─[anchor_ambiguous_text.tsx:1:1]
  1 │ <a>learn      more</a>;
    · ──────────────────────
    ╰────
+  help: Avoid using ambiguous text like "learn more", replace it with more descriptive text that provides context.
 
-  ⚠ eslint-plugin-jsx-a11y(anchor-ambiguous-text): Unexpected ambagious anchor link text.
+  ⚠ eslint-plugin-jsx-a11y(anchor-ambiguous-text): Ambiguous text within anchor, screen reader users rely on link text for context.
    ╭─[anchor_ambiguous_text.tsx:1:1]
  1 │ <a>learn more.</a>;
    · ──────────────────
    ╰────
+  help: Avoid using ambiguous text like "learn more", replace it with more descriptive text that provides context.
 
-  ⚠ eslint-plugin-jsx-a11y(anchor-ambiguous-text): Unexpected ambagious anchor link text.
+  ⚠ eslint-plugin-jsx-a11y(anchor-ambiguous-text): Ambiguous text within anchor, screen reader users rely on link text for context.
    ╭─[anchor_ambiguous_text.tsx:1:1]
  1 │ <a>learn more?</a>;
    · ──────────────────
    ╰────
+  help: Avoid using ambiguous text like "learn more", replace it with more descriptive text that provides context.
 
-  ⚠ eslint-plugin-jsx-a11y(anchor-ambiguous-text): Unexpected ambagious anchor link text.
+  ⚠ eslint-plugin-jsx-a11y(anchor-ambiguous-text): Ambiguous text within anchor, screen reader users rely on link text for context.
    ╭─[anchor_ambiguous_text.tsx:1:1]
  1 │ <a>learn more,</a>;
    · ──────────────────
    ╰────
+  help: Avoid using ambiguous text like "learn more", replace it with more descriptive text that provides context.
 
-  ⚠ eslint-plugin-jsx-a11y(anchor-ambiguous-text): Unexpected ambagious anchor link text.
+  ⚠ eslint-plugin-jsx-a11y(anchor-ambiguous-text): Ambiguous text within anchor, screen reader users rely on link text for context.
    ╭─[anchor_ambiguous_text.tsx:1:1]
  1 │ <a>learn more!</a>;
    · ──────────────────
    ╰────
+  help: Avoid using ambiguous text like "learn more", replace it with more descriptive text that provides context.
 
-  ⚠ eslint-plugin-jsx-a11y(anchor-ambiguous-text): Unexpected ambagious anchor link text.
+  ⚠ eslint-plugin-jsx-a11y(anchor-ambiguous-text): Ambiguous text within anchor, screen reader users rely on link text for context.
    ╭─[anchor_ambiguous_text.tsx:1:1]
  1 │ <a>learn more;</a>;
    · ──────────────────
    ╰────
+  help: Avoid using ambiguous text like "learn more", replace it with more descriptive text that provides context.
 
-  ⚠ eslint-plugin-jsx-a11y(anchor-ambiguous-text): Unexpected ambagious anchor link text.
+  ⚠ eslint-plugin-jsx-a11y(anchor-ambiguous-text): Ambiguous text within anchor, screen reader users rely on link text for context.
    ╭─[anchor_ambiguous_text.tsx:1:1]
  1 │ <a>learn more:</a>;
    · ──────────────────
    ╰────
+  help: Avoid using ambiguous text like "learn more", replace it with more descriptive text that provides context.
 
-  ⚠ eslint-plugin-jsx-a11y(anchor-ambiguous-text): Unexpected ambagious anchor link text.
+  ⚠ eslint-plugin-jsx-a11y(anchor-ambiguous-text): Ambiguous text within anchor, screen reader users rely on link text for context.
    ╭─[anchor_ambiguous_text.tsx:1:1]
  1 │ <a>link</a>;
    · ───────────
    ╰────
+  help: Avoid using ambiguous text like "link", replace it with more descriptive text that provides context.
 
-  ⚠ eslint-plugin-jsx-a11y(anchor-ambiguous-text): Unexpected ambagious anchor link text.
+  ⚠ eslint-plugin-jsx-a11y(anchor-ambiguous-text): Ambiguous text within anchor, screen reader users rely on link text for context.
    ╭─[anchor_ambiguous_text.tsx:1:1]
  1 │ <a>a link</a>;
    · ─────────────
    ╰────
+  help: Avoid using ambiguous text like "a link", replace it with more descriptive text that provides context.
 
-  ⚠ eslint-plugin-jsx-a11y(anchor-ambiguous-text): Unexpected ambagious anchor link text.
+  ⚠ eslint-plugin-jsx-a11y(anchor-ambiguous-text): Ambiguous text within anchor, screen reader users rely on link text for context.
    ╭─[anchor_ambiguous_text.tsx:1:1]
  1 │ <a aria-label="click here">something</a>;
    · ────────────────────────────────────────
    ╰────
+  help: Avoid using ambiguous text like "click here", replace it with more descriptive text that provides context.
 
-  ⚠ eslint-plugin-jsx-a11y(anchor-ambiguous-text): Unexpected ambagious anchor link text.
+  ⚠ eslint-plugin-jsx-a11y(anchor-ambiguous-text): Ambiguous text within anchor, screen reader users rely on link text for context.
    ╭─[anchor_ambiguous_text.tsx:1:1]
  1 │ <a> a link </a>;
    · ───────────────
    ╰────
+  help: Avoid using ambiguous text like "a link", replace it with more descriptive text that provides context.
 
-  ⚠ eslint-plugin-jsx-a11y(anchor-ambiguous-text): Unexpected ambagious anchor link text.
+  ⚠ eslint-plugin-jsx-a11y(anchor-ambiguous-text): Ambiguous text within anchor, screen reader users rely on link text for context.
    ╭─[anchor_ambiguous_text.tsx:1:1]
  1 │ <a>a<i></i> link</a>;
    · ────────────────────
    ╰────
+  help: Avoid using ambiguous text like "a link", replace it with more descriptive text that provides context.
 
-  ⚠ eslint-plugin-jsx-a11y(anchor-ambiguous-text): Unexpected ambagious anchor link text.
+  ⚠ eslint-plugin-jsx-a11y(anchor-ambiguous-text): Ambiguous text within anchor, screen reader users rely on link text for context.
    ╭─[anchor_ambiguous_text.tsx:1:1]
  1 │ <a><i></i>a link</a>;
    · ────────────────────
    ╰────
+  help: Avoid using ambiguous text like "a link", replace it with more descriptive text that provides context.
 
-  ⚠ eslint-plugin-jsx-a11y(anchor-ambiguous-text): Unexpected ambagious anchor link text.
+  ⚠ eslint-plugin-jsx-a11y(anchor-ambiguous-text): Ambiguous text within anchor, screen reader users rely on link text for context.
    ╭─[anchor_ambiguous_text.tsx:1:1]
  1 │ <a><span>click</span> here</a>;
    · ──────────────────────────────
    ╰────
+  help: Avoid using ambiguous text like "click here", replace it with more descriptive text that provides context.
 
-  ⚠ eslint-plugin-jsx-a11y(anchor-ambiguous-text): Unexpected ambagious anchor link text.
+  ⚠ eslint-plugin-jsx-a11y(anchor-ambiguous-text): Ambiguous text within anchor, screen reader users rely on link text for context.
    ╭─[anchor_ambiguous_text.tsx:1:1]
  1 │ <a><span> click </span> here</a>;
    · ────────────────────────────────
    ╰────
+  help: Avoid using ambiguous text like "click here", replace it with more descriptive text that provides context.
 
-  ⚠ eslint-plugin-jsx-a11y(anchor-ambiguous-text): Unexpected ambagious anchor link text.
+  ⚠ eslint-plugin-jsx-a11y(anchor-ambiguous-text): Ambiguous text within anchor, screen reader users rely on link text for context.
    ╭─[anchor_ambiguous_text.tsx:1:1]
  1 │ <a><span aria-hidden>more text</span>learn more</a>;
    · ───────────────────────────────────────────────────
    ╰────
+  help: Avoid using ambiguous text like "learn more", replace it with more descriptive text that provides context.
 
-  ⚠ eslint-plugin-jsx-a11y(anchor-ambiguous-text): Unexpected ambagious anchor link text.
+  ⚠ eslint-plugin-jsx-a11y(anchor-ambiguous-text): Ambiguous text within anchor, screen reader users rely on link text for context.
    ╭─[anchor_ambiguous_text.tsx:1:1]
  1 │ <a><span aria-hidden="true">more text</span>learn more</a>;
    · ──────────────────────────────────────────────────────────
    ╰────
+  help: Avoid using ambiguous text like "learn more", replace it with more descriptive text that provides context.
 
-  ⚠ eslint-plugin-jsx-a11y(anchor-ambiguous-text): Unexpected ambagious anchor link text.
+  ⚠ eslint-plugin-jsx-a11y(anchor-ambiguous-text): Ambiguous text within anchor, screen reader users rely on link text for context.
    ╭─[anchor_ambiguous_text.tsx:1:1]
  1 │ <a><img alt="click here"/></a>;
    · ──────────────────────────────
    ╰────
+  help: Avoid using ambiguous text like "click here", replace it with more descriptive text that provides context.
 
-  ⚠ eslint-plugin-jsx-a11y(anchor-ambiguous-text): Unexpected ambagious anchor link text.
+  ⚠ eslint-plugin-jsx-a11y(anchor-ambiguous-text): Ambiguous text within anchor, screen reader users rely on link text for context.
    ╭─[anchor_ambiguous_text.tsx:1:1]
  1 │ <a alt="tutorial on using eslint-plugin-jsx-a11y">click here</a>;
    · ────────────────────────────────────────────────────────────────
    ╰────
+  help: Avoid using ambiguous text like "click here", replace it with more descriptive text that provides context.
 
-  ⚠ eslint-plugin-jsx-a11y(anchor-ambiguous-text): Unexpected ambagious anchor link text.
+  ⚠ eslint-plugin-jsx-a11y(anchor-ambiguous-text): Ambiguous text within anchor, screen reader users rely on link text for context.
    ╭─[anchor_ambiguous_text.tsx:1:1]
  1 │ <a><span alt="tutorial on using eslint-plugin-jsx-a11y">click here</span></a>;
    · ─────────────────────────────────────────────────────────────────────────────
    ╰────
+  help: Avoid using ambiguous text like "click here", replace it with more descriptive text that provides context.
 
-  ⚠ eslint-plugin-jsx-a11y(anchor-ambiguous-text): Unexpected ambagious anchor link text.
+  ⚠ eslint-plugin-jsx-a11y(anchor-ambiguous-text): Ambiguous text within anchor, screen reader users rely on link text for context.
    ╭─[anchor_ambiguous_text.tsx:1:1]
  1 │ <a><CustomElement>click</CustomElement> here</a>;
    · ────────────────────────────────────────────────
    ╰────
+  help: Avoid using ambiguous text like "click here", replace it with more descriptive text that provides context.
 
-  ⚠ eslint-plugin-jsx-a11y(anchor-ambiguous-text): Unexpected ambagious anchor link text.
+  ⚠ eslint-plugin-jsx-a11y(anchor-ambiguous-text): Ambiguous text within anchor, screen reader users rely on link text for context.
    ╭─[anchor_ambiguous_text.tsx:1:1]
  1 │ <Link>here</Link>
    · ─────────────────
    ╰────
+  help: Avoid using ambiguous text like "here", replace it with more descriptive text that provides context.
 
-  ⚠ eslint-plugin-jsx-a11y(anchor-ambiguous-text): Unexpected ambagious anchor link text.
+  ⚠ eslint-plugin-jsx-a11y(anchor-ambiguous-text): Ambiguous text within anchor, screen reader users rely on link text for context.
    ╭─[anchor_ambiguous_text.tsx:1:1]
  1 │ <a><Image alt="click here" /></a>
    · ─────────────────────────────────
    ╰────
+  help: Avoid using ambiguous text like "click here", replace it with more descriptive text that provides context.
 
-  ⚠ eslint-plugin-jsx-a11y(anchor-ambiguous-text): Unexpected ambagious anchor link text.
+  ⚠ eslint-plugin-jsx-a11y(anchor-ambiguous-text): Ambiguous text within anchor, screen reader users rely on link text for context.
    ╭─[anchor_ambiguous_text.tsx:1:1]
  1 │ <a>a disallowed word</a>
    · ────────────────────────
    ╰────
+  help: Avoid using ambiguous text like "a disallowed word", replace it with more descriptive text that provides context.