From d2b10aec006d04680c8b36fbd4e4e325376a73c0 Mon Sep 17 00:00:00 2001
From: xM8WVqaG <44505331+xM8WVqaG@users.noreply.github.com>
Date: Sat, 25 Mar 2023 14:49:48 +0000
Subject: [PATCH] [Docs] `extensions`: reference node ESM behavior

This behavior largely didn't change despite the functionality becoming more widely adopted. Even though the document assumes CJS, It's probably worth including at least a footnote about the resolver behaving differently for ESM.

See: https://github.com/import-js/eslint-plugin-import/issues/2043
---
 CHANGELOG.md             | 3 +++
 docs/rules/extensions.md | 4 +++-
 2 files changed, 6 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1866819b0..d10ceef81 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,6 +14,7 @@ This change log adheres to standards from [Keep a CHANGELOG](https://keepachange
 ### Changed
 - [Docs] [`no-duplicates`]: fix example schema ([#2684], thanks [@simmo])
 - [Docs] [`group-exports`]: fix syntax highlighting ([#2699], thanks [@devinrhode2])
+- [Docs] [`extensions`]: reference node ESM behavior ([#2748], thanks [@xM8WVqaG])
 
 ## [2.27.5] - 2023-01-16
 
@@ -1067,6 +1068,7 @@ for info on changes for earlier releases.
 [`memo-parser`]: ./memo-parser/README.md
 
 [#2754]: https://github.com/import-js/eslint-plugin-import/pull/2754
+[#2748]: https://github.com/import-js/eslint-plugin-import/pull/2748
 [#2699]: https://github.com/import-js/eslint-plugin-import/pull/2699
 [#2664]: https://github.com/import-js/eslint-plugin-import/pull/2664
 [#2613]: https://github.com/import-js/eslint-plugin-import/pull/2613
@@ -1853,6 +1855,7 @@ for info on changes for earlier releases.
 [@wKich]: https://github.com/wKich
 [@wschurman]: https://github.com/wschurman
 [@wtgtybhertgeghgtwtg]: https://github.com/wtgtybhertgeghgtwtg
+[@xM8WVqaG]: https://github.com/xM8WVqaG
 [@xpl]: https://github.com/xpl
 [@yordis]: https://github.com/yordis
 [@zloirock]: https://github.com/zloirock
diff --git a/docs/rules/extensions.md b/docs/rules/extensions.md
index 9e78b8c70..df4f34128 100644
--- a/docs/rules/extensions.md
+++ b/docs/rules/extensions.md
@@ -2,7 +2,7 @@
 
 <!-- end auto-generated rule header -->
 
-Some file resolve algorithms allow you to omit the file extension within the import source path. For example the `node` resolver can resolve `./foo/bar` to the absolute path `/User/someone/foo/bar.js` because the `.js` extension is resolved automatically by default. Depending on the resolver you can configure more extensions to get resolved automatically.
+Some file resolve algorithms allow you to omit the file extension within the import source path. For example the `node` resolver (which does not yet support ESM/`import`) can resolve `./foo/bar` to the absolute path `/User/someone/foo/bar.js` because the `.js` extension is resolved automatically by default in CJS. Depending on the resolver you can configure more extensions to get resolved automatically.
 
 In order to provide a consistent use of file extensions across your code base, this rule can enforce or disallow the use of certain file extensions.
 
@@ -170,3 +170,5 @@ import foo from '@/foo';
 ## When Not To Use It
 
 If you are not concerned about a consistent usage of file extension.
+
+In the future, when this rule supports native node ESM resolution, and the plugin is configured to use native rather than transpiled ESM (a config option that is not yet available) - setting this to `always` will have no effect.