Add support for options for jsPlugins

Author: wagenet

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

@@ -1,8 +1,14 @@
 /* auto-generated by NAPI-RS */
 /* eslint-disable */
+/**
+ * JS callable function to retrieve the serialized external rule options.
+ * Returns a JSON string of options arrays. Called once from JS after creating the external linter.
+ */
+export declare function getExternalRuleOptions(): string | null
+
 /** JS callback to lint a file. */
 export type JsLintFileCb =
-  ((arg0: string, arg1: number, arg2: Uint8Array | undefined | null, arg3: Array<number>, arg4: string) => string)
+  ((arg0: string, arg1: number, arg2: Uint8Array | undefined | null, arg3: Array<number>, arg4: Array<number>, arg5: string) => string)
 
 /** JS callback to load a JS plugin. */
 export type JsLoadPluginCb =

apps/oxlint/src-js/bindings.js

@@ -575,5 +575,6 @@ if (!nativeBinding) {
   throw new Error(`Failed to load native binding`)
 }
 
-const { lint } = nativeBinding
+const { getExternalRuleOptions, lint } = nativeBinding
+export { getExternalRuleOptions }
 export { lint }

apps/oxlint/src-js/cli.ts

@@ -38,6 +38,7 @@ function loadPluginWrapper(path: string, packageName: string | null): Promise<st
  * @param bufferId - ID of buffer containing file data
  * @param buffer - Buffer containing file data, or `null` if buffer with this ID was previously sent to JS
  * @param ruleIds - IDs of rules to run on this file
+ * @param optionsIds - IDs of options to use for rules on this file
  * @param settingsJSON - Settings for file, as JSON
  * @returns Diagnostics or error serialized to JSON string
  */
@@ -46,12 +47,13 @@ function lintFileWrapper(
   bufferId: number,
   buffer: Uint8Array | null,
   ruleIds: number[],
+  optionsIds: number[],
   settingsJSON: string,
 ): string {
   // `lintFileWrapper` is never called without `loadPluginWrapper` being called first,
   // so `lintFile` must be defined here
   debugAssertIsNonNull(lintFile);
-  return lintFile(filePath, bufferId, buffer, ruleIds, settingsJSON);
+  return lintFile(filePath, bufferId, buffer, ruleIds, optionsIds, settingsJSON);
 }
 
 // Get command line arguments, skipping first 2 (node binary and script path)

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

@@ -1,6 +1,6 @@
 import { setupFileContext, resetFileContext } from "./context.js";
 import { registeredRules } from "./load.js";
-import { allOptions, DEFAULT_OPTIONS_ID } from "./options.js";
+import { allOptions, areOptionsInitialized, DEFAULT_OPTIONS_ID, setOptions } from "./options.js";
 import { diagnostics } from "./report.js";
 import { setSettingsForFile, resetSettings } from "./settings.js";
 import { ast, initAst, resetSourceAndAst, setupSourceForFile } from "./source_code.js";
@@ -12,6 +12,7 @@ import {
   finalizeCompiledVisitor,
   initCompiledVisitor,
 } from "./visitor.js";
+import { getExternalRuleOptions } from "../bindings.js";
 
 // Lazy implementation
 /*
@@ -46,6 +47,7 @@ const PARSER_SERVICES_DEFAULT: Record<string, unknown> = Object.freeze({});
  * @param bufferId - ID of buffer containing file data
  * @param buffer - Buffer containing file data, or `null` if buffer with this ID was previously sent to JS
  * @param ruleIds - IDs of rules to run on this file
+ * @param optionsIds - IDs of options to use for rules on this file
  * @param settingsJSON - Settings for file, as JSON
  * @returns Diagnostics or error serialized to JSON string
  */
