fix(oxlintrc): resolve relative plugin specifiers before merging extended configs (#14562)

- Fixes #14478
- Relative specifiers need to joined with their config's directory path.
- When extended configs are merged. we drop the "other" config's path.
- In this "extends" case, the plugins from the "other" config are
resolved relative to the "self" config's path. That shouldn't happen.

- All relative specifiers are resolved _before_ the merge.
- Since full platform-specific (correct) paths to the plugin are logged
when loading fails, this won't work well with the snapshot tests.

<img width="898" height="249" alt="image"
src="https://github.com/user-attachments/assets/7e4d0fa1-c0c1-4dc5-8135-dbf663900902"
/>

I am vacillating on this solution. Maybe external_plugin should be an
enum.

---------

Co-authored-by: Arsh <emmagoldmanvevo+github@pm.me>

Author: camc314

apps/oxlint/src/snapshots/_-c fixtures__print_config__ban_rules__eslintrc.json -A all -D eqeqeq --print-config@oxlint.snap

@@ -11,7 +11,6 @@ working directory:
     "typescript",
     "oxc"
   ],
-  "jsPlugins": null,
   "categories": {},
   "rules": {
     "eqeqeq": [

apps/oxlint/src/snapshots/fixtures_-A all --print-config@oxlint.snap

@@ -11,7 +11,6 @@ working directory: fixtures
     "typescript",
     "oxc"
   ],
-  "jsPlugins": null,
   "categories": {},
   "rules": {},
   "settings": {

apps/oxlint/test/e2e.test.ts

@@ -16,6 +16,11 @@ interface TestOptions {
   // Function to get extra data to include in the snapshot
   getExtraSnapshotData?: (dirPath: string) => Promise<{ [key: string]: string }>;
 
+  /**
+   * Override the `files` directory within the fixture to lint.
+   * This is useful when the fixture has a different structure, e.g. when testing nested configs.
+   * Defaults to `files`.
+   */
   overrideFiles?: string;
 }
 

apps/oxlint/test/fixtures/custom_plugin_nested_config/output.snap.md

@@ -0,0 +1,20 @@
+# Exit code
+1
+
+# stdout
+```
+  x basic-custom-plugin(no-debugger): Unexpected Debugger Statement
+   ,-[nested/index.ts:1:1]
+ 1 | debugger;
+   : ^^^^^^^^^
+   `----
+
+Found 0 warnings and 1 error.
+Finished in Xms on 2 files using X threads.
+```
+
+# stderr
+```
+WARNING: JS plugins are experimental and not subject to semver.
+Breaking changes are possible while JS plugins support is under development.
+```

crates/oxc_linter/src/config/config_builder.rs

@@ -147,15 +147,16 @@ impl ConfigStoreBuilder {
         let (oxlintrc, extended_paths) = resolve_oxlintrc_config(oxlintrc)?;
 
         // Collect external plugins from both base config and overrides
-        let mut external_plugins = FxHashSet::default();
+        let mut external_plugins: FxHashSet<(&PathBuf, &str)> = FxHashSet::default();
 
         if let Some(base_external_plugins) = &oxlintrc.external_plugins {
-            external_plugins.extend(base_external_plugins.iter().cloned());
+            external_plugins.extend(base_external_plugins.iter().map(|(k, v)| (k, v.as_str())));
         }
 
         for r#override in &oxlintrc.overrides {
             if let Some(override_external_plugins) = &r#override.external_plugins {
-                external_plugins.extend(override_external_plugins.iter().cloned());
+                external_plugins
+                    .extend(override_external_plugins.iter().map(|(k, v)| (k, v.as_str())));
             }
         }
 
@@ -165,8 +166,10 @@ impl ConfigStoreBuilder {
         if !external_plugins.is_empty() && external_plugin_store.is_enabled() {
             let Some(external_linter) = external_linter else {
                 #[expect(clippy::missing_panics_doc, reason = "infallible")]
-                let plugin_specifier = external_plugins.iter().next().unwrap().clone();
-                return Err(ConfigBuilderError::NoExternalLinterConfigured { plugin_specifier });
+                let (_, original_specifier) = external_plugins.iter().next().unwrap();
+                return Err(ConfigBuilderError::NoExternalLinterConfigured {
+                    plugin_specifier: (*original_specifier).to_string(),
+                });
             };
 
             let resolver = Resolver::new(ResolveOptions {
@@ -175,19 +178,17 @@ impl ConfigStoreBuilder {
                 ..Default::default()
             });
 
-            #[expect(clippy::missing_panics_doc, reason = "oxlintrc.path is always a file path")]
-            let oxlintrc_dir = oxlintrc.path.parent().unwrap();
-
-            for plugin_specifier in &external_plugins {
+            for (config_path, specifier) in &external_plugins {
                 Self::load_external_plugin(
-                    oxlintrc_dir,
-                    plugin_specifier,
+                    config_path,
+                    specifier,
                     external_linter,
                     &resolver,
                     external_plugin_store,
                 )?;
             }
         }
+
         let plugins = oxlintrc.plugins.unwrap_or_default();
 
         let rules =
@@ -505,7 +506,7 @@ impl ConfigStoreBuilder {
     }
 
     fn load_external_plugin(
-        oxlintrc_dir_path: &Path,
+        resolve_dir: &Path,
         plugin_specifier: &str,
         external_linter: &ExternalLinter,
         resolver: &Resolver,
@@ -521,7 +522,8 @@ impl ConfigStoreBuilder {
             );
         }
 
-        let resolved = resolver.resolve(oxlintrc_dir_path, plugin_specifier).map_err(|e| {
+        // Resolve the specifier relative to the config directory
+        let resolved = resolver.resolve(resolve_dir, plugin_specifier).map_err(|e| {
             ConfigBuilderError::PluginLoadFailed {
                 plugin_specifier: plugin_specifier.to_string(),
                 error: e.to_string(),

crates/oxc_linter/src/config/overrides.rs

@@ -1,11 +1,12 @@
 use std::{
     borrow::Cow,
     ops::{Deref, DerefMut},
+    path::PathBuf,
 };
 
 use rustc_hash::FxHashSet;
 use schemars::{JsonSchema, r#gen, schema::Schema};
-use serde::{Deserialize, Deserializer, Serialize};
+use serde::{Deserialize, Deserializer, Serialize, Serializer};
 
 use crate::{LintPlugins, OxlintEnv, OxlintGlobals, config::OxlintRules};
 
@@ -97,8 +98,17 @@ pub struct OxlintOverride {
     ///
     /// Note: JS plugins are experimental and not subject to semver.
     /// They are not supported in language server at present.
-    #[serde(rename = "jsPlugins")]
-    pub external_plugins: Option<FxHashSet<String>>,
+    #[serde(
+        rename = "jsPlugins",
+        deserialize_with = "deserialize_external_plugins_override",
+        serialize_with = "serialize_external_plugins_override",
+        default,
+        skip_serializing_if = "Option::is_none"
+    )]
+    #[schemars(with = "Option<FxHashSet<String>>")]
+    pub external_plugins: Option<
+        FxHashSet<(PathBuf /* config file directory */, String /* plugin specifier */)>,
+    >,
 
     #[serde(default)]
     pub rules: OxlintRules,
@@ -139,6 +149,33 @@ impl GlobSet {
     }
 }
 
+#[expect(clippy::type_complexity)]
+fn deserialize_external_plugins_override<'de, D>(
+    deserializer: D,
+) -> Result<Option<FxHashSet<(PathBuf, String)>>, D::Error>
+where
+    D: Deserializer<'de>,
+{
+    let opt_set: Option<FxHashSet<String>> = Option::deserialize(deserializer)?;
+    Ok(opt_set
+        .map(|set| set.into_iter().map(|specifier| (PathBuf::default(), specifier)).collect()))
+}
+
+#[expect(clippy::ref_option)]
+fn serialize_external_plugins_override<S>(
+    plugins: &Option<FxHashSet<(PathBuf, String)>>,
+    serializer: S,
+) -> Result<S::Ok, S::Error>
+where
+    S: Serializer,
+{
+    // Serialize as an array of original specifiers (the values in the map)
+    match plugins {
+        Some(set) => serializer.collect_seq(set.iter().map(|(_, specifier)| specifier)),
+        None => serializer.serialize_none(),
+    }
+}
+
 #[cfg(test)]
 mod test {
     use crate::config::{globals::GlobalValue, plugins::LintPlugins};

crates/oxc_linter/src/config/oxlintrc.rs

@@ -5,7 +5,7 @@ use std::{
 
 use rustc_hash::{FxHashMap, FxHashSet};
 use schemars::JsonSchema;
-use serde::{Deserialize, Serialize};
+use serde::{Deserialize, Deserializer, Serialize, Serializer};
 
 use oxc_diagnostics::OxcDiagnostic;
 
@@ -68,8 +68,15 @@ pub struct Oxlintrc {
     ///
     /// Note: JS plugins are experimental and not subject to semver.
     /// They are not supported in language server at present.
-    #[serde(rename = "jsPlugins")]
-    pub external_plugins: Option<FxHashSet<String>>,
+    #[serde(
+        rename = "jsPlugins",
+        deserialize_with = "deserialize_external_plugins",
+        serialize_with = "serialize_external_plugins",
+        default,
+        skip_serializing_if = "Option::is_none"
+    )]
+    #[schemars(with = "Option<FxHashSet<String>>")]
+    pub external_plugins: Option<FxHashSet<(PathBuf, String)>>,
     pub categories: OxlintCategories,
     /// Example
     ///
@@ -152,6 +159,24 @@ impl Oxlintrc {
 
         config.path = path.to_path_buf();
 
+        #[expect(clippy::missing_panics_doc)]
+        let config_dir = config.path.parent().unwrap();
+        if let Some(external_plugins) = &mut config.external_plugins {
+            *external_plugins = std::mem::take(external_plugins)
+                .into_iter()
+                .map(|(_, specifier)| (config_dir.to_path_buf(), specifier))
+                .collect();
+        }
+
+        for override_config in config.overrides.iter_mut() {
+            if let Some(external_plugins) = &mut override_config.external_plugins {
+                *external_plugins = std::mem::take(external_plugins)
+                    .into_iter()
+                    .map(|(_, specifier)| (config_dir.to_path_buf(), specifier))
+                    .collect();
+            }
+        }
+
         Ok(config)
     }
 
@@ -232,6 +257,32 @@ fn is_json_ext(ext: &str) -> bool {
     ext == "json" || ext == "jsonc"
 }
 
+fn deserialize_external_plugins<'de, D>(
+    deserializer: D,
+) -> Result<Option<FxHashSet<(PathBuf, String)>>, D::Error>
+where
+    D: Deserializer<'de>,
+{
+    let opt_set: Option<FxHashSet<String>> = Option::deserialize(deserializer)?;
+    Ok(opt_set
+        .map(|set| set.into_iter().map(|specifier| (PathBuf::default(), specifier)).collect()))
+}
+
+#[expect(clippy::ref_option)]
+fn serialize_external_plugins<S>(
+    plugins: &Option<FxHashSet<(PathBuf, String)>>,
+    serializer: S,
+) -> Result<S::Ok, S::Error>
+where
+    S: Serializer,
+{
+    // Serialize as an array of original specifiers (the values in the map)
+    match plugins {
+        Some(set) => serializer.collect_seq(set.iter().map(|(_, specifier)| specifier)),
+        None => serializer.serialize_none(),
+    }
+}
+
 #[cfg(test)]
 mod test {
     use serde_json::json;

crates/oxc_linter/src/snapshots/schema_json.snap

@@ -53,7 +53,6 @@ expression: json
     },
     "jsPlugins": {
       "description": "JS plugins.\n\nNote: JS plugins are experimental and not subject to semver.\nThey are not supported in language server at present.",
-      "default": null,
       "type": [
         "array",
         "null"

npm/oxlint/configuration_schema.json

@@ -49,7 +49,6 @@
     },
     "jsPlugins": {
       "description": "JS plugins.\n\nNote: JS plugins are experimental and not subject to semver.\nThey are not supported in language server at present.",
-      "default": null,
       "type": [
         "array",
         "null"

tasks/website/src/linter/snapshots/schema_markdown.snap

@@ -197,7 +197,6 @@ Globs to ignore during linting. These are resolved from the configuration file p
 
 type: `string[]`
 
-default: `null`
 
 JS plugins.