feat(useSortedKeys): add groupByNesting option

[PaulRBerg]

Implements a new groupByNesting option for the useSortedKeys assist that groups object keys by their value's nesting depth before applying alphabetical sorting.

Nesting depth classification:

• Depth 0 (simple): primitives, single-line arrays
• Depth 1 (nested): objects, multi-line arrays

When enabled, simple values are sorted alphabetically first, followed by nested values sorted alphabetically. This addresses the common use case where developers want scalar properties at the top of objects, with complex nested structures appearing at the bottom.

Implementation details:

• Added group_by_nesting: bool field to UseSortedKeysOptions
• Implemented get_nesting_depth_js() for JavaScript AST nodes
• Implemented get_nesting_depth() for JSON AST nodes
• Updated sorting comparators to use tuple (depth, name) ordering
• Works with both natural and lexicographic sort orders

Configuration:

{
  "assist": {
    "actions": {
      "source": {
        "useSortedKeys": {
          "level": "on",
          "options": {
            "groupByNesting": true
          }
        }
      }
    }
  }
}

Summary

Discussed in https://github.com/biomejs/biome/discussions/7331

Test Plan

• 4 JS test cases (natural + lexicographic × grouping on/off)
• 4 JSON test cases (natural + lexicographic × grouping on/off)
• All snapshot tests generated and validated

[changeset-bot[bot]]

🦋 Changeset detected

Latest commit: 0dde4e6068d9809a389451c3f1b222dfcfe55b87

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

This PR includes changesets to release 14 packages

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

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[bot]]

Walkthrough

This pull request introduces a new groupByNesting option to the useSortedKeys assist for both JavaScript and JSON analysis. When enabled, this option groups object keys by their value's nesting depth before sorting alphabetically, placing simple values (primitives and single-line arrays) before nested values (objects and multi-line arrays). The implementation adds helper functions to compute nesting depth, updates sorting logic in both rule and action paths, adds the option to rule options, and includes tests for lexicographic and natural sort orders.

Suggested labels

A-Project

Suggested reviewers

• dyc3

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: adding a groupByNesting option to the useSortedKeys assist feature.
Description check	✅ Passed	The description is directly related to the changeset, clearly explaining the feature, implementation details, configuration, and test coverage.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

• [ ] Create PR with unit tests
• [ ] Post copyable unit tests in a comment

---

📜 Recent review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 092b6201c9225b66b458ea9b4d81cdc905769322 and 62fb192d03b7460d30d04c0de532e73a5ced1e8e.

📒 Files selected for processing (1)

• .changeset/group-by-nesting-feature.md (1 hunks)

🚧 Files skipped from review as they are similar to previous changes (1)

• .changeset/group-by-nesting-feature.md

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[PaulRBerg]

@coderabbitai generate docstrings

[coderabbitai[bot]]

✅ Actions performed

Initiated docstring generation; will generate only if new commits exist.

[coderabbitai[bot]]

[!NOTE] Docstrings generation - SUCCESS Generated docstrings for this pull request at https://github.com/biomejs/biome/pull/7800

[PaulRBerg]

The CI has failed but I think it's related to the AWS outage today?

[ematipico]

Please point this PR to next, as per contribution guidelines

[PaulRBerg]

@ematipico saw you closed this, will this be implemented in another PR? How can I help?

[ematipico]

It wasn't on purpose, I reopned the PR

[PaulRBerg]

Thanks for your feedback @ematipico - the PR is ready for reviewing again.

[codspeed-hq[bot]]

CodSpeed Performance Report

Merging #7799 will not alter performance

_{Comparing PaulRBerg:feat/use-sorted-keys-group-by-nesting (0dde4e6) with next (5901d79)}

Summary

✅ 53 untouched
⏩ 85 skipped[^skipped]

[^skipped]: 85 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.