docs: outdated order rule doc

close #279

Author: JounQin

.github/workflows/pkg-pr-new.yml

@@ -27,4 +27,5 @@ jobs:
       - name: Build
         run: yarn build
 
-      - run: yarn dlx pkg-pr-new publish --compact
+      - name: Publish
+        run: yarn dlx pkg-pr-new publish --compact

README.md

@@ -645,8 +645,8 @@ Detailed changes for each release are documented in [CHANGELOG.md](./CHANGELOG.m
 [`eslint-loader`]: https://www.npmjs.com/package/eslint-loader
 [`resolve`]: https://www.npmjs.com/package/resolve
 [`externals`]: https://webpack.github.io/docs/library-and-externals.html
-[1stg.me]: https://www.1stg.me
-[jounqin]: https://GitHub.com/JounQin
-[mit]: http://opensource.org/licenses/MIT
+[1stG.me]: https://www.1stG.me
+[JounQin]: https://github.com/JounQin
+[MIT]: http://opensource.org/licenses/MIT
 [node]: https://www.npmjs.com/package/eslint-import-resolver-node
 [webpack]: https://www.npmjs.com/package/eslint-import-resolver-webpack

docs/rules/order.md

@@ -99,14 +99,14 @@ import 'format2.css' // OK
 This rule supports the following options (none of which are required):
 
 - [`groups`][18]
-- [`pathGroups`][19]
-- [`pathGroupsExcludedImportTypes`][15]
+- [`pathGroups`][8]
+- [`pathGroupsExcludedImportTypes`][9]
 - [`distinctGroup`][32]
-- [`newlines-between`][24]
+- [`newlines-between`][20]
 - [`alphabetize`][30]
 - [`named`][33]
 - [`warnOnUnassignedImports`][5]
-- [`sortTypesAmongThemselves`][7]
+- [`sortTypesGroup`][7]
 - [`newlines-between-types`][27]
 - [`consolidateIslands`][25]
 
@@ -162,7 +162,7 @@ Roughly speaking, the grouping algorithm is as follows:
 
 1. If the import has no corresponding identifiers (e.g. `import './my/thing.js'`), is otherwise "unassigned," or is an unsupported use of `require()`, and [`warnOnUnassignedImports`][5] is disabled, it will be ignored entirely since the order of these imports may be important for their [side-effects][31]
 2. If the import is part of an arcane TypeScript declaration (e.g. `import log = console.log`), it will be considered **object**. However, note that external module references (e.g. `import x = require('z')`) are treated as normal `require()`s and import-exports (e.g. `export import w = y;`) are ignored entirely
-3. If the import is [type-only][6], `"type"` is in `groups`, and [`sortTypesAmongThemselves`][7] is disabled, it will be considered **type** (with additional implications if using [`pathGroups`][8] and `"type"` is in [`pathGroupsExcludedImportTypes`][9])
+3. If the import is [type-only][6], `"type"` is in `groups`, and [`sortTypesGroup`][7] is disabled, it will be considered **type** (with additional implications if using [`pathGroups`][8] and `"type"` is in [`pathGroupsExcludedImportTypes`][9])
 4. If the import's specifier matches [`import-x/internal-regex`][28], it will be considered **internal**
 5. If the import's specifier is an absolute path, it will be considered **unknown**
 6. If the import's specifier has the name of a Node.js core module (using [is-core-module][10]), it will be considered **builtin**
@@ -177,22 +177,20 @@ Roughly speaking, the grouping algorithm is as follows:
 15. If the import's specifier has a name that starts with a word character, it will be considered **external**
 16. If this point is reached, the import will be ignored entirely
 
-At the end of the process, if they co-exist in the same file, all top-level `require()` statements that haven't been ignored are shifted (with respect to their order) below any ES6 `import` or similar declarations. Finally, any type-only declarations are potentially reorganized according to [`sortTypesAmongThemselves`][7].
+At the end of the process, if they co-exist in the same file, all top-level `require()` statements that haven't been ignored are shifted (with respect to their order) below any ES6 `import` or similar declarations. Finally, any type-only declarations are potentially reorganized according to [`sortTypesGroup`][7].
 
 ### `pathGroups`
 
 Valid values: `PathGroup[]` \
 Default: `[]`
 
-Sometimes [the predefined groups][18] are not fine-grained
-enough, especially when using import aliases. `pathGroups` defines one or more
-[`PathGroup`][13]s relative to a predefined group. Imports are associated with a
-[`PathGroup`][13] based on path matching against the import specifier (using
-[minimatch][14]).
+Sometimes [the predefined groups][18] are not fine-grained enough, especially when using import aliases.
+`pathGroups` defines one or more [`PathGroup`][13]s relative to a predefined group.
+Imports are associated with a [`PathGroup`][13] based on path matching against the import specifier (using [minimatch][14]).
 
-> \[!IMPORTANT]
+> [!IMPORTANT]
 >
-> Note that, by default, imports grouped as `"builtin"`, `"external"`, or `"object"` will not be considered for further `pathGroups` matching unless they are removed from [`pathGroupsExcludedImportTypes`][15].
+> Note that, by default, imports grouped as `"builtin"`, `"external"`, or `"object"` will not be considered for further `pathGroups` matching unless they are removed from [`pathGroupsExcludedImportTypes`][9].
 
 #### `PathGroup`
 
@@ -230,11 +228,10 @@ enough, especially when using import aliases. `pathGroups` defines one or more
 Valid values: `("builtin" | "external" | "internal" | "unknown" | "parent" | "sibling" | "index" | "object" | "type")[]` \
 Default: `["builtin", "external", "object"]`
 
-By default, imports in certain [groups][18] are excluded
-from being matched against [`pathGroups`][19] to prevent overeager sorting. Use
-`pathGroupsExcludedImportTypes` to modify which groups are excluded.
+By default, imports in certain [groups][18] are excluded from being matched against [`pathGroups`][8] to prevent overeager sorting.
+Use `pathGroupsExcludedImportTypes` to modify which groups are excluded.
 
-> \[!TIP]
+> [!TIP]
 >
 > If using imports with custom specifier aliases (e.g.
 > you're using `eslint-import-resolver-alias`, `paths` in `tsconfig.json`, etc) that [end up
@@ -267,7 +264,7 @@ from being matched against [`pathGroups`][19] to prevent overeager sorting. Use
 Valid values: `boolean` \
 Default: `true`
 
-> \[!CAUTION]
+> [!CAUTION]
 >
 > Currently, `distinctGroup` defaults to `true`. However, in a later update, the
 > default will change to `false`.
@@ -310,9 +307,9 @@ Enforces or forbids new lines between import groups.
 
 - If set to `always`, at least one new line between each group will be enforced, and new lines inside a group will be forbidden
 
-  > \[!TIP]
-  >
-  > To prevent multiple lines between imports, the [`no-multiple-empty-lines` rule][21], or a tool like [Prettier][22], can be used.
+> [!TIP]
+>
+> To prevent multiple lines between imports, the [`no-multiple-empty-lines` rule][21], or a tool like [Prettier][22], can be used.
 
 - If set to `always-and-inside-groups`, it will act like `always` except new lines are allowed inside import groups
 
@@ -385,9 +382,9 @@ import index from './'
 Valid values: `{ order?: "asc" | "desc" | "ignore", orderImportKind?: "asc" | "desc" | "ignore", caseInsensitive?: boolean }` \
 Default: `{ order: "ignore", orderImportKind: "ignore", caseInsensitive: false }`
 
-Determine the sort order of imports within each [predefined group][18] or [`PathGroup`][19] alphabetically based on specifier.
+Determine the sort order of imports within each [predefined group][18] or [`PathGroup`][8] alphabetically based on specifier.
 
-> \[!NOTE]
+> [!NOTE]
 >
 > Imports will be alphabetized based on their _specifiers_, not by their
 > identifiers. For example, `const a = require('z');` will come _after_ `const z = require('a');` when `alphabetize` is set to `{ order: "asc" }`.
@@ -445,13 +442,10 @@ Default: `false`
 
 Enforce ordering of names within imports and exports.
 
-If set to `true` or `{ enabled: true }`, _all_ named imports must be ordered
-according to [`alphabetize`][30]. If set to `false` or `{ enabled:
-false }`, named imports can occur in any order.
+If set to `true` or `{ enabled: true }`, _all_ named imports must be ordered according to [`alphabetize`][30].
+If set to `false` or `{ enabled: false }`, named imports can occur in any order.
 
-If set to `{ enabled: true, ... }`, and any of the properties `import`,
-`export`, `require`, or `cjsExports` are set to `false`, named ordering is
-disabled with respect to the following kind of expressions:
+If set to `{ enabled: true, ... }`, and any of the properties `import`, `export`, `require`, or `cjsExports` are set to `false`, named ordering is disabled with respect to the following kind of expressions:
 
 - `import`:
 
@@ -524,15 +518,12 @@ import { apply, compose } from 'xcompose'
 Valid values: `boolean` \
 Default: `false`
 
-Warn when "unassigned" imports are out of order. Unassigned imports are imports
-with no corresponding identifiers (e.g. `import './my/thing.js'` or
-`require('./side-effects.js')`).
+Warn when "unassigned" imports are out of order.
+Unassigned imports are imports with no corresponding identifiers (e.g. `import './my/thing.js'` or `require('./side-effects.js')`).
 
-> \[!NOTE]
+> [!NOTE]
 >
-> These warnings are not fixable with `--fix` since unassigned imports might be
-> used for their
-> [side-effects][31],
+> These warnings are not fixable with `--fix` since unassigned imports might be used for their [side-effects][31],
 > and changing the order of such imports cannot be done safely.
 
 #### Example
@@ -566,12 +557,12 @@ import path from 'path'
 import './styles.css'
 ```
 
-### `sortTypesAmongThemselves`
+### `sortTypesGroup`
 
 Valid values: `boolean` \
 Default: `false`
 
-> \[!NOTE]
+> [!NOTE]
 >
 > This setting is only meaningful when `"type"` is included in [`groups`][18].
 
@@ -613,7 +604,7 @@ import e from './'
 
 This happens because [type-only imports][6] are considered part of one global
 [`"type"` group](#how-imports-are-grouped) by default. However, if we set
-`sortTypesAmongThemselves` to `true`:
+`sortTypesGroup` to `true`:
 
 ```jsonc
 {
@@ -622,7 +613,7 @@ This happens because [type-only imports][6] are considered part of one global
     {
       "groups": ["type", "builtin", "parent", "sibling", "index"],
       "alphabetize": { "order": "asc" },
-      "sortTypesAmongThemselves": true,
+      "sortTypesGroup": true,
     },
   ],
 }
@@ -633,19 +624,15 @@ The same example will pass.
 ### `newlines-between-types`
 
 Valid values: `"ignore" | "always" | "always-and-inside-groups" | "never"` \
-Default: the value of [`newlines-between`][24]
+Default: the value of [`newlines-between`][20]
 
-> \[!NOTE]
+> [!NOTE]
 >
-> This setting is only meaningful when [`sortTypesAmongThemselves`][7] is enabled.
+> This setting is only meaningful when [`sortTypesGroup`][7] is enabled.
 
-`newlines-between-types` is functionally identical to [`newlines-between`][24]
-except it only enforces or forbids new lines between _[type-only][6] import
-groups_, which exist only when [`sortTypesAmongThemselves`][7] is enabled.
+`newlines-between-types` is functionally identical to [`newlines-between`][20] except it only enforces or forbids new lines between _[type-only][6] import groups_, which exist only when [`sortTypesGroup`][7] is enabled.
 
-In addition, when determining if a new line is enforceable or forbidden between
-the type-only imports and the normal imports, `newlines-between-types` takes
-precedence over [`newlines-between`][24].
+In addition, when determining if a new line is enforceable or forbidden between the type-only imports and the normal imports, `newlines-between-types` takes precedence over [`newlines-between`][20].
 
 #### Example
 
@@ -657,7 +644,7 @@ Given the following settings:
     "error",
     {
       "groups": ["type", "builtin", "parent", "sibling", "index"],
-      "sortTypesAmongThemselves": true,
+      "sortTypesGroup": true,
       "newlines-between": "always",
     },
   ],
