[New] order: add consolidateIslands option to collapse excess spacing for aesthetically pleasing imports

[Xunnamius]

Depends on #3128

This PR implements in import/order: a new option enabling the manipulation/consolidation of newlines around imports.

A demo package containing this feature is temporarily available for easy testing:

npm install --save-dev eslint-plugin-import@npm:@-xun/eslint-plugin-import-experimental

Collapse excess spacing for aesthetically pleasing imports

This is implemented via consolidateIslands. The proposed documentation corresponding to this new feature can be previewed here.

Example

Given this code (which could be the output of a previous --fix pass):

var fs = require('fs');
var path = require('path');
var { util1, util2, util3 } = require('util');

var async = require('async');

// Ugly but technically valid

var relParent1 = require('../foo');
var {
  relParent21,
  relParent22,
  relParent23,
  relParent24,
} = require('../');
var relParent3 = require('../bar');

var { sibling1,
  sibling2, sibling3 } = require('./foo');
var sibling2 = require('./bar');
var sibling3 = require('./foobar');

And the following settings, the rule check will pass:

{
  "newlines-between": "always-and-inside-groups"
}

However, when given the following instead, the rule check will fail:

{
  "newlines-between": "always-and-inside-groups",
+ "consolidateIslands": "inside-groups"
}

With --fix yielding:

var fs = require('fs');
var path = require('path');
var { util1, util2, util3 } = require('util');

var async = require('async');

// Pretty

var relParent1 = require('../foo');

var {
  relParent21,
  relParent22,
  relParent23,
  relParent24,
} = require('../');

var relParent3 = require('../bar');

var { sibling1,
  sibling2, sibling3 } = require('./foo');

var sibling2 = require('./bar');
var sibling3 = require('./foobar');

Note how the intragroup "islands" of grouped single-line imports, as well as multi-line imports, are surrounded by new lines.

Essentially, I was looking for a newlines-between-like setting somewhere between "never" and "always-and-inside-groups". I want newlines separating groups/pathGroups imports from one another (like "always-and-inside-groups"), newlines separating imports that span multiple lines from other imports (this is the new thing), and any remaining newlines deleted or "consolidated" (like "never"). The example above demonstrates this use case.

Right now, this is achievable with newlines-between set to "always-and-inside-groups" if you add additional newlines around multi-line imports to every file by hand. The goal of consolidateIslands is to allow eslint --fix to take care of the tedium in a backward-compatible way.

There was a slight complication with consolidateIslands though: while testing across a few mid-sized repos, I discovered my naive implementation caused a conflict when enabled alongside sortTypesAmongThemselves: true, newlines-between: "always-and-inside-groups", and newlines-between-types: "never"... and then only when a normal import was followed by a multi-line type-only import. This conflict makes sense, since newlines-between-types: "never" wants no newlines ever and demands no newline separate type-only imports from normal imports (since, currently, newlines-between-types governs that space), yet consolidateIslands demands a newline separate all multi-line imports from other imports.

To solve this, the current implementation has newlines-between-types yield to consolidateIslands whenever they conflict. I've also added a test to catch any regressions around this edge case.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 95.68%. Comparing base (5e7ea1d) to head (ba167f2).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3129      +/-   ##
==========================================
+ Coverage   95.51%   95.68%   +0.17%     
==========================================
  Files          83       83              
  Lines        3659     3688      +29     
  Branches     1306     1331      +25     
==========================================
+ Hits         3495     3529      +34     
+ Misses        164      159       -5     

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