[New] order: add named.orderByLocalName option to sort aliased specifiers by local name

[KAMRONBEK]

Problem

With named: true and alphabetize: { order: 'asc' }, import { b, a as c } from 'lib'; is reported because named ordering always sorts by the original (imported/exported) name — here a — with no way to order by the local alias c. #3181 asks for an option to sort by the alias instead; ljharb: "That seems like a reasonable option to add." (labels: help wanted, semver-minor).

Implementation

New named.sortBy option following the existing named option-object shape (like named.types):

• 'name' (default — current behavior): sort aliased specifiers by their original name (the name to the left of as).
• 'alias': sort aliased specifiers by their alias (the name to the right of as — the local name of an aliased import / destructured require, or the exported name of an aliased export / CJS export), falling back to the name when not aliased.

Changes in src/rules/order.js:

• schema: sortBy: { type: 'string', enum: ['name', 'alias'] } on the named object form;
• create(): sortBy: 'name' default merged into the normalized named options;
• makeNamedOrderReport(): in alias mode the composite sort key becomes `${alias || name}:${name}` (mirroring the existing `${name}:${alias}` scheme, so duplicate keys stay distinct), and the report displayName becomes name as alias so messages are unambiguous, e.g. '`b` import should occur before import of `c as z`'.

The autofix needs no changes — it already swaps whole specifier texts, so reordering follows the new ranks.

Docs

docs/rules/order.md named section: updated the Valid values line and added a named.sortBy value list with a pass/fail example, matching the existing named.types doc format.

Tests

7 new cases in tests/src/rules/order.js, following the surrounding named test style:

• valid: the exact example from the issue (import { b, a as c } with sortBy: 'alias'); a combined aliased export { Z as A, B } + destructured require + module.exports = { b: B, a: Z } case; explicit sortBy: 'name' keeping current behavior;
• invalid (with autofix output and messages): aliased imports, aliased exports + destructured require in one test, module.exports object exports, and explicit sortBy: 'name' on the issue's example.

All 326 tests in the file pass; the 7 new tests fail without the implementation (verified by temporarily reverting src/rules/order.js). Default behavior is unchanged (the full pre-existing suite passes untouched), so this is semver-minor.

Fixes #3181.

[KAMRONBEK]

@ljharb TL;DR for the help-wanted #3181: adds a named.orderByLocalName option to import/order so aliased specifiers can sort by the local name (import { b as a } sorts as a) instead of the imported/exported name — following the existing named option object shape. Comparator + schema + docs/rules/order.md + tests covering both settings for imports AND exports incl. autofix output. Semver-minor, default behavior unchanged. CHANGELOG entry included.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 79.61%. Comparing base (1a39fb8) to head (3b0ac8e).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3272      +/-   ##
==========================================
+ Coverage   79.58%   79.61%   +0.02%     
==========================================
  Files          98       98              
  Lines        4527     4533       +6     
  Branches     1529     1534       +5     
==========================================
+ Hits         3603     3609       +6     
  Misses        924      924              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.