@@ -691,7 +678,7 @@ However, if we set `newlines-between-types` to `"ignore"`:
     "error",
     {
       "groups": ["type", "builtin", "parent", "sibling", "index"],
-      "sortTypesAmongThemselves": true,
+      "sortTypesGroup": true,
       "newlines-between": "always",
       "newlines-between-types": "ignore",
     },
@@ -703,19 +690,19 @@ The same example will pass.
 
 Note the new line after `import type E from './';` but before `import a from "fs";`. This new line separates the type-only imports from the normal imports. Its existence is governed by [`newlines-between-types`][27] and _not `newlines-between`_.
 
-> \[!IMPORTANT]
+> [!IMPORTANT]
 >
 > In certain situations, [`consolidateIslands: true`][25] will take precedence over `newlines-between-types: "never"`, if used, when it comes to the new line separating type-only imports from normal imports.
 
-The next example will pass even though there's a new line preceding the normal import and [`newlines-between`][24] is set to `"never"`:
+The next example will pass even though there's a new line preceding the normal import and [`newlines-between`][20] is set to `"never"`:
 
 ```jsonc
 {
   "import-x/order": [
     "error",
     {
       "groups": ["type", "builtin", "parent", "sibling", "index"],
-      "sortTypesAmongThemselves": true,
+      "sortTypesGroup": true,
       "newlines-between": "never",
       "newlines-between-types": "always",
     },
@@ -749,7 +736,7 @@ While the following fails due to the new line between the last type import and t
     "error",
     {
       "groups": ["type", "builtin", "parent", "sibling", "index"],
-      "sortTypesAmongThemselves": true,
+      "sortTypesGroup": true,
       "newlines-between": "always",
       "newlines-between-types": "never",
     },
@@ -780,26 +767,28 @@ import e from './'
 Valid values: `"inside-groups" | "never"` \
 Default: `"never"`
 
-> \[!NOTE]
+> [!NOTE]
 >
-> This setting is only meaningful when [`newlines-between`][24] and/or [`newlines-between-types`][27] is set to `"always-and-inside-groups"`.
+> This setting is only meaningful when [`newlines-between`][20] and/or [`newlines-between-types`][27] is set to `"always-and-inside-groups"`.
 
-When set to `"inside-groups"`, this ensures imports spanning multiple lines are separated from other imports with a new line while single-line imports are grouped together (and the space between them consolidated) if they belong to the same [group][18] or \[`pathGroups`]\[26].
+When set to `"inside-groups"`, this ensures imports spanning multiple lines are separated from other imports with a new line while single-line imports are grouped together (and the space between them consolidated) if they belong to the same [group][18] or [`pathGroups`][8].
 
-> \[!IMPORTANT]
+> [!IMPORTANT]
 >
 > When all of the following are true:
 >
+> - [`sortTypesGroup`][7] is set to `true`
 > - `consolidateIslands` is set to `"inside-groups"`
-> - [`newlines-between`][24] is set to `"always-and-inside-groups"`
-> - [`newlines-between-types`][27] is set to `"never"`
-> - [`sortTypesAmongThemselves`][7] is set to `true`
+> - [`newlines-between`][20] is set to `"always-and-inside-groups"` when [`newlines-between-types`][27] is set to `"never"` (or vice-versa)
 >
-> Then [`newlines-between-types`][27] will yield to `consolidateIslands` and allow new lines to separate multi-line imports and a single new line to separate all [type-only imports][6] from all normal imports. Other than that, [`newlines-between-types: "never"`][27] functions as described.
+> Then [`newlines-between`][20]/[`newlines-between-types`][27] will yield to
+> `consolidateIslands` and allow new lines to separate multi-line imports
+> regardless of the `"never"` setting.
 >
-> This configuration is useful to keep type-only imports stacked tightly
-> together at the bottom of your import block to preserve space while still
-> logically organizing normal imports for quick and pleasant reference.
+> This configuration is useful, for instance, to keep single-line type-only
+> imports stacked tightly together at the bottom of your import block to
+> preserve space while still logically organizing normal imports for quick and
+> pleasant reference.
 
 #### Example
 
@@ -853,7 +842,7 @@ var sibling2 = require('./bar')
 var sibling3 = require('./foobar')
 ```
 
