feat: enforce group comments

Author: hugop95

docs/content/rules/sort-exports.mdx

@@ -277,6 +277,30 @@ This feature is only applicable when [`partitionByNewLine`](#partitionbynewline)
 }
 ```
 
+#### Comment above groups
+
+You may place `commentAbove` objects between above your groups to enforce the presence of a comment containing the
+content of `commentAbove`.
+
+`newlinesBetween` and `commentAbove` objects can be combined together.
+
+```ts
+{
+  groups: [
+    { commentAbove: 'Type exports' },
+    'type-export',
+    { commentAbove: 'Value exports' },
+    'value-export',
+  ]
+}
+```
+
+- An error will be raised if no comment containing the content of `commentAbove` is found above the top element of the
+group.
+- Auto-fixing will add a comment containing the content of `commentAbove` above the top element of the group.
+- Auto-fixing will also remove invalid auto-added comments (only comments existing in `commentAbove`
+objects are considered as auto-removable).
+
 ### customGroups
 
 <sub>

docs/content/rules/sort-imports.mdx

@@ -465,6 +465,30 @@ This feature is only applicable when [`partitionByNewLine`](#partitionbynewline)
 }
 ```
 
+#### Comment above groups
+
+You may place `commentAbove` objects between above your groups to enforce the presence of a comment containing the
+content of `commentAbove`.
+
+`newlinesBetween` and `commentAbove` objects can be combined together.
+
+```ts
+{
+  groups: [
+    { commentAbove: 'Internal imports' },
+    'internal',
+    { commentAbove: 'External imports' },
+    'external',
+  ]
+}
+```
+
+- An error will be raised if no comment containing the content of `commentAbove` is found above the top element of the
+group.
+- Auto-fixing will add a comment containing the content of `commentAbove` above the top element of the group.
+- Auto-fixing will also remove invalid auto-added comments (only comments existing in `commentAbove`
+objects are considered as auto-removable).
+
 ### customGroups
 
 <Important title="Migrating from the old API">

rules/sort-exports.ts