@@ -54,11 +56,9 @@ export function lintFile(
   bufferId: number,
   buffer: Uint8Array | null,
   ruleIds: number[],
+  optionsIds: number[],
   settingsJSON: string,
 ): string {
-  // TODO: Get `optionsIds` from Rust side
-  const optionsIds = ruleIds.map((_) => DEFAULT_OPTIONS_ID);
-
   try {
     lintFileImpl(filePath, bufferId, buffer, ruleIds, optionsIds, settingsJSON);
     return JSON.stringify({ Success: diagnostics });
@@ -145,6 +145,14 @@ function lintFileImpl(
     "Rule IDs and options IDs arrays must be the same length",
   );
 
+  // Initialize external rule options if not already initialized
+  if (!areOptionsInitialized()) {
+    const optionsJson = getExternalRuleOptions();
+    if (optionsJson !== null && optionsJson.length > 0) {
+      setOptions(optionsJson);
+    }
+  }
+
   for (let i = 0, len = ruleIds.length; i < len; i++) {
     const ruleId = ruleIds[i];
     debugAssert(ruleId < registeredRules.length, "Rule ID out of bounds");

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

@@ -12,8 +12,46 @@ export type Options = JsonValue[];
 // Default rule options
 export const DEFAULT_OPTIONS: Readonly<Options> = Object.freeze([]);
 
-// All rule options
-export const allOptions: Readonly<Options>[] = [DEFAULT_OPTIONS];
+// All rule options.
+// Indexed by options ID sent alongside ruleId for each file.
+// Element 0 is always the default options (empty array).
+export let allOptions: Readonly<Options>[] = [DEFAULT_OPTIONS];
 
 // Index into `allOptions` for default options
 export const DEFAULT_OPTIONS_ID = 0;
+
+// 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");
+    // 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");
+    }
+    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;
+}

apps/oxlint/src/js_plugins/external_linter.rs

@@ -72,6 +72,7 @@ fn wrap_lint_file(cb: JsLintFileCb) -> ExternalLinterLintFileCb {
     Box::new(
         move |file_path: String,
               rule_ids: Vec<u32>,
+              options_ids: Vec<u32>,
               settings_json: String,
               allocator: &Allocator| {
             let (tx, rx) = channel();
@@ -87,7 +88,7 @@ fn wrap_lint_file(cb: JsLintFileCb) -> ExternalLinterLintFileCb {
 
             // Send data to JS
             let status = cb.call_with_return_value(
-                FnArgs::from((file_path, buffer_id, buffer, rule_ids, settings_json)),
+                FnArgs::from((file_path, buffer_id, buffer, rule_ids, options_ids, settings_json)),
                 ThreadsafeFunctionCallMode::NonBlocking,
                 move |result, _env| {
                     let _ = match &result {

apps/oxlint/src/lint.rs

@@ -277,7 +277,7 @@ impl CliRunner {
             || nested_configs.values().any(|config| config.plugins().has_import());
         let mut options = LintServiceOptions::new(self.cwd).with_cross_module(use_cross_module);
 
-        let lint_config = match config_builder.build(&external_plugin_store) {
+        let lint_config = match config_builder.build(&mut external_plugin_store) {
             Ok(config) => config,
             Err(e) => {
                 print_and_flush_stdout(
@@ -329,6 +329,13 @@ impl CliRunner {
             return CliRunResult::None;
         }
 
+        // After building config, serialize external rule options for JS side.
+        #[cfg(all(feature = "napi", target_pointer_width = "64", target_endian = "little"))]
+        {
+            let store = config_store.external_plugin_store();
+            crate::set_external_options_json(store);
+        }
+
         let files_to_lint = paths
             .into_iter()
             .filter(|path| !ignore_matcher.should_ignore(Path::new(path)))

apps/oxlint/src/run.rs

@@ -16,6 +16,30 @@ use crate::{
     result::CliRunResult,
 };
 
+#[cfg(all(feature = "napi", target_pointer_width = "64", target_endian = "little"))]
+use oxc_linter::ExternalPluginStore;
+
+#[cfg(all(feature = "napi", target_pointer_width = "64", target_endian = "little"))]
+use std::sync::OnceLock;
+
+#[cfg(all(feature = "napi", target_pointer_width = "64", target_endian = "little"))]
+static EXTERNAL_OPTIONS_JSON: OnceLock<String> = OnceLock::new();
+
+/// Set serialized external rule options JSON after building configs.
+/// Called from Rust side (internal) before any linting, then consumed on first call to `lint`.
+#[cfg(all(feature = "napi", target_pointer_width = "64", target_endian = "little"))]
+pub fn set_external_options_json(plugin_store: &ExternalPluginStore) {
+    let _ = EXTERNAL_OPTIONS_JSON.set(plugin_store.serialize_all_options());
+}
+
+/// JS callable function to retrieve the serialized external rule options.
+/// Returns a JSON string of options arrays. Called once from JS after creating the external linter.
+#[cfg(all(feature = "napi", target_pointer_width = "64", target_endian = "little"))]
+#[napi]
+pub fn get_external_rule_options() -> Option<String> {
+    EXTERNAL_OPTIONS_JSON.get().cloned()
+}
+
 /// JS callback to load a JS plugin.
 #[napi]
 pub type JsLoadPluginCb = ThreadsafeFunction<
@@ -40,12 +64,13 @@ pub type JsLintFileCb = ThreadsafeFunction<
         u32,                // Buffer ID
         Option<Uint8Array>, // Buffer (optional)
         Vec<u32>,           // Array of rule IDs
+        Vec<u32>,           // Array of options IDs
         String,             // Stringified settings effective for the file
     )>,
     // Return value
     String, // `Vec<LintFileResult>`, serialized to JSON
     // Arguments (repeated)
-    FnArgs<(String, u32, Option<Uint8Array>, Vec<u32>, String)>,
+    FnArgs<(String, u32, Option<Uint8Array>, Vec<u32>, Vec<u32>, String)>,
     // Error status
     Status,
     // CalleeHandled

apps/oxlint/test/fixtures/custom_plugin_with_options/.oxlintrc.json

@@ -0,0 +1,10 @@
+{
+  "categories": {
+    "correctness": "off"
+  },
+  "jsPlugins": ["./plugin.ts"],
+  "rules": {
+    "test-plugin-options/check-options": ["error", true, { "expected": "production" }]
+  }
+}
+

apps/oxlint/test/fixtures/custom_plugin_with_options/files/index.js

@@ -0,0 +1,4 @@
+// Test file with debugger statement
+debugger;
+
+console.log("Hello, world!");