Feature: Allow Explicit Separator after Top-of-file-comments

src/preprocessors/preprocessor.ts

@@ -1,53 +1,28 @@
 import { parse as babelParser, ParserOptions } from '@babel/parser';
 import traverse, { NodePath } from '@babel/traverse';
 import { ImportDeclaration, isTSModuleDeclaration } from '@babel/types';
-import semver from 'semver';
 
-import { TYPES_SPECIAL_WORD } from '../constants';
 import { PrettierOptions } from '../types';
 import { getCodeFromAst } from '../utils/get-code-from-ast';
-import { getExperimentalParserPlugins } from '../utils/get-experimental-parser-plugins';
 import { getSortedNodes } from '../utils/get-sorted-nodes';
+import { examineAndNormalizePluginOptions } from '../utils/normalize-plugin-options';
 
 export function preprocessor(code: string, options: PrettierOptions): string {
-    const { importOrderParserPlugins, importOrder } = options;
-    let { importOrderTypeScriptVersion } = options;
-    const isTSSemverValid = semver.valid(importOrderTypeScriptVersion);
+    const { plugins, ...remainingOptions } =
+        examineAndNormalizePluginOptions(options);
 
-    if (!isTSSemverValid) {
-        console.warn(
-            `[@ianvs/prettier-plugin-sort-imports]: The option importOrderTypeScriptVersion is not a valid semver version and will be ignored.`,
-        );
-        importOrderTypeScriptVersion = '1.0.0';
-    }
-
-    // Do not combine type and value imports if `<TYPES>` is specified explicitly
-    let importOrderCombineTypeAndValueImports = importOrder.some((group) =>
-        group.includes(TYPES_SPECIAL_WORD),
-    )
-        ? false
-        : true;
-
-    const allOriginalImportNodes: ImportDeclaration[] = [];
     const parserOptions: ParserOptions = {
         sourceType: 'module',
         attachComment: true,
-        plugins: getExperimentalParserPlugins(importOrderParserPlugins),
+        plugins,
     };
 
-    // Disable importOrderCombineTypeAndValueImports if typescript is not set to a version that supports it
-    if (
-        parserOptions.plugins?.includes('typescript') &&
-        semver.lt(importOrderTypeScriptVersion, '4.5.0')
-    ) {
-        importOrderCombineTypeAndValueImports = false;
-    }
-
     const ast = babelParser(code, parserOptions);
 
     const directives = ast.program.directives;
     const interpreter = ast.program.interpreter;
 
+    const allOriginalImportNodes: ImportDeclaration[] = [];
     traverse(ast, {
         ImportDeclaration(path: NodePath<ImportDeclaration>) {
             const tsModuleParent = path.findParent((p) =>
@@ -64,10 +39,10 @@ export function preprocessor(code: string, options: PrettierOptions): string {
         return code;
     }
 
-    const nodesToOutput = getSortedNodes(allOriginalImportNodes, {
-        importOrder,
-        importOrderCombineTypeAndValueImports,
-    });
+    const nodesToOutput = getSortedNodes(
+        allOriginalImportNodes,
+        remainingOptions,
+    );
 
     return getCodeFromAst({
         nodesToOutput,

src/types.ts

@@ -1,3 +1,4 @@
+import type { ParserPlugin } from '@babel/parser';
 import {
     type EmptyStatement,
     type ExpressionStatement,
@@ -46,13 +47,28 @@ export type SomeSpecifier =
     | ImportNamespaceSpecifier;
 export type ImportRelated = ImportOrLine | SomeSpecifier;
 
+export interface InspectedAndNormalizedOptions {
+    importOrder: PrettierOptions['importOrder'];
+    importOrderCombineTypeAndValueImports: boolean;
+    hasAnyCustomGroupSeparatorsInImportOrder: boolean;
+    provideGapAfterTopOfFileComments: boolean;
+    plugins: ParserPlugin[];
+}
+
 export type GetSortedNodes = (
     nodes: ImportDeclaration[],
-    options: Pick<PrettierOptions, 'importOrder'> & {
+    options: Pick<InspectedAndNormalizedOptions, 'importOrder'> & {
         importOrderCombineTypeAndValueImports: boolean;
+        hasAnyCustomGroupSeparatorsInImportOrder?: boolean;
+        provideGapAfterTopOfFileComments?: boolean;
     },
 ) => ImportOrLine[];
 
+export type GetSortedNodesByImportOrder = (
+    nodes: ImportDeclaration[],
+    options: Pick<InspectedAndNormalizedOptions, 'importOrder'>,
+) => ImportOrLine[];
+
 export type GetChunkTypeOfNode = (node: ImportDeclaration) => ChunkType;
 
 export type GetImportFlavorOfNode = (node: ImportDeclaration) => FlavorType;
@@ -65,3 +81,7 @@ export type MergeNodesWithMatchingImportFlavors = (
 export type ExplodeTypeAndValueSpecifiers = (
     nodes: ImportDeclaration[],
 ) => ImportDeclaration[];
+
+export interface CommentAttachmentOptions {
+    provideGapAfterTopOfFileComments?: boolean;
+}

src/utils/__tests__/get-all-comments-from-nodes.spec.ts

@@ -9,12 +9,13 @@ import { expect, test } from 'vitest';
 import { getAllCommentsFromNodes } from '../get-all-comments-from-nodes';
 import { getImportNodes } from '../get-import-nodes';
 import { getSortedNodes } from '../get-sorted-nodes';
+import { testingOnly } from '../normalize-plugin-options';
 
 const getSortedImportNodes = (code: string, options?: ParserOptions) => {
     const importNodes: ImportDeclaration[] = getImportNodes(code, options);
 
     return getSortedNodes(importNodes, {
-        importOrder: [],
+        importOrder: testingOnly.normalizeImportOrderOption([]),
         importOrderCombineTypeAndValueImports: true,
     });
 };

src/utils/__tests__/get-code-from-ast.spec.ts

@@ -4,6 +4,9 @@ import { expect, test } from 'vitest';
 import { getCodeFromAst } from '../get-code-from-ast';
 import { getImportNodes } from '../get-import-nodes';
 import { getSortedNodes } from '../get-sorted-nodes';
+import { testingOnly } from '../normalize-plugin-options';
+
+const emptyImportOrder = testingOnly.normalizeImportOrderOption([]);
 
 test('sorts imports correctly', () => {
     const code = `import z from 'z';
@@ -15,7 +18,7 @@ import a from 'a';
 `;
     const importNodes = getImportNodes(code);
     const sortedNodes = getSortedNodes(importNodes, {
-        importOrder: [],
+        importOrder: emptyImportOrder,
         importOrderCombineTypeAndValueImports: true,
     });
     const formatted = getCodeFromAst({
@@ -47,7 +50,7 @@ import type {See} from 'c';
 `;
     const importNodes = getImportNodes(code, { plugins: ['typescript'] });
     const sortedNodes = getSortedNodes(importNodes, {
-        importOrder: [],
+        importOrder: emptyImportOrder,
         importOrderCombineTypeAndValueImports: true,
     });
     const formatted = getCodeFromAst({

src/utils/__tests__/get-comment-registry.spec.ts

@@ -10,7 +10,7 @@ import {
     attachCommentsToOutputNodes,
     CommentAssociation,
     getCommentRegistryFromImportDeclarations,
-    testingOnlyExports,
+    testingOnly,
 } from '../get-comment-registry';
 
 describe('getCommentRegistryFromImportDeclarations', () => {
@@ -64,7 +64,7 @@ describe('attachCommentsToOutputNodes', () => {
                     needsTopOfFileOwner: true,
                     comment,
                     ownerIsSpecifier: false,
-                    commentId: testingOnlyExports.nodeId(comment),
+                    commentId: testingOnly.nodeId(comment),
                     owner: firstImport,
                     association: CommentAssociation.trailing,
                     processingPriority: 0,

src/utils/__tests__/get-sorted-nodes-by-import-order.spec.ts

@@ -5,6 +5,7 @@ import { getImportNodes } from '../get-import-nodes';
 import { getSortedNodesByImportOrder } from '../get-sorted-nodes-by-import-order';
 import { getSortedNodesModulesNames } from '../get-sorted-nodes-modules-names';
 import { getSortedNodesNamesAndNewlines } from '../get-sorted-nodes-names-and-newlines';
+import { testingOnly } from '../normalize-plugin-options';
 
 const code = `// first comment
 // second comment
@@ -28,8 +29,7 @@ import Xa from 'Xa';
 test('it returns all sorted nodes', () => {
     const result = getImportNodes(code);
     const sorted = getSortedNodesByImportOrder(result, {
-        importOrder: ['^[./]'],
-        importOrderCombineTypeAndValueImports: true,
+        importOrder: testingOnly.normalizeImportOrderOption(['^[./]']),
     }) as ImportDeclaration[];
 
     expect(getSortedNodesNamesAndNewlines(sorted)).toEqual([
@@ -77,8 +77,13 @@ test('it returns all sorted nodes', () => {
 test('it returns all sorted nodes with sort order', () => {
     const result = getImportNodes(code);
     const sorted = getSortedNodesByImportOrder(result, {
-        importOrder: ['^a$', '^t$', '^k$', '^B', '^[./]'],
-        importOrderCombineTypeAndValueImports: true,
+        importOrder: testingOnly.normalizeImportOrderOption([
+            '^a$',
+            '^t$',
+            '^k$',
+            '^B',
+            '^[./]',
+        ]),
     }) as ImportDeclaration[];
     expect(getSortedNodesNamesAndNewlines(sorted)).toEqual([
         'node:fs/promises',
@@ -133,8 +138,7 @@ import {type B, A} from 'z';
         plugins: ['typescript'],
     });
     const sorted = getSortedNodesByImportOrder(result, {
-        importOrder: ['^[./]'],
-        importOrderCombineTypeAndValueImports: true,
+        importOrder: testingOnly.normalizeImportOrderOption(['^[./]']),
     }) as ImportDeclaration[];
     expect(getSortedNodesNamesAndNewlines(sorted)).toEqual(['k', 't', 'z']);
     expect(
@@ -153,8 +157,7 @@ import {type B, A} from 'z';
 test('it returns all sorted nodes with builtin specifiers at the top', () => {
     const result = getImportNodes(code);
     const sorted = getSortedNodesByImportOrder(result, {
-        importOrder: ['^[./]'],
-        importOrderCombineTypeAndValueImports: true,
+        importOrder: testingOnly.normalizeImportOrderOption(['^[./]']),
     }) as ImportDeclaration[];
 
     expect(getSortedNodesNamesAndNewlines(sorted)).toEqual([
@@ -179,8 +182,13 @@ test('it returns all sorted nodes with builtin specifiers at the top', () => {
 test('it returns all sorted nodes with custom third party modules and builtins at top', () => {
     const result = getImportNodes(code);
     const sorted = getSortedNodesByImportOrder(result, {
-        importOrder: ['^a$', '<THIRD_PARTY_MODULES>', '^t$', '^k$', '^[./]'],
-        importOrderCombineTypeAndValueImports: true,
+        importOrder: testingOnly.normalizeImportOrderOption([
+            '^a$',
+            '<THIRD_PARTY_MODULES>',
+            '^t$',
+            '^k$',
+            '^[./]',
+        ]),
     }) as ImportDeclaration[];
     expect(getSortedNodesNamesAndNewlines(sorted)).toEqual([
         'node:fs/promises',
@@ -204,15 +212,14 @@ test('it returns all sorted nodes with custom third party modules and builtins a
 test('it returns all sorted nodes with custom separation', () => {
     const result = getImportNodes(code);
     const sorted = getSortedNodesByImportOrder(result, {
-        importOrder: [
+        importOrder: testingOnly.normalizeImportOrderOption([
             '^a$',
             '<THIRD_PARTY_MODULES>',
             '^t$',
             '',
             '^k$',
             '^[./]',
-        ],
-        importOrderCombineTypeAndValueImports: true,
+        ]),
     }) as ImportDeclaration[];
     expect(getSortedNodesNamesAndNewlines(sorted)).toEqual([
         'node:fs/promises',
@@ -237,7 +244,7 @@ test('it returns all sorted nodes with custom separation', () => {
 test('it does not add multiple custom import separators', () => {
     const result = getImportNodes(code);
     const sorted = getSortedNodesByImportOrder(result, {
-        importOrder: [
+        importOrder: testingOnly.normalizeImportOrderOption([
             '^a$',
             '<THIRD_PARTY_MODULES>',
             '^t$',
@@ -246,8 +253,7 @@ test('it does not add multiple custom import separators', () => {
             '',
             '^k$',
             '^[./]',
-        ],
-        importOrderCombineTypeAndValueImports: true,
+        ]),
     }) as ImportDeclaration[];
     expect(getSortedNodesNamesAndNewlines(sorted)).toEqual([
         'node:fs/promises',

src/utils/__tests__/get-sorted-nodes.spec.ts

@@ -5,6 +5,7 @@ import { getImportNodes } from '../get-import-nodes';
 import { getSortedNodes } from '../get-sorted-nodes';
 import { getSortedNodesModulesNames } from '../get-sorted-nodes-modules-names';
 import { getSortedNodesNamesAndNewlines } from '../get-sorted-nodes-names-and-newlines';
+import { testingOnly } from '../normalize-plugin-options';
 
 const code = `
 import "se3";
@@ -28,7 +29,7 @@ import "se2";
 test('it returns all sorted nodes, preserving the order side effect nodes', () => {
     const result = getImportNodes(code);
     const sorted = getSortedNodes(result, {
-        importOrder: [],
+        importOrder: testingOnly.normalizeImportOrderOption([]),
         importOrderCombineTypeAndValueImports: true,
     }) as ImportDeclaration[];
     expect(getSortedNodesNamesAndNewlines(sorted)).toEqual([

src/utils/__tests__/merge-nodes-with-matching-flavors.spec.ts

@@ -4,11 +4,13 @@ import { expect, test } from 'vitest';
 import { getCodeFromAst } from '../get-code-from-ast';
 import { getImportNodes } from '../get-import-nodes';
 import { getSortedNodes } from '../get-sorted-nodes';
+import { examineAndNormalizePluginOptions } from '../normalize-plugin-options';
 
-const defaultOptions = {
+const defaultOptions = examineAndNormalizePluginOptions({
     importOrder: [''], // Separate side-effect and ignored chunks, for easier test readability
-    importOrderCombineTypeAndValueImports: true,
-};
+    importOrderTypeScriptVersion: '5.0.0',
+    importOrderParserPlugins: [],
+});
 
 test('should merge duplicate imports within a given chunk', () => {
     const code = `

src/utils/__tests__/remove-nodes-from-original-code.spec.ts

@@ -5,6 +5,7 @@ import { expect, test } from 'vitest';
 import { getAllCommentsFromNodes } from '../get-all-comments-from-nodes';
 import { getImportNodes } from '../get-import-nodes';
 import { getSortedNodes } from '../get-sorted-nodes';
+import { testingOnly } from '../normalize-plugin-options';
 import { removeNodesFromOriginalCode } from '../remove-nodes-from-original-code';
 
 const code = `"some directive";// first comment
@@ -23,7 +24,7 @@ test('it should remove nodes from the original code', () => {
     const ast = babelParser(code, { sourceType: 'module' });
     const importNodes = getImportNodes(code);
     const sortedNodes = getSortedNodes(importNodes, {
-        importOrder: [],
+        importOrder: testingOnly.normalizeImportOrderOption([]),
         importOrderCombineTypeAndValueImports: true,
     });
     const allCommentsFromImports = getAllCommentsFromNodes(sortedNodes);

src/utils/adjust-comments-on-sorted-nodes.ts

@@ -1,6 +1,6 @@
 import { removeComments, type ImportDeclaration } from '@babel/types';
 
-import { ImportOrLine } from '../types';
+import { CommentAttachmentOptions, ImportOrLine } from '../types';
 import {
     attachCommentsToOutputNodes,
     getCommentRegistryFromImportDeclarations,
@@ -17,6 +17,7 @@ import {
 export const adjustCommentsOnSortedNodes = (
     originalDeclarationNodes: readonly ImportDeclaration[],
     finalNodes: readonly ImportOrLine[],
+    options: CommentAttachmentOptions,
 ) => {
     const outputNodes: ImportDeclaration[] = finalNodes.filter(
         (n) => n.type === 'ImportDeclaration',
@@ -46,7 +47,12 @@ export const adjustCommentsOnSortedNodes = (
         return noDirectCommentsNode;
     });
 
-    attachCommentsToOutputNodes(registry, finalNodesClone, firstImport);
+    attachCommentsToOutputNodes(
+        registry,
+        finalNodesClone,
+        firstImport,
+        options,
+    );
 
     return finalNodesClone;
 };