Skip to content

docs(organizeImports): revamp user-facing docs#9887

Merged
Conaclos merged 17 commits intonextfrom
conaclos/organizeImports-docs
Apr 14, 2026
Merged

docs(organizeImports): revamp user-facing docs#9887
Conaclos merged 17 commits intonextfrom
conaclos/organizeImports-docs

Conversation

@Conaclos
Copy link
Copy Markdown
Member

@Conaclos Conaclos commented Apr 9, 2026

Summary

This PR improves the docs of our import organizer.
The new docs is hopefully more user-centric and goal-oriented than the previous one.

The main structure is:

  • Quick explanation of the default behavior of the import organizer
  • Introduce the three options to customize the rule behavior
  • Provide common usages
  • Detailed behavior of the organizer ("How it works")

This work is based on #9762

Once merged I plan to submit the same PR on main without the sortBareimports option which was recently added to next.

Test Plan

CI should be green.

Docs

This is the purpose of this PR.

@Conaclos Conaclos changed the title refactor(organizeImports): revamp docs docs(organizeImports): revamp user-facing docs Apr 9, 2026
@changeset-bot
Copy link
Copy Markdown

changeset-bot Bot commented Apr 9, 2026

⚠️ No Changeset found

Latest commit: 5445c17

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

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

@github-actions github-actions Bot added A-Linter Area: linter L-JavaScript Language: JavaScript and super languages labels Apr 9, 2026
@coderabbitai
Copy link
Copy Markdown
Contributor

coderabbitai Bot commented Apr 9, 2026

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

  • @coderabbitai resume to resume automatic reviews.
  • @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

  • ▶️ Resume reviews
  • 🔍 Trigger review

Walkthrough

The documentation comment for the OrganizeImports source rule was rewritten. It now describes default distance-based ordering (external → local aliases → local files), natural ordering for sources at equal distance, merging of imports/exports from the same source, and alphabetical sorting of named specifiers and attributes. Examples and option descriptions (groups, sortBareImports, identifierOrder) were updated; no code, control flow, or public API declarations changed.

Suggested reviewers

  • ematipico
  • dyc3
🚥 Pre-merge checks | ✅ 2
✅ Passed checks (2 passed)
Check name Status Explanation
Title check ✅ Passed The title accurately summarizes the main change: documentation improvements for the import organizer rule.
Description check ✅ Passed The description is directly related to the changeset, clearly explaining the documentation restructuring and improvements made to the import organizer.

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

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch conaclos/organizeImports-docs

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

Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

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

Actionable comments posted: 6

