feat(linter/plugins): rule options #16215

lilnasy · 2025-11-27T20:57:59Z

Implements Linter plugins: Support options for JS rules #14825
Rebased feat(linter): Add support for options for jsPlugins #15822. Refactored. Pruned the slop. Tests passing.

Big changes from the original approach

Options IDs are stored in their own arrays. This was laid out in refactor(linter/plugins): prepare for rule options #16158. The original approach was to store ruleId-optionId pairs as tuples in an array - several heap allocated objects and excessive pointer indirection.
The rust code populates the options by calling a new JS callback named setupConfigs(). I expect we would use this callback for more plugin related data, including settings which are currently implemented in a hacky way.
Investigate a refactor to avoid requiring a mutable reference to ExternalPluginStore everywhere.

Smaller Changes

Removed the extra fixture ("working version"). There were no meaningful changes compared to the first fixture. Probably slop.

Copilot

Pull request overview

This PR implements rule options support for external JavaScript plugins in the linter. It introduces an ExternalOptionsId type to track and pass rule-specific configuration options from Rust to JavaScript plugins, allowing JS plugin rules to receive configuration parameters similar to ESLint rule options.

Key changes:

Added ExternalOptionsId type and options storage to ExternalPluginStore with index 0 reserved for "no options"
Updated external rule signatures from (ExternalRuleId, AllowWarnDeny) to (ExternalRuleId, ExternalOptionsId, AllowWarnDeny) throughout the codebase
Implemented options serialization/deserialization flow between Rust and JavaScript using OnceLock for thread-safe caching

Reviewed changes

Copilot reviewed 23 out of 24 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
`crates/oxc_linter/src/external_plugin_store.rs`	Added `ExternalOptionsId` type and options storage with index 0 reserved for empty/null options
`crates/oxc_linter/src/external_linter.rs`	Updated callback signature to include `options_ids` parameter
`crates/oxc_linter/src/lib.rs`	Updated external rule handling to pass options IDs to JS side
`crates/oxc_linter/src/config/rules.rs`	Modified `override_rules` to track options alongside severity; added comprehensive tests
`crates/oxc_linter/src/config/config_store.rs`	Updated rule storage and override logic to handle options IDs; added override precedence test
`crates/oxc_linter/src/config/config_builder.rs`	Updated builder to accept mutable reference to external plugin store for options registration
`crates/oxc_linter/src/config/mod.rs`	Updated test to use mutable external plugin store
`crates/oxc_linter/src/tester.rs`	Updated to pass mutable reference to external plugin store
`crates/oxc_language_server/src/linter/server_linter.rs`	Updated config building calls to use mutable external plugin store
`tasks/benchmark/benches/linter.rs`	Updated benchmark to use mutable external plugin store
`napi/playground/src/lib.rs`	Updated playground to properly share external plugin store between config building and linter creation
`apps/oxlint/src/run.rs`	Added `OnceLock`-based caching for serialized options JSON and export function for JS
`apps/oxlint/src/lint.rs`	Added serialization of external options after config building
`apps/oxlint/src/js_plugins/external_linter.rs`	Updated wrapper to forward options IDs to JS callback
`apps/oxlint/src-js/plugins/options.ts`	Added options initialization logic and storage
`apps/oxlint/src-js/plugins/load.ts`	Duplicated options initialization logic (should be removed)
`apps/oxlint/src-js/plugins/lint.ts`	Added lazy options initialization and options ID handling; duplicate `ruleIndex` assignment
`apps/oxlint/src-js/cli.ts`	Updated wrapper to forward options IDs parameter
`apps/oxlint/src-js/bindings.js`	Exported `getExternalRuleOptions` function
`apps/oxlint/src-js/bindings.d.ts`	Added TypeScript declaration for `getExternalRuleOptions`
`apps/oxlint/test/fixtures/custom_plugin_with_options/*`	Added integration test fixture for external plugin with options

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

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

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

Copilot · 2025-11-27T21:01:10Z

apps/oxlint/src/run.rs

+/// 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()


The documentation comment states "Returns a JSON string of options arrays" but the function returns Option<String>, which can be None. The comment should clarify when None is returned (e.g., "Returns a JSON string of options arrays, or None if options haven't been set yet").

codspeed-hq · 2025-11-27T21:04:40Z

CodSpeed Performance Report

Merging #16215 will not alter performance

_{Comparing lilnasy:js-plugin-options (42eee5d) with main (505ceb1)}

Summary

✅ 42 untouched
⏩ 3 skipped¹

3 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

overlookmotel · 2025-11-27T22:28:50Z

Just a note: As I mentioned on Discord, I don't think we should worry about merging options with default options in this first PR - can leave that to a follow-on. But FYI I've implemented the merging logic in #16217 because I needed it for the rule tester.

overlookmotel · 2025-11-28T13:58:41Z

Refactor to avoid requiring a mutable reference to ExternalPluginStore everywhere.

I know it was met that said this should be possible, but I could very well be wrong. If it's not possible, don't worry about it.

lilnasy · 2025-11-28T19:15:40Z

apps/oxlint/src/lint.rs

+        // TODO: refactor this elsewhere.
+        // This code is in the oxlint app, not in oxc_linter crate
+        if let Some(ref external_linter) = external_linter {
+            if 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;
+            }
+        }


I could use help here. I exposed setup_configs() for the oxlint crate by putting it on ExternalPluginStore only because it's the first place I found. I could do with a few pointers on separation of concerns regarding these structs.

Copilot

Pull request overview

Copilot reviewed 23 out of 24 changed files in this pull request and generated 2 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

apps/oxlint/src/js_plugins/external_linter.rs

Copilot · 2025-11-28T20:29:32Z

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

+ * 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 {


[nitpick] The comment states "Note: the name setupConfigs is currently incorrect, as we only populate rule options." While this is acknowledged as a TODO, consider renaming to setupOptions or setupRuleOptions to accurately reflect the current functionality. This would make the code clearer until multi-config workspace support is implemented.

Suggested change

* 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 {

* Populates Rust-resolved rule options on the JS side.

* Called from Rust side after all rule options have been resolved.

*

* The intention is for this function to eventually 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 setupOptions(optionsJSON: string): string {

lilnasy · 2025-11-28T20:47:13Z

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

+
+    // If the rule has no user-provided options, use the plugin-provided default
+    // options (which falls back to `DEFAULT_OPTIONS`)
    ruleDetails.options =
      optionsId === DEFAULT_OPTIONS_ID ? ruleDetails.defaultOptions : allOptions[optionsId];


@overlookmotel You mentioned this could be simplified to allOptions[optionsId]. How would plugin-provided default options get used in that case?

lilnasy · 2025-11-28T20:49:20Z

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

+      const el = parsed[i];
+      if (!isArray(el)) throw new TypeError("Each options entry must be an array", { cause: el });
+    }
+  }


This is a debug check because I this validation is done probably done on the rust side as well. I need to confirm this.

Copilot AI review requested due to automatic review settings November 27, 2025 20:58

lilnasy requested review from Sysix, camc314 and overlookmotel as code owners November 27, 2025 20:58

lilnasy marked this pull request as draft November 27, 2025 20:58

github-actions bot added A-linter Area - Linter A-cli Area - CLI A-editor Area - Editor and Language Server A-linter-plugins Area - Linter JS plugins C-enhancement Category - New feature or request labels Nov 27, 2025

Copilot started reviewing on behalf of lilnasy November 27, 2025 20:58 View session

Copilot finished reviewing on behalf of lilnasy November 27, 2025 21:00

Copilot AI reviewed Nov 27, 2025

View reviewed changes

lilnasy force-pushed the js-plugin-options branch 2 times, most recently from a7a3ca1 to 9c2d8a4 Compare November 27, 2025 21:11

lilnasy force-pushed the js-plugin-options branch 2 times, most recently from d62762c to 3c46139 Compare November 28, 2025 13:01

wagenet and others added 4 commits November 29, 2025 00:38

Add support for options for jsPlugins

4c19782

lint issues

a3f1ba5

delete set_external_options_json()

839d6af

delete getExternalRuleOptions()

26513bb

lilnasy force-pushed the js-plugin-options branch from 3c46139 to ae52e34 Compare November 28, 2025 19:08

lilnasy commented Nov 28, 2025

View reviewed changes

lilnasy force-pushed the js-plugin-options branch from ae52e34 to 3e53d55 Compare November 28, 2025 19:20

introduce setupConfigs()

1b4cd57

lilnasy force-pushed the js-plugin-options branch from dfb4439 to 1b4cd57 Compare November 28, 2025 19:21

createOnce() -> create()

a20747d

lilnasy added 3 commits November 29, 2025 01:33

refactor: init options using index_vec!

9701596

deep freeze the options array parsing

f56f662

comment: explain ruleDetails.options assignment

ad6d9fd

lilnasy marked this pull request as ready for review November 28, 2025 20:25

lilnasy requested a review from Copilot November 28, 2025 20:25

Copilot started reviewing on behalf of lilnasy November 28, 2025 20:26 View session

Copilot finished reviewing on behalf of lilnasy November 28, 2025 20:28

Copilot AI reviewed Nov 28, 2025

View reviewed changes

lilnasy added 3 commits November 29, 2025 02:10

update copy-pasted comment

88f5f37

simplify test

4e03bc9

remove unused method

42eee5d

lilnasy commented Nov 28, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

feat(linter/plugins): rule options #16215

feat(linter/plugins): rule options #16215

lilnasy commented Nov 27, 2025 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI Nov 27, 2025

Uh oh!

codspeed-hq bot commented Nov 27, 2025 •

edited

Loading

Uh oh!

overlookmotel commented Nov 27, 2025

Uh oh!

overlookmotel commented Nov 28, 2025

Uh oh!

lilnasy Nov 28, 2025

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Copilot AI Nov 28, 2025

Uh oh!

lilnasy Nov 28, 2025

Uh oh!

lilnasy Nov 28, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

feat(linter/plugins): rule options #16215

Are you sure you want to change the base?

feat(linter/plugins): rule options #16215

Conversation

lilnasy commented Nov 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Big changes from the original approach

Smaller Changes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Copilot AI Nov 27, 2025

Choose a reason for hiding this comment

Uh oh!

codspeed-hq bot commented Nov 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

CodSpeed Performance Report

Merging #16215 will not alter performance

Summary

Footnotes

Uh oh!

overlookmotel commented Nov 27, 2025

Uh oh!

overlookmotel commented Nov 28, 2025

Uh oh!

lilnasy Nov 28, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI Nov 28, 2025

Choose a reason for hiding this comment

Uh oh!

lilnasy Nov 28, 2025

Choose a reason for hiding this comment

Uh oh!

lilnasy Nov 28, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

lilnasy commented Nov 27, 2025 •

edited

Loading

codspeed-hq bot commented Nov 27, 2025 •

edited

Loading