fix(useSemanticElements): don't flag elements and roles

[ematipico]

Summary

This PR closes #5212

There was some overlap with noRedundantRoles. The new code now makes sure that useSemanticElements doesn't flag them.

PR created with Claude Code.

Test Plan

Added new tests. Updated current snapshots

Docs

Updated the docs to reflect the change

[changeset-bot]

🦋 Changeset detected

Latest commit: 8e97702

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 13 packages

Name	Type
@biomejs/biome	Patch
@biomejs/cli-win32-x64	Patch
@biomejs/cli-win32-arm64	Patch
@biomejs/cli-darwin-x64	Patch
@biomejs/cli-darwin-arm64	Patch
@biomejs/cli-linux-x64	Patch
@biomejs/cli-linux-arm64	Patch
@biomejs/cli-linux-x64-musl	Patch
@biomejs/cli-linux-arm64-musl	Patch
@biomejs/wasm-web	Patch
@biomejs/wasm-bundler	Patch
@biomejs/wasm-nodejs	Patch
@biomejs/backend-jsonrpc	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: ffba17ef-f8a2-4b16-a574-c41d063fe4ab

📥 Commits

Reviewing files that changed from the base of the PR and between 162b3a1 and 8e97702.

⛔ Files ignored due to path filters (2)

• crates/biome_js_analyze/tests/specs/a11y/useSemanticElements/invalid.jsx.snap is excluded by !**/*.snap and included by **
• crates/biome_js_analyze/tests/specs/a11y/useSemanticElements/valid.jsx.snap is excluded by !**/*.snap and included by **

📒 Files selected for processing (3)

• crates/biome_js_analyze/src/lint/a11y/use_semantic_elements.rs
• crates/biome_js_analyze/tests/specs/a11y/useSemanticElements/invalid.jsx
• crates/biome_js_analyze/tests/specs/a11y/useSemanticElements/valid.jsx

---

Walkthrough

The change updates the useSemanticElements lint rule to avoid reporting a diagnostic when a semantic HTML element already includes the matching role attribute (e.g.,

). Such cases are now left to the noRedundantRoles rule. The patch adds an early-return and redundancy checks in the rule logic, updates tests to include semantic elements with matching roles, and adds a changeset for a patch release.

Possibly related PRs

• fix: remove option, combobox, listbox from semantic element suggestions #7129 — Modifies the same use_semantic_elements rule and adjusts its runtime checks in the rule's run logic.
• fix(useSemanticElements): exclude components and custom elements #7348 — Adds early-exit checks to the use_semantic_elements rule to prevent false positives for already-semantic elements.

Suggested reviewers

• dyc3
• siketyan

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: fixing useSemanticElements to avoid flagging semantic elements that already have matching role attributes.
Description check	✅ Passed	The description is directly related to the changeset, referencing issue #5212, explaining the overlap with noRedundantRoles, and mentioning test additions and documentation updates.
Linked Issues check	✅ Passed	The changes successfully address issue #5212 by preventing useSemanticElements from flagging semantic elements with matching role attributes, delegating that responsibility to noRedundantRoles [#5212].
Out of Scope Changes check	✅ Passed	All changes are directly within scope: the lint rule logic update, test additions for valid and invalid cases, and the changeset file are all aligned with fixing the false positive reported in #5212.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch fix/semantic-elements

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@crates/biome_js_analyze/src/lint/a11y/use_semantic_elements.rs`:
- Around line 117-121: The current guard using is_already_semantic only compares
tag names (semantic_elements/related_elements .any(|instance|
instance.element.as_str() == element_name)), which causes false negatives for
constrained mappings (e.g., role -> input[type=checkbox]); update the comparison
to verify both tag and required attributes: iterate
semantic_elements.chain(related_elements) and for each instance check that
instance.element == element_name AND that all of instance.required_attributes
(or equivalent metadata on the mapping) are present and match in the current
node's attributes (use the node's attributes accessor where this check runs).
Replace the simple tag equality with this tag+required-attributes match to
ensure constrained elements are recognized correctly.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 59287639-57dd-481f-ba2c-6584ed217bc1

📥 Commits

Reviewing files that changed from the base of the PR and between 2a29e0d and 162b3a1.

⛔ Files ignored due to path filters (3)

• crates/biome_js_analyze/tests/specs/a11y/useSemanticElements/invalid.jsx.snap is excluded by !**/*.snap and included by **
• crates/biome_js_analyze/tests/specs/a11y/useSemanticElements/invalid_self_closing.jsx.snap is excluded by !**/*.snap and included by **
• crates/biome_js_analyze/tests/specs/a11y/useSemanticElements/valid.jsx.snap is excluded by !**/*.snap and included by **

📒 Files selected for processing (3)

• .changeset/fix-use-semantic-elements-false-positive.md
• crates/biome_js_analyze/src/lint/a11y/use_semantic_elements.rs
• crates/biome_js_analyze/tests/specs/a11y/useSemanticElements/valid.jsx

[codspeed-hq]

Merging this PR will not alter performance

✅ 58 untouched benchmarks
⏩ 156 skipped benchmarks¹

---

_{Comparing fix/semantic-elements (8e97702) with main (59c086a)²}

Footnotes

1. 156 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 (35d2c33) during the generation of this report, so 59c086a was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