eslint-plugin-perfectionist 4.13.0 → 4.14.0

package/dist/package.json.js

@@ -1,6 +1,6 @@
 'use strict'
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' })
 const name = 'eslint-plugin-perfectionist'
-const version = '4.13.0'
+const version = '4.14.0'
 exports.name = name
 exports.version = version

package/dist/rules/sort-classes.js

@@ -18,7 +18,7 @@ const createEslintRule = require('../utils/create-eslint-rule.js')
 const getDecoratorName = require('../utils/get-decorator-name.js')
 const reportAllErrors = require('../utils/report-all-errors.js')
 const shouldPartition = require('../utils/should-partition.js')
-const getGroupNumber = require('../utils/get-group-number.js')
+const getGroupIndex = require('../utils/get-group-index.js')
 const computeGroup = require('../utils/compute-group.js')
 const rangeToDiff = require('../utils/range-to-diff.js')
 const getSettings = require('../utils/get-settings.js')
@@ -474,7 +474,7 @@ const sortClasses = createEslintRule.createEslintRule({
         let nodesSortedByGroups = formattedNodes.flatMap(nodes2 =>
           sortNodesByGroups.sortNodesByGroups({
             isNodeIgnored: sortingNode =>
-              getGroupNumber.getGroupNumber(options.groups, sortingNode) ===
+              getGroupIndex.getGroupIndex(options.groups, sortingNode) ===
               options.groups.length,
             getOptionsByGroupNumber:
               getCustomGroupsCompareOptions.buildGetCustomGroupOverriddenOptionsFunction(

package/dist/rules/sort-exports.js

@@ -142,6 +142,7 @@ const sortExports = createEslintRule.createEslintRule({
               missedSpacingBetweenMembers: 'missedSpacingBetweenExports',
               extraSpacingBetweenMembers: 'extraSpacingBetweenExports',
               unexpectedGroupOrder: 'unexpectedExportsGroupOrder',
+              missedCommentAbove: 'missedCommentAboveExport',
               unexpectedOrder: 'unexpectedExportsOrder',
             },
             sortNodesExcludingEslintDisabled,
@@ -185,6 +186,7 @@ const sortExports = createEslintRule.createEslintRule({
       type: 'array',
     },
     messages: {
+      missedCommentAboveExport: reportErrors.MISSED_COMMENT_ABOVE_ERROR,
       missedSpacingBetweenExports: reportErrors.MISSED_SPACING_ERROR,
       extraSpacingBetweenExports: reportErrors.EXTRA_SPACING_ERROR,
       unexpectedExportsGroupOrder: reportErrors.GROUP_ORDER_ERROR,

package/dist/rules/sort-imports/compute-common-selectors.js

@@ -65,12 +65,22 @@ let builtinPrefixOnlyModules = /* @__PURE__ */ new Set([
   'node:sea',
 ])
 let isCoreModule = (value, environment) => {
-  let valueToCheck = value.startsWith('node:') ? value.split('node:')[1] : value
-  return (
-    (!!valueToCheck && nodeBuiltinModules.has(valueToCheck)) ||
+  let clean = string_ => string_.replace(/^(?:node:){1,2}/u, '')
+  let [basePath] = value.split('/')
+  let cleanValue = clean(value)
+  let cleanBase = clean(basePath)
+  if (nodeBuiltinModules.has(cleanValue) || nodeBuiltinModules.has(cleanBase)) {
+    return true
+  }
+  if (
     builtinPrefixOnlyModules.has(value) ||
-    (environment === 'bun' ? bunModules.has(value) : false)
-  )
+    builtinPrefixOnlyModules.has(`node:${cleanValue}`) ||
+    builtinPrefixOnlyModules.has(basePath) ||
+    builtinPrefixOnlyModules.has(`node:${cleanBase}`)
+  ) {
+    return true
+  }
+  return environment === 'bun' && bunModules.has(value)
 }
 let isParent = value => value.startsWith('..')
 let isSibling = value => value.startsWith('./')

package/dist/rules/sort-imports/is-side-effect-only-group.js

@@ -1,8 +1,12 @@
 'use strict'
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' })
 const isNewlinesBetweenOption = require('../../utils/is-newlines-between-option.js')
+const isCommentAboveOption = require('../../utils/is-comment-above-option.js')
 let isSideEffectOnlyGroup = group => {
-  if (isNewlinesBetweenOption.isNewlinesBetweenOption(group)) {
+  if (
+    isNewlinesBetweenOption.isNewlinesBetweenOption(group) ||
+    isCommentAboveOption.isCommentAboveOption(group)
+  ) {
     return false
   }
   if (typeof group === 'string') {

package/dist/rules/sort-imports/read-closest-ts-config-by-path.js

@@ -29,15 +29,20 @@ const path__namespace = /* @__PURE__ */ _interopNamespaceDefault(path)
 const fs__namespace = /* @__PURE__ */ _interopNamespaceDefault(fs)
 let directoryCacheByPath = /* @__PURE__ */ new Map()
 let contentCacheByPath = /* @__PURE__ */ new Map()
-let readClosestTsConfigByPath = input => {
+let readClosestTsConfigByPath = ({
+  tsconfigFilename,
+  tsconfigRootDir,
+  contextCwd,
+  filePath,
+}) => {
   let typescriptImport = getTypescriptImport.getTypescriptImport()
   if (!typescriptImport) {
     return null
   }
-  let directory = path__namespace.dirname(input.filePath)
+  let directory = path__namespace.dirname(filePath)
   let checkedDirectories = [directory]
   do {
-    let tsconfigPath = path__namespace.join(directory, 'tsconfig.json')
+    let tsconfigPath = path__namespace.join(directory, tsconfigFilename)
     let cachedDirectory = directoryCacheByPath.get(directory)
     if (!cachedDirectory && fs__namespace.existsSync(tsconfigPath)) {
       cachedDirectory = tsconfigPath
@@ -46,20 +51,13 @@ let readClosestTsConfigByPath = input => {
       for (let checkedDirectory of checkedDirectories) {
         directoryCacheByPath.set(checkedDirectory, cachedDirectory)
       }
-      return getCompilerOptions(
-        typescriptImport,
-        input.contextCwd,
-        cachedDirectory,
-      )
+      return getCompilerOptions(typescriptImport, contextCwd, cachedDirectory)
     }
     directory = path__namespace.dirname(directory)
     checkedDirectories.push(directory)
-  } while (
-    directory.length > 1 &&
-    directory.length >= input.tsconfigRootDir.length
-  )
+  } while (directory.length > 1 && directory.length >= tsconfigRootDir.length)
   throw new Error(
-    `Couldn't find any tsconfig.json relative to '${input.filePath}' within '${input.tsconfigRootDir}'.`,
+    `Couldn't find any ${tsconfigFilename} relative to '${filePath}' within '${tsconfigRootDir}'.`,
   )
 }
 let getCompilerOptions = (typescriptImport, contextCwd, filePath) => {

package/dist/rules/sort-imports.js

@@ -26,38 +26,39 @@ const getSettings = require('../utils/get-settings.js')
 const isSortable = require('../utils/is-sortable.js')
 const complete = require('../utils/complete.js')
 let cachedGroupsByModifiersAndSelectors = /* @__PURE__ */ new Map()
-let defaultGroups = [
-  'type-import',
-  ['value-builtin', 'value-external'],
-  'type-internal',
-  'value-internal',
-  ['type-parent', 'type-sibling', 'type-index'],
-  ['value-parent', 'value-sibling', 'value-index'],
-  'ts-equals-import',
-  'unknown',
-]
+let defaultOptions = {
+  groups: [
+    'type-import',
+    ['value-builtin', 'value-external'],
+    'type-internal',
+    'value-internal',
+    ['type-parent', 'type-sibling', 'type-index'],
+    ['value-parent', 'value-sibling', 'value-index'],
+    'ts-equals-import',
+    'unknown',
+  ],
+  internalPattern: ['^~/.+', '^@/.+'],
+  fallbackSort: { type: 'unsorted' },
+  partitionByComment: false,
+  partitionByNewLine: false,
+  newlinesBetween: 'always',
+  specialCharacters: 'keep',
+  sortSideEffects: false,
+  type: 'alphabetical',
+  environment: 'node',
+  customGroups: [],
+  ignoreCase: true,
+  locales: 'en-US',
+  alphabet: '',
+  order: 'asc',
+}
 const sortImports = createEslintRule.createEslintRule({
   create: context => {
+    var _a, _b
     let settings = getSettings.getSettings(context.settings)
     let userOptions = context.options.at(0)
     let options = getOptionsWithCleanGroups.getOptionsWithCleanGroups(
-      complete.complete(userOptions, settings, {
-        internalPattern: ['^~/.+', '^@/.+'],
-        fallbackSort: { type: 'unsorted' },
-        partitionByComment: false,
-        partitionByNewLine: false,
-        newlinesBetween: 'always',
-        specialCharacters: 'keep',
-        sortSideEffects: false,
-        groups: defaultGroups,
-        type: 'alphabetical',
-        environment: 'node',
-        customGroups: [],
-        ignoreCase: true,
-        locales: 'en-US',
-        alphabet: '',
-        order: 'asc',
-      }),
+      complete.complete(userOptions, settings, defaultOptions),
     )
     validateGeneratedGroupsConfiguration.validateGeneratedGroupsConfiguration({
       options: {
@@ -77,9 +78,15 @@ const sortImports = createEslintRule.createEslintRule({
       options,
     )
     validateSideEffectsConfiguration.validateSideEffectsConfiguration(options)
-    let tsConfigOutput = options.tsconfigRootDir
+    let tsconfigRootDirectory =
+      ((_a = options.tsconfig) == null ? void 0 : _a.rootDir) ??
+      options.tsconfigRootDir
+    let tsConfigOutput = tsconfigRootDirectory
       ? readClosestTsConfigByPath.readClosestTsConfigByPath({
-          tsconfigRootDir: options.tsconfigRootDir,
+          tsconfigFilename:
+            ((_b = options.tsconfig) == null ? void 0 : _b.filename) ??
+            'tsconfig.json',
+          tsconfigRootDir: tsconfigRootDirectory,
           filePath: context.physicalFilename,
           contextCwd: context.cwd,
         })
@@ -306,6 +313,7 @@ const sortImports = createEslintRule.createEslintRule({
               missedSpacingBetweenMembers: 'missedSpacingBetweenImports',
               extraSpacingBetweenMembers: 'extraSpacingBetweenImports',
               unexpectedGroupOrder: 'unexpectedImportsGroupOrder',
+              missedCommentAbove: 'missedCommentAboveImport',
               unexpectedOrder: 'unexpectedImportsOrder',
             },
             options: {
@@ -322,15 +330,15 @@ const sortImports = createEslintRule.createEslintRule({
         }
       },
       VariableDeclaration: node => {
-        var _a
+        var _a2
         if (
           node.declarations[0].init &&
           node.declarations[0].init.type === 'CallExpression' &&
           node.declarations[0].init.callee.type === 'Identifier' &&
           node.declarations[0].init.callee.name === 'require' &&
-          ((_a = node.declarations[0].init.arguments[0]) == null
+          ((_a2 = node.declarations[0].init.arguments[0]) == null
             ? void 0
-            : _a.type) === 'Literal'
+            : _a2.type) === 'Literal'
         ) {
           registerNode(node)
         }
@@ -366,6 +374,21 @@ const sortImports = createEslintRule.createEslintRule({
               }),
             ],
           },
+          tsconfig: {
+            properties: {
+              rootDir: {
+                description: 'Specifies the tsConfig root directory.',
+                type: 'string',
+              },
+              filename: {
+                description: 'Specifies the tsConfig filename.',
+                type: 'string',
+              },
+            },
+            additionalProperties: false,
+            required: ['rootDir'],
+            type: 'object',
+          },
           maxLineLength: {
             description: 'Specifies the maximum line length.',
             exclusiveMinimum: true,
@@ -400,6 +423,7 @@ const sortImports = createEslintRule.createEslintRule({
     },
     messages: {
       unexpectedImportsDependencyOrder: reportErrors.DEPENDENCY_ORDER_ERROR,
+      missedCommentAboveImport: reportErrors.MISSED_COMMENT_ABOVE_ERROR,
       missedSpacingBetweenImports: reportErrors.MISSED_SPACING_ERROR,
       extraSpacingBetweenImports: reportErrors.EXTRA_SPACING_ERROR,
       unexpectedImportsGroupOrder: reportErrors.GROUP_ORDER_ERROR,
@@ -413,24 +437,7 @@ const sortImports = createEslintRule.createEslintRule({
     type: 'suggestion',
     fixable: 'code',
   },
-  defaultOptions: [
-    {
-      customGroups: { value: {}, type: {} },
-      internalPattern: ['^~/.+', '^@/.+'],
-      partitionByComment: false,
-      partitionByNewLine: false,
-      specialCharacters: 'keep',
-      newlinesBetween: 'always',
-      sortSideEffects: false,
-      groups: defaultGroups,
-      type: 'alphabetical',
-      environment: 'node',
-      ignoreCase: true,
-      locales: 'en-US',
-      alphabet: '',
-      order: 'asc',
-    },
-  ],
+  defaultOptions: [defaultOptions],
   name: 'sort-imports',
 })
 let hasContentBetweenNodes = (sourceCode, left, right) =>

package/dist/rules/sort-modules.js

@@ -18,8 +18,8 @@ const createEslintRule = require('../utils/create-eslint-rule.js')
 const getDecoratorName = require('../utils/get-decorator-name.js')
 const reportAllErrors = require('../utils/report-all-errors.js')
 const shouldPartition = require('../utils/should-partition.js')
-const getGroupNumber = require('../utils/get-group-number.js')
 const getEnumMembers = require('../utils/get-enum-members.js')
+const getGroupIndex = require('../utils/get-group-index.js')
 const computeGroup = require('../utils/compute-group.js')
 const rangeToDiff = require('../utils/range-to-diff.js')
 const getSettings = require('../utils/get-settings.js')
@@ -284,7 +284,7 @@ let analyzeModule = ({
     let nodesSortedByGroups = formattedNodes.flatMap(nodes2 =>
       sortNodesByGroups.sortNodesByGroups({
         isNodeIgnored: sortingNode =>
-          getGroupNumber.getGroupNumber(options.groups, sortingNode) ===
+          getGroupIndex.getGroupIndex(options.groups, sortingNode) ===
           options.groups.length,
         getOptionsByGroupNumber:
           getCustomGroupsCompareOptions.buildGetCustomGroupOverriddenOptionsFunction(

package/dist/rules/sort-switch-case.js

@@ -77,6 +77,9 @@ const sortSwitchCase = createEslintRule.createEslintRule({
           sortedCaseNameSortingNodes,
         )
         pairwise.pairwise(caseNodesSortingNodeGroup, (left, right) => {
+          if (!left) {
+            return
+          }
           let leftIndex = nodeIndexMap.get(left)
           let rightIndex = nodeIndexMap.get(right)
           if (leftIndex < rightIndex) {
@@ -198,6 +201,9 @@ const sortSwitchCase = createEslintRule.createEslintRule({
       let sortingNodeGroupsForBlockSortFlat =
         sortingNodeGroupsForBlockSort.flat()
       pairwise.pairwise(sortingNodeGroupsForBlockSortFlat, (left, right) => {
+        if (!left) {
+          return
+        }
         let indexOfLeft = sortedSortingNodeGroupsForBlockSort.indexOf(left)
         let indexOfRight = sortedSortingNodeGroupsForBlockSort.indexOf(right)
         if (indexOfLeft < indexOfRight) {
@@ -210,6 +216,7 @@ const sortSwitchCase = createEslintRule.createEslintRule({
               : makeFixes.makeFixes({
                   sortedNodes: sortedSortingNodeGroupsForBlockSort,
                   nodes: sortingNodeGroupsForBlockSortFlat,
+                  hasCommentAboveMissing: false,
                   sourceCode,
                   fixer,
                 }),

package/dist/utils/common-json-schemas.js

@@ -68,6 +68,10 @@ let newlinesBetweenJsonSchema = {
   enum: ['ignore', 'always', 'never'],
   type: 'string',
 }
+let commentAboveJsonSchema = {
+  description: 'Specifies a comment to enforce above the group.',
+  type: 'string',
+}
 let groupsJsonSchema = {
   items: {
     oneOf: [
@@ -83,9 +87,10 @@ let groupsJsonSchema = {
       {
         properties: {
           newlinesBetween: newlinesBetweenJsonSchema,
+          commentAbove: commentAboveJsonSchema,
         },
-        required: ['newlinesBetween'],
         additionalProperties: false,
+        minProperties: 1,
         type: 'object',
       },
     ],

package/dist/utils/get-comment-above-that-should-exist.js

@@ -0,0 +1,34 @@
+'use strict'
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' })
+const isCommentAboveOption = require('./is-comment-above-option.js')
+const getCommentsBefore = require('./get-comments-before.js')
+let getCommentAboveThatShouldExist = ({
+  rightGroupIndex,
+  leftGroupIndex,
+  sortingNode,
+  sourceCode,
+  options,
+}) => {
+  if (leftGroupIndex !== null && leftGroupIndex >= rightGroupIndex) {
+    return null
+  }
+  let groupAboveRight = options.groups[rightGroupIndex - 1]
+  if (!isCommentAboveOption.isCommentAboveOption(groupAboveRight)) {
+    return null
+  }
+  let matchingCommentsAbove = getCommentsBefore
+    .getCommentsBefore({
+      node: sortingNode.node,
+      sourceCode,
+    })
+    .find(comment =>
+      commentMatches(comment.value, groupAboveRight.commentAbove),
+    )
+  return {
+    comment: groupAboveRight.commentAbove,
+    exists: !!matchingCommentsAbove,
+  }
+}
+let commentMatches = (comment, expected) =>
+  comment.toLowerCase().includes(expected.toLowerCase().trim())
+exports.getCommentAboveThatShouldExist = getCommentAboveThatShouldExist

package/dist/utils/{get-group-number.js → get-group-index.js}

@@ -1,6 +1,6 @@
 'use strict'
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' })
-let getGroupNumber = (groups, node) => {
+let getGroupIndex = (groups, node) => {
   for (let max = groups.length, i = 0; i < max; i++) {
     let currentGroup = groups[i]
     if (
@@ -14,4 +14,4 @@ let getGroupNumber = (groups, node) => {
   }
   return groups.length
 }
-exports.getGroupNumber = getGroupNumber
+exports.getGroupIndex = getGroupIndex

package/dist/utils/{get-newlines-errors.js → get-newlines-between-errors.js}

@@ -2,13 +2,13 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' })
 const getNewlinesBetweenOption = require('./get-newlines-between-option.js')
 const getLinesBetween = require('./get-lines-between.js')
-let getNewlinesErrors = ({
+let getNewlinesBetweenErrors = ({
   newlinesBetweenValueGetter,
   missedSpacingError,
   extraSpacingError,
+  rightGroupIndex,
+  leftGroupIndex,
   sourceCode,
-  rightNum,
-  leftNum,
   options,
   right,
   left,
@@ -26,7 +26,7 @@ let getNewlinesErrors = ({
           right,
           left,
         })) ?? newlinesBetween
-  if (leftNum > rightNum) {
+  if (leftGroupIndex > rightGroupIndex) {
     return []
   }
   let numberOfEmptyLinesBetween = getLinesBetween.getLinesBetween(
@@ -48,4 +48,4 @@ let getNewlinesErrors = ({
   }
   return []
 }
-exports.getNewlinesErrors = getNewlinesErrors
+exports.getNewlinesBetweenErrors = getNewlinesBetweenErrors

package/dist/utils/get-newlines-between-option.js

@@ -1,13 +1,10 @@
 'use strict'
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' })
 const isNewlinesBetweenOption = require('./is-newlines-between-option.js')
-const getGroupNumber = require('./get-group-number.js')
+const getGroupIndex = require('./get-group-index.js')
 let getNewlinesBetweenOption = ({ nextSortingNode, sortingNode, options }) => {
-  let nodeGroupNumber = getGroupNumber.getGroupNumber(
-    options.groups,
-    sortingNode,
-  )
-  let nextNodeGroupNumber = getGroupNumber.getGroupNumber(
+  let nodeGroupNumber = getGroupIndex.getGroupIndex(options.groups, sortingNode)
+  let nextNodeGroupNumber = getGroupIndex.getGroupIndex(
     options.groups,
     nextSortingNode,
   )

package/dist/utils/is-comment-above-option.js

@@ -0,0 +1,5 @@
+'use strict'
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' })
+let isCommentAboveOption = groupOption =>
+  typeof groupOption === 'object' && 'commentAbove' in groupOption
+exports.isCommentAboveOption = isCommentAboveOption

package/dist/utils/make-comment-above-fixes.js

@@ -0,0 +1,109 @@
+'use strict'
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' })
+const getCommentAboveThatShouldExist = require('./get-comment-above-that-should-exist.js')
+const isCommentAboveOption = require('./is-comment-above-option.js')
+const getCommentsBefore = require('./get-comments-before.js')
+const getGroupIndex = require('./get-group-index.js')
+let makeCommentAboveFixes = ({ sortedNodes, sourceCode, options, fixer }) => {
+  let allAutoAddedComments = new Set(
+    options.groups
+      .filter(group => isCommentAboveOption.isCommentAboveOption(group))
+      .map(({ commentAbove }) => commentAbove),
+  )
+  let fixes = []
+  let firstNodeFixes = makeCommentAboveFix({
+    nextSortedSortingNode: sortedNodes[0],
+    sortedSortingNode: null,
+    allAutoAddedComments,
+    sourceCode,
+    options,
+    fixer,
+  })
+  fixes.push(...firstNodeFixes)
+  for (let i = 0; i < sortedNodes.length - 1; i++) {
+    let sortedSortingNode = sortedNodes.at(i)
+    let nextSortedSortingNode = sortedNodes.at(i + 1)
+    let nodeFixes = makeCommentAboveFix({
+      nextSortedSortingNode,
+      allAutoAddedComments,
+      sortedSortingNode,
+      sourceCode,
+      options,
+      fixer,
+    })
+    fixes.push(...nodeFixes)
+  }
+  return fixes
+}
+let makeCommentAboveFix = ({
+  nextSortedSortingNode,
+  allAutoAddedComments,
+  sortedSortingNode,
+  sourceCode,
+  options,
+  fixer,
+}) => {
+  let leftGroupIndex = sortedSortingNode
+    ? getGroupIndex.getGroupIndex(options.groups, sortedSortingNode)
+    : -1
+  let rightGroupIndex = getGroupIndex.getGroupIndex(
+    options.groups,
+    nextSortedSortingNode,
+  )
+  let commentAboveThatShouldExist =
+    getCommentAboveThatShouldExist.getCommentAboveThatShouldExist({
+      options: {
+        ...options,
+        groups: options.groups,
+      },
+      sortingNode: nextSortedSortingNode,
+      rightGroupIndex,
+      leftGroupIndex,
+      sourceCode,
+    })
+  let commentsBefore = getCommentsBefore.getCommentsBefore({
+    node: nextSortedSortingNode.node,
+    sourceCode,
+  })
+  let autoAddedCommentsAboveToRemove = commentsBefore
+    .filter(
+      comment =>
+        !(commentAboveThatShouldExist == null
+          ? void 0
+          : commentAboveThatShouldExist.comment) ||
+        comment.value.slice(1) !== commentAboveThatShouldExist.comment,
+    )
+    .filter(
+      comment =>
+        comment.type === 'Line' &&
+        allAutoAddedComments.has(comment.value.slice(1)),
+    )
+  let fixes = []
+  for (let autoAddedCommentAboveToRemove of autoAddedCommentsAboveToRemove) {
+    let nextToken = sourceCode.getTokenAfter(autoAddedCommentAboveToRemove)
+    fixes.push(
+      fixer.removeRange([
+        autoAddedCommentAboveToRemove.range[0],
+        nextToken.range[0],
+      ]),
+    )
+  }
+  if (commentAboveThatShouldExist && !commentAboveThatShouldExist.exists) {
+    let nodeToPutCommentBefore
+    let isFirstToken = !sourceCode.getTokenBefore(nextSortedSortingNode.node)
+    if (isFirstToken || !commentsBefore[0]) {
+      nodeToPutCommentBefore = nextSortedSortingNode.node
+    } else {
+      ;[nodeToPutCommentBefore] = commentsBefore
+    }
+    fixes.push(
+      fixer.insertTextBeforeRange(
+        nodeToPutCommentBefore.range,
+        `// ${commentAboveThatShouldExist.comment}
+`,
+      ),
+    )
+  }
+  return fixes
+}
+exports.makeCommentAboveFixes = makeCommentAboveFixes

package/dist/utils/make-fixes.js

@@ -1,11 +1,13 @@
 'use strict'
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' })
+const makeNewlinesBetweenFixes = require('./make-newlines-between-fixes.js')
 const makeCommentAfterFixes = require('./make-comment-after-fixes.js')
-const makeNewlinesFixes = require('./make-newlines-fixes.js')
+const makeCommentAboveFixes = require('./make-comment-above-fixes.js')
 const makeOrderFixes = require('./make-order-fixes.js')
 let makeFixes = ({
   ignoreFirstNodeHighestBlockComment,
   newlinesBetweenValueGetter,
+  hasCommentAboveMissing,
   sortedNodes,
   sourceCode,
   options,
@@ -26,25 +28,40 @@ let makeFixes = ({
     nodes,
     fixer,
   })
-  if (
-    commentAfterFixes.length > 0 ||
-    !(options == null ? void 0 : options.groups) ||
-    !options.newlinesBetween
-  ) {
+  if (commentAfterFixes.length > 0) {
     return [...orderFixes, ...commentAfterFixes]
   }
-  let newlinesFixes = makeNewlinesFixes.makeNewlinesFixes({
+  if ((options == null ? void 0 : options.groups) && options.newlinesBetween) {
+    let newlinesFixes = makeNewlinesBetweenFixes.makeNewlinesBetweenFixes({
+      options: {
+        ...options,
+        newlinesBetween: options.newlinesBetween,
+        groups: options.groups,
+      },
+      newlinesBetweenValueGetter,
+      sortedNodes,
+      sourceCode,
+      fixer,
+      nodes,
+    })
+    if (newlinesFixes.length > 0) {
+      return [...orderFixes, ...newlinesFixes]
+    }
+  }
+  if (orderFixes.length > 0) {
+    return orderFixes
+  }
+  if (!hasCommentAboveMissing || !(options == null ? void 0 : options.groups)) {
+    return []
+  }
+  return makeCommentAboveFixes.makeCommentAboveFixes({
     options: {
       ...options,
-      newlinesBetween: options.newlinesBetween,
       groups: options.groups,
     },
-    newlinesBetweenValueGetter,
     sortedNodes,
     sourceCode,
     fixer,
-    nodes,
   })
-  return [...orderFixes, ...newlinesFixes]
 }
 exports.makeFixes = makeFixes

package/dist/utils/{make-newlines-fixes.js → make-newlines-between-fixes.js}

@@ -3,7 +3,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' })
 const getNewlinesBetweenOption = require('./get-newlines-between-option.js')
 const getLinesBetween = require('./get-lines-between.js')
 const getNodeRange = require('./get-node-range.js')
-let makeNewlinesFixes = ({
+let makeNewlinesBetweenFixes = ({
   newlinesBetweenValueGetter,
   sortedNodes,
   sourceCode,
@@ -87,4 +87,4 @@ let addNewlineBeforeFirstNewline = value => {
   return `${value.slice(0, firstNewlineIndex)}
 ${value.slice(firstNewlineIndex)}`
 }
-exports.makeNewlinesFixes = makeNewlinesFixes
+exports.makeNewlinesBetweenFixes = makeNewlinesBetweenFixes

package/dist/utils/make-single-node-comment-after-fixes.js

@@ -1,13 +1,12 @@
 'use strict'
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' })
-const getCommentAfter = require('./get-comment-after.js')
 let makeSingleNodeCommentAfterFixes = ({
   sortedNode,
   sourceCode,
   fixer,
   node,
 }) => {
-  let commentAfter = getCommentAfter.getCommentAfter(sortedNode, sourceCode)
+  let commentAfter = getCommentAfter(sortedNode, sourceCode)
   let areNodesOnSameLine = node.loc.start.line === sortedNode.loc.end.line
   if (!commentAfter || areNodesOnSameLine) {
     return []
@@ -28,4 +27,19 @@ let makeSingleNodeCommentAfterFixes = ({
   )
   return fixes
 }
+let getCommentAfter = (node, source) => {
+  let token = source.getTokenAfter(node, {
+    filter: ({ value, type }) =>
+      type !== 'Punctuator' || ![',', ';', ':'].includes(value),
+    includeComments: true,
+  })
+  if (
+    ((token == null ? void 0 : token.type) === 'Block' ||
+      (token == null ? void 0 : token.type) === 'Line') &&
+    node.loc.end.line === token.loc.end.line
+  ) {
+    return token
+  }
+  return null
+}
 exports.makeSingleNodeCommentAfterFixes = makeSingleNodeCommentAfterFixes

package/dist/utils/pairwise.js

@@ -5,10 +5,11 @@ let pairwise = (nodes, callback) => {
   if (!isSortable.isSortable(nodes)) {
     return
   }
+  callback(null, nodes.at(0))
   for (let i = 1; i < nodes.length; i++) {
     let left = nodes.at(i - 1)
     let right = nodes.at(i)
-    callback(left, right, i - 1)
+    callback(left, right)
   }
 }
 exports.pairwise = pairwise

package/dist/utils/report-all-errors.js

@@ -1,10 +1,11 @@
 'use strict'
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' })
 const computeNodesInCircularDependencies = require('./compute-nodes-in-circular-dependencies.js')
+const getCommentAboveThatShouldExist = require('./get-comment-above-that-should-exist.js')
 const isNodeDependentOnOtherNode = require('./is-node-dependent-on-other-node.js')
+const getNewlinesBetweenErrors = require('./get-newlines-between-errors.js')
 const createNodeIndexMap = require('./create-node-index-map.js')
-const getNewlinesErrors = require('./get-newlines-errors.js')
-const getGroupNumber = require('./get-group-number.js')
+const getGroupIndex = require('./get-group-index.js')
 const reportErrors = require('./report-errors.js')
 const pairwise = require('./pairwise.js')
 let reportAllErrors = ({
@@ -28,9 +29,13 @@ let reportAllErrors = ({
         )
       : /* @__PURE__ */ new Set()
   pairwise.pairwise(nodes, (left, right) => {
-    let leftNumber = getGroupNumber.getGroupNumber(options.groups, left)
-    let rightNumber = getGroupNumber.getGroupNumber(options.groups, right)
-    let leftIndex = nodeIndexMap.get(left)
+    let leftInfo = left
+      ? {
+          groupIndex: getGroupIndex.getGroupIndex(options.groups, left),
+          index: nodeIndexMap.get(left),
+        }
+      : null
+    let rightGroupIndex = getGroupIndex.getGroupIndex(options.groups, right)
     let rightIndex = nodeIndexMap.get(right)
     let indexOfRightExcludingEslintDisabled =
       sortedNodesExcludingEslintDisabled.indexOf(right)
@@ -44,16 +49,17 @@ let reportAllErrors = ({
       })
     }
     if (
-      firstUnorderedNodeDependentOnRight ||
-      leftIndex > rightIndex ||
-      (left.isEslintDisabled &&
-        leftIndex >= indexOfRightExcludingEslintDisabled)
+      leftInfo &&
+      (firstUnorderedNodeDependentOnRight ||
+        leftInfo.index > rightIndex ||
+        ((left == null ? void 0 : left.isEslintDisabled) &&
+          leftInfo.index >= indexOfRightExcludingEslintDisabled))
     ) {
       if (firstUnorderedNodeDependentOnRight) {
         messageIds.push(availableMessageIds.unexpectedDependencyOrder)
       } else {
         messageIds.push(
-          leftNumber === rightNumber ||
+          leftInfo.groupIndex === rightGroupIndex ||
             !availableMessageIds.unexpectedGroupOrder
             ? availableMessageIds.unexpectedOrder
             : availableMessageIds.unexpectedGroupOrder,
@@ -61,33 +67,51 @@ let reportAllErrors = ({
       }
     }
     if (
+      left &&
       options.newlinesBetween &&
       availableMessageIds.missedSpacingBetweenMembers &&
       availableMessageIds.extraSpacingBetweenMembers
     ) {
       messageIds = [
         ...messageIds,
-        ...getNewlinesErrors.getNewlinesErrors({
+        ...getNewlinesBetweenErrors.getNewlinesBetweenErrors({
           options: {
             ...options,
             newlinesBetween: options.newlinesBetween,
           },
           missedSpacingError: availableMessageIds.missedSpacingBetweenMembers,
           extraSpacingError: availableMessageIds.extraSpacingBetweenMembers,
+          leftGroupIndex: leftInfo.groupIndex,
           newlinesBetweenValueGetter,
-          rightNum: rightNumber,
-          leftNum: leftNumber,
+          rightGroupIndex,
           sourceCode,
           right,
           left,
         }),
       ]
     }
+    let commentAboveMissing
+    if (availableMessageIds.missedCommentAbove) {
+      let commentAboveThatShouldExist =
+        getCommentAboveThatShouldExist.getCommentAboveThatShouldExist({
+          leftGroupIndex:
+            (leftInfo == null ? void 0 : leftInfo.groupIndex) ?? null,
+          sortingNode: right,
+          rightGroupIndex,
+          sourceCode,
+          options,
+        })
+      if (commentAboveThatShouldExist && !commentAboveThatShouldExist.exists) {
+        commentAboveMissing = commentAboveThatShouldExist.comment
+        messageIds = [...messageIds, availableMessageIds.missedCommentAbove]
+      }
+    }
     reportErrors.reportErrors({
       sortedNodes: sortedNodesExcludingEslintDisabled,
       ignoreFirstNodeHighestBlockComment,
       firstUnorderedNodeDependentOnRight,
       newlinesBetweenValueGetter,
+      commentAboveMissing,
       messageIds,
       sourceCode,
       options,

package/dist/utils/report-errors.js

@@ -1,21 +1,23 @@
 'use strict'
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' })
-const toSingleLine = require('./to-single-line.js')
 const makeFixes = require('./make-fixes.js')
 const NODE_DEPENDENT_ON_RIGHT = 'nodeDependentOnRight'
 const RIGHT = 'right'
 const RIGHT_GROUP = 'rightGroup'
 const LEFT = 'left'
 const LEFT_GROUP = 'leftGroup'
+const MISSED_COMMENT_ABOVE = 'missedCommentAbove'
 const ORDER_ERROR = `Expected "{{${RIGHT}}}" to come before "{{${LEFT}}}".`
 const DEPENDENCY_ORDER_ERROR = `Expected dependency "{{${RIGHT}}}" to come before "{{${NODE_DEPENDENT_ON_RIGHT}}}".`
 const GROUP_ORDER_ERROR = `Expected "{{${RIGHT}}}" ({{${RIGHT_GROUP}}}) to come before "{{${LEFT}}}" ({{${LEFT_GROUP}}}).`
 const EXTRA_SPACING_ERROR = `Extra spacing between "{{${LEFT}}}" and "{{${RIGHT}}}" objects.`
 const MISSED_SPACING_ERROR = `Missed spacing between "{{${LEFT}}}" and "{{${RIGHT}}}".`
+const MISSED_COMMENT_ABOVE_ERROR = `Missed comment "{{${MISSED_COMMENT_ABOVE}}}" above "{{${RIGHT}}}".`
 let reportErrors = ({
   firstUnorderedNodeDependentOnRight,
   ignoreFirstNodeHighestBlockComment,
   newlinesBetweenValueGetter,
+  commentAboveMissing,
   sortedNodes,
   messageIds,
   sourceCode,
@@ -27,8 +29,20 @@ let reportErrors = ({
 }) => {
   for (let messageId of messageIds) {
     context.report({
+      data: {
+        [NODE_DEPENDENT_ON_RIGHT]:
+          firstUnorderedNodeDependentOnRight == null
+            ? void 0
+            : firstUnorderedNodeDependentOnRight.name,
+        [MISSED_COMMENT_ABOVE]: commentAboveMissing,
+        [LEFT]: toSingleLine((left == null ? void 0 : left.name) ?? ''),
+        [RIGHT]: toSingleLine(right.name),
+        [RIGHT_GROUP]: right.group,
+        [LEFT_GROUP]: left == null ? void 0 : left.group,
+      },
       fix: fixer =>
         makeFixes.makeFixes({
+          hasCommentAboveMissing: !!commentAboveMissing,
           ignoreFirstNodeHighestBlockComment,
           newlinesBetweenValueGetter,
           sortedNodes,
@@ -37,25 +51,17 @@ let reportErrors = ({
           fixer,
           nodes,
         }),
-      data: {
-        [NODE_DEPENDENT_ON_RIGHT]:
-          firstUnorderedNodeDependentOnRight == null
-            ? void 0
-            : firstUnorderedNodeDependentOnRight.name,
-        [RIGHT]: toSingleLine.toSingleLine(right.name),
-        [LEFT]: toSingleLine.toSingleLine(left.name),
-        [RIGHT_GROUP]: right.group,
-        [LEFT_GROUP]: left.group,
-      },
       node: right.node,
       messageId,
     })
   }
 }
+let toSingleLine = string => string.replaceAll(/\s{2,}/gu, ' ').trim()
 exports.DEPENDENCY_ORDER_ERROR = DEPENDENCY_ORDER_ERROR
 exports.EXTRA_SPACING_ERROR = EXTRA_SPACING_ERROR
 exports.GROUP_ORDER_ERROR = GROUP_ORDER_ERROR
 exports.LEFT = LEFT
+exports.MISSED_COMMENT_ABOVE_ERROR = MISSED_COMMENT_ABOVE_ERROR
 exports.MISSED_SPACING_ERROR = MISSED_SPACING_ERROR
 exports.ORDER_ERROR = ORDER_ERROR
 exports.RIGHT = RIGHT

package/dist/utils/should-partition.js

@@ -1,6 +1,6 @@
 'use strict'
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' })
-const hasPartitionComment = require('./has-partition-comment.js')
+const isPartitionComment = require('./is-partition-comment.js')
 const getCommentsBefore = require('./get-comments-before.js')
 const getLinesBetween = require('./get-lines-between.js')
 let shouldPartition = ({
@@ -12,7 +12,7 @@ let shouldPartition = ({
 }) => {
   let shouldPartitionByComment =
     options.partitionByComment &&
-    hasPartitionComment.hasPartitionComment({
+    hasPartitionComment({
       comments: getCommentsBefore.getCommentsBefore({
         tokenValueToIgnoreBefore,
         node: sortingNode.node,
@@ -29,4 +29,11 @@ let shouldPartition = ({
     getLinesBetween.getLinesBetween(sourceCode, lastSortingNode, sortingNode)
   )
 }
+let hasPartitionComment = ({ partitionByComment, comments }) =>
+  comments.some(comment =>
+    isPartitionComment.isPartitionComment({
+      partitionByComment,
+      comment,
+    }),
+  )
 exports.shouldPartition = shouldPartition

package/dist/utils/sort-nodes-by-groups.js

@@ -1,6 +1,6 @@
 'use strict'
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' })
-const getGroupNumber = require('./get-group-number.js')
+const getGroupIndex = require('./get-group-index.js')
 const sortNodes = require('./sort-nodes.js')
 let sortNodesByGroups = ({
   ignoreEslintDisabledNodes,
@@ -20,7 +20,7 @@ let sortNodesByGroups = ({
       ignoredNodeIndices.push(index)
       continue
     }
-    let groupNumber = getGroupNumber.getGroupNumber(groups, sortingNode)
+    let groupNumber = getGroupIndex.getGroupIndex(groups, sortingNode)
     nodesByNonIgnoredGroupNumber[groupNumber] ??
       (nodesByNonIgnoredGroupNumber[groupNumber] = [])
     nodesByNonIgnoredGroupNumber[groupNumber].push(sortingNode)

package/dist/utils/validate-generated-groups-configuration.js

@@ -1,6 +1,6 @@
 'use strict'
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' })
-const validateNewlinesBetweenInsideGroups = require('./validate-newlines-between-inside-groups.js')
+const validateObjectsInsideGroups = require('./validate-objects-inside-groups.js')
 const validateNoDuplicatedGroups = require('./validate-no-duplicated-groups.js')
 let validateGeneratedGroupsConfiguration = ({
   selectors,
@@ -24,9 +24,7 @@ let validateGeneratedGroupsConfiguration = ({
     throw new Error(`Invalid group(s): ${invalidGroups.join(', ')}`)
   }
   validateNoDuplicatedGroups.validateNoDuplicatedGroups(options)
-  validateNewlinesBetweenInsideGroups.validateNewlinesBetweenInsideGroups(
-    options,
-  )
+  validateObjectsInsideGroups.validateObjectsInsideGroups(options)
 }
 let isPredefinedGroup = (allSelectors, allModifiers, input) => {
   if (input === 'unknown') {

package/dist/utils/validate-no-duplicated-groups.js

@@ -1,12 +1,16 @@
 'use strict'
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' })
 const isNewlinesBetweenOption = require('./is-newlines-between-option.js')
+const isCommentAboveOption = require('./is-comment-above-option.js')
 let validateNoDuplicatedGroups = ({ groups }) => {
   let flattenGroups = groups.flat()
   let seenGroups = /* @__PURE__ */ new Set()
   let duplicatedGroups = /* @__PURE__ */ new Set()
   for (let group of flattenGroups) {
-    if (isNewlinesBetweenOption.isNewlinesBetweenOption(group)) {
+    if (
+      isNewlinesBetweenOption.isNewlinesBetweenOption(group) ||
+      isCommentAboveOption.isCommentAboveOption(group)
+    ) {
       continue
     }
     if (seenGroups.has(group)) {

package/dist/utils/validate-objects-inside-groups.js

@@ -0,0 +1,18 @@
+'use strict'
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' })
+let validateObjectsInsideGroups = ({ groups }) => {
+  let isPreviousElementObject = false
+  for (let group of groups) {
+    if (typeof group === 'string' || Array.isArray(group)) {
+      isPreviousElementObject = false
+      continue
+    }
+    if (isPreviousElementObject) {
+      throw new Error(
+        'Consecutive objects (`newlinesBetween` or `commentAbove` are not allowed: merge them into a single object',
+      )
+    }
+    isPreviousElementObject = true
+  }
+}
+exports.validateObjectsInsideGroups = validateObjectsInsideGroups

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-perfectionist",
-  "version": "4.13.0",
+  "version": "4.14.0",
   "description": "ESLint plugin for sorting various data such as objects, imports, types, enums, JSX props, etc.",
   "keywords": [
     "eslint",
@@ -27,8 +27,8 @@
     "./dist"
   ],
   "dependencies": {
-    "@typescript-eslint/types": "^8.32.1",
-    "@typescript-eslint/utils": "^8.32.1",
+    "@typescript-eslint/types": "^8.33.1",
+    "@typescript-eslint/utils": "^8.33.1",
     "natural-orderby": "^5.0.0"
   },
   "peerDependencies": {

package/dist/utils/get-comment-after.js

@@ -1,18 +0,0 @@
-'use strict'
-Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' })
-let getCommentAfter = (node, source) => {
-  let token = source.getTokenAfter(node, {
-    filter: ({ value, type }) =>
-      type !== 'Punctuator' || ![',', ';', ':'].includes(value),
-    includeComments: true,
-  })
-  if (
-    ((token == null ? void 0 : token.type) === 'Block' ||
-      (token == null ? void 0 : token.type) === 'Line') &&
-    node.loc.end.line === token.loc.end.line
-  ) {
-    return token
-  }
-  return null
-}
-exports.getCommentAfter = getCommentAfter

package/dist/utils/has-partition-comment.js

@@ -1,11 +0,0 @@
-'use strict'
-Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' })
-const isPartitionComment = require('./is-partition-comment.js')
-let hasPartitionComment = ({ partitionByComment, comments }) =>
-  comments.some(comment =>
-    isPartitionComment.isPartitionComment({
-      partitionByComment,
-      comment,
-    }),
-  )
-exports.hasPartitionComment = hasPartitionComment

package/dist/utils/to-single-line.js

@@ -1,4 +0,0 @@
-'use strict'
-Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' })
-let toSingleLine = string => string.replaceAll(/\s{2,}/gu, ' ').trim()
-exports.toSingleLine = toSingleLine

package/dist/utils/validate-newlines-between-inside-groups.js

@@ -1,18 +0,0 @@
-'use strict'
-Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' })
-const isNewlinesBetweenOption = require('./is-newlines-between-option.js')
-let validateNewlinesBetweenInsideGroups = ({ groups }) => {
-  let isPreviousElementNewlinesBetween = false
-  for (let groupElement of groups) {
-    if (!isNewlinesBetweenOption.isNewlinesBetweenOption(groupElement)) {
-      isPreviousElementNewlinesBetween = false
-      continue
-    }
-    if (isPreviousElementNewlinesBetween) {
-      throw new Error("Consecutive 'newlinesBetween' objects are not allowed")
-    }
-    isPreviousElementNewlinesBetween = true
-  }
-}
-exports.validateNewlinesBetweenInsideGroups =
-  validateNewlinesBetweenInsideGroups