Merge pull request #23 from mskelton/export-sort-groups

Export sort groups

Author: mskelton

docs/rules/exports.md

@@ -27,13 +27,83 @@ export { mark }
 export default React
 ```
 
+## Rule Options
+
+This rule has an object with its properties as:
+
+- `"groups"` (default: `[]`)
+
 ### Groups
 
-Exports are sorted in the following groups top to bottom:
+By default, this rule will perform basic alphanumeric sorting but you can
+greatly customize your export sorting with sort groups.This allows you to
+separate common groups of exports to make it easier to scan your exports at a
+glance.
+
+There are four built-in sort groups you can use:
+
+1. `default`
+   - Default exports (e.g. `export default a`).
+1. `sourceless`
+   - Exports without a source (e.g. `export { a }`).
+1. `dependency`
+   - Exports which do not throw an error when calling `require.resolve` on the
+     source.
+   - Useful for differentiating between path aliases (e.g. `components/Hello`)
+     and dependencies (e.g. `react`).
+1. `other`
+   - Catch all sort group for any exports which did not match other sort groups.
+
+You can also define custom regex sort groups if the built-in sort groups aren't
+enough. The following configuration shows an example of using the built-in sort
+groups as well as a custom regex sort group.
+
+```json
+{
+  "sort/exports": [
+    "warn",
+    {
+      "groups": [
+        { "type": "default", "order": 5 },
+        { "type": "sourceless", "order": 1 },
+        { "regex": "^~", "order": 3 },
+        { "type": "dependency", "order": 2 },
+        { "type": "other", "order": 4 }
+      ]
+    }
+  ]
+}
+```
+
+This configuration would result in the following output.
+
+```js
+export { a }
+export { useState } from "react"
+export App from "~/components"
+export { b } from "./b"
+export default c
+```
+
+#### Group Order
+
+It's important to understand the difference between the order of the sort groups
+in the `groups` array, and the `order` property of each sort group. When sorting
+exports, this plugin will find the first sort group which the export would apply
+to and then assign it an order using the `order` property. This allows you to
+define a hierarchy of sort groups in descending specificity (e.g. dependency
+then regex) while still having full control over the order of the sort groups in
+the resulting code.
+
+For example, the `other` sort group will match any export and thus should always
+be last in the list of sort groups. However, if you want to sort dependency
+exports (e.g. `react`) after the `other` sort group, you can use the `order`
+property to give the dependency exports a higher order than the `other` sort
+group.
 
-- Exports with a source
-- Exports with no source
-- Default export
+The configuration example above shows how this works where default exports are
+the first sort group even though they have the highest order and are thus the
+last sort group in the resulting code.
 
 ## When Not To Use It
 

src/__tests__/exports.spec.ts

@@ -1,3 +1,5 @@
+jest.mock("../resolver")
+
 import { RuleTester } from "eslint"
 import rule from "../rules/exports"
 
@@ -33,6 +35,33 @@ ruleTester.run("sort/exports", rule, {
       // c
       export { c } from "./c"
     `.trim(),
