From b215b6cd03a6cb9f70c1e0d25827af6904b42eb8 Mon Sep 17 00:00:00 2001
From: camc314 <18101008+camc314@users.noreply.github.com>
Date: Fri, 9 May 2025 09:36:16 +0000
Subject: [PATCH] fix(semantic): dont parse `@` as jsdoc tags inside `[`/`]`
 (#10919)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

fixes #10910

```
  × eslint-plugin-jsdoc(check-tag-names): Invalid tag name found.
   ╭─[index.ts:3:14]
 2 │     /**
 3 │      * @see [@parcel/watcher](https://github.com/parcel-bundler/watcher)
   ·              ───────────────────────────────────────────────────────────
 4 │      */
   ╰────
  help: `@parcel/watcher](https://github.com/parcel-bundler/watcher)` is invalid tag name.
```

`@see` was being parsed as a tag and `@parcel/watcher](https://github.com/parcel-bundler/watcher)` as another tag.

I fixed this by checking if we are in `[` or `]`
---
 crates/oxc_linter/src/rules/jsdoc/check_tag_names.rs | 11 +++++++++++
 crates/oxc_semantic/src/jsdoc/parser/parse.rs        |  5 ++++-
 2 files changed, 15 insertions(+), 1 deletion(-)

diff --git a/crates/oxc_linter/src/rules/jsdoc/check_tag_names.rs b/crates/oxc_linter/src/rules/jsdoc/check_tag_names.rs
index 74c078ea77897..937fc84039476 100644
--- a/crates/oxc_linter/src/rules/jsdoc/check_tag_names.rs
+++ b/crates/oxc_linter/src/rules/jsdoc/check_tag_names.rs
@@ -562,6 +562,17 @@ fn test() {
             ])),
             None,
         ),
+        // https://github.com/oxc-project/oxc/issues/10910
+        (
+          "
+          /**
+           * @see [@parcel/watcher](https://github.com/parcel-bundler/watcher)
+           */
+          function quux (foo) { }
+      ",
+          Some(serde_json::json!([ { "definedTags": [] } ])),
+          None,
+      ),
     ];
 
     let fail = vec![
diff --git a/crates/oxc_semantic/src/jsdoc/parser/parse.rs b/crates/oxc_semantic/src/jsdoc/parser/parse.rs
index 3492bf4052e75..e6f3b0f9fc057 100644
--- a/crates/oxc_semantic/src/jsdoc/parser/parse.rs
+++ b/crates/oxc_semantic/src/jsdoc/parser/parse.rs
@@ -22,6 +22,7 @@ pub fn parse_jsdoc(source_text: &str, jsdoc_span_start: u32) -> (JSDocCommentPar
     // So, find `@` to split comment and each tag.
     // But `@` can be found inside of `{}` (e.g. `{@see link}`), it should be distinguished.
     let mut in_braces = false;
+    let mut in_square_braces = false;
     // Also, `@` is often found inside of backtick(` or ```), like markdown.
     let mut in_backticks = false;
     let mut comment_found = false;
@@ -30,7 +31,7 @@ pub fn parse_jsdoc(source_text: &str, jsdoc_span_start: u32) -> (JSDocCommentPar
 
     let mut chars = source_text.chars().peekable();
     while let Some(ch) = chars.next() {
-        let can_parse = !(in_braces || in_backticks);
+        let can_parse = !(in_braces || in_backticks || in_square_braces);
         match ch {
             // NOTE: For now, only odd backtick(s) are handled.
             // - 1 backtick: inline code
@@ -45,6 +46,8 @@ pub fn parse_jsdoc(source_text: &str, jsdoc_span_start: u32) -> (JSDocCommentPar
             }
             '{' => in_braces = true,
             '}' => in_braces = false,
+            '[' => in_square_braces = true,
+            ']' => in_square_braces = false,
             '@' if can_parse => {
                 let part = &source_text[start..end];
                 let span = Span::new(