Skip to content

fix(semantic/jsdoc): inline tags like {@link} break jsdoc parsing#19019

Merged
graphite-app[bot] merged 1 commit intomainfrom
fix/jsdoc-inline-tags-type-parsing
Feb 6, 2026
Merged

fix(semantic/jsdoc): inline tags like {@link} break jsdoc parsing#19019
graphite-app[bot] merged 1 commit intomainfrom
fix/jsdoc-inline-tags-type-parsing

Conversation

@Boshen
Copy link
Member

@Boshen Boshen commented Feb 6, 2026

Summary

  • find_type_range() searched for the first {...} pair anywhere in the tag body, so {@link Type} or {} in descriptions were incorrectly treated as type annotations, causing false "missing param description" lint errors
  • Now only matches {...} at the start of the tag body (after whitespace), matching the JSDoc spec that type annotations must come first

Closes #18724

🤖 Generated with Claude Code

@Boshen Boshen requested a review from Dunqing as a code owner February 6, 2026 04:05
Copilot AI review requested due to automatic review settings February 6, 2026 04:05
@github-actions github-actions bot added A-semantic Area - Semantic C-bug Category - Bug labels Feb 6, 2026
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR fixes a bug in JSDoc parsing where inline tags like {@link Type} and curly braces in descriptions were incorrectly treated as type annotations, causing false "missing param description" lint errors.

Changes:

  • Modified find_type_range() to only match {...} at the start of tag body (after whitespace), per JSDoc spec
  • Updated test expectations to correctly return None for braces not at the beginning
  • Added comprehensive test cases for inline tags and braces in descriptions

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File Description
crates/oxc_semantic/src/jsdoc/parser/utils.rs Fixed find_type_range() to only match type annotations at start of string; added test cases for inline tags
crates/oxc_semantic/src/jsdoc/parser/jsdoc_tag.rs Updated test expectations and added integration tests for @param tags with inline tags and braces

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

@codspeed-hq
Copy link

codspeed-hq bot commented Feb 6, 2026

Merging this PR will not alter performance

✅ 46 untouched benchmarks
⏩ 3 skipped benchmarks1


Comparing fix/jsdoc-inline-tags-type-parsing (5d87bd8) with main (e3609e3)2

Open in CodSpeed

Footnotes

  1. 3 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports.

  2. No successful run was found on main (b249ee2) during the generation of this report, so e3609e3 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report.

Copy link
Member

@leaysgur leaysgur left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm concerned that Some became None in the test case, but honestly, I don't know the correct answer...

However, if it doesn't affect other existing tests (especially in linter), then it probably aligns with general use cases.

@leaysgur leaysgur added the 0-merge Merge with Graphite Merge Queue label Feb 6, 2026
Copy link
Member

leaysgur commented Feb 6, 2026

Merge activity

…19019)

## Summary

- `find_type_range()` searched for the first `{...}` pair anywhere in the tag body, so `{@link Type}` or `{}` in descriptions were incorrectly treated as type annotations, causing false "missing param description" lint errors
- Now only matches `{...}` at the start of the tag body (after whitespace), matching the JSDoc spec that type annotations must come first

Closes #18724