-Note the intragroup "islands" of grouped single-line imports, as well as multi-line imports, are surrounded by new lines. At the same time, note the typical new lines separating different groups are still maintained thanks to [`newlines-between`][24].
+Note the intragroup "islands" of grouped single-line imports, as well as multi-line imports, are surrounded by new lines. At the same time, note the typical new lines separating different groups are still maintained thanks to [`newlines-between`][20].
 
 The same holds true for the next example; when given the following settings:
 
@@ -883,25 +872,20 @@ The same holds true for the next example; when given the following settings:
       "newlines-between": "always-and-inside-groups",
       "newlines-between-types": "never",
       "pathGroupsExcludedImportTypes": [],
-      "sortTypesAmongThemselves": true,
+      "sortTypesGroup": true,
       "consolidateIslands": "inside-groups",
     },
   ],
 }
 ```
 
-> \[!IMPORTANT]
+> [!IMPORTANT]
 >
-> **Pay special attention to the value of
-> [`pathGroupsExcludedImportTypes`](#pathgroupsexcludedimporttypes)** in this
-> example's settings. Without it, the successful example below would fail. This is
-> because the imports with specifiers starting with "dirA/", "dirB/", and
-> "dirC/" are all [considered part of the `"external"`
-> group](#how-imports-are-grouped), and imports in that group are
-> excluded from [`pathGroups`](#pathgroups) matching by default.
+> **Pay special attention to the value of [`pathGroupsExcludedImportTypes`][9]** in this example's settings.
+> Without it, the successful example below would fail.
+> This is because the imports with specifiers starting with "dirA/", "dirB/", and "dirC/" are all [considered part of the `"external"` group](#how-imports-are-grouped), and imports in that group are excluded from [`pathGroups`][8] matching by default.
 >
-> The fix is to remove `"external"` (and, in this example, the others) from
-> [`pathGroupsExcludedImportTypes`](#pathgroupsexcludedimporttypes).
+> The fix is to remove `"external"` (and, in this example, the others) from [`pathGroupsExcludedImportTypes`][9].
 
 This will fail the rule check:
 
@@ -984,24 +968,21 @@ import type { H } from './bbb'
 [4]: https://nodejs.org/api/esm.html#terminology
 [5]: #warnonunassignedimports
 [6]: https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-8.html#type-only-imports-and-export
-[7]: #sorttypesamongthemselves
+[7]: #sorttypesgroup
 [8]: #pathgroups
 [9]: #pathgroupsexcludedimporttypes
 [10]: https://www.npmjs.com/package/is-core-module
 [11]: ../../README.md#importcore-modules
 [12]: https://www.npmjs.com/package/package-up
 [13]: #pathgroup
 [14]: https://www.npmjs.com/package/minimatch
-[15]: #pathgroupsexcludedimporttypes
 [16]: https://www.npmjs.com/package/minimatch#features
 [17]: https://www.npmjs.com/package/minimatch#options
 [18]: #groups
-[19]: #pathgroups
 [20]: #newlines-between
 [21]: https://eslint.org/docs/latest/rules/no-multiple-empty-lines
 [22]: https://prettier.io
 [23]: https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-5.html#type-modifiers-on-import-names
-[24]: #newlines-between
 [25]: #consolidateislands
 [27]: #newlines-between-types
 [28]: ../../README.md#importinternal-regex