feat: added support for sort-imports-ignore

docs/TROUBLESHOOTING.md

@@ -90,3 +90,7 @@ via prettier config.
     plugins: [require('@trivago/prettier-plugin-sort-imports')],
   }
 ```
+
+#### Q. How can I prevent the plugin from reordering specific import statements?
+
+Due to the complexity of maintaining the position of certain imports while reordering others, you can prevent the plugin from rearranging your file by adding the following comment at the top of your file: `// sort-imports-ignore`.

src/constants.ts

@@ -7,6 +7,8 @@ export const jsx: ParserPlugin = 'jsx';
 
 export const newLineCharacters = '\n\n';
 
+export const sortImportsIgnoredComment = 'sort-imports-ignore';
+
 /*
  * Used to mark the position between RegExps,
  * where the not matched imports should be placed

src/index.ts

@@ -1,7 +1,7 @@
 import { parsers as babelParsers } from 'prettier/parser-babel';
 import { parsers as flowParsers } from 'prettier/parser-flow';
-import { parsers as typescriptParsers } from 'prettier/parser-typescript';
 import { parsers as htmlParsers } from 'prettier/parser-html';
+import { parsers as typescriptParsers } from 'prettier/parser-typescript';
 
 import { defaultPreprocessor } from './preprocessors/default-processor';
 import { vuePreprocessor } from './preprocessors/vue-preprocessor';

src/preprocessors/preprocessor.ts

@@ -6,6 +6,7 @@ import { extractASTNodes } from '../utils/extract-ast-nodes';
 import { getCodeFromAst } from '../utils/get-code-from-ast';
 import { getExperimentalParserPlugins } from '../utils/get-experimental-parser-plugins';
 import { getSortedNodes } from '../utils/get-sorted-nodes';
+import { isSortImportsIgnored } from '../utils/is-sort-imports-ignored';
 
 export function preprocessor(code: string, options: PrettierOptions) {
     const {
@@ -33,6 +34,7 @@ export function preprocessor(code: string, options: PrettierOptions) {
 
     // short-circuit if there are no import declaration
     if (importNodes.length === 0) return code;
+    if (isSortImportsIgnored(importNodes)) return code;
 
     const allImports = getSortedNodes(importNodes, {
         importOrder,

src/utils/__tests__/is-sort-imports-ignored.spec.ts

@@ -0,0 +1,23 @@
+import { getImportNodes } from '../get-import-nodes';
+import { isSortImportsIgnored } from '../is-sort-imports-ignored';
+
+const codeIgnored = `// sort-imports-ignore
+// second comment
+import z from 'z';
+`;
+
+const codeNotIgnored = `// second comment
+import z from 'z';
+`;
+
+test('it should return true if specific leading comment detected', () => {
+    const importNodes = getImportNodes(codeIgnored);
+
+    expect(isSortImportsIgnored(importNodes)).toBeTruthy();
+});
+
+test('it should return false if no specific leading comment detected', () => {
+    const importNodes = getImportNodes(codeNotIgnored);
+
+    expect(isSortImportsIgnored(importNodes)).toBeFalsy();
+});

src/utils/get-sorted-nodes-group.ts

@@ -1,4 +1,5 @@
 import { Import, ImportDeclaration } from '@babel/types';
+
 import { naturalSort } from '../natural-sort';
 import { PrettierOptions } from '../types';
 

src/utils/is-sort-imports-ignored.ts

@@ -0,0 +1,11 @@
+import { Statement } from '@babel/types';
+
+import { sortImportsIgnoredComment } from '../constants';
+import { getAllCommentsFromNodes } from './get-all-comments-from-nodes';
+
+export const isSortImportsIgnored = (nodes: Statement[]) =>
+    getAllCommentsFromNodes(nodes).some(
+        (comment) =>
+            comment.loc.start.line === 1 &&
+            comment.value.includes(sortImportsIgnoredComment),
+    );

tests/ImportsNotSeparated/__snapshots__/ppsi.spec.js.snap

@@ -385,3 +385,30 @@ import "./commands";
 // require('./commands')
 
 `;
+
+exports[`sort-imports-ignored.ts - typescript-verify: sort-imports-ignored.ts 1`] = `
+// sort-imports-ignore
+
+import './commands';
+import b from 'b';
+import a from 'a';
+
+// Comment
+
+function add(a:number,b:number) {
+    return a + b;
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+// sort-imports-ignore
+
+import "./commands";
+import b from "b";
+import a from "a";
+
+// Comment
+
+function add(a: number, b: number) {
+    return a + b;
+}
+
+`;

tests/ImportsNotSeparated/sort-imports-ignored.ts

@@ -0,0 +1,11 @@
+// sort-imports-ignore
+
+import './commands';
+import b from 'b';
+import a from 'a';
+
+// Comment
+
+function add(a:number,b:number) {
+    return a + b;
+}

tests/ImportsNotSeparatedRest/__snapshots__/ppsi.spec.js.snap

@@ -328,3 +328,30 @@ import "./commands";
 // require('./commands')
 
 `;
+
+exports[`sort-imports-ignored.ts - typescript-verify: sort-imports-ignored.ts 1`] = `
+// sort-imports-ignore
+
+import './commands';
+import b from 'b';
+import a from 'a';
+
+// Comment
+
+function add(a:number,b:number) {
+    return a + b;
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+// sort-imports-ignore
+
+import "./commands";
+import b from "b";
+import a from "a";
+
+// Comment
+
+function add(a: number, b: number) {
+    return a + b;
+}
+
+`;

tests/ImportsNotSeparatedRest/sort-imports-ignored.ts

@@ -0,0 +1,11 @@
+// sort-imports-ignore
+
+import './commands';
+import b from 'b';
+import a from 'a';
+
+// Comment
+
+function add(a:number,b:number) {
+    return a + b;
+}

tests/ImportsSeparated/__snapshots__/ppsi.spec.js.snap

@@ -412,3 +412,30 @@ import "./commands";
 // require('./commands')
 
 `;
+
+exports[`sort-imports-ignored.ts - typescript-verify: sort-imports-ignored.ts 1`] = `
+// sort-imports-ignore
+
+import './commands';
+import b from 'b';
+import a from 'a';
+
+// Comment
+
+function add(a:number,b:number) {
+    return a + b;
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+// sort-imports-ignore
+
+import "./commands";
+import b from "b";
+import a from "a";
+
+// Comment
+
+function add(a: number, b: number) {
+    return a + b;
+}
+
+`;

tests/ImportsSeparated/sort-imports-ignored.ts

@@ -0,0 +1,11 @@
+// sort-imports-ignore
+
+import './commands';
+import b from 'b';
+import a from 'a';
+
+// Comment
+
+function add(a:number,b:number) {
+    return a + b;
+}

tests/ImportsSeparatedRest/__snapshots__/ppsi.spec.js.snap

@@ -347,3 +347,30 @@ import "./commands";
 // require('./commands')
 
 `;
+
+exports[`sort-imports-ignored.ts - typescript-verify: sort-imports-ignored.ts 1`] = `
+// sort-imports-ignore
+
+import './commands';
+import b from 'b';
+import a from 'a';
+
+// Comment
+
+function add(a:number,b:number) {
+    return a + b;
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+// sort-imports-ignore
+
+import "./commands";
+import b from "b";
+import a from "a";
+
+// Comment
+
+function add(a: number, b: number) {
+    return a + b;
+}
+
+`;

tests/ImportsSeparatedRest/sort-imports-ignored.ts

@@ -0,0 +1,11 @@
+// sort-imports-ignore
+
+import './commands';
+import b from 'b';
+import a from 'a';
+
+// Comment
+
+function add(a:number,b:number) {
+    return a + b;
+}