@@ -12,6 +12,7 @@ import {
   groupsJsonSchema,
 } from '../utils/common-json-schemas'
 import {
+  MISSED_COMMENT_ABOVE_ERROR,
   MISSED_SPACING_ERROR,
   EXTRA_SPACING_ERROR,
   GROUP_ORDER_ERROR,
@@ -41,19 +42,20 @@ import { complete } from '../utils/complete'
  */
 let cachedGroupsByModifiersAndSelectors = new Map<string, string[]>()
 
+type MESSAGE_ID =
+  | 'unexpectedExportsGroupOrder'
+  | 'missedSpacingBetweenExports'
+  | 'extraSpacingBetweenExports'
+  | 'missedCommentAboveExport'
+  | 'unexpectedExportsOrder'
+
 interface SortExportsSortingNode
   extends SortingNode<
     TSESTree.ExportNamedDeclarationWithSource | TSESTree.ExportAllDeclaration
   > {
   groupKind: 'value' | 'type'
 }
 
-type MESSAGE_ID =
-  | 'unexpectedExportsGroupOrder'
-  | 'missedSpacingBetweenExports'
-  | 'extraSpacingBetweenExports'
-  | 'unexpectedExportsOrder'
-
 let defaultOptions: Required<Options[0]> = {
   fallbackSort: { type: 'unsorted' },
   specialCharacters: 'keep',
@@ -184,6 +186,7 @@ export default createEslintRule<Options, MESSAGE_ID>({
               missedSpacingBetweenMembers: 'missedSpacingBetweenExports',
               extraSpacingBetweenMembers: 'extraSpacingBetweenExports',
               unexpectedGroupOrder: 'unexpectedExportsGroupOrder',
+              missedCommentAbove: 'missedCommentAboveExport',
               unexpectedOrder: 'unexpectedExportsOrder',
             },
             sortNodesExcludingEslintDisabled,
@@ -227,6 +230,7 @@ export default createEslintRule<Options, MESSAGE_ID>({
       type: 'array',
     },
     messages: {
+      missedCommentAboveExport: MISSED_COMMENT_ABOVE_ERROR,
       missedSpacingBetweenExports: MISSED_SPACING_ERROR,
       extraSpacingBetweenExports: EXTRA_SPACING_ERROR,
       unexpectedExportsGroupOrder: GROUP_ORDER_ERROR,

rules/sort-imports.ts

@@ -24,6 +24,7 @@ import {
   regexJsonSchema,
 } from '../utils/common-json-schemas'
 import {
+  MISSED_COMMENT_ABOVE_ERROR,
   DEPENDENCY_ORDER_ERROR,
   MISSED_SPACING_ERROR,
   EXTRA_SPACING_ERROR,
@@ -67,6 +68,7 @@ export type MESSAGE_ID =
   | 'missedSpacingBetweenImports'
   | 'unexpectedImportsGroupOrder'
   | 'extraSpacingBetweenImports'
+  | 'missedCommentAboveImport'
   | 'unexpectedImportsOrder'
 
 let defaultOptions: Required<
@@ -390,6 +392,7 @@ export default createEslintRule<Options, MESSAGE_ID>({
               missedSpacingBetweenMembers: 'missedSpacingBetweenImports',
               extraSpacingBetweenMembers: 'extraSpacingBetweenImports',
               unexpectedGroupOrder: 'unexpectedImportsGroupOrder',
+              missedCommentAbove: 'missedCommentAboveImport',
               unexpectedOrder: 'unexpectedImportsOrder',
             },
             options: {
@@ -494,6 +497,7 @@ export default createEslintRule<Options, MESSAGE_ID>({
     },
     messages: {
       unexpectedImportsDependencyOrder: DEPENDENCY_ORDER_ERROR,
+      missedCommentAboveImport: MISSED_COMMENT_ABOVE_ERROR,
       missedSpacingBetweenImports: MISSED_SPACING_ERROR,
       extraSpacingBetweenImports: EXTRA_SPACING_ERROR,
       unexpectedImportsGroupOrder: GROUP_ORDER_ERROR,

rules/sort-imports/is-side-effect-only-group.ts

@@ -1,11 +1,12 @@
 import type { GroupsOptions } from '../../types/common-options'
 
 import { isNewlinesBetweenOption } from '../../utils/is-newlines-between-option'
+import { isCommentAboveOption } from '../../utils/is-comment-above-option'
 
 export let isSideEffectOnlyGroup = (
   group: GroupsOptions<string>[0],
 ): boolean => {
-  if (isNewlinesBetweenOption(group)) {
+  if (isNewlinesBetweenOption(group) || isCommentAboveOption(group)) {
     return false
   }
   if (typeof group === 'string') {

rules/sort-switch-case.ts

@@ -97,6 +97,10 @@ export default createEslintRule<Options, MESSAGE_ID>({
         let nodeIndexMap = createNodeIndexMap(sortedCaseNameSortingNodes)
 
         pairwise(caseNodesSortingNodeGroup, (left, right) => {
+          if (!left) {
+            return
+          }
+
           let leftIndex = nodeIndexMap.get(left)!
           let rightIndex = nodeIndexMap.get(right)!
 
@@ -230,6 +234,10 @@ export default createEslintRule<Options, MESSAGE_ID>({
       let sortingNodeGroupsForBlockSortFlat =
         sortingNodeGroupsForBlockSort.flat()
       pairwise(sortingNodeGroupsForBlockSortFlat, (left, right) => {
+        if (!left) {
+          return
+        }
+
         let indexOfLeft = sortedSortingNodeGroupsForBlockSort.indexOf(left)
         let indexOfRight = sortedSortingNodeGroupsForBlockSort.indexOf(right)
         if (indexOfLeft < indexOfRight) {
@@ -242,6 +250,7 @@ export default createEslintRule<Options, MESSAGE_ID>({
               : makeFixes({
                   sortedNodes: sortedSortingNodeGroupsForBlockSort,
                   nodes: sortingNodeGroupsForBlockSortFlat,
+                  hasCommentAboveMissing: false,
                   sourceCode,
                   fixer,
                 }),