Special case import grouping when source code file contains a license header.

[aabmets]

Currently, Biome does not differentiate between regular comments and license headers in the imports section at the top of source code files. This produces the effect, whereby some imports might be moved at the top of the file on line 1, above the license header, when imports are sorted.

Using license headers at the top of source code files is a standard practice in public-domain and proprietary software, where companies and organizations need to clearly outline the legal permissions that govern the given source code. This is standard use case and Biome does not currently respect this.

The proposal is to modify the imports sorting algorithm, such that it will always treat a multiline comment at the top of a source code file as a license header and will not move any import statements above it.

This is a call to all readers to please voice your opinion on this subject, whether you agree or disagree with this proposal, because the Biome devs need community support for implementing standard use cases into the Biome software.

This is the invalid result when biome check --write is executed on a file which
requires import sorting and contains a license header:

import ElectronLogo from "@assets/electron.svg";
/*
 *   European Union Public License 1.2
 *
 *   Copyright (c) 2024, My Company Name
 *
 *   The contents of this file are subject to the terms and conditions defined in the License.
 *   You may not use, modify, or distribute this file except in compliance with the License.
 *
 *   SPDX-License-Identifier: EUPL-1.2
 */
import { Fragment, type ReactNode } from "react";
import Versions from "./Versions.tsx";

This is the expected result:

/*
 *   European Union Public License 1.2
 *
 *   Copyright (c) 2024, My Company Name
 *
 *   The contents of this file are subject to the terms and conditions defined in the License.
 *   You may not use, modify, or distribute this file except in compliance with the License.
 *
 *   SPDX-License-Identifier: EUPL-1.2
 */
import ElectronLogo from "@assets/electron.svg";
import { Fragment, type ReactNode } from "react";
import Versions from "./Versions.tsx";

This discussion is motivated from the following issue: #4210 (comment)

[dyc3]

It's important to note that this behavior has a workaround (as stated in the linked issue).

Adding an extra newline after the license comment will prevent the import sorter from moving it. Playground

That being said, I think this would be nice to have because it lowers one more barrier for adoption.

[ematipico]

How can Biome understand a license banner from a normal comment? I'm out of ideas, looking for some

[aabmets]

Why would Biome need to move an import statement above the comment that describes the group, if it is the first (or only) group in the file? If it is valid to sort imports such that the comment that describes the group remains above the group, then under no circumstance should Biome move any import statements above the comment that describes the group, irrespective if it is the first (or only) group, or a subsequent group. Whether the comment is a multiline or a single-line comment is completely irrelevant.

[aabmets]

Please take a look at this playground example, how Biome does not respect the location of import group descriptive comments: LINK

Under what circumstance can this sorting algorithm be considered to behave correctly:

import ElectronLogo from "@assets/electron.svg";
// My first group
import { Fragment, type ReactNode } from "react";
import Versions from "./Versions.tsx";

import ElectronLogo2 from "@assets/electron.svg";
// My second group
import { Fragment2, type ReactNode2 } from "react";
import Versions2 from "./Versions.tsx";

This should be the expected result:

// My first group
import ElectronLogo from "@assets/electron.svg";
import { Fragment, type ReactNode } from "react";
import Versions from "./Versions.tsx";

// My second group
import ElectronLogo2 from "@assets/electron.svg";
import { Fragment2, type ReactNode2 } from "react";
import Versions2 from "./Versions.tsx";

[aabmets]

The same goes for multiline comments. A comment that is written above a group must be considered to be part of the group and must behave like a header field of an excel table column. When you sort rows in excel table by row values, the column header is kept at the top of the file and not sorted into X position along with the other row values. Inserting a newline after the comment creates a separate group specifically for the comment itself, which is why Biome does not sort other import statements above it, but this is not a solution to the problem being described.

[Conaclos]

We can understand your point. However, license header don't comment an import block. It seems good to add a blank line to separate the license header from the imports.

[dyc3]

License comments are usually a few lines long, and they usually contain the word "license". They are always at the top of the file (by convention).

I think we can reliably detect license comments via some set of these signals:

• is the comment at the very top of the file?
• is it a multi line comment >4 lines long?
• does it contain the word "license"?

[aabmets]

@ematipico @Conaclos

Here, I implemented the functionality for you in Python and ChatGPT 4o translated it into Rust:
For Python: sort_imports_python_v2.py.txt
For Rust: sort_imports_rust_v2.rs.txt

EDIT: Fixed a minor bug which prevented a newline from being placed between import groups.
EDIT 2: Removed attitude.

[ematipico]

Why are you being adamantly against this?

I have never said I am against this. Please try to keep this civil, and let's discuss the technical aspects of the suggestion. There is no need to jump to conclusions just because the maintainers have different ideas from yours.

[aabmets]

I have provided the technical implementation in my previous comment. Thank you for taking it into consideration.

[Conaclos]

I am working on #3015. I will consider your request.