+
+    // Sort groups
+    {
+      code: `
+        const mark = ''
+
+        export default React
+        export { relA } from './a'
+        export { relB } from './b'
+        export { depA } from 'dependency-a'
+        export { depB } from 'dependency-b'
+        export * from 'a'
+        export { b } from 'b'
+        export { mark }
+      `.trim(),
+      options: [
+        {
+          groups: [
+            { type: "default", order: 1 },
+            { type: "sourceless", order: 5 },
+            { regex: "^\\.+\\/", order: 2 },
+            { type: "dependency", order: 3 },
+            { type: "other", order: 4 },
+          ],
+        },
+      ],
+    },
   ],
   invalid: [
     {
@@ -61,11 +90,11 @@ ruleTester.run("sort/exports", rule, {
       output: `
         const mark = ''
 
+        export default React
+        export { mark }
         export { a } from 'a'
         export * from 'b'
         export { c } from 'c'
-        export { mark }
-        export default React
       `,
       errors: [{ messageId: "unsorted" }],
     },
@@ -90,5 +119,81 @@ ruleTester.run("sort/exports", rule, {
       `.trim(),
       errors: [{ messageId: "unsorted" }],
     },
+
+    // Sort groups
+    {
+      code: `
+        const mark = ''
+
+        export { depB } from 'dependency-b'
+        export { mark }
+        export default React
+        export { relB } from './b'
+        export * from 'a'
+        export { relA } from './a'
+        export { depA } from 'dependency-a'
+        export { b } from 'b'
+      `.trim(),
+      output: `
+        const mark = ''
+
+        export { relA } from './a'
+        export { relB } from './b'
+        export * from 'a'
+        export { b } from 'b'
+        export { depA } from 'dependency-a'
+        export { depB } from 'dependency-b'
+        export { mark }
+        export default React
+    `.trim(),
+      options: [
+        {
+          groups: [
+            { type: "default", order: 3 },
+            { type: "sourceless", order: 2 },
+            { type: "other", order: 1 },
+          ],
+        },
+      ],
+      errors: [{ messageId: "unsorted" }],
+    },
+    {
+      code: `
+        const mark = ''
+
+        export { depB } from 'dependency-b'
+        export { mark }
+        export default React
+        export { relB } from './b'
+        export * from 'a'
+        export { relA } from './a'
+        export { depA } from 'dependency-a'
+        export { b } from 'b'
+      `.trim(),
+      output: `
+        const mark = ''
+
+        export default React
+        export { relA } from './a'
+        export { relB } from './b'
+        export { depA } from 'dependency-a'
+        export { depB } from 'dependency-b'
+        export * from 'a'
+        export { b } from 'b'
+        export { mark }
+    `.trim(),
+      options: [
+        {
+          groups: [
+            { type: "default", order: 1 },
+            { type: "sourceless", order: 5 },
+            { regex: "^\\.+\\/", order: 2 },
+            { type: "dependency", order: 3 },
+            { type: "other", order: 4 },
+          ],
+        },
+      ],
+      errors: [{ messageId: "unsorted" }],
+    },
   ],
 })

src/index.ts

@@ -12,7 +12,18 @@ module.exports = {
       plugins: ["sort"],
       rules: {
         "sort/destructuring-properties": "warn",
-        "sort/exports": "warn",
+        "sort/exports": [
+          "warn",
+          {
+            groups: [
+              { type: "default", order: 5 },
+              { type: "sourceless", order: 4 },
+              { regex: "^\\.+\\/", order: 3 },
+              { type: "dependency", order: 1 },
+              { type: "other", order: 2 },
+            ],
+          },
+        ],
         "sort/export-members": "warn",
         "sort/imports": [
           "warn",

src/rules/exports.ts

@@ -1,15 +1,53 @@
+import { ExportDefaultDeclaration } from "@typescript-eslint/types/dist/ast-spec"
 import { Rule } from "eslint"
 import { ImportDeclaration, ModuleDeclaration } from "estree"
+import { isResolved } from "../resolver"
 import { docsURL, filterNodes, getName, report } from "../utils"
 
 type Export = Exclude<ModuleDeclaration, ImportDeclaration>
 
+interface SortGroup {
+  order: number
+  type?: "default" | "sourceless" | "dependency" | "other"
+  regex?: string
+}
+
 /**
- * Returns the node's sort weight. The sort weight is used to separate types
- * of nodes into groups and then sort in each individual group.
+ * Returns the order of a given node based on the sort groups configured in the
+ * rule options. If no sort groups are configured (default), the order returned
+ * is always 0.
  */
-function getWeight(node: Export) {
-  return node.type === "ExportDefaultDeclaration" ? 2 : node.source ? 0 : 1
+function getSortGroup(
+  sortGroups: SortGroup[],
+  node: Exclude<Export, ExportDefaultDeclaration>
+) {
+  const source = getSortValue(node)
+  const isDefaultExport = node.type === "ExportDefaultDeclaration"
+
+  for (const { regex, type, order } of sortGroups) {
+    switch (type) {
+      case "default":
+        if (isDefaultExport) return order
+        break
+
+      case "sourceless":
+        if (!isDefaultExport && !node.source) return order
+        break
+
+      case "dependency":
+        if (isResolved(source)) return order
+        break
+
+      case "other":
+        return order
+    }
+
+    if (regex && new RegExp(regex).test(source)) {
+      return order
+    }
+  }
+
+  return 0
 }
 
 function getSortValue(node: Export) {
@@ -20,6 +58,8 @@ function getSortValue(node: Export) {
 
 export default {
   create(context) {
+    const groups = context.options[0]?.groups ?? []
+
     return {
       Program(program) {
         const nodes = filterNodes(program.body, [
@@ -35,8 +75,8 @@ export default {
 
         const sorted = nodes.slice().sort(
           (a, b) =>
-            // First sort by weight
-            getWeight(a) - getWeight(b) ||
+            // First, sort by sort group
+            getSortGroup(groups, a) - getSortGroup(groups, b) ||
             // Then sort by path
             getSortValue(a).localeCompare(getSortValue(b))
         )
@@ -54,5 +94,27 @@ export default {
     messages: {
       unsorted: "Exports should be sorted alphabetically.",
     },
+    schema: [
+      {
+        type: "object",
+        properties: {
+          groups: {
+            type: "array",
+            items: {
+              type: "object",
+              properties: {
+                type: {
+                  enum: ["default", "sourceless", "dependency", "other"],
+                },
+                regex: { type: "string" },
+                order: { type: "number" },
+              },
+              required: ["order"],
+              additionalProperties: false,
+            },
+          },
+        },
+      },
+    ],
   },
 } as Rule.RuleModule