🤖 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/assist/source/organize_imports.rs`:
- Line 593: Fix the typo in the doc comment inside organize_imports.rs where the
sentence starts with "mports"—change it to "Imports" (capital I) so the comment
reads "Imports from the same source in the same chunk are merged when
possible:"; update the doc comment text near the organize_imports
module/function to correct the spelling and capitalization.
- Line 382: Fix the typo in the doc comment inside organize_imports.rs: change
"theh" to "the" in the sentence "To place them at the end, use theh following
configuration." so the comment reads "To place them at the end, use the
following configuration."; update the comment near the organize_imports
module/function documentation to correct this single-word misspelling.
- Line 182: Fix the doc comment in organize_imports.rs that currently reads '///
Setting `"type": false` matches only non-type imports anmd exports].' — correct
the typo "anmd" to "and" and remove the extraneous trailing ']' so it reads '///
Setting `"type": false` matches only non-type imports and exports.'; update the
comment next to the `Setting "type": false` doc line in the organize imports
code to reflect this change.
- Line 129: Typo in the documentation comment: change the word "soretd" to
"sorted" in the doc comment near the organize imports logic; locate the comment
string "/// ...is soretd as:" in organize_imports.rs (associated with the
organize imports functionality) and update it to "/// ...is sorted as:" so the
docs read correctly.
- Line 238: The doc comment in organize_imports.rs contains a typo "a `natural`
sort_" with an extra trailing underscore; edit the documentation string (near
the organize_imports module/any function or struct that contains this comment)
to remove the trailing underscore so it reads "a `natural` sort". Ensure only
the stray '_' after the backtick-enclosed word is deleted and formatting of the
surrounding comment remains unchanged.
- Line 687: The example doc comment contains an unterminated array literal in
the import-organizing example; fix it by closing the array literal (add the
missing closing bracket and any required trailing comma/semicolon) and ensure
the surrounding code block and Rust example are properly terminated so the
snippet compiles; locate the example in the organize_imports.rs documentation
comment and update the example array literal accordingly.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 4e071327-008d-422f-9b60-07f6563f6a04

📥 Commits

Reviewing files that changed from the base of the PR and between 5a594fb and 849a22c.

📒 Files selected for processing (1)
  • crates/biome_js_analyze/src/assist/source/organize_imports.rs

Comment thread crates/biome_js_analyze/src/assist/source/organize_imports.rs Outdated
Comment thread crates/biome_js_analyze/src/assist/source/organize_imports.rs Outdated
Comment thread crates/biome_js_analyze/src/assist/source/organize_imports.rs Outdated
Comment thread crates/biome_js_analyze/src/assist/source/organize_imports.rs Outdated
Comment thread crates/biome_js_analyze/src/assist/source/organize_imports.rs Outdated
Comment thread crates/biome_js_analyze/src/assist/source/organize_imports.rs
@codspeed-hq
Copy link
Copy Markdown

codspeed-hq Bot commented Apr 9, 2026

Merging this PR will not alter performance

✅ 58 untouched benchmarks
⏩ 196 skipped benchmarks1


Comparing conaclos/organizeImports-docs (5445c17) with next (f7c34d9)

Open in CodSpeed

Footnotes

  1. 196 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.

Copy link
Copy Markdown
Member

@ematipico ematipico left a comment

Choose a reason for hiding this comment

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

Preliminary feedback

Comment thread crates/biome_js_analyze/src/assist/source/organize_imports.rs Outdated
Comment thread crates/biome_js_analyze/src/assist/source/organize_imports.rs Outdated
Comment thread crates/biome_js_analyze/src/assist/source/organize_imports.rs Outdated
Comment thread crates/biome_js_analyze/src/assist/source/organize_imports.rs Outdated
Comment thread crates/biome_js_analyze/src/assist/source/organize_imports.rs Outdated
Comment thread crates/biome_js_analyze/src/assist/source/organize_imports.rs Outdated
Comment thread crates/biome_js_analyze/src/assist/source/organize_imports.rs Outdated
Comment thread crates/biome_js_analyze/src/assist/source/organize_imports.rs Outdated
Copy link
Copy Markdown
Member

@ematipico ematipico left a comment

Choose a reason for hiding this comment

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

Another review left

Comment thread crates/biome_js_analyze/src/assist/source/organize_imports.rs Outdated
Comment thread crates/biome_js_analyze/src/assist/source/organize_imports.rs Outdated
Comment thread crates/biome_js_analyze/src/assist/source/organize_imports.rs Outdated
Comment thread crates/biome_js_analyze/src/assist/source/organize_imports.rs Outdated
Comment thread crates/biome_js_analyze/src/assist/source/organize_imports.rs Outdated
Comment thread crates/biome_js_analyze/src/assist/source/organize_imports.rs
Comment thread crates/biome_js_analyze/src/assist/source/organize_imports.rs Outdated
Comment thread crates/biome_js_analyze/src/assist/source/organize_imports.rs
Comment thread crates/biome_js_analyze/src/assist/source/organize_imports.rs Outdated
Comment thread crates/biome_js_analyze/src/assist/source/organize_imports.rs Outdated
@Conaclos Conaclos requested a review from ematipico April 14, 2026 11:56
@Conaclos
Copy link
Copy Markdown
Member Author

Conaclos commented Apr 14, 2026

The full_options examples seem not work. This causes the CI to fail. Perhaps it is not possible to enable an extra rule in docs.

@ematipico
Copy link
Copy Markdown
Member

Maybe it works only for lint rules, and not assist actions. We can add ignore for now, and fix it later

@Conaclos Conaclos force-pushed the conaclos/organizeImports-docs branch from e297288 to 6b36771 Compare April 14, 2026 19:31
@github-actions github-actions Bot added the A-CLI Area: CLI label Apr 14, 2026
@Conaclos
Copy link
Copy Markdown
Member Author

The remaining CI failures are caused by other merged PRs.

@Conaclos Conaclos merged commit 11f5460 into next Apr 14, 2026
26 of 28 checks passed
@Conaclos Conaclos deleted the conaclos/organizeImports-docs branch April 14, 2026 20:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

A-CLI Area: CLI A-Linter Area: linter L-JavaScript Language: JavaScript and super languages

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants