introduce setupConfigs()

Author: lilnasy

apps/oxlint/src-js/bindings.d.ts

@@ -8,14 +8,19 @@ export type JsLintFileCb =
 export type JsLoadPluginCb =
   ((arg0: string, arg1?: string | undefined | null) => Promise<string>)
 
+/** JS callback to setup configs. */
+export type JsSetupConfigsCb =
+  ((arg0: string) => string)
+
 /**
  * NAPI entry point.
  *
  * JS side passes in:
  * 1. `args`: Command line arguments (process.argv.slice(2))
  * 2. `load_plugin`: Load a JS plugin from a file path.
- * 3. `lint_file`: Lint a file.
+ * 3. `setup_configs`: Setup configuration options.
+ * 4. `lint_file`: Lint a file.
  *
  * Returns `true` if linting succeeded without errors, `false` otherwise.
  */
-export declare function lint(args: Array<string>, loadPlugin: JsLoadPluginCb, lintFile: JsLintFileCb): Promise<boolean>
+export declare function lint(args: Array<string>, loadPlugin: JsLoadPluginCb, setupConfigs: JsSetupConfigsCb, lintFile: JsLintFileCb): Promise<boolean>

apps/oxlint/src-js/cli.ts

@@ -5,6 +5,7 @@ import { debugAssertIsNonNull } from "./utils/asserts.js";
 // Using `typeof wrapper` here makes TS check that the function signatures of `loadPlugin` and `loadPluginWrapper`
 // are identical. Ditto `lintFile` and `lintFileWrapper`.
 let loadPlugin: typeof loadPluginWrapper | null = null;
+let setupConfigs: typeof setupConfigsWrapper | null = null;
 let lintFile: typeof lintFileWrapper | null = null;
 
 /**
@@ -21,14 +22,27 @@ function loadPluginWrapper(path: string, packageName: string | null): Promise<st
     // Use promises here instead of making `loadPluginWrapper` an async function,
     // to avoid a micro-tick and extra wrapper `Promise` in all later calls to `loadPluginWrapper`
     return import("./plugins/index.js").then((mod) => {
-      ({ loadPlugin, lintFile } = mod);
+      ({ loadPlugin, lintFile, setupConfigs } = mod);
       return loadPlugin(path, packageName);
     });
   }
   debugAssertIsNonNull(loadPlugin);
   return loadPlugin(path, packageName);
 }
 
+/**
+ * Bootstrap configuration options.
+ *
+ * Delegates to `setupConfigs`, which was lazy-loaded by `loadPluginWrapper`.
+ *
+ * @param optionsJSON - JSON serialization of an array containing all rule options across all configurations.
+ * @returns "ok" on success or error message on failure
+ */
+function setupConfigsWrapper(optionsJSON: string): string {
+  debugAssertIsNonNull(setupConfigs);
+  return setupConfigs(optionsJSON);
+}
+
 /**
  * Lint a file.
  *
@@ -59,8 +73,8 @@ function lintFileWrapper(
 // Get command line arguments, skipping first 2 (node binary and script path)
 const args = process.argv.slice(2);
 
-// Call Rust, passing `loadPlugin` and `lintFile` as callbacks, and CLI arguments
-const success = await lint(args, loadPluginWrapper, lintFileWrapper);
+// Call Rust, passing `loadPlugin`, `setupConfigs`, and `lintFile` as callbacks, and CLI arguments
+const success = await lint(args, loadPluginWrapper, setupConfigsWrapper, lintFileWrapper);
 
 // Note: It's recommended to set `process.exitCode` instead of calling `process.exit()`.
 // `process.exit()` kills the process immediately and `stdout` may not be flushed before process dies.

apps/oxlint/src-js/plugins/config.ts

@@ -0,0 +1,26 @@
+import { setOptions } from "./options.js";
+
+/**
+ * Populates Rust-resolved configuration options on the JS side.
+ * Called from Rust side after all configuration options have been resolved.
+ *
+ * Note: the name `setupConfigs` is currently incorrect, as we only populate rule options.
+ * The intention is for this function to transfer all configurations in a multi-config workspace.
+ * The configuration relevant to each file would then be resolved on the JS side.
+ *
+ * @param optionsJSON - JSON serialization of an array containing all rule options across all configurations.
+ * @returns "ok" on success, or error message on failure
+ */
+export function setupConfigs(optionsJSON: string): string {
+  // TODO: setup settings using this function
+  try {
+    setOptions(optionsJSON);
+    // TODO: flesh out error handling.
+    // Currently, the only procedure that may fail is `JSON.parse()`
+    // in `setOptions()`, but it won't because the JSON string from
+    // the rust side is serde serialized.
+    return "ok";
+  } catch (err) {
+    return err instanceof Error ? err.message : String(err);
+  }
+}

apps/oxlint/src-js/plugins/index.ts

@@ -1,2 +1,3 @@
 export { lintFile } from "./lint.js";
 export { loadPlugin } from "./load.js";
+export { setupConfigs } from "./config.js";

apps/oxlint/src-js/plugins/lint.ts

@@ -1,6 +1,6 @@
 import { setupFileContext, resetFileContext } from "./context.js";
 import { registeredRules } from "./load.js";
-import { allOptions, areOptionsInitialized, DEFAULT_OPTIONS_ID, setOptions } from "./options.js";
+import { allOptions, DEFAULT_OPTIONS_ID } from "./options.js";
 import { diagnostics } from "./report.js";
 import { setSettingsForFile, resetSettings } from "./settings.js";
 import { ast, initAst, resetSourceAndAst, setupSourceForFile } from "./source_code.js";

apps/oxlint/src-js/plugins/options.ts

@@ -131,38 +131,21 @@ function mergeValues(configValue: JsonValue, defaultValue: JsonValue): JsonValue
   return freeze(merged);
 }
 
-// Track if options have been initialized to avoid re-initialization
-let optionsInitialized = false;
-
 /**
  * Set all external rule options.
  * Called once from Rust after config building, before any linting occurs.
  * @param optionsJson - JSON string of outer array of per-options arrays.
  */
 export function setOptions(optionsJson: string): void {
-  try {
-    const parsed = JSON.parse(optionsJson);
-    if (!Array.isArray(parsed)) throw new TypeError("Expected optionsJson to decode to an array");
+  const parsed = JSON.parse(optionsJson);
+  if (DEBUG) {
+    if (!isArray(parsed))
+      throw new TypeError("Expected optionsJson to decode to an array", { cause: parsed });
     // Basic shape validation: each element must be an array (options tuple array)
     for (let i = 0; i < parsed.length; i++) {
       const el = parsed[i];
-      if (!Array.isArray(el)) throw new TypeError("Each options entry must be an array");
+      if (!isArray(el)) throw new TypeError("Each options entry must be an array", { cause: el });
     }
-    allOptions = parsed as Readonly<Options>[];
-    optionsInitialized = true;
-  } catch (err) {
-    // Re-throw with clearer message for Rust side logging.
-    throw new Error(
-      "Failed to parse external rule options JSON: " +
-        (err instanceof Error ? err.message : String(err)),
-    );
   }
-}
-
-/**
- * Check if options have been initialized.
- * @returns `true` if options have been set, `false` otherwise.
- */
-export function areOptionsInitialized(): boolean {
-  return optionsInitialized;
+  allOptions = parsed as Readonly<Options>[];
 }

apps/oxlint/src/js_plugins/external_linter.rs

@@ -15,18 +15,20 @@ use oxc_linter::{
 
 use crate::{
     generated::raw_transfer_constants::{BLOCK_ALIGN, BUFFER_SIZE},
-    run::{JsLintFileCb, JsLoadPluginCb},
+    run::{JsLintFileCb, JsLoadPluginCb, JsSetupConfigsCb},
 };
 
 /// Wrap JS callbacks as normal Rust functions, and create [`ExternalLinter`].
 pub fn create_external_linter(
     load_plugin: JsLoadPluginCb,
+    setup_configs: JsSetupConfigsCb,
     lint_file: JsLintFileCb,
 ) -> ExternalLinter {
     let rust_load_plugin = wrap_load_plugin(load_plugin);
+    let rust_setup_configs = wrap_setup_configs(setup_configs);
     let rust_lint_file = wrap_lint_file(lint_file);
 
-    ExternalLinter::new(rust_load_plugin, rust_lint_file)
+    ExternalLinter::new(rust_load_plugin, rust_setup_configs, rust_lint_file)
 }
 
 /// Wrap `loadPlugin` JS callback as a normal Rust function.
@@ -59,6 +61,45 @@ pub enum LintFileReturnValue {
     Failure(String),
 }
 
+/// Wrap `setupConfigs` JS callback as a normal Rust function.
+///
+/// Use an `mpsc::channel` to wait for the result from JS side, and block current thread until `lintFile`
+/// completes execution.
+fn wrap_setup_configs(
+    cb: JsSetupConfigsCb,
+) -> Box<dyn Fn(String) -> Result<(), String> + Send + Sync> {
+    Box::new(move |options_json: String| {
+        let (tx, rx) = channel();
+
+        // Send data to JS
+        let status = cb.call_with_return_value(
+            FnArgs::from((options_json,)),
+            ThreadsafeFunctionCallMode::Blocking,
+            move |result, _env| {
+                let _ = match &result {
+                    Ok(r) => tx.send(Ok(r.clone())),
+                    Err(e) => tx.send(Err(e.to_string())),
+                };
+                result.map(|_| ())
+            },
+        );
+
+        assert!(status == Status::Ok, "Failed to schedule setupConfigs callback: {status:?}");
+
+        match rx.recv() {
+            Ok(Ok(result)) => {
+                if result == "ok" {
+                    Ok(())
+                } else {
+                    Err(result)
+                }
+            }
+            Ok(Err(err)) => Err(err),
+            Err(err) => panic!("setupConfigs callback did not respond: {err}"),
+        }
+    })
+}
+
 /// Wrap `lintFile` JS callback as a normal Rust function.
 ///
 /// The returned function creates a `Uint8Array` referencing the memory of the given `Allocator`,

apps/oxlint/src/lint.rs

@@ -291,6 +291,17 @@ impl CliRunner {
             }
         };
 
+        // TODO: refactor this elsewhere.
+        // This code is in the oxlint app, not in oxc_linter crate
+        if let Some(ref external_linter) = external_linter
+            && let Err(err) = external_plugin_store.setup_configs(external_linter) {
+                print_and_flush_stdout(
+                    stdout,
+                    &format!("Failed to setup external plugin options: {err}\n"),
+                );
+                return CliRunResult::InvalidOptionConfig;
+            }
+
         let report_unused_directives = match inline_config_options.report_unused_directives {
             ReportUnusedDirectives::WithoutSeverity(true) => Some(AllowWarnDeny::Warn),
             ReportUnusedDirectives::WithSeverity(Some(severity)) => Some(severity),

apps/oxlint/src/run.rs

@@ -53,25 +53,47 @@ pub type JsLintFileCb = ThreadsafeFunction<
     false,
 >;
 
+/// JS callback to setup configs.
+#[napi]
+pub type JsSetupConfigsCb = ThreadsafeFunction<
+    // Arguments
+    FnArgs<(String,)>, // Stringified options array
+    // Return value
+    String, // Result ("ok" or error message)
+    // Arguments (repeated)
+    FnArgs<(String,)>,
+    // Error status
+    Status,
+    // CalleeHandled
+    false,
+>;
+
 /// NAPI entry point.
 ///
 /// JS side passes in:
 /// 1. `args`: Command line arguments (process.argv.slice(2))
 /// 2. `load_plugin`: Load a JS plugin from a file path.
-/// 3. `lint_file`: Lint a file.
+/// 3. `setup_configs`: Setup configuration options.
+/// 4. `lint_file`: Lint a file.
 ///
 /// Returns `true` if linting succeeded without errors, `false` otherwise.
 #[expect(clippy::allow_attributes)]
 #[allow(clippy::trailing_empty_array, clippy::unused_async)] // https://github.com/napi-rs/napi-rs/issues/2758
 #[napi]
-pub async fn lint(args: Vec<String>, load_plugin: JsLoadPluginCb, lint_file: JsLintFileCb) -> bool {
-    lint_impl(args, load_plugin, lint_file).await.report() == ExitCode::SUCCESS
+pub async fn lint(
+    args: Vec<String>,
+    load_plugin: JsLoadPluginCb,
+    setup_configs: JsSetupConfigsCb,
+    lint_file: JsLintFileCb,
+) -> bool {
+    lint_impl(args, load_plugin, setup_configs, lint_file).await.report() == ExitCode::SUCCESS
 }
 
 /// Run the linter.
 async fn lint_impl(
     args: Vec<String>,
     load_plugin: JsLoadPluginCb,
+    setup_configs: JsSetupConfigsCb,
     lint_file: JsLintFileCb,
 ) -> CliRunResult {
     // Convert String args to OsString for compatibility with bpaf
@@ -105,10 +127,11 @@ async fn lint_impl(
 
     // JS plugins are only supported on 64-bit little-endian platforms at present
     #[cfg(all(target_pointer_width = "64", target_endian = "little"))]
-    let external_linter = Some(crate::js_plugins::create_external_linter(load_plugin, lint_file));
+    let external_linter =
+        Some(crate::js_plugins::create_external_linter(load_plugin, setup_configs, lint_file));
     #[cfg(not(all(target_pointer_width = "64", target_endian = "little")))]
     let external_linter = {
-        let (_, _) = (load_plugin, lint_file);
+        let (_, _, _) = (load_plugin, setup_configs, lint_file);
         None
     };
 

crates/oxc_linter/src/external_linter.rs

@@ -10,6 +10,8 @@ pub type ExternalLinterLoadPluginCb = Box<
         + Sync,
 >;
 
+pub type ExternalLinterSetupConfigsCb = Box<dyn Fn(String) -> Result<(), String> + Send + Sync>;
+
 pub type ExternalLinterLintFileCb = Box<
     dyn Fn(String, Vec<u32>, Vec<u32>, String, &Allocator) -> Result<Vec<LintFileResult>, String>
         + Sync
@@ -46,15 +48,17 @@ pub struct JsFix {
 
 pub struct ExternalLinter {
     pub(crate) load_plugin: ExternalLinterLoadPluginCb,
+    pub(crate) setup_configs: ExternalLinterSetupConfigsCb,
     pub(crate) lint_file: ExternalLinterLintFileCb,
 }
 
 impl ExternalLinter {
     pub fn new(
         load_plugin: ExternalLinterLoadPluginCb,
+        setup_configs: ExternalLinterSetupConfigsCb,
         lint_file: ExternalLinterLintFileCb,
     ) -> Self {
-        Self { load_plugin, lint_file }
+        Self { load_plugin, setup_configs, lint_file }
     }
 }