🤖 Generated with [Claude Code](https://claude.com/claude-code)
@graphite-app graphite-app bot force-pushed the fix/jsdoc-inline-tags-type-parsing branch from 5d87bd8 to b13bb70 Compare February 6, 2026 04:53
@graphite-app graphite-app bot merged commit b13bb70 into main Feb 6, 2026
21 checks passed
@graphite-app graphite-app bot deleted the fix/jsdoc-inline-tags-type-parsing branch February 6, 2026 04:59
@graphite-app graphite-app bot removed the 0-merge Merge with Graphite Merge Queue label Feb 6, 2026
camc314 added a commit that referenced this pull request Feb 10, 2026
### 💥 BREAKING CHANGES

- 2bf7293 mangler: [**BREAKING**] Enable `top_level` by default for
modules and commonjs (#18278) (sapphi-red)
- 48b0542 span: [**BREAKING**] SourceType::ts should set module to
unambigious (#18873) (Boshen)

### 🚀 Features

- 500d071 minifier: Local traverse ctx and generated minifier traverse
(#19106) (Boshen)
- 142a1be parser: Detect binary files with TS1490 error (#19047)
(Boshen)
- e316857 allocator/bitset: Add `Ones` iterator to `BitSet` (#19027)
(sapphi-red)
- 742ad3f minifier: Default `invalid_import_side_effects` to `false`
(#18916) (sapphi-red)
- 0eff6be parser: Error JSX-like type assertions and generics in
`.mts`/`.cts` (#18910) (Boshen)
- 18320c6 span: Store file extension in `SourceType` (#18893) (Boshen)

### 🐛 Bug Fixes

- a7514e4 isolated-declarations: Preserve const context in literal type
inference (#19178) (camc314)
- 312e756 isolated-declarations: Preserve readonly literal initializers
(#19177) (camc314)
- d0ca8d0 isolated-declarations: Skip parenthesis when inferring type
(#19176) (camc314)
- 110c300 oxc_ecmascript: `+[false]` and `+[true]` should evaluate to
`NaN` (#19174) (copilot-swe-agent)
- f32ea19 semantic: Report redeclaration error for import bindings
conflicting with value declarations (#19068) (Boshen)
- 3aeba7a semantic: Report redeclaration error for `function a() {} var
a` in module mode (#19041) (Boshen)
- 35e32c6 coverage: Match Babel's options.json inheritance for test
fixtures (#19002) (Boshen)
- 463d60d semantic: Skip TS2391 for standalone computed-name class
methods (#19025) (Boshen)
- 56c086b parser: Add modifier ordering validation (TS1029) (#19024)
(Boshen)
- 6067a49 linter/jsdoc: False positive in `check-tag-names` for `@` in
email addresses and npm scopes (#19021) (Boshen)
- b13bb70 semantic/jsdoc: Inline tags like `{@link}` break jsdoc parsing
(#19019) (Boshen)
- e3609e3 regular_expression: Preserve UnicodeEscape CharacterKind in
string literals (#18998) (Boshen)
- 57917ee parser: Parse decorators on rest parameters (#18938) (Boshen)
- 487601b napi: Disable mimalloc on Windows to fix worker_threads crash
(#18923) (Boshen)
- 1f6b193 parser: Validate TypeScript import type options (#18889)
(Boshen)
- 1663184 parser: Allow conditional types in function type parameters
(#18886) (Boshen)
- 5758046 parser: Error on property access after instantiation
expression (#18887) (Boshen)
- 5eb4a94 parser: Handle `<<` as two `<` tokens in type argument
contexts (#18885) (Boshen)

### ⚡ Performance

- ed8c054 oxc_str: Add precomputed hash to Ident for fast HashMap
lookups (#19143) (Boshen)
- d4a0867 transformer_plugins: Switch ReplaceGlobalDefines from Traverse
to VisitMut (#19146) (Boshen)
- 9eb16b3 syntax: Pack ASCII identifier tables into single bitflag table
(#19088) (Boshen)
- e7595d1 mangler: Use BitSet for exported symbols set (#19023)
(sapphi-red)
- 2537924 semantic: Optimize scope resolution with fast paths and
inlining (#19029) (Boshen)
- 69a8d85 mangler: Use BitSet for keep_names symbols set (#19028)
(sapphi-red)
- f78c525 parser: Try hybrid parsing for jsx children and closing
element/fragments (#18789) (camchenry)

Co-authored-by: camc314 <18101008+camc314@users.noreply.github.com>
owjs3901 pushed a commit to owjs3901/oxc that referenced this pull request Feb 11, 2026
### 💥 BREAKING CHANGES

- 2bf7293 mangler: [**BREAKING**] Enable `top_level` by default for
modules and commonjs (oxc-project#18278) (sapphi-red)
- 48b0542 span: [**BREAKING**] SourceType::ts should set module to
unambigious (oxc-project#18873) (Boshen)

### 🚀 Features

- 500d071 minifier: Local traverse ctx and generated minifier traverse
(oxc-project#19106) (Boshen)
- 142a1be parser: Detect binary files with TS1490 error (oxc-project#19047)
(Boshen)
- e316857 allocator/bitset: Add `Ones` iterator to `BitSet` (oxc-project#19027)
(sapphi-red)
- 742ad3f minifier: Default `invalid_import_side_effects` to `false`
(oxc-project#18916) (sapphi-red)
- 0eff6be parser: Error JSX-like type assertions and generics in
`.mts`/`.cts` (oxc-project#18910) (Boshen)
- 18320c6 span: Store file extension in `SourceType` (oxc-project#18893) (Boshen)

### 🐛 Bug Fixes

- a7514e4 isolated-declarations: Preserve const context in literal type
inference (oxc-project#19178) (camc314)
- 312e756 isolated-declarations: Preserve readonly literal initializers
(oxc-project#19177) (camc314)
- d0ca8d0 isolated-declarations: Skip parenthesis when inferring type
(oxc-project#19176) (camc314)
- 110c300 oxc_ecmascript: `+[false]` and `+[true]` should evaluate to
`NaN` (oxc-project#19174) (copilot-swe-agent)
- f32ea19 semantic: Report redeclaration error for import bindings
conflicting with value declarations (oxc-project#19068) (Boshen)
- 3aeba7a semantic: Report redeclaration error for `function a() {} var
a` in module mode (oxc-project#19041) (Boshen)
- 35e32c6 coverage: Match Babel's options.json inheritance for test
fixtures (oxc-project#19002) (Boshen)
- 463d60d semantic: Skip TS2391 for standalone computed-name class
methods (oxc-project#19025) (Boshen)
- 56c086b parser: Add modifier ordering validation (TS1029) (oxc-project#19024)
(Boshen)
- 6067a49 linter/jsdoc: False positive in `check-tag-names` for `@` in
email addresses and npm scopes (oxc-project#19021) (Boshen)
- b13bb70 semantic/jsdoc: Inline tags like `{@link}` break jsdoc parsing
(oxc-project#19019) (Boshen)
- e3609e3 regular_expression: Preserve UnicodeEscape CharacterKind in
string literals (oxc-project#18998) (Boshen)
- 57917ee parser: Parse decorators on rest parameters (oxc-project#18938) (Boshen)
- 487601b napi: Disable mimalloc on Windows to fix worker_threads crash
(oxc-project#18923) (Boshen)
- 1f6b193 parser: Validate TypeScript import type options (oxc-project#18889)
(Boshen)
- 1663184 parser: Allow conditional types in function type parameters
(oxc-project#18886) (Boshen)
- 5758046 parser: Error on property access after instantiation
expression (oxc-project#18887) (Boshen)
- 5eb4a94 parser: Handle `<<` as two `<` tokens in type argument
contexts (oxc-project#18885) (Boshen)

### ⚡ Performance

- ed8c054 oxc_str: Add precomputed hash to Ident for fast HashMap
lookups (oxc-project#19143) (Boshen)
- d4a0867 transformer_plugins: Switch ReplaceGlobalDefines from Traverse
to VisitMut (oxc-project#19146) (Boshen)
- 9eb16b3 syntax: Pack ASCII identifier tables into single bitflag table
(oxc-project#19088) (Boshen)
- e7595d1 mangler: Use BitSet for exported symbols set (oxc-project#19023)
(sapphi-red)
- 2537924 semantic: Optimize scope resolution with fast paths and
inlining (oxc-project#19029) (Boshen)
- 69a8d85 mangler: Use BitSet for keep_names symbols set (oxc-project#19028)
(sapphi-red)
- f78c525 parser: Try hybrid parsing for jsx children and closing
element/fragments (oxc-project#18789) (camchenry)

Co-authored-by: camc314 <18101008+camc314@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

A-semantic Area - Semantic C-bug Category - Bug

Projects

None yet

Development

Successfully merging this pull request may close these issues.

linter: {@link Type} breaks jsdoc parsing

